@maadb/core 0.0.1 → 0.7.9

package/dist/cli/index.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// ============================================================================
+// MAAD CLI — Command dispatch
+// ============================================================================
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cmdScan, cmdSummary, cmdDescribe } from './commands/discover.js';
+import { cmdGet, cmdQuery, cmdSearch, cmdRelated, cmdSchema } from './commands/read.js';
+import { cmdCreate, cmdUpdate } from './commands/write.js';
+import { cmdInit, cmdValidate, cmdReindex, cmdParse } from './commands/maintain.js';
+import { cmdHistory, cmdAudit } from './commands/audit.js';
+import { cmdAuth } from './commands/auth.js';
+import { startServer } from '../mcp/server.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Parse --project / --instance flags (env vars MAAD_PROJECT / MAAD_INSTANCE as fallbacks).
+// --project and --instance are mutually exclusive. If neither is supplied, `serve` errors out;
+// other commands still default --project to cwd for backward compatibility.
+const rawArgs = process.argv.slice(2);
+let projectRoot = process.env['MAAD_PROJECT'];
+let instancePath = process.env['MAAD_INSTANCE'];
+const args = [];
+for (let i = 0; i < rawArgs.length; i++) {
+    if (rawArgs[i] === '--project' && rawArgs[i + 1]) {
+        projectRoot = rawArgs[i + 1];
+        i++;
+    }
+    else if (rawArgs[i] === '--instance' && rawArgs[i + 1]) {
+        instancePath = rawArgs[i + 1];
+        i++;
+    }
+    else {
+        args.push(rawArgs[i]);
+    }
+}
+if (projectRoot && instancePath) {
+    console.error('Error: --project and --instance are mutually exclusive.');
+    process.exit(1);
+}
+// Non-serve commands still need a default project when neither flag is set.
+if (!projectRoot && !instancePath)
+    projectRoot = '.';
+const ctx = { args, projectRoot: projectRoot ?? '.', __dirname };
+const command = args[0];
+async function main() {
+    switch (command) {
+        // Discover
+        case 'scan':
+            await cmdScan(ctx);
+            break;
+        case 'summary':
+            await cmdSummary(ctx);
+            break;
+        case 'describe':
+            await cmdDescribe(ctx);
+            break;
+        // Read
+        case 'get':
+            await cmdGet(ctx);
+            break;
+        case 'query':
+            await cmdQuery(ctx);
+            break;
+        case 'search':
+            await cmdSearch(ctx);
+            break;
+        case 'related':
+            await cmdRelated(ctx);
+            break;
+        case 'schema':
+            await cmdSchema(ctx);
+            break;
+        // Write
+        case 'create':
+            await cmdCreate(ctx);
+            break;
+        case 'update':
+            await cmdUpdate(ctx);
+            break;
+        // Maintain
+        case 'init':
+            await cmdInit(ctx);
+            break;
+        case 'validate':
+            await cmdValidate(ctx);
+            break;
+        case 'reindex':
+            await cmdReindex(ctx);
+            break;
+        case 'parse':
+            await cmdParse(ctx);
+            break;
+        // Audit
+        case 'history':
+            await cmdHistory(ctx);
+            break;
+        case 'audit':
+            await cmdAudit(ctx);
+            break;
+        // Auth (0.7.0)
+        case 'auth':
+            await cmdAuth({ instancePath, args });
+            break;
+        // MCP
+        case 'serve':
+            await cmdServe();
+            break;
+        case 'help':
+        case '--help':
+        case '-h':
+        case undefined:
+            printHelp();
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+function parseIntEnv(val, fallback) {
+    if (val === undefined || val === '')
+        return fallback;
+    const n = Number.parseInt(val, 10);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+async function cmdServe() {
+    let role = process.env['MAAD_ROLE'];
+    let dryRun = false;
+    let provenance = process.env['MAAD_PROV'];
+    let transport = process.env['MAAD_TRANSPORT'] ?? 'stdio';
+    let httpHost = process.env['MAAD_HTTP_HOST'] ?? '127.0.0.1';
+    let httpPort = parseIntEnv(process.env['MAAD_HTTP_PORT'], 7733);
+    let httpMaxBody = parseIntEnv(process.env['MAAD_HTTP_MAX_BODY'], 1_048_576);
+    let headersTimeoutMs = parseIntEnv(process.env['MAAD_HTTP_HEADERS_TIMEOUT_MS'], 10_000);
+    let requestTimeoutMs = parseIntEnv(process.env['MAAD_HTTP_REQUEST_TIMEOUT_MS'], 60_000);
+    let keepAliveTimeoutMs = parseIntEnv(process.env['MAAD_HTTP_KEEPALIVE_TIMEOUT_MS'], 5_000);
+    let idleMs = parseIntEnv(process.env['MAAD_SESSION_IDLE_MS'], 1_800_000);
+    let trustProxy = process.env['MAAD_TRUST_PROXY'] === '1' || process.env['MAAD_TRUST_PROXY'] === 'true';
+    let authToken = process.env['MAAD_AUTH_TOKEN'];
+    // 0.7.5 (fup-2026-148) — Unix-socket transport
+    let socketPath = process.env['MAAD_UNIX_SOCKET'];
+    let socketMode = (() => {
+        const raw = process.env['MAAD_UNIX_SOCKET_MODE'];
+        if (!raw)
+            return undefined;
+        const n = Number.parseInt(raw, 8);
+        return Number.isFinite(n) && n > 0 ? n : undefined;
+    })();
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const next = args[i + 1];
+        if (a === '--role' && next)
+            role = next;
+        else if (a === '--dry-run')
+            dryRun = true;
+        else if (a === '--prov' && next)
+            provenance = next;
+        else if (a === '--transport' && next)
+            transport = next;
+        else if (a === '--http-host' && next)
+            httpHost = next;
+        else if (a === '--http-port' && next)
+            httpPort = parseIntEnv(next, httpPort);
+        else if (a === '--http-max-body' && next)
+            httpMaxBody = parseIntEnv(next, httpMaxBody);
+        else if (a === '--http-headers-timeout' && next)
+            headersTimeoutMs = parseIntEnv(next, headersTimeoutMs);
+        else if (a === '--http-request-timeout' && next)
+            requestTimeoutMs = parseIntEnv(next, requestTimeoutMs);
+        else if (a === '--http-keepalive-timeout' && next)
+            keepAliveTimeoutMs = parseIntEnv(next, keepAliveTimeoutMs);
+        else if (a === '--session-idle-ms' && next)
+            idleMs = parseIntEnv(next, idleMs);
+        else if (a === '--trust-proxy')
+            trustProxy = true;
+        else if (a === '--auth-token' && next)
+            authToken = next;
+        else if (a === '--unix-socket' && next)
+            socketPath = next;
+        else if (a === '--unix-socket-mode' && next) {
+            const n = Number.parseInt(next, 8);
+            if (Number.isFinite(n) && n > 0)
+                socketMode = n;
+        }
+    }
+    if (transport !== 'stdio' && transport !== 'http' && transport !== 'unix') {
+        console.error(`Error: --transport must be 'stdio', 'http', or 'unix' (got '${transport}')`);
+        process.exit(1);
+    }
+    if (transport === 'unix' && (!socketPath || socketPath.length === 0)) {
+        console.error("Error: --transport unix requires --unix-socket=<path> or MAAD_UNIX_SOCKET env");
+        process.exit(1);
+    }
+    // 0.7.0 — HTTP boot-mode enforcement moved to server.ts (needs TokenStore).
+    // CLI just passes authToken through; server validates via checkHttpAuthAtBoot.
+    const base = {
+        role,
+        dryRun,
+        provenance,
+        transport,
+        ...(transport === 'http' || transport === 'unix' ? {
+            http: {
+                host: httpHost,
+                port: httpPort,
+                maxBodyBytes: httpMaxBody,
+                headersTimeoutMs,
+                requestTimeoutMs,
+                keepAliveTimeoutMs,
+                trustProxy,
+                idleMs,
+                authToken,
+                ...(transport === 'unix' ? { socketPath, socketMode } : {}),
+            },
+        } : {}),
+    };
+    if (instancePath) {
+        await startServer({ ...base, instancePath: path.resolve(instancePath) });
+    }
+    else if (projectRoot) {
+        await startServer({ ...base, projectRoot: path.resolve(projectRoot) });
+    }
+    else {
+        console.error('Error: `serve` requires --project <dir> or --instance <path>.');
+        process.exit(1);
+    }
+}
+function printHelp() {
+    console.log(`
+MAAD — Markdown As A Database
+
+Usage: maad <command> [options]
+
+Commands:
+  init [dir]                        Initialize a new MAAD project
+  scan <file.md|dir>                 Analyze raw markdown (no registry needed)
+  summary                           Project snapshot (types, counts, sample IDs, object inventory)
+  describe                          Show project overview
+  get <doc_id> [depth] [block]      Read a document (hot/warm/cold/full)
+  query <type> [--filter k=v]       Find documents by type and filters
+  search <primitive> [opts]         Search extracted objects (--subtype, --value, --contains, --doc)
+  related <doc_id> [direction]      Show related documents
+  schema <type>                     Show field definitions for a type (for writes)
+  create <type> --field k=v [...]   Create a new document
+  update <doc_id> --field k=v [...] Update a document's fields or body
+  validate [doc_id]                 Validate one or all documents
+  reindex [--force]                 Rebuild the index from markdown
+  parse <file.md>                   Parse a file and print the result
+  history <doc_id>                  Show git history for a document
+  audit [--since date]              Show project-wide activity
+  serve [--transport stdio|http] [--role ...] [--prov ...]  Start MCP server
+
+Options:
+  --project <dir>                   Single-project mode (default for CLI cmds: cwd)
+  --instance <path>                 Multi-project mode: path to instance.yaml (serve only)
+  --role <role>                     MCP server role in single-project mode (default: reader)
+  --force                           Force full reindex (skip hash check)
+  --help                            Show this help
+
+serve HTTP options (when --transport http or --transport unix):
+  --transport <stdio|http|unix>     Transport selection (default: stdio)
+  --http-host <host>                Bind address for http (default: 127.0.0.1)
+  --http-port <port>                Bind port for http (default: 7733)
+  --unix-socket <path>              Unix socket path (required for unix transport)
+  --unix-socket-mode <octal>        Socket file mode (default: 660)
+  --auth-token <token>              Bearer token (required for http/unix; prefer MAAD_AUTH_TOKEN env)
+  --http-max-body <bytes>           Max request body bytes (default: 1048576)
+  --http-headers-timeout <ms>       node:http headersTimeout (default: 10000)
+  --http-request-timeout <ms>       node:http requestTimeout (default: 60000)
+  --http-keepalive-timeout <ms>     node:http keepAliveTimeout (default: 5000)
+  --session-idle-ms <ms>            Per-session idle eviction threshold (default: 1800000 = 30 min)
+  --trust-proxy                     Use X-Forwarded-For first hop for remote IP in logs (http only)
+
+Environment Variables:
+  MAAD_PROJECT                      Project root (fallback for --project)
+  MAAD_INSTANCE                     Path to instance.yaml (fallback for --instance)
+  MAAD_ROLE                         Server role (fallback for --role)
+  MAAD_PROV                         Provenance mode (fallback for --prov)
+  MAAD_TRANSPORT                    stdio | http | unix (default: stdio)
+  MAAD_HTTP_HOST                    HTTP bind host (default: 127.0.0.1)
+  MAAD_HTTP_PORT                    HTTP bind port (default: 7733)
+  MAAD_UNIX_SOCKET                  Unix socket path (required when MAAD_TRANSPORT=unix)
+  MAAD_UNIX_SOCKET_MODE             Socket file mode in octal (default: 660)
+  MAAD_AUTH_TOKEN                   Bearer token for HTTP/UDS transport (required)
+  MAAD_SESSION_IDLE_MS              Per-session idle eviction threshold (default: 1800000)
+  MAAD_HTTP_MAX_BODY                HTTP max body bytes (default: 1048576)
+  MAAD_HTTP_HEADERS_TIMEOUT_MS      headersTimeout ms (default: 10000)
+  MAAD_HTTP_REQUEST_TIMEOUT_MS      requestTimeout ms (default: 60000)
+  MAAD_HTTP_KEEPALIVE_TIMEOUT_MS    keepAliveTimeout ms (default: 5000)
+  MAAD_TRUST_PROXY                  1|true to trust X-Forwarded-For (default: false)
+`);
+}
+main().catch(e => {
+    console.error(e);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './cli/index.js';
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAMA,OAAO,gBAAgB,CAAC"}

package/dist/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// ============================================================================
+// Re-export from cli/ directory.
+// All code lives in src/cli/*.ts — this file is the entry point passthrough.
+// ============================================================================
+import './cli/index.js';
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,+EAA+E;AAC/E,iCAAiC;AACjC,6EAA6E;AAC7E,+EAA+E;AAE/E,OAAO,gBAAgB,CAAC"}

package/dist/engine/audit.d.ts

@@ -0,0 +1,15 @@
+import { type Result } from '../errors.js';
+import { type DocId, type DocType, type ParsedCommit, type AuditEntry, type DiffResult, type SnapshotResult } from '../types.js';
+import type { EngineContext } from './context.js';
+export declare function history(ctx: EngineContext, id: DocId, opts?: {
+    limit?: number;
+    since?: string;
+}): Promise<Result<ParsedCommit[]>>;
+export declare function diff(ctx: EngineContext, id: DocId, from: string, to?: string): Promise<Result<DiffResult>>;
+export declare function snapshot(ctx: EngineContext, id: DocId, at: string): Promise<Result<SnapshotResult>>;
+export declare function audit(ctx: EngineContext, opts?: {
+    since?: string;
+    until?: string;
+    docType?: DocType;
+}): Promise<Result<AuditEntry[]>>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/engine/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/engine/audit.ts"],"names":[],"mappings":"AAMA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAEL,KAAK,KAAK,EACV,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,cAAc,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,wBAAsB,OAAO,CAC3B,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,KAAK,EACT,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,CAAC,CAAC,CAQjC;AAED,wBAAsB,IAAI,CACxB,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,KAAK,EACT,IAAI,EAAE,MAAM,EACZ,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAS7B;AAED,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,aAAa,EAClB,EAAE,EAAE,KAAK,EACT,EAAE,EAAE,MAAM,GACT,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC,CASjC;AAED,wBAAsB,KAAK,CACzB,GAAG,EAAE,aAAa,EAClB,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAC3D,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,CAK/B"}

package/dist/engine/audit.js

@@ -0,0 +1,42 @@
+// ============================================================================
+// Audit — history, diff, snapshot, audit (git-backed)
+// ============================================================================
+import { ok, singleErr } from '../errors.js';
+export async function history(ctx, id, opts) {
+    if (!ctx.gitLayer)
+        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+    const doc = ctx.backend.getDocument(id);
+    if (!doc)
+        return singleErr('FILE_NOT_FOUND', `Document "${id}" not found`);
+    const commits = await ctx.gitLayer.history(doc.filePath, opts);
+    return ok(commits);
+}
+export async function diff(ctx, id, from, to) {
+    if (!ctx.gitLayer)
+        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+    const doc = ctx.backend.getDocument(id);
+    if (!doc)
+        return singleErr('FILE_NOT_FOUND', `Document "${id}" not found`);
+    const result = await ctx.gitLayer.diff(doc.filePath, id, from, to);
+    if (!result)
+        return singleErr('GIT_ERROR', 'Failed to compute diff');
+    return ok(result);
+}
+export async function snapshot(ctx, id, at) {
+    if (!ctx.gitLayer)
+        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+    const doc = ctx.backend.getDocument(id);
+    if (!doc)
+        return singleErr('FILE_NOT_FOUND', `Document "${id}" not found`);
+    const result = await ctx.gitLayer.snapshot(doc.filePath, id, at);
+    if (!result)
+        return singleErr('GIT_ERROR', 'Failed to retrieve snapshot');
+    return ok(result);
+}
+export async function audit(ctx, opts) {
+    if (!ctx.gitLayer)
+        return singleErr('GIT_NOT_INITIALIZED', 'Git is not available in this project');
+    const entries = await ctx.gitLayer.audit(opts);
+    return ok(entries);
+}
+//# sourceMappingURL=audit.js.map

package/dist/engine/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../../src/engine/audit.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,sDAAsD;AACtD,+EAA+E;AAI/E,OAAO,EAAE,EAAE,EAAE,SAAS,EAAe,MAAM,cAAc,CAAC;AAY1D,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,GAAkB,EAClB,EAAS,EACT,IAAyC;IAEzC,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,gBAAgB,EAAE,aAAa,EAAY,aAAa,CAAC,CAAC;IAErF,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,QAAkB,EAAE,IAAI,CAAC,CAAC;IACzE,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CACxB,GAAkB,EAClB,EAAS,EACT,IAAY,EACZ,EAAW;IAEX,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,gBAAgB,EAAE,aAAa,EAAY,aAAa,CAAC,CAAC;IAErF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAkB,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC;IAC7E,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC,WAAW,EAAE,wBAAwB,CAAC,CAAC;IACrE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAkB,EAClB,EAAS,EACT,EAAU;IAEV,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,gBAAgB,EAAE,aAAa,EAAY,aAAa,CAAC,CAAC;IAErF,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAkB,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC3E,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC,WAAW,EAAE,6BAA6B,CAAC,CAAC;IAC1E,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;AACpB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,KAAK,CACzB,GAAkB,EAClB,IAA4D;IAE5D,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC,qBAAqB,EAAE,sCAAsC,CAAC,CAAC;IAEnG,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,OAAO,EAAE,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC"}

package/dist/engine/composites.d.ts

@@ -0,0 +1,6 @@
+import { type Result } from '../errors.js';
+import { type DocId } from '../types.js';
+import type { EngineContext } from './context.js';
+import type { GetFullResult } from './types.js';
+export declare function getDocumentFull(ctx: EngineContext, id: DocId): Promise<Result<GetFullResult>>;
+//# sourceMappingURL=composites.d.ts.map

package/dist/engine/composites.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"composites.d.ts","sourceRoot":"","sources":["../../src/engine/composites.ts"],"names":[],"mappings":"AAKA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,EAEL,KAAK,KAAK,EACX,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,wBAAsB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CA+FnG"}

package/dist/engine/composites.js

@@ -0,0 +1,102 @@
+// ============================================================================
+// Composites — Tier 2 deterministic bundled reads (provisional)
+// Evaluate after MCP: keep only if they measurably reduce tool chatter.
+// ============================================================================
+import { ok, singleErr } from '../errors.js';
+import { docId as toDocId, } from '../types.js';
+import { logger } from './logger.js';
+import { readFrontmatter } from './helpers.js';
+export async function getDocumentFull(ctx, id) {
+    const doc = ctx.backend.getDocument(id);
+    if (!doc)
+        return singleErr('FILE_NOT_FOUND', `Document "${id}" not found`);
+    const frontmatter = await readFrontmatter(ctx.projectRoot, doc);
+    // Resolve ref fields to names
+    const schema = ctx.schemaStore.getSchemaForType(doc.docType);
+    const resolvedRefs = {};
+    if (schema) {
+        for (const [fieldName, fieldDef] of schema.fields) {
+            if (fieldDef.type === 'ref' && frontmatter[fieldName]) {
+                const targetId = String(frontmatter[fieldName]);
+                const targetDoc = ctx.backend.getDocument(toDocId(targetId));
+                if (targetDoc) {
+                    const targetFm = await readFrontmatter(ctx.projectRoot, targetDoc);
+                    resolvedRefs[fieldName] = {
+                        docId: targetId,
+                        name: String(targetFm['name'] ?? targetFm['title'] ?? targetId),
+                    };
+                }
+            }
+        }
+    }
+    const objects = ctx.backend.findObjects({ docId: id, limit: 50 });
+    const rels = ctx.backend.getRelationships(id, 'both');
+    // Batch lookup all related doc IDs
+    const relatedIds = new Set();
+    for (const rel of rels) {
+        if (rel.sourceDocId === id)
+            relatedIds.add(rel.targetDocId);
+        else
+            relatedIds.add(rel.sourceDocId);
+    }
+    const docsMap = ctx.backend.getDocumentsByIds([...relatedIds]);
+    const outgoing = [];
+    const incoming = [];
+    for (const rel of rels) {
+        if (rel.sourceDocId === id) {
+            const target = docsMap.get(rel.targetDocId);
+            outgoing.push({
+                docId: rel.targetDocId,
+                docType: (target?.docType ?? 'unknown'),
+                field: rel.field,
+            });
+        }
+        else {
+            const source = docsMap.get(rel.sourceDocId);
+            incoming.push({
+                docId: rel.sourceDocId,
+                docType: (source?.docType ?? 'unknown'),
+                field: rel.field,
+            });
+        }
+    }
+    // Latest incoming note
+    let latestNote = null;
+    if (ctx.gitLayer) {
+        for (const inc of incoming) {
+            const incDoc = docsMap.get(toDocId(inc.docId));
+            if (!incDoc)
+                continue;
+            if (!(inc.docType.includes('note')))
+                continue;
+            try {
+                const history = await ctx.gitLayer.history(incDoc.filePath, { limit: 1 });
+                if (history.length > 0) {
+                    const entry = history[0];
+                    if (!latestNote || entry.timestamp > latestNote.timestamp) {
+                        latestNote = {
+                            docId: inc.docId,
+                            summary: entry.summary,
+                            timestamp: entry.timestamp,
+                        };
+                    }
+                }
+            }
+            catch (e) {
+                logger.bestEffort('composites', 'getDocumentFull.latestNote', `Git history lookup failed for ${inc.docId}`, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+    }
+    return ok({
+        docId: doc.docId,
+        docType: doc.docType,
+        version: doc.version,
+        updatedAt: doc.updatedAt,
+        frontmatter,
+        resolvedRefs,
+        objects,
+        related: { outgoing, incoming },
+        latestNote,
+    });
+}
+//# sourceMappingURL=composites.js.map

package/dist/engine/composites.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composites.js","sourceRoot":"","sources":["../../src/engine/composites.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,gEAAgE;AAChE,wEAAwE;AACxE,+EAA+E;AAE/E,OAAO,EAAE,EAAE,EAAE,SAAS,EAAe,MAAM,cAAc,CAAC;AAC1D,OAAO,EACL,KAAK,IAAI,OAAO,GAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,CAAC,KAAK,UAAU,eAAe,CAAC,GAAkB,EAAE,EAAS;IACjE,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC,gBAAgB,EAAE,aAAa,EAAY,aAAa,CAAC,CAAC;IAErF,MAAM,WAAW,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,CAAC;IAEhE,8BAA8B;IAC9B,MAAM,MAAM,GAAG,GAAG,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAC7D,MAAM,YAAY,GAAoD,EAAE,CAAC;IACzE,IAAI,MAAM,EAAE,CAAC;QACX,KAAK,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClD,IAAI,QAAQ,CAAC,IAAI,KAAK,KAAK,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC;gBACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;gBAChD,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAC7D,IAAI,SAAS,EAAE,CAAC;oBACd,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;oBACnE,YAAY,CAAC,SAAS,CAAC,GAAG;wBACxB,KAAK,EAAE,QAAQ;wBACf,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO,CAAC,IAAI,QAAQ,CAAC;qBAChE,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;IAElE,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAEtD,mCAAmC;IACnC,MAAM,UAAU,GAAG,IAAI,GAAG,EAA+B,CAAC;IAC1D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,WAAW,KAAK,EAAE;YAAE,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;;YACvD,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;IAE/D,MAAM,QAAQ,GAAyC,EAAE,CAAC;IAC1D,MAAM,QAAQ,GAAyC,EAAE,CAAC;IAE1D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,IAAI,GAAG,CAAC,WAAW,KAAK,EAAE,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAC5C,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,GAAG,CAAC,WAAqB;gBAChC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,IAAI,SAAS,CAAW;gBACjD,KAAK,EAAE,GAAG,CAAC,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YAC5C,QAAQ,CAAC,IAAI,CAAC;gBACZ,KAAK,EAAE,GAAG,CAAC,WAAqB;gBAChC,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,IAAI,SAAS,CAAW;gBACjD,KAAK,EAAE,GAAG,CAAC,KAAK;aACjB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,uBAAuB;IACvB,IAAI,UAAU,GAAgC,IAAI,CAAC;IACnD,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QACjB,KAAK,MAAM,GAAG,IAAI,QAAQ,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC;YAC/C,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAAE,SAAS;YAE9C,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,QAAkB,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;gBACpF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBACvB,MAAM,KAAK,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;oBAC1B,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,EAAE,CAAC;wBAC1D,UAAU,GAAG;4BACX,KAAK,EAAE,GAAG,CAAC,KAAK;4BAChB,OAAO,EAAE,KAAK,CAAC,OAAO;4BACtB,SAAS,EAAE,KAAK,CAAC,SAAS;yBAC3B,CAAC;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,CAAC,UAAU,CAAC,YAAY,EAAE,4BAA4B,EAAE,iCAAiC,GAAG,CAAC,KAAK,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACrK,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,CAAC;QACR,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,WAAW;QACX,YAAY;QACZ,OAAO;QACP,OAAO,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE;QAC/B,UAAU;KACX,CAAC,CAAC;AACL,CAAC"}

package/dist/engine/context.d.ts

@@ -0,0 +1,47 @@
+import type { Registry, SchemaStore } from '../types.js';
+import type { MaadBackend } from '../backend/index.js';
+import type { GitLayer, CommitOptions, CommitOutcome } from '../git/index.js';
+import type { CommitIdentity } from '../git/commit.js';
+import type { OperationJournal } from './journal.js';
+/**
+ * 0.6.10 — Mutable counters on the context so a write-path failure in
+ * `gitCommit` can be surfaced through `maad_health` without plumbing state
+ * back to the engine. Initialized once per engine init; bumped by `gitCommit`
+ * on the 'failed' outcome.
+ */
+export interface CommitFailureTracker {
+    count: number;
+    lastAt: string | null;
+    lastCode: string | null;
+    lastMessage: string | null;
+    lastAction: 'create' | 'update' | 'delete' | null;
+    lastDocId: string | null;
+}
+export declare function newCommitFailureTracker(): CommitFailureTracker;
+export interface EngineContext {
+    projectRoot: string;
+    registry: Registry;
+    schemaStore: SchemaStore;
+    backend: MaadBackend;
+    gitLayer: GitLayer | null;
+    journal: OperationJournal;
+    readOnly: boolean;
+    commitFailures: CommitFailureTracker;
+    /**
+     * 0.7.0 — Identity snapshot set per-operation by the MCP layer inside the
+     * write mutex. When populated AND MAAD_COMMIT_IDENTITY is not "false",
+     * gitCommit passes it through to the commit builder so commit messages
+     * get role/token/agent/user lines appended.
+     */
+    commitIdentity?: CommitIdentity;
+}
+/**
+ * Run a git commit and return the outcome. When gitLayer is absent (git not
+ * initialized or disabled), returns `noop` — the caller treats that as
+ * durable since there's no git to reconcile against. When the commit fails,
+ * the failure is logged on the ops channel AND tallied on
+ * `ctx.commitFailures` so `maad_health` can surface it; the caller gets the
+ * outcome back and can stamp `write_durable: false` on the MCP response.
+ */
+export declare function gitCommit(ctx: EngineContext, opts: CommitOptions): Promise<CommitOutcome>;
+//# sourceMappingURL=context.d.ts.map

package/dist/engine/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC9E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAIrD;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;IAClD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,wBAAgB,uBAAuB,IAAI,oBAAoB,CAS9D;AAED,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,QAAQ,CAAC;IACnB,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAC1B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,oBAAoB,CAAC;IACrC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CA6B/F"}

package/dist/engine/context.js

@@ -0,0 +1,55 @@
+// ============================================================================
+// Engine Context — shared state passed to all domain modules
+// ============================================================================
+import { logger } from './logger.js';
+import { logCommitFailure } from '../logging.js';
+export function newCommitFailureTracker() {
+    return {
+        count: 0,
+        lastAt: null,
+        lastCode: null,
+        lastMessage: null,
+        lastAction: null,
+        lastDocId: null,
+    };
+}
+/**
+ * Run a git commit and return the outcome. When gitLayer is absent (git not
+ * initialized or disabled), returns `noop` — the caller treats that as
+ * durable since there's no git to reconcile against. When the commit fails,
+ * the failure is logged on the ops channel AND tallied on
+ * `ctx.commitFailures` so `maad_health` can surface it; the caller gets the
+ * outcome back and can stamp `write_durable: false` on the MCP response.
+ */
+export async function gitCommit(ctx, opts) {
+    if (!ctx.gitLayer)
+        return { status: 'noop' };
+    // 0.7.0 — Thread commit identity through when set by the MCP layer.
+    // Engine-level direct callers (CLI imports, tests) leave ctx.commitIdentity
+    // undefined; formatCommitMessage then emits the bare title.
+    const enriched = ctx.commitIdentity !== undefined
+        ? { ...opts, identity: ctx.commitIdentity }
+        : opts;
+    const outcome = await ctx.gitLayer.commit(enriched);
+    if (outcome.status === 'failed') {
+        ctx.commitFailures.count++;
+        ctx.commitFailures.lastAt = new Date().toISOString();
+        ctx.commitFailures.lastCode = outcome.code;
+        ctx.commitFailures.lastMessage = outcome.message;
+        ctx.commitFailures.lastAction = opts.action;
+        ctx.commitFailures.lastDocId = opts.docId;
+        logCommitFailure({
+            code: outcome.code,
+            message: outcome.message,
+            action: opts.action,
+            doc_id: opts.docId,
+            doc_type: opts.docType,
+            file_count: opts.files.length,
+        });
+        // Keep the dev-facing log line so the existing logger.bestEffort signal
+        // stays visible for humans tailing ops in non-JSON mode.
+        logger.bestEffort('git', 'commit', `Git commit failed for ${opts.docId}: ${outcome.code} — ${outcome.message}`);
+    }
+    return outcome;
+}
+//# sourceMappingURL=context.js.map

package/dist/engine/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/engine/context.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,6DAA6D;AAC7D,+EAA+E;AAO/E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAiBjD,MAAM,UAAU,uBAAuB;IACrC,OAAO;QACL,KAAK,EAAE,CAAC;QACR,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,IAAI;QACd,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,IAAI;QAChB,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC;AAoBD;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,GAAkB,EAAE,IAAmB;IACrE,IAAI,CAAC,GAAG,CAAC,QAAQ;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAC7C,oEAAoE;IACpE,4EAA4E;IAC5E,4DAA4D;IAC5D,MAAM,QAAQ,GAAkB,GAAG,CAAC,cAAc,KAAK,SAAS;QAC9D,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,GAAG,CAAC,cAAc,EAAE;QAC3C,CAAC,CAAC,IAAI,CAAC;IACT,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpD,IAAI,OAAO,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QAChC,GAAG,CAAC,cAAc,CAAC,KAAK,EAAE,CAAC;QAC3B,GAAG,CAAC,cAAc,CAAC,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrD,GAAG,CAAC,cAAc,CAAC,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;QAC3C,GAAG,CAAC,cAAc,CAAC,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;QACjD,GAAG,CAAC,cAAc,CAAC,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC;QAC5C,GAAG,CAAC,cAAc,CAAC,SAAS,GAAG,IAAI,CAAC,KAAe,CAAC;QACpD,gBAAgB,CAAC;YACf,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,KAAe;YAC5B,QAAQ,EAAE,IAAI,CAAC,OAAiB;YAChC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM;SAC9B,CAAC,CAAC;QACH,wEAAwE;QACxE,yDAAyD;QACzD,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,QAAQ,EAAE,yBAAyB,IAAI,CAAC,KAAe,KAAK,OAAO,CAAC,IAAI,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC5H,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/engine/docid-safe.d.ts

@@ -0,0 +1,8 @@
+export interface DocIdRejection {
+    reason: 'EMPTY' | 'TOO_LONG' | 'CONTAINS_DOTDOT' | 'LEADING_DOT' | 'INVALID_CHARS' | 'WINDOWS_RESERVED' | 'CONTROL_CHARS';
+    message: string;
+}
+export declare function checkDocIdSafe(docId: string): DocIdRejection | null;
+export declare function assertDocIdSafe(docId: string): void;
+export declare const DOC_ID_MAX_LEN = 128;
+//# sourceMappingURL=docid-safe.d.ts.map