@wix/himalaya-cli 0.1360.0 → 0.1362.0

package/dist/cli.mjs

@@ -28055,6 +28055,7 @@ __export(capabilities_exports, {
   capabilityConfigFindings: () => capabilityConfigFindings,
   capabilityInfo: () => capabilityInfo,
   capabilityIssues: () => capabilityIssues,
+  capabilityRemedy: () => capabilityRemedy,
   contentShell: () => contentShell,
   envelopeSubsetIssues: () => envelopeSubsetIssues,
   formatCapability: () => formatCapability,
@@ -28063,6 +28064,7 @@ __export(capabilities_exports, {
   isShell: () => isShell,
   lastDistFromJob: () => lastDistFromJob,
   needsBinaryNotice: () => needsBinaryNotice,
+  notInBinaryReason: () => notInBinaryReason,
   readLastDist: () => readLastDist,
   shellDistAdds: () => shellDistAdds,
   shellServes: () => shellServes,
@@ -28107,6 +28109,8 @@ function capabilityInfo(rawId, sdkRef = []) {
   const pkgs = PACKAGES[id] ?? [...new Set((CAPABILITY_IMPLIES[id] ?? []).flatMap((i2) => PACKAGES[i2] ?? []))];
   const ios = iosPlanFor([id]);
   const android = androidPlanFor([id]);
+  const modules = modulesOf(id);
+  const refusal = distAddRefusal(id);
   return {
     id,
     import: [...pkgs],
@@ -28116,9 +28120,30 @@ function capabilityInfo(rawId, sdkRef = []) {
     ios: { info: ios.info, entitlements: ios.entitlements },
     android: { permissions: android.permissions, features: android.features.map((f2) => f2.name) },
     shells: Object.fromEntries(SHELLS.map((s2) => [s2, shellSupport(s2, id)])),
-    declare: DECLARE_HINT
+    declare: DECLARE_HINT,
+    description: summaryOf2(pkgs, sdkRef),
+    implies: [...CAPABILITY_IMPLIES[id] ?? []],
+    modules,
+    components: Object.entries(COMPONENT_MODULES).filter(([, m2]) => modules.some((x2) => x2.id === m2)).map(([component]) => component).sort(),
+    distAddable: refusal === null,
+    distAddRefusal: refusal
   };
 }
+function modulesOf(id) {
+  return NATIVE_MODULES.filter((m2) => {
+    const caps = capabilitiesOfModule(m2);
+    return caps.ios.includes(id) || caps.android.includes(id);
+  }).map((m2) => ({
+    id: m2.id,
+    ...m2.ios ? { ios: m2.ios.product } : {},
+    ...m2.android ? { android: m2.android.project } : {}
+  }));
+}
+function summaryOf2(pkgs, sdkRef) {
+  const d2 = pkgs.map((p2) => sdkRef.find((s2) => s2.name === p2)?.description ?? "").find((x2) => x2.trim()) ?? "";
+  const first = /^[\s\S]*?[.!?](?=\s|$)/.exec(d2.trim())?.[0] ?? d2.trim();
+  return first.replace(/\s+/g, " ").slice(0, 200);
+}
 function allCapabilities(sdkRef = []) {
   return KNOWN_CAPABILITY_IDS.map((id) => capabilityInfo(id, sdkRef));
 }
@@ -28177,22 +28202,53 @@ function needsBinaryNotice(json6) {
 function noImportLabel(id) {
   return BRIDGE_CAPABILITY_IDS.includes(id) || id === "wix_platform" ? "a bridge capability (no @himalaya import of its own)" : "declare-only (no @himalaya import of its own)";
 }
-function formatCapability(c2) {
+function notInBinaryReason(c2, shell) {
+  const s2 = SHELL_CAPABILITIES[shell];
+  if (s2 && !s2.extensible) {
+    return `${s2.shared ? "one shared binary" : "a fixed binary"} \u2014 only a new ${shell} build adds it; a content package cannot`;
+  }
+  return c2.distAddRefusal ? `a dist build cannot add it: ${c2.id} ${c2.distAddRefusal}` : "a dist build would add it";
+}
+function capabilityRemedy(c2, shell) {
+  const sel = shell ? SHELL_CAPABILITIES[shell] : void 0;
+  if (shell && sel && !sel.extensible && c2.shells[shell] !== "serves") {
+    return `${shell} is ${sel.shared ? "one shared binary" : "a fixed binary"} \u2014 only a new ${shell} build adds ${c2.id}; \`himi dist\` and an OTA push cannot. Or pick a shell whose binary already serves it (${SHELLS.filter((x2) => c2.shells[x2] === "serves").join(", ") || "none today"}).`;
+  }
+  if (!c2.distAddable) {
+    const serves = SHELLS.filter((s2) => c2.shells[s2] === "serves");
+    return `pick a shell whose binary already serves it (${serves.join(", ") || "none today"}) \u2014 a dist build cannot add it (${c2.id} ${c2.distAddRefusal}).`;
+  }
+  if (!c2.needsNativeBuild) return "declare it; `himi dist` registers it in an extensible shell that does not yet.";
+  return "a NEW binary (`himi dist`) \u2014 declare it in config.ts `capabilities`, or list it in `capabilityEnvelope` to build it in now and turn it on later over the air. An OTA push alone cannot add it.";
+}
+function formatCapability(c2, shell) {
   const lines = [`${c2.id}  \u2014  ${c2.import.length ? `import from ${c2.import.join(" or ")}` : noImportLabel(c2.id)}`];
+  if (c2.description) lines.push(`  about:    ${c2.description}`);
   if (c2.exports.length) lines.push(`  exports:  ${c2.exports.join(", ")}`);
   if (c2.verbs.length) lines.push(`  verbs:    ${c2.verbs.map((v2) => `capability.${c2.id}.${v2}`).join(", ")}`);
+  if (c2.implies.length) lines.push(`  implies:  ${c2.implies.join(", ")} (declaring ${c2.id} grants it)`);
   lines.push(`  declare:  ${c2.declare}`);
   const iosKeys = [...Object.keys(c2.ios.info), ...Object.keys(c2.ios.entitlements)];
   const androidKeys = [...c2.android.permissions, ...c2.android.features];
   lines.push(
     c2.needsNativeBuild ? `  binary:   needs a NATIVE build \u2014 iOS ${iosKeys.join(", ") || "(nothing)"}; Android ${androidKeys.join(", ") || "(nothing)"}. An OTA push cannot add it.` : "  binary:   no native footprint \u2014 works in any shell that registers its handler."
   );
+  lines.push(
+    c2.modules.length ? `  module:   ${c2.modules.map((m2) => `${m2.id} (${[m2.ios && `iOS ${m2.ios}`, m2.android && `Android ${m2.android}`].filter(Boolean).join(", ")})`).join("; ")}` + (c2.components.length ? ` \u2014 also needed by the ${c2.components.join(", ")} component${c2.components.length === 1 ? "" : "s"}` : "") : "  module:   none \u2014 its native code is in the core runtime"
+  );
+  lines.push(`  dist:     ${c2.distAddable ? "a `himi dist` build can add it to an extensible shell" : `cannot be added at dist \u2014 ${c2.id} ${c2.distAddRefusal}`}`);
   const serves = SHELLS.filter((s2) => c2.shells[s2] === "serves");
   const adds = SHELLS.filter((s2) => c2.shells[s2] === "dist-adds");
   const not = SHELLS.filter((s2) => c2.shells[s2] === "not-in-binary");
+  const byReason = /* @__PURE__ */ new Map();
+  for (const s2 of not) {
+    const r2 = notInBinaryReason(c2, s2);
+    byReason.set(r2, [...byReason.get(r2) ?? [], s2]);
+  }
   lines.push(
-    `  shells:   served by ${serves.join(", ") || "none"}` + (adds.length ? `; \`himi dist\` adds it to ${adds.join(", ")}` : "") + (not.length ? `; NOT in the ${not.join(", ")} binary` : "")
+    `  shells:   served by ${serves.join(", ") || "none"}` + (adds.length ? `; \`himi dist\` adds it to ${adds.join(", ")}` : "") + [...byReason].map(([r2, shells]) => `; NOT in the ${shells.join(", ")} binary (${r2})`).join("")
   );
+  if (adds.length || not.length) lines.push(`  remedy:   ${capabilityRemedy(c2, shell)}`);
   return lines;
 }
 function formatCapabilityList(caps, shell) {
@@ -153530,7 +153586,7 @@ function rawTools() {
     {
       name: "himi_capabilities",
       title: "Native capabilities (camera, location, push, \u2026)",
-      description: "The native capabilities a worker can use: the @himalaya import, where to declare it (config.ts `capabilities` + the screen's logicBundle.declaredCapabilities), what the binary needs (usage strings, permissions), and which `himi dist --shell` binaries serve it. A capability with a native footprint only arrives with a new binary \u2014 an OTA push cannot add it. Offline.",
+      description: "The native capabilities a worker can use: the @himalaya import, where to declare it (config.ts `capabilities` + the screen's logicBundle.declaredCapabilities), what the binary needs (usage strings, permissions), the native module it links (`modules`) and the components that need that module (`components`), and which `himi dist --shell` binaries serve it. A capability with a native footprint only arrives with a new binary \u2014 an OTA push cannot add it; list it in config.ts `capabilityEnvelope` to build it in now and turn it on later. `distAddable` / `distAddRefusal` say whether a `himi dist` build can add it to an extensible shell, and why not. Offline.",
       annotations: LEARN,
       inputSchema: z3.object({
         id: z3.string().optional().describe("One capability, e.g. `camera`. Omit for all."),
@@ -178515,7 +178571,7 @@ Guides in your browser: ${idx.portalUrl}`);
       return 0;
     }
     case "capabilities": {
-      const { allCapabilities: allCapabilities2, capabilityInfo: capabilityInfo2, contentShell: contentShell2, formatCapability: formatCapability2, formatCapabilityList: formatCapabilityList2, isShell: isShell2, SHELLS: SHELLS2 } = await Promise.resolve().then(() => (init_capabilities(), capabilities_exports));
+      const { allCapabilities: allCapabilities2, capabilityInfo: capabilityInfo2, contentShell: contentShell2, formatCapability: formatCapability2, formatCapabilityList: formatCapabilityList2, isShell: isShell2, notInBinaryReason: notInBinaryReason2, SHELLS: SHELLS2 } = await Promise.resolve().then(() => (init_capabilities(), capabilities_exports));
       const sdkRef = loadSdkReference();
       const shell = contentShell2(contentDir(flags), str9(flags.shell));
       if (shell && !isShell2(shell)) {
@@ -178533,8 +178589,11 @@ Guides in your browser: ${idx.portalUrl}`);
           print({ ok: true, ...c2, ...shell ? { shell, servedByShell: c2.shells[shell] === "serves" } : {} });
           return 0;
         }
-        for (const line of formatCapability2(c2)) io2.log(line);
-        if (shell) io2.log(`  ${shell}:  ${c2.shells[shell] === "serves" ? "serves it" : "does NOT serve it \u2014 its binary is not built with it"}`);
+        for (const line of formatCapability2(c2, shell ?? void 0)) io2.log(line);
+        if (shell) {
+          const v2 = c2.shells[shell];
+          io2.log(`  ${shell}:  ${v2 === "serves" ? "serves it" : v2 === "dist-adds" ? "does not serve it yet \u2014 `himi dist` adds it" : `does NOT serve it \u2014 ${notInBinaryReason2(c2, shell)}`}`);
+        }
         return 0;
       }
       const caps = allCapabilities2(sdkRef);

package/guides/capabilities.md

@@ -22,10 +22,35 @@ himi capabilities --shell branded-lite # what that one binary serves
 
 ```
 camera  —  import from @himalaya/camera
-  exports:  capturePhoto, pickDocument, scanQR
-  declare:  config.ts `capabilities` AND each calling screen's `logicBundle.declaredCapabilities`
-  binary:   needs a NATIVE build — iOS NSCameraUsageDescription; Android android.permission.CAMERA …
-  shells:   served by owner-lite, player; `himi dist` adds it to base44, branded-lite, brandy; NOT in the demo-app binary
+  about:    Tier-5 typed binding to the platform's camera capability.
+  exports:  capturePhoto, pickDocument, scanQR, version
+  verbs:    capability.camera.capture, capability.camera.pickDocument, capability.camera.scanQR
+  declare:  config.ts `capabilities` (the app-level list a binary is built with) AND each calling screen's `logicBundle.declaredCapabilities` (the runtime gate)
+  binary:   needs a NATIVE build — iOS NSCameraUsageDescription, NSPhotoLibraryUsageDescription; Android android.permission.CAMERA, android.hardware.camera. An OTA push cannot add it.
+  module:   none — its native code is in the core runtime
+  dist:     a `himi dist` build can add it to an extensible shell
+  shells:   served by owner-lite, player; `himi dist` adds it to base44, branded-lite, brandy; NOT in the demo-app binary (a fixed binary — only a new demo-app build adds it; a content package cannot)
+  remedy:   a NEW binary (`himi dist`) — declare it in config.ts `capabilities`, or list it in `capabilityEnvelope` to build it in now and turn it on later over the air. An OTA push alone cannot add it.
+```
+
+The per-id output also answers three build questions (the JSON and MCP forms carry the same fields as
+`modules`, `components`, `distAddable` and `distAddRefusal`):
+
+- `module:` — the native module the capability links into a binary (its SwiftPM product and Gradle
+  project), and the SDUI components that need that module too (`animation` — also needed by the Lottie, Rive components).
+- `dist:` — whether a `himi dist` build can add the capability to an extensible shell, and if not,
+  why.
+- `remedy:` — what to do about it. It takes the shell you passed with `--shell` into account.
+
+A capability a build cannot add shows the refusal reason, for example (`himi capabilities live_activity`,
+abridged):
+
+```
+live_activity  —  import from @himalaya/live-activity
+  module:   live_activity (iOS HimalayaCoreLiveActivity, Android :core-runtime-live-update)
+  dist:     cannot be added at dist — live_activity needs a WidgetKit extension target in the shell's project, which a build cannot add
+  shells:   served by branded-lite, demo-app, owner-lite; NOT in the base44, brandy binary (a dist build cannot add it …); NOT in the player binary (one shared binary …)
+  remedy:   pick a shell whose binary already serves it (branded-lite, demo-app, owner-lite) — a dist build cannot add it (live_activity needs a WidgetKit extension target in the shell's project, which a build cannot add).
 ```
 
 Agents: the same data is the `himi_capabilities` MCP tool. `himi sdk <name>` also prints the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1360.0",
+  "version": "0.1362.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "0a238e262e21ac93a2e8120f032811ae402c599e5b3e208cd0def547"
+  "falconPackageHash": "6f8e9ebff2033817c8121233af0096191f0d147fc9d49e65d9e6f02d"
 }