apcore-cli 0.8.1 → 0.9.0

package/dist/index.d.ts

@@ -69,6 +69,13 @@ type ApcliConfig = boolean | {
     exclude?: string[];
     disableEnv?: boolean;
 };
+/**
+ * Default name of the built-in command group. Overridable per ApcliGroup
+ * instance via the `name` constructor option, or via createCli's
+ * `builtinGroupName` option. Cross-SDK parity with Python
+ * `DEFAULT_BUILTIN_GROUP_NAME` (2026-05-08).
+ */
+declare const DEFAULT_BUILTIN_GROUP_NAME = "apcli";
 /**
  * Set of group names reserved by apcore-cli when no rename is configured.
  * Default mirrors {@link DEFAULT_BUILTIN_GROUP_NAME}; when `builtinGroupName`
@@ -76,6 +83,16 @@ type ApcliConfig = boolean | {
  * is applied per-instance during the cli.ts collision check.
  */
 declare const RESERVED_GROUP_NAMES: ReadonlySet<string>;
+/**
+ * Canonical set of apcli subcommand names.
+ *
+ * Declarative mirror of the registration TABLE in `src/main.ts`
+ * (`_registerApcliSubcommands`). Used by `_normalizeList` to warn on
+ * unknown entries in include/exclude lists (spec §7 error table / T-APCLI-25).
+ *
+ * Keep in sync with main.ts TABLE if subcommands are added or removed.
+ */
+declare const APCLI_SUBCOMMAND_NAMES: ReadonlySet<string>;
 /**
  * Visibility configuration for the built-in `apcli` command group.
  *
@@ -178,7 +195,7 @@ declare class ApcliGroup {
  * Protocol spec: CLI command structure & lazy loading
  */
 
