@jskit-ai/jskit-cli 0.2.26 → 0.2.28

package/src/server/commandHandlers/show/renderPackageText.js

@@ -0,0 +1,332 @@
+import {
+  ensureArray,
+  ensureObject
+} from "../../shared/collectionUtils.js";
+import { createShowRenderHelpers } from "./renderHelpers.js";
+import { writePackageExportsSection } from "./renderPackageExports.js";
+import { writeCapabilitiesSections } from "./renderPackageCapabilities.js";
+
+function renderPackagePayloadText({
+  payload,
+  provides,
+  requires,
+  capabilityDetails,
+  options,
+  stdout,
+  color,
+  resolveWrapWidth,
+  writeWrappedItems,
+  normalizeRelativePosixPath,
+  formatPackageSubpathImport,
+  normalizePlacementOutlets,
+  normalizePlacementContributions,
+  shouldShowPackageExportTarget,
+  classifyExportedSymbols,
+  deriveProviderDisplayName
+} = {}) {
+  const wrapWidth = resolveWrapWidth(stdout, 80);
+  const {
+    writeBindingsSection,
+    writeField,
+    writeRuntimeProviders
+  } = createShowRenderHelpers({
+    stdout,
+    color,
+    options,
+    deriveProviderDisplayName
+  });
+
+  const runtimeMutations = ensureObject(ensureObject(payload.mutations).dependencies).runtime || {};
+  const devMutations = ensureObject(ensureObject(payload.mutations).dependencies).dev || {};
+  const scriptMutations = ensureObject(ensureObject(payload.mutations).packageJson).scripts || {};
+  const textMutations = ensureArray(ensureObject(payload.mutations).text);
+  const runtimeMutationEntries = Object.entries(ensureObject(runtimeMutations));
+  const devMutationEntries = Object.entries(ensureObject(devMutations));
+  const scriptMutationEntries = Object.entries(ensureObject(scriptMutations));
+
+  const introspection = ensureObject(payload.introspection);
+  const introspectionAvailable = introspection.available === true;
+  const introspectionNotes = ensureArray(introspection.notes)
+    .map((value) => String(value || "").trim())
+    .filter(Boolean);
+
+  const metadataApiSummary = ensureObject(ensureObject(payload.metadata).apiSummary);
+  const metadataUi = ensureObject(ensureObject(payload.metadata).ui);
+  const summarySurfaces = ensureArray(metadataApiSummary.surfaces)
+    .map((entry) => {
+      const record = ensureObject(entry);
+      return {
+        subpath: String(record.subpath || "").trim(),
+        summary: String(record.summary || "").trim()
+      };
+    })
+    .filter((entry) => entry.subpath && entry.summary);
+  const containerTokenSummary = ensureObject(metadataApiSummary.containerTokens);
+  const quickServerTokens = ensureArray(containerTokenSummary.server).map((value) => String(value || "").trim()).filter(Boolean);
+  const quickClientTokens = ensureArray(containerTokenSummary.client).map((value) => String(value || "").trim()).filter(Boolean);
+  const metadataUiPlacements = ensureObject(metadataUi.placements);
+  const placementOutlets = normalizePlacementOutlets(metadataUiPlacements.outlets);
+  const placementContributions = normalizePlacementContributions(metadataUiPlacements.contributions);
+  const bindingSections = ensureObject(payload.containerBindings);
+  const serverBindings = ensureArray(bindingSections.server);
+  const clientBindings = ensureArray(bindingSections.client);
+
+  stdout.write(`${color.heading("Information")}\n`);
+  writeField("Package", payload.packageId, color.item);
+  writeField("Version", payload.version, color.installed);
+  if (payload.description) {
+    writeField("Description", payload.description);
+  }
+  writeField("Descriptor", payload.descriptorPath, color.dim);
+
+  if (summarySurfaces.length > 0) {
+    stdout.write(`${color.heading("Summary:")}\n`);
+    for (const summaryEntry of summarySurfaces) {
+      const importPath = formatPackageSubpathImport(payload.packageId, summaryEntry.subpath);
+      stdout.write(`- ${color.item(`${importPath}:`)}\n`);
+      stdout.write(`  ${summaryEntry.summary}\n`);
+    }
+  }
+
+  if (quickServerTokens.length > 0 || quickClientTokens.length > 0) {
+    stdout.write(`${color.heading("Container tokens")} ${color.dim("-- app.make('...'):")}\n`);
+    if (quickServerTokens.length > 0) {
+      stdout.write(`- ${color.installed("server")}: ${quickServerTokens.map((token) => color.item(token)).join(", ")}\n`);
+    }
+    if (quickClientTokens.length > 0) {
+      stdout.write(`- ${color.installed("client")}: ${quickClientTokens.map((token) => color.item(token)).join(", ")}\n`);
+    }
+  }
+
+  if (placementOutlets.length > 0) {
+    stdout.write(`${color.heading(`Placement outlets (accepted host/position pairs) (${placementOutlets.length}):`)}\n`);
+    for (const outlet of placementOutlets) {
+      const surfaces = ensureArray(outlet.surfaces).map((value) => String(value || "").trim()).filter(Boolean);
+      const surfacesLabel = surfaces.length > 0 ? ` ${color.installed(`[surfaces:${surfaces.join(", ")}]`)}` : "";
+      const description = String(outlet.description || "").trim();
+      const descriptionSuffix = description ? `: ${description}` : "";
+      stdout.write(`- ${color.item(`${outlet.host}.${outlet.position}`)}${surfacesLabel}${descriptionSuffix}\n`);
+      if (options.details) {
+        const sourceLabel = String(outlet.source || "").trim();
+        if (sourceLabel) {
+          stdout.write(`  ${color.dim(`source: ${sourceLabel}`)}\n`);
+        }
+      }
+    }
+  }
+
+  if (placementContributions.length > 0) {
+    stdout.write(`${color.heading(`Placement contributions (default entries) (${placementContributions.length}):`)}\n`);
+    for (const contribution of placementContributions) {
+      const surfaces = ensureArray(contribution.surfaces).map((value) => String(value || "").trim()).filter(Boolean);
+      const surfacesLabel = surfaces.length > 0 ? surfaces.join(", ") : "*";
+      const orderSuffix = Number.isFinite(contribution.order) ? ` ${color.installed(`[order:${contribution.order}]`)}` : "";
+      const componentToken = String(contribution.componentToken || "").trim();
+      const componentSuffix = componentToken ? ` ${color.dim(`component:${componentToken}`)}` : "";
+      const description = String(contribution.description || "").trim();
+      const descriptionSuffix = description ? `: ${description}` : "";
+      stdout.write(
+        `- ${color.item(contribution.id)} ${color.dim("->")} ${color.item(`${contribution.host}.${contribution.position}`)} ${color.installed(`[surfaces:${surfacesLabel}]`)}${orderSuffix}${componentSuffix}${descriptionSuffix}\n`
+      );
+      if (options.details) {
+        const when = String(contribution.when || "").trim();
+        if (when) {
+          stdout.write(`  ${color.dim(`when: ${when}`)}\n`);
+        }
+        const sourceLabel = String(contribution.source || "").trim();
+        if (sourceLabel) {
+          stdout.write(`  ${color.dim(`source: ${sourceLabel}`)}\n`);
+        }
+      }
+    }
+  }
+
+  if (introspectionAvailable) {
+    writeBindingsSection("server", serverBindings);
+    writeBindingsSection("client", clientBindings);
+  }
+
+  writePackageExportsSection({
+    payload,
+    options,
+    stdout,
+    color,
+    wrapWidth,
+    normalizeRelativePosixPath,
+    shouldShowPackageExportTarget,
+    classifyExportedSymbols,
+    writeWrappedItems
+  });
+
+  if (payload.dependsOn.length > 0) {
+    writeWrappedItems({
+      stdout,
+      heading: `${color.heading("Depends on")} ${color.installed(`(${payload.dependsOn.length})`)}:`,
+      wrapWidth,
+      items: payload.dependsOn.map((dependencyId) => {
+        const text = String(dependencyId);
+        return {
+          text,
+          rendered: color.item(text)
+        };
+      })
+    });
+  }
+
+  if (runtimeMutationEntries.length > 0) {
+    writeWrappedItems({
+      stdout,
+      heading: color.heading(`Dependency mutations runtime (${runtimeMutationEntries.length}):`),
+      wrapWidth,
+      items: runtimeMutationEntries.map(([dependencyId, versionSpec]) => {
+        const dependencyText = String(dependencyId);
+        const versionText = String(versionSpec);
+        return {
+          text: `${dependencyText} ${versionText}`,
+          rendered: `${color.item(dependencyText)} ${color.installed(versionText)}`
+        };
+      })
+    });
+  }
+
+  writeCapabilitiesSections({
+    payload,
+    provides,
+    requires,
+    capabilityDetails,
+    stdout,
+    color,
+    wrapWidth,
+    writeWrappedItems
+  });
+
+  const uiRoutes = ensureArray(ensureObject(payload.metadata.ui).routes);
+  if (uiRoutes.length > 0) {
+    stdout.write(`${color.heading(`UI routes (${uiRoutes.length}):`)}\n`);
+    for (const route of uiRoutes) {
+      const record = ensureObject(route);
+      const routePath = String(record.path || "").trim();
+      const scope = String(record.scope || "").trim();
+      const routeId = String(record.id || record.name || "").trim();
+      const purpose = String(record.purpose || "").trim();
+      const modeLabel = record.autoRegister === false ? "advisory" : "auto";
+      const scopeLabel = scope ? ` (${scope})` : "";
+      const modePart = ` ${color.installed(`[${modeLabel}]`)}`;
+      const purposePart = purpose ? ` ${purpose}` : "";
+      const idPart = routeId ? ` ${color.installed(`(id:${routeId})`)}` : "";
+      stdout.write(`- ${color.item(routePath)}${color.installed(scopeLabel)}${modePart}${purposePart}${idPart}\n`);
+    }
+  }
+
+  const serverRoutes = ensureArray(ensureObject(payload.metadata.server).routes);
+  if (serverRoutes.length > 0) {
+    stdout.write(`${color.heading(`Server routes (${serverRoutes.length}):`)}\n`);
+    for (const route of serverRoutes) {
+      const record = ensureObject(route);
+      const method = String(record.method || "").trim().toUpperCase();
+      const routePath = String(record.path || "").trim();
+      const summary = String(record.summary || "").trim();
+      const routeLabel = `${method} ${routePath}`.trim();
+      const summarySuffix = summary ? `: ${summary}` : "";
+      stdout.write(`- ${color.item(routeLabel)}${summarySuffix}\n`);
+    }
+  }
+
+  const optionNames = Object.keys(ensureObject(payload.options));
+  if (optionNames.length > 0) {
+    stdout.write(`${color.heading(`Options (${optionNames.length}):`)}\n`);
+    for (const optionName of optionNames) {
+      const schema = ensureObject(payload.options[optionName]);
+      const required = schema.required ? "required" : "optional";
+      const defaultSuffix = schema.defaultValue ? ` (default: ${schema.defaultValue})` : "";
+      stdout.write(`- ${color.item(optionName)} ${color.installed(`[${required}]`)}${color.dim(defaultSuffix)}\n`);
+    }
+  }
+
+  if (devMutationEntries.length > 0) {
+    writeWrappedItems({
+      stdout,
+      heading: color.heading(`Dependency mutations dev (${devMutationEntries.length}):`),
+      wrapWidth,
+      items: devMutationEntries.map(([dependencyId, versionSpec]) => {
+        const dependencyText = String(dependencyId);
+        const versionText = String(versionSpec);
+        return {
+          text: `${dependencyText} ${versionText}`,
+          rendered: `${color.item(dependencyText)} ${color.installed(versionText)}`
+        };
+      })
+    });
+  }
+
+  if (scriptMutationEntries.length > 0) {
+    stdout.write(`${color.heading(`Script mutations (${scriptMutationEntries.length}):`)}\n`);
+    for (const [scriptName, scriptValue] of scriptMutationEntries) {
+      stdout.write(`- ${color.item(scriptName)}: ${String(scriptValue)}\n`);
+    }
+  }
+
+  if (textMutations.length > 0) {
+    stdout.write(`${color.heading(`Text mutations (${textMutations.length}):`)}\n`);
+    for (const mutation of textMutations) {
+      const record = ensureObject(mutation);
+      const op = String(record.op || "").trim();
+      const file = String(record.file || "").trim();
+      const key = String(record.key || "").trim();
+      const position = String(record.position || "").trim();
+      const reason = String(record.reason || "").trim();
+      const reasonSuffix = reason ? `: ${reason}` : "";
+      let mutationLabel = `${op} ${file} ${key}`.trim();
+      if (op === "append-text") {
+        mutationLabel = `${op} ${file}`;
+        if (position) {
+          mutationLabel = `${mutationLabel} [${position}]`;
+        }
+      }
+      stdout.write(`- ${color.item(mutationLabel)}${reasonSuffix}\n`);
+    }
+  }
+
+  if (payload.fileWritePlan.fileCount > 0) {
+    stdout.write(`${color.heading(`File writes (${payload.fileWritePlan.fileCount}):`)}\n`);
+    for (const group of payload.fileWritePlan.groups) {
+      const groupId = String(group.id || "").trim();
+      const category = String(group.category || "").trim();
+      const reason = String(group.reason || "").trim();
+      const files = ensureArray(group.files);
+      let marker = "";
+      if (groupId) {
+        marker = `id:${groupId}`;
+      } else if (category) {
+        marker = `category:${category}`;
+      }
+      const markerSuffix = marker ? ` (${marker})` : "";
+      for (const file of files) {
+        const targetPath = String(ensureObject(file).to || "").trim();
+        if (!targetPath) {
+          continue;
+        }
+        stdout.write(`- ${color.item(targetPath)}${color.installed(markerSuffix)}:\n`);
+        if (reason) {
+          stdout.write(`  ${reason}\n`);
+        }
+      }
+    }
+  }
+
+  const serverProviders = ensureArray(ensureObject(payload.runtime.server).providers);
+  const clientProviders = ensureArray(ensureObject(payload.runtime.client).providers);
+  writeRuntimeProviders("server", serverProviders);
+  writeRuntimeProviders("client", clientProviders);
+
+  if (introspectionNotes.length > 0) {
+    stdout.write(`${color.heading(`Introspection notes (${introspectionNotes.length}):`)}\n`);
+    for (const note of introspectionNotes) {
+      stdout.write(`- ${color.dim(note)}\n`);
+    }
+  }
+}
+
+export {
+  renderPackagePayloadText
+};

