@jskit-ai/jskit-cli 0.2.41 → 0.2.43

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

@@ -54,10 +54,15 @@ function buildPackageOptionRows(packageEntry = {}) {
 
   for (const optionName of sortStrings(Object.keys(optionSchemas))) {
     const schema = ensureObject(optionSchemas[optionName]);
+    const allowedValues = ensureArray(schema.allowedValues)
+      .map((value) => String(typeof value === "string" ? value : ensureObject(value).value || "").trim())
+      .filter(Boolean);
     rows.push(Object.freeze({
       name: optionName,
       required: schema.required === true,
       inputType: String(schema.inputType || "text").trim() || "text",
+      validationType: String(schema.validationType || "").trim(),
+      allowedValues,
       defaultValue: String(schema.defaultValue || "").trim(),
       allowEmpty: schema.allowEmpty === true,
       promptLabel: String(schema.promptLabel || "").trim(),
@@ -326,9 +331,12 @@ function formatOptionSummary(optionRow = {}, { color = null } = {}) {
     ? `; default: ${optionRow.defaultValue}`
     : optionalDefaultSuffix;
   const allowEmptySuffix = optionRow.allowEmpty ? "; allow-empty" : "";
+  const allowedValuesHint = Array.isArray(optionRow.allowedValues) && optionRow.allowedValues.length > 0
+    ? `Allowed values: ${optionRow.allowedValues.join(", ")}.`
+    : "";
   const labelParts = [
     String(optionRow.helpLabel || "").trim() || String(optionRow.promptLabel || "").trim(),
-    String(optionRow.helpHint || "").trim() || String(optionRow.promptHint || "").trim()
+    String(optionRow.helpHint || "").trim() || String(optionRow.promptHint || "").trim() || allowedValuesHint
   ].filter(Boolean);
   const label = labelParts.join(". ");
   const normalizedInputType = String(optionRow.inputType || "").trim().toLowerCase();
@@ -337,7 +345,7 @@ function formatOptionSummary(optionRow = {}, { color = null } = {}) {
     : "";
   const baseDescription = label || "No description provided.";
   const description = optionRow.name === "placement-component-token"
-    ? `${baseDescription} Use \`jskit list-link-items\` to discover link-item tokens.`
+    ? `${baseDescription} Use \`jskit list-component-tokens\` to discover link-item tokens.`
     : baseDescription;
   const optionName = `--${optionRow.name}`;
   const renderedOptionName = color ? color.item(optionName) : optionName;

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

@@ -7,6 +7,8 @@ import {
 } from "./discoverabilityHelp.js";
 import { interpolateOptionValue } from "../../shared/optionInterpolation.js";
 
+const SHELL_WEB_PACKAGE_ID = "@jskit-ai/shell-web";
+
 function resolveGeneratorSubcommandDefinitionMetadata(packageEntry = {}, subcommandName = "") {
   const descriptor = packageEntry?.descriptor && typeof packageEntry.descriptor === "object"
     ? packageEntry.descriptor
@@ -27,6 +29,10 @@ function resolveGeneratorSubcommandDefinitionMetadata(packageEntry = {}, subcomm
   return definition && typeof definition === "object" ? definition : {};
 }
 
+function resolveSubcommandRequiresShellWeb(packageEntry = {}, subcommandName = "") {
+  return resolveGeneratorSubcommandDefinitionMetadata(packageEntry, subcommandName)?.requiresShellWeb === true;
+}
+
 function mapDescriptorBackedSubcommandArgsToInlineOptions(
   packageEntry = {},
   subcommandName = "",
@@ -73,40 +79,11 @@ function mapDescriptorBackedSubcommandArgsToInlineOptions(
 }
 
 function resolveSubcommandRequiresInput(packageEntry = {}, subcommandName = "") {
-  const descriptor = packageEntry?.descriptor && typeof packageEntry.descriptor === "object"
-    ? packageEntry.descriptor
-    : {};
-  const optionSchemas = descriptor?.options && typeof descriptor.options === "object"
-    ? descriptor.options
-    : {};
   const subcommandDefinition = resolveGeneratorSubcommandDefinitionMetadata(packageEntry, subcommandName);
   const positionalArgs = Array.isArray(subcommandDefinition?.positionalArgs)
     ? subcommandDefinition.positionalArgs
     : [];
-  if (positionalArgs.length > 0) {
-    return true;
-  }
-  const requiredOptionNames = Array.isArray(subcommandDefinition?.requiredOptionNames)
-    ? subcommandDefinition.requiredOptionNames
-    : [];
-  if (requiredOptionNames.some((optionName) => String(optionName || "").trim().length > 0)) {
-    return true;
-  }
-
-  const optionNames = Array.isArray(subcommandDefinition?.optionNames) && subcommandDefinition.optionNames.length > 0
-    ? subcommandDefinition.optionNames
-    : Object.keys(optionSchemas);
-  for (const optionName of optionNames) {
-    const normalizedOptionName = String(optionName || "").trim();
-    if (!normalizedOptionName) {
-      continue;
-    }
-    const schema = optionSchemas[normalizedOptionName];
-    if (schema && typeof schema === "object" && schema.required === true) {
-      return true;
-    }
-  }
-  return false;
+  return positionalArgs.some((arg) => arg && typeof arg === "object" && arg.required !== false);
 }
 
 function collectUnexpectedGeneratorSubcommandOptionNames(packageEntry = {}, subcommandName = "", inlineOptions = {}) {
@@ -228,6 +205,7 @@ async function runPackageGenerateCommand(
     resolvePackageKind,
     resolveGeneratorPrimarySubcommand,
     hasGeneratorSubcommandDefinition,
+    loadLockFile,
     readdir,
     validateInlineOptionValuesForPackage,
     runGeneratorSubcommand,
@@ -389,6 +367,15 @@ async function runPackageGenerateCommand(
       appRoot,
       optionNames: validatedOptionNames
     });
+    if (resolveSubcommandRequiresShellWeb(packageEntry, normalizedSubcommandName)) {
+      const { lock } = await loadLockFile(appRoot);
+      if (!lock?.installedPackages?.[SHELL_WEB_PACKAGE_ID]) {
+        const commandLabel = `${String(targetId || resolvedPackageId || "").trim() || resolvedPackageId} ${normalizedSubcommandName}`.trim();
+        throw createCliError(
+          `Generator command ${commandLabel} requires ${SHELL_WEB_PACKAGE_ID} to be installed in this app. Run: npx jskit add package shell-web`
+        );
+      }
+    }
 
     const primarySubcommand = resolveGeneratorPrimarySubcommand(packageEntry);
     if (
@@ -461,7 +448,18 @@ async function runPackageGenerateCommand(
     });
   }
 
-  const { packageEntry } = await resolveGeneratorPackageEntry(targetId);
+  const resolvedGeneratorPackage = await resolveGeneratorPackageEntry(targetId);
+  const { packageEntry } = resolvedGeneratorPackage;
+  const primarySubcommand = resolveGeneratorPrimarySubcommand(packageEntry);
+  const hasInlineOptions = Object.keys(options?.inlineOptions || {}).length > 0;
+  if (primarySubcommand && hasInlineOptions) {
+    return runResolvedGeneratorSubcommand({
+      ...resolvedGeneratorPackage,
+      subcommandName: primarySubcommand,
+      subcommandArgs: []
+    });
+  }
+
   renderGeneratePackageHelp({
     io,
     packageEntry,

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

@@ -1,11 +1,20 @@
 import path from "node:path";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import {
+  LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS,
+  findLocalLinkItemDefinition,
+  readLocalLinkItemComponentSource
+} from "@jskit-ai/shell-web/server/support/localLinkItemScaffolds";
 
 const MAIN_CLIENT_PROVIDER_FILE = "packages/main/src/client/providers/MainClientProvider.js";
-const TAB_LINK_COMPONENT_FILE = "src/components/TabLinkItem.vue";
-const TAB_LINK_COMPONENT_NAME = "TabLinkItem";
+const PLACEMENT_FILE = "src/placement.js";
+const PLACEMENT_COMPONENT_TOKEN_PATTERN = /\bcomponentToken\s*:\s*["']([^"']+)["']/g;
 const TAB_LINK_COMPONENT_TOKEN = "local.main.ui.tab-link-item";
 
+const LOCAL_LINK_ITEM_COMPONENT_TOKENS = Object.freeze(
+  LOCAL_LINK_ITEM_COMPONENT_DEFINITIONS.map((entry) => entry.token)
+);
+
 function toPosixPath(value = "") {
   return String(value || "").replaceAll("\\", "/");
 }
@@ -58,7 +67,7 @@ function insertBeforeClassDeclaration(source = "", line = "", { className = "",
   const classPattern = new RegExp(`^class\\s+${String(className || "").trim()}\\b`, "m");
   const classMatch = classPattern.exec(sourceText);
   if (!classMatch) {
-    throw new Error(`crud-ui-generator could not find ${className} class declaration in ${contextFile || "target file"}.`);
+    throw new Error(`placement component provisioning could not find ${className} class declaration in ${contextFile || "target file"}.`);
   }
 
   return {
@@ -67,143 +76,42 @@ function insertBeforeClassDeclaration(source = "", line = "", { className = "",
   };
 }
 
-function renderTabLinkItemSource() {
-  return `<script setup>
-import { computed } from "vue";
-import { useRoute } from "vue-router";
-import { usePaths } from "@jskit-ai/users-web/client/composables/usePaths";
-import { useWorkspaceRouteContext } from "@jskit-ai/users-web/client/composables/useWorkspaceRouteContext";
-
-const props = defineProps({
-  label: {
-    type: String,
-    default: ""
-  },
-  to: {
-    type: String,
-    default: ""
-  },
-  surface: {
-    type: String,
-    default: ""
-  },
-  workspaceSuffix: {
-    type: String,
-    default: "/"
-  },
-  nonWorkspaceSuffix: {
-    type: String,
-    default: "/"
-  },
-  disabled: {
-    type: Boolean,
-    default: false
-  }
-});
-
-const route = useRoute();
-const paths = usePaths();
-const { currentSurfaceId, workspaceSlugFromRoute } = useWorkspaceRouteContext();
-
-function normalizePathname(pathname = "") {
-  const source = String(pathname || "").trim();
-  if (!source) {
-    return "";
+async function collectProvisionableLocalPlacementComponentTokensFromApp({
+  appRoot = ""
+} = {}) {
+  const placementAbsolutePath = path.join(appRoot, PLACEMENT_FILE);
+  const placementSource = await readUtf8FileIfExists(placementAbsolutePath);
+  if (!placementSource) {
+    return [];
   }
 
-  const queryIndex = source.indexOf("?");
-  const hashIndex = source.indexOf("#");
-  const cutoff =
-    queryIndex < 0
-      ? hashIndex
-      : hashIndex < 0
-        ? queryIndex
-        : Math.min(queryIndex, hashIndex);
-  return cutoff < 0 ? source : source.slice(0, cutoff);
-}
-
-function interpolateBracketParams(pathTemplate = "", params = {}) {
-  const source = String(pathTemplate || "").trim();
-  if (!source) {
-    return "";
+  const collectedTokens = new Set();
+  for (const match of String(placementSource).matchAll(PLACEMENT_COMPONENT_TOKEN_PATTERN)) {
+    const componentToken = String(match[1] || "").trim();
+    if (!findLocalLinkItemDefinition(componentToken)) {
+      continue;
+    }
+    collectedTokens.add(componentToken);
   }
 
-  return source.replace(/\\[([^\\]]+)\\]/g, (_match, rawKey) => {
-    const key = String(rawKey || "").trim();
-    if (!key) {
-      return "";
-    }
-    const value = params?.[key];
-    return value == null ? "[" + key + "]" : encodeURIComponent(String(value));
-  });
+  return Array.from(collectedTokens).sort((left, right) => left.localeCompare(right));
 }
 
-const targetSurfaceId = computed(() => {
-  const explicitSurface = String(props.surface || "").trim().toLowerCase();
-  if (explicitSurface && explicitSurface !== "*") {
-    return explicitSurface;
-  }
-  return String(currentSurfaceId.value || paths.currentSurfaceId.value || "").trim().toLowerCase();
-});
-
-const resolvedTo = computed(() => {
-  const explicitTo = String(props.to || "").trim();
-  if (explicitTo) {
-    if (explicitTo.startsWith("./")) {
-      const workspaceSlug = String(workspaceSlugFromRoute.value || "").trim();
-      const suffixTemplate = workspaceSlug ? props.workspaceSuffix : props.nonWorkspaceSuffix;
-      const interpolatedSuffix = interpolateBracketParams(suffixTemplate, route.params || {});
-      if (interpolatedSuffix && !interpolatedSuffix.includes("[")) {
-        return paths.page(interpolatedSuffix, {
-          surface: targetSurfaceId.value,
-          mode: "auto"
-        });
-      }
-    }
-    return explicitTo;
+async function resolveProvisionableLocalPlacementComponentTokens({
+  appRoot = "",
+  componentTokens = []
+} = {}) {
+  const collectedTokens = new Set(
+    (Array.isArray(componentTokens) ? componentTokens : [])
+      .map((value) => String(value || "").trim())
+      .filter((value) => Boolean(findLocalLinkItemDefinition(value)))
+  );
+
+  for (const componentToken of await collectProvisionableLocalPlacementComponentTokensFromApp({ appRoot })) {
+    collectedTokens.add(componentToken);
   }
 
-  const workspaceSlug = String(workspaceSlugFromRoute.value || "").trim();
-  const suffix = workspaceSlug ? props.workspaceSuffix : props.nonWorkspaceSuffix;
-  const normalizedSuffix = String(suffix || "/").trim() || "/";
-  return paths.page(normalizedSuffix, {
-    surface: targetSurfaceId.value,
-    mode: "auto"
-  });
-});
-
-const isActive = computed(() => {
-  const targetPath = normalizePathname(resolvedTo.value);
-  const currentPath = normalizePathname(route.fullPath || route.path || "");
-  if (!targetPath || !currentPath) {
-    return false;
-  }
-  return currentPath === targetPath || currentPath.startsWith(\`\${targetPath}/\`);
-});
-</script>
-
-<template>
-  <v-btn
-    class="tab-link-item"
-    variant="text"
-    size="small"
-    :to="resolvedTo"
-    :active="isActive"
-    :disabled="disabled"
-    color="primary"
-  >
-    {{ label || "Tab" }}
-  </v-btn>
-</template>
-
-<style scoped>
-.tab-link-item {
-  text-transform: none;
-  font-weight: 600;
-  border-radius: 999px;
-}
-</style>
-`;
+  return Array.from(collectedTokens).sort((left, right) => left.localeCompare(right));
 }
 
 async function readUtf8FileIfExists(absolutePath = "") {
@@ -217,28 +125,35 @@ async function readUtf8FileIfExists(absolutePath = "") {
   }
 }
 
-async function ensureTabLinkItemComponentFile({ appRoot = "", dryRun = false, touchedFiles = new Set() } = {}) {
-  const componentRelativePath = TAB_LINK_COMPONENT_FILE;
+async function ensureProvisionedComponentFile(
+  definition,
+  {
+    appRoot = "",
+    dryRun = false,
+    touchedFiles = new Set()
+  } = {}
+) {
+  const componentRelativePath = definition.componentFile;
   const componentAbsolutePath = path.join(appRoot, componentRelativePath);
   const existingComponentSource = await readUtf8FileIfExists(componentAbsolutePath);
   if (existingComponentSource) {
     return;
   }
 
-  if (dryRun !== true) {
-    await mkdir(path.dirname(componentAbsolutePath), { recursive: true });
-    await writeFile(componentAbsolutePath, renderTabLinkItemSource(), "utf8");
-  }
+    if (dryRun !== true) {
+      await mkdir(path.dirname(componentAbsolutePath), { recursive: true });
+      await writeFile(componentAbsolutePath, await readLocalLinkItemComponentSource(definition), "utf8");
+    }
   touchedFiles.add(toPosixPath(componentRelativePath));
 }
 
-function hasTabLinkItemTokenRegistration(providerSource = "") {
-  const tokenPattern = TAB_LINK_COMPONENT_TOKEN.replaceAll(".", "\\.");
+function hasProvisionedTokenRegistration(providerSource = "", componentToken = "") {
+  const tokenPattern = String(componentToken || "").replaceAll(".", "\\.");
   const pattern = new RegExp(`registerMainClientComponent\\(\\s*"${tokenPattern}"\\s*,`, "m");
   return pattern.test(String(providerSource || ""));
 }
 
-async function loadMainClientProviderSource({ appRoot = "", createCliError } = {}) {
+async function loadMainClientProviderSource({ appRoot = "", createCliError, componentToken = "" } = {}) {
   const providerAbsolutePath = path.join(appRoot, MAIN_CLIENT_PROVIDER_FILE);
   let providerSource = "";
   try {
@@ -246,7 +161,7 @@ async function loadMainClientProviderSource({ appRoot = "", createCliError } = {
   } catch (error) {
     if (error && error.code === "ENOENT") {
       throw createCliError(
-        `crud-ui-generator placement component token "${TAB_LINK_COMPONENT_TOKEN}" requires ${MAIN_CLIENT_PROVIDER_FILE}.`
+        `placement component token "${componentToken}" requires ${MAIN_CLIENT_PROVIDER_FILE}.`
       );
     }
     throw error;
@@ -254,31 +169,35 @@ async function loadMainClientProviderSource({ appRoot = "", createCliError } = {
 
   if (!/\bregisterMainClientComponent\s*\(/.test(providerSource)) {
     throw createCliError(
-      `crud-ui-generator placement component token "${TAB_LINK_COMPONENT_TOKEN}" could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
+      `placement component token "${componentToken}" could not find registerMainClientComponent() contract in ${MAIN_CLIENT_PROVIDER_FILE}.`
     );
   }
 
   return providerSource;
 }
 
-async function ensureTabLinkItemProviderRegistration({
-  appRoot = "",
-  createCliError,
-  dryRun = false,
-  touchedFiles = new Set()
-} = {}) {
+async function ensureProvisionedProviderRegistration(
+  definition,
+  {
+    appRoot = "",
+    createCliError,
+    dryRun = false,
+    touchedFiles = new Set()
+  } = {}
+) {
   const providerRelativePath = MAIN_CLIENT_PROVIDER_FILE;
   const providerAbsolutePath = path.join(appRoot, providerRelativePath);
   const providerSource = await loadMainClientProviderSource({
     appRoot,
-    createCliError
+    createCliError,
+    componentToken: definition.token
   });
-  if (hasTabLinkItemTokenRegistration(providerSource)) {
+  if (hasProvisionedTokenRegistration(providerSource, definition.token)) {
     return false;
   }
 
-  const importLine = `import ${TAB_LINK_COMPONENT_NAME} from "/${toPosixPath(TAB_LINK_COMPONENT_FILE)}";`;
-  const registerLine = `registerMainClientComponent("${TAB_LINK_COMPONENT_TOKEN}", () => ${TAB_LINK_COMPONENT_NAME});`;
+  const importLine = `import ${definition.componentName} from "/${toPosixPath(definition.componentFile)}";`;
+  const registerLine = `registerMainClientComponent("${definition.token}", () => ${definition.componentName});`;
 
   const importApplied = insertImportIfMissing(providerSource, importLine);
   const registerApplied = insertBeforeClassDeclaration(importApplied.content, registerLine, {
@@ -297,30 +216,70 @@ async function ensureTabLinkItemProviderRegistration({
   return true;
 }
 
-async function ensureLocalMainTabLinkItemProvisioning({
+async function ensureLocalMainPlacementComponentProvisioning({
   appRoot = "",
   createCliError,
   dryRun = false,
-  touchedFiles = new Set()
+  touchedFiles = new Set(),
+  componentTokens = []
 } = {}) {
-  const providerSource = await loadMainClientProviderSource({
-    appRoot,
-    createCliError
-  });
-  if (hasTabLinkItemTokenRegistration(providerSource)) {
-    return;
+  const uniqueComponentTokens = Array.from(
+    new Set(
+      (Array.isArray(componentTokens) ? componentTokens : [])
+        .map((value) => String(value || "").trim())
+        .filter(Boolean)
+    )
+  );
+
+  for (const componentToken of uniqueComponentTokens) {
+    const definition = findLocalLinkItemDefinition(componentToken);
+    if (!definition) {
+      continue;
+    }
+
+    const providerSource = await loadMainClientProviderSource({
+      appRoot,
+      createCliError,
+      componentToken: definition.token
+    });
+    if (hasProvisionedTokenRegistration(providerSource, definition.token)) {
+      continue;
+    }
+
+    await ensureProvisionedComponentFile(definition, {
+      appRoot,
+      dryRun,
+      touchedFiles
+    });
+    await ensureProvisionedProviderRegistration(definition, {
+      appRoot,
+      createCliError,
+      dryRun,
+      touchedFiles
+    });
   }
+}
 
-  await ensureTabLinkItemComponentFile({ appRoot, dryRun, touchedFiles });
-  await ensureTabLinkItemProviderRegistration({
+async function ensureLocalMainTabLinkItemProvisioning({
+  appRoot = "",
+  createCliError,
+  dryRun = false,
+  touchedFiles = new Set()
+} = {}) {
+  return ensureLocalMainPlacementComponentProvisioning({
     appRoot,
     createCliError,
     dryRun,
-    touchedFiles
+    touchedFiles,
+    componentTokens: [TAB_LINK_COMPONENT_TOKEN]
   });
 }
 
 export {
+  LOCAL_LINK_ITEM_COMPONENT_TOKENS,
   TAB_LINK_COMPONENT_TOKEN,
+  collectProvisionableLocalPlacementComponentTokensFromApp,
+  resolveProvisionableLocalPlacementComponentTokens,
+  ensureLocalMainPlacementComponentProvisioning,
   ensureLocalMainTabLinkItemProvisioning
 };

package/src/server/commandHandlers/shared.js

@@ -1,10 +1,14 @@
 import { spawn } from "node:child_process";
-import { pathToFileURL } from "node:url";
+import { importFreshModuleFromAbsolutePath } from "@jskit-ai/kernel/server/support";
 import {
   ensureArray,
   ensureObject,
   sortStrings
 } from "../shared/collectionUtils.js";
+import {
+  ensureLocalMainPlacementComponentProvisioning,
+  resolveProvisionableLocalPlacementComponentTokens
+} from "./packageCommands/tabLinkItemProvisioning.js";
 
 function createCommandHandlerShared(ctx = {}) {
   const {
@@ -242,7 +246,7 @@ function createCommandHandlerShared(ctx = {}) {
 
     let moduleNamespace = null;
     try {
-      moduleNamespace = await import(`${pathToFileURL(entrypointPath).href}?t=${Date.now()}_${Math.random()}`);
+      moduleNamespace = await importFreshModuleFromAbsolutePath(entrypointPath);
     } catch (error) {
       throw createCliError(
         `Unable to load generator subcommand entrypoint ${normalizeRelativePath(appRoot, entrypointPath)}: ${String(error?.message || error || "unknown error")}`
@@ -268,9 +272,25 @@ function createCommandHandlerShared(ctx = {}) {
       dryRun: dryRun === true
     });
     const payload = ensureObject(result);
-    const touchedFiles = sortStrings(
+    const touchedFileSet = new Set(
       ensureArray(payload.touchedFiles).map((value) => String(value || "").trim()).filter(Boolean)
     );
+    const placementComponentTokens = await resolveProvisionableLocalPlacementComponentTokens({
+      appRoot,
+      componentTokens: ensureArray(payload.placementComponentTokens)
+        .map((value) => String(value || "").trim())
+        .filter(Boolean)
+    });
+    if (placementComponentTokens.length > 0) {
+      await ensureLocalMainPlacementComponentProvisioning({
+        appRoot,
+        createCliError,
+        dryRun: dryRun === true,
+        touchedFiles: touchedFileSet,
+        componentTokens: placementComponentTokens
+      });
+    }
+    const touchedFiles = sortStrings([...touchedFileSet]);
     const summary = String(payload.summary || "").trim();
 
     if (json) {

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

@@ -99,13 +99,13 @@ function renderPackagePayloadText({
   }
 
   if (placementOutlets.length > 0) {
-    stdout.write(`${color.heading(`Placement outlets (accepted host/position pairs) (${placementOutlets.length}):`)}\n`);
+    stdout.write(`${color.heading(`Placement outlets (${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`);
+      stdout.write(`- ${color.item(outlet.target)}${surfacesLabel}${descriptionSuffix}\n`);
       if (options.details) {
         const sourceLabel = String(outlet.source || "").trim();
         if (sourceLabel) {
@@ -126,7 +126,7 @@ function renderPackagePayloadText({
       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`
+        `- ${color.item(contribution.id)} ${color.dim("->")} ${color.item(contribution.target)} ${color.installed(`[surfaces:${surfacesLabel}]`)}${orderSuffix}${componentSuffix}${descriptionSuffix}\n`
       );
       if (options.details) {
         const when = String(contribution.when || "").trim();

package/src/server/core/argParser.js

@@ -56,6 +56,11 @@ function parseArgs(argv, { createCliError } = {}) {
   while (args.length > 0) {
     const token = String(args.shift() || "");
 
+    if (token === "--") {
+      positional.push(...args.map((value) => String(value || "")));
+      break;
+    }
+
     if (token === "--dry-run") {
       options.dryRun = true;
       continue;
@@ -104,6 +109,10 @@ function parseArgs(argv, { createCliError } = {}) {
       options.inlineOptions.force = "true";
       continue;
     }
+    if (token === "--install") {
+      options.inlineOptions.install = "true";
+      continue;
+    }
 
     if (token.startsWith("--")) {
       const withoutPrefix = token.slice(2);
@@ -120,8 +129,9 @@ function parseArgs(argv, { createCliError } = {}) {
       if (hasInlineValue) {
         optionValueRaw = withoutPrefix.slice(withoutPrefix.indexOf("=") + 1);
       } else {
-        const nextToken = typeof args[0] === "string" ? String(args[0]) : "";
-        if (nextToken && !nextToken.startsWith("-")) {
+        const hasNextStringToken = typeof args[0] === "string";
+        const nextToken = hasNextStringToken ? String(args[0]) : "";
+        if (hasNextStringToken && !nextToken.startsWith("-")) {
           optionValueRaw = args.shift();
         }
       }