@akanjs/cli 3.1.1-rc.8 → 3.1.1

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 (184) hide show
  1. package/.build-stamp +1 -1
  2. package/CodeAgent-35wnb7w5.js +9 -0
  3. package/{CodeTui-rqxarxsn.js → CodeTui-h6yz2kvq.js} +1 -1
  4. package/TunnelShare-xyjpa7gx.js +14 -0
  5. package/agent.command-3r4jsck8.js +46 -0
  6. package/akanCode.js +10 -6
  7. package/{application.command-14xsthcr.js → application.command-g7xv6ad0.js} +46 -13
  8. package/{applicationBuildRunner-t2r84sz6.js → applicationBuildRunner-qvjnhr9j.js} +9 -6
  9. package/buildBatch.proc.js +6 -6
  10. package/{cloud.command-rmw1kcf1.js → cloud.command-6ebygmhw.js} +17 -15
  11. package/cloud.script-0s1jybd5.js +26 -0
  12. package/{code.command-719k3e9q.js → code.command-mpkm2emr.js} +6 -6
  13. package/commandManifest.json +1 -1
  14. package/{context.command-c4t4z1vy.js → context.command-svdh6b2w.js} +18 -17
  15. package/context.runner-ch0z3a8g.js +26 -0
  16. package/{devTui-q7k7bakd.js → devTui-evr3b35y.js} +1 -1
  17. package/{guideline.command-snh85ctf.js → guideline.command-qwp3tnjx.js} +3 -3
  18. package/guidelines/conventions/core.md +106 -0
  19. package/guidelines/conventions/rules/app.md +83 -0
  20. package/guidelines/conventions/rules/auth.md +45 -0
  21. package/guidelines/conventions/rules/config.md +56 -0
  22. package/guidelines/conventions/rules/constant.md +24 -0
  23. package/guidelines/conventions/rules/gates.md +31 -0
  24. package/guidelines/conventions/rules/layer.md +25 -0
  25. package/guidelines/conventions/rules/migration.md +27 -0
  26. package/guidelines/conventions/rules/module.md +90 -0
  27. package/guidelines/conventions/rules/page.md +56 -0
  28. package/guidelines/conventions/rules/sensitive.md +16 -0
  29. package/guidelines/conventions/rules/server.md +86 -0
  30. package/guidelines/conventions/rules/ssr.md +47 -0
  31. package/guidelines/conventions/rules/style.md +43 -0
  32. package/guidelines/conventions/rules/test.md +34 -0
  33. package/guidelines/conventions/rules/ts.md +95 -0
  34. package/guidelines/conventions/rules/tsx.md +75 -0
  35. package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
  36. package/guidelines/pageRule/pageRule.instruction.md +4 -3
  37. package/guidelines/queryRule/queryRule.instruction.md +4 -0
  38. package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +3 -3
  39. package/incrementalBuilder.proc.js +6 -6
  40. package/{index-pcwzkdqb.js → index-1p0qbq3m.js} +1 -1
  41. package/{index-xb8809yb.js → index-1shvxzt0.js} +3 -3
  42. package/{index-8w76g4rm.js → index-266dewjs.js} +11 -11
  43. package/{index-5max10jx.js → index-3yz30c07.js} +72 -53
  44. package/{index-xjf5j657.js → index-4mj92tsh.js} +952 -47
  45. package/index-4pdts00b.js +1604 -0
  46. package/{index-42j4a8zq.js → index-8559hsz4.js} +4 -3
  47. package/{index-wcej7g4z.js → index-8scw1pjk.js} +93 -23
  48. package/{index-5phjb48k.js → index-96wzdhfh.js} +74 -233
  49. package/index-9bv479q5.js +1 -0
  50. package/index-9rvcs76p.js +653 -0
  51. package/index-am36s3jh.js +3582 -0
  52. package/index-b8c289dx.js +444 -0
  53. package/{index-espk51ah.js → index-dd44g6vz.js} +3 -3
  54. package/{index-3wypz6xj.js → index-eja64h28.js} +7 -3
  55. package/index-fbewhg4g.js +590 -0
  56. package/index-jje9qzyq.js +27 -0
  57. package/{index-j9vyj3dj.js → index-k5jbcxyh.js} +3 -3
  58. package/{index-hmmv2cah.js → index-ksfgqq1x.js} +1 -1
  59. package/index-m5n3ka0p.js +18 -0
  60. package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
  61. package/{index-0p37cz91.js → index-payhwt51.js} +21 -29
  62. package/{index-myc22sgv.js → index-qkkdhjm6.js} +5 -4
  63. package/{index-74tjjsnc.js → index-qxzrp5xt.js} +33 -37
  64. package/{index-zrte51fn.js → index-r0k3ham2.js} +4 -4
  65. package/{index-hmt54t45.js → index-r2w2eh93.js} +4 -4
  66. package/index-r2wedvqn.js +138 -0
  67. package/{index-skk9zc1x.js → index-rnphv731.js} +2 -2
  68. package/{index-pa3c2mb8.js → index-s6da8ta9.js} +82 -1227
  69. package/index-tenw3mah.js +225 -0
  70. package/{index-31es1yev.js → index-tgt2fnd6.js} +107 -6
  71. package/{index-8ap5z1n5.js → index-vxmy1p4f.js} +16 -36
  72. package/{index-mdqr41sp.js → index-w4k2ragk.js} +7 -7
  73. package/{index-qd5km521.js → index-w7q6h97v.js} +1 -1
  74. package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
  75. package/{index-2xcc2ax5.js → index-xq543a5y.js} +2 -2
  76. package/{index-0fz95kxe.js → index-xqgwjz7a.js} +1 -1
  77. package/{index-40brg4px.js → index-xxfy1jp2.js} +4 -4
  78. package/{index-905qdgqp.js → index-z4b84y6k.js} +1 -1
  79. package/index-zcf6k8a5.js +410 -0
  80. package/index.js +23 -22
  81. package/{library.command-gycrwhf1.js → library.command-2853y6mk.js} +3 -3
  82. package/{localRegistry.command-2t3fghje.js → localRegistry.command-76ds31p4.js} +19 -15
  83. package/{module.command-v6hgs1bc.js → module.command-yfnb0abs.js} +5 -5
  84. package/{package.command-shzpcfph.js → package.command-d9s86hp9.js} +3 -3
  85. package/package.json +2 -2
  86. package/{page.command-ptxn5kqk.js → page.command-6a8a8rd1.js} +3 -3
  87. package/{pipeline.command-zz31pgax.js → pipeline.command-rt3rwd2z.js} +2 -2
  88. package/{primitive.command-a1vse91z.js → primitive.command-emcebgrq.js} +6 -6
  89. package/{projectTypecheck-2ztky9cf.js → projectTypecheck-51m7eh1f.js} +1 -1
  90. package/{prompter-76k56b37.js → prompter-hgcta8pb.js} +1 -1
  91. package/quality.command-xtrk0n3x.js +76 -0
  92. package/{repair.command-cvazbz99.js → repair.command-51szxnxx.js} +5 -5
  93. package/{routeSourceValidator-6jd0q6r6.js → routeSourceValidator-4h947v7c.js} +13 -3
  94. package/{scalar.command-0acvyp26.js → scalar.command-8qv27t82.js} +4 -4
  95. package/skills/akan-agent/SKILL.md +36 -0
  96. package/skills/akan-code/SKILL.md +1 -0
  97. package/skills/akan-debug/SKILL.md +40 -6
  98. package/skills/akan-deps/SKILL.md +1 -2
  99. package/skills/akan-mcp/SKILL.md +40 -0
  100. package/skills/akan-page/SKILL.md +44 -0
  101. package/skills/akan-query/SKILL.md +38 -0
  102. package/skills/akan-runtime/SKILL.md +40 -0
  103. package/skills/akan-scaffold/SKILL.md +16 -6
  104. package/skills/akan-transport/SKILL.md +40 -0
  105. package/skills/akan-validate/SKILL.md +13 -11
  106. package/{subspace.command-kvxmyxtf.js → subspace.command-pn56pnh8.js} +8 -8
  107. package/templates/__scalar/__model__/__model__.constant.ts +3 -5
  108. package/templates/__scalar/__model__/__model__.dictionary.ts +6 -5
  109. package/templates/__scalar/__model__/__model__.document.ts +3 -3
  110. package/templates/app/akan.config.ts +2 -3
  111. package/templates/app/env/env.client.ts +2 -4
  112. package/templates/app/env/env.client.type.ts +2 -3
  113. package/templates/app/env/env.server.ts +2 -3
  114. package/templates/app/lib/___appName__/__appName__.dictionary.ts +1 -2
  115. package/templates/app/lib/___appName__/__appName__.service.ts +3 -3
  116. package/templates/app/lib/___appName__/__appName__.signal.ts +5 -5
  117. package/templates/app/lib/___appName__/__appName__.store.ts +4 -6
  118. package/templates/app/lib/option.ts +2 -3
  119. package/templates/app/main.ts +2 -4
  120. package/templates/app/page/_index.tsx +3 -3
  121. package/templates/app/page/_layout.tsx +13 -10
  122. package/templates/appSample/lib/__scalar/workHistory/workHistory.constant.ts +1 -5
  123. package/templates/appSample/lib/__scalar/workHistory/workHistory.dictionary.ts +1 -1
  124. package/templates/appSample/lib/_noti/noti.signal.ts +1 -1
  125. package/templates/appSample/lib/task/Task.Template.tsx +2 -1
  126. package/templates/appSample/lib/task/Task.Unit.tsx +3 -2
  127. package/templates/appSample/lib/task/Task.Util.tsx +16 -4
  128. package/templates/appSample/lib/task/task.constant.ts +1 -5
  129. package/templates/appSample/lib/task/task.dictionary.ts +2 -8
  130. package/templates/appSample/lib/task/task.document.ts +1 -1
  131. package/templates/appSample/page/task/_index.tsx +2 -1
  132. package/templates/appSample/page/task/new.tsx +2 -1
  133. package/templates/appSample/ui/QuantityControl.tsx +5 -9
  134. package/templates/biomeForm.ts +144 -0
  135. package/templates/crudPages/[__model__Id]/edit/page.tsx +3 -3
  136. package/templates/crudPages/[__model__Id]/page.tsx +5 -5
  137. package/templates/crudPages/new/page.tsx +4 -3
  138. package/templates/crudPages/page.tsx +3 -3
  139. package/templates/crudSinglePage/page.tsx +9 -5
  140. package/templates/libRoot/akan.config.ts +2 -3
  141. package/templates/libRoot/lib/___libName__/__libName__.dictionary.ts +1 -2
  142. package/templates/libRoot/lib/___libName__/__libName__.service.ts +5 -4
  143. package/templates/libRoot/lib/___libName__/__libName__.signal.ts +6 -5
  144. package/templates/libRoot/lib/___libName__/__libName__.store.ts +5 -6
  145. package/templates/libRoot/lib/option.ts +1 -2
  146. package/templates/module/__Model__.Template.tsx +11 -10
  147. package/templates/module/__Model__.Unit.tsx +18 -5
  148. package/templates/module/__Model__.Util.tsx +9 -7
  149. package/templates/module/__Model__.View.tsx +9 -6
  150. package/templates/module/__Model__.Zone.tsx +25 -17
  151. package/templates/module/__model__.constant.ts +8 -9
  152. package/templates/module/__model__.dictionary.ts +16 -17
  153. package/templates/module/__model__.document.ts +6 -8
  154. package/templates/module/__model__.service.ts +3 -3
  155. package/templates/module/__model__.signal.ts +11 -10
  156. package/templates/module/__model__.store.ts +3 -5
  157. package/templates/service/__model__.dictionary.ts +6 -5
  158. package/templates/service/__model__.service.ts +3 -3
  159. package/templates/service/__model__.signal.ts +5 -4
  160. package/templates/service/__model__.store.ts +3 -5
  161. package/templates/workspaceRoot/.gitignore.template +3 -0
  162. package/templates/workspaceRoot/.vscode/settings.json.template +21 -21
  163. package/templates/workspaceRoot/AGENTS.md.template +4 -10
  164. package/{tunnel.command-kxv0ddmp.js → tunnel.command-q2h0j2en.js} +7 -7
  165. package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
  166. package/typecheck.proc.js +6 -1
  167. package/verify.command-z1dsbmrt.js +91 -0
  168. package/{workflow.command-abb1d5xy.js → workflow.command-r3y67jeq.js} +47 -13
  169. package/workspace.command-t2f0xsrw.js +263 -0
  170. package/CodeAgent-3sy7kjgj.js +0 -9
  171. package/TunnelShare-2ef94kha.js +0 -14
  172. package/agent.command-ydftceda.js +0 -25
  173. package/cloud.script-v1ysyerg.js +0 -24
  174. package/context.runner-qb15sjf8.js +0 -25
  175. package/guidelines/conventions/conventions.instruction.md +0 -617
  176. package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
  177. package/index-4vgbysa0.js +0 -279
  178. package/index-7md2g9vw.js +0 -6
  179. package/index-b70zct19.js +0 -856
  180. package/index-zzvvc845.js +0 -74
  181. package/quality.command-ah8qcakd.js +0 -1478
  182. package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
  183. package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
  184. package/workspace.command-tsc99yec.js +0 -521
