@sema-ai/registry-core 0.10.3

package/dist/file-edit.js

@@ -0,0 +1,126 @@
+/**
+ * TOC editor helpers — the read/write/VALIDATE surface the desktop/CLI builds its OWN config UX on top of
+ * (Clay's decision: only the LIB is shared, the TOC builds its own UI). These expose write/validate, not just
+ * read, so a single-machine consumer never needs the server's routes.
+ *
+ * Validation uses the SAME zod schemas as the server's parseDomain → identical rules on both sides.
+ */
+import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { collectEnvRefs } from "./secret-refs.js";
+import { RemoteExecSpec } from "./remote-exec.js";
+import { parseDomain, sanitizeZodError } from "./config-fns.js";
+import { DOMAIN_SCHEMAS, isDomainName } from "./types.js";
+/** Throw a CLEAR error for a non-domain key instead of the cryptic `undefined.parse(...)` you'd get from
+ *  `DOMAIN_SCHEMAS[badKey]`. The classic trip-wire: a consumer scans `config.d/*.json` and feeds every file
+ *  (incl. the non-domain `remote-exec.json`) into writeBundle/writeDomainFile. `remote-exec` is the exec
+ *  backend, NOT a domain — write it via writeRemoteExec. Filter arbitrary keys with `isDomainName` first. */
+function assertDomainName(domain) {
+    if (!isDomainName(domain)) {
+        const hint = domain === "remote-exec" ? " — the exec backend is NOT a domain; use writeRemoteExec (config.d/remote-exec.json)" : "";
+        throw new Error(`"${domain}" is not a config domain (expected one of: ${DOMAINS_LIST})${hint}`);
+    }
+}
+const DOMAINS_LIST = Object.keys(DOMAIN_SCHEMAS).join(", ");
+// Monotonic suffix so concurrent same-domain atomic writes in one process+ms can't collide on the tmp name.
+let tmpSeq = 0;
+/** VALIDATE a domain payload against its zod schema WITHOUT writing — the editor's "is this form valid?" check.
+ *  Returns the parsed+defaulted value or the zod issues. Identical rules to the server's parseDomain. Throws
+ *  (clear message) if `domain` is not a real domain name (a misuse, not invalid user data). */
+export function validateDomain(domain, raw) {
+    assertDomainName(domain);
+    let r;
+    try {
+        r = DOMAIN_SCHEMAS[domain].safeParse(raw === undefined ? {} : raw); // explicit null is corrupt, not defaults (R4)
+    }
+    catch {
+        // a hostile getter/Proxy trap threw during traversal — never surface its (secret-bearing) message. R13 (codex).
+        return { ok: false, issues: [{ code: "custom", message: `invalid "${domain}" config (a value could not be read during validation)`, path: [] }] };
+    }
+    if (r.success)
+        return { ok: true, value: r.data };
+    return { ok: false, issues: sanitizeZodError(r.error).issues }; // recursive redaction (R13/R14) — no secret echo
+}
+/** Same, for the remote-exec contract (a standalone contract, not a DOMAIN_SCHEMAS member). */
+export function validateRemoteExec(raw) {
+    let r;
+    try {
+        r = RemoteExecSpec.safeParse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ code: "custom", message: "invalid remoteExec (a value could not be read during validation)", path: [] }] };
+    }
+    return r.success ? { ok: true, value: r.data } : { ok: false, issues: sanitizeZodError(r.error).issues }; // no secret echo (R14)
+}
+/** Absolute path to a domain's JSON file under a config root (mirrors FileConfigStore.domainPath). Guards the
+ *  name (no `../../secret` traversal even if a caller bypasses the DomainName type). */
+export function domainFilePath(root, domain) {
+    assertDomainName(domain);
+    return path.join(root, "config.d", `${domain}.json`);
+}
+/** WRITE a domain file ATOMICALLY (write a tmp in the same dir → rename) so a crash never leaves a half-written
+ *  config.d/<domain>.json. VALIDATES first (throws on invalid — never persists garbage); persists the parsed +
+ *  defaulted value so the file is canonical. */
+export async function writeDomainFile(root, domain, value) {
+    assertDomainName(domain); // a stray non-domain key (e.g. "remote-exec" from a config.d scan) fails LOUD + clear
+    const parsed = parseDomain(domain, value); // routes through the SANITIZED parser (explicit-null reject R4 + no secret echo R14)
+    const dir = path.join(root, "config.d");
+    await mkdir(dir, { recursive: true });
+    const dest = path.join(dir, `${domain}.json`);
+    const tmp = path.join(dir, `.${domain}.json.${process.pid}.${Date.now()}.${tmpSeq++}.tmp`);
+    try {
+        await writeFile(tmp, JSON.stringify(parsed, null, 2) + "\n", "utf8");
+        await rename(tmp, dest);
+    }
+    catch (e) {
+        await unlink(tmp).catch(() => { }); // never leave a half-written tmp behind on a write/rename failure
+        throw e;
+    }
+    return parsed;
+}
+/** LIST every env-NAME the current local config requires (across models/workers/mcp + the
+ *  remote-exec backend), marking which are MISSING from the resolved env — the TOC "you still need to set
+ *  these secrets" panel. Reuses collectEnvRefs for the domain side, then appends the remoteExec secret refs. */
+export function listRequiredEnvNames(eff, remoteExec, resolvedEnv) {
+    const map = new Map();
+    const add = (envName, domain, detail) => {
+        if (!envName)
+            return;
+        const list = map.get(envName) ?? [];
+        list.push({ domain, detail });
+        map.set(envName, list);
+    };
+    for (const r of collectEnvRefs(eff))
+        for (const use of r.refs)
+            add(r.envName, use.domain, use.detail);
+    if (remoteExec) {
+        const re = remoteExec;
+        if (re.provider === "e2b") {
+            add(re.apiKeyEnv, "remoteExec", "e2b.apiKeyEnv");
+            for (const e of re.sandboxEnv ?? [])
+                add(e, "remoteExec", "e2b.sandboxEnv[]");
+        }
+        else if (re.provider === "k8s") {
+            add(re.tokenEnv, "remoteExec", "k8s.tokenEnv");
+            add(re.caCertEnv, "remoteExec", "k8s.caCertEnv");
+            if (re.s3Snapshot) {
+                add(re.s3Snapshot.accessKeyEnv, "remoteExec", "k8s.s3Snapshot.accessKeyEnv");
+                add(re.s3Snapshot.secretKeyEnv, "remoteExec", "k8s.s3Snapshot.secretKeyEnv");
+            }
+        }
+        else if (re.provider === "ssh") {
+            add(re.privateKeyEnv, "remoteExec", "ssh.privateKeyEnv");
+        }
+        else if (re.provider === "remote-docker") {
+            add(re.tlsCertEnv, "remoteExec", "remote-docker.tlsCertEnv");
+            add(re.tlsKeyEnv, "remoteExec", "remote-docker.tlsKeyEnv");
+            add(re.tlsCaEnv, "remoteExec", "remote-docker.tlsCaEnv");
+            add(re.sshKeyEnv, "remoteExec", "remote-docker.sshKeyEnv");
+        }
+        // adb / host / local-docker carry no secret env-NAME refs.
+    }
+    return [...map.entries()]
+        .map(([envName, refs]) => ({ envName, refs, present: resolvedEnv[envName] !== undefined }))
+        .sort((a, b) => a.envName.localeCompare(b.envName));
+}
+//# sourceMappingURL=file-edit.js.map

