@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/workspace-principals.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/principals/v1/workspace-principals.schema.json",
+  "title": "workspace-principals.json",
+  "description": "Principal classes a plugin supplies (#2524 D5, #3080, ws-079). A package publishes this file as data at its ./workspace-principals subpath, beside ./workspace-kinds. chant reads it with the file system and never imports the package. A class is a name for the principals holding one role in the trust policy at base; the declaration's writeScope may then give it an entry.",
+  "type": "object",
+  "required": ["schema", "classes"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "An editor hint. chant ignores it."
+    },
+    "$comment": {
+      "type": "string",
+      "description": "A note for people. chant ignores it."
+    },
+    "schema": {
+      "const": 1,
+      "description": "The principal classes format version."
+    },
+    "classes": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/class"
+      }
+    }
+  },
+  "patternProperties": {
+    "^x-": true
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "class": {
+      "type": "object",
+      "required": ["name", "description", "role"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^(?!x-)[a-z][a-z0-9-]{0,39}$",
+          "description": "The class's name, as a key of the declaration's writeScope names it. human, agent, runner and service are the core classes and can't be supplied."
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "One line saying who is in the class, for listings and error messages."
+        },
+        "role": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "The role whose grant in the trust policy at base (.chant/trust.json roles) puts a principal in this class. The agent, runner and service roles belong to the core classes and can't be named here. One role puts a principal in one class."
+        }
+      },
+      "patternProperties": {
+        "^x-": true
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/src/workspace/write-lock-cli.ts

@@ -0,0 +1,131 @@
+/**
+ * `chant workspace lock` (#3173, ws-089): the working tree's write lock
+ * (`write-lock.ts`), seen and held from outside chant.
+ *
+ * - `lock` prints who holds it now, or that nobody does.
+ * - `lock acquire --holder <name> [--ttl <duration>]` takes it for a batch of
+ *   writes across several chant calls, waiting for it as a write does, and
+ *   prints the token. Each chant write of the batch runs with
+ *   `CHANT_WRITE_LOCK=<token>` and goes ahead without waiting; every other
+ *   writer waits. The lock lasts until it is released or the ttl passes
+ *   (default 60s, at most 10m), after which any writer may break it.
+ * - `lock release --token <token>` gives it back.
+ *
+ * Each prints one JSON document (`write-lock.schema.json`); a refusal exits 1.
+ * The token is printed only to the caller that took the lock: `lock` never
+ * prints it, so holding the lock can't be taken over by reading who holds it.
+ */
+
+import type { CommandContext } from "../cli/registry";
+import { parseDuration } from "../op/duration";
+import { readerVersion } from "./declaration";
+import {
+  acquireBatchLock,
+  DEFAULT_BATCH_TTL_MS,
+  MAX_BATCH_TTL_MS,
+  releaseLock,
+  writeLockHolder,
+  writeLockPath,
+  WriteLockError,
+  type WriteLockHolder,
+} from "./write-lock";
+import { AGENT_ENV } from "./write-scope";
+
+export const WRITE_LOCK_CONTRACT_VERSION = 1;
+export const WRITE_LOCK_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json";
+
+/** Why a lock command did nothing. Closed. */
+export const WRITE_LOCK_ERROR_CODES = ["write-usage-invalid", "write-lock-timeout", "write-lock-not-held"] as const;
+export type WriteLockErrorCode = (typeof WRITE_LOCK_ERROR_CODES)[number];
+
+/** A holder as the documents show it: everything but the token. */
+export type HolderView = Omit<WriteLockHolder, "token">;
+
+export type WriteLockDocument =
+  | {
+      $schema: string;
+      contract: number;
+      chant: string;
+      verb: "status" | "acquire" | "release";
+      /** The lock directory. */
+      path: string;
+      /** Who holds the lock after the command: the batch for acquire, null after release. */
+      holder: HolderView | null;
+      /** acquire only: the token each write of the batch runs with, as CHANT_WRITE_LOCK. */
+      token?: string;
+    }
+  | { $schema: string; contract: number; chant: string; verb: "status" | "acquire" | "release"; error: { code: WriteLockErrorCode; message: string }; holder: HolderView | null };
+
+const USAGE = "chant workspace lock [acquire --holder <name> [--ttl <duration>] | release --token <token>] [--json]";
+
+function view(h: WriteLockHolder | null): HolderView | null {
+  if (h === null) return null;
+  const { token: _token, ...rest } = h;
+  return rest;
+}
+
+/** Run one lock command and build its document. */
+export async function workspaceLock(req: { cwd: string; verb: string | undefined; holder?: string; ttl?: string; token?: string; agent?: string }): Promise<WriteLockDocument> {
+  const verb = req.verb === undefined || req.verb === "status" ? "status" : req.verb === "acquire" || req.verb === "release" ? req.verb : null;
+  const head = { $schema: WRITE_LOCK_SCHEMA_ID, contract: WRITE_LOCK_CONTRACT_VERSION, chant: readerVersion() };
+  const fail = (v: "status" | "acquire" | "release", code: WriteLockErrorCode, message: string, holder: WriteLockHolder | null = null): WriteLockDocument => ({
+    ...head,
+    verb: v,
+    error: { code, message: code === "write-usage-invalid" ? `${message}\n${USAGE}` : message },
+    holder: view(holder),
+  });
+  if (verb === null) return fail("status", "write-usage-invalid", `lock takes acquire or release, or nothing to say who holds it, not ${req.verb}`);
+  if (verb === "status") {
+    if (req.holder !== undefined || req.ttl !== undefined || req.token !== undefined) return fail(verb, "write-usage-invalid", "lock with no verb only says who holds the lock, and takes no --holder, --ttl or --token");
+    const { path, holder } = writeLockHolder(req.cwd);
+    return { ...head, verb, path, holder: view(holder) };
+  }
+  if (verb === "acquire") {
+    if (!req.holder) return fail(verb, "write-usage-invalid", "lock acquire needs --holder <name>: who holds the lock, as the other writers waiting on it are told");
+    if (req.token !== undefined) return fail(verb, "write-usage-invalid", "lock acquire hands out a token, and takes none");
+    let ttlMs = DEFAULT_BATCH_TTL_MS;
+    if (req.ttl !== undefined) {
+      const ms = /^\d+$/.test(req.ttl) ? Number(req.ttl) * 1000 : parseDurationOrNull(req.ttl);
+      if (ms === null || ms <= 0 || ms > MAX_BATCH_TTL_MS) return fail(verb, "write-usage-invalid", `--ttl takes a duration up to ${MAX_BATCH_TTL_MS / 60_000}m, such as 90s or 5m, not ${JSON.stringify(req.ttl)}`);
+      ttlMs = ms;
+    }
+    try {
+      const { path, holder } = await acquireBatchLock(req.cwd, { verb: "batch", by: req.holder, agent: req.agent ?? null }, ttlMs);
+      return { ...head, verb, path, holder: view(holder), token: holder.token };
+    } catch (err) {
+      if (err instanceof WriteLockError) return fail(verb, err.code, err.message, err.holder);
+      throw err;
+    }
+  }
+  if (!req.token) return fail(verb, "write-usage-invalid", "lock release needs --token <token>, as lock acquire printed it");
+  if (req.holder !== undefined || req.ttl !== undefined) return fail(verb, "write-usage-invalid", "lock release takes only --token");
+  const path = writeLockPath(req.cwd);
+  if (!releaseLock(path, req.token)) {
+    const { holder } = writeLockHolder(req.cwd);
+    return fail(verb, "write-lock-not-held", `the token given does not hold the write lock (${holder ? "another writer holds it" : "nobody holds it"}): it was released already, or it expired`, holder);
+  }
+  return { ...head, verb, path, holder: null };
+}
+
+function parseDurationOrNull(raw: string): number | null {
+  try {
+    return parseDuration(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** `chant workspace lock [acquire|release]`. Prints one JSON document; exits 1 on a refusal. */
+export async function runWorkspaceLock(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  const doc = await workspaceLock({
+    cwd: process.cwd(),
+    verb: args.extraPositional,
+    holder: args.holder,
+    ttl: args.ttl,
+    token: args.token,
+    agent: process.env[AGENT_ENV] || undefined,
+  });
+  console.log(JSON.stringify(doc, null, 2));
+  return "error" in doc ? 1 : 0;
+}

package/src/workspace/write-lock.schema.json

@@ -0,0 +1,172 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json",
+  "title": "chant workspace lock output",
+  "description": "What `chant workspace lock [acquire --holder <name> [--ttl <duration>] | release --token <token>]` prints (#3173, ws-089): who holds the working tree's write lock, the token of a batch that took it, or the reason the command did nothing. Every chant write to the working tree (records new, amend, review and close, points ask and answer, box listing set) holds this lock from its first read to its last write. A batch holds it across chant calls: each call runs with CHANT_WRITE_LOCK=<token> and goes ahead without waiting while the token holds it. Readers ignore fields they do not know; a field is only ever added within a version. The error codes are a closed list, each in the one closed list of `reason-codes.ts`.",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/result"
+    },
+    {
+      "$ref": "#/$defs/failure"
+    }
+  ],
+  "$defs": {
+    "result": {
+      "type": "object",
+      "description": "Exit code 0.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "verb",
+        "path",
+        "holder"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string",
+          "description": "The chant version that printed it."
+        },
+        "verb": {
+          "enum": [
+            "status",
+            "acquire",
+            "release"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "description": "The lock directory: chant-write.lock in the working tree's git directory, or a directory under the system's temporary directory outside git."
+        },
+        "holder": {
+          "$ref": "#/$defs/holder"
+        },
+        "token": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{32}$",
+          "description": "acquire only: the token each write of the batch runs with, as CHANT_WRITE_LOCK, and lock release takes. Never printed by status."
+        },
+        "error": false
+      }
+    },
+    "failure": {
+      "type": "object",
+      "description": "Nothing was done. Exit code 1.",
+      "required": [
+        "$schema",
+        "contract",
+        "chant",
+        "verb",
+        "error",
+        "holder"
+      ],
+      "properties": {
+        "$schema": {
+          "const": "https://intentius.io/chant/schemas/workspace/write-lock/v1/write-lock.schema.json"
+        },
+        "contract": {
+          "const": 1
+        },
+        "chant": {
+          "type": "string"
+        },
+        "verb": {
+          "enum": [
+            "status",
+            "acquire",
+            "release"
+          ]
+        },
+        "error": {
+          "type": "object",
+          "required": [
+            "code",
+            "message"
+          ],
+          "properties": {
+            "code": {
+              "enum": [
+                "write-usage-invalid",
+                "write-lock-timeout",
+                "write-lock-not-held"
+              ]
+            },
+            "message": {
+              "type": "string"
+            }
+          }
+        },
+        "holder": {
+          "$ref": "#/$defs/holder"
+        },
+        "token": false
+      }
+    },
+    "holder": {
+      "description": "Who holds the lock: everything owner.json in the lock directory says but the token.",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "required": [
+            "pid",
+            "host",
+            "verb",
+            "by",
+            "agent",
+            "acquiredAt",
+            "expiresAt"
+          ],
+          "properties": {
+            "pid": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "description": "The process holding it, or null for a batch held across chant calls."
+            },
+            "host": {
+              "type": "string",
+              "description": "The host the holder runs on."
+            },
+            "verb": {
+              "type": "string",
+              "description": "What holds it: a write command, such as records amend, or batch."
+            },
+            "by": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "Who the write or batch names: --by, or lock acquire's --holder."
+            },
+            "agent": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "description": "The agent session (CHANT_AGENT), or null."
+            },
+            "acquiredAt": {
+              "type": "string",
+              "description": "When it was taken, as an ISO 8601 time."
+            },
+            "expiresAt": {
+              "type": "string",
+              "description": "When any writer may break it, as an ISO 8601 time."
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/src/workspace/write-lock.test.ts

@@ -0,0 +1,189 @@
+/**
+ * The working tree's write lock and write journal (#3173, ws-089): where the
+ * lock lives, that writes in one process and across a batch serialise, that a
+ * dead or expired holder is broken, that a waiter is refused naming the
+ * holder, and that the journal names a record's last writer only while the
+ * file holds what that write left.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { hostname, tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, afterEach, describe, expect, test } from "vitest";
+import { cleanScratch, contract, git, repo, scratchDir } from "./__fixtures__/contract-repo";
+import writeLockSchema from "./write-lock.schema.json";
+import { workspaceLock } from "./write-lock-cli";
+import {
+  gitDirOf,
+  lastWriteReader,
+  noteWrites,
+  WRITE_LOCK_ENV,
+  WRITE_LOCK_WAIT_ENV,
+  withWriteLock,
+  withWriteLockSync,
+  WriteLockError,
+  writeLockHolder,
+  writeLockPath,
+} from "./write-lock";
+
+afterAll(cleanScratch);
+afterEach(() => {
+  delete process.env[WRITE_LOCK_ENV];
+  delete process.env[WRITE_LOCK_WAIT_ENV];
+});
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+const lockDoc = contract(writeLockSchema);
+
+/** Put a lock in place as another process would have left it. */
+function plant(start: string, over: Record<string, unknown>): string {
+  const lock = writeLockPath(start);
+  mkdirSync(lock);
+  const now = Date.now();
+  writeFileSync(
+    join(lock, "owner.json"),
+    JSON.stringify({ token: "f".repeat(32), pid: process.pid, host: hostname(), verb: "records amend", by: "alice", agent: null, acquiredAt: new Date(now).toISOString(), expiresAt: new Date(now + 60_000).toISOString(), ...over }),
+  );
+  return lock;
+}
+
+describe("where the lock lives", () => {
+  test("in the working tree's git directory, the linked worktree's own for a worktree, and under tmp outside git", () => {
+    const root = repo({ "a.txt": "a\n" }, true);
+    expect(gitDirOf(root)).toBe(join(root, ".git"));
+    expect(writeLockPath(join(root))).toBe(join(root, ".git", "chant-write.lock"));
+    const wt = join(scratchDir(), "wt");
+    git(root, "worktree", "add", "-q", wt);
+    expect(writeLockPath(wt)).toBe(join(root, ".git", "worktrees", "wt", "chant-write.lock"));
+    const bare = scratchDir();
+    expect(writeLockPath(bare).startsWith(tmpdir())).toBe(true);
+    expect(writeLockPath(bare)).toMatch(/chant-write-[0-9a-f]{16}\.lock$/);
+  });
+});
+
+describe("withWriteLock", () => {
+  test("serialises two writes this process runs at once, and lets a write inside a write through", async () => {
+    const root = repo({});
+    const order: string[] = [];
+    const one = withWriteLock(root, { verb: "records amend", by: "alice" }, false, async () => {
+      order.push("one in");
+      expect(writeLockHolder(root).holder).toMatchObject({ verb: "records amend", by: "alice", pid: process.pid });
+      // Re-entrant: work evidence amends inside its own write.
+      await withWriteLock(root, { verb: "records amend" }, false, async () => void order.push("nested"));
+      await sleep(80);
+      order.push("one out");
+    });
+    await sleep(10);
+    const two = withWriteLock(root, { verb: "records amend", by: "bob" }, false, async () => void order.push("two"));
+    await Promise.all([one, two]);
+    expect(order).toEqual(["one in", "nested", "one out", "two"]);
+    expect(existsSync(writeLockPath(root))).toBe(false);
+  });
+
+  test("a dry run takes no lock", async () => {
+    const root = repo({});
+    plant(root, {});
+    expect(await withWriteLock(root, { verb: "records amend" }, true, async () => "ran")).toBe("ran");
+  });
+
+  test("a waiter is refused with write-lock-timeout naming the holder, and the lock is released after a failure", async () => {
+    const root = repo({});
+    plant(root, {});
+    process.env[WRITE_LOCK_WAIT_ENV] = "100";
+    const err = await withWriteLock(root, { verb: "records review" }, false, async () => "no").catch((e: unknown) => e);
+    expect(err).toBeInstanceOf(WriteLockError);
+    expect((err as WriteLockError).code).toBe("write-lock-timeout");
+    expect((err as WriteLockError).message).toMatch(/records amend \(alice\)/);
+    expect((err as WriteLockError).holder?.by).toBe("alice");
+
+    const other = repo({});
+    await expect(withWriteLock(other, { verb: "records new" }, false, async () => { throw new Error("boom"); })).rejects.toThrow("boom");
+    expect(existsSync(writeLockPath(other))).toBe(false);
+  });
+
+  test("breaks a lock whose process has exited, or that has expired", async () => {
+    const dead = repo({});
+    plant(dead, { pid: 2 ** 22 + 12345 });
+    expect(await withWriteLock(dead, { verb: "records amend" }, false, async () => "took it")).toBe("took it");
+    const expired = repo({});
+    plant(expired, { pid: null, verb: "batch", expiresAt: new Date(Date.now() - 1000).toISOString() });
+    expect(await withWriteLock(expired, { verb: "records amend" }, false, async () => "took it")).toBe("took it");
+    expect(writeLockHolder(expired).holder).toBeNull();
+  });
+
+  test("the sync form refuses at once while this process's own async write holds the lock", async () => {
+    const root = repo({});
+    let inner: unknown;
+    const outer = withWriteLock(root, { verb: "records amend" }, false, async () => {
+      await sleep(30);
+    });
+    await sleep(5);
+    try {
+      withWriteLockSync(root, { verb: "box listing set" }, false, () => "no");
+    } catch (e) {
+      inner = e;
+    }
+    await outer;
+    expect((inner as WriteLockError).code).toBe("write-lock-timeout");
+    expect(withWriteLockSync(root, { verb: "box listing set" }, false, () => "yes")).toBe("yes");
+  });
+});
+
+describe("a batch held across chant calls (lock acquire)", () => {
+  test("its token lets each write through while others wait, and a released token is refused", async () => {
+    const root = repo({});
+    const acquired = await workspaceLock({ cwd: root, verb: "acquire", holder: "hud:alice", ttl: "30s" });
+    lockDoc.expectValid(acquired);
+    if ("error" in acquired) throw new Error(acquired.error.message);
+    expect(acquired.holder).toMatchObject({ verb: "batch", by: "hud:alice", pid: null });
+    expect(acquired.token).toMatch(/^[0-9a-f]{32}$/);
+
+    const status = await workspaceLock({ cwd: root, verb: undefined });
+    lockDoc.expectValid(status);
+    expect(status).not.toHaveProperty("token");
+    expect(status.holder).toMatchObject({ by: "hud:alice" });
+
+    // Another writer, without the token, waits and is refused.
+    process.env[WRITE_LOCK_WAIT_ENV] = "60";
+    await expect(withWriteLock(root, { verb: "records amend" }, false, async () => "no")).rejects.toMatchObject({ code: "write-lock-timeout" });
+    // The batch's own writes go ahead.
+    process.env[WRITE_LOCK_ENV] = acquired.token!;
+    expect(await withWriteLock(root, { verb: "records amend" }, false, async () => "batch write")).toBe("batch write");
+    expect(writeLockHolder(root).holder?.verb).toBe("batch");
+
+    const released = await workspaceLock({ cwd: root, verb: "release", token: acquired.token });
+    lockDoc.expectValid(released);
+    expect(released).toMatchObject({ verb: "release", holder: null });
+    await expect(withWriteLock(root, { verb: "records amend" }, false, async () => "no")).rejects.toMatchObject({ code: "write-lock-not-held" });
+    const again = await workspaceLock({ cwd: root, verb: "release", token: acquired.token });
+    lockDoc.expectValid(again);
+    expect(again).toMatchObject({ error: { code: "write-lock-not-held" } });
+  });
+
+  test("usage is refused with write-usage-invalid", async () => {
+    const root = repo({});
+    for (const req of [{ verb: "acquire" }, { verb: "acquire", holder: "x", ttl: "1h" }, { verb: "release" }, { verb: "steal" }, { verb: undefined, token: "x" }]) {
+      const doc = await workspaceLock({ cwd: root, ...req });
+      lockDoc.expectValid(doc);
+      expect(doc).toMatchObject({ error: { code: "write-usage-invalid" } });
+    }
+  });
+});
+
+describe("the write journal", () => {
+  test("names the last chant write of a file while the file holds the text it left", () => {
+    const root = repo({});
+    noteWrites(root, [{ path: "decisions/ws-001.md", text: "one\n" }], { verb: "records amend", by: null, agent: "app-agent" });
+    const read = lastWriteReader(root);
+    expect(read("decisions/ws-001.md", "one\n")).toMatchObject({ verb: "records amend", by: null, agent: "app-agent" });
+    expect(read("decisions/ws-001.md", "edited by hand\n")).toBeNull();
+    expect(read("decisions/ws-002.md", "one\n")).toBeNull();
+    expect(JSON.parse(readFileSync(join(root, ".git", "chant-writes.json"), "utf-8")).version).toBe(1);
+  });
+
+  test("is not kept outside git", () => {
+    const bare = scratchDir();
+    noteWrites(bare, [{ path: "a.md", text: "a" }], { verb: "records new" });
+    expect(lastWriteReader(bare)("a.md", "a")).toBeNull();
+  });
+});