@@ -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>`.
@@ -0,0 +1,95 @@
1
+ ---
2
+ description: TypeScript house style: classes, naming, file size, type shape, imports, comments.
3
+ paths:
4
+ - "{apps,libs}/**/*.{ts,tsx}"
5
+ ---
6
+
7
+ # TypeScript Style
8
+
9
+ ## Coding Style
10
+
11
+ - Run a large unit of work through a class instance; prefer class or `static` methods over unrelated top-level
12
+ helpers, and keep a class file's functions and variables inside the class when they reasonably can be.
13
+ - `#private` over TypeScript `private`, except in the four lint-banned suffixes, which use `private`.
14
+ - `const` function expressions over `function` declarations, unless hoisting, overloads, generators, or a framework
15
+ convention make `function` the better fit.
16
+ - One class per file, named after it (`RouteClientBuilder.ts`, not `buildRouteClient.ts`). Migrate callers off an
17
+ exported function that only instantiates a class and calls one method.
18
+ - TypeScript filenames are camelCase, except React component and convention files.
19
+ - One-off `className` strings stay inline; extract a constant only when reused, conditionally composed, or too large
20
+ to read in JSX.
21
+
22
+ ### File Size And Duplication
23
+
24
+ - Keep files small (house median well under 50 lines); split a component before ~150 lines rather than adding
25
+ section comments.
26
+ - Ship every scaffold file even when empty — `export class XInternal extends internal(srv.x, () => ({})) {}`, empty
27
+ dictionary stages, the `// state` / `// action` markers. They mark where things go.
28
+ - Never add a sibling helper file inside `lib/<model>/`; helpers go to `common/`, `webkit/`, `srvkit/`, or `ui/`.
29
+ - Prefer duplication to premature abstraction at the leaf: near-identical sibling modules and per-vendor pages are
30
+ copied with changed literals, not parameterised; share enums by import only.
31
+
32
+ ### TypeScript Shape
33
+
34
+ - `interface` for object shapes, `type` only for unions and aliases.
35
+ - `interface <ComponentName>Props` sits directly above the component (no blank line), `className?: string` first,
36
+ named for the component (`CardProps`), never the model; exported only when a sibling imports it.
37
+ - No non-null assertions — narrow with `?.`, an early return, or a type predicate
38
+ (`.filter((id): id is string => !!id)`). Escape with `as unknown as T`, never `as any`.
39
+ - Never annotate a component's return type; annotate a helper only for a union, tuple, or type predicate.
40
+ - `as const` on every `enumOf(...)` array (even though `enumOf` infers its literals, so a typo already fails to
41
+ compile), `via(Model, [...] as const, …)` Light tuple, and module-scope lookup map; never the `enum` keyword.
42
+ - Async functions carry no `Async` suffix.
43
+
44
+ - **`#private` is banned in exactly `*.constant.ts`, `*.document.ts`, `*.service.ts`, `*.store.ts`**
45
+ (`no-js-private-class-method`, by path, so it stays the house style everywhere else, `srvkit/` and `adapt()` classes
46
+ included).
47
+
48
+ ## TypeScript And Imports
49
+
50
+ - Bun and ESM per the root `tsconfig.json`. Path aliases across packages: `akanjs/*`, `@apps/*`, `@libs/*`,
51
+ `@contract/*`, respecting the `/client` and `/server` entrypoints. Let Biome organize imports.
52
+ - Backend `.ts` namespaces the generated barrels — `import * as cnst from "../cnst"`, `* as db`, `* as srv` —
53
+ with `import type * as srv` in services (keeps the runtime graph lazy) and a value import in signals.
54
+ - `.tsx` uses one flat named import from the package client path
55
+ (`import { cnst, fetch, st, Ticket, usePage } from "@apps/<app>/client"`), never a relative `../` import.
56
+
57
+ - Biome formats: 2-space indent, 120 columns, double quotes.
58
+
59
+ ## Naming And Language
60
+
61
+ - Component exports are role names (`Card`, `General`, `Preview`, `Admin`, `Remove`) — the namespace carries the
62
+ model (`<Floor.Unit.Card>`, never `FloorCard`). `Util` exports are the endpoint verb minus the noun (`Serve`,
63
+ `Refund`).
64
+ - Layer the verbs: the document chain method drops the model (`sign()`), the service keeps the bare verb, signal,
65
+ store and dictionary re-add it (`signScContract`) — clear of generated CRUD, and `st.do.X` reads like `fetch.X`.
66
+ - Slice and filter names are prepositional (`inOrg`, `byStatuses`, `ofPortfolio`), never `getXInY` or `listX`.
67
+ - Handlers are `onX` props taking inline arrows, never an extracted `handleX`.
68
+ - Booleans `is*` / `has*` / `can*` / `show*` / `disable*`; counters `*Num`; indices `idx`; collections `*List` or
69
+ plural; no `SCREAMING_SNAKE` — module-scope tables are camelCase + `as const`.
70
+ - Keep existing domain vocabulary and its typos — transliterated terms and misspellings in use are load-bearing, and
71
+ renaming silently breaks callers that match on the name.
72
+ - Identifiers, type names, endpoint names, and log messages are **English**. Everything a user reads goes through
73
+ `l("model.field")` or `l.trans({ en, ko })` — never a hard-coded JSX string, never `window.alert`.
74
+ - Dictionary entries are `[en, ko]` pairs, nearly every label with a `.desc([en, ko])` even when repetitive; English
75
+ in Title Case, Korean the plain domain term, `.error()` Korean ending in `다.`.
76
+
77
+ ## Comments
78
+
79
+ Do not narrate code. Do document the thing the code cannot say. Both halves are the rule.
80
+
81
+ - Never restate the identifier, the signature, or the control flow; prefer names and structure. No JSDoc, section
82
+ banners, or "why/how" comments on ordinary logic.
83
+ - Density tracks the layer: pages carry none, product `lib/` and `ui/` stay under 1 %, `srvkit/` adapters and
84
+ `guards.ts` (what would leak without each guard) carry what the external constraints require. `akan quality scan`
85
+ reports a `lib/` module or `ui/` entry past 1 % once it holds five comment lines (`akan.comment.density`).
86
+ - Mark a retired field or function `/** @deprecated <what to use instead> */` on its declaration, never a
87
+ `// deprecated` comment — only the tag strikes through every use site.
88
+ - Warranted for: a vendor or protocol quirk; an infrastructure constraint; a library gotcha; security reasoning; why
89
+ an arbitrary-looking rule is correct; a math derivation; a domain field's business meaning; a state transition above
90
+ a document chain method; why an obvious alternative was rejected.
91
+ - Markers: `TODO` (tracked unfinished work), `FIXME` (known broken), `XXX` (a hazard a reader must not miss), `//!`
92
+ (disabled or must-fix — server, `srvkit/`, CLI only), `//?` (an aside), `//*` (a design note), and a deletion
93
+ caution saying why removing a line would break something non-obvious.
94
+ - One short line each. Every suppression carries a reason (`// biome-ignore lint/<rule>: <why>`), never a bare
95
+ disable block. Match the nearby density.
@@ -0,0 +1,75 @@
1
+ ---
2
+ description: React components: the five roles, forms, loading states, hooks and the lint rules on .tsx files.
3
+ paths:
4
+ - "{apps,libs}/**/*.tsx"
5
+ ---
6
+
7
+ # React Components
8
+
9
+ A screen that grows keeps five roles: an **assembly** `Zone` that reads the store and places pieces, with no
10
+ branching; **pieces** (`Unit`, `View`, small components) that only display, server-rendered where they can be; a
11
+ **kind table** `{ [kind in cnst.X["value"]]: Component }` instead of mode flags, so a new enum value without an entry
12
+ is a type error — each entry is a component of the module that owns that kind's data (a tab of video scenes is
13
+ `VideoScene.Zone.<X>`), so a screen spanning several models adds no folder; an **interaction hook**
14
+ `webkit/use<X>.tsx` over a pure, tested `common/<x>.ts` class for drag, selection and keys, handed its writes as
15
+ arguments; and **writes** as one-line store actions, one endpoint each. Kinds a screen invents rather than a model
16
+ (canvas node kinds) key the table by an `as const` union in `common/`. A screen choosing along two axes (what to
17
+ pick, and where the pick lands) keeps two tables, the second mapping each purpose to its one commit action. State
18
+ several components or an agent tool read stays in the store, where `st.tool` sees it; the hook keeps only gesture
19
+ state. Reach for the path, not the nearest file:
20
+
21
+ | Task | Path |
22
+ |---|---|
23
+ | A state-changing act, or chained writes in an action or handler | `akan workflow plan add-mutation --app <app> --module <m> --mutation <verbModel> --guard <Guard>[,…] [--with <ref>.<method>] [--after <ref>.<method>]` |
24
+ | Event, keyboard, pointer or layout logic growing in a component | `akan workflow plan create-interaction --app <app> --interaction <name>` |
25
+ | A missing `View` / `Unit` / `Template` / `Zone` / `Util` | `akan workflow plan create-ui --app <app> --module <m> --surface <surface>` |
26
+
27
+ - `export const X = ({ … }: XProps) => { return (…); };` — `export default` only for pages, layouts, `lazy()`
28
+ targets. No `React.FC`, `defaultProps`, `PropsWithChildren`; defaults in the destructuring, `children: ReactNode`.
29
+ - `cond ? <X/> : null`, never `{cond && <X/>}` (renders `"false"` in a `className`); early `return null` only for
30
+ guard clauses.
31
+ - Never hand-roll loading, empty, or list states: `Load.Units` / `Load.View` / `Load.Edit` (`renderItem`,
32
+ `renderList`, `renderView`, `renderEmpty`), `<Empty />`, `Model.New` / `Model.Edit` / `Model.SureToRemove`.
33
+ Otherwise `<Load.Stream of={promise} fallback={…}>{(value) => …}</Load.Stream>` awaits one promise behind its own
34
+ boundary (a resolved value renders in the shell).
35
+ - Avoid hooks. `useState` only for modal-open, tab, draft-input, and drag state, never server data; `useEffect` only
36
+ for a genuine effect (subscribe-with-cleanup, one-shot init); `Tab` over a mode switch; zero `useState` in a
37
+ `.Template.tsx`.
38
+ - Forms are store-driven: `value={xForm.field}`, `onChange={st.do.setFieldOnX}` **by reference** — that emits the
39
+ `data-akan-action` / `data-akan-state` the in-page agent, E2E selectors and browser agents read. Always `Field.*`,
40
+ never a bare `<input>` for a model field; nested rows use `st.do.writeOnX("payments.3.name", v)` and the generated
41
+ `add<Field>OnX` / `sub<Field>OnX`. Never hand-write `data-akan-*`.
42
+ - Read with `st.use.*`, write with `st.do.*`; client components never call `fetch.*`.
43
+ - A raw `<button>` defaults to `type="submit"`, so a click inside any `<form>` also submits it. Write
44
+ `type="button"` on every raw `<button>` that does not submit; `<Button>` from `akanjs/ui` already defaults to it.
45
+ - **Never persist form values yourself** — `Load.Edit`, `Model.EditModal` and `Model.New` save and recover the whole
46
+ `<model>Form` per record or route and user (`draft={false}` off, `draft="<scope>"` to name it; secret and hidden
47
+ values never saved; field `cache` / `cacheKey` props are deprecated no-ops — `modelStore`).
48
+ - `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links. A `<Link>` handed
49
+ an absolute URL (any scheme, any case) or a `//host` path passes it through untouched and opens it outside the app;
50
+ only an app path gets the locale and basePath. `Href.isExternal(href)` from `akanjs/client` is that test.
51
+
52
+ ## Lint Rules On Components
53
+
54
+ - **Never type a `*.Util.tsx` / `*.Zone.tsx` prop as a `cnst` model** (`no-model-type-in-util-zone`) — the server would
55
+ hand a class instance to a client component; take `bannerId: string` and read the model from the store. Exempt:
56
+ `cnst.<Enum>["value"]`, a `ClientInit` / `ClientView` / `ClientEdit` / `ModelsProps<…>` type argument, a
57
+ function-typed prop, a `cnst` type that never leaves the file; `ModelProps<…>` and other indexed accesses stay
58
+ flagged.
59
+ - **Never wrap a form setter in a pass-through arrow** (`no-unpublished-form-setter`) —
60
+ `(v) => st.do.setTypeOnTicket(v)` emits no `data-akan-action` and publishes no agent tool. A wrapper that transforms,
61
+ adds a statement, or calls `writeOnX` is legal; publish it with an explicit `st.tool`.
62
+ - **Never call a hook conditionally** — a skipped call shifts every later hook, and production React crashes
63
+ elsewhere. Biome's `useHookAtTopLevel` checks plain hooks (`useState`, `useEffect`), early returns included.
64
+ `no-conditional-st-hook` checks the `st` hooks it cannot see — `st.use.*`, `st.slice.<x>.use.*`, `st.sel`, `st.ref`,
65
+ `st.tool(…).exec()` / `.card()`, `st.useState(…).init()`, `st.expose(…).value()` — behind `||` / `&&` / `??`, in a
66
+ ternary, an `if`, a `switch`, a loop, a `catch`, a default value, an optional call or a callback; not after an early
67
+ `return` or inside a helper the component calls. Read each into its own `const` at the top, then combine.
68
+ - **No async component under `ui/`** (`no-async-component-in-ui`) — React has no async client component. Await in the
69
+ page, or hand an unawaited `fetch.*` field to a `Zone` / `<Load.Stream of={…}>`, and take the data as a prop. An async
70
+ handler in a synchronous component and `lazy(async () => import(…))` are untouched.
71
+ - **Never call `fetch.init<Model><Suffix>` / `fetch.get<Model>Init<Suffix>` from a client file** (`"use client"` or
72
+ `*.store.ts`; `no-init-fetch-in-client`) — it is the hydration snapshot. Load it in the page and pass `init` down;
73
+ reload with `st.do.init<Model><Suffix>()`.
74
+ - `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose — `key={idx}` for embedded scalars and
75
+ short dependency arrays are intentional.
@@ -580,7 +580,7 @@ element, beside the tools it explains. Exactly these texts reach every client: `
580
580
 
