@akanjs/cli 3.1.1-rc.9 → 3.1.2-rc.0

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 (207) hide show
  1. package/.build-stamp +1 -1
  2. package/CodeAgent-dyc45f5w.js +11 -0
  3. package/{CodeAgentRpcHost-9g27hmer.js → CodeAgentRpcHost-6dzfkvsc.js} +1 -1
  4. package/CodeAgentRpcListener-tcwrdvst.js +182 -0
  5. package/{CodeTui-z5vkm9ea.js → CodeTui-q55b2zrn.js} +25 -8
  6. package/TunnelShare-hdq9h1hr.js +14 -0
  7. package/agent.command-20zaqe60.js +49 -0
  8. package/akanCode.js +13 -8
  9. package/{application.command-wthg8nn9.js → application.command-nd0fshsk.js} +45 -12
  10. package/{applicationBuildRunner-t2r84sz6.js → applicationBuildRunner-s13x3zqb.js} +14 -10
  11. package/buildBatch.proc.js +7 -7
  12. package/{cloud.command-sz11hpre.js → cloud.command-8kbddsz9.js} +28 -19
  13. package/cloud.script-hgvvajm3.js +27 -0
  14. package/code.command-625bg8s8.js +345 -0
  15. package/commandManifest.json +1 -1
  16. package/{context.command-15j9b7c0.js → context.command-p6haqjay.js} +20 -18
  17. package/context.runner-rsnqnk9j.js +27 -0
  18. package/{dependencyScanner-3afj2vt1.js → dependencyScanner-78sq8m4q.js} +2 -2
  19. package/{devTui-q7k7bakd.js → devTui-evr3b35y.js} +1 -1
  20. package/{fileSys-wzzrntkw.js → fileSys-zpvt5gtf.js} +1 -1
  21. package/{guideline.command-snh85ctf.js → guideline.command-195g0h9a.js} +4 -4
  22. package/guidelines/agentRule/agentRule.instruction.md +22 -8
  23. package/guidelines/conventions/core.md +106 -0
  24. package/guidelines/conventions/rules/app.md +83 -0
  25. package/guidelines/conventions/rules/auth.md +46 -0
  26. package/guidelines/conventions/rules/config.md +60 -0
  27. package/guidelines/conventions/rules/constant.md +24 -0
  28. package/guidelines/conventions/rules/gates.md +32 -0
  29. package/guidelines/conventions/rules/layer.md +25 -0
  30. package/guidelines/conventions/rules/migration.md +27 -0
  31. package/guidelines/conventions/rules/module.md +90 -0
  32. package/guidelines/conventions/rules/page.md +56 -0
  33. package/guidelines/conventions/rules/sensitive.md +16 -0
  34. package/guidelines/conventions/rules/server.md +91 -0
  35. package/guidelines/conventions/rules/ssr.md +47 -0
  36. package/guidelines/conventions/rules/style.md +43 -0
  37. package/guidelines/conventions/rules/test.md +34 -0
  38. package/guidelines/conventions/rules/ts.md +95 -0
  39. package/guidelines/conventions/rules/tsx.md +76 -0
  40. package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
  41. package/guidelines/pageRule/pageRule.instruction.md +8 -7
  42. package/guidelines/queryRule/queryRule.instruction.md +4 -0
  43. package/guidelines/runtimeRule/runtimeRule.instruction.md +35 -25
  44. package/guidelines/ssrRule/ssrRule.instruction.md +11 -10
  45. package/guidelines/transportRule/transportRule.instruction.md +5 -4
  46. package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +4 -4
  47. package/incrementalBuilder.proc.js +7 -7
  48. package/{index-301pdbzz.js → index-00a7j05x.js} +7 -7
  49. package/{index-js6geqjn.js → index-0j1t1h2b.js} +3 -1
  50. package/{index-6txx6a9p.js → index-1h2jc0x3.js} +154 -88
  51. package/{index-55j120r8.js → index-1qsd8ft1.js} +65 -145
  52. package/{index-9th4gszy.js → index-2mwjshz5.js} +233 -1271
  53. package/index-2nxk8wgs.js +266 -0
  54. package/{index-j9vyj3dj.js → index-2phm56a1.js} +49 -8
  55. package/index-35j83zkd.js +61 -0
  56. package/index-4am4dvmf.js +29 -0
  57. package/index-75y7bcz4.js +28 -0
  58. package/index-7apsdr5g.js +487 -0
  59. package/{index-42j4a8zq.js → index-84h43kg6.js} +8 -6
  60. package/index-9bv479q5.js +1 -0
  61. package/{index-3wypz6xj.js → index-9zy8479y.js} +11 -5
  62. package/{index-a5dhqkdr.js → index-a1vb3x7t.js} +273 -259
  63. package/{index-52w0fvh8.js → index-bns3wcpc.js} +15 -0
  64. package/index-cjmjvg4r.js +3622 -0
  65. package/{index-pcwzkdqb.js → index-defp4gmb.js} +1 -1
  66. package/index-ewbmfarf.js +1606 -0
  67. package/index-fbewhg4g.js +590 -0
  68. package/index-fhw7yq2d.js +653 -0
  69. package/{index-wcej7g4z.js → index-g500c5j9.js} +271 -105
  70. package/{index-74tjjsnc.js → index-g841cap9.js} +33 -37
  71. package/{index-2azahjaw.js → index-gr9thy79.js} +5 -5
  72. package/{index-4pf8g7ff.js → index-h7hehkw6.js} +3 -0
  73. package/{index-xjf5j657.js → index-hm0tn7qv.js} +1001 -91
  74. package/index-j6eeh5d7.js +138 -0
  75. package/{index-31es1yev.js → index-j7hwy56s.js} +108 -7
  76. package/{index-skk9zc1x.js → index-jc2zbwra.js} +2 -2
  77. package/{index-905qdgqp.js → index-khk05tsf.js} +1 -1
  78. package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
  79. package/{index-tvehn2sp.js → index-qd7xn2bk.js} +1 -1
  80. package/{index-a58emady.js → index-qw6814m4.js} +55 -17
  81. package/index-raz588b3.js +445 -0
  82. package/{index-at7bz0xq.js → index-s4nvxpzm.js} +2 -0
  83. package/{index-bt438yxm.js → index-sp0qsr7a.js} +116 -13
  84. package/{index-xb8809yb.js → index-sveq36gh.js} +40 -43
  85. package/{index-hmt54t45.js → index-t1t9wq9a.js} +4 -4
  86. package/index-t78230d7.js +191 -0
  87. package/index-tenw3mah.js +225 -0
  88. package/{index-qfp55x1y.js → index-tgqameyb.js} +4 -4
  89. package/{index-espk51ah.js → index-tp56652m.js} +6 -6
  90. package/index-w15mg3km.js +389 -0
  91. package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
  92. package/{index-2xcc2ax5.js → index-y4kcmbt2.js} +2 -2
  93. package/index-yf9wc28h.js +52 -0
  94. package/{index-0fz95kxe.js → index-zbrwnmf1.js} +9 -7
  95. package/{index-40brg4px.js → index-zttm13c3.js} +5 -5
  96. package/index.js +24 -23
  97. package/{library.command-gycrwhf1.js → library.command-63hgt9te.js} +4 -4
  98. package/{localRegistry.command-jtd8gaes.js → localRegistry.command-g3f8k25t.js} +46 -22
  99. package/{module.command-v6hgs1bc.js → module.command-r4sa2khp.js} +7 -6
  100. package/{package.command-shzpcfph.js → package.command-96eheyvd.js} +5 -5
  101. package/package.json +2 -2
  102. package/{page.command-ptxn5kqk.js → page.command-gs6d841d.js} +4 -4
  103. package/{pipeline.command-zz31pgax.js → pipeline.command-wdfvdbfj.js} +3 -3
  104. package/{primitive.command-a1vse91z.js → primitive.command-dfsv4mpe.js} +8 -7
  105. package/{projectTypecheck-2ztky9cf.js → projectTypecheck-kqj1t6hb.js} +1 -1
  106. package/{prompter-76k56b37.js → prompter-qrwx1p17.js} +2 -2
  107. package/quality.command-webzxee2.js +78 -0
  108. package/{repair.command-cvazbz99.js → repair.command-3r3j1xre.js} +7 -6
  109. package/{routeSourceValidator-6jd0q6r6.js → routeSourceValidator-4h947v7c.js} +13 -3
  110. package/{scalar.command-0acvyp26.js → scalar.command-e8y47j6d.js} +6 -5
  111. package/skills/akan-agent/SKILL.md +43 -0
  112. package/skills/akan-code/SKILL.md +38 -11
  113. package/skills/akan-debug/SKILL.md +41 -6
  114. package/skills/akan-deps/SKILL.md +1 -2
  115. package/skills/akan-err/SKILL.md +2 -1
  116. package/skills/akan-mcp/SKILL.md +40 -0
  117. package/skills/akan-page/SKILL.md +44 -0
  118. package/skills/akan-query/SKILL.md +39 -0
  119. package/skills/akan-runtime/SKILL.md +43 -0
  120. package/skills/akan-scaffold/SKILL.md +16 -6
  121. package/skills/akan-transport/SKILL.md +40 -0
  122. package/skills/akan-validate/SKILL.md +13 -11
  123. package/{subspace.command-822qx2bx.js → subspace.command-a1sf9n5a.js} +12 -10
  124. package/templates/__scalar/__model__/__model__.constant.ts +3 -5
  125. package/templates/__scalar/__model__/__model__.dictionary.ts +6 -5
  126. package/templates/__scalar/__model__/__model__.document.ts +3 -3
  127. package/templates/app/akan.config.ts +2 -3
  128. package/templates/app/env/env.client.ts +2 -4
  129. package/templates/app/env/env.client.type.ts +2 -3
  130. package/templates/app/env/env.server.ts +2 -3
  131. package/templates/app/lib/___appName__/__appName__.dictionary.ts +1 -2
  132. package/templates/app/lib/___appName__/__appName__.service.ts +3 -3
  133. package/templates/app/lib/___appName__/__appName__.signal.ts +5 -5
  134. package/templates/app/lib/___appName__/__appName__.store.ts +4 -6
  135. package/templates/app/lib/option.ts +2 -3
  136. package/templates/app/main.ts +2 -4
  137. package/templates/app/page/_index.tsx +3 -3
  138. package/templates/app/page/_layout.tsx +13 -10
  139. package/templates/appSample/lib/__scalar/workHistory/workHistory.constant.ts +1 -5
  140. package/templates/appSample/lib/__scalar/workHistory/workHistory.dictionary.ts +1 -1
  141. package/templates/appSample/lib/_noti/noti.signal.ts +1 -1
  142. package/templates/appSample/lib/task/Task.Template.tsx +2 -1
  143. package/templates/appSample/lib/task/Task.Unit.tsx +3 -2
  144. package/templates/appSample/lib/task/Task.Util.tsx +16 -4
  145. package/templates/appSample/lib/task/task.constant.ts +1 -5
  146. package/templates/appSample/lib/task/task.dictionary.ts +2 -8
  147. package/templates/appSample/lib/task/task.document.ts +1 -1
  148. package/templates/appSample/lib/task/task.signal.ts +14 -9
  149. package/templates/appSample/page/task/_index.tsx +2 -1
  150. package/templates/appSample/page/task/new.tsx +2 -1
  151. package/templates/appSample/srvkit/guards.ts +11 -0
  152. package/templates/appSample/ui/QuantityControl.tsx +5 -9
  153. package/templates/biomeForm.ts +144 -0
  154. package/templates/crudPages/[__model__Id]/edit/page.tsx +3 -3
  155. package/templates/crudPages/[__model__Id]/page.tsx +5 -5
  156. package/templates/crudPages/new/page.tsx +4 -3
  157. package/templates/crudPages/page.tsx +3 -3
  158. package/templates/crudSinglePage/page.tsx +9 -5
  159. package/templates/libRoot/akan.config.ts +2 -3
  160. package/templates/libRoot/lib/___libName__/__libName__.dictionary.ts +1 -2
  161. package/templates/libRoot/lib/___libName__/__libName__.service.ts +5 -4
  162. package/templates/libRoot/lib/___libName__/__libName__.signal.ts +6 -5
  163. package/templates/libRoot/lib/___libName__/__libName__.store.ts +5 -6
  164. package/templates/libRoot/lib/option.ts +1 -2
  165. package/templates/module/__Model__.Template.tsx +11 -10
  166. package/templates/module/__Model__.Unit.tsx +18 -5
  167. package/templates/module/__Model__.Util.tsx +9 -7
  168. package/templates/module/__Model__.View.tsx +9 -6
  169. package/templates/module/__Model__.Zone.tsx +25 -17
  170. package/templates/module/__model__.constant.ts +8 -9
  171. package/templates/module/__model__.dictionary.ts +16 -17
  172. package/templates/module/__model__.document.ts +6 -8
  173. package/templates/module/__model__.service.ts +3 -3
  174. package/templates/module/__model__.signal.ts +11 -10
  175. package/templates/module/__model__.store.ts +3 -5
  176. package/templates/service/__model__.dictionary.ts +5 -6
  177. package/templates/service/__model__.service.ts +3 -3
  178. package/templates/service/__model__.signal.ts +5 -4
  179. package/templates/service/__model__.store.ts +3 -5
  180. package/templates/workspaceRoot/.gitignore.template +4 -0
  181. package/templates/workspaceRoot/.vscode/settings.json.template +21 -21
  182. package/templates/workspaceRoot/AGENTS.md.template +4 -10
  183. package/{tunnel.command-ycmja19q.js → tunnel.command-dcb0wg93.js} +25 -13
  184. package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
  185. package/typecheck.proc.js +6 -1
  186. package/verify.command-yyepccbh.js +93 -0
  187. package/{workflow.command-abb1d5xy.js → workflow.command-z5pg9ay0.js} +49 -14
  188. package/workspace.command-d7x5jttw.js +290 -0
  189. package/CodeAgent-8d5qs787.js +0 -9
  190. package/CodeAgentRpcListener-7p7z5dd7.js +0 -97
  191. package/TunnelShare-qkm8zp03.js +0 -14
  192. package/agent.command-ydftceda.js +0 -25
  193. package/cloud.script-nqevg5qw.js +0 -24
  194. package/code.command-9h3yrzhe.js +0 -167
  195. package/context.runner-8gg030b0.js +0 -25
  196. package/guidelines/conventions/conventions.instruction.md +0 -617
  197. package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
  198. package/index-2mwc0g0d.js +0 -49
  199. package/index-4vgbysa0.js +0 -279
  200. package/index-7md2g9vw.js +0 -6
  201. package/index-b70zct19.js +0 -856
  202. package/index-c6eggbee.js +0 -123
  203. package/index-zzvvc845.js +0 -74
  204. package/quality.command-ah8qcakd.js +0 -1478
  205. package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
  206. package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
  207. package/workspace.command-qm7cw29v.js +0 -521
