@kirrosh/zond 0.26.0 → 0.27.0

package/src/cli/commands/add-api.ts

@@ -1,146 +0,0 @@
-/**
- * `zond add api <name> --spec <path|url>` — register a new API in the
- * current workspace.
- *
- * The split from `zond init --spec` exists so the two operations
- * (workspace bootstrap vs. API registration) have separate names and
- * separate skill mentions. `init --spec` still works as a deprecated
- * alias.
- *
- * This command refuses to run when no workspace marker is present,
- * pointing the user at `zond init` first. setupApi handles spec
- * snapshot + artifact generation.
- */
-
-import { setupApi, type SetupApiResult } from "../../core/setup-api.ts";
-import { findWorkspaceRoot } from "../../core/workspace/root.ts";
-import { jsonOk, jsonError, printJson, zerr } from "../json-envelope.ts";
-import { printError, printSuccess } from "../output.ts";
-
-export interface AddApiOptions {
-  name: string;
-  /** One or more specs. Multiple → deterministic union (ARV-375). */
-  specs?: string[];
-  baseUrl?: string;
-  dir?: string;
-  force?: boolean;
-  insecure?: boolean;
-  caPath?: string;
-  dbPath?: string;
-  json?: boolean;
-}
-
-export async function addApiCommand(opts: AddApiOptions): Promise<number> {
-  const ws = findWorkspaceRoot();
-  if (ws.fromFallback) {
-    const m = `No workspace detected (no zond.config.yml / .zond / apis marker). Run \`zond init\` first to bootstrap a workspace.`;
-    if (opts.json) printJson(jsonError("add-api", [m])); else printError(m);
-    return 2;
-  }
-
-  const envVars: Record<string, string> = {};
-  if (opts.baseUrl) envVars.base_url = opts.baseUrl;
-
-  const hasSpec = (opts.specs?.length ?? 0) > 0;
-  let result: SetupApiResult;
-  try {
-    result = await setupApi({
-      name: opts.name,
-      specs: opts.specs,
-      dir: opts.dir,
-      envVars: Object.keys(envVars).length > 0 ? envVars : undefined,
-      dbPath: opts.dbPath,
-      force: opts.force,
-      insecure: opts.insecure,
-      caPath: opts.caPath,
-    });
-  } catch (err) {
-    const m = (err as Error).message;
-    // Tag known spec-ingest failures with a structured code so downstream
-    // tooling (skills, retry logic) can branch on it (ARV-145). Cyclic
-    // structures escape decycleSchema only when @readme/openapi-parser
-    // builds an unusual graph — surface that as spec_load_failure with a
-    // pointer to the underlying serializer message.
-    const isCycleError = /cyclic structures|spec_serialize_failed/i.test(m);
-    const errInput = isCycleError ? zerr("spec_load_failure", m) : m;
-    if (opts.json) printJson(jsonError("add-api", [errInput])); else printError(m);
-    return 2;
-  }
-
-  const mode: "spec" | "run-only" = hasSpec ? "spec" : "run-only";
-  const artifacts = mode === "spec"
-    ? ["spec.json", ".api-catalog.yaml", ".api-resources.yaml", ".api-fixtures.yaml", ".env.yaml"]
-    : [".env.yaml"];
-
-  if (opts.json) {
-    printJson(jsonOk("add-api", {
-      api: opts.name,
-      mode,
-      collectionId: result.collectionId,
-      baseDir: result.baseDir,
-      testPath: result.testPath,
-      endpoints: result.specEndpoints,
-      artifacts,
-    }, result.warnings));
-  } else {
-    if (mode === "spec") {
-      printSuccess(`Registered API '${opts.name}' at ${result.baseDir} (${result.specEndpoints} endpoints)`);
-      process.stdout.write(`  Artifacts: spec.json + .api-catalog.yaml + .api-resources.yaml + .api-fixtures.yaml\n`);
-      if (result.authVars && result.authVars.length > 0) {
-        const list = result.authVars.map((v) => `\`${v}\``).join(", ");
-        process.stdout.write(`  Auth required: fill ${list} in ${result.baseDir}/.secrets.yaml (already wired via @secret in .env.yaml).\n`);
-      }
-      process.stdout.write(`  Next: run \`zond doctor --api ${opts.name}\` to see required fixtures.\n`);
-    } else {
-      printSuccess(`Registered API '${opts.name}' at ${result.baseDir} (no spec — run-only mode)`);
-      process.stdout.write(`  Artifacts: .env.yaml (base_url=${opts.baseUrl})\n`);
-      process.stdout.write(`  Next: write tests in ${result.testPath}/, run \`zond run --api ${opts.name} <test.yaml>\`.\n`);
-      process.stdout.write(`  To enable generate/probe/validate-schema, attach a spec: \`zond refresh-api ${opts.name} --spec <path|url>\`.\n`);
-    }
-    if (result.warnings) for (const w of result.warnings) process.stderr.write(`Warning: ${w}\n`);
-  }
-  return 0;
-}
-
-import type { Command } from "commander";
-import { globalJson } from "../resolve.ts";
-
-export function registerAdd(program: Command): void {
-  const add = program.command("add").description("Register objects in the workspace");
-  add
-    .command("api <name>")
-    .description("Register an API: from an OpenAPI spec (full toolkit) or just --base-url (run-only mode)")
-    .option(
-      "--spec <path>",
-      "Path or URL to OpenAPI spec — enables generate/probe/validate-schema. Repeat --spec to union multiple specs (e.g. v1 + v2) into one merged audit target (ARV-375).",
-      (val: string, acc: string[]) => acc.concat(val),
-      [] as string[],
-    )
-    .option("--base-url <url>", "Base URL recorded in .env.yaml (required if --spec is omitted)")
-    .option("--dir <path>", "Target directory (defaults to apis/<name>/)")
-    .option("--force", "Overwrite an existing API with the same name")
-    .option("--insecure", "Skip TLS verification when fetching the spec from https")
-    .option("--ca <path>", "PEM CA bundle to trust for the spec fetch (adds to public roots; also reads NODE_EXTRA_CA_CERTS) — use instead of --insecure for internal/corp CAs")
-    .option("--db <path>", "Path to SQLite database file")
-    .action(async (name: string, opts, cmd: Command) => {
-      const json = globalJson(cmd);
-      const specs: string[] = Array.isArray(opts.spec) ? opts.spec : (opts.spec ? [opts.spec] : []);
-      if (specs.length === 0 && !opts.baseUrl) {
-        const m = "Provide --spec <path|url> for a full registration, or --base-url <url> for run-only mode.";
-        if (json) printJson(jsonError("add-api", [m])); else printError(m);
-        process.exitCode = 2;
-        return;
-      }
-      process.exitCode = await addApiCommand({
-        name,
-        specs,
-        baseUrl: opts.baseUrl,
-        dir: opts.dir,
-        force: opts.force === true,
-        insecure: opts.insecure === true,
-        caPath: typeof opts.ca === "string" ? opts.ca : undefined,
-        dbPath: typeof opts.db === "string" ? opts.db : undefined,
-        json,
-      });
-    });
-}

