yarramate 0.6.0 → 0.7.1

package/dist/adapters/mcp-cli.js

@@ -10,14 +10,65 @@ const workspaceProperty = {
 };
 const tools = [
     {
-        name: 'yarramate_status',
-        description: 'One-call workspace orientation: check verdict, reconciliation summary, and a titled inventory of documents, states, projections, evidence, and contracts.',
+        name: 'yarramate_ask',
+        description: 'The consumed-now read surface. Without a query: orientation — check verdict, drift summary, open-question count, and the backlog in dependency order. With a query: free text matches concept ids, names, and descriptions and returns the connected slice; exact subject ids (document-id#local-id) and projection paths address precisely. Set mode for the roster (subjects), declarable vocabulary (kinds), build order (next), or the full open-questions report (open).',
         inputSchema: {
             type: 'object',
             required: ['workspace'],
-            properties: workspaceProperty,
+            properties: {
+                ...workspaceProperty,
+                query: {
+                    type: 'string',
+                    description: 'Free text, a globally qualified subject id, or a projection path',
+                },
+                mode: {
+                    type: 'string',
+                    enum: ['subjects', 'kinds', 'next', 'open'],
+                    description: 'Optional flag mode instead of a query: the filterable roster, the declarable kind vocabulary, dependency-ordered planned work, or the open-questions report',
+                },
+                budget: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'Approximate token budget for the compact slice rendering (query form only)',
+                },
+            },
+        },
+        arguments: (input) => {
+            const workspace = String(input.workspace);
+            if (typeof input.mode === 'string') {
+                return ['ask', workspace, `--${input.mode}`, '--json'];
+            }
+            if (typeof input.query === 'string' && input.query.length > 0) {
+                const budget = typeof input.budget === 'number'
+                    ? ['--budget', String(input.budget)]
+                    : ['--json'];
+                return ['ask', workspace, input.query, ...budget];
+            }
+            return ['ask', workspace, '--json'];
+        },
+    },
+    {
+        name: 'yarramate_design',
+        description: 'The design interview, one stateless step: the top open question with its subject slice, materiality, and progress. Read-only — answers land through the CLI apply command in the repository, not through this server.',
+        inputSchema: {
+            type: 'object',
+            required: ['workspace'],
+            properties: {
+                ...workspaceProperty,
+                subject: {
+                    type: 'string',
+                    description: 'Optional globally qualified subject id to narrow the interview',
+                },
+            },
         },
-        arguments: (input) => ['status', String(input.workspace), '--json'],
+        arguments: (input) => [
+            'design',
+            String(input.workspace),
+            ...(typeof input.subject === 'string'
+                ? ['--subject', input.subject]
+                : []),
+            '--json',
+        ],
     },
     {
         name: 'yarramate_check',
@@ -39,51 +90,6 @@ const tools = [
         },
         arguments: (input) => ['reconcile', String(input.workspace)],
     },
