yarramate 0.3.3 → 0.5.0

package/dist/status-command.js

@@ -0,0 +1,171 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseDocument } from 'yaml';
+import { runCheckCommand } from './check-command.js';
+import { diagnosticJson, humanDiagnostics, usage, } from './cli-support.js';
+import { compileWorkspace } from './compiler.js';
+import { evaluateEvidenceWorkspace, loadEvidence } from './evidence.js';
+import { loadProjection } from './projection.js';
+import { reconcileEvidenceReports, } from './reconciliation.js';
+import { loadWorkspaceManifest } from './workspace.js';
+const plural = (count, singular, pluralForm) => `${count} ${count === 1 ? singular : (pluralForm ?? `${singular}s`)}`;
+export function runStatusCommand(options, cwd) {
+    const json = options.includes('--json');
+    const paths = options.filter((option) => option !== '--json');
+    const [workspacePath] = paths;
+    if (paths.length !== 1 ||
+        workspacePath === undefined ||
+        workspacePath.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: 'status requires an explicit workspace manifest (yarramate/workspace/v1)\n',
+            };
+        }
+        const loadedWorkspace = loadWorkspaceManifest({ path: workspacePath, source: manifestSource }, cwd);
+        if (!loadedWorkspace.ok) {
+            return {
+                exitCode: 1,
+                stdout: json
+                    ? diagnosticJson(loadedWorkspace.diagnostics)
+                    : humanDiagnostics(loadedWorkspace.diagnostics),
+                stderr: '',
+            };
+        }
+        const workspace = loadedWorkspace.workspace;
+        const checked = runCheckCommand([workspacePath, '--json'], cwd);
+        const checkPayload = JSON.parse(checked.stdout);
+        const projections = workspace.projections.map((path) => {
+            const loaded = loadProjection({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            });
+            return loaded.ok
+                ? {
+                    id: loaded.projection.id,
+                    path,
+                    ...(loaded.projection.presentation?.title === undefined
+                        ? {}
+                        : { title: loaded.projection.presentation.title }),
+                }
+                : { id: path, path };
+        });
+        let documents = workspace.documents.map((path) => ({ id: path, path }));
+        let states = [];
+        let reconciliation;
+        if (checkPayload.ok) {
+            const compilation = compileWorkspace([...workspace.profiles, ...workspace.documents].map((path) => ({
+                path,
+                source: readFileSync(resolve(cwd, path), 'utf8'),
+            })));
+            if (compilation.ok) {
+                const sourceByDocument = new Map(compilation.graph.documents.map((document) => [
+                    document.id,
+                    document.source,
+                ]));
+                documents = workspace.documents.map((path) => {
+                    const id = [...sourceByDocument.entries()].find(([, source]) => source === path)?.[0];
+                    return { id: id ?? path, path };
+                });
+                states = compilation.graph.claims
+                    .filter(({ predicate }) => predicate === 'yarramate/state/type')
+                    .map(({ subject, object }) => ({
+                    id: subject,
+                    type: 'value' in object && typeof object.value === 'string'
+                        ? object.value
+                        : 'baseline',
+                }));
+                if (workspace.evidence.length > 0) {
+                    const evidenceDocuments = workspace.evidence.flatMap((path) => {
+                        const loaded = loadEvidence({
+                            path,
+                            source: readFileSync(resolve(cwd, path), 'utf8'),
+                        });
+                        return loaded.ok ? [loaded.evidence] : [];
+                    });
+                    const evaluation = evaluateEvidenceWorkspace(compilation.graph, evidenceDocuments);
+                    if (evaluation.ok) {
+                        reconciliation = reconcileEvidenceReports(workspace.id, evaluation.reports, compilation.graph).summary;
+                    }
+                }
+            }
+        }
+        const result = {
+            format: 'yarramate/status-result/v1',
+            workspace: workspace.id,
+            ok: checkPayload.ok,
+            check: {
+                ok: checkPayload.ok,
+                diagnostics: checkPayload.ok ? [] : checkPayload.diagnostics,
+                ...(checkPayload.counted === undefined
+                    ? {}
+                    : { counted: checkPayload.counted }),
+            },
+            ...(reconciliation === undefined ? {} : { reconciliation }),
+            inventory: {
+                documents,
+                profiles: workspace.profiles,
+                states,
+                projections,
+                evidence: workspace.evidence,
+                adapterMappings: workspace.adapterMappings,
+                contracts: workspace.contracts,
+            },
+        };
+        if (json) {
+            return {
+                exitCode: result.ok ? 0 : 1,
+                stdout: `${JSON.stringify(result, null, 2)}\n`,
+                stderr: '',
+            };
+        }
+        const lines = [];
+        const counted = result.check.counted;
+        lines.push(`Workspace ${result.workspace}: check ${result.ok ? 'ok' : 'failing'}` +
+            (counted === undefined
+                ? ''
+                : ` (${plural(counted.concepts, 'concept')}, ` +
+                    `${plural(counted.relationships, 'relationship')}, ` +
+                    `${plural(counted.states, 'state')}, ` +
+                    `${plural(counted.documents, 'document')})`));
+        if (!result.ok) {
+            lines.push(`Diagnostics: ${plural(result.check.diagnostics.length, 'error')}; run \`yarramate check ${workspacePath}\` for details`);
+        }
+        if (result.reconciliation !== undefined) {
+            lines.push(`Reconciliation: ${plural(result.reconciliation.observations, 'observation')}, ` +
+                `${result.reconciliation.confirmed} confirmed, ` +
+                `${plural(result.reconciliation.findings, 'finding')}` +
+                (result.reconciliation.findings > 0
+                    ? ` (${result.reconciliation.contradicted} contradicted, ` +
+                        `${result.reconciliation.unknown} unknown, ` +
+                        `${result.reconciliation.notObserved} not observed)`
+                    : ''));
+        }
+        lines.push(`Documents: ${documents.map(({ id }) => id).join(', ') || 'none'}`);
+        if (states.length > 0) {
+            lines.push(`States: ${states.map(({ id, type }) => `${id} (${type})`).join(', ')}`);
+        }
+        lines.push(`Projections: ${projections
+            .map(({ id, title }) => title === undefined ? id : `${id} — ${title}`)
+            .join('; ') || 'none'}`);
+        lines.push(`Profiles: ${workspace.profiles.length} · ` +
+            `Evidence: ${workspace.evidence.length} · ` +
+            `Adapter mappings: ${workspace.adapterMappings.length} · ` +
+            `Contracts: ${workspace.contracts.length}`);
+        return {
+            exitCode: result.ok ? 0 : 1,
+            stdout: `${lines.join('\n')}\n`,
+            stderr: '',
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { exitCode: 2, stdout: '', stderr: `${message}\n` };
+    }
+}