581
581
  ## Verifying An App
582
582
 
583
- - `akan lint <app>`, `akan typecheck <app>`, `akan sync <app>`, then the boot log above.
583
+ - `akan verify <app>`, then the boot log above.
584
584
  - The lib's own suites run wherever it is mounted: the OAuth signal test (metadata, registration, both `authorize`
585
585
  redirects, code exchange, `/mcp` with the minted token and the refusal of a first-party or forged one, refresh
586
586
  rotation) and the refresh-session and option unit tests.
@@ -83,9 +83,10 @@ body shape — this is the full contract behind them. Before changing route beha
83
83
  native back or swipe, the agent's `navigate` and `goBack` — with routes free of locale and basePath and `to: null`
84
84
  for a `back`. `false`, a throw or a rejection keeps the page, `router.navigation()` rejects with
85
85
  `NavigationRefused`, and a refused browser back is undone before the page redraws. Guards answer one at a time; a
86
- move started while one decides is refused. Register it from an effect and return the remover
87
- (`useEffect(() => router.addNavigationGuard(…), [isDirty])`). Redirects, `notFound()`, `setLang` and moves off the
88
- origin are not asked; a closing tab is `beforeunload`'s.
86
+ move started while one decides is refused. In a component, register it with `useNavigationGuard(() => !isDirty)`
87
+ (`akanjs/webkit`), held only while its page is current: a page kept under the next for a swipe back stays mounted,
88
+ and a guard it kept would hold that page too. Redirects, `notFound()`, `setLang` and moves off the origin are not
89
+ asked; a closing tab is `beforeunload`'s.
89
90
 
