@typeship-ax/cli 0.10.0 → 0.21.0

package/src/cli.ts

@@ -21,6 +21,8 @@ import { homedir, hostname } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { TypeshipClient, formatDebugEvent, type ClientOptions, type DebugEvent } from "./index.js";
+import { asApiResult, validateAgainstSchema, ValidationError, type Violation } from "./core/http.js";
+import { SCHEMAS, DEFS } from "./schemas.js";
 import { GLOBALS, OMITTED_OPS, OPS, buildArgs, findOp, missingRequired, type OmittedOpSpec, type OpSpec, type ParamSpec } from "./ops.js";
 import {
   MCP_CLIENTS, agentGuide, agentBlock, agentInstructionsFile, agentMode, bundleProperty, claimProperty, classifyApiError, collectionProperty, detectHarness, envelope,
@@ -40,17 +42,17 @@ const BASIC: { envUser: string; envPass: string } | null = null;
 const EXCLUDED_OPS = 0;
 /** Generated CLI operations that are intentionally unavailable to MCP. */
 const MCP_EXCLUDED_OPS = 0;
-const VERSION = "0.10.0";
+const VERSION = "0.21.0";
 const API_VERSION = "1.0.0";
 const SPEC_FORMAT = "openapi";
 const IDENTITY_POLICY: IdentityPolicy = {};
 let LOGIN_IDENTITY: VerifiedIdentity | undefined;
-const WHOAMI: { resource: string; method: string } | null = {"resource":"account","method":"retrieve"};
+const WHOAMI: { resource: string; method: string } | null = null;
 const ENVIRONMENTS: Record<string, string> = {};
 const HAS_MCP = false;
 const PKG_NAME = "@typeship-ax/cli";
 const UPDATE_NOTICE = false;
-const API_DESCRIPTION: string | null = "Resolve an OpenAPI or GraphQL Definition, diagnose it, and keep every\nselected SDK, CLI, and MCP Target current.\n\nEvery operation but one requires a bearer credential: an organization\nAPI key from the console, or an OAuth access token carrying the operation's\nread, generate, or write capability and the organization selected during\nconsent. OAuth grants cannot switch organizations after consent. A browser\nsession is not a credential for this API. The exception is POST /generate,\nwhich works anonymously with the free plan's limits.\n";
+const API_DESCRIPTION: string | null = "Resolve an OpenAPI or GraphQL Spec, diagnose it, and keep every\nselected CLI, MCP, and SDK Target current.\n\nEvery operation but one requires a bearer credential: an organization\nAPI key from the console, or an OAuth access token carrying the operation's\nread, generate, or write capability and the organization selected during\nconsent. OAuth grants cannot switch organizations after consent. A browser\nsession is not a credential for this API. The exception is POST /generate,\nwhich works anonymously with the free plan's limits.\n\nExamples use Parcel, a fictional delivery service. Replace its domains,\nrepository names, and resource identifiers with your own. The hosted\npetstore Spec is a runnable sample.\n";
 const DOCS_URL_DEFAULT: string | null = "https://typeship.dev";
 const DOCS_INDEX_URL_DEFAULT: string | null = null;
 const RELAY: { mintUrl: string; project: string } | null = null;
@@ -138,7 +140,8 @@ function parseArgv(argv: string[]): Parsed {
         setFlag(arg.slice(2, eq), arg.slice(eq + 1));
       } else if (isBooleanFlag(arg.slice(2), positionals)) {
         const next = argv[i + 1];
-        if (next === "true" || next === "false") { setFlag(arg.slice(2), next); i++; }
+        const nullable = positionals.length >= 2 && findOp(positionals[0]!, positionals[1]!)?.params.some((p) => p.flag === arg.slice(2) && p.nullable);
+        if (next === "true" || next === "false" || (next === "null" && nullable)) { setFlag(arg.slice(2), next); i++; }
         else flags.set(arg.slice(2), true);
       } else {
         const next = argv[i + 1];
@@ -220,25 +223,22 @@ function out(value: unknown): void {
 let FIELDS: string[][] | null = null;
 
 /** Keep only FIELDS of a result: arrays item by item, objects by dotted path; scalars untouched. */
-function project(value: unknown): unknown {
-  if (FIELDS === null) return value;
-  if (Array.isArray(value)) return value.map(project);
+function project(value: unknown, paths: string[][] | null = FIELDS): unknown {
+  if (paths === null) return value;
+  if (Array.isArray(value)) return value.map((item) => project(item, paths));
   if (value === null || typeof value !== "object") return value;
+  const groups = new Map<string, string[][]>();
+  for (const [key, ...rest] of paths) {
+    if (key === undefined) continue;
+    const group = groups.get(key);
+    if (group) group.push(rest); else groups.set(key, [rest]);
+  }
   const out: Record<string, unknown> = {};
-  for (const path of FIELDS) {
-    let cursor: unknown = value;
-    for (const key of path) {
-      if (cursor === null || typeof cursor !== "object" || Array.isArray(cursor)) { cursor = undefined; break; }
-      cursor = (cursor as Record<string, unknown>)[key];
-    }
-    if (cursor === undefined) continue;
-    let target = out;
-    for (const key of path.slice(0, -1)) {
-      const next = target[key];
-      if (next === undefined || next === null || typeof next !== "object" || Array.isArray(next)) target[key] = {};
-      target = target[key] as Record<string, unknown>;
-    }
-    target[path[path.length - 1]!] = cursor;
+  for (const [key, rests] of groups) {
+    const child = (value as Record<string, unknown>)[key];
+    if (child === undefined) continue;
+    if (rests.some((rest) => rest.length === 0)) out[key] = child;
+    else if (child !== null && typeof child === "object") out[key] = project(child, rests);
   }
   return out;
 }
@@ -289,11 +289,23 @@ function humanError(body: ReturnType<typeof envelope>, code: number): string {
   if (detail?.violations !== undefined) {
     for (const v of (detail.violations as { path?: string; message?: string }[]).slice(0, 8)) lines.push("  " + paintErr("dim", (v.path ? v.path + ": " : "") + (v.message ?? "")));
   } else if (detail?.body !== undefined) {
-    // The API's own body, when the message above did not already come from
-    // it; the request id always, for support tickets.
-    const compact = typeof detail.body === "string" ? detail.body : JSON.stringify(detail.body);
-    const firstWords = (issue?.message ?? "").slice(0, 40);
-    if (compact && compact !== "{}" && !(firstWords && compact.includes(firstWords))) lines.push("  " + paintErr("dim", "API said: " + (compact.length > 300 ? compact.slice(0, 297) + "…" : compact)));
+    // Keep every API error and its field visible, even when the headline
+    // already used the first message. Unstructured bodies retain a summary.
+    const apiErrors = typeof detail.body === "object" && detail.body !== null
+      ? (detail.body as { errors?: unknown }).errors : undefined;
+    const entries = Array.isArray(apiErrors) ? apiErrors.filter((entry): entry is { message: string; field?: string; in?: string } =>
+      entry !== null && typeof entry === "object" && typeof entry.message === "string") : [];
+    if (entries.length > 0) {
+      for (const entry of entries) {
+        const field = typeof entry.field === "string" ? entry.field : "";
+        const location = typeof entry.in === "string" ? entry.in + " " : "";
+        lines.push("  " + paintErr("dim", (field ? location + field + ": " : "") + entry.message));
+      }
+    } else {
+      const compact = typeof detail.body === "string" ? detail.body : JSON.stringify(detail.body);
+      const firstWords = (issue?.message ?? "").slice(0, 40);
+      if (compact && compact !== "{}" && !(firstWords && compact.includes(firstWords))) lines.push("  " + paintErr("dim", "API said: " + (compact.length > 300 ? compact.slice(0, 297) + "…" : compact)));
+    }
     const requestId = detail.request_id ?? (detail.body as { request_id?: unknown; requestId?: unknown } | null)?.request_id ?? (detail.body as { requestId?: unknown } | null)?.requestId;
     if (typeof requestId === "string") lines.push("  " + paintErr("dim", "request id: " + requestId));
   }
@@ -590,7 +602,7 @@ async function startOAuthBrowserSession(parsed: Parsed, clientId: string, timeou
       audience: OAUTH_TOKEN_PARAMS.audience, resource: OAUTH_TOKEN_PARAMS.resource,
       organization: requestedLoginOrganization(parsed.flags),
     }, { signal: controller.signal, timeoutMs, authorize(url) {
-      process.stderr.write("Sign in to your existing account: " + url + "\n");
+      process.stderr.write("Sign in with your existing credentials: " + url + "\n");
       if (isAgentMode(parsed) || parsed.flags.get("no-browser") === true) process.stderr.write(JSON.stringify({ event: "oauth_browser", authorization_url: url, note: "Open this URL in a browser on the same computer as the CLI." }) + "\n");
       else openInBrowser(url);
     } });
@@ -643,7 +655,6 @@ async function cmdLogin(parsed: Parsed): Promise<void> {
       ...AUTH_SCALARS.map((a) => "  " + BIN + " login --" + a.flag + " <value>"),
       ...(CLI_AUTH_URL ? ["  " + BIN + " login                        approve in the browser: a key is minted for you (add --no-browser to print the link instead of opening it)"] : []),
       "  " + BIN + " login --with-token           read the credential from stdin (CI)",
-      "  " + BIN + " login --console-check <file> test browser login for your Typeship Console without replacing saved logins",
       ...(HAS_OAUTH_LOGIN ? ["  " + BIN + " login --client-id <id>       OAuth " + OAUTH_LOGIN_METHOD + " login" + (OAUTH_CLIENT_ID ? " (a default id is built in)" : "")] : []),
       ...(HAS_OAUTH_LOGIN ? ["  " + BIN + " login --no-browser           print the approval URL instead of opening a browser", "  " + BIN + " login --device               use device authorization when your provider supports it"] : []),
       ...(BASIC ? ["  " + BIN + " login --username <u> --password <p>"] : []),
@@ -769,7 +780,7 @@ async function cmdWhoami(parsed: Parsed): Promise<void> {
   if (op) {
     const client = await makeClient(parsed.flags, op);
     const target = (client as unknown as Record<string, Record<string, () => Promise<{ ok: boolean; data?: unknown; error?: unknown }>>>)[op.resource]!;
-    const result = await target[op.method]!();
+    const result = await asApiResult(target[op.method]!());
     if (result.ok) { out(result.data ?? { ok: true }); await flushExit(0); }
     failApi(result.error, LAST_CLIENT_HAD_CREDENTIAL);
   }
@@ -940,12 +951,11 @@ async function cmdMcp(parsed: Parsed): Promise<void> {
       "  " + BIN + " mcp install --codex          Codex CLI (~/.codex/config.toml)",
       "  " + BIN + " mcp install --vscode         VS Code (./.vscode/mcp.json)",
       "  " + BIN + " mcp install --windsurf | --gemini | --opencode | --zed | --claude-desktop",
-      "  " + BIN + " mcp install --cursor         Cursor (./.cursor/mcp.json; see note below)",
+      "  " + BIN + " mcp install --cursor         Cursor (./.cursor/mcp.json)",
       "  " + BIN + " mcp --url <https://...>      use a remote MCP endpoint instead of the local server",
       "  " + BIN + " mcp install --claude --read-only   register a read-only server (writes are not callable)",
       "",
       (MCP_URL ? "Default entry: the hosted endpoint " + MCP_URL + " with the auth env var as a reference (never a literal key)." : "Default entry: this package's local stdio server, which reads credentials saved by '" + BIN + " login' or the CLI's auth env vars."),
-      "--all skips Cursor until it speaks MCP 2026-07-28.",
     ];
     process.stdout.write(lines.join("\n") + "\n");
     await flushExit(0);
@@ -1040,7 +1050,7 @@ function commandSummaries(): CommandSummary[] {
     paginated: op.paginated,
     destructive: op.safety === "destructive",
     auth: op.auth,
-    flags: op.params.filter((p) => p.kind !== "path").map((p) => ({ flag: p.flag, type: p.type, ...(p.items ? { items: p.items } : {}), ...(p.enum ? { enum: p.enum } : {}), required: p.required, ...(p.description ? { description: p.description.split("\n")[0] } : {}) })),
+    flags: op.params.filter((p) => p.kind !== "path").map((p) => ({ flag: p.flag, type: p.type, ...(p.nullable ? { nullable: true } : {}), ...(p.items ? { items: p.items } : {}), ...(p.enum ? { enum: p.enum } : {}), required: p.required, ...(p.description ? { description: p.description.split("\n")[0] } : {}) })),
   }));
 }
 
@@ -1164,7 +1174,7 @@ async function cmdAuth(parsed: Parsed): Promise<void> {
     if (op) {
       const client = await makeClient(parsed.flags, op);
       const target = (client as unknown as Record<string, Record<string, () => Promise<{ ok: boolean; data?: unknown; error?: unknown }>>>)[op.resource]!;
-      const result = await target[op.method]!();
+      const result = await asApiResult(target[op.method]!());
       if (result.ok) {
         if (identityConfiguration() && savedIdentity?.identity) assertApiIdentity(savedIdentity.identity.values, readApiIdentity(result.data, IDENTITY_POLICY));
         report.identity = result.data;
@@ -1188,7 +1198,7 @@ async function cmdDoctor(parsed: Parsed): Promise<void> {
   }
   const checks: DoctorCheck[] = [];
   const nodeMajor = Number(process.versions.node.split(".")[0]);
-  checks.push({ name: "node", ok: nodeMajor >= 18, detail: process.version, ...(nodeMajor >= 18 ? {} : { fix: "Install Node 18 or newer." }) });
+  checks.push({ name: "node", ok: nodeMajor >= 20, detail: process.version, ...(nodeMajor >= 20 ? {} : { fix: "Install Node 20 or newer." }) });
   checks.push({ name: "cli", ok: true, detail: BIN + " " + VERSION + " (" + PKG_NAME + ")" });
   let source: string | null = null;
   let storageProblem: string | undefined;
@@ -1212,7 +1222,7 @@ async function cmdDoctor(parsed: Parsed): Promise<void> {
       try {
         const client = await makeClient(parsed.flags, op);
         const target = (client as unknown as Record<string, Record<string, () => Promise<{ ok: boolean; error?: unknown }>>>)[op.resource]!;
-        const result = await target[op.method]!();
+        const result = await asApiResult(target[op.method]!());
         checks.push(result.ok ? { name: "identity", ok: true, detail: op.command.join(" ") + " ok" } : { name: "identity", ok: false, detail: classifyApiError(result.error, { bin: BIN, hadCredential: true, docsUrl: DOCS_URL_DEFAULT }).message, fix: "The credential was rejected; run '" + BIN + " login' with a current one." });
       } catch (e) {
         checks.push({ name: "identity", ok: false, detail: (e as Error).message });
@@ -1241,7 +1251,7 @@ async function cmdDoctor(parsed: Parsed): Promise<void> {
  * init: the one command that connects a machine (or a repo) to this API.
  * Stores a credential when given one, installs the skills repository, writes
  * MCP config for every agent client found, and upserts a marked block into
- * AGENTS.md (CLAUDE.md under Claude Code). Idempotent; --all takes the
+ * AGENTS.md (or an existing CLAUDE.md when AGENTS.md is absent). Idempotent; --all takes the
  * defaults without asking; every part reports and none of them fails init.
  */
 async function cmdInit(parsed: Parsed): Promise<void> {
@@ -1253,7 +1263,7 @@ async function cmdInit(parsed: Parsed): Promise<void> {
       "  --all                    do everything without prompting (implied under an agent)",
       "  --no-skills | --no-mcp | --no-agents-md   skip a part",
       "",
-      "Writes: " + credsPath() + " (credential), the skills directory of each agent on this machine" + (SKILLS_REPO ? " (npx skills add " + SKILLS_REPO + ")" : " (no skills repository configured)") + ", MCP config for detected clients, and a '" + BIN + "' block in ./AGENTS.md.",
+      "Writes: " + credsPath() + " (credential), the skills directory of each agent on this machine" + (SKILLS_REPO ? " (npx skills add " + SKILLS_REPO + ")" : " (no skills repository configured)") + ", MCP config for detected clients, and a '" + BIN + "' block in ./AGENTS.md (or an existing ./CLAUDE.md when AGENTS.md is absent).",
     ].join("\n") + "\n");
     await flushExit(0);
   }
@@ -1316,7 +1326,7 @@ async function cmdInit(parsed: Parsed): Promise<void> {
   if (parsed.flags.get("no-agents-md") === true) {
     report.agents_md = { status: "skipped" };
   } else {
-    const file = agentInstructionsFile(cwd, harness);
+    const file = agentInstructionsFile(cwd);
     const result = upsertAgentBlock(file, BIN + " agent-contract", agentBlock(agentContext(), commandSummaries()));
     report.agents_md = { status: result.updated ? "updated" : "written", file: result.file };
   }
@@ -1803,6 +1813,8 @@ async function cmdDocs(parsed: Parsed): Promise<void> {
 
 
 
+
+
 /** The command that fetches the next page: same positionals, the next page's query flags. */
 function nextCommandFor(op: OpSpec, pathValues: string[], next: Record<string, unknown>): string {
   const parts = [BIN, op.command[0], op.command[1], ...pathValues.map(shellQuote)];
@@ -1869,6 +1881,7 @@ function helpSentence(description: string | undefined): string {
 
 /** Type column text for a param: string, number, string[], a|b|c, enum, object, json, path. */
 function typeLabel(p: ParamSpec): string {
+  if (p.nullable) return typeLabel({ ...p, nullable: false }) + "|null";
   if (p.type === "file") return "path (uploaded)";
   if (p.format && p.type === "string") return p.format;
   const inlineEnum = (values: string[] | undefined) => values && values.join("|").length <= 24 ? values.join("|") : undefined;
@@ -1944,7 +1957,7 @@ function printRoot(stream: NodeJS.WriteStream = process.stdout): void {
   }
   const width = termWidth();
   const lines: string[] = [];
-  lines.push(paintOut("bold", BIN) + ": " + "typeship API" + " (v" + "1.0.0" + "), package " + "0.10.0");
+  lines.push(paintOut("bold", BIN) + ": " + "typeship API" + " (v" + "1.0.0" + "), package " + "0.21.0");
   lines.push("");
   lines.push(paintOut("bold", "Usage:") + " " + BIN + " <resource> <command> [args] [--flags]");
   lines.push("");
@@ -1968,7 +1981,7 @@ function printRoot(stream: NodeJS.WriteStream = process.stdout): void {
     lines.push(...labeled("Upgrade: ", "https://typeship.dev/pricing, then regenerate without the operation cap", width, 14));
   }
   lines.push("");
-  const flagsText = "-v/--version, -h/--help, --debug, --non-interactive, --color on|off|auto, --base-url <url>, --profile <name>, --credentials @<file>|-, --data '<json>', --fields <a,b.c>, --all (paginated lists), --validate (schema-check bodies)" +
+  const flagsText = "-v/--version, -h/--help, --debug, --non-interactive, --color on|off|auto, --base-url <url>, --profile <name>, --credentials @<file>|-, --data '<json>', --fields <a,b.c>, --all (paginated lists), --validate (schema-check parameters and JSON bodies)" +
     (AUTH_SCALARS.length > 0 ? ", " + AUTH_SCALARS.map((a) => "--" + a.flag + " <value>").join(", ") : "");
   lines.push(...labeled(paintOut("bold", "Global flags:") + " ", flagsText, width, 14).map((l, i) => (i === 0 ? l : l)));
   lines.push(...labeled("Credential env vars: ", [
@@ -1976,11 +1989,12 @@ function printRoot(stream: NodeJS.WriteStream = process.stdout): void {
     ...(BASIC ? [BASIC.envUser, BASIC.envPass] : []),
   ].join(", ") || "none", width, 21));
   lines.push(...labeled("Endpoint env var: ", "TYPESHIP_BASE_URL", width, 18));
-  lines.push(...labeled("Account: ", BIN + " login | logout | whoami | auth check  (stored at " + credsPath() + ")", width, 9));
+  lines.push(...labeled("Sign-in: ", BIN + " login | logout | whoami | auth check  (stored at " + credsPath() + ")", width, 9));
   lines.push(...labeled("Setup: ", BIN + " init (connect this machine)" + " | " + BIN + " config (defaults)" + (HAS_MCP || MCP_URL ? " | " + BIN + " mcp install --all (agent clients)" : "") + " | " + BIN + " doctor | " + BIN + " upgrade | " + BIN + " completion <shell>", width, 7));
   lines.push(...labeled("Agents: ", BIN + " agent-guide | " + BIN + " help --json | --mode agent | -y/--yes/--force | --out <dir>  (JSON errors: {status, issues[{code}], next_steps})", width, 8));
   lines.push(...labeled("Docs: ", BIN + " docs [<resource> <command> | search <term> | read <page> | --web]", width, 6));
   if (RELAY) lines.push("Webhooks: " + BIN + " webhooks listen --forward-to <url>  (local event forwarding)");
+
   if (SUPPORT_URL) lines.push("Feedback: " + BIN + " feedback  (opens the provider's issue tracker)");
   if (MCP_EXCLUDED_OPS > 0 && HAS_MCP) {
     lines.push("");
@@ -2021,16 +2035,17 @@ function commandExtras(op: OpSpec): [string, string][] {
   if (op.paginated) extras.push(["--all", "stream every item from every page (NDJSON)"]);
   const collectionField = collectionProperty(op.outputSchema);
   extras.push(["--fields <a,b.c>", "keep only these fields of the result" + (op.paginated ? " (per item)" : collectionField ? " (per item in " + collectionField + ")" : "")]);
-  if (bundleProperty(op.outputSchema) !== null) extras.push(["--out <dir>", "write the response's files ({path, content}) into a directory"]);
+  if ((op.fileBundleProperty ?? bundleProperty(op.outputSchema)) !== null) extras.push(["--out <dir>", "write the response's files ({path, content}) into a directory"]);
   if (op.safety === "destructive") extras.push(["--force, -y", "destructive: required without a terminal, skips the prompt with one"]);
   return extras;
 }
 
-/** One runnable example built from the required inputs. */
+/** One runnable example from required inputs and authored optional values. */
 function exampleLine(op: OpSpec): string {
   const parts = [BIN, op.command[0], op.command[1]];
   for (const p of op.params) {
-    if (!p.required) continue;
+    const hasExample = p.type !== "file" && Object.hasOwn(op.exampleArguments, p.name);
+    if (!p.required && !hasExample) continue;
     const generated = p.type === "file" ? undefined : op.exampleArguments[p.name];
     const values = p.type === "array" ? p.items?.enum : p.enum;
     const fallback: unknown = p.type === "file" ? "./file"
@@ -2040,17 +2055,18 @@ function exampleLine(op: OpSpec): string {
       : p.type === "object" ? {}
       : p.type === "array" ? [p.items?.type === "number" ? 1 : "value"]
       : "value";
-    const value = generated ?? fallback;
+    const value = hasExample ? generated : fallback;
     const sample = typeof value === "string" ? shellQuote(value)
       : typeof value === "object" ? shellQuote(JSON.stringify(value))
       : String(value);
     if (p.kind === "path") parts.push(sample);
     else parts.push("--" + p.flag, sample);
   }
-  const required = op.bodyStyle === "data" && ((op.inputSchema.required as string[] | undefined) ?? []).includes("body");
-  if (required) {
-    const body = op.exampleArguments.body;
-    parts.push(op.bodyKind === "binary" ? "--file ./file" : "--data " + shellQuote(JSON.stringify(body ?? {})));
+  const showBody = op.bodyStyle === "data" && (Object.hasOwn(op.exampleArguments, "body")
+    || ((op.inputSchema.required as string[] | undefined) ?? []).includes("body"));
+  if (showBody) {
+    const body = Object.hasOwn(op.exampleArguments, "body") ? op.exampleArguments.body : {};
+    parts.push(op.bodyKind === "binary" ? "--file ./file" : "--data " + shellQuote(JSON.stringify(body)));
   }
   if (op.safety === "destructive") parts.push("--force");
   return parts.join(" ");
@@ -2079,6 +2095,9 @@ function printOp(op: OpSpec): void {
   lines.push("  " + exampleLine(op));
   if (op.paginated) lines.push("  " + usageLine(op) + " --all | jq -r '.id'");
   const arrayFlag = rows.find((p) => p.type === "array");
+  if (rows.some((p) => p.nullable)) {
+    lines.push("", "Nullable body flags accept null for JSON null. Use --data to send the literal string null.");
+  }
   if (arrayFlag) {
     const sample = arrayFlag.items?.enum ? arrayFlag.items.enum.slice(0, 2).join(",") : arrayFlag.items?.type === "number" ? "1,2" : "a,b";
     lines.push("", "Array flags take a comma list (--" + arrayFlag.flag + " " + sample + "), the flag repeated, or a JSON array.");
@@ -2160,6 +2179,7 @@ function coerceScalar(flag: string, type: "string" | "number" | "boolean" | "obj
  * Objects must be JSON. Enum values are checked locally.
  */
 function coerce(spec: ParamSpec, raw: string | boolean, repeated?: string[]): unknown {
+  if (spec.nullable && raw === "null" && repeated === undefined) return null;
   if (spec.type === "file") {
     if (raw === true) fail(2, "--" + spec.flag + " expects a file path");
     return fileFromPath(spec.flag, String(raw));
@@ -2207,9 +2227,60 @@ function coerce(spec: ParamSpec, raw: string | boolean, repeated?: string[]): un
   return coerceScalar(spec.flag, spec.type === "json" ? "json" : spec.type === "number" ? "number" : "string", spec.enum, text);
 }
 
+/** Use validation schemas, not the shortened agent-facing schemas: every union
+ * branch and referenced definition must remain valid input. */
+function validateParameters(op: OpSpec, values: Record<string, unknown>, flags: Map<string, string | boolean>): void {
+  if (flags.get("validate") !== true) return;
+  const schemas = SCHEMAS[op.resource + "." + op.method]?.params;
+  if (!schemas) return;
+  const violations: Violation[] = [];
+  for (const parameter of op.params) {
+    if (parameter.kind === "body") continue;
+    let value = values[parameter.name];
+    if (value === undefined && parameter.global) {
+      const global = GLOBALS.find((entry) => entry.name === parameter.name);
+      const raw = global ? process.env["TYPESHIP_" + global.envSuffix] : undefined;
+      if (raw !== undefined) value = coerce(parameter, raw);
+    }
+    if (value === undefined) continue;
+    if (parameter.kind === "path") value = coerce(parameter, String(value));
+    const key = parameter.kind + "." + parameter.name;
+    validateAgainstSchema(value, schemas[key], key, violations, DEFS);
+  }
+  if (violations.length) failApi(new ValidationError("request", violations, "parameters"), false);
+}
+
 /** Whether the last client built carried any credential; failApi tells NO_AUTH from AUTH_INVALID with it. */
 let LAST_CLIENT_HAD_CREDENTIAL = false;
 
+/** Check the same complete alternatives the request runtime can select, after
+ * per-scheme flag, environment, profile, and OAuth resolution. */
+function requireOperationCredentials(op: OpSpec, options: ClientOptions & Record<string, unknown>): void {
+  if (op.auth !== "required") return;
+  const supplied = (value: unknown): boolean => typeof value === "function" || (typeof value === "string" && value.length > 0)
+    || (value !== null && typeof value === "object" && "username" in value && "password" in value && typeof value.username === "string" && value.username.length > 0 && typeof value.password === "string" && value.password.length > 0);
+  const named = Object.fromEntries(Object.entries(options.credentials ?? {}).filter(([, value]) => supplied(value))) as NamedCredentials;
+  const available = namedCredentialAvailability(NAMED_SCHEMES, new Set(Object.keys(options).filter((key) => supplied(options[key]))), named);
+  if (op.credentialOptions?.some((alternative) => alternative.length > 0 && alternative.every((option) => available.has(option)))) return;
+  const alternatives = (op.credentialOptions ?? []).filter((alternative) => alternative.length > 0 && alternative.every((option) => option.startsWith("credentials.")));
+  const missing = alternatives.map((alternative) => alternative.filter((option) => !available.has(option)).map((option) => option.slice("credentials.".length)));
+  const names = new Set(missing.flat());
+  const relevant = AUTH_SCALARS.filter((scalar) => [...names].some((name) => NAMED_SCHEMES[name]?.options.includes(scalar.option)));
+  const needsBasic = [...names].some((name) => NAMED_SCHEMES[name]?.options.includes("basicAuth"));
+  failWith({
+    status: "action_required",
+    code: "NO_AUTH",
+    message: op.command.join(" ") + " needs one complete credential alternative (" + wireOf(op) + "). " + (missing.length
+      ? "Missing security schemes: " + missing.map((names) => names.join(" + ")).join(" OR ") + "."
+      : "The declared security requirements have no supported, compatible alternative in this CLI."),
+    nextSteps: alternatives.length ? [
+      ...relevant.map((a) => "Set " + a.env + " in the environment, pass --" + a.flag + " <value>, or run '" + BIN + " login'."),
+      ...(needsBasic && BASIC ? ["Set " + BASIC.envUser + " and " + BASIC.envPass + ", or pass --username and --password."] : []),
+      "Supply all schemes in one alternative through " + "TYPESHIP_CREDENTIALS" + " or --credentials @<JSON-file>: " + alternatives.map((alternative) => alternative.map((option) => option.slice("credentials.".length)).join(" + ")).join(" OR ") + ".",
+    ] : ["Check the operation's security schemes in the API Spec and regenerate with a supported, compatible alternative."],
+  });
+}
+
 function validateCredentialsInput(flags: Map<string, string | boolean>): void {
   const input = flags.get("credentials");
   if (BASIC && flags.has("username") !== flags.has("password")) fail(2, "Supply --username and --password together, or use a complete named Basic credential.");
@@ -2317,18 +2388,17 @@ async function makeClient(flags: Map<string, string | boolean>, op: OpSpec, cand
     if (value !== undefined) options[g.option] = value;
   }
   LAST_CLIENT_HAD_CREDENTIAL = Object.keys(options.credentials ?? {}).length > 0 || AUTH_SCALARS.some((a) => options[a.option] !== undefined) || options.basicAuth !== undefined || options.bearerToken !== undefined;
-  // Who is calling: the CLI, under which agent harness, and whether an
-  // agent is driving. "agent" means a harness was detected or the caller
-  // said so (--mode agent / env); a bare non-TTY run (CI, a pipeline) is
-  // "non-interactive", so usage by surface does not count CI as agents.
-  // The API can read it back; it carries no secrets.
+  requireOperationCredentials(op, options);
+  // Identify the package and version. Optional harness and caller details
+  // let the API distinguish agent traffic from other non-interactive use.
   const harness = detectHarness();
   const explicitAgent = flags.get("mode") === "agent" || process.env["TYPESHIP_MODE"] === "agent";
   const behaving = agentMode({ flagMode: flags.get("mode"), envMode: process.env["TYPESHIP_MODE"], stdoutIsTTY: process.stdout.isTTY === true, stdinIsTTY: process.stdin.isTTY === true });
-  const caller = harness || explicitAgent ? "; agent" : behaving ? "; non-interactive" : "";
+  const caller = harness || explicitAgent ? "agent" : behaving ? "non-interactive" : null;
+  const details = [harness ? "harness=" + harness : null, caller].filter(Boolean).join("; ");
   options.defaultHeaders = {
     ...(options.defaultHeaders as Record<string, string> | undefined),
-    "User-Agent": PKG_NAME + "-cli/" + VERSION + " (typeship" + (harness ? "; harness=" + harness : "") + caller + ")",
+    "User-Agent": PKG_NAME + "-cli/" + VERSION + (details ? " (" + details + ")" : ""),
   };
   if (forIdentity) { options.fetch = identityFetch(baseUrl); options.maxRetries = 0; options.timeoutMs = 10_000; }
   return new TypeshipClient(options);
@@ -2368,7 +2438,7 @@ function failOmitted(op: OmittedOpSpec): never {
   return failWith({
     status: "action_required",
     code: "PLAN_LIMIT",
-    message: "The command '" + BIN + " " + op.command.join(" ") + "' exists in the API Definition but was omitted from this generated package by its plan limit.",
+    message: "The command '" + BIN + " " + op.command.join(" ") + "' exists in the API Spec but was omitted from this generated package by its plan limit.",
     detail: { operation: op.tool, method: op.httpMethod, path: op.path, generated_operations: OPS.length, total_operations: OPS.length + EXCLUDED_OPS },
     nextSteps: ["Upgrade at https://typeship.dev/pricing and regenerate the package without the operation cap.", "Do not invent or retry an omitted command against this generated package."],
   });
@@ -2393,8 +2463,8 @@ async function main(): Promise<void> {
     fail(2, "--format json is the only format; output is always JSON.");
   }
   if (parsed.flags.has("version") || parsed.positionals[0] === "version") {
-    // "typeship 1.0.0 (typeship 1.0.0, ...)" said the name three times; when
-    // the API's title is the bin, name the API version as such.
+    // "acme 1.0.0 (acme 1.0.0)" would say the name twice; when the API's
+    // title is the bin, name the API version as such.
     const apiLabel = API_TITLE.toLowerCase().replace(/[^a-z0-9]/g, "") === BIN.toLowerCase().replace(/[^a-z0-9]/g, "") ? "API " + API_VERSION : API_TITLE + " " + API_VERSION;
     process.stdout.write(BIN + " " + VERSION + " (" + apiLabel + ", generated by typeship)\n");
     await flushExit(0);
@@ -2415,6 +2485,7 @@ async function main(): Promise<void> {
   if (resourceCmd === "upgrade") { await cmdUpgrade(parsed); }
 
 
+
   if (resourceCmd === "docs") { await cmdDocs(parsed); }
   if (resourceCmd === "completion") { await cmdCompletion(parsed); }
   if (resourceCmd === "config") { await cmdConfig(parsed); }
@@ -2532,28 +2603,15 @@ async function main(): Promise<void> {
   }
 
   // --out <dir> materializes a file-shaped response (see cli-agent.ts bundleProperty).
-  const bundleField = bundleProperty(op.outputSchema);
+  const bundleField = op.fileBundleProperty ?? bundleProperty(op.outputSchema);
   const collectionField = collectionProperty(op.outputSchema);
   const outDir = typeof parsed.flags.get("out") === "string" ? (parsed.flags.get("out") as string) : undefined;
   if (outDir !== undefined && bundleField === null) {
     fail(2, "--out applies to commands whose response carries files ({path, content}); " + op.command.join(" ") + " does not.");
   }
 
-  // The spec says this operation needs a credential and none resolved:
-  // say so now, locally, instead of sending a request to learn it.
-  if (op.auth === "required" && (AUTH_SCALARS.length > 0 || BASIC || HAS_OAUTH_LOGIN) && credentialSource(parsed.flags) === null) {
-    failWith({
-      status: "action_required",
-      code: "NO_AUTH",
-      message: op.command.join(" ") + " needs a credential (" + wireOf(op) + " is authenticated) and none was found.",
-      nextSteps: [
-        ...AUTH_SCALARS.map((a) => "Set " + a.env + " in the environment, pass --" + a.flag + " <value>, or run '" + BIN + " login'."),
-        ...(BASIC ? ["Set " + BASIC.envUser + " and " + BASIC.envPass + ", or pass --username and --password."] : []),
-        ...(AUTH_SCALARS.length === 0 && !BASIC ? ["Run '" + BIN + " login'."] : []),
-        "'" + BIN + " auth check' shows what the CLI would send.",
-      ],
-    });
-  }
+  validateParameters(op, values, parsed.flags);
+  const client = await makeClient(parsed.flags, op);
 
   // Destructive commands need --force. A person gets asked; an agent gets
   // an action_required envelope with the exact command to run, so nothing
@@ -2573,7 +2631,6 @@ async function main(): Promise<void> {
     if (answer !== "y" && answer !== "yes") failWith({ status: "action_required", code: "CONFIRMATION_REQUIRED", message: "Cancelled.", nextSteps: ["Run again with --force to skip the prompt: " + rerun] });
   }
 
-  const client = await makeClient(parsed.flags, op);
   const selectValue = typeof parsed.flags.get("select") === "string" ? (parsed.flags.get("select") as string) : undefined;
   const args = buildArgs(op, values, dataBody, selectValue);
   const target = (client as unknown as Record<string, Record<string, (...a: unknown[]) => unknown>>)[op.resource]!;
@@ -2590,7 +2647,18 @@ async function main(): Promise<void> {
     }
   }
 
-  const result = await (callResult as Promise<{ ok: boolean; data?: unknown; error?: unknown; response?: { requestId?: string } }>);
+  let result = await asApiResult(callResult as Promise<unknown>);
+  if (result.ok && op.httpMethod === "POST" && op.path === "/projects/{project_id}/generate") {
+    const batch = result.data as { data: Array<{ id: string }> };
+    const generations = (client as unknown as { generations: { wait(id: string): Promise<unknown> } }).generations;
+    const completed: unknown[] = [];
+    for (const generation of batch.data) {
+      const waited = await asApiResult(generations.wait(generation.id));
+      if (!waited.ok) failApi(waited.error, LAST_CLIENT_HAD_CREDENTIAL);
+      completed.push(waited.data);
+    }
+    result = { ...result, data: { ...batch, data: completed } };
+  }
   if (result.ok) {
     if (op.sse) {
       // Server-sent events as NDJSON, one line per event, until the stream ends.