@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/commands/spec.d.ts

@@ -1,3 +0,0 @@
-export declare const SPEC_NEW_GUIDE = "## Spec workflow\n\nBuild and save a design + requirements spec: a document describing what to\nbuild, the shape of the solution, and the behaviors it must satisfy. A spec is\nupstream of a plan \u2014 it captures decisions, not implementation steps.\n\nAnti-pattern: do not fish for clarifications upfront. Draft a concrete spec\nfirst based on your investigation, then iterate. A specific draft the user can\nreact to converges faster than a list of questions in a vacuum.\n\n### Phase 1: Shape\n\nBuild a comprehensive picture of the problem and the relevant code. Surface\nexisting patterns, constraints, and prior decisions.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for narrow, well-scoped problems; use more when the spec\ntouches several subsystems or you need to compare existing implementations.\nQuality over quantity \u2014 3 agents maximum.\n\nAfter exploration, draft a high-level design: the shape of the solution, new or\nchanged pieces, the boundaries.\n\n### Phase 2: Requirements\n\nTranslate the shape into concrete behavioral requirements. Each requirement\nmust be:\n\n- Testable \u2014 has a clear pass/fail condition.\n- Behavior-focused \u2014 describes what the system does, not how.\n- Scoped \u2014 covers one observable behavior.\n\nGroup requirements by capability. Plain English is fine. For conditional or\nstateful behaviors, EARS templates sharpen phrasing:\n`When <trigger>, the system shall <behavior>` or\n`If <condition>, then the system shall <response>`.\n\nFor larger / multi-component designs, walk the design end-to-end: at each step\nfrom trigger to final state, verify preconditions, state, failure handling, and\nhandoffs between components are specified. Skip this for small self-contained\nspecs.\n\n### Phase 3: Deepen\n\nRead the critical files identified during Phase 1. Reconcile requirements\nagainst the shape \u2014 if a requirement reveals a gap in the design, refine the\ndesign before saving.\n\nUse AskUserQuestion ONLY to clarify requirements or choose between approaches.\nNever use it to ask \"is this spec okay?\" or \"should I save?\".\n\n### Phase 4: Compose the spec body\n\nRequired sections:\n\n  # Spec: <one-line title>\n\n  ## Context\n  <the problem this spec addresses, what motivates it, and the intended outcome.\n  Include relevant constraints \u2014 user goals, stakeholders, deadlines.>\n\n  ## Design\n  <the shape of the solution. Components, data flow, key decisions and why they\n  were chosen. Reference existing code with `file_path:line_number`.>\n\n  ## Requirements\n  <grouped behavioral requirements. Each one testable. Plain English is fine.>\n\n  ### <Capability A>\n  - <one observable behavior>\n\n  ### <Capability B>\n  - ...\n\n  ## Out of scope\n  <things explicitly NOT covered, so the next reader knows where the edges are.>\n\n  ## Open questions\n  <anything you could not resolve. Empty if all decisions are pinned.>\n\n### Phase 5: Save\n\nRun `crtr agent spec new`:\n\n  echo '<spec markdown>' | crtr agent spec new <kebab-case-name>\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/refresh-tokens`).\n- Pipe the full spec markdown composed in Phase 4 on stdin.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Done\n\nAfter the reviewer approves the spec, your turn ends. Do not summarize in chat.\nFor a human gate, optionally run `crtr human review` on the spec for anchored\ncomments and `crtr human approve` to gate the handoff \u2014 this complements, not\nreplaces, `crtr agent new reviewer`.\nIf the user is ready to plan, ask once whether to hand off; if yes, follow the\n`follow_up` instructions from the save output.";
-import type { BranchDef } from '../core/command.js';
-export declare function registerSpec(): BranchDef;

package/dist/commands/spec.js

