@crouton-kit/crouter 0.3.78 → 0.3.80

package/dist/build-root.d.ts

@@ -9,8 +9,16 @@ export declare const SUBTREE_NAMES: string[];
  *  every valid child). This keeps every help/error surface byte-identical while
  *  the common leaf-dispatch path loads exactly one subtree. */
 export declare function resolveRoot(first: string | undefined): Promise<RootDef>;
-/** Assemble the full crtr command tree (all subtrees). Used for root -h, the
- *  unknown-path error, bare-root boot, and the listing-completeness test. Root
- *  owns only the tagline; every subtree declares its own root representation via
- *  its rootEntry. */
+/** Assemble the full crtr command tree: every core subtree plus any top-level
+ *  branches contributed by enabled command plugins. Used for root -h, the
+ *  unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by name (from discovery). Discovery is
+ *  invocation-local — no cache, no persistence — so plugin enable/update/remove
+ *  takes effect on the next invocation automatically. */
 export declare function buildRoot(): Promise<RootDef>;

package/dist/build-root.js

@@ -36,11 +36,30 @@ export async function resolveRoot(first) {
     }
     return buildRoot();
 }
-/** Assemble the full crtr command tree (all subtrees). Used for root -h, the
- *  unknown-path error, bare-root boot, and the listing-completeness test. Root
- *  owns only the tagline; every subtree declares its own root representation via
- *  its rootEntry. */
+/** Assemble the full crtr command tree: every core subtree plus any top-level
+ *  branches contributed by enabled command plugins. Used for root -h, the
+ *  unknown-path error, bare-root boot, front-door recognition, and the
+ *  listing-completeness test — i.e. only the FALLTHROUGH path, never the core
+ *  fast path (`resolveRoot` short-circuits a recognized core first token with
+ *  zero plugin I/O). Root owns only the tagline; every subtree (core or
+ *  external) declares its own root representation via its rootEntry.
+ *
+ *  Order is deterministic: core subtrees in declared order first, then accepted
+ *  external branches sorted by name (from discovery). Discovery is
+ *  invocation-local — no cache, no persistence — so plugin enable/update/remove
+ *  takes effect on the next invocation automatically. */
 export async function buildRoot() {
-    const subtrees = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
-    return defineRoot({ tagline: TAGLINE, globals: [], subtrees });
+    const core = await Promise.all(SUBTREE_NAMES.map((n) => SUBTREE_LOADERS[n]()));
+    // Dynamic import keeps command-plugin discovery/compose (and their
+    // resolver/manifest deps) OFF the hot leaf path's module graph — they load
+    // only here, on the fallthrough, matching this file's lazy-subtree rationale.
+    const [{ discoverCommandContributions }, { composeExternalSubtrees }] = await Promise.all([
+        import('./core/command-plugins/discovery.js'),
+        import('./core/command-plugins/compose.js'),
+    ]);
+    // Core always wins: a plugin claiming a core top-level name is skipped +
+    // recorded as an issue (surfaced via pkg plugin show / sys doctor).
+    const snapshot = discoverCommandContributions(new Set(SUBTREE_NAMES));
+    const external = composeExternalSubtrees(snapshot);
+    return defineRoot({ tagline: TAGLINE, globals: [], subtrees: [...core, ...external] });
 }

package/dist/builtin-memory/crouter-development/plugins.md

@@ -1,10 +1,12 @@
 ---
 kind: knowledge
 when-and-why-to-read: When creating a crtr plugin, packaging memory docs for
-  distribution, or debugging install/resolution, this knowledge should be read.
+  distribution, adding top-level CLI commands via a command manifest, or
+  debugging install/resolution, this knowledge should be read.
 short-form: How to author a crtr plugin — plugin.json manifest, directory
-  layout, scopes, install mechanics, versioning. Use when creating a new plugin,
-  packaging memory docs for distribution, or debugging install/resolution.
+  layout, scopes, install mechanics, versioning, and command plugins (top-level
+  CLI commands via commands.json + one executable). Use when creating a plugin,
+  packaging memory docs, contributing commands, or debugging install/resolution.
 system-prompt-visibility: name
 file-read-visibility: none
 ---
@@ -39,7 +41,7 @@ If it's a one-off note for yourself, scope-owned memory docs are simpler. Promot
         └── <name>.md
 ```
 
-The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Sibling dirs (`rules/`, `agents/`, and future `commands/`, `hooks/`) hold the other artifact types.
+The `<plugin-name>` directory IS the plugin. The manifest's `name` field must match the directory name (install renames if needed). Sibling dirs (`rules/`, `agents/`, and future `hooks/`) hold the other artifact types. A plugin that contributes CLI commands adds a `commands.json` manifest plus its executable — see [Command plugins](#command-plugins).
 
 ## The manifest
 
@@ -65,6 +67,7 @@ The `<plugin-name>` directory IS the plugin. The manifest's `name` field must ma
 | `description` | yes | One sentence. |
 | `source` | recommended | Git URL where the plugin lives. Used by `crtr pkg plugin update --name <name>`. |
 | `owner` | optional | Author info. |
+| `commands` | optional | Plugin-root-relative path to a `commands.json` command manifest. Present ⇒ the plugin contributes top-level `crtr` commands — see [Command plugins](#command-plugins). |
 
 ## Scopes
 
@@ -150,13 +153,87 @@ Bad plugin scope:
 
 If your memory doc conceptually depends on another plugin's doc, link via `## Related` with `` `<plugin>/<doc>` ``. Don't fork content; link it.
 
