@akanjs/cli 3.2.1-rc.1 → 3.2.1-rc.2

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 (93) hide show
  1. package/.build-stamp +2 -2
  2. package/{CodeAgent-xdw73nbz.js → CodeAgent-9t00vd1t.js} +2 -2
  3. package/{CodeTui-0gewm71c.js → CodeTui-6pzd57d9.js} +1 -1
  4. package/TunnelShare-ystnpd6r.js +16 -0
  5. package/{agent.command-g1mj34wz.js → agent.command-mx412p4j.js} +17 -17
  6. package/akanCode.js +2 -2
  7. package/{appExecutor-rrx10jya.js → appExecutor-5rqem8rw.js} +3 -3
  8. package/{application.command-3w4v7t40.js → application.command-6qec3fkg.js} +13 -13
  9. package/{applicationBuildRunner-y5xbetyz.js → applicationBuildRunner-3sgyp4kc.js} +13 -10
  10. package/buildBatch.proc.js +10 -10
  11. package/{cloud.command-ph0rz6sw.js → cloud.command-zcm1vwep.js} +18 -18
  12. package/cloud.script-zv6bxdvg.js +30 -0
  13. package/{code.command-9b967qpg.js → code.command-9ve10cys.js} +10 -10
  14. package/{context.command-ndzs5rbf.js → context.command-f1sqfvws.js} +18 -18
  15. package/context.runner-7d1zp6sp.js +32 -0
  16. package/{csrArtifactBuilder-gtvff6k7.js → csrArtifactBuilder-9zvt4tqd.js} +2 -3
  17. package/{guideline.command-y8qz9kxy.js → guideline.command-6rezhb4j.js} +6 -6
  18. package/guidelines/akanApi/akanApi.instruction.md +7 -2
  19. package/guidelines/conventions/core.md +6 -11
  20. package/guidelines/conventions/rules/app.md +1 -2
  21. package/guidelines/conventions/rules/auth.md +18 -27
  22. package/guidelines/conventions/rules/config.md +14 -46
  23. package/guidelines/conventions/rules/page.md +19 -34
  24. package/guidelines/conventions/rules/server.md +1 -4
  25. package/guidelines/conventions/rules/ssr.md +3 -4
  26. package/guidelines/conventions/rules/ts.md +2 -1
  27. package/guidelines/cssRule/cssRule.instruction.md +1 -0
  28. package/guidelines/pageRule/pageRule.instruction.md +6 -53
  29. package/incrementalBuilder.proc.js +8 -8
  30. package/{index-4a1n0nym.js → index-2fw81aak.js} +1 -1
  31. package/{index-whvhsb5f.js → index-2qhrmtb0.js} +1 -1
  32. package/{index-dr1carpr.js → index-3jzx6k0e.js} +4 -4
  33. package/{index-2kh4xj3m.js → index-5fwhv8kp.js} +1 -1
  34. package/{index-scfsqen7.js → index-6z5cwvq1.js} +3 -3
  35. package/{index-y2g0s9tn.js → index-7jknrhws.js} +1 -1
  36. package/{index-6j351de4.js → index-8vger8r0.js} +2 -2
  37. package/{index-1c2807kg.js → index-94a2xrv1.js} +3 -3
  38. package/{index-ymgsvhc5.js → index-adbcqv0k.js} +4 -4
  39. package/{index-45aprybg.js → index-akep88g2.js} +2 -2
  40. package/{index-652f3bs8.js → index-c1sfw20m.js} +5 -5
  41. package/{index-cm9rb480.js → index-c7zk1gtv.js} +5 -6
  42. package/{index-b0t92k71.js → index-cryyzd80.js} +11 -11
  43. package/{index-82cmbpxc.js → index-d9qkd87g.js} +7 -7
  44. package/{index-6gepp8yn.js → index-ep31fxe8.js} +60 -19
  45. package/{index-ankyx6dj.js → index-f0qe3x4t.js} +3 -3
  46. package/{index-38x8ynrx.js → index-f52d0acp.js} +2 -2
  47. package/{index-twjgmryg.js → index-f5s9w5bq.js} +4 -4
  48. package/{index-pc42gxa5.js → index-g4hta169.js} +4 -4
  49. package/{index-ktxdfqg5.js → index-gxe8nyxd.js} +1 -1
  50. package/{index-2vn0m9z5.js → index-h2g1qt9p.js} +3 -3
  51. package/{index-4zgm54wf.js → index-havp958b.js} +7 -7
  52. package/{index-qh81drde.js → index-mj9mzss7.js} +8 -8
  53. package/{index-3569fr49.js → index-nawk3ttc.js} +5 -5
  54. package/{index-0wa5z6rm.js → index-pad3djxk.js} +1 -1
  55. package/{index-gtydr9qc.js → index-q7ct22a1.js} +8 -8
  56. package/{index-0csk6jqm.js → index-qc4xk6ng.js} +3 -3
  57. package/{index-jdw9m5c4.js → index-qk2evkwr.js} +4 -4
  58. package/{index-b372rck5.js → index-smjm20t4.js} +14 -7
  59. package/{index-d0n78fzc.js → index-tc9k9sgg.js} +11 -11
  60. package/{index-jg5rwrf7.js → index-wjecpeyq.js} +226 -21
  61. package/{index-f2arv0mv.js → index-xftdwcdj.js} +1 -1
  62. package/{index-1p9bxjmt.js → index-xrmcq5hx.js} +2 -2
  63. package/{index-q8h4eg5y.js → index-y9tadrbb.js} +6 -6
  64. package/{index-02v45hh9.js → index-yjq1e8ge.js} +3 -3
  65. package/{index-9rymt8d6.js → index-yq1rfscr.js} +1 -1
  66. package/{index-0z8sbdme.js → index-zswfx1y8.js} +1 -1
  67. package/{index-mnhrqjjq.js → index-zxvw9wme.js} +1 -1
  68. package/index.js +27 -27
  69. package/{libExecutor-nstr00s7.js → libExecutor-6we2k5s7.js} +2 -2
  70. package/{library.command-b02aw1hm.js → library.command-3d276hfe.js} +7 -7
  71. package/{localRegistry.command-3hg1p4aj.js → localRegistry.command-0k4wbbw3.js} +17 -17
  72. package/{module.command-bd9gz6cv.js → module.command-2efp8hnc.js} +9 -9
  73. package/{package.command-xmr0mxze.js → package.command-jbmhv4ka.js} +8 -8
  74. package/package.json +3 -2
  75. package/{page.command-x94qf58g.js → page.command-bmn5mqg4.js} +7 -7
  76. package/{pipeline.command-n2843k6t.js → pipeline.command-wy27rp6n.js} +6 -6
  77. package/{pkgExecutor-cka27e3c.js → pkgExecutor-zg3p4wzh.js} +2 -2
  78. package/{primitive.command-cs7v376h.js → primitive.command-c1zhx2k0.js} +10 -10
  79. package/{projectTypecheck-za2n3nbr.js → projectTypecheck-2nrmqybz.js} +1 -1
  80. package/{quality.command-nqngh1jd.js → quality.command-s7k6hd9v.js} +8 -8
  81. package/{repair.command-v2medwsm.js → repair.command-whzxzzwt.js} +9 -9
  82. package/{scalar.command-61cjmxn1.js → scalar.command-9h6jj42g.js} +8 -8
  83. package/skills/akan-page/SKILL.md +18 -13
  84. package/skills/akan-runtime/SKILL.md +21 -16
  85. package/skills/akan-service/SKILL.md +2 -2
  86. package/{subspace.command-dtv8nfh7.js → subspace.command-n39bhv0c.js} +10 -10
  87. package/{tunnel.command-fmwm5fgb.js → tunnel.command-n5ezcmfs.js} +9 -9
  88. package/{verify.command-4f260t53.js → verify.command-c7xn9jkn.js} +14 -14
  89. package/{workflow.command-tm5q9xsm.js → workflow.command-7jf64z5f.js} +14 -14
  90. package/{workspace.command-75gc280j.js → workspace.command-h55z8b42.js} +31 -31
  91. package/TunnelShare-cccfdgbm.js +0 -16
  92. package/cloud.script-8bs9tp4j.js +0 -30
  93. package/context.runner-bmstpng2.js +0 -32
