@crouton-kit/crouter 0.2.6 → 0.3.1

package/dist/commands/__tests__/skill.test.js

@@ -0,0 +1,287 @@
+// Tests for the skill subtree argv-model migration.
+// Run with: node --import tsx/esm --test 'src/commands/__tests__/skill.test.ts'
+//
+// Tests exercise leaf param schemas via parseArgv (framework) — no subprocess
+// spawning, no filesystem side-effects from handler logic.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseArgv } from '../../core/command.js';
+// ---------------------------------------------------------------------------
+// Shared flag param sets (mirrors the leaf definitions exactly)
+// ---------------------------------------------------------------------------
+const scopeAllFlag = {
+    kind: 'flag', name: 'scope', type: 'enum',
+    choices: ['user', 'project', 'all'], required: false, constraint: '',
+};
+const scopeWriteFlag = {
+    kind: 'flag', name: 'scope', type: 'enum',
+    choices: ['user', 'project'], required: false, constraint: '',
+};
+const pluginFlag = {
+    kind: 'flag', name: 'plugin', type: 'string', required: false, constraint: '',
+};
+const includeDisabledFlag = {
+    kind: 'flag', name: 'include-disabled', type: 'bool', required: false, constraint: '',
+};
+// ---------------------------------------------------------------------------
+// skill find list
+// ---------------------------------------------------------------------------
+describe('skill find list params', () => {
+    const params = [
+        scopeAllFlag,
+        pluginFlag,
+        includeDisabledFlag,
+        { kind: 'flag', name: 'limit', type: 'int', required: false, default: 50, constraint: '' },
+        { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: '' },
+    ];
+    test('no args: defaults applied', async () => {
+        const r = await parseArgv(params, []);
+        assert.equal(r['includeDisabled'], false);
+        assert.equal(r['limit'], 50);
+        assert.equal(r['scope'], undefined);
+        assert.equal(r['plugin'], undefined);
+        assert.equal(r['cursor'], undefined);
+    });
+    test('--scope user', async () => {
+        const r = await parseArgv(params, ['--scope', 'user']);
+        assert.equal(r['scope'], 'user');
+    });
+    test('--scope invalid rejects', async () => {
+        await assert.rejects(() => parseArgv(params, ['--scope', 'bogus']), (e) => { assert.match(e.message, /must be one of/); return true; });
+    });
+    test('--include-disabled presence = true', async () => {
+        const r = await parseArgv(params, ['--include-disabled']);
+        assert.equal(r['includeDisabled'], true);
+    });
+    test('--include-disabled=value rejects', async () => {
+        await assert.rejects(() => parseArgv(params, ['--include-disabled=yes']), (e) => { assert.match(e.message, /takes no value/); return true; });
+    });
+    test('--limit 100', async () => {
+        const r = await parseArgv(params, ['--limit', '100']);
+        assert.equal(r['limit'], 100);
+    });
+    test('--limit non-integer rejects', async () => {
+        await assert.rejects(() => parseArgv(params, ['--limit', '1.5']), (e) => { assert.match(e.message, /must be an integer/); return true; });
+    });
+    test('--cursor TOKEN', async () => {
+        const r = await parseArgv(params, ['--cursor', 'tok_abc']);
+        assert.equal(r['cursor'], 'tok_abc');
+    });
+    test('--plugin my-plugin', async () => {
+        const r = await parseArgv(params, ['--plugin', 'my-plugin']);
+        assert.equal(r['plugin'], 'my-plugin');
+    });
+});
+// ---------------------------------------------------------------------------
+// skill find search
+// ---------------------------------------------------------------------------
+describe('skill find search params', () => {
+    const params = [
+        { kind: 'positional', name: 'query', required: true, constraint: '' },
+        scopeAllFlag,
+        pluginFlag,
+        includeDisabledFlag,
+        { kind: 'flag', name: 'search-body', type: 'bool', required: false, constraint: '' },
+    ];
+    test('query positional required', async () => {
+        await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
+    });
+    test('query parsed as positional', async () => {
+        const r = await parseArgv(params, ['my topic']);
+        assert.equal(r['query'], 'my topic');
+    });
+    test('query + flags', async () => {
+        const r = await parseArgv(params, ['debugging', '--scope', 'project', '--include-disabled', '--search-body']);
+        assert.equal(r['query'], 'debugging');
+        assert.equal(r['scope'], 'project');
+        assert.equal(r['includeDisabled'], true);
+        assert.equal(r['searchBody'], true);
+    });
+    test('--search-body presence = true, absence = false', async () => {
+        const present = await parseArgv(params, ['q', '--search-body']);
+        assert.equal(present['searchBody'], true);
+        const absent = await parseArgv(params, ['q']);
+        assert.equal(absent['searchBody'], false);
+    });
+    test('--scope all valid', async () => {
+        const r = await parseArgv(params, ['q', '--scope', 'all']);
+        assert.equal(r['scope'], 'all');
+    });
+});
+// ---------------------------------------------------------------------------
+// skill find grep
+// ---------------------------------------------------------------------------
+describe('skill find grep params', () => {
+    const params = [
+        { kind: 'positional', name: 'pattern', required: true, constraint: '' },
+        scopeAllFlag,
+        pluginFlag,
+    ];
+    test('pattern positional required', async () => {
+        await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
+    });
+    test('pattern parsed as positional', async () => {
+        const r = await parseArgv(params, ['foo.*bar']);
+        assert.equal(r['pattern'], 'foo.*bar');
+    });
+    test('pattern + scope + plugin', async () => {
+        const r = await parseArgv(params, ['\\btest\\b', '--scope', 'user', '--plugin', 'myplugin']);
+        assert.equal(r['pattern'], '\\btest\\b');
+        assert.equal(r['scope'], 'user');
+        assert.equal(r['plugin'], 'myplugin');
+    });
+});
+// ---------------------------------------------------------------------------
+// skill read show
+// ---------------------------------------------------------------------------
+describe('skill read show params', () => {
+    const params = [
+        { kind: 'positional', name: 'name', required: true, constraint: '' },
+        scopeWriteFlag,
+        pluginFlag,
+        { kind: 'flag', name: 'frontmatter', type: 'bool', required: false, constraint: '' },
+    ];
+    test('name positional required', async () => {
+        await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
+    });
+    test('name parsed correctly', async () => {
+        const r = await parseArgv(params, ['my-skill']);
+        assert.equal(r['name'], 'my-skill');
+    });
+    test('--frontmatter presence = true', async () => {
+        const r = await parseArgv(params, ['my-skill', '--frontmatter']);
+        assert.equal(r['frontmatter'], true);
+    });
+    test('--frontmatter absent = false', async () => {
+        const r = await parseArgv(params, ['my-skill']);
+        assert.equal(r['frontmatter'], false);
+    });
+    test('--scope rejects all', async () => {
+        await assert.rejects(() => parseArgv(params, ['my-skill', '--scope', 'all']), (e) => { assert.match(e.message, /must be one of/); return true; });
+    });
+    test('--scope user valid', async () => {
+        const r = await parseArgv(params, ['my-skill', '--scope', 'user']);
+        assert.equal(r['scope'], 'user');
+    });
+});
+// ---------------------------------------------------------------------------
+// skill read where
+// ---------------------------------------------------------------------------
+describe('skill read where params', () => {
+    const params = [
+        { kind: 'positional', name: 'name', required: true, constraint: '' },
+        scopeWriteFlag,
+        pluginFlag,
+    ];
+    test('name positional required', async () => {
+        await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
+    });
+    test('name parsed correctly', async () => {
+        const r = await parseArgv(params, ['some/nested/skill']);
+        assert.equal(r['name'], 'some/nested/skill');
+    });
+    test('--scope project valid', async () => {
+        const r = await parseArgv(params, ['skillname', '--scope', 'project']);
+        assert.equal(r['scope'], 'project');
+    });
+});
+// ---------------------------------------------------------------------------
+// skill author guide
+// ---------------------------------------------------------------------------
+describe('skill author guide params', () => {
+    const VALID_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
+    const params = [
+        { kind: 'flag', name: 'type', type: 'enum', choices: VALID_TYPES, required: false, constraint: '' },
+        { kind: 'flag', name: 'topic', type: 'string', required: false, constraint: '' },
+    ];
+    test('no args: both undefined', async () => {
+        const r = await parseArgv(params, []);
+        assert.equal(r['type'], undefined);
+        assert.equal(r['topic'], undefined);
+    });
+    test('--type playbook', async () => {
+        const r = await parseArgv(params, ['--type', 'playbook']);
+        assert.equal(r['type'], 'playbook');
+    });
+    test('--type invalid rejects', async () => {
+        await assert.rejects(() => parseArgv(params, ['--type', 'bogus']), (e) => { assert.match(e.message, /must be one of/); return true; });
+    });
+    test('all valid types accepted', async () => {
+        for (const t of VALID_TYPES) {
+            const r = await parseArgv(params, ['--type', t]);
+            assert.equal(r['type'], t);
+        }
+    });
+    test('--topic string', async () => {
+        const r = await parseArgv(params, ['--topic', 'debugging methodology']);
+        assert.equal(r['topic'], 'debugging methodology');
+    });
+});
+// ---------------------------------------------------------------------------
+// skill author scaffold
+// ---------------------------------------------------------------------------
+describe('skill author scaffold params', () => {
+    const VALID_TYPES = ['playbook', 'primer', 'reference', 'runbook', 'freeform'];
+    const params = [
+        { kind: 'positional', name: 'qualifier', required: true, constraint: '' },
+        { kind: 'flag', name: 'type', type: 'enum', choices: VALID_TYPES, required: false, constraint: '' },
+        { kind: 'flag', name: 'description', type: 'string', required: false, constraint: '' },
+        { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: '' },
+    ];
+    test('qualifier positional required', async () => {
+        await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
+    });
+    test('qualifier parsed correctly', async () => {
+        const r = await parseArgv(params, ['myplugin:myskill']);
+        assert.equal(r['qualifier'], 'myplugin:myskill');
+    });
+    test('full invocation', async () => {
+        const r = await parseArgv(params, [
+            'myplugin:myskill',
+            '--type', 'playbook',
+            '--scope', 'project',
+            '--description', 'Use when debugging',
+        ]);
+        assert.equal(r['qualifier'], 'myplugin:myskill');
+        assert.equal(r['type'], 'playbook');
+        assert.equal(r['scope'], 'project');
+        assert.equal(r['description'], 'Use when debugging');
+    });
+    test('--type invalid rejects', async () => {
+        await assert.rejects(() => parseArgv(params, ['q:s', '--type', 'invalid']), (e) => { assert.match(e.message, /must be one of/); return true; });
+    });
+    test('--scope all rejects', async () => {
+        await assert.rejects(() => parseArgv(params, ['q:s', '--scope', 'all']), (e) => { assert.match(e.message, /must be one of/); return true; });
+    });
+});
+// ---------------------------------------------------------------------------
+// skill state enable / disable
+// ---------------------------------------------------------------------------
+describe('skill state enable/disable params', () => {
+    const params = [
+        { kind: 'positional', name: 'name', required: true, constraint: '' },
+        { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: '' },
+    ];
+    test('name positional required', async () => {
+        await assert.rejects(() => parseArgv(params, []), (e) => { assert.match(e.message, /required parameter is missing/); return true; });
+    });
+    test('name parsed correctly', async () => {
+        const r = await parseArgv(params, ['my-skill']);
+        assert.equal(r['name'], 'my-skill');
+    });
+    test('--scope user', async () => {
+        const r = await parseArgv(params, ['my-skill', '--scope', 'user']);
+        assert.equal(r['scope'], 'user');
+    });
+    test('--scope project', async () => {
+        const r = await parseArgv(params, ['my-skill', '--scope', 'project']);
+        assert.equal(r['scope'], 'project');
+    });
+    test('--scope all rejects', async () => {
+        await assert.rejects(() => parseArgv(params, ['my-skill', '--scope', 'all']), (e) => { assert.match(e.message, /must be one of/); return true; });
+    });
+    test('plugin:skill qualifier as name', async () => {
+        const r = await parseArgv(params, ['myplugin:myskill']);
+        assert.equal(r['name'], 'myplugin:myskill');
+    });
+});

