feat: implement Config Bus namespace support, add man page pager integration, and update apcore-js dependency to 0.15.1

Author: tercel

package.json

@@ -1,6 +1,6 @@
 {
   "name": "apcore-cli",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "CLI wrapper for the apcore core SDK — exposes apcore modules as CLI commands",
   "type": "module",
   "main": "./dist/index.js",
@@ -27,7 +27,7 @@
     "node": ">=18.0.0"
   },
   "peerDependencies": {
-    "apcore-js": ">=0.14.0",
+    "apcore-js": ">=0.15.1",
     "apcore-toolkit": ">=0.4.0"
   },
   "peerDependenciesMeta": {

pnpm-lock.yaml

@@ -19,8 +19,50 @@ export const DEFAULTS: Record<string, unknown> = {
   "cli.stdin_buffer_limit": 10_485_760,
   "cli.auto_approve": false,
   "cli.help_text_max_length": 1000,
+  // Namespace-mode aliases (apcore >= 0.15.0 Config Bus)
+  "apcore-cli.stdin_buffer_limit": 10_485_760,
+  "apcore-cli.auto_approve": false,
+  "apcore-cli.help_text_max_length": 1000,
+  "apcore-cli.logging_level": "WARNING",
 };
 
+/** Namespace key ↔ legacy key mapping for backward compatibility. */
+const NAMESPACE_TO_LEGACY: Record<string, string> = {
+  "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",
+};
+const LEGACY_TO_NAMESPACE: Record<string, string> = Object.fromEntries(
+  Object.entries(NAMESPACE_TO_LEGACY).map(([k, v]) => [v, k]),
+);
+
+/**
+ * Register the apcore-cli Config Bus namespace (apcore >= 0.15.0).
+ * Safe to call even when apcore-js is unavailable or < 0.15.0.
+ */
+export function registerConfigNamespace(): void {
+  try {
+    // Dynamic import to avoid hard failure when apcore-js is not available
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { Config } = require("apcore-js");
+    if (typeof Config?.registerNamespace === "function") {
+      Config.registerNamespace({
+        name: "apcore-cli",
+        envPrefix: "APCORE_CLI",
+        defaults: {
+          stdin_buffer_limit: 10_485_760,
+          auto_approve: false,
+          help_text_max_length: 1000,
+          logging_level: "WARNING",
+        },
+      });
+    }
+  } catch {
+    // apcore-js not installed or < 0.15.0 — graceful no-op
+  }
+}
+
 // ---------------------------------------------------------------------------
 // ConfigResolver
 // ---------------------------------------------------------------------------
@@ -64,11 +106,18 @@ export class ConfigResolver {
       }
     }
 
-    // Tier 3: Config file
+    // Tier 3: Config file (try both namespace and legacy keys)
     const fileValue = this.resolveFromFile(key);
     if (fileValue !== undefined) {
       return fileValue;
     }
+    const altKey = NAMESPACE_TO_LEGACY[key] ?? LEGACY_TO_NAMESPACE[key];
+    if (altKey) {
+      const altFileValue = this.resolveFromFile(altKey);
+      if (altFileValue !== undefined) {
+        return altFileValue;
+      }
+    }
 
     // Tier 4: Defaults
     return DEFAULTS[key];

src/config.ts

@@ -83,6 +83,13 @@ export const EXIT_CODES = {
   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,
 } as const;
 
