@sigrun/sigrun 0.0.0-stage → 0.1.1

package/dist/harness/stores.js

@@ -0,0 +1,450 @@
+/**
+ * The sigrun store roots (extension config surfaces, spec §3/§4): the
+ * four XDG-respected roots every on-disk surface resolves under —
+ * config, data, cache, state — plus the extension slug function that
+ * names every per-extension surface under them. ONE resolution chain
+ * per root:
+ *
+ * 1. explicit env — `SIGRUN_CONFIG_DIR` / `SIGRUN_DATA_DIR` /
+ *    `SIGRUN_CACHE_DIR` / `SIGRUN_STATE_DIR`, used VERBATIM (never
+ *    suffixed; the deploy sets these to PVC/emptyDir mounts);
+ * 2. `$XDG_CONFIG_HOME` / `$XDG_DATA_HOME` / `$XDG_CACHE_HOME` /
+ *    `$XDG_STATE_HOME` + `/sigrun`, when set and non-empty;
+ * 3. the spec defaults of {@link DEFAULT_STORE_ROOTS} (`~` expanded via
+ *    `homedir()`, the join style of `defaultSettingsDir`).
+ *
+ * The empty-string-falls-through semantics (`undefined` OR `""` counts
+ * as unset) predate this module and hold across the whole chain. The
+ * core config-dir helpers (`defaultConfigDir` in src/cli.ts,
+ * `defaultSettingsDir` in src/harness/settings.ts) delegate to
+ * `resolveStoreRoots` for their configDir — ONE chain everywhere, so
+ * settings/auth/packages/git can never split from the store roots
+ * (spec Decision 3).
+ *
+ * Resolution is CALL-TIME on the `env` PARAMETER (never `process.env`
+ * directly, never cached): tests vary env per call, and boot reads the
+ * live process env once at the boundary. `homedir()` is the one
+ * process-global consulted, exactly as the precedents do.
+ *
+ * The lifecycle half sits below the resolver: `ensureStoreRoots` (the
+ * boot-time mkdir of every root but cache) and `ensureCacheDir` (the
+ * per-call repair of `<cacheDir>/<slug>`). The split is the plan's
+ * Review Focus 5: a wiped cache root (the container `emptyDir` case)
+ * must never break boot — so boot never ensures cache, and every
+ * cache-path consumer recreates it at call time instead.
+ */
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * The tier-3 defaults (spec §4): `~/.config/sigrun`,
+ * `~/.local/share/sigrun`, `~/.cache/sigrun`, `~/.local/state/sigrun`.
+ */
+export const DEFAULT_STORE_ROOTS = {
+    config: ["~/.config", "sigrun"],
+    data: ["~/.local/share", "sigrun"],
+    cache: ["~/.cache", "sigrun"],
+    state: ["~/.local/state", "sigrun"],
+};
+/** The env var names each root's tiers read. */
+const ENV_VARS = {
+    config: { explicit: "SIGRUN_CONFIG_DIR", xdg: "XDG_CONFIG_HOME" },
+    data: { explicit: "SIGRUN_DATA_DIR", xdg: "XDG_DATA_HOME" },
+    cache: { explicit: "SIGRUN_CACHE_DIR", xdg: "XDG_CACHE_HOME" },
+    state: { explicit: "SIGRUN_STATE_DIR", xdg: "XDG_STATE_HOME" },
+};
+/**
+ * Tier 1 — the explicit `SIGRUN_*_DIR` override, VERBATIM (no suffix,
+ * no `~` expansion, no absolutizing: the precedents use it as given).
+ * `undefined` when unset or empty (the unset-adjacent `""` falls
+ * through, exactly like `defaultConfigDir`/`defaultSettingsDir`).
+ */
+function explicitRoot(env, name) {
+    const value = env[name];
+    return value !== undefined && value !== "" ? value : undefined;
+}
+/**
+ * Tier 2 — `$XDG_*_HOME` with the sigrun dir name appended. `undefined`
+ * when unset or empty (the XDG spec's own ""-means-unset reading).
+ */
+function xdgRoot(env, name, dirName) {
+    const value = env[name];
+    return value !== undefined && value !== ""
+        ? join(value, dirName)
+        : undefined;
+}
+/**
+ * Expand a leading `~` against `home`: `~` alone → `home`, `~/rest` →
+ * `home/rest`, anything else unchanged. (Only the fixed
+ * {@link DEFAULT_STORE_ROOTS} constants flow through here — a future
+ * default without the `~` prefix must pass through untouched, not
+ * have its first segment silently swallowed.)
+ */
+function expandHome(path, home) {
+    if (path === "~")
+        return home;
+    if (path.startsWith("~/"))
+        return join(home, path.slice(2));
+    return path;
+}
+/** Tier 3 — the spec default: `~`-expanded base + dir name. */
+function defaultRoot(spec, home) {
+    return join(expandHome(spec[0], home), spec[1]);
+}
+/** The config root's per-extension settings subdirectory (spec §3 map). */
+const SETTINGS_DIR_NAME = "settings";
+/**
+ * `mkdir -p` one path, failing loud with the path and the operation
+ * named when it cannot be created (EACCES/EROFS and friends — the
+ * message carries the root so a mispermissioned deploy points at the
+ * exact directory, not a generic sqlite/npm error from further in).
+ */
+async function ensureDir(path) {
+    try {
+        await mkdir(path, { recursive: true });
+    }
+    catch (error) {
+        throw mkdirFailure(path, error);
+    }
+}
+/** The loud `cannot mkdir` error both ensure paths share (async + sync). */
+function mkdirFailure(path, error) {
+    const { code, message } = error;
+    const detail = code === undefined
+        ? String(error)
+        : `${code}: ${message ?? String(error)}`;
+    return new Error(`sigrun: cannot mkdir ${path} (${detail})`, {
+        cause: error,
+    });
+}
+/**
+ * Ensure the durable store roots exist (spec §6 boot): mkdir recursive
+ * on the config root AND its `settings/` subdirectory (the
+ * per-extension settings files' home), plus the data and state roots.
+ * The CACHE root is deliberately absent from this list — it is
+ * regenerable and wipe-prone (`emptyDir` mounts), so ensuring it at
+ * boot would make a wipe break the NEXT boot's repair story instead;
+ * `ensureCacheDir` owns it, per call.
+ */
+export async function ensureStoreRoots(roots) {
+    await ensureDir(roots.configDir);
+    await ensureDir(join(roots.configDir, SETTINGS_DIR_NAME));
+    await ensureDir(roots.dataDir);
+    await ensureDir(roots.stateDir);
+}
+/**
+ * Ensure and return `<cacheDir>/<slug>` — mkdir -p AT CALL TIME (never
+ * at boot), recreating the cache root itself when it has vanished
+ * since the last call (the wiped-`emptyDir` repair, Review Focus 5).
+ * Idempotent: an existing directory is a no-op. Never touches any
+ * other root — repair is confined to the cache path, and the resolved
+ * path always sits under `roots.cacheDir` (there is no fallback chain;
+ * a missing cache root is recreated, never rerouted under data).
+ *
+ * The mkdir core is synchronous (`ensureCacheDirAt`): the async wrapper
+ * is the call-time contract callers hold, while the sync core serves
+ * the extension-stores handle's `paths.cache` getter — a getter cannot
+ * await, and a fire-and-forget ensure would let a caller stat a path
+ * whose mkdir is still in flight. Same semantics, one implementation.
+ */
+export async function ensureCacheDir(roots, slug) {
+    return ensureCacheDirAt(roots, slug);
+}
+/** The synchronous mkdir core behind {@link ensureCacheDir}. */
+function ensureCacheDirAt(roots, slug) {
+    const dir = join(roots.cacheDir, slug);
+    try {
+        mkdirSync(dir, { recursive: true });
+    }
+    catch (error) {
+        throw mkdirFailure(dir, error);
+    }
+    return dir;
+}
+/**
+ * The extension slug (spec §6 rename rule): the sanitized identity every
+ * sigrun surface keys on — registry name, store sections, seam records,
+ * worker names. The chain, verbatim: take everything after the LAST `/`
+ * (npm scopes `@org/name` and URL-ish git names both collapse to their
+ * last segment — `@a/tool` and `@b/tool` share a slug by design), strip a
+ * trailing `@version` suffix (defensive; manifest names cannot carry
+ * one), lowercase, fold `[^a-z0-9_-]+` runs to a single `-`, trim edge
+ * `-`/`_`. An empty result is the CALLER's rejection — the loader fails
+ * the load naming the declared name (Review Focus 2); this function
+ * itself just returns "" for names nothing survives.
+ */
+export function slugifyName(declared) {
+    const segment = declared.slice(declared.lastIndexOf("/") + 1);
+    const versionAt = segment.lastIndexOf("@");
+    const unversioned = versionAt === -1 ? segment : segment.slice(0, versionAt);
+    return unversioned
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^[-_]+|[-_]+$/g, "");
+}
+/**
+ * Resolve all four store roots from `env` (spec §4's one chain, applied
+ * per root). Pure over the argument; call it wherever the roots are
+ * needed — nothing is cached, so tests and boot share the same path.
+ */
+export function resolveStoreRoots(env) {
+    const home = homedir();
+    const one = (kind) => {
+        const { explicit, xdg } = ENV_VARS[kind];
+        const spec = DEFAULT_STORE_ROOTS[kind];
+        return (explicitRoot(env, explicit) ??
+            xdgRoot(env, xdg, spec[1]) ??
+            defaultRoot(spec, home));
+    };
+    return {
+        configDir: one("config"),
+        dataDir: one("data"),
+        cacheDir: one("cache"),
+        stateDir: one("state"),
+    };
+}
+/**
+ * The extension store classes + the secret precedence resolver (spec
+ * §3's server-mediated surfaces): extension code NEVER touches these
+ * files directly — it asks the server, which is the single writer.
+ * Every write goes through {@link writeFileAtomic}, so a crash or a
+ * concurrent reader can only ever see the old complete file or the new
+ * complete file, never a half-written one.
+ */
+/**
+ * Atomic file replace: stage `data` to a fresh temp file in the SAME
+ * directory as `path` (rename is same-filesystem atomic), stamp the
+ * final `mode` on the temp BEFORE the rename (a chmod after the rename
+ * would leave a window at the wrong permissions on secrets; `chmod`
+ * beats `writeFile`'s `mode` option here because the latter is masked
+ * by umask), then `rename` over the target. On failure the staged temp
+ * is best-effort removed and the error rethrown — the target keeps its
+ * old bytes.
+ */
+export async function writeFileAtomic(path, data, mode) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, data, { mode });
+        await chmod(temp, mode);
+        await rename(temp, path);
+    }
+    catch (error) {
+        await rm(temp, { force: true }).catch(() => { });
+        throw error;
+    }
+}
+/** Serialize a JSON value the house way (tabs, trailing newline). */
+function serializeJson(value) {
+    return `${JSON.stringify(value, null, "\t")}\n`;
+}
+/**
+ * Read one JSON-object file. Absent (`ENOENT`) → `{}` — first use is
+ * not an error for either store. Every OTHER failure mode is loud:
+ * unparseable JSON, or JSON that is not an object (an array/scalar
+ * file is malformed for a map-shaped surface). The error names the
+ * path — a corrupt `secrets.json` must stop the show pointing at the
+ * file, never be silently reset to `{}` by the next write.
+ */
+async function readJsonObject(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`sigrun: malformed JSON in ${path}: ${String(error)}`, { cause: error });
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`sigrun: malformed JSON in ${path}: expected an object, got ${Array.isArray(parsed) ? "an array" : typeof parsed}`);
+    }
+    return parsed;
+}
+/** An object-shaped value check (sections are always written objects). */
+function isPlainObject(value) {
+    return (typeof value === "object" && value !== null && !Array.isArray(value));
+}
+/**
+ * The secrets store (spec §3): ONE `secrets.json` at the config root,
+ * keyed by extension slug — whole-file read-modify-write, atomic,
+ * `0600`. The server (the API-mediated secret endpoints) is the only
+ * writer; extension code reads through `resolveSecretFor`.
+ */
+export class SecretsStore {
+    secretsPath;
+    constructor(secretsPath) {
+        this.secretsPath = secretsPath;
+    }
+    /** One extension's secret section; absent section → `{}`. */
+    async readSection(slug) {
+        const section = (await readJsonObject(this.secretsPath))[slug];
+        return isPlainObject(section) ? section : {};
+    }
+    /**
+     * Set one extension's section, preserving every sibling section
+     * (read-modify-write of the whole map). Loud on a malformed file —
+     * never a silent reset.
+     */
+    async writeSection(slug, section) {
+        const all = await readJsonObject(this.secretsPath);
+        all[slug] = section;
+        await writeFileAtomic(this.secretsPath, serializeJson(all), 0o600);
+    }
+}
+/**
+ * The per-extension settings store (spec §3): one JSON file per slug
+ * under `<configDir>/settings/`, contents entirely the extension's
+ * shape. Absent → `{}`; atomic `0644` writes (settings are not
+ * secrets — world-unreadable is not required, group/other-readable
+ * is acceptable).
+ */
+export class ExtensionSettingsStore {
+    settingsDir;
+    constructor(settingsDir) {
+        this.settingsDir = settingsDir;
+    }
+    pathFor(slug) {
+        return join(this.settingsDir, `${slug}.json`);
+    }
+    /** One extension's settings object; absent file → `{}`. */
+    async read(slug) {
+        return readJsonObject(this.pathFor(slug));
+    }
+    /** Replace one extension's settings file atomically. */
+    async write(slug, value) {
+        await writeFileAtomic(this.pathFor(slug), serializeJson(value), 0o644);
+    }
+}
+/** The env prefix every extension secret's fallback var carries. */
+const SECRET_ENV_PREFIX = "SIGRUN_EXT_";
+/** slug/key → `SIGRUN_EXT_<SLUG-SNAKE>_<KEY-SNAKE>` (upper, `-`→`_`). */
+function secretEnvName(slug, key) {
+    const snake = (part) => part.toUpperCase().replace(/-/g, "_");
+    return `${SECRET_ENV_PREFIX}${snake(slug)}_${snake(key)}`;
+}
+/**
+ * Resolve one secret for one extension (spec §4 precedence): the
+ * STORED section wins when it has the key; else the env var
+ * `SIGRUN_EXT_<SLUG>_<KEY>`; else undefined. Pure over its arguments —
+ * it NEVER writes env values down (Review Focus 4: env-only
+ * resolution must leave the file byte-identical; the write path is
+ * the API alone). Takes the SECTION object (the caller just did
+ * `readSection`), not a store instance. An empty-string env var
+ * counts as unset — the same ""-means-unset reading this module's dir
+ * tiers use.
+ */
+export function resolveSecretFor(slug, section, key, env) {
+    const stored = section[key];
+    if (stored !== undefined && stored !== null) {
+        return { value: String(stored), source: "stored" };
+    }
+    const fromEnv = env[secretEnvName(slug, key)];
+    return fromEnv !== undefined && fromEnv !== ""
+        ? { value: fromEnv, source: "env" }
+        : undefined;
+}
+/** The `secrets.json` file name at the config root (spec §3 map). */
+const SECRETS_FILE_NAME = "secrets.json";
+/** Build the shared trio from resolved roots (cheap, no I/O). */
+export function sharedExtensionStores(roots, env = {}) {
+    const settings = new ExtensionSettingsStore(join(roots.configDir, SETTINGS_DIR_NAME));
+    const secrets = new SecretsStore(join(roots.configDir, SECRETS_FILE_NAME));
+    return {
+        secrets,
+        settings,
+        roots,
+        settingsFor: (slug) => ({
+            get: () => settings.read(slug),
+            set: (value) => settings.write(slug, value),
+        }),
+        secretKeys: async (slug) => {
+            // Stored keys first (the resolver's winning source), then the
+            // `SIGRUN_EXT_<SLUG>_`-prefixed env fallbacks that are not stored.
+            // A stored key with an env twin lists ONCE as stored — exactly
+            // `resolveSecretFor`'s precedence, never two entries for one key.
+            const section = await secrets.readSection(slug);
+            const keys = Object.keys(section).map((key) => ({
+                key,
+                source: "stored",
+            }));
+            const prefix = `${SECRET_ENV_PREFIX}${slug
+                .toUpperCase()
+                .replace(/-/g, "_")}_`;
+            for (const name of Object.keys(env)) {
+                if (!name.startsWith(prefix))
+                    continue;
+                // The resolver's ""-means-unset reading applies to the listing
+                // too: an empty env var is no secret at all.
+                if (env[name] === undefined || env[name] === "")
+                    continue;
+                // The inverse of `secretEnvName`'s key map (upper, `-`→`_`):
+                // lower, `_`→`-` — kebab keys round-trip exactly; a snake key
+                // still forward-resolves (both map to the same env name).
+                const key = name.slice(prefix.length).toLowerCase().replace(/_/g, "-");
+                if (key === "" || section[key] !== undefined)
+                    continue;
+                keys.push({ key, source: "env" });
+            }
+            return keys;
+        },
+        setSecret: async (slug, key, value) => {
+            const section = await secrets.readSection(slug);
+            section[key] = value;
+            await secrets.writeSection(slug, section);
+        },
+        deleteSecret: async (slug, key) => {
+            const section = await secrets.readSection(slug);
+            if (section[key] === undefined)
+                return;
+            delete section[key];
+            await secrets.writeSection(slug, section);
+        },
+    };
+}
+/**
+ * Build ONE extension's scoped view over the shared trio — the object
+ * the factory host exposes as `stores`. All cheap closure wiring (no
+ * I/O at construction): reads/writes ride the shared classes keyed by
+ * `slug`, paths are joins, and the cache dir is created only when
+ * `paths.cache` is actually read. The seam host REBUILDS this view on
+ * `rekey` (the two-phase identity pattern) so the view always keys on
+ * the host's CURRENT slug.
+ */
+export function scopedExtensionStores(shared, slug) {
+    return {
+        secrets: {
+            async get(key) {
+                const section = await shared.secrets.readSection(slug);
+                const value = section[key];
+                return value === undefined || value === null
+                    ? undefined
+                    : String(value);
+            },
+            async set(key, value) {
+                const section = await shared.secrets.readSection(slug);
+                section[key] = value;
+                await shared.secrets.writeSection(slug, section);
+            },
+        },
+        settings: {
+            get: () => shared.settings.read(slug),
+            set: (value) => shared.settings.write(slug, value),
+        },
+        paths: {
+            data: join(shared.roots.dataDir, slug),
+            state: join(shared.roots.stateDir, slug),
+            get cache() {
+                return ensureCacheDirAt(shared.roots, slug);
+            },
+        },
+    };
+}