npm - apcore-cli - Versions diffs - 0.4.0 → 0.5.0 - Mend

apcore-cli 0.4.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/bin/apcore-cli.js +225 -9
package/dist/bin/apcore-cli.js.map +1 -1
package/dist/index.d.ts +12 -1
package/dist/index.js +1122 -1024
package/dist/index.js.map +1 -1
package/package.json +2 -2

package/dist/bin/apcore-cli.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.8_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js","../../src/errors.ts","../../bin/apcore-cli.ts","../../src/main.ts","../../src/ref-resolver.ts","../../src/schema-parser.ts","../../src/approval.ts","../../src/output.ts","../../src/logger.ts","../../src/init-cmd.ts","../../src/display-helpers.ts"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ / getDirname()\nexport const __filename = / @__PURE__ / getFilename()\n","/\n Error classes and exit code mapping for apcore-cli.\n \n Protocol spec: Error handling & exit codes\n /\n\n// ---------------------------------------------------------------------------\n// Error classes\n// ---------------------------------------------------------------------------\n\n/* Thrown when the user does not approve module execution within the timeout. /\nexport class ApprovalTimeoutError extends Error {\n constructor(message = \"Approval timed out\") {\n super(message);\n this.name = \"ApprovalTimeoutError\";\n }\n}\n\n/* Thrown when API key authentication fails or is missing. /\nexport class AuthenticationError extends Error {\n constructor(message = \"Authentication failed\") {\n super(message);\n this.name = \"AuthenticationError\";\n }\n}\n\n/* Thrown when encrypted config cannot be decrypted. /\nexport class ConfigDecryptionError extends Error {\n constructor(message = \"Config decryption failed\") {\n super(message);\n this.name = \"ConfigDecryptionError\";\n }\n}\n\n/* Thrown when module execution fails. /\nexport class ModuleExecutionError extends Error {\n constructor(message = \"Module execution failed\") {\n super(message);\n this.name = \"ModuleExecutionError\";\n }\n}\n\n/* Thrown when approval is denied by the user. /\nexport class ApprovalDeniedError extends Error {\n constructor(message = \"Approval denied\") {\n super(message);\n this.name = \"ApprovalDeniedError\";\n }\n}\n\n/* Thrown when schema validation fails. /\nexport class SchemaValidationError extends Error {\n constructor(message = \"Schema validation failed\") {\n super(message);\n this.name = \"SchemaValidationError\";\n }\n}\n\n/* Thrown when a module is not found. /\nexport class ModuleNotFoundError extends Error {\n constructor(message = \"Module not found\") {\n super(message);\n this.name = \"ModuleNotFoundError\";\n }\n}\n\n// ---------------------------------------------------------------------------\n// Exit code map\n// ---------------------------------------------------------------------------\n\nexport const EXIT_CODES = {\n SUCCESS: 0,\n MODULE_EXECUTE_ERROR: 1,\n MODULE_TIMEOUT: 1,\n INVALID_CLI_INPUT: 2,\n MODULE_NOT_FOUND: 44,\n MODULE_LOAD_ERROR: 44,\n MODULE_DISABLED: 44,\n SCHEMA_VALIDATION_ERROR: 45,\n APPROVAL_DENIED: 46,\n APPROVAL_TIMEOUT: 46,\n CONFIG_NOT_FOUND: 47,\n CONFIG_INVALID: 47,\n SCHEMA_CIRCULAR_REF: 48,\n ACL_DENIED: 77,\n KEYBOARD_INTERRUPT: 130,\n} as const;\n\nexport type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/\n Map a caught error to the appropriate process exit code.\n * Also checks for apcore error codes on the error object.\n /\nexport function exitCodeForError(error: unknown): ExitCode {\n if (error instanceof ApprovalTimeoutError) {\n return EXIT_CODES.APPROVAL_TIMEOUT;\n }\n if (error instanceof ApprovalDeniedError) {\n return EXIT_CODES.APPROVAL_DENIED;\n }\n if (error instanceof AuthenticationError) {\n return EXIT_CODES.ACL_DENIED;\n }\n if (error instanceof ConfigDecryptionError) {\n return EXIT_CODES.CONFIG_INVALID;\n }\n if (error instanceof SchemaValidationError) {\n return EXIT_CODES.SCHEMA_VALIDATION_ERROR;\n }\n if (error instanceof ModuleNotFoundError) {\n return EXIT_CODES.MODULE_NOT_FOUND;\n }\n if (error instanceof ModuleExecutionError) {\n return EXIT_CODES.MODULE_EXECUTE_ERROR;\n }\n\n // Check for apcore error codes on the error object\n if (error instanceof Error) {\n const code = (error as unknown as Record<string, unknown>).code as string \| undefined;\n const codeMap: Record<string, ExitCode> = {\n MODULE_NOT_FOUND: EXIT_CODES.MODULE_NOT_FOUND,\n MODULE_LOAD_ERROR: EXIT_CODES.MODULE_LOAD_ERROR,\n MODULE_DISABLED: EXIT_CODES.MODULE_DISABLED,\n SCHEMA_VALIDATION_ERROR: EXIT_CODES.SCHEMA_VALIDATION_ERROR,\n SCHEMA_CIRCULAR_REF: EXIT_CODES.SCHEMA_CIRCULAR_REF,\n APPROVAL_DENIED: EXIT_CODES.APPROVAL_DENIED,\n APPROVAL_TIMEOUT: EXIT_CODES.APPROVAL_TIMEOUT,\n CONFIG_NOT_FOUND: EXIT_CODES.CONFIG_NOT_FOUND,\n CONFIG_INVALID: EXIT_CODES.CONFIG_INVALID,\n MODULE_EXECUTE_ERROR: EXIT_CODES.MODULE_EXECUTE_ERROR,\n MODULE_TIMEOUT: EXIT_CODES.MODULE_TIMEOUT,\n ACL_DENIED: EXIT_CODES.ACL_DENIED,\n };\n if (code && code in codeMap) {\n return codeMap[code];\n }\n }\n\n return EXIT_CODES.MODULE_EXECUTE_ERROR;\n}\n","#!/usr/bin/env node\n/\n apcore-cli — Shebang entry point.\n \n This file is the bin target. It bootstraps the CLI and delegates to main().\n /\n\nimport { main } from \"../src/main.js\";\n\nmain(\"apcore-cli\");\n","/\n CLI entry point — createCli / main equivalents.\n \n Protocol spec: CLI bootstrapping & command registration\n /\n\nimport { readFileSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport as path from \"node:path\";\nimport { Command, CommanderError, Option } from \"commander\";\nimport { EXIT_CODES, exitCodeForError } from \"./errors.js\";\nimport { resolveRefs } from \"./ref-resolver.js\";\nimport { schemaToCliOptions } from \"./schema-parser.js\";\nimport { checkApproval } from \"./approval.js\";\nimport { formatExecResult } from \"./output.js\";\nimport { setLogLevel } from \"./logger.js\";\nimport { registerInitCommand } from \"./init-cmd.js\";\nimport { getDisplay } from \"./display-helpers.js\";\nimport type { Executor, ModuleDescriptor } from \"./cli.js\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\n/** Whether --verbose was passed (controls help detail level). /\nexport let verboseHelp = false;\n\n/* Set the verbose help flag. When false, built-in options are hidden from help. /\nexport function setVerboseHelp(verbose: boolean): void {\n verboseHelp = verbose;\n}\n\n/* Base URL for online documentation. Null means no docs link shown. /\nexport let docsUrl: string \| null = null;\n\n/\n Set the base URL for online documentation links shown in help and man pages.\n * Pass null to disable. Command-level help appends `/commands/{name}` automatically.\n \n @example setDocsUrl(\"https://docs.apcore.dev/cli\");\n /\nexport function setDocsUrl(url: string \| null): void {\n docsUrl = url;\n}\n\n/* Check if --verbose is present in process.argv (pre-parse, before Commander). /\nfunction hasVerboseFlag(): boolean {\n return process.argv.includes(\"--verbose\");\n}\n\nlet VERSION = \"0.0.0\";\ntry {\n const pkg = JSON.parse(readFileSync(path.resolve(__dirname, \"../package.json\"), \"utf-8\"));\n VERSION = pkg.version;\n} catch {\n // Bundled environments (e.g., Bun compile) may not have package.json accessible\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/* Configuration for a single Commander option derived from a JSON Schema property. /\nexport interface OptionConfig {\n /* The property name from the schema. /\n name: string;\n /* Commander flags string (e.g. \"--my-flag <value>\" or \"--flag, --no-flag\"). /\n flags: string;\n /* Help text for the option. /\n description: string;\n /* Default value. /\n defaultValue?: unknown;\n /* Whether the field is required (for display only). /\n required: boolean;\n /* Enum choices (string values). /\n choices?: string[];\n /* Whether this is a boolean flag pair (--flag/--no-flag). /\n isBooleanFlag?: boolean;\n /* Maps string enum value → original type name (\"int\", \"float\", \"bool\"). /\n enumOriginalTypes?: Record<string, string>;\n /* Parser function for Commander (e.g. parseInt, parseFloat). /\n parseArg?: (value: string) => unknown;\n}\n\n// ---------------------------------------------------------------------------\n// createCli\n// ---------------------------------------------------------------------------\n\n/\n Build and return the top-level Commander program.\n \n @param extensionsDir Path to the extensions directory (default: ./extensions)\n * @param progName Program name shown in help (default: apcore-cli)\n /\nexport function createCli(\n extensionsDir?: string,\n progName?: string,\n verbose = false,\n): Command {\n verboseHelp = verbose;\n // Resolve program name\n const resolvedProgName = progName ?? path.basename(process.argv[1] ?? \"apcore-cli\") ?? \"apcore-cli\";\n\n // Resolve log level\n const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? \"WARNING\";\n setLogLevel(cliLogLevel);\n\n const program = new Command(resolvedProgName)\n .exitOverride()\n .version(VERSION, \"--version\", `Show ${resolvedProgName} version`)\n .description(\"apcore CLI — execute apcore modules from the command line\")\n .option(\"--extensions-dir <path>\", \"Path to extensions directory\")\n .option(\"--commands-dir <path>\", \"Path to convention-based commands directory\")\n .option(\"--binding <path>\", \"Path to binding.yaml for display overlay\")\n .option(\"--log-level <level>\", \"Logging level (DEBUG\|INFO\|WARNING\|ERROR)\", \"WARNING\")\n .option(\"--verbose\", \"Show all options in help output (including built-in apcore options)\");\n\n // NOTE: Full registry/executor wiring requires apcore-js to be available.\n // For now, extensions-dir is accepted but not wired to a real registry.\n const resolvedExtDir = extensionsDir\n ?? process.env.APCORE_EXTENSIONS_ROOT\n ?? \"./extensions\";\n void resolvedExtDir; // Will be used when apcore-js registry is wired\n\n // Register init command for scaffolding\n registerInitCommand(program);\n\n // Hook to apply optional toolkit integration before command execution.\n // Commander actions are async, so we can set up toolkit state lazily.\n program.hook(\"preAction\", async (thisCommand) => {\n const opts = thisCommand.opts();\n const commandsDir = opts.commandsDir as string \| undefined;\n const bindingPath = opts.binding as string \| undefined;\n await applyToolkitIntegration(commandsDir, bindingPath);\n });\n\n return program;\n}\n\n// ---------------------------------------------------------------------------\n// applyToolkitIntegration\n// ---------------------------------------------------------------------------\n\n/\n Optionally apply apcore-toolkit features (DisplayResolver, RegistryWriter).\n \n Uses dynamic import so the dependency remains optional — if apcore-toolkit\n * is not installed, a warning is printed and the CLI continues without it.\n /\nexport async function applyToolkitIntegration(\n commandsDir?: string,\n bindingPath?: string,\n): Promise<void> {\n if (!commandsDir && !bindingPath) {\n return;\n }\n\n try {\n // Use a variable to prevent TypeScript from resolving the module at build time\n const toolkitModule = \"apcore-toolkit\";\n // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment\n const toolkit = await import(/ @vite-ignore / toolkitModule);\n\n // ConventionScanner is not yet available in the TypeScript toolkit\n if (commandsDir) {\n console.warn(\"Convention scanning not yet available in TypeScript toolkit\");\n }\n\n // DisplayResolver for binding overlay\n if (bindingPath) {\n const resolver = new toolkit.DisplayResolver();\n // NOTE: Full integration requires registered modules from apcore-js.\n // For now, the resolver is instantiated and ready for when modules\n // are available through the registry.\n void resolver;\n }\n } catch {\n // apcore-toolkit not installed — graceful fallback\n console.warn(\"apcore-toolkit not installed — toolkit features unavailable\");\n }\n}\n\n// ---------------------------------------------------------------------------\n// main\n// ---------------------------------------------------------------------------\n\n/\n Parse argv and run the CLI. Handles top-level error catching and exit codes.\n /\nexport function main(progName?: string): void {\n verboseHelp = hasVerboseFlag();\n const program = createCli(undefined, progName, verboseHelp);\n\n try {\n program.parse(process.argv);\n } catch (error: unknown) {\n if (error instanceof CommanderError) {\n // Commander already printed the error message\n process.exit(error.exitCode);\n }\n const code = exitCodeForError(error);\n if (error instanceof Error) {\n process.stderr.write(`Error: ${error.message}\\n`);\n }\n process.exit(code);\n }\n}\n\n// ---------------------------------------------------------------------------\n// buildModuleCommand\n// ---------------------------------------------------------------------------\n\n/\n Build a Commander Command for a single apcore module.\n /\nexport function buildModuleCommand(\n moduleDef: ModuleDescriptor,\n executor: Executor,\n helpTextMaxLength = 1000,\n cmdName?: string,\n verbose = verboseHelp,\n): Command {\n const moduleId = moduleDef.id;\n let resolvedSchema: Record<string, unknown> = {};\n let schemaOptions: OptionConfig[] = [];\n\n // Resolve display overlay fields\n const display = getDisplay(moduleDef);\n const cliDisplay = (display.cli && typeof display.cli === \"object\" && !Array.isArray(display.cli))\n ? (display.cli as Record<string, unknown>)\n : {};\n const effectiveCmdName: string = cmdName ?? (cliDisplay.alias as string \| undefined) ?? moduleId;\n const cmdHelp: string = (cliDisplay.description as string \| undefined) ?? moduleDef.description;\n\n // Resolve schema\n const inputSchema = moduleDef.inputSchema;\n if (inputSchema && typeof inputSchema === \"object\" && inputSchema.properties) {\n try {\n resolvedSchema = resolveRefs(inputSchema, 32, moduleId);\n } catch {\n resolvedSchema = inputSchema;\n }\n schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);\n }\n\n const cmd = new Command(effectiveCmdName).description(cmdHelp);\n\n // Built-in options (hidden unless --verbose)\n const inputOpt = new Option(\"--input <source>\", \"Read JSON input from a file path, or use '-' to read from stdin pipe\");\n const yesOpt = new Option(\"-y, --yes\", \"Skip interactive approval prompts (for scripts and CI)\").default(false);\n const largeInputOpt = new Option(\"--large-input\", \"Allow stdin input larger than 10MB (default limit protects against accidental pipes)\").default(false);\n const formatOpt = new Option(\"--format <format>\", \"Set output format: 'json' for machine-readable, 'table' for human-readable\");\n // --sandbox is always hidden (not yet implemented)\n const sandboxOpt = new Option(\"--sandbox\", \"Run module in an isolated subprocess with restricted filesystem and env access\").default(false).hideHelp();\n\n if (!verbose) {\n inputOpt.hideHelp();\n yesOpt.hideHelp();\n largeInputOpt.hideHelp();\n formatOpt.hideHelp();\n }\n\n cmd.addOption(inputOpt);\n cmd.addOption(yesOpt);\n cmd.addOption(largeInputOpt);\n cmd.addOption(formatOpt);\n cmd.addOption(sandboxOpt);\n\n // Help footer: verbose hint + optional docs link\n const footerParts: string[] = [];\n if (!verbose) {\n footerParts.push(\"Use --verbose to show all options (including built-in apcore options).\");\n }\n if (docsUrl) {\n footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);\n }\n if (footerParts.length > 0) {\n cmd.addHelpText(\"after\", \"\\n\" + footerParts.join(\"\\n\") + \"\\n\");\n }\n\n // Schema-generated options\n for (const opt of schemaOptions) {\n if (opt.parseArg) {\n cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);\n } else {\n cmd.option(opt.flags, opt.description, opt.defaultValue as string \| boolean \| undefined);\n }\n }\n\n // Action callback\n cmd.action(async (options: Record<string, unknown>) => {\n // Pop built-in options\n const stdinFlag = options.input as string \| undefined;\n const autoApprove = options.yes as boolean;\n const largeInput = options.largeInput as boolean;\n const outputFormat = options.format as string \| undefined;\n const sandboxEnabled = options.sandbox as boolean;\n\n // Remove built-in keys from options to get schema kwargs\n const schemaKwargs: Record<string, unknown> = {};\n const builtinKeys = new Set([\"input\", \"yes\", \"largeInput\", \"format\", \"sandbox\", \"verbose\"]);\n for (const [k, v] of Object.entries(options)) {\n if (!builtinKeys.has(k)) {\n schemaKwargs[k] = v;\n }\n }\n\n try {\n // Collect and merge input\n const merged = await collectInput(stdinFlag, schemaKwargs, largeInput);\n\n // Reconvert enum values\n const reconverted = reconvertEnumValues(merged, schemaOptions);\n\n // Check approval\n await checkApproval(moduleDef, autoApprove);\n\n // Execute with timing\n const { Sandbox } = await import(\"./security/index.js\");\n const sandbox = new Sandbox(sandboxEnabled);\n const startTime = performance.now();\n const result = await sandbox.execute(moduleId, reconverted, executor);\n const durationMs = Math.round(performance.now() - startTime);\n\n // Audit log (success)\n const { getAuditLogger } = await import(\"./security/audit.js\");\n const auditLogger = getAuditLogger();\n if (auditLogger) {\n auditLogger.logExecution(moduleId, reconverted, \"success\", 0, durationMs);\n }\n\n // Format output\n formatExecResult(result, outputFormat);\n } catch (err: unknown) {\n // Audit log (error)\n const { getAuditLogger } = await import(\"./security/audit.js\");\n const auditLogger = getAuditLogger();\n const code = exitCodeForError(err);\n if (auditLogger) {\n auditLogger.logExecution(moduleId, {}, \"error\", code, 0);\n }\n\n if (err instanceof Error) {\n process.stderr.write(`Error: ${err.message}\\n`);\n }\n process.exit(code);\n }\n });\n\n return cmd;\n}\n\n// ---------------------------------------------------------------------------\n// validateModuleId\n// ---------------------------------------------------------------------------\n\n/\n Validate that a module ID conforms to the expected format.\n * Pattern: [a-z][a-z0-9_](.[a-z][a-z0-9_]) — max 128 chars.\n /\nexport function validateModuleId(moduleId: string): void {\n if (moduleId.length > 128) {\n process.stderr.write(\n `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n if (!/^[a-z][a-z0-9_](\\.[a-z][a-z0-9_])$/.test(moduleId)) {\n process.stderr.write(\n `Error: Invalid module ID format: '${moduleId}'.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n}\n\n// ---------------------------------------------------------------------------\n// collectInput\n// ---------------------------------------------------------------------------\n\n/*\n Collect module input from stdin and/or CLI keyword arguments.\n /\nexport async function collectInput(\n stdinFlag?: string,\n cliKwargs: Record<string, unknown> = {},\n largeInput?: boolean,\n): Promise<Record<string, unknown>> {\n // Remove null/undefined values from CLI kwargs\n const cliKwargsNonNull: Record<string, unknown> = {};\n for (const [k, v] of Object.entries(cliKwargs)) {\n if (v !== null && v !== undefined) {\n cliKwargsNonNull[k] = v;\n }\n }\n\n if (!stdinFlag) {\n return cliKwargsNonNull;\n }\n\n if (stdinFlag === \"-\") {\n const raw = await readStdin();\n const rawSize = Buffer.byteLength(raw, \"utf-8\");\n\n if (rawSize > 10_485_760 && !largeInput) {\n process.stderr.write(\n \"Error: STDIN input exceeds 10MB limit. Use --large-input to override.\\n\",\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n if (!raw) {\n return cliKwargsNonNull;\n }\n\n let stdinData: unknown;\n try {\n stdinData = JSON.parse(raw);\n } catch {\n process.stderr.write(\n \"Error: STDIN does not contain valid JSON.\\n\",\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n if (typeof stdinData !== \"object\" \|\| stdinData === null \|\| Array.isArray(stdinData)) {\n process.stderr.write(\n `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? \"array\" : typeof stdinData}.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n // CLI flags override STDIN for duplicate keys\n return { ...(stdinData as Record<string, unknown>), ...cliKwargsNonNull };\n }\n\n return cliKwargsNonNull;\n}\n\n/\n Read all data from stdin with proper cleanup.\n /\nfunction readStdin(): Promise<string> {\n return new Promise((resolve, reject) => {\n const chunks: Buffer[] = [];\n const onData = (chunk: Buffer) => chunks.push(chunk);\n const onEnd = () => {\n cleanup();\n resolve(Buffer.concat(chunks).toString(\"utf-8\"));\n };\n const onError = (err: Error) => {\n cleanup();\n reject(err);\n };\n const cleanup = () => {\n process.stdin.removeListener(\"data\", onData);\n process.stdin.removeListener(\"end\", onEnd);\n process.stdin.removeListener(\"error\", onError);\n };\n process.stdin.on(\"data\", onData);\n process.stdin.on(\"end\", onEnd);\n process.stdin.on(\"error\", onError);\n process.stdin.resume();\n });\n}\n\n// ---------------------------------------------------------------------------\n// reconvertEnumValues\n// ---------------------------------------------------------------------------\n\n/\n Re-convert CLI string values back to their schema-typed equivalents\n * based on the option configs.\n /\nexport function reconvertEnumValues(\n kwargs: Record<string, unknown>,\n options: OptionConfig[],\n): Record<string, unknown> {\n const result = { ...kwargs };\n for (const opt of options) {\n if (!opt.enumOriginalTypes) continue;\n const paramName = opt.name;\n if (!(paramName in result) \|\| result[paramName] === null \|\| result[paramName] === undefined) {\n continue;\n }\n const strVal = String(result[paramName]);\n const origType = opt.enumOriginalTypes[strVal];\n if (origType === \"int\") {\n result[paramName] = parseInt(strVal, 10);\n } else if (origType === \"float\") {\n result[paramName] = parseFloat(strVal);\n } else if (origType === \"bool\") {\n result[paramName] = strVal.toLowerCase() === \"true\";\n }\n }\n return result;\n}\n","/\n JSON Schema $ref resolver.\n \n Protocol spec: Schema resolution & $ref handling\n /\n\nimport { EXIT_CODES } from \"./errors.js\";\n\n// ---------------------------------------------------------------------------\n// resolveRefs\n// ---------------------------------------------------------------------------\n\n/\n Resolve all $ref references in a JSON Schema.\n * Returns a fully inlined schema with $defs/definitions removed.\n /\nexport function resolveRefs(\n schema: Record<string, unknown>,\n maxDepth = 32,\n moduleId = \"\",\n): Record<string, unknown> {\n const cloned = structuredClone(schema);\n const defs = (cloned.$defs ?? cloned.definitions ?? {}) as Record<\n string,\n unknown\n >;\n const result = resolveNode(\n cloned,\n defs,\n new Set<string>(),\n 0,\n maxDepth,\n moduleId,\n ) as Record<string, unknown>;\n\n // Remove definition keys\n delete result.$defs;\n delete result.definitions;\n return result;\n}\n\nfunction resolveNode(\n node: unknown,\n defs: Record<string, unknown>,\n visited: Set<string>,\n depth: number,\n maxDepth: number,\n moduleId: string,\n): unknown {\n if (typeof node !== \"object\" \|\| node === null \|\| Array.isArray(node)) {\n return node;\n }\n\n const obj = node as Record<string, unknown>;\n\n // Handle $ref\n if (\"$ref\" in obj) {\n const refPath = obj.$ref as string;\n\n if (depth >= maxDepth) {\n process.stderr.write(\n `Error: $ref resolution depth exceeded maximum of ${maxDepth} for module '${moduleId}'.\\n`,\n );\n process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);\n }\n\n if (visited.has(refPath)) {\n process.stderr.write(\n `Error: Circular $ref detected in schema for module '${moduleId}' at path '${refPath}'.\\n`,\n );\n process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);\n }\n\n // Parse ref target: extract key from \"#/$defs/Address\" → \"Address\"\n const parts = refPath.split(\"/\");\n const key = parts[parts.length - 1];\n\n if (!(key in defs)) {\n process.stderr.write(\n `Error: Unresolvable $ref '${refPath}' in schema for module '${moduleId}'.\\n`,\n );\n process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);\n }\n\n const newVisited = new Set(visited);\n newVisited.add(refPath);\n return resolveNode(defs[key], defs, newVisited, depth + 1, maxDepth, moduleId);\n }\n\n // Handle allOf\n if (\"allOf\" in obj && Array.isArray(obj.allOf)) {\n const merged: Record<string, unknown> = {\n properties: {},\n required: [] as string[],\n };\n for (const subSchema of obj.allOf as unknown[]) {\n const resolved = resolveNode(\n subSchema,\n defs,\n visited,\n depth + 1,\n maxDepth,\n moduleId,\n ) as Record<string, unknown>;\n if (resolved.properties) {\n Object.assign(\n merged.properties as Record<string, unknown>,\n resolved.properties,\n );\n }\n if (Array.isArray(resolved.required)) {\n (merged.required as string[]).push(...resolved.required);\n }\n }\n // Deduplicate required\n merged.required = [...new Set(merged.required as string[])];\n // Copy non-composition keys\n for (const [k, v] of Object.entries(obj)) {\n if (k !== \"allOf\" && !(k in merged)) {\n merged[k] = v;\n }\n }\n return merged;\n }\n\n // Handle anyOf / oneOf\n for (const keyword of [\"anyOf\", \"oneOf\"]) {\n if (keyword in obj && Array.isArray(obj[keyword])) {\n const merged: Record<string, unknown> = {\n properties: {},\n required: [] as string[],\n };\n const allRequiredSets: Set<string>[] = [];\n for (const subSchema of obj[keyword] as unknown[]) {\n const resolved = resolveNode(\n subSchema,\n defs,\n visited,\n depth + 1,\n maxDepth,\n moduleId,\n ) as Record<string, unknown>;\n if (resolved.properties) {\n Object.assign(\n merged.properties as Record<string, unknown>,\n resolved.properties,\n );\n }\n if (Array.isArray(resolved.required)) {\n allRequiredSets.push(new Set(resolved.required as string[]));\n }\n }\n // Required = intersection of all branches\n if (allRequiredSets.length > 0) {\n let intersection = allRequiredSets[0];\n for (let i = 1; i < allRequiredSets.length; i++) {\n intersection = new Set(\n [...intersection].filter((x) => allRequiredSets[i].has(x)),\n );\n }\n merged.required = [...intersection];\n } else {\n merged.required = [];\n }\n // Copy non-composition keys\n for (const [k, v] of Object.entries(obj)) {\n if (k !== keyword && !(k in merged)) {\n merged[k] = v;\n }\n }\n return merged;\n }\n }\n\n // Recursively process nested properties\n if (\"properties\" in obj && typeof obj.properties === \"object\" && obj.properties !== null) {\n const props = obj.properties as Record<string, unknown>;\n for (const [propName, propSchema] of Object.entries(props)) {\n props[propName] = resolveNode(\n propSchema,\n defs,\n visited,\n depth + 1,\n maxDepth,\n moduleId,\n );\n }\n }\n\n return obj;\n}\n","/\n JSON Schema -> Commander options mapping.\n \n Protocol spec: Schema-driven argument parsing\n /\n\nimport type { OptionConfig } from \"./main.js\";\nimport { EXIT_CODES } from \"./errors.js\";\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/* Sentinel type marker for boolean flags. /\nconst BOOLEAN_FLAG = Symbol(\"BOOLEAN_FLAG\");\n\ntype TypeResult = \"string\" \| \"int\" \| \"float\" \| typeof BOOLEAN_FLAG \| \"file\";\n\n/\n Map JSON Schema type to a type identifier.\n /\nexport function mapType(propName: string, propSchema: Record<string, unknown>): TypeResult {\n const schemaType = propSchema.type as string \| undefined;\n\n // Check file convention\n if (\n schemaType === \"string\" &&\n (propName.endsWith(\"_file\") \|\| propSchema[\"x-cli-file\"] === true)\n ) {\n return \"file\";\n }\n\n const typeMap: Record<string, TypeResult> = {\n string: \"string\",\n integer: \"int\",\n number: \"float\",\n boolean: BOOLEAN_FLAG,\n object: \"string\",\n array: \"string\",\n };\n\n if (!schemaType) {\n return \"string\";\n }\n\n return typeMap[schemaType] ?? \"string\";\n}\n\n/\n Extract help text from schema property, preferring x-llm-description.\n /\nexport function extractHelp(propSchema: Record<string, unknown>, maxLength = 1000): string \| undefined {\n let text = propSchema[\"x-llm-description\"] as string \| undefined;\n if (!text) {\n text = propSchema.description as string \| undefined;\n }\n if (!text) {\n return undefined;\n }\n if (maxLength > 0 && text.length > maxLength) {\n return text.slice(0, maxLength - 3) + \"...\";\n }\n return text;\n}\n\n// ---------------------------------------------------------------------------\n// schemaToCliOptions\n// ---------------------------------------------------------------------------\n\n/* Reserved CLI option names that cannot be used by schema properties. /\nconst RESERVED_NAMES = new Set([\"input\", \"yes\", \"large_input\", \"format\", \"sandbox\"]);\n\n/\n Convert a JSON Schema `properties` object into an array of\n * Commander option configurations.\n /\nexport function schemaToCliOptions(\n schema: Record<string, unknown>,\n maxHelpLength = 1000,\n): OptionConfig[] {\n const properties = (schema.properties ?? {}) as Record<\n string,\n Record<string, unknown>\n >;\n const requiredList = (schema.required ?? []) as string[];\n const options: OptionConfig[] = [];\n const flagNames: Record<string, string> = {};\n\n for (const [propName, propSchema] of Object.entries(properties)) {\n const flagName = \"--\" + propName.replace(/_/g, \"-\");\n\n // Collision detection\n if (flagName in flagNames) {\n process.stderr.write(\n `Error: Flag name collision: properties '${propName}' and '${flagNames[flagName]}' both map to '${flagName}'.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n flagNames[flagName] = propName;\n\n // Reserved name check\n if (RESERVED_NAMES.has(propName)) {\n process.stderr.write(\n `Error: Module schema property '${propName}' conflicts with a reserved CLI option name. Rename the property.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n const typeResult = mapType(propName, propSchema);\n const isRequired = requiredList.includes(propName);\n const helpBase = extractHelp(propSchema, maxHelpLength);\n const helpText = isRequired\n ? (helpBase ? helpBase + \" \" : \"\") + \"[required]\"\n : helpBase ?? \"\";\n const defaultValue = propSchema.default as unknown;\n\n if (typeResult === BOOLEAN_FLAG) {\n // Boolean flag pair: --flag/--no-flag\n const flagBase = propName.replace(/_/g, \"-\");\n const defaultVal = (propSchema.default as boolean) ?? false;\n options.push({\n name: propName,\n flags: `--${flagBase}, --no-${flagBase}`,\n description: helpText,\n defaultValue: defaultVal,\n required: false,\n isBooleanFlag: true,\n });\n } else if (\"enum\" in propSchema && Array.isArray(propSchema.enum)) {\n const enumValues = propSchema.enum as unknown[];\n if (enumValues.length === 0) {\n // Empty enum — fall back to plain string option\n options.push({\n name: propName,\n flags: `${flagName} <value>`,\n description: helpText,\n defaultValue,\n required: false,\n });\n } else {\n const stringValues = enumValues.map(String);\n const enumOriginalTypes: Record<string, string> = {};\n for (const v of enumValues) {\n if (typeof v === \"number\" && Number.isInteger(v)) {\n enumOriginalTypes[String(v)] = \"int\";\n } else if (typeof v === \"number\") {\n enumOriginalTypes[String(v)] = \"float\";\n } else if (typeof v === \"boolean\") {\n enumOriginalTypes[String(v)] = \"bool\";\n }\n }\n options.push({\n name: propName,\n flags: `${flagName} <value>`,\n description: helpText,\n defaultValue:\n defaultValue !== undefined ? String(defaultValue) : undefined,\n required: false,\n choices: stringValues,\n enumOriginalTypes:\n Object.keys(enumOriginalTypes).length > 0\n ? enumOriginalTypes\n : undefined,\n });\n }\n } else {\n // Standard option\n let parseArg: ((value: string) => unknown) \| undefined;\n if (typeResult === \"int\") {\n parseArg = (v: string) => {\n const n = parseInt(v, 10);\n if (isNaN(n)) throw new Error(`Invalid integer: ${v}`);\n return n;\n };\n } else if (typeResult === \"float\") {\n parseArg = (v: string) => {\n const n = parseFloat(v);\n if (isNaN(n)) throw new Error(`Invalid number: ${v}`);\n return n;\n };\n }\n options.push({\n name: propName,\n flags: `${flagName} <value>`,\n description: helpText,\n defaultValue,\n required: false,\n parseArg,\n });\n }\n }\n\n return options;\n}\n","/\n Interactive approval prompts with timeout.\n \n Protocol spec: Approval workflow\n /\n\nimport as readline from \"node:readline\";\nimport type { ModuleDescriptor } from \"./cli.js\";\nimport { ApprovalTimeoutError, EXIT_CODES } from \"./errors.js\";\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/*\n Get an annotation value from either a dict or an object.\n /\nfunction getAnnotation(\n annotations: unknown,\n key: string,\n defaultValue: unknown = undefined,\n): unknown {\n if (!annotations \|\| typeof annotations !== \"object\") return defaultValue;\n const ann = annotations as Record<string, unknown>;\n return key in ann ? ann[key] : defaultValue;\n}\n\n// ---------------------------------------------------------------------------\n// checkApproval\n// ---------------------------------------------------------------------------\n\n/\n Check if module requires approval and handle accordingly.\n * Returns normally if approved (or approval not required).\n * Calls process.exit(46) if denied/timed out/non-TTY.\n /\nexport async function checkApproval(\n moduleDef: ModuleDescriptor,\n autoApprove: boolean,\n): Promise<void> {\n const annotations = moduleDef.annotations;\n\n // Check if approval is required\n let requiresApproval: boolean;\n if (moduleDef.requiresApproval !== undefined) {\n requiresApproval = moduleDef.requiresApproval;\n } else if (annotations) {\n requiresApproval = getAnnotation(annotations, \"requires_approval\", false) === true;\n } else {\n return; // No annotations, no approval needed\n }\n\n if (!requiresApproval) {\n return;\n }\n\n const moduleId = moduleDef.id;\n\n // Bypass: autoApprove flag (highest priority)\n if (autoApprove) {\n return;\n }\n\n // Bypass: APCORE_CLI_AUTO_APPROVE env var\n const envVal = process.env.APCORE_CLI_AUTO_APPROVE ?? \"\";\n if (envVal === \"1\") {\n return;\n }\n if (envVal !== \"\" && envVal !== \"1\") {\n process.stderr.write(\n `Warning: APCORE_CLI_AUTO_APPROVE is set to '${envVal}', expected '1'. Ignoring.\\n`,\n );\n }\n\n // Non-TTY check\n if (!process.stdin.isTTY) {\n process.stderr.write(\n `Error: Module '${moduleId}' requires approval but no interactive ` +\n \"terminal is available. Use --yes or set APCORE_CLI_AUTO_APPROVE=1 \" +\n \"to bypass.\\n\",\n );\n process.exit(EXIT_CODES.APPROVAL_DENIED);\n }\n\n // TTY prompt\n await promptWithTimeout(moduleDef, 60);\n}\n\n/\n Display approval prompt with timeout.\n /\nasync function promptWithTimeout(\n moduleDef: ModuleDescriptor,\n timeout: number,\n): Promise<void> {\n // Clamp timeout\n timeout = Math.max(1, Math.min(timeout, 3600));\n\n const moduleId = moduleDef.id;\n const annotations = moduleDef.annotations;\n const message =\n (annotations\n ? (getAnnotation(annotations, \"approval_message\") as string \| undefined)\n : undefined) ??\n `Module '${moduleId}' requires approval to execute.`;\n\n process.stderr.write(message + \"\\n\");\n\n const rl = readline.createInterface({\n input: process.stdin,\n output: process.stderr,\n });\n\n let timer: ReturnType<typeof setTimeout> \| undefined;\n\n try {\n const answer = await Promise.race([\n new Promise<string>((resolve) => {\n rl.question(\"Proceed? [y/N] \", (ans) => resolve(ans));\n }),\n new Promise<never>((_, reject) => {\n timer = setTimeout(() => {\n reject(new ApprovalTimeoutError(\n `Approval prompt timed out after ${timeout} seconds.`,\n ));\n }, timeout 1000);\n }),\n ]);\n\n // Clear the timeout — prompt resolved before timeout fired\n if (timer) clearTimeout(timer);\n\n const normalized = answer.trim().toLowerCase();\n if (normalized === \"y\" \|\| normalized === \"yes\") {\n return;\n }\n\n process.stderr.write(\"Error: Approval denied.\\n\");\n process.exit(EXIT_CODES.APPROVAL_DENIED);\n } catch (err) {\n if (timer) clearTimeout(timer);\n if (err instanceof ApprovalTimeoutError) {\n process.stderr.write(\n `Error: Approval prompt timed out after ${timeout} seconds.\\n`,\n );\n process.exit(EXIT_CODES.APPROVAL_TIMEOUT);\n }\n throw err;\n } finally {\n rl.close();\n }\n}\n","/*\n TTY-adaptive output formatting (table/json).\n \n Protocol spec: Output formatting\n /\n\nimport type { ModuleDescriptor } from \"./cli.js\";\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/\n Resolve output format with TTY-adaptive default.\n /\nexport function resolveFormat(explicitFormat?: string): string {\n if (explicitFormat !== undefined) {\n return explicitFormat;\n }\n return process.stdout.isTTY ? \"table\" : \"json\";\n}\n\n/\n Truncate text to maxLength, appending '...' if needed.\n /\nexport function truncate(text: string, maxLength = 80): string {\n if (text.length <= maxLength) {\n return text;\n }\n return text.slice(0, maxLength - 3) + \"...\";\n}\n\n/\n Render a simple plain-text table with column headers.\n /\nfunction formatTable(\n headers: string[],\n rows: string[][],\n): string {\n // Calculate column widths\n const colWidths = headers.map((h, i) =>\n Math.max(h.length, ...rows.map((r) => (r[i] ?? \"\").length)),\n );\n\n const sep = colWidths.map((w) => \"-\".repeat(w)).join(\" \");\n const headerLine = headers\n .map((h, i) => h.padEnd(colWidths[i]))\n .join(\" \");\n const dataLines = rows.map((row) =>\n row.map((cell, i) => (cell ?? \"\").padEnd(colWidths[i])).join(\" \"),\n );\n\n return [headerLine, sep, ...dataLines].join(\"\\n\") + \"\\n\";\n}\n\n// ---------------------------------------------------------------------------\n// formatModuleList\n// ---------------------------------------------------------------------------\n\n/\n Format and print a list of modules.\n /\nexport function formatModuleList(\n modules: ModuleDescriptor[],\n format: string,\n filterTags?: string[],\n): void {\n if (format === \"table\") {\n if (modules.length === 0 && filterTags && filterTags.length > 0) {\n process.stdout.write(\n `No modules found matching tags: ${filterTags.join(\", \")}.\\n`,\n );\n return;\n }\n if (modules.length === 0) {\n process.stdout.write(\"No modules found.\\n\");\n return;\n }\n\n const headers = [\"ID\", \"Description\", \"Tags\"];\n const rows = modules.map((m) => [\n m.id,\n truncate(m.description, 80),\n (m.tags ?? []).join(\", \"),\n ]);\n process.stdout.write(formatTable(headers, rows));\n } else if (format === \"json\") {\n const result = modules.map((m) => ({\n id: m.id,\n description: m.description,\n tags: m.tags ?? [],\n }));\n process.stdout.write(JSON.stringify(result, null, 2) + \"\\n\");\n }\n}\n\n// ---------------------------------------------------------------------------\n// formatModuleDetail\n// ---------------------------------------------------------------------------\n\n/\n Convert annotations to a plain dict, filtering out falsy/default values.\n /\nfunction annotationsToDict(\n annotations: unknown,\n): Record<string, unknown> \| null {\n if (!annotations) return null;\n if (typeof annotations !== \"object\" \|\| Array.isArray(annotations)) return null;\n const result: Record<string, unknown> = {};\n for (const [k, v] of Object.entries(annotations as Record<string, unknown>)) {\n if (v !== null && v !== undefined && v !== false && v !== 0 && !(Array.isArray(v) && v.length === 0)) {\n result[k] = v;\n }\n }\n return Object.keys(result).length > 0 ? result : null;\n}\n\n/\n Format and print full module metadata.\n /\nexport function formatModuleDetail(\n moduleDef: ModuleDescriptor,\n format: string,\n): void {\n if (format === \"table\") {\n process.stdout.write(`\\nModule: ${moduleDef.id}\\n`);\n process.stdout.write(`\\nDescription:\\n ${moduleDef.description}\\n`);\n\n if (moduleDef.inputSchema && Object.keys(moduleDef.inputSchema).length > 0) {\n process.stdout.write(\"\\nInput Schema:\\n\");\n process.stdout.write(JSON.stringify(moduleDef.inputSchema, null, 2) + \"\\n\");\n }\n\n if (moduleDef.outputSchema && Object.keys(moduleDef.outputSchema).length > 0) {\n process.stdout.write(\"\\nOutput Schema:\\n\");\n process.stdout.write(JSON.stringify(moduleDef.outputSchema, null, 2) + \"\\n\");\n }\n\n const annDict = annotationsToDict(\n moduleDef.annotations,\n );\n if (annDict) {\n process.stdout.write(\"\\nAnnotations:\\n\");\n for (const [k, v] of Object.entries(annDict)) {\n process.stdout.write(` ${k}: ${v}\\n`);\n }\n }\n\n // Extension metadata (x- prefixed)\n const metadata = moduleDef.metadata;\n if (metadata) {\n const xFields: Record<string, unknown> = {};\n for (const [k, v] of Object.entries(metadata)) {\n if (k.startsWith(\"x-\") \|\| k.startsWith(\"x_\")) {\n xFields[k] = v;\n }\n }\n if (Object.keys(xFields).length > 0) {\n process.stdout.write(\"\\nExtension Metadata:\\n\");\n for (const [k, v] of Object.entries(xFields)) {\n process.stdout.write(` ${k}: ${v}\\n`);\n }\n }\n }\n\n const tags = moduleDef.tags ?? [];\n if (tags.length > 0) {\n process.stdout.write(`\\nTags: ${tags.join(\", \")}\\n`);\n }\n } else if (format === \"json\") {\n const result: Record<string, unknown> = {\n id: moduleDef.id,\n description: moduleDef.description,\n };\n if (moduleDef.inputSchema) result.input_schema = moduleDef.inputSchema;\n if (moduleDef.outputSchema) result.output_schema = moduleDef.outputSchema;\n\n const annDict = annotationsToDict(\n moduleDef.annotations,\n );\n if (annDict) result.annotations = annDict;\n\n const tags = moduleDef.tags ?? [];\n if (tags.length > 0) result.tags = tags;\n\n // Extension metadata\n const metadata = moduleDef.metadata;\n if (metadata) {\n for (const [k, v] of Object.entries(metadata)) {\n if (k.startsWith(\"x-\") \|\| k.startsWith(\"x_\")) {\n result[k] = v;\n }\n }\n }\n\n process.stdout.write(JSON.stringify(result, null, 2) + \"\\n\");\n }\n}\n\n// ---------------------------------------------------------------------------\n// formatExecResult\n// ---------------------------------------------------------------------------\n\n/\n Format and print module execution result.\n /\nexport function formatExecResult(\n result: unknown,\n format?: string,\n): void {\n if (result === null \|\| result === undefined) {\n return;\n }\n const effective = resolveFormat(format);\n if (\n effective === \"table\" &&\n typeof result === \"object\" &&\n !Array.isArray(result)\n ) {\n // Key-value table\n const entries = Object.entries(result as Record<string, unknown>);\n const headers = [\"Key\", \"Value\"];\n const rows = entries.map(([k, v]) => [String(k), String(v)]);\n process.stdout.write(formatTable(headers, rows));\n } else if (typeof result === \"object\") {\n process.stdout.write(JSON.stringify(result, null, 2) + \"\\n\");\n } else if (typeof result === \"string\") {\n process.stdout.write(result + \"\\n\");\n } else {\n process.stdout.write(String(result) + \"\\n\");\n }\n}\n","/\n Simple structured logger respecting logging.level config.\n /\n\nconst LEVELS = { DEBUG: 0, INFO: 1, WARNING: 2, ERROR: 3 } as const;\ntype LogLevel = keyof typeof LEVELS;\n\nlet currentLevel: LogLevel = \"WARNING\";\n\nexport function setLogLevel(level: string): void {\n const upper = level.toUpperCase();\n if (upper in LEVELS) {\n currentLevel = upper as LogLevel;\n }\n}\n\nexport function getLogLevel(): LogLevel {\n return currentLevel;\n}\n\nfunction shouldLog(level: LogLevel): boolean {\n return LEVELS[level] >= LEVELS[currentLevel];\n}\n\nexport function debug(message: string): void {\n if (shouldLog(\"DEBUG\")) process.stderr.write(`DEBUG: ${message}\\n`);\n}\n\nexport function info(message: string): void {\n if (shouldLog(\"INFO\")) process.stderr.write(`INFO: ${message}\\n`);\n}\n\nexport function warn(message: string): void {\n if (shouldLog(\"WARNING\")) process.stderr.write(`WARNING: ${message}\\n`);\n}\n\nexport function error(message: string): void {\n if (shouldLog(\"ERROR\")) process.stderr.write(`ERROR: ${message}\\n`);\n}\n","/\n Init command — scaffold new apcore modules (Phase 1).\n /\n\nimport { Command } from \"commander\";\nimport as fs from \"node:fs\";\nimport * as path from \"node:path\";\n\nconst DECORATOR_TEMPLATE = `\\\nimport { module } from \"apcore-js\";\nimport { Type } from \"@sinclair/typebox\";\n\nexport const {varName} = module({\n id: \"{moduleId}\",\n description: \"{description}\",\n inputSchema: Type.Object({}),\n outputSchema: Type.Object({ status: Type.String() }),\n execute: (_inputs) => {\n // TODO: implement\n return { status: \"ok\" };\n },\n});\n`;\n\nconst CONVENTION_TEMPLATE = `\\\n/*\n {description}\n /\n{cliGroupLine}\nexport function {funcName}(): Record<string, unknown> {\n // TODO: implement\n return { status: \"ok\" };\n}\n`;\n\nconst BINDING_TEMPLATE = `\\\nbindings:\n - module_id: \"{moduleId}\"\n target: \"{target}\"\n description: \"{description}\"\n auto_schema: true\n`;\n\n/\n Simple template rendering: replaces {key} with values from the context.\n /\nfunction renderTemplate(template: string, context: Record<string, string>): string {\n let result = template;\n for (const [key, value] of Object.entries(context)) {\n // Replace all occurrences of {key} with the value\n result = result.split(`{${key}}`).join(value);\n }\n return result;\n}\n\n/\n Register the init command group on the CLI program.\n /\nexport function registerInitCommand(cli: Command): void {\n const initGroup = cli.command(\"init\").description(\"Scaffold new apcore modules.\");\n\n initGroup\n .command(\"module <module-id>\")\n .description(\"Create a new module from a template.\\n\\nMODULE_ID is the module identifier (e.g., ops.deploy, user.create).\")\n .option(\n \"--style <style>\",\n \"Module style: decorator (@module), convention (plain function), or binding (YAML).\",\n \"convention\",\n )\n .option(\"--dir <path>\", \"Output directory. Default: extensions/ or commands/.\")\n .option(\"-d, --description <text>\", \"Module description.\", \"TODO: add description\")\n .action((moduleId: string, opts: { style: string; dir?: string; description: string }) => {\n // Parse module_id into parts\n const lastDot = moduleId.lastIndexOf(\".\");\n const prefix = lastDot >= 0 ? moduleId.substring(0, lastDot) : moduleId;\n const funcName = lastDot >= 0 ? moduleId.substring(lastDot + 1) : moduleId;\n\n const style = opts.style;\n const description = opts.description;\n\n // Validate --dir to prevent path traversal\n const dir = opts.dir ?? (style === \"decorator\" ? \"extensions\" : style === \"binding\" ? \"bindings\" : \"commands\");\n if (dir.split(path.sep).includes(\"..\") \|\| dir.split(\"/\").includes(\"..\")) {\n process.stderr.write(`Error: Output directory must not contain '..' path components.\\n`);\n process.exit(2);\n }\n\n switch (style) {\n case \"decorator\":\n createDecoratorModule(moduleId, prefix, funcName, description, dir);\n break;\n case \"convention\":\n createConventionModule(moduleId, prefix, funcName, description, dir);\n break;\n case \"binding\":\n createBindingModule(moduleId, prefix, funcName, description, dir);\n break;\n default:\n process.stderr.write(`Error: Unknown style '${style}'\\n`);\n process.exit(2);\n }\n });\n}\n\nfunction createDecoratorModule(\n moduleId: string,\n _prefix: string,\n funcName: string,\n description: string,\n outputDir: string,\n): void {\n fs.mkdirSync(outputDir, { recursive: true });\n const filename = moduleId.replace(/\\./g, \"_\") + \".ts\";\n const filepath = path.join(outputDir, filename);\n\n const varName = funcName + \"Module\";\n const content = renderTemplate(DECORATOR_TEMPLATE, {\n moduleId,\n varName,\n funcName,\n description,\n });\n fs.writeFileSync(filepath, content);\n process.stdout.write(`Created ${filepath}\\n`);\n}\n\nfunction createConventionModule(\n moduleId: string,\n prefix: string,\n funcName: string,\n description: string,\n outputDir: string,\n): void {\n // If prefix has dots, create subdirectories\n const prefixParts = prefix.split(\".\");\n const dirPath = prefixParts.length > 1\n ? path.join(outputDir, ...prefixParts.slice(0, -1))\n : outputDir;\n fs.mkdirSync(dirPath, { recursive: true });\n\n let filename: string;\n if (prefixParts.length > 1) {\n filename = prefixParts[prefixParts.length - 1] + \".ts\";\n } else {\n filename = prefix + \".ts\";\n }\n // If the file would be the same as the function name, use prefix as filename\n if (prefix === funcName) {\n filename = prefix + \".ts\";\n }\n const filepath = path.join(dirPath, filename);\n\n const cliGroupLine = moduleId.includes(\".\")\n ? `export const CLI_GROUP = \"${prefixParts[0]}\";\\n`\n : \"\";\n\n const content = renderTemplate(CONVENTION_TEMPLATE, {\n funcName,\n description,\n cliGroupLine,\n });\n fs.writeFileSync(filepath, content);\n process.stdout.write(`Created ${filepath}\\n`);\n}\n\nfunction createBindingModule(\n moduleId: string,\n prefix: string,\n funcName: string,\n description: string,\n outputDir: string,\n): void {\n fs.mkdirSync(outputDir, { recursive: true });\n\n const yamlFile = path.join(outputDir, moduleId.replace(/\\./g, \"_\") + \".binding.yaml\");\n const target = `commands.${prefix}:${funcName}`;\n\n const yamlContent = renderTemplate(BINDING_TEMPLATE, {\n moduleId,\n target,\n description,\n });\n fs.writeFileSync(yamlFile, yamlContent);\n process.stdout.write(`Created ${yamlFile}\\n`);\n\n // Also create the target function file\n const baseSrc = \"commands\";\n fs.mkdirSync(baseSrc, { recursive: true });\n const srcFile = path.join(baseSrc, prefix.replace(/\\./g, \"_\") + \".ts\");\n if (!fs.existsSync(srcFile)) {\n const srcContent =\n `export function ${funcName}(): Record<string, unknown> {\\n` +\n ` /* ${description} /\\n` +\n \" // TODO: implement\\n\" +\n ' return { status: \"ok\" };\\n' +\n \"}\\n\";\n fs.writeFileSync(srcFile, srcContent);\n process.stdout.write(`Created ${srcFile}\\n`);\n }\n}\n","/\n Display overlay helpers — shared resolution logic for CLI surfaces.\n /\n\nimport type { ModuleDescriptor } from \"./cli.js\";\n\n/\n Extract resolved display overlay from a ModuleDescriptor's metadata.\n /\nexport function getDisplay(descriptor: ModuleDescriptor): Record<string, unknown> {\n const metadata = descriptor.metadata ?? {};\n const display = (metadata as Record<string, unknown>).display;\n if (display && typeof display === \"object\" && !Array.isArray(display)) {\n return display as Record<string, unknown>;\n }\n return {};\n}\n\n/\n Return [displayName, description, tags] resolved from the display overlay.\n \n Falls back to scanner-provided values when no overlay is present.\n */\nexport function getCliDisplayFields(descriptor: ModuleDescriptor): [string, string, string[]] {\n const display = getDisplay(descriptor);\n const cli = (display.cli && typeof display.cli === \"object\" && !Array.isArray(display.cli))\n ? (display.cli as Record<string, unknown>)\n : {};\n const name = (cli.alias as string \| undefined)\n ?? (display.alias as string \| undefined)\n ?? descriptor.id;\n const desc = (cli.description as string \| undefined) ?? descriptor.description;\n const tags = (display.tags as string[] \| undefined) ?? descriptor.tags ?? [];\n return [name, desc, tags];\n}\n"],"mappings":"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","names":["fileURLToPath","path","path","__dirname","fileURLToPath","__dirname"]}
1	+ {"version":3,"sources":["../../node_modules/.pnpm/tsup@8.5.1_postcss@8.5.8_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js","../../src/errors.ts","../../bin/apcore-cli.ts","../../src/main.ts","../../src/ref-resolver.ts","../../src/schema-parser.ts","../../src/approval.ts","../../src/output.ts","../../src/logger.ts","../../src/init-cmd.ts","../../src/display-helpers.ts","../../src/config.ts","../../src/shell.ts"],"sourcesContent":["// Shim globals in esm bundle\nimport path from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nconst getFilename = () => fileURLToPath(import.meta.url)\nconst getDirname = () => path.dirname(getFilename())\n\nexport const __dirname = /* @__PURE__ / getDirname()\nexport const __filename = / @__PURE__ / getFilename()\n","/\n Error classes and exit code mapping for apcore-cli.\n \n Protocol spec: Error handling & exit codes\n /\n\n// ---------------------------------------------------------------------------\n// Error classes\n// ---------------------------------------------------------------------------\n\n/* Thrown when the user does not approve module execution within the timeout. /\nexport class ApprovalTimeoutError extends Error {\n constructor(message = \"Approval timed out\") {\n super(message);\n this.name = \"ApprovalTimeoutError\";\n }\n}\n\n/* Thrown when API key authentication fails or is missing. /\nexport class AuthenticationError extends Error {\n constructor(message = \"Authentication failed\") {\n super(message);\n this.name = \"AuthenticationError\";\n }\n}\n\n/* Thrown when encrypted config cannot be decrypted. /\nexport class ConfigDecryptionError extends Error {\n constructor(message = \"Config decryption failed\") {\n super(message);\n this.name = \"ConfigDecryptionError\";\n }\n}\n\n/* Thrown when module execution fails. /\nexport class ModuleExecutionError extends Error {\n constructor(message = \"Module execution failed\") {\n super(message);\n this.name = \"ModuleExecutionError\";\n }\n}\n\n/* Thrown when approval is denied by the user. /\nexport class ApprovalDeniedError extends Error {\n constructor(message = \"Approval denied\") {\n super(message);\n this.name = \"ApprovalDeniedError\";\n }\n}\n\n/* Thrown when schema validation fails. /\nexport class SchemaValidationError extends Error {\n constructor(message = \"Schema validation failed\") {\n super(message);\n this.name = \"SchemaValidationError\";\n }\n}\n\n/* Thrown when a module is not found. /\nexport class ModuleNotFoundError extends Error {\n constructor(message = \"Module not found\") {\n super(message);\n this.name = \"ModuleNotFoundError\";\n }\n}\n\n// ---------------------------------------------------------------------------\n// Exit code map\n// ---------------------------------------------------------------------------\n\nexport const EXIT_CODES = {\n SUCCESS: 0,\n MODULE_EXECUTE_ERROR: 1,\n MODULE_TIMEOUT: 1,\n INVALID_CLI_INPUT: 2,\n MODULE_NOT_FOUND: 44,\n MODULE_LOAD_ERROR: 44,\n MODULE_DISABLED: 44,\n SCHEMA_VALIDATION_ERROR: 45,\n APPROVAL_DENIED: 46,\n APPROVAL_TIMEOUT: 46,\n CONFIG_NOT_FOUND: 47,\n CONFIG_INVALID: 47,\n SCHEMA_CIRCULAR_REF: 48,\n ACL_DENIED: 77,\n // Config Bus errors (apcore >= 0.15.0)\n CONFIG_NAMESPACE_RESERVED: 78,\n CONFIG_NAMESPACE_DUPLICATE: 78,\n CONFIG_ENV_PREFIX_CONFLICT: 78,\n CONFIG_MOUNT_ERROR: 66,\n CONFIG_BIND_ERROR: 65,\n ERROR_FORMATTER_DUPLICATE: 70,\n KEYBOARD_INTERRUPT: 130,\n} as const;\n\nexport type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/\n Map a caught error to the appropriate process exit code.\n * Also checks for apcore error codes on the error object.\n /\nexport function exitCodeForError(error: unknown): ExitCode {\n if (error instanceof ApprovalTimeoutError) {\n return EXIT_CODES.APPROVAL_TIMEOUT;\n }\n if (error instanceof ApprovalDeniedError) {\n return EXIT_CODES.APPROVAL_DENIED;\n }\n if (error instanceof AuthenticationError) {\n return EXIT_CODES.ACL_DENIED;\n }\n if (error instanceof ConfigDecryptionError) {\n return EXIT_CODES.CONFIG_INVALID;\n }\n if (error instanceof SchemaValidationError) {\n return EXIT_CODES.SCHEMA_VALIDATION_ERROR;\n }\n if (error instanceof ModuleNotFoundError) {\n return EXIT_CODES.MODULE_NOT_FOUND;\n }\n if (error instanceof ModuleExecutionError) {\n return EXIT_CODES.MODULE_EXECUTE_ERROR;\n }\n\n // Check for apcore error codes on the error object\n if (error instanceof Error) {\n const code = (error as unknown as Record<string, unknown>).code as string \| undefined;\n const codeMap: Record<string, ExitCode> = {\n MODULE_NOT_FOUND: EXIT_CODES.MODULE_NOT_FOUND,\n MODULE_LOAD_ERROR: EXIT_CODES.MODULE_LOAD_ERROR,\n MODULE_DISABLED: EXIT_CODES.MODULE_DISABLED,\n SCHEMA_VALIDATION_ERROR: EXIT_CODES.SCHEMA_VALIDATION_ERROR,\n SCHEMA_CIRCULAR_REF: EXIT_CODES.SCHEMA_CIRCULAR_REF,\n APPROVAL_DENIED: EXIT_CODES.APPROVAL_DENIED,\n APPROVAL_TIMEOUT: EXIT_CODES.APPROVAL_TIMEOUT,\n APPROVAL_PENDING: EXIT_CODES.APPROVAL_DENIED,\n CONFIG_NOT_FOUND: EXIT_CODES.CONFIG_NOT_FOUND,\n CONFIG_INVALID: EXIT_CODES.CONFIG_INVALID,\n MODULE_EXECUTE_ERROR: EXIT_CODES.MODULE_EXECUTE_ERROR,\n MODULE_TIMEOUT: EXIT_CODES.MODULE_TIMEOUT,\n ACL_DENIED: EXIT_CODES.ACL_DENIED,\n // Config Bus errors (apcore >= 0.15.0)\n CONFIG_NAMESPACE_RESERVED: EXIT_CODES.CONFIG_NAMESPACE_RESERVED,\n CONFIG_NAMESPACE_DUPLICATE: EXIT_CODES.CONFIG_NAMESPACE_DUPLICATE,\n CONFIG_ENV_PREFIX_CONFLICT: EXIT_CODES.CONFIG_ENV_PREFIX_CONFLICT,\n CONFIG_MOUNT_ERROR: EXIT_CODES.CONFIG_MOUNT_ERROR,\n CONFIG_BIND_ERROR: EXIT_CODES.CONFIG_BIND_ERROR,\n ERROR_FORMATTER_DUPLICATE: EXIT_CODES.ERROR_FORMATTER_DUPLICATE,\n };\n if (code && code in codeMap) {\n return codeMap[code];\n }\n }\n\n return EXIT_CODES.MODULE_EXECUTE_ERROR;\n}\n","#!/usr/bin/env node\n/\n apcore-cli — Shebang entry point.\n \n This file is the bin target. It bootstraps the CLI and delegates to main().\n /\n\nimport { main } from \"../src/main.js\";\n\nmain(\"apcore-cli\");\n","/\n CLI entry point — createCli / main equivalents.\n \n Protocol spec: CLI bootstrapping & command registration\n /\n\nimport { readFileSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport as path from \"node:path\";\nimport { Command, CommanderError, Option } from \"commander\";\nimport { EXIT_CODES, exitCodeForError } from \"./errors.js\";\nimport { resolveRefs } from \"./ref-resolver.js\";\nimport { schemaToCliOptions } from \"./schema-parser.js\";\nimport { checkApproval } from \"./approval.js\";\nimport { formatExecResult } from \"./output.js\";\nimport { setLogLevel } from \"./logger.js\";\nimport { registerInitCommand } from \"./init-cmd.js\";\nimport { getDisplay } from \"./display-helpers.js\";\nimport { registerConfigNamespace } from \"./config.js\";\nimport { configureManHelp } from \"./shell.js\";\nimport type { Executor, ModuleDescriptor } from \"./cli.js\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\n\n/** Whether --verbose was passed (controls help detail level). /\nexport let verboseHelp = false;\n\n/* Set the verbose help flag. When false, built-in options are hidden from help. /\nexport function setVerboseHelp(verbose: boolean): void {\n verboseHelp = verbose;\n}\n\n/* Base URL for online documentation. Null means no docs link shown. /\nexport let docsUrl: string \| null = null;\n\n/\n Set the base URL for online documentation links shown in help and man pages.\n * Pass null to disable. Command-level help appends `/commands/{name}` automatically.\n \n @example setDocsUrl(\"https://docs.apcore.dev/cli\");\n /\nexport function setDocsUrl(url: string \| null): void {\n docsUrl = url;\n}\n\n/* Check if --verbose is present in process.argv (pre-parse, before Commander). /\nfunction hasVerboseFlag(): boolean {\n return process.argv.includes(\"--verbose\");\n}\n\nlet VERSION = \"0.0.0\";\ntry {\n const pkg = JSON.parse(readFileSync(path.resolve(__dirname, \"../package.json\"), \"utf-8\"));\n VERSION = pkg.version;\n} catch {\n // Bundled environments (e.g., Bun compile) may not have package.json accessible\n}\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/* Configuration for a single Commander option derived from a JSON Schema property. /\nexport interface OptionConfig {\n /* The property name from the schema. /\n name: string;\n /* Commander flags string (e.g. \"--my-flag <value>\" or \"--flag, --no-flag\"). /\n flags: string;\n /* Help text for the option. /\n description: string;\n /* Default value. /\n defaultValue?: unknown;\n /* Whether the field is required (for display only). /\n required: boolean;\n /* Enum choices (string values). /\n choices?: string[];\n /* Whether this is a boolean flag pair (--flag/--no-flag). /\n isBooleanFlag?: boolean;\n /* Maps string enum value → original type name (\"int\", \"float\", \"bool\"). /\n enumOriginalTypes?: Record<string, string>;\n /* Parser function for Commander (e.g. parseInt, parseFloat). /\n parseArg?: (value: string) => unknown;\n}\n\n// ---------------------------------------------------------------------------\n// createCli\n// ---------------------------------------------------------------------------\n\n/\n Build and return the top-level Commander program.\n \n @param extensionsDir Path to the extensions directory (default: ./extensions)\n * @param progName Program name shown in help (default: apcore-cli)\n /\nexport function createCli(\n extensionsDir?: string,\n progName?: string,\n verbose = false,\n): Command {\n verboseHelp = verbose;\n // Register Config Bus namespace (apcore >= 0.15.0)\n registerConfigNamespace();\n // Resolve program name\n const resolvedProgName = progName ?? path.basename(process.argv[1] ?? \"apcore-cli\") ?? \"apcore-cli\";\n\n // Resolve log level\n const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? \"WARNING\";\n setLogLevel(cliLogLevel);\n\n const program = new Command(resolvedProgName)\n .exitOverride()\n .version(VERSION, \"--version\", `Show ${resolvedProgName} version`)\n .description(\"apcore CLI — execute apcore modules from the command line\")\n .option(\"--extensions-dir <path>\", \"Path to extensions directory\")\n .option(\"--commands-dir <path>\", \"Path to convention-based commands directory\")\n .option(\"--binding <path>\", \"Path to binding.yaml for display overlay\")\n .option(\"--log-level <level>\", \"Logging level (DEBUG\|INFO\|WARNING\|ERROR)\", \"WARNING\")\n .option(\"--verbose\", \"Show all options in help output (including built-in apcore options)\");\n\n // NOTE: Full registry/executor wiring requires apcore-js to be available.\n // For now, extensions-dir is accepted but not wired to a real registry.\n const resolvedExtDir = extensionsDir\n ?? process.env.APCORE_EXTENSIONS_ROOT\n ?? \"./extensions\";\n void resolvedExtDir; // Will be used when apcore-js registry is wired\n\n // Footer hints for discoverability\n program.addHelpText(\"after\", [\n \"\",\n \"Use --help --verbose to show all options (including built-in apcore options).\",\n \"Use --help --man to display a formatted man page.\",\n ].join(\"\\n\"));\n\n // Register init command for scaffolding\n registerInitCommand(program);\n\n // Register --help --man support\n configureManHelp(program, resolvedProgName, VERSION);\n\n // Hook to apply optional toolkit integration before command execution.\n // Commander actions are async, so we can set up toolkit state lazily.\n program.hook(\"preAction\", async (thisCommand) => {\n const opts = thisCommand.opts();\n const commandsDir = opts.commandsDir as string \| undefined;\n const bindingPath = opts.binding as string \| undefined;\n await applyToolkitIntegration(commandsDir, bindingPath);\n });\n\n return program;\n}\n\n// ---------------------------------------------------------------------------\n// applyToolkitIntegration\n// ---------------------------------------------------------------------------\n\n/\n Optionally apply apcore-toolkit features (DisplayResolver, RegistryWriter).\n \n Uses dynamic import so the dependency remains optional — if apcore-toolkit\n * is not installed, a warning is printed and the CLI continues without it.\n /\nexport async function applyToolkitIntegration(\n commandsDir?: string,\n bindingPath?: string,\n): Promise<void> {\n if (!commandsDir && !bindingPath) {\n return;\n }\n\n try {\n // Use a variable to prevent TypeScript from resolving the module at build time\n const toolkitModule = \"apcore-toolkit\";\n // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment\n const toolkit = await import(/ @vite-ignore / toolkitModule);\n\n // ConventionScanner is not yet available in the TypeScript toolkit\n if (commandsDir) {\n console.warn(\"Convention scanning not yet available in TypeScript toolkit\");\n }\n\n // DisplayResolver for binding overlay\n if (bindingPath) {\n const resolver = new toolkit.DisplayResolver();\n // NOTE: Full integration requires registered modules from apcore-js.\n // For now, the resolver is instantiated and ready for when modules\n // are available through the registry.\n void resolver;\n }\n } catch {\n // apcore-toolkit not installed — graceful fallback\n console.warn(\"apcore-toolkit not installed — toolkit features unavailable\");\n }\n}\n\n// ---------------------------------------------------------------------------\n// main\n// ---------------------------------------------------------------------------\n\n/\n Parse argv and run the CLI. Handles top-level error catching and exit codes.\n /\nexport function main(progName?: string): void {\n verboseHelp = hasVerboseFlag();\n const program = createCli(undefined, progName, verboseHelp);\n\n try {\n program.parse(process.argv);\n } catch (error: unknown) {\n if (error instanceof CommanderError) {\n // Commander already printed the error message\n process.exit(error.exitCode);\n }\n const code = exitCodeForError(error);\n if (error instanceof Error) {\n process.stderr.write(`Error: ${error.message}\\n`);\n }\n process.exit(code);\n }\n}\n\n// ---------------------------------------------------------------------------\n// buildModuleCommand\n// ---------------------------------------------------------------------------\n\n/\n Build a Commander Command for a single apcore module.\n /\nexport function buildModuleCommand(\n moduleDef: ModuleDescriptor,\n executor: Executor,\n helpTextMaxLength = 1000,\n cmdName?: string,\n verbose = verboseHelp,\n): Command {\n const moduleId = moduleDef.id;\n let resolvedSchema: Record<string, unknown> = {};\n let schemaOptions: OptionConfig[] = [];\n\n // Resolve display overlay fields\n const display = getDisplay(moduleDef);\n const cliDisplay = (display.cli && typeof display.cli === \"object\" && !Array.isArray(display.cli))\n ? (display.cli as Record<string, unknown>)\n : {};\n const effectiveCmdName: string = cmdName ?? (cliDisplay.alias as string \| undefined) ?? moduleId;\n const cmdHelp: string = (cliDisplay.description as string \| undefined) ?? moduleDef.description;\n\n // Resolve schema\n const inputSchema = moduleDef.inputSchema;\n if (inputSchema && typeof inputSchema === \"object\" && inputSchema.properties) {\n try {\n resolvedSchema = resolveRefs(inputSchema, 32, moduleId);\n } catch {\n resolvedSchema = inputSchema;\n }\n schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);\n }\n\n const cmd = new Command(effectiveCmdName).description(cmdHelp);\n\n // Built-in options (hidden unless --verbose)\n const inputOpt = new Option(\"--input <source>\", \"Read JSON input from a file path, or use '-' to read from stdin pipe\");\n const yesOpt = new Option(\"-y, --yes\", \"Skip interactive approval prompts (for scripts and CI)\").default(false);\n const largeInputOpt = new Option(\"--large-input\", \"Allow stdin input larger than 10MB (default limit protects against accidental pipes)\").default(false);\n const formatOpt = new Option(\"--format <format>\", \"Set output format: 'json' for machine-readable, 'table' for human-readable\");\n // --sandbox is always hidden (not yet implemented)\n const sandboxOpt = new Option(\"--sandbox\", \"Run module in an isolated subprocess with restricted filesystem and env access\").default(false).hideHelp();\n\n if (!verbose) {\n inputOpt.hideHelp();\n yesOpt.hideHelp();\n largeInputOpt.hideHelp();\n formatOpt.hideHelp();\n }\n\n cmd.addOption(inputOpt);\n cmd.addOption(yesOpt);\n cmd.addOption(largeInputOpt);\n cmd.addOption(formatOpt);\n cmd.addOption(sandboxOpt);\n\n // Help footer: verbose hint + optional docs link\n const footerParts: string[] = [];\n if (!verbose) {\n footerParts.push(\"Use --verbose to show all options (including built-in apcore options).\");\n }\n if (docsUrl) {\n footerParts.push(`Docs: ${docsUrl}/commands/${effectiveCmdName}`);\n }\n if (footerParts.length > 0) {\n cmd.addHelpText(\"after\", \"\\n\" + footerParts.join(\"\\n\") + \"\\n\");\n }\n\n // Schema-generated options\n for (const opt of schemaOptions) {\n if (opt.parseArg) {\n cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);\n } else {\n cmd.option(opt.flags, opt.description, opt.defaultValue as string \| boolean \| undefined);\n }\n }\n\n // Action callback\n cmd.action(async (options: Record<string, unknown>) => {\n // Pop built-in options\n const stdinFlag = options.input as string \| undefined;\n const autoApprove = options.yes as boolean;\n const largeInput = options.largeInput as boolean;\n const outputFormat = options.format as string \| undefined;\n const sandboxEnabled = options.sandbox as boolean;\n\n // Remove built-in keys from options to get schema kwargs\n const schemaKwargs: Record<string, unknown> = {};\n const builtinKeys = new Set([\"input\", \"yes\", \"largeInput\", \"format\", \"sandbox\", \"verbose\"]);\n for (const [k, v] of Object.entries(options)) {\n if (!builtinKeys.has(k)) {\n schemaKwargs[k] = v;\n }\n }\n\n try {\n // Collect and merge input\n const merged = await collectInput(stdinFlag, schemaKwargs, largeInput);\n\n // Reconvert enum values\n const reconverted = reconvertEnumValues(merged, schemaOptions);\n\n // Check approval\n await checkApproval(moduleDef, autoApprove);\n\n // Execute with timing\n const { Sandbox } = await import(\"./security/index.js\");\n const sandbox = new Sandbox(sandboxEnabled);\n const startTime = performance.now();\n const result = await sandbox.execute(moduleId, reconverted, executor);\n const durationMs = Math.round(performance.now() - startTime);\n\n // Audit log (success)\n const { getAuditLogger } = await import(\"./security/audit.js\");\n const auditLogger = getAuditLogger();\n if (auditLogger) {\n auditLogger.logExecution(moduleId, reconverted, \"success\", 0, durationMs);\n }\n\n // Format output\n formatExecResult(result, outputFormat);\n } catch (err: unknown) {\n // Audit log (error)\n const { getAuditLogger } = await import(\"./security/audit.js\");\n const auditLogger = getAuditLogger();\n const code = exitCodeForError(err);\n if (auditLogger) {\n auditLogger.logExecution(moduleId, {}, \"error\", code, 0);\n }\n\n if (err instanceof Error) {\n process.stderr.write(`Error: ${err.message}\\n`);\n }\n process.exit(code);\n }\n });\n\n return cmd;\n}\n\n// ---------------------------------------------------------------------------\n// validateModuleId\n// ---------------------------------------------------------------------------\n\n/\n Validate that a module ID conforms to the expected format.\n * Pattern: [a-z][a-z0-9_](.[a-z][a-z0-9_]) — max 128 chars.\n /\nexport function validateModuleId(moduleId: string): void {\n if (moduleId.length > 128) {\n process.stderr.write(\n `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n if (!/^[a-z][a-z0-9_](\\.[a-z][a-z0-9_])$/.test(moduleId)) {\n process.stderr.write(\n `Error: Invalid module ID format: '${moduleId}'.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n}\n\n// ---------------------------------------------------------------------------\n// collectInput\n// ---------------------------------------------------------------------------\n\n/*\n Collect module input from stdin and/or CLI keyword arguments.\n /\nexport async function collectInput(\n stdinFlag?: string,\n cliKwargs: Record<string, unknown> = {},\n largeInput?: boolean,\n): Promise<Record<string, unknown>> {\n // Remove null/undefined values from CLI kwargs\n const cliKwargsNonNull: Record<string, unknown> = {};\n for (const [k, v] of Object.entries(cliKwargs)) {\n if (v !== null && v !== undefined) {\n cliKwargsNonNull[k] = v;\n }\n }\n\n if (!stdinFlag) {\n return cliKwargsNonNull;\n }\n\n if (stdinFlag === \"-\") {\n const raw = await readStdin();\n const rawSize = Buffer.byteLength(raw, \"utf-8\");\n\n if (rawSize > 10_485_760 && !largeInput) {\n process.stderr.write(\n \"Error: STDIN input exceeds 10MB limit. Use --large-input to override.\\n\",\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n if (!raw) {\n return cliKwargsNonNull;\n }\n\n let stdinData: unknown;\n try {\n stdinData = JSON.parse(raw);\n } catch {\n process.stderr.write(\n \"Error: STDIN does not contain valid JSON.\\n\",\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n if (typeof stdinData !== \"object\" \|\| stdinData === null \|\| Array.isArray(stdinData)) {\n process.stderr.write(\n `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? \"array\" : typeof stdinData}.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n // CLI flags override STDIN for duplicate keys\n return { ...(stdinData as Record<string, unknown>), ...cliKwargsNonNull };\n }\n\n return cliKwargsNonNull;\n}\n\n/\n Read all data from stdin with proper cleanup.\n /\nfunction readStdin(): Promise<string> {\n return new Promise((resolve, reject) => {\n const chunks: Buffer[] = [];\n const onData = (chunk: Buffer) => chunks.push(chunk);\n const onEnd = () => {\n cleanup();\n resolve(Buffer.concat(chunks).toString(\"utf-8\"));\n };\n const onError = (err: Error) => {\n cleanup();\n reject(err);\n };\n const cleanup = () => {\n process.stdin.removeListener(\"data\", onData);\n process.stdin.removeListener(\"end\", onEnd);\n process.stdin.removeListener(\"error\", onError);\n };\n process.stdin.on(\"data\", onData);\n process.stdin.on(\"end\", onEnd);\n process.stdin.on(\"error\", onError);\n process.stdin.resume();\n });\n}\n\n// ---------------------------------------------------------------------------\n// reconvertEnumValues\n// ---------------------------------------------------------------------------\n\n/\n Re-convert CLI string values back to their schema-typed equivalents\n * based on the option configs.\n /\nexport function reconvertEnumValues(\n kwargs: Record<string, unknown>,\n options: OptionConfig[],\n): Record<string, unknown> {\n const result = { ...kwargs };\n for (const opt of options) {\n if (!opt.enumOriginalTypes) continue;\n const paramName = opt.name;\n if (!(paramName in result) \|\| result[paramName] === null \|\| result[paramName] === undefined) {\n continue;\n }\n const strVal = String(result[paramName]);\n const origType = opt.enumOriginalTypes[strVal];\n if (origType === \"int\") {\n result[paramName] = parseInt(strVal, 10);\n } else if (origType === \"float\") {\n result[paramName] = parseFloat(strVal);\n } else if (origType === \"bool\") {\n result[paramName] = strVal.toLowerCase() === \"true\";\n }\n }\n return result;\n}\n","/\n JSON Schema $ref resolver.\n \n Protocol spec: Schema resolution & $ref handling\n /\n\nimport { EXIT_CODES } from \"./errors.js\";\n\n// ---------------------------------------------------------------------------\n// resolveRefs\n// ---------------------------------------------------------------------------\n\n/\n Resolve all $ref references in a JSON Schema.\n * Returns a fully inlined schema with $defs/definitions removed.\n /\nexport function resolveRefs(\n schema: Record<string, unknown>,\n maxDepth = 32,\n moduleId = \"\",\n): Record<string, unknown> {\n const cloned = structuredClone(schema);\n const defs = (cloned.$defs ?? cloned.definitions ?? {}) as Record<\n string,\n unknown\n >;\n const result = resolveNode(\n cloned,\n defs,\n new Set<string>(),\n 0,\n maxDepth,\n moduleId,\n ) as Record<string, unknown>;\n\n // Remove definition keys\n delete result.$defs;\n delete result.definitions;\n return result;\n}\n\nfunction resolveNode(\n node: unknown,\n defs: Record<string, unknown>,\n visited: Set<string>,\n depth: number,\n maxDepth: number,\n moduleId: string,\n): unknown {\n if (typeof node !== \"object\" \|\| node === null \|\| Array.isArray(node)) {\n return node;\n }\n\n const obj = node as Record<string, unknown>;\n\n // Handle $ref\n if (\"$ref\" in obj) {\n const refPath = obj.$ref as string;\n\n if (depth >= maxDepth) {\n process.stderr.write(\n `Error: $ref resolution depth exceeded maximum of ${maxDepth} for module '${moduleId}'.\\n`,\n );\n process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);\n }\n\n if (visited.has(refPath)) {\n process.stderr.write(\n `Error: Circular $ref detected in schema for module '${moduleId}' at path '${refPath}'.\\n`,\n );\n process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);\n }\n\n // Parse ref target: extract key from \"#/$defs/Address\" → \"Address\"\n const parts = refPath.split(\"/\");\n const key = parts[parts.length - 1];\n\n if (!(key in defs)) {\n process.stderr.write(\n `Error: Unresolvable $ref '${refPath}' in schema for module '${moduleId}'.\\n`,\n );\n process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);\n }\n\n const newVisited = new Set(visited);\n newVisited.add(refPath);\n return resolveNode(defs[key], defs, newVisited, depth + 1, maxDepth, moduleId);\n }\n\n // Handle allOf\n if (\"allOf\" in obj && Array.isArray(obj.allOf)) {\n const merged: Record<string, unknown> = {\n properties: {},\n required: [] as string[],\n };\n for (const subSchema of obj.allOf as unknown[]) {\n const resolved = resolveNode(\n subSchema,\n defs,\n visited,\n depth + 1,\n maxDepth,\n moduleId,\n ) as Record<string, unknown>;\n if (resolved.properties) {\n Object.assign(\n merged.properties as Record<string, unknown>,\n resolved.properties,\n );\n }\n if (Array.isArray(resolved.required)) {\n (merged.required as string[]).push(...resolved.required);\n }\n }\n // Deduplicate required\n merged.required = [...new Set(merged.required as string[])];\n // Copy non-composition keys\n for (const [k, v] of Object.entries(obj)) {\n if (k !== \"allOf\" && !(k in merged)) {\n merged[k] = v;\n }\n }\n return merged;\n }\n\n // Handle anyOf / oneOf\n for (const keyword of [\"anyOf\", \"oneOf\"]) {\n if (keyword in obj && Array.isArray(obj[keyword])) {\n const merged: Record<string, unknown> = {\n properties: {},\n required: [] as string[],\n };\n const allRequiredSets: Set<string>[] = [];\n for (const subSchema of obj[keyword] as unknown[]) {\n const resolved = resolveNode(\n subSchema,\n defs,\n visited,\n depth + 1,\n maxDepth,\n moduleId,\n ) as Record<string, unknown>;\n if (resolved.properties) {\n Object.assign(\n merged.properties as Record<string, unknown>,\n resolved.properties,\n );\n }\n if (Array.isArray(resolved.required)) {\n allRequiredSets.push(new Set(resolved.required as string[]));\n }\n }\n // Required = intersection of all branches\n if (allRequiredSets.length > 0) {\n let intersection = allRequiredSets[0];\n for (let i = 1; i < allRequiredSets.length; i++) {\n intersection = new Set(\n [...intersection].filter((x) => allRequiredSets[i].has(x)),\n );\n }\n merged.required = [...intersection];\n } else {\n merged.required = [];\n }\n // Copy non-composition keys\n for (const [k, v] of Object.entries(obj)) {\n if (k !== keyword && !(k in merged)) {\n merged[k] = v;\n }\n }\n return merged;\n }\n }\n\n // Recursively process nested properties\n if (\"properties\" in obj && typeof obj.properties === \"object\" && obj.properties !== null) {\n const props = obj.properties as Record<string, unknown>;\n for (const [propName, propSchema] of Object.entries(props)) {\n props[propName] = resolveNode(\n propSchema,\n defs,\n visited,\n depth + 1,\n maxDepth,\n moduleId,\n );\n }\n }\n\n return obj;\n}\n","/\n JSON Schema -> Commander options mapping.\n \n Protocol spec: Schema-driven argument parsing\n /\n\nimport type { OptionConfig } from \"./main.js\";\nimport { EXIT_CODES } from \"./errors.js\";\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\n/* Sentinel type marker for boolean flags. /\nconst BOOLEAN_FLAG = Symbol(\"BOOLEAN_FLAG\");\n\ntype TypeResult = \"string\" \| \"int\" \| \"float\" \| typeof BOOLEAN_FLAG \| \"file\";\n\n/\n Map JSON Schema type to a type identifier.\n /\nexport function mapType(propName: string, propSchema: Record<string, unknown>): TypeResult {\n const schemaType = propSchema.type as string \| undefined;\n\n // Check file convention\n if (\n schemaType === \"string\" &&\n (propName.endsWith(\"_file\") \|\| propSchema[\"x-cli-file\"] === true)\n ) {\n return \"file\";\n }\n\n const typeMap: Record<string, TypeResult> = {\n string: \"string\",\n integer: \"int\",\n number: \"float\",\n boolean: BOOLEAN_FLAG,\n object: \"string\",\n array: \"string\",\n };\n\n if (!schemaType) {\n return \"string\";\n }\n\n return typeMap[schemaType] ?? \"string\";\n}\n\n/\n Extract help text from schema property, preferring x-llm-description.\n /\nexport function extractHelp(propSchema: Record<string, unknown>, maxLength = 1000): string \| undefined {\n let text = propSchema[\"x-llm-description\"] as string \| undefined;\n if (!text) {\n text = propSchema.description as string \| undefined;\n }\n if (!text) {\n return undefined;\n }\n if (maxLength > 0 && text.length > maxLength) {\n return text.slice(0, maxLength - 3) + \"...\";\n }\n return text;\n}\n\n// ---------------------------------------------------------------------------\n// schemaToCliOptions\n// ---------------------------------------------------------------------------\n\n/* Reserved CLI option names that cannot be used by schema properties. /\nconst RESERVED_NAMES = new Set([\"input\", \"yes\", \"large_input\", \"format\", \"sandbox\"]);\n\n/\n Convert a JSON Schema `properties` object into an array of\n * Commander option configurations.\n /\nexport function schemaToCliOptions(\n schema: Record<string, unknown>,\n maxHelpLength = 1000,\n): OptionConfig[] {\n const properties = (schema.properties ?? {}) as Record<\n string,\n Record<string, unknown>\n >;\n const requiredList = (schema.required ?? []) as string[];\n const options: OptionConfig[] = [];\n const flagNames: Record<string, string> = {};\n\n for (const [propName, propSchema] of Object.entries(properties)) {\n const flagName = \"--\" + propName.replace(/_/g, \"-\");\n\n // Collision detection\n if (flagName in flagNames) {\n process.stderr.write(\n `Error: Flag name collision: properties '${propName}' and '${flagNames[flagName]}' both map to '${flagName}'.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n flagNames[flagName] = propName;\n\n // Reserved name check\n if (RESERVED_NAMES.has(propName)) {\n process.stderr.write(\n `Error: Module schema property '${propName}' conflicts with a reserved CLI option name. Rename the property.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n const typeResult = mapType(propName, propSchema);\n const isRequired = requiredList.includes(propName);\n const helpBase = extractHelp(propSchema, maxHelpLength);\n const helpText = isRequired\n ? (helpBase ? helpBase + \" \" : \"\") + \"[required]\"\n : helpBase ?? \"\";\n const defaultValue = propSchema.default as unknown;\n\n if (typeResult === BOOLEAN_FLAG) {\n // Boolean flag pair: --flag/--no-flag\n const flagBase = propName.replace(/_/g, \"-\");\n const defaultVal = (propSchema.default as boolean) ?? false;\n options.push({\n name: propName,\n flags: `--${flagBase}, --no-${flagBase}`,\n description: helpText,\n defaultValue: defaultVal,\n required: false,\n isBooleanFlag: true,\n });\n } else if (\"enum\" in propSchema && Array.isArray(propSchema.enum)) {\n const enumValues = propSchema.enum as unknown[];\n if (enumValues.length === 0) {\n // Empty enum — fall back to plain string option\n options.push({\n name: propName,\n flags: `${flagName} <value>`,\n description: helpText,\n defaultValue,\n required: false,\n });\n } else {\n const stringValues = enumValues.map(String);\n const enumOriginalTypes: Record<string, string> = {};\n for (const v of enumValues) {\n if (typeof v === \"number\" && Number.isInteger(v)) {\n enumOriginalTypes[String(v)] = \"int\";\n } else if (typeof v === \"number\") {\n enumOriginalTypes[String(v)] = \"float\";\n } else if (typeof v === \"boolean\") {\n enumOriginalTypes[String(v)] = \"bool\";\n }\n }\n options.push({\n name: propName,\n flags: `${flagName} <value>`,\n description: helpText,\n defaultValue:\n defaultValue !== undefined ? String(defaultValue) : undefined,\n required: false,\n choices: stringValues,\n enumOriginalTypes:\n Object.keys(enumOriginalTypes).length > 0\n ? enumOriginalTypes\n : undefined,\n });\n }\n } else {\n // Standard option\n let parseArg: ((value: string) => unknown) \| undefined;\n if (typeResult === \"int\") {\n parseArg = (v: string) => {\n const n = parseInt(v, 10);\n if (isNaN(n)) throw new Error(`Invalid integer: ${v}`);\n return n;\n };\n } else if (typeResult === \"float\") {\n parseArg = (v: string) => {\n const n = parseFloat(v);\n if (isNaN(n)) throw new Error(`Invalid number: ${v}`);\n return n;\n };\n }\n options.push({\n name: propName,\n flags: `${flagName} <value>`,\n description: helpText,\n defaultValue,\n required: false,\n parseArg,\n });\n }\n }\n\n return options;\n}\n","/\n Interactive approval prompts with timeout.\n \n Protocol spec: Approval workflow\n /\n\nimport as readline from \"node:readline\";\nimport type { ModuleDescriptor } from \"./cli.js\";\nimport { ApprovalTimeoutError, EXIT_CODES } from \"./errors.js\";\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/*\n Get an annotation value from either a dict or an object.\n /\nfunction getAnnotation(\n annotations: unknown,\n key: string,\n defaultValue: unknown = undefined,\n): unknown {\n if (!annotations \|\| typeof annotations !== \"object\") return defaultValue;\n const ann = annotations as Record<string, unknown>;\n return key in ann ? ann[key] : defaultValue;\n}\n\n// ---------------------------------------------------------------------------\n// checkApproval\n// ---------------------------------------------------------------------------\n\n/\n Check if module requires approval and handle accordingly.\n * Returns normally if approved (or approval not required).\n * Calls process.exit(46) if denied/timed out/non-TTY.\n /\nexport async function checkApproval(\n moduleDef: ModuleDescriptor,\n autoApprove: boolean,\n): Promise<void> {\n const annotations = moduleDef.annotations;\n\n // Check if approval is required\n let requiresApproval: boolean;\n if (moduleDef.requiresApproval !== undefined) {\n requiresApproval = moduleDef.requiresApproval;\n } else if (annotations) {\n requiresApproval = getAnnotation(annotations, \"requires_approval\", false) === true;\n } else {\n return; // No annotations, no approval needed\n }\n\n if (!requiresApproval) {\n return;\n }\n\n const moduleId = moduleDef.id;\n\n // Bypass: autoApprove flag (highest priority)\n if (autoApprove) {\n return;\n }\n\n // Bypass: APCORE_CLI_AUTO_APPROVE env var\n const envVal = process.env.APCORE_CLI_AUTO_APPROVE ?? \"\";\n if (envVal === \"1\") {\n return;\n }\n if (envVal !== \"\" && envVal !== \"1\") {\n process.stderr.write(\n `Warning: APCORE_CLI_AUTO_APPROVE is set to '${envVal}', expected '1'. Ignoring.\\n`,\n );\n }\n\n // Non-TTY check\n if (!process.stdin.isTTY) {\n process.stderr.write(\n `Error: Module '${moduleId}' requires approval but no interactive ` +\n \"terminal is available. Use --yes or set APCORE_CLI_AUTO_APPROVE=1 \" +\n \"to bypass.\\n\",\n );\n process.exit(EXIT_CODES.APPROVAL_DENIED);\n }\n\n // TTY prompt\n await promptWithTimeout(moduleDef, 60);\n}\n\n/\n Display approval prompt with timeout.\n /\nasync function promptWithTimeout(\n moduleDef: ModuleDescriptor,\n timeout: number,\n): Promise<void> {\n // Clamp timeout\n timeout = Math.max(1, Math.min(timeout, 3600));\n\n const moduleId = moduleDef.id;\n const annotations = moduleDef.annotations;\n const message =\n (annotations\n ? (getAnnotation(annotations, \"approval_message\") as string \| undefined)\n : undefined) ??\n `Module '${moduleId}' requires approval to execute.`;\n\n process.stderr.write(message + \"\\n\");\n\n const rl = readline.createInterface({\n input: process.stdin,\n output: process.stderr,\n });\n\n let timer: ReturnType<typeof setTimeout> \| undefined;\n\n try {\n const answer = await Promise.race([\n new Promise<string>((resolve) => {\n rl.question(\"Proceed? [y/N] \", (ans) => resolve(ans));\n }),\n new Promise<never>((_, reject) => {\n timer = setTimeout(() => {\n reject(new ApprovalTimeoutError(\n `Approval prompt timed out after ${timeout} seconds.`,\n ));\n }, timeout 1000);\n }),\n ]);\n\n // Clear the timeout — prompt resolved before timeout fired\n if (timer) clearTimeout(timer);\n\n const normalized = answer.trim().toLowerCase();\n if (normalized === \"y\" \|\| normalized === \"yes\") {\n return;\n }\n\n process.stderr.write(\"Error: Approval denied.\\n\");\n process.exit(EXIT_CODES.APPROVAL_DENIED);\n } catch (err) {\n if (timer) clearTimeout(timer);\n if (err instanceof ApprovalTimeoutError) {\n process.stderr.write(\n `Error: Approval prompt timed out after ${timeout} seconds.\\n`,\n );\n process.exit(EXIT_CODES.APPROVAL_TIMEOUT);\n }\n throw err;\n } finally {\n rl.close();\n }\n}\n","/*\n TTY-adaptive output formatting (table/json).\n \n Protocol spec: Output formatting\n /\n\nimport type { ModuleDescriptor } from \"./cli.js\";\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/\n Resolve output format with TTY-adaptive default.\n /\nexport function resolveFormat(explicitFormat?: string): string {\n if (explicitFormat !== undefined) {\n return explicitFormat;\n }\n return process.stdout.isTTY ? \"table\" : \"json\";\n}\n\n/\n Truncate text to maxLength, appending '...' if needed.\n /\nexport function truncate(text: string, maxLength = 80): string {\n if (text.length <= maxLength) {\n return text;\n }\n return text.slice(0, maxLength - 3) + \"...\";\n}\n\n/\n Render a simple plain-text table with column headers.\n /\nfunction formatTable(\n headers: string[],\n rows: string[][],\n): string {\n // Calculate column widths\n const colWidths = headers.map((h, i) =>\n Math.max(h.length, ...rows.map((r) => (r[i] ?? \"\").length)),\n );\n\n const sep = colWidths.map((w) => \"-\".repeat(w)).join(\" \");\n const headerLine = headers\n .map((h, i) => h.padEnd(colWidths[i]))\n .join(\" \");\n const dataLines = rows.map((row) =>\n row.map((cell, i) => (cell ?? \"\").padEnd(colWidths[i])).join(\" \"),\n );\n\n return [headerLine, sep, ...dataLines].join(\"\\n\") + \"\\n\";\n}\n\n// ---------------------------------------------------------------------------\n// formatModuleList\n// ---------------------------------------------------------------------------\n\n/\n Format and print a list of modules.\n /\nexport function formatModuleList(\n modules: ModuleDescriptor[],\n format: string,\n filterTags?: string[],\n): void {\n if (format === \"table\") {\n if (modules.length === 0 && filterTags && filterTags.length > 0) {\n process.stdout.write(\n `No modules found matching tags: ${filterTags.join(\", \")}.\\n`,\n );\n return;\n }\n if (modules.length === 0) {\n process.stdout.write(\"No modules found.\\n\");\n return;\n }\n\n const headers = [\"ID\", \"Description\", \"Tags\"];\n const rows = modules.map((m) => [\n m.id,\n truncate(m.description, 80),\n (m.tags ?? []).join(\", \"),\n ]);\n process.stdout.write(formatTable(headers, rows));\n } else if (format === \"json\") {\n const result = modules.map((m) => ({\n id: m.id,\n description: m.description,\n tags: m.tags ?? [],\n }));\n process.stdout.write(JSON.stringify(result, null, 2) + \"\\n\");\n }\n}\n\n// ---------------------------------------------------------------------------\n// formatModuleDetail\n// ---------------------------------------------------------------------------\n\n/\n Convert annotations to a plain dict, filtering out falsy/default values.\n /\nfunction annotationsToDict(\n annotations: unknown,\n): Record<string, unknown> \| null {\n if (!annotations) return null;\n if (typeof annotations !== \"object\" \|\| Array.isArray(annotations)) return null;\n const result: Record<string, unknown> = {};\n for (const [k, v] of Object.entries(annotations as Record<string, unknown>)) {\n if (v !== null && v !== undefined && v !== false && v !== 0 && !(Array.isArray(v) && v.length === 0)) {\n result[k] = v;\n }\n }\n return Object.keys(result).length > 0 ? result : null;\n}\n\n/\n Format and print full module metadata.\n /\nexport function formatModuleDetail(\n moduleDef: ModuleDescriptor,\n format: string,\n): void {\n if (format === \"table\") {\n process.stdout.write(`\\nModule: ${moduleDef.id}\\n`);\n process.stdout.write(`\\nDescription:\\n ${moduleDef.description}\\n`);\n\n if (moduleDef.inputSchema && Object.keys(moduleDef.inputSchema).length > 0) {\n process.stdout.write(\"\\nInput Schema:\\n\");\n process.stdout.write(JSON.stringify(moduleDef.inputSchema, null, 2) + \"\\n\");\n }\n\n if (moduleDef.outputSchema && Object.keys(moduleDef.outputSchema).length > 0) {\n process.stdout.write(\"\\nOutput Schema:\\n\");\n process.stdout.write(JSON.stringify(moduleDef.outputSchema, null, 2) + \"\\n\");\n }\n\n const annDict = annotationsToDict(\n moduleDef.annotations,\n );\n if (annDict) {\n process.stdout.write(\"\\nAnnotations:\\n\");\n for (const [k, v] of Object.entries(annDict)) {\n process.stdout.write(` ${k}: ${v}\\n`);\n }\n }\n\n // Extension metadata (x- prefixed)\n const metadata = moduleDef.metadata;\n if (metadata) {\n const xFields: Record<string, unknown> = {};\n for (const [k, v] of Object.entries(metadata)) {\n if (k.startsWith(\"x-\") \|\| k.startsWith(\"x_\")) {\n xFields[k] = v;\n }\n }\n if (Object.keys(xFields).length > 0) {\n process.stdout.write(\"\\nExtension Metadata:\\n\");\n for (const [k, v] of Object.entries(xFields)) {\n process.stdout.write(` ${k}: ${v}\\n`);\n }\n }\n }\n\n const tags = moduleDef.tags ?? [];\n if (tags.length > 0) {\n process.stdout.write(`\\nTags: ${tags.join(\", \")}\\n`);\n }\n } else if (format === \"json\") {\n const result: Record<string, unknown> = {\n id: moduleDef.id,\n description: moduleDef.description,\n };\n if (moduleDef.inputSchema) result.input_schema = moduleDef.inputSchema;\n if (moduleDef.outputSchema) result.output_schema = moduleDef.outputSchema;\n\n const annDict = annotationsToDict(\n moduleDef.annotations,\n );\n if (annDict) result.annotations = annDict;\n\n const tags = moduleDef.tags ?? [];\n if (tags.length > 0) result.tags = tags;\n\n // Extension metadata\n const metadata = moduleDef.metadata;\n if (metadata) {\n for (const [k, v] of Object.entries(metadata)) {\n if (k.startsWith(\"x-\") \|\| k.startsWith(\"x_\")) {\n result[k] = v;\n }\n }\n }\n\n process.stdout.write(JSON.stringify(result, null, 2) + \"\\n\");\n }\n}\n\n// ---------------------------------------------------------------------------\n// formatExecResult\n// ---------------------------------------------------------------------------\n\n/\n Format and print module execution result.\n /\nexport function formatExecResult(\n result: unknown,\n format?: string,\n): void {\n if (result === null \|\| result === undefined) {\n return;\n }\n const effective = resolveFormat(format);\n if (\n effective === \"table\" &&\n typeof result === \"object\" &&\n !Array.isArray(result)\n ) {\n // Key-value table\n const entries = Object.entries(result as Record<string, unknown>);\n const headers = [\"Key\", \"Value\"];\n const rows = entries.map(([k, v]) => [String(k), String(v)]);\n process.stdout.write(formatTable(headers, rows));\n } else if (typeof result === \"object\") {\n process.stdout.write(JSON.stringify(result, null, 2) + \"\\n\");\n } else if (typeof result === \"string\") {\n process.stdout.write(result + \"\\n\");\n } else {\n process.stdout.write(String(result) + \"\\n\");\n }\n}\n","/\n Simple structured logger respecting logging.level config.\n /\n\nconst LEVELS = { DEBUG: 0, INFO: 1, WARNING: 2, ERROR: 3 } as const;\ntype LogLevel = keyof typeof LEVELS;\n\nlet currentLevel: LogLevel = \"WARNING\";\n\nexport function setLogLevel(level: string): void {\n const upper = level.toUpperCase();\n if (upper in LEVELS) {\n currentLevel = upper as LogLevel;\n }\n}\n\nexport function getLogLevel(): LogLevel {\n return currentLevel;\n}\n\nfunction shouldLog(level: LogLevel): boolean {\n return LEVELS[level] >= LEVELS[currentLevel];\n}\n\nexport function debug(message: string): void {\n if (shouldLog(\"DEBUG\")) process.stderr.write(`DEBUG: ${message}\\n`);\n}\n\nexport function info(message: string): void {\n if (shouldLog(\"INFO\")) process.stderr.write(`INFO: ${message}\\n`);\n}\n\nexport function warn(message: string): void {\n if (shouldLog(\"WARNING\")) process.stderr.write(`WARNING: ${message}\\n`);\n}\n\nexport function error(message: string): void {\n if (shouldLog(\"ERROR\")) process.stderr.write(`ERROR: ${message}\\n`);\n}\n","/\n Init command — scaffold new apcore modules (Phase 1).\n /\n\nimport { Command } from \"commander\";\nimport as fs from \"node:fs\";\nimport * as path from \"node:path\";\n\nconst DECORATOR_TEMPLATE = `\\\nimport { module } from \"apcore-js\";\nimport { Type } from \"@sinclair/typebox\";\n\nexport const {varName} = module({\n id: \"{moduleId}\",\n description: \"{description}\",\n inputSchema: Type.Object({}),\n outputSchema: Type.Object({ status: Type.String() }),\n execute: (_inputs) => {\n // TODO: implement\n return { status: \"ok\" };\n },\n});\n`;\n\nconst CONVENTION_TEMPLATE = `\\\n/*\n {description}\n /\n{cliGroupLine}\nexport function {funcName}(): Record<string, unknown> {\n // TODO: implement\n return { status: \"ok\" };\n}\n`;\n\nconst BINDING_TEMPLATE = `\\\nbindings:\n - module_id: \"{moduleId}\"\n target: \"{target}\"\n description: \"{description}\"\n auto_schema: true\n`;\n\n/\n Simple template rendering: replaces {key} with values from the context.\n /\nfunction renderTemplate(template: string, context: Record<string, string>): string {\n let result = template;\n for (const [key, value] of Object.entries(context)) {\n // Replace all occurrences of {key} with the value\n result = result.split(`{${key}}`).join(value);\n }\n return result;\n}\n\n/\n Register the init command group on the CLI program.\n /\nexport function registerInitCommand(cli: Command): void {\n const initGroup = cli.command(\"init\").description(\"Scaffold new apcore modules.\");\n\n initGroup\n .command(\"module <module-id>\")\n .description(\"Create a new module from a template.\\n\\nMODULE_ID is the module identifier (e.g., ops.deploy, user.create).\")\n .option(\n \"--style <style>\",\n \"Module style: decorator (@module), convention (plain function), or binding (YAML).\",\n \"convention\",\n )\n .option(\"--dir <path>\", \"Output directory. Default: extensions/ or commands/.\")\n .option(\"-d, --description <text>\", \"Module description.\", \"TODO: add description\")\n .action((moduleId: string, opts: { style: string; dir?: string; description: string }) => {\n // Parse module_id into parts\n const lastDot = moduleId.lastIndexOf(\".\");\n const prefix = lastDot >= 0 ? moduleId.substring(0, lastDot) : moduleId;\n const funcName = lastDot >= 0 ? moduleId.substring(lastDot + 1) : moduleId;\n\n const style = opts.style;\n const description = opts.description;\n\n // Validate --dir to prevent path traversal\n const dir = opts.dir ?? (style === \"decorator\" ? \"extensions\" : style === \"binding\" ? \"bindings\" : \"commands\");\n if (dir.split(path.sep).includes(\"..\") \|\| dir.split(\"/\").includes(\"..\")) {\n process.stderr.write(`Error: Output directory must not contain '..' path components.\\n`);\n process.exit(2);\n }\n\n switch (style) {\n case \"decorator\":\n createDecoratorModule(moduleId, prefix, funcName, description, dir);\n break;\n case \"convention\":\n createConventionModule(moduleId, prefix, funcName, description, dir);\n break;\n case \"binding\":\n createBindingModule(moduleId, prefix, funcName, description, dir);\n break;\n default:\n process.stderr.write(`Error: Unknown style '${style}'\\n`);\n process.exit(2);\n }\n });\n}\n\nfunction createDecoratorModule(\n moduleId: string,\n _prefix: string,\n funcName: string,\n description: string,\n outputDir: string,\n): void {\n fs.mkdirSync(outputDir, { recursive: true });\n const filename = moduleId.replace(/\\./g, \"_\") + \".ts\";\n const filepath = path.join(outputDir, filename);\n\n const varName = funcName + \"Module\";\n const content = renderTemplate(DECORATOR_TEMPLATE, {\n moduleId,\n varName,\n funcName,\n description,\n });\n fs.writeFileSync(filepath, content);\n process.stdout.write(`Created ${filepath}\\n`);\n}\n\nfunction createConventionModule(\n moduleId: string,\n prefix: string,\n funcName: string,\n description: string,\n outputDir: string,\n): void {\n // If prefix has dots, create subdirectories\n const prefixParts = prefix.split(\".\");\n const dirPath = prefixParts.length > 1\n ? path.join(outputDir, ...prefixParts.slice(0, -1))\n : outputDir;\n fs.mkdirSync(dirPath, { recursive: true });\n\n let filename: string;\n if (prefixParts.length > 1) {\n filename = prefixParts[prefixParts.length - 1] + \".ts\";\n } else {\n filename = prefix + \".ts\";\n }\n // If the file would be the same as the function name, use prefix as filename\n if (prefix === funcName) {\n filename = prefix + \".ts\";\n }\n const filepath = path.join(dirPath, filename);\n\n const cliGroupLine = moduleId.includes(\".\")\n ? `export const CLI_GROUP = \"${prefixParts[0]}\";\\n`\n : \"\";\n\n const content = renderTemplate(CONVENTION_TEMPLATE, {\n funcName,\n description,\n cliGroupLine,\n });\n fs.writeFileSync(filepath, content);\n process.stdout.write(`Created ${filepath}\\n`);\n}\n\nfunction createBindingModule(\n moduleId: string,\n prefix: string,\n funcName: string,\n description: string,\n outputDir: string,\n): void {\n fs.mkdirSync(outputDir, { recursive: true });\n\n const yamlFile = path.join(outputDir, moduleId.replace(/\\./g, \"_\") + \".binding.yaml\");\n const target = `commands.${prefix}:${funcName}`;\n\n const yamlContent = renderTemplate(BINDING_TEMPLATE, {\n moduleId,\n target,\n description,\n });\n fs.writeFileSync(yamlFile, yamlContent);\n process.stdout.write(`Created ${yamlFile}\\n`);\n\n // Also create the target function file\n const baseSrc = \"commands\";\n fs.mkdirSync(baseSrc, { recursive: true });\n const srcFile = path.join(baseSrc, prefix.replace(/\\./g, \"_\") + \".ts\");\n if (!fs.existsSync(srcFile)) {\n const srcContent =\n `export function ${funcName}(): Record<string, unknown> {\\n` +\n ` /* ${description} /\\n` +\n \" // TODO: implement\\n\" +\n ' return { status: \"ok\" };\\n' +\n \"}\\n\";\n fs.writeFileSync(srcFile, srcContent);\n process.stdout.write(`Created ${srcFile}\\n`);\n }\n}\n","/\n Display overlay helpers — shared resolution logic for CLI surfaces.\n /\n\nimport type { ModuleDescriptor } from \"./cli.js\";\n\n/\n Extract resolved display overlay from a ModuleDescriptor's metadata.\n /\nexport function getDisplay(descriptor: ModuleDescriptor): Record<string, unknown> {\n const metadata = descriptor.metadata ?? {};\n const display = (metadata as Record<string, unknown>).display;\n if (display && typeof display === \"object\" && !Array.isArray(display)) {\n return display as Record<string, unknown>;\n }\n return {};\n}\n\n/\n Return [displayName, description, tags] resolved from the display overlay.\n \n Falls back to scanner-provided values when no overlay is present.\n /\nexport function getCliDisplayFields(descriptor: ModuleDescriptor): [string, string, string[]] {\n const display = getDisplay(descriptor);\n const cli = (display.cli && typeof display.cli === \"object\" && !Array.isArray(display.cli))\n ? (display.cli as Record<string, unknown>)\n : {};\n const name = (cli.alias as string \| undefined)\n ?? (display.alias as string \| undefined)\n ?? descriptor.id;\n const desc = (cli.description as string \| undefined) ?? descriptor.description;\n const tags = (display.tags as string[] \| undefined) ?? descriptor.tags ?? [];\n return [name, desc, tags];\n}\n","/\n ConfigResolver — 4-tier config resolution (CLI flag > env > file > default).\n \n Protocol spec: Configuration resolution\n /\n\nimport as fs from \"node:fs\";\nimport yaml from \"js-yaml\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Default configuration values. /\nexport const DEFAULTS: Record<string, unknown> = {\n \"extensions.root\": \"./extensions\",\n \"logging.level\": \"WARNING\",\n \"sandbox.enabled\": false,\n \"cli.stdin_buffer_limit\": 10_485_760,\n \"cli.auto_approve\": false,\n \"cli.help_text_max_length\": 1000,\n // Namespace-mode aliases (apcore >= 0.15.0 Config Bus)\n \"apcore-cli.stdin_buffer_limit\": 10_485_760,\n \"apcore-cli.auto_approve\": false,\n \"apcore-cli.help_text_max_length\": 1000,\n \"apcore-cli.logging_level\": \"WARNING\",\n};\n\n/* Namespace key ↔ legacy key mapping for backward compatibility. /\nconst NAMESPACE_TO_LEGACY: Record<string, string> = {\n \"apcore-cli.stdin_buffer_limit\": \"cli.stdin_buffer_limit\",\n \"apcore-cli.auto_approve\": \"cli.auto_approve\",\n \"apcore-cli.help_text_max_length\": \"cli.help_text_max_length\",\n \"apcore-cli.logging_level\": \"logging.level\",\n};\nconst LEGACY_TO_NAMESPACE: Record<string, string> = Object.fromEntries(\n Object.entries(NAMESPACE_TO_LEGACY).map(([k, v]) => [v, k]),\n);\n\n/\n Register the apcore-cli Config Bus namespace (apcore >= 0.15.0).\n * Safe to call even when apcore-js is unavailable or < 0.15.0.\n /\nexport function registerConfigNamespace(): void {\n try {\n // Dynamic import to avoid hard failure when apcore-js is not available\n // eslint-disable-next-line @typescript-eslint/no-require-imports\n const { Config } = require(\"apcore-js\");\n if (typeof Config?.registerNamespace === \"function\") {\n Config.registerNamespace({\n name: \"apcore-cli\",\n envPrefix: \"APCORE_CLI\",\n defaults: {\n stdin_buffer_limit: 10_485_760,\n auto_approve: false,\n help_text_max_length: 1000,\n logging_level: \"WARNING\",\n },\n });\n }\n } catch {\n // apcore-js not installed or < 0.15.0 — graceful no-op\n }\n}\n\n// ---------------------------------------------------------------------------\n// ConfigResolver\n// ---------------------------------------------------------------------------\n\n/\n Resolves configuration from four tiers (highest to lowest priority):\n * 1. CLI flags\n * 2. Environment variables\n * 3. Config file (YAML/JSON)\n * 4. Built-in defaults\n /\nexport class ConfigResolver {\n private readonly cliFlags: Record<string, unknown>;\n private readonly configPath: string;\n private fileCache: Record<string, unknown> \| null = null;\n private fileCacheLoaded = false;\n\n constructor(cliFlags?: Record<string, unknown>, configPath?: string) {\n this.cliFlags = cliFlags ?? {};\n this.configPath = configPath ?? \"apcore.yaml\";\n }\n\n /\n Resolve a single configuration key across all four tiers.\n /\n resolve(key: string, cliFlag?: string, envVar?: string): unknown {\n // Tier 1: CLI flag\n const flagKey = cliFlag ?? key;\n if (flagKey in this.cliFlags) {\n const value = this.cliFlags[flagKey];\n if (value !== null && value !== undefined) {\n return value;\n }\n }\n\n // Tier 2: Environment variable\n if (envVar) {\n const envValue = process.env[envVar];\n if (envValue !== undefined && envValue !== \"\") {\n return envValue;\n }\n }\n\n // Tier 3: Config file (try both namespace and legacy keys)\n const fileValue = this.resolveFromFile(key);\n if (fileValue !== undefined) {\n return fileValue;\n }\n const altKey = NAMESPACE_TO_LEGACY[key] ?? LEGACY_TO_NAMESPACE[key];\n if (altKey) {\n const altFileValue = this.resolveFromFile(altKey);\n if (altFileValue !== undefined) {\n return altFileValue;\n }\n }\n\n // Tier 4: Defaults\n return DEFAULTS[key];\n }\n\n /\n Load a value from the config file using a dot-separated key path.\n /\n private resolveFromFile(key: string): unknown {\n if (!this.fileCacheLoaded) {\n this.fileCache = this.loadConfigFile();\n this.fileCacheLoaded = true;\n }\n if (this.fileCache === null) {\n return undefined;\n }\n return this.fileCache[key];\n }\n\n /\n Load and flatten a YAML config file.\n /\n private loadConfigFile(): Record<string, unknown> \| null {\n let content: string;\n try {\n content = fs.readFileSync(this.configPath, \"utf-8\");\n } catch (err: unknown) {\n if (err instanceof Error && \"code\" in err && err.code === \"ENOENT\") {\n return null;\n }\n console.warn(\n `Configuration file '${this.configPath}' is malformed, using defaults.`,\n );\n return null;\n }\n\n let parsed: unknown;\n try {\n parsed = yaml.load(content);\n } catch {\n console.warn(\n `Configuration file '${this.configPath}' is malformed, using defaults.`,\n );\n return null;\n }\n\n if (typeof parsed !== \"object\" \|\| parsed === null \|\| Array.isArray(parsed)) {\n console.warn(\n `Configuration file '${this.configPath}' is malformed, using defaults.`,\n );\n return null;\n }\n\n return this.flattenDict(parsed as Record<string, unknown>);\n }\n\n /\n Flatten nested dict to dot-notation keys.\n /\n private flattenDict(\n d: Record<string, unknown>,\n prefix = \"\",\n ): Record<string, unknown> {\n const result: Record<string, unknown> = {};\n for (const [key, value] of Object.entries(d)) {\n const fullKey = prefix ? `${prefix}.${key}` : key;\n if (\n typeof value === \"object\" &&\n value !== null &&\n !Array.isArray(value)\n ) {\n Object.assign(\n result,\n this.flattenDict(value as Record<string, unknown>, fullKey),\n );\n } else {\n result[fullKey] = value;\n }\n }\n return result;\n }\n}\n","/\n Shell completion + man page generation.\n \n Protocol spec: Shell integration\n /\n\nimport { readFileSync } from \"node:fs\";\nimport { fileURLToPath } from \"node:url\";\nimport as path from \"node:path\";\nimport { spawnSync } from \"node:child_process\";\nimport { Command, Help, Option } from \"commander\";\nimport { EXIT_CODES } from \"./errors.js\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\nlet SHELL_VERSION = \"0.0.0\";\ntry {\n const pkg = JSON.parse(readFileSync(path.resolve(__dirname, \"../package.json\"), \"utf-8\"));\n SHELL_VERSION = pkg.version;\n} catch {\n // Bundled environments (e.g., Bun compile) may not have package.json accessible\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/*\n Convert a prog_name like 'my-tool' to a valid shell identifier '_my_tool'.\n /\nfunction makeFunctionName(progName: string): string {\n return \"_\" + progName.replace(/[^a-zA-Z0-9]/g, \"_\");\n}\n\n/\n Shell-safe quoting.\n /\nfunction shellQuote(s: string): string {\n return \"'\" + s.replace(/'/g, \"'\\\\''\") + \"'\";\n}\n\n// ---------------------------------------------------------------------------\n// Completion generators\n// ---------------------------------------------------------------------------\n\nfunction generateBashCompletion(progName: string): string {\n const fn = makeFunctionName(progName);\n const quoted = shellQuote(progName);\n const moduleListCmd =\n `${quoted} list --format json 2>/dev/null` +\n ` \| node -e \"process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})\" 2>/dev/null`;\n const groupsAndTopCmd =\n `${quoted} list --format json 2>/dev/null \| node -e \"\\n` +\n `const m=require('fs').readFileSync('/dev/stdin','utf8');\\n` +\n `const ids=JSON.parse(m).map(x=>x.id);\\n` +\n `const g=new Set(),t=[];\\n` +\n `ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});\\n` +\n `console.log([...g].sort().concat(t.sort()).join(' '))\\n` +\n `\" 2>/dev/null`;\n const groupCmdsCmd =\n `${quoted} list --format json 2>/dev/null \| node -e \"\\n` +\n `const m=require('fs').readFileSync('/dev/stdin','utf8');\\n` +\n `const g=process.env._APCORE_GRP;\\n` +\n `JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))\\n` +\n `\" 2>/dev/null`;\n\n return (\n `${fn}() {\\n` +\n ` local cur prev opts\\n` +\n ` COMPREPLY=()\\n` +\n ` cur=\"\\${COMP_WORDS[COMP_CWORD]}\"\\n` +\n ` prev=\"\\${COMP_WORDS[COMP_CWORD-1]}\"\\n` +\n `\\n` +\n ` if [[ \\${COMP_CWORD} -eq 1 ]]; then\\n` +\n ` opts=\"completion describe exec init list man\"\\n` +\n ` local groups_and_top=$(${groupsAndTopCmd})\\n` +\n ` COMPREPLY=( $(compgen -W \"\\${opts} \\${groups_and_top}\" -- \\${cur}) )\\n` +\n ` return 0\\n` +\n ` fi\\n` +\n `\\n` +\n ` if [[ \\${COMP_CWORD} -eq 2 ]]; then\\n` +\n ` if [[ \"\\${COMP_WORDS[1]}\" == \"exec\" ]]; then\\n` +\n ` local modules=$(${moduleListCmd})\\n` +\n ` COMPREPLY=( $(compgen -W \"\\${modules}\" -- \\${cur}) )\\n` +\n ` return 0\\n` +\n ` fi\\n` +\n ` export _APCORE_GRP=\"\\${COMP_WORDS[1]}\"\\n` +\n ` local group_cmds=$(${groupCmdsCmd})\\n` +\n ` COMPREPLY=( $(compgen -W \"\\${group_cmds}\" -- \\${cur}) )\\n` +\n ` return 0\\n` +\n ` fi\\n` +\n `}\\n` +\n `complete -F ${fn} ${quoted}\\n`\n );\n}\n\nfunction generateZshCompletion(progName: string): string {\n const fn = makeFunctionName(progName);\n const quoted = shellQuote(progName);\n const moduleListCmd =\n `${quoted} list --format json 2>/dev/null` +\n ` \| node -e \"process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})\" 2>/dev/null`;\n const groupsAndTopCmd =\n `${quoted} list --format json 2>/dev/null \| node -e \"\\n` +\n `const m=require('fs').readFileSync('/dev/stdin','utf8');\\n` +\n `const ids=JSON.parse(m).map(x=>x.id);\\n` +\n `const g=new Set(),t=[];\\n` +\n `ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});\\n` +\n `console.log([...g].sort().concat(t.sort()).join(' '))\\n` +\n `\" 2>/dev/null`;\n const groupCmdsCmd =\n `${quoted} list --format json 2>/dev/null \| node -e \"\\n` +\n `const m=require('fs').readFileSync('/dev/stdin','utf8');\\n` +\n `const g=process.env._APCORE_GRP;\\n` +\n `JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))\\n` +\n `\" 2>/dev/null`;\n\n return (\n `#compdef ${progName}\\n` +\n `\\n` +\n `${fn}() {\\n` +\n ` local -a commands\\n` +\n ` commands=(\\n` +\n ` 'list:List available modules'\\n` +\n ` 'describe:Show module metadata and schema'\\n` +\n ` 'completion:Generate shell completion script'\\n` +\n ` 'init:Scaffolding commands'\\n` +\n ` 'man:Generate man page'\\n` +\n ` )\\n` +\n `\\n` +\n ` _arguments -C \\\\\\n` +\n ` '1:command:->command' \\\\\\n` +\n ` '::arg:->args'\\n` +\n `\\n` +\n ` case \"$state\" in\\n` +\n ` command)\\n` +\n ` _describe -t commands '${progName} commands' commands\\n` +\n ` local -a groups_and_top\\n` +\n ` groups_and_top=($(${groupsAndTopCmd}))\\n` +\n ` compadd -a groups_and_top\\n` +\n ` ;;\\n` +\n ` args)\\n` +\n ` case \"\\${words[1]}\" in\\n` +\n ` exec)\\n` +\n ` local modules\\n` +\n ` modules=($(${moduleListCmd}))\\n` +\n ` compadd -a modules\\n` +\n ` ;;\\n` +\n ` )\\n` +\n ` export _APCORE_GRP=\"\\${words[1]}\"\\n` +\n ` local -a group_cmds\\n` +\n ` group_cmds=($(${groupCmdsCmd}))\\n` +\n ` compadd -a group_cmds\\n` +\n ` ;;\\n` +\n ` esac\\n` +\n ` ;;\\n` +\n ` esac\\n` +\n `}\\n` +\n `\\n` +\n `compdef ${fn} ${quoted}\\n`\n );\n}\n\nfunction generateFishCompletion(progName: string): string {\n const quoted = shellQuote(progName);\n const moduleListCmd =\n `${quoted} list --format json 2>/dev/null` +\n ` \| node -e \\\\\"process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})\\\\\" 2>/dev/null`;\n const groupsAndTopCmd =\n `${quoted} list --format json 2>/dev/null \| node -e \\\\\"` +\n `const m=require('fs').readFileSync('/dev/stdin','utf8');` +\n `const ids=JSON.parse(m).map(x=>x.id);` +\n `const g=new Set(),t=[];` +\n `ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});` +\n `console.log([...g].sort().concat(t.sort()).join('\\\\\\\\n'))\\\\\" 2>/dev/null`;\n\n return (\n `# Fish completions for ${progName}\\n` +\n `complete -c ${quoted} -n \"__fish_use_subcommand\"` +\n ` -a list -d \"List available modules\"\\n` +\n `complete -c ${quoted} -n \"__fish_use_subcommand\"` +\n ` -a describe -d \"Show module metadata and schema\"\\n` +\n `complete -c ${quoted} -n \"__fish_use_subcommand\"` +\n ` -a completion -d \"Generate shell completion script\"\\n` +\n `complete -c ${quoted} -n \"__fish_use_subcommand\"` +\n ` -a init -d \"Scaffolding commands\"\\n` +\n `complete -c ${quoted} -n \"__fish_use_subcommand\"` +\n ` -a man -d \"Generate man page\"\\n` +\n `complete -c ${quoted} -n \"__fish_use_subcommand\"` +\n ` -a \"(${groupsAndTopCmd})\" -d \"Module group\"\\n` +\n `\\n` +\n `complete -c ${quoted} -n \"__fish_seen_subcommand_from exec\"` +\n ` -a \"(${moduleListCmd})\"\\n` +\n `\\n` +\n `function __apcore_group_cmds\\n` +\n ` set -l grp (commandline -opc)[2]\\n` +\n ` set -x _APCORE_GRP $grp\\n` +\n ` ${quoted} list --format json 2>/dev/null \| node -e \"\\n` +\n `const m=require('fs').readFileSync('/dev/stdin','utf8');\\n` +\n `const g=process.env._APCORE_GRP;\\n` +\n `JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))\\n` +\n `\" 2>/dev/null\\n` +\n `end\\n` +\n `\\n` +\n `# Group subcommand completion — matches when position 1 is not a builtin\\n` +\n `complete -c ${quoted} -n \"not __fish_use_subcommand; and not __fish_seen_subcommand_from list describe completion init man exec\"` +\n ` -a \"(__apcore_group_cmds)\"\\n`\n );\n}\n\n// ---------------------------------------------------------------------------\n// Man page generation\n// ---------------------------------------------------------------------------\n\nfunction buildSynopsis(\n command: Command \| null,\n progName: string,\n commandName: string,\n): string {\n if (!command) {\n return `\\\\fB${progName} ${commandName}\\\\fR [OPTIONS]`;\n }\n\n const parts = [`\\\\fB${progName} ${commandName}\\\\fR`];\n for (const opt of command.options) {\n const flag = opt.long ?? opt.short ?? \"\";\n if (opt.isBoolean?.()) {\n parts.push(`[${flag}]`);\n } else if (opt.required) {\n const typeName = (opt.argChoices ? \"CHOICE\" : \"VALUE\").toUpperCase();\n parts.push(`${flag} \\\\fI${typeName}\\\\fR`);\n } else {\n const typeName = (opt.argChoices ? \"CHOICE\" : \"VALUE\").toUpperCase();\n parts.push(`[${flag} \\\\fI${typeName}\\\\fR]`);\n }\n }\n\n for (const arg of command.registeredArguments ?? []) {\n const meta = arg.name().toUpperCase();\n if (arg.required) {\n parts.push(`\\\\fI${meta}\\\\fR`);\n } else {\n parts.push(`[\\\\fI${meta}\\\\fR]`);\n }\n }\n\n return parts.join(\" \");\n}\n\nfunction generateManPage(\n commandName: string,\n command: Command \| null,\n progName: string,\n version = SHELL_VERSION,\n): string {\n const today = new Date().toISOString().slice(0, 10);\n const title = `${progName}-${commandName}`.toUpperCase();\n const pkgLabel = `${progName} ${version}`;\n const manualLabel = `${progName} Manual`;\n\n const sections: string[] = [];\n sections.push(`.TH \"${title}\" \"1\" \"${today}\" \"${pkgLabel}\" \"${manualLabel}\"`);\n\n sections.push(\".SH NAME\");\n const desc = command?.description() ?? commandName;\n const nameDesc = desc.split(\"\\n\")[0].replace(/\\.$/, \"\");\n sections.push(`${progName}-${commandName} \\\\- ${nameDesc}`);\n\n sections.push(\".SH SYNOPSIS\");\n sections.push(buildSynopsis(command, progName, commandName));\n\n if (command?.description()) {\n sections.push(\".SH DESCRIPTION\");\n sections.push(\n command.description().replace(/\\\\/g, \"\\\\\\\\\").replace(/-/g, \"\\\\-\"),\n );\n }\n\n if (command && command.options.length > 0) {\n sections.push(\".SH OPTIONS\");\n for (const opt of command.options) {\n const flag = [opt.short, opt.long].filter(Boolean).join(\", \");\n sections.push(\".TP\");\n if (opt.isBoolean?.()) {\n sections.push(`\\\\fB${flag}\\\\fR`);\n } else {\n sections.push(`\\\\fB${flag}\\\\fR \\\\fIVALUE\\\\fR`);\n }\n if (opt.description) {\n sections.push(opt.description);\n }\n if (opt.defaultValue !== undefined && !opt.isBoolean?.()) {\n sections.push(`Default: ${opt.defaultValue}.`);\n }\n }\n }\n\n sections.push(\".SH ENVIRONMENT\");\n sections.push(\".TP\");\n sections.push(\"\\\\fBAPCORE_EXTENSIONS_ROOT\\\\fR\");\n sections.push(\n \"Path to the apcore extensions directory. Overrides the default \\\\fI./extensions\\\\fR.\",\n );\n sections.push(\".TP\");\n sections.push(\"\\\\fBAPCORE_CLI_AUTO_APPROVE\\\\fR\");\n sections.push(\n \"Set to \\\\fB1\\\\fR to bypass approval prompts for modules that require human-in-the-loop confirmation.\",\n );\n sections.push(\".TP\");\n sections.push(\"\\\\fBAPCORE_CLI_LOGGING_LEVEL\\\\fR\");\n sections.push(\n \"CLI-specific logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. \" +\n \"Takes priority over \\\\fBAPCORE_LOGGING_LEVEL\\\\fR. Default: WARNING.\",\n );\n sections.push(\".TP\");\n sections.push(\"\\\\fBAPCORE_LOGGING_LEVEL\\\\fR\");\n sections.push(\n \"Global apcore logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. \" +\n \"Used as fallback when \\\\fBAPCORE_CLI_LOGGING_LEVEL\\\\fR is not set. Default: WARNING.\",\n );\n sections.push(\".TP\");\n sections.push(\"\\\\fBAPCORE_AUTH_API_KEY\\\\fR\");\n sections.push(\n \"API key for authenticating with the apcore registry.\",\n );\n\n sections.push(\".SH EXIT CODES\");\n const exitCodes: [string, string][] = [\n [\"0\", \"Success.\"],\n [\"1\", \"Module execution error.\"],\n [\"2\", \"Invalid CLI input or missing argument.\"],\n [\"44\", \"Module not found, disabled, or failed to load.\"],\n [\"45\", \"Input failed JSON Schema validation.\"],\n [\n \"46\",\n \"Approval denied, timed out, or no interactive terminal available.\",\n ],\n [\n \"47\",\n \"Configuration error (extensions directory not found or unreadable).\",\n ],\n [\"48\", \"Schema contains a circular \\\\fB$ref\\\\fR.\"],\n [\"77\", \"ACL denied — insufficient permissions for this module.\"],\n [\"130\", \"Execution cancelled by user (SIGINT / Ctrl\\\\-C).\"],\n ];\n for (const [code, meaning] of exitCodes) {\n sections.push(`.TP\\n\\\\fB${code}\\\\fR\\n${meaning}`);\n }\n\n sections.push(\".SH SEE ALSO\");\n sections.push(\n [\n `\\\\fB${progName}\\\\fR(1)`,\n `\\\\fB${progName}\\\\-list\\\\fR(1)`,\n `\\\\fB${progName}\\\\-describe\\\\fR(1)`,\n `\\\\fB${progName}\\\\-completion\\\\fR(1)`,\n ].join(\", \"),\n );\n\n return sections.join(\"\\n\");\n}\n\n// ---------------------------------------------------------------------------\n// Program-wide man page generation\n// ---------------------------------------------------------------------------\n\n/* Escape a string for roff output. /\nfunction roffEscape(s: string): string {\n return s.replace(/\\\\/g, \"\\\\\\\\\").replace(/-/g, \"\\\\-\").replace(/'/g, \"\\\\(aq\");\n}\n\n/\n Build a complete roff man page for the entire program.\n * Covers all registered commands including downstream business commands.\n /\nexport function buildProgramManPage(\n program: Command,\n progName: string,\n version: string,\n description?: string,\n docsUrl?: string,\n): string {\n const help = new Help();\n const today = new Date().toISOString().slice(0, 10);\n const s: string[] = [];\n\n const resolvedDesc = description ?? program.description() ?? `${progName} CLI`;\n\n s.push(`.TH \"${progName.toUpperCase()}\" \"1\" \"${today}\" \"${progName} ${version}\" \"${progName} Manual\"`);\n\n s.push(\".SH NAME\");\n s.push(`${progName} \\\\- ${roffEscape(resolvedDesc)}`);\n\n s.push(\".SH SYNOPSIS\");\n s.push(`\\\\fB${progName}\\\\fR [\\\\fIglobal\\\\-options\\\\fR] \\\\fIcommand\\\\fR [\\\\fIcommand\\\\-options\\\\fR]`);\n\n if (resolvedDesc) {\n s.push(\".SH DESCRIPTION\");\n s.push(roffEscape(resolvedDesc));\n }\n\n // Global options\n const globalOpts = help.visibleOptions(program)\n .filter((o) => ![\"help\", \"version\", \"all\", \"man\"].includes(o.long?.replace(\"--\", \"\") ?? \"\"));\n if (globalOpts.length > 0) {\n s.push(\".SH GLOBAL OPTIONS\");\n for (const opt of globalOpts) {\n const flag = [opt.short, opt.long].filter(Boolean).join(\", \");\n s.push(\".TP\");\n s.push(`\\\\fB${roffEscape(flag)}\\\\fR`);\n if (opt.description) s.push(roffEscape(opt.description));\n }\n }\n\n // Commands\n const allCommands = help.visibleCommands(program);\n if (allCommands.length > 0) {\n s.push(\".SH COMMANDS\");\n for (const cmd of allCommands) {\n if (cmd.name() === \"help\") continue;\n\n const desc = help.subcommandDescription(cmd);\n s.push(\".TP\");\n s.push(`\\\\fB${progName} ${roffEscape(cmd.name())}\\\\fR`);\n if (desc) s.push(roffEscape(desc));\n\n // Command options\n const cmdHelp = new Help();\n const opts = cmdHelp.visibleOptions(cmd)\n .filter((o) => ![\"help\", \"version\"].includes(o.long?.replace(\"--\", \"\") ?? \"\"));\n for (const opt of opts) {\n const flag = [opt.short, opt.long].filter(Boolean).join(\", \");\n s.push(\".RS\");\n s.push(\".TP\");\n s.push(`\\\\fB${roffEscape(flag)}\\\\fR`);\n if (opt.description) s.push(roffEscape(opt.description));\n s.push(\".RE\");\n }\n\n // Nested subcommands (e.g., series init, asset add)\n const subCmds = cmdHelp.visibleCommands(cmd).filter((c) => c.name() !== \"help\");\n for (const sub of subCmds) {\n const subDesc = help.subcommandDescription(sub);\n s.push(\".TP\");\n s.push(`\\\\fB${progName} ${roffEscape(cmd.name())} ${roffEscape(sub.name())}\\\\fR`);\n if (subDesc) s.push(roffEscape(subDesc));\n const subOpts = cmdHelp.visibleOptions(sub)\n .filter((o) => ![\"help\", \"version\"].includes(o.long?.replace(\"--\", \"\") ?? \"\"));\n for (const opt of subOpts) {\n const flag = [opt.short, opt.long].filter(Boolean).join(\", \");\n s.push(\".RS\");\n s.push(\".TP\");\n s.push(`\\\\fB${roffEscape(flag)}\\\\fR`);\n if (opt.description) s.push(roffEscape(opt.description));\n s.push(\".RE\");\n }\n }\n }\n }\n\n // Environment\n s.push(\".SH ENVIRONMENT\");\n s.push(\".TP\");\n s.push(\"\\\\fBAPCORE_EXTENSIONS_ROOT\\\\fR\");\n s.push(\"Path to the apcore extensions directory.\");\n s.push(\".TP\");\n s.push(\"\\\\fBAPCORE_CLI_AUTO_APPROVE\\\\fR\");\n s.push(\"Set to \\\\fB1\\\\fR to bypass approval prompts.\");\n s.push(\".TP\");\n s.push(\"\\\\fBAPCORE_CLI_LOGGING_LEVEL\\\\fR\");\n s.push(\"CLI\\\\-specific logging verbosity (DEBUG\|INFO\|WARNING\|ERROR).\");\n\n // Exit codes\n s.push(\".SH EXIT CODES\");\n const exitCodes: [string, string][] = [\n [\"0\", \"Success.\"],\n [\"1\", \"Module execution error.\"],\n [\"2\", \"Invalid CLI input or missing argument.\"],\n [\"44\", \"Module not found, disabled, or failed to load.\"],\n [\"45\", \"Input failed JSON Schema validation.\"],\n [\"46\", \"Approval denied or timed out.\"],\n [\"47\", \"Configuration error.\"],\n [\"77\", \"ACL denied.\"],\n [\"130\", \"Cancelled by user (SIGINT).\"],\n ];\n for (const [code, meaning] of exitCodes) {\n s.push(`.TP\\n\\\\fB${code}\\\\fR\\n${meaning}`);\n }\n\n s.push(\".SH SEE ALSO\");\n s.push(`\\\\fB${progName} \\\\-\\\\-help \\\\-\\\\-verbose\\\\fR for full option list.`);\n if (docsUrl) {\n s.push(`.PP\\nFull documentation at \\\\fI${roffEscape(docsUrl)}\\\\fR`);\n }\n\n return s.join(\"\\n\");\n}\n\n/\n Configure --help --man support on a Commander program.\n * When --man is passed with --help, outputs a complete roff man page\n * covering all registered commands (including downstream business commands).\n \n Usage in downstream projects:\n * configureManHelp(program, 'reach', '0.2.0', 'ReachForge: The Social Influence Engine', 'https://reachforge.dev/docs');\n /\nexport function configureManHelp(\n program: Command,\n progName: string,\n version: string,\n description?: string,\n docsUrl?: string,\n): void {\n // Add --man as a hidden option\n const manOpt = new Option(\"--man\", \"Output man page in roff format (use with --help)\").hideHelp();\n program.addOption(manOpt);\n\n // Intercept help to output roff when --man is set\n program.addHelpText(\"beforeAll\", () => {\n if (program.opts().man) {\n const roff = buildProgramManPage(program, progName, version, description, docsUrl) + \"\\n\";\n\n // If stdout is a TTY, render through a pager; otherwise output raw roff\n // (allows piping/redirection like `reach --help --man > reach.1`)\n if (process.stdout.isTTY) {\n // Try mandoc first (available on macOS/BSD), then groff, then fall back to raw output\n const pagers: Array<{ cmd: string; args: string[] }> = [\n { cmd: \"mandoc\", args: [\"-a\"] },\n { cmd: \"groff\", args: [\"-man\", \"-Tutf8\"] },\n ];\n let rendered = false;\n for (const { cmd, args } of pagers) {\n const result = spawnSync(cmd, args, {\n input: roff,\n stdio: [\"pipe\", \"pipe\", \"pipe\"],\n encoding: \"utf-8\",\n });\n if (result.status === 0 && result.stdout) {\n const pager = process.env.PAGER \|\| \"less\";\n const pagerResult = spawnSync(pager, [\"-R\"], {\n input: result.stdout,\n stdio: [\"pipe\", \"inherit\", \"inherit\"],\n });\n if (pagerResult.status !== null) {\n rendered = true;\n break;\n }\n }\n }\n if (!rendered) {\n process.stdout.write(roff);\n }\n } else {\n process.stdout.write(roff);\n }\n process.exit(0);\n }\n return \"\";\n });\n}\n\n// ---------------------------------------------------------------------------\n// registerShellCommands\n// ---------------------------------------------------------------------------\n\n/\n Register completion and man commands.\n */\nexport function registerShellCommands(\n cli: Command,\n progName = \"apcore-cli\",\n): void {\n const completionCmd = new Command(\"completion\")\n .description(\n \"Generate a shell completion script and print it to stdout.\",\n )\n .argument(\"<shell>\", \"Shell type: bash, zsh, or fish\")\n .action((shell: string) => {\n const validShells = [\"bash\", \"zsh\", \"fish\"];\n if (!validShells.includes(shell)) {\n process.stderr.write(\n `Error: Unknown shell '${shell}'. Expected: bash, zsh, or fish.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n const resolved = cli.name() \|\| progName;\n const generators: Record<string, () => string> = {\n bash: () => generateBashCompletion(resolved),\n zsh: () => generateZshCompletion(resolved),\n fish: () => generateFishCompletion(resolved),\n };\n process.stdout.write(generators[shell]());\n });\n cli.addCommand(completionCmd);\n\n const manCmd = new Command(\"man\")\n .description(\"Generate a roff man page for COMMAND and print it to stdout.\")\n .argument(\"<command>\", \"Command to generate man page for\")\n .action((commandName: string) => {\n const knownBuiltins = new Set([\"completion\", \"describe\", \"exec\", \"init\", \"list\", \"man\"]);\n const cmd = cli.commands.find((c) => c.name() === commandName) ?? null;\n\n if (!cmd && !knownBuiltins.has(commandName)) {\n process.stderr.write(\n `Error: Unknown command '${commandName}'.\\n`,\n );\n process.exit(EXIT_CODES.INVALID_CLI_INPUT);\n }\n\n const resolved = cli.name() \|\| progName;\n const roff = generateManPage(commandName, cmd, resolved);\n process.stdout.write(roff);\n });\n cli.addCommand(manCmd);\n}\n"],"mappings":"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","names":["readFileSync","fileURLToPath","path","Command","Option","path","fs","readFileSync","fileURLToPath","path","__dirname","__dirname","fileURLToPath","readFileSync","__dirname","Command"]}

