syndai 0.1.1 → 0.4.0

package/src/schedules.js

@@ -0,0 +1,377 @@
+// `syndai schedule` (a project's recurring runs) and `syndai repeat` (repeat a run you liked).
+//
+// The server owns cron: it labels a cadence (`cadence_label`) and lists the next fires
+// (`upcoming`), so nothing here parses cron. The only mapping is the presets the portal's
+// Repeats field offers (apps/portal-v2/src/lib/cadence.ts `toCron`), with Sunday = 0.
+// Merge and skip policy are edited in the portal or with `syndai api updateSchedule`.
+
+import { ApiError, CliError, EXIT } from "./errors.js";
+import { projectLabel, resolveProject } from "./projects.js";
+import { ask, ulid } from "./ui.js";
+
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
+const MAX_PAGES = 50;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const PAUSE_REASONS = {
+  consecutive_failures: "it failed 5 times in a row",
+  invalid_trigger: "its schedule is no longer valid",
+};
+const CADENCE_HELP = 'hourly --at :MM, daily|weekdays --at HH:MM, weekly --at "mon HH:MM", or a 5-field cron';
+
+// --- cadence -------------------------------------------------------------------------------
+
+/** The IANA zone to use: --tz (checked), else this computer's. */
+export function timeZoneOf(flags) {
+  const zone = flags.tz ?? (Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC");
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+  } catch {
+    throw new CliError(EXIT.USAGE, `Unknown time zone "${zone}"; use an IANA name like Europe/Berlin.`);
+  }
+  return zone;
+}
+
+/** Wall-clock hour, minute, second and weekday (0 = Sunday) of `now` in `zone`. */
+function clock(now, zone) {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat("en-US", {
+      timeZone: zone,
+      hourCycle: "h23",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      weekday: "short",
+    })
+      .formatToParts(new Date(now))
+      .map((p) => [p.type, p.value]),
+  );
+  return {
+    hh: Number(parts.hour) % 24,
+    mm: Number(parts.minute),
+    ss: Number(parts.second),
+    dow: DAYS.indexOf(parts.weekday.slice(0, 3).toLowerCase()),
+  };
+}
+
+/**
+ * `--every` (+ `--at`) -> a 5-field cron, as the portal's `toCron` writes it. `--at` defaults
+ * to the next quarter hour in the schedule's zone (the portal's `defaultCadence`).
+ */
+export function cronFor({ every, at }, now, zone) {
+  const fail = (why) => new CliError(EXIT.USAGE, `${why} --every takes ${CADENCE_HELP}.`);
+  if (!every) throw fail("How often?");
+  const fields = every.trim().split(/\s+/);
+  if (fields.length === 5) {
+    if (at !== undefined) throw fail("--at does not go with a cron expression.");
+    return fields.join(" ");
+  }
+  const preset = every.trim().toLowerCase();
+  if (!["hourly", "daily", "weekdays", "weekly"].includes(preset)) throw fail(`"${every}" is not a cadence.`);
+
+  const c = clock(now, zone);
+  const minutes = (Math.ceil((c.hh * 60 + c.mm + (c.ss > 0 ? 1 : 0)) / 15) * 15) % 1440;
+  let hh = Math.floor(minutes / 60);
+  let mm = minutes % 60;
+  let dow = c.dow;
+  if (at !== undefined) {
+    const text = at.trim().toLowerCase();
+    let match;
+    if (preset === "hourly") {
+      match = /^:?(\d{1,2})$/.exec(text);
+      if (!match || Number(match[1]) > 59) throw fail(`--at for hourly is :MM, not "${at}".`);
+      mm = Number(match[1]);
+    } else {
+      const shape = preset === "weekly" ? /^([a-z]+|[0-6])\s+(\d{1,2}):(\d{2})$/ : /^()(\d{1,2}):(\d{2})$/;
+      match = shape.exec(text);
+      const day = match?.[1] ? dayIndex(match[1]) : dow;
+      if (!match || Number(match[2]) > 23 || Number(match[3]) > 59 || day < 0) {
+        throw fail(`--at for ${preset} is ${preset === "weekly" ? '"mon HH:MM"' : "HH:MM"}, not "${at}".`);
+      }
+      [hh, mm, dow] = [Number(match[2]), Number(match[3]), day];
+    }
+  }
+  return {
+    hourly: `${mm} * * * *`,
+    daily: `${mm} ${hh} * * *`,
+    weekdays: `${mm} ${hh} * * 1-5`,
+    weekly: `${mm} ${hh} * * ${dow}`,
+  }[preset];
+}
+
+function dayIndex(text) {
+  if (/^[0-6]$/.test(text)) return Number(text);
+  const short = text.slice(0, 3);
+  const full = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+  const index = DAYS.indexOf(short);
+  return index >= 0 && full[index].startsWith(text) ? index : -1;
+}
+
+/** `--budget 5` -> 5; `--budget none` -> null (no per-run cap) where allowed. */
+function budgetOf(text, { allowNone }) {
+  if (text === undefined) return undefined;
+  if (allowNone && text.trim().toLowerCase() === "none") return null;
+  const value = Number(text.replace(/^\$/, ""));
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new CliError(EXIT.USAGE, `--budget is a dollar amount per run${allowNone ? ", or none" : ""}, not "${text}".`);
+  }
+  return value;
+}
+
+function triggerOf(ctx, { every, at, tz }) {
+  const zone = timeZoneOf({ tz });
+  if (tz === undefined && zone === "UTC" && ctx.ui.interactive) {
+    ctx.ui.progress(ctx.ui.dim("(your system time zone is UTC; pass --tz to change)"));
+  }
+  return { kind: "cron", expr: cronFor({ every, at }, ctx.io.now(), zone), timezone: zone };
+}
+
+// --- printing ------------------------------------------------------------------------------
+
+function when(iso, zone) {
+  if (!iso) return "-";
+  return new Intl.DateTimeFormat("en-US", {
+    timeZone: zone,
+    weekday: "short",
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  }).format(new Date(iso));
+}
+
+const labelOf = (s) => `${s.cadence_label ?? s.trigger.expr} ${s.trigger.timezone}`;
+const firstLine = (text) => (text ?? "").split("\n")[0].slice(0, 60);
+
+function stateOf(s) {
+  if (s.status !== "paused") return `next ${when(s.upcoming?.[0] ?? s.next_fire_at, s.trigger.timezone)}`;
+  const why = s.pause_reason && s.pause_reason !== "user" ? (PAUSE_REASONS[s.pause_reason] ?? s.pause_reason) : null;
+  return why ? `paused (${why})` : "paused";
+}
+
+function row(s) {
+  const last = s.last_occurrence ? (s.last_occurrence.summary ?? s.last_occurrence.disposition) : "";
+  return `${s.id.slice(0, 8)}  ${labelOf(s)}  ${stateOf(s)}  "${firstLine(s.prompt)}"${last ? `  ${last}` : ""}`;
+}
+
+function upcomingLine(s) {
+  const times = (s.upcoming ?? []).map((t) => when(t, s.trigger.timezone));
+  return times.length ? `Next: ${times.join(" · ")}` : "Next: -";
+}
+
+function card(s, occurrences = []) {
+  const lines = [`${labelOf(s)} · ${stateOf(s)}`, `"${firstLine(s.prompt)}"`];
+  if (s.repo_name) lines.push(`Project ${s.repo_name}`);
+  if (s.occurrence_budget_usd !== null && s.occurrence_budget_usd !== undefined) {
+    lines.push(`Cap $${s.occurrence_budget_usd} per run`);
+  }
+  if (s.status !== "paused") lines.push(upcomingLine(s));
+  lines.push("", occurrences.length ? "History:" : "History: none yet");
+  for (const o of occurrences) {
+    const parts = [when(o.slot_ts, s.trigger.timezone), o.disposition, o.summary, o.coding_run_id].filter(Boolean);
+    lines.push(`  ${parts.join(" · ")}`);
+  }
+  return lines.join("\n");
+}
+
+// --- API -----------------------------------------------------------------------------------
+
+async function listAll(ctx, query) {
+  const schedules = [];
+  let cursor;
+  for (let page = 0; page < MAX_PAGES; page++) {
+    const res = await ctx.client.call("listSchedules", { query: { ...query, limit: 100, cursor } });
+    schedules.push(...res.schedules);
+    cursor = res.next_cursor;
+    if (!cursor) break;
+  }
+  return schedules;
+}
+
+/** A full id, or the 8-character prefix `schedule list` prints. */
+async function scheduleId(ctx, ref) {
+  if (!ref) throw new CliError(EXIT.USAGE, "Which schedule? Its id is in `syndai schedule list`.");
+  if (UUID.test(ref)) return ref;
+  const hits = (await listAll(ctx, {})).filter((s) => s.id.startsWith(ref.toLowerCase()));
+  if (hits.length === 1) return hits[0].id;
+  throw new CliError(EXIT.USAGE, hits.length ? `"${ref}" matches ${hits.length} schedules; use more of the id.` : `No schedule "${ref}".`, {
+    next: "syndai schedule list --all",
+  });
+}
+
+/**
+ * Create with a fresh request id (so a retried POST is the same create). A replay answers
+ * 409 + Location: that schedule is the result. A 409 without one is a changed replay.
+ */
+async function create(ctx, body) {
+  const res = await ctx.client.call("createSchedule", {
+    body: { ...body, client_request_id: `cli:${ulid()}` },
+    retry: true,
+    raw: true,
+  });
+  if (res.status < 300) return res.body;
+  const location = res.status === 409 ? res.headers.get("location") : null;
+  if (location) return (await ctx.client.send("GET", new URL(location, ctx.baseUrl).pathname)).schedule;
+  throw new ApiError(res.status, res.body, res.headers);
+}
+
+function printCreated(ctx, s, heading) {
+  ctx.ui.result(
+    s,
+    [heading, `${labelOf(s)}: "${firstLine(s.prompt)}"`, upcomingLine(s), `Manage: syndai schedule show ${s.id}`].join("\n"),
+  );
+  return EXIT.OK;
+}
+
+// --- commands ------------------------------------------------------------------------------
+
+export async function schedule(ctx, [action, ...rest]) {
+  const handler = ACTIONS[action];
+  if (!handler) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai schedule list|show|add|edit|pause|resume|run-now|delete", {
+      next: "syndai schedule list",
+    });
+  }
+  return handler(ctx, rest);
+}
+
+const ACTIONS = {
+  async list(ctx) {
+    const { flags, ui } = ctx;
+    if (flags.all && flags.app) throw new CliError(EXIT.USAGE, "Pick one of --app and --all.");
+    const project = flags.all ? null : await resolveProject(ctx, { app: flags.app });
+    const schedules = await listAll(ctx, project ? { coding_repository_id: project.id } : {});
+    const where = project ? projectLabel(project) : "any project";
+    ui.result(
+      { project_id: project?.id ?? null, schedules },
+      schedules.length
+        ? schedules.map(row).join("\n")
+        : `Nothing repeats on ${where} yet. Add one: syndai schedule add "<what>" --every daily`,
+    );
+    return EXIT.OK;
+  },
+
+  async show(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const detail = await ctx.client.call("getSchedule", { params: { schedule_id: id } });
+    ctx.ui.result(detail, card(detail.schedule, detail.occurrences));
+    return EXIT.OK;
+  },
+
+  async add(ctx, words) {
+    const { flags } = ctx;
+    const prompt = words.join(" ").trim();
+    if (!prompt) throw new CliError(EXIT.USAGE, 'Say what to run: syndai schedule add "<what>" --every daily');
+    const trigger = triggerOf(ctx, flags);
+    const budget = budgetOf(flags.budget, { allowNone: false });
+    const project = await resolveProject(ctx, { app: flags.app });
+    const created = await create(ctx, {
+      prompt,
+      coding_repository_id: project.id,
+      trigger,
+      ...(budget === undefined ? {} : { occurrence_budget_usd: budget }),
+    });
+    return printCreated(ctx, created, `Repeats on ${projectLabel(project)}.`);
+  },
+
+  async edit(ctx, [ref]) {
+    const { client, flags, ui } = ctx;
+    const id = await scheduleId(ctx, ref);
+    if ([flags.prompt, flags.every, flags.at, flags.tz, flags.budget].every((v) => v === undefined)) {
+      throw new CliError(EXIT.USAGE, "Nothing to change: pass --prompt, --every, --at, --tz or --budget.");
+    }
+    if (flags.at !== undefined && flags.every === undefined) {
+      throw new CliError(EXIT.USAGE, "--at goes with --every (the cadence it sets the time of).");
+    }
+    const { schedule: current } = await client.call("getSchedule", { params: { schedule_id: id } });
+    const patch = {};
+    if (flags.prompt !== undefined && flags.prompt !== current.prompt) patch.prompt = flags.prompt;
+    if (flags.every !== undefined || flags.tz !== undefined) {
+      const zone = timeZoneOf({ tz: flags.tz ?? current.trigger.timezone });
+      const expr = flags.every === undefined ? current.trigger.expr : cronFor(flags, ctx.io.now(), zone);
+      if (expr !== current.trigger.expr || zone !== current.trigger.timezone) {
+        patch.trigger = { kind: "cron", expr, timezone: zone };
+      }
+    }
+    const budget = budgetOf(flags.budget, { allowNone: true });
+    if (budget !== undefined && budget !== (current.occurrence_budget_usd ?? null)) {
+      patch.occurrence_budget_usd = budget;
+    }
+    if (Object.keys(patch).length === 0) {
+      ui.result(current, `Nothing changed. ${row(current)}`);
+      return EXIT.OK;
+    }
+    const updated = await client.call("updateSchedule", { params: { schedule_id: id }, body: patch });
+    ui.result(updated, `Updated. ${row(updated)}`);
+    return EXIT.OK;
+  },
+
+  async pause(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const s = await ctx.client.call("pauseSchedule", { params: { schedule_id: id } });
+    ctx.ui.result(s, `Paused. ${row(s)}`);
+    return EXIT.OK;
+  },
+
+  async resume(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const s = await ctx.client.call("resumeSchedule", { params: { schedule_id: id } });
+    ctx.ui.result(s, `Resumed. ${row(s)}`);
+    return EXIT.OK;
+  },
+
+  async "run-now"(ctx, [ref]) {
+    const id = await scheduleId(ctx, ref);
+    const res = await ctx.client.call("runScheduleNow", { params: { schedule_id: id }, raw: true });
+    if (res.status >= 400 && res.status !== 409) throw new ApiError(res.status, res.body, res.headers);
+    const already = res.status === 409;
+    ctx.ui.result(
+      { schedule_id: id, started: !already, already_started: already },
+      `${already ? "It already started this minute." : "Started."} Its run shows in: syndai schedule show ${id}`,
+    );
+    return EXIT.OK;
+  },
+
+  async delete(ctx, [ref]) {
+    const { flags, ui, io } = ctx;
+    const id = await scheduleId(ctx, ref);
+    if (!flags.yes) {
+      if (!ui.interactive) {
+        throw new CliError(EXIT.USAGE, "Deleting a schedule needs --yes when nobody can confirm it.", {
+          next: `syndai schedule delete ${id} --yes`,
+        });
+      }
+      const answer = await ask(io, `Delete schedule ${id.slice(0, 8)} and its history? [y/N] `);
+      if (!/^y/i.test(answer)) {
+        ui.result({ schedule_id: id, deleted: false }, "Kept.");
+        return EXIT.OK;
+      }
+    }
+    await ctx.client.call("deleteSchedule", { params: { schedule_id: id } });
+    ui.result({ schedule_id: id, deleted: true }, "Deleted.");
+    return EXIT.OK;
+  },
+};
+
+/**
+ * Repeat a run: the server copies its original prompt and project (`from_coding_run_id`).
+ * The first run is the next scheduled time, never now: re-running a run that just finished
+ * would charge twice.
+ */
+export async function repeat(ctx, [runId]) {
+  const { client, flags } = ctx;
+  if (!runId) throw new CliError(EXIT.USAGE, "Which run? syndai repeat <run> --every weekly");
+  const trigger = triggerOf(ctx, flags);
+  const budget = budgetOf(flags.budget, { allowNone: false });
+  const { run } = await client.call("getRun", { params: { coding_run_id: runId } });
+  const created = await create(ctx, {
+    from_coding_run_id: runId,
+    trigger,
+    ...(budget === undefined ? {} : { occurrence_budget_usd: budget }),
+  });
+  const cost = typeof run.cost_usd === "number" ? ` (last run cost $${run.cost_usd.toFixed(2)})` : "";
+  return printCreated(
+    ctx,
+    created,
+    `Repeating "${firstLine(run.title ?? run.prompt)}"${cost}. First run ${when(created.upcoming?.[0], created.trigger.timezone)}.`,
+  );
+}

