@elizaos/prompts 2.0.0-beta.1 → 2.0.3-beta.3

package/scripts/generate-plugin-action-spec.js

@@ -1,17 +1,8 @@
 #!/usr/bin/env node
-/**
- * Generate plugin action docs spec (best-effort).
- *
- * Scans plugins/** TypeScript action definitions and emits a merged spec file:
- *   packages/prompts/specs/actions/plugins.generated.json
- *
- * This is intentionally dependency-free and uses a small brace-aware extractor to
- * locate `export const X: Action = { ... }` blocks.
- */
-
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { ensureDirectory, readJson, readText } from "./file-utils.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -37,7 +28,16 @@ const RETIRED_IMPLEMENTATION_ONLY_ACTIONS = new Set([
   "ASK_USER_QUESTION",
   "CHECKIN",
   "CHECK_AVAILABILITY",
+  "CLEAR_HISTORY",
+  "CREATE_PLAN",
+  "CREATE_PAYMENT_REQUEST",
+  "DESKTOP",
+  "DEVICE_FILE_READ",
+  "DEVICE_FILE_WRITE",
+  "DEVICE_LIST_DIR",
   "DISCORD_SETUP_CREDENTIALS",
+  "DOC",
+  "DELIVER_PAYMENT_LINK",
   "EDIT",
   "ENTER_WORKTREE",
   "EXIT_WORKTREE",
