@cairnkeep/cli 2.3.1 → 2.5.0

package/mcp-memory-server/dist/node-cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { existsSync, lstatSync, readdirSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { doctorNoteStore } from "./note-store.js";
+import { doctorTypedNodeStore } from "./node-store.js";
+function baseDirectory() {
+    const value = process.env.CAIRN_AGENTFS_BASE_DIR?.trim();
+    if (!value || value === "~")
+        return join(process.env.HOME ?? "", ".cairnkeep");
+    if (value.startsWith("~/"))
+        return join(process.env.HOME ?? "", value.slice(2));
+    return resolve(value);
+}
+function databasePaths(projectRoot) {
+    const base = baseDirectory();
+    const candidates = [];
+    const addFiles = (directory) => {
+        if (!existsSync(directory) || lstatSync(directory).isSymbolicLink())
+            return;
+        for (const entry of readdirSync(directory, { withFileTypes: true })) {
+            if (candidates.length >= 1024)
+                throw new Error("Database enumeration exceeded the 1024-file safety bound.");
+            if (entry.isFile() && !entry.isSymbolicLink() && entry.name.endsWith(".db"))
+                candidates.push(join(directory, entry.name));
+        }
+    };
+    addFiles(base);
+    addFiles(join(base, "projects"));
+    const local = join(resolve(projectRoot), ".agentfs", "project.db");
+    if (existsSync(local) && !lstatSync(local).isSymbolicLink())
+        candidates.push(local);
+    return [...new Set(candidates)].sort();
+}
+export async function doctorNodes(options = {}) {
+    const scopes = [];
+    const issues = [];
+    try {
+        for (const path of databasePaths(options.projectRoot ?? process.cwd())) {
+            const scope = basename(path, ".db");
+            const result = await doctorTypedNodeStore({ scope, baseDir: dirname(path), repair: options.repair });
+            scopes.push({ scope, path, ...result });
+            issues.push(...result.issues.map((issue) => `${scope}: ${issue}`));
+        }
+    }
+    catch (error) {
+        issues.push(error instanceof Error ? error.message : String(error));
+    }
+    const notes = doctorNoteStore(options.repair ?? false);
+    issues.push(...notes.issues.map((issue) => `notes: ${issue}`));
+    const exists = scopes.length > 0 || notes.exists;
+    return {
+        schema_version: 1,
+        exists,
+        ok: issues.length === 0 && scopes.every((scope) => scope.ok) && notes.ok,
+        repaired: scopes.some((scope) => scope.repaired) || notes.repaired,
+        scopes,
+        notes,
+        issues,
+    };
+}
+async function main() {
+    const [command, ...args] = process.argv.slice(2);
+    if (command !== "doctor")
+        throw new Error("Usage: node node-cli.js doctor [--repair] [--project-root PATH]");
+    let repair = false;
+    let projectRoot = process.cwd();
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--repair")
+            repair = true;
+        else if (args[index] === "--project-root" && args[index + 1])
+            projectRoot = args[++index];
+        else
+            throw new Error(`Unknown node doctor option: ${args[index]}`);
+    }
+    const result = await doctorNodes({ repair, projectRoot });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    process.exitCode = result.ok ? 0 : 1;
+}
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
+    main().catch((error) => {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

package/mcp-memory-server/dist/node-schema.js

@@ -0,0 +1,170 @@
+import { z } from "zod";
+export const NODE_SCHEMA_VERSION = 1;
+export const MAX_IMPORT_NODES = 256;
+export const MAX_NODE_VALUE_BYTES = 256 * 1024;
+export const MAX_IMPORT_VALUE_BYTES = 5 * 1024 * 1024;
+const truthyPattern = /^(?:1|true|yes|on)$/i;
+export const coreNodeTypeSchema = z.enum(["memory", "knowledge", "hindsight", "shared", "provenance"]);
+export const noteNodeTypeSchema = z.enum(["hindsight", "knowledge", "shared", "provenance"]);
+const extensionNodeTypeSchema = z.string().regex(/^[a-z][a-z0-9-]{0,31}:[a-z0-9][a-z0-9-]{0,63}$/);
+export const nodeTypeSchema = z.union([coreNodeTypeSchema, extensionNodeTypeSchema]);
+function normalizeTag(value) {
+    return value.trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/-+/g, "-");
+}
+export const canonicalTagSchema = z.string().transform(normalizeTag).pipe(z.string().regex(/^[a-z0-9][a-z0-9-]{0,127}$/));
+export const canonicalTagsSchema = z.array(canonicalTagSchema).max(64).transform((values) => [...new Set(values)].sort());
+export const nodePathSchema = z.string().min(1).max(1024).superRefine((value, context) => {
+    if (value.startsWith("/") || value.endsWith("/") || value.includes("\\") || /[\u0000-\u001f\u007f]/.test(value)) {
+        context.addIssue({ code: "custom", message: "Node path must be a relative slash-separated path." });
+        return;
+    }
+    const segments = value.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        context.addIssue({ code: "custom", message: "Node path contains an invalid segment." });
+    }
+    if (segments[0]?.startsWith("__") || segments[0]?.startsWith(".cairnkeep")) {
+        context.addIssue({ code: "custom", message: "Node path uses a reserved namespace." });
+    }
+});
+export const nodeMetadataSchema = z.object({
+    schema_version: z.literal(NODE_SCHEMA_VERSION),
+    node_type: nodeTypeSchema,
+    tags: canonicalTagsSchema,
+}).strict();
+export const nodeSummarySchema = z.object({
+    schema_version: z.literal(NODE_SCHEMA_VERSION),
+    address_space: z.enum(["memory", "project-notes", "shared-notes"]),
+    scope: z.string(),
+    key: nodePathSchema,
+    node_type: nodeTypeSchema,
+    tags: canonicalTagsSchema,
+}).strict();
+export const failureFrameSchema = z.object({
+    function: z.string().min(1).max(512),
+    file: z.string().min(1).max(1024),
+}).strict();
+export const failureLookupKeysSchema = z.object({
+    full: z.string().regex(/^v1:full:[a-f0-9]{64}$/),
+    message_stack: z.string().regex(/^v1:message-stack:[a-f0-9]{64}$/),
+    message_component: z.string().regex(/^v1:message-component:[a-f0-9]{64}$/),
+    message: z.string().regex(/^v1:message:[a-f0-9]{64}$/),
+}).strict();
+export const failureSignatureSchema = z.object({
+    signature_version: z.literal(NODE_SCHEMA_VERSION),
+    family: z.string().regex(/^[a-z0-9][a-z0-9-]{0,127}$/),
+    normalized_message: z.string().min(1).max(4096),
+    stack_digest: z.union([z.literal(""), z.string().regex(/^[a-f0-9]{64}$/)]),
+    component: z.string().max(1024),
+    frames: z.array(failureFrameSchema).max(16),
+    lookup_keys: failureLookupKeysSchema,
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+}).strict();
+export const noteOccurrenceSchema = z.object({
+    session_id: z.string().min(1).max(256),
+    session_digest: z.string().regex(/^[a-f0-9]{64}$/),
+    ended_at: z.iso.datetime(),
+    sequence: z.number().int().nonnegative(),
+    outcome: z.enum(["failure", "resolution", "abandonment"]),
+    tool_name: z.string().min(1).max(256).optional(),
+    validation_key: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    evidence: z.string().min(1).max(4096),
+}).strict();
+export const noteEnrichmentContentSchema = z.object({
+    summary: z.string().min(1).max(4096),
+    lessons: z.array(z.string().min(1).max(1024)).max(16),
+    caveats: z.array(z.string().min(1).max(1024)).max(16),
+}).strict();
+export const noteNodeSchema = z.object({
+    schema_version: z.literal(NODE_SCHEMA_VERSION),
+    id: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,255}$/),
+    title: z.string().min(1).max(512),
+    description: z.string().min(1).max(4096),
+    keywords: z.array(z.string().min(1).max(128)).max(64),
+    node_type: noteNodeTypeSchema,
+    tags: canonicalTagsSchema,
+    project_id: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,255}$/).optional(),
+    canonical_id: z.string().regex(/^[a-z0-9][a-z0-9._-]{0,255}$/).optional(),
+    status: z.enum(["unresolved", "resolved", "abandoned"]).optional(),
+    signature: failureSignatureSchema.optional(),
+    enrichment: noteEnrichmentContentSchema.optional(),
+    occurrences: z.array(noteOccurrenceSchema).max(1024),
+    created_at: z.iso.datetime(),
+    updated_at: z.iso.datetime(),
+}).strict().superRefine((note, context) => {
+    if (new Set(note.keywords).size !== note.keywords.length) {
+        context.addIssue({ code: "custom", path: ["keywords"], message: "Keywords must be unique." });
+    }
+    if (["hindsight", "provenance"].includes(note.node_type) && (!note.project_id || !note.signature || !note.status)) {
+        context.addIssue({ code: "custom", message: "Project hindsight and provenance notes require project_id, signature, and status." });
+    }
+    if (note.node_type === "provenance" && !note.canonical_id) {
+        context.addIssue({ code: "custom", message: "Provenance notes require canonical_id." });
+    }
+    if (note.node_type === "shared" && (!note.signature || !note.status)) {
+        context.addIssue({ code: "custom", message: "Shared hindsight notes require signature and status." });
+    }
+});
+export const memoryImportNodeSchema = z.object({
+    key: nodePathSchema,
+    value: z.string().refine((value) => Buffer.byteLength(value, "utf8") <= MAX_NODE_VALUE_BYTES, "Node value exceeds 256 KiB."),
+    node_type: nodeTypeSchema,
+    tags: canonicalTagsSchema,
+    note: noteNodeSchema.optional(),
+}).strict();
+export const memoryImportEnvelopeSchema = z.object({
+    schema_version: z.literal(NODE_SCHEMA_VERSION),
+    scope: z.string().min(1).refine((value) => value !== "all", 'Import scope must be concrete; "all" is read-only.'),
+    address_space: z.enum(["memory", "project-notes", "shared-notes"]).default("memory"),
+    import_id: z.string().max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/).optional(),
+    conflict_policy: z.enum(["reject", "supersede"]).default("reject"),
+    dry_run: z.boolean().default(false),
+    nodes: z.array(memoryImportNodeSchema).min(1).max(MAX_IMPORT_NODES),
+}).strict().superRefine((envelope, context) => {
+    const keys = new Set();
+    let totalBytes = 0;
+    envelope.nodes.forEach((node, index) => {
+        totalBytes += Buffer.byteLength(node.value, "utf8");
+        if (keys.has(node.key))
+            context.addIssue({ code: "custom", path: ["nodes", index, "key"], message: "Import keys must be unique." });
+        keys.add(node.key);
+        if (envelope.address_space !== "memory") {
+            const noteRequired = ["hindsight", "shared", "provenance"].includes(node.node_type);
+            if (noteRequired && !node.note)
+                context.addIssue({ code: "custom", path: ["nodes", index, "note"], message: "This note type requires a complete note record." });
+            if (node.note && (node.note.node_type !== node.node_type || JSON.stringify(node.note.tags) !== JSON.stringify(node.tags))) {
+                context.addIssue({ code: "custom", path: ["nodes", index], message: "Import envelope type/tags must agree with note front matter." });
+            }
+        }
+    });
+    if (totalBytes > MAX_IMPORT_VALUE_BYTES)
+        context.addIssue({ code: "custom", path: ["nodes"], message: "Aggregate node values exceed 5 MiB." });
+});
+export const memoryImportActionSchema = z.object({
+    key: nodePathSchema,
+    action: z.enum(["would_create", "would_replace", "created", "replaced", "unchanged", "rejected"]),
+    code: z.string().optional(),
+}).strict();
+export const memoryImportCountsSchema = z.object({
+    created: z.number().int().nonnegative().optional(),
+    replaced: z.number().int().nonnegative().optional(),
+    would_create: z.number().int().nonnegative().optional(),
+    would_replace: z.number().int().nonnegative().optional(),
+    unchanged: z.number().int().nonnegative(),
+    rejected: z.number().int().nonnegative(),
+}).strict();
+export const memoryImportResultSchema = z.object({
+    schema_version: z.literal(NODE_SCHEMA_VERSION),
+    scope: z.string(),
+    address_space: z.enum(["memory", "project-notes", "shared-notes"]),
+    batch_digest: z.string().regex(/^[a-f0-9]{64}$/),
+    import_id: z.string().optional(),
+    dry_run: z.boolean(),
+    conflict_policy: z.enum(["reject", "supersede"]),
+    committed: z.boolean(),
+    replayed: z.boolean().optional(),
+    counts: memoryImportCountsSchema,
+    actions: z.array(memoryImportActionSchema).max(MAX_IMPORT_NODES),
+}).strict();
+export function isTypedMemoryNodesEnabled(value = process.env.CAIRN_TYPED_MEMORY_NODES) {
+    return truthyPattern.test(value?.trim() ?? "");
+}