@wootsup/yt-builder-mcp 1.0.0 → 1.1.0

package/dist/sites/schema.js

@@ -0,0 +1,71 @@
+/**
+ * W1 — Sites-Storage Foundation: Zod schemas for the on-disk sites file.
+ *
+ * Schema spec frozen by `2026-05-25-04-yt-builder-mcp-multi-site-implementation.md`
+ * §W1. Do NOT rename fields without bumping `schema_version` and adding a
+ * migration in W3 (registry).
+ *
+ * The on-disk format is JSON. Each entry represents one connected
+ * YOOtheme-Pro-equipped site. A site MUST carry either an inline `bearer`
+ * (plain text, for local-dev) OR an `op://` 1Password Secret Reference
+ * (`bearer_ref`), never both — enforced via {@link SiteEntry}'s refine().
+ *
+ * @license MIT
+ */
+import { z } from 'zod';
+/**
+ * Allowed character set for a `site_id`. Letters, digits, underscore,
+ * dash — no spaces, no path separators, no shell metacharacters.
+ *
+ * Surface: filename-safe, URL-path-safe, log-safe.
+ */
+export const SITE_ID_REGEX = /^[a-zA-Z0-9_-]+$/;
+/**
+ * 1Password Secret Reference shape (`op://<vault>/<item>/<field>` and
+ * deeper). Letters, digits, underscore, slash, dot, dash only — same
+ * defence-in-depth set the W2 SecretResolver will re-validate before
+ * shelling out to `op`.
+ *
+ * W12-R1.3 (A2-L1): the previous pattern allowed `..` path segments
+ * because `.` was in the character class. The `op` CLI does not honour
+ * filesystem-style traversal but the input was reaching shell argv
+ * verbatim, so a ref like `op://vault/../something` (or worse, encoded
+ * in a hand-edited sites.json) muddied the trust boundary. The
+ * negative lookahead `(?!.*\/\.\.\/)` rejects any ref containing a
+ * `/../` segment without disallowing legitimate `.` in vault/item
+ * names (e.g. `op://team.acme/...`).
+ */
+export const OP_REF_REGEX = /^op:\/\/(?!.*\/\.\.\/)[A-Za-z0-9_/.-]+$/;
+/**
+ * Bearer-token shape produced by `KeyService.php`:
+ * `ytb_(live|test)_<payloadB64Url>.<sigB64Url>`. Re-validated here so a
+ * hand-edited sites.json can never inject a token shape the server would
+ * reject anyway.
+ */
+export const BEARER_REGEX = /^ytb_(live|test)_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+/**
+ * One site entry. Carries identity (`site_id`), reachability (`url` +
+ * `platform`), credential (exactly one of `bearer`/`bearer_ref`), and
+ * presentation metadata (`is_default`, `label`, `added_at`).
+ */
+export const SiteEntry = z.object({
+    site_id: z.string().min(1).max(64).regex(SITE_ID_REGEX),
+    url: z.string().url(),
+    platform: z.enum(['wordpress', 'joomla', 'auto']).default('auto'),
+    bearer: z.string().regex(BEARER_REGEX).optional(),
+    bearer_ref: z.string().regex(OP_REF_REGEX).optional(),
+    is_default: z.boolean().default(false),
+    label: z.string().max(120).optional(),
+    added_at: z.string().datetime().optional(),
+}).refine((s) => (s.bearer !== undefined) !== (s.bearer_ref !== undefined), { message: 'Exactly one of bearer or bearer_ref must be set' });
+/**
+ * The on-disk sites-file root. `schema_version` is a literal `1` for now;
+ * future schema migrations bump it AND add a migration step in the W3
+ * registry loader.
+ */
+export const SitesFile = z.object({
+    schema_version: z.literal(1),
+    default_site_id: z.string().regex(SITE_ID_REGEX).nullable(),
+    sites: z.array(SiteEntry),
+}).refine((f) => f.sites.filter((s) => s.is_default).length <= 1, { message: 'At most one site can have is_default:true' });
+//# sourceMappingURL=schema.js.map