package/src/settings.js

@@ -0,0 +1,130 @@
+// `syndai settings`: one project's owner settings.
+//
+// Settings live in four places server-side:
+//   autonomy          repo-scoped policy default       GET/PUT policy/defaults
+//   feature_requests  the app's publication            GET/PATCH .../publication
+//   bug_scan          the repo's Bug Finder schedule   GET/PUT repositories/{id}/bug-scan
+//   protected_paths   the repo row                     PATCH repos/{id} (a key may only tighten)
+
+import { ApiError, CliError, EXIT, explain } from "./errors.js";
+import { projectLabel, resolveProject } from "./projects.js";
+
+const VALUES = {
+  autonomy: ["gated", "auto", "merge"],
+  feature_requests: ["off", "members", "public"],
+  bug_scan: ["on", "off"],
+};
+
+export async function settings(ctx, args) {
+  const { flags, ui } = ctx;
+  const [action = "get", ...pairs] = args;
+  if (!["get", "set"].includes(action) || (action === "set" && pairs.length === 0)) {
+    throw new CliError(EXIT.USAGE, "Usage: syndai settings [get | set key=value...]", {
+      next: "syndai settings set autonomy=auto",
+    });
+  }
+  const project = await resolveProject(ctx, { app: flags.app });
+  for (const pair of pairs) await apply(ctx, project, parsePair(pair));
+  const current = await read(ctx, project);
+  const show = (value) =>
+    value === null ? "-" : Array.isArray(value) ? value.join(", ") || "(none)" : value;
+  const lines = [ui.bold(projectLabel(project))];
+  for (const key of ["autonomy", "feature_requests", "bug_scan", "protected_paths"]) {
+    const why = current.unavailable[key];
+    lines.push(`  ${key.padEnd(17)}${why ? ui.dim(why) : show(current[key])}`);
+  }
+  ui.result({ project_id: project.id, ...current }, lines.join("\n"));
+  return EXIT.OK;
+}
+
+function parsePair(pair) {
+  const match = /^([a-z_]+)(\+?=)(.*)$/.exec(pair);
+  const known = match && (match[1] in VALUES || match[1] === "protected_paths");
+  if (!known || (match[2] === "+=" && match[1] !== "protected_paths")) {
+    throw new CliError(
+      EXIT.USAGE,
+      `Cannot set "${pair}". Keys: autonomy, feature_requests, bug_scan, protected_paths (= or +=).`,
+    );
+  }
+  const [, key, op, value] = match;
+  if (VALUES[key] && !VALUES[key].includes(value)) {
+    throw new CliError(EXIT.USAGE, `${key} is one of ${VALUES[key].join(", ")}.`);
+  }
+  return { key, op, value };
+}
+
+async function apply(ctx, project, { key, op, value }) {
+  const { client } = ctx;
+  if (key === "autonomy") {
+    const current = await orNull(client.call("getPolicy", { query: { coding_repository_id: project.id } }));
+    await client.call("putPolicy", {
+      body: { coding_repository_id: project.id, config: { ...(current?.config ?? {}), autonomy: value } },
+    });
+  } else if (key === "feature_requests") {
+    await client.call("updatePublication", {
+      params: { customer_id: project.customer_id, coding_repository_id: project.id },
+      body: { feature_requests: value },
+    });
+  } else if (key === "bug_scan") {
+    await client.call("setBugScan", {
+      params: { repository_id: project.id },
+      body: { enabled: value === "on" },
+    });
+  } else {
+    const added = value
+      .split(",")
+      .map((p) => p.trim())
+      .filter(Boolean);
+    const next = op === "+=" ? [...project.protected_paths, ...added] : added;
+    // The server refuses a loosening from a key with HUMAN_APPROVAL_REQUIRED + review_url.
+    const repo = await client.call("updateRepo", {
+      params: { coding_repository_id: project.id },
+      body: { protected_paths: next },
+    });
+    project.protected_paths = repo.protected_paths ?? next;
+  }
+}
+
+async function read(ctx, project) {
+  const { client } = ctx;
+  const ids = { customer_id: project.customer_id, coding_repository_id: project.id };
+  const [policy, publication, bugScan] = await Promise.all([
+    settle(client.call("getPolicy", { query: { coding_repository_id: project.id } })),
+    settle(client.call("getPublication", { params: ids })),
+    settle(client.call("getBugScan", { params: { repository_id: project.id } })),
+  ]);
+  const unavailable = {};
+  for (const [key, got] of [
+    ["autonomy", policy],
+    ["feature_requests", publication],
+    ["bug_scan", bugScan],
+  ]) {
+    if (got.error) unavailable[key] = got.error;
+  }
+  return {
+    autonomy: policy.value?.config?.autonomy ?? null,
+    feature_requests: publication.value?.feature_requests ?? null,
+    bug_scan: bugScan.value ? (bugScan.value.enabled ? "on" : "off") : null,
+    protected_paths: project.protected_paths,
+    unavailable,
+  };
+}
+
+/** A read that may be missing (404 -> null) or not allowed for this key or plan (-> error). */
+async function settle(promise) {
+  try {
+    return { value: await promise };
+  } catch (err) {
+    if (!(err instanceof ApiError)) throw err;
+    return err.status === 404 ? { value: null } : { error: explain(err).message };
+  }
+}
+
+async function orNull(promise) {
+  try {
+    return await promise;
+  } catch (err) {
+    if (err instanceof ApiError && err.status === 404) return null;
+    throw err;
+  }
+}