@@ -0,0 +1,106 @@
1
+ ## Akan.js
2
+
3
+ Akan.js is a full-stack TypeScript framework: business code written once reaches web, native apps, server, database
4
+ and infrastructure. A workspace is Bun-first: `apps/<app>` holds pages, domain modules, UI, env files and
5
+ `akan.config.ts`; `libs/<lib>` holds shared domain and utility code apps reuse.
6
+
7
+ ## Work Loop
8
+
9
+ 1. Read the module's `*.abstract.md` and its neighbours before changing it. Update the abstract when an invariant, a
10
+ workflow or public behaviour changes, never for a style-only edit.
11
+ 2. Prefer an Akan workflow to a hand edit: `akan workflow list` / `explain <name>` / `plan <name> … --out <plan>` /
12
+ `apply <plan>`, or the `list_workflows` / `plan_workflow` / `apply_workflow` tools of `akan mcp`. Split a
13
+ compound request into workflows applied in order (`create-module`, then `add-field`). Hand-edit only the owning
14
+ source file, and only when no workflow fits or apply reports manual action.
15
+ 3. Never hand-edit a generated file (listed below). After adding, renaming or deleting a file, run
16
+ `akan sync <app-or-lib>`.
17
+ 4. After editing, run `akan verify [<app-or-lib>]` once. It syncs, lints with fixes, typechecks, fast-builds and
18
+ checks SSR over what changed, and prints only what failed. Fix and rerun until it prints `verify ok`; never run
19
+ `akan lint`, `akan typecheck` and `akan build` one by one.
20
+ 5. After a page, UI or runtime change, run `akan preview <app> --changed` (or name the paths) and quote its verdict
21
+ lines; it reuses the running dev server. Name any platform you could not open.
22
+ 6. Check an endpoint with a signal test (`akan test <app> [files]`), never raw HTTP against the dev server.
23
+ 7. Scaffolds take the target positionally (`akan create-module photo <app>`, `akan sync <app>`); only `add-field` and
24
+ `add-enum-field` take `--app` / `--module`.
25
+
26
+ ## Change Scope
27
+
28
+ - Change what the task needs and the files directly tied to it — no formatting-only diffs, no style rewrites nearby.
29
+ - Never revert or overwrite someone else's change in a dirty working tree.
30
+ - Follow the nearest established pattern; when two shapes disagree, follow the newer neighbour. A new abstraction must
31
+ remove real duplication — near-identical sibling modules are copied with changed literals, not parameterised.
32
+
33
+ ## Looks Wrong, Is Right — Do Not "Fix"
34
+
35
+ - Tailwind class order (`font-bold text-2xl text-foreground`) — Biome sorts it, `cn()` arguments included.
36
+ - `static name = "User";` on a guard class — `fetch` serializes it and the API explorer filters on it.
37
+ - `(this as unknown as RootStore).logout()` in a store — the sanctioned way to reach another store.
38
+ - `key={idx}` and short dependency arrays — `noArrayIndexKey` and `useExhaustiveDependencies` are off on purpose.
39
+ - Empty scaffold files, empty dictionary stages, the `// state` / `// action` markers — they mark where code goes.
40
+ - One-line re-export shims in a lib's `common/`, `webkit/`, `ui/` — the only legal path for a third-party package.
41
+ - `return await …save()` in a service; `as const` on every `enumOf(...)` array.
42
+ - Typos and transliterated terms in domain vocabulary — callers match on the name.
43
+
44
+ ## Rules That Break The Build
45
+
46
+ `akan verify` reports each through the check named in parentheses, and the bracketed path rule carries the full
47
+ contract. Path rules name their checks the same way.
48
+
49
+ - Throw `new Err("<module>.error.<key>")` with the key in the module dictionary's `.error({})`; never a raw `Error`
50
+ (`no-throw-raw-error`) [app].
51
+ - A third-party package reaches `page/**`, a barrel or a module file only through a lib re-export
52
+ (`no-import-external-library`) [app].
53
+ - Colors only from the semantic vocabulary (`bg-primary`, `text-foreground/70`) — no palette, arbitrary, daisyUI or
54
+ `style={{}}` colors (`no-raw-palette-class`, `no-arbitrary-color`, `no-daisyui-legacy-class`, `no-inline-color`)
55
+ [style].
56
+ - No `console.log` / `console.debug`, never `logger.log()` (`noConsole`, `no-deprecated-log-level`); server code logs
57
+ through `this.logger` [app].
58
+ - No `document.cookie`, `localStorage` or `sessionStorage` (`no-document-cookie`, `no-web-storage`) — `getCookie`,
59
+ `setCookie`, `storage`, `secretStorage` from `akanjs/client` [app].
60
+ - Client files never import server files and the reverse (`no-import-server-in-client`, `no-import-client-in-server`);
61
+ `import type` is legal everywhere [ssr].
62
+ - A server write leaves the browser only through a store action, one write per action or handler
63
+ (`akan.write.placement`, `akan.store.multi-write`, `akan.component.write-chain`); chained writes become one service
64
+ method behind one endpoint [gates].
65
+ - Every endpoint and named slice names its `guards`, `[Public]` when anonymous is the intent (`no-unguarded-endpoint`)
66
+ [auth].
67
+ - Never ask a list for more than 500 rows (`no-oversized-list-limit`) [module]; never call a hook conditionally, `st.*`
68
+ hooks included (`useHookAtTopLevel`, `no-conditional-st-hook`) [tsx].
69
+ - A file or component past its size limit fails (`akan.size.file`, `akan.size.component`), and `akan.baseline.json`
70
+ only shrinks (`akan.baseline.growth`) — never add or raise an entry [gates].
71
+ - Suppress a plugin diagnostic as `// biome-ignore lint/plugin: <reason>`; every suppression carries a reason [app].
72
+
73
+ ## Code Style
74
+
75
+ - `const` arrow functions over `function`; `interface` for shapes, `type` for unions; no non-null assertions
76
+ (`as unknown as T`, never `as any`); `#private`, but `private` in `*.{constant,document,service,store}.ts`.
77
+ - One class per file, named after it; TypeScript files are camelCase, component and convention files excepted.
78
+ - Identifiers, endpoint names and logs are English; everything a user reads goes through `l("model.field")` or
79
+ `l.trans({ en, ko })`, and dictionary entries are `[en, ko]` pairs.
80
+ - Comment only what the code cannot say (`akan verify` flags each new one as `akan.comment.added`) — a vendor quirk,
81
+ an infrastructure constraint, security reasoning, a domain field's meaning, a state transition, a rejected
82
+ alternative. Never restate code, label a section or add JSDoc; retire a symbol with
83
+ `/** @deprecated <what instead> */`.
84
+ - Server rendering is the default: `"use client"` only for a hook, an event handler, the store, a browser global or
85
+ a client-only package.
86
+
87
+ ## Where Code Goes
88
+
89
+ | Code | Place |
90
+ |---|---|
91
+ | A database-backed noun (User, Product) | `lib/<model>/` — `akan create-module <model> <app>` |
92
+ | A workflow or integration with no stored model | `lib/_<service>/` — `akan create-service <service> <app>` |
93
+ | An embedded value type (Address) | `lib/__scalar/<scalar>/` — `akan create-scalar <scalar> <app>` |
94
+ | A route | `page/` — `<route>.tsx`, `_index.tsx`, `_layout.tsx`, `[param]/` |
95
+ | A pure, isomorphic helper | `common/<name>.ts` (imports `akanjs/base` only, never throws) |
96
+ | A React hook, browser or native-bridge code | `webkit/use<Thing>.tsx` |
97
+ | An adapter, guard, or code touching `node:*`, `Bun`, env or a secret | `srvkit/<name>.ts` |
98
+ | JSX or a look not bound to one model | `ui/<Component>.tsx`, `ui/Recipe/<name>.ts` |
99
+ | The color theme | semantic token values in `page/styles.css` |
100
+ | An iOS, Android or desktop app | `native: { … }` in `akan.config.ts`; an owned plugin in `native/<id>/` |
101
+ | A change to the stored document shape | `akan create-migration <name> <app>` |
102
+
103
+ ## Secrets
104
+
105
+ Never print, summarise or commit secret values, credentials, tokens, private keys or `.env` contents; name env keys
106
+ with placeholders only. `AKAN_PUBLIC_*` values ship to the browser — never put a secret in one.
@@ -0,0 +1,83 @@
1
+ ---
2
+ description: Akan app and library code: the lint gates, sync allowlists and the warts not to copy.
3
+ paths:
4
+ - "{apps,libs}/**"
5
+ ---
6
+
7
+ # Akan App And Library Code
8
+
9
+ ## Rules Every File Obeys
10
+
11
+ `biome.json` extends `@akanjs/devkit/biome.base.json`, which scopes every grit plugin in `@akanjs/devkit/lint/`;
12
+ each plugin's header and diagnostic carry its full reasoning.
13
+
14
+ - **Never construct a raw `Error`** (`no-throw-raw-error`). Throw `new Err("<module>.error.<key>")` with the key
15
+ registered as `[en, ko]` in the module dictionary's `.error({})` — imported from `"../dict"` on the server, from
16
+ `"@libs/<lib>/client"` / `"@apps/<app>/client"` in UI. A `throw` is an error; a raw `Error` rejected, returned or
17
+ stored loses the key and status too (a warning for now). Exempt: tests, `*.constant.ts`, a root `native/` folder
18
+ (plugins throw `AkanNativeError`), `script/migration/**` (an operator reads its message), and `common/**` / `env/**`,
19
+ which have no legal `Err` import — keep throwing code out of them.
20
+ - **Never import a third-party package** (`no-import-external-library`) from `page/**`, any barrel, a module logic file
21
+ (`*.{constant,dictionary,document,service,signal,store}.ts`) or module component
22
+ (`*.{Template,Unit,Util,View,Zone}.tsx`) — re-export it through a lib first (one-line shims in a lib's `common/`,
23
+ `webkit/`, `ui/` are load-bearing). `*.signal.test.ts` / `*.service.test.ts` too, though they may import `node:*` and
24
+ `bun:*` (`no-import-external-library-in-test`).
25
+ - **No `console.log` / `console.debug`** (`noConsole`; only `assert`, `error`, `info`, `warn`; server code uses
26
+ `this.logger` or `new Logger("ClassName")`), and **never `logger.log()` / `Logger.log()`** (`no-deprecated-log-level`)
27
+ — it emits at `info` while reading like its own level; write `.info()`. The ladder is
28
+ `trace verbose debug info warn error`.
29
+ - **Never touch `document.cookie`, `localStorage` or `sessionStorage`** (`no-document-cookie`, `no-web-storage`) — a
30
+ native shell's page keeps no cookies on iOS, macOS and Linux, and Web Storage throws during SSR. Use `getCookie` /
31
+ `setCookie` / `removeCookie`, `storage`, `secretStorage` from `akanjs/client`. Browser APIs a WebView lacks
32
+ (`navigator.share`, `serviceWorker`, `Notification`, `geolocation`, `vibrate`) live in a `webkit/` hook behind
33
+ `isNativeApp()` (`no-web-only-api-outside-webkit`, a warning). Both in full: `runtimeRule`.
34
+ - **No deep imports past a barrel** (`no-deep-internal-import`), except cross-module constants (`../map/map.constant`).
35
+ - **Suppress a grit diagnostic as `lint/plugin`** (`// biome-ignore lint/plugin: <reason>`,
36
+ `// biome-ignore-all lint/plugin: <reason>`); bare `plugin:` does nothing. `pkgs/` is out of scope.
37
+ - **`biome.json` is strict JSON** — a comment breaks config resolution without an error (Biome falls back to
38
+ discovery and aborts on a nested config); rename it `biome.jsonc` to document a disabled rule.
39
+ - **`akan lint` prints up to 200 diagnostics** (`--max-diagnostics <n>`, `0` = all); Biome's own uncounted 20 reads
40
+ as progress when the mix merely changed.
41
+
42
+ ## Akan Sync Conventions
43
+
44
+ - App root files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.baseline.json`, `akan.config.ts`, `client.ts`,
45
+ `main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`; folders: `.akan`, `common`, `env`,
46
+ `lib`, `native`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`. A Capacitor-era
47
+ `ios` / `android` / `mobile` folder or `capacitor.config.*` in an app root is refused as a leftover (native
48
+ projects live under `dist/native/<app>/<target>`).
49
+ - Lib root files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `akan.baseline.json`, `akan.config.ts`, `akan.lib.json`,
50
+ `client.ts`, `index.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.spec.json`, `tsconfig.tsbuildinfo`;
51
+ folders: the app's minus `.akan`, `script`, `secrets` (no `main.ts` either — a lib is never booted).
52
+ - The allowlists' one source is `pkgs/@akanjs/devkit/workspaceLayout.ts`, read by `akan sync` (error), `akan doctor`
53
+ and `akan quality scan` — add an entry there and mirror it here.
54
+ - `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` carry a generated `## Recipes In Scope` block between the
55
+ `akan:agent` markers — never hand-edit it (outside the markers is yours); `akan lint` fails when it is stale.
56
+ - `plugin/<name>.plugin.ts` declares an Akan plugin. No `apps/*/base` or `libs/*/base` — use `common/`.
57
+ - `lib/` root holds only `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`,
58
+ `useServer.ts` — no hand-written file or test.
59
+ - Modules are `lib/<model>`, `lib/_<service>`, `lib/__scalar/<scalar>`; their UI files are
60
+ `<Model>.Template|Unit|Util|View|Zone.tsx`, `<Service>.Util|Zone.tsx`, `<Scalar>.Template|Unit.tsx`. A test is
61
+ named after the one file it covers, so `<model>.<topic>.signal.test.ts` is refused like `<model>.<topic>.signal.ts`.
62
+ - `ui/`, `webkit/`, `srvkit/`, `common/`, `plugin/` and module `index.ts` barrels are generated
63
+ (`export * from "./name";` per 1-depth entry, `export {};` when empty, so a stale one heals on sync;
64
+ `akan create-library` starts `common/`, `srvkit/`, `webkit/`, `ui/` with that empty barrel) — never hand-edit or
65
+ track them. **Never hand-write an
66
+ `index.tsx` / `.jsx` / `.mts` at those roots**: Bun resolves it before the generated `index.ts`, so new exports are
67
+ `undefined` at runtime (`akan sync` refuses it, `akan doctor` reports `facet-index-shadowed`); a namespace belongs
68
+ in `ui/<Folder>/index.tsx`.
69
+ - Sync writes barrels, module indexes and `akan.*.json` exactly as Biome prints them (`akan lint --no-fix` passes
70
+ right after a sync), so a lint diff in one is a generator bug — fix the generator.
71
+ - **`akan sync` owns package.json `dependencies`**: it adds imports at the root's version, realigns root-declared
72
+ entries, and drops unimported ones (logged); undeclared-at-root entries are kept with a warning. Keep a package no
73
+ TS file imports (a CSS `@plugin`, a runtime-only package) with `akan.keepDependencies`; `externalLibs` and
74
+ `trustedDependencies` always stay; devDependencies are realigned, never pruned. `akan install-library` lets the
75
+ root win — it adds only what the root lacks and warns when the lib wants a newer version.
76
+
77
+ ## Present In The Code — Do Not Imitate
78
+
79
+ Warts in older files — never copy them; when two shapes disagree, follow the newer neighbour: `children: any`
80
+ (use `ReactNode`); hard-coded API keys or secrets (they belong in `option.ts` or env); large commented-out blocks;
81
+ stale `// TODO: Implement …` above implemented methods; `{cond && <X/>}`, hard-coded Korean bypassing `l()`,
82
+ `window.alert(...)`; bare `/* eslint-disable */` blocks; raw palette grays like `text-gray-400`. A store reaching
83
+ another through `(this as unknown as RootStore)` is **not** a wart — it is the sanctioned way.
@@ -0,0 +1,46 @@
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 declares none. `Public` belongs on a slice `get:`;
15
+ on a mutation only for an act that must work signed out (sign-up/in, token refresh, an OAuth route), which also
16
+ declares a `rateLimit`. A guardless endpoint answers every call with 403 and stops the boot outside local
17
+ operation; MCP also refuses a mutation guarded only by `Public`.
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
+ refuses every caller, and outside local operation the server does not boot. Write `guards: [Public]` when
32
+ anonymous access is the intent.
33
+
34
+ - **A `slice()` takes its guard map as a second argument**, `slice(srv.task, { guards: { root: Admin, get: SignedIn,
35
+ cru: SignedIn } }, (init) => ({...}))`. An `endpoint()` takes no guard argument at all —
36
+ `endpoint(srv.task, ({ mutation }) => ({...}))` — so **every custom `mutation` / `query` / `message` names its own
37
+ `guards: [...]` array**: `mutation(cnst.Task, { guards: [SignedIn] })`. `Public` always allows; other guards
38
+ implement the `Guard` interface in `srvkit/` (server-only).
39
+ - **Read the caller inside a guard** with `context.get<T>("account")`, which works on HTTP and websocket calls
40
+ alike — never branch on `getHttpContext()` / `getWebSocketContext()`. Every guard class also declares
41
+ `static scope: GuardScope`, `"account"` or `"resource"`, with no default.
42
+ - **Read the current user inside a custom endpoint** by injecting an `InternalArg` with `.with(...)`:
43
+ `mutation(cnst.Task, { guards: [SignedIn] }).with(CurrentUserId).exec(async function (currentUserId) { ... })`.
44
+ - **Auto-generated CRUD and `serve()` service methods / lifecycle hooks do not receive session context.** If an
45
+ operation needs the acting user, expose a custom endpoint that takes it via `.with(CurrentUserId)` — never trust a
46
+ client-supplied user id.
@@ -0,0 +1,60 @@
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
+ - **`i18n: { localePrefix: "as-needed" }`** serves the default locale at unprefixed paths (`/pokemon/x`, and `<Link>`
31
+ renders them so) while other locales keep `/<locale>/…`. Use it, not a raw `<a>`, for a single-language app or URLs
32
+ fixed from outside (OAuth callbacks, QR codes, mail links, a migrated site).
33
+
34
+ ## Running An App
35
+
36
+ - After changing application code, run `bun run akan start <appName>` (`a,b`, `a b`, or `all` for several); check
37
+ the production build with `bun run akan build <appName>`, and serve it without Docker with
38
+ `cd dist/apps/<appName> && bun main.js` (`PORT` or any variable you set overrides the build's env).
39
+ - A supervised session writes `local/apps/<app>/runtime/dev.log` (previous: `dev.prev.log`) — hand over that path,
40
+ not a paste of the repainting full-screen view. Keys, `--plain`, boot waves, `--kill`, watch scope, running a
41
+ built artifact, booting a server in a test: `runtimeRule`.
42
+
43
+ ## Native Apps
44
+
45
+ `native: { desktop: { server: true } }` in `akan.config.ts` is all a desktop app that carries its own server needs.
46
+ A `start-*` command loads its pages from `akan start`, so run that first; a desktop app that carries its server
47
+ starts it itself. The full contract — targets, updates, what the carried server ships — is
48
+ `akan guideline show runtimeRule`.
49
+
50
+ ```bash
51
+ akan start-desktop <app> # Run the desktop app on this computer
52
+ akan start-ios <app> # Run it in a simulator or on an iPhone (start-android alike)
53
+ akan build-desktop <app> # Build it for this computer into dist/native/<app>/<target>/build
54
+ akan build-desktop <app> --installer true # Windows: add a per-user setup program
55
+ akan update-keygen <app> # Make the update signing key once; print its public key
56
+ akan publish-update <app> # Build a key-signed release for updates.url; --sign true also code-signs it
57
+ ```
58
+
59
+ A device capability the framework lacks is a plugin the app owns in `native/<id>/`: `native-plugin.json`,
60
+ `src/index.ts` (the page API, used from a `webkit/` hook), `src/desktop.ts`, Kotlin and Swift.
@@ -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,32 @@
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 (`create<Model>Many`). An `internal` job and a counted loop (a retry, paging) are
28
+ spared.
29
+ - `akan.baseline.json` (`akan.baseline.growth`) records, per rule, the debt adopted with the gate, and is compared
30
+ with its copy at the fork point of the default branch, so it only ever shrinks: never add or raise an entry. A size,
31
+ store-reach or per-item entry with a `reasons` line is an exception a person decided on, never an agent; the write
32
+ 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`); a list of new rows is one `create<Model>Many(rows)`. 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`.