package/dist/sites/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/sites/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,yCAAyC,CAAC;AAEtE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,kDAAkD,CAAC;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC;IACvD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACrB,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACjE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE;IACjD,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE;IACrD,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;IACtC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC7C,CAAC,CAAC,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,EAChE,EAAE,OAAO,EAAE,iDAAiD,EAAE,CACjE,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;IAC3D,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC;CAC5B,CAAC,CAAC,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,IAAI,CAAC,EACtD,EAAE,OAAO,EAAE,2CAA2C,EAAE,CAC3D,CAAC"}

package/dist/sites/secret-resolver.d.ts

@@ -0,0 +1,109 @@
+/**
+ * W2 — Secret-Resolver: produce a bearer-token for a `SiteEntryT` at call
+ * time, supporting either a plain in-file token (`bearer`) or a 1Password
+ * Secret Reference (`bearer_ref`) resolved through the `op` CLI.
+ *
+ * Design choices (per plan §W2):
+ *  - **`execFile`, never `exec`/`spawn` with `shell:true`.** `op read <ref>`
+ *    must run as a direct `execve` with an argv array — no shell, no
+ *    metacharacter expansion. The W1 schema already enforces
+ *    {@link OP_REF_REGEX}; this module re-enforces it at the call site as
+ *    defence-in-depth (a hand-edited sites.json could otherwise sneak a
+ *    payload past validation).
+ *  - **5-second hard timeout.** `op` is interactive in some failure modes
+ *    (Touch-ID, biometric retry). We cap with a real timer + `kill()` to
+ *    avoid agent-loop wedging on a stalled subprocess.
+ *  - **Pluggable for testing.** The OpSecretResolver accepts an injected
+ *    `execFile` callback so tests can mock subprocess invocation without
+ *    monkey-patching the global `node:child_process` module.
+ *
+ * @license MIT
+ */
+import { type SiteEntryT } from './schema.js';
+/**
+ * Shape returned by every resolver. W12-R1.2 (A5-S3): the planned TTL
+ * cache that was the original justification for `resolvedAt` never
+ * shipped — the W4 ClientPool caches the `RestClient` itself, not the
+ * bearer — so the field was dead weight. Dropped to keep the contract
+ * minimal. Re-add ONLY when a real consumer appears.
+ */
+export interface ResolvedBearer {
+    readonly token: string;
+    readonly source: 'plain' | 'op';
+}
+/**
+ * Pluggable resolver contract. Implementations MUST NOT log the token,
+ * MUST NOT mutate the input site, and MUST throw {@link SecretResolverError}
+ * on any failure (never return an empty/placeholder bearer).
+ */
+export interface SecretResolver {
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+}
+/** Domain-tagged error so callers (auth, client) can branch on `code`. */
+export declare class SecretResolverError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Signature of `node:child_process.execFile` reduced to the callback we
+ * actually rely on. Injecting this lets tests provide a deterministic
+ * substitute without `vi.mock('node:child_process')` side-effects.
+ *
+ * The real `execFile` overload returns a `ChildProcess` and accepts
+ * many option shapes; we accept the broadest superset and only use the
+ * pieces the resolver needs (`timeout`, `signal`, callback args).
+ */
+export type ExecFileLike = (file: string, args: readonly string[], options: {
+    timeout?: number;
+    maxBuffer?: number;
+}, callback: (error: (Error & {
+    code?: string | number;
+    signal?: string;
+}) | null, stdout: string, stderr: string) => void) => void;
+/**
+ * Plain in-file bearer — used when `site.bearer` is populated. Returns the
+ * stored token verbatim, with `source:'plain'`.
+ */
+export declare class PlainSecretResolver implements SecretResolver {
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+}
+/**
+ * Resolves `bearer_ref` (`op://vault/item/field`) through the 1Password CLI.
+ *
+ * Failure surface:
+ *  - Missing `bearer_ref`             → `OP_REF_MISSING`
+ *  - Malformed ref at call site       → `OP_REF_INVALID`
+ *  - `op` binary not on PATH (ENOENT) → `OP_CLI_MISSING`
+ *  - `op` exit-code 6 (not signed in) → `OP_NOT_SIGNED_IN`
+ *  - 5-second timeout exceeded        → `OP_TIMEOUT`
+ *  - Empty/whitespace stdout          → `OP_EMPTY_OUTPUT`
+ *  - Any other non-zero exit          → `OP_EXEC_FAILED`
+ */
+export declare class OpSecretResolver implements SecretResolver {
+    private readonly opBinary;
+    private readonly execFile;
+    private readonly timeoutMs;
+    constructor(opBinary?: string, execFile?: ExecFileLike, timeoutMs?: number);
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+    /**
+     * Invokes `op read <ref>` with a hard timeout. The promise is wrapped
+     * so a stalled subprocess (e.g. waiting on biometric prompt) cannot
+     * outlive {@link timeoutMs}.
+     */
+    private runOpRead;
+    private mapExecError;
+}
+/**
+ * Composite resolver — chooses Plain/Op per site at resolve-time. This is
+ * the resolver wired into the registry in W4; W2 ships it standalone so
+ * unit tests cover the routing logic in isolation from any caching.
+ */
+export declare class CompositeSecretResolver implements SecretResolver {
+    private readonly plain;
+    private readonly op;
+    constructor(plain?: SecretResolver, op?: SecretResolver);
+    resolve(site: SiteEntryT): Promise<ResolvedBearer>;
+}
+/** Default factory consumed by the W4 registry / W5 auth pipeline. */
+export declare function defaultSecretResolver(): CompositeSecretResolver;
+//# sourceMappingURL=secret-resolver.d.ts.map

