@kirrosh/zond 0.21.0 → 0.23.0

package/src/core/selectors/operation-filter.ts

@@ -0,0 +1,144 @@
+/**
+ * Unified operation filter (m-15 ARV-9).
+ *
+ * Parses `--include`/`--exclude` filter specs in a single grammar so
+ * `zond run`, `zond checks`, `zond probe`, and `zond generate` all
+ * accept the same `<selector>:<value>` strings without each command
+ * inventing its own flag set.
+ *
+ * Grammar:
+ *
+ *   <spec> := <selector> ":" <value>
+ *   <selector> := "path" | "method" | "tag" | "operation-id" | "operationId"
+ *   <value>:
+ *     path        — POSIX-style regex matched against `op.path`
+ *     method      — comma-separated HTTP methods, case-insensitive
+ *     tag         — comma-separated tag names, exact match (case-sensitive)
+ *     operation-id — POSIX-style regex matched against `op.operationId`
+ *
+ * Semantics:
+ *   - Multiple `--include` flags combine with OR (op passes if it
+ *     matches *any* include); when no include is given, every op is
+ *     considered included.
+ *   - `--exclude` always removes a match — combines with OR too.
+ *   - Excludes are evaluated *after* includes.
+ *
+ * Errors are returned in a `errors[]` array on the compile result so
+ * the CLI can surface a friendly multi-line message instead of a
+ * stack trace (AC #4).
+ */
+import type { EndpointInfo } from "../generator/types.ts";
+
+export type SelectorKind = "path" | "method" | "tag" | "operation-id";
+
+const SELECTOR_ALIASES: Record<string, SelectorKind> = {
+  path: "path",
+  method: "method",
+  tag: "tag",
+  "operation-id": "operation-id",
+  operationid: "operation-id",
+  operation_id: "operation-id",
+};
+
+export interface ParsedSelector {
+  kind: SelectorKind;
+  raw: string;
+  /** Regex form for `path` and `operation-id` selectors. */
+  pattern?: RegExp;
+  /** Lowercase token list for `method`/`tag` selectors. */
+  values?: string[];
+}
+
+export type ParseResult =
+  | { ok: true; selector: ParsedSelector }
+  | { ok: false; error: string };
+
+export function parseFilterSpec(spec: string): ParseResult {
+  const idx = spec.indexOf(":");
+  if (idx <= 0) {
+    return { ok: false, error: `Filter "${spec}": expected "<selector>:<value>" (e.g. path:/users/.*)` };
+  }
+  const head = spec.slice(0, idx).trim().toLowerCase();
+  const tail = spec.slice(idx + 1).trim();
+  if (tail.length === 0) {
+    return { ok: false, error: `Filter "${spec}": value is empty after "${head}:"` };
+  }
+  const kind = SELECTOR_ALIASES[head];
+  if (!kind) {
+    const known = Object.keys(SELECTOR_ALIASES).filter((k) => k === SELECTOR_ALIASES[k]).join(", ");
+    return { ok: false, error: `Filter "${spec}": unknown selector "${head}". Known: ${known}` };
+  }
+
+  if (kind === "path" || kind === "operation-id") {
+    let pattern: RegExp;
+    try {
+      pattern = new RegExp(tail);
+    } catch (err) {
+      return { ok: false, error: `Filter "${spec}": invalid regex — ${(err as Error).message}` };
+    }
+    return { ok: true, selector: { kind, raw: spec, pattern } };
+  }
+
+  // method / tag — comma-separated.
+  const values = tail.split(",").map((v) => v.trim()).filter(Boolean);
+  if (values.length === 0) {
+    return { ok: false, error: `Filter "${spec}": no values after "${head}:"` };
+  }
+  if (kind === "method") {
+    return { ok: true, selector: { kind, raw: spec, values: values.map((v) => v.toUpperCase()) } };
+  }
+  return { ok: true, selector: { kind, raw: spec, values } };
+}
+
+function selectorMatches(sel: ParsedSelector, op: EndpointInfo): boolean {
+  switch (sel.kind) {
+    case "path":
+      return sel.pattern!.test(op.path);
+    case "method":
+      return sel.values!.includes(op.method.toUpperCase());
+    case "tag":
+      return op.tags.some((t) => sel.values!.includes(t));
+    case "operation-id":
+      return op.operationId !== undefined && sel.pattern!.test(op.operationId);
+  }
+}
+
+export interface CompileFilterOptions {
+  includes?: string[];
+  excludes?: string[];
+}
+
+export interface CompiledFilter {
+  filter: (op: EndpointInfo) => boolean;
+  errors: string[];
+  /** Parsed selectors — handy for debug `--explain` output. */
+  parsed: { includes: ParsedSelector[]; excludes: ParsedSelector[] };
+}
+
+export function compileOperationFilter(opts: CompileFilterOptions = {}): CompiledFilter {
+  const errors: string[] = [];
+  const includes: ParsedSelector[] = [];
+  const excludes: ParsedSelector[] = [];
+  for (const raw of opts.includes ?? []) {
+    const r = parseFilterSpec(raw);
+    if (r.ok) includes.push(r.selector);
+    else errors.push(r.error);
+  }
+  for (const raw of opts.excludes ?? []) {
+    const r = parseFilterSpec(raw);
+    if (r.ok) excludes.push(r.selector);
+    else errors.push(r.error);
+  }
+  const filter = (op: EndpointInfo): boolean => {
+    if (includes.length > 0) {
+      const passInclude = includes.some((s) => selectorMatches(s, op));
+      if (!passInclude) return false;
+    }
+    for (const s of excludes) {
+      if (selectorMatches(s, op)) return false;
+    }
+    return true;
+  };
+  return { filter, errors, parsed: { includes, excludes } };
+}
+

