@akanjs/cli 3.1.1 → 3.1.2-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (113) hide show
  1. package/.build-stamp +1 -1
  2. package/CodeAgent-dyc45f5w.js +11 -0
  3. package/{CodeAgentRpcHost-9g27hmer.js → CodeAgentRpcHost-6dzfkvsc.js} +1 -1
  4. package/CodeAgentRpcListener-tcwrdvst.js +182 -0
  5. package/{CodeTui-h6yz2kvq.js → CodeTui-q55b2zrn.js} +25 -8
  6. package/TunnelShare-hdq9h1hr.js +14 -0
  7. package/{agent.command-3r4jsck8.js → agent.command-20zaqe60.js} +18 -15
  8. package/akanCode.js +8 -7
  9. package/{application.command-g7xv6ad0.js → application.command-nd0fshsk.js} +11 -11
  10. package/{applicationBuildRunner-qvjnhr9j.js → applicationBuildRunner-s13x3zqb.js} +10 -9
  11. package/buildBatch.proc.js +6 -6
  12. package/{cloud.command-6ebygmhw.js → cloud.command-8kbddsz9.js} +25 -18
  13. package/cloud.script-hgvvajm3.js +27 -0
  14. package/code.command-625bg8s8.js +345 -0
  15. package/{context.command-svdh6b2w.js → context.command-p6haqjay.js} +19 -18
  16. package/context.runner-rsnqnk9j.js +27 -0
  17. package/{dependencyScanner-3afj2vt1.js → dependencyScanner-78sq8m4q.js} +2 -2
  18. package/{fileSys-wzzrntkw.js → fileSys-zpvt5gtf.js} +1 -1
  19. package/{guideline.command-qwp3tnjx.js → guideline.command-195g0h9a.js} +4 -4
  20. package/guidelines/agentRule/agentRule.instruction.md +22 -8
  21. package/guidelines/conventions/rules/auth.md +5 -4
  22. package/guidelines/conventions/rules/config.md +5 -1
  23. package/guidelines/conventions/rules/gates.md +2 -1
  24. package/guidelines/conventions/rules/module.md +1 -1
  25. package/guidelines/conventions/rules/server.md +8 -3
  26. package/guidelines/conventions/rules/ssr.md +2 -2
  27. package/guidelines/conventions/rules/tsx.md +2 -1
  28. package/guidelines/pageRule/pageRule.instruction.md +4 -4
  29. package/guidelines/runtimeRule/runtimeRule.instruction.md +35 -25
  30. package/guidelines/ssrRule/ssrRule.instruction.md +11 -10
  31. package/guidelines/transportRule/transportRule.instruction.md +5 -4
  32. package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +1 -1
  33. package/incrementalBuilder.proc.js +4 -4
  34. package/{index-w4k2ragk.js → index-00a7j05x.js} +7 -7
  35. package/{index-w7q6h97v.js → index-0j1t1h2b.js} +3 -1
  36. package/{index-payhwt51.js → index-1h2jc0x3.js} +141 -67
  37. package/{index-vxmy1p4f.js → index-1qsd8ft1.js} +63 -123
  38. package/{index-s6da8ta9.js → index-2mwjshz5.js} +158 -51
  39. package/index-2nxk8wgs.js +266 -0
  40. package/{index-k5jbcxyh.js → index-2phm56a1.js} +49 -8
  41. package/{index-jje9qzyq.js → index-35j83zkd.js} +37 -3
  42. package/{index-m5n3ka0p.js → index-4am4dvmf.js} +13 -2
  43. package/index-75y7bcz4.js +28 -0
  44. package/{index-b8c289dx.js → index-7apsdr5g.js} +55 -12
  45. package/{index-8559hsz4.js → index-84h43kg6.js} +6 -5
  46. package/{index-eja64h28.js → index-9zy8479y.js} +5 -3
  47. package/{index-96wzdhfh.js → index-a1vb3x7t.js} +209 -36
  48. package/{index-52w0fvh8.js → index-bns3wcpc.js} +15 -0
  49. package/{index-am36s3jh.js → index-cjmjvg4r.js} +157 -117
  50. package/{index-1p0qbq3m.js → index-defp4gmb.js} +1 -1
  51. package/{index-4pdts00b.js → index-ewbmfarf.js} +10 -8
  52. package/{index-9rvcs76p.js → index-fhw7yq2d.js} +10 -10
  53. package/{index-8scw1pjk.js → index-g500c5j9.js} +178 -82
  54. package/{index-qxzrp5xt.js → index-g841cap9.js} +4 -4
  55. package/{index-qkkdhjm6.js → index-gr9thy79.js} +5 -5
  56. package/{index-4pf8g7ff.js → index-h7hehkw6.js} +3 -0
  57. package/{index-4mj92tsh.js → index-hm0tn7qv.js} +73 -68
  58. package/{index-r2wedvqn.js → index-j6eeh5d7.js} +1 -1
  59. package/{index-tgt2fnd6.js → index-j7hwy56s.js} +3 -3
  60. package/{index-rnphv731.js → index-jc2zbwra.js} +2 -2
  61. package/{index-z4b84y6k.js → index-khk05tsf.js} +1 -1
  62. package/{index-tvehn2sp.js → index-qd7xn2bk.js} +1 -1
  63. package/{index-266dewjs.js → index-qw6814m4.js} +53 -15
  64. package/{index-zcf6k8a5.js → index-raz588b3.js} +47 -12
  65. package/{index-at7bz0xq.js → index-s4nvxpzm.js} +2 -0
  66. package/{index-3yz30c07.js → index-sp0qsr7a.js} +114 -12
  67. package/{index-1shvxzt0.js → index-sveq36gh.js} +39 -42
  68. package/{index-r2w2eh93.js → index-t1t9wq9a.js} +4 -4
  69. package/index-t78230d7.js +191 -0
  70. package/{index-r0k3ham2.js → index-tgqameyb.js} +4 -4
  71. package/{index-dd44g6vz.js → index-tp56652m.js} +5 -5
  72. package/index-w15mg3km.js +389 -0
  73. package/{index-xq543a5y.js → index-y4kcmbt2.js} +2 -2
  74. package/index-yf9wc28h.js +52 -0
  75. package/{index-xqgwjz7a.js → index-zbrwnmf1.js} +9 -7
  76. package/{index-xxfy1jp2.js → index-zttm13c3.js} +4 -4
  77. package/index.js +24 -24
  78. package/{library.command-2853y6mk.js → library.command-63hgt9te.js} +4 -4
  79. package/{localRegistry.command-76ds31p4.js → localRegistry.command-g3f8k25t.js} +43 -23
  80. package/{module.command-yfnb0abs.js → module.command-r4sa2khp.js} +7 -6
  81. package/{package.command-d9s86hp9.js → package.command-96eheyvd.js} +5 -5
  82. package/package.json +2 -2
  83. package/{page.command-6a8a8rd1.js → page.command-gs6d841d.js} +4 -4
  84. package/{pipeline.command-rt3rwd2z.js → pipeline.command-wdfvdbfj.js} +3 -3
  85. package/{primitive.command-emcebgrq.js → primitive.command-dfsv4mpe.js} +8 -7
  86. package/{projectTypecheck-51m7eh1f.js → projectTypecheck-kqj1t6hb.js} +1 -1
  87. package/{prompter-hgcta8pb.js → prompter-qrwx1p17.js} +2 -2
  88. package/{quality.command-xtrk0n3x.js → quality.command-webzxee2.js} +6 -4
  89. package/{repair.command-51szxnxx.js → repair.command-3r3j1xre.js} +7 -6
  90. package/{scalar.command-8qv27t82.js → scalar.command-e8y47j6d.js} +6 -5
  91. package/skills/akan-agent/SKILL.md +8 -1
  92. package/skills/akan-code/SKILL.md +37 -11
  93. package/skills/akan-debug/SKILL.md +2 -1
  94. package/skills/akan-err/SKILL.md +2 -1
  95. package/skills/akan-query/SKILL.md +3 -2
  96. package/skills/akan-runtime/SKILL.md +3 -0
  97. package/{subspace.command-pn56pnh8.js → subspace.command-a1sf9n5a.js} +12 -10
  98. package/templates/appSample/lib/task/task.signal.ts +14 -9
  99. package/templates/appSample/srvkit/guards.ts +11 -0
  100. package/templates/service/__model__.dictionary.ts +3 -5
  101. package/templates/workspaceRoot/.gitignore.template +1 -0
  102. package/{tunnel.command-q2h0j2en.js → tunnel.command-dcb0wg93.js} +25 -13
  103. package/{verify.command-z1dsbmrt.js → verify.command-yyepccbh.js} +13 -11
  104. package/{workflow.command-r3y67jeq.js → workflow.command-z5pg9ay0.js} +12 -11
  105. package/{workspace.command-t2f0xsrw.js → workspace.command-d7x5jttw.js} +74 -47
  106. package/CodeAgent-35wnb7w5.js +0 -9
  107. package/CodeAgentRpcListener-7p7z5dd7.js +0 -97
  108. package/TunnelShare-xyjpa7gx.js +0 -14
  109. package/cloud.script-0s1jybd5.js +0 -26
  110. package/code.command-mpkm2emr.js +0 -167
  111. package/context.runner-ch0z3a8g.js +0 -26
  112. package/index-c6eggbee.js +0 -123
  113. package/index-ksfgqq1x.js +0 -49