@@ -67,13 +67,14 @@ const RETIRED_IMPLEMENTATION_ONLY_ACTIONS = new Set([
   "GOOGLE_CALENDAR",
   "LIFEOPS_PAUSE",
   "NOSTR_PUBLISH_PROFILE",
-  "PAYMENT",
   "PLACE_CALL",
   "PLAY_AUDIO",
   "PLAYBACK",
   "READ",
+  "READING",
   "RELEASE_BLOCK",
   "SCREEN_TIME",
+  "SEND_TO_ADMIN",
   "TOGGLE_FEATURE",
   "TAILSCALE",
   "START_TUNNEL",
@@ -82,6 +83,11 @@ const RETIRED_IMPLEMENTATION_ONLY_ACTIONS = new Set([
   "WRITE",
   "LS",
   "MUSIC_LIBRARY",
+  "MYSTICISM_PAYMENT",
+  "VERIFY_PAYMENT_PAYLOAD",
+  "SETTLE_PAYMENT",
+  "AWAIT_PAYMENT_CALLBACK",
+  "CANCEL_PAYMENT_REQUEST",
   "LIST_OVERDUE_FOLLOWUPS",
   "MARK_FOLLOWUP_DONE",
   "SET_FOLLOWUP_THRESHOLD",
@@ -99,19 +105,17 @@ const RETIRED_IMPLEMENTATION_ONLY_ACTIONS = new Set([
   "GET_LINEAR_ACTIVITY",
   "CLEAR_LINEAR_ACTIVITY",
   "SEARCH_LINEAR_ISSUES",
+  "BROWSER_ACTIONS",
+  "WALLET_ACTIONS",
+  "CHARACTER_ACTIONS",
+  "SETTINGS_ACTIONS",
+  "CONNECTOR_ACTIONS",
+  "AUTOMATION_ACTIONS",
+  "PHONE_ACTIONS",
+  "OWNER_ACTIONS",
 ]);
 
-function readText(filePath) {
-  return fs.readFileSync(filePath, "utf-8");
-}
-
-function readJson(filePath) {
-  return JSON.parse(readText(filePath));
-}
-
 /**
- * Template literals are extracted as raw source text; expand known `${...}` patterns
- * so generated JSON/docs contain real strings (Biome flags `${` inside quoted TS strings).
  * @param {string} description
  * @param {string} actionFilePath
  * @returns {string}
@@ -123,7 +127,7 @@ function expandDescriptionTemplateLiterals(description, actionFilePath) {
   const emotesPath = path.join(path.dirname(actionFilePath), "emotes.ts");
   if (!fs.existsSync(emotesPath)) {
     console.warn(
-      `[generate-plugin-action-spec] VALID_EMOTE_IDS placeholder but missing ${emotesPath}`,
+      `[generate-plugin-action-spec] VALID_EMOTE_IDS template expression but missing ${emotesPath}`,
     );
     return description;
   }
@@ -152,18 +156,6 @@ function expandDescriptionTemplateLiterals(description, actionFilePath) {
   return description.replace(/\$\{VALID_EMOTE_IDS\.join\([^)]*\)\}/g, joined);
 }
 
-/**
- * Ensures a directory exists, creating it and parent directories if necessary.
- * @param {string} dir - The directory path to ensure exists
- * @throws {Error} If the directory path is empty or whitespace-only
- */
-function ensureDir(dir) {
-  if (!dir || dir.trim() === "") {
-    throw new Error("Directory path cannot be empty");
-  }
-  fs.mkdirSync(dir, { recursive: true });
-}
-
 function listTsFiles(rootDir) {
   const out = [];
   if (!fs.existsSync(rootDir)) return out;
@@ -174,7 +166,6 @@ function listTsFiles(rootDir) {
     for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
       const full = path.join(dir, ent.name);
       if (ent.isDirectory()) {
-        // ignore generated + dist trees
         if (
           ent.name === "dist" ||
           ent.name === "generated" ||
@@ -184,6 +175,7 @@ function listTsFiles(rootDir) {
         }
         stack.push(full);
       } else if (ent.isFile() && ent.name.endsWith(".ts")) {
+        if (!isActionCandidateFile(full)) continue;
         if (full.includes(`${path.sep}__tests__${path.sep}`)) continue;
         if (full.endsWith(".test.ts")) continue;
         out.push(full);
@@ -193,110 +185,323 @@ function listTsFiles(rootDir) {
   return out.sort((a, b) => a.localeCompare(b));
 }
 
-/**
- * Extract object literal source for `export const X: Action = { ... }`.
- * Returns array of `{ filePath, objectText }`.
- */
-function extractActionObjects(filePath, src) {
-  const results = [];
-  const re = /:\s*Action\s*=\s*\{/gm;
-  for (;;) {
-    const m = re.exec(src);
-    if (m === null) break;
-    const braceStart = m.index + m[0].lastIndexOf("{");
-
-    // Parse balanced braces, skipping strings and comments.
-    let depth = 0;
-    let j = braceStart;
-    let inSingle = false;
-    let inDouble = false;
-    let inTemplate = false;
-    let inLineComment = false;
-    let inBlockComment = false;
-    let escaped = false;
-
-    while (j < src.length) {
-      const ch = src[j];
-      const next = j + 1 < src.length ? src[j + 1] : "";
-
-      if (inLineComment) {
-        if (ch === "\n") inLineComment = false;
-        j++;
+function isActionCandidateFile(filePath) {
+  return (
+    filePath.includes(`${path.sep}actions${path.sep}`) ||
+    filePath.endsWith(`${path.sep}actions.ts`)
+  );
+}
+
+const registeredActionBindingsByPluginRoot = new Map();
+
+function getPluginRoot(filePath) {
+  const relative = path.relative(PLUGINS_ROOT, filePath);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return null;
+  const [pluginName] = relative.split(path.sep);
+  return pluginName ? path.join(PLUGINS_ROOT, pluginName) : null;
+}
+
+function resolveTsImport(entryDir, importPath) {
+  if (!importPath.startsWith(".")) return null;
+  const base = path.resolve(entryDir, importPath);
+  const candidates = [
+    base,
+    base.replace(/\.js$/u, ".ts"),
+    `${base}.ts`,
+    path.join(base, "index.ts"),
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+}
+
+function readBalancedArraySource(src, bracketStart) {
+  let depth = 0;
+  let i = bracketStart;
+  let inSingle = false;
+  let inDouble = false;
+  let inTemplate = false;
+  let inLineComment = false;
+  let inBlockComment = false;
+  let escaped = false;
+
+  while (i < src.length) {
+    const ch = src[i];
+    const next = i + 1 < src.length ? src[i + 1] : "";
+
+    if (inLineComment) {
+      if (ch === "\n") inLineComment = false;
+      i++;
+      continue;
+    }
+    if (inBlockComment) {
+      if (ch === "*" && next === "/") {
+        inBlockComment = false;
+        i += 2;
         continue;
       }
-      if (inBlockComment) {
-        if (ch === "*" && next === "/") {
-          inBlockComment = false;
-          j += 2;
-          continue;
-        }
-        j++;
+      i++;
+      continue;
+    }
+    if (!inSingle && !inDouble && !inTemplate) {
+      if (ch === "/" && next === "/") {
+        inLineComment = true;
+        i += 2;
+        continue;
+      }
+      if (ch === "/" && next === "*") {
+        inBlockComment = true;
+        i += 2;
         continue;
       }
+    }
+
+    if (inSingle) {
+      if (!escaped && ch === "'") inSingle = false;
+      escaped = !escaped && ch === "\\";
+      i++;
+      continue;
+    }
+    if (inDouble) {
+      if (!escaped && ch === '"') inDouble = false;
+      escaped = !escaped && ch === "\\";
+      i++;
+      continue;
+    }
+    if (inTemplate) {
+      if (!escaped && ch === "`") inTemplate = false;
+      escaped = !escaped && ch === "\\";
+      i++;
+      continue;
+    }
+
+    if (ch === "'") {
+      inSingle = true;
+      i++;
+      continue;
+    }
+    if (ch === '"') {
+      inDouble = true;
+      i++;
+      continue;
+    }
+    if (ch === "`") {
+      inTemplate = true;
+      i++;
+      continue;
+    }
+
+    if (ch === "[") depth++;
+    if (ch === "]") {
+      depth--;
+      if (depth === 0) return src.slice(bracketStart, i + 1);
+    }
+    i++;
+  }
+
+  return null;
+}
+
+function extractActionArraySources(src) {
+  const sources = [];
+  const re = /\bactions\s*:\s*\[/gm;
+  for (;;) {
+    const match = re.exec(src);
+    if (match === null) break;
+    const bracketStart = match.index + match[0].lastIndexOf("[");
+    const source = readBalancedArraySource(src, bracketStart);
+    if (source) sources.push(source);
+    re.lastIndex = Math.max(re.lastIndex, bracketStart + (source?.length ?? 1));
+  }
+  return sources;
+}
+
+function extractNamedImports(src, entryDir) {
+  const imports = new Map();
+  const re = /import\s+\{([\s\S]*?)\}\s+from\s+(["'])([^"']+)\2/gm;
+  for (;;) {
+    const match = re.exec(src);
+    if (match === null) break;
+    const resolved = resolveTsImport(entryDir, match[3]);
+    if (!resolved || !isActionCandidateFile(resolved)) continue;
+    for (const rawPart of match[1].split(",")) {
+      const part = rawPart.trim();
+      if (!part) continue;
+      const [importedRaw, localRaw] = part.split(/\s+as\s+/u);
+      const imported = importedRaw.trim();
+      const local = (localRaw ?? importedRaw).trim();
+      if (
+        /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(imported) &&
+        /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(local)
+      ) {
+        imports.set(local, imported);
+      }
+    }
+  }
+  return imports;
+}
+
+function entrypointCandidatesForPlugin(pluginRoot) {
+  return [
+    path.join(pluginRoot, "src", "plugin.ts"),
+    path.join(pluginRoot, "src", "index.ts"),
+    path.join(pluginRoot, "index.ts"),
+  ].filter((candidate) => fs.existsSync(candidate));
+}
+
+function getRegisteredActionBindings(pluginRoot) {
+  if (!pluginRoot) return null;
+  if (registeredActionBindingsByPluginRoot.has(pluginRoot)) {
+    return registeredActionBindingsByPluginRoot.get(pluginRoot);
+  }
+
+  const entrypoints = entrypointCandidatesForPlugin(pluginRoot);
+  const registeredLocalNames = new Set();
+  const registeredExportNames = new Set();
+  let foundActionArray = false;
+
+  for (const entrypoint of entrypoints) {
+    const src = readText(entrypoint);
+    const actionArrays = extractActionArraySources(src);
+    if (actionArrays.length === 0) continue;
+    foundActionArray = true;
+    const imports = extractNamedImports(src, path.dirname(entrypoint));
+    const actionArraySource = actionArrays.join("\n");
+    for (const [localName, importedName] of imports) {
+      const localRe = new RegExp(`\\b${localName}\\b`, "u");
+      if (localRe.test(actionArraySource)) {
+        registeredLocalNames.add(localName);
+        registeredExportNames.add(importedName);
+      }
+    }
+
+    const identifierRe = /\b[A-Za-z_$][A-Za-z0-9_$]*\b/g;
+    for (;;) {
+      const match = identifierRe.exec(actionArraySource);
+      if (match === null) break;
+      registeredLocalNames.add(match[0]);
+    }
+  }
+
+  const result = foundActionArray
+    ? { localNames: registeredLocalNames, exportNames: registeredExportNames }
+    : null;
+  registeredActionBindingsByPluginRoot.set(pluginRoot, result);
+  return result;
+}
+
+function isRegisteredActionObject(filePath, exportName) {
+  const registered = getRegisteredActionBindings(getPluginRoot(filePath));
+  if (!registered || !exportName) return true;
+  return (
+    registered.exportNames.has(exportName) ||
+    registered.localNames.has(exportName)
+  );
+}
 
-      if (!inSingle && !inDouble && !inTemplate) {
-        if (ch === "/" && next === "/") {
-          inLineComment = true;
-          j += 2;
+function extractActionObjects(filePath, src) {
+  const results = [];
+  const patterns = [
+    /\b(?:export\s+)?const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*:\s*Action(?:\s*&\s*\{[\s\S]*?\})?\s*=\s*\{/gm,
+    /\b(?:export\s+)?function\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*\([^)]*\)\s*:\s*Action\s*\{[\s\S]*?\breturn\s+\{/gm,
+  ];
+  for (const re of patterns) {
+    for (;;) {
+      const m = re.exec(src);
+      if (m === null) break;
+      const exportName = m[1];
+      const braceStart = m.index + m[0].lastIndexOf("{");
+
+      let depth = 0;
+      let j = braceStart;
+      let inSingle = false;
+      let inDouble = false;
+      let inTemplate = false;
+      let inLineComment = false;
+      let inBlockComment = false;
+      let escaped = false;
+
+      while (j < src.length) {
+        const ch = src[j];
+        const next = j + 1 < src.length ? src[j + 1] : "";
+
+        if (inLineComment) {
+          if (ch === "\n") inLineComment = false;
+          j++;
           continue;
         }
-        if (ch === "/" && next === "*") {
-          inBlockComment = true;
-          j += 2;
+        if (inBlockComment) {
+          if (ch === "*" && next === "/") {
+            inBlockComment = false;
+            j += 2;
+            continue;
+          }
+          j++;
           continue;
         }
-      }
 
-      if (inSingle) {
-        if (!escaped && ch === "'") inSingle = false;
-        escaped = !escaped && ch === "\\";
-        j++;
-        continue;
-      }
-      if (inDouble) {
-        if (!escaped && ch === '"') inDouble = false;
-        escaped = !escaped && ch === "\\";
-        j++;
-        continue;
-      }
-      if (inTemplate) {
-        if (!escaped && ch === "`") {
-          inTemplate = false;
+        if (!inSingle && !inDouble && !inTemplate) {
+          if (ch === "/" && next === "/") {
+            inLineComment = true;
+            j += 2;
+            continue;
+          }
+          if (ch === "/" && next === "*") {
+            inBlockComment = true;
+            j += 2;
+            continue;
+          }
+        }
+
+        if (inSingle) {
+          if (!escaped && ch === "'") inSingle = false;
+          escaped = !escaped && ch === "\\";
+          j++;
+          continue;
+        }
+        if (inDouble) {
+          if (!escaped && ch === '"') inDouble = false;
+          escaped = !escaped && ch === "\\";
+          j++;
+          continue;
+        }
+        if (inTemplate) {
+          if (!escaped && ch === "`") {
+            inTemplate = false;
+            j++;
+            continue;
+          }
+          escaped = !escaped && ch === "\\";
           j++;
           continue;
         }
-        escaped = !escaped && ch === "\\";
-        j++;
-        continue;
-      }
 
-      if (ch === "'") {
-        inSingle = true;
-        j++;
-        continue;
-      }
-      if (ch === '"') {
-        inDouble = true;
-        j++;
-        continue;
-      }
-      if (ch === "`") {
-        inTemplate = true;
-        j++;
-        continue;
-      }
+        if (ch === "'") {
+          inSingle = true;
+          j++;
+          continue;
+        }
+        if (ch === '"') {
+          inDouble = true;
+          j++;
+          continue;
+        }
+        if (ch === "`") {
+          inTemplate = true;
+          j++;
+          continue;
+        }
 
-      if (ch === "{") depth++;
-      if (ch === "}") {
-        depth--;
-        if (depth === 0) {
-          const objectText = src.slice(braceStart, j + 1);
-          results.push({ filePath, objectText });
-          break;
+        if (ch === "{") depth++;
+        if (ch === "}") {
+          depth--;
+          if (depth === 0) {
+            const objectText = src.slice(braceStart, j + 1);
+            results.push({ filePath, exportName, objectText });
+            break;
+          }
         }
-      }
 
-      j++;
+        j++;
+      }
     }
   }
 
@@ -329,7 +534,6 @@ function isWs(ch) {
 }
 
 function scanTopLevelPropertyValue(objText, propName) {
-  // objText is `{ ... }`
   let i = 0;
   let braceDepth = 0;
   let bracketDepth = 0;
@@ -414,7 +618,6 @@ function scanTopLevelPropertyValue(objText, propName) {
 
     // Top-level inside the object: braceDepth === 1
     if (braceDepth === 1 && bracketDepth === 0) {
-      // Look for `<propName>:` starting at identifier boundary.
       if (objText.startsWith(propName, i)) {
         const before = i > 0 ? objText[i - 1] : "";
         const after =
@@ -446,7 +649,6 @@ function scanTopLevelPropertyValue(objText, propName) {
 function extractTopLevelStringProp(objText, propName) {
   const tail = scanTopLevelPropertyValue(objText, propName);
   if (!tail) return null;
-  // Parse a single string literal token.
   const first = tail.trimStart();
   if (
     !(first.startsWith('"') || first.startsWith("'") || first.startsWith("`"))
@@ -454,7 +656,6 @@ function extractTopLevelStringProp(objText, propName) {
     return null;
   }
 
-  // Grab up to the end of the literal (best-effort, supports escaped quotes).
   const quote = first[0];
   let i = 1;
   let escaped = false;
@@ -765,13 +966,33 @@ function skipTypeAssertionSuffix(src, cursor) {
     const after = i + 2 < src.length ? src[i + 2] : "";
     if (/[A-Za-z0-9_$]/.test(before) || /[A-Za-z0-9_$]/.test(after)) break;
     i = skipTrivia(src, i + 2);
-    while (i < src.length && ![",", "]", "}"].includes(src[i])) i++;
+    let bracketDepth = 0;
+    let angleDepth = 0;
+    let parenDepth = 0;
+    while (i < src.length) {
+      const ch = src[i];
+      if (
+        bracketDepth === 0 &&
+        angleDepth === 0 &&
+        parenDepth === 0 &&
+        [",", "]", "}"].includes(ch)
+      ) {
+        break;
+      }
+      if (ch === "[") bracketDepth++;
+      else if (ch === "]" && bracketDepth > 0) bracketDepth--;
+      else if (ch === "<") angleDepth++;
+      else if (ch === ">" && angleDepth > 0) angleDepth--;
+      else if (ch === "(") parenDepth++;
+      else if (ch === ")" && parenDepth > 0) parenDepth--;
+      i++;
+    }
     i = skipTrivia(src, i);
   }
   return i;
 }
 
-function parseTsLiteralValue(src, cursor = 0) {
+function parseTsLiteralValue(src, cursor = 0, constants = new Map()) {
   let i = skipTrivia(src, cursor);
   const ch = src[i];
   if (ch === undefined) return { value: undefined, end: i };
@@ -793,9 +1014,15 @@ function parseTsLiteralValue(src, cursor = 0) {
         break;
       }
       if (src.startsWith("...", i)) {
-        i = skipUnknownExpression(src, i + 3);
+        const ident = readIdentifier(src, skipTrivia(src, i + 3));
+        if (ident && Array.isArray(constants.get(ident.value))) {
+          arr.push(...constants.get(ident.value));
+          i = ident.end;
+        } else {
+          i = skipUnknownExpression(src, i + 3);
+        }
       } else {
-        const parsed = parseTsLiteralValue(src, i);
+        const parsed = parseTsLiteralValue(src, i, constants);
         if (parsed.value !== undefined) arr.push(parsed.value);
         i = parsed.end;
       }
@@ -845,7 +1072,7 @@ function parseTsLiteralValue(src, cursor = 0) {
         if (src[i] === ",") i++;
         continue;
       }
-      const parsed = parseTsLiteralValue(src, i + 1);
+      const parsed = parseTsLiteralValue(src, i + 1, constants);
       if (parsed.value !== undefined) obj[key] = parsed.value;
       i = skipTrivia(src, parsed.end);
       if (src[i] === ",") i++;
@@ -861,6 +1088,12 @@ function parseTsLiteralValue(src, cursor = 0) {
 
   const ident = readIdentifier(src, i);
   if (ident) {
+    if (constants.has(ident.value)) {
+      return {
+        value: constants.get(ident.value),
+        end: skipTypeAssertionSuffix(src, ident.end),
+      };
+    }
     if (ident.value === "true") {
       return { value: true, end: skipTypeAssertionSuffix(src, ident.end) };
     }
@@ -875,10 +1108,134 @@ function parseTsLiteralValue(src, cursor = 0) {
   return { value: undefined, end: skipUnknownExpression(src, i) };
 }
 
-function extractTopLevelLiteralProp(objText, propName) {
+function extractTopLevelLiteralProp(objText, propName, constants = new Map()) {
   const source = extractTopLevelValueSource(objText, propName);
   if (!source) return undefined;
-  return parseTsLiteralValue(source).value;
+  return parseTsLiteralValue(source, 0, constants).value;
+}
+
+function extractConstLiterals(src) {
+  const constants = new Map();
+  const re = /\bconst\s+([A-Za-z_$][A-Za-z0-9_$]*)(?:\s*:[^=]+)?\s*=\s*/gm;
+  for (;;) {
+    const match = re.exec(src);
+    if (match === null) break;
+    const name = match[1];
+    const initializerStart = skipTrivia(src, re.lastIndex);
+    if (src[initializerStart] === "{") {
+      re.lastIndex = Math.max(
+        skipUnknownExpression(src, initializerStart),
+        re.lastIndex,
+      );
+      continue;
+    }
+    const parsed = parseTsLiteralValue(src, re.lastIndex, constants);
+    if (
+      typeof parsed.value === "string" ||
+      typeof parsed.value === "number" ||
+      typeof parsed.value === "boolean" ||
+      Array.isArray(parsed.value)
+    ) {
+      constants.set(name, parsed.value);
+    }
+    re.lastIndex = Math.max(parsed.end, re.lastIndex);
+  }
+  return constants;
+}
+
+function readArrayLiteralAfter(src, marker) {
+  const markerIndex = src.indexOf(marker);
+  if (markerIndex < 0) return [];
+  const bracketStart = src.indexOf("[", markerIndex);
+  if (bracketStart < 0) return [];
+  const source = readBalancedArraySource(src, bracketStart);
+  if (!source) return [];
+  const parsed = parseTsLiteralValue(source, 0);
+  return Array.isArray(parsed.value) ? parsed.value : [];
+}
+
+function dynamicCommandActionDocs(filePath, name) {
+  const relativePath = path.relative(REPO_ROOT, filePath);
+  const commandActionNameTemplate = "$" + "{key.toUpperCase()}_COMMAND";
+  if (
+    relativePath !==
+      path.join(
+        "plugins",
+        "plugin-commands",
+        "src",
+        "actions",
+        "command-actions.ts",
+      ) ||
+    name !== commandActionNameTemplate
+  ) {
+    return null;
+  }
+
+  const pluginCommandsRoot = path.join(PLUGINS_ROOT, "plugin-commands");
+  const handlersSrc = readText(
+    path.join(pluginCommandsRoot, "src", "actions", "handlers.ts"),
+  );
+  const deterministicCommandKeys = extractConstLiterals(handlersSrc).get(
+    "DETERMINISTIC_COMMAND_KEYS",
+  );
+  if (!Array.isArray(deterministicCommandKeys)) return [];
+
+  const registrySrc = readText(
+    path.join(pluginCommandsRoot, "src", "registry.ts"),
+  );
+  const commandDefinitions = readArrayLiteralAfter(
+    registrySrc,
+    "DEFAULT_COMMANDS",
+  );
+  const definitionsByKey = new Map();
+  for (const definition of commandDefinitions) {
+    if (isRecordValue(definition) && typeof definition.key === "string") {
+      definitionsByKey.set(definition.key, definition);
+    }
+  }
+
+  return deterministicCommandKeys
+    .filter((key) => typeof key === "string")
+    .map((key) => {
+      const definition = definitionsByKey.get(key);
+      const aliases = Array.isArray(definition?.textAliases)
+        ? definition.textAliases.filter((alias) => typeof alias === "string")
+        : [];
+      const doc = {
+        name: `${key.toUpperCase()}_COMMAND`,
+        description:
+          typeof definition?.description === "string"
+            ? definition.description
+            : "",
+        parameters: sanitizeParameters(definition?.args),
+      };
+      if (aliases.length > 0) {
+        doc.similes = aliases;
+      }
+      return doc;
+    });
+}
+
+function resolveRequireActionSpecName(src, source) {
+  const match = source.trim().match(/^([A-Za-z_$][A-Za-z0-9_$]*)\.name$/);
+  if (!match) return null;
+  const specName = match[1];
+  const specRe = new RegExp(
+    `\\bconst\\s+${specName}\\s*=\\s*requireActionSpec\\((["'\`])([^"'\`]+)\\1\\)`,
+  );
+  return specRe.exec(src)?.[2] ?? null;
+}
+
+function extractResolvedStringProp(objText, propName, constants, src) {
+  const direct = extractTopLevelStringProp(objText, propName);
+  if (typeof direct === "string") return direct;
+
+  const source = extractTopLevelValueSource(objText, propName);
+  if (!source) return null;
+  const parsed = parseTsLiteralValue(source, 0, constants).value;
+  if (typeof parsed === "string") return parsed;
+
+  return resolveRequireActionSpecName(src, source);
 }
 
 function isRecordValue(value) {
@@ -1176,13 +1533,6 @@ function main() {
     ["slippage", { description: "Max slippage percentage.", example: 1 }],
   ]);
 
-  function humanizeKey(key) {
-    return key
-      .replaceAll(/[_-]+/g, " ")
-      .replaceAll(/([a-z0-9])([A-Z])/g, "$1 $2")
-      .toLowerCase();
-  }
-
   function inferParamType(objText, key) {
     const re = new RegExp(`state\\?\\.${key}\\s+as\\s+([A-Za-z0-9_]+)`, "g");
     const m = re.exec(objText);
@@ -1206,7 +1556,7 @@ function main() {
       const type = inferParamType(objText, key);
       const known = commonParamDocs.get(key);
       const description =
-        known?.description ?? `The ${humanizeKey(key)} to use.`;
+        known?.description ?? `The ${humanizeParamKey(key)} to use.`;
       const example =
         known?.example ??
         (type === "boolean" ? false : type === "number" ? 1 : "example");
@@ -1269,22 +1619,36 @@ function main() {
   const actionDocsByName = new Map();
 
   for (const filePath of tsFiles) {
-    // Only consider files that look like they might define actions.
-    if (
-      !filePath.includes(`${path.sep}actions${path.sep}`) &&
-      !filePath.endsWith(`${path.sep}actions.ts`)
-    ) {
-      continue;
+    if (process.env.DEBUG_ACTION_SPEC) {
+      console.error(
+        `[generate-plugin-action-spec] ${path.relative(REPO_ROOT, filePath)}`,
+      );
     }
     const src = readText(filePath);
     if (!src.includes(": Action")) continue;
+    const constants = extractConstLiterals(src);
 
     const objects = extractActionObjects(filePath, src);
     for (const obj of objects) {
-      const name = extractTopLevelStringProp(obj.objectText, "name");
+      const name = extractResolvedStringProp(
+        obj.objectText,
+        "name",
+        constants,
+        src,
+      );
       if (!name) continue;
+      if (!isRegisteredActionObject(filePath, obj.exportName)) continue;
       if (RETIRED_IMPLEMENTATION_ONLY_ACTIONS.has(name)) continue;
       if (coreActionNames.has(name)) continue;
+      const dynamicDocs = dynamicCommandActionDocs(filePath, name);
+      if (dynamicDocs) {
+        for (const doc of dynamicDocs) {
+          if (!actionDocsByName.has(doc.name)) {
+            actionDocsByName.set(doc.name, doc);
+          }
+        }
+        continue;
+      }
       const description = expandDescriptionTemplateLiterals(
         extractTopLevelStringProp(obj.objectText, "description") ?? "",
         filePath,
@@ -1293,15 +1657,16 @@ function main() {
         obj.objectText,
         "descriptionCompressed",
       );
-      const similes = extractTopLevelStringArrayProp(obj.objectText, "similes");
+      const similes = extractTopLevelStringArrayProp(
+        obj.objectText,
+        "similes",
+      ).filter((simile) => !RETIRED_IMPLEMENTATION_ONLY_ACTIONS.has(simile));
       const explicitParameters = sanitizeParameters(
-        extractTopLevelLiteralProp(obj.objectText, "parameters"),
+        extractTopLevelLiteralProp(obj.objectText, "parameters", constants),
       );
       const descriptionParameters = inferParametersFromDescription(description);
       const jsonTemplateParameters =
-        explicitParameters.length === 0 &&
-        descriptionParameters.length === 0 &&
-        (name.endsWith("") || description.toLowerCase().includes("router"))
+        explicitParameters.length === 0 && descriptionParameters.length === 0
           ? inferParametersFromJsonTemplate(src)
           : [];
       const parameters =
@@ -1314,7 +1679,6 @@ function main() {
               : inferParameters(obj.objectText);
       const exampleCalls = buildExampleCallForAction(name, parameters);
 
-      // Do not overwrite existing entries; prefer the first seen (stable ordering).
       if (!actionDocsByName.has(name)) {
         actionDocsByName.set(name, {
           name,
@@ -1351,7 +1715,7 @@ function main() {
 
   const outRoot = { version, actions };
 
-  ensureDir(path.dirname(OUTPUT_PATH));
+  ensureDirectory(path.dirname(OUTPUT_PATH));
   fs.writeFileSync(OUTPUT_PATH, `${JSON.stringify(outRoot, null, 2)}\n`);
   console.log(
     `Wrote ${actions.length} plugin actions to ${path.relative(REPO_ROOT, OUTPUT_PATH)}`,