apcore-cli 0.2.0

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

@@ -0,0 +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"],"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 } 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 type { Executor, ModuleDescriptor } from \"./cli.js\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\nconst pkg = JSON.parse(readFileSync(path.resolve(__dirname, \"../package.json\"), \"utf-8\"));\nconst VERSION: string = pkg.version;\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): Command {\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(\"--log-level <level>\", \"Logging level (DEBUG|INFO|WARNING|ERROR)\", \"WARNING\");\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  void extensionsDir;\n\n  return program;\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  const program = createCli(undefined, progName);\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): Command {\n  const moduleId = moduleDef.id;\n  let resolvedSchema: Record<string, unknown> = {};\n  let schemaOptions: OptionConfig[] = [];\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);\n  }\n\n  const cmd = new Command(moduleId).description(moduleDef.description);\n\n  // Built-in options\n  cmd.option(\"--input <source>\", \"Read input from STDIN ('-')\");\n  cmd.option(\"-y, --yes\", \"Bypass approval prompts\", false);\n  cmd.option(\"--large-input\", \"Allow STDIN input larger than 10MB\", false);\n  cmd.option(\"--format <format>\", \"Output format (json|table)\");\n  cmd.option(\"--sandbox\", \"Run module in subprocess sandbox\", false);\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\"]);\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>): 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 (text.length > 200) {\n    return text.slice(0, 197) + \"...\";\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): 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);\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"],"mappings":"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","names":["fileURLToPath","path","__dirname","fileURLToPath"]}

package/dist/src/index.d.ts

