@north-light/crouter 0.3.165 → 0.3.167

package/dist/commands/node-context.js

@@ -1,8 +1,9 @@
 // `crtr node inspect context` — browse this node's context and reports dirs and those of
 // every node it subscribes to, in one read-only nvim file explorer.
 //
-// crtr makes a STRONG CLAIM that nvim is installed (see crouter/CLAUDE.md): the
-// file explorer + file viewer are nvim, not a hand-rolled view-contract surface.
+// crtr makes a STRONG CLAIM that nvim is installed (see
+// .crouter/memory/INDEX.md): the file explorer + file viewer are nvim, not a
+// hand-rolled view-contract surface.
 // We synthesize a temp dir of LABELLED NODE DIRS — `self` first, then one per
 // subscription — and place `context` / `reports` symlinks inside each label dir
 // for the node's existing on-disk dirs. We then open `nvim -R` on the temp tree

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

@@ -110,6 +110,28 @@ function commandsJson(topName = 'app') {
         ],
     };
 }
+function passthroughCommandsJson() {
+    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: 'capture', 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 = {}) {
@@ -122,7 +144,7 @@ function installPlugin(scopeRoot, name, opts = {}) {
         version: '0.1.0',
         description: 'fixture',
         commands: pointer,
-        transport: { kind: 'exec', executable: opts.executable ?? 'bin/cmd.js' },
+        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');
@@ -446,6 +468,23 @@ describe('typed validation issues', () => {
         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'));

package/dist/core/__tests__/history-inbox.test.js

@@ -6,11 +6,12 @@
 // sender (`from`) is visible in both the read body and the artifact title.
 import { test, before, after, beforeEach } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { createNode } from '../canvas/canvas.js';
 import { closeDb } from '../canvas/db.js';
+import { contextDir } from '../canvas/paths.js';
 import { appendInbox } from '../feed/inbox.js';
 import { buildCorpus, resolveRef } from '../canvas/history.js';
 let home;
@@ -39,6 +40,15 @@ after(() => {
     rmSync(home, { recursive: true, force: true });
     delete process.env['CRTR_HOME'];
 });
+test('history corpus skips malformed frontmatter in another cwd', () => {
+    const broken = createNode(node('broken-frontmatter', '/tmp/hist-broken'));
+    const valid = createNode(node('valid-history', '/tmp/hist-valid'));
+    writeFileSync(join(contextDir(broken.node_id), 'copied-source.md'), '---\ndesc: "unterminated\n---\nsource text\n');
+    writeFileSync(join(contextDir(valid.node_id), 'result.md'), '---\ntitle: result\n---\n0a0afd613\n');
+    const corpus = buildCorpus({ allCwds: true }, { types: ['report', 'doc', 'roadmap'] });
+    assert.equal(corpus.some((a) => a.ref === `${broken.node_id}:context/copied-source.md`), false, 'invalid artifact is skipped');
+    assert.ok(corpus.some((a) => a.loadBody().includes('0a0afd613')), 'valid artifacts remain searchable');
+});
 test('default history excludes inbox; --type inbox includes it, with full sender-attributed bodies', () => {
     const cwd = '/tmp/hist-work';
     createNode(node('sender-1', cwd));

package/dist/core/__tests__/self-update.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/__tests__/self-update.test.js

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+const SELF_UPDATE = join(ROOT, 'scripts', 'self-update.mjs');
+test('self-update installs the downloaded release without replacing the stable global shim', () => {
+    const directory = mkdtempSync(join(tmpdir(), 'crtr-self-update-test-'));
+    try {
+        const release = join(directory, 'release');
+        const archive = join(directory, 'release.tgz');
+        const bin = join(directory, 'bin');
+        const stableShim = join(bin, 'crtr');
+        const marker = join(directory, 'selected');
+        const calls = join(directory, 'npm-calls');
+        const fakeBin = join(directory, 'fake-bin');
+        mkdirSync(join(release, 'scripts'), { recursive: true });
+        mkdirSync(bin);
+        mkdirSync(fakeBin);
+        writeFileSync(join(release, 'scripts', 'install-runtime.mjs'), `import { writeFileSync } from 'node:fs';\nwriteFileSync(process.env.CRTR_SELF_UPDATE_MARKER, 'selected');\n`);
+        execFileSync('tar', ['-czf', archive, '-C', release, '.']);
+        symlinkSync('../stable-crtr', stableShim);
+        writeFileSync(join(fakeBin, 'npm'), `#!/usr/bin/env node\nimport { copyFileSync, appendFileSync } from 'node:fs';\nimport { basename, join } from 'node:path';\nconst args = process.argv.slice(2);\nappendFileSync(process.env.CRTR_SELF_UPDATE_CALLS, args.join(' ') + '\\n');\nif (args[0] !== 'pack') process.exit(1);\nconst destination = args[args.indexOf('--pack-destination') + 1];\ncopyFileSync(process.env.CRTR_SELF_UPDATE_ARCHIVE, join(destination, basename(process.env.CRTR_SELF_UPDATE_ARCHIVE)));\nprocess.stdout.write(JSON.stringify([{ filename: basename(process.env.CRTR_SELF_UPDATE_ARCHIVE) }]));\n`);
+        chmodSync(join(fakeBin, 'npm'), 0o755);
+        const result = spawnSync(process.execPath, [SELF_UPDATE], {
+            encoding: 'utf8',
+            env: {
+                ...process.env,
+                PATH: `${fakeBin}:${process.env.PATH}`,
+                CRTR_SELF_UPDATE_ARCHIVE: archive,
+                CRTR_SELF_UPDATE_CALLS: calls,
+                CRTR_SELF_UPDATE_MARKER: marker,
+            },
+        });
+        assert.equal(result.status, 0, result.stderr);
+        assert.equal(readFileSync(marker, 'utf8'), 'selected');
+        assert.equal(readlinkSync(stableShim), '../stable-crtr');
+        assert.match(readFileSync(calls, 'utf8'), /^pack @north-light\/crouter@latest --json --pack-destination .+\/crtr-self-update-\S+\n$/);
+    }
+    finally {
+        rmSync(directory, { recursive: true, force: true });
+    }
+});

package/dist/core/auto-update.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { readConfig, readState, updateState } from './config.js';
 import { nowIso } from './fs-utils.js';
 import { info } from './output.js';
-import { selfCheck, contentCheck } from './self-update.js';
+import { SELF_UPDATE_SCRIPT, selfCheck, contentCheck } from './self-update.js';
 const HOUR_MS = 60 * 60 * 1000;
 const SKIP_SUBCOMMANDS = new Set([
     'update',
@@ -27,7 +27,7 @@ function withinInterval(lastIso, intervalHours) {
     return Date.now() - last < intervalHours * HOUR_MS;
 }
 function spawnDetachedSelfUpdate() {
-    const child = spawn('npm', ['i', '-g', '@north-light/crouter@latest'], {
+    const child = spawn(process.execPath, [SELF_UPDATE_SCRIPT], {
         detached: true,
         stdio: 'ignore',
     });

package/dist/core/canvas/history.js

@@ -15,6 +15,7 @@ import { getNode, listNodes, view } from './canvas.js';
 import { contextDir, reportsDir, nodeDir, inboxPath } from './paths.js';
 import { readTextIfExists, walkFiles, pathExists } from '../fs-utils.js';
 import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { warn } from '../output.js';
 /** The cwd the caller means by default: the calling node's cwd (resolved from
  *  CRTR_NODE_ID via the canvas data layer), falling back to the process cwd
  *  when not run as a node. */
@@ -242,6 +243,11 @@ function listDocFiles(nodeId) {
         return [];
     }
 }
+/** Keep one malformed artifact from breaking a cross-node corpus scan. */
+function warnInvalidFrontmatter(path, error) {
+    const message = (error instanceof Error ? error.message : String(error)).split('\n')[0];
+    warn(`invalid frontmatter in ${path}: ${message}`);
+}
 /** The node desc lives in meta.json, not the row — read it once per survivor. */
 function nodeDescOf(nodeId) {
     const n = getNode(nodeId);
@@ -281,7 +287,15 @@ export function buildCorpus(scope, corpus) {
             out.push(metaArtifact(row, desc));
         if (want.has('report')) {
             for (const f of listReportFiles(row.node_id)) {
-                const a = reportArtifact(row, desc, f);
+                const abs = join(reportsDir(row.node_id), f);
+                let a;
+                try {
+                    a = reportArtifact(row, desc, f);
+                }
+                catch (e) {
+                    warnInvalidFrontmatter(abs, e);
+                    continue;
+                }
                 if (a === null)
                     continue;
                 if (wantReportKind !== undefined && a.reportKind !== wantReportKind)
@@ -291,7 +305,14 @@ export function buildCorpus(scope, corpus) {
         }
         if (want.has('doc') || want.has('roadmap')) {
             for (const abs of listDocFiles(row.node_id)) {
-                const a = docArtifact(row, desc, abs);
+                let a;
+                try {
+                    a = docArtifact(row, desc, abs);
+                }
+                catch (e) {
+                    warnInvalidFrontmatter(abs, e);
+                    continue;
+                }
                 if (a.source === 'roadmap' && !want.has('roadmap'))
                     continue;
                 if (a.source === 'doc' && !want.has('doc'))

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

@@ -217,6 +217,7 @@ function materializeForest(mounts, reservedCoreNames, issue) {
         ...(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],
     }));
     // Attach nested mounts
@@ -270,6 +271,12 @@ function resolveAndAttachMount(roots, mount, issue) {
         }
         current = child;
     }
+    // A passthrough owns every token below its path, so nested mounts would make
+    // the materialized branch invalid even though its inline children are empty.
+    if (current.passthrough !== undefined) {
+        issue('command_parent_invalid', 'parent path resolves to a passthrough branch', mount.parent.join('.'), 'a branch without passthrough', 'Remove the nested mount or remove passthrough from its parent branch.', mount.parent.join('.'));
+        return false;
+    }
     // Attach the node
     if (current.children.some((c) => c.name === mount.node.name)) {
         issue('command_node_invalid', `duplicate child name`, mount.node.name, 'unique child names within a branch', 'Rename the node or remove the duplicate.', `${mount.parent.join('.')}.${mount.node.name}`);

package/dist/core/command-plugins/compose.js

@@ -8,11 +8,15 @@ export function adaptPluginContributions(contributions) {
             node: contribution.node,
             adaptLeaf: (leaf, commandPath) => {
                 const transport = contribution.transport;
-                if (transport.kind === 'exec')
+                if (transport.kind === 'exec') {
+                    const executable = transport.executable;
+                    if (executable === undefined)
+                        throw new Error(`exec plugin "${contribution.plugin.name}" has an executable leaf without transport.executable`);
                     return {
                         outputKind: 'object',
-                        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable: transport.executable, commandPath: [...commandPath], output: leaf.output }, input),
+                        run: async (input) => executeExternalLeaf({ plugin: contribution.plugin, executable, commandPath: [...commandPath], output: leaf.output }, input),
                     };
+                }
                 const httpLeaf = leaf;
                 return {
                     outputKind: httpLeaf.rest.streaming === true ? 'jsonl' : 'object',

package/dist/core/command-plugins/discovery.js

@@ -56,17 +56,29 @@ function transportFor(plugin, issues) {
         return undefined;
     }
     const unknown = Object.keys(value).filter((key) => !['kind', 'executable'].includes(key));
-    if (value.kind !== 'exec' || unknown.length || typeof value.executable !== 'string' || value.executable.length === 0) {
-        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: unknown.length ? `transport has unknown keys: ${unknown.join(', ')}` : 'exec transport requires executable', received: JSON.stringify(raw), expected: '{ kind: "exec", executable: "plugin-relative path" }', next: 'Fix plugin.json.transport.', path: 'transport' });
+    if (value.kind !== 'exec' || unknown.length || (value.executable !== undefined && (typeof value.executable !== 'string' || value.executable.length === 0))) {
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: unknown.length ? `transport has unknown keys: ${unknown.join(', ')}` : 'exec transport requires a non-empty executable when declared', received: JSON.stringify(raw), expected: '{ kind: "exec", executable?: "plugin-relative path" }', next: 'Fix plugin.json.transport.', path: 'transport' });
         return undefined;
     }
-    const executable = safePath(plugin.root, value.executable);
+    return { kind: 'exec', ...(value.executable !== undefined ? { executable: value.executable } : {}) };
+}
+function hasExecutableLeaf(node) {
+    return node.kind === 'leaf' || node.children.some(hasExecutableLeaf);
+}
+function validateExecExecutable(plugin, transport, manifest, issues) {
+    if (transport.executable === undefined) {
+        if (!manifest.roots.some(hasExecutableLeaf))
+            return transport;
+        issues.push({ code: 'command_manifest_invalid', plugin: plugin.name, message: 'exec transport requires executable when commands.json declares executable leaves', received: '(missing)', expected: '{ kind: "exec", executable: "plugin-relative path" }', next: 'Add plugin.json.transport.executable.', path: 'transport.executable' });
+        return undefined;
+    }
+    const executable = safePath(plugin.root, transport.executable);
     if (executable === null) {
-        issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'executable escapes the plugin root or is not a regular file', received: value.executable, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.transport.executable.', path: 'transport.executable' });
+        issues.push({ code: 'command_path_unsafe', plugin: plugin.name, message: 'executable escapes the plugin root or is not a regular file', received: transport.executable, expected: 'a relative path to a regular file inside the plugin root', next: 'Fix plugin.json.transport.executable.', path: 'transport.executable' });
         return undefined;
     }
     if ((statSync(executable).mode & 0o111) === 0) {
-        issues.push({ code: 'command_not_executable', plugin: plugin.name, message: 'executable lacks the POSIX exec bit', received: value.executable, expected: 'a file with an executable permission bit', next: 'chmod +x the plugin executable, then update the plugin.', path: 'transport.executable' });
+        issues.push({ code: 'command_not_executable', plugin: plugin.name, message: 'executable lacks the POSIX exec bit', received: transport.executable, expected: 'a file with an executable permission bit', next: 'chmod +x the plugin executable, then update the plugin.', path: 'transport.executable' });
         return undefined;
     }
     return { kind: 'exec', executable };
@@ -122,7 +134,12 @@ export function validatePluginCommands(plugin, reservedNames = new Set()) {
         validation.issues.forEach(issueFor(plugin, issues));
         return { plugin, manifestPath, transport, contributions: [], issues };
     }
-    return { plugin, manifestPath, transport, contributions: validation.manifest.roots.map((node) => ({ plugin, transport, node, manifest: validation.manifest })), issues };
+    const resolvedTransport = transport.kind === 'exec'
+        ? validateExecExecutable(plugin, transport, validation.manifest, issues)
+        : transport;
+    if (resolvedTransport === undefined)
+        return { plugin, manifestPath, transport, contributions: [], issues };
+    return { plugin, manifestPath, transport: resolvedTransport, contributions: validation.manifest.roots.map((node) => ({ plugin, transport: resolvedTransport, node, manifest: validation.manifest })), issues };
 }
 export function discoverPluginCommandCandidates(startDir = process.cwd(), profileId) {
     return effectiveCommandPlugins(startDir, profileId).map((plugin) => validatePluginCommands(plugin));

package/dist/core/runtime/broker.js

@@ -475,8 +475,9 @@ export async function runBroker(nodeId, startupAt = process.hrtime.bigint(), sta
         });
     };
     // Defensive: any `crtr` child the engine/extensions spawn must inherit the
-    // front-door recursion guard (runtime/CLAUDE.md fork-bomb invariant). The host
-    // (T6) also sets this; we set it again so the broker is self-sufficient.
+    // front-door recursion guard (see
+    // src/core/runtime/.crouter/memory/INDEX.md). The host (T6) also sets this;
+    // setting it here keeps the broker self-sufficient.
     process.env[FRONT_DOOR_ENV] = '1';
     // A successful in-turn crtr command stamps this process id into its stop
     // signal, so a crash-revived broker cannot consume a prior broker's outcome.

package/dist/core/runtime/lifecycle.js

@@ -33,8 +33,8 @@
 // Layering note: lifecycle.ts is runtime, but it is the canvas write surface's
 // `transition` verb (the only writer of status+intent), so it owns its atomic
 // row UPDATE directly via openDb — the one sanctioned exception to "only
-// canvas.ts touches the db" (see canvas/CLAUDE.md), exactly as db.ts's backfill
-// is the sanctioned exception for a data migration.
+// canvas.ts touches the db" (see src/core/canvas/.crouter/memory/INDEX.md),
+// exactly as db.ts's backfill is the sanctioned exception for a data migration.
 import { openDb, getNode, cancelCronsOnWake } from '../canvas/index.js';
 const ANY = '*';
 /** The supervised statuses — a live node the daemon watches. */

package/dist/core/self-update.d.ts

@@ -1,3 +1,4 @@
+export declare const SELF_UPDATE_SCRIPT: string;
 export declare function currentVersion(): string;
 export declare function selfUpdate(): void;
 /** Check whether a newer crtr version is available on npm.

package/dist/core/self-update.js

@@ -15,16 +15,18 @@ const __dirname = dirname(__filename);
 // src/core/self-update.ts → up to src/ → up to pkg root
 const PKG_ROOT = join(__dirname, '..', '..');
 const PACKAGE_JSON_PATH = join(PKG_ROOT, 'package.json');
+export const SELF_UPDATE_SCRIPT = join(PKG_ROOT, 'scripts', 'self-update.mjs');
 export function currentVersion() {
     const raw = readFileSync(PACKAGE_JSON_PATH, 'utf8');
     const parsed = JSON.parse(raw);
     return parsed.version;
 }
 export function selfUpdate() {
-    const res = spawnSync('npm', ['i', '-g', '@north-light/crouter@latest'], { stdio: 'inherit' });
-    if (res.status !== 0) {
-        throw general('npm install failed');
-    }
+    const res = spawnSync(process.execPath, [SELF_UPDATE_SCRIPT], { stdio: 'inherit' });
+    if (res.error)
+        throw general(`self-update failed: ${res.error.message}`);
+    if (res.status !== 0)
+        throw general(`self-update failed (${res.status ?? res.signal ?? 'unknown'})`);
 }
 /** Check whether a newer crtr version is available on npm.
  *  Warns to stderr if network unavailable; returns {current, latest} or null if unreachable. */

package/dist/prompts/review.js

@@ -48,8 +48,10 @@ seams to fall between — skip it for self-contained specs.
 
 For larger specs touching established patterns, optionally spawn a Task
 agent (\`general-purpose\`, \`sonnet\`) to cross-check the spec's design
-against \`CLAUDE.md\` / \`.claude/rules/*.md\` and the files it references,
-looking for contradictions with project conventions. Skip for small specs.
+against the applicable project memory documents (discover them with
+\`crtr memory list\` and load them with \`crtr memory read\`) and the files they
+reference, looking for contradictions with project conventions. Skip for small
+specs.
 
 ## Calibration
 

package/dist/types.d.ts

@@ -14,8 +14,8 @@ export interface OwnerRef {
     email?: string;
 }
 export type PluginTransport = {
-    kind: 'exec';
-    executable: string;
+    kind: 'exec'; /** Required when the validated command manifest has executable leaves. */
+    executable?: string;
 } | {
     kind: 'http';
     endpoint: string;