apcore-cli 0.2.0

package/dist/src/index.js

@@ -0,0 +1,1755 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// node_modules/.pnpm/tsup@8.5.1_postcss@8.5.8_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js
+import path from "path";
+import { fileURLToPath } from "url";
+var init_esm_shims = __esm({
+  "node_modules/.pnpm/tsup@8.5.1_postcss@8.5.8_typescript@5.9.3/node_modules/tsup/assets/esm_shims.js"() {
+    "use strict";
+  }
+});
+
+// src/errors.ts
+function exitCodeForError(error2) {
+  if (error2 instanceof ApprovalTimeoutError) {
+    return EXIT_CODES.APPROVAL_TIMEOUT;
+  }
+  if (error2 instanceof ApprovalDeniedError) {
+    return EXIT_CODES.APPROVAL_DENIED;
+  }
+  if (error2 instanceof AuthenticationError) {
+    return EXIT_CODES.ACL_DENIED;
+  }
+  if (error2 instanceof ConfigDecryptionError) {
+    return EXIT_CODES.CONFIG_INVALID;
+  }
+  if (error2 instanceof SchemaValidationError) {
+    return EXIT_CODES.SCHEMA_VALIDATION_ERROR;
+  }
+  if (error2 instanceof ModuleNotFoundError) {
+    return EXIT_CODES.MODULE_NOT_FOUND;
+  }
+  if (error2 instanceof ModuleExecutionError) {
+    return EXIT_CODES.MODULE_EXECUTE_ERROR;
+  }
+  if (error2 instanceof Error) {
+    const code = error2.code;
+    const codeMap = {
+      MODULE_NOT_FOUND: EXIT_CODES.MODULE_NOT_FOUND,
+      MODULE_LOAD_ERROR: EXIT_CODES.MODULE_LOAD_ERROR,
+      MODULE_DISABLED: EXIT_CODES.MODULE_DISABLED,
+      SCHEMA_VALIDATION_ERROR: EXIT_CODES.SCHEMA_VALIDATION_ERROR,
+      SCHEMA_CIRCULAR_REF: EXIT_CODES.SCHEMA_CIRCULAR_REF,
+      APPROVAL_DENIED: EXIT_CODES.APPROVAL_DENIED,
+      APPROVAL_TIMEOUT: EXIT_CODES.APPROVAL_TIMEOUT,
+      CONFIG_NOT_FOUND: EXIT_CODES.CONFIG_NOT_FOUND,
+      CONFIG_INVALID: EXIT_CODES.CONFIG_INVALID,
+      MODULE_EXECUTE_ERROR: EXIT_CODES.MODULE_EXECUTE_ERROR,
+      MODULE_TIMEOUT: EXIT_CODES.MODULE_TIMEOUT,
+      ACL_DENIED: EXIT_CODES.ACL_DENIED
+    };
+    if (code && code in codeMap) {
+      return codeMap[code];
+    }
+  }
+  return EXIT_CODES.MODULE_EXECUTE_ERROR;
+}
+var ApprovalTimeoutError, AuthenticationError, ConfigDecryptionError, ModuleExecutionError, ApprovalDeniedError, SchemaValidationError, ModuleNotFoundError, EXIT_CODES;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    init_esm_shims();
+    ApprovalTimeoutError = class extends Error {
+      constructor(message = "Approval timed out") {
+        super(message);
+        this.name = "ApprovalTimeoutError";
+      }
+    };
+    AuthenticationError = class extends Error {
+      constructor(message = "Authentication failed") {
+        super(message);
+        this.name = "AuthenticationError";
+      }
+    };
+    ConfigDecryptionError = class extends Error {
+      constructor(message = "Config decryption failed") {
+        super(message);
+        this.name = "ConfigDecryptionError";
+      }
+    };
+    ModuleExecutionError = class extends Error {
+      constructor(message = "Module execution failed") {
+        super(message);
+        this.name = "ModuleExecutionError";
+      }
+    };
+    ApprovalDeniedError = class extends Error {
+      constructor(message = "Approval denied") {
+        super(message);
+        this.name = "ApprovalDeniedError";
+      }
+    };
+    SchemaValidationError = class extends Error {
+      constructor(message = "Schema validation failed") {
+        super(message);
+        this.name = "SchemaValidationError";
+      }
+    };
+    ModuleNotFoundError = class extends Error {
+      constructor(message = "Module not found") {
+        super(message);
+        this.name = "ModuleNotFoundError";
+      }
+    };
+    EXIT_CODES = {
+      SUCCESS: 0,
+      MODULE_EXECUTE_ERROR: 1,
+      MODULE_TIMEOUT: 1,
+      INVALID_CLI_INPUT: 2,
+      MODULE_NOT_FOUND: 44,
+      MODULE_LOAD_ERROR: 44,
+      MODULE_DISABLED: 44,
+      SCHEMA_VALIDATION_ERROR: 45,
+      APPROVAL_DENIED: 46,
+      APPROVAL_TIMEOUT: 46,
+      CONFIG_NOT_FOUND: 47,
+      CONFIG_INVALID: 47,
+      SCHEMA_CIRCULAR_REF: 48,
+      ACL_DENIED: 77,
+      KEYBOARD_INTERRUPT: 130
+    };
+  }
+});
+
+// src/security/audit.ts
+var audit_exports = {};
+__export(audit_exports, {
+  AuditLogger: () => AuditLogger,
+  getAuditLogger: () => getAuditLogger,
+  setAuditLogger: () => setAuditLogger
+});
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as os from "os";
+import * as path2 from "path";
+function setAuditLogger(auditLogger) {
+  _auditLogger = auditLogger;
+}
+function getAuditLogger() {
+  return _auditLogger;
+}
+var _auditLogger, AuditLogger;
+var init_audit = __esm({
+  "src/security/audit.ts"() {
+    "use strict";
+    init_esm_shims();
+    _auditLogger = null;
+    AuditLogger = class _AuditLogger {
+      static DEFAULT_PATH = path2.join(
+        os.homedir(),
+        ".apcore-cli",
+        "audit.jsonl"
+      );
+      logPath;
+      constructor(path6) {
+        this.logPath = path6 ?? _AuditLogger.DEFAULT_PATH;
+        this.ensureDirectory();
+      }
+      ensureDirectory() {
+        try {
+          fs.mkdirSync(path2.dirname(this.logPath), { recursive: true });
+        } catch {
+        }
+      }
+      logExecution(moduleId, inputData, status, exitCode, durationMs) {
+        const entry = {
+          timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+          user: this.getUser(),
+          module_id: moduleId,
+          input_hash: this.hashInput(inputData),
+          status,
+          exit_code: exitCode,
+          duration_ms: durationMs
+        };
+        try {
+          fs.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
+        } catch (err) {
+          console.warn(`Could not write audit log: ${err}`);
+        }
+      }
+      hashInput(inputData) {
+        const salt = crypto.randomBytes(16);
+        const sortedKeys = Object.keys(inputData).sort();
+        const payload = JSON.stringify(inputData, sortedKeys);
+        return crypto.createHash("sha256").update(Buffer.concat([salt, Buffer.from(payload, "utf-8")])).digest("hex");
+      }
+      getUser() {
+        try {
+          return os.userInfo().username;
+        } catch {
+          return process.env.USER ?? process.env.USERNAME ?? "unknown";
+        }
+      }
+    };
+  }
+});
+
+// src/security/config-encryptor.ts
+import * as crypto2 from "crypto";
+import * as os2 from "os";
+async function getKeytar() {
+  if (keytarModule) return keytarModule;
+  try {
+    keytarModule = await import("keytar");
+    return keytarModule;
+  } catch {
+    return null;
+  }
+}
+var keytarModule, ConfigEncryptor;
+var init_config_encryptor = __esm({
+  "src/security/config-encryptor.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    keytarModule = null;
+    ConfigEncryptor = class _ConfigEncryptor {
+      static SERVICE_NAME = "apcore-cli";
+      /**
+       * Encrypt and store a configuration value.
+       */
+      async store(key, value) {
+        const keytar = await getKeytar();
+        if (keytar) {
+          try {
+            await keytar.setPassword(_ConfigEncryptor.SERVICE_NAME, key, value);
+            return `keyring:${key}`;
+          } catch {
+          }
+        }
+        console.warn("OS keyring unavailable. Using file-based encryption.");
+        const ciphertext = this.aesEncrypt(value);
+        return `enc:${Buffer.from(ciphertext).toString("base64")}`;
+      }
+      /**
+       * Retrieve and decrypt a configuration value.
+       */
+      async retrieve(configValue, key) {
+        if (configValue.startsWith("keyring:")) {
+          const keytar = await getKeytar();
+          if (!keytar) {
+            throw new ConfigDecryptionError(
+              `Keyring module not available to retrieve '${key}'.`
+            );
+          }
+          try {
+            const refKey = configValue.slice("keyring:".length);
+            const result = await keytar.getPassword(
+              _ConfigEncryptor.SERVICE_NAME,
+              refKey
+            );
+            if (result === null || result === void 0) {
+              throw new ConfigDecryptionError(
+                `Keyring entry not found for '${refKey}'.`
+              );
+            }
+            return result;
+          } catch (err) {
+            if (err instanceof ConfigDecryptionError) throw err;
+            throw new ConfigDecryptionError(
+              `Failed to retrieve from keyring: ${err}`
+            );
+          }
+        }
+        if (configValue.startsWith("enc:")) {
+          const ciphertext = Buffer.from(
+            configValue.slice("enc:".length),
+            "base64"
+          );
+          try {
+            return this.aesDecrypt(ciphertext);
+          } catch {
+            throw new ConfigDecryptionError(
+              `Failed to decrypt configuration value '${key}'. Re-configure with 'apcore-cli config set ${key}'.`
+            );
+          }
+        }
+        return configValue;
+      }
+      // NOTE: Best-effort fallback when OS keyring is unavailable.
+      // The key is derived from hostname + username (non-secret inputs).
+      // For production security, ensure the OS keyring is accessible.
+      deriveKey() {
+        const hostname2 = os2.hostname();
+        const username = process.env.USER ?? process.env.USERNAME ?? "unknown";
+        const salt = Buffer.from("apcore-cli-config-v1");
+        const material = `${hostname2}:${username}`;
+        return crypto2.pbkdf2Sync(material, salt, 1e5, 32, "sha256");
+      }
+      aesEncrypt(plaintext) {
+        const key = this.deriveKey();
+        const nonce = crypto2.randomBytes(12);
+        const cipher = crypto2.createCipheriv("aes-256-gcm", key, nonce);
+        const ct = Buffer.concat([
+          cipher.update(plaintext, "utf-8"),
+          cipher.final()
+        ]);
+        const tag = cipher.getAuthTag();
+        return Buffer.concat([nonce, tag, ct]);
+      }
+      aesDecrypt(data) {
+        const key = this.deriveKey();
+        const nonce = data.subarray(0, 12);
+        const tag = data.subarray(12, 28);
+        const ct = data.subarray(28);
+        const decipher = crypto2.createDecipheriv("aes-256-gcm", key, nonce);
+        decipher.setAuthTag(tag);
+        const plaintext = Buffer.concat([decipher.update(ct), decipher.final()]);
+        return plaintext.toString("utf-8");
+      }
+    };
+  }
+});
+
+// src/security/auth.ts
+var AuthProvider;
+var init_auth = __esm({
+  "src/security/auth.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    init_config_encryptor();
+    AuthProvider = class {
+      config;
+      encryptor;
+      constructor(config, encryptor) {
+        this.config = config;
+        this.encryptor = encryptor ?? new ConfigEncryptor();
+      }
+      /**
+       * Retrieve the API key from the configured sources.
+       * Handles keyring: and enc: prefixes via ConfigEncryptor.
+       */
+      async getApiKey() {
+        const result = this.config.resolve(
+          "auth.api_key",
+          "--api-key",
+          "APCORE_AUTH_API_KEY"
+        );
+        if (result === null || result === void 0) {
+          return null;
+        }
+        const strResult = String(result);
+        if (strResult.startsWith("keyring:") || strResult.startsWith("enc:")) {
+          return this.encryptor.retrieve(strResult, "auth.api_key");
+        }
+        return strResult;
+      }
+      /**
+       * Add authentication headers to an outgoing request.
+       */
+      async authenticateRequest(headers) {
+        const key = await this.getApiKey();
+        if (!key) {
+          throw new AuthenticationError(
+            "Remote registry requires authentication. Set --api-key, APCORE_AUTH_API_KEY, or auth.api_key in config."
+          );
+        }
+        return { ...headers, Authorization: `Bearer ${key}` };
+      }
+      /**
+       * Handle an HTTP response status code for auth-related errors.
+       */
+      handleResponse(statusCode) {
+        if (statusCode === 401 || statusCode === 403) {
+          throw new AuthenticationError(
+            "Authentication failed. Verify your API key."
+          );
+        }
+      }
+    };
+  }
+});
+
+// src/security/sandbox.ts
+import * as child_process from "child_process";
+import * as fs2 from "fs";
+import * as os3 from "os";
+import * as path3 from "path";
+var Sandbox;
+var init_sandbox = __esm({
+  "src/security/sandbox.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_errors();
+    Sandbox = class {
+      enabled;
+      constructor(enabled = false) {
+        this.enabled = enabled;
+      }
+      /**
+       * Execute a module, optionally inside a sandboxed subprocess.
+       */
+      async execute(moduleId, inputData, executor) {
+        if (!this.enabled) {
+          return executor.execute(moduleId, inputData);
+        }
+        return this.sandboxedExecute(moduleId, inputData);
+      }
+      sandboxedExecute(moduleId, inputData) {
+        const env = {};
+        for (const key of ["PATH", "NODE_PATH", "LANG", "LC_ALL"]) {
+          if (process.env[key]) {
+            env[key] = process.env[key];
+          }
+        }
+        for (const [key, value] of Object.entries(process.env)) {
+          if (key.startsWith("APCORE_") && value) {
+            env[key] = value;
+          }
+        }
+        const tmpDir = fs2.mkdtempSync(
+          path3.join(os3.tmpdir(), "apcore_sandbox_")
+        );
+        try {
+          env.HOME = tmpDir;
+          env.TMPDIR = tmpDir;
+          const script = [
+            "let d='';",
+            "process.stdin.setEncoding('utf-8');",
+            "process.stdin.on('data',c=>d+=c);",
+            "process.stdin.on('end',()=>{",
+            "  const input=JSON.parse(d);",
+            `  process.stdout.write(JSON.stringify({error:"Sandbox runner not yet implemented for module: ${moduleId}"}));`,
+            "});"
+          ].join("");
+          const result = child_process.execFileSync(
+            process.execPath,
+            ["-e", script],
+            {
+              input: JSON.stringify(inputData),
+              env,
+              cwd: tmpDir,
+              timeout: 3e5,
+              maxBuffer: 10 * 1024 * 1024
+            }
+          );
+          return JSON.parse(result.toString("utf-8"));
+        } catch (err) {
+          if (err instanceof Error && "killed" in err && err.killed) {
+            throw new ModuleExecutionError(
+              `Error: Module '${moduleId}' timed out in sandbox.`
+            );
+          }
+          const stderr = err instanceof Error && "stderr" in err ? String(err.stderr) : String(err);
+          throw new ModuleExecutionError(
+            `Error: Module '${moduleId}' execution failed: ${stderr}`
+          );
+        } finally {
+          try {
+            fs2.rmSync(tmpDir, { recursive: true, force: true });
+          } catch {
+          }
+        }
+      }
+    };
+  }
+});
+
+// src/security/index.ts
+var security_exports = {};
+__export(security_exports, {
+  AuditLogger: () => AuditLogger,
+  AuthProvider: () => AuthProvider,
+  ConfigEncryptor: () => ConfigEncryptor,
+  Sandbox: () => Sandbox,
+  getAuditLogger: () => getAuditLogger,
+  setAuditLogger: () => setAuditLogger
+});
+var init_security = __esm({
+  "src/security/index.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_audit();
+    init_auth();
+    init_config_encryptor();
+    init_sandbox();
+  }
+});
+
+// src/index.ts
+init_esm_shims();
+
+// src/main.ts
+init_esm_shims();
+init_errors();
+import { readFileSync } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import * as path4 from "path";
+import { Command, CommanderError } from "commander";
+
+// src/ref-resolver.ts
+init_esm_shims();
+init_errors();
+function resolveRefs(schema, maxDepth = 32, moduleId = "") {
+  const cloned = structuredClone(schema);
+  const defs = cloned.$defs ?? cloned.definitions ?? {};
+  const result = resolveNode(
+    cloned,
+    defs,
+    /* @__PURE__ */ new Set(),
+    0,
+    maxDepth,
+    moduleId
+  );
+  delete result.$defs;
+  delete result.definitions;
+  return result;
+}
+function resolveNode(node, defs, visited, depth, maxDepth, moduleId) {
+  if (typeof node !== "object" || node === null || Array.isArray(node)) {
+    return node;
+  }
+  const obj = node;
+  if ("$ref" in obj) {
+    const refPath = obj.$ref;
+    if (depth >= maxDepth) {
+      process.stderr.write(
+        `Error: $ref resolution depth exceeded maximum of ${maxDepth} for module '${moduleId}'.
+`
+      );
+      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+    }
+    if (visited.has(refPath)) {
+      process.stderr.write(
+        `Error: Circular $ref detected in schema for module '${moduleId}' at path '${refPath}'.
+`
+      );
+      process.exit(EXIT_CODES.SCHEMA_CIRCULAR_REF);
+    }
+    const parts = refPath.split("/");
+    const key = parts[parts.length - 1];
+    if (!(key in defs)) {
+      process.stderr.write(
+        `Error: Unresolvable $ref '${refPath}' in schema for module '${moduleId}'.
+`
+      );
+      process.exit(EXIT_CODES.SCHEMA_VALIDATION_ERROR);
+    }
+    const newVisited = new Set(visited);
+    newVisited.add(refPath);
+    return resolveNode(defs[key], defs, newVisited, depth + 1, maxDepth, moduleId);
+  }
+  if ("allOf" in obj && Array.isArray(obj.allOf)) {
+    const merged = {
+      properties: {},
+      required: []
+    };
+    for (const subSchema of obj.allOf) {
+      const resolved = resolveNode(
+        subSchema,
+        defs,
+        visited,
+        depth + 1,
+        maxDepth,
+        moduleId
+      );
+      if (resolved.properties) {
+        Object.assign(
+          merged.properties,
+          resolved.properties
+        );
+      }
+      if (Array.isArray(resolved.required)) {
+        merged.required.push(...resolved.required);
+      }
+    }
+    merged.required = [...new Set(merged.required)];
+    for (const [k, v] of Object.entries(obj)) {
+      if (k !== "allOf" && !(k in merged)) {
+        merged[k] = v;
+      }
+    }
+    return merged;
+  }
+  for (const keyword of ["anyOf", "oneOf"]) {
+    if (keyword in obj && Array.isArray(obj[keyword])) {
+      const merged = {
+        properties: {},
+        required: []
+      };
+      const allRequiredSets = [];
+      for (const subSchema of obj[keyword]) {
+        const resolved = resolveNode(
+          subSchema,
+          defs,
+          visited,
+          depth + 1,
+          maxDepth,
+          moduleId
+        );
+        if (resolved.properties) {
+          Object.assign(
+            merged.properties,
+            resolved.properties
+          );
+        }
+        if (Array.isArray(resolved.required)) {
+          allRequiredSets.push(new Set(resolved.required));
+        }
+      }
+      if (allRequiredSets.length > 0) {
+        let intersection = allRequiredSets[0];
+        for (let i = 1; i < allRequiredSets.length; i++) {
+          intersection = new Set(
+            [...intersection].filter((x) => allRequiredSets[i].has(x))
+          );
+        }
+        merged.required = [...intersection];
+      } else {
+        merged.required = [];
+      }
+      for (const [k, v] of Object.entries(obj)) {
+        if (k !== keyword && !(k in merged)) {
+          merged[k] = v;
+        }
+      }
+      return merged;
+    }
+  }
+  if ("properties" in obj && typeof obj.properties === "object" && obj.properties !== null) {
+    const props = obj.properties;
+    for (const [propName, propSchema] of Object.entries(props)) {
+      props[propName] = resolveNode(
+        propSchema,
+        defs,
+        visited,
+        depth + 1,
+        maxDepth,
+        moduleId
+      );
+    }
+  }
+  return obj;
+}
+
+// src/schema-parser.ts
+init_esm_shims();
+init_errors();
+var BOOLEAN_FLAG = /* @__PURE__ */ Symbol("BOOLEAN_FLAG");
+function mapType(propName, propSchema) {
+  const schemaType = propSchema.type;
+  if (schemaType === "string" && (propName.endsWith("_file") || propSchema["x-cli-file"] === true)) {
+    return "file";
+  }
+  const typeMap = {
+    string: "string",
+    integer: "int",
+    number: "float",
+    boolean: BOOLEAN_FLAG,
+    object: "string",
+    array: "string"
+  };
+  if (!schemaType) {
+    return "string";
+  }
+  return typeMap[schemaType] ?? "string";
+}
+function extractHelp(propSchema) {
+  let text = propSchema["x-llm-description"];
+  if (!text) {
+    text = propSchema.description;
+  }
+  if (!text) {
+    return void 0;
+  }
+  if (text.length > 200) {
+    return text.slice(0, 197) + "...";
+  }
+  return text;
+}
+var RESERVED_NAMES = /* @__PURE__ */ new Set(["input", "yes", "large_input", "format", "sandbox"]);
+function schemaToCliOptions(schema) {
+  const properties = schema.properties ?? {};
+  const requiredList = schema.required ?? [];
+  const options = [];
+  const flagNames = {};
+  for (const [propName, propSchema] of Object.entries(properties)) {
+    const flagName = "--" + propName.replace(/_/g, "-");
+    if (flagName in flagNames) {
+      process.stderr.write(
+        `Error: Flag name collision: properties '${propName}' and '${flagNames[flagName]}' both map to '${flagName}'.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    flagNames[flagName] = propName;
+    if (RESERVED_NAMES.has(propName)) {
+      process.stderr.write(
+        `Error: Module schema property '${propName}' conflicts with a reserved CLI option name. Rename the property.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    const typeResult = mapType(propName, propSchema);
+    const isRequired = requiredList.includes(propName);
+    const helpBase = extractHelp(propSchema);
+    const helpText = isRequired ? (helpBase ? helpBase + " " : "") + "[required]" : helpBase ?? "";
+    const defaultValue = propSchema.default;
+    if (typeResult === BOOLEAN_FLAG) {
+      const flagBase = propName.replace(/_/g, "-");
+      const defaultVal = propSchema.default ?? false;
+      options.push({
+        name: propName,
+        flags: `--${flagBase}, --no-${flagBase}`,
+        description: helpText,
+        defaultValue: defaultVal,
+        required: false,
+        isBooleanFlag: true
+      });
+    } else if ("enum" in propSchema && Array.isArray(propSchema.enum)) {
+      const enumValues = propSchema.enum;
+      if (enumValues.length === 0) {
+        options.push({
+          name: propName,
+          flags: `${flagName} <value>`,
+          description: helpText,
+          defaultValue,
+          required: false
+        });
+      } else {
+        const stringValues = enumValues.map(String);
+        const enumOriginalTypes = {};
+        for (const v of enumValues) {
+          if (typeof v === "number" && Number.isInteger(v)) {
+            enumOriginalTypes[String(v)] = "int";
+          } else if (typeof v === "number") {
+            enumOriginalTypes[String(v)] = "float";
+          } else if (typeof v === "boolean") {
+            enumOriginalTypes[String(v)] = "bool";
+          }
+        }
+        options.push({
+          name: propName,
+          flags: `${flagName} <value>`,
+          description: helpText,
+          defaultValue: defaultValue !== void 0 ? String(defaultValue) : void 0,
+          required: false,
+          choices: stringValues,
+          enumOriginalTypes: Object.keys(enumOriginalTypes).length > 0 ? enumOriginalTypes : void 0
+        });
+      }
+    } else {
+      let parseArg;
+      if (typeResult === "int") {
+        parseArg = (v) => {
+          const n = parseInt(v, 10);
+          if (isNaN(n)) throw new Error(`Invalid integer: ${v}`);
+          return n;
+        };
+      } else if (typeResult === "float") {
+        parseArg = (v) => {
+          const n = parseFloat(v);
+          if (isNaN(n)) throw new Error(`Invalid number: ${v}`);
+          return n;
+        };
+      }
+      options.push({
+        name: propName,
+        flags: `${flagName} <value>`,
+        description: helpText,
+        defaultValue,
+        required: false,
+        parseArg
+      });
+    }
+  }
+  return options;
+}
+
+// src/approval.ts
+init_esm_shims();
+init_errors();
+import * as readline from "readline";
+function getAnnotation(annotations, key, defaultValue = void 0) {
+  if (!annotations || typeof annotations !== "object") return defaultValue;
+  const ann = annotations;
+  return key in ann ? ann[key] : defaultValue;
+}
+async function checkApproval(moduleDef, autoApprove) {
+  const annotations = moduleDef.annotations;
+  let requiresApproval;
+  if (moduleDef.requiresApproval !== void 0) {
+    requiresApproval = moduleDef.requiresApproval;
+  } else if (annotations) {
+    requiresApproval = getAnnotation(annotations, "requires_approval", false) === true;
+  } else {
+    return;
+  }
+  if (!requiresApproval) {
+    return;
+  }
+  const moduleId = moduleDef.id;
+  if (autoApprove) {
+    return;
+  }
+  const envVal = process.env.APCORE_CLI_AUTO_APPROVE ?? "";
+  if (envVal === "1") {
+    return;
+  }
+  if (envVal !== "" && envVal !== "1") {
+    process.stderr.write(
+      `Warning: APCORE_CLI_AUTO_APPROVE is set to '${envVal}', expected '1'. Ignoring.
+`
+    );
+  }
+  if (!process.stdin.isTTY) {
+    process.stderr.write(
+      `Error: Module '${moduleId}' requires approval but no interactive terminal is available. Use --yes or set APCORE_CLI_AUTO_APPROVE=1 to bypass.
+`
+    );
+    process.exit(EXIT_CODES.APPROVAL_DENIED);
+  }
+  await promptWithTimeout(moduleDef, 60);
+}
+async function promptWithTimeout(moduleDef, timeout) {
+  timeout = Math.max(1, Math.min(timeout, 3600));
+  const moduleId = moduleDef.id;
+  const annotations = moduleDef.annotations;
+  const message = (annotations ? getAnnotation(annotations, "approval_message") : void 0) ?? `Module '${moduleId}' requires approval to execute.`;
+  process.stderr.write(message + "\n");
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr
+  });
+  let timer;
+  try {
+    const answer = await Promise.race([
+      new Promise((resolve3) => {
+        rl.question("Proceed? [y/N] ", (ans) => resolve3(ans));
+      }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new ApprovalTimeoutError(
+            `Approval prompt timed out after ${timeout} seconds.`
+          ));
+        }, timeout * 1e3);
+      })
+    ]);
+    if (timer) clearTimeout(timer);
+    const normalized = answer.trim().toLowerCase();
+    if (normalized === "y" || normalized === "yes") {
+      return;
+    }
+    process.stderr.write("Error: Approval denied.\n");
+    process.exit(EXIT_CODES.APPROVAL_DENIED);
+  } catch (err) {
+    if (timer) clearTimeout(timer);
+    if (err instanceof ApprovalTimeoutError) {
+      process.stderr.write(
+        `Error: Approval prompt timed out after ${timeout} seconds.
+`
+      );
+      process.exit(EXIT_CODES.APPROVAL_TIMEOUT);
+    }
+    throw err;
+  } finally {
+    rl.close();
+  }
+}
+
+// src/output.ts
+init_esm_shims();
+function resolveFormat(explicitFormat) {
+  if (explicitFormat !== void 0) {
+    return explicitFormat;
+  }
+  return process.stdout.isTTY ? "table" : "json";
+}
+function truncate(text, maxLength = 80) {
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return text.slice(0, maxLength - 3) + "...";
+}
+function formatTable(headers, rows) {
+  const colWidths = headers.map(
+    (h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length))
+  );
+  const sep = colWidths.map((w) => "-".repeat(w)).join("  ");
+  const headerLine = headers.map((h, i) => h.padEnd(colWidths[i])).join("  ");
+  const dataLines = rows.map(
+    (row) => row.map((cell, i) => (cell ?? "").padEnd(colWidths[i])).join("  ")
+  );
+  return [headerLine, sep, ...dataLines].join("\n") + "\n";
+}
+function formatModuleList(modules, format, filterTags) {
+  if (format === "table") {
+    if (modules.length === 0 && filterTags && filterTags.length > 0) {
+      process.stdout.write(
+        `No modules found matching tags: ${filterTags.join(", ")}.
+`
+      );
+      return;
+    }
+    if (modules.length === 0) {
+      process.stdout.write("No modules found.\n");
+      return;
+    }
+    const headers = ["ID", "Description", "Tags"];
+    const rows = modules.map((m) => [
+      m.id,
+      truncate(m.description, 80),
+      (m.tags ?? []).join(", ")
+    ]);
+    process.stdout.write(formatTable(headers, rows));
+  } else if (format === "json") {
+    const result = modules.map((m) => ({
+      id: m.id,
+      description: m.description,
+      tags: m.tags ?? []
+    }));
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+}
+function annotationsToDict(annotations) {
+  if (!annotations) return null;
+  if (typeof annotations !== "object" || Array.isArray(annotations)) return null;
+  const result = {};
+  for (const [k, v] of Object.entries(annotations)) {
+    if (v !== null && v !== void 0 && v !== false && v !== 0 && !(Array.isArray(v) && v.length === 0)) {
+      result[k] = v;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+function formatModuleDetail(moduleDef, format) {
+  if (format === "table") {
+    process.stdout.write(`
+Module: ${moduleDef.id}
+`);
+    process.stdout.write(`
+Description:
+  ${moduleDef.description}
+`);
+    if (moduleDef.inputSchema && Object.keys(moduleDef.inputSchema).length > 0) {
+      process.stdout.write("\nInput Schema:\n");
+      process.stdout.write(JSON.stringify(moduleDef.inputSchema, null, 2) + "\n");
+    }
+    if (moduleDef.outputSchema && Object.keys(moduleDef.outputSchema).length > 0) {
+      process.stdout.write("\nOutput Schema:\n");
+      process.stdout.write(JSON.stringify(moduleDef.outputSchema, null, 2) + "\n");
+    }
+    const annDict = annotationsToDict(
+      moduleDef.annotations
+    );
+    if (annDict) {
+      process.stdout.write("\nAnnotations:\n");
+      for (const [k, v] of Object.entries(annDict)) {
+        process.stdout.write(`  ${k}: ${v}
+`);
+      }
+    }
+    const metadata = moduleDef.metadata;
+    if (metadata) {
+      const xFields = {};
+      for (const [k, v] of Object.entries(metadata)) {
+        if (k.startsWith("x-") || k.startsWith("x_")) {
+          xFields[k] = v;
+        }
+      }
+      if (Object.keys(xFields).length > 0) {
+        process.stdout.write("\nExtension Metadata:\n");
+        for (const [k, v] of Object.entries(xFields)) {
+          process.stdout.write(`  ${k}: ${v}
+`);
+        }
+      }
+    }
+    const tags = moduleDef.tags ?? [];
+    if (tags.length > 0) {
+      process.stdout.write(`
+Tags: ${tags.join(", ")}
+`);
+    }
+  } else if (format === "json") {
+    const result = {
+      id: moduleDef.id,
+      description: moduleDef.description
+    };
+    if (moduleDef.inputSchema) result.input_schema = moduleDef.inputSchema;
+    if (moduleDef.outputSchema) result.output_schema = moduleDef.outputSchema;
+    const annDict = annotationsToDict(
+      moduleDef.annotations
+    );
+    if (annDict) result.annotations = annDict;
+    const tags = moduleDef.tags ?? [];
+    if (tags.length > 0) result.tags = tags;
+    const metadata = moduleDef.metadata;
+    if (metadata) {
+      for (const [k, v] of Object.entries(metadata)) {
+        if (k.startsWith("x-") || k.startsWith("x_")) {
+          result[k] = v;
+        }
+      }
+    }
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  }
+}
+function formatExecResult(result, format) {
+  if (result === null || result === void 0) {
+    return;
+  }
+  const effective = resolveFormat(format);
+  if (effective === "table" && typeof result === "object" && !Array.isArray(result)) {
+    const entries = Object.entries(result);
+    const headers = ["Key", "Value"];
+    const rows = entries.map(([k, v]) => [String(k), String(v)]);
+    process.stdout.write(formatTable(headers, rows));
+  } else if (typeof result === "object") {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+  } else if (typeof result === "string") {
+    process.stdout.write(result + "\n");
+  } else {
+    process.stdout.write(String(result) + "\n");
+  }
+}
+
+// src/logger.ts
+init_esm_shims();
+var LEVELS = { DEBUG: 0, INFO: 1, WARNING: 2, ERROR: 3 };
+var currentLevel = "WARNING";
+function setLogLevel(level) {
+  const upper = level.toUpperCase();
+  if (upper in LEVELS) {
+    currentLevel = upper;
+  }
+}
+function getLogLevel() {
+  return currentLevel;
+}
+function shouldLog(level) {
+  return LEVELS[level] >= LEVELS[currentLevel];
+}
+function debug(message) {
+  if (shouldLog("DEBUG")) process.stderr.write(`DEBUG: ${message}
+`);
+}
+function info(message) {
+  if (shouldLog("INFO")) process.stderr.write(`INFO: ${message}
+`);
+}
+function warn(message) {
+  if (shouldLog("WARNING")) process.stderr.write(`WARNING: ${message}
+`);
+}
+function error(message) {
+  if (shouldLog("ERROR")) process.stderr.write(`ERROR: ${message}
+`);
+}
+
+// src/main.ts
+var __dirname2 = path4.dirname(fileURLToPath2(import.meta.url));
+var pkg = JSON.parse(readFileSync(path4.resolve(__dirname2, "../package.json"), "utf-8"));
+var VERSION = pkg.version;
+function createCli(extensionsDir, progName) {
+  const resolvedProgName = progName ?? path4.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;
+  return program;
+}
+function main(progName) {
+  const program = createCli(void 0, progName);
+  try {
+    program.parse(process.argv);
+  } catch (error2) {
+    if (error2 instanceof CommanderError) {
+      process.exit(error2.exitCode);
+    }
+    const code = exitCodeForError(error2);
+    if (error2 instanceof Error) {
+      process.stderr.write(`Error: ${error2.message}
+`);
+    }
+    process.exit(code);
+  }
+}
+function buildModuleCommand(moduleDef, executor) {
+  const moduleId = moduleDef.id;
+  let resolvedSchema = {};
+  let schemaOptions = [];
+  const inputSchema = moduleDef.inputSchema;
+  if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
+    try {
+      resolvedSchema = resolveRefs(inputSchema, 32, moduleId);
+    } catch {
+      resolvedSchema = inputSchema;
+    }
+    schemaOptions = schemaToCliOptions(resolvedSchema);
+  }
+  const cmd = new Command(moduleId).description(moduleDef.description);
+  cmd.option("--input <source>", "Read input from STDIN ('-')");
+  cmd.option("-y, --yes", "Bypass approval prompts", false);
+  cmd.option("--large-input", "Allow STDIN input larger than 10MB", false);
+  cmd.option("--format <format>", "Output format (json|table)");
+  cmd.option("--sandbox", "Run module in subprocess sandbox", false);
+  for (const opt of schemaOptions) {
+    if (opt.parseArg) {
+      cmd.option(opt.flags, opt.description, opt.parseArg, opt.defaultValue);
+    } else {
+      cmd.option(opt.flags, opt.description, opt.defaultValue);
+    }
+  }
+  cmd.action(async (options) => {
+    const stdinFlag = options.input;
+    const autoApprove = options.yes;
+    const largeInput = options.largeInput;
+    const outputFormat = options.format;
+    const sandboxEnabled = options.sandbox;
+    const schemaKwargs = {};
+    const builtinKeys = /* @__PURE__ */ new Set(["input", "yes", "largeInput", "format", "sandbox"]);
+    for (const [k, v] of Object.entries(options)) {
+      if (!builtinKeys.has(k)) {
+        schemaKwargs[k] = v;
+      }
+    }
+    try {
+      const merged = await collectInput(stdinFlag, schemaKwargs, largeInput);
+      const reconverted = reconvertEnumValues(merged, schemaOptions);
+      await checkApproval(moduleDef, autoApprove);
+      const { Sandbox: Sandbox2 } = await Promise.resolve().then(() => (init_security(), security_exports));
+      const sandbox = new Sandbox2(sandboxEnabled);
+      const startTime = performance.now();
+      const result = await sandbox.execute(moduleId, reconverted, executor);
+      const durationMs = Math.round(performance.now() - startTime);
+      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+      const auditLogger = getAuditLogger2();
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, reconverted, "success", 0, durationMs);
+      }
+      formatExecResult(result, outputFormat);
+    } catch (err) {
+      const { getAuditLogger: getAuditLogger2 } = await Promise.resolve().then(() => (init_audit(), audit_exports));
+      const auditLogger = getAuditLogger2();
+      const code = exitCodeForError(err);
+      if (auditLogger) {
+        auditLogger.logExecution(moduleId, {}, "error", code, 0);
+      }
+      if (err instanceof Error) {
+        process.stderr.write(`Error: ${err.message}
+`);
+      }
+      process.exit(code);
+    }
+  });
+  return cmd;
+}
+function validateModuleId(moduleId) {
+  if (moduleId.length > 128) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'. Maximum length is 128 characters.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+  if (!/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/.test(moduleId)) {
+    process.stderr.write(
+      `Error: Invalid module ID format: '${moduleId}'.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+}
+async function collectInput(stdinFlag, cliKwargs = {}, largeInput) {
+  const cliKwargsNonNull = {};
+  for (const [k, v] of Object.entries(cliKwargs)) {
+    if (v !== null && v !== void 0) {
+      cliKwargsNonNull[k] = v;
+    }
+  }
+  if (!stdinFlag) {
+    return cliKwargsNonNull;
+  }
+  if (stdinFlag === "-") {
+    const raw = await readStdin();
+    const rawSize = Buffer.byteLength(raw, "utf-8");
+    if (rawSize > 10485760 && !largeInput) {
+      process.stderr.write(
+        "Error: STDIN input exceeds 10MB limit. Use --large-input to override.\n"
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    if (!raw) {
+      return cliKwargsNonNull;
+    }
+    let stdinData;
+    try {
+      stdinData = JSON.parse(raw);
+    } catch {
+      process.stderr.write(
+        "Error: STDIN does not contain valid JSON.\n"
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    if (typeof stdinData !== "object" || stdinData === null || Array.isArray(stdinData)) {
+      process.stderr.write(
+        `Error: STDIN JSON must be an object, got ${Array.isArray(stdinData) ? "array" : typeof stdinData}.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    return { ...stdinData, ...cliKwargsNonNull };
+  }
+  return cliKwargsNonNull;
+}
+function readStdin() {
+  return new Promise((resolve3, reject) => {
+    const chunks = [];
+    const onData = (chunk) => chunks.push(chunk);
+    const onEnd = () => {
+      cleanup();
+      resolve3(Buffer.concat(chunks).toString("utf-8"));
+    };
+    const onError = (err) => {
+      cleanup();
+      reject(err);
+    };
+    const cleanup = () => {
+      process.stdin.removeListener("data", onData);
+      process.stdin.removeListener("end", onEnd);
+      process.stdin.removeListener("error", onError);
+    };
+    process.stdin.on("data", onData);
+    process.stdin.on("end", onEnd);
+    process.stdin.on("error", onError);
+    process.stdin.resume();
+  });
+}
+function reconvertEnumValues(kwargs, options) {
+  const result = { ...kwargs };
+  for (const opt of options) {
+    if (!opt.enumOriginalTypes) continue;
+    const paramName = opt.name;
+    if (!(paramName in result) || result[paramName] === null || result[paramName] === void 0) {
+      continue;
+    }
+    const strVal = String(result[paramName]);
+    const origType = opt.enumOriginalTypes[strVal];
+    if (origType === "int") {
+      result[paramName] = parseInt(strVal, 10);
+    } else if (origType === "float") {
+      result[paramName] = parseFloat(strVal);
+    } else if (origType === "bool") {
+      result[paramName] = strVal.toLowerCase() === "true";
+    }
+  }
+  return result;
+}
+
+// src/cli.ts
+init_esm_shims();
+var LazyModuleGroup = class {
+  registry;
+  executor;
+  commandCache = /* @__PURE__ */ new Map();
+  constructor(registry, executor) {
+    this.registry = registry;
+    this.executor = executor;
+  }
+  /**
+   * List all available command names from the Registry.
+   *
+   * TODO: Implement registry enumeration.
+   */
+  listCommands() {
+    return this.registry.listModules().map((m) => m.id);
+  }
+  /**
+   * Get or lazily build a Commander Command for the given module.
+   *
+   * TODO: Implement lazy command construction with schema-based options.
+   */
+  getCommand(cmdName) {
+    if (this.commandCache.has(cmdName)) {
+      return this.commandCache.get(cmdName);
+    }
+    const moduleDef = this.registry.getModule(cmdName);
+    if (!moduleDef) {
+      return null;
+    }
+    const cmd = buildModuleCommand(moduleDef, this.executor);
+    this.commandCache.set(cmdName, cmd);
+    return cmd;
+  }
+};
+
+// src/config.ts
+init_esm_shims();
+import * as fs3 from "fs";
+import yaml from "js-yaml";
+var DEFAULTS = {
+  "extensions.root": "./extensions",
+  "logging.level": "WARNING",
+  "sandbox.enabled": false,
+  "cli.stdin_buffer_limit": 10485760,
+  "cli.auto_approve": false
+};
+var ConfigResolver = class {
+  cliFlags;
+  configPath;
+  fileCache = null;
+  fileCacheLoaded = false;
+  constructor(cliFlags, configPath) {
+    this.cliFlags = cliFlags ?? {};
+    this.configPath = configPath ?? "apcore.yaml";
+  }
+  /**
+   * Resolve a single configuration key across all four tiers.
+   */
+  resolve(key, cliFlag, envVar) {
+    const flagKey = cliFlag ?? key;
+    if (flagKey in this.cliFlags) {
+      const value = this.cliFlags[flagKey];
+      if (value !== null && value !== void 0) {
+        return value;
+      }
+    }
+    if (envVar) {
+      const envValue = process.env[envVar];
+      if (envValue !== void 0 && envValue !== "") {
+        return envValue;
+      }
+    }
+    const fileValue = this.resolveFromFile(key);
+    if (fileValue !== void 0) {
+      return fileValue;
+    }
+    return DEFAULTS[key];
+  }
+  /**
+   * Load a value from the config file using a dot-separated key path.
+   */
+  resolveFromFile(key) {
+    if (!this.fileCacheLoaded) {
+      this.fileCache = this.loadConfigFile();
+      this.fileCacheLoaded = true;
+    }
+    if (this.fileCache === null) {
+      return void 0;
+    }
+    return this.fileCache[key];
+  }
+  /**
+   * Load and flatten a YAML config file.
+   */
+  loadConfigFile() {
+    let content;
+    try {
+      content = fs3.readFileSync(this.configPath, "utf-8");
+    } catch (err) {
+      if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+        return null;
+      }
+      console.warn(
+        `Configuration file '${this.configPath}' is malformed, using defaults.`
+      );
+      return null;
+    }
+    let parsed;
+    try {
+      parsed = yaml.load(content);
+    } catch {
+      console.warn(
+        `Configuration file '${this.configPath}' is malformed, using defaults.`
+      );
+      return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      console.warn(
+        `Configuration file '${this.configPath}' is malformed, using defaults.`
+      );
+      return null;
+    }
+    return this.flattenDict(parsed);
+  }
+  /**
+   * Flatten nested dict to dot-notation keys.
+   */
+  flattenDict(d, prefix = "") {
+    const result = {};
+    for (const [key, value] of Object.entries(d)) {
+      const fullKey = prefix ? `${prefix}.${key}` : key;
+      if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        Object.assign(
+          result,
+          this.flattenDict(value, fullKey)
+        );
+      } else {
+        result[fullKey] = value;
+      }
+    }
+    return result;
+  }
+};
+
+// src/discovery.ts
+init_esm_shims();
+init_errors();
+import { Command as Command2 } from "commander";
+var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
+function validateTag(tag) {
+  if (!TAG_PATTERN.test(tag)) {
+    process.stderr.write(
+      `Error: Invalid tag format: '${tag}'. Tags must match [a-z][a-z0-9_-]*.
+`
+    );
+    process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+  }
+}
+function collectTag(value, previous) {
+  return previous.concat([value]);
+}
+function registerDiscoveryCommands(cli, registry) {
+  const listCmd = new Command2("list").description("List available modules in the registry.").option("--tag <tag>", "Filter modules by tag (AND logic). Repeatable.", collectTag, []).option("--format <format>", "Output format.", void 0).action((opts) => {
+    for (const t of opts.tag) {
+      validateTag(t);
+    }
+    const modules = [];
+    for (const m of registry.listModules()) {
+      modules.push(m);
+    }
+    let filtered = modules;
+    if (opts.tag.length > 0) {
+      const filterTags = new Set(opts.tag);
+      filtered = modules.filter((m) => {
+        const mTags = m.tags ?? [];
+        return [...filterTags].every((t) => mTags.includes(t));
+      });
+    }
+    const fmt = resolveFormat(opts.format);
+    formatModuleList(filtered, fmt, opts.tag.length > 0 ? opts.tag : void 0);
+  });
+  cli.addCommand(listCmd);
+  const describeCmd = new Command2("describe").description("Show metadata, schema, and annotations for a module.").argument("<module-id>", "Module ID to describe").option("--format <format>", "Output format.", void 0).action((moduleId, opts) => {
+    validateModuleId(moduleId);
+    const moduleDef = registry.getModule(moduleId);
+    if (!moduleDef) {
+      process.stderr.write(
+        `Error: Module '${moduleId}' not found.
+`
+      );
+      process.exit(EXIT_CODES.MODULE_NOT_FOUND);
+    }
+    const fmt = resolveFormat(opts.format);
+    formatModuleDetail(moduleDef, fmt);
+  });
+  cli.addCommand(describeCmd);
+}
+
+// src/shell.ts
+init_esm_shims();
+init_errors();
+import { readFileSync as readFileSync3 } from "fs";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import * as path5 from "path";
+import { Command as Command3 } from "commander";
+var __dirname3 = path5.dirname(fileURLToPath3(import.meta.url));
+var pkg2 = JSON.parse(readFileSync3(path5.resolve(__dirname3, "../package.json"), "utf-8"));
+var SHELL_VERSION = pkg2.version;
+function makeFunctionName(progName) {
+  return "_" + progName.replace(/[^a-zA-Z0-9]/g, "_");
+}
+function shellQuote(s) {
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+function generateBashCompletion(progName) {
+  const fn = makeFunctionName(progName);
+  const quoted = shellQuote(progName);
+  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
+  return `${fn}() {
+    local cur prev opts
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+
+    if [[ \${COMP_CWORD} -eq 1 ]]; then
+        opts="list describe completion man"
+        COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
+        return 0
+    fi
+
+    if [[ "\${COMP_WORDS[1]}" == "exec" && \${COMP_CWORD} -eq 2 ]]; then
+        local modules=$(${moduleListCmd})
+        COMPREPLY=( $(compgen -W "\${modules}" -- \${cur}) )
+        return 0
+    fi
+}
+complete -F ${fn} ${quoted}
+`;
+}
+function generateZshCompletion(progName) {
+  const fn = makeFunctionName(progName);
+  const quoted = shellQuote(progName);
+  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e "process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})" 2>/dev/null`;
+  return `#compdef ${progName}
+
+${fn}() {
+    local -a commands
+    commands=(
+        'list:List available modules'
+        'describe:Show module metadata and schema'
+        'completion:Generate shell completion script'
+        'man:Generate man page'
+    )
+
+    _arguments -C \\
+        '1:command:->command' \\
+        '*::arg:->args'
+
+    case "$state" in
+        command)
+            _describe -t commands '${progName} commands' commands
+            ;;
+        args)
+            case "\${words[1]}" in
+                exec)
+                    local modules
+                    modules=($(${moduleListCmd}))
+                    compadd -a modules
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+compdef ${fn} ${quoted}
+`;
+}
+function generateFishCompletion(progName) {
+  const quoted = shellQuote(progName);
+  const moduleListCmd = `${quoted} list --format json 2>/dev/null | node -e \\"process.stdin.on('data',d=>{JSON.parse(d).forEach(m=>console.log(m.id))})\\" 2>/dev/null`;
+  return `# Fish completions for ${progName}
+complete -c ${quoted} -n "__fish_use_subcommand" -a list -d "List available modules"
+complete -c ${quoted} -n "__fish_use_subcommand" -a describe -d "Show module metadata and schema"
+complete -c ${quoted} -n "__fish_use_subcommand" -a completion -d "Generate shell completion script"
+complete -c ${quoted} -n "__fish_use_subcommand" -a man -d "Generate man page"
+
+complete -c ${quoted} -n "__fish_seen_subcommand_from exec" -a "(${moduleListCmd})"
+`;
+}
+function buildSynopsis(command, progName, commandName) {
+  if (!command) {
+    return `\\fB${progName} ${commandName}\\fR [OPTIONS]`;
+  }
+  const parts = [`\\fB${progName} ${commandName}\\fR`];
+  for (const opt of command.options) {
+    const flag = opt.long ?? opt.short ?? "";
+    if (opt.isBoolean?.()) {
+      parts.push(`[${flag}]`);
+    } else if (opt.required) {
+      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
+      parts.push(`${flag} \\fI${typeName}\\fR`);
+    } else {
+      const typeName = (opt.argChoices ? "CHOICE" : "VALUE").toUpperCase();
+      parts.push(`[${flag} \\fI${typeName}\\fR]`);
+    }
+  }
+  for (const arg of command.registeredArguments ?? []) {
+    const meta = arg.name().toUpperCase();
+    if (arg.required) {
+      parts.push(`\\fI${meta}\\fR`);
+    } else {
+      parts.push(`[\\fI${meta}\\fR]`);
+    }
+  }
+  return parts.join(" ");
+}
+function generateManPage(commandName, command, progName, version = SHELL_VERSION) {
+  const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const title = `${progName}-${commandName}`.toUpperCase();
+  const pkgLabel = `${progName} ${version}`;
+  const manualLabel = `${progName} Manual`;
+  const sections = [];
+  sections.push(`.TH "${title}" "1" "${today}" "${pkgLabel}" "${manualLabel}"`);
+  sections.push(".SH NAME");
+  const desc = command?.description() ?? commandName;
+  const nameDesc = desc.split("\n")[0].replace(/\.$/, "");
+  sections.push(`${progName}-${commandName} \\- ${nameDesc}`);
+  sections.push(".SH SYNOPSIS");
+  sections.push(buildSynopsis(command, progName, commandName));
+  if (command?.description()) {
+    sections.push(".SH DESCRIPTION");
+    sections.push(
+      command.description().replace(/\\/g, "\\\\").replace(/-/g, "\\-")
+    );
+  }
+  if (command && command.options.length > 0) {
+    sections.push(".SH OPTIONS");
+    for (const opt of command.options) {
+      const flag = [opt.short, opt.long].filter(Boolean).join(", ");
+      sections.push(".TP");
+      if (opt.isBoolean?.()) {
+        sections.push(`\\fB${flag}\\fR`);
+      } else {
+        sections.push(`\\fB${flag}\\fR \\fIVALUE\\fR`);
+      }
+      if (opt.description) {
+        sections.push(opt.description);
+      }
+      if (opt.defaultValue !== void 0 && !opt.isBoolean?.()) {
+        sections.push(`Default: ${opt.defaultValue}.`);
+      }
+    }
+  }
+  sections.push(".SH ENVIRONMENT");
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_EXTENSIONS_ROOT\\fR");
+  sections.push(
+    "Path to the apcore extensions directory. Overrides the default \\fI./extensions\\fR."
+  );
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_CLI_AUTO_APPROVE\\fR");
+  sections.push(
+    "Set to \\fB1\\fR to bypass approval prompts for modules that require human-in-the-loop confirmation."
+  );
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_CLI_LOGGING_LEVEL\\fR");
+  sections.push(
+    "CLI-specific logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Takes priority over \\fBAPCORE_LOGGING_LEVEL\\fR. Default: WARNING."
+  );
+  sections.push(".TP");
+  sections.push("\\fBAPCORE_LOGGING_LEVEL\\fR");
+  sections.push(
+    "Global apcore logging verbosity. One of: DEBUG, INFO, WARNING, ERROR. Used as fallback when \\fBAPCORE_CLI_LOGGING_LEVEL\\fR is not set. Default: WARNING."
+  );
+  sections.push(".SH EXIT CODES");
+  const exitCodes = [
+    ["0", "Success."],
+    ["1", "Module execution error."],
+    ["2", "Invalid CLI input or missing argument."],
+    ["44", "Module not found, disabled, or failed to load."],
+    ["45", "Input failed JSON Schema validation."],
+    [
+      "46",
+      "Approval denied, timed out, or no interactive terminal available."
+    ],
+    [
+      "47",
+      "Configuration error (extensions directory not found or unreadable)."
+    ],
+    ["48", "Schema contains a circular \\fB$ref\\fR."],
+    ["77", "ACL denied \u2014 insufficient permissions for this module."],
+    ["130", "Execution cancelled by user (SIGINT / Ctrl\\-C)."]
+  ];
+  for (const [code, meaning] of exitCodes) {
+    sections.push(`.TP
+\\fB${code}\\fR
+${meaning}`);
+  }
+  sections.push(".SH SEE ALSO");
+  sections.push(
+    [
+      `\\fB${progName}\\fR(1)`,
+      `\\fB${progName}\\-list\\fR(1)`,
+      `\\fB${progName}\\-describe\\fR(1)`,
+      `\\fB${progName}\\-completion\\fR(1)`
+    ].join(", ")
+  );
+  return sections.join("\n");
+}
+function registerShellCommands(cli, progName = "apcore-cli") {
+  const completionCmd = new Command3("completion").description(
+    "Generate a shell completion script and print it to stdout."
+  ).argument("<shell>", "Shell type: bash, zsh, or fish").action((shell) => {
+    const validShells = ["bash", "zsh", "fish"];
+    if (!validShells.includes(shell)) {
+      process.stderr.write(
+        `Error: Unknown shell '${shell}'. Expected: bash, zsh, or fish.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    const resolved = cli.name() || progName;
+    const generators = {
+      bash: () => generateBashCompletion(resolved),
+      zsh: () => generateZshCompletion(resolved),
+      fish: () => generateFishCompletion(resolved)
+    };
+    process.stdout.write(generators[shell]());
+  });
+  cli.addCommand(completionCmd);
+  const manCmd = new Command3("man").description("Generate a roff man page for COMMAND and print it to stdout.").argument("<command>", "Command to generate man page for").action((commandName) => {
+    const knownBuiltins = /* @__PURE__ */ new Set(["list", "describe", "completion", "man"]);
+    const cmd = cli.commands.find((c) => c.name() === commandName) ?? null;
+    if (!cmd && !knownBuiltins.has(commandName)) {
+      process.stderr.write(
+        `Error: Unknown command '${commandName}'.
+`
+      );
+      process.exit(EXIT_CODES.INVALID_CLI_INPUT);
+    }
+    const resolved = cli.name() || progName;
+    const roff = generateManPage(commandName, cmd, resolved);
+    process.stdout.write(roff);
+  });
+  cli.addCommand(manCmd);
+}
+
+// src/index.ts
+init_errors();
+init_security();
+export {
+  ApprovalDeniedError,
+  ApprovalTimeoutError,
+  AuditLogger,
+  AuthProvider,
+  AuthenticationError,
+  ConfigDecryptionError,
+  ConfigEncryptor,
+  ConfigResolver,
+  DEFAULTS,
+  EXIT_CODES,
+  LazyModuleGroup,
+  ModuleExecutionError,
+  ModuleNotFoundError,
+  Sandbox,
+  SchemaValidationError,
+  buildModuleCommand,
+  checkApproval,
+  collectInput,
+  createCli,
+  debug,
+  error,
+  exitCodeForError,
+  extractHelp,
+  formatExecResult,
+  formatModuleDetail,
+  formatModuleList,
+  getAuditLogger,
+  getLogLevel,
+  info,
+  main,
+  mapType,
+  reconvertEnumValues,
+  registerDiscoveryCommands,
+  registerShellCommands,
+  resolveFormat,
+  resolveRefs,
+  schemaToCliOptions,
+  setAuditLogger,
+  setLogLevel,
+  truncate,
+  validateModuleId,
+  warn
+};
+//# sourceMappingURL=index.js.map