apcore-cli 0.3.2 → 0.4.0

package/dist/index.js

@@ -494,7 +494,7 @@ init_errors();
 import { readFileSync } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import * as path5 from "path";
-import { Command, CommanderError } from "commander";
+import { Command, CommanderError, Option } from "commander";
 
 // src/ref-resolver.ts
 init_esm_shims();
@@ -1220,17 +1220,29 @@ function getCliDisplayFields(descriptor) {
 
 // src/main.ts
 var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
+var verboseHelp = false;
+function setVerboseHelp(verbose) {
+  verboseHelp = verbose;
+}
+var docsUrl = null;
+function setDocsUrl(url) {
+  docsUrl = url;
+}
+function hasVerboseFlag() {
+  return process.argv.includes("--verbose");
+}
 var VERSION = "0.0.0";
 try {
   const pkg = JSON.parse(readFileSync(path5.resolve(__dirname2, "../package.json"), "utf-8"));
   VERSION = pkg.version;
 } catch {
 }
-function createCli(extensionsDir, progName) {
+function createCli(extensionsDir, progName, verbose = false) {
+  verboseHelp = verbose;
   const resolvedProgName = progName ?? path5.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 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;
   registerInitCommand(program);
@@ -1264,7 +1276,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 (error2) {
@@ -1279,7 +1292,7 @@ function main(progName) {
     process.exit(code);
   }
 }
-function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName) {
+function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName, verbose = verboseHelp) {
   const moduleId = moduleDef.id;
   let resolvedSchema = {};
   let schemaOptions = [];
@@ -1297,11 +1310,32 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
   }
   const cmd = new Command(effectiveCmdName).description(cmdHelp);
-  cmd.option("--input <source>", "Read input from STDIN ('-')");
-  cmd.option("-y, --yes", "Bypass approval prompts", false);
-  cmd.option("--large-input", "Allow STDIN input larger than 10MB", false);
-  cmd.option("--format <format>", "Output format (json|table)");
-  cmd.option("--sandbox", "Run module in subprocess sandbox", false);
+  const inputOpt = new Option("--input <source>", "Read JSON input from a file path, or use '-' to read from stdin pipe");
+  const yesOpt = new Option("-y, --yes", "Skip interactive approval prompts (for scripts and CI)").default(false);
+  const largeInputOpt = new Option("--large-input", "Allow stdin input larger than 10MB (default limit protects against accidental pipes)").default(false);
+  const formatOpt = new Option("--format <format>", "Set output format: 'json' for machine-readable, 'table' for human-readable");
+  const sandboxOpt = new Option("--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}`);
+  }
+  if (footerParts.length > 0) {
+    cmd.addHelpText("after", "\n" + footerParts.join("\n") + "\n");
+  }
   for (const opt of schemaOptions) {
     if (opt.parseArg) {
       cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
@@ -1316,7 +1350,7 @@ function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdNam
     const outputFormat = options.format;
     const sandboxEnabled = options.sandbox;
     const schemaKwargs = {};
-    const builtinKeys = /* @__PURE__ */ new Set(["input", "yes", "largeInput", "format", "sandbox"]);
+    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;
@@ -1880,7 +1914,7 @@ init_errors();
 import { readFileSync as readFileSync3 } from "fs";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import * as path6 from "path";
-import { Command as Command4 } from "commander";
+import { Command as Command4, Help, Option as Option2 } from "commander";
 var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
 var SHELL_VERSION = "0.0.0";
 try {
@@ -2151,6 +2185,117 @@ ${meaning}`);
   );
   return sections.join("\n");
 }
+function roffEscape(s) {
+  return s.replace(/\\/g, "\\\\").replace(/-/g, "\\-").replace(/'/g, "\\(aq");
+}
+function buildProgramManPage(program, progName, version, description, docsUrl2) {
+  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 (docsUrl2) {
+    s.push(`.PP
+Full documentation at \\fI${roffEscape(docsUrl2)}\\fR`);
+  }
+  return s.join("\n");
+}
+function configureManHelp(program, progName, version, description, docsUrl2) {
+  const manOpt = new Option2("--man", "Output man page in roff format (use with --help)").hideHelp();
+  program.addOption(manOpt);
+  program.addHelpText("beforeAll", () => {
+    if (program.opts().man) {
+      process.stdout.write(buildProgramManPage(program, progName, version, description, docsUrl2));
+      process.stdout.write("\n");
+      process.exit(0);
+    }
+    return "";
+  });
+}
 function registerShellCommands(cli, progName = "apcore-cli") {
   const completionCmd = new Command4("completion").description(
     "Generate a shell completion script and print it to stdout."
@@ -2213,10 +2358,13 @@ export {
   SchemaValidationError,
   applyToolkitIntegration,
   buildModuleCommand,
+  buildProgramManPage,
   checkApproval,
   collectInput,
+  configureManHelp,
   createCli,
   debug,
+  docsUrl,
   error,
   exitCodeForError,
   extractHelp,
@@ -2238,9 +2386,12 @@ export {
   resolveRefs,
   schemaToCliOptions,
   setAuditLogger,
+  setDocsUrl,
   setLogLevel,
+  setVerboseHelp,
   truncate,
   validateModuleId,
+  verboseHelp,
   warn
 };
 //# sourceMappingURL=index.js.map