@north-light/crouter 0.3.259 → 0.3.260

package/dist/commands/pkg/plugin-inspect.js

@@ -106,7 +106,7 @@ export const pluginShow = defineLeaf({
             { name: 'enabled', type: 'boolean', required: true, constraint: 'Whether the plugin is active.' },
             { name: 'manifest', type: 'object', required: true, constraint: 'Full plugin.json contents.' },
             { name: 'docs', type: 'object[]', required: true, constraint: 'Each: {name, path}. Memory docs provided by the plugin (its `<pluginName>/` memory subtree).' },
-            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, mounts: string[] (accepted top-level command names), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
+            { name: 'commands', type: 'object', required: false, constraint: 'Present only when the plugin declares a command manifest (manifest.commands). {manifestPath: string, mounts: string[] (accepted top-level command names), extensibleBranches: string[] (mount names accepting repository fragments), issues: object[] ({code, path?, message, received, expected, next})}. Validated statically; command execution never occurs.' },
             { name: 'hooks', type: 'object', required: false, constraint: 'Present for every hook declaration, including hook-only plugins. {manifestPath?, executablePath?, declarations: {target, phase, op, description, effects}[], issues: object[] ({code, path?, message, received, expected, next}), trust: string}. Static only: no hook executable runs.' },
         ],
         outputKind: 'object',
@@ -146,6 +146,7 @@ export const pluginShow = defineLeaf({
             commands = {
                 manifestPath: v.manifestPath,
                 mounts: v.contributions.map((c) => c.node.name),
+                extensibleBranches: v.contributions.filter((c) => c.node.extensible === true).map((c) => c.node.name),
                 issues: v.issues,
             };
         }

package/dist/commands/sys/doctor.d.ts

@@ -1 +1,36 @@
+import { type Scope } from '../../types.js';
+type CheckStatus = 'pass' | 'fail';
+type CheckScope = Scope | 'canvas';
+/**
+ * Structured fix action for a failing check. Surfaced on each
+ * non-pass result so an agent reading doctor output can apply it directly
+ * when `--fix` is not used (or when --fix did not auto-apply). Every
+ * remediation includes the exact action and payload — no inference required.
+ */
+interface Remediation {
+    kind: 'remove_config_key' | 'rm_path' | 'human_action';
+    description: string;
+    scope?: Scope;
+    configKey?: string;
+    path?: string;
+    command?: string;
+}
+interface CheckResult {
+    scope: CheckScope;
+    name: string;
+    status: CheckStatus;
+    message: string;
+    fixed?: boolean;
+    remediation?: Remediation;
+}
+/**
+ * Validate the command manifest + executable path of every effective command
+ * plugin (the deduped, enabled set that actually composes into the tree).
+ * Purely static — the plugin binary is NEVER executed, and no remediation ever
+ * chmods or rewrites third-party plugin content (every fix is a human_action:
+ * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
+ * are reported, so `--scope` narrows these checks too.
+ */
+export declare function runCommandPluginChecks(scopes: Scope[]): Promise<CheckResult[]>;
 export declare const sysDoctorLeaf: import("../../core/command.js").LeafDef;
+export {};

package/dist/commands/sys/doctor.js

@@ -14,6 +14,9 @@ import { readFault } from '../../core/runtime/fault.js';
 import { detectNerdFont, nerdFontInstallCommand, NERD_FONT_SELECT_HINT } from '../../core/runtime/nerd-font.js';
 import { detectPackageManager } from './setup-core.js';
 import { validateEffectiveCommandPlugins } from '../../core/command-plugins/discovery.js';
+import { adaptPluginContributions } from '../../core/command-plugins/compose.js';
+import { resolveCommandRegistry } from '../../core/command-manifests/registry.js';
+import { applyCommandExtensions, orphanCommandExtensionValidations } from '../../core/command-plugins/extensions.js';
 import { discoverHookRegistry } from '../../core/command-hooks/discovery.js';
 import { resolveBinContributions } from '../../core/runtime/bin-contributions.js';
 import { inspectHumanActions } from '../../core/human-actions.js';
@@ -116,7 +119,7 @@ function faultRemediation(fault, nodeId) {
  * disable/update/remove the plugin). Only plugins whose scope is in `scopes`
  * are reported, so `--scope` narrows these checks too.
  */
-async function runCommandPluginChecks(scopes) {
+export async function runCommandPluginChecks(scopes) {
     const results = [];
     const inScope = new Set(scopes);
     const reserved = new Set(SUBTREE_NAMES);
@@ -124,7 +127,8 @@ async function runCommandPluginChecks(scopes) {
     // collisions surface here. A collision no longer costs anyone their command:
     // each claimant mounts under an origin-qualified name, so it is reported as a
     // healthy mount rather than a failure demanding the user remove a plugin.
-    for (const v of validateEffectiveCommandPlugins(reserved, undefined, undefined, await coreCommandPaths())) {
+    const validations = validateEffectiveCommandPlugins(reserved, undefined, undefined, await coreCommandPaths());
+    for (const v of validations) {
         const plugin = v.plugin;
         if (!inScope.has(plugin.scope))
             continue;
@@ -143,6 +147,22 @@ async function runCommandPluginChecks(scopes) {
             results.push(failCheck(plugin.scope, `plugin:${plugin.name}:commands[${i}]`, `${issue.code}${detail}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, remediation));
         });
     }
+    if (inScope.has('project')) {
+        const registry = resolveCommandRegistry(adaptPluginContributions(validations.flatMap((validation) => validation.contributions)).contributions, reserved);
+        const extensions = applyCommandExtensions(registry.contributions);
+        const allExtensionChecks = [...extensions.validations, ...orphanCommandExtensionValidations(registry.contributions)];
+        for (const extension of allExtensionChecks) {
+            if (extension.issue === undefined) {
+                results.push(pass('project', `extension:${extension.branch}`, `repository fragment valid: ${extension.fragmentPath}`));
+                continue;
+            }
+            const issue = extension.issue;
+            results.push(failCheck('project', `extension:${extension.branch}`, `${issue.code} at ${issue.path ?? extension.fragmentPath}: ${issue.message} (received ${issue.received}, expected ${issue.expected})`, {
+                kind: 'human_action',
+                description: issue.next,
+            }));
+        }
+    }
     return results;
 }
 /** Statically inspect the complete effective hook registry. This shares the

package/dist/core/__tests__/integration/command-plugins.test.js

@@ -29,7 +29,7 @@ import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { discoverCommandContributions, effectiveCommandPlugins, validatePluginCommands, } from '../../command-plugins/discovery.js';
+import { discoverCommandContributions, effectiveCommandPlugins, validatePluginCommands, buildExternalCommandSnapshot, } from '../../command-plugins/discovery.js';
 import { composeExternalSubtrees, adaptPluginContributions } from '../../command-plugins/compose.js';
 import { collectHelpAddenda } from '../../command-plugins/help-addenda.js';
 import { resolveCommandRegistry } from '../../command-manifests/registry.js';
@@ -38,9 +38,11 @@ import { renderRoot, renderBranch, renderLeafArgv } from '../../help.js';
 import { renderResult } from '../../render.js';
 import { CrtrError } from '../../errors.js';
 import { resetScopeCache } from '../../scope.js';
+import { createProfile } from '../../profiles/manifest.js';
 import { listInstalledPluginsInRoot } from '../../resolver.js';
 import { pluginShow } from '../../../commands/pkg/plugin-inspect.js';
-import { pluginDisable, pluginEnable, pluginInstall } from '../../../commands/pkg/plugin-manage.js';
+import { pluginDisable, pluginEnable, pluginInstall, pluginUpdate } from '../../../commands/pkg/plugin-manage.js';
+import { runCommandPluginChecks } from '../../../commands/sys/doctor.js';
 // The set of reserved core names discovery must fail closed against. We don't
 // import the real SUBTREE_NAMES (build-root.ts pulls the whole tree); a small
 // explicit set is enough for the collision contract and keeps the test cheap.
@@ -112,6 +114,45 @@ function commandsJson(topName = 'app') {
         ],
     };
 }
+function extensibleDemoCommandsJson(extensible = true) {
+    return {
+        schemaVersion: 1,
+        mounts: [{
+                parent: [],
+                node: {
+                    kind: 'branch',
+                    name: 'demo',
+                    description: 'fixture extensible branch',
+                    whenToUse: 'testing repository command contributions',
+                    ...(extensible ? { extensible: true } : {}),
+                    rootEntry: { concept: 'fixture command contributions', description: 'fixture extensible branch', whenToUse: 'testing repository command contributions' },
+                    summary: 'fixture extensible branch',
+                    children: [{ kind: 'branch', name: 'built-in', description: 'plugin-owned branch', whenToUse: 'using the plugin-owned command', summary: 'plugin-owned branch', children: [] }],
+                },
+            }],
+    };
+}
+function extensionFragment(rootName = 'repo-branch') {
+    return {
+        schemaVersion: 1,
+        transport: { kind: 'exec', executable: 'scripts/extension.js' },
+        mounts: [
+            { parent: [], node: { kind: 'branch', name: rootName, description: 'repository branch', whenToUse: 'using repository-defined commands', summary: 'repository branch', children: [] } },
+            { parent: [rootName], node: { kind: 'leaf', name: 'run', description: 'run repository operation', whenToUse: 'testing extension execution', summary: 'run repository operation', params: [{ kind: 'flag', name: 'thing', type: 'string', required: true, constraint: 'fixture input' }], output: [{ name: 'value', type: 'string', required: true, constraint: 'echoed fixture input' }], outputKind: 'object', effects: ['None. Read-only.'] } },
+        ],
+    };
+}
+const EXTENSION_EXEC = `#!/usr/bin/env node
+const fs = require('fs');
+let data = '';
+process.stdin.on('data', (chunk) => data += chunk);
+process.stdin.on('end', () => {
+  const request = JSON.parse(data);
+  if (process.env.EXTENSION_REQUEST_LOG) fs.writeFileSync(process.env.EXTENSION_REQUEST_LOG, JSON.stringify(request));
+  if (process.env.EXTENSION_SENTINEL) fs.writeFileSync(process.env.EXTENSION_SENTINEL, 'executed');
+  process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { value: request.input.thing } }));
+});
+`;
 function passthroughCommandsJson() {
     return {
         schemaVersion: 1,
@@ -210,6 +251,26 @@ after(() => {
     }
     resetScopeCache();
 });
+function installExtensionFixture(manifest = extensionFragment()) {
+    installPlugin(userRoot, 'extension-fixture', { manifest: extensibleDemoCommandsJson() });
+    const commandsDir = join(projectRoot, 'commands');
+    const scriptsDir = join(projectDir, 'scripts');
+    mkdirSync(commandsDir, { recursive: true });
+    mkdirSync(scriptsDir, { recursive: true });
+    const fragmentPath = join(commandsDir, 'demo.json');
+    const executable = join(scriptsDir, 'extension.js');
+    writeFileSync(fragmentPath, JSON.stringify(manifest));
+    writeFileSync(executable, EXTENSION_EXEC);
+    chmodSync(executable, 0o755);
+    return { fragmentPath, executable };
+}
+function extensionBranch(startDir = projectDir, name = 'demo') {
+    resetScopeCache();
+    const snapshot = buildExternalCommandSnapshot(RESERVED, startDir);
+    const branch = composeExternalSubtrees(snapshot).find((node) => node.name === name);
+    assert.ok(branch, `expected the extensible ${name} branch`);
+    return branch;
+}
 function leafOf(branch, name) {
     const c = branch.children.find((x) => x.name === name);
     assert.ok(c !== undefined && c.kind === 'leaf', `expected leaf ${name}`);
@@ -384,6 +445,260 @@ describe('end-to-end CLI invocation', () => {
         assert.equal(obj.status, 'running');
     });
 });
+// Extensible plugin command branches — repository fragments attach to a marked
+// top-level branch as one native forest and stay entirely inside the existing
+// parser/help/exec contract.
+describe('extensible plugin command branches', () => {
+    test('merges native help, executes with extension context, and mirrors JSON', async () => {
+        const { fragmentPath } = installExtensionFixture();
+        const branch = extensionBranch();
+        const help = renderBranch(branch.help);
+        assert.match(help, /<command name="demo"/);
+        assert.match(help, /<subcommand name="built-in"/);
+        assert.match(help, /<subcommand name="repo-branch"[^>]*subcommands="1"/);
+        assert.ok(help.indexOf('name="built-in"') < help.indexOf('name="repo-branch"'));
+        assert.equal((help.match(/<command name=/g) ?? []).length, 1);
+        const repoBranch = branch.children.find((child) => child.name === 'repo-branch');
+        assert.ok(repoBranch !== undefined && repoBranch.kind === 'branch');
+        const leaf = leafOf(repoBranch, 'run');
+        const leafHelp = renderLeafArgv(leaf.help);
+        assert.match(leafHelp, /^demo repo-branch run: run repository operation\./);
+        assert.match(leafHelp, /Input/);
+        assert.match(leafHelp, /Output \(fields carried in the rendered result\)/);
+        assert.match(leafHelp, /Effects/);
+        const requestLog = join(projectDir, 'extension-request.json');
+        process.env['EXTENSION_REQUEST_LOG'] = requestLog;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            assert.deepEqual(await leaf.run({ thing: 'x' }), { value: 'x' });
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_REQUEST_LOG'];
+        }
+        const request = JSON.parse(readFileSync(requestLog, 'utf8'));
+        assert.deepEqual(request.command, ['demo', 'repo-branch', 'run']);
+        assert.deepEqual(request.input, { thing: 'x' });
+        assert.deepEqual(request.context.extension, { branch: 'demo', root: projectDir });
+        assert.equal(request.context.plugin, undefined);
+        const root = defineRoot({ tagline: 'test', globals: [], subtrees: [branch] });
+        assert.match(renderRoot(root.help), /\[\+2 subcommands — `crtr demo -h`\]/);
+        assert.equal(existsSync(join(projectDir, 'EXECUTED')), false);
+        assert.ok(existsSync(fragmentPath));
+    });
+    test('uses a collision-qualified branch name for fragment discovery, doctor, and exec context', async () => {
+        installPlugin(userRoot, 'first', { manifest: extensibleDemoCommandsJson() });
+        installPlugin(userRoot, 'second', { manifest: extensibleDemoCommandsJson() });
+        const commandsDir = join(projectRoot, 'commands');
+        const scriptsDir = join(projectDir, 'scripts');
+        mkdirSync(commandsDir, { recursive: true });
+        mkdirSync(scriptsDir, { recursive: true });
+        writeFileSync(join(commandsDir, 'first:demo.json'), JSON.stringify(extensionFragment()));
+        writeFileSync(join(scriptsDir, 'extension.js'), EXTENSION_EXEC);
+        chmodSync(join(scriptsDir, 'extension.js'), 0o755);
+        const first = extensionBranch(projectDir, 'first:demo');
+        const second = extensionBranch(projectDir, 'second:demo');
+        assert.ok(first.children.some((child) => child.name === 'repo-branch'));
+        assert.ok(!second.children.some((child) => child.name === 'repo-branch'));
+        const repoBranch = first.children.find((child) => child.name === 'repo-branch');
+        assert.ok(repoBranch !== undefined && repoBranch.kind === 'branch');
+        const requestLog = join(projectDir, 'collision-extension-request.json');
+        process.env['EXTENSION_REQUEST_LOG'] = requestLog;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            assert.deepEqual(await leafOf(repoBranch, 'run').run({ thing: 'x' }), { value: 'x' });
+            const checks = await runCommandPluginChecks(['project']);
+            const extension = checks.find((check) => check.name === 'extension:first:demo');
+            assert.ok(extension, JSON.stringify(checks));
+            assert.equal(extension.status, 'pass');
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_REQUEST_LOG'];
+        }
+        const request = JSON.parse(readFileSync(requestLog, 'utf8'));
+        assert.deepEqual(request.command, ['first:demo', 'repo-branch', 'run']);
+        assert.deepEqual(request.context.extension, { branch: 'first:demo', root: projectDir });
+        assert.equal(request.context.plugin, undefined);
+    });
+    test('runs through the real CLI with native help and --json output', { timeout: 40000 }, () => {
+        installExtensionFixture();
+        const cli = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'dist', 'cli.js');
+        const run = (args) => execFileSync(process.execPath, [cli, ...args], {
+            cwd: projectDir,
+            env: { ...process.env, HOME: home, CRTR_FRONT_DOOR: '' },
+            encoding: 'utf8',
+        });
+        const branchHelp = run(['demo', '-h']);
+        assert.match(branchHelp, /<command name="demo"/);
+        assert.match(branchHelp, /<subcommand name="built-in"/);
+        assert.match(branchHelp, /<subcommand name="repo-branch"/);
+        assert.deepEqual(JSON.parse(run(['demo', 'repo-branch', 'run', '--thing', 'x', '--json'])), { value: 'x' });
+    });
+    test('discovers per invocation, scopes by cwd, and nearest root wins', () => {
+        const { fragmentPath } = installExtensionFixture();
+        assert.ok(renderBranch(extensionBranch().help).includes('repo-branch'));
+        writeFileSync(fragmentPath, JSON.stringify(extensionFragment('changed')));
+        assert.ok(renderBranch(extensionBranch().help).includes('name="changed"'));
+        rmSync(fragmentPath);
+        assert.ok(!renderBranch(extensionBranch().help).includes('repo-branch'));
+        writeFileSync(fragmentPath, JSON.stringify(extensionFragment('outer')));
+        const inner = join(projectDir, 'nested');
+        const innerScope = join(inner, '.crouter', 'commands');
+        mkdirSync(innerScope, { recursive: true });
+        mkdirSync(join(inner, 'scripts'), { recursive: true });
+        writeFileSync(join(inner, 'scripts', 'extension.js'), EXTENSION_EXEC);
+        chmodSync(join(inner, 'scripts', 'extension.js'), 0o755);
+        writeFileSync(join(innerScope, 'demo.json'), JSON.stringify(extensionFragment('inner')));
+        assert.ok(renderBranch(extensionBranch(inner).help).includes('name="inner"'));
+        assert.ok(!renderBranch(extensionBranch(inner).help).includes('name="outer"'));
+        assert.ok(!renderBranch(extensionBranch(emptyStart).help).includes('name="outer"'));
+    });
+    test('does not discover fragments from selected-profile projects outside the cwd chain', () => {
+        installPlugin(userRoot, 'extension-fixture', { manifest: extensibleDemoCommandsJson() });
+        const profileProject = mintDir('crtr-cmdplugin-profile-project-');
+        const fragmentDir = join(profileProject, '.crouter', 'commands');
+        const scriptDir = join(profileProject, 'scripts');
+        mkdirSync(fragmentDir, { recursive: true });
+        mkdirSync(scriptDir, { recursive: true });
+        writeFileSync(join(fragmentDir, 'demo.json'), JSON.stringify(extensionFragment()));
+        writeFileSync(join(scriptDir, 'extension.js'), EXTENSION_EXEC);
+        chmodSync(join(scriptDir, 'extension.js'), 0o755);
+        process.env['CRTR_PROFILE_ID'] = createProfile('extension-fragment-scope', [{ path: profileProject, memory: 'content' }]).profileId;
+        resetScopeCache();
+        assert.ok(!renderBranch(extensionBranch(emptyStart).help).includes('repo-branch'));
+    });
+    test('rejects absolute executable paths and identifies the offending fragment node', async () => {
+        const { fragmentPath, executable } = installExtensionFixture();
+        const fragment = extensionFragment();
+        fragment.transport.executable = executable;
+        writeFileSync(fragmentPath, JSON.stringify(fragment));
+        const help = renderBranch(extensionBranch().help);
+        assert.match(help, /<extension-issue/);
+        assert.ok(!help.includes('repo-branch'));
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const checks = await runCommandPluginChecks(['project']);
+            const check = checks.find((candidate) => candidate.name === 'extension:demo');
+            assert.ok(check, JSON.stringify(checks));
+            assert.equal(check.status, 'fail');
+            assert.match(check.message, new RegExp(`${fragmentPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:transport\\.executable`));
+        }
+        finally {
+            process.chdir(priorCwd);
+        }
+    });
+    test('rejects the complete fragment with scoped help notice and doctor remediation', async () => {
+        const { fragmentPath } = installExtensionFixture();
+        const bad = extensionFragment();
+        bad['unknown'] = true;
+        writeFileSync(fragmentPath, JSON.stringify(bad));
+        const help = renderBranch(extensionBranch().help);
+        assert.match(help, /name="built-in"/);
+        assert.ok(!help.includes('repo-branch'));
+        assert.match(help, new RegExp(`<extension-issue fragment="${fragmentPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"`));
+        assert.match(help, /unknown top-level keys/);
+        const sentinel = join(projectDir, 'extension-executed');
+        process.env['EXTENSION_SENTINEL'] = sentinel;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const checks = await runCommandPluginChecks(['project']);
+            const check = checks.find((candidate) => candidate.name === 'extension:demo');
+            assert.ok(check, JSON.stringify(checks));
+            assert.equal(check.status, 'fail');
+            assert.match(check.message, /command_extension_invalid/);
+            assert.match(check.message, new RegExp(fragmentPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+            assert.match(check.remediation.description, /regenerate/i);
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_SENTINEL'];
+        }
+        assert.equal(existsSync(sentinel), false);
+    });
+    test('requires the marker, rejects passthrough/rootEntry/conflicts, and leaves unmarked passthrough inert', async () => {
+        const { fragmentPath } = installExtensionFixture();
+        writeFileSync(join(userRoot, 'plugins', 'extension-fixture', 'commands.json'), JSON.stringify(extensibleDemoCommandsJson(false)));
+        assert.ok(!renderBranch(extensionBranch().help).includes('repo-branch'));
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const checks = await runCommandPluginChecks(['project']);
+            const orphan = checks.find((candidate) => candidate.name === 'extension:demo');
+            assert.ok(orphan, JSON.stringify(checks));
+            assert.equal(orphan.status, 'fail');
+            assert.match(orphan.message, /no effective plugin branch is extensible/);
+        }
+        finally {
+            process.chdir(priorCwd);
+        }
+        writeFileSync(join(userRoot, 'plugins', 'extension-fixture', 'commands.json'), JSON.stringify(extensibleDemoCommandsJson()));
+        const variants = [
+            ['passthrough', (fragment) => { fragment['mounts'][0]['node']['passthrough'] = { bin: 'x', installHint: 'x' }; }],
+            ['rootEntry', (fragment) => { fragment['mounts'][0]['node']['rootEntry'] = { concept: 'x', description: 'x', whenToUse: 'x' }; }],
+        ];
+        for (const [name, mutate] of variants) {
+            const fragment = extensionFragment();
+            mutate(fragment);
+            writeFileSync(fragmentPath, JSON.stringify(fragment));
+            const help = renderBranch(extensionBranch().help);
+            assert.match(help, /<extension-issue/);
+            assert.ok(!help.includes('repo-branch'), name);
+        }
+        writeFileSync(fragmentPath, JSON.stringify(extensionFragment('built-in')));
+        const conflictHelp = renderBranch(extensionBranch().help);
+        assert.match(conflictHelp, /<extension-issue/);
+        assert.match(conflictHelp, /conflicts with a child/);
+        installPlugin(userRoot, 'passthrough-fixture', { manifest: passthroughCommandsJson() });
+        writeFileSync(join(projectRoot, 'commands', 'capture.json'), JSON.stringify(extensionFragment()));
+        resetScopeCache();
+        const snapshot = buildExternalCommandSnapshot(RESERVED, projectDir);
+        const capture = composeExternalSubtrees(snapshot).find((branch) => branch.name === 'capture');
+        assert.ok(capture?.passthrough);
+        assert.equal(capture.children.length, 0);
+    });
+    test('install and update validate the marker but never inspect repository fragments', async () => {
+        const source = join(mintDir('crtr-extensible-source-'), 'fixture');
+        mkdirSync(join(source, '.crouter-plugin'), { recursive: true });
+        mkdirSync(join(source, 'bin'), { recursive: true });
+        const manifest = extensibleDemoCommandsJson();
+        manifest.mounts[0].node['name'] = 'install-demo';
+        const rootEntry = manifest.mounts[0].node['rootEntry'];
+        rootEntry['concept'] = 'install fixture';
+        writeFileSync(join(source, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: 'install-extension-fixture', version: '0.1.0', description: 'fixture', commands: 'commands.json', transport: { kind: 'exec', executable: 'bin/cmd.js' } }));
+        writeFileSync(join(source, 'commands.json'), JSON.stringify(manifest));
+        writeFileSync(join(source, 'bin', 'cmd.js'), EXTENSION_EXEC);
+        chmodSync(join(source, 'bin', 'cmd.js'), 0o755);
+        mkdirSync(join(projectRoot, 'commands'), { recursive: true });
+        writeFileSync(join(projectRoot, 'commands', 'install-demo.json'), JSON.stringify({ unknown: true }));
+        await pluginInstall.run({ installRef: source, scope: 'user' });
+        (manifest.mounts[0].node['children'][0]['extensible'] = true);
+        writeFileSync(join(source, 'commands.json'), JSON.stringify(manifest));
+        await assert.rejects(pluginUpdate.run({ name: 'install-extension-fixture' }), /extensible is valid only on a top-level branch mount/);
+    });
+    test('plugin inspection identifies extensible branches without executing the fragment executable', async () => {
+        const { executable } = installExtensionFixture();
+        const sentinel = join(projectDir, 'inspect-executed');
+        process.env['EXTENSION_SENTINEL'] = sentinel;
+        const priorCwd = process.cwd();
+        process.chdir(projectDir);
+        try {
+            const shown = await pluginShow.run({ name: 'extension-fixture' });
+            const commands = shown['commands'];
+            assert.deepEqual(commands.extensibleBranches, ['demo']);
+        }
+        finally {
+            process.chdir(priorCwd);
+            delete process.env['EXTENSION_SENTINEL'];
+        }
+        assert.equal(existsSync(sentinel), false);
+        assert.ok(existsSync(executable));
+    });
+});
 // 5. Lifecycle without restart (per-invocation discovery)
 describe('lifecycle without restart', () => {
     test('install → appears; disable → gone; edit → visible; remove → gone', () => {

package/dist/core/command-manifests/manifest.d.ts

@@ -1,10 +1,10 @@
-import type { DeclLeaf, TransportKind, DeclBranch, ManifestTimeouts, CommandManifestIssue } from './schema.js';
+import type { DeclLeaf, DeclNode, TransportKind, ManifestTimeouts, CommandManifestIssue } from './schema.js';
 export interface ValidatedCommandManifest {
     schemaVersion: 1;
     baseUrl?: string;
     timeouts?: ManifestTimeouts;
-    /** Top-level branches, each ready to mount at parent []. */
-    roots: DeclBranch<DeclLeaf>[];
+    /** Top-level plugin branches or repository-fragment nodes, ready to mount. */
+    roots: DeclNode<DeclLeaf>[];
     /** Core command path (space-joined, e.g. "cron add") → attributed addendum
      *  text appended beneath that core command's help. Append-only product
      *  guidance — a plugin can never alter core contract text. */
@@ -32,4 +32,6 @@ export declare function validateCommandManifest(raw: unknown, options: {
      *  and ingress report can never disagree. Omitted only on the tolerant
      *  compose path, where mounting ignores addenda entirely. */
     coreCommandPaths?: ReadonlySet<string>;
+    /** A repository fragment attaches roots below an existing extensible branch. */
+    extensionFragment?: boolean;
 }): CommandManifestValidation;

package/dist/core/command-manifests/manifest.js

@@ -33,17 +33,19 @@ export function validateCommandManifest(raw, options) {
     };
     // Top-level structure check
     if (!isRecord(raw)) {
-        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts, helpAddenda? }' : '{ schemaVersion, mounts, helpAddenda? }', 'Provide a valid JSON manifest object.');
+        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.extensionFragment === true ? '{ schemaVersion, transport, mounts }' : options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts, helpAddenda? }' : '{ schemaVersion, mounts, helpAddenda? }', 'Provide a valid JSON manifest object.');
         return { issues };
     }
     // Check for unknown top-level keys
     const topKeys = Object.keys(raw);
-    const allowedTopKeys = options.transport === 'http'
-        ? new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts', 'helpAddenda'])
-        : new Set(['schemaVersion', 'mounts', 'helpAddenda']);
+    const allowedTopKeys = options.extensionFragment === true
+        ? new Set(['schemaVersion', 'transport', 'mounts'])
+        : options.transport === 'http'
+            ? new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts', 'helpAddenda'])
+            : new Set(['schemaVersion', 'mounts', 'helpAddenda']);
     const unknownKeys = topKeys.filter((k) => !allowedTopKeys.has(k));
     if (unknownKeys.length > 0) {
-        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.transport === 'http' ? 'only: schemaVersion, baseUrl, timeouts, mounts, helpAddenda' : 'only: schemaVersion, mounts, helpAddenda', 'Remove the unknown keys.');
+        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.extensionFragment === true ? 'only: schemaVersion, transport, mounts' : options.transport === 'http' ? 'only: schemaVersion, baseUrl, timeouts, mounts, helpAddenda' : 'only: schemaVersion, mounts, helpAddenda', 'Remove the unknown keys.');
         return { issues };
     }
     // Validate schemaVersion
@@ -101,7 +103,7 @@ export function validateCommandManifest(raw, options) {
     // Validate and collect all mounts
     const validatedMounts = [];
     for (let i = 0; i < mounts.length; i++) {
-        const m = validateMount(mounts[i], i, options.transport, issue);
+        const m = validateMount(mounts[i], i, options.transport, issue, options.extensionFragment === true ? { topLevelRootEntry: 'forbidden', allowPassthrough: false, allowExtensible: false } : undefined);
         if (m === null)
             return { issues };
         validatedMounts.push(m);
@@ -179,7 +181,7 @@ function validateHelpAddenda(raw, coreCommandPaths, issue) {
     }
     return out;
 }
-function validateMount(raw, index, transport, issue) {
+function validateMount(raw, index, transport, issue, nodeOptions) {
     const path = `mounts[${index}]`;
     if (!isRecord(raw)) {
         issue('command_manifest_invalid', 'mount must be an object', typeName(raw), '{ parent, node }', 'Fix the mount.', path);
@@ -208,17 +210,10 @@ function validateMount(raw, index, transport, issue) {
     // Validate node
     const nodeRaw = raw['node'];
     const topLevel = parent.length === 0;
-    const node = validateCommandNode(nodeRaw, [`${path}.node`], topLevel, transport, issue);
+    const node = validateCommandNode(nodeRaw, [`${path}.node`], topLevel, transport, issue, nodeOptions);
     if (node === null)
         return null;
-    // Top-level mount must be a branch with rootEntry
-    if (topLevel && node.kind !== 'branch') {
-        issue('command_node_invalid', 'top-level mount node must be a branch', node.kind, 'a branch with a rootEntry', 'Wrap the command in a top-level branch.', `${path}.node.kind`);
-        return null;
-    }
-    // Ensure the node is properly typed (should only be DeclLeaf at this point)
-    const typedNode = node;
-    return { parent, node: typedNode };
+    return { parent, node };
 }
 // Forest materialization (order-independent)
 /**
@@ -236,19 +231,10 @@ function materializeForest(mounts, reservedCoreNames, issue) {
             return null;
         }
     }
-    // Build the forest: all top-level nodes with inline children, then attach nested mounts
-    const roots = topLevel.map((m) => ({
-        kind: 'branch',
-        name: m.node.name,
-        description: m.node.description,
-        whenToUse: m.node.whenToUse,
-        ...(m.node.tier !== undefined ? { tier: m.node.tier } : {}),
-        ...(m.node.rootEntry !== undefined ? { rootEntry: m.node.rootEntry } : {}),
-        summary: m.node.summary,
-        ...(m.node.model !== undefined ? { model: m.node.model } : {}),
-        ...(m.node.passthrough !== undefined ? { passthrough: m.node.passthrough } : {}),
-        children: [...m.node.children],
-    }));
+    // Build the forest: all top-level nodes with inline children, then attach nested mounts.
+    const roots = topLevel.map((m) => m.node.kind === 'branch'
+        ? { ...m.node, children: [...m.node.children] }
+        : { ...m.node });
     // Attach nested mounts
     for (const mount of nested) {
         const resolved = resolveAndAttachMount(roots, mount, issue);
@@ -270,8 +256,7 @@ function materializeForest(mounts, reservedCoreNames, issue) {
         return true;
     };
     for (const root of roots) {
-        const child = root;
-        if (!indexPaths(child, [root.name]))
+        if (!indexPaths(root, [root.name]))
             return null;
     }
     return roots;
@@ -287,6 +272,10 @@ function resolveAndAttachMount(roots, mount, issue) {
         issue('command_parent_invalid', `parent path starts with unknown branch`, first, 'a branch this manifest contributes', 'Fix the parent path or add the parent branch.', mount.parent.join('.'));
         return false;
     }
+    if (root.kind === 'leaf') {
+        issue('command_parent_invalid', 'parent path resolves to a leaf', first, 'a branch', 'Change the parent to point to a branch.', mount.parent.join('.'));
+        return false;
+    }
     let current = root;
     for (const token of rest) {
         const child = current.children.find((c) => c.name === token);

package/dist/core/command-manifests/registry.d.ts

@@ -1,5 +1,6 @@
 import type { LeafDef } from '../command.js';
 import type { DeclLeafBase, DeclBranch, CommandManifestIssue } from './schema.js';
+import type { ExtensionIssueNotice } from '../command-plugins/extensions.js';
 /** Reference to an external contributor (plugin or HTTP-transport plugin). */
 export type CommandContributorRef = {
     name: string;
@@ -27,6 +28,8 @@ export interface CommandContribution {
     /** Root name from the manifest, before collision qualification. */
     manifestName: string;
     adaptLeaf: LeafAdapter;
+    /** Present only on an extensible branch whose nearest repository fragment was rejected. */
+    extensionIssue?: ExtensionIssueNotice;
 }
 /** Per-contributor collision issue. */
 export interface ContributorIssue extends CommandManifestIssue {

package/dist/core/command-manifests/schema.d.ts

@@ -12,6 +12,8 @@ export interface DeclBranch<L = DeclLeafBase> {
     tier?: 'normal' | 'common' | 'important';
     /** Required on a top-level branch, forbidden on a nested one. */
     rootEntry?: DeclRootEntry;
+    /** Allows the nearest repository fragment to contribute children below this top-level branch. */
+    extensible?: true;
     summary: string;
     model?: string;
     /** Exec transport only: forward every argv token after this branch to an
@@ -78,8 +80,16 @@ export interface CommandManifestIssue {
     expected: string;
     next: string;
 }
-export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision' | 'command_help_addendum_invalid' | 'command_rest_invalid';
+export type CommandIssueCode = 'command_manifest_unreadable' | 'command_manifest_invalid' | 'command_schema_version' | 'command_path_unsafe' | 'command_not_executable' | 'command_parent_invalid' | 'command_node_invalid' | 'command_collision' | 'command_help_addendum_invalid' | 'command_rest_invalid' | 'command_extension_invalid';
 type IssueFn = (code: CommandIssueCode, message: string, received: string, expected: string, next: string, path?: string) => void;
 export type TransportKind = 'exec' | 'http';
-export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn): DeclBranch<DeclLeaf> | DeclLeaf | null;
+export interface CommandNodeValidationOptions {
+    /** Plugin roots need rootEntry; repository-fragment roots attach under an existing branch and forbid it. */
+    topLevelRootEntry?: 'required' | 'forbidden';
+    /** Repository fragments have no passthrough escape hatch. */
+    allowPassthrough?: boolean;
+    /** Only plugin manifests may mark their own top-level branch extensible. */
+    allowExtensible?: boolean;
+}
+export declare function validateCommandNode(raw: unknown, path: string[], topLevel: boolean, transport: TransportKind, issue: IssueFn, options?: CommandNodeValidationOptions): DeclBranch<DeclLeaf> | DeclLeaf | null;
 export {};