Skip to content

armgit / cogit

Public Imported from GitHub
0

Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.

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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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" }] },
+ });
+ });
+});