@north-light/crouter 0.3.317 → 0.3.319

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

@@ -1,1200 +0,0 @@
-// Contract-seam tests for the external command-plugin seam (Phase 1).
-// Run with: npm run test:integration
-//
-// All tests run against an ISOLATED home (HOME → a fresh temp dir, no ambient
-// user plugins) and pass an explicit no-`.crouter` startDir, so discovery is
-// deterministic and cannot pick up the developer's real machine state.
-//
-// Covers the spec's Tests items:
-//  1. Registry composition — a fixture top-level branch + leaf composes into
-//     real BranchDef/LeafDef whose root/branch/leaf help carries the plugin's
-//     representations, schema, effects, and stable order.
-//  2. Core collision — a fixture claiming a SUBTREE_NAMES name is skipped +
-//     recorded as a command_collision issue; plugin collisions keep both
-//     commands under origin-qualified names.
-//  3. Scope/shadowing — a project copy shadows a user copy of the same plugin
-//     name; a disabled project copy suppresses the user copy.
-//  4. Protocol integration (table-driven, one fixture executable) — request
-//     envelope contents, rendered success, --json mirror, stderr separation,
-//     recoverable error propagation, and every malformed case.
-//  5. Lifecycle without restart — install/disable/edit/remove all take effect
-//     on the next discovery call (per-invocation, no cache).
-//  6/7. Typed issues for path/exec-bit/schema/unknown-key violations and nested
-//     mount composition without executing the fixture binary.
-import { test, describe, before, after, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, chmodSync, existsSync, lstatSync, realpathSync } from 'node:fs';
-import { readFileSync } from 'node:fs';
-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, 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';
-import { defineRoot } from '../../command.js';
-import { renderRoot, renderBranch, renderLeafArgv } from '../../help.js';
-import { renderResult } from '../../render.js';
-import { CrtrError } from '../../errors.js';
-import { resetScopeCache } from '../../scope.js';
-import { readConfig, updateRawConfigAtomically, writeRawConfig } from '../../config.js';
-import { closeScopedStores } from '../../scoped-state/db.js';
-import { initializeFreshScopedStore } from '../../scoped-state/migrate.js';
-import { createProfile } from '../../profiles/manifest.js';
-import { listInstalledPluginsInRoot } from '../../resolver.js';
-import { pluginShow } from '../../../commands/pkg/plugin-inspect.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.
-const RESERVED = new Set(['push', 'node', 'canvas', 'sys', 'memory']);
-// Fixture executable: reads one JSON request on stdin, writes one envelope.
-// Behavior is selected by req.input.mode so one binary drives the whole table.
-const FIXTURE_EXEC = `#!/usr/bin/env node
-const fs = require('fs');
-let data = '';
-process.stdin.on('data', (c) => (data += c));
-process.stdin.on('end', () => {
-  const req = JSON.parse(data);
-  const log = process.env.FIXTURE_REQUEST_LOG;
-  if (log) fs.writeFileSync(log, JSON.stringify(req));
-  const mode = (req.input && req.input.mode) || 'ok';
-  const env = (o, code) => { process.stdout.write(JSON.stringify(o)); process.exit(code); };
-  if (mode === 'invalid-json') { process.stdout.write('this is not json'); process.exit(0); }
-  if (mode === 'extra-stdout') { process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { app_id: 'x' } }) + '\\nEXTRA JUNK'); process.exit(0); }
-  if (mode === 'oversize') { process.stdout.write('x'.repeat(11 * 1024 * 1024)); process.exit(0); }
-  if (mode === 'signal') { process.kill(process.pid, 'SIGKILL'); return; }
-  if (mode === 'error') return env({ protocolVersion: 1, ok: false, error: { code: 'authentication_required', message: 'No home session is available.', field: 'session', next: 'Log in, then retry.' } }, 1);
-  if (mode === 'reserved-code') return env({ protocolVersion: 1, ok: false, error: { code: 'internal', message: 'boom' } }, 1);
-  if (mode === 'missing-field') return env({ protocolVersion: 1, ok: true, result: { status: 'running' } }, 0);
-  if (mode === 'exit-mismatch') return env({ protocolVersion: 1, ok: true, result: { app_id: req.input.appId, status: 'running' } }, 3);
-  if (mode === 'diag') { process.stderr.write('a diagnostic line on stderr\\n'); return env({ protocolVersion: 1, ok: true, result: { app_id: req.input.appId, status: 'running' } }, 0); }
-  return env({ protocolVersion: 1, ok: true, result: { app_id: req.input.appId, status: 'running' } }, 0);
-});
-`;
-function commandsJson(topName = 'app') {
-    return {
-        schemaVersion: 1,
-        mounts: [
-            {
-                parent: [],
-                node: {
-                    kind: 'branch',
-                    name: topName,
-                    description: 'application lifecycle and inspection',
-                    whenToUse: 'you need to create, deploy, inspect, or remove an application',
-                    rootEntry: {
-                        concept: 'applications hosted by a crouter home',
-                        description: 'application lifecycle and inspection',
-                        whenToUse: 'you need to create, deploy, inspect, or remove an application',
-                    },
-                    summary: 'application lifecycle and inspection',
-                    model: 'Applications are product resources owned by the selected home.',
-                    children: [
-                        {
-                            kind: 'leaf',
-                            name: 'show',
-                            description: 'show one application',
-                            whenToUse: 'inspect a single application by id',
-                            tier: 'important',
-                            summary: 'show one application details',
-                            params: [
-                                { kind: 'positional', name: 'app-id', required: true, constraint: 'the application id' },
-                                { kind: 'flag', name: 'mode', type: 'string', required: false, constraint: 'fixture behavior selector' },
-                            ],
-                            output: [
-                                { name: 'app_id', type: 'string', required: true, constraint: 'the echoed application id' },
-                                { name: 'status', type: 'string', required: false, constraint: 'current application status' },
-                            ],
-                            outputKind: 'object',
-                            effects: ['None. Read-only.'],
-                        },
-                    ],
-                },
-            },
-        ],
-    };
-}
-function humanCommandsJson(parent = ['human'], name = 'pr') {
-    return {
-        schemaVersion: 1,
-        helpAddenda: { human: 'Pull request review commands are provided by this plugin.' },
-        mounts: [{
-                parent,
-                node: {
-                    kind: 'branch',
-                    name,
-                    description: 'pull request review',
-                    whenToUse: 'a person needs to review a pull request',
-                    summary: 'review a pull request with a person',
-                    children: [{
-                            kind: 'leaf',
-                            name: 'review',
-                            description: 'start pull request review',
-                            whenToUse: 'the pull request is ready for review',
-                            summary: 'start one pull request review',
-                            params: [{ kind: 'flag', name: 'app-id', type: 'string', required: true, constraint: 'fixture pull request id' }],
-                            output: [{ name: 'app_id', type: 'string', required: true, constraint: 'echoed fixture pull request id' }, { name: 'status', type: 'string', required: false, constraint: 'fixture status' }],
-                            outputKind: 'object',
-                            effects: ['None. Read-only.'],
-                        }],
-                },
-            }],
-    };
-}
-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(bin = 'capture') {
-    return {
-        schemaVersion: 1,
-        mounts: [{
-                parent: [],
-                node: {
-                    kind: 'branch',
-                    name: 'capture',
-                    description: 'browser automation',
-                    whenToUse: 'driving a browser through the Capture CLI',
-                    rootEntry: {
-                        concept: 'browser automation',
-                        description: 'browser automation through Capture',
-                        whenToUse: 'driving a browser through the Capture CLI',
-                    },
-                    summary: 'browser automation through Capture',
-                    passthrough: { bin, installHint: 'Install @crouton-kit/capture globally.' },
-                    children: [],
-                },
-            }],
-    };
-}
-/** Write a plugin into `scopeRoot/plugins/<name>/` with a command manifest +
- *  executable. `manifest` is the commands.json object (default fixture). */
-function installPlugin(scopeRoot, name, opts = {}) {
-    const root = join(scopeRoot, 'plugins', name);
-    mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
-    mkdirSync(join(root, 'bin'), { recursive: true });
-    const pointer = opts.commandsPointer ?? 'commands.json';
-    writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({
-        name,
-        version: '0.1.0',
-        description: 'fixture',
-        commands: pointer,
-        transport: { kind: 'exec', ...(opts.executable === null ? {} : { executable: opts.executable ?? 'bin/cmd.js' }) },
-    }));
-    writeFileSync(join(root, 'commands.json'), JSON.stringify(opts.manifest ?? commandsJson()));
-    const execPath = join(root, 'bin', 'cmd.js');
-    writeFileSync(execPath, opts.exec ?? FIXTURE_EXEC);
-    chmodSync(execPath, opts.execBit === false ? 0o644 : 0o755);
-    const config = {
-        ...(opts.enabled === false ? { enabled: false } : {}),
-        ...(opts.sourceMarketplace !== undefined ? { source_marketplace: opts.sourceMarketplace } : {}),
-    };
-    if (Object.keys(config).length > 0) {
-        if (scopeRoot === userRoot) {
-            updateRawConfigAtomically('user', (raw) => ({ ...raw, plugins: { ...raw.plugins, [name]: config } }));
-        }
-        else {
-            writeFileSync(join(scopeRoot, 'config.json'), JSON.stringify({ plugins: { [name]: config } }));
-        }
-    }
-    return root;
-}
-// Isolated home + workspace
-let home; // becomes HOME → user scope root = $HOME/.crouter
-let userRoot;
-let projectDir; // a workspace with its own .crouter (project scope)
-let projectRoot;
-let emptyStart; // a startDir with NO .crouter anywhere above it
-let realHome;
-let realProfile;
-before(() => {
-    realHome = process.env['HOME'];
-    realProfile = process.env['CRTR_PROFILE_ID'];
-    delete process.env['CRTR_PROFILE_ID'];
-});
-after(() => {
-    if (realHome !== undefined)
-        process.env['HOME'] = realHome;
-    else
-        delete process.env['HOME'];
-    if (realProfile !== undefined)
-        process.env['CRTR_PROFILE_ID'] = realProfile;
-});
-// Every temp dir any test mints, so cleanup removes them ALL (an
-// after(...[home, ...]) would only see the LAST test's set and leak the rest).
-const tempDirs = [];
-function mintDir(prefix) {
-    const d = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
-    tempDirs.push(d);
-    return d;
-}
-beforeEach(() => {
-    home = mintDir('crtr-cmdplugin-home-');
-    process.env['HOME'] = home;
-    userRoot = join(home, '.crouter');
-    initializeFreshScopedStore({ kind: 'user', root: userRoot });
-    mkdirSync(join(userRoot, 'plugins'), { recursive: true });
-    projectDir = mintDir('crtr-cmdplugin-proj-');
-    projectRoot = join(projectDir, '.crouter');
-    mkdirSync(join(projectRoot, 'plugins'), { recursive: true });
-    emptyStart = mintDir('crtr-cmdplugin-empty-');
-    resetScopeCache();
-});
-after(() => {
-    closeScopedStores();
-    for (const d of tempDirs) {
-        try {
-            rmSync(d, { recursive: true, force: true });
-        }
-        catch { /* ignore */ }
-    }
-    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}`);
-    return c;
-}
-// 1. Registry composition
-describe('registry composition', () => {
-    test('a fixture top-level branch composes with plugin-owned help, schema, effects, stable order', () => {
-        installPlugin(userRoot, 'deploy-tools');
-        resetScopeCache();
-        const snapshot = discoverCommandContributions(RESERVED, emptyStart);
-        // user scope is discovered from any startDir (it's not a project ancestor).
-        assert.equal(snapshot.issues.length, 0, JSON.stringify(snapshot.issues));
-        const registrySnapshot = adaptPluginContributions(snapshot.contributions);
-        const external = composeExternalSubtrees(registrySnapshot);
-        assert.equal(external.length, 1);
-        const app = external[0];
-        assert.equal(app.kind, 'branch');
-        assert.equal(app.name, 'app');
-        // Root help carries the plugin-owned rootEntry (mapped description→desc,
-        // whenToUse→useWhen), no core file knows what an app is.
-        const root = defineRoot({ tagline: 'test', globals: [], subtrees: external });
-        const rootOut = renderRoot(root.help);
-        assert.match(rootOut, /<command name="app">/);
-        assert.match(rootOut, /applications hosted by a crouter home/);
-        assert.match(rootOut, /use when you need to create, deploy, inspect, or remove an application/);
-        // important child promoted into root with its shortform desc.
-        assert.match(rootOut, /app show {2,}show one application/);
-        // Branch help lists the leaf via its own description/whenToUse.
-        const branchOut = renderBranch(app.help);
-        assert.match(branchOut, /<command name="app" description="application lifecycle and inspection">/);
-        assert.match(branchOut, /Applications are product resources owned by the selected home\./);
-        assert.match(branchOut, /name="show"[^>]*whenToUse="inspect a single application by id"/);
-        // Leaf help carries the full input/output schema + effects.
-        const leaf = leafOf(app, 'show');
-        const leafOut = renderLeafArgv(leaf.help);
-        assert.match(leafOut, /APP-ID/);
-        assert.match(leafOut, /--mode MODE/);
-        assert.match(leafOut, /app_id {2,}string\. the echoed application id/);
-        assert.match(leafOut, /None\. Read-only\./);
-    });
-});
-describe('extensible core mounts', () => {
-    test('a plugin mounts under human in real help and dispatch receives the full path', async () => {
-        installPlugin(userRoot, 'pr-review', { manifest: humanCommandsJson() });
-        resetScopeCache();
-        const { resolveRoot } = await import('../../../build-root.js');
-        const { runCli } = await import('../../command.js');
-        const root = await resolveRoot('human');
-        const chunks = [];
-        const realWrite = process.stdout.write.bind(process.stdout);
-        const realCwd = process.cwd();
-        const requestLog = join(emptyStart, 'human-mount-request.json');
-        process.env['FIXTURE_REQUEST_LOG'] = requestLog;
-        process.chdir(emptyStart);
-        process.stdout.write = ((chunk) => {
-            chunks.push(String(chunk));
-            return true;
-        });
-        try {
-            await runCli(root, ['node', 'crtr', 'human', '-h']);
-            await runCli(root, ['node', 'crtr', 'human', 'pr', 'review', '--app-id', '42', '--json']);
-        }
-        finally {
-            process.stdout.write = realWrite;
-            process.chdir(realCwd);
-            delete process.env['FIXTURE_REQUEST_LOG'];
-        }
-        assert.match(chunks.join(''), /name="pr"[^>]*plugin="pr-review"/);
-        assert.match(chunks.join(''), /<plugin-help plugin="pr-review">/);
-        assert.deepEqual(JSON.parse(readFileSync(requestLog, 'utf8')).command, ['human', 'pr', 'review']);
-    });
-    test('plugin installation accepts a human mount', async () => {
-        const source = join(mintDir('crtr-human-mount-source-'), 'fixture');
-        mkdirSync(join(source, '.crouter-plugin'), { recursive: true });
-        mkdirSync(join(source, 'bin'), { recursive: true });
-        writeFileSync(join(source, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name: 'human-mount-install', version: '0.1.0', description: 'fixture', commands: 'commands.json', transport: { kind: 'exec', executable: 'bin/cmd.js' } }));
-        writeFileSync(join(source, 'commands.json'), JSON.stringify(humanCommandsJson()));
-        writeFileSync(join(source, 'bin', 'cmd.js'), FIXTURE_EXEC);
-        chmodSync(join(source, 'bin', 'cmd.js'), 0o755);
-        await pluginInstall.run({ installRef: source, scope: 'user' });
-    });
-    test('only explicitly extensible core branches accept mounts and core children win collisions', () => {
-        const node = listInstalledPluginsInRoot('user', userRoot);
-        installPlugin(userRoot, 'wrong-parent', { manifest: humanCommandsJson(['node']) });
-        installPlugin(userRoot, 'core-child', { manifest: humanCommandsJson(['human'], 'send') });
-        resetScopeCache();
-        const plugins = listInstalledPluginsInRoot('user', userRoot);
-        const options = { reserved: new Set(['human', 'node']), paths: new Set(['human', 'human send']), extensible: new Set(['human']) };
-        const wrongParent = validatePluginCommands(plugins.find((plugin) => plugin.name === 'wrong-parent'), options.reserved, options.paths, options.extensible);
-        const coreChild = validatePluginCommands(plugins.find((plugin) => plugin.name === 'core-child'), options.reserved, options.paths, options.extensible);
-        assert.equal(wrongParent.contributions.length, 0);
-        assert.match(wrongParent.issues[0]?.next ?? '', /extensible core branches: human/);
-        assert.equal(coreChild.contributions.length, 0);
-        assert.match(coreChild.issues[0]?.message ?? '', /conflicts with a child the extensible core branch already owns/);
-        assert.equal(node.length, 0);
-    });
-});
-// 2. Core collision
-describe('core collision', () => {
-    test('a fixture claiming a core top-level name is skipped + recorded', () => {
-        installPlugin(userRoot, 'rogue', { manifest: commandsJson('push') });
-        resetScopeCache();
-        const candidates = discoverCommandContributions(new Set(), emptyStart);
-        const registrySnapshot = resolveCommandRegistry(adaptPluginContributions(candidates.contributions).contributions, RESERVED);
-        assert.equal(composeExternalSubtrees(registrySnapshot).length, 0, 'the colliding branch must not enter the tree');
-        const collision = registrySnapshot.issues.find((i) => i.code === 'command_collision');
-        assert.ok(collision, 'a command_collision issue must be recorded for doctor/show');
-        assert.equal(collision.path, 'push');
-        assert.equal(collision.contributor.name, 'rogue');
-    });
-});
-// 3. Scope / shadowing
-describe('scope shadowing', () => {
-    test('a project copy shadows a user copy of the same plugin name', () => {
-        installPlugin(userRoot, 'deploy-tools');
-        installPlugin(projectRoot, 'deploy-tools');
-        resetScopeCache();
-        const effective = effectiveCommandPlugins(projectDir);
-        assert.equal(effective.length, 1);
-        assert.equal(effective[0].scope, 'project');
-        assert.equal(effective[0].root, join(projectRoot, 'plugins', 'deploy-tools'));
-    });
-    test('a disabled project copy suppresses the user copy (no resurfacing)', () => {
-        installPlugin(userRoot, 'deploy-tools');
-        installPlugin(projectRoot, 'deploy-tools', { enabled: false });
-        resetScopeCache();
-        // sanity: the project copy really is disabled at that root.
-        const projPlugins = listInstalledPluginsInRoot('project', projectRoot);
-        assert.equal(projPlugins.find((p) => p.name === 'deploy-tools').enabled, false);
-        const effective = effectiveCommandPlugins(projectDir);
-        assert.equal(effective.length, 0, 'the disabled higher-precedence copy must suppress the user copy');
-    });
-});
-// 4. Protocol integration (table-driven)
-describe('protocol integration', () => {
-    function showLeaf() {
-        installPlugin(userRoot, 'deploy-tools');
-        resetScopeCache();
-        const snapshot = discoverCommandContributions(RESERVED, emptyStart);
-        const registrySnapshot = adaptPluginContributions(snapshot.contributions);
-        const app = composeExternalSubtrees(registrySnapshot)[0];
-        return leafOf(app, 'show');
-    }
-    test('request envelope carries command path, camelCase input, cwd, plugin context', async () => {
-        const leaf = showLeaf();
-        const log = join(emptyStart, 'req.json');
-        process.env['FIXTURE_REQUEST_LOG'] = log;
-        try {
-            await leaf.run({ appId: 'app_123', mode: 'ok' });
-            const req = JSON.parse(readFileSync(log, 'utf8'));
-            assert.equal(req.protocolVersion, 1);
-            assert.deepEqual(req.command, ['app', 'show']);
-            assert.equal(req.input.appId, 'app_123');
-            assert.equal(req.context.cwd, process.cwd());
-            assert.equal(req.context.plugin.name, 'deploy-tools');
-            assert.equal(req.context.plugin.scope, 'user');
-            assert.equal(req.context.plugin.version, '0.1.0');
-            assert.equal(req.context.plugin.root, join(userRoot, 'plugins', 'deploy-tools'));
-        }
-        finally {
-            delete process.env['FIXTURE_REQUEST_LOG'];
-        }
-    });
-    test('ok:true → result validated + rendered; --json mirrors the same object', async () => {
-        const leaf = showLeaf();
-        const result = await leaf.run({ appId: 'app_123', mode: 'ok' });
-        assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
-        // Rendered through the existing generic renderer (no custom renderer).
-        const rendered = renderResult(result, leaf.help);
-        assert.match(rendered, /app_id/);
-        assert.match(rendered, /app_123/);
-    });
-    test('valid envelope + wrong exit code is honored (soft diagnostic, not a discard)', async () => {
-        const leaf = showLeaf();
-        const result = await leaf.run({ appId: 'app_123', mode: 'exit-mismatch' });
-        assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
-    });
-    test('stderr diagnostics do not pollute the stdout envelope', async () => {
-        const leaf = showLeaf();
-        const result = await leaf.run({ appId: 'app_123', mode: 'diag' });
-        assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
-    });
-    test('ok:false → structured CrtrError with the plugin code', async () => {
-        const leaf = showLeaf();
-        await assert.rejects(() => leaf.run({ appId: 'app_123', mode: 'error' }), (e) => e instanceof CrtrError && e.code === 'authentication_required' && (e.details?.['next'] === 'Log in, then retry.'));
-    });
-    const malformed = [
-        ['invalid JSON', 'invalid-json'],
-        ['extra stdout after the envelope', 'extra-stdout'],
-        ['oversize stdout (>10 MiB)', 'oversize'],
-        ['signal termination', 'signal'],
-        ['missing declared output field', 'missing-field'],
-        ['reserved error code', 'reserved-code'],
-    ];
-    for (const [desc, mode] of malformed) {
-        test(`malformed: ${desc} → plugin_protocol_error`, async () => {
-            const leaf = showLeaf();
-            await assert.rejects(() => leaf.run({ appId: 'app_123', mode }), (e) => e instanceof CrtrError && e.code === 'plugin_protocol_error');
-        });
-    }
-});
-const CLI = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..', 'dist', 'cli.js');
-// 4b. True end-to-end CLI invocation (argv → parseArgv → adapter → renderer)
-describe('end-to-end CLI invocation', () => {
-    // dist/cli.js is up 4 from src/core/__tests__/integration/. Requires a prior
-    // `npm run build` (the harness/CI builds before tests). Drives the WHOLE seam: the
-    // declared positional `app-id` must arrive as `appId` in the request, and
-    // the rendered + --json outputs come through the real dispatcher.
-    const runCrtr = (args) => {
-        installPlugin(userRoot, 'deploy-tools');
-        resetScopeCache();
-        return execFileSync(process.execPath, [CLI, ...args], {
-            cwd: emptyStart,
-            env: { ...process.env, HOME: home, CRTR_FRONT_DOOR: '' },
-            encoding: 'utf8',
-        });
-    };
-    test('crtr app show <id> renders the plugin result end to end', { timeout: 40000 }, () => {
-        const out = runCrtr(['app', 'show', 'app_123']);
-        assert.match(out, /app_123/);
-        assert.match(out, /running/);
-    });
-    test('--json mirrors the same result object', { timeout: 40000 }, () => {
-        const out = runCrtr(['app', 'show', 'app_123', '--json']);
-        const obj = JSON.parse(out);
-        assert.equal(obj.app_id, 'app_123');
-        assert.equal(obj.status, 'running');
-    });
-});
-// Passthrough paths resolve inside their plugin during discovery. Bare names are
-// deliberately left for the invoking process's PATH.
-describe('passthrough binary resolution', () => {
-    function runPassthrough(args, env = process.env) {
-        return execFileSync(process.execPath, [CLI, ...args], {
-            cwd: emptyStart,
-            env: { ...env, HOME: home, CRTR_FRONT_DOOR: '' },
-            encoding: 'utf8',
-        });
-    }
-    test('a plugin-relative bin runs the plugin program', () => {
-        const root = installPlugin(userRoot, 'passthrough-fixture', { manifest: passthroughCommandsJson('bin/passthrough.js'), executable: null });
-        const program = join(root, 'bin', 'passthrough.js');
-        writeFileSync(program, '#!/bin/sh\nprintf "plugin program: %s\\n" "$*"\n');
-        chmodSync(program, 0o755);
-        const validation = validatePluginCommands(listInstalledPluginsInRoot('user', userRoot).find((plugin) => plugin.name === 'passthrough-fixture'), RESERVED);
-        assert.equal(validation.issues.length, 0, JSON.stringify(validation.issues));
-        assert.equal(validation.contributions[0].node.passthrough?.bin, realpathSync(program));
-        assert.equal(runPassthrough(['capture', 'one', '--two']).trim(), 'plugin program: one --two');
-    });
-    test('a bare bin runs the program from PATH', () => {
-        installPlugin(userRoot, 'passthrough-fixture', { manifest: passthroughCommandsJson('capture-fixture'), executable: null });
-        const pathDir = mintDir('crtr-cmdplugin-path-');
-        const program = join(pathDir, 'capture-fixture');
-        writeFileSync(program, '#!/bin/sh\nprintf "PATH program: %s\\n" "$*"\n');
-        chmodSync(program, 0o755);
-        const validation = validatePluginCommands(listInstalledPluginsInRoot('user', userRoot).find((plugin) => plugin.name === 'passthrough-fixture'), RESERVED);
-        assert.equal(validation.issues.length, 0, JSON.stringify(validation.issues));
-        assert.equal(validation.contributions[0].node.passthrough?.bin, 'capture-fixture');
-        assert.equal(runPassthrough(['capture', 'three'], { ...process.env, PATH: `${pathDir}:${process.env['PATH'] ?? ''}` }).trim(), 'PATH program: three');
-    });
-});
-// 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', () => {
-        const discover = () => {
-            resetScopeCache();
-            const snapshot = discoverCommandContributions(RESERVED, emptyStart);
-            return composeExternalSubtrees(adaptPluginContributions(snapshot.contributions));
-        };
-        // install
-        installPlugin(userRoot, 'deploy-tools');
-        assert.equal(discover().length, 1);
-        // disable (config edit only — no restart)
-        writeRawConfig('user', { plugins: { 'deploy-tools': { enabled: false } } });
-        assert.equal(discover().length, 0);
-        // re-enable + edit the declaration (rename the top-level command)
-        writeRawConfig('user', { plugins: { 'deploy-tools': { enabled: true } } });
-        writeFileSync(join(userRoot, 'plugins', 'deploy-tools', 'commands.json'), JSON.stringify(commandsJson('deploy')));
-        const afterEdit = discover();
-        assert.equal(afterEdit.length, 1);
-        assert.equal(afterEdit[0].name, 'deploy');
-        // remove
-        rmSync(join(userRoot, 'plugins', 'deploy-tools'), { recursive: true, force: true });
-        assert.equal(discover().length, 0);
-    });
-});
-// 6/7. Typed issues without executing the binary
-describe('typed validation issues', () => {
-    function validate(manifest, extra = {}) {
-        installPlugin(userRoot, 'p', { manifest, ...extra });
-        resetScopeCache();
-        const plugins = listInstalledPluginsInRoot('user', userRoot);
-        const p = plugins.find((x) => x.name === 'p');
-        return validatePluginCommands(p, RESERVED);
-    }
-    test('unknown schemaVersion → command_schema_version, no contribution', () => {
-        const m = commandsJson();
-        m['schemaVersion'] = 2;
-        const v = validate(m);
-        assert.equal(v.contributions.length, 0);
-        assert.ok(v.issues.some((i) => i.code === 'command_schema_version'));
-    });
-    test('unknown top-level key → command_manifest_invalid', () => {
-        const m = commandsJson();
-        m['requires'] = { crtr: '>=1' };
-        const v = validate(m);
-        assert.ok(v.issues.some((i) => i.code === 'command_manifest_invalid'));
-    });
-    test('a child mount declared before its non-empty parent materializes into the nested branch', () => {
-        const m = commandsJson();
-        const topLevel = m.mounts[0];
-        const child = topLevel.node['children'][0];
-        topLevel.node['children'] = [{
-                kind: 'branch',
-                name: 'tools',
-                description: 'application tools',
-                whenToUse: 'inspect application tools',
-                summary: 'application tools',
-                children: [],
-            }];
-        m.mounts = [
-            { parent: ['app', 'tools'], node: { ...child, name: 'status' } },
-            topLevel,
-        ];
-        const v = validate(m);
-        assert.equal(v.issues.length, 0, JSON.stringify(v.issues));
-        assert.equal(v.contributions.length, 1);
-        const tools = (v.contributions[0].node.children.find((node) => node.name === 'tools'));
-        assert.equal(tools.kind, 'branch');
-        assert.deepEqual(tools.children.map((node) => node.name), ['status']);
-    });
-    test('non-executable file → command_not_executable', () => {
-        const v = validate(commandsJson(), { execBit: false });
-        assert.ok(v.issues.some((i) => i.code === 'command_not_executable'));
-    });
-    test('exec transport omits executable only for a passthrough-only manifest', () => {
-        const passthrough = validate(passthroughCommandsJson(), { executable: null });
-        assert.equal(passthrough.issues.length, 0, JSON.stringify(passthrough.issues));
-        assert.equal(passthrough.contributions.length, 1);
-        assert.equal(passthrough.contributions[0].node.passthrough?.bin, 'capture');
-        assert.equal(composeExternalSubtrees(adaptPluginContributions(passthrough.contributions))[0].passthrough?.bin, 'capture');
-        const nestedPassthrough = passthroughCommandsJson();
-        nestedPassthrough.mounts.push({
-            parent: ['capture'],
-            node: { kind: 'branch', name: 'child', description: 'nested child', whenToUse: 'testing invalid composition', summary: 'nested child', children: [] },
-        });
-        const rejectedNestedMount = validate(nestedPassthrough, { executable: null });
-        assert.ok(rejectedNestedMount.issues.some((issue) => issue.code === 'command_parent_invalid' && /passthrough branch/.test(issue.message)));
-        const executableLeaf = validate(commandsJson(), { executable: null });
-        assert.equal(executableLeaf.contributions.length, 0);
-        assert.ok(executableLeaf.issues.some((i) => i.path === 'transport.executable' && /requires executable/.test(i.message)));
-    });
-    test('executable escaping the plugin root → command_path_unsafe', () => {
-        const v = validate(commandsJson(), { executable: '../../../../bin/sh' });
-        assert.ok(v.issues.some((i) => i.code === 'command_path_unsafe'));
-    });
-    test('passthrough path escaping the plugin root → command_path_unsafe', () => {
-        const v = validate(passthroughCommandsJson('../../../../bin/sh'), { executable: null });
-        assert.ok(v.issues.some((i) => i.code === 'command_path_unsafe'));
-    });
-    test('non-executable passthrough path → command_not_executable', () => {
-        const v = validate(passthroughCommandsJson('bin/cmd.js'), { executable: null, execBit: false });
-        assert.ok(v.issues.some((i) => i.code === 'command_not_executable'));
-    });
-    test('a top-level leaf (no rootEntry) → command_node_invalid', () => {
-        const m = {
-            schemaVersion: 1,
-            mounts: [{ parent: [], node: { kind: 'leaf', name: 'x', description: 'd', whenToUse: 'w', summary: 's', params: [], output: [], outputKind: 'object', effects: ['None. Read-only.'] } }],
-        };
-        const v = validate(m);
-        assert.ok(v.issues.some((i) => i.code === 'command_node_invalid'));
-        assert.equal(v.contributions.length, 0);
-    });
-    test('a valid manifest yields a contribution and zero issues', () => {
-        const v = validate(commandsJson());
-        assert.equal(v.issues.length, 0);
-        assert.equal(v.contributions.length, 1);
-        assert.equal(v.contributions[0].node.name, 'app');
-    });
-});
-// Plugin help addenda — the append-only product-guidance seam. An addendum
-// that quietly stops rendering is exactly the silent-absence class: pin that a
-// valid entry survives validation and is collected attributed, and that the
-// STRICT gates (install/bundle, which pass coreCommandPaths) reject a key
-// naming no core command path while the tolerant compose path still mounts the
-// plugin's tree. The help-render lookup receives the gate's exact inputs, so a
-// map rejected at ingress renders nothing — render never disagrees with the
-// install report.
-describe('plugin help addenda', () => {
-    const gate = (paths) => ({
-        reservedCoreNames: RESERVED,
-        coreCommandPaths: () => Promise.resolve(new Set(paths)),
-        extensibleCoreBranches: () => Promise.resolve(new Set(['human'])),
-    });
-    test('a helpAddenda entry survives validation and is collected attributed to its plugin', async () => {
-        const m = commandsJson();
-        m['helpAddenda'] = { cron: 'Gate on the device: exit 75 parks the occurrence.' };
-        installPlugin(userRoot, 'northlight-fixture', { manifest: m });
-        resetScopeCache();
-        const p = listInstalledPluginsInRoot('user', userRoot).find((x) => x.name === 'northlight-fixture');
-        const v = validatePluginCommands(p, RESERVED);
-        assert.equal(v.issues.length, 0, JSON.stringify(v.issues));
-        assert.deepEqual(v.manifest?.helpAddenda, { cron: 'Gate on the device: exit 75 parks the occurrence.' });
-        // The help-render lookup: attributed, and empty for an unaddended path.
-        assert.deepEqual(await collectHelpAddenda('cron', gate(['cron', 'node']), emptyStart), [
-            { plugin: 'northlight-fixture', text: 'Gate on the device: exit 75 parks the occurrence.' },
-        ]);
-        assert.deepEqual(await collectHelpAddenda('node', gate(['cron', 'node']), emptyStart), []);
-    });
-    test('a key naming no core command path fails the strict gate and renders nothing, even beside a valid key', async () => {
-        const m = commandsJson();
-        m['helpAddenda'] = {
-            cron: 'a valid target beside the typo',
-            'cronn add': 'a typo that must fail at install, never silently at render',
-        };
-        installPlugin(userRoot, 'p', { manifest: m });
-        resetScopeCache();
-        const p = listInstalledPluginsInRoot('user', userRoot).find((x) => x.name === 'p');
-        // Strict (install/bundle/doctor): the typo is a typed issue, zero contributions.
-        const strict = validatePluginCommands(p, RESERVED, new Set(['cron', 'cron add']));
-        assert.ok(strict.issues.some((i) => i.code === 'command_help_addendum_invalid'), JSON.stringify(strict.issues));
-        assert.equal(strict.contributions.length, 0);
-        assert.equal(strict.manifest, undefined);
-        // Tolerant (runtime compose): an already-installed plugin's typo'd addendum
-        // must not drop its whole command tree.
-        const tolerant = validatePluginCommands(p, RESERVED);
-        assert.equal(tolerant.issues.length, 0, JSON.stringify(tolerant.issues));
-        assert.equal(tolerant.contributions.length, 1);
-        // The render lookup reproduces the GATE verdict, not the compose one: the
-        // rejected map contributes nothing — including its valid key — so render
-        // can never show what the install report said was rejected.
-        assert.deepEqual(await collectHelpAddenda('cron', gate(['cron', 'cron add']), emptyStart), []);
-    });
-    test('an installed addendum renders through the real help path as an attributed block', async () => {
-        const m = commandsJson();
-        m['helpAddenda'] = { cron: 'ADDENDUM RENDERED THROUGH THE REAL HELP PATH' };
-        installPlugin(userRoot, 'northlight-fixture', { manifest: m });
-        resetScopeCache();
-        // Pin the durable wiring, not the lookup: runCli → renderNodeWithAddenda →
-        // collectHelpAddenda → <plugin-help> serialization. This is the exact
-        // silent-absence class — the dynamic import or the append could regress
-        // with every lookup-level assertion still green.
-        const { resolveRoot } = await import('../../../build-root.js');
-        const { runCli } = await import('../../command.js');
-        const root = await resolveRoot('cron');
-        const chunks = [];
-        const realWrite = process.stdout.write.bind(process.stdout);
-        const realCwd = process.cwd();
-        process.chdir(emptyStart); // startDir with no project scope — user scope is the fixture HOME
-        process.stdout.write = ((chunk) => {
-            chunks.push(String(chunk));
-            return true;
-        });
-        try {
-            await runCli(root, ['node', 'crtr', 'cron', '-h']);
-        }
-        finally {
-            process.stdout.write = realWrite;
-            process.chdir(realCwd);
-        }
-        const out = chunks.join('');
-        assert.ok(out.includes('<plugin-help plugin="northlight-fixture">'), out.slice(-400));
-        assert.ok(out.includes('ADDENDUM RENDERED THROUGH THE REAL HELP PATH'), out.slice(-400));
-    });
-});
-// Lifecycle surfaces — the validator's verdict must reach the caller WITHOUT
-// executing the plugin binary, and a cross-plugin top-level collision must
-// preserve every claimant under its origin-qualified command name.
-describe('lifecycle surfaces report validation without executing the plugin', () => {
-    // Records the fact it ran. No validation surface may ever spawn it.
-    const SENTINEL_EXEC = `#!/usr/bin/env node
-const fs = require('fs');
-if (process.env.CMDPLUGIN_SENTINEL) fs.writeFileSync(process.env.CMDPLUGIN_SENTINEL, 'executed');
-process.stdout.write(JSON.stringify({ protocolVersion: 1, ok: true, result: { app_id: 'x', status: 'running' } }));
-`;
-    let sentinel;
-    let realCwd;
-    beforeEach(() => {
-        realCwd = process.cwd();
-        sentinel = join(emptyStart, 'EXECUTED');
-        process.env['CMDPLUGIN_SENTINEL'] = sentinel;
-        process.chdir(emptyStart); // no .crouter ancestor → project scope is empty
-        resetScopeCache();
-    });
-    afterEach(() => {
-        process.chdir(realCwd);
-        delete process.env['CMDPLUGIN_SENTINEL'];
-        resetScopeCache();
-    });
-    function assertNotExecuted() {
-        assert.equal(existsSync(sentinel), false, 'a validation surface must never spawn the plugin binary');
-    }
-    test('pkg plugin show passes the typed issue through and mounts nothing', async () => {
-        const broken = commandsJson();
-        broken['schemaVersion'] = 2;
-        installPlugin(userRoot, 'p', { manifest: broken, exec: SENTINEL_EXEC });
-        resetScopeCache();
-        const out = await pluginShow.run({ name: 'p' });
-        const commands = out['commands'];
-        const issue = commands.issues.find((i) => i.code === 'command_schema_version');
-        assert.ok(issue, `expected command_schema_version, got ${JSON.stringify(commands.issues.map((i) => i.code))}`);
-        assert.ok(typeof issue.received === 'string' && typeof issue.expected === 'string' && typeof issue.next === 'string');
-        assert.equal(commands.mounts.length, 0, 'a rejected manifest contributes no mounts');
-        assertNotExecuted();
-    });
-    test('a cross-plugin top-level collision keeps both commands under their origin-qualified names', async () => {
-        // Two plugins, each valid in isolation, both claiming `app`. One is direct;
-        // the other records its marketplace as the command origin.
-        installPlugin(userRoot, 'p-one', { exec: SENTINEL_EXEC });
-        installPlugin(userRoot, 'p-two', { exec: SENTINEL_EXEC, sourceMarketplace: 'fixture-market' });
-        resetScopeCache();
-        const snapshot = discoverCommandContributions(new Set(['sys']), emptyStart);
-        assert.deepEqual(snapshot.contributions.map((contribution) => contribution.node.name).sort(), ['fixture-market:app', 'p-one:app']);
-        assert.deepEqual(snapshot.issues.filter((i) => i.code === 'command_collision').map((i) => i.plugin).sort(), ['p-one', 'p-two'], 'both claimants report their resolved mount');
-        for (const [name, mount] of [['p-one', 'p-one:app'], ['p-two', 'fixture-market:app']]) {
-            const out = await pluginShow.run({ name });
-            const commands = out['commands'];
-            assert.deepEqual(commands.mounts, [mount], `${name} lists its qualified command as an accepted mount`);
-            const issue = commands.issues.find((i) => i.code === 'command_collision');
-            assert.ok(issue, `${name} show must carry the command_collision issue`);
-            assert.deepEqual(issue.received.split(', ').sort(), ['p-one', 'p-two'], 'the issue names both claimants');
-            assert.match(issue.message, new RegExp(`mounted as "${mount}"`));
-            assert.equal(issue.expected, 'an origin-qualified top-level command for each claimant');
-            assert.equal(issue.next, `Invoke "${mount}" to use this plugin command.`);
-        }
-        assertNotExecuted();
-    });
-    test('a colliding exec plugin keeps its manifest path for help and execution', async () => {
-        installPlugin(userRoot, 'p-one', { exec: FIXTURE_EXEC });
-        installPlugin(userRoot, 'p-two', { exec: FIXTURE_EXEC, sourceMarketplace: 'fixture-market' });
-        resetScopeCache();
-        const snapshot = discoverCommandContributions(new Set(['sys']), emptyStart);
-        const external = composeExternalSubtrees(adaptPluginContributions(snapshot.contributions));
-        const mounted = external.find((branch) => branch.name === 'fixture-market:app');
-        assert.ok(mounted, 'the marketplace-qualified plugin branch is mounted');
-        assert.match(renderBranch(mounted.help), /<command name="fixture-market:app"/);
-        const leaf = leafOf(mounted, 'show');
-        const log = join(emptyStart, 'collision-request.json');
-        process.env['FIXTURE_REQUEST_LOG'] = log;
-        try {
-            const result = await leaf.run({ appId: 'app_123', mode: 'ok' });
-            assert.deepEqual(result, { app_id: 'app_123', status: 'running' });
-            assert.deepEqual(JSON.parse(readFileSync(log, 'utf8')).command, ['app', 'show']);
-        }
-        finally {
-            delete process.env['FIXTURE_REQUEST_LOG'];
-        }
-    });
-});
-// Memory-corpus gate across the plugin lifecycle — install, and enable of a
-// package installed while disabled, both converge the candidate's memory store
-// onto exact canonical identity BEFORE it can mount. A local-path install stays
-// a live link, so the caller's own directory is the corpus that gets rewritten;
-// a corpus that cannot converge writes nothing and changes no config. Update
-// runs the same gate through the same helper, so it needs no cases of its own.
-describe('memory corpus gate across the plugin lifecycle', () => {
-    let realCwd;
-    beforeEach(() => {
-        realCwd = process.cwd();
-        process.chdir(emptyStart); // no .crouter ancestor → the real repo is never a scope
-        resetScopeCache();
-    });
-    afterEach(() => {
-        process.chdir(realCwd);
-        resetScopeCache();
-    });
-    function writeDoc(path, frontmatter, body) {
-        mkdirSync(dirname(path), { recursive: true });
-        writeFileSync(path, `---\n${frontmatter}\nwhen-and-why-to-read: When the fixture runs, this knowledge should be read because it proves the gate.\n---\n\n${body}\n`);
-    }
-    function pluginSource(name) {
-        const root = join(mintDir('crtr-plugin-src-'), name);
-        mkdirSync(join(root, '.crouter-plugin'), { recursive: true });
-        writeFileSync(join(root, '.crouter-plugin', 'plugin.json'), JSON.stringify({ name, version: '0.1.0', description: 'fixture' }));
-        return root;
-    }
-    function userConfig() {
-        return readConfig('user');
-    }
-    test('a local install migrates the caller-owned linked corpus in place and reports it', async () => {
-        const source = pluginSource('memfix');
-        writeDoc(join(source, 'memory', 'topics', 'INDEX.md'), 'kind: knowledge\nname: topics/INDEX', 'Topic overview.');
-        writeDoc(join(source, 'memory', 'overview.md'), 'kind: knowledge', 'Depth lives in [[memfix/topics/INDEX]].');
-        // Non-document files the substrate never loads as documents: the count
-        // below must not include them even though lint YAML-checks them too.
-        writeDoc(join(source, 'memory', 'SKILL.md'), 'kind: knowledge\nname: unrelated-skill', 'Skill body.');
-        writeDoc(join(source, 'memory', 'MEMORY.md'), 'kind: knowledge', 'Index body.');
-        resetScopeCache();
-        const out = await pluginInstall.run({ installRef: source, scope: 'user' });
-        const memory = out['memory'];
-        assert.deepEqual(memory.migrated, ['overview.md', 'topics/INDEX.md'], 'both phases rewrote a document');
-        assert.equal(memory.linkedSource, realpathSync(join(source, 'memory')), 'the report names the caller-owned directory it rewrote');
-        assert.equal(memory.docs, 2);
-        assert.equal(lstatSync(join(userRoot, 'plugins', 'memfix')).isSymbolicLink(), true, 'the install stays a live link');
-        // The rewrite landed in the caller's source, not in a copy.
-        assert.match(readFileSync(join(source, 'memory', 'overview.md'), 'utf8'), /\[\[memfix\/topics\]\]/);
-        assert.doesNotMatch(readFileSync(join(source, 'memory', 'topics', 'INDEX.md'), 'utf8'), /^name:/m);
-        assert.equal(userConfig().plugins['memfix']?.enabled, true);
-    });
-    test('a corpus that cannot converge blocks the install, writes nothing, and registers nothing', async () => {
-        const source = pluginSource('blocked');
-        writeDoc(join(source, 'memory', 'dup-a.md'), 'kind: knowledge\nname: dup', 'First claimant.');
-        writeDoc(join(source, 'memory', 'dup-b.md'), 'kind: knowledge\nname: dup', 'Second claimant.');
-        const before = ['dup-a.md', 'dup-b.md'].map((f) => readFileSync(join(source, 'memory', f), 'utf8'));
-        resetScopeCache();
-        await assert.rejects(pluginInstall.run({ installRef: source, scope: 'user' }), (error) => /cannot be migrated to exact canonical identity/.test(error.message) && /dup/.test(error.message));
-        assert.equal(existsSync(join(userRoot, 'plugins', 'blocked')), false, 'a blocked candidate installs nothing');
-        assert.equal(userConfig().plugins['blocked'], undefined, 'config is unchanged');
-        assert.deepEqual(['dup-a.md', 'dup-b.md'].map((f) => readFileSync(join(source, 'memory', f), 'utf8')), before, 'a blocked plan writes nothing');
-    });
-    test('enable migrates a package installed while disabled before it flips config', async () => {
-        const source = pluginSource('lifecycle');
-        writeDoc(join(source, 'memory', 'ready.md'), 'kind: knowledge', 'Already canonical.');
-        resetScopeCache();
-        await pluginInstall.run({ installRef: source, scope: 'user' });
-        resetScopeCache();
-        await pluginDisable.run({ name: 'lifecycle' });
-        resetScopeCache();
-        // The package gains an old-format document while it sits disabled.
-        writeDoc(join(source, 'memory', 'guide', 'INDEX.md'), 'kind: knowledge\nname: guide/INDEX', 'Guide.');
-        const enabled = await pluginEnable.run({ name: 'lifecycle' });
-        const memory = enabled['memory'];
-        assert.deepEqual(memory.migrated, ['guide/INDEX.md']);
-        assert.equal(memory.linkedSource, realpathSync(join(source, 'memory')));
-        assert.doesNotMatch(readFileSync(join(source, 'memory', 'guide', 'INDEX.md'), 'utf8'), /^name:/m);
-        assert.equal(userConfig().plugins['lifecycle']?.enabled, true);
-        resetScopeCache();
-        await pluginDisable.run({ name: 'lifecycle' });
-        resetScopeCache();
-        writeDoc(join(source, 'memory', 'dup-a.md'), 'kind: knowledge\nname: dup', 'First claimant.');
-        writeDoc(join(source, 'memory', 'dup-b.md'), 'kind: knowledge\nname: dup', 'Second claimant.');
-        await assert.rejects(pluginEnable.run({ name: 'lifecycle' }), /cannot be migrated to exact canonical identity/);
-        assert.equal(userConfig().plugins['lifecycle']?.enabled, false, 'a refused corpus leaves the plugin disabled');
-    });
-});