stubsmith 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,575 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { realpathSync } from "fs";
+import { pathToFileURL } from "url";
+
+// src/_version.ts
+var VERSION = "0.2.0";
+
+// src/pull.ts
+import { randomBytes } from "crypto";
+import { promises as fsp } from "fs";
+import path from "path";
+
+// src/env.ts
+var DEFAULT_BACKEND_URL = "https://app.stubsmith.dev/api";
+function env(name) {
+  return process.env[name];
+}
+function resolveApiUrl() {
+  return env("STUBSMITH_API_URL") || env("STUBSMITH_BACKEND_URL") || DEFAULT_BACKEND_URL;
+}
+
+// src/internal/codepoint.ts
+function compareCodePoints(a, b) {
+  const la = a.length;
+  const lb = b.length;
+  let i = 0;
+  let j = 0;
+  while (i < la && j < lb) {
+    const pa = a.codePointAt(i);
+    const pb = b.codePointAt(j);
+    if (pa !== pb) return pa < pb ? -1 : 1;
+    i += pa > 65535 ? 2 : 1;
+    j += pb > 65535 ? 2 : 1;
+  }
+  if (i < la) return 1;
+  if (j < lb) return -1;
+  return 0;
+}
+
+// src/replayState.ts
+import { AsyncLocalStorage } from "async_hooks";
+import http from "http";
+import https from "https";
+var DEPTH_KEY = /* @__PURE__ */ Symbol.for("stubsmith.replayDepth");
+var GUARD_KEY = /* @__PURE__ */ Symbol.for("stubsmith.captureGuard");
+var REQUEST_KEY = /* @__PURE__ */ Symbol.for("stubsmith.originalRequest");
+var g = globalThis;
+function sharedSlot(key, init) {
+  if (g[key] === void 0) g[key] = init();
+  return g[key];
+}
+var depth = sharedSlot(DEPTH_KEY, () => ({ n: 0 }));
+var captureGuard = sharedSlot(GUARD_KEY, () => new AsyncLocalStorage());
+var ORIGINAL_REQUEST = sharedSlot(REQUEST_KEY, () => ({
+  http: http.request,
+  https: https.request
+}));
+
+// src/transport.ts
+var HOLD_TOTAL_MS = 12e4;
+function sendRequest(url, opts) {
+  let req = null;
+  let aborted = false;
+  const abort = () => {
+    aborted = true;
+    req?.destroy(new Error("aborted"));
+  };
+  const promise = new Promise((resolve, reject) => {
+    let settled = false;
+    let total = null;
+    const fail = (err2) => {
+      if (settled) return;
+      settled = true;
+      if (total) clearTimeout(total);
+      reject(err2 instanceof Error ? err2 : new Error(String(err2)));
+    };
+    const succeed = (r2) => {
+      if (settled) return;
+      settled = true;
+      if (total) clearTimeout(total);
+      resolve(r2);
+    };
+    let u;
+    try {
+      u = new URL(url);
+    } catch (err2) {
+      fail(err2);
+      return;
+    }
+    const request = u.protocol === "https:" ? ORIGINAL_REQUEST.https : u.protocol === "http:" ? ORIGINAL_REQUEST.http : null;
+    if (request === null) {
+      fail(new Error(`unsupported protocol ${u.protocol}`));
+      return;
+    }
+    const headers = { ...opts.headers };
+    if (opts.body !== void 0) headers["content-length"] = String(opts.body.length);
+    try {
+      captureGuard.run(true, () => {
+        req = request(u, { method: opts.method, headers }, (res) => {
+          const chunks = [];
+          let got = 0;
+          let truncated = false;
+          const finish = () => {
+            if (aborted) fail(new Error("aborted"));
+            else {
+              succeed({
+                status: res.statusCode ?? 0,
+                headers: res.headers,
+                body: Buffer.concat(chunks).subarray(0, opts.maxBytes),
+                truncated,
+                complete: !truncated && res.complete
+              });
+            }
+          };
+          res.on("data", (c) => {
+            if (got < opts.maxBytes) chunks.push(c);
+            got += c.length;
+            if (got > opts.maxBytes) {
+              truncated = true;
+              finish();
+              res.destroy();
+            }
+          });
+          res.on("end", finish);
+          res.on("error", finish);
+          res.on("close", finish);
+        });
+      });
+    } catch (err2) {
+      fail(err2);
+      return;
+    }
+    const r = req;
+    const hold = opts.holdProcess === true;
+    const totalMs = opts.totalTimeoutMs ?? (hold ? HOLD_TOTAL_MS : opts.timeoutMs);
+    total = setTimeout(() => r.destroy(new Error("timeout")), totalMs);
+    if (!hold) {
+      total.unref();
+      r.on("socket", (s) => s.unref());
+    }
+    r.setTimeout(opts.timeoutMs, () => r.destroy(new Error("timeout")));
+    r.on("error", fail);
+    r.end(opts.body);
+    if (aborted) r.destroy(new Error("aborted"));
+  });
+  return { promise, abort };
+}
+
+// src/pull.ts
+var TIMEOUT_MS = 3e4;
+var MAX_BYTES = 128 * 1024 * 1024;
+var MAX_MIB = MAX_BYTES / (1024 * 1024);
+function isObj(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function arr(v) {
+  return Array.isArray(v) ? v.filter(isObj) : [];
+}
+function str(v) {
+  return typeof v === "string" ? v : "";
+}
+function parseEndpoint(raw) {
+  const i = raw.indexOf(" ");
+  if (i < 0) return null;
+  const method = raw.slice(0, i).trim();
+  const p = raw.slice(i + 1).trim();
+  if (!method || !p) return null;
+  return { method: method.toUpperCase(), path: p };
+}
+function normaliseSamples(samples, endpointGiven) {
+  const raw = String(samples).trim().toLowerCase();
+  if (raw !== "all" && !/^\d+$/.test(raw)) {
+    throw new Error(`samples must be a positive integer or 'all', got: ${JSON.stringify(samples)}`);
+  }
+  if (raw !== "all" && Number(raw) < 1) throw new Error(`samples must be at least 1, got: ${JSON.stringify(samples)}`);
+  if ((raw === "all" || Number(raw) > 1) && !endpointGiven) {
+    throw new Error(
+      'samples greater than 1 requires an endpoint. Fetching every recording for a whole project is not supported; scope it, e.g. endpoints: ["GET /api/orders"].'
+    );
+  }
+  return raw;
+}
+async function fetchOne(apiUrl, apiKey, method, p, samples) {
+  const params = new URLSearchParams();
+  if (method) params.set("method", method);
+  if (p) params.set("path", p);
+  if (samples !== null) params.set("samples", samples);
+  const qs = [...params].length > 0 ? `?${params.toString()}` : "";
+  const url = `${apiUrl.replace(/\/+$/, "")}/v1/replay/bundle${qs}`;
+  let res;
+  try {
+    res = await sendRequest(url, {
+      method: "GET",
+      headers: { authorization: `Bearer ${apiKey}`, "user-agent": `stubsmith-cli/${VERSION}` },
+      timeoutMs: TIMEOUT_MS,
+      holdProcess: true,
+      maxBytes: MAX_BYTES
+    }).promise;
+  } catch (err2) {
+    throw new Error(
+      `Network error reaching ${url}: ${err2 instanceof Error ? err2.message : String(err2)}
+Check that the backend is reachable, or set STUBSMITH_API_URL to override (default: ${DEFAULT_BACKEND_URL}).`
+    );
+  }
+  if (res.truncated) throw new Error(`Bundle response exceeded ${MAX_MIB} MiB; narrow with --endpoint.`);
+  const text = res.body.toString("utf8");
+  if (res.status === 404) {
+    throw new Error(
+      `HTTP 404 from ${url}
+The StubSmith backend was not found at that URL.
+For the hosted service the URL is ${DEFAULT_BACKEND_URL}.
+Override with STUBSMITH_API_URL, or unset it to use the default.`
+    );
+  }
+  if (res.status < 200 || res.status >= 300) throw new Error(`HTTP ${res.status}: ${text}`);
+  if (!res.complete) throw new Error(`Connection closed before the response completed (${url}). Retry the pull.`);
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (err2) {
+    throw new Error(`Server returned unparseable JSON: ${err2 instanceof Error ? err2.message : String(err2)}`);
+  }
+  if (!isObj(data)) throw new Error("Server returned an unexpected response (not a JSON object)");
+  if (!Array.isArray(data.endpoints)) throw new Error("Server returned an unexpected response (no endpoints array)");
+  return data;
+}
+function cursorValue(v) {
+  if (v === void 0 || v === null || v === "" || v === 0 || v === false) return 0n;
+  if (typeof v === "number") return Number.isInteger(v) ? BigInt(v) : BigInt(Math.trunc(v));
+  if (typeof v === "string" && /^\s*[+-]?\d+(?:_\d+)*\s*$/.test(v)) return BigInt(v.trim().replace(/_/g, ""));
+  return null;
+}
+function mergeBundles(typed) {
+  const parts = typed;
+  if (parts.length === 0) return { ok: true, version: 1, cursor: "0", endpoints: [] };
+  if (parts.length === 1) return typed[0];
+  const merged = /* @__PURE__ */ new Map();
+  const seen = /* @__PURE__ */ new Map();
+  const truncated = /* @__PURE__ */ new Map();
+  let cursor = 0n;
+  for (const part of parts) {
+    const c = cursorValue(part.cursor);
+    if (c !== null && c > cursor) cursor = c;
+    if (isObj(part.truncated)) {
+      for (const [k, v] of Object.entries(part.truncated)) if (!truncated.has(k)) truncated.set(k, v);
+    }
+    for (const ep of arr(part.endpoints)) {
+      const key = JSON.stringify([str(ep.domain), str(ep.method).toUpperCase(), str(ep.path_template)]);
+      let m = merged.get(key);
+      if (!m) {
+        m = { ...ep, stubs: [] };
+        merged.set(key, m);
+        seen.set(key, /* @__PURE__ */ new Set());
+      }
+      const fps = seen.get(key);
+      for (const stub of arr(ep.stubs)) {
+        const fp = str(stub.fingerprint);
+        if (fps.has(fp)) continue;
+        fps.add(fp);
+        m.stubs.push(stub);
+      }
+    }
+  }
+  const out2 = {
+    ok: true,
+    version: parts[0].version ?? 1,
+    cursor: cursor.toString(),
+    generated_at: parts[parts.length - 1].generated_at ?? null,
+    endpoints: [...merged.values()]
+  };
+  for (let i = parts.length - 1; i >= 0; i--) {
+    const ps = parts[i].project_settings;
+    if (isObj(ps) && typeof ps.group_ids_in_paths === "boolean") {
+      out2.project_settings = ps;
+      break;
+    }
+  }
+  if (truncated.size > 0) out2.truncated = Object.fromEntries(truncated);
+  return out2;
+}
+function statusKey(v) {
+  return typeof v.status === "number" ? v.status : 0;
+}
+function sortBundle(typed) {
+  const data = typed;
+  const endpoints = [...arr(data.endpoints)].sort(
+    (a, b) => compareCodePoints(str(a.domain), str(b.domain)) || compareCodePoints(str(a.method), str(b.method)) || compareCodePoints(str(a.path_template), str(b.path_template))
+  );
+  return {
+    ...data,
+    endpoints: endpoints.map((ep) => ({
+      ...ep,
+      stubs: [...arr(ep.stubs)].sort((a, b) => compareCodePoints(str(a.fingerprint), str(b.fingerprint))).map((stub) => ({ ...stub, variants: [...arr(stub.variants)].sort((a, b) => statusKey(a) - statusKey(b)) }))
+    }))
+  };
+}
+function summarizeBundle(typed) {
+  const data = typed;
+  const eps = arr(data.endpoints);
+  const summary = { endpoints: eps.length, stubs: 0, variants: 0, degraded: [], bodyCapped: 0 };
+  for (const ep of eps) {
+    for (const stub of arr(ep.stubs)) {
+      summary.stubs++;
+      if (stub.degraded) {
+        summary.degraded.push({
+          domain: str(ep.domain),
+          method: str(ep.method),
+          pathTemplate: str(ep.path_template),
+          fingerprint: str(stub.fingerprint)
+        });
+      }
+      for (const v of arr(stub.variants)) {
+        summary.variants++;
+        if (v.body_capped) summary.bodyCapped++;
+      }
+    }
+  }
+  return summary;
+}
+function resolveAuth(opts) {
+  const apiKey = opts.apiKey || process.env.STUBSMITH_API_KEY || "";
+  if (!apiKey) throw new Error("No API key: pass apiKey or set $STUBSMITH_API_KEY.");
+  return { apiKey, apiUrl: opts.apiUrl || resolveApiUrl() };
+}
+async function pullBundle(opts = {}) {
+  const { apiKey, apiUrl } = resolveAuth(opts);
+  const targets = [];
+  for (const raw of opts.endpoints ?? []) {
+    const ep = parseEndpoint(raw);
+    if (!ep) throw new Error(`endpoint must be "METHOD /path" (e.g. "GET /api/orders"), got: ${JSON.stringify(raw)}`);
+    targets.push({ method: ep.method, path: ep.path });
+  }
+  const samples = opts.samples === void 0 ? null : normaliseSamples(opts.samples, targets.length > 0);
+  if (targets.length === 0) targets.push({ method: null, path: null });
+  const fetched = [];
+  for (const t of targets) {
+    if (t.method && t.path) opts.onFetch?.(t.method, t.path);
+    fetched.push(await fetchOne(apiUrl, apiKey, t.method, t.path, samples));
+  }
+  const bundle = sortBundle(mergeBundles(fetched));
+  return { bundle, summary: summarizeBundle(bundle) };
+}
+function compareKeys(a, b) {
+  return compareCodePoints(a, b);
+}
+function stringifyBundle(value, indent = "") {
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    const inner = `${indent}  `;
+    return `[
+${value.map((v) => inner + stringifyBundle(v === void 0 ? null : v, inner)).join(",\n")}
+${indent}]`;
+  }
+  if (isObj(value)) {
+    const keys = Object.keys(value).filter((k) => value[k] !== void 0).sort(compareKeys);
+    if (keys.length === 0) return "{}";
+    const inner = `${indent}  `;
+    return `{
+${keys.map((k) => `${inner}${JSON.stringify(k)}: ${stringifyBundle(value[k], inner)}`).join(",\n")}
+${indent}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+async function writeBundle(outPath, data) {
+  const dest = path.resolve(outPath);
+  const dir = path.dirname(dest);
+  await fsp.mkdir(dir, { recursive: true });
+  const serialised = `${stringifyBundle(data)}
+`;
+  const tmp = path.join(dir, `.stubsmith-bundle-${randomBytes(6).toString("hex")}`);
+  try {
+    await fsp.writeFile(tmp, serialised, { encoding: "utf8", flag: "wx", mode: 384 });
+    await fsp.chmod(tmp, 420);
+    await fsp.rename(tmp, dest);
+  } catch (err2) {
+    await fsp.unlink(tmp).catch(() => void 0);
+    throw err2;
+  }
+}
+
+// src/cli.ts
+var DEFAULT_OUT = ".stubsmith/bundle.json";
+var USAGE = `usage: stubsmith [-h] [--version] <command> ...
+
+StubSmith command-line tools.
+
+commands:
+  pull    Fetch the replay bundle and write it to disk.
+
+usage: stubsmith pull [-h] [--out PATH] [--endpoint "METHOD /path/template"]... [--samples N|all]
+
+  --out PATH                       Destination file (default: ${DEFAULT_OUT})
+  --endpoint "METHOD /path"        Filter to an endpoint, e.g. "GET /api/users/{id}".
+                                   Repeat to pull several into one bundle. Each endpoint
+                                   is one request; the responses are merged.
+  --samples N|all                  Recordings to keep per response (default: 1, the newest).
+                                   Requires --endpoint.
+
+Environment: STUBSMITH_API_KEY (required), STUBSMITH_API_URL.
+`;
+function out(s) {
+  process.stdout.write(`${s}
+`);
+}
+function err(s) {
+  process.stderr.write(`${s}
+`);
+}
+function parsePull(argv) {
+  const args = { out: DEFAULT_OUT, endpoints: [], samples: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") return "help";
+    const m = /^(--(?:out|endpoint|samples))(?:=([\s\S]*))?$/.exec(a);
+    if (!m) return `unrecognized arguments: ${a}`;
+    const flag = m[1];
+    let value = m[2];
+    if (value === void 0) {
+      if (i + 1 >= argv.length) return `argument ${flag}: expected one argument`;
+      value = argv[++i];
+    }
+    if (flag === "--out") args.out = value;
+    else if (flag === "--endpoint") args.endpoints.push(value);
+    else args.samples = value;
+  }
+  return args;
+}
+function printSummary(bundle, outPath, s) {
+  out(`Wrote ${outPath}`);
+  out(`  endpoints : ${s.endpoints}`);
+  out(`  stubs     : ${s.stubs}`);
+  out(`  variants  : ${s.variants}`);
+  out(`  cursor    : ${bundle.cursor ?? ""}`);
+  out(`  generated : ${bundle.generated_at ?? ""}`);
+  const t = bundle.truncated;
+  if (t && typeof t === "object" && Object.keys(t).length > 0) {
+    out("");
+    out("WARNING: bundle is truncated - not all data was included.");
+    const stubs = t.stubs;
+    if (stubs && stubs.dropped) out(`  stubs: ${stubs.dropped} stubs dropped (server limit: ${stubs.limit})`);
+    const variants = t.variants;
+    if (Array.isArray(variants) && variants.length > 0) {
+      const dropped = variants.reduce((n, v) => n + (typeof v.dropped === "number" ? v.dropped : 0), 0);
+      out(
+        `  variants: ${dropped} variant(s) dropped across ${variants.length} fingerprint(s) (server limit per fingerprint: ${variants[0].limit})`
+      );
+    }
+    const samples = t.samples;
+    if (samples && samples.limit) out(`  samples: clamped to the server limit of ${samples.limit} recordings per response`);
+    const bb = t.body_bytes;
+    if (bb) {
+      const limitKb = Math.floor((typeof bb.limit === "number" ? bb.limit : 0) / 1024);
+      out(
+        `  body_bytes: ${bb.capped} variant body/bodies omitted (exceeded ${limitKb} KB cap) - these stubs will replay with an empty body`
+      );
+    }
+  }
+  if (s.degraded.length > 0) {
+    out(
+      `WARNING: ${s.degraded.length} stub(s) marked degraded - no recorded captures are available; replay will fail for those stubs.`
+    );
+  }
+  if (s.bodyCapped > 0) {
+    out(
+      `WARNING: ${s.bodyCapped} variant(s) have body_capped=true - body exceeded the server size cap and was omitted; replay will return an empty body for those variants.`
+    );
+  }
+}
+async function cmdPull(args) {
+  const apiKey = process.env.STUBSMITH_API_KEY ?? "";
+  if (!apiKey) {
+    err("Error: STUBSMITH_API_KEY is not set. Export your project API key before running stubsmith pull.");
+    return 1;
+  }
+  for (const raw of args.endpoints) {
+    if (!parseEndpoint(raw)) {
+      err(`Error: --endpoint must be "METHOD /path" (e.g. "GET /api/users"), got: ${JSON.stringify(raw)}`);
+      return 1;
+    }
+  }
+  if (args.samples !== null) {
+    const raw = args.samples.trim().toLowerCase();
+    if (raw !== "all" && !/^\d+$/.test(raw)) {
+      err(`Error: --samples must be a positive integer or 'all', got: ${JSON.stringify(args.samples)}`);
+      return 1;
+    }
+    if (raw !== "all" && Number(raw) < 1) {
+      err("Error: --samples must be at least 1.");
+      return 1;
+    }
+    if ((raw === "all" || Number(raw) > 1) && args.endpoints.length === 0) {
+      err(
+        'Error: --samples greater than 1 requires --endpoint.\nFetching every recording for a whole project is not supported; scope it, e.g. --endpoint "GET /api/orders". Repeat --endpoint to cover several in one bundle.'
+      );
+      return 1;
+    }
+  }
+  let result;
+  try {
+    result = await pullBundle({
+      apiKey,
+      endpoints: args.endpoints,
+      ...args.samples !== null ? { samples: args.samples } : {},
+      onFetch: (method, path2) => err(`Fetching ${method} ${path2} ...`)
+    });
+  } catch (e) {
+    err(`Error: ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  }
+  try {
+    await writeBundle(args.out, result.bundle);
+  } catch (e) {
+    err(`Error writing bundle: ${e instanceof Error ? e.message : String(e)}`);
+    return 1;
+  }
+  printSummary(result.bundle, args.out, result.summary);
+  return 0;
+}
+async function main(argv = process.argv.slice(2)) {
+  const first = argv[0];
+  if (first === "--version" || first === "-V") {
+    out(`stubsmith ${VERSION}`);
+    return 0;
+  }
+  if (first === "-h" || first === "--help") {
+    out(USAGE);
+    return 0;
+  }
+  if (first === void 0) {
+    err(USAGE);
+    err("stubsmith: error: the following arguments are required: <command>");
+    return 1;
+  }
+  if (first !== "pull") {
+    err(USAGE);
+    err(`stubsmith: error: unrecognized command or argument: ${first}`);
+    return 1;
+  }
+  const parsed = parsePull(argv.slice(1));
+  if (parsed === "help") {
+    out(USAGE);
+    return 0;
+  }
+  if (typeof parsed === "string") {
+    err(`stubsmith pull: error: ${parsed}`);
+    return 1;
+  }
+  return cmdPull(parsed);
+}
+function isEntryPoint() {
+  const argv1 = process.argv[1];
+  if (!argv1) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(argv1)).href;
+  } catch {
+    return false;
+  }
+}
+if (isEntryPoint()) {
+  main().then(
+    (code) => {
+      process.exitCode = code;
+    },
+    (e) => {
+      err(`Error: ${e instanceof Error ? e.message : String(e)}`);
+      process.exitCode = 1;
+    }
+  );
+}
+export {
+  main
+};
+//# sourceMappingURL=cli.js.map