@specbook/cli 0.4.0 → 0.5.0

package/agent-guide.md

@@ -106,7 +106,7 @@ export default sequence({
 - `request.with({ ... })` changes a request for one step (for example its `assert`).
 - Also: `.input(name, ctx => controls)` asks a person for values, `.each(name, items, make)` repeats a request per item, `.check(name, fn)` asserts on the flow's state, `.use(otherFlow)` includes another flow.
 - Controls are `c.number`, `c.text`, `c.select`, `c.multiselect`, `c.boolean`, `c.date`, `c.object`, `c.array`. A flow also runs unattended in CI and as a monitor, so every input and every `.input()` control needs a default that makes sense with nobody to ask.
-- For generated data: `import { faker } from '@specbook/core/faker'` and use it in a default, for example `c.text({ default: () => faker.person.fullName() })`.
+- For generated data: `import { faker } from '@specbook/core/faker'` and use it in a default, for example `c.text({ default: () => faker.person.fullName() })`. It is typed, and `specbook init` installs `@faker-js/faker`. A `{{faker.person.firstName}}` placeholder (`faker.<module>.<method>`, no arguments) also works in a field.
 - Each step is also a request you can run alone.
 
 ### Recipe: list, check, pick, act

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) => {
@@ -2161,15 +2121,25 @@ 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) {
@@ -2184,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];
@@ -2944,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 join19 = (...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      ")} ${join19(
+    `${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      ")} ${join19(
+    `${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 ")} ${join19(
+    `${c.bold(" Assertions ")} ${join20(
       part(t.assertions.failed, "failed", c.red),
       part(t.assertions.passed, "passed", c.green)
     )}`
@@ -5501,6 +5483,16 @@ var faker2 = new Proxy({}, {
     return current[key];
   }
 });
+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");
@@ -5518,15 +5510,25 @@ 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) {
@@ -5541,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];
@@ -6221,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();
@@ -6508,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))
@@ -6516,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]) => [
@@ -6616,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(
@@ -6987,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}`;
@@ -6996,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")}
@@ -7484,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;
@@ -7540,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,
@@ -7558,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)) {
@@ -7593,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;
   }
@@ -7630,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";
@@ -7645,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",
@@ -7656,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);
@@ -7665,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);
@@ -7676,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
@@ -8055,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/**"]
@@ -8074,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;
@@ -8088,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"
             )
           );
@@ -8102,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;
@@ -8130,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");
@@ -8140,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-[^/]+)(\/|$)/;
@@ -8148,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: ""
         };
@@ -8181,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)}
@@ -8228,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))
@@ -8246,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",
@@ -8300,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,
@@ -8308,6 +8360,31 @@ 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:
@@ -8319,7 +8396,7 @@ ${e instanceof Error ? e.message : e}`
     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)}
 `);
@@ -8339,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 = [];
@@ -8360,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(
@@ -8440,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/**"]
@@ -8504,13 +8581,13 @@ async function generateCommand(project, loader, only) {
 
 // src/commands/init.ts
 import { existsSync as existsSync10 } from "fs";
-import { mkdir as mkdir8, readFile as readFile16, writeFile as writeFile9 } from "fs/promises";
-import { join as join15 } from "path";
+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 readFile15, writeFile as writeFile8 } from "fs/promises";
-import { join as join14 } from "path";
+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";
@@ -8548,18 +8625,18 @@ 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 readFile15(fileURLToPath2(new URL(rel2, import.meta.url)), "utf8");
+      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 = join14(cwd, ".specbook");
+  const dir = join15(cwd, ".specbook");
   await mkdir7(dir, { recursive: true });
   const guide = await readGuide();
   await writeFile8(
-    join14(dir, "agent-guide.md"),
+    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}`
@@ -8568,15 +8645,15 @@ ${guide}`
   const seen = /* @__PURE__ */ new Set();
   const found = [];
   for (const f2 of FILES) {
-    if (!existsSync9(join14(cwd, f2))) continue;
-    const real = realpathSync(join14(cwd, f2));
+    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(
-      join14(cwd, "AGENTS.md"),
+      join15(cwd, "AGENTS.md"),
       `# AGENTS.md
 
 Instructions for AI coding agents working in this repository.
@@ -8594,8 +8671,8 @@ ${agentBlock()}
     return;
   }
   for (const file of found) {
-    const path = join14(cwd, file);
-    const text = await readFile15(path, "utf8");
+    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;
@@ -8615,10 +8692,11 @@ ${agentBlock()}
 }
 
 // src/commands/init.ts
