catherd-cli 0.2.0 → 1.0.0

package/src/services/profile-service.ts

@@ -0,0 +1,292 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { CatherdError } from "../domain/errors.ts";
+import { parseRung } from "../domain/ids.ts";
+import {
+  agentName,
+  applyPatch,
+  assertProfileName,
+  type Change,
+  defaultProfileDoc,
+  diffProfiles,
+  type Profile,
+  type ProfileDoc,
+  type ProfilePatch,
+  resolveProfile,
+} from "../domain/profile.ts";
+import { type Validation, validateProfile } from "../domain/profile-rules.ts";
+import { ROLES } from "../domain/roles.ts";
+import { withFileLockSync } from "../infra/filelock.ts";
+import { configDir } from "../infra/paths.ts";
+import { ensurePrivateDir, writeJsonAtomic, writeTextAtomic } from "../infra/store.ts";
+import { apply, plan, type Synced } from "./agent-links.ts";
+import { loadCatalog } from "./catalog-service.ts";
+import type { ProfilePort, ProfileSaved, ProfileView } from "./ports.ts";
+import {
+  activeName,
+  configFile,
+  getProfile,
+  listProfiles,
+  profileExists,
+  profileFile,
+  profileFor,
+  projectsFile,
+  readConfig,
+  readProfileDoc,
+  readProjects,
+  requireProfile,
+  roleEnforcement,
+  runnableBackends,
+  validateNamed,
+} from "./profile-store.ts";
+
+// Spec §7.3, the single writer: one lock over profiles, config.json, projects.json, agent files and links.
+// Reads live in profile-store.ts, the agent files and links in agent-links.ts.
+
+/** The profiles lock every writer here takes; `init` moves 0.x files aside under it too. */
+export const withProfilesLock = <T>(fn: () => T): T => {
+  ensurePrivateDir(configDir());
+  return withFileLockSync(join(configDir(), "profiles"), fn);
+};
+const locked = withProfilesLock;
+
+const writeDoc = (name: string, doc: ProfileDoc) => writeJsonAtomic(profileFile(name), { ...doc, name });
+
+/** Writes `doc` as profile `name` and relinks; when the relink refuses, puts the profile back as it was. */
+function saveAndLink(name: string, doc: ProfileDoc): Synced {
+  const before = existsSync(profileFile(name)) ? readFileSync(profileFile(name), "utf8") : null;
+  writeDoc(name, doc);
+  try {
+    return apply(plan([name]));
+  } catch (e) {
+    if (before === null) rmSync(profileFile(name), { force: true });
+    else writeTextAtomic(profileFile(name), before);
+    throw e;
+  }
+}
+
+const validate = (doc: ProfileDoc, name: string): Validation =>
+  validateProfile(resolveProfile(doc, name), loadCatalog({ timings: false }), runnableBackends(), doc);
+
+/** What a save returns: the port's ProfileSaved (one type for the CLI, the TUI and the MCP tools). */
+export type Saved = ProfileSaved;
+
+const unsaved = (v: Validation): Saved => ({
+  saved: false,
+  ...v,
+  diff: [],
+  linked: [],
+  pruned: [],
+  newSessionNeededFor: [],
+});
+
+/** The issue path of a save refused because the profile is no longer the one its caller was shown. */
+export const CHANGED_ON_DISK = "profile";
+
+/**
+ * Spec §7.3 `patch` (profile_set, `catherd profile set`): validates first and writes nothing when invalid.
+ * A profile that does not exist yet starts from the default profile. With `expect` (the profile as a
+ * preview read it), it writes nothing when the profile under the lock is no longer that one: the patch
+ * would land on values the preview never showed.
+ */
+export function patchProfile(
+  name: string | undefined,
+  patch: ProfilePatch,
+  opts: { expect?: ProfileDoc } = {},
+): Saved {
+  return locked(() => {
+    const n = assertProfileName(name ?? activeName());
+    const before = profileExists(n) ? readProfileDoc(n) : defaultProfileDoc(n);
+    if (opts.expect !== undefined && !isDeepStrictEqual(before, opts.expect))
+      return unsaved({
+        errors: [
+          {
+            path: CHANGED_ON_DISK,
+            message: `profile "${n}" changed on disk since it was shown`,
+            fix: "check the changes and save again",
+          },
+        ],
+        warnings: [],
+      });
+    const after = applyPatch(before, patch);
+    const resolved = resolveProfile(after, n);
+    const v = validate(after, n);
+    if (v.errors.length) return unsaved(v);
+    const diff = diffProfiles(resolveProfile(before, n), resolved);
+    return { saved: true, ...v, diff, ...saveAndLink(n, after) };
+  });
+}
+
+/** Spec §7.3 `create` and `copy`: a new profile from `from` (default: the default profile). */
+export function createProfile(name: string, from?: string): Saved {
+  return locked(() => {
+    // `default` exists without a file: resetProfile is the only way to write it
+    if (profileExists(assertProfileName(name)))
+      throw new CatherdError("E_INPUT_INVALID", `profile "${name}" already exists`, {
+        fix: `pick another name, or edit it with catherd profile set --profile ${name}`,
+      });
+    if (from !== undefined && !profileExists(assertProfileName(from)))
+      throw new CatherdError("E_INPUT_INVALID", `no profile named "${from}" to copy`, {
+        fix: "catherd profile list",
+      });
+    const doc = from === undefined ? defaultProfileDoc(name) : readProfileDoc(from);
+    const v = validate(doc, name);
+    if (v.errors.length) return unsaved(v);
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+  });
+}
+
+/** Writes the default profile under `name`, replacing what is there (`catherd init` when asked to). */
+export function resetProfile(name: string): Saved {
+  return locked(() => {
+    assertProfileName(name);
+    const doc = defaultProfileDoc(name);
+    const v = validate(doc, name);
+    if (v.errors.length) return unsaved(v);
+    return { saved: true, ...v, diff: [], ...saveAndLink(name, doc) };
+  });
+}
+
+/**
+ * Spec §7.3 `delete`: never the active profile or a repo-bound one; its agent files go with it. A binding
+ * whose repo no longer exists does not count: it is pruned with the profile.
+ */
+export function deleteProfile(name: string): Synced {
+  return locked(() => {
+    assertProfileName(name);
+    if (!existsSync(profileFile(name)))
+      throw new CatherdError("E_INPUT_INVALID", `profile "${name}" has no file to delete`, {
+        fix: "catherd profile list",
+      });
+    if (name === activeName())
+      throw new CatherdError("E_INPUT_INVALID", `"${name}" is the active profile`, {
+        fix: "make another profile active first: catherd profile use <name>",
+      });
+    const projects = readProjects();
+    const mine = Object.keys(projects.bindings).filter((repo) => projects.bindings[repo] === name);
+    const bound = mine.filter((repo) => existsSync(repo));
+    if (bound.length)
+      throw new CatherdError("E_INPUT_INVALID", `"${name}" is bound to ${bound.join(", ")}`, {
+        fix: "run catherd profile use --repo --clear (or use <name> --repo) inside each of those repos",
+      });
+    const text = readFileSync(profileFile(name), "utf8");
+    rmSync(profileFile(name), { force: true });
+    const gone = new Set(mine);
+    if (gone.size)
+      writeJsonAtomic(projectsFile(), {
+        ...projects,
+        bindings: Object.fromEntries(Object.entries(projects.bindings).filter(([r]) => !gone.has(r))),
+      });
+    try {
+      return apply(plan(), [name]);
+    } catch (e) {
+      writeTextAtomic(profileFile(name), text);
+      if (gone.size) writeJsonAtomic(projectsFile(), projects);
+      throw e;
+    }
+  });
+}
+
+/** Spec §7.3 `activate(name, repo?)`: the active profile, or the one bound to a repo; relinks the agents. */
+export function activate(
+  name: string,
+  repo: string | null = null,
+): Synced & { active: string; repo: string | null } {
+  return locked(() => {
+    assertProfileName(name);
+    if (!profileExists(name))
+      throw new CatherdError("E_INPUT_INVALID", `no profile named "${name}"`, {
+        fix: "catherd profile list",
+      });
+    const config = readConfig();
+    const projects = readProjects();
+    const write = () =>
+      repo === null
+        ? writeJsonAtomic(configFile(), { ...config, schema: 1, activeProfile: name })
+        : writeJsonAtomic(projectsFile(), {
+            ...projects,
+            schema: 1,
+            bindings: { ...projects.bindings, [repo]: name },
+          });
+    write();
+    try {
+      return { active: name, repo, ...apply(plan([name])) };
+    } catch (e) {
+      if (repo === null) writeJsonAtomic(configFile(), config);
+      else writeJsonAtomic(projectsFile(), projects);
+      throw e;
+    }
+  });
+}
+
+/** `catherd profile use --repo --clear`: removes `repo`'s binding, so it runs on the active profile again. */
+export function unbind(repo: string): Synced & { repo: string; was: string } {
+  return locked(() => {
+    const projects = readProjects();
+    const was = projects.bindings[repo];
+    if (was === undefined)
+      throw new CatherdError("E_INPUT_INVALID", `${repo} is bound to no profile`, {
+        fix: "catherd profile list shows the bound repos",
+      });
+    const bindings = { ...projects.bindings };
+    delete bindings[repo];
+    writeJsonAtomic(projectsFile(), { ...projects, schema: 1, bindings });
+    try {
+      return { repo, was, ...apply(plan()) };
+    } catch (e) {
+      writeJsonAtomic(projectsFile(), projects);
+      throw e;
+    }
+  });
+}
+
+export function diffNamed(a: string, b: string): Change[] {
+  return diffProfiles(getProfile(a), getProfile(b));
+}
+
+function viewOf(p: Profile): ProfileView {
+  const roles: ProfileView["roles"] = {};
+  for (const role of ROLES) roles[role] = { ...p.roles[role], rungs: [...p.roles[role].rungs] };
+  return {
+    name: p.name,
+    objective: p.objective,
+    roles,
+    billing: p.billing,
+    jev: p.jev,
+    isolated: Object.fromEntries(Object.entries(p.harness).map(([k, h]) => [k, h.isolated])),
+    failover: p.failover,
+    budget: p.budget,
+    timeouts: p.timeouts,
+    preflight: p.preflight,
+    heavy: p.lock.heavy,
+    notify: p.notify,
+  };
+}
+
+/** The ProfilePort the run engine and the MCP tools use (spec §7.3: the single writer). */
+export function profileService(): ProfilePort {
+  // without a name, each tool acts on the profile `repo` runs on (the active one outside a repo)
+  return {
+    forRepo: (repo) => viewOf(profileFor(repo)),
+    get(name, repo = null) {
+      const here = activeName(repo);
+      const p = getProfile(name === undefined ? here : requireProfile(name));
+      return {
+        active: activeName(),
+        here,
+        profiles: listProfiles(),
+        profile: viewOf(p),
+        enforcement: roleEnforcement(p),
+      };
+    },
+    validate(name, repo = null) {
+      const v = validateNamed(name === undefined ? activeName(repo) : requireProfile(name), repo);
+      return { valid: v.errors.length === 0, ...v };
+    },
+    // a name that does not exist yet starts from the default profile
+    set: (name, patch, repo = null) => patchProfile(name ?? activeName(repo), patch),
+    agentFor: (repo, role, rung) =>
+      parseRung(rung).backend === "claude" ? agentName(activeName(repo), role, rung) : null,
+  };
+}

