@jskit-ai/jskit-cli 0.2.40 → 0.2.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.40",
+  "version": "0.2.41",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [

package/src/server/cliRuntime/packageInstallFlow.js

@@ -275,7 +275,8 @@ async function applyPackageInstall({
   appPackageJson,
   lock,
   packageRegistry,
-  touchedFiles
+  touchedFiles,
+  reportTemplateFetchStatus = null
 }) {
   const existingInstall = ensureObject(lock.installedPackages[packageEntry.packageId]);
   const existingManaged = ensureObject(existingInstall.managed);
@@ -292,7 +293,11 @@ async function applyPackageInstall({
   const mutationWarnings = [];
   const mutations = ensureObject(packageEntry.descriptor.mutations);
   const fileMutations = ensureArray(mutations.files);
-  const templateRoot = await resolvePackageTemplateRoot({ packageEntry, appRoot });
+  const templateRoot = await resolvePackageTemplateRoot({
+    packageEntry,
+    appRoot,
+    reportTemplateFetchStatus
+  });
   const packageEntryForMutations =
     templateRoot === packageEntry.rootDir
       ? packageEntry

package/src/server/cliRuntime/packageTemplateResolution.js

@@ -68,7 +68,10 @@ async function ensureMaterializedInstallWorkspace(installRoot) {
   );
 }
 
-async function installCatalogPackageIntoCache({ installRoot, packageEntry }) {
+async function installCatalogPackageIntoCache({
+  installRoot,
+  packageEntry
+}) {
   const packageId = String(packageEntry?.packageId || "").trim();
   const version = String(packageEntry?.version || "").trim();
   const packageSpec = version ? `${packageId}@${version}` : packageId;
@@ -124,6 +127,7 @@ async function installCatalogPackageIntoCache({ installRoot, packageEntry }) {
 async function materializeCatalogPackageRoot({
   packageEntry,
   appRoot,
+  reportTemplateFetchStatus = null,
   installCatalogPackage = installCatalogPackageIntoCache
 } = {}) {
   if (!isInternalCatalogPackageEntry(packageEntry)) {
@@ -139,12 +143,20 @@ async function materializeCatalogPackageRoot({
   const installRoot = buildMaterializedInstallRoot({ appRoot, packageEntry });
   const candidateRoot = path.join(installRoot, "node_modules", ...packageId.split("/"));
   const descriptorPath = path.join(candidateRoot, "package.descriptor.mjs");
+  let didInstallPackage = false;
 
   if (!(await fileExists(descriptorPath))) {
+    if (typeof reportTemplateFetchStatus === "function") {
+      reportTemplateFetchStatus({
+        packageEntry,
+        state: "start"
+      });
+    }
     await installCatalogPackage({
       installRoot,
       packageEntry
     });
+    didInstallPackage = true;
   }
 
   if (!(await fileExists(descriptorPath))) {
@@ -153,6 +165,13 @@ async function materializeCatalogPackageRoot({
     );
   }
 
+  if (didInstallPackage && typeof reportTemplateFetchStatus === "function") {
+    reportTemplateFetchStatus({
+      packageEntry,
+      state: "complete"
+    });
+  }
+
   MATERIALIZED_PACKAGE_ROOTS.set(cacheKey, candidateRoot);
   return candidateRoot;
 }
@@ -243,6 +262,7 @@ async function resolvePackageRootFromLocalWorkspace({ packageId }) {
 async function resolvePackageTemplateRoot({
   packageEntry,
   appRoot,
+  reportTemplateFetchStatus = null,
   materializeCatalogRoot = materializeCatalogPackageRoot
 } = {}) {
   const packageRoot = String(packageEntry?.rootDir || "").trim();
@@ -267,7 +287,8 @@ async function resolvePackageTemplateRoot({
 
   const materializedCatalogPackageRoot = await materializeCatalogRoot({
     packageEntry,
-    appRoot
+    appRoot,
+    reportTemplateFetchStatus
   });
   if (materializedCatalogPackageRoot) {
     return materializedCatalogPackageRoot;

package/src/server/commandHandlers/packageCommands/add.js

@@ -38,7 +38,8 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
     adoptAppLocalPackageDependencies,
     writeJsonFile,
     runNpmInstall,
-    renderResolvedSummary
+    renderResolvedSummary,
+    createCatalogFetchStatusReporter = () => () => {}
   } = ctx;
 
   const invocationMode = options?.commandMode === "generate" ? "generate" : "add";
@@ -242,6 +243,9 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
 
   const packagesToInstall = [];
   const resolvedOptionsByPackage = {};
+  const reportTemplateFetchStatus = createCatalogFetchStatusReporter(io, {
+    enabled: options.json !== true
+  });
   const forceReapplyTarget = options?.forceReapplyTarget === true;
   const hasInlineOptions = Object.keys(ensureObject(options.inlineOptions)).length > 0;
   for (const packageId of resolvedPackageIds) {
@@ -293,7 +297,8 @@ async function runPackageAddCommand(ctx = {}, { positional, options, cwd, io })
       appPackageJson: packageJson,
       lock,
       packageRegistry: combinedPackageRegistry,
-      touchedFiles
+      touchedFiles,
+      reportTemplateFetchStatus
     });
     installedPackageRecords.push(managedRecord);
   }

package/src/server/commandHandlers/packageCommands/generate.js

@@ -230,7 +230,8 @@ async function runPackageGenerateCommand(
     hasGeneratorSubcommandDefinition,
     readdir,
     validateInlineOptionValuesForPackage,
-    runGeneratorSubcommand
+    runGeneratorSubcommand,
+    createCatalogFetchStatusReporter = () => () => {}
   } = ctx;
 
   const firstToken = String(positional[0] || "").trim();
@@ -244,6 +245,9 @@ async function runPackageGenerateCommand(
   const targetId = firstToken === "package" ? secondToken : firstToken;
   const subcommandName = firstToken === "package" ? thirdToken : secondToken;
   const subcommandArgs = firstToken === "package" ? positional.slice(3) : positional.slice(2);
+  const reportTemplateFetchStatus = createCatalogFetchStatusReporter(io, {
+    enabled: options.json !== true
+  });
 
   async function resolveGeneratorPackageEntry(packageIdInput = "") {
     const appRoot = await resolveAppRootFromCwd(cwd);
@@ -425,7 +429,8 @@ async function runPackageGenerateCommand(
 
     const templateRoot = await resolvePackageTemplateRoot({
       packageEntry,
-      appRoot
+      appRoot,
+      reportTemplateFetchStatus
     });
     const executablePackageEntry =
       templateRoot === packageEntry.rootDir

package/src/server/commandHandlers/shared.js

@@ -39,6 +39,44 @@ function createCommandHandlerShared(ctx = {}) {
     return lines.join("\n");
   }
 
+  function createCatalogFetchStatusReporter(io = {}, { enabled = true } = {}) {
+    if (enabled !== true) {
+      return () => {};
+    }
+
+    const stdout = io?.stdout;
+    if (!stdout || typeof stdout.write !== "function") {
+      return () => {};
+    }
+
+    const activeFetchLabels = new Set();
+    return ({ packageEntry, state } = {}) => {
+      const packageId = String(packageEntry?.packageId || "").trim();
+      const version = String(packageEntry?.version || "").trim();
+      const packageLabel = version ? `${packageId}@${version}` : packageId;
+      if (!packageLabel) {
+        return;
+      }
+
+      if (state === "start") {
+        if (activeFetchLabels.has(packageLabel)) {
+          return;
+        }
+        activeFetchLabels.add(packageLabel);
+        stdout.write(`Fetching ${packageLabel}...\n`);
+        return;
+      }
+
+      if (state === "complete") {
+        if (!activeFetchLabels.has(packageLabel)) {
+          return;
+        }
+        activeFetchLabels.delete(packageLabel);
+        stdout.write(`Fetching ${packageLabel}... done!\n`);
+      }
+    };
+  }
+
   async function runNpmInstall(appRoot, stderr) {
     await new Promise((resolve, reject) => {
       const child = spawn("npm", ["install"], {
@@ -298,6 +336,7 @@ function createCommandHandlerShared(ctx = {}) {
 
   return {
     renderResolvedSummary,
+    createCatalogFetchStatusReporter,
     runNpmInstall,
     getInstalledDependents,
     resolvePackageKind,

package/src/server/core/commandCatalog.js

@@ -1,50 +1,569 @@
-const KNOWN_COMMAND_IDS = Object.freeze([
-  "help",
-  "create",
-  "generate",
-  "list",
-  "list-placements",
-  "list-link-items",
-  "show",
-  "view",
-  "migrations",
-  "add",
-  "position",
-  "update",
-  "remove",
-  "doctor",
-  "lint-descriptors"
-]);
-
-const KNOWN_COMMANDS = new Set(KNOWN_COMMAND_IDS);
-
-const COMMAND_ALIASES = Object.freeze({
-  view: "show",
-  ls: "list",
-  gen: "generate",
-  lp: "list-placements",
-  lpct: "list-link-items",
-  "list-placement-component-tokens": "list-link-items"
+const OPTION_FLAG_LABELS = Object.freeze({
+  dryRun: "--dry-run",
+  runNpmInstall: "--run-npm-install",
+  full: "--full",
+  expanded: "--expanded",
+  details: "--details",
+  debugExports: "--debug-exports",
+  checkDiLabels: "--check-di-labels",
+  verbose: "--verbose",
+  json: "--json",
+  all: "--all"
 });
 
+const PARSED_BOOLEAN_OPTION_KEYS = Object.freeze(Object.keys(OPTION_FLAG_LABELS));
+
+function isHelpToken(value = "") {
+  return String(value || "").trim().toLowerCase() === "help";
+}
+
+function canDelegateAddInlineOptions(positional = []) {
+  const [first, second, third] = Array.isArray(positional) ? positional : [];
+  const targetType = String(first || "").trim();
+  const targetId = String(second || "").trim();
+  if (!targetType || !targetId || isHelpToken(targetId) || isHelpToken(third)) {
+    return false;
+  }
+  return targetType === "package" || targetType === "bundle";
+}
+
+function canDelegateGenerateInlineOptions(positional = []) {
+  const normalizedPositionals = Array.isArray(positional) ? positional : [];
+  const first = String(normalizedPositionals[0] || "").trim();
+  const second = String(normalizedPositionals[1] || "").trim();
+  const last = String(normalizedPositionals[normalizedPositionals.length - 1] || "").trim();
+  if (!first || !second || isHelpToken(first) || isHelpToken(second) || isHelpToken(last)) {
+    return false;
+  }
+  return true;
+}
+
+function canDelegateMigrationsInlineOptions(positional = []) {
+  const [first, second] = Array.isArray(positional) ? positional : [];
+  return String(first || "").trim().toLowerCase() === "package" && Boolean(String(second || "").trim());
+}
+
+function canDelegatePackageTargetInlineOptions(positional = [], expectedTargetType = "") {
+  const [first, second] = Array.isArray(positional) ? positional : [];
+  const targetType = String(first || "").trim();
+  const targetId = String(second || "").trim();
+  if (!targetType || !targetId || isHelpToken(targetId)) {
+    return false;
+  }
+  return targetType === String(expectedTargetType || "").trim();
+}
+
+const COMMAND_DESCRIPTORS = Object.freeze({
+  help: Object.freeze({
+    command: "help",
+    aliases: Object.freeze([]),
+    showInOverview: false,
+    summary: "Show command-specific usage.",
+    minimalUse: "jskit help [command]",
+    parameters: Object.freeze([
+      Object.freeze({
+        name: "[command]",
+        description: "Optional command name to inspect."
+      })
+    ]),
+    defaults: Object.freeze([
+      "Without a command, help prints the top-level overview.",
+      "Use jskit help <command> for command-specific usage."
+    ]),
+    fullUse: "jskit help [command]",
+    showHelpOnBareInvocation: false,
+    handlerName: "",
+    allowedFlagKeys: Object.freeze([]),
+    inlineOptionMode: "none",
+    allowedValueOptionNames: Object.freeze([])
+  }),
+  create: Object.freeze({
+    command: "create",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Scaffold an app-local runtime package.",
+    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]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandCreate",
+    allowedFlagKeys: Object.freeze(["dryRun", "runNpmInstall", "json"]),
+    inlineOptionMode: "enumerated",
+    allowedValueOptionNames: Object.freeze(["scope", "package-id", "description"])
+  }),
+  add: Object.freeze({
+    command: "add",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Install a runtime bundle or package into the current app.",
+    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]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandAdd",
+    allowedFlagKeys: Object.freeze(["dryRun", "runNpmInstall", "json", "verbose"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: canDelegateAddInlineOptions
+  }),
+  generate: Object.freeze({
+    command: "generate",
+    aliases: Object.freeze(["gen"]),
+    showInOverview: true,
+    summary: "Run a generator package (or generator subcommand).",
+    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]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandGenerate",
+    allowedFlagKeys: Object.freeze(["dryRun", "runNpmInstall", "json", "verbose"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: canDelegateGenerateInlineOptions
+  }),
+  list: Object.freeze({
+    command: "list",
+    aliases: Object.freeze(["ls"]),
+    showInOverview: true,
+    summary: "List bundles, runtime packages, or generator packages.",
+    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]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandList",
+    allowedFlagKeys: Object.freeze(["full", "expanded", "json"]),
+    inlineOptionMode: "none",
+    allowedValueOptionNames: Object.freeze([])
+  }),
+  "list-placements": Object.freeze({
+    command: "list-placements",
+    aliases: Object.freeze(["lp"]),
+    showInOverview: true,
+    summary: "List discovered UI placement targets.",
+    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]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandListPlacements",
+    allowedFlagKeys: Object.freeze(["json"]),
+    inlineOptionMode: "none",
+    allowedValueOptionNames: Object.freeze([])
+  }),
+  "list-link-items": Object.freeze({
+    command: "list-link-items",
+    aliases: Object.freeze(["lpct", "list-placement-component-tokens"]),
+    showInOverview: true,
+    summary: "List available placement link-item component tokens.",
+    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]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandListLinkItems",
+    allowedFlagKeys: Object.freeze(["json", "all"]),
+    inlineOptionMode: "enumerated",
+    allowedValueOptionNames: Object.freeze(["prefix"])
+  }),
+  show: Object.freeze({
+    command: "show",
+    aliases: Object.freeze(["view"]),
+    showInOverview: true,
+    summary: "Show detailed metadata for a bundle or package.",
+    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]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandShow",
+    allowedFlagKeys: Object.freeze(["details", "debugExports", "json"]),
+    inlineOptionMode: "none",
+    allowedValueOptionNames: Object.freeze([])
+  }),
+  migrations: Object.freeze({
+    command: "migrations",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Generate managed migration files only.",
+    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([
+      "Inline options are accepted only for 'migrations package <packageId>'.",
+      "This command only materializes managed migration files; it does not run npm install.",
+      "Without --json, output lists touched migration files."
+    ]),
+    fullUse: "jskit migrations <all|changed|package> [packageId] [--<option> <value>...] [--dry-run] [--json] [--verbose]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandMigrations",
+    allowedFlagKeys: Object.freeze(["dryRun", "json", "verbose"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: canDelegateMigrationsInlineOptions
+  }),
+  position: Object.freeze({
+    command: "position",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Re-apply positioning-only mutations for an installed package.",
+    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.",
+      "This command does not run npm install.",
+      "Reads current options from lock unless overridden inline."
+    ]),
+    fullUse: "jskit position element <packageId> [--<option> <value>...] [--dry-run] [--json]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandPosition",
+    allowedFlagKeys: Object.freeze(["dryRun", "json"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => canDelegatePackageTargetInlineOptions(positional, "element")
+  }),
+  update: Object.freeze({
+    command: "update",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Re-apply one installed package.",
+    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]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandUpdate",
+    allowedFlagKeys: Object.freeze(["dryRun", "runNpmInstall", "json"]),
+    inlineOptionMode: "delegate",
+    allowedValueOptionNames: Object.freeze([]),
+    canDelegateInlineOptions: (positional = []) => canDelegatePackageTargetInlineOptions(positional, "package")
+  }),
+  remove: Object.freeze({
+    command: "remove",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Remove one installed package.",
+    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]",
+    showHelpOnBareInvocation: true,
+    handlerName: "commandRemove",
+    allowedFlagKeys: Object.freeze(["dryRun", "runNpmInstall", "json"]),
+    inlineOptionMode: "none",
+    allowedValueOptionNames: Object.freeze([])
+  }),
+  doctor: Object.freeze({
+    command: "doctor",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Validate lockfile and managed-file integrity.",
+    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]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandDoctor",
+    allowedFlagKeys: Object.freeze(["json"]),
+    inlineOptionMode: "none",
+    allowedValueOptionNames: Object.freeze([])
+  }),
+  "lint-descriptors": Object.freeze({
+    command: "lint-descriptors",
+    aliases: Object.freeze([]),
+    showInOverview: true,
+    summary: "Validate bundle and package descriptor contracts.",
+    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]",
+    showHelpOnBareInvocation: false,
+    handlerName: "commandLintDescriptors",
+    allowedFlagKeys: Object.freeze(["checkDiLabels", "json"]),
+    inlineOptionMode: "none",
+    allowedValueOptionNames: Object.freeze([])
+  })
+});
+
+const COMMAND_ALIAS_TO_ID = Object.freeze(
+  Object.fromEntries(
+    Object.values(COMMAND_DESCRIPTORS)
+      .flatMap((descriptor) =>
+        Array.isArray(descriptor.aliases)
+          ? descriptor.aliases.map((alias) => [alias, descriptor.command])
+          : [])
+      .sort((left, right) => String(left[0] || "").localeCompare(String(right[0] || "")))
+  )
+);
+
+const COMMAND_IDS = Object.freeze(Object.keys(COMMAND_DESCRIPTORS));
+const KNOWN_COMMANDS = new Set(COMMAND_IDS);
+
 function resolveCommandAlias(rawCommand) {
   const command = String(rawCommand || "").trim();
   if (!command) {
     return "";
   }
-  return COMMAND_ALIASES[command] || command;
+  return COMMAND_ALIAS_TO_ID[command] || command;
 }
 
-function isKnownCommandName(rawCommand) {
+function resolveCommandDescriptor(rawCommand) {
   const command = resolveCommandAlias(rawCommand);
   if (!command) {
+    return null;
+  }
+  return COMMAND_DESCRIPTORS[command] || null;
+}
+
+function isKnownCommandName(rawCommand) {
+  const descriptor = resolveCommandDescriptor(rawCommand);
+  return Boolean(descriptor && KNOWN_COMMANDS.has(descriptor.command));
+}
+
+function listOverviewCommandDescriptors() {
+  return Object.values(COMMAND_DESCRIPTORS)
+    .filter((descriptor) => descriptor.showInOverview !== false)
+    .sort((left, right) => left.command.localeCompare(right.command));
+}
+
+function shouldShowCommandHelpOnBareInvocation(command = "", positional = []) {
+  const descriptor = resolveCommandDescriptor(command);
+  if (!descriptor || descriptor.showHelpOnBareInvocation !== true) {
     return false;
   }
-  return KNOWN_COMMANDS.has(command);
+  const argumentList = Array.isArray(positional) ? positional : [];
+  return argumentList.length < 1;
+}
+
+function sortOptionLabels(labels = []) {
+  return [...new Set((Array.isArray(labels) ? labels : []).filter(Boolean))]
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function validateCommandOptions(
+  { command = "", positional = [], options = {} } = {},
+  { createCliError, renderUsage = null } = {}
+) {
+  if (typeof createCliError !== "function") {
+    throw new TypeError("validateCommandOptions requires createCliError.");
+  }
+
+  const descriptor = resolveCommandDescriptor(command);
+  if (!descriptor) {
+    return;
+  }
+
+  const allowedFlagKeys = new Set(Array.isArray(descriptor.allowedFlagKeys) ? descriptor.allowedFlagKeys : []);
+  const unsupportedOptionLabels = [];
+  for (const flagKey of PARSED_BOOLEAN_OPTION_KEYS) {
+    if (options?.[flagKey] !== true) {
+      continue;
+    }
+    if (!allowedFlagKeys.has(flagKey)) {
+      unsupportedOptionLabels.push(OPTION_FLAG_LABELS[flagKey]);
+    }
+  }
+
+  const inlineOptions = options && typeof options === "object" ? options.inlineOptions : null;
+  const inlineOptionNames = Object.keys(inlineOptions && typeof inlineOptions === "object" ? inlineOptions : {});
+  const inlineOptionMode = String(descriptor.inlineOptionMode || "none").trim().toLowerCase() || "none";
+  if (inlineOptionMode === "none") {
+    for (const optionName of inlineOptionNames) {
+      unsupportedOptionLabels.push(`--${optionName}`);
+    }
+  } else if (inlineOptionMode === "enumerated") {
+    const allowedValueOptionNames = new Set(
+      Array.isArray(descriptor.allowedValueOptionNames) ? descriptor.allowedValueOptionNames : []
+    );
+    for (const optionName of inlineOptionNames) {
+      if (!allowedValueOptionNames.has(optionName)) {
+        unsupportedOptionLabels.push(`--${optionName}`);
+      }
+    }
+  } else if (
+    inlineOptionMode === "delegate" &&
+    inlineOptionNames.length > 0 &&
+    typeof descriptor.canDelegateInlineOptions === "function" &&
+    descriptor.canDelegateInlineOptions(positional) !== true
+  ) {
+    for (const optionName of inlineOptionNames) {
+      unsupportedOptionLabels.push(`--${optionName}`);
+    }
+  }
+
+  const normalizedUnsupportedLabels = sortOptionLabels(unsupportedOptionLabels);
+  if (normalizedUnsupportedLabels.length < 1) {
+    return;
+  }
+
+  throw createCliError(
+    `Unknown option${normalizedUnsupportedLabels.length === 1 ? "" : "s"} for command ${descriptor.command}: ${normalizedUnsupportedLabels.join(", ")}.`,
+    {
+      renderUsage: typeof renderUsage === "function" ? renderUsage : null
+    }
+  );
 }
 
 export {
-  KNOWN_COMMAND_IDS,
+  COMMAND_IDS,
+  OPTION_FLAG_LABELS,
   resolveCommandAlias,
-  isKnownCommandName
+  resolveCommandDescriptor,
+  isKnownCommandName,
+  listOverviewCommandDescriptors,
+  shouldShowCommandHelpOnBareInvocation,
+  validateCommandOptions
 };

package/src/server/core/createCliRunner.js

@@ -15,6 +15,10 @@ import {
 import { createCommandHandlers } from "./createCommandHandlers.js";
 import { parseArgs } from "./argParser.js";
 import { printUsage, shouldShowCommandHelpOnBareInvocation } from "./usageHelp.js";
+import {
+  resolveCommandDescriptor,
+  validateCommandOptions
+} from "./commandCatalog.js";
 import { createCommandHandlerDeps } from "./buildCommandDeps.js";
 import { createRunCli } from "./dispatchCli.js";
 import {
@@ -148,6 +152,8 @@ const runCli = createRunCli({
   parseArgs,
   printUsage,
   shouldShowCommandHelpOnBareInvocation,
+  validateCommandOptions,
+  resolveCommandDescriptor,
   commandHandlers,
   cleanupMaterializedPackageRoots,
   createCliError

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