@crouton-kit/crouter 0.3.67 → 0.3.68

package/dist/commands/capture.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerCapture(): BranchDef;

package/dist/commands/capture.js

@@ -0,0 +1,28 @@
+// `crtr capture` — transparent passthrough to the external Capture CLI
+// (`@crouton-kit/capture`, bin `capture`). Capture stays a separately
+// published, open-source package: crouter takes no build-time dependency on
+// it and does not mirror its command tree. Every argument after `capture` is
+// forwarded verbatim (see the `passthrough` field on BranchDef in
+// core/command.ts) — including `crtr capture -h`, which shows CAPTURE's own
+// help, not crtr's. crtr's only framing of this command lives in the
+// rootEntry below (surfaced at `crtr -h`); there is no separate crtr-level
+// help body to keep in sync with capture's schema.
+import { defineBranch } from '../core/command.js';
+const INSTALL_HINT = 'Install the Capture CLI: npm install -g @crouton-kit/capture';
+export function registerCapture() {
+    return defineBranch({
+        name: 'capture',
+        passthrough: { bin: 'capture', installHint: INSTALL_HINT },
+        rootEntry: {
+            concept: 'browser automation for agents via the external Capture CLI (CDP screenshots, HAR, a11y, JS-exec, and site libs)',
+            desc: 'forwards verbatim to the external `capture` binary',
+            useWhen: 'you need headless browser automation — screenshot or inspect a page, record a HAR, or run JS in a real browser to reach a site\'s backend (e.g. Reddit/X via the bundled libs). `crtr capture <args>` forwards every argument verbatim to the external `capture` CLI, including `-h` — run `crtr capture -h` for capture\'s own command schema. Requires `capture` on PATH (npm install -g @crouton-kit/capture).',
+        },
+        help: {
+            name: 'capture',
+            summary: 'transparent alias for the external `capture` CLI — every argument forwards verbatim',
+            model: 'This branch owns no schema of its own: it execs `capture` with whatever args follow, inherits stdio, and propagates its exit code. Run `crtr capture -h` for capture\'s real command tree.',
+        },
+        children: [],
+    });
+}

package/dist/core/__tests__/revive.test.js

@@ -34,9 +34,11 @@ import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
+import { DatabaseSync } from 'node:sqlite';
 import { createNode, subscribe } from '../canvas/canvas.js';
 import { readInboxSince } from '../feed/inbox.js';
-import { closeDb } from '../canvas/db.js';
+import { closeDb, openDb } from '../canvas/db.js';
+import { canvasDbPath } from '../canvas/paths.js';
 import { buildPiArgv } from '../runtime/launch.js';
 import { headlessBrokerHost } from '../runtime/host.js';
 import { resumeArgs, reviveNode } from '../runtime/revive.js';
@@ -350,3 +352,70 @@ test('reviveNode fans a doctrine wake to subscribers when launch/preflight throw
         await h.dispose();
     }
 });
