@crouton-kit/crouter 0.2.6 → 0.3.1

package/dist/core/__tests__/argv-parser.test.d.ts

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

package/dist/core/__tests__/argv-parser.test.js

@@ -0,0 +1,199 @@
+// Framework tests for the argv parser and help renderer (inputModel: 'argv').
+// Run with: node --import tsx/esm --test src/core/__tests__/argv-parser.test.ts
+// These tests exercise parseArgv and renderLeafArgv directly — no process.argv
+// mutation, no subprocess spawning.
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseArgv } from '../command.js';
+import { renderLeafArgv } from '../help.js';
+import { defineLeaf } from '../command.js';
+// ---------------------------------------------------------------------------
+// parseArgv — flags
+// ---------------------------------------------------------------------------
+describe('parseArgv: flags', () => {
+    const params = [
+        { kind: 'flag', name: 'plan-id', type: 'string', required: true, constraint: 'Plan id.' },
+        { kind: 'flag', name: 'limit', type: 'int', required: false, constraint: 'Max results.', default: 20 },
+        { kind: 'flag', name: 'follow', type: 'bool', required: false, constraint: 'Stream.' },
+        { kind: 'flag', name: 'status', type: 'enum', choices: ['draft', 'done'], required: false, constraint: 'Filter.' },
+    ];
+    test('parses --flag value form', async () => {
+        const result = await parseArgv(params, ['--plan-id', 'abc123']);
+        assert.equal(result['planId'], 'abc123');
+    });
+    test('parses --flag=value form', async () => {
+        const result = await parseArgv(params, ['--plan-id=abc123']);
+        assert.equal(result['planId'], 'abc123');
+    });
+    test('parses int flag', async () => {
+        const result = await parseArgv(params, ['--plan-id', 'x', '--limit', '42']);
+        assert.equal(result['limit'], 42);
+    });
+    test('rejects non-integer for int flag', async () => {
+        await assert.rejects(() => parseArgv(params, ['--plan-id', 'x', '--limit', 'notanint']), (err) => { assert.match(err.message, /must be an integer/); return true; });
+    });
+    test('bool flag: presence = true', async () => {
+        const result = await parseArgv(params, ['--plan-id', 'x', '--follow']);
+        assert.equal(result['follow'], true);
+    });
+    test('bool flag: absence = default false', async () => {
+        const result = await parseArgv(params, ['--plan-id', 'x']);
+        assert.equal(result['follow'], false);
+    });
+    test('bool flag rejects --flag=value', async () => {
+        await assert.rejects(() => parseArgv(params, ['--plan-id', 'x', '--follow=true']), (err) => { assert.match(err.message, /takes no value/); return true; });
+    });
+    test('enum flag: valid value passes', async () => {
+        const result = await parseArgv(params, ['--plan-id', 'x', '--status', 'draft']);
+        assert.equal(result['status'], 'draft');
+    });
+    test('enum flag: invalid value throws invalid_type', async () => {
+        await assert.rejects(() => parseArgv(params, ['--plan-id', 'x', '--status', 'unknown']), (err) => { assert.match(err.message, /must be one of/); return true; });
+    });
+    test('int flag default applied when absent', async () => {
+        const result = await parseArgv(params, ['--plan-id', 'x']);
+        assert.equal(result['limit'], 20);
+    });
+    test('unknown flag throws unknown_flag', async () => {
+        await assert.rejects(() => parseArgv(params, ['--plan-id', 'x', '--bogus', 'y']), (err) => { assert.match(err.message, /unknown flag/); return true; });
+    });
+    test('missing required flag throws missing_parameter', async () => {
+        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
+    });
+    test('kebab-case flag name becomes camelCase key', async () => {
+        const result = await parseArgv(params, ['--plan-id', 'abc']);
+        assert.ok('planId' in result);
+        assert.ok(!('plan-id' in result));
+    });
+});
+// ---------------------------------------------------------------------------
+// parseArgv — positional
+// ---------------------------------------------------------------------------
+describe('parseArgv: positional', () => {
+    const params = [
+        { kind: 'positional', name: 'job-id', required: true, constraint: 'Job id.' },
+        { kind: 'flag', name: 'follow', type: 'bool', required: false, constraint: '' },
+    ];
+    test('parses single positional before flags', async () => {
+        const result = await parseArgv(params, ['job-abc', '--follow']);
+        assert.equal(result['jobId'], 'job-abc');
+        assert.equal(result['follow'], true);
+    });
+    test('parses single positional after flags', async () => {
+        const result = await parseArgv(params, ['--follow', 'job-abc']);
+        assert.equal(result['jobId'], 'job-abc');
+    });
+    test('parses positional after bare --', async () => {
+        const result = await parseArgv(params, ['--', 'job-abc']);
+        assert.equal(result['jobId'], 'job-abc');
+    });
+    test('two positionals throws bad_invocation', async () => {
+        await assert.rejects(() => parseArgv(params, ['job-abc', 'extra']), (err) => { assert.match(err.message, /unexpected extra positional/); return true; });
+    });
+    test('missing required positional throws missing_parameter', async () => {
+        await assert.rejects(() => parseArgv(params, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
+    });
+    test('positional when none declared throws bad_invocation', async () => {
+        const noPos = [
+            { kind: 'flag', name: 'name', type: 'string', required: false, constraint: '' },
+        ];
+        await assert.rejects(() => parseArgv(noPos, ['somevalue']), (err) => { assert.match(err.message, /takes no positional/); return true; });
+    });
+});
+// ---------------------------------------------------------------------------
+// parseArgv — context-file
+// ---------------------------------------------------------------------------
+describe('parseArgv: context-file', () => {
+    test('unknown --context-file when not declared throws unknown_flag', async () => {
+        const params = [];
+        await assert.rejects(() => parseArgv(params, ['--context-file', '/some/path']), (err) => { assert.match(err.message, /unknown flag: --context-file/); return true; });
+    });
+    test('--context-file missing PATH throws missing_parameter', async () => {
+        const params = [
+            { kind: 'context-file', name: 'context', required: false, constraint: '' },
+        ];
+        await assert.rejects(() => parseArgv(params, ['--context-file']), (err) => { assert.match(err.message, /requires a PATH/); return true; });
+    });
+    test('--context-file with nonexistent file throws invalid_type', async () => {
+        const params = [
+            { kind: 'context-file', name: 'context', required: false, constraint: '' },
+        ];
+        await assert.rejects(() => parseArgv(params, ['--context-file', '/no/such/file/xyz.json']), (err) => { assert.match(err.message, /cannot read file/); return true; });
+    });
+});
+// ---------------------------------------------------------------------------
+// renderLeafArgv — help format
+// ---------------------------------------------------------------------------
+describe('renderLeafArgv: help format', () => {
+    const help = {
+        name: 'task claim',
+        summary: 'claim a draft task and spawn a worker',
+        params: [
+            { kind: 'positional', name: 'task-id', required: true, constraint: 'Task in draft state.' },
+            { kind: 'flag', name: 'worker', type: 'string', required: false, constraint: 'Worker template.' },
+            { kind: 'flag', name: 'follow', type: 'bool', required: false, constraint: 'Stream output.' },
+            { kind: 'context-file', name: 'context', required: false, constraint: 'Extra facts for the worker.', shape: '{key: string}' },
+        ],
+        output: [
+            { name: 'job_id', type: 'string', required: true, constraint: 'Use with crtr job logs.' },
+        ],
+        outputKind: 'object',
+        effects: ['Marks task claimed.'],
+    };
+    test('starts with name: summary', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.startsWith('task claim: claim a draft task and spawn a worker.'));
+    });
+    test('contains Input section', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.includes('Input'));
+    });
+    test('positional shown as TASK_ID', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.includes('TASK-ID'));
+    });
+    test('bool flag shown without VALUE placeholder', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.includes('--follow'));
+        assert.ok(!out.includes('--follow FOLLOW'));
+    });
+    test('string flag shown with VALUE placeholder', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.includes('--worker WORKER'));
+    });
+    test('context-file shown as --context-file PATH', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.includes('--context-file PATH'));
+    });
+    test('contains Output section', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.includes('Output (stdout, JSON)'));
+    });
+    test('contains Effects section', () => {
+        const out = renderLeafArgv(help);
+        assert.ok(out.includes('Effects'));
+        assert.ok(out.includes('Marks task claimed.'));
+    });
+});
+// ---------------------------------------------------------------------------
+// defineLeaf
+// ---------------------------------------------------------------------------
+describe('defineLeaf', () => {
+    test('builds a leaf with the declared params', () => {
+        const leaf = defineLeaf({
+            name: 'test',
+            help: {
+                name: 'test',
+                summary: 'test leaf',
+                params: [],
+                output: [],
+                outputKind: 'object',
+                effects: [],
+            },
+            run: async () => { },
+        });
+        assert.equal(leaf.kind, 'leaf');
+        assert.equal(leaf.name, 'test');
+        assert.deepEqual(leaf.help.params, []);
+    });
+});

package/dist/core/__tests__/flow-leaves.test.d.ts

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

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

@@ -0,0 +1,248 @@
+// 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');
+    });
+});

package/dist/core/__tests__/job.test.d.ts

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