@maadb/core 0.0.1 → 0.7.10-rc.3

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/backup.d.ts

@@ -0,0 +1,9 @@
+import { type Result } from '../errors.js';
+import type { EngineContext } from './context.js';
+import type { BackupTag, CreateBackupOptions, ListBackupsOptions } from './types.js';
+export declare function createBackup(ctx: EngineContext, opts?: CreateBackupOptions): Promise<Result<BackupTag>>;
+export declare function listBackups(ctx: EngineContext, opts?: ListBackupsOptions): Promise<Result<BackupTag[]>>;
+export declare function deleteBackup(ctx: EngineContext, tag: string): Promise<Result<{
+    removed: string;
+}>>;
+//# sourceMappingURL=backup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"backup.d.ts","sourceRoot":"","sources":["../../src/engine/backup.ts"],"names":[],"mappings":"AAYA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AA+BrF,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,IAAI,GAAE,mBAAwB,GAC7B,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAwC5B;AAED,wBAAsB,WAAW,CAC/B,GAAG,EAAE,aAAa,EAClB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAiB9B;AAED,wBAAsB,YAAY,CAChC,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAkBtC"}

package/dist/engine/backup.js

@@ -0,0 +1,100 @@
+// ============================================================================
+// 0.7.10 — maad_backup: named recovery anchors via annotated git tags.
+//
+// Three operations:
+//   createBackup — annotated tag on HEAD with structured name
+//   listBackups  — every maad-snapshot-* tag with sha + message + createdAt
+//   deleteBackup — drop a maad-snapshot-* tag (refuses other tags)
+//
+// Pure git operations on the project repo. No SQLite reads, no schema lookups,
+// no engine_meta writes (that stamp comes with Step 9 / maad_health).
+// ============================================================================
+import { ok, singleErr } from '../errors.js';
+const MAAD_SNAPSHOT_PREFIX = 'maad-snapshot-';
+const LABEL_MAX_LEN = 32;
+/**
+ * Sanitize an operator-supplied label: trim, lowercase, replace runs of
+ * non-[a-z0-9-] chars with a single -, strip leading/trailing hyphens,
+ * cap at LABEL_MAX_LEN. Returns null when the result is empty.
+ */
+function sanitizeLabel(raw) {
+    const sanitized = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, LABEL_MAX_LEN)
+        .replace(/^-+|-+$/g, '');
+    return sanitized.length > 0 ? sanitized : null;
+}
+function formatTagName(now, label) {
+    const yyyy = now.getUTCFullYear();
+    const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(now.getUTCDate()).padStart(2, '0');
+    const hh = String(now.getUTCHours()).padStart(2, '0');
+    const mn = String(now.getUTCMinutes()).padStart(2, '0');
+    const base = `${MAAD_SNAPSHOT_PREFIX}${yyyy}-${mm}-${dd}-${hh}${mn}`;
+    return label ? `${base}-${label}` : base;
+}
+export async function createBackup(ctx, opts = {}) {
+    if (!ctx.gitLayer) {
+        return singleErr('GIT_NOT_INITIALIZED', 'Project has no git repository');
+    }
+    const head = await ctx.gitLayer.headSha();
+    if (!head) {
+        return singleErr('NO_HEAD_COMMIT', 'Repository has no commits yet — nothing to snapshot');
+    }
+    let label = null;
+    if (opts.label !== undefined && opts.label !== '') {
+        label = sanitizeLabel(opts.label);
+        if (label === null) {
+            return singleErr('INVALID_FIELDS', `Label "${opts.label}" sanitizes to an empty string — use [a-z0-9-] chars`);
+        }
+    }
+    const tagName = formatTagName(new Date(), label);
+    // Collision check — refuse to overwrite an existing tag of the same name.
+    const existing = await ctx.gitLayer.listTagsByPrefix(tagName);
+    if (existing.some(t => t.tag === tagName)) {
+        return singleErr('TAG_EXISTS', `Snapshot "${tagName}" already exists`);
+    }
+    const branch = await ctx.gitLayer.currentBranch();
+    const message = opts.message ?? `MAADB snapshot at ${head} ('${branch}')`;
+    await ctx.gitLayer.addAnnotatedTag(tagName, message);
+    return ok({
+        tag: tagName,
+        sha: head,
+        message,
+        createdAt: new Date().toISOString(),
+    });
+}
+export async function listBackups(ctx, opts = {}) {
+    if (!ctx.gitLayer)
+        return ok([]);
+    const all = await ctx.gitLayer.listTagsByPrefix(MAAD_SNAPSHOT_PREFIX);
+    if (opts.since !== undefined) {
+        const sinceMs = Date.parse(opts.since);
+        if (Number.isNaN(sinceMs)) {
+            return singleErr('INVALID_FIELDS', `since is not a valid ISO8601 date: "${opts.since}"`);
+        }
+        return ok(all.filter(t => {
+            const tagMs = Date.parse(t.createdAt);
+            return !Number.isNaN(tagMs) && tagMs >= sinceMs;
+        }));
+    }
+    return ok(all);
+}
+export async function deleteBackup(ctx, tag) {
+    if (!ctx.gitLayer) {
+        return singleErr('GIT_NOT_INITIALIZED', 'Project has no git repository');
+    }
+    if (!tag.startsWith(MAAD_SNAPSHOT_PREFIX)) {
+        return singleErr('INVALID_FIELDS', `maad_backup delete only removes ${MAAD_SNAPSHOT_PREFIX}* tags — got "${tag}"`);
+    }
+    const existing = await ctx.gitLayer.listTagsByPrefix(tag);
+    if (!existing.some(t => t.tag === tag)) {
+        return singleErr('TAG_NOT_FOUND', `Tag "${tag}" does not exist`);
+    }
+    await ctx.gitLayer.deleteTag(tag);
+    return ok({ removed: tag });
+}
+//# sourceMappingURL=backup.js.map

package/dist/engine/backup.js.map

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

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":"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"}