apcore-cli 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to apcore-cli (TypeScript SDK) will be documented in this fi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-03-29
+
+### Added
+- **Verbose help mode** — Built-in apcore options (`--input`, `--yes`, `--large-input`, `--format`, `--sandbox`) are now hidden from `--help` output by default. Pass `--help --verbose` to display the full option list including built-in options.
+- **Universal man page generation** — `buildProgramManPage()` generates a complete roff man page covering all registered commands. `configureManHelp()` adds `--help --man` support to any Commander program, enabling downstream projects to get man pages for free.
+- **Documentation URL support** — `setDocsUrl()` sets a base URL for online docs. Per-command help shows `Docs: {url}/commands/{name}`, man page SEE ALSO includes `Full documentation at {url}`. No default — disabled when not set.
+
+### Changed
+- `buildModuleCommand()` accepts optional `verboseHelp` parameter to control built-in option visibility in help.
+- `--sandbox` is now always hidden from help (not yet implemented). Only four built-in options (`--input`, `--yes`, `--large-input`, `--format`) toggle with `--verbose`.
+- Improved built-in option descriptions for clarity (e.g., `--input` now reads "Read JSON input from a file path, or use '-' to read from stdin pipe").
+
 ## [0.3.2] - 2026-03-28
 
 ### Fixed

package/README.md

@@ -148,6 +148,8 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 | `--log-level` | `WARNING` | Logging: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
 | `--version` | | Show version and exit |
 | `--help` | | Show help and exit |
+| `--verbose` | | Show all options in help (including built-in apcore options) |
+| `--man` | | Output man page in roff format (use with `--help`) |
 
 ### Built-in Commands
 
@@ -161,7 +163,7 @@ apcore-cli [OPTIONS] COMMAND [ARGS]
 
 ### Module Execution Options
 
-When executing a module (e.g. `apcore-cli math.add`), these built-in options are always available:
+When executing a module (e.g. `apcore-cli math.add`), these built-in options are available (hidden by default; use `--verbose` to show in `--help`):
 
 | Option | Description |
 |--------|-------------|
@@ -169,7 +171,7 @@ When executing a module (e.g. `apcore-cli math.add`), these built-in options are
 | `--yes` / `-y` | Bypass approval prompts |
 | `--large-input` | Allow STDIN input larger than 10MB |
 | `--format` | Output format: `json` or `table` |
-| `--sandbox` | Run module in subprocess sandbox |
+| `--sandbox` | Run module in subprocess sandbox (not yet implemented — always hidden) |
 
 Schema-generated flags (e.g. `--a`, `--b`) are added automatically from the module's `input_schema`.
 
@@ -234,7 +236,8 @@ cli:
 - **Schema validation** -- inputs validated against JSON Schema before execution, with `$ref`/`allOf`/`anyOf`/`oneOf` resolution
 - **Security** -- API key auth (keyring + AES-256-GCM), append-only audit logging, subprocess sandboxing
 - **Shell completions** -- `apcore-cli completion bash|zsh|fish` generates completion scripts with dynamic module ID completion
-- **Man pages** -- `apcore-cli man <command>` generates roff-formatted man pages
+- **Man pages** -- `apcore-cli man <command>` for single commands, or `--help --man` for a complete program man page. `configureManHelp()` provides one-line integration for downstream projects
+- **Documentation URL** -- `setDocsUrl()` adds doc links to help footers and man pages
 - **Audit logging** -- all executions logged to `~/.apcore-cli/audit.jsonl` with SHA-256 input hashing
 
 ## How It Works
@@ -274,7 +277,7 @@ apcore Registry + Executor (your modules, unchanged)
 
 **Classes:** `LazyModuleGroup`, `ConfigResolver`, `AuthProvider`, `ConfigEncryptor`, `AuditLogger`, `Sandbox`
 
-**Functions:** `createCli`, `main`, `buildModuleCommand`, `validateModuleId`, `collectInput`, `schemaToCliOptions`, `reconvertEnumValues`, `resolveRefs`, `checkApproval`, `resolveFormat`, `formatModuleList`, `formatModuleDetail`, `formatExecResult`, `registerDiscoveryCommands`, `registerShellCommands`, `setAuditLogger`, `getAuditLogger`, `exitCodeForError`, `mapType`, `extractHelp`, `truncate`
+**Functions:** `createCli`, `main`, `buildModuleCommand`, `validateModuleId`, `collectInput`, `schemaToCliOptions`, `reconvertEnumValues`, `resolveRefs`, `checkApproval`, `resolveFormat`, `formatModuleList`, `formatModuleDetail`, `formatExecResult`, `registerDiscoveryCommands`, `registerShellCommands`, `setAuditLogger`, `getAuditLogger`, `setVerboseHelp`, `setDocsUrl`, `buildProgramManPage`, `configureManHelp`, `exitCodeForError`, `mapType`, `extractHelp`, `truncate`
 
 **Errors:** `ApprovalTimeoutError`, `ApprovalDeniedError`, `AuthenticationError`, `ConfigDecryptionError`, `ModuleExecutionError`, `ModuleNotFoundError`, `SchemaValidationError`
 

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,13 @@ 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_MOUNT_ERROR: 66,
+      CONFIG_BIND_ERROR: 65,
+      ERROR_FORMATTER_DUPLICATE: 70,
       KEYBOARD_INTERRUPT: 130
     };
   }
@@ -131,10 +152,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 } from "commander";
+import { readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import * as path4 from "path";
+import { Command as Command2, CommanderError, Option as Option2 } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -309,22 +330,222 @@ 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"
+        }
+      });
+    }
+  } 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/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) {
-  const resolvedProgName = progName ?? path3.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
+function createCli(extensionsDir, progName, verbose = false) {
+  verboseHelp = verbose;
+  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");
+  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;
@@ -355,7 +576,8 @@ async function applyToolkitIntegration(commandsDir, bindingPath) {
   }
 }
 function main(progName) {
-  const program = createCli(void 0, progName);
+  verboseHelp = hasVerboseFlag();
+  const program = createCli(void 0, progName, verboseHelp);
   try {
     program.parse(process.argv);
   } catch (error) {