package/src/cli/commands/api/annotate/idempotency.ts

@@ -1,59 +0,0 @@
-/**
- * ARV-187 / idempotency: parser + expected shape.
- */
-
-import { z } from "zod";
-import type { ResourcePatch } from "./overlay.ts";
-import type { ResourceSlice } from "./prompts.ts";
-
-const IdempotencySchema = z.object({
-  header: z.string().default("Idempotency-Key"),
-  scope: z.enum(["endpoint", "global"]).optional(),
-  ignore_response_fields: z.array(z.string()).optional(),
-});
-
-const ResponseSchema = z.object({
-  resource: z.string(),
-  idempotency: IdempotencySchema.nullable(),
-  rationale: z.string().optional(),
-  confidence: z.enum(["low", "medium", "high"]).optional(),
-});
-
-export const EXPECTED_OUTPUT_SHAPE = {
-  resource: "string (echo input)",
-  idempotency: {
-    header: "string (header name, e.g. 'Idempotency-Key')",
-    scope: "endpoint | global (optional)",
-    ignore_response_fields: "string[] (optional — fields that change between replays, e.g. 'created')",
-  },
-  rationale: "string (optional)",
-  confidence: "low | medium | high",
-  null_form: "if create endpoint doesn't support idempotency-replay, return { resource, idempotency: null }",
-};
-
-export function parseIdempotencyResponse(parsed: unknown, slice: ResourceSlice): { patch: ResourcePatch; audit: Record<string, unknown> } {
-  const validated = ResponseSchema.safeParse(parsed);
-  if (!validated.success) {
-    throw new Error(`idempotency response failed schema for ${slice.resource}: ${validated.error.message}`);
-  }
-  const v = validated.data;
-  if (v.idempotency == null) {
-    return {
-      patch: { resource: slice.resource },
-      audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence, dropped: "no Idempotency-Key support" },
-    };
-  }
-  return {
-    patch: {
-      resource: slice.resource,
-      idempotency: {
-        header: v.idempotency.header,
-        scope: v.idempotency.scope,
-        ignore_response_fields: v.idempotency.ignore_response_fields,
-      },
-    },
-    audit: { resource: slice.resource, rationale: v.rationale, confidence: v.confidence },
-  };
-}
-
-export function isApplicable(slice: ResourceSlice): boolean { return Boolean(slice.endpoints.create); }