@@ -7,17 +7,27 @@ paths:
7
7
 
8
8
  # Authorization
9
9
 
10
- - **Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.**
10
+ - **Every endpoint and named slice names its guards** (`no-unguarded-endpoint`, a warning) — a `query` / `mutation` /
11
+ `pubsub` / `message`, a named slice's `init()`, or a `slice()` map without `root` that names none (or `guards: []`)
12
+ answers every call with 403 on every transport, and outside local operation the server does not boot. Write
13
+ `guards: [Public]` when anonymous access is the intent; `AKAN_UNGUARDED_ENDPOINTS=open` is a deployment's stopgap,
14
+ never the fix.
15
+ - **A `slice()` takes its guard map as a second argument**, and `root:` is always `Admin`:
16
+ `slice(srv.task, { guards: { root: Admin, get: SignedIn, cru: SignedIn } }, (init) => ({...}))`.
11
17
  `guards: { cru: false }` (or per verb) takes a generated verb off HTTP; `mcp: { cru: false }` only keeps it off the
12
18
  agent shelf.
13
- - **Every custom `mutation` / `query` / `message` names its own `guards: [...]`** — the slice map reaches only
14
- generated endpoints, and a `pubsub` / `message` without its own declares none. `Public` belongs on a slice `get:`;
15
- on a mutation only for an act that must work signed out (sign-up/in, token refresh, an OAuth route), which also
16
- declares a `rateLimit`. A guardless endpoint answers every call with 403 and stops the boot outside local
17
- operation; MCP also refuses a mutation guarded only by `Public`.
19
+ - **An `endpoint()` takes no guard argument** — `endpoint(srv.task, ({ mutation }) => ({...}))` — and the slice map
20
+ reaches only generated endpoints, so every custom `mutation` / `query` / `message` names its own array:
21
+ `mutation(cnst.Task, { guards: [SignedIn] })`. A `pubsub` / `message` without its own declares none.
22
+ - `Public` always allows. It belongs on a slice `get:`; on a mutation only for an act that must work signed out
23
+ (sign-up/in, token refresh, an OAuth route), which also declares a `rateLimit`. MCP refuses a mutation guarded only
24
+ by `Public`. Other guards implement the `Guard` interface in `srvkit/` (server-only).
18
25
  - Guards serve HTTP and websocket alike: read `context.get<T>("account")`, never `getHttpContext()` /
