@cairnkeep/cli 2.8.0 → 2.11.0

package/mcp-memory-server/dist/skill-store.js

@@ -1,10 +1,11 @@
 import { createHash, randomBytes } from "node:crypto";
-import { constants, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync, chmodSync } from "node:fs";
-import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { constants, existsSync, lstatSync, mkdirSync, openSync, closeSync, readFileSync, readSync, readdirSync, renameSync, rmSync, writeFileSync, chmodSync } from "node:fs";
+import { delimiter, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
 import { canonicalDigest } from "./eval-schema.js";
 import { EvalProcessError, runBoundedJsonProcess } from "./eval-process.js";
 import { noteNodeSchema } from "./node-schema.js";
 import { getNoteLayout, listAddressedNotes } from "./note-store.js";
+import { hardenPrivatePath, privatePathIsSafe } from "./platform-security.js";
 import { MAX_SKILL_BYTES, SKILL_SCHEMA_VERSION, skillAdapterConfigSchema, skillApplicationSchema, skillCandidateSchema, skillEvaluationSchema, skillProposalRequestSchema, skillProposalResponseSchema, skillProposalSchema, skillRelativePathSchema, } from "./skill-schema.js";
 const MAX_ARTIFACT_BYTES = 2 * 1024 * 1024;
 const PROTECTED_ADAPTER_ENVIRONMENT = new Set([
@@ -38,10 +39,21 @@ function isContained(root, candidate) {
     const path = relative(root, candidate);
     return path === "" || (!path.startsWith(`..${sep}`) && path !== ".." && !isAbsolute(path));
 }
+function pathCrossesSymlink(path) {
+    const absolute = resolve(path);
+    const root = parse(absolute).root;
+    let cursor = root;
+    for (const segment of absolute.slice(root.length).split(sep).filter(Boolean)) {
+        cursor = join(cursor, segment);
+        if (lstatSync(cursor).isSymbolicLink())
+            return true;
+    }
+    return false;
+}
 function requireProjectRoot(projectRoot) {
     const absolute = resolve(projectRoot);
     const info = lstatSync(absolute);
-    if (info.isSymbolicLink() || !info.isDirectory() || realpathSync(absolute) !== absolute) {
+    if (!info.isDirectory() || pathCrossesSymlink(absolute)) {
         throw new Error("Project root must be a real, non-symlink directory.");
     }
     return absolute;
@@ -49,10 +61,10 @@ function requireProjectRoot(projectRoot) {
 function privateDirectory(path) {
     mkdirSync(path, { recursive: true, mode: 0o700 });
     const info = lstatSync(path);
-    if (info.isSymbolicLink() || !info.isDirectory() || realpathSync(path) !== path) {
+    if (!info.isDirectory() || pathCrossesSymlink(path)) {
         throw new Error(`Unsafe skill state directory: ${path}`);
     }
-    chmodSync(path, 0o700);
+    hardenPrivatePath(path);
 }
 export function getSkillStore(projectRoot = process.cwd(), create = true) {
     const rootProject = requireProjectRoot(projectRoot);
@@ -97,12 +109,13 @@ function atomicWrite(path, value) {
     finally {
         closeSync(descriptor);
     }
-    chmodSync(temporary, 0o600);
+    hardenPrivatePath(temporary);
     renameSync(temporary, path);
+    hardenPrivatePath(path);
 }
 function readJson(path) {
     const info = lstatSync(path);
-    if (info.isSymbolicLink() || !info.isFile() || info.size > MAX_ARTIFACT_BYTES || (info.mode & 0o077) !== 0) {
+    if (info.isSymbolicLink() || !info.isFile() || info.size > MAX_ARTIFACT_BYTES || !privatePathIsSafe(path)) {
         throw new Error(`Unsafe skill artifact: ${path}`);
     }
     const descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
@@ -117,7 +130,7 @@ function listJson(directory, parse) {
     if (!existsSync(directory))
         return [];
     const info = lstatSync(directory);
-    if (info.isSymbolicLink() || !info.isDirectory() || (info.mode & 0o077) !== 0)
+    if (info.isSymbolicLink() || !info.isDirectory() || !privatePathIsSafe(directory))
         throw new Error("Unsafe skill artifact directory.");
     return [...new Set(readdirSync(directory))]
         .filter((name) => /^[a-z0-9][a-z0-9._-]{0,127}\.json$/.test(name))
@@ -315,8 +328,10 @@ function loadAdapterConfig(path) {
     if (!isAbsolute(config.command.program))
         throw new Error("Skill adapter program must be an absolute path.");
     const programInfo = lstatSync(config.command.program);
-    if (programInfo.isSymbolicLink() || !programInfo.isFile() || (programInfo.mode & 0o111) === 0
-        || realpathSync(config.command.program) !== config.command.program) {
+    const windowsRunnable = /\.(?:cjs|mjs|js|exe|com)$/i.test(config.command.program);
+    if (!programInfo.isFile()
+        || pathCrossesSymlink(config.command.program)
+        || (process.platform === "win32" ? !windowsRunnable : (programInfo.mode & 0o111) === 0)) {
         throw new Error("Skill adapter program must be a real executable file.");
     }
     return { config, digest: canonicalDigest(config), program_digest: sha256File(config.command.program) };
@@ -502,7 +517,7 @@ export function applySkillProposal(options) {
         rolled_back_at: null,
     });
     writeFileSync(backupPath, target.content, { encoding: "utf8", mode: 0o600, flag: "wx" });
-    chmodSync(backupPath, 0o600);
+    hardenPrivatePath(backupPath);
     try {
         atomicWriteTarget(target.path, proposal.candidate_content, proposal.target_mode);
         if (sha256(readFileSync(target.path)) !== proposal.candidate_content_digest) {
@@ -563,7 +578,7 @@ export function rollbackSkillApplication(options) {
     const backup = resolve(store.project_root, application.backup_path);
     const backupInfo = lstatSync(backup);
     if (!isContained(store.backups, backup) || backupInfo.isSymbolicLink() || !backupInfo.isFile()
-        || backupInfo.size > MAX_SKILL_BYTES || (backupInfo.mode & 0o077) !== 0) {
+        || backupInfo.size > MAX_SKILL_BYTES || !privatePathIsSafe(backup)) {
         throw new Error("Skill backup is missing or unsafe.");
     }
     const original = readFileSync(backup, "utf8");

package/mcp-memory-server/package.json

@@ -46,9 +46,12 @@
         "check:eval-statistics": "node scripts/smoke-eval-statistics.mjs",
         "check:skill-lifecycle": "node scripts/smoke-skill-lifecycle.mjs",
         "check:graph-cli": "node scripts/smoke-graph-cli.mjs",
+        "check:mcp-trust": "node scripts/smoke-mcp-trust.mjs",
+        "check:pi-mcp-bridge": "node scripts/smoke-pi-mcp-bridge.mjs",
+        "check:context-pack": "node scripts/smoke-context-pack.mjs",
         "check:notes": "npm run build && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment",
         "test": "npm run test:smoke",
-        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli",
+        "test:smoke": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:scope-guard && npm run check:http-guard && npm run check:remote-context && npm run check:explore-guard && npm run check:explore-cache && npm run check:explore-crossref && npm run check:route-guard && npm run check:reviewed-memory && npm run check:trajectory-roundtrip && npm run check:trajectory-redaction && npm run check:trajectory-retention && npm run check:note-signatures && npm run check:note-distillation && npm run check:note-enrichment && npm run check:node-compat && npm run check:typed-nodes && npm run check:memory-import && npm run check:note-mcp && npm run check:node-doctor && npm run check:artifact-store && npm run check:artifact-mcp && npm run check:compaction-capture && npm run check:capability-contract && npm run check:capability-logging && npm run check:capability-harness && npm run check:capability-mcp && npm run check:eval-schema && npm run check:eval-process && npm run check:eval-statistics && npm run check:skill-lifecycle && npm run check:graph-cli && npm run check:mcp-trust && npm run check:pi-mcp-bridge && npm run check:context-pack",
         "test:search": "npm run build && npm run check:search",
         "test:memory": "npm run build && npm run check:embeddings && npm run check:extract && npm run check:search",
         "test:all": "npm run test:memory"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnkeep/cli",
-  "version": "2.8.0",
+  "version": "2.11.0",
   "description": "A durable, harness-agnostic memory + context layer for coding agents and MCP clients.",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,7 +9,7 @@
   },
   "bin": {
     "cairn": "bin/cairn",
-    "cairn-container": "scripts/cairn-container"
+    "cairn-container": "bin/cairn-container"
   },
   "files": [
     "bin/",
@@ -43,9 +43,10 @@
   },
   "scripts": {
     "build:server": "npm --prefix mcp-memory-server ci --include=dev --global=false --dry-run=false && npm --prefix mcp-memory-server run build --global=false --dry-run=false",
-    "fix:perms": "git ls-files -s | awk '$1==\"100755\"{print $4}' | xargs chmod 755",
+    "fix:perms": "node scripts/fix-permissions.mjs",
     "prepack": "npm run build:server && npm run fix:perms",
-    "test": "for test in scripts/test-*.sh; do \"$test\" || exit 1; done",
+    "test": "node scripts/run-repository-tests.mjs",
+    "test:windows": "node scripts/test-windows-native.mjs",
     "audit:runtime": "node scripts/verify-dependency-security.mjs && npm audit --omit=dev --audit-level=high && npm --prefix mcp-memory-server audit --omit=dev --audit-level=high",
     "check:public": "scripts/verify-no-private-references.sh && scripts/verify-docs-parity.sh && npm run audit:runtime && npm run build:server && npm test",
     "prepublishOnly": "npm run check:public && npm --prefix mcp-memory-server test --global=false --dry-run=false"

package/pi/extensions/cairnkeep-memory.ts

@@ -0,0 +1,61 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+const CAIRN_ROOT = "@@INFRA_ROOT@@";
+const BRIDGE_ENTRY = join(CAIRN_ROOT, "mcp-memory-server", "dist", "pi-mcp-bridge.js");
+
+type BridgeModule = typeof import("../../mcp-memory-server/dist/pi-mcp-bridge.js");
+type Bridge = Awaited<ReturnType<BridgeModule["connectCairnPiBridge"]>>;
+
+function existingToolNames(pi: ExtensionAPI): Set<string> {
+    return new Set(pi.getAllTools().map((tool) => tool.name));
+}
+
+export default function cairnMemoryExtension(pi: ExtensionAPI): void {
+    let bridge: Bridge | undefined;
+    let startPromise: Promise<void> | undefined;
+    let shutdownPromise: Promise<void> | undefined;
+
+    const start = async (ctx: ExtensionContext): Promise<void> => {
+        const module = await import(pathToFileURL(BRIDGE_ENTRY).href) as BridgeModule;
+        const connected = await module.connectCairnPiBridge({ cwd: ctx.cwd, env: { ...process.env } });
+        try {
+            const tools = await connected.listAllTools();
+            const existing = existingToolNames(pi);
+            const collisions = tools.map(({ name }) => name).filter((name) => existing.has(name));
+            if (collisions.length) {
+                throw new Error(`Cairnkeep MCP tool collision would override an existing Pi tool: ${collisions.join(", ")}.`);
+            }
+            for (const tool of tools) {
+                pi.registerTool({
+                    name: tool.name,
+                    label: tool.title ?? tool.name,
+                    description: tool.description ?? tool.title ?? tool.name,
+                    parameters: tool.inputSchema,
+                    execute: async (_callId, args, signal) => connected.call(tool, args, { signal }),
+                });
+            }
+            bridge = connected;
+        } catch (error) {
+            await connected.close().catch(() => undefined);
+            throw error;
+        }
+    };
+
+    pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+        if (shutdownPromise) throw new Error("Cairnkeep MCP bridge is already shutting down.");
+        if (!startPromise) startPromise = start(ctx);
+        await startPromise;
+    });
+
+    pi.on("session_shutdown", async () => {
+        if (!shutdownPromise) {
+            shutdownPromise = (async () => {
+                await startPromise?.catch(() => undefined);
+                await bridge?.close();
+            })();
+        }
+        await shutdownPromise;
+    });
+}

package/schemas/cairnkeep-setup-policy.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/cairnkeep-setup-policy.schema.json",
+  "title": "Cairnkeep guided setup policy",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "defaults", "constraints"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "git": {"enum": ["init", "existing", "none"]},
+        "harnesses": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+        },
+        "memory": {"enum": ["local", "none"]}
+      }
+    },
+    "constraints": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "git": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["init", "existing", "none"]}
+        },
+        "harnesses": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+        },
+        "required_harnesses": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+        },
+        "memory": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {"enum": ["local", "none"]}
+        }
+      }
+    }
+  }
+}

package/schemas/cairnkeep-setup.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/cairnkeep-setup.schema.json",
+  "title": "Cairnkeep project setup state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "cairnkeep_version", "git", "memory", "harnesses", "assets"],
+  "properties": {
+    "schema_version": {"const": 1},
+    "cairnkeep_version": {"type": "string", "minLength": 1, "maxLength": 128},
+    "git": {"enum": ["init", "existing", "none"]},
+    "memory": {"enum": ["local", "none"]},
+    "harnesses": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"enum": ["claude", "opencode", "pi", "kimi", "qwen"]}
+    },
+    "assets": {
+      "type": "object",
+      "propertyNames": {
+        "pattern": "^\\.(?:ai|planning|agentfs)/(?!.*(?:^|/)\\.\\.(?:/|$))[A-Za-z0-9._/-]+$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["digest", "mode", "template"],
+        "properties": {
+          "digest": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "mode": {"type": "integer", "minimum": 0, "maximum": 511},
+          "template": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$"}
+        }
+      }
+    }
+  }
+}