-    {
-        name: 'yarramate_context',
-        description: 'Bounded architecture context. Provide either a projection path or one or more globally qualified subjects (document-id#local-id) for an ad-hoc connected neighbourhood. Optional token budget switches to a compact ranked rendering.',
-        inputSchema: {
-            type: 'object',
-            required: ['workspace'],
-            properties: {
-                ...workspaceProperty,
-                projection: {
-                    type: 'string',
-                    description: 'Path to an authored projection definition',
-                },
-                subjects: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Globally qualified subject identities for ad-hoc context',
-                },
-                budget: {
-                    type: 'integer',
-                    minimum: 1,
-                    description: 'Approximate token budget for the compact rendering',
-                },
-            },
-        },
-        arguments: (input) => {
-            const budget = typeof input.budget === 'number'
-                ? ['--budget', String(input.budget)]
-                : [];
-            if (typeof input.projection === 'string') {
-                return [
-                    'context',
-                    input.projection,
-                    String(input.workspace),
-                    ...budget,
-                ];
-            }
-            const subjects = Array.isArray(input.subjects)
-                ? input.subjects.flatMap((subject) => [
-                    '--subject',
-                    String(subject),
-                ])
-                : [];
-            return ['context', ...subjects, String(input.workspace), ...budget];
-        },
-    },
 ];
 const respond = (id, result) => {
     process.stdout.write(`${JSON.stringify({ jsonrpc: '2.0', id, result })}\n`);

package/dist/apply-command.d.ts

@@ -0,0 +1,2 @@
+import { type CliResult } from './cli-support.js';
+export declare function runApplyCommand(options: readonly string[], cwd: string): CliResult;

package/dist/apply-command.js

@@ -0,0 +1,346 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { isMap, isScalar, isSeq, parseDocument, stringify, } from 'yaml';
+import Ajv2020Module from 'ajv/dist/2020.js';
+import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
+import { compileWorkspace } from './compiler.js';
+import { loadSourceDocument, locateSourcePath, } from './source-document.js';
+import { loadWorkspaceManifest } from './workspace.js';
+import operationsSchema from '../schema/yarramate-operations.schema.json' with {
+    type: 'json'
+};
+const Ajv2020 = Ajv2020Module.default;
+const validateOperations = new Ajv2020({ allErrors: true }).compile(operationsSchema);
+// Scalar fields replace; list fields append; `remove` retracts (ADR 0062).
+// An answer enriches what is there and may explicitly take back what it
+// asserted — it never silently shrinks anything.
+const SCALAR_CONCEPT_FIELDS = ['kind', 'name', 'description', 'status', 'owner'];
+const LIST_CONCEPT_FIELDS = ['constraints', 'references', 'presentIn', 'attestations'];
+const SCALAR_RELATIONSHIP_FIELDS = ['kind', 'from', 'to', 'name', 'description', 'status', 'mode', 'content'];
+const LIST_RELATIONSHIP_FIELDS = ['references', 'presentIn'];
+// ---------------------------------------------------------------------------
+// The splice layer. Every operation becomes a minimal text edit against the
+// document's current source, so bytes the batch never touched stay
+// byte-identical — an apply diff is exactly the answer it landed (#114).
+// The atomic compile gate below validates the spliced text itself, so any
+// splice defect rejects the batch loudly instead of corrupting a document.
+const lineStartOf = (source, offset) => source.lastIndexOf('\n', offset - 1) + 1;
+const indentAt = (source, offset) => offset - lineStartOf(source, offset);
+// End of the last line a node occupies, extended through its newline.
+const lineEndAfter = (source, offset) => {
+    const newline = source.indexOf('\n', Math.max(offset - 1, 0));
+    return newline === -1 ? source.length : newline + 1;
+};
+const reindent = (text, indent) => text.split('\n').join(`\n${' '.repeat(indent)}`);
+// A plain value as YAML source. lineWidth 0 keeps strings we author on one
+// line; genuinely multi-line strings become block scalars and are re-indented
+// by the caller.
+const valueText = (value) => stringify(value, { lineWidth: 0 }).trimEnd();
+const pairFor = (map, key) => map.items.find((pair) => isScalar(pair.key) && pair.key.value === key);
+const nodeRange = (node) => {
+    const range = node.range;
+    if (range === undefined) {
+        throw new Error('YAML node has no source range');
+    }
+    return range;
+};
+// Renders `items` as block sequence entries at the given marker indent.
+const sequenceEntries = (items, markerIndent) => {
+    const rendered = stringify(items, { lineWidth: 0 }).trimEnd();
+    return `${' '.repeat(markerIndent)}${reindent(rendered, markerIndent)}`;
+};
+const splice = (source, start, end, text) => source.slice(0, start) + text + source.slice(end);
+// Insert a newline-terminated block at a line boundary, tolerating a
+// source that does not end in a newline.
+const insertBlock = (source, insertAt, block) => splice(source, insertAt, insertAt, insertAt > 0 && source[insertAt - 1] !== '\n' ? `\n${block}` : block);
+// Node ranges may extend past their trailing newline to the start of the
+// next line; anchor insertions on the last CONTENT line instead.
+const afterContentLine = (source, offset) => {
+    let anchor = offset;
+    while (anchor > 0 && source[anchor - 1] === '\n')
+        anchor -= 1;
+    return lineEndAfter(source, anchor);
+};
+// Where a new field of an item lands: after the last line of the item's
+// final pair.
+const itemFieldInsertAt = (source, map) => {
+    const lastPair = map.items[map.items.length - 1];
+    const anchor = lastPair.value === null || lastPair.value === undefined
+        ? nodeRange(lastPair.key)[2]
+        : nodeRange(lastPair.value)[1];
+    return afterContentLine(source, anchor);
+};
+// Appends one item to a top-level block collection (`concepts:` or
+// `relationships:`), creating or converting the collection when needed.
+const appendCollectionItem = (source, collection, item) => {
+    const document = parseDocument(source);
+    const root = document.contents;
+    if (!isMap(root))
+        throw new Error('Document root is not a mapping');
+    const pair = pairFor(root, collection);
+    if (pair === undefined) {
+        const base = source.endsWith('\n') ? source : `${source}\n`;
+        return `${base}${collection}:\n${sequenceEntries([item], 2)}\n`;
+    }
+    const sequence = pair.value;
+    if (isSeq(sequence) && !sequence.flow && sequence.items.length > 0) {
+        const lastItem = sequence.items[sequence.items.length - 1];
+        const markerIndent = indentAt(source, nodeRange(lastItem)[0]) - 2;
+        const insertAt = lineEndAfter(source, nodeRange(lastItem)[2]);
+        return insertBlock(source, insertAt, `${sequenceEntries([item], markerIndent)}\n`);
+    }
+    if (!isSeq(sequence)) {
+        // `concepts:` with no value at all: append the block under the key.
+        const insertAt = lineEndAfter(source, nodeRange(pair.key)[2]);
+        return insertBlock(source, insertAt, `${sequenceEntries([item], 2)}\n`);
+    }
+    // Empty or flow collection: replace the whole value with a block
+    // sequence carrying any existing entries plus the new one, consuming
+    // the space that separated it from the key.
+    const existing = sequence.items.length > 0
+        ? sequence.toJSON()
+        : [];
+    let [start] = nodeRange(sequence);
+    const valueEnd = nodeRange(sequence)[1];
+    while (start > 0 && source[start - 1] === ' ')
+        start -= 1;
+    return splice(source, start, valueEnd, `\n${sequenceEntries([...existing, item], 2)}`);
+};
+const itemMap = (source, collection, id) => {
+    const document = parseDocument(source);
+    const root = document.contents;
+    if (!isMap(root))
+        return undefined;
+    const pair = pairFor(root, collection);
+    if (pair === undefined || !isSeq(pair.value))
+        return undefined;
+    const found = pair.value.items.find((candidate) => isMap(candidate) &&
+        candidate.items.some((field) => isScalar(field.key) &&
+            field.key.value === 'id' &&
+            isScalar(field.value) &&
+            field.value.value === id));
+    return found === undefined ? undefined : { map: found };
+};
+// The indent item fields sit at, read off the item's own first field.
+const fieldIndentOf = (source, map) => indentAt(source, nodeRange(map.items[0].key)[0]);
+const setScalarField = (source, map, key, value) => {
+    const indent = fieldIndentOf(source, map);
+    const rendered = reindent(valueText(value), indent + 2);
+    const pair = pairFor(map, key);
+    if (pair === undefined) {
+        return insertBlock(source, itemFieldInsertAt(source, map), `${' '.repeat(indent)}${key}: ${rendered}\n`);
+    }
+    const [start, valueEnd] = nodeRange(pair.value);
+    return splice(source, start, valueEnd, rendered);
+};
+const appendListField = (source, map, key, additions) => {
+    const indent = fieldIndentOf(source, map);
+    const pair = pairFor(map, key);
+    if (pair === undefined) {
+        return insertBlock(source, itemFieldInsertAt(source, map), `${' '.repeat(indent)}${key}:\n${sequenceEntries(additions, indent + 2)}\n`);
+    }
+    const sequence = pair.value;
+    if (isSeq(sequence) && !sequence.flow && sequence.items.length > 0) {
+        const lastItem = sequence.items[sequence.items.length - 1];
+        const markerIndent = indentAt(source, nodeRange(lastItem)[0]) - 2;
+        const insertAt = lineEndAfter(source, nodeRange(lastItem)[2]);
+        return insertBlock(source, insertAt, `${sequenceEntries(additions, markerIndent)}\n`);
+    }
+    const existing = isSeq(sequence) && sequence.items.length > 0
+        ? sequence.toJSON()
+        : [];
+    const merged = [...existing, ...additions];
+    const [start, valueEnd] = isSeq(sequence)
+        ? nodeRange(sequence)
+        : nodeRange(pair.value);
+    if (isSeq(sequence) && sequence.flow) {
+        const flow = stringify(merged, {
+            collectionStyle: 'flow',
+            lineWidth: 0,
+        }).trimEnd();
+        return splice(source, start, valueEnd, flow);
+    }
+    return splice(source, start, valueEnd, `\n${sequenceEntries(merged, indent + 2)}`);
+};
+// Retraction (#115): delete the field's whole entry, from the start of its
+// key line through the end of its value's last line.
+const removeField = (source, map, key) => {
+    const pair = pairFor(map, key);
+    if (pair === undefined)
+        return undefined;
+    const start = lineStartOf(source, nodeRange(pair.key)[0]);
+    const valueEnd = pair.value === null || pair.value === undefined
+        ? nodeRange(pair.key)[2]
+        : nodeRange(pair.value)[2];
+    return splice(source, start, lineEndAfter(source, valueEnd), '');
+};
+// ---------------------------------------------------------------------------
+export function runApplyCommand(options, cwd) {
+    const json = options.includes('--json');
+    const rest = options.filter((option) => option !== '--json');
+    const [operationsPath, workspacePath] = rest;
+    if (rest.length !== 2 ||
+        operationsPath === undefined ||
+        workspacePath === undefined ||
+        rest.some((option) => option.startsWith('-'))) {
+        return { exitCode: 2, stdout: '', stderr: usage };
+    }
+    try {
+        const manifestSource = readFileSync(resolve(cwd, workspacePath), 'utf8');
+        if (parseDocument(manifestSource).get('format') !== 'yarramate/workspace/v1') {
+            return {
+                exitCode: 2,
+                stdout: '',
+                stderr: 'apply requires an explicit workspace manifest (yarramate/workspace/v1)\n',
+            };
+        }
+        const failed = (diagnostics) => ({
+            exitCode: 1,
+            stdout: json ? diagnosticJson(diagnostics) : humanDiagnostics(diagnostics),
+            stderr: '',
+        });
+        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+        if (!loadedWorkspace.ok)
+            return failed(loadedWorkspace.diagnostics);
+        const workspace = loadedWorkspace.workspace;
+        const operationsSource = readFileSync(resolve(cwd, operationsPath), 'utf8');
+        const loadedOperations = loadSourceDocument({ path: operationsPath, source: operationsSource }, validateOperations, 'Operations');
+        if (!loadedOperations.ok)
+            return failed(loadedOperations.diagnostics);
+        const operations = loadedOperations.document.value.operations;
+        const yaml = loadedOperations.document.yaml;
+        const lineCounter = loadedOperations.document.lineCounter;
+        // Documents are addressed by their manifest paths; an operation aimed
+        // anywhere else is rejected before anything is touched.
+        const workspaceDocuments = new Map(workspace.documents.map((path) => [resolve(cwd, path), path]));
+        const candidates = new Map();
+        const counts = {
+            addedConcepts: 0,
+            addedRelationships: 0,
+            updatedConcepts: 0,
+            updatedRelationships: 0,
+        };
+        for (const [index, operation] of operations.entries()) {
+            const absolute = resolve(cwd, operation.document);
+            const manifestPath = workspaceDocuments.get(absolute);
+            const locate = (message) => ({
+                severity: 'error',
+                code: 'YM912',
+                message,
+                ...locateSourcePath(operationsPath, yaml, lineCounter, ['operations', index, 'document'], `/operations/${index}/document`),
+            });
+            if (manifestPath === undefined) {
+                return failed([
+                    locate(`Operation ${index} targets "${operation.document}", which is not a document of workspace "${workspace.id}"`),
+                ]);
+            }
+            let source = candidates.get(absolute);
+            if (source === undefined) {
+                source = readFileSync(absolute, 'utf8');
+            }
+            if (operation.op === 'add-concept') {
+                source = appendCollectionItem(source, 'concepts', operation.concept);
+                counts.addedConcepts += 1;
+            }
+            else if (operation.op === 'add-relationship') {
+                source = appendCollectionItem(source, 'relationships', operation.relationship);
+                counts.addedRelationships += 1;
+            }
+            else {
+                const collection = operation.op === 'update-concept' ? 'concepts' : 'relationships';
+                const payload = (operation.op === 'update-concept'
+                    ? operation.concept
+                    : operation.relationship);
+                const scalars = operation.op === 'update-concept'
+                    ? SCALAR_CONCEPT_FIELDS
+                    : SCALAR_RELATIONSHIP_FIELDS;
+                const lists = operation.op === 'update-concept'
+                    ? LIST_CONCEPT_FIELDS
+                    : LIST_RELATIONSHIP_FIELDS;
+                const id = payload.id;
+                const removals = operation.remove ?? [];
+                const contradiction = removals.find((key) => payload[key] !== undefined);
+                if (contradiction !== undefined) {
+                    return failed([
+                        locate(`Operation ${index} both sets and removes "${contradiction}" on "${id}"`),
+                    ]);
+                }
+                const located = itemMap(source, collection, id);
+                if (located === undefined) {
+                    return failed([
+                        locate(`Operation ${index} updates "${id}", which does not exist in ${operation.document}`),
+                    ]);
+                }
+                for (const key of scalars) {
+                    if (payload[key] === undefined)
+                        continue;
+                    source = setScalarField(source, itemMap(source, collection, id).map, key, payload[key]);
+                }
+                for (const key of lists) {
+                    const additions = payload[key];
+                    if (additions === undefined || additions.length === 0)
+                        continue;
+                    source = appendListField(source, itemMap(source, collection, id).map, key, additions);
+                }
+                for (const key of removals) {
+                    const removed = removeField(source, itemMap(source, collection, id).map, key);
+                    if (removed === undefined) {
+                        return failed([
+                            locate(`Operation ${index} removes "${key}", which is not set on "${id}"`),
+                        ]);
+                    }
+                    source = removed;
+                }
+                if (operation.op === 'update-concept') {
+                    counts.updatedConcepts += 1;
+                }
+                else {
+                    counts.updatedRelationships += 1;
+                }
+            }
+            candidates.set(absolute, source);
+        }
+        // The atomic gate: the whole candidate workspace must compile before a
+        // single byte is written; any diagnostic rejects the entire batch.
+        const compilation = compileWorkspace([...workspace.profiles, ...workspace.documents].map((path) => {
+            const absolute = resolve(cwd, path);
+            return {
+                path,
+                source: candidates.get(absolute) ?? readFileSync(absolute, 'utf8'),
+            };
+        }));
+        if (!compilation.ok)
+            return failed(compilation.diagnostics);
+        for (const [absolute, source] of candidates) {
+            writeFileSync(absolute, source, 'utf8');
+        }
+        const touched = [...candidates.keys()]
+            .map((absolute) => workspaceDocuments.get(absolute))
+            .sort();
+        if (json) {
+            return {
+                exitCode: 0,
+                stdout: `${JSON.stringify({
+                    format: 'yarramate/apply-result/v1',
+                    workspace: workspace.id,
+                    applied: counts,
+                    documents: touched,
+                }, null, 2)}\n`,
+                stderr: '',
+            };
+        }
+        const applied = counts.addedConcepts +
+            counts.addedRelationships +
+            counts.updatedConcepts +
+            counts.updatedRelationships;
+        return {
+            exitCode: 0,
+            stdout: `Applied ${applied} operation${applied === 1 ? '' : 's'} to ${touched.join(', ')}\n`,
+            stderr: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+}

package/dist/{new-command.d.ts → ask-command.d.ts}

@@ -1,2 +1,2 @@
 import { type CliResult } from './cli-support.js';
-export declare function runNewCommand(options: readonly string[], cwd: string): CliResult;
+export declare function runAskCommand(options: readonly string[], cwd: string): CliResult;