90
91
  ## MCP Apps — `.app()`
91
92
 
@@ -120,6 +120,10 @@ this is the full contract behind them.
120
120
  still run — a nudge that re-sends a row its rooms must re-read, with no edit to stamp.
121
121
  - `upsertById(data, { preserveTimestamps })` writes a record whole under its own id, new or in place, with no
122
122
  hook: the write a sync or a backfill repeats safely, keeping the record's `createdAt`/`updatedAt` when asked.
123
+ With `{ where }` it writes over a stored row only when that row matches, in the same statement, and never over a
124
+ removed row unless `withRemoved` is also passed; an id no row holds is inserted. It then answers `updateOne`'s
125
+ result: `modifiedCount` 0 when the stored row did not match, and `upsertedId` set on an insert. A writer whose
126
+ lease may have lapsed passes the lease as `where`, so a takeover's row is never overwritten or revived.
123
127
  - **Writes that must land together go in `this.transaction(async () => …)`**, which every service has: it commits
124
128
  when the body resolves, returns its value, and rolls back when it throws, rethrowing that error unchanged. A
125
129
  server has one database, so it covers every model, hooks and query-level writes included; a nested call joins the
@@ -1,7 +1,7 @@
1
1
  # Workspace Recipes — Worked Examples And The Auto-Generated API