19
- `getWebSocketContext()`; keep them side-effect free and re-runnable. The acting user comes from `.with(Self)` /
20
- `.with(CurrentUserId)` / `.with(Me)` (never a client-supplied id) and the caller's address from `.with(Ip)`.
26
+ `getWebSocketContext()`; keep them side-effect free and re-runnable.
27
+ - **The acting user comes from an `InternalArg`**, never a client-supplied id:
28
+ `mutation(cnst.Task, { guards: [SignedIn] }).with(CurrentUserId).exec(async function (currentUserId) { ... })`, or
29
+ `.with(Self)` / `.with(Me)`; the caller's address from `.with(Ip)`. Generated CRUD and `serve()` service methods /
30
+ lifecycle hooks receive no session context, so an operation that needs the acting user is a custom endpoint.
21
31
  - Keep `static name = "User";` on guard classes — `fetch` serializes it and the API explorer filters on it. It looks
22
32
  dead, so comment it.
23
33
  - **Every guard declares `static scope: GuardScope`, no default**: `"account"` reads only the caller (MCP listings
@@ -25,22 +35,3 @@ paths:
25
35
  `Admin` / roles are `"account"`, every `Can<Verb><Model>` is `"resource"`; `Person` adds `static agents = false`.
26
36
  - `Can<Verb><Model>` guards in `srvkit/guards.ts` fail closed and ship with the model's library (`transportRule`).
27
37
  Services re-check ownership behind a guard — two independent gates.
28
-
29
- - **Every endpoint and named slice names its guards** (`no-unguarded-endpoint`, a warning) — a `query` / `mutation` /
30
- `pubsub` / `message`, a named slice's `init()`, or a `slice()` map without `root` that names none (or `guards: []`)
31
- refuses every caller, and outside local operation the server does not boot. Write `guards: [Public]` when
32
- anonymous access is the intent.
33
-
34
- - **A `slice()` takes its guard map as a second argument**, `slice(srv.task, { guards: { root: Admin, get: SignedIn,
35
- cru: SignedIn } }, (init) => ({...}))`. An `endpoint()` takes no guard argument at all —
36
- `endpoint(srv.task, ({ mutation }) => ({...}))` — so **every custom `mutation` / `query` / `message` names its own
37
- `guards: [...]` array**: `mutation(cnst.Task, { guards: [SignedIn] })`. `Public` always allows; other guards
38
- implement the `Guard` interface in `srvkit/` (server-only).
39
- - **Read the caller inside a guard** with `context.get<T>("account")`, which works on HTTP and websocket calls
40
- alike — never branch on `getHttpContext()` / `getWebSocketContext()`. Every guard class also declares
41
- `static scope: GuardScope`, `"account"` or `"resource"`, with no default.
42
- - **Read the current user inside a custom endpoint** by injecting an `InternalArg` with `.with(...)`:
43
- `mutation(cnst.Task, { guards: [SignedIn] }).with(CurrentUserId).exec(async function (currentUserId) { ... })`.
44
- - **Auto-generated CRUD and `serve()` service methods / lifecycle hooks do not receive session context.** If an
45
- operation needs the acting user, expose a custom endpoint that takes it via `.with(CurrentUserId)` — never trust a
46
- client-supplied user id.
@@ -8,53 +8,21 @@ paths:
8
8
 
9
9
  # Runtime And Build Configuration
10
10
 
11
- Declared in `akan.config.ts`, narrowed — never widened — by an env at boot; domain code reaches none of it
12
- (`runtimeRule`).
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
- - **`web: true | false | { csr: boolean }`** — `{ csr: false }` drops the CSR bundle native apps ship, `false` is
15
- API-only.
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
- - **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`**, not the barrel.
20
- - Give every log sink a floor (`Logger.addSink(sink, { minLevel })`), never log per delivered record in anything
21
- that delivers records, and tail with `akan logs <app>`.
22
- - **`docker` is `string | { image, preRuns, postRuns, command }`**; the generated image installs only
23
- `ca-certificates` and `tzdata`.
24
- - **Native apps are the `native` section** (iOS, Android, desktop). A desktop app's carried server listens on a
25
- loopback port any local program can call — guard it as a network server — and ships `private/` and its env
26
- readable on the user's computer; read runtime files from `AKAN_APP_DIR`, and keep a secret the user gives it with
27
- `NativeSecret` (the OS credential store), never in a file.
28
- - **`database: { modes: [...] }`** (`single`, `multiple`, `cluster`), chosen by `AKAN_DATABASE_MODE`; an app running
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`.
23
+ - An app running in two database modes avoids `q.raw`.
24
+ - Give every log sink a floor (`Logger.addSink(sink, { minLevel })`), and never log per delivered record in anything
25
+ that delivers records.
26
+ - **A desktop app's carried server listens on a loopback port any local program can call** — guard it as a network
27
+ server — and ships `private/` and its env readable on the user's computer; read runtime files from `AKAN_APP_DIR`,
28
+ 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
- Full contract — guards, apps, heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
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)`; values
19
- arrive typed. `lang` is never declared — every stage receives it. A client filter writes its key back with
20
- `router.replace(href, { shallow: true })`, which keeps the page on screen.
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()`. A 404's title is the `<title>` a layout's
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; auth is the chain's `.guard()`, which runs before anything renders. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
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 renders throws
52
- `base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
53
- `{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
54
- - Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`; a new workspace has that lib only with
55
- `create-workspace --libs true`) at `_layout.tsx`, and repeat it on a page that needs more; it is a courtesy, the
56
- endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits;
57
- the callback is not a React component, so it takes no name and no return type. No `useState`, `useEffect`, or
58
- comments in page files.
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 (`transportRule`)**: an endpoint, a named slice's `init()` or a root slice that declares no guards is
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>`; ⑧ `.guard(() => signedIn())`
45
- (`@libs/shared/webkit`) on `_layout.tsx` (a real 3xx before anything renders; `getSelf({ unauthorize })` in a body
46
- under a `.loading()` redirects in-page after I/O); ⑨ CSS (`data-*` + `group-data-[…]`, `<details>`) over client
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
 
@@ -1,53 +1,13 @@
1
- # Page Rule — Route Files, The Route Chain, Heads, Lib Pages
1
+ # Page Rule — The Route Chain, Guards, Heads, Lib Pages
2
2
 
3
- What a file under `page/` may be, how a route declares its arguments and settings, how a route guards itself, how
4
- heads merge, what a CSR bundle shows of a root layout, and how a lib's routes reach an app. `conventions` carries the invariants and the page
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
- - **`.head()` takes JSX — `<title>`, `<meta>`, `<link>` — or a function of the route's args returning it.** One that
121
- throws renders no head (warned about), so a layout's sign-in redirect still answers. There is no metadata object,
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`: `true` takes every lib dep that has a `page` folder, an array takes the libs listed, `false` (the
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`
@@ -3,21 +3,21 @@ import"./index-zyjztrvc.js";
3
3
  import {
4
4
  CodegenLock,
5
5
  WorkspaceExecutor
6
- } from "./index-pc42gxa5.js";
6
+ } from "./index-g4hta169.js";
7
7
  import"./index-j4yvgfhr.js";
