apcore-cli 0.5.0 → 0.6.0

package/dist/index.js

@@ -142,6 +142,7 @@ var init_errors = __esm({
       CONFIG_NAMESPACE_RESERVED: 78,
       CONFIG_NAMESPACE_DUPLICATE: 78,
       CONFIG_ENV_PREFIX_CONFLICT: 78,
+      CONFIG_ENV_MAP_CONFLICT: 78,
       CONFIG_MOUNT_ERROR: 66,
       CONFIG_BIND_ERROR: 65,
       ERROR_FORMATTER_DUPLICATE: 70,
@@ -515,7 +516,7 @@ init_errors();
 import { readFileSync as readFileSync3 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import * as path6 from "path";
-import { Command as Command2, CommanderError, Option as Option2 } from "commander";
+import { Command as Command6, CommanderError, Option as Option4 } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -733,7 +734,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
         flags: `--${flagBase}, --no-${flagBase}`,
         description: helpText,
         defaultValue: defaultVal,
-        required: false,
+        required: isRequired,
         isBooleanFlag: true
       });
     } else if ("enum" in propSchema && Array.isArray(propSchema.enum)) {
@@ -744,7 +745,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
           flags: `${flagName} <value>`,
           description: helpText,
           defaultValue,
-          required: false
+          required: isRequired
         });
       } else {
         const stringValues = enumValues.map(String);
@@ -763,7 +764,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
           flags: `${flagName} <value>`,
           description: helpText,
           defaultValue: defaultValue !== void 0 ? String(defaultValue) : void 0,
-          required: false,
+          required: isRequired,
           choices: stringValues,
           enumOriginalTypes: Object.keys(enumOriginalTypes).length > 0 ? enumOriginalTypes : void 0
         });
@@ -788,7 +789,7 @@ function schemaToCliOptions(schema, maxHelpLength = 1e3) {
         flags: `${flagName} <value>`,
         description: helpText,
         defaultValue,
-        required: false,
+        required: isRequired,
         parseArg
       });
     }
@@ -805,7 +806,41 @@ function getAnnotation(annotations, key, defaultValue = void 0) {
   const ann = annotations;
   return key in ann ? ann[key] : defaultValue;
 }
-async function checkApproval(moduleDef, autoApprove) {
+var CliApprovalHandler = class {
+  autoApprove;
+  timeout;
+  constructor(autoApprove = false, timeout = 60) {
+    this.autoApprove = autoApprove;
+    this.timeout = Math.max(1, Math.min(timeout, 3600));
+  }
+  async requestApproval(request) {
+    const moduleId = request.module_id ?? "unknown";
+    if (this.autoApprove) {
+      return { status: "approved", approved_by: "auto_approve" };
+    }
+    const envVal = process.env.APCORE_CLI_AUTO_APPROVE ?? "";
+    if (envVal === "1") {
+      return { status: "approved", approved_by: "env_auto_approve" };
+    }
+    if (!process.stdin.isTTY) {
+      return { status: "rejected", reason: "Non-interactive session without --yes" };
+    }
+    const annotations = request.annotations;
+    const extra = annotations?.extra ?? {};
+    const message = extra.approval_message ?? `Module '${moduleId}' requires approval to execute.`;
+    process.stderr.write(message + "\n");
+    try {
+      await promptWithTimeout({ id: moduleId }, this.timeout);
+      return { status: "approved", approved_by: "tty_user" };
+    } catch {
+      return { status: "rejected", reason: "User rejected or timed out" };
+    }
+  }
+  async checkApproval(_approvalId) {
+    return { status: "rejected", reason: "CLI does not support async approval polling" };
+  }
+};
+async function checkApproval(moduleDef, autoApprove, timeout = 60) {
   const annotations = moduleDef.annotations;
   let requiresApproval;
   if (moduleDef.requiresApproval !== void 0) {
@@ -839,7 +874,7 @@ async function checkApproval(moduleDef, autoApprove) {
     );
     process.exit(EXIT_CODES.APPROVAL_DENIED);
   }
-  await promptWithTimeout(moduleDef, 60);
+  await promptWithTimeout(moduleDef, timeout);
 }
 async function promptWithTimeout(moduleDef, timeout) {
   timeout = Math.max(1, Math.min(timeout, 3600));
@@ -912,7 +947,7 @@ function formatTable(headers, rows) {
   );
   return [headerLine, sep2, ...dataLines].join("\n") + "\n";
 }
-function formatModuleList(modules, format, filterTags) {
+function formatModuleList(modules, format, filterTags, showDeps = false) {
   if (format === "table") {
     if (modules.length === 0 && filterTags && filterTags.length > 0) {
       process.stdout.write(
@@ -925,19 +960,29 @@ function formatModuleList(modules, format, filterTags) {
       process.stdout.write("No modules found.\n");
       return;
     }
-    const headers = ["ID", "Description", "Tags"];
-    const rows = modules.map((m) => [
-      m.id,
-      truncate(m.description, 80),
-      (m.tags ?? []).join(", ")
-    ]);
+    const headers = showDeps ? ["ID", "Description", "Tags", "Deps"] : ["ID", "Description", "Tags"];
+    const rows = modules.map((m) => {
+      const base = [m.id, truncate(m.description, 80), (m.tags ?? []).join(", ")];
+      if (showDeps) {
+        const deps = m.dependencies;
+        base.push(String(Array.isArray(deps) ? deps.length : 0));
+      }
+      return base;
+    });
     process.stdout.write(formatTable(headers, rows));
   } else if (format === "json") {
-    const result = modules.map((m) => ({
-      id: m.id,
-      description: m.description,
-      tags: m.tags ?? []
-    }));
+    const result = modules.map((m) => {
+      const entry = {
+        id: m.id,
+        description: m.description,
+        tags: m.tags ?? []
+      };
+      if (showDeps) {
+        const deps = m.dependencies;
+        entry.dependency_count = Array.isArray(deps) ? deps.length : 0;
+      }
+      return entry;
+    });
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
   }
 }
@@ -1025,24 +1070,171 @@ Tags: ${tags.join(", ")}
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");
   }
 }
-function formatExecResult(result, format) {
+function selectFields(result, fields) {
+  const selected = {};
+  for (const f of fields.split(",")) {
+    const key = f.trim();
+    let val = result;
+    for (const part of key.split(".")) {
+      if (val && typeof val === "object" && !Array.isArray(val)) {
+        val = val[part];
+      } else {
+        val = void 0;
+        break;
+      }
+    }
+    selected[key] = val;
+  }
+  return selected;
+}
+function formatExecResult(result, format, fields) {
   if (result === null || result === void 0) {
     return;
   }
+  let effective_result = result;
+  if (fields && typeof result === "object" && !Array.isArray(result) && result !== null) {
+    effective_result = selectFields(result, fields);
+  }
   const effective = resolveFormat(format);
-  if (effective === "table" && typeof result === "object" && !Array.isArray(result)) {
-    const entries = Object.entries(result);
+  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(String(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(String(obj[k]))).join(",");
+      });
+      process.stdout.write(header + "\n" + rows.join("\n") + "\n");
+    } else {
+      process.stdout.write(JSON.stringify(effective_result) + "\n");
+    }
+  } else if (effective === "yaml") {
+    if (typeof effective_result === "object" && !Array.isArray(effective_result) && effective_result !== null) {
+      const obj = effective_result;
+      const lines = Object.entries(obj).map(([k, v]) => {
+        if (v === null || v === void 0) return `${k}: null`;
+        if (typeof v === "object") return `${k}: ${JSON.stringify(v)}`;
+        return `${k}: ${v}`;
+      });
+      process.stdout.write(lines.join("\n") + "\n");
+    } else if (Array.isArray(effective_result)) {
+      for (const item of effective_result) {
+        if (typeof item === "object" && item !== null) {
+          const obj = item;
+          const lines = Object.entries(obj).map(([k, v]) => `  ${k}: ${v}`);
+          process.stdout.write("- " + lines.join("\n  ") + "\n");
+        } else {
+          process.stdout.write(`- ${item}
+`);
+        }
+      }
+    } else {
+      process.stdout.write(String(effective_result) + "\n");
+    }
+  } else if (effective === "jsonl") {
+    if (Array.isArray(effective_result)) {
+      for (const item of effective_result) {
+        process.stdout.write(JSON.stringify(item) + "\n");
+      }
+    } else {
+      process.stdout.write(JSON.stringify(effective_result) + "\n");
+    }
+  } else if (effective === "table" && typeof effective_result === "object" && !Array.isArray(effective_result)) {
+    const entries = Object.entries(effective_result);
     const headers = ["Key", "Value"];
     const rows = entries.map(([k, v]) => [String(k), String(v)]);
     process.stdout.write(formatTable(headers, rows));
-  } else if (typeof result === "object") {
-    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
-  } else if (typeof result === "string") {
-    process.stdout.write(result + "\n");
+  } else if (typeof effective_result === "object") {
+    process.stdout.write(JSON.stringify(effective_result, null, 2) + "\n");
+  } else if (typeof effective_result === "string") {
+    process.stdout.write(effective_result + "\n");
+  } else {
+    process.stdout.write(String(effective_result) + "\n");
+  }
+}
+function escapeCsvField(value) {
+  if (value.includes(",") || value.includes('"') || value.includes("\n")) {
+    return '"' + value.replace(/"/g, '""') + '"';
+  }
+  return value;
+}
+function formatPreflightResult(result, format) {
+  const resolved = resolveFormat(format);
+  if (resolved === "json" || !process.stdout.isTTY) {
+    const payload = {
+      valid: result.valid,
+      requires_approval: result.requires_approval,
+      checks: result.checks.map((c) => {
+        const entry = { check: c.check, passed: c.passed };
+        if (c.error !== void 0 && c.error !== null) {
+          entry.error = c.error;
+        }
+        if (c.warnings && c.warnings.length > 0) {
+          entry.warnings = c.warnings;
+        }
+        return entry;
+      })
+    };
+    process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
   } else {
-    process.stdout.write(String(result) + "\n");
+    for (const c of result.checks) {
+      const hasWarnings = (c.warnings?.length ?? 0) > 0;
+      let sym;
+      if (c.passed && hasWarnings) {
+        sym = "\u26A0";
+      } else if (c.passed) {
+        sym = "\u2713";
+      } else if (c.passed === false) {
+        sym = "\u2717";
+      } else {
+        sym = "\u25CB";
+      }
+      let status = `  ${sym} ${c.check.padEnd(20)}`;
+      if (c.error) {
+        const detail = typeof c.error === "object" ? JSON.stringify(c.error) : String(c.error);
+        status += ` ${detail}`;
+      } else if (c.passed && !hasWarnings) {
+        status += " OK";
+      } else if (!c.passed) {
+        status += " Skipped";
+      }
+      process.stdout.write(status + "\n");
+      for (const w of c.warnings ?? []) {
+        process.stdout.write(`    Warning: ${w}
+`);
+      }
+    }
+    const errors = result.checks.filter((c) => !c.passed).length;
+    const warnings = result.checks.reduce((sum, c) => sum + (c.warnings?.length ?? 0), 0);
+    const tag = result.valid ? "PASS" : "FAIL";
+    process.stdout.write(`
+Result: ${tag} (${errors} error(s), ${warnings} warning(s))
+`);
   }
 }
+function firstFailedExitCode(result) {
+  const checkToExit = {
+    module_id: 2,
+    module_lookup: 44,
+    call_chain: 1,
+    acl: 77,
+    schema: 45,
+    approval: 46,
+    module_preflight: 1
+  };
+  for (const check of result.checks) {
+    if (!check.passed) {
+      return checkToExit[check.check] ?? 1;
+    }
+  }
+  return 1;
+}
 
 // src/logger.ts
 init_esm_shims();
@@ -1254,7 +1446,14 @@ var DEFAULTS = {
   "apcore-cli.stdin_buffer_limit": 10485760,
   "apcore-cli.auto_approve": false,
   "apcore-cli.help_text_max_length": 1e3,
-  "apcore-cli.logging_level": "WARNING"
+  "apcore-cli.logging_level": "WARNING",
+  // FE-11 config keys
+  "cli.approval_timeout": 60,
+  "cli.strategy": "standard",
+  "cli.group_depth": 1,
+  "apcore-cli.approval_timeout": 60,
+  "apcore-cli.strategy": "standard",
+  "apcore-cli.group_depth": 1
 };
 var NAMESPACE_TO_LEGACY = {
   "apcore-cli.stdin_buffer_limit": "cli.stdin_buffer_limit",
@@ -1276,7 +1475,10 @@ function registerConfigNamespace() {
           stdin_buffer_limit: 10485760,
           auto_approve: false,
           help_text_max_length: 1e3,
-          logging_level: "WARNING"
+          logging_level: "WARNING",
+          approval_timeout: 60,
+          strategy: "standard",
+          group_depth: 1
         }
       });
     }
