@wootsup/mcp 0.1.0 → 0.4.0

package/dist/sites/loader.js

@@ -0,0 +1,134 @@
+// src/sites/loader.ts — Phase 3.
+//
+// Load + validate the on-disk sites file pointed at by APIMAPPER_SITES_FILE and
+// wrap it in a small read-only registry. This is the multi-site "agency / .dxt
+// one-click" path: a plaintext JSON file listing several WordPress/Joomla sites,
+// each with its own URL + token + platform. The keychain ProfileStore path
+// (src/auth/profiles.ts) remains the secure wizard default for single-machine
+// setups — the two mechanisms coexist; the sites-file takes priority in
+// client.ts ONLY when APIMAPPER_SITES_FILE is set and the file is non-empty.
+//
+// Read-only by design: this loader never writes the sites file. Editing is an
+// operator / wizard concern, kept out of the hot request path.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { SitesFile } from "./schema.js";
+/** Base class for any sites-file IO / parse / validation failure. */
+export class SitesFileError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "SitesFileError";
+        Object.setPrototypeOf(this, SitesFileError.prototype);
+    }
+}
+/**
+ * Read-only registry around a parsed, non-empty sites file. Provides O(1)-ish
+ * lookups for the active-site resolution in client.ts. Never mutates the input.
+ */
+export class SitesRegistry {
+    file;
+    constructor(file) {
+        this.file = file;
+    }
+    /** Entries in insertion order (stable for list-tool UX). */
+    list() {
+        return this.file.sites;
+    }
+    /** Site_id list in insertion order. */
+    listIds() {
+        return this.file.sites.map((s) => s.site_id);
+    }
+    /** Raw entry for a site_id, or null when unknown. */
+    get(siteId) {
+        return this.file.sites.find((s) => s.site_id === siteId) ?? null;
+    }
+    /** True when the registry contains the given site_id. */
+    has(siteId) {
+        return this.file.sites.some((s) => s.site_id === siteId);
+    }
+    /**
+     * The default site entry. Resolution order:
+     *   1. `default_site_id` (when it points at an existing entry).
+     *   2. The lone `is_default:true` entry (schema guarantees at most one).
+     *   3. The first entry (the file is guaranteed non-empty by the loader).
+     */
+    getDefault() {
+        const explicit = this.file.default_site_id;
+        if (explicit !== null) {
+            const hit = this.get(explicit);
+            if (hit)
+                return hit;
+        }
+        const flagged = this.file.sites.find((s) => s.is_default);
+        if (flagged)
+            return flagged;
+        // Loader guarantees sites.length > 0 (empty → null, never a registry).
+        return this.file.sites[0];
+    }
+}
+/**
+ * Load the sites file at `path` and return a {@link SitesRegistry}, or `null`
+ * when there is no usable multi-site config (so the caller falls through to the
+ * env / keychain single-site path).
+ *
+ *   - `path` unset / empty / whitespace  → null
+ *   - file does not exist                 → null
+ *   - file parses but has zero sites      → null
+ *   - malformed JSON / schema-invalid /
+ *     unknown schema_version              → throws {@link SitesFileError}
+ */
+/**
+ * F190 (2026-06-12): expand a leading `~` to the user's home directory.
+ * Node's fs does NOT do this — a `~/...` path typed into the Claude Desktop
+ * DXT settings silently failed (existsSync false → no sites). Only `~` and
+ * `~/...` are expanded; `~user/...` is left untouched (not supported).
+ */
+export function expandTilde(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+export function loadSitesRegistry(path) {
+    const trimmed = expandTilde((path ?? "").trim());
+    if (trimmed.length === 0)
+        return null;
+    if (!existsSync(trimmed))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(trimmed, "utf8");
+    }
+    catch (e) {
+        throw new SitesFileError(`Failed to read sites file at ${trimmed}`, e);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new SitesFileError(`Sites file at ${trimmed} is not valid JSON`, e);
+    }
+    // Explicit schema-version gate: reject a known-unknown version with a clear
+    // message rather than letting the Zod literal check surface a cryptic issue.
+    if (typeof parsed === "object" &&
+        parsed !== null &&
+        "schema_version" in parsed &&
+        parsed.schema_version !== 1) {
+        throw new SitesFileError(`Unsupported sites-file schema_version: ${String(parsed.schema_version)}. This build supports schema_version: 1.`);
+    }
+    const result = SitesFile.safeParse(parsed);
+    if (!result.success) {
+        throw new SitesFileError(`Sites file at ${trimmed} failed schema validation: ` +
+            result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; "));
+    }
+    // Empty sites list → no usable multi-site config; fall through to env.
+    if (result.data.sites.length === 0)
+        return null;
+    return new SitesRegistry(result.data);
+}
+//# sourceMappingURL=loader.js.map

package/dist/sites/loader.js.map

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

package/dist/sites/schema.d.ts

@@ -0,0 +1,69 @@
+import { z } from "zod";
+/**
+ * Allowed character set for a `site_id`. Letters, digits, underscore, dash —
+ * no spaces, no path separators, no shell metacharacters. Filename-safe,
+ * URL-path-safe, log-safe.
+ */
+export declare const SITE_ID_REGEX: RegExp;
+/**
+ * 1Password Secret Reference shape (`op://<vault>/<item>/<field>` and deeper).
+ * Letters, digits, underscore, slash, dot, dash only. The negative lookahead
+ * `(?!.*\/\.\.\/)` rejects any ref containing a `/../` traversal segment while
+ * still allowing legitimate `.` in vault/item names (e.g. `op://team.acme/...`).
+ * Re-validated at the secret-resolver call site as defence-in-depth before the
+ * ref ever reaches a subprocess argv.
+ */
+export declare const OP_REF_REGEX: RegExp;
+/**
+ * API Mapper MCP-key shape (canonical — mirrors core `KeyService.php`):
+ * `amk_(live|test)_<payloadB64url>.<signatureB64url>` — the payload and the
+ * signature are base64url (`A-Za-z0-9_-`) joined by exactly ONE dot. The earlier
+ * pattern dropped the `.<sig>` arm, so it rejected every REAL token (which always
+ * carries the dot) — a sites.json with a valid key failed schema validation.
+ * Re-validated here so a hand-edited sites.json can never inject a token shape the
+ * server would reject anyway.
+ */
+export declare const BEARER_REGEX: RegExp;
+/**
+ * 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 declare const SiteEntry: z.ZodObject<{
+    site_id: z.ZodString;
+    url: z.ZodString;
+    platform: z.ZodDefault<z.ZodEnum<{
+        wordpress: "wordpress";
+        joomla: "joomla";
+        auto: "auto";
+    }>>;
+    bearer: z.ZodOptional<z.ZodString>;
+    bearer_ref: z.ZodOptional<z.ZodString>;
+    is_default: z.ZodDefault<z.ZodBoolean>;
+    label: z.ZodOptional<z.ZodString>;
+    added_at: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * 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 loader.
+ */
+export declare const SitesFile: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    default_site_id: z.ZodNullable<z.ZodString>;
+    sites: z.ZodArray<z.ZodObject<{
+        site_id: z.ZodString;
+        url: z.ZodString;
+        platform: z.ZodDefault<z.ZodEnum<{
+            wordpress: "wordpress";
+            joomla: "joomla";
+            auto: "auto";
+        }>>;
+        bearer: z.ZodOptional<z.ZodString>;
+        bearer_ref: z.ZodOptional<z.ZodString>;
+        is_default: z.ZodDefault<z.ZodBoolean>;
+        label: z.ZodOptional<z.ZodString>;
+        added_at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SiteEntryT = z.infer<typeof SiteEntry>;
+export type SitesFileT = z.infer<typeof SitesFile>;

package/dist/sites/schema.js

@@ -0,0 +1,71 @@
+// src/sites/schema.ts — Zod schemas for the on-disk API Mapper sites file.
+//
+// Phase 3 (2026-06-03): the multi-site sites-file mechanism. Mirrors the YT
+// Builder reference shape (yt-builder-mcp/packages/mcp/src/sites/schema.ts) so
+// both MCP servers expose the SAME multi-site concept, adapted for API Mapper:
+//   - token shape is `amk_(live|test)_…` (API Mapper MCP key), not `ytb_…`.
+//   - per-site `platform` is 'wordpress' | 'joomla' | 'auto' (default 'auto').
+//
+// The on-disk format is JSON. Each entry is one connected WordPress/Joomla site
+// running API Mapper. A site MUST carry either an inline `bearer` (plain text)
+// OR an `op://` 1Password Secret Reference (`bearer_ref`), never both — enforced
+// via the SiteEntry refine().
+import { z } from "zod";
+/**
+ * Allowed character set for a `site_id`. Letters, digits, underscore, dash —
+ * no spaces, no path separators, no shell metacharacters. 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. The negative lookahead
+ * `(?!.*\/\.\.\/)` rejects any ref containing a `/../` traversal segment while
+ * still allowing legitimate `.` in vault/item names (e.g. `op://team.acme/...`).
+ * Re-validated at the secret-resolver call site as defence-in-depth before the
+ * ref ever reaches a subprocess argv.
+ */
+export const OP_REF_REGEX = /^op:\/\/(?!.*\/\.\.\/)[A-Za-z0-9_/.-]+$/;
+/**
+ * API Mapper MCP-key shape (canonical — mirrors core `KeyService.php`):
+ * `amk_(live|test)_<payloadB64url>.<signatureB64url>` — the payload and the
+ * signature are base64url (`A-Za-z0-9_-`) joined by exactly ONE dot. The earlier
+ * pattern dropped the `.<sig>` arm, so it rejected every REAL token (which always
+ * carries the dot) — a sites.json with a valid key failed schema validation.
+ * Re-validated here so a hand-edited sites.json can never inject a token shape the
+ * server would reject anyway.
+ */
+export const BEARER_REGEX = /^amk_(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 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,2EAA2E;AAC3E,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,+EAA+E;AAC/E,4EAA4E;AAC5E,+EAA+E;AAC/E,EAAE;AACF,gFAAgF;AAChF,+EAA+E;AAC/E,iFAAiF;AACjF,8BAA8B;AAE9B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,kBAAkB,CAAC;AAEhD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,yCAAyC,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,YAAY,GACvB,kDAAkD,CAAC;AAErD;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC;KACvB,MAAM,CAAC;IACN,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;CAC3C,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,KAAK,SAAS,CAAC,EAAE;IACxE,OAAO,EAAE,iDAAiD;CAC3D,CAAC,CAAC;AAEL;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC;KACvB,MAAM,CAAC;IACN,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;CAC1B,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,IAAI,CAAC,EAAE;IAC9D,OAAO,EAAE,2CAA2C;CACrD,CAAC,CAAC"}

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

@@ -0,0 +1,47 @@
+import { type SiteEntryT } from "./schema.js";
+/**
+ * Resolve the `op` binary to an absolute path so it works under a stripped-down
+ * GUI PATH. Precedence: explicit `APIMAPPER_OP_BINARY` env override → first
+ * existing well-known absolute path → bare `op` (PATH).
+ */
+export declare function resolveOpBinary(env?: NodeJS.ProcessEnv): string;
+/** Resolved bearer + its provenance for downstream logs (never the token). */
+export interface ResolvedBearer {
+    readonly token: string;
+    readonly source: "plain" | "op";
+}
+/** Domain-tagged error so callers 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 rely
+ * on. Injecting this lets tests provide a deterministic substitute without a
+ * `vi.mock('node:child_process')` side-effect.
+ */
+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;
+export interface ResolveSiteBearerOptions {
+    /** Injected execFile for tests. Defaults to Node's real execFile. */
+    execFile?: ExecFileLike;
+    /** Resolved `op` binary path. Defaults to {@link resolveOpBinary}. */
+    opBinary?: string;
+    /** Per-call timeout override. Defaults to {@link OP_TIMEOUT_MS}. */
+    timeoutMs?: number;
+}
+/**
+ * Resolve the bearer token for a site entry.
+ *
+ *   - `bearer` present  → returned verbatim (`source:'plain'`).
+ *   - `bearer_ref` set  → `op read <ref>` via execFile (`source:'op'`).
+ *   - neither           → throws SecretResolverError('BEARER_MISSING').
+ *
+ * Never logs the token; never mutates the input site.
+ */
+export declare function resolveSiteBearer(site: SiteEntryT, opts?: ResolveSiteBearerOptions): Promise<ResolvedBearer>;

package/dist/sites/secret-resolver.js

@@ -0,0 +1,150 @@
+// src/sites/secret-resolver.ts — Phase 3.
+//
+// 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. Mirrors the YT Builder defence model
+// (yt-builder-mcp/packages/mcp/src/sites/secret-resolver.ts), kept simple:
+//
+//   - `execFile`, NEVER `exec`/`spawn` with `shell:true`. `op read <ref>` runs
+//     as a direct argv invocation — no shell, no metacharacter expansion. The
+//     schema enforces OP_REF_REGEX on load; we re-enforce it here as
+//     defence-in-depth (a hand-edited sites.json could otherwise sneak a
+//     payload past validation).
+//   - Hard timeout so a biometric-stalled `op` can't wedge the agent loop.
+//   - Pluggable `execFile` for testing — no global child_process monkey-patch.
+import { execFile as nodeExecFile } from "node:child_process";
+import { existsSync } from "node:fs";
+import { OP_REF_REGEX } from "./schema.js";
+/** Hard cap for any single `op read` invocation. */
+const OP_TIMEOUT_MS = 5_000;
+/**
+ * Common absolute install locations for the 1Password CLI. GUI-spawned MCP
+ * hosts (Claude Desktop, etc.) launch the server subprocess with a minimal
+ * PATH that usually omits `/opt/homebrew/bin` and `/usr/local/bin`, so a bare
+ * `op` resolves to ENOENT even when `op` works in the user's shell. Probe these
+ * absolute paths before falling back to PATH.
+ */
+const OP_BINARY_CANDIDATES = [
+    "/opt/homebrew/bin/op",
+    "/usr/local/bin/op",
+    "/usr/bin/op",
+];
+/**
+ * Resolve the `op` binary to an absolute path so it works under a stripped-down
+ * GUI PATH. Precedence: explicit `APIMAPPER_OP_BINARY` env override → first
+ * existing well-known absolute path → bare `op` (PATH).
+ */
+export function resolveOpBinary(env = process.env) {
+    const override = (env.APIMAPPER_OP_BINARY ?? "").trim();
+    if (override.length > 0)
+        return override;
+    for (const candidate of OP_BINARY_CANDIDATES) {
+        try {
+            if (existsSync(candidate))
+                return candidate;
+        }
+        catch {
+            // ignore stat errors and keep probing
+        }
+    }
+    return "op";
+}
+/** Domain-tagged error so callers can branch on `code`. */
+export class SecretResolverError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "SecretResolverError";
+        Object.setPrototypeOf(this, SecretResolverError.prototype);
+    }
+}
+/** Default adapter wrapping Node's real `execFile` with utf8 encoding. */
+const defaultExecFile = (file, args, options, callback) => {
+    nodeExecFile(file, args, { ...options, encoding: "utf8" }, (err, stdout, stderr) => {
+        callback(err, stdout, stderr);
+    });
+};
+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.",
+};
+/**
+ * Resolve the bearer token for a site entry.
+ *
+ *   - `bearer` present  → returned verbatim (`source:'plain'`).
+ *   - `bearer_ref` set  → `op read <ref>` via execFile (`source:'op'`).
+ *   - neither           → throws SecretResolverError('BEARER_MISSING').
+ *
+ * Never logs the token; never mutates the input site.
+ */
+export async function resolveSiteBearer(site, opts = {}) {
+    if (site.bearer !== undefined && site.bearer.length > 0) {
+        return { token: site.bearer, source: "plain" };
+    }
+    const ref = site.bearer_ref;
+    if (ref === undefined || ref.length === 0) {
+        throw new SecretResolverError("BEARER_MISSING", `Site '${site.site_id}' has neither an inline 'bearer' nor a 'bearer_ref'.`);
+    }
+    // Defence-in-depth: re-validate the ref shape BEFORE it reaches a subprocess
+    // argv. The schema enforces this on load; a hand-edited sites.json could
+    // 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 execFile = opts.execFile ?? defaultExecFile;
+    const opBinary = opts.opBinary ?? resolveOpBinary();
+    const timeoutMs = opts.timeoutMs ?? OP_TIMEOUT_MS;
+    const stdout = await runOpRead(execFile, opBinary, ref, timeoutMs, site.site_id);
+    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" };
+}
+/** Invoke `op read <ref>` with a hard timeout that survives a stalled child. */
+function runOpRead(execFile, opBinary, ref, timeoutMs, siteId) {
+    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 ${timeoutMs}ms — is 1Password CLI hung on a biometric prompt?`));
+        }, timeoutMs);
+        if (typeof timer.unref === "function")
+            timer.unref();
+        execFile(opBinary, ["read", ref], { timeout: timeoutMs, maxBuffer: 1024 * 64 }, (err, stdout, stderr) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err) {
+                reject(mapExecError(err, stderr, ref, siteId));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+function mapExecError(err, stderr, ref, siteId) {
+    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 for site '${siteId}' — install 1Password CLI (or set APIMAPPER_OP_BINARY), ` +
+            "or use an inline 'bearer' field instead of 'bearer_ref'.");
+    }
+    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.`);
+    }
+    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}`);
+}
+//# 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/skill-instructions.d.ts

