Search by

waaseyaa / bimaaji

jonesrussell

Bimaaji — application graph introspection and agent-safe mutation for Waaseyaa

Package info

github.com/waaseyaa/bimaaji

pkg:composer/waaseyaa/bimaaji

Security

Advisories: 0

Aikido package health analysis

Transparency log

Statistics

Installs: 7 375

Dependents: 2

Suggesters: 0

Stars: 0

Open Issues: 0

v0.1.0-alpha.300 2026-09-02 15:49 UTC

Requires

Requires (Dev)

Suggests

  • waaseyaa/cli: Enables the graph:dump and bimaaji:install command integrations.

Provides

None

Conflicts

None

Replaces

None

GPL-2.0-or-later fa4b69537a78fa678a01e14a8761794880822f0c

Published on Packagist.org on 2026-09-02 16:13 UTC

This package is auto-updated.

Last update: 2026-09-02 16:13:59 UTC

README

Bimaaji is a Waaseyaa package providing application graph introspection and an agent-safe mutation protocol. The name (Anishinaabemowin: "to give life to") reflects its role: making a booted Waaseyaa application's structure visible and actionable to AI agents.

What it does

Bimaaji exposes two surfaces:

  1. Read-only introspection. Six GraphSectionProvider implementations (admin, entities, jsonapi, public_surface, routing, sovereignty) emit versioned GraphSection payloads that, taken together, describe what an application contains: registered entity types and their fields, every registered route plus access classification, the JSON:API surface, admin entity groupings, the current sovereignty profile, and the public-surface map.
  2. Validated mutation. A MutationRequest → MutationValidator → PatchSet pipeline lets an agent propose changes (e.g., "add field X to entity Y"). The validator gates every request through SovereigntyGuardrails; the patch generator emits content-hashed, reviewable file patches. Bimaaji itself never writes to disk — patches are returned for human (or upstream agent) review.

Quick start

After installing waaseyaa/framework (which depends on this package), the framework's PackageManifestCompiler auto-discovers BimaajiServiceProvider. The application graph generator is then reachable from the container:

use Waaseyaa\Bimaaji\Graph\ApplicationGraphGenerator;

$graph = $container->get(ApplicationGraphGenerator::class)->generate();
foreach ($graph->sections as $key => $section) {
    echo "{$key}: " . count($section->data) . " entries\n";
}

The six default section providers are pre-wired:

Provider Section key Constructor deps
AdminIntrospectionProvider admin EntityTypeManagerInterface
EntityIntrospectionProvider entities EntityTypeManagerInterface
JsonApiIntrospectionProvider jsonapi RouteCollection
PublicSurfaceProvider public_surface RouteCollection
RoutingIntrospectionProvider routing RouteCollection
SovereigntyIntrospectionProvider sovereignty SovereigntyProfile

Filesystem-backed spec indexing is disabled by default. Applications that intentionally expose spec search to an authenticated bimaaji.read principal must configure a non-empty bimaaji.specs_directory; Bimaaji never guesses a project-root docs/specs path for a remotely callable tool.

SovereigntyProfile is derived from SovereigntyConfigInterface::getProfile() and falls back to SovereigntyProfile::Local when no config is bound. RouteCollection is looked up directly and falls back to WaaseyaaRouter::getRouteCollection().

Extending: third-party graph sections

A consuming package can contribute its own section by implementing GraphSectionProviderInterface and binding it in its own ServiceProvider::register(). The canonical tag is BimaajiServiceProvider::SECTION_PROVIDER_TAG (bimaaji.section_provider); tag your binding under it for forward-compatibility with future tagged-collection container support.

final class FooSectionProvider implements GraphSectionProviderInterface
{
    public function getKey(): string { return 'foo'; }
    public function provide(): GraphSection { /* ... */ }
}

Installing guidelines / skills (bin/waaseyaa bimaaji:install)

Ship the framework-canonical agent skill pack to a consumer project in per-client formats. Lifted in spirit from Laravel Boost's php artisan boost:install; framework-native, no Node runtime.

The skills are resources of this package — resources/skills/<id>/SKILL.md — so the command reads the same directory whether it runs from the framework monorepo or from a consumer's vendor/waaseyaa/bimaaji. Nothing is read from the consuming project. An application with its own skill set points bimaaji.skills_directory at it.

# Install for one client
bin/waaseyaa bimaaji:install --client=claude

# Install for several (comma-separated or repeated)
bin/waaseyaa bimaaji:install --client=claude,cursor --force

# Preview without writing
bin/waaseyaa bimaaji:install --client=cursor --dry-run

# Interactive client selection when omitted on a TTY
bin/waaseyaa bimaaji:install

Every generated file frames its payload in <!-- waaseyaa:bimaaji:install BEGIN --> / END markers. A re-run replaces only the text between them, so notes you write above or below the block survive upgrades. A target file that carries no markers is treated as wholly hand-authored and still needs --force (or an interactive confirmation) before it is replaced.

The command records what it generated in .waaseyaa/bimaaji-install.json (commit it) and prunes targets a later skill set no longer produces. Ownership is recorded, never inferred from a filename: a path the manifest does not claim is never touched, a retired target you have since edited is neutralised rather than deleted, and supporting files you add inside a generated skill directory survive.

For Claude Code the output is .claude/skills/waaseyaa-<id>/SKILL.md — one directory per skill, which is the only layout Claude Code discovers.

Seven launch clients: claude, cursor, codex, copilot, gemini, windsurf, junie. See docs/specs/bimaaji-install.md for the per-client target paths, flag semantics, interactive UX, exit codes, sandbox guarantees, and the five-step extension guide for adding new clients.

Status

Bimaaji is now exposed over MCP via packages/mcp/'s per-request bridge architecture as of 2026-05-23 (M3 bimaaji-mcp-bridge-01KS5VS8). Five #[AsAgentTool] adapters live in packages/ai-agent/src/Tool/Bimaaji/ and surface automatically through the AgentToolRegistryBridge with no per-tool MCP code. See docs/specs/mcp-endpoint.md § "Bimaaji MCP bridge" for the transport contract and packages/mcp/README.md for the operator-facing summary.

The 2026-05-20 "PHP-only" deferral that closed #1463 was formally superseded by M3; the issue stays closed with a supersession comment linking to the M3 PR set.

Legacy MCP-server cleanup (pre-M3 consumers)

Projects (e.g., Minoo) that previously wired the deleted Node-based bimaaji MCP server (vendor/waaseyaa/bimaaji/mcp/server.js, removed in #1387/#1464) should:

  1. Remove any mcpServers.bimaaji entry pointing at the deleted server.js from .claude/settings.json. The replacement is the framework-native /mcp HTTP endpoint shipped by waaseyaa/mcp.
  2. Drop composer bimaaji-mcp-install from post-install hooks or contributor docs — the script body was Minoo-local and has no upstream entry point.
  3. Wire the new HTTP /mcp endpoint instead. See packages/mcp/README.md for the claude_desktop_config.json example fragment.

Where to read more