package/schemas/context-pack.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/cairnkeep/cairnkeep/main/schemas/context-pack.schema.json",
+  "title": "Cairnkeep context pack manifest v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "version", "title", "description", "license", "files"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 64 },
+    "version": { "type": "string", "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(?:-[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$", "maxLength": 128 },
+    "title": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "description": { "type": "string", "minLength": 1, "maxLength": 2048 },
+    "license": { "type": "string", "minLength": 1, "maxLength": 128 },
+    "files": {
+      "type": "array",
+      "maxItems": 1024,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "kind", "title", "description", "keywords", "sha256"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1, "maxLength": 512 },
+          "kind": { "enum": ["document", "skill"] },
+          "title": { "type": "string", "minLength": 1, "maxLength": 256 },
+          "description": { "type": "string", "maxLength": 2048 },
+          "keywords": { "type": "array", "maxItems": 64, "items": { "type": "string", "minLength": 1, "maxLength": 128 } },
+          "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+        }
+      }
+    }
+  }
+}

package/schemas/eval-report.schema.json

@@ -412,6 +412,7 @@
         "package_version": { "type": "string", "minLength": 1, "maxLength": 128 },
         "runtime_id": { "$ref": "#/$defs/identifier" },
         "task_set_digest": { "$ref": "#/$defs/digest" },