package/dist/sites/secret-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-resolver.d.ts","sourceRoot":"","sources":["../../src/sites/secret-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAW5D;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC3B,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CACtD;AAED,0EAA0E;AAC1E,qBAAa,mBAAoB,SAAQ,KAAK;aACd,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI5D;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,CACvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EACjD,QAAQ,EAAE,CACN,KAAK,EAAE,CAAC,KAAK,GAAG;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,IAAI,EACnE,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,KACb,IAAI,KACR,IAAI,CAAC;AAqBV;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAChD,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;CAa3D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IAE/C,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAFT,QAAQ,GAAE,MAAa,EACvB,QAAQ,GAAE,YAA8B,EACxC,SAAS,GAAE,MAAsB;IAGhD,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;IAmCxD;;;;OAIG;IACH,OAAO,CAAC,SAAS;IAoCjB,OAAO,CAAC,YAAY;CAoDvB;AAED;;;;GAIG;AACH,qBAAa,uBAAwB,YAAW,cAAc;IAEtD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE;gBADF,KAAK,GAAE,cAA0C,EACjD,EAAE,GAAE,cAAuC;IAG1D,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC;CAM3D;AAED,sEAAsE;AACtE,wBAAgB,qBAAqB,IAAI,uBAAuB,CAE/D"}

package/dist/sites/secret-resolver.js