package/dist/index.d.ts CHANGED Viewed

@@ -219,6 +219,11 @@ declare function registerInitCommand(cli: Command): void;
  */
 /** Default configuration values. */
 declare const DEFAULTS: Record<string, unknown>;
+/**
+ * Register the apcore-cli Config Bus namespace (apcore >= 0.15.0).
+ * Safe to call even when apcore-js is unavailable or < 0.15.0.
+ */
+declare function registerConfigNamespace(): void;
 /**
  * Resolves configuration from four tiers (highest to lowest priority):
  *   1. CLI flags
@@ -408,6 +413,12 @@ declare const EXIT_CODES: {
     readonly CONFIG_INVALID: 47;
     readonly SCHEMA_CIRCULAR_REF: 48;
     readonly ACL_DENIED: 77;
+    readonly CONFIG_NAMESPACE_RESERVED: 78;
+    readonly CONFIG_NAMESPACE_DUPLICATE: 78;
+    readonly CONFIG_ENV_PREFIX_CONFLICT: 78;
+    readonly CONFIG_MOUNT_ERROR: 66;
+    readonly CONFIG_BIND_ERROR: 65;
+    readonly ERROR_FORMATTER_DUPLICATE: 70;
     readonly KEYBOARD_INTERRUPT: 130;
 };
 type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
@@ -532,4 +543,4 @@ declare class Sandbox {
     private sandboxedExecute;
 }
-export { ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, BUILTIN_COMMANDS, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type Registry, Sandbox, SchemaValidationError, applyToolkitIntegration, buildModuleCommand, buildProgramManPage, checkApproval, collectInput, configureManHelp, createCli, debug, docsUrl, error, exitCodeForError, extractHelp, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getCliDisplayFields, getDisplay, getLogLevel, info, main, mapType, reconvertEnumValues, registerDiscoveryCommands, registerInitCommand, registerShellCommands, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, truncate, validateModuleId, verboseHelp, warn };
+export { ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, BUILTIN_COMMANDS, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, GroupedModuleGroup, LazyGroup, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type Registry, Sandbox, SchemaValidationError, applyToolkitIntegration, buildModuleCommand, buildProgramManPage, checkApproval, collectInput, configureManHelp, createCli, debug, docsUrl, error, exitCodeForError, extractHelp, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getCliDisplayFields, getDisplay, getLogLevel, info, main, mapType, reconvertEnumValues, registerConfigNamespace, registerDiscoveryCommands, registerInitCommand, registerShellCommands, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setDocsUrl, setLogLevel, setVerboseHelp, truncate, validateModuleId, verboseHelp, warn };