package/src/server/commandHandlers/show.js

@@ -0,0 +1,114 @@
+import { createShowRenderHelpers } from "./show/renderHelpers.js";
+import {
+  buildBundleShowPayload,
+  buildPackageShowPayload
+} from "./show/payloads.js";
+import { renderBundlePayloadText } from "./show/renderBundleText.js";
+import { renderPackagePayloadText } from "./show/renderPackageText.js";
+
+function createShowCommand(ctx = {}) {
+  const {
+    createCliError,
+    createColorFormatter,
+    resolveWrapWidth,
+    writeWrappedItems,
+    normalizeRelativePosixPath,
+    resolvePackageIdInput,
+    loadPackageRegistry,
+    loadBundleRegistry,
+    inspectPackageOfferings,
+    buildFileWriteGroups,
+    listDeclaredCapabilities,
+    buildCapabilityDetailsForPackage,
+    formatPackageSubpathImport,
+    normalizePlacementOutlets,
+    normalizePlacementContributions,
+    shouldShowPackageExportTarget,
+    classifyExportedSymbols,
+    deriveProviderDisplayName
+  } = ctx;
+
+  async function commandShow({ positional, options, stdout }) {
+    const id = String(positional[0] || "").trim();
+    if (!id) {
+      throw createCliError("show requires an id.", { showUsage: true });
+    }
+
+    const packageRegistry = await loadPackageRegistry();
+    const bundleRegistry = await loadBundleRegistry();
+    const color = createColorFormatter(stdout);
+    const resolvedPackageId = resolvePackageIdInput(id, packageRegistry);
+
+    if (resolvedPackageId) {
+      const packageEntry = packageRegistry.get(resolvedPackageId);
+      const {
+        payload,
+        provides,
+        requires,
+        capabilityDetails
+      } = await buildPackageShowPayload({
+        packageRegistry,
+        packageEntry,
+        options,
+        inspectPackageOfferings,
+        buildFileWriteGroups,
+        listDeclaredCapabilities,
+        buildCapabilityDetailsForPackage
+      });
+
+      if (options.json) {
+        stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+      } else {
+        renderPackagePayloadText({
+          payload,
+          provides,
+          requires,
+          capabilityDetails,
+          options,
+          stdout,
+          color,
+          resolveWrapWidth,
+          writeWrappedItems,
+          normalizeRelativePosixPath,
+          formatPackageSubpathImport,
+          normalizePlacementOutlets,
+          normalizePlacementContributions,
+          shouldShowPackageExportTarget,
+          classifyExportedSymbols,
+          deriveProviderDisplayName
+        });
+      }
+      return 0;
+    }
+
+    if (bundleRegistry.has(id)) {
+      const bundle = bundleRegistry.get(id);
+      const payload = buildBundleShowPayload(bundle);
+      if (options.json) {
+        stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+      } else {
+        const { writeField } = createShowRenderHelpers({
+          stdout,
+          color,
+          options,
+          deriveProviderDisplayName
+        });
+        renderBundlePayloadText({
+          payload,
+          stdout,
+          color,
+          writeField
+        });
+      }
+      return 0;
+    }
+
+    throw createCliError(`Unknown package or bundle: ${id}`);
+  }
+
+  return {
+    commandShow
+  };
+}
+
+export { createShowCommand };