package/dist/file-edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-edit.js","sourceRoot":"","sources":["../src/file-edit.ts"],"names":[],"mappings":"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"}

package/dist/file-store.d.ts

@@ -0,0 +1,39 @@
+import { type EffectiveReadWarning } from "./config-fns.js";
+import type { ConfigReader } from "./reader.js";
+import { type DomainConfig, type DomainName, type EffectiveConfig } from "./types.js";
+/** The domains a single-machine TOC carries (fleet-only workers/hosts/systems omitted — they default empty).
+ *  `projects` (0.10.0) is ALSO deliberately excluded: the ledger is TENANT IDENTITY DATA, not portable
+ *  config — bundling it into another deployment would copy identity registrations out of thin air (the
+ *  design/142 §1.4 threat-model-① "carried-in foreign projectId" in import clothing). Export/带走 goes
+ *  through the 142 §5 export face (service half), never the config bundle. */
+export declare const PORTABLE_DOMAINS: readonly ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "runtime", "governance", "execution"];
+export type PortableDomain = (typeof PORTABLE_DOMAINS)[number];
+export declare class FileConfigStore implements ConfigReader {
+    #private;
+    private readonly root;
+    private readonly opts;
+    /** `opts.onWarning` (0.8.1): receives buildEffective's read-degradation warnings (grandfathered hosts /
+     *  domain defaulted — see {@link EffectiveReadWarning}) so a TOC shell can surface them; omit = resilient
+     *  but silent. Additive — existing `new FileConfigStore(root)` callers are unchanged. */
+    constructor(root: string, opts?: {
+        onWarning?: (w: EffectiveReadWarning) => void;
+    });
+    /** Absolute path to a domain's JSON file. Guards the name (defence in depth — a non-domain string like
+     *  `../../secret` must never be joined into a filesystem path, even if a caller bypasses the type). */
+    domainPath(domain: DomainName): string;
+    /** Read+parse one domain (validated, defaults filled), or `undefined` if the domain is ABSENT — matching
+     *  the {@link ConfigReader} contract (reader.ts: absent domain → undefined) and the server stores'
+     *  `has(domain) ? parse : undefined`. A present-but-empty file (`{}` / whitespace) IS a set domain → parsed
+     *  with defaults; a missing file is absence → undefined. (getEffective still fills defaults for absent
+     *  domains; getDomain is the per-domain "was this ever set?" probe.) */
+    getDomain<K extends DomainName>(domain: K): Promise<DomainConfig[K] | undefined>;
+    /** All portable domains → EffectiveConfig. The PAYLOAD and its `version` come from ONE raws snapshot (no
+     *  re-read between them — else a concurrent atomic rename could pair payload A with version B and a consumer
+     *  would skip the change). `updatedAt` = max file mtime (informational; the content-hash version is the
+     *  authoritative change-detector). */
+    getEffective(): Promise<EffectiveConfig>;
+    /** Stable version number for the current files: same files ⇒ same number ⇒ a consumer's "skip re-apply if
+     *  version unchanged" works locally too. */
+    getVersion(): Promise<number>;
+}
+//# sourceMappingURL=file-store.d.ts.map