package/dist/commands/debug.d.ts

@@ -0,0 +1,3 @@
+export declare const FLOW_DEBUG_GUIDE = "## Debug workflow \u2014 reproduce first\n\nAudience: the agent that ran `crtr flow debug`. A reproduction agent is\nalready spawned in a sibling pane. It writes ONE failing integration test and\nnever fixes anything. You do everything after: gate on the repro, root-cause,\nfix, verify against that same test.\n\n### Phase 0: Await the repro agent\n\nRun `crtr job read result <job_id> --wait` (10-min budget).\nOn status:\"timeout\": re-issue the wait, or run `crtr job read logs <job_id> --follow`\nuntil the job is terminal.\n\n### Phase 1: Gate on reproduction\n\n`reproduces:true`: read `test_path`, run `test_command` YOURSELF, confirm\nit fails for the stated reason. Do not trust the agent's claim \u2014 if it passes\nor fails differently, treat repro as NOT achieved. This test is the regression\ngate; it stays in the suite after the fix.\n`status:\"failed\"` / `reproduces:false` / your run disproves it: no repro\nharness. Continue, but record \"no reproduction \u2014 fix unverified; do not claim\nverified-fixed.\"\n\n### Phase 2: Reconnaissance\n\nRead the key files yourself \u2014 entry point, failure point, the data flow\nbetween. `git log` / `git blame` near the failure: recent changes are\nhigh-signal.\n\n### Phase 3: Assess difficulty, scale investigators\n\nSimple \u2192 solo (Explore subagents for tracing if the area is large).\nMedium \u2192 2\u20133 parallel `devcore:senior-advisor`: data-flow tracer, assumption\nauditor, change investigator.\nHard (intermittent, races, \"been stuck\", many modules) \u2192 3\u20135 parallel:\nend-to-end tracer, assumption breaker, git archaeologist, boundary inspector.\nGive investigators file paths, observed behavior, and concrete tasks \u2014 never\nyour hypotheses. Challenge theories against each other; the one that survives\ndisconfirmation wins.\n\n### Phase 4: Fix\n\nMinimal root-cause fix. No scope expansion, no drive-by refactor.\n\n### Phase 5: Verify\n\nRe-run `test_command`: it MUST now pass. Run the broader suite for\nregressions. If there was no repro test, state the fix is unverified by\nreproduction and recommend explicit manual verification.\n\n### Phase 6: Report\n\nRoot cause (exact line + why), evidence, the now-passing repro test path,\nconfidence (High/Medium/Low; if not High, name what is uncertain).\n\n### Constraints\n\nThe repro test is the regression guard \u2014 it stays; a fix-agent must never\nweaken it. Investigators run in forked contexts; they return summaries, not\nraw output. No code changes during Phases 2\u20133 except the repro test.";
+import type { LeafDef } from '../core/command.js';
+export declare function registerDebug(): LeafDef;

