apcore-cli 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,45 @@ All notable changes to apcore-cli (TypeScript SDK) will be documented in this fi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-03-27
+
+### Added
+- **Grouped CLI commands (FE-09)** — `GroupedModuleGroup` organizes modules into nested subcommand groups by namespace prefix, enabling `apcore-cli <group> <command>` invocation.
+- **Display overlay helpers** — `getDisplay()` and `getCliDisplayFields()` resolve alias, description, and tags from `metadata["display"]`.
+- **Init command (FE-10)** — `apcore-cli init module <id>` scaffolds new modules with `--style` (decorator/convention/binding), `--dir`, and `--description` options.
+- **Grouped shell completions** — Bash, Zsh, and Fish completions now support two-level group/command completion via `_APCORE_GRP`.
+- **Optional apcore-toolkit integration** — `DisplayResolver` and `RegistryWriter` via optional `apcore-toolkit` peer dependency with graceful fallback.
+- **Path traversal validation** — `--dir` rejects paths containing `..` components.
+
+### Changed
+- `BUILTIN_COMMANDS` updated to include `init` (6 items, sorted).
+- `buildModuleCommand` accepts optional `cmdName` parameter for display alias override.
+- `APCORE_EXTENSIONS_ROOT` environment variable now used as fallback in `createCli()`.
+- `APCORE_AUTH_API_KEY` added to man page ENVIRONMENT section.
+- Dependency bump: `apcore-js >= 0.14.0`.
+
+## [0.2.2] - 2026-03-22
+
+### Changed
+- Rebrand: aipartnerup → aiperceivable
+
+## [0.2.1] - 2026-03-19
+
+### Changed
+- Help text truncation limit increased from 200 to 1000 characters (configurable via `cli.help_text_max_length` config key)
+- `extractHelp`: added `maxLength` parameter (default 1000) (`schema-parser.ts`)
+- `schemaToCliOptions`: added `maxHelpLength` parameter (default 1000) (`schema-parser.ts`)
+- `buildModuleCommand`: added `helpTextMaxLength` parameter (default 1000), threaded through to schema parser (`main.ts`)
+- `LazyModuleGroup`: constructor accepts `helpTextMaxLength` (default 1000), passes to `buildModuleCommand` (`cli.ts`)
+
+### Added
+- `cli.help_text_max_length` config key (default: 1000) in `DEFAULTS` (`config.ts`)
+- `APCORE_CLI_HELP_TEXT_MAX_LENGTH` environment variable support
+- Test: "truncates help text at 1000 chars (default)"
+- Test: "does not truncate text within default limit"
+- Test: "truncates at custom maxLength"
+- 183 tests (up from 181)
+
 ## [0.2.0] - 2026-03-18
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 AI Partner Up
+Copyright (c) 2026 AI Perceivable
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="https://raw.githubusercontent.com/aipartnerup/apcore-cli/main/apcore-cli-logo.svg" alt="apcore-cli logo" width="200"/>
+  <img src="https://raw.githubusercontent.com/aiperceivable/apcore-cli/main/apcore-cli-logo.svg" alt="apcore-cli logo" width="200"/>
 </div>
 
 # apcore-cli
