@livx.cc/appwrap 0.54.0 → 0.55.0

package/src/cli.ts

@@ -10,7 +10,7 @@
  */
 import { execFileSync, spawn, spawnSync } from 'child_process';
 import { createHash } from 'crypto';
-import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
+import { copyFileSync, cpSync, existsSync, mkdirSync, openSync, closeSync, readdirSync, readFileSync, readSync, renameSync, rmSync, statSync, writeFileSync, writeSync } from 'fs';
 import { builtinModules } from 'module';
 import { networkInterfaces, tmpdir } from 'os';
 import { basename, delimiter as pathDelimiter, dirname, extname, join, resolve } from 'path';
@@ -23,6 +23,7 @@ import type * as CapManifest from '../../../runtime/app/shell/capabilities.manif
 // type + `defineConfig` helper without pulling in (and running) the CLI dispatch.
 import type { AppwrapConfig } from './config';
 import { unknownConfigKeys } from './config';
+import { resolveModulePacks, type ResolvedModule, type SyncContext } from './packs';
 import { createHash } from 'crypto';
 import { buildInfoPlist, buildMacEntitlements, deriveDesktopConfig, parseMacProfile, resolveCargoPath, stampTauriConf } from './desktop';
 import type { DesktopShellConfig } from './desktop';
@@ -103,10 +104,42 @@ function resolveAssetRoot(rel: string): string {
   return existsSync(local) ? local : resolve(import.meta.dir, '../../..', rel);
 }
 const TEMPLATE_DIR = resolveAssetRoot('runtime');
+/** Ordered runtime-template roots copied into native/ (later roots overlay earlier — file-level
+ * last-wins), defaulting to the single built-in template. runCli (A5) can extend this so a consumer
+ * like appwrap-ee layers extra shell files on top of CE without forking the template. A single root
+ * is byte-identical to the pre-overlay behavior. */
+let TEMPLATE_ROOTS: string[] = [TEMPLATE_DIR];
 const CI_TEMPLATE_DIR = resolveAssetRoot('templates/ci');
