cairn-ai 0.2.2 → 0.2.4

package/scripts/cairn-safe-fs.mjs

@@ -0,0 +1,246 @@
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { link, lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+const LOCK_SCHEMA_VERSION = 1;
+const DEFAULT_LOCK_TIMEOUT_MS = 5_000;
+const DEFAULT_RETRY_MS = 25;
+const DEFAULT_MALFORMED_STALE_MS = 30_000;
+const TRANSIENT_LOCK_ERROR_CODES = new Set(["EACCES", "EBUSY", "EPERM"]);
+
+export function stateLockPath(root = process.cwd()) {
+  return safePath(root, ".cairn/state.lock");
+}
+
+export function safePath(root, relativePath) {
+  const workspaceRoot = resolve(root);
+  const target = resolve(workspaceRoot, relativePath);
+  const relation = relative(workspaceRoot, target);
+  if (relation === ".." || relation.startsWith(`..${sep}`)) {
+    throw new Error(`Managed path must remain inside the workspace: ${relativePath}`);
+  }
+  return target;
+}
+
+export async function assertNoSymlinkComponents(root, target, { allowMissing = true } = {}) {
+  const workspaceRoot = resolve(root);
+  const absoluteTarget = resolve(target);
+  const relation = relative(workspaceRoot, absoluteTarget);
+  if (relation === ".." || relation.startsWith(`..${sep}`)) {
+    throw new Error(`Managed path must remain inside the workspace: ${target}`);
+  }
+  const components = relation === "" ? [] : relation.split(sep);
+  let current = workspaceRoot;
+  await rejectSymlink(current);
+  for (const component of components) {
+    current = join(current, component);
+    try {
+      await rejectSymlink(current);
+    } catch (error) {
+      if (allowMissing && error?.code === "ENOENT") return;
+      throw error;
+    }
+  }
+}
+
+export async function safeMkdir(root, relativePath) {
+  const workspaceRoot = resolve(root);
+  const target = safePath(workspaceRoot, relativePath);
+  await assertNoSymlinkComponents(workspaceRoot, workspaceRoot, { allowMissing: false });
+  const relation = relative(workspaceRoot, target);
+  let current = workspaceRoot;
+  for (const component of relation.split(sep).filter(Boolean)) {
+    current = join(current, component);
+    try {
+      const stat = await lstat(current);
+      if (stat.isSymbolicLink()) throw symlinkError(current);
+      if (!stat.isDirectory()) throw new Error(`Managed directory component is not a directory: ${current}`);
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+      try {
+        await mkdir(current);
+      } catch (mkdirError) {
+        if (mkdirError?.code !== "EEXIST") throw mkdirError;
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink()) throw symlinkError(current);
+        if (!stat.isDirectory()) throw new Error(`Managed directory component is not a directory: ${current}`);
+      }
+    }
+  }
+  return target;
+}
+
+export async function safeWriteFile(root, target, data, options) {
+  const absoluteTarget = safePath(root, relative(resolve(root), resolve(target)));
+  await assertNoSymlinkComponents(root, dirname(absoluteTarget), { allowMissing: false });
+  await assertNoSymlinkComponents(root, absoluteTarget);
+  return writeFile(absoluteTarget, data, options);
+}
+
+export async function withStateLock(root, operation, {
+  timeoutMs = DEFAULT_LOCK_TIMEOUT_MS,
+  retryMs = DEFAULT_RETRY_MS,
+  malformedStaleMs = DEFAULT_MALFORMED_STALE_MS,
+  testHooks = {},
+} = {}) {
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("lock timeoutMs must be a non-negative number");
+  const workspaceRoot = resolve(root);
+  await safeMkdir(workspaceRoot, ".cairn");
+  const lockPath = stateLockPath(workspaceRoot);
+  const owner = {
+    schemaVersion: LOCK_SCHEMA_VERSION,
+    pid: process.pid,
+    hostname: hostname(),
+    nonce: randomUUID(),
+    acquiredAt: new Date().toISOString(),
+  };
+  const deadline = Date.now() + timeoutMs;
+  while (true) {
+    try {
+      await safeWriteFile(workspaceRoot, lockPath, `${JSON.stringify(owner)}\n`, { encoding: "utf8", flag: "wx" });
+      await testHooks.afterLockWritten?.({ lockPath, owner: structuredClone(owner) });
+      if (await confirmsLockOwnership(lockPath, owner.nonce)) break;
+    } catch (error) {
+      if (isTransientLockError(error)) {
+        // Windows can briefly deny a lock file that another process is closing.
+        // Retry within the deadline; permission errors are not evidence of staleness.
+      } else if (error?.code === "EEXIST") {
+        try {
+          await testHooks.beforeContendedLockConfirmation?.({ lockPath });
+          if (await confirmsLockOwnership(lockPath, owner.nonce)) break;
+          const reclaimed = await reclaimStaleLock(workspaceRoot, lockPath, malformedStaleMs, testHooks);
+          if (reclaimed) continue;
+        } catch (inspectionError) {
+          if (!isTransientLockError(inspectionError)) throw inspectionError;
+        }
+      } else {
+        throw error;
+      }
+    }
+    if (Date.now() >= deadline) throw new Error(`Timed out waiting for Cairn state lock after ${timeoutMs}ms`);
+    await delay(Math.min(retryMs, Math.max(1, deadline - Date.now())));
+  }
+
+  try {
+    return await operation();
+  } finally {
+    await releaseOwnedLock(lockPath, owner.nonce);
+  }
+}
+
+async function reclaimStaleLock(root, lockPath, malformedStaleMs, testHooks) {
+  let observed;
+  let stat;
+  try {
+    [observed, stat] = await Promise.all([readFile(lockPath, "utf8"), lstat(lockPath)]);
+  } catch (error) {
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) throw symlinkError(lockPath);
+  const record = parseLockRecord(observed);
+  if (record) {
+    if (record.hostname !== hostname()) return false;
+    if (pidIsAlive(record.pid)) return false;
+  } else if (Date.now() - stat.mtimeMs <= malformedStaleMs) {
+    return false;
+  }
+
+  await testHooks.afterStaleObserved?.({ lockPath, observed, record: record ? structuredClone(record) : null });
+  const quarantine = safePath(root, `.cairn/state.lock.stale.${record?.nonce ?? "malformed"}.${randomUUID()}`);
+  try {
+    await rename(lockPath, quarantine);
+  } catch (error) {
+    if (error?.code === "ENOENT") return true;
+    throw error;
+  }
+  const moved = await readFile(quarantine, "utf8");
+  if (moved !== observed) {
+    const restored = await restoreMovedCandidate(lockPath, quarantine);
+    await testHooks.afterReclaimMismatch?.({ lockPath, restored });
+    return false;
+  }
+  await rm(quarantine, { force: true });
+  return true;
+}
+
+async function restoreMovedCandidate(lockPath, quarantine) {
+  try {
+    await link(quarantine, lockPath);
+    await rm(quarantine);
+    return true;
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    await rm(quarantine, { force: true });
+    return false;
+  }
+}
+
+async function confirmsLockOwnership(lockPath, nonce) {
+  try {
+    return parseLockRecord(await readFile(lockPath, "utf8"))?.nonce === nonce;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function releaseOwnedLock(lockPath, nonce) {
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    try {
+      const record = parseLockRecord(await readFile(lockPath, "utf8"));
+      if (record?.nonce !== nonce) return;
+      await rm(lockPath);
+      return;
+    } catch (error) {
+      if (error?.code === "ENOENT") return;
+      if (!isTransientLockError(error) || attempt === 7) throw error;
+      await delay(10 * (attempt + 1));
+    }
+  }
+}
+
+function isTransientLockError(error) {
+  return TRANSIENT_LOCK_ERROR_CODES.has(error?.code);
+}
+
+function parseLockRecord(text) {
+  try {
+    const value = JSON.parse(text);
+    if (value?.schemaVersion !== LOCK_SCHEMA_VERSION) return null;
+    if (!Number.isSafeInteger(value.pid) || value.pid <= 0) return null;
+    if (typeof value.hostname !== "string" || value.hostname.length === 0) return null;
+    if (typeof value.nonce !== "string" || value.nonce.length === 0) return null;
+    if (typeof value.acquiredAt !== "string" || Number.isNaN(Date.parse(value.acquiredAt))) return null;
+    return value;
+  } catch {
+    return null;
+  }
+}
+
+function pidIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === "EPERM") return true;
+    if (error?.code === "ESRCH") return false;
+    return true;
+  }
+}
+
+async function rejectSymlink(path) {
+  const stat = await lstat(path);
+  if (stat.isSymbolicLink()) throw symlinkError(path);
+}
+
+function symlinkError(path) {
+  const error = new Error(`Managed path must not contain a symbolic link: ${path}`);
+  error.code = "CAIRN_SYMLINK";
+  return error;
+}
+
+function delay(ms) {
+  return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}