package/src/services/profile-store.ts

@@ -0,0 +1,141 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { adapterFor } from "../adapters/registry.ts";
+import "../adapters/all.ts";
+import { CatherdError, UPGRADE } from "../domain/errors.ts";
+import { ADAPTER_IDS, tryParseRung } from "../domain/ids.ts";
+import {
+  assertProfileName,
+  defaultProfileDoc,
+  PROFILE_NAME,
+  type Profile,
+  type ProfileDoc,
+  ProfileDocSchema,
+  resolveProfile,
+} from "../domain/profile.ts";
+import { type Validation, validateProfile } from "../domain/profile-rules.ts";
+import type { Access } from "../domain/record.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import { configDir } from "../infra/paths.ts";
+import { readJsonFile } from "../infra/store.ts";
+import { backendOfKey, loadCatalog } from "./catalog-service.ts";
+
+// Spec §7.3, the read side of the profile service: where profiles, config.json and projects.json live,
+// and reading them. Every write goes through profile-service.ts.
+
+export const profilesDir = (): string => join(configDir(), "profiles");
+export const configFile = (): string => join(configDir(), "config.json");
+export const projectsFile = (): string => join(configDir(), "projects.json");
+/** `<config>/agents/<profile>/<agent>.md`: catherd's own agent files, which the links point at. */
+export const agentsRoot = (): string => join(configDir(), "agents");
+export const profileFile = (name: string): string => join(profilesDir(), `${name}.json`);
+
+const ConfigSchema = z.looseObject({ schema: z.literal(1), activeProfile: z.string().optional() });
+const ProjectsSchema = z.looseObject({
+  schema: z.literal(1),
+  bindings: z.record(z.string(), z.string()).default({}),
+});
+export type Config = z.infer<typeof ConfigSchema>;
+export type Projects = z.infer<typeof ProjectsSchema>;
+
+/**
+ * Reads a schema-1 file. A file without `schema` was written by catherd 0.x, which 1.0 does not read
+ * (spec D2): `catherd init` moves those aside.
+ */
+function readV1<T>(file: string, schema: z.ZodType<T>): T {
+  const raw = readJsonFile(file);
+  const found = (raw as { schema?: unknown } | null)?.schema;
+  if (found === undefined)
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is from catherd 0.x`, {
+      fix: "run catherd init, which moves 0.x files aside and writes 1.0 ones",
+    });
+  if (typeof found === "number" && found > 1)
+    throw new CatherdError(
+      "E_CONFIG_NEWER_SCHEMA",
+      `${file} has schema ${found}, newer than this catherd (1)`,
+      {
+        fix: `upgrade catherd: ${UPGRADE}`,
+      },
+    );
+  const r = schema.safeParse(raw);
+  if (!r.success)
+    throw new CatherdError("E_CONFIG_INVALID", `${file} is invalid:\n${z.prettifyError(r.error)}`, {
+      fix: `fix it with catherd profile set, or delete ${file}`,
+    });
+  return r.data;
+}
+
+export const readConfig = (): Config =>
+  existsSync(configFile()) ? readV1(configFile(), ConfigSchema) : { schema: 1 };
+export const readProjects = (): Projects =>
+  existsSync(projectsFile()) ? readV1(projectsFile(), ProjectsSchema) : { schema: 1, bindings: {} };
+
+/** Every profile name: the files in `profiles/`, and `default`, which exists even before its file does. */
+export function listProfiles(): string[] {
+  const onDisk = existsSync(profilesDir())
+    ? readdirSync(profilesDir())
+        .filter((f) => f.endsWith(".json"))
+        .map((f) => f.slice(0, -".json".length))
+        .filter((n) => PROFILE_NAME.test(n))
+    : [];
+  return [...new Set(["default", ...onDisk])].sort();
+}
+
+export const profileExists = (name: string): boolean => listProfiles().includes(name);
+
+/** The stored document; `default` without a file is the built-in default profile. */
+export function readProfileDoc(name: string): ProfileDoc {
+  assertProfileName(name);
+  if (existsSync(profileFile(name))) return readV1(profileFile(name), ProfileDocSchema);
+  if (name === "default") return defaultProfileDoc();
+  throw new CatherdError("E_CONFIG_INVALID", `no profile named "${name}"`, { fix: "catherd profile list" });
+}
+
+export const getProfile = (name: string): Profile => resolveProfile(readProfileDoc(name), name);
+
+/** A profile name the user typed: refused as bad input (exit 2) when no such profile exists. */
+export function requireProfile(name: string): string {
+  if (!profileExists(assertProfileName(name)))
+    throw new CatherdError("E_INPUT_INVALID", `no profile named "${name}"`, { fix: "catherd profile list" });
+  return name;
+}
+
+/** The profile bound to `repo` (a git toplevel), else the active one, else `default`. */
+export function activeName(repo: string | null = null): string {
+  const bound = repo === null ? undefined : readProjects().bindings[repo];
+  return bound ?? readConfig().activeProfile ?? "default";
+}
+
+export const profileFor = (repo: string | null): Profile => getProfile(activeName(repo));
+
+/** The backends catherd can run: every registered adapter, and the native `claude` path. */
+export const runnableBackends = (): string[] => ["claude", ...ADAPTER_IDS.filter((id) => adapterFor(id))];
+
+/** Whether a profile's billing or harness key belongs to one of `backends` (default: runnableBackends()). */
+export const keyRunnable = (key: string, backends: string[] = runnableBackends()): boolean =>
+  backends.includes(backendOfKey(key));
+
+/** `repo`: the git toplevel whose listing route reads (opencode lists its models per repository). */
+export function validateNamed(name?: string, repo: string | null = null): Validation {
+  const n = name ?? activeName(repo);
+  const doc = readProfileDoc(n);
+  const catalog = loadCatalog({ timings: false, ...(repo === null ? {} : { repo }) });
+  return validateProfile(resolveProfile(doc, n), catalog, runnableBackends(), doc);
+}
+
+/** Spec D10: how strongly the backend holds a role to its access mode. */
+export function enforcementOf(rung: string, access: Access): "enforced" | "advisory" {
+  const r = tryParseRung(rung);
+  return (r && adapterFor(r.backend)?.enforcement[access]) ?? "advisory";
+}
+
+/** Each role's weakest enforcement over its rungs, for `profile show` and profile_get. */
+export function roleEnforcement(p: Profile): Record<Role, "enforced" | "advisory"> {
+  const out = {} as Record<Role, "enforced" | "advisory">;
+  for (const role of ROLES) {
+    const rc = p.roles[role];
+    out[role] = rc.rungs.every((r) => enforcementOf(r, rc.access) === "enforced") ? "enforced" : "advisory";
+  }
+  return out;
+}

package/src/services/reconcile.ts

@@ -0,0 +1,101 @@
+import { readFileSync, statSync } from "node:fs";
+import { errorMessage } from "../domain/errors.ts";
+import { dispatchPaths } from "../infra/dispatch-dir.ts";
+import { log } from "../infra/log.ts";
+import { writeJsonAtomic } from "../infra/store.ts";
+import { type Dispatch, listDispatches, pendingDispatches } from "./dispatches.ts";
+import { finalizeDispatch, waitForFinish } from "./finalize.ts";
+import type { Deps } from "./ports.ts";
+import { listRuns, type Run } from "./run-store.ts";
+import { refreshState } from "./state.ts";
+
+/**
+ * Builds before the spec.json fix (plan-2 review I1) wrote every env value of the MCP server into
+ * spec.json, readable by others. A spec is read once, when its supervisor starts, so such a file loses
+ * its env and becomes 0600. Returns how many it scrubbed.
+ */
+function scrubOldSpecs(run: Run): number {
+  let n = 0;
+  for (const d of listDispatches(run)) {
+    const file = dispatchPaths(d.dir).spec;
+    try {
+      if ((statSync(file).mode & 0o077) === 0) continue;
+      const doc = JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+      writeJsonAtomic(file, { ...doc, env: {} }, { mode: 0o600 });
+      n++;
+    } catch {
+      // no spec.json, or one that cannot be read: nothing to scrub
+    }
+  }
+  return n;
+}
+
+export interface ReconcileReport {
+  finalized: string[];
+  watching: string[];
+  warnings: string[];
+  /** settles once every watched dispatch is finalized */
+  done: Promise<void>;
+}
+
+/**
+ * Waits for a live dispatch this process did not start, then finalizes it. A state.md refresh that
+ * fails rejects, after the record is written, with a message that says so.
+ */
+async function watchAndFinalize(deps: Deps, run: Run, d: Dispatch): Promise<void> {
+  await waitForFinish(d, { pollMs: deps.pollMs, tickMs: Number.POSITIVE_INFINITY, now: deps.now });
+  await finalizeDispatch(run, d);
+  const { hints } = await refreshState(run);
+  if (hints[0]) throw new Error(hints[0]);
+}
+
+/**
+ * Spec §4.7: on server start, finalize each finished dispatch that has no record, and watch each live
+ * one until it finishes. A run that cannot be read is skipped with a warning; it never stops the server.
+ */
+export async function reconcileAll(deps: Deps): Promise<ReconcileReport> {
+  const { runs, corrupt } = listRuns();
+  const report: Omit<ReconcileReport, "done"> = {
+    finalized: [],
+    watching: [],
+    warnings: corrupt.map((c) => `skipped run ${c.id}: ${c.reason}`),
+  };
+  const watchers: Promise<void>[] = [];
+  const warn = (run: Run, e: unknown): void => {
+    const w = `${run.id}: ${errorMessage(e)}`;
+    if (!report.warnings.includes(w)) report.warnings.push(w);
+  };
+  for (const run of runs) {
+    let pending;
+    try {
+      const scrubbed = scrubOldSpecs(run);
+      if (scrubbed) log("warn", "reconcile", { run: run.id, scrubbedSpecs: scrubbed });
+      pending = pendingDispatches(run, deps.now());
+    } catch (e) {
+      warn(run, e);
+      continue;
+    }
+    for (const d of pending) {
+      if (d.state !== "finished") {
+        report.watching.push(d.admit.dispatchId);
+        watchers.push(watchAndFinalize(deps, run, d).catch((e: unknown) => warn(run, e)));
+        continue;
+      }
+      try {
+        await finalizeDispatch(run, d);
+      } catch (e) {
+        warn(run, e);
+        continue;
+      }
+      report.finalized.push(d.admit.dispatchId);
+      for (const h of (await refreshState(run)).hints) warn(run, h);
+    }
+  }
+  log("info", "reconcile", {
+    runs: runs.length,
+    finalized: report.finalized.length,
+    watching: report.watching.length,
+    warnings: report.warnings,
+  });
+  return { ...report, done: Promise.all(watchers).then(() => undefined) };
+}