@akanjs/cli 3.0.0-beta.27 → 3.0.0-beta.29

package/guidelines/conventions/conventions.instruction.md

@@ -28,7 +28,7 @@ you fetch on demand — `get_guideline` with the name, or `akan guideline show <
 | name | covers |
 |---|---|
 | `ssrRule` | server-share targets, the `akan.ssr.*` warnings, the client-boundary playbook |
-| `runtimeRule` | `web` / `csr` surfaces, gateway vs solo processes, logging, the generated image, shipped assets, database modes |
+| `runtimeRule` | `web` / `csr` surfaces, gateway vs solo processes, logging, the generated image, a desktop app's server, shipped assets, database modes |
 | `queryRule` | slices and hydration, the generated filter methods, full-text search, cascade removal |
 | `transportRule` | guards across HTTP and websocket, socket identity and cleanup, binary pubsub, mutation verbs |
 | `mcpRule` | MCP configuration, wire behaviour, resource URIs, OAuth metadata, protocol revisions |
@@ -57,8 +57,9 @@ back.
   `no-inline-color`, `no-interpolated-arbitrary-class`)
 - **Never `throw new Error`.** Throw `new Err("<module>.error.<key>")` and register the key as `[en, ko]` in that
   module's dictionary `.error({})`. Import `Err` from `"../dict"` on the server and from `"@libs/<lib>/client"` or
-  `"@apps/<app>/client"` in UI. `no-throw-raw-error.grit` exempts tests, `*.constant.ts`, `common/**`, and `env/**`
-  — the last two have no legal `Err` import path, so keep throwing code out of them.
+  `"@apps/<app>/client"` in UI. `no-throw-raw-error.grit` exempts tests, `*.constant.ts`, `common/**`, `env/**`, and
+  a root `native/` folder — `common/` and `env/` have no legal `Err` import path, so keep throwing code out of them,
+  and a native plugin throws `AkanNativeError`, the error its bridge carries back to the page.
 - **Never import a third-party package** from `page/**`, from any barrel, or from any
   `*.{constant,dictionary,document,service,signal,store}.ts` / `*.{Template,Unit,Util,View,Zone}.tsx`
   (`no-import-external-library.grit`). Re-export the symbol through a lib first. One-line re-export shims in a lib's
@@ -87,7 +88,8 @@ back.
   `Notification.requestPermission` / `.permission` (no app page has them), `navigator.geolocation` (use
   `useGeoLocation` from `akanjs/webkit`) and `navigator.vibrate` (iOS has none; use `haptics`). They are legal on the
   web, so the rule does not ban them: it keeps them in a `webkit/` hook that branches on `isNativeApp()` from
-  `akanjs/client/native`, which is where the app side goes too.
+  `akanjs/client/native`, which is where the app side goes too. A root `native/` folder is out of its scope: a
+  plugin's web part is where those APIs belong.
 - **Never return a value from a store action** (`no-return-in-store-action.grit`). Every method of a `store(...)`
   class dispatches through `st.do.<action>()`, typed `void` / `Promise<void>`, so the value is unreachable — write
   it into state with `this.set({ ... })`. A bare `return;` guard, a `return` inside a nested callback, a getter,
@@ -348,6 +350,15 @@ Full contract: `get_guideline` with `runtimeRule`, or `akan guideline show runti
   assembles one from; the string form takes no contributions. The generated image installs `ca-certificates` and
   `tzdata` and nothing else, so an app needing `ffmpeg` or Chromium declares it in `preRuns` / `postRuns`. A lib
   declares the steps its own runtime needs and every mounting app inherits them.
+- **A desktop app's server (`native.desktop.server: true` on its target) gets nothing from `docker`.** An executable the app spawns
+  goes in `bin` — per platform, a download checked against its `sha256` or a file beside the config, put first on
+  the app's PATH so the server's `spawn("ffmpeg")` finds it, and in `ctx.binDir` for a native plugin — and a package
+  that builds itself at install goes in `trustedDependencies`, which the image honours too. Carry a static LGPL ffmpeg: a `--enable-nonfree` build may
+  not be redistributed. A file the user picks with `filePicker.pickFiles({ forServer: true })` reaches it as a
+  grant, never a copy or a path: `NativeFile.resolve(grant, "read")` in `akanjs/server` asks the shell for it.
+  What it carries is readable on the user's computer — `private/` (each lib's too, under `private/libs/<lib>`), the
+  one `env.server.<env>.ts` of its `--env` and its libs' server env defaults (`env.server.testing.ts`) — and it has
+  no `public/`: read runtime files from `AKAN_APP_DIR`, never `process.cwd()`.
 - **`assets: { pruneFonts, keepFonts }`** trims from the `dist` copy of `public/` the fonts nothing reads; source
   trees are never touched. A font with `optimize` on is a build input, not a runtime asset. `keepFonts` belongs to
   the `akan.config.ts` that owns the font, written against that scope's own `public/`.
@@ -872,6 +883,12 @@ shape, so `cascade` never means "related" — it means one of exactly these:
   `.layoutStyle()` on the root layout; `.prompt()` on a page. A named export beside the chain, or `page()` in a
   `_layout.tsx`, fails the build. `.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function of the
   route's args returning it; there is no metadata object, and analytics is the app's own script, not a stage.
+- **A CSR bundle (a native app, `?csr=true`) never shows a root layout's own markup.** Pages render into the
+  frame, and what the root layout draws around `{children}` stays in a hidden container, so its wrappers cannot
+  stack a second screen beside the frame. Its components still mount and their effects run (`<Auth.User />` works).
+  Anything a person must see from a root layout — an overlay, a gate, a banner — renders through
+  `createPortal(…, document.body)`, as `<Agent.Chat />` and the dialogs already do. A non-root `_layout.tsx` has no
+  such limit.
 - **A page names every `[x]` segment of its path with `.param("x", Type)`** and reads a query key only through
   `.search("k", Type)`. Values arrive typed — `ID`/`String` → string, `Int`/`Float` → number, `Boolean`, `Date` →
   Dayjs, an `enumOf` class → its union, `[T]` → array — a path value the type refuses answers not-found, and a
@@ -915,9 +932,9 @@ export default page()
 ## Akan Sync Conventions (`apps/**`, `libs/**`)
 
 - `apps/<appName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`.
-- `apps/<appName>` root may only contain these folders: `.akan`, `common`, `env`, `lib`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
+- `apps/<appName>` root may only contain these folders: `.akan`, `common`, `env`, `lib`, `native`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`.
 - `libs/<libName>` root may only contain these files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `akan.config.ts`, `akan.lib.json`, `client.ts`, `index.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.spec.json`, `tsconfig.tsbuildinfo`.
-- `libs/<libName>` root may only contain these folders: `common`, `env`, `lib`, `page`, `plugin`, `private`, `public`, `srvkit`, `ui`, `webkit`. A library is never booted or packaged as an app, so the run and mobile entries an app carries (`main.ts`, `.akan`, `script`, `secrets`) are rejected there. A Capacitor-era `ios` / `android` / `mobile` folder or `capacitor.config.*` is refused in an app root too, named as a leftover: the native runtime generates its projects under `.akan/mobile/<target>`.
+- `libs/<libName>` root may only contain these folders: `common`, `env`, `lib`, `native`, `page`, `plugin`, `private`, `public`, `srvkit`, `ui`, `webkit`. A library is never booted or packaged as an app, so the run and mobile entries an app carries (`main.ts`, `.akan`, `script`, `secrets`) are rejected there. A Capacitor-era `ios` / `android` / `mobile` folder or `capacitor.config.*` is refused in an app root too, named as a leftover: the native runtime generates its projects under `.akan/mobile/<target>`.
 - Both allowlists have one source — `pkgs/@akanjs/devkit/workspaceLayout.ts`. `akan sync` (error), `akan doctor`
   (diagnostic), and `akan quality scan` (warning) all read it, so add a new root entry there and mirror it into this
   list, never into one of the three call sites.
@@ -941,12 +958,15 @@ export default page()
 | Folder | Admission test | Naming |
 |---|---|---|
 | `common/` | pure, isomorphic, zero-dependency; may import only sibling `common/*` and `akanjs/base`. Cannot import `Err`, so keep throwing code out of it. | camelCase file, filename equals the single export |
-| `webkit/` | touches `window` / `navigator` / the native bridge (`akanjs/client/native`), or is a React hook | `use<Thing>.tsx` — `.tsx` even with no JSX |
+| `webkit/` | touches `window` / `navigator` / the native bridge (`akanjs/client/native`, or `akanjs/client/native/<plugin id>` for any builtin plugin), or is a React hook | `use<Thing>.tsx` — `.tsx` even with no JSX |
 | `srvkit/` | touches `node:*`, `Bun`, `process.env`, a secret, or a server SDK | camelCase file, PascalCase class |
 | `ui/` | renders JSX, or defines a look (a recipe in `Recipe/`, a lib's `tokens.css`), and is not bound to one model | PascalCase component, camelCase sidecar (`swipeCard.util.ts`), `Recipe/<name>.ts` |
 | `plugin/` | build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
+| `native/` | a native plugin the app or lib owns: `native-plugin.json` beside its page API (`src/index.ts`, `definePlugin` from `akanjs/client/native`), its desktop part (`src/desktop.ts`, `defineDesktopPlugin` from `akanjs/native/desktop`), Kotlin and Swift. Every mobile and desktop target ships it; a lib's reach only the apps that depend on it, and the app's own wins an id | `native/<id>/`, the folder named after the plugin id |
 
 - Hooks return a named object of async closures, never a tuple.
+- A `native/` plugin's page API is imported by a `webkit/` hook (`../native/<id>/src`) and nothing else; pages and
+  components call the hook, the same way they reach `akanjs/client/native`.
 - `ui/` is the presentation layer — markup and the looks it is built from — so a recipe lives there although it is
   neither a component nor a hook. Not `webkit/`: its hooks are `"use client"`, the opposite signal for a function
   server components call. Not `common/`: it cannot import `akanjs/ui`, where `recipe` / `tv` come from.

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -1,4 +1,4 @@
-# Runtime Rule — Serving, Processes, Logging, Image, Assets
+# Runtime Rule — Serving, Processes, Logging, Image, Desktop Server, Assets
 
 How an Akan app is built, what it serves, how many processes it runs, where its logs go, and what ends up in
 its image. Everything here is declared in `akan.config.ts` or narrowed by an env at boot; none of it is reached
@@ -184,6 +184,121 @@ const config: AppConfig = { docker: "FROM oven/bun:1-slim\n…" }; // verbatim,
 - `AkanAppConfig.docker` is the resolved declaration; `AkanAppConfig.dockerfile` is the text `akan build` writes
   to `dist/apps/<app>/Dockerfile`.
 
+## A Desktop App's Server — `bin` And `trustedDependencies`
+
+A mobile target that declares `native: { desktop: { server: true } }` carries the app's server: `akan build-desktop`,
+`start-desktop --release` and `publish-update` put the backend `akan build` made into the app — everything the
+backend build wrote (the `.js`, `akan.build.json`, `private/`, a bundled package's `.node`, `.wasm` or file asset)
+but the Dockerfile, the RSC worker, the console, `csr/` and `public/` — and install its packages first with
+`bun install --production --prefer-offline`, before `akan build` runs. `start-desktop` without `--release` starts
+`akan start` beside the app when no dev server of this checkout answers. The setting is the app's backend,
+so it does not change under an installed app: an update whose release carries a server when the app has none, or
+none when it has one, is refused, and switching means a reinstall.
+A desktop app builds only for the computer it is built on, so every native addon's prebuild matches the one it runs
+on. It runs as an API-only edge server on SQLite, on a loopback port the launcher picks — the last session's when
+it is free, which is not a guarantee, so a provider that needs an exact redirect URI signs in through a cloud
+server's adapter. It refuses a `Host` other than its own, but any program on the computer can still call that port:
+guard its endpoints as a network server's. It runs in one process, so a `main.ts` or an env asking for replicas (`replica`,
+`solo: false`, `AKAN_SOLO=false`, `AKAN_REPLICA`, `AKAN_COMMAND_TYPE=start`) does not boot in the app. Its data lives in the app's local data folder (`%LOCALAPPDATA%\<id>\server`
+on Windows, never Roaming; `server-debug` for a `--debug` build). It trusts the OS certificate store, and of the
+user's environment it takes a fixed set and nothing else: the system's own (`PATH`, `HOME`, the temp folder, `LANG`,
+`TZ`, Windows' folders and `ComSpec`), the desktop session a `bin` tool needs for the screen or the audio server
+(`DISPLAY`, `XAUTHORITY`, `WAYLAND_DISPLAY`, the session bus, `PULSE_*`, `XDG_*`), and the proxy and CA variables
+(`HTTP(S)_PROXY`, `NO_PROXY`, `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`).
+
+**Everything it carries is on the user's computer, readable.** That is `private/` as it is — each lib's too, under
+`private/libs/<lib>` — and the server env of the one environment the build is for (`--env`: `debug` for
+`build-desktop`, `local` for `start-desktop --release`, `main` for `publish-update`, unless named): the build keeps
+`env/env.server.<env>.ts` and swaps every other environment's file for exports that refuse to be read. The server env
+each lib exports as its defaults (the lib's `env.server.testing.ts`, spread into every environment by
+`env.server.type.ts`) ships as well. Keep a key in those files only if every user of the app may hold it; a secret the
+server needs belongs to a cloud server its adapter calls. There is no `public/`: a file the server reads at runtime
+goes in `private/` and is read from `AKAN_APP_DIR` (the folder `server.js` sits in), never from `process.cwd()`, which
+is the app's data folder.
+
+**Nothing from `docker` reaches it.** `preRuns`, `postRuns` and a whole Dockerfile install into a Linux image the
+desktop app never runs in, and the build warns when an app has them and carries no `bin`. What the server needs
+from them comes one of two ways:
+
+```ts
+const config: AppConfig = {
+  trustedDependencies: ["rclnodejs"],
+  bin: {
+    ffmpeg: {
+      "darwin-arm64": {
+        url: "https://files.example.com/ffmpeg-7.1-lgpl-darwin-arm64.zip",
+        sha256: "…",
+        file: "ffmpeg-7.1/bin/ffmpeg",
+      },
+      "win32-x64": { url: "https://files.example.com/ffmpeg-7.1-lgpl-win64.zip", sha256: "…", file: "bin/ffmpeg.exe" },
+      "linux-x64": { path: "tools/linux-x64/ffmpeg" },
+    },
+  },
+};
+```
+
+- **An executable the desktop app spawns goes in `bin`** — its server's code or its native plugins, whether or not
+  it carries a server — keyed by the name the code spawns and then by
+  `${process.platform}-${process.arch}` (`darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`, `win32-arm64`,
+  `win32-x64`). A source is `{ url, sha256, file? }` — downloaded when the app is built, refused unless it hashes
+  to `sha256` (so plain http is as safe as https), kept in `apps/<app>/.akan/cache/bin/<sha256>` — or
+  `{ path, file? }`, relative to the `akan.config.ts` that declares it. `file` is the executable inside an archive
+  (`.zip`, `.tar.gz`, `.tgz`, `.tar.xz`, `.tar.bz2`, `.tar`), unpacked with the OS's own `tar` (`unzip` for a zip
+  on Linux).
+- Only the building computer's platform is fetched, and an entry without it fails the build instead of the user's
+  call. `build-desktop` and `start-desktop` copy the file into the app's `bin/` (keeping `.exe` on Windows), sign it
+  with the app on macOS, and put that folder first on the app's PATH. The server's `spawn("ffmpeg")` needs no change
+  and finds the carried file even in an app launched from the Finder, whose PATH is only
+  `/usr/bin:/bin:/usr/sbin:/sbin`. A native plugin finds the folder in `ctx.binDir`: Bun's own `spawn` and `which`
+  without `env` read the environment the app started with, so a plugin passes `env: process.env` to run one by name.
+  The server passes it too when it spawns a carried `bun build --compile` executable: the shell starts the server as
+  Bun with `BUN_BE_BUN=1`, which akanjs takes out of `process.env` at boot, and a child spawned without `env` still
+  inherits it and runs as Bun's own CLI instead of the tool.
+- **One file per entry, so carry a static build.** A build that loads its own shared libraries — a `-shared`
+  archive, or Homebrew's ffmpeg with its 55 dylibs — runs on the computer that built it and nowhere else.
+- **A lib's `bin` reaches only the apps that depend on it**, unlike its `docker` steps; the app's own entry of the
+  same name wins, and two libs that declare one name differently fail the build.
+- **The image does not read `bin`.** Keep installing through `docker.preRuns` there.
+- **A package that builds itself at install goes in `trustedDependencies`.** `bun install --production` runs no
+  dependency's install or postinstall script unless the package is trusted, so an addon with no prebuild arrives
+  unbuilt and fails at its first call. The list lands in the built `package.json`, so it applies to the image and to
+  the desktop server alike, and a lib's list reaches every app, like its `externalLibs`.
+
+**Carry an LGPL ffmpeg.** A build configured with `--enable-nonfree` may not be redistributed at all — the macOS
+binary npm's `ffmpeg-static` downloads is one — and a `--enable-gpl` build obliges you to offer its source. An LGPL
+build has no `libx264`, so encode H.264 through the OS's encoder: `h264_videotoolbox` on macOS, `h264_mf` on
+Windows, VAAPI or NVENC on Linux. Codec patents are a separate question to settle before shipping.
+
+**A server bound to its machine stays a service.** A server that needs a whole environment — ROS, system services,
+root to change the network or the clock — runs as a service on that machine (the image), and the desktop app's
+target leaves `desktop.server` off, pinned to it with `AKAN_PUBLIC_SERVER_URL` at build time. A carried server runs
+as the signed-in user and stops with the app, and so does what it started. On macOS and Linux the server leads its
+own process group: quitting the app ends the group, and when the app was killed or crashed — even while the server
+was still starting — the server sees its parent gone and ends the group itself, SIGTERM first and SIGKILL a second
+later for whatever ignored it. On Windows the job object ends them all with the app. A process started `detached`
+leaves the group, or the job, and keeps running.
+
+**A file the user picks reaches the server as a grant, never as a copy or a path.** With `native.plugins:
+["file-picker"]` on the target, `filePicker.pickFiles({ forServer: true })` (also `pickDirectory` and `saveFile`,
+from `akanjs/client/native`) copies nothing, whatever the size: its FileRefs serve the originals for a preview, and
+each result carries a `grant`. The page hands the grant to an endpoint, and the server exchanges it:
+
+```ts
+const input = await NativeFile.resolve(grant, "read"); // "write" for a saveFile grant, "folder" for pickDirectory
+const clip = await NativeFile.resolveIn(folderGrant, "day1/a.mp4"); // refused if it climbs out of the folder
+```
+
+The carried server asks the shell that showed the dialog over its IPC channel, so it reaches what the user picked
+and nothing else, and no page ever holds a path. Behind a dev build `akan start` checks the grant's signature
+against a key in `~/.akan/native` instead, in `operationMode` local only; every other server refuses a grant.
+
+**Devices belong to the shell, not the server.** Displays and their changes (`screen`), windows placed on them
+(`window`), the system volume and mute (`volume`), global shortcuts, keep-awake and launch at login are native
+runtime plugins, each added to the target's `native.plugins`. Every builtin plugin's page API is
+`akanjs/client/native/<id>` (`akanjs/client/native/window`, `…/screen`, `…/global-shortcut`), imported in a `webkit/`
+hook; `volume` and `filePicker` also come from `akanjs/client/native` itself. A capability the shell
+lacks is added there: an app's own plugin runs as Bun code in the plugin host and cannot add a native shell op.
+
 ## Database Modes — `database` In `akan.config.ts`
 
 | mode | database | cache · queue · pubsub | runs as |

package/incrementalBuilder.proc.js

@@ -8,7 +8,7 @@ import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-0n9q1f23.js";
+} from "./index-r8gp8zk3.js";
 import"./index-52w0fvh8.js";
 import {
   GraphClientEntryDiscovery,
@@ -20,7 +20,7 @@ import {
   DevChangePlanner,
   DevGeneratedIndexSync,
   SsrDevBundler
-} from "./index-5kjsr2pg.js";
+} from "./index-ttn00pr3.js";
 import {
   prepareDevWatchBatch
 } from "./index-a5vmm6x4.js";

package/{index-hzy4pe24.js → index-0pqzrbpr.js}

@@ -8,7 +8,7 @@ import {
   isScannedRootEntry,
   AppExecutor,
   LibExecutor
-} from "./index-0n9q1f23.js";
+} from "./index-r8gp8zk3.js";
 import {
   FileSys2
 } from "./index-52w0fvh8.js";
@@ -21,7 +21,7 @@ import {
   workflowPathsForPlan,
   workflowRunArtifactPath,
   workflowSyncDir
-} from "./index-d65fzxvd.js";
+} from "./index-2s2e5qnd.js";
 
 // pkgs/@akanjs/devkit/akanContext.ts
 import { readdir } from "fs/promises";

package/{index-w5pet0nq.js → index-16k7m3cs.js}

@@ -1,13 +1,13 @@
 // @bun
 import {
   AppExecutor
-} from "./index-0n9q1f23.js";
+} from "./index-r8gp8zk3.js";
 import {
   jsonText,
   createWorkflowBaselineSummary,
   buildAkanModuleContextIndex,
   toolingRolloutGate
-} from "./index-d65fzxvd.js";
+} from "./index-2s2e5qnd.js";
 import {
   buildResourceList,
   codexMcpConfigPath,
@@ -17,24 +17,25 @@ import {
   upsertCodexMcpServerBlock,
   renderDoctorText,
   AkanContextAnalyzer
-} from "./index-hzy4pe24.js";
+} from "./index-0pqzrbpr.js";
 import {
   runner
-} from "./index-58cyna2s.js";
+} from "./index-b68zfsvz.js";
 import {
   getMobileTargets,
+  appIdsOf,
   NativeApp,
   isPlaceholderAppId
-} from "./index-y736f42m.js";
+} from "./index-1hs6jrys.js";
 import {
   Prompter2
 } from "./index-zzvvc845.js";
 import {
   RepairRunner
-} from "./index-t02g6dpn.js";
+} from "./index-2z30v4k5.js";
 import {
   WorkflowRunner
-} from "./index-da72pfdv.js";
+} from "./index-h9ed99ax.js";
 
 // pkgs/@akanjs/devkit/akanMcpContract.ts
 import path from "path";
@@ -606,13 +607,14 @@ class ContextRunner2 extends runner("context") {
           });
       }
       for (const { name, config: target } of await getMobileTargets(app)) {
-        if (!isPlaceholderAppId(target.appId))
+        const placeholder = appIdsOf(target.appId).find(isPlaceholderAppId);
+        if (!placeholder)
           continue;
         diagnostics.push({
           severity: "warning",
           code: "mobile-appid-placeholder",
           path: `apps/${appName}/akan.config.ts`,
-          message: `Mobile target '${name}' uses placeholder bundle id '${target.appId}'. Apple's developer portal almost always already claims it, so signing to a physical device fails with "cannot be registered to your development team". Set a unique mobile.appId (reverse-DNS of your org).`
+          message: `Mobile target '${name}' uses placeholder bundle id '${placeholder}'. Apple's developer portal almost always already claims it, so signing to a physical device fails with "cannot be registered to your development team". Set a unique mobile.appId (reverse-DNS of your org).`
         });
       }
     }