package/src/server/core/argParser.js

@@ -0,0 +1,144 @@
+import { isKnownCommandName, resolveCommandAlias } from "./commandCatalog.js";
+
+function parseArgs(argv, { createCliError } = {}) {
+  if (typeof createCliError !== "function") {
+    throw new TypeError("parseArgs requires createCliError.");
+  }
+
+  const args = Array.isArray(argv) ? [...argv] : [];
+  const firstToken = String(args[0] || "").trim();
+  if (firstToken === "--help" || firstToken === "-h") {
+    args.shift();
+    return {
+      command: "help",
+      options: {
+        dryRun: false,
+        runNpmInstall: false,
+        full: false,
+        expanded: false,
+        details: false,
+        debugExports: false,
+        checkDiLabels: false,
+        verbose: false,
+        json: false,
+        all: false,
+        help: true,
+        inlineOptions: {}
+      },
+      positional: []
+    };
+  }
+
+  const rawCommand = String(args.shift() || "help").trim() || "help";
+  const command = resolveCommandAlias(rawCommand);
+
+  if (!isKnownCommandName(command)) {
+    throw createCliError(`Unknown command: ${rawCommand}`, { showUsage: true });
+  }
+
+  const options = {
+    dryRun: false,
+    runNpmInstall: false,
+    full: false,
+    expanded: false,
+    details: false,
+    debugExports: false,
+    checkDiLabels: false,
+    verbose: false,
+    json: false,
+    all: false,
+    help: false,
+    inlineOptions: {}
+  };
+  const positional = [];
+
+  while (args.length > 0) {
+    const token = String(args.shift() || "");
+
+    if (token === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+    if (token === "--run-npm-install") {
+      options.runNpmInstall = true;
+      continue;
+    }
+    if (token === "--full") {
+      options.full = true;
+      continue;
+    }
+    if (token === "--expanded") {
+      options.expanded = true;
+      continue;
+    }
+    if (token === "--details") {
+      options.details = true;
+      continue;
+    }
+    if (token === "--debug-exports") {
+      options.debugExports = true;
+      continue;
+    }
+    if (token === "--check-di-labels") {
+      options.checkDiLabels = true;
+      continue;
+    }
+    if (token === "--verbose") {
+      options.verbose = true;
+      continue;
+    }
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--all") {
+      options.all = true;
+      continue;
+    }
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (token.startsWith("--")) {
+      const withoutPrefix = token.slice(2);
+      const hasInlineValue = withoutPrefix.includes("=");
+      const optionName = hasInlineValue ? withoutPrefix.slice(0, withoutPrefix.indexOf("=")) : withoutPrefix;
+      const optionValueRaw = hasInlineValue
+        ? withoutPrefix.slice(withoutPrefix.indexOf("=") + 1)
+        : args.shift();
+
+      if (!/^[a-z][a-z0-9-]*$/.test(optionName)) {
+        throw createCliError(`Unknown option: ${token}`, { showUsage: true });
+      }
+      if (typeof optionValueRaw !== "string") {
+        throw createCliError(`--${optionName} requires a value.`, { showUsage: true });
+      }
+      const optionValue = optionValueRaw.trim();
+      if (!hasInlineValue && optionValue.startsWith("-")) {
+        throw createCliError(`--${optionName} requires a value.`, { showUsage: true });
+      }
+
+      options.inlineOptions[optionName] = optionValue;
+      continue;
+    }
+
+    if (token.startsWith("-")) {
+      throw createCliError(`Unknown option: ${token}`, { showUsage: true });
+    }
+
+    positional.push(token);
+  }
+
+  if (options.debugExports) {
+    options.details = true;
+  }
+
+  return {
+    command,
+    options,
+    positional
+  };
+}
+
+export { parseArgs };

