@crouton-kit/crouter 0.3.8 → 0.3.12

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

@@ -1,310 +0,0 @@
-// Tests for the job subtree (monitoring) and agent new * (spawning) argv
-// migration. Exercises parseArgv against each leaf's param schema directly —
-// no subprocess, no tmux, no filesystem side-effects from the handler.
-//
-// Run with: node --import tsx/esm --test src/core/__tests__/job.test.ts
-import { test, describe } from 'node:test';
-import assert from 'node:assert/strict';
-import { parseArgv } from '../command.js';
-// ---------------------------------------------------------------------------
-// Param schemas extracted from each leaf (mirrors job.ts exactly)
-// ---------------------------------------------------------------------------
-const startPromptParams = [
-    { kind: 'stdin', name: 'prompt', required: true, constraint: '' },
-    { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: '' },
-];
-const startForkParams = [
-    { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: '' },
-];
-const startPlannerParams = [
-    { kind: 'positional', name: 'spec_path', type: 'path', required: true, constraint: '' },
-    { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: '' },
-];
-const startImplementerParams = [
-    { kind: 'positional', name: 'plan_path', type: 'path', required: true, constraint: '' },
-    { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: '' },
-];
-const startReviewerParams = [
-    { kind: 'positional', name: 'artifact_path', type: 'path', required: true, constraint: '' },
-    { kind: 'flag', name: 'kind', type: 'enum', choices: ['plan', 'spec'], required: true, constraint: '' },
-    { kind: 'flag', name: 'spec-path', type: 'path', required: false, constraint: '' },
-    { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: '' },
-];
-const readListParams = [
-    { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: '' },
-    { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: '' },
-];
-const readStatusParams = [
-    { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
-];
-const readResultParams = [
-    { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
-    { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: '' },
-];
-const readLogsParams = [
-    { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
-    { kind: 'flag', name: 'since', type: 'string', required: false, constraint: '' },
-    { kind: 'flag', name: 'until', type: 'string', required: false, constraint: '' },
-    { kind: 'flag', name: 'level', type: 'enum', choices: ['debug', 'info', 'warn', 'error'], required: false, default: 'info', constraint: '' },
-    { kind: 'flag', name: 'follow', type: 'bool', required: false, constraint: '' },
-];
-// NOTE: the real leaf also declares a `stdin` param for `body`. We omit it
-// from the test schema because parseArgv reads stdin to EOF whenever a stdin
-// param is declared — and under `node --test`, stdin is piped with no EOF, so
-// the call hangs forever. The body-required-on-status=done check lives in the
-// leaf's `run` handler, not in parseArgv, so the schema tests below cover
-// everything parseArgv can see without needing stdin.
-const submitParams = [
-    { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
-    { kind: 'flag', name: 'status', type: 'enum', choices: ['done', 'failed'], required: false, default: 'done', constraint: '' },
-    { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: '' },
-    { kind: 'flag', name: 'kill-pane', type: 'bool', required: false, constraint: '' },
-];
-const cancelParams = [
-    { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
-];
-const failParams = [
-    { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
-];
-// ---------------------------------------------------------------------------
-// agent new prompt (formerly job start prompt)
-// ---------------------------------------------------------------------------
-describe('agent new prompt', () => {
-    // stdin is handled by readStdinRaw() which requires actual stdin — we only
-    // test the non-stdin flag parsing here.
-    test('--cwd flag parsed as string', async () => {
-        // stdin param will be read but we can't pipe here — skip stdin assertion,
-        // test that cwd parses correctly alongside other tokens.
-        // We test the flag-only shape: no stdin params in isolation.
-        const flagOnlyParams = [
-            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: '' },
-        ];
-        const result = await parseArgv(flagOnlyParams, ['--cwd', '/tmp/mydir']);
-        assert.equal(result['cwd'], '/tmp/mydir');
-    });
-    test('cwd absent → undefined', async () => {
-        const flagOnlyParams = [
-            { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: '' },
-        ];
-        const result = await parseArgv(flagOnlyParams, []);
-        assert.equal(result['cwd'], undefined);
-    });
-});
-// ---------------------------------------------------------------------------
-// agent new fork (formerly job start fork)
-// ---------------------------------------------------------------------------
-describe('agent new fork', () => {
-    test('no args parses cleanly', async () => {
-        const result = await parseArgv(startForkParams, []);
-        assert.equal(result['cwd'], undefined);
-    });
-    test('--cwd parsed', async () => {
-        const result = await parseArgv(startForkParams, ['--cwd', '/workspace']);
-        assert.equal(result['cwd'], '/workspace');
-    });
-    test('unknown positional rejected', async () => {
-        await assert.rejects(() => parseArgv(startForkParams, ['extra-pos']), (err) => { assert.match(err.message, /takes no positional/); return true; });
-    });
-});
-// ---------------------------------------------------------------------------
-// agent new planner (formerly job start planner)
-// ---------------------------------------------------------------------------
-describe('agent new planner', () => {
-    test('positional spec_path required', async () => {
-        await assert.rejects(() => parseArgv(startPlannerParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('positional parsed as spec_path (camelCase: specPath? no — underscore stays as-is)', async () => {
-        const result = await parseArgv(startPlannerParams, ['/tmp/spec.md']);
-        // flagNameToKey converts kebab to camel; underscores are unaffected
-        assert.equal(result['spec_path'], '/tmp/spec.md');
-    });
-    test('--cwd optional', async () => {
-        const result = await parseArgv(startPlannerParams, ['/tmp/spec.md', '--cwd', '/src']);
-        assert.equal(result['cwd'], '/src');
-        assert.equal(result['spec_path'], '/tmp/spec.md');
-    });
-});
-// ---------------------------------------------------------------------------
-// agent new implementer (formerly job start implementer)
-// ---------------------------------------------------------------------------
-describe('agent new implementer', () => {
-    test('positional plan_path required', async () => {
-        await assert.rejects(() => parseArgv(startImplementerParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('positional parsed', async () => {
-        const result = await parseArgv(startImplementerParams, ['/tmp/plan.md']);
-        assert.equal(result['plan_path'], '/tmp/plan.md');
-    });
-});
-// ---------------------------------------------------------------------------
-// agent new reviewer (formerly job start reviewer)
-// ---------------------------------------------------------------------------
-describe('agent new reviewer', () => {
-    test('positional + --kind required', async () => {
-        await assert.rejects(() => parseArgv(startReviewerParams, ['/tmp/artifact.md']), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('valid kind: plan', async () => {
-        const result = await parseArgv(startReviewerParams, ['/tmp/artifact.md', '--kind', 'plan']);
-        assert.equal(result['artifact_path'], '/tmp/artifact.md');
-        assert.equal(result['kind'], 'plan');
-    });
-    test('valid kind: spec', async () => {
-        const result = await parseArgv(startReviewerParams, ['/tmp/artifact.md', '--kind', 'spec']);
-        assert.equal(result['kind'], 'spec');
-    });
-    test('invalid kind throws invalid_type', async () => {
-        await assert.rejects(() => parseArgv(startReviewerParams, ['/tmp/artifact.md', '--kind', 'bad']), (err) => { assert.match(err.message, /must be one of/); return true; });
-    });
-    test('--spec-path optional, becomes specPath', async () => {
-        const result = await parseArgv(startReviewerParams, [
-            '/tmp/artifact.md', '--kind', 'plan', '--spec-path', '/tmp/spec.md',
-        ]);
-        assert.equal(result['specPath'], '/tmp/spec.md');
-    });
-});
-// ---------------------------------------------------------------------------
-// job read list
-// ---------------------------------------------------------------------------
-describe('job read list', () => {
-    test('defaults: limit=20, cursor=undefined', async () => {
-        const result = await parseArgv(readListParams, []);
-        assert.equal(result['limit'], 20);
-        assert.equal(result['cursor'], undefined);
-    });
-    test('--limit N parsed as int', async () => {
-        const result = await parseArgv(readListParams, ['--limit', '50']);
-        assert.equal(result['limit'], 50);
-    });
-    test('--limit with non-integer throws', async () => {
-        await assert.rejects(() => parseArgv(readListParams, ['--limit', 'abc']), (err) => { assert.match(err.message, /must be an integer/); return true; });
-    });
-    test('--cursor opaque token', async () => {
-        const result = await parseArgv(readListParams, ['--cursor', 'tok_abc123']);
-        assert.equal(result['cursor'], 'tok_abc123');
-    });
-    test('--limit and --cursor together', async () => {
-        const result = await parseArgv(readListParams, ['--limit', '5', '--cursor', 'next_page']);
-        assert.equal(result['limit'], 5);
-        assert.equal(result['cursor'], 'next_page');
-    });
-});
-// ---------------------------------------------------------------------------
-// job read status
-// ---------------------------------------------------------------------------
-describe('job read status', () => {
-    test('positional job_id required', async () => {
-        await assert.rejects(() => parseArgv(readStatusParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('positional job_id parsed', async () => {
-        const result = await parseArgv(readStatusParams, ['job-abc-123']);
-        assert.equal(result['job_id'], 'job-abc-123');
-    });
-});
-// ---------------------------------------------------------------------------
-// job read result
-// ---------------------------------------------------------------------------
-describe('job read result', () => {
-    test('positional job_id required', async () => {
-        await assert.rejects(() => parseArgv(readResultParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('positional job_id without --wait', async () => {
-        const result = await parseArgv(readResultParams, ['job-xyz']);
-        assert.equal(result['job_id'], 'job-xyz');
-        assert.equal(result['wait'], false);
-    });
-    test('--wait presence = true', async () => {
-        const result = await parseArgv(readResultParams, ['job-xyz', '--wait']);
-        assert.equal(result['wait'], true);
-    });
-    test('--wait=value rejected (bool takes no value)', async () => {
-        await assert.rejects(() => parseArgv(readResultParams, ['job-xyz', '--wait=true']), (err) => { assert.match(err.message, /takes no value/); return true; });
-    });
-});
-// ---------------------------------------------------------------------------
-// job read logs
-// ---------------------------------------------------------------------------
-describe('job read logs', () => {
-    test('positional job_id required', async () => {
-        await assert.rejects(() => parseArgv(readLogsParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('defaults: level=info, follow=false', async () => {
-        const result = await parseArgv(readLogsParams, ['job-abc']);
-        assert.equal(result['job_id'], 'job-abc');
-        assert.equal(result['level'], 'info');
-        assert.equal(result['follow'], false);
-    });
-    test('--follow presence = true', async () => {
-        const result = await parseArgv(readLogsParams, ['job-abc', '--follow']);
-        assert.equal(result['follow'], true);
-    });
-    test('--follow=value rejected', async () => {
-        await assert.rejects(() => parseArgv(readLogsParams, ['job-abc', '--follow=true']), (err) => { assert.match(err.message, /takes no value/); return true; });
-    });
-    test('--level valid enum', async () => {
-        const result = await parseArgv(readLogsParams, ['job-abc', '--level', 'debug']);
-        assert.equal(result['level'], 'debug');
-    });
-    test('--level invalid enum throws', async () => {
-        await assert.rejects(() => parseArgv(readLogsParams, ['job-abc', '--level', 'trace']), (err) => { assert.match(err.message, /must be one of/); return true; });
-    });
-    test('--since and --until optional strings', async () => {
-        const result = await parseArgv(readLogsParams, [
-            'job-abc', '--since', '2025-01-01T00:00:00Z', '--until', '2025-01-02T00:00:00Z',
-        ]);
-        assert.equal(result['since'], '2025-01-01T00:00:00Z');
-        assert.equal(result['until'], '2025-01-02T00:00:00Z');
-    });
-});
-// ---------------------------------------------------------------------------
-// job submit
-// ---------------------------------------------------------------------------
-describe('job submit', () => {
-    test('positional job_id + defaults: status=done, killPane=false', async () => {
-        const result = await parseArgv(submitParams, ['job-abc']);
-        assert.equal(result['job_id'], 'job-abc');
-        assert.equal(result['status'], 'done');
-        assert.equal(result['killPane'], false);
-    });
-    test('--status failed parsed', async () => {
-        const result = await parseArgv(submitParams, ['job-abc', '--status', 'failed', '--reason', 'broken']);
-        assert.equal(result['status'], 'failed');
-        assert.equal(result['reason'], 'broken');
-    });
-    test('--status invalid enum throws', async () => {
-        await assert.rejects(() => parseArgv(submitParams, ['job-abc', '--status', 'bogus']), (err) => { assert.match(err.message, /must be one of/); return true; });
-    });
-    test('--kill-pane presence = true, killPane key', async () => {
-        const result = await parseArgv(submitParams, ['job-abc', '--kill-pane']);
-        assert.equal(result['killPane'], true);
-    });
-    test('missing positional job_id throws missing_parameter', async () => {
-        await assert.rejects(() => parseArgv(submitParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('--context-file no longer accepted', async () => {
-        await assert.rejects(() => parseArgv(submitParams, ['job-abc', '--context-file', '/tmp/anything']), (err) => { assert.match(err.message, /unknown flag: --context-file/); return true; });
-    });
-});
-// ---------------------------------------------------------------------------
-// job cancel
-// ---------------------------------------------------------------------------
-describe('job cancel', () => {
-    test('positional job_id required', async () => {
-        await assert.rejects(() => parseArgv(cancelParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('positional job_id parsed', async () => {
-        const result = await parseArgv(cancelParams, ['job-abc-123']);
-        assert.equal(result['job_id'], 'job-abc-123');
-    });
-});
-// ---------------------------------------------------------------------------
-// job _fail
-// ---------------------------------------------------------------------------
-describe('job _fail', () => {
-    test('positional job_id required', async () => {
-        await assert.rejects(() => parseArgv(failParams, []), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
-    });
-    test('positional job_id parsed', async () => {
-        const result = await parseArgv(failParams, ['job-fail-001']);
-        assert.equal(result['job_id'], 'job-fail-001');
-    });
-});

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

@@ -1,66 +0,0 @@
-// Tests for jobs.ts result-file storage (markdown vs json paths).
-//
-// Run with: node --import tsx/esm --test src/core/__tests__/jobs.test.ts
-import { test, describe, before, after } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { createJob, writeResult, writeMarkdownResult, readResult, } from '../jobs.js';
-let stateDir;
-let origXdg;
-before(() => {
-    stateDir = join(tmpdir(), `crtr-jobs-test-${Date.now()}`);
-    mkdirSync(stateDir, { recursive: true });
-    origXdg = process.env['XDG_STATE_HOME'];
-    process.env['XDG_STATE_HOME'] = stateDir;
-});
-after(() => {
-    if (origXdg === undefined) {
-        delete process.env['XDG_STATE_HOME'];
-    }
-    else {
-        process.env['XDG_STATE_HOME'] = origXdg;
-    }
-    rmSync(stateDir, { recursive: true, force: true });
-});
-describe('writeMarkdownResult + readResult round-trip', () => {
-    test('done with body writes result.md, parses frontmatter back', async () => {
-        const { jobId, dir } = createJob('prompt', { cwd: '/tmp' });
-        const body = '**Summary:** all good\n\nMore details on the next line.\n';
-        writeMarkdownResult(jobId, body, 'done');
-        assert.ok(existsSync(join(dir, 'result.md')), 'result.md should exist');
-        assert.ok(!existsSync(join(dir, 'result.json')), 'result.json should NOT exist on md path');
-        const raw = readFileSync(join(dir, 'result.md'), 'utf8');
-        assert.match(raw, /^---\nstatus: done\nwritten_at: \d{4}-\d{2}-\d{2}T/);
-        assert.ok(raw.endsWith(body), 'body preserved at end of file');
-        const r = await readResult(jobId, { waitMs: 0 });
-        assert.equal(r.status, 'done');
-        assert.equal(r.result_md, body);
-        assert.equal(r.reason, undefined);
-        assert.equal(r.result, undefined);
-    });
-    test('failed with reason writes reason into frontmatter and reads it back', async () => {
-        const { jobId } = createJob('prompt', { cwd: '/tmp' });
-        writeMarkdownResult(jobId, '', 'failed', 'broke: had "quoted" parts and a\nnewline');
-        const r = await readResult(jobId, { waitMs: 0 });
-        assert.equal(r.status, 'failed');
-        assert.equal(r.result_md, '');
-        assert.equal(r.reason, 'broke: had "quoted" parts and a\nnewline');
-    });
-    test('writeResult (JSON) writes result.json and read still works', async () => {
-        const { jobId, dir } = createJob('prompt', { cwd: '/tmp' });
-        writeResult(jobId, { feedback: 'approved', n: 3 }, 'done');
-        assert.ok(existsSync(join(dir, 'result.json')));
-        assert.ok(!existsSync(join(dir, 'result.md')));
-        const r = await readResult(jobId, { waitMs: 0 });
-        assert.equal(r.status, 'done');
-        assert.deepEqual(r.result, { feedback: 'approved', n: 3 });
-        assert.equal(r.result_md, undefined);
-    });
-    test('readResult with no result file and waitMs=0 returns timeout', async () => {
-        const { jobId } = createJob('prompt', { cwd: '/tmp' });
-        const r = await readResult(jobId, { waitMs: 0 });
-        assert.equal(r.status, 'timeout');
-    });
-});

package/dist/core/jobs.d.ts

@@ -1,101 +0,0 @@
-type TerminalStatus = 'done' | 'failed' | 'canceled';
-type JobState = 'live' | TerminalStatus;
-type LogLevel = 'debug' | 'info' | 'warn' | 'error';
-/**
- * Allocate a new job directory and write meta.json atomically.
- * Returns the job_id and the absolute directory path.
- */
-export declare function createJob(kind: string, opts: {
-    cwd: string;
-    pid?: number;
-}): {
-    jobId: string;
-    dir: string;
-};
-/**
- * Record the tmux pane hosting a detached worker so `cancelJob` can kill it.
- */
-export declare function recordJobPane(jobId: string, paneId: string): void;
-/**
- * Append one event line to log.jsonl. Does NOT throw if jobId doesn't exist —
- * a crashed writer should not further corrupt state; use a guard at the call site.
- */
-export declare function appendEvent(jobId: string, event: {
-    level: LogLevel;
-    event: string;
-    message: string;
-    data?: object;
-}): void;
-/**
- * Atomically write result.json (structured object) and update meta.json status.
- * Used by programmatic callers (human, sys) that produce object results.
- * The result file's appearance is the completion signal — never inferred from log content.
- */
-export declare function writeResult(jobId: string, result: object, terminalStatus: TerminalStatus): void;
-/**
- * Atomically write result.md (YAML frontmatter + markdown body) and update meta.json status.
- * Used by `crtr job submit` for agent-driven markdown results.
- */
-export declare function writeMarkdownResult(jobId: string, body: string, terminalStatus: TerminalStatus, reason?: string): void;
-/**
- * Read whichever result file exists (result.md or result.json). If neither
- * exists and waitMs is given, block via fs.watch until one appears or the
- * timeout elapses.
- *
- * Race safety: registers the watcher THEN re-stats. If a result file appeared
- * between the first stat and the watch registration, the re-stat catches it
- * before the watcher has a chance to miss it.
- *
- * Returns shape:
- *   - JSON path:     { status, result: object }
- *   - Markdown path: { status, result_md: string, reason?: string }
- *   - Timeout:       { status: 'timeout' }
- */
-export interface ReadResultResponse {
-    status: 'done' | 'failed' | 'canceled' | 'timeout';
-    result?: object;
-    result_md?: string;
-    reason?: string;
-}
-export declare function readResult(jobId: string, opts?: {
-    waitMs?: number;
-}): Promise<ReadResultResponse>;
-/**
- * Derive job state from meta.json, the result file, and the tail of log.jsonl.
- * If a pid is recorded, is not alive, and no result file exists → 'failed'.
- */
-export declare function jobStatus(jobId: string): {
-    state: JobState;
-    age_s: number;
-    last_event: {
-        event: string;
-        ts: string;
-    } | null;
-};
-/**
- * List all jobs sorted by created_at ascending. Pagination is applied by the
- * caller, not here.
- */
-export declare function listJobs(): {
-    job_id: string;
-    kind: string;
-    state: JobState;
-    created_at: string;
-}[];
-/**
- * Read and filter log events. Ordering preserved. sinceTs/untilTs are ISO8601
- * strings; minLevel filters by severity rank (inclusive).
- */
-export declare function readLog(jobId: string, opts?: {
-    sinceTs?: string;
-    untilTs?: string;
-    minLevel?: LogLevel;
-}): object[];
-/**
- * Best-effort cancel: send SIGTERM to the recorded pid (if any), mark meta
- * canceled. Success means the signal was delivered, not that execution stopped.
- */
-export declare function cancelJob(jobId: string): {
-    canceled: boolean;
-};
-export {};