apcore-cli 0.4.0 → 0.6.0

package/dist/bin/apcore-cli.js

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -46,11 +52,19 @@ function exitCodeForError(error) {
       SCHEMA_CIRCULAR_REF: EXIT_CODES.SCHEMA_CIRCULAR_REF,
       APPROVAL_DENIED: EXIT_CODES.APPROVAL_DENIED,
       APPROVAL_TIMEOUT: EXIT_CODES.APPROVAL_TIMEOUT,
+      APPROVAL_PENDING: EXIT_CODES.APPROVAL_DENIED,
       CONFIG_NOT_FOUND: EXIT_CODES.CONFIG_NOT_FOUND,
       CONFIG_INVALID: EXIT_CODES.CONFIG_INVALID,
       MODULE_EXECUTE_ERROR: EXIT_CODES.MODULE_EXECUTE_ERROR,
       MODULE_TIMEOUT: EXIT_CODES.MODULE_TIMEOUT,
-      ACL_DENIED: EXIT_CODES.ACL_DENIED
+      ACL_DENIED: EXIT_CODES.ACL_DENIED,
+      // Config Bus errors (apcore >= 0.15.0)
+      CONFIG_NAMESPACE_RESERVED: EXIT_CODES.CONFIG_NAMESPACE_RESERVED,
+      CONFIG_NAMESPACE_DUPLICATE: EXIT_CODES.CONFIG_NAMESPACE_DUPLICATE,
+      CONFIG_ENV_PREFIX_CONFLICT: EXIT_CODES.CONFIG_ENV_PREFIX_CONFLICT,
+      CONFIG_MOUNT_ERROR: EXIT_CODES.CONFIG_MOUNT_ERROR,
+      CONFIG_BIND_ERROR: EXIT_CODES.CONFIG_BIND_ERROR,
+      ERROR_FORMATTER_DUPLICATE: EXIT_CODES.ERROR_FORMATTER_DUPLICATE
     };
     if (code && code in codeMap) {
       return codeMap[code];
@@ -120,6 +134,14 @@ var init_errors = __esm({
       CONFIG_INVALID: 47,
       SCHEMA_CIRCULAR_REF: 48,
       ACL_DENIED: 77,
+      // Config Bus errors (apcore >= 0.15.0)
+      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,
       KEYBOARD_INTERRUPT: 130
     };
   }
@@ -131,10 +153,10 @@ init_esm_shims();
 // src/main.ts
 init_esm_shims();
 init_errors();
-import { readFileSync } from "fs";
-import { fileURLToPath as fileURLToPath2 } from "url";
-import * as path3 from "path";
-import { Command, CommanderError, Option } from "commander";
+import { readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import * as path4 from "path";
+import { Command as Command6, CommanderError, Option as Option4 } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -151,6 +173,188 @@ import * as readline from "readline";
 
 // src/output.ts
 init_esm_shims();
+function resolveFormat(explicitFormat) {
+  if (explicitFormat !== void 0) {
+    return explicitFormat;
+  }
+  return process.stdout.isTTY ? "table" : "json";
+}
+function formatTable(headers, rows) {
+  const colWidths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const sep2 = colWidths.map((w) => "-".repeat(w)).join("  ");
+  const headerLine = headers.map((h, i) => h.padEnd(colWidths[i])).join("  ");
+  const dataLines = rows.map(
+    (row) => row.map((cell, i) => (cell ?? "").padEnd(colWidths[i])).join("  ")
+  );
+  return [headerLine, sep2, ...dataLines].join("\n") + "\n";
+}
+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 === "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 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 {
+    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();
@@ -162,6 +366,13 @@ function setLogLevel(level) {
     currentLevel = upper;
   }
 }
+function shouldLog(level) {
+  return LEVELS[level] >= LEVELS[currentLevel];
+}
+function debug(message) {
+  if (shouldLog("DEBUG")) process.stderr.write(`DEBUG: ${message}
+`);
+}
 
 // src/init-cmd.ts
 init_esm_shims();
@@ -309,27 +520,766 @@ function createBindingModule(moduleId, prefix, funcName, description, outputDir)
 // src/display-helpers.ts
 init_esm_shims();
 
-// src/main.ts
+// src/config.ts
+init_esm_shims();
+import * as fs2 from "fs";
+import yaml from "js-yaml";
+var NAMESPACE_TO_LEGACY = {
+  "apcore-cli.stdin_buffer_limit": "cli.stdin_buffer_limit",
+  "apcore-cli.auto_approve": "cli.auto_approve",
+  "apcore-cli.help_text_max_length": "cli.help_text_max_length",
+  "apcore-cli.logging_level": "logging.level"
+};
+var LEGACY_TO_NAMESPACE = Object.fromEntries(
+  Object.entries(NAMESPACE_TO_LEGACY).map(([k, v]) => [v, k])
+);
+function registerConfigNamespace() {
+  try {
+    const { Config } = __require("apcore-js");
+    if (typeof Config?.registerNamespace === "function") {
+      Config.registerNamespace({
+        name: "apcore-cli",
+        envPrefix: "APCORE_CLI",
+        defaults: {
+          stdin_buffer_limit: 10485760,
+          auto_approve: false,
+          help_text_max_length: 1e3,
+          logging_level: "WARNING",
+          approval_timeout: 60,
+          strategy: "standard",
+          group_depth: 1
+        }
+      });
+    }
+  } catch {
+  }
+}
+
+// src/shell.ts
+init_esm_shims();
+init_errors();
+import { readFileSync as readFileSync2 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import * as path3 from "path";
+import { spawnSync } from "child_process";
+import { Command, Help, Option } from "commander";
 var __dirname2 = path3.dirname(fileURLToPath2(import.meta.url));
+var SHELL_VERSION = "0.0.0";
+try {
+  const pkg = JSON.parse(readFileSync2(path3.resolve(__dirname2, "../package.json"), "utf-8"));
+  SHELL_VERSION = pkg.version;
+} catch {
+}
+function roffEscape(s) {
+  return s.replace(/\\/g, "\\\\").replace(/-/g, "\\-").replace(/'/g, "\\(aq");
+}
+function buildProgramManPage(program, progName, version, description, docsUrl) {
+  const help = new Help();
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const s = [];
+  const resolvedDesc = description ?? program.description() ?? `${progName} CLI`;
+  s.push(`.TH "${progName.toUpperCase()}" "1" "${today}" "${progName} ${version}" "${progName} Manual"`);
+  s.push(".SH NAME");
+  s.push(`${progName} \\- ${roffEscape(resolvedDesc)}`);
+  s.push(".SH SYNOPSIS");
+  s.push(`\\fB${progName}\\fR [\\fIglobal\\-options\\fR] \\fIcommand\\fR [\\fIcommand\\-options\\fR]`);
+  if (resolvedDesc) {
+    s.push(".SH DESCRIPTION");
+    s.push(roffEscape(resolvedDesc));
+  }
+  const globalOpts = help.visibleOptions(program).filter((o) => !["help", "version", "all", "man"].includes(o.long?.replace("--", "") ?? ""));
+  if (globalOpts.length > 0) {
+    s.push(".SH GLOBAL OPTIONS");
+    for (const opt of globalOpts) {
+      const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+      s.push(".TP");
+      s.push(`\\fB${roffEscape(flag)}\\fR`);
+      if (opt.description) s.push(roffEscape(opt.description));
+    }
+  }
+  const allCommands = help.visibleCommands(program);
+  if (allCommands.length > 0) {
+    s.push(".SH COMMANDS");
+    for (const cmd of allCommands) {
+      if (cmd.name() === "help") continue;
+      const desc = help.subcommandDescription(cmd);
+      s.push(".TP");
+      s.push(`\\fB${progName} ${roffEscape(cmd.name())}\\fR`);
+      if (desc) s.push(roffEscape(desc));
+      const cmdHelp = new Help();
+      const opts = cmdHelp.visibleOptions(cmd).filter((o) => !["help", "version"].includes(o.long?.replace("--", "") ?? ""));
+      for (const opt of opts) {
+        const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+        s.push(".RS");
+        s.push(".TP");
+        s.push(`\\fB${roffEscape(flag)}\\fR`);
+        if (opt.description) s.push(roffEscape(opt.description));
+        s.push(".RE");
+      }
+      const subCmds = cmdHelp.visibleCommands(cmd).filter((c) => c.name() !== "help");
+      for (const sub of subCmds) {
+        const subDesc = help.subcommandDescription(sub);
+        s.push(".TP");
+        s.push(`\\fB${progName} ${roffEscape(cmd.name())} ${roffEscape(sub.name())}\\fR`);
+        if (subDesc) s.push(roffEscape(subDesc));
+        const subOpts = cmdHelp.visibleOptions(sub).filter((o) => !["help", "version"].includes(o.long?.replace("--", "") ?? ""));
+        for (const opt of subOpts) {
+          const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+          s.push(".RS");
+          s.push(".TP");
+          s.push(`\\fB${roffEscape(flag)}\\fR`);
+          if (opt.description) s.push(roffEscape(opt.description));
+          s.push(".RE");
+        }
+      }
+    }
+  }
+  s.push(".SH ENVIRONMENT");
+  s.push(".TP");
+  s.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
+  s.push("Path to the apcore extensions directory.");
+  s.push(".TP");
+  s.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
+  s.push("Set to \\fB1\\fR to bypass approval prompts.");
+  s.push(".TP");
+  s.push("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR");
+  s.push("CLI\\-specific logging verbosity (DEBUG|INFO|WARNING|ERROR).");
+  s.push(".SH EXIT CODES");
+  const exitCodes = [
+    ["0", "Success."],
+    ["1", "Module execution error."],
+    ["2", "Invalid CLI input or missing argument."],
+    ["44", "Module not found, disabled, or failed to load."],
+    ["45", "Input failed JSON Schema validation."],
+    ["46", "Approval denied or timed out."],
+    ["47", "Configuration error."],
+    ["77", "ACL denied."],
+    ["130", "Cancelled by user (SIGINT)."]
+  ];
+  for (const [code, meaning] of exitCodes) {
+    s.push(`.TP
+\\fB${code}\\fR
+${meaning}`);
+  }
+  s.push(".SH SEE ALSO");
+  s.push(`\\fB${progName} \\-\\-help \\-\\-verbose\\fR for full option list.`);
+  if (docsUrl) {
+    s.push(`.PP
+Full documentation at \\fI${roffEscape(docsUrl)}\\fR`);
+  }
+  return s.join("\n");
+}
+function configureManHelp(program, progName, version, description, docsUrl) {
+  const manOpt = new Option("--man", "Output man page in roff format (use with --help)").hideHelp();
+  program.addOption(manOpt);
+  program.addHelpText("beforeAll", () => {
+    if (program.opts().man) {
+      const roff = buildProgramManPage(program, progName, version, description, docsUrl) + "\n";
+      if (process.stdout.isTTY) {
+        const pagers = [
+          { cmd: "mandoc", args: ["-a"] },
+          { cmd: "groff", args: ["-man", "-Tutf8"] }
+        ];
+        let rendered = false;
+        for (const { cmd, args } of pagers) {
+          const result = spawnSync(cmd, args, {
+            input: roff,
+            stdio: ["pipe", "pipe", "pipe"],
+            encoding: "utf-8"
+          });
+          if (result.status === 0 && result.stdout) {
+            const pager = process.env.PAGER || "less";
+            const pagerResult = spawnSync(pager, ["-R"], {
+              input: result.stdout,
+              stdio: ["pipe", "inherit", "inherit"]
+            });
+            if (pagerResult.status !== null) {
+              rendered = true;
+              break;
+            }
+          }
+        }
+        if (!rendered) {
+          process.stdout.write(roff);
+        }
+      } else {
+        process.stdout.write(roff);
+      }
+      process.exit(0);
+    }
+    return "";
+  });
+}
+
+// src/discovery.ts
+init_esm_shims();
+init_errors();
+import { Command as Command2, Option as Option2 } from "commander";
+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);
+    }
+    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);
+    }
+    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 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.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 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})
+`);
+    }
+  }
+}
+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;
+  }
+  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)}
+`
+    );
+  }
+  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 {
+      await callSystemModule(executor, "system.health.summary", { include_healthy: true });
+    }
+  } catch {
+    debug("System modules not available; skipping system command registration.");
+    return;
+  }
+  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 {
+      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
+        });
+      }
+      if (fmt === "json" || !process.stdout.isTTY) {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else if (moduleId) {
+        formatExecResult(result, fmt);
+      } else {
+        formatUsageSummaryTty(result);
+      }
+    } 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}
+`);
+      }
+    } catch (e) {
+      process.stderr.write(`Error: ${e instanceof Error ? e.message : e}
+`);
+      process.exit(1);
+    }
+  });
+  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");
+    }
+    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);
+    }
+  });
+  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");
+    }
+    const fmt = resolveFormat(opts.format);
+    try {
+      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 {
+      parsedValue = value;
+    }
+    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);
+    }
+  });
+  configGroup.addCommand(configSetCmd);
+  cli.addCommand(configGroup);
+}
+
+// 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;
+      }
+    }
+    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;
+    }
+    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 Command5 } from "commander";
+var BUILTIN_COMMANDS = [
+  "completion",
+  "config",
+  "describe",
+  "describe-pipeline",
+  "disable",
+  "enable",
+  "exec",
+  "health",
+  "init",
+  "list",
+  "man",
+  "reload",
+  "usage",
+  "validate"
+];
+
+// src/main.ts
+var __dirname3 = path4.dirname(fileURLToPath3(import.meta.url));
 var verboseHelp = false;
 function hasVerboseFlag() {
   return process.argv.includes("--verbose");
 }
 var VERSION = "0.0.0";
 try {
-  const pkg = JSON.parse(readFileSync(path3.resolve(__dirname2, "../package.json"), "utf-8"));
+  const pkg = JSON.parse(readFileSync3(path4.resolve(__dirname3, "../package.json"), "utf-8"));
   VERSION = pkg.version;
 } catch {
 }
-function createCli(extensionsDir, progName, verbose = false) {
+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;
-  const resolvedProgName = progName ?? path3.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
+  registerConfigNamespace();
+  const resolvedProgName = progName ?? path4.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 Command(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;
+  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);
+    }
+  } 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);
+    }
+  }
   program.hook("preAction", async (thisCommand) => {
     const opts = thisCommand.opts();
     const commandsDir = opts.commandsDir;
@@ -376,6 +1326,87 @@ function main(progName) {
     process.exit(code);
   }
 }
+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();
+  });
+}
 
 // bin/apcore-cli.ts
 main("apcore-cli");