@akanjs/cli 3.3.0-rc.12 → 3.3.0-rc.13

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 (91) hide show
  1. package/.build-stamp +2 -2
  2. package/{CodeAgent-cqbf9gsv.js → CodeAgent-zkr3s3xy.js} +2 -2
  3. package/{CodeTui-ehdr4hgw.js → CodeTui-1qvrzfmy.js} +1 -1
  4. package/TunnelShare-8j95ta3w.js +16 -0
  5. package/{agent.command-x55ncdjm.js → agent.command-dejgb8vz.js} +18 -17
  6. package/akanCode.js +2 -2
  7. package/{appExecutor-1ctzymwa.js → appExecutor-nj95a6en.js} +3 -3
  8. package/{application.command-xpntxnh8.js → application.command-3tnq1587.js} +45 -15
  9. package/{applicationBuildRunner-19c76791.js → applicationBuildRunner-cbjy05yg.js} +75 -12
  10. package/buildBatch.proc.js +10 -10
  11. package/{cloud.command-p3ybjes7.js → cloud.command-qae6et2e.js} +19 -18
  12. package/cloud.script-34xmprty.js +31 -0
  13. package/{code.command-m6skj1kj.js → code.command-xrh506zf.js} +10 -10
  14. package/commandManifest.json +1 -1
  15. package/{context.command-3c3nv0d6.js → context.command-fxyzkwg5.js} +18 -18
  16. package/context.runner-bz1jwxkk.js +32 -0
  17. package/{csrArtifactBuilder-mdh9ykn2.js → csrArtifactBuilder-rqg85wbg.js} +2 -2
  18. package/{guideline.command-725fq5p0.js → guideline.command-7dgscqjq.js} +6 -6
  19. package/guidelines/conventions/rules/config.md +5 -0
  20. package/guidelines/conventions/rules/page.md +3 -0
  21. package/guidelines/errorCodes/errorCodes.instruction.md +4 -0
  22. package/guidelines/pageRule/pageRule.instruction.md +19 -0
  23. package/guidelines/runtimeRule/runtimeRule.instruction.md +109 -6
  24. package/incrementalBuilder.proc.js +8 -8
  25. package/{index-3mj5trqc.js → index-0bzrcv91.js} +1 -1
  26. package/{index-q63nbpv7.js → index-0zkxsdsg.js} +3 -3
  27. package/{index-wxqp1amd.js → index-1c52g4st.js} +11 -9
  28. package/{index-vnk1qwgr.js → index-22h6vq3f.js} +4 -4
  29. package/index-35p43f33.js +16 -0
  30. package/{index-fagjtk6m.js → index-3q7ectss.js} +2 -2
  31. package/{index-se7n78fh.js → index-54g085ty.js} +1 -1
  32. package/{index-rt7q20sj.js → index-5sa1tr7w.js} +1 -1
  33. package/{index-h8w1n11r.js → index-6a3rmwxx.js} +4 -4
  34. package/{index-yey1envc.js → index-741xbhes.js} +1 -1
  35. package/{index-9a9t77hz.js → index-77627y32.js} +2 -2
  36. package/{index-4r8dgm4x.js → index-8javbznc.js} +3 -3
  37. package/{index-hxg6ctk2.js → index-a2a3nh57.js} +3 -3
  38. package/{index-j2wq064m.js → index-aezpcphy.js} +121 -15
  39. package/{index-3r1crbct.js → index-ay4vkwr8.js} +1 -1
  40. package/{index-t23dgyaf.js → index-b4m7bjbx.js} +7 -7
  41. package/{index-rdcgz02t.js → index-bma8tmgb.js} +4 -4
  42. package/{index-3zkhg65e.js → index-c4g8egm2.js} +40 -13
  43. package/{index-9gjcbp2g.js → index-c8kj74zz.js} +1 -1
  44. package/{index-fjqapyex.js → index-es2wkn41.js} +40 -5
  45. package/{index-pyjkbg8e.js → index-extg77rx.js} +2 -2
  46. package/{index-nmdmkjt2.js → index-fey1dd49.js} +4 -4
  47. package/{index-c669pbyb.js → index-fjzeak0t.js} +68 -37
  48. package/{index-f4jydw2x.js → index-gdgbgn82.js} +1 -1
  49. package/{index-4yvtqcme.js → index-gyyscjzx.js} +16 -4
  50. package/{index-qecrqpt6.js → index-hxcefw29.js} +1 -1
  51. package/{index-a4gcdffy.js → index-k380ww64.js} +3 -3
  52. package/index-kqxs1d7z.js +377 -0
  53. package/{index-nnmw56fz.js → index-mv3ke0fc.js} +5 -5
  54. package/{index-m303nhv6.js → index-mvdmb73w.js} +6 -6
  55. package/{index-cbm9gzgx.js → index-pa53zktp.js} +5 -5
  56. package/{index-3a3vy2xy.js → index-psvxwemh.js} +8 -8
  57. package/{index-ckcc9ab3.js → index-r24mj2pw.js} +8 -8
  58. package/{index-8bta5pnr.js → index-serpfvat.js} +2 -2
  59. package/{index-kbnvyhy4.js → index-shjjjdte.js} +3 -3
  60. package/{index-pr9nypg7.js → index-sjmk7wp7.js} +2 -2
  61. package/{index-wkwe91sn.js → index-th7qbjfz.js} +11 -11
  62. package/{index-5ahe641t.js → index-vgd07z61.js} +8 -8
  63. package/{index-crd99zqs.js → index-wzvvqkcy.js} +1 -1
  64. package/{index-v16gj2as.js → index-ys1sjp6m.js} +90 -51
  65. package/{index-22bwg8hy.js → index-zc43cyg8.js} +1 -1
  66. package/index.js +27 -27
  67. package/{libExecutor-n8hpm8s7.js → libExecutor-mqxnn0h6.js} +2 -2
  68. package/{library.command-8abb26pg.js → library.command-4kefxh8z.js} +7 -7
  69. package/{localRegistry.command-sa211m1z.js → localRegistry.command-phgrhkks.js} +18 -17
  70. package/{module.command-z3cwjf0p.js → module.command-8476gwze.js} +9 -9
  71. package/{package.command-akynhtee.js → package.command-ygxm5pp9.js} +8 -8
  72. package/package.json +2 -2
  73. package/{page.command-3fpdavk9.js → page.command-f7fwkj8y.js} +7 -7
  74. package/{pipeline.command-ca95n8rd.js → pipeline.command-9htjbrdm.js} +6 -6
  75. package/{pkgExecutor-a73q41vx.js → pkgExecutor-6a91xng5.js} +2 -2
  76. package/{primitive.command-xwe9ggnf.js → primitive.command-0k0h0cm0.js} +10 -10
  77. package/{projectTypecheck-7g542ymk.js → projectTypecheck-7kakbacs.js} +1 -1
  78. package/{quality.command-7wz7y8z1.js → quality.command-frsfdfc5.js} +9 -8
  79. package/{repair.command-dej1qtfq.js → repair.command-yag3bpq2.js} +9 -9
  80. package/{scalar.command-z9qfxnvm.js → scalar.command-qtyrywvt.js} +8 -8
  81. package/skills/akan-runtime/SKILL.md +20 -0
  82. package/{subspace.command-9wekm4gn.js → subspace.command-kr53abzt.js} +10 -10
  83. package/{tunnel.command-cxc4h3j8.js → tunnel.command-pswe6nye.js} +9 -9
  84. package/{typeChecker-7jt6abrs.js → typeChecker-epg7ebfy.js} +2 -1
  85. package/typecheck.proc.js +2 -1
  86. package/{verify.command-j0w9dr5c.js → verify.command-ghhhzgrw.js} +15 -14
  87. package/{workflow.command-yt4sz04b.js → workflow.command-fpwqth4w.js} +14 -14
  88. package/{workspace.command-8mp4mcp2.js → workspace.command-6bbmtn3w.js} +33 -31
  89. package/TunnelShare-0p4dy89e.js +0 -16
  90. package/cloud.script-0dsyd10v.js +0 -30
  91. package/context.runner-yyp7a112.js +0 -32