@@ -1844,288 +2046,610 @@ function registerShellCommands(cli, progName = "apcore-cli") {
   cli.addCommand(manCmd);
 }
 
-// src/main.ts
-var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
-var verboseHelp = false;
-function setVerboseHelp(verbose) {
-  verboseHelp = verbose;
+// src/discovery.ts
+init_esm_shims();
+init_errors();
+import { Command as Command2, Option as Option2 } from "commander";
+var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+function validateTag(tag) {
+  if (!TAG_PATTERN.test(tag)) {
+    process.stderr.write(
+      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
 }
-var docsUrl = null;
-function setDocsUrl(url) {
-  docsUrl = url;
+function collectTag(value, previous) {
+  return previous.concat([value]);
 }
-function hasVerboseFlag() {
-  return process.argv.includes("--verbose");
+function collectAnnotation(value, previous) {
+  return previous.concat([value]);
 }
-var VERSION = "0.0.0";
-try {
-  const pkg = JSON.parse(readFileSync3(path6.resolve(__dirname3, "../package.json"), "utf-8"));
-  VERSION = pkg.version;
-} catch {
+function getAnnotationFlag(moduleDef, flag) {
+  const annotations = moduleDef.annotations;
+  if (!annotations || typeof annotations !== "object") return false;
+  const ann = annotations;
+  const map = {
+    "destructive": "destructive",
+    "requires-approval": "requires_approval",
+    "readonly": "readonly",
+    "streaming": "streaming",
+    "cacheable": "cacheable",
+    "idempotent": "idempotent"
+  };
+  const attr = map[flag] ?? flag;
+  return ann[attr] === true;
 }
-function createCli(extensionsDir, progName, verbose = false) {
-  verboseHelp = verbose;
-  registerConfigNamespace();
-  const resolvedProgName = progName ?? path6.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
-  const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? "WARNING";
-  setLogLevel(cliLogLevel);
-  const program = new Command2(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
-  const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
-  void resolvedExtDir;
-  program.addHelpText("after", [
-    "",
-    "Use --help --verbose to show all options (including built-in apcore options).",
-    "Use --help --man to display a formatted man page."
-  ].join("\n"));
-  registerInitCommand(program);
-  configureManHelp(program, resolvedProgName, VERSION);
-  program.hook("preAction", async (thisCommand) => {
-    const opts = thisCommand.opts();
-    const commandsDir = opts.commandsDir;
-    const bindingPath = opts.binding;
-    await applyToolkitIntegration(commandsDir, bindingPath);
+function registerDiscoveryCommands(cli, registry) {
+  const listCmd = new Command2("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--flat", "Show flat list (no grouping).", false).option("--format <format>", "Output format.", void 0).option("-s, --search <query>", "Filter by substring match on ID and description.").addOption(
+    new Option2("--status <status>", "Filter by module status.").choices(["enabled", "disabled", "all"]).default("enabled")
+  ).option("-a, --annotation <flag>", "Filter by annotation flag (AND logic). Repeatable.", collectAnnotation, []).addOption(
+    new Option2("--sort <field>", "Sort order.").choices(["id", "calls", "errors", "latency"]).default("id")
+  ).option("--reverse", "Reverse sort order.", false).option("--deprecated", "Include deprecated modules.", false).option("--deps", "Show dependency count column.", false).action((opts) => {
+    for (const t of opts.tag) {
+      validateTag(t);
+    }
+    let modules = [];
+    for (const m of registry.listModules()) {
+      modules.push(m);
+    }
+    if (opts.tag.length > 0) {
+      const filterTags = new Set(opts.tag);
+      modules = modules.filter((m) => {
+        const mTags = m.tags ?? [];
+        return [...filterTags].every((t) => mTags.includes(t));
+      });
+    }
+    if (opts.search) {
+      const query = opts.search.toLowerCase();
+      modules = modules.filter(
+        (m) => (m.id ?? "").toLowerCase().includes(query) || (m.description ?? "").toLowerCase().includes(query)
+      );
+    }
+    if (opts.status === "enabled") {
+      modules = modules.filter((m) => {
+        const enabled = m.enabled;
+        return enabled !== false;
+      });
+    } else if (opts.status === "disabled") {
+      modules = modules.filter((m) => {
+        const enabled = m.enabled;
+        return enabled === false;
+      });
+    }
+    if (!opts.deprecated) {
+      modules = modules.filter((m) => {
+        const deprecated = m.deprecated;
+        return deprecated !== true;
+      });
+    }
+    if (opts.annotation.length > 0) {
+      for (const annFlag of opts.annotation) {
+        modules = modules.filter((m) => getAnnotationFlag(m, annFlag));
+      }
+    }
+    if (opts.sort === "calls" || opts.sort === "errors" || opts.sort === "latency") {
+      process.stderr.write(
+        `Warning: Usage data not available; sorting by id. Sort by ${opts.sort} requires system.usage modules.
+`
+      );
+    }
+    modules.sort((a, b) => (a.id ?? "").localeCompare(b.id ?? ""));
+    if (opts.reverse) {
+      modules.reverse();
+    }
+    const fmt = resolveFormat(opts.format);
+    const filterTagsArg = opts.tag.length > 0 ? opts.tag : void 0;
+    formatModuleList(modules, fmt, filterTagsArg, opts.deps);
   });
-  return program;
+  cli.addCommand(listCmd);
+  const describeCmd = new Command2("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getModule(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(
+        `Error: Module '${moduleId}' not found.
+`
+      );
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
+    }
+    const fmt = resolveFormat(opts.format);
+    formatModuleDetail(moduleDef, fmt);
+  });
+  cli.addCommand(describeCmd);
 }
-async function applyToolkitIntegration(commandsDir, bindingPath) {
-  if (!commandsDir && !bindingPath) {
-    return;
-  }
-  try {
-    const toolkitModule = "apcore-toolkit";
-    const toolkit = await import(
-      /* @vite-ignore */
-      toolkitModule
-    );
-    if (commandsDir) {
-      console.warn("Convention scanning not yet available in TypeScript toolkit");
+function registerValidateCommand(cli, registry, executor) {
+  const validateCmd = new Command2("validate").description("Run preflight checks without executing a module.").argument("<module-id>", "Module ID to validate").option("--input <source>", "JSON input file or '-' for stdin.").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getModule(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(`Error: Module '${moduleId}' not found.
+`);
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
     }
-    if (bindingPath) {
-      const resolver = new toolkit.DisplayResolver();
-      void resolver;
+    const merged = opts.input ? await collectInput(opts.input, {}, false) : {};
+    if (!executor.validate) {
+      process.stderr.write("Error: Executor does not support validate.\n");
+      process.exit(1);
     }
-  } catch {
-    console.warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
+    const preflight = await executor.validate(moduleId, merged);
+    formatPreflightResult(preflight, opts.format);
+    process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+  });
+  cli.addCommand(validateCmd);
+}
+
+// src/system-cmd.ts
+init_esm_shims();
+import { Command as Command3 } from "commander";
+async function callSystemModule(executor, moduleId, inputs) {
+  if (executor.call) {
+    return executor.call(moduleId, inputs);
   }
+  return executor.execute(moduleId, inputs);
 }
-function main(progName) {
-  verboseHelp = hasVerboseFlag();
-  const program = createCli(void 0, progName, verboseHelp);
-  try {
-    program.parse(process.argv);
-  } catch (error2) {
-    if (error2 instanceof CommanderError) {
-      process.exit(error2.exitCode);
-    }
-    const code = exitCodeForError(error2);
-    if (error2 instanceof Error) {
-      process.stderr.write(`Error: ${error2.message}
+function formatHealthSummaryTty(result) {
+  const summary = result.summary ?? {};
+  const modules = result.modules ?? [];
+  if (modules.length === 0) {
+    process.stdout.write("No modules found.\n");
+    return;
+  }
+  const total = summary.total_modules ?? modules.length;
+  process.stdout.write(`Health Overview (${total} modules)
+
 `);
-    }
-    process.exit(code);
+  process.stdout.write(`  ${"Module".padEnd(28)} ${"Status".padEnd(12)} ${"Error Rate".padEnd(12)} Top Error
+`);
+  process.stdout.write(`  ${"-".repeat(28)} ${"-".repeat(12)} ${"-".repeat(12)} ${"-".repeat(20)}
+`);
+  for (const m of modules) {
+    const top = m.top_error;
+    const topStr = top ? `${top.code} (${top.count ?? "?"})` : "\u2014";
+    const rate = `${((m.error_rate ?? 0) * 100).toFixed(1)}%`;
+    process.stdout.write(
+      `  ${String(m.module_id).padEnd(28)} ${String(m.status).padEnd(12)} ${rate.padEnd(12)} ${topStr}
+`
+    );
+  }
+  const parts = [];
+  for (const key of ["healthy", "degraded", "error"]) {
+    const count = summary[key];
+    if (count) parts.push(`${count} ${key}`);
   }
+  process.stdout.write(`
+Summary: ${parts.join(", ") || "no data"}
+`);
 }
-function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName, verbose = verboseHelp) {
-  const moduleId = moduleDef.id;
-  let resolvedSchema = {};
-  let schemaOptions = [];
-  const display = getDisplay(moduleDef);
-  const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
-  const effectiveCmdName = cmdName ?? cliDisplay.alias ?? moduleId;
-  const cmdHelp = cliDisplay.description ?? moduleDef.description;
-  const inputSchema = moduleDef.inputSchema;
-  if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
-    try {
-      resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
-    } catch {
-      resolvedSchema = inputSchema;
+function formatHealthModuleTty(result) {
+  process.stdout.write(`Module: ${result.module_id ?? "?"}
+`);
+  process.stdout.write(`Status: ${result.status ?? "unknown"}
+`);
+  const total = result.total_calls ?? 0;
+  const errors = result.error_count ?? 0;
+  const rate = result.error_rate ?? 0;
+  const avg = result.avg_latency_ms ?? 0;
+  const p99 = result.p99_latency_ms ?? 0;
+  process.stdout.write(`Calls: ${total.toLocaleString()} total | ${errors.toLocaleString()} errors | ${(rate * 100).toFixed(1)}% error rate
+`);
+  process.stdout.write(`Latency: ${avg.toFixed(0)}ms avg | ${p99.toFixed(0)}ms p99
+`);
+  const recent = result.recent_errors ?? [];
+  if (recent.length > 0) {
+    process.stdout.write(`
+Recent Errors (top ${recent.length}):
+`);
+    for (const e of recent) {
+      const count = e.count ?? "?";
+      const last = e.last_occurred ?? "?";
+      process.stdout.write(`  ${String(e.code ?? "?").padEnd(24)} x${count}  (last: ${last})
+`);
     }
-    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
-  }
-  const cmd = new Command2(effectiveCmdName).description(cmdHelp);
-  const inputOpt = new Option2("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
-  const yesOpt = new Option2("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
-  const largeInputOpt = new Option2("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
-  const formatOpt = new Option2("--format <format>", "Set output format: 'json' for machine-readable, 'table' for human-readable");
-  const sandboxOpt = new Option2("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
-  if (!verbose) {
-    inputOpt.hideHelp();
-    yesOpt.hideHelp();
-    largeInputOpt.hideHelp();
-    formatOpt.hideHelp();
-  }
-  cmd.addOption(inputOpt);
-  cmd.addOption(yesOpt);
-  cmd.addOption(largeInputOpt);
-  cmd.addOption(formatOpt);
-  cmd.addOption(sandboxOpt);
-  const footerParts = [];
-  if (!verbose) {
-    footerParts.push("Use --verbose to show all options (including built-in apcore options).");
   }
-  if (docsUrl) {
-    footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);
+}
+function formatUsageSummaryTty(result) {
+  const modules = result.modules ?? [];
+  const period = result.period ?? "?";
+  if (modules.length === 0) {
+    process.stdout.write(`No usage data for period ${period}.
+`);
+    return;
   }
-  if (footerParts.length > 0) {
-    cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
+  process.stdout.write(`Usage Summary (last ${period})
+
+`);
+  process.stdout.write(`  ${"Module".padEnd(24)} ${"Calls".padStart(8)} ${"Errors".padStart(8)} ${"Avg Latency".padStart(12)} ${"Trend".padStart(10)}
+`);
+  process.stdout.write(`  ${"-".repeat(24)} ${"-".repeat(8)} ${"-".repeat(8)} ${"-".repeat(12)} ${"-".repeat(10)}
+`);
+  for (const m of modules) {
+    const avg = `${(m.avg_latency_ms ?? 0).toFixed(0)}ms`;
+    process.stdout.write(
+      `  ${String(m.module_id).padEnd(24)} ${String(m.call_count ?? 0).padStart(8)} ${String(m.error_count ?? 0).padStart(8)} ${avg.padStart(12)} ${String(m.trend ?? "").padStart(10)}
+`
+    );
   }
-  for (const opt of schemaOptions) {
-    if (opt.parseArg) {
-      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
+  const totalCalls = result.total_calls ?? modules.reduce((s, m) => s + (m.call_count ?? 0), 0);
+  const totalErrors = result.total_errors ?? modules.reduce((s, m) => s + (m.error_count ?? 0), 0);
+  process.stdout.write(`
+Total: ${totalCalls.toLocaleString()} calls | ${totalErrors.toLocaleString()} errors
+`);
+}
+async function registerSystemCommands(cli, executor) {
+  try {
+    if (executor.validate) {
+      await executor.validate("system.health.summary", {});
     } else {
-      cmd.option(opt.flags, opt.description, opt.defaultValue);
+      await callSystemModule(executor, "system.health.summary", { include_healthy: true });
     }
+  } catch {
+    debug("System modules not available; skipping system command registration.");
+    return;
   }
-  cmd.action(async (options) => {
-    const stdinFlag = options.input;
-    const autoApprove = options.yes;
-    const largeInput = options.largeInput;
-    const outputFormat = options.format;
-    const sandboxEnabled = options.sandbox;
-    const schemaKwargs = {};
-    const builtinKeys = /* @__PURE__ */ new Set(["input", "yes", "largeInput", "format", "sandbox", "verbose"]);
-    for (const [k, v] of Object.entries(options)) {
-      if (!builtinKeys.has(k)) {
-        schemaKwargs[k] = v;
+  const healthCmd = new Command3("health").description("Show module health status. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed health").option("--threshold <number>", "Error rate threshold (default: 0.01).", parseFloat, 0.01).option("--all", "Include healthy modules.", false).option("--errors <count>", "Max recent errors (module detail only).", parseInt, 10).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      if (moduleId) {
+        const result = await callSystemModule(executor, "system.health.module", {
+          module_id: moduleId,
+          error_limit: opts.errors
+        });
+        if (fmt === "json" || !process.stdout.isTTY) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        } else {
+          formatHealthModuleTty(result);
+        }
+      } else {
+        const result = await callSystemModule(executor, "system.health.summary", {
+          error_rate_threshold: opts.threshold,
+          include_healthy: opts.all
+        });
+        if (fmt === "json" || !process.stdout.isTTY) {
+          process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        } else {
+          formatHealthSummaryTty(result);
+        }
       }
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
     }
+  });
+  cli.addCommand(healthCmd);
+  const usageCmd = new Command3("usage").description("Show module usage statistics. Optionally specify a module ID for details.").argument("[module-id]", "Module ID for detailed usage").option("--period <period>", "Time window: 1h, 24h, 7d, 30d.", "24h").option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    const fmt = resolveFormat(opts.format);
     try {
-      const merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
-      const reconverted = reconvertEnumValues(merged, schemaOptions);
-      await checkApproval(moduleDef, autoApprove);
-      const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
-      const sandbox = new Sandbox2(sandboxEnabled);
-      const startTime = performance.now();
-      const result = await sandbox.execute(moduleId, reconverted, executor);
-      const durationMs = Math.round(performance.now() - startTime);
-      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-      const auditLogger = getAuditLogger2();
-      if (auditLogger) {
-        auditLogger.logExecution(moduleId, reconverted, "success", 0, durationMs);
+      let result;
+      if (moduleId) {
+        result = await callSystemModule(executor, "system.usage.module", {
+          module_id: moduleId,
+          period: opts.period
+        });
+      } else {
+        result = await callSystemModule(executor, "system.usage.summary", {
+          period: opts.period
+        });
       }
-      formatExecResult(result, outputFormat);
-    } catch (err) {
-      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
-      const auditLogger = getAuditLogger2();
-      const code = exitCodeForError(err);
-      if (auditLogger) {
-        auditLogger.logExecution(moduleId, {}, "error", code, 0);
+      if (fmt === "json" || !process.stdout.isTTY) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else if (moduleId) {
+        formatExecResult(result, fmt);
+      } else {
+        formatUsageSummaryTty(result);
       }
-      if (err instanceof Error) {
-        process.stderr.write(`Error: ${err.message}
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
+    }
+  });
+  cli.addCommand(usageCmd);
+  const enableCmd = new Command3("enable").description("Enable a disabled module at runtime.").argument("<module-id>", "Module ID to enable").requiredOption("--reason <reason>", "Reason for enabling (required for audit).").option("-y, --yes", "Skip approval prompt.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    if (!opts.yes) {
+      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
+    }
+    const fmt = resolveFormat(opts.format);
+    try {
+      const result = await callSystemModule(executor, "system.control.toggle_feature", {
+        module_id: moduleId,
+        enabled: true,
+        reason: opts.reason
+      });
+      if (fmt === "json" || !process.stdout.isTTY) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Module '${moduleId}' enabled.
+  Reason: ${opts.reason}
 `);
       }
-      process.exit(code);
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
     }
   });
-  return cmd;
-}
-function validateModuleId(moduleId) {
-  if (moduleId.length > 128) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(moduleId)) {
-    process.stderr.write(
-      `Error: Invalid module ID format: '${moduleId}'.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
-}
-async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
-  const cliKwargsNonNull = {};
-  for (const [k, v] of Object.entries(cliKwargs)) {
-    if (v !== null && v !== void 0) {
-      cliKwargsNonNull[k] = v;
+  cli.addCommand(enableCmd);
+  const disableCmd = new Command3("disable").description("Disable a module at runtime (calls are rejected until re-enabled).").argument("<module-id>", "Module ID to disable").requiredOption("--reason <reason>", "Reason for disabling (required for audit).").option("-y, --yes", "Skip approval prompt.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    if (!opts.yes) {
+      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
     }
-  }
-  if (!stdinFlag) {
-    return cliKwargsNonNull;
-  }
-  if (stdinFlag === "-") {
-    const raw = await readStdin();
-    const rawSize = Buffer.byteLength(raw, "utf-8");
-    if (rawSize > 10485760 && !largeInput) {
-      process.stderr.write(
-        "Error: STDIN input exceeds 10MB limit. Use --large-input to override.\n"
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    const fmt = resolveFormat(opts.format);
+    try {
+      const result = await callSystemModule(executor, "system.control.toggle_feature", {
+        module_id: moduleId,
+        enabled: false,
+        reason: opts.reason
+      });
+      if (fmt === "json" || !process.stdout.isTTY) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Module '${moduleId}' disabled.
+  Reason: ${opts.reason}
+`);
+      }
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
     }
-    if (!raw) {
-      return cliKwargsNonNull;
+  });
+  cli.addCommand(disableCmd);
+  const reloadCmd = new Command3("reload").description("Hot-reload a module from disk.").argument("<module-id>", "Module ID to reload").requiredOption("--reason <reason>", "Reason for reload (required for audit).").option("-y, --yes", "Skip approval prompt.", false).option("--format <format>", "Output format.").action(async (moduleId, opts) => {
+    if (!opts.yes) {
+      process.stderr.write("Note: This command requires approval. Use --yes to bypass.\n");
     }
-    let stdinData;
+    const fmt = resolveFormat(opts.format);
     try {
-      stdinData = JSON.parse(raw);
+      const result = await callSystemModule(executor, "system.control.reload_module", {
+        module_id: moduleId,
+        reason: opts.reason
+      });
+      if (fmt === "json" || !process.stdout.isTTY) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else {
+        const prev = result.previous_version ?? "?";
+        const newVer = result.new_version ?? "?";
+        const dur = result.reload_duration_ms ?? "?";
+        process.stdout.write(`Module '${moduleId}' reloaded.
+`);
+        process.stdout.write(`  Version: ${prev} -> ${newVer}
+`);
+        process.stdout.write(`  Duration: ${dur}ms
+`);
+      }
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
+    }
+  });
+  cli.addCommand(reloadCmd);
+  const configGroup = new Command3("config").description("Read or update runtime configuration.");
+  const configGetCmd = new Command3("get").description("Read a configuration value by dot-path key.").argument("<key>", "Configuration key (dot-path)").option("--format <format>", "Output format.", "table").action(async (key, opts) => {
+    const fmt = resolveFormat(opts.format);
+    try {
+      const result = await callSystemModule(executor, "system.config.get", { key });
+      const value = result?.value ?? result;
+      if (fmt === "json" || !process.stdout.isTTY) {
+        process.stdout.write(JSON.stringify({ key, value }, null, 2) + "\n");
+      } else {
+        process.stdout.write(`${key} = ${JSON.stringify(value)}
+`);
+      }
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
+    }
+  });
+  configGroup.addCommand(configGetCmd);
+  const configSetCmd = new Command3("set").description("Update a runtime configuration value (requires approval).").argument("<key>", "Configuration key (dot-path)").argument("<value>", "New value").requiredOption("--reason <reason>", "Reason for config change (required for audit).").option("--format <format>", "Output format.").action(async (key, value, opts) => {
+    const fmt = resolveFormat(opts.format);
+    let parsedValue;
+    try {
+      parsedValue = JSON.parse(value);
     } catch {
-      process.stderr.write(
-        "Error: STDIN does not contain valid JSON.\n"
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+      parsedValue = value;
     }
-    if (typeof stdinData !== "object" || stdinData === null || Array.isArray(stdinData)) {
-      process.stderr.write(
-        `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? "array" : typeof stdinData}.
-`
-      );
-      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    try {
+      const result = await callSystemModule(executor, "system.control.update_config", {
+        key,
+        value: parsedValue,
+        reason: opts.reason
+      });
+      if (fmt === "json" || !process.stdout.isTTY) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else {
+        const old = result.old_value ?? "?";
+        const newVal = result.new_value ?? "?";
+        process.stdout.write(`Config updated: ${key}
+`);
+        process.stdout.write(`  ${JSON.stringify(old)} -> ${JSON.stringify(newVal)}
+`);
+        process.stdout.write(`  Reason: ${opts.reason}
+`);
+      }
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
     }
-    return { ...stdinData, ...cliKwargsNonNull };
-  }
-  return cliKwargsNonNull;
-}
-function readStdin() {
-  return new Promise((resolve3, reject) => {
-    const chunks = [];
-    const onData = (chunk) => chunks.push(chunk);
-    const onEnd = () => {
-      cleanup();
-      resolve3(Buffer.concat(chunks).toString("utf-8"));
-    };
-    const onError = (err) => {
-      cleanup();
-      reject(err);
-    };
-    const cleanup = () => {
-      process.stdin.removeListener("data", onData);
-      process.stdin.removeListener("end", onEnd);
-      process.stdin.removeListener("error", onError);
-    };
-    process.stdin.on("data", onData);
-    process.stdin.on("end", onEnd);
-    process.stdin.on("error", onError);
-    process.stdin.resume();
   });
+  configGroup.addCommand(configSetCmd);
+  cli.addCommand(configGroup);
 }
-function reconvertEnumValues(kwargs, options) {
-  const result = { ...kwargs };
-  for (const opt of options) {
-    if (!opt.enumOriginalTypes) continue;
-    const paramName = opt.name;
-    if (!(paramName in result) || result[paramName] === null || result[paramName] === void 0) {
-      continue;
+
+// src/strategy.ts
+init_esm_shims();
+import { Command as Command4, Option as Option3 } from "commander";
+var PRESET_STEPS = {
+  standard: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "acl_check",
+    "approval_gate",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  internal: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  testing: [
+    "context_creation",
+    "module_lookup",
+    "middleware_before",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "middleware_after",
+    "return_result"
+  ],
+  performance: [
+    "context_creation",
+    "call_chain_guard",
+    "module_lookup",
+    "acl_check",
+    "approval_gate",
+    "input_validation",
+    "execute",
+    "output_validation",
+    "return_result"
+  ],
+  minimal: [
+    "context_creation",
+    "module_lookup",
+    "execute",
+    "return_result"
+  ]
+};
+function registerPipelineCommand(cli, executor) {
+  const pipelineCmd = new Command4("describe-pipeline").description("Show the execution pipeline steps for a strategy.").addOption(
+    new Option3("--strategy <name>", "Strategy to describe (default: standard).").choices(["standard", "internal", "testing", "performance", "minimal"]).default("standard")
+  ).option("--format <format>", "Output format.").action((opts) => {
+    const fmt = resolveFormat(opts.format);
+    let strategyObj = null;
+    const ex = executor;
+    if (typeof ex._resolve_strategy_name === "function" || typeof ex._resolveStrategyName === "function") {
+      try {
+        const fn = ex._resolve_strategy_name ?? ex._resolveStrategyName;
+        strategyObj = fn(opts.strategy);
+      } catch {
+        strategyObj = null;
+      }
     }
-    const strVal = String(result[paramName]);
-    const origType = opt.enumOriginalTypes[strVal];
-    if (origType === "int") {
-      result[paramName] = parseInt(strVal, 10);
-    } else if (origType === "float") {
-      result[paramName] = parseFloat(strVal);
-    } else if (origType === "bool") {
-      result[paramName] = strVal.toLowerCase() === "true";
+    if (!strategyObj) {
+      const steps = PRESET_STEPS[opts.strategy] ?? [];
+      const pureSteps = /* @__PURE__ */ new Set([
+        "context_creation",
+        "call_chain_guard",
+        "module_lookup",
+        "acl_check",
+        "input_validation"
+      ]);
+      const nonRemovable = /* @__PURE__ */ new Set([
+        "context_creation",
+        "module_lookup",
+        "execute",
+        "return_result"
+      ]);
+      if (fmt === "json" || !process.stdout.isTTY) {
+        const payload = {
+          strategy: opts.strategy,
+          step_count: steps.length,
+          steps: steps.map((s, i) => ({
+            index: i + 1,
+            name: s,
+            pure: pureSteps.has(s),
+            removable: !nonRemovable.has(s)
+          }))
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+      } else {
+        process.stdout.write(`Pipeline: ${opts.strategy} (${steps.length} steps)
+
+`);
+        process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
+`);
+        process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
+`);
+        for (let i = 0; i < steps.length; i++) {
+          const pure = pureSteps.has(steps[i]) ? "yes" : "no";
+          const removable = nonRemovable.has(steps[i]) ? "no" : "yes";
+          process.stdout.write(`  ${String(i + 1).padEnd(4)} ${steps[i].padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} \u2014
+`);
+        }
+      }
+      return;
     }
-  }
-  return result;
+    const stepsInfo = strategyObj.steps.map((step) => ({
+      name: step.name,
+      pure: step.pure ?? false,
+      removable: step.removable ?? true,
+      timeout_ms: step.timeout_ms ?? null
+    }));
+    if (fmt === "json" || !process.stdout.isTTY) {
+      const payload = {
+        strategy: opts.strategy,
+        step_count: stepsInfo.length,
+        steps: stepsInfo.map((s, i) => ({ index: i + 1, ...s }))
+      };
+      process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
+    } else {
+      process.stdout.write(`Pipeline: ${opts.strategy} (${stepsInfo.length} steps)
+
+`);
+      process.stdout.write(`  ${"#".padEnd(4)} ${"Step".padEnd(28)} ${"Pure".padEnd(6)} ${"Removable".padEnd(11)} Timeout
+`);
+      process.stdout.write(`  ${"-".repeat(4)} ${"-".repeat(28)} ${"-".repeat(6)} ${"-".repeat(11)} ${"-".repeat(8)}
+`);
+      for (let i = 0; i < stepsInfo.length; i++) {
+        const s = stepsInfo[i];
+        const pure = s.pure ? "yes" : "no";
+        const removable = s.removable ? "yes" : "no";
+        const timeout = s.timeout_ms !== null ? `${s.timeout_ms}ms` : "\u2014";
+        process.stdout.write(`  ${String(i + 1).padEnd(4)} ${s.name.padEnd(28)} ${pure.padEnd(6)} ${removable.padEnd(11)} ${timeout}
+`);
+      }
+    }
+  });
+  cli.addCommand(pipelineCmd);
 }
 
 // src/cli.ts
 init_esm_shims();
-import { Command as Command3 } from "commander";
-var BUILTIN_COMMANDS = ["completion", "describe", "exec", "init", "list", "man"];
+import { Command as Command5 } from "commander";
+var BUILTIN_COMMANDS = [
+  "completion",
+  "config",
+  "describe",
+  "describe-pipeline",
+  "disable",
+  "enable",
+  "exec",
+  "health",
+  "init",
+  "list",
+  "man",
+  "reload",
+  "usage",
+  "validate"
+];
 var LazyModuleGroup = class {
   registry;
   executor;
@@ -2208,7 +2732,7 @@ var LazyGroup = class {
     this.members = members;
     this._executor = executor;
     this._helpTextMaxLength = helpTextMaxLength;
-    this.command = new Command3(name).description(`${name} commands`);
+    this.command = new Command5(name).description(`${name} commands`);
     for (const [cmdName, [, descriptor]] of this.members) {
       const cmd = buildModuleCommand(
         descriptor,
@@ -2252,8 +2776,13 @@ var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
   groupMapBuilt = false;
   /**
    * Determine (groupName | null, commandName) for a module from its display overlay.
+   *
+   * @param groupDepth  Number of dotted segments to consume as the group prefix.
+   *                    Defaults to 1 (e.g., "math.add" → group="math", cmd="add").
+   *                    Set to 2 for multi-level grouping (e.g., "math.trig.sin" →
+   *                    group="math.trig", cmd="sin").
    */
-  static resolveGroup(moduleId, descriptor) {
+  static resolveGroup(moduleId, descriptor, groupDepth = 1) {
     if (!moduleId) {
       warn("Empty module_id encountered in resolveGroup");
       return [null, ""];
@@ -2269,9 +2798,10 @@ var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
     }
     const cliName = cliDisplay.alias ?? moduleId;
     if (cliName.includes(".")) {
-      const dotIdx = cliName.indexOf(".");
-      const group = cliName.substring(0, dotIdx);
-      const cmd = cliName.substring(dotIdx + 1);
+      const parts = cliName.split(".");
+      const depth = Math.max(1, Math.min(groupDepth, parts.length - 1));
+      const group = parts.slice(0, depth).join(".");
+      const cmd = parts.slice(depth).join(".");
       return [group, cmd];
     }
     return [null, cliName];
@@ -2377,58 +2907,615 @@ var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
   }
 };
 
-// src/discovery.ts
-init_esm_shims();
-init_errors();
-import { Command as Command4 } from "commander";
-var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
-function validateTag(tag) {
-  if (!TAG_PATTERN.test(tag)) {
-    process.stderr.write(
-      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
-`
-    );
-    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
-  }
+// src/main.ts
+var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
+var verboseHelp = false;
+function setVerboseHelp(verbose) {
+  verboseHelp = verbose;
 }
-function collectTag(value, previous) {
-  return previous.concat([value]);
+var docsUrl = null;
+function setDocsUrl(url) {
+  docsUrl = url;
 }
-function registerDiscoveryCommands(cli, registry) {
-  const listCmd = new Command4("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--format <format>", "Output format.", void 0).action((opts) => {
-    for (const t of opts.tag) {
-      validateTag(t);
+function hasVerboseFlag() {
+  return process.argv.includes("--verbose");
+}
+var VERSION = "0.0.0";
+try {
+  const pkg = JSON.parse(readFileSync3(path6.resolve(__dirname3, "../package.json"), "utf-8"));
+  VERSION = pkg.version;
+} catch {
+}
+var ERROR_CODE_MAP = {
+  MODULE_NOT_FOUND: 44,
+  MODULE_LOAD_ERROR: 44,
+  MODULE_DISABLED: 44,
+  SCHEMA_VALIDATION_ERROR: 45,
+  SCHEMA_CIRCULAR_REF: 48,
+  APPROVAL_DENIED: 46,
+  APPROVAL_TIMEOUT: 46,
+  APPROVAL_PENDING: 46,
+  CONFIG_NOT_FOUND: 47,
+  CONFIG_INVALID: 47,
+  MODULE_EXECUTE_ERROR: 1,
+  MODULE_TIMEOUT: 1,
+  ACL_DENIED: 77,
+  CONFIG_NAMESPACE_RESERVED: 78,
+  CONFIG_NAMESPACE_DUPLICATE: 78,
+  CONFIG_ENV_PREFIX_CONFLICT: 78,
+  CONFIG_ENV_MAP_CONFLICT: 78,
+  CONFIG_MOUNT_ERROR: 66,
+  CONFIG_BIND_ERROR: 65,
+  ERROR_FORMATTER_DUPLICATE: 70
+};
+function emitErrorJson(e, exitCode) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  const errRecord = err;
+  const code = errRecord.code ?? "UNKNOWN";
+  const payload = {
+    error: true,
+    code,
+    message: err.message,
+    exit_code: exitCode
+  };
+  for (const field of ["details", "suggestion", "ai_guidance", "retryable", "user_fixable"]) {
+    const val = errRecord[field];
+    if (val !== void 0 && val !== null) {
+      payload[field] = val;
+    }
+  }
+  process.stderr.write(JSON.stringify(payload) + "\n");
+}
+function emitErrorTty(e, exitCode) {
+  const err = e instanceof Error ? e : new Error(String(e));
+  const errRecord = err;
+  const code = errRecord.code;
+  const header = code ? `Error [${code}]: ${err.message}` : `Error: ${err.message}`;
+  process.stderr.write(header + "\n");
+  const details = errRecord.details;
+  if (details && typeof details === "object" && !Array.isArray(details)) {
+    process.stderr.write("\n  Details:\n");
+    for (const [k, v] of Object.entries(details)) {
+      process.stderr.write(`    ${k}: ${v}
+`);
     }
-    const modules = [];
-    for (const m of registry.listModules()) {
-      modules.push(m);
+  }
+  const suggestion = errRecord.suggestion;
+  if (suggestion) {
+    process.stderr.write(`
+  Suggestion: ${suggestion}
+`);
+  }
+  const retryable = errRecord.retryable;
+  if (retryable !== void 0 && retryable !== null) {
+    const label = retryable ? "Yes" : "No (same input will fail again)";
+    process.stderr.write(`  Retryable: ${label}
+`);
+  }
+  process.stderr.write(`
+  Exit code: ${exitCode}
+`);
+}
+function createCli(extensionsDirOrOpts, progName, verbose = false) {
+  let extensionsDir;
+  let registry;
+  let executor;
+  let extraCommands;
+  if (typeof extensionsDirOrOpts === "object" && extensionsDirOrOpts !== null) {
+    extensionsDir = extensionsDirOrOpts.extensionsDir;
+    progName = extensionsDirOrOpts.progName ?? progName;
+    verbose = extensionsDirOrOpts.verbose ?? verbose;
+    registry = extensionsDirOrOpts.registry;
+    executor = extensionsDirOrOpts.executor;
+    extraCommands = extensionsDirOrOpts.extraCommands;
+  } else {
+    extensionsDir = extensionsDirOrOpts;
+  }
+  verboseHelp = verbose;
+  registerConfigNamespace();
+  const resolvedProgName = progName ?? path6.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
+  const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? "WARNING";
+  setLogLevel(cliLogLevel);
+  const program = new Command6(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING").option("--verbose", "Show all options in help output (including built-in apcore options)");
+  if (executor && !registry) {
+    throw new Error("executor requires registry \u2014 pass both or neither");
+  }
+  if (registry) {
+    program._registry = registry;
+    if (executor) {
+      program._executor = executor;
+      registerValidateCommand(program, registry, executor);
+      void registerSystemCommands(program, executor);
+      registerPipelineCommand(program, executor);
     }
-    let filtered = modules;
-    if (opts.tag.length > 0) {
-      const filterTags = new Set(opts.tag);
-      filtered = modules.filter((m) => {
-        const mTags = m.tags ?? [];
-        return [...filterTags].every((t) => mTags.includes(t));
-      });
+  } else {
+    const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
+    void resolvedExtDir;
+  }
+  program.addHelpText("after", [
+    "",
+    "Use --help --verbose to show all options (including built-in apcore options).",
+    "Use --help --man to display a formatted man page."
+  ].join("\n"));
+  registerInitCommand(program);
+  configureManHelp(program, resolvedProgName, VERSION);
+  if (extraCommands && extraCommands.length > 0) {
+    const existingNames = /* @__PURE__ */ new Set([
+      ...BUILTIN_COMMANDS,
+      ...program.commands.map((c) => c.name())
+    ]);
+    for (const cmd of extraCommands) {
+      const cmdName = cmd.name();
+      if (existingNames.has(cmdName)) {
+        process.stderr.write(
+          `Warning: Extra command '${cmdName}' collides with a built-in command and will be skipped.
+`
+        );
+        continue;
+      }
+      program.addCommand(cmd);
+      existingNames.add(cmdName);
     }
-    const fmt = resolveFormat(opts.format);
-    formatModuleList(filtered, fmt, opts.tag.length > 0 ? opts.tag : void 0);
+  }
+  program.hook("preAction", async (thisCommand) => {
+    const opts = thisCommand.opts();
+    const commandsDir = opts.commandsDir;
+    const bindingPath = opts.binding;
+    await applyToolkitIntegration(commandsDir, bindingPath);
   });
-  cli.addCommand(listCmd);
-  const describeCmd = new Command4("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
-    validateModuleId(moduleId);
-    const moduleDef = registry.getModule(moduleId);
-    if (!moduleDef) {
+  return program;
+}
+async function applyToolkitIntegration(commandsDir, bindingPath) {
+  if (!commandsDir && !bindingPath) {
+    return;
+  }
+  try {
+    const toolkitModule = "apcore-toolkit";
+    const toolkit = await import(
+      /* @vite-ignore */
+      toolkitModule
+    );
+    if (commandsDir) {
+      console.warn("Convention scanning not yet available in TypeScript toolkit");
+    }
+    if (bindingPath) {
+      const resolver = new toolkit.DisplayResolver();
+      void resolver;
+    }
+  } catch {
+    console.warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
+  }
+}
+function main(progName) {
+  verboseHelp = hasVerboseFlag();
+  const program = createCli(void 0, progName, verboseHelp);
+  try {
+    program.parse(process.argv);
+  } catch (error2) {
+    if (error2 instanceof CommanderError) {
+      process.exit(error2.exitCode);
+    }
+    const code = exitCodeForError(error2);
+    if (error2 instanceof Error) {
+      process.stderr.write(`Error: ${error2.message}
+`);
+    }
+    process.exit(code);
+  }
+}
+function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName, verbose = verboseHelp) {
+  const moduleId = moduleDef.id;
+  let resolvedSchema = {};
+  let schemaOptions = [];
+  const display = getDisplay(moduleDef);
+  const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+  const effectiveCmdName = cmdName ?? cliDisplay.alias ?? moduleId;
+  const cmdHelp = cliDisplay.description ?? moduleDef.description;
+  const inputSchema = moduleDef.inputSchema;
+  if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
+    try {
+      resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
+    } catch {
+      resolvedSchema = inputSchema;
+    }
+    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
+  }
+  const cmd = new Command6(effectiveCmdName).description(cmdHelp);
+  const inputOpt = new Option4("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
+  const yesOpt = new Option4("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
+  const largeInputOpt = new Option4("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
+  const formatOpt = new Option4("--format <format>", "Output format: json, table, csv, yaml, jsonl.").choices(["json", "table", "csv", "yaml", "jsonl"]);
+  const fieldsOpt = new Option4("--fields <fields>", "Comma-separated dot-paths to select from the result (e.g., 'status,data.count').");
+  const sandboxOpt = new Option4("--sandbox", "Run module in an isolated subprocess with restricted filesystem and env access").default(false).hideHelp();
+  const dryRunOpt = new Option4("--dry-run", "Run preflight checks without executing the module. Shows validation results.").default(false);
+  const traceOpt = new Option4("--trace", "Show execution pipeline trace with per-step timing after the result.").default(false);
+  const streamOpt = new Option4("--stream", "Stream module output as JSONL (one JSON object per line, flushed immediately).").default(false);
+  const strategyOpt = new Option4("--strategy <name>", "Execution pipeline strategy: standard (default), internal, testing, performance.").choices(["standard", "internal", "testing", "performance", "minimal"]);
+  const approvalTimeoutOpt = new Option4("--approval-timeout <seconds>", "Override approval prompt timeout in seconds (default: 60).").argParser(parseInt);
+  const approvalTokenOpt = new Option4("--approval-token <token>", "Resume a pending approval with the given token (for async approval flows).");
+  if (!verbose) {
+    inputOpt.hideHelp();
+    yesOpt.hideHelp();
+    largeInputOpt.hideHelp();
+    formatOpt.hideHelp();
+    fieldsOpt.hideHelp();
+    dryRunOpt.hideHelp();
+    traceOpt.hideHelp();
+    streamOpt.hideHelp();
+    strategyOpt.hideHelp();
+    approvalTimeoutOpt.hideHelp();
+    approvalTokenOpt.hideHelp();
+  }
+  cmd.addOption(inputOpt);
+  cmd.addOption(yesOpt);
+  cmd.addOption(largeInputOpt);
+  cmd.addOption(formatOpt);
+  cmd.addOption(fieldsOpt);
+  cmd.addOption(sandboxOpt);
+  cmd.addOption(dryRunOpt);
+  cmd.addOption(traceOpt);
+  cmd.addOption(streamOpt);
+  cmd.addOption(strategyOpt);
+  cmd.addOption(approvalTimeoutOpt);
+  cmd.addOption(approvalTokenOpt);
+  const footerParts = [];
+  if (!verbose) {
+    footerParts.push("Use --verbose to show all options (including built-in apcore options).");
+  }
+  if (docsUrl) {
+    footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);
+  }
+  if (footerParts.length > 0) {
+    cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
+  }
+  const reservedNames = /* @__PURE__ */ new Set([
+    "input",
+    "yes",
+    "largeInput",
+    "format",
+    "fields",
+    "sandbox",
+    "verbose",
+    "dryRun",
+    "trace",
+    "stream",
+    "strategy",
+    "approvalTimeout",
+    "approvalToken"
+  ]);
+  for (const opt of schemaOptions) {
+    if (reservedNames.has(opt.name)) {
       process.stderr.write(
-        `Error: Module '${moduleId}' not found.
+        `Error: Module '${moduleId}' schema property '${opt.name}' conflicts with a reserved CLI option name. Rename the property.
 `
       );
-      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+  }
+  for (const opt of schemaOptions) {
+    if (opt.parseArg) {
+      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
+    } else {
+      cmd.option(opt.flags, opt.description, opt.defaultValue);
+    }
+  }
+  cmd.action(async (options) => {
+    const stdinFlag = options.input;
+    const autoApprove = options.yes;
+    const largeInput = options.largeInput;
+    const outputFormat = options.format;
+    const outputFields = options.fields;
+    const sandboxEnabled = options.sandbox;
+    const dryRun = options.dryRun;
+    const traceFlag = options.trace;
+    const streamFlag = options.stream;
+    const strategyName = options.strategy;
+    const approvalTimeout = options.approvalTimeout ?? 60;
+    const approvalToken = options.approvalToken;
+    const schemaKwargs = {};
+    const builtinKeys = /* @__PURE__ */ new Set([
+      "input",
+      "yes",
+      "largeInput",
+      "format",
+      "fields",
+      "sandbox",
+      "verbose",
+      "dryRun",
+      "trace",
+      "stream",
+      "strategy",
+      "approvalTimeout",
+      "approvalToken"
+    ]);
+    for (const [k, v] of Object.entries(options)) {
+      if (!builtinKeys.has(k)) {
+        schemaKwargs[k] = v;
+      }
+    }
+    let merged = {};
+    try {
+      merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
+      const reconverted = reconvertEnumValues(merged, schemaOptions);
+      merged = reconverted;
+      if (dryRun) {
+        if (!executor.validate) {
+          process.stderr.write("Error: Executor does not support validate.\n");
+          process.exit(1);
+        }
+        const preflight = await executor.validate(moduleId, merged);
+        formatPreflightResult(preflight, outputFormat);
+        if (traceFlag) {
+          const pureSteps = /* @__PURE__ */ new Set([
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "input_validation"
+          ]);
+          const allSteps = [
+            "context_creation",
+            "call_chain_guard",
+            "module_lookup",
+            "acl_check",
+            "approval_gate",
+            "middleware_before",
+            "input_validation",
+            "execute",
+            "output_validation",
+            "middleware_after",
+            "return_result"
+          ];
+          process.stderr.write("\nPipeline preview (dry-run):\n");
+          for (const s of allSteps) {
+            if (pureSteps.has(s)) {
+              process.stderr.write(`  \u2713 ${s.padEnd(24)} (pure \u2014 would execute)
+`);
+            } else {
+              process.stderr.write(`  \u25CB ${s.padEnd(24)} (impure \u2014 skipped in dry-run)
+`);
+            }
+          }
+        }
+        process.exit(preflight.valid ? 0 : firstFailedExitCode(preflight));
+      }
+      if (approvalToken) {
+        merged._approval_token = approvalToken;
+      }
+      await checkApproval(moduleDef, autoApprove, approvalTimeout);
+      const startTime = performance.now();
+      if (streamFlag) {
+        if (resolveFormat(outputFormat) === "table") {
+          process.stderr.write("Warning: Streaming mode always outputs JSONL; --format table is ignored.\n");
+        }
+        const annotations = moduleDef.annotations;
+        const isStreaming = annotations?.streaming === true;
+        if (!isStreaming) {
+          process.stderr.write(
+            `Warning: Module '${moduleId}' does not declare streaming support. Falling back to standard execution.
+`
+          );
+        }
+        if (isStreaming && executor.stream) {
+          let chunks = 0;
+          for await (const chunk of executor.stream(moduleId, merged)) {
+            chunks++;
+            process.stdout.write(JSON.stringify(chunk) + "\n");
+            if (process.stderr.isTTY) {
+              process.stderr.write(`\rStreaming ${moduleId}... (${chunks} chunks)`);
+            }
+          }
+          if (process.stderr.isTTY) {
+            process.stderr.write("\n");
+          }
+          const durationMs2 = Math.round(performance.now() - startTime);
+          const { getAuditLogger: getAuditLogger3 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+          const auditLogger2 = getAuditLogger3();
+          if (auditLogger2) {
+            auditLogger2.logExecution(moduleId, merged, "success", 0, durationMs2);
+          }
+          return;
+        }
+      }
+      if (traceFlag && executor.callWithTrace) {
+        const [result2, trace] = await executor.callWithTrace(
+          moduleId,
+          merged,
+          strategyName ? { strategy: strategyName } : void 0
+        );
+        const durationMs2 = Math.round(performance.now() - startTime);
+        const { getAuditLogger: getAuditLogger3 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const auditLogger2 = getAuditLogger3();
+        if (auditLogger2) {
+          auditLogger2.logExecution(moduleId, merged, "success", 0, durationMs2);
+        }
+        const resolved = resolveFormat(outputFormat);
+        if (resolved === "json" || !process.stdout.isTTY) {
+          const traceData = {
+            strategy: trace.strategy_name,
+            total_duration_ms: trace.total_duration_ms,
+            success: trace.success,
+            steps: trace.steps.map((s) => ({
+              name: s.name,
+              duration_ms: s.duration_ms,
+              skipped: s.skipped,
+              ...s.skipped ? { skip_reason: s.skip_reason } : {}
+            }))
+          };
+          let output;
+          if (typeof result2 === "object" && result2 !== null && !Array.isArray(result2)) {
+            output = { ...result2, _trace: traceData };
+          } else {
+            output = { result: result2, _trace: traceData };
+          }
+          process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+        } else {
+          formatExecResult(result2, outputFormat, outputFields);
+          const stepCount = trace.steps.length;
+          process.stderr.write(
+            `
+Pipeline Trace (strategy: ${trace.strategy_name}, ${stepCount} steps, ${trace.total_duration_ms.toFixed(1)}ms)
+`
+          );
+          for (const s of trace.steps) {
+            if (s.skipped) {
+              const reason = s.skip_reason ?? "n/a";
+              process.stderr.write(`  \u25CB ${s.name.padEnd(24)} ${"\u2014".padStart(8)}  skipped (${reason})
+`);
+            } else {
+              process.stderr.write(`  \u2713 ${s.name.padEnd(24)} ${(s.duration_ms.toFixed(1) + "ms").padStart(8)}
+`);
+            }
+          }
+        }
+        return;
+      }
+      let result;
+      if (strategyName && executor.callWithTrace) {
+        const [res] = await executor.callWithTrace(
+          moduleId,
+          merged,
+          { strategy: strategyName }
+        );
+        result = res;
+        if (strategyName !== "standard" && process.stderr.isTTY) {
+          process.stderr.write(`Warning: Using '${strategyName}' strategy.
+`);
+        }
+      } else {
+        const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
+        const sandbox = new Sandbox2(sandboxEnabled);
+        result = await sandbox.execute(moduleId, merged, executor);
+      }
+      const durationMs = Math.round(performance.now() - startTime);
+      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+      const auditLogger = getAuditLogger2();
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, merged, "success", 0, durationMs);
+      }
+      formatExecResult(result, outputFormat, outputFields);
+    } catch (err) {
+      const errRecord = err;
+      const errorCode = typeof errRecord?.code === "string" ? errRecord.code : void 0;
+      const exitCode = errorCode && errorCode in ERROR_CODE_MAP ? ERROR_CODE_MAP[errorCode] : exitCodeForError(err);
+      try {
+        const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+        const auditLogger = getAuditLogger2();
+        if (auditLogger) {
+          auditLogger.logExecution(moduleId, merged, "error", exitCode, 0);
+        }
+      } catch {
+      }
+      if (outputFormat === "json" || !process.stderr.isTTY) {
+        emitErrorJson(err, exitCode);
+      } else {
+        emitErrorTty(err, exitCode);
+      }
+      process.exit(exitCode);
     }
-    const fmt = resolveFormat(opts.format);
-    formatModuleDetail(moduleDef, fmt);
   });
-  cli.addCommand(describeCmd);
+  return cmd;
+}
+function validateModuleId(moduleId) {
+  if (moduleId.length > 128) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(moduleId)) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+}
+async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
+  const cliKwargsNonNull = {};
+  for (const [k, v] of Object.entries(cliKwargs)) {
+    if (v !== null && v !== void 0) {
+      cliKwargsNonNull[k] = v;
+    }
+  }
+  if (!stdinFlag) {
+    return cliKwargsNonNull;
+  }
+  if (stdinFlag === "-") {
+    const raw = await readStdin();
+    const rawSize = Buffer.byteLength(raw, "utf-8");
+    if (rawSize > 10485760 && !largeInput) {
+      process.stderr.write(
+        "Error: STDIN input exceeds 10MB limit. Use --large-input to override.\n"
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    if (!raw) {
+      return cliKwargsNonNull;
+    }
+    let stdinData;
+    try {
+      stdinData = JSON.parse(raw);
+    } catch {
+      process.stderr.write(
+        "Error: STDIN does not contain valid JSON.\n"
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    if (typeof stdinData !== "object" || stdinData === null || Array.isArray(stdinData)) {
+      process.stderr.write(
+        `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? "array" : typeof stdinData}.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    return { ...stdinData, ...cliKwargsNonNull };
+  }
+  return cliKwargsNonNull;
+}
+function readStdin() {
+  return new Promise((resolve3, reject) => {
+    const chunks = [];
+    const onData = (chunk) => chunks.push(chunk);
+    const onEnd = () => {
+      cleanup();
+      resolve3(Buffer.concat(chunks).toString("utf-8"));
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(err);
+    };
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.removeListener("end", onEnd);
+      process.stdin.removeListener("error", onError);
+    };
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    process.stdin.on("error", onError);
+    process.stdin.resume();
+  });
+}
+function reconvertEnumValues(kwargs, options) {
+  const result = { ...kwargs };
+  for (const opt of options) {
+    if (!opt.enumOriginalTypes) continue;
+    const paramName = opt.name;
+    if (!(paramName in result) || result[paramName] === null || result[paramName] === void 0) {
+      continue;
+    }
+    const strVal = String(result[paramName]);
+    const origType = opt.enumOriginalTypes[strVal];
+    if (origType === "int") {
+      result[paramName] = parseInt(strVal, 10);
+    } else if (origType === "float") {
+      result[paramName] = parseFloat(strVal);
+    } else if (origType === "bool") {
+      result[paramName] = strVal.toLowerCase() === "true";
+    }
+  }
+  return result;
 }
 
 // src/index.ts
@@ -2441,6 +3528,7 @@ export {
   AuthProvider,
   AuthenticationError,
   BUILTIN_COMMANDS,
+  CliApprovalHandler,
   ConfigDecryptionError,
   ConfigEncryptor,
   ConfigResolver,
@@ -2462,12 +3550,16 @@ export {
   createCli,
   debug,
   docsUrl,
+  emitErrorJson,
+  emitErrorTty,
   error,
   exitCodeForError,
   extractHelp,
+  firstFailedExitCode,
   formatExecResult,
   formatModuleDetail,
   formatModuleList,
+  formatPreflightResult,
   getAuditLogger,
   getCliDisplayFields,
   getDisplay,
@@ -2479,7 +3571,10 @@ export {
   registerConfigNamespace,
   registerDiscoveryCommands,
   registerInitCommand,
+  registerPipelineCommand,
   registerShellCommands,
+  registerSystemCommands,
+  registerValidateCommand,
   resolveFormat,
   resolveRefs,
   schemaToCliOptions,