@@ -0,0 +1,189 @@
+/**
+ * W2 — Secret-Resolver: produce a bearer-token for a `SiteEntryT` at call
+ * time, supporting either a plain in-file token (`bearer`) or a 1Password
+ * Secret Reference (`bearer_ref`) resolved through the `op` CLI.
+ *
+ * Design choices (per plan §W2):
+ *  - **`execFile`, never `exec`/`spawn` with `shell:true`.** `op read <ref>`
+ *    must run as a direct `execve` with an argv array — no shell, no
+ *    metacharacter expansion. The W1 schema already enforces
+ *    {@link OP_REF_REGEX}; this module re-enforces it at the call site as
+ *    defence-in-depth (a hand-edited sites.json could otherwise sneak a
+ *    payload past validation).
+ *  - **5-second hard timeout.** `op` is interactive in some failure modes
+ *    (Touch-ID, biometric retry). We cap with a real timer + `kill()` to
+ *    avoid agent-loop wedging on a stalled subprocess.
+ *  - **Pluggable for testing.** The OpSecretResolver accepts an injected
+ *    `execFile` callback so tests can mock subprocess invocation without
+ *    monkey-patching the global `node:child_process` module.
+ *
+ * @license MIT
+ */
+import { execFile as nodeExecFile } from 'node:child_process';
+import { OP_REF_REGEX } from './schema.js';
+/** Hard cap for any single `op read` invocation. */
+const OP_TIMEOUT_MS = 5_000;
+/** `op` CLI exit-code → friendly hint mapping. */
+const OP_EXIT_CODE_HINTS = {
+    6: 'Not signed in to 1Password CLI. Run `op signin` and retry.',
+    1: 'Generic op CLI error — verify the secret reference exists and the vault is accessible.',
+};
+/** Domain-tagged error so callers (auth, client) can branch on `code`. */
+export class SecretResolverError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SecretResolverError';
+    }
+}
+/** Default factory wrapping Node's real `execFile`. Adapter for type-shape. */
+const defaultExecFile = (file, args, options, callback) => {
+    // Pass `encoding: 'utf8'` explicitly so stdout/stderr are guaranteed
+    // strings, not Buffers. The execFile overload resolution returns `string`
+    // for both when `encoding` is set.
+    nodeExecFile(file, args, { ...options, encoding: 'utf8' }, (err, stdout, stderr) => {
+        callback(err, stdout, stderr);
+    });
+};
+/**
+ * Plain in-file bearer — used when `site.bearer` is populated. Returns the
+ * stored token verbatim, with `source:'plain'`.
+ */
+export class PlainSecretResolver {
+    async resolve(site) {
+        const token = site.bearer;
+        if (token === undefined || token.length === 0) {
+            throw new SecretResolverError('PLAIN_BEARER_MISSING', `Site '${site.site_id}' has no inline 'bearer' — set one or configure 'bearer_ref'.`);
+        }
+        return {
+            token,
+            source: 'plain',
+        };
+    }
+}
+/**
+ * Resolves `bearer_ref` (`op://vault/item/field`) through the 1Password CLI.
+ *
+ * Failure surface:
+ *  - Missing `bearer_ref`             → `OP_REF_MISSING`
+ *  - Malformed ref at call site       → `OP_REF_INVALID`
+ *  - `op` binary not on PATH (ENOENT) → `OP_CLI_MISSING`
+ *  - `op` exit-code 6 (not signed in) → `OP_NOT_SIGNED_IN`
+ *  - 5-second timeout exceeded        → `OP_TIMEOUT`
+ *  - Empty/whitespace stdout          → `OP_EMPTY_OUTPUT`
+ *  - Any other non-zero exit          → `OP_EXEC_FAILED`
+ */
+export class OpSecretResolver {
+    opBinary;
+    execFile;
+    timeoutMs;
+    constructor(opBinary = 'op', execFile = defaultExecFile, timeoutMs = OP_TIMEOUT_MS) {
+        this.opBinary = opBinary;
+        this.execFile = execFile;
+        this.timeoutMs = timeoutMs;
+    }
+    async resolve(site) {
+        const ref = site.bearer_ref;
+        if (ref === undefined || ref.length === 0) {
+            throw new SecretResolverError('OP_REF_MISSING', `Site '${site.site_id}' has no 'bearer_ref' — OpSecretResolver requires one.`);
+        }
+        // Defence-in-depth: re-validate the ref shape at the call site,
+        // BEFORE we hand the string to a subprocess. The W1 schema also
+        // enforces this on load/save, but a hand-edited or hot-loaded
+        // sites.json could in theory bypass that.
+        if (!OP_REF_REGEX.test(ref)) {
+            throw new SecretResolverError('OP_REF_INVALID', `Site '${site.site_id}' has an invalid 'bearer_ref' shape — must match op://<vault>/<item>/<field>.`);
+        }
+        const stdout = await this.runOpRead(ref);
+        const token = stdout.trim();
+        if (token.length === 0) {
+            throw new SecretResolverError('OP_EMPTY_OUTPUT', `op returned empty output for '${ref}' — verify the field exists and is non-empty.`);
+        }
+        return {
+            token,
+            source: 'op',
+        };
+    }
+    /**
+     * Invokes `op read <ref>` with a hard timeout. The promise is wrapped
+     * so a stalled subprocess (e.g. waiting on biometric prompt) cannot
+     * outlive {@link timeoutMs}.
+     */
+    runOpRead(ref) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new SecretResolverError('OP_TIMEOUT', `op read '${ref}' exceeded ${this.timeoutMs}ms — is 1Password CLI hung on a biometric prompt?`));
+            }, this.timeoutMs);
+            // Allow the test process to exit even if `op` is still pending.
+            if (typeof timer.unref === 'function')
+                timer.unref();
+            this.execFile(this.opBinary, ['read', ref], { timeout: this.timeoutMs, maxBuffer: 1024 * 64 }, (err, stdout, stderr) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                if (err) {
+                    reject(this.mapExecError(err, stderr, ref));
+                    return;
+                }
+                resolve(stdout);
+            });
+        });
+    }
+    mapExecError(err, stderr, ref) {
+        const codeStr = typeof err.code === 'string' ? err.code : '';
+        const codeNum = typeof err.code === 'number' ? err.code : NaN;
+        if (codeStr === 'ENOENT') {
+            return new SecretResolverError('OP_CLI_MISSING', `op CLI not found in PATH — install 1Password CLI or use plain bearer field instead of bearer_ref.`);
+        }
+        // W12-R1.2 (A5-S4): the `op` CLI returns "isn't an item" / "item
+        // not found" on stderr when the ref points to a nonexistent item.
+        // Surfaced as generic OP_EXEC_FAILED pre-W12, which left the
+        // customer guessing whether their ref shape was wrong vs whether
+        // the item was deleted. Brand it explicitly so the recovery hint
+        // can name the right knob.
+        const stderrLower = (stderr || '').toLowerCase();
+        if (stderrLower.includes(`isn't an item`)
+            || stderrLower.includes('item not found')) {
+            return new SecretResolverError('OP_ITEM_NOT_FOUND', `1Password item not found at '${ref}'. `
+                + 'Verify the ref points to an existing item, or update sites.json bearer_ref.');
+        }
+        if (Number.isFinite(codeNum)) {
+            const hint = OP_EXIT_CODE_HINTS[codeNum];
+            if (codeNum === 6) {
+                return new SecretResolverError('OP_NOT_SIGNED_IN', hint ?? `op exited 6 — not signed in.`);
+            }
+            return new SecretResolverError('OP_EXEC_FAILED', `op read '${ref}' failed with exit ${codeNum}: ${(stderr || '').trim() || (hint ?? 'no stderr')}`);
+        }
+        return new SecretResolverError('OP_EXEC_FAILED', `op read '${ref}' failed: ${err.message}`);
+    }
+}
+/**
+ * Composite resolver — chooses Plain/Op per site at resolve-time. This is
+ * the resolver wired into the registry in W4; W2 ships it standalone so
+ * unit tests cover the routing logic in isolation from any caching.
+ */
+export class CompositeSecretResolver {
+    plain;
+    op;
+    constructor(plain = new PlainSecretResolver(), op = new OpSecretResolver()) {
+        this.plain = plain;
+        this.op = op;
+    }
+    async resolve(site) {
+        if (site.bearer_ref !== undefined) {
+            return this.op.resolve(site);
+        }
+        return this.plain.resolve(site);
+    }
+}
+/** Default factory consumed by the W4 registry / W5 auth pipeline. */
+export function defaultSecretResolver() {
+    return new CompositeSecretResolver();
+}
+//# sourceMappingURL=secret-resolver.js.map