8
8
  import {
9
9
  HmrWatcher,
10
10
  WatchRootResolver,
11
11
  ApplicationBuildReporter
12
- } from "./index-6j351de4.js";
12
+ } from "./index-8vger8r0.js";
13
13
  import {
14
14
  AppExecutor2
15
- } from "./index-b372rck5.js";
16
- import"./index-f2arv0mv.js";
17
- import"./index-mnhrqjjq.js";
15
+ } from "./index-smjm20t4.js";
16
+ import"./index-xftdwcdj.js";
17
+ import"./index-zxvw9wme.js";
18
18
  import {
19
19
  ServerGraphFile
20
- } from "./index-0z8sbdme.js";
20
+ } from "./index-zswfx1y8.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-scfsqen7.js";
30
+ } from "./index-6z5cwvq1.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-whvhsb5f.js";
44
+ import"./index-2qhrmtb0.js";
45
45
 
46
46
  // pkgs/@akanjs/devkit/incrementalBuilder/incrementalBuilder.proc.ts
47
47
  import path6 from "path";
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  GlobalConfig,
4
4
  CloudApi
5
- } from "./index-45aprybg.js";
5
+ } from "./index-akep88g2.js";
6
6
 
7
7
  // pkgs/@akanjs/cli/tunnel/TunnelShare.ts
