@warmhub/cli 0.62.0 → 0.63.0

package/dist/wh.js

@@ -27353,7 +27353,7 @@ function findSystemComponent(componentId) {
 // ../../packages/sdk-ts/package.json
 var package_default = {
   name: "@warmhub/sdk-ts",
-  version: "0.62.0",
+  version: "0.62.1",
   private: false,
   type: "module",
   description: "The TypeScript SDK for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -27439,6 +27439,7 @@ var package_default = {
     "@trpc/client": "11.17.0"
   },
   devDependencies: {
+    "@trpc/server": "11.17.0",
     "@vitest/coverage-v8": "catalog:",
     "@warmhub/backend": "workspace:*",
     "@warmhub/rules": "workspace:*",
@@ -27697,6 +27698,14 @@ function resolveRetryPolicy(retry) {
   };
 }
 var DEFINITE_CLIENT_REJECT_CODES = new Set([
+  "BAD_REQUEST",
+  "METHOD_NOT_SUPPORTED",
+  "PARSE_ERROR",
+  "PAYLOAD_TOO_LARGE",
+  "PRECONDITION_FAILED",
+  "UNAUTHORIZED",
+  "UNPROCESSABLE_CONTENT",
+  "UNSUPPORTED_MEDIA_TYPE",
   "UNAUTHENTICATED",
   "FORBIDDEN",
   "VALIDATION_ERROR",
@@ -27709,6 +27718,7 @@ var DEFINITE_CLIENT_REJECT_CODES = new Set([
   "ALREADY_RETRACTED",
   "ARCHIVED",
   "RATE_LIMITED",
+  "TOO_MANY_REQUESTS",
   "UNRESOLVED_TOKEN"
 ]);
 function extractErrorCode(cause) {
@@ -27726,9 +27736,24 @@ function extractErrorCode(cause) {
     return dc;
   return;
 }
+function extractHttpStatus(cause) {
+  if (!cause || typeof cause !== "object")
+    return;
+  const status = cause.data?.httpStatus;
+  if (typeof status === "number")
+    return status;
+  const warmhubStatus = cause.data?.warmhub?.status;
+  if (typeof warmhubStatus === "number")
+    return warmhubStatus;
+  const direct = cause.status;
+  return typeof direct === "number" ? direct : undefined;
+}
+function isDefiniteClientRejectionStatus(status) {
+  return status !== undefined && status >= 400 && status < 500 && status !== 408;
+}
 function isDefiniteClientError(cause) {
   const code = extractErrorCode(cause);
-  return code !== undefined && DEFINITE_CLIENT_REJECT_CODES.has(code);
+  return code !== undefined && DEFINITE_CLIENT_REJECT_CODES.has(code) || isDefiniteClientRejectionStatus(extractHttpStatus(cause));
 }
 function isTransientStreamFailure(cause) {
   if (isDefiniteClientError(cause))
@@ -28075,6 +28100,48 @@ function sanitizeSubscriptionUpdateInput(input) {
   } = input;
   return supported;
 }
+function trpcClientCodeToWarmHubCode(code) {
+  switch (code) {
+    case "BAD_REQUEST":
+    case "PARSE_ERROR":
+    case "PAYLOAD_TOO_LARGE":
+    case "UNPROCESSABLE_CONTENT":
+    case "UNSUPPORTED_MEDIA_TYPE":
+      return "VALIDATION_ERROR";
+    case "METHOD_NOT_SUPPORTED":
+      return "NOT_FOUND";
+    case "UNAUTHORIZED":
+      return "UNAUTHENTICATED";
+    case "FORBIDDEN":
+      return "FORBIDDEN";
+    case "NOT_FOUND":
+      return "NOT_FOUND";
+    case "CONFLICT":
+      return "CONFLICT";
+    case "PRECONDITION_FAILED":
+      return "PRECONDITION_FAILED";
+    case "TOO_MANY_REQUESTS":
+      return "RATE_LIMITED";
+    default:
+      return;
+  }
+}
+function trpcHttpStatusToWarmHubCode(status) {
+  if (status === undefined || status === 408)
+    return;
+  if (status === 405)
+    return "NOT_FOUND";
+  if (status === 412)
+    return "PRECONDITION_FAILED";
+  if (status === 422)
+    return "VALIDATION_ERROR";
+  const mapped = httpStatusToWarmHubCode(status);
+  if (mapped !== "BACKEND")
+    return mapped;
+  if (status >= 400 && status < 500)
+    return "VALIDATION_ERROR";
+  return mapped;
+}
 var INTERNAL_PATTERNS = [
   /\bselect\b.+?\bfrom\b/i,
   /\binsert\b.+?\binto\b/i,
@@ -28136,8 +28203,10 @@ function toWarmHubError(error) {
     }
     const data = error.data;
     const wireCode = data?.warmhub?.code;
+    const trpcCode = typeof data?.code === "string" ? trpcClientCodeToWarmHubCode(data.code) : undefined;
+    const trpcStatus = trpcHttpStatusToWarmHubCode(data?.httpStatus);
     const message = data?.warmhub?.message ?? sanitizeErrorMessage(error.message);
-    return new WarmHubError(wireCode ?? "BACKEND", message, data?.warmhub?.status, data?.warmhub?.hint, data?.warmhub?.retryAfter, wireCode, data?.warmhub?.details);
+    return new WarmHubError(wireCode ?? trpcCode ?? trpcStatus ?? "BACKEND", message, data?.warmhub?.status ?? data?.httpStatus, data?.warmhub?.hint, data?.warmhub?.retryAfter ?? data?.retryAfter, wireCode, data?.warmhub?.details);
   }
   if (error instanceof Error) {
     const warmhubLike = error;
@@ -30576,7 +30645,12 @@ function parseArgs(argv) {
     positionals.push(arg);
     i += 1;
   }
-  return { positionals, flags, ...terminator ? { terminator } : {} };
+  return {
+    positionals,
+    flags,
+    ...terminator ? { terminator } : {},
+    rawArgv: [...argv]
+  };
 }
 function getStringFlag(flags, ...keys) {
   for (const key of keys) {
@@ -30598,8 +30672,9 @@ function getBoolFlag(flags, ...keys) {
 function getNumberFlag(flags, ...keys) {
   for (const key of keys) {
     const val = flags[key];
-    if (typeof val === "string") {
-      const num = Number(val);
+    const scalar = Array.isArray(val) ? val[val.length - 1] : val;
+    if (typeof scalar === "string") {
+      const num = Number(scalar);
       if (!Number.isNaN(num))
         return num;
     }
@@ -31448,10 +31523,21 @@ function writeStore(store, path) {
     }
   }
 }
+function hasProfile(store, name) {
+  return Object.hasOwn(store.profiles, name);
+}
+function setProfile(store, name, profile) {
+  Object.defineProperty(store.profiles, name, {
+    value: profile,
+    enumerable: true,
+    configurable: true,
+    writable: true
+  });
+}
 function saveProfile(name, profile, path) {
   const p = path ?? getAuthPath();
   const store = loadProfileStore(p);
-  store.profiles[name] = profile;
+  setProfile(store, name, profile);
   writeStore(store, p);
 }
 function saveProfileWhileLocked(name, profile, path) {
@@ -31460,7 +31546,7 @@ function saveProfileWhileLocked(name, profile, path) {
 function getProfile(name, path) {
   const p = path ?? getAuthPath();
   const store = loadProfileStore(p);
-  return store.profiles[name] ?? null;
+  return hasProfile(store, name) ? store.profiles[name] : null;
 }
 async function modifyStore(mutator, path) {
   const p = path ?? getAuthPath();
@@ -31473,12 +31559,12 @@ async function modifyStore(mutator, path) {
 }
 async function saveProfileLocked(name, profile, path) {
   await modifyStore((store) => {
-    store.profiles[name] = profile;
+    setProfile(store, name, profile);
   }, path);
 }
 async function deleteProfileLocked(name, path) {
   await modifyStore((store) => {
-    if (!(name in store.profiles))
+    if (!hasProfile(store, name))
       return;
     delete store.profiles[name];
   }, path);
@@ -31714,8 +31800,52 @@ var package_default2 = {
   }
 };
 
+// ../../packages/warmhub-cli/src/cli-trace-context.ts
+import { randomBytes } from "node:crypto";
+var TRACE_VERSION = "00";
+var TRACE_FLAGS_SAMPLED = "01";
+var activeTrace;
+function randomHex(byteLength) {
+  let value = "";
+  do {
+    value = randomBytes(byteLength).toString("hex");
+  } while (/^0+$/.test(value));
+  return value;
+}
+function createTraceContext() {
+  return {
+    traceId: randomHex(16),
+    rootSpanId: randomHex(8)
+  };
+}
+function startCliTraceContext() {
+  activeTrace = createTraceContext();
+  return activeTrace;
+}
+function getCliTraceContext() {
+  activeTrace ??= createTraceContext();
+  return activeTrace;
+}
+function cliTraceLogFields() {
+  const trace = getCliTraceContext();
+  return {
+    traceId: trace.traceId,
+    spanId: trace.rootSpanId
+  };
+}
+function createCliTraceparent() {
+  const trace = getCliTraceContext();
+  return [
+    TRACE_VERSION,
+    trace.traceId,
+    trace.rootSpanId,
+    TRACE_FLAGS_SAMPLED
+  ].join("-");
+}
+
 // ../../packages/warmhub-cli/src/client.ts
 var BENCHMARK_HEADER = "x-warmhub-benchmark-id";
+var TRACEPARENT_HEADER = "traceparent";
 var REQUEST_TOTAL_MS_HEADER = "x-warmhub-request-total-ms";
 var REQUEST_DB_QUERY_COUNT_HEADER = "x-warmhub-request-db-query-count";
 var benchmarkTelemetry = emptyBenchmarkTelemetry();
@@ -31753,10 +31883,9 @@ function recordBenchmarkResponse(response, benchmarkId) {
   }
 }
 function createBenchmarkAwareFetch(benchmarkId, signal) {
-  if (!benchmarkId && !signal)
-    return;
   return async (input, init) => {
     const headers = new Headers(init?.headers);
+    headers.set(TRACEPARENT_HEADER, createCliTraceparent());
     if (benchmarkId)
       headers.set(BENCHMARK_HEADER, benchmarkId);
     const response = await fetch(input, {
@@ -31812,6 +31941,15 @@ function createClient(config, opts = {}) {
     client: cliClientIdentity()
   });
 }
+function createUnauthenticatedClient(config, opts = {}) {
+  const benchmarkId = process.env.WH_BENCHMARK_ID?.trim();
+  return new WarmHubClient({
+    apiUrl: config.apiUrl,
+    fetch: createBenchmarkAwareFetch(benchmarkId),
+    functionLogs: opts.functionLogs,
+    client: cliClientIdentity()
+  });
+}
 function wantsStructuredLiveOutput(format) {
   return format === "json" || format === "jsonl";
 }
@@ -32186,9 +32324,18 @@ class DomainRegistry {
       throw new Error(`Domain '${def.name}' already registered`);
     }
     const spec = this.buildSpec(def);
-    this.domains.set(def.name, spec);
-    this.registerHandlers(def);
     this.validateDomain(spec, def);
+    const handlers = new Map;
+    this.collectHandlers(def, handlers);
+    for (const key of handlers.keys()) {
+      if (this.handlers.has(key)) {
+        throw new Error(`Handler '${key}' already registered`);
+      }
+    }
+    this.domains.set(def.name, spec);
+    for (const [key, handler] of handlers) {
+      this.handlers.set(key, handler);
+    }
   }
   buildSpec(def) {
     if (def.kind === "flat") {
@@ -32241,39 +32388,48 @@ class DomainRegistry {
       aliases: f.aliases
     }));
   }
-  registerHandlers(def, path = [def.name]) {
+  collectHandlers(def, handlers, path = [def.name]) {
     if (def.kind === "flat") {
       const key = [...path, ""].join(":");
-      if (this.handlers.has(key)) {
+      if (handlers.has(key)) {
         throw new Error(`Handler '${key}' already registered`);
       }
-      this.handlers.set(key, def.handler);
+      handlers.set(key, def.handler);
       return;
     }
     for (const [verbName, v] of Object.entries(def.verbs)) {
       const key = [...path, verbName].join(":");
-      if (this.handlers.has(key)) {
+      if (handlers.has(key)) {
         throw new Error(`Handler '${key}' already registered`);
       }
-      this.handlers.set(key, v.handler);
+      handlers.set(key, v.handler);
     }
     if (def.subdomains) {
       for (const [subName, subDef] of Object.entries(def.subdomains)) {
-        this.registerHandlers(subDef, [...path, subName]);
+        this.collectHandlers(subDef, handlers, [...path, subName]);
       }
     }
   }
-  validateDomain(spec, def) {
+  validateDomain(spec, def, path = [def.name]) {
     if (spec.kind === "noun") {
+      const displayPath = path.join(".");
       for (const [verbName, v] of Object.entries(spec.verbs)) {
         for (const alias of v.verbAliases ?? []) {
           if (spec.verbs[alias]) {
-            throw new Error(`Alias '${alias}' for ${spec.name}.${verbName} conflicts with verb '${alias}'`);
+            throw new Error(`Alias '${alias}' for ${displayPath}.${verbName} conflicts with verb '${alias}'`);
           }
         }
       }
       if (def.kind !== "flat" && def.defaultVerb && !def.verbs[def.defaultVerb]) {
-        throw new Error(`Domain '${def.name}': defaultVerb '${def.defaultVerb}' does not name a canonical verb`);
+        throw new Error(`Domain '${displayPath}': defaultVerb '${def.defaultVerb}' does not name a canonical verb`);
+      }
+      if (def.kind !== "flat" && def.subdomains) {
+        for (const [subName, subDef] of Object.entries(def.subdomains)) {
+          const subSpec = spec.subdomains?.[subName];
+          if (subSpec) {
+            this.validateDomain(subSpec, subDef, [...path, subName]);
+          }
+        }
       }
     }
   }
@@ -32299,6 +32455,14 @@ class DomainRegistry {
       path.push(tokens[i]);
       i++;
     }
+    if (cursor.kind === "flat") {
+      return {
+        domain,
+        domainPath: path,
+        verb: undefined,
+        remaining: tokens.slice(i)
+      };
+    }
     const verb = tokens[i];
     const remaining = tokens.slice(i + 1);
     return { domain, domainPath: path, verb, remaining };
@@ -35720,8 +35884,9 @@ var handleLogin = async (ctx, { flags }) => {
   try {
     clientId = await ctx.client.auth.getClientId();
   } catch {
-    await deleteProfileLocked(profile);
-    clientId = await ctx.client.auth.getClientId();
+    clientId = await createUnauthenticatedClient(ctx.config, {
+      functionLogs: ctx.functionLogMode
+    }).auth.getClientId();
   }
   if (!clientId) {
     throw new CliError(5 /* Auth */, "AUTH", "Backend has no WORKOS_CLIENT_ID configured.");
@@ -37818,7 +37983,8 @@ function resolveInvocation(parsed) {
     subcommand,
     positional: positionals,
     flags,
-    ...parsed.terminator ? { terminator: parsed.terminator } : {}
+    ...parsed.terminator ? { terminator: parsed.terminator } : {},
+    ...parsed.rawArgv ? { rawArgv: [...parsed.rawArgv] } : {}
   };
 }
 
@@ -37829,6 +37995,68 @@ function isRawGlobalFlagForComponentExec(key) {
     return true;
   return isGlobalShortFlag(key) && key !== key.toLowerCase();
 }
+function isNegativeNumericToken(token) {
+  if (!token.startsWith("-") || token === "-")
+    return false;
+  return Number.isFinite(Number(token));
+}
+function isNumericMethodArg(method, name) {
+  return method.args.some((arg) => arg.name === name && (arg.type === "number" || arg.type === "integer"));
+}
+function normalizeNegativeNumericMethodArgs(method, argv) {
+  const normalized = [];
+  for (let i = 0;i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token.startsWith("--") && !token.includes("=") && isNumericMethodArg(method, token.slice(2)) && argv[i + 1] !== undefined && isNegativeNumericToken(argv[i + 1])) {
+      normalized.push(`${token}=${argv[i + 1]}`);
+      i += 1;
+      continue;
+    }
+    normalized.push(token);
+  }
+  return normalized;
+}
+function flagValueTokenLength(argv, index) {
+  const token = argv[index];
+  if (token === undefined)
+    return 0;
+  if (token.startsWith("--")) {
+    if (token.includes("="))
+      return 1;
+    const next = argv[index + 1];
+    return next !== undefined && !next.startsWith("-") ? 2 : 1;
+  }
+  if (token.startsWith("-") && token !== "-") {
+    const next = argv[index + 1];
+    return next !== undefined && !next.startsWith("-") ? 2 : 1;
+  }
+  return 0;
+}
+function findComponentMethodArgStart(rawArgv, componentName, methodName) {
+  const terminatorIndex = rawArgv.indexOf("--");
+  const scanEnd = terminatorIndex === -1 ? rawArgv.length : terminatorIndex;
+  const positionalIndexes = [];
+  for (let i = 0;i < scanEnd; ) {
+    const consumedFlagTokens = flagValueTokenLength(rawArgv, i);
+    if (consumedFlagTokens > 0) {
+      i += consumedFlagTokens;
+      continue;
+    }
+    positionalIndexes.push(i);
+    i += 1;
+  }
+  const positionals = positionalIndexes.map((index) => rawArgv[index]);
+  if (positionals[0] === "component" && positionals[1] === "exec" && positionals[2] === componentName && positionals[3] === methodName) {
+    return positionalIndexes[3] + 1;
+  }
+  if (positionals[0] === componentName && positionals[1] === methodName) {
+    return positionalIndexes[1] + 1;
+  }
+  return;
+}
+function parseComponentMethodTokenStream(method, argv) {
+  return parseArgs(normalizeNegativeNumericMethodArgs(method, argv));
+}
 function parseMethodArgs(method, rawFlags, terminatorFlags = {}) {
   const argsByName = new Map;
   for (const a of method.args)
@@ -37971,9 +38199,6 @@ var handleComponentExec = async (ctx, { args, terminator }) => {
   }
   const componentName = args[0];
   const methodName = args[1];
-  if (args.length > 2) {
-    throw new CliError(2 /* UserInput */, "USER_INPUT", `Unexpected argument: '${args[2]}'`, undefined, "'wh component exec' accepts at most 2 positional arguments (<component> <method>); pass method inputs as flags");
-  }
   const { org, repo } = parseOrgRepo(getRepoRef(ctx), ctx.config);
   const installRepo = `${org}/${repo}`;
   const cache = await ensureFreshInstallSnapshotCache(installRepo, ctx.client);
@@ -37996,14 +38221,29 @@ var handleComponentExec = async (ctx, { args, terminator }) => {
     renderMethodHelp(ctx, componentName, method);
     return;
   }
-  const terminatorArgs = terminator && terminator.length > 0 ? parseArgs([...terminator]) : undefined;
+  const rawArgv = ctx.invocation.rawArgv;
+  const methodArgStart = rawArgv === undefined ? undefined : findComponentMethodArgStart(rawArgv, componentName, methodName);
+  const terminatorIndex = rawArgv?.indexOf("--") ?? -1;
+  const preTerminatorEnd = rawArgv === undefined ? undefined : terminatorIndex === -1 ? rawArgv.length : terminatorIndex;
+  const preMethodArgs = rawArgv !== undefined && methodArgStart !== undefined ? parseComponentMethodTokenStream(method, rawArgv.slice(0, methodArgStart)) : undefined;
+  const methodArgs = rawArgv !== undefined && methodArgStart !== undefined && preTerminatorEnd !== undefined ? parseComponentMethodTokenStream(method, rawArgv.slice(methodArgStart, preTerminatorEnd)) : undefined;
+  const unexpectedMethodPositional = methodArgs?.positionals[0] ?? (methodArgStart === undefined ? args[2] : undefined);
+  if (unexpectedMethodPositional !== undefined) {
+    throw new CliError(2 /* UserInput */, "USER_INPUT", `Unexpected argument: '${unexpectedMethodPositional}'`, undefined, "'wh component exec' accepts at most 2 positional arguments (<component> <method>); pass method inputs as flags");
+  }
+  const terminatorArgs = terminator && terminator.length > 0 ? parseComponentMethodTokenStream(method, terminator) : undefined;
   if (terminatorArgs?.positionals.length) {
     throw new CliError(2 /* UserInput */, "USER_INPUT", `Unexpected argument: '${terminatorArgs.positionals[0]}'`, undefined, "Component CLI method inputs must be passed as named flags, even after --");
   }
   const terminatorFlags = terminatorArgs?.flags ?? {};
   let parsedArgs;
+  const rawFlags = {
+    ...methodArgStart === undefined ? ctx.invocation.flags : {},
+    ...preMethodArgs?.flags,
+    ...methodArgs?.flags
+  };
   try {
-    parsedArgs = parseMethodArgs(method, ctx.invocation.flags, terminatorFlags);
+    parsedArgs = parseMethodArgs(method, rawFlags, terminatorFlags);
   } catch (error) {
     withMethodHelpHint(error, methodHelpHint(componentName, methodName, installRepo));
   }
@@ -41479,6 +41719,17 @@ function buildContentPrompt(ctx) {
 }
 
 // ../../packages/warmhub-cli/src/domains/repo/helpers.ts
+function parseExplicitOrgRepoArg(ref, usage, example) {
+  if (!ref?.includes("/")) {
+    usageError(usage, example);
+  }
+  const parts = ref.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    usageError(`Invalid repo format "${ref}". Expected "org/repo" with no extra slashes or empty segments.`, example);
+  }
+  const [orgName, repoName] = parts;
+  return { orgName, repoName };
+}
 function ensureNonEmptyDisplayName(value, exampleCommand) {
   if (value !== undefined && value.trim() === "") {
     usageError("--display-name requires a non-empty value", exampleCommand);
@@ -41730,11 +41981,7 @@ var confirmFlags2 = {
   yes: flag.boolean({ short: "y", description: "Skip confirmation prompt" })
 };
 var handleArchive2 = async (ctx, { flags, args }) => {
-  const orgRepo = args[0];
-  if (!orgRepo?.includes("/")) {
-    usageError("Usage: wh repo archive <org/repo> [--yes]", "wh repo archive myorg/old-repo");
-  }
-  const [orgName, repoName] = orgRepo.split("/", 2);
+  const { orgName, repoName } = parseExplicitOrgRepoArg(args[0], "Usage: wh repo archive <org/repo> [--yes]", "wh repo archive myorg/old-repo");
   if (!flags.yes) {
     const confirmed = await ctx.confirm?.(`Archive repo "${orgName}/${repoName}"? This will block new commits.`);
     if (!confirmed) {
@@ -41749,11 +41996,7 @@ var handleArchive2 = async (ctx, { flags, args }) => {
   });
 };
 var handleUnarchive2 = async (ctx, { args }) => {
-  const orgRepo = args[0];
-  if (!orgRepo?.includes("/")) {
-    usageError("Usage: wh repo unarchive <org/repo>", "wh repo unarchive myorg/old-repo");
-  }
-  const [orgName, repoName] = orgRepo.split("/", 2);
+  const { orgName, repoName } = parseExplicitOrgRepoArg(args[0], "Usage: wh repo unarchive <org/repo>", "wh repo unarchive myorg/old-repo");
   const c = ctx.colors;
   const result = await ctx.client.repo.unarchive(orgName, repoName);
   writeOutput(ctx, result, () => {
@@ -41764,11 +42007,7 @@ var deleteFlags = {
   yes: flag.boolean({ short: "y", description: "Skip confirmation prompt" })
 };
 var handleDelete2 = async (ctx, { flags, args }) => {
-  const orgRepo = args[0];
-  if (!orgRepo?.includes("/")) {
-    usageError("Usage: wh repo delete <org/repo> [--yes]", "wh repo delete myorg/old-repo");
-  }
-  const [orgName, repoName] = orgRepo.split("/", 2);
+  const { orgName, repoName } = parseExplicitOrgRepoArg(args[0], "Usage: wh repo delete <org/repo> [--yes]", "wh repo delete myorg/old-repo");
   const c = ctx.colors;
   if (!flags.yes) {
     const prompt = `Delete "${orgName}/${repoName}"? The repo will be hidden immediately and permanently deleted after a 30-day grace window.`;
@@ -41866,21 +42105,23 @@ var handleRepoRename = async (ctx, { args, flags }) => {
   const flagSlug = flags.slug;
   const displayName2 = flags["display-name"];
   const rawSlugFromInvocation = ctx.invocation.positional[2];
+  const usage = 'Usage: wh repo rename <org/repoName> [<newName>] [--slug <slug>] [--display-name "..."]';
+  const example = 'wh repo rename myorg/oldrepo newrepo --display-name "New Repo"';
   if (!orgRepo?.includes("/")) {
-    usageError('Usage: wh repo rename <org/repoName> [<newName>] [--slug <slug>] [--display-name "..."]', 'wh repo rename myorg/oldrepo newrepo --display-name "New Repo"');
+    usageError(usage, example);
   }
   if (positionalSlug && flagSlug !== undefined && positionalSlug !== flagSlug) {
     usageError("Specify the new slug as either a positional or --slug, not both", "wh repo rename myorg/foo bar  # or: wh repo rename myorg/foo --slug bar");
   }
   const newSlug = positionalSlug !== undefined ? positionalSlug : flagSlug;
   if (newSlug === undefined && displayName2 === undefined) {
-    usageError('Usage: wh repo rename <org/repoName> [<newName>] [--slug <slug>] [--display-name "..."]', 'wh repo rename myorg/oldrepo newrepo --display-name "New Repo"');
+    usageError(usage, example);
   }
   if (newSlug !== undefined && newSlug.length === 0 || rawSlugFromInvocation === "" || flagSlug === "") {
     usageError("New slug must be a non-empty string", "wh repo rename myorg/oldrepo newrepo");
   }
   ensureNonEmptyDisplayName(displayName2, 'wh repo rename myorg/oldrepo --display-name "New Repo"');
-  const [orgName, oldName] = orgRepo.split("/", 2);
+  const { orgName, repoName: oldName } = parseExplicitOrgRepoArg(orgRepo, usage, example);
   const c = ctx.colors;
   const slugChange = newSlug && newSlug !== oldName ? newSlug : undefined;
   if (displayName2 !== undefined && slugChange) {
@@ -41909,14 +42150,12 @@ var updateFlags3 = {
   description: flag.string({ short: "d", description: "New repo description" })
 };
 var handleUpdate3 = async (ctx, { args, flags }) => {
-  const orgRepo = args[0];
-  if (!orgRepo?.includes("/")) {
-    usageError('Usage: wh repo update <org/repo> --description "..."', 'wh repo update myorg/myrepo -d "My repo description"');
-  }
+  const usage = 'Usage: wh repo update <org/repo> --description "..."';
+  const example = 'wh repo update myorg/myrepo -d "My repo description"';
+  const { orgName, repoName } = parseExplicitOrgRepoArg(args[0], usage, example);
   if (flags.description === undefined) {
     usageError("At least one field must be specified to update", 'wh repo update myorg/myrepo --description "New description"');
   }
-  const [orgName, repoName] = orgRepo.split("/", 2);
   const c = ctx.colors;
   const description = flags.description === "" ? undefined : flags.description;
   const result = await ctx.client.repo.setDescription(orgName, repoName, description);
@@ -44345,12 +44584,13 @@ function extractFlags(flags, specs) {
         result[spec.long] = Boolean(value);
         break;
       case "number": {
-        if (typeof value === "boolean") {
+        const scalarValue = Array.isArray(value) ? value[value.length - 1] : value;
+        if (typeof scalarValue === "boolean") {
           throw new CliError(2 /* UserInput */, "USER_INPUT", `Flag --${spec.long} requires a numeric value`, undefined, `Usage: --${spec.long} <number>`);
         }
-        const n = Number(value);
+        const n = Number(scalarValue);
         if (!Number.isFinite(n)) {
-          throw new CliError(2 /* UserInput */, "USER_INPUT", `Invalid number for --${spec.long}: '${value}'`, undefined, `Expected a number, e.g. --${spec.long} 10`);
+          throw new CliError(2 /* UserInput */, "USER_INPUT", `Invalid number for --${spec.long}: '${scalarValue}'`, undefined, `Expected a number, e.g. --${spec.long} 10`);
         }
         result[spec.long] = n;
         break;
@@ -44558,6 +44798,11 @@ function walkSubdomainsForHelpAll(out) {
             for (const [verbName, verb] of Object.entries(sub.verbs)) {
               out(`    ${domain.name} ${subName} ${verbName.padEnd(12)} ${verb.summary}`);
             }
+          } else {
+            out(`    ${domain.name} ${subName.padEnd(12)} ${sub.summary}`);
+            if (sub.args) {
+              out(`      Usage: wh ${domain.name} ${subName} ${sub.args}`);
+            }
           }
         }
       }
@@ -44725,6 +44970,20 @@ function printVerbHelp(out, domain, verbName, verb, format, domainPath) {
 }
 
 // ../../packages/warmhub-cli/src/domain-dispatch-core.ts
+function resolveDomainPathSpec(domain, domainPath) {
+  let cursor = domain;
+  for (const seg of domainPath.slice(1)) {
+    if (cursor.kind !== "noun") {
+      throw new CliError(1 /* Runtime */, "UNKNOWN", `Invalid subdomain path: ${seg}`);
+    }
+    const next = cursor.subdomains?.[seg];
+    if (!next) {
+      throw new CliError(1 /* Runtime */, "UNKNOWN", `Invalid subdomain path: ${seg}`);
+    }
+    cursor = next;
+  }
+  return cursor;
+}
 async function dispatchDomain(ctx, depth = 0) {
   const tokens = [
     ctx.invocation.command ?? "",
@@ -44752,9 +45011,10 @@ async function dispatchDomain(ctx, depth = 0) {
   }
   const { domain, domainPath, verb, remaining } = resolved;
   const helpRequested = ctx.invocation.flags.help === true || ctx.invocation.flags.h === true;
-  if (domain.kind === "flat") {
+  const pathSpec = resolveDomainPathSpec(domain, domainPath);
+  if (pathSpec.kind === "flat") {
     if (helpRequested) {
-      printDomainVerbHelp(ctx.out, domain, ctx.format, domainPath);
+      printDomainVerbHelp(ctx.out, pathSpec, ctx.format, domainPath);
       return true;
     }
     if (remaining.length > 0) {
@@ -44764,13 +45024,13 @@ async function dispatchDomain(ctx, depth = 0) {
         throwRenameHint(flatRenameHint);
       }
     }
-    const maxPositional = countMaxPositional(domain.args);
+    const maxPositional = countMaxPositional(pathSpec.args);
     if (remaining.length > maxPositional) {
       const extra = remaining[maxPositional];
-      const usageHint = maxPositional === 0 ? `'wh ${domainPath.join(" ")}' takes no positional arguments` : `'wh ${domainPath.join(" ")}' accepts at most ${maxPositional} positional argument${maxPositional === 1 ? "" : "s"} (${domain.args})`;
+      const usageHint = maxPositional === 0 ? `'wh ${domainPath.join(" ")}' takes no positional arguments` : `'wh ${domainPath.join(" ")}' accepts at most ${maxPositional} positional argument${maxPositional === 1 ? "" : "s"} (${pathSpec.args})`;
       throw new CliError(2 /* UserInput */, "USER_INPUT", `Unexpected argument: '${extra}'`, undefined, usageHint);
     }
-    const typedFlags2 = extractFlags(ctx.invocation.flags, domain.flags);
+    const typedFlags2 = extractFlags(ctx.invocation.flags, pathSpec.flags);
     const allArgs = verb ? [verb, ...remaining] : remaining;
     if (ctx.dryRun) {
       ctx.out(JSON.stringify({
@@ -44793,12 +45053,7 @@ async function dispatchDomain(ctx, depth = 0) {
     });
     return true;
   }
-  const specCursor = domainPath.slice(1).reduce((d, seg) => {
-    const next = d.subdomains?.[seg];
-    if (!next || next.kind === "flat")
-      throw new CliError(1 /* Runtime */, "UNKNOWN", `Invalid subdomain path: ${seg}`);
-    return next;
-  }, domain);
+  const specCursor = pathSpec;
   const verbs = Object.keys(specCursor.verbs);
   const invokeSingleVerb = async (args) => {
     if (verbs.length !== 1 || helpRequested)
@@ -45108,6 +45363,8 @@ function parseFunctionLogMode(flags, env) {
 async function runCli(argv, opts) {
   const version = opts?.version ?? package_default2.version;
   setCliClientVersion(version);
+  startCliTraceContext();
+  const traceFields = cliTraceLogFields();
   const startedAt = Date.now();
   const { out, err } = stdioWriter();
   const parsed = parseArgs(argv);
@@ -45135,7 +45392,8 @@ async function runCli(argv, opts) {
     cwd: process.cwd(),
     node: process.version,
     pid: process.pid,
-    profile: getStringFlag(invocation.flags, "profile", "P") ?? undefined
+    profile: getStringFlag(invocation.flags, "profile", "P") ?? undefined,
+    ...traceFields
   });
   let exitCode = 0 /* Ok */;
   let removeSignalListeners;
@@ -45194,14 +45452,14 @@ async function runCli(argv, opts) {
     let cancelledExitCode;
     const handleSigint = () => {
       ac.abort();
-      logger.info("cli.cancelled", { signal: "SIGINT" });
+      logger.info("cli.cancelled", { signal: "SIGINT", ...traceFields });
       cancelledExitCode = cancellationExitCode("SIGINT", liveMode);
       if (!liveMode)
         process.exitCode = 130 /* Cancelled */;
     };
     const handleSigterm = () => {
       ac.abort();
-      logger.info("cli.cancelled", { signal: "SIGTERM" });
+      logger.info("cli.cancelled", { signal: "SIGTERM", ...traceFields });
       cancelledExitCode = cancellationExitCode("SIGTERM", liveMode);
       process.exitCode = 143;
     };
@@ -45241,7 +45499,8 @@ async function runCli(argv, opts) {
     const cliError = toCliError2(error);
     const fields = {
       kind: cliError.kind,
-      exit_code: cliError.code
+      exit_code: cliError.code,
+      ...traceFields
     };
     if (cliError.kind !== "USER_INPUT" && cliError.kind !== "CONFIG") {
       fields.message = cliError.message;
@@ -45261,7 +45520,8 @@ async function runCli(argv, opts) {
     removeSignalListeners?.();
     logger.info("cli.end", {
       exit_code: exitCode,
-      duration_ms: Date.now() - startedAt
+      duration_ms: Date.now() - startedAt,
+      ...traceFields
     });
     await logger.shutdown();
   }
@@ -45314,7 +45574,7 @@ function resolveLogLevel(flags, env) {
 // package.json
 var package_default3 = {
   name: "@warmhub/cli",
-  version: "0.62.0",
+  version: "0.63.0",
   private: false,
   type: "module",
   description: "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",
@@ -45374,6 +45634,14 @@ var package_default3 = {
 };
 
 // ../../packages/warmhub-cli/src/component-shell.ts
+function registeredComponentUsageHint(verb) {
+  const example = verb === "install" ? "wh component install warmhub/veritas --repo myorg/myrepo" : "wh component update warmhub/identity --repo org/repo";
+  return [
+    `Usage: wh component ${verb} <org/name> --repo org/repo`,
+    `Example: ${example}`
+  ].join(`
+`);
+}
 async function maybeHandleComponentShellBoundary(argv, deps = {}) {
   const parsed = parseArgs(argv);
   const invocation = resolveInvocation(parsed);
@@ -45397,6 +45665,11 @@ async function maybeHandleComponentShellBoundary(argv, deps = {}) {
     if (getBoolFlag(invocation.flags, "dry-run")) {
       return;
     }
+    const source = invocation.positional[1];
+    if (source && invocation.positional.length > 2) {
+      const unexpected = invocation.positional[2];
+      throw new CliError(2 /* UserInput */, "USER_INPUT", `Unexpected argument '${unexpected}' for wh component ${componentShellVerb}.`, undefined, registeredComponentUsageHint(componentShellVerb));
+    }
     const { config, client } = resolveCliContext({
       invocation,
       format,
@@ -45404,7 +45677,6 @@ async function maybeHandleComponentShellBoundary(argv, deps = {}) {
       config: deps.config,
       client: deps.client
     });
-    const source = invocation.positional[1];
     if (!source) {
       return;
     }
@@ -45956,4 +46228,4 @@ if (!updateCheckSuppressedByArgv && shouldRunUpdateCheck(updateEligibility)) {
 var interceptedExitCode = await maybeHandleComponentShellBoundary(dispatchArgv);
 process.exitCode = interceptedExitCode === undefined ? await runCli(dispatchArgv, { version: package_default3.version }) : interceptedExitCode;
 
-//# debugId=FB7C860F078FFF2164756E2164756E21
+//# debugId=AA99DB1239BF58B064756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmhub/cli",
-  "version": "0.62.0",
+  "version": "0.63.0",
   "private": false,
   "type": "module",
   "description": "The wh CLI for WarmHub — create repos, commit and query data, and compound knowledge with your AI agents.",