@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.
- package/.build-stamp +1 -1
- package/CodeAgent-dyc45f5w.js +11 -0
- package/{CodeAgentRpcHost-9g27hmer.js → CodeAgentRpcHost-6dzfkvsc.js} +1 -1
- package/CodeAgentRpcListener-tcwrdvst.js +182 -0
- package/{CodeTui-z5vkm9ea.js → CodeTui-q55b2zrn.js} +25 -8
- package/TunnelShare-hdq9h1hr.js +14 -0
- package/agent.command-20zaqe60.js +49 -0
- package/akanCode.js +13 -8
- package/{application.command-wthg8nn9.js → application.command-nd0fshsk.js} +45 -12
- package/{applicationBuildRunner-t2r84sz6.js → applicationBuildRunner-s13x3zqb.js} +14 -10
- package/buildBatch.proc.js +7 -7
- package/{cloud.command-sz11hpre.js → cloud.command-8kbddsz9.js} +28 -19
- package/cloud.script-hgvvajm3.js +27 -0
- package/code.command-625bg8s8.js +345 -0
- package/commandManifest.json +1 -1
- package/{context.command-15j9b7c0.js → context.command-p6haqjay.js} +20 -18
- package/context.runner-rsnqnk9j.js +27 -0
- package/{dependencyScanner-3afj2vt1.js → dependencyScanner-78sq8m4q.js} +2 -2
- package/{devTui-q7k7bakd.js → devTui-evr3b35y.js} +1 -1
- package/{fileSys-wzzrntkw.js → fileSys-zpvt5gtf.js} +1 -1
- package/{guideline.command-snh85ctf.js → guideline.command-195g0h9a.js} +4 -4
- package/guidelines/agentRule/agentRule.instruction.md +22 -8
- package/guidelines/conventions/core.md +106 -0
- package/guidelines/conventions/rules/app.md +83 -0
- package/guidelines/conventions/rules/auth.md +46 -0
- package/guidelines/conventions/rules/config.md +60 -0
- package/guidelines/conventions/rules/constant.md +24 -0
- package/guidelines/conventions/rules/gates.md +32 -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 +91 -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 +76 -0
- package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
- package/guidelines/pageRule/pageRule.instruction.md +8 -7
- package/guidelines/queryRule/queryRule.instruction.md +4 -0
- package/guidelines/runtimeRule/runtimeRule.instruction.md +35 -25
- package/guidelines/ssrRule/ssrRule.instruction.md +11 -10
- package/guidelines/transportRule/transportRule.instruction.md +5 -4
- package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +4 -4
- package/incrementalBuilder.proc.js +7 -7
- package/{index-301pdbzz.js → index-00a7j05x.js} +7 -7
- package/{index-js6geqjn.js → index-0j1t1h2b.js} +3 -1
- package/{index-6txx6a9p.js → index-1h2jc0x3.js} +154 -88
- package/{index-55j120r8.js → index-1qsd8ft1.js} +65 -145
- package/{index-9th4gszy.js → index-2mwjshz5.js} +233 -1271
- package/index-2nxk8wgs.js +266 -0
- package/{index-j9vyj3dj.js → index-2phm56a1.js} +49 -8
- package/index-35j83zkd.js +61 -0
- package/index-4am4dvmf.js +29 -0
- package/index-75y7bcz4.js +28 -0
- package/index-7apsdr5g.js +487 -0
- package/{index-42j4a8zq.js → index-84h43kg6.js} +8 -6
- package/index-9bv479q5.js +1 -0
- package/{index-3wypz6xj.js → index-9zy8479y.js} +11 -5
- package/{index-a5dhqkdr.js → index-a1vb3x7t.js} +273 -259
- package/{index-52w0fvh8.js → index-bns3wcpc.js} +15 -0
- package/index-cjmjvg4r.js +3622 -0
- package/{index-pcwzkdqb.js → index-defp4gmb.js} +1 -1
- package/index-ewbmfarf.js +1606 -0
- package/index-fbewhg4g.js +590 -0
- package/index-fhw7yq2d.js +653 -0
- package/{index-wcej7g4z.js → index-g500c5j9.js} +271 -105
- package/{index-74tjjsnc.js → index-g841cap9.js} +33 -37
- package/{index-2azahjaw.js → index-gr9thy79.js} +5 -5
- package/{index-4pf8g7ff.js → index-h7hehkw6.js} +3 -0
- package/{index-xjf5j657.js → index-hm0tn7qv.js} +1001 -91
- package/index-j6eeh5d7.js +138 -0
- package/{index-31es1yev.js → index-j7hwy56s.js} +108 -7
- package/{index-skk9zc1x.js → index-jc2zbwra.js} +2 -2
- package/{index-905qdgqp.js → index-khk05tsf.js} +1 -1
- package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
- package/{index-tvehn2sp.js → index-qd7xn2bk.js} +1 -1
- package/{index-a58emady.js → index-qw6814m4.js} +55 -17
- package/index-raz588b3.js +445 -0
- package/{index-at7bz0xq.js → index-s4nvxpzm.js} +2 -0
- package/{index-bt438yxm.js → index-sp0qsr7a.js} +116 -13
- package/{index-xb8809yb.js → index-sveq36gh.js} +40 -43
- package/{index-hmt54t45.js → index-t1t9wq9a.js} +4 -4
- package/index-t78230d7.js +191 -0
- package/index-tenw3mah.js +225 -0
- package/{index-qfp55x1y.js → index-tgqameyb.js} +4 -4
- package/{index-espk51ah.js → index-tp56652m.js} +6 -6
- package/index-w15mg3km.js +389 -0
- package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
- package/{index-2xcc2ax5.js → index-y4kcmbt2.js} +2 -2
- package/index-yf9wc28h.js +52 -0
- package/{index-0fz95kxe.js → index-zbrwnmf1.js} +9 -7
- package/{index-40brg4px.js → index-zttm13c3.js} +5 -5
- package/index.js +24 -23
- package/{library.command-gycrwhf1.js → library.command-63hgt9te.js} +4 -4
- package/{localRegistry.command-jtd8gaes.js → localRegistry.command-g3f8k25t.js} +46 -22
- package/{module.command-v6hgs1bc.js → module.command-r4sa2khp.js} +7 -6
- package/{package.command-shzpcfph.js → package.command-96eheyvd.js} +5 -5
- package/package.json +2 -2
- package/{page.command-ptxn5kqk.js → page.command-gs6d841d.js} +4 -4
- package/{pipeline.command-zz31pgax.js → pipeline.command-wdfvdbfj.js} +3 -3
- package/{primitive.command-a1vse91z.js → primitive.command-dfsv4mpe.js} +8 -7
- package/{projectTypecheck-2ztky9cf.js → projectTypecheck-kqj1t6hb.js} +1 -1
- package/{prompter-76k56b37.js → prompter-qrwx1p17.js} +2 -2
- package/quality.command-webzxee2.js +78 -0
- package/{repair.command-cvazbz99.js → repair.command-3r3j1xre.js} +7 -6
- package/{routeSourceValidator-6jd0q6r6.js → routeSourceValidator-4h947v7c.js} +13 -3
- package/{scalar.command-0acvyp26.js → scalar.command-e8y47j6d.js} +6 -5
- package/skills/akan-agent/SKILL.md +43 -0
- package/skills/akan-code/SKILL.md +38 -11
- package/skills/akan-debug/SKILL.md +41 -6
- package/skills/akan-deps/SKILL.md +1 -2
- package/skills/akan-err/SKILL.md +2 -1
- package/skills/akan-mcp/SKILL.md +40 -0
- package/skills/akan-page/SKILL.md +44 -0
- package/skills/akan-query/SKILL.md +39 -0
- package/skills/akan-runtime/SKILL.md +43 -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-822qx2bx.js → subspace.command-a1sf9n5a.js} +12 -10
- package/templates/__scalar/__model__/__model__.constant.ts +3 -5
- package/templates/__scalar/__model__/__model__.dictionary.ts +6 -5
- package/templates/__scalar/__model__/__model__.document.ts +3 -3
- package/templates/app/akan.config.ts +2 -3
- package/templates/app/env/env.client.ts +2 -4
- package/templates/app/env/env.client.type.ts +2 -3
- package/templates/app/env/env.server.ts +2 -3
- package/templates/app/lib/___appName__/__appName__.dictionary.ts +1 -2
- package/templates/app/lib/___appName__/__appName__.service.ts +3 -3
- package/templates/app/lib/___appName__/__appName__.signal.ts +5 -5
- package/templates/app/lib/___appName__/__appName__.store.ts +4 -6
- package/templates/app/lib/option.ts +2 -3
- package/templates/app/main.ts +2 -4
- package/templates/app/page/_index.tsx +3 -3
- package/templates/app/page/_layout.tsx +13 -10
- package/templates/appSample/lib/__scalar/workHistory/workHistory.constant.ts +1 -5
- package/templates/appSample/lib/__scalar/workHistory/workHistory.dictionary.ts +1 -1
- package/templates/appSample/lib/_noti/noti.signal.ts +1 -1
- package/templates/appSample/lib/task/Task.Template.tsx +2 -1
- package/templates/appSample/lib/task/Task.Unit.tsx +3 -2
- package/templates/appSample/lib/task/Task.Util.tsx +16 -4
- package/templates/appSample/lib/task/task.constant.ts +1 -5
- package/templates/appSample/lib/task/task.dictionary.ts +2 -8
- package/templates/appSample/lib/task/task.document.ts +1 -1
- package/templates/appSample/lib/task/task.signal.ts +14 -9
- package/templates/appSample/page/task/_index.tsx +2 -1
- package/templates/appSample/page/task/new.tsx +2 -1
- package/templates/appSample/srvkit/guards.ts +11 -0
- package/templates/appSample/ui/QuantityControl.tsx +5 -9
- package/templates/biomeForm.ts +144 -0
- package/templates/crudPages/[__model__Id]/edit/page.tsx +3 -3
- package/templates/crudPages/[__model__Id]/page.tsx +5 -5
- package/templates/crudPages/new/page.tsx +4 -3
- package/templates/crudPages/page.tsx +3 -3
- package/templates/crudSinglePage/page.tsx +9 -5
- package/templates/libRoot/akan.config.ts +2 -3
- package/templates/libRoot/lib/___libName__/__libName__.dictionary.ts +1 -2
- package/templates/libRoot/lib/___libName__/__libName__.service.ts +5 -4
- package/templates/libRoot/lib/___libName__/__libName__.signal.ts +6 -5
- package/templates/libRoot/lib/___libName__/__libName__.store.ts +5 -6
- package/templates/libRoot/lib/option.ts +1 -2
- package/templates/module/__Model__.Template.tsx +11 -10
- package/templates/module/__Model__.Unit.tsx +18 -5
- package/templates/module/__Model__.Util.tsx +9 -7
- package/templates/module/__Model__.View.tsx +9 -6
- package/templates/module/__Model__.Zone.tsx +25 -17
- package/templates/module/__model__.constant.ts +8 -9
- package/templates/module/__model__.dictionary.ts +16 -17
- package/templates/module/__model__.document.ts +6 -8
- package/templates/module/__model__.service.ts +3 -3
- package/templates/module/__model__.signal.ts +11 -10
- package/templates/module/__model__.store.ts +3 -5
- package/templates/service/__model__.dictionary.ts +5 -6
- package/templates/service/__model__.service.ts +3 -3
- package/templates/service/__model__.signal.ts +5 -4
- package/templates/service/__model__.store.ts +3 -5
- package/templates/workspaceRoot/.gitignore.template +4 -0
- package/templates/workspaceRoot/.vscode/settings.json.template +21 -21
- package/templates/workspaceRoot/AGENTS.md.template +4 -10
- package/{tunnel.command-ycmja19q.js → tunnel.command-dcb0wg93.js} +25 -13
- package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
- package/typecheck.proc.js +6 -1
- package/verify.command-yyepccbh.js +93 -0
- package/{workflow.command-abb1d5xy.js → workflow.command-z5pg9ay0.js} +49 -14
- package/workspace.command-d7x5jttw.js +290 -0
- package/CodeAgent-8d5qs787.js +0 -9
- package/CodeAgentRpcListener-7p7z5dd7.js +0 -97
- package/TunnelShare-qkm8zp03.js +0 -14
- package/agent.command-ydftceda.js +0 -25
- package/cloud.script-nqevg5qw.js +0 -24
- package/code.command-9h3yrzhe.js +0 -167
- package/context.runner-8gg030b0.js +0 -25
- package/guidelines/conventions/conventions.instruction.md +0 -617
- package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
- package/index-2mwc0g0d.js +0 -49
- package/index-4vgbysa0.js +0 -279
- package/index-7md2g9vw.js +0 -6
- package/index-b70zct19.js +0 -856
- package/index-c6eggbee.js +0 -123
- package/index-zzvvc845.js +0 -74
- package/quality.command-ah8qcakd.js +0 -1478
- package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
- package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
- package/workspace.command-qm7cw29v.js +0 -521
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Services, signals, documents and srvkit adapters: calls, queries, injection and where errors are thrown.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.{service,signal,document}.ts"
|
|
5
|
+
- "{apps,libs}/**/srvkit/**"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Services And Signals
|
|
9
|
+
|
|
10
|
+
- `serve(...)` services hold business operations. Signals hold contracts: `internal(...)` for init, interval, cron
|
|
11
|
+
and queue jobs (retries, dead letter: `workspaceRecipes` Recipe 5), `slice(...)` for focused data views feeding
|
|
12
|
+
stores and zones, `endpoint(...)` for queries and mutations. External APIs and infrastructure go through
|
|
13
|
+
`srvkit/` adapters injected into services, never vendor clients in domain logic.
|
|
14
|
+
|
|
15
|
+
## Calls, Queries, Agents
|
|
16
|
+
|
|
17
|
+
- **Guards (`transportRule`)**: an endpoint, a named slice's `init()` or a root slice that declares no guards is
|
|
18
|
+
refused with 403 on every transport, and outside local operation the server does not boot with one. Name its
|
|
19
|
+
guards, or `[Public]` to open it on purpose; `AKAN_UNGUARDED_ENDPOINTS=open` is a deployment's stopgap, never the
|
|
20
|
+
fix.
|
|
21
|
+
- **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
|
|
22
|
+
30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
|
|
23
|
+
dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
|
|
24
|
+
`option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not a caller. A
|
|
25
|
+
device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
|
|
26
|
+
without `connect: true`, retries through `retry`, and rethrows a remote `Err` as is — never wrapped or re-keyed.
|
|
27
|
+
- **Body types**: `.body()` / `.param()` take scalars, model refs, or `enumOf(...)`; `Int` / `Float`, never
|
|
28
|
+
`Number` (`pkgs/akanjs/signal/endpointInfo.ts`); `Upload` only in a `fileUpload: true` mutation; bytes are
|
|
29
|
+
`Binary`, never `Any`. A model or scalar argument is checked against the request schema on every transport: a
|
|
30
|
+
wrong JSON type, a value outside its enum or a missing required field answers 400 with `data.name` naming the
|
|
31
|
+
path (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's
|
|
32
|
+
input keeps an absent field absent.
|
|
33
|
+
- **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
|
|
34
|
+
whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
|
|
35
|
+
name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
|
|
36
|
+
- **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
|
|
37
|
+
`query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
|
|
38
|
+
A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
|
|
39
|
+
only way to read a `field.secret`. More rows: `loadMoreOf<Model>()` / `hasMoreOf<Model>`, never
|
|
40
|
+
`count > page * limit`. A filter's `remove*` / `update*` are hookless (no cascade). No value is `q.empty`, never
|
|
41
|
+
`q.missing`.
|
|
42
|
+
- **Search**: `q.search(text, { prefix: true })` in a filter, at an AND position, over `text`-role fields; a search
|
|
43
|
+
*slice* only on data safe to enumerate; blank input matches nothing — never a passthrough.
|
|
44
|
+
- **`cascade` names a direction; the wrong one loses data**: `removeRef` on the owner's relation, `removeWith` on
|
|
45
|
+
the child's reference to its owner. A query-level removal runs no cascade.
|
|
46
|
+
- **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
|
|
47
|
+
mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
|
|
48
|
+
`.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
|
|
49
|
+
required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
|
|
50
|
+
screen with `page().prompt(name, description)`, and publish one component a host draws with
|
|
51
|
+
`page().app(name, description, load)` — a read-only tool whose `load` may only query.
|
|
52
|
+
- **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
|
|
53
|
+
every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
|
|
54
|
+
`option.setAgentRequestPolicy`, size-capped until one is set; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
|
|
55
|
+
The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
|
|
56
|
+
`st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
|
|
57
|
+
`visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
|
|
58
|
+
`<Agent.Guide instructions="…" />`; model-facing text is English.
|
|
59
|
+
|
|
60
|
+
## Injection And Adapters
|
|
61
|
+
|
|
62
|
+
- A field named `<refName>Service` / `<refName>Signal` resolves to that registration — the suffix is required
|
|
63
|
+
(`pkgs/akanjs/service/injectInfo.ts`). In a service: `service<srv.XService>()` · `plug(AdapterClass)` /
|
|
64
|
+
`plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
|
|
65
|
+
- `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
|
|
66
|
+
`String` memory.
|
|
67
|
+
- A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
|
|
68
|
+
`storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
|
|
69
|
+
`readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
|
|
70
|
+
`access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
|
|
71
|
+
- **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
|
|
72
|
+
register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
|
|
73
|
+
lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy
|
|
74
|
+
`constructor(options)` adapters migrate only when already being changed. Example and adapter conventions (one
|
|
75
|
+
`#api<T>` with a timeout, pagination, secrets, parameter shapes): `workspaceRecipes` Recipe 2.
|
|
76
|
+
|
|
77
|
+
## Error Placement
|
|
78
|
+
|
|
79
|
+
- State-machine preconditions throw in `document.ts`, cross-document rules in `service.ts`, request policy in
|
|
80
|
+
`signal.ts` guards. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no Result types.
|
|
81
|
+
- A `pick` or generated `get<Model>` that finds no live row answers 404 `base.error.documentNotFound` by itself
|
|
82
|
+
(`NoDocumentError`); load with a nullable `load<Model>` and throw `Err.NotFound` only to say more than that.
|
|
83
|
+
- An endpoint names the errors it throws on purpose — `errors: { 409: ["ticket.error.locked"] }` in its signal
|
|
84
|
+
option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
|
|
85
|
+
of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
|
|
86
|
+
`Err.is(error, "ticket.error.locked")`.
|
|
87
|
+
- `try/catch` turns an exception into a decision: guards → `logger.warn` → `false`; adapters → `logger.error` →
|
|
88
|
+
`null`; UI `try/finally` resets a spinner. A bodyless `catch {}` needs a one-line reason.
|
|
89
|
+
- Store actions do not `try/catch` (the framework toasts the `Err`); one no screen waits on (a token refresh) is
|
|
90
|
+
listed in the store's `static silent`, rejecting untoasted to the caller that handles it. Client validation is
|
|
91
|
+
`msg.error("<key>")` plus an early return, never a throw.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: The client/server boundary and SSR-first rendering for .tsx files and pages.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
- "{apps,libs}/**/page/**"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Client/Server Boundary And SSR
|
|
9
|
+
|
|
10
|
+
## Client / Server Boundaries
|
|
11
|
+
|
|
12
|
+
- `"use client";` tops client component files. It is mechanical by role: `Template`, `Zone`, `Util` always carry it
|
|
13
|
+
on line 1; `Unit`, `View` never do. `usePage()` is legal in server files.
|
|
14
|
+
- A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never `export *` — the server knows a
|
|
15
|
+
client module only by the names it spells out, so `akan start` / `akan build` stop on a star re-export.
|
|
16
|
+
- Keep page props serializable unless the route pattern clearly allows otherwise; be careful importing client-only
|
|
17
|
+
code into pages and layouts. Preserve file roles (`.document.ts`, `.service.ts`, `.store.ts`, `.constant.ts`,
|
|
18
|
+
`.client.ts`), and inspect nearby files before introducing a new boundary pattern.
|
|
19
|
+
|
|
20
|
+
- **Never import across the client/server boundary** (`apps/**`, `libs/**`; `no-import-server-in-client`,
|
|
21
|
+
`no-import-client-in-server`). Client files (`ui/`, `webkit/`, `page/`, `*.store.ts`, every `.tsx`) never import a
|
|
22
|
+
`*.document|dictionary|service|signal.ts`, `srvkit/`, a package `server` entrypoint, or the `db` / `srv` / `sig` /
|
|
23
|
+
`dict` / `option` / `useServer` barrels. Server files (those four suffixes, `srvkit/`) never import a `*.store.ts`, a
|
|
24
|
+
module component, `ui/`, `webkit/`, a package `client` entrypoint, or the `st` / `store` / `useClient` barrels.
|
|
25
|
+
`common/` and `*.constant.ts` obey both. `import type` is legal everywhere; a mixed value-and-type import is not.
|
|
26
|
+
- **Server-component discipline** on `page/**`, `*.Unit.tsx`, `*.View.tsx` (`no-import-client-functions`,
|
|
27
|
+
`no-use-client-in-server`, `non-scalar-props-restricted`).
|
|
28
|
+
|
|
29
|
+
## SSR First — Server Rendering Is The Default
|
|
30
|
+
|
|
31
|
+
Server-rendered JSX ships as HTML and costs nothing to hydrate; `"use client"` ships it twice (markup plus JS that
|
|
32
|
+
re-runs). **The default is server; the directive is a cost justified per component** by a React hook, a JSX event
|
|
33
|
+
handler, the store, a browser global, or a client-only package — never by markup, params, `l()` or mapping data.
|
|
34
|
+
`akan quality ssr` (`--format json`) prints each app's and lib's server share: **50% is the floor, and a falling
|
|
35
|
+
share is a regression** to justify in the PR or revert. A client package or an `index_.tsx` `lazy()` boundary
|
|
36
|
+
justifies the directive; a `fetch.*` inside `onClick` is not flagged, only mount-time loads.
|
|
37
|
+
|
|
38
|
+
Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction and render `children` untouched;
|
|
39
|
+
② split compound components (`Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`) — never one client file with a mode
|
|
40
|
+
`useState` and every panel inlined; ③ fetch in the route and pass `init` / `view` to a `Zone`, never a
|
|
41
|
+
`useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
|
|
42
|
+
promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
|
|
43
|
+
`<Load.Stream>` (model instances, server-only) — and `await` only what the shell must contain; ⑥ named `ReactNode`
|
|
44
|
+
slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ `.guard(() => signedIn())`
|
|
45
|
+
(`@libs/shared/webkit`) on `_layout.tsx` (a real 3xx before anything renders; `getSelf({ unauthorize })` in a body
|
|
46
|
+
under a `.loading()` redirects in-page after I/O); ⑨ CSS (`data-*` + `group-data-[…]`, `<details>`) over client
|
|
47
|
+
state for visibility; ⑩ heavy islands behind `index_.tsx` + `lazy()`.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Styling: Tailwind order, the semantic colour vocabulary, cn(), recipes and the app theme.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
- "{apps,libs}/**/*.css"
|
|
6
|
+
- "{apps,libs}/*/ui/Recipe/**"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Styling
|
|
10
|
+
|
|
11
|
+
- **Never hand-order Tailwind classes** — `nursery/useSortedClasses` sorts them, `cn()` arguments included, and its
|
|
12
|
+
output (`font-bold text-2xl text-foreground`) is correct.
|
|
13
|
+
- **Stay inside the color vocabulary** (`no-raw-palette-class`, `no-arbitrary-color`, `no-interpolated-arbitrary-class`,
|
|
14
|
+
`no-daisyui-legacy-class`, `no-inline-color`): no raw palette (`bg-blue-500`), arbitrary or interpolated color classes
|
|
15
|
+
(`bg-[#3b82f6]`), daisyUI classes or slots (`btn-primary`, `bg-base-100`), or color literals in `style={{}}` — they
|
|
16
|
+
render no CSS. Use semantic tokens (`bg-primary`, `text-foreground/70`); a legitimate fixed color takes
|
|
17
|
+
`// biome-ignore lint/plugin: <reason>`. Slot replacements, SVG / `el.style` warnings, legal values: `cssRule`.
|
|
18
|
+
|
|
19
|
+
- Static class strings stay plain. `cn` (from `akanjs/client`) only for a conditional or to merge an incoming
|
|
20
|
+
`className`, caller last: `cn("base", cond && "extra", className)` — the only combiner: no `clsx`, raw `twMerge`,
|
|
21
|
+
or object syntax.
|
|
22
|
+
- Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
|
|
23
|
+
- Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
|
|
24
|
+
`Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
|
|
25
|
+
name map (`BadgeVariants["variant"]`) moves to `webkit/`.
|
|
26
|
+
|
|
27
|
+
## Theme And Component Overrides
|
|
28
|
+
|
|
29
|
+
When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
|
|
30
|
+
|
|
31
|
+
- **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
|
|
32
|
+
- **Lib tokens (`libs/<lib>/ui/tokens.css`).** The one CSS file a lib owns: colors its own components pin that must **not** follow the theme — a vendor brand color, a fixed surface — declared once as plain `:root` custom properties and compiled automatically into every app whose pages reach the lib, ahead of the app's stylesheets, so nothing is imported by hand. Reference them as `bg-[var(--kakao)]`; never copy the block into each app. `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet, and theme-following colors are the app's.
|
|
33
|
+
- **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
|
|
34
|
+
|
|
35
|
+
## Recipes
|
|
36
|
+
|
|
37
|
+
Framework UI recipes (Tailwind-variant look factories) import from `akanjs/ui`: `<name>(variants?, className?)`.
|
|
38
|
+
The second argument merges internally and takes an array too, so never wrap it in `cn()`:
|
|
39
|
+
`<name>({}, ["h-full", isWide && "w-full", className])`. Do not guess a recipe name or variant value, and do not open
|
|
40
|
+
the recipe file to consume one. Before inlining a repeated surface (card, box, tile): reuse a recipe, or add one as
|
|
41
|
+
`apps/<app>/ui/Recipe/<name>.ts`, one per file, re-exported from that folder's `index.ts` — never a near-duplicate.
|
|
42
|
+
Each app and lib lists its own recipes in `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` (`## Recipes In Scope`),
|
|
43
|
+
regenerated by `akan sync`. Full policy: the `recipeRule` guideline.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Tests: Bun's runner, one suite per module file, the signal test split and how to run them.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.{test,spec}.ts"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Test Code
|
|
8
|
+
|
|
9
|
+
- Bun's runner (`describe`, `expect`, `test` from `bun:test`); colocated `*.test.ts` / `*.spec.ts`; focused behavior
|
|
10
|
+
tests of public contracts and edge cases. A placeholder `it` with a descriptive title is the floor; a
|
|
11
|
+
security-relevant behaviour gets a real suite.
|
|
12
|
+
- Run `bun run akan test <pkg> [files]` from the root (`files`: comma-separated paths from the target or the root;
|
|
13
|
+
the only way a signal test runs), or `cd <pkg> && bun test --isolate ./<file>`. Plain `bun test` shares one global
|
|
14
|
+
object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not honored as
|
|
15
|
+
of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
|
|
16
|
+
- Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
|
|
17
|
+
`Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
|
|
18
|
+
describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
|
|
19
|
+
`await expect(p).rejects.toThrow()`. Each `fetch.clone()` reports its own address (`198.18.x.y`), so an `ip` rate
|
|
20
|
+
limit counts it apart: clone once per simulated user, signup included (`clone({ clientIp })` names one).
|
|
21
|
+
- **One suite per module file**: `<model>.<role>.test.ts` beside the file it covers — never topic splits
|
|
22
|
+
(`chatMessage.trim.signal.test.ts`); add a `describe`. A suite spanning modules goes in `srvkit/`
|
|
23
|
+
(`libs/shared/srvkit/guards.signal.test.ts`), never the `lib/` root; `akan sync` refuses all three shapes. Only
|
|
24
|
+
`akan verify` and `akan typecheck <app-or-lib>` typecheck tests (`bun:test` types included) and the `script/`
|
|
25
|
+
files nothing imports.
|
|
26
|
+
- Delete an export only tests reference together with its test (`akan quality scan` reports
|
|
27
|
+
`akan.global.test-only-export` in an app's `common/`, `webkit/`, `srvkit/`, `ui/`).
|
|
28
|
+
- Import `UserAgent` / `AdminAgent` from `lib/user/user.signal.spec.ts`, the one place agent types are re-typed.
|
|
29
|
+
|
|
30
|
+
**Verify endpoints with signal tests, not raw HTTP.** The canonical way to check a query/mutation/slice
|
|
31
|
+
contract is an in-memory signal test (`<model>.signal.test.ts`), using the test fetch harness
|
|
32
|
+
(`getOrSetupSignalTestFetch`) — it is fast, needs no running server, and exercises `fetch.*`, `view/edit/merge<Model>`,
|
|
33
|
+
and slice `init`/`list`/`insight` directly. Prefer it over `curl`: the dev gateway locale-prefixes routes (`/en/...`),
|
|
34
|
+
so hand-rolled HTTP calls against a raw path can redirect unexpectedly. See `akan test <app>`.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: TypeScript house style: classes, naming, file size, type shape, imports, comments.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.{ts,tsx}"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# TypeScript Style
|
|
8
|
+
|
|
9
|
+
## Coding Style
|
|
10
|
+
|
|
11
|
+
- Run a large unit of work through a class instance; prefer class or `static` methods over unrelated top-level
|
|
12
|
+
helpers, and keep a class file's functions and variables inside the class when they reasonably can be.
|
|
13
|
+
- `#private` over TypeScript `private`, except in the four lint-banned suffixes, which use `private`.
|
|
14
|
+
- `const` function expressions over `function` declarations, unless hoisting, overloads, generators, or a framework
|
|
15
|
+
convention make `function` the better fit.
|
|
16
|
+
- One class per file, named after it (`RouteClientBuilder.ts`, not `buildRouteClient.ts`). Migrate callers off an
|
|
17
|
+
exported function that only instantiates a class and calls one method.
|
|
18
|
+
- TypeScript filenames are camelCase, except React component and convention files.
|
|
19
|
+
- One-off `className` strings stay inline; extract a constant only when reused, conditionally composed, or too large
|
|
20
|
+
to read in JSX.
|
|
21
|
+
|
|
22
|
+
### File Size And Duplication
|
|
23
|
+
|
|
24
|
+
- Keep files small (house median well under 50 lines); split a component before ~150 lines rather than adding
|
|
25
|
+
section comments.
|
|
26
|
+
- Ship every scaffold file even when empty — `export class XInternal extends internal(srv.x, () => ({})) {}`, empty
|
|
27
|
+
dictionary stages, the `// state` / `// action` markers. They mark where things go.
|
|
28
|
+
- Never add a sibling helper file inside `lib/<model>/`; helpers go to `common/`, `webkit/`, `srvkit/`, or `ui/`.
|
|
29
|
+
- Prefer duplication to premature abstraction at the leaf: near-identical sibling modules and per-vendor pages are
|
|
30
|
+
copied with changed literals, not parameterised; share enums by import only.
|
|
31
|
+
|
|
32
|
+
### TypeScript Shape
|
|
33
|
+
|
|
34
|
+
- `interface` for object shapes, `type` only for unions and aliases.
|
|
35
|
+
- `interface <ComponentName>Props` sits directly above the component (no blank line), `className?: string` first,
|
|
36
|
+
named for the component (`CardProps`), never the model; exported only when a sibling imports it.
|
|
37
|
+
- No non-null assertions — narrow with `?.`, an early return, or a type predicate
|
|
38
|
+
(`.filter((id): id is string => !!id)`). Escape with `as unknown as T`, never `as any`.
|
|
39
|
+
- Never annotate a component's return type; annotate a helper only for a union, tuple, or type predicate.
|
|
40
|
+
- `as const` on every `enumOf(...)` array (even though `enumOf` infers its literals, so a typo already fails to
|
|
41
|
+
compile), `via(Model, [...] as const, …)` Light tuple, and module-scope lookup map; never the `enum` keyword.
|
|
42
|
+
- Async functions carry no `Async` suffix.
|
|
43
|
+
|
|
44
|
+
- **`#private` is banned in exactly `*.constant.ts`, `*.document.ts`, `*.service.ts`, `*.store.ts`**
|
|
45
|
+
(`no-js-private-class-method`, by path, so it stays the house style everywhere else, `srvkit/` and `adapt()` classes
|
|
46
|
+
included).
|
|
47
|
+
|
|
48
|
+
## TypeScript And Imports
|
|
49
|
+
|
|
50
|
+
- Bun and ESM per the root `tsconfig.json`. Path aliases across packages: `akanjs/*`, `@apps/*`, `@libs/*`,
|
|
51
|
+
`@contract/*`, respecting the `/client` and `/server` entrypoints. Let Biome organize imports.
|
|
52
|
+
- Backend `.ts` namespaces the generated barrels — `import * as cnst from "../cnst"`, `* as db`, `* as srv` —
|
|
53
|
+
with `import type * as srv` in services (keeps the runtime graph lazy) and a value import in signals.
|
|
54
|
+
- `.tsx` uses one flat named import from the package client path
|
|
55
|
+
(`import { cnst, fetch, st, Ticket, usePage } from "@apps/<app>/client"`), never a relative `../` import.
|
|
56
|
+
|
|
57
|
+
- Biome formats: 2-space indent, 120 columns, double quotes.
|
|
58
|
+
|
|
59
|
+
## Naming And Language
|
|
60
|
+
|
|
61
|
+
- Component exports are role names (`Card`, `General`, `Preview`, `Admin`, `Remove`) — the namespace carries the
|
|
62
|
+
model (`<Floor.Unit.Card>`, never `FloorCard`). `Util` exports are the endpoint verb minus the noun (`Serve`,
|
|
63
|
+
`Refund`).
|
|
64
|
+
- Layer the verbs: the document chain method drops the model (`sign()`), the service keeps the bare verb, signal,
|
|
65
|
+
store and dictionary re-add it (`signScContract`) — clear of generated CRUD, and `st.do.X` reads like `fetch.X`.
|
|
66
|
+
- Slice and filter names are prepositional (`inOrg`, `byStatuses`, `ofPortfolio`), never `getXInY` or `listX`.
|
|
67
|
+
- Handlers are `onX` props taking inline arrows, never an extracted `handleX`.
|
|
68
|
+
- Booleans `is*` / `has*` / `can*` / `show*` / `disable*`; counters `*Num`; indices `idx`; collections `*List` or
|
|
69
|
+
plural; no `SCREAMING_SNAKE` — module-scope tables are camelCase + `as const`.
|
|
70
|
+
- Keep existing domain vocabulary and its typos — transliterated terms and misspellings in use are load-bearing, and
|
|
71
|
+
renaming silently breaks callers that match on the name.
|
|
72
|
+
- Identifiers, type names, endpoint names, and log messages are **English**. Everything a user reads goes through
|
|
73
|
+
`l("model.field")` or `l.trans({ en, ko })` — never a hard-coded JSX string, never `window.alert`.
|
|
74
|
+
- Dictionary entries are `[en, ko]` pairs, nearly every label with a `.desc([en, ko])` even when repetitive; English
|
|
75
|
+
in Title Case, Korean the plain domain term, `.error()` Korean ending in `다.`.
|
|
76
|
+
|
|
77
|
+
## Comments
|
|
78
|
+
|
|
79
|
+
Do not narrate code. Do document the thing the code cannot say. Both halves are the rule.
|
|
80
|
+
|
|
81
|
+
- Never restate the identifier, the signature, or the control flow; prefer names and structure. No JSDoc, section
|
|
82
|
+
banners, or "why/how" comments on ordinary logic.
|
|
83
|
+
- Density tracks the layer: pages carry none, product `lib/` and `ui/` stay under 1 %, `srvkit/` adapters and
|
|
84
|
+
`guards.ts` (what would leak without each guard) carry what the external constraints require. `akan quality scan`
|
|
85
|
+
reports a `lib/` module or `ui/` entry past 1 % once it holds five comment lines (`akan.comment.density`).
|
|
86
|
+
- Mark a retired field or function `/** @deprecated <what to use instead> */` on its declaration, never a
|
|
87
|
+
`// deprecated` comment — only the tag strikes through every use site.
|
|
88
|
+
- Warranted for: a vendor or protocol quirk; an infrastructure constraint; a library gotcha; security reasoning; why
|
|
89
|
+
an arbitrary-looking rule is correct; a math derivation; a domain field's business meaning; a state transition above
|
|
90
|
+
a document chain method; why an obvious alternative was rejected.
|
|
91
|
+
- Markers: `TODO` (tracked unfinished work), `FIXME` (known broken), `XXX` (a hazard a reader must not miss), `//!`
|
|
92
|
+
(disabled or must-fix — server, `srvkit/`, CLI only), `//?` (an aside), `//*` (a design note), and a deletion
|
|
93
|
+
caution saying why removing a line would break something non-obvious.
|
|
94
|
+
- One short line each. Every suppression carries a reason (`// biome-ignore lint/<rule>: <why>`), never a bare
|
|
95
|
+
disable block. Match the nearby density.
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: React components: the five roles, forms, loading states, hooks and the lint rules on .tsx files.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# React Components
|
|
8
|
+
|
|
9
|
+
A screen that grows keeps five roles: an **assembly** `Zone` that reads the store and places pieces, with no
|
|
10
|
+
branching; **pieces** (`Unit`, `View`, small components) that only display, server-rendered where they can be; a
|
|
11
|
+
**kind table** `{ [kind in cnst.X["value"]]: Component }` instead of mode flags, so a new enum value without an entry
|
|
12
|
+
is a type error — each entry is a component of the module that owns that kind's data (a tab of video scenes is
|
|
13
|
+
`VideoScene.Zone.<X>`), so a screen spanning several models adds no folder; an **interaction hook**
|
|
14
|
+
`webkit/use<X>.tsx` over a pure, tested `common/<x>.ts` class for drag, selection and keys, handed its writes as
|
|
15
|
+
arguments; and **writes** as one-line store actions, one endpoint each. Kinds a screen invents rather than a model
|
|
16
|
+
(canvas node kinds) key the table by an `as const` union in `common/`. A screen choosing along two axes (what to
|
|
17
|
+
pick, and where the pick lands) keeps two tables, the second mapping each purpose to its one commit action. State
|
|
18
|
+
several components or an agent tool read stays in the store, where `st.tool` sees it; the hook keeps only gesture
|
|
19
|
+
state. Reach for the path, not the nearest file:
|
|
20
|
+
|
|
21
|
+
| Task | Path |
|
|
22
|
+
|---|---|
|
|
23
|
+
| A state-changing act, or chained writes in an action or handler | `akan workflow plan add-mutation --app <app> --module <m> --mutation <verbModel> --guard <Guard>[,…] [--with <ref>.<method>] [--after <ref>.<method>]` |
|
|
24
|
+
| Event, keyboard, pointer or layout logic growing in a component | `akan workflow plan create-interaction --app <app> --interaction <name>` |
|
|
25
|
+
| A missing `View` / `Unit` / `Template` / `Zone` / `Util` | `akan workflow plan create-ui --app <app> --module <m> --surface <surface>` |
|
|
26
|
+
|
|
27
|
+
- `export const X = ({ … }: XProps) => { return (…); };` — `export default` only for pages, layouts, `lazy()`
|
|
28
|
+
targets. No `React.FC`, `defaultProps`, `PropsWithChildren`; defaults in the destructuring, `children: ReactNode`.
|
|
29
|
+
- `cond ? <X/> : null`, never `{cond && <X/>}` (renders `"false"` in a `className`); early `return null` only for
|
|
30
|
+
guard clauses.
|
|
31
|
+
- Never hand-roll loading, empty, or list states: `Load.Units` / `Load.View` / `Load.Edit` (`renderItem`,
|
|
32
|
+
`renderList`, `renderView`, `renderEmpty`), `<Empty />`, `Model.New` / `Model.Edit` / `Model.SureToRemove`.
|
|
33
|
+
Otherwise `<Load.Stream of={promise} fallback={…}>{(value) => …}</Load.Stream>` awaits one promise behind its own
|
|
34
|
+
boundary (a resolved value renders in the shell).
|
|
35
|
+
- Avoid hooks. `useState` only for modal-open, tab, draft-input, and drag state, never server data; `useEffect` only
|
|
36
|
+
for a genuine effect (subscribe-with-cleanup, one-shot init); `Tab` over a mode switch; zero `useState` in a
|
|
37
|
+
`.Template.tsx`.
|
|
38
|
+
- Forms are store-driven: `value={xForm.field}`, `onChange={st.do.setFieldOnX}` **by reference** — that emits the
|
|
39
|
+
`data-akan-action` / `data-akan-state` the in-page agent, E2E selectors and browser agents read. Always `Field.*`,
|
|
40
|
+
never a bare `<input>` for a model field; nested rows use `st.do.writeOnX("payments.3.name", v)` and the generated
|
|
41
|
+
`add<Field>OnX` / `sub<Field>OnX`. Never hand-write `data-akan-*`.
|
|
42
|
+
- Read with `st.use.*`, write with `st.do.*`; client components never call `fetch.*`.
|
|
43
|
+
- A raw `<button>` defaults to `type="submit"`, so a click inside any `<form>` also submits it. Write
|
|
44
|
+
`type="button"` on every raw `<button>` that does not submit; `<Button>` from `akanjs/ui` already defaults to it.
|
|
45
|
+
- **Never persist form values yourself** — `Load.Edit`, `Model.EditModal` and `Model.New` save and recover the whole
|
|
46
|
+
`<model>Form` per record or route and user (`draft={false}` off, `draft="<scope>"` to name it; secret and hidden
|
|
47
|
+
values never saved; field `cache` / `cacheKey` props are deprecated no-ops — `modelStore`).
|
|
48
|
+
- `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links. A `<Link>` handed
|
|
49
|
+
an absolute URL (any scheme, any case) or a `//host` path passes it through untouched and opens it outside the app;
|
|
50
|
+
only an app path gets the locale (none for the default locale under `i18n.localePrefix: "as-needed"`) and basePath.
|
|
51
|
+
`Href.isExternal(href)` from `akanjs/client` is that test.
|
|
52
|
+
|
|
53
|
+
## Lint Rules On Components
|
|
54
|
+
|
|
55
|
+
- **Never type a `*.Util.tsx` / `*.Zone.tsx` prop as a `cnst` model** (`no-model-type-in-util-zone`) — the server would
|
|
56
|
+
hand a class instance to a client component; take `bannerId: string` and read the model from the store. Exempt:
|
|
57
|
+
`cnst.<Enum>["value"]`, a `ClientInit` / `ClientView` / `ClientEdit` / `ModelsProps<…>` type argument, a
|
|
58
|
+
function-typed prop, a `cnst` type that never leaves the file; `ModelProps<…>` and other indexed accesses stay
|
|
59
|
+
flagged.
|
|
60
|
+
- **Never wrap a form setter in a pass-through arrow** (`no-unpublished-form-setter`) —
|
|
61
|
+
`(v) => st.do.setTypeOnTicket(v)` emits no `data-akan-action` and publishes no agent tool. A wrapper that transforms,
|
|
62
|
+
adds a statement, or calls `writeOnX` is legal; publish it with an explicit `st.tool`.
|
|
63
|
+
- **Never call a hook conditionally** — a skipped call shifts every later hook, and production React crashes
|
|
64
|
+
elsewhere. Biome's `useHookAtTopLevel` checks plain hooks (`useState`, `useEffect`), early returns included.
|
|
65
|
+
`no-conditional-st-hook` checks the `st` hooks it cannot see — `st.use.*`, `st.slice.<x>.use.*`, `st.sel`, `st.ref`,
|
|
66
|
+
`st.tool(…).exec()` / `.card()`, `st.useState(…).init()`, `st.expose(…).value()` — behind `||` / `&&` / `??`, in a
|
|
67
|
+
ternary, an `if`, a `switch`, a loop, a `catch`, a default value, an optional call or a callback; not after an early
|
|
68
|
+
`return` or inside a helper the component calls. Read each into its own `const` at the top, then combine.
|
|
69
|
+
- **No async component under `ui/`** (`no-async-component-in-ui`) — React has no async client component. Await in the
|
|
70
|
+
page, or hand an unawaited `fetch.*` field to a `Zone` / `<Load.Stream of={…}>`, and take the data as a prop. An async
|
|
71
|
+
handler in a synchronous component and `lazy(async () => import(…))` are untouched.
|
|
72
|
+
- **Never call `fetch.init<Model><Suffix>` / `fetch.get<Model>Init<Suffix>` from a client file** (`"use client"` or
|
|
73
|
+
`*.store.ts`; `no-init-fetch-in-client`) — it is the hydration snapshot. Load it in the page and pass `init` down;
|
|
74
|
+
reload with `st.do.init<Model><Suffix>()`.
|
|
75
|
+
- `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose — `key={idx}` for embedded scalars and
|
|
76
|
+
short dependency arrays are intentional.
|
|
@@ -580,7 +580,7 @@ element, beside the tools it explains. Exactly these texts reach every client: `
|
|
|
580
580
|
|
|
581
581
|
## Verifying An App
|
|
582
582
|
|
|
583
|
-
- `akan
|
|
583
|
+
- `akan verify <app>`, then the boot log above.
|
|
584
584
|
- The lib's own suites run wherever it is mounted: the OAuth signal test (metadata, registration, both `authorize`
|
|
585
585
|
redirects, code exchange, `/mcp` with the minted token and the refusal of a first-party or forged one, refresh
|
|
586
586
|
rotation) and the refresh-session and option unit tests.
|
|
@@ -58,10 +58,10 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
58
58
|
(`.guard(() => signedIn())`), because `.guard(signedIn)` would hand the route's arguments to `unauthorize`.
|
|
59
59
|
- **On the server every guard of the chain runs before any layout body starts**, root layout first and before the
|
|
60
60
|
route's arguments are checked, so a redirect is a real 307 even after an awaited query, and a not-found is a 404 —
|
|
61
|
-
where a `getSelf({ unauthorize })` inside a layout body after I/O
|
|
62
|
-
guard that the server refuses with 403 or 404 (an owner check) answers not-found, so the page
|
|
63
|
-
record exists. A refusal's not-found keeps only the layouts above the refusing guard, and a path
|
|
64
|
-
asks the guards of the layouts its not-found would sit under first.
|
|
61
|
+
where a `getSelf({ unauthorize })` inside a layout body under a `.loading()` redirects late after I/O, inside the
|
|
62
|
+
stream. A query in a guard that the server refuses with 403 or 404 (an owner check) answers not-found, so the page
|
|
63
|
+
never confirms the record exists. A refusal's not-found keeps only the layouts above the refusing guard, and a path
|
|
64
|
+
no page matches asks the guards of the layouts its not-found would sit under first.
|
|
65
65
|
- **On a client navigation a page's layers wait for its guards.** The verdict is kept by what the guards read (a
|
|
66
66
|
query only the page reads keeps it) and lasts while a layer of that location is on screen. Only the page in front
|
|
67
67
|
asks — never a parked one, nor the one under it during a swipe back; back in front, a cached page included, it asks
|
|
@@ -83,9 +83,10 @@ body shape — this is the full contract behind them. Before changing route beha
|
|
|
83
83
|
native back or swipe, the agent's `navigate` and `goBack` — with routes free of locale and basePath and `to: null`
|
|
84
84
|
for a `back`. `false`, a throw or a rejection keeps the page, `router.navigation()` rejects with
|
|
85
85
|
`NavigationRefused`, and a refused browser back is undone before the page redraws. Guards answer one at a time; a
|
|
86
|
-
move started while one decides is refused.
|
|
87
|
-
(`
|
|
88
|
-
|
|
86
|
+
move started while one decides is refused. In a component, register it with `useNavigationGuard(() => !isDirty)`
|
|
87
|
+
(`akanjs/webkit`), held only while its page is current: a page kept under the next for a swipe back stays mounted,
|
|
88
|
+
and a guard it kept would hold that page too. Redirects, `notFound()`, `setLang` and moves off the origin are not
|
|
89
|
+
asked; a closing tab is `beforeunload`'s.
|
|
89
90
|
|
|
90
91
|
## MCP Apps — `.app()`
|
|
91
92
|
|
|
@@ -120,6 +120,10 @@ this is the full contract behind them.
|
|
|
120
120
|
still run — a nudge that re-sends a row its rooms must re-read, with no edit to stamp.
|
|
121
121
|
- `upsertById(data, { preserveTimestamps })` writes a record whole under its own id, new or in place, with no
|
|
122
122
|
hook: the write a sync or a backfill repeats safely, keeping the record's `createdAt`/`updatedAt` when asked.
|
|
123
|
+
With `{ where }` it writes over a stored row only when that row matches, in the same statement, and never over a
|
|
124
|
+
removed row unless `withRemoved` is also passed; an id no row holds is inserted. It then answers `updateOne`'s
|
|
125
|
+
result: `modifiedCount` 0 when the stored row did not match, and `upsertedId` set on an insert. A writer whose
|
|
126
|
+
lease may have lapsed passes the lease as `where`, so a takeover's row is never overwritten or revived.
|
|
123
127
|
- **Writes that must land together go in `this.transaction(async () => …)`**, which every service has: it commits
|
|
124
128
|
when the body resolves, returns its value, and rolls back when it throws, rethrowing that error unchanged. A
|
|
125
129
|
server has one database, so it covers every model, hooks and query-level writes included; a nested call joins the
|
|
@@ -102,9 +102,11 @@ worker per web-serving replica.
|
|
|
102
102
|
gateway's own shape — a `children` array with one entry — so a probe reads one contract either way. It owns the
|
|
103
103
|
rotating log file the gateway would otherwise write, in the same `runtime/logs` directory.
|
|
104
104
|
- **Health detail and metrics answer only `Authorization: Bearer $AKAN_STATUS_TOKEN`** (or the log stream token)
|
|
105
|
-
outside
|
|
106
|
-
|
|
107
|
-
|
|
105
|
+
outside the local dev runtime — `AKAN_PUBLIC_ENV` and the operation mode both `local`, under `akan start` or a
|
|
106
|
+
`NODE_ENV` other than `production`, so a built server stays closed: without it `/_akan/app/health` is `{ status }`
|
|
107
|
+
alone (still 200) and `/_akan/app/metrics` is 401. An address that sends 10 wrong bearers in a minute is refused
|
|
108
|
+
the right one too until the minute passes. A probe that reads only the status code needs nothing; give a scraper or
|
|
109
|
+
monitor `AKAN_STATUS_TOKEN` (32 characters or more, or it warns), which reads nothing else.
|
|
108
110
|
- **Nothing supervises a solo process but the orchestrator**, since the gateway's crash-restart-with-backoff went
|
|
109
111
|
with it. `infra/app/templates/app.yaml` carries the liveness, readiness and startup probes that replace it.
|
|
110
112
|
- **`PORT` is the whole tree's port, and a server-side self-call follows it.** `AkanApp` resolves it once
|
|
@@ -156,12 +158,13 @@ worker per web-serving replica.
|
|
|
156
158
|
and neither does a save in a sibling app. An import that makes a new lib a dependency needs a fresh
|
|
157
159
|
`akan start`, because it needs a `sync` first anyway. Before the first `sync` the manifests do not exist yet and
|
|
158
160
|
the whole `libs/` container is watched, which is the safe direction.
|
|
159
|
-
- **A built artifact runs from the generated app directory
|
|
161
|
+
- **A built artifact runs from the generated app directory, without Docker and without an env.** `akan build`
|
|
162
|
+
writes `akan.env.json` beside `main.js` with the values the Dockerfile's `ENV` lines set, and `main.js` takes
|
|
163
|
+
each one the process was not started with, so a variable you set (or the image's `ENV`) wins. Start it from that
|
|
164
|
+
directory: the runtime reads its artifacts and writes `runtime/` and SQLite files relative to the cwd.
|
|
160
165
|
|
|
161
166
|
```bash
|
|
162
|
-
cd dist/apps/<appName> &&
|
|
163
|
-
AKAN_PUBLIC_APP_NAME=<appName> AKAN_PUBLIC_ENV=local AKAN_PUBLIC_OPERATION_MODE=local SERVER_MODE=federation \
|
|
164
|
-
AKAN_PUBLIC_BASE_PATHS=<basePaths> bun main.js
|
|
167
|
+
cd dist/apps/<appName> && PORT=3100 bun main.js
|
|
165
168
|
```
|
|
166
169
|
|
|
167
170
|
- **A server a test boots in-process takes `start({ listen: false, schedules: false })`** to run no internal
|
|
@@ -207,7 +210,8 @@ normalized to `info` with one warning.
|
|
|
207
210
|
server's socket rather than reading their own logs.
|
|
208
211
|
- **The generated Dockerfile sets `AKAN_LOG_TO_FILE=0`.** A container's writable layer is ephemeral and nothing
|
|
209
212
|
collects a file from it; stdout is the collection path. A deployment that wants the files back sets
|
|
210
|
-
`AKAN_LOG_TO_FILE=1
|
|
213
|
+
`AKAN_LOG_TO_FILE=1`; they are created 0600, so a collector running as another user needs `AKAN_LOG_FILE_MODE`
|
|
214
|
+
(octal, e.g. `640`), and a file already there keeps its mode.
|
|
211
215
|
- **`AKAN_LOG_FORMAT=ndjson` makes the container's stdout one JSON record per line, and the hub owner (gateway or
|
|
212
216
|
solo replica) its only writer** — every other server process turns its console off and forwards from
|
|
213
217
|
`AKAN_LOG_STDOUT_LEVEL` (default: the console level); a child's or the RSC worker's crash stack is wrapped as a
|
|
@@ -216,8 +220,8 @@ normalized to `info` with one warning.
|
|
|
216
220
|
unset, the route does not exist. The same bearer also unlocks the health detail and metrics.
|
|
217
221
|
- **`AKAN_LOG_CANONICAL=1|slow`** writes one `ok|error <endpoint> ms= status=` line per call; **`AKAN_LOG_FLIGHT=1`**
|
|
218
222
|
keeps each call's last 64 sub-level records and promotes them (`flight=true`) only when it failed or ran past
|
|
219
|
-
`AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` —
|
|
220
|
-
`AKAN_LOG_DEBUG_HEADER` secret.
|
|
223
|
+
`AKAN_LOG_FLIGHT_MS`; an `x-akan-debug` header lowers one request to `trace` — under the local dev runtime, or
|
|
224
|
+
with the `AKAN_LOG_DEBUG_HEADER` secret.
|
|
221
225
|
- **Structured values go in `LogRecord.attrs` via `Logger.emit(...)`**; a key naming a secret is `[redacted]`
|
|
222
226
|
before the record exists.
|
|
223
227
|
- **Never log per delivered record in anything that delivers records.** The control socket and the hub do not,
|
|
@@ -394,11 +398,11 @@ const config: AppConfig = {
|
|
|
394
398
|
A desktop app whose `native` section, or target, declares `desktop: { server: true }` carries the app's server:
|
|
395
399
|
`akan build-desktop`, `start-desktop --release` and `publish-update` put the backend `akan build` made into the
|
|
396
400
|
app — everything the backend build wrote (the `.js`, `akan.build.json`, `private/`, a bundled package's `.node`,
|
|
397
|
-
`.wasm` or file asset) but the Dockerfile
|
|
398
|
-
packages first with `bun install --production --prefer-offline`, before `akan build`
|
|
399
|
-
`--release` starts `akan start` beside the app when no dev server of this checkout
|
|
400
|
-
app's backend, so it does not change under an installed app: an update whose release
|
|
401
|
-
has none, or none when it has one, is refused, and switching means a reinstall.
|
|
401
|
+
`.wasm` or file asset) but the Dockerfile and its `akan.env.json`, the RSC worker, the console, `csr/` and
|
|
402
|
+
`public/` — and install its packages first with `bun install --production --prefer-offline`, before `akan build`
|
|
403
|
+
runs. `start-desktop` without `--release` starts `akan start` beside the app when no dev server of this checkout
|
|
404
|
+
answers. The setting is the app's backend, so it does not change under an installed app: an update whose release
|
|
405
|
+
carries a server when the app has none, or none when it has one, is refused, and switching means a reinstall.
|
|
402
406
|
`desktop: { server: { omit: ["rclnodejs"] } }` carries the server without packages only the image needs — an addon
|
|
403
407
|
tied to the image's system, code only a process the app never starts loads — and whatever only they pull in; the
|
|
404
408
|
image keeps them, and the server's own bundle must not import them. A package another dependency still installs
|
|
@@ -598,8 +602,8 @@ serving without a key. Everything else is behind the ops channel.
|
|
|
598
602
|
|
|
599
603
|
| surface | what it does |
|
|
600
604
|
|---|---|
|
|
601
|
-
| `bun main.js ops snapshot [--id] [--out] [--include-solid] [--json]` | `VACUUM INTO` a consistent copy, `integrity_check`, sha256, gzip,
|
|
602
|
-
| `bun main.js ops restore <manifest.json> [--identity <file>]` | offline only: verify, stage, keep the old file as `<db>.pre-restore-<ts>` (its `-wal`/`-shm` beside it), swap |
|
|
605
|
+
| `bun main.js ops snapshot [--id] [--out] [--include-solid] [--allow-plaintext] [--json]` | `VACUUM INTO` a consistent copy, `integrity_check`, sha256, gzip, age encryption, `manifest.json` |
|
|
606
|
+
| `bun main.js ops restore <manifest.json> [--identity <file>] [--allow-plaintext]` | offline only: verify, stage, keep the old file as `<db>.pre-restore-<ts>` (its `-wal`/`-shm` beside it), swap |
|
|
603
607
|
| `GET /_akan/ops/info` | the public info plus `akanVersion`, `buildId`, `serverMode`, `databaseMode`, `solo`, `startedAt`, `replicaIdx` |
|
|
604
608
|
| `POST /_akan/ops/snapshot` `{ id, includeSolid?, uploadUrls: { main, solid?, manifest } }` | 202; a child process snapshots, then PUTs each file and the manifest **last** |
|
|
605
609
|
| `GET /_akan/ops/snapshot/:id` | `running` → `uploading` → `done` \| `failed`; kept in memory, so a restart answers 404 |
|
|
@@ -612,12 +616,15 @@ serving without a key. Everything else is behind the ops channel.
|
|
|
612
616
|
- **Restore refuses while an app answers `/_akan/app/health` on `PORT`** and names it by its `/_akan/app/info`;
|
|
613
617
|
`--force` is for a port some other app holds.
|
|
614
618
|
- **The channel exists only when `AKAN_OPS_PUBLIC_KEY` is set** (Ed25519: PEM, JWK, base64 SPKI or raw 32 bytes).
|
|
615
|
-
The control plane signs a short EdDSA JWS — `
|
|
616
|
-
|
|
617
|
-
someone carries off
|
|
619
|
+
The control plane signs a short EdDSA JWS — `typ` `akan-ops+jwt` (`JWT` or none from an older control plane; any
|
|
620
|
+
other `typ` is refused), `aud`, `iat`, `exp` at most 300s after `iat`, a `jti` the process refuses twice, and
|
|
621
|
+
optionally `sub`, whom it acts for — and the host holds only the public half, so a machine someone carries off
|
|
622
|
+
mints nothing.
|
|
618
623
|
`aud` is `<appName>/<environment>`, or `<appName>/<environment>/<AKAN_OPS_INSTANCE>` when that is set, and then
|
|
619
|
-
only that: a token minted for the app as a whole would replay across every host sharing the name.
|
|
620
|
-
minute per process; every refusal is the same 401
|
|
624
|
+
only that: a token minted for the app as a whole would replay across every host sharing the name. Verified calls
|
|
625
|
+
get 30 a minute per process; every refusal is the same 401 and spends none of them, and an address refused 10
|
|
626
|
+
times in a minute gets 429 until it passes. A malformed key, or the machine token's own key
|
|
627
|
+
(`AKAN_MACHINE_PUBLIC_KEY`), logs an error and leaves the app serving with the channel off.
|
|
621
628
|
- **A migrate job runs for the token's `sub`**, which the run records as its actor: apply and rollback refuse a
|
|
622
629
|
token without one, and a body naming `actor` is refused. Each option reaches the command as `--name=value`. One
|
|
623
630
|
job runs at a time per process (409 meanwhile); the run's own lease keeps two hosts on one database apart. Jobs
|
|
@@ -629,10 +636,13 @@ serving without a key. Everything else is behind the ops channel.
|
|
|
629
636
|
(`SQLITE_DATABASE_PATH`, `AKAN_SOLID_DB_PATH`, `AKAN_SQLITE_DIR`); a solo process uses the path its adaptor
|
|
630
637
|
actually opened, so a gateway deployment that moved the file in `env.server.ts` names it in the env too.
|
|
631
638
|
- **`AKAN_BACKUP_RECIPIENT=age1…[,age1…]` encrypts before upload** — age v1 X25519, so `age -d -i key.txt` opens
|
|
632
|
-
it.
|
|
633
|
-
`
|
|
639
|
+
it. Outside local operation a snapshot refuses to run without it, the ops channel's job included, unless
|
|
640
|
+
`--allow-plaintext` or `AKAN_BACKUP_PLAINTEXT=1` allows an unencrypted one. Restore takes `--identity` /
|
|
641
|
+
`AKAN_BACKUP_IDENTITY_FILE`, or a file an operator already decrypted with `age -d -o <name without .age>`; given
|
|
642
|
+
an identity, it refuses a manifest recording no encryption without `--allow-plaintext`.
|
|
634
643
|
- **The host keeps the newest `AKAN_OPS_SNAPSHOT_KEEP` (default 2) snapshots** under `AKAN_OPS_SNAPSHOT_DIR`
|
|
635
|
-
(default `<db dir>/snapshots/<id>/`) — the copy an edge still has while its uplink or the bucket is down.
|
|
644
|
+
(default `<db dir>/snapshots/<id>/`) — the copy an edge still has while its uplink or the bucket is down. Files are
|
|
645
|
+
0600 and each `<id>/` 0700; `AKAN_OPS_SNAPSHOT_FILE_MODE` (octal, e.g. `640`) sets another mode.
|
|
636
646
|
- **`buildId` is `AKAN_BUILD_ID` when the deployment sets it**, else the git sha `akan build` wrote into
|
|
637
647
|
`akan.build.json` beside `main.js` (`-dirty` when the tree was).
|
|
638
648
|
- **`operationMode` does not gate any of this** — the key does. `edge` means a production host outside the
|