yarramate 1.4.1 → 1.6.0

package/dist/adapters/visual/session-server.js

@@ -501,8 +501,9 @@ export const startVisualServer = async (options) => {
      * session instead of serving a stale graph.
      */
     const workspaceSources = () => {
+        let reading = "";
         try {
-            return [
+            const paths = [
                 ...resolvedWorkspace.profiles,
                 // Patterns are compiler input like profiles (#268). Without them a
                 // session recompiles a workspace the manifest does not describe: an
@@ -512,18 +513,46 @@ export const startVisualServer = async (options) => {
                 // rather than as a compile that failed.
                 ...resolvedWorkspace.patterns,
                 ...resolvedWorkspace.documents,
-            ].map((path) => ({
-                path,
-                source: readFileSync(resolve(options.cwd, path), "utf8"),
-            }));
+            ];
+            return {
+                ok: true,
+                sources: paths.map((path) => {
+                    reading = path;
+                    return {
+                        path,
+                        source: readFileSync(resolve(options.cwd, path), "utf8"),
+                    };
+                }),
+            };
         }
-        catch {
-            // A source that cannot be read is one whose diagnostics belong to no
-            // subject anyway, so an empty list is the right answer rather than a
-            // throw from a path that is only trying to add detail.
-            return [];
+        catch (cause) {
+            // Never an empty list. Compiling one SUCCEEDS - `compileWorkspaceResolved`
+            // over no sources returns an empty graph, not a failure - so swallowing
+            // the read error here made an unreadable workspace indistinguishable
+            // from an empty one, and the session then served "your model has nothing
+            // in it" as though it were an answer (#349). The older comment defended
+            // the empty list as belonging to a path "only trying to add detail";
+            // this feeds the single compile that produces what the browser draws.
+            return {
+                ok: false,
+                path: reading,
+                reason: cause instanceof Error ? cause.message : String(cause),
+            };
         }
     };
+    /**
+     * The sources, for attaching subjects to a diagnostic that already exists.
+     *
+     * Here an unreadable source really is nothing worth reporting: the caller is
+     * decorating a refusal it has already decided on, so a missing file costs a
+     * subject marker and nothing else. That was the whole of the old
+     * `workspaceSources` contract, and it stayed correct for exactly these two
+     * callers while being wrong for the compile (#349).
+     */
+    const sourcesForDetail = () => {
+        const read = workspaceSources();
+        return read.ok ? read.sources : [];
+    };
     /**
      * The digest of every projection the session knows about, read now.
      *
@@ -549,11 +578,22 @@ export const startVisualServer = async (options) => {
     };
     const recompileWorkspace = () => {
         try {
-            const sources = workspaceSources();
+            const read = workspaceSources();
+            if (!read.ok) {
+                return {
+                    ok: false,
+                    diagnostics: [
+                        serverDiagnostic("YMVS319", `Workspace source ${read.path} cannot be read, so the workspace was not recompiled; the last good model stays as it is: ${read.reason}`),
+                    ],
+                };
+            }
+            const sources = read.sources;
             const compiled = compileWorkspaceWithProfileContext(sources);
             if (!compiled.ok) {
-                compiledWorkspace = undefined;
-                return false;
+                return {
+                    ok: false,
+                    diagnostics: published(compiled.diagnostics, sources),
+                };
             }
             compiledWorkspace = {
                 graph: compiled.graph,
@@ -577,14 +617,36 @@ export const startVisualServer = async (options) => {
             // replacing the identity the session started with.
             views.splice(0, views.length, ...workspaceModel.views);
             rendered = workspaceModel.model;
-            return true;
+            // Recovered: a browser connecting now is not handed a fault that has
+            // been fixed since. The connected ones clear it on the `model` frame
+            // this success is about to broadcast.
+            standingDiagnostics = [];
+            return { ok: true };
         }
-        catch {
-            compiledWorkspace = undefined;
-            return false;
+        catch (cause) {
+            return {
+                ok: false,
+                diagnostics: [
+                    serverDiagnostic("YMVS319", `Workspace could not be recompiled, so the last good model stays as it is: ${cause instanceof Error ? cause.message : String(cause)}`),
+                ],
+            };
         }
     };
-    recompileWorkspace();
+    /**
+     * What the last recompile could not do, held for a browser that is not
+     * connected yet.
+     *
+     * The startup recompile runs before any socket exists, so a failure there
+     * has nobody to tell. Holding it means the first browser to arrive is told
+     * what every later one would have heard, rather than opening onto a session
+     * that looks well and answers nothing.
+     */
+    let standingDiagnostics = [];
+    {
+        const started = recompileWorkspace();
+        if (!started.ok)
+            standingDiagnostics = started.diagnostics;
+    }
     const filterMatchedIds = (query) => compiledWorkspace === undefined
         ? []
         : matchedIdsOf(compiledWorkspace.graph, query, compiledWorkspace.profileContext);
@@ -851,6 +913,36 @@ export const startVisualServer = async (options) => {
         for (const socket of connections.values())
             sendFrame(socket, frame);
     };
+    /**
+     * Tells the browser the workspace no longer compiles, and what said so.
+     *
+     * Journalled as an ordinary `diagnostic` response rather than a new frame
+     * kind, because that is the one the browser already renders - `Faults`
+     * reads `state.diagnostics`, which a `model` frame clears, so a recovered
+     * recompile clears the banner without anyone clearing it (#349). Held in
+     * `standingDiagnostics` too, for the browser that has not connected yet.
+     */
+    const reportRecompileFailure = async (diagnostics, eventId = drawHex(16)) => {
+        standingDiagnostics = diagnostics;
+        const response = {
+            format: "yarramate/visual-response/v1",
+            sessionId,
+            responseId: drawHex(16),
+            eventId,
+            type: "diagnostic",
+            timestamp: stamp(),
+            payload: { diagnostics },
+        };
+        const appended = await appendVisualResponse(paths, response);
+        if (appended.ok) {
+            transcriptBytes = appended.transcriptBytes;
+            recordResponse(response);
+            broadcast({ kind: "response", response });
+        }
+        else if (appended.freeze !== undefined) {
+            freeze(appended.freeze);
+        }
+    };
     const idleDelivery = () => ({
         waiting: true,
         lastSequence,
@@ -1172,8 +1264,17 @@ export const startVisualServer = async (options) => {
                         kind: "apply-result",
                         result: { ok: false, diagnostics: refused },
                     });
-                    if (recompileWorkspace())
+                    const refreshed = recompileWorkspace();
+                    if (refreshed.ok) {
                         broadcast({ kind: "model", model: rendered, views });
+                    }
+                    else {
+                        // Nothing at all reached the browser here before (#349): a refused
+                        // apply whose refresh also failed left the reviewer with a
+                        // refusal about their rows and no word that the workspace itself
+                        // had stopped compiling.
+                        await reportRecompileFailure(refreshed.diagnostics);
+                    }
                     return;
                 }
                 const operationsSource = stringify({
@@ -1193,7 +1294,7 @@ export const startVisualServer = async (options) => {
                         kind: "apply-result",
                         result: {
                             ok: false,
-                            diagnostics: published(loadedWorkspace.diagnostics, workspaceSources()),
+                            diagnostics: published(loadedWorkspace.diagnostics, sourcesForDetail()),
                         },
                     });
                     return;
@@ -1232,7 +1333,7 @@ export const startVisualServer = async (options) => {
                         kind: "apply-result",
                         result: {
                             ok: false,
-                            diagnostics: published(outcome.diagnostics, workspaceSources()),
+                            diagnostics: published(outcome.diagnostics, sourcesForDetail()),
                         },
                     });
                     return;
@@ -1249,7 +1350,8 @@ export const startVisualServer = async (options) => {
                     kind: "apply-result",
                     result: { ok: true, result: outcome.result },
                 });
-                if (recompileWorkspace()) {
+                const recompiled = recompileWorkspace();
+                if (recompiled.ok) {
                     broadcast({ kind: "model", model: rendered, views });
                     return;
                 }
@@ -1257,29 +1359,13 @@ export const startVisualServer = async (options) => {
                 // landed but produced a document Core itself can no longer parse.
                 // The freeze alone only tells the browser input is refused, not why
                 // the graph on screen has gone stale, so a diagnostic response is
-                // journaled alongside it.
-                const diagnosticResponse = {
-                    format: "yarramate/visual-response/v1",
-                    sessionId,
-                    responseId: drawHex(16),
-                    eventId: event.eventId,
-                    type: "diagnostic",
-                    timestamp: stamp(),
-                    payload: {
-                        diagnostics: [
-                            serverDiagnostic("YMVS310", "Workspace failed to recompile after a landed changeset"),
-                        ],
-                    },
-                };
-                const appendedResponse = await appendVisualResponse(paths, diagnosticResponse);
-                if (appendedResponse.ok) {
-                    transcriptBytes = appendedResponse.transcriptBytes;
-                    recordResponse(diagnosticResponse);
-                    broadcast({ kind: "response", response: diagnosticResponse });
-                }
-                else if (appendedResponse.freeze !== undefined) {
-                    freeze(appendedResponse.freeze);
-                }
+                // journaled alongside it - and it carries the compiler's OWN
+                // diagnostics, because YMVS310 by itself names no document, no code
+                // and no line (#349).
+                await reportRecompileFailure([
+                    serverDiagnostic("YMVS310", "Workspace failed to recompile after a landed changeset"),
+                    ...recompiled.diagnostics,
+                ], event.eventId);
                 freeze("recompile-failed");
                 return;
             }
@@ -1431,6 +1517,22 @@ export const startVisualServer = async (options) => {
                 return;
             }
             sendFrame(socket, { kind: "ready", snapshot: snapshot() });
+            // A recompile that failed before this socket existed - the one at
+            // startup, most often - has had nobody to tell until now (#349).
+            if (standingDiagnostics.length > 0) {
+                sendFrame(socket, {
+                    kind: "response",
+                    response: {
+                        format: "yarramate/visual-response/v1",
+                        sessionId,
+                        responseId: drawHex(16),
+                        eventId: drawHex(16),
+                        type: "diagnostic",
+                        timestamp: stamp(),
+                        payload: { diagnostics: standingDiagnostics },
+                    },
+                });
+            }
         });
     };
     // ------------------------------------------------------------- agent routes