package/docs/CONSUMING-YARRAMATE.md

@@ -143,3 +143,51 @@ yarramate-graphify observe \
 Graphify extraction remains a separate installation and operation. The
 adapter observes only explicitly mapped nodes and never promotes them into
 canonical architecture.
+
+## MCP server for agent harnesses
+
+Harnesses that load MCP servers can connect the bundled read-only adapter:
+
+```json
+{
+  "mcpServers": {
+    "yarramate": {
+      "command": "yarramate-mcp"
+    }
+  }
+}
+```
+
+It exposes `yarramate_status`, `yarramate_check`, `yarramate_reconcile`,
+and `yarramate_context` (projection path or ad-hoc subjects, with an
+optional token budget). Every tool call executes the same stable CLI in
+the server's working directory; nothing mutates native documents, and
+authoring stays with the CLI and Git review.
+
+## Continuous drift signal in CI
+
+The repository root ships a composite GitHub Action that checks the
+workspace and reports intent-vs-evidence drift on every pull request:
+
+```yaml
+name: architecture
+on: pull_request
+jobs:
+  drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: yarrasys/yarramate@main
+        with:
+          workspace: .yarramate/workspace.yaml
+```
+
+The job fails on deterministic correctness errors and, by default, when
+reconciliation reports contradicted claims; unknown and not-observed
+findings are reported in the job summary without failing. Set
+`fail-on-contradiction: 'false'` to make the whole signal advisory. The
+action never mutates sources — it runs only the read-only `check` and
+`reconcile` commands, so it is safe as a required check.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yarramate",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Tool-neutral semantic architecture engine and guided methodology",
   "license": "MIT",
   "repository": {
@@ -58,6 +58,7 @@
     "./schema/likec4-kind-mapping": "./schema/yarramate-likec4-kind-mapping.schema.json",
     "./schema/likec4-check-result": "./schema/yarramate-likec4-check-result.schema.json",
     "./schema/state-comparison": "./schema/yarramate-state-comparison.schema.json",
+    "./schema/status-result": "./schema/yarramate-status-result.schema.json",
     "./schema/graph-v2": "./schema/yarramate-graph-v2.schema.json",
     "./schema/workspace": "./schema/yarramate-workspace.schema.json",
     "./schema/evidence": "./schema/yarramate-evidence.schema.json",
@@ -69,7 +70,8 @@
   "bin": {
     "yarramate": "dist/cli.js",
     "yarramate-likec4": "dist/adapters/likec4-cli.js",
-    "yarramate-graphify": "dist/adapters/graphify-cli.js"
+    "yarramate-graphify": "dist/adapters/graphify-cli.js",
+    "yarramate-mcp": "dist/adapters/mcp-cli.js"
   },
   "packageManager": "pnpm@11.7.0",
   "engines": {
@@ -90,11 +92,11 @@
     "self:contract": "pnpm build && node dist/cli.js context .yarramate/projections/core-contract-foundation.yaml .yarramate/workspace.yaml",
     "self:evidence": "pnpm build && node dist/cli.js evidence .yarramate/evidence/repository.yaml .yarramate/workspace.yaml",
     "self:reconcile": "pnpm build && node dist/cli.js reconcile .yarramate/workspace.yaml",
-    "self:check:likec4": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/integrations/likec4/project.yaml .yarramate/workspace.yaml",
-    "self:check:likec4:json": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/integrations/likec4/project.yaml --json .yarramate/workspace.yaml",
-    "self:export:likec4": "pnpm build && node dist/adapters/likec4-cli.js export-project .yarramate/integrations/likec4/project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml",
+    "self:check:likec4": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/likec4-project.yaml .yarramate/workspace.yaml",
+    "self:check:likec4:json": "pnpm build && node dist/adapters/likec4-cli.js check .yarramate/likec4-project.yaml --json .yarramate/workspace.yaml",
+    "self:export:likec4": "pnpm build && node dist/adapters/likec4-cli.js export-project .yarramate/likec4-project.yaml .yarramate-out/likec4 .yarramate/workspace.yaml",
     "validate": "pnpm self:export:likec4 && likec4 validate --no-layout .yarramate-out/likec4",
-    "verify": "pnpm typecheck && pnpm test && pnpm self:check && pnpm validate",
+    "verify": "pnpm typecheck && pnpm build && pnpm test && pnpm self:check && pnpm validate",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"
   },

package/schema/yarramate-core-contract.schema.json

@@ -34,7 +34,11 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["id", "schema", "packageExport"],
+        "required": [
+          "id",
+          "schema",
+          "packageExport"
+        ],
         "properties": {
           "id": {
             "$ref": "#/$defs/formatIdentity"
@@ -55,14 +59,19 @@
       "items": {
         "type": "object",
         "additionalProperties": false,
-        "required": ["name", "binary"],
+        "required": [
+          "name",
+          "binary"
+        ],
         "properties": {
           "name": {
             "enum": [
               "init",
               "add",
               "connect",
+              "new",
               "check",
+              "status",
               "compile",
               "view",
               "context",

package/schema/yarramate-likec4-project.schema.json

@@ -41,7 +41,7 @@
     },
     "path": {
       "type": "string",
-      "description": "Repository-relative path resolved from the CLI working directory. Parent traversal, absolute paths, and backslashes are rejected.",
+      "description": "Path resolved from the project-definition document's directory, matching workspace-manifest semantics. Parent traversal, absolute paths, and backslashes are rejected, so references stay beneath the project document.",
       "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
     },
     "subjectIdentity": {

package/schema/yarramate-reconciliation-report.schema.json

@@ -66,6 +66,21 @@
         "message": { "type": "string", "minLength": 1 }
       }
     },
+    "subjectIdentity": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*#[a-z][a-z0-9]*(?:-[a-z0-9]+)*$"
+    },
+    "assertedRelationship": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["from", "to", "kind"],
+      "properties": {
+        "from": { "$ref": "#/$defs/subjectIdentity" },
+        "to": { "$ref": "#/$defs/subjectIdentity" },
+        "kind": { "type": "string", "pattern": "^\\S+$" },
+        "name": { "type": "string", "minLength": 1 }
+      }
+    },
     "finding": {
       "type": "object",
       "additionalProperties": false,
@@ -78,6 +93,7 @@
       ],
       "properties": {
         "target": { "$ref": "#/$defs/target" },
+        "asserted": { "$ref": "#/$defs/assertedRelationship" },
         "result": {
           "enum": ["contradicted", "unknown", "not-observed"]
         },

package/schema/yarramate-status-result.schema.json

@@ -0,0 +1,273 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yarramate.org/schema/status-result/v1",
+  "title": "YarraMate workspace status result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "format",
+    "workspace",
+    "ok",
+    "check",
+    "inventory"
+  ],
+  "properties": {
+    "format": {
+      "const": "yarramate/status-result/v1"
+    },
+    "workspace": {
+      "type": "string",
+      "minLength": 1
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "check": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ok",
+        "diagnostics"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "diagnostics": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/diagnostic"
+          }
+        },
+        "counted": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "documents",
+            "concepts",
+            "relationships",
+            "states"
+          ],
+          "properties": {
+            "documents": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "concepts": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "relationships": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "states": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        }
+      }
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "evidenceDocuments",
+        "observations",
+        "confirmed",
+        "findings",
+        "contradicted",
+        "unknown",
+        "notObserved"
+      ],
+      "properties": {
+        "evidenceDocuments": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "observations": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "confirmed": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "findings": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "contradicted": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "unknown": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "notObserved": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "inventory": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "documents",
+        "profiles",
+        "states",
+        "projections",
+        "evidence",
+        "adapterMappings",
+        "contracts"
+      ],
+      "properties": {
+        "documents": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "path"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "profiles": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "states": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "type"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "type": {
+                "enum": [
+                  "baseline",
+                  "transition",
+                  "target"
+                ]
+              }
+            }
+          }
+        },
+        "projections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "path"
+            ],
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1
+              },
+              "path": {
+                "type": "string",
+                "minLength": 1
+              },
+              "title": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "adapterMappings": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "contracts": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "diagnostic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "severity",
+        "code",
+        "message",
+        "path",
+        "pointer",
+        "line",
+        "column"
+      ],
+      "properties": {
+        "severity": {
+          "const": "error"
+        },
+        "code": {
+          "type": "string",
+          "pattern": "^YM[0-9]{3}$"
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pointer": {
+          "type": "string",
+          "pattern": "^/"
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "column": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    }
+  }
+}