@jskit-ai/jskit-cli 0.2.75 → 0.2.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/jskit-cli",
-  "version": "0.2.75",
+  "version": "0.2.76",
   "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.74",
-    "@jskit-ai/kernel": "0.1.66",
-    "@jskit-ai/shell-web": "0.1.65"
+    "@jskit-ai/jskit-catalog": "0.1.75",
+    "@jskit-ai/kernel": "0.1.67",
+    "@jskit-ai/shell-web": "0.1.66"
   },
   "engines": {
     "node": "20.x"

package/src/server/cliRuntime/mutations/textMutations.js

@@ -113,6 +113,13 @@ async function applyTextMutations(
       const previous = await readFileBufferIfExists(absoluteFile);
       const previousContent = previous.exists ? previous.buffer.toString("utf8") : "";
       const mutationId = String(mutation?.id || "").trim() || "append-text";
+      const interpolatedSkipChecks = normalizeSkipChecks(mutation?.skipIfContains)
+        .map((entry) => interpolateOptionValue(entry, options, packageEntry.packageId, `${mutationId}.skipIfContains`))
+        .filter((entry) => String(entry || "").trim().length > 0);
+      if (interpolatedSkipChecks.some((pattern) => previousContent.includes(String(pattern)))) {
+        continue;
+      }
+
       const resolvedSnippet = interpolateOptionValue(snippet, options, packageEntry.packageId, mutationId);
       const templateContextReplacements = await resolveTemplateContextReplacementsForMutation({
         packageEntry,
@@ -126,8 +133,7 @@ async function applyTextMutations(
       const renderedSnippet = templateContextReplacements
         ? applyTemplateContextReplacements(resolvedSnippet, templateContextReplacements)
         : resolvedSnippet;
-      const skipChecks = normalizeSkipChecks(mutation?.skipIfContains)
-        .map((entry) => interpolateOptionValue(entry, options, packageEntry.packageId, `${mutationId}.skipIfContains`))
+      const skipChecks = interpolatedSkipChecks
         .map((entry) => {
           if (!templateContextReplacements) {
             return entry;

package/src/server/commandHandlers/health.js

@@ -1825,8 +1825,12 @@ function createHealthCommands(ctx = {}) {
     return false;
   }
 
-  function isSharedListFiltersImportSource(sourcePath = "") {
-    return /(^|\/)shared\/[^/'"]*ListFilters(?:\.[A-Za-z0-9]+)?$/u.test(String(sourcePath || "").trim());
+  function isListFiltersImportSource(sourcePath = "") {
+    const normalizedSource = String(sourcePath || "").trim();
+    return (
+      /(^|\/)shared\/[^/'"]*ListFilters(?:\.[A-Za-z0-9]+)?$/u.test(normalizedSource) ||
+      /^\.\/listFilters\.[A-Za-z0-9]+$/u.test(normalizedSource)
+    );
   }
 
   function findCallSites(sourceText = "", calleeName = "") {
@@ -1872,22 +1876,22 @@ function createHealthCommands(ctx = {}) {
 
         if (!firstArgument || firstArgument.startsWith("{")) {
           issues.push(
-            `${relativePath}:${lineNumber}: [filters:shared-definition] do not inline structured filter definitions in ${calleeName}(...). Put them in packages/<crud>/src/shared/<crud>ListFilters.js and import that shared module.`
+            `${relativePath}:${lineNumber}: [filters:shared-definition] do not inline structured filter definitions in ${calleeName}(...). Put them in listFilters.js or packages/<crud>/src/shared/<crud>ListFilters.js and import that module.`
           );
           continue;
         }
 
         if (!/^[A-Za-z_$][\w$]*$/u.test(firstArgument)) {
           issues.push(
-            `${relativePath}:${lineNumber}: [filters:shared-definition] ${calleeName}(...) must receive a definitions symbol imported from a CRUD shared *ListFilters module, not an ad-hoc expression.`
+            `${relativePath}:${lineNumber}: [filters:shared-definition] ${calleeName}(...) must receive a definitions symbol imported from listFilters.js or a CRUD shared *ListFilters module, not an ad-hoc expression.`
           );
           continue;
         }
 
         const importSource = importBindings.get(firstArgument) || "";
-        if (!isSharedListFiltersImportSource(importSource)) {
+        if (!isListFiltersImportSource(importSource)) {
           issues.push(
-            `${relativePath}:${lineNumber}: [filters:shared-definition] ${calleeName}(${firstArgument}, ...) must use definitions imported from a CRUD shared *ListFilters module. Found ${importSource ? `import source "${importSource}"` : "a local symbol"} instead.`
+            `${relativePath}:${lineNumber}: [filters:shared-definition] ${calleeName}(${firstArgument}, ...) must use definitions imported from listFilters.js or a CRUD shared *ListFilters module. Found ${importSource ? `import source "${importSource}"` : "a local symbol"} instead.`
           );
         }
       }

package/src/server/commandHandlers/list.js

@@ -14,6 +14,9 @@ const REGISTER_MAIN_CLIENT_COMPONENT_PATTERN = /registerMainClientComponent\(\s*
 const LINK_ITEM_TOKEN_SUFFIX = "link-item";
 const JSKIT_SCOPE_PREFIX = "@jskit-ai/";
 const FEATURE_SERVER_GENERATOR_PACKAGE_ID = "@jskit-ai/feature-server-generator";
+const PLACEMENT_LAYOUT_CLASSES = Object.freeze(["compact", "medium", "expanded"]);
+const PLACEMENT_KIND_COMPONENT = "component";
+const PLACEMENT_KIND_LINK = "link";
 const PROVIDER_SOURCE_EXTENSIONS = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx"]);
 const READ_FILE_IGNORE_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EISDIR", "EACCES", "EPERM"]);
 const READ_DIRECTORY_IGNORE_ERROR_CODES = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM"]);
@@ -82,6 +85,331 @@ function isLinkItemToken(token = "") {
   return String(token || "").trim().toLowerCase().endsWith(LINK_ITEM_TOKEN_SUFFIX);
 }
 
+function collectPlacementRendererKinds(placementTarget = {}) {
+  const kinds = new Set();
+  const variants = ensureObject(placementTarget.variants);
+  for (const layoutClass of PLACEMENT_LAYOUT_CLASSES) {
+    const variant = ensureObject(variants[layoutClass]);
+    const renderers = ensureObject(variant.renderers);
+    for (const kind of Object.keys(renderers)) {
+      const normalizedKind = String(kind || "").trim();
+      if (normalizedKind) {
+        kinds.add(normalizedKind);
+      }
+    }
+  }
+  if (kinds.size < 1) {
+    kinds.add(PLACEMENT_KIND_COMPONENT);
+  }
+  return sortStrings([...kinds]);
+}
+
+function collectPlacementConcreteOutlets(placementTarget = {}) {
+  const outlets = new Set();
+  const variants = ensureObject(placementTarget.variants);
+  for (const layoutClass of PLACEMENT_LAYOUT_CLASSES) {
+    const variant = ensureObject(variants[layoutClass]);
+    const outlet = String(variant.outlet || "").trim();
+    if (outlet) {
+      outlets.add(outlet);
+    }
+  }
+  return sortStrings([...outlets]);
+}
+
+function classifyPlacementTarget(placementTarget = {}) {
+  const owner = String(placementTarget.owner || "").trim();
+  const kinds = collectPlacementRendererKinds(placementTarget);
+  const acceptsLinks = kinds.includes(PLACEMENT_KIND_LINK);
+  const acceptsComponents = kinds.includes(PLACEMENT_KIND_COMPONENT);
+
+  if (acceptsLinks && acceptsComponents) {
+    return owner ? "ownerMixed" : "mixed";
+  }
+  if (acceptsLinks) {
+    return owner ? "ownerLinks" : "links";
+  }
+  return owner ? "ownerComponents" : "components";
+}
+
+function createConcreteTargetSourcePathMap(concreteTargets = []) {
+  const sourcePathByTarget = new Map();
+  for (const concreteTarget of ensureArray(concreteTargets)) {
+    const target = String(ensureObject(concreteTarget).id || "").trim();
+    const sourcePath = String(ensureObject(concreteTarget).sourcePath || "").trim();
+    if (target && sourcePath && !sourcePathByTarget.has(target)) {
+      sourcePathByTarget.set(target, sourcePath);
+    }
+  }
+  return sourcePathByTarget;
+}
+
+function resolveChildPagePatternFromHostSourcePath(sourcePath = "") {
+  const normalizedPath = String(sourcePath || "").replaceAll("\\", "/").trim();
+  if (!normalizedPath.startsWith("src/pages/")) {
+    return "";
+  }
+  const pagePath = normalizedPath.slice("src/pages/".length);
+  if (pagePath.endsWith("/index.vue")) {
+    const hostPath = pagePath.slice(0, -"/index.vue".length);
+    return hostPath
+      ? `${hostPath}/<page>.vue or ${hostPath}/<page>/index.vue`
+      : "<page>.vue or <page>/index.vue";
+  }
+  if (pagePath.endsWith(".vue")) {
+    const hostPath = pagePath.slice(0, -".vue".length);
+    return hostPath
+      ? `${hostPath}/<page>.vue or ${hostPath}/<page>/index.vue`
+      : "<page>.vue or <page>/index.vue";
+  }
+  return "";
+}
+
+function resolveOwnerScopedChildPagePattern(placementTarget = {}, concreteSourcePathByTarget = new Map()) {
+  const outlets = collectPlacementConcreteOutlets(placementTarget);
+  for (const outlet of outlets) {
+    const childPagePattern = resolveChildPagePatternFromHostSourcePath(
+      concreteSourcePathByTarget.get(outlet) || ""
+    );
+    if (childPagePattern) {
+      return childPagePattern;
+    }
+  }
+  return "";
+}
+
+function createPlacementTargetSummary(placementTarget = {}, color, { concreteSourcePathByTarget = new Map() } = {}) {
+  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 childPagePattern = owner
+    ? resolveOwnerScopedChildPagePattern(placementTarget, concreteSourcePathByTarget)
+    : "";
+  const childPagePatternLabel = childPagePattern ? ` -> ${color.dim(childPagePattern)}` : "";
+  const descriptionSuffix = description ? `: ${description}` : "";
+  return `- ${color.item(placementId)}${ownerLabel}${defaultLabel}${childPagePatternLabel}${descriptionSuffix}`;
+}
+
+function appendPlacementLayoutDetails(lines, placementTarget = {}, color) {
+  const variants = ensureObject(placementTarget.variants);
+  for (const layoutClass of PLACEMENT_LAYOUT_CLASSES) {
+    const variant = ensureObject(variants[layoutClass]);
+    const outlet = String(variant.outlet || "").trim();
+    if (outlet) {
+      lines.push(`  ${layoutClass} -> ${color.dim(outlet)}`);
+    }
+  }
+}
+
+function collectMappedConcreteOutletIds(semanticPlacements = []) {
+  const mapped = new Set();
+  for (const placementTarget of ensureArray(semanticPlacements)) {
+    const variants = ensureObject(placementTarget.variants);
+    for (const layoutClass of PLACEMENT_LAYOUT_CLASSES) {
+      const variant = ensureObject(variants[layoutClass]);
+      const outlet = String(variant.outlet || "").trim();
+      if (outlet) {
+        mapped.add(outlet);
+      }
+    }
+  }
+  return mapped;
+}
+
+function resolveUnmappedConcreteTargets({
+  semanticPlacements = [],
+  concreteTargets = []
+} = {}) {
+  const mappedConcreteOutletIds = collectMappedConcreteOutletIds(semanticPlacements);
+  return ensureArray(concreteTargets)
+    .map((entry) => ensureObject(entry))
+    .filter((entry) => {
+      const id = String(entry.id || "").trim();
+      return id && !mappedConcreteOutletIds.has(id);
+    })
+    .sort((left, right) => String(left.id || "").localeCompare(String(right.id || "")));
+}
+
+function formatPlacementGuidanceLine(line = "", color) {
+  const guidanceLine = String(line || "").trim();
+  const labelMatch = /^([^:]+):\s*(.*)$/u.exec(guidanceLine);
+  if (!labelMatch) {
+    return `  ${color.dim(guidanceLine)}`;
+  }
+  const label = String(labelMatch[1] || "").trim();
+  const value = String(labelMatch[2] || "").trim();
+  const renderedLabel = color.installed(`${label}:`);
+  const renderedValue = value ? ` ${color.provider(value)}` : "";
+  return `  ${renderedLabel}${renderedValue}`;
+}
+
+function appendPlacementGroup(lines, {
+  color,
+  title = "",
+  description = "",
+  guidance = [],
+  targets = [],
+  concreteSourcePathByTarget = new Map(),
+  showLayoutDetails = false
+} = {}) {
+  const placementTargets = ensureArray(targets);
+  if (placementTargets.length < 1) {
+    return;
+  }
+  if (lines.length > 1) {
+    lines.push("");
+  }
+  lines.push(color.heading(title));
+  if (description) {
+    lines.push(description);
+  }
+  const guidanceLines = ensureArray(guidance).map((value) => String(value || "").trim()).filter(Boolean);
+  for (const guidanceLine of guidanceLines) {
+    lines.push(formatPlacementGuidanceLine(guidanceLine, color));
+  }
+  for (const placementTarget of placementTargets) {
+    lines.push(createPlacementTargetSummary(placementTarget, color, { concreteSourcePathByTarget }));
+    if (showLayoutDetails) {
+      appendPlacementLayoutDetails(lines, placementTarget, color);
+    }
+  }
+}
+
+function appendUnmappedConcreteTargetWarnings(lines, {
+  color,
+  concreteTargets = []
+} = {}) {
+  const targets = ensureArray(concreteTargets);
+  if (targets.length < 1) {
+    return;
+  }
+
+  if (lines.length > 1) {
+    lines.push("");
+  }
+  lines.push(color.heading("Unmapped concrete outlets:"));
+  lines.push(
+    "These concrete ShellOutlet recipients are discoverable but are not reached by semantic topology. Add a semantic mapping or keep them private/internal."
+  );
+  lines.push(
+    color.dim(
+      "Format: npx jskit generate ui-generator topology --placement <area.slot> --kind <link|component> --compact-target <host:position> --medium-target <host:position> --expanded-target <host:position>"
+    )
+  );
+  for (const placementTarget of targets) {
+    const placementId = String(placementTarget.id || "").trim();
+    const sourcePath = String(placementTarget.sourcePath || "").trim();
+    const sourceLabel = sourcePath ? ` ${color.dim(`[${sourcePath}]`)}` : "";
+    lines.push(`- ${color.item(placementId)}${sourceLabel}`);
+  }
+}
+
+function appendSemanticPlacementGroups(lines, {
+  color,
+  semanticPlacements = [],
+  concreteTargets = [],
+  showLayoutDetails = false
+} = {}) {
+  const concreteSourcePathByTarget = createConcreteTargetSourcePathMap(concreteTargets);
+  const groupedTargets = {
+    links: [],
+    ownerLinks: [],
+    components: [],
+    ownerComponents: [],
+    mixed: [],
+    ownerMixed: []
+  };
+
+  for (const placementTarget of ensureArray(semanticPlacements)) {
+    const groupKey = classifyPlacementTarget(placementTarget);
+    if (groupedTargets[groupKey]) {
+      groupedTargets[groupKey].push(placementTarget);
+    }
+  }
+
+  appendPlacementGroup(lines, {
+    color,
+    title: "Navigation link placements",
+    guidance: [
+      'Format: npx jskit generate ui-generator page <page-file> --name "Label" --link-placement <placement>',
+      'Example: npx jskit generate ui-generator page admin/reports/index.vue --name "Reports" --link-placement admin.tools-menu'
+    ],
+    targets: groupedTargets.links,
+    concreteSourcePathByTarget,
+    showLayoutDetails
+  });
+
+  appendPlacementGroup(lines, {
+    color,
+    title: "Owner-scoped navigation link placements",
+    guidance: [
+      'Format: npx jskit generate ui-generator page <host-path>/<page>.vue --name "Label"',
+      'Alternative: npx jskit generate ui-generator page <host-path>/<page>/index.vue --name "Label"',
+      'Example: npx jskit generate ui-generator page home/settings/profile.vue --name "Profile"'
+    ],
+    targets: groupedTargets.ownerLinks,
+    concreteSourcePathByTarget,
+    showLayoutDetails
+  });
+
+  appendPlacementGroup(lines, {
+    color,
+    title: "Component, widget, and section placements",
+    guidance: [
+      'Format: npx jskit generate ui-generator placed-element --name "Widget Name" --placement <placement>',
+      'Example: npx jskit generate ui-generator placed-element --name "Connection Status" --placement shell.status'
+    ],
+    targets: groupedTargets.components,
+    concreteSourcePathByTarget,
+    showLayoutDetails
+  });
+
+  appendPlacementGroup(lines, {
+    color,
+    title: "Owner-scoped component and section placements",
+    guidance: [
+      'Format: npx jskit generate ui-generator placed-element --name "Section Name" --placement <placement> --owner <owner>',
+      'Example: npx jskit generate ui-generator placed-element --name "Security Section" --placement settings.sections --owner account-settings'
+    ],
+    targets: groupedTargets.ownerComponents,
+    concreteSourcePathByTarget,
+    showLayoutDetails
+  });
+
+  appendPlacementGroup(lines, {
+    color,
+    title: "Mixed-kind placements",
+    description: "These topology entries accept more than one semantic kind. Choose the generator by what you are adding.",
+    guidance: [
+      'Link format: npx jskit generate ui-generator page <page-file> --name "Label" --link-placement <placement>',
+      'Component format: npx jskit generate ui-generator placed-element --name "Widget Name" --placement <placement>',
+      'Link example: npx jskit generate ui-generator page admin/reports/index.vue --name "Reports" --link-placement <placement>',
+      'Component example: npx jskit generate ui-generator placed-element --name "Ops Panel" --placement <placement>'
+    ],
+    targets: groupedTargets.mixed,
+    concreteSourcePathByTarget,
+    showLayoutDetails
+  });
+
+  appendPlacementGroup(lines, {
+    color,
+    title: "Owner-scoped mixed-kind placements",
+    description: "These owner-scoped entries accept more than one semantic kind. Include the owner when adding manual placement entries.",
+    guidance: [
+      'Link format: npx jskit generate ui-generator page <host-path>/<page>.vue --name "Label"',
+      'Link alternative: npx jskit generate ui-generator page <host-path>/<page>/index.vue --name "Label"',
+      'Component format: npx jskit generate ui-generator placed-element --name "Widget Name" --placement <placement> --owner <owner>',
+      'Link example: npx jskit generate ui-generator page home/settings/profile.vue --name "Profile"',
+      'Component example: npx jskit generate ui-generator placed-element --name "Security Section" --placement <placement> --owner <owner>'
+    ],
+    targets: groupedTargets.ownerMixed,
+    concreteSourcePathByTarget,
+    showLayoutDetails
+  });
+}
+
 async function readFileIfExists(filePath = "") {
   try {
     return await readFile(filePath, "utf8");
@@ -178,6 +506,7 @@ function createListCommands(ctx = {}) {
     loadAppLocalPackageRegistry,
     resolveInstalledNodeModulePackageEntry,
     discoverPlacementTopologyFromApp,
+    discoverShellOutletSourcePathsFromApp,
     discoverShellOutletTargetsFromApp,
     normalizePlacementContributions,
     resolvePackageKind
@@ -439,6 +768,8 @@ function createListCommands(ctx = {}) {
     const showConcreteOnly = options.concrete === true && options.all !== true;
     const showConcrete = options.concrete === true || options.all === true;
     const showSemantic = showConcreteOnly !== true;
+    const showLayoutDetails = options.details === true;
+    const shouldLookupHostPaths = showSemantic;
     const discoveredTopology = await discoverPlacementTopologyFromApp({ appRoot });
     const semanticPlacements = ensureArray(discoveredTopology.placements)
       .map((entry) => ensureObject(entry))
@@ -450,16 +781,28 @@ function createListCommands(ctx = {}) {
         }
         return String(left.owner || "").localeCompare(String(right.owner || ""));
       });
-    const discoveredConcrete = showConcrete
-      ? await discoverShellOutletTargetsFromApp({
+    let discoveredConcrete = { targets: [] };
+    if (showConcrete) {
+      discoveredConcrete = await discoverShellOutletTargetsFromApp({
         appRoot,
         sourceRoot: "src"
-      })
-      : { targets: [] };
+      });
+    } else if (shouldLookupHostPaths) {
+      discoveredConcrete = await discoverShellOutletSourcePathsFromApp({
+        appRoot,
+        sourceRoot: "src"
+      });
+    }
     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 || "")));
+    const unmappedConcreteTargets = showSemantic
+      ? resolveUnmappedConcreteTargets({
+        semanticPlacements,
+        concreteTargets
+      })
+      : [];
 
     if (options.json) {
       const payload = {
@@ -480,7 +823,12 @@ function createListCommands(ctx = {}) {
             default: placementTarget.default === true,
             sourcePath: String(placementTarget.sourcePath || "").trim()
           }))
-          : []
+          : [],
+        unmappedConcretePlacements: unmappedConcreteTargets.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;
@@ -490,27 +838,21 @@ function createListCommands(ctx = {}) {
     const lines = [];
     if (showSemantic) {
       lines.push(color.heading("Available placements:"));
+      lines.push("Semantic placement targets are the stable IDs you should author against. Use --concrete only for low-level ShellOutlet recipients.");
       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)}`);
-            }
-          }
-        }
+        appendSemanticPlacementGroups(lines, {
+          color,
+          semanticPlacements,
+          concreteTargets,
+          showLayoutDetails
+        });
       }
+      appendUnmappedConcreteTargetWarnings(lines, {
+        color,
+        concreteTargets: unmappedConcreteTargets
+      });
     }
 
     if (showConcrete) {

package/src/server/commandHandlers/mobile.js

@@ -1,6 +1,6 @@
 import path from "node:path";
 import { spawn } from "node:child_process";
-import { readFile } from "node:fs/promises";
+import { readFile, writeFile } from "node:fs/promises";
 import {
   createColorFormatter,
   writeWrappedLines
@@ -23,6 +23,10 @@ import {
 } from "./mobileShellSupport.js";
 const CAPACITOR_RUNTIME_PACKAGE_ID = "@jskit-ai/mobile-capacitor";
 const MOBILE_NOTES_RELATIVE_PATH = path.join(".jskit", "mobile-capacitor.md");
+const MANAGED_MOBILE_FILE_RELATIVE_PATHS = Object.freeze([
+  "capacitor.config.json",
+  MOBILE_NOTES_RELATIVE_PATH
+]);
 
 async function collectManagedMobileFileDriftIssues({
   ctx,
@@ -34,12 +38,7 @@ async function collectManagedMobileFileDriftIssues({
     path: pathModule,
     normalizeRelativePath
   } = ctx;
-  const managedRelativePaths = [
-    "capacitor.config.json",
-    MOBILE_NOTES_RELATIVE_PATH
-  ];
-
-  for (const relativePath of managedRelativePaths) {
+  for (const relativePath of MANAGED_MOBILE_FILE_RELATIVE_PATHS) {
     const absolutePath = pathModule.join(appRoot, relativePath);
     if (!(await fileExists(absolutePath))) {
       continue;
@@ -66,46 +65,6 @@ async function collectManagedMobileFileDriftIssues({
   }
 }
 
-async function collectMissingInstalledDependencyNames(ctx, appRoot = "", packageJson = {}) {
-  const {
-    fileExists,
-    path: pathModule
-  } = ctx;
-  const sections = [
-    packageJson?.dependencies,
-    packageJson?.devDependencies,
-    packageJson?.optionalDependencies
-  ];
-  const missing = [];
-  const seen = new Set();
-
-  for (const section of sections) {
-    if (!section || typeof section !== "object" || Array.isArray(section)) {
-      continue;
-    }
-
-    for (const packageName of Object.keys(section).sort((left, right) => left.localeCompare(right))) {
-      const normalizedPackageName = String(packageName || "").trim();
-      if (!normalizedPackageName || seen.has(normalizedPackageName)) {
-        continue;
-      }
-      seen.add(normalizedPackageName);
-
-      const packageJsonPath = pathModule.join(
-        appRoot,
-        "node_modules",
-        ...normalizedPackageName.split("/"),
-        "package.json"
-      );
-      if (!(await fileExists(packageJsonPath))) {
-        missing.push(normalizedPackageName);
-      }
-    }
-  }
-
-  return missing;
-}
-
 function renderAndroidMobileCommandList(lines, color) {
   for (const entry of listMobileCommandDefinitions()) {
     if (entry.name === "dev") {
@@ -429,9 +388,13 @@ async function runLocalBinary(binaryName, args = [], {
 
     child.on("error", (error) => {
       if (error?.code === "ENOENT") {
+        const installHint =
+          binaryName === "cap"
+            ? ` Run npm install after adding ${CAPACITOR_RUNTIME_PACKAGE_ID}, then rerun this command.`
+            : "";
         reject(
           createCliError(
-            `Could not find local "${binaryName}" in node_modules/.bin. Re-run jskit add package @jskit-ai/mobile-capacitor after npm install succeeds.`
+            `Could not find local "${binaryName}" in node_modules/.bin.${installHint}`
           )
         );
         return;
@@ -451,100 +414,93 @@ async function runLocalBinary(binaryName, args = [], {
   });
 }
 
-async function runMobileAppInstall({
+function hasPackageDependency(packageJson = {}, packageId = "") {
+  const sections = [
+    packageJson?.dependencies,
+    packageJson?.devDependencies,
+    packageJson?.optionalDependencies
+  ];
+  return sections.some((section) => (
+    section &&
+    typeof section === "object" &&
+    !Array.isArray(section) &&
+    Object.prototype.hasOwnProperty.call(section, packageId)
+  ));
+}
+
+async function readJsonFileForMobileCommand(filePath = "", label = "", createCliError) {
+  try {
+    return JSON.parse(await readFile(filePath, "utf8"));
+  } catch (error) {
+    const message = String(error?.message || error || "unknown error");
+    throw createCliError(`Could not read ${label}: ${message}`);
+  }
+}
+
+async function assertMobileRuntimePackageInstalled({
   ctx,
-  appRoot,
-  stdout,
-  stderr,
-  dryRun = false,
-  devlinks = false
+  appRoot
 } = {}) {
   const {
     path: pathModule,
-    loadAppPackageJson
+    createCliError
   } = ctx;
-  const { packageJson } = await loadAppPackageJson(appRoot);
-  const packageScripts = packageJson?.scripts && typeof packageJson.scripts === "object" ? packageJson.scripts : {};
-
-  await runLocalBinary("npm", ["install"], {
-    appRoot,
-    stderr,
-    stdout,
-    pathModule,
-    createCliError: ctx.createCliError,
-    dryRun
-  });
+  const packageJsonPath = pathModule.join(appRoot, "package.json");
+  const lockPath = pathModule.join(appRoot, ".jskit", "lock.json");
+  const packageJson = await readJsonFileForMobileCommand(packageJsonPath, "package.json", createCliError);
+  const lock = await readJsonFileForMobileCommand(lockPath, ".jskit/lock.json", createCliError);
+  const hasDependency = hasPackageDependency(packageJson, CAPACITOR_RUNTIME_PACKAGE_ID);
+  const hasLockRecord = Boolean(lock?.installedPackages?.[CAPACITOR_RUNTIME_PACKAGE_ID]);
 
-  if (devlinks === true && Object.prototype.hasOwnProperty.call(packageScripts, "devlinks")) {
-    await runLocalBinary("npm", ["run", "--if-present", "devlinks"], {
-      appRoot,
-      stderr,
-      stdout,
-      pathModule,
-      createCliError: ctx.createCliError,
-      dryRun
-    });
+  if (!hasDependency || !hasLockRecord) {
+    throw createCliError(
+      `Mobile Capacitor runtime package is not installed for this app. Run jskit add package ${CAPACITOR_RUNTIME_PACKAGE_ID} first.`
+    );
   }
 }
 
 async function refreshManagedMobileFiles({
   ctx,
-  commandAdd,
   appRoot,
   options = {},
-  stdout,
-  stderr
+  stdout
 } = {}) {
   const {
-    path: pathModule
+    fileExists,
+    path: pathModule,
+    normalizeRelativePath,
+    createCliError
   } = ctx;
-  const packageJsonPath = pathModule.join(appRoot, "package.json");
-  const packageJsonBefore = await readFile(packageJsonPath, "utf8");
-  let capturedStdout = "";
-  await commandAdd({
-    positional: ["package", CAPACITOR_RUNTIME_PACKAGE_ID],
-    options: {
-      ...options,
-      forceReapplyTarget: true,
-      runNpmInstall: false,
-      inlineOptions: {}
-    },
-    cwd: appRoot,
-    io: {
-      stdout: {
-        write(chunk) {
-          capturedStdout += String(chunk || "");
-        }
-      },
-      stderr
-    }
-  });
-  const packageJsonAfter = await readFile(packageJsonPath, "utf8");
-  const parsedPackageJsonAfter = JSON.parse(packageJsonAfter);
-  const missingInstalledDependencies = await collectMissingInstalledDependencyNames(ctx, appRoot, parsedPackageJsonAfter);
 
-  if (!/Touched files \(0\):/u.test(capturedStdout)) {
-    stdout.write(capturedStdout);
-  }
+  for (const relativePath of MANAGED_MOBILE_FILE_RELATIVE_PATHS) {
+    const absolutePath = pathModule.join(appRoot, relativePath);
+    if (!(await fileExists(absolutePath))) {
+      throw createCliError(
+        `Managed mobile file is missing: ${normalizeRelativePath(appRoot, absolutePath)}. Run jskit add package ${CAPACITOR_RUNTIME_PACKAGE_ID} first.`
+      );
+    }
 
-  if (
-    options?.dryRun !== true &&
-    (packageJsonAfter !== packageJsonBefore || missingInstalledDependencies.length > 0)
-  ) {
-    await runMobileAppInstall({
-      ctx,
+    const currentSource = await readFile(absolutePath, "utf8");
+    const nextSource = await renderManagedMobileFile({
       appRoot,
-      stdout,
-      stderr,
-      dryRun: false,
-      devlinks: options?.devlinks === true
+      relativeTargetPath: relativePath
     });
+    if (nextSource === currentSource) {
+      continue;
+    }
+
+    if (options?.dryRun === true) {
+      stdout?.write(`[dry-run] refresh ${normalizeRelativePath(appRoot, absolutePath)}\n`);
+      continue;
+    }
+
+    await writeFile(absolutePath, nextSource, "utf8");
+    stdout?.write(`[mobile] Refreshed ${normalizeRelativePath(appRoot, absolutePath)}.\n`);
   }
 }
 
 async function runMobileSyncAndroidCommand({
   ctx,
-  commandAdd,
   appRoot,
   options = {},
   stdout,
@@ -554,19 +510,20 @@ async function runMobileSyncAndroidCommand({
     path: pathModule
   } = ctx;
 
-  await refreshManagedMobileFiles({
+  await assertMobileRuntimePackageInstalled({
     ctx,
-    commandAdd,
-    appRoot,
-    options,
-    stdout,
-    stderr
+    appRoot
   });
-
   await assertCapacitorShellInstalled({
     ctx,
     appRoot
   });
+  await refreshManagedMobileFiles({
+    ctx,
+    appRoot,
+    options,
+    stdout
+  });
   await ensureAndroidNativeShellIdentity({
     ctx,
     appRoot,
@@ -607,7 +564,6 @@ async function runMobileSyncAndroidCommand({
 
 async function runMobileRunAndroidCommand({
   ctx,
-  commandAdd,
   appRoot,
   options = {},
   stdout,
@@ -632,26 +588,26 @@ async function runMobileRunAndroidCommand({
   if (mobileConfig.assetMode === "bundled") {
     await runMobileSyncAndroidCommand({
       ctx,
-      commandAdd,
       appRoot,
       options,
       stdout,
       stderr
     });
   } else {
-    await refreshManagedMobileFiles({
+    await assertMobileRuntimePackageInstalled({
       ctx,
-      commandAdd,
-      appRoot,
-      options,
-      stdout,
-      stderr
+      appRoot
     });
-
     await assertCapacitorShellInstalled({
       ctx,
       appRoot
     });
+    await refreshManagedMobileFiles({
+      ctx,
+      appRoot,
+      options,
+      stdout
+    });
     await ensureAndroidNativeShellIdentity({
       ctx,
       appRoot,
@@ -722,7 +678,6 @@ async function runCapRunAndroidCommand({
 
 async function runMobileBuildAndroidCommand({
   ctx,
-  commandAdd,
   appRoot,
   options = {},
   stdout,
@@ -751,7 +706,6 @@ async function runMobileBuildAndroidCommand({
 
   await runMobileSyncAndroidCommand({
     ctx,
-    commandAdd,
     appRoot,
     options,
     stdout,
@@ -1005,7 +959,6 @@ async function runMobileRestartAndroidCommand({
 
 async function runMobileDevAndroidCommand({
   ctx,
-  commandAdd,
   appRoot,
   options = {},
   stdout,
@@ -1024,7 +977,6 @@ async function runMobileDevAndroidCommand({
   stdout.write("[mobile]   npx jskit mobile android sync\n");
   await runMobileSyncAndroidCommand({
     ctx,
-    commandAdd,
     appRoot,
     options,
     stdout,
@@ -1060,16 +1012,12 @@ async function runMobileDevAndroidCommand({
   return 0;
 }
 
-function createMobileCommands(ctx = {}, { commandAdd } = {}) {
+function createMobileCommands(ctx = {}) {
   const {
     createCliError,
     resolveAppRootFromCwd
   } = ctx;
 
-  if (typeof commandAdd !== "function") {
-    throw new TypeError("createMobileCommands requires commandAdd().");
-  }
-
   async function commandMobile({ positional = [], options = {}, cwd = "", stdout, stderr }) {
     const firstToken = String(positional[0] || "").trim();
     const secondToken = String(positional[1] || "").trim();
@@ -1154,7 +1102,6 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
 
       return runMobileDevAndroidCommand({
         ctx,
-        commandAdd,
         appRoot,
         options,
         stdout,
@@ -1203,7 +1150,6 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
 
       return runMobileSyncAndroidCommand({
         ctx,
-        commandAdd,
         appRoot,
         options,
         stdout,
@@ -1220,7 +1166,6 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
 
       return runMobileRunAndroidCommand({
         ctx,
-        commandAdd,
         appRoot,
         options,
         stdout,
@@ -1237,7 +1182,6 @@ function createMobileCommands(ctx = {}, { commandAdd } = {}) {
 
       return runMobileBuildAndroidCommand({
         ctx,
-        commandAdd,
         appRoot,
         options,
         stdout,

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
@@ -913,6 +935,7 @@ export {
   ANDROID_DIRECTORY_NAME,
   ANDROID_MANIFEST_RELATIVE_PATH,
   buildManagedMobileConfigStub,
+  isEmptyDisabledMobileConfigPlaceholder,
   resolveInstalledMobileConfig,
   resolveAndroidSdkDetails,
   collectAndroidSdkComponentIssues,

package/src/server/core/buildCommandDeps.js

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

package/src/server/core/commandCatalog.js

@@ -317,14 +317,16 @@ const COMMAND_DESCRIPTORS = Object.freeze({
     minimalUse: "jskit list-placements",
     parameters: Object.freeze([]),
     defaults: Object.freeze([
-      "Shows semantic placement targets from app placement topology by default.",
+      "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 [--concrete] [--all] [--json]",
+    fullUse: "jskit list-placements [--details] [--concrete] [--all] [--json]",
     showHelpOnBareInvocation: false,
     handlerName: "commandListPlacements",
-    allowedFlagKeys: Object.freeze(["concrete", "all", "json"]),
+    allowedFlagKeys: Object.freeze(["details", "concrete", "all", "json"]),
     inlineOptionMode: "none",
     allowedValueOptionNames: Object.freeze([])
   }),

package/src/server/core/createCliRunner.js

@@ -7,6 +7,7 @@ import {
 import path from "node:path";
 import {
   discoverPlacementTopologyFromApp,
+  discoverShellOutletSourcePathsFromApp,
   discoverShellOutletTargetsFromApp
 } from "@jskit-ai/kernel/server/support";
 import { createCliError } from "../shared/cliError.js";
@@ -149,6 +150,7 @@ const commandHandlers = createCommandHandlers(
     removeManagedViteProxyEntries,
     hashBuffer,
     rm,
+    discoverShellOutletSourcePathsFromApp,
     discoverShellOutletTargetsFromApp,
     discoverPlacementTopologyFromApp
   })