package/dist/commands/debug.js

@@ -0,0 +1,179 @@
+// `crtr flow debug` leaf — reproduce-first root-cause workflow.
+//
+// Running it spawns a reproduction-only agent in a sibling tmux pane (the same
+// spawn + job-handle shape as `crtr job start prompt`) and returns a job handle
+// plus a follow_up. The orchestrator-side methodology lives in FLOW_DEBUG_GUIDE
+// (the leaf's help.guide), loaded via `crtr flow debug -h` after the repro
+// agent returns. Methodology stays in the CLI guide field, like PLAN_NEW_GUIDE;
+// no builtin skill.
+export const FLOW_DEBUG_GUIDE = `## Debug workflow — reproduce first
+
+Audience: the agent that ran \`crtr flow debug\`. A reproduction agent is
+already spawned in a sibling pane. It writes ONE failing integration test and
+never fixes anything. You do everything after: gate on the repro, root-cause,
+fix, verify against that same test.
+
+### Phase 0: Await the repro agent
+
+Run \`crtr job read result <job_id> --wait\` (10-min budget).
+On status:"timeout": re-issue the wait, or run \`crtr job read logs <job_id> --follow\`
+until the job is terminal.
+
+### Phase 1: Gate on reproduction
+
+\`reproduces:true\`: read \`test_path\`, run \`test_command\` YOURSELF, confirm
+it fails for the stated reason. Do not trust the agent's claim — if it passes
+or fails differently, treat repro as NOT achieved. This test is the regression
+gate; it stays in the suite after the fix.
+\`status:"failed"\` / \`reproduces:false\` / your run disproves it: no repro
+harness. Continue, but record "no reproduction — fix unverified; do not claim
+verified-fixed."
+
+### Phase 2: Reconnaissance
+
+Read the key files yourself — entry point, failure point, the data flow
+between. \`git log\` / \`git blame\` near the failure: recent changes are
+high-signal.
+
+### Phase 3: Assess difficulty, scale investigators
+
+Simple → solo (Explore subagents for tracing if the area is large).
+Medium → 2–3 parallel \`devcore:senior-advisor\`: data-flow tracer, assumption
+auditor, change investigator.
+Hard (intermittent, races, "been stuck", many modules) → 3–5 parallel:
+end-to-end tracer, assumption breaker, git archaeologist, boundary inspector.
+Give investigators file paths, observed behavior, and concrete tasks — never
+your hypotheses. Challenge theories against each other; the one that survives
+disconfirmation wins.
+
+### Phase 4: Fix
+
+Minimal root-cause fix. No scope expansion, no drive-by refactor.
+
+### Phase 5: Verify
+
+Re-run \`test_command\`: it MUST now pass. Run the broader suite for
+regressions. If there was no repro test, state the fix is unverified by
+reproduction and recommend explicit manual verification.
+
+### Phase 6: Report
+
+Root cause (exact line + why), evidence, the now-passing repro test path,
+confidence (High/Medium/Low; if not High, name what is uncertain).
+
+### Constraints
+
+The repro test is the regression guard — it stays; a fix-agent must never
+weaken it. Investigators run in forked contexts; they return summaries, not
+raw output. No code changes during Phases 2–3 except the repro test.`;
+import { defineLeaf } from '../core/command.js';
+import { InputError } from '../core/io.js';
+import { createJob, appendEvent } from '../core/jobs.js';
+import { spawnAgent, isInTmux } from '../core/spawn.js';
+import { readConfig } from '../core/config.js';
+import { reproHandoffPrompt } from '../prompts/debug.js';
+// Inlined from job.ts (module-private there; not exported, per the no-shim
+// convention). Same forms.
+function resolveMaxPanes() {
+    const cfg = readConfig('user');
+    return cfg.max_panes_per_window;
+}
+function assertTmux() {
+    if (!isInTmux()) {
+        throw new InputError({
+            error: 'not_in_tmux',
+            message: 'crtr flow debug requires tmux (TMUX env var not set).',
+            next: 'Run inside a tmux session.',
+        });
+    }
+}
+export function registerDebug() {
+    return defineLeaf({
+        name: 'debug',
+        help: {
+            name: 'flow debug',
+            summary: 'reproduce-first root-cause workflow: spawns a reproduction agent, then you root-cause and fix',
+            guide: FLOW_DEBUG_GUIDE,
+            params: [
+                {
+                    kind: 'stdin',
+                    name: 'steps_to_reproduce',
+                    required: true,
+                    constraint: 'Prose describing how to reproduce the failure. Pipe on stdin.',
+                },
+                {
+                    kind: 'flag',
+                    name: 'summary',
+                    type: 'string',
+                    required: true,
+                    constraint: 'One paragraph summary of the failure: symptom, where observed, expected vs actual.',
+                },
+                {
+                    kind: 'flag',
+                    name: 'cwd',
+                    type: 'path',
+                    required: false,
+                    constraint: 'Working directory for the spawned agent. Defaults to process.cwd().',
+                },
+            ],
+            output: [
+                {
+                    name: 'job_id',
+                    type: 'string',
+                    required: true,
+                    constraint: 'Use with `job read status`, `job read logs`, `job read result`, `job cancel`.',
+                },
+                {
+                    name: 'follow_up',
+                    type: 'string',
+                    required: true,
+                    constraint: 'Recommended next call.',
+                },
+            ],
+            outputKind: 'object',
+            effects: [
+                'Spawns a reproduction agent in a sibling tmux pane.',
+                'Creates a job entry at $XDG_STATE_HOME/crtr/jobs/<job_id>/.',
+                'On completion, result writes atomically to result.json.',
+            ],
+        },
+        run: async (input) => {
+            assertTmux();
+            const stepsToReproduce = input['steps_to_reproduce'];
+            const summary = input['summary'];
+            const cwd = input['cwd'] ?? process.cwd();
+            const issue = `${summary}\n\n${stepsToReproduce}`;
+            const { jobId } = createJob('debug-repro', { cwd });
+            const result = spawnAgent({
+                prompt: reproHandoffPrompt(issue, jobId),
+                cwd,
+                jobId,
+                maxPanesPerWindow: resolveMaxPanes(),
+            });
+            if (result.status === 'not-in-tmux') {
+                throw new InputError({
+                    error: 'not_in_tmux',
+                    message: result.message,
+                    next: 'Run inside a tmux session.',
+                });
+            }
+            if (result.status === 'spawn-failed') {
+                throw new InputError({
+                    error: 'spawn_failed',
+                    message: result.message,
+                    next: 'Check tmux is running and try again.',
+                });
+            }
+            const paneLabel = result.paneId !== undefined ? result.paneId : 'unknown';
+            appendEvent(jobId, {
+                level: 'info',
+                event: 'worker_started',
+                message: `repro pane ${paneLabel} spawned`,
+            });
+            return {
+                job_id: jobId,
+                follow_up: `Await the reproduction agent: crtr job read result ${jobId} --wait. Then run \`crtr flow debug -h\` and follow the workflow from Phase 1.`,
+            };
+        },
+    });
+}