@@ -58,10 +58,10 @@ body shape — this is the full contract behind them. Before changing route beha
58
58
  (`.guard(() => signedIn())`), because `.guard(signedIn)` would hand the route's arguments to `unauthorize`.
59
59
  - **On the server every guard of the chain runs before any layout body starts**, root layout first and before the
60
60
  route's arguments are checked, so a redirect is a real 307 even after an awaited query, and a not-found is a 404 —
61
- where a `getSelf({ unauthorize })` inside a layout body after I/O redirects late, inside the stream. A query in a
62
- guard that the server refuses with 403 or 404 (an owner check) answers not-found, so the page never confirms the
63
- record exists. A refusal's not-found keeps only the layouts above the refusing guard, and a path no page matches
64
- asks the guards of the layouts its not-found would sit under first.
61
+ where a `getSelf({ unauthorize })` inside a layout body under a `.loading()` redirects late after I/O, inside the
62
+ stream. A query in a guard that the server refuses with 403 or 404 (an owner check) answers not-found, so the page
63
+ never confirms the record exists. A refusal's not-found keeps only the layouts above the refusing guard, and a path
64
+ no page matches asks the guards of the layouts its not-found would sit under first.
65
65
  - **On a client navigation a page's layers wait for its guards.** The verdict is kept by what the guards read (a
