@jskit-ai/mobile-capacitor 0.1.94 → 0.1.96

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/mobile-capacitor",
-  "version": "0.1.94",
+  "version": "0.1.96",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -13,8 +13,8 @@
   "dependencies": {
     "@capacitor/browser": "^7.0.1",
     "@capacitor/core": "^7.4.3",
-    "@jskit-ai/kernel": "0.1.159",
-    "@jskit-ai/shell-web": "0.1.163"
+    "@jskit-ai/kernel": "0.1.161",
+    "@jskit-ai/shell-web": "0.1.165"
   },
   "description": "Thin Capacitor client integration for JSKIT mobile-shell launch routing and auth callback completion.",
   "jskit": {
@@ -34,23 +34,14 @@
           {
             "entrypoint": "src/client/providers/MobileCapacitorClientProvider.js",
             "export": "MobileCapacitorClientProvider"
+          },
+          {
+            "entrypoint": "src/client/providers/MobileCapacitorClientProvider.js",
+            "export": "MobileCapacitorRuntimeProvider"
           }
         ]
       }
     },
-    "lifecycle": {
-      "install": {
-        "prepare": {
-          "entrypoint": "src/server/buildTemplateContext.js",
-          "export": "prepareInstallHook"
-        },
-        "finalize": {
-          "entrypoint": "src/server/buildTemplateContext.js",
-          "export": "finalizeInstallHook",
-          "managesNpmInstall": true
-        }
-      }
-    },
     "metadata": {
       "apiSummary": {
         "surfaces": [
@@ -59,67 +50,11 @@
             "summary": "Exports the Capacitor client provider, launch adapter helpers, and mobile-shell runtime."
           }
         ],
-        "containerTokens": {
-          "server": [],
-          "client": [
-            "mobile.capacitor.client.runtime",
-            "mobile.capacitor.adapter.client"
-          ]
-        }
+        "clientCapabilities": [
+          "client.mobile",
+          "client.mobile-runtime"
+        ]
       }
-    },
-    "mutations": {
-      "dependencies": {
-        "runtime": {
-          "@capacitor/android": "^7.4.3",
-          "@capacitor/app": "^7.1.0",
-          "@capacitor/browser": "^7.0.1",
-          "@capacitor/core": "^7.4.3",
-          "@jskit-ai/kernel": "0.1.159",
-          "@jskit-ai/shell-web": "0.1.163"
-        },
-        "dev": {
-          "@capacitor/cli": "^7.4.3"
-        }
-      },
-      "packageJson": {
-        "scripts": {
-          "mobile:dev:android": "jskit mobile android dev",
-          "mobile:devices:android": "jskit mobile android devices",
-          "mobile:sync:android": "jskit mobile android sync",
-          "mobile:tunnel:android": "jskit mobile android tunnel",
-          "mobile:restart:android": "jskit mobile android restart",
-          "mobile:run:android": "jskit mobile android run",
-          "mobile:build:web": "npm run build",
-          "mobile:build:android": "jskit mobile android build"
-        }
-      },
-      "procfile": {},
-      "text": [],
-      "files": [
-        {
-          "from": "templates/capacitor.config.json",
-          "to": "capacitor.config.json",
-          "reason": "Install Capacitor shell configuration rendered from config.mobile.",
-          "category": "mobile-capacitor",
-          "id": "mobile-capacitor-config",
-          "templateContext": {
-            "entrypoint": "src/server/buildTemplateContext.js",
-            "export": "buildTemplateContext"
-          }
-        },
-        {
-          "from": "templates/mobile-capacitor.md",
-          "to": ".jskit/mobile-capacitor.md",
-          "reason": "Install managed mobile-shell notes for the Capacitor Android integration.",
-          "category": "mobile-capacitor",
-          "id": "mobile-capacitor-notes",
-          "templateContext": {
-            "entrypoint": "src/server/buildTemplateContext.js",
-            "export": "buildTemplateContext"
-          }
-        }
-      ]
     }
   }
 }

package/patterns/android-application/PATTERN.md

