@jskit-ai/jskit-cli 0.2.27 → 0.2.28

package/src/server/core/createCliRunner.js

@@ -0,0 +1,150 @@
+import {
+  mkdir,
+  rm,
+  writeFile
+} from "node:fs/promises";
+import path from "node:path";
+import { discoverShellOutletTargetsFromApp } from "@jskit-ai/kernel/server/support";
+import { createCliError } from "../shared/cliError.js";
+import {
+  createColorFormatter,
+  resolveWrapWidth,
+  writeWrappedItems
+} from "../shared/outputFormatting.js";
+import { createCommandHandlers } from "./createCommandHandlers.js";
+import { parseArgs } from "./argParser.js";
+import { printUsage, shouldShowCommandHelpOnBareInvocation } from "./usageHelp.js";
+import { createCommandHandlerDeps } from "./buildCommandDeps.js";
+import { createRunCli } from "./dispatchCli.js";
+import {
+  resolvePackageIdInput,
+  resolveInstalledPackageIdInput
+} from "../shared/packageIdHelpers.js";
+import {
+  buildFileWriteGroups,
+  fileExists,
+  hashBuffer,
+  normalizeRelativePath,
+  readFileBufferIfExists
+} from "../cliRuntime/ioAndMigrations.js";
+import {
+  resolveAppRootFromCwd,
+  loadAppPackageJson,
+  loadLockFile,
+  applyPackageJsonField,
+  restorePackageJsonField,
+  removeEnvValue,
+  writeJsonFile
+} from "../cliRuntime/appState.js";
+import {
+  mergePackageRegistries,
+  loadAppLocalPackageRegistry,
+  loadPackageRegistry,
+  resolveInstalledNodeModulePackageEntry,
+  hydratePackageRegistryFromInstalledNodeModules,
+  loadBundleRegistry
+} from "../cliRuntime/packageRegistries.js";
+import {
+  normalizeRelativePosixPath,
+  toFileDependencySpecifier,
+  resolveLocalPackageId,
+  createLocalPackageScaffoldFiles,
+  resolveLocalDependencyOrder
+} from "../cliRuntime/localPackageSupport.js";
+import {
+  listDeclaredCapabilities,
+  buildCapabilityDetailsForPackage,
+  validatePlannedCapabilityClosure
+} from "../cliRuntime/capabilitySupport.js";
+import {
+  classifyExportedSymbols,
+  deriveProviderDisplayName,
+  formatPackageSubpathImport,
+  inspectPackageOfferings,
+  normalizePlacementContributions,
+  normalizePlacementOutlets,
+  shouldShowPackageExportTarget
+} from "../cliRuntime/packageIntrospection.js";
+import {
+  resolvePackageOptions,
+  validateInlineOptionsForPackage
+} from "../cliRuntime/packageOptions.js";
+import {
+  cleanupMaterializedPackageRoots
+} from "../cliRuntime/packageTemplateResolution.js";
+import {
+  applyPackageInstall,
+  applyPackageMigrationsOnly,
+  applyPackagePositioning,
+  adoptAppLocalPackageDependencies
+} from "../cliRuntime/packageInstallFlow.js";
+import {
+  removeManagedViteProxyEntries
+} from "../cliRuntime/viteProxy.js";
+
+const commandHandlers = createCommandHandlers(
+  createCommandHandlerDeps({
+    createCliError,
+    createColorFormatter,
+    resolveWrapWidth,
+    writeWrappedItems,
+    normalizeRelativePath,
+    normalizeRelativePosixPath,
+    resolveAppRootFromCwd,
+    loadLockFile,
+    loadPackageRegistry,
+    loadBundleRegistry,
+    loadAppLocalPackageRegistry,
+    mergePackageRegistries,
+    resolvePackageIdInput,
+    resolveInstalledPackageIdInput,
+    resolveInstalledNodeModulePackageEntry,
+    hydratePackageRegistryFromInstalledNodeModules,
+    validateInlineOptionsForPackage,
+    resolveLocalDependencyOrder,
+    validatePlannedCapabilityClosure,
+    resolvePackageOptions,
+    applyPackageInstall,
+    applyPackageMigrationsOnly,
+    applyPackagePositioning,
+    adoptAppLocalPackageDependencies,
+    loadAppPackageJson,
+    resolveLocalPackageId,
+    createLocalPackageScaffoldFiles,
+    fileExists,
+    applyPackageJsonField,
+    toFileDependencySpecifier,
+    writeJsonFile,
+    writeFile,
+    mkdir,
+    path,
+    inspectPackageOfferings,
+    buildFileWriteGroups,
+    listDeclaredCapabilities,
+    buildCapabilityDetailsForPackage,
+    formatPackageSubpathImport,
+    normalizePlacementOutlets,
+    normalizePlacementContributions,
+    shouldShowPackageExportTarget,
+    classifyExportedSymbols,
+    deriveProviderDisplayName,
+    restorePackageJsonField,
+    readFileBufferIfExists,
+    removeEnvValue,
+    removeManagedViteProxyEntries,
+    hashBuffer,
+    rm,
+    discoverShellOutletTargetsFromApp
+  })
+);
+
+const runCli = createRunCli({
+  parseArgs,
+  printUsage,
+  shouldShowCommandHelpOnBareInvocation,
+  commandHandlers,
+  cleanupMaterializedPackageRoots,
+  createCliError
+});
+
+export { runCli };