@@ -1,4 +1,17 @@
 export declare const FALLBACK_INSTRUCTIONS = "Use this MCP to manage API Mapper flows, connections, and sources across WordPress + Joomla.";
+/**
+ * F134 / F118 — load-bearing operational rules that MUST survive into the
+ * server `instructions` field regardless of SKILL.md body length. The body is
+ * truncated to MAX_LENGTH chars, and its opening prose (intro + `npx setup`)
+ * pushes the rules a cold agent actually needs PAST that window. We front-load
+ * this compact preamble so the rules are always present, then append a bounded
+ * slice of the body and the topic pointer.
+ *
+ * Keep this TERSE — every char competes with the body for the instructions
+ * budget. Each line encodes one P0-prevention rule found by the cold-agent
+ * friction audit.
+ */
+export declare const CRITICAL_RULES = "## Critical rules (read first)\n\n- Most tools are reachable via the gateway: apimapper_advanced({ tool: \"<name>\", arguments: {...} }). The arg key is `arguments` (NOT `input`). Omit `arguments` to discover a tool's schema.\n- If a call returns \"Unknown tool\", it is gateway-only \u2014 wrap it as apimapper_advanced({ tool, arguments }).\n- Verify connectivity with apimapper_health({}) \u2014 it is first-class in tools/list (call it directly, NOT via the gateway). Recover auth/config errors via apimapper_diagnose; deeper guidance via apimapper_get_skill({ topic }).\n";
 /**
  * Agent-discoverable skill-topic pointer appended to every loaded instructions
  * string. Documents the canonical entrypoint for deeper guidance via the
@@ -8,7 +21,7 @@ export declare const FALLBACK_INSTRUCTIONS = "Use this MCP to manage API Mapper
  *
  * Topics MUST stay in sync with SKILL_TOPICS in modules/apimapper/get-skill.ts.
  */
