@jskit-ai/jskit-cli 0.2.74 → 0.2.76

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

@@ -158,6 +158,18 @@ function buildManagedMobileConfigStub({ packageJson = {} } = {}) {
   ].join("\n");
 }
 
+function isEmptyDisabledMobileConfigPlaceholder(mobileConfig = {}) {
+  return (
+    mobileConfig?.enabled !== true &&
+    !String(mobileConfig?.strategy || "").trim() &&
+    !String(mobileConfig?.appId || "").trim() &&
+    !String(mobileConfig?.appName || "").trim() &&
+    !String(mobileConfig?.apiBaseUrl || "").trim() &&
+    !String(mobileConfig?.auth?.customScheme || "").trim() &&
+    !String(mobileConfig?.android?.packageName || "").trim()
+  );
+}
+
 function parseAndroidSdkDirFromLocalProperties(source = "") {
   const lines = String(source || "").split(/\r?\n/u);
   for (const line of lines) {
@@ -489,9 +501,19 @@ async function ensureMobileConfigStub({
   } = ctx;
   const publicConfigPath = path.join(appRoot, PUBLIC_CONFIG_RELATIVE_PATH);
   const currentSource = await readFile(publicConfigPath, "utf8");
-  if (/\bconfig\.mobile\b|\bmobile\s*:/u.test(currentSource)) {
+  if (
+    currentSource.includes(MANAGED_MOBILE_CONFIG_START_MARKER) &&
+    currentSource.includes(MANAGED_MOBILE_CONFIG_END_MARKER)
+  ) {
     return false;
   }
+  if (/\bconfig\.mobile\b|\bmobile\s*:/u.test(currentSource)) {
+    const mergedConfig = await loadAppConfigFromAppRoot({ appRoot });
+    const mobileConfig = resolveMobileConfig({ mobile: mergedConfig.mobile });
+    if (!isEmptyDisabledMobileConfigPlaceholder(mobileConfig)) {
+      return false;
+    }
+  }
 
   const stubSource = buildManagedMobileConfigStub({
     packageJson
@@ -619,7 +641,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 +700,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 +744,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 +779,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 +805,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 +829,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");
@@ -913,6 +935,7 @@ export {
   ANDROID_DIRECTORY_NAME,
   ANDROID_MANIFEST_RELATIVE_PATH,
   buildManagedMobileConfigStub,
+  isEmptyDisabledMobileConfigPlaceholder,
   resolveInstalledMobileConfig,
   resolveAndroidSdkDetails,
   collectAndroidSdkComponentIssues,

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,9 @@ function createCommandHandlerDeps(deps = {}) {
     removeManagedViteProxyEntries: deps.removeManagedViteProxyEntries,
     hashBuffer: deps.hashBuffer,
     rm: deps.rm,
-    discoverShellOutletTargetsFromApp: deps.discoverShellOutletTargetsFromApp
+    discoverShellOutletSourcePathsFromApp: deps.discoverShellOutletSourcePathsFromApp,
+    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,16 @@ 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 grouped by authoring model.",
+      "Default output includes the generator command pattern for adding to each group.",
+      "Use --details to include compact, medium, and expanded layout outlet mappings.",
+      "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 [--details] [--concrete] [--all] [--json]",
     showHelpOnBareInvocation: false,
     handlerName: "commandListPlacements",
-    allowedFlagKeys: Object.freeze(["json"]),
+    allowedFlagKeys: Object.freeze(["details", "concrete", "all", "json"]),
     inlineOptionMode: "none",
     allowedValueOptionNames: Object.freeze([])
   }),

package/src/server/core/createCliRunner.js

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