66
66
  query only the page reads keeps it) and lasts while a layer of that location is on screen. Only the page in front
67
67
  asks — never a parked one, nor the one under it during a swipe back; back in front, a cached page included, it asks
@@ -102,9 +102,11 @@ worker per web-serving replica.
102
102
  gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
103
103
  rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
104
104
  - **Health detail and metrics answer only `Authorization: Bearer $AKAN_STATUS_TOKEN`** (or the log stream token)
105
- outside `local`: without it `/_akan/app/health` is `{ status }` alone (still 200) and `/_akan/app/metrics` is 401.
106
- A probe that reads only the status code needs nothing; give a scraper or monitor `AKAN_STATUS_TOKEN`, which reads
107
- nothing else.
105
+ outside the local dev runtime — `AKAN_PUBLIC_ENV` and the operation mode both `local`, under `akan start` or a
106
+ `NODE_ENV` other than `production`, so a built server stays closed: without it `/_akan/app/health` is `{ status }`
107
+ alone (still 200) and `/_akan/app/metrics` is 401. An address that sends 10 wrong bearers in a minute is refused
108
+ the right one too until the minute passes. A probe that reads only the status code needs nothing; give a scraper or
109
+ monitor `AKAN_STATUS_TOKEN` (32 characters or more, or it warns), which reads nothing else.
108
110
  - **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
109
111
  with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
110
112
  - **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
@@ -156,12 +158,13 @@ worker per web-serving replica.
156
158
  and neither does a save in a sibling app. An import that makes a new lib a dependency needs a fresh
157
159
  `akan start`, because it needs a `sync` first anyway. Before the first `sync` the manifests do not exist yet and