-export declare const SKILL_TOPIC_POINTER = "\n\n## Available skill topics\n\nFor deeper guidance on specific aspects of API Mapper, call:\n  apimapper_get_skill({ topic })\n\nAvailable topics:\n- getting-started \u2014 Quickstart, common tools, common pitfalls\n- oauth \u2014 Wiring OAuth-protected sources (Google, Pexels, Instagram, Notion, ...)\n- yootheme \u2014 Publish flows as YOOtheme sources; Save-vs-Publish\n- joomla \u2014 Joomla 3-tier auth, com_ajax envelope, system plugin layout\n- troubleshooting \u2014 HTTP status triage, flow issues, credential states\n";
+export declare const SKILL_TOPIC_POINTER = "\n\n## Available skill topics\n\nFor deeper guidance on specific aspects of API Mapper, call:\n  apimapper_get_skill({ topic })\n\nAvailable topics:\n- getting-started \u2014 Quickstart, common tools, common pitfalls\n- oauth \u2014 Wiring OAuth-protected sources (Google, Pexels, Instagram, Notion, ...)\n- yootheme \u2014 Publish flows as YOOtheme sources; Save-vs-Publish\n- joomla \u2014 Joomla 3-tier auth, com_ajax envelope, system plugin layout\n- troubleshooting \u2014 HTTP status triage, flow issues, credential states\n- render \u2014 Render a flow as a diagram (viz-type, flow-diagram output)\n- jmespath-pitfalls \u2014 The 9 traps + date-primitive functions (date_weekday, date_iso_to_time, date_iso_to_date, time_in_window) + depth-cap warning\n- jmespath-cookbook \u2014 Copy-paste JMESPath recipes (ternary, join, conditions, sort_by, coordinates, format_number, dates, two-transform split) + a GIBT-ES-NICHT list (arithmetic/split/regex/if-else) with workarounds; iterate via apimapper_jmespath_test\n- merge-two-sources-on-key \u2014 Joining two sources on a shared key, including date-primitive bridging for weekday-name \u2194 ISO-datetime joins\n- conditional-style-multi-items \u2014 Per-row YOOtheme styles driven by a row field (text_color, panel_style)\n- library-template-discovery \u2014 Inspect a library template's contract before activating\n- yootheme-source-to-builder-handoff \u2014 Bind a published flow into a Builder element. Two shapes: field_mappings (fresh element; binding_for_flow \u2192 element_bind_source; map_item, bindingLevel) AND the theme-canonical #parent repeater form to dynamize an EXISTING designed layout (swap source.query.name to apiMapperFlow<Id>List; _condition '!'/'!!'; named-section discovery; article-context width)\n- dynamize-existing-layout \u2014 READ FIRST when the customer says \"keep the design exactly as it is\" / \"bind onto my existing section/page\": ONE call does it \u2014 template_summary (find the named section) \u2192 binding_for_flow (source name + flat fields) \u2192 yootheme_builder_page_dynamize({ template_id, section_path, source_name, leaf_map, publish: true }) \u2192 visual row check. The tool copies the subtree byte-identically and swaps only leaf_map names by construction (insert nothing, rebuild nothing)\n";
 /**
  * Loads MCP server instructions from skills/apimapper/SKILL.md.
  *

package/dist/skill-instructions.js

@@ -7,6 +7,24 @@ import { readFileSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve } from "node:path";
 export const FALLBACK_INSTRUCTIONS = "Use this MCP to manage API Mapper flows, connections, and sources across WordPress + Joomla.";
+/**
+ * F134 / F118 — load-bearing operational rules that MUST survive into the
+ * server `instructions` field regardless of SKILL.md body length. The body is
+ * truncated to MAX_LENGTH chars, and its opening prose (intro + `npx setup`)
+ * pushes the rules a cold agent actually needs PAST that window. We front-load
+ * this compact preamble so the rules are always present, then append a bounded
+ * slice of the body and the topic pointer.
+ *
+ * Keep this TERSE — every char competes with the body for the instructions
+ * budget. Each line encodes one P0-prevention rule found by the cold-agent
+ * friction audit.
+ */
+export const CRITICAL_RULES = `## Critical rules (read first)
+
+- Most tools are reachable via the gateway: apimapper_advanced({ tool: "<name>", arguments: {...} }). The arg key is \`arguments\` (NOT \`input\`). Omit \`arguments\` to discover a tool's schema.
+- If a call returns "Unknown tool", it is gateway-only — wrap it as apimapper_advanced({ tool, arguments }).
+- Verify connectivity with apimapper_health({}) — it is first-class in tools/list (call it directly, NOT via the gateway). Recover auth/config errors via apimapper_diagnose; deeper guidance via apimapper_get_skill({ topic }).
+`;
 const MAX_LENGTH = 500;
 /**
  * Agent-discoverable skill-topic pointer appended to every loaded instructions
@@ -30,6 +48,14 @@ Available topics:
 - yootheme — Publish flows as YOOtheme sources; Save-vs-Publish
 - joomla — Joomla 3-tier auth, com_ajax envelope, system plugin layout
 - troubleshooting — HTTP status triage, flow issues, credential states
+- render — Render a flow as a diagram (viz-type, flow-diagram output)
+- jmespath-pitfalls — The 9 traps + date-primitive functions (date_weekday, date_iso_to_time, date_iso_to_date, time_in_window) + depth-cap warning
+- jmespath-cookbook — Copy-paste JMESPath recipes (ternary, join, conditions, sort_by, coordinates, format_number, dates, two-transform split) + a GIBT-ES-NICHT list (arithmetic/split/regex/if-else) with workarounds; iterate via apimapper_jmespath_test
+- merge-two-sources-on-key — Joining two sources on a shared key, including date-primitive bridging for weekday-name ↔ ISO-datetime joins
+- conditional-style-multi-items — Per-row YOOtheme styles driven by a row field (text_color, panel_style)
+- library-template-discovery — Inspect a library template's contract before activating
+- yootheme-source-to-builder-handoff — Bind a published flow into a Builder element. Two shapes: field_mappings (fresh element; binding_for_flow → element_bind_source; map_item, bindingLevel) AND the theme-canonical #parent repeater form to dynamize an EXISTING designed layout (swap source.query.name to apiMapperFlow<Id>List; _condition '!'/'!!'; named-section discovery; article-context width)
+- dynamize-existing-layout — READ FIRST when the customer says "keep the design exactly as it is" / "bind onto my existing section/page": ONE call does it — template_summary (find the named section) → binding_for_flow (source name + flat fields) → yootheme_builder_page_dynamize({ template_id, section_path, source_name, leaf_map, publish: true }) → visual row check. The tool copies the subtree byte-identically and swaps only leaf_map names by construction (insert nothing, rebuild nothing)
 `;
 /**
  * Loads MCP server instructions from skills/apimapper/SKILL.md.
@@ -43,22 +69,25 @@ export function loadSkillInstructions(rootDir) {
     const baseDir = rootDir ?? defaultRoot();
     const skillPath = join(baseDir, "skills", "apimapper", "SKILL.md");
     if (!existsSync(skillPath)) {
-        return FALLBACK_INSTRUCTIONS + SKILL_TOPIC_POINTER;
+        return CRITICAL_RULES + FALLBACK_INSTRUCTIONS + SKILL_TOPIC_POINTER;
     }
     let raw;
     try {
         raw = readFileSync(skillPath, "utf8");
     }
     catch {
-        return FALLBACK_INSTRUCTIONS + SKILL_TOPIC_POINTER;
+        return CRITICAL_RULES + FALLBACK_INSTRUCTIONS + SKILL_TOPIC_POINTER;
     }
     const body = stripFrontmatter(raw).trim();
     if (body.length === 0) {
-        return FALLBACK_INSTRUCTIONS + SKILL_TOPIC_POINTER;
+        return CRITICAL_RULES + FALLBACK_INSTRUCTIONS + SKILL_TOPIC_POINTER;
     }
-    // Append the skill-topic pointer AFTER truncation so the topic discovery
-    // surface is always present, regardless of the SKILL.md body length.
-    return body.slice(0, MAX_LENGTH) + SKILL_TOPIC_POINTER;
+    // Front-load the load-bearing rules (F134/F118) so they always survive
+    // truncation, then a bounded slice of the SKILL.md body, then the topic
+    // pointer. The body keeps its own MAX_LENGTH window; the rules + pointer are
+    // never truncated. (Pre-F134 the body opened the instructions and its intro
+    // prose pushed these rules past the window — a cold agent never saw them.)
+    return CRITICAL_RULES + body.slice(0, MAX_LENGTH) + SKILL_TOPIC_POINTER;
 }
 /**
  * Strips a YAML frontmatter block (`---\n...\n---\n`) from the start of the

package/dist/skill-instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-instructions.js","sourceRoot":"","sources":["../src/skill-instructions.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,yCAAyC;AACzC,EAAE;AACF,yEAAyE;AAEzE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,CAAC,MAAM,qBAAqB,GAChC,8FAA8F,CAAC;AAEjG,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;CAalC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,MAAM,OAAO,GAAG,OAAO,IAAI,WAAW,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IAEnE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,OAAO,qBAAqB,GAAG,mBAAmB,CAAC;IACrD,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,qBAAqB,GAAG,mBAAmB,CAAC;IACrD,CAAC;IAED,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,qBAAqB,GAAG,mBAAmB,CAAC;IACrD,CAAC;IACD,yEAAyE;IACzE,qEAAqE;IACrE,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,mBAAmB,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,iDAAiD;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC1C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,kEAAkE;IAClE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC/C,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,qDAAqD;QACrD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,WAAW;IAClB,8DAA8D;IAC9D,qEAAqE;IACrE,wCAAwC;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"skill-instructions.js","sourceRoot":"","sources":["../src/skill-instructions.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,0EAA0E;AAC1E,yCAAyC;AACzC,EAAE;AACF,yEAAyE;AAEzE,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEnD,MAAM,CAAC,MAAM,qBAAqB,GAChC,8FAA8F,CAAC;AAEjG;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;CAK7B,CAAC;AAEF,MAAM,UAAU,GAAG,GAAG,CAAC;AAEvB;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;CAqBlC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IACpD,MAAM,OAAO,GAAG,OAAO,IAAI,WAAW,EAAE,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,CAAC,CAAC;IAEnE,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3B,OAAO,cAAc,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;IACtE,CAAC;IAED,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,cAAc,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;IACtE,CAAC;IAED,MAAM,IAAI,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,cAAc,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;IACtE,CAAC;IACD,uEAAuE;IACvE,wEAAwE;IACxE,6EAA6E;IAC7E,4EAA4E;IAC5E,2EAA2E;IAC3E,OAAO,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,mBAAmB,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,KAAK,CAAC;IACf,CAAC;IACD,iDAAiD;IACjD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC1C,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,kEAAkE;IAClE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC,CAAC;IAC/C,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACd,qDAAqD;QACrD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,WAAW;IAClB,8DAA8D;IAC9D,qEAAqE;IACrE,wCAAwC;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC7B,CAAC"}

package/dist/transports/stdio.js

@@ -1,9 +1,9 @@
-// src/transports/stdio.ts — Phase 9.1.
+// src/transports/stdio.ts
 //
 // Thin factory that connects an McpServer to a StdioServerTransport so the
-// process speaks JSON-RPC over stdin/stdout. Extracted from src/index.ts as
-// part of the multi-transport split — Task 9.2 introduces an HTTP variant
-// using the same `connect*` shape.
+// process speaks JSON-RPC over stdin/stdout. stdio is the only transport the
+// MCP server ships — it runs over stdio for both the npm/npx path and the
+// Claude Desktop DXT bundle.
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 /**
  * Connect the given McpServer to a fresh `StdioServerTransport`.

package/dist/transports/stdio.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,0EAA0E;AAC1E,mCAAmC;AAGnC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAiB;IAClD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/transports/stdio.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,EAAE;AACF,2EAA2E;AAC3E,6EAA6E;AAC7E,0EAA0E;AAC1E,6BAA6B;AAG7B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,MAAiB;IAClD,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC"}