@@ -0,0 +1,71 @@
+---
+id: mobile/android-application
+title: Capacitor Android application
+summary: Wrap a JSKIT web application in a Capacitor Android shell using native Capacitor and Android commands.
+keywords: android, capacitor, device, mobile, native, shell, webview
+requires: @jskit-ai/mobile-capacitor, @capacitor/android, @capacitor/app, @capacitor/cli
+---
+
+# Capacitor Android application
+
+## Use when
+
+Use this pattern when the same JSKIT application should run inside a Capacitor
+Android shell and the product accepts a WebView-based native application.
+
+## Do not use when
+
+Do not use this pattern for a browser-only app, for a native UI product, or when
+the target platform is not supported by the selected Capacitor packages.
+
+## Product decisions
+
+Choose the stable application id, display name, built web directory, callback
+URLs, development server policy, and native permissions before creating the
+Android project.
+
+## Framework APIs
+
+Install the declared npm packages normally. Adapt `example/capacitor.config.json`
+into valid JSON, then use Capacitor directly:
+
+```text
+npx cap add android
+npm run build
+npx cap sync android
+npx cap run android
+```
+
+Use `adb devices`, `adb reverse`, Android Studio, and Gradle directly for device
+selection, tunnelling, diagnostics, and release builds. JSKIT does not wrap
+those tools in another command language.
+
+## Example files
+
+`example/capacitor.config.json` shows the small Capacitor configuration shape.
+Replace its obvious values directly; it is not an interpolation template.
+
+## Variation points
+
+Change application id/name, build directory, development server, callback URLs,
+plugins, native permissions, and platform-specific release configuration.
+
+## Invariants
+
+- `webDir` is the actual output of the application's production build.
+- Development origins are explicit and never leak into release configuration.
+- Browser navigation that leaves the app uses the package's public mobile
+  routing capability.
+- Native projects and signing configuration are ordinary app-owned source.
+
+## Verification
+
+Build the web application, sync Android, launch on an explicit device, test
+callback routing and external links, then build the native release variant.
+
+## Avoid
+
+- hidden device selection
+- checking secrets or signing keys into source
+- a JSKIT-specific wrapper around Capacitor, adb, or Gradle
+- generated-operation receipts

package/src/client/index.js

@@ -1,13 +1,10 @@
-import { MobileCapacitorClientProvider } from "./providers/MobileCapacitorClientProvider.js";
-
-export { MobileCapacitorClientProvider } from "./providers/MobileCapacitorClientProvider.js";
+export {
+  MobileCapacitorClientProvider,
+  MobileCapacitorRuntimeProvider
+} from "./providers/MobileCapacitorClientProvider.js";
 export { createMobileCapacitorRuntime } from "./runtime/mobileCapacitorRuntime.js";
 export {
   createGlobalCapacitorAppAdapter,
   createNoopCapacitorAppAdapter,
   resolveCapacitorAppPlugin
 } from "./runtime/globalCapacitorAppAdapter.js";
-
-const clientProviders = Object.freeze([MobileCapacitorClientProvider]);
-
-export { clientProviders };

package/src/client/providers/MobileCapacitorClientProvider.js

@@ -1,17 +1,14 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
 import { getClientAppConfig, resolveMobileConfig } from "@jskit-ai/kernel/client";
 import { createGlobalCapacitorAppAdapter } from "../runtime/globalCapacitorAppAdapter.js";
 import { createCapacitorAwareFetch } from "../runtime/apiRequestClient.js";
 import { createMobileCapacitorRuntime } from "../runtime/mobileCapacitorRuntime.js";
 import { createCapacitorAwareOAuthLaunchClient } from "../runtime/oauthLaunchClient.js";
 