package/dist/sites/secret-resolver.js.map

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

package/dist/sites/store.d.ts

@@ -0,0 +1,82 @@
+/**
+ * W1 — Sites-Storage Foundation: load/save the sites file.
+ *
+ * Guarantees:
+ *  - **Atomic replace.** Writes go to a sibling `*.tmp.<rand>` file, are
+ *    fsynced, chmod'd to 0600, and then `rename(2)`d over the target.
+ *    A SIGINT/SIGKILL between any two of these steps leaves either the
+ *    old file intact or the new file fully written — never a torn write.
+ *  - **Lock for concurrent writers.** `proper-lockfile` acquires an
+ *    advisory lockfile (`<file>.lock`) before any read/modify/write
+ *    cycle. Default `stale: 10000` ms; second concurrent save retries
+ *    with exponential back-off (`retries: 10, minTimeout: 50`).
+ *  - **0600 mode on write.** The temp file is opened/chmod'd to 0600
+ *    BEFORE the rename so the new inode never exists with looser perms,
+ *    even for one fsync window.
+ *  - **Schema-version gate.** Refuses to load a file with a version we
+ *    don't understand — explicit error, never silent migration.
+ *
+ * @license MIT
+ */
+import { type SitesFileT } from './schema.js';
+/** Base class for any sites-file IO/format failure. */
+export declare class SitesFileError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Thrown when the on-disk file declares a `schema_version` we don't know. */
+export declare class SchemaVersionError extends SitesFileError {
+    readonly found: unknown;
+    constructor(found: unknown);
+}
+/**
+ * Discriminated lock-acquisition failure. W12-R1.2 (A4-F1): the
+ * pre-W12 `SitesFileError` collapsed three distinct failure modes into
+ * one opaque "lock not acquired" string. Operators triaging a stuck
+ * setup wizard need to distinguish them to choose the right recovery:
+ *
+ *   - LOCK_TIMEOUT    → another setup process is currently writing.
+ *                       Wait + retry; do NOT touch the lockfile.
+ *   - LOCK_ORPHAN     → stale lock from a crashed prior process.
+ *                       Manual `rm <lockfilePath>` is the only fix.
+ *   - LOCK_PERMISSION → the lock dir itself is not writable. Fix
+ *                       file-system permissions.
+ *
+ * The `lockCode` discriminant + `lockfilePath` field let CLI surfaces
+ * (and pre-flight automation) emit precise hints.
+ */
+export type SitesFileLockCode = 'LOCK_TIMEOUT' | 'LOCK_ORPHAN' | 'LOCK_PERMISSION';
+export declare class SitesFileLockError extends SitesFileError {
+    readonly lockCode: SitesFileLockCode;
+    readonly lockfilePath: string;
+    constructor(lockCode: SitesFileLockCode, lockfilePath: string, message: string, cause?: unknown);
+}
+/**
+ * Returns the empty seed used when a sites file does not yet exist.
+ * Callers (W3 registry) detect "no file → run env-bridge fallback".
+ */
+export declare function emptySitesFile(): SitesFileT;
+/**
+ * Load + validate a sites file.
+ *
+ * Returns {@link emptySitesFile} when the path does not exist (no error).
+ * Throws {@link SchemaVersionError} for a known-unknown version and
+ * {@link SitesFileError} for JSON-parse or Zod-validation failures.
+ */
+export declare function loadSitesFile(path: string): Promise<SitesFileT>;
+/**
+ * Persist + validate a sites file atomically with chmod 0600.
+ *
+ * Pipeline:
+ *  1. Acquire `<path>.lock` via proper-lockfile (with retries).
+ *  2. Validate `data` through {@link SitesFile} (rejects bad input
+ *     before touching the filesystem).
+ *  3. Ensure parent directory exists.
+ *  4. Write JSON to `<path>.tmp.<pid>.<rand>`, fsync, chmod 0600.
+ *  5. `renameSync` over `<path>`.
+ *  6. Release lock.
+ *
+ * Tmp-file cleanup on any failure path.
+ */
+export declare function saveSitesFile(path: string, data: SitesFileT): Promise<void>;
+//# sourceMappingURL=store.d.ts.map

package/dist/sites/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sites/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAkBH,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzD,uDAAuD;AACvD,qBAAa,cAAe,SAAQ,KAAK;aACQ,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAI/D;AAED,8EAA8E;AAC9E,qBAAa,kBAAmB,SAAQ,cAAc;aACtB,KAAK,EAAE,OAAO;gBAAd,KAAK,EAAE,OAAO;CAQ7C;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,GAAG,aAAa,GAAG,iBAAiB,CAAC;AAEnF,qBAAa,kBAAmB,SAAQ,cAAc;aAE9B,QAAQ,EAAE,iBAAiB;aAC3B,YAAY,EAAE,MAAM;gBADpB,QAAQ,EAAE,iBAAiB,EAC3B,YAAY,EAAE,MAAM,EACpC,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO;CAKtB;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAE3C;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAiCrE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAoFjF"}