@@ -2,35 +2,35 @@
2
2
  import {
3
3
  Workspace,
4
4
  command
5
- } from "./index-nnmw56fz.js";
5
+ } from "./index-mv3ke0fc.js";
6
6
  import"./index-j4yvgfhr.js";
7
- import"./index-v16gj2as.js";
7
+ import"./index-ys1sjp6m.js";
8
8
  import"./index-zyjztrvc.js";
9
- import"./index-9a9t77hz.js";
10
- import"./index-yey1envc.js";
11
- import"./index-crd99zqs.js";
12
- import"./index-q63nbpv7.js";
9
+ import"./index-77627y32.js";
10
+ import"./index-741xbhes.js";
11
+ import"./index-wzvvqkcy.js";
12
+ import"./index-0zkxsdsg.js";
13
13
  import"./index-trffs83s.js";
14
- import"./index-h8w1n11r.js";
14
+ import"./index-6a3rmwxx.js";
15
15
  import"./index-1p81ecbz.js";
16
- import"./index-5ahe641t.js";
16
+ import"./index-vgd07z61.js";
17
17
  import"./index-j3fqs8rc.js";
18
- import"./index-fjqapyex.js";
19
- import"./index-f4jydw2x.js";
18
+ import"./index-es2wkn41.js";
19
+ import"./index-gdgbgn82.js";
20
20
  import"./index-m9jj544v.js";
21
21
  import"./index-zyb0ebm4.js";
22
22
  import"./index-xs9a3ddt.js";
23
- import"./index-kbnvyhy4.js";
24
- import"./index-9gjcbp2g.js";
25
- import"./index-rdcgz02t.js";
26
- import"./index-m303nhv6.js";
27
- import"./index-fagjtk6m.js";
23
+ import"./index-shjjjdte.js";
24
+ import"./index-c8kj74zz.js";
25
+ import"./index-bma8tmgb.js";
26
+ import"./index-mvdmb73w.js";
27
+ import"./index-3q7ectss.js";
28
28
  import"./index-t4d0ckde.js";
29
- import"./index-3a3vy2xy.js";
29
+ import"./index-psvxwemh.js";
30
30
  import {
31
31
  ContextScript
32
- } from "./index-vnk1qwgr.js";
33
- import"./index-3r1crbct.js";
32
+ } from "./index-22h6vq3f.js";
33
+ import"./index-ay4vkwr8.js";
34
34
 
35
35
  // pkgs/@akanjs/cli/context/context.command.ts