-const AUTH_OAUTH_LAUNCH_CLIENT_TOKEN = "auth.oauth-launch.client";
 const GLOBAL_FETCH_RESTORE_KEY = Symbol.for("jskit.mobile.capacitor.restoreFetch");
 
 function installCapacitorAwareGlobalFetch({ adapter = null, apiBaseUrl = "", globalObject = globalThis } = {}) {
-  if (!globalObject || typeof globalObject !== "object") {
-    return null;
-  }
-  if (adapter?.available !== true) {
+  if (!globalObject || typeof globalObject !== "object" || adapter?.available !== true) {
     return null;
   }
   if (typeof globalObject.fetch !== "function") {
@@ -41,104 +38,70 @@ function installCapacitorAwareGlobalFetch({ adapter = null, apiBaseUrl = "", glo
   return restore;
 }
 
-class MobileCapacitorClientProvider {
-  static id = "mobile.capacitor.client";
-
-  static startsAfter = ["shell.web.client"];
-
-  register(app) {
-    if (!app || typeof app.singleton !== "function") {
-      throw new Error("MobileCapacitorClientProvider requires application singleton().");
-    }
-
-    let adapterInstance = null;
-    if (!app.has || app.has("mobile.capacitor.adapter.client") !== true) {
-      adapterInstance = createGlobalCapacitorAppAdapter();
-      app.singleton("mobile.capacitor.adapter.client", () => adapterInstance);
-    } else if (typeof app.make === "function") {
-      adapterInstance = app.make("mobile.capacitor.adapter.client");
-    }
-
-    const mobileConfig = resolveMobileConfig(getClientAppConfig());
-    installCapacitorAwareGlobalFetch({
-      adapter: adapterInstance,
-      apiBaseUrl: mobileConfig.apiBaseUrl
-    });
-
-    if (!app.has || app.has(AUTH_OAUTH_LAUNCH_CLIENT_TOKEN) !== true) {
-      app.singleton(AUTH_OAUTH_LAUNCH_CLIENT_TOKEN, (scope) => {
-        return createCapacitorAwareOAuthLaunchClient({
-          adapter: scope.make("mobile.capacitor.adapter.client"),
-          apiBaseUrl: mobileConfig.apiBaseUrl
-        });
-      });
-    }
-    app.singleton("mobile.capacitor.client.runtime", (scope) => {
-      if (!scope.has("jskit.client.router")) {
-        throw new Error("MobileCapacitorClientProvider requires jskit.client.router.");
-      }
-
-      const placementRuntime = scope.has("runtime.web-placement.client")
-        ? scope.make("runtime.web-placement.client")
-        : null;
-      const authCallbackCompleter = scope.has("auth.mobile-callback.client")
-        ? scope.make("auth.mobile-callback.client")
-        : null;
-      const authGuardRuntime = scope.has("runtime.auth-guard.client")
-        ? scope.make("runtime.auth-guard.client")
-        : null;
-
-      return createMobileCapacitorRuntime({
-        router: scope.make("jskit.client.router"),
-        mobileConfig: getClientAppConfig().mobile || {},
-        adapter: scope.make("mobile.capacitor.adapter.client"),
-        placementRuntime,
-        authCallbackCompleter,
-        authGuardRuntime
-      });
+const MobileCapacitorClientProvider = defineProvider({
+  id: "mobile.capacitor.client",
+  provides: {
+    mobile: "client.mobile"
+  },
+  setup() {
+    const adapter = createGlobalCapacitorAppAdapter();
+    const config = resolveMobileConfig(getClientAppConfig());
+    const restoreFetch = installCapacitorAwareGlobalFetch({
+      adapter,
+      apiBaseUrl: config.apiBaseUrl
     });
+    return {
+      mobile: Object.freeze({
+        adapter,
+        config,
+        oauthLaunch: createCapacitorAwareOAuthLaunchClient({
+          adapter,
+          apiBaseUrl: config.apiBaseUrl
+        }),
+        restoreFetch
+      })
+    };
+  },
+  shutdown(_dependencies, { outputs }) {
+    outputs.mobile.restoreFetch?.();
   }
-
-  async boot(app) {
-    if (!app || typeof app.make !== "function" || typeof app.has !== "function") {
-      throw new Error("MobileCapacitorClientProvider boot requires application make()/has().");
-    }
-
-    if (!app.has("mobile.capacitor.client.runtime")) {
-      return;
-    }
-
-    const mobileConfig = resolveMobileConfig(getClientAppConfig());
-    installCapacitorAwareGlobalFetch({
-      adapter: app.make("mobile.capacitor.adapter.client"),
-      apiBaseUrl: mobileConfig.apiBaseUrl
-    });
-
-    const runtime = app.make("mobile.capacitor.client.runtime");
-    if (runtime && typeof runtime.initialize === "function") {
-      await runtime.initialize();
-    }
-  }
-
-  shutdown(app) {
-    if (!app || typeof app.has !== "function" || typeof app.make !== "function") {
-      return;
-    }
-
-    if (!app.has("mobile.capacitor.client.runtime")) {
-      return;
-    }
-
-    const restoreFetch = globalThis[GLOBAL_FETCH_RESTORE_KEY];
-    if (typeof restoreFetch === "function") {
-      restoreFetch();
-    }
-
-    const runtime = app.make("mobile.capacitor.client.runtime");
-    if (runtime && typeof runtime.dispose === "function") {
-      runtime.dispose();
-    }
+});
+
+const MobileCapacitorRuntimeProvider = defineProvider({
+  id: "mobile.capacitor.runtime.client",
+  requires: {
+    mobile: "client.mobile",
+    router: "client.router"
+  },
+  optional: {
+    auth: "client.auth",
+    shell: "client.shell"
+  },
+  provides: {
+    mobileRuntime: "client.mobile-runtime"
+  },
+  setup({ auth, mobile, router, shell }) {
+    return {
+      mobileRuntime: createMobileCapacitorRuntime({
+        router,
+        mobileConfig: getClientAppConfig().mobile || {},
+        adapter: mobile.adapter,
+        placementRuntime: shell?.placement || null,
+        authCallbackCompleter: auth?.mobileCallback || null,
+        authGuardRuntime: auth?.guard || null
+      })
+    };
+  },
+  async boot(_dependencies, { outputs }) {
+    await outputs.mobileRuntime.initialize();
+  },
+  shutdown(_dependencies, { outputs }) {
+    outputs.mobileRuntime.dispose?.();
   }
-}
+});
 
-export { MobileCapacitorClientProvider, installCapacitorAwareGlobalFetch };
+export {
+  MobileCapacitorClientProvider,
+  MobileCapacitorRuntimeProvider,
+  installCapacitorAwareGlobalFetch
+};

package/test/provider.test.js

@@ -1,88 +1,44 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { MobileCapacitorClientProvider } from "../src/client/providers/MobileCapacitorClientProvider.js";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import {
+  MobileCapacitorClientProvider,
+  MobileCapacitorRuntimeProvider
+} from "../src/client/providers/MobileCapacitorClientProvider.js";
 
-function createAppDouble({
-  adapter = null,
-  authCallbackCompleter = null,
-  authGuardRuntime = null,
-  placementRuntime = null
-} = {}) {
-  const singletons = new Map();
-  const singletonInstances = new Map();
-  const runtime = {
-    initializeCalls: 0,
-    disposeCalls: 0
-  };
-
-  const app = {
-    singleton(token, factory) {
-      singletons.set(token, factory);
-    },
-    has(token) {
-      if (token === "jskit.client.router") {
-        return true;
-      }
-      if (token === "runtime.web-placement.client") {
-        return Boolean(placementRuntime);
-      }
-      if (token === "auth.mobile-callback.client") {
-        return Boolean(authCallbackCompleter);
-      }
-      if (token === "runtime.auth-guard.client") {
-        return Boolean(authGuardRuntime);
-      }
-      if (token === "auth.oauth-launch.client") {
-        return singletons.has(token) || singletonInstances.has(token);
+function createRouter() {
+  return {
+    currentRoute: {
+      value: {
+        fullPath: "/home"
       }
-      return singletons.has(token) || singletonInstances.has(token);
     },
-    make(token) {
-      if (token === "jskit.client.router") {
-        return {
-          currentRoute: {
-            value: {
-              fullPath: "/home"
-            }
-          },
-          async replace() {}
-        };
-      }
-      if (token === "runtime.web-placement.client") {
-        return placementRuntime;
-      }
-      if (token === "auth.mobile-callback.client") {
-        return authCallbackCompleter;
-      }
-      if (token === "runtime.auth-guard.client") {
-        return authGuardRuntime;
-      }
-      if (singletonInstances.has(token)) {
-        return singletonInstances.get(token);
-      }
-      const factory = singletons.get(token);
-      if (!factory) {
-        throw new Error(`Unknown token ${String(token)}`);
-      }
-      const instance = factory(this);
-      singletonInstances.set(token, instance);
-      return instance;
-    }
+    async replace() {},
+    back() {}
   };
+}
 
-  if (adapter) {
-    app.singleton("mobile.capacitor.adapter.client", () => adapter);
-  }
-
-  return {
-    app,
-    runtime,
-    singletons,
-    singletonInstances
-  };
+function createMobileProbe(onCapabilities) {
+  return defineProvider({
+    id: "test.mobile.capacitor.probe",
+    requires: {
+      mobile: "client.mobile",
+      mobileRuntime: "client.mobile-runtime"
+    },
+    setup(capabilities) {
+      onCapabilities(capabilities);
+      return {};
+    }
+  });
 }
 
-test("MobileCapacitorClientProvider registers and boots the mobile runtime", async () => {
+test("mobile providers publish, boot, and dispose their declared capabilities", async () => {
+  const originalCapacitor = globalThis.Capacitor;
+  const originalConfig = globalThis.__JSKIT_CLIENT_APP_CONFIG__;
+  const listenerEvents = [];
+  const removedListeners = [];
+  let capabilities = null;
+
   globalThis.__JSKIT_CLIENT_APP_CONFIG__ = {
     mobile: {
       enabled: true,
@@ -91,52 +47,67 @@ test("MobileCapacitorClientProvider registers and boots the mobile runtime", asy
       }
     }
   };
-
-  try {
-    const adapter = {
-      available: true,
-      async getInitialLaunchUrl() {
-        return "";
-      },
-      subscribeToLaunchUrls() {
-        return () => {};
+  globalThis.Capacitor = {
+    Plugins: {
+      App: {
+        async getLaunchUrl() {
+          return { url: "" };
+        },
+        async addListener(eventName) {
+          listenerEvents.push(eventName);
+          return {
+            remove() {
+              removedListeners.push(eventName);
+            }
+          };
+        }
       }
-    };
-    const { app } = createAppDouble({ adapter });
-    const provider = new MobileCapacitorClientProvider();
-
-    provider.register(app);
-
-    assert.equal(app.has("mobile.capacitor.adapter.client"), true);
-    assert.equal(app.has("mobile.capacitor.client.runtime"), true);
-    assert.equal(app.has("auth.oauth-launch.client"), true);
+    }
+  };
 
-    const runtime = app.make("mobile.capacitor.client.runtime");
-    assert.equal(typeof runtime.initialize, "function");
-    assert.equal(runtime.getState().available, true);
+  const runtime = createCapabilityRuntime({
+    inputs: {
+      "client.router": createRouter()
+    },
+    providers: [
+      MobileCapacitorClientProvider,
+      MobileCapacitorRuntimeProvider,
+      createMobileProbe((value) => {
+        capabilities = value;
+      })
+    ]
+  });
 
-    await provider.boot(app);
-    assert.equal(runtime.getState().initialized, true);
+  try {
+    await runtime.start();
+    assert.equal(capabilities.mobile.adapter.available, true);
+    assert.equal(typeof capabilities.mobile.oauthLaunch.open, "function");
+    assert.deepEqual(capabilities.mobileRuntime.getState(), {
+      initialized: true,
+      available: true,
+      enabled: true,
+      lastAppliedPath: ""
+    });
+    assert.deepEqual(listenerEvents.sort(), ["appUrlOpen", "backButton"]);
 
-    provider.shutdown(app);
-    assert.equal(runtime.getState().initialized, false);
+    await runtime.shutdown();
+    assert.equal(capabilities.mobileRuntime.getState().initialized, false);
+    await Promise.resolve();
+    assert.deepEqual(removedListeners.sort(), ["appUrlOpen", "backButton"]);
   } finally {
-    delete globalThis.__JSKIT_CLIENT_APP_CONFIG__;
+    globalThis.Capacitor = originalCapacitor;
+    globalThis.__JSKIT_CLIENT_APP_CONFIG__ = originalConfig;
   }
 });
 
-test("MobileCapacitorClientProvider installs and restores the Capacitor fetch wrapper", async () => {
+test("mobile provider installs and restores the Capacitor-aware fetch wrapper", async () => {
+  const originalCapacitor = globalThis.Capacitor;
   const originalConfig = globalThis.__JSKIT_CLIENT_APP_CONFIG__;
   const originalFetch = globalThis.fetch;
   const fetchCalls = [];
   const stubFetch = async (url, options) => {
-    fetchCalls.push({
-      url,
-      options
-    });
-    return {
-      ok: true
-    };
+    fetchCalls.push({ url, options });
+    return { ok: true };
   };
 
   globalThis.__JSKIT_CLIENT_APP_CONFIG__ = {
@@ -148,39 +119,40 @@ test("MobileCapacitorClientProvider installs and restores the Capacitor fetch wr
       }
     }
   };
-  globalThis.fetch = stubFetch;
-
-  try {
-    const { app } = createAppDouble({
-      adapter: {
-        available: true,
-        async getInitialLaunchUrl() {
-          return "";
+  globalThis.Capacitor = {
+    Plugins: {
+      App: {
+        async getLaunchUrl() {
+          return { url: "" };
         },
-        subscribeToLaunchUrls() {
-          return () => {};
+        async addListener() {
+          return { remove() {} };
         }
       }
-    });
-    const provider = new MobileCapacitorClientProvider();
+    }
+  };
+  globalThis.fetch = stubFetch;
 
-    provider.register(app);
-    await globalThis.fetch("/api/session", {
-      method: "GET"
-    });
-    await provider.boot(app);
-    provider.shutdown(app);
+  const runtime = createCapabilityRuntime({
+    inputs: {
+      "client.router": createRouter()
+    },
+    providers: [MobileCapacitorClientProvider, MobileCapacitorRuntimeProvider]
+  });
 
-    assert.deepEqual(fetchCalls, [
-      {
-        url: "http://127.0.0.1:3000/api/session",
-        options: {
-          method: "GET"
-        }
-      }
-    ]);
+  try {
+    await runtime.start();
+    assert.notEqual(globalThis.fetch, stubFetch);
+    await globalThis.fetch("/api/session", { method: "GET" });
+    await runtime.shutdown();
+
+    assert.deepEqual(fetchCalls, [{
+      url: "http://127.0.0.1:3000/api/session",
+      options: { method: "GET" }
+    }]);
     assert.equal(globalThis.fetch, stubFetch);
   } finally {
+    globalThis.Capacitor = originalCapacitor;
     globalThis.__JSKIT_CLIENT_APP_CONFIG__ = originalConfig;
     globalThis.fetch = originalFetch;
   }

package/src/server/buildTemplateContext.js

@@ -1,231 +0,0 @@
-import path from "node:path";
-import { readdir, rm } from "node:fs/promises";
-import { loadAppConfigFromAppRoot, resolveMobileConfig } from "@jskit-ai/kernel/server/support";
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
-
-function requireNonEmptyText(value, label = "value") {
-  const normalized = normalizeText(value);
-  if (!normalized) {
-    throw new Error(`${label} is required in config.mobile before installing Capacitor support.`);
-  }
-  return normalized;
-}
-
-function requireUrl(value, label = "value", { allowHttp = true, allowHttps = true } = {}) {
-  const normalized = requireNonEmptyText(value, label);
-  let parsed = null;
-  try {
-    parsed = new URL(normalized);
-  } catch {
-    throw new Error(`${label} must be a valid absolute URL in config.mobile.`);
-  }
-
-  const protocol = String(parsed.protocol || "").toLowerCase();
-  if ((protocol === "http:" && allowHttp !== true) || (protocol === "https:" && allowHttps !== true)) {
-    throw new Error(`${label} must use an allowed protocol in config.mobile.`);
-  }
-  if (protocol !== "http:" && protocol !== "https:") {
-    throw new Error(`${label} must use http or https in config.mobile.`);
-  }
-
-  return parsed.toString();
-}
-
-function buildCapacitorServerBlock(mobileConfig = {}) {
-  if (mobileConfig.assetMode !== "dev_server") {
-    return "";
-  }
-
-  const devServerUrl = requireUrl(mobileConfig.devServerUrl, "config.mobile.devServerUrl");
-  const cleartext = String(new URL(devServerUrl).protocol || "").toLowerCase() === "http:";
-
-  return [
-    ",",
-    '  "server": {',
-    `    "url": ${JSON.stringify(devServerUrl)},`,
-    `    "cleartext": ${cleartext}`,
-    "  }"
-  ].join("\n");
-}
-
-function buildAppLinkDomainsValue(appLinkDomains = []) {
-  const domains = Array.isArray(appLinkDomains) ? appLinkDomains : [];
-  if (domains.length < 1) {
-    return "(none)";
-  }
-  return domains.join(", ");
-}
-
-async function directoryContainsAnyFiles(directoryPath = "") {
-  const entries = await readdir(directoryPath, { withFileTypes: true });
-  for (const entry of entries) {
-    const absoluteChildPath = path.join(directoryPath, entry.name);
-    if (entry.isFile() || entry.isSymbolicLink()) {
-      return true;
-    }
-    if (entry.isDirectory() && await directoryContainsAnyFiles(absoluteChildPath)) {
-      return true;
-    }
-  }
-  return false;
-}
-
-async function buildTemplateContext({ appRoot } = {}) {
-  const mergedConfig = await loadAppConfigFromAppRoot({
-    appRoot: path.resolve(String(appRoot || ""))
-  });
-  const mobileConfig = resolveMobileConfig({
-    mobile: mergedConfig.mobile
-  });
-
-  if (mobileConfig.enabled !== true) {
-    throw new Error("config.mobile.enabled must be true before installing Capacitor support.");
-  }
-  if (mobileConfig.strategy !== "capacitor") {
-    throw new Error('config.mobile.strategy must be "capacitor" before installing Capacitor support.');
-  }
-
-  const appId = requireNonEmptyText(mobileConfig.appId, "config.mobile.appId");
-  const appName = requireNonEmptyText(mobileConfig.appName, "config.mobile.appName");
-  const apiBaseUrl = requireUrl(mobileConfig.apiBaseUrl, "config.mobile.apiBaseUrl");
-  const callbackPath = requireNonEmptyText(mobileConfig.auth.callbackPath, "config.mobile.auth.callbackPath");
-  const customScheme = requireNonEmptyText(mobileConfig.auth.customScheme, "config.mobile.auth.customScheme");
-  const androidPackageName = requireNonEmptyText(
-    mobileConfig.android.packageName,
-    "config.mobile.android.packageName"
-  );
-  const androidVersionName = requireNonEmptyText(
-    mobileConfig.android.versionName,
-    "config.mobile.android.versionName"
-  );
-
-  return {
-    "__JSKIT_MOBILE_CAPACITOR_APP_ID__": appId,
-    "__JSKIT_MOBILE_CAPACITOR_APP_NAME__": appName,
-    "__JSKIT_MOBILE_CAPACITOR_WEB_DIR__": "dist",
-    "__JSKIT_MOBILE_CAPACITOR_SERVER_BLOCK__": buildCapacitorServerBlock(mobileConfig),
-    "__JSKIT_MOBILE_CAPACITOR_ASSET_MODE__": mobileConfig.assetMode,
-    "__JSKIT_MOBILE_CAPACITOR_DEV_SERVER_URL__": mobileConfig.devServerUrl || "(unused)",
-    "__JSKIT_MOBILE_CAPACITOR_API_BASE_URL__": apiBaseUrl,
-    "__JSKIT_MOBILE_CAPACITOR_CALLBACK_PATH__": callbackPath,
-    "__JSKIT_MOBILE_CAPACITOR_CUSTOM_SCHEME__": customScheme,
-    "__JSKIT_MOBILE_CAPACITOR_APP_LINK_DOMAINS__": buildAppLinkDomainsValue(mobileConfig.auth.appLinkDomains),
-    "__JSKIT_MOBILE_CAPACITOR_ANDROID_PACKAGE_NAME__": androidPackageName,
-    "__JSKIT_MOBILE_CAPACITOR_ANDROID_MIN_SDK__": String(mobileConfig.android.minSdk),
-    "__JSKIT_MOBILE_CAPACITOR_ANDROID_TARGET_SDK__": String(mobileConfig.android.targetSdk),
-    "__JSKIT_MOBILE_CAPACITOR_ANDROID_VERSION_CODE__": String(mobileConfig.android.versionCode),
-    "__JSKIT_MOBILE_CAPACITOR_ANDROID_VERSION_NAME__": androidVersionName
-  };
-}
-
-async function prepareInstallHook({
-  appRoot,
-  appPackageJson = {},
-  io,
-  dryRun = false,
-  helpers = {}
-} = {}) {
-  const ensureManagedMobileConfig = helpers?.ensureManagedMobileConfig;
-  if (typeof ensureManagedMobileConfig !== "function") {
-    throw new Error("install hook helpers.ensureManagedMobileConfig is required.");
-  }
-
-  const addedConfigStub = await ensureManagedMobileConfig({
-    dryRun
-  });
-  if (dryRun === true && addedConfigStub) {
-    return {
-      stopInstall: true,
-      touchedFiles: ["config/public.js"],
-      stopMessage:
-        "[dry-run] mobile package install preview stops after the config.mobile stub because rendered Capacitor files depend on those values."
-    };
-  }
-
-  return {};
-}
-
-async function finalizeInstallHook({
-  appRoot,
-  io,
-  dryRun = false,
-  skipManagedFinalize = false,
-  helpers = {}
-} = {}) {
-  if (skipManagedFinalize === true) {
-    return {};
-  }
-
-  const installAppDependencies = helpers?.installAppDependencies;
-  const runProjectBinary = helpers?.runProjectBinary;
-  const helperFileExists = helpers?.fileExists;
-  const collectShellInstallIssues = helpers?.collectCapacitorShellInstallIssues;
-  const ensureDeepLinks = helpers?.ensureAndroidManifestDeepLinks;
-  const ensureNativeShellIdentity = helpers?.ensureAndroidNativeShellIdentity;
-  if (typeof installAppDependencies !== "function") {
-    throw new Error("install hook helpers.installAppDependencies is required.");
-  }
-  if (typeof runProjectBinary !== "function") {
-    throw new Error("install hook helpers.runProjectBinary is required.");
-  }
-  if (typeof helperFileExists !== "function") {
-    throw new Error("install hook helpers.fileExists is required.");
-  }
-  if (typeof collectShellInstallIssues !== "function") {
-    throw new Error("install hook helpers.collectCapacitorShellInstallIssues is required.");
-  }
-  if (typeof ensureDeepLinks !== "function") {
-    throw new Error("install hook helpers.ensureAndroidManifestDeepLinks is required.");
-  }
-  if (typeof ensureNativeShellIdentity !== "function") {
-    throw new Error("install hook helpers.ensureAndroidNativeShellIdentity is required.");
-  }
-
-  await installAppDependencies({
-    dryRun
-  });
-
-  const androidDirectoryPath = path.join(appRoot, "android");
-  const shellInstallIssues = await collectShellInstallIssues();
-  if (shellInstallIssues.length < 1) {
-    io?.stdout?.write("[mobile] Android shell is already installed. Skipping cap add android.\n");
-  } else {
-    if (await helperFileExists(androidDirectoryPath)) {
-      io?.stdout?.write("[mobile] Android shell is partial or stale. Reprovisioning it with Capacitor CLI because these artifacts are missing:\n");
-      for (const issue of shellInstallIssues) {
-        io?.stdout?.write(`- ${issue}\n`);
-      }
-      const androidDirectoryHasFiles = await directoryContainsAnyFiles(androidDirectoryPath);
-      if (!androidDirectoryHasFiles) {
-        io?.stdout?.write("[mobile] android/ exists but contains no files. Removing the empty partial shell before reprovisioning.\n");
-        if (!dryRun) {
-          await rm(androidDirectoryPath, { recursive: true, force: true });
-        }
-      } else {
-        throw new Error(
-          "android/ exists but the Capacitor shell is incomplete. JSKIT will not delete a non-empty native tree automatically. Remove android/ and rerun the install."
-        );
-      }
-    } else {
-      io?.stdout?.write("[mobile] Android shell is not installed yet. Provisioning it with Capacitor CLI.\n");
-    }
-    await runProjectBinary("cap", ["add", "android"], {
-      explanation: "[mobile] Provisioning Android shell with Capacitor CLI:",
-      dryRun
-    });
-    if (!dryRun) {
-      io?.stdout?.write("[mobile] Added Android shell with Capacitor CLI.\n");
-    }
-  }
-  await ensureDeepLinks({
-    dryRun
-  });
-  await ensureNativeShellIdentity({
-    dryRun
-  });
-  return {
-    touchedFiles: ["android"]
-  };
-}
-
-export { buildTemplateContext, prepareInstallHook, finalizeInstallHook };

package/templates/mobile-capacitor.md

@@ -1,46 +0,0 @@
-# Mobile Capacitor
-
-This file is managed by `@jskit-ai/mobile-capacitor`.
-
-Installed contract:
-
-- strategy: `capacitor`
-- asset mode: `__JSKIT_MOBILE_CAPACITOR_ASSET_MODE__`
-- dev server url: `__JSKIT_MOBILE_CAPACITOR_DEV_SERVER_URL__`
-- API base URL: `__JSKIT_MOBILE_CAPACITOR_API_BASE_URL__`
-- auth callback path: `__JSKIT_MOBILE_CAPACITOR_CALLBACK_PATH__`
-- custom scheme: `__JSKIT_MOBILE_CAPACITOR_CUSTOM_SCHEME__`
-- app link domains: `__JSKIT_MOBILE_CAPACITOR_APP_LINK_DOMAINS__`
-- Capacitor app id: `__JSKIT_MOBILE_CAPACITOR_APP_ID__`
-- Capacitor app name: `__JSKIT_MOBILE_CAPACITOR_APP_NAME__`
-- Android package name: `__JSKIT_MOBILE_CAPACITOR_ANDROID_PACKAGE_NAME__`
-- Android min SDK: `__JSKIT_MOBILE_CAPACITOR_ANDROID_MIN_SDK__`
-- Android target SDK: `__JSKIT_MOBILE_CAPACITOR_ANDROID_TARGET_SDK__`
-- Android version code: `__JSKIT_MOBILE_CAPACITOR_ANDROID_VERSION_CODE__`
-- Android version name: `__JSKIT_MOBILE_CAPACITOR_ANDROID_VERSION_NAME__`
-
-Owned artifacts:
-
-- `capacitor.config.json`
-- `android/` after `jskit add package @jskit-ai/mobile-capacitor` runs `cap add android`
-- `android/app/src/main/AndroidManifest.xml` managed deep-link intent filter for the custom scheme
-
-Managed commands:
-
-- `jskit add package @jskit-ai/mobile-capacitor`
-- `jskit mobile android dev [--target <device-id>]`
-- `jskit mobile android devices`
-- `jskit mobile android sync`
-- `jskit mobile android tunnel --target <device-id>`
-- `jskit mobile android restart --target <device-id>`
-- `jskit mobile android run [--target <device-id>]`
-- `jskit mobile android build`
-- `jskit mobile android doctor`
-
-Current Stage 1 limits:
-
-- Android only
-- web assets stay the JSKIT web client
-- OAuth start uses the external browser/custom tab only when the app is running inside the Capacitor shell
-- auth/deep-link handling stays routed through normal JSKIT paths
-- native app-link verification is still out of scope for Stage 1