@crvouga/mockingbird-service-junction 1.8.2 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crvouga/mockingbird-service-junction",
-  "version": "1.8.2",
+  "version": "2.0.0",
   "description": "Stateful mock of the Junction (Vital) user API driven by its OpenAPI contract and verified by differential property tests against the Junction sandbox.",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,10 @@
   "files": [
     "dist",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "DISCOVERY.md",
+    "SUPPORT.md",
+    "openapi.yaml"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -62,7 +65,29 @@
     "parityTier": "cold",
     "parityInputs": [
       "PARITY_FAILURE_SEED_REGISTRY.json"
-    ]
+    ],
+    "discovery": {
+      "guide": "DISCOVERY.md",
+      "behavior": "README.md",
+      "capabilities": "SUPPORT.md",
+      "contract": "openapi.yaml",
+      "types": "dist/index.d.ts",
+      "oracle": {
+        "kind": "Live vendor API or sandbox",
+        "command": "bun run parity:service -- junction",
+        "note": "Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2."
+      },
+      "introspection": [
+        "GET /__admin/health",
+        "GET /__admin",
+        "GET /__admin/state",
+        "GET /__admin/requests",
+        "GET /__admin/metrics",
+        "GET /__admin/faults/presets",
+        "GET /__admin/ui"
+      ],
+      "reporting": "https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md"
+    }
   },
   "scripts": {
     "generate": "bun ../../openapi/codegen/dist/cli.js",
@@ -86,7 +111,7 @@
     "verify": "bun src/cli.ts verify"
   },
   "dependencies": {
-    "@crvouga/mockingbird-service-sqlite": "1.3.0",
+    "@crvouga/mockingbird-service-sqlite": "2.0.0",
     "hono": "4.11.9"
   },
   "devDependencies": {

package/dist/chunk-4QHCRJO4.js

@@ -1,540 +0,0 @@
-import {
-  IDENTITY_MODES,
-  createRuntime,
-  defaultBillingTypesFrom,
-  pullCorpus
-} from "./chunk-ADSZBAJZ.js";
-import {
-  defaultCorpus
-} from "./chunk-C2UGIPPM.js";
-import {
-  parseSealedCorpus
-} from "./chunk-ISDNA2TU.js";
-
-// src/server.ts
-import { readFile as readFile2 } from "node:fs/promises";
-
-// ../../adapters/node/dist/cli.js
-import { readFile } from "node:fs/promises";
-import { parseArgs } from "node:util";
-
-// ../../adapters/node/dist/serve.js
-import { createServer } from "node:http";
-var serve = async (api, options = {}) => {
-  const server = createServer(async (req, res) => {
-    const chunks = [];
-    for await (const chunk of req) {
-      chunks.push(Buffer.from(chunk));
-    }
-    const body = Buffer.concat(chunks);
-    const address = server.address();
-    const port = typeof address === "object" && address !== null ? address.port : void 0;
-    const base = `http://${req.headers.host ?? `localhost:${port ?? 80}`}`;
-    const raw = req.url ?? "/";
-    const url = new URL(raw.replace(/^\/+/, "/"), base);
-    const method = req.method ?? "GET";
-    const init = { method, headers: req.headers };
-    if (method !== "GET" && method !== "HEAD" && body.length > 0) {
-      init.body = body;
-    }
-    const aborted = new AbortController();
-    res.once("close", () => {
-      if (!res.writableFinished)
-        aborted.abort();
-    });
-    init.signal = aborted.signal;
-    const request = new Request(url, init);
-    let response;
-    try {
-      response = await api.fetch(request);
-    } catch (error) {
-      if (error.code === "MOCKINGBIRD_DROP") {
-        req.socket.destroy();
-        return;
-      }
-      res.writeHead(500, { "content-type": "application/json" });
-      res.end(JSON.stringify({
-        error: {
-          type: "mockingbird_internal",
-          message: error instanceof Error ? error.message : String(error)
-        }
-      }));
-      return;
-    }
-    const headers = Object.fromEntries(response.headers);
-    const cookies = response.headers.getSetCookie();
-    if (cookies.length > 0)
-      headers["set-cookie"] = cookies;
-    if (!response.body) {
-      res.writeHead(response.status, headers);
-      res.end();
-      return;
-    }
-    res.writeHead(response.status, headers);
-    res.flushHeaders();
-    const reader = response.body.getReader();
-    try {
-      for (; ; ) {
-        const { done, value } = await reader.read();
-        if (done)
-          break;
-        if (!res.write(value))
-          await new Promise((resolve) => res.once("drain", resolve));
-      }
-      res.end();
-    } catch {
-      res.destroy();
-    } finally {
-      reader.releaseLock();
-    }
-  });
-  await new Promise((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(options.port ?? 0, options.host, resolve);
-  });
-  return server;
-};
-
-// ../../adapters/node/dist/listen.js
-var listen = async (api, options = {}) => {
-  const host = options.host ?? "127.0.0.1";
-  const server = await serve(api, { port: options.port ?? 0, host });
-  const address = server.address();
-  const port = typeof address === "object" && address !== null ? address.port : options.port ?? 0;
-  const shown = host.includes(":") ? `[${host}]` : host;
-  return {
-    url: `http://${shown}:${port}`,
-    port,
-    host,
-    server,
-    close: () => new Promise((resolve, reject) => {
-      server.close((error) => {
-        if (error && error.code !== "ERR_SERVER_NOT_RUNNING")
-          reject(error);
-        else
-          resolve();
-      });
-      server.closeAllConnections?.();
-    })
-  };
-};
-
-// ../../adapters/node/dist/cli.js
-var optionHelp = (options) => Object.entries(options).map(([name, option]) => {
-  const flag = `--${name}${option.type === "string" ? ` ${option.value ?? "<value>"}` : ""}`;
-  const fallback = option.default !== void 0 ? ` (default: ${String(option.default)})` : "";
-  return `  ${flag.padEnd(30)} ${option.description}${fallback}`;
-});
-var help = (spec) => [
-  `${spec.bin} \u2014 ${spec.description}`,
-  "",
-  "Usage:",
-  `  ${spec.bin} <command> [options]`,
-  "",
-  "Commands:",
-  ...Object.entries(spec.commands).map(([name, c]) => `  ${name.padEnd(30)} ${c.summary}`),
-  "",
-  `Run \`${spec.bin} <command> --help\` for a command's options.`
-].join("\n");
-var commandHelp = (spec, name, command) => [
-  `${spec.bin} ${name} \u2014 ${command.summary}`,
-  "",
-  "Usage:",
-  `  ${command.usage ?? `${spec.bin} ${name} [options]`}`,
-  ...command.options ? ["", "Options:", ...optionHelp(command.options)] : []
-].join("\n");
-var runCli = async (spec, argv) => {
-  const pair = argv.length >= 2 ? `${argv[0]} ${argv[1]}` : void 0;
-  const words = pair !== void 0 && spec.commands[pair] ? 2 : 1;
-  const name = words === 2 ? pair : argv[0];
-  const rest = argv.slice(words);
-  if (name === void 0 || name === "--help" || name === "-h" || name === "help") {
-    console.log(help(spec));
-    return 0;
-  }
-  const command = spec.commands[name];
-  if (!command) {
-    console.error(`${spec.bin}: unknown command ${JSON.stringify(name)}
-
-${help(spec)}`);
-    return 2;
-  }
-  if (rest.includes("--help") || rest.includes("-h")) {
-    console.log(commandHelp(spec, name, command));
-    return 0;
-  }
-  let parsed;
-  try {
-    parsed = parseArgs({
-      args: rest,
-      allowPositionals: true,
-      strict: true,
-      options: Object.fromEntries(Object.entries(command.options ?? {}).map(([key, option]) => [
-        key,
-        {
-          type: option.type,
-          ...option.default !== void 0 ? { default: option.default } : {}
-        }
-      ]))
-    });
-  } catch (error) {
-    console.error(`${spec.bin} ${name}: ${error instanceof Error ? error.message : String(error)}
-
-${commandHelp(spec, name, command)}`);
-    return 2;
-  }
-  return command.run(parsed.values, parsed.positionals);
-};
-var COMMON_SERVE_OPTIONS = {
-  port: { type: "string", value: "<port>", description: "Port to listen on" },
-  host: { type: "string", value: "<host>", description: "Interface to bind", default: "127.0.0.1" },
-  "admin-key": {
-    type: "string",
-    value: "<key>",
-    description: "Require x-mockingbird-admin-key on /__admin/* (env MOCKINGBIRD_ADMIN_KEY)"
-  },
-  seed: { type: "string", value: "<seed>", description: "Seed for every random choice" },
-  log: {
-    type: "string",
-    value: "<pretty|json|off>",
-    description: "Request log format",
-    default: "pretty"
-  },
-  "log-requests": {
-    type: "boolean",
-    description: "One JSON line per request: namespace, operationId, status, ids touched (never bodies). Same as --log json"
-  },
-  config: {
-    type: "string",
-    value: "<file>",
-    description: "Serve every service in a mockingbird.json config instead"
-  }
-};
-var formatLog = (format) => {
-  if (format === "off")
-    return void 0;
-  if (format === "json")
-    return (entry) => console.log(JSON.stringify(entry));
-  return (entry) => {
-    const op = entry.operationId ?? (entry.unmatched ? "UNMATCHED" : "-");
-    const ns = entry.namespace === "default" ? "" : ` [${entry.namespace}]`;
-    const fault = entry.faultId ? ` fault=${entry.faultId}` : "";
-    const adopted = entry.adopted ? " adopted" : "";
-    const received = entry.request ? ` received=${entry.request.bodyBytes === null ? "?" : `${entry.request.bodyBytes}B`} ct=${entry.request.contentType ?? "-"}${entry.request.transferEncoding ? ` te=${entry.request.transferEncoding}` : ""}` : "";
-    const issues = entry.issues?.length ? ` issues=${entry.issues.slice(0, 3).map((issue) => `${issue.path || "$"}: ${issue.message}`).join("; ")}${entry.issues.length > 3 ? ` (+${entry.issues.length - 3})` : ""}` : "";
-    console.log(`${entry.service} ${entry.method} ${entry.path} ${entry.status} ${op} ${entry.durationMs}ms${ns}${fault}${adopted}${received}${issues}`);
-  };
-};
-var asString = (value) => typeof value === "string" ? value : void 0;
-var loadTarget = async (name, own) => {
-  if (name === own.name)
-    return own;
-  const specifier = `@crvouga/mockingbird-service-${name}/server`;
-  try {
-    const mod = await import(specifier);
-    if (!mod.serveTarget)
-      throw new Error(`${specifier} exports no serveTarget`);
-    return mod.serveTarget;
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    throw new Error(`cannot load service "${name}": ${reason}. Install @crvouga/mockingbird-service-${name}.`);
-  }
-};
-var start = async (target, values, config) => {
-  const runtime = await target.create(values, {
-    adminKey: config.adminKey,
-    seed: config.seed,
-    onLog: formatLog(config.log)
-  });
-  const listening = await listen(runtime, { port: config.port, host: config.host });
-  target.listening?.(listening);
-  console.log(`${target.name} mock listening on ${listening.url}`);
-  console.log(`${target.name} health: GET ${listening.url}/health`);
-  console.log(`${target.name} admin: ${listening.url}/__admin (${config.adminKey ? "x-mockingbird-admin-key required" : "open \u2014 pass --admin-key to lock"})`);
-  console.log(`${target.name} admin ui: ${listening.url}/__admin/ui`);
-  for (const line of target.banner?.(runtime) ?? [])
-    console.log(`${target.name} ${line}`);
-  return listening;
-};
-var untilSignal = async (servers) => new Promise((resolve) => {
-  const stop = async () => {
-    await Promise.allSettled(servers.map((s) => s.close()));
-    resolve(0);
-  };
-  process.once("SIGINT", stop);
-  process.once("SIGTERM", stop);
-});
-var serveCommand = (target) => ({
-  summary: `Serve the ${target.name} mock over HTTP`,
-  options: { ...COMMON_SERVE_OPTIONS, ...target.options },
-  async run(values) {
-    const log = values["log-requests"] === true ? "json" : asString(values.log) ?? "pretty";
-    if (!["pretty", "json", "off"].includes(log)) {
-      console.error(`--log must be pretty, json or off (got ${log})`);
-      return 2;
-    }
-    const configPath = asString(values.config);
-    if (configPath !== void 0) {
-      const config = JSON.parse(await readFile(configPath, "utf8"));
-      const servers = [];
-      try {
-        for (const [name, entry] of Object.entries(config.services ?? {})) {
-          const each = await loadTarget(name, target);
-          servers.push(await start(each, entry.options ?? {}, {
-            port: entry.port ?? each.defaultPort,
-            host: entry.host ?? "127.0.0.1",
-            ...entry.adminKey !== void 0 ? { adminKey: entry.adminKey } : {},
-            ...entry.seed !== void 0 ? { seed: entry.seed } : {},
-            log: config.log ?? log
-          }));
-        }
-      } catch (error) {
-        await Promise.allSettled(servers.map((s) => s.close()));
-        console.error(error instanceof Error ? error.message : String(error));
-        return 1;
-      }
-      return untilSignal(servers);
-    }
-    const port = asString(values.port);
-    const adminKey = asString(values["admin-key"]) ?? process.env.MOCKINGBIRD_ADMIN_KEY;
-    const seed = asString(values.seed);
-    let listening;
-    try {
-      listening = await start(target, values, {
-        port: port === void 0 ? target.defaultPort : Number.parseInt(port, 10),
-        host: asString(values.host) ?? "127.0.0.1",
-        ...adminKey !== void 0 ? { adminKey } : {},
-        ...seed !== void 0 ? { seed } : {},
-        log
-      });
-    } catch (error) {
-      console.error(error instanceof Error ? error.message : String(error));
-      return 1;
-    }
-    return untilSignal([listening]);
-  }
-});
-
-// src/server.ts
-var DEFAULT_PORT = 8787;
-var loadCorpus = async (source) => {
-  if (typeof source !== "string") return source;
-  if (source === "none") return void 0;
-  if (source === "default") return defaultCorpus;
-  const raw = await readFile2(source, "utf8").catch(() => void 0);
-  if (raw === void 0) throw new Error(`junction mock corpus not found: ${source}`);
-  return parseSealedCorpus(JSON.parse(raw));
-};
-var createServer2 = async (options = {}) => {
-  const { port, host, corpus: source, ...rest } = options;
-  const corpus = await loadCorpus(source ?? "default");
-  const runtime = createRuntime({ ...rest, ...corpus ? { corpus } : {} });
-  const listening = await listen(runtime, {
-    port: port ?? 0,
-    ...host !== void 0 ? { host } : {}
-  });
-  return { ...listening, runtime };
-};
-var asString2 = (value) => typeof value === "string" && value !== "" ? value : void 0;
-var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-var count = (value, flag) => {
-  if (value === void 0) return void 0;
-  if (!/^\d+$/.test(value)) throw new Error(`${flag} must be a non-negative integer (got ${value})`);
-  return Number.parseInt(value, 10);
-};
-var readJson = async (path) => {
-  const raw = await readFile2(path, "utf8").catch(() => void 0);
-  if (raw === void 0) throw new Error(`junction mock: file not found: ${path}`);
-  try {
-    return JSON.parse(raw);
-  } catch (error) {
-    throw new Error(`junction mock: ${path} is not JSON (${error.message})`);
-  }
-};
-var retryDelays = (value) => {
-  if (value === void 0) return void 0;
-  const delays = value.split(",").map((part) => Number.parseInt(part.trim(), 10));
-  if (delays.some((delay) => !Number.isFinite(delay) || delay < 0)) {
-    throw new Error(`--webhook-retry-delays must be comma-separated milliseconds (got ${value})`);
-  }
-  return delays;
-};
-var billingDefaults = (value) => {
-  if (value === void 0) return void 0;
-  const entries = value.split(",").map((part) => part.split("=").map((side) => side.trim()));
-  if (entries.some((entry) => entry.length !== 2 || !entry[0] || !entry[1])) {
-    throw new Error(`--default-billing-type must be lab=billing_type pairs (got ${value})`);
-  }
-  try {
-    return defaultBillingTypesFrom(Object.fromEntries(entries));
-  } catch (error) {
-    throw new Error(`--default-billing-type: ${error.message}`);
-  }
-};
-var serveTarget = {
-  name: "junction",
-  defaultPort: DEFAULT_PORT,
-  options: {
-    corpus: {
-      type: "string",
-      value: "<default|none|file>",
-      description: "Corpus to serve: the shipped one, none (synthetic), or a pulled file",
-      default: "default"
-    },
-    geo: {
-      type: "string",
-      value: "<corpus|synthetic>",
-      description: "Unknown ZIPs: refuse (corpus) or invent coverage (synthetic)"
-    },
-    "lab-accounts": {
-      type: "string",
-      value: "<file>",
-      description: 'Lab accounts to route orders through: a JSON array, or { "presets": [...], "accounts": [...] }'
-    },
-    "team-id": {
-      type: "string",
-      value: "<uuid>",
-      description: "Team the mock answers as (default: the corpus's recorded team)"
-    },
-    "max-users": {
-      type: "string",
-      value: "<n>",
-      description: "Enforce the sandbox's live-user cap (default: unlimited)"
-    },
-    identity: {
-      type: "string",
-      value: "<strict|adopt-users>",
-      description: "Unknown user ids: 404 (strict) or create on first use",
-      default: "strict"
-    },
-    "default-billing-type": {
-      type: "string",
-      value: "<lab=type,\u2026>",
-      description: "billing_type an order for that lab gets when it omits one (default: client_bill), e.g. bioreference=patient_bill_passthrough"
-    },
-    fixtures: {
-      type: "string",
-      value: "<file>",
-      description: 'Users and orders every namespace starts with: { "users": [...], "orders": [...] }'
-    },
-    "journal-size": {
-      type: "string",
-      value: "<n>",
-      description: "Requests each namespace's journal keeps (GET /__admin/requests)",
-      default: "1000"
-    },
-    "seed-url": {
-      type: "string",
-      value: "<url>",
-      description: "Pull a corpus from this Junction team at boot (prefer a committed corpus)"
-    },
-    "seed-key": {
-      type: "string",
-      value: "<key>",
-      description: "API key for --seed-url (env MOCKINGBIRD_JUNCTION_SEED_KEY)"
-    },
-    "webhook-url": { type: "string", value: "<url>", description: "Deliver signed webhooks here" },
-    "webhook-secret": {
-      type: "string",
-      value: "<whsec_\u2026>",
-      description: "Svix signing secret (env MOCKINGBIRD_JUNCTION_WEBHOOK_SECRET)"
-    },
-    "webhook-retry-delays": {
-      type: "string",
-      value: "<ms,ms,\u2026>",
-      description: "Delay before each delivery attempt (default: Svix's schedule)"
-    },
-    "webhook-scope": {
-      type: "string",
-      value: "<scope>",
-      description: "Sent as x-mockingbird-scope on every delivery"
-    }
-  },
-  async create(values, common) {
-    const seedUrl = asString2(values["seed-url"]);
-    const seedKey = asString2(values["seed-key"]) ?? process.env.MOCKINGBIRD_JUNCTION_SEED_KEY;
-    let corpus;
-    if (seedUrl !== void 0) {
-      if (seedKey === void 0) throw new Error("--seed-url needs --seed-key");
-      console.log(
-        `junction pulling a corpus from ${seedUrl} (commit one with \`corpus pull\` to skip this)`
-      );
-      corpus = await pullCorpus({ baseUrl: seedUrl, apiKey: seedKey });
-    } else {
-      corpus = await loadCorpus(asString2(values.corpus) ?? "default");
-    }
-    const geo = asString2(values.geo);
-    if (geo !== void 0 && geo !== "corpus" && geo !== "synthetic") {
-      throw new Error(`--geo must be corpus or synthetic (got ${geo})`);
-    }
-    const accountsFile = asString2(values["lab-accounts"]);
-    const labAccounts = accountsFile === void 0 ? void 0 : await readJson(accountsFile);
-    const fixturesFile = asString2(values.fixtures);
-    const fixtures = fixturesFile === void 0 ? void 0 : await readJson(fixturesFile);
-    const teamId = asString2(values["team-id"]);
-    if (teamId !== void 0 && !UUID.test(teamId)) {
-      throw new Error(`--team-id must be a UUID (got ${teamId})`);
-    }
-    const maxUsers = count(asString2(values["max-users"]), "--max-users");
-    const journalSize = count(asString2(values["journal-size"]), "--journal-size");
-    const identity = asString2(values.identity);
-    if (identity !== void 0 && !IDENTITY_MODES.includes(identity)) {
-      throw new Error(`--identity must be one of ${IDENTITY_MODES.join(", ")} (got ${identity})`);
-    }
-    const defaultBillingTypes = billingDefaults(asString2(values["default-billing-type"]));
-    const webhookUrl = asString2(values["webhook-url"]);
-    const webhookSecret = asString2(values["webhook-secret"]) ?? process.env.MOCKINGBIRD_JUNCTION_WEBHOOK_SECRET;
-    if (webhookUrl !== void 0 && webhookSecret === void 0) {
-      throw new Error("--webhook-url needs --webhook-secret (the whsec_\u2026 your receiver verifies)");
-    }
-    const delays = retryDelays(asString2(values["webhook-retry-delays"]));
-    const scope = asString2(values["webhook-scope"]);
-    return createRuntime({
-      ...corpus ? { corpus } : {},
-      ...geo ? { geo } : {},
-      ...labAccounts ? { labAccounts } : {},
-      ...fixtures ? { fixtures } : {},
-      ...teamId !== void 0 ? { teamId } : {},
-      ...maxUsers !== void 0 ? { limits: { maxUsers } } : {},
-      ...identity !== void 0 ? { identity } : {},
-      ...defaultBillingTypes ? { defaultBillingTypes } : {},
-      ...journalSize !== void 0 ? { journalSize } : {},
-      ...webhookUrl !== void 0 && webhookSecret !== void 0 ? {
-        webhooks: {
-          url: webhookUrl,
-          secret: webhookSecret,
-          ...delays ? { retryDelaysMs: delays } : {},
-          ...scope ? { headers: { "x-mockingbird-scope": scope } } : {}
-        }
-      } : {},
-      ...common.adminKey !== void 0 ? { adminKey: common.adminKey } : {},
-      ...common.seed !== void 0 ? { seed: common.seed } : {},
-      ...common.onLog ? { onLog: common.onLog } : {}
-    });
-  },
-  banner(runtime) {
-    const junction = runtime;
-    const api = junction.instance();
-    const info = api.corpusInfo();
-    return [
-      info ? `corpus ${info.label}: ${info.observations} observations, ${info.zips} ZIPs, ${info.labTests} lab tests, ${info.labAccounts} lab accounts (recorded ${info.recordedAt} from ${info.source})` : "corpus none: synthetic catalog and coverage",
-      `geo ${api.geoMode}${api.geoMode === "corpus" ? " (unknown ZIPs answer 424 MOCKINGBIRD_UNKNOWN_ZIP)" : ""}`,
-      `team ${api.teamId}`,
-      `lab accounts: ${api.labAccounts().length}`,
-      `limits: ${Object.entries(api.limits).filter(([, value]) => value !== null && value !== false).map(([key, value]) => `${key}=${String(value)}`).join(", ") || "none (sandbox caps off)"}`,
-      `identity ${api.identity}`,
-      `webhooks: ${junction.webhooks ? "signed delivery on" : "off"}`,
-      "auth: any x-vital-api-key value (e.g. sk_us_mockingbird)"
-    ];
-  }
-};
-
-export {
-  runCli,
-  serveCommand,
-  DEFAULT_PORT,
-  loadCorpus,
-  createServer2 as createServer,
-  serveTarget
-};
-//# sourceMappingURL=chunk-4QHCRJO4.js.map