yarramate 0.23.0 → 1.0.0

package/dist/adapters/visual/workspace-model.js

@@ -0,0 +1,212 @@
+import { stringify } from "yaml";
+import { loadProjection } from "../../projection.js";
+import { withDiagnosticSubjects } from "../../compiler.js";
+import { posixDirectoryOf } from "../../apply-command.js";
+import { projectGraphForCanvas } from "../../graph-projection.js";
+import { DEFAULT_PROJECTION_DIRECTORY } from "./view-identity.js";
+import { evaluateProjection, explainProjection } from "../../projection.js";
+import { kindLabelOf } from "../../kind-label.js";
+/**
+ * What a workspace looks like to the editor, however the editor is being run
+ * (#252).
+ *
+ * These were the session server's, and the session server is one host now: an
+ * embedder mounting the editor over its own store computes the same model, the
+ * same vocabulary and the same view counts, and two definitions of any of them
+ * would be two answers to the same question. So the arithmetic lives here and
+ * the orchestration - which bytes to read, which digests to pin, what a layout
+ * sidecar says - stays with whoever owns those.
+ *
+ * Browser-safe: no `node:`, no filesystem, no session. Everything is a pure
+ * function of a compile result.
+ */
+/**
+ * The kinds a browser may offer, each with the core kind it descends from.
+ *
+ * `[0]` is the nearest declared ancestor, the same reading
+ * `projectGraphForCanvas` gives an authored subject its `coreKindLabel`. A kind
+ * with no lineage IS a core kind and stands for itself. Without the core label
+ * an editor can read a palette but cannot judge it: the ArchiMate table is
+ * keyed on core kinds, so offering an extension kind unchecked puts a `YM404`
+ * one click away.
+ */
+export const kindOptionsOf = (lineages) => [...lineages.keys()].map((id) => ({
+    id,
+    label: kindLabelOf(id),
+    coreLabel: kindLabelOf(lineages.get(id)?.[0] ?? id),
+}));
+/**
+ * How many SUBJECTS a query matches, which is not the size of its match set.
+ *
+ * A `SemanticGraph`'s subjects are concepts and relationships together, so the
+ * match set returns both — right for narrowing a canvas that draws edges as
+ * well as nodes, and wrong for a number sitting beside a view called its
+ * subject count. A view over three components with two relationships between
+ * them would read as five, and the reviewer counting boxes would find three.
+ */
+export const conceptCountOf = (graph, query, profileContext) => evaluateProjection(graph, adHoc(query), profileContext).subjects.filter(({ type }) => type === "concept").length;
+/**
+ * Rebuilds the shared editor workspace from one successful compile.
+ *
+ * The caller owns metadata which cannot be inferred from a graph (authority,
+ * source revisions, layouts, and initial view); this helper owns all derived
+ * canvas, vocabulary, and view-count arithmetic.
+ */
+export const renderedWorkspaceOf = (compiled, views, metadata) => {
+    const refreshedViews = views.map((view) => ({
+        ...view,
+        subjectCount: conceptCountOf(compiled.graph, view.query, compiled.profileContext),
+    }));
+    return {
+        model: {
+            ...metadata,
+            graph: projectGraphForCanvas(compiled.graph, compiled.profileContext),
+            vocabulary: {
+                conceptKinds: kindOptionsOf(compiled.profileContext.conceptKindLineages),
+                relationshipKinds: kindOptionsOf(compiled.profileContext.relationshipKindLineages),
+            },
+        },
+        views: refreshedViews,
+    };
+};
+/** Every subject a query draws, concepts and relationships alike. */
+export const matchedIdsOf = (graph, query, profileContext) => evaluateProjection(graph, adHoc(query), profileContext).subjects.map(({ id }) => id);
+/** Every concept a query dropped, and the facet that dropped it (#248). */
+export const exclusionsOf = (graph, query, profileContext) => explainProjection(graph, adHoc(query), profileContext);
+/**
+ * A query on its own is not a projection, and every evaluator here wants one.
+ * The id is a placeholder that never reaches a document.
+ */
+const adHoc = (query) => ({
+    format: "yarramate/projection/v1",
+    id: "ad-hoc",
+    version: "0",
+    query,
+});
+/**
+ * One saved view, as the rail reads it. `subjectCount` is the caller's,
+ * because counting needs a compiled graph and a session builds its first list
+ * before it has one.
+ */
+export const viewSummaryOf = (projection, path, subjectCount = 0) => ({
+    id: projection.id,
+    title: projection.presentation?.title ?? projection.id,
+    description: projection.presentation?.description ?? "",
+    query: projection.query,
+    presentation: projection.presentation,
+    path,
+    subjectCount,
+});
+/**
+ * Applies a landed view batch to a host-owned list.
+ *
+ * Writes are read back through the callback, so a malformed or otherwise
+ * unreadable landed document cannot become a fabricated summary.
+ */
+export const adoptLandedViews = (views, operations, readSummary) => {
+    const next = [...views];
+    for (const operation of operations) {
+        const at = next.findIndex((view) => view.path === operation.path);
+        if (operation.op === "delete-view") {
+            if (at !== -1)
+                next.splice(at, 1);
+            continue;
+        }
+        const summary = readSummary(operation.path);
+        if (summary === undefined)
+            continue;
+        if (at === -1)
+            next.push(summary);
+        else
+            next[at] = summary;
+    }
+    return next;
+};
+/**
+ * The document a diagnostic the runtime minted itself points at. Not a file:
+ * these are about the session rather than about anything the workspace holds.
+ */
+export const VISUAL_SERVER_DOCUMENT = "visual-session-server";
+export const published = (diagnostics, sources) => withDiagnosticSubjects(diagnostics, sources);
+export const serverDiagnostic = (code, message, pointer = "/") => ({
+    severity: "error",
+    code,
+    message,
+    path: VISUAL_SERVER_DOCUMENT,
+    pointer,
+    line: 1,
+    column: 1,
+});
+/**
+ * Whether the workspace would load a projection written at this path.
+ *
+ * This is a DIRECTORY check, not a pattern match, and deliberately so: ADR
+ * 0100 recorded that the manifest's pattern dialect has never been named - it
+ * is whatever `globSync` happens to support, undocumented and untested past
+ * one wildcard - so a matcher written here would be inventing the dialect
+ * rather than honouring it. A directory that already holds a projection the
+ * manifest resolved is a directory the manifest demonstrably reaches.
+ *
+ * A workspace with no projections at all has nothing to demonstrate, so the
+ * default directory is allowed: refusing there would make the first view in a
+ * fresh workspace impossible to create.
+ */
+export const projectionDirectoryIsCovered = (path, workspace) => {
+    if (workspace.projections.length === 0) {
+        return posixDirectoryOf(path) === DEFAULT_PROJECTION_DIRECTORY;
+    }
+    const covered = new Set(workspace.projections.map(posixDirectoryOf));
+    return covered.has(posixDirectoryOf(path));
+};
+/**
+ * Turns staged view operations into pending writes, refusing before anything
+ * is written (ADR 0103).
+ *
+ * A `write-view` is validated through the same `loadProjection` the CLI's own
+ * projection writes go through, so a document the schema would reject never
+ * reaches the store. A `delete-view` names a revision, which is what makes a
+ * removal refusable rather than a silent success on a file someone else
+ * already changed.
+ */
+export const planViewWrites = (operations, workspace, store) => {
+    const writes = [];
+    const diagnostics = [];
+    for (const operation of operations) {
+        const held = store.read(operation.path);
+        if (operation.op === "delete-view") {
+            if (held === undefined) {
+                diagnostics.push(serverDiagnostic("YMVS314", `View "${operation.path}" is already gone`));
+                continue;
+            }
+            writes.push({
+                path: operation.path,
+                source: null,
+                expected: held.revision,
+            });
+            continue;
+        }
+        if (held === undefined &&
+            !projectionDirectoryIsCovered(operation.path, workspace)) {
+            // A projection no pattern reaches is a file the workspace never loads,
+            // which is worse than a refusal because nothing later says so (ADR 0043).
+            diagnostics.push(serverDiagnostic("YMVS315", `The workspace manifest covers no projection in "${posixDirectoryOf(operation.path)}", so a view saved there would never load`));
+            continue;
+        }
+        const source = stringify(operation.projection);
+        const loaded = loadProjection({ path: operation.path, source });
+        if (!loaded.ok) {
+            // The composed document is the only source these are about, so they are
+            // published against it rather than against the workspace.
+            diagnostics.push(...published(loaded.diagnostics, [{ path: operation.path, source }]));
+            continue;
+        }
+        writes.push({
+            path: operation.path,
+            source,
+            expected: held?.revision ?? null,
+        });
+    }
+    return diagnostics.length > 0
+        ? { ok: false, diagnostics }
+        : { ok: true, writes };
+};

