@wacht/bench 0.1.2 → 0.1.4

package/dist/commands.js

@@ -16,6 +16,7 @@ import { completionScript } from './completion.js';
 import { configApply, configDiff, configPull, configSchemaCommand, printConfigTemplate, } from './config-workflow.js';
 import { clearDeployment, createDeploymentCommand, createProjectCommand, currentDeployment, selectDeployment, } from './deployment-context.js';
 import { initProject, initStarter } from './init.js';
+import { docsSearch } from './docs-search.js';
 import { envPull } from './env-pull.js';
 import { apiCommand, listProjects } from './machine-api.js';
 import { openApiCall, openApiDescribe, openApiList, openApiRefresh } from './openapi.js';
@@ -219,6 +220,21 @@ export async function runCli(args) {
         .action((options) => {
         printMcpConfig(options.client);
     });
+    const docs = program.command('docs').description('search and explore Wacht docs');
+    docs
+        .command('search <query...>')
+        .description('full-text search Wacht docs and print matching pages')
+        .option('--limit <n>', 'max number of pages to print', (v) => Number.parseInt(v, 10))
+        .option('--base-url <url>', 'docs base URL (default: https://wacht.dev/docs, or $WACHT_DOCS_URL)')
+        .option('--json', 'emit JSON instead of human-readable output')
+        .action(async (queryParts, options) => {
+        await docsSearch(context(program), {
+            query: queryParts.join(' '),
+            limit: options.limit,
+            baseUrl: options.baseUrl,
+            json: options.json,
+        });
+    });
     const env = program.command('env').description('manage deployment credentials and environment files');
     env
         .command('pull')
@@ -307,14 +323,18 @@ export async function runCli(args) {
         .argument('<operation>', 'OpenAPI operation id')
         .option('--deployment <id>', 'deployment id override; defaults to active deployment')
         .option('--param <key=value>', 'path or query parameter; repeatable', collect, [])
-        .option('--body <json>', 'JSON request body')
+        .option('--body <json>', 'JSON request body; pass @path/to/file.json to read from disk')
         .option('--field <key=value>', 'URL-encoded form field; repeatable', collect, [])
         .option('--form <key=value>', 'multipart form field; value @path is treated as a file; repeatable', collect, [])
         .option('--file <key=path>', 'multipart file field; key=path or key=@path; repeatable', collect, [])
         .option('--header <key=value>', 'request header; repeatable', collect, [])
         .option('--refresh', 'refresh the cached OpenAPI schema first')
-        .action(async (operation, options) => {
-        await openApiCall(context(program), operation, options);
+        .option('--no-validate', 'skip local JSON Schema validation of the request body')
+        .action(async (operation, _options, cmd) => {
+        // The parent `api` command also declares --body / --field / --form / --file / --header
+        // so `optsWithGlobals()` is what actually surfaces them through this subcommand.
+        // Commander does not merge clashing options automatically.
+        await openApiCall(context(program), operation, cmd.optsWithGlobals());
     });
     const schema = api.command('schema').description('manage cached OpenAPI schema');
     schema

package/dist/docs-search.js

@@ -0,0 +1,81 @@
+import { field, log, printBannerFor, printError, printJson, section } from './ui.js';
+const DEFAULT_DOCS_URL = 'https://wacht.dev/docs';
+export async function docsSearch(ctx, options) {
+    const baseUrl = (options.baseUrl ?? process.env.WACHT_DOCS_URL ?? DEFAULT_DOCS_URL).replace(/\/+$/, '');
+    const endpoint = `${baseUrl}/api/search?query=${encodeURIComponent(options.query)}`;
+    let response;
+    try {
+        response = await fetch(endpoint, { headers: { Accept: 'application/json' } });
+    }
+    catch (error) {
+        printError(error);
+        process.exitCode = 1;
+        return;
+    }
+    if (!response.ok) {
+        printError(new Error(`docs search failed: ${response.status} ${response.statusText} (${endpoint})`));
+        process.exitCode = 1;
+        return;
+    }
+    const raw = (await response.json());
+    if (!Array.isArray(raw)) {
+        printError(new Error('unexpected docs search response shape'));
+        process.exitCode = 1;
+        return;
+    }
+    const pages = new Map();
+    const snippets = new Map();
+    for (const hit of raw) {
+        const pageUrl = hit.url.split('#')[0];
+        if (hit.type === 'page') {
+            pages.set(pageUrl, hit);
+        }
+        else {
+            if (!snippets.has(pageUrl))
+                snippets.set(pageUrl, []);
+            snippets.get(pageUrl).push(hit);
+        }
+    }
+    const orderedPages = Array.from(pages.values());
+    const sliced = options.limit ? orderedPages.slice(0, options.limit) : orderedPages;
+    if (options.json) {
+        printJson({
+            ok: true,
+            query: options.query,
+            baseUrl,
+            results: sliced.map((page) => ({
+                title: page.content,
+                url: `${baseUrl}${page.url}`,
+                breadcrumbs: page.breadcrumbs ?? [],
+                snippets: (snippets.get(page.url) ?? []).map((s) => ({
+                    text: s.content,
+                    url: `${baseUrl}${s.url}`,
+                })),
+            })),
+        });
+        return;
+    }
+    printBannerFor(ctx);
+    log(ctx, section('Docs Search'));
+    log(ctx, field('Query', options.query));
+    log(ctx, field('Source', baseUrl));
+    log(ctx, field('Results', String(sliced.length)));
+    log(ctx, '');
+    if (sliced.length === 0) {
+        log(ctx, 'No matches.');
+        return;
+    }
+    for (const page of sliced) {
+        const breadcrumbs = page.breadcrumbs?.length ? page.breadcrumbs.join(' › ') : '';
+        log(ctx, `• ${page.content}`);
+        if (breadcrumbs)
+            log(ctx, `    ${breadcrumbs}`);
+        log(ctx, `    ${baseUrl}${page.url}`);
+        const pageSnippets = snippets.get(page.url) ?? [];
+        for (const s of pageSnippets.slice(0, 3)) {
+            const trimmed = s.content.length > 140 ? `${s.content.slice(0, 137).trimEnd()}…` : s.content;
+            log(ctx, `      – ${trimmed}`);
+        }
+        log(ctx, '');
+    }
+}

package/dist/env-pull.js

@@ -73,10 +73,15 @@ export async function envPull(ctx, options = {}) {
     }
     const root = process.cwd();
     const profile = await detectProject(root);
-    const pubVar = publishableKeyVar(new Set(profile.frameworks));
+    const frameworks = new Set(profile.frameworks);
+    const pubVar = publishableKeyVar(frameworks);
+    // Vite-based frameworks read `.env`; Next.js reads `.env.local`.
+    const defaultFile = frameworks.has('React Router') || frameworks.has('TanStack Router')
+        ? '.env'
+        : '.env.local';
     const filePath = options.file
         ? path.resolve(root, options.file)
-        : path.join(root, '.env.local');
+        : path.join(root, defaultFile);
     const existing = await readFile(filePath, 'utf8').catch((err) => {
         if (err.code === 'ENOENT')
             return '';

package/dist/init.js

@@ -43,7 +43,7 @@ This project is configured for AI-assisted Wacht development.
 - Detected project shape: \`${frameworks}\`.
 - Suggested Wacht skills for this project: \`${skills}\`.
 - Active skill router: \`wacht\` (always start there). For CLI work specifically, use the \`wacht-bench-cli\` skill.
-- Install or update skills with \`wacht skills add\`.
+- Install or update skills with \`wacht skills install\`.
 
 ### Where to look (single source of truth)
 
@@ -96,6 +96,13 @@ async function upsertAgentsBlock(root, profile) {
     return agentsPath;
 }
 async function writeEnvTemplate(root, profile) {
+    // If the project already ships a `.env.local.example` / `.env.example` (typical for
+    // scaffolded starters), don't drop a second redundant file alongside it.
+    for (const existing of ['.env.local.example', '.env.example']) {
+        if (await pathExists(path.join(root, existing))) {
+            return null;
+        }
+    }
     const envPath = path.join(root, '.env.wacht.example');
     const frameworks = new Set(profile.frameworks);
     const isVite = frameworks.has('React Router') || frameworks.has('TanStack Router');
@@ -105,7 +112,8 @@ async function writeEnvTemplate(root, profile) {
             ? 'VITE_WACHT_PUBLISHABLE_KEY'
             : 'NEXT_PUBLIC_WACHT_PUBLISHABLE_KEY';
     const lines = [
-        '# Wacht SDK environment. Fill these from your Wacht deployment.',
+        '# Wacht SDK environment. Run `wacht env pull` to populate these automatically,',
+        '# or copy values from https://console.wacht.dev.',
         '',
         '# Client-safe publishable key. Encodes deployment + frontend host.',
         `${publishableKeyVar}=`,
@@ -129,7 +137,9 @@ export async function initProject(args, ctx) {
     log(ctx, field('Suggested skills', profile.suggestedSkills.join(', ')));
     log(ctx, '');
     if (!options.skipEnv) {
-        written.push(await writeEnvTemplate(root, profile));
+        const envPath = await writeEnvTemplate(root, profile);
+        if (envPath)
+            written.push(envPath);
     }
     if (!options.skipAgents) {
         written.push(await upsertAgentsBlock(root, profile));
@@ -142,10 +152,6 @@ export async function initProject(args, ctx) {
         log(ctx, section('Install Skills'));
         await installSkills({ yes: true });
     }
-    else {
-        log(ctx, '');
-        log(ctx, field('Skills', `run ${command('wacht skills install')} when you want to install/update the pack`));
-    }
     if (ctx.json) {
         printJson({
             ok: true,
@@ -162,6 +168,22 @@ export async function initProject(args, ctx) {
     log(ctx, '');
     log(ctx, success('Wacht Bench project bootstrap complete.'));
 }
+function printAgentBootstrapSteps(ctx, opts) {
+    log(ctx, '');
+    log(ctx, section('Next'));
+    const cd = opts.starterDir ? `cd ${opts.starterDir} && ` : '';
+    if (!opts.installedSkills) {
+        log(ctx, `  ${command('wacht skills install --agent claude-code --global --yes')}`);
+    }
+    log(ctx, `  ${command('wacht mcp install --client claude-code-user --yes')}`);
+    log(ctx, `  ${command('wacht login && wacht deployments select')}`);
+    log(ctx, `  ${command(`${cd}wacht env pull`)}`);
+    if (opts.starterDir) {
+        log(ctx, `  ${command(`${cd}pnpm install && pnpm dev`)}`);
+    }
+    log(ctx, '');
+    log(ctx, '(Restart your AI client after installing skills/MCP so they load.)');
+}
 // ─── Starter mode ───────────────────────────────────────────────────
 const STARTERS = {
     nextjs: {
@@ -232,7 +254,10 @@ export async function initStarter(options, ctx) {
     }
     log(ctx, '');
     log(ctx, success(`Starter ready at ${path.relative(process.cwd(), absoluteTarget) || '.'}`));
-    log(ctx, `Next: ${command(`cd ${path.relative(process.cwd(), absoluteTarget) || '.'} && pnpm install && pnpm dev`)}`);
+    printAgentBootstrapSteps(ctx, {
+        starterDir: path.relative(process.cwd(), absoluteTarget) || '.',
+        installedSkills: options.install,
+    });
 }
 export function listStarters() {
     return Object.entries(STARTERS).map(([framework, info]) => ({ framework, description: info.description, repo: info.repo }));

package/dist/machine-api.js

@@ -239,9 +239,16 @@ export async function requestBody(options) {
         headers.set(key, value);
     }
     if (options.body) {
+        // `--body @path/to/file.json` reads the JSON from disk so prompt files and
+        // larger configuration blobs don't have to be inlined in the shell.
+        let source = options.body;
+        if (source.startsWith('@')) {
+            const filePath = path.resolve(source.slice(1));
+            source = await readFile(filePath, 'utf8');
+        }
         headers.set('content-type', 'application/json');
         return {
-            body: JSON.stringify(JSON.parse(options.body)),
+            body: JSON.stringify(JSON.parse(source)),
             headers,
         };
     }

package/dist/openapi-validate.js

@@ -0,0 +1,172 @@
+import { Ajv } from 'ajv';
+/**
+ * Validate a JSON request body against an operation's `requestBody` schema using
+ * the cached OpenAPI spec. Returns `null` on success; an array of human-readable
+ * error strings on failure.
+ *
+ * The validator handles OpenAPI 3.0 `nullable: true` (rewritten to JSON-Schema
+ * `type: [..., "null"]`), `$ref` resolution against `components.schemas`, and
+ * discriminated unions via `oneOf` + `discriminator`.
+ */
+export function validateBody(spec, schema, body) {
+    if (!isRecord(schema))
+        return null;
+    const componentSchemas = readComponentSchemas(spec);
+    const ajv = buildAjv(componentSchemas);
+    const compiled = compileSafely(ajv, schema);
+    if (!compiled)
+        return null;
+    if (compiled(body))
+        return null;
+    return summariseErrors(compiled.errors ?? [], body);
+}
+// Collapse `oneOf` failures into one line per union and drop the noisy umbrella
+// + `type: null` errors our `nullable` rewrite introduces.
+function summariseErrors(rawErrors, body) {
+    // Discover oneOf failure points by looking for the `oneOf` umbrella error.
+    const oneOfPaths = new Set();
+    for (const e of rawErrors) {
+        if (e.keyword === 'oneOf')
+            oneOfPaths.add(e.instancePath);
+    }
+    const collapsed = [];
+    const skip = new Set();
+    for (const path of oneOfPaths) {
+        const value = readJsonPointer(body, path);
+        // The variant tag is conventionally `type`; if absent, just describe the path.
+        const tag = isRecord(value) && typeof value.type === 'string'
+            ? `, got type "${value.type}"`
+            : '';
+        collapsed.push(`${path || '(body root)'}: doesn't match any variant of the discriminated union${tag}. ` +
+            `Run \`wacht api describe <operation>\` to see each variant's required fields.`);
+        // Drop every error at the union path; the user fixes the variant first.
+        for (const e of rawErrors) {
+            if (e.instancePath === path || e.instancePath.startsWith(path + '/'))
+                skip.add(e);
+        }
+    }
+    const out = [...collapsed];
+    for (const e of rawErrors) {
+        if (skip.has(e))
+            continue;
+        if (e.keyword === 'anyOf' || e.keyword === 'oneOf')
+            continue;
+        if (e.keyword === 'type' && e.params?.type === 'null')
+            continue;
+        out.push(formatError(e));
+    }
+    // Dedupe identical lines (e.g. two variants both miss the same field).
+    return [...new Set(out)];
+}
+function readJsonPointer(value, pointer) {
+    if (!pointer || pointer === '/')
+        return value;
+    const segments = pointer.split('/').slice(1).map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+    let cur = value;
+    for (const seg of segments) {
+        if (Array.isArray(cur)) {
+            const idx = Number.parseInt(seg, 10);
+            if (Number.isNaN(idx))
+                return undefined;
+            cur = cur[idx];
+        }
+        else if (isRecord(cur)) {
+            cur = cur[seg];
+        }
+        else {
+            return undefined;
+        }
+    }
+    return cur;
+}
+function readComponentSchemas(spec) {
+    if (!isRecord(spec))
+        return {};
+    const components = isRecord(spec.components) ? spec.components : undefined;
+    const schemas = components && isRecord(components.schemas) ? components.schemas : undefined;
+    return schemas ?? {};
+}
+function buildAjv(componentSchemas) {
+    // OpenAPI 3.1 schemas are JSON Schema draft 2020-12, but the spec we generate
+    // also leans on draft-7 `nullable: true` shorthand. Rewrite to draft-7 unions
+    // and run Ajv permissively — we're validating user payloads, not enforcing
+    // the spec itself.
+    const ajv = new Ajv({
+        strict: false,
+        allErrors: true,
+        coerceTypes: false,
+        allowUnionTypes: true,
+        validateFormats: false,
+    });
+    // Make every component schema addressable by its $ref so nested references resolve.
+    for (const [name, raw] of Object.entries(componentSchemas)) {
+        const rewritten = rewriteNullable(raw);
+        try {
+            ajv.addSchema(rewritten, `#/components/schemas/${name}`);
+        }
+        catch {
+            // Bad schemas shouldn't break the CLI — skip and keep going.
+        }
+    }
+    return ajv;
+}
+function compileSafely(ajv, schema) {
+    try {
+        return ajv.compile(rewriteNullable(schema));
+    }
+    catch {
+        return null;
+    }
+}
+/** Walk a schema and rewrite `{type: X, nullable: true}` → `{type: [X, "null"]}`. */
+function rewriteNullable(value) {
+    if (Array.isArray(value))
+        return value.map(rewriteNullable);
+    if (!isRecord(value))
+        return value;
+    const out = {};
+    let nullable = false;
+    for (const [key, v] of Object.entries(value)) {
+        if (key === 'nullable' && v === true) {
+            nullable = true;
+            continue;
+        }
+        out[key] = rewriteNullable(v);
+    }
+    if (nullable && typeof out.type === 'string') {
+        out.type = [out.type, 'null'];
+    }
+    else if (nullable && Array.isArray(out.type)) {
+        if (!out.type.includes('null'))
+            out.type = [...out.type, 'null'];
+    }
+    else if (nullable) {
+        // No `type`; allow null alongside whatever shape the schema describes.
+        out.anyOf = [{ ...out }, { type: 'null' }];
+        for (const k of Object.keys(out))
+            if (k !== 'anyOf')
+                delete out[k];
+    }
+    return out;
+}
+function formatError(err) {
+    const path = err.instancePath || '(body root)';
+    const reason = err.message ?? 'invalid';
+    const extras = err.params ? formatParams(err.params) : '';
+    return `${path}: ${reason}${extras}`;
+}
+function formatParams(params) {
+    // Skim the most useful bits — missingProperty, allowedValues — without
+    // dumping every Ajv internal.
+    const bits = [];
+    if (typeof params.missingProperty === 'string')
+        bits.push(`missing "${params.missingProperty}"`);
+    if (Array.isArray(params.allowedValues))
+        bits.push(`allowed: ${params.allowedValues.map((v) => JSON.stringify(v)).join(', ')}`);
+    if (typeof params.additionalProperty === 'string')
+        bits.push(`unknown property "${params.additionalProperty}"`);
+    return bits.length ? ` (${bits.join('; ')})` : '';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/openapi.js

@@ -1,7 +1,9 @@
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
 import { AUTH_DIR, OPENAPI_CACHE_FILE, PLATFORM_OPENAPI_URL } from './config.js';
 import { readBenchContext } from './context-store.js';
 import { entries, requestBody, machineRequest } from './machine-api.js';
+import { validateBody } from './openapi-validate.js';
 import { field, log, printBannerFor, printJson, section, warning } from './ui.js';
 const OPENAPI_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
@@ -74,6 +76,7 @@ function operations(spec) {
                 tags: typed.tags ?? [],
                 parameters: typed.parameters ?? [],
                 requestBody: typed.requestBody,
+                responses: typed.responses,
             });
         }
     }
@@ -95,14 +98,172 @@ function findOperation(spec, target, maybePath) {
 function schemaType(schema) {
     if (!schema)
         return 'unknown';
-    if (typeof schema.type === 'string')
+    if (typeof schema.type === 'string') {
+        if (schema.type === 'array' && isRecord(schema.items)) {
+            return `array<${schemaType(schema.items)}>`;
+        }
+        if (Array.isArray(schema.enum) && schema.enum.length) {
+            return `${schema.type}<${schema.enum.map((v) => JSON.stringify(v)).join(' | ')}>`;
+        }
+        if (typeof schema.const === 'string')
+            return `const "${schema.const}"`;
+        // Surface common formats like `binary` (file uploads) so multipart fields
+        // are recognisable at a glance vs plain strings.
+        if (typeof schema.format === 'string')
+            return `${schema.type} (${schema.format})`;
         return schema.type;
+    }
     if (typeof schema.$ref === 'string')
         return schema.$ref.split('/').pop() ?? schema.$ref;
     if (Array.isArray(schema.anyOf))
         return schema.anyOf.map((item) => isRecord(item) ? schemaType(item) : 'unknown').join(' | ');
+    if (Array.isArray(schema.oneOf))
+        return schema.oneOf.map((item) => isRecord(item) ? schemaType(item) : 'unknown').join(' | ');
+    if (schema.const !== undefined)
+        return `const ${JSON.stringify(schema.const)}`;
     return 'object';
 }
+const REF_PREFIX = '#/components/schemas/';
+function resolveSchemaRef(spec, schema, seen = new Set()) {
+    if (!schema)
+        return undefined;
+    if (typeof schema.$ref !== 'string')
+        return schema;
+    const name = schema.$ref.startsWith(REF_PREFIX) ? schema.$ref.slice(REF_PREFIX.length) : '';
+    if (!name || seen.has(name))
+        return schema;
+    const schemas = isRecord(spec.components) && isRecord(spec.components.schemas) ? spec.components.schemas : undefined;
+    const target = schemas?.[name];
+    if (!isRecord(target))
+        return schema;
+    seen.add(name);
+    return resolveSchemaRef(spec, target, seen);
+}
+/**
+ * Merge an `allOf` chain into a single object schema. Used for our generator's
+ * internally-tagged enum encoding: `allOf: [{$ref: Payload}, {properties: {<tag>: const}}]`.
+ */
+function flattenAllOf(spec, schema) {
+    if (!Array.isArray(schema.allOf))
+        return schema;
+    const props = {};
+    const required = new Set();
+    for (const part of schema.allOf) {
+        if (!isRecord(part))
+            continue;
+        const resolved = resolveSchemaRef(spec, part) ?? part;
+        if (isRecord(resolved.properties)) {
+            for (const [key, value] of Object.entries(resolved.properties))
+                props[key] = value;
+        }
+        if (Array.isArray(resolved.required)) {
+            for (const key of resolved.required) {
+                if (typeof key === 'string')
+                    required.add(key);
+            }
+        }
+    }
+    return { type: 'object', properties: props, required: Array.from(required) };
+}
+/** How many levels of nested object schemas to inline before falling back to the type name. */
+const MAX_BODY_DEPTH = 3;
+/** Pull the schema-component name out of a `$ref`, if any. */
+function refName(schema) {
+    if (!schema || typeof schema.$ref !== 'string')
+        return undefined;
+    return schema.$ref.startsWith(REF_PREFIX) ? schema.$ref.slice(REF_PREFIX.length) : undefined;
+}
+/** True when a resolved schema carries structure worth expanding inline. */
+function isStructural(schema) {
+    if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf) || Array.isArray(schema.allOf))
+        return true;
+    if (isRecord(schema.properties) && Object.keys(schema.properties).length > 0)
+        return true;
+    return false;
+}
+function printSchema(pctx, raw, indent, depth) {
+    // Stop recursing if we're already too deep — caller has shown the type name.
+    if (depth > MAX_BODY_DEPTH)
+        return;
+    const name = refName(raw);
+    if (name && pctx.seen.has(name)) {
+        log(pctx.ctx, `${indent}(circular reference to ${name})`);
+        return;
+    }
+    const resolved = resolveSchemaRef(pctx.spec, raw) ?? raw;
+    const flat = Array.isArray(resolved.allOf) ? flattenAllOf(pctx.spec, resolved) : resolved;
+    if (Array.isArray(flat.oneOf)) {
+        if (depth >= MAX_BODY_DEPTH) {
+            log(pctx.ctx, `${indent}(oneOf — drill further with \`wacht api describe ${name ?? '<schema>'}\`)`);
+            return;
+        }
+        if (depth === 0)
+            log(pctx.ctx, `${indent}(oneOf — pick exactly one variant)`);
+        if (name)
+            pctx.seen.add(name);
+        for (const variant of flat.oneOf) {
+            if (!isRecord(variant))
+                continue;
+            const variantInner = resolveSchemaRef(pctx.spec, variant) ?? variant;
+            const variantFlat = Array.isArray(variantInner.allOf) ? flattenAllOf(pctx.spec, variantInner) : variantInner;
+            const variantProps = isRecord(variantFlat.properties) ? variantFlat.properties : {};
+            const tagEntry = Object.entries(variantProps).find(([, val]) => isRecord(val) && typeof val.const === 'string');
+            const label = tagEntry
+                ? `variant "${tagEntry[1].const}"`
+                : 'variant';
+            log(pctx.ctx, `${indent}  ${label}:`);
+            printObjectFields(pctx, variantFlat, `${indent}    `, depth + 1);
+        }
+        if (name)
+            pctx.seen.delete(name);
+        return;
+    }
+    printObjectFields(pctx, flat, indent, depth);
+}
+function printObjectFields(pctx, schema, indent, depth) {
+    const expanded = Array.isArray(schema.allOf) ? flattenAllOf(pctx.spec, schema) : schema;
+    const props = isRecord(expanded.properties) ? expanded.properties : {};
+    const required = new Set(Array.isArray(expanded.required)
+        ? expanded.required.filter((k) => typeof k === 'string')
+        : []);
+    if (Object.keys(props).length === 0) {
+        log(pctx.ctx, `${indent}(no fields)`);
+        return;
+    }
+    for (const [key, raw] of Object.entries(props)) {
+        if (!isRecord(raw))
+            continue;
+        const tag = required.has(key) ? 'required' : 'optional';
+        const inlineType = schemaType(raw);
+        log(pctx.ctx, `${indent}${key} (${tag}, ${inlineType})`);
+        // Drill into nested structures one indent deeper, guarded by depth + cycle.
+        if (depth >= MAX_BODY_DEPTH)
+            continue;
+        const target = refName(raw) ?? refName(isRecord(raw.items) ? raw.items : undefined);
+        const nested = resolveSchemaRef(pctx.spec, raw) ?? raw;
+        // Array element refs: descend into the items' resolved schema.
+        const arrayItem = nested.type === 'array' && isRecord(nested.items)
+            ? (resolveSchemaRef(pctx.spec, nested.items) ?? nested.items)
+            : undefined;
+        const next = arrayItem ?? nested;
+        if (!isStructural(next))
+            continue;
+        if (target && pctx.seen.has(target)) {
+            log(pctx.ctx, `${indent}  (circular reference to ${target})`);
+            continue;
+        }
+        if (target)
+            pctx.seen.add(target);
+        printSchema(pctx, next, `${indent}  `, depth + 1);
+        if (target)
+            pctx.seen.delete(target);
+    }
+}
+function printBodySchema(ctx, spec, schema) {
+    if (!schema)
+        return;
+    printSchema({ ctx, spec, seen: new Set() }, schema, '', 0);
+}
 function requestContent(operation) {
     return Object.keys(operation.requestBody?.content ?? {});
 }
