@akanjs/cli 3.3.0-rc.1 → 3.3.0-rc.11
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.
- package/.build-stamp +2 -2
- package/CodeAgent-cqbf9gsv.js +11 -0
- package/{CodeAgentRpcHost-6dzfkvsc.js → CodeAgentRpcHost-pwps2d67.js} +1 -1
- package/{CodeTui-zee8atsr.js → CodeTui-ehdr4hgw.js} +46 -6
- package/TunnelShare-0p4dy89e.js +16 -0
- package/{agent.command-x65f2ags.js → agent.command-x55ncdjm.js} +20 -22
- package/akanCode.js +7 -7
- package/appExecutor-1ctzymwa.js +11 -0
- package/{application.command-azbd1pb2.js → application.command-xpntxnh8.js} +18 -20
- package/{applicationBuildRunner-trfxv3pd.js → applicationBuildRunner-19c76791.js} +16 -13
- package/buildBatch.proc.js +19 -19
- package/{cloud.command-gapp4634.js → cloud.command-p3ybjes7.js} +19 -24
- package/cloud.script-0dsyd10v.js +30 -0
- package/{code.command-5smx61yf.js → code.command-m6skj1kj.js} +34 -19
- package/{context.command-ym5jbkny.js → context.command-3c3nv0d6.js} +20 -22
- package/context.runner-yyp7a112.js +32 -0
- package/csrArtifactBuilder-mdh9ykn2.js +9 -0
- package/{index-2ny1e95c.js → dependencyScanner-93g8tk0r.js} +6 -5
- package/{fileSys-q22646yc.js → fileSys-e5mwt73x.js} +1 -1
- package/frameworkGraph-aneq2nwy.js +8 -0
- package/{guideline.command-zwypaqsh.js → guideline.command-725fq5p0.js} +8 -8
- package/guidelines/agentRule/agentRule.instruction.md +46 -7
- package/guidelines/akanApi/akanApi.instruction.md +7 -2
- package/guidelines/conventions/core.md +6 -11
- package/guidelines/conventions/rules/app.md +1 -2
- package/guidelines/conventions/rules/auth.md +18 -27
- package/guidelines/conventions/rules/config.md +15 -46
- package/guidelines/conventions/rules/page.md +19 -34
- package/guidelines/conventions/rules/server.md +1 -4
- package/guidelines/conventions/rules/ssr.md +3 -4
- package/guidelines/conventions/rules/ts.md +2 -1
- package/guidelines/cssRule/cssRule.instruction.md +3 -0
- package/guidelines/errorCodes/errorCodes.instruction.md +4 -0
- package/guidelines/mcpRule/mcpRule.instruction.md +11 -4
- package/guidelines/pageRule/pageRule.instruction.md +6 -53
- package/guidelines/runtimeRule/runtimeRule.instruction.md +68 -4
- package/incrementalBuilder.proc.js +24 -18
- package/{index-nc3br31y.js → index-22bwg8hy.js} +2 -2
- package/{index-9f3reh2y.js → index-2v38x3ad.js} +12 -1
- package/{index-67sd09ag.js → index-3a3vy2xy.js} +8 -8
- package/{index-p7beqww9.js → index-3fmzz9sf.js} +18 -18
- package/{index-9wh04mqy.js → index-3mj5trqc.js} +65 -11
- package/{index-7wf8snar.js → index-3r1crbct.js} +1 -1
- package/{index-41a03gkj.js → index-3zkhg65e.js} +19 -19
- package/{index-2jmvfa62.js → index-4r8dgm4x.js} +3 -3
- package/{index-jek2re5k.js → index-4yvtqcme.js} +8 -8
- package/{index-j0wr4e32.js → index-5ahe641t.js} +9 -9
- package/{index-0dm25wvf.js → index-7ssr7wq4.js} +1 -1
- package/{index-dmcpetwe.js → index-8bta5pnr.js} +98 -23
- package/{index-z92zm3wd.js → index-9a9t77hz.js} +29 -11
- package/{index-3txdtztz.js → index-9gjcbp2g.js} +1 -1
- package/{index-8jtqfye2.js → index-a4gcdffy.js} +488 -53
- package/{index-xwwex8rf.js → index-cbm9gzgx.js} +5 -5
- package/{index-j6jjmn2r.js → index-ckcc9ab3.js} +62 -21
- package/{index-w1zexzpx.js → index-crd99zqs.js} +1 -1
- package/{index-612fdtbk.js → index-f4jydw2x.js} +1 -1
- package/{index-4ss4gkv3.js → index-fagjtk6m.js} +2 -2
- package/{index-ebn9kgea.js → index-fjqapyex.js} +45 -16
- package/{index-h901f24n.js → index-h8w1n11r.js} +5 -5
- package/{index-275a4r3n.js → index-hxg6ctk2.js} +12 -16
- package/{index-78y75t0a.js → index-j2wq064m.js} +6 -7
- package/{index-knpm8sdm.js → index-j3fqs8rc.js} +1 -1
- package/{index-kfvjzk8r.js → index-kbnvyhy4.js} +3 -3
- package/{index-6dzjer7p.js → index-m303nhv6.js} +6 -6
- package/{index-dadwp2aw.js → index-nmdmkjt2.js} +271 -39
- package/{index-2yn3r67f.js → index-nnmw56fz.js} +6 -6
- package/{index-a860mx0m.js → index-pr9nypg7.js} +24 -24
- package/{index-s885g0jj.js → index-pyjkbg8e.js} +3 -3
- package/{index-zmd9xxgd.js → index-q63nbpv7.js} +3 -3
- package/{index-v7ajmsh3.js → index-qecrqpt6.js} +4 -21
- package/{index-gt8phqpt.js → index-rdcgz02t.js} +4 -4
- package/{index-j592zfqc.js → index-rt7q20sj.js} +1 -1
- package/{index-baccvws5.js → index-se7n78fh.js} +1 -1
- package/{index-s4nvxpzm.js → index-sxbsrndq.js} +1 -1
- package/{index-k6vwww45.js → index-t23dgyaf.js} +7 -7
- package/{index-71y6176j.js → index-v16gj2as.js} +86 -66
- package/{index-0s7w2085.js → index-vnk1qwgr.js} +4 -4
- package/{index-z96ks033.js → index-wkwe91sn.js} +169 -51
- package/{index-ybcb9wc8.js → index-wxqp1amd.js} +9 -9
- package/{index-p5zh7pmc.js → index-xv3pvdw4.js} +1 -1
- package/{index-zfnz878d.js → index-yey1envc.js} +1 -1
- package/{index-by2tvsq6.js → index-zyjztrvc.js} +1 -1
- package/index.js +30 -28
- package/{libExecutor-jc6f8hm6.js → libExecutor-n8hpm8s7.js} +3 -3
- package/{library.command-nxvesvhb.js → library.command-8abb26pg.js} +8 -8
- package/{localRegistry.command-xz62e4ng.js → localRegistry.command-sa211m1z.js} +18 -23
- package/{module.command-aaws9byg.js → module.command-z3cwjf0p.js} +10 -10
- package/{package.command-j7hv26p0.js → package.command-akynhtee.js} +9 -12
- package/package.json +3 -2
- package/{page.command-7yffs7n9.js → page.command-3fpdavk9.js} +8 -8
- package/{pipeline.command-7yk0zcng.js → pipeline.command-ca95n8rd.js} +7 -7
- package/{pkgExecutor-arxmvx4t.js → pkgExecutor-a73q41vx.js} +3 -3
- package/{primitive.command-7a1pt715.js → primitive.command-xwe9ggnf.js} +11 -11
- package/{projectTypecheck-f4qhbecd.js → projectTypecheck-7g542ymk.js} +1 -1
- package/{prompter-qyggfhqd.js → prompter-d33wmdpa.js} +2 -2
- package/{quality.command-c6mvrjh1.js → quality.command-7wz7y8z1.js} +9 -9
- package/{repair.command-093adzt9.js → repair.command-dej1qtfq.js} +10 -10
- package/{scalar.command-2ex84spb.js → scalar.command-z9qfxnvm.js} +9 -9
- package/skills/akan-agent/SKILL.md +8 -1
- package/skills/akan-code/SKILL.md +38 -3
- package/skills/akan-page/SKILL.md +18 -13
- package/skills/akan-runtime/SKILL.md +21 -16
- package/skills/akan-service/SKILL.md +2 -2
- package/{subspace.command-4n4n4jpv.js → subspace.command-9wekm4gn.js} +11 -13
- package/templates/localDev/docker-compose.yaml.template +2 -2
- package/{tunnel.command-f7ep1qfa.js → tunnel.command-cxc4h3j8.js} +10 -12
- package/{verify.command-zrkxnvct.js → verify.command-j0w9dr5c.js} +15 -17
- package/{workflow.command-ks16jegk.js → workflow.command-yt4sz04b.js} +15 -15
- package/{workspace.command-ahhfpaag.js → workspace.command-8mp4mcp2.js} +34 -38
- package/CodeAgent-fx6088tv.js +0 -11
- package/TunnelShare-9ry4vh0y.js +0 -18
- package/appExecutor-79azsb2w.js +0 -11
- package/cloud.script-3b401efv.js +0 -35
- package/context.runner-kctbfsde.js +0 -34
- package/dependencyScanner-ge10gb52.js +0 -8
|
@@ -8,53 +8,22 @@ paths:
|
|
|
8
8
|
|
|
9
9
|
# Runtime And Build Configuration
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
11
|
+
Which setting does what, running an app and its logs, and the native commands: the `akan-runtime` skill. Full
|
|
12
|
+
contract: `runtimeRule`.
|
|
13
13
|
|
|
14
|
-
-
|
|
15
|
-
|
|
14
|
+
- Settings are declared in `akan.config.ts` and narrowed — never widened — by an env at boot; domain code reaches
|
|
15
|
+
none of them.
|
|
16
|
+
- **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`**, not the barrel.
|
|
16
17
|
- **Route prefixes move together**: `new AkanApp({ prefix, websocketPrefix })` in `main.ts`, mirrored in
|
|
17
18
|
`api: { … }` in `akan.config.ts` for a CSR shell or native bundle. Read them with `getApiPrefix()` /
|
|
18
19
|
`getWsPrefix()` (`akanjs/base`); never write `/api` or `/ws`, never pass one as a prop.
|
|
19
|
-
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
`
|
|
28
|
-
|
|
29
|
-
in two modes avoids `q.raw`.
|
|
30
|
-
- **`i18n: { localePrefix: "as-needed" }`** serves the default locale at unprefixed paths (`/books/x`, and `<Link>`
|
|
31
|
-
renders them so) while other locales keep `/<locale>/…`. Use it, not a raw `<a>`, for a single-language app or URLs
|
|
32
|
-
fixed from outside (OAuth callbacks, QR codes, mail links, a migrated site).
|
|
33
|
-
|
|
34
|
-
## Running An App
|
|
35
|
-
|
|
36
|
-
- After changing application code, run `bun run akan start <appName>` (`a,b`, `a b`, or `all` for several); check
|
|
37
|
-
the production build with `bun run akan build <appName>`, and serve it without Docker with
|
|
38
|
-
`cd dist/apps/<appName> && bun main.js` (`PORT` or any variable you set overrides the build's env).
|
|
39
|
-
- A supervised session writes `local/apps/<app>/runtime/dev.log` (previous: `dev.prev.log`) — hand over that path,
|
|
40
|
-
not a paste of the repainting full-screen view. Keys, `--plain`, boot waves, `--kill`, watch scope, running a
|
|
41
|
-
built artifact, booting a server in a test: `runtimeRule`.
|
|
42
|
-
|
|
43
|
-
## Native Apps
|
|
44
|
-
|
|
45
|
-
`native: { desktop: { server: true } }` in `akan.config.ts` is all a desktop app that carries its own server needs.
|
|
46
|
-
A `start-*` command loads its pages from `akan start`, so run that first; a desktop app that carries its server
|
|
47
|
-
starts it itself. The full contract — targets, updates, what the carried server ships — is
|
|
48
|
-
`akan guideline show runtimeRule`.
|
|
49
|
-
|
|
50
|
-
```bash
|
|
51
|
-
akan start-desktop <app> # Run the desktop app on this computer
|
|
52
|
-
akan start-ios <app> # Run it in a simulator or on an iPhone (start-android alike)
|
|
53
|
-
akan build-desktop <app> # Build it for this computer into dist/native/<app>/<target>/build
|
|
54
|
-
akan build-desktop <app> --installer true # Windows: add a per-user setup program
|
|
55
|
-
akan update-keygen <app> # Make the update signing key once; print its public key
|
|
56
|
-
akan publish-update <app> # Build a key-signed release for updates.url; --sign true also code-signs it
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
A device capability the framework lacks is a plugin the app owns in `native/<id>/`: `native-plugin.json`,
|
|
60
|
-
`src/index.ts` (the page API, used from a `webkit/` hook), `src/desktop.ts`, Kotlin and Swift.
|
|
20
|
+
- A single-language app, or URLs fixed from outside (OAuth callbacks, QR codes, mail links, a migrated site), gets
|
|
21
|
+
unprefixed paths from `i18n: { localePrefix: "as-needed" }` and `<Link>`, never from a raw `<a>`.
|
|
22
|
+
- The generated Docker image installs only `ca-certificates` and `tzdata` (add the rest in `docker.preRuns`) and
|
|
23
|
+
runs the server as uid 1000 (`bun`) after its root build steps.
|
|
24
|
+
- An app running in two database modes avoids `q.raw`.
|
|
25
|
+
- Give every log sink a floor (`Logger.addSink(sink, { minLevel })`), and never log per delivered record in anything
|
|
26
|
+
that delivers records.
|
|
27
|
+
- **A desktop app's carried server listens on a loopback port any local program can call** — guard it as a network
|
|
28
|
+
server — and ships `private/` and its env readable on the user's computer; read runtime files from `AKAN_APP_DIR`,
|
|
29
|
+
and keep a secret the user gives it with `NativeSecret` (the OS credential store), never in a file.
|
|
@@ -6,7 +6,8 @@ paths:
|
|
|
6
6
|
|
|
7
7
|
# Akan Page Routing
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Steps, typed values, loading and error views, Link and the router: the `akan-page` skill. Full contract — guards,
|
|
10
|
+
apps, heads, CSR root layouts, lib pages, `devOnly`: `pageRule`.
|
|
10
11
|
|
|
11
12
|
- `page/` holds `.tsx` route modules only: `<routeName>.tsx` or `_index.tsx`, `_layout.tsx`, `_overrides.tsx` — no
|
|
12
13
|
other `_*.tsx`, helpers, `.ts` / `.js` files, or uppercase filenames. `[id]` is a dynamic segment, `(group)` a
|
|
@@ -15,49 +16,33 @@ Full contract — guards, apps, heads, CSR root layouts, typed params, lib pages
|
|
|
15
16
|
`_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
|
|
16
17
|
`.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
|
|
17
18
|
A named export beside it fails the build.
|
|
18
|
-
- **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`;
|
|
19
|
-
|
|
20
|
-
`
|
|
19
|
+
- **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`; a layout
|
|
20
|
+
may declare a subset. `akan sync` reads the names off the `export default` chain itself, so it refuses a chain bound
|
|
21
|
+
to a variable first and a `[x]` folder whose page declares no `.param("x")`. `lang` is never declared — every stage
|
|
22
|
+
receives it.
|
|
21
23
|
- `.head()` takes JSX or a function returning it — never a metadata object; deeper heads replace by tag identity,
|
|
22
|
-
and a canonical link / `og:url` comes only from the page's own `.head()`.
|
|
23
|
-
`.notFound()` returns at its top: `.notFound(() => <><title>Not found</title>…</>)`, except below a `.loading()`.
|
|
24
|
+
and a canonical link / `og:url` comes only from the page's own `.head()`.
|
|
24
25
|
- In a CSR bundle a root layout's own markup is hidden: what a person must see from it renders through
|
|
25
26
|
`createPortal(…, document.body)`.
|
|
26
27
|
- `_overrides.tsx` is one `export default override({ Slot: AppComponent })` (`akanjs/ui`), no logic, no
|
|
27
28
|
`"use client"`. The legacy `export default async function Page` shape is never written anew.
|
|
28
29
|
- `libs/<lib>/page` reaches an app through `syncPageLibs`, linked into the generated `page/(libs)/(<lib>)`; edit the
|
|
29
30
|
lib source, never the link. `.config({ devOnly: true })` (a literal) keeps a route out of `akan build`.
|
|
30
|
-
|
|
31
|
-
```tsx
|
|
32
|
-
export default page()
|
|
33
|
-
.param("orgId", ID)
|
|
34
|
-
.config({ transition: "stack" })
|
|
35
|
-
.guard(() => signedIn())
|
|
36
|
-
.render(({ orgId }) => {
|
|
37
|
-
const { l } = usePage();
|
|
38
|
-
const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
|
|
39
|
-
return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
|
|
40
|
-
});
|
|
41
|
-
```
|
|
42
|
-
|
|
43
31
|
- `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
|
|
44
|
-
return
|
|
45
|
-
(title, redirect, link id) in one `Promise.all`.
|
|
32
|
+
return. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
|
|
33
|
+
(title, redirect, link id) in one `Promise.all`. `async` only when the body awaits; the callback is not a React
|
|
34
|
+
component, so it takes no name and no return type. No `useState`, `useEffect`, or comments in page files.
|
|
46
35
|
- **A field's refusal belongs to its `Load.*`**, which draws a notice in its place while the page answers 200. So a
|
|
47
36
|
field reaches only a `Load.*`, directly or through a Zone. Awaited in a component below the page, rendered as a
|
|
48
37
|
child or `use()`-d outside `Load.*`, a refused field takes its whole route level, which draws a retryable notice
|
|
49
38
|
under the layouts above it, as any server error after the first byte does. Await the handle
|
|
50
39
|
(`await fetch.initX()`) instead, so a refusal takes the layout's `.error()`.
|
|
51
|
-
- **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it
|
|
52
|
-
`base.error.mutationInRender
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
- **SSR auth-gated pages: guard at the layout.** `.guard(() => signedIn())` on the `_layout.tsx` chain answers a
|
|
61
|
-
real 307 before any of it renders, so nested pages never render for signed-out users; a check in `.render()`
|
|
62
|
-
after awaited I/O redirects in-page, as an HTTP 200. `signedIn()` comes from `@libs/shared/webkit`, which a new
|
|
63
|
-
workspace has only with `create-workspace --libs true`.
|
|
40
|
+
- **A route never writes while it renders**: a `fetch.<mutation>()` (or socket message) in a stage or a component it
|
|
41
|
+
renders throws `base.error.mutationInRender` before it is sent, synchronously, so a `.catch()` on its promise never
|
|
42
|
+
sees it: opening a link would perform it. Send it from a user action; `{ duringRender: true }` only for a write
|
|
43
|
+
harmless to repeat and safe for anyone to trigger (`ssrRule`).
|
|
44
|
+
- **Gate auth at the layout**: `.guard(() => signedIn())` on the `_layout.tsx` chain answers a real 307 before any of
|
|
45
|
+
it renders, where a check in `.render()` after awaited I/O redirects in-page as an HTTP 200; repeat it on a page
|
|
46
|
+
that needs more. It is a courtesy — the endpoint guards are the gate. `getSelf({ unauthorize })` in a body still
|
|
47
|
+
works. `signedIn()` comes from `@libs/shared/webkit`, which a new workspace has only with
|
|
48
|
+
`create-workspace --libs true`.
|
|
@@ -14,10 +14,7 @@ paths:
|
|
|
14
14
|
|
|
15
15
|
## Calls, Queries, Agents
|
|
16
16
|
|
|
17
|
-
- **Guards
|
|
18
|
-
refused with 403 on every transport, and outside local operation the server does not boot with one. Name its
|
|
19
|
-
guards, or `[Public]` to open it on purpose; `AKAN_UNGUARDED_ENDPOINTS=open` is a deployment's stopgap, never the
|
|
20
|
-
fix.
|
|
17
|
+
- **Guards**: the `auth` rule, loaded with every `*.signal.ts`.
|
|
21
18
|
- **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
|
|
22
19
|
30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
|
|
23
20
|
dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
|
|
@@ -41,7 +41,6 @@ Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction a
|
|
|
41
41
|
`useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
|
|
42
42
|
promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
|
|
43
43
|
`<Load.Stream>` (model instances, server-only) — and `await` only what the shell must contain; ⑥ named `ReactNode`
|
|
44
|
-
slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧
|
|
45
|
-
(
|
|
46
|
-
|
|
47
|
-
state for visibility; ⑩ heavy islands behind `index_.tsx` + `lazy()`.
|
|
44
|
+
slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ gate auth with
|
|
45
|
+
`.guard(() => signedIn())` on `_layout.tsx`, not in a body after I/O (the `page` rule); ⑨ CSS (`data-*` +
|
|
46
|
+
`group-data-[…]`, `<details>`) over client state for visibility; ⑩ heavy islands behind `index_.tsx` + `lazy()`.
|
|
@@ -80,7 +80,8 @@ paths:
|
|
|
80
80
|
Do not narrate code. Do document the thing the code cannot say. Both halves are the rule.
|
|
81
81
|
|
|
82
82
|
- Never restate the identifier, the signature, or the control flow; prefer names and structure. No JSDoc, section
|
|
83
|
-
banners, or "why/how" comments on ordinary logic.
|
|
83
|
+
banners, or "why/how" comments on ordinary logic. `akan verify` flags each new comment as `akan.comment.added`, a
|
|
84
|
+
`// TODO: <issue url>` aside.
|
|
84
85
|
- Density tracks the layer: pages carry none, product `lib/` and `ui/` stay under 1 %, `srvkit/` adapters and
|
|
85
86
|
`guards.ts` (what would leak without each guard) carry what the external constraints require. `akan quality scan`
|
|
86
87
|
reports a `lib/` module or `ui/` entry past 1 % once it holds five comment lines (`akan.comment.density`).
|
|
@@ -78,6 +78,7 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
|
|
|
78
78
|
- Declare plain custom properties under `:root`, not a Tailwind `@theme` extension: the color vocabulary is closed per stylesheet, so `bg-kakao` would generate no CSS. Reference them as `bg-[var(--kakao)]` / `text-[var(--kakao-foreground)]`, which `no-arbitrary-color` allows by design (a `var()` reference is not an arbitrary color literal).
|
|
79
79
|
- Theme-following colors still belong to the app: a lib token is for a color that must **not** change with `data-theme`.
|
|
80
80
|
- An `@import` the CSS pipeline cannot resolve fails the build; it is never dropped. A stylesheet under `page/` that no route imports is compiled by nothing and warns at build time.
|
|
81
|
+
- A stylesheet whose import graph uses no Tailwind (no `@import "tailwindcss"`, no `@theme`, `@apply`, `@plugin` or other Tailwind at-rule, no `theme()`/`--alpha()`/`--spacing()`) skips the Tailwind compiler: only its imports are inlined and the build minifies it, with no Tailwind banner; one Tailwind feature anywhere in that graph compiles the whole stylesheet with Tailwind.
|
|
81
82
|
|
|
82
83
|
## Frame Variables (the page's chrome and the device's insets)
|
|
83
84
|
|
|
@@ -95,6 +96,8 @@ are there on every surface; the three keyboard variables are written only on the
|
|
|
95
96
|
- `--akan-top-inset` / `--akan-bottom-inset` — the height of the page's top bar and bottom tab slot, per breakpoint
|
|
96
97
|
when the page declares a responsive inset. A slot whose inset is 0 at a width clips its chrome there and hides it
|
|
97
98
|
from the keyboard and screen readers, so a phone-only bar needs no `md:hidden`.
|
|
99
|
+
- `--akan-overlay-top` / `--akan-overlay-bottom` — the chrome a route's `overlay` runs the page under (`0px`
|
|
100
|
+
elsewhere); pad the page's scroller by it so its last row clears the bar.
|
|
98
101
|
- `--akan-keyboard-inset`, `--akan-viewport-height`, `--akan-viewport-offset-top` — the on-screen keyboard over the
|
|
99
102
|
page's bottom, the visible height, and how far iOS panned the page to show a field (the top slots follow it). Only
|
|
100
103
|
an SSR page in a browser writes them; a CSR bundle and a native app never do, so read them with a fallback
|
|
@@ -33,6 +33,7 @@ Generated from the akanjs sources of this release: every code a framework error
|
|
|
33
33
|
| `consoleDisabled` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
34
34
|
| `databaseLocked` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
35
35
|
| `desktopAppRequired` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
36
|
+
| `directoryNotWritable` | 500 | `DirectoryNotWritableError` | no | yes | `service/predefinedAdaptor/directoryNotWritableError.ts` |
|
|
36
37
|
| `documentNotFound` | 404 | `NoDocumentError` | yes | no | `document/noDocumentError.ts` |
|
|
37
38
|
| `duplicateRegistration` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
38
39
|
| `failed` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
@@ -60,6 +61,7 @@ Generated from the akanjs sources of this release: every code a framework error
|
|
|
60
61
|
| `invalidInsightQuery` | 400 | `InsightQueryError` | yes | yes | `service/insightQueryError.ts` |
|
|
61
62
|
| `invalidKey` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
62
63
|
| `invalidMessage` | 400 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
64
|
+
| `invalidMetric` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
63
65
|
| `invalidParam` | 500 | `MigrationError` | no | yes | `server/migration/migrationError.ts` |
|
|
64
66
|
| `invalidPrompt` | 500 | `PromptError` | no | yes | `signal/mcp/promptError.ts` |
|
|
65
67
|
| `invalidQuery` | 500 | `DocumentStoreError` | no | yes | `service/documentStoreError.ts` |
|
|
@@ -103,6 +105,8 @@ Generated from the akanjs sources of this release: every code a framework error
|
|
|
103
105
|
| `remoteUnavailable` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
104
106
|
| `remoteUrlRejected` | 502 | `RemoteError` | no | yes | `server/remote/remoteError.ts` |
|
|
105
107
|
| `renderAborted` | 499 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
108
|
+
| `renderQueueFull` | 503 | `RscRenderRefusal` | no | yes | `server/rscRenderRefusal.ts` |
|
|
109
|
+
| `renderQueueTimeout` | 503 | `RscRenderRefusal` | no | yes | `server/rscRenderRefusal.ts` |
|
|
106
110
|
| `routeConflict` | 500 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
107
111
|
| `routeNotFound` | 404 | `AkanError` | no | yes | `base/akanError.ts` |
|
|
108
112
|
| `routeNotFound` | 404 | `RscRouteNotFound` | no | yes | `server/rscClient.tsx` |
|
|
@@ -552,9 +552,10 @@ at every event.
|
|
|
552
552
|
the account sees on `/mcp`, and a call to a name that round did not list is answered as an unknown tool, neither
|
|
553
553
|
asked about nor run. A request with no `allow` array is an `error`.
|
|
554
554
|
- **Toolkits.** `toolkits: { calendar: { description, tools } }` groups names of `allow` so a round need not carry
|
|
555
|
-
every tool. A tool in no toolkit is listed every round, beside
|
|
556
|
-
|
|
557
|
-
`approve` and counts as no tool call. A resume reopens what stored calls and a
|
|
555
|
+
every tool. A tool in no toolkit is listed every round, beside `openToolkit({ name })`, whose description lists the
|
|
556
|
+
toolkits. An opened toolkit's tools are listed from the next round on, until a compaction keeps no message using
|
|
557
|
+
it; `openToolkit` never reaches `approve` and counts as no tool call. A resume reopens what stored calls and a
|
|
558
|
+
summary opened.
|
|
558
559
|
- **The open screen's tools.** `clientTools` takes `new AgentClientTools().list()` from a page the member has open
|
|
559
560
|
(`akanjs/ui`), sent over your own transport. It is client input: a name an endpoint holds is dropped, every one
|
|
560
561
|
counts as a write whatever `readOnly` it was sent with, and past 128 tools, 200,000 characters of definitions or
|
|
@@ -593,7 +594,13 @@ at every event.
|
|
|
593
594
|
reaches `approve(call, { tainted, tool, client })` with `tainted` set, and `client: true` when the call is to a
|
|
594
595
|
page's tool. `askUser`'s answer, `openToolkit`'s and a call the run refused without running taint nothing. A
|
|
595
596
|
remote is the exception on each count: opening one taints the run, and so does any call into one, refused or not,
|
|
596
|
-
whatever `untrusted` returns and with none given.
|
|
597
|
+
whatever `untrusted` returns and with none given. Text the request itself carries from another party taints the
|
|
598
|
+
run before any tool has run: a `context` block marked `untrusted: true`, and a user message's `references`, the
|
|
599
|
+
records it points at. With no `approve`, a write in such a run is answered with the code `writeAfterPageText`
|
|
600
|
+
for the rest of the conversation, as the stored messages keep the reference: only `approve` decides it.
|
|
601
|
+
`context` reaches the model as data in a user turn, never in the system prompt, and a marked block is fenced as
|
|
602
|
+
page content. The run stores `tainted: true` on each assistant message it writes while tainted, so a resume and
|
|
603
|
+
the next ask in that conversation keep the taint without the block being passed again. A batch is judged before it runs, since the model wrote it
|
|
597
604
|
before reading its results. Without `approve`, a `needsConfirm`
|
|
598
605
|
tool — on this catalogue, a mutation with the `destructive` hint above — is refused, and so is every write once
|
|
599
606
|
tainted: such a run writes only in the batch written before any result, and a later write is answered with the
|
|
@@ -1,53 +1,13 @@
|
|
|
1
|
-
# Page Rule —
|
|
1
|
+
# Page Rule — The Route Chain, Guards, Heads, Lib Pages
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
body shape — this is the full contract behind them. Before changing route behavior, check
|
|
3
|
+
The full contract behind the `page` rule and the `akan-page` skill, which carry what a route file may be, the chain,
|
|
4
|
+
typed params and search, loading, 404 and error views, Link and the router. Before changing route behavior, check
|
|
6
5
|
`pkgs/akanjs/server/routeTreeBuilder.ts` and nearby routes for the expected pattern.
|
|
7
6
|
|
|
8
|
-
## Route Files
|
|
9
|
-
|
|
10
|
-
- `apps/<app>/page` may contain route modules only. Do not add helper logic or component-only files there.
|
|
11
|
-
- Route source files under `page/` must use `.tsx`. Do not add `logic.ts`, `.js`, or `.jsx` files under `page/`.
|
|
12
|
-
- A route page is either `<routeName>.tsx` (serving `/routeName`) or a directory's `_index.tsx`; layouts use
|
|
13
|
-
`_layout.tsx`; per-route UI overrides use `_overrides.tsx`.
|
|
14
|
-
- Reserved `_*.tsx` route filenames are limited to `_index.tsx`, `_layout.tsx`, and `_overrides.tsx`; do not add
|
|
15
|
-
files like `_Component.tsx` or `_helper.tsx`.
|
|
16
|
-
- Page filenames must not start with an uppercase letter. Move helper components like `Component.tsx` to app `ui`,
|
|
17
|
-
`common`, or `lib` instead.
|
|
18
|
-
- Dynamic segments use `[id]`; route groups use directories like `(user)`, `(public)`, `(tab)`, or `(detail)`.
|
|
19
|
-
- `_overrides.tsx` is a logic-free UI-override manifest: imports plus a single
|
|
20
|
-
`export default override({ Slot: AppComponent })` (from `akanjs/ui`), no `"use client"`. It re-skins framework
|
|
21
|
-
`akanjs/ui` components for its route subtree; nested manifests merge over ancestors slot-by-slot (closest wins).
|
|
22
|
-
The slot list is in `componentRule`.
|
|
23
|
-
|
|
24
7
|
## The Route Chain
|
|
25
8
|
|
|
26
|
-
- **A route file exports one thing**: `export default page()…render(…)` for a page, `layout()…render(…)` for a
|
|
27
|
-
`_layout.tsx`, `rootLayout()…render(…)` for the app's (or a basePath's) root `_layout.tsx`. Every route setting is
|
|
28
|
-
a stage of the chain — `.param()`, `.search()`, `.config()`, `.guard()`, `.head()`, `.loading()`; `.notFound()` /
|
|
29
|
-
`.error()` on a layout; `.fonts()` / `.theme()` / `.manifest()` / `.reconnect()` / `.wsConnect()` /
|
|
30
|
-
`.layoutStyle()` / `.viewport()` on the root layout; `.prompt()` and `.app()` on a page. A named export beside the
|
|
31
|
-
chain, or `page()` in a `_layout.tsx`, fails the build.
|
|
32
|
-
- **A page names every `[x]` segment of its path with `.param("x", Type)`** and reads a query key only through
|
|
33
|
-
`.search("k", Type)`. Values arrive typed — `ID`/`String` → string, `Int`/`Float` → number, `Boolean`, `Date` →
|
|
34
|
-
Dayjs, an `enumOf` class → its union, `[T]` → array — a path value the type refuses answers not-found, and a
|
|
35
|
-
search value that fails is dropped. A layout may declare a subset. Names are string literals: `akan sync` reads
|
|
36
|
-
them off the source and refuses a `[projectId]` folder whose page declares no `.param("projectId")`, so the chain
|
|
37
|
-
is the `export default` expression itself — one bound to a variable first is refused.
|
|
38
|
-
- **`lang` is never declared**: every route sits under `/:lang`, and the locale segment reaches every stage as
|
|
39
|
-
`lang`.
|
|
40
9
|
- **On a web page's first render `st.use.searchParams()` is still the server's empty snapshot**, synced right after
|
|
41
10
|
hydration, so an effect that needs the query on its first run takes the page's `.search()` value as a prop.
|
|
42
|
-
- There is no `loader=` / `render=` page prop and no `PageProps` interface: the chain declares the arguments and
|
|
43
|
-
`.render()` receives them flat, typed, with `lang` on every route and `children` added for a layout.
|
|
44
|
-
- **A route only reads while it renders.** A `fetch.<mutation>()` (or socket message) sent from `.render()`, `.guard()`,
|
|
45
|
-
`.head()`, `.loading()` or a layout's `.notFound()` / `.error()` (a `.prompt()` run included) throws
|
|
46
|
-
`base.error.mutationInRender` synchronously, before it is sent — a `.catch()` on its promise never sees it: opening a
|
|
47
|
-
link to the page would perform it. Send a write from a user action — a button through a store action. Only a write
|
|
48
|
-
that is harmless to repeat and safe for anyone to trigger (a warm-up) passes `{ duringRender: true }` as the option
|
|
49
|
-
after the endpoint's own arguments (`fetch.updateX(id, data, { duringRender: true })`). `akan quality` flags the call,
|
|
50
|
-
same-file helpers included, as `akan.ssr.render-mutation`.
|
|
51
11
|
- **A `Link` renders its page ahead of the click** — on hover, on keyboard focus, or as it shows with
|
|
52
12
|
`prefetch="viewport"` (production only). A page whose render has an effect one visit should cause once — a view
|
|
53
13
|
counted through `duringRender`, an expensive report — refuses with `.config({ prefetch: false })`; on a `_layout.tsx`
|
|
@@ -117,20 +77,14 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
117
77
|
|
|
118
78
|
## Heads
|
|
119
79
|
|
|
120
|
-
-
|
|
121
|
-
|
|
122
|
-
and analytics is the app's own script, not a stage.
|
|
80
|
+
- A `.head()` that throws renders no head (warned about), so a layout's sign-in redirect still answers. Analytics is
|
|
81
|
+
the app's own script, not a stage.
|
|
123
82
|
- **Heads merge root first**: a deeper `.head()` replaces the `<title>`, a `<meta>` with the same `name` /
|
|
124
83
|
`property`, and a canonical / manifest / icon link, and keeps the rest — so a page states only what it changes.
|
|
125
|
-
- A canonical link and `og:url` each name one URL, so a page carries them only from its own `.head()`, never from a
|
|
126
|
-
layout's.
|
|
127
84
|
- A level that writes `og:image` or `twitter:image` drops the `og:image:*` / `twitter:image:*` tags it inherits, and a
|
|
128
85
|
`<meta name="theme-color">` a `.head()` writes replaces the root `.viewport({ themeColor })`'s. Only `.head()`
|
|
129
86
|
merges: a `<title>` or `<meta>` written inside a component renders beside the merged head, so a second `<title>`
|
|
130
87
|
can reach the document.
|
|
131
|
-
- **A not-found or error view titles itself**: the `<title>` and `<meta>` at the top of what a layout's `.notFound()`
|
|
132
|
-
/ `.error()` returns replace the layouts' head, and the page's own head is dropped. Under a `.loading()` the head is
|
|
133
|
-
already out, so they stay in the view.
|
|
134
88
|
|
|
135
89
|
## A Root Layout Inside A CSR Bundle
|
|
136
90
|
|
|
@@ -144,8 +98,7 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
144
98
|
## Lib Pages — `syncPageLibs`
|
|
145
99
|
|
|
146
100
|
- `libs/<lib>/page` follows the same rules and ships routes to apps that opt in with `syncPageLibs` in
|
|
147
|
-
`akan.config.ts
|
|
148
|
-
default) syncs nothing.
|
|
101
|
+
`akan.config.ts`.
|
|
149
102
|
- `akan sync` links those routes into `apps/<app>/page/(libs)/(<lib>)` — once per basePath when the app declares
|
|
150
103
|
subRoutes. The folder is generated and gitignored like `public/libs`; edit the lib source, never the link.
|
|
151
104
|
- Both path segments are route groups, so a lib route mounts at its own path (`libs/<lib>/page/login/_index.tsx`
|
|
@@ -98,6 +98,23 @@ worker per web-serving replica.
|
|
|
98
98
|
is then the only thing bound to answer `/_akan/app/health`.
|
|
99
99
|
- **The RSC worker is never folded in.** It runs under `--conditions react-server`, which resolves the same
|
|
100
100
|
module graph differently, so it cannot share a process with the server that renders client components.
|
|
101
|
+
- **A render worker starts every render it is sent, unless `AKAN_RSC_WORKER_MAX_CONCURRENCY` caps it.** With a
|
|
102
|
+
cap, that many renders run in one worker (so per replica) and the rest wait first come, first served: documents,
|
|
103
|
+
`/__rsc` navigations and prefetches, and a failed render's error page. A stored page is replayed without a slot,
|
|
104
|
+
after a wait too; an aborted request leaves the queue, and a slot comes back when its render ends, throws, is
|
|
105
|
+
cancelled, or has held it as long as `AKAN_IDLE_TIMEOUT` (120 s, also where that is `0`); MCP page prompts are not
|
|
106
|
+
queued. `AKAN_RSC_WORKER_MAX_QUEUE` bounds the queue (default: the cap times that timeout's seconds, `0` for
|
|
107
|
+
none): a render past it, or one that waited that timeout, is answered `503` with `Retry-After: 1` and `no-store`
|
|
108
|
+
before it renders (`renderQueueFull`, `renderQueueTimeout`; a browser gets a page that reloads once, backing
|
|
109
|
+
off), counted as its route's `5xx` and in `akan_rsc_render_refusals_total{reason}`, which counts a slot taken
|
|
110
|
+
back as `hold-timeout`. `akan_rsc_renders_in_flight`, `akan_rsc_render_queue_depth` and
|
|
111
|
+
`akan_rsc_render_queue_wait_seconds` report the queue; a page that waited carries `queueMs` on its request line.
|
|
112
|
+
The cap bounds admitted renders, not abandoned ones: a page whose slot came back runs on until its own `await`
|
|
113
|
+
settles, counted in `akan_rsc_renders_abandoned`.
|
|
114
|
+
Off by default, because a page that awaits data holds its slot: on `apps/akan` at 32 requests at once, pages
|
|
115
|
+
waiting 20–200 ms on data served 151 requests a second uncapped and 32 at a cap of 4, while CPU-bound pages
|
|
116
|
+
served about 105 at any cap with the same median latency. It bounds a burst, not latency: set it to the requests
|
|
117
|
+
one replica is sized for; the table is in `pkgs/akanjs/server/SSR_MEMORY_DIAGNOSIS.md`.
|
|
101
118
|
- **A solo process answers `/_akan/app/health`, `/_akan/app/metrics` and `/_akan/bench/ping` itself**, in the
|
|
102
119
|
gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
|
|
103
120
|
rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
|
|
@@ -107,6 +124,19 @@ worker per web-serving replica.
|
|
|
107
124
|
alone (still 200) and `/_akan/app/metrics` is 401. An address that sends 10 wrong bearers in a minute is refused
|
|
108
125
|
the right one too until the minute passes. A probe that reads only the status code needs nothing; give a scraper or
|
|
109
126
|
monitor `AKAN_STATUS_TOKEN` (32 characters or more, or it warns), which reads nothing else.
|
|
127
|
+
- **`/_akan/app/metrics` answers a Prometheus scrape as text**, behind the same token: `Accept:
|
|
128
|
+
application/openmetrics-text` gets OpenMetrics 1.0 and `text/plain` the 0.0.4 text, while `*/*`,
|
|
129
|
+
`application/json` or no Accept keeps the JSON, whose `metricFamilies` carries the same series. Every endpoint and
|
|
130
|
+
page call is counted and timed with tracing off — `akan_endpoint_requests_total{endpoint, status_class}`,
|
|
131
|
+
`akan_page_requests_total{route, status_class}` and their `_duration_seconds` histograms (12 buckets, 1 ms to
|
|
132
|
+
10 s) — labelled `<type>:<key>` or the route id and the process `role`, never a URL, user or query; a path no
|
|
133
|
+
route matches is `unmatched`, and a label past 2,000 values is `other`. Behind a gateway each replica reports its
|
|
134
|
+
own and the gateway adds them, as fresh as `AKAN_MEMORY_LOG_INTERVAL_MS`. A new series is one line,
|
|
135
|
+
`metricRegistry.counter|gauge|histogram(name, help, labels)` from `server/metrics/metricRegistry`, in the server
|
|
136
|
+
or in its RSC worker, whose series reach the same scrape as fresh as that interval and survive a worker restart. The
|
|
137
|
+
`infra/app` chart adds the `prometheus.io/*` scrape annotations with `<branch>.metrics.scrape: true` and reads the
|
|
138
|
+
token from the Secret `<branch>.metrics.tokenSecret` names, and refuses to render `scrape` without it;
|
|
139
|
+
`infra/monitoring` holds a Grafana dashboard and the alert rules.
|
|
110
140
|
- **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
|
|
111
141
|
with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
|
|
112
142
|
- **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
|
|
@@ -191,9 +221,20 @@ normalized to `info` with one warning.
|
|
|
191
221
|
`traceId`. Internal triggers get `internal:<key>`, the RSC worker gets `page:<route>`, MCP calls are the
|
|
192
222
|
endpoint's own type with `origin: "mcp"`. `AKAN_LOG_CONTEXT=0` is the escape hatch; `AKAN_TRACE=1` is a
|
|
193
223
|
different switch that adds span and query aggregation. Measured cost: ~25ns per call.
|
|
224
|
+
- **One id per request, across processes.** The `traceId` is 32 hex digits (a W3C trace id), written on the response
|
|
225
|
+
as `x-request-id` and in a failed call's body as `traceId`. The server always mints it: an inbound `traceparent`,
|
|
226
|
+
or else an `x-request-id` that is a UUID or 32 hex digits, is kept as `link` on every record of the request, and
|
|
227
|
+
`akan logs --trace` matches `link` too and takes the id as the caller sent it. Only the gateway's unix-socket hop
|
|
228
|
+
to its replica carries an id over. `AKAN_TRACE_ADOPT=trusted-proxies` lets a peer `AKAN_TRUSTED_PROXIES` names
|
|
229
|
+
(an address, a CIDR, or `private`; never the unset default, `*`, or loopback unlisted) choose the id, which is
|
|
230
|
+
safe only when that proxy overwrites or strips both headers. The replica hands its id to the RSC worker in the
|
|
231
|
+
render message, a server-side `fetch` sends `traceparent` to the app's own server and to a `clone({ origin })`,
|
|
232
|
+
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
|
+
enqueuing one.
|
|
194
234
|
- **Not everything carries context, by design.** The primitive query fast path (an unauthenticated GET of a
|
|
195
235
|
primitive with no args, guards or middlewares) skips it; the schedule adaptor's own `started/finished/error`
|
|
196
|
-
lines wrap the traced handler from outside; gateway
|
|
236
|
+
lines wrap the traced handler from outside; gateway lines written outside a request have none. `akan logs
|
|
237
|
+
--endpoint` says so.
|
|
197
238
|
- **`Logger.addSink(sink, { minLevel })` — give a sink its floor.** A sink with none follows `AKAN_LOG_FILE_LEVEL`
|
|
198
239
|
(default `trace`), which is why a registered sink used to make every `verbose` call render (1,294ns against an
|
|
199
240
|
11ns reject). The IPC forwarder and any sink that never reads the text pass a floor and cost a record literal.
|
|
@@ -224,8 +265,17 @@ normalized to `info` with one warning.
|
|
|
224
265
|
- **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call, at `info`, `warn` under
|
|
225
266
|
500, or `error` with `type` and `stack` for a 5xx (then the only 5xx record); **`AKAN_LOG_FLIGHT=1`**
|
|
226
267
|
keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
|
|
227
|
-
`AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace
|
|
228
|
-
with the `AKAN_LOG_DEBUG_HEADER` secret.
|
|
268
|
+
`AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace`, records its spans and answers with
|
|
269
|
+
`Server-Timing` — under the local dev runtime, or with the `AKAN_LOG_DEBUG_HEADER` secret. A local runtime sends
|
|
270
|
+
`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.
|
|
272
|
+
- **Every dev route is listed once, in `akanjs/server/routing/devSurfaces`** — devtools, Studio, `/_akan/hmr`,
|
|
273
|
+
the ssr-dev and csr-dev module registries, `/__rsc/manifest` — and is mounted through `DevRoutes.mount`, which
|
|
274
|
+
refuses a path the list lacks. Each answers only localhost, an IP address, the app's own hosts and
|
|
275
|
+
`AKAN_ALLOWED_HOSTS` names, even on a server that answers every Host; `--share` serves only the two module
|
|
276
|
+
registries. Devtools opens in the local dev runtime; elsewhere `AKAN_DEVTOOLS=true` opens it only with
|
|
277
|
+
`AKAN_LOG_DEBUG_HEADER` set to at least 32 characters, to `x-akan-debug: <secret>` or a browser that posted the
|
|
278
|
+
secret to the form it is shown (a 15-minute cookie); without one that long it stays closed and the log says why.
|
|
229
279
|
- **Structured values go in `LogRecord.attrs` via `Logger.emit(...)`**; a key naming a secret is `[redacted]`
|
|
230
280
|
before the record exists.
|
|
231
281
|
- **Never log per delivered record in anything that delivers records.** The control socket and the hub do not,
|
|
@@ -247,6 +297,16 @@ const config: AppConfig = { docker: "FROM oven/bun:1.4.4-slim\n…" }; // verbat
|
|
|
247
297
|
`RUN if [ "$TARGETARCH" = "<arch>" ]` guard, so a multi-arch build runs it on one leg only. `preRuns` land
|
|
248
298
|
before `bun install --production` (where a native dependency's build tools have to be), `postRuns` after it
|
|
249
299
|
and before the app files are copied.
|
|
300
|
+
- **The server runs as `USER 1000:1000`, oven/bun's `bun` user, and owns only the directories it writes.** The
|
|
301
|
+
build steps (`apt-get`, `preRuns`, `bun install`, `postRuns`) run as root and the app files stay root's, so
|
|
302
|
+
`main.js`, `server.js`, `public/` and `node_modules` are read-only to the server. After the copy, uid 1000 gets
|
|
303
|
+
`/workspace/sqlite`, `/workspace/local`, `/workspace/runtime` (the control socket), `/workspace/data` and
|
|
304
|
+
`/workspace/.akan/artifact/image-cache`; `/tmp` and `/home/bun` are writable too. A directory a `postRuns` step
|
|
305
|
+
makes for the server to write needs `chown 1000:1000`. An empty named volume takes the owner of the directory it
|
|
306
|
+
mounts over; one a root image already wrote is owned by root, so the server stops at boot with
|
|
307
|
+
`directoryNotWritable`, naming the directory and the `chown -R 1000:1000` that fixes it.
|
|
308
|
+
- **The base image is pinned by digest**, `oven/bun:<bun>-slim@sha256:…`, the multi-arch index's, so amd64 and
|
|
309
|
+
arm64 build from the same release; a test holds the tag to the Bun version the workspace's `package.json` pins.
|
|
250
310
|
- **The image installs the versions the workspace locked.** `akan build` writes a `bun.lock` beside the image's
|
|
251
311
|
`package.json`, cut down from the workspace's to what the server needs, and the image installs it
|
|
252
312
|
`--frozen-lockfile`. A workspace without a root `bun.lock` gets a warning and an unlocked install; a Dockerfile
|
|
@@ -396,7 +456,11 @@ const config: AppConfig = {
|
|
|
396
456
|
only, `evaluate`, a trusted `sendKey`, `capture`, and `loadFailed` / `gone` (it reloads, or is rebuilt, by itself;
|
|
397
457
|
the reason is `terminated` on macOS, and `rebuildFailed` when a rebuild failed and the view is closed, to be opened
|
|
398
458
|
again) / `consoleMessage` events. Every method on Windows and Linux, where a visible view also holds the keyboard
|
|
399
|
-
focus and no `consoleMessage` is sent; macOS 14+ lacks `sendKey`, `setMuted` and `capture`.
|
|
459
|
+
focus and no `consoleMessage` is sent; macOS 14+ lacks `sendKey`, `setMuted` and `capture`. A view opens only the
|
|
460
|
+
exact origins `native.desktop.externalView.allowOrigins` lists (none without it), over the calling page's own window:
|
|
461
|
+
its own `allowOrigins` narrow within them, and opening it again while it is open never adds one. Closed, its id opens
|
|
462
|
+
again for any listed origins with the same profile, which belongs to the id. `evaluate` and `initScript` need
|
|
463
|
+
`desktop.externalView.evaluate: true`, `sendKey` needs `desktop.externalView.sendKey: true`.
|
|
400
464
|
|
|
401
465
|
## A Desktop App's Server — `bin` And `trustedDependencies`
|
|
402
466
|
|
|
@@ -1,23 +1,23 @@
|
|
|
1
1
|
// @bun
|
|
2
|
-
import
|
|
3
|
-
HmrWatcher,
|
|
4
|
-
WatchRootResolver,
|
|
5
|
-
ApplicationBuildReporter
|
|
6
|
-
} from "./index-dmcpetwe.js";
|
|
2
|
+
import"./index-zyjztrvc.js";
|
|
7
3
|
import {
|
|
8
4
|
CodegenLock,
|
|
9
5
|
WorkspaceExecutor
|
|
10
|
-
} from "./index-
|
|
11
|
-
import"./index-by2tvsq6.js";
|
|
6
|
+
} from "./index-v16gj2as.js";
|
|
12
7
|
import"./index-j4yvgfhr.js";
|
|
8
|
+
import {
|
|
9
|
+
HmrWatcher,
|
|
10
|
+
WatchRootResolver,
|
|
11
|
+
ApplicationBuildReporter
|
|
12
|
+
} from "./index-8bta5pnr.js";
|
|
13
13
|
import {
|
|
14
14
|
AppExecutor2
|
|
15
|
-
} from "./index-
|
|
16
|
-
import"./index-
|
|
17
|
-
import"./index-
|
|
15
|
+
} from "./index-9a9t77hz.js";
|
|
16
|
+
import"./index-yey1envc.js";
|
|
17
|
+
import"./index-crd99zqs.js";
|
|
18
18
|
import {
|
|
19
19
|
ServerGraphFile
|
|
20
|
-
} from "./index-
|
|
20
|
+
} from "./index-3mj5trqc.js";
|
|
21
21
|
import {
|
|
22
22
|
GraphClientEntryDiscovery,
|
|
23
23
|
RouteClientBuilder,
|
|
@@ -27,11 +27,11 @@ import {
|
|
|
27
27
|
DevChangePlanner,
|
|
28
28
|
DevGeneratedIndexSync,
|
|
29
29
|
SsrDevBundler
|
|
30
|
-
} from "./index-
|
|
30
|
+
} from "./index-4yvtqcme.js";
|
|
31
31
|
import"./index-trffs83s.js";
|
|
32
32
|
import {
|
|
33
|
-
|
|
34
|
-
} from "./index-
|
|
33
|
+
FrameworkGraph2
|
|
34
|
+
} from "./index-3fmzz9sf.js";
|
|
35
35
|
import {
|
|
36
36
|
GitRevision
|
|
37
37
|
} from "./index-zyb0ebm4.js";
|
|
@@ -41,7 +41,7 @@ import {
|
|
|
41
41
|
import {
|
|
42
42
|
prepareDevWatchBatch
|
|
43
43
|
} from "./index-a5vmm6x4.js";
|
|
44
|
-
import"./index-
|
|
44
|
+
import"./index-3r1crbct.js";
|
|
45
45
|
|
|
46
46
|
// pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts
|
|
47
47
|
import path6 from "path";
|
|
@@ -194,7 +194,12 @@ class BuilderBoot {
|
|
|
194
194
|
if (!result.artifact || !result.optimizedFonts)
|
|
195
195
|
throw new Error("boot build reported success without an artifact; the build worker likely died");
|
|
196
196
|
const discovery = await GraphClientEntryDiscovery.create(app);
|
|
197
|
-
return {
|
|
197
|
+
return {
|
|
198
|
+
artifact: result.artifact,
|
|
199
|
+
optimizedFonts: result.optimizedFonts,
|
|
200
|
+
discovery,
|
|
201
|
+
basePhaseMs: result.basePhaseMs ?? {}
|
|
202
|
+
};
|
|
198
203
|
}
|
|
199
204
|
static recoverBoot(app, bootError, logger, runner, initialGeneration, create) {
|
|
200
205
|
const firstMessage = bootError instanceof Error ? bootError.message : String(bootError);
|
|
@@ -272,7 +277,7 @@ class BuilderGraphPayloads {
|
|
|
272
277
|
this.#generation = generation;
|
|
273
278
|
}
|
|
274
279
|
touched(files) {
|
|
275
|
-
|
|
280
|
+
FrameworkGraph2.touched(this.#app.workspace.workspaceRoot, files);
|
|
276
281
|
}
|
|
277
282
|
async of(msg) {
|
|
278
283
|
if (msg.framework)
|
|
@@ -290,7 +295,7 @@ class BuilderGraphPayloads {
|
|
|
290
295
|
}
|
|
291
296
|
async#framework() {
|
|
292
297
|
const { workspaceRoot } = this.#app.workspace;
|
|
293
|
-
return { workspaceRoot, framework: await
|
|
298
|
+
return { workspaceRoot, framework: await FrameworkGraph2.cached(workspaceRoot) };
|
|
294
299
|
}
|
|
295
300
|
async#changesSince(since) {
|
|
296
301
|
const { workspace, name } = this.#app;
|
|
@@ -1352,6 +1357,7 @@ class IncrementalBuilder {
|
|
|
1352
1357
|
const initialGeneration = BuilderBoot.initialGeneration();
|
|
1353
1358
|
try {
|
|
1354
1359
|
const deps = await BuilderBoot.buildBootDeps(app, bootRunner);
|
|
1360
|
+
BuilderChannel.emit({ type: "base-built", phaseMs: deps.basePhaseMs });
|
|
1355
1361
|
builder = new IncrementalBuilder({ app, watch, initialGeneration, ...deps });
|
|
1356
1362
|
} catch (err) {
|
|
1357
1363
|
if (!watch)
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// @bun
|
|
2
2
|
import {
|
|
3
3
|
akanCodePaths2
|
|
4
|
-
} from "./index-
|
|
4
|
+
} from "./index-xv3pvdw4.js";
|
|
5
5
|
import {
|
|
6
6
|
ConfigLock
|
|
7
7
|
} from "./index-bqbf654f.js";
|
|
@@ -157,7 +157,7 @@ class SubagentPool2 {
|
|
|
157
157
|
}
|
|
158
158
|
}
|
|
159
159
|
async#run(id, kind, prompt, signal) {
|
|
160
|
-
const { CodeAgent } = await import("./CodeAgent-
|
|
160
|
+
const { CodeAgent } = await import("./CodeAgent-cqbf9gsv.js");
|
|
161
161
|
const budget = this.#options.parent.tools.subagent;
|
|
162
162
|
const child = SubagentPool2.childOf(this.#options.parent, kind);
|
|
163
163
|
const model = this.#options.model?.();
|