@kirrosh/zond 0.21.0 → 0.23.0

package/src/cli/commands/init/bootstrap.ts

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { upsertAgentsBlock, type AgentsBlockResult } from "./agents-md.ts";
+import {
+  detectStaleSkills,
+  pruneStaleSkills,
+  upsertSkills,
+  type SkillResult,
+  type StaleSkill,
+} from "./skills.ts";
+import zondConfigTemplate from "./templates/zond-config.yml" with { type: "text" };
+
+export interface BootstrapOptions {
+  cwd?: string;
+  /** Whether to write/upsert AGENTS.md. Defaults to true. */
+  writeAgents?: boolean;
+  /** Whether to write Claude Code skills under .claude/skills/. Defaults to true. */
+  writeSkills?: boolean;
+  /** Remove legacy skill dirs (zond-base, zond-scenarios, …) instead of just warning. */
+  pruneStaleSkills?: boolean;
+  /** Override $HOME — used by tests and intentional overrides. */
+  home?: string;
+  dryRun?: boolean;
+}
+
+export interface BootstrapResult {
+  cwd: string;
+  configPath: string;
+  configAction: "created" | "noop";
+  apisDir: string;
+  apisAction: "created" | "noop";
+  agents: AgentsBlockResult | null;
+  skills: SkillResult[];
+  /** Legacy skill dirs that exist on disk but are no longer in `SKILLS`. */
+  staleSkills: StaleSkill[];
+  /** Subset of `staleSkills` that were actually removed (empty unless `pruneStaleSkills`). */
+  prunedSkills: StaleSkill[];
+  warnings: string[];
+}
+
+/**
+ * Idempotent workspace bootstrap. Creates `zond.config.yml`, `apis/`, and
+ * (unless `writeAgents` is false) `AGENTS.md`.
+ */
+export function bootstrapWorkspace(opts: BootstrapOptions = {}): BootstrapResult {
+  const cwd = resolve(opts.cwd ?? process.cwd());
+  const warnings: string[] = [];
+  const writeAgents = opts.writeAgents ?? true;
+  const writeSkills = opts.writeSkills ?? true;
+
+  // 1. zond.config.yml
+  const configPath = join(cwd, "zond.config.yml");
+  let configAction: "created" | "noop" = "noop";
+  if (!existsSync(configPath)) {
+    if (!opts.dryRun) writeFileSync(configPath, zondConfigTemplate, "utf-8");
+    configAction = "created";
+  }
+
+  // 2. apis/
+  const apisDir = join(cwd, "apis");
+  let apisAction: "created" | "noop" = "noop";
+  if (!existsSync(apisDir)) {
+    if (!opts.dryRun) mkdirSync(apisDir, { recursive: true });
+    apisAction = "created";
+  }
+
+  // 3. AGENTS.md
+  let agents: AgentsBlockResult | null = null;
+  if (writeAgents) {
+    if (!opts.dryRun) {
+      agents = upsertAgentsBlock(cwd);
+    } else {
+      agents = { path: join(cwd, "AGENTS.md"), action: existsSync(join(cwd, "AGENTS.md")) ? "updated" : "created" };
+    }
+  }
+
+  // 4. .claude/skills/zond-*/SKILL.md
+  const skills: SkillResult[] = writeSkills ? upsertSkills(cwd, { dryRun: opts.dryRun }) : [];
+
+  // 5. Detect (and optionally prune) legacy skill dirs left over from
+  // retired templates. User-authored skill dirs are NOT touched —
+  // only names in `LEGACY_SKILL_NAMES` are considered.
+  const staleSkills = writeSkills ? detectStaleSkills(cwd) : [];
+  let prunedSkills: StaleSkill[] = [];
+  if (writeSkills && opts.pruneStaleSkills && staleSkills.length > 0) {
+    prunedSkills = pruneStaleSkills(cwd, { dryRun: opts.dryRun });
+  } else if (staleSkills.length > 0) {
+    for (const { name } of staleSkills) {
+      warnings.push(
+        `stale skill detected: .claude/skills/${name}/ — re-run with --prune-stale-skills to remove`,
+      );
+    }
+  }
+
+  return {
+    cwd,
+    configPath,
+    configAction,
+    apisDir,
+    apisAction,
+    agents,
+    skills,
+    staleSkills,
+    prunedSkills,
+    warnings,
+  };
+}

package/src/cli/commands/init/index.ts

