@akanjs/cli 3.1.1-rc.16 → 3.1.1-rc.18

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 (118) hide show
  1. package/.build-stamp +1 -1
  2. package/{CodeAgent-23ewzxqa.js → CodeAgent-fbcq8vks.js} +2 -2
  3. package/{CodeTui-kc99fk78.js → CodeTui-0626gxqd.js} +1 -1
  4. package/TunnelShare-2p24xxza.js +14 -0
  5. package/agent.command-hpza0pg9.js +46 -0
  6. package/akanCode.js +5 -3
  7. package/{application.command-bvfd1680.js → application.command-3a7q1hs2.js} +11 -10
  8. package/{applicationBuildRunner-4ajaesk1.js → applicationBuildRunner-s7yt71j4.js} +5 -5
  9. package/buildBatch.proc.js +6 -6
  10. package/{cloud.command-f2w40fyy.js → cloud.command-4vg0pcea.js} +15 -14
  11. package/cloud.script-nkmeyhet.js +25 -0
  12. package/{code.command-dbhhnahn.js → code.command-fbntb67p.js} +6 -6
  13. package/commandManifest.json +1 -1
  14. package/{context.command-yswjwv6y.js → context.command-31rm54v0.js} +18 -18
  15. package/context.runner-w01a32ph.js +26 -0
  16. package/{guideline.command-ztx6dkpk.js → guideline.command-cv3by2ng.js} +3 -3
  17. package/guidelines/conventions/core.md +104 -0
  18. package/guidelines/conventions/rules/app.md +83 -0
  19. package/guidelines/conventions/rules/auth.md +45 -0
  20. package/guidelines/conventions/rules/config.md +56 -0
  21. package/guidelines/conventions/rules/constant.md +24 -0
  22. package/guidelines/conventions/rules/gates.md +31 -0
  23. package/guidelines/conventions/rules/layer.md +25 -0
  24. package/guidelines/conventions/rules/migration.md +27 -0
  25. package/guidelines/conventions/rules/module.md +90 -0
  26. package/guidelines/conventions/rules/page.md +56 -0
  27. package/guidelines/conventions/rules/sensitive.md +16 -0
  28. package/guidelines/conventions/rules/server.md +86 -0
  29. package/guidelines/conventions/rules/ssr.md +47 -0
  30. package/guidelines/conventions/rules/style.md +43 -0
  31. package/guidelines/conventions/rules/test.md +34 -0
  32. package/guidelines/conventions/rules/ts.md +95 -0
  33. package/guidelines/conventions/rules/tsx.md +75 -0
  34. package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
  35. package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +3 -3
  36. package/incrementalBuilder.proc.js +6 -6
  37. package/{index-xjwcp91m.js → index-05nxx4m5.js} +43 -12
  38. package/{index-k9k18vq9.js → index-0ht91675.js} +37 -59
  39. package/{index-er16p89s.js → index-0zwznvv1.js} +1 -1
  40. package/{index-76jwsm3g.js → index-0zyatd10.js} +2 -2
  41. package/{index-97fsvy66.js → index-12kzwak1.js} +3 -3
  42. package/{index-005dqc83.js → index-1dhf8ymv.js} +2 -2
  43. package/{index-00ke4phc.js → index-3gccwenr.js} +1 -1
  44. package/{index-2epb3wgh.js → index-3txrjt6n.js} +2 -2
  45. package/{index-7ndgffg4.js → index-57q1ayd2.js} +18 -1240
  46. package/index-5kh9scvs.js +514 -0
  47. package/index-5n5hds19.js +1246 -0
  48. package/{index-9sa6abze.js → index-6269mf2s.js} +10 -9
  49. package/{index-921cxqrd.js → index-64g9fsjy.js} +41 -12
  50. package/index-7zeb5r1p.js +653 -0
  51. package/{index-s4c2y5gs.js → index-8s8b4eba.js} +45 -4
  52. package/{index-4332q6yj.js → index-922k2zwq.js} +3 -3
  53. package/{index-m6qgr1rx.js → index-9ndw5d8j.js} +7 -7
  54. package/{index-xfp4dcnx.js → index-et6ce601.js} +1 -1
  55. package/{index-saj9cx3a.js → index-f5adsa58.js} +4 -4
  56. package/{index-vgt25eh1.js → index-fbewhg4g.js} +7 -32
  57. package/{index-ysyt782g.js → index-hm7x0c11.js} +4 -4
  58. package/{index-2p1brf5e.js → index-hvv5rnaq.js} +2 -2
  59. package/index-jje9qzyq.js +27 -0
  60. package/{index-rxse80x6.js → index-js1gj6f6.js} +12 -10
  61. package/{index-p2pahmsa.js → index-kjrvwzav.js} +3 -3
  62. package/index-m6r88hhr.js +3582 -0
  63. package/{index-mk391h0z.js → index-mt0wa941.js} +4 -4
  64. package/{index-m93qg20j.js → index-mwj9q2ya.js} +1 -1
  65. package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
  66. package/index-r2wedvqn.js +138 -0
  67. package/{index-gxj80jz7.js → index-rvynj5gz.js} +1 -1
  68. package/{index-m54n0v29.js → index-tdv66eah.js} +4 -4
  69. package/{index-vq77g679.js → index-w134p86k.js} +1 -1
  70. package/{index-deeskxjh.js → index-wfczhj1z.js} +14 -36
  71. package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
  72. package/{index-qx4r4cj2.js → index-x5ecanqh.js} +2 -2
  73. package/{index-nzfgyw3b.js → index-zre4m2ce.js} +4 -4
  74. package/index.js +23 -22
  75. package/{library.command-hmbkcwzw.js → library.command-sh70fyvy.js} +3 -3
  76. package/{localRegistry.command-sq5p4c9x.js → localRegistry.command-2nbyy84d.js} +14 -13
  77. package/{module.command-n4z29zcv.js → module.command-n0bmtzwy.js} +5 -5
  78. package/{package.command-20025dy3.js → package.command-7h9r51bz.js} +3 -3
  79. package/package.json +2 -2
  80. package/{page.command-q8fvpjer.js → page.command-vjtpfbb1.js} +3 -3
  81. package/{pipeline.command-8j97fq88.js → pipeline.command-c93se3ar.js} +2 -2
  82. package/{primitive.command-e5y6dqp1.js → primitive.command-a3075qp2.js} +6 -6
  83. package/{projectTypecheck-tbdye9k3.js → projectTypecheck-sf9xwaga.js} +1 -1
  84. package/{prompter-76k56b37.js → prompter-hgcta8pb.js} +1 -1
  85. package/quality.command-dw1y9hmy.js +76 -0
  86. package/{repair.command-dq1gckth.js → repair.command-tg57d8yt.js} +5 -5
  87. package/{scalar.command-5vwf152w.js → scalar.command-cwzge353.js} +4 -4
  88. package/skills/akan-agent/SKILL.md +36 -0
  89. package/skills/akan-debug/SKILL.md +3 -3
  90. package/skills/akan-deps/SKILL.md +1 -2
  91. package/skills/akan-mcp/SKILL.md +40 -0
  92. package/skills/akan-page/SKILL.md +44 -0
  93. package/skills/akan-query/SKILL.md +38 -0
  94. package/skills/akan-runtime/SKILL.md +40 -0
  95. package/skills/akan-scaffold/SKILL.md +16 -6
  96. package/skills/akan-transport/SKILL.md +40 -0
  97. package/skills/akan-validate/SKILL.md +13 -11
  98. package/{subspace.command-182be8vj.js → subspace.command-3h03c7kc.js} +8 -8
  99. package/templates/workspaceRoot/.gitignore.template +3 -0
  100. package/templates/workspaceRoot/AGENTS.md.template +4 -10
  101. package/{tunnel.command-bfzj7xkb.js → tunnel.command-czaz6ys4.js} +7 -7
  102. package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
  103. package/typecheck.proc.js +6 -1
  104. package/verify.command-nzwhtz71.js +91 -0
  105. package/{workflow.command-3g53242s.js → workflow.command-srhky88x.js} +23 -13
  106. package/{workspace.command-h7399jwv.js → workspace.command-9stchcd2.js} +31 -29
  107. package/TunnelShare-dk2gw78d.js +0 -14
  108. package/agent.command-knp5j7bq.js +0 -25
  109. package/cloud.script-2r82sv0f.js +0 -24
  110. package/context.runner-c3wsh2jw.js +0 -26
  111. package/guidelines/conventions/conventions.instruction.md +0 -663
  112. package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
  113. package/index-4t4qb8jg.js +0 -279
  114. package/index-hvg3esm0.js +0 -1844
  115. package/index-zzvvc845.js +0 -74
  116. package/quality.command-168pt5vm.js +0 -1788
  117. package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
  118. package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