2
2
 
3
3
  Step-by-step recipes for the most frequent Akan.js changes, and the reference of what `akan sync` generates for
4
- you at each layer. `workspaceOnboarding` carries the index and the rules; this is the worked code behind them.
4
+ you at each layer. The `conventions` guideline carries the rules; this is the worked code behind them.
5
5
  Read the whole recipe before editing, and change only the sections it names — do not rewrite a file.
6
6
 
7
7
  ## Workflow Recipes
@@ -394,7 +394,7 @@ export const Insight = ({ sliceName }: { sliceName: string }) => {
394
394
  A route file used to be a default function beside named exports (`pageConfig`, `head`, `generateHead`, `Loading`,
395
395
  `fonts`, …). It is now one chain, and the chain is also what publishes a screen to agents. The legacy shape still
396
396
  loads and logs one warning per file at boot (`… uses the legacy route shape …`); migrate file by file, then run
397
- `bun run akan typecheck <app>` and `bun run akan lint <app>`.
397
+ `bun run akan verify <app>`.
398
398
 
399
399
  ```tsx
400
400
  // before — page/(user)/project/[projectId]/_index.tsx
@@ -514,7 +514,7 @@ surface (`akan context`, the MCP tools, `akan guideline show`) is what feeds a c
514
514
 
515
515
  `~/.akan/config.json` keeps an `llm` entry if it had one. It is ignored; delete it, because it holds an API key.
516
516
 
517
- Then: `bun run akan typecheck <app>`, `bun run akan lint <app>`, and one agent turn in the browser to confirm the
517
+ Then: `bun run akan verify <app>` and one agent turn in the browser to confirm the
518
518
  provider answers.
519
519
 
520
520
  ### Data Flow Summary
@@ -1,14 +1,14 @@
1
1
  // @bun
2
2
  import {
3
- ApplicationBuildReporter,
4
3
  HmrWatcher,
5
- WatchRootResolver
6
- } from "./index-5nd1wtkv.js";
4
+ WatchRootResolver,
5
+ ApplicationBuildReporter
6
+ } from "./index-p6x5b7hr.js";
7
7
  import {
8
8
  CodegenLock,
9
9
  WorkspaceExecutor,
10
10
  AppExecutor
11
- } from "./index-wcej7g4z.js";
11
+ } from "./index-8scw1pjk.js";
12
12
  import"./index-52w0fvh8.js";
13
13
  import {
14
14
  GraphClientEntryDiscovery,
@@ -19,10 +19,10 @@ import {
19
19
  DevChangePlanner,
20
20
  DevGeneratedIndexSync,
21
21
  SsrDevBundler
22
- } from "./index-espk51ah.js";
22
+ } from "./index-dd44g6vz.js";
23
23
  import {
24
24
  ServerGraphFile
25
- } from "./index-0fz95kxe.js";
25
+ } from "./index-xqgwjz7a.js";
26
26
  import {
27
27
  prepareDevWatchBatch
28
28
  } from "./index-a5vmm6x4.js";
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  AppInfo
4
- } from "./index-wcej7g4z.js";
4
+ } from "./index-8scw1pjk.js";
5
5
 
6
6
  // pkgs/@akanjs/devkit/slicePlanner.ts
7
7
  class SlicePlanner {
@@ -1,13 +1,13 @@
1
1
  // @bun
2
2
  import {
3
3
  resolveSsrPageEntriesForApp
4
- } from "./index-wcej7g4z.js";
4
+ } from "./index-8scw1pjk.js";
5
5
  import {
6
6
  bundleDefine,
7
7
  CsrEntryFiles,
8
8
  PagesEntrySourceGenerator,
9
9
  PagesBundleBuilder
10
- } from "./index-0fz95kxe.js";
10
+ } from "./index-xqgwjz7a.js";
11
11
 
12
12
  // pkgs/@akanjs/devkit/frontendBuild/csrArtifactBuilder.ts
13
13
  import { mkdir as mkdir2, rm as rm2, unlink as unlink2 } from "fs/promises";
@@ -274,7 +274,7 @@ ${logs}` : ""}`);
274
274
  await rm(stagingDir, { recursive: true, force: true });
275
275
  }
276
276
  static async discover(pageEntries, basePaths) {
277
- const { RouteSourceValidator } = await import("./routeSourceValidator-6jd0q6r6.js");
277
+ const { RouteSourceValidator } = await import("./routeSourceValidator-4h947v7c.js");
278
278
  const roots = pageEntries.filter((entry) => parseRouteModuleKey(entry.key).isInternalRootLayout);
279
279
  const overrides = pageEntries.filter((entry) => parseRouteModuleKey(entry.key).kind === "overrides");
280
280
  const layoutNodes = new Set(pageEntries.flatMap((entry) => {
@@ -1,13 +1,13 @@
1
1
  // @bun
2
2
  import {
3
3
  AppExecutor
4
- } from "./index-wcej7g4z.js";
4
+ } from "./index-8scw1pjk.js";
5
5
  import {
6
6
  jsonText,
7
7
  createWorkflowBaselineSummary,
8
8
  buildAkanModuleContextIndex,
9
9
  toolingRolloutGate
10
- } from "./index-xjf5j657.js";
10
+ } from "./index-4mj92tsh.js";
11
11
  import {
12
12
  buildResourceList,
13
13
  codexMcpConfigPath,
@@ -17,29 +17,29 @@ import {
17
17
  upsertCodexMcpServerBlock,
18
18
  renderDoctorText,
19
19
  AkanContextAnalyzer
20
- } from "./index-31es1yev.js";
20
+ } from "./index-tgt2fnd6.js";
21
21
  import {
22
22
  runner
23
- } from "./index-3wypz6xj.js";
23
+ } from "./index-eja64h28.js";
24
24
  import {
25
25
  NativeApp
26
- } from "./index-5max10jx.js";
26
+ } from "./index-3yz30c07.js";
27
27
  import {
28
28
  isPlaceholderAppId
29
- } from "./index-qd5km521.js";
29
+ } from "./index-w7q6h97v.js";
30
30
  import {
31
31
  getMobileTargets,
32
32
  appIdsOf
33
33
  } from "./index-m9jj544v.js";
34
34
  import {
35
35
  Prompter2
36
- } from "./index-zzvvc845.js";
36
+ } from "./index-r2wedvqn.js";
37
37
  import {
38
38
  RepairRunner
39
- } from "./index-j9vyj3dj.js";
39
+ } from "./index-k5jbcxyh.js";
40
40
  import {
41
41
  WorkflowRunner
42
- } from "./index-b70zct19.js";
42
+ } from "./index-zcf6k8a5.js";
43
43
 
44
44
  // pkgs/@akanjs/devkit/akanMcpContract.ts
45
45
  import path from "path";
@@ -654,8 +654,7 @@ class ContextRunner2 extends runner("context") {
654
654
  throw new Error(`${configPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
655
655
  }