+/** Scaffold for `appwrap create-module` — a starter module pack (see packs.ts / @livx.cc/appwrap/testing). */
+const MODULE_PACK_TEMPLATE_DIR = resolveAssetRoot('templates/module-pack');
 /** Desktop (Tauri chassis) template — phase-0, macOS-only. Its own generated wrapper (`native-desktop/`)
- * is disposable, like `native/`; the template stays canonical (edit here, regenerate propagates). */
-const DESKTOP_TEMPLATE_DIR = resolveAssetRoot('runtime-desktop');
+ * is disposable, like `native/`; the template stays canonical (edit here, regenerate propagates).
+ * A `let` so runCli (A5) can point it at a host-provided template (e.g. appwrap-ee owns the desktop lane). */
+let DESKTOP_TEMPLATE_DIR = resolveAssetRoot('runtime-desktop');
+
+/**
+ * Composition seam for a HOST that wraps this CLI (appwrap-ee, or any consumer). Every field is
+ * optional and no-op by default, so the bare `appwrap` bin behaves exactly as before. A host calls
+ * `runCli({...})` to extend the CLI without forking it.
+ */
+export interface CliOptions {
+  /** Extra or overriding top-level commands, keyed by command name — consulted BEFORE the built-in
+   * switch, so a host can add a command or replace a built-in one. */
+  commands?: Record<string, (cwd: string, flags: Record<string, string>, positionals: string[]) => Promise<void> | void>;
+  /** Pluggable platform handlers for `dev`/`build` (keyed by the platform arg, e.g. 'desktop') —
+   * consulted BEFORE the built-in platform routing, so a host can add/replace a platform lane. */
+  platforms?: Record<string, (cwd: string, flags: Record<string, string>, positionals: string[]) => Promise<void> | void>;
+  /** Module packs injected by the host, applied BEFORE the app config's own `modulePacks` (so the app
+   * can still override them, last-wins). */
+  modulePacks?: string[];
+  /** Extra runtime-template overlay roots, appended after the built-in template (later roots win). */
+  templateRoots?: string[];
+  /** Override for the desktop (Tauri) template dir. */
+  desktopTemplateDir?: string;
+}
+
+/** The host composition for THIS run, set once by runCli. Empty by default → bare-bin behavior. */
+let cliOptions: CliOptions = {};
 
 /** This CLI's own published version — used to pin the `bunx @livx.cc/appwrap@^x.y.z` invocations the
  * emitted workflow runs. Pinning to THIS version's floor means CI fails LOUDLY ("version not found")
@@ -116,10 +149,67 @@ const CLI_VERSION: string = (await import(resolve(import.meta.dir, '..', 'packag
 
 // Load the capability manifest VALUES from the resolved runtime (pure data — safe outside NativeScript).
 // Top-level await resolves before any command dispatches at the bottom of this file.
-const { MODULES, OPTIONAL_GROUPS } = (await import(
+const { MODULES, OPTIONAL_GROUPS, LEGACY_BUNDLED_GROUPS, MANIFEST_SCHEMA_VERSION } = (await import(
   resolve(TEMPLATE_DIR, 'app/shell/capabilities.manifest')
 )) as typeof CapManifest;
 
+/** The composed module set for THIS command run: built-ins + the config's `modulePacks`, resolved once
+ * at command entry by `applyModulePacks`. Stays `null` when NO packs are configured — every code path
+ * then reads the built-in `MODULES` directly, so a pack-less build is byte-identical to pre-packs. */
+let RESOLVED_MODULES: ResolvedModule[] | null = null;
+
+/** The active module set the CLI derives from — merged (built-ins + packs) when packs are configured,
+ * else the built-ins verbatim. */
+function moduleList(): CapManifest.ModuleManifest[] {
+  return RESOLVED_MODULES ? RESOLVED_MODULES.map((r) => r.manifest) : MODULES;
+}
+
+/** Pack provenance for a module name (source label + pack dir) — used by the generator to locate a
+ * pack module's handler file + native source. Undefined for a built-in. */
+function packInfo(name: string): { source: string; packDir: string } | undefined {
+  const r = RESOLVED_MODULES?.find((m) => m.manifest.name === name);
+  return r && r.packDir ? { source: r.source, packDir: r.packDir } : undefined;
+}
+
+/** Resolve the config's `modulePacks` (if any) into RESOLVED_MODULES for this run. No-op (leaves the
+ * built-ins untouched → byte-identical) when the config declares no packs. Async because pack manifests
+ * are dynamically imported; callers await it before the sync/regenerate pipeline. */
+async function applyModulePacks(cwd: string, cfg: AppwrapConfig): Promise<void> {
+  // Host-injected packs first (appwrap-ee's), then the app config's — so the app can override, last-wins.
+  const refs = [...(cliOptions.modulePacks ?? []), ...(cfg.modulePacks ?? [])];
+  if (refs.length === 0) {
+    RESOLVED_MODULES = null;
+  } else {
+    const ctx: SyncContext = {
+      platform: 'both',
+      env: process.env.APPWRAP_ENV || 'default',
+      ci: !!process.env.CI,
+    };
+    const map = await resolveModulePacks({
+      builtins: MODULES,
+      builtinSchemaVersion: MANIFEST_SCHEMA_VERSION,
+      packRefs: refs,
+      ctx,
+      cwd,
+    });
+    RESOLVED_MODULES = [...map.values()];
+  }
+  warnUnknownModules(cfg);
+}
+
+/** Warn (never fail) for any name in `modules` that resolves to neither a built-in nor a pack module —
+ * with the pack model it's easy to list a capability (e.g. 'billing') and forget to add its pack to
+ * `modulePacks`, which would otherwise silently no-op (no handler, no capability). */
+function warnUnknownModules(cfg: AppwrapConfig): void {
+  if (!cfg.modules) return;
+  const known = new Set(moduleList().map((m) => m.name));
+  for (const name of cfg.modules) {
+    if (!known.has(name)) {
+      console.warn(`⚠ module '${name}' is listed in \`modules\` but isn't a built-in or provided by any \`modulePacks\` — did you forget to add its pack? (ignored)`);
+    }
+  }
+}
+
 /** Native requirements composed for a build: the union (deduped) of the active modules' self-contained
  * manifest declarations. Two modes:
  *  - `modules` ABSENT (legacy): every capability active; permissions come ONLY from `permissions{}`
@@ -137,20 +227,25 @@ interface NativeReqs {
   androidGradleDeps: string[];
   androidKotlin: boolean;        // any active module ships Kotlin native source
   androidManifestApp: string[];  // raw XML injected inside AndroidManifest <application>
-  nativeSrc: string[];           // active modules' nativeSrc dir names (under runtime/modules-native/)
-  widgetAppGroup?: string;       // 'group.<appId>' when the `widget` module is active (App Group id
-                                 // shared by the app + its widget extension; templated into both)
+  nativeSrc: string[];           // active BUILT-IN modules' nativeSrc dir names (under runtime/modules-native/)
+  packNativeSrc: Array<{ name: string; srcDir: string }>;  // active PACK modules' native source (absolute src dirs)
+  packHandlers: Array<{ name: string; source: string; packDir: string; file: string; fn: string }>; // active pack modules with a register handler (for the generated barrel + staging)
+  packModules: Array<Pick<CapManifest.ModuleManifest, 'name' | 'core' | 'capabilities' | 'group'>>; // active pack modules' handshake-relevant subset (their capabilities aren't in the runtime's static MODULES)
 }
 
 function nativeReqs(cfg: AppwrapConfig): NativeReqs {
-  const optIn = MODULES.filter((m) => !m.core);
+  const modules = moduleList();
+  const optIn = modules.filter((m) => !m.core);
   // Legacy default (no `modules` key) = every opt-in capability EXCEPT strictly-opt-in own-file
   // modules (OPTIONAL_GROUPS, e.g. health): those carry deps/perms legacy won't stamp, so they must
   // be explicitly requested. Explicit mode = exactly what `modules` lists.
   const active = cfg.modules
     ? new Set(cfg.modules)
-    : new Set(optIn.filter((m) => !OPTIONAL_GROUPS.includes(m.group as (typeof OPTIONAL_GROUPS)[number])).map((m) => m.name));
-  const activeMods = MODULES.filter((m) => m.core || active.has(m.name));
+    : new Set(optIn.filter((m) =>
+        !OPTIONAL_GROUPS.includes(m.group as (typeof OPTIONAL_GROUPS)[number]) ||
+        LEGACY_BUNDLED_GROUPS.includes(m.group as (typeof LEGACY_BUNDLED_GROUPS)[number])
+      ).map((m) => m.name));
+  const activeMods = modules.filter((m) => m.core || active.has(m.name));
 
   const iosPlist: Array<{ key: string; usage: string }> = [];
   const seenKeys = new Set<string>();
@@ -158,6 +253,9 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
   const gradle = new Set<string>();
   const iosEntitlements: Record<string, boolean | string | string[]> = {};
   const nativeSrc: string[] = [];
+  const packNativeSrc: NativeReqs['packNativeSrc'] = [];
+  const packHandlers: NativeReqs['packHandlers'] = [];
+  const packModules: NativeReqs['packModules'] = [];
   const androidManifestApp: string[] = [];
   let androidKotlin = false;
 
@@ -174,7 +272,9 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
       Object.assign(iosEntitlements, m.ios?.entitlements ?? {});
       if (m.android?.kotlin) androidKotlin = true;
       if (m.android?.manifestApplication) androidManifestApp.push(m.android.manifestApplication);
-      if (m.nativeSrc) nativeSrc.push(m.nativeSrc);
+      // built-in native source resolves under runtime/modules-native/; pack native source (below)
+      // resolves under the pack's own dir, so it must not be conflated with the built-in dir names.
+      if (m.nativeSrc && !packInfo(m.name)) nativeSrc.push(m.nativeSrc);
     }
   } else {
     // legacy: only what `permissions{}` declares (via the key maps) — no behavior change
@@ -186,6 +286,18 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
     }
   }
 
+  // Active PACK modules (from the config's modulePacks) — their native source + register handler
+  // resolve against the pack's own dir. No-op when no packs are configured (packInfo → undefined).
+  for (const m of activeMods) {
+    const info = packInfo(m.name);
+    if (!info) continue;
+    if (m.nativeSrc) packNativeSrc.push({ name: m.name, srcDir: join(info.packDir, 'native-src', m.nativeSrc) });
+    if (m.handler) packHandlers.push({ name: m.name, source: info.source, packDir: info.packDir, file: m.handler.file, fn: m.handler.fn });
+    // The runtime's static MODULES doesn't include pack modules, so their capabilities must be carried
+    // into the generated handshake map explicitly (see generateModuleArtifacts + buildCapabilityMap).
+    packModules.push({ name: m.name, core: m.core, capabilities: m.capabilities, group: m.group });
+  }
+
   return {
     explicit: !!cfg.modules,
     activeOptIn: optIn.filter((m) => active.has(m.name)).map((m) => m.name),
@@ -197,15 +309,14 @@ function nativeReqs(cfg: AppwrapConfig): NativeReqs {
     androidKotlin,
     androidManifestApp,
     nativeSrc,
-    // App Group for the widget extension ↔ app shared container. Derived from the app id so the module
-    // stays app-agnostic; templated into app.entitlements + the extension's entitlements/Swift.
-    widgetAppGroup: active.has('widget') ? `group.${cfg.id}` : undefined,
+    packNativeSrc,
+    packHandlers,
+    packModules,
   };
 }
 
 /** Map a strippable optional group → its handler file + register fn (for the generated barrel). */
 const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