+var FAKER_VERSION = "9.3.0";
 async function initCommand(cwd, opts = {}) {
-  const dir = join15(cwd, ".specbook");
+  const dir = join16(cwd, ".specbook");
   await mkdir8(dir, { recursive: true });
-  const cfg = join15(dir, "specbook.config.ts");
+  const cfg = join16(dir, "specbook.config.ts");
   if (!existsSync10(cfg)) {
     await writeFile9(
       cfg,
@@ -8639,28 +8717,35 @@ export default defineConfig({
     console.log("\u2713 created .specbook/specbook.config.ts");
   }
   const envDir = await ensureEnvironmentsDir(cwd);
-  const example = join15(envDir, "staging.secrets.env.example");
+  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 writeFile9(
-      join15(envDir, "staging.env"),
+      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 = join15(cwd, "package.json");
-  const pkg = existsSync10(pkgPath) ? JSON.parse(await readFile16(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";
+  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 = join15(cwd, ".gitignore");
-  const current = existsSync10(gi) ? await readFile16(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)
   );
@@ -8681,13 +8766,13 @@ 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 join17, 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 readFile17, stat, writeFile as writeFile10 } 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 join16, resolve as resolve11, sep as sep8 } from "path";
+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() {
@@ -8708,9 +8793,9 @@ function enclosingNodeModules(file) {
 function dependencyFolders(root) {
   const found = /* @__PURE__ */ new Set([
     ...enclosingNodeModules(fileURLToPath3(import.meta.url)),
-    ...enclosingNodeModules(join16(root, "package.json"))
+    ...enclosingNodeModules(join17(root, "package.json"))
   ]);
-  for (const from of [join16(root, "package.json"), fileURLToPath3(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 {
@@ -8735,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: {
@@ -8768,7 +8858,7 @@ async function devCommand(project, port = 5173) {
 }
 async function buildCommand(project, outDir, options = {}) {
   const out = resolve11(project.root, outDir);
-  const generated = join16(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)");
@@ -8790,12 +8880,12 @@ async function buildCommand(project, outDir, options = {}) {
       }
     }
   });
-  await copyMetadata(join16(generated, "specbook.json"), join16(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 readFile17(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}`))
@@ -8808,7 +8898,7 @@ async function copyMetadata(from, to, operations) {
   }
 }
 async function copyViewer(project, outDir, viewerDir = resolve11(uiRoot(), "dist-viewer")) {
-  const has2 = await stat(join16(viewerDir, "index.html")).then(
+  const has2 = await stat(join17(viewerDir, "index.html")).then(
     () => true,
     () => false
   );
@@ -8827,9 +8917,9 @@ 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 (!existsSync11(join17(dir, "package.json")) || JSON.parse(readFileSync2(join17(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 = join17(root, "node_modules", ...name.split("/"));
+    const dest = join18(root, "node_modules", ...name.split("/"));
     await mkdir9(dirname8(dest), { recursive: true });
     await symlink(dir, dest, "dir");
   } catch {
@@ -8850,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(join17(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)));
@@ -8860,7 +8950,7 @@ 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 = join17(root, `openapi/api${ext}`);
+    specFile = join18(root, `openapi/api${ext}`);
     await mkdir9(dirname8(specFile), { recursive: true });
     await writeFile11(specFile, await res.text());
   }
@@ -8895,14 +8985,14 @@ async function previewCommand(source, o = {}) {
       }
     }
   };
-  const configFile = join17(root, ".specbook/specbook.config.ts");
+  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: join17(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);
@@ -8971,18 +9061,18 @@ import { resolve as resolve15 } from "path";
 
 // src/examples.ts
 import { File } from "buffer";
-import { readFile as readFile18 } from "fs/promises";
-import { basename as basename6, dirname as dirname9, join as join18, 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 ?? join18(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 readFile18(file, "utf8"));
+      const doc = JSON.parse(await readFile19(file, "utf8"));
       return { ...doc, source: custom ? "project" : "generated", dir: dirname9(file) };
     } catch {
       return void 0;
@@ -8990,7 +9080,7 @@ function exampleLoadersFor(project) {
   };
   const read = async (path, dir) => {
     const abs = resolve14(dir ?? project.root, path);
-    return new File([await readFile18(abs)], basename6(abs));
+    return new File([await readFile19(abs)], basename6(abs));
   };
   return { example, readFile: read };
 }
@@ -9021,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");
@@ -9105,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 {

package/dist/standalone.js

@@ -470,7 +470,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 = (v) => {
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specbook/cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Specbook command line: init, add, generate, dev, build, test, bundle, check, secrets and preview.",
   "keywords": [
     "specbook",
@@ -38,10 +38,10 @@
   "dependencies": {
     "@apidevtools/swagger-parser": "10.1.1",
     "@faker-js/faker": "9.3.0",
-    "@specbook/codegen": "0.4.0",
-    "@specbook/core": "0.4.0",
-    "@specbook/ui": "0.4.0",
-    "@specbook/vite": "0.4.0",
+    "@specbook/codegen": "0.5.0",
+    "@specbook/core": "0.5.0",
+    "@specbook/ui": "0.5.0",
+    "@specbook/vite": "0.5.0",
     "fast-glob": "3.3.2",
     "rolldown": "1.2.13",
     "swagger2openapi": "7.0.8",