8
8
  import { TunnelAgent } from "akanjs/server/tunnel";
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  execEmoji,
4
4
  Executor
5
- } from "./index-pc42gxa5.js";
5
+ } from "./index-g4hta169.js";
6
6
  // pkgs/@akanjs/devkit/executors/moduleExecutor.ts
7
7
  class ModuleExecutor extends Executor {
8
8
  sys;
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  runner,
4
4
  script
5
- } from "./index-652f3bs8.js";
5
+ } from "./index-c1sfw20m.js";
6
6
  import {
7
7
  bilingualLabelForField,
8
8
  bilingualDescriptionForField,
@@ -10,10 +10,10 @@ import {
10
10
  sourceFile,
11
11
  generatedFilesForSync,
12
12
  createPassedPrimitiveReport
13
- } from "./index-1c2807kg.js";
13
+ } from "./index-94a2xrv1.js";
14
14
  import {
15
15
  PageScript
16
- } from "./index-y2g0s9tn.js";
16
+ } from "./index-7jknrhws.js";
17
17
  import {
18
18
  pluralizeName
19
19
  } from "./index-nz8prx9g.js";
@@ -22,7 +22,7 @@ import {
22
22
  } from "./index-va90m8nd.js";
23
23
  import {
24
24
  ModuleExecutor
25
- } from "./index-whvhsb5f.js";
25
+ } from "./index-2qhrmtb0.js";
26
26
 