+// ---------------------------------------------------------------------------
+// Duplicate-broker leak (live-incident regression): reviveNode's guard-check-
+// then-launch-then-recordPid critical section must be a single atomic write
+// transaction, so a concurrent reviveNode call for the SAME node (a second OS
+// process racing this one against the same canvas.db, e.g. a retried web-relay
+// revive under socket thrash) cannot read the same stale pid, launch its own
+// broker, and overwrite this call's freshly-recorded pid — leaking this call's
+// broker as an untracked live process. Proven here by holding a competing raw
+// write transaction open on a SECOND connection to the same db file before
+// calling reviveNode: with the fix, reviveNode's own BEGIN IMMEDIATE cannot
+// acquire the write lock while the other connection holds it, so it fails
+// closed (throws) rather than silently interleaving with the held lock and
+// corrupting the guard's read-then-write. Releasing the competing lock lets an
+// identical reviveNode call proceed and record a fresh pid normally — the
+// serialization is transient contention, not a permanent wedge.
+// ---------------------------------------------------------------------------
+test('reviveNode\'s guard-check-through-recordPid section is one atomic write transaction (duplicate-broker-leak regression)', async () => {
+    const h = await createHarness({ headless: true, sessionPrefix: 'crtr-revive-lock' });
+    let contender;
+    try {
+        const sessionFile = join(home, 'sessions', 'crtr-revive-lock.jsonl');
+        mkdirSync(join(home, 'sessions'), { recursive: true });
+        writeFileSync(sessionFile, '{}\n', 'utf8');
+        const stalePid = deadPid();
+        const M = h.fabricateBrokerNode({
+            status: 'active',
+            intent: null,
+            pi_pid: stalePid,
+            pi_session_id: 'uuid-lock',
+            pi_session_file: sessionFile,
+        });
+        // Shorten THIS test's connection's busy_timeout (default 5000ms, db.ts) so
+        // the contended call below fails fast instead of waiting out the real
+        // production window — it's the ACQUIRING side's timeout that governs how
+        // long `BEGIN IMMEDIATE` waits, not the holder's.
+        openDb().exec('PRAGMA busy_timeout = 200;');
+        // A second raw connection to the SAME db file holds an exclusive write
+        // transaction open — modeling a concurrent reviveNode call (a different OS
+        // process, in the real incident) that already won the race and is mid-launch.
+        contender = new DatabaseSync(canvasDbPath());
+        contender.exec('BEGIN IMMEDIATE');
+        assert.throws(() => reviveNode(M, { resume: true }), /locked|busy/i, 'a reviveNode call cannot acquire the write lock while a concurrent revive holds it — no interleaved double-launch');
+        assert.equal(h.node(M).pi_pid, stalePid, 'blocked-out call recorded nothing — the held pid is untouched');
+        // Release the contender's lock — an identical reviveNode call now proceeds
+        // normally, exactly like the uncontended case.
+        contender.exec('COMMIT');
+        contender.close();
+        contender = undefined;
+        reviveNode(M, { resume: true });
+        const after = h.node(M);
+        assert.notEqual(after.pi_pid, stalePid, 'once uncontended, revive proceeds and records a fresh pid');
+        assert.equal(after.cycles, 1, 'the uncontended revive bumped the cycle counter');
+    }
+    finally {
+        if (contender !== undefined) {
+            try {
+                contender.exec('ROLLBACK');
+            }
+            catch { /* best-effort */ }
+            try {
+                contender.close();
+            }
+            catch { /* best-effort */ }
+        }
+        await h.dispose();
+    }
+});

package/dist/core/command.d.ts

