@livx.cc/appwrap 0.48.1 → 0.49.0

package/src/cli.ts

@@ -11,8 +11,9 @@
 import { execFileSync, spawn } from 'child_process';
 import { createHash } from 'crypto';
 import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
+import { builtinModules } from 'module';
 import { networkInterfaces, tmpdir } from 'os';
-import { delimiter as pathDelimiter, dirname, join, resolve } from 'path';
+import { delimiter as pathDelimiter, dirname, extname, join, resolve } from 'path';
 import { pathToFileURL } from 'url';
 // PURE-DATA capability manifest (no NativeScript globals) — type-only import (erased at runtime);
 // the VALUES are loaded dynamically below from the resolved runtime so the CLI works both in the
@@ -247,6 +248,127 @@ function generateModuleArtifacts(outDir: string, req: NativeReqs): void {
   );
 }
 
+/** Make `cfg.plugins` LIVE for the MOBILE (NativeScript) shell — the in-process analog of the desktop
+ * `regeneratePlugins`. There is no separate host on mobile (one WebView, the NS runtime IS the trusted
+ * host), so a plugin's `handlers` register directly on the bridge at boot. For each configured plugin:
+ * resolve the entry (path or npm), bun-build it to a single ESM bundle under
+ * `native/app/shell/plugins/<id>.js` (definePlugin inlined; @nativescript/core externalized), emit a
+ * typed `.d.ts` shim so the barrel type-checks, and generate `app/shell/plugins.generated.ts` that
+ * imports + registers each. No plugins → rewrite the barrel to the committed no-op default and drop the
+ * plugins dir, so a non-plugin build compiles NO plugin glue (parity with the module barrels).
+ *
+ * SKELETON scope: only `handlers` are consumed on mobile. `attachTo`/`onWindow`/`WindowCtx` are
+ * desktop-only; a plugin declaring them still builds here (those fields are ignored).
+ *
+ * CROSS-LANE SKIP: a plugin that fails to resolve OR that pulls in a Node.js CORE module
+ * (`net`/`fs`/`child_process`/…, unavailable in the NativeScript runtime) is skipped with a warning,
+ * so a shared `plugins:[]` list genuinely builds on both lanes. The build alone is NOT enough to
+ * decide this: `bun build --target=node` treats node builtins as valid passthrough externals, so a
+ * desktop-only plugin importing `net` builds successfully and the incompatible `import "net"` lands
+ * in the emitted bundle — which then breaks the NS webpack build. We therefore SCAN the plugin's
+ * authored SOURCE for node-builtin imports/requires and skip on a hit (deterministic across import
+ * styles). We scan the source (not the emitted bundle) on purpose: a raw-text/bundle scan false-
+ * positives on (a) builtin specifiers that appear inside STRING LITERALS in a handler body, and (b)
+ * bun's own `import { createRequire } from "node:module"` interop shim, which it injects into the
+ * bundle for ANY CJS plugin — even one that only `require()`s the documented external
+ * `@nativescript/core`. The source reflects the author's real imports; bun's shims do not.
+ * KNOWN LIMITATION: only the ENTRY's own imports are scanned — a builtin pulled in TRANSITIVELY via a
+ * dependency slips through and fails the NS webpack build later (loud, not silent). Acceptable at this
+ * stage: it degrades in the right direction (a rare, self-announcing build error) vs the silent-drop a
+ * bundle scan caused, and such a plugin is desktop-only by construction. Revisit with a resolve-graph
+ * walk if transitive desktop deps become common. */
+/** Node.js core module names (bare + `node:` forms) — anything here is unavailable in the NS runtime. */
+const NODE_BUILTIN_SET = new Set(builtinModules.flatMap((m) => [m, `node:${m}`]));
+
+/** The distinct Node.js core modules a plugin's SOURCE actually imports/requires. Uses
+ * `Bun.Transpiler.scanImports`, which returns only real import/require STATEMENTS (never a specifier
+ * that merely appears inside a string literal), so a handler body containing `"x from 'fs'"` is not
+ * flagged. Subpaths like `fs/promises` and the `node:` prefix are normalised to the base module
+ * before the membership test. `loader` matches the source dialect (ts/tsx/js/jsx). */
+function nodeBuiltinImports(src: string, loader: 'ts' | 'tsx' | 'js' | 'jsx'): string[] {
+  const hits = new Set<string>();
+  for (const { path } of new Bun.Transpiler({ loader }).scanImports(src)) {
+    const base = path.replace(/^node:/, '').split('/')[0];
+    if (NODE_BUILTIN_SET.has(path) || NODE_BUILTIN_SET.has(base)) hits.add(path);
+  }
+  return [...hits];
+}
+
+/** Map a plugin entrypoint's extension to the Bun.Transpiler loader for its source dialect. */
+function loaderForEntry(entrypoint: string): 'ts' | 'tsx' | 'js' | 'jsx' {
+  const ext = extname(entrypoint).toLowerCase();
+  if (ext === '.tsx') return 'tsx';
+  if (ext === '.jsx') return 'jsx';
+  if (ext === '.ts' || ext === '.mts' || ext === '.cts') return 'ts';
+  return 'js';
+}
+
+export function regenerateMobilePlugins(cwd: string, cfg: AppwrapConfig, outDir: string): void {
+  const shellDir = join(outDir, 'app/shell');
+  const pluginsDir = join(shellDir, 'plugins');
+  // Start clean: stale bundles from a previous config must not linger in the disposable native/.
+  rmSync(pluginsDir, { recursive: true, force: true });
+
+  const barrelPath = join(shellDir, 'plugins.generated.ts');
+  const header = `/** Generated by \`appwrap\` from the appwrap config \`plugins\`. Do not edit. */\n`;
+  const writeNoop = () => writeFileSync(barrelPath, `${header}export function registerPlugins(): void {\n}\n`);
+
+  const entries = cfg.plugins ?? [];
+  if (entries.length === 0) { writeNoop(); return; }
+
+  mkdirSync(pluginsDir, { recursive: true });
+  const bun = process.execPath; // the CLI runs under bun → the exact runtime to build with
+  const imports: string[] = [];
+  const calls: string[] = [];
+  let idx = 0;
+  for (const raw of entries) {
+    const name = typeof raw === 'string' ? raw : raw.name;
+    // Resolve: an existing path (relative to the app root) wins; else treat as an npm package name.
+    let entrypoint = resolve(cwd, name);
+    if (!existsSync(entrypoint)) {
+      try {
+        entrypoint = (Bun as unknown as { resolveSync(id: string, parent: string): string }).resolveSync(name, cwd);
+      } catch {
+        console.warn(`⚠ mobile plugin "${name}" not found (no such path, not resolvable as an npm package) — skipping.`);
+        continue;
+      }
+    }
+    const bundleId = name.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const outfile = join(pluginsDir, `${bundleId}.js`);
+    // Cross-lane guard: a desktop-only plugin (importing net/fs/child_process/…) BUILDS fine here — node
+    // builtins pass through as valid externals — so scan the plugin's SOURCE for real builtin imports and
+    // skip on a hit, BEFORE building (no point bundling a plugin we'll drop).
+    const nodeBuiltins = nodeBuiltinImports(readFileSync(entrypoint, 'utf8'), loaderForEntry(entrypoint));
+    if (nodeBuiltins.length) {
+      console.warn(`⚠ mobile plugin "${name}" imports Node.js core module(s) [${nodeBuiltins.join(', ')}] unavailable in the NativeScript runtime (desktop-only plugin on the mobile lane) — skipping.`);
+      continue;
+    }
+    try {
+      // ESM single-file so NS webpack bundles it; @nativescript/core stays external (provided by the shell).
+      execFileSync(bun, ['build', entrypoint, '--format=esm', '--target=node', '--external=@nativescript/core', '--outfile', outfile], { stdio: 'pipe' });
+    } catch (e: unknown) {
+      console.warn(`⚠ mobile plugin bun-build failed (${name}): ${e instanceof Error ? e.message : String(e)} — skipping.`);
+      continue;
+    }
+    // Typed shim so the generated barrel resolves the JS bundle's default export under tsc.
+    writeFileSync(
+      join(pluginsDir, `${bundleId}.d.ts`),
+      `import type { MobilePluginDef } from '../plugin-host';\ndeclare const plugin: MobilePluginDef;\nexport default plugin;\n`
+    );
+    const ident = `plugin_${idx++}`;
+    imports.push(`import ${ident} from './plugins/${bundleId}.js';`);
+    calls.push(`  registerPluginHandlers(${ident});`);
+    console.log(`  plugin ← ${name}  (mobile: handlers)`);
+  }
+
+  if (imports.length === 0) { writeNoop(); return; }
+  writeFileSync(
+    barrelPath,
+    `${header}import { registerPluginHandlers } from './plugin-host';\n${imports.join('\n')}\n\n` +
+      `export function registerPlugins(): void {\n${calls.join('\n')}\n}\n`
+  );
+}
+
 /** Stamp the active modules' gradle dependencies into Android app.gradle. Idempotent marker block. */
 function stampAndroidGradleDeps(outDir: string, deps: string[]): void {
   const appGradle = join(outDir, 'App_Resources/Android/app.gradle');
@@ -482,6 +604,14 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
 }
 
 function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
