@akanjs/cli 3.1.1-rc.16 → 3.1.1-rc.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.build-stamp +1 -1
- package/{CodeAgent-23ewzxqa.js → CodeAgent-fbcq8vks.js} +2 -2
- package/{CodeTui-kc99fk78.js → CodeTui-0626gxqd.js} +1 -1
- package/TunnelShare-2p24xxza.js +14 -0
- package/agent.command-hpza0pg9.js +46 -0
- package/akanCode.js +5 -3
- package/{application.command-bvfd1680.js → application.command-3a7q1hs2.js} +11 -10
- package/{applicationBuildRunner-4ajaesk1.js → applicationBuildRunner-s7yt71j4.js} +5 -5
- package/buildBatch.proc.js +6 -6
- package/{cloud.command-f2w40fyy.js → cloud.command-4vg0pcea.js} +15 -14
- package/cloud.script-nkmeyhet.js +25 -0
- package/{code.command-dbhhnahn.js → code.command-fbntb67p.js} +6 -6
- package/commandManifest.json +1 -1
- package/{context.command-yswjwv6y.js → context.command-31rm54v0.js} +18 -18
- package/context.runner-w01a32ph.js +26 -0
- package/{guideline.command-ztx6dkpk.js → guideline.command-cv3by2ng.js} +3 -3
- package/guidelines/conventions/core.md +104 -0
- package/guidelines/conventions/rules/app.md +83 -0
- package/guidelines/conventions/rules/auth.md +45 -0
- package/guidelines/conventions/rules/config.md +56 -0
- package/guidelines/conventions/rules/constant.md +24 -0
- package/guidelines/conventions/rules/gates.md +31 -0
- package/guidelines/conventions/rules/layer.md +25 -0
- package/guidelines/conventions/rules/migration.md +27 -0
- package/guidelines/conventions/rules/module.md +90 -0
- package/guidelines/conventions/rules/page.md +56 -0
- package/guidelines/conventions/rules/sensitive.md +16 -0
- package/guidelines/conventions/rules/server.md +86 -0
- package/guidelines/conventions/rules/ssr.md +47 -0
- package/guidelines/conventions/rules/style.md +43 -0
- package/guidelines/conventions/rules/test.md +34 -0
- package/guidelines/conventions/rules/ts.md +95 -0
- package/guidelines/conventions/rules/tsx.md +75 -0
- package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
- package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +3 -3
- package/incrementalBuilder.proc.js +6 -6
- package/{index-xjwcp91m.js → index-05nxx4m5.js} +43 -12
- package/{index-k9k18vq9.js → index-0ht91675.js} +37 -59
- package/{index-er16p89s.js → index-0zwznvv1.js} +1 -1
- package/{index-76jwsm3g.js → index-0zyatd10.js} +2 -2
- package/{index-97fsvy66.js → index-12kzwak1.js} +3 -3
- package/{index-005dqc83.js → index-1dhf8ymv.js} +2 -2
- package/{index-00ke4phc.js → index-3gccwenr.js} +1 -1
- package/{index-2epb3wgh.js → index-3txrjt6n.js} +2 -2
- package/{index-7ndgffg4.js → index-57q1ayd2.js} +18 -1240
- package/index-5kh9scvs.js +514 -0
- package/index-5n5hds19.js +1246 -0
- package/{index-9sa6abze.js → index-6269mf2s.js} +10 -9
- package/{index-921cxqrd.js → index-64g9fsjy.js} +41 -12
- package/index-7zeb5r1p.js +653 -0
- package/{index-s4c2y5gs.js → index-8s8b4eba.js} +45 -4
- package/{index-4332q6yj.js → index-922k2zwq.js} +3 -3
- package/{index-m6qgr1rx.js → index-9ndw5d8j.js} +7 -7
- package/{index-xfp4dcnx.js → index-et6ce601.js} +1 -1
- package/{index-saj9cx3a.js → index-f5adsa58.js} +4 -4
- package/{index-vgt25eh1.js → index-fbewhg4g.js} +7 -32
- package/{index-ysyt782g.js → index-hm7x0c11.js} +4 -4
- package/{index-2p1brf5e.js → index-hvv5rnaq.js} +2 -2
- package/index-jje9qzyq.js +27 -0
- package/{index-rxse80x6.js → index-js1gj6f6.js} +12 -10
- package/{index-p2pahmsa.js → index-kjrvwzav.js} +3 -3
- package/index-m6r88hhr.js +3582 -0
- package/{index-mk391h0z.js → index-mt0wa941.js} +4 -4
- package/{index-m93qg20j.js → index-mwj9q2ya.js} +1 -1
- package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
- package/index-r2wedvqn.js +138 -0
- package/{index-gxj80jz7.js → index-rvynj5gz.js} +1 -1
- package/{index-m54n0v29.js → index-tdv66eah.js} +4 -4
- package/{index-vq77g679.js → index-w134p86k.js} +1 -1
- package/{index-deeskxjh.js → index-wfczhj1z.js} +14 -36
- package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
- package/{index-qx4r4cj2.js → index-x5ecanqh.js} +2 -2
- package/{index-nzfgyw3b.js → index-zre4m2ce.js} +4 -4
- package/index.js +23 -22
- package/{library.command-hmbkcwzw.js → library.command-sh70fyvy.js} +3 -3
- package/{localRegistry.command-sq5p4c9x.js → localRegistry.command-2nbyy84d.js} +14 -13
- package/{module.command-n4z29zcv.js → module.command-n0bmtzwy.js} +5 -5
- package/{package.command-20025dy3.js → package.command-7h9r51bz.js} +3 -3
- package/package.json +2 -2
- package/{page.command-q8fvpjer.js → page.command-vjtpfbb1.js} +3 -3
- package/{pipeline.command-8j97fq88.js → pipeline.command-c93se3ar.js} +2 -2
- package/{primitive.command-e5y6dqp1.js → primitive.command-a3075qp2.js} +6 -6
- package/{projectTypecheck-tbdye9k3.js → projectTypecheck-sf9xwaga.js} +1 -1
- package/{prompter-76k56b37.js → prompter-hgcta8pb.js} +1 -1
- package/quality.command-dw1y9hmy.js +76 -0
- package/{repair.command-dq1gckth.js → repair.command-tg57d8yt.js} +5 -5
- package/{scalar.command-5vwf152w.js → scalar.command-cwzge353.js} +4 -4
- package/skills/akan-agent/SKILL.md +36 -0
- package/skills/akan-debug/SKILL.md +3 -3
- package/skills/akan-deps/SKILL.md +1 -2
- package/skills/akan-mcp/SKILL.md +40 -0
- package/skills/akan-page/SKILL.md +44 -0
- package/skills/akan-query/SKILL.md +38 -0
- package/skills/akan-runtime/SKILL.md +40 -0
- package/skills/akan-scaffold/SKILL.md +16 -6
- package/skills/akan-transport/SKILL.md +40 -0
- package/skills/akan-validate/SKILL.md +13 -11
- package/{subspace.command-182be8vj.js → subspace.command-3h03c7kc.js} +8 -8
- package/templates/workspaceRoot/.gitignore.template +3 -0
- package/templates/workspaceRoot/AGENTS.md.template +4 -10
- package/{tunnel.command-bfzj7xkb.js → tunnel.command-czaz6ys4.js} +7 -7
- package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
- package/typecheck.proc.js +6 -1
- package/verify.command-nzwhtz71.js +91 -0
- package/{workflow.command-3g53242s.js → workflow.command-srhky88x.js} +23 -13
- package/{workspace.command-h7399jwv.js → workspace.command-9stchcd2.js} +31 -29
- package/TunnelShare-dk2gw78d.js +0 -14
- package/agent.command-knp5j7bq.js +0 -25
- package/cloud.script-2r82sv0f.js +0 -24
- package/context.runner-c3wsh2jw.js +0 -26
- package/guidelines/conventions/conventions.instruction.md +0 -663
- package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
- package/index-4t4qb8jg.js +0 -279
- package/index-hvg3esm0.js +0 -1844
- package/index-zzvvc845.js +0 -74
- package/quality.command-168pt5vm.js +0 -1788
- package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
- package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
|
@@ -1,663 +0,0 @@
|
|
|
1
|
-
## Repo Overview
|
|
2
|
-
|
|
3
|
-
- Akan.js is a full-stack TypeScript framework: write one line and deploy across web, app, server, database, and
|
|
4
|
-
infrastructure. It abstracts the technical implementation so what remains is business code — minimal, fast, and
|
|
5
|
-
type-safe everywhere at once.
|
|
6
|
-
- This is a Bun-first monorepo: `apps/<app>` (pages, domain code, UI, env files, `akan.config.ts`), `libs/*` (shared
|
|
7
|
-
domain and utility libraries), `pkgs/akanjs/*` (framework, runtime, and tooling facets published through the single
|
|
8
|
-
`akanjs` package — extend an existing facet before adding a framework-level pattern), and `infra/` (Helm,
|
|
9
|
-
deployment templates, edge configs, Jenkins env/secret scripts).
|
|
10
|
-
|
|
11
|
-
## Change Scope
|
|
12
|
-
|
|
13
|
-
- Keep edits scoped to the requested task and the directly related files.
|
|
14
|
-
- Do not reformat unrelated files or rewrite nearby code just for style.
|
|
15
|
-
- Do not revert or overwrite unrelated user changes in a dirty working tree.
|
|
16
|
-
- Prefer established nearby patterns over introducing a new abstraction.
|
|
17
|
-
- Add new abstractions only when they remove real duplication or match an existing project pattern.
|
|
18
|
-
|
|
19
|
-
## Deep-Dive Guidelines
|
|
20
|
-
|
|
21
|
-
This file carries the rules. The reasoning, the measurements, and the per-feature edge cases live in guidelines
|
|
22
|
-
you fetch on demand — `get_guideline` with the name, or `akan guideline show <name>`. Fetch the relevant one
|
|
23
|
-
**before** a deep pass on that area; a section below that points at one is a summary, not the whole contract.
|
|
24
|
-
|
|
25
|
-
| name | covers |
|
|
26
|
-
|---|---|
|
|
27
|
-
| `ssrRule` | server-share targets, the `akan.ssr.*` warnings, the client-boundary playbook |
|
|
28
|
-
| `pageRule` | route files, the route chain, heads, root layouts in a CSR bundle, lib pages |
|
|
29
|
-
| `runtimeRule` | web surfaces, gateway vs solo, the dev server, logging, the image, native apps and a desktop server, database modes |
|
|
30
|
-
| `queryRule` | slices and hydration, filter methods, soft removal and the facade's writes, full-text search, cascade |
|
|
31
|
-
| `transportRule` | guards and writing one, deadlines, cache, rate limits, server-to-server calls, bytes, binary pubsub, verbs |
|
|
32
|
-
| `mcpRule` | MCP exposure, configuration, wire behaviour, OAuth, page prompts, MCP Apps |
|
|
33
|
-
| `agentRule` | the in-page agent: chat options, tools, forms, zones, slash commands, compaction |
|
|
34
|
-
| `fieldRule` | field types, `hidden` / `secret` / `visual`, immutable and `Date` fields, image and file fields |
|
|
35
|
-
| `cssRule` | the semantic token set, the color vocabulary lint enforces, lib-owned tokens |
|
|
36
|
-
| `componentRule` / `recipeRule` | `_overrides.tsx` slots and drop-in components / authoring and consuming recipes |
|
|
37
|
-
| `workspaceRecipes` | worked recipes (fields, injection and `adapt()`, slices, endpoints, internals, insights), the generated API |
|
|
38
|
-
|
|
39
|
-
Module structure and each module file have their own guide (`moduleOverview`, `modelConstant` … `modelZone`,
|
|
40
|
-
`scalarConstant`, `scalarDictionary`, `scalarModule`).
|
|
41
|
-
|
|
42
|
-
## Lint-Enforced Rules (These Break The Build)
|
|
43
|
-
|
|
44
|
-
`biome.json` extends `@akanjs/devkit/biome.base.json`, which scopes every grit plugin in `@akanjs/devkit/lint/`;
|
|
45
|
-
each plugin's header and diagnostic carry its full reasoning. Several rules produce output that looks wrong — do
|
|
46
|
-
not "fix" it back.
|
|
47
|
-
|
|
48
|
-
- **Never hand-order Tailwind classes** — `nursery/useSortedClasses` sorts them, `cn()` arguments included, and its
|
|
49
|
-
output (`font-bold text-2xl text-foreground`) is correct.
|
|
50
|
-
- **Stay inside the color vocabulary**: no raw palette (`bg-blue-500`), arbitrary or interpolated color classes
|
|
51
|
-
(`bg-[#3b82f6]`), daisyUI classes or slots (`btn-primary`, `bg-base-100`), or color literals in `style={{}}` —
|
|
52
|
-
they render no CSS. Use semantic tokens (`bg-primary`, `text-foreground/70`); a legitimate fixed color takes
|
|
53
|
-
`// biome-ignore lint/plugin: <reason>`. Slot replacements, SVG / `el.style` warnings, legal values: `cssRule`.
|
|
54
|
-
- **Never construct a raw `Error`.** Throw `new Err("<module>.error.<key>")` with the key registered as `[en, ko]` in
|
|
55
|
-
the module dictionary's `.error({})` — imported from `"../dict"` on the server, from `"@libs/<lib>/client"` /
|
|
56
|
-
`"@apps/<app>/client"` in UI. A `throw` is an error; a raw `Error` rejected, returned or stored loses the key and
|
|
57
|
-
status too (a warning for now). Exempt: tests, `*.constant.ts`, a root `native/` folder (plugins throw
|
|
58
|
-
`AkanNativeError`), `script/migration/**` (an operator reads its message), and `common/**` / `env/**`, which have
|
|
59
|
-
no legal `Err` import — keep throwing code out of them.
|
|
60
|
-
- **Never import a third-party package** from `page/**`, any barrel, a module logic file
|
|
61
|
-
(`*.{constant,dictionary,document,service,signal,store}.ts`) or module component
|
|
62
|
-
(`*.{Template,Unit,Util,View,Zone}.tsx`) — re-export it through a lib first (one-line shims in a lib's `common/`,
|
|
63
|
-
`webkit/`, `ui/` are load-bearing). `*.signal.test.ts` / `*.service.test.ts` too, though they may import `node:*`
|
|
64
|
-
and `bun:*`.
|
|
65
|
-
- **`#private` is banned in exactly `*.constant.ts`, `*.document.ts`, `*.service.ts`, `*.store.ts`** (by path, so it
|
|
66
|
-
stays the house style everywhere else, `srvkit/` and `adapt()` classes included).
|
|
67
|
-
- **No `console.log` / `console.debug`** (only `assert`, `error`, `info`, `warn`; server code uses `this.logger` or
|
|
68
|
-
`new Logger("ClassName")`), and **never `logger.log()` / `Logger.log()`** — it emits at `info` while reading like
|
|
69
|
-
its own level; write `.info()`. The ladder is `trace verbose debug info warn error`.
|
|
70
|
-
- **No `//!` or `/*!` in browser-reachable code** (`ui/`, `webkit/`, `common/`, `page/**/*.tsx`, `*.constant.ts`,
|
|
71
|
-
`*.store.ts`, module components) — Bun keeps both through minification. Use `// FIXME:`.
|
|
72
|
-
- **`{name}`, never `{{name}}`**, in a dictionary `.error()` / `.translate()` entry — only single braces interpolate.
|
|
73
|
-
- **Every endpoint and named slice names its guards** (warning) — a `query` / `mutation` / `pubsub` / `message`, a
|
|
74
|
-
named slice's `init()`, or a `slice()` map without `root` that names none (or `guards: []`) answers every caller.
|
|
75
|
-
Write `guards: [Public]` when anonymous access is the intent.
|
|
76
|
-
- **Never touch `document.cookie`, `localStorage` or `sessionStorage`** — a native shell's page keeps no cookies on
|
|
77
|
-
iOS, macOS and Linux, and Web Storage throws during SSR. Use `getCookie` / `setCookie` / `removeCookie`,
|
|
78
|
-
`storage`, `secretStorage` from `akanjs/client`. Browser APIs a WebView lacks (`navigator.share`, `serviceWorker`,
|
|
79
|
-
`Notification`, `geolocation`, `vibrate`) live in a `webkit/` hook behind `isNativeApp()` (warning). Both in full:
|
|
80
|
-
`runtimeRule`.
|
|
81
|
-
- **Never return a value from a store action** — actions dispatch through `st.do.*` as `void`; write state with
|
|
82
|
-
`this.set({ ... })`. A bare `return;`, a nested callback's `return`, a getter, and a `static` helper are fine.
|
|
83
|
-
- **No `static` on an `XObject` or `LightX` class** — `via()` mixes in their prototypes only; use `XInput` (or a
|
|
84
|
-
scalar), `X`, or `XInsight`.
|
|
85
|
-
- **Never redeclare a generated CRUD endpoint name** in `*.signal.ts`.
|
|
86
|
-
- **Never type a `*.Util.tsx` / `*.Zone.tsx` prop as a `cnst` model** — the server would hand a class instance to a
|
|
87
|
-
client component; take `bannerId: string` and read the model from the store. Exempt: `cnst.<Enum>["value"]`, a
|
|
88
|
-
`ClientInit` / `ClientView` / `ClientEdit` / `ModelsProps<…>` type argument, a function-typed prop, a `cnst` type
|
|
89
|
-
that never leaves the file; `ModelProps<…>` and other indexed accesses stay flagged.
|
|
90
|
-
- **Never wrap a form setter in a pass-through arrow** — `(v) => st.do.setTypeOnTicket(v)` emits no
|
|
91
|
-
`data-akan-action` and publishes no agent tool. A wrapper that transforms, adds a statement, or calls `writeOnX`
|
|
92
|
-
is legal; publish it with an explicit `st.tool`.
|
|
93
|
-
- **Never call a hook conditionally** — a skipped call shifts every later hook, and production React crashes
|
|
94
|
-
elsewhere. Biome's `useHookAtTopLevel` checks plain hooks (`useState`, `useEffect`), early returns included.
|
|
95
|
-
`no-conditional-st-hook` checks the `st` hooks it cannot see — `st.use.*`, `st.slice.<x>.use.*`, `st.sel`, `st.ref`,
|
|
96
|
-
`st.tool(…).exec()` / `.card()`, `st.useState(…).init()`, `st.expose(…).value()` — behind `||` / `&&` / `??`, in a
|
|
97
|
-
ternary, an `if`, a `switch`, a loop, a `catch`, a default value, an optional call or a callback; not after an early
|
|
98
|
-
`return` or inside a helper the component calls. Read each into its own `const` at the top, then combine.
|
|
99
|
-
- **Never ask a list for more than 500 rows** (`no-oversized-list-limit`) — the server serves at most 500 per
|
|
100
|
-
request and drops the rest without an error, so `fetch.xListInY(0, 10000)` silently stops at row 500. Page with
|
|
101
|
-
skip/limit or `st.do.loadMoreOf<X>()` while `hasMoreOf<X>`, or compute the figure in an insight or an endpoint.
|
|
102
|
-
- **No deep imports past a barrel**, except cross-module constants (`../map/map.constant`).
|
|
103
|
-
- **Never import across the client/server boundary** (`apps/**`, `libs/**`). Client files (`ui/`, `webkit/`,
|
|
104
|
-
`page/`, `*.store.ts`, every `.tsx`) never import a `*.document|dictionary|service|signal.ts`, `srvkit/`, a
|
|
105
|
-
package `server` entrypoint, or the `db` / `srv` / `sig` / `dict` / `option` / `useServer` barrels. Server files
|
|
106
|
-
(those four suffixes, `srvkit/`) never import a `*.store.ts`, a module component, `ui/`, `webkit/`, a package
|
|
107
|
-
`client` entrypoint, or the `st` / `store` / `useClient` barrels. `common/` and `*.constant.ts` obey both.
|
|
108
|
-
`import type` is legal everywhere; a mixed value-and-type import is not.
|
|
109
|
-
- **Server-component discipline** on `page/**`, `*.Unit.tsx`, `*.View.tsx` (`no-import-client-functions`,
|
|
110
|
-
`no-use-client-in-server`, `non-scalar-props-restricted`).
|
|
111
|
-
- **No async component under `ui/`** — React has no async client component. Await in the page, or hand an
|
|
112
|
-
unawaited `fetch.*` field to a `Zone` / `<Load.Stream of={…}>`, and take the data as a prop. An async handler in a
|
|
113
|
-
synchronous component and `lazy(async () => import(…))` are untouched.
|
|
114
|
-
- **Never call `fetch.init<Model><Suffix>` / `fetch.get<Model>Init<Suffix>` from a client file** (`"use client"` or
|
|
115
|
-
`*.store.ts`) — it is the hydration snapshot. Load it in the page and pass `init` down; reload with
|
|
116
|
-
`st.do.init<Model><Suffix>()`.
|
|
117
|
-
- `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose — `key={idx}` for embedded scalars and
|
|
118
|
-
short dependency arrays are intentional.
|
|
119
|
-
- **Suppress a grit diagnostic as `lint/plugin`** (`// biome-ignore lint/plugin: <reason>`,
|
|
120
|
-
`// biome-ignore-all lint/plugin: <reason>`); bare `plugin:` does nothing. `pkgs/` is out of scope.
|
|
121
|
-
- **`biome.json` is strict JSON** — a comment breaks config resolution without an error (Biome falls back to
|
|
122
|
-
discovery and aborts on a nested config); rename it `biome.jsonc` to document a disabled rule.
|
|
123
|
-
- **`akan lint` prints up to 200 diagnostics** (`--max-diagnostics <n>`, `0` = all); Biome's own uncounted 20 reads
|
|
124
|
-
as progress when the mix merely changed.
|
|
125
|
-
- **Size, store reach, where writes start, and per-item calls fail `akan lint`** for an app or lib, each failure
|
|
126
|
-
naming its rule and the `akan workflow plan …` path that fixes it:
|
|
127
|
-
- `akan.size.file`: a `Zone` / `Util` / `Template` / `Unit` / `View`, a `*.store.ts`, or a `ui/` / `webkit/` file
|
|
128
|
-
over 400 lines; a service or document over 500; an abstract over 300. `akan.size.component`: a component or hook
|
|
129
|
-
over 250. `akan.component.store-access`: a component or hook reaching `st` more than 16 times (form setters aside).
|
|
130
|
-
- `akan.write.placement`: a server write leaves the browser only through a store action, started by a module
|
|
131
|
-
component — no `fetch.<mutation>` outside a `*.store.ts`, and no writing `st.do.*` in `ui/` or `webkit/`, which
|
|
132
|
-
take the write as an `onX` prop or hook argument.
|
|
133
|
-
- `akan.store.multi-write`, `akan.store.root-write-chain`, `akan.component.write-chain`: a store action, a store
|
|
134
|
-
`static`, or one handler (a hook's included) sending two or more writes — directly, through a sibling action,
|
|
135
|
-
through another store via `RootStore`, or once per item in a loop or `map`. Make them one service method
|
|
136
|
-
(`this.transaction(fn)`, a side effect in `this.afterCommit(fn)`) behind one endpoint, taking the list, that the
|
|
137
|
-
action calls once.
|
|
138
|
-
- `akan.service.call-in-loop`: a service method an `endpoint` or `slice` reaches calling a service, a model or a
|
|
139
|
-
generated query once per item (`for … of`, `map`, `forEach`); load the set once (`load<Model>Many`, one
|
|
140
|
-
filter query) or write it once. An `internal` job and a counted loop (a retry, paging) are spared.
|
|
141
|
-
- `akan.baseline.json` records, per rule, the debt adopted with the gate, and is compared with its copy at the
|
|
142
|
-
fork point of the default branch, so it only ever shrinks: never add or raise an entry. A size, store-reach or
|
|
143
|
-
per-item entry with a `reasons` line is an exception a person decided on, never an agent; the write rules take
|
|
144
|
-
no exceptions.
|
|
145
|
-
|
|
146
|
-
## Coding Style (`**/*.{ts,tsx}`)
|
|
147
|
-
|
|
148
|
-
- Run a large unit of work through a class instance; prefer class or `static` methods over unrelated top-level
|
|
149
|
-
helpers, and keep a class file's functions and variables inside the class when they reasonably can be.
|
|
150
|
-
- `#private` over TypeScript `private`, except in the four lint-banned suffixes, which use `private`.
|
|
151
|
-
- `const` function expressions over `function` declarations, unless hoisting, overloads, generators, or a framework
|
|
152
|
-
convention make `function` the better fit.
|
|
153
|
-
- One class per file, named after it (`RouteClientBuilder.ts`, not `buildRouteClient.ts`). Migrate callers off an
|
|
154
|
-
exported function that only instantiates a class and calls one method.
|
|
155
|
-
- TypeScript filenames are camelCase, except React component and convention files.
|
|
156
|
-
- One-off `className` strings stay inline; extract a constant only when reused, conditionally composed, or too large
|
|
157
|
-
to read in JSX.
|
|
158
|
-
|
|
159
|
-
### File Size And Duplication
|
|
160
|
-
|
|
161
|
-
- Keep files small (house median well under 50 lines); split a component before ~150 lines rather than adding
|
|
162
|
-
section comments.
|
|
163
|
-
- Ship every scaffold file even when empty — `export class XInternal extends internal(srv.x, () => ({})) {}`, empty
|
|
164
|
-
dictionary stages, the `// state` / `// action` markers. They mark where things go.
|
|
165
|
-
- Never add a sibling helper file inside `lib/<model>/`; helpers go to `common/`, `webkit/`, `srvkit/`, or `ui/`.
|
|
166
|
-
- Prefer duplication to premature abstraction at the leaf: near-identical sibling modules and per-vendor pages are
|
|
167
|
-
copied with changed literals, not parameterised; share enums by import only.
|
|
168
|
-
|
|
169
|
-
### TypeScript Shape
|
|
170
|
-
|
|
171
|
-
- `interface` for object shapes, `type` only for unions and aliases.
|
|
172
|
-
- `interface <ComponentName>Props` sits directly above the component (no blank line), `className?: string` first,
|
|
173
|
-
named for the component (`CardProps`), never the model; exported only when a sibling imports it.
|
|
174
|
-
- No non-null assertions — narrow with `?.`, an early return, or a type predicate
|
|
175
|
-
(`.filter((id): id is string => !!id)`). Escape with `as unknown as T`, never `as any`.
|
|
176
|
-
- Never annotate a component's return type; annotate a helper only for a union, tuple, or type predicate.
|
|
177
|
-
- `as const` on every `enumOf(...)` array (even though `enumOf` infers its literals, so a typo already fails to
|
|
178
|
-
compile), `via(Model, [...] as const, …)` Light tuple, and module-scope lookup map; never the `enum` keyword.
|
|
179
|
-
- Async functions carry no `Async` suffix.
|
|
180
|
-
|
|
181
|
-
### Test Code
|
|
182
|
-
|
|
183
|
-
- Bun's runner (`describe`, `expect`, `test` from `bun:test`); colocated `*.test.ts` / `*.spec.ts`; focused behavior
|
|
184
|
-
tests of public contracts and edge cases. A placeholder `it` with a descriptive title is the floor; a
|
|
185
|
-
security-relevant behaviour gets a real suite.
|
|
186
|
-
- Run `bun run akan test <pkg> [files]` from the root (`files`: comma-separated paths from the target or the root;
|
|
187
|
-
the only way a signal test runs), or `cd <pkg> && bun test --isolate ./<file>`. Plain `bun test` shares one global
|
|
188
|
-
object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not honored as
|
|
189
|
-
of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
|
|
190
|
-
- Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
|
|
191
|
-
`Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
|
|
192
|
-
describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
|
|
193
|
-
`await expect(p).rejects.toThrow()`. Each `fetch.clone()` reports its own address (`198.18.x.y`), so an `ip` rate
|
|
194
|
-
limit counts it apart: clone once per simulated user, signup included (`clone({ clientIp })` names one).
|
|
195
|
-
- **One suite per module file**: `<model>.<role>.test.ts` beside the file it covers — never topic splits
|
|
196
|
-
(`chatMessage.trim.signal.test.ts`); add a `describe`. A suite spanning modules goes in `srvkit/`
|
|
197
|
-
(`libs/shared/srvkit/guards.signal.test.ts`), never the `lib/` root; `akan sync` refuses all three shapes. Only
|
|
198
|
-
`akan typecheck <app-or-lib>` typechecks tests (`bun:test` types included) and the `script/` files nothing imports.
|
|
199
|
-
- Delete an export only tests reference together with its test (`akan quality scan` reports
|
|
200
|
-
`akan.global.test-only-export` in an app's `common/`, `webkit/`, `srvkit/`, `ui/`).
|
|
201
|
-
- Import `UserAgent` / `AdminAgent` from `lib/user/user.signal.spec.ts`, the one place agent types are re-typed.
|
|
202
|
-
|
|
203
|
-
## Comments
|
|
204
|
-
|
|
205
|
-
Do not narrate code. Do document the thing the code cannot say. Both halves are the rule.
|
|
206
|
-
|
|
207
|
-
- Never restate the identifier, the signature, or the control flow; prefer names and structure. No JSDoc, section
|
|
208
|
-
banners, or "why/how" comments on ordinary logic.
|
|
209
|
-
- Density tracks the layer: pages carry none, product `lib/` and `ui/` stay under 1 %, `srvkit/` adapters and
|
|
210
|
-
`guards.ts` (what would leak without each guard) carry what the external constraints require. `akan quality scan`
|
|
211
|
-
reports a `lib/` module or `ui/` entry past 1 % once it holds five comment lines (`akan.comment.density`).
|
|
212
|
-
- Mark a retired field or function `/** @deprecated <what to use instead> */` on its declaration, never a
|
|
213
|
-
`// deprecated` comment — only the tag strikes through every use site.
|
|
214
|
-
- Warranted for: a vendor or protocol quirk; an infrastructure constraint; a library gotcha; security reasoning; why
|
|
215
|
-
an arbitrary-looking rule is correct; a math derivation; a domain field's business meaning; a state transition above
|
|
216
|
-
a document chain method; why an obvious alternative was rejected.
|
|
217
|
-
- Markers: `TODO` (tracked unfinished work), `FIXME` (known broken), `XXX` (a hazard a reader must not miss), `//!`
|
|
218
|
-
(disabled or must-fix — server, `srvkit/`, CLI only), `//?` (an aside), `//*` (a design note), and a deletion
|
|
219
|
-
caution saying why removing a line would break something non-obvious.
|
|
220
|
-
- One short line each. Every suppression carries a reason (`// biome-ignore lint/<rule>: <why>`), never a bare
|
|
221
|
-
disable block. Match the nearby density.
|
|
222
|
-
|
|
223
|
-
## TypeScript And Imports (`**/*.{ts,tsx}`)
|
|
224
|
-
|
|
225
|
-
- Bun and ESM per the root `tsconfig.json`. Path aliases across packages: `akanjs/*`, `@apps/*`, `@libs/*`,
|
|
226
|
-
`@contract/*`, respecting the `/client` and `/server` entrypoints. Let Biome organize imports.
|
|
227
|
-
- Backend `.ts` namespaces the generated barrels — `import * as cnst from "../cnst"`, `* as db`, `* as srv` —
|
|
228
|
-
with `import type * as srv` in services (keeps the runtime graph lazy) and a value import in signals.
|
|
229
|
-
- `.tsx` uses one flat named import from the package client path
|
|
230
|
-
(`import { cnst, fetch, st, Ticket, usePage } from "@apps/<app>/client"`), never a relative `../` import.
|
|
231
|
-
|
|
232
|
-
## Formatting And Linting
|
|
233
|
-
|
|
234
|
-
- Biome formats and lints: `bun run akan lint <appName>` from the root; 2-space indent, 120 columns, double quotes.
|
|
235
|
-
No broad formatting-only changes in unrelated files.
|
|
236
|
-
|
|
237
|
-
## Client / Server Boundaries (`apps/**`, `libs/**`, `pkgs/akanjs/**`)
|
|
238
|
-
|
|
239
|
-
- `"use client";` tops client component files. It is mechanical by role: `Template`, `Zone`, `Util` always carry it
|
|
240
|
-
on line 1; `Unit`, `View` never do. `usePage()` is legal in server files.
|
|
241
|
-
- A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never `export *` — the server knows a
|
|
242
|
-
client module only by the names it spells out, so `akan start` / `akan build` stop on a star re-export.
|
|
243
|
-
- Keep page props serializable unless the route pattern clearly allows otherwise; be careful importing client-only
|
|
244
|
-
code into pages and layouts. Preserve file roles (`.document.ts`, `.service.ts`, `.store.ts`, `.constant.ts`,
|
|
245
|
-
`.client.ts`), and inspect nearby files before introducing a new boundary pattern.
|
|
246
|
-
|
|
247
|
-
## SSR First — Server Rendering Is The Default
|
|
248
|
-
|
|
249
|
-
Server-rendered JSX ships as HTML and costs nothing to hydrate; `"use client"` ships it twice (markup plus JS that
|
|
250
|
-
re-runs). **The default is server; the directive is a cost justified per component** by a React hook, a JSX event
|
|
251
|
-
handler, the store, a browser global, or a client-only package — never by markup, params, `l()` or mapping data.
|
|
252
|
-
`akan quality ssr` (`--format json`) prints each app's and lib's server share: **50% is the floor, and a falling
|
|
253
|
-
share is a regression** to justify in the PR or revert. A client package or an `index_.tsx` `lazy()` boundary
|
|
254
|
-
justifies the directive; a `fetch.*` inside `onClick` is not flagged, only mount-time loads.
|
|
255
|
-
|
|
256
|
-
Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction and render `children` untouched;
|
|
257
|
-
② split compound components (`Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`) — never one client file with a mode
|
|
258
|
-
`useState` and every panel inlined; ③ fetch in the route and pass `init` / `view` to a `Zone`, never a
|
|
259
|
-
`useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
|
|
260
|
-
promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
|
|
261
|
-
`<Load.Stream>` (model instances, server-only) — and `await` only what the shell must contain; ⑥ named `ReactNode`
|
|
262
|
-
slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ `.guard(() => signedIn())`
|
|
263
|
-
(`@libs/shared/webkit`) on `_layout.tsx` (a real 3xx before anything renders; `getSelf({ unauthorize })` in a body
|
|
264
|
-
redirects in-page after I/O); ⑨ CSS (`data-*` + `group-data-[…]`, `<details>`) over client state for visibility;
|
|
265
|
-
⑩ heavy islands behind `index_.tsx` + `lazy()`.
|
|
266
|
-
|
|
267
|
-
## Runtime & Build Configuration
|
|
268
|
-
|
|
269
|
-
Declared in `akan.config.ts`, narrowed — never widened — by an env at boot; domain code reaches none of it
|
|
270
|
-
(`runtimeRule`).
|
|
271
|
-
|
|
272
|
-
- **`web: true | false | { csr: boolean }`** — `{ csr: false }` drops the CSR bundle native apps ship, `false` is
|
|
273
|
-
API-only.
|
|
274
|
-
- **Route prefixes move together**: `new AkanApp({ prefix, websocketPrefix })` in `main.ts`, mirrored in
|
|
275
|
-
`api: { … }` in `akan.config.ts` for a CSR shell or native bundle. Read them with `getApiPrefix()` /
|
|
276
|
-
`getWsPrefix()` (`akanjs/base`); never write `/api` or `/ws`, never pass one as a prop.
|
|
277
|
-
- **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`**, not the barrel.
|
|
278
|
-
- Give every log sink a floor (`Logger.addSink(sink, { minLevel })`), never log per delivered record in anything
|
|
279
|
-
that delivers records, and tail with `akan logs <app>`.
|
|
280
|
-
- **`docker` is `string | { image, preRuns, postRuns, command }`**; the generated image installs only
|
|
281
|
-
`ca-certificates` and `tzdata`.
|
|
282
|
-
- **Native apps are the `native` section** (iOS, Android, desktop). A desktop app's carried server listens on a
|
|
283
|
-
loopback port any local program can call — guard it as a network server — and ships `private/` and its env
|
|
284
|
-
readable on the user's computer; read runtime files from `AKAN_APP_DIR`, and keep a secret the user gives it with
|
|
285
|
-
`NativeSecret` (the OS credential store), never in a file.
|
|
286
|
-
- **`database: { modes: [...] }`** (`single`, `multiple`, `cluster`), chosen by `AKAN_DATABASE_MODE`; an app running
|
|
287
|
-
in two modes avoids `q.raw`.
|
|
288
|
-
|
|
289
|
-
## React Components And Styling (`**/*.tsx`)
|
|
290
|
-
|
|
291
|
-
A screen that grows keeps five roles: an **assembly** `Zone` that reads the store and places pieces, with no
|
|
292
|
-
branching; **pieces** (`Unit`, `View`, small components) that only display, server-rendered where they can be; a
|
|
293
|
-
**kind table** `{ [kind in cnst.X["value"]]: Component }` instead of mode flags, so a new enum value without an entry
|
|
294
|
-
is a type error — each entry is a component of the module that owns that kind's data (a tab of video scenes is
|
|
295
|
-
`VideoScene.Zone.<X>`), so a screen spanning several models adds no folder; an **interaction hook**
|
|
296
|
-
`webkit/use<X>.tsx` over a pure, tested `common/<x>.ts` class for drag, selection and keys, handed its writes as
|
|
297
|
-
arguments; and **writes** as one-line store actions, one endpoint each. Kinds a screen invents rather than a model
|
|
298
|
-
(canvas node kinds) key the table by an `as const` union in `common/`. A screen choosing along two axes (what to
|
|
299
|
-
pick, and where the pick lands) keeps two tables, the second mapping each purpose to its one commit action. State
|
|
300
|
-
several components or an agent tool read stays in the store, where `st.tool` sees it; the hook keeps only gesture
|
|
301
|
-
state. Reach for the path, not the nearest file:
|
|
302
|
-
|
|
303
|
-
| Task | Path |
|
|
304
|
-
|---|---|
|
|
305
|
-
| 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>]` |
|
|
306
|
-
| Event, keyboard, pointer or layout logic growing in a component | `akan workflow plan create-interaction --app <app> --interaction <name>` |
|
|
307
|
-
| A missing `View` / `Unit` / `Template` / `Zone` / `Util` | `akan workflow plan create-ui --app <app> --module <m> --surface <surface>` |
|
|
308
|
-
|
|
309
|
-
- `export const X = ({ … }: XProps) => { return (…); };` — `export default` only for pages, layouts, `lazy()`
|
|
310
|
-
targets. No `React.FC`, `defaultProps`, `PropsWithChildren`; defaults in the destructuring, `children: ReactNode`.
|
|
311
|
-
- `cond ? <X/> : null`, never `{cond && <X/>}` (renders `"false"` in a `className`); early `return null` only for
|
|
312
|
-
guard clauses.
|
|
313
|
-
- Never hand-roll loading, empty, or list states: `Load.Units` / `Load.View` / `Load.Edit` (`renderItem`,
|
|
314
|
-
`renderList`, `renderView`, `renderEmpty`), `<Empty />`, `Model.New` / `Model.Edit` / `Model.SureToRemove`.
|
|
315
|
-
Otherwise `<Load.Stream of={promise} fallback={…}>{(value) => …}</Load.Stream>` awaits one promise behind its own
|
|
316
|
-
boundary (a resolved value renders in the shell).
|
|
317
|
-
- Avoid hooks. `useState` only for modal-open, tab, draft-input, and drag state, never server data; `useEffect` only
|
|
318
|
-
for a genuine effect (subscribe-with-cleanup, one-shot init); `Tab` over a mode switch; zero `useState` in a
|
|
319
|
-
`.Template.tsx`.
|
|
320
|
-
- Forms are store-driven: `value={xForm.field}`, `onChange={st.do.setFieldOnX}` **by reference** — that emits the
|
|
321
|
-
`data-akan-action` / `data-akan-state` the in-page agent, E2E selectors and browser agents read. Always `Field.*`,
|
|
322
|
-
never a bare `<input>` for a model field; nested rows use `st.do.writeOnX("payments.3.name", v)` and the generated
|
|
323
|
-
`add<Field>OnX` / `sub<Field>OnX`. Never hand-write `data-akan-*`.
|
|
324
|
-
- Read with `st.use.*`, write with `st.do.*`; client components never call `fetch.*`.
|
|
325
|
-
- A raw `<button>` defaults to `type="submit"`, so a click inside any `<form>` also submits it. Write
|
|
326
|
-
`type="button"` on every raw `<button>` that does not submit; `<Button>` from `akanjs/ui` already defaults to it.
|
|
327
|
-
- **Never persist form values yourself** — `Load.Edit`, `Model.EditModal` and `Model.New` save and recover the whole
|
|
328
|
-
`<model>Form` per record or route and user (`draft={false}` off, `draft="<scope>"` to name it; secret and hidden
|
|
329
|
-
values never saved; field `cache` / `cacheKey` props are deprecated no-ops — `modelStore`).
|
|
330
|
-
- Static class strings stay plain. `cn` (from `akanjs/client`) only for a conditional or to merge an incoming
|
|
331
|
-
`className`, caller last: `cn("base", cond && "extra", className)` — the only combiner: no `clsx`, raw `twMerge`,
|
|
332
|
-
or object syntax.
|
|
333
|
-
- Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
|
|
334
|
-
- Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
|
|
335
|
-
`Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
|
|
336
|
-
name map (`BadgeVariants["variant"]`) moves to `webkit/`.
|
|
337
|
-
- `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links. A `<Link>` handed
|
|
338
|
-
an absolute URL (any scheme, any case) or a `//host` path passes it through untouched and opens it outside the app;
|
|
339
|
-
only an app path gets the locale and basePath. `Href.isExternal(href)` from `akanjs/client` is that test.
|
|
340
|
-
|
|
341
|
-
## Naming And Language
|
|
342
|
-
|
|
343
|
-
- Component exports are role names (`Card`, `General`, `Preview`, `Admin`, `Remove`) — the namespace carries the
|
|
344
|
-
model (`<Floor.Unit.Card>`, never `FloorCard`). `Util` exports are the endpoint verb minus the noun (`Serve`,
|
|
345
|
-
`Refund`).
|
|
346
|
-
- Layer the verbs: the document chain method drops the model (`sign()`), the service keeps the bare verb, signal,
|
|
347
|
-
store and dictionary re-add it (`signScContract`) — clear of generated CRUD, and `st.do.X` reads like `fetch.X`.
|
|
348
|
-
- Slice and filter names are prepositional (`inOrg`, `byStatuses`, `ofPortfolio`), never `getXInY` or `listX`.
|
|
349
|
-
- Handlers are `onX` props taking inline arrows, never an extracted `handleX`.
|
|
350
|
-
- Booleans `is*` / `has*` / `can*` / `show*` / `disable*`; counters `*Num`; indices `idx`; collections `*List` or
|
|
351
|
-
plural; no `SCREAMING_SNAKE` — module-scope tables are camelCase + `as const`.
|
|
352
|
-
- Keep existing domain vocabulary and its typos — transliterated terms and misspellings in use are load-bearing, and
|
|
353
|
-
renaming silently breaks callers that match on the name.
|
|
354
|
-
- Identifiers, type names, endpoint names, and log messages are **English**. Everything a user reads goes through
|
|
355
|
-
`l("model.field")` or `l.trans({ en, ko })` — never a hard-coded JSX string, never `window.alert`.
|
|
356
|
-
- Dictionary entries are `[en, ko]` pairs, nearly every label with a `.desc([en, ko])` even when repetitive; English
|
|
357
|
-
in Title Case, Korean the plain domain term, `.error()` Korean ending in `다.`.
|
|
358
|
-
|
|
359
|
-
## Domain Module Conventions (`apps/**/lib/**`, `libs/**/lib/**`)
|
|
360
|
-
|
|
361
|
-
A business concept is one `lib/` folder holding its logic files
|
|
362
|
-
(`<model>.constant|dictionary|document|service|signal|store.ts`) and components
|
|
363
|
-
(`<Model>.Template|Unit|View|Zone|Util.tsx`). `constant`, `dictionary` and
|
|
364
|
-
`signal` are shared contracts with no platform-specific dependency; persistence and queries live in `document`,
|
|
365
|
-
orchestration in `service`, client state in `store`; `Template` is forms, `Unit` list/card items, `View` details,
|
|
366
|
-
`Zone` page sections, `Util` domain UI helpers.
|
|
367
|
-
|
|
368
|
-
- **`<model>.constant.ts`** — `enumOf("camelName", [...] as const)` classes, then
|
|
369
|
-
`XInput → XObject → LightX → X → XInsight`, one blank line apart, `XInsight` even when empty. **Display and
|
|
370
|
-
predicate logic goes on `LightX`** (`isNew()`, `canWrite(user?)`), which server and client both hold, never a util
|
|
371
|
-
module — the most commonly missed rule. Collection helpers are `static` on `X`; a non-obvious field gets a short
|
|
372
|
-
trailing comment. `Date` fields are prototype accessors that a spread drops — copy with `new cnst.X().set(user)`
|
|
373
|
-
(`fieldRule`).
|
|
374
|
-
- **`<model>.document.ts`** — `XFilter extends from(...)` → `X extends by(...)` → `XModel extends into(...)`,
|
|
375
|
-
`sort: {}` always present. Chain methods validate → mutate → `return this`, never `save()` (the caller saves, so
|
|
376
|
-
`org.removeUser(id).removeInvite(id).save()` composes), with a one-line transition comment above each. Atomic
|
|
377
|
-
counters live on the Model class with the updater callback, returning `!!modifiedCount`; indexes and derived
|
|
378
|
-
totals go in `static override _onSchema`. **Removal is soft** and reads see live rows unless
|
|
379
|
-
`{ withRemoved: true }`; the one hard delete is `purge<Filter>` / `purgeMany`, for data past retention.
|
|
380
|
-
`updateById` / `removeById` fire no hooks — a cascading or `_postRemove` model removes through
|
|
381
|
-
`remove<Model>(id)`, and `pickAndWrite` writes through the save hooks (`queryRule`).
|
|
382
|
-
- **`<model>.service.ts`** — a few lines: load → chain → `return await ….save()` (keep the `return await`). Side
|
|
383
|
-
effects go in `override async _preUpdate` / `_postCreate`; fire-and-forget is `void`-ed. Load every referenced
|
|
384
|
-
document, then save, then notify; writes that must land together go in `this.transaction(async () => …)` and
|
|
385
|
-
their notification in `this.afterCommit(…)` (`queryRule`). Return `null` / `false` for not allowed or not found;
|
|
386
|
-
the signal decides whether that is an error.
|
|
387
|
-
- **`<model>.signal.ts`** — `XInternal` → `XSlice` → `XEndpoint`, all three even when empty; `exec` is a one-liner
|
|
388
|
-
calling the service.
|
|
389
|
-
- **`<model>.store.ts`** — custom actions only for a toast, an optimistic update, or a multi-field write:
|
|
390
|
-
`await fetch.X` → `this.setX(...)` → toast, or mutate the client model, `void fetch.*`, then commit.
|
|
391
|
-
`this.pick(...)` when the value must exist, `this.get()` when it may not, `this.set({...})` to write; lists through
|
|
392
|
-
the collection API (`xList.set(x).save()`), not spread. **Another store is reached through `this`**:
|
|
393
|
-
`import type { RootStore } from "../st"` (type-only — `st.ts` imports every store), then
|
|
394
|
-
`(this as unknown as RootStore).logout()` or `.set({ … })` / `.get()`; every store is mixed into one root at
|
|
395
|
-
runtime, so the cast only names what `this` already is.
|
|
396
|
-
- **`<model>.dictionary.ts`** — empty stages still written:
|
|
397
|
-
`.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`;
|
|
398
|
-
every `.arg()` named, framework `skip` / `limit` / `sort` included; `modelDictionary` / `scalarDictionary` /
|
|
399
|
-
`serviceDictionary` by module kind.
|
|
400
|
-
- **`<module>.abstract.md`** — a title, one sentence naming what the module owns, a `## Rules` list of two to five
|
|
401
|
-
invariants the code cannot show, an optional workflow chain (`draft -> signed -> active`). Never restate fields or
|
|
402
|
-
types; update it when an invariant or workflow changes.
|
|
403
|
-
|
|
404
|
-
## Service And Signal Conventions (`*.{service,signal}.ts`, `server/**`)
|
|
405
|
-
|
|
406
|
-
- `serve(...)` services hold business operations. Signals hold contracts: `internal(...)` for init, interval, cron
|
|
407
|
-
and queue jobs (retries, dead letter: `workspaceRecipes` Recipe 5), `slice(...)` for focused data views feeding
|
|
408
|
-
stores and zones, `endpoint(...)` for queries and mutations. External APIs and infrastructure go through
|
|
409
|
-
`srvkit/` adapters injected into services, never vendor clients in domain logic.
|
|
410
|
-
|
|
411
|
-
### Authorization
|
|
412
|
-
|
|
413
|
-
- **Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.**
|
|
414
|
-
`guards: { cru: false }` (or per verb) takes a generated verb off HTTP; `mcp: { cru: false }` only keeps it off the
|
|
415
|
-
agent shelf.
|
|
416
|
-
- **Every custom `mutation` / `query` / `message` names its own `guards: [...]`** — the slice map reaches only
|
|
417
|
-
generated endpoints, and a `pubsub` / `message` without its own is unguarded. `Public` belongs on a slice `get:`;
|
|
418
|
-
on a mutation only for an act that must work signed out (sign-up/in, token refresh, an OAuth route), which also
|
|
419
|
-
declares a `rateLimit`. A guardless endpoint is warned at boot and never published to MCP, which also refuses a
|
|
420
|
-
mutation guarded only by `Public`.
|
|
421
|
-
- Guards serve HTTP and websocket alike: read `context.get<T>("account")`, never `getHttpContext()` /
|
|
422
|
-
`getWebSocketContext()`; keep them side-effect free and re-runnable. The acting user comes from `.with(Self)` /
|
|
423
|
-
`.with(CurrentUserId)` / `.with(Me)` (never a client-supplied id) and the caller's address from `.with(Ip)`.
|
|
424
|
-
- Keep `static name = "User";` on guard classes — `fetch` serializes it and the API explorer filters on it. It looks
|
|
425
|
-
dead, so comment it.
|
|
426
|
-
- **Every guard declares `static scope: GuardScope`, no default**: `"account"` reads only the caller (MCP listings
|
|
427
|
-
evaluate it to hide entries), `"resource"` needs the call's arguments and fails closed without them. `SignedIn` /
|
|
428
|
-
`Admin` / roles are `"account"`, every `Can<Verb><Model>` is `"resource"`; `Person` adds `static agents = false`.
|
|
429
|
-
- `Can<Verb><Model>` guards in `srvkit/guards.ts` fail closed and ship with the model's library (`transportRule`).
|
|
430
|
-
Services re-check ownership behind a guard — two independent gates.
|
|
431
|
-
|
|
432
|
-
### Calls, Queries, Agents (summaries)
|
|
433
|
-
|
|
434
|
-
- **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
|
|
435
|
-
30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
|
|
436
|
-
dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
|
|
437
|
-
`option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not a caller. A
|
|
438
|
-
device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
|
|
439
|
-
without `connect: true`, retries through `retry`, and rethrows a remote `Err` as is — never wrapped or re-keyed.
|
|
440
|
-
- **Body types**: `.body()` / `.param()` take scalars, model refs, or `enumOf(...)`; `Int` / `Float`, never
|
|
441
|
-
`Number` (`pkgs/akanjs/signal/endpointInfo.ts`); `Upload` only in a `fileUpload: true` mutation; bytes are
|
|
442
|
-
`Binary`, never `Any`. A model or scalar argument is checked against the request schema on every transport: a
|
|
443
|
-
wrong JSON type, a value outside its enum or a missing required field answers 400 with `data.name` naming the
|
|
444
|
-
path (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's
|
|
445
|
-
input keeps an absent field absent.
|
|
446
|
-
- **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
|
|
447
|
-
whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
|
|
448
|
-
name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
|
|
449
|
-
- **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
|
|
450
|
-
`query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
|
|
451
|
-
A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
|
|
452
|
-
only way to read a `field.secret`. More rows: `loadMoreOf<Model>()` / `hasMoreOf<Model>`, never
|
|
453
|
-
`count > page * limit`. A filter's `remove*` / `update*` are hookless (no cascade). No value is `q.empty`, never
|
|
454
|
-
`q.missing`.
|
|
455
|
-
- **Search**: `q.search(text, { prefix: true })` in a filter, at an AND position, over `text`-role fields; a search
|
|
456
|
-
*slice* only on data safe to enumerate; blank input matches nothing — never a passthrough.
|
|
457
|
-
- **`cascade` names a direction; the wrong one loses data**: `removeRef` on the owner's relation, `removeWith` on
|
|
458
|
-
the child's reference to its owner. A query-level removal runs no cascade.
|
|
459
|
-
- **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
|
|
460
|
-
mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
|
|
461
|
-
`.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
|
|
462
|
-
required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
|
|
463
|
-
screen with `page().prompt(name, description)`, and publish one component a host draws with
|
|
464
|
-
`page().app(name, description, load)` — a read-only tool whose `load` may only query.
|
|
465
|
-
- **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
|
|
466
|
-
every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
|
|
467
|
-
`option.setAgentRequestPolicy`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
|
|
468
|
-
The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
|
|
469
|
-
`st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
|
|
470
|
-
`visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
|
|
471
|
-
`<Agent.Guide instructions="…" />`; model-facing text is English.
|
|
472
|
-
|
|
473
|
-
### Injection And Adapters
|
|
474
|
-
|
|
475
|
-
- A field named `<refName>Service` / `<refName>Signal` resolves to that registration — the suffix is required
|
|
476
|
-
(`pkgs/akanjs/service/injectInfo.ts`). In a service: `service<srv.XService>()` · `plug(AdapterClass)` /
|
|
477
|
-
`plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
|
|
478
|
-
- `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
|
|
479
|
-
`String` memory.
|
|
480
|
-
- A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
|
|
481
|
-
`storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
|
|
482
|
-
`readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
|
|
483
|
-
`access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
|
|
484
|
-
- **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
|
|
485
|
-
register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
|
|
486
|
-
lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy
|
|
487
|
-
`constructor(options)` adapters migrate only when already being changed. Example and adapter conventions (one
|
|
488
|
-
`#api<T>` with a timeout, pagination, secrets, parameter shapes): `workspaceRecipes` Recipe 2.
|
|
489
|
-
|
|
490
|
-
### Error Placement
|
|
491
|
-
|
|
492
|
-
- State-machine preconditions throw in `document.ts`, cross-document rules in `service.ts`, request policy in
|
|
493
|
-
`signal.ts` guards. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no Result types.
|
|
494
|
-
- A `pick` or generated `get<Model>` that finds no live row answers 404 `base.error.documentNotFound` by itself
|
|
495
|
-
(`NoDocumentError`); load with a nullable `load<Model>` and throw `Err.NotFound` only to say more than that.
|
|
496
|
-
- An endpoint names the errors it throws on purpose — `errors: { 409: ["ticket.error.locked"] }` in its signal
|
|
497
|
-
option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
|
|
498
|
-
of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
|
|
499
|
-
`Err.is(error, "ticket.error.locked")`.
|
|
500
|
-
- `try/catch` turns an exception into a decision: guards → `logger.warn` → `false`; adapters → `logger.error` →
|
|
501
|
-
`null`; UI `try/finally` resets a spinner. A bodyless `catch {}` needs a one-line reason.
|
|
502
|
-
- Store actions do not `try/catch` (the framework toasts the `Err`); client validation is `msg.error("<key>")` plus
|
|
503
|
-
an early return, never a throw.
|
|
504
|
-
|
|
505
|
-
## Scalar Modeling (`**/*.constant.ts`)
|
|
506
|
-
|
|
507
|
-
- Models use `via` from `akanjs/constant`, all five layers (`Input`, `Object`, `Light<Model>`, `<Model>`,
|
|
508
|
-
`<Model>Insight`). `Int` for counts, `Float` only for decimals, `ID` for references; structured fields over `Any`.
|
|
509
|
-
- Import `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `ImageResult`, `enumOf`, `dayjs` from `akanjs/base`;
|
|
510
|
-
`String` / `Boolean` / `Date` are globals. No `JSON` scalar (use `Any`), no `Number`, and `Binary` / `Upload` are
|
|
511
|
-
never fields — a file is `field(File).optional()` / `field([File])`, uploaded by the generated
|
|
512
|
-
`upload<Field>On<Model>` (which `Field.Img` / `Files` and siblings use when handed the generated setter); it marks
|
|
513
|
-
the field in `<model>FormUploading` while the request runs and drops a result whose form was set whole meanwhile
|
|
514
|
-
(or, on a single field, re-picked) — gate a hand-written submit on it.
|
|
515
|
-
- Defaults: a literal for scalars, a thunk for anything constructed (`default: () => dayjs()`). Arrays
|
|
516
|
-
`field([T])`; optional `.optional()`.
|
|
517
|
-
- **`field.hidden` / `field.secret` read `null` on the client while the type declares them** — guard with `??` or
|
|
518
|
-
`== null`, never `=== undefined` or a default. `field.visual(T)` is rendered but stripped from every agent and MCP
|
|
519
|
-
read. Full contract: `fieldRule`.
|
|
520
|
-
|
|
521
|
-
## Akan Page Routing (`apps/**/page/**`)
|
|
522
|
-
|
|
523
|
-
Full contract — guards, apps, heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
|
|
524
|
-
|
|
525
|
-
- `page/` holds `.tsx` route modules only: `<routeName>.tsx` or `_index.tsx`, `_layout.tsx`, `_overrides.tsx` — no
|
|
526
|
-
other `_*.tsx`, helpers, `.ts` / `.js` files, or uppercase filenames. `[id]` is a dynamic segment, `(group)` a
|
|
527
|
-
route group.
|
|
528
|
-
- **A route file exports one chain** — `page()`, `layout()` in a `_layout.tsx`, `rootLayout()` in a root
|
|
529
|
-
`_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
|
|
530
|
-
`.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
|
|
531
|
-
A named export beside it fails the build.
|
|
532
|
-
- **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`; values
|
|
533
|
-
arrive typed. `lang` is never declared — every stage receives it.
|
|
534
|
-
- `.head()` takes JSX or a function returning it — never a metadata object; deeper heads replace by tag identity,
|
|
535
|
-
and a canonical link / `og:url` comes only from the page's own `.head()`.
|
|
536
|
-
- In a CSR bundle a root layout's own markup is hidden: what a person must see from it renders through
|
|
537
|
-
`createPortal(…, document.body)`.
|
|
538
|
-
- `_overrides.tsx` is one `export default override({ Slot: AppComponent })` (`akanjs/ui`), no logic, no
|
|
539
|
-
`"use client"`. The legacy `export default async function Page` shape is never written anew.
|
|
540
|
-
- `libs/<lib>/page` reaches an app through `syncPageLibs`, linked into the generated `page/(libs)/(<lib>)`; edit the
|
|
541
|
-
lib source, never the link. `.config({ devOnly: true })` (a literal) keeps a route out of `akan build`.
|
|
542
|
-
|
|
543
|
-
```tsx
|
|
544
|
-
export default page()
|
|
545
|
-
.param("orgId", ID)
|
|
546
|
-
.config({ transition: "stack" })
|
|
547
|
-
.guard(() => signedIn())
|
|
548
|
-
.render(({ orgId }) => {
|
|
549
|
-
const { l } = usePage();
|
|
550
|
-
const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
|
|
551
|
-
return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
|
|
552
|
-
});
|
|
553
|
-
```
|
|
554
|
-
|
|
555
|
-
- `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
|
|
556
|
-
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
|
|
557
|
-
(title, redirect, link id) in one `Promise.all`.
|
|
558
|
-
- **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it renders throws
|
|
559
|
-
`base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
|
|
560
|
-
`{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
|
|
561
|
-
- Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`; a new workspace has that lib only with
|
|
562
|
-
`create-workspace --libs true`) at `_layout.tsx`, and repeat it on a page that needs more; it is a courtesy, the
|
|
563
|
-
endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits;
|
|
564
|
-
the callback is not a React component, so it takes no name and no return type. No `useState`, `useEffect`, or
|
|
565
|
-
comments in page files.
|
|
566
|
-
|
|
567
|
-
## Akan Sync Conventions (`apps/**`, `libs/**`)
|
|
568
|
-
|
|
569
|
-
- App root files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.baseline.json`, `akan.config.ts`, `client.ts`,
|
|
570
|
-
`main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`; folders: `.akan`, `common`, `env`,
|
|
571
|
-
`lib`, `native`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`. A Capacitor-era
|
|
572
|
-
`ios` / `android` / `mobile` folder or `capacitor.config.*` in an app root is refused as a leftover (native
|
|
573
|
-
projects live under `dist/native/<app>/<target>`).
|
|
574
|
-
- Lib root files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `akan.baseline.json`, `akan.config.ts`, `akan.lib.json`,
|
|
575
|
-
`client.ts`, `index.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.spec.json`, `tsconfig.tsbuildinfo`;
|
|
576
|
-
folders: the app's minus `.akan`, `script`, `secrets` (no `main.ts` either — a lib is never booted).
|
|
577
|
-
- The allowlists' one source is `pkgs/@akanjs/devkit/workspaceLayout.ts`, read by `akan sync` (error), `akan doctor`
|
|
578
|
-
and `akan quality scan` — add an entry there and mirror it here.
|
|
579
|
-
- `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` carry a generated `## Recipes In Scope` block between the
|
|
580
|
-
`akan:agent` markers — never hand-edit it (outside the markers is yours); `akan lint` fails when it is stale.
|
|
581
|
-
- `plugin/<name>.plugin.ts` declares an Akan plugin. No `apps/*/base` or `libs/*/base` — use `common/`.
|
|
582
|
-
- `lib/` root holds only `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`,
|
|
583
|
-
`useServer.ts` — no hand-written file or test.
|
|
584
|
-
- Modules are `lib/<model>`, `lib/_<service>`, `lib/__scalar/<scalar>`; their UI files are
|
|
585
|
-
`<Model>.Template|Unit|Util|View|Zone.tsx`, `<Service>.Util|Zone.tsx`, `<Scalar>.Template|Unit.tsx`. A test is
|
|
586
|
-
named after the one file it covers, so `<model>.<topic>.signal.test.ts` is refused like `<model>.<topic>.signal.ts`.
|
|
587
|
-
- `ui/`, `webkit/`, `srvkit/`, `common/`, `plugin/` and module `index.ts` barrels are generated
|
|
588
|
-
(`export * from "./name";` per 1-depth entry, `export {};` when empty, so a stale one heals on sync;
|
|
589
|
-
`akan create-library` starts `common/`, `srvkit/`, `webkit/`, `ui/` with that empty barrel) — never hand-edit or
|
|
590
|
-
track them. **Never hand-write an
|
|
591
|
-
`index.tsx` / `.jsx` / `.mts` at those roots**: Bun resolves it before the generated `index.ts`, so new exports are
|
|
592
|
-
`undefined` at runtime (`akan sync` refuses it, `akan doctor` reports `facet-index-shadowed`); a namespace belongs
|
|
593
|
-
in `ui/<Folder>/index.tsx`.
|
|
594
|
-
- Sync writes barrels, module indexes and `akan.*.json` exactly as Biome prints them (`akan lint --no-fix` passes
|
|
595
|
-
right after a sync), so a lint diff in one is a generator bug — fix the generator.
|
|
596
|
-
- **`akan sync` owns package.json `dependencies`**: it adds imports at the root's version, realigns root-declared
|
|
597
|
-
entries, and drops unimported ones (logged); undeclared-at-root entries are kept with a warning. Keep a package no
|
|
598
|
-
TS file imports (a CSS `@plugin`, a runtime-only package) with `akan.keepDependencies`; `externalLibs` and
|
|
599
|
-
`trustedDependencies` always stay; devDependencies are realigned, never pruned. `akan install-library` lets the
|
|
600
|
-
root win — it adds only what the root lacks and warns when the lib wants a newer version.
|
|
601
|
-
|
|
602
|
-
## Layer Placement (`common/`, `webkit/`, `srvkit/`, `ui/`)
|
|
603
|
-
|
|
604
|
-
| Folder | Admission test | Naming |
|
|
605
|
-
|---|---|---|
|
|
606
|
-
| `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 |
|
|
607
|
-
| `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 |
|
|
608
|
-
| `srvkit/` | touches `node:*`, `Bun`, `process.env`, a secret, or a server SDK | camelCase file, PascalCase class |
|
|
609
|
-
| `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` |
|
|
610
|
-
| `plugin/` | a build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
|
|
611
|
-
| `native/` | a native plugin the app or lib owns — its page API reached only through a `webkit/` hook (`runtimeRule`) | `native/<id>/` |
|
|
612
|
-
|
|
613
|
-
- Hooks return a named object of async closures, never a tuple.
|
|
614
|
-
- Recipes live in `ui/`: `webkit/` hooks are `"use client"`, and `common/` cannot import `akanjs/ui`.
|
|
615
|
-
- A layer-root `index.ts` is generated; a `ui/<Folder>/index.tsx` building a namespace is hand-written (a generated
|
|
616
|
-
barrel holds only `export *` lines). `ui/<Folder>/index_.tsx` is the `"use client"` + `lazy()` boundary beside a
|
|
617
|
-
server-safe `index.tsx` — merging the pair breaks RSC.
|
|
618
|
-
|
|
619
|
-
## Data Migrations (`apps/*/script/migration/**`)
|
|
620
|
-
|
|
621
|
-
A change that reshapes stored documents ships a migration: `akan create-migration <name> <app>` writes
|
|
622
|
-
`script/migration/<yyyyMMddHHmm>_<name>.ts`, a default-exported `migration(title)` from `akanjs/server`, which
|
|
623
|
-
`akan migrate <app>` runs locally and `bun main.js ops migrate` in a built container (the `cheatsheet/dev/migration`
|
|
624
|
-
docs page).
|
|
625
|
-
|
|
626
|
-
- The new code reads both shapes until every environment has applied it — a deploy serves traffic first.
|
|
627
|
-
- Write only through `table(refName)`, never a service, a document or raw `sql` — a service write runs the model's
|
|
628
|
-
hooks, and none of them reaches the change log a rollback reverts. Call nothing outside the database.
|
|
629
|
-
- `plan` reads only and must hash the same on unchanged data: a timestamp, `createId()` or random value in it makes
|
|
630
|
-
every `apply --expect <planHash>` refuse as `planChanged`.
|
|
631
|
-
- Past about five seconds on SQLite, an apply's one transaction makes the live server's writes fail. Take
|
|
632
|
-
`.config({ transaction: false })`, which commits each `rewrite` batch and resumes a `partial` run from the top of
|
|
633
|
-
`apply` — so a second run must change nothing (a `where` the new shape no longer matches).
|
|
634
|
-
- `$ne` leaves out rows whose path is missing or `null` (match them with `{ path: null }`; `$exists: false` misses a
|
|
635
|
-
stored `null`); `find`, `count` and `rewrite` include removed rows unless `{ withRemoved: false }`; a `table()` write
|
|
636
|
-
leaves `updatedAt` alone.
|
|
637
|
-
- Throw a plain `Error` an operator can act on. Never edit a migration an environment has applied — write another;
|
|
638
|
-
delete it once every environment has, unless its `.rollback(fn)` may still be needed: without the file a rollback
|
|
639
|
-
runs the default undo.
|
|
640
|
-
|
|
641
|
-
## Present In The Code — Do Not Imitate
|
|
642
|
-
|
|
643
|
-
Warts in older files — never copy them; when two shapes disagree, follow the newer neighbour: `children: any`
|
|
644
|
-
(use `ReactNode`); hard-coded API keys or secrets (they belong in `option.ts` or env); large commented-out blocks;
|
|
645
|
-
stale `// TODO: Implement …` above implemented methods; `{cond && <X/>}`, hard-coded Korean bypassing `l()`,
|
|
646
|
-
`window.alert(...)`; bare `/* eslint-disable */` blocks; raw palette grays like `text-gray-400`. A store reaching
|
|
647
|
-
another through `(this as unknown as RootStore)` is **not** a wart — it is the sanctioned way.
|
|
648
|
-
|
|
649
|
-
## Secrets And Env Safety (`.env`, `infra/**`, `*secret*`, `*credential*`)
|
|
650
|
-
|
|
651
|
-
- Never print, summarize, commit, or expose real secret values, credentials, tokens, private keys, or `.env`
|
|
652
|
-
contents; document env keys by name with placeholders only.
|
|
653
|
-
- Preserve the env/secret flow through `bun run downloadEnv`, `uploadEnv`, `downloadSecret`, `uploadSecret`, and
|
|
654
|
-
keep Jenkins and deployment assumptions intact unless the task asks otherwise.
|
|
655
|
-
- Treat generated env/secret artifacts as sensitive even when they are not named `.env`.
|
|
656
|
-
|
|
657
|
-
## Application Test Commands
|
|
658
|
-
|
|
659
|
-
- After changing application code, run `bun run akan start <appName>` (`a,b`, `a b`, or `all` for several); check
|
|
660
|
-
the production build with `bun run akan build <appName>`.
|
|
661
|
-
- A supervised session writes `local/apps/<app>/runtime/dev.log` (previous: `dev.prev.log`) — hand over that path,
|
|
662
|
-
not a paste of the repainting full-screen view. Keys, `--plain`, boot waves, `--kill`, watch scope, running a
|
|
663
|
-
built artifact, booting a server in a test: `runtimeRule`.
|