@@ -130,11 +137,19 @@ export function exitCodeForError(error: unknown): ExitCode {
       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,
+      // 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];

src/errors.ts

@@ -19,7 +19,7 @@ export { getDisplay, getCliDisplayFields } from "./display-helpers.js";
 export { registerInitCommand } from "./init-cmd.js";
 
 // Configuration
-export { ConfigResolver, DEFAULTS } from "./config.js";
+export { ConfigResolver, DEFAULTS, registerConfigNamespace } from "./config.js";
 
 // Discovery
 export { registerDiscoveryCommands } from "./discovery.js";

src/index.ts

@@ -16,6 +16,8 @@ import { formatExecResult } from "./output.js";
 import { setLogLevel } from "./logger.js";
 import { registerInitCommand } from "./init-cmd.js";
 import { getDisplay } from "./display-helpers.js";
+import { registerConfigNamespace } from "./config.js";
+import { configureManHelp } from "./shell.js";
 import type { Executor, ModuleDescriptor } from "./cli.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -96,6 +98,8 @@ export function createCli(
   verbose = false,
 ): Command {
   verboseHelp = verbose;
+  // Register Config Bus namespace (apcore >= 0.15.0)
+  registerConfigNamespace();
   // Resolve program name
   const resolvedProgName = progName ?? path.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
 
@@ -120,9 +124,19 @@ export function createCli(
     ?? "./extensions";
   void resolvedExtDir; // Will be used when apcore-js registry is wired
 
+  // Footer hints for discoverability
+  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"));
+
   // Register init command for scaffolding
   registerInitCommand(program);
 
+  // Register --help --man support
+  configureManHelp(program, resolvedProgName, VERSION);
+
   // Hook to apply optional toolkit integration before command execution.
   // Commander actions are async, so we can set up toolkit state lazily.
   program.hook("preAction", async (thisCommand) => {

src/main.ts

@@ -7,6 +7,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
+import { spawnSync } from "node:child_process";
 import { Command, Help, Option } from "commander";
 import { EXIT_CODES } from "./errors.js";
 
@@ -516,8 +517,41 @@ export function configureManHelp(
   // Intercept help to output roff when --man is set
   program.addHelpText("beforeAll", () => {
     if (program.opts().man) {
-      process.stdout.write(buildProgramManPage(program, progName, version, description, docsUrl));
-      process.stdout.write("\n");
+      const roff = buildProgramManPage(program, progName, version, description, docsUrl) + "\n";
+
+      // If stdout is a TTY, render through a pager; otherwise output raw roff
+      // (allows piping/redirection like `reach --help --man > reach.1`)
+      if (process.stdout.isTTY) {
+        // Try mandoc first (available on macOS/BSD), then groff, then fall back to raw output
+        const pagers: Array<{ cmd: string; args: string[] }> = [
+          { 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/shell.ts

@@ -196,4 +196,49 @@ describe("ConfigResolver", () => {
       expect(mockReadFileSync).toHaveBeenCalledTimes(1);
     });
   });
+
+  // ---- Task 4: Namespace-aware config resolution (apcore >= 0.15.0) ----
+
+  describe("namespace-aware config resolution", () => {
+    it("DEFAULTS contain namespace keys", () => {
+      expect(DEFAULTS).toHaveProperty("apcore-cli.stdin_buffer_limit");
+      expect(DEFAULTS).toHaveProperty("apcore-cli.auto_approve");
+      expect(DEFAULTS).toHaveProperty("apcore-cli.help_text_max_length");
+      expect(DEFAULTS).toHaveProperty("apcore-cli.logging_level");
+    });
+
+    it("resolves namespace key from legacy config file", () => {
+      mockFileContent(yaml.dump({ cli: { stdin_buffer_limit: 5242880 } }));
+      const resolver = new ConfigResolver({}, "apcore.yaml");
+      expect(resolver.resolve("apcore-cli.stdin_buffer_limit")).toBe(5242880);
+    });
+
+    it("resolves legacy key from namespace config file", () => {
+      mockFileContent(
+        yaml.dump({ "apcore-cli": { auto_approve: true } }),
+      );
+      const resolver = new ConfigResolver({}, "apcore.yaml");
+      expect(resolver.resolve("cli.auto_approve")).toBe(true);
+    });
+
+    it("direct key takes precedence over alternate", () => {
+      mockFileContent(
+        yaml.dump({
+          cli: { help_text_max_length: 500 },
+          "apcore-cli": { help_text_max_length: 2000 },
+        }),
+      );
+      const resolver = new ConfigResolver({}, "apcore.yaml");
+      expect(resolver.resolve("cli.help_text_max_length")).toBe(500);
+      expect(resolver.resolve("apcore-cli.help_text_max_length")).toBe(2000);
+    });
+
+    it("returns namespace default when no file present", () => {
+      mockFileNotFound();
+      const resolver = new ConfigResolver();
+      expect(resolver.resolve("apcore-cli.stdin_buffer_limit")).toBe(10_485_760);
+      expect(resolver.resolve("apcore-cli.auto_approve")).toBe(false);
+      expect(resolver.resolve("apcore-cli.logging_level")).toBe("WARNING");
+    });
+  });
 });

tests/config.test.ts

@@ -111,4 +111,40 @@ describe("exitCodeForError", () => {
   it("maps unknown errors to exit code 1", () => {
     expect(exitCodeForError(new Error("unknown"))).toBe(EXIT_CODES.MODULE_EXECUTE_ERROR);
   });
+
+  // Config Bus error codes (apcore >= 0.15.0)
+  it("maps APPROVAL_PENDING to exit code 46", () => {
+    const err = Object.assign(new Error("test"), { code: "APPROVAL_PENDING" });
+    expect(exitCodeForError(err)).toBe(EXIT_CODES.APPROVAL_DENIED);
+  });
+
+  it("maps CONFIG_NAMESPACE_RESERVED to exit code 78", () => {
+    const err = Object.assign(new Error("test"), { code: "CONFIG_NAMESPACE_RESERVED" });
+    expect(exitCodeForError(err)).toBe(EXIT_CODES.CONFIG_NAMESPACE_RESERVED);
+  });
+
+  it("maps CONFIG_NAMESPACE_DUPLICATE to exit code 78", () => {
+    const err = Object.assign(new Error("test"), { code: "CONFIG_NAMESPACE_DUPLICATE" });
+    expect(exitCodeForError(err)).toBe(EXIT_CODES.CONFIG_NAMESPACE_DUPLICATE);
+  });
+
+  it("maps CONFIG_ENV_PREFIX_CONFLICT to exit code 78", () => {
+    const err = Object.assign(new Error("test"), { code: "CONFIG_ENV_PREFIX_CONFLICT" });
+    expect(exitCodeForError(err)).toBe(EXIT_CODES.CONFIG_ENV_PREFIX_CONFLICT);
+  });
+
+  it("maps CONFIG_MOUNT_ERROR to exit code 66", () => {
+    const err = Object.assign(new Error("test"), { code: "CONFIG_MOUNT_ERROR" });
+    expect(exitCodeForError(err)).toBe(EXIT_CODES.CONFIG_MOUNT_ERROR);
+  });
+
+  it("maps CONFIG_BIND_ERROR to exit code 65", () => {
+    const err = Object.assign(new Error("test"), { code: "CONFIG_BIND_ERROR" });
+    expect(exitCodeForError(err)).toBe(EXIT_CODES.CONFIG_BIND_ERROR);
+  });
+
+  it("maps ERROR_FORMATTER_DUPLICATE to exit code 70", () => {
+    const err = Object.assign(new Error("test"), { code: "ERROR_FORMATTER_DUPLICATE" });
+    expect(exitCodeForError(err)).toBe(EXIT_CODES.ERROR_FORMATTER_DUPLICATE);
+  });
 });