+  // Resolve the env-switcher block. Absent block OR `enabled:false` → the whole feature is inert
+  // (the shell reads `envSwitcher.enabled`). `allowPattern`/`envs` default to empty (default-deny).
+  const es = cfg.envSwitcher;
+  const envSwitcher = {
+    enabled: !!es && es.enabled !== false,
+    envs: (es?.envs ?? []).map((e) => ({ label: String(e.label), url: String(e.url) })),
+    allowPattern: es?.allowPattern ?? '',
+  };
   const content = `/**
  * Shell config — stamped by \`appwrap init\`/\`sync\` from the appwrap config. Do not edit.
  */
@@ -508,6 +638,7 @@ export const SHELL_CONFIG = {
   pushAndroid: ${JSON.stringify(!!cfg.push?.enabled && cfg.push?.android !== false)},
   pushRegistrationUrl: ${JSON.stringify(cfg.push?.registrationUrl ?? '')},
   iosKeyboardExtraLift: ${JSON.stringify(cfg.iosKeyboardExtraLift ?? 82)},
+  envSwitcher: ${JSON.stringify(envSwitcher)} as { enabled: boolean; envs: { label: string; url: string }[]; allowPattern: string },
 };
 `;
   writeFileSync(join(outDir, 'app/shell/config.ts'), content);