-  health: { file: './handlers-health', fn: 'registerHealthHandlers' },
   oauth: { file: './handlers-oauth', fn: 'registerOAuthHandlers' },
   reviews: { file: './handlers-reviews', fn: 'registerReviewsHandlers' },
   scanner: { file: './handlers-scanner', fn: 'registerScannerHandlers' },
@@ -213,22 +324,112 @@ const OPTIONAL_GROUP_HANDLERS: Record<string, { file: string; fn: string }> = {
   tracking: { file: './handlers-tracking', fn: 'registerTrackingHandlers' },
   appleSignIn: { file: './handlers-apple-signin', fn: 'registerAppleSignInHandlers' },
   backgroundTask: { file: './handlers-background', fn: 'registerBackgroundTaskHandlers' },
-  widget: { file: './handlers-widget', fn: 'registerWidgetHandlers' },
+  // billing/health/widget moved to appwrap-ee packs — their handlers stage from packages/ee/packs/*.
 };
 
+/** The bare specifier a pack handler uses to import a built-in shell API — rewritten to a relative
+ * `./<mod>` when the file is staged next to the shell sources. A pack authored out-of-repo imports
+ * e.g. `@livx.cc/appwrap/runtime/app/shell/bridge` (resolvable, since the npm package ships runtime/),
+ * so it typechecks standalone; staging drops it beside the real shell files, where `./bridge` resolves. */
+const SHELL_API_SPECIFIER = /(['"])@livx\.cc\/appwrap\/runtime\/app\/shell\//g;
+
+/** Rewrite a pack handler's shell-API imports from the package specifier to relative, so the file
+ * resolves once staged beside the real shell sources. Pure (exported for tests). */
+export function rewritePackShellImports(src: string): string {
+  return src.replace(SHELL_API_SPECIFIER, '$1./');
+}
+
+/** Resolve a pack-local relative import specifier to an absolute source file (trying the usual TS/JS
+ * extensions + an index file), or null if it doesn't resolve to a real file. */
+function resolvePackImport(fromDir: string, spec: string): string | null {
+  const base = resolve(fromDir, spec);
+  const cands = [base, `${base}.ts`, `${base}.tsx`, `${base}.js`, `${base}.jsx`, join(base, 'index.ts'), join(base, 'index.js')];
+  return cands.find((c) => existsSync(c) && statSync(c).isFile()) ?? null;
+}
+
+/** Replace an exact (quoted) import specifier in source with another — anchored so `./x` never
+ * partial-matches `./x-y`. Pure (exported for tests). */
+export function replaceImportSpecifier(src: string, oldSpec: string, newSpec: string): string {
+  const esc = oldSpec.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return src.replace(new RegExp(`(['"])${esc}\\1`, 'g'), `$1${newSpec}$1`);
+}
+
+/** Stage a pack source file into the shell, namespaced `pack-<label>-<name>.ts` (never colliding with a
+ * built-in file — keeps built-in staged filenames stable, preserving the byte-compare gate). Rewrites
+ * (a) shell-API imports → relative `./<x>`, and (b) pack-LOCAL relative imports → their namespaced
+ * staged sibling, staging each RECURSIVELY — so a handler's own helper modules (e.g. billing's
+ * billing-offer.ts) are staged too. `staged` memoizes by abs path (dedup + cycle guard). `entryName`
+ * overrides the staged basename for the handler entry (so the barrel imports it by module identity). */
+function stagePackFile(shell: string, label: string, packDir: string, absFile: string, staged: Map<string, string>, entryName?: string): string {
+  const cached = staged.get(absFile);
+  if (cached) return cached;
+  if (!existsSync(absFile)) {
+    console.error(`✖ module pack "${label}": imported file not found: ${absFile}`);
+    process.exit(1);
+  }
+  const name = entryName ?? basename(absFile).replace(/\.(tsx?|jsx?)$/, '');
+  const destName = `pack-${label}-${name}.ts`;
+  const spec = `./${destName.replace(/\.ts$/, '')}`;
+  staged.set(absFile, spec); // set BEFORE recursing so an import cycle terminates
+
+  let src = rewritePackShellImports(readFileSync(absFile, 'utf8'));
+  const fromDir = dirname(absFile);
+  for (const imp of new Bun.Transpiler({ loader: loaderForEntry(absFile) }).scanImports(src)) {
+    if (!imp.path.startsWith('.')) continue; // only pack-LOCAL relative imports need staging
+    const depAbs = resolvePackImport(fromDir, imp.path);
+    if (!depAbs || !depAbs.startsWith(packDir + '/')) continue; // must stay inside the pack dir
+    const depSpec = stagePackFile(shell, label, packDir, depAbs, staged);
+    src = replaceImportSpecifier(src, imp.path, depSpec);
+  }
+  writeFileSync(join(shell, destName), src);
+  return spec;
+}
+
+/** Stage a pack module's handler (+ its pack-local imports) into the shell. Returns the import
+ * specifier the generated barrel imports the handler by. */
+function stagePackHandler(shell: string, h: NativeReqs['packHandlers'][number]): string {
+  const srcFile = resolve(h.packDir, h.file);
+  if (!existsSync(srcFile)) {
+    console.error(`✖ module pack "${h.source}": handler file not found: ${srcFile}`);
+    process.exit(1);
+  }
+  const label = h.source.replace(/[^a-zA-Z0-9_-]/g, '_');
+  const spec = stagePackFile(shell, label, h.packDir, srcFile, new Map(), h.name);
+  console.log(`  pack ← ${h.source}  (${h.name} handler)`);
+  return spec;
+}
+
 /** Generate the two composition artifacts in the wrapper: the active capability list (drives the
  * handshake map) and the optional-handler barrel (imports only active strippable groups). */
 function generateModuleArtifacts(outDir: string, req: NativeReqs): void {
   const shell = join(outDir, 'app/shell');
+  // Sweep stale pack-staged handlers first so a removed/renamed pack never leaves an orphan behind
+  // (self-pruning, like regenerateMobilePlugins wiping its dir) — the active ones are re-staged below.
+  for (const f of existsSync(shell) ? readdirSync(shell) : []) {
+    if (f.startsWith('pack-') && f.endsWith('.ts')) rmSync(join(shell, f), { force: true });
+  }
   writeFileSync(
     join(shell, 'active-modules.generated.ts'),
-    `/** Generated by \`appwrap\` from the appwrap config \`modules\`. Do not edit. */\n` +
-      `export const ACTIVE_MODULE_NAMES: string[] = ${JSON.stringify(req.activeOptIn)};\n`
+    `/** Generated by \`appwrap\` from the appwrap config \`modules\` + \`modulePacks\`. Do not edit. */\n` +
+      `import type { ModuleManifest } from './capabilities.manifest';\n` +
+      `export const ACTIVE_MODULE_NAMES: string[] = ${JSON.stringify(req.activeOptIn)};\n` +
+      // Pack modules aren't in the runtime's static MODULES, so their handshake capabilities travel here
+      // and buildCapabilityMap merges them (empty for a pack-less build).
+      `export const PACK_MODULES: Array<Pick<ModuleManifest, 'name' | 'core' | 'capabilities' | 'group'>> = ${JSON.stringify(req.packModules)};\n`
   );
 
   const groups = req.activeOptionalGroups.filter((g) => OPTIONAL_GROUP_HANDLERS[g]);
-  const imports = groups.map((g) => `import { ${OPTIONAL_GROUP_HANDLERS[g].fn} } from '${OPTIONAL_GROUP_HANDLERS[g].file}';`).join('\n');
-  const calls = groups.map((g) => `  ${OPTIONAL_GROUP_HANDLERS[g].fn}();`).join('\n');
+  const importLines = groups.map((g) => `import { ${OPTIONAL_GROUP_HANDLERS[g].fn} } from '${OPTIONAL_GROUP_HANDLERS[g].file}';`);
+  const callLines = groups.map((g) => `  ${OPTIONAL_GROUP_HANDLERS[g].fn}();`);
+  // Active PACK modules with a register handler — staged into the shell + APPENDED after the built-in
+  // groups (empty when no packs → byte-identical to the pre-packs barrel).
+  for (const h of req.packHandlers) {
+    const spec = stagePackHandler(shell, h);
+    importLines.push(`import { ${h.fn} } from '${spec}';`);
+    callLines.push(`  ${h.fn}();`);
+  }
+  const imports = importLines.join('\n');
+  const calls = callLines.join('\n');
   writeFileSync(
     join(shell, 'optional-handlers.generated.ts'),
     `/** Generated by \`appwrap\` — only the active strippable modules are imported. Do not edit. */\n` +
@@ -394,9 +595,13 @@ function stampEntitlements(outDir: string, cfg: AppwrapConfig, req: NativeReqs):
   const file = join(iosDir, 'app.entitlements');
   const ent: Record<string, boolean | string | string[]> = { ...req.iosEntitlements, ...cfg.iosEntitlements };
   if (!!cfg.push?.enabled && cfg.push?.ios !== false) ent['aps-environment'] = cfg.push.apsEnvironment ?? 'development';
-  // Widget module → App Group on the MAIN app target (the extension's own entitlements file gets the
-  // same group via token substitution). Derived from the app id so no per-app config is needed.
-  if (req.widgetAppGroup) ent['com.apple.security.application-groups'] = [req.widgetAppGroup];
+  // Resolve build tokens in entitlement values (e.g. a module's `__APP_GROUP__` → group.<appId>) so a
+  // module declaring an app-derived entitlement (widget's App Group) needs no hardcoded stamper case.
+  const tokens = buildTokens(cfg);
+  for (const [k, v] of Object.entries(ent)) {
+    if (typeof v === 'string') ent[k] = substituteBuildTokens(v, tokens);
+    else if (Array.isArray(v)) ent[k] = v.map((x) => substituteBuildTokens(x, tokens));
+  }
   const keys = Object.keys(ent);
   if (keys.length === 0) { rmSync(file, { force: true }); return; }
   const val = (v: boolean | string | string[]): string =>
@@ -426,29 +631,52 @@ function stampPrivacyManifest(outDir: string, cfg: AppwrapConfig, req: NativeReq
   if (active) console.log(`  priv ← NSPrivacyTracking=true${cfg.trackingDomains?.length ? ` (${cfg.trackingDomains.length} domain${cfg.trackingDomains.length > 1 ? 's' : ''})` : ''}`);
 }
 
-/** Copy active modules' native source (runtime/modules-native/<name>/) into native/ — only when the
- * module is active, so module native code stays stripped from builds that don't use it. */
-function copyModuleNativeSrc(outDir: string, req: NativeReqs): void {
-  for (const name of req.nativeSrc) {
-    const src = join(MODULES_NATIVE_DIR, name);
-    if (!existsSync(src)) { console.warn(`⚠ module nativeSrc not found: ${src}`); continue; }
+/** Copy active modules' native source (runtime/modules-native/<name>/ for built-ins, <packDir>/
+ * native-src/<name>/ for packs) into native/ — only when the module is active, so module native code
+ * stays stripped from builds that don't use it. Returns the set of dest paths (relative to outDir) it
+ * copied, so regenerateCore can prune a now-INACTIVE module's native files on re-sync (they mirror the
+ * App_Resources layout and cpSync only overwrites, never deletes). */
+function copyModuleNativeSrc(outDir: string, req: NativeReqs): Set<string> {
+  const copied = new Set<string>();
+  const copyFrom = (src: string, label: string) => {
+    if (!existsSync(src)) { console.warn(`⚠ module nativeSrc not found: ${src}`); return; }
     cpSync(src, outDir, { recursive: true, force: true });
-    console.log(`  natv ← module '${name}' native source`);
-  }
+    for (const rel of collectRelFiles(src)) copied.add(rel);
+    console.log(`  natv ← ${label} native source`);
+  };
+  for (const name of req.nativeSrc) copyFrom(join(MODULES_NATIVE_DIR, name), `module '${name}'`);
+  for (const { name, srcDir } of req.packNativeSrc) copyFrom(srcDir, `pack module '${name}'`);
+  return copied;
+}
+
+/** Build-time tokens a module's native source / entitlements may reference — resolved from the app
+ * config so a module ships app-agnostic and the CLI stamps the app-specific value in. Not module-
+ * specific: any module (built-in or pack) can use these tokens. Currently `__APP_GROUP__` → the App
+ * Group id shared by the app + an extension (e.g. widget); extend here as new app-derived needs arise. */
+function buildTokens(cfg: AppwrapConfig): Record<string, string> {
+  return { __APP_GROUP__: `group.${cfg.id}` };
 }
 
-/** Substitute build-time tokens in copied module native source (after copyModuleNativeSrc). Currently
- * only `__APP_GROUP__` → the derived App Group id, applied to the widget extension's Swift/entitlements/
- * plist so the module ships app-agnostic and the CLI stamps the app-specific group in. Idempotent (the
- * source is re-copied verbatim each sync, then re-substituted). */
-function substituteModuleTokens(outDir: string, req: NativeReqs): void {
-  if (!req.widgetAppGroup) return;
+/** Substitute any {@link buildTokens} in a stamped string (entitlement value or native-source file). */
+function substituteBuildTokens(s: string, tokens: Record<string, string>): string {
+  let out = s;
+  for (const [tok, val] of Object.entries(tokens)) out = out.replaceAll(tok, val);
+  return out;
+}
+
+/** Substitute build-time tokens in copied module native source (after copyModuleNativeSrc) — applied
+ * generically to every iOS extension file, so a module's app-agnostic source (e.g. the widget
+ * extension's Swift/entitlements/plist) gets the app-specific value stamped in. Idempotent (source is
+ * re-copied verbatim each sync, then re-substituted). No-op when no extensions were copied. */
+function substituteModuleTokens(outDir: string, cfg: AppwrapConfig): void {
   const extRoot = join(outDir, 'App_Resources/iOS/extensions');
   if (!existsSync(extRoot)) return;
+  const tokens = buildTokens(cfg);
+  let touched = false;
   const subst = (file: string) => {
     const s = readFileSync(file, 'utf8');
-    if (!s.includes('__APP_GROUP__')) return;
-    writeFileSync(file, s.replaceAll('__APP_GROUP__', req.widgetAppGroup!));
+    const next = substituteBuildTokens(s, tokens);
+    if (next !== s) { writeFileSync(file, next); touched = true; }
   };
   const walk = (dir: string) => {
     for (const e of readdirSync(dir, { withFileTypes: true })) {
@@ -458,7 +686,7 @@ function substituteModuleTokens(outDir: string, req: NativeReqs): void {
     }
   };
   walk(extRoot);
-  console.log(`  tokn ← __APP_GROUP__ = ${req.widgetAppGroup} (widget extension)`);
+  if (touched) console.log(`  tokn ← __APP_GROUP__ = ${tokens.__APP_GROUP__} (extension source)`);
 }
 
 /** Hosts to register as Android App Links (autoVerify https intent-filters). Explicit
@@ -584,7 +812,7 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
   }
 
   // loader:'server' bakes serverUrl into the shell and loads it via NSURL/WKWebView. A scheme-less
-  // value (e.g. "agf.circlesup.com") produces an unusable URL — the app silently fails to load (or
+  // value (e.g. "app.example.com") produces an unusable URL — the app silently fails to load (or
   // shows a stale page) with no error. Normalize to https:// when no scheme is present, and fail loud
   // on a genuinely malformed URL rather than shipping a broken build.
   if (cfg.serverUrl) {
@@ -603,7 +831,7 @@ async function loadConfig(cwd: string, flags: Record<string, string>): Promise<A
   return cfg;
 }
 
-function stampShellConfig(outDir: string, cfg: AppwrapConfig): void {
+export 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;
@@ -628,6 +856,7 @@ export const SHELL_CONFIG = {
   loader: ${JSON.stringify(cfg.loader ?? 'app')} as 'app' | 'file' | 'server',
   serverUrl: ${JSON.stringify(cfg.serverUrl ?? '')},
   backendOrigin: ${JSON.stringify(cfg.backendOrigin ?? '')},
+  urlScheme: ${JSON.stringify(cfg.urlScheme ?? '')},
   debug: ${JSON.stringify(cfg.debug ?? false)},
   debugLog: ${JSON.stringify(cfg.debugLog ?? '*')},
   devMenu: ${JSON.stringify(cfg.devMenu ?? true)},
@@ -1626,17 +1855,23 @@ export function applyOverrides(cwd: string, outDir: string, cfg: AppwrapConfig):
   const dir = resolve(cwd, cfg.overrides ?? 'appwrap.overrides');
   // Files the template still provides must survive an override removal (regenerateCore ran first and
   // re-copied them) → protect them from the override prune.
-  const templateFiles = existsSync(TEMPLATE_DIR) ? collectRelFiles(TEMPLATE_DIR, templateCopyFilter) : new Set<string>();
+  const templateFiles = allTemplateFiles();
   // ACTIVE modules' native source needs the SAME protection: copyModuleNativeSrc re-copied it into
   // these exact relative paths, but it lives under runtime/modules-native/<name>/, which
   // templateCopyFilter deliberately excludes — so it is absent from templateFiles above. Without this,
   // dropping a consumer override that happened to shadow a module file prunes the MODULE's own copy
   // too (the prune only sees "was in the overrides manifest, isn't in overrides now"), silently
   // deleting e.g. res/xml/appwrap_widget_info.xml and failing the build at AAPT.
-  for (const name of nativeReqs(cfg).nativeSrc) {
+  const reqs = nativeReqs(cfg);
+  for (const name of reqs.nativeSrc) {
     const modDir = join(MODULES_NATIVE_DIR, name);
     if (existsSync(modDir)) for (const rel of collectRelFiles(modDir)) templateFiles.add(rel);
   }
+  // Same protection for active PACK modules' native source (lives under the pack dir, absent from the
+  // template file set) — so an override removal never prunes a pack module's own copied files.
+  for (const { srcDir } of reqs.packNativeSrc) {
+    if (existsSync(srcDir)) for (const rel of collectRelFiles(srcDir)) templateFiles.add(rel);
+  }
   if (!existsSync(dir)) {
     // No overrides now: prune anything a PRIOR overrides run left behind (renamed/removed override files).
     pruneStale(outDir, OVERRIDES_MANIFEST, new Set(), templateFiles);
@@ -1795,12 +2030,27 @@ function copyCiTemplates(cwd: string, outDir: string, cfg: AppwrapConfig, force
 // so without this a relocated source lingers in native/ and gets re-bundled.
 const TEMPLATE_MANIFEST = '.appwrap-template-manifest.json';
 const OVERRIDES_MANIFEST = '.appwrap-overrides-manifest.json';
+/** Tracks module-owned native source copied into native/ (built-in + pack), so a module DEACTIVATED
+ * since the last sync has its App_Resources files pruned rather than lingering (cpSync never deletes). */
+const MODULE_NATIVE_MANIFEST = '.appwrap-module-native-manifest.json';
 
 /** Files under TEMPLATE_DIR to skip when copying/walking it (deps, build output, PWA staging, per-module
  * native — those are handled selectively elsewhere). Shared by the cpSync filter and the prune walk so
  * the copied set and the pruned set are defined identically. */
-const templateCopyFilter = (src: string): boolean =>
-  !/(?:^|\/)(node_modules|platforms|hooks|app\/www|modules-native)(\/|$)/.test(src.slice(TEMPLATE_DIR.length));
+const templateCopyFilterFor = (root: string) => (src: string): boolean =>
+  !/(?:^|\/)(node_modules|platforms|hooks|app\/www|modules-native)(\/|$)/.test(src.slice(root.length));
+/** Single-root filter for the built-in template (the common path). */
+const templateCopyFilter = templateCopyFilterFor(TEMPLATE_DIR);
+/** Every file the active template roots contribute, relative to each root (deduped across roots) —
+ * the union prune set + override-protection set for the overlay chain. */
+function allTemplateFiles(): Set<string> {
+  const out = new Set<string>();
+  for (const root of TEMPLATE_ROOTS) {
+    if (!existsSync(root)) continue;
+    for (const rel of collectRelFiles(root, templateCopyFilterFor(root))) out.add(rel);
+  }
+  return out;
+}
 
 /** File (not dir) paths under `root`, relative to it, skipping entries `accept` rejects. */
 function collectRelFiles(root: string, accept: (abs: string) => boolean = () => true): Set<string> {
@@ -1851,16 +2101,23 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   if (opts.firstRun && !req.explicit) {
     console.log('  ℹ no `modules` in the appwrap config → all capabilities active. Declare `modules` to shrink the store build (strip unused handlers/perms).');
   }
-  cpSync(TEMPLATE_DIR, outDir, {
-    recursive: true,
-    force: true, // explicit: Bun's cpSync does not overwrite existing files by default
-    // modules-native/ is copied selectively per active module (copyModuleNativeSrc), not wholesale.
-    // Match RELATIVE to TEMPLATE_DIR — when installed from npm, TEMPLATE_DIR itself sits under
-    // node_modules/, so testing the absolute path would wrongly exclude the entire template.
-    filter: templateCopyFilter,
-  });
-  // Delete template files removed/renamed since the last regenerate (cpSync only overwrites, never deletes).
-  pruneStale(outDir, TEMPLATE_MANIFEST, collectRelFiles(TEMPLATE_DIR, templateCopyFilter));
+  // Copy each template root in order — later roots OVERLAY earlier (file-level last-wins), so a
+  // consumer template can add or replace shell files without forking CE. Single root (default) is
+  // exactly the pre-overlay copy.
+  for (const root of TEMPLATE_ROOTS) {
+    if (!existsSync(root)) { console.warn(`⚠ template root not found: ${root}`); continue; }
+    cpSync(root, outDir, {
+      recursive: true,
+      force: true, // explicit: Bun's cpSync does not overwrite existing files by default
+      // modules-native/ is copied selectively per active module (copyModuleNativeSrc), not wholesale.
+      // Match RELATIVE to the root — when installed from npm, a root itself sits under node_modules/,
+      // so testing the absolute path would wrongly exclude the entire template.
+      filter: templateCopyFilterFor(root),
+    });
+  }
+  // Delete template files removed/renamed since the last regenerate (cpSync only overwrites, never
+  // deletes) — pruned against the UNION of all roots' files so an overlay-provided file isn't culled.
+  pruneStale(outDir, TEMPLATE_MANIFEST, allTemplateFiles());
   stampShellConfig(outDir, cfg);
   stampNativeScriptConfig(outDir, cfg);
   stampIOSDisplayName(outDir, cfg, req);
@@ -1872,8 +2129,12 @@ function regenerateCore(cwd: string, outDir: string, cfg: AppwrapConfig, opts: {
   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
+  const moduleNativeFiles = copyModuleNativeSrc(outDir, req); // module-owned native source (e.g. health's Kotlin shim)
+  // Prune a now-inactive module's native files (in the prior manifest, not re-copied this sync). Protect
+  // base-template files so a module that overrode a template App_Resources file, once removed, reverts to
+  // the template copy instead of being deleted outright.
+  pruneStale(outDir, MODULE_NATIVE_MANIFEST, moduleNativeFiles, allTemplateFiles());
+  substituteModuleTokens(outDir, cfg); // stamp __APP_GROUP__ etc. into the copied extension source
   stampLaunchScreen(outDir, cfg);
   stampStoreKit(cwd, outDir, cfg);
   stampPush(cwd, outDir, cfg);
@@ -1908,6 +2169,7 @@ async function init(cwd: string, flags: Record<string, string>): Promise<void> {
 
   console.log(`🎁 appwrap init → ${outDir}`);
   mkdirSync(outDir, { recursive: true });
+  await applyModulePacks(cwd, cfg); // resolve config `modulePacks` (no-op when none) before deriving
   regenerateCore(cwd, outDir, cfg, { firstRun: true, flags });
   copyCiTemplates(cwd, outDir, cfg, 'force' in flags, 'ci' in flags); // GH workflows: opt-in (--ci), first-time only; fastlane lane: re-emit on --force
   writeFileSync(join(outDir, '.gitignore'), 'node_modules/\nplatforms/\nhooks/\n');
@@ -1928,6 +2190,7 @@ async function sync(cwd: string, flags: Record<string, string>, cfgOverride?: Ap
     console.error(`✖ Wrapper not found at ${outDir} — run \`appwrap init\` first`);
     process.exit(1);
   }
+  await applyModulePacks(cwd, cfg); // resolve config `modulePacks` (no-op when none) before deriving
   regenerateCore(cwd, outDir, cfg, { flags });
   applyOverrides(cwd, outDir, cfg); // overrides win last
   stampManualSigning(outDir, cfg, { configPath: resolveConfigPath(cwd, flags) }); // AFTER overrides: a consumer's extension.json / build.xcconfig would otherwise clobber the signing stamp
@@ -2002,6 +2265,7 @@ function openInspector(cfg: AppwrapConfig, flags: Record<string, string>, platfo
  */
 async function dev(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
+  if (platform && cliOptions.platforms?.[platform]) return void await cliOptions.platforms[platform](cwd, flags, positionals);
   if (platform === 'desktop') return devDesktop(cwd, flags);
   const sim = 'sim' in flags || positionals[1] === 'sim';
   const wantDebug = 'debug' in flags;
@@ -2040,6 +2304,7 @@ async function dev(cwd: string, flags: Record<string, string>, positionals: stri
       : stamped?.loader === 'server'
         ? { ...cfg, loader: 'server', serverUrl: stamped.serverUrl, debug: stamped.debug }
         : cfg;
+    await applyModulePacks(cwd, simCfg); // resolve config `modulePacks` (no-op when none) before deriving
     regenerateCore(cwd, outDir, simCfg, { flags });
     applyOverrides(cwd, outDir, simCfg); // overrides win last — same order as sync
     stampIOSExtensionVersions(outDir, simCfg); // AFTER overrides: keep extension version matching the app's (Xcode warns on mismatch)
@@ -2921,6 +3186,7 @@ async function buildDesktop(cwd: string, flags: Record<string, string>): Promise
 
 async function build(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
   const platform = positionals[0];
+  if (platform && cliOptions.platforms?.[platform]) return void await cliOptions.platforms[platform](cwd, flags, positionals);
   if (platform === 'desktop') return buildDesktop(cwd, flags);
   if (platform !== 'ios' && platform !== 'android') {
     console.error('Usage: appwrap build <ios|android|desktop> [--release] [--aab] [--config <path>] [--out native]');
@@ -3277,8 +3543,8 @@ function pinTeamIdToConfig(configPath: string, teamId: string): void {
  * `app/www` (PWA staging) is build OUTPUT and `node_modules`/`platforms`/`hooks` are generated, so all four
  * would make the hash unstable across runs. Matched RELATIVE to TEMPLATE_DIR: when installed from npm
  * TEMPLATE_DIR itself lives under node_modules/, and testing the absolute path would exclude everything. */
-const templateFingerprintFilter = (src: string): boolean =>
-  !/(?:^|\/)(node_modules|platforms|hooks|app\/www)(\/|$)/.test(src.slice(TEMPLATE_DIR.length));
+const templateFingerprintFilterFor = (root: string) => (src: string): boolean =>
+  !/(?:^|\/)(node_modules|platforms|hooks|app\/www)(\/|$)/.test(src.slice(root.length));
 
 /** Cheap fingerprint of SOURCE build inputs: mtime sum of the PWA dist/ + appwrap config + the appwrap
  * `runtime/` template tree + this CLI's version.
@@ -3317,12 +3583,16 @@ function buildInputStats(cwd: string, cfg: { pwaDist?: string; overrides?: strin
   const distDir = cfg.pwaDist ? resolve(cwd, cfg.pwaDist) : join(cwd, 'dist');
   const overridesDir = resolve(cwd, cfg.overrides ?? 'appwrap.overrides');
   const stats = [mtimeStats(distDir), mtimeStats(overridesDir), mtimeStats(resolveConfigPath(cwd, flags))];
-  // The appwrap runtime template — bundled into bundle.js, so it is a first-class build input.
+  // The appwrap runtime template(s) — bundled into bundle.js, so a first-class build input. Every
+  // overlay root counts, so editing a host-provided (e.g. appwrap-ee) template file busts the cache.
   let runtime = 0, runtimeNewest = 0;
-  for (const rel of collectRelFiles(TEMPLATE_DIR, templateFingerprintFilter)) {
-    const s = mtimeStats(join(TEMPLATE_DIR, rel));
+  for (const root of TEMPLATE_ROOTS) {
+   if (!existsSync(root)) continue;
+   for (const rel of collectRelFiles(root, templateFingerprintFilterFor(root))) {
+    const s = mtimeStats(join(root, rel));
     runtime += s.sum;
     if (s.newest > runtimeNewest) runtimeNewest = s.newest;
+   }
   }
   stats.push({ sum: runtime, newest: runtimeNewest });
   return { parts: stats.map((s) => s.sum), newest: Math.max(...stats.map((s) => s.newest)) };
@@ -4240,10 +4510,69 @@ async function publish(cwd: string, flags: Record<string, string>, positionals:
   console.log(`✓ Uploaded to Play ${track} track.`);
 }
 
-async function main(): Promise<void> {
+/** Scaffold a new module pack from the built-in template — the community entry point for authoring an
+ * extension. `appwrap create-module <name> [--dir <parent>]` writes <parent>/<name>/ with a manifest +
+ * handler + native-src stub, substituting the module name (and its PascalCase form) into the tokens,
+ * then validates the result so a fresh scaffold is guaranteed pack-conformant. */
+async function createModule(cwd: string, flags: Record<string, string>, positionals: string[]): Promise<void> {
+  const name = positionals[0];
+  if (!name || !/^[a-zA-Z][a-zA-Z0-9]*$/.test(name)) {
+    console.error('Usage: appwrap create-module <name> [--dir <parent>]\n  <name> must be a camelCase capability id (letters/digits, leading letter), e.g. `confetti`.');
+    process.exit(1);
+  }
+  if (!existsSync(MODULE_PACK_TEMPLATE_DIR)) {
+    console.error(`✖ module-pack template not found at ${MODULE_PACK_TEMPLATE_DIR}`);
+    process.exit(1);
+  }
+  const pascal = name.replace(/(^|[-_])(\w)/g, (_m, _s, c: string) => c.toUpperCase());
+  const dest = resolve(cwd, flags.dir ?? '.', name);
+  if (existsSync(dest)) {
+    console.error(`✖ ${dest} already exists — choose a different name or --dir.`);
+    process.exit(1);
+  }
+  // Copy the scaffold, then substitute the name tokens in every text file + rename the token'd native-src dir.
+  cpSync(MODULE_PACK_TEMPLATE_DIR, dest, { recursive: true });
+  const rename = (from: string, to: string) => { if (existsSync(from)) renameSync(from, to); };
+  rename(join(dest, 'native-src/__MODULE_NAME__'), join(dest, 'native-src', name));
+  const walk = (dir: string) => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (/\.(ts|md|json|swift|kt|xml)$/.test(e.name)) {
+        writeFileSync(p, readFileSync(p, 'utf8').replaceAll('__MODULE_NAME__', name).replaceAll('__MODULE_PASCAL__', pascal));
+      }
+    }
+  };
+  walk(dest);
+  const { validatePack } = await import('./testing');
+  const res = await validatePack(dest);
+  if (!res.ok) {
+    console.error(`✖ scaffolded pack failed validation (this is a bug in the template):\n  ${res.errors.join('\n  ')}`);
+    process.exit(1);
+  }
+  console.log(`✓ Created module pack '${name}' → ${dest}`);
+  console.log(`  Reference it from your appwrap.config.ts:`);
+  console.log(`    modulePacks: ['${flags.dir ? join(flags.dir, name) : `./${name}`}'],`);
+  console.log(`    modules: ['${name}', ...],`);
+}
+
+/**
+ * The CLI entry point — the bare `appwrap` bin calls `runCli()` with no options (identical to the
+ * historical `main`). A host (appwrap-ee) calls `runCli({ commands, platforms, modulePacks,
+ * templateRoots, desktopTemplateDir })` to compose extra capability on top of CE without forking it.
+ */
+export async function runCli(options: CliOptions = {}): Promise<void> {
+  cliOptions = { ...options };
+  if (options.desktopTemplateDir) DESKTOP_TEMPLATE_DIR = options.desktopTemplateDir;
+  // Host template overlays land AFTER the built-in runtime template → they win (file-level last-wins).
+  if (options.templateRoots?.length) TEMPLATE_ROOTS = [...TEMPLATE_ROOTS, ...options.templateRoots];
+
   const { command, flags, positionals } = parseArgs(process.argv.slice(2));
   const cwd = process.cwd();
 
+  // Host-provided commands are consulted first — they can add a new command or override a built-in.
+  if (command && cliOptions.commands?.[command]) { await cliOptions.commands[command](cwd, flags, positionals); return; }
+
   switch (command) {
     case 'init':
       await init(cwd, flags);
@@ -4251,6 +4580,9 @@ async function main(): Promise<void> {
     case 'sync':
       await sync(cwd, flags);
       break;
+    case 'create-module':
+      await createModule(cwd, flags, positionals);
+      break;
     case 'clean':
       await clean(cwd, flags);
       break;
@@ -4298,11 +4630,12 @@ async function main(): Promise<void> {
         '  build <ios|android> [--release] [--aab]   (store artifact only — no install/upload)\n' +
         '  logs <ios|android> [--once] [--native]    (stream WebView console; --native = full OS log)\n' +
         '  clean                                     (ns clean: wipe generated platforms/hooks/node_modules, restore deps — fixes stale/corrupt Podfile after a repo move)\n' +
+        '  create-module <name> [--dir <parent>]     (scaffold a new module pack — a swappable/extensible capability; see modulePacks)\n' +
         '  aliases: `release ios` = `publish ios`; `submit ios` = `publish ios prod`.');
       process.exit(command ? 1 : 0);
   }
 }
 
 if (import.meta.main) {
-  main();
+  runCli();
 }