36
36
  class ContextCommand extends command("context", [ContextScript], ({ public: target }) => ({
@@ -0,0 +1,32 @@
1
+ // @bun
2
+ import {
3
+ ContextRunner2
4
+ } from "./index-vgd07z61.js";
5
+ import"./index-psvxwemh.js";
6
+ import"./index-3q7ectss.js";
7
+ import"./index-mvdmb73w.js";
8
+ import"./index-shjjjdte.js";
9
+ import"./index-bma8tmgb.js";
10
+ import"./index-c8kj74zz.js";
11
+ import"./index-t4d0ckde.js";
12
+ import"./index-6a3rmwxx.js";
13
+ import"./index-0zkxsdsg.js";
14
+ import"./index-j3fqs8rc.js";
15
+ import"./index-gdgbgn82.js";
16
+ import"./index-es2wkn41.js";
17
+ import"./index-m9jj544v.js";
18
+ import"./index-mv3ke0fc.js";
19
+ import"./index-xs9a3ddt.js";
20
+ import"./index-zyb0ebm4.js";
21
+ import"./index-trffs83s.js";
22
+ import"./index-ay4vkwr8.js";
23
+ import"./index-77627y32.js";
24
+ import"./index-741xbhes.js";
25
+ import"./index-wzvvqkcy.js";
26
+ import"./index-ys1sjp6m.js";
27
+ import"./index-j4yvgfhr.js";
28
+ import"./index-1p81ecbz.js";
29
+ import"./index-zyjztrvc.js";
30
+ export {
31
+ ContextRunner2 as ContextRunner
32
+ };
@@ -1,8 +1,8 @@
1
1
  // @bun
2
2
  import {
3
3
  CsrArtifactBuilder2
4
- } from "./index-pr9nypg7.js";
5
- import"./index-3mj5trqc.js";
4
+ } from "./index-sjmk7wp7.js";
5
+ import"./index-0bzrcv91.js";
6
6
  import"./index-zyjztrvc.js";
7
7
  export {
8
8
  CsrArtifactBuilder2 as CsrArtifactBuilder
@@ -2,17 +2,17 @@
2
2
  import {
3
3
  script,
4
4
  command
5
- } from "./index-nnmw56fz.js";
5
+ } from "./index-mv3ke0fc.js";
6
6
  import"./index-j4yvgfhr.js";
7
- import"./index-v16gj2as.js";
7
+ import"./index-ys1sjp6m.js";
8
8
  import"./index-zyjztrvc.js";
9
- import"./index-9a9t77hz.js";
10
- import"./index-yey1envc.js";
11
- import"./index-crd99zqs.js";
9
+ import"./index-77627y32.js";
10
+ import"./index-741xbhes.js";
11
+ import"./index-wzvvqkcy.js";
12
12
  import {
13
13
  Prompter2
14
14
  } from "./index-j3fqs8rc.js";
15
- import"./index-3r1crbct.js";
15
+ import"./index-ay4vkwr8.js";
16
16
 
17
17
  // pkgs/@akanjs/cli/guideline/guideline.script.ts
18
18
  import { Logger } from "akanjs/common";
@@ -22,6 +22,11 @@ contract: `runtimeRule`.
22
22
  - The generated Docker image installs only `ca-certificates` and `tzdata` (add the rest in `docker.preRuns`) and
23
23
  runs the server as uid 1000 (`bun`) after its root build steps.
24
24
  - An app running in two database modes avoids `q.raw`.
25
+ - **`akan build` leaves the server env's secrets out of the image**: a string under a secret-named key (password,
26
+ secret, token, apiKey, privateKey, …) or a URL carrying a password in `env/env.server.<env>.ts` is read at boot
27
+ from a variable named after its key path, which the deployment sets (`akan secret-env <app> --env <env>` lists
28
+ them). A secret the file computes or imports stops the build: write the string at the key, or
29
+ `process.env.<NAME>` there.
25
30
  - Give every log sink a floor (`Logger.addSink(sink, { minLevel })`), and never log per delivered record in anything
26
31
  that delivers records.
27
32
  - **A desktop app's carried server listens on a loopback port any local program can call** — guard it as a network
@@ -22,6 +22,9 @@ apps, heads, CSR root layouts, lib pages, `devOnly`: `pageRule`.
22
22
  receives it.
23
23
  - `.head()` takes JSX or a function returning it — never a metadata object; deeper heads replace by tag identity,
24
24
  and a canonical link / `og:url` comes only from the page's own `.head()`.
25
+ - An inline `<script>` in a `.head()` is named in the page's script policy, reported now and refused from 3.5.0:
26
+ `scriptHashes("sha256-…")` for a constant snippet (the page stays cacheable), `nonce={scriptNonce()}` for anything
27
+ else (the page turns dynamic); both from `akanjs/client`, called in the `.head()`.
25
28
  - In a CSR bundle a root layout's own markup is hidden: what a person must see from it renders through
26
29
  `createPortal(…, document.body)`.
27
30
  - `libs/<lib>/page` reaches an app through `syncPageLibs`, linked into the generated `page/(libs)/(<lib>)`; edit the
@@ -23,6 +23,7 @@ Generated from the akanjs sources of this release: every code a framework error
23
23
  | `badRequest` | 400 | `Exception.BadRequest` | yes | no | `signal/exception.ts` |
24
24
  | `badRequest` | 400 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
25
25
  | `baseMismatch` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
26
+ | `browserError` | 500 | `BrowserError` | no | yes | `signal/browserError.ts` |
26
27
  | `buildFailed` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
27
28
  | `builderUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
28
29
  | `bytesThroughAny` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
@@ -84,6 +85,7 @@ Generated from the akanjs sources of this release: every code a framework error
84
85
  | `missingModel` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
85
86
  | `missingSlice` | 500 | `SignalDeclarationError` | no | yes | `signal/signalDeclarationError.ts` |
86
87
  | `noHandler` | 500 | `SignalContractError` | no | yes | `signal/signalContractError.ts` |
88
+ | `nonErrorThrown` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
87
89
  | `notApplied` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
88
90
  | `notFound` | 404 | `Exception.NotFound` | yes | no | `signal/exception.ts` |
89
91
  | `notFound` | 404 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
@@ -119,6 +121,7 @@ Generated from the akanjs sources of this release: every code a framework error
119
121
  | `rscWorkerStopped` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
120
122
  | `searchMisconfigured` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
121
123
  | `searchUnavailable` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
124
+ | `secretEnvInvalid` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
122
125
  | `secretRefused` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
123
126
  | `secretStoreUnavailable` | 503 | `AkanError` | no | yes | `base/akanError.ts` |
124
127
  | `serviceUnavailable` | 503 | `ImageOptimizerError` | no | yes | `server/imageOptimizerError.ts` |
@@ -145,6 +148,7 @@ Generated from the akanjs sources of this release: every code a framework error
145
148
  | set when thrown | set when thrown | `Err.Forbidden` | yes | yes | `common/err.ts` |
146
149
  | set when thrown | set when thrown | `Err.NotFound` | yes | yes | `common/err.ts` |
147
150
  | set when thrown | set when thrown | `Err.Unauthorized` | yes | yes | `common/err.ts` |
151
+ | set when thrown | 500 | `ForwardedError` | no | yes | `server/forwardedError.ts` |
148
152
 
149
153
  ## Codes by status
150
154
 
@@ -85,6 +85,25 @@ typed params and search, loading, 404 and error views, Link and the router. Befo
85
85
  `<meta name="theme-color">` a `.head()` writes replaces the root `.viewport({ themeColor })`'s. Only `.head()`
86
86
  merges: a `<title>` or `<meta>` written inside a component renders beside the merged head, so a second `<title>`
87
87
  can reach the document.
88
+ - **An inline `<script>` a `.head()` writes has to be named in the page's script policy.** Every HTML response sends
89
+ `Content-Security-Policy-Report-Only: script-src … 'strict-dynamic'`, which 3.5.0 enforces: an inline script runs by
90
+ its hash or by the response's nonce, and a `<script src>` in JSX by the nonce (its host in a policy does nothing
91
+ under `'strict-dynamic'`). For a constant snippet call `scriptHashes("sha256-…")` in the `.head()` — the page stays
92
+ cacheable, and the hash is the one the browser prints in its console report. For text that differs per request, or
93
+ a script loaded by URL, pass `nonce={scriptNonce()}`; reading it makes the page dynamic, so no result cache keeps
94
+ it. Both come from `akanjs/client`, do nothing in the browser, and are too late outside a `.head()`: the header
95
+ leaves with the first byte. An `onclick="…"` attribute and a `javascript:` URL have no such form.
96
+ `AKAN_CONTENT_SECURITY_POLICY_REPORT_ONLY=off` drops the header, `AKAN_CONTENT_SECURITY_POLICY_REPORT_URI` names
97
+ where the browser posts reports, and `AKAN_CONTENT_SECURITY_POLICY_SCRIPT_SRC` adds sources to every response
98
+ (`'wasm-unsafe-eval'` for a page that compiles WebAssembly).
99
+ A response names at most 32 hashes (its header stays under 2 KB, inside the 4 KB a proxy reads headers into):
100
+ `scriptHashes()` past that are left out with one warning per route, and a page whose cached replay would need more
101
+ (one per streamed boundary) is rendered each time, answering `X-Akan-Cache-Reason: script-hashes`.
102
+ - **`load` and `DOMContentLoaded` can fire before client code runs.** The client entry is a module the document's
103
+ bootstrap script adds, not a tag in the markup, so neither event waits for it. A listener for either is added only
104
+ after checking `document.readyState` (`"complete"` for `load`, not `"loading"` for `DOMContentLoaded`) and calling
105
+ the handler directly when it already holds. A browser test waits for what the hydrated page does (the result of
106
+ its action, or a marker a client component sets in an effect), never for navigation's `load`.
88
107
 
89
108
  ## A Root Layout Inside A CSR Bundle
90
109
 
@@ -66,9 +66,9 @@ const config: AppConfig = { api: { prefix: "/backend", websocketPrefix: "/socket
66
66
  inside it can reach a prebuilt bundle at all. The two jobs need two names.
67
67
  - **`new AkanApp({ prefix })` reaches the browser through the page, not through a prop.** `FetchClient` fixes its
68
68
  origin when the module graph initializes, before any component renders, so a React prop — a `System.Provider`
69
- value, anything out of `implicitRootLayout` — is always too late. The value rides the SSR classic bootstrap
70
- script instead, the one thing guaranteed to run ahead of every module script, and is omitted when it matches
71
- what the bundle already assumes. `akan.config.ts` is what a native app bundle or a statically served CSR shell
69
+ value, anything out of `implicitRootLayout` — is always too late. The value rides the data block the SSR classic
70
+ bootstrap script reads instead, the one thing guaranteed to run ahead of every module script, and is omitted when
71
+ it matches what the bundle already assumes. `akan.config.ts` is what a native app bundle or a statically served CSR shell
72
72
  follows, because neither is rendered by a server that could tell it otherwise.
73
73
  - **A prefix is a path segment.** A blank value or a bare `/` is refused: `/` would be mounted ahead of the SSR
74
74
  catch-all and swallow every page route. A prefix whose first segment is a declared basePath is refused at
@@ -137,6 +137,13 @@ worker per web-serving replica.
137
137
  `infra/app` chart adds the `prometheus.io/*` scrape annotations with `<branch>.metrics.scrape: true` and reads the
138
138
  token from the Secret `<branch>.metrics.tokenSecret` names, and refuses to render `scrape` without it;
139
139
  `infra/monitoring` holds a Grafana dashboard and the alert rules.
140
+ - **Each SQL statement is timed once, where its driver sends it**; the `db:` spans, the `akan_db_statement*` series
141
+ (labels `model`, `op`; the SQLite write-turn or Postgres pool wait apart) and the slow log read that
142
+ point. A fingerprint hashes the text with literals `?` and lists collapsed; the text sent never changes.
143
+ `/_akan/app/statements` (metrics token) ranks statements by total time and p95 with their senders.
144
+ `AKAN_LOG_SLOW_STATEMENT_MS` (200, `off`) logs one `SlowStatement` warn per fingerprint a minute; a local dev run
145
+ warns once (`QueryPlan`) of a full scan or temp sort, silenced per fingerprint by `AKAN_QUERY_PLAN_IGNORE`.
146
+ `akan_room_replay_bytes` and `akan_pubsub_buffered_messages` gauge the reconnect replay and the Redis buffer.
140
147
  - **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
141
148
  with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
142
149
  - **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
@@ -188,13 +195,16 @@ worker per web-serving replica.
188
195
  and neither does a save in a sibling app. An import that makes a new lib a dependency needs a fresh
189
196
  `akan start`, because it needs a `sync` first anyway. Before the first `sync` the manifests do not exist yet and
190
197
  the whole `libs/` container is watched, which is the safe direction.
191
- - **A built artifact runs from the generated app directory, without Docker and without an env.** `akan build`
198
+ - **A built artifact runs from the generated app directory, without Docker.** `akan build`
192
199
  writes `akan.env.json` beside `main.js` with the values the Dockerfile's `ENV` lines set, and `main.js` takes
193
200
  each one the process was not started with, so a variable you set (or the image's `ENV`) wins. Start it from that
194
- directory: the runtime reads its artifacts and writes `runtime/` and SQLite files relative to the cwd.
201
+ directory: the runtime reads its artifacts and writes `runtime/` and SQLite files relative to the cwd. The secrets
202
+ of its server env are not in it (see "Server Env Secrets" below): give them in the env, or it warns and runs
203
+ without them.
195
204
 
196
205
  ```bash
197
206
  cd dist/apps/<appName> && PORT=3100 bun main.js
207
+ cd dist/apps/<appName> && bun --env-file=/path/outside/dist/<appName>.env main.js
198
208
  ```
199
209
 
200
210
  - **A server a test boots in-process takes `start({ listen: false, schedules: false })`** to run no internal
@@ -231,6 +241,16 @@ normalized to `info` with one warning.
231
241
  render message, a server-side `fetch` sends `traceparent` to the app's own server and to a `clone({ origin })`,
232
242
  every websocket frame is a span under its handshake's id, and a queued job is a trace of its own that links the
233
243
  enqueuing one.
244
+ - **Errors to a tracker go through `option.setErrorReporter(fn)`**, never a `Logger` sink parsing lines. It gets each
245
+ server 5xx (never a 4xx), render error, uncaught exception and unhandled rejection as a real `Error`, once, after
246
+ the response, with `{ source, traceId, endpoint, routeId, accountId, digest }`, in the solo server or the replica
247
+ (a worker's render error is carried to it; the gateway reports none). Reports of one request share `traceId`. A
248
+ process hands it at most 600 errors a minute, 10 of them process errors, and 3 render errors a request, so `await`
249
+ what the reporter sends: an unawaited send that fails returns as an unhandled rejection. `option.setClientReport({
250
+ sampleRate })`, off unless set, adds what pages hit in the browser as a `BrowserError` through
251
+ `/_akan/client-report`: a report is taken only with the signed id the page's `Server-Timing` gave that page view,
252
+ for 30 to 60 minutes and five times, and its text is cleaned of query strings, email addresses and credentials. With
253
+ more than one gateway or pod, set `AKAN_CLIENT_REPORT_KEY` (a secret, 32+ characters, the same on each) so each takes the others' ids.
234
254
  - **Not everything carries context, by design.** The primitive query fast path (an unauthenticated GET of a
235
255
  primitive with no args, guards or middlewares) skips it; the schedule adaptor's own `started/finished/error`
236
256
  lines wrap the traced handler from outside; gateway lines written outside a request have none. `akan logs
@@ -268,7 +288,17 @@ normalized to `info` with one warning.
268
288
  `AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace`, records its spans and answers with
269
289
  `Server-Timing` — under the local dev runtime, or with the `AKAN_LOG_DEBUG_HEADER` secret. A local runtime sends
270
290
  `Server-Timing` on every signal response. Spans carry ids, parents and start offsets; under `AKAN_TRACE=1` each
271
- database call is a `db:<model>.<op>` span, never its statement or values.
291
+ SQL statement sent is a `db:<model>.<op>` span, never its text or values.
292
+ - **`OTEL_EXPORTER_OTLP_ENDPOINT` (or `…_TRACES_ENDPOINT` / `…_LOGS_ENDPOINT`) turns on OTLP/HTTP JSON export**;
293
+ with none set nothing is created. Each process sends its own spans and log records with `akan.process.role`, the
294
+ RSC worker included, batched in a bounded queue that drops its oldest and never blocks or throws into a request.
295
+ `OTEL_TRACES_SAMPLER` (`always_on`, `always_off`, `traceidratio` and their `parentbased_` forms, default
296
+ `parentbased_always_on`; any other value exports no spans) decides at the first TCP hop, and the sampled flag of
297
+ `traceparent` carries it to the replica and the worker. Logs go only with `OTEL_LOGS_EXPORTER=otlp` or
298
+ `…_LOGS_ENDPOINT`, never from the generic endpoint alone, their message text as written; only secret-named attrs are
299
+ redacted. Stage spans wait for `AKAN_TRACE=1`. `OTEL_EXPORTER_OTLP_HEADERS` values are credentials, never
300
+ logged; `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` and `OTEL_SDK_DISABLED` work as in the OTel spec. It is
301
+ separate from `AKAN_TRACE` and `x-akan-debug`: neither changes what is sampled.
272
302
  - **Every dev route is listed once, in `akanjs/server/routing/devSurfaces`** — devtools, Studio, `/_akan/hmr`,
273
303
  the ssr-dev and csr-dev module registries, `/__rsc/manifest` — and is mounted through `DevRoutes.mount`, which
274
304
  refuses a path the list lacks. Each answers only localhost, an IP address, the app's own hosts and
@@ -324,6 +354,79 @@ const config: AppConfig = { docker: "FROM oven/bun:1.4.4-slim\n…" }; // verbat
324
354
  - `AkanAppConfig.docker` is the resolved declaration; `AkanAppConfig.dockerfile` is the text `akan build` writes
325
355
  to `dist/apps/<app>/Dockerfile`.
326
356
 
357
+ ## Server Env Secrets — Read From The Process Env
358
+
359
+ `akan build <app>` puts no secret value of the server env into the server it builds. The env file stays the one
360
+ place a developer writes them; the build turns each into a read of an environment variable the deployment sets.
361
+
362
+ - **What is a secret.** A string under a secret-named key at any depth below it, unless blank, or a URL carrying a
363
+ password or a secret-named query parameter. The names are the ones the logger masks: `password`, `pass`, `pwd`,
364
+ `token`, `jwt`, `secret`, `cookie`, `authorization`, `apiKey`, `aesKey`, `privateKey`, `accessKey`, `authKey`,
365
+ `hashKey`, a signing, encryption, master or session key, `webhook`, `credential`, a `dsn`, a connection string,
366
+ `iapVerify`, `serviceAccount`, `cred(s)`. Numbers, booleans and `null` never are. The rule over-matches
367
+ (`cookieDomain`, `tokenTtl` as a string), which only means the deployment sets that value too; it misses a key such
368
+ as `stripeKey` or `salt`, which stays in the build unless the env file reads `process.env.<NAME>` itself.
369
+ - **Its variable** is its key path, each key in upper snake case and joined with `__`:
370
+ `security.sso.google.clientSecret` is `SECURITY__SSO__GOOGLE__CLIENT_SECRET`, `iapVerify.google.private_key` is
371
+ `IAP_VERIFY__GOOGLE__PRIVATE_KEY`. Four keep the names the framework already reads ahead of the env file:
372
+ `security.jwtSecret` is `JWT_SECRET`, `database.postgres.url` is `POSTGRES_URL` (`POSTGRES_URI` satisfies it),
373
+ `database.postgres.password` is `POSTGRES_PASSWORD`, `database.postgres.insightUrl` is `POSTGRES_INSIGHT_URL`.
374
+ An array holding a secret moves whole into one variable holding JSON (`discord.tokens` is `DISCORD__TOKENS`,
375
+ `["a","b"]`). An object is never one variable: each secret string in it is its own. A multi-line value (a PEM key)
376
+ is carried with its real line breaks.
377
+ - **What the build rewrites** is source text: a string literal that is the value of a key in the object
378
+ `export const env` holds, in the app's `env.server.<env>.ts`, in `env.server.ts` itself where a pipeline copies an
379
+ env file over it, and in each lib's `env.server.<name>.ts`. In `process.env.MY_URL ?? "literal"` only the literal
380
+ becomes the read, so the developer's own variable comes first. Two keys that map to one name (`apiKey` and
381
+ `api_key`), and a name the platform or akan owns (`PATH`, `HOME`, `HOSTNAME`, `PORT`, `USER`, `PWD`, `TZ`,
382
+ `NODE_ENV`, `AKAN_*`, `BUN_*`), stop the build before it starts.
383
+ - **What stops a build.** Before any phase the build loads the env file with each literal marked, to list the
384
+ variables and to see what it cannot move. A secret-named key whose value is computed, imported or spread from
385
+ another file stops it there, whatever the value's length or shape, naming the app, the env file and the keys:
386
+ write the string at the key, or `process.env.<NAME>`. A key the env file reads from `process.env` itself is the
387
+ developer's own: it is not moved, never stops the build, and the bundle holds the read and no value, set in the
388
+ build's shell or not. After the bundles are written the build looks in `dist/apps/<app>` for each secret string it
389
+ left out, eight characters or longer: a long mixed one found there stops the build, naming its key, its variable
390
+ and a plain key of the env that holds it too; a short or plain one (a password equal to a database's name) is a
391
+ warning by the same names, as is a shorter string a plain key holds as well. No message prints a value.
392
+ - **How the env file is loaded.** In a process with `PATH`, `HOME` and `AKAN_PUBLIC_ENV` alone, so the list is the
393
+ same from any shell and `process.env.X ?? fallback` reads as the fallback the bundle carries. A file that cannot
394
+ load so (`process.env.HOSTS!.split(",")`) is loaded again with the build shell's variables, where a value a
395
+ variable gave counts as the developer's read. One that loads neither way stops the build with the error's class
396
+ and its file and line, never its message, which could quote a value; loading has a 60 second limit, and a file
397
+ that leaves a timer or a server open still ends when its answer is in.
398
+ - **What the image carries** is the list: `AKAN_ENV_NAMES` in `akan.env.json` and the Dockerfile, names with
399
+ `:json` or `:multiline` after an array or a multi-line value, never a value. The build prints the names.
400
+ - **At boot**, in `AkanApp.start` before the server is loaded or a replica is spawned, the list is compared with the
401
+ process env. A variable not set, or set empty, is one warning naming every such variable. The framework does not
402
+ stop for it, and what reads the value gets `undefined` and may stop (an app that requires its
403
+ JWT secret does); version 3.5.0 will refuse to boot. A `:json` variable that does not parse as an
404
+ array is refused (`secretEnvInvalid`). A `:multiline` variable holding a backslash and an n in place of its line
405
+ breaks is warned about by name. No message carries a value. `bun console.js` and `bun main.js ops …` do not
406
+ check.
407
+ - **`akan secret-env <app> [--env <env>]`** lists each variable with its kind, whether the shell sets it, and its key
408
+ in the env file. `--out <file>` writes the values the env file evaluates to: `--format k8s` (the default) a
409
+ `kind: Secret` with base64 `data`, named by `--name` (default `<app>-env`); `--format dotenv` `NAME=value` lines
410
+ quoted so that Bun's loader reads each back unchanged. The file is created readable by its user alone. A path
411
+ under `dist/`, a path git would track and an existing file (without `--force`) are refused. The file holds the
412
+ secrets: apply or import it, then delete it.
413
+ - **Giving the server its variables.** Kubernetes: apply the Secret and name it in the container's `envFrom`; a
414
+ Secret that is missing stops the container before boot. Docker: `-e NAME=value`; `docker run --env-file` takes
415
+ each line as written, so of the dotenv file it reads the unquoted values and no quoted or multi-line one.
416
+ A host: `bun --env-file=<file> main.js`, with the file outside `dist/apps/<app>`, which an image copies whole.
417
+ Every replica and the RSC worker inherit the gateway's env, so a changed Secret reaches a pod only when it
418
+ restarts.
419
+ - **`akan build <app> --inline-secrets`** keeps each value in the build as what its read falls back to, for a
420
+ deployment that does not set the variables yet; a variable that is set still wins, the boot warning says the
421
+ built-in values are in use, and nothing above stops it: a computed or imported secret stays, the files written are
422
+ not searched, and an env file that cannot be loaded is a warning, after which the env files are bundled as
423
+ written and no variable is read. Version 3.5.0 removes the flag.
424
+ - **Read as written, as before:** `akan start` and `akan test` (the env file is imported from source), a
425
+ `--profile` build (its profile file may hold no secret at all), and the server a desktop or mobile build carries.
426
+ - **Not covered:** a key file an env value names by path (`security.sso.apple.keyFilePath` under `private/`) ships
427
+ with `private/`; mount it instead. Images built before 3.4.0 still hold the values: rotate the secrets once the
428
+ new images are live.
429
+
327
430
  ## Native Apps — The `native` Section
328
431
 
329
432
  An app's iOS, Android and desktop (macOS, Windows, Linux) apps are the `native` section of its `akan.config.ts`.
@@ -3,21 +3,21 @@ import"./index-zyjztrvc.js";
3
3
  import {
4
4
  CodegenLock,
5
5
  WorkspaceExecutor
6
- } from "./index-v16gj2as.js";
6
+ } from "./index-ys1sjp6m.js";
7
7
  import"./index-j4yvgfhr.js";
8
8
  import {
9
9
  HmrWatcher,
10
10
  WatchRootResolver,
11
11
  ApplicationBuildReporter
12
- } from "./index-8bta5pnr.js";
12
+ } from "./index-serpfvat.js";
13
13
  import {
14
14
  AppExecutor2
15
- } from "./index-9a9t77hz.js";
16
- import"./index-yey1envc.js";
17
- import"./index-crd99zqs.js";
15
+ } from "./index-77627y32.js";
16
+ import"./index-741xbhes.js";
17
+ import"./index-wzvvqkcy.js";
18
18
  import {
19
19
  ServerGraphFile
20
- } from "./index-3mj5trqc.js";
20
+ } from "./index-0bzrcv91.js";
21
21
  import {
22
22
  GraphClientEntryDiscovery,
23
23
  RouteClientBuilder,
@@ -27,7 +27,7 @@ import {
27
27
  DevChangePlanner,
28
28
  DevGeneratedIndexSync,
29
29
  SsrDevBundler
30
- } from "./index-4yvtqcme.js";
30
+ } from "./index-gyyscjzx.js";
31
31
  import"./index-trffs83s.js";
32
32
  import {
33
33
  FrameworkGraph2
@@ -41,7 +41,7 @@ import {
41
41
  import {
42
42
  prepareDevWatchBatch
43
43
  } from "./index-a5vmm6x4.js";
44
- import"./index-3r1crbct.js";
44
+ import"./index-ay4vkwr8.js";
45
45
 
46
46
  // pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts
47
47
  import path6 from "path";
@@ -3,7 +3,7 @@ import {
3
3
  AsyncDefaultExportDetector,
4
4
  StoreBootstrap,
5
5
  resolveSsrPageEntriesForApp
6
- } from "./index-9a9t77hz.js";
6
+ } from "./index-77627y32.js";
7
7
  import {
8
8
  FileSys2
9
9
  } from "./index-zyjztrvc.js";
@@ -1,10 +1,10 @@
1
1
  // @bun
2
2
  import {
3
3
  AppExecutor2
4
- } from "./index-9a9t77hz.js";
4
+ } from "./index-77627y32.js";
5
5
  import {
6
6
  LibExecutor2
7
- } from "./index-yey1envc.js";
7
+ } from "./index-741xbhes.js";
8
8
  import {
9
9
  createAst,
10
10
  AkanIndex
@@ -15,7 +15,7 @@ import {
15
15
  } from "./index-va90m8nd.js";
16
16
  import {
17
17
  camelToKebabCase
18
- } from "./index-nnmw56fz.js";
18
+ } from "./index-mv3ke0fc.js";
19
19
 
20
20
  // pkgs/@akanjs/devkit/workflow/artifacts.ts
21
21
  import { capitalize as capitalize2 } from "akanjs/common";
@@ -3,29 +3,32 @@ import {
3
3
  parseBiomeReport,
4
4
  Linter,
5
5
  ProjectTypecheck2
6
- } from "./index-v16gj2as.js";
6
+ } from "./index-ys1sjp6m.js";
7
7
  import {
8
8
  TypecheckFailure
9
9
  } from "./index-j4yvgfhr.js";
10
10
  import {
11
11
  ApplicationBuildReporter
12
- } from "./index-8bta5pnr.js";
12
+ } from "./index-serpfvat.js";
13
13
  import {
14
14
  AppExecutor2
15
- } from "./index-9a9t77hz.js";
15
+ } from "./index-77627y32.js";
16
16
  import {
17
17
  LibExecutor2
18
- } from "./index-yey1envc.js";
18
+ } from "./index-741xbhes.js";
19
19
  import {
20
20
  PkgExecutor2
21
- } from "./index-crd99zqs.js";
21
+ } from "./index-wzvvqkcy.js";
22
22
  import {
23
23
  WorkspaceRunner,
24
24
  AkanQualityScanner
25
- } from "./index-j2wq064m.js";
25
+ } from "./index-aezpcphy.js";
26
+ import {
27
+ WithheldEnvFile
28
+ } from "./index-35p43f33.js";
26
29
  import {
27
30
  VerifyScope
28
- } from "./index-wkwe91sn.js";
31
+ } from "./index-th7qbjfz.js";
29
32
 
30
33
  // pkgs/@akanjs/cli/verify/verifyComments.ts
31
34
  import { existsSync } from "fs";
@@ -205,7 +208,6 @@ import path5 from "path";
205
208
  // pkgs/@akanjs/cli/verify/verifyDiagnostics.ts
206
209
  import { readFileSync } from "fs";
207
210
  import path2 from "path";
208
-
209
211
  class VerifyDiagnostics {
210
212
  static fromTypecheck(records) {
211
213
  return records.map((record) => {
@@ -248,7 +250,7 @@ class VerifyDiagnostics {
248
250
  col: diagnostic.location?.start?.column ?? 0,
249
251
  code: diagnostic.category ?? "biome",
250
252
  severity: diagnostic.severity === "error" ? "error" : "warning",
251
- ...VerifyDiagnostics.#adapterErrorOf(file, diagnostic.message) ?? VerifyDiagnostics.#deepImportOf(root, file, diagnostic) ?? { message: diagnostic.message }
253
+ ...WithheldEnvFile.isEnvFile(file ?? undefined) ? { message: WithheldEnvFile.note } : VerifyDiagnostics.#adapterErrorOf(file, diagnostic.message) ?? VerifyDiagnostics.#deepImportOf(root, file, diagnostic) ?? { message: diagnostic.message }
252
254
  };
253
255
  });
254
256
  }
@@ -1,16 +1,16 @@
1
1
  // @bun
2
2
  import {
3
3
  script
4
- } from "./index-nnmw56fz.js";
4
+ } from "./index-mv3ke0fc.js";
5
5
  import {
6
6
  jsonText
7
- } from "./index-q63nbpv7.js";
7
+ } from "./index-0zkxsdsg.js";
8
8
  import {
9
9
  akanMcpInstallTargets
10
- } from "./index-h8w1n11r.js";
10
+ } from "./index-6a3rmwxx.js";
11
11
  import {
12
12
  ContextRunner2
13
- } from "./index-5ahe641t.js";
13
+ } from "./index-vgd07z61.js";
14
14
 
15
15
  // pkgs/@akanjs/cli/context/context.script.ts
16
16
  import { Logger } from "akanjs/common";
@@ -0,0 +1,16 @@
1
+ // @bun
2
+ // pkgs/@akanjs/devkit/lint/withheldEnvFile.ts
3
+ class WithheldEnvFile {
4
+ static #name = "env[\\\\/]env\\.(?:server|client)(?:\\.[A-Za-z0-9-]+)*\\.ts";
5
+ static #envFile = new RegExp(`[\\\\/]${WithheldEnvFile.#name}$`);
6
+ static #named = new RegExp(WithheldEnvFile.#name);
7
+ static note = "the text is withheld because this file holds secrets";
8
+ static isEnvFile(fileName) {
9
+ return fileName !== undefined && WithheldEnvFile.#envFile.test(fileName.startsWith("env/") ? `/${fileName}` : fileName);
10
+ }
11
+ static namesEnvFile(text) {
12
+ return WithheldEnvFile.#named.test(text);
13
+ }
14
+ }
15
+
16
+ export { WithheldEnvFile };
@@ -2,12 +2,12 @@
2
2
  import {
3
3
  runner,
4
4
  script
5
- } from "./index-nnmw56fz.js";
5
+ } from "./index-mv3ke0fc.js";
6
6
  import {
7
7
  generatedFilesForSync,
8
8
  createPassedPrimitiveReport,
9
9
  scalarChangedFiles
10
- } from "./index-q63nbpv7.js";
10
+ } from "./index-0zkxsdsg.js";
11
11
  import {
12
12
  pluralizeName
13
13
  } from "./index-nz8prx9g.js";
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  JsonFormatter
4
- } from "./index-v16gj2as.js";
4
+ } from "./index-ys1sjp6m.js";
5
5
 
6
6
  // pkgs/@akanjs/devkit/quality/maintainabilityBaseline.ts
7
7
  class MaintainabilityBaseline {
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  AppInfo
4
- } from "./index-v16gj2as.js";
4
+ } from "./index-ys1sjp6m.js";
5
5
 
6
6
  // pkgs/@akanjs/devkit/workspace/slicePlanner.ts
7
7
  class SlicePlanner {
@@ -8,21 +8,21 @@ import {
8
8
  isScannedRootEntry,
9
9
  extractBlockVersion,
10
10
  readDevkitVersion
11
- } from "./index-v16gj2as.js";
11
+ } from "./index-ys1sjp6m.js";
12
12
  import {
13
13
  FileSys2
14
14
  } from "./index-zyjztrvc.js";
15
15
  import {
16
16
  AppExecutor2
17
- } from "./index-9a9t77hz.js";
17
+ } from "./index-77627y32.js";
18
18
  import {
19
19
  LibExecutor2
20
- } from "./index-yey1envc.js";
20
+ } from "./index-741xbhes.js";
21
21
  import {
22
22
  workflowPathsForPlan,
23
23
  workflowRunArtifactPath,
24
24
  workflowSyncDir
25
- } from "./index-q63nbpv7.js";
25
+ } from "./index-0zkxsdsg.js";
26
26
  import {
27
27
  collectRecipeSources2,
28
28
  scanRecipes2,
@@ -5,7 +5,7 @@ import {
5
5
  SysExecutor,
6
6
  WorkspaceExecutor,
7
7
  AkanLibConfig
8
- } from "./index-v16gj2as.js";
8
+ } from "./index-ys1sjp6m.js";
9
9
 
10
10
  // pkgs/@akanjs/devkit/executors/libExecutor.ts
11
11
  class LibExecutor2 extends SysExecutor {
@@ -7,13 +7,13 @@ import {
7
7
  AkanAppConfig,
8
8
  increaseBuildNum,
9
9
  decreaseBuildNum
10
- } from "./index-v16gj2as.js";
10
+ } from "./index-ys1sjp6m.js";
11
11
  import {
12
12
  FileSys2
13
13
  } from "./index-zyjztrvc.js";
14
14
  import {
15
15
  LibExecutor2
16
- } from "./index-yey1envc.js";
16
+ } from "./index-741xbhes.js";
17
17
 
18
18
  // pkgs/@akanjs/devkit/executors/appExecutor.ts
19
19
  import { cp as cpEntry, lstat, mkdir, readdir as readDirEntries, realpath, rm as rm2, stat, symlink } from "fs/promises";