seisin 0.4.2 → 0.6.0

package/src/commands/init.js

@@ -11,62 +11,120 @@
  * The second is better and needs a run first. Neither writes a policy you did
  * not read: `--from-observations` lands as `.observed`, not as the config.
  */
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, relative } from "node:path";
+import { existsSync, readdirSync, readFileSync, writeFileSync, statSync, copyFileSync, appendFileSync } from "node:fs";
+import { join, relative, resolve, isAbsolute } from "node:path";
 import { CONFIG_NAME, tomlString, tomlName } from "../layout.js";
 import { read, logPath, observed, generalise } from "../log.js";
 import { C, out } from "../render.js";
+import { loadConfig } from "../config.js";
+import { applyGrant } from "../requests.js";
+import { setKey } from "../controls.js";
+import { keyName } from "../owners.js";
+import { toRepoRelative } from "../paths.js";
 
 /**
  * Three places a repo already says who does what, in order of how much it
  * actually means. None is a policy, so all of them are proposals.
  */
 export function discover(root) {
+  const keyDir = KEY_DIRS.find((d) => isDir(join(root, d))) ?? null;
   const agents = join(root, ".claude", "agents");
   if (existsSync(agents)) {
     const roles = readdirSync(agents)
       .filter((f) => f.endsWith(".md"))
       .map((f) => ({ name: f.replace(/\.md$/, ""), writes: [], keys: [] }));
-    if (roles.length) return { source: ".claude/agents/", roles };
+    if (roles.length) return { source: ".claude/agents/", roles, agents: roles.length, keyDir };
   }
 
   for (const p of ["CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS"]) {
     const file = join(root, p);
     if (!existsSync(file)) continue;
-    const paths = readFileSync(file, "utf8")
-      .split(/\r?\n/)
-      .map((l) => l.replace(/#.*$/, "").trim())
-      .filter(Boolean)
-      .map((l) => l.split(/\s+/)[0])
-      .filter((g) => g && g !== "*");
-    if (paths.length)
-      return {
-        source: p,
-        roles: [...new Set(paths)].slice(0, 8).map((g, i) => {
-          // CODEOWNERS anchors a leading "/" at the repo root; seisin's writes
-          // are already repo-relative, so a literal "/apps/**" would ask the
-          // kernel for the machine's /apps and make `explain` (which reads it as
-          // outside the repo) disagree with what the profile grants. Strip the
-          // anchor. A trailing "/" means a directory, so it becomes "/**".
-          const rel = g.replace(/^\/+/, "");
-          return {
-            name: rel.replace(/[^A-Za-z0-9]+/g, "-").replace(/^-|-$/g, "") || `role-${i + 1}`,
-            writes: [rel.endsWith("/") ? rel + "**" : rel],
-            keys: [],
-          };
-        }),
-      };
+    const roles = fromCodeowners(readFileSync(file, "utf8"));
+    if (roles.length) return { source: p, roles, agents: 0, keyDir };
   }
 
+  const dirs = codeDirs(root);
   return {
-    source: "nothing to read — this is a blank start",
-    roles: [
-      { name: "frontend", writes: ["src/web/**"], keys: [] },
-      { name: "backend", writes: ["src/api/**"], keys: [] },
-    ],
+    source: dirs.length
+      ? "the top-level folders that hold code — one role each"
+      : "nothing to read — this is a blank start",
+    roles: dirs.length
+      ? dirs.map((d) => ({ name: roleName(d), writes: [`${d}/**`], keys: [] }))
+      : [{ name: "agent", writes: [], keys: [] }],
+    agents: 0,
+    keyDir,
   };
 }
 
+/** Where a repo keeps its keys by convention, in the order they are looked for. */
+const KEY_DIRS = [".secrets", "secrets", ".keys"];
+
+/**
+ * One role per owner, with every path that owner has.
+ *
+ * It was one role per LINE, named after the path, and cut at eight — so a
+ * team's ownership came back as eight roles called `apps-web`, `apps-api`… with
+ * the rest dropped and nothing said. An owner is the thing a role stands for.
+ * A line's first owner takes it: CODEOWNERS lets several share a path, and
+ * seisin would rather print one proposal a person corrects than invent an
+ * overlap. `*` is skipped — it is the fallback owner, not a territory.
+ */
+export function fromCodeowners(text) {
+  const byOwner = new Map();
+  for (const raw of text.split(/\r?\n/)) {
+    const [glob, owner] = raw.replace(/#.*$/, "").trim().split(/\s+/);
+    if (!glob || glob === "*" || !owner) continue;
+    // CODEOWNERS anchors a leading "/" at the repo root; seisin's writes
+    // are already repo-relative, so a literal "/apps/**" would ask the
+    // kernel for the machine's /apps and make `explain` (which reads it as
+    // outside the repo) disagree with what the profile grants. Strip the
+    // anchor. A trailing "/" means a directory, so it becomes "/**".
+    const rel = glob.replace(/^\/+/, "");
+    const path = rel.endsWith("/") ? rel + "**" : rel;
+    const name = roleName(owner.replace(/^@/, "").replace(/^.*\//, "")) || `role-${byOwner.size + 1}`;
+    const role = byOwner.get(name) ?? byOwner.set(name, { name, writes: [], keys: [] }).get(name);
+    if (!role.writes.includes(path)) role.writes.push(path);
+  }
+  return [...byOwner.values()];
+}
+
+const roleName = (s) => String(s).replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+
+/**
+ * The top-level folders that hold code, for a repo that says nothing else.
+ *
+ * It proposed `src/web/**` and `src/api/**` whatever the repo looked like, so
+ * the first `check` was about folders that did not exist. Kept simple on
+ * purpose: a folder counts when some file under it (a few levels down) has a
+ * source extension. Dot-folders, dependencies and build output are skipped,
+ * and a folder of only documents or images proposes nothing — it is somebody's
+ * territory, but not the first thing a person wants to decide.
+ */
+const CODE = /\.(js|mjs|cjs|jsx|ts|tsx|py|rb|go|rs|java|kt|kts|swift|c|h|cc|cpp|hpp|cs|php|sh|sql|vue|svelte|astro|dart|scala|ex|exs|lua|pl|r|m|html|css|scss)$/i;
+const SKIP = new Set(["node_modules", "vendor", "dist", "build", "out", "target", "coverage", "__pycache__", "venv"]);
+
+function codeDirs(root) {
+  let top;
+  try { top = readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  return top
+    .filter((e) => e.isDirectory() && !e.name.startsWith(".") && !SKIP.has(e.name) && roleName(e.name))
+    .map((e) => e.name)
+    .filter((d) => holdsCode(join(root, d), 4))
+    .sort();
+}
+
+function holdsCode(dir, depth) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return false; }
+  if (entries.some((e) => e.isFile() && CODE.test(e.name))) return true;
+  if (depth <= 1) return false;
+  return entries.some((e) => e.isDirectory() && !e.name.startsWith(".") && !SKIP.has(e.name) && holdsCode(join(dir, e.name), depth - 1));
+}
+
+function isDir(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
 /** The proposed config, as TOML. Pure: takes what `discover` found. */
 export function renderConfig(found) {
   const lines = [
@@ -75,9 +133,17 @@ export function renderConfig(found) {
     `# Proposed from: ${found.source}`,
     "# Nothing here is enforced until you run the agent through `seisin run`.",
     "# Anything not listed is denied. There is no permissive default.",
+    "#",
+    "# Each role runs as its own process:  seisin run <role> -- <agent>",
+    "# A Claude Code subagent runs inside its parent's process, so it has its",
+    "# parent's role — give it its own by running it as its own `seisin run`.",
+    "",
+    "# [runtime]",
+    '# read = "territory"   # opt-in: keep data roots shut; roles declare reads/toolchain/verify',
     "",
-    "# [keys]",
-    '# dir = ".secrets"      # every key lives here; roles name the files they may read',
+    ...(found.keyDir
+      ? ["[keys]", `dir = ${tomlString(found.keyDir)}      # every key lives here; roles name the files they may read`]
+      : ["# [keys]", '# dir = ".secrets"      # every key lives here; roles name the files they may read']),
     "",
     "[network]",
     "# The agent's own API comes first. Leave it out and the agent cannot even",
@@ -95,88 +161,117 @@ export function renderConfig(found) {
     "",
   ];
   for (const r of found.roles) {
+    if (!r.writes.length) lines.push("# writes nothing yet: add the folders this role owns, e.g. \"app/**\"");
     lines.push(`[roles.${tomlName(r.name)}]`);
     lines.push(`writes = [${r.writes.map(tomlString).join(", ")}]`);
     lines.push(`keys   = [${r.keys.map(tomlString).join(", ")}]`);
+    lines.push('# reads = ["path/**"]       # data outside the repo this role must read');
+    lines.push('# toolchain = ["~/.venvs/app"] # stack under a home or another data root');
+    lines.push('# verify = ["npm", "test"]  # seisin check --verify runs this inside the role');
     lines.push("");
   }
   return lines.join("\n");
 }
 
-/** The observed config, as TOML. Pure: takes the log entries. */
-export function renderObserved(config, entries) {
+/** A proposal that adds observed permissions to the current policy text. */
+export function renderObserved(config, entries, text = readFileSync(config.path, "utf8")) {
+  // Start from the policy being proposed for promotion. Rebuilding writes and
+  // keys alone discarded isolate, never_writes, providers, per-role network,
+  // MCP and every other setting, including those of roles that did not act.
+  config = loadConfig(config.path, text);
   const roles = observed(entries);
-  const lines = [
-    `# ${CONFIG_NAME} — written from ${entries.length} observed action(s).`,
-    "#",
-    "# This is what your agents actually did, generalised to directories. Read it",
-    "# before you trust it: an agent that touched a file once by mistake asked for",
-    "# that directory here, and observation cannot tell intent from accident.",
-    "",
-  ];
-  if (config.keyDirs.length)
-    lines.push("[keys]", `dir = [${config.keyDirs.map(tomlString).join(", ")}]`, "");
-  lines.push("[network]", `allow = [${config.allowedDomains.map(tomlString).join(", ")}]`, "");
-
-  /**
-   * Every declared role appears, whether it acted or not.
-   *
-   * This used to emit only the roles the log had seen, and the file says "diff
-   * it, then move it" — so moving it deleted the territory of every role that
-   * happened to be idle during the observation window, silently. A role that
-   * did nothing is not a role that needs nothing; it is a role nobody watched.
-   *
-   * So observation *adds*. What was declared stays, what was seen is appended,
-   * and the comment beside each role says which part came from where — because
-   * the whole reason to read this file is to tell the two apart.
-   */
-  for (const name of new Set([...Object.keys(config.roles), ...roles.keys()])) {
-    const declared = config.roles[name];
+  let toml = text;
+  const notes = [];
+  for (const name of Object.keys(config.roles)) {
     const seen = roles.get(name);
-
-    const from = declared ? declared.writesDeclared ?? declared.writes : [];
-    const found = seen ? generalise([...seen.writes]).filter((w) => !from.includes(w)) : [];
-    const keys = [
-      ...(declared ? declared.keys : []),
-      ...(seen ? [...new Set([...seen.keys].map((k) => k.replace(/^.*\//, "")))] : []),
+    if (!seen) {
+      notes.push(`# ${name}: this role did nothing while observing — kept as written`);
+      continue;
+    }
+    // A host path is not a repo-relative grant. Unknown roles and outside
+    // paths from older logs cannot silently become territory in the proposal.
+    const paths = [...seen.writes].map((p) => toRepoRelative(config, resolve(config.root, p)))
+      .filter((p) => !isAbsolute(p) && p !== ".." && !p.startsWith("../"));
+    const additions = [
+      ...generalise(paths).map((grant) => ({ action: "write", grant })),
+      ...[...seen.keys].map((target) => ({ action: "read", grant: keyName(config, target) })),
     ];
-
-    // Every value below came out of the log, and the log records paths the
-    // agent chose. tomlString refuses what the format cannot hold rather than
-    // emitting a file that parses into something else.
-    lines.push(`[roles.${tomlName(name)}]`);
-    lines.push(`writes = [${[...from, ...found].map(tomlString).join(", ")}]`);
-    lines.push(`keys   = [${[...new Set(keys)].map(tomlString).join(", ")}]`);
-    lines.push(
-      seen
-        ? `# declared ${from.length}; observation added ${found.length} ` +
-          `(${seen.writes.size} path(s) written, ${seen.keys.size} key(s) read)`
-        : `# declared ${from.length}; this role did nothing while observing — kept as written`
-    );
-    lines.push("");
+    let added = 0;
+    for (const request of additions) {
+      const field = request.action === "read" ? "keys" : "writes";
+      // A valid role can omit either list. Insert only a missing list and
+      // retry the same grant; existing values and comments stay untouched.
+      let result;
+      try {
+        result = applyGrant(toml, { ...request, role: name, times: 1 }, "observation proposal");
+      } catch (e) {
+        if (!e.message.includes(`has no ${field} list`)) throw e;
+        toml = setKey(toml, `roles.${name}`, field, "[]", "", "from observation");
+        result = applyGrant(toml, { ...request, role: name, times: 1 }, "observation proposal");
+      }
+      toml = result.toml;
+      if (result.changed) added++;
+    }
+    notes.push(`# ${name}: observation added ${added}; all other settings kept as written`);
   }
-  return { toml: lines.join("\n"), roles: roles.size };
+  loadConfig(config.path, toml);
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const heading = [
+    `# ${CONFIG_NAME} — proposal from ${entries.length} observed action(s).`,
+    "# Observation adds territory and keys; read the diff before promoting this file.",
+    ...notes, "",
+  ].join(eol);
+  return { toml: heading + eol + toml, roles: [...roles.keys()].filter((name) => config.roles[name]).length };
 }
 
-export function init(cwd = process.cwd()) {
+export function init(cwd = process.cwd(), { force = false } = {}) {
   const target = join(cwd, CONFIG_NAME);
-  if (existsSync(target))
-    throw new Error(`${CONFIG_NAME} already exists here. Delete it first if you meant to start over.`);
+  const had = existsSync(target);
+  if (had && !force)
+    throw new Error(`${CONFIG_NAME} already exists here. seisin init --force replaces it, keeping the old one as ${CONFIG_NAME}.bak`);
 
   const found = discover(cwd);
+  if (had) copyFileSync(target, target + ".bak");
   writeFileSync(target, renderConfig(found));
+  const ignored = ignoreState(cwd);
   out(
     `\n  wrote ${C.b}${CONFIG_NAME}${C.off} with ${found.roles.length} role(s) from ${found.source}\n` +
-    `  ${C.dim}These are a proposal, not a policy. Read them before you run anything.${C.off}\n\n` +
-    `  next:  seisin check\n\n`
+    (had ? `  ${C.dim}the previous one is ${CONFIG_NAME}.bak${C.off}\n` : "") +
+    (found.keyDir ? `  ${C.dim}[keys] dir = "${found.keyDir}" — it is there, so it is declared${C.off}\n` : "") +
+    (ignored ? `  ${C.dim}added .seisin/ to .gitignore — the log and the request queue belong to this machine${C.off}\n` : "") +
+    `  ${C.dim}These are a proposal, not a policy. Read them before you run anything.${C.off}\n` +
+    // Said once, here, where someone with one agent decides whether to go on.
+    (found.agents <= 1
+      ? `  ${C.dim}one agent? its own sandbox covers most of this. seisin adds a built environment, a key dir no role reads\n` +
+        `  unless it is declared, and an owner named on every denial — it earns its setup at two roles.${C.off}\n`
+      : "") +
+    `\n  next:  seisin check\n\n`
   );
   return found;
 }
 
+/**
+ * `.seisin/` into the repo's .gitignore, when it has one and it is not there.
+ * The state directory is this machine's record; committed, every clone would
+ * start with somebody else's log and queue. No .gitignore, nothing written.
+ */
+function ignoreState(cwd) {
+  const file = join(cwd, ".gitignore");
+  if (!existsSync(file)) return false;
+  const text = readFileSync(file, "utf8");
+  if (/^\/?\.seisin\/?\s*$/m.test(text)) return false;
+  appendFileSync(file, `${text.endsWith("\n") || !text ? "" : "\n"}.seisin/\n`);
+  return true;
+}
+
 export function initFromObservations(config) {
   const entries = read(logPath(config.root), { verdict: "observed" });
   if (entries.length === 0)
-    throw new Error("nothing observed yet. Run: seisin run <role> --observe -- <command>");
+    throw new Error(
+      "nothing observed yet.\n" +
+      "  observations come from the hook: run `seisin wire` once, then observe an agent —\n" +
+      "    seisin run <role> --observe -- claude      (or codex, …)\n" +
+      "  a plain shell command goes through no hook and records nothing. keys stay denied while observing.");
 
   const { toml, roles } = renderObserved(config, entries);
   const file = join(config.root, CONFIG_NAME + ".observed");

package/src/commands/log.js

@@ -18,15 +18,30 @@ const flag = (argv, name) => {
   return i === -1 ? undefined : argv[i + 1];
 };
 
+const VERDICTS = ["allowed", "denied", "observed"];
+
 export function log(config, argv = []) {
   if (argv[0] === "verify") return verify(config);
-  const entries = read(logPath(config.root), {
-    role: flag(argv, "--role"),
-    verdict: flag(argv, "--verdict"),
-    limit: Number(flag(argv, "--limit") ?? 40),
-  });
+  const role = flag(argv, "--role");
+  const verdict = flag(argv, "--verdict");
+  const limit = flag(argv, "--limit") ?? "40";
+  // Checked, because a filter that matches nothing reads as an empty log.
+  if (verdict !== undefined && !VERDICTS.includes(verdict))
+    throw new Error(`unknown verdict "${verdict}" — use allowed, denied or observed`);
+  if (!/^[1-9]\d*$/.test(limit)) throw new Error(`--limit takes a positive number, got "${limit}"`);
+  // A role that is not in the policy is still a fair question: the log keeps
+  // the lines of a role that was renamed or removed. The empty answer says so.
+  const entries = read(logPath(config.root), { role, verdict, limit: Number(limit) });
 
   if (entries.length === 0) {
+    // Say which: nothing at all, or nothing for this filter.
+    const any = role || verdict ? read(logPath(config.root), { limit: 1000 }) : [];
+    if (any.length) {
+      const others = [...new Set(any.map((e) => e.role).filter(Boolean))];
+      out(`\n  ${C.dim}no entries for ${[role && `role ${role}`, verdict && `verdict ${verdict}`].filter(Boolean).join(", ")} — ` +
+        `the log has ${any.length === 1000 ? "1000+" : any.length} for ${others.join(", ") || "other filters"}${C.off}\n\n`);
+      return entries;
+    }
     out(`\n  ${C.dim}nothing recorded yet — run an agent through "seisin run"${C.off}\n\n`);
     return entries;
   }
@@ -56,14 +71,38 @@ function verify(config) {
   const dropped = r.dropped
     ? `  ${C.yellow}${r.dropped} entr${r.dropped === 1 ? "y was" : "ies were"} never written${C.off}  another writer held the lock too long; see ${LOG_NAME}.dropped\n`
     : "";
+  // Where the chain starts is only checked once it has been recorded. Until
+  // then a log whose chain was stripped or rewritten whole reads like an
+  // intact one — so with chained lines and no record this is a warning, not a
+  // footnote. A record made after chained lines already stood pins whatever
+  // they said by then, and says so.
+  let genesis = "";
+  if (r.genesis === "unrecorded" && r.chained)
+    genesis = `  ${C.yellow}where the chain starts is not recorded${C.off} — a chain stripped or rewritten from its first line would not show here.\n` +
+      `  ${C.dim}the next entry records it, marked late: tampering before that cannot be excluded${C.off}\n`;
+  else if (r.genesis === "unrecorded" && r.unchained)
+    genesis = `  ${C.dim}where the chain starts is not recorded yet — it will be on the next entry${C.off}\n`;
+  else if (r.genesis === "pruned")
+    genesis = `  ${C.dim}the oldest segments were rotated away; the chain is checked from the oldest one kept${C.off}\n`;
+  else if (r.late)
+    genesis = `  ${C.yellow}start recorded late${C.off}${r.late.at ? ` (${r.late.at})` : ""}, after ${r.late.after ?? "some"} chained line(s) — earlier tampering cannot be excluded\n`;
   if (!r.breaks.length) {
-    out(`\n  ${C.green}intact${C.off}  ${head}${r.chained} chained line(s)${segs}\n${dropped}\n`);
+    out(`\n  ${C.green}intact${C.off}  ${head}${r.chained} chained line(s)${segs}\n${genesis}${dropped}\n`);
     return r;
   }
   out(`\n  ${C.red}broken${C.off}  ${head}${r.chained} chained line(s), ${r.breaks.length} break(s):\n`);
-  for (const b of r.breaks.slice(0, 10))
-    out(`    line ${b.line}: expected prev ${b.expected}, found ${b.found ?? "none"}\n`);
-  out(`  ${C.dim}a line was edited, removed or reordered just before each of these${C.off}\n${dropped}\n`);
+  const foreign = r.breaks.find((b) => b.foreign);
+  for (const b of r.breaks.slice(0, 10)) {
+    if (b.foreign) out(`    the genesis record belongs to another log: it pins a different start (${LOG_NAME}.genesis)\n`);
+    else out(`    line ${b.line}: expected prev ${b.expected}, found ${b.found ?? "none"}\n`);
+  }
+  if (foreign)
+    out(`  ${C.dim}if ${LOG_NAME} was archived or replaced by hand, move ${LOG_NAME}.genesis along with the archived log;\n` +
+      `  or remove it, and the next entry records this log's start (marked late). If nobody replaced the log,\n` +
+      `  it was rewritten from its first line.${C.off}\n`);
+  if (r.breaks.some((b) => !b.foreign))
+    out(`  ${C.dim}a line was edited, removed or reordered just before each of these${C.off}\n`);
+  out(`${genesis}${dropped}\n`);
   process.exitCode = 1;
   return r;
 }