package/dist/ask-command.js

@@ -471,7 +471,7 @@ export function runAskCommand(options, cwd) {
             const loadedCatalogue = loadQuestionCatalogue({
                 path: shippedCataloguePath,
                 source: readFileSync(shippedCataloguePath, 'utf8'),
-            });
+            }, compilation.profileContext);
             if (!loadedCatalogue.ok)
                 return failed(loadedCatalogue.diagnostics);
             const report = evaluateCatalogue(loadedCatalogue.catalogue, compilation.graph, compilation.profileContext, evidenceDocuments.flatMap(({ observations }) => observations));
@@ -701,7 +701,7 @@ export function runAskCommand(options, cwd) {
             const loadedCatalogue = loadQuestionCatalogue({
                 path: cataloguePath ?? resolvedCataloguePath,
                 source: readFileSync(resolvedCataloguePath, 'utf8'),
-            });
+            }, compilation.profileContext);
             if (!loadedCatalogue.ok)
                 return failed(loadedCatalogue.diagnostics);
             // The evidence overlay rides along for the one condition that
@@ -996,7 +996,7 @@ export function runAskCommand(options, cwd) {
         const loadedCatalogue = loadQuestionCatalogue({
             path: cataloguePath ?? resolvedCataloguePath,
             source: readFileSync(resolvedCataloguePath, 'utf8'),
-        });
+        }, compilation.profileContext);
         if (!loadedCatalogue.ok)
             return failed(loadedCatalogue.diagnostics);
         // Loaded ahead of evaluation so the overlay feeds the one condition

