Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
feat(store): add atomic writes, directory locks and locked JSON stores
Eren223822cd30c0
diff --git a/packages/cli/src/store/fs.ts b/packages/cli/src/store/fs.tsnew file mode 100644index 0000000..15c841c--- /dev/null+++ b/packages/cli/src/store/fs.ts@@ -0,0 +1,48 @@+import { randomBytes } from "node:crypto";+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";+import { basename, dirname, join } from "node:path";++/** Writes via a temp file in the same directory and renames it into place. */+export async function atomicWrite(file: string, data: string): Promise<void> {+ const dir = dirname(file);+ await mkdir(dir, { recursive: true });+ const tmp = join(dir, `.${basename(file)}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`);+ const fh = await open(tmp, "w");+ try {+ await fh.writeFile(data);+ await fh.sync();+ } finally {+ await fh.close();+ }+ try {+ await rename(tmp, file);+ } catch (err) {+ await rm(tmp, { force: true });+ throw err;+ }+}++export async function atomicWriteJson(file: string, value: unknown): Promise<void> {+ await atomicWrite(file, `${JSON.stringify(value, null, 2)}\n`);+}++export type JsonRead =+ | { found: false }+ | { found: true; value: unknown }+ | { found: true; error: string };++/** Reads a JSON file; a missing file is not an error, invalid JSON is reported. */+export async function readJson(file: string): Promise<JsonRead> {+ let text: string;+ try {+ text = await readFile(file, "utf8");+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code === "ENOENT") return { found: false };+ throw err;+ }+ try {+ return { found: true, value: JSON.parse(text) };+ } catch (err) {+ return { found: true, error: `invalid JSON: ${(err as Error).message}` };+ }+}diff --git a/packages/cli/src/store/lock.ts b/packages/cli/src/store/lock.tsnew file mode 100644index 0000000..31a4416--- /dev/null+++ b/packages/cli/src/store/lock.ts@@ -0,0 +1,72 @@+import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";+import { dirname, join } from "node:path";+import { setTimeout as sleep } from "node:timers/promises";++export interface LockOptions {+ /** Give up after this long. 0 = try once. */+ timeoutMs?: number;+ /** A lock older than this is considered abandoned. */+ staleMs?: number;+}++export class LockBusyError extends Error {+ constructor(readonly lockPath: string) {+ super(`lock is held: ${lockPath}`);+ }+}++function alive(pid: number): boolean {+ try {+ process.kill(pid, 0);+ return true;+ } catch (err) {+ return (err as NodeJS.ErrnoException).code === "EPERM";+ }+}++async function isStale(lockPath: string, staleMs: number): Promise<boolean> {+ try {+ const owner = Number.parseInt(await readFile(join(lockPath, "owner"), "utf8"), 10);+ if (Number.isInteger(owner) && owner > 0 && !alive(owner)) return true;+ } catch {+ // owner not written yet (or already gone): fall back to age+ }+ // the lock may vanish between mkdir and stat; then it is not stale, just retry+ const info = await stat(lockPath).catch(() => undefined);+ return info !== undefined && Date.now() - info.mtimeMs > staleMs;+}++async function acquire(lockPath: string, opts: LockOptions): Promise<void> {+ const { timeoutMs = 10_000, staleMs = 60_000 } = opts;+ const deadline = Date.now() + timeoutMs;+ await mkdir(dirname(lockPath), { recursive: true });+ for (let delay = 20; ; delay = Math.min(delay * 2, 250)) {+ try {+ await mkdir(lockPath);+ await writeFile(join(lockPath, "owner"), String(process.pid));+ return;+ } catch (err) {+ if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;+ }+ if (await isStale(lockPath, staleMs)) {+ await rm(lockPath, { recursive: true, force: true });+ continue;+ }+ if (Date.now() >= deadline) throw new LockBusyError(lockPath);+ await sleep(delay);+ }+}++/** Runs `fn` while holding a directory lock (mkdir is atomic on every platform). */+export async function withLock<T>(+ lockPath: string,+ fn: () => Promise<T>,+ opts: LockOptions = {},+): Promise<T> {+ await acquire(lockPath, opts);+ try {+ return await fn();+ } finally {+ await rm(lockPath, { recursive: true, force: true });+ }+}diff --git a/packages/cli/src/store/paths.ts b/packages/cli/src/store/paths.tsnew file mode 100644index 0000000..5528b86--- /dev/null+++ b/packages/cli/src/store/paths.ts@@ -0,0 +1,32 @@+import { homedir } from "node:os";+import { join } from "node:path";++export const DIR_NAME = ".codelineage";++export function projectPaths(root: string) {+ const base = join(root, DIR_NAME);+ return {+ base,+ project: join(base, "project.json"),+ sessions: join(base, "sessions"),+ session: (id: string) => join(base, "sessions", `${id}.json`),+ state: (id: string) => join(base, "state", `${id}.json`),+ snapshots: join(base, "snapshots"),+ locks: join(base, "locks"),+ lock: (name: string) => join(base, "locks", `${name}.lock`),+ html: join(base, "lineage.html"),+ };+}++/** `CODELINEAGE_HOME` > `$XDG_CONFIG_HOME/codelineage` > `~/.config/codelineage`. */+export function globalPaths(env: NodeJS.ProcessEnv = process.env) {+ const base =+ env.CODELINEAGE_HOME ?? join(env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "codelineage");+ return {+ base,+ config: join(base, "config.json"),+ registry: join(base, "projects.json"),+ lock: join(base, "registry.lock"),+ panel: join(base, "panel.html"),+ };+}diff --git a/packages/cli/src/store/stores.ts b/packages/cli/src/store/stores.tsnew file mode 100644index 0000000..b7e1cc6--- /dev/null+++ b/packages/cli/src/store/stores.ts@@ -0,0 +1,93 @@+import type { z } from "zod";+import { CONFIG_SCHEMA, Config, Registry } from "../schema/config.js";+import { PROJECT_SCHEMA, Project } from "../schema/project.js";+import { SESSION_SCHEMA, Session } from "../schema/session.js";+import { type Parsed, parseVersioned } from "../schema/versioned.js";+import { atomicWriteJson, readJson } from "./fs.js";+import { type LockOptions, withLock } from "./lock.js";+import { globalPaths, projectPaths } from "./paths.js";++export type Loaded<T> = { found: false } | ({ found: true } & Parsed<T>);++async function load<S extends z.ZodType>(+ file: string,+ schema: S,+ version: number,+): Promise<Loaded<z.infer<S>>> {+ const read = await readJson(file);+ if (!read.found) return { found: false };+ if ("error" in read) return { found: true, ok: false, error: read.error, warnings: [] };+ return { found: true, ...parseVersioned(read.value, schema, version) };+}++/**+ * Locked read → update → atomic write. `fn` gets the current value (undefined if+ * the file is missing) and returns the new one. An unreadable file is an error,+ * never silently overwritten.+ */+async function update<S extends z.ZodType, R extends z.infer<S>>(+ file: string,+ lockPath: string,+ schema: S,+ version: number,+ fn: (current: z.infer<S> | undefined) => R | Promise<R>,+ opts?: LockOptions,+): Promise<R> {+ return withLock(+ lockPath,+ async () => {+ const cur = await load(file, schema, version);+ if (cur.found && !cur.ok) throw new Error(`${file}: ${cur.error}`);+ const next = await fn(cur.found && cur.ok ? cur.data : undefined);+ await atomicWriteJson(file, schema.parse(next));+ return next;+ },+ opts,+ );+}++export const loadProject = (root: string) =>+ load(projectPaths(root).project, Project, PROJECT_SCHEMA);++export const updateProject = (+ root: string,+ fn: (cur: Project | undefined) => Project | Promise<Project>,+) => {+ const p = projectPaths(root);+ return update(p.project, p.lock("project"), Project, PROJECT_SCHEMA, fn);+};++export const loadSession = (root: string, id: string) =>+ load(projectPaths(root).session(id), Session, SESSION_SCHEMA);++export const updateSession = (+ root: string,+ id: string,+ fn: (cur: Session | undefined) => Session | Promise<Session>,+ opts?: LockOptions,+) => {+ const p = projectPaths(root);+ return update(p.session(id), p.lock(`session-${id}`), Session, SESSION_SCHEMA, fn, opts);+};++export const loadConfig = async (env?: NodeJS.ProcessEnv): Promise<Config> => {+ const cur = await load(globalPaths(env).config, Config, CONFIG_SCHEMA);+ return cur.found && cur.ok ? cur.data : Config.parse({ schema: CONFIG_SCHEMA });+};++export const updateConfig = (fn: (cur: Config) => Config, env?: NodeJS.ProcessEnv) => {+ const g = globalPaths(env);+ return update(g.config, `${g.config}.lock`, Config, CONFIG_SCHEMA, (cur) =>+ fn(cur ?? Config.parse({ schema: CONFIG_SCHEMA })),+ );+};++export const loadRegistry = (env?: NodeJS.ProcessEnv) =>+ load(globalPaths(env).registry, Registry, CONFIG_SCHEMA);++export const updateRegistry = (fn: (cur: Registry) => Registry, env?: NodeJS.ProcessEnv) => {+ const g = globalPaths(env);+ return update(g.registry, g.lock, Registry, CONFIG_SCHEMA, (cur) =>+ fn(cur ?? Registry.parse({ schema: CONFIG_SCHEMA })),+ );+};diff --git a/packages/cli/test/store.test.ts b/packages/cli/test/store.test.tsnew file mode 100644index 0000000..40df64a--- /dev/null+++ b/packages/cli/test/store.test.ts@@ -0,0 +1,214 @@+import { chmod, mkdir, mkdtemp, readdir, readFile, utimes, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { beforeEach, describe, expect, it } from "vitest";+import { atomicWrite, atomicWriteJson, readJson } from "../src/store/fs.js";+import { LockBusyError, withLock } from "../src/store/lock.js";+import { globalPaths, projectPaths } from "../src/store/paths.js";+import {+ loadConfig,+ loadProject,+ loadRegistry,+ loadSession,+ updateConfig,+ updateProject,+ updateRegistry,+ updateSession,+} from "../src/store/stores.js";++let dir: string;+let env: NodeJS.ProcessEnv;+beforeEach(async () => {+ dir = await mkdtemp(join(tmpdir(), "codelineage-"));+ env = { CODELINEAGE_HOME: join(dir, "home") };+});++const T0 = "2026-10-21T10:00:00.000Z";++describe("paths", () => {+ it("resolves the global dir from env", () => {+ expect(globalPaths({ CODELINEAGE_HOME: "/x" }).config).toBe("/x/config.json");+ expect(globalPaths({ XDG_CONFIG_HOME: "/xdg" }).base).toBe("/xdg/codelineage");+ expect(globalPaths({}).base).toMatch(/\.config\/codelineage$/);+ });++ it("lays out the project dir", () => {+ const p = projectPaths("/r");+ expect(p.session("s1")).toBe("/r/.codelineage/sessions/s1.json");+ expect(p.state("s1")).toBe("/r/.codelineage/state/s1.json");+ expect(p.lock("project")).toBe("/r/.codelineage/locks/project.lock");+ expect([p.snapshots, p.html]).toEqual([+ "/r/.codelineage/snapshots",+ "/r/.codelineage/lineage.html",+ ]);+ });+});++describe("fs", () => {+ it("writes atomically without leaving temp files", async () => {+ const f = join(dir, "a", "b.json");+ await atomicWriteJson(f, { x: 1 });+ expect(JSON.parse(await readFile(f, "utf8"))).toEqual({ x: 1 });+ expect(await readdir(join(dir, "a"))).toEqual(["b.json"]);+ });++ it("cleans up the temp file when the rename fails", async () => {+ const target = join(dir, "isdir");+ await mkdir(join(target, "child"), { recursive: true });+ await expect(atomicWrite(target, "x")).rejects.toThrow();+ expect((await readdir(dir)).filter((n) => n.endsWith(".tmp"))).toEqual([]);+ });++ it("reads missing, invalid and valid JSON", async () => {+ expect(await readJson(join(dir, "nope.json"))).toEqual({ found: false });+ await writeFile(join(dir, "bad.json"), "{");+ expect(await readJson(join(dir, "bad.json"))).toMatchObject({+ found: true,+ error: /invalid JSON/,+ });+ await writeFile(join(dir, "ok.json"), '{"a":1}');+ expect(await readJson(join(dir, "ok.json"))).toEqual({ found: true, value: { a: 1 } });+ await expect(readJson(dir)).rejects.toThrow();+ });+});++describe("withLock", () => {+ it("serializes concurrent critical sections", async () => {+ const lock = join(dir, "locks", "x.lock");+ let inside = 0;+ let maxInside = 0;+ await Promise.all(+ Array.from({ length: 8 }, () =>+ withLock(lock, async () => {+ inside++;+ maxInside = Math.max(maxInside, inside);+ await new Promise((r) => setTimeout(r, 5));+ inside--;+ }),+ ),+ );+ expect(maxInside).toBe(1);+ });++ it("fails fast when busy and timeout is 0", async () => {+ const lock = join(dir, "x.lock");+ await withLock(lock, async () => {+ await expect(withLock(lock, async () => 1, { timeoutMs: 0 })).rejects.toBeInstanceOf(+ LockBusyError,+ );+ });+ });++ it("releases the lock when fn throws", async () => {+ const lock = join(dir, "x.lock");+ await expect(withLock(lock, async () => Promise.reject(new Error("boom")))).rejects.toThrow(+ "boom",+ );+ expect(await withLock(lock, async () => "free", { timeoutMs: 0 })).toBe("free");+ });++ it("takes over a lock whose owner process is gone", async () => {+ const lock = join(dir, "x.lock");+ await mkdir(lock);+ await writeFile(join(lock, "owner"), "999999999");+ expect(await withLock(lock, async () => "ok", { timeoutMs: 0 })).toBe("ok");+ });++ it("takes over a lock older than staleMs, but not a live recent one", async () => {+ const lock = join(dir, "x.lock");+ await mkdir(lock);+ await writeFile(join(lock, "owner"), "1"); // pid 1 is alive (EPERM for non-root)+ await expect(withLock(lock, async () => 1, { timeoutMs: 0 })).rejects.toBeInstanceOf(+ LockBusyError,+ );+ const old = new Date(Date.now() - 120_000);+ await utimes(lock, old, old);+ expect(await withLock(lock, async () => "ok", { timeoutMs: 0 })).toBe("ok");+ });++ it("treats a recent lock without an owner file as held", async () => {+ const lock = join(dir, "x.lock");+ await mkdir(lock);+ await expect(withLock(lock, async () => 1, { timeoutMs: 0 })).rejects.toBeInstanceOf(+ LockBusyError,+ );+ });++ it("rethrows unexpected mkdir errors", async () => {+ const ro = join(dir, "ro");+ await mkdir(ro);+ await chmod(ro, 0o555);+ await expect(withLock(join(ro, "x.lock"), async () => 1)).rejects.toMatchObject({+ code: "EACCES",+ });+ await chmod(ro, 0o755);+ });+});++describe("stores", () => {+ it("creates and updates project.json under the lock", async () => {+ expect(await loadProject(dir)).toEqual({ found: false });+ await updateProject(dir, (cur) => cur ?? { schema: 1, name: "p", epochs: [] });+ await updateProject(dir, (cur) => ({+ ...(cur ?? { schema: 1, name: "p", epochs: [] }),+ epochs: [{ id: "e1", title: "E", createdAt: T0 }],+ }));+ expect(await loadProject(dir)).toMatchObject({+ found: true,+ ok: true,+ data: { epochs: [{ id: "e1" }] },+ });+ });++ it("never overwrites an unreadable file", async () => {+ const p = projectPaths(dir);+ await mkdir(p.base, { recursive: true });+ await writeFile(p.project, "{broken");+ await expect(updateProject(dir, () => ({ schema: 1, name: "p", epochs: [] }))).rejects.toThrow(+ /invalid JSON/,+ );+ expect(await readFile(p.project, "utf8")).toBe("{broken");+ expect(await loadProject(dir)).toMatchObject({ found: true, ok: false });+ });++ it("keeps every concurrent session update", async () => {+ await Promise.all(+ Array.from({ length: 10 }, (_, i) =>+ updateSession(dir, "s1", (cur) => ({+ ...(cur ?? {+ schema: 1,+ sessionId: "s1",+ agent: "claude-code",+ title: "",+ epoch: null,+ startedAt: T0,+ updatedAt: T0,+ status: { goal: "", done: [], pending: [], next: "" },+ nodes: [],+ }),+ nodes: [+ ...(cur?.nodes ?? []),+ { id: `n${i}`, parent: null, kind: "step", title: `${i}` },+ ],+ })),+ ),+ );+ const s = await loadSession(dir, "s1");+ expect(s.found && s.ok && s.data.nodes).toHaveLength(10);+ });++ it("returns default config and persists changes", async () => {+ expect((await loadConfig(env)).updateEveryTurns).toBe(5);+ await updateConfig((c) => ({ ...c, updateEveryTurns: 3 }), env);+ expect((await loadConfig(env)).updateEveryTurns).toBe(3);+ });++ it("registers projects in the global registry", async () => {+ await updateRegistry((r) => ({ ...r, projects: [{ path: dir, name: "p", addedAt: T0 }] }), env);+ expect(await loadRegistry(env)).toMatchObject({+ found: true,+ ok: true,+ data: { projects: [{ name: "p" }] },+ });+ });+});