@akanjs/cli 3.1.0-rc.0 → 3.1.0-rc.2

package/guidelines/runtimeRule/runtimeRule.instruction.md

@@ -257,9 +257,10 @@ const config: AppConfig = {
   Intel Macs are not a target, so `--arch x64` on macOS is refused.
 - **A release is signed only with `--sign` and notarized only with `--notarize`** (`build-desktop`,
   `publish-update`); the environment names the identity and never decides to use it, so a shell exporting a Developer
-  ID signs and uploads nothing unasked. Before either, the server the app carries is searched for every secret value
-  of the workspace's server env files and refused with the paths, and one line names the identity and the service
-  the app goes to.
+  ID signs and uploads nothing unasked. Every release build and every `publish-update` of a target that carries a
+  server, signed or not, first searches that server for every secret value of the workspace's server env files and
+  refuses with the paths; an env file it cannot evaluate stops the release too, and a debug build is not searched.
+  One line then names the identity and the service the app goes to.
 - **A macOS release for download is signed with a Developer ID and notarized.**
   `AKAN_NATIVE_MACOS_IDENTITY` names a keychain identity, or `AKAN_NATIVE_MACOS_CERTIFICATE` +
   `_CERTIFICATE_PASSWORD` a `.p12` the build imports into a keychain of its own (a CI runner);
@@ -280,12 +281,15 @@ const config: AppConfig = {
   key. List the online signing key first and offline spares after it (up to three): a phone binary trusts all of
   them, and a key may revoke only the keys listed before it, so a leaked key cannot lock out its spares. A desktop
   app trusts the first; `publicKey` is the one-key form. `akan publish-update <app>` builds and signs a release
-  into `updates/`: upload that folder to `url`, the manifests last, or let `--upload s3://<bucket>/<prefix>` do it
-  (credentials and endpoint from `S3_*` or `AWS_*`; a release file the bucket holds is skipped). A phone reads only
-  `<url>/<platform>/<channel>/<nativeApi>.json`, so each store generation on a channel takes its own fixes.
+  into `updates/`: upload that release's files to `url` and its manifest last, or let
+  `--upload s3://<bucket>/<prefix>` do it (credentials and endpoint from `S3_*` or `AWS_*`; a release file the bucket
+  holds is skipped), which sends that release alone, and nothing when it is missing or fails a check. Never upload the
+  folder whole: a phone's is also where `pack-update` writes by default.
+  A phone reads only `<url>/<platform>/<channel>/<nativeApi>.json`, so each store generation on a channel takes its
+  own fixes.
   `akan pack-update` writes an unsigned phone bundle for whoever holds the key to sign and records it in
   `<out>/pack.json`, exiting 2 when `--against` says it needs a new store build; `akan push-update` packs and uploads to
-  an akasys project that holds the key, and `akan register-binary` registers a store build after `release-*`. A
+  the Akan Cloud project that holds the key, and `akan register-binary` registers a store build after `release-*`. A
   release that hangs is rolled back while the app runs, and `report: { url }` has a phone post what became of each
   release (applied, confirmed, rolled back and why) at its next launch, so rollback rates are visible. `devtools: true`
   opens the web inspector of a release build for an internal test target. The channel is the backend env the binary was built for unless `channel` names one;
@@ -307,10 +311,11 @@ const config: AppConfig = {
   their page paints, so a dark board never flashes white, and `desktop.publisher` names who publishes a Windows app in
   Apps & features and its executable's company (the app name when unset, never Bun's own).
 - **A third-party page shown first-party** — a scoreboard, a menu board — is the `external-view` plugin, listed in
-  `native.plugins`: a webview over the window with a browser profile of its own, held to the origins it was opened
-  for, with an init script, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is
-  rebuilt, by itself) / `consoleMessage` events. Every method on Windows; macOS 14+ lacks `sendKey`, `setMuted` and
-  `capture`.
+  `native.plugins`: a webview over the window with a browser profile of its own, its top level held to the origins it
+  was opened for while its frames load web content from anywhere, with an init script that runs in the top document
+  only, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is rebuilt, by itself;
+  the reason is `terminated` on macOS, and `rebuildFailed` when a rebuild failed and the view is closed, to be opened
+  again) / `consoleMessage` events. Every method on Windows; macOS 14+ lacks `sendKey`, `setMuted` and `capture`.
 
 ## A Desktop App's Server — `bin` And `trustedDependencies`
 
@@ -416,10 +421,14 @@ in those alone, and `modules: ["@edge"]` (or `AKAN_MODULES=@edge`) names every m
 inject, cascade to and hold a relation to. `desktop: { server: { profile: "edge", modules: ["@edge"] } }` builds the
 carried server that way: `env/env.server.<env>.edge.ts` is bundled in place of `env/env.server.<env>.ts`, which never
 enters it, and the build evaluates the profile file with no app env and refuses one whose secret-named keys hold a