@@ -1,286 +0,0 @@
-// `crtr agent spec` subtree — spec new / show / list handlers.
-export const SPEC_NEW_GUIDE = `## Spec workflow
-
-Build and save a design + requirements spec: a document describing what to
-build, the shape of the solution, and the behaviors it must satisfy. A spec is
-upstream of a plan — it captures decisions, not implementation steps.
-
-Anti-pattern: do not fish for clarifications upfront. Draft a concrete spec
-first based on your investigation, then iterate. A specific draft the user can
-react to converges faster than a list of questions in a vacuum.
-
-### Phase 1: Shape
-
-Build a comprehensive picture of the problem and the relevant code. Surface
-existing patterns, constraints, and prior decisions.
-
-Launch up to 3 Explore subagents IN PARALLEL (single message, multiple tool
-calls). Use 1 agent for narrow, well-scoped problems; use more when the spec
-touches several subsystems or you need to compare existing implementations.
-Quality over quantity — 3 agents maximum.
-
-After exploration, draft a high-level design: the shape of the solution, new or
-changed pieces, the boundaries.
-
-### Phase 2: Requirements
-
-Translate the shape into concrete behavioral requirements. Each requirement
-must be:
-
-- Testable — has a clear pass/fail condition.
-- Behavior-focused — describes what the system does, not how.
-- Scoped — covers one observable behavior.
-
-Group requirements by capability. Plain English is fine. For conditional or
-stateful behaviors, EARS templates sharpen phrasing:
-\`When <trigger>, the system shall <behavior>\` or
-\`If <condition>, then the system shall <response>\`.
-
-For larger / multi-component designs, walk the design end-to-end: at each step
-from trigger to final state, verify preconditions, state, failure handling, and
-handoffs between components are specified. Skip this for small self-contained
-specs.
-
-### Phase 3: Deepen
-
-Read the critical files identified during Phase 1. Reconcile requirements
-against the shape — if a requirement reveals a gap in the design, refine the
-design before saving.
-
-Use AskUserQuestion ONLY to clarify requirements or choose between approaches.
-Never use it to ask "is this spec okay?" or "should I save?".
-
-### Phase 4: Compose the spec body
-
-Required sections:
-
-  # Spec: <one-line title>
-
-  ## Context
-  <the problem this spec addresses, what motivates it, and the intended outcome.
-  Include relevant constraints — user goals, stakeholders, deadlines.>
-
-  ## Design
-  <the shape of the solution. Components, data flow, key decisions and why they
-  were chosen. Reference existing code with \`file_path:line_number\`.>
-
-  ## Requirements
-  <grouped behavioral requirements. Each one testable. Plain English is fine.>
-
-  ### <Capability A>
-  - <one observable behavior>
-
-  ### <Capability B>
-  - ...
-
-  ## Out of scope
-  <things explicitly NOT covered, so the next reader knows where the edges are.>
-
-  ## Open questions
-  <anything you could not resolve. Empty if all decisions are pinned.>
-
-### Phase 5: Save
-
-Run \`crtr agent spec new\`:
-
-  echo '<spec markdown>' | crtr agent spec new <kebab-case-name>
-
-- NAME: short kebab-case slug. Nested names become subdirectories
-  (e.g. \`auth/refresh-tokens\`).
-- Pipe the full spec markdown composed in Phase 4 on stdin.
-
-Output: \`{path, follow_up}\`. The \`follow_up\` field names the exact next call
-— run it.
-
-### Phase 6: Done
-
-After the reviewer approves the spec, your turn ends. Do not summarize in chat.
-For a human gate, optionally run \`crtr human review\` on the spec for anchored
-comments and \`crtr human approve\` to gate the handoff — this complements, not
-replaces, \`crtr agent new reviewer\`.
-If the user is ready to plan, ask once whether to hand off; if yes, follow the
-\`follow_up\` instructions from the save output.`;
-import { defineBranch, defineLeaf } from '../core/command.js';
-import { saveArtifact, readArtifact, listArtifacts, OVERSIZE_WARN_LINES } from '../core/artifact.js';
-import { paginate } from '../core/pagination.js';
-export function registerSpec() {
-    const specNew = defineLeaf({
-        name: 'new',
-        help: {
-            name: 'agent spec new',
-            summary: 'draft a specification artifact from intent',
-            guide: SPEC_NEW_GUIDE,
-            params: [
-                {
-                    kind: 'positional',
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Kebab-case slug used as the artifact filename. No spaces; use hyphens.',
-                },
-                {
-                    kind: 'stdin',
-                    name: 'body',
-                    required: true,
-                    constraint: 'Full specification prose. Treated as ground truth for downstream planning.',
-                },
-            ],
-            output: [
-                {
-                    name: 'path',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Absolute path to the written spec artifact.',
-                },
-                {
-                    name: 'follow_up',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Recommended next call (planner spawn via `crtr agent new planner`).',
-                },
-            ],
-            outputKind: 'object',
-            effects: ['Writes a spec artifact to the specs artifact directory.'],
-        },
-        run: async (input) => {
-            const name = input['name'];
-            const body = input['body'];
-            const { path, oversize, lineCount } = saveArtifact('specs', name, body);
-            let follow_up = `Plan it: crtr agent new planner ${path} (returns {job_id}), then crtr job read result <job_id> --wait.`;
-            follow_up +=
-                ` Optional human gate before planning (complements, does not replace \`crtr agent new reviewer\`): crtr human review --file ${path} for anchored comments, then gate with crtr human approve --title "Approve this spec?".`;
-            if (oversize) {
-                follow_up +=
-                    ` OVERSIZE ADVISORY: this spec is ${lineCount} lines (> ${OVERSIZE_WARN_LINES}). Split into focused sub-specs before planning.`;
-            }
-            return { path, follow_up };
-        },
-    });
-    const specShow = defineLeaf({
-        name: 'show',
-        help: {
-            name: 'agent spec show',
-            summary: 'read a spec artifact by name',
-            params: [
-                {
-                    kind: 'positional',
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Exact artifact name (no path extension). Use `spec list` to enumerate.',
-                },
-            ],
-            output: [
-                {
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Artifact name as stored.',
-                },
-                {
-                    name: 'path',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Absolute path to the artifact file.',
-                },
-                {
-                    name: 'body',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Full spec body text.',
-                },
-            ],
-            outputKind: 'object',
-            effects: ['None. Read-only.'],
-        },
-        run: async (input) => {
-            const name = input['name'];
-            const record = readArtifact('specs', name);
-            return { name: record.name, path: record.path, body: record.body };
-        },
-    });
-    const specList = defineLeaf({
-        name: 'list',
-        help: {
-            name: 'agent spec list',
-            summary: 'paginated list of spec artifacts, sorted ascending by name',
-            params: [
-                {
-                    kind: 'flag',
-                    name: 'scope',
-                    type: 'enum',
-                    choices: ['user', 'project', 'all'],
-                    required: false,
-                    constraint: 'Filter by scope. Omit to list all.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'limit',
-                    type: 'int',
-                    required: false,
-                    default: 20,
-                    constraint: 'Default 20, max 100.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'cursor',
-                    type: 'string',
-                    required: false,
-                    constraint: "Opaque token from a previous response's next_cursor. Omit on first call.",
-                },
-            ],
-            output: [
-                {
-                    name: 'items',
-                    type: 'object[]',
-                    required: true,
-                    constraint: 'Each: {name, path, updated_at}. Sorted ascending by name.',
-                },
-                {
-                    name: 'next_cursor',
-                    type: 'string | null',
-                    required: true,
-                    constraint: 'Pass on the next call to continue. null means no more items.',
-                },
-                {
-                    name: 'total',
-                    type: 'integer | null',
-                    required: true,
-                    constraint: 'Total specs matching the query. Exact when cheap; null on large/filtered sets — do not retry to force it.',
-                },
-            ],
-            outputKind: 'object',
-            effects: ['None. Read-only.'],
-        },
-        run: async (input) => {
-            const limit = input['limit'] ?? 20;
-            const cursor = input['cursor'];
-            const all = listArtifacts('specs');
-            const result = paginate(all, { limit, cursor }, {
-                defaultLimit: 20,
-                maxLimit: 100,
-                keyOf: (item) => item.name,
-                total: 'count',
-            });
-            return {
-                items: result.items,
-                next_cursor: result.next_cursor,
-                total: result.total,
-            };
-        },
-    });
-    return defineBranch({
-        name: 'spec',
-        help: {
-            name: 'agent spec',
-            summary: 'create and read specification artifacts',
-            model: 'Lifecycle: draft -> approved. Approved specs drive plan creation.',
-            children: [
-                { name: 'new', desc: 'draft a spec from intent', useWhen: 'capturing requirements before planning' },
-                { name: 'show', desc: 'read a spec by name', useWhen: 'reasoning about an existing spec' },
-                { name: 'list', desc: 'enumerate specs', useWhen: 'discovering what specs exist' },
-            ],
-        },
-        children: [specNew, specShow, specList],
-    });
-}