package/dist/commands/flow.d.ts

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

package/dist/commands/flow.js

@@ -0,0 +1,24 @@
+// `crtr flow` umbrella — groups the spec → plan → debug development process.
+// registerSpec/registerPlan are unchanged (each still defineBranch{name}); they
+// nest under `flow` here instead of registering at root. registerDebug is a
+// leaf — `crtr flow debug` spawns directly and `-h` prints FLOW_DEBUG_GUIDE.
+import { defineBranch } from '../core/command.js';
+import { registerSpec } from './spec.js';
+import { registerPlan } from './plan.js';
+import { registerDebug } from './debug.js';
+export function registerFlow() {
+    return defineBranch({
+        name: 'flow',
+        help: {
+            name: 'flow',
+            summary: 'the spec → plan → debug development process',
+            model: 'spec captures requirements; plan decomposes them; debug root-causes failures reproduce-first.',
+            children: [
+                { name: 'spec', desc: 'create, read, list specifications', useWhen: 'capturing requirements before planning' },
+                { name: 'plan', desc: 'create, read, list plans', useWhen: 'shaping or inspecting work' },
+                { name: 'debug', desc: 'reproduce-first root-cause workflow', useWhen: 'a bug, test failure, or unexpected behavior needs root-causing' },
+            ],
+        },
+        children: [registerSpec(), registerPlan(), registerDebug()],
+    });
+}

package/dist/commands/human.d.ts

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