27
27
  // pkgs/@akanjs/cli/module/module.script.ts
28
28
  import { capitalize as capitalize2 } from "akanjs/common";
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  DesktopBin
4
- } from "./index-ymgsvhc5.js";
4
+ } from "./index-adbcqv0k.js";
5
5
  // pkgs/@akanjs/devkit/mobile/desktopServerStage.ts
6
6
  import { cp, mkdir, readdir, rm, writeFile } from "fs/promises";
7
7
  import path from "path";
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  SOURCE_EXTS,
4
4
  WatchRootResolver
5
- } from "./index-6j351de4.js";
5
+ } from "./index-8vger8r0.js";
6
6
  import {
7
7
  loaderFor,
8
8
  BarrelAnalyzer,
@@ -18,7 +18,7 @@ import {
18
18
  CsrDevPaths,
19
19
  PagesEntrySourceGenerator,
20
20
  PagesBundleBuilder
21
- } from "./index-0z8sbdme.js";
21
+ } from "./index-zswfx1y8.js";
22
22
  import {
23
23
  FileSys2
24
24
  } from "./index-zyjztrvc.js";
@@ -26,7 +26,7 @@ import {
26
26
  AsyncDefaultExportDetector,
27
27
  StoreBootstrap,
28
28
  resolveSsrPageEntriesForApp
29
- } from "./index-b372rck5.js";
29
+ } from "./index-smjm20t4.js";
30
30
 
31
31
  // pkgs/@akanjs/devkit/frontendBuild/clientEntryDiscovery.ts
32
32
  import fs from "fs";
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  runner,
4
4
  script
5
- } from "./index-652f3bs8.js";
5
+ } from "./index-c1sfw20m.js";
6
6
 
7
7
  // pkgs/@akanjs/cli/page/page.runner.ts
8
8
  class PageRunner extends runner("page") {
@@ -5,10 +5,10 @@ import {
5
5
  import {
6
6
  JsonFormatter,
7
7
  AkanAppConfig
8
- } from "./index-pc42gxa5.js";
8
+ } from "./index-g4hta169.js";
9
9
  import {
10
10
  ErrorReport
11
- } from "./index-whvhsb5f.js";
11
+ } from "./index-2qhrmtb0.js";
12
12
 
13
13
  // pkgs/@akanjs/devkit/app/applicationBuildReporter.ts
14
14
  import { Logger } from "akanjs/common";
@@ -1,10 +1,10 @@
1
1
  // @bun
2
2
  import {
3
3
  AppExecutor2
4
- } from "./index-b372rck5.js";
4
+ } from "./index-smjm20t4.js";
5
5
  import {
6
6
  LibExecutor2
7
- } from "./index-f2arv0mv.js";
7
+ } from "./index-xftdwcdj.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-652f3bs8.js";
18
+ } from "./index-c1sfw20m.js";
19
19
 
20
20
  // pkgs/@akanjs/devkit/workflow/artifacts.ts
21
21
  import { capitalize as capitalize2 } from "akanjs/common";
