akanjs 3.0.0-beta.2 → 3.0.0-beta.21

package/index.ts

@@ -4,10 +4,9 @@ import type { AkanImageConfig } from "akanjs/server";
 export const archs = ["amd64", "arm64"] as const;
 export type Arch = (typeof archs)[number];
 
-/** One image step. The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
+/** The object form runs only on the matching `TARGETARCH` leg of a multi-arch build. */
 export type DockerRun = string | { [key in Arch]?: string };
 
-/** The pieces Akan assembles a Dockerfile from. */
 export interface DockerImageConfig {
   image: string | { [key in Arch]?: string };
   /** Runs before `bun install`, so a system package a native dependency needs is there for the install. */
@@ -17,19 +16,12 @@ export interface DockerImageConfig {
   command: string[];
 }
 
-/**
- * A whole Dockerfile as a string, or the parts Akan assembles one from. The string form is taken verbatim —
- * nothing is merged into it, including the steps a lib contributes through its own `docker`.
- */
+/** The string form is taken verbatim: nothing is merged into it, not even a lib's `docker` steps. */
 export type DockerConfig = string | DockerImageConfig;
 
-/** What an `akan.config.ts` may write for `docker`: a whole Dockerfile, or any subset of the parts. */
 export type DockerOption = string | Partial<DockerImageConfig>;
 
-/**
- * A lib's contribution to the image of every app that mounts it — a lib never picks the base image or the
- * command, only the steps its own runtime needs.
- */
+/** Steps every app mounting the lib inherits; a lib never picks the base image or the command. */
 export interface LibDockerConfig {
   preRuns: DockerRun[];
   postRuns: DockerRun[];
@@ -47,39 +39,23 @@ export interface AkanRouteConfig {
   domains: AkanRouteDomains;
 }
 
-/**
- * Which web surfaces an app serves, resolved. `ssr` is the RSC/SSR route renderer and everything it needs —
- * the pages bundle, the client bundles, the RSC worker process. `csr` is the single-file SPA shell that the
- * Capacitor mobile build ships and that `/__csr` serves.
- */
+/** `ssr`: the RSC/SSR renderer with its bundles and RSC worker; `csr`: the SPA shell the native apps ship and `/__csr` serves. */
 export interface AkanWebConfig {
   ssr: boolean;
   csr: boolean;
 }
 
 /**
- * What an `akan.config.ts` may write. `false` is an API-only app — no web artifact is built and no web route
- * is mounted; `true` (the default) is both surfaces. The object form keeps SSR and toggles only the CSR
- * bundle, which is the whole range there is: the CSR bundle inlines the stylesheet the SSR build compiles, so
- * CSR without SSR would ship an unstyled app and is not expressible here.
+ * `false` is an API-only app, `true` (the default) both surfaces; the object form toggles only CSR, because the CSR
+ * bundle inlines the stylesheet the SSR build compiles.
  */
 export type AkanWebOption = boolean | { csr: boolean };
 
-/**
- * How `akan build` trims the `public/` tree it copies into `dist`. Source trees are never touched: an app's
- * and a lib's `public/` keep every file, and only the build's own copy is trimmed.
- */
+/** Trims only the build's own copy of `public/`; source trees keep every file. */
 export interface AkanAssetsConfig {
-  /**
-   * Drop font files from the build's `public/` that no built surface references. A font with `optimize` on is
-   * served from `/_akan/fonts` after subsetting, so its source is a build input the image never reads.
-   */
+  /** Drops fonts no built surface references; an `optimize` font is served subset from `/_akan/fonts`. */
   pruneFonts: boolean;
-  /**
-   * Font files to keep whatever the scan concludes, as globs relative to this app's or lib's own `public/`
-   * (`"fonts/Assistant-*.woff2"`). For the case a scan cannot see: a URL assembled at runtime. Declare it in
-   * the `akan.config.ts` that owns the font, so the reason travels with the lib rather than with the app.
-   */
+  /** Globs relative to the owning app's or lib's `public/`, for fonts a scan cannot see (a runtime-built URL). */
   keepFonts: string[];
 }
 
@@ -106,47 +82,61 @@ export interface AkanMobileTargetDeepLinks {
   };
 }
 
-export interface AkanMobileTargetFiles {
-  ios?: Record<string, string>;
-  android?: Record<string, string>;
-}
+/**
+ * Files copied into the app, keyed by where they land: `ios/<path>` (the app bundle), `android/res/<type>/<file>` or
+ * `android/assets/<path>`. The value is the source, relative to the app folder.
+ */
+export type AkanMobileTargetFiles = Record<string, string>;
 
-export interface AkanCapacitorLikeConfig {
-  plugins?: Record<string, unknown>;
-  android?: Record<string, unknown>;
-  ios?: Record<string, unknown>;
-  [key: string]: unknown;
+export type AkanNativeValue = string | number | boolean | AkanNativeValue[] | { [key: string]: AkanNativeValue };
+
+export interface AkanMobileNativeConfig {
+  /** Native runtime plugins beyond the ones the permissions bring, by builtin id (`"iap"`) or absolute folder. */
+  plugins?: string[];
+  ios?: {
+    infoPlist?: Record<string, AkanNativeValue>;
+    entitlements?: Record<string, AkanNativeValue>;
+  };
+  android?: {
+    /** XML at the `<manifest>` level; `${applicationId}` is replaced. */
+    manifest?: string[];
+    /** XML inside `<application>`. */
+    application?: string[];
+    /** XML inside the app's activity. */
+    activity?: string[];
+    /** The Firebase project's google-services.json, relative to the app folder, for FCM push on Android. */
+    googleServices?: string;
+  };
 }
 
-export interface AkanMobileTargetConfig extends AkanCapacitorLikeConfig {
+export interface AkanMobileTargetConfig {
   name: string;
   basePath?: string;
   indexPath?: string;
   appName: string;
   appId: string;
+  /** Executables, archives and the Swift module; letters, digits, `.`, `_` and `-`. Default: the app's folder name. */
+  fileName?: string;
   version: string;
   buildNum: number;
   assets?: AkanMobileTargetAssets;
   permissions?: MobilePermission[];
   deepLinks?: AkanMobileTargetDeepLinks;
   files?: AkanMobileTargetFiles;
+  native?: AkanMobileNativeConfig;
 }
 
-export interface AkanMobileConfig extends AkanCapacitorLikeConfig {
+export interface AkanMobileConfig {
   appName: string;
   appId: string;
+  fileName?: string;
   version: string;
   buildNum: number;
+  files?: AkanMobileTargetFiles;
+  native?: AkanMobileNativeConfig;
   targets: Record<string, AkanMobileTargetConfig>;
 }
 
-export interface PluginRuntimeContext {
-  readonly appName: string;
-  readonly mobile: AkanMobileConfig;
-  /** True when any mobile target declares the given permission. */
-  hasMobilePermission(permission: MobilePermission): boolean;
-}
-
 export interface AkanScanInfo {
   /** Transitive lib dependencies of the app (or direct deps of a lib). */
   getLibs(): string[];
@@ -174,49 +164,34 @@ export interface AkanExecutor {
 export interface AkanSyncContext {
   readonly appName: string;
   readonly appPath: string;
-  /** The full app/lib executor for advanced scan-result access and file operations. */
   readonly executor: AkanExecutor;
   getPath(rel: string): string;
   fileExists(rel: string): Promise<boolean>;
+  readFile(rel: string): Promise<string>;
   writeFile(rel: string, content: string, opts?: { overwrite?: boolean }): Promise<void>;
   /** Resolves `env/env.client.ts` and returns its exported `env`, or null when absent/invalid. */
   readEnvClient(): Promise<Record<string, unknown> | null>;
 }
 
-export interface AkanNativeContext {
-  readonly appPath: string;
-  /** The app executor for advanced scan-result access and file operations. */
-  readonly executor: AkanExecutor;
-  readonly target: AkanMobileTargetConfig;
-  readonly operation: "local" | "release";
-  readonly env: MobileEnv;
-  /** Set NS-prefixed usage descriptions in the iOS Info.plist (Debug + Release). */
-  setIosUsageDescriptions(descriptions: Record<string, string>): Promise<void>;
-  /** Merge raw key/values into the iOS Info.plist (Debug + Release). */
-  updateIosInfoPlist(values: Record<string, unknown>): Promise<void>;
-  /** Contribute entries to the iOS entitlements file (merged, then written once per prepare). */
-  addIosEntitlements(entitlements: Record<string, string | string[]>): void;
-  /** Transform `ios/App/App/AppDelegate.swift` in place (no-op when the file is absent). */
-  editIosAppDelegate(transform: (content: string) => string): Promise<void>;
-  /** Add `uses-permission` entries to the Android manifest (without the `android.permission.` prefix). */
-  addAndroidPermissions(permissions: string[]): void;
-  /** Add `uses-feature` entries to the Android manifest. */
-  addAndroidFeatures(features: string[]): void;
-}
-
-export interface AkanPluginCapacitorConfig {
-  /** Mobile permission that activates this plugin's native config (reuses the existing permission model). */
-  permission?: MobilePermission;
-  /** Imperative native (Capacitor) project configuration. */
-  configureNative?: (ctx: AkanNativeContext) => Promise<void>;
+/** What a plugin adds to a mobile app whose target asks for its permission; the native build merges every one. */
+export interface AkanPluginNativeConfig {
+  permission: MobilePermission;
+  /** Native runtime plugins, by builtin id (`"camera"`). */
+  plugins?: string[];
+  /** iOS usage texts by description name (`cameraUsageDescription`); `$(PRODUCT_NAME)` becomes the app name. */
+  usageDescriptions?: Record<string, string>;
+  infoPlist?: Record<string, AkanNativeValue>;
+  entitlements?: Record<string, AkanNativeValue>;
+  /** `uses-permission` names, without the `android.permission.` prefix. */
+  androidPermissions?: string[];
+  /** `uses-feature` names, declared as not required. */
+  androidFeatures?: string[];
 }
 
+/** Read live by the CLI at build time; it carries functions, so it stays out of the serializable config results. */
 export interface AkanPlugin {
   name: string;
-  /** Runtime npm packages this plugin needs; installed on demand by the CLI (e.g. firebase for push). */
-  runtimePackages?: (ctx: PluginRuntimeContext) => string[];
-  /** Native (Capacitor) project configuration. */
-  capacitor?: AkanPluginCapacitorConfig;
+  native?: AkanPluginNativeConfig;
   /** Build-time asset generation (e.g. `public/firebase-messaging-sw.js`). */
   syncAssets?: (ctx: AkanSyncContext) => Promise<void>;
 }
@@ -228,22 +203,28 @@ export interface AkanApiConfig {
   websocketPrefix: string;
 }
 
+export interface AkanDatabaseConfig {
+  /**
+   * The build carries each mode's drivers; a deployment picks one with `AKAN_DATABASE_MODE` (required when there are
+   * several), and `akan start` runs the first unless the shell names another.
+   */
+  modes: DatabaseMode[];
+}
+
 export interface AppConfigResult {
   docker: DockerConfig;
-  defaultDatabaseMode: DatabaseMode;
+  database: AkanDatabaseConfig;
   /**
-   * Where this app mounts its endpoints. Declared here rather than only in `main.ts` because the value is baked
-   * into every client bundle: a prebuilt CSR shell or a mobile bundle never reaches the server that would tell
-   * it otherwise. `new AkanApp({ prefix })` still overrides the server and every server-rendered page.
+   * Baked into every client bundle, since a prebuilt CSR shell or mobile bundle never asks the server;
+   * `new AkanApp({ prefix })` still overrides the server and every server-rendered page.
    */
   api: AkanApiConfig;
   /** Web surfaces built into the app and mounted at boot. Both default to `true`. */
   web: AkanWebConfig;
   routes?: AkanRouteConfig[];
   /**
-   * Mounts `libs/<lib>/page` into this app under `page/(libs)/(<lib>)` on sync. `true` takes every lib
-   * dependency that ships a `page` folder, an array takes exactly the libs listed, `false` (the default)
-   * syncs nothing and removes what a previous sync created.
+   * Mounts `libs/<lib>/page` under `page/(libs)/(<lib>)` on sync: `true` every lib dependency with a `page` folder, an
+   * array exactly those libs, `false` (the default) nothing, removing what a previous sync created.
    */
   syncPageLibs?: string[] | boolean;
   externalLibs: string[];
@@ -254,7 +235,6 @@ export interface AppConfigResult {
   publicEnv: string[];
   mobile: AkanMobileConfig;
   secrets: string[];
-  /** How the build trims the `public/` copy it ships. */
   assets: AkanAssetsConfig;
 }
 
@@ -292,25 +272,15 @@ export interface SubspaceDeclaration {
   repo: string;
   /** Apps this subspace serves. Libraries are never listed — they are derived from each app's closure. */
   apps: string[];
+  /** The subspace's own `AKAN_WORKSPACE_ID`, not this workspace's; only `akan subspace upload-env` reads it. */
+  workspaceId?: string;
 }
 
-/**
- * What `akan.subspace.ts` at a workspace root may write: the customer repos this workspace is mirrored
- * to. There is no branch field — the branch is whichever one the workspace is on, so one declaration
- * serves every release branch and each of them holds one akanjs version and one copy of the library
- * source.
- */
+/** `akan.subspace.ts`: the repos this workspace mirrors to, on whichever branch the workspace is on. */
 export interface SubspaceConfigInput {
-  /**
-   * Branches a push may target. A feature branch is refused, because pushing it would copy this
-   * workspace's branch namespace into every customer repo.
-   */
+  /** A feature branch is refused: pushing it would copy this workspace's branch namespace into every customer repo. */
   pushableBranches?: string[];
-  /**
-   * Workspace-root entries to keep out of every subspace, on top of the ones that always are. Top-level
-   * names or `dir/` prefixes — a workspace's own infra, release and benchmark trees are the usual
-   * entries.
-   */
+  /** Workspace-root names or `dir/` prefixes kept out of every subspace, on top of the ones that always are. */
   exclude?: string[];
   subspaces: SubspaceDeclaration[];
 }
@@ -334,10 +304,8 @@ export interface FileConventionScanResult {
 }
 
 /**
- * What a *live* scan exposes on `AppInfo.file` / `LibInfo.file`: a set per module kind, with every file
- * type carrying all four kinds. `FileConventionScanResult` above is the serialized form that crosses a
- * process boundary as JSON, which is why it is arrays and why each file type lists only the kinds it can
- * hold. The two are not interchangeable — every reader of `.file` calls `.has()`.
+ * The live form of `FileConventionScanResult` on `AppInfo.file`/`LibInfo.file` (every reader calls `.has()`); the
+ * arrays above are its JSON form, which lists only the kinds each file type can hold.
  */
 export interface FileConventionScanSet {
   all: Set<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akanjs",
-  "version": "3.0.0-beta.2",
+  "version": "3.0.0-beta.21",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -90,15 +90,10 @@
       "import": "./client/index.ts",
       "default": "./client/index.ts"
     },
-    "./client/capacitor": {
-      "types": "./types/client/capacitor.d.ts",
-      "import": "./client/capacitor.ts",
-      "default": "./client/capacitor.ts"
-    },
-    "./capacitor.base.config": {
-      "types": "./types/capacitor.base.config.d.ts",
-      "import": "./capacitor.base.config.ts",
-      "default": "./capacitor.base.config.ts"
+    "./client/native": {
+      "types": "./types/client/native.d.ts",
+      "import": "./client/native.ts",
+      "default": "./client/native.ts"
     },
     "./webkit": {
       "types": "./types/webkit/index.d.ts",
@@ -171,6 +166,11 @@
       "import": "./server/akanApp.ts",
       "default": "./server/akanApp.ts"
     },
+    "./server/tunnel": {
+      "types": "./types/server/tunnel/index.d.ts",
+      "import": "./server/tunnel/index.ts",
+      "default": "./server/tunnel/index.ts"
+    },
     "./server/memoryLimit": {
       "types": "./types/server/memoryLimit.d.ts",
       "import": "./server/memoryLimit.ts",
@@ -181,6 +181,16 @@
       "import": "./server/lifecycle/portInUse.ts",
       "default": "./server/lifecycle/portInUse.ts"
     },
+    "./server/artifact/routeSeedIndexStore": {
+      "types": "./types/server/artifact/routeSeedIndexStore.d.ts",
+      "import": "./server/artifact/routeSeedIndexStore.ts",
+      "default": "./server/artifact/routeSeedIndexStore.ts"
+    },
+    "./server/artifact/routesManifestStore": {
+      "types": "./types/server/artifact/routesManifestStore.d.ts",
+      "import": "./server/artifact/routesManifestStore.ts",
+      "default": "./server/artifact/routesManifestStore.ts"
+    },
     "./server/logging/logQuery": {
       "types": "./types/server/logging/logQuery.d.ts",
       "import": "./server/logging/logQuery.ts",
@@ -193,38 +203,22 @@
     }
   },
   "dependencies": {
+    "@lexical/plain-text": "^0.51.0",
+    "@noble/ciphers": "^2.4.0",
     "dayjs": "^1.11.20",
     "immer": "^11.1.8",
+    "lexical": "^0.51.0",
     "tailwind-merge": "^3.3.1",
     "tailwind-variants": "^3.3.0"
   },
   "peerDependencies": {
-    "@capacitor-community/contacts": "^7.2.0",
-    "@capacitor/android": "^8.3.4",
-    "@capacitor/app": "^8.1.0",
-    "@capacitor/assets": "^3.0.5",
-    "@capacitor/browser": "^8.0.3",
-    "@capacitor/camera": "^8.2.0",
-    "@capacitor/cli": "^8.3.4",
-    "@capacitor/core": "^8.3.4",
-    "@capacitor/device": "^8.0.2",
-    "@capacitor/geolocation": "^8.2.0",
-    "@capacitor/haptics": "^8.0.2",
-    "@capacitor/inappbrowser": "^4.0.1",
-    "@capacitor/ios": "^8.3.4",
-    "@capacitor/keyboard": "^8.0.3",
-    "@capacitor/preferences": "^8.0.1",
-    "@capacitor/push-notifications": "^8.1.1",
-    "@capgo/capacitor-updater": "^8.46.1",
     "@happy-dom/global-registrator": "^20.11.2",
     "@libsql/client": "^0.17.3",
     "@playwright/test": "^1.60.0",
     "@react-spring/web": "^10.1.0",
     "@use-gesture/react": "^10.3.1",
     "bullmq": "^5.76.10",
-    "capacitor-plugin-safe-area": "^5.0.0",
     "chance": "^1.1.13",
-    "cordova-plugin-purchase": "^13.16.0",
     "firebase": "^12.13.0",
     "happy-dom": "^20.11.2",
     "ioredis": "^5.10.1",
@@ -235,64 +229,12 @@
     "react-icons": "^5.6.0",
     "react-refresh": "^0.18.0",
     "react-server-dom-webpack": "^19.2.7",
-    "react-simple-pull-to-refresh": "^1.3.4",
     "react-spring": "^10.0.4",
     "scheduler": "^0.27.0",
     "tailwind-scrollbar": "^4.0.2",
     "typescript": "^6.0.3"
   },
   "peerDependenciesMeta": {
-    "@capacitor-community/contacts": {
-      "optional": true
-    },
-    "@capacitor/android": {
-      "optional": true
-    },
-    "@capacitor/app": {
-      "optional": true
-    },
-    "@capacitor/assets": {
-      "optional": true
-    },
-    "@capacitor/browser": {
-      "optional": true
-    },
-    "@capacitor/camera": {
-      "optional": true
-    },
-    "@capacitor/cli": {
-      "optional": true
-    },
-    "@capacitor/core": {
-      "optional": true
-    },
-    "@capacitor/device": {
-      "optional": true
-    },
-    "@capacitor/geolocation": {
-      "optional": true
-    },
-    "@capacitor/haptics": {
-      "optional": true
-    },
-    "@capacitor/inappbrowser": {
-      "optional": true
-    },
-    "@capacitor/ios": {
-      "optional": true
-    },
-    "@capacitor/keyboard": {
-      "optional": true
-    },
-    "@capacitor/preferences": {
-      "optional": true
-    },
-    "@capacitor/push-notifications": {
-      "optional": true
-    },
-    "@capgo/capacitor-updater": {
-      "optional": true
-    },
     "@happy-dom/global-registrator": {
       "optional": true
     },
@@ -311,15 +253,9 @@
     "bullmq": {
       "optional": true
     },
-    "capacitor-plugin-safe-area": {
-      "optional": true
-    },
     "chance": {
       "optional": true
     },
-    "cordova-plugin-purchase": {
-      "optional": true
-    },
     "firebase": {
       "optional": true
     },
@@ -350,9 +286,6 @@
     "react-server-dom-webpack": {
       "optional": true
     },
-    "react-simple-pull-to-refresh": {
-      "optional": true
-    },
     "react-spring": {
       "optional": true
     },
@@ -368,7 +301,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.12",
-    "@types/bun": "^1.4.0"
+    "@types/bun": "^1.4.2"
   },
   "bun": {
     "platform": "bun"