+        "mcp_tool_profile_digest": { "$ref": "#/$defs/digest" },
         "report_digest": { "$ref": "#/$defs/digest" },
         "schema_digests": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "$ref": "#/$defs/digest" } },
         "note_snapshot_digests": { "type": "array", "maxItems": 10000, "items": { "$ref": "#/$defs/digest" } },

package/scripts/cairn-cli.mjs

@@ -0,0 +1,119 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { runWindowsCommand, powershellCompletion } from "./windows-platform.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const NODE_COMMANDS = new Map([
+  ["memory-server", "index.js"],
+  ["trajectory", "trajectory-cli.js"],
+  ["artifact", "artifact-cli.js"],
+  ["capabilities", "capability-cli.js"],
+  ["mcp-tools", "mcp-tool-cli.js"],
+  ["pack", "context-pack-cli.js"],
+  ["notes", "note-cli.js"],
+  ["eval", "eval-cli.js"],
+  ["skill", "skill-cli.js"],
+  ["graph", "graph-cli.js"],
+]);
+
+const POSIX_COMMANDS = new Map([
+  ["bootstrap", "bootstrap.sh"],
+  ["doctor", "doctor.sh"],
+  ["uninstall", "uninstall.sh"],
+  ["memory", "memory-store.sh"],
+  ["sync", "sync-claude-assets.sh"],
+  ["sync-pi", "sync-pi-assets.sh"],
+  ["sync-kimi", "sync-kimi-assets.sh"],
+  ["audit-timer", "install-audit-timer.sh"],
+  ["completion", "completion.sh"],
+]);
+
+export const USAGE = `cairn — Cairnkeep CLI
+
+Usage:
+  cairn bootstrap [--untracked] [path]
+  cairn setup PATH --git init|existing|none --harness LIST --memory local|none [--policy PATH] --yes [--json]
+  cairn memory-server
+  cairn sync [--check|--apply] [--live-root DIR]
+  cairn sync-pi [--check|--apply] [--live-root DIR]
+  cairn sync-kimi [--check|--apply] [--live-root DIR]
+  cairn doctor [--repair]
+  cairn trajectory <list|show|prune>
+  cairn artifact <list|show|delete|prune>
+  cairn capabilities <list|status|enable|disable|reset|logging>
+  cairn mcp-tools <list|status|set|reset>
+  cairn pack <init|lock|validate|install|list|show|remove|enable|disable|update|skills|approve-skill|revoke-skill>
+  cairn notes <distill|search-error|promote|doctor>
+  cairn eval <validate|run|ablate|report|prune|delete>
+  cairn skill <harvest|list|show|review|propose|evaluate|apply|rollback>
+  cairn graph <build|query|status|diff|explain|path>
+  cairn memory <path|export|import>
+  cairn audit-timer [--on-calendar SPEC] [--para-root PATH] [--render-only DIR]
+  cairn uninstall [--dry-run] [--yes] [--purge-memory] [--purge-packs] [PROJECT ...]
+  cairn completion bash|zsh|fish|powershell
+  cairn version
+  cairn help
+
+Native Windows support does not require WSL or Git Bash. Windows x64 is the
+supported native target; Windows ARM64 currently runs through x64 emulation.`;
+
+function run(executable, args, options = {}) {
+  const result = spawnSync(executable, args, { stdio: "inherit", ...options });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}
+
+function version() {
+  const pkg = JSON.parse(readFileSync(resolve(ROOT, "package.json"), "utf8"));
+  console.log(`cairnkeep ${pkg.version}`);
+}
+
+export async function main(argv) {
+  const [command = "help", ...args] = argv;
+
+  if (["help", "--help", "-h"].includes(command)) {
+    console.log(USAGE);
+    return;
+  }
+  if (["version", "--version", "-v"].includes(command)) {
+    version();
+    return;
+  }
+
+  const nodeEntry = NODE_COMMANDS.get(command);
+  if (nodeEntry) {
+    // Preserve the historical dispatcher contract: child Node resolution comes
+    // from PATH, which supports managed runtimes and test/probe wrappers.
+    run("node", [resolve(ROOT, "mcp-memory-server", "dist", nodeEntry), ...args]);
+    return;
+  }
+
+  if (command === "completion" && args[0] === "powershell") {
+    process.stdout.write(powershellCompletion());
+    return;
+  }
+
+  if (command === "setup" && process.platform !== "win32") {
+    const { runSetup } = await import("./setup.mjs");
+    process.exitCode = await runSetup(args);
+    return;
+  }
+
+  if (process.platform === "win32") {
+    const handled = await runWindowsCommand({ command, args, root: ROOT });
+    if (handled) return;
+  } else {
+    const script = POSIX_COMMANDS.get(command);
+    if (script) {
+      run(resolve(ROOT, "scripts", script), args);
+      return;
+    }
+  }
+
+  console.error(`Unknown command: ${command}`);
+  console.error(USAGE);
+  process.exitCode = 2;
+}

