@crouton-kit/crouter 0.3.32 → 0.3.33

package/dist/commands/chord.js

@@ -1,51 +1,123 @@
 // `crtr canvas chord` — the tmux prefix-menu dispatcher.
 //
 // The alt+c display-menu can't see the cursor node or read config at popup time
-// — it only knows the active pane. So every config-driven prefix chord routes
-// through this one leaf: tmux passes `--pane '#{pane_id}'` + `--key <k>`, and
-// the dispatcher resolves the node in that pane, reads
-// `canvasNav.prefixBinds[key]`, interpolates the template vars, and execs
-// `crtr <argv>`. This keeps the menu static while the behaviour stays fully
-// config-driven (no per-node menu rebuild).
+// — it only knows the active pane. So the menu hands this leaf a resolved `--run`
+// string plus the originating pane id; this dispatcher resolves the node in that
+// pane, interpolates the node vars, and execs `crtr <argv>` with no shell.
 //
-// One special case bypasses the bind table:
-//   • a bind whose `run` is the sentinel `__graph__` → send-keys `/graph` into
-//     the pane (toggles the in-pi GRAPH modal); the menu emits this directly so
-//     the dispatcher only handles it defensively.
-//
-// execFile (never `sh -c`) runs the interpolated argv, so a node name with
-// shell metacharacters can never inject — each argv element is literal.
+// execFile/spawn (never `sh -c`) keeps the argv literal, so shell metacharacters
+// in config data cannot inject.
+import { spawn, execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { execFile } from 'node:child_process';
 import { defineLeaf } from '../core/command.js';
 import { InputError } from '../core/io.js';
-import { readConfig } from '../core/config.js';
-import { sendKeysEnter } from '../core/runtime/tmux-chrome.js';
 import { nodeInPane } from './node.js';
 import { getNode, subscribersOf, view, fullName, } from '../core/canvas/index.js';
 const pexec = promisify(execFile);
 /** Template vars available to a `run` string. Single-valued vars interpolate
- *  in place (preserving spaces, e.g. a node name); `{subtree}` is multi-valued
- *  and a bare `{subtree}` token expands to several argv elements. */
-function buildVars(selfId) {
+ *  in place (preserving spaces, e.g. a node name); `{pane}` is the active tmux
+ *  pane id; `{subtree}` is multi-valued and a bare `{subtree}` token expands to
+ *  several argv elements. */
+function buildVars(selfId, pane) {
     const node = getNode(selfId);
     const manager = subscribersOf(selfId)[0]?.node_id ?? '';
     return {
         id: selfId,
         self: selfId,
+        pane,
         lane: selfId,
         name: node !== null ? fullName(node) : selfId,
         manager,
         subtree: view(selfId).join(' '),
     };
 }
+function parseRun(run) {
+    const out = [];
+    let cur = '';
+    let quoted = null;
+    let escaped = false;
+    let inToken = false;
+    const push = () => {
+        if (!inToken)
+            return;
+        out.push(cur);
+        cur = '';
+        inToken = false;
+    };
+    for (let i = 0; i < run.length; i++) {
+        const ch = run[i];
+        if (escaped) {
+            cur += ch;
+            inToken = true;
+            escaped = false;
+            continue;
+        }
+        if (quoted === 'single') {
+            if (ch === "'") {
+                quoted = null;
+            }
+            else {
+                cur += ch;
+                inToken = true;
+            }
+            continue;
+        }
+        if (quoted === 'double') {
+            if (ch === '"') {
+                quoted = null;
+            }
+            else if (ch === '\\') {
+                escaped = true;
+            }
+            else {
+                cur += ch;
+                inToken = true;
+            }
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            push();
+            continue;
+        }
+        if (ch === "'") {
+            quoted = 'single';
+            inToken = true;
+            continue;
+        }
+        if (ch === '"') {
+            quoted = 'double';
+            inToken = true;
+            continue;
+        }
+        if (ch === '\\') {
+            escaped = true;
+            inToken = true;
+            continue;
+        }
+        cur += ch;
+        inToken = true;
+    }
+    if (escaped) {
+        cur += '\\';
+        inToken = true;
+    }
+    if (quoted !== null) {
+        throw new InputError({
+            error: 'bad_run',
+            message: 'invalid canvas run string: unterminated quote',
+            next: 'Fix the bind in config.json and try again.',
+        });
+    }
+    push();
+    return out;
+}
 /** Split a `run` string argv-style and interpolate the template vars. A bare
  *  `{subtree}` token expands to several argv elements; every other placeholder
  *  is substituted in place (kept as one element so a multi-word name survives
  *  as a single argument under execFile). */
 function interpolateArgv(run, vars) {
     const out = [];
-    for (const tok of run.split(/\s+/).filter((t) => t !== '')) {
+    for (const tok of parseRun(run)) {
         if (tok === '{subtree}') {
             for (const part of (vars['subtree'] ?? '').split(/\s+/).filter((p) => p !== ''))
                 out.push(part);
@@ -55,13 +127,36 @@ function interpolateArgv(run, vars) {
     }
     return out;
 }
+async function dispatch(argv, interactive) {
+    if (argv.length === 0)
+        return;
+    if (interactive) {
+        await new Promise((resolve) => {
+            try {
+                const child = spawn('crtr', argv, { stdio: 'inherit' });
+                child.once('error', () => resolve());
+                child.once('close', () => resolve());
+            }
+            catch {
+                resolve();
+            }
+        });
+        return;
+    }
+    try {
+        await pexec('crtr', argv, { timeout: 15_000 });
+    }
+    catch {
+        /* best-effort: the keystroke just acts; errors are surfaced by the inner cmd */
+    }
+}
 export const chordLeaf = defineLeaf({
     name: 'chord',
     description: 'tmux prefix-menu dispatcher (bound by alt+c; not run by hand)',
-    whenToUse: 'never directly — the alt+c menu routes config-driven chords through it',
+    whenToUse: 'never directly — the alt+c menu routes node-relative actions through it',
     help: {
         name: 'canvas chord',
-        summary: 'tmux prefix-menu dispatcher — resolve the node in --pane, look up canvasNav.prefixBinds[--key], interpolate, and exec `crtr <argv>`. Bound by the alt+c menu; not meant to be run by hand.',
+        summary: 'tmux prefix-menu dispatcher — resolve the node in --pane, interpolate --run against it, and exec `crtr <argv>`. Bound by the alt+c menu; not meant to be run by hand.',
         params: [
             {
                 kind: 'flag',
@@ -72,24 +167,39 @@ export const chordLeaf = defineLeaf({
             },
             {
                 kind: 'flag',
-                name: 'key',
+                name: 'run',
                 type: 'string',
                 required: true,
-                constraint: 'The chord key pressed after alt+c (e.g. g or m).',
+                constraint: 'The argv string to run as crtr, after node vars resolve.',
+            },
+            {
+                kind: 'flag',
+                name: 'interactive',
+                type: 'bool',
+                required: false,
+                constraint: 'When true, inherit stdio so popup forms can read from the popup tty.',
             },
         ],
         output: [
             { name: 'ran', type: 'boolean', required: true, constraint: 'True when an action was dispatched.' },
-            { name: 'key', type: 'string', required: true, constraint: 'Echo of the chord key.' },
             { name: 'node_id', type: 'string', required: false, constraint: 'The node the chord resolved against.' },
-            { name: 'action', type: 'string', required: false, constraint: 'What ran: a crtr argv string, "graph-toggle", or "noop".' },
+            { name: 'action', type: 'string', required: false, constraint: 'What ran: a crtr argv string or "noop".' },
         ],
         outputKind: 'object',
-        effects: ['Runs a `crtr` subcommand (focus/close/…) or sends `/graph` into the pane, per the matched bind.'],
+        effects: ['Runs a `crtr` subcommand per the resolved bind.'],
     },
     run: async (input) => {
-        const pane = input['pane'] ?? process.env['TMUX_PANE'];
-        const key = input['key'].trim();
+        const rawPane = input['pane'];
+        const pane = rawPane !== undefined && rawPane !== '' ? rawPane : process.env['TMUX_PANE'];
+        const run = input['run']?.trim();
+        const interactive = input['interactive'] === true;
+        if (run === undefined || run === '') {
+            throw new InputError({
+                error: 'missing_run',
+                message: 'no run string provided',
+                next: 'Pass --run <argv-string> from the menu renderer.',
+            });
+        }
         const selfId = nodeInPane(pane);
         if (selfId === undefined) {
             throw new InputError({
@@ -98,25 +208,10 @@ export const chordLeaf = defineLeaf({
                 next: 'Run from inside an agent\'s pane, or pass --pane <pane-id>.',
             });
         }
-        const bind = readConfig('user').canvasNav.prefixBinds[key];
-        if (bind === undefined)
-            return { ran: false, key, node_id: selfId, action: 'noop' };
-        // The GRAPH-toggle sentinel: type /graph into the pane (the menu normally
-        // emits this directly; handle it here too so a manual chord still works).
-        if (bind.run === '__graph__') {
-            if (pane !== undefined && pane !== '')
-                sendKeysEnter(pane, '/graph');
-            return { ran: true, key, node_id: selfId, action: 'graph-toggle' };
-        }
-        const argv = interpolateArgv(bind.run, buildVars(selfId));
+        const argv = interpolateArgv(run, buildVars(selfId, pane ?? ''));
         if (argv.length === 0)
-            return { ran: false, key, node_id: selfId, action: 'noop' };
-        try {
-            await pexec('crtr', argv, { timeout: 15_000 });
-        }
-        catch {
-            /* best-effort: the keystroke just acts; errors are surfaced by the inner cmd */
-        }
-        return { ran: true, key, node_id: selfId, action: `crtr ${argv.join(' ')}` };
+            return { ran: false, node_id: selfId, action: 'noop' };
+        await dispatch(argv, interactive);
+        return { ran: true, node_id: selfId, action: `crtr ${argv.join(' ')}` };
     },
 });

package/dist/commands/daemon.js

@@ -29,11 +29,11 @@ const daemonStart = defineLeaf({
         outputKind: 'object',
         effects: [
             'Spawns dist/daemon/crtrd-cli.js detached + unref\'d; it outlives this process.',
-            'Writes a pidfile at crtrHome()/crtrd.pid.',
+            'Writes a pidfile at CRTR_PIDFILE if set, otherwise crtrHome()/crtrd.pid.'
         ],
     },
     run: async (_input) => {
-        const result = spawnDaemon();
+        const result = await spawnDaemon();
         return result;
     },
 });
@@ -94,7 +94,7 @@ const daemonStop = defineLeaf({
             throw new InputError({
                 error: 'kill_failed',
                 message: `failed to signal pid ${pid}: ${err.message}`,
-                next: 'The pidfile may be stale; remove ~/.crouter/canvas/crtrd.pid manually.',
+                next: 'The pidfile may be stale; remove the recorded pidfile manually.',
             });
         }
     },

package/dist/commands/human/prompts.d.ts

@@ -1,5 +1,4 @@
 export declare const humanAsk: import("../../core/command.js").LeafDef;
-export declare const humanApprove: import("../../core/command.js").LeafDef;
 export declare const humanReview: import("../../core/command.js").LeafDef;
 export declare const humanNotify: import("../../core/command.js").LeafDef;
 export declare const humanShow: import("../../core/command.js").LeafDef;

package/dist/commands/human/prompts.js

@@ -6,25 +6,40 @@ import { tmuxServerReachable } from '../../core/spawn.js';
 import { mkdirSync, existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { validateDeck, approveDeck, notifyDeck, atomicWriteJson, deckPath, display, } from '@crouton-kit/humanloop';
+import { validateDeck, notifyDeck, atomicWriteJson, deckPath, display, } from '@crouton-kit/humanloop';
 import { DECK_SCHEMA_HINT, followUpReview, spawnHumanJob, detachHumanTui, resolveMaxPanes, } from './shared.js';
 /** The asking node's id, or null when run from a bare shell (no parent to route to). */
 function askingNode() {
     return process.env['CRTR_NODE_ID'] ?? null;
 }
+function buildHumanAskDeck(question) {
+    return validateDeck({
+        title: question,
+        interactions: [
+            {
+                id: 'question',
+                title: question,
+                options: [],
+                allowFreetext: true,
+                freetextLabel: 'Your answer',
+            },
+        ],
+    });
+}
 // ---------------------------------------------------------------------------
 // ask
 // ---------------------------------------------------------------------------
 export const humanAsk = defineLeaf({
     name: 'ask',
     description: 'put a structured choice or open question to a person',
-    whenToUse: 'you would otherwise lay a decision, a set of options, or a question out for the user as prose — reach for this instead, for anything from a quick yes/no to a judgment-heavy call: reviewing all the requirements before building, choosing among implementation patterns, walking a list of risks and deciding what to do about each, settling a naming or scope question, picking which of several findings to act on. Works for open-ended asks too (set `allowFreetext`, offer a few `options` as starting points). The kickoff never blocks, so the human answering on their own time is never a reason to skip the ask and guess instead',
+    whenToUse: 'you would otherwise lay a decision, a set of options, or a question out for the user as prose — reach for this instead, for anything from a quick yes/no to a judgment-heavy call: gating a handoff, merge, deploy, destructive/irreversible operation, or real budget on an explicit human sign-off (offer Yes/No options), reviewing all the requirements before building, choosing among implementation patterns, walking a list of risks and deciding what to do about each, settling a naming or scope question, picking which of several findings to act on. Works for open-ended asks too (set `allowFreetext`, offer a few `options` as starting points). The kickoff never blocks, so the human answering on their own time is never a reason to skip the ask and guess instead',
     help: {
         name: 'human ask',
         summary: 'put a humanloop decision deck in front of a person; returns a job handle immediately. This is the default, expected channel for posing ANY question or decision to the user — reach for it instead of writing the question as prose in your reply.',
-        guide: 'Use this for quick, open-ended, and nuanced asks alike — not just "formal" multiple-choice. Set `allowFreetext: true` (with `freetextLabel`) when the answer is open-ended; offer a few `options` as starting points even for judgment calls. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
+        guide: 'Use exactly one of these forms: `crtr human ask "<question>"` for a simple open-text prompt (the CLI builds a one-item humanloop deck internally), or `crtr human ask --context-file deck.json` for a fully structured deck. The kickoff is instant and NEVER blocks — "never block on the result" refers only to not busy-waiting on the job; the human answering on their own time is not a reason to avoid asking or to fall back to inline prose. The deck body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
         params: [
-            { kind: 'context-file', name: 'deck', required: true, constraint: 'Contains a humanloop deck. Validated before any job is created.', shape: DECK_SCHEMA_HINT },
+            { kind: 'positional', name: 'question', type: 'string', required: false, constraint: 'Bare-question shorthand for a simple open-text ask. Mutually exclusive with `--context-file`.' },
+            { kind: 'context-file', name: 'deck', required: false, constraint: 'Strict complex-ask deck JSON. Use this when you need multiple interactions, options, or other deck structure. Mutually exclusive with the question shorthand.', shape: DECK_SCHEMA_HINT },
             { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'Accepted for symmetry with the job contract; the kickoff never blocks.' },
         ],
         output: [
@@ -39,9 +54,25 @@ export const humanAsk = defineLeaf({
         ],
     },
     run: async (input) => {
+        const question = input['question'];
+        const deckInput = input['deck'];
+        if (question !== undefined && deckInput !== undefined) {
+            throw new InputError({
+                error: 'bad_invocation',
+                message: 'use either a bare question or --context-file, not both',
+                next: 'Run `crtr human ask "<question>"` for a simple open-text prompt, or `crtr human ask --context-file deck.json` for a structured deck.',
+            });
+        }
+        if (question === undefined && deckInput === undefined) {
+            throw new InputError({
+                error: 'missing_parameter',
+                message: 'human ask needs either a question or --context-file deck.json',
+                next: 'Run `crtr human ask "<question>"` or `crtr human ask --context-file deck.json`.',
+            });
+        }
         let deck;
         try {
-            deck = validateDeck(input['deck']);
+            deck = validateDeck(question !== undefined ? buildHumanAskDeck(question) : deckInput);
         }
         catch (e) {
             throw new InputError({
@@ -63,61 +94,15 @@ export const humanAsk = defineLeaf({
     },
 });
 // ---------------------------------------------------------------------------
-// approve
-// ---------------------------------------------------------------------------
-export const humanApprove = defineLeaf({
-    name: 'approve',
-    description: 'a Yes/No sign-off gate',
-    whenToUse: 'a step needs an explicit human yes before it proceeds and a plain answer (not anchored comments) is enough: before a handoff, a merge or deploy, a destructive or irreversible operation, spending real budget, or acting on a risky plan. Reach for `ask` instead when you need them to choose among options or answer something open-ended; reach for `review` when the feedback belongs inline on a document',
-    help: {
-        name: 'human approve',
-        summary: 'a Yes/No approval gate; returns a job handle immediately. The standard way to gate a handoff on human sign-off. Kickoff never blocks — peek at the result later rather than busy-waiting; the human answering on their own time is not a reason to skip the gate.',
-        guide: 'The body is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.',
-        params: [
-            { kind: 'positional', name: 'title', type: 'string', required: true, constraint: 'The question shown to the human.' },
-            { kind: 'flag', name: 'subtitle', type: 'string', required: false, constraint: 'Optional one-line context.' },
-            { kind: 'flag', name: 'body', type: 'string', required: false, constraint: 'Optional markdown body.' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Node id of this approval; the {approved, …envelope} result is pushed to your inbox when answered.' },
-            { name: 'dir', type: 'string', required: true, constraint: 'Interaction directory.' },
-            { name: 'follow_up', type: 'string', required: true, constraint: 'A non-blocking status peek. The human may take minutes to hours — never block waiting on this.' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Creates a kind:"human" node under you and writes a Yes/No validation deck.',
-            'Spawns the approval TUI in a detached tmux pane (when in tmux).',
-        ],
-    },
-    run: async (input) => {
-        const title = input['title'];
-        const subtitle = input['subtitle'];
-        const body = input['body'];
-        const deck = approveDeck(title, {
-            ...(subtitle !== undefined ? { subtitle } : {}),
-            ...(body !== undefined ? { body } : {}),
-        });
-        const cwd = process.cwd();
-        const jobId = spawnNode({ kind: 'human', parent: askingNode(), cwd, name: 'human-approve', lifecycle: 'terminal' }).node_id;
-        const idir = interactionDir(jobId, cwd);
-        mkdirSync(idir, { recursive: true });
-        atomicWriteJson(deckPath(idir), deck);
-        const rc = { mode: 'approve', job_id: jobId, approve_iid: 'approve' };
-        atomicWriteJson(join(idir, 'run.json'), rc);
-        const { follow_up } = spawnHumanJob(jobId, idir, cwd);
-        return { job_id: jobId, dir: idir, follow_up };
-    },
-});
-// ---------------------------------------------------------------------------
 // review
 // ---------------------------------------------------------------------------
 export const humanReview = defineLeaf({
     name: 'review',
     description: 'collect anchored comments on a .md (plan or spec)',
-    whenToUse: 'a human should comment line-by-line on a document rather than give one overall answer: reviewing a plan or spec before you build it, marking up a draft, flagging specific sections to change. The comments come back anchored to the lines they touch. Use `approve` instead for a single yes/no on the whole thing, or `ask` to pose a discrete choice',
+    whenToUse: 'a human should comment line-by-line on a document rather than give one overall answer: reviewing a plan or spec before you build it, marking up a draft, flagging specific sections to change. The comments come back anchored to the lines they touch. Use `ask` instead for a single yes/no sign-off on the whole thing, or to pose a discrete choice',
     help: {
         name: 'human review',
-        summary: "put a .md live on the human's screen for anchored, line-by-line comments; returns a job handle instantly (a non-blocking kickoff, like ask/approve). The pane tracks the file and re-renders on every save, so edit in place rather than re-presenting.",
+        summary: "put a .md live on the human's screen for anchored, line-by-line comments; returns a job handle instantly (a non-blocking kickoff, like ask). The pane tracks the file and re-renders on every save, so edit in place rather than re-presenting.",
         guide: "A kickoff, not a blocking call: it returns at once and the human reviews on their own time. When they submit, the FeedbackResult (anchored comments, plus any line edits they made) is pushed to your inbox — waking you — and autosaved to `output`; you never poll, verify it opened, or background it. The pane is a LIVE view of the file: keep editing the .md in place and it updates, so do not cancel and re-present to show a change. The .md is directive-flavored markdown rendered by termrender (panels, columns, trees, callouts, mermaid) — see `termrender doc -h` for the directive set before authoring one.",
         params: [
             { kind: 'positional', name: 'file', type: 'path', required: true, constraint: 'Absolute path to an existing .md file.' },
@@ -163,7 +148,7 @@ export const humanReview = defineLeaf({
         const output = outputArg !== undefined ? outputArg : join(idir, 'feedback.json');
         const rc = { mode: 'review', job_id: jobId, file: abs, output };
         atomicWriteJson(join(idir, 'run.json'), rc);
-        // review is a non-blocking kickoff, exactly like ask/approve: the detached
+        // review is a non-blocking kickoff, exactly like ask: the detached
         // `_run` worker pushes the FeedbackResult as this node's final report when
         // the human submits, which fans into our inbox and wakes us (and is also
         // autosaved to `output`). There is nothing to block on — the doc is live on

package/dist/commands/human/queue.d.ts

@@ -10,12 +10,23 @@
  *  flips status=done). Reconstructs the same pushFinal body `_run` would have
  *  emitted, per mode; a canceled-on-disk response reaps the node without
  *  delivering a result (mirrors `human cancel`). Returns true iff it acted. */
-export declare function finalizeResolvedInteraction(jobId: string): Promise<boolean>;
+export declare function finalizeResolvedInteraction(jobId: string, claim?: InteractionClaim): Promise<boolean>;
 /** Sweep every interaction under the cwd's interactions root and deliver-back +
  *  reap any that are answered-but-undelivered (see finalizeResolvedInteraction).
  *  Interaction dir names ARE the bridge node ids. Returns how many it healed. */
 export declare function healStrandedInteractions(cwd: string): Promise<number>;
 export declare const humanInbox: import("../../core/command.js").LeafDef;
 export declare const humanList: import("../../core/command.js").LeafDef;
+export declare const humanDeck: import("../../core/command.js").LeafDef;
+interface InteractionClaim {
+    release: () => void;
+}
+export declare function acquireInteractionClaim(dir: string, jobId: string, opts?: {
+    allowResolved?: boolean;
+    markProgress?: boolean;
+    respectProgress?: boolean;
+}): InteractionClaim | 'already_resolved' | 'claimed';
+export declare const humanResolve: import("../../core/command.js").LeafDef;
 export declare const humanCancel: import("../../core/command.js").LeafDef;
 export declare const humanRun: import("../../core/command.js").LeafDef;
+export {};