@jskit-ai/jskit-cli 0.2.40 → 0.2.42

package/src/server/core/dispatchCli.js

@@ -2,6 +2,8 @@ function createRunCli({
   parseArgs,
   printUsage,
   shouldShowCommandHelpOnBareInvocation,
+  validateCommandOptions,
+  resolveCommandDescriptor,
   commandHandlers,
   cleanupMaterializedPackageRoots,
   createCliError
@@ -15,6 +17,12 @@ function createRunCli({
   if (typeof shouldShowCommandHelpOnBareInvocation !== "function") {
     throw new TypeError("createRunCli requires shouldShowCommandHelpOnBareInvocation.");
   }
+  if (typeof validateCommandOptions !== "function") {
+    throw new TypeError("createRunCli requires validateCommandOptions.");
+  }
+  if (typeof resolveCommandDescriptor !== "function") {
+    throw new TypeError("createRunCli requires resolveCommandDescriptor.");
+  }
   if (!commandHandlers || typeof commandHandlers !== "object") {
     throw new TypeError("createRunCli requires commandHandlers.");
   }
@@ -33,6 +41,16 @@ function createRunCli({
 
     try {
       const { command, options, positional } = parseArgs(argv, { createCliError });
+      validateCommandOptions(
+        { command, positional, options },
+        {
+          createCliError,
+          renderUsage: () => {
+            const helpCommand = command === "help" ? String(positional[0] || "").trim() : command;
+            printUsage(stderr, { command: helpCommand });
+          }
+        }
+      );
       if (options.help || command === "help") {
         const helpCommand = command === "help" ? String(positional[0] || "").trim() : command;
         printUsage(stdout, { command: helpCommand });
@@ -44,80 +62,22 @@ function createRunCli({
         return 0;
       }
 
-      if (command === "create") {
-        return await commandHandlers.commandCreate({
-          positional,
-          options,
-          cwd,
-          io: { stdin, stdout, stderr }
-        });
-      }
-      if (command === "list") {
-        return await commandHandlers.commandList({ positional, options, cwd, stdout });
-      }
-      if (command === "list-placements") {
-        return await commandHandlers.commandListPlacements({ options, cwd, stdout });
-      }
-      if (command === "list-link-items") {
-        return await commandHandlers.commandListLinkItems({ options, cwd, stdout });
-      }
-      if (command === "show") {
-        return await commandHandlers.commandShow({ positional, options, stdout });
-      }
-      if (command === "migrations") {
-        return await commandHandlers.commandMigrations({
-          positional,
-          options,
-          cwd,
-          io: { stdin, stdout, stderr }
-        });
-      }
-      if (command === "add") {
-        return await commandHandlers.commandAdd({
-          positional,
-          options,
-          cwd,
-          io: { stdin, stdout, stderr }
-        });
-      }
-      if (command === "generate") {
-        return await commandHandlers.commandGenerate({
-          positional,
-          options,
-          cwd,
-          io: { stdin, stdout, stderr }
-        });
-      }
-      if (command === "position") {
-        return await commandHandlers.commandPosition({
-          positional,
-          options,
-          cwd,
-          io: { stdin, stdout, stderr }
-        });
-      }
-      if (command === "update") {
-        return await commandHandlers.commandUpdate({
+      const commandDescriptor = resolveCommandDescriptor(command);
+      const handlerName = String(commandDescriptor?.handlerName || "").trim();
+      if (handlerName) {
+        const commandHandler = commandHandlers[handlerName];
+        if (typeof commandHandler !== "function") {
+          throw createCliError(`Unhandled command: ${command}`, { showUsage: true });
+        }
+        return await commandHandler({
           positional,
           options,
           cwd,
+          stdout,
+          stderr,
           io: { stdin, stdout, stderr }
         });
       }
-      if (command === "remove") {
-        return await commandHandlers.commandRemove({
-          positional,
-          options,
-          cwd,
-          io: { stdin, stdout, stderr }
-        });
-      }
-      if (command === "doctor") {
-        return await commandHandlers.commandDoctor({ cwd, options, stdout });
-      }
-      if (command === "lint-descriptors") {
-        return await commandHandlers.commandLintDescriptors({ options, stdout });
-      }
 
       throw createCliError(`Unhandled command: ${command}`, { showUsage: true });
     } catch (error) {

package/src/server/core/usageHelp.js

@@ -1,323 +1,13 @@
-import { resolveCommandAlias } from "./commandCatalog.js";
+import {
+  listOverviewCommandDescriptors,
+  resolveCommandDescriptor,
+  shouldShowCommandHelpOnBareInvocation
+} from "./commandCatalog.js";
 import {
   createColorFormatter,
   writeWrappedLines
 } from "../shared/outputFormatting.js";
 
-const COMMAND_OVERVIEW = Object.freeze([
-  Object.freeze({
-    command: "create",
-    summary: "Scaffold an app-local runtime package."
-  }),
-  Object.freeze({
-    command: "add",
-    summary: "Install a runtime bundle or package into the current app."
-  }),
-  Object.freeze({
-    command: "generate",
-    summary: "Run a generator package (or generator subcommand)."
-  }),
-  Object.freeze({
-    command: "list",
-    summary: "List bundles, runtime packages, or generator packages."
-  }),
-  Object.freeze({
-    command: "list-placements",
-    summary: "List discovered UI placement targets."
-  }),
-  Object.freeze({
-    command: "list-link-items",
-    summary: "List available placement link-item component tokens."
-  }),
-  Object.freeze({
-    command: "show",
-    summary: "Show detailed metadata for a bundle or package."
-  }),
-  Object.freeze({
-    command: "migrations",
-    summary: "Generate managed migration files only."
-  }),
-  Object.freeze({
-    command: "position",
-    summary: "Re-apply positioning-only mutations for an installed package."
-  }),
-  Object.freeze({
-    command: "update",
-    summary: "Re-apply one installed package."
-  }),
-  Object.freeze({
-    command: "remove",
-    summary: "Remove one installed package."
-  }),
-  Object.freeze({
-    command: "doctor",
-    summary: "Validate lockfile and managed-file integrity."
-  }),
-  Object.freeze({
-    command: "lint-descriptors",
-    summary: "Validate bundle and package descriptor contracts."
-  })
-]);
-
-const COMMAND_HELP = Object.freeze({
-  create: Object.freeze({
-    title: "create",
-    minimalUse: "jskit create package <name>",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "<name>",
-        description: "Local package slug used to scaffold packages/<name>."
-      })
-    ]),
-    defaults: Object.freeze([
-      "No npm install runs unless --run-npm-install is passed.",
-      "If --scope is omitted, scope is inferred from app name.",
-      "If --package-id is omitted, it is derived from scope + name."
-    ]),
-    fullUse: "jskit create package <name> [--scope <scope>] [--package-id <id>] [--description <text>] [--dry-run] [--run-npm-install] [--json]"
-  }),
-  add: Object.freeze({
-    title: "add",
-    minimalUse: "jskit add package <packageId>",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "package | bundle",
-        description: "Target type. Use package for one runtime package, bundle for a bundle id."
-      }),
-      Object.freeze({
-        name: "<packageId|bundleId>",
-        description: "Catalog id or installed node_modules package id."
-      })
-    ]),
-    defaults: Object.freeze([
-      "No npm install runs unless --run-npm-install is passed.",
-      "Short ids resolve to @jskit-ai/<id> when available.",
-      "Running without args lists bundles and runtime packages.",
-      "Existing matching version is skipped unless options force reapply."
-    ]),
-    fullUse: "jskit add <package|bundle> <id> [--<option> <value>...] [--dry-run] [--run-npm-install] [--json] [--verbose]"
-  }),
-  generate: Object.freeze({
-    title: "generate",
-    minimalUse: "jskit generate <generatorId>",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "<generatorId>",
-        description: "Generator package id (for example: crud-ui-generator)."
-      }),
-      Object.freeze({
-        name: "[subcommand]",
-        description: "Optional generator subcommand (for example: scaffold or scaffold-field)."
-      }),
-      Object.freeze({
-        name: "[subcommand args...]",
-        description: "Optional positional args consumed by the chosen subcommand."
-      })
-    ]),
-    defaults: Object.freeze([
-      "No npm install runs unless --run-npm-install is passed.",
-      "Short ids resolve to @jskit-ai/<id> when available.",
-      "Running without args lists available generators.",
-      "Running with only <generatorId> shows generator help.",
-      "Use jskit generate <generatorId> <subcommand> help for subcommand-specific usage."
-    ]),
-    examples: Object.freeze([
-      Object.freeze({
-        label: "Common usage",
-        lines: Object.freeze([
-          "npx jskit generate ui-generator page \\",
-          "  admin/reports/index.vue"
-        ])
-      }),
-      Object.freeze({
-        label: "More advanced usage",
-        lines: Object.freeze([
-          "npx jskit generate crud-ui-generator crud \\",
-          "  admin/catalog/index/products \\",
-          "  --resource-file packages/products/src/shared/productResource.js"
-        ])
-      })
-    ]),
-    fullUse: "jskit generate <generatorId> [subcommand] [subcommand args...] [--<option> <value>...] [--dry-run] [--run-npm-install] [--json] [--verbose]"
-  }),
-  list: Object.freeze({
-    title: "list",
-    minimalUse: "jskit list",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "[mode]",
-        description: "Optional mode: bundles, packages, or generators."
-      })
-    ]),
-    defaults: Object.freeze([
-      "Without mode, list prints bundles + runtime packages + generators.",
-      "placements are listed by the dedicated list-placements command.",
-      "--full and --expanded only affect bundle/package listing views."
-    ]),
-    fullUse: "jskit list [bundles|packages|generators] [--full] [--expanded] [--json]"
-  }),
-  "list-placements": Object.freeze({
-    title: "list-placements",
-    minimalUse: "jskit list-placements",
-    parameters: Object.freeze([]),
-    defaults: Object.freeze([
-      "Discovers placement outlets from app Vue ShellOutlet tags and route meta.",
-      "Includes placement outlets contributed by installed package metadata.",
-      "Shows plain text by default; use --json for structured output."
-    ]),
-    fullUse: "jskit list-placements [--json]"
-  }),
-  "list-link-items": Object.freeze({
-    title: "list-link-items",
-    minimalUse: "jskit list-link-items",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "[--prefix <value>]",
-        description: "Optional token prefix filter (example: local.main. or users.web.shell.)."
-      }),
-      Object.freeze({
-        name: "[--all]",
-        description: "Include all discovered tokens (including non-link-item and client container/runtime tokens)."
-      })
-    ]),
-    defaults: Object.freeze([
-      "Default output shows link-item tokens only (token names ending with link-item).",
-      "Default includes app and installed-package placement-linked token sources.",
-      "Use --prefix to narrow quickly (recommended: --prefix local.main.).",
-      "Use --all when you want the full discovered token set.",
-      "Shows plain text by default; use --json for structured output."
-    ]),
-    fullUse: "jskit list-link-items [--prefix <value>] [--all] [--json]"
-  }),
-  show: Object.freeze({
-    title: "show",
-    minimalUse: "jskit show <id>",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "<id>",
-        description: "Bundle id or package id to inspect."
-      })
-    ]),
-    defaults: Object.freeze([
-      "view is an alias of show.",
-      "Basic output is compact; --details expands capability and runtime sections.",
-      "--debug-exports implies --details."
-    ]),
-    fullUse: "jskit show <id> [--details] [--debug-exports] [--json]"
-  }),
-  migrations: Object.freeze({
-    title: "migrations",
-    minimalUse: "jskit migrations changed",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "<scope>",
-        description: "all | changed | package."
-      }),
-      Object.freeze({
-        name: "[packageId]",
-        description: "Required only when scope is package."
-      })
-    ]),
-    defaults: Object.freeze([
-      "No npm install runs unless --run-npm-install is passed.",
-      "Inline options are accepted only for 'migrations package <packageId>'.",
-      "Without --json, output lists touched migration files."
-    ]),
-    fullUse: "jskit migrations <all|changed|package> [packageId] [--<option> <value>...] [--dry-run] [--json] [--verbose]"
-  }),
-  position: Object.freeze({
-    title: "position",
-    minimalUse: "jskit position element <packageId>",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "element",
-        description: "Target type for positioning command."
-      }),
-      Object.freeze({
-        name: "<packageId>",
-        description: "Installed package id to re-position."
-      })
-    ]),
-    defaults: Object.freeze([
-      "Only positioning mutations are applied.",
-      "No npm install runs unless --run-npm-install is passed.",
-      "Reads current options from lock unless overridden inline."
-    ]),
-    fullUse: "jskit position element <packageId> [--<option> <value>...] [--dry-run] [--json]"
-  }),
-  update: Object.freeze({
-    title: "update",
-    minimalUse: "jskit update package <packageId>",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "package",
-        description: "Target type for update command."
-      }),
-      Object.freeze({
-        name: "<packageId>",
-        description: "Installed package id to re-apply."
-      })
-    ]),
-    defaults: Object.freeze([
-      "No npm install runs unless --run-npm-install is passed.",
-      "Existing lock options are reused unless overridden inline.",
-      "update reuses add package flow with forced reapply."
-    ]),
-    fullUse: "jskit update package <packageId> [--<option> <value>...] [--dry-run] [--run-npm-install] [--json]"
-  }),
-  remove: Object.freeze({
-    title: "remove",
-    minimalUse: "jskit remove package <packageId>",
-    parameters: Object.freeze([
-      Object.freeze({
-        name: "package",
-        description: "Target type for remove command."
-      }),
-      Object.freeze({
-        name: "<packageId>",
-        description: "Installed package id to remove."
-      })
-    ]),
-    defaults: Object.freeze([
-      "No npm install runs unless --run-npm-install is passed.",
-      "Managed files and lock entries are removed for the package.",
-      "Local package source directories are not deleted."
-    ]),
-    fullUse: "jskit remove package <packageId> [--dry-run] [--run-npm-install] [--json]"
-  }),
-  doctor: Object.freeze({
-    title: "doctor",
-    minimalUse: "jskit doctor",
-    parameters: Object.freeze([]),
-    defaults: Object.freeze([
-      "Validates lock entries, managed files, and registry visibility.",
-      "Reports issues as plain text by default.",
-      "Use --json for machine-readable diagnostics."
-    ]),
-    fullUse: "jskit doctor [--json]"
-  }),
-  "lint-descriptors": Object.freeze({
-    title: "lint-descriptors",
-    minimalUse: "jskit lint-descriptors",
-    parameters: Object.freeze([]),
-    defaults: Object.freeze([
-      "Runs descriptor consistency checks.",
-      "check-di-labels is optional and adds stricter DI token label checks.",
-      "Outputs plain text by default and supports --json."
-    ]),
-    fullUse: "jskit lint-descriptors [--check-di-labels] [--json]"
-  })
-});
-
-const BARE_COMMAND_HELP = new Set([
-  "create",
-  "show",
-  "migrations",
-  "position",
-  "update",
-  "remove"
-]);
-
 function appendSeparatedBlocks(lines = [], blocks = []) {
   const normalizedBlocks = Array.isArray(blocks) ? blocks : [];
   for (const [index, block] of normalizedBlocks.entries()) {
@@ -346,18 +36,14 @@ function printTopLevelHelp(stream = process.stderr) {
   lines.push("Use: jskit help <command> for command-specific usage.");
   lines.push("");
   lines.push(color.heading("Available commands:"));
-  for (const entry of COMMAND_OVERVIEW) {
+  for (const entry of listOverviewCommandDescriptors()) {
     lines.push(`  ${color.item(entry.command.padEnd(16, " "))} ${entry.summary}`);
   }
-  lines.push("");
-  lines.push(color.heading("Global flags:"));
-  lines.push("  --dry-run --run-npm-install --json --verbose --help");
   writeHelpLines(stream, lines);
 }
 
 function printCommandHelp(stream = process.stderr, command = "") {
-  const resolvedCommand = resolveCommandAlias(command);
-  const entry = COMMAND_HELP[resolvedCommand];
+  const entry = resolveCommandDescriptor(command);
   if (!entry) {
     printTopLevelHelp(stream);
     return;
@@ -365,7 +51,7 @@ function printCommandHelp(stream = process.stderr, command = "") {
 
   const color = createColorFormatter(stream);
   const lines = [];
-  lines.push(`Command: ${color.emphasis(entry.title)}`);
+  lines.push(`Command: ${color.emphasis(entry.command)}`);
   lines.push("");
 
   let sectionNumber = 1;
@@ -423,15 +109,6 @@ function printUsage(stream = process.stderr, { command = "" } = {}) {
   printCommandHelp(stream, normalizedCommand);
 }
 
-function shouldShowCommandHelpOnBareInvocation(command = "", positional = []) {
-  const resolvedCommand = resolveCommandAlias(command);
-  const argumentList = Array.isArray(positional) ? positional : [];
-  if (!BARE_COMMAND_HELP.has(resolvedCommand)) {
-    return false;
-  }
-  return argumentList.length < 1;
-}
-
 export {
   printUsage,
   shouldShowCommandHelpOnBareInvocation

package/src/server/shared/optionInterpolation.js

@@ -209,6 +209,80 @@ function normalizePathValue(value) {
     .join("/");
 }
 
+function normalizePromptChoices(rawChoices = []) {
+  return ensureArray(rawChoices)
+    .map((entry) => {
+      if (!entry || typeof entry !== "object") {
+        return null;
+      }
+      const value = String(entry.value || "").trim();
+      const label = String(entry.label || value).trim();
+      if (!value || !label) {
+        return null;
+      }
+      return Object.freeze({ value, label });
+    })
+    .filter(Boolean);
+}
+
+function findPromptChoice(promptChoices = [], answer = "") {
+  const normalizedAnswer = String(answer || "").trim();
+  if (!normalizedAnswer) {
+    return null;
+  }
+
+  if (/^\d+$/.test(normalizedAnswer)) {
+    const index = Number.parseInt(normalizedAnswer, 10) - 1;
+    if (index >= 0 && index < promptChoices.length) {
+      return promptChoices[index];
+    }
+  }
+
+  return promptChoices.find((entry) => {
+    return entry.value === normalizedAnswer || entry.label === normalizedAnswer;
+  }) || null;
+}
+
+async function promptForChoice({
+  promptText = "",
+  promptChoices = [],
+  stdin,
+  stdout,
+  required = false,
+  defaultValue = ""
+}) {
+  const rl = createInterface({
+    input: stdin,
+    output: stdout
+  });
+
+  try {
+    while (true) {
+      const answer = String(await rl.question(promptText)).trim();
+      if (!answer && defaultValue) {
+        return defaultValue;
+      }
+      if (!answer && !required) {
+        return "";
+      }
+      if (!answer && required) {
+        throw createCliError("A selection is required.");
+      }
+
+      const matchedChoice = findPromptChoice(promptChoices, answer);
+      if (matchedChoice) {
+        return matchedChoice.value;
+      }
+
+      const values = promptChoices.map((entry) => entry.value).join(", ");
+      stdout.write(`Invalid selection. Enter a number or one of: ${values}.
+`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
 function parseTransformSpec(transform) {
   const normalized = String(transform || "").trim();
   if (!normalized) {
@@ -359,6 +433,7 @@ async function promptForRequiredOption({
   ownerId,
   optionName,
   optionSchema,
+  promptChoices = [],
   stdin = process.stdin,
   stdout = process.stdout
 }) {
@@ -387,6 +462,24 @@ async function promptForRequiredOption({
   const defaultHint = defaultValue ? ` [default: ${defaultValue}]` : "";
   const hintSuffix = promptHint ? ` ${promptHint}` : "";
   const promptText = `${label}${defaultHint}${hintSuffix}: `;
+  const normalizedPromptChoices = normalizePromptChoices(promptChoices);
+
+  if (normalizedPromptChoices.length > 0) {
+    stdout.write(`${label}${defaultHint}${hintSuffix}
+`);
+    normalizedPromptChoices.forEach((entry, index) => {
+      stdout.write(`  ${index + 1}) ${entry.label}
+`);
+    });
+    return promptForChoice({
+      promptText: "Select a surface by number or id: ",
+      promptChoices: normalizedPromptChoices,
+      stdin,
+      stdout,
+      required,
+      defaultValue
+    });
+  }
 
   let answer = "";