@@ -0,0 +1,45 @@
1
+ ---
2
+ description: Guards and authorization on signals and srvkit: slice guard maps, endpoint guards, the acting user.
3
+ paths:
4
+ - "{apps,libs}/**/*.signal.ts"
5
+ - "{apps,libs}/**/srvkit/**"
6
+ ---
7
+
8
+ # Authorization
9
+
10
+ - **Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.**
11
+ `guards: { cru: false }` (or per verb) takes a generated verb off HTTP; `mcp: { cru: false }` only keeps it off the
12
+ 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 is unguarded. `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 is warned at boot and never published to MCP, which also refuses a
17
+ mutation guarded only by `Public`.
18
+ - 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)`.
21
+ - Keep `static name = "User";` on guard classes — `fetch` serializes it and the API explorer filters on it. It looks
22
+ dead, so comment it.
23
+ - **Every guard declares `static scope: GuardScope`, no default**: `"account"` reads only the caller (MCP listings
24
+ evaluate it to hide entries), `"resource"` needs the call's arguments and fails closed without them. `SignedIn` /
25
+ `Admin` / roles are `"account"`, every `Can<Verb><Model>` is `"resource"`; `Person` adds `static agents = false`.
26
+ - `Can<Verb><Model>` guards in `srvkit/guards.ts` fail closed and ship with the model's library (`transportRule`).
27
+ 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
+ answers every caller. Write `guards: [Public]` when anonymous access is the intent.
32
+
33
+ - **A `slice()` takes its guard map as a second argument**, `slice(srv.task, { guards: { root: Admin, get: SignedIn,
34
+ cru: SignedIn } }, (init) => ({...}))`. An `endpoint()` takes no guard argument at all —
35
+ `endpoint(srv.task, ({ mutation }) => ({...}))` — so **every custom `mutation` / `query` / `message` names its own
36
+ `guards: [...]` array**: `mutation(cnst.Task, { guards: [SignedIn] })`. `Public` always allows; other guards
37
+ implement the `Guard` interface in `srvkit/` (server-only).
38
+ - **Read the caller inside a guard** with `context.get<T>("account")`, which works on HTTP and websocket calls
39
+ alike — never branch on `getHttpContext()` / `getWebSocketContext()`. Every guard class also declares
40
+ `static scope: GuardScope`, `"account"` or `"resource"`, with no default.
41
+ - **Read the current user inside a custom endpoint** by injecting an `InternalArg` with `.with(...)`:
42
+ `mutation(cnst.Task, { guards: [SignedIn] }).with(CurrentUserId).exec(async function (currentUserId) { ... })`.
43
+ - **Auto-generated CRUD and `serve()` service methods / lifecycle hooks do not receive session context.** If an
44
+ operation needs the acting user, expose a custom endpoint that takes it via `.with(CurrentUserId)` — never trust a
45
+ client-supplied user id.
@@ -0,0 +1,56 @@
1
+ ---
2
+ description: Runtime and build configuration: akan.config.ts, main.ts, env narrowing, native apps, database modes.
3
+ paths:
4
+ - "{apps,libs}/*/akan.config.ts"
5
+ - "{apps,libs}/*/main.ts"
6
+ - "{apps,libs}/*/env/**"
7
+ ---
8
+
9
+ # Runtime And Build Configuration
10
+
11
+ Declared in `akan.config.ts`, narrowed — never widened — by an env at boot; domain code reaches none of it
12
+ (`runtimeRule`).
13
+
14
+ - **`web: true | false | { csr: boolean }`** — `{ csr: false }` drops the CSR bundle native apps ship, `false` is
15
+ API-only.
16
+ - **Route prefixes move together**: `new AkanApp({ prefix, websocketPrefix })` in `main.ts`, mirrored in
17
+ `api: { … }` in `akan.config.ts` for a CSR shell or native bundle. Read them with `getApiPrefix()` /
18
+ `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
+
31
+ ## Running An App
32
+
33
+ - After changing application code, run `bun run akan start <appName>` (`a,b`, `a b`, or `all` for several); check
34
+ the production build with `bun run akan build <appName>`.
35
+ - A supervised session writes `local/apps/<app>/runtime/dev.log` (previous: `dev.prev.log`) — hand over that path,
36
+ not a paste of the repainting full-screen view. Keys, `--plain`, boot waves, `--kill`, watch scope, running a
37
+ built artifact, booting a server in a test: `runtimeRule`.
38
+
39
+ ## Native Apps
40
+
41
+ `native: { desktop: { server: true } }` in `akan.config.ts` is all a desktop app that carries its own server needs.
42
+ A `start-*` command loads its pages from `akan start`, so run that first; a desktop app that carries its server
43
+ starts it itself. The full contract — targets, updates, what the carried server ships — is
44
+ `akan guideline show runtimeRule`.
45
+
46
+ ```bash
47
+ akan start-desktop <app> # Run the desktop app on this computer
48
+ akan start-ios <app> # Run it in a simulator or on an iPhone (start-android alike)
49
+ akan build-desktop <app> # Build it for this computer into dist/native/<app>/<target>/build
50
+ akan build-desktop <app> --installer true # Windows: add a per-user setup program
51
+ akan update-keygen <app> # Make the update signing key once; print its public key
52
+ akan publish-update <app> # Build a key-signed release for updates.url; --sign true also code-signs it
53
+ ```
54
+
55
+ A device capability the framework lacks is a plugin the app owns in `native/<id>/`: `native-plugin.json`,
56
+ `src/index.ts` (the page API, used from a `webkit/` hook), `src/desktop.ts`, Kotlin and Swift.
@@ -0,0 +1,24 @@
1
+ ---
2
+ description: Model and scalar shapes in *.constant.ts: the five layers, scalars, defaults and field kinds.
3
+ paths:
4
+ - "{apps,libs}/**/*.constant.ts"
5
+ ---
6
+
7
+ # Scalar Modeling
8
+
9
+ - Models use `via` from `akanjs/constant`, all five layers (`Input`, `Object`, `Light<Model>`, `<Model>`,
10
+ `<Model>Insight`). `Int` for counts, `Float` only for decimals, `ID` for references; structured fields over `Any`.
11
+ - Import `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `ImageResult`, `enumOf`, `dayjs` from `akanjs/base`;
12
+ `String` / `Boolean` / `Date` are globals. No `JSON` scalar (use `Any`), no `Number`, and `Binary` / `Upload` are
13
+ never fields — a file is `field(File).optional()` / `field([File])`, uploaded by the generated
14
+ `upload<Field>On<Model>` (which `Field.Img` / `Files` and siblings use when handed the generated setter); it marks
15
+ the field in `<model>FormUploading` while the request runs and drops a result whose form was set whole meanwhile
16
+ (or, on a single field, re-picked) — gate a hand-written submit on it.
17
+ - Defaults: a literal for scalars, a thunk for anything constructed (`default: () => dayjs()`). Arrays
18
+ `field([T])`; optional `.optional()`.
19
+ - **`field.hidden` / `field.secret` read `null` on the client while the type declares them** — guard with `??` or
20
+ `== null`, never `=== undefined` or a default. `field.visual(T)` is rendered but stripped from every agent and MCP
21
+ read. Full contract: `fieldRule`.
22
+
23
+ - **No `static` on an `XObject` or `LightX` class** (`no-static-in-object-light-model`) — `via()` mixes in their
24
+ prototypes only; use `XInput` (or a scalar), `X`, or `XInsight`.
@@ -0,0 +1,31 @@
1
+ ---
2
+ description: The akan lint gates on size, store reach, where writes start and per-item calls, and the baseline.
3
+ paths:
4
+ - "{apps,libs}/**/*.tsx"
5
+ - "{apps,libs}/**/*.{store,service,document}.ts"
6
+ - "{apps,libs}/*/{ui,webkit}/**"
7
+ - "{apps,libs}/*/akan.baseline.json"
8
+ ---
9
+
10
+ # Lint Gates
11
+
12
+ - **Size, store reach, where writes start, and per-item calls fail `akan lint`** for an app or lib, each failure
13
+ naming its rule and the `akan workflow plan …` path that fixes it:
14
+ - `akan.size.file`: a `Zone` / `Util` / `Template` / `Unit` / `View`, a `*.store.ts`, or a `ui/` / `webkit/` file
15
+ over 400 lines; a service or document over 500; an abstract over 300. `akan.size.component`: a component or hook
16
+ over 250. `akan.component.store-access`: a component or hook reaching `st` more than 16 times (form setters aside).
17
+ - `akan.write.placement`: a server write leaves the browser only through a store action, started by a module
18
+ component — no `fetch.<mutation>` outside a `*.store.ts`, and no writing `st.do.*` in `ui/` or `webkit/`, which
19
+ take the write as an `onX` prop or hook argument.
20
+ - `akan.store.multi-write`, `akan.store.root-write-chain`, `akan.component.write-chain`: a store action, a store
21
+ `static`, or one handler (a hook's included) sending two or more writes — directly, through a sibling action,
22
+ through another store via `RootStore`, or once per item in a loop or `map`. Make them one service method
23
+ (`this.transaction(fn)`, a side effect in `this.afterCommit(fn)`) behind one endpoint, taking the list, that the
24
+ action calls once.
25
+ - `akan.service.call-in-loop`: a service method an `endpoint` or `slice` reaches calling a service, a model or a
26
+ generated query once per item (`for … of`, `map`, `forEach`); load the set once (`load<Model>Many`, one
27
+ filter query) or write it once. An `internal` job and a counted loop (a retry, paging) are spared.
28
+ - `akan.baseline.json` (`akan.baseline.growth`) records, per rule, the debt adopted with the gate, and is compared
29
+ with its copy at the fork point of the default branch, so it only ever shrinks: never add or raise an entry. A size,
30
+ store-reach or per-item entry with a `reasons` line is an exception a person decided on, never an agent; the write
31
+ rules take no exceptions.
@@ -0,0 +1,25 @@
1
+ ---
2
+ description: The shared layers common/, webkit/, srvkit/, ui/, plugin/, native/: what each admits.
3
+ paths:
4
+ - "{apps,libs}/*/{common,webkit,srvkit,ui,plugin,native}/**"
5
+ ---
6
+
7
+ # Layer Placement
8
+
9
+ | Folder | Admission test | Naming |
10
+ |---|---|---|
11
+ | `common/` | pure, isomorphic, zero-dependency; imports only sibling `common/*` and `akanjs/base` (so no `Err`, and no throwing code) | camelCase file named after its single export |
12
+ | `webkit/` | touches `window` / `navigator` / the native bridge (`akanjs/client/native[/<plugin id>]`), or is a React hook; sends no server write | `use<Thing>.tsx`, `.tsx` even without JSX |
13
+ | `srvkit/` | touches `node:*`, `Bun`, `process.env`, a secret, or a server SDK | camelCase file, PascalCase class |
14
+ | `ui/` | renders JSX or defines a look (`Recipe/`, a lib's `tokens.css`), not bound to one model; sends no server write | PascalCase component, camelCase sidecar, `Recipe/<name>.ts` |
15
+ | `plugin/` | a build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
16
+ | `native/` | a native plugin the app or lib owns — its page API reached only through a `webkit/` hook (`runtimeRule`) | `native/<id>/` |
17
+
18
+ - Hooks return a named object of async closures, never a tuple.
19
+ - Recipes live in `ui/`: `webkit/` hooks are `"use client"`, and `common/` cannot import `akanjs/ui`.
20
+ - A layer-root `index.ts` is generated; a `ui/<Folder>/index.tsx` building a namespace is hand-written (a generated
21
+ barrel holds only `export *` lines). `ui/<Folder>/index_.tsx` is the `"use client"` + `lazy()` boundary beside a
22
+ server-safe `index.tsx` — merging the pair breaks RSC.
23
+
24
+ - **No `//!` or `/*!` in browser-reachable code** (`ui/`, `webkit/`, `common/`, `page/**/*.tsx`, `*.constant.ts`,
25
+ `*.store.ts`, module components; `no-bang-comment-in-client`) — Bun keeps both through minification. Use `// FIXME:`.
@@ -0,0 +1,27 @@
1
+ ---
2
+ description: Data migrations under script/migration: table() writes, plan hashing and resumable applies.
3
+ paths:
4
+ - "{apps,libs}/*/script/migration/**"
5
+ ---
6
+
7
+ # Data Migrations
8
+
9
+ A change that reshapes stored documents ships a migration: `akan create-migration <name> <app>` writes
10
+ `script/migration/<yyyyMMddHHmm>_<name>.ts`, a default-exported `migration(title)` from `akanjs/server`, which
11
+ `akan migrate <app>` runs locally and `bun main.js ops migrate` in a built container (the `cheatsheet/dev/migration`
12
+ docs page).
13
+
14
+ - The new code reads both shapes until every environment has applied it — a deploy serves traffic first.
15
+ - Write only through `table(refName)`, never a service, a document or raw `sql` — a service write runs the model's
16
+ hooks, and none of them reaches the change log a rollback reverts. Call nothing outside the database.
17
+ - `plan` reads only and must hash the same on unchanged data: a timestamp, `createId()` or random value in it makes
18
+ every `apply --expect <planHash>` refuse as `planChanged`.
19
+ - Past about five seconds on SQLite, an apply's one transaction makes the live server's writes fail. Take
20
+ `.config({ transaction: false })`, which commits each `rewrite` batch and resumes a `partial` run from the top of
21
+ `apply` — so a second run must change nothing (a `where` the new shape no longer matches).
22
+ - `$ne` leaves out rows whose path is missing or `null` (match them with `{ path: null }`; `$exists: false` misses a
23
+ stored `null`); `find`, `count` and `rewrite` include removed rows unless `{ withRemoved: false }`; a `table()` write
24
+ leaves `updatedAt` alone.
25
+ - Throw a plain `Error` an operator can act on. Never edit a migration an environment has applied — write another;
26
+ delete it once every environment has, unless its `.rollback(fn)` may still be needed: without the file a rollback
27
+ runs the default undo.
@@ -0,0 +1,90 @@
1
+ ---
2
+ description: Domain modules under lib/: what each module file owns, and the modeling gotchas.
3
+ paths:
4
+ - "{apps,libs}/**/lib/**"
5
+ ---
6
+
7
+ # Domain Modules
8
+
9
+ A business concept is one `lib/` folder holding its logic files
10
+ (`<model>.constant|dictionary|document|service|signal|store.ts`) and components
11
+ (`<Model>.Template|Unit|View|Zone|Util.tsx`). `constant`, `dictionary` and
12
+ `signal` are shared contracts with no platform-specific dependency; persistence and queries live in `document`,
13
+ orchestration in `service`, client state in `store`; `Template` is forms, `Unit` list/card items, `View` details,
14
+ `Zone` page sections, `Util` domain UI helpers.
15
+
16
+ - **`<model>.constant.ts`** — `enumOf("camelName", [...] as const)` classes, then
17
+ `XInput → XObject → LightX → X → XInsight`, one blank line apart, `XInsight` even when empty. **Display and
18
+ predicate logic goes on `LightX`** (`isNew()`, `canWrite(user?)`), which server and client both hold, never a util
19
+ module — the most commonly missed rule. Collection helpers are `static` on `X`; a non-obvious field gets a short
20
+ trailing comment. `Date` fields are prototype accessors that a spread drops — copy with `new cnst.X().set(user)`
21
+ (`fieldRule`).
22
+ - **`<model>.document.ts`** — `XFilter extends from(...)` → `X extends by(...)` → `XModel extends into(...)`,
23
+ `sort: {}` always present. Chain methods validate → mutate → `return this`, never `save()` (the caller saves, so
24
+ `org.removeUser(id).removeInvite(id).save()` composes), with a one-line transition comment above each. Atomic
25
+ counters live on the Model class with the updater callback, returning `!!modifiedCount`; indexes and derived
26
+ totals go in `static override _onSchema`. **Removal is soft** and reads see live rows unless
27
+ `{ withRemoved: true }`; the one hard delete is `purge<Filter>` / `purgeMany`, for data past retention.
28
+ `updateById` / `removeById` fire no hooks — a cascading or `_postRemove` model removes through
29
+ `remove<Model>(id)`, and `pickAndWrite` writes through the save hooks (`queryRule`).
30
+ - **`<model>.service.ts`** — a few lines: load → chain → `return await ….save()` (keep the `return await`). Side
31
+ effects go in `override async _preUpdate` / `_postCreate`; fire-and-forget is `void`-ed. Load every referenced
32
+ document, then save, then notify; writes that must land together go in `this.transaction(async () => …)` and
33
+ their notification in `this.afterCommit(…)` (`queryRule`). Return `null` / `false` for not allowed or not found;
34
+ the signal decides whether that is an error.
35
+ - **`<model>.signal.ts`** — `XInternal` → `XSlice` → `XEndpoint`, all three even when empty; `exec` is a one-liner
36
+ calling the service.
37
+ - **`<model>.store.ts`** — custom actions only for a toast, an optimistic update, or a multi-field write:
38
+ `await fetch.X` → `this.setX(...)` → toast, or mutate the client model, `void fetch.*`, then commit.
39
+ `this.pick(...)` when the value must exist, `this.get()` when it may not, `this.set({...})` to write; lists through
40
+ the collection API (`xList.set(x).save()`), not spread. **Another store is reached through `this`**:
41
+ `import type { RootStore } from "../st"` (type-only — `st.ts` imports every store), then
42
+ `(this as unknown as RootStore).logout()` or `.set({ … })` / `.get()`; every store is mixed into one root at
43
+ runtime, so the cast only names what `this` already is.
44
+ - **`<model>.dictionary.ts`** — empty stages still written:
45
+ `.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`;
46
+ every `.arg()` named, framework `skip` / `limit` / `sort` included; `modelDictionary` / `scalarDictionary` /
47
+ `serviceDictionary` by module kind.
48
+ - **`<module>.abstract.md`** — a title, one sentence naming what the module owns, a `## Rules` list of two to five
49
+ invariants the code cannot show, an optional workflow chain (`draft -> signed -> active`). Never restate fields or
50
+ types; update it when an invariant or workflow changes.
51
+
52
+ - **`{name}`, never `{{name}}`** (`no-double-brace-placeholder`), in a dictionary `.error()` / `.translate()` entry —
53
+ only single braces interpolate.
54
+ - **Never return a value from a store action** (`no-return-in-store-action`) — actions dispatch through `st.do.*` as
55
+ `void`; write state with `this.set({ ... })`. A bare `return;`, a nested callback's `return`, a getter, and a `static`
56
+ helper are fine.
57
+ - **Never redeclare a generated CRUD endpoint name** in `*.signal.ts` (`no-redeclare-predefined-endpoint`).
58
+ - **Never ask a list for more than 500 rows** (`no-oversized-list-limit`) — the server serves at most 500 per
59
+ request and drops the rest without an error, so `fetch.xListInY(0, 10000)` silently stops at row 500. Page with
60
+ skip/limit or `st.do.loadMoreOf<X>()` while `hasMoreOf<X>`, or compute the figure in an insight or an endpoint.
61
+
62
+ ## Modeling And Query Gotchas
63
+
64
+ - **Slices return a query, not a list.** A slice `exec` must return `this.<model>Service.query<Filter>(...)`, never
65
+ a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
66
+ `Unknown document field path: 0`. (See Recipe 3.)
67
+ - **Custom endpoint names must not collide with generated CRUD.** `create/update/remove/view/edit/merge<Model>`
68
+ already exist wherever the slice mounts the verb. A collision builds green and the server refuses to boot
69
+ (`[DI:fetch]`) — pick a distinct verb.
70
+ - **Numbers are `Int` or `Float`, never `Number`.** `field(Number)` / `.body("x", Number)` fail to typecheck.
71
+ - **Array fields use `field([T])`** — `tags: field([String])`, `images: field([File])`.
72
+ - **Reading a secret field needs an explicit select, and the two call sites spell it differently.**
73
+ `field(...).secret()` values are stripped from query results by default. The model facade takes the projection
74
+ **bare** — `this.userModel.pickById(id, { passwordHash: true })`, likewise `pickOne` / `find` / `findOne` /
75
+ `findById`. A generated filter accessor takes it **inside the option object** —
76
+ `this.userModel.findByAccountId(accountId, statuses, { select: { passwordHash: true } })`. Handing `{ select: … }`
77
+ to the facade projects a field named `select`, which no model has, and throws `Unknown document field path`.
78
+ - **`cascade` names a direction, and the wrong one is a data loss** — `removeRef` on the relation the owner holds,
79
+ `removeWith` on the child's reference to its owner. A query-level removal fires no hooks and therefore no cascade.
80
+ - **`q.search()` is a filter node, not a slice requirement.** `bySearch: filter().arg("text", String).query((text,
81
+ q) => q.search(text, { prefix: true }))` generates `listBySearch` / `countBySearch` / `queryBySearch` /
82
+ `insightBySearch` for free. Only add a search *slice* when the model's data is safe to enumerate.
83
+
84
+ ## Akan Module Abstracts
85
+
86
+ - Before changing a domain, service, or scalar module, read its `*.abstract.md` file first.
87
+ - Update the abstract when business invariants, workflows, or public behavior change.
88
+ - Do not update the abstract for formatting-only, import-only, or style-only changes.
89
+ - Service modules live in `lib/_<service>`, but their abstract file is `<service>.abstract.md`.
90
+ - Keep an abstract short — the invariants the code cannot show, and nothing it already states. `akan quality scan` warns past 300 lines.
@@ -0,0 +1,56 @@
1
+ ---
2
+ description: Route files under page/: the one chain, params, heads, guards and lib pages.
3
+ paths:
4
+ - "{apps,libs}/**/page/**"
5
+ ---
6
+
7
+ # Akan Page Routing
8
+
9
+ Full contract — guards, apps, heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
10
+
11
+ - `page/` holds `.tsx` route modules only: `<routeName>.tsx` or `_index.tsx`, `_layout.tsx`, `_overrides.tsx` — no
12
+ other `_*.tsx`, helpers, `.ts` / `.js` files, or uppercase filenames. `[id]` is a dynamic segment, `(group)` a
13
+ route group.
14
+ - **A route file exports one chain** — `page()`, `layout()` in a `_layout.tsx`, `rootLayout()` in a root
15
+ `_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
16
+ `.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
17
+ 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.
20
+ - `.head()` takes JSX or a function returning it — never a metadata object; deeper heads replace by tag identity,
21
+ and a canonical link / `og:url` comes only from the page's own `.head()`.
22
+ - In a CSR bundle a root layout's own markup is hidden: what a person must see from it renders through
23
+ `createPortal(…, document.body)`.
24
+ - `_overrides.tsx` is one `export default override({ Slot: AppComponent })` (`akanjs/ui`), no logic, no
25
+ `"use client"`. The legacy `export default async function Page` shape is never written anew.
26
+ - `libs/<lib>/page` reaches an app through `syncPageLibs`, linked into the generated `page/(libs)/(<lib>)`; edit the
27
+ lib source, never the link. `.config({ devOnly: true })` (a literal) keeps a route out of `akan build`.
28
+
29
+ ```tsx
30
+ export default page()
31
+ .param("orgId", ID)
32
+ .config({ transition: "stack" })
33
+ .guard(() => signedIn())
34
+ .render(({ orgId }) => {
35
+ const { l } = usePage();
36
+ const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
37
+ return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
38
+ });
39
+ ```
40
+
41
+ - `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
42
+ 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
43
+ (title, redirect, link id) in one `Promise.all`.
44
+ - **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it renders throws
45
+ `base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
46
+ `{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
47
+ - Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`; a new workspace has that lib only with
48
+ `create-workspace --libs true`) at `_layout.tsx`, and repeat it on a page that needs more; it is a courtesy, the
49
+ endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits;
50
+ the callback is not a React component, so it takes no name and no return type. No `useState`, `useEffect`, or
51
+ comments in page files.
52
+
53
+ - **SSR auth-gated pages: guard at the layout.** `.guard(() => signedIn())` on the `_layout.tsx` chain answers a
54
+ real 307 before any of it renders, so nested pages never render for signed-out users; a check in `.render()`
55
+ after awaited I/O redirects in-page, as an HTTP 200. `signedIn()` comes from `@libs/shared/webkit`, which a new
56
+ workspace has only with `create-workspace --libs true`.
@@ -0,0 +1,16 @@
1
+ ---
2
+ description: Secret and env files: never print, commit or summarise their values.
3
+ paths:
4
+ - "**/.env*"
5
+ - "**/*secret*"
6
+ - "**/*credential*"
7
+ - "infra/**"
8
+ ---
9
+
10
+ # Secrets And Env Safety
11
+
12
+ - Never print, summarize, commit, or expose real secret values, credentials, tokens, private keys, or `.env`
13
+ contents; document env keys by name with placeholders only.
14
+ - Preserve the env/secret flow through `bun run downloadEnv`, `uploadEnv`, `downloadSecret`, `uploadSecret`, and
15
+ keep Jenkins and deployment assumptions intact unless the task asks otherwise.
16
+ - Treat generated env/secret artifacts as sensitive even when they are not named `.env`.
@@ -0,0 +1,86 @@
1
+ ---
2
+ description: Services, signals, documents and srvkit adapters: calls, queries, injection and where errors are thrown.
3
+ paths:
4
+ - "{apps,libs}/**/*.{service,signal,document}.ts"
5
+ - "{apps,libs}/**/srvkit/**"
6
+ ---
7
+
8
+ # Services And Signals
9
+
10
+ - `serve(...)` services hold business operations. Signals hold contracts: `internal(...)` for init, interval, cron
11
+ and queue jobs (retries, dead letter: `workspaceRecipes` Recipe 5), `slice(...)` for focused data views feeding
12
+ stores and zones, `endpoint(...)` for queries and mutations. External APIs and infrastructure go through
13
+ `srvkit/` adapters injected into services, never vendor clients in domain logic.
14
+
15
+ ## Calls, Queries, Agents
16
+
17
+ - **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
18
+ 30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
19
+ dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
20
+ `option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not a caller. A
21
+ device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
22
+ without `connect: true`, retries through `retry`, and rethrows a remote `Err` as is — never wrapped or re-keyed.
23
+ - **Body types**: `.body()` / `.param()` take scalars, model refs, or `enumOf(...)`; `Int` / `Float`, never
24
+ `Number` (`pkgs/akanjs/signal/endpointInfo.ts`); `Upload` only in a `fileUpload: true` mutation; bytes are
25
+ `Binary`, never `Any`. A model or scalar argument is checked against the request schema on every transport: a
26
+ wrong JSON type, a value outside its enum or a missing required field answers 400 with `data.name` naming the
27
+ path (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's
28
+ input keeps an absent field absent.
29
+ - **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
30
+ whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
31
+ name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
32
+ - **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
33
+ `query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
34
+ A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
35
+ only way to read a `field.secret`. More rows: `loadMoreOf<Model>()` / `hasMoreOf<Model>`, never
36
+ `count > page * limit`. A filter's `remove*` / `update*` are hookless (no cascade). No value is `q.empty`, never
37
+ `q.missing`.
38
+ - **Search**: `q.search(text, { prefix: true })` in a filter, at an AND position, over `text`-role fields; a search
39
+ *slice* only on data safe to enumerate; blank input matches nothing — never a passthrough.
40
+ - **`cascade` names a direction; the wrong one loses data**: `removeRef` on the owner's relation, `removeWith` on
41
+ the child's reference to its owner. A query-level removal runs no cascade.
42
+ - **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
43
+ mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
44
+ `.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
45
+ required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
46
+ screen with `page().prompt(name, description)`, and publish one component a host draws with
47
+ `page().app(name, description, load)` — a read-only tool whose `load` may only query.
48
+ - **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
49
+ every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
50
+ `option.setAgentRequestPolicy`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
51
+ The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
52
+ `st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
53
+ `visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
54
+ `<Agent.Guide instructions="…" />`; model-facing text is English.
55
+
56
+ ## Injection And Adapters
57
+
58
+ - A field named `<refName>Service` / `<refName>Signal` resolves to that registration — the suffix is required
59
+ (`pkgs/akanjs/service/injectInfo.ts`). In a service: `service<srv.XService>()` · `plug(AdapterClass)` /
60
+ `plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
61
+ - `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
62
+ `String` memory.
63
+ - A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
64
+ `storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
65
+ `readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
66
+ `access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
67
+ - **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
68
+ register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
69
+ lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy
70
+ `constructor(options)` adapters migrate only when already being changed. Example and adapter conventions (one
71
+ `#api<T>` with a timeout, pagination, secrets, parameter shapes): `workspaceRecipes` Recipe 2.
72
+
73
+ ## Error Placement
74
+
75
+ - State-machine preconditions throw in `document.ts`, cross-document rules in `service.ts`, request policy in
76
+ `signal.ts` guards. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no Result types.
77
+ - A `pick` or generated `get<Model>` that finds no live row answers 404 `base.error.documentNotFound` by itself
78
+ (`NoDocumentError`); load with a nullable `load<Model>` and throw `Err.NotFound` only to say more than that.
79
+ - An endpoint names the errors it throws on purpose — `errors: { 409: ["ticket.error.locked"] }` in its signal
80
+ option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
81
+ of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
82
+ `Err.is(error, "ticket.error.locked")`.
83
+ - `try/catch` turns an exception into a decision: guards → `logger.warn` → `false`; adapters → `logger.error` →
84
+ `null`; UI `try/finally` resets a spinner. A bodyless `catch {}` needs a one-line reason.
85
+ - Store actions do not `try/catch` (the framework toasts the `Err`); client validation is `msg.error("<key>")` plus
86
+ an early return, never a throw.
@@ -0,0 +1,47 @@
1
+ ---
2
+ description: The client/server boundary and SSR-first rendering for .tsx files and pages.
3
+ paths:
4
+ - "{apps,libs}/**/*.tsx"
5
+ - "{apps,libs}/**/page/**"
6
+ ---
7
+
8
+ # Client/Server Boundary And SSR
9
+
10
+ ## Client / Server Boundaries
11
+
12
+ - `"use client";` tops client component files. It is mechanical by role: `Template`, `Zone`, `Util` always carry it
13
+ on line 1; `Unit`, `View` never do. `usePage()` is legal in server files.
14
+ - A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never `export *` — the server knows a
15
+ client module only by the names it spells out, so `akan start` / `akan build` stop on a star re-export.
16
+ - Keep page props serializable unless the route pattern clearly allows otherwise; be careful importing client-only
17
+ code into pages and layouts. Preserve file roles (`.document.ts`, `.service.ts`, `.store.ts`, `.constant.ts`,
18
+ `.client.ts`), and inspect nearby files before introducing a new boundary pattern.
19
+
20
+ - **Never import across the client/server boundary** (`apps/**`, `libs/**`; `no-import-server-in-client`,
21
+ `no-import-client-in-server`). Client files (`ui/`, `webkit/`, `page/`, `*.store.ts`, every `.tsx`) never import a
22
+ `*.document|dictionary|service|signal.ts`, `srvkit/`, a package `server` entrypoint, or the `db` / `srv` / `sig` /
23
+ `dict` / `option` / `useServer` barrels. Server files (those four suffixes, `srvkit/`) never import a `*.store.ts`, a
24
+ module component, `ui/`, `webkit/`, a package `client` entrypoint, or the `st` / `store` / `useClient` barrels.
25
+ `common/` and `*.constant.ts` obey both. `import type` is legal everywhere; a mixed value-and-type import is not.
26
+ - **Server-component discipline** on `page/**`, `*.Unit.tsx`, `*.View.tsx` (`no-import-client-functions`,
27
+ `no-use-client-in-server`, `non-scalar-props-restricted`).
28
+
29
+ ## SSR First — Server Rendering Is The Default
30
+
31
+ Server-rendered JSX ships as HTML and costs nothing to hydrate; `"use client"` ships it twice (markup plus JS that
32
+ re-runs). **The default is server; the directive is a cost justified per component** by a React hook, a JSX event
33
+ handler, the store, a browser global, or a client-only package — never by markup, params, `l()` or mapping data.
34
+ `akan quality ssr` (`--format json`) prints each app's and lib's server share: **50% is the floor, and a falling
35
+ share is a regression** to justify in the PR or revert. A client package or an `index_.tsx` `lazy()` boundary
36
+ justifies the directive; a `fetch.*` inside `onClick` is not flagged, only mount-time loads.
37
+
38
+ Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction and render `children` untouched;
39
+ ② split compound components (`Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`) — never one client file with a mode
40
+ `useState` and every panel inlined; ③ fetch in the route and pass `init` / `view` to a `Zone`, never a
41
+ `useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
42
+ promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
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
+ redirects in-page after I/O); ⑨ CSS (`data-*` + `group-data-[…]`, `<details>`) over client state for visibility;
47
+ ⑩ heavy islands behind `index_.tsx` + `lazy()`.
@@ -0,0 +1,43 @@
1
+ ---
2
+ description: Styling: Tailwind order, the semantic colour vocabulary, cn(), recipes and the app theme.
3
+ paths:
4
+ - "{apps,libs}/**/*.tsx"
5
+ - "{apps,libs}/**/*.css"
6
+ - "{apps,libs}/*/ui/Recipe/**"
7
+ ---
8
+
9
+ # Styling
10
+
11
+ - **Never hand-order Tailwind classes** — `nursery/useSortedClasses` sorts them, `cn()` arguments included, and its
12
+ output (`font-bold text-2xl text-foreground`) is correct.
13
+ - **Stay inside the color vocabulary** (`no-raw-palette-class`, `no-arbitrary-color`, `no-interpolated-arbitrary-class`,
14
+ `no-daisyui-legacy-class`, `no-inline-color`): no raw palette (`bg-blue-500`), arbitrary or interpolated color classes
15
+ (`bg-[#3b82f6]`), daisyUI classes or slots (`btn-primary`, `bg-base-100`), or color literals in `style={{}}` — they
16
+ render no CSS. Use semantic tokens (`bg-primary`, `text-foreground/70`); a legitimate fixed color takes
17
+ `// biome-ignore lint/plugin: <reason>`. Slot replacements, SVG / `el.style` warnings, legal values: `cssRule`.
18
+
19
+ - Static class strings stay plain. `cn` (from `akanjs/client`) only for a conditional or to merge an incoming
20
+ `className`, caller last: `cn("base", cond && "extra", className)` — the only combiner: no `clsx`, raw `twMerge`,
21
+ or object syntax.
22
+ - Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
23
+ - Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
24
+ `Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
25
+ name map (`BadgeVariants["variant"]`) moves to `webkit/`.
26
+
27
+ ## Theme And Component Overrides
28
+
29
+ When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
30
+
31
+ - **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
32
+ - **Lib tokens (`libs/<lib>/ui/tokens.css`).** The one CSS file a lib owns: colors its own components pin that must **not** follow the theme — a vendor brand color, a fixed surface — declared once as plain `:root` custom properties and compiled automatically into every app whose pages reach the lib, ahead of the app's stylesheets, so nothing is imported by hand. Reference them as `bg-[var(--kakao)]`; never copy the block into each app. `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet, and theme-following colors are the app's.
33
+ - **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
34
+
35
+ ## Recipes
36
+
37
+ Framework UI recipes (Tailwind-variant look factories) import from `akanjs/ui`: `<name>(variants?, className?)`.
38
+ The second argument merges internally and takes an array too, so never wrap it in `cn()`:
39
+ `<name>({}, ["h-full", isWide && "w-full", className])`. Do not guess a recipe name or variant value, and do not open
40
+ the recipe file to consume one. Before inlining a repeated surface (card, box, tile): reuse a recipe, or add one as
41
+ `apps/<app>/ui/Recipe/<name>.ts`, one per file, re-exported from that folder's `index.ts` — never a near-duplicate.
42
+ Each app and lib lists its own recipes in `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` (`## Recipes In Scope`),
43
+ regenerated by `akan sync`. Full policy: the `recipeRule` guideline.
@@ -0,0 +1,34 @@
1
+ ---
2
+ description: Tests: Bun's runner, one suite per module file, the signal test split and how to run them.
3
+ paths:
4
+ - "{apps,libs}/**/*.{test,spec}.ts"
5
+ ---
6
+
7
+ # Test Code
8
+
9
+ - Bun's runner (`describe`, `expect`, `test` from `bun:test`); colocated `*.test.ts` / `*.spec.ts`; focused behavior
10
+ tests of public contracts and edge cases. A placeholder `it` with a descriptive title is the floor; a
11
+ security-relevant behaviour gets a real suite.
12
+ - Run `bun run akan test <pkg> [files]` from the root (`files`: comma-separated paths from the target or the root;
13
+ the only way a signal test runs), or `cd <pkg> && bun test --isolate ./<file>`. Plain `bun test` shares one global
14
+ object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not honored as
15
+ of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
16
+ - Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
17
+ `Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
18
+ describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
19
+ `await expect(p).rejects.toThrow()`. Each `fetch.clone()` reports its own address (`198.18.x.y`), so an `ip` rate
20
+ limit counts it apart: clone once per simulated user, signup included (`clone({ clientIp })` names one).
21
+ - **One suite per module file**: `<model>.<role>.test.ts` beside the file it covers — never topic splits
22
+ (`chatMessage.trim.signal.test.ts`); add a `describe`. A suite spanning modules goes in `srvkit/`
23
+ (`libs/shared/srvkit/guards.signal.test.ts`), never the `lib/` root; `akan sync` refuses all three shapes. Only
24
+ `akan verify` and `akan typecheck <app-or-lib>` typecheck tests (`bun:test` types included) and the `script/`
25
+ files nothing imports.
26
+ - Delete an export only tests reference together with its test (`akan quality scan` reports
27
+ `akan.global.test-only-export` in an app's `common/`, `webkit/`, `srvkit/`, `ui/`).
28
+ - Import `UserAgent` / `AdminAgent` from `lib/user/user.signal.spec.ts`, the one place agent types are re-typed.
29
+
30
+ **Verify endpoints with signal tests, not raw HTTP.** The canonical way to check a query/mutation/slice
31
+ contract is an in-memory signal test (`<model>.signal.test.ts`), using the test fetch harness
32
+ (`getOrSetupSignalTestFetch`) — it is fast, needs no running server, and exercises `fetch.*`, `view/edit/merge<Model>`,
33
+ and slice `init`/`list`/`insight` directly. Prefer it over `curl`: the dev gateway locale-prefixes routes (`/en/...`),
34
+ so hand-rolled HTTP calls against a raw path can redirect unexpectedly. See `akan test <app>`.