@specbook/cli 0.3.0 → 0.5.0

package/dist/bin.js

@@ -243,35 +243,6 @@ function exampleBoolean(key) {
     key.toLowerCase()
   );
 }
-var FAKE_BY_FORMAT = {
-  email: "internet.email",
-  uuid: "string.uuid",
-  uri: "internet.url",
-  url: "internet.url",
-  hostname: "internet.domainName",
-  ipv4: "internet.ipv4"
-};
-var FAKE_BY_NAME = [
-  [/^(first_?name|given_?name)$/, "person.firstName"],
-  [/^(last_?name|family_?name|surname)$/, "person.lastName"],
-  [/^(full_?name|display_?name)$/, "person.fullName"],
-  [/^name$/, "word.noun"],
-  [/^(user_?name|login|handle)$/, "internet.username"],
-  [/^e?-?mail(_?address)?$/, "internet.email"],
-  [/^(phone|phone_?number|mobile)$/, "phone.number"],
-  [/^(city|town)$/, "location.city"],
-  [/^country$/, "location.country"],
-  [/^(postal_?code|zip|zip_?code)$/, "location.zipCode"],
-  [/^(line1|address|street|address_?line_?1)$/, "location.streetAddress"],
-  [/^(company|organization|org)$/, "company.name"],
-  [/^(title|subject)$/, "lorem.sentence"],
-  [/^(description|summary|bio|about|body|comment|note|notes|message)$/, "lorem.sentence"],
-  [/^(url|website|homepage)$/, "internet.url"]
-];
-function fakerFor(key, format) {
-  const path = format && FAKE_BY_FORMAT[format] || FAKE_BY_NAME.find(([re2]) => re2.test(key.toLowerCase()))?.[1];
-  return path ? `{{faker.${path}}}` : void 0;
-}
 var MAX_DEPTH = 6;
 var PLACEHOLDER_VALUE = /^(string|str|<string>|\{string\}|string\d+|null)$/i;
 function sanitizeExample(value, key = "", format, status) {
@@ -308,18 +279,14 @@ function fits(schema, value) {
   }
 }
 var HARD_DEPTH = 14;
-function synthesize(schema, resolve16, depth = 0, seen = [], key = "", status, fake = false, sparse = false) {
+function synthesize(schema, resolve16, depth = 0, seen = [], key = "", status, sparse = false) {
   if (!schema) return null;
-  const again = (s, k = key, d = depth, sn = seen) => synthesize(s, resolve16, d, sn, k, status, fake, sparse);
+  const again = (s, k = key, d = depth, sn = seen) => synthesize(s, resolve16, d, sn, k, status, sparse);
   if (schema.$ref) {
     const target = resolve16(schema.$ref);
     if (seen.includes(schema.$ref)) return again(target, key, Math.max(depth, MAX_DEPTH), []);
     return again(target, key, depth, [...seen, schema.$ref]);
   }
-  if (fake && schema.type === "string" && !schema.enum) {
-    const generated = fakerFor(key, schema.format);
-    if (generated) return generated;
-  }
   if (schema.example !== void 0 && fits(schema, schema.example))
     return schema.enum ? schema.example : sanitizeExample(schema.example, key, schema.format, status);
   if (schema.default !== void 0 && fits(schema, schema.default)) return schema.default;
@@ -725,13 +692,12 @@ ${typeBlocks.join("\n\n") || "export {}"}
       const fileFieldPaths = body2?.encoding === "multipart" ? fileFields(body2.schema, resolve16) : [];
       const wholeBodyFile = body2?.encoding === "binary";
       const sample = `./${SAMPLE_FILE}`;
-      const paramsFor = (fake) => {
+      const paramsFor = () => {
         const pick = (where) => {
           const out = {};
           for (const p of group(where)) {
             if (p.example !== void 0) out[p.name] = p.example;
-            else if (p.required)
-              out[p.name] = synthesize(p.schema, resolve16, 0, [], p.name, void 0, fake);
+            else if (p.required) out[p.name] = synthesize(p.schema, resolve16, 0, [], p.name);
           }
           return Object.keys(out).length ? out : void 0;
         };
@@ -752,7 +718,7 @@ ${typeBlocks.join("\n\n") || "export {}"}
           title: ex.summary ?? key,
           summary: ex.description,
           source: "spec",
-          ...paramsFor(false),
+          ...paramsFor(),
           body: bodyFor(sanitizeExample(ex.value))
         });
       }
@@ -761,26 +727,14 @@ ${typeBlocks.join("\n\n") || "export {}"}
           name: take("example"),
           title: "Example",
           source: "spec",
-          ...paramsFor(false),
+          ...paramsFor(),
           body: bodyFor(sanitizeExample(body2.media.example))
         });
       const plain = {
-        ...paramsFor(false),
-        body: body2?.schema ? bodyFor(synthesize(body2.schema, resolve16, 0, [], "", void 0, false, true)) : void 0
-      };
-      const dynamic = {
-        ...paramsFor(true),
-        body: body2?.schema ? bodyFor(synthesize(body2.schema, resolve16, 0, [], "", void 0, true, true)) : void 0
+        ...paramsFor(),
+        body: body2?.schema ? bodyFor(synthesize(body2.schema, resolve16, 0, [], "", void 0, true)) : void 0
       };
       docs.push({ name: take("default"), title: "Default", source: "generated", ...plain });