@@ -1712,6 +1843,7 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   stampAndroidGradleDeps(outDir, req.androidGradleDeps);
   stampKotlin(outDir, req.androidKotlin);
   generateModuleArtifacts(outDir, req);
+  regenerateMobilePlugins(cwd, cfg, outDir); // config-gated TS plugins → bridge handlers (in-process)
   copyModuleNativeSrc(outDir, req); // module-owned native source (e.g. health's Kotlin shim)
   substituteModuleTokens(outDir, req); // stamp __APP_GROUP__ etc. into the copied extension source
   stampLaunchScreen(outDir, cfg);

package/src/config.ts

@@ -17,6 +17,29 @@
  * JSON still supported as a fallback). See `loadConfig` in cli.ts.
  */
 
+/** A single named environment shown in the switcher menu. */
+export interface EnvSwitcherEnv {
+  /** Human label shown in the menu + banner (e.g. 'Prod', 'Lab', 'PR #123'). */
+  label: string;
+  /** Absolute origin the WebView loads for this env (e.g. 'https://lab.example.com'). */
+  url: string;
+}
+
+/** Runtime env-switcher config (see `AppwrapConfig.envSwitcher`). */
+export interface EnvSwitcherConfig {
+  /** Kill-switch. Omitted → ON when the block is present. A prod config fork can set `false` to
+   * HARD-DISABLE the whole feature (menu action + banner + boot override all inert) even if `envs` /
+   * `allowPattern` are declared. Absent `envSwitcher` block entirely → also off (default for any app). */
+  enabled?: boolean;
+  /** Presets shown in the switch menu; always implicitly trusted (bypass `allowPattern`). */
+  envs?: EnvSwitcherEnv[];
+  /** Anchored regex (`^…$`) gating the free-form "Other" URL entry. DEFAULT-DENY: absent/invalid →
+   * "Other" is disabled (presets only). Compiled with try/catch; a throwing pattern → default-deny. */
+  allowPattern?: string;
+  /** Deeplink auto-switch (Phase 2 — not yet implemented). Opt-in. */
+  deeplink?: boolean;
+}
+
 export interface AppwrapConfig {
   id: string;
   name: string;
@@ -168,6 +191,13 @@ export interface AppwrapConfig {
   loader?: 'app' | 'file' | 'server';
   /** Live URL loaded when loader === 'server'. Set via config or `appwrap dev --url <url>`. */
   serverUrl?: string;
+  /** Runtime env-switcher (loader:'server' apps). Lets a build re-point the WebView between declared
+   * environments (prod / lab / a preview URL) at runtime — via the native dev-menu "Switch Environment"
+   * action + a bottom env-indicator banner — surviving a cold start, with NO separate native build.
+   * The chosen URL persists in native storage (`kit:serverUrlOverride`) and is honored by the shell's
+   * boot loader. Runs in ALL build types when configured (gate = `allowPattern` + `enabled`, NOT debug —
+   * distinct from the debug-only dev-server cert trust). Absent block → the whole feature is inert. */
+  envSwitcher?: EnvSwitcherConfig;
   /** Absolute backend origin for an offline (loader:'app') PWA whose API/WebSocket calls were
    * originally same-origin (e.g. "https://api.example.com"). Injected to the page as
    * `window.__APPWRAP_BACKEND_ORIGIN__`; a same-origin PWA reads it to make its calls absolute.
@@ -337,7 +367,7 @@ export function defineConfig(config: AppwrapConfig): AppwrapConfig {
 export const KNOWN_CONFIG_KEYS: ReadonlySet<string> = new Set([
   'androidAppLinks', 'appBoundDomains', 'backendOrigin', 'backgroundAudio', 'backgroundColor', 'backgroundTasks', 'buildNumber', 'debug',
   'debugLog', 'desktop', 'devMenu', 'edgeToEdge', 'entry', 'icon', 'id', 'iosKeyboardExtraLift', 'loader', 'modules', 'name',
-  'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
+  'envSwitcher', 'iosEntitlements', 'neutralizeServiceWorker', 'oauthRedirectSchemes', 'openNewWindowsInBrowser', 'orientation', 'overrides', 'permissions',
   'plugins', 'push', 'pwaDist', 'queryPackages', 'queryUrlSchemes', 'serverUrl', 'signing', 'signingProfiles', 'statusBarStyle',
   'splashIcon', 'storekitConfig', 'targetedDevices', 'teamId', 'themeColor', 'trackingDomains', 'urlScheme',
   'usesNonExemptEncryption', 'vendorPaths', 'version',