@kb-labs/cli-commands 2.94.0 → 2.96.0

package/dist/registry/index.js

@@ -3,11 +3,11 @@ import path2 from 'path';
 import { fileURLToPath, pathToFileURL } from 'url';
 import { existsSync, promises } from 'fs';
 import { createHash } from 'crypto';
+import { computeManifestIntegrity } from '@kb-labs/core-discovery';
 import { parse } from 'yaml';
 import { glob } from 'glob';
 import { toPosixPath } from '@kb-labs/shared-cli-ui';
 import { z } from 'zod';
-import Ajv from 'ajv';
 import { platform } from '@kb-labs/core-runtime';
 import { getLogLevel } from '@kb-labs/cli-runtime';
 
@@ -107,62 +107,37 @@ var FlagDefinitionSchema = z.object({
   choices: z.array(z.string()).optional(),
   required: z.boolean().optional()
 }).refine(
-  (data) => {
-    if (data.choices && data.type !== "string") {
-      return false;
-    }
-    return true;
-  },
+  (data) => !(data.choices && data.type !== "string"),
   { message: "Choices are only allowed for string type flags" }
 );
 var EngineSchema = z.object({
   node: z.string().optional(),
-  // e.g., ">=18", "^18.0.0"
   kbCli: z.string().optional(),
-  // e.g., "^1.5.0"
   module: z.enum(["esm", "cjs"]).optional()
 }).optional();
 var CommandManifestSchema = z.object({
   manifestVersion: z.literal("1.0"),
-  // Legacy fields (still supported)
-  id: z.string().min(1).regex(/^[a-z0-9-]+:[a-z0-9-]+(?:[:a-z0-9-]+)*$/, 'Command ID must be in format "namespace:command"'),
-  aliases: z.array(z.string()).optional(),
+  segments: z.array(z.string().min(1)).min(1),
+  id: z.string().min(1),
   group: z.string().min(1),
+  subgroup: z.string().optional(),
+  aliases: z.array(z.string()).optional(),
+  category: z.string().optional(),
   describe: z.string().min(1),
   longDescription: z.string().optional(),
   requires: z.array(z.string()).optional(),
-  // Package names with optional semver
   flags: z.array(FlagDefinitionSchema).optional(),
   examples: z.array(z.string()).optional(),
   loader: z.any(),
-  // Function validation happens at runtime
-  // New fields (optional for backward compatibility)
   package: z.string().optional(),
-  // Full package name
-  namespace: z.string().optional(),
-  // Derived from id if not provided
   engine: EngineSchema,
   permissions: z.array(z.string()).optional(),
-  // e.g., ["fs.read", "git.read", "net.fetch"]
   telemetry: z.enum(["opt-in", "off"]).optional(),
   manifestV2: z.any().optional(),
-  // Full ManifestV3 for sandbox execution
-  // Internal flags for auto-generated commands
-  isSetup: z.boolean().optional(),
-  // Auto-generated setup command
-  isSetupRollback: z.boolean().optional(),
-  // Auto-generated setup rollback command
-  pkgRoot: z.string().optional()
-  // Package root path for handler resolution
+  pkgRoot: z.string().optional(),
+  _synthetic: z.boolean().optional(),
+  operationType: z.enum(["read", "mutate", "execute", "analyze"]).optional()
 }).refine(
-  (data) => {
-    if (data.namespace && data.group && data.namespace !== data.group) {
-      return false;
-    }
-    return true;
-  },
-  { message: "namespace must match group" }
-).refine(
   (data) => {
     if (data.requires) {
       for (const req2 of data.requires) {
@@ -189,46 +164,36 @@ function validateManifests(manifests) {
     if (result.success) {
       validated.push(result.data);
     } else {
-      const errorWithIndex = new z.ZodError([
-        ...result.error.issues.map((issue) => ({
-          ...issue,
-          path: [`[${i}]`, ...issue.path]
-        }))
-      ]);
-      errors.push(errorWithIndex);
+      errors.push(
+        new z.ZodError(
+          result.error.issues.map((issue) => ({ ...issue, path: [`[${i}]`, ...issue.path] }))
+        )
+      );
     }
   }
-  if (errors.length === 0) {
-    return { success: true, data: validated };
-  }
-  return { success: false, errors };
+  return errors.length === 0 ? { success: true, data: validated } : { success: false, errors };
 }
-function normalizeManifest(manifest, packageName, namespace) {
-  const normalized = { ...manifest };
-  if (!normalized.namespace && normalized.group) {
-    normalized.namespace = normalized.group;
-  } else if (!normalized.namespace && namespace) {
-    normalized.namespace = namespace;
-  }
-  if (!normalized.group && normalized.namespace) {
-    normalized.group = normalized.namespace;
-  }
-  if (!normalized.package) {
-    normalized.package = packageName;
-  }
-  return normalized;
+function normalizeManifest(manifest, packageName) {
+  const segs = manifest.segments;
+  return {
+    ...manifest,
+    id: segs[segs.length - 1] ?? "",
+    group: segs[0] ?? "",
+    subgroup: segs.length >= 3 ? segs[1] : void 0,
+    package: manifest.package ?? packageName
+  };
 }
 
 // src/registry/discover.ts
+var DISCOVERY_VERSION = 2;
 var DEBUG_MODE = process.env.DEBUG_SANDBOX === "1" || process.env.NODE_ENV === "development";
 var log = (level, message, fields) => {
   if (!DEBUG_MODE) {
     return;
   }
   const prefix = level === "error" ? "\u2717" : level === "warn" ? "\u26A0" : level === "info" ? "\u2139" : "\u{1F50D}";
-  const logFn = level === "error" ? console.error : level === "warn" ? console.warn : console.log;
   {
-    logFn(`${prefix} [discover] ${message}`);
+    console.error(`${prefix} [discover] ${message}`);
   }
 };
 function createManifestV3Loader(commandId) {
@@ -250,6 +215,14 @@ var __test = {
   createManifestV3Loader
   // resetInProcCache is exported directly (not via __test) since it's part of the public API
 };
+var NonPluginManifestError = class extends Error {
+  schema;
+  constructor(pkgName, schema) {
+    super(`${pkgName} uses manifest schema "${schema}", not kb.plugin/3 \u2014 skipping`);
+    this.name = "NonPluginManifestError";
+    this.schema = schema;
+  }
+};
 function createUnavailableManifest(pkgName, error) {
   const rawMsg = (error instanceof Error ? error.message : String(error) || "").toString();
   let missing = null;
@@ -264,9 +237,11 @@ function createUnavailableManifest(pkgName, error) {
   const group = (seg || pkgName).replace(/-cli$/, "");
   const short = seg || pkgName;
   const requires = missing ? [missing] : [];
+  const unavailableId = `manifest:${short}`;
   const manifest = {
     manifestVersion: "1.0",
-    id: `${group}:manifest:${short}`,
+    segments: [group, unavailableId],
+    id: unavailableId,
     group,
     describe: `Commands from ${pkgName} are unavailable`,
     requires,
@@ -289,14 +264,6 @@ var inProcDiscoveryCache = null;
 function resetInProcCache() {
   inProcDiscoveryCache = null;
 }
-async function computeManifestHash(manifestPath) {
-  try {
-    const content = await promises.readFile(manifestPath, "utf8");
-    return createHash("sha256").update(content).digest("hex");
-  } catch {
-    return "unknown";
-  }
-}
 async function computeLockfileHash(cwd) {
   const lockfilePath = path2.join(cwd, "pnpm-lock.yaml");
   try {
@@ -402,8 +369,12 @@ async function loadManifest(manifestPath, pkgName, pkgRoot) {
   const mod = await import(fileUrl);
   const modTyped = mod;
   const rawManifest = modTyped.manifest || modTyped.default;
-  if (!rawManifest || typeof rawManifest !== "object" || rawManifest.schema !== "kb.plugin/3") {
-    throw new Error(`Unsupported manifest format in ${pkgName}. Only kb.plugin/3 schema is supported.`);
+  if (!rawManifest || typeof rawManifest !== "object") {
+    throw new Error(`No manifest export found in ${pkgName}`);
+  }
+  const schema = rawManifest.schema;
+  if (schema !== "kb.plugin/3") {
+    throw new NonPluginManifestError(pkgName, typeof schema === "string" ? schema : String(schema ?? "unknown"));
   }
   const manifest = rawManifest;
   const namespace = getNamespaceFromManifest(manifest, pkgName);
@@ -414,20 +385,23 @@ async function loadManifest(manifestPath, pkgName, pkgRoot) {
     log("warn", `ManifestV3 ${manifest.id || pkgName} has no CLI commands or setup entry`);
   }
   const commandManifests = cliCommands.map((cmd) => {
-    const commandId = cmd.id;
+    const segments = cmd.path.trim().split(/\s+/).filter(Boolean);
+    const commandId = segments[segments.length - 1] ?? namespace;
     const commandManifest = {
       manifestVersion: "1.0",
+      segments,
       id: commandId,
-      group: cmd.group || namespace,
-      subgroup: cmd.subgroup,
+      group: segments[0] ?? namespace,
+      subgroup: segments.length >= 3 ? segments[1] : void 0,
+      category: cmd.category,
       describe: cmd.describe || "",
       longDescription: cmd.longDescription,
       aliases: cmd.aliases,
       flags: cmd.flags,
       examples: cmd.examples,
-      loader: createManifestV3Loader(commandId),
+      loader: createManifestV3Loader(cmd.path),
       package: pkgName,
-      namespace: cmd.group || namespace
+      operationType: cmd.operationType
     };
     commandManifest.manifestV2 = manifest;
     commandManifest.pkgRoot = baseRoot;
@@ -441,7 +415,7 @@ async function loadManifest(manifestPath, pkgName, pkgRoot) {
     log("warn", `ManifestV3 validation warnings for ${pkgName}: ${errorMessages}`);
   }
   return (validation.success ? validation.data : commandManifests).map(
-    (m) => normalizeManifest(m, pkgName, namespace)
+    (m) => normalizeManifest(m, pkgName)
   );
 }
 async function readPackageJson(pkgPath) {
@@ -512,10 +486,11 @@ function validateUniqueIds(manifests, pkgName) {
   const ids = /* @__PURE__ */ new Set();
   const aliases = /* @__PURE__ */ new Set();
   for (const m of manifests) {
-    if (ids.has(m.id)) {
+    const key = m.segments.join("/");
+    if (ids.has(key)) {
       throw new Error(`Duplicate command ID "${m.id}" in package ${pkgName}`);
     }
-    ids.add(m.id);
+    ids.add(key);
     if (m.aliases) {
       for (const alias of m.aliases) {
         if (aliases.has(alias) || ids.has(alias)) {
@@ -608,6 +583,10 @@ async function loadManifestsForPackages(packageInfos, source, scope) {
       log("debug", `[plugins][perf] ${pkgName} failed after ${pkgTime}ms`);
       const errMsg = err instanceof Error ? err.message : String(err);
       const errCode = err.code ?? "UNKNOWN";
+      if (err instanceof NonPluginManifestError) {
+        log("debug", `[plugins] ${pkgName} skipped: ${err.message}`);
+        return null;
+      }
       log("warn", JSON.stringify({
         code: "DISCOVERY_MANIFEST_LOAD_FAIL",
         packageName: pkgName,
@@ -778,6 +757,10 @@ async function discoverNodeModules(cwd) {
       } catch (err) {
         const errMsg = err instanceof Error ? err.message : String(err);
         const errCode = err.code ?? "UNKNOWN";
+        if (err instanceof NonPluginManifestError) {
+          log("debug", `[plugins] ${pkgName} skipped: ${err.message}`);
+          return null;
+        }
         log("warn", JSON.stringify({
           code: "DISCOVERY_MANIFEST_LOAD_FAIL",
           packageName: pkgName,
@@ -867,6 +850,10 @@ async function loadCache(cwd, roots) {
       log("debug", "Cache invalidated: Node version changed");
       return null;
     }
+    if ((cache.discoveryVersion ?? 0) !== DISCOVERY_VERSION) {
+      log("debug", `Cache invalidated: discovery logic changed (${cache.discoveryVersion ?? 0} \u2192 ${DISCOVERY_VERSION})`);
+      return null;
+    }
     const currentCliVersion = process.env.CLI_VERSION || "0.1.0";
     if (cache.cliVersion !== currentCliVersion) {
       log("debug", "Cache invalidated: CLI version changed");
@@ -920,7 +907,7 @@ async function loadCache(cwd, roots) {
     return null;
   }
 }
-async function isPackageCacheStale(entry, options) {
+async function isPackageCacheStale(entry) {
   const manifestFsPath = entry.manifestPath.split("/").join(path2.sep);
   const pkgJsonPath = path2.join(entry.result.pkgRoot.split("/").join(path2.sep), PACKAGE_JSON);
   try {
@@ -933,26 +920,23 @@ async function isPackageCacheStale(entry, options) {
     log("debug", `Package cache invalidated: missing package.json for ${entry.result.packageName} (${error instanceof Error ? error.message : "unknown"})`);
     return true;
   }
-  let manifestStat;
+  let manifestMtimeChanged = false;
   try {
-    manifestStat = await promises.stat(manifestFsPath);
-    if (manifestStat.mtimeMs !== entry.manifestMtime) {
-      log("debug", `Package cache invalidated: manifest mtime changed for ${entry.result.packageName}`);
-      return true;
-    }
+    const manifestStat = await promises.stat(manifestFsPath);
+    manifestMtimeChanged = manifestStat.mtimeMs !== entry.manifestMtime;
   } catch (error) {
     log("debug", `Package cache invalidated: manifest deleted for ${entry.result.packageName} (${error instanceof Error ? error.message : "unknown"})`);
     return true;
   }
-  if (options.validateHash) {
+  if (manifestMtimeChanged) {
     try {
-      const currentHash = await computeManifestHash(manifestFsPath);
+      const currentHash = await computeManifestIntegrity(manifestFsPath);
       if (currentHash !== entry.manifestHash) {
-        log("debug", `Package cache invalidated: manifest hash changed for ${entry.result.packageName}`);
+        log("debug", `Package cache invalidated: manifest content changed for ${entry.result.packageName}`);
         return true;
       }
     } catch (error) {
-      log("debug", `Package cache hash validation failed for ${entry.result.packageName}: ${error instanceof Error ? error.message : "unknown"}`);
+      log("debug", `Package cache hash check failed for ${entry.result.packageName}: ${error instanceof Error ? error.message : "unknown"}`);
       return true;
     }
   }
@@ -971,7 +955,7 @@ async function saveCache(cwd, results, roots) {
       continue;
     }
     try {
-      const manifestHash = await computeManifestHash(result.manifestPath);
+      const manifestHash = await computeManifestIntegrity(result.manifestPath);
       const pkgJsonPath = path2.join(result.pkgRoot.split("/").join(path2.sep), PACKAGE_JSON);
       const pkgStat = await promises.stat(pkgJsonPath);
       const pkg = await readPackageJson(pkgJsonPath);
@@ -1026,6 +1010,7 @@ async function saveCache(cwd, results, roots) {
   const cache = {
     version: process.version,
     cliVersion: process.env.CLI_VERSION || "0.1.0",
+    discoveryVersion: DISCOVERY_VERSION,
     timestamp: now,
     ttlMs: DISK_CACHE_TTL_MS,
     stateHash: stateHasher.digest("hex"),
@@ -1073,11 +1058,10 @@ async function discoverManifests(cwd, noCache = false, options = {}) {
       const freshResults = [];
       const cacheAge = Date.now() - cached.timestamp;
       const ttlMs = cached.ttlMs ?? DISK_CACHE_TTL_MS;
-      const enforceHashValidation = cacheAge >= ttlMs;
-      log("debug", `[plugins][cache] hit age=${cacheAge}ms ttl=${ttlMs}ms validateHash=${enforceHashValidation}`);
+      log("debug", `[plugins][cache] hit age=${cacheAge}ms ttl=${ttlMs}ms`);
       let staleCount = 0;
       for (const entry of Object.values(cached.packages)) {
-        const stale = await isPackageCacheStale(entry, { validateHash: enforceHashValidation });
+        const stale = await isPackageCacheStale(entry);
         if (!stale) {
           freshResults.push(entry.result);
         } else {
@@ -1144,7 +1128,19 @@ async function discoverManifests(cwd, noCache = false, options = {}) {
       if (projectWorkspace.length > 0) {
         log("info", `Discovered ${projectWorkspace.length} project workspace packages with CLI manifests`);
       }
-    } catch {
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const isMissingYaml = msg.includes("ENOENT") || msg.includes("no such file");
+      if (isMissingYaml) {
+        log("debug", `[plugins][discover] no pnpm-workspace.yaml at projectRoot=${roots.projectRoot} \u2014 skipping project workspace scan`);
+      } else {
+        log("warn", JSON.stringify({
+          code: "PROJECT_WORKSPACE_DISCOVERY_FAILED",
+          projectRoot: roots.projectRoot,
+          error: msg,
+          hint: "Project workspace plugins may be missing from CLI discovery"
+        }));
+      }
     }
   }
   const dedupStart = Date.now();
@@ -1170,81 +1166,37 @@ async function discoverManifestsByNamespace(cwd, namespace, noCache = false) {
   const allResults = await discoverManifests(cwd, noCache);
   return allResults.filter((result) => {
     return result.manifests.some((m) => {
-      const manifestNamespace = m.namespace || m.group;
-      return manifestNamespace === namespace;
+      return m.group === namespace;
     });
   });
 }
-var ajv = new Ajv();
-var flagSchema = {
-  type: "object",
-  required: ["name", "type"],
-  additionalProperties: false,
-  properties: {
-    name: { type: "string" },
-    type: { enum: ["string", "boolean", "number", "array"] },
-    alias: { type: "string", pattern: "^[a-z]$" },
-    // single letter
-    description: { type: "string" },
-    choices: { type: "array", items: { type: "string" } },
-    required: { type: "boolean" },
-    default: {}
-    // must match type
-  }
-};
-var manifestSchema = {
-  type: "object",
-  required: ["manifestVersion", "id", "group", "describe", "loader"],
-  additionalProperties: true,
-  properties: {
-    manifestVersion: { type: "string", enum: ["1.0"] },
-    id: { type: "string", pattern: "^[a-z0-9-]+(?::[a-z0-9-]+)*$" },
-    // Simple or namespaced (colon-separated)
-    aliases: { type: "array", items: { type: "string" } },
-    group: { type: "string" },
-    describe: { type: "string" },
-    longDescription: { type: "string" },
-    requires: { type: "array", items: { type: "string" } },
-    flags: {
-      type: "array",
-      items: flagSchema
-    },
-    examples: { type: "array", items: { type: "string" } }
-  }
-};
-var validateManifest = ajv.compile(manifestSchema);
-var validateFlag = ajv.compile(flagSchema);
-function validateFlagDef(flag, manifestId) {
-  if (!validateFlag(flag)) {
+function validateManifestStructure(manifest) {
+  if (manifest.manifestVersion !== "1.0") {
     throw new Error(
-      `Invalid flag "${flag.name}" in ${manifestId}: ${ajv.errorsText(validateFlag.errors)}`
+      `Unsupported manifestVersion "${manifest.manifestVersion}" in ${manifest.segments?.join(" ") ?? manifest.id} (expected "1.0")`
     );
   }
-  if (flag.choices && flag.type !== "string") {
-    throw new Error(`Flag "${flag.name}" in ${manifestId}: choices allowed only for string type`);
-  }
-  if (flag.default !== void 0) {
-    const typeMatches = flag.type === "string" && typeof flag.default === "string" || flag.type === "boolean" && typeof flag.default === "boolean" || flag.type === "number" && typeof flag.default === "number" || flag.type === "array" && Array.isArray(flag.default);
-    if (!typeMatches) {
-      throw new Error(
-        `Flag "${flag.name}" in ${manifestId}: default value type mismatch (expected ${flag.type})`
-      );
-    }
+  if (!Array.isArray(manifest.segments) || manifest.segments.length === 0) {
+    throw new Error(`Missing or empty segments in manifest ${manifest.id}`);
   }
-}
-function validateManifestStructure(manifest) {
-  if (!validateManifest(manifest)) {
-    throw new Error(`Invalid manifest ${manifest.id}: ${ajv.errorsText(validateManifest.errors)}`);
+  if (!manifest.describe) {
+    throw new Error(`Missing describe in manifest ${manifest.segments.join(" ")}`);
   }
-  if (manifest.manifestVersion !== "1.0") {
-    throw new Error(
-      `Unsupported manifestVersion "${manifest.manifestVersion}" in ${manifest.id} (expected "1.0")`
-    );
+  if (!manifest.loader && !manifest.manifestV2) {
+    throw new Error(`Command ${manifest.segments.join(" ")} must have either loader or manifestV2`);
   }
-  if (manifest.flags && Array.isArray(manifest.flags) && manifest.id) {
+  if (manifest.flags) {
     for (const flag of manifest.flags) {
-      if (flag && typeof flag === "object" && flag.name) {
-        validateFlagDef(flag, manifest.id);
+      if (!flag.name || !flag.type) {
+        throw new Error(`Invalid flag in ${manifest.segments.join(" ")}: missing name or type`);
+      }
+      if (flag.alias && flag.alias.length !== 1) {
+        throw new Error(`Flag "${flag.name}" in ${manifest.segments.join(" ")}: alias must be a single character`);
+      }
+      if (flag.choices && flag.type !== "string") {
+        throw new Error(
+          `Flag "${flag.name}" in ${manifest.segments.join(" ")}: choices only allowed for string type`
+        );
       }
     }
   }
@@ -1255,61 +1207,8 @@ var SOURCE_PRIORITY = {
   linked: 2,
   node_modules: 1
 };
-function normalizeCommandId(id, _namespace) {
-  return id;
-}
-function generateWhitespaceAliases(id) {
-  if (!id.includes(":")) {
-    return [];
-  }
-  return [id.replace(":", " ")];
-}
-function normalizeAliases(manifest, logger) {
-  const log2 = logger ?? platform.logger;
-  const aliases = /* @__PURE__ */ new Set();
-  manifest.namespace || manifest.group;
-  if (manifest.aliases) {
-    for (const alias of manifest.aliases) {
-      if (!/^[a-z0-9-:]+$/i.test(alias)) {
-        log2.warn(`Invalid alias "${alias}" in ${manifest.id}: aliases must be alphanumeric with hyphens or colons`);
-        continue;
-      }
-      aliases.add(alias);
-    }
-  }
-  const whitespaceAliases = generateWhitespaceAliases(manifest.id);
-  for (const alias of whitespaceAliases) {
-    aliases.add(alias);
-  }
-  return Array.from(aliases);
-}
-function checkNamespaceCollision(manifest, existing, namespace) {
-  const existingGroup = existing.manifest.group || "";
-  const currentGroup = manifest.group || "";
-  if (existingGroup === currentGroup && existingGroup === namespace && existing.manifest.id === manifest.id) {
-    throw new Error(
-      `Command collision in group "${namespace}": "${manifest.id}" conflicts with existing "${existing.manifest.id}". Rename one of the commands to use a different ID (e.g., "${manifest.id}2" or use --alias to create a different alias).`
-    );
-  }
-}
 function getSourcePriority(source) {
-  return SOURCE_PRIORITY[source] || 0;
-}
-function checkCollision(manifest, existing, currentSource, namespace) {
-  const existingPriority = getSourcePriority(existing.source);
-  const currentPriority = getSourcePriority(currentSource);
-  checkNamespaceCollision(manifest, existing, namespace);
-  if (currentSource === "workspace" && existing.source === "workspace") {
-    throw new Error(
-      `Command ID collision: "${manifest.id}" is exported by multiple workspace packages. This is not allowed. Please rename one of the commands to use a different ID.`
-    );
-  }
-  if (currentPriority > existingPriority) {
-    return { shouldShadow: true };
-  } else if (currentPriority < existingPriority) {
-    return { shouldShadow: false };
-  }
-  return { shouldShadow: false };
+  return SOURCE_PRIORITY[source] ?? 0;
 }
 function preflightManifests(discoveryResults, logger) {
   const log2 = logger ?? platform.logger;
@@ -1324,24 +1223,17 @@ function preflightManifests(discoveryResults, logger) {
         allowed.push(manifest);
       } catch (error) {
         const reason = error instanceof Error ? error.message : "Validation failed";
-        const manifestId = manifest?.id || manifest?.group || result.packageName || "unknown";
-        skipped.push({
-          id: manifestId,
-          source: result.source,
-          reason
-        });
-        log2.warn(`Preflight skipped manifest ${manifestId}: ${reason}`);
+        const id = manifest?.segments?.join(" ") ?? manifest?.id ?? result.packageName ?? "unknown";
+        skipped.push({ id, source: result.source, reason });
+        log2.warn(`Preflight skipped manifest ${id}: ${reason}`);
         if (logLevel === "debug") {
-          process.stderr.write(`[debug][preflight] skipped ${manifestId} (${result.source}): ${reason}
+          process.stderr.write(`[debug][preflight] skipped ${id} (${result.source}): ${reason}
 `);
         }
       }
     }
     if (allowed.length > 0) {
-      valid.push({
-        ...result,
-        manifests: allowed
-      });
+      valid.push({ ...result, manifests: allowed });
     }
   }
   return { valid, skipped };
@@ -1351,41 +1243,27 @@ async function registerManifests(discoveryResults, registry2, options = {}) {
   const registered = [];
   const skipped = [];
   const globalIds = /* @__PURE__ */ new Map();
-  const globalAliases = /* @__PURE__ */ new Map();
   const logLevel = getLogLevel();
   let collisions = 0;
   let errors = 0;
   const sorted = [...discoveryResults].sort((a, b) => {
-    const priorityA = getSourcePriority(a.source);
-    const priorityB = getSourcePriority(b.source);
-    return priorityB - priorityA;
+    return getSourcePriority(b.source) - getSourcePriority(a.source);
   });
   for (const result of sorted) {
     for (const manifest of result.manifests) {
-      const manifestId = manifest.id || manifest.group || "unknown";
-      const namespace = manifest.namespace || manifest.group;
+      const manifestId = manifest.segments?.join(" ") ?? manifest.id ?? "unknown";
       try {
         try {
           validateManifestStructure(manifest);
         } catch (err) {
           throw new Error(`Validation failed: ${err instanceof Error ? err.message : String(err)}`);
         }
-        const normalizedId = normalizeCommandId(manifest.id, namespace);
-        if (normalizedId !== manifest.id) {
-          log2.warn(`Command ID "${manifest.id}" normalized to "${normalizedId}"`);
-          manifest.id = normalizedId;
-        }
-        const normalizedAliases = normalizeAliases(manifest, log2);
-        if (normalizedAliases.length > 0) {
-          manifest.aliases = normalizedAliases;
-        }
         const availability = checkRequires(manifest, {
           cwd: options.cwd ?? result.pkgRoot
         });
         const cmd = {
           manifest,
           v3Manifest: manifest.manifestV2,
-          // Extract V3 manifest from legacy field
           available: availability.available,
           unavailableReason: availability.available ? void 0 : availability.reason,
           hint: availability.available ? void 0 : availability.hint,
@@ -1396,14 +1274,14 @@ async function registerManifests(discoveryResults, registry2, options = {}) {
         };
         try {
           const manifestModule = await import(result.manifestPath);
-          if (manifestModule.init && typeof manifestModule.init === "function") {
+          if (typeof manifestModule.init === "function") {
             await manifestModule.init({
               cwd: result.pkgRoot,
               package: result.packageName,
               manifest: cmd.manifest
             });
           }
-          if (manifestModule.register && typeof manifestModule.register === "function") {
+          if (typeof manifestModule.register === "function") {
             await manifestModule.register({
               registry: registry2,
               command: cmd,
@@ -1411,18 +1289,25 @@ async function registerManifests(discoveryResults, registry2, options = {}) {
               package: result.packageName
             });
           }
-          if (manifestModule.dispose && typeof manifestModule.dispose === "function") {
+          if (typeof manifestModule.dispose === "function") {
             cmd._disposeHook = manifestModule.dispose;
           }
         } catch (hookError) {
           const hookMsg = hookError instanceof Error ? hookError.message : String(hookError);
-          log2.debug(`Lifecycle hooks unavailable for ${manifest.id}: ${hookMsg}`);
+          log2.debug(`Lifecycle hooks unavailable for ${manifestId}: ${hookMsg}`);
         }
-        const canonicalKey = manifest.group ? `${manifest.group}:${manifest.id}` : manifest.id;
+        const canonicalKey = manifest.segments.join(":");
         const existing = globalIds.get(canonicalKey);
         if (existing) {
-          const collision = checkCollision(manifest, existing, result.source, namespace);
-          if (collision.shouldShadow) {
+          if (existing.source === result.source && existing.source === "workspace") {
+            collisions++;
+            throw new Error(
+              `Command path collision: "${manifestId}" exported by multiple workspace packages.`
+            );
+          }
+          const existPri = getSourcePriority(existing.source);
+          const curPri = getSourcePriority(result.source);
+          if (curPri > existPri) {
             existing.shadowed = true;
             globalIds.set(canonicalKey, cmd);
             if (logLevel === "info" || logLevel === "debug") {
@@ -1437,63 +1322,15 @@ async function registerManifests(discoveryResults, registry2, options = {}) {
         } else {
           globalIds.set(canonicalKey, cmd);
         }
-        const aliasesToCheck = manifest.aliases || [];
-        for (const alias of aliasesToCheck) {
-          const existingAlias = globalAliases.get(alias);
-          if (existingAlias) {
-            if (existingAlias.manifest.id === manifest.id) {
-              continue;
-            }
-            const existingPriority = getSourcePriority(existingAlias.source);
-            const currentPriority = getSourcePriority(result.source);
-            if (currentPriority > existingPriority) {
-              existingAlias.shadowed = true;
-              globalAliases.set(alias, cmd);
-              if (logLevel === "info" || logLevel === "debug") {
-                log2.info(`Alias "${alias}" from ${result.source} shadows ${existingAlias.source} version`);
-              }
-            } else if (currentPriority < existingPriority) {
-              if (logLevel === "info" || logLevel === "debug") {
-                log2.info(`Alias "${alias}" from ${result.source} shadowed by ${existingAlias.source} version`);
-              }
-              continue;
-            } else {
-              collisions++;
-              throw new Error(
-                `Alias collision: "${alias}" used by both ${manifest.id} and ${existingAlias.manifest.id}. Rename one alias or use a different namespace.`
-              );
-            }
-          }
-          if (globalIds.has(alias)) {
-            const conflictingCmd = globalIds.get(alias);
-            const existingPriority = getSourcePriority(conflictingCmd.source);
-            const currentPriority = getSourcePriority(result.source);
-            if (currentPriority > existingPriority) {
-              log2.warn(`Alias "${alias}" conflicts with command ID "${alias}". Alias will shadow command.`);
-              globalAliases.set(alias, cmd);
-            } else {
-              throw new Error(
-                `Alias "${alias}" conflicts with existing command ID "${alias}". Rename the alias or use a different name.`
-              );
-            }
-          } else {
-            globalAliases.set(alias, cmd);
-          }
-        }
         if (!cmd.shadowed) {
           registry2.registerManifest(cmd);
+          registered.push(cmd);
         }
-        registered.push(cmd);
       } catch (error) {
         errors++;
         const reason = error instanceof Error ? error.message : String(error);
-        skipped.push({
-          id: manifestId,
-          source: result.source,
-          reason
-        });
+        skipped.push({ id: manifestId, source: result.source, reason });
         log2.error(`Skipped manifest ${manifestId} (${result.source}): ${reason}`);
-        continue;
       }
     }
   }
@@ -1503,24 +1340,18 @@ async function registerManifests(discoveryResults, registry2, options = {}) {
       log2.warn(`  \u2022 ${skip.id} [${skip.source}] \u2192 ${skip.reason}`);
     }
   }
-  return {
-    registered,
-    skipped,
-    collisions,
-    errors
-  };
+  return { registered, skipped, collisions, errors };
 }
 async function disposeAllPlugins(registry2, logger) {
   const log2 = logger ?? platform.logger;
-  const manifests = registry2.listManifests();
+  const manifests = registry2.listCommands();
   const disposePromises = [];
   for (const cmd of manifests) {
     const disposeHook = cmd._disposeHook;
-    if (disposeHook && typeof disposeHook === "function") {
+    if (typeof disposeHook === "function") {
       disposePromises.push(
         Promise.resolve(disposeHook()).catch((err) => {
-          const errMsg = err instanceof Error ? err.message : String(err);
-          log2.warn(`Dispose hook failed for ${cmd.manifest.id}: ${errMsg}`);
+          log2.warn(`Dispose hook failed for ${cmd.manifest.segments.join(" ")}: ${err instanceof Error ? err.message : String(err)}`);
         })
       );
     }
@@ -1551,421 +1382,512 @@ async function runCommand(cmd, ctx, argv, flags) {
   return typeof result === "number" ? result : 0;
 }
 
-// src/registry/service.ts
-function manifestToCommand(registered) {
-  return {
-    name: registered.manifest.id,
-    category: registered.manifest.group,
-    describe: registered.manifest.describe,
-    longDescription: registered.manifest.longDescription,
-    aliases: registered.manifest.aliases || [],
-    flags: registered.manifest.flags,
-    examples: registered.manifest.examples,
-    async run() {
-      throw new Error(`Command ${registered.manifest.id} should be executed via plugin-executor, not via legacy run() path.`);
-    }
-  };
+// src/registry/trie-router.ts
+function makeNode() {
+  return { children: /* @__PURE__ */ new Map() };
 }
-function buildCanonicalId(manifest) {
-  const { id, group, subgroup } = manifest;
-  if (group && subgroup) {
-    return `${group}:${subgroup}:${id}`;
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from(
+    { length: m + 1 },
+    (_, i) => Array.from({ length: n + 1 }, (__, j) => i === 0 ? j : j === 0 ? i : 0)
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      if (a[i - 1] === b[j - 1]) {
+        dp[i][j] = dp[i - 1][j - 1];
+      } else {
+        dp[i][j] = 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      }
+    }
   }
-  if (group) {
-    return `${group}:${id}`;
+  return dp[m][n];
+}
+function findDeep(node, targetSegments, prefix) {
+  const results = [];
+  function dfs(current, path3) {
+    if (current.command) {
+      if (targetSegments.length <= path3.length) {
+        const tail = path3.slice(path3.length - targetSegments.length);
+        const matches = tail.every((seg, i) => seg === targetSegments[i]);
+        if (matches) {
+          results.push(path3.join(" "));
+        }
+      }
+    }
+    for (const [key, child] of current.children) {
+      dfs(child, [...path3, key]);
+    }
   }
-  return id;
+  dfs(node, [...prefix]);
+  return results;
 }
-var InMemoryRegistry = class {
-  // System commands (in-process): key = any registered name/alias
-  systemCommands = /* @__PURE__ */ new Map();
-  // Plugin commands: key = canonicalId only
-  pluginByCanonical = /* @__PURE__ */ new Map();
-  // Alias → canonicalId: covers all user-input variants that resolve to a plugin
-  pluginAliases = /* @__PURE__ */ new Map();
-  // Legacy unified collection for backward compatibility (display/get)
-  byName = /* @__PURE__ */ new Map();
-  groups = /* @__PURE__ */ new Map();
-  // manifests: any key → RegisteredCommand (for listing/lookup; still stores multi-key for compat)
-  manifests = /* @__PURE__ */ new Map();
-  partial = false;
-  // ─── System command registration ────────────────────────────────────────
-  register(cmd) {
-    this.systemCommands.set(cmd.name, cmd);
-    this.byName.set(cmd.name, cmd);
-    for (const a of cmd.aliases || []) {
-      this.systemCommands.set(a, cmd);
-      this.byName.set(a, cmd);
+var TrieRouter = class {
+  root = makeNode();
+  /**
+   * Insert a plugin command into the trie.
+   *
+   * Enforces 1-manifest-1-namespace: the first packageName to register any command
+   * under a top-level group becomes the owner. Subsequent packages with a different
+   * packageName are rejected (collides: true) — the caller is responsible for warning
+   * and marking the command as shadowed.
+   *
+   * Returns { collides: false } on success, or { collides: true, ownerPackage } on conflict.
+   */
+  insertCommand(segments, cmd) {
+    if (segments.length === 0) {
+      return { collides: false };
+    }
+    const incoming = cmd.packageName ?? "__unknown__";
+    const topSeg = segments[0];
+    if (!this.root.children.has(topSeg)) {
+      this.root.children.set(topSeg, makeNode());
+    }
+    const groupNode = this.root.children.get(topSeg);
+    if (groupNode.ownerPackage === void 0) {
+      groupNode.ownerPackage = incoming;
+    } else if (groupNode.ownerPackage !== incoming) {
+      return { collides: true, ownerPackage: groupNode.ownerPackage };
+    }
+    let node = groupNode;
+    for (const seg of segments.slice(1)) {
+      if (!node.children.has(seg)) {
+        node.children.set(seg, makeNode());
+      }
+      node = node.children.get(seg);
     }
+    node.command = cmd;
+    return { collides: false };
   }
-  registerGroup(group) {
-    this.groups.set(group.name, group);
-    this.byName.set(group.name, group);
+  insertSystemCommand(cmd) {
+    const segments = [cmd.name];
+    let node = this.root;
+    for (const seg of segments) {
+      if (!node.children.has(seg)) {
+        node.children.set(seg, makeNode());
+      }
+      node = node.children.get(seg);
+    }
+    node.systemCommand = cmd;
+    for (const alias of cmd.aliases ?? []) {
+      let aliasNode = this.root;
+      if (!aliasNode.children.has(alias)) {
+        aliasNode.children.set(alias, makeNode());
+      }
+      aliasNode = aliasNode.children.get(alias);
+      aliasNode.systemCommand = cmd;
+    }
+  }
+  insertSystemGroup(group) {
+    let groupNode = this.root;
+    if (!groupNode.children.has(group.name)) {
+      groupNode.children.set(group.name, makeNode());
+    }
+    groupNode = groupNode.children.get(group.name);
+    groupNode.systemGroup = group;
+    groupNode.groupDescribe = group.describe;
     for (const cmd of group.commands) {
-      this.systemCommands.set(cmd.name, cmd);
-      const fullName = `${group.name} ${cmd.name}`;
-      this.systemCommands.set(fullName, cmd);
-      this.byName.set(fullName, cmd);
-      for (const alias of cmd.aliases || []) {
-        this.systemCommands.set(alias, cmd);
-        this.byName.set(alias, cmd);
+      let cmdNode = groupNode;
+      if (!cmdNode.children.has(cmd.name)) {
+        cmdNode.children.set(cmd.name, makeNode());
+      }
+      cmdNode = cmdNode.children.get(cmd.name);
+      cmdNode.systemCommand = cmd;
+      for (const alias of cmd.aliases ?? []) {
+        let aliasNode = groupNode;
+        if (!aliasNode.children.has(alias)) {
+          aliasNode.children.set(alias, makeNode());
+        }
+        aliasNode = aliasNode.children.get(alias);
+        aliasNode.systemCommand = cmd;
       }
     }
-    if (group.subgroups) {
-      for (const sub of group.subgroups) {
-        const subName = `${group.name} ${sub.name}`;
-        this.groups.set(subName, sub);
-        this.byName.set(subName, sub);
-        for (const cmd of sub.commands) {
-          const fullName = `${group.name} ${sub.name} ${cmd.name}`;
-          this.systemCommands.set(fullName, cmd);
-          this.byName.set(fullName, cmd);
-          for (const alias of cmd.aliases || []) {
-            this.systemCommands.set(alias, cmd);
-            this.byName.set(alias, cmd);
-          }
+    for (const sub of group.subgroups ?? []) {
+      let subNode = groupNode;
+      if (!subNode.children.has(sub.name)) {
+        subNode.children.set(sub.name, makeNode());
+      }
+      subNode = subNode.children.get(sub.name);
+      subNode.systemGroup = sub;
+      subNode.groupDescribe = sub.describe;
+      for (const cmd of sub.commands) {
+        let cmdNode = subNode;
+        if (!cmdNode.children.has(cmd.name)) {
+          cmdNode.children.set(cmd.name, makeNode());
         }
+        cmdNode = cmdNode.children.get(cmd.name);
+        cmdNode.systemCommand = cmd;
       }
     }
   }
-  // ─── Plugin command registration ────────────────────────────────────────
-  registerManifest(cmd) {
-    const canonicalId = buildCanonicalId(cmd.manifest);
-    const collisionKey = this._findSystemCollision(cmd.manifest, canonicalId);
-    if (collisionKey) {
-      console.warn(`[registry] Plugin command "${canonicalId}" collides with system command "${collisionKey}". System command takes priority.`);
-      cmd.shadowed = true;
+  getGroupDescribe(segments) {
+    let node = this.root;
+    for (const seg of segments) {
+      const child = node.children.get(seg);
+      if (!child) {
+        return void 0;
+      }
+      node = child;
     }
-    const collisionAliases = /* @__PURE__ */ new Set();
-    for (const alias of cmd.manifest.aliases || []) {
-      if (this.systemCommands.has(alias)) {
-        console.warn(`[registry] Plugin alias "${alias}" collides with system command. System command takes priority.`);
-        collisionAliases.add(alias);
+    return node.groupDescribe;
+  }
+  setGroupDescribe(segments, describe) {
+    let node = this.root;
+    for (const seg of segments) {
+      if (!node.children.has(seg)) {
+        node.children.set(seg, makeNode());
       }
+      node = node.children.get(seg);
     }
-    this.pluginByCanonical.set(canonicalId, cmd);
-    this.manifests.set(canonicalId, cmd);
-    this.manifests.set(cmd.manifest.id, cmd);
-    if (cmd.shadowed) {
-      return;
+    if (!node.groupDescribe) {
+      node.groupDescribe = describe;
     }
-    this._registerPluginAliases(cmd, canonicalId, collisionAliases);
-    const commandAdapter = manifestToCommand(cmd);
-    this.byName.set(canonicalId, commandAdapter);
-    const spaceCanonical = canonicalId.replace(/:/g, " ");
-    this.byName.set(spaceCanonical, commandAdapter);
-    this._registerSyntheticGroups(cmd, commandAdapter);
   }
-  /**
-   * Check whether any system command already owns the canonical id or its parts.
-   * Returns the colliding key if found, null otherwise.
-   */
-  _findSystemCollision(manifest, canonicalId) {
-    if (this.systemCommands.has(canonicalId)) {
-      return canonicalId;
+  resolve(tokens) {
+    if (tokens.length === 0) {
+      return {
+        type: "group",
+        segments: [],
+        childKeys: [...this.root.children.keys()]
+      };
+    }
+    let node = this.root;
+    let i = 0;
+    while (i < tokens.length) {
+      const tok = tokens[i];
+      const child = node.children.get(tok);
+      if (!child) {
+        return this._notFound(node, tokens, i);
+      }
+      node = child;
+      i++;
+      if (node.command && i < tokens.length) {
+        return { type: "command", command: node.command, rest: tokens.slice(i) };
+      }
+      if (node.systemCommand && i < tokens.length) {
+        return { type: "system-cmd", cmd: node.systemCommand, rest: tokens.slice(i) };
+      }
     }
-    const space = canonicalId.replace(/:/g, " ");
-    if (this.systemCommands.has(space)) {
-      return space;
+    if (node.command) {
+      return { type: "command", command: node.command, rest: [] };
     }
-    return null;
+    if (node.systemCommand) {
+      return { type: "system-cmd", cmd: node.systemCommand, rest: [] };
+    }
+    if (node.systemGroup) {
+      return { type: "system-group", group: node.systemGroup, rest: [] };
+    }
+    if (node.children.size > 0 || node.groupDescribe !== void 0) {
+      const segs = tokens.slice(0, i);
+      return {
+        type: "group",
+        segments: segs,
+        describe: node.groupDescribe,
+        childKeys: [...node.children.keys()]
+      };
+    }
+    return { type: "not-found", input: tokens, suggestions: [] };
   }
-  /**
-   * Register all lookup aliases for a plugin command.
-   *
-   * Priority (what beats what) is handled in resolveToCanonical at query time.
-   * Here we just build the mapping.
-   *
-   * Aliases registered:
-   *   - canonicalId itself        ("marketplace:plugins:list")
-   *   - bare id                   ("list")         ← low priority, may clash
-   *   - 2-part shorthand          ("marketplace:list", "marketplace list")
-   *   - manifest.aliases[]        (user-defined aliases, except collisions)
-   */
-  _registerPluginAliases(cmd, canonicalId, collisionAliases) {
-    const { id, group, subgroup } = cmd.manifest;
-    const register = (key) => {
-      if (!this.systemCommands.has(key) && !this.systemCommands.has(key.replace(/:/g, " "))) {
-        if (!this.pluginAliases.has(key)) {
-          this.pluginAliases.set(key, canonicalId);
-          this.manifests.set(key, cmd);
-        }
+  complete(tokens) {
+    if (tokens.length === 0) {
+      return [...this.root.children.keys()];
+    }
+    let node = this.root;
+    for (let i = 0; i < tokens.length - 1; i++) {
+      const child = node.children.get(tokens[i]);
+      if (!child) {
+        return [];
       }
-    };
-    this.pluginAliases.set(canonicalId, canonicalId);
-    const spaceCanonical = canonicalId.replace(/:/g, " ");
-    this.pluginAliases.set(spaceCanonical, canonicalId);
-    this.manifests.set(spaceCanonical, cmd);
-    if (group && subgroup) {
-      const twoPartColon = `${group}:${id}`;
-      const twoPartSpace = `${group} ${id}`;
-      register(twoPartColon);
-      register(twoPartSpace);
-      this.manifests.set(twoPartColon, cmd);
-      this.manifests.set(twoPartSpace, cmd);
-      const fullPath = `${group} ${subgroup} ${id}`;
-      this.pluginAliases.set(fullPath, canonicalId);
-      this.manifests.set(fullPath, cmd);
-      const colonPath = `${group}:${subgroup}:${id}`;
-      this.pluginAliases.set(colonPath, canonicalId);
-      this.manifests.set(colonPath, cmd);
-    } else if (group) {
-      const colonName = `${group}:${id}`;
-      const spaceName = `${group} ${id}`;
-      this.pluginAliases.set(colonName, canonicalId);
-      this.pluginAliases.set(spaceName, canonicalId);
-      this.manifests.set(colonName, cmd);
-      this.manifests.set(spaceName, cmd);
-    }
-    register(id);
-    for (const alias of cmd.manifest.aliases || []) {
-      if (!collisionAliases.has(alias)) {
-        register(alias);
+      node = child;
+    }
+    const partial = tokens[tokens.length - 1] ?? "";
+    const results = [];
+    const prefix = tokens.slice(0, tokens.length - 1);
+    for (const [key] of node.children) {
+      if (key.startsWith(partial)) {
+        results.push([...prefix, key].join(" "));
       }
     }
+    return results;
   }
   /**
-   * Register synthetic subgroups for help display.
+   * List all leaf plugin commands under a given node path.
    */
-  _registerSyntheticGroups(cmd, commandAdapter) {
-    const { id, group, subgroup } = cmd.manifest;
-    if (group && subgroup) {
-      const subgroupKey = `${group} ${subgroup}`;
-      if (!this.groups.has(subgroupKey)) {
-        this.groups.set(subgroupKey, {
-          name: subgroupKey,
-          describe: subgroup,
-          commands: []
-        });
-        this.byName.set(subgroupKey, this.groups.get(subgroupKey));
+  listUnder(segments) {
+    let node = this.root;
+    for (const seg of segments) {
+      const child = node.children.get(seg);
+      if (!child) {
+        return [];
       }
-      this.groups.get(subgroupKey).commands.push(commandAdapter);
-      const twoPartSpace = `${group} ${id}`;
-      if (!this.byName.has(twoPartSpace)) {
-        this.byName.set(twoPartSpace, commandAdapter);
+      node = child;
+    }
+    const results = [];
+    this._collectCommands(node, results);
+    return results;
+  }
+  /**
+   * Get exact command at path.
+   */
+  getAt(segments) {
+    let node = this.root;
+    for (const seg of segments) {
+      const child = node.children.get(seg);
+      if (!child) {
+        return null;
       }
-      const twoPartColon = `${group}:${id}`;
-      if (!this.byName.has(twoPartColon)) {
-        this.byName.set(twoPartColon, commandAdapter);
+      node = child;
+    }
+    return node.command ?? null;
+  }
+  /**
+   * List top-level system groups and standalone system commands (depth=1 nodes).
+   */
+  listSystemTopLevel() {
+    const results = [];
+    for (const [name, node] of this.root.children) {
+      if (node.systemGroup) {
+        results.push({ name, describe: node.systemGroup.describe, isGroup: true });
+      } else if (node.systemCommand) {
+        results.push({ name, describe: node.systemCommand.describe, isGroup: false });
       }
-      const fullPath = `${group} ${subgroup} ${id}`;
-      this.byName.set(fullPath, commandAdapter);
-    } else if (group) {
-      const fullName = `${group} ${id}`;
-      const colonName = `${group}:${id}`;
-      this.byName.set(fullName, commandAdapter);
-      this.byName.set(colonName, commandAdapter);
     }
+    return results;
   }
-  // ─── Resolution ──────────────────────────────────────────────────────────
   /**
-   * Resolve any user input to its canonical plugin ID.
-   *
-   * Returns canonicalId if found in plugin aliases, undefined otherwise.
+   * Collect all plugin commands reachable from node.
    */
-  resolveToCanonical(input) {
-    if (this.pluginAliases.has(input)) {
-      return this.pluginAliases.get(input);
+  listAll() {
+    const results = [];
+    this._collectCommands(this.root, results);
+    return results;
+  }
+  _collectCommands(node, out) {
+    if (node.command) {
+      out.push(node.command);
     }
-    const converted = input.includes(":") ? input.replace(/:/g, " ") : input.replace(/ /g, ":");
-    if (this.pluginAliases.has(converted)) {
-      return this.pluginAliases.get(converted);
+    for (const child of node.children.values()) {
+      this._collectCommands(child, out);
     }
-    return void 0;
   }
-  // ─── Public API ──────────────────────────────────────────────────────────
-  markPartial(partial) {
-    this.partial = partial;
+  _notFound(node, tokens, failIdx) {
+    const failToken = tokens[failIdx];
+    const prefix = tokens.slice(0, failIdx);
+    const siblings = [...node.children.keys()];
+    const fuzzy = siblings.map((s) => ({ s, d: levenshtein(failToken, s) })).filter(({ d }) => d <= 2).sort((a, b) => a.d - b.d).map(({ s }) => [...prefix, s, ...tokens.slice(failIdx + 1)].join(" "));
+    if (fuzzy.length === 1) {
+      return { type: "not-found", input: tokens, suggestions: fuzzy };
+    }
+    if (fuzzy.length > 1) {
+      return { type: "ambiguous", input: tokens, candidates: fuzzy };
+    }
+    const remaining = tokens.slice(failIdx);
+    const deep = findDeep(node, remaining, prefix);
+    if (deep.length === 0) {
+      return { type: "not-found", input: tokens, suggestions: [] };
+    }
+    if (deep.length === 1) {
+      return { type: "not-found", input: tokens, suggestions: deep };
+    }
+    return { type: "ambiguous", input: tokens, candidates: deep };
   }
-  isPartial() {
-    return this.partial;
+};
+
+// src/registry/archetype-flags.ts
+var outputFlag = { name: "output", type: "string", choices: ["json", "table", "csv"], description: "Output format" };
+var dryRunFlag = { name: "dry-run", type: "boolean", description: "Show what would happen without executing" };
+var yesFlag = { name: "yes", type: "boolean", alias: "y", description: "Skip confirmation prompts" };
+var waitFlag = { name: "wait", type: "boolean", description: "Block until execution completes" };
+var watchFlag = { name: "watch", type: "boolean", description: "Stream events as NDJSON" };
+var timeoutFlag = { name: "timeout", type: "string", description: "Max wait time (e.g. 30s, 5m)" };
+var limitFlag = { name: "limit", type: "number", description: "Max results to return" };
+var offsetFlag = { name: "offset", type: "number", description: "Offset for pagination" };
+var formatFlag = { name: "format", type: "string", choices: ["json", "text", "md"], description: "Output format" };
+var streamFlag = { name: "stream", type: "boolean", description: "Stream output progressively" };
+var schemaFlag = {
+  name: "schema",
+  type: "boolean",
+  description: "Output JSON Schema for this command (flags, types, examples)"
+};
+var ARCHETYPE_FLAGS = {
+  read: [outputFlag, limitFlag, offsetFlag],
+  mutate: [outputFlag, dryRunFlag, yesFlag],
+  execute: [outputFlag, waitFlag, watchFlag, timeoutFlag, yesFlag],
+  analyze: [outputFlag, formatFlag, streamFlag]
+};
+function getArchetypeFlags(operationType, existing = []) {
+  const toInject = ARCHETYPE_FLAGS[operationType] ?? [];
+  const existingNames = new Set(existing.map((f) => f.name));
+  return toInject.filter((f) => !existingNames.has(f.name));
+}
+
+// src/registry/service.ts
+var RESERVED_NAMESPACES = /* @__PURE__ */ new Set(["__complete", "__internal"]);
+var MAX_PATH_DEPTH = 6;
+function validateSegments(segs) {
+  if (segs.length === 0) {
+    return "empty path \u2014 segments must not be empty";
   }
-  getManifest(id) {
-    return this.manifests.get(id);
+  if (segs.length > MAX_PATH_DEPTH) {
+    return `path too deep: ${segs.length} segments (max ${MAX_PATH_DEPTH})`;
   }
-  listManifests() {
-    const unique = /* @__PURE__ */ new Set();
-    for (const cmd of this.pluginByCanonical.values()) {
-      unique.add(cmd);
-    }
-    return Array.from(unique);
+  if (RESERVED_NAMESPACES.has(segs[0])) {
+    return `"${segs[0]}" is a reserved namespace`;
+  }
+  return null;
+}
+var noopLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  },
+  child: () => noopLogger
+};
+var TrieBackedRegistry = class {
+  systemRouter = new TrieRouter();
+  pluginRouter = new TrieRouter();
+  partial = false;
+  logger = noopLogger;
+  // ─── Logger ────────────────────────────────────────────────────────────────
+  setLogger(logger) {
+    this.logger = logger;
   }
-  has(name) {
-    return this.byName.has(name) || this.pluginAliases.has(name);
+  // ─── Registration ──────────────────────────────────────────────────────────
+  register(cmd) {
+    this.systemRouter.insertSystemCommand(cmd);
   }
-  /**
-   * Get command with type information for secure routing.
-   *
-   * System commands ALWAYS win — checked first before any plugin lookup.
-   * Returns type='system' for system commands (in-process execution).
-   * Returns type='plugin' for plugin commands (subprocess execution).
-   */
-  getWithType(nameOrPath) {
-    const normalized = typeof nameOrPath === "string" ? nameOrPath : nameOrPath.join(" ");
-    if (this.systemCommands.has(normalized)) {
-      return { cmd: this.systemCommands.get(normalized), type: "system" };
-    }
-    const colonVariant = normalized.replace(/ /g, ":");
-    if (this.systemCommands.has(colonVariant)) {
-      return { cmd: this.systemCommands.get(colonVariant), type: "system" };
-    }
-    if (this.groups.has(normalized)) {
-      return { cmd: this.groups.get(normalized), type: "system" };
-    }
-    const canonicalId = this.resolveToCanonical(normalized);
-    if (canonicalId) {
-      const pluginCmd = this.pluginByCanonical.get(canonicalId);
-      if (pluginCmd && !pluginCmd.shadowed) {
-        const cmd2 = this.byName.get(canonicalId) ?? this.byName.get(normalized);
-        if (cmd2) {
-          return { cmd: cmd2, type: "plugin" };
-        }
+  registerGroup(group) {
+    this.systemRouter.insertSystemGroup(group);
+    if (group.subgroups) {
+      for (const sub of group.subgroups) {
+        this.systemRouter.setGroupDescribe([group.name, sub.name], sub.describe ?? "");
       }
     }
-    const cmd = this.get(nameOrPath);
-    if (!cmd) {
-      return void 0;
-    }
-    if ("commands" in cmd) {
-      return { cmd, type: "system" };
+  }
+  registerManifest(cmd) {
+    if (cmd.manifest._synthetic) {
+      return;
     }
-    if (this.systemCommands.has(normalized) || this.systemCommands.has(colonVariant)) {
-      return { cmd, type: "system" };
+    const segs = cmd.manifest.segments;
+    const pkg = cmd.packageName ?? "unknown";
+    const validationError = validateSegments(segs);
+    if (validationError) {
+      this.logger.warn(`[registry] Plugin "${pkg}" skipped: ${validationError} (path: "${segs.join(" ")}")`);
+      cmd.shadowed = true;
+      return;
     }
-    const manifestCmd = this.getManifestCommand(normalized);
-    if (manifestCmd && !manifestCmd.shadowed) {
-      return { cmd, type: "plugin" };
+    const sysResult = this.systemRouter.resolve([...segs]);
+    if (sysResult.type === "system-cmd" || sysResult.type === "system-group") {
+      this.logger.warn(`[registry] Plugin "${pkg}" tried to register "${segs.join(" ")}" but it collides with a system command. Command will be shadowed.`);
+      cmd.shadowed = true;
+      return;
     }
-    return { cmd, type: "system" };
-  }
-  get(nameOrPath) {
-    if (typeof nameOrPath === "string") {
-      if (this.byName.has(nameOrPath)) {
-        return this.byName.get(nameOrPath);
-      }
-      if (nameOrPath.includes(":")) {
-        const spaceKey = nameOrPath.replace(/:/g, " ");
-        if (this.byName.has(spaceKey)) {
-          return this.byName.get(spaceKey);
-        }
-        const parts = nameOrPath.split(":");
-        if (parts.length === 2) {
-          const spaceKey2 = parts.join(" ");
-          if (this.byName.has(spaceKey2)) {
-            return this.byName.get(spaceKey2);
-          }
-        }
+    if (cmd.manifest.operationType) {
+      const injected = getArchetypeFlags(cmd.manifest.operationType, cmd.manifest.flags ?? []);
+      if (injected.length > 0) {
+        cmd.manifest.flags = [...cmd.manifest.flags ?? [], ...injected];
       }
     }
-    const key = Array.isArray(nameOrPath) ? nameOrPath.join(" ") : nameOrPath;
-    if (this.byName.has(key)) {
-      return this.byName.get(key);
+    if (cmd.manifest.operationType && !cmd.manifest.flags?.some((f) => f.name === "schema")) {
+      cmd.manifest.flags = [...cmd.manifest.flags ?? [], schemaFlag];
     }
-    if (Array.isArray(nameOrPath) && nameOrPath.length === 1 && nameOrPath[0]?.includes(":")) {
-      if (this.byName.has(nameOrPath[0])) {
-        return this.byName.get(nameOrPath[0]);
+    const result = this.pluginRouter.insertCommand(segs, cmd);
+    if (result.collides) {
+      this.logger.warn(
+        `[registry] Plugin "${pkg}" tried to register "${segs.join(" ")}" but namespace "${segs[0]}" is owned by "${result.ownerPackage ?? "unknown"}". Command will be shadowed.`
+      );
+      cmd.shadowed = true;
+      return;
+    }
+    for (const alias of cmd.manifest.aliases ?? []) {
+      const aliasSegs = alias.trim().split(/\s+/).filter(Boolean);
+      if (aliasSegs.length === 0) {
+        continue;
       }
-      const [group, command] = nameOrPath[0].split(":");
-      const legacyKey = `${group} ${command}`;
-      if (this.byName.has(legacyKey)) {
-        return this.byName.get(legacyKey);
+      const aliasValidationError = validateSegments(aliasSegs);
+      if (aliasValidationError) {
+        this.logger.warn(`[registry] Plugin "${pkg}" alias "${alias}" skipped: ${aliasValidationError}`);
+        continue;
       }
-    }
-    if (Array.isArray(nameOrPath)) {
-      const dot = nameOrPath.join(".");
-      if (this.byName.has(dot)) {
-        return this.byName.get(dot);
+      const aliasSysResult = this.systemRouter.resolve([...aliasSegs]);
+      if (aliasSysResult.type === "system-cmd" || aliasSysResult.type === "system-group") {
+        this.logger.warn(`[registry] Plugin "${pkg}" alias "${alias}" collides with a system command and will be skipped.`);
+        continue;
+      }
+      const aliasResult = this.pluginRouter.insertCommand(aliasSegs, cmd);
+      if (aliasResult.collides) {
+        this.logger.warn(
+          `[registry] Plugin "${pkg}" alias "${alias}" conflicts with namespace "${aliasSegs[0]}" owned by "${aliasResult.ownerPackage ?? "unknown"}". Alias skipped.`
+        );
       }
     }
-    if (Array.isArray(nameOrPath) && nameOrPath.length >= 2) {
-      const [groupPrefix, ...cmdParts] = nameOrPath;
-      const cmdName = cmdParts.join(" ");
-      for (const group of this.groups.values()) {
-        if (group.name === groupPrefix || group.name.startsWith(groupPrefix + ":")) {
-          const fullName = `${group.name} ${cmdName}`;
-          if (this.byName.has(fullName)) {
-            return this.byName.get(fullName);
-          }
-        }
+    const v3 = cmd.manifest.manifestV2;
+    if (v3?.cli?.groupMeta) {
+      for (const meta of v3.cli.groupMeta) {
+        const metaSegs = meta.path.trim().split(/\s+/).filter(Boolean);
+        this.pluginRouter.setGroupDescribe(metaSegs, meta.describe);
       }
     }
-    return void 0;
   }
-  list() {
-    const commands = /* @__PURE__ */ new Set();
-    for (const value of this.byName.values()) {
-      if ("run" in value) {
-        commands.add(value);
+  // ─── Resolution ────────────────────────────────────────────────────────────
+  resolve(tokens) {
+    if (tokens.length > 0) {
+      const sysResult = this.systemRouter.resolve(tokens);
+      if (sysResult.type !== "not-found") {
+        return sysResult;
       }
     }
-    return Array.from(commands);
+    return this.pluginRouter.resolve(tokens);
   }
-  listGroups() {
-    return Array.from(this.groups.values());
+  // ─── Tab completion ─────────────────────────────────────────────────────────
+  complete(tokens) {
+    const sysCompletions = this.systemRouter.complete(tokens);
+    const pluginCompletions = this.pluginRouter.complete(tokens);
+    return [.../* @__PURE__ */ new Set([...sysCompletions, ...pluginCompletions])];
   }
-  getGroupsByPrefix(prefix) {
-    const result = [];
-    for (const group of this.groups.values()) {
-      if (group.name === prefix || group.name.startsWith(prefix + ":")) {
-        result.push(group);
-      }
-    }
-    return result;
+  // ─── Query ──────────────────────────────────────────────────────────────────
+  listSystemTopLevel() {
+    return this.systemRouter.listSystemTopLevel();
   }
-  getCommandsByGroupPrefix(prefix) {
-    const result = [];
-    for (const group of this.groups.values()) {
-      if (group.name === prefix || group.name.startsWith(prefix + ":")) {
-        result.push(...group.commands);
-      }
-    }
-    return result;
-  }
-  listProductGroups() {
-    const groups = /* @__PURE__ */ new Map();
-    for (const cmd of this.listManifests()) {
-      const groupName = cmd.manifest.group;
-      if (!groups.has(groupName)) {
-        groups.set(groupName, {
-          name: groupName,
-          describe: cmd.manifest.group,
-          commands: []
-        });
-      }
-      groups.get(groupName).commands.push(cmd);
-    }
-    return Array.from(groups.values());
+  getPluginGroupDescribe(segments) {
+    return this.pluginRouter.getGroupDescribe(segments);
   }
-  getCommandsByGroup(group) {
-    return this.listManifests().filter((cmd) => cmd.manifest.group === group).sort((a, b) => a.manifest.id.localeCompare(b.manifest.id));
+  listCommands() {
+    return this.pluginRouter.listAll();
   }
-  getManifestCommand(idOrAlias) {
-    if (this.manifests.has(idOrAlias)) {
-      return this.manifests.get(idOrAlias);
-    }
-    const canonicalId = this.resolveToCanonical(idOrAlias);
-    if (canonicalId) {
-      return this.pluginByCanonical.get(canonicalId);
-    }
-    for (const cmd of this.pluginByCanonical.values()) {
-      if (cmd.manifest.aliases?.includes(idOrAlias)) {
-        return cmd;
-      }
-      if (cmd.manifest.id.replace(/:/g, " ") === idOrAlias) {
-        return cmd;
-      }
-    }
-    return void 0;
+  listCommandsUnder(segments) {
+    return this.pluginRouter.listUnder(segments);
+  }
+  getCommandAt(segments) {
+    return this.pluginRouter.getAt(segments);
+  }
+  // ─── Partial loading state ─────────────────────────────────────────────────
+  markPartial(v) {
+    this.partial = v;
+  }
+  isPartial() {
+    return this.partial;
+  }
+  // ─── Diagnostics ──────────────────────────────────────────────────────────
+  getDiagnostics() {
+    return {
+      systemCommandCount: this.systemRouter.listAll().length,
+      systemGroupCount: 0,
+      pluginCommandCount: this.pluginRouter.listAll().length,
+      partialLoad: this.partial
+    };
   }
 };
-var registry = new InMemoryRegistry();
-function findCommand(nameOrPath) {
-  return registry.get(nameOrPath);
-}
-function findCommandWithType(nameOrPath) {
-  return registry.getWithType(nameOrPath);
+function createRegistry() {
+  return new TrieBackedRegistry();
 }
+var registry = new TrieBackedRegistry();
 
-export { __test, checkRequires, discoverManifests, discoverManifestsByNamespace, disposeAllPlugins, findCommand, findCommandWithType, preflightManifests, registerManifests, registry, resetInProcCache, runCommand };
+export { TrieBackedRegistry, TrieRouter, __test, checkRequires, createRegistry, discoverManifests, discoverManifestsByNamespace, disposeAllPlugins, levenshtein, loadConfig, preflightManifests, registerManifests, registry, resetInProcCache, runCommand };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map