@@ -0,0 +1,421 @@
+import { Command } from 'commander';
+
+/**
+ * LazyModuleGroup — Dynamic command loading from Registry.
+ *
+ * Equivalent to the Python LazyModuleGroup. Dynamically discovers apcore
+ * modules from the Registry and exposes them as Commander subcommands.
+ *
+ * Protocol spec: CLI command structure & lazy loading
+ */
+
+/** Placeholder for apcore-js Registry. */
+interface Registry {
+    listModules(): ModuleDescriptor[];
+    getModule(moduleId: string): ModuleDescriptor | null;
+}
+/** Placeholder for apcore-js Executor. */
+interface Executor {
+    execute(moduleId: string, input: Record<string, unknown>): Promise<unknown>;
+}
+/** Placeholder for apcore-js ModuleDescriptor. */
+interface ModuleDescriptor {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    requiresApproval?: boolean;
+    annotations?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Dynamically loads apcore modules as Commander subcommands from Registry.
+ *
+ * TODO: Implement lazy loading — commands should only be fully built when
+ * actually invoked, not at registration time.
+ */
+declare class LazyModuleGroup {
+    private readonly registry;
+    readonly executor: Executor;
+    private commandCache;
+    constructor(registry: Registry, executor: Executor);
+    /**
+     * List all available command names from the Registry.
+     *
+     * TODO: Implement registry enumeration.
+     */
+    listCommands(): string[];
+    /**
+     * Get or lazily build a Commander Command for the given module.
+     *
+     * TODO: Implement lazy command construction with schema-based options.
+     */
+    getCommand(cmdName: string): Command | null;
+}
+
+/**
+ * CLI entry point — createCli / main equivalents.
+ *
+ * Protocol spec: CLI bootstrapping & command registration
+ */
+
+/** Configuration for a single Commander option derived from a JSON Schema property. */
+interface OptionConfig {
+    /** The property name from the schema. */
+    name: string;
+    /** Commander flags string (e.g. "--my-flag <value>" or "--flag, --no-flag"). */
+    flags: string;
+    /** Help text for the option. */
+    description: string;
+    /** Default value. */
+    defaultValue?: unknown;
+    /** Whether the field is required (for display only). */
+    required: boolean;
+    /** Enum choices (string values). */
+    choices?: string[];
+    /** Whether this is a boolean flag pair (--flag/--no-flag). */
+    isBooleanFlag?: boolean;
+    /** Maps string enum value → original type name ("int", "float", "bool"). */
+    enumOriginalTypes?: Record<string, string>;
+    /** Parser function for Commander (e.g. parseInt, parseFloat). */
+    parseArg?: (value: string) => unknown;
+}
+/**
+ * Build and return the top-level Commander program.
+ *
+ * @param extensionsDir  Path to the extensions directory (default: ./extensions)
+ * @param progName       Program name shown in help (default: apcore-cli)
+ */
+declare function createCli(extensionsDir?: string, progName?: string): Command;
+/**
+ * Parse argv and run the CLI. Handles top-level error catching and exit codes.
+ */
+declare function main(progName?: string): void;
+/**
+ * Build a Commander Command for a single apcore module.
+ */
+declare function buildModuleCommand(moduleDef: ModuleDescriptor, executor: Executor): Command;
+/**
+ * Validate that a module ID conforms to the expected format.
+ * Pattern: [a-z][a-z0-9_]*(.[a-z][a-z0-9_])* — max 128 chars.
+ */
+declare function validateModuleId(moduleId: string): void;
+/**
+ * Collect module input from stdin and/or CLI keyword arguments.
+ */
+declare function collectInput(stdinFlag?: string, cliKwargs?: Record<string, unknown>, largeInput?: boolean): Promise<Record<string, unknown>>;
+/**
+ * Re-convert CLI string values back to their schema-typed equivalents
+ * based on the option configs.
+ */
+declare function reconvertEnumValues(kwargs: Record<string, unknown>, options: OptionConfig[]): Record<string, unknown>;
+
+/**
+ * ConfigResolver — 4-tier config resolution (CLI flag > env > file > default).
+ *
+ * Protocol spec: Configuration resolution
+ */
+/** Default configuration values. */
+declare const DEFAULTS: Record<string, unknown>;
+/**
+ * Resolves configuration from four tiers (highest to lowest priority):
+ *   1. CLI flags
+ *   2. Environment variables
+ *   3. Config file (YAML/JSON)
+ *   4. Built-in defaults
+ */
+declare class ConfigResolver {
+    private readonly cliFlags;
+    private readonly configPath;
+    private fileCache;
+    private fileCacheLoaded;
+    constructor(cliFlags?: Record<string, unknown>, configPath?: string);
+    /**
+     * Resolve a single configuration key across all four tiers.
+     */
+    resolve(key: string, cliFlag?: string, envVar?: string): unknown;
+    /**
+     * Load a value from the config file using a dot-separated key path.
+     */
+    private resolveFromFile;
+    /**
+     * Load and flatten a YAML config file.
+     */
+    private loadConfigFile;
+    /**
+     * Flatten nested dict to dot-notation keys.
+     */
+    private flattenDict;
+}
+
+/**
+ * Discovery commands — list and describe modules.
+ *
+ * Protocol spec: Module discovery & introspection
+ */
+
+/**
+ * Register list and describe commands on the CLI group.
+ */
+declare function registerDiscoveryCommands(cli: Command, registry: Registry): void;
+
+/**
+ * TTY-adaptive output formatting (table/json).
+ *
+ * Protocol spec: Output formatting
+ */
+
+/**
+ * Resolve output format with TTY-adaptive default.
+ */
+declare function resolveFormat(explicitFormat?: string): string;
+/**
+ * Truncate text to maxLength, appending '...' if needed.
+ */
+declare function truncate(text: string, maxLength?: number): string;
+/**
+ * Format and print a list of modules.
+ */
+declare function formatModuleList(modules: ModuleDescriptor[], format: string, filterTags?: string[]): void;
+/**
+ * Format and print full module metadata.
+ */
+declare function formatModuleDetail(moduleDef: ModuleDescriptor, format: string): void;
+/**
+ * Format and print module execution result.
+ */
+declare function formatExecResult(result: unknown, format?: string): void;
+
+/**
+ * JSON Schema $ref resolver.
+ *
+ * Protocol spec: Schema resolution & $ref handling
+ */
+/**
+ * Resolve all $ref references in a JSON Schema.
+ * Returns a fully inlined schema with $defs/definitions removed.
+ */
+declare function resolveRefs(schema: Record<string, unknown>, maxDepth?: number, moduleId?: string): Record<string, unknown>;
+
+/**
+ * JSON Schema -> Commander options mapping.
+ *
+ * Protocol spec: Schema-driven argument parsing
+ */
+
+/** Sentinel type marker for boolean flags. */
+declare const BOOLEAN_FLAG: unique symbol;
+type TypeResult = "string" | "int" | "float" | typeof BOOLEAN_FLAG | "file";
+/**
+ * Map JSON Schema type to a type identifier.
+ */
+declare function mapType(propName: string, propSchema: Record<string, unknown>): TypeResult;
+/**
+ * Extract help text from schema property, preferring x-llm-description.
+ */
+declare function extractHelp(propSchema: Record<string, unknown>): string | undefined;
+/**
+ * Convert a JSON Schema `properties` object into an array of
+ * Commander option configurations.
+ */
+declare function schemaToCliOptions(schema: Record<string, unknown>): OptionConfig[];
+
+/**
+ * Interactive approval prompts with timeout.
+ *
+ * Protocol spec: Approval workflow
+ */
+
+/**
+ * Check if module requires approval and handle accordingly.
+ * Returns normally if approved (or approval not required).
+ * Calls process.exit(46) if denied/timed out/non-TTY.
+ */
+declare function checkApproval(moduleDef: ModuleDescriptor, autoApprove: boolean): Promise<void>;
+
+/**
+ * Shell completion + man page generation.
+ *
+ * Protocol spec: Shell integration
+ */
+
+/**
+ * Register completion and man commands.
+ */
+declare function registerShellCommands(cli: Command, progName?: string): void;
+
+/**
+ * Error classes and exit code mapping for apcore-cli.
+ *
+ * Protocol spec: Error handling & exit codes
+ */
+/** Thrown when the user does not approve module execution within the timeout. */
+declare class ApprovalTimeoutError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when API key authentication fails or is missing. */
+declare class AuthenticationError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when encrypted config cannot be decrypted. */
+declare class ConfigDecryptionError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when module execution fails. */
+declare class ModuleExecutionError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when approval is denied by the user. */
+declare class ApprovalDeniedError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when schema validation fails. */
+declare class SchemaValidationError extends Error {
+    constructor(message?: string);
+}
+/** Thrown when a module is not found. */
+declare class ModuleNotFoundError extends Error {
+    constructor(message?: string);
+}
+declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly MODULE_EXECUTE_ERROR: 1;
+    readonly MODULE_TIMEOUT: 1;
+    readonly INVALID_CLI_INPUT: 2;
+    readonly MODULE_NOT_FOUND: 44;
+    readonly MODULE_LOAD_ERROR: 44;
+    readonly MODULE_DISABLED: 44;
+    readonly SCHEMA_VALIDATION_ERROR: 45;
+    readonly APPROVAL_DENIED: 46;
+    readonly APPROVAL_TIMEOUT: 46;
+    readonly CONFIG_NOT_FOUND: 47;
+    readonly CONFIG_INVALID: 47;
+    readonly SCHEMA_CIRCULAR_REF: 48;
+    readonly ACL_DENIED: 77;
+    readonly KEYBOARD_INTERRUPT: 130;
+};
+type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+/**
+ * Map a caught error to the appropriate process exit code.
+ * Also checks for apcore error codes on the error object.
+ */
+declare function exitCodeForError(error: unknown): ExitCode;
+
+/**
+ * Simple structured logger respecting logging.level config.
+ */
+declare const LEVELS: {
+    readonly DEBUG: 0;
+    readonly INFO: 1;
+    readonly WARNING: 2;
+    readonly ERROR: 3;
+};
+type LogLevel = keyof typeof LEVELS;
+declare function setLogLevel(level: string): void;
+declare function getLogLevel(): LogLevel;
+declare function debug(message: string): void;
+declare function info(message: string): void;
+declare function warn(message: string): void;
+declare function error(message: string): void;
+
+/**
+ * AuditLogger — JSONL audit trail.
+ *
+ * Protocol spec: Security — audit logging
+ */
+type ExecutionStatus = "success" | "error";
+/**
+ * Set the module-level audit logger instance.
+ */
+declare function setAuditLogger(auditLogger: AuditLogger | null): void;
+/**
+ * Get the current module-level audit logger instance.
+ */
+declare function getAuditLogger(): AuditLogger | null;
+declare class AuditLogger {
+    static readonly DEFAULT_PATH: string;
+    private readonly logPath;
+    constructor(path?: string);
+    private ensureDirectory;
+    logExecution(moduleId: string, inputData: Record<string, unknown>, status: ExecutionStatus, exitCode: number, durationMs: number): void;
+    private hashInput;
+    private getUser;
+}
+
+/**
+ * ConfigEncryptor — Keyring + AES-256-GCM fallback.
+ *
+ * Protocol spec: Security — config encryption
+ */
+/**
+ * Encrypts and decrypts configuration values. Prefers OS keyring for key
+ * storage, falling back to AES-256-GCM with a derived key.
+ */
+declare class ConfigEncryptor {
+    static readonly SERVICE_NAME = "apcore-cli";
+    /**
+     * Encrypt and store a configuration value.
+     */
+    store(key: string, value: string): Promise<string>;
+    /**
+     * Retrieve and decrypt a configuration value.
+     */
+    retrieve(configValue: string, key: string): Promise<string>;
+    private deriveKey;
+    private aesEncrypt;
+    private aesDecrypt;
+}
+
+/**
+ * AuthProvider — API key auth with keyring/encrypted storage.
+ *
+ * Protocol spec: Security — authentication
+ */
+
+/**
+ * Manages API key retrieval and request authentication.
+ */
+declare class AuthProvider {
+    private readonly config;
+    private readonly encryptor;
+    constructor(config: ConfigResolver, encryptor?: ConfigEncryptor);
+    /**
+     * Retrieve the API key from the configured sources.
+     * Handles keyring: and enc: prefixes via ConfigEncryptor.
+     */
+    getApiKey(): Promise<string | null>;
+    /**
+     * Add authentication headers to an outgoing request.
+     */
+    authenticateRequest(headers: Record<string, string>): Promise<Record<string, string>>;
+    /**
+     * Handle an HTTP response status code for auth-related errors.
+     */
+    handleResponse(statusCode: number): void;
+}
+
+/**
+ * Sandbox — Subprocess isolation for module execution.
+ *
+ * Protocol spec: Security — sandboxed execution
+ */
+
+/**
+ * Executes modules in an isolated subprocess to limit the blast radius
+ * of untrusted or third-party modules.
+ *
+ * When disabled, delegates directly to the Executor.
+ */
+declare class Sandbox {
+    private readonly enabled;
+    constructor(enabled?: boolean);
+    /**
+     * Execute a module, optionally inside a sandboxed subprocess.
+     */
+    execute(moduleId: string, inputData: Record<string, unknown>, executor: Executor): Promise<unknown>;
+    private sandboxedExecute;
+}
+
+export { ApprovalDeniedError, ApprovalTimeoutError, AuditLogger, AuthProvider, AuthenticationError, ConfigDecryptionError, ConfigEncryptor, ConfigResolver, DEFAULTS, EXIT_CODES, type Executor, type ExitCode, LazyModuleGroup, type ModuleDescriptor, ModuleExecutionError, ModuleNotFoundError, type OptionConfig, type Registry, Sandbox, SchemaValidationError, buildModuleCommand, checkApproval, collectInput, createCli, debug, error, exitCodeForError, extractHelp, formatExecResult, formatModuleDetail, formatModuleList, getAuditLogger, getLogLevel, info, main, mapType, reconvertEnumValues, registerDiscoveryCommands, registerShellCommands, resolveFormat, resolveRefs, schemaToCliOptions, setAuditLogger, setLogLevel, truncate, validateModuleId, warn };