package/dist/core/__tests__/flow-leaves.test.js

@@ -1,248 +0,0 @@
-// Tests for flow subtree leaves (spec new/show/list, plan new/show/list, debug).
-// Exercises the argv parsing path for each leaf via parseArgv and verifies
-// help.params structure (not help.input).
-//
-// Run with: node --import tsx/esm --test src/core/__tests__/flow-leaves.test.ts
-import { test, describe } from 'node:test';
-import assert from 'node:assert/strict';
-import { parseArgv } from '../command.js';
-import { renderLeafArgv } from '../help.js';
-import { registerSpec } from '../../commands/spec.js';
-import { registerPlan } from '../../commands/plan.js';
-import { registerDebug } from '../../commands/debug.js';
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-function getLeaf(branch, name) {
-    const leaf = branch.children.find((c) => c.name === name);
-    assert.ok(leaf !== undefined, `leaf '${name}' not found in branch`);
-    assert.equal(leaf.kind, 'leaf');
-    return leaf;
-}
-// ---------------------------------------------------------------------------
-// spec new
-// ---------------------------------------------------------------------------
-describe('spec new: argv model', () => {
-    const specBranch = registerSpec();
-    const leaf = getLeaf(specBranch, 'new');
-    test('help.params defined', () => {
-        assert.ok(leaf.help.params !== undefined);
-    });
-    test('has positional name param', () => {
-        const pos = leaf.help.params.find((p) => p.kind === 'positional' && p.name === 'name');
-        assert.ok(pos !== undefined);
-        assert.equal(pos.required, true);
-    });
-    test('has stdin body param', () => {
-        const stdin = leaf.help.params.find((p) => p.kind === 'stdin' && p.name === 'body');
-        assert.ok(stdin !== undefined);
-        assert.equal(stdin.required, true);
-    });
-    test('parseArgv: positional name parsed correctly', async () => {
-        const params = leaf.help.params;
-        // Remove stdin param for parse-only test (stdin reads from process.stdin)
-        const noStdin = params.filter((p) => p.kind !== 'stdin');
-        const result = await parseArgv(noStdin, ['my-spec-name']);
-        assert.equal(result['name'], 'my-spec-name');
-    });
-    test('parseArgv: missing required positional throws', async () => {
-        const params = leaf.help.params.filter((p) => p.kind !== 'stdin');
-        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('renderLeafArgv renders Input section with positional', () => {
-        const out = renderLeafArgv(leaf.help);
-        assert.ok(out.includes('Input'));
-        assert.ok(out.includes('NAME'));
-        assert.ok(out.includes('stdin'));
-    });
-});
-// ---------------------------------------------------------------------------
-// spec show
-// ---------------------------------------------------------------------------
-describe('spec show: argv model', () => {
-    const specBranch = registerSpec();
-    const leaf = getLeaf(specBranch, 'show');
-    test('help.params defined', () => {
-        assert.ok(leaf.help.params !== undefined);
-    });
-    test('parseArgv: positional name', async () => {
-        const result = await parseArgv(leaf.help.params, ['my-spec']);
-        assert.equal(result['name'], 'my-spec');
-    });
-    test('parseArgv: rejects unknown flag', async () => {
-        await assert.rejects(() => parseArgv(leaf.help.params, ['my-spec', '--bogus']), (err) => { assert.match(err.message, /unknown flag/); return true; });
-    });
-});
-// ---------------------------------------------------------------------------
-// spec list
-// ---------------------------------------------------------------------------
-describe('spec list: argv model', () => {
-    const specBranch = registerSpec();
-    const leaf = getLeaf(specBranch, 'list');
-    test('help.params defined', () => {
-        assert.ok(leaf.help.params !== undefined);
-    });
-    test('has --scope enum flag', () => {
-        const flag = leaf.help.params.find((p) => p.kind === 'flag' && p.name === 'scope');
-        assert.ok(flag !== undefined);
-        assert.equal(flag.kind, 'flag');
-        if (flag.kind === 'flag') {
-            assert.equal(flag.type, 'enum');
-            assert.deepEqual(flag.choices, ['user', 'project', 'all']);
-        }
-    });
-    test('has --limit int flag with default 20', () => {
-        const flag = leaf.help.params.find((p) => p.kind === 'flag' && p.name === 'limit');
-        assert.ok(flag !== undefined);
-        assert.equal(flag.kind, 'flag');
-        if (flag.kind === 'flag') {
-            assert.equal(flag.type, 'int');
-            assert.equal(flag.default, 20);
-        }
-    });
-    test('has --cursor string flag', () => {
-        const flag = leaf.help.params.find((p) => p.kind === 'flag' && p.name === 'cursor');
-        assert.ok(flag !== undefined);
-    });
-    test('parseArgv: --limit 50 parses as integer', async () => {
-        const result = await parseArgv(leaf.help.params, ['--limit', '50']);
-        assert.equal(result['limit'], 50);
-    });
-    test('parseArgv: --scope user parses', async () => {
-        const result = await parseArgv(leaf.help.params, ['--scope', 'user']);
-        assert.equal(result['scope'], 'user');
-    });
-    test('parseArgv: --scope invalid throws', async () => {
-        await assert.rejects(() => parseArgv(leaf.help.params, ['--scope', 'invalid']), (err) => { assert.match(err.message, /must be one of/); return true; });
-    });
-    test('parseArgv: default limit applied when absent', async () => {
-        const result = await parseArgv(leaf.help.params, []);
-        assert.equal(result['limit'], 20);
-    });
-    test('parseArgv: --cursor token', async () => {
-        const result = await parseArgv(leaf.help.params, ['--cursor', 'tok123']);
-        assert.equal(result['cursor'], 'tok123');
-    });
-});
-// ---------------------------------------------------------------------------
-// plan new
-// ---------------------------------------------------------------------------
-describe('plan new: argv model', () => {
-    const planBranch = registerPlan();
-    const leaf = getLeaf(planBranch, 'new');
-    test('help.params defined', () => {
-        assert.ok(leaf.help.params !== undefined);
-    });
-    test('has positional name param', () => {
-        const pos = leaf.help.params.find((p) => p.kind === 'positional' && p.name === 'name');
-        assert.ok(pos !== undefined);
-        assert.equal(pos.required, true);
-    });
-    test('has stdin body param', () => {
-        const stdin = leaf.help.params.find((p) => p.kind === 'stdin' && p.name === 'body');
-        assert.ok(stdin !== undefined);
-        assert.equal(stdin.required, true);
-    });
-    test('has optional --spec flag', () => {
-        const flag = leaf.help.params.find((p) => p.kind === 'flag' && p.name === 'spec');
-        assert.ok(flag !== undefined);
-        assert.equal(flag.required, false);
-    });
-    test('parseArgv: positional name and --spec flag', async () => {
-        const params = leaf.help.params.filter((p) => p.kind !== 'stdin');
-        const result = await parseArgv(params, ['my-plan', '--spec', 'my-spec']);
-        assert.equal(result['name'], 'my-plan');
-        assert.equal(result['spec'], 'my-spec');
-    });
-    test('parseArgv: positional name without --spec', async () => {
-        const params = leaf.help.params.filter((p) => p.kind !== 'stdin');
-        const result = await parseArgv(params, ['my-plan']);
-        assert.equal(result['name'], 'my-plan');
-        assert.equal(result['spec'], undefined);
-    });
-});
-// ---------------------------------------------------------------------------
-// plan show
-// ---------------------------------------------------------------------------
-describe('plan show: argv model', () => {
-    const planBranch = registerPlan();
-    const leaf = getLeaf(planBranch, 'show');
-    test('help.params defined', () => {
-        assert.ok(leaf.help.params !== undefined);
-    });
-    test('parseArgv: positional name', async () => {
-        const result = await parseArgv(leaf.help.params, ['my-plan']);
-        assert.equal(result['name'], 'my-plan');
-    });
-});
-// ---------------------------------------------------------------------------
-// plan list
-// ---------------------------------------------------------------------------
-describe('plan list: argv model', () => {
-    const planBranch = registerPlan();
-    const leaf = getLeaf(planBranch, 'list');
-    test('help.params defined', () => {
-        assert.ok(leaf.help.params !== undefined);
-    });
-    test('has --scope, --limit, --cursor flags', () => {
-        const names = leaf.help.params.map((p) => p.name);
-        assert.ok(names.includes('scope'));
-        assert.ok(names.includes('limit'));
-        assert.ok(names.includes('cursor'));
-    });
-    test('parseArgv: --limit 10 --cursor abc', async () => {
-        const result = await parseArgv(leaf.help.params, ['--limit', '10', '--cursor', 'abc']);
-        assert.equal(result['limit'], 10);
-        assert.equal(result['cursor'], 'abc');
-    });
-});
-// ---------------------------------------------------------------------------
-// debug
-// ---------------------------------------------------------------------------
-describe('debug: argv model', () => {
-    const leaf = registerDebug();
-    test('help.params defined', () => {
-        assert.ok(leaf.help.params !== undefined);
-    });
-    test('has stdin steps_to_reproduce param', () => {
-        const stdin = leaf.help.params.find((p) => p.kind === 'stdin' && p.name === 'steps_to_reproduce');
-        assert.ok(stdin !== undefined);
-        assert.equal(stdin.required, true);
-    });
-    test('has required --summary flag', () => {
-        const flag = leaf.help.params.find((p) => p.kind === 'flag' && p.name === 'summary');
-        assert.ok(flag !== undefined);
-        assert.equal(flag.required, true);
-        if (flag.kind === 'flag')
-            assert.equal(flag.type, 'string');
-    });
-    test('has optional --cwd flag of type path', () => {
-        const flag = leaf.help.params.find((p) => p.kind === 'flag' && p.name === 'cwd');
-        assert.ok(flag !== undefined);
-        assert.equal(flag.required, false);
-        if (flag.kind === 'flag')
-            assert.equal(flag.type, 'path');
-    });
-    test('parseArgv: --summary and --cwd flags (no stdin)', async () => {
-        const params = leaf.help.params.filter((p) => p.kind !== 'stdin');
-        const result = await parseArgv(params, ['--summary', 'test fails on startup', '--cwd', '/tmp/project']);
-        assert.equal(result['summary'], 'test fails on startup');
-        assert.equal(result['cwd'], '/tmp/project');
-    });
-    test('parseArgv: missing required --summary throws', async () => {
-        const params = leaf.help.params.filter((p) => p.kind !== 'stdin');
-        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('renderLeafArgv renders --summary and stdin', () => {
-        const out = renderLeafArgv(leaf.help);
-        assert.ok(out.includes('--summary'));
-        assert.ok(out.includes('stdin'));
-        assert.ok(out.includes('--cwd'));
-    });
-    test('stdin name is steps_to_reproduce (underscores, no camelCase transform)', () => {
-        // flagNameToKey only converts hyphen segments; underscores are passed through.
-        // The handler reads input['steps_to_reproduce'], not input['stepsToReproduce'].
-        const stdin = leaf.help.params.find((p) => p.kind === 'stdin');
-        assert.equal(stdin?.name, 'steps_to_reproduce');
-    });
-});