@kirrosh/zond 0.22.0 → 0.23.0

package/src/cli/commands/{init.ts → init/index.ts}

@@ -1,7 +1,8 @@
-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 "./init/bootstrap.ts";
+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)
@@ -21,6 +22,8 @@ export interface InitOptions {
   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). */
@@ -55,7 +58,13 @@ export async function initCommand(options: InitOptions): Promise<number> {
       return 0;
     }
 
-    const bootstrap = bootstrapWorkspace({ writeAgents, writeSkills, cwd: options.cwd, home: options.home });
+    const bootstrap = bootstrapWorkspace({
+      writeAgents,
+      writeSkills,
+      pruneStaleSkills: options.pruneStaleSkills,
+      cwd: options.cwd,
+      home: options.home,
+    });
     let register: SetupApiResult | null = null;
 
     if (mode === "bootstrap+register") {
@@ -72,6 +81,8 @@ export async function initCommand(options: InitOptions): Promise<number> {
         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;
@@ -134,6 +145,9 @@ function printBootstrapResult(b: BootstrapResult, writeAgents: boolean): void {
   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`);
   }
@@ -143,8 +157,88 @@ function printBootstrapResult(b: BootstrapResult, writeAgents: boolean): void {
   } 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

@@ -1,8 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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 scenariosSkill from "./templates/skills/scenarios.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;
@@ -16,10 +17,62 @@ interface SkillTemplate {
 }
 
 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 },
-  { name: "zond-scenarios", body: scenariosSkill },
+  // 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.

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

@@ -1,73 +1,77 @@
 ## API testing with zond
 
-This workspace uses [zond](https://github.com/kirrosh/zond) for API testing. The MCP
-server is **not** configured for this workspace, so use the CLI directly.
+This workspace uses [zond](https://github.com/kirrosh/zond) for API testing — CLI
+only, no MCP server in this workspace.
 
-### Detailed playbooks (skills)
+### Skills
 
-Detailed task-specific playbooks live in `.claude/skills/` and are auto-discovered by
-Claude Code. Other agents (Codex, Cursor, Aider) can read them as plain markdown:
+- **`.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.
 
-- `.claude/skills/zond/SKILL.md` — end-to-end API testing: generate from OpenAPI,
-  run, diagnose failures, hunt bugs via probes, report coverage. Has explicit
-  entry points so narrow requests (only diagnose, only probe) skip earlier phases.
-- `.claude/skills/zond-scenarios/SKILL.md` — author multi-step user-journey tests
-  and fixture creation via the API (hand-written YAML with captures,
-  `setup: true`, `always: true`). NOT for spec coverage or bug hunting.
+Both skills work off the per-API artifacts written by `zond add api`:
 
-### Mandatory rules (always-on)
+```
+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/
+```
 
-- **NEVER** read OpenAPI/Swagger/JSON spec files with Read/cat — use `zond describe`,
-  `zond catalog`, or the generated `.api-catalog.yaml`.
-- **NEVER** use curl/wget for ad-hoc requests — use `zond request <method> <url>`.
-- **NEVER** write test YAML from scratch — start with `zond generate <spec> --output <dir>`,
-  then edit failing cases.
-- **NEVER** hardcode tokens — put them in `apis/<name>/.env.yaml` (already gitignored)
-  and reference as `{{auth_token}}` in test YAML.
-- `--safe` enforces GET-only; never run CRUD tests against production without explicit
-  user confirmation and a staging environment.
-- When `zond db diagnose` reports `recommended_action: report_backend_bug` — STOP, do
-  not change the test to make it pass.
+`.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.
 
-### Workflow — covering an API end-to-end
+### Setup flow
 
 ```bash
-# 1. Register the API
-zond init --spec <path-or-url> --name <name> [--base-url <url>]
-zond use <name>                              # remember as current
-
-# 2. Inspect endpoints (avoid reading the raw spec)
-zond catalog <spec> --output apis/<name>     # writes .api-catalog.yaml
-zond describe <spec> --compact
-
-# 3. Generate test stubs and run smoke (GET-only)
-zond generate <spec> --output apis/<name>/tests --tag smoke
-zond run --safe --json
-
-# 4. Diagnose failures
-zond db runs --limit 5
-zond db diagnose <run-id> --json
-
-# 5. Coverage gate
-zond coverage --fail-on-coverage 50
-
-# 6. CRUD only with explicit user confirmation + staging env
-zond run --tag crud --dry-run                # show what would be sent
-zond run --tag crud --env staging
+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)
 ```
 
-### Filtering by tag
-
-`--tag <name>` filters suites. If a `setup` suite primes auth tokens, always include
-its tag together with the target group: `--tag crud,setup`.
-
-### Auth patterns
-
-For in-memory or test backends that issue tokens via login, use a `setup.yaml` suite
-with `setup: true`. Captured variables (e.g. `auth_token`) propagate to subsequent
-suites in the same run. Do NOT hardcode bearer tokens for these flows.
-
-### Environments
-
-`zond run --env <name>` loads `.env.<name>.yaml` (or `.env.yaml` by default) from the
-API directory. Environment files are auto-gitignored by `zond init`.
+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.