@jskit-ai/jskit-cli 0.2.73 → 0.2.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.73",
+  "version": "0.2.75",
   "description": "Bundle and package orchestration CLI for JSKIT apps.",
   "type": "module",
   "files": [
@@ -20,9 +20,9 @@
     "test": "node --test"
   },
   "dependencies": {
-    "@jskit-ai/jskit-catalog": "0.1.72",
-    "@jskit-ai/kernel": "0.1.64",
-    "@jskit-ai/shell-web": "0.1.63"
+    "@jskit-ai/jskit-catalog": "0.1.74",
+    "@jskit-ai/kernel": "0.1.66",
+    "@jskit-ai/shell-web": "0.1.65"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/completion.js

@@ -2,6 +2,10 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { access, readdir, readFile } from "node:fs/promises";
 import { buildCrudFieldContractMap } from "@jskit-ai/kernel/shared/support/crudFieldContract";
+import {
+  discoverPlacementTopologyFromApp,
+  discoverShellOutletTargetsFromApp
+} from "@jskit-ai/kernel/server/support";
 import {
   buildAppCommandOptionMeta,
   listAppCommandDefinitions
@@ -370,6 +374,37 @@ async function discoverPlacementTargets(appRoot) {
   return uniqueSorted(placementValues);
 }
 
+async function discoverSemanticPlacementTargets(appRoot) {
+  try {
+    const topology = await discoverPlacementTopologyFromApp({ appRoot });
+    return uniqueSorted(
+      (Array.isArray(topology?.placements) ? topology.placements : [])
+        .map((placement) => normalizeText(placement?.id))
+        .filter(Boolean)
+    );
+  } catch {
+    const topologyPath = path.join(appRoot, "src", "placementTopology.js");
+    if (!(await pathExists(topologyPath))) {
+      return [];
+    }
+    const source = await readFile(topologyPath, "utf8");
+    return uniqueSorted(extractMatches(source, [/\bid\s*:\s*["']([^"':]+(?:\.[^"':]+)+)["']/g]));
+  }
+}
+
+async function discoverConcretePlacementTargets(appRoot) {
+  try {
+    const discovered = await discoverShellOutletTargetsFromApp({ appRoot });
+    return uniqueSorted(
+      (Array.isArray(discovered?.targets) ? discovered.targets : [])
+        .map((target) => normalizeText(target?.id || target?.target))
+        .filter(Boolean)
+    );
+  } catch {
+    return discoverPlacementTargets(appRoot);
+  }
+}
+
 async function discoverComponentTokens(appRoot) {
   const tokens = [];
   for (const filePath of [
@@ -391,7 +426,6 @@ async function discoverComponentTokens(appRoot) {
     const source = await readFile(filePath, "utf8");
     tokens.push(...extractMatches(source, [
       /\bcomponentToken\s*:\s*["']([^"']+)["']/g,
-      /\bdefault-link-component-token\s*=\s*["']([^"']+)["']/g,
       /registerMainClientComponent\(\s*["']([^"']+)["']/g
     ]));
   }
@@ -590,9 +624,11 @@ async function completeOptionValue({
 
   if (normalizedOptionName === "resource-file") {
     suggestions = await discoverResourceFiles(appRoot);
-  } else if (["link-placement", "placement", "target"].includes(normalizedOptionName)) {
-    suggestions = await discoverPlacementTargets(appRoot);
-  } else if (normalizedOptionName === "link-component-token") {
+  } else if (["link-placement", "placement"].includes(normalizedOptionName)) {
+    suggestions = await discoverSemanticPlacementTargets(appRoot);
+  } else if (normalizedOptionName === "target") {
+    suggestions = await discoverConcretePlacementTargets(appRoot);
+  } else if (normalizedOptionName === "link-renderer") {
     suggestions = await discoverComponentTokens(appRoot);
   } else if (normalizedOptionName === "surface") {
     suggestions = await discoverSurfaces(appRoot);

package/src/server/cliRuntime/packageIntrospection/placementNormalization.js

@@ -3,7 +3,11 @@ import {
   ensureObject
 } from "../../shared/collectionUtils.js";
 import {
-  normalizeShellOutletTargetId
+  normalizePlacementKind,
+  normalizePlacementOwnerId,
+  normalizePlacementTopologyDefinition,
+  normalizeShellOutletTargetId,
+  resolvePlacementTargetReference
 } from "@jskit-ai/kernel/shared/support/shellLayoutTargets";
 
 function normalizePlacementOutlets(value) {
@@ -41,22 +45,27 @@ function normalizePlacementContributions(value) {
   for (const entry of ensureArray(value)) {
     const record = ensureObject(entry);
     const id = String(record.id || "").trim();
-    const target = normalizeShellOutletTargetId(record.target);
-    if (!id || !target) {
+    const targetReference = resolvePlacementTargetReference(record.target);
+    if (!id || !targetReference?.id) {
       continue;
     }
 
     const surfaces = [...new Set(ensureArray(record.surfaces).map((item) => String(item || "").trim()).filter(Boolean))];
+    const kind = normalizePlacementKind(record.kind) || (String(record.componentToken || "").trim() ? "component" : "link");
     const componentToken = String(record.componentToken || "").trim();
     const when = String(record.when || "").trim();
     const description = String(record.description || "").trim();
     const source = String(record.source || "").trim();
+    const owner = normalizePlacementOwnerId(record.owner);
     const parsedOrder = Number(record.order);
     const order = Number.isFinite(parsedOrder) ? Math.trunc(parsedOrder) : null;
     contributions.push(
       Object.freeze({
         id,
-        target,
+        target: targetReference.id,
+        targetType: targetReference.type,
+        owner,
+        kind,
         surfaces: Object.freeze(surfaces),
         order,
         componentToken,
@@ -83,7 +92,12 @@ function normalizePlacementContributions(value) {
   );
 }
 
+function normalizePlacementTopology(value, { context = "package placement topology" } = {}) {
+  return normalizePlacementTopologyDefinition(value, { context }).placements;
+}
+
 export {
   normalizePlacementContributions,
-  normalizePlacementOutlets
+  normalizePlacementOutlets,
+  normalizePlacementTopology
 };

package/src/server/commandHandlers/list.js

@@ -177,6 +177,7 @@ function createListCommands(ctx = {}) {
     loadBundleRegistry,
     loadAppLocalPackageRegistry,
     resolveInstalledNodeModulePackageEntry,
+    discoverPlacementTopologyFromApp,
     discoverShellOutletTargetsFromApp,
     normalizePlacementContributions,
     resolvePackageKind
@@ -435,39 +436,99 @@ function createListCommands(ctx = {}) {
 
   async function commandListPlacements({ options, cwd, stdout }) {
     const appRoot = await resolveAppRootFromCwd(cwd);
-    const discoveredPlacements = await discoverShellOutletTargetsFromApp({
-      appRoot,
-      sourceRoot: "src"
-    });
-    const placementTargets = ensureArray(discoveredPlacements.targets)
+    const showConcreteOnly = options.concrete === true && options.all !== true;
+    const showConcrete = options.concrete === true || options.all === true;
+    const showSemantic = showConcreteOnly !== true;
+    const discoveredTopology = await discoverPlacementTopologyFromApp({ appRoot });
+    const semanticPlacements = ensureArray(discoveredTopology.placements)
+      .map((entry) => ensureObject(entry))
+      .filter((entry) => String(entry.id || "").trim())
+      .sort((left, right) => {
+        const idCompare = String(left.id || "").localeCompare(String(right.id || ""));
+        if (idCompare !== 0) {
+          return idCompare;
+        }
+        return String(left.owner || "").localeCompare(String(right.owner || ""));
+      });
+    const discoveredConcrete = showConcrete
+      ? await discoverShellOutletTargetsFromApp({
+        appRoot,
+        sourceRoot: "src"
+      })
+      : { targets: [] };
+    const concreteTargets = ensureArray(discoveredConcrete.targets)
       .map((entry) => ensureObject(entry))
       .filter((entry) => String(entry.id || "").trim())
       .sort((left, right) => String(left.id || "").localeCompare(String(right.id || "")));
 
     if (options.json) {
       const payload = {
-        placements: placementTargets.map((placementTarget) => ({
-          target: String(placementTarget.id || "").trim(),
-          default: placementTarget.default === true,
-          sourcePath: String(placementTarget.sourcePath || "").trim()
-        }))
+        placements: showSemantic
+          ? semanticPlacements.map((placementTarget) => ({
+            target: String(placementTarget.id || "").trim(),
+            owner: String(placementTarget.owner || "").trim(),
+            default: placementTarget.default === true,
+            description: String(placementTarget.description || "").trim(),
+            surfaces: ensureArray(placementTarget.surfaces).map((entry) => String(entry || "").trim()).filter(Boolean),
+            variants: ensureObject(placementTarget.variants),
+            sourcePath: String(placementTarget.sourcePath || "").trim()
+          }))
+          : [],
+        concretePlacements: showConcrete
+          ? concreteTargets.map((placementTarget) => ({
+            target: String(placementTarget.id || "").trim(),
+            default: placementTarget.default === true,
+            sourcePath: String(placementTarget.sourcePath || "").trim()
+          }))
+          : []
       };
       stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
       return 0;
     }
 
     const color = createColorFormatter(stdout);
-    const lines = [color.heading("Available placements:")];
-    if (placementTargets.length < 1) {
-      lines.push("- none");
-    } else {
-      for (const placementTarget of placementTargets) {
-        const placementId = String(placementTarget.id || "").trim();
-        const sourcePath = String(placementTarget.sourcePath || "").trim();
-        const isDefault = placementTarget.default === true;
-        const defaultLabel = isDefault ? color.installed(" (default)") : "";
-        const sourceLabel = sourcePath ? ` ${color.dim(`[${sourcePath}]`)}` : "";
-        lines.push(`- ${color.item(placementId)}${defaultLabel}${sourceLabel}`);
+    const lines = [];
+    if (showSemantic) {
+      lines.push(color.heading("Available placements:"));
+      if (semanticPlacements.length < 1) {
+        lines.push("- none");
+      } else {
+        for (const placementTarget of semanticPlacements) {
+          const placementId = String(placementTarget.id || "").trim();
+          const owner = String(placementTarget.owner || "").trim();
+          const ownerLabel = owner ? color.dim(` [owner:${owner}]`) : "";
+          const defaultLabel = placementTarget.default === true ? color.installed(" (default)") : "";
+          const description = String(placementTarget.description || "").trim();
+          const descriptionSuffix = description ? `: ${description}` : "";
+          lines.push(`- ${color.item(placementId)}${ownerLabel}${defaultLabel}${descriptionSuffix}`);
+          const variants = ensureObject(placementTarget.variants);
+          for (const layoutClass of ["compact", "medium", "expanded"]) {
+            const variant = ensureObject(variants[layoutClass]);
+            const outlet = String(variant.outlet || "").trim();
+            if (outlet) {
+              lines.push(`  ${layoutClass} -> ${color.dim(outlet)}`);
+            }
+          }
+        }
+      }
+    }
+
+    if (showConcrete) {
+      if (lines.length > 0) {
+        lines.push("");
+      }
+      lines.push(color.heading("Available concrete outlets:"));
+      if (concreteTargets.length < 1) {
+        lines.push("- none");
+      } else {
+        for (const placementTarget of concreteTargets) {
+          const placementId = String(placementTarget.id || "").trim();
+          const sourcePath = String(placementTarget.sourcePath || "").trim();
+          const isDefault = placementTarget.default === true;
+          const defaultLabel = isDefault ? color.installed(" (default)") : "";
+          const sourceLabel = sourcePath ? ` ${color.dim(`[${sourcePath}]`)}` : "";
+          lines.push(`- ${color.item(placementId)}${defaultLabel}${sourceLabel}`);
+        }
       }
     }
 

package/src/server/commandHandlers/mobile.js

@@ -60,7 +60,7 @@ async function collectManagedMobileFileDriftIssues({
     }
     if (currentContent !== expectedContent) {
       issues.push(
-        `${normalizeRelativePath(appRoot, absolutePath)} is stale and no longer matches config.mobile. Re-run jskit mobile sync android to refresh managed mobile-shell files.`
+        `${normalizeRelativePath(appRoot, absolutePath)} is stale and no longer matches config.mobile. Re-run jskit mobile android sync to refresh managed mobile-shell files.`
       );
     }
   }
@@ -106,24 +106,53 @@ async function collectMissingInstalledDependencyNames(ctx, appRoot = "", package
   return missing;
 }
 
-function renderMobileHelp(stream, definition = null) {
+function renderAndroidMobileCommandList(lines, color) {
+  for (const entry of listMobileCommandDefinitions()) {
+    if (entry.name === "dev") {
+      lines.push(
+        `     - ${color.item(entry.name)}: Shortcut to run ${color.emphasis("sync")}, ${color.emphasis("tunnel")}, ${color.emphasis("run")} in this order`
+      );
+      continue;
+    }
+    lines.push(`     - ${color.item(entry.name)}: ${entry.summary}`);
+  }
+}
+
+function renderMobileHelp(stream, definition = null, platform = "") {
   const color = createColorFormatter(stream);
   const lines = [];
 
-  if (!definition) {
+  if (!definition && !platform) {
     lines.push(`Command: ${color.emphasis("mobile")}`);
     lines.push("");
     lines.push(color.heading("1) Minimal use"));
-    lines.push("   jskit mobile <subcommand>");
+    lines.push("   jskit mobile <platform> <subcommand>");
     lines.push("");
-    lines.push(color.heading("2) Subcommands"));
-    for (const entry of listMobileCommandDefinitions()) {
-      lines.push(`   - ${color.item(entry.name)}: ${entry.summary}`);
-    }
+    lines.push(color.heading("2) Platforms"));
+    lines.push(`   - ${color.item("android")}`);
+    renderAndroidMobileCommandList(lines, color);
     lines.push("");
     lines.push(color.heading("3) Notes"));
     lines.push("   - Mobile helpers are for the Stage 1 Android Capacitor shell flow.");
-    lines.push("   - Use jskit mobile <subcommand> help for subcommand-specific usage.");
+    lines.push("   - Use jskit mobile <platform> help for platform-specific usage.");
+    writeWrappedLines({
+      stdout: stream,
+      lines
+    });
+    return;
+  }
+
+  if (!definition) {
+    lines.push(`Mobile platform: ${color.emphasis(platform)}`);
+    lines.push("");
+    lines.push(color.heading("1) Minimal use"));
+    lines.push(`   jskit mobile ${platform} <subcommand>`);
+    lines.push("");
+    lines.push(color.heading("2) Subcommands"));
+    renderAndroidMobileCommandList(lines, color);
+    lines.push("");
+    lines.push(color.heading("3) Notes"));
+    lines.push(`   - Use jskit mobile ${platform} <subcommand> help for subcommand-specific usage.`);
     writeWrappedLines({
       stdout: stream,
       lines
@@ -256,7 +285,7 @@ function resolveAdbReversePort({
   const port = Number(parsedUrl.port || "");
   if (!Number.isInteger(port) || port < 1 || port > 65535) {
     throw createCliError(
-      `config.mobile.apiBaseUrl "${apiBaseUrl}" must include an explicit port so jskit mobile tunnel android can infer adb reverse.`
+      `config.mobile.apiBaseUrl "${apiBaseUrl}" must include an explicit port so jskit mobile android tunnel can infer adb reverse.`
     );
   }
 
@@ -337,7 +366,7 @@ async function resolveAndroidDeviceTarget({
     appRoot
   });
   if (devices.length < 1) {
-    throw ctx.createCliError(`No Android devices are visible to adb. Run jskit mobile devices android before ${commandLabel}.`);
+    throw ctx.createCliError(`No Android devices are visible to adb. Run jskit mobile android devices before ${commandLabel}.`);
   }
 
   const normalizedExplicitTarget = String(explicitTarget || "").trim();
@@ -346,7 +375,7 @@ async function resolveAndroidDeviceTarget({
     : devices[0];
 
   if (!selectedDevice) {
-    throw ctx.createCliError(`Android device "${normalizedExplicitTarget}" is not visible to adb. Run jskit mobile devices android first.`);
+    throw ctx.createCliError(`Android device "${normalizedExplicitTarget}" is not visible to adb. Run jskit mobile android devices first.`);
   }
   if (selectedDevice.state !== "device") {
     throw ctx.createCliError(`Android device "${selectedDevice.serial}" is currently "${selectedDevice.state}", not ready for ${commandLabel}.`);
@@ -402,7 +431,7 @@ async function runLocalBinary(binaryName, args = [], {
       if (error?.code === "ENOENT") {
         reject(
           createCliError(
-            `Could not find local "${binaryName}" in node_modules/.bin. Re-run jskit mobile add capacitor after npm install succeeds.`
+            `Could not find local "${binaryName}" in node_modules/.bin. Re-run jskit add package @jskit-ai/mobile-capacitor after npm install succeeds.`
           )
         );
         return;
@@ -513,28 +542,6 @@ async function refreshManagedMobileFiles({
   }
 }
 
-async function runMobileAddCapacitorCommand({
-  commandAdd,
-  appRoot,
-  options = {},
-  stdout,
-  stderr
-}) {
-  return await commandAdd({
-    positional: ["package", CAPACITOR_RUNTIME_PACKAGE_ID],
-    options: {
-      ...options,
-      runNpmInstall: true,
-      inlineOptions: {}
-    },
-    cwd: appRoot,
-    io: {
-      stdout,
-      stderr
-    }
-  });
-}
-
 async function runMobileSyncAndroidCommand({
   ctx,
   commandAdd,
@@ -738,7 +745,7 @@ async function runMobileBuildAndroidCommand({
 
   if (mobileConfig.assetMode !== "bundled") {
     throw createCliError(
-      'jskit mobile build android requires config.mobile.assetMode="bundled" so the release shell does not depend on a live dev server.'
+      'jskit mobile android build requires config.mobile.assetMode="bundled" so the release shell does not depend on a live dev server.'
     );
   }
 
@@ -906,9 +913,6 @@ async function runMobileTunnelAndroidCommand({
 }) {
   const inlineOptions = normalizeInlineOptions(options);
   const target = String(inlineOptions.target || "").trim();
-  if (!target) {
-    throw ctx.createCliError("jskit mobile tunnel android requires --target <device-id>.");
-  }
 
   const mobileConfig = await resolveInstalledMobileConfigForCommand({
     appRoot,
@@ -960,9 +964,6 @@ async function runMobileRestartAndroidCommand({
 }) {
   const inlineOptions = normalizeInlineOptions(options);
   const target = String(inlineOptions.target || "").trim();
-  if (!target) {
-    throw ctx.createCliError("jskit mobile restart android requires --target <device-id>.");
-  }
 
   const mobileConfig = await resolveInstalledMobileConfigForCommand({
     appRoot,
@@ -1020,7 +1021,7 @@ async function runMobileDevAndroidCommand({
 
   stdout.write(`[mobile] Using Android device: ${selectedDevice.serial}\n`);
   stdout.write("[mobile] Building and syncing the Android shell:\n");
-  stdout.write("[mobile]   npx jskit mobile sync android\n");
+  stdout.write("[mobile]   npx jskit mobile android sync\n");
   await runMobileSyncAndroidCommand({
     ctx,
     commandAdd,
@@ -1030,20 +1031,8 @@ async function runMobileDevAndroidCommand({
     stderr
   });
 
-  stdout.write(`[mobile] Installing and launching the app on ${selectedDevice.serial}:\n`);
-  stdout.write(`[mobile]   npx jskit mobile run android --target ${selectedDevice.serial}\n`);
-  await runCapRunAndroidCommand({
-    ctx,
-    appRoot,
-    pathModule: ctx.path,
-    target: selectedDevice.serial,
-    stdout,
-    stderr,
-    dryRun: false
-  });
-
   stdout.write(`[mobile] Creating the adb reverse tunnel on ${selectedDevice.serial}:\n`);
-  stdout.write(`[mobile]   npx jskit mobile tunnel android --target ${selectedDevice.serial}\n`);
+  stdout.write(`[mobile]   npx jskit mobile android tunnel --target ${selectedDevice.serial}\n`);
   await runMobileTunnelAndroidCommand({
     ctx,
     appRoot,
@@ -1056,6 +1045,18 @@ async function runMobileDevAndroidCommand({
     stderr
   });
 
+  stdout.write(`[mobile] Installing and launching the app on ${selectedDevice.serial}:\n`);
+  stdout.write(`[mobile]   npx jskit mobile android run --target ${selectedDevice.serial}\n`);
+  await runCapRunAndroidCommand({
+    ctx,
+    appRoot,
+    pathModule: ctx.path,
+    target: selectedDevice.serial,
+    stdout,
+    stderr,
+    dryRun: false
+  });
+
   return 0;
 }
 
@@ -1072,7 +1073,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
   async function commandMobile({ positional = [], options = {}, cwd = "", stdout, stderr }) {
     const firstToken = String(positional[0] || "").trim();
     const secondToken = String(positional[1] || "").trim();
-    const remainingPositionals = positional.slice(2);
+    const thirdToken = String(positional[2] || "").trim();
+    const remainingPositionals = positional.slice(3);
 
     if (!firstToken) {
       renderMobileHelp(stdout);
@@ -1080,19 +1082,31 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     }
 
     if (firstToken === "help") {
-      renderMobileHelp(stdout, resolveMobileCommandDefinition(secondToken));
+      renderMobileHelp(stdout);
       return 0;
     }
 
-    const definition = resolveMobileCommandDefinition(firstToken);
-    if (!definition) {
-      throw createCliError(`Unknown mobile subcommand: ${firstToken}.`, {
+    const platform = firstToken;
+    if (platform !== "android") {
+      throw createCliError(`Unknown mobile platform: ${platform}.`, {
         renderUsage: () => renderMobileHelp(stderr)
       });
     }
 
-    if (secondToken === "help") {
-      renderMobileHelp(stdout, definition);
+    if (!secondToken || secondToken === "help") {
+      renderMobileHelp(stdout, null, platform);
+      return 0;
+    }
+
+    const definition = resolveMobileCommandDefinition(secondToken);
+    if (!definition) {
+      throw createCliError(`Unknown mobile ${platform} subcommand: ${secondToken}.`, {
+        renderUsage: () => renderMobileHelp(stderr, null, platform)
+      });
+    }
+
+    if (thirdToken === "help") {
+      renderMobileHelp(stdout, definition, platform);
       return 0;
     }
 
@@ -1102,14 +1116,14 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     const unknownInlineOptionNames = inlineOptionNames.filter((optionName) => !supportedOptionNames.has(optionName));
     if (unknownInlineOptionNames.length > 0) {
       throw createCliError(
-        `Unknown option${unknownInlineOptionNames.length === 1 ? "" : "s"} for jskit mobile ${definition.name}: ${unknownInlineOptionNames.map((optionName) => `--${optionName}`).join(", ")}.`,
+        `Unknown option${unknownInlineOptionNames.length === 1 ? "" : "s"} for jskit mobile ${platform} ${definition.name}: ${unknownInlineOptionNames.map((optionName) => `--${optionName}`).join(", ")}.`,
         {
           renderUsage: () => renderMobileHelp(stderr, definition)
         }
       );
     }
     if (options?.dryRun === true && !supportedOptionNames.has("dry-run")) {
-      throw createCliError(`Unknown option for jskit mobile ${definition.name}: --dry-run.`, {
+      throw createCliError(`Unknown option for jskit mobile ${platform} ${definition.name}: --dry-run.`, {
         renderUsage: () => renderMobileHelp(stderr, definition)
       });
     }
@@ -1117,13 +1131,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     const appRoot = await resolveAppRootFromCwd(cwd);
 
     if (definition.name === "devices") {
-      if (secondToken !== "android") {
-        throw createCliError(`jskit mobile devices currently supports only "android".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile devices: ${remainingPositionals.join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} devices: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }
@@ -1137,13 +1146,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     }
 
     if (definition.name === "dev") {
-      if (secondToken !== "android") {
-        throw createCliError(`jskit mobile dev currently supports only "android".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile dev: ${remainingPositionals.join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} dev: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }
@@ -1159,13 +1163,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     }
 
     if (definition.name === "tunnel") {
-      if (secondToken !== "android") {
-        throw createCliError(`jskit mobile tunnel currently supports only "android".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile tunnel: ${remainingPositionals.join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} tunnel: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }
@@ -1180,13 +1179,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     }
 
     if (definition.name === "restart") {
-      if (secondToken !== "android") {
-        throw createCliError(`jskit mobile restart currently supports only "android".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile restart: ${remainingPositionals.join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} restart: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }
@@ -1200,36 +1194,9 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
       });
     }
 
-    if (definition.name === "add") {
-      if (secondToken !== "capacitor") {
-        throw createCliError(`jskit mobile add currently supports only "capacitor".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile add: ${remainingPositionals.join(" ")}`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-
-      return runMobileAddCapacitorCommand({
-        ctx,
-        commandAdd,
-        appRoot,
-        options,
-        stdout,
-        stderr
-      });
-    }
-
     if (definition.name === "sync") {
-      if (secondToken !== "android") {
-        throw createCliError(`jskit mobile sync currently supports only "android".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile sync: ${remainingPositionals.join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} sync: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }
@@ -1245,13 +1212,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     }
 
     if (definition.name === "run") {
-      if (secondToken !== "android") {
-        throw createCliError(`jskit mobile run currently supports only "android".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile run: ${remainingPositionals.join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} run: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }
@@ -1267,13 +1229,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     }
 
     if (definition.name === "build") {
-      if (secondToken !== "android") {
-        throw createCliError(`jskit mobile build currently supports only "android".`, {
-          renderUsage: () => renderMobileHelp(stderr, definition)
-        });
-      }
-      if (remainingPositionals.length > 0) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile build: ${remainingPositionals.join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} build: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }
@@ -1289,8 +1246,8 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
     }
 
     if (definition.name === "doctor") {
-      if (secondToken) {
-        throw createCliError(`Unexpected positional arguments for jskit mobile doctor: ${[secondToken, ...remainingPositionals].join(" ")}`, {
+      if (thirdToken || remainingPositionals.length > 0) {
+        throw createCliError(`Unexpected positional arguments for jskit mobile ${platform} doctor: ${[thirdToken, ...remainingPositionals].filter(Boolean).join(" ")}`, {
           renderUsage: () => renderMobileHelp(stderr, definition)
         });
       }

package/src/server/commandHandlers/mobileCommandCatalog.js

@@ -1,30 +1,8 @@
 const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
-  add: Object.freeze({
-    name: "add",
-    summary: "Install Capacitor mobile-shell support into the current app.",
-    usage: "jskit mobile add capacitor [--dry-run] [--devlinks]",
-    options: Object.freeze([
-      Object.freeze({
-        label: "--devlinks",
-        description: "Run npm run --if-present devlinks after install for local development relinking."
-      }),
-      Object.freeze({
-        label: "--dry-run",
-        description: "Preview the package install and generated files without mutating package.json, lockfiles, or app files."
-      })
-    ]),
-    defaults: Object.freeze([
-      "Installs @jskit-ai/mobile-capacitor plus the required Capacitor packages.",
-      "Renders capacitor.config.json and .jskit/mobile-capacitor.md from config.mobile.",
-      "Runs npm install and then cap add android unless --dry-run is used.",
-      "Use --devlinks only when you want npm run devlinks to relink the app after install.",
-      "If android/ already exists, the Capacitor CLI add step is skipped."
-    ])
-  }),
   sync: Object.freeze({
     name: "sync",
     summary: "Build the JSKIT web client and sync the Android Capacitor shell.",
-    usage: "jskit mobile sync android [--dry-run] [--devlinks]",
+    usage: "jskit mobile android sync [--dry-run] [--devlinks]",
     options: Object.freeze([
       Object.freeze({
         label: "--devlinks",
@@ -38,13 +16,13 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
     defaults: Object.freeze([
       "Runs npm run build so dist/ matches the current JSKIT web client.",
       "Runs cap sync android after the frontend build succeeds.",
-      "Requires capacitor.config.json and android/ from jskit mobile add capacitor."
+      "Requires capacitor.config.json and android/ from jskit add package @jskit-ai/mobile-capacitor."
     ])
   }),
   run: Object.freeze({
     name: "run",
     summary: "Launch the Android Capacitor shell for the current app.",
-    usage: "jskit mobile run android [--target <device-id>] [--dry-run]",
+    usage: "jskit mobile android run [--target <device-id>] [--dry-run]",
     options: Object.freeze([
       Object.freeze({
         label: "--target <device-id>",
@@ -62,8 +40,8 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
   }),
   dev: Object.freeze({
     name: "dev",
-    summary: "Run the local Android phone workflow: sync, install/run, then create the adb reverse tunnel.",
-    usage: "jskit mobile dev android [--target <device-id>]",
+    summary: "Shortcut to run sync, tunnel, run in this order.",
+    usage: "jskit mobile android dev [--target <device-id>]",
     options: Object.freeze([
       Object.freeze({
         label: "--target <device-id>",
@@ -71,15 +49,15 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
       })
     ]),
     defaults: Object.freeze([
-      "Runs jskit mobile sync android first.",
-      "Runs jskit mobile run android --target <device-id> without re-syncing a second time.",
-      "Runs jskit mobile tunnel android --target <device-id> last so local backend traffic reaches your laptop."
+      "jskit mobile android sync",
+      "jskit mobile android tunnel",
+      "jskit mobile android run"
     ])
   }),
   devices: Object.freeze({
     name: "devices",
     summary: "List Android devices currently visible to adb.",
-    usage: "jskit mobile devices android",
+    usage: "jskit mobile android devices",
     options: Object.freeze([]),
     defaults: Object.freeze([
       "Runs adb devices -l and prints the currently connected Android targets."
@@ -88,11 +66,11 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
   tunnel: Object.freeze({
     name: "tunnel",
     summary: "Create and verify an adb reverse tunnel for local Android testing.",
-    usage: "jskit mobile tunnel android --target <device-id> [--port <port>]",
+    usage: "jskit mobile android tunnel [--target <device-id>] [--port <port>]",
     options: Object.freeze([
       Object.freeze({
         label: "--target <device-id>",
-        description: "Required adb device serial to tunnel to."
+        description: "Optional adb device serial. If omitted, uses the first device from adb devices -l."
       }),
       Object.freeze({
         label: "--port <port>",
@@ -107,11 +85,11 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
   restart: Object.freeze({
     name: "restart",
     summary: "Clear app data and cold-start the Android shell on a chosen device.",
-    usage: "jskit mobile restart android --target <device-id>",
+    usage: "jskit mobile android restart [--target <device-id>]",
     options: Object.freeze([
       Object.freeze({
         label: "--target <device-id>",
-        description: "Required adb device serial to restart."
+        description: "Optional adb device serial. If omitted, uses the first device from adb devices -l."
       })
     ]),
     defaults: Object.freeze([
@@ -122,7 +100,7 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
   build: Object.freeze({
     name: "build",
     summary: "Build a release Android App Bundle for the current app.",
-    usage: "jskit mobile build android [--dry-run]",
+    usage: "jskit mobile android build [--dry-run]",
     options: Object.freeze([
       Object.freeze({
         label: "--dry-run",
@@ -137,7 +115,7 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
   doctor: Object.freeze({
     name: "doctor",
     summary: "Validate the Android Capacitor shell wiring for the current app.",
-    usage: "jskit mobile doctor",
+    usage: "jskit mobile android doctor",
     options: Object.freeze([]),
     defaults: Object.freeze([
       "Checks config.mobile, capacitor.config.json, android/, and the managed AndroidManifest deep-link filter."
@@ -146,8 +124,25 @@ const MOBILE_COMMAND_DEFINITIONS = Object.freeze({
 });
 
 function listMobileCommandDefinitions() {
+  const order = new Map([
+    ["dev", 0],
+    ["sync", 1],
+    ["tunnel", 2],
+    ["run", 3],
+    ["restart", 4],
+    ["build", 5],
+    ["devices", 6],
+    ["doctor", 7]
+  ]);
   return Object.values(MOBILE_COMMAND_DEFINITIONS)
-    .sort((left, right) => left.name.localeCompare(right.name));
+    .sort((left, right) => {
+      const leftOrder = order.get(left.name) ?? Number.MAX_SAFE_INTEGER;
+      const rightOrder = order.get(right.name) ?? Number.MAX_SAFE_INTEGER;
+      if (leftOrder !== rightOrder) {
+        return leftOrder - rightOrder;
+      }
+      return left.name.localeCompare(right.name);
+    });
 }
 
 function resolveMobileCommandDefinition(rawName = "") {
@@ -168,7 +163,7 @@ function buildMobileCommandOptionMeta(subcommandName = "") {
     return optionMeta;
   }
 
-  if (definition.name === "add" || definition.name === "sync" || definition.name === "run" || definition.name === "build") {
+  if (definition.name === "sync" || definition.name === "run" || definition.name === "build") {
     optionMeta["dry-run"] = { inputType: "flag" };
   }
   if (definition.name === "run") {

package/src/server/commandHandlers/mobileShellSupport.js

@@ -619,7 +619,7 @@ async function assertCapacitorShellInstalled({ ctx, appRoot }) {
 
   if (missingPaths.length > 0) {
     throw ctx.createCliError(
-      `Capacitor Android shell is not installed for this app. Missing: ${missingPaths.join(", ")}. Run jskit mobile add capacitor first.`
+      `Capacitor Android shell is not installed for this app. Missing: ${missingPaths.join(", ")}. Run jskit add package @jskit-ai/mobile-capacitor first.`
     );
   }
 }
@@ -678,7 +678,7 @@ async function ensureAndroidManifestDeepLinks({
   const manifestPath = pathModule.join(appRoot, ANDROID_MANIFEST_RELATIVE_PATH);
   if (!(await fileExists(manifestPath))) {
     throw createCliError(
-      `Capacitor Android shell is missing ${normalizeRelativePath(appRoot, manifestPath)}. Run jskit mobile add capacitor first.`
+      `Capacitor Android shell is missing ${normalizeRelativePath(appRoot, manifestPath)}. Run jskit add package @jskit-ai/mobile-capacitor first.`
     );
   }
 
@@ -722,7 +722,7 @@ async function collectAndroidNativeShellIdentityIssues({ ctx, appRoot } = {}) {
     const expectedSource = renderer(currentSource, nativeConfig);
     if (currentSource !== expectedSource) {
       issues.push(
-        `${normalizeRelativePath(appRoot, absolutePath)} is stale and no longer matches config.mobile. Re-run jskit mobile sync android to refresh the Android shell.`
+        `${normalizeRelativePath(appRoot, absolutePath)} is stale and no longer matches config.mobile. Re-run jskit mobile android sync to refresh the Android shell.`
       );
     }
   };
@@ -757,7 +757,7 @@ async function collectAndroidNativeShellIdentityIssues({ ctx, appRoot } = {}) {
     currentMainActivitySource !== expectedMainActivitySource
   ) {
     issues.push(
-      `${normalizeRelativePath(appRoot, mainActivityEntry.absolutePath)} is stale and no longer matches config.mobile. Re-run jskit mobile sync android to refresh the Android shell.`
+      `${normalizeRelativePath(appRoot, mainActivityEntry.absolutePath)} is stale and no longer matches config.mobile. Re-run jskit mobile android sync to refresh the Android shell.`
     );
   }
 
@@ -783,7 +783,7 @@ async function ensureAndroidNativeShellIdentity({
     const absolutePath = pathModule.join(appRoot, relativePath);
     if (!(await fileExists(absolutePath))) {
       throw createCliError(
-        `Capacitor Android shell is missing ${normalizeRelativePath(appRoot, absolutePath)}. Run jskit mobile add capacitor first.`
+        `Capacitor Android shell is missing ${normalizeRelativePath(appRoot, absolutePath)}. Run jskit add package @jskit-ai/mobile-capacitor first.`
       );
     }
     const currentSource = await readFile(absolutePath, "utf8");
@@ -807,7 +807,7 @@ async function ensureAndroidNativeShellIdentity({
 
   const mainActivityEntry = await resolveAndroidMainActivityEntry(appRoot);
   if (!mainActivityEntry) {
-    throw createCliError("Capacitor Android shell is missing MainActivity.java or MainActivity.kt. Run jskit mobile add capacitor first.");
+    throw createCliError("Capacitor Android shell is missing MainActivity.java or MainActivity.kt. Run jskit add package @jskit-ai/mobile-capacitor first.");
   }
 
   const currentMainActivitySource = await readFile(mainActivityEntry.absolutePath, "utf8");

package/src/server/core/argParser.js

@@ -23,6 +23,7 @@ function parseArgs(argv, { createCliError } = {}) {
         verbose: false,
         json: false,
         all: false,
+        concrete: false,
         help: true,
         inlineOptions: {}
       },
@@ -49,6 +50,7 @@ function parseArgs(argv, { createCliError } = {}) {
     verbose: false,
     json: false,
     all: false,
+    concrete: false,
     help: false,
     inlineOptions: {}
   };
@@ -107,6 +109,10 @@ function parseArgs(argv, { createCliError } = {}) {
       options.all = true;
       continue;
     }
+    if (token === "--concrete") {
+      options.concrete = true;
+      continue;
+    }
     if (token === "--help" || token === "-h") {
       options.help = true;
       continue;

package/src/server/core/buildCommandDeps.js

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

package/src/server/core/commandCatalog.js

@@ -173,20 +173,24 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     aliases: Object.freeze([]),
     showInOverview: true,
     summary: "Run JSKIT-managed mobile-shell helpers.",
-    minimalUse: "jskit mobile add capacitor",
+    minimalUse: "jskit mobile android dev",
     parameters: Object.freeze([
+      Object.freeze({
+        name: "<platform>",
+        description: "Currently only android is supported."
+      }),
       Object.freeze({
         name: "<subcommand>",
-        description: "add (more mobile helpers will live here as Stage 1 expands)."
+        description: "dev | devices | sync | tunnel | restart | run | build | doctor."
       })
     ]),
     defaults: Object.freeze([
-      "The first supported flow is jskit mobile add capacitor.",
-      "Use jskit mobile <subcommand> help for subcommand-specific usage.",
-      "--dry-run is accepted by jskit mobile add/sync/run/build.",
-      "--devlinks runs npm run --if-present devlinks after install/sync maintenance for development-only relinking."
+      "Install the shell first with jskit add package @jskit-ai/mobile-capacitor.",
+      "Use jskit mobile <platform> help for platform-specific usage.",
+      "--dry-run is accepted by jskit mobile android sync/run/build.",
+      "--devlinks runs npm run --if-present devlinks after jskit mobile android sync maintenance for development-only relinking."
     ]),
-    fullUse: "jskit mobile <subcommand> [help] [--dry-run] [--<option> <value>...]",
+    fullUse: "jskit mobile <platform> <subcommand> [help] [--dry-run] [--<option> <value>...]",
     showHelpOnBareInvocation: true,
     handlerName: "commandMobile",
     allowedFlagKeys: Object.freeze(["dryRun", "devlinks"]),
@@ -313,14 +317,14 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     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."
+      "Shows semantic placement targets from app placement topology by default.",
+      "Use --concrete to inspect low-level ShellOutlet recipients.",
+      "Use --all to show both semantic placements and concrete recipients."
     ]),
-    fullUse: "jskit list-placements [--json]",
+    fullUse: "jskit list-placements [--concrete] [--all] [--json]",
     showHelpOnBareInvocation: false,
     handlerName: "commandListPlacements",
-    allowedFlagKeys: Object.freeze(["json"]),
+    allowedFlagKeys: Object.freeze(["concrete", "all", "json"]),
     inlineOptionMode: "none",
     allowedValueOptionNames: Object.freeze([])
   }),

package/src/server/core/createCliRunner.js

@@ -5,7 +5,10 @@ import {
   writeFile
 } from "node:fs/promises";
 import path from "node:path";
-import { discoverShellOutletTargetsFromApp } from "@jskit-ai/kernel/server/support";
+import {
+  discoverPlacementTopologyFromApp,
+  discoverShellOutletTargetsFromApp
+} from "@jskit-ai/kernel/server/support";
 import { createCliError } from "../shared/cliError.js";
 import {
   createColorFormatter,
@@ -146,7 +149,8 @@ const commandHandlers = createCommandHandlers(
     removeManagedViteProxyEntries,
     hashBuffer,
     rm,
-    discoverShellOutletTargetsFromApp
+    discoverShellOutletTargetsFromApp,
+    discoverPlacementTopologyFromApp
   })
 );