-/** Placeholder for apcore-js Registry. */
+/** CLI-internal Registry shim (see D9-W2 note above). */
 interface Registry {
     listModules(): ModuleDescriptor[];
     getModule(moduleId: string): ModuleDescriptor | null;
@@ -375,7 +392,9 @@ declare class GroupedModuleGroup extends LazyModuleGroup {
  */
 declare function validateModuleId(moduleId: string): void;
 
-/** Set the verbose help flag. When false, built-in options are hidden from help. */
+/** Set the all-options help flag. When false, built-in options are hidden from help. */
+declare function setAllOptionsHelp(allOptions: boolean): void;
+/** @deprecated Use {@link setAllOptionsHelp} instead. Kept for backward compatibility. */
 declare function setVerboseHelp(verbose: boolean): void;
 /**
  * Set the base URL for online documentation links shown in help and man pages.
@@ -417,6 +436,12 @@ interface APCore {
 interface CreateCliOptions {
     extensionsDir?: string;
     progName?: string;
+    /**
+     * Show all options in help output (controls `--all-options` behaviour;
+     * parameter was named `verbose` prior to v0.9.0).
+     */
+    allOptions?: boolean;
+    /** @deprecated Use {@link allOptions} instead. Kept for backward compatibility with pre-v0.9.0 callers. */
     verbose?: boolean;
     /**
      * APCore unified client instance (apcore-js >= 0.18.0).
@@ -493,9 +518,10 @@ interface CreateCliOptions {
  *
  * @param extensionsDirOrOpts  Path to extensions directory, or a CreateCliOptions object.
  * @param progName       Program name shown in help (default: apcore-cli)
- * @param verbose        Show verbose help output
+ * @param allOptions     Show all options in help output (controls `--all-options` behaviour;
+ *                       parameter was named `verbose` prior to v0.9.0)
  */
-declare function createCli(extensionsDirOrOpts?: string | CreateCliOptions, progName?: string, verbose?: boolean): Command;
+declare function createCli(extensionsDirOrOpts?: string | CreateCliOptions, progName?: string, allOptions?: boolean): Command;
 /** Options bag for {@link applyToolkitIntegration}. */
 interface ApplyToolkitIntegrationOptions {
     /**
@@ -826,6 +852,18 @@ declare class ApprovalDeniedError extends Error {
 declare class SchemaValidationError extends Error {
     constructor(message?: string);
 }
+/** Thrown when $ref resolution depth exceeds the configured maximum. */
+declare class MaxDepthExceededError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when a circular $ref is detected during schema resolution. */
+declare class CircularRefError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when a $ref target cannot be found in $defs/definitions. */
+declare class UnresolvableRefError extends Error {
+    constructor(message?: string);
+}
 /** Thrown when a module is not found. */
 declare class ModuleNotFoundError extends Error {
     constructor(message?: string);
@@ -950,8 +988,19 @@ declare class ConfigEncryptor {
  */
 declare class AuthProvider {
     private readonly config;
-    private readonly encryptor;
+    private readonly _encryptor?;
     constructor(config: ConfigResolver, encryptor?: ConfigEncryptor);
+    /**
+     * Resolve the active ConfigEncryptor instance.
+     *
+     * D11-005 (2026-05-12): three-tier fallback chain matching Python's
+     * `_get_encryptor` (auth.py:33): explicit constructor arg > peer attribute
+     * `config.encryptor` (set by embedders injecting forced-AES test fixtures
+     * or shared instances) > fresh `new ConfigEncryptor()`. Previously TS
+     * skipped the peer-attribute tier, silently giving embedders a different
+     * encryptor than the one they wired on the config.
+     */
+    private getEncryptor;
     /**
      * Retrieve the API key from the configured sources.
      * Handles keyring: and enc: prefixes via ConfigEncryptor.
@@ -1027,4 +1076,4 @@ declare class Sandbox {
     private _sandboxedExecute;
 }
 
-export { type APCore, type ApcliConfig, ApcliGroup, ApcliGroupError, type ApcliMode, type ApplyToolkitIntegrationOptions, ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, CliApprovalHandler, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, type CreateCliOptions, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, ExposureFilter, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type PipelineTrace, type PipelineTraceStep, type PreflightCheck, type PreflightResult, RESERVED_GROUP_NAMES, type Registry, Sandbox, SchemaValidationError, type StrategyInfo, type StrategyStep, applyToolkitIntegration, buildModuleCommand, checkApproval, collectInput, configureManHelp, createCli, exitCodeForError, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getLogLevel, main, reconvertEnumValues, registerCompletionCommand, registerConfigCommand, registerConfigNamespace, registerDescribeCommand, registerDisableCommand, registerEnableCommand, registerExecCommand, registerHealthCommand, registerInitCommand, registerListCommand, registerPipelineCommand, registerReloadCommand, registerUsageCommand, registerValidateCommand, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, validateModuleId };
+export { APCLI_SUBCOMMAND_NAMES, type APCore, type ApcliConfig, ApcliGroup, ApcliGroupError, type ApcliMode, type ApplyToolkitIntegrationOptions, ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, CircularRefError, CliApprovalHandler, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, type CreateCliOptions, DEFAULTS, DEFAULT_BUILTIN_GROUP_NAME, EXIT_CODES, type Executor, type ExitCode, ExposureFilter, GroupedModuleGroup, LazyGroup, LazyModuleGroup, MaxDepthExceededError, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type PipelineTrace, type PipelineTraceStep, type PreflightCheck, type PreflightResult, RESERVED_GROUP_NAMES, type Registry, Sandbox, SchemaValidationError, type StrategyInfo, type StrategyStep, UnresolvableRefError, applyToolkitIntegration, buildModuleCommand, checkApproval, collectInput, configureManHelp, createCli, exitCodeForError, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getLogLevel, main, reconvertEnumValues, registerCompletionCommand, registerConfigCommand, registerConfigNamespace, registerDescribeCommand, registerDisableCommand, registerEnableCommand, registerExecCommand, registerHealthCommand, registerInitCommand, registerListCommand, registerPipelineCommand, registerReloadCommand, registerUsageCommand, registerValidateCommand, resolveFormat, resolveRefs, schemaToCliOptions, setAllOptionsHelp, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, validateModuleId };

package/dist/index.js

@@ -34,6 +34,12 @@ function exitCodeForError(error) {
   if (error instanceof SchemaValidationError) {
     return EXIT_CODES.SCHEMA_VALIDATION_ERROR;
   }
+  if (error instanceof MaxDepthExceededError || error instanceof CircularRefError) {
+    return EXIT_CODES.SCHEMA_CIRCULAR_REF;
+  }
+  if (error instanceof UnresolvableRefError) {
+    return EXIT_CODES.SCHEMA_VALIDATION_ERROR;
+  }
   if (error instanceof ModuleNotFoundError) {
     return EXIT_CODES.MODULE_NOT_FOUND;
   }
@@ -73,7 +79,7 @@ function exitCodeForError(error) {
   }
   return EXIT_CODES.MODULE_EXECUTE_ERROR;
 }
-var ApprovalTimeoutError, AuthenticationError, ConfigDecryptionError, ModuleExecutionError, ApprovalDeniedError, SchemaValidationError, ModuleNotFoundError, EXIT_CODES;
+var ApprovalTimeoutError, AuthenticationError, ConfigDecryptionError, ModuleExecutionError, ApprovalDeniedError, SchemaValidationError, MaxDepthExceededError, CircularRefError, UnresolvableRefError, ModuleNotFoundError, EXIT_CODES;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -114,6 +120,24 @@ var init_errors = __esm({
         this.name = "SchemaValidationError";
       }
     };
+    MaxDepthExceededError = class extends Error {
+      constructor(message = "Schema $ref resolution depth exceeded") {
+        super(message);
+        this.name = "MaxDepthExceededError";
+      }
+    };
+    CircularRefError = class extends Error {
+      constructor(message = "Circular $ref detected in schema") {
+        super(message);
+        this.name = "CircularRefError";
+      }
+    };
+    UnresolvableRefError = class extends Error {
+      constructor(message = "Unresolvable $ref in schema") {
+        super(message);
+        this.name = "UnresolvableRefError";
+      }
+    };
     ModuleNotFoundError = class extends Error {
       constructor(message = "Module not found") {
         super(message);
@@ -406,7 +430,7 @@ var init_config_encryptor = __esm({
           _ConfigEncryptor.weakFallbackWarned = true;
         }
         const hostname2 = os3.hostname();
-        const username = process.env.USER ?? process.env.USERNAME ?? "unknown";
+        const username = process.env.USER ?? process.env.LOGNAME ?? process.env.USERNAME ?? "unknown";
         const material = `${hostname2}:${username}`;
         return crypto2.pbkdf2Sync(material, salt, PBKDF2_ITERATIONS, 32, "sha256");
       }
@@ -438,7 +462,7 @@ var init_config_encryptor = __esm({
         const tag = data.subarray(12, 28);
         const ct = data.subarray(28);
         const hostname2 = os3.hostname();
-        const username = process.env.USER ?? process.env.USERNAME ?? "unknown";
+        const username = process.env.USER ?? process.env.LOGNAME ?? process.env.USERNAME ?? "unknown";
         const passphrase = process.env.APCORE_CLI_CONFIG_PASSPHRASE;
         const materials = passphrase ? [passphrase, `${hostname2}:${username}`] : [`${hostname2}:${username}`];
         for (const material of materials) {
@@ -468,10 +492,26 @@ var init_auth = __esm({
     init_config_encryptor();
     AuthProvider = class {
       config;
-      encryptor;
+      _encryptor;
       constructor(config, encryptor) {
         this.config = config;
-        this.encryptor = encryptor ?? new ConfigEncryptor();
+        this._encryptor = encryptor;
+      }
+      /**
+       * Resolve the active ConfigEncryptor instance.
+       *
+       * D11-005 (2026-05-12): three-tier fallback chain matching Python's
+       * `_get_encryptor` (auth.py:33): explicit constructor arg > peer attribute
+       * `config.encryptor` (set by embedders injecting forced-AES test fixtures
+       * or shared instances) > fresh `new ConfigEncryptor()`. Previously TS
+       * skipped the peer-attribute tier, silently giving embedders a different
+       * encryptor than the one they wired on the config.
+       */
+      getEncryptor() {
+        if (this._encryptor) return this._encryptor;
+        const fromConfig = this.config.encryptor;
+        if (fromConfig) return fromConfig;
+        return new ConfigEncryptor();
       }
       /**
        * Retrieve the API key from the configured sources.
@@ -489,11 +529,11 @@ var init_auth = __esm({
         const strResult = String(result);
         if (strResult.startsWith("keyring:") || strResult.startsWith("enc:")) {
           try {
-            return await this.encryptor.retrieve(strResult, "auth.api_key");
+            return await this.getEncryptor().retrieve(strResult, "auth.api_key");
           } catch (err) {
             if (err instanceof ConfigDecryptionError) {
               throw new AuthenticationError(
-                "Failed to decrypt stored API key. Re-configure with 'apcore-cli config set auth.api_key'."
+                "Failed to decrypt stored API key. Re-store with 'apcli config set auth.api_key'."
               );
             }
             throw err;
@@ -522,7 +562,7 @@ var init_auth = __esm({
         }
         if (/[\r\n]/.test(key)) {
           throw new AuthenticationError(
-            "Malformed API key: contains invalid characters (CR/LF). Re-configure with 'apcore-cli config set auth.api_key'."
+            "Malformed API key: contains invalid characters (CR/LF). Re-store with 'apcli config set auth.api_key'."
           );
         }
         headers.Authorization = `Bearer ${key.trim()}`;
@@ -550,7 +590,7 @@ import { join as join4, resolve as resolvePath } from "path";
 function buildSandboxEnv(tmpDir) {
   const env = {};
   for (const key of SANDBOX_ALLOW_KEYS) {
-    if (process.env[key]) env[key] = process.env[key];
+    if (process.env[key] !== void 0) env[key] = process.env[key];
   }
   for (const [key, val] of Object.entries(process.env)) {
     if (key.startsWith(SANDBOX_ALLOW_PREFIX) && !key.startsWith(SANDBOX_DENY_PREFIX) && !SANDBOX_DENY_KEYS.includes(key)) {
@@ -655,11 +695,20 @@ var init_sandbox = __esm({
           }
           stderr += chunk.toString();
         });
+        child.stdin.on("error", () => {
+        });
         child.stdin.write(JSON.stringify(inputData));
         child.stdin.end();
         return new Promise((resolve2, reject) => {
+          const cleanup = () => {
+            try {
+              rmSync(tmpDir, { recursive: true, force: true });
+            } catch {
+            }
+          };
           const timer = setTimeout(() => {
             child.kill("SIGKILL");
+            cleanup();
             reject(
               new ModuleExecutionError(
                 `Sandbox module '${moduleId}' timed out after ${this.timeoutSeconds}s.`
@@ -668,10 +717,7 @@ var init_sandbox = __esm({
           }, this.timeoutSeconds * 1e3);
           child.on("close", (code) => {
             clearTimeout(timer);
-            try {
-              rmSync(tmpDir, { recursive: true, force: true });
-            } catch {
-            }
+            cleanup();
             if (sizeExceeded) {
               const limitMiB = Math.floor(outputCap / (1024 * 1024));
               reject(new ModuleExecutionError(
@@ -695,6 +741,7 @@ var init_sandbox = __esm({
           });
           child.on("error", (err) => {
             clearTimeout(timer);
+            cleanup();
             reject(new ModuleExecutionError(`Failed to spawn sandbox process: ${err.message}`));
           });
         });
@@ -761,27 +808,21 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
   if ("$ref" in obj) {
     const refPath = obj.$ref;
     if (depth >= maxDepth) {
-      process.stderr.write(
-        `Error: $ref resolution depth exceeded maximum of ${maxDepth} for module '${moduleId}'.
-`
+      throw new MaxDepthExceededError(
+        `$ref resolution depth exceeded maximum of ${maxDepth} for module '${moduleId}'.`
       );
-      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
     }
     if (visited.has(refPath)) {
-      process.stderr.write(
-        `Error: Circular $ref detected in schema for module '${moduleId}' at path '${refPath}'.
-`
+      throw new CircularRefError(
+        `Circular $ref detected in schema for module '${moduleId}' at path '${refPath}'.`
       );
-      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
     }
     const parts = refPath.split("/");
     const key = parts[parts.length - 1];
     if (!(key in defs)) {
-      process.stderr.write(
-        `Error: Unresolvable $ref '${refPath}' in schema for module '${moduleId}'.
-`
+      throw new UnresolvableRefError(
+        `Unresolvable $ref '${refPath}' in schema for module '${moduleId}'.`
       );
-      process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);
     }
     const newVisited = new Set(visited);
     newVisited.add(refPath);
@@ -882,17 +923,12 @@ function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
       return merged;
     }
   }
-  if ("properties" in obj && typeof obj.properties === "object" && obj.properties !== null) {
-    const props = obj.properties;
-    for (const [propName, propSchema] of Object.entries(props)) {
-      props[propName] = resolveNode(
-        propSchema,
-        defs,
-        visited,
-        depth,
-        maxDepth,
-        moduleId
-      );
+  for (const [k, v] of Object.entries(obj)) {
+    if (k === "allOf" || k === "anyOf" || k === "oneOf" || k === "$ref") {
+      continue;
+    }
+    if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+      obj[k] = resolveNode(v, defs, visited, depth, maxDepth, moduleId);
     }
   }
   return obj;
@@ -941,7 +977,7 @@ var RESERVED_NAMES = /* @__PURE__ */ new Set([
   "format",
   "fields",
   "sandbox",
-  "verbose",
+  "all_options",
   "dry_run",
   "trace",
   "stream",
@@ -1089,6 +1125,14 @@ var CliApprovalHandler = class {
   }
   async requestApproval(request) {
     const moduleId = request.module_id ?? "unknown";
+    if (request.requires_approval === false) {
+      return { status: "approved", approved_by: "not_required" };
+    }
+    const moduleDef = request.module_def;
+    const annotationsForCheck = moduleDef?.annotations;
+    if (annotationsForCheck && annotationsForCheck.requires_approval === false) {
+      return { status: "approved", approved_by: "not_required" };
+    }
     if (this.autoApprove) {
       return { status: "approved", approved_by: "auto_approve" };
     }
@@ -1197,7 +1241,8 @@ async function promptWithTimeout(moduleDef, timeout) {
 init_esm_shims();
 init_errors();
 import yaml from "js-yaml";
-var TOOLKIT_MISSING_HINT = "The 'markdown' and 'skill' output formats require the apcore-toolkit peer dependency. Install with: npm install apcore-toolkit@^0.6";
+import { formatCsv, formatJsonl } from "apcore-toolkit";
+var TOOLKIT_MISSING_HINT = "The 'markdown' and 'skill' output formats require the apcore-toolkit peer dependency. Install with: npm install apcore-toolkit@^0.7";
 function descriptorToScanned(m) {
   const metadata = m.metadata ?? {};
   const display = metadata["display"] ?? null;
@@ -1218,11 +1263,6 @@ function descriptorToScanned(m) {
     warnings: []
   };
 }
-function csvCellString(value) {
-  if (value === null || value === void 0) return "";
-  if (typeof value === "object") return JSON.stringify(value);
-  return String(value);
-}
 function resolveFormat(explicitFormat) {
   if (explicitFormat !== void 0) {
     return explicitFormat;
@@ -1425,30 +1465,18 @@ function formatExecResult(result, format, fields) {
   }
   const effective = resolveFormat(format);
   if (effective === "csv") {
-    if (typeof effective_result === "object" && !Array.isArray(effective_result) && effective_result !== null) {
-      const obj = effective_result;
-      const keys = Object.keys(obj);
-      const header = keys.map(escapeCsvField).join(",");
-      const row = keys.map((k) => escapeCsvField(csvCellString(obj[k]))).join(",");
-      process.stdout.write(header + "\n" + row + "\n");
-    } else if (Array.isArray(effective_result) && effective_result.length > 0 && typeof effective_result[0] === "object") {
-      const keys = Object.keys(effective_result[0]);
-      const header = keys.map(escapeCsvField).join(",");
-      const rows = effective_result.map((item) => {
-        const obj = item;
-        return keys.map((k) => escapeCsvField(csvCellString(obj[k]))).join(",");
-      });
-      process.stdout.write(header + "\n" + rows.join("\n") + "\n");
+    const rows = toRowsForTabular(effective_result);
+    if (rows !== null) {
+      process.stdout.write(formatCsv(rows));
     } else {
       process.stdout.write(JSON.stringify(effective_result) + "\n");
     }
   } else if (effective === "yaml") {
     process.stdout.write(yaml.dump(effective_result, { lineWidth: -1 }));
   } else if (effective === "jsonl") {
-    if (Array.isArray(effective_result)) {
-      for (const item of effective_result) {
-        process.stdout.write(JSON.stringify(item) + "\n");
-      }
+    const rows = toRowsForTabular(effective_result);
+    if (rows !== null) {
+      process.stdout.write(formatJsonl(rows));
     } else {
       process.stdout.write(JSON.stringify(effective_result) + "\n");
     }
@@ -1465,11 +1493,19 @@ function formatExecResult(result, format, fields) {
     process.stdout.write(String(effective_result) + "\n");
   }
 }
-function escapeCsvField(value) {
-  if (value.includes(",") || value.includes('"') || value.includes("\n") || value.includes("\r")) {
-    return '"' + value.replace(/"/g, '""') + '"';
+function toRowsForTabular(value) {
+  if (value === null || value === void 0) return null;
+  if (Array.isArray(value)) {
+    if (value.length === 0) return null;
+    if (!value.every((item) => typeof item === "object" && item !== null && !Array.isArray(item))) {
+      return null;
+    }
+    return value;
+  }
+  if (typeof value === "object") {
+    return [value];
   }
-  return value;
+  return null;
 }
 function formatPreflightResult(result, format) {
   const resolved = resolveFormat(format);
@@ -1607,7 +1643,7 @@ function renderTemplate(template, context) {
   return result;
 }
 function registerInitCommand(cli) {
-  const initGroup = cli.command("init").description("Scaffold new apcore modules.");
+  const initGroup = cli.command("init").description("Scaffold new modules.");
   initGroup.command("module <module-id>").description("Create a new module from a template.\n\nMODULE_ID is the module identifier (e.g., ops.deploy, user.create).").option(
     "--style <style>",
     "Module style: decorator (@module), convention (plain function), or binding (YAML).",
@@ -2135,7 +2171,7 @@ function buildProgramManPage(program, progName, version, description, docsUrl2)
   s.push(".SH ENVIRONMENT");
   s.push(".TP");
   s.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
-  s.push("Path to the apcore extensions directory.");
+  s.push("Path to the extensions directory.");
   s.push(".TP");
   s.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
   s.push("Set to \\fB1\\fR to bypass approval prompts.");
@@ -2160,7 +2196,7 @@ function buildProgramManPage(program, progName, version, description, docsUrl2)
 ${meaning}`);
   }
   s.push(".SH SEE ALSO");
-  s.push(`\\fB${progName} \\-\\-help \\-\\-verbose\\fR for full option list.`);
+  s.push(`\\fB${progName} \\-\\-help \\-\\-all\\-options\\fR for full option list.`);
   if (docsUrl2) {
     s.push(`.PP
 Full documentation at \\fI${roffEscape(docsUrl2)}\\fR`);
@@ -2512,7 +2548,7 @@ function registerExecCommand(apcliGroup, registry, executor) {
         return;
       }
       let result;
-      if (opts.strategy && executor.callWithTrace) {
+      if ((opts.trace || opts.strategy) && executor.callWithTrace) {
         const [res] = await executor.callWithTrace(moduleId, merged, { strategy: opts.strategy });
         result = res;
       } else {
@@ -3573,15 +3609,18 @@ function validateModuleId(moduleId) {
 // src/main.ts
 var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
 var verboseHelp = false;
+function setAllOptionsHelp(allOptions) {
+  verboseHelp = allOptions;
+}
 function setVerboseHelp(verbose) {
-  verboseHelp = verbose;
+  setAllOptionsHelp(verbose);
 }
 var docsUrl = null;
 function setDocsUrl(url) {
   docsUrl = url;
 }
 function hasVerboseFlag() {
-  return process.argv.includes("--verbose");
+  return process.argv.includes("--all-options");
 }
 function resolveIntOption(cliValue, envValue, defaultValue) {
   if (cliValue !== void 0 && Number.isFinite(cliValue) && cliValue > 0) {
@@ -3662,7 +3701,7 @@ function emitErrorTty(e, exitCode) {
   Exit code: ${exitCode}
 `);
 }
-function createCli(extensionsDirOrOpts, progName, verbose = false) {
+function createCli(extensionsDirOrOpts, progName, allOptions = false) {
   let extensionsDir;
   let registry;
   let executor;
@@ -3677,7 +3716,7 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
   if (typeof extensionsDirOrOpts === "object" && extensionsDirOrOpts !== null) {
     extensionsDir = extensionsDirOrOpts.extensionsDir;
     progName = extensionsDirOrOpts.progName ?? progName;
-    verbose = extensionsDirOrOpts.verbose ?? verbose;
+    allOptions = extensionsDirOrOpts.allOptions ?? extensionsDirOrOpts.verbose ?? allOptions;
     app = extensionsDirOrOpts.app;
     registry = extensionsDirOrOpts.registry;
     executor = extensionsDirOrOpts.executor;
@@ -3691,7 +3730,7 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
   } else {
     extensionsDir = extensionsDirOrOpts;
   }
-  verboseHelp = verbose;
+  verboseHelp = allOptions;
   registerConfigNamespace();
   try {
     const auditLogger = new AuditLogger();
@@ -3724,7 +3763,7 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
     }
   }
   const registryInjected = registry !== void 0;
-  const program = new Command5(resolvedProgName).exitOverride().helpOption("-h, --help", "Print help").addHelpCommand("help [command]", "Print this message or the help of the given subcommand(s)").description(appDescription ?? `${resolvedProgName} CLI`).option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in options)");
+  const program = new Command5(resolvedProgName).exitOverride().helpOption("-h, --help", "Print help").addHelpCommand("help [command]", "Print this message or the help of the given subcommand(s)").description(appDescription ?? `${resolvedProgName} CLI`).option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--all-options", "Show all options in help output (including built-in options)");
   if (appVersion) {
     program.version(appVersion, "-V, --version", "Print version");
   }
@@ -3795,7 +3834,7 @@ function createCli(extensionsDirOrOpts, progName, verbose = false) {
   _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter);
   program.addHelpText("after", [
     "",
-    "Use --help --verbose to show all options (including built-in options).",
+    "Use --help --all-options to show all options (including built-in options).",
     "Use --help --man to display a formatted man page."
   ].join("\n"));
   configureManHelp(program, resolvedProgName, appVersion ?? VERSION);
@@ -3833,7 +3872,7 @@ var _ALWAYS_REGISTERED = /* @__PURE__ */ new Set(["exec"]);
 function _registerApcliSubcommands(apcliGroup, apcliCfg, registry, executor, exposureFilter) {
   const emitUnwiredError = () => {
     process.stderr.write(
-      "Error: no apcore-js registry wired. In standalone mode, pass --extensions-dir <path> to enable module discovery.\n"
+      "Error: no module registry wired. In standalone mode, pass --extensions-dir <path> to enable module discovery.\n"
     );
     process.exit(EXIT_CODES.CONFIG_INVALID);
   };
@@ -3945,9 +3984,9 @@ function main(progName) {
   verboseHelp = hasVerboseFlag();
   const program = createCli({
     progName,
-    verbose: verboseHelp,
+    allOptions: verboseHelp,
     version: VERSION,
-    description: `${progName ?? "apcore-cli"} \u2014 execute apcore modules from the command line`
+    description: `${progName ?? "apcore-cli"} \u2014 execute modules from the command line`
   });
   try {
     program.parse(process.argv);
@@ -3975,7 +4014,17 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
   if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
     try {
       resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
-    } catch {
+    } catch (err) {
+      if (err instanceof MaxDepthExceededError || err instanceof CircularRefError) {
+        process.stderr.write(`Error: ${err.message}
+`);
+        process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+      }
+      if (err instanceof UnresolvableRefError) {
+        process.stderr.write(`Error: ${err.message}
+`);
+        process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);
+      }
       resolvedSchema = inputSchema;
     }
     schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
@@ -4020,7 +4069,7 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
   cmd.addOption(approvalTokenOpt);
   const footerParts = [];
   if (!verbose) {
-    footerParts.push("Use --verbose to show all options (including built-in apcore options).");
+    footerParts.push("Use --all-options to show all options (including built-in options).");
   }
   if (docsUrl) {
     footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);
@@ -4669,6 +4718,7 @@ init_errors();
 init_logger();
 init_security();
 export {
+  APCLI_SUBCOMMAND_NAMES,
   ApcliGroup,
   ApcliGroupError,
   ApprovalDeniedError,
@@ -4676,21 +4726,25 @@ export {
   AuditLogger,
   AuthProvider,
   AuthenticationError,
+  CircularRefError,
   CliApprovalHandler,
   ConfigDecryptionError,
   ConfigEncryptor,
   ConfigResolver,
   DEFAULTS,
+  DEFAULT_BUILTIN_GROUP_NAME,
   EXIT_CODES,
   ExposureFilter,
   GroupedModuleGroup,
   LazyGroup,
   LazyModuleGroup,
+  MaxDepthExceededError,
   ModuleExecutionError,
   ModuleNotFoundError,
   RESERVED_GROUP_NAMES,
   Sandbox,
   SchemaValidationError,
+  UnresolvableRefError,
   applyToolkitIntegration,
   buildModuleCommand,
   checkApproval,
@@ -4722,6 +4776,7 @@ export {
   resolveFormat,
   resolveRefs,
   schemaToCliOptions,
+  setAllOptionsHelp,
   setAuditLogger,
   setDocsUrl,
   setLogLevel,