158
160
  the whole `libs/` container is watched, which is the safe direction.
159
- - **A built artifact runs from the generated app directory** with the Akan runtime environment variables:
161
+ - **A built artifact runs from the generated app directory, without Docker and without an env.** `akan build`
162
+ writes `akan.env.json` beside `main.js` with the values the Dockerfile's `ENV` lines set, and `main.js` takes
163
+ each one the process was not started with, so a variable you set (or the image's `ENV`) wins. Start it from that
164
+ directory: the runtime reads its artifacts and writes `runtime/` and SQLite files relative to the cwd.
160
165
 
161
166
  ```bash
162
- cd dist/apps/<appName> && USE_AKANJS_PKGS=true AKAN_PUBLIC_REPO_NAME=<repo> AKAN_PUBLIC_SERVE_DOMAIN="<domain>" \
163
- AKAN_PUBLIC_APP_NAME=<appName> AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation \
164
- AKAN_PUBLIC_BASE_PATHS=<basePaths> bun main.js
167
+ cd dist/apps/<appName> && PORT=3100 bun main.js
165
168
  ```
166
169
 
167
170
  - **A server a test boots in-process takes `start({ listen: false, schedules: false })`** to run no internal
@@ -207,7 +210,8 @@ normalized to `info` with one warning.
207
210
  server's socket rather than reading their own logs.
208
211
  - **The generated Dockerfile sets `AKAN_LOG_TO_FILE=0`.** A container's writable layer is ephemeral and nothing
209
212
  collects a file from it; stdout is the collection path. A deployment that wants the files back sets
210
- `AKAN_LOG_TO_FILE=1`.
213
+ `AKAN_LOG_TO_FILE=1`; they are created 0600, so a collector running as another user needs `AKAN_LOG_FILE_MODE`
214
+ (octal, e.g. `640`), and a file already there keeps its mode.
211
215
  - **`AKAN_LOG_FORMAT=ndjson` makes the container's stdout one JSON record per line, and the hub owner (gateway or
212
216
  solo replica) its only writer** — every other server process turns its console off and forwards from
