@cairnkeep/cli 2.14.0 → 2.15.1

package/mcp-memory-server/dist/playbook-receipt.js

@@ -0,0 +1,245 @@
+import { createHash, randomBytes } from "node:crypto";
+import { constants, existsSync, readdirSync } from "node:fs";
+import { link, lstat, mkdir, open, realpath, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
+import { playbookProjectIdentity, resolvePlaybookStatus } from "./playbook.js";
+import { PLAYBOOK_SCHEMA_VERSION, playbookActionIdSchema, playbookActorSchema, playbookEventSchema, playbookOutcomeSchema, playbookReasonSchema, } from "./playbook-schema.js";
+const MAX_RECEIPT_BYTES = 8 * 1024;
+const MAX_RECEIPTS = 10_000;
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/;
+const SESSION_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const RECEIPT_PATTERN = /^pbk_[a-f0-9]{32}$/;
+const receiptSchema = z.strictObject({
+    schema_version: z.literal(PLAYBOOK_SCHEMA_VERSION),
+    receipt_id: z.string().regex(RECEIPT_PATTERN),
+    project_identity: z.string().regex(DIGEST_PATTERN),
+    policy_digest: z.string().regex(DIGEST_PATTERN),
+    decision_digest: z.string().regex(DIGEST_PATTERN),
+    actor: playbookActorSchema,
+    session_id: z.string().regex(SESSION_PATTERN),
+    event: playbookEventSchema,
+    action: playbookActionIdSchema,
+    outcome: playbookOutcomeSchema,
+    reason: playbookReasonSchema,
+    recorded_at: z.string().datetime({ offset: true }),
+});
+function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+async function layout(projectRoot = process.cwd()) {
+    const root = await realpath(resolve(projectRoot));
+    const agentfs = join(root, ".agentfs");
+    const store = join(agentfs, "playbooks");
+    const receipts = join(store, "receipts");
+    if (dirname(agentfs) !== root || dirname(store) !== agentfs || dirname(receipts) !== store) {
+        throw new Error("Playbook receipt store escapes the project root.");
+    }
+    return { root, agentfs, store, receipts };
+}
+async function ensureDirectory(path, parent) {
+    if (existsSync(path)) {
+        const info = await lstat(path);
+        if (!info.isDirectory() || info.isSymbolicLink() || !privatePathIsSafe(path)) {
+            throw new Error("Playbook receipt storage contains an unsafe path.");
+        }
+        return;
+    }
+    const parentInfo = await lstat(parent);
+    if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink())
+        throw new Error("Playbook receipt storage parent is unsafe.");
+    await mkdir(path, { mode: 0o700 });
+    hardenPrivatePath(path);
+}
+async function ensureStore(projectRoot) {
+    const target = await layout(projectRoot);
+    if (!existsSync(target.agentfs))
+        await mkdir(target.agentfs, { mode: 0o700 });
+    const agentInfo = await lstat(target.agentfs);
+    if (!agentInfo.isDirectory() || agentInfo.isSymbolicLink())
+        throw new Error("Project .agentfs path is unsafe.");
+    await ensureDirectory(target.store, target.agentfs);
+    await ensureDirectory(target.receipts, target.store);
+    return target.receipts;
+}
+async function safeRead(path) {
+    const info = await lstat(path);
+    if (!info.isFile() || info.isSymbolicLink() || info.size > MAX_RECEIPT_BYTES || !privatePathIsSafe(path)) {
+        throw new Error("Unsafe playbook receipt.");
+    }
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        const opened = await handle.stat();
+        if (!opened.isFile() || opened.size > MAX_RECEIPT_BYTES || opened.dev !== info.dev || opened.ino !== info.ino) {
+            throw new Error("Playbook receipt changed during validation.");
+        }
+        return receiptSchema.parse(JSON.parse((await handle.readFile()).toString("utf8")));
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function atomicReceipt(path, value) {
+    const bytes = Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8");
+    if (bytes.byteLength > MAX_RECEIPT_BYTES)
+        throw new Error("Playbook receipt exceeds its storage limit.");
+    const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(bytes);
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        hardenPrivatePath(temporary);
+        try {
+            await link(temporary, path);
+        }
+        catch (error) {
+            if (error.code === "EEXIST")
+                return false;
+            throw error;
+        }
+        hardenPrivatePath(path);
+        return true;
+    }
+    finally {
+        if (handle)
+            await handle.close().catch(() => undefined);
+        await rm(temporary, { force: true });
+    }
+}
+function receiptFiles(directory) {
+    if (!existsSync(directory))
+        return [];
+    return readdirSync(directory).filter((name) => RECEIPT_PATTERN.test(name.replace(/\.json$/, "")) && name.endsWith(".json")).sort();
+}
+export async function recordPlaybookReceipt(options) {
+    const projectRoot = options.projectRoot ?? process.cwd();
+    if (!DIGEST_PATTERN.test(options.policyDigest) || !DIGEST_PATTERN.test(options.decisionDigest))
+        throw new Error("Invalid playbook digest.");
+    if (!SESSION_PATTERN.test(options.sessionId))
+        throw new Error("Invalid playbook session ID.");
+    const actor = playbookActorSchema.parse(options.actor);
+    const event = playbookEventSchema.parse(options.event);
+    const action = playbookActionIdSchema.parse(options.action);
+    const outcome = playbookOutcomeSchema.parse(options.outcome);
+    const reason = playbookReasonSchema.parse(options.reason ?? "");
+    if ((outcome === "skipped" || outcome === "failed") && reason.trim().length === 0) {
+        throw new Error("Skipped or failed playbook actions require a bounded reason.");
+    }
+    const status = await resolvePlaybookStatus({ projectRoot });
+    if (status.issues.length || status.policy_digest !== options.policyDigest)
+        throw new Error("Playbook policy digest is stale or invalid.");
+    const projectIdentity = await playbookProjectIdentity(projectRoot);
+    const identity = {
+        schema_version: PLAYBOOK_SCHEMA_VERSION,
+        project_identity: projectIdentity,
+        policy_digest: options.policyDigest,
+        decision_digest: options.decisionDigest,
+        actor,
+        session_id: options.sessionId,
+        event,
+        action,
+        outcome,
+        reason,
+    };
+    const receiptId = `pbk_${sha256(JSON.stringify(identity)).slice(0, 32)}`;
+    const directory = await ensureStore(projectRoot);
+    if (receiptFiles(directory).length >= MAX_RECEIPTS)
+        throw new Error("Playbook receipt limit reached; archive or remove old project state.");
+    const path = join(directory, `${receiptId}.json`);
+    if (existsSync(path))
+        return safeRead(path);
+    const receipt = receiptSchema.parse({ ...identity, receipt_id: receiptId, recorded_at: (options.now ?? new Date()).toISOString() });
+    return await atomicReceipt(path, receipt) ? receipt : safeRead(path);
+}
+export async function listPlaybookReceipts(projectRoot = process.cwd()) {
+    const { receipts } = await layout(projectRoot);
+    if (!existsSync(receipts))
+        return { schema_version: PLAYBOOK_SCHEMA_VERSION, receipts: [] };
+    const info = await lstat(receipts);
+    if (!info.isDirectory() || info.isSymbolicLink())
+        throw new Error("Playbook receipt store is unsafe.");
+    const values = [];
+    for (const name of receiptFiles(receipts))
+        values.push(await safeRead(join(receipts, name)));
+    values.sort((left, right) => right.recorded_at.localeCompare(left.recorded_at) || left.receipt_id.localeCompare(right.receipt_id));
+    return { schema_version: PLAYBOOK_SCHEMA_VERSION, receipts: values };
+}
+export async function readPlaybookReceipt(selector, projectRoot = process.cwd()) {
+    if (!/^(?:pbk_)?[a-f0-9]{6,32}$/.test(selector))
+        throw new Error("Invalid playbook receipt selector.");
+    const values = (await listPlaybookReceipts(projectRoot)).receipts.filter(({ receipt_id }) => receipt_id === selector || receipt_id.startsWith(selector.startsWith("pbk_") ? selector : `pbk_${selector}`));
+    if (values.length === 0)
+        throw new Error("Playbook receipt not found.");
+    if (values.length > 1)
+        throw new Error("Playbook receipt selector is ambiguous.");
+    return values[0];
+}
+export async function doctorPlaybooks(projectRoot = process.cwd()) {
+    const status = await resolvePlaybookStatus({ projectRoot });
+    const policyIssues = [...status.issues];
+    const receiptIssues = [];
+    let count = 0;
+    try {
+        const target = await layout(projectRoot);
+        const ai = join(target.root, ".ai");
+        if (existsSync(ai)) {
+            const info = await lstat(ai);
+            if (!info.isDirectory() || info.isSymbolicLink())
+                policyIssues.push("unsafe playbook configuration directory");
+            else {
+                for (const name of readdirSync(ai).sort()) {
+                    if (name === ".playbooks.lock" || /^\.playbooks\.json\..+\.tmp$/.test(name)) {
+                        policyIssues.push(`playbook configuration remnant: ${name}`);
+                    }
+                }
+            }
+        }
+        if (existsSync(target.store)) {
+            const info = await lstat(target.store);
+            if (!info.isDirectory() || info.isSymbolicLink() || !privatePathIsSafe(target.store)) {
+                receiptIssues.push("unsafe playbook receipt root");
+            }
+            else {
+                for (const name of readdirSync(target.store).sort()) {
+                    if (name !== "receipts")
+                        receiptIssues.push(`unexpected playbook store entry: ${name}`);
+                }
+            }
+        }
+        if (existsSync(target.receipts)) {
+            const info = await lstat(target.receipts);
+            if (!info.isDirectory() || info.isSymbolicLink() || !privatePathIsSafe(target.receipts))
+                receiptIssues.push("unsafe receipt directory");
+            else {
+                const names = readdirSync(target.receipts).sort();
+                for (const name of names) {
+                    if (!name.endsWith(".json") || !RECEIPT_PATTERN.test(name.slice(0, -5))) {
+                        receiptIssues.push(`unexpected receipt entry: ${name}`);
+                        continue;
+                    }
+                    try {
+                        await safeRead(join(target.receipts, name));
+                        count += 1;
+                    }
+                    catch {
+                        receiptIssues.push(`invalid receipt: ${name}`);
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        receiptIssues.push("receipt store diagnostic failed");
+    }
+    return {
+        schema_version: PLAYBOOK_SCHEMA_VERSION,
+        ok: policyIssues.length === 0 && receiptIssues.length === 0,
+        policy: { ok: policyIssues.length === 0, issues: policyIssues },
+        receipts: { ok: receiptIssues.length === 0, count, issues: receiptIssues },
+    };
+}

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

@@ -0,0 +1,56 @@
+import { z } from "zod";
+export const PLAYBOOK_SCHEMA_VERSION = 1;
+export const PLAYBOOK_PROFILES = ["minimal", "balanced", "strict"];
+export const PLAYBOOK_MODES = ["must", "should", "may", "off"];
+export const PLAYBOOK_EVENTS = ["start", "check", "finish"];
+export const PLAYBOOK_COMPLEXITIES = ["trivial", "standard", "complex"];
+export const PLAYBOOK_FAMILIARITIES = ["known", "mixed", "unfamiliar"];
+export const PLAYBOOK_RISKS = ["low", "normal", "high", "security"];
+export const PLAYBOOK_CHANGE_TYPES = ["code", "tests", "docs", "config", "dependencies", "security"];
+export const PLAYBOOK_OUTCOMES = ["completed", "skipped", "failed"];
+export const PLAYBOOK_ACTOR_KINDS = ["user", "agent", "service"];
+export const PLAYBOOK_ACTION_IDS = [
+    "context.recall",
+    "context.explore",
+    "work.plan",
+    "verify.tests",
+    "review.repository",
+    "review.security",
+    "docs.update",
+    "learning.capture",
+];
+export const playbookProfileSchema = z.enum(PLAYBOOK_PROFILES);
+export const playbookModeSchema = z.enum(PLAYBOOK_MODES);
+export const playbookEventSchema = z.enum(PLAYBOOK_EVENTS);
+export const playbookComplexitySchema = z.enum(PLAYBOOK_COMPLEXITIES);
+export const playbookFamiliaritySchema = z.enum(PLAYBOOK_FAMILIARITIES);
+export const playbookRiskSchema = z.enum(PLAYBOOK_RISKS);
+export const playbookChangeTypeSchema = z.enum(PLAYBOOK_CHANGE_TYPES);
+export const playbookOutcomeSchema = z.enum(PLAYBOOK_OUTCOMES);
+export const playbookActorKindSchema = z.enum(PLAYBOOK_ACTOR_KINDS);
+export const playbookActionIdSchema = z.enum(PLAYBOOK_ACTION_IDS);
+export const playbookOverridesSchema = z.partialRecord(playbookActionIdSchema.or(z.never()), playbookModeSchema);
+export const playbookConfigSchema = z.strictObject({
+    schema_version: z.literal(PLAYBOOK_SCHEMA_VERSION),
+    profile: playbookProfileSchema,
+    overrides: playbookOverridesSchema,
+});
+export const playbookActorSchema = z.strictObject({
+    id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$/),
+    kind: playbookActorKindSchema,
+    authenticated: z.literal(false),
+});
+export const playbookReasonSchema = z.string().max(512).refine((value) => !/[\u0000-\u001f\u007f]/.test(value), "Playbook reasons must not contain control characters.");
+export const playbookEvidenceSchema = z.strictObject({
+    action: playbookActionIdSchema,
+    outcome: playbookOutcomeSchema,
+    reason: playbookReasonSchema,
+});
+export const playbookSignalsSchema = z.strictObject({
+    complexity: playbookComplexitySchema,
+    familiarity: playbookFamiliaritySchema,
+    risk: playbookRiskSchema,
+    public_change: z.boolean(),
+    changed_paths: z.array(z.string().min(1).max(512)).max(256),
+    change_types: z.array(playbookChangeTypeSchema).max(PLAYBOOK_CHANGE_TYPES.length),
+});