package/src/store.js

@@ -0,0 +1,137 @@
+// Local files, all outside any repository (`.syndai/**` in a repo is a protected path):
+//   $XDG_CONFIG_HOME/syndai/credentials.json  keys, by workspace (customer), mode 0600
+//   $XDG_CONFIG_HOME/syndai/links.json        directory -> project
+//   $XDG_STATE_HOME/syndai/pending/*.json     a change's request id, written BEFORE its POST
+//   $XDG_CACHE_HOME/syndai/openapi-<host>.json the live API description (24h)
+
+import fs from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { CliError, EXIT } from "./errors.js";
+
+const PENDING_TTL_MS = 24 * 60 * 60 * 1000;
+
+export function storePaths(env) {
+  const home = env.HOME || homedir();
+  const config = path.join(env.XDG_CONFIG_HOME || path.join(home, ".config"), "syndai");
+  const state = path.join(env.XDG_STATE_HOME || path.join(home, ".local", "state"), "syndai");
+  const cache = path.join(env.XDG_CACHE_HOME || path.join(home, ".cache"), "syndai");
+  return {
+    home,
+    credentials: path.join(config, "credentials.json"),
+    links: path.join(config, "links.json"),
+    pending: path.join(state, "pending"),
+    cache,
+  };
+}
+
+export function readJson(file, fallback) {
+  let text;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return fallback;
+    throw err;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliError(EXIT.FAILED, `${file} is not valid JSON; fix or delete it.`);
+  }
+}
+
+/** Atomic write (temp file + rename) with an exact mode, whatever the umask. */
+export function writeFileAtomic(file, text, mode = 0o600) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tmp, text, { mode });
+  fs.chmodSync(tmp, mode);
+  fs.renameSync(tmp, file);
+}
+
+export function writeJson(file, data, mode = 0o600) {
+  writeFileAtomic(file, `${JSON.stringify(data, null, 2)}\n`, mode);
+}
+
+// --- credentials -------------------------------------------------------------------------
+
+export function loadCredentials(paths) {
+  const data = readJson(paths.credentials, null);
+  return data && typeof data.customers === "object" ? data : { default: null, customers: {} };
+}
+
+export function saveCredential(paths, { customer_id, api_key, key_id, expires_at }) {
+  const data = loadCredentials(paths);
+  data.customers[customer_id] = { api_key, key_id, expires_at };
+  data.default = customer_id;
+  writeJson(paths.credentials, data);
+}
+
+export function removeCredential(paths, customerId) {
+  const data = loadCredentials(paths);
+  delete data.customers[customerId];
+  if (data.default === customerId) data.default = Object.keys(data.customers)[0] ?? null;
+  writeJson(paths.credentials, data);
+}
+
+// --- links -------------------------------------------------------------------------------
+
+/** The link for `cwd` or its nearest linked parent, or null. */
+export function findLink(paths, cwd) {
+  const links = readJson(paths.links, {});
+  let dir = path.resolve(cwd);
+  for (;;) {
+    if (links[dir]) return { dir, ...links[dir] };
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function saveLink(paths, dir, link) {
+  const links = readJson(paths.links, {});
+  links[path.resolve(dir)] = link;
+  writeJson(paths.links, links);
+}
+
+// --- pending change requests -------------------------------------------------------------
+
+function pendingFile(paths, requestId) {
+  return path.join(paths.pending, `${requestId.replace(/[^\w-]/g, "_")}.json`);
+}
+
+/** A not-yet-confirmed request for the same project and text (a crash or a retry), or null. */
+export function findPending(paths, { app, text }, now = Date.now()) {
+  let names;
+  try {
+    names = fs.readdirSync(paths.pending);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+  let match = null;
+  for (const name of names.filter((n) => n.endsWith(".json"))) {
+    const file = path.join(paths.pending, name);
+    let record;
+    try {
+      record = JSON.parse(fs.readFileSync(file, "utf8"));
+    } catch {
+      fs.rmSync(file, { force: true });
+      continue;
+    }
+    if (now - Date.parse(record.created_at) > PENDING_TTL_MS) {
+      fs.rmSync(file, { force: true });
+    } else if (record.app === app && record.text === text) {
+      match = record;
+    }
+  }
+  return match;
+}
+
+export function writePending(paths, record) {
+  writeJson(pendingFile(paths, record.request_id), record);
+}
+
+export function clearPending(paths, requestId) {
+  fs.rmSync(pendingFile(paths, requestId), { force: true });
+}