@crouton-kit/crouter 0.3.2 → 0.3.8

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

@@ -1,13 +1,10 @@
-// Tests for the job subtree argv migration.
-// Exercises parseArgv against each leaf's param schema directly — no subprocess,
-// no tmux, no filesystem side-effects from the handler.
+// 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 { writeFileSync, mkdirSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
 import { parseArgv } from '../command.js';
 // ---------------------------------------------------------------------------
 // Param schemas extracted from each leaf (mirrors job.ts exactly)
@@ -51,9 +48,16 @@ const readLogsParams = [
     { 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: 'context-file', name: 'result', 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 = [
@@ -63,27 +67,9 @@ const failParams = [
     { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: '' },
 ];
 // ---------------------------------------------------------------------------
-// Helpers
+// agent new prompt (formerly job start prompt)
 // ---------------------------------------------------------------------------
-let tmpDir;
-function setup() {
-    tmpDir = join(tmpdir(), `crtr-job-test-${Date.now()}`);
-    mkdirSync(tmpDir, { recursive: true });
-}
-function teardown() {
-    if (tmpDir !== undefined) {
-        rmSync(tmpDir, { recursive: true, force: true });
-    }
-}
-function writeTmpJson(name, obj) {
-    const p = join(tmpDir, name);
-    writeFileSync(p, JSON.stringify(obj), 'utf8');
-    return p;
-}
-// ---------------------------------------------------------------------------
-// job start prompt
-// ---------------------------------------------------------------------------
-describe('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 () => {
@@ -105,9 +91,9 @@ describe('job start prompt', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// job start fork
+// agent new fork (formerly job start fork)
 // ---------------------------------------------------------------------------
-describe('job start fork', () => {
+describe('agent new fork', () => {
     test('no args parses cleanly', async () => {
         const result = await parseArgv(startForkParams, []);
         assert.equal(result['cwd'], undefined);
@@ -121,9 +107,9 @@ describe('job start fork', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// job start planner
+// agent new planner (formerly job start planner)
 // ---------------------------------------------------------------------------
-describe('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; });
     });
@@ -139,9 +125,9 @@ describe('job start planner', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// job start implementer
+// agent new implementer (formerly job start implementer)
 // ---------------------------------------------------------------------------
-describe('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; });
     });
@@ -151,9 +137,9 @@ describe('job start implementer', () => {
     });
 });
 // ---------------------------------------------------------------------------
-// job start reviewer
+// agent new reviewer (formerly job start reviewer)
 // ---------------------------------------------------------------------------
-describe('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; });
     });
@@ -273,51 +259,29 @@ describe('job read logs', () => {
 // job submit
 // ---------------------------------------------------------------------------
 describe('job submit', () => {
-    // setup/teardown wraps tests via explicit calls since node:test lacks
-    // per-describe lifecycle hooks in older versions.
-    test('--context-file with valid JSON object', async () => {
-        setup();
-        try {
-            const p = writeTmpJson('result.json', { status: 'done', summary: 'all good' });
-            const result = await parseArgv(submitParams, ['job-abc', '--context-file', p]);
-            assert.equal(result['job_id'], 'job-abc');
-            assert.deepEqual(result['result'], { status: 'done', summary: 'all good' });
-            assert.equal(result['killPane'], false);
-        }
-        finally {
-            teardown();
-        }
+    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 () => {
-        setup();
-        try {
-            const p = writeTmpJson('result.json', { status: 'done' });
-            const result = await parseArgv(submitParams, ['job-abc', '--context-file', p, '--kill-pane']);
-            assert.equal(result['killPane'], true);
-        }
-        finally {
-            teardown();
-        }
-    });
-    test('missing --context-file throws missing_parameter', async () => {
-        await assert.rejects(() => parseArgv(submitParams, ['job-abc']), (err) => { assert.match(err.message, /required parameter is missing/); return true; });
+        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 with non-existent file throws invalid_type', async () => {
-        await assert.rejects(() => parseArgv(submitParams, ['job-abc', '--context-file', '/no/such/file.json']), (err) => { assert.match(err.message, /cannot read file/); return true; });
-    });
-    test('--context-file with invalid JSON throws invalid_type', async () => {
-        setup();
-        try {
-            const p = join(tmpDir, 'bad.json');
-            writeFileSync(p, 'not json', 'utf8');
-            await assert.rejects(() => parseArgv(submitParams, ['job-abc', '--context-file', p]), (err) => { assert.match(err.message, /not valid JSON/); return true; });
-        }
-        finally {
-            teardown();
-        }
+    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; });
     });
 });
 // ---------------------------------------------------------------------------

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

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

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

@@ -0,0 +1,66 @@
+// 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/__tests__/resolver.test.d.ts

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

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

@@ -0,0 +1,113 @@
+// Tests for parseSkillQualifier (slash-only form) and config migration.
+//
+// Run with: node --import tsx/esm --test 'src/core/__tests__/resolver.test.ts'
+import { test, describe, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { parseSkillQualifier } from '../resolver.js';
+import { InputError } from '../io.js';
+import { readConfig } from '../config.js';
+import { SCHEMA_VERSION } from '../../types.js';
+// ---------------------------------------------------------------------------
+// parseSkillQualifier — slash-only form
+// ---------------------------------------------------------------------------
+describe('parseSkillQualifier', () => {
+    test('bare name returns single segment', () => {
+        const r = parseSkillQualifier('foo');
+        assert.deepEqual(r, { segments: ['foo'] });
+    });
+    test('plugin/name returns two segments', () => {
+        const r = parseSkillQualifier('ai/interface');
+        assert.deepEqual(r, { segments: ['ai', 'interface'] });
+    });
+    test('plugin/nested/name returns three segments', () => {
+        const r = parseSkillQualifier('ai/interface/cli-design');
+        assert.deepEqual(r, { segments: ['ai', 'interface', 'cli-design'] });
+    });
+    test('scope-qualified user/name sets scope, single segment', () => {
+        const r = parseSkillQualifier('user/my-skill');
+        assert.deepEqual(r, { scope: 'user', segments: ['my-skill'] });
+    });
+    test('scope-qualified project/name sets scope', () => {
+        const r = parseSkillQualifier('project/my-skill');
+        assert.deepEqual(r, { scope: 'project', segments: ['my-skill'] });
+    });
+    test('scope-qualified user/ai/x/y sets scope and leaves rest as segments', () => {
+        const r = parseSkillQualifier('user/ai/x/y');
+        assert.deepEqual(r, { scope: 'user', segments: ['ai', 'x', 'y'] });
+    });
+    test('colon in input throws InputError with invalid_qualifier', () => {
+        assert.throws(() => parseSkillQualifier('ai:interface/cli-design'), (e) => {
+            assert.ok(e instanceof InputError, 'should be InputError');
+            assert.equal(e.payload.error, 'invalid_qualifier');
+            assert.equal(e.payload.received, 'ai:interface/cli-design');
+            assert.ok(e.payload.next.includes('ai/interface/cli-design'), `next should contain slash form, got: ${e.payload.next}`);
+            return true;
+        });
+    });
+    test('legacy scope:name form throws invalid_qualifier', () => {
+        assert.throws(() => parseSkillQualifier('user:my-skill'), (e) => {
+            assert.ok(e instanceof InputError);
+            assert.equal(e.payload.error, 'invalid_qualifier');
+            assert.ok(e.payload.next.includes('user/my-skill'));
+            return true;
+        });
+    });
+    test('legacy scope:plugin/name form throws invalid_qualifier', () => {
+        assert.throws(() => parseSkillQualifier('user:ai/interface/cli-design'), (e) => {
+            assert.ok(e instanceof InputError);
+            assert.equal(e.payload.error, 'invalid_qualifier');
+            assert.ok(e.payload.next.includes('user/ai/interface/cli-design'));
+            return true;
+        });
+    });
+});
+// ---------------------------------------------------------------------------
+// Config migration: colon keys → slash keys on readConfig with old schema_version
+// ---------------------------------------------------------------------------
+describe('config migration: skill keys colon → slash', () => {
+    let testHomeDir;
+    let origHome;
+    let crouterDir;
+    before(() => {
+        testHomeDir = join(tmpdir(), `crtr-resolver-test-${Date.now()}`);
+        mkdirSync(testHomeDir, { recursive: true });
+        origHome = process.env['HOME'];
+        process.env['HOME'] = testHomeDir;
+        crouterDir = join(testHomeDir, '.crouter');
+        mkdirSync(crouterDir, { recursive: true });
+    });
+    after(() => {
+        if (origHome === undefined) {
+            delete process.env['HOME'];
+        }
+        else {
+            process.env['HOME'] = origHome;
+        }
+        rmSync(testHomeDir, { recursive: true, force: true });
+    });
+    test('colon keys are migrated to slash keys and written with new schema_version', () => {
+        const oldConfig = {
+            schema_version: 1,
+            marketplaces: {},
+            plugins: {},
+            skills: {
+                'ai:foo': { enabled: true },
+                'ai:interface/cli-design': { enabled: false },
+            },
+            auto_update: { crtr: 'notify', content: 'notify', interval_hours: 24 },
+            max_panes_per_window: 3,
+        };
+        writeFileSync(join(crouterDir, 'config.json'), JSON.stringify(oldConfig), 'utf8');
+        const cfg = readConfig('user');
+        assert.ok(!('ai:foo' in cfg.skills), 'old colon key should be gone');
+        assert.ok('ai/foo' in cfg.skills, 'slash key should exist');
+        assert.equal(cfg.skills['ai/foo']?.enabled, true, 'enabled state preserved');
+        assert.ok(!('ai:interface/cli-design' in cfg.skills), 'old colon key should be gone');
+        assert.ok('ai/interface/cli-design' in cfg.skills, 'slash key should exist for nested');
+        assert.equal(cfg.skills['ai/interface/cli-design']?.enabled, false, 'disabled state preserved');
+        assert.equal(cfg.schema_version, SCHEMA_VERSION, 'schema_version bumped to current');
+    });
+});

package/dist/core/config.js

@@ -1,7 +1,8 @@
 import { join } from 'node:path';
-import { CONFIG_FILE, STATE_FILE, defaultScopeConfig, defaultScopeState } from '../types.js';
+import { CONFIG_FILE, STATE_FILE, SCHEMA_VERSION, defaultScopeConfig, defaultScopeState } from '../types.js';
 import { readJsonIfExists, writeJson, ensureDir } from './fs-utils.js';
 import { scopeRoot, requireScopeRoot } from './scope.js';
+import { diag } from './io.js';
 function configPathFor(root) {
     return join(root, CONFIG_FILE);
 }
@@ -23,7 +24,24 @@ export function readConfig(scope) {
     const existing = readJsonIfExists(configPathFor(root));
     if (!existing)
         return defaultScopeConfig();
-    return mergeConfig(existing);
+    const cfg = mergeConfig(existing);
+    if ((existing.schema_version ?? 0) < SCHEMA_VERSION) {
+        migrateSkillConfigKeys(cfg, scope, root);
+    }
+    return cfg;
+}
+function migrateSkillConfigKeys(cfg, scope, root) {
+    const colonKeys = Object.keys(cfg.skills).filter((k) => k.includes(':'));
+    if (colonKeys.length > 0) {
+        for (const key of colonKeys) {
+            const newKey = key.replace(/:/g, '/');
+            cfg.skills[newKey] = cfg.skills[key];
+            delete cfg.skills[key];
+        }
+        diag(`crtr: migrated ${colonKeys.length} skill config keys to slash form in ${scope}`);
+    }
+    cfg.schema_version = SCHEMA_VERSION;
+    writeJson(configPathFor(root), cfg);
 }
 export function readState(scope) {
     const root = scopeRoot(scope);

package/dist/core/jobs.d.ts

@@ -27,28 +27,42 @@ export declare function appendEvent(jobId: string, event: {
     data?: object;
 }): void;
 /**
- * Atomically write result.json and update meta.json status.
- * result.json's appearance is the ONLY completion signal — never inferred from
- * log content.
+ * 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;
 /**
- * Read result.json. If it doesn't exist and waitMs is given, block via fs.watch
- * until result.json appears or the timeout elapses.
+ * 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 result.json appeared
+ * 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 declare function readResult(jobId: string, opts?: {
-    waitMs?: number;
-}): Promise<{
+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, result.json, and the tail of log.jsonl.
- * If a pid is recorded, is not alive, and no result.json exists → 'failed'.
+ * 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;