package/scripts/cairn-container-cli.mjs

@@ -0,0 +1,121 @@
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { basename, dirname, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const USAGE = `Usage:
+  cairn-container stdio [--image IMAGE] [--volume VOLUME]
+  cairn-container http --token-file FILE [--port PORT] [--name NAME]
+                       [--allowed-hosts HOSTS] [--image IMAGE]
+                       [--volume VOLUME] [--env-file FILE]
+  cairn-container workspace --repo PATH [--mode sandbox|shared]
+                            [--image IMAGE] [--data-volume VOLUME]
+                            [--workspace-volume VOLUME] [--home-volume VOLUME]
+                            [--env-file FILE] [--secret NAME=FILE]... [--] [COMMAND...]`;
+
+function options(args) {
+  const values = new Map();
+  const rest = [];
+  const valued = new Set(["--image", "--volume", "--token-file", "--port", "--name", "--allowed-hosts", "--env-file", "--repo", "--mode", "--data-volume", "--workspace-volume", "--home-volume", "--secret"]);
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === "--") { rest.push(...args.slice(index + 1)); break; }
+    if (!args[index].startsWith("--")) { rest.push(...args.slice(index)); break; }
+    if (!valued.has(args[index])) throw new Error(`unknown option: ${args[index]}`);
+    if (index + 1 >= args.length) throw new Error(`${args[index]} requires a value`);
+    const value = args[++index];
+    if (args[index - 1] === "--secret") values.set("--secret", [...(values.get("--secret") ?? []), value]);
+    else values.set(args[index - 1], value);
+  }
+  return { values, rest };
+}
+
+function regularFile(path) {
+  const absolute = resolve(path);
+  if (!existsSync(absolute)) throw new Error(`not a regular file: ${path}`);
+  const info = lstatSync(absolute);
+  if (!info.isFile() || info.isSymbolicLink()) throw new Error(`refusing non-regular or symlink file: ${path}`);
+  if (process.platform === "win32") {
+    const script = "$m=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value;$a=Get-Acl -LiteralPath $args[0];$ok=@($m,'S-1-5-18','S-1-5-32-544');foreach($e in $a.Access){if($e.AccessControlType -eq 'Allow'){$s=$e.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value;if($ok -notcontains $s){exit 1}}};exit 0";
+    const acl = spawnSync("powershell.exe", ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script, absolute], { stdio: "ignore", windowsHide: true });
+    if (acl.status !== 0) throw new Error(`secret file ACL must be restricted to the current user and system administrators: ${path}`);
+  }
+  return absolute;
+}
+
+function execute(engine, args) {
+  const result = spawnSync(engine, args, { stdio: "inherit", windowsHide: true });
+  if (result.error) throw result.error;
+  process.exitCode = result.status ?? 1;
+}
+
+function baseArgs() {
+  return ["run", "--rm", "--userns=keep-id:uid=10001,gid=10001", "--cap-drop=all", "--security-opt=no-new-privileges", "--read-only", "--tmpfs=/tmp:rw,noexec,nosuid,size=64m,mode=1777"];
+}
+
+export function runNativeContainer(args, root = ROOT, executor = execute) {
+  const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
+  const engine = process.env.CONTAINER_ENGINE || "podman.exe";
+  const serverImage = process.env.CAIRNKEEP_CONTAINER_IMAGE || `ghcr.io/cairnkeep/cairnkeep:${pkg.version}`;
+  const workspaceImage = process.env.CAIRNKEEP_WORKSPACE_IMAGE || `ghcr.io/cairnkeep/cairnkeep-workspace:${pkg.version}`;
+  const [command = "help", ...commandArgs] = args;
+  if (["help", "-h", "--help"].includes(command)) { console.log(USAGE); return; }
+  const { values, rest } = options(commandArgs);
+  const common = baseArgs();
+  if (command === "stdio") {
+    executor(engine, [...common, "-i", "--volume", `${values.get("--volume") || "cairnkeep-data"}:/data:Z,U`, values.get("--image") || serverImage, "stdio"]);
+    return;
+  }
+  if (command === "http") {
+    if (!values.get("--token-file")) throw new Error("http mode requires --token-file");
+    const token = regularFile(values.get("--token-file"));
+    const port = values.get("--port") || "7801";
+    if (!/^\d+$/.test(port)) throw new Error(`invalid port: ${port}`);
+    const hosts = values.get("--allowed-hosts") || `localhost:${port},127.0.0.1:${port},localhost:7801,127.0.0.1:7801`;
+    const extra = values.get("--env-file") ? ["--env-file", regularFile(values.get("--env-file"))] : [];
+    executor(engine, [...common, "--detach", "--replace", "--name", values.get("--name") || "cairnkeep", ...extra,
+      "--publish", `127.0.0.1:${port}:7801`, "--volume", `${values.get("--volume") || "cairnkeep-data"}:/data:Z,U`,
+      "--volume", `${token}:/run/secrets/http-token:ro,Z`, "--env", "MCP_HTTP_HOST=0.0.0.0", "--env", "MCP_HTTP_PORT=7801",
+      "--env", `CAIRN_MEMORY_HTTP_ALLOWED_HOSTS=${hosts}`, "--env", "CAIRN_MEMORY_HTTP_TOKEN_FILE=/run/secrets/http-token",
+      values.get("--image") || serverImage, "http"]);
+    return;
+  }
+  if (command === "workspace") {
+    if (!values.get("--repo")) throw new Error("workspace mode requires --repo");
+    const repo = resolve(values.get("--repo"));
+    if (!existsSync(repo) || !lstatSync(repo).isDirectory()) throw new Error(`not a directory: ${repo}`);
+    const mode = values.get("--mode") || "sandbox";
+    if (!["sandbox", "shared"].includes(mode)) throw new Error("--mode must be sandbox or shared");
+    const slug = basename(repo).toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+    const id = createHash("sha256").update(repo).digest("hex").slice(0, 12);
+    const workspace = values.get("--workspace-volume") || `cairnkeep-workspace-${slug}-${id}`;
+    const mounts = mode === "shared" ? ["--volume", `${repo}:/workspace:rw,Z`] : ["--volume", `${repo}:/source:ro,Z`, "--volume", `${workspace}:/workspace:Z,U`];
+    const secrets = [];
+    for (const specification of values.get("--secret") ?? []) {
+      const index = specification.indexOf("=");
+      if (index < 1) throw new Error("--secret requires NAME=FILE");
+      const name = specification.slice(0, index);
+      if (!/^[A-Z0-9_]+$/.test(name)) throw new Error(`invalid secret variable name: ${name}`);
+      const file = regularFile(specification.slice(index + 1));
+      const target = name.toLowerCase().replace(/[^a-z0-9_.-]/g, "-");
+      secrets.push("--volume", `${file}:/run/secrets/${target}:ro,Z`, "--env", `${name}_FILE=/run/secrets/${target}`);
+    }
+    const envFile = values.get("--env-file") ? ["--env-file", regularFile(values.get("--env-file"))] : [];
+    executor(engine, [...common, "-i", "--volume", `${values.get("--data-volume") || "cairnkeep-data"}:/data:Z,U`,
+      "--volume", `${values.get("--home-volume") || "cairnkeep-home"}:/home/cairn:Z,U`, "--env", `CAIRN_WORKSPACE_MODE=${mode}`,
+      ...mounts, ...envFile, ...secrets, values.get("--image") || workspaceImage, ...(rest.length ? rest : ["bash"])]);
+    return;
+  }
+  throw new Error(`unknown command: ${command}`);
+}
+
+export async function main(args) {
+  if (process.platform !== "win32") {
+    const result = spawnSync(resolve(ROOT, "scripts", "cairn-container"), args, { stdio: "inherit" });
+    if (result.error) throw result.error;
+    process.exitCode = result.status ?? 1;
+    return;
+  }
+  runNativeContainer(args);
+}