@sigrun/sigrun 0.0.0-stage → 0.1.0

package/dist/harness/ambient.js

@@ -0,0 +1,261 @@
+/**
+ * The ambient seam (spec: docs/approval-ux-seams.md, "Ambient surfaces"):
+ * core-owned, channel-neutral records for persistent read-mostly state —
+ * statusline slots and panel widgets — written by extensions through the
+ * host context and rendered by channels generically.
+ *
+ * SPLIT (build-and-webui Task 1): the canonical TYPE declarations live in
+ * the `@sigrun/shared` package (`shared/src/ambient.ts` — the records ride
+ * the §5 wire as-is, so the shapes ARE the channel contract); this module
+ * owns the docs, validation, and registry RUNTIME, importing the types
+ * (type-only — no runtime dependency on the built package).
+ *
+ * Lifecycle difference from interactions: an ambient surface is replaced
+ * repeatedly (write = FULL state replacement, never a delta) and never
+ * blocks. One slot key is owned by exactly one extension (allocation,
+ * not silent composition — the pi-zentui chrome-skin lesson).
+ *
+ * Layering mirrors the interaction seam: strict envelope (key, place,
+ * budget, refresh, expires) around a body composed only from the closed
+ * ambient primitives (line, rows, gauge, ledger), with opaque `details`.
+ */
+import { defineDoc, defineDocFamily } from "@earendil-works/pi-durable";
+/**
+ * The ambient record family: one record per surface key, per conversation.
+ * (Session-scoped statuslines that outlive one conversation are a v2
+ * concern; channels today render conversation-scoped state.)
+ */
+export const AmbientDoc = defineDocFamily({
+    kind: "sigrun.ambient",
+    version: 1,
+    scope: "conversation",
+    history: "latest",
+    fork: "current",
+    family: true,
+    initial: (key) => ({
+        key,
+        owner: "",
+        place: "status",
+        expires: "never",
+        updatedAt: 0,
+    }),
+});
+export const AmbientOwnersDoc = defineDoc({
+    kind: "sigrun.ambient.owners",
+    version: 1,
+    scope: "session",
+    initial: () => ({ owners: {} }),
+});
+const PLACES = new Set(["status", "footer", "panel"]);
+const OVERFLOWS = new Set(["drop", "wrap", "summarize"]);
+const FORMATS = new Set(["compact", "usd", "percent"]);
+const ZONES = new Set(["left", "middle", "right"]);
+/** Structural validation of one ambient record. Returns the error text or null. */
+export function validateAmbient(value) {
+    if (typeof value !== "object" || value === null) {
+        return "ambient record must be an object";
+    }
+    const r = value;
+    if (typeof r.key !== "string" || r.key.length === 0) {
+        return "key must be a non-empty string";
+    }
+    if (typeof r.place !== "string" || !PLACES.has(r.place)) {
+        return `place must be one of status|footer|panel (got ${String(r.place)})`;
+    }
+    if (r.maxRows !== undefined && typeof r.maxRows !== "number") {
+        return "maxRows must be a number";
+    }
+    if (r.overflow !== undefined && !OVERFLOWS.has(String(r.overflow))) {
+        return `overflow must be one of drop|wrap|summarize (got ${String(r.overflow)})`;
+    }
+    if (r.refreshMs !== undefined && typeof r.refreshMs !== "number") {
+        return "refreshMs must be a number";
+    }
+    if (r.expires !== "never" && r.expires !== "idle") {
+        return `expires must be "never" or "idle" (got ${String(r.expires)})`;
+    }
+    if (typeof r.updatedAt !== "number") {
+        return "updatedAt must be a number";
+    }
+    const body = r.body;
+    if (body === undefined)
+        return null; // an empty write clears the surface
+    if (typeof body !== "object" || body === null) {
+        return "body must be an object";
+    }
+    const b = body;
+    const known = new Set(["line", "rows", "gauge", "ledger"]);
+    const unknownKey = Object.keys(b).find((k) => !known.has(k));
+    if (unknownKey !== undefined) {
+        return `body.${unknownKey} is outside the closed primitives (move it to details)`;
+    }
+    if (b.line !== undefined) {
+        const problem = validateLine(b.line);
+        if (problem !== null)
+            return problem;
+    }
+    if (b.rows !== undefined) {
+        if (!Array.isArray(b.rows))
+            return "body.rows must be an array";
+        for (const row of b.rows) {
+            const problem = validateRow(row);
+            if (problem !== null)
+                return problem;
+        }
+    }
+    if (b.gauge !== undefined) {
+        const problem = validateGauge(b.gauge);
+        if (problem !== null)
+            return problem;
+    }
+    if (b.ledger !== undefined) {
+        if (!Array.isArray(b.ledger))
+            return "body.ledger must be an array";
+        for (const e of b.ledger) {
+            const problem = validateLedgerEntry(e);
+            if (problem !== null)
+                return problem;
+        }
+    }
+    return null;
+}
+function validateLine(value) {
+    if (typeof value !== "object" || value === null)
+        return "line must be an object";
+    const l = value;
+    if (l.text === undefined && l.segments === undefined) {
+        return "line needs text or segments";
+    }
+    if (l.text !== undefined && typeof l.text !== "string") {
+        return "line.text must be a string";
+    }
+    if (l.segments !== undefined) {
+        if (!Array.isArray(l.segments))
+            return "line.segments must be an array";
+        for (const s of l.segments) {
+            if (typeof s !== "object" || s === null)
+                return "segment must be an object";
+            const seg = s;
+            if (typeof seg.id !== "string" || seg.id.length === 0) {
+                return "segment.id must be a non-empty string";
+            }
+            if (typeof seg.text !== "string")
+                return "segment.text must be a string";
+            if (seg.place !== undefined && !ZONES.has(String(seg.place))) {
+                return `segment.place must be one of left|middle|right (got ${String(seg.place)})`;
+            }
+        }
+    }
+    return null;
+}
+function validateRow(value) {
+    if (typeof value !== "object" || value === null)
+        return "row must be an object";
+    const r = value;
+    if (typeof r.id !== "string" || r.id.length === 0) {
+        return "row.id must be a non-empty string";
+    }
+    if (typeof r.label !== "string")
+        return "row.label must be a string";
+    if (r.status !== undefined && typeof r.status !== "string") {
+        return "row.status must be a string";
+    }
+    if (r.severity !== undefined &&
+        r.severity !== 0 &&
+        r.severity !== 1 &&
+        r.severity !== 2) {
+        return "row.severity must be 0, 1, or 2";
+    }
+    if (r.quiet !== undefined && typeof r.quiet !== "boolean") {
+        return "row.quiet must be a boolean";
+    }
+    if (r.detail !== undefined && typeof r.detail !== "string") {
+        return "row.detail must be a string";
+    }
+    if (r.depth !== undefined && typeof r.depth !== "number") {
+        return "row.depth must be a number";
+    }
+    if (r.deps !== undefined && !Array.isArray(r.deps)) {
+        return "row.deps must be an array of ids";
+    }
+    if (Array.isArray(r.deps) && r.deps.some((d) => typeof d !== "string")) {
+        return "row.deps must be an array of ids";
+    }
+    if (r.spinnerLabel !== undefined && typeof r.spinnerLabel !== "string") {
+        return "row.spinnerLabel must be a string";
+    }
+    if (r.metrics !== undefined) {
+        const problem = validateMetrics(r.metrics);
+        if (problem !== null)
+            return problem;
+    }
+    return null;
+}
+function validateMetrics(value) {
+    if (typeof value !== "object" || value === null)
+        return "metrics must be an object";
+    const m = value;
+    for (const k of ["tokens", "cost", "current", "total", "completed"]) {
+        if (m[k] !== undefined && typeof m[k] !== "number") {
+            return `metrics.${k} must be a number`;
+        }
+    }
+    if (m.format !== undefined && !FORMATS.has(String(m.format))) {
+        return `metrics.format must be one of compact|usd|percent (got ${String(m.format)})`;
+    }
+    return null;
+}
+function validateGauge(value) {
+    if (typeof value !== "object" || value === null)
+        return "gauge must be an object";
+    const g = value;
+    if (typeof g.label !== "string")
+        return "gauge.label must be a string";
+    if (g.percent !== undefined && typeof g.percent !== "number") {
+        return "gauge.percent must be a number";
+    }
+    if (g.phase !== undefined && typeof g.phase !== "string") {
+        return "gauge.phase must be a string";
+    }
+    if (g.elapsedMs !== undefined && typeof g.elapsedMs !== "number") {
+        return "gauge.elapsedMs must be a number";
+    }
+    if (g.recentOutput !== undefined && !Array.isArray(g.recentOutput)) {
+        return "gauge.recentOutput must be an array of strings";
+    }
+    if (Array.isArray(g.recentOutput) && g.recentOutput.some((l) => typeof l !== "string")) {
+        return "gauge.recentOutput must be an array of strings";
+    }
+    if (g.checks !== undefined && !Array.isArray(g.checks)) {
+        return "gauge.checks must be row-shaped";
+    }
+    if (Array.isArray(g.checks)) {
+        for (const row of g.checks) {
+            const problem = validateRow(row);
+            if (problem !== null)
+                return `gauge.checks: ${problem}`;
+        }
+    }
+    return null;
+}
+function validateLedgerEntry(value) {
+    if (typeof value !== "object" || value === null)
+        return "ledger entry must be an object";
+    const e = value;
+    if (typeof e.id !== "string" || e.id.length === 0) {
+        return "ledger.id must be a non-empty string";
+    }
+    if (typeof e.at !== "number")
+        return "ledger.at must be a number";
+    if (typeof e.kind !== "string")
+        return "ledger.kind must be a string";
+    if (typeof e.summary !== "string")
+        return "ledger.summary must be a string";
+    if (e.detail !== undefined && !Array.isArray(e.detail)) {
+        return "ledger.detail must be an array of strings";
+    }
+    if (Array.isArray(e.detail) && e.detail.some((d) => typeof d !== "string")) {
+        return "ledger.detail must be an array of strings";
+    }
+    return null;
+}