@@ -56,6 +56,17 @@ export interface BranchDef {
     rootEntry?: RootEntry;
     /** Opt into editor slash-command exposure (see SlashSpec). */
     slash?: SlashSpec;
+    /** Opt this branch out of the tree model entirely: every token after this
+     *  branch's name is forwarded VERBATIM (raw argv, not the `--json`-filtered
+     *  tokens) to an external binary via spawn, with stdio inherited and the
+     *  child's exit code propagated. A deliberate, documented exception for
+     *  wrapping an external CLI whose own schema crtr cannot and must not
+     *  duplicate (see `crtr capture`) — not a general escape hatch. A
+     *  passthrough branch should declare no children. */
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
     children: (LeafDef | BranchDef)[];
 }
 export interface RootDef {
@@ -81,6 +92,10 @@ export declare function defineBranch(opts: {
     help: BranchHelp;
     rootEntry?: RootEntry;
     slash?: SlashSpec;
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
     children: (LeafDef | BranchDef)[];
 }): BranchDef;
 /** Walk the whole tree and collect every node's SlashSpec (depth-first). Used

package/dist/core/command.js

@@ -10,6 +10,8 @@ import { renderResult } from './render.js';
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
 import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { constants as osConstants } from 'node:os';
 // ---------------------------------------------------------------------------
 // Factory functions
 // ---------------------------------------------------------------------------
@@ -34,6 +36,14 @@ function visibleSubCount(def) {
     return (def.help.listing ?? []).filter((c) => c.tier !== 'hidden').length;
 }
 export function defineBranch(opts) {
+    // A passthrough branch must be childless: walk() only stops at the deepest
+    // matched node, so a passthrough branch with children would let some
+    // invocations descend into a child (tree dispatch) while others hit the
+    // passthrough interception — silently inconsistent transparency. Fail loudly
+    // at construction instead of letting that split happen at runtime.
+    if (opts.passthrough !== undefined && opts.children.length > 0) {
+        throw new Error(`defineBranch("${opts.name}"): a passthrough branch must declare no children (found ${opts.children.length})`);
+    }
     // Assemble the parent-level listing straight from the child defs — each node
     // owns its own description/whenToUse/tier, so the parent copies nothing
     // (principle 16). Bottom-up construction guarantees a child branch's listing
@@ -57,6 +67,7 @@ export function defineBranch(opts) {
         help: opts.help,
         rootEntry: opts.rootEntry,
         slash: opts.slash,
+        passthrough: opts.passthrough,
         children: opts.children,
     };
 }
@@ -169,6 +180,59 @@ function renderNode(node) {
 function helpRequested(remaining) {
     return remaining.some((t) => t === '-h' || t === '--help');
 }
+/** Recover the RAW argv slice after a matched passthrough branch's path,
+ *  unaffected by the `--json`-stripping done to build `tokens`. `path` is a
+ *  prefix of non-`--json` tokens in order, so walking `rawTokens` while
+ *  skipping `--json` occurrences until `path` is fully matched lands the
+ *  cursor exactly where the branch's own args begin — including a literal
+ *  `--json` the external binary itself accepts. */
+function rawArgsAfterPath(rawTokens, path) {
+    let matched = 0;
+    for (let i = 0; i < rawTokens.length; i++) {
+        if (matched === path.length)
+            return rawTokens.slice(i);
+        if (rawTokens[i] === '--json')
+            continue;
+        if (rawTokens[i] === path[matched])
+            matched++;
+    }
+    return [];
+}
+/** Forward `args` to an external binary verbatim: stdio inherited (streaming
+ *  preserved), and the child's exit code propagated. Never returns — either
+ *  exits with the child's status or throws a structured CrtrError (ENOENT ->
+ *  install hint) for the caller's existing error handler to render. */
+function runPassthrough(passthrough, args) {
+    const result = spawnSync(passthrough.bin, args, { stdio: 'inherit' });
+    if (result.error !== undefined) {
+        // Any launch-time failure (not found, not executable, ...) means this
+        // binary isn't usable from here — surface one structured error with the
+        // install hint rather than branching on a specific errno. (Node/libuv can
+        // report EACCES instead of ENOENT for a genuinely-missing binary when PATH
+        // contains malformed entries — e.g. a literal `~/...` segment — so a
+        // ENOENT-only check would miss real missing-binary cases on such hosts.)
+        const err = result.error;
+        throw new CrtrError('binary_missing', `${passthrough.bin} could not be run (${err.code ?? err.message})`, ExitCode.USAGE, {
+            received: passthrough.bin,
+            next: passthrough.installHint,
+        });
+    }
+    if (result.status !== null) {
+        process.exit(result.status);
+    }
+    if (result.signal !== null) {
+        // Signal-terminated: exit(1) would break the transparent exit-propagation
+        // contract (a direct shell invocation would show 128+signal, e.g. 143 for
+        // SIGTERM). Map to the standard 128+signal-number convention.
+        const signalNumber = osConstants.signals[result.signal];
+        if (signalNumber !== undefined) {
+            process.exit(128 + signalNumber);
+        }
+    }
+    // Truly impossible per Node's spawnSync contract (status and signal are
+    // mutually exclusive and one is always set on a completed run) — fallback only.
+    process.exit(1);
+}
 /** Build a structured unknown-path error. Names valid children of the deepest
  *  matched node and names the entry command per the spec. The entry command is
  *  the full path to the matched node (not just its local name), so the recovery
@@ -367,6 +431,14 @@ export async function runCli(root, argv) {
     }
     const { node, path, remaining } = walk(root, tokens);
     try {
+        // Passthrough branches (e.g. `crtr capture`) opt out of the tree model
+        // entirely: forward every token after the branch verbatim to an external
+        // binary before any of the normal unknown-path / help / dispatch logic
+        // runs, so `crtr capture -h`, `crtr capture <args>`, and bare `crtr capture`
+        // all reach the external CLI untouched.
+        if (node.kind === 'branch' && node.passthrough !== undefined) {
+            runPassthrough(node.passthrough, rawArgsAfterPath(rawTokens, path));
+        }
         // A root/branch node's `remaining` is only non-empty because walk hit
         // -h/--help or an unmatched child name (a leaf always consumes the rest
         // of the path itself). So a non-help leading token here is always the

package/dist/core/profiles/select.d.ts

@@ -27,7 +27,10 @@ export declare function profileCoversCwd(entry: ProfileEntry, cwd: string): bool
  *         is covered). Default is the MRU covering profile.
  *       - Non-interactive: auto-pick the MRU covering profile, no prompt.
  *  4. Else — nothing covers cwd walking all the way up. Interactive: prompt to
- *     create a profile here or use the root profile. Non-interactive (no TTY):
+ *     create a profile here, select an existing profile (a searchable list of
+ *     every profile, for when you started somewhere none of them cover and
+ *     can't recall the exact name — the pick then offers to adopt cwd), or use
+ *     the root profile. Non-interactive (no TTY):
  *     default to the root profile and print the recovery instruction to STDERR —
  *     never stdout, which the caller may be piping. */
 export declare function selectProfileForCwd(cwd: string, explicitProfile?: string | null, forcePicker?: boolean): Promise<string>;