package/scripts/cairn-state.mjs

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 import { realpathSync } from "node:fs";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { evaluateStop, isGoalOwnedBySession, readGoalState } from "./cairn-goal.mjs";
 import { resolveRepoRoot } from "./cairn-paths.mjs";
+import { assertNoSymlinkComponents, safeMkdir, safeWriteFile } from "./cairn-safe-fs.mjs";
 
 const memoryTemplate = `# MEMORY
 
@@ -116,7 +117,7 @@ const planTemplateKo = `# PLAN
 
 const contextLimits = {
   goalTitle: 64,
-  taskId: 32,
+  roadmapTaskId: 24,
   taskTitle: 40,
   roadmapWindow: 3,
 };
@@ -157,17 +158,25 @@ export async function runStateResult(event = "manual", {
 
   if (event === "session-start" || event === "user-prompt-submit") {
     const state = await readGoalState({ root: resolvedRoot });
-    if (!isGoalOwnedBySession(state, payload?.session_id)) return { status: 0, message: "", hookOutput: {} };
+    if (state?.goal?.status === "active" && !isGoalOwnedBySession(state, payload?.session_id)) {
+      return foreignSessionContextResult({ ko, event });
+    }
     return contextResult({ ko, state, event });
   }
 
   if (event === "post-tool-use") {
+    const message = ko
+      ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거 기록이 필요합니다. 활성 목표가 있다면 현재 task에 성공 증거를 기록하세요."
+      : "Cairn check: external-state changes need dry-run/check evidence. When a goal is active, record successful evidence for its current task.";
     return {
       status: 0,
-      message: ko
-        ? "Cairn 점검: 외부 상태 변경에는 dry-run/check 증거 기록이 필요합니다. 활성 목표가 있다면 현재 task에 성공 증거를 기록하세요."
-        : "Cairn check: external-state changes need dry-run/check evidence. When a goal is active, record successful evidence for its current task.",
-      hookOutput: {},
+      message,
+      hookOutput: {
+        hookSpecificOutput: {
+          hookEventName: "PostToolUse",
+          additionalContext: message,
+        },
+      },
     };
   }
 
@@ -193,73 +202,98 @@ export async function runStateResult(event = "manual", {
 }
 
 async function initializeProject(root, ko) {
-  await mkdir(join(root, "docs", "memory"), { recursive: true });
-  await mkdir(join(root, "docs", "plan"), { recursive: true });
-  await writeIfMissing(join(root, "MEMORY.md"), ko ? memoryTemplateKo : memoryTemplate);
-  await writeIfMissing(join(root, "PLAN.md"), ko ? planTemplateKo : planTemplate);
+  await safeMkdir(root, "docs/memory");
+  await safeMkdir(root, "docs/plan");
+  await writeIfMissing(root, join(root, "MEMORY.md"), ko ? memoryTemplateKo : memoryTemplate);
+  await writeIfMissing(root, join(root, "PLAN.md"), ko ? planTemplateKo : planTemplate);
 }
 
-async function writeIfMissing(path, content) {
+async function writeIfMissing(root, path, content) {
+  await assertNoSymlinkComponents(root, path);
   try {
     await readFile(path, "utf8");
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
-    await writeFile(path, content);
+    try {
+      await safeWriteFile(root, path, content, { encoding: "utf8", flag: "wx" });
+    } catch (writeError) {
+      if (writeError?.code !== "EEXIST") throw writeError;
+      await assertNoSymlinkComponents(root, path, { allowMissing: false });
+    }
   }
 }
 
 function contextResult({ ko, state, event }) {
-  const base = ko ? "Cairn: 루트 MEMORY.md를 읽으세요." : "Cairn: read root MEMORY.md.";
+  const base = ko ? "Cairn kernel: 루트 MEMORY.md를 먼저 읽으세요." : "Cairn kernel: read root MEMORY.md first.";
   const idlePolicy = event === "user-prompt-submit"
     ? (ko
-      ? " 구현/계속 실행: 초기 트리아지 계획 작성 → update_plan → create_goal → 탐색 전 저장소 goal 시작 → 트리아지 후 계획 확정 → 구현. 상담·설명·계획 전용은 goal 없이 처리하세요."
-      : " Implementation/continue: write an initial triage plan; call update_plan, then create_goal; start the repository goal before exploration; finalize the plan after triage, then implement. Skip goals for consultation, explanation, or plan-only requests.")
-    : "";
-  if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}` });
+      ? " 구현/계속 실행이면 cairn-plan을 로드하고 active plan과 current task를 복원하거나 생성하세요. 상담·설명·계획 전용은 goal 없이 처리하세요."
+      : " For implementation/continue, load cairn-plan and restore or create the active plan and current task. Keep consultation, explanation, and plan-only requests goal-free.")
+    : (ko
+      ? " 중요 작업 전에 cairn-plan을 로드하고 active plan과 current task를 복원하세요."
+      : " Before non-trivial work, load cairn-plan and restore the active plan and current task.");
+  const failClosed = ko
+    ? " state, skill, plan 또는 required reference가 없거나 읽을 수 없거나 일치하지 않으면 수정·위임·완료하지 말고 보고하거나 차단하세요."
+    : " If state, skill, plan, or a required ref is missing, unreadable, or inconsistent, do not edit, delegate, or complete; report/block.";
+  if (!state || state.goal.status !== "active") return contextHookResult({ event, message: `${base}${idlePolicy}${failClosed}` });
   const task = state.tasks.find((item) => item.status === "active")
     ?? state.tasks.find((item) => item.status === "pending")
     ?? state.tasks.find((item) => item.status === "blocked");
-  const goalTitle = clipText(state.goal.title, contextLimits.goalTitle);
+  const planId = state.goal.planId;
+  const phase = task ? "cairn-work" : "cairn-review";
   const activeHeader = ko
-    ? `Cairn active: "${goalTitle}". ${base}`
-    : `Cairn active: "${goalTitle}". ${base}`;
+    ? `${base} ${phase}를 로드하고 정확한 plan ${planId}${task ? "과 아래 current task" : "의 완료 기준"}를 복원하세요. 압축·재시작·handoff·위임 뒤 다시 읽으세요.${failClosed}`
+    : `${base} Load ${phase}; restore exact plan ${planId}${task ? " and the current task below" : " completion criteria"}. Re-read after compaction/restart/handoff/delegation.${failClosed}`;
   if (!task) {
     return contextHookResult({
       event,
       message: [activeHeader, taskRoadmap(ko, state), activeGoalCompletionMessage(ko, state)].join("\n"),
     });
   }
-  const taskId = clipText(task.id, contextLimits.taskId);
+  const taskId = task.id;
   const taskTitle = clipText(task.title, contextLimits.taskTitle);
-  const continuation = ko
-    ? `현재: ${taskId} (${taskTitle}). 바인딩된 증거 뒤에만 완료하세요.`
-    : `Current: ${taskId} (${taskTitle}). Complete only after bound evidence.`;
-  const resume = event === "user-prompt-submit"
+  const continuation = taskId.length > 48
     ? (ko
-      ? `곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 ${taskId}를 재개하세요.`
-      : `After a side question, resume ${taskId} unless asked to pause, stop, or switch.`)
+      ? `정확한 current task: ${taskId}. 바인딩된 증거 뒤에만 완료하세요.`
+      : `Exact task: ${taskId}. Complete after bound evidence.`)
+    : (ko
+      ? `현재: ${taskId} (${taskTitle}). 바인딩된 증거 뒤에만 완료하세요.`
+      : `Current: ${taskId} (${taskTitle}). Complete only after bound evidence.`);
+  const resume = event === "user-prompt-submit"
+    ? (taskId.length > 48
+      ? (ko
+        ? "곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 위의 정확한 task를 재개하세요."
+        : "Resume that exact task after side questions unless paused, stopped, or switched.")
+      : (ko
+        ? `곁가지 질문 뒤 일시정지·중단·전환 요청이 없으면 ${taskId}를 재개하세요.`
+        : `After a side question, resume ${taskId} unless asked to pause, stop, or switch.`))
     : "";
   return contextHookResult({ event, message: [activeHeader, taskRoadmap(ko, state), continuation, resume].filter(Boolean).join("\n") });
 }
 
+function foreignSessionContextResult({ ko, event }) {
+  const message = ko
+    ? "Cairn kernel: 루트 MEMORY.md를 먼저 읽으세요. 저장소 goal을 다른 session이 소유합니다. cairn goal status로 상태를 확인하고 소유권이 해결될 때까지 Cairn 작업을 시작·수정·위임·완료하지 마세요. 이 capsule은 goal, plan, task 상세를 노출하지 않습니다."
+    : "Cairn kernel: read root MEMORY.md first. A repository goal is owned by another session. Inspect cairn goal status; until ownership is resolved, do not start, edit, delegate, or complete Cairn work. This capsule does not expose goal, plan, or task details.";
+  return contextHookResult({ event, message });
+}
+
 function taskRoadmap(ko, state) {
-  const formatTask = (task, index) => `${index + 1}. ${clipText(task.id, contextLimits.taskId)} [${task.status}] ${clipText(task.title, contextLimits.taskTitle)}`;
+  const formatTask = (task, index) => `${index + 1}. ${clipText(task.id, contextLimits.roadmapTaskId)} [${task.status}] ${clipText(task.title, contextLimits.taskTitle)}`;
   if (state.tasks.length <= contextLimits.roadmapWindow) {
     return `${ko ? "작업 단계" : "Work steps"}:\n${state.tasks.map(formatTask).join("\n")}`;
   }
 
   const currentIndex = Math.max(0, state.tasks.findIndex((task) => task.status === "active" || task.status === "pending"));
-  const maxStart = state.tasks.length - contextLimits.roadmapWindow;
-  const start = Math.min(Math.max(0, currentIndex - 1), maxStart);
-  const visible = state.tasks.slice(start, start + contextLimits.roadmapWindow);
   const counts = Object.fromEntries([...TASK_STATUS_NAMES].map((status) => [status, state.tasks.filter((task) => task.status === status).length]));
   const countSummary = Object.entries(counts).filter(([, count]) => count > 0).map(([status, count]) => `${status} ${count}`).join(", ");
-  const omitted = state.tasks.length - visible.length;
+  const omitted = state.tasks.length - 1;
   const header = ko
     ? `작업 단계 (${state.tasks.length}개; ${countSummary})`
     : `Work steps (${state.tasks.length}; ${countSummary})`;
   const omission = ko ? `… ${omitted}개 단계 생략` : `… ${omitted} steps omitted`;
-  return `${header}:\n${visible.map((task, index) => formatTask(task, start + index)).join("\n")}\n${omission}`;
+  const currentPosition = currentIndex + 1;
+  return `${header}. ${ko ? `현재 위치 ${currentPosition}` : `Current position ${currentPosition}`}; ${omission}`;
 }
 
 function contextHookResult({ event, message }) {