213
217
  `AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
@@ -216,8 +220,8 @@ normalized to `info` with one warning.
216
220
  unset, the route does not exist. The same bearer also unlocks the health detail and metrics.
217
221
  - **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call; **`AKAN_LOG_FLIGHT=1`**
218
222
  keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
219
- `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — in `local`, or with the
220
- `AKAN_LOG_DEBUG_HEADER` secret.
223
+ `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — under the local dev runtime, or
224
+ with the `AKAN_LOG_DEBUG_HEADER` secret.
221
225
  - **Structured values go in `LogRecord.attrs` via `Logger.emit(...)`**; a key naming a secret is `[redacted]`
222
226
  before the record exists.
223
227
  - **Never log per delivered record in anything that delivers records.** The control socket and the hub do not,
@@ -394,11 +398,11 @@ const config: AppConfig = {
394
398
  A desktop app whose `native` section, or target, declares `desktop: { server: true }` carries the app's server:
395
399
  `akan build-desktop`, `start-desktop --release` and `publish-update` put the backend `akan build` made into the
396
400
  app — everything the backend build wrote (the `.js`, `akan.build.json`, `private/`, a bundled package's `.node`,
397
- `.wasm` or file asset) but the Dockerfile, the RSC worker, the console, `csr/` and `public/` — and install its
398
- packages first with `bun install --production --prefer-offline`, before `akan build` runs. `start-desktop` without
399
- `--release` starts `akan start` beside the app when no dev server of this checkout answers. The setting is the
400
- app's backend, so it does not change under an installed app: an update whose release carries a server when the app
401
- has none, or none when it has one, is refused, and switching means a reinstall.
401
+ `.wasm` or file asset) but the Dockerfile and its `akan.env.json`, the RSC worker, the console, `csr/` and
402
+ `public/` — and install its packages first with `bun install --production --prefer-offline`, before `akan build`
403
+ runs. `start-desktop` without `--release` starts `akan start` beside the app when no dev server of this checkout
404
+ answers. The setting is the app's backend, so it does not change under an installed app: an update whose release
405
+ carries a server when the app has none, or none when it has one, is refused, and switching means a reinstall.
402
406
  `desktop: { server: { omit: ["rclnodejs"] } }` carries the server without packages only the image needs — an addon
403
407
  tied to the image's system, code only a process the app never starts loads — and whatever only they pull in; the
404
408
  image keeps them, and the server's own bundle must not import them. A package another dependency still installs
@@ -598,8 +602,8 @@ serving without a key. Everything else is behind the ops channel.
598
602
 
599
603
  | surface | what it does |
600
604
  |---|---|
601
- | `bun main.js ops snapshot [--id] [--out] [--include-solid] [--json]` | `VACUUM INTO` a consistent copy, `integrity_check`, sha256, gzip, optional age encryption, `manifest.json` |
602
- | `bun main.js ops restore <manifest.json> [--identity <file>]` | offline only: verify, stage, keep the old file as `<db>.pre-restore-<ts>` (its `-wal`/`-shm` beside it), swap |
605
+ | `bun main.js ops snapshot [--id] [--out] [--include-solid] [--allow-plaintext] [--json]` | `VACUUM INTO` a consistent copy, `integrity_check`, sha256, gzip, age encryption, `manifest.json` |
606
+ | `bun main.js ops restore <manifest.json> [--identity <file>] [--allow-plaintext]` | offline only: verify, stage, keep the old file as `<db>.pre-restore-<ts>` (its `-wal`/`-shm` beside it), swap |
603
607
  | `GET /_akan/ops/info` | the public info plus `akanVersion`, `buildId`, `serverMode`, `databaseMode`, `solo`, `startedAt`, `replicaIdx` |
604
608
  | `POST /_akan/ops/snapshot` `{ id, includeSolid?, uploadUrls: { main, solid?, manifest } }` | 202; a child process snapshots, then PUTs each file and the manifest **last** |
605
609
  | `GET /_akan/ops/snapshot/:id` | `running` → `uploading` → `done` \| `failed`; kept in memory, so a restart answers 404 |
@@ -612,12 +616,15 @@ serving without a key. Everything else is behind the ops channel.
612
616
  - **Restore refuses while an app answers `/_akan/app/health` on `PORT`** and names it by its `/_akan/app/info`;
613
617
  `--force` is for a port some other app holds.
614
618
  - **The channel exists only when `AKAN_OPS_PUBLIC_KEY` is set** (Ed25519: PEM, JWK, base64 SPKI or raw 32 bytes).
615
- The control plane signs a short EdDSA JWS — `aud`, `iat`, `exp` at most 300s after `iat`, a `jti` the process
616
- refuses twice, and optionally `sub`, whom it acts for — and the host holds only the public half, so a machine
617
- someone carries off mints nothing.
619
+ The control plane signs a short EdDSA JWS — `typ` `akan-ops+jwt` (`JWT` or none from an older control plane; any
620
+ other `typ` is refused), `aud`, `iat`, `exp` at most 300s after `iat`, a `jti` the process refuses twice, and
621
+ optionally `sub`, whom it acts for — and the host holds only the public half, so a machine someone carries off
622
+ mints nothing.
618
623
  `aud` is `<appName>/<environment>`, or `<appName>/<environment>/<AKAN_OPS_INSTANCE>` when that is set, and then
619
- only that: a token minted for the app as a whole would replay across every host sharing the name. 30 calls a
620
- minute per process; every refusal is the same 401. A malformed key leaves the app serving with the channel off.
624
+ only that: a token minted for the app as a whole would replay across every host sharing the name. Verified calls
625
+ get 30 a minute per process; every refusal is the same 401 and spends none of them, and an address refused 10
626
+ times in a minute gets 429 until it passes. A malformed key, or the machine token's own key
627
+ (`AKAN_MACHINE_PUBLIC_KEY`), logs an error and leaves the app serving with the channel off.
621
628
  - **A migrate job runs for the token's `sub`**, which the run records as its actor: apply and rollback refuse a
622
629
  token without one, and a body naming `actor` is refused. Each option reaches the command as `--name=value`. One
623
630
  job runs at a time per process (409 meanwhile); the run's own lease keeps two hosts on one database apart. Jobs
@@ -629,10 +636,13 @@ serving without a key. Everything else is behind the ops channel.
629
636
  (`SQLITE_DATABASE_PATH`, `AKAN_SOLID_DB_PATH`, `AKAN_SQLITE_DIR`); a solo process uses the path its adaptor
630
637
  actually opened, so a gateway deployment that moved the file in `env.server.ts` names it in the env too.
631
638
  - **`AKAN_BACKUP_RECIPIENT=age1…[,age1…]` encrypts before upload** — age v1 X25519, so `age -d -i key.txt` opens
632
- it. Restore takes `--identity` / `AKAN_BACKUP_IDENTITY_FILE`, or a file an operator already decrypted with
633
- `age -d -o <name without .age>`.
639
+ it. Outside local operation a snapshot refuses to run without it, the ops channel's job included, unless
640
+ `--allow-plaintext` or `AKAN_BACKUP_PLAINTEXT=1` allows an unencrypted one. Restore takes `--identity` /
641
+ `AKAN_BACKUP_IDENTITY_FILE`, or a file an operator already decrypted with `age -d -o <name without .age>`; given
642
+ an identity, it refuses a manifest recording no encryption without `--allow-plaintext`.
634
643
  - **The host keeps the newest `AKAN_OPS_SNAPSHOT_KEEP` (default 2) snapshots** under `AKAN_OPS_SNAPSHOT_DIR`
635
- (default `<db dir>/snapshots/<id>/`) — the copy an edge still has while its uplink or the bucket is down.
644
+ (default `<db dir>/snapshots/<id>/`) — the copy an edge still has while its uplink or the bucket is down. Files are
645
+ 0600 and each `<id>/` 0700; `AKAN_OPS_SNAPSHOT_FILE_MODE` (octal, e.g. `640`) sets another mode.
636
646
  - **`buildId` is `AKAN_BUILD_ID` when the deployment sets it**, else the git sha `akan build` wrote into
637
647
  `akan.build.json` beside `main.js` (`-dirty` when the tree was).
638
648
  - **`operationMode` does not gate any of this** — the key does. `edge` means a production host outside the
@@ -124,9 +124,9 @@ own boundary as its own data lands, so one slow query no longer holds the page.
124
124
  the aggregate the way `x<Slice>Init` must.
125
125
 
126
126
  **`await` is still the right call for what the page needs immediately.** It returns the shape the helper always
127
- gave and keeps that markup in the shell, which is what SEO snapshots, prerendering and pre-hydration E2E read; a
128
- boundary moves its subtree out of the shell and into the stream. Independent awaited fetches still go through one
129
- `Promise.all`.
127
+ gave and keeps that markup in the shell — every level above the route's first `.loading()` — which is what SEO
128
+ snapshots, prerendering and pre-hydration E2E read; a boundary moves its subtree out of the shell and into the
129
+ stream. Independent awaited fetches still go through one `Promise.all`.
130
130
 
131
131
  Three rules the shape enforces:
132
132
 
@@ -143,13 +143,14 @@ Three rules the shape enforces:
143
143
  **A failure now surfaces where it happened.** One `Promise.all` in the page body reports nothing about which of
144
144
  eight queries threw; per-section boundaries put each rejection at its own boundary.
145
145
 
146
- **Know which redirects are real.** A streaming response starts while layout and page bodies still run, so a redirect
147
- is a real 3xx only when it was raised before any I/O was awaited, the body's own or a layout's above it (a layout that
148
- awaits `fetch.viewOrg` makes every page under it late); after one — `getSelf({ unauthorize: "/signin" })` fetches —
149
- a browser gets an HTTP 200 that navigates in the page, which `curl` does not follow, while a crawler, whose response
146
+ **Know which redirects are real.** The response starts once every layout and page body above the route's first
147
+ `.loading()` has rendered — the whole route when it declares none — so a redirect or `router.notFound()` raised in
148
+ those bodies is a real 3xx or 404 even after I/O. Below a `.loading()` or inside a streamed section the response has
149
+ already started: a redirect raised there after I/O — `getSelf({ unauthorize: "/signin" })` fetches — reaches a
150
+ browser as an HTTP 200 that navigates in the page, which `curl` does not follow, while a crawler, whose response
150
151
  waits for the whole render, gets the real 3xx. Either way no markup below the redirect is sent. A route's `.guard()`
151
- runs before any layout body starts, so a redirect from it is a real 3xx even after the guard's own awaited query:
152
- gate there. A route that must answer a real 3xx from its body after I/O — a moved URL found by a query — takes
152
+ runs before any layout body starts, so a redirect from it is a real 3xx even under a `.loading()`: gate there. A
153
+ route with a `.loading()` that must answer a real 3xx from its body after I/O — a moved URL found by a query — takes
153
154
  `.config({ ssr: "block" })`: the response waits for the whole render. Never redirect from inside a streamed section.
154
155
 
155
156
  **⑥ Use named `ReactNode` slots, not just `children`.** A client shell that takes one slot per region lets a
@@ -163,7 +164,7 @@ the same method, so a client component that exists only to compute a label is ma
163
164
  **⑧ Gate auth on the server.** `.guard(() => signedIn())` (`@libs/shared/webkit`, which a new workspace has only
164
165
  with `create-workspace --libs true`) on `_layout.tsx` runs before any of the route renders, so the redirect is a
165
166
  real 3xx; `getSelf({ unauthorize: "/signin" })` in a layout body still redirects before any of the page's markup,
166
- in-page after I/O. A client-side check costs a hydration round-trip and flashes the wrong UI first.
167
+ in-page after I/O under a `.loading()`. A client-side check costs a hydration round-trip and flashes the wrong UI first.
167
168
 
168
169
  **⑨ Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants (see
169
170
  `libs/util/ui/Grid/*`) or `<details>`/`<summary>` keeps both branches server-rendered. Reach for `useState` when the
@@ -8,10 +8,11 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
8
8
  ## Guards And Transports
9
9
 
10
10
  - Guards run on both HTTP and websocket calls. Read the caller with `context.get<T>("account")` (`pkgs/akanjs/signal/signalContext.ts`) instead of branching on `getHttpContext()` / `getWebSocketContext()`.
11
- - Slice-level `guards` only reach the generated query/mutation endpoints. A `pubsub`/`message` endpoint is unguarded unless it declares its own `guards` in its signal option.
12
- - **Every endpoint that declares no guards is named in a boot `warn`**, since it answers anyone over HTTP and
13
- WebSocket — a named slice's `init()`, a root slice, a `pubsub`/`message`/`query`/`mutation`. Write
14
- `guards: [Public]` to keep one open on purpose.
11
+ - Slice-level `guards` only reach the generated query/mutation endpoints. A `pubsub`/`message` endpoint declares none unless it names its own `guards` in its signal option.
12
+ - **An endpoint that declares no guards is refused** — 403 over HTTP and WebSocket, and MCP neither lists nor runs
13
+ it: a named slice's `init()`, a root slice, a `pubsub`/`message`/`query`/`mutation`. Local operation names each in a boot `warn`;
14
+ anywhere else the boot fails, so the deploy does. Write `guards: [Public]` to keep one open on purpose;
15
+ `AKAN_UNGUARDED_ENDPOINTS=open` answers them to anyone as before, with a boot warning.
15
16
  - **A generated verb is taken off HTTP with `guards: { cru: false }`** (or `get`/`create`/`update`/`remove:
16
17
  false`), and a verb whose guards resolve to none is not mounted at all. `mcp: { cru: false }` does **not** do
17
18
  this: it keeps the verbs off the agent shelf while HTTP serves them to whoever passes their guards.
@@ -488,7 +488,7 @@ export const env: ModulesOptions = {
488
488
  | `setLlm({ apiKey })`, relying on the DeepSeek default | `setLlm({ apiKey, model, host })` | The app boots, the log warns once, and the chat answers `llmUnavailable` to every turn |
489
489
  | `applyAdaptor(LlmAdaptorRole, DeepseekLlm)` | `OpenaiLlm` + `host: "https://api.deepseek.com"` | Build error — the class is gone |
490
490
  | `OpenaiLlm` pointed at a **named** `host`, reading images | add `accepts: { image: true }` to `setLlm` | **Silent**: images reach the model as a note saying they could not be read |
491
- | An adaptor of your own throwing `agent.error.<vendor>RequestFailed` | `new Err("agent.error.llmRequestFailed", { provider, status, reason })` | The chat prints the raw key instead of a sentence |
491
+ | An adaptor of your own throwing `agent.error.<vendor>RequestFailed` | `throw LlmOverflow.refusal(host, status, reason)`, which sends `{ provider, status }` and logs `reason` on the server | The chat prints the raw key instead of a sentence |
492
492
  | Provider settings in a second `option.use({ myLlmOption })` | put them in `setLlm` and read `use<MyLlmOption>()` | Nothing breaks; the second channel is no longer needed |
493
493
 
494
494
  `OpenaiLlm` claims vision for its default host (`https://api.openai.com/v1`) and for nothing else, because a host
@@ -8,8 +8,8 @@ import {
8
8
  CodegenLock,
9
9
  WorkspaceExecutor,
10
10
  AppExecutor
11
- } from "./index-8scw1pjk.js";
12
- import"./index-52w0fvh8.js";
11
+ } from "./index-g500c5j9.js";
12
+ import"./index-bns3wcpc.js";
13
13
  import {
14
14
  GraphClientEntryDiscovery,
15
15
  RouteClientBuilder,
@@ -19,10 +19,10 @@ import {
19
19
  DevChangePlanner,
20
20
  DevGeneratedIndexSync,
21
21
  SsrDevBundler
22
- } from "./index-dd44g6vz.js";
22
+ } from "./index-tp56652m.js";
23
23
  import {
24
24
  ServerGraphFile
25
- } from "./index-xqgwjz7a.js";
25
+ } from "./index-zbrwnmf1.js";
26
26
  import {
27
27
  prepareDevWatchBatch
28
28
  } from "./index-a5vmm6x4.js";
@@ -4,27 +4,27 @@ import {
4
4
  CloudApi,
5
5
  CloudUpdates,
6
6
  PipelineSecrets
7
- } from "./index-qkkdhjm6.js";
7
+ } from "./index-gr9thy79.js";
8
8
  import {
9
9
  PkgExecutor
10
- } from "./index-8scw1pjk.js";
10
+ } from "./index-g500c5j9.js";
11
11
  import {
12
12
  UpdatePackFolder,
13
13
  NativePublicEnv,
14
14
  NativeApp
15
- } from "./index-3yz30c07.js";
15
+ } from "./index-sp0qsr7a.js";
16
16
  import {
17
17
  script
18
- } from "./index-eja64h28.js";
18
+ } from "./index-9zy8479y.js";
19
19
  import {
20
20
  ApplicationScript
21
- } from "./index-4pdts00b.js";
21
+ } from "./index-ewbmfarf.js";
22
22
  import {
23
23
  PackageScript
24
- } from "./index-8559hsz4.js";
24
+ } from "./index-84h43kg6.js";
25
25
  import {
26
26
  CloudRunner
27
- } from "./index-payhwt51.js";
27
+ } from "./index-1h2jc0x3.js";
28
28
 
29
29
  // pkgs/@akanjs/cli/cloud/cloud.script.ts
30
30
  import { Logger } from "akanjs/common";
@@ -1,15 +1,17 @@
1
1
  // @bun
2
2
  import {
3
3
  DesktopBin
4
- } from "./index-3yz30c07.js";
4
+ } from "./index-sp0qsr7a.js";
5
5
  // pkgs/@akanjs/devkit/mobile/desktopServerStage.ts
6
6
  import { cp, mkdir, readdir, rm, writeFile } from "fs/promises";
7
7
  import path from "path";
8
8
  import { toError } from "akanjs/common";
9
+ import { BUILD_ENV_FILE } from "akanjs/server/lifecycle/buildEnv";
9
10
  class DesktopServerStage {
10
11
  app;
11
12
  static uncarried = new Set([
12
13
  "Dockerfile",
14
+ BUILD_ENV_FILE,
13
15
  "package.json",
14
16
  "bun.lock",
15
17
  "rscWorker.js",