package/dist/harness/auth.js

@@ -0,0 +1,130 @@
+/**
+ * The auth store (the 2026-10-13 config-surface ruling): a pi-style
+ * credentials file at `<config-dir>/auth.json` — the same directory the
+ * settings store lives in (`SIGRUN_CONFIG_DIR` / `~/.config/sigrun`).
+ *
+ * Shape: `{ "<provider>": { "apiKey": "..." } }`, one entry per provider
+ * id, plus the magic key `"default"` naming the DEFAULT provider's key —
+ * so a deployment that does not know the resolved provider id up front
+ * can still hand the env-driven OpenAI-compatible provider its key.
+ *
+ * The file is created with mode 0o600 (owner-only) whenever a write
+ * happens. Key material is NEVER logged or echoed: validation errors
+ * name the key path, never the value; callers must not interpolate
+ * resolved keys into messages.
+ *
+ * Absent file = no stored keys (the `OPENAI_API_KEY` env fallback still
+ * applies). A malformed file (bad JSON, non-object, a key present but not
+ * a non-empty string) fails loud on read, like a bad `SIGRUN_*` value.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { defaultSettingsDir } from "./settings.js";
+import { writeFileAtomic } from "./stores.js";
+/** The magic provider key meaning "the resolved default provider's key". */
+export const DEFAULT_AUTH_KEY = "default";
+/** Default file path: `<dir>/auth.json`. */
+export function authPath(dir) {
+    return join(dir, "auth.json");
+}
+/** A field-level validation error; names the key path, never the value. */
+export class AuthValidationError extends Error {
+    field;
+    constructor(field, reason) {
+        super(`auth: ${field} ${reason}`);
+        this.field = field;
+    }
+}
+/**
+ * A file-backed auth store. Reads are fresh per call (same discipline as
+ * the settings store). The store is permissive about unknown fields inside
+ * an entry (future auth kinds — token refresh, base-url pins — may add
+ * some) but strict about `apiKey`: when present it must be a non-empty
+ * string.
+ */
+export class AuthStore {
+    path;
+    constructor(options = {}) {
+        this.path = authPath(options.dir ?? defaultSettingsDir());
+    }
+    /** The current auth file; absent file = `{}` (no stored keys). */
+    read() {
+        if (!existsSync(this.path))
+            return {};
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.path, "utf8"));
+        }
+        catch (cause) {
+            throw new Error(`auth: ${this.path} is not valid JSON (${cause instanceof Error ? cause.message : String(cause)})`);
+        }
+        if (typeof parsed !== "object" ||
+            parsed === null ||
+            Array.isArray(parsed)) {
+            throw new Error(`auth: ${this.path} must contain a JSON object`);
+        }
+        const file = parsed;
+        for (const [provider, entry] of Object.entries(file)) {
+            if (typeof entry !== "object" ||
+                entry === null ||
+                Array.isArray(entry)) {
+                throw new AuthValidationError(provider, "must be an object");
+            }
+            const apiKey = entry.apiKey;
+            if (apiKey !== undefined &&
+                (typeof apiKey !== "string" || apiKey === "")) {
+                throw new AuthValidationError(`${provider}.apiKey`, "must be a non-empty string");
+            }
+        }
+        return file;
+    }
+    /**
+     * Persist `file` wholesale, creating the file mode 0o600 (owner-only —
+     * the file carries key material). An existing file is chmod'd to
+     * 0o600 as well: a hand-created world-readable auth file is tightened
+     * on the first write.
+     */
+    write(file) {
+        mkdirSync(dirname(this.path), { recursive: true });
+        writeFileSync(this.path, `${JSON.stringify(file, null, "\t")}\n`, {
+            mode: 0o600,
+        });
+    }
+    /**
+     * Set one key's api key (core hardening W3 Task 6, spec §7.6): the
+     * server's credential ROUTE writes through this — read-modify-write
+     * over the current file (other entries untouched), staged through
+     * {@link writeFileAtomic} at 0600 so a crash or concurrent reader only
+     * ever sees the old or new complete file. `key` is the auth.json
+     * provider key (`<id>`, or the magic `"default"` for the default
+     * model's provider); `apiKey` must be a non-empty string — anything
+     * else is refused HERE rather than written as a file the store's own
+     * `read()` would reject. The pi-ai bridge stays read-only; this method
+     * is the server's single write seam.
+     */
+    async setApiKey(key, apiKey) {
+        if (typeof apiKey !== "string" || apiKey === "") {
+            throw new AuthValidationError(`${key}.apiKey`, "must be a non-empty string");
+        }
+        const file = { ...this.read() };
+        file[key] = { ...file[key], apiKey };
+        await mkdir(dirname(this.path), { recursive: true });
+        await writeFileAtomic(this.path, `${JSON.stringify(file, null, "\t")}\n`, 0o600);
+    }
+    /**
+     * Remove one key's entry entirely (spec §7.6: "DELETE removes the
+     * entry") — atomic and 0600 like every write. Idempotent: an absent
+     * key writes nothing (DELETE of a never-set credential is a no-op,
+     * not an error).
+     */
+    async deleteApiKey(key) {
+        const file = this.read();
+        if (file[key] === undefined)
+            return;
+        const next = { ...file };
+        delete next[key];
+        await mkdir(dirname(this.path), { recursive: true });
+        await writeFileAtomic(this.path, `${JSON.stringify(next, null, "\t")}\n`, 0o600);
+    }
+}