-value — a `process.env.X ?? "literal"` counts as the literal. Each lib's env defaults (`env.server.testing.ts`) are
+value — a `process.env.X ?? "literal"` counts as the literal. Signing, encryption, master and session keys, `pwd`, a
+`…dsn` and a connection string are secret-named, and a URL holding a password or a secret-named query parameter is a
+secret under any key. The profile may spread `libEnv`, and the lib defaults it reaches are checked as the bundle
+carries them; a profile that imports the file it replaces is refused. Each lib's env defaults (`env.server.testing.ts`) are
 swapped the same way: for the lib's `env/env.server.testing.edge.ts`, held to the same check, or for the defaults with
-every secret-named value left out, which the build names in a warning. `akan build <app> --profile edge` does the
-same for an image. A module listing only edge does not mount under `akan start` (local): list `local` too to develop
+every secret-named value left out, which the build names in a warning — and a default a JSON snapshot cannot carry (a
+function, Map, Set, Date, class instance, bigint or non-finite number) is refused unless the lib has its profile file.
+`akan build <app> --profile edge` does the same for an image. A module listing only edge does not mount under `akan start` (local): list `local` too to develop
 it there.
 
 **A file the user picks reaches the server as a grant, never as a copy or a path.** With `"file-picker"` in
@@ -556,7 +565,7 @@ const config: AppConfig = { assets: { pruneFonts: false } }; // emergency valve,
 
 Akan Cloud builds and deploys each app as `build` → `docker` → `deploy`, and `ota` after them when asked. **An app's own stages go in
 `apps/<app>/akan.config.ts` under `pipeline`; stages around every app go in the workspace root's
-`akan.config.ts`**, typed `WorkspaceConfig` (`before`, `after`, `post`, `env`, `timeout`). Both are `import type`
+`akan.config.ts`**, typed `WorkspaceConfig`, under its own `pipeline` (`before`, `after`, `post`, `env`, `timeout`). Both are `import type`
 objects (or `(ctx) => …`), and `akan pipeline dry-run | validate | plan` turns them into the plan Akan Cloud runs —
 locally, running nothing.
 

package/guidelines/transportRule/transportRule.instruction.md

@@ -47,14 +47,17 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   change revokes it, `disconnect` when the socket closes while still subscribed — so a room already left runs
   neither again, and cleanup that must happen either way registers for both. From a `message` handler it belongs to
   the socket and runs at close. A handler that throws is logged and never blocks the rest of the teardown.
+- **A subscribe the client leaves before it finishes joins nothing.** When an `unsubscribe` for the room, or the
+  socket's close, arrives while the subscribe is still running, the subscribe answers `subscribe: false` and runs its
+  `unsubscribe` cleanup (and its `disconnect` one when the socket closed) instead of joining the room.
 
 ## Request Deadlines
 
 - **`{ timeout: <ms> }` in an endpoint's signal option is the whole configuration surface**, and it reaches both
   ends of the call. Server side, the `Timeout` middleware races the handler against it and answers
   `base.error.gatewayTimeout` (504) once it is spent. Client side, `FetchSerializer` ships the value on the
-  serialized endpoint and `fetch.<endpoint>()` uses it as that request's `AbortSignal.timeout` budget, so the
-  browser does not abandon a call the server is still allowed to be working on.
+  serialized endpoint and `fetch.<endpoint>()` uses it as that call's deadline — every retry of the call and every
+  wait between them included — so the browser does not abandon a call the server is still allowed to be working on.
 - **The middleware is registered by default and has no default of its own.** An endpoint that declares no
   `timeout` is passed straight through — a default here would put a deadline on every endpoint in the app that
   nobody asked for, which is why the middleware used to be opt-in and, being opt-in, made the declared value
@@ -92,6 +95,11 @@ mutation is mounted under. `conventions` carries the invariants — this is the
 - **The entry is the handler's result, not the response.** The lookup wraps the handler only, so `resolveReturn`
   still runs per call on the cached value — field masking, `hidden`/`secret` stripping and relation resolution are
   never cached, and a relation still costs its own load. The cache saves the handler, not the serialization.
+- **A hit hands `resolveReturn` an instance of the declared return model**, rebuilt from an entry that keeps its
+  `Map`s, bytes and dates, so a `resolveField` reads the same methods and `Dayjs` values on a hit as on a miss. It is
+  the declared model, not the service's document: a method only the document has is not there on a hit, and a return
+  declared as a `Light` model shows `resolveField` its light fields only. The entry still holds `hidden` and `secret`
+  values for its TTL, as the handler returned them.
 - **A cache backend that is down does not take the endpoint down.** A failed read is warned and the call runs
   uncached; a failed write is warned and dropped.
 - The default middleware chain is `Logging → Timeout → <lib middlewares>`, and the call inside it runs an