@@ -0,0 +1,244 @@
+import { existsSync, readdirSync } from "node:fs";
+import { setupApi, type SetupApiResult } from "../../../core/setup-api.ts";
+import { printError, printSuccess } from "../../output.ts";
+import { jsonOk, jsonError, printJson } from "../../json-envelope.ts";
+import { bootstrapWorkspace, type BootstrapResult } from "./bootstrap.ts";
+
+export interface InitOptions {
+  // register-an-API options (existing)
+  name?: string;
+  spec?: string;
+  baseUrl?: string;
+  dir?: string;
+  force?: boolean;
+  insecure?: boolean;
+  dbPath?: string;
+  json?: boolean;
+
+  // workspace bootstrap (new)
+  workspace?: boolean;
+  withSpec?: string;
+  /** Skip writing AGENTS.md. */
+  noAgents?: boolean;
+  /** Skip writing Claude Code skills under .claude/skills/. */
+  noSkills?: boolean;
+  /** Remove legacy skill dirs (zond-base, zond-scenarios, …) — by default a warning is printed. */
+  pruneStaleSkills?: boolean;
+  /** Override cwd for bootstrap (used by tests; CLI always uses process.cwd()). */
+  cwd?: string;
+  /** Override $HOME for MCP install (used by tests). */
+  home?: string;
+}
+
+type InitMode = "register" | "workspace" | "bootstrap+register";
+
+function resolveMode(options: InitOptions): InitMode {
+  if (options.spec) return "register";
+  if (options.withSpec) return "bootstrap+register";
+  return "workspace";
+}
+
+export async function initCommand(options: InitOptions): Promise<number> {
+  // Reject conflicting combos
+  if (options.spec && options.workspace) {
+    const msg = "Cannot use --spec and --workspace together. Use --with-spec to bootstrap and register in one step.";
+    if (options.json) printJson(jsonError("init", [msg]));
+    else printError(msg);
+    return 2;
+  }
+
+  const mode = resolveMode(options);
+  const writeAgents = !options.noAgents;
+  const writeSkills = !options.noSkills;
+
+  try {
+    if (mode === "register") {
+      const result = await registerApi(options);
+      printRegisterResult(options, result);
+      return 0;
+    }
+
+    const bootstrap = bootstrapWorkspace({
+      writeAgents,
+      writeSkills,
+      pruneStaleSkills: options.pruneStaleSkills,
+      cwd: options.cwd,
+      home: options.home,
+    });
+    let register: SetupApiResult | null = null;
+
+    if (mode === "bootstrap+register") {
+      register = await registerApi({ ...options, spec: options.withSpec });
+    }
+
+    if (options.json) {
+      const data: Record<string, unknown> = {
+        mode,
+        configPath: bootstrap.configPath,
+        configAction: bootstrap.configAction,
+        apisDir: bootstrap.apisDir,
+        apisAction: bootstrap.apisAction,
+        agentsPath: bootstrap.agents?.path ?? null,
+        agentsAction: bootstrap.agents?.action ?? null,
+        skills: bootstrap.skills.map((s) => ({ name: s.name, path: s.path, action: s.action })),
+        staleSkills: bootstrap.staleSkills.map((s) => ({ name: s.name, path: s.path })),
+        prunedSkills: bootstrap.prunedSkills.map((s) => ({ name: s.name, path: s.path })),
+      };
+      if (register) {
+        data.collectionId = register.collectionId;
+        data.baseDir = register.baseDir;
+        data.testPath = register.testPath;
+        data.endpoints = register.specEndpoints;
+      }
+      printJson(jsonOk("init", data, [...bootstrap.warnings, ...(register?.warnings ?? [])]));
+    } else {
+      printBootstrapResult(bootstrap, writeAgents);
+      if (register) printRegisterResult(options, register);
+    }
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (options.json) printJson(jsonError("init", [message]));
+    else printError(message);
+    return 2;
+  }
+}
+
+async function registerApi(options: InitOptions): Promise<SetupApiResult> {
+  const envVars: Record<string, string> = {};
+  if (options.baseUrl) envVars.base_url = options.baseUrl;
+
+  return await setupApi({
+    name: options.name,
+    spec: options.spec ?? options.withSpec,
+    dir: options.dir,
+    envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
+    dbPath: options.dbPath,
+    force: options.force,
+    insecure: options.insecure,
+  });
+}
+
+function printRegisterResult(options: InitOptions, result: SetupApiResult): void {
+  if (options.json) {
+    // Only used by the legacy "register"-only path
+    printJson(jsonOk("init", {
+      mode: "register",
+      collectionId: result.collectionId,
+      baseDir: result.baseDir,
+      testPath: result.testPath,
+      endpoints: result.specEndpoints,
+    }, result.warnings));
+    return;
+  }
+  printSuccess(`Created API '${options.name ?? "api"}' at ${result.baseDir} (${result.specEndpoints} endpoints)`);
+  if (result.warnings) {
+    for (const w of result.warnings) process.stderr.write(`Warning: ${w}\n`);
+  }
+}
+
+function printBootstrapResult(b: BootstrapResult, writeAgents: boolean): void {
+  const lines: string[] = [];
+  lines.push(`  ${verb(b.configAction)} zond.config.yml`);
+  lines.push(`  ${verb(b.apisAction)} apis/`);
+  if (b.agents) lines.push(`  ${verb(b.agents.action)} AGENTS.md`);
+  for (const s of b.skills) {
+    lines.push(`  ${verb(s.action)} .claude/skills/${s.name}/SKILL.md`);
+  }
+  for (const s of b.prunedSkills) {
+    lines.push(`  Removed .claude/skills/${s.name}/ (stale)`);
+  }
+  for (const w of b.warnings) {
+    process.stderr.write(`Warning: ${w}\n`);
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+  if (!writeAgents) {
+    printSuccess("Workspace ready. Run `zond init --spec <path>` to register your first API.");
+  } else {
+    printSuccess("Workspace ready. See AGENTS.md for the CLI workflow.");
+  }
+  const apiNames = listExistingApis(b.cwd);
+  if (apiNames.length === 0) {
+    process.stderr.write(
+      `\nNext steps:\n` +
+      `  1. zond add api <name> --spec <path|url>   # register API → builds .api-fixtures.yaml (manifest)\n` +
+      `  2. zond doctor --api <name>                 # gap report: which vars are UNSET in .env.yaml\n` +
+      `  3. zond prepare-fixtures --api <name> --apply [--seed]   # fill .env.yaml values\n` +
+      `\nNote: zond init only refreshes workspace files (skills, AGENTS.md, zond.config.yml).\n` +
+      `      It does NOT touch fixtures or .env.yaml — that's the doctor/prepare-fixtures loop above.\n`
+    );
+  } else {
+    const sample = apiNames[0]!;
+    process.stderr.write(
+      `\nFixtures untouched. zond init only refreshes skills/AGENTS.md/zond.config.yml.\n` +
+      `Verify env state with:\n` +
+      `  zond doctor --api ${sample} --missing-only   # show UNSET vars + blocked endpoints\n` +
+      `  zond prepare-fixtures --api ${sample} --apply [--seed]   # discover/seed values\n`
+    );
+  }
+}
+
+function listExistingApis(cwd: string): string[] {
+  try {
+    const apisDir = `${cwd}/apis`;
+    if (!existsSync(apisDir)) return [];
+    return readdirSync(apisDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && existsSync(`${apisDir}/${d.name}/spec.json`))
+      .map((d) => d.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+function verb(action: "created" | "updated" | "noop"): string {
+  return action === "created" ? "Created" : action === "updated" ? "Updated" : "Up-to-date:";
+}
+
+import type { Command } from "commander";
+import { globalJson } from "../../resolve.ts";
+
+export function registerInit(program: Command): void {
+  program
+    .command("init [spec]")
+    .description("Bootstrap a workspace, or register an API when --spec is given")
+    .option("--name <name>", "API name (auto-detected from spec title if omitted)")
+    .option("--spec <path>", "Path to OpenAPI spec file (registers a single API)")
+    .option("--base-url <url>", "Override base URL")
+    .option("--dir <path>", "Target directory")
+    .option("--force", "Overwrite existing API collection")
+    .option("--insecure", "Skip TLS verification when fetching the spec")
+    .option("--db <path>", "Path to SQLite database file")
+    .option("--workspace", "Bootstrap a zond workspace (zond.config.yml, apis/, AGENTS.md)")
+    .option("--with-spec <path>", "Bootstrap workspace AND register first API from spec")
+    .option("--no-agents-md", "Skip writing AGENTS.md when bootstrapping")
+    .option("--no-skills", "Skip writing Claude Code skills under .claude/skills/")
+    .option(
+      "--prune-stale-skills",
+      "Remove .claude/skills/ dirs for retired template names (zond-base, zond-scenarios)",
+    )
+    .action(async (specPos: string | undefined, opts, cmd: Command) => {
+      const spec = opts.spec ?? specPos;
+      const json = globalJson(cmd);
+      if ((spec || opts.withSpec) && !json) {
+        process.stderr.write(
+          `Warning: 'zond init --spec' / '--with-spec' is deprecated. Use \`zond add api <name> --spec <path>\` (run \`zond init\` separately to bootstrap the workspace).\n`,
+        );
+      }
+      process.exitCode = await initCommand({
+        name: opts.name,
+        spec,
+        baseUrl: opts.baseUrl,
+        dir: opts.dir,
+        force: opts.force === true,
+        insecure: opts.insecure === true,
+        dbPath: opts.db,
+        workspace: opts.workspace === true,
+        withSpec: opts.withSpec,
+        noAgents: opts.agentsMd === false,
+        noSkills: opts.skills === false,
+        pruneStaleSkills: opts.pruneStaleSkills === true,
+        json,
+      });
+    });
+}

package/src/cli/commands/init/skills.ts

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import zondSkill from "./templates/skills/zond.md" with { type: "text" };
+import checksSkill from "./templates/skills/zond-checks.md" with { type: "text" };
+import triageSkill from "./templates/skills/zond-triage.md" with { type: "text" };
+
+export interface SkillResult {
+  name: string;
+  path: string;
+  action: "created" | "updated" | "noop";
+}
+
+interface SkillTemplate {
+  name: string;
+  body: string;
+}
+
+const SKILLS: SkillTemplate[] = [
+  // Primary skill: artifact model + iron rules + full workflow
+  // (init → fixtures → annotate → generate → run → stateful checks →
+  // probes → coverage → share) + single-flow scenario authoring.
+  { name: "zond", body: zondSkill },
+  // Depth-check reference: conformance + security + m-20 stateful
+  // (cross_call_references, idempotency_replay, pagination_invariants,
+  // lifecycle_transitions) with per-aspect annotate flow.
+  { name: "zond-checks", body: checksSkill },
+  // Read-only triage of a finished run / probe artifact.
+  { name: "zond-triage", body: triageSkill },
+];
+
+/**
+ * Names previously emitted by `upsertSkills` but no longer in `SKILLS`.
+ * Detected as stale by `detectStaleSkills` and removed by
+ * `pruneStaleSkills` (only when the user opts in via `--prune-stale-skills`).
+ *
+ * Append a name here whenever a skill template is retired. User-authored
+ * skills (any name NOT in this list) are never touched.
+ */
+const LEGACY_SKILL_NAMES: readonly string[] = [
+  "zond-base",       // retired by skills-consolidation refactor (folded into zond)
+  "zond-scenarios",  // retired by skills-consolidation refactor (folded into zond)
+] as const;
+
+export interface StaleSkill {
+  name: string;
+  path: string;
+}
+
+/**
+ * Returns directories under `<cwd>/.claude/skills/` whose name is in
+ * `LEGACY_SKILL_NAMES`. User-authored skill directories (any other
+ * name) are intentionally ignored.
+ */
+export function detectStaleSkills(cwd: string): StaleSkill[] {
+  const out: StaleSkill[] = [];
+  for (const name of LEGACY_SKILL_NAMES) {
+    const path = join(cwd, ".claude", "skills", name);
+    if (existsSync(path)) out.push({ name, path });
+  }
+  return out;
+}
+
+/**
+ * Recursively removes the directories returned by `detectStaleSkills`.
+ * Returns the list of names that were actually removed.
+ */
+export function pruneStaleSkills(cwd: string, opts: { dryRun?: boolean } = {}): StaleSkill[] {
+  const stale = detectStaleSkills(cwd);
+  if (!opts.dryRun) {
+    for (const { path } of stale) rmSync(path, { recursive: true, force: true });
+  }
+  return stale;
+}
+
+/**
+ * Idempotently writes Claude Code skills into `<cwd>/.claude/skills/<name>/SKILL.md`.
+ * Body is identical to the in-binary template — overwrites on drift, noop on match.
+ */
+export function upsertSkills(cwd: string, opts: { dryRun?: boolean } = {}): SkillResult[] {
+  return SKILLS.map(({ name, body }) => {
+    const path = join(cwd, ".claude", "skills", name, "SKILL.md");
+    const desired = body.endsWith("\n") ? body : body + "\n";
+
+    if (!existsSync(path)) {
+      if (!opts.dryRun) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, desired, "utf-8");
+      }
+      return { name, path, action: "created" };
+    }
+
+    const current = readFileSync(path, "utf-8");
+    if (current === desired) return { name, path, action: "noop" };
+    if (!opts.dryRun) writeFileSync(path, desired, "utf-8");
+    return { name, path, action: "updated" };
+  });
+}

package/src/cli/commands/init/templates/agents.md

@@ -0,0 +1,77 @@
+## API testing with zond
+
+This workspace uses [zond](https://github.com/kirrosh/zond) for API testing — CLI
+only, no MCP server in this workspace.
+
+### Skills
+
+- **`.claude/skills/zond/SKILL.md` (primary)** — artifact model + iron
+  rules + full workflow: fixtures → annotate → generate → smoke → CRUD
+  → stateful checks → probes → coverage → report, plus single-flow
+  scenario authoring. Loads on workspace touch and on intent ("audit
+  this API", "find bugs", "write a test for X flow").
+- **`.claude/skills/zond-checks/SKILL.md`** — depth-check reference:
+  conformance + security + m-20 stateful invariants
+  (cross_call_references, idempotency_replay, pagination_invariants,
+  lifecycle_transitions) and the `zond api annotate dump+apply` flow.
+- **`.claude/skills/zond-triage/SKILL.md`** — read-only triage of a
+  finished run / probe artifact. Routes by `recommended_action` enum.
+
+Both skills work off the per-API artifacts written by `zond add api`:
+
+```
+apis/<name>/
+  spec.json              # dereferenced OpenAPI (machine source — only generators read it)
+  .api-catalog.yaml      # endpoint index (cheap to read, agent-friendly)
+  .api-resources.yaml    # CRUD chains, FK deps, ETag/soft-delete flags
+  .api-fixtures.yaml     # MANIFEST: required {{vars}} (read-only, auto-generated)
+  .env.yaml              # VALUES: variable values (user-edited; auto-gitignored)
+  tests/  scenarios/  probes/
+```
+
+`.api-fixtures.yaml` is the **manifest** (single source of truth for the
+list of vars an API needs) and `.env.yaml` holds their **values**. Don't
+add a key to `.env.yaml` that's not in the manifest — it'll be warned and
+ignored. A missing entry in the manifest is a generator/manifest bug, not
+an env fix.
+
+### Setup flow
+
+```bash
+zond init                                              # bootstrap workspace (no fixture changes)
+zond add api <name> --spec <path-or-url>               # register API + emit manifest + seed empty .env.yaml
+zond doctor --api <name> --missing-only                # gap report: which vars are UNSET
+zond prepare-fixtures --api <name> --apply [--seed]    # fill .env.yaml from live API
+zond doctor --api <name>                               # re-check (exit 0 = ready)
+```
+
+What each step does to `.env.yaml`:
+
+| Command | Touches `.env.yaml`? |
+|---|---|
+| `zond init` | no — only writes workspace/skills files |
+| `zond add api` | seeds skeleton with empty placeholders for every required var |
+| `zond doctor` | no — read-only diagnostic |
+| `zond prepare-fixtures --apply` | writes discovered values (`.bak` backup); `--seed` POST-creates resources when list endpoints return `[]` |
+| `zond refresh-api` | no — only re-snapshots `spec.json` and rebuilds the manifest |
+
+`zond refresh-api <name> [--spec <new-source>]` re-snapshots when the upstream
+spec changes.
+
+**Re-running `zond init`** is safe and expected after a CLI upgrade: it
+re-emits skills/AGENTS.md/zond.config.yml only. Fixtures stay exactly as
+they were — never relies on init to fill `.env.yaml`.
+
+### Mandatory rules (mirrored from the skills — non-negotiable)
+
+- **NEVER read raw OpenAPI/Swagger** with Read/cat/grep — use the artifacts
+  in `apis/<name>/.api-*.yaml`. Drop into `spec.json` only when a probe
+  generator needs full schemas.
+- **NEVER use curl/wget** — use `zond request <method> <url>` for ad-hoc HTTP.
+- **NEVER write test YAML from scratch for autogen flows** — start with
+  `zond generate`, then edit failures. (Hand-written YAML is fine for
+  scenarios.)
+- **NEVER hardcode tokens** — `apis/<name>/.env.yaml` (auto-gitignored),
+  reference as `{{auth_token}}`.
+- **`recommended_action: report_backend_bug` (5xx) → STOP**, do not edit
+  assertions to make the test pass.

package/src/cli/commands/init/templates/markdown.d.ts

@@ -0,0 +1,4 @@
+declare module "*.md" {
+  const content: string;
+  export default content;
+}