@specbook/cli 0.2.0 → 0.4.0

package/dist/standalone.js

@@ -0,0 +1,593 @@
+// src/standalone.ts
+import { File } from "buffer";
+import { basename, posix } from "path";
+import { parseArgs } from "util";
+import {
+  environmentNames
+} from "@specbook/core";
+
+// src/run-tests.ts
+import { execFileSync } from "child_process";
+import { appendFileSync, readFileSync } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import { hostname } from "os";
+import { dirname as dirname2, resolve as resolve2 } from "path";
+import {
+  baseUrlFor,
+  buildReport,
+  collectSecretNames,
+  colorEnabled,
+  createColors,
+  createFetchTransport,
+  createListReporter,
+  createMockTransport,
+  detectCi,
+  dotenvProvider,
+  environmentScope,
+  envProvider,
+  formatGithub,
+  formatList,
+  githubSummary,
+  headerLine,
+  installFaker,
+  MissingSecretsError,
+  maskDeep,
+  redactEvent,
+  redactResults,
+  resolveSecrets,
+  retryLine,
+  runSuite,
+  testExitCode,
+  toJUnit,
+  withoutLocations
+} from "@specbook/core";
+
+// src/project.ts
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { parseDotenv } from "@specbook/core";
+async function readDotenv(path) {
+  if (!existsSync(path)) return {};
+  return parseDotenv(await readFile(path, "utf8"));
+}
+
+// src/version.ts
+import { createRequire } from "module";
+var fixed;
+function fixCliVersion(version) {
+  fixed = version;
+}
+function cliVersion() {
+  if (fixed !== void 0) return fixed;
+  const require2 = createRequire(import.meta.url);
+  for (const p of ["../package.json", "../../package.json"])
+    try {
+      return require2(p).version;
+    } catch {
+    }
+  return "";
+}
+
+// src/run-tests.ts
+var titleOf = (r) => r.kind === "sequence" ? r.meta.title : r.input.name ?? r.op.id;
+var tagsOf = (r) => r.kind === "sequence" ? r.meta.tags ?? [] : r.input.tags ?? [];
+function isRunnable(v) {
+  const k = v?.kind;
+  return k === "request" || k === "sequence";
+}
+function targetsOf(mod, file) {
+  const found = isRunnable(mod.default) ? [mod.default] : Object.values(mod).filter(isRunnable);
+  return found.map((run) => ({ run, file, title: titleOf(run), tags: tagsOf(run) }));
+}
+var KINDS = ["list", "json", "junit", "github", "ndjson"];
+function gitInfo(root) {
+  const git = (...args) => {
+    try {
+      return execFileSync("git", args, { cwd: root, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    } catch {
+      return void 0;
+    }
+  };
+  return {
+    sha: git("rev-parse", "--short", "HEAD"),
+    branch: git("rev-parse", "--abbrev-ref", "HEAD")
+  };
+}
+var quote = (s) => `"${s.replace(/(["\\$`])/g, "\\$1")}"`;
+var escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function parseShard(s) {
+  const m = /^(\d+)\/(\d+)$/.exec(s);
+  if (!m) return void 0;
+  const [index, total] = [Number(m[1]), Number(m[2])];
+  return index >= 1 && total >= 1 && index <= total ? { index, total } : void 0;
+}
+function select(targets, o) {
+  let out = targets;
+  if (o.tags.length) out = out.filter((t) => t.tags.some((x) => o.tags.includes(x)));
+  try {
+    if (o.grep) {
+      const re = new RegExp(o.grep, "i");
+      out = out.filter((t) => re.test(`${t.file} ${t.title}`));
+    }
+    if (o.grepInvert) {
+      const re = new RegExp(o.grepInvert, "i");
+      out = out.filter((t) => !re.test(`${t.file} ${t.title}`));
+    }
+  } catch (e) {
+    return `Bad --grep expression: ${e instanceof Error ? e.message : e}`;
+  }
+  if (o.shard) {
+    const shard = parseShard(o.shard);
+    if (!shard) return `Bad --shard "${o.shard}": use i/n, for example 1/3`;
+    out = out.filter((_, i) => i % shard.total === shard.index - 1);
+  }
+  return out;
+}
+var authOf = (config) => config.auth ?? {};
+var serviceAuthOf = (config) => Object.fromEntries(
+  Object.entries(config.services).filter(([, s]) => s.auth).map(([n, s]) => [n, s.auth])
+);
+async function resolveRunSecrets(ctx, targets, env, files, secretsFile) {
+  const needed = /* @__PURE__ */ new Set();
+  for (const t of targets)
+    for (const n of await collectSecretNames(
+      t,
+      authOf(ctx.config),
+      ctx.examples.example,
+      serviceAuthOf(ctx.config)
+    ))
+      needed.add(n);
+  const providers = [
+    envProvider(process.env),
+    ...secretsFile ? [dotenvProvider(await readDotenv(resolve2(secretsFile)), "secrets-file")] : [],
+    dotenvProvider(files.secrets, `environments/${env}.secrets.env`),
+    dotenvProvider(files.shared, "secrets.local.env"),
+    ...ctx.config.secretProviders ?? []
+  ];
+  return resolveSecrets(needed, ctx.config.secrets ?? {}, providers);
+}
+function missingSecretsMessage(e, env, files) {
+  const list = `Missing secrets for "${env}":
+  ${e.names.join("\n  ")}
+
+`;
+  return files ? `${list}Set them as environment variables, or in .specbook/environments/${env}.secrets.env (or .specbook/secrets.local.env to share across environments).` : `${list}Set them as environment variables.`;
+}
+function transportFor(ctx, env, vars) {
+  if (env === "mock") return createMockTransport({ loader: ctx.mock });
+  return createFetchTransport({
+    baseUrl: (service) => {
+      const url = baseUrlFor(ctx.config, service, env, vars);
+      if (!url) throw new Error(`No baseUrl for service "${service}" in env "${env}"`);
+      return url;
+    }
+  });
+}
+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) {
+        const u = new URL(url);
+        out[service] = basePath ? `${u.origin}${u.pathname.replace(/\/+$/, "")}` : u.origin;
+      }
+    } catch {
+    }
+  }
+  return out;
+}
+async function runTests(ctx, o) {
+  const specs = (o.reporters.length ? o.reporters : ["list"]).map((s) => {
+    const [kind, path] = s.split(/:(.*)/s);
+    return { kind, path };
+  });
+  const bad = specs.find((s) => !KINDS.includes(s.kind));
+  if (bad) {
+    console.error(`Unknown reporter "${bad.kind}". Use: ${KINDS.join(", ")}`);
+    return 3;
+  }
+  if (process.env.GITHUB_ACTIONS === "true" && !specs.some((s) => s.kind === "github"))
+    specs.push({ kind: "github", path: void 0 });
+  if (!ctx.environments.includes(o.env)) {
+    console.error(`Unknown environment "${o.env}". Known: ${ctx.environments.join(", ")}`);
+    return 3;
+  }
+  const picked = select(ctx.targets, o);
+  if (typeof picked === "string") {
+    console.error(picked);
+    return 3;
+  }
+  if (picked.length === 0) {
+    console.error(
+      "Nothing to run: no request or flow found, or none matched --tag, --grep or --shard."
+    );
+    return 3;
+  }
+  if (o.list) {
+    for (const t of picked)
+      console.log(`${t.file} \u203A ${t.title}${t.tags.length ? `  [${t.tags.join(", ")}]` : ""}`);
+    console.log(`
+${picked.length} ${picked.length === 1 ? "test" : "tests"}`);
+    return 0;
+  }
+  if (o.env === "mock" && !ctx.mock) {
+    console.error(
+      "The mock environment is for development, where the generated examples are. Test a real environment (--env <name>)."
+    );
+    return 2;
+  }
+  const envFiles = await ctx.readEnvironment(o.env);
+  let secrets = {};
+  if (o.env !== "mock") {
+    try {
+      secrets = await resolveRunSecrets(
+        ctx,
+        picked.map((t) => t.run),
+        o.env,
+        envFiles,
+        o.secretsFile
+      );
+    } catch (e) {
+      if (e instanceof MissingSecretsError) {
+        console.error(missingSecretsMessage(e, o.env, ctx.secretFiles !== false));
+        return 2;
+      }
+      throw e;
+    }
+  }
+  try {
+    return await execute(ctx, o, picked, specs, envFiles.vars, secrets);
+  } catch (e) {
+    console.error(maskDeep(e instanceof Error ? e.message : String(e), Object.values(secrets)));
+    return 2;
+  }
+}
+async function execute(ctx, o, picked, specs, fileVars, secrets) {
+  const config = ctx.config;
+  const total = ctx.targets.length;
+  const given = Object.fromEntries(
+    Object.entries(o.vars).map(([k, v]) => [k, typeof v === "string" ? v : JSON.stringify(v)])
+  );
+  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 faker = await ctx.loadFaker();
+  const git = { ...ctx.git ?? gitInfo(ctx.root) };
+  const ci = detectCi(process.env);
+  if (ci?.sha) git.sha = ci.sha.slice(0, 7);
+  if (ci?.branch) git.branch = ci.branch;
+  const bundle = ctx.bundle;
+  const colors = createColors(colorEnabled(process.env, !!process.stdout.isTTY));
+  const readSource = ctx.readSource ?? ((file) => {
+    try {
+      return readFileSync(file, "utf8");
+    } catch {
+      return void 0;
+    }
+  });
+  const listOptions = {
+    colors,
+    quiet: o.quiet,
+    trace: o.trace,
+    origins: addresses,
+    cwd: ctx.root,
+    readSource,
+    rerun: (r) => `${ctx.command}${r.file && ctx.command === "specbook test" ? ` ${r.file}` : ""} --env ${o.env} --grep ${quote(escapeRegExp(r.title))}${o.safe ? " --safe" : ""}`
+  };
+  const startedAt = /* @__PURE__ */ new Date();
+  const list = specs.find((s) => s.kind === "list");
+  const streaming = list && !list.path ? createListReporter({ ...listOptions, write: (s) => process.stdout.write(s) }) : void 0;
+  const ndjson = specs.find((s) => s.kind === "ndjson");
+  const ndjsonLines = [];
+  let flow = "";
+  const onEvent = (e) => {
+    streaming?.onEvent(e);
+    if (e.type === "run:start") flow = e.title ?? e.id;
+    if (ndjson && e.type !== "done") {
+      const line = JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), flow, ...redactEvent(e) });
+      if (ndjson.path) ndjsonLines.push(line);
+      else process.stdout.write(`${line}
+`);
+    }
+  };
+  if (streaming && !o.quiet) {
+    const where = [
+      git.branch && git.sha ? `${git.branch}@${git.sha}` : git.sha ?? "",
+      bundle ? ["bundle", bundle.sha, `built ${bundle.createdAt.slice(0, 10)}`].filter(Boolean).join(" ") : ""
+    ].filter(Boolean);
+    process.stdout.write(
+      headerLine(
+        { version: cliVersion(), env: o.env, picked: picked.length, total, where },
+        colors
+      )
+    );
+  }
+  const { results, notRun, stopped } = await runSuite(picked, {
+    run: {
+      env: o.env,
+      vars,
+      overrides: o.vars,
+      inputs: o.inputs,
+      transport,
+      secrets,
+      auth: authOf(config),
+      serviceAuth: serviceAuthOf(config),
+      locale: o.locale,
+      seed: o.seed,
+      onEvent,
+      example: ctx.examples.example,
+      readFile: ctx.examples.readFile,
+      readOnly: o.safe === true,
+      implicitStatusCheck: true,
+      // the flag, else the project's own, else the runner's 30 seconds
+      timeoutMs: o.timeoutMs ?? config.timeoutMs
+    },
+    retries: o.retries,
+    bail: o.bail,
+    globalTimeoutMs: o.globalTimeoutMs,
+    beforeAttempt: () => {
+      if (faker) installFaker(faker, config.faker, { locale: o.locale, seed: o.seed });
+    },
+    onRetry: (t, attempt, allowed) => {
+      if (streaming) process.stdout.write(retryLine(colors, t.title, attempt, allowed));
+      if (ndjson && !ndjson.path)
+        process.stdout.write(
+          `${JSON.stringify({ ts: (/* @__PURE__ */ new Date()).toISOString(), type: "retry", flow: t.title, attempt })}
+`
+        );
+    }
+  });
+  const finishedAt = /* @__PURE__ */ new Date();
+  const meta = {
+    env: o.env,
+    specbook: cliVersion(),
+    node: process.version,
+    os: `${process.platform}-${process.arch}`,
+    git: git.sha || git.branch ? git : void 0,
+    ci,
+    bundle: bundle ? { sha: bundle.sha, createdAt: bundle.createdAt } : void 0,
+    services: origins,
+    startedAt: startedAt.toISOString(),
+    finishedAt: finishedAt.toISOString()
+  };
+  const clean = redactResults(ctx.hideLocations ? withoutLocations(results) : results);
+  const write = async (path, text) => {
+    if (!path) return process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+    await mkdir(dirname2(resolve2(path)), { recursive: true });
+    await writeFile(resolve2(path), text.endsWith("\n") ? text : `${text}
+`);
+  };
+  for (const s of specs) {
+    if (s.kind === "list") {
+      if (streaming) streaming.onEnd(clean);
+      else
+        await write(
+          s.path,
+          formatList(clean, {
+            ...listOptions,
+            colors: createColors(false),
+            durationMs: finishedAt.getTime() - startedAt.getTime()
+          })
+        );
+    } else if (s.kind === "json") {
+      await write(s.path, JSON.stringify(buildReport(clean, meta), null, 2));
+    } else if (s.kind === "junit") {
+      await write(
+        s.path,
+        toJUnit(clean, {
+          timestamp: meta.startedAt,
+          hostname: hostname(),
+          origins: addresses,
+          properties: { env: o.env, sha: git.sha, branch: git.branch, specbook: meta.specbook }
+        })
+      );
+    } else if (s.kind === "github") {
+      await write(s.path, formatGithub(clean, { cwd: ctx.root }));
+      const summary = process.env.GITHUB_STEP_SUMMARY;
+      if (summary && process.env.GITHUB_ACTIONS === "true")
+        appendFileSync(summary, githubSummary(clean, { env: o.env, runUrl: ci?.runUrl }));
+    } else if (s.kind === "ndjson" && s.path) {
+      const totals = buildReport(clean, meta).totals;
+      ndjsonLines.push(JSON.stringify({ ts: meta.finishedAt, type: "summary", totals }));
+      await write(s.path, ndjsonLines.join("\n"));
+    }
+  }
+  if (ndjson && !ndjson.path) {
+    process.stdout.write(
+      `${JSON.stringify({ ts: meta.finishedAt, type: "summary", totals: buildReport(clean, meta).totals })}
+`
+    );
+  }
+  if (stopped) console.error(`${colors.yellow(stopped)}${notRun ? `: ${notRun} not run` : ""}`);
+  const code = stopped ? 1 : testExitCode(results);
+  if (o.notify && code !== 0) {
+    const failed = results.filter((r) => r.status !== "pass");
+    try {
+      await fetch(o.notify, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          text: `specbook: ${failed.length}/${results.length} runs failed in ${o.env}: ${failed.map((r) => r.title).join(", ")}`,
+          env: o.env,
+          failed: failed.map((r) => ({
+            id: r.id,
+            title: r.title,
+            status: r.status,
+            totals: r.totals
+          }))
+        })
+      });
+    } catch (e) {
+      console.error(`notify failed: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+  return code;
+}
+
+// src/test-args.ts
+var UsageError = class extends Error {
+};
+var TEST_FLAGS = {
+  env: { type: "string", default: "mock" },
+  input: { type: "string", multiple: true },
+  var: { type: "string", multiple: true },
+  tag: { type: "string", multiple: true },
+  reporter: { type: "string", multiple: true },
+  "secrets-file": { type: "string" },
+  locale: { type: "string" },
+  seed: { type: "string" },
+  notify: { type: "string" },
+  grep: { type: "string" },
+  "grep-invert": { type: "string" },
+  list: { type: "boolean" },
+  shard: { type: "string" },
+  bail: { type: "string" },
+  retries: { type: "string" },
+  timeout: { type: "string" },
+  "global-timeout": { type: "string" },
+  safe: { type: "boolean" },
+  trace: { type: "string" },
+  quiet: { type: "boolean" }
+};
+var TEST_HELP = `      --env <name>             environment (default: mock, for development)
+      --tag <tag>              only requests/flows with this tag (repeatable)
+      --grep <re> --grep-invert <re>   select by file or title
+      --list                   print what would run
+      --shard <i/n>            run the i-th of n equal parts
+      --bail <n>               stop after n failed flows
+      --retries <n>            run a failed flow again up to n times (a pass is "flaky")
+      --timeout <ms>           per request (default: the config's timeoutMs, else 30000; 0 waits)
+      --global-timeout <ms>    the whole run
+      --safe                   refuse requests that may change data (use against production)
+      --reporter <r[:path]>    list (default) | json | junit | github | ndjson (repeatable)
+      --trace <when>           on-failure (default) | always | off: the request and response of a step
+      --quiet                  only failures and the summary
+      --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
+      --notify <url>           POST a summary to a webhook when something fails`;
+var parseValue = (v) => {
+  try {
+    return JSON.parse(v);
+  } catch {
+    return v;
+  }
+};
+var kv = (list = []) => Object.fromEntries(
+  list.map((s) => {
+    const i = s.indexOf("=");
+    return [s.slice(0, i), parseValue(s.slice(i + 1))];
+  })
+);
+var number = (name, v) => {
+  if (v === void 0) return void 0;
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < 0) throw new UsageError(`--${name} takes a number, got "${v}"`);
+  return n;
+};
+function testOptions(values, patterns) {
+  if (values.trace && !["on-failure", "always", "off"].includes(values.trace))
+    throw new UsageError("--trace takes on-failure, always or off");
+  return {
+    patterns,
+    env: values.env,
+    inputs: kv(values.input),
+    vars: kv(values.var),
+    reporters: values.reporter ?? [],
+    secretsFile: values["secrets-file"],
+    tags: values.tag ?? [],
+    grep: values.grep,
+    grepInvert: values["grep-invert"],
+    list: values.list,
+    shard: values.shard,
+    bail: number("bail", values.bail),
+    retries: number("retries", values.retries),
+    timeoutMs: number("timeout", values.timeout),
+    globalTimeoutMs: number("global-timeout", values["global-timeout"]),
+    safe: values.safe,
+    trace: values.trace,
+    quiet: values.quiet,
+    locale: values.locale,
+    seed: values.seed ? Number(values.seed) : void 0,
+    notify: values.notify
+  };
+}
+
+// src/standalone.ts
+var HELP = (name) => `${name} [options]   run the tests built into this file
+
+${TEST_HELP}
+  --help                       this text
+
+Exit codes: 0 pass, 1 a test failed or errored, 2 could not run (secrets, config), 3 usage.
+There is no mock environment here: name a real one with --env. Secrets come from environment variables.`;
+async function main(data, argv = process.argv.slice(2)) {
+  fixCliVersion(data.specbook);
+  const name = `node ${basename(process.argv[1] ?? "tests.mjs")}`;
+  const options = { ...TEST_FLAGS, help: { type: "boolean", short: "h" } };
+  const parse = () => parseArgs({ args: argv, options, allowPositionals: true });
+  let parsed;
+  try {
+    parsed = parse();
+  } catch (e) {
+    console.error(`${e instanceof Error ? e.message : e}
+
+${HELP(name)}`);
+    return 3;
+  }
+  if (parsed.values.help) {
+    console.log(HELP(name));
+    return 0;
+  }
+  let o;
+  try {
+    o = testOptions(parsed.values, parsed.positionals);
+  } catch (e) {
+    if (!(e instanceof UsageError)) throw e;
+    console.error(e.message);
+    return 3;
+  }
+  const environments = environmentNames(data.config, Object.keys(data.environments));
+  const targets = data.modules.flatMap((m) => targetsOf(m.mod, m.file));
+  const example = async (op, exampleName) => {
+    const hit = data.examples[`${op.service}/${op.id}/${exampleName}`];
+    return hit ? { ...hit.doc, source: hit.source, dir: hit.dir } : void 0;
+  };
+  const readFile2 = async (path, dir) => {
+    const key = posix.normalize(posix.join(dir ?? "", path));
+    const b64 = data.files[key];
+    if (b64 === void 0) throw new Error(`File "${key}" is not in this bundle`);
+    return new File([Buffer.from(b64, "base64")], posix.basename(key));
+  };
+  return runTests(
+    {
+      command: name,
+      root: process.cwd(),
+      config: data.config,
+      targets,
+      environments,
+      readEnvironment: async (env) => ({
+        vars: data.environments[env] ?? {},
+        secrets: {},
+        shared: {}
+      }),
+      examples: { example, readFile: readFile2 },
+      loadFaker: async () => data.faker,
+      bundle: { sha: data.git?.sha, createdAt: data.createdAt },
+      git: {},
+      readSource: () => void 0,
+      hideLocations: true,
+      secretFiles: false
+    },
+    o
+  );
+}
+export {
+  main
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@specbook/cli",
-  "version": "0.2.0",
-  "description": "Specbook command line: init, add, generate, dev, build, run, check, secrets and preview.",
+  "version": "0.4.0",
+  "description": "Specbook command line: init, add, generate, dev, build, test, bundle, check, secrets and preview.",
   "keywords": [
     "specbook",
     "openapi",
@@ -32,16 +32,18 @@
   },
   "files": [
     "dist",
+    "agent-guide.md",
     "!**/*.test.*"
   ],
   "dependencies": {
     "@apidevtools/swagger-parser": "10.1.1",
     "@faker-js/faker": "9.3.0",
-    "@specbook/codegen": "0.2.0",
-    "@specbook/core": "0.2.0",
-    "@specbook/ui": "0.2.0",
-    "@specbook/vite": "0.2.0",
+    "@specbook/codegen": "0.4.0",
+    "@specbook/core": "0.4.0",
+    "@specbook/ui": "0.4.0",
+    "@specbook/vite": "0.4.0",
     "fast-glob": "3.3.2",
+    "rolldown": "1.2.13",
     "swagger2openapi": "7.0.8",
     "vite": "8.3.4",
     "vite-node": "6.0.0"