656
656
  const nextConfig = { ...existing, mcpServers: { ...mcpServers, akan: nextAkanServer } };
657
- await workspace.writeFile(configPath, `${JSON.stringify(nextConfig, null, 2)}
658
- `);
657
+ await workspace.writeFile(configPath, nextConfig);
659
658
  return configPath;
660
659
  }
661
660
  async#installCodexMcp(workspace, { force, mode }) {
@@ -949,6 +948,7 @@ ${payload}`);
949
948
  "create-ui": "`akan create-ui --app <app-or-lib> --module <module> --surface <view|unit|template> --format json` creates one UI surface and returns a primitive write report.",
950
949
  "add-field": "`akan add-field --app <app-or-lib> --module <module> --field <field> --type <String|Boolean|Date|Int|Float|scalar> --format json` updates source constant/dictionary files. Use Int or Float for numeric fields, not Number.",
951
950
  "add-enum-field": "`akan add-enum-field --app <app-or-lib> --module <module> --field <field> --values a,b --format json` adds an enum field to source constant/dictionary files without editing generated files.",
951
+ verify: "`akan verify [<app-or-lib-or-pkg>]` syncs, lints, typechecks and fast-builds what git reports as changed in one run, printing one line per problem; run it instead of lint, typecheck and build in turn.",
952
952
  sync: "`akan sync <app-or-lib>` refreshes generated Akan files from source conventions.",
953
953
  lint: "`akan lint <app-or-lib-or-pkg>` runs Biome linting after preparing generated files.",
954
954
  typecheck: "`akan typecheck <app-or-lib>` typechecks an app or a library after preparing generated files, its tests and specs included (`--tests false` to leave them out; a build does).",