package/dist/adapters/visual-cli.d.ts

@@ -30,7 +30,7 @@ export interface VisualStartIo {
  * Serves one visual session in the foreground.
  *
  * The request is validated before any filesystem or network effect, so a bad
- * document costs nothing. Exactly one public `visual-session-started/v1` line is
+ * document costs nothing. Exactly one public `visual-session-started/v2` line is
  * published before the command blocks — it names the private descriptor but
  * never carries the agent capability, which lives only in that mode 0600 file.
  * The command then holds the session open until the runtime closes it, whether

package/dist/adapters/visual-cli.js

@@ -10,11 +10,14 @@ export const visualUsage = 'Usage:\n' +
     '  yarramate-visual request [--view <id>] [--title <text>]\n' +
     '                           [--description <text>] [--chat]\n' +
     '  yarramate-visual start <request.json>\n' +
-    '  yarramate-visual wait <descriptor.json> [--after <sequence>]\n' +
-    '  yarramate-visual respond <descriptor.json> <response.json>\n' +
-    '  yarramate-visual status <descriptor.json>\n' +
-    '  yarramate-visual recover <descriptor.json> [--transcript]\n' +
-    '  yarramate-visual stop <descriptor.json> [--transcript]\n' +
+    '  yarramate-visual wait <descriptor-uri> [--after <sequence>]\n' +
+    '  yarramate-visual respond <descriptor-uri> <response.json>\n' +
+    '  yarramate-visual status <descriptor-uri>\n' +
+    '  yarramate-visual recover <descriptor-uri> [--transcript]\n' +
+    '  yarramate-visual stop <descriptor-uri> [--transcript]\n' +
+    '\n' +
+    '<descriptor-uri> is the `descriptorPath` file: URI `start` published,\n' +
+    'copied back verbatim. It is never resolved against the working directory.\n' +
     '  yarramate-visual --version\n';
 /**
  * Where a repository keeps its live sessions, one directory per session. It sits
@@ -126,11 +129,11 @@ const requestCliCommand = (rest, cwd) => {
         return refusalResult(built.diagnostics);
     return { exitCode: 0, stdout: documentLine(built.request), stderr: '' };
 };
-const waitCliCommand = async (descriptorPath, rest, cwd) => {
+const waitCliCommand = async (descriptorUri, rest) => {
     const after = sequenceFlag(rest);
     if (after === undefined)
         return usageResult;
-    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    const descriptor = await readVisualSessionDescriptor(descriptorUri);
     if (!descriptor.ok)
         return refusalResult(descriptor.diagnostics);
     const delivery = await waitForVisualEvent(descriptor.value, after);
@@ -144,13 +147,16 @@ const waitCliCommand = async (descriptorPath, rest, cwd) => {
         stderr: '',
     };
 };
-const respondCliCommand = async (descriptorPath, rest, cwd) => {
+const respondCliCommand = async (descriptorUri, rest, cwd) => {
     const [responsePath, ...trailing] = rest;
     if (responsePath === undefined || trailing.length > 0)
         return usageResult;
-    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    const descriptor = await readVisualSessionDescriptor(descriptorUri);
     if (!descriptor.ok)
         return refusalResult(descriptor.diagnostics);
+    // The response document is the agent's own file, named however the agent
+    // likes: it is not a protocol path field, so it stays a native path
+    // resolved against `cwd`.
     const document = await readVisualJsonDocument(responsePath, cwd);
     if (!document.ok)
         return refusalResult(document.diagnostics);
@@ -164,10 +170,10 @@ const respondCliCommand = async (descriptorPath, rest, cwd) => {
         return refusalResult(accepted.diagnostics);
     return { exitCode: 0, stdout: documentLine(accepted.value), stderr: '' };
 };
-const statusCliCommand = async (descriptorPath, rest, cwd) => {
+const statusCliCommand = async (descriptorUri, rest) => {
     if (rest.length > 0)
         return usageResult;
-    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    const descriptor = await readVisualSessionDescriptor(descriptorUri);
     if (!descriptor.ok)
         return refusalResult(descriptor.diagnostics);
     const status = await fetchVisualStatus(descriptor.value);
@@ -175,11 +181,11 @@ const statusCliCommand = async (descriptorPath, rest, cwd) => {
         return refusalResult(status.diagnostics);
     return { exitCode: 0, stdout: documentLine(status.value), stderr: '' };
 };
-const recoverCliCommand = async (descriptorPath, rest, cwd) => {
+const recoverCliCommand = async (descriptorUri, rest) => {
     const includeTranscript = transcriptFlag(rest);
     if (includeTranscript === undefined)
         return usageResult;
-    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    const descriptor = await readVisualSessionDescriptor(descriptorUri);
     if (!descriptor.ok)
         return refusalResult(descriptor.diagnostics);
     const handoff = await recoverVisualSessionClient(descriptor.value, includeTranscript);
@@ -201,13 +207,13 @@ const recoverCliCommand = async (descriptorPath, rest, cwd) => {
  * descriptor that did not parse, and a corrupt, redirected, or foreign
  * descriptor fails exactly as before.
  */
-const stopCliCommand = async (descriptorPath, rest, cwd) => {
+const stopCliCommand = async (descriptorUri, rest) => {
     const includeTranscript = transcriptFlag(rest);
     if (includeTranscript === undefined)
         return usageResult;
-    const descriptor = await readVisualSessionDescriptor(descriptorPath, cwd);
+    const descriptor = await readVisualSessionDescriptor(descriptorUri);
     if (!descriptor.ok) {
-        return (await visualSessionAlreadyStopped(descriptorPath, cwd))
+        return (await visualSessionAlreadyStopped(descriptorUri))
             ? { exitCode: 0, stdout: '', stderr: '' }
             : refusalResult(descriptor.diagnostics);
     }
@@ -236,17 +242,20 @@ export async function runVisualClientCli(args, cwd = process.cwd()) {
         return requestCliCommand(args.slice(1), cwd);
     if (descriptor === undefined)
         return usageResult;
+    // `cwd` reaches only the commands that still read a native path of their
+    // own. The descriptor argument is a `file:` URI and is never resolved
+    // against anything.
     switch (command) {
         case 'wait':
-            return waitCliCommand(descriptor, rest, cwd);
+            return waitCliCommand(descriptor, rest);
         case 'respond':
             return respondCliCommand(descriptor, rest, cwd);
         case 'status':
-            return statusCliCommand(descriptor, rest, cwd);
+            return statusCliCommand(descriptor, rest);
         case 'recover':
-            return recoverCliCommand(descriptor, rest, cwd);
+            return recoverCliCommand(descriptor, rest);
         case 'stop':
-            return stopCliCommand(descriptor, rest, cwd);
+            return stopCliCommand(descriptor, rest);
         default:
             return usageResult;
     }
@@ -259,7 +268,7 @@ const processIo = {
  * Serves one visual session in the foreground.
  *
  * The request is validated before any filesystem or network effect, so a bad
- * document costs nothing. Exactly one public `visual-session-started/v1` line is
+ * document costs nothing. Exactly one public `visual-session-started/v2` line is
  * published before the command blocks — it names the private descriptor but
  * never carries the agent capability, which lives only in that mode 0600 file.
  * The command then holds the session open until the runtime closes it, whether

package/dist/apply-cli.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-cli.js

@@ -0,0 +1,83 @@
+/**
+ * The `apply` command, and the only part of applying a batch that touches a
+ * filesystem.
+ *
+ * It lives apart from `./apply-command.js` for the reason `./nesting.js` and
+ * `./kind-label.js` state for their own values: the engine half is reachable
+ * from a browser now (#252), and a top-level `node:fs` import is a bundle
+ * failure whether or not the function that uses it is ever called. Core reads
+ * nothing (ADR 0100) - this is the caller that reads for it.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseDocument } from 'yaml';
+import { landOperations, posixDirectoryOf } from './apply-command.js';
+import { createFileSystemStore } from './source-store.js';
+import { loadWorkspaceManifest } from './workspace.js';
+import { diagnosticJson, humanDiagnostics, usage } from './cli-support.js';
+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 operationsSource = readFileSync(resolve(cwd, operationsPath), 'utf8');
+        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+        if (!loadedWorkspace.ok) {
+            return {
+                exitCode: 1,
+                stdout: json
+                    ? diagnosticJson(loadedWorkspace.diagnostics)
+                    : humanDiagnostics(loadedWorkspace.diagnostics),
+                stderr: '',
+            };
+        }
+        const outcome = landOperations(createFileSystemStore(cwd), {
+            workspace: loadedWorkspace.workspace,
+            operations: { path: operationsPath, source: operationsSource },
+            manifestDirectory: posixDirectoryOf(workspacePath),
+        });
+        if (!outcome.ok) {
+            return {
+                exitCode: 1,
+                stdout: json
+                    ? diagnosticJson(outcome.diagnostics)
+                    : humanDiagnostics(outcome.diagnostics),
+                stderr: '',
+            };
+        }
+        const { result } = outcome;
+        if (json) {
+            return {
+                exitCode: 0,
+                stdout: `${JSON.stringify(result, null, 2)}\n`,
+                stderr: '',
+            };
+        }
+        // Every counter, summed by iteration rather than by hand, so a new
+        // operation kind cannot silently report zero work.
+        const applied = Object.values(result.applied).reduce((total, count) => total + count, 0);
+        return {
+            exitCode: 0,
+            stdout: `Applied ${applied} operation${applied === 1 ? '' : 's'} to ${result.documents.join(', ')}\n`,
+            stderr: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+}

package/dist/apply-command.d.ts

@@ -1,12 +1,93 @@
-import { type CliResult } from './cli-support.js';
 import { type Diagnostic, type WorkspaceSource } from './compiler.js';
+import type { ResolvedWorkspace } from './workspace.js';
+import { type PendingWrite, type SourceStore, type WriteConflict } from './source-store.js';
+/**
+ * The directory part of a workspace path, in the `/`-separated terms a
+ * manifest is written in rather than the platform's.
+ *
+ * Both separators by hand rather than `node:path`'s `sep`: this module is
+ * reachable from a browser (#252), where there is no platform separator to
+ * ask about, and a manifest path is `/`-separated wherever it is read.
+ */
+export declare const posixDirectoryOf: (path: string) => string;
 import type { YarramateApplyResult } from './operations.js';
 export type ApplyOutcome = {
     readonly ok: true;
+    /**
+     * The documents this batch changed, for the caller to write. Core
+     * returns them rather than writing them, so the store's comparison is
+     * the last thing that happens before bytes land (ADR 0100).
+     */
+    readonly sources: readonly WorkspaceSource[];
     readonly result: YarramateApplyResult;
 } | {
     readonly ok: false;
     readonly diagnostics: readonly Diagnostic[];
 };
-export declare const applyOperations: (operations: WorkspaceSource, workspace: WorkspaceSource, cwd: string) => ApplyOutcome;
-export declare function runApplyCommand(options: readonly string[], cwd: string): CliResult;
+/**
+ * Everything `applyOperations` is allowed to know. The workspace is already
+ * resolved and the sources are already read, because Core does not reach for
+ * either (ADR 0100).
+ */
+export interface ApplyInput {
+    /** The workspace this batch is addressed to, already resolved. */
+    readonly workspace: ResolvedWorkspace;
+    /** Every source that workspace resolves to, keyed by its manifest path. */
+    readonly sources: readonly WorkspaceSource[];
+    /** The operations document itself. */
+    readonly operations: WorkspaceSource;
+    /**
+     * Where the manifest sits relative to the paths in `workspace`, so an
+     * operation may address a document the way the manifest names it as well as
+     * the way the workspace lists it (#216). String arithmetic, not a lookup.
+     */
+    readonly manifestDirectory: string;
+}
+export declare const applyOperations: (input: ApplyInput) => ApplyOutcome;
+export type PlannedOperations = {
+    readonly ok: true;
+    readonly outcome: ApplyOutcome & {
+        readonly ok: true;
+    };
+    /** What this batch would write, unwritten. Empty when it changes nothing. */
+    readonly writes: readonly PendingWrite[];
+} | {
+    readonly ok: false;
+    readonly outcome: ApplyOutcome & {
+        readonly ok: false;
+    };
+};
+/**
+ * Reads a workspace through a store and applies a batch, stopping short of
+ * writing (ADR 0100).
+ *
+ * Separated from {@link landOperations} because a caller may have writes of
+ * its own to land in the same batch: the visual runtime commits a projection
+ * beside the model it belongs to, and one `writeAll` is what makes the two
+ * arrive together or not at all (ADR 0103). A caller with nothing to add wants
+ * `landOperations` and should not see this.
+ */
+export declare const planOperations: (store: SourceStore, input: {
+    readonly workspace: ResolvedWorkspace;
+    readonly operations: WorkspaceSource;
+    readonly manifestDirectory: string;
+}) => PlannedOperations;
+/**
+ * The diagnostics a refused `writeAll` becomes, in the workspace range
+ * (ADR 0100). Shared so a caller that merges writes of its own into the batch
+ * reports a conflict the same way the CLI does.
+ */
+export declare const writeConflictDiagnostics: (conflicts: readonly WriteConflict[], operationsPath: string) => readonly Diagnostic[];
+/**
+ * Reads a workspace through a store, applies a batch, and writes what changed
+ * back only if every document still holds what was read (ADR 0100).
+ *
+ * This is the composition Core deliberately does not perform: `applyOperations`
+ * is a pure function, and the comparison that decides whether a batch lands
+ * belongs to the store.
+ */
+export declare const landOperations: (store: SourceStore, input: {
+    readonly workspace: ResolvedWorkspace;
+    readonly operations: WorkspaceSource;
+    readonly manifestDirectory: string;
+}) => ApplyOutcome;