+## Command plugins
+
+Beyond docs, a plugin may contribute **top-level `crtr` commands** — new noun branches with their own leaves. You declare one pointer in the manifest and ship one executable; crtr owns parsing, help, rendering, and errors, and direct-spawns your executable once per leaf invocation.
+
+### The manifest pointer
+
+Add `commands` to `plugin.json` — a plugin-root-relative path to one static manifest:
+
+```json
+{ "name": "crouter-infra", "version": "0.1.0", "description": "...", "commands": "commands.json" }
+```
+
+Only an installed, **enabled** plugin's `commands` manifest contributes. Discovery is per-invocation: enable/disable/update/remove takes effect on the very next `crtr` call — no daemon restart, no cache to clear.
+
+### commands.json shape
+
+```json
+{
+  "schemaVersion": 1,
+  "executable": "bin/cmd.js",
+  "mounts": [
+    { "parent": [], "node": { "kind": "branch", "name": "app", "...": "..." } }
+  ]
+}
+```
+
+- `schemaVersion` — exactly the integer `1`. Anything else rejects the whole manifest.
+- `executable` — plugin-root-relative path to the one command binary. Must resolve inside the plugin root, be a regular file, and carry the POSIX exec bit.
+- `mounts[]` — each `{ parent: [], node }`. v1 supports **top-level mounts only**: `parent` must be `[]`.
+
+Every top-level `node` is a **branch** (`kind: "branch"`) carrying a `rootEntry { concept, description, whenToUse }` — the representation crtr renders at root help. Branch children are nested branches (no rootEntry) or leaves. A leaf declares `params`, `output` (array of `{ name, type, required, constraint }`), `outputKind: "object"`, and a non-empty `effects` array. Params use crtr's public vocabulary — one positional max, long-form `flag`s (types `string|int|bool|path|enum`, `choices` for enum), `stdin`, `context-file`; kebab-case names, no aliases. The declaration mirrors crtr's stable help descriptors, not its internal TypeScript defs — no closures, no dynamic state, no renderers.
+
+### Execution: the trust boundary
+
+On explicit leaf invocation — **never on install, help, or discovery** — crtr direct-spawns your executable (no shell) with `--crtr-command-protocol 1`, the caller's cwd, and the full environment. Installed command plugins are **trusted local code running with the caller's authority**: crtr does not sandbox them, filter the environment, mint a credential, or interpret your backend's auth. Your executable owns authentication to its own backend. This is an execution trust boundary, not a sandbox — installed code can already read the caller's files, so env filtering would only imply a security guarantee that does not exist.
+
+### The protocol
+
+crtr writes exactly one JSON request to your executable's stdin:
+
+```json
+{
+  "protocolVersion": 1,
+  "command": ["app", "show"],
+  "input": { "appId": "app_123" },
+  "context": { "cwd": "/caller/cwd", "plugin": { "name": "crouter-infra", "version": "0.1.0", "scope": "project", "root": "/plugin/root" } }
+}
+```
+
+`input` keys are the parser's camelCase form; a declared `stdin` param arrives as an `input` string, not a second stream. Your executable writes exactly one JSON envelope to stdout and nothing else — diagnostics go to stderr:
+
+```json
+{ "protocolVersion": 1, "ok": true, "result": { "app_id": "app_123" } }
+{ "protocolVersion": 1, "ok": false, "error": { "code": "authentication_required", "message": "...", "field": "session", "next": "..." } }
+```
+
+`ok` is the source of truth (a valid envelope is honored regardless of exit code). crtr validates `result` against your declared `output` (top-level field presence + type) and renders it; `--json` mirrors the same object. An error envelope becomes a normal crtr error with your `code` — lowercase snake_case, never crtr-reserved `internal`, `unknown_path`, `command_collision`, or `plugin_protocol_error`. No envelope at all (invalid JSON, empty, extra stdout, output over 10 MiB, signal kill) becomes `plugin_protocol_error`.
+
+### Two rules that prevent silent breakage
+
+- **Generate `commands.json` from your command definitions — never hand-write it.** The manifest must stay in lockstep with the executable's actual command surface; a hand-maintained copy drifts, and a drifted param or output field surfaces as a validation issue or a `plugin_protocol_error` at invocation. Emit it from the same source your executable dispatches on.
+- **A required output field must be non-null.** The adapter treats an explicit `null` for a declared-required field as *absent* → `plugin_protocol_error`. If a value is genuinely optional, declare it `required: false`; if it's required, always return a real value.
+
+### Validating your command manifest
+
+crtr validates command manifests **statically — it never executes your binary** to check them:
+
+- `crtr pkg plugin show <name>` — inventories the manifest path, executable, accepted top-level command names, and every current validation issue (each with received/expected/next).
+- `crtr sys doctor` — validates the manifest + executable path for every effective command plugin and reports structured remediation (disable/update/remove). `--fix` never chmods or rewrites plugin content.
+- `crtr pkg plugin install` / `update` — report the accepted top-level commands and any issues in their result.
+
+A fixed manifest goes live on the next invocation; there is nothing to restart.
+
 ## Validation
 
 `crtr sys doctor` checks each plugin's manifest:
 - Manifest exists and is valid JSON.
 - Manifest `name` matches the directory name.
+- When the plugin declares `commands`, its command manifest + executable path are validated statically (never executed) — see [Command plugins](#command-plugins).
 
-`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Sibling artifact dirs (`rules/`, `agents/`, `commands/`, `hooks/`) are validated by their respective specs as those land.
+`crtr memory lint` checks the docs under `memory/`: frontmatter parses, valid `kind`, both visibility rungs set. Run `crtr memory write -h` for the authoring + routing guide. Other sibling artifact dirs (`rules/`, `agents/`, `hooks/`) are validated by their respective specs as those land.
 
 ## Cross-publishing with Claude Code