-      if (JSON.stringify(dynamic) !== JSON.stringify(plain))
-        docs.push({
-          name: take("dynamic"),
-          title: "Dynamic",
-          summary: "Generated values, fresh on every play.",
-          source: "generated",
-          ...dynamic
-        });
       for (const d of docs)
         exampleFiles.push({
           path: `examples/${id}/${d.name}.example.json`,
@@ -2108,7 +2062,7 @@ function diffAssertion(a3, context = 3) {
   return [];
 }
 
-// ../core/src/faker.ts
+// ../core/src/faker-runtime.ts
 var KEY = "__specbookFaker";
 var store = globalThis;
 var faker = new Proxy({}, {
@@ -2129,6 +2083,12 @@ function fakerLocaleNames(config = {}, locale) {
   const name = locale ?? config.default ?? "en";
   return [.../* @__PURE__ */ new Set([...config.locales?.[name] ?? [name, "en"], "base"])];
 }
+function fakerLocaleExports(config = {}) {
+  const names = /* @__PURE__ */ new Set(["en", ...fakerLocaleNames(config)]);
+  for (const name of Object.keys(config.locales ?? {}))
+    for (const n of fakerLocaleNames(config, name)) names.add(n);
+  return [...names].sort();
+}
 function installFaker(mod, config = {}, opts = {}) {
   const name = opts.locale ?? config.default ?? "en";
   const locales = fakerLocaleNames(config, name).map((n) => {
@@ -2143,8 +2103,10 @@ function installFaker(mod, config = {}, opts = {}) {
 }
 
 // ../core/src/template.ts
-var WHOLE = /^\s*\{\{\s*([\w.$-]+)\s*\}\}\s*$/;
-var EMBED = /\{\{\s*([\w.$-]+)\s*\}\}/g;
+var NAME = String.raw`[\w.$\[\]-]+`;
+var WHOLE = new RegExp(String.raw`^\s*\{\{\s*(${NAME})\s*\}\}\s*$`);
+var EMBED = new RegExp(String.raw`\{\{\s*(${NAME})\s*\}\}`, "g");
+var rootName = (name) => name.split(/[.[]/, 1)[0];
 var DEFERRED_NAMESPACES = ["secrets", "session"];
 var TemplateError = class extends Error {
   constructor(variable) {
@@ -2159,21 +2121,32 @@ function isDeferred(name) {
   return DEFERRED_NAMESPACES.includes(ns) && name.includes(".");
 }
 var isFakerName = (name) => name.startsWith("faker.");
-function fromFaker(path) {
-  let parent = faker;
-  let cur = faker;
-  for (const part of path.split(".").slice(1)) {
-    parent = cur;
-    cur = cur?.[part];
-    if (cur === void 0) return { found: false };
+var FakerPlaceholderError = class extends TemplateError {
+  constructor(variable, message) {
+    super(variable);
+    this.message = message;
+    this.name = "FakerPlaceholderError";
   }
-  return { found: true, value: typeof cur === "function" ? cur.call(parent) : cur };
+  message;
+};
+function fromFaker(path) {
+  const [, group, method, ...rest] = path.split(".");
+  const unknown = () => new FakerPlaceholderError(
+    path,
+    `Unknown faker generator "{{${path}}}": use faker.<module>.<method>`
+  );
+  if (!group || !method || rest.length > 0) throw unknown();
+  const mod = faker[group];
+  const fn = typeof mod === "object" && mod !== null ? mod[method] : void 0;
+  if (typeof fn !== "function" || method === "constructor") throw unknown();
+  return { found: true, value: fn.call(mod) };
 }
+var steps = (path) => path.replace(/\[(\d+)\]/g, ".$1").split(".");
 function lookup(scope, path) {
   if (isFakerName(path)) return fromFaker(path);
   let cur = scope;
-  for (const part of path.split(".")) {
-    if (cur !== null && typeof cur === "object" && part in cur) {
+  for (const part of steps(path)) {
+    if (cur !== null && typeof cur === "object" && Object.hasOwn(cur, part)) {
       cur = cur[part];
     } else {
       return { found: false };
@@ -2181,7 +2154,19 @@ function lookup(scope, path) {
   }
   return { found: true, value: cur };
 }
+function rejectFakerCall(s) {
+  if (!s.includes("faker")) return;
+  const left = /\{\{\s*(faker\.[\s\S]*?)(?:\}\}|$)/.exec(s.replace(EMBED, ""));
+  if (left) {
+    const name = left[1].trim();
+    throw new FakerPlaceholderError(
+      name,
+      `"{{${name}}}" is not a faker placeholder: placeholders take no arguments. Use faker in a request file for those.`
+    );
+  }
+}
 function renderString(s, scope) {
+  rejectFakerCall(s);
   const whole = WHOLE.exec(s);
   if (whole) {
     const name = whole[1];
@@ -2862,7 +2847,7 @@ function createColors(enabled) {
 // ../core/src/reporters/list.ts
 var MARKS = { pass: "\u2713", fail: "\u2717", error: "!", skipped: "\u2013" };
 var formatDuration = (ms) => ms < 1e3 ? `${Math.round(ms)}ms` : ms < 6e4 ? `${(ms / 1e3).toFixed(2)}s` : `${Math.floor(ms / 6e4)}m ${Math.round(ms % 6e4 / 1e3)}s`;
-var leaves = (steps) => steps.flatMap((s) => s.children?.length ? leaves(s.children) : [s]);
+var leaves = (steps3) => steps3.flatMap((s) => s.children?.length ? leaves(s.children) : [s]);
 function paint(status, c, text) {
   return status === "pass" ? c.green(text) : status === "skipped" ? c.dim(text) : status === "error" ? c.yellow(text) : c.red(text);
 }
@@ -2941,21 +2926,21 @@ function formatSummary(results, o = {}) {
   const c = o.colors ?? createColors(false);
   const t = reportTotals(results);
   const part = (n, word, paintFn) => n ? paintFn(`${n} ${word}`) : "";
-  const join18 = (...parts) => parts.filter(Boolean).join(c.dim(" | ")) || c.dim("none");
+  const join20 = (...parts) => parts.filter(Boolean).join(c.dim(" | ")) || c.dim("none");
   const lines2 = [
     "",
-    `${c.bold(" Flows      ")} ${join18(
+    `${c.bold(" Flows      ")} ${join20(
       part(t.flows.failed, "failed", c.red),
       part(t.flows.errored, "errored", c.yellow),
       part(t.flows.flaky, "flaky", c.yellow),
       part(t.flows.passed, "passed", c.green)
     )} ${c.dim(`(${results.length})`)}`,
-    `${c.bold(" Steps      ")} ${join18(
+    `${c.bold(" Steps      ")} ${join20(
       part(t.steps.failed, "failed", c.red),
       part(t.steps.skipped, "skipped", c.dim),
       part(t.steps.passed, "passed", c.green)
     )}`,
-    `${c.bold(" Assertions ")} ${join18(
+    `${c.bold(" Assertions ")} ${join20(
       part(t.assertions.failed, "failed", c.red),
       part(t.assertions.passed, "passed", c.green)
     )}`
@@ -3030,7 +3015,7 @@ var esc = (s) => String(s).replace(
   /[<>&"']|[\u0000-\u0008\u000b\u000c\u000e-\u001f]/g,
   (c) => ({ "<": "&lt;", ">": "&gt;", "&": "&amp;", '"': "&quot;", "'": "&apos;" })[c] ?? ""
 );
-var leafSteps = (steps) => steps.flatMap((s) => s.children?.length ? leafSteps(s.children) : [s]);
+var leafSteps = (steps3) => steps3.flatMap((s) => s.children?.length ? leafSteps(s.children) : [s]);
 function toJUnit(results, o = {}) {
   const suites = results.map((r) => {
     const flat = leafSteps(r.steps);
@@ -3225,6 +3210,31 @@ function buildUrl(base, req) {
   return `${base.replace(/\/+$/, "")}${req.url}${q2 ? `?${q2}` : ""}`;
 }
 var DEFAULT_TIMEOUT_MS = 3e4;
+var WHY = {
+  ECONNREFUSED: "connection refused",
+  ENOTFOUND: "host not found",
+  EAI_AGAIN: "host not found",
+  ECONNRESET: "connection reset",
+  ETIMEDOUT: "connection timed out",
+  UND_ERR_CONNECT_TIMEOUT: "connection timed out",
+  EHOSTUNREACH: "host unreachable",
+  ENETUNREACH: "network unreachable"
+};
+function unreachable2(e, url) {
+  const cause = e?.cause;
+  if (!(e instanceof TypeError) || !cause) return e;
+  const code = cause.code ?? cause.errors?.find((x2) => x2.code)?.code;
+  const tls = code && /^CERT_|^ERR_TLS|SELF_SIGNED|UNABLE_TO_VERIFY/.test(code) ? "certificate problem" : "";
+  const own = typeof cause.message === "string" && cause.message.length <= 120 ? cause.message : "";
+  const why = code && WHY[code] || tls || own;
+  if (!why) return e;
+  let host = url;
+  try {
+    host = new URL(url).host;
+  } catch {
+  }
+  return new Error(`Could not reach ${host}: ${why}.`, { cause: e });
+}
 function createFetchTransport(opts) {
   return async (req, signal) => {
     if (signal?.aborted) throw new Error("Stopped before the API answered.");
@@ -3243,8 +3253,9 @@ function createFetchTransport(opts) {
       ctl.abort();
     }, req.timeoutMs) : void 0;
     signal?.addEventListener("abort", () => ctl.abort());
+    const url = buildUrl(opts.baseUrl(req.service), req);
     try {
-      const res = await f2(buildUrl(opts.baseUrl(req.service), req), {
+      const res = await f2(url, {
         method: req.method,
         headers,
         body: body2,
@@ -3268,7 +3279,7 @@ function createFetchTransport(opts) {
     } catch (e) {
       if (timedOut) throw new Error(`Timed out after ${req.timeoutMs}ms: no answer from the API.`);
       if (signal?.aborted) throw new Error("Stopped before the API answered.");
-      throw e;
+      throw unreachable2(e, url);
     } finally {
       if (timer) clearTimeout(timer);
     }
@@ -3318,7 +3329,7 @@ function usesOf(names, layers, from) {
   const out = [];
   for (const name of names) {
     if (isDeferred(name) || isFakerName(name)) continue;
-    const key = name.split(".")[0];
+    const key = rootName(name);
     if (seen.has(key)) continue;
     seen.add(key);
     for (let i = layers.length - 1; i >= 0; i--) {
@@ -3587,7 +3598,7 @@ async function execute(rt2, def, name, flow, kind = "request", noAuth = false) {
   emit(rt2, { type: "step:end", name, status: result.status });
   return { result, response, authResults };
 }
-function summarize(steps) {
+function summarize(steps3) {
   const t = { steps: 0, passed: 0, failed: 0, skipped: 0, assertions: { passed: 0, failed: 0 } };
   const visit = (s) => {
     if (s.children?.length) {
@@ -3600,21 +3611,21 @@ function summarize(steps) {
     else t.failed++;
     for (const a3 of s.assertions) a3.pass ? t.assertions.passed++ : t.assertions.failed++;
   };
-  steps.forEach(visit);
+  steps3.forEach(visit);
   return t;
 }
-function overall(steps) {
+function overall(steps3) {
   const all = [];
   const walk2 = (s) => {
     all.push(s);
     s.children?.forEach(walk2);
   };
-  steps.forEach(walk2);
+  steps3.forEach(walk2);
   if (all.some((s) => s.status === "error")) return "error";
   if (all.some((s) => s.status === "fail")) return "fail";
   return "pass";
 }
-function finish(rt2, kind, meta, steps, startedAt) {
+function finish(rt2, kind, meta, steps3, startedAt) {
   const result = {
     schemaVersion: 1,
     runId: rid(),
@@ -3626,11 +3637,11 @@ function finish(rt2, kind, meta, steps, startedAt) {
     seed: rt2.o.seed,
     usedDrafts: rt2.o.usedDrafts ?? false,
     tags: meta.tags ?? [],
-    status: overall(steps),
+    status: overall(steps3),
     startedAt: new Date(startedAt).toISOString(),
     durationMs: (rt2.o.now?.() ?? now0()) - startedAt,
-    totals: summarize(steps),
-    steps
+    totals: summarize(steps3),
+    steps: steps3
   };
   const masked = maskDeep(result, rt2.mask);
   emit(rt2, { type: "done", result: masked });
@@ -3718,7 +3729,7 @@ async function runSequence(seq, o) {
     kind: "sequence",
     tags: seq.meta.tags
   });
-  const steps = [];
+  const steps3 = [];
   const captured = {};
   const from = {};
   const remember = (values, step) => {
@@ -3729,7 +3740,7 @@ async function runSequence(seq, o) {
   try {
     inputs = resolveControls(seq.meta.inputs ?? {}, o.inputs);
   } catch (e) {
-    steps.push({
+    steps3.push({
       name: "inputs",
       kind: "input",
       status: "error",
@@ -3738,7 +3749,7 @@ async function runSequence(seq, o) {
       error: e.message,
       durationMs: 0
     });
-    return finish(rt2, "sequence", seq.meta, steps, t0);
+    return finish(rt2, "sequence", seq.meta, steps3, t0);
   }
   const vars = o.vars ?? {};
   const ctx = () => ({
@@ -3748,7 +3759,7 @@ async function runSequence(seq, o) {
     env: o.env
   });
   let failed = false;
-  const skip = (name, kind) => steps.push({ name, kind, status: "skipped", assertions: [], captured: {}, durationMs: 0 });
+  const skip = (name, kind) => steps3.push({ name, kind, status: "skipped", assertions: [], captured: {}, durationMs: 0 });
   for (const node of seq.nodes) {
     if (failed && !seq.meta.continueOnFailure) {
       skip(node.name, node.kind === "step" ? "request" : node.kind);
@@ -3767,7 +3778,7 @@ async function runSequence(seq, o) {
           captured,
           from
         });
-        steps.push(...authResults, result);
+        steps3.push(...authResults, result);
         remember(result.captured, node.name);
         if (result.status !== "pass") failed = true;
       } else if (node.kind === "each") {
@@ -3803,7 +3814,7 @@ async function runSequence(seq, o) {
         parent.captured = collected;
         parent.durationMs = (o.now?.() ?? now0()) - p0;
         remember(collected, node.name);
-        steps.push(parent);
+        steps3.push(parent);
         if (parent.status !== "pass") failed = true;
       } else if (node.kind === "input") {
         const controls = node.controls(ctx());
@@ -3812,7 +3823,7 @@ async function runSequence(seq, o) {
         const given = o.onInput ? await o.onInput({ name: node.name, controls: described }) : o.inputs ?? {};
         const values = resolveControls(controls, given);
         inputs = { ...inputs, ...values };
-        steps.push({
+        steps3.push({
           name: node.name,
           kind: "input",
           status: "pass",
@@ -3842,12 +3853,12 @@ async function runSequence(seq, o) {
         s.assertions = a3.results;
         if (s.status === "pass" && a3.results.some((r) => !r.pass)) s.status = "fail";
         emit(rt2, { type: "step:end", name: node.name, status: s.status });
-        steps.push(s);
+        steps3.push(s);
         if (s.status !== "pass") failed = true;
       }
     } catch (e) {
       const isControl = e instanceof ControlError;
-      steps.push({
+      steps3.push({
         name: node.name,
         kind: node.kind === "step" ? "request" : node.kind,
         status: "error",
@@ -3859,7 +3870,7 @@ async function runSequence(seq, o) {
       failed = true;
     }
   }
-  return finish(rt2, "sequence", seq.meta, steps, t0);
+  return finish(rt2, "sequence", seq.meta, steps3, t0);
 }
 
 // ../core/src/runner/suite.ts
@@ -3919,7 +3930,7 @@ function headerLine(h2, colors2) {
 var retryLine = (colors2, title, attempt, allowed) => `  ${colors2.yellow("\u21BB")} retrying ${title} (attempt ${attempt} of ${allowed})
 `;
 function withoutLocations(results) {
-  const strip = (steps) => steps.map((s) => ({
+  const strip = (steps3) => steps3.map((s) => ({
     ...s,
     assertions: s.assertions.map((a3) => ({ ...a3, location: void 0 })),
     ...s.children ? { children: strip(s.children) } : {}
@@ -5472,8 +5483,19 @@ var faker2 = new Proxy({}, {
     return current[key];
   }
 });
-var WHOLE2 = /^\s*\{\{\s*([\w.$-]+)\s*\}\}\s*$/;
-var EMBED2 = /\{\{\s*([\w.$-]+)\s*\}\}/g;
+function fakerLocaleNames2(config = {}, locale) {
+  const name = locale ?? config.default ?? "en";
+  return [.../* @__PURE__ */ new Set([...config.locales?.[name] ?? [name, "en"], "base"])];
+}
+function fakerLocaleExports2(config = {}) {
+  const names = /* @__PURE__ */ new Set(["en", ...fakerLocaleNames2(config)]);
+  for (const name of Object.keys(config.locales ?? {}))
+    for (const n of fakerLocaleNames2(config, name)) names.add(n);
+  return [...names].sort();
+}
+var NAME2 = String.raw`[\w.$\[\]-]+`;
+var WHOLE2 = new RegExp(String.raw`^\s*\{\{\s*(${NAME2})\s*\}\}\s*$`);
+var EMBED2 = new RegExp(String.raw`\{\{\s*(${NAME2})\s*\}\}`, "g");
 var DEFERRED_NAMESPACES2 = ["secrets", "session"];
 var TemplateError2 = class extends Error {
   constructor(variable) {
@@ -5488,21 +5510,32 @@ function isDeferred2(name) {
   return DEFERRED_NAMESPACES2.includes(ns) && name.includes(".");
 }
 var isFakerName2 = (name) => name.startsWith("faker.");
-function fromFaker2(path) {
-  let parent = faker2;
-  let cur = faker2;
-  for (const part of path.split(".").slice(1)) {
-    parent = cur;
-    cur = cur?.[part];
-    if (cur === void 0) return { found: false };
+var FakerPlaceholderError2 = class extends TemplateError2 {
+  constructor(variable, message) {
+    super(variable);
+    this.message = message;
+    this.name = "FakerPlaceholderError";
   }
-  return { found: true, value: typeof cur === "function" ? cur.call(parent) : cur };
+  message;
+};
+function fromFaker2(path) {
+  const [, group, method, ...rest] = path.split(".");
+  const unknown = () => new FakerPlaceholderError2(
+    path,
+    `Unknown faker generator "{{${path}}}": use faker.<module>.<method>`
+  );
+  if (!group || !method || rest.length > 0) throw unknown();
+  const mod = faker2[group];
+  const fn = typeof mod === "object" && mod !== null ? mod[method] : void 0;
+  if (typeof fn !== "function" || method === "constructor") throw unknown();
+  return { found: true, value: fn.call(mod) };
 }
+var steps2 = (path) => path.replace(/\[(\d+)\]/g, ".$1").split(".");
 function lookup2(scope, path) {
   if (isFakerName2(path)) return fromFaker2(path);
   let cur = scope;
-  for (const part of path.split(".")) {
-    if (cur !== null && typeof cur === "object" && part in cur) {
+  for (const part of steps2(path)) {
+    if (cur !== null && typeof cur === "object" && Object.hasOwn(cur, part)) {
       cur = cur[part];
     } else {
       return { found: false };
@@ -5510,7 +5543,19 @@ function lookup2(scope, path) {
   }
   return { found: true, value: cur };
 }
+function rejectFakerCall2(s) {
+  if (!s.includes("faker")) return;
+  const left = /\{\{\s*(faker\.[\s\S]*?)(?:\}\}|$)/.exec(s.replace(EMBED2, ""));
+  if (left) {
+    const name = left[1].trim();
+    throw new FakerPlaceholderError2(
+      name,
+      `"{{${name}}}" is not a faker placeholder: placeholders take no arguments. Use faker in a request file for those.`
+    );
+  }
+}
 function renderString2(s, scope) {
+  rejectFakerCall2(s);
   const whole = WHOLE2.exec(s);
   if (whole) {
     const name = whole[1];
@@ -6143,7 +6188,7 @@ async function writeEnvKey(file, key, value) {
   await writeFile3(file, setDotenvKey(current, key, value));
 }
 var IGNORE = ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"];
-var NAME = /\.example\.json$/;
+var NAME22 = /\.example\.json$/;
 async function scanExamples(root, outDir, operations) {
   const examples = {};
   const assets = {};
@@ -6161,7 +6206,7 @@ async function scanExamples(root, outDir, operations) {
     const [svc, , id, file] = relative22(gen, abs).split(sep22);
     if (!operations.has(`${svc}/${id}`)) continue;
     add(`${svc}/${id}`, {
-      name: file.replace(NAME, ""),
+      name: file.replace(NAME22, ""),
       abs,
       source: "generated",
       dir: `${svc}/${id}@generated`
@@ -6175,7 +6220,7 @@ async function scanExamples(root, outDir, operations) {
     const key = `${svc}/${id}`;
     if (!svc || !id || !operations.has(key)) continue;
     add(key, {
-      name: file.replace(NAME, ""),
+      name: file.replace(NAME22, ""),
       abs,
       source: "project",
       dir: `${svc}/${id}@project`
@@ -6190,7 +6235,7 @@ async function scanExamples(root, outDir, operations) {
     list.sort((a3, b) => order(a3) - order(b) || a3.name.localeCompare(b.name));
   return { examples, assets };
 }
-var order = (e) => e.source === "project" ? 0 : e.name === "default" ? 2 : e.name === "dynamic" ? 3 : 1;
+var order = (e) => e.source === "project" ? 0 : e.name === "default" ? 2 : 1;
 var IGNORE2 = ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"];
 async function scanProject(root) {
   const rel2 = (e) => e.map((f2) => relative3(root, f2).split(sep3).join("/")).sort();
@@ -6477,7 +6522,7 @@ async function readBody2(req) {
     req.on("error", fail);
   });
 }
-function fakerLocales(entry) {
+function fakerLocales(entry, cfg) {
   const names = /* @__PURE__ */ new Set(["en", "base"]);
   const dir = join5(dirname2(entry), "locale");
   if (existsSync3(dir))
@@ -6485,8 +6530,11 @@ function fakerLocales(entry) {
       const m = /^([A-Za-z0-9_]+)\.js$/.exec(f2);
       if (m) names.add(m[1]);
     }
-  return [...names].sort();
+  if (!cfg) return [...names].sort();
+  const wanted = new Set(fakerLocaleExports2(cfg));
+  return [...names].filter((n) => wanted.has(n)).sort();
 }
+var USES_FAKER = /@specbook\/core\/faker|\{\{\s*faker\./;
 function slim(manifests) {
   return Object.fromEntries(
     Object.entries(manifests).map(([k, m]) => [
@@ -6585,6 +6633,14 @@ function specbook(options) {
       fakerEntry = createRequire(join5(root, "package.json")).resolve("@faker-js/faker");
     } catch {
     }
+    if (!fakerEntry) {
+      for (const f2 of [...files.requests, ...files.sequences]) {
+        if (USES_FAKER.test(await readFile6(join5(root, f2), "utf8").catch(() => "")))
+          throw new Error(
+            `${f2} uses faker, but @faker-js/faker is not installed in this project. Add it to devDependencies (npm install --save-dev @faker-js/faker).`
+          );
+      }
+    }
     const operationEntries = Object.values(manifests).flatMap((m) => {
       const mm = m;
       return mm.operations.map(
@@ -6956,7 +7012,10 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
         const r = await this.resolve("@faker-js/faker", join5(root, "package.json"), {
           skipSelf: true
         });
-        if (!r) return "export {}";
+        if (!r)
+          throw new Error(
+            "@faker-js/faker could not be resolved from this project. Add it to devDependencies."
+          );
         const pkg = JSON.stringify(r.id);
         if (id.startsWith(RESOLVED_FAKER_LOCALE))
           return `export { ${id.slice(RESOLVED_FAKER_LOCALE.length)} as default } from ${pkg}`;
@@ -6965,7 +7024,7 @@ export const loadConfig = ${cfg ? imp(cfg) : '() => Promise.resolve({ default: {
           entry = createRequire(join5(root, "package.json")).resolve("@faker-js/faker");
         } catch {
         }
-        const names = fakerLocales(entry);
+        const names = fakerLocales(entry, options.faker);
         return `export { Faker, base } from ${pkg}
 export const locales = {
 ${names.map((n) => `  ${JSON.stringify(n)}: () => import(${JSON.stringify(`${VIRTUAL_FAKER_LOCALE}${n}`)}).then((m) => m.default)`).join(",\n")}
@@ -7453,16 +7512,44 @@ ${entry}`
 import { execFileSync as execFileSync3 } from "child_process";
 import { createHash as createHash2 } from "crypto";
 import { existsSync as existsSync7, statSync as statSync2 } from "fs";
-import { chmod, mkdir as mkdir6, readdir as readdir3, readFile as readFile13, writeFile as writeFile7 } from "fs/promises";
+import { chmod, mkdir as mkdir6, readdir as readdir3, readFile as readFile14, writeFile as writeFile7 } from "fs/promises";
 import { createRequire as createRequire4 } from "module";
-import { basename as basename4, dirname as dirname6, join as join12, relative as relative9, resolve as resolve9, sep as sep7 } from "path";
+import { basename as basename4, dirname as dirname6, join as join13, relative as relative9, resolve as resolve9, sep as sep7 } from "path";
 import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "url";
 import { rolldown } from "rolldown";
 
-// src/ops.ts
+// src/faker-use.ts
 import { readFile as readFile10 } from "fs/promises";
-import { join as join9, relative as relative7, sep as sep5 } from "path";
+import { join as join9 } from "path";
 import fg6 from "fast-glob";
+var USES_FAKER2 = /@specbook\/core\/faker|\{\{\s*faker\./;
+var IGNORE3 = [
+  "**/node_modules/**",
+  "**/.generated/**",
+  "**/dist/**",
+  "**/.git/**",
+  "**/openapi/**",
+  "**/*.d.ts",
+  "**/package.json",
+  "**/package-lock.json",
+  "**/tsconfig*.json"
+];
+async function projectUsesFaker(root) {
+  const files = await fg6(["**/*.ts", "**/*.json", ".specbook/**/*.env"], {
+    cwd: root,
+    ignore: IGNORE3,
+    dot: true,
+    absolute: false
+  });
+  for (const f2 of files)
+    if (USES_FAKER2.test(await readFile10(join9(root, f2), "utf8").catch(() => ""))) return true;
+  return false;
+}
+
+// src/ops.ts
+import { readFile as readFile11 } from "fs/promises";
+import { join as join10, relative as relative7, sep as sep5 } from "path";
+import fg7 from "fast-glob";
 import { parseSync } from "vite";
 var prefixOf = (project) => (project.config.codegen?.importPrefix ?? "#api").replace(/\/+$/, "");
 var IMPORT_RE = /import\s+(type\s+)?(?:([\w$]+)\s*,?\s*)?(?:\*\s+as\s+[\w$]+|\{([^}]*)\})?\s*from\s*['"]([^'"]+)['"]/g;
@@ -7509,7 +7596,7 @@ function importedOperations(file, text, prefix = "#api") {
   return [...found.values()];
 }
 async function projectSources(root) {
-  return fg6(["**/*.ts", ".specbook/**/*.ts"], {
+  return fg7(["**/*.ts", ".specbook/**/*.ts"], {
     cwd: root,
     absolute: true,
     dot: true,
@@ -7527,7 +7614,7 @@ async function usedOperations(project) {
   const out = { named: /* @__PURE__ */ new Map(), whole: /* @__PURE__ */ new Set(), where: /* @__PURE__ */ new Map() };
   const prefix = prefixOf(project);
   for (const file of (await projectSources(project.root)).sort()) {
-    const text = await readFile10(file, "utf8").catch(() => "");
+    const text = await readFile11(file, "utf8").catch(() => "");
     if (!text.includes(prefix)) continue;
     const rel2 = relative7(project.root, file).split(sep5).join("/");
     for (const imp of importedOperations(file, text, prefix)) {
@@ -7562,10 +7649,10 @@ async function usedOperationKeys(project, outDir) {
   }
   return new Set([...keys].filter((k) => known.has(k)));
 }
-var metaFile = (outDir, service) => join9(outDir, service, "opmeta.json");
+var metaFile = (outDir, service) => join10(outDir, service, "opmeta.json");
 async function readJson(file) {
   try {
-    return JSON.parse(await readFile10(file, "utf8"));
+    return JSON.parse(await readFile11(file, "utf8"));
   } catch {
     return void 0;
   }
@@ -7599,11 +7686,11 @@ async function unknownOperationsMessage(project, outDir) {
 }
 
 // src/runtime.ts
-import { readFile as readFile12 } from "fs/promises";
+import { readFile as readFile13 } from "fs/promises";
 import { createRequire as createRequire3 } from "module";
-import { join as join11, relative as relative8, resolve as resolve8, sep as sep6 } from "path";
+import { join as join12, relative as relative8, resolve as resolve8, sep as sep6 } from "path";
 import { pathToFileURL } from "url";
-import fg7 from "fast-glob";
+import fg8 from "fast-glob";
 
 // src/run-tests.ts
 import { execFileSync as execFileSync2 } from "child_process";
@@ -7614,8 +7701,8 @@ import { dirname as dirname5, resolve as resolve7 } from "path";
 
 // src/project.ts
 import { existsSync as existsSync6 } from "fs";
-import { readFile as readFile11 } from "fs/promises";
-import { dirname as dirname4, join as join10, resolve as resolve6 } from "path";
+import { readFile as readFile12 } from "fs/promises";
+import { dirname as dirname4, join as join11, resolve as resolve6 } from "path";
 var CANDIDATES = [
   ".specbook/specbook.config.ts",
   "specbook.config.ts",
@@ -7625,7 +7712,7 @@ function findConfigFile(cwd) {
   let dir = resolve6(cwd);
   for (; ; ) {
     for (const c of CANDIDATES) {
-      const p = join10(dir, c);
+      const p = join11(dir, c);
       if (existsSync6(p)) return p;
     }
     const up = dirname4(dir);
@@ -7634,7 +7721,7 @@ function findConfigFile(cwd) {
   }
 }
 function rootOf(configFile) {
-  return configFile.endsWith(`${join10(".specbook", "specbook.config.ts")}`) ? dirname4(dirname4(configFile)) : dirname4(configFile);
+  return configFile.endsWith(`${join11(".specbook", "specbook.config.ts")}`) ? dirname4(dirname4(configFile)) : dirname4(configFile);
 }
 async function loadProject(cwd, loader) {
   const configFile = findConfigFile(cwd);
@@ -7645,7 +7732,7 @@ async function loadProject(cwd, loader) {
 }
 async function readDotenv(path) {
   if (!existsSync6(path)) return {};
-  return parseDotenv(await readFile11(path, "utf8"));
+  return parseDotenv(await readFile12(path, "utf8"));
 }
 
 // src/version.ts
@@ -7757,13 +7844,16 @@ function transportFor(ctx, env, vars) {
     }
   });
 }
-function originsFor(config, env, vars) {
+function originsFor(config, env, vars, basePath = false) {
   if (env === "mock") return {};
   const out = {};
   for (const service of Object.keys(config.services)) {
     try {
       const url = baseUrlFor(config, service, env, vars);
-      if (url) out[service] = new URL(url).origin;
+      if (url) {
+        const u = new URL(url);
+        out[service] = basePath ? `${u.origin}${u.pathname.replace(/\/+$/, "")}` : u.origin;
+      }
     } catch {
     }
   }
@@ -7844,6 +7934,7 @@ async function execute2(ctx, o, picked, specs, fileVars, secrets) {
   const vars = environmentScope(config, o.env, { ...fileVars, ...given });
   const transport = transportFor(ctx, o.env, vars);
   const origins = originsFor(config, o.env, vars);
+  const addresses = originsFor(config, o.env, vars, true);
   const faker3 = await ctx.loadFaker();
   const git2 = { ...ctx.git ?? gitInfo(ctx.root) };
   const ci = detectCi(process.env);
@@ -7862,7 +7953,7 @@ async function execute2(ctx, o, picked, specs, fileVars, secrets) {
     colors: colors2,
     quiet: o.quiet,
     trace: o.trace,
-    origins,
+    origins: addresses,
     cwd: ctx.root,
     readSource,
     rerun: (r) => `${ctx.command}${r.file && ctx.command === "specbook test" ? ` ${r.file}` : ""} --env ${o.env} --grep ${quote3(escapeRegExp(r.title))}${o.safe ? " --safe" : ""}`
@@ -7971,7 +8062,7 @@ async function execute2(ctx, o, picked, specs, fileVars, secrets) {
         toJUnit(clean, {
           timestamp: meta.startedAt,
           hostname: hostname(),
-          origins,
+          origins: addresses,
           properties: { env: o.env, sha: git2.sha, branch: git2.branch, specbook: meta.specbook }
         })
       );
@@ -8020,7 +8111,7 @@ async function execute2(ctx, o, picked, specs, fileVars, secrets) {
 
 // src/runtime.ts
 async function discoverTargets(project, loader, patterns) {
-  const files = (await fg7(patterns, {
+  const files = (await fg8(patterns, {
     cwd: project.root,
     absolute: true,
     ignore: ["**/node_modules/**", "**/.generated/**"]
@@ -8039,7 +8130,7 @@ function mockLoaderFor(project) {
   const manifest = (service) => {
     let m = manifests.get(service);
     if (!m) {
-      m = readFile12(join11(outDir, service, "manifest.json"), "utf8").then(JSON.parse);
+      m = readFile13(join12(outDir, service, "manifest.json"), "utf8").then(JSON.parse);
       manifests.set(service, m);
     }
     return m;
@@ -8053,8 +8144,8 @@ function mockLoaderFor(project) {
       for (const name of [String(status), "default"]) {
         try {
           return JSON.parse(
-            await readFile12(
-              join11(outDir, service, "examples", opId2, `${name}.response.json`),
+            await readFile13(
+              join12(outDir, service, "examples", opId2, `${name}.response.json`),
               "utf8"
             )
           );
@@ -8067,7 +8158,7 @@ function mockLoaderFor(project) {
 }
 async function loadFaker(project) {
   try {
-    const entry = createRequire3(join11(project.root, "package.json")).resolve("@faker-js/faker");
+    const entry = createRequire3(join12(project.root, "package.json")).resolve("@faker-js/faker");
     return await import(pathToFileURL(entry).href);
   } catch {
     return void 0;
@@ -8095,9 +8186,9 @@ function git(root) {
 function standalonePath() {
   const here = dirname6(fileURLToPath(import.meta.url));
   for (const p of [
-    join12(here, "standalone.js"),
-    join12(here, "..", "standalone.js"),
-    join12(here, "..", "standalone.ts")
+    join13(here, "standalone.js"),
+    join13(here, "..", "standalone.js"),
+    join13(here, "..", "standalone.ts")
   ])
     if (existsSync7(p)) return p;
   throw new Error("The test runner is missing from this installation of specbook");
@@ -8105,7 +8196,7 @@ function standalonePath() {
 async function walk(dir) {
   const entries = await readdir3(dir, { withFileTypes: true }).catch(() => []);
   return (await Promise.all(
-    entries.map((e) => e.isDirectory() ? walk(join12(dir, e.name)) : [join12(dir, e.name)])
+    entries.map((e) => e.isDirectory() ? walk(join13(dir, e.name)) : [join13(dir, e.name)])
   )).flat();
 }
 var SKIP = /(^|\/)(node_modules|\.generated|\.git|dist|dist-[^/]+)(\/|$)/;
@@ -8113,15 +8204,15 @@ var CODE = /\.(ts|tsx|mts|cts|js|mjs|cjs|md)$/;
 async function embed(project, outDir, used) {
   const root = project.root;
   const out = { examples: {}, files: {}, bytes: 0 };
-  const read = async (file) => JSON.parse(await readFile13(file, "utf8"));
+  const read = async (file) => JSON.parse(await readFile14(file, "utf8"));
   for (const [service, ops] of Object.entries(used))
     for (const id of Object.keys(ops)) {
-      const dir = join12(outDir, service, "examples", id);
+      const dir = join13(outDir, service, "examples", id);
       for (const f2 of await readdir3(dir).catch(() => [])) {
         const m = /^(.+)\.example\.json$/.exec(f2);
         if (!m) continue;
         out.examples[`${service}/${id}/${m[1]}`] = {
-          doc: await read(join12(dir, f2)),
+          doc: await read(join13(dir, f2)),
           source: "generated",
           dir: ""
         };
@@ -8146,24 +8237,21 @@ async function embed(project, outDir, used) {
     for (const abs of await walk(folder)) {
       const rel2 = posix(relative9(root, abs));
       if (SKIP.test(rel2) || CODE.test(rel2) || rel2.endsWith(".example.json")) continue;
-      const data2 = await readFile13(abs);
+      const data2 = await readFile14(abs);
       out.files[rel2] = data2.toString("base64");
       out.bytes += data2.length;
     }
   return out;
 }
-async function fakerSource(project, sources) {
+async function fakerSource(project) {
   let entry;
   try {
-    entry = createRequire4(join12(project.root, "package.json")).resolve("@faker-js/faker");
+    entry = createRequire4(join13(project.root, "package.json")).resolve("@faker-js/faker");
   } catch {
     return void 0;
   }
-  if (!project.config.faker && !/faker/.test(sources)) return void 0;
   const cfg = project.config.faker ?? {};
-  const wanted = /* @__PURE__ */ new Set(["Faker", ...fakerLocaleNames(cfg)]);
-  for (const name of Object.keys(cfg.locales ?? {}))
-    for (const n of fakerLocaleNames(cfg, name)) wanted.add(n);
+  const wanted = /* @__PURE__ */ new Set(["Faker", ...fakerLocaleExports(cfg)]);
   const have = new Set(Object.keys(await import(pathToFileURL2(entry).href)));
   const names = [...wanted].filter((n) => have.has(n)).sort();
   return `export { ${names.join(", ")} } from ${JSON.stringify(entry)}
@@ -8193,11 +8281,10 @@ async function bundleCommand(project, loader, o) {
   const files = [...new Set(chosen.map((t) => t.file))].sort();
   const ops = await usedMetadata(project, outDir);
   const sourceText = (await Promise.all(
-    [project.configFile, ...files.map((f2) => join12(root, f2))].map(
-      (f2) => readFile13(f2, "utf8").catch(() => "")
+    [project.configFile, ...files.map((f2) => join13(root, f2))].map(
+      (f2) => readFile14(f2, "utf8").catch(() => "")
     )
   )).join("\n");
-  const faker3 = await fakerSource(project, sourceText);
   const embedded = await embed(project, outDir, ops.services);
   const environments = {};
   for (const env of await listEnvironmentFiles(root))
@@ -8211,48 +8298,48 @@ async function bundleCommand(project, loader, o) {
     examples: embedded.examples,
     files: embedded.files
   };
-  const entry = [
-    `import { main } from ${JSON.stringify(standalonePath())}`,
-    `import config from ${JSON.stringify(project.configFile)}`,
-    ...files.map((f2, i) => `import * as m${i} from ${JSON.stringify(join12(root, f2))}`),
-    ...faker3 ? [`import * as fakerModule from ${JSON.stringify(FAKER)}`] : [],
-    `const data = { ...${JSON.stringify(data2)}, config,`,
-    `  modules: [${files.map((f2, i) => `{ file: ${JSON.stringify(f2)}, mod: m${i} }`).join(", ")}],`,
-    `  faker: ${faker3 ? "fakerModule" : "undefined"} }`,
-    "main(data).then((code) => process.exit(code), (e) => {",
-    "  console.error(e instanceof Error ? e.message : e)",
-    "  process.exit(2)",
-    "})"
-  ].join("\n");
   const ours = createRequire4(import.meta.url);
-  const plugin = {
-    name: "specbook-bundle",
-    resolveId(id) {
-      if (id === ENTRY) return ENTRY;
-      if (id === FAKER) return FAKER;
-      if (id.startsWith(`${prefix}/`) && !id.slice(prefix.length + 1).includes("/"))
-        return `\0specbook:api:${id.slice(prefix.length + 1)}`;
-      if (id === "@specbook/core" || id.startsWith("@specbook/core/")) return ours.resolve(id);
-      return void 0;
-    },
-    load(id) {
-      if (id === ENTRY) return entry;
-      if (id === FAKER) return faker3;
-      if (!id.startsWith("\0specbook:api:")) return void 0;
-      const service = id.slice("\0specbook:api:".length);
-      const metas = ops.services[service];
-      if (!metas) throw new Error(`Service "${service}" has no operations your requests use`);
-      return [
-        "import { defineOperation } from '@specbook/core'",
-        ...Object.entries(metas).map(
-          ([opId2, meta]) => `export const ${opId2} = /* @__PURE__ */ defineOperation(${JSON.stringify(meta)})`
-        ),
-        ""
-      ].join("\n");
-    }
-  };
   const warnings = [];
-  try {
+  const compile = async (faker3) => {
+    const entry = [
+      `import { main } from ${JSON.stringify(standalonePath())}`,
+      `import config from ${JSON.stringify(project.configFile)}`,
+      ...files.map((f2, i) => `import * as m${i} from ${JSON.stringify(join13(root, f2))}`),
+      ...faker3 ? [`import * as fakerModule from ${JSON.stringify(FAKER)}`] : [],
+      `const data = { ...${JSON.stringify(data2)}, config,`,
+      `  modules: [${files.map((f2, i) => `{ file: ${JSON.stringify(f2)}, mod: m${i} }`).join(", ")}],`,
+      `  faker: ${faker3 ? "fakerModule" : "undefined"} }`,
+      "main(data).then((code) => process.exit(code), (e) => {",
+      "  console.error(e instanceof Error ? e.message : e)",
+      "  process.exit(2)",
+      "})"
+    ].join("\n");
+    const plugin = {
+      name: "specbook-bundle",
+      resolveId(id) {
+        if (id === ENTRY) return ENTRY;
+        if (id === FAKER) return FAKER;
+        if (id.startsWith(`${prefix}/`) && !id.slice(prefix.length + 1).includes("/"))
+          return `\0specbook:api:${id.slice(prefix.length + 1)}`;
+        if (id === "@specbook/core" || id.startsWith("@specbook/core/")) return ours.resolve(id);
+        return void 0;
+      },
+      load(id) {
+        if (id === ENTRY) return entry;
+        if (id === FAKER) return faker3;
+        if (!id.startsWith("\0specbook:api:")) return void 0;
+        const service = id.slice("\0specbook:api:".length);
+        const metas = ops.services[service];
+        if (!metas) throw new Error(`Service "${service}" has no operations your requests use`);
+        return [
+          "import { defineOperation } from '@specbook/core'",
+          ...Object.entries(metas).map(
+            ([opId2, meta]) => `export const ${opId2} = /* @__PURE__ */ defineOperation(${JSON.stringify(meta)})`
+          ),
+          ""
+        ].join("\n");
+      }
+    };
     const build2 = await rolldown({
       input: ENTRY,
       platform: "node",
@@ -8265,7 +8352,7 @@ async function bundleCommand(project, loader, o) {
       }
     });
     await mkdir6(dirname6(out), { recursive: true });
-    await build2.write({
+    const written = await build2.write({
       file: out,
       format: "esm",
       minify: true,
@@ -8273,18 +8360,43 @@ async function bundleCommand(project, loader, o) {
       banner: "#!/usr/bin/env node"
     });
     await build2.close();
+    return written.output.some(
+      (c) => c.type === "chunk" && Object.keys(c.modules).some((m) => m.endsWith("/core/src/faker.ts"))
+    );
+  };
+  const noFaker = () => console.error(
+    "These tests use faker, but @faker-js/faker is not installed in this project. Add it to devDependencies (npm install --save-dev @faker-js/faker)."
+  );
+  try {
+    const text = `${sourceText}
+${JSON.stringify(embedded.examples)}
+${JSON.stringify(environments)}`;
+    let faker3 = USES_FAKER2.test(text) ? await fakerSource(project) : void 0;
+    if (USES_FAKER2.test(text) && !faker3) {
+      noFaker();
+      return 2;
+    }
+    const importsFaker = await compile(faker3);
+    if (importsFaker && !faker3) {
+      faker3 = await fakerSource(project);
+      if (!faker3) {
+        noFaker();
+        return 2;
+      }
+      await compile(faker3);
+    }
   } catch (e) {
     console.error(
       `Could not compile the tests into one file:
 ${e instanceof Error ? e.message : e}`
     );
     console.error(
-      "A package that cannot be compiled in (a native addon, a computed require) can stay an import: --external <package>."
+      "A package that cannot be compiled in (a native addon, a computed require) can stay an import: --external <package>. A browser cannot load it, so replace it with fetch or plain code if the request must also run in the portal."
     );
     return 2;
   }
   await chmod(out, 493);
-  const bytes = await readFile13(out);
+  const bytes = await readFile14(out);
   const hash = sha2562(bytes);
   await writeFile7(`${out}.sha256`, `${hash}  ${basename4(out)}
 `);
@@ -8304,9 +8416,9 @@ ${e instanceof Error ? e.message : e}`
 
 // src/commands/check.ts
 import { existsSync as existsSync8 } from "fs";
-import { readFile as readFile14 } from "fs/promises";
-import { join as join13, resolve as resolve10 } from "path";
-import fg8 from "fast-glob";
+import { readFile as readFile15 } from "fs/promises";
+import { join as join14, resolve as resolve10 } from "path";
+import fg9 from "fast-glob";
 async function checkCommand(project, loader) {
   const errors = [];
   const warnings = [];
@@ -8325,8 +8437,8 @@ async function checkCommand(project, loader) {
       if (untracked.includes(name)) continue;
       let drift = 0;
       for (const f2 of files2) {
-        const p = join13(outDir, name, f2.path);
-        if (!existsSync8(p) || await readFile14(p, "utf8") !== f2.content) drift++;
+        const p = join14(outDir, name, f2.path);
+        if (!existsSync8(p) || await readFile15(p, "utf8") !== f2.content) drift++;
       }
       if (drift)
         errors.push(
@@ -8405,7 +8517,7 @@ async function checkCommand(project, loader) {
     ...fileVarNames
   ]);
   const declared = new Set(Object.keys(cfg.secrets ?? {}));
-  const files = await fg8("**/*.req.ts", {
+  const files = await fg9("**/*.req.ts", {
     cwd: project.root,
     absolute: true,
     ignore: ["**/node_modules/**", "**/.generated/**"]
@@ -8432,9 +8544,9 @@ async function checkCommand(project, loader) {
       ...def.dataPatches
     ]);
     const init2 = new Set(Object.keys(def.input.init ?? {}));
-    const roots = new Set([...used2].map((n) => n.split(".")[0]));
+    const roots = new Set([...used2].map(rootName));
     for (const name of used2) {
-      const root = name.split(".")[0];
+      const root = rootName(name);
       if (name.startsWith("secrets.")) {
         if (!declared.has(name.slice(8)))
           warnings.push(`[${rel2}] secret "${name.slice(8)}" is not declared in config.secrets`);
@@ -8468,15 +8580,125 @@ async function generateCommand(project, loader, only) {
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync9 } from "fs";
-import { mkdir as mkdir7, readFile as readFile15, writeFile as writeFile8 } from "fs/promises";
-import { join as join14 } from "path";
-async function initCommand(cwd) {
-  const dir = join14(cwd, ".specbook");
+import { existsSync as existsSync10 } from "fs";
+import { mkdir as mkdir8, readFile as readFile17, writeFile as writeFile9 } from "fs/promises";
+import { join as join16 } from "path";
+
+// src/commands/agents.ts
+import { existsSync as existsSync9, realpathSync } from "fs";
+import { mkdir as mkdir7, readFile as readFile16, writeFile as writeFile8 } from "fs/promises";
+import { join as join15 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+var FILES = ["AGENTS.md", "CLAUDE.md"];
+var START = "<!-- specbook:start";
+var END = "<!-- specbook:end -->";
+function agentBlock(eol = "\n") {
+  return [
+    `${START} (written by specbook init; \`specbook init --agents\` refreshes it) -->`,
+    "## Specbook",
+    "",
+    "This project uses Specbook: requests (`requests/**/*.req.ts`) and flows (`sequences/**/*.seq.ts`) built from OpenAPI specs run as",
+    "the docs, as tests and as monitors. Before adding or changing one, read `.specbook/agent-guide.md`. In short:",
+    "",
+    "- Import operations from `#api/<service>`. Never edit `.generated/`.",
+    "- Label every `assert`, and use `capture` to pass values between steps.",
+    "- Write isomorphic code: requests and flows also run in the browser, so no Node built-ins, `Buffer` or `process.env`.",
+    "- Run `npx specbook check` and `npx specbook test` before you finish.",
+    END
+  ].join(eol);
+}
+function withBlock(text) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const block = agentBlock(eol);
+  const start = text.indexOf(START);
+  if (start >= 0) {
+    const end = text.indexOf(END, start);
+    if (end < 0) return { text, status: "unterminated" };
+    const next = text.slice(0, start) + block + text.slice(end + END.length);
+    return { text: next, status: next === text ? "unchanged" : "updated" };
+  }
+  if (!text.trim()) return { text: `${block}${eol}`, status: "added" };
+  const lead = text.endsWith("\n") ? "" : eol;
+  return { text: `${text}${lead}${eol}${block}${eol}`, status: "added" };
+}
+var importsAgents = (text) => /^@AGENTS\.md\b/m.test(text);
+async function readGuide() {
+  for (const rel2 of ["../agent-guide.md", "../../agent-guide.md"])
+    try {
+      return await readFile16(fileURLToPath2(new URL(rel2, import.meta.url)), "utf8");
+    } catch {
+    }
+  throw new Error("agent-guide.md is missing from the @specbook/cli package");
+}
+async function agentsStep(cwd, agents) {
+  if (agents === false) return;
+  const dir = join15(cwd, ".specbook");
   await mkdir7(dir, { recursive: true });
-  const cfg = join14(dir, "specbook.config.ts");
-  if (!existsSync9(cfg)) {
+  const guide = await readGuide();
+  await writeFile8(
+    join15(dir, "agent-guide.md"),
+    `<!-- Written by specbook init v${cliVersion()}. Re-run \`specbook init\` to refresh it, and put project rules in AGENTS.md. -->
+
+${guide}`
+  );
+  console.log("\u2713 wrote .specbook/agent-guide.md");
+  const seen = /* @__PURE__ */ new Set();
+  const found = [];
+  for (const f2 of FILES) {
+    if (!existsSync9(join15(cwd, f2))) continue;
+    const real = realpathSync(join15(cwd, f2));
+    if (seen.has(real)) continue;
+    seen.add(real);
+    found.push(f2);
+  }
+  if (found.length === 0) {
     await writeFile8(
+      join15(cwd, "AGENTS.md"),
+      `# AGENTS.md
+
+Instructions for AI coding agents working in this repository.
+
+${agentBlock()}
+`
+    );
+    console.log("\u2713 created AGENTS.md (read by Claude Code, Codex and other coding agents)");
+    return;
+  }
+  if (!agents) {
+    console.log(
+      `${found.join(" and ")} already ${found.length > 1 ? "exist" : "exists"} and was not changed. To add Specbook's section to ${found.length > 1 ? "them" : "it"}: specbook init --agents`
+    );
+    return;
+  }
+  for (const file of found) {
+    const path = join15(cwd, file);
+    const text = await readFile16(path, "utf8");
+    if (file === "CLAUDE.md" && found.includes("AGENTS.md") && importsAgents(text)) {
+      console.log("CLAUDE.md imports AGENTS.md: its section covers Claude Code too");
+      continue;
+    }
+    const r = withBlock(text);
+    if (r.status === "unterminated") {
+      console.log(`! ${file} has a "${START}" marker with no end marker; left unchanged`);
+      continue;
+    }
+    if (r.status === "unchanged") {
+      console.log(`${file} already has Specbook's section`);
+      continue;
+    }
+    await writeFile8(path, r.text);
+    console.log(`\u2713 ${r.status === "added" ? "added" : "updated"} Specbook's section in ${file}`);
+  }
+}
+
+// src/commands/init.ts
+var FAKER_VERSION = "9.3.0";
+async function initCommand(cwd, opts = {}) {
+  const dir = join16(cwd, ".specbook");
+  await mkdir8(dir, { recursive: true });
+  const cfg = join16(dir, "specbook.config.ts");
+  if (!existsSync10(cfg)) {
+    await writeFile9(
       cfg,
       `import { defineConfig } from '@specbook/core'
 
@@ -8495,55 +8717,63 @@ export default defineConfig({
     console.log("\u2713 created .specbook/specbook.config.ts");
   }
   const envDir = await ensureEnvironmentsDir(cwd);
-  const example = join14(envDir, "staging.secrets.env.example");
-  if (!existsSync9(example)) {
-    await writeFile8(
+  const example = join16(envDir, "staging.secrets.env.example");
+  if (!existsSync10(example)) {
+    await writeFile9(
       example,
       "# Copy to staging.secrets.env (gitignored) and fill in. One KEY=value per line.\n# YOUR_API_KEY=\n"
     );
-    await writeFile8(
-      join14(envDir, "staging.env"),
+    await writeFile9(
+      join16(envDir, "staging.env"),
       '# Non-secret variables for the "staging" environment (committed).\n# region=eu-west-1\n'
     );
     console.log("\u2713 created .specbook/environments/ (staging.env, staging.secrets.env.example)");
   }
-  const pkgPath = join14(cwd, "package.json");
-  const pkg = existsSync9(pkgPath) ? JSON.parse(await readFile15(pkgPath, "utf8")) : { name: "my-apis", private: true, type: "module" };
+  const pkgPath = join16(cwd, "package.json");
+  const pkg = existsSync10(pkgPath) ? JSON.parse(await readFile17(pkgPath, "utf8")) : { name: "my-apis", private: true, type: "module" };
   pkg.imports = { ...pkg.imports ?? {}, "#api/*": "./.generated/*/index.ts" };
   pkg.scripts = { ...pkg.scripts ?? {} };
   if (!pkg.scripts.prepare) pkg.scripts.prepare = "specbook generate";
-  await writeFile8(pkgPath, `${JSON.stringify(pkg, null, 2)}
+  pkg.devDependencies = { ...pkg.devDependencies ?? {} };
+  const hasFaker = ["dependencies", "devDependencies", "peerDependencies"].some(
+    (k) => pkg[k]?.["@faker-js/faker"]
+  );
+  if (!hasFaker) pkg.devDependencies["@faker-js/faker"] = FAKER_VERSION;
+  await writeFile9(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `);
-  console.log('\u2713 added the "#api/*" subpath import and a "prepare" script to package.json');
-  const gi = join14(cwd, ".gitignore");
-  const current = existsSync9(gi) ? await readFile15(gi, "utf8") : "";
+  console.log(
+    `\u2713 added the "#api/*" subpath import, a "prepare" script${hasFaker ? "" : " and @faker-js/faker"} to package.json`
+  );
+  const gi = join16(cwd, ".gitignore");
+  const current = existsSync10(gi) ? await readFile17(gi, "utf8") : "";
   const missing = [".generated", ".specbook/secrets.local.env"].filter(
     (entry) => !current.split("\n").some((l) => l.trim() === entry)
   );
   if (missing.length) {
-    await writeFile8(
+    await writeFile9(
       gi,
       `${current}${current.endsWith("\n") || !current ? "" : "\n"}${missing.join("\n")}
 `
     );
     console.log(`\u2713 gitignored ${missing.join(", ")}`);
   }
+  await agentsStep(cwd, opts.agents);
 }
 
 // src/commands/preview.ts
 import { spawn } from "child_process";
-import { existsSync as existsSync10, readFileSync as readFileSync2 } from "fs";
-import { mkdir as mkdir8, mkdtemp as mkdtemp2, rm as rm4, symlink, writeFile as writeFile10 } from "fs/promises";
+import { existsSync as existsSync11, readFileSync as readFileSync2 } from "fs";
+import { mkdir as mkdir9, mkdtemp as mkdtemp2, rm as rm4, symlink, writeFile as writeFile11 } from "fs/promises";
 import { createRequire as createRequire6 } from "module";
 import { tmpdir as tmpdir2 } from "os";
-import { dirname as dirname8, extname, join as join16, resolve as resolve12 } from "path";
+import { dirname as dirname8, extname, join as join18, resolve as resolve12 } from "path";
 import SwaggerParser4 from "@apidevtools/swagger-parser";
 
 // src/commands/ui.ts
-import { copyFile, cp, readFile as readFile16, stat, writeFile as writeFile9 } from "fs/promises";
+import { copyFile, cp, readFile as readFile18, stat, writeFile as writeFile10 } from "fs/promises";
 import { createRequire as createRequire5 } from "module";
-import { basename as basename5, dirname as dirname7, join as join15, resolve as resolve11, sep as sep8 } from "path";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { basename as basename5, dirname as dirname7, join as join17, resolve as resolve11, sep as sep8 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
 import { build, createServer } from "vite";
 function uiRoot() {
   const require2 = createRequire5(import.meta.url);
@@ -8562,10 +8792,10 @@ function enclosingNodeModules(file) {
 }
 function dependencyFolders(root) {
   const found = /* @__PURE__ */ new Set([
-    ...enclosingNodeModules(fileURLToPath2(import.meta.url)),
-    ...enclosingNodeModules(join15(root, "package.json"))
+    ...enclosingNodeModules(fileURLToPath3(import.meta.url)),
+    ...enclosingNodeModules(join17(root, "package.json"))
   ]);
-  for (const from of [join15(root, "package.json"), fileURLToPath2(import.meta.url)]) {
+  for (const from of [join17(root, "package.json"), fileURLToPath3(import.meta.url)]) {
     const require2 = createRequire5(from);
     for (const name of ["vite", "prism-code-editor", "preact", "@preact/signals"]) {
       try {
@@ -8590,7 +8820,12 @@ function uiConfig(project, operations) {
       rolldownOptions: { transform: { jsx: { runtime: "automatic", importSource: "preact" } } }
     },
     plugins: [
-      specbook({ projectRoot: project.root, outDir: project.config.codegen?.outDir, operations })
+      specbook({
+        projectRoot: project.root,
+        outDir: project.config.codegen?.outDir,
+        operations,
+        faker: project.config.faker
+      })
     ],
     server: {
       fs: {
@@ -8623,7 +8858,7 @@ async function devCommand(project, port = 5173) {
 }
 async function buildCommand(project, outDir, options = {}) {
   const out = resolve11(project.root, outDir);
-  const generated = join15(project.root, project.config.codegen?.outDir ?? ".generated");
+  const generated = join17(project.root, project.config.codegen?.outDir ?? ".generated");
   const operations = options.minimal ? await usedOperationKeys(project, generated) : void 0;
   if (operations && operations.size === 0)
     throw new Error("Nothing to publish: no request or flow imports an operation (see --minimal)");
@@ -8645,25 +8880,25 @@ async function buildCommand(project, outDir, options = {}) {
       }
     }
   });
-  await copyMetadata(join15(generated, "specbook.json"), join15(out, "specbook.json"), operations);
+  await copyMetadata(join17(generated, "specbook.json"), join17(out, "specbook.json"), operations);
 }
 async function copyMetadata(from, to, operations) {
   try {
     if (!operations) return await copyFile(from, to);
-    const meta = JSON.parse(await readFile16(from, "utf8"));
+    const meta = JSON.parse(await readFile18(from, "utf8"));
     for (const [svc, s] of Object.entries(meta.services)) {
       s.operations = Object.fromEntries(
         Object.entries(s.operations).filter(([id]) => operations.has(`${svc}/${id}`))
       );
       if (Object.keys(s.operations).length === 0) delete meta.services[svc];
     }
-    await writeFile9(to, `${JSON.stringify(meta)}
+    await writeFile10(to, `${JSON.stringify(meta)}
 `);
   } catch {
   }
 }
 async function copyViewer(project, outDir, viewerDir = resolve11(uiRoot(), "dist-viewer")) {
-  const has2 = await stat(join15(viewerDir, "index.html")).then(
+  const has2 = await stat(join17(viewerDir, "index.html")).then(
     () => true,
     () => false
   );
@@ -8682,10 +8917,10 @@ var slug3 = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/
 async function link(root, name) {
   try {
     let dir = dirname8(createRequire6(import.meta.url).resolve(name));
-    while (!existsSync10(join16(dir, "package.json")) || JSON.parse(readFileSync2(join16(dir, "package.json"), "utf8")).name !== name)
+    while (!existsSync11(join18(dir, "package.json")) || JSON.parse(readFileSync2(join18(dir, "package.json"), "utf8")).name !== name)
       dir = dirname8(dir);
-    const dest = join16(root, "node_modules", ...name.split("/"));
-    await mkdir8(dirname8(dest), { recursive: true });
+    const dest = join18(root, "node_modules", ...name.split("/"));
+    await mkdir9(dirname8(dest), { recursive: true });
     await symlink(dir, dest, "dir");
   } catch {
   }
@@ -8705,7 +8940,7 @@ async function previewCommand(source, o = {}) {
   const { servers } = openApiServers(api, source);
   const where = servers.length === 0 ? "" : servers.length === 1 && servers[0]?.name === "live" ? `, live calls go to ${servers[0].url}` : `
   Environments: ${servers.map((s) => `${s.name} \u2192 ${s.url}`).join(", ")}`;
-  const root = await mkdtemp2(join16(tmpdir2(), "specbook-preview-"));
+  const root = await mkdtemp2(join18(tmpdir2(), "specbook-preview-"));
   const cleanup = () => rm4(root, { recursive: true, force: true }).catch(() => {
   });
   process.once("SIGINT", () => cleanup().then(() => process.exit(0)));
@@ -8715,9 +8950,9 @@ async function previewCommand(source, o = {}) {
     const res = await fetch(source);
     if (!res.ok) throw new Error(`Could not fetch ${source} (${res.status})`);
     const ext = /ya?ml/.test(extname(new URL(source).pathname)) ? ".yaml" : ".json";
-    specFile = join16(root, `openapi/api${ext}`);
-    await mkdir8(dirname8(specFile), { recursive: true });
-    await writeFile10(specFile, await res.text());
+    specFile = join18(root, `openapi/api${ext}`);
+    await mkdir9(dirname8(specFile), { recursive: true });
+    await writeFile11(specFile, await res.text());
   }
   const {
     auth,
@@ -8750,14 +8985,14 @@ async function previewCommand(source, o = {}) {
       }
     }
   };
-  const configFile = join16(root, ".specbook/specbook.config.ts");
-  await mkdir8(dirname8(configFile), { recursive: true });
-  await writeFile10(configFile, `export default ${JSON.stringify(config, null, 2)}
+  const configFile = join18(root, ".specbook/specbook.config.ts");
+  await mkdir9(dirname8(configFile), { recursive: true });
+  await writeFile11(configFile, `export default ${JSON.stringify(config, null, 2)}
 `);
   await link(root, "@specbook/core");
   await link(root, "@faker-js/faker");
   console.log(`Generating "${title}" \u2026`);
-  const out = await generateToDisk({ spec: specFile, service, outDir: join16(root, ".generated") });
+  const out = await generateToDisk({ spec: specFile, service, outDir: join18(root, ".generated") });
   console.log(`\u2713 ${out.operations.length} operations${where}`);
   const project = { root, configFile, config };
   const server = await devCommand(project, o.port ?? 5173);
@@ -8826,18 +9061,18 @@ import { resolve as resolve15 } from "path";
 
 // src/examples.ts
 import { File } from "buffer";
-import { readFile as readFile17 } from "fs/promises";
-import { basename as basename6, dirname as dirname9, join as join17, resolve as resolve14 } from "path";
-import fg9 from "fast-glob";
-var IGNORE3 = ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"];
+import { readFile as readFile19 } from "fs/promises";
+import { basename as basename6, dirname as dirname9, join as join19, resolve as resolve14 } from "path";
+import fg10 from "fast-glob";
+var IGNORE4 = ["**/node_modules/**", "**/.generated/**", "**/dist/**", "**/.git/**"];
 function exampleLoadersFor(project) {
   const outDir = resolve14(project.root, project.config.codegen?.outDir ?? ".generated");
   const example = async (op, name) => {
     const rel2 = `${op.service}/${op.id}/${name}.example.json`;
-    const [custom] = await fg9(`**/${rel2}`, { cwd: project.root, absolute: true, ignore: IGNORE3 });
-    const file = custom ?? join17(outDir, op.service, "examples", op.id, `${name}.example.json`);
+    const [custom] = await fg10(`**/${rel2}`, { cwd: project.root, absolute: true, ignore: IGNORE4 });
+    const file = custom ?? join19(outDir, op.service, "examples", op.id, `${name}.example.json`);
     try {
-      const doc = JSON.parse(await readFile17(file, "utf8"));
+      const doc = JSON.parse(await readFile19(file, "utf8"));
       return { ...doc, source: custom ? "project" : "generated", dir: dirname9(file) };
     } catch {
       return void 0;
@@ -8845,7 +9080,7 @@ function exampleLoadersFor(project) {
   };
   const read = async (path, dir) => {
     const abs = resolve14(dir ?? project.root, path);
-    return new File([await readFile17(abs)], basename6(abs));
+    return new File([await readFile19(abs)], basename6(abs));
   };
   return { example, readFile: read };
 }
@@ -8876,7 +9111,8 @@ async function testCommand(project, loader, o) {
       readEnvironment: (env) => readEnvironment(project.root, env),
       examples: exampleLoadersFor(project),
       mock: mockLoaderFor(project),
-      loadFaker: () => loadFaker(project),
+      // only a project that uses faker pays for importing it
+      loadFaker: async () => await projectUsesFaker(project.root) ? loadFaker(project) : void 0,
       readSource: (file) => {
         try {
           return readFileSync3(file, "utf8");
@@ -8960,7 +9196,7 @@ var TEST_HELP = `      --env <name>             environment (default: mock, for
       --input k=v              flow input value (repeatable)
       --var k=v                variable override (repeatable)
       --secrets-file <path>    dotenv file with secrets
-      --locale <l> --seed <n>  synthetic data locale / deterministic seed
+      --locale <l> --seed <n>  generated values: locale / seed for a repeatable run
       --notify <url>           POST a summary to a webhook when something fails`;
 var parseValue = (v2) => {
   try {
@@ -9012,7 +9248,9 @@ function testOptions(values, patterns) {
 // src/bin.ts
 var HELP = `specbook <command>
 
-  init                         scaffold config, #api/* import and the environments folder
+  init                         scaffold config, #api/* import, the environments folder and an agent guide
+      --agents                 add a Specbook section to an existing AGENTS.md or CLAUDE.md (never edited otherwise)
+      --no-agents              skip the agent guide and AGENTS.md
   add <service> --spec <p|url> register an OpenAPI spec in the config and generate it; an address is downloaded to
                                openapi/ and recorded in openapi/sources.json
   add --refresh [service...]   download the recorded addresses again, say what changed and regenerate it
@@ -9028,7 +9266,7 @@ var HELP = `specbook <command>
 ${TEST_HELP}
   bundle [--out <file>]        compile the tests into one .mjs that runs with just node: for CI or ops, no install
       --tag <t>                only the requests and flows with this tag (repeatable)
-      --external <pkg>         leave a package as an import (it must be installed where the file runs; repeatable)
+      --external <pkg>         leave a package as an import (installed where the file runs; a browser cannot load it; repeatable)
   check                        validate specs, generated code drift, imported operations, placeholders and environment files
   secrets [--env <name>]       show where each declared secret resolves from (never values)
       --secrets-file <path>    include a dotenv file, as test would
@@ -9046,6 +9284,8 @@ async function main() {
       out: { type: "string" },
       external: { type: "string", multiple: true },
       "no-open": { type: "boolean" },
+      agents: { type: "boolean" },
+      "no-agents": { type: "boolean" },
       viewer: { type: "boolean" },
       minimal: { type: "boolean" },
       help: { type: "boolean", short: "h" }
@@ -9070,7 +9310,13 @@ async function main() {
     });
   }
   if (cmd === "init") {
-    await initCommand(cwd);
+    if (values.agents && values["no-agents"]) {
+      console.error("init: pass --agents or --no-agents, not both\n");
+      return 3;
+    }
+    await initCommand(cwd, {
+      agents: values["no-agents"] ? false : values.agents ? true : void 0
+    });
     return 0;
   }
   if (!["generate", "test", "bundle", "dev", "build", "add", "check", "secrets"].includes(cmd)) {