package/src/core/setup-api.ts

@@ -1,8 +1,171 @@
-import { resolve, join } from "path";
-import { mkdirSync, writeFileSync, existsSync, readFileSync } from "fs";
+import { resolve, join, relative } from "path";
+import { mkdirSync, writeFileSync, existsSync, readFileSync, rmSync } from "fs";
 import { getDb } from "../db/schema.ts";
 import { createCollection, deleteCollection, findCollectionByNameOrId, normalizePath } from "../db/queries.ts";
-import { readOpenApiSpec, extractEndpoints } from "./generator/index.ts";
+import {
+  readOpenApiSpec,
+  extractEndpoints,
+  extractSecuritySchemes,
+  buildCatalog,
+  serializeCatalog,
+  buildApiResourceMap,
+  serializeApiResourceMap,
+  buildApiFixtureManifest,
+  serializeApiFixtureManifest,
+} from "./generator/index.ts";
+import { decycleSchema } from "./generator/schema-utils.ts";
+import { schemeVarName } from "./generator/suite-generator.ts";
+import type { SecuritySchemeInfo } from "./generator/types.ts";
+import { hashSpec } from "./meta/meta-store.ts";
+import { findWorkspaceRoot } from "./workspace/root.ts";
+import { recordGeneratedFiles, type RecordInput } from "./workspace/manifest.ts";
+import { CANONICAL_IDENTITY_KEYS } from "./identity/identity-file.ts";
+
+/** Filename of the dereferenced spec snapshot inside `apis/<name>/`. */
+export const SPEC_SNAPSHOT_FILENAME = "spec.json";
+
+interface WriteArtifactsParams {
+  /** Dereferenced OpenAPI document. */
+  doc: unknown;
+  /** Absolute path to apis/<name>/. */
+  baseDir: string;
+  /** Collection name (goes into the catalog header). */
+  apiName: string;
+  /** Resolved server URL or "". */
+  baseUrl: string;
+  /** Absolute workspace root, used to compute the relative specSource. */
+  workspaceRoot: string;
+  /** Caller label for manifest entries (defaults to "zond add api"). */
+  by?: string;
+}
+
+/**
+ * Snapshot the dereferenced spec into `apis/<name>/spec.json` and emit the
+ * three derived artifacts (`.api-catalog.yaml`, `.api-resources.yaml`,
+ * `.api-fixtures.yaml`). Pure side-effect; safe to call from `setupApi` at
+ * register time and from `refreshApi` for re-snapshot.
+ */
+export function writeArtifactsFromDoc(params: WriteArtifactsParams): void {
+  const { doc, baseDir, apiName, baseUrl, workspaceRoot, by = "zond add api" } = params;
+  const localSpecAbsPath = join(baseDir, SPEC_SNAPSHOT_FILENAME);
+  // Pass through decycleSchema first — large specs (Stripe, GitHub) contain
+  // mutually-recursive `$ref` chains that resolve to true object cycles after
+  // dereference, and raw JSON.stringify crashes on those with "cannot
+  // serialize cyclic structures" (ARV-145). decycleSchema collapses the
+  // second visit to `{ "x-circular": true }` (vendor-extension sentinel —
+  // NOT `$ref`, otherwise the parser tries to resolve "[Circular]" as a
+  // file path when re-reading spec.json, ARV-146) so the on-disk snapshot
+  // is self-contained, parser-safe JSON.
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(decycleSchema(doc), null, 2);
+  } catch (err) {
+    const m = (err as Error).message;
+    throw new Error(
+      `spec_serialize_failed: could not serialize dereferenced spec for '${apiName}' — ${m}. ` +
+      `This usually means the spec contains a structure decycleSchema could not collapse; please open an issue with the spec URL.`,
+    );
+  }
+  writeFileSync(localSpecAbsPath, serialized + "\n", "utf-8");
+
+  const endpoints = extractEndpoints(doc as any);
+  const securitySchemes = extractSecuritySchemes(doc as any);
+  // Hash the on-disk file bytes — this is what `zond doctor` re-hashes when
+  // checking artifact freshness (TASK-215). Both sides now read the decycled
+  // form: setup-api writes it here, doctor re-reads the same file.
+  const specHash = hashSpec(readFileSync(localSpecAbsPath, "utf-8"));
+  const localSpecRelPath = relative(workspaceRoot, localSpecAbsPath).replace(/\\/g, "/");
+
+  const catalog = buildCatalog({
+    endpoints,
+    securitySchemes,
+    specSource: localSpecRelPath,
+    specHash,
+    apiName,
+    apiVersion: (doc as any).info?.version,
+    baseUrl,
+  });
+  const catalogPath = join(baseDir, ".api-catalog.yaml");
+  writeFileSync(catalogPath, serializeCatalog(catalog), "utf-8");
+
+  const resources = buildApiResourceMap({ endpoints, specHash });
+  const resourcesPath = join(baseDir, ".api-resources.yaml");
+  writeFileSync(resourcesPath, serializeApiResourceMap(resources), "utf-8");
+
+  const fixtures = buildApiFixtureManifest({
+    endpoints,
+    securitySchemes,
+    baseUrl: baseUrl || undefined,
+    specHash,
+    resourceMap: resources,
+  });
+  const fixturesPath = join(baseDir, ".api-fixtures.yaml");
+  writeFileSync(fixturesPath, serializeApiFixtureManifest(fixtures), "utf-8");
+
+  // Record artifacts in .zond/manifest.json (TASK-156).
+  try {
+    const entries: RecordInput[] = [
+      { path: localSpecAbsPath, by, api: apiName, category: "spec" },
+      { path: catalogPath, by, api: apiName, category: "catalog" },
+      { path: resourcesPath, by, api: apiName, category: "resources" },
+      { path: fixturesPath, by, api: apiName, category: "fixtures" },
+    ];
+    recordGeneratedFiles(workspaceRoot, entries);
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Resolve a `collections.openapi_spec` value to a concrete file path the
+ * caller can read. Throws on a legacy / broken workspace so the user gets
+ * a single clear instruction instead of a downstream ENOENT.
+ *
+ * Resolution order:
+ *   1. URL (http/https) — return as-is.
+ *   2. Workspace-relative path (e.g. `apis/<name>/spec.json`) that exists.
+ *   3. Absolute filesystem path that exists. Treated as legacy: the spec
+ *      is outside the workspace and not snapshotted into `apis/<name>/`.
+ *      We let it through, but `assertLocalSpec` (used by run/report/doctor)
+ *      will reject it.
+ *   4. Otherwise — throw a "legacy / stale workspace" error pointing at
+ *      `zond refresh-api`.
+ */
+export function resolveCollectionSpec(specRef: string): string {
+  if (/^https?:\/\//i.test(specRef)) return specRef;
+  const root = findWorkspaceRoot().root;
+  const local = resolve(root, specRef);
+  if (existsSync(local)) return local;
+  if (specRef.startsWith("/") && existsSync(specRef)) return specRef;
+  throw new Error(
+    `Spec for this API is missing at ${local}` +
+    (specRef.startsWith("/") ? ` (DB recorded an external path: ${specRef})` : "") +
+    `. The workspace looks legacy or stale — run \`zond refresh-api <name> [--spec <path|url>]\` to re-snapshot.`,
+  );
+}
+
+/**
+ * Strict variant for code paths that must read the workspace-local
+ * snapshot (run/report/doctor). Returns the local absolute path or
+ * throws — never returns an external URL or path.
+ */
+export function assertLocalSpec(specRef: string, apiName: string): string {
+  if (/^https?:\/\//i.test(specRef)) {
+    throw new Error(
+      `API '${apiName}' has a remote spec recorded (${specRef}) but no local snapshot. ` +
+      `Run \`zond refresh-api ${apiName}\` to materialise apis/${apiName}/${SPEC_SNAPSHOT_FILENAME}.`,
+    );
+  }
+  const root = findWorkspaceRoot().root;
+  const local = resolve(root, specRef);
+  if (!existsSync(local)) {
+    throw new Error(
+      `Local spec missing for API '${apiName}' (expected ${local}). ` +
+      `Run \`zond refresh-api ${apiName}\` to regenerate it.`,
+    );
+  }
+  return local;
+}
 
 function toYaml(vars: Record<string, string>): string {
   const lines: string[] = [];
@@ -31,9 +194,32 @@ export interface SetupApiResult {
   baseUrl: string;
   specEndpoints: number;
   pathParams?: Record<string, string>;
+  /** Auth-related env-var names auto-seeded as `@secret:<name>` (TASK-209). */
+  authVars?: string[];
   warnings?: string[];
 }
 
+/**
+ * Walk the security schemes and derive the env-var names that
+ * `@readme/openapi-parser`-derived suites/probes will reference for auth
+ * tokens. Mirrors `getAuthHeaders` in src/core/probe/shared.ts:
+ *   - HTTP bearer/basic/empty-scheme → schemeVarName(...) (default "auth_token")
+ *   - apiKey in header named "Authorization" → schemeVarName(...)
+ *   - apiKey in header (other name) → "api_key"
+ */
+function deriveAuthVarNames(schemes: SecuritySchemeInfo[]): string[] {
+  const vars = new Set<string>();
+  for (const s of schemes) {
+    if (s.type === "http" && (s.scheme === "bearer" || s.scheme === "basic" || !s.scheme)) {
+      vars.add(schemeVarName(s, schemes));
+    } else if (s.type === "apiKey" && s.in === "header" && s.apiKeyName) {
+      if (s.apiKeyName === "Authorization") vars.add(schemeVarName(s, schemes));
+      else vars.add("api_key");
+    }
+  }
+  return [...vars];
+}
+
 export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult> {
   const { spec, dbPath } = options;
 
@@ -46,11 +232,47 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
   const pathParams = new Map<string, string>();
   const warnings: string[] = [];
   let specTitle: string | undefined;
+  // The dereferenced doc is captured here so we can copy it into the
+  // workspace after the target dir is computed (below). We snapshot the
+  // *dereferenced* form so all consumers (probe-*, generate, describe) read
+  // a self-contained file — no external $ref resolution at runtime.
+  let dereferencedDoc: unknown = null;
+  let authVarNames: string[] = [];
   if (spec) {
     const doc = await readOpenApiSpec(spec, { insecure: options.insecure });
+    // Validate the document looks like OpenAPI/Swagger before we snapshot it.
+    // dereference() happily round-trips arbitrary JSON (e.g. a marketing-site
+    // landing payload), so without this guard `zond add api foo --spec
+    // https://example.com` silently registers a 0-endpoint API.
+    const docAny = doc as any;
+    const hasOpenApiField = typeof docAny?.openapi === "string";
+    const hasSwaggerField = typeof docAny?.swagger === "string";
+    if (!hasOpenApiField && !hasSwaggerField) {
+      throw new Error(
+        `Spec at ${spec} is not an OpenAPI/Swagger document — missing top-level 'openapi' (3.x) or 'swagger' (2.x) field. Check the URL points to the JSON spec, not the API root.`,
+      );
+    }
+    dereferencedDoc = doc;
     openapiSpec = spec;
     if ((doc as any).servers?.[0]?.url) {
       baseUrl = (doc as any).servers[0].url;
+      // Resolve OpenAPI server variables (e.g. {region}) using their declared defaults.
+      // Without this, the raw placeholder ends up in .env.yaml and causes cryptic TLS
+      // errors because the hostname literally contains "{region}".
+      const serverVars = (doc as any).servers[0].variables as
+        Record<string, { default?: string }> | undefined;
+      if (serverVars && baseUrl.includes("{")) {
+        baseUrl = baseUrl.replace(/\{([^}]+)\}/g, (_: string, name: string) =>
+          serverVars[name]?.default ?? `{${name}}`
+        );
+      }
+      // Warn if any placeholder remains unresolved (spec didn't provide a default).
+      const unresolved = [...baseUrl.matchAll(/\{([^}]+)\}/g)].map(m => m[1]);
+      if (unresolved.length > 0) {
+        warnings.push(
+          `base_url contains unresolved server variable${unresolved.length === 1 ? "" : "s"}: ${unresolved.map(v => `{${v}}`).join(", ")}. Edit .env.yaml and replace with a concrete value.`,
+        );
+      }
     }
     if (baseUrl && !baseUrl.startsWith("http://") && !baseUrl.startsWith("https://")) {
       warnings.push(`Spec server URL "${baseUrl}" is relative — requests will fail without a host. Override with envVars: {"base_url": "https://your-host${baseUrl}"}`);
@@ -58,16 +280,28 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     specTitle = (doc as any).info?.title;
     const endpoints = extractEndpoints(doc);
     endpointCount = endpoints.length;
+    authVarNames = deriveAuthVarNames(extractSecuritySchemes(doc));
 
-    // Collect unique path parameters with default values
+    if (endpointCount === 0) {
+      const hasPaths = docAny?.paths && typeof docAny.paths === "object" && Object.keys(docAny.paths).length > 0;
+      warnings.push(
+        hasPaths
+          ? `Spec declares paths but no operations were extracted — every method may be filtered out (deprecated, unsupported method, etc.). Verify with \`zond catalog --api <name>\`.`
+          : `Spec contains 0 endpoints — 'paths' field is empty or missing. generate/probe/checks will produce nothing until the spec is fixed or replaced.`,
+      );
+    }
+
+    // Collect unique path parameters. The default is empty string so that
+    // generated `skip_if: "{{<id>}} =="` checks auto-skip until the user
+    // fills the value in .env.yaml (TASK-210). Spec-provided examples are
+    // kept verbatim so they are still useful as concrete fixtures.
     for (const ep of endpoints) {
       for (const param of (ep.parameters ?? []).filter(p => p.in === "path")) {
         if (pathParams.has(param.name)) continue;
         const schema = param.schema as any;
         if (param.example !== undefined) pathParams.set(param.name, String(param.example));
         else if (schema?.example !== undefined) pathParams.set(param.name, String(schema.example));
-        else if (schema?.type === "integer" || schema?.type === "number") pathParams.set(param.name, "1");
-        else pathParams.set(param.name, "example");
+        else pathParams.set(param.name, "");
       }
     }
   }
@@ -90,12 +324,68 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
 
   // Sanitize name for directory use
   const dirName = name.replace(/[^a-zA-Z0-9_\-\.]/g, "-").toLowerCase();
-  const baseDir = resolve(options.dir ?? `./apis/${dirName}/`);
+  const baseDir = options.dir
+    ? resolve(options.dir)
+    : resolve(findWorkspaceRoot().root, `apis/${dirName}/`);
   const testPath = join(baseDir, "tests");
 
+  // Track whether we created baseDir from scratch so we can clean it up on
+  // failure — without this, a crash mid-setup (e.g. JSON.stringify on a
+  // cyclic spec, ARV-145) leaves apis/<slug>/tests/ behind and confuses the
+  // next `zond add api` invocation.
+  const baseDirPreExisted = existsSync(baseDir);
+
   // Create directories
   mkdirSync(testPath, { recursive: true });
 
+  try {
+    return await finalizeSetup({
+      name,
+      baseDir,
+      testPath,
+      baseUrl,
+      pathParams,
+      authVarNames,
+      envVarsOverride: options.envVars,
+      spec,
+      dereferencedDoc,
+      openapiSpec,
+      endpointCount,
+      warnings,
+    });
+  } catch (err) {
+    // Roll back partial filesystem state (apis/<slug>/tests/, spec.json, etc.)
+    // when we created the dir from scratch. Without this, the next
+    // `zond add api <same-name>` would still find a stale dir and demand
+    // --force, even though no collection was actually registered. ARV-145.
+    if (!baseDirPreExisted) {
+      try { rmSync(baseDir, { recursive: true, force: true }); } catch { /* best-effort */ }
+    }
+    throw err;
+  }
+}
+
+interface FinalizeSetupParams {
+  name: string;
+  baseDir: string;
+  testPath: string;
+  baseUrl: string;
+  pathParams: Map<string, string>;
+  authVarNames: string[];
+  envVarsOverride?: Record<string, string>;
+  spec?: string;
+  dereferencedDoc: unknown;
+  openapiSpec: string | null;
+  endpointCount: number;
+  warnings: string[];
+}
+
+async function finalizeSetup(p: FinalizeSetupParams): Promise<SetupApiResult> {
+  const {
+    name, baseDir, testPath, baseUrl, pathParams, authVarNames,
+    envVarsOverride, spec, dereferencedDoc, openapiSpec, endpointCount, warnings,
+  } = p;
+
   // Build environment variables
   const envVars: Record<string, string> = {};
   if (baseUrl) envVars.base_url = baseUrl;
@@ -103,8 +393,33 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
   for (const [k, v] of pathParams) {
     if (!(k in envVars)) envVars[k] = v;
   }
-  if (options.envVars) {
-    Object.assign(envVars, options.envVars);
+  // Auto-wire auth env-vars to .secrets.yaml so generated suites and probes
+  // resolve `{{auth_token}}` (etc.) without manual editing of .env.yaml
+  // (TASK-209). The matching `<var>: ""` placeholder is seeded into
+  // .secrets.yaml below — the user only fills the secret value.
+  for (const v of authVarNames) {
+    if (!(v in envVars)) envVars[v] = `@secret:${v}`;
+  }
+  // ARV-201 (R10/F2): when the spec declares no `components.securitySchemes`
+  // (GitHub publishes its OpenAPI this way), `deriveAuthVarNames` returns []
+  // and the loop above is a no-op — yet `zond request --api <name>` knows
+  // to attach `Authorization: Bearer <auth_token>` if the env carries an
+  // `auth_token`. Mirror the `.secrets.yaml` fallback (which already seeds
+  // `auth_token: ""` when authVarNames is empty) into `.env.yaml` so users
+  // do not need to hand-add `auth_token: "@secret:auth_token"` just to
+  // surface the Bearer header on bare specs.
+  if (authVarNames.length === 0 && !("auth_token" in envVars)) {
+    envVars.auth_token = "@secret:auth_token";
+  }
+  if (envVarsOverride) {
+    Object.assign(envVars, envVarsOverride);
+  }
+
+  // Spec-less registration is allowed, but we need a base_url from somewhere
+  // (server URL extracted from the spec, or envVars.base_url passed in by the
+  // caller). Without it the API is useless — `zond run` can't resolve {{base_url}}.
+  if (!spec && !envVars.base_url) {
+    throw new Error("setupApi requires --spec or envVars.base_url to register an API");
   }
 
   // Write .env.yaml in base_dir
@@ -113,26 +428,112 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     writeFileSync(envFilePath, toYaml(envVars) + "\n", "utf-8");
   }
 
-  // Create/update .gitignore to exclude env files
+  // Create/update .gitignore to exclude env / secret files
   const gitignorePath = join(baseDir, ".gitignore");
-  const gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+  let gitignoreContent = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+  let gitignoreDirty = false;
   if (!gitignoreContent.includes(".env*.yaml")) {
-    writeFileSync(
-      gitignorePath,
-      gitignoreContent + (gitignoreContent.endsWith("\n") || !gitignoreContent ? "" : "\n") + ".env*.yaml\n",
-      "utf-8",
-    );
+    gitignoreContent +=
+      (gitignoreContent.endsWith("\n") || !gitignoreContent ? "" : "\n") + ".env*.yaml\n";
+    gitignoreDirty = true;
+  }
+  // TASK-170 (m-10): keep `.secrets.yaml` git-invisible. Older `.env*.yaml`
+  // pattern matched it accidentally; pin it explicitly so a future glob
+  // narrowing can't regress.
+  if (!gitignoreContent.includes(".secrets.yaml")) {
+    gitignoreContent += ".secrets.yaml\n";
+    gitignoreDirty = true;
+  }
+  // TASK-174 (m-10): identity values are not secrets but they identify
+  // the user's account; keep them out of git too.
+  if (!gitignoreContent.includes(".identity.yaml")) {
+    gitignoreContent += ".identity.yaml\n";
+    gitignoreDirty = true;
+  }
+  if (gitignoreDirty) {
+    writeFileSync(gitignorePath, gitignoreContent, "utf-8");
+  }
+
+  // Seed `.secrets.yaml` placeholder once. The file lives gitignored
+  // alongside `.env.yaml`; values placed here are auto-registered with
+  // the SecretRegistry on load and never appear in artifacts.
+  const secretsPath = join(baseDir, ".secrets.yaml");
+  if (!existsSync(secretsPath)) {
+    const seedKeys = authVarNames.length > 0 ? authVarNames : ["auth_token"];
+    const lines = [
+      "# .secrets.yaml — gitignored, holds raw secret values.",
+      "# Reference these in .env.yaml as @secret:<key>.",
+      "# Values here are auto-registered for redaction in DB writes,",
+      "# HTML/JSON/JUnit reports, case-studies, and probe digests.",
+    ];
+    for (const k of seedKeys) lines.push(`${k}: ""  # required for live probes`);
+    lines.push("");
+    writeFileSync(secretsPath, lines.join("\n"), "utf-8");
+  }
+
+  // TASK-174 (m-10): seed `.identity.yaml` with placeholders for any
+  // canonical identity-keys that appear as path-params in the spec. The
+  // file is gitignored — values are visible locally for triage and
+  // hidden from outbound shares only when --redact-identity is set.
+  const identityKeys = [...pathParams.keys()].filter((k) =>
+    CANONICAL_IDENTITY_KEYS.has(k),
+  );
+  if (identityKeys.length > 0) {
+    const identityPath = join(baseDir, ".identity.yaml");
+    if (!existsSync(identityPath)) {
+      const lines = [
+        "# .identity.yaml — gitignored, holds non-secret-but-identifying values.",
+        "# Reference these in .env.yaml as @identity:<key>.",
+        "# Values are visible locally and in case-study drafts; pass",
+        "# --redact-identity (TASK-173) to swap them for placeholders when",
+        "# sharing reports outbound.",
+      ];
+      for (const k of identityKeys.sort()) {
+        lines.push(`${k}: ""  # fill with your ${k}`);
+      }
+      lines.push("");
+      writeFileSync(identityPath, lines.join("\n"), "utf-8");
+    }
+  }
+
+  const workspaceRoot = findWorkspaceRoot().root;
+
+  // Snapshot the dereferenced spec into apis/<name>/spec.json so all later
+  // commands (catalog, describe, generate, probe-*) read a self-contained
+  // local file. The spec lives inside the workspace and is git-trackable;
+  // an external --spec path is only consulted at register/refresh time.
+  let localSpecAbsPath: string | null = null;
+  if (dereferencedDoc) {
+    localSpecAbsPath = join(baseDir, SPEC_SNAPSHOT_FILENAME);
+    writeArtifactsFromDoc({
+      doc: dereferencedDoc,
+      baseDir,
+      apiName: name,
+      baseUrl,
+      workspaceRoot,
+    });
   }
 
   const normalizedTestPath = normalizePath(testPath);
   const normalizedBaseDir = normalizePath(baseDir);
 
+  // Persist the workspace-relative path to the local snapshot in
+  // collections.openapi_spec so we don't rely on the user's external path
+  // sticking around. Falls back to the external path only when the snapshot
+  // could not be created (no spec given to setupApi).
+  // Don't run normalizePath on the relative form — it calls resolve() and
+  // would re-absolutize the path. Posix-style separators are enough for
+  // SQLite + Windows compat.
+  const dbSpecPath = localSpecAbsPath
+    ? relative(workspaceRoot, localSpecAbsPath).replace(/\\/g, "/")
+    : (openapiSpec ?? undefined);
+
   // Create collection in DB
   const collectionId = createCollection({
     name,
     base_dir: normalizedBaseDir,
     test_path: normalizedTestPath,
-    openapi_spec: openapiSpec ?? undefined,
+    openapi_spec: dbSpecPath,
   });
 
   const pathParamsObj = pathParams.size > 0 ? Object.fromEntries(pathParams) : undefined;
@@ -145,6 +546,7 @@ export async function setupApi(options: SetupApiOptions): Promise<SetupApiResult
     baseUrl,
     specEndpoints: endpointCount,
     ...(pathParamsObj ? { pathParams: pathParamsObj } : {}),
+    ...(authVarNames.length > 0 ? { authVars: authVarNames } : {}),
     ...(warnings.length > 0 ? { warnings } : {}),
   };
 }