apcore-cli 0.2.0 → 0.3.0

package/dist/src/index.js

@@ -137,9 +137,9 @@ __export(audit_exports, {
   setAuditLogger: () => setAuditLogger
 });
 import * as crypto from "crypto";
-import * as fs from "fs";
+import * as fs2 from "fs";
 import * as os from "os";
-import * as path2 from "path";
+import * as path3 from "path";
 function setAuditLogger(auditLogger) {
   _auditLogger = auditLogger;
 }
@@ -153,19 +153,19 @@ var init_audit = __esm({
     init_esm_shims();
     _auditLogger = null;
     AuditLogger = class _AuditLogger {
-      static DEFAULT_PATH = path2.join(
+      static DEFAULT_PATH = path3.join(
         os.homedir(),
         ".apcore-cli",
         "audit.jsonl"
       );
       logPath;
-      constructor(path6) {
-        this.logPath = path6 ?? _AuditLogger.DEFAULT_PATH;
+      constructor(path7) {
+        this.logPath = path7 ?? _AuditLogger.DEFAULT_PATH;
         this.ensureDirectory();
       }
       ensureDirectory() {
         try {
-          fs.mkdirSync(path2.dirname(this.logPath), { recursive: true });
+          fs2.mkdirSync(path3.dirname(this.logPath), { recursive: true });
         } catch {
         }
       }
@@ -180,7 +180,7 @@ var init_audit = __esm({
           duration_ms: durationMs
         };
         try {
-          fs.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
+          fs2.appendFileSync(this.logPath, JSON.stringify(entry) + "\n");
         } catch (err) {
           console.warn(`Could not write audit log: ${err}`);
         }
@@ -381,9 +381,9 @@ var init_auth = __esm({
 
 // src/security/sandbox.ts
 import * as child_process from "child_process";
-import * as fs2 from "fs";
+import * as fs3 from "fs";
 import * as os3 from "os";
-import * as path3 from "path";
+import * as path4 from "path";
 var Sandbox;
 var init_sandbox = __esm({
   "src/security/sandbox.ts"() {
@@ -416,8 +416,8 @@ var init_sandbox = __esm({
             env[key] = value;
           }
         }
-        const tmpDir = fs2.mkdtempSync(
-          path3.join(os3.tmpdir(), "apcore_sandbox_")
+        const tmpDir = fs3.mkdtempSync(
+          path4.join(os3.tmpdir(), "apcore_sandbox_")
         );
         try {
           env.HOME = tmpDir;
@@ -455,7 +455,7 @@ var init_sandbox = __esm({
           );
         } finally {
           try {
-            fs2.rmSync(tmpDir, { recursive: true, force: true });
+            fs3.rmSync(tmpDir, { recursive: true, force: true });
           } catch {
           }
         }
@@ -493,7 +493,7 @@ init_esm_shims();
 init_errors();
 import { readFileSync } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
-import * as path4 from "path";
+import * as path5 from "path";
 import { Command, CommanderError } from "commander";
 
 // src/ref-resolver.ts
@@ -663,7 +663,7 @@ function mapType(propName, propSchema) {
   }
   return typeMap[schemaType] ?? "string";
 }
-function extractHelp(propSchema) {
+function extractHelp(propSchema, maxLength = 1e3) {
   let text = propSchema["x-llm-description"];
   if (!text) {
     text = propSchema.description;
@@ -671,13 +671,13 @@ function extractHelp(propSchema) {
   if (!text) {
     return void 0;
   }
-  if (text.length > 200) {
-    return text.slice(0, 197) + "...";
+  if (maxLength > 0 && text.length > maxLength) {
+    return text.slice(0, maxLength - 3) + "...";
   }
   return text;
 }
 var RESERVED_NAMES = /* @__PURE__ */ new Set(["input", "yes", "large_input", "format", "sandbox"]);
-function schemaToCliOptions(schema) {
+function schemaToCliOptions(schema, maxHelpLength = 1e3) {
   const properties = schema.properties ?? {};
   const requiredList = schema.required ?? [];
   const options = [];
@@ -701,7 +701,7 @@ function schemaToCliOptions(schema) {
     }
     const typeResult = mapType(propName, propSchema);
     const isRequired = requiredList.includes(propName);
-    const helpBase = extractHelp(propSchema);
+    const helpBase = extractHelp(propSchema, maxHelpLength);
     const helpText = isRequired ? (helpBase ? helpBase + " " : "") + "[required]" : helpBase ?? "";
     const defaultValue = propSchema.default;
     if (typeResult === BOOLEAN_FLAG) {
@@ -884,12 +884,12 @@ 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 sep2 = 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";
+  return [headerLine, sep2, ...dataLines].join("\n") + "\n";
 }
 function formatModuleList(modules, format, filterTags) {
   if (format === "table") {
@@ -1056,18 +1056,209 @@ function error(message) {
 `);
 }
 
+// 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();
+function getDisplay(descriptor) {
+  const metadata = descriptor.metadata ?? {};
+  const display = metadata.display;
+  if (display && typeof display === "object" && !Array.isArray(display)) {
+    return display;
+  }
+  return {};
+}
+function getCliDisplayFields(descriptor) {
+  const display = getDisplay(descriptor);
+  const cli = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+  const name = cli.alias ?? display.alias ?? descriptor.id;
+  const desc = cli.description ?? descriptor.description;
+  const tags = display.tags ?? descriptor.tags ?? [];
+  return [name, desc, tags];
+}
+
 // src/main.ts
-var __dirname2 = path4.dirname(fileURLToPath2(import.meta.url));
-var pkg = JSON.parse(readFileSync(path4.resolve(__dirname2, "../package.json"), "utf-8"));
+var __dirname2 = path5.dirname(fileURLToPath2(import.meta.url));
+var pkg = JSON.parse(readFileSync(path5.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 resolvedProgName = progName ?? path5.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 {
@@ -1084,10 +1275,14 @@ function main(progName) {
     process.exit(code);
   }
 }
-function buildModuleCommand(moduleDef, executor) {
+function buildModuleCommand(moduleDef, executor, helpTextMaxLength = 1e3, cmdName) {
   const moduleId = moduleDef.id;
   let resolvedSchema = {};
   let schemaOptions = [];
+  const display = getDisplay(moduleDef);
+  const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+  const effectiveCmdName = cmdName ?? cliDisplay.alias ?? moduleId;
+  const cmdHelp = cliDisplay.description ?? moduleDef.description;
   const inputSchema = moduleDef.inputSchema;
   if (inputSchema && typeof inputSchema === "object" && inputSchema.properties) {
     try {
@@ -1095,9 +1290,9 @@ function buildModuleCommand(moduleDef, executor) {
     } catch {
       resolvedSchema = inputSchema;
     }
-    schemaOptions = schemaToCliOptions(resolvedSchema);
+    schemaOptions = schemaToCliOptions(resolvedSchema, helpTextMaxLength);
   }
-  const cmd = new Command(moduleId).description(moduleDef.description);
+  const cmd = new Command(effectiveCmdName).description(cmdHelp);
   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);
@@ -1258,51 +1453,270 @@ function reconvertEnumValues(kwargs, options) {
 
 // src/cli.ts
 init_esm_shims();
+import { Command as Command2 } from "commander";
+var BUILTIN_COMMANDS = ["completion", "describe", "exec", "init", "list", "man"];
 var LazyModuleGroup = class {
   registry;
   executor;
+  helpTextMaxLength;
   commandCache = /* @__PURE__ */ new Map();
-  constructor(registry, executor) {
+  /** alias -> canonical module_id (populated lazily) */
+  aliasMap = /* @__PURE__ */ new Map();
+  /** module_id -> descriptor cache (populated during alias map build) */
+  descriptorCache = /* @__PURE__ */ new Map();
+  aliasMapBuilt = false;
+  constructor(registry, executor, helpTextMaxLength = 1e3) {
     this.registry = registry;
     this.executor = executor;
+    this.helpTextMaxLength = helpTextMaxLength;
+  }
+  /**
+   * Build alias->module_id map from display overlay metadata.
+   */
+  buildAliasMap() {
+    if (this.aliasMapBuilt) {
+      return;
+    }
+    try {
+      for (const descriptor of this.registry.listModules()) {
+        const moduleId = descriptor.id;
+        this.descriptorCache.set(moduleId, descriptor);
+        const display = getDisplay(descriptor);
+        const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+        const cliAlias = cliDisplay.alias;
+        if (cliAlias && cliAlias !== moduleId) {
+          this.aliasMap.set(cliAlias, moduleId);
+        }
+      }
+      this.aliasMapBuilt = true;
+    } catch {
+      warn("Failed to build alias map from registry");
+    }
   }
   /**
    * List all available command names from the Registry.
-   *
-   * TODO: Implement registry enumeration.
    */
   listCommands() {
-    return this.registry.listModules().map((m) => m.id);
+    this.buildAliasMap();
+    const reverse = /* @__PURE__ */ new Map();
+    for (const [alias, moduleId] of this.aliasMap) {
+      reverse.set(moduleId, alias);
+    }
+    const moduleIds = this.registry.listModules().map((m) => m.id);
+    const names = moduleIds.map((mid) => reverse.get(mid) ?? mid);
+    return [...new Set(names)].sort();
   }
   /**
    * 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);
+    this.buildAliasMap();
+    const moduleId = this.aliasMap.get(cmdName) ?? cmdName;
+    let moduleDef = this.descriptorCache.get(moduleId);
+    if (!moduleDef) {
+      moduleDef = this.registry.getModule(moduleId) ?? void 0;
+    }
     if (!moduleDef) {
       return null;
     }
-    const cmd = buildModuleCommand(moduleDef, this.executor);
+    const cmd = buildModuleCommand(moduleDef, this.executor, this.helpTextMaxLength, cmdName);
     this.commandCache.set(cmdName, cmd);
     return cmd;
   }
 };
+var LazyGroup = class {
+  members;
+  _executor;
+  _helpTextMaxLength;
+  _cmdCache = /* @__PURE__ */ new Map();
+  command;
+  constructor(members, executor, name, helpTextMaxLength = 1e3) {
+    this.members = members;
+    this._executor = executor;
+    this._helpTextMaxLength = helpTextMaxLength;
+    this.command = new Command2(name).description(`${name} commands`);
+    for (const [cmdName, [, descriptor]] of this.members) {
+      const cmd = buildModuleCommand(
+        descriptor,
+        this._executor,
+        this._helpTextMaxLength,
+        cmdName
+      );
+      this._cmdCache.set(cmdName, cmd);
+      this.command.addCommand(cmd);
+    }
+  }
+  listCommands() {
+    return [...this.members.keys()].sort();
+  }
+  getCommand(cmdName) {
+    if (this._cmdCache.has(cmdName)) {
+      return this._cmdCache.get(cmdName);
+    }
+    const entry = this.members.get(cmdName);
+    if (!entry) {
+      return null;
+    }
+    const [, descriptor] = entry;
+    const cmd = buildModuleCommand(
+      descriptor,
+      this._executor,
+      this._helpTextMaxLength,
+      cmdName
+    );
+    this._cmdCache.set(cmdName, cmd);
+    return cmd;
+  }
+};
+var GroupedModuleGroup = class _GroupedModuleGroup extends LazyModuleGroup {
+  /** groupName -> { cmdName -> [moduleId, descriptor] } */
+  groupMap = /* @__PURE__ */ new Map();
+  /** cmdName -> [moduleId, descriptor] for top-level (ungrouped) modules */
+  topLevelModules = /* @__PURE__ */ new Map();
+  /** Cached LazyGroup instances */
+  groupCache = /* @__PURE__ */ new Map();
+  groupMapBuilt = false;
+  /**
+   * Determine (groupName | null, commandName) for a module from its display overlay.
+   */
+  static resolveGroup(moduleId, descriptor) {
+    if (!moduleId) {
+      warn("Empty module_id encountered in resolveGroup");
+      return [null, ""];
+    }
+    const display = getDisplay(descriptor);
+    const cliDisplay = display.cli && typeof display.cli === "object" && !Array.isArray(display.cli) ? display.cli : {};
+    const explicitGroup = cliDisplay.group;
+    if (typeof explicitGroup === "string" && explicitGroup !== "") {
+      return [explicitGroup, cliDisplay.alias ?? moduleId];
+    }
+    if (explicitGroup === "") {
+      return [null, cliDisplay.alias ?? moduleId];
+    }
+    const cliName = cliDisplay.alias ?? moduleId;
+    if (cliName.includes(".")) {
+      const dotIdx = cliName.indexOf(".");
+      const group = cliName.substring(0, dotIdx);
+      const cmd = cliName.substring(dotIdx + 1);
+      return [group, cmd];
+    }
+    return [null, cliName];
+  }
+  /**
+   * Build the group map from registry modules.
+   */
+  buildGroupMap() {
+    if (this.groupMapBuilt) {
+      return;
+    }
+    try {
+      this.buildAliasMap();
+      for (const descriptor of this.registry.listModules()) {
+        const moduleId = descriptor.id;
+        const cached = this.descriptorCache.get(moduleId);
+        if (!cached) {
+          continue;
+        }
+        const [group, cmd] = _GroupedModuleGroup.resolveGroup(moduleId, cached);
+        if (group === null) {
+          this.topLevelModules.set(cmd, [moduleId, cached]);
+        } else if (!/^[a-z][a-z0-9_-]*$/.test(group)) {
+          warn(
+            `Module '${moduleId}': group name '${group}' is not shell-safe \u2014 treating as top-level.`
+          );
+          this.topLevelModules.set(cmd, [moduleId, cached]);
+        } else {
+          if (!this.groupMap.has(group)) {
+            this.groupMap.set(group, /* @__PURE__ */ new Map());
+          }
+          this.groupMap.get(group).set(cmd, [moduleId, cached]);
+        }
+      }
+      for (const groupName of this.groupMap.keys()) {
+        if (BUILTIN_COMMANDS.includes(groupName)) {
+          warn(
+            `Group name '${groupName}' collides with a built-in command and will be ignored`
+          );
+        }
+      }
+      this.groupMapBuilt = true;
+    } catch {
+      warn("Failed to build group map");
+    }
+  }
+  /**
+   * List all available command names: builtins + group names + top-level module names.
+   */
+  listCommands() {
+    this.buildGroupMap();
+    const groupNames = [...this.groupMap.keys()].filter(
+      (g) => !BUILTIN_COMMANDS.includes(g)
+    );
+    const topNames = [...this.topLevelModules.keys()];
+    return [.../* @__PURE__ */ new Set([...BUILTIN_COMMANDS, ...groupNames, ...topNames])].sort();
+  }
+  /**
+   * Get a command by name: check builtins -> group cache -> group map -> top-level modules.
+   */
+  getCommand(cmdName) {
+    this.buildGroupMap();
+    if (this.groupCache.has(cmdName)) {
+      return this.groupCache.get(cmdName).command;
+    }
+    if (this.groupMap.has(cmdName)) {
+      const lazyGrp = new LazyGroup(
+        this.groupMap.get(cmdName),
+        this.executor,
+        cmdName,
+        this.helpTextMaxLength
+      );
+      this.groupCache.set(cmdName, lazyGrp);
+      return lazyGrp.command;
+    }
+    if (this.topLevelModules.has(cmdName)) {
+      if (this.commandCache.has(cmdName)) {
+        return this.commandCache.get(cmdName);
+      }
+      const [, descriptor] = this.topLevelModules.get(cmdName);
+      const cmd = buildModuleCommand(
+        descriptor,
+        this.executor,
+        this.helpTextMaxLength,
+        cmdName
+      );
+      this.commandCache.set(cmdName, cmd);
+      return cmd;
+    }
+    return null;
+  }
+  /** Expose groupMap for testing. */
+  getGroupMap() {
+    return this.groupMap;
+  }
+  /** Expose topLevelModules for testing. */
+  getTopLevelModules() {
+    return this.topLevelModules;
+  }
+  /** Expose groupMapBuilt for testing. */
+  isGroupMapBuilt() {
+    return this.groupMapBuilt;
+  }
+};
 
 // src/config.ts
 init_esm_shims();
-import * as fs3 from "fs";
+import * as fs4 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
+  "cli.auto_approve": false,
+  "cli.help_text_max_length": 1e3
 };
 var ConfigResolver = class {
   cliFlags;
@@ -1355,7 +1769,7 @@ var ConfigResolver = class {
   loadConfigFile() {
     let content;
     try {
-      content = fs3.readFileSync(this.configPath, "utf-8");
+      content = fs4.readFileSync(this.configPath, "utf-8");
     } catch (err) {
       if (err instanceof Error && "code" in err && err.code === "ENOENT") {
         return null;
@@ -1405,7 +1819,7 @@ var ConfigResolver = class {
 // src/discovery.ts
 init_esm_shims();
 init_errors();
-import { Command as Command2 } from "commander";
+import { Command as Command3 } from "commander";
 var TAG_PATTERN = /^[a-z][a-z0-9_-]*$/;
 function validateTag(tag) {
   if (!TAG_PATTERN.test(tag)) {
@@ -1420,7 +1834,7 @@ 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) => {
+  const listCmd = new Command3("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);
     }
@@ -1440,7 +1854,7 @@ function registerDiscoveryCommands(cli, registry) {
     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) => {
+  const describeCmd = new Command3("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) {
@@ -1461,10 +1875,10 @@ 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"));
+import * as path6 from "path";
+import { Command as Command4 } from "commander";
+var __dirname3 = path6.dirname(fileURLToPath3(import.meta.url));
+var pkg2 = JSON.parse(readFileSync3(path6.resolve(__dirname3, "../package.json"), "utf-8"));
 var SHELL_VERSION = pkg2.version;
 function makeFunctionName(progName) {
   return "_" + progName.replace(/[^a-zA-Z0-9]/g, "_");
@@ -1476,6 +1890,18 @@ 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`;
+  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const ids=JSON.parse(m).map(x=>x.id);
+const g=new Set(),t=[];
+ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
+console.log([...g].sort().concat(t.sort()).join(' '))
+" 2>/dev/null`;
+  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const g=process.env._APCORE_GRP;
+JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
+" 2>/dev/null`;
   return `${fn}() {
     local cur prev opts
     COMPREPLY=()
@@ -1483,14 +1909,21 @@ function generateBashCompletion(progName) {
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
 
     if [[ \${COMP_CWORD} -eq 1 ]]; then
-        opts="list describe completion man"
-        COMPREPLY=( $(compgen -W "\${opts}" -- \${cur}) )
+        opts="completion describe exec init list man"
+        local groups_and_top=$(${groupsAndTopCmd})
+        COMPREPLY=( $(compgen -W "\${opts} \${groups_and_top}" -- \${cur}) )
         return 0
     fi
 
-    if [[ "\${COMP_WORDS[1]}" == "exec" && \${COMP_CWORD} -eq 2 ]]; then
-        local modules=$(${moduleListCmd})
-        COMPREPLY=( $(compgen -W "\${modules}" -- \${cur}) )
+    if [[ \${COMP_CWORD} -eq 2 ]]; then
+        if [[ "\${COMP_WORDS[1]}" == "exec" ]]; then
+            local modules=$(${moduleListCmd})
+            COMPREPLY=( $(compgen -W "\${modules}" -- \${cur}) )
+            return 0
+        fi
+        export _APCORE_GRP="\${COMP_WORDS[1]}"
+        local group_cmds=$(${groupCmdsCmd})
+        COMPREPLY=( $(compgen -W "\${group_cmds}" -- \${cur}) )
         return 0
     fi
 }
@@ -1501,6 +1934,18 @@ 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`;
+  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const ids=JSON.parse(m).map(x=>x.id);
+const g=new Set(),t=[];
+ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});
+console.log([...g].sort().concat(t.sort()).join(' '))
+" 2>/dev/null`;
+  const groupCmdsCmd = `${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const g=process.env._APCORE_GRP;
+JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
+" 2>/dev/null`;
   return `#compdef ${progName}
 
 ${fn}() {
@@ -1509,6 +1954,7 @@ ${fn}() {
         'list:List available modules'
         'describe:Show module metadata and schema'
         'completion:Generate shell completion script'
+        'init:Scaffolding commands'
         'man:Generate man page'
     )
 
@@ -1519,6 +1965,9 @@ ${fn}() {
     case "$state" in
         command)
             _describe -t commands '${progName} commands' commands
+            local -a groups_and_top
+            groups_and_top=($(${groupsAndTopCmd}))
+            compadd -a groups_and_top
             ;;
         args)
             case "\${words[1]}" in
@@ -1527,6 +1976,12 @@ ${fn}() {
                     modules=($(${moduleListCmd}))
                     compadd -a modules
                     ;;
+                *)
+                    export _APCORE_GRP="\${words[1]}"
+                    local -a group_cmds
+                    group_cmds=($(${groupCmdsCmd}))
+                    compadd -a group_cmds
+                    ;;
             esac
             ;;
     esac
@@ -1538,13 +1993,29 @@ 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`;
+  const groupsAndTopCmd = `${quoted} list --format json 2>/dev/null | node -e \\"const m=require('fs').readFileSync('/dev/stdin','utf8');const ids=JSON.parse(m).map(x=>x.id);const g=new Set(),t=[];ids.forEach(i=>{if(i.includes('.'))g.add(i.split('.')[0]);else t.push(i)});console.log([...g].sort().concat(t.sort()).join('\\\\n'))\\" 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 init -d "Scaffolding commands"
 complete -c ${quoted} -n "__fish_use_subcommand" -a man -d "Generate man page"
+complete -c ${quoted} -n "__fish_use_subcommand" -a "(${groupsAndTopCmd})" -d "Module group"
 
 complete -c ${quoted} -n "__fish_seen_subcommand_from exec" -a "(${moduleListCmd})"
+
+function __apcore_group_cmds
+    set -l grp (commandline -opc)[2]
+    set -x _APCORE_GRP $grp
+    ${quoted} list --format json 2>/dev/null | node -e "
+const m=require('fs').readFileSync('/dev/stdin','utf8');
+const g=process.env._APCORE_GRP;
+JSON.parse(m).map(x=>x.id).filter(i=>i.includes('.')&&i.split('.')[0]===g).forEach(i=>console.log(i.split('.',2)[1]))
+" 2>/dev/null
+end
+
+# Group subcommand completion \u2014 matches when position 1 is not a builtin
+complete -c ${quoted} -n "not __fish_use_subcommand; and not __fish_seen_subcommand_from list describe completion init man exec" -a "(__apcore_group_cmds)"
 `;
 }
 function buildSynopsis(command, progName, commandName) {
@@ -1632,6 +2103,11 @@ function generateManPage(commandName, command, progName, version = SHELL_VERSION
   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(".TP");
+  sections.push("\\fBAPCORE_AUTH_API_KEY\\fR");
+  sections.push(
+    "API key for authenticating with the apcore registry."
+  );
   sections.push(".SH EXIT CODES");
   const exitCodes = [
     ["0", "Success."],
@@ -1668,7 +2144,7 @@ ${meaning}`);
   return sections.join("\n");
 }
 function registerShellCommands(cli, progName = "apcore-cli") {
-  const completionCmd = new Command3("completion").description(
+  const completionCmd = new Command4("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"];
@@ -1688,8 +2164,8 @@ function registerShellCommands(cli, progName = "apcore-cli") {
     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 manCmd = new Command4("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(["completion", "describe", "exec", "init", "list", "man"]);
     const cmd = cli.commands.find((c) => c.name() === commandName) ?? null;
     if (!cmd && !knownBuiltins.has(commandName)) {
       process.stderr.write(
@@ -1714,16 +2190,20 @@ export {
   AuditLogger,
   AuthProvider,
   AuthenticationError,
+  BUILTIN_COMMANDS,
   ConfigDecryptionError,
   ConfigEncryptor,
   ConfigResolver,
   DEFAULTS,
   EXIT_CODES,
+  GroupedModuleGroup,
+  LazyGroup,
   LazyModuleGroup,
   ModuleExecutionError,
   ModuleNotFoundError,
   Sandbox,
   SchemaValidationError,
+  applyToolkitIntegration,
   buildModuleCommand,
   checkApproval,
   collectInput,
@@ -1736,12 +2216,15 @@ export {
   formatModuleDetail,
   formatModuleList,
   getAuditLogger,
+  getCliDisplayFields,
+  getDisplay,
   getLogLevel,
   info,
   main,
   mapType,
   reconvertEnumValues,
   registerDiscoveryCommands,
+  registerInitCommand,
   registerShellCommands,
   resolveFormat,
   resolveRefs,