@@ -5,14 +5,14 @@ import {
5
5
  WorkspaceExecutor,
6
6
  ServerEnvProfile,
7
7
  AkanAppConfig
8
- } from "./index-pc42gxa5.js";
8
+ } from "./index-g4hta169.js";
9
9
  import {
10
10
  resolveAppId,
11
11
  targetHtmlFilename
12
12
  } from "./index-m9jj544v.js";
13
13
  import {
14
14
  ExitCodeError
15
- } from "./index-652f3bs8.js";
15
+ } from "./index-c1sfw20m.js";
16
16
 
17
17
  // pkgs/@akanjs/devkit/mobile/desktopBin.ts
18
18
  import { chmod, mkdir, rename, rm, writeFile } from "fs/promises";
@@ -1123,14 +1123,14 @@ class NativePublicEnv {
1123
1123
  return [...new Set([...Object.keys(a), ...Object.keys(b)])].filter((key) => a[key] !== b[key]).sort((x, y) => x < y ? -1 : x > y ? 1 : 0);
1124
1124
  }
1125
1125
  static async built(app) {
1126
- const { CsrArtifactBuilder } = await import("./csrArtifactBuilder-gtvff6k7.js");
1126
+ const { CsrArtifactBuilder } = await import("./csrArtifactBuilder-9zvt4tqd.js");
1127
1127
  const file = Bun.file(CsrArtifactBuilder.publicEnvPath(app));
1128
1128
  if (!await file.exists())
1129
1129
  return null;
1130
1130
  return NativePublicEnv.of(await file.json());
1131
1131
  }
1132
1132
  static async inlined(app) {
1133
- const { CsrArtifactBuilder } = await import("./csrArtifactBuilder-gtvff6k7.js");
1133
+ const { CsrArtifactBuilder } = await import("./csrArtifactBuilder-9zvt4tqd.js");
1134
1134
  const file = Bun.file(CsrArtifactBuilder.publicEnvPath(app));
1135
1135
  const env = await file.exists() ? await file.json() : process.env;
1136
1136
  return Object.fromEntries(Object.entries(env).flatMap(([key, value]) => key.startsWith("AKAN_PUBLIC_") && typeof value === "string" ? [[key, value]] : []));
@@ -9,10 +9,10 @@ import {
9
9
  UpdatePackFolder,
10
10
  NativePublicEnv,
11
11
  NativeApp
12
- } from "./index-ymgsvhc5.js";
12
+ } from "./index-adbcqv0k.js";
13
13
  import {
14
14
  ExitCodeError
15
- } from "./index-652f3bs8.js";
15
+ } from "./index-c1sfw20m.js";
16
16
  import {
17
17
  ConfigLock
18
18
  } from "./index-bqbf654f.js";
@@ -5,24 +5,24 @@ import {
5
5
  import {
6
6
  Executor,
7
7
  WorkspaceExecutor
8
- } from "./index-pc42gxa5.js";
8
+ } from "./index-g4hta169.js";
9
9
  import {
10
10
  getDirname2,
11
11
  FileSys2
12
12
  } from "./index-zyjztrvc.js";
13
13
  import {
14
14
  AppExecutor2
15
- } from "./index-b372rck5.js";
15
+ } from "./index-smjm20t4.js";
16
16
  import {
17
17
  LibExecutor2
18
- } from "./index-f2arv0mv.js";
18
+ } from "./index-xftdwcdj.js";
19
19
  import {
20
20
  PkgExecutor2
21
- } from "./index-mnhrqjjq.js";
21
+ } from "./index-zxvw9wme.js";
22
22
  import {
23
23
  ModuleExecutor,
24
24
  ErrorReport
25
- } from "./index-whvhsb5f.js";
25
+ } from "./index-2qhrmtb0.js";
26
26
 
27
27
  // pkgs/@akanjs/devkit/commandDecorators/camelToKebabCase.ts
28
28
  var camelToKebabCase = (str) => str.replace(/([A-Z])/g, "-$1").toLowerCase();