@cad0p/pi-usage 0.0.0-stage → 0.11.2

package/src/model.js

@@ -0,0 +1,332 @@
+/**
+ * Shared quota model.
+ *
+ * Every provider normalizes its own API response into `QuotaWindow[]` so the
+ * terminal renderer, the Pi TUI extension and the Moshi adapter consume exactly
+ * one shape.
+ */
+
+/**
+ * @typedef {Object} QuotaWindow
+ * @property {string} id                   Stable id, e.g. "5h", "weekly", "monthly".
+ * @property {string} label                Human label, e.g. "5h window".
+ * @property {number | null} usedPercent   Percent consumed (0-100).
+ * @property {number | null} remainingPercent
+ * @property {string | null} resetsAt      ISO timestamp.
+ * @property {number | null} resetsInSec   Seconds until reset.
+ * @property {number | null} windowSeconds Length of the window when known.
+ * @property {string | null} note          Provider-specific extra context.
+ */
+
+/**
+ * @typedef {Object} QuotaResult
+ * @property {string} family
+ * @property {string} label
+ * @property {string} account              Display identity (email or short id).
+ * @property {string | null} [slot]         Numbered sibling account ("2"), or null
+ *                                          for the base entry of a family.
+ * @property {string | null} plan
+ * @property {QuotaWindow[]} windows
+ * @property {string | null} error         Degradation message; null when healthy.
+ * @property {boolean} ok
+ * @property {string} updatedAt            ISO timestamp.
+ * @property {string} source               Credential source description.
+ * @property {"pi" | "claude-code"} [sourceKind]  Which kind of store produced it.
+ * @property {string | null} expiresInMin  Credential freshness, when known.
+ */
+
+/**
+ * Clamp to the inclusive 0-100 percent range.
+ *
+ * A missing value stays missing: `Number(null)` is 0, and turning "no data" into
+ * "0% used" would render as a full bar.
+ *
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+export function clampPercent(value) {
+  if (typeof value !== "number" && typeof value !== "string") return null;
+  if (typeof value === "string" && value.trim() === "") return null;
+  const number = Number(value);
+  if (!Number.isFinite(number)) return null;
+  return Math.min(100, Math.max(0, number));
+}
+
+/**
+ * @param {unknown} value
+ * @returns {number | null}
+ */
+export function finiteNumber(value) {
+  if (typeof value !== "number" && typeof value !== "string") return null;
+  if (typeof value === "string" && value.trim() === "") return null;
+  const number = Number(value);
+  return Number.isFinite(number) ? number : null;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | null}
+ */
+export function stringValue(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+/**
+ * Epoch values below this are seconds, above are milliseconds. See the matching
+ * constant in auth/pi-auth.js.
+ */
+const SECONDS_EPOCH_CEILING = 1e11;
+
+/**
+ * Parse a reset value into an ISO timestamp plus a countdown.
+ *
+ * Accepts ISO strings, epoch seconds/ms numbers and explicit second counts.
+ *
+ * @param {unknown} value
+ * @param {number} now
+ * @returns {{ resetsAt: string | null, resetsInSec: number | null }}
+ */
+export function parseReset(value, now = Date.now()) {
+  const numeric = finiteNumber(value);
+  if (numeric !== null) {
+    if (numeric > 1e9) {
+      const ms = numeric > SECONDS_EPOCH_CEILING ? numeric : numeric * 1000;
+      return { resetsAt: new Date(ms).toISOString(), resetsInSec: Math.max(0, Math.round((ms - now) / 1000)) };
+    }
+    if (numeric >= 0) {
+      return parseResetSeconds(numeric, now);
+    }
+    return { resetsAt: null, resetsInSec: null };
+  }
+  const text = stringValue(value);
+  if (text) {
+    if (/^\d+(\.\d+)?$/.test(text)) {
+      const num = Number(text);
+      if (num >= 0 && num <= 1e9) {
+        return parseResetSeconds(num, now);
+      }
+    }
+    const parsed = Date.parse(text);
+    if (!Number.isNaN(parsed)) {
+      return { resetsAt: new Date(parsed).toISOString(), resetsInSec: Math.max(0, Math.round((parsed - now) / 1000)) };
+    }
+  }
+  return { resetsAt: null, resetsInSec: null };
+}
+
+/**
+ * Derive a reset timestamp purely from a remaining-seconds count.
+ *
+ * @param {unknown} seconds
+ * @param {number} now
+ * @returns {{ resetsAt: string | null, resetsInSec: number | null }}
+ */
+export function parseResetSeconds(seconds, now = Date.now()) {
+  const numeric = finiteNumber(seconds);
+  if (numeric === null || numeric < 0) return { resetsAt: null, resetsInSec: null };
+  const rounded = Math.round(numeric);
+  return { resetsAt: new Date(now + rounded * 1000).toISOString(), resetsInSec: rounded };
+}
+
+/**
+ * Build a window from a used-percent value.
+ *
+ * @param {{
+ *   id: string,
+ *   label: string,
+ *   usedPercent?: unknown,
+ *   remainingPercent?: unknown,
+ *   resetsAt?: unknown,
+ *   resetsInSec?: unknown,
+ *   windowSeconds?: unknown,
+ *   note?: string | null,
+ *   now?: number,
+ * }} input
+ * @returns {QuotaWindow}
+ */
+export function buildWindow(input) {
+  const now = input.now ?? Date.now();
+  let used = clampPercent(input.usedPercent);
+  let remaining = clampPercent(input.remainingPercent);
+  if (used === null && remaining !== null) {
+    used = 100 - remaining;
+  } else if (remaining === null && used !== null) {
+    remaining = 100 - used;
+  }
+
+  let resets = { resetsAt: null, resetsInSec: null };
+  if (input.resetsAt !== undefined && input.resetsAt !== null) {
+    resets = parseReset(input.resetsAt, now);
+  } else if (input.resetsInSec !== undefined && input.resetsInSec !== null) {
+    resets = parseResetSeconds(input.resetsInSec, now);
+  }
+
+  return {
+    id: input.id,
+    label: input.label,
+    usedPercent: used,
+    remainingPercent: remaining,
+    resetsAt: resets.resetsAt,
+    resetsInSec: resets.resetsInSec,
+    windowSeconds: finiteNumber(input.windowSeconds),
+    note: input.note ?? null,
+  };
+}
+
+/**
+ * Map a window length in seconds onto a canonical id/label pair.
+ *
+ * @param {number | null} seconds
+ * @returns {{ id: string, label: string }}
+ */
+export function windowFromSeconds(seconds) {
+  if (seconds === null) return { id: "window", label: "Window" };
+  if (seconds <= 6 * 3600) return { id: "5h", label: "5h window" };
+  if (seconds <= 8 * 86400) return { id: "weekly", label: "Weekly window" };
+  if (seconds <= 31 * 86400) return { id: "monthly", label: "Monthly window" };
+  return { id: "window", label: "Window" };
+}
+
+/**
+ * Map a provider-supplied window name onto a canonical id/label pair.
+ *
+ * @param {unknown} name
+ * @returns {{ id: string, label: string }}
+ */
+export function windowFromName(name) {
+  const text = (stringValue(name) ?? "").toLowerCase();
+  if (text.includes("week")) return { id: "weekly", label: "Weekly window" };
+  if (text.includes("month")) return { id: "monthly", label: "Monthly window" };
+  if (text.includes("day") && !text.includes("week")) return { id: "daily", label: "Daily window" };
+  if (text.includes("5h") || text.includes("five") || text.includes("session") || text.includes("hour")) {
+    return { id: "5h", label: "5h window" };
+  }
+  return { id: text || "window", label: text || "Window" };
+}
+
+/**
+ * Format a second count as a short human duration, e.g. "3h 12m".
+ *
+ * @param {number | null} seconds
+ * @returns {string}
+ */
+export function humanDuration(seconds) {
+  if (seconds === null || !Number.isFinite(seconds)) return "unknown";
+  if (seconds <= 0) return "now";
+  const total = Math.round(seconds);
+  const days = Math.floor(total / 86400);
+  const hours = Math.floor((total % 86400) / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  if (days > 0) return `${days}d ${hours}h`;
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m`;
+  return `${total}s`;
+}
+
+/**
+ * Format a reset countdown for a UI string.
+ *
+ * @param {number | null} seconds
+ * @returns {string}
+ */
+export function humanReset(seconds) {
+  if (seconds === null) return "reset unknown";
+  if (seconds <= 0) return "resetting now";
+  return `reset in ${humanDuration(seconds)}`;
+}
+
+/**
+ * Build a complete degraded result for one family.
+ *
+ * @param {{
+ *   family: string,
+ *   label: string,
+ *   account?: string | null,
+ *   plan?: string | null,
+ *   error: string,
+ *   source: string,
+ *   now?: number,
+ *   expiresInMin?: number | null,
+ *   windows?: QuotaWindow[],
+ * }} input
+ * @returns {QuotaResult}
+ */
+export function degradedResult(input) {
+  const notConfigured = Boolean(
+    input.notConfigured ??
+      (typeof input.error === "string" && input.error.startsWith("no ") && input.error.includes("credential in the Pi store")),
+  );
+  return {
+    family: input.family,
+    label: input.label,
+    account: input.account ?? "unknown",
+    plan: input.plan ?? null,
+    windows: input.windows ?? [],
+    error: input.error,
+    ok: false,
+    notConfigured,
+    updatedAt: new Date(input.now ?? Date.now()).toISOString(),
+    source: input.source,
+    sourceKind: input.sourceKind,
+    expiresInMin: input.expiresInMin ?? null,
+  };
+}
+
+/**
+ * Pick a display identity without leaking full secrets.
+ *
+ * @param {{ email?: string | null, accountId?: string | null, projectId?: string | null, identity?: string }} credential
+ * @returns {string}
+ */
+export function displayIdentity(credential) {
+  if (credential.email) return credential.email;
+  if (credential.accountId) return `${credential.accountId.slice(0, 8)}…`;
+  if (credential.projectId) return `project ${credential.projectId.slice(0, 8)}…`;
+  return credential.identity ? `id ${credential.identity.slice(0, 8)}…` : "unknown";
+}
+
+/**
+ * Rank a window by how soon it constrains you: 0 = shortest (5h/session),
+ * then daily, weekly, monthly, and finally anything unrecognized.
+ *
+ * @param {QuotaWindow} window
+ * @returns {number}
+ */
+export function windowRank(window) {
+  const seconds = finiteNumber(window?.windowSeconds);
+  if (seconds !== null && seconds > 0) {
+    if (seconds <= 6 * 3600) return 0;
+    if (seconds <= 36 * 3600) return 1;
+    if (seconds <= 8 * 86400) return 2;
+    if (seconds <= 31 * 86400) return 3;
+  }
+  const id = String(window?.id ?? "").toLowerCase();
+  if (id.includes("5h") || id.includes("session") || id.includes("hour") || id.includes("rolling")) return 0;
+  if (id.includes("daily") || id.includes("day")) return 1;
+  if (id.includes("weekly") || id.includes("week") || id.includes("7d")) return 2;
+  if (id.includes("monthly") || id.includes("month") || id.includes("30d")) return 3;
+  return 4;
+}
+
+/**
+ * The window that represents a provider at a glance.
+ *
+ * Shortest first, because that is the limit you hit first: a 5h window at 3%
+ * used tells you far more about "can I keep working" than a weekly window at
+ * 69%. Ties inside the same rank go to the tightest one, so Antigravity's two
+ * 5h groups resolve to whichever is more consumed.
+ *
+ * @param {QuotaWindow[]} windows
+ * @returns {QuotaWindow | null}
+ */
+export function selectPrimaryWindow(windows) {
+  const list = Array.isArray(windows) ? windows : [];
+  const scored = list.filter((window) => window?.remainingPercent !== null && window?.remainingPercent !== undefined);
+  if (scored.length === 0) return list[0] ?? null;
+  return scored.reduce((best, window) => {
+    const bestRank = windowRank(best);
+    const rank = windowRank(window);
+    if (rank !== bestRank) return rank < bestRank ? window : best;
+    return /** @type {number} */ (window.remainingPercent) < /** @type {number} */ (best.remainingPercent) ? window : best;
+  });
+}

package/src/omarchy/assets/antigravity.svg

@@ -0,0 +1,3 @@
+<svg viewBox="0 0 24 24" width="24" height="24" xmlns="http://www.w3.org/2000/svg">
+  <path d="M12 0C12 6.627 6.627 12 0 12c6.627 0 12 5.373 12 12 0-6.627 5.373-12 12-12-6.627 0-12-5.373-12-12z" fill="#B877DB"/>
+</svg>

package/src/omarchy/assets/claude.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="256" height="257" preserveAspectRatio="xMidYMid" viewBox="0 0 256 257"><path fill="#D97757" d="m50.228 170.321 50.357-28.257.843-2.463-.843-1.361h-2.462l-8.426-.518-28.775-.778-24.952-1.037-24.175-1.296-6.092-1.297L0 125.796l.583-3.759 5.12-3.434 7.324.648 16.202 1.101 24.304 1.685 17.629 1.037 26.118 2.722h4.148l.583-1.685-1.426-1.037-1.101-1.037-25.147-17.045-27.22-18.017-14.258-10.37-7.713-5.25-3.888-4.925-1.685-10.758 7-7.713 9.397.649 2.398.648 9.527 7.323 20.35 15.75L94.817 91.9l3.889 3.24 1.555-1.102.195-.777-1.75-2.917-14.453-26.118-15.425-26.572-6.87-11.018-1.814-6.61c-.648-2.723-1.102-4.991-1.102-7.778l7.972-10.823L71.42 0 82.05 1.426l4.472 3.888 6.61 15.101 10.694 23.786 16.591 32.34 4.861 9.592 2.592 8.879.973 2.722h1.685v-1.556l1.36-18.211 2.528-22.36 2.463-28.776.843-8.1 4.018-9.722 7.971-5.25 6.222 2.981 5.12 7.324-.713 4.73-3.046 19.768-5.962 30.98-3.889 20.739h2.268l2.593-2.593 10.499-13.934 17.628-22.036 7.778-8.749 9.073-9.657 5.833-4.601h11.018l8.1 12.055-3.628 12.443-11.342 14.388-9.398 12.184-13.48 18.147-8.426 14.518.778 1.166 2.01-.194 30.46-6.481 16.462-2.982 19.637-3.37 8.88 4.148.971 4.213-3.5 8.62-20.998 5.184-24.628 4.926-36.682 8.685-.454.324.519.648 16.526 1.555 7.065.389h17.304l32.21 2.398 8.426 5.574 5.055 6.805-.843 5.184-12.962 6.611-17.498-4.148-40.83-9.721-14-3.5h-1.944v1.167l11.666 11.406 21.387 19.314 26.767 24.887 1.36 6.157-3.434 4.86-3.63-.518-23.526-17.693-9.073-7.972-20.545-17.304h-1.36v1.814l4.73 6.935 25.017 37.59 1.296 11.536-1.814 3.76-6.481 2.268-7.13-1.297-14.647-20.544-15.1-23.138-12.185-20.739-1.49.843-7.194 77.448-3.37 3.953-7.778 2.981-6.48-4.925-3.436-7.972 3.435-15.749 4.148-20.544 3.37-16.333 3.046-20.285 1.815-6.74-.13-.454-1.49.194-15.295 20.999-23.267 31.433-18.406 19.702-4.407 1.75-7.648-3.954.713-7.064 4.277-6.286 25.47-32.405 15.36-20.092 9.917-11.6-.065-1.686h-.583L44.07 198.125l-12.055 1.555-5.185-4.86.648-7.972 2.463-2.593 20.35-13.999-.064.065Z"/></svg>

package/src/omarchy/assets/codex.svg

@@ -0,0 +1 @@
+<svg fill="#fff" fill-rule="evenodd" height="1em" style="flex:none;line-height:1" viewBox="0 0 24 24" width="1em" xmlns="http://www.w3.org/2000/svg"><title>Codex</title><path clip-rule="evenodd" d="M8.086.457a6.105 6.105 0 013.046-.415c1.333.153 2.521.72 3.564 1.7a.117.117 0 00.107.029c1.408-.346 2.762-.224 4.061.366l.063.03.154.076c1.357.703 2.33 1.77 2.918 3.198.278.679.418 1.388.421 2.126a5.655 5.655 0 01-.18 1.631.167.167 0 00.04.155 5.982 5.982 0 011.578 2.891c.385 1.901-.01 3.615-1.183 5.14l-.182.22a6.063 6.063 0 01-2.934 1.851.162.162 0 00-.108.102c-.255.736-.511 1.364-.987 1.992-1.199 1.582-2.962 2.462-4.948 2.451-1.583-.008-2.986-.587-4.21-1.736a.145.145 0 00-.14-.032c-.518.167-1.04.191-1.604.185a5.924 5.924 0 01-2.595-.622 6.058 6.058 0 01-2.146-1.781c-.203-.269-.404-.522-.551-.821a7.74 7.74 0 01-.495-1.283 6.11 6.11 0 01-.017-3.064.166.166 0 00.008-.074.115.115 0 00-.037-.064 5.958 5.958 0 01-1.38-2.202 5.196 5.196 0 01-.333-1.589 6.915 6.915 0 01.188-2.132c.45-1.484 1.309-2.648 2.577-3.493.282-.188.55-.334.802-.438.286-.12.573-.22.861-.304a.129.129 0 00.087-.087A6.016 6.016 0 015.635 2.31C6.315 1.464 7.132.846 8.086.457zm-.804 7.85a.848.848 0 00-1.473.842l1.694 2.965-1.688 2.848a.849.849 0 001.46.864l1.94-3.272a.849.849 0 00.007-.854l-1.94-3.393zm5.446 6.24a.849.849 0 000 1.695h4.848a.849.849 0 000-1.696h-4.848z"/></svg>

package/src/omarchy/assets/github-actions.svg

@@ -0,0 +1,3 @@
+<svg viewBox="0 0 98 96" width="24" height="24" xmlns="http://www.w3.org/2000/svg">
+  <path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#2088FF"/>
+</svg>

package/src/omarchy/assets/opencode-go.svg

@@ -0,0 +1,3 @@
+<svg viewBox="0 0 24 24" width="24" height="24" xmlns="http://www.w3.org/2000/svg">
+  <path d="M9.4 16.6L4.8 12l4.6-4.6L8 6l-6 6 6 6 1.4-1.4zm5.2 0l4.6-4.6-4.6-4.6L16 6l6 6-6 6-1.4-1.4z" fill="#22D3EE"/>
+</svg>

package/src/omarchy/publish.js

@@ -0,0 +1,152 @@
+/**
+ * Atomic writer for Omarchy agent usage records.
+ *
+ * This is the one place piQuota writes outside its own cache and state
+ * directories, and it is opt-in (`piquota omarchy`). It only ever creates or
+ * removes files named `pi-<family>.json` in Omarchy's usage directory, so
+ * Omarchy's own `claude.json` / `codex.json` records are never touched.
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isPiRecordId, RECORD_PREFIX } from "./record.js";
+
+/**
+ * `PI_QUOTA_OMARCHY_DIR` wins; otherwise Omarchy's own location under
+ * `$XDG_STATE_HOME` (default `~/.local/state`).
+ *
+ * @param {{ env?: Record<string, string | undefined>, home?: string }} [options]
+ * @returns {string}
+ */
+export function resolveOmarchyDir(options = {}) {
+  const env = options.env ?? process.env;
+  if (env.PI_QUOTA_OMARCHY_DIR) return env.PI_QUOTA_OMARCHY_DIR;
+  const state = env.XDG_STATE_HOME || join(options.home ?? homedir(), ".local", "state");
+  return join(state, "omarchy", "agents", "usage");
+}
+
+/**
+ * @param {string} dir
+ * @param {string} id
+ * @param {Record<string, unknown>} record
+ * @returns {string} The final path.
+ */
+function writeRecord(dir, id, record) {
+  const target = join(dir, `${id}.json`);
+  const content = `${JSON.stringify(record)}\n`;
+  if (existsSync(target)) {
+    try {
+      if (readFileSync(target, "utf-8") === content) {
+        return target;
+      }
+    } catch {}
+  }
+  // The temp name does not end in `.json`, so Omarchy's `*.json` watcher never
+  // sees a half-written file.
+  const temp = join(dir, `.${id}.${process.pid}.tmp`);
+  try {
+    writeFileSync(temp, content, { mode: 0o644 });
+    renameSync(temp, target);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    throw error;
+  }
+  return target;
+}
+
+/**
+ * Copy a file only if the target does not exist or its content differs.
+ * This is critical when writing to directories watched by inotify, such as
+ * Omarchy's plugins directory, where redundant writes trigger full shell reloads.
+ *
+ * @param {string} srcPath
+ * @param {string} dstPath
+ * @returns {boolean} Whether the file was written.
+ */
+function copyIfChanged(srcPath, dstPath) {
+  try {
+    if (existsSync(dstPath)) {
+      const srcBuf = readFileSync(srcPath);
+      const dstBuf = readFileSync(dstPath);
+      if (srcBuf.equals(dstBuf)) return false;
+    }
+    copyFileSync(srcPath, dstPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Synchronize provider SVG icons into Omarchy plugin assets directories if present.
+ *
+ * @param {{ env?: Record<string, string | undefined>, home?: string }} [options]
+ * @returns {string[]} Paths of written assets.
+ */
+export function syncOmarchyAssets(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? (env.HOME || homedir());
+  const pluginsDir = join(home, ".config", "omarchy", "plugins");
+  if (!existsSync(pluginsDir)) return [];
+
+  const assetsSrc = fileURLToPath(new URL("assets", import.meta.url));
+  if (!existsSync(assetsSrc)) return [];
+
+  const copied = [];
+  try {
+    for (const plugin of readdirSync(pluginsDir)) {
+      const pluginDir = join(pluginsDir, plugin);
+      const manifestPath = join(pluginDir, "manifest.json");
+      if (!existsSync(manifestPath)) continue;
+      const targetAssetsDir = join(pluginDir, "assets");
+      if (!existsSync(targetAssetsDir)) {
+        mkdirSync(targetAssetsDir, { recursive: true });
+      }
+
+      for (const file of readdirSync(assetsSrc)) {
+        if (!file.endsWith(".svg")) continue;
+        const srcPath = join(assetsSrc, file);
+        const dstPath = join(targetAssetsDir, file);
+        const piDstPath = join(targetAssetsDir, `pi-${file}`);
+        if (copyIfChanged(srcPath, dstPath)) copied.push(dstPath);
+        if (copyIfChanged(srcPath, piDstPath)) copied.push(piDstPath);
+      }
+    }
+  } catch {}
+  return copied;
+}
+
+/**
+ * Write the given records and remove stale `pi-*.json` files whose provider is
+ * no longer present.
+ *
+ * @param {Array<{ id: string, record: Record<string, unknown> }>} records
+ * @param {{ dir?: string, env?: Record<string, string | undefined>, home?: string }} [options]
+ * @returns {{ dir: string, written: string[], removed: string[] }}
+ */
+export function publishRecords(records, options = {}) {
+  const dir = options.dir ?? resolveOmarchyDir(options);
+  mkdirSync(dir, { recursive: true });
+
+  const written = [];
+  for (const { id, record } of records) {
+    if (!isPiRecordId(id)) continue;
+    written.push(writeRecord(dir, id, record));
+  }
+
+  const keep = new Set(records.map(({ id }) => `${id}.json`));
+  const removed = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.startsWith(RECORD_PREFIX) || !name.endsWith(".json")) continue;
+    if (!isPiRecordId(name.slice(0, -".json".length)) || keep.has(name)) continue;
+    rmSync(join(dir, name), { force: true });
+    removed.push(join(dir, name));
+  }
+
+  syncOmarchyAssets(options);
+
+  return { dir, written, removed };
+}