@@ -8,16 +8,16 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Node](https://img.shields.io/badge/node-18%2B-blue.svg)](https://nodejs.org)
-[![Tests](https://img.shields.io/badge/tests-181%20passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-183%20passed-brightgreen.svg)]()
 
 | | |
 |---|---|
-| **TypeScript SDK** | [github.com/aipartnerup/apcore-cli-typescript](https://github.com/aipartnerup/apcore-cli-typescript) |
-| **Python SDK** | [github.com/aipartnerup/apcore-cli-python](https://github.com/aipartnerup/apcore-cli-python) |
-| **Spec repo** | [github.com/aipartnerup/apcore-cli](https://github.com/aipartnerup/apcore-cli) |
-| **apcore core** | [github.com/aipartnerup/apcore](https://github.com/aipartnerup/apcore) |
+| **TypeScript SDK** | [github.com/aiperceivable/apcore-cli-typescript](https://github.com/aiperceivable/apcore-cli-typescript) |
+| **Python SDK** | [github.com/aiperceivable/apcore-cli-python](https://github.com/aiperceivable/apcore-cli-python) |
+| **Spec repo** | [github.com/aiperceivable/apcore-cli](https://github.com/aiperceivable/apcore-cli) |
+| **apcore core** | [github.com/aiperceivable/apcore](https://github.com/aiperceivable/apcore) |
 
-**apcore-cli** turns any [apcore](https://github.com/aipartnerup/apcore)-based project into a fully featured CLI tool — with **zero code changes** to your existing modules.
+**apcore-cli** turns any [apcore](https://github.com/aiperceivable/apcore)-based project into a fully featured CLI tool — with **zero code changes** to your existing modules.
 
 ```
 ┌──────────────────┐
@@ -49,7 +49,7 @@ Terminal adapter for apcore. Execute AI-Perceivable modules from the command lin
 pnpm add apcore-cli apcore-js
 ```
 
-Requires Node.js 18+ and `apcore-js >= 0.13.0`.
+Requires Node.js 18+ and `apcore-js >= 0.14.0`.
 
 ## Quick Start
 
@@ -207,6 +207,7 @@ apcore-cli uses a 4-tier configuration precedence:
 | `APCORE_LOGGING_LEVEL` | Global apcore log level (fallback when `APCORE_CLI_LOGGING_LEVEL` is unset) | `WARNING` |
 | `APCORE_AUTH_API_KEY` | API key for remote registry authentication | *(unset)* |
 | `APCORE_CLI_SANDBOX` | Set to `1` to enable subprocess sandboxing | *(unset)* |
+| `APCORE_CLI_HELP_TEXT_MAX_LENGTH` | Maximum characters for CLI option help text before truncation | `1000` |
 
 ### Config File (`apcore.yaml`)
 
@@ -217,6 +218,8 @@ logging:
   level: DEBUG
 sandbox:
   enabled: false
+cli:
+  help_text_max_length: 1000
 ```
 
 ## Features
@@ -278,10 +281,10 @@ apcore Registry + Executor (your modules, unchanged)
 ## Development
 
 ```bash
-git clone https://github.com/aipartnerup/apcore-cli-typescript.git
+git clone https://github.com/aiperceivable/apcore-cli-typescript.git
 cd apcore-cli-typescript
 pnpm install
-pnpm test                        # 181 tests
+pnpm test                        # 183 tests
 pnpm build                       # compile TypeScript
 ```
 

package/dist/bin/apcore-cli.js

@@ -133,7 +133,7 @@ init_esm_shims();
 init_errors();
 import { readFileSync } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import * as path2 from "path";
+import * as path3 from "path";
 import { Command, CommanderError } from "commander";
 
 // src/ref-resolver.ts
@@ -163,18 +163,193 @@ function setLogLevel(level) {
   }
 }
 
+// src/init-cmd.ts
+init_esm_shims();
+import * as fs from "fs";
+import * as path2 from "path";
+var DECORATOR_TEMPLATE = `import { module } from "apcore-js";
+import { Type } from "@sinclair/typebox";
+
+export const {varName} = module({
+  id: "{moduleId}",
+  description: "{description}",
+  inputSchema: Type.Object({}),
+  outputSchema: Type.Object({ status: Type.String() }),
+  execute: (_inputs) => {
+    // TODO: implement
+    return { status: "ok" };
+  },
+});
+`;
+var CONVENTION_TEMPLATE = `/**
+ * {description}
+ */
+{cliGroupLine}
+export function {funcName}(): Record<string, unknown> {
+  // TODO: implement
+  return { status: "ok" };
+}
+`;
+var BINDING_TEMPLATE = `bindings:
+  - module_id: "{moduleId}"
+    target: "{target}"
+    description: "{description}"
+    auto_schema: true
+`;
+function renderTemplate(template, context) {
+  let result = template;
+  for (const [key, value] of Object.entries(context)) {
+    result = result.split(`{${key}}`).join(value);
+  }
+  return result;
+}
+function registerInitCommand(cli) {
+  const initGroup = cli.command("init").description("Scaffold new apcore modules.");
+  initGroup.command("module <module-id>").description("Create a new module from a template.\n\nMODULE_ID is the module identifier (e.g., ops.deploy, user.create).").option(
+    "--style <style>",
+    "Module style: decorator (@module), convention (plain function), or binding (YAML).",
+    "convention"
+  ).option("--dir <path>", "Output directory. Default: extensions/ or commands/.").option("-d, --description <text>", "Module description.", "TODO: add description").action((moduleId, opts) => {
+    const lastDot = moduleId.lastIndexOf(".");
+    const prefix = lastDot >= 0 ? moduleId.substring(0, lastDot) : moduleId;
+    const funcName = lastDot >= 0 ? moduleId.substring(lastDot + 1) : moduleId;
+    const style = opts.style;
+    const description = opts.description;
+    const dir = opts.dir ?? (style === "decorator" ? "extensions" : style === "binding" ? "bindings" : "commands");
+    if (dir.split(path2.sep).includes("..") || dir.split("/").includes("..")) {
+      process.stderr.write(`Error: Output directory must not contain '..' path components.
+`);
+      process.exit(2);
+    }
+    switch (style) {
+      case "decorator":
+        createDecoratorModule(moduleId, prefix, funcName, description, dir);
+        break;
+      case "convention":
+        createConventionModule(moduleId, prefix, funcName, description, dir);
+        break;
+      case "binding":
+        createBindingModule(moduleId, prefix, funcName, description, dir);
+        break;
+      default:
+        process.stderr.write(`Error: Unknown style '${style}'
+`);
+        process.exit(2);
+    }
+  });
+}
+function createDecoratorModule(moduleId, _prefix, funcName, description, outputDir) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  const filename = moduleId.replace(/\./g, "_") + ".ts";
+  const filepath = path2.join(outputDir, filename);
+  const varName = funcName + "Module";
+  const content = renderTemplate(DECORATOR_TEMPLATE, {
+    moduleId,
+    varName,
+    funcName,
+    description
+  });
+  fs.writeFileSync(filepath, content);
+  process.stdout.write(`Created ${filepath}
+`);
+}
+function createConventionModule(moduleId, prefix, funcName, description, outputDir) {
+  const prefixParts = prefix.split(".");
+  const dirPath = prefixParts.length > 1 ? path2.join(outputDir, ...prefixParts.slice(0, -1)) : outputDir;
+  fs.mkdirSync(dirPath, { recursive: true });
+  let filename;
+  if (prefixParts.length > 1) {
+    filename = prefixParts[prefixParts.length - 1] + ".ts";
+  } else {
+    filename = prefix + ".ts";
+  }
+  if (prefix === funcName) {
+    filename = prefix + ".ts";
+  }
+  const filepath = path2.join(dirPath, filename);
+  const cliGroupLine = moduleId.includes(".") ? `export const CLI_GROUP = "${prefixParts[0]}";
+` : "";
+  const content = renderTemplate(CONVENTION_TEMPLATE, {
+    funcName,
+    description,
+    cliGroupLine
+  });
+  fs.writeFileSync(filepath, content);
+  process.stdout.write(`Created ${filepath}
+`);
+}
+function createBindingModule(moduleId, prefix, funcName, description, outputDir) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  const yamlFile = path2.join(outputDir, moduleId.replace(/\./g, "_") + ".binding.yaml");
+  const target = `commands.${prefix}:${funcName}`;
+  const yamlContent = renderTemplate(BINDING_TEMPLATE, {
+    moduleId,
+    target,
+    description
+  });
+  fs.writeFileSync(yamlFile, yamlContent);
+  process.stdout.write(`Created ${yamlFile}
+`);
+  const baseSrc = "commands";
+  fs.mkdirSync(baseSrc, { recursive: true });
+  const srcFile = path2.join(baseSrc, prefix.replace(/\./g, "_") + ".ts");
+  if (!fs.existsSync(srcFile)) {
+    const srcContent = `export function ${funcName}(): Record<string, unknown> {
+  /** ${description} */
+  // TODO: implement
+  return { status: "ok" };
+}
+`;
+    fs.writeFileSync(srcFile, srcContent);
+    process.stdout.write(`Created ${srcFile}
+`);
+  }
+}
+
+// src/display-helpers.ts
+init_esm_shims();
+
 // src/main.ts
-var __dirname2 = path2.dirname(fileURLToPath2(import.meta.url));
-var pkg = JSON.parse(readFileSync(path2.resolve(__dirname2, "../package.json"), "utf-8"));
+var __dirname2 = path3.dirname(fileURLToPath2(import.meta.url));
+var pkg = JSON.parse(readFileSync(path3.resolve(__dirname2, "../package.json"), "utf-8"));
 var VERSION = pkg.version;
 function createCli(extensionsDir, progName) {
-  const resolvedProgName = progName ?? path2.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
+  const resolvedProgName = progName ?? path3.basename(process.argv[1] ?? "apcore-cli") ?? "apcore-cli";
   const cliLogLevel = process.env.APCORE_CLI_LOGGING_LEVEL ?? process.env.APCORE_LOGGING_LEVEL ?? "WARNING";
   setLogLevel(cliLogLevel);
-  const program = new Command(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING");
-  void extensionsDir;
+  const program = new Command(resolvedProgName).exitOverride().version(VERSION, "--version", `Show ${resolvedProgName} version`).description("apcore CLI \u2014 execute apcore modules from the command line").option("--extensions-dir <path>", "Path to extensions directory").option("--commands-dir <path>", "Path to convention-based commands directory").option("--binding <path>", "Path to binding.yaml for display overlay").option("--log-level <level>", "Logging level (DEBUG|INFO|WARNING|ERROR)", "WARNING");
+  const resolvedExtDir = extensionsDir ?? process.env.APCORE_EXTENSIONS_ROOT ?? "./extensions";
+  void resolvedExtDir;
+  registerInitCommand(program);
+  program.hook("preAction", async (thisCommand) => {
+    const opts = thisCommand.opts();
+    const commandsDir = opts.commandsDir;
+    const bindingPath = opts.binding;
+    await applyToolkitIntegration(commandsDir, bindingPath);
+  });
   return program;
 }
+async function applyToolkitIntegration(commandsDir, bindingPath) {
+  if (!commandsDir && !bindingPath) {
+    return;
+  }
+  try {
+    const toolkitModule = "apcore-toolkit";
+    const toolkit = await import(
+      /* @vite-ignore */
+      toolkitModule
+    );
+    if (commandsDir) {
+      console.warn("Convention scanning not yet available in TypeScript toolkit");
+    }
+    if (bindingPath) {
+      const resolver = new toolkit.DisplayResolver();
+      void resolver;
+    }
+  } catch {
+    console.warn("apcore-toolkit not installed \u2014 toolkit features unavailable");
+  }
+}
 function main(progName) {
   const program = createCli(void 0, progName);
   try {

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

@@ -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"],"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":";;;;;;;AACA,OAAO,UAAU;AACjB,SAAS,qBAAqB;AAF9B;AAAA;AAAA;AAAA;AAAA;;;ACkGO,SAAS,iBAAiB,OAA0B;AACzD,MAAI,iBAAiB,sBAAsB;AACzC,WAAO,WAAW;AAAA,EACpB;AACA,MAAI,iBAAiB,qBAAqB;AACxC,WAAO,WAAW;AAAA,EACpB;AACA,MAAI,iBAAiB,qBAAqB;AACxC,WAAO,WAAW;AAAA,EACpB;AACA,MAAI,iBAAiB,uBAAuB;AAC1C,WAAO,WAAW;AAAA,EACpB;AACA,MAAI,iBAAiB,uBAAuB;AAC1C,WAAO,WAAW;AAAA,EACpB;AACA,MAAI,iBAAiB,qBAAqB;AACxC,WAAO,WAAW;AAAA,EACpB;AACA,MAAI,iBAAiB,sBAAsB;AACzC,WAAO,WAAW;AAAA,EACpB;AAGA,MAAI,iBAAiB,OAAO;AAC1B,UAAM,OAAQ,MAA6C;AAC3D,UAAM,UAAoC;AAAA,MACxC,kBAAkB,WAAW;AAAA,MAC7B,mBAAmB,WAAW;AAAA,MAC9B,iBAAiB,WAAW;AAAA,MAC5B,yBAAyB,WAAW;AAAA,MACpC,qBAAqB,WAAW;AAAA,MAChC,iBAAiB,WAAW;AAAA,MAC5B,kBAAkB,WAAW;AAAA,MAC7B,kBAAkB,WAAW;AAAA,MAC7B,gBAAgB,WAAW;AAAA,MAC3B,sBAAsB,WAAW;AAAA,MACjC,gBAAgB,WAAW;AAAA,MAC3B,YAAY,WAAW;AAAA,IACzB;AACA,QAAI,QAAQ,QAAQ,SAAS;AAC3B,aAAO,QAAQ,IAAI;AAAA,IACrB;AAAA,EACF;AAEA,SAAO,WAAW;AACpB;AAhJA,IAWa,sBAQA,qBAQA,uBAQA,sBAQA,qBAQA,uBAQA,qBAWA;AAtEb;AAAA;AAAA;AAAA;AAWO,IAAM,uBAAN,cAAmC,MAAM;AAAA,MAC9C,YAAY,UAAU,sBAAsB;AAC1C,cAAM,OAAO;AACb,aAAK,OAAO;AAAA,MACd;AAAA,IACF;AAGO,IAAM,sBAAN,cAAkC,MAAM;AAAA,MAC7C,YAAY,UAAU,yBAAyB;AAC7C,cAAM,OAAO;AACb,aAAK,OAAO;AAAA,MACd;AAAA,IACF;AAGO,IAAM,wBAAN,cAAoC,MAAM;AAAA,MAC/C,YAAY,UAAU,4BAA4B;AAChD,cAAM,OAAO;AACb,aAAK,OAAO;AAAA,MACd;AAAA,IACF;AAGO,IAAM,uBAAN,cAAmC,MAAM;AAAA,MAC9C,YAAY,UAAU,2BAA2B;AAC/C,cAAM,OAAO;AACb,aAAK,OAAO;AAAA,MACd;AAAA,IACF;AAGO,IAAM,sBAAN,cAAkC,MAAM;AAAA,MAC7C,YAAY,UAAU,mBAAmB;AACvC,cAAM,OAAO;AACb,aAAK,OAAO;AAAA,MACd;AAAA,IACF;AAGO,IAAM,wBAAN,cAAoC,MAAM;AAAA,MAC/C,YAAY,UAAU,4BAA4B;AAChD,cAAM,OAAO;AACb,aAAK,OAAO;AAAA,MACd;AAAA,IACF;AAGO,IAAM,sBAAN,cAAkC,MAAM;AAAA,MAC7C,YAAY,UAAU,oBAAoB;AACxC,cAAM,OAAO;AACb,aAAK,OAAO;AAAA,MACd;AAAA,IACF;AAMO,IAAM,aAAa;AAAA,MACxB,SAAS;AAAA,MACT,sBAAsB;AAAA,MACtB,gBAAgB;AAAA,MAChB,mBAAmB;AAAA,MACnB,kBAAkB;AAAA,MAClB,mBAAmB;AAAA,MACnB,iBAAiB;AAAA,MACjB,yBAAyB;AAAA,MACzB,iBAAiB;AAAA,MACjB,kBAAkB;AAAA,MAClB,kBAAkB;AAAA,MAClB,gBAAgB;AAAA,MAChB,qBAAqB;AAAA,MACrB,YAAY;AAAA,MACZ,oBAAoB;AAAA,IACtB;AAAA;AAAA;;;ACtFA;;;ACAA;AAUA;AAJA,SAAS,oBAAoB;AAC7B,SAAS,iBAAAA,sBAAqB;AAC9B,YAAYC,WAAU;AACtB,SAAS,SAAS,sBAAsB;;;ACTxC;AAMA;;;ACNA;AAOA;;;ACPA;AAQA;AAFA,YAAY,cAAc;;;ACN1B;;;ACAA;AAIA,IAAM,SAAS,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,EAAE;AAGzD,IAAI,eAAyB;AAEtB,SAAS,YAAY,OAAqB;AAC/C,QAAM,QAAQ,MAAM,YAAY;AAChC,MAAI,SAAS,QAAQ;AACnB,mBAAe;AAAA,EACjB;AACF;;;ALIA,IAAMC,aAAiB,cAAQC,eAAc,YAAY,GAAG,CAAC;AAC7D,IAAM,MAAM,KAAK,MAAM,aAAkB,cAAQD,YAAW,iBAAiB,GAAG,OAAO,CAAC;AACxF,IAAM,UAAkB,IAAI;AAsCrB,SAAS,UACd,eACA,UACS;AAET,QAAM,mBAAmB,YAAiB,eAAS,QAAQ,KAAK,CAAC,KAAK,YAAY,KAAK;AAGvF,QAAM,cAAc,QAAQ,IAAI,4BAA4B,QAAQ,IAAI,wBAAwB;AAChG,cAAY,WAAW;AAEvB,QAAM,UAAU,IAAI,QAAQ,gBAAgB,EACzC,aAAa,EACb,QAAQ,SAAS,aAAa,QAAQ,gBAAgB,UAAU,EAChE,YAAY,gEAA2D,EACvE,OAAO,2BAA2B,8BAA8B,EAChE,OAAO,uBAAuB,4CAA4C,SAAS;AAItF,OAAK;AAEL,SAAO;AACT;AASO,SAAS,KAAK,UAAyB;AAC5C,QAAM,UAAU,UAAU,QAAW,QAAQ;AAE7C,MAAI;AACF,YAAQ,MAAM,QAAQ,IAAI;AAAA,EAC5B,SAAS,OAAgB;AACvB,QAAI,iBAAiB,gBAAgB;AAEnC,cAAQ,KAAK,MAAM,QAAQ;AAAA,IAC7B;AACA,UAAM,OAAO,iBAAiB,KAAK;AACnC,QAAI,iBAAiB,OAAO;AAC1B,cAAQ,OAAO,MAAM,UAAU,MAAM,OAAO;AAAA,CAAI;AAAA,IAClD;AACA,YAAQ,KAAK,IAAI;AAAA,EACnB;AACF;;;ADjGA,KAAK,YAAY;","names":["fileURLToPath","path","__dirname","fileURLToPath"]}
+{"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 } 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));\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(\"--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\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  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  helpTextMaxLength = 1000,\n  cmdName?: string,\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\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>, 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"]}