@@ -99,6 +107,21 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   handler: a hung cache backend is bounded by the same deadline as the handler it stands in for. **`Retry` was removed** — an automatic re-run of an endpoint
   whose failure it cannot classify replays whatever the first attempt already did.
 
+## Repeated Mutations
+
+- **A mutation sent again under the same `Idempotency-Key` header runs once.** The key is checked after the
+  resource guards and the internal arguments, and it is scoped to the endpoint, the caller and a digest of the
+  arguments, so one caller's key never hands another caller its answer. A repeat while the first run is still going
+  answers 409 `base.error.idempotencyInFlight`.
+- **A repeat answers the first response as it was sent** — resolved, masked and serialized — for 24 hours. What
+  is kept is that wire form, never the handler's result, so no `hidden` or `secret` field reaches the cache.
+- A handler that throws frees the key, so a repeat runs it again. A failure after the handler returned is kept and
+  replayed instead, for the same 24 hours and a transient one (a relation read during a database blip) included:
+  the handler's writes stand, so running it again would repeat them.
+- **Only an HTTP call is deduplicated.** A signed-out call, one whose handler returns a `Response` (whose headers,
+  such as a session's `Set-Cookie`, cannot be replayed), a websocket call, and a call through MCP all run every
+  time.
+
 ## Rate Limits
 
 - **`{ rateLimit: { calls, windowMs?, by? } }` in an endpoint's signal option** counts calls per caller per window
@@ -107,9 +130,9 @@ mutation is mounted under. `conventions` carries the invariants — this is the
   checked after the middlewares and before the guards, keyed by `accountKey(account)`; a caller it names nothing
   for — an anonymous one — is counted by address. Leaving a pubsub room is never counted.
 - **The answer is 429 `base.error.tooManyRequests` with `data: { seconds }`** and a `Retry-After` header; a WS
-  call gets the same payload as its error frame, and the HTTP client restores a proxy's own non-JSON 429 under the
-  same key (seconds from its `Retry-After`, else 60). The first refusal per endpoint per process is warned once;
-  later ones log at `debug`, so a flood does not become a log flood.
+  call gets the same payload as its error frame, and the HTTP client restores a proxy's own 429 — a page, or JSON
+  naming no error key of ours — under the same key (seconds from its `Retry-After`, `0` included, else 60). The first
+  refusal per endpoint per process is warned once; later ones log at `debug`, so a flood does not become a log flood.
 - **Keys and addresses.** The address is `context.getClientIp()` — the trusted-proxy answer, never a raw header
   from an untrusted peer. Callers whose address is unknown share one `unknown` budget (fail closed), and the first
   such call is warned about, since it usually means the proxy in front records no `X-Real-IP`/`X-Forwarded-For`

package/incrementalBuilder.proc.js

@@ -8,19 +8,21 @@ import {
   CodegenLock,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-55mynnqs.js";
+} from "./index-2etqq75t.js";
 import"./index-52w0fvh8.js";
 import {
   GraphClientEntryDiscovery,
   RouteClientBuilder,
   AutoImportSync,
-  ServerGraphFile,
   CsrDevPatcher,
   CsrDevBundler,
   DevChangePlanner,
   DevGeneratedIndexSync,
   SsrDevBundler
-} from "./index-aprt7pkz.js";
+} from "./index-xpdgxsj5.js";
+import {
+  ServerGraphFile
+} from "./index-nq045px5.js";
 import {
   prepareDevWatchBatch
 } from "./index-a5vmm6x4.js";
@@ -235,7 +237,7 @@ class IncrementalBuilder {
   #autoImportSync;
   #watcher = null;
   #generation = 0;
-  #shellGeneration = null;
+  #shellKey = null;
   #discoveredThrough = 0;
   #csrActive = IncrementalBuilder.#csrArmedByEnv();
   #csrBundler;
@@ -948,13 +950,14 @@ class IncrementalBuilder {
   async#buildShell(msg) {
     await this.#workQueue.enqueue("build-shell", async () => {
       const generation = this.#generation;
+      const shellKey = `${generation}:${JSON.stringify(this.#artifact.cssAssets)}`;
       let error;
-      if (this.#shellGeneration !== generation)
+      if (this.#shellKey !== shellKey)
         try {
           const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs: ["shell"], changedFiles: [] }));
           error = result.errors.shell;
           if (!error)
-            this.#shellGeneration = generation;
+            this.#shellKey = shellKey;
         } catch (err) {
           error = ApplicationBuildReporter.formatError(err, this.#app.workspace.workspaceRoot);
         }