package/src/server/{runtimeDeps.js → core/buildCommandDeps.js}

@@ -49,7 +49,8 @@ function createCommandHandlerDeps(deps = {}) {
     removeEnvValue: deps.removeEnvValue,
     removeManagedViteProxyEntries: deps.removeManagedViteProxyEntries,
     hashBuffer: deps.hashBuffer,
-    rm: deps.rm
+    rm: deps.rm,
+    discoverShellOutletTargetsFromApp: deps.discoverShellOutletTargetsFromApp
   };
 }
 

package/src/server/core/commandCatalog.js

@@ -0,0 +1,47 @@
+const KNOWN_COMMAND_IDS = Object.freeze([
+  "help",
+  "create",
+  "generate",
+  "list",
+  "list-placements",
+  "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"
+});
+
+function resolveCommandAlias(rawCommand) {
+  const command = String(rawCommand || "").trim();
+  if (!command) {
+    return "";
+  }
+  return COMMAND_ALIASES[command] || command;
+}
+
+function isKnownCommandName(rawCommand) {
+  const command = resolveCommandAlias(rawCommand);
+  if (!command) {
+    return false;
+  }
+  return KNOWN_COMMANDS.has(command);
+}
+
+export {
+  KNOWN_COMMAND_IDS,
+  resolveCommandAlias,
+  isKnownCommandName
+};