package/dist/file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"AAuBA,OAAO,EAA+B,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAgB,KAAK,YAAY,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAEpG;;;;8EAI8E;AAC9E,eAAO,MAAM,gBAAgB,yHAA0J,CAAC;AACxL,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,qBAAa,eAAgB,YAAW,YAAY;;IAKhD,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IALvB;;6FAEyF;gBAEtE,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;QAAE,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,oBAAoB,KAAK,IAAI,CAAA;KAAO;IAG/E;2GACuG;IACvG,UAAU,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM;IAiEtC;;;;4EAIwE;IAClE,SAAS,CAAC,CAAC,SAAS,UAAU,EAAE,MAAM,EAAE,CAAC,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC;IAWtF;;;0CAGsC;IAChC,YAAY,IAAI,OAAO,CAAC,eAAe,CAAC;IAM9C;gDAC4C;IACtC,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;CAGpC"}

package/dist/file-store.js

@@ -0,0 +1,142 @@
+/**
+ * FileConfigStore — a local, single-machine config source for the TOC desktop/CLI. Reads the PORTABLE domains
+ * from `<root>/config.d/<domain>.json` (one file per domain, each = exactly that domain's zod object) and
+ * resolves them into an {@link EffectiveConfig} via the SAME pure `buildEffective`/`parseDomain` the server
+ * stores use. Implements ONLY the narrow {@link ConfigReader} (3 methods) — no publish/RBAC/worker-status.
+ *
+ * LOCAL FILE LAYOUT (the TOC owns the root, e.g. `~/.ai-agent/` or a project-local `.ai-agent/`):
+ *   <root>/config.d/{models,rosters,skills,mcp,plugins,scenarios,collab,runtime,governance,execution}.json
+ *   <root>/.env        secret VALUES (KEY=value) — the ONLY file holding secrets; gitignored, never read here.
+ *
+ * Rules:
+ *  - A MISSING file (ENOENT) → the domain is absent → schema defaults fill in (parseDomain tolerates undefined).
+ *    A present-but-EMPTY/whitespace file is a half-write → THROW (fail-closed, like remote-exec); to mean
+ *    "absent/defaults" the file must be missing, not empty. A valid `{}` object IS a set domain (→ defaults).
+ *  - FLEET-only domains (`workers`/`hosts`/`systems`) are OMITTED on a single machine (no reconciler); they
+ *    resolve to their schema defaults (`{workers:[]}` etc.) — no stubbing needed.
+ *  - The JSON files only ever carry env-NAMEs (the ENV_NAME boundary holds locally too); `.env` holds values.
+ *  - `getVersion()` = a stable content hash of all portable files → a u53 number, so a consumer's
+ *    "skip re-apply if version unchanged" works locally. `getEffective().updatedAt` = the max file mtime,
+ *    passed EXPLICITLY into buildEffective (the determinism refactor) so identical files ⇒ identical bytes.
+ */
+import { readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { buildEffective, parseDomain } from "./config-fns.js";
+import { stableHash } from "./hash.js";
+import { isDomainName } from "./types.js";
+/** The domains a single-machine TOC carries (fleet-only workers/hosts/systems omitted — they default empty).
+ *  `projects` (0.10.0) is ALSO deliberately excluded: the ledger is TENANT IDENTITY DATA, not portable
+ *  config — bundling it into another deployment would copy identity registrations out of thin air (the
+ *  design/142 §1.4 threat-model-① "carried-in foreign projectId" in import clothing). Export/带走 goes
+ *  through the 142 §5 export face (service half), never the config bundle. */
+export const PORTABLE_DOMAINS = ["models", "rosters", "skills", "mcp", "plugins", "scenarios", "collab", "runtime", "governance", "execution"];
+export class FileConfigStore {
+    root;
+    opts;
+    /** `opts.onWarning` (0.8.1): receives buildEffective's read-degradation warnings (grandfathered hosts /
+     *  domain defaulted — see {@link EffectiveReadWarning}) so a TOC shell can surface them; omit = resilient
+     *  but silent. Additive — existing `new FileConfigStore(root)` callers are unchanged. */
+    constructor(root, opts = {}) {
+        this.root = root;
+        this.opts = opts;
+    }
+    /** Absolute path to a domain's JSON file. Guards the name (defence in depth — a non-domain string like
+     *  `../../secret` must never be joined into a filesystem path, even if a caller bypasses the type). */
+    domainPath(domain) {
+        if (!isDomainName(domain))
+            throw new Error(`"${domain}" is not a config domain — refusing to build a config.d path (no traversal)`);
+        return path.join(this.root, "config.d", `${domain}.json`);
+    }
+    /** Read + JSON.parse one domain file. A MISSING file (ENOENT) → undefined = the domain is ABSENT (the ONLY
+     *  way to mean "use defaults"). A present file that is EMPTY/whitespace-only, or parses to anything but a JSON
+     *  OBJECT (literal `null`, an array, a number/string/bool), is CORRUPT → throw, FAIL CLOSED — identical
+     *  discipline to loadRemoteExec + the `file:` ref (an empty present file is a half-write/truncation, NOT
+     *  "absent": treating it as absent would silently DROP a published domain — e.g. a truncated runtime.json
+     *  drops its commandPolicy/autonomy guardrails and the consumer falls back to env). This also keeps
+     *  getVersion in lock-step with getEffective/getDomain: stableStringify collapses `undefined` (absent) and
+     *  `null` to the SAME bytes, so an empty/null file that resolved to undefined would hash IDENTICALLY to
+     *  "domain absent" and a version-gated poller would skip a change getEffective/getDomain actually FAIL on.
+     *  Every domain schema is a z.object, so a non-object/empty file is never valid — reject all those shapes
+     *  here, once. R17 + R(codex 整体复审 0.1.27). */
+    async #readDomainRaw(domain) {
+        let text;
+        try {
+            text = await readFile(this.domainPath(domain), "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return undefined;
+            throw e;
+        }
+        const trimmed = text.trim();
+        // FAIL CLOSED on an empty/whitespace present file (half-write/truncation), same as loadRemoteExec/file: —
+        // to mean "absent → defaults" the file must be MISSING (ENOENT), never present-but-empty.
+        if (!trimmed)
+            throw new Error(`config.d/${domain}.json is empty/whitespace — delete it for the domain default, or write a valid object`);
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            throw new Error(`invalid JSON in config.d/${domain}.json`); // sanitized: never echo the raw file text into the error
+        }
+        if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            const kind = parsed === null ? "null" : Array.isArray(parsed) ? "array" : typeof parsed;
+            throw new Error(`config.d/${domain}.json must be a JSON object (got ${kind}) — delete the file for the domain default, or write a valid object`);
+        }
+        return parsed;
+    }
+    /** Raw (unparsed) values for every PORTABLE domain, keyed by domain name (absent → undefined). */
+    async #readAllRaw() {
+        const out = {};
+        await Promise.all(PORTABLE_DOMAINS.map(async (d) => { out[d] = await this.#readDomainRaw(d); }));
+        return out;
+    }
+    /** The max mtime (ISO) across the present portable files, or the epoch when none exist — so `updatedAt`
+     *  is deterministic for a given set of files (not the wall clock). */
+    async #maxMtimeIso() {
+        let maxMs = 0;
+        await Promise.all(PORTABLE_DOMAINS.map(async (d) => {
+            try {
+                const s = await stat(this.domainPath(d));
+                if (s.mtimeMs > maxMs)
+                    maxMs = s.mtimeMs;
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    throw e;
+            }
+        }));
+        return new Date(maxMs).toISOString();
+    }
+    /** Read+parse one domain (validated, defaults filled), or `undefined` if the domain is ABSENT — matching
+     *  the {@link ConfigReader} contract (reader.ts: absent domain → undefined) and the server stores'
+     *  `has(domain) ? parse : undefined`. A present-but-empty file (`{}` / whitespace) IS a set domain → parsed
+     *  with defaults; a missing file is absence → undefined. (getEffective still fills defaults for absent
+     *  domains; getDomain is the per-domain "was this ever set?" probe.) */
+    async getDomain(domain) {
+        const raw = await this.#readDomainRaw(domain);
+        if (raw === undefined)
+            return undefined; // missing/empty file → domain absent (not schema defaults)
+        return parseDomain(domain, raw);
+    }
+    /** Content hash of a raws snapshot → a stable u53-ish version number (≤ Number.MAX_SAFE_INTEGER). */
+    #versionOf(raws) {
+        return parseInt(stableHash(raws).slice(0, 13), 16); // 13 hex digits ≤ 2^52, safely within u53
+    }
+    /** All portable domains → EffectiveConfig. The PAYLOAD and its `version` come from ONE raws snapshot (no
+     *  re-read between them — else a concurrent atomic rename could pair payload A with version B and a consumer
+     *  would skip the change). `updatedAt` = max file mtime (informational; the content-hash version is the
+     *  authoritative change-detector). */
+    async getEffective() {
+        const raws = await this.#readAllRaw();
+        const updatedAt = await this.#maxMtimeIso();
+        return buildEffective(this.#versionOf(raws), (d) => raws[d], updatedAt, this.opts.onWarning);
+    }
+    /** Stable version number for the current files: same files ⇒ same number ⇒ a consumer's "skip re-apply if
+     *  version unchanged" works locally too. */
+    async getVersion() {
+        return this.#versionOf(await this.#readAllRaw());
+    }
+}
+//# sourceMappingURL=file-store.js.map

package/dist/file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store.js","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"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"}