@clovnet/plugin-sdk 0.1.4

package/dist/testing.js

@@ -0,0 +1,1010 @@
+import {
+  CATALOG_ALLOWED_KINDS,
+  CATALOG_IMPORT_TASK_TYPE,
+  DataScopes,
+  PLUGIN_CATALOG_LIMITS,
+  PLUGIN_DATASET_LIMITS,
+  PLUGIN_JOB_LIMITS,
+  PLUGIN_MIGRATION_LIMITS,
+  ReadModelRequiredScopes,
+  deriveActionSchemas,
+  generateClientPackage,
+  jsonSchemaToTsType,
+  pascalCase,
+  validateActionDecls
+} from "./chunk-XRSKWL3A.js";
+
+// src/testing/context.ts
+import { createHmac } from "crypto";
+
+// src/testing/errors.ts
+var TestContextError = class extends Error {
+  statusCode;
+  code;
+  details;
+  constructor(name, message, opts) {
+    super(message);
+    this.name = name;
+    this.statusCode = opts.statusCode;
+    this.code = opts.code;
+    this.details = opts.details;
+  }
+};
+var forbidden = (message) => new TestContextError("ForbiddenError", message, { statusCode: 403, code: "FORBIDDEN" });
+var validation = (message, details) => new TestContextError("ValidationError", message, {
+  statusCode: 400,
+  code: "VALIDATION_ERROR",
+  details
+});
+var notFound = (message) => new TestContextError("NotFoundError", message, { statusCode: 404, code: "NOT_FOUND" });
+var unauthorized = (message) => new TestContextError("UnauthorizedError", message, { statusCode: 401, code: "UNAUTHORIZED" });
+var quotaExceeded = (message, details) => new TestContextError("PluginDatasetQuotaExceededError", message, {
+  statusCode: 409,
+  code: "PLUGIN_DATASET_QUOTA_EXCEEDED",
+  details
+});
+var egressDenied = (message) => new TestContextError("PluginEgressDeniedError", message, {
+  statusCode: 403,
+  code: "PLUGIN_EGRESS_DENIED"
+});
+
+// src/testing/catalog.ts
+function catalogGrantedFor(manifest) {
+  return manifest.catalog !== void 0 && CATALOG_ALLOWED_KINDS.includes(manifest.kind);
+}
+var emptyLite = () => ({
+  providers: { inserted: 0, updated: 0 },
+  categories: { inserted: 0, updated: 0 },
+  restrictionGroups: { inserted: 0, updated: 0 },
+  currencyGroups: { inserted: 0, updated: 0 },
+  games: { inserted: 0, updated: 0, unchanged: 0 },
+  gameCategoryLinks: 0
+});
+var same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+function createCatalogMock(manifest, requestImport) {
+  const stores = {
+    providers: /* @__PURE__ */ new Map(),
+    categories: /* @__PURE__ */ new Map(),
+    restrictionGroups: /* @__PURE__ */ new Map(),
+    currencyGroups: /* @__PURE__ */ new Map(),
+    games: /* @__PURE__ */ new Map()
+  };
+  const capFamily = (family, rows) => {
+    if (rows && rows.length > PLUGIN_CATALOG_LIMITS.maxRowsPerFamily) {
+      throw validation(
+        `delta family '${family}' has ${rows.length} rows; the cap is ${PLUGIN_CATALOG_LIMITS.maxRowsPerFamily} per call`
+      );
+    }
+  };
+  const upsertInto = (store, key, value, counts) => {
+    const existing = store.get(key);
+    if (existing === void 0) {
+      store.set(key, value);
+      counts.inserted++;
+    } else if (!same(existing, value)) {
+      store.set(key, value);
+      counts.updated++;
+    } else if (counts.unchanged !== void 0) {
+      counts.unchanged++;
+    }
+  };
+  const stubProvider = (externalId, counts) => {
+    if (stores.providers.has(externalId)) return;
+    stores.providers.set(externalId, {
+      externalId,
+      name: `Provider ${externalId}`,
+      stub: true
+    });
+    counts.inserted++;
+  };
+  const applyDelta = (delta) => {
+    for (const family of [
+      "providers",
+      "categories",
+      "restrictionGroups",
+      "currencyGroups",
+      "games",
+      "gameCategories"
+    ]) {
+      capFamily(family, delta[family]);
+    }
+    const summary = emptyLite();
+    for (const p of delta.providers ?? []) {
+      upsertInto(stores.providers, p.externalId, p, summary.providers);
+    }
+    for (const r of delta.restrictionGroups ?? []) {
+      upsertInto(stores.restrictionGroups, r.externalId, r, summary.restrictionGroups);
+    }
+    for (const c of delta.currencyGroups ?? []) {
+      upsertInto(stores.currencyGroups, c.externalId, c, summary.currencyGroups);
+    }
+    for (const c of delta.categories ?? []) {
+      upsertInto(stores.categories, c.externalId, c, summary.categories);
+    }
+    for (const g of delta.games ?? []) {
+      stubProvider(g.providerExternalId, summary.providers);
+      if (g.subProviderExternalId) stubProvider(g.subProviderExternalId, summary.providers);
+      if (g.restrictionGroupExternalId && !stores.restrictionGroups.has(g.restrictionGroupExternalId)) {
+        throw validation(
+          `game '${g.externalGameId}' references unknown restriction group externalId '${g.restrictionGroupExternalId}'`
+        );
+      }
+      if (g.currencyGroupExternalId && !stores.currencyGroups.has(g.currencyGroupExternalId)) {
+        throw validation(
+          `game '${g.externalGameId}' references unknown currency group externalId '${g.currencyGroupExternalId}'`
+        );
+      }
+      for (const ext of g.categoryExternalIds) {
+        if (!stores.categories.has(ext)) {
+          throw validation(
+            `game '${g.externalGameId}' references unknown category externalId '${ext}'`
+          );
+        }
+      }
+      const existing = stores.games.get(g.externalGameId);
+      if (!existing) {
+        stores.games.set(g.externalGameId, { game: g, status: "active" });
+        summary.games.inserted++;
+      } else if (!same(existing.game, g) || existing.status !== "active") {
+        stores.games.set(g.externalGameId, { game: g, status: "active" });
+        summary.games.updated++;
+      } else {
+        summary.games.unchanged++;
+      }
+    }
+    const linkedGames = /* @__PURE__ */ new Set();
+    for (const link of delta.gameCategories ?? []) {
+      const row = stores.games.get(link.gameExternalId);
+      if (!row) {
+        throw validation(
+          `game category link references unknown game externalId '${link.gameExternalId}'`
+        );
+      }
+      if (!stores.categories.has(link.categoryExternalId)) {
+        throw validation(
+          `game category link references unknown category externalId '${link.categoryExternalId}'`
+        );
+      }
+      if (!row.game.categoryExternalIds.includes(link.categoryExternalId)) {
+        stores.games.set(link.gameExternalId, {
+          ...row,
+          game: {
+            ...row.game,
+            categoryExternalIds: [...row.game.categoryExternalIds, link.categoryExternalId]
+          }
+        });
+        linkedGames.add(link.gameExternalId);
+      }
+    }
+    summary.gameCategoryLinks = linkedGames.size;
+    return summary;
+  };
+  const upserted = (s, family) => {
+    const c = s[family];
+    return { upserted: c.inserted + c.updated };
+  };
+  const capability = {
+    async upsertBatch(delta) {
+      return applyDelta(delta);
+    },
+    async upsertProviders(providers) {
+      return upserted(applyDelta({ providers }), "providers");
+    },
+    async upsertRestrictionGroups(groups) {
+      return upserted(applyDelta({ restrictionGroups: groups }), "restrictionGroups");
+    },
+    async upsertCurrencyGroups(groups) {
+      return upserted(applyDelta({ currencyGroups: groups }), "currencyGroups");
+    },
+    async upsertCategories(categories) {
+      return upserted(applyDelta({ categories }), "categories");
+    },
+    async upsertGames(games) {
+      return upserted(applyDelta({ games }), "games");
+    },
+    async attachGameCategories(links) {
+      applyDelta({ gameCategories: links });
+    },
+    async setGameStatus(externalGameId, enabled) {
+      const row = stores.games.get(externalGameId);
+      if (!row) {
+        throw notFound(`game '${externalGameId}' not found under source 'plugin:${manifest.key}'`);
+      }
+      stores.games.set(externalGameId, { ...row, status: enabled ? "active" : "retired" });
+    },
+    async listOwnGames(q) {
+      const limit = Math.min(Math.max(1, q?.limit ?? 50), 200);
+      let rows = [...stores.games.entries()].sort(([a], [b]) => a < b ? -1 : 1);
+      if (q?.cursor !== void 0) rows = rows.filter(([key]) => key > q.cursor);
+      const page = rows.slice(0, limit);
+      const games = page.map(([externalGameId, row]) => ({
+        gameId: `mock-${externalGameId}`,
+        externalGameId,
+        slug: null,
+        name: row.game.name ?? null,
+        launchCode: row.game.launchCode ?? null,
+        providerId: `mock-provider-${row.game.providerExternalId}`,
+        status: row.status
+      }));
+      return {
+        games,
+        ...page.length === limit ? { nextCursor: page[page.length - 1][0] } : {}
+      };
+    },
+    async requestImport() {
+      return requestImport();
+    }
+  };
+  return { capability, stores };
+}
+function applyCatalogSnapshot(stores, capability, normalized) {
+  return (async () => {
+    const startedAt = Date.now();
+    const chunks = (rows) => {
+      const out = [];
+      for (let i = 0; i < rows.length; i += PLUGIN_CATALOG_LIMITS.maxRowsPerFamily) {
+        out.push(rows.slice(i, i + PLUGIN_CATALOG_LIMITS.maxRowsPerFamily));
+      }
+      return out.length ? out : [[]];
+    };
+    const total = {
+      providers: { inserted: 0, updated: 0 },
+      categories: { inserted: 0, updated: 0 },
+      restrictionGroups: { inserted: 0, updated: 0 },
+      currencyGroups: { inserted: 0, updated: 0 },
+      games: { inserted: 0, updated: 0, retired: 0, unchanged: 0 },
+      skippedUnknownCategoryLinks: 0,
+      durationMs: 0
+    };
+    const add = (a, b) => {
+      a.inserted += b.inserted;
+      a.updated += b.updated;
+    };
+    for (const providers of chunks(normalized.providers)) {
+      add(total.providers, (await capability.upsertBatch({ providers })).providers);
+    }
+    for (const restrictionGroups of chunks(normalized.restrictionGroups)) {
+      add(
+        total.restrictionGroups,
+        (await capability.upsertBatch({ restrictionGroups })).restrictionGroups
+      );
+    }
+    for (const currencyGroups of chunks(normalized.currencyGroups)) {
+      add(total.currencyGroups, (await capability.upsertBatch({ currencyGroups })).currencyGroups);
+    }
+    for (const categories of chunks(normalized.categories)) {
+      add(total.categories, (await capability.upsertBatch({ categories })).categories);
+    }
+    for (const games of chunks(normalized.games)) {
+      const s = (await capability.upsertBatch({ games })).games;
+      total.games.inserted += s.inserted;
+      total.games.updated += s.updated;
+      total.games.unchanged += s.unchanged;
+    }
+    const incoming = new Set(normalized.games.map((g) => g.externalGameId));
+    for (const [externalGameId, row] of stores.games) {
+      if (row.status === "active" && !incoming.has(externalGameId)) {
+        stores.games.set(externalGameId, { ...row, status: "retired" });
+        total.games.retired++;
+      }
+    }
+    total.durationMs = Date.now() - startedAt;
+    return total;
+  })();
+}
+
+// src/testing/context.ts
+var REDACT_KEY_RE = /secret|password|token|apikey|api_key|credential/i;
+function hostMatches(host, allowlist) {
+  const target = host.toLowerCase();
+  for (const raw of allowlist) {
+    const entry = raw.toLowerCase();
+    if (entry.startsWith("*.")) {
+      const suffix = entry.slice(1);
+      if (target.endsWith(suffix) && !target.slice(0, -suffix.length).includes(".")) return true;
+    } else if (target === entry) return true;
+  }
+  return false;
+}
+var OPTION_ONLY_KEYS = [
+  "definition",
+  "tenantId",
+  "region",
+  "settings",
+  "secrets",
+  "commandResults",
+  "httpMock",
+  "readModels",
+  "datasetQuota",
+  "sharedDatasets",
+  "datasets",
+  "http",
+  "quotas"
+];
+function isDefinitionForm(first, second) {
+  if (second !== void 0) return true;
+  if (typeof first !== "object" || first === null || !("manifest" in first)) return false;
+  return !OPTION_ONLY_KEYS.some((key) => key in first);
+}
+function createTestContext(first, second) {
+  const options = isDefinitionForm(first, second) ? { ...second ?? {}, definition: first } : first;
+  return buildTestContext(options);
+}
+function buildTestContext(options) {
+  const resolved = options.definition?.manifest ?? options.manifest;
+  if (!resolved) throw new Error("createTestContext requires a manifest (or definition)");
+  const manifest = resolved;
+  const handlers = options.definition?.handlers ?? options.handlers ?? {};
+  const hooks = options.definition?.hooks ?? options.hooks;
+  const tenantId = options.tenantId ?? "test-tenant";
+  const region = options.region ?? "eu";
+  const settings = { ...options.settings ?? {} };
+  const secrets = new Map(Object.entries(options.secrets ?? {}));
+  const allowedCommands = new Set(manifest.permissions.commands);
+  const allowedSubscribe = new Set(manifest.permissions.events.subscribe);
+  const allowedEmit = new Set(manifest.permissions.events.emit);
+  const grantedScopes = new Set(manifest.permissions.dataScopes ?? []);
+  const allowedHosts = [
+    ...manifest.network?.allowedHosts ?? [],
+    ...manifest.permissions.networkAllow ?? []
+  ];
+  const emitPrefix = `plugin.${manifest.key}.`;
+  const httpHostMocks = new Map(
+    Object.entries(options.http ?? {}).map(([host, mock]) => [host.toLowerCase(), mock])
+  );
+  const commands = [];
+  const events = [];
+  const httpExchanges = [];
+  const logs = [];
+  const tasksStarted = [];
+  const eventHandlers = /* @__PURE__ */ new Map();
+  const datasetStores = /* @__PURE__ */ new Map();
+  const storeOf = (dataset) => {
+    let store = datasetStores.get(dataset);
+    if (!store) {
+      store = /* @__PURE__ */ new Map();
+      datasetStores.set(dataset, store);
+    }
+    return store;
+  };
+  function ownCollection(dataset) {
+    const decl = manifest.datasets?.[dataset];
+    if (!decl) {
+      throw notFound(`Plugin '${manifest.key}' does not declare a dataset named '${dataset}'`);
+    }
+    const indexes = (decl.indexes ?? []).slice(0, PLUGIN_DATASET_LIMITS.maxIndexes);
+    const quota = options.quotas?.[dataset] ?? options.datasetQuota ?? decl.maxRecords ?? PLUGIN_DATASET_LIMITS.defaultMaxRecords;
+    const store = storeOf(dataset);
+    const validate = (key, value) => {
+      const parsed = decl.schema.safeParse(value);
+      if (!parsed.success) {
+        throw validation(`Record '${key}' does not match the '${dataset}' dataset schema`, {
+          issues: parsed.error.issues.slice(0, 5)
+        });
+      }
+      const data = parsed.data;
+      const keyFieldValue = data[decl.keyField];
+      if (keyFieldValue !== void 0 && String(keyFieldValue) !== key) {
+        throw validation(`Record key '${key}' does not match its '${decl.keyField}' field`);
+      }
+      const bytes = Buffer.byteLength(JSON.stringify(data), "utf8");
+      if (bytes > PLUGIN_DATASET_LIMITS.maxRecordBytes) {
+        throw validation(
+          `Record '${key}' is ${bytes} bytes; the cap is ${PLUGIN_DATASET_LIMITS.maxRecordBytes}`
+        );
+      }
+      return data;
+    };
+    return {
+      async get(key) {
+        return store.get(key)?.value ?? null;
+      },
+      async put(key, value) {
+        await this.putMany([{ key, value }]);
+      },
+      async putMany(records) {
+        if (records.length === 0) return;
+        if (records.length > PLUGIN_DATASET_LIMITS.maxBatch) {
+          throw validation(
+            `putMany accepts at most ${PLUGIN_DATASET_LIMITS.maxBatch} records per call`
+          );
+        }
+        const validated = records.map(({ key, value }) => ({ key, data: validate(key, value) }));
+        const newCount = validated.filter(({ key }) => !store.has(key)).length;
+        if (store.size + newCount > quota) {
+          throw quotaExceeded(
+            `Dataset '${manifest.key}.${dataset}' quota exceeded (${store.size}+${newCount} > ${quota})`,
+            { current: store.size, incoming: newCount, quota }
+          );
+        }
+        for (const { key, data } of validated) store.set(key, { key, value: data });
+      },
+      async delete(key) {
+        store.delete(key);
+      },
+      async query(q) {
+        for (const field of Object.keys(q.where ?? {})) {
+          if (!indexes.includes(field)) {
+            throw validation(`Field '${field}' is not an indexed field of dataset '${dataset}'`);
+          }
+        }
+        const limit = Math.min(Math.max(1, q.limit ?? 50), PLUGIN_DATASET_LIMITS.maxQueryLimit);
+        let rows = [...store.values()].sort((a, b) => a.key < b.key ? -1 : 1);
+        for (const [field, value] of Object.entries(q.where ?? {})) {
+          rows = rows.filter((r) => String(r.value[field]) === String(value));
+        }
+        if (q.cursor !== void 0) rows = rows.filter((r) => r.key > q.cursor);
+        const page = rows.slice(0, limit);
+        return {
+          records: page.map((r) => ({ key: r.key, value: r.value })),
+          ...page.length === limit ? { nextCursor: page[page.length - 1].key } : {}
+        };
+      },
+      async count() {
+        return store.size;
+      },
+      async truncate() {
+        store.clear();
+      }
+    };
+  }
+  function foreignCollection(name) {
+    const declared = manifest.permissions.datasets?.read?.includes(name) === true;
+    const fixture = options.sharedDatasets?.[name];
+    if (!declared || !fixture) {
+      throw forbidden(`Plugin '${manifest.key}' may not read dataset '${name}'`);
+    }
+    const rows = new Map(fixture.map((r) => [r.key, r]));
+    const readOnly = () => {
+      throw forbidden(`Plugin '${manifest.key}' has read-only access to '${name}'`);
+    };
+    return {
+      get: async (key) => rows.get(key)?.value ?? null,
+      query: async (q) => {
+        const limit = Math.min(Math.max(1, q.limit ?? 50), PLUGIN_DATASET_LIMITS.maxQueryLimit);
+        let sorted = [...rows.values()].sort((a, b) => a.key < b.key ? -1 : 1);
+        if (q.cursor !== void 0) sorted = sorted.filter((r) => r.key > q.cursor);
+        const page = sorted.slice(0, limit);
+        return {
+          records: page.map((r) => ({ key: r.key, value: r.value })),
+          ...page.length === limit ? { nextCursor: page[page.length - 1].key } : {}
+        };
+      },
+      count: async () => rows.size,
+      put: readOnly,
+      putMany: readOnly,
+      delete: readOnly,
+      truncate: readOnly
+    };
+  }
+  const redact = (extra) => {
+    const out = {};
+    for (const [k, v] of Object.entries(extra ?? {})) {
+      out[k] = REDACT_KEY_RE.test(k) ? "[redacted]" : v;
+    }
+    return out;
+  };
+  const log = (level) => (message, extra) => {
+    logs.push({ level, message, extra: redact(extra) });
+  };
+  const ctx = {
+    tenantId,
+    region,
+    pluginKey: manifest.key,
+    version: manifest.version,
+    commands: {
+      async execute(command, opts) {
+        if (!allowedCommands.has(command.name)) {
+          throw forbidden(
+            `Plugin '${manifest.key}' is not permitted to execute command '${command.name}'`
+          );
+        }
+        commands.push({ name: command.name, input: command.input, ...opts ?? {} });
+        const stub = options.commandResults?.[command.name];
+        if (stub instanceof Error) throw stub;
+        if (typeof stub === "function") {
+          return await stub(command.input);
+        }
+        return stub ?? {};
+      }
+    },
+    settings: {
+      get() {
+        return settings;
+      }
+    },
+    secrets: {
+      get: async (key) => secrets.get(key)
+    },
+    events: {
+      on(event, handler) {
+        if (!allowedSubscribe.has(event)) {
+          throw forbidden(`Plugin '${manifest.key}' is not permitted to subscribe to '${event}'`);
+        }
+        const list = eventHandlers.get(event) ?? [];
+        list.push(handler);
+        eventHandlers.set(event, list);
+      },
+      async emit(event) {
+        if (!event.name.startsWith(emitPrefix) || !allowedEmit.has(event.name)) {
+          throw forbidden(`Plugin '${manifest.key}' is not permitted to emit '${event.name}'`);
+        }
+        events.push(event);
+      }
+    },
+    data: {
+      async query(model, params) {
+        const required = ReadModelRequiredScopes[model];
+        if (!required) throw notFound(`Unknown read model '${String(model)}'`);
+        if (!grantedScopes.has(required)) {
+          throw forbidden(
+            `Plugin '${manifest.key}' lacks scope '${required}' for read model '${String(model)}'`
+          );
+        }
+        const fixture = options.readModels?.[model];
+        if (fixture === void 0) {
+          throw new Error(
+            `No fixture for read model '${String(model)}' \u2014 pass options.readModels['${String(model)}']`
+          );
+        }
+        const value = typeof fixture === "function" ? await fixture(params) : fixture;
+        return value;
+      }
+    },
+    datasets: {
+      collection(name) {
+        const dot = name.indexOf(".");
+        if (dot === -1 || name.slice(0, dot) === manifest.key) {
+          return ownCollection(dot === -1 ? name : name.slice(dot + 1));
+        }
+        return foreignCollection(name);
+      }
+    },
+    http: {
+      async fetch(url, init) {
+        let parsed;
+        try {
+          parsed = new URL(url);
+        } catch {
+          throw validation(`'${url}' is not a valid URL`);
+        }
+        if (parsed.protocol !== "https:") {
+          throw egressDenied(
+            `Plugin '${manifest.key}' may only call HTTPS endpoints (got ${parsed.protocol}//)`
+          );
+        }
+        if (!hostMatches(parsed.hostname, allowedHosts)) {
+          throw egressDenied(
+            `Host '${parsed.hostname}' is not in plugin '${manifest.key}' allowedHosts`
+          );
+        }
+        const real = { ...init?.headers ?? {} };
+        const redacted = { ...init?.headers ?? {} };
+        for (const [header, secretName] of Object.entries(init?.secretHeaders ?? {})) {
+          const secret = secrets.get(secretName);
+          if (secret === void 0) {
+            throw validation(`secretHeaders['${header}'] references unknown secret '${secretName}'`);
+          }
+          real[header] = secret;
+          redacted[header] = `<redacted:${secretName}>`;
+        }
+        const bodyText = init?.body === void 0 ? void 0 : typeof init.body === "string" ? init.body : JSON.stringify(init.body);
+        const request = {
+          url,
+          method: init?.method ?? "GET",
+          headers: real,
+          ...bodyText !== void 0 ? { body: bodyText } : {}
+        };
+        const hostMock = httpHostMocks.get(parsed.hostname.toLowerCase());
+        let status;
+        let text;
+        let responseHeaders;
+        if (hostMock) {
+          const response = await hostMock(request);
+          status = response.status;
+          text = typeof response.body === "string" ? response.body : JSON.stringify(response.body ?? null);
+          responseHeaders = response.headers ?? {};
+        } else {
+          if (!options.httpMock) {
+            throw new Error("ctx.http.fetch called without options.httpMock \u2014 provide one");
+          }
+          const response = await options.httpMock(request);
+          status = response.status;
+          text = response.text ?? JSON.stringify(response.json ?? null);
+          responseHeaders = response.headers ?? {};
+        }
+        httpExchanges.push({
+          url: `${parsed.origin}${parsed.pathname}`,
+          method: init?.method ?? "GET",
+          headers: redacted,
+          status
+        });
+        return {
+          status,
+          ok: status >= 200 && status < 300,
+          headers: responseHeaders,
+          bodyText: text,
+          json() {
+            return JSON.parse(text);
+          }
+        };
+      },
+      async hmacSha256(secretName, payload) {
+        const secret = secrets.get(secretName);
+        if (secret === void 0) throw validation(`Unknown secret '${secretName}'`);
+        return createHmac("sha256", secret).update(payload).digest("hex");
+      }
+    },
+    tasks: {
+      async start(type, input) {
+        tasksStarted.push({ type, ...input !== void 0 ? { input } : {} });
+        return { taskId: `test-task-${tasksStarted.length}` };
+      }
+    },
+    logger: {
+      debug: log("debug"),
+      info: log("info"),
+      warn: log("warn"),
+      error: log("error")
+    }
+  };
+  if (manifest.kind === "provider") {
+    ctx.registerProviderAdapter = (adapter) => {
+      harness.providerAdapter = adapter;
+    };
+  }
+  let catalogStores;
+  if (catalogGrantedFor(manifest)) {
+    const mock = createCatalogMock(manifest, async () => {
+      tasksStarted.push({ type: CATALOG_IMPORT_TASK_TYPE });
+      return { taskId: `test-task-${tasksStarted.length}` };
+    });
+    catalogStores = mock.stores;
+    ctx.catalog = mock.capability;
+    ctx.registerCatalogSource = (adapter) => {
+      harness.catalogSourceAdapter = adapter;
+    };
+  }
+  const findRoute = (ref) => {
+    if (typeof ref !== "string") return ref;
+    const withMethod = /^([A-Z]+)\s+(.+)$/.exec(ref);
+    const method = withMethod?.[1];
+    const path = withMethod?.[2] ?? ref;
+    const decl = (manifest.routes ?? []).find(
+      (r) => r.path === path && (method === void 0 || r.method === method)
+    );
+    if (!decl) throw notFound(`No declared route matching '${ref}'`);
+    return decl;
+  };
+  const harness = {
+    ctx,
+    commands,
+    events,
+    httpExchanges,
+    logs,
+    tasksStarted,
+    datasetStores,
+    /** In-memory catalog stores (undefined unless `manifest.catalog` granted). */
+    catalogStores,
+    providerAdapter: void 0,
+    /** Captured by `ctx.registerCatalogSource` during `runSetup()`. */
+    catalogSourceAdapter: void 0,
+    /**
+     * Run the registered catalog source adapter the way the host's reserved
+     * `catalog:import` task does: `ingest(ctx)` → apply as a full snapshot
+     * (upsert every family, RETIRE games absent from the snapshot) → summary.
+     */
+    async runImport() {
+      if (!ctx.catalog || !catalogStores) {
+        throw forbidden(`Plugin '${manifest.key}' has no catalog grant (manifest.catalog missing)`);
+      }
+      const adapter = harness.catalogSourceAdapter;
+      if (!adapter) {
+        throw notFound(
+          `Plugin '${manifest.key}' registered no catalog source adapter \u2014 call harness.runSetup() first`
+        );
+      }
+      const normalized = await adapter.ingest(ctx);
+      return applyCatalogSnapshot(catalogStores, ctx.catalog, normalized);
+    },
+    /** Deliver a domain event to handlers registered via `ctx.events.on`. */
+    async dispatch(event) {
+      for (const handler of eventHandlers.get(event.name) ?? []) {
+        await handler(event);
+      }
+    },
+    async runHook(name, ...args) {
+      const hook = hooks?.[name];
+      if (!hook) return void 0;
+      return hook(ctx, ...args);
+    },
+    async runSetup() {
+      await options.definition?.setup?.(ctx);
+    },
+    /** Zod-validate inputs per the declaration, enforce surface auth, invoke. */
+    async invokeRoute(ref, request = {}) {
+      const decl = findRoute(ref);
+      const handler = handlers.routes?.[decl.handler];
+      if (!handler) throw notFound(`Handler '${decl.handler}' not found in handlers.routes`);
+      if (decl.surface === "player" && !request.player) {
+        throw unauthorized("Player session required");
+      }
+      if (decl.surface === "admin" && !request.actor) {
+        throw unauthorized("Staff actor required");
+      }
+      if (decl.idempotent && !request.idempotencyKey) {
+        throw validation("Idempotency-Key header is required for this route");
+      }
+      const parse = (schema, value) => schema ? schema.parse(value) : value;
+      const rawBody = request.rawBody ?? JSON.stringify(request.body ?? {});
+      const headers = Object.fromEntries(
+        Object.entries(request.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v])
+      );
+      const verifySignature = async (secretName, opts) => {
+        if (request.trustSignature) return;
+        const secret = secrets.get(secretName);
+        if (!secret) throw unauthorized("Signature secret is not configured");
+        const headerName = (opts?.header ?? "x-signature").toLowerCase();
+        const provided = headers[headerName];
+        if (!provided) throw unauthorized("Missing signature");
+        const expected = createHmac(opts?.algorithm ?? "sha256", secret).update(rawBody).digest(opts?.encoding ?? "hex");
+        if (provided !== expected) throw unauthorized("Invalid signature");
+      };
+      const pluginRequest = {
+        params: parse(decl.input?.params, request.params ?? {}),
+        query: parse(decl.input?.query, request.query ?? {}),
+        body: parse(decl.input?.body, request.body),
+        ...request.player ? { player: request.player } : {},
+        ...request.actor ? { actor: request.actor } : {},
+        headers: Object.freeze(headers),
+        ...request.idempotencyKey ? { idempotencyKey: request.idempotencyKey } : {},
+        verifySignature
+      };
+      return handler(pluginRequest, ctx);
+    },
+    async runJob(name) {
+      const decl = manifest.jobs?.[name];
+      if (!decl) throw notFound(`Plugin '${manifest.key}' has no job '${name}'`);
+      const handler = handlers.jobs?.[decl.handler];
+      if (!handler) throw notFound(`Handler '${decl.handler}' not found in handlers.jobs`);
+      await handler(ctx);
+    },
+    async runTask(type, input = {}, checkpoint = null) {
+      const handler = handlers.tasks?.[type];
+      if (!handler) throw notFound(`Handler '${type}' not found in handlers.tasks`);
+      let current = checkpoint;
+      let percent = 0;
+      let message;
+      const progress = {
+        report: async (p, m) => {
+          percent = p;
+          message = m;
+        },
+        get checkpoint() {
+          return current;
+        },
+        saveCheckpoint: async (cp) => {
+          current = cp;
+        }
+      };
+      await handler(ctx, input, progress);
+      return { progress: percent, ...message !== void 0 ? { message } : {}, checkpoint: current };
+    },
+    /** Run declared migrations with semver `toVersion` (in-memory datasets). */
+    async runMigration(toVersion) {
+      const decl = (manifest.migrations ?? []).find((m) => m.toVersion === toVersion);
+      if (!decl) throw notFound(`No migration with toVersion '${toVersion}'`);
+      const handler = handlers.migrations?.[decl.handler];
+      if (!handler) throw notFound(`Handler '${decl.handler}' not found in handlers.migrations`);
+      let totalProcessed = 0;
+      const helper = {
+        async transformDataset(dataset, transform) {
+          const store = storeOf(dataset);
+          const collection = ownCollection(dataset);
+          const keys = [...store.keys()].sort();
+          let processed = 0;
+          for (let i = 0; i < keys.length; i += PLUGIN_MIGRATION_LIMITS.batchSize) {
+            const batch = keys.slice(i, i + PLUGIN_MIGRATION_LIMITS.batchSize);
+            const out = [];
+            for (const key of batch) {
+              const result = await transform({
+                key,
+                value: store.get(key).value
+              });
+              if (result) out.push(result);
+            }
+            if (out.length > 0) await collection.putMany(out);
+            processed += batch.length;
+          }
+          totalProcessed += processed;
+          return { processed };
+        }
+      };
+      await handler(ctx, helper);
+      return { processed: totalProcessed };
+    },
+    /** Seed a dataset store directly (bypasses schema — arrange step only). */
+    seedDataset(dataset, records) {
+      const store = storeOf(dataset);
+      for (const r of records) store.set(r.key, { key: r.key, value: r.value });
+    },
+    setSecret(key, value) {
+      if (value === void 0) secrets.delete(key);
+      else secrets.set(key, value);
+    },
+    setSettings(next) {
+      Object.assign(settings, next);
+    }
+  };
+  for (const [dataset, records] of Object.entries(options.datasets ?? {})) {
+    harness.seedDataset(
+      dataset,
+      records.map((r) => ({ key: r.key, value: r.value }))
+    );
+  }
+  const recorder = {
+    commands,
+    events,
+    http: httpExchanges,
+    logs,
+    tasksStarted
+  };
+  return {
+    ctx,
+    harness,
+    recorder,
+    // Top-level aliases of the harness runners (§10 ergonomics). These are
+    // direct references — the harness methods close over module state and
+    // must stay `this`-free (runImport, which uses `harness.`, is not aliased).
+    runHook: harness.runHook,
+    runJob: harness.runJob,
+    runTask: harness.runTask,
+    runMigration: harness.runMigration,
+    invokeRoute: harness.invokeRoute,
+    dispatch: harness.dispatch,
+    runSetup: harness.runSetup,
+    seedDataset: harness.seedDataset,
+    setSettings: harness.setSettings,
+    setSecret: harness.setSecret
+  };
+}
+
+// src/testing/validate.ts
+var ROUTE_PATH_RE = /^\/[A-Za-z0-9_\-./:%]*$/;
+var SURFACES = /* @__PURE__ */ new Set(["public", "player", "admin", "callback"]);
+var HOST_RE = /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/i;
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
+var KEY_RE = /^[a-z0-9][a-z0-9-]*$/;
+function isValidCronSyntax(expression) {
+  const fields = expression.trim().split(/\s+/);
+  if (fields.length !== 5) return false;
+  return fields.every((f) => /^[0-9*,/-]+$/.test(f));
+}
+function validateManifest(definition) {
+  const errors = [];
+  const warnings = [];
+  const manifest = definition.manifest;
+  const handlers = definition.handlers ?? {};
+  if (!KEY_RE.test(manifest.key)) errors.push(`key '${manifest.key}': must be a lowercase slug`);
+  if (!SEMVER_RE.test(manifest.version)) {
+    errors.push(`version '${manifest.version}': not SemVer x.y.z`);
+  }
+  const emitPrefix = `plugin.${manifest.key}.`;
+  for (const emitted of manifest.permissions.events.emit) {
+    if (!emitted.startsWith(emitPrefix)) {
+      errors.push(`emitted event '${emitted}' must be namespaced '${emitPrefix}*'`);
+    }
+  }
+  const seenRoutes = /* @__PURE__ */ new Set();
+  for (const route of manifest.routes ?? []) {
+    const label = `${route.method} ${route.surface}${route.path}`;
+    if (!SURFACES.has(route.surface)) errors.push(`route ${label}: unknown surface`);
+    if (!ROUTE_PATH_RE.test(route.path) || route.path.includes("..")) {
+      errors.push(`route ${label}: path must look like '/lobby' or '/games/:gameKey'`);
+    }
+    const dup = `${route.surface} ${route.method} ${route.path}`;
+    if (seenRoutes.has(dup)) errors.push(`route ${label}: duplicate declaration`);
+    seenRoutes.add(dup);
+    if (!handlers.routes?.[route.handler]) {
+      errors.push(`route ${label}: handler '${route.handler}' not found in handlers.routes`);
+    } else if (route.surface === "callback") {
+      const src = handlers.routes[route.handler].toString();
+      if (!src.includes("verifySignature")) {
+        errors.push(
+          `route ${label}: callback handlers must call req.verifySignature(...) before trusting the body`
+        );
+      }
+    }
+  }
+  for (const [name, decl] of Object.entries(manifest.datasets ?? {})) {
+    const fields = Object.keys(decl.schema.shape);
+    if (!fields.includes(decl.keyField)) {
+      errors.push(`dataset '${name}': keyField '${decl.keyField}' is not a schema field`);
+    }
+    const indexes = decl.indexes ?? [];
+    if (indexes.length > PLUGIN_DATASET_LIMITS.maxIndexes) {
+      errors.push(`dataset '${name}': at most ${PLUGIN_DATASET_LIMITS.maxIndexes} indexes`);
+    }
+    for (const idx of indexes) {
+      if (!fields.includes(idx)) {
+        errors.push(`dataset '${name}': index '${idx}' is not a top-level schema field`);
+      }
+    }
+  }
+  for (const [name, decl] of Object.entries(manifest.jobs ?? {})) {
+    if (!isValidCronSyntax(decl.schedule)) {
+      errors.push(`job '${name}': '${decl.schedule}' is not a 5-field cron expression`);
+    }
+    if (!handlers.jobs?.[decl.handler]) {
+      errors.push(`job '${name}': handler '${decl.handler}' not found in handlers.jobs`);
+    }
+    if (decl.timeoutSec !== void 0 && (decl.timeoutSec < 1 || decl.timeoutSec > PLUGIN_JOB_LIMITS.maxTimeoutSec)) {
+      errors.push(`job '${name}': timeoutSec must be 1..${PLUGIN_JOB_LIMITS.maxTimeoutSec}`);
+    }
+  }
+  if (manifest.install?.seedTask && !handlers.tasks?.[manifest.install.seedTask]) {
+    errors.push(`install.seedTask '${manifest.install.seedTask}' not found in handlers.tasks`);
+  }
+  for (const migration of manifest.migrations ?? []) {
+    if (!SEMVER_RE.test(migration.toVersion)) {
+      errors.push(`migration '${migration.toVersion}': not a valid SemVer version`);
+    }
+    if (!handlers.migrations?.[migration.handler]) {
+      errors.push(
+        `migration '${migration.toVersion}': handler '${migration.handler}' not found in handlers.migrations`
+      );
+    }
+  }
+  for (const host of manifest.network?.allowedHosts ?? []) {
+    if (!HOST_RE.test(host)) {
+      errors.push(`network.allowedHosts '${host}': exact host or '*.example.com' only`);
+    }
+  }
+  const knownScopes = new Set(DataScopes);
+  for (const scope of manifest.permissions.dataScopes ?? []) {
+    if (!knownScopes.has(scope)) {
+      warnings.push(`dataScope '${scope}' is not a v2 scope \u2014 it grants no read models`);
+    }
+  }
+  for (const dep of manifest.permissions.datasets?.read ?? []) {
+    if (!dep.includes(".")) {
+      errors.push(`permissions.datasets.read '${dep}': must be '<ownerPluginKey>.<dataset>'`);
+    }
+  }
+  const adminRoutes = new Set(
+    (manifest.routes ?? []).filter((r) => r.surface === "admin").map((r) => r.path)
+  );
+  const pageKeys = /* @__PURE__ */ new Set();
+  for (const page of manifest.surfaces?.backoffice?.pages ?? []) {
+    if (pageKeys.has(page.key)) errors.push(`surface page '${page.key}': duplicate key`);
+    pageKeys.add(page.key);
+    for (const block of page.blocks) {
+      const ref = "dataRoute" in block ? block.dataRoute : block.submitRoute;
+      if (!adminRoutes.has(ref)) {
+        errors.push(`surface page '${page.key}': '${ref}' is not a declared admin route`);
+      }
+    }
+  }
+  for (const nav of manifest.surfaces?.backoffice?.nav ?? []) {
+    if (!pageKeys.has(nav.pageKey)) {
+      errors.push(`surface nav '${nav.label}': pageKey '${nav.pageKey}' has no page`);
+    }
+  }
+  const actionIssues = validateActionDecls(definition);
+  errors.push(...actionIssues.errors);
+  warnings.push(...actionIssues.warnings);
+  return { ok: errors.length === 0, errors, warnings };
+}
+export {
+  TestContextError,
+  catalogGrantedFor,
+  createTestContext,
+  deriveActionSchemas,
+  generateClientPackage,
+  isValidCronSyntax,
+  jsonSchemaToTsType,
+  pascalCase,
+  validateActionDecls,
+  validateManifest
+};
+//# sourceMappingURL=testing.js.map