@@ -177,8 +338,40 @@ export async function openApiDescribe(ctx, target, maybePath, options) {
     if (contentTypes.length) {
         log(ctx, '');
         log(ctx, section('Request Body'));
-        for (const contentType of contentTypes)
-            log(ctx, contentType);
+        const required = operation.requestBody?.required ? ' (required)' : ' (optional)';
+        for (const contentType of contentTypes) {
+            log(ctx, `${contentType}${required}`);
+            const bodySchema = operation.requestBody?.content?.[contentType]?.schema;
+            if (!isRecord(bodySchema))
+                continue;
+            // JSON, multipart, and url-encoded bodies all surface as object schemas
+            // with `properties` once form annotations are in place; render uniformly.
+            const isStructured = contentType === 'application/json'
+                || contentType === 'multipart/form-data'
+                || contentType === 'application/x-www-form-urlencoded';
+            if (isStructured) {
+                printBodySchema(ctx, loaded.spec, bodySchema);
+            }
+        }
+    }
+    if (operation.responses && Object.keys(operation.responses).length) {
+        log(ctx, '');
+        log(ctx, section('Responses'));
+        const statuses = Object.keys(operation.responses).sort();
+        for (const status of statuses) {
+            const response = operation.responses[status];
+            const description = response?.description ? ` — ${response.description}` : '';
+            log(ctx, `${status}${description}`);
+            // Only drill the 2xx success body; error responses share a common
+            // `{errors: [{message, code}]}` envelope and just clutter the output.
+            const isSuccess = status.startsWith('2');
+            if (!isSuccess)
+                continue;
+            const successJson = response?.content?.['application/json']?.schema;
+            if (isRecord(successJson)) {
+                printBodySchema(ctx, loaded.spec, successJson);
+            }
+        }
     }
 }
 function applyPathParams(path, params) {
@@ -218,6 +411,33 @@ export async function openApiCall(ctx, target, options) {
         file: options.file,
         header: options.header,
     };
+    // Validate the JSON body against the operation's request schema first —
+    // local check, useful regardless of deployment state. Skips multipart
+    // (JSON Schema can't validate FormData) and anything not parseable as JSON.
+    if (apiOptions.body && options.validate !== false) {
+        const sourceBody = apiOptions.body.startsWith('@')
+            ? await readFile(path.resolve(apiOptions.body.slice(1)), 'utf8')
+            : apiOptions.body;
+        let parsed;
+        try {
+            parsed = JSON.parse(sourceBody);
+        }
+        catch {
+            parsed = undefined;
+        }
+        const bodySchema = operation.requestBody?.content?.['application/json']?.schema;
+        if (parsed !== undefined && bodySchema) {
+            const errors = validateBody(loaded.spec, bodySchema, parsed);
+            if (errors && errors.length) {
+                log(ctx, warning(`Request body did not match schema for ${operation.operationId}:`));
+                for (const e of errors)
+                    log(ctx, `  - ${e}`);
+                log(ctx, '');
+                log(ctx, `Pass --no-validate to skip local validation, or \`wacht api describe ${operation.operationId}\` to see the schema.`);
+                throw new Error('Validation failed.');
+            }
+        }
+    }
     const pathWithParams = appendQueryParams(applyPathParams(operation.path, params), params, operation);
     const isProjectScoped = pathWithParams.startsWith('/project') || pathWithParams === '/projects';
     let machinePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wacht/bench",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "CLI for Wacht Bench, the AI development workbench for Wacht.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "ajv": "^8.20.0",
     "commander": "^12.1.0"
   },
   "devDependencies": {