package/dist/cli-support.d.ts

@@ -7,7 +7,7 @@ export interface CliResult {
 export declare const isMainModule: (moduleUrl: string, entrypoint: string | undefined) => boolean;
 export declare const packageVersion: string;
 export declare const versionResult: (binary: string) => CliResult;
-export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
+export declare const usage = "Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> \"<free text>\" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise \"<topic>\" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where \"<free text>\" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n";
 export declare const diagnosticJson: (diagnostics: unknown) => string;
 export declare const checkResultJson: (ok: boolean, diagnostics: unknown, counted?: {
     readonly documents: number;

package/dist/cli-support.js

@@ -22,7 +22,7 @@ export const versionResult = (binary) => ({
     stdout: `${binary} ${packageVersion}\n`,
     stderr: '',
 });
-export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
+export const usage = 'Usage:\n  yarramate init <directory> [--no-pointer]\n  yarramate design <workspace.yaml> [--subject <subject-id>] [--catalogue <catalogue.yaml>] [--facilitate] [--json]\n  yarramate apply <operations.yaml> <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> [--json]\n  yarramate ask <workspace.yaml> "<free text>" | <subject-id> ... | <projection.yaml> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate ask <workspace.yaml> --subjects [--kind <term>] [--status <status>] [--json]\n  yarramate ask <workspace.yaml> --kinds [--json]\n  yarramate ask <workspace.yaml> --advise "<topic>" [--budget <tokens>] [--neighbours <n>] [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --where "<free text>" | <subject-id> ... [--json]\n  yarramate ask <workspace.yaml> --next [--json]\n  yarramate ask <workspace.yaml> --open [--catalogue <catalogue.yaml>] [--json]\n  yarramate ask <workspace.yaml> --compare <from-state> <to-state> [--json]\n  yarramate ask <workspace.yaml> --changed <git-range> [--budget <tokens>] [--neighbours <n>] [--json]\n  yarramate check <source.yaml> [source.yaml ...] [--json] [--strict]\n  yarramate reconcile <workspace.yaml> [--json]\n  yarramate export graph <workspace.yaml> [--out <file>]\n  yarramate export markdown <projection.yaml> <workspace.yaml> [--out <file>]\n  yarramate export markdown --changed <git-range> <workspace.yaml> [--out <file>]\n  yarramate export briefs <projection.yaml> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export briefs --changed <git-range> <workspace.yaml> --out <directory> [--budget <tokens>]\n  yarramate export rtm <workspace.yaml> --out <directory>\n  yarramate export xlsx <projection.yaml> <workspace.yaml> --out <file>\n  yarramate import xlsx <workbook.xlsx> <workspace.yaml> [--json]\n  yarramate export likec4 <likec4-project.yaml> <output-dir> <workspace.yaml> [--changed <git-range>]\n';
 export const diagnosticJson = (diagnostics) => `${JSON.stringify({
     format: 'yarramate/diagnostic-result/v1',
     diagnostics,

package/dist/cli.d.ts

@@ -3,3 +3,13 @@ import { type CliResult } from './cli-support.js';
 export type { CliResult } from './cli-support.js';
 export declare const deriveInitId: (directory: string) => string;
 export declare function runCli(args: readonly string[], cwd?: string): CliResult;
+/**
+ * Every verb, including the one that cannot be synchronous.
+ *
+ * `import xlsx` has to inflate a workbook, and the only inflater available
+ * everywhere this runs is `DecompressionStream`, which is async. Widening
+ * `runCli` to return a promise would change the type every one of its callers
+ * reads - the readers half of the rule in CONTRIBUTING.md - so the async verb
+ * gets its own entry and `runCli` keeps its signature.
+ */
+export declare function runCliAsync(args: readonly string[], cwd?: string): Promise<CliResult>;

package/dist/cli.js

@@ -5,6 +5,7 @@ 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 { runImportCommand } from './import-command.js';
 import { runExportCommand } from './export-command.js';
 import { runApplyCommand } from './apply-cli.js';
 import { runDesignCommand } from './design-command.js';
@@ -227,8 +228,23 @@ export function runCli(args, cwd = process.cwd()) {
     }
     return { exitCode: 2, stdout: '', stderr: usage };
 }
+/**
+ * Every verb, including the one that cannot be synchronous.
+ *
+ * `import xlsx` has to inflate a workbook, and the only inflater available
+ * everywhere this runs is `DecompressionStream`, which is async. Widening
+ * `runCli` to return a promise would change the type every one of its callers
+ * reads - the readers half of the rule in CONTRIBUTING.md - so the async verb
+ * gets its own entry and `runCli` keeps its signature.
+ */
+export async function runCliAsync(args, cwd = process.cwd()) {
+    const [command, ...options] = args;
+    if (command === 'import')
+        return runImportCommand(options, cwd);
+    return runCli(args, cwd);
+}
 if (isMainModule(import.meta.url, process.argv[1])) {
-    const result = runCli(process.argv.slice(2));
+    const result = await runCliAsync(process.argv.slice(2));
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);
     process.exitCode = result.exitCode;

package/dist/design-command.js

@@ -191,12 +191,10 @@ export function runDesignCommand(options, cwd) {
         const resolvedCataloguePath = cataloguePath === undefined
             ? shippedCataloguePath
             : resolve(cwd, cataloguePath);
-        const loadedCatalogue = loadQuestionCatalogue({
-            path: cataloguePath ?? resolvedCataloguePath,
-            source: readFileSync(resolvedCataloguePath, 'utf8'),
-        });
-        if (!loadedCatalogue.ok)
-            return failed(loadedCatalogue.diagnostics);
+        // Compiled BEFORE the catalogue loads, so the catalogue can be checked
+        // against the vocabulary its kinds are written against (#351). A
+        // catalogue naming a kind its own profile does not have loads clean
+        // otherwise, and the question it names is dead on arrival.
         const compilation = compileWorkspaceWithProfileContext([
             ...workspace.profiles,
             ...workspace.patterns,
@@ -207,6 +205,12 @@ export function runDesignCommand(options, cwd) {
         })));
         if (!compilation.ok)
             return failed(compilation.diagnostics);
+        const loadedCatalogue = loadQuestionCatalogue({
+            path: cataloguePath ?? resolvedCataloguePath,
+            source: readFileSync(resolvedCataloguePath, 'utf8'),
+        }, compilation.profileContext);
+        if (!loadedCatalogue.ok)
+            return failed(loadedCatalogue.diagnostics);
         // The evidence overlay rides along for the one condition that reads
         // it (unchallenged-evidence). A workspace declaring no evidence
         // passes an empty overlay — known to be empty, which keeps that

package/dist/export-command.js

@@ -1,16 +1,18 @@
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseDocument } from 'yaml';
 import { renderBrief } from './brief.js';
 import { deriveChangedSubjects } from './changed.js';
-import { humanDiagnostics, usage } from './cli-support.js';
+import { humanDiagnostics, packageVersion, usage, } from './cli-support.js';
 import { compileWorkspaceWithProfileContext, } from './compiler.js';
 import { serializeSemanticGraph } from './graph.js';
 import { evaluateEvidenceWorkspace, loadEvidence, } from './evidence.js';
 import { evaluateProjection, loadProjection, renderProjectionMarkdown, } from './projection.js';
 import { buildRtm, renderRtmMarkdown } from './rtm.js';
+import { workbookFrom } from './workbook.js';
 import { loadWorkspaceManifest } from './workspace.js';
 // The adapter stays a separate process behind the verb: the core never
 // imports adapter code (the adapter-runtime-dependency exclusion), it
@@ -74,7 +76,7 @@ const parseExportOptions = (options) => {
 export function runExportCommand(options, cwd) {
     const [kind, ...rest] = options;
     if (kind === undefined ||
-        !['graph', 'markdown', 'briefs', 'rtm', 'likec4'].includes(kind)) {
+        !['graph', 'markdown', 'briefs', 'rtm', 'likec4', 'xlsx'].includes(kind)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     const parsed = parseExportOptions(rest);
@@ -128,7 +130,8 @@ export function runExportCommand(options, cwd) {
         parsed.json ||
         (usesChanged && (kind === 'graph' || kind === 'rtm')) ||
         (parsed.budget !== undefined && kind !== 'briefs') ||
-        ((kind === 'briefs' || kind === 'rtm') && parsed.out === undefined)) {
+        ((kind === 'briefs' || kind === 'rtm' || kind === 'xlsx') &&
+            parsed.out === undefined)) {
         return { exitCode: 2, stdout: '', stderr: usage };
     }
     try {
@@ -149,14 +152,17 @@ export function runExportCommand(options, cwd) {
         if (!loadedWorkspace.ok)
             return failed(loadedWorkspace.diagnostics);
         const workspace = loadedWorkspace.workspace;
-        const compilation = compileWorkspaceWithProfileContext([
+        // Named rather than inlined so the workbook can pin its digests against
+        // exactly the bytes that compiled, the way a visual commit does (#355).
+        const sources = [
             ...workspace.profiles,
             ...workspace.patterns,
             ...workspace.documents,
         ].map((path) => ({
             path,
             source: readFileSync(resolve(cwd, path), 'utf8'),
-        })));
+        }));
+        const compilation = compileWorkspaceWithProfileContext(sources);
         if (!compilation.ok)
             return failed(compilation.diagnostics);
         if (kind === 'rtm') {
@@ -246,6 +252,36 @@ export function runExportCommand(options, cwd) {
                 return failed(loadedProjection.diagnostics);
             result = evaluateProjection(compilation.graph, loadedProjection.projection, compilation.profileContext);
         }
+        if (kind === 'xlsx') {
+            // A workbook an architect can work in (#355). It takes a PROJECTION,
+            // like markdown and briefs do, which is what gives it version selection
+            // for free: a projection query already has a `states` facet, so
+            // "export the target state" is an existing capability rather than a
+            // flag competing with it.
+            const bytes = workbookFrom(result, {
+                workspace: workspace.id,
+                yarramateVersion: packageVersion,
+                sourceDigests: Object.fromEntries(sources.map(({ path, source }) => [
+                    path,
+                    createHash('sha256').update(source, 'utf8').digest('hex'),
+                ])),
+                conceptKinds: [
+                    ...compilation.profileContext.conceptKindLineages.keys(),
+                ].sort(),
+                relationshipKinds: [
+                    ...compilation.profileContext.relationshipKindLineages.keys(),
+                ].sort(),
+                statuses: ['planned', 'current', 'retired'],
+            });
+            const outPath = resolve(cwd, parsed.out);
+            mkdirSync(dirname(outPath), { recursive: true });
+            writeFileSync(outPath, bytes);
+            return {
+                exitCode: 0,
+                stdout: `Wrote workbook to ${parsed.out}\n`,
+                stderr: '',
+            };
+        }
         if (kind === 'markdown') {
             const rendered = renderProjectionMarkdown(result, compilation.profileContext);
             if (parsed.out === undefined) {

package/dist/import-command.d.ts

@@ -0,0 +1,16 @@
+import { type CliResult } from './cli-support.js';
+/**
+ * `yarramate import xlsx <file> <workspace.yaml>` (#355, ADR 0127).
+ *
+ * The workbook carries its own ancestor, so this is a three-way merge rather
+ * than an overwrite: the author's edits are measured against `~Baseline`, the
+ * repository's drift is measured against the same, and only a field both moved
+ * is refused. Everything the author changed that the repository left alone
+ * merges cleanly, which is what makes a week-long workbook cycle usable.
+ *
+ * Edits land as `yarramate/operations/v1` through `apply`, so untouched YAML
+ * keeps its comments, key order and formatting, and the whole import passes
+ * the atomic compile gate. A workbook that would produce an uncompilable model
+ * is refused whole rather than half written.
+ */
+export declare function runImportCommand(options: readonly string[], cwd: string): Promise<CliResult>;