package/src/server/core/createCommandHandlers.js

@@ -0,0 +1,43 @@
+import { createCommandHandlerShared } from "../commandHandlers/shared.js";
+import { createListCommands } from "../commandHandlers/list.js";
+import { createShowCommand } from "../commandHandlers/show.js";
+import { createPackageCommands } from "../commandHandlers/package.js";
+import { createHealthCommands } from "../commandHandlers/health.js";
+
+function createCommandHandlers(deps = {}) {
+  const shared = createCommandHandlerShared(deps);
+  const commandContext = {
+    ...deps,
+    ...shared
+  };
+
+  const { commandList, commandListPlacements } = createListCommands(commandContext);
+  const { commandShow } = createShowCommand(commandContext);
+  const {
+    commandCreate,
+    commandAdd,
+    commandGenerate,
+    commandUpdate,
+    commandMigrations,
+    commandPosition,
+    commandRemove
+  } = createPackageCommands(commandContext);
+  const { commandDoctor, commandLintDescriptors } = createHealthCommands(commandContext);
+
+  return {
+    commandList,
+    commandListPlacements,
+    commandShow,
+    commandCreate,
+    commandAdd,
+    commandGenerate,
+    commandMigrations,
+    commandPosition,
+    commandUpdate,
+    commandRemove,
+    commandDoctor,
+    commandLintDescriptors
+  };
+}
+
+export { createCommandHandlers };

package/src/server/{runCli.js → core/dispatchCli.js}

@@ -1,6 +1,7 @@
 function createRunCli({
   parseArgs,
   printUsage,
+  shouldShowCommandHelpOnBareInvocation,
   commandHandlers,
   cleanupMaterializedPackageRoots,
   createCliError
@@ -11,6 +12,9 @@ function createRunCli({
   if (typeof printUsage !== "function") {
     throw new TypeError("createRunCli requires printUsage.");
   }
+  if (typeof shouldShowCommandHelpOnBareInvocation !== "function") {
+    throw new TypeError("createRunCli requires shouldShowCommandHelpOnBareInvocation.");
+  }
   if (!commandHandlers || typeof commandHandlers !== "object") {
     throw new TypeError("createRunCli requires commandHandlers.");
   }
@@ -30,7 +34,13 @@ function createRunCli({
     try {
       const { command, options, positional } = parseArgs(argv, { createCliError });
       if (options.help || command === "help") {
-        printUsage(stdout);
+        const helpCommand = command === "help" ? String(positional[0] || "").trim() : command;
+        printUsage(stdout, { command: helpCommand });
+        return 0;
+      }
+
+      if (shouldShowCommandHelpOnBareInvocation(command, positional)) {
+        printUsage(stdout, { command });
         return 0;
       }
 
@@ -45,6 +55,9 @@ function createRunCli({
       if (command === "list") {
         return await commandHandlers.commandList({ positional, options, cwd, stdout });
       }
+      if (command === "list-placements") {
+        return await commandHandlers.commandListPlacements({ options, cwd, stdout });
+      }
       if (command === "show") {
         return await commandHandlers.commandShow({ positional, options, stdout });
       }

package/src/server/core/usageHelp.js

@@ -0,0 +1,344 @@
+import { resolveCommandAlias } from "./commandCatalog.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: "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.",
+      "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: add-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.",
+      "If no subcommand is provided, the generator primary command runs."
+    ]),
+    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 ShellOutlet targets from app src/ Vue files.",
+      "Includes placement outlets contributed by installed package metadata.",
+      "Shows plain text by default; use --json for structured output."
+    ]),
+    fullUse: "jskit list-placements [--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",
+  "add",
+  "generate",
+  "show",
+  "migrations",
+  "position",
+  "update",
+  "remove"
+]);
+
+function writeLine(stream, line = "") {
+  stream.write(`${line}\n`);
+}
+
+function printTopLevelHelp(stream = process.stderr) {
+  writeLine(stream, "JSKit CLI");
+  writeLine(stream, "");
+  writeLine(stream, "Use: jskit help <command> for command-specific usage.");
+  writeLine(stream, "");
+  writeLine(stream, "Available commands:");
+  for (const entry of COMMAND_OVERVIEW) {
+    writeLine(stream, `  ${entry.command.padEnd(16, " ")} ${entry.summary}`);
+  }
+  writeLine(stream, "");
+  writeLine(stream, "Global flags:");
+  writeLine(stream, "  --dry-run --run-npm-install --json --verbose --help");
+}
+
+function printCommandHelp(stream = process.stderr, command = "") {
+  const resolvedCommand = resolveCommandAlias(command);
+  const entry = COMMAND_HELP[resolvedCommand];
+  if (!entry) {
+    printTopLevelHelp(stream);
+    return;
+  }
+
+  writeLine(stream, `Command: ${entry.title}`);
+  writeLine(stream, "");
+
+  writeLine(stream, "1) Minimal use");
+  writeLine(stream, `   ${entry.minimalUse}`);
+  if (entry.parameters.length > 0) {
+    writeLine(stream, "   Parameters:");
+    for (const parameter of entry.parameters) {
+      writeLine(stream, `   - ${parameter.name}: ${parameter.description}`);
+    }
+  }
+  writeLine(stream, "");
+
+  writeLine(stream, "2) Defaults");
+  for (const defaultLine of entry.defaults) {
+    writeLine(stream, `   - ${defaultLine}`);
+  }
+  writeLine(stream, "");
+
+  writeLine(stream, "3) Full use");
+  writeLine(stream, `   ${entry.fullUse}`);
+}
+
+function printUsage(stream = process.stderr, { command = "" } = {}) {
+  const normalizedCommand = String(command || "").trim();
+  if (!normalizedCommand) {
+    printTopLevelHelp(stream);
+    return;
+  }
+
+  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/index.js

@@ -1 +1 @@
-export { runCli } from "./cliRuntime.js";
+export { runCli } from "./core/createCliRunner.js";

package/src/server/{optionInterpolation.js → shared/optionInterpolation.js}

@@ -187,7 +187,18 @@ function toPluralForm(value) {
 function normalizePathValue(value) {
   return String(value || "")
     .split("/")
-    .map((segment) => wordsToKebab(splitTextIntoWords(segment)))
+    .map((segment) => {
+      const normalizedSegment = String(segment || "").trim();
+      if (!normalizedSegment) {
+        return "";
+      }
+
+      if (/^\[[^\]]+\]$/.test(normalizedSegment)) {
+        return normalizedSegment;
+      }
+
+      return wordsToKebab(splitTextIntoWords(normalizedSegment));
+    })
     .filter(Boolean)
     .join("/");
 }

package/src/server/{pathResolution.js → shared/pathResolution.js}

@@ -5,7 +5,7 @@ import process from "node:process";
 import { fileURLToPath } from "node:url";
 import { createCliError } from "./cliError.js";
 
-const CLI_PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const CLI_PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../..");
 const require = createRequire(import.meta.url);
 
 function resolveCatalogPackagesPath() {