yarramate 0.5.0 → 0.7.0

package/dist/cli.js

@@ -1,243 +1,16 @@
 #!/usr/bin/env node
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { dirname, relative, resolve } from 'node:path';
-import { isSeq, parseDocument } from 'yaml';
-import { compileWorkspace, compileWorkspaceWithProfileContext, } from './compiler.js';
-import { compareArchitectureStates } from './architecture-state.js';
-import { serializeSemanticGraph } from './graph.js';
-import { diagnosticJson, humanDiagnostics, isMainModule, resolveCliWorkspaceSources, usage, versionResult, } from './cli-support.js';
+import { compileWorkspace } from './compiler.js';
+import { diagnosticJson, isMainModule, usage, versionResult, } from './cli-support.js';
+import { runAskCommand } from './ask-command.js';
 import { runCheckCommand } from './check-command.js';
-import { runNewCommand } from './new-command.js';
-import { runStatusCommand } from './status-command.js';
-import { evaluateEvidence, evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
+import { runExportCommand } from './export-command.js';
+import { runApplyCommand } from './apply-command.js';
+import { runDesignCommand } from './design-command.js';
+import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { reconcileEvidenceReports } from './reconciliation.js';
 import { loadWorkspaceManifest } from './workspace.js';
-import { evaluateProjection, loadProjection, renderBudgetedContext, renderProjectionMarkdown, } from './projection.js';
-const extractBudget = (options) => {
-    const rest = [];
-    let budget;
-    for (let index = 0; index < options.length; index += 1) {
-        const option = options[index];
-        if (option === '--budget') {
-            const value = options[index + 1];
-            if (value === undefined ||
-                budget !== undefined ||
-                !/^[1-9][0-9]*$/.test(value)) {
-                return { ok: false };
-            }
-            budget = Number(value);
-            index += 1;
-            continue;
-        }
-        if (option !== undefined)
-            rest.push(option);
-    }
-    return budget === undefined ? { ok: true, rest } : { ok: true, budget, rest };
-};
-const runProjection = (options, cwd, output) => {
-    const extracted = output === 'json' ? extractBudget(options) : { ok: true, rest: options };
-    if (!extracted.ok) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const budget = 'budget' in extracted ? extracted.budget : undefined;
-    const [projectionPath, ...paths] = extracted.rest;
-    if (projectionPath === undefined ||
-        paths.length === 0 ||
-        extracted.rest.some((option) => option.startsWith('-'))) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    try {
-        const resolved = resolveCliWorkspaceSources(paths, cwd);
-        if (!resolved.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(resolved.diagnostics),
-                stderr: '',
-            };
-        }
-        const loaded = loadProjection({
-            path: projectionPath,
-            source: readFileSync(resolve(cwd, projectionPath), 'utf8'),
-        });
-        if (!loaded.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(loaded.diagnostics),
-                stderr: '',
-            };
-        }
-        const compilation = compileWorkspaceWithProfileContext(resolved.paths.map((path) => ({
-            path,
-            source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
-        if (!compilation.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(compilation.diagnostics),
-                stderr: '',
-            };
-        }
-        const result = evaluateProjection(compilation.graph, loaded.projection, compilation.profileContext);
-        return {
-            exitCode: 0,
-            stdout: output === 'json'
-                ? budget === undefined
-                    ? `${JSON.stringify(result, null, 2)}\n`
-                    : renderBudgetedContext(result, budget)
-                : renderProjectionMarkdown(result),
-            stderr: '',
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
-    }
-};
-const runAdHocContext = (options, cwd) => {
-    const extracted = extractBudget(options);
-    if (!extracted.ok) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const budget = 'budget' in extracted ? extracted.budget : undefined;
-    const subjects = [];
-    const paths = [];
-    for (let index = 0; index < extracted.rest.length; index += 1) {
-        const option = extracted.rest[index];
-        if (option === '--subject') {
-            const value = extracted.rest[index + 1];
-            if (value === undefined || value.startsWith('-')) {
-                return { exitCode: 2, stdout: '', stderr: usage };
-            }
-            subjects.push(value);
-            index += 1;
-            continue;
-        }
-        if (option === undefined || option.startsWith('-')) {
-            return { exitCode: 2, stdout: '', stderr: usage };
-        }
-        paths.push(option);
-    }
-    if (subjects.length === 0 || paths.length === 0) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const unqualified = subjects.filter((subject) => !subject.includes('#'));
-    if (unqualified.length > 0) {
-        return {
-            exitCode: 2,
-            stdout: '',
-            stderr: 'Ad-hoc context subjects must be globally qualified as ' +
-                `"<document-id>#<local-id>": ${unqualified.join(', ')}\n`,
-        };
-    }
-    try {
-        const resolved = resolveCliWorkspaceSources(paths, cwd);
-        if (!resolved.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(resolved.diagnostics),
-                stderr: '',
-            };
-        }
-        const compilation = compileWorkspaceWithProfileContext(resolved.paths.map((path) => ({
-            path,
-            source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
-        if (!compilation.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(compilation.diagnostics),
-                stderr: '',
-            };
-        }
-        const known = new Set(compilation.graph.subjects.map(({ id }) => id));
-        const unknown = subjects.filter((subject) => !known.has(subject));
-        if (unknown.length > 0) {
-            return {
-                exitCode: 1,
-                stdout: '',
-                stderr: `Unknown subject ${unknown.length === 1 ? 'identity' : 'identities'}: ` +
-                    `${unknown.join(', ')} (the compiled workspace declares ${known.size} subjects)\n`,
-            };
-        }
-        const result = evaluateProjection(compilation.graph, {
-            format: 'yarramate/projection/v1',
-            id: 'ad-hoc-context',
-            version: '0.0',
-            query: { subjects, relationships: 'connected' },
-            presentation: {
-                title: 'Ad-hoc context',
-                description: `Connected neighbourhood of ${subjects.join(', ')}`,
-            },
-        }, compilation.profileContext);
-        return {
-            exitCode: 0,
-            stdout: budget === undefined
-                ? `${JSON.stringify(result, null, 2)}\n`
-                : renderBudgetedContext(result, budget),
-            stderr: '',
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
-    }
-};
-const runEvidence = (options, cwd) => {
-    const [evidencePath, ...paths] = options;
-    if (evidencePath === undefined ||
-        paths.length === 0 ||
-        options.some((option) => option.startsWith('-'))) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    try {
-        const resolved = resolveCliWorkspaceSources(paths, cwd);
-        if (!resolved.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(resolved.diagnostics),
-                stderr: '',
-            };
-        }
-        const loaded = loadEvidence({
-            path: evidencePath,
-            source: readFileSync(resolve(cwd, evidencePath), 'utf8'),
-        });
-        if (!loaded.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(loaded.diagnostics),
-                stderr: '',
-            };
-        }
-        const compilation = compileWorkspace(resolved.paths.map((path) => ({
-            path,
-            source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
-        if (!compilation.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(compilation.diagnostics),
-                stderr: '',
-            };
-        }
-        const evaluation = evaluateEvidence(compilation.graph, loaded.evidence);
-        return evaluation.ok
-            ? {
-                exitCode: 0,
-                stdout: `${JSON.stringify(evaluation.report, null, 2)}\n`,
-                stderr: '',
-            }
-            : {
-                exitCode: 1,
-                stdout: diagnosticJson(evaluation.diagnostics),
-                stderr: '',
-            };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
-    }
-};
 const runReconciliation = (options, cwd) => {
     const [workspacePath] = options;
     if (options.length !== 1 ||
@@ -306,52 +79,6 @@ const runReconciliation = (options, cwd) => {
         return { exitCode: 2, stdout: '', stderr: `${message}\n` };
     }
 };
-const runStateComparison = (options, cwd) => {
-    const [from, to, ...paths] = options;
-    if (from === undefined ||
-        to === undefined ||
-        paths.length === 0 ||
-        options.some((option) => option.startsWith('-'))) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    try {
-        const resolved = resolveCliWorkspaceSources(paths, cwd);
-        if (!resolved.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(resolved.diagnostics),
-                stderr: '',
-            };
-        }
-        const compilation = compileWorkspace(resolved.paths.map((path) => ({
-            path,
-            source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
-        if (!compilation.ok) {
-            return {
-                exitCode: 1,
-                stdout: diagnosticJson(compilation.diagnostics),
-                stderr: '',
-            };
-        }
-        const comparison = compareArchitectureStates(compilation.graph, from, to);
-        return comparison.ok
-            ? {
-                exitCode: 0,
-                stdout: `${JSON.stringify(comparison.comparison, null, 2)}\n`,
-                stderr: '',
-            }
-            : {
-                exitCode: 2,
-                stdout: '',
-                stderr: `${comparison.issues.map(({ message }) => message).join('\n')}\n`,
-            };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
-    }
-};
 const runInit = (options, cwd) => {
     const positional = options.filter((option) => option !== '--no-pointer');
     const writePointer = positional.length === options.length;
@@ -398,9 +125,9 @@ const runInit = (options, cwd) => {
         'YarraMate documents in `.yarramate/`. When prose documentation and the\n' +
         'model disagree, the model is authoritative.\n' +
         '\n' +
-        '- Orient first: `yarramate status .yarramate/workspace.yaml --json`\n' +
+        '- Orient first: `yarramate ask .yarramate/workspace.yaml`\n' +
+        '- Continue the design interview: `yarramate design .yarramate/workspace.yaml`\n' +
         '- Validate changes: `yarramate check .yarramate/workspace.yaml --json`\n' +
-        '- Bounded task context: `yarramate context <projection.yaml> .yarramate/workspace.yaml`\n' +
         '\n' +
         'Author native documents only; never edit generated output.\n';
     // Harnesses look in different files: AGENTS.md is the cross-harness
@@ -434,283 +161,9 @@ const runInit = (options, cwd) => {
         stderr: '',
     };
 };
-const parseFlags = (options) => {
-    const [path, ...rest] = options;
-    if (path === undefined || path.startsWith('-') || rest.length % 2 !== 0) {
-        return undefined;
-    }
-    const flags = new Map();
-    for (let index = 0; index < rest.length; index += 2) {
-        const flag = rest[index];
-        const value = rest[index + 1];
-        if (flag === undefined ||
-            value === undefined ||
-            !flag.startsWith('--') ||
-            value.startsWith('--')) {
-            return undefined;
-        }
-        flags.set(flag, [...(flags.get(flag) ?? []), value]);
-    }
-    return { path, flags };
-};
-const oneFlag = (flags, flag) => {
-    const values = flags.get(flag);
-    return values?.length === 1 ? values[0] : undefined;
-};
-const hasRepeatedSingletonFlag = (flags) => [...flags.entries()].some(([flag, values]) => flag !== '--source' &&
-    flag !== '--constraint' &&
-    flag !== '--reference' &&
-    flag !== '--present-in' &&
-    values.length !== 1);
-const appendBlockItem = (document, collection, item) => {
-    document.addIn([collection], item);
-    const sequence = document.getIn([collection], true);
-    if (isSeq(sequence)) {
-        sequence.flow = false;
-    }
-};
-const identifiedReferences = (values) => {
-    const parsed = values.map((value) => {
-        const separator = value.indexOf('=');
-        return separator <= 0 || separator === value.length - 1
-            ? undefined
-            : {
-                id: value.slice(0, separator),
-                ref: value.slice(separator + 1),
-            };
-    });
-    return parsed.some((reference) => reference === undefined)
-        ? undefined
-        : parsed;
-};
-const runAdd = (options, cwd) => {
-    const parsed = parseFlags(options);
-    if (parsed === undefined) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const allowed = new Set([
-        '--id',
-        '--kind',
-        '--name',
-        '--status',
-        '--description',
-        '--owner',
-        '--constraint',
-        '--reference',
-        '--present-in',
-        '--source',
-    ]);
-    if ([...parsed.flags.keys()].some((flag) => !allowed.has(flag)) ||
-        hasRepeatedSingletonFlag(parsed.flags)) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const id = oneFlag(parsed.flags, '--id');
-    const kind = oneFlag(parsed.flags, '--kind');
-    const name = oneFlag(parsed.flags, '--name');
-    if (id === undefined || kind === undefined || name === undefined) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const constraints = identifiedReferences(parsed.flags.get('--constraint') ?? []);
-    const references = identifiedReferences(parsed.flags.get('--reference') ?? []);
-    if (constraints === undefined || references === undefined) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    try {
-        const absolutePath = resolve(cwd, parsed.path);
-        const document = parseDocument(readFileSync(absolutePath, 'utf8'));
-        appendBlockItem(document, 'concepts', {
-            id,
-            kind,
-            name,
-            ...(oneFlag(parsed.flags, '--description') === undefined
-                ? {}
-                : { description: oneFlag(parsed.flags, '--description') }),
-            ...(oneFlag(parsed.flags, '--status') === undefined
-                ? {}
-                : { status: oneFlag(parsed.flags, '--status') }),
-            ...(oneFlag(parsed.flags, '--owner') === undefined
-                ? {}
-                : { owner: oneFlag(parsed.flags, '--owner') }),
-            ...(constraints.length === 0 ? {} : { constraints }),
-            ...(references.length === 0 ? {} : { references }),
-            ...(parsed.flags.get('--present-in') === undefined
-                ? {}
-                : { presentIn: parsed.flags.get('--present-in') }),
-        });
-        const candidate = document.toString({ lineWidth: 0 });
-        const companions = resolveCliWorkspaceSources(parsed.flags.get('--source') ?? [], cwd);
-        if (!companions.ok) {
-            return {
-                exitCode: 1,
-                stdout: humanDiagnostics(companions.diagnostics),
-                stderr: '',
-            };
-        }
-        const compilation = compileWorkspace([
-            { path: parsed.path, source: candidate },
-            ...companions.paths
-                .filter((path) => resolve(cwd, path) !== resolve(cwd, parsed.path))
-                .map((path) => ({
-                path,
-                source: readFileSync(resolve(cwd, path), 'utf8'),
-            })),
-        ]);
-        if (!compilation.ok) {
-            return {
-                exitCode: 1,
-                stdout: humanDiagnostics(compilation.diagnostics),
-                stderr: '',
-            };
-        }
-        writeFileSync(absolutePath, candidate, 'utf8');
-        return {
-            exitCode: 0,
-            stdout: `Added concept "${id}" to ${parsed.path}\n`,
-            stderr: '',
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
-    }
-};
-const runConnect = (options, cwd) => {
-    const parsed = parseFlags(options);
-    if (parsed === undefined) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const allowed = new Set([
-        '--id',
-        '--kind',
-        '--from',
-        '--to',
-        '--name',
-        '--description',
-        '--status',
-        '--mode',
-        '--content',
-        '--reference',
-        '--present-in',
-        '--source',
-    ]);
-    if ([...parsed.flags.keys()].some((flag) => !allowed.has(flag)) ||
-        hasRepeatedSingletonFlag(parsed.flags)) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const id = oneFlag(parsed.flags, '--id');
-    const kind = oneFlag(parsed.flags, '--kind');
-    const from = oneFlag(parsed.flags, '--from');
-    const to = oneFlag(parsed.flags, '--to');
-    if (id === undefined ||
-        kind === undefined ||
-        from === undefined ||
-        to === undefined) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    const references = identifiedReferences(parsed.flags.get('--reference') ?? []);
-    if (references === undefined) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    try {
-        const absolutePath = resolve(cwd, parsed.path);
-        const document = parseDocument(readFileSync(absolutePath, 'utf8'));
-        appendBlockItem(document, 'relationships', {
-            id,
-            kind,
-            from,
-            to,
-            ...(oneFlag(parsed.flags, '--name') === undefined
-                ? {}
-                : { name: oneFlag(parsed.flags, '--name') }),
-            ...(oneFlag(parsed.flags, '--description') === undefined
-                ? {}
-                : { description: oneFlag(parsed.flags, '--description') }),
-            ...(oneFlag(parsed.flags, '--status') === undefined
-                ? {}
-                : { status: oneFlag(parsed.flags, '--status') }),
-            ...(oneFlag(parsed.flags, '--mode') === undefined
-                ? {}
-                : { mode: oneFlag(parsed.flags, '--mode') }),
-            ...(oneFlag(parsed.flags, '--content') === undefined
-                ? {}
-                : { content: oneFlag(parsed.flags, '--content') }),
-            ...(references.length === 0 ? {} : { references }),
-            ...(parsed.flags.get('--present-in') === undefined
-                ? {}
-                : { presentIn: parsed.flags.get('--present-in') }),
-        });
-        const candidate = document.toString({ lineWidth: 0 });
-        const companions = resolveCliWorkspaceSources(parsed.flags.get('--source') ?? [], cwd);
-        if (!companions.ok) {
-            return {
-                exitCode: 1,
-                stdout: humanDiagnostics(companions.diagnostics),
-                stderr: '',
-            };
-        }
-        const compilation = compileWorkspace([
-            { path: parsed.path, source: candidate },
-            ...companions.paths
-                .filter((path) => resolve(cwd, path) !== resolve(cwd, parsed.path))
-                .map((path) => ({
-                path,
-                source: readFileSync(resolve(cwd, path), 'utf8'),
-            })),
-        ]);
-        if (!compilation.ok) {
-            return {
-                exitCode: 1,
-                stdout: humanDiagnostics(compilation.diagnostics),
-                stderr: '',
-            };
-        }
-        writeFileSync(absolutePath, candidate, 'utf8');
-        return {
-            exitCode: 0,
-            stdout: `Added relationship "${id}" to ${parsed.path}\n`,
-            stderr: '',
-        };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
-    }
-};
-const runCompile = (options, cwd) => {
-    if (options.length === 0 ||
-        options.some((option) => option.startsWith('-'))) {
-        return { exitCode: 2, stdout: '', stderr: usage };
-    }
-    try {
-        const resolved = resolveCliWorkspaceSources(options, cwd);
-        if (!resolved.ok) {
-            return {
-                exitCode: 1,
-                stdout: humanDiagnostics(resolved.diagnostics),
-                stderr: '',
-            };
-        }
-        const result = compileWorkspace(resolved.paths.map((path) => ({
-            path,
-            source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
-        return result.ok
-            ? {
-                exitCode: 0,
-                stdout: serializeSemanticGraph(result.graph),
-                stderr: '',
-            }
-            : {
-                exitCode: 1,
-                stdout: humanDiagnostics(result.diagnostics),
-                stderr: '',
-            };
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
-    }
-};
+// The seven-verb contract (docs/AGENT-INTERFACE.md): one verb per
+// lifecycle stage — init creates, design fills, apply writes, ask reads,
+// check gates, reconcile reports drift, export derives artifacts.
 export function runCli(args, cwd = process.cwd()) {
     const [command, ...options] = args;
     if (command === '--help' || command === '-h' || command === 'help') {
@@ -722,40 +175,23 @@ export function runCli(args, cwd = process.cwd()) {
     if (command === 'init') {
         return runInit(options, cwd);
     }
-    if (command === 'add') {
-        return runAdd(options, cwd);
-    }
-    if (command === 'connect') {
-        return runConnect(options, cwd);
-    }
-    if (command === 'compile') {
-        return runCompile(options, cwd);
+    if (command === 'design') {
+        return runDesignCommand(options, cwd);
     }
-    if (command === 'context') {
-        return options.includes('--subject')
-            ? runAdHocContext(options, cwd)
-            : runProjection(options, cwd, 'json');
+    if (command === 'apply') {
+        return runApplyCommand(options, cwd);
     }
-    if (command === 'view') {
-        return runProjection(options, cwd, 'markdown');
-    }
-    if (command === 'compare') {
-        return runStateComparison(options, cwd);
-    }
-    if (command === 'evidence') {
-        return runEvidence(options, cwd);
-    }
-    if (command === 'reconcile') {
-        return runReconciliation(options, cwd);
+    if (command === 'ask') {
+        return runAskCommand(options, cwd);
     }
     if (command === 'check') {
         return runCheckCommand(options, cwd);
     }
-    if (command === 'status') {
-        return runStatusCommand(options, cwd);
+    if (command === 'reconcile') {
+        return runReconciliation(options, cwd);
     }
-    if (command === 'new') {
-        return runNewCommand(options, cwd);
+    if (command === 'export') {
+        return runExportCommand(options, cwd);
     }
     return { exitCode: 2, stdout: '', stderr: usage };
 }