@akanjs/cli 3.1.1-rc.8 → 3.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.build-stamp +1 -1
- package/CodeAgent-35wnb7w5.js +9 -0
- package/{CodeTui-rqxarxsn.js → CodeTui-h6yz2kvq.js} +1 -1
- package/TunnelShare-xyjpa7gx.js +14 -0
- package/agent.command-3r4jsck8.js +46 -0
- package/akanCode.js +10 -6
- package/{application.command-14xsthcr.js → application.command-g7xv6ad0.js} +46 -13
- package/{applicationBuildRunner-t2r84sz6.js → applicationBuildRunner-qvjnhr9j.js} +9 -6
- package/buildBatch.proc.js +6 -6
- package/{cloud.command-rmw1kcf1.js → cloud.command-6ebygmhw.js} +17 -15
- package/cloud.script-0s1jybd5.js +26 -0
- package/{code.command-719k3e9q.js → code.command-mpkm2emr.js} +6 -6
- package/commandManifest.json +1 -1
- package/{context.command-c4t4z1vy.js → context.command-svdh6b2w.js} +18 -17
- package/context.runner-ch0z3a8g.js +26 -0
- package/{devTui-q7k7bakd.js → devTui-evr3b35y.js} +1 -1
- package/{guideline.command-snh85ctf.js → guideline.command-qwp3tnjx.js} +3 -3
- package/guidelines/conventions/core.md +106 -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/pageRule/pageRule.instruction.md +4 -3
- package/guidelines/queryRule/queryRule.instruction.md +4 -0
- package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +3 -3
- package/incrementalBuilder.proc.js +6 -6
- package/{index-pcwzkdqb.js → index-1p0qbq3m.js} +1 -1
- package/{index-xb8809yb.js → index-1shvxzt0.js} +3 -3
- package/{index-8w76g4rm.js → index-266dewjs.js} +11 -11
- package/{index-5max10jx.js → index-3yz30c07.js} +72 -53
- package/{index-xjf5j657.js → index-4mj92tsh.js} +952 -47
- package/index-4pdts00b.js +1604 -0
- package/{index-42j4a8zq.js → index-8559hsz4.js} +4 -3
- package/{index-wcej7g4z.js → index-8scw1pjk.js} +93 -23
- package/{index-5phjb48k.js → index-96wzdhfh.js} +74 -233
- package/index-9bv479q5.js +1 -0
- package/index-9rvcs76p.js +653 -0
- package/index-am36s3jh.js +3582 -0
- package/index-b8c289dx.js +444 -0
- package/{index-espk51ah.js → index-dd44g6vz.js} +3 -3
- package/{index-3wypz6xj.js → index-eja64h28.js} +7 -3
- package/index-fbewhg4g.js +590 -0
- package/index-jje9qzyq.js +27 -0
- package/{index-j9vyj3dj.js → index-k5jbcxyh.js} +3 -3
- package/{index-hmmv2cah.js → index-ksfgqq1x.js} +1 -1
- package/index-m5n3ka0p.js +18 -0
- package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
- package/{index-0p37cz91.js → index-payhwt51.js} +21 -29
- package/{index-myc22sgv.js → index-qkkdhjm6.js} +5 -4
- package/{index-74tjjsnc.js → index-qxzrp5xt.js} +33 -37
- package/{index-zrte51fn.js → index-r0k3ham2.js} +4 -4
- package/{index-hmt54t45.js → index-r2w2eh93.js} +4 -4
- package/index-r2wedvqn.js +138 -0
- package/{index-skk9zc1x.js → index-rnphv731.js} +2 -2
- package/{index-pa3c2mb8.js → index-s6da8ta9.js} +82 -1227
- package/index-tenw3mah.js +225 -0
- package/{index-31es1yev.js → index-tgt2fnd6.js} +107 -6
- package/{index-8ap5z1n5.js → index-vxmy1p4f.js} +16 -36
- package/{index-mdqr41sp.js → index-w4k2ragk.js} +7 -7
- package/{index-qd5km521.js → index-w7q6h97v.js} +1 -1
- package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
- package/{index-2xcc2ax5.js → index-xq543a5y.js} +2 -2
- package/{index-0fz95kxe.js → index-xqgwjz7a.js} +1 -1
- package/{index-40brg4px.js → index-xxfy1jp2.js} +4 -4
- package/{index-905qdgqp.js → index-z4b84y6k.js} +1 -1
- package/index-zcf6k8a5.js +410 -0
- package/index.js +23 -22
- package/{library.command-gycrwhf1.js → library.command-2853y6mk.js} +3 -3
- package/{localRegistry.command-2t3fghje.js → localRegistry.command-76ds31p4.js} +19 -15
- package/{module.command-v6hgs1bc.js → module.command-yfnb0abs.js} +5 -5
- package/{package.command-shzpcfph.js → package.command-d9s86hp9.js} +3 -3
- package/package.json +2 -2
- package/{page.command-ptxn5kqk.js → page.command-6a8a8rd1.js} +3 -3
- package/{pipeline.command-zz31pgax.js → pipeline.command-rt3rwd2z.js} +2 -2
- package/{primitive.command-a1vse91z.js → primitive.command-emcebgrq.js} +6 -6
- package/{projectTypecheck-2ztky9cf.js → projectTypecheck-51m7eh1f.js} +1 -1
- package/{prompter-76k56b37.js → prompter-hgcta8pb.js} +1 -1
- package/quality.command-xtrk0n3x.js +76 -0
- package/{repair.command-cvazbz99.js → repair.command-51szxnxx.js} +5 -5
- package/{routeSourceValidator-6jd0q6r6.js → routeSourceValidator-4h947v7c.js} +13 -3
- package/{scalar.command-0acvyp26.js → scalar.command-8qv27t82.js} +4 -4
- package/skills/akan-agent/SKILL.md +36 -0
- package/skills/akan-code/SKILL.md +1 -0
- package/skills/akan-debug/SKILL.md +40 -6
- 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-kvxmyxtf.js → subspace.command-pn56pnh8.js} +8 -8
- 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/page/task/_index.tsx +2 -1
- package/templates/appSample/page/task/new.tsx +2 -1
- 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 +6 -5
- 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 +3 -0
- package/templates/workspaceRoot/.vscode/settings.json.template +21 -21
- package/templates/workspaceRoot/AGENTS.md.template +4 -10
- package/{tunnel.command-kxv0ddmp.js → tunnel.command-q2h0j2en.js} +7 -7
- package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
- package/typecheck.proc.js +6 -1
- package/verify.command-z1dsbmrt.js +91 -0
- package/{workflow.command-abb1d5xy.js → workflow.command-r3y67jeq.js} +47 -13
- package/workspace.command-t2f0xsrw.js +263 -0
- package/CodeAgent-3sy7kjgj.js +0 -9
- package/TunnelShare-2ef94kha.js +0 -14
- package/agent.command-ydftceda.js +0 -25
- package/cloud.script-v1ysyerg.js +0 -24
- package/context.runner-qb15sjf8.js +0 -25
- package/guidelines/conventions/conventions.instruction.md +0 -617
- package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
- package/index-4vgbysa0.js +0 -279
- package/index-7md2g9vw.js +0 -6
- package/index-b70zct19.js +0 -856
- 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-tsc99yec.js +0 -521
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
## Akan.js
|
|
2
|
+
|
|
3
|
+
Akan.js is a full-stack TypeScript framework: business code written once reaches web, native apps, server, database
|
|
4
|
+
and infrastructure. A workspace is Bun-first: `apps/<app>` holds pages, domain modules, UI, env files and
|
|
5
|
+
`akan.config.ts`; `libs/<lib>` holds shared domain and utility code apps reuse.
|
|
6
|
+
|
|
7
|
+
## Work Loop
|
|
8
|
+
|
|
9
|
+
1. Read the module's `*.abstract.md` and its neighbours before changing it. Update the abstract when an invariant, a
|
|
10
|
+
workflow or public behaviour changes, never for a style-only edit.
|
|
11
|
+
2. Prefer an Akan workflow to a hand edit: `akan workflow list` / `explain <name>` / `plan <name> … --out <plan>` /
|
|
12
|
+
`apply <plan>`, or the `list_workflows` / `plan_workflow` / `apply_workflow` tools of `akan mcp`. Split a
|
|
13
|
+
compound request into workflows applied in order (`create-module`, then `add-field`). Hand-edit only the owning
|
|
14
|
+
source file, and only when no workflow fits or apply reports manual action.
|
|
15
|
+
3. Never hand-edit a generated file (listed below). After adding, renaming or deleting a file, run
|
|
16
|
+
`akan sync <app-or-lib>`.
|
|
17
|
+
4. After editing, run `akan verify [<app-or-lib>]` once. It syncs, lints with fixes, typechecks, fast-builds and
|
|
18
|
+
checks SSR over what changed, and prints only what failed. Fix and rerun until it prints `verify ok`; never run
|
|
19
|
+
`akan lint`, `akan typecheck` and `akan build` one by one.
|
|
20
|
+
5. After a page, UI or runtime change, run `akan preview <app> --changed` (or name the paths) and quote its verdict
|
|
21
|
+
lines; it reuses the running dev server. Name any platform you could not open.
|
|
22
|
+
6. Check an endpoint with a signal test (`akan test <app> [files]`), never raw HTTP against the dev server.
|
|
23
|
+
7. Scaffolds take the target positionally (`akan create-module photo <app>`, `akan sync <app>`); only `add-field` and
|
|
24
|
+
`add-enum-field` take `--app` / `--module`.
|
|
25
|
+
|
|
26
|
+
## Change Scope
|
|
27
|
+
|
|
28
|
+
- Change what the task needs and the files directly tied to it — no formatting-only diffs, no style rewrites nearby.
|
|
29
|
+
- Never revert or overwrite someone else's change in a dirty working tree.
|
|
30
|
+
- Follow the nearest established pattern; when two shapes disagree, follow the newer neighbour. A new abstraction must
|
|
31
|
+
remove real duplication — near-identical sibling modules are copied with changed literals, not parameterised.
|
|
32
|
+
|
|
33
|
+
## Looks Wrong, Is Right — Do Not "Fix"
|
|
34
|
+
|
|
35
|
+
- Tailwind class order (`font-bold text-2xl text-foreground`) — Biome sorts it, `cn()` arguments included.
|
|
36
|
+
- `static name = "User";` on a guard class — `fetch` serializes it and the API explorer filters on it.
|
|
37
|
+
- `(this as unknown as RootStore).logout()` in a store — the sanctioned way to reach another store.
|
|
38
|
+
- `key={idx}` and short dependency arrays — `noArrayIndexKey` and `useExhaustiveDependencies` are off on purpose.
|
|
39
|
+
- Empty scaffold files, empty dictionary stages, the `// state` / `// action` markers — they mark where code goes.
|
|
40
|
+
- One-line re-export shims in a lib's `common/`, `webkit/`, `ui/` — the only legal path for a third-party package.
|
|
41
|
+
- `return await …save()` in a service; `as const` on every `enumOf(...)` array.
|
|
42
|
+
- Typos and transliterated terms in domain vocabulary — callers match on the name.
|
|
43
|
+
|
|
44
|
+
## Rules That Break The Build
|
|
45
|
+
|
|
46
|
+
`akan verify` reports each through the check named in parentheses, and the bracketed path rule carries the full
|
|
47
|
+
contract. Path rules name their checks the same way.
|
|
48
|
+
|
|
49
|
+
- Throw `new Err("<module>.error.<key>")` with the key in the module dictionary's `.error({})`; never a raw `Error`
|
|
50
|
+
(`no-throw-raw-error`) [app].
|
|
51
|
+
- A third-party package reaches `page/**`, a barrel or a module file only through a lib re-export
|
|
52
|
+
(`no-import-external-library`) [app].
|
|
53
|
+
- Colors only from the semantic vocabulary (`bg-primary`, `text-foreground/70`) — no palette, arbitrary, daisyUI or
|
|
54
|
+
`style={{}}` colors (`no-raw-palette-class`, `no-arbitrary-color`, `no-daisyui-legacy-class`, `no-inline-color`)
|
|
55
|
+
[style].
|
|
56
|
+
- No `console.log` / `console.debug`, never `logger.log()` (`noConsole`, `no-deprecated-log-level`); server code logs
|
|
57
|
+
through `this.logger` [app].
|
|
58
|
+
- No `document.cookie`, `localStorage` or `sessionStorage` (`no-document-cookie`, `no-web-storage`) — `getCookie`,
|
|
59
|
+
`setCookie`, `storage`, `secretStorage` from `akanjs/client` [app].
|
|
60
|
+
- Client files never import server files and the reverse (`no-import-server-in-client`, `no-import-client-in-server`);
|
|
61
|
+
`import type` is legal everywhere [ssr].
|
|
62
|
+
- A server write leaves the browser only through a store action, one write per action or handler
|
|
63
|
+
(`akan.write.placement`, `akan.store.multi-write`, `akan.component.write-chain`); chained writes become one service
|
|
64
|
+
method behind one endpoint [gates].
|
|
65
|
+
- Every endpoint and named slice names its `guards`, `[Public]` when anonymous is the intent (`no-unguarded-endpoint`)
|
|
66
|
+
[auth].
|
|
67
|
+
- Never ask a list for more than 500 rows (`no-oversized-list-limit`) [module]; never call a hook conditionally, `st.*`
|
|
68
|
+
hooks included (`useHookAtTopLevel`, `no-conditional-st-hook`) [tsx].
|
|
69
|
+
- A file or component past its size limit fails (`akan.size.file`, `akan.size.component`), and `akan.baseline.json`
|
|
70
|
+
only shrinks (`akan.baseline.growth`) — never add or raise an entry [gates].
|
|
71
|
+
- Suppress a plugin diagnostic as `// biome-ignore lint/plugin: <reason>`; every suppression carries a reason [app].
|
|
72
|
+
|
|
73
|
+
## Code Style
|
|
74
|
+
|
|
75
|
+
- `const` arrow functions over `function`; `interface` for shapes, `type` for unions; no non-null assertions
|
|
76
|
+
(`as unknown as T`, never `as any`); `#private`, but `private` in `*.{constant,document,service,store}.ts`.
|
|
77
|
+
- One class per file, named after it; TypeScript files are camelCase, component and convention files excepted.
|
|
78
|
+
- Identifiers, endpoint names and logs are English; everything a user reads goes through `l("model.field")` or
|
|
79
|
+
`l.trans({ en, ko })`, and dictionary entries are `[en, ko]` pairs.
|
|
80
|
+
- Comment only what the code cannot say (`akan verify` flags each new one as `akan.comment.added`) — a vendor quirk,
|
|
81
|
+
an infrastructure constraint, security reasoning, a domain field's meaning, a state transition, a rejected
|
|
82
|
+
alternative. Never restate code, label a section or add JSDoc; retire a symbol with
|
|
83
|
+
`/** @deprecated <what instead> */`.
|
|
84
|
+
- Server rendering is the default: `"use client"` only for a hook, an event handler, the store, a browser global or
|
|
85
|
+
a client-only package.
|
|
86
|
+
|
|
87
|
+
## Where Code Goes
|
|
88
|
+
|
|
89
|
+
| Code | Place |
|
|
90
|
+
|---|---|
|
|
91
|
+
| A database-backed noun (User, Product) | `lib/<model>/` — `akan create-module <model> <app>` |
|
|
92
|
+
| A workflow or integration with no stored model | `lib/_<service>/` — `akan create-service <service> <app>` |
|
|
93
|
+
| An embedded value type (Address) | `lib/__scalar/<scalar>/` — `akan create-scalar <scalar> <app>` |
|
|
94
|
+
| A route | `page/` — `<route>.tsx`, `_index.tsx`, `_layout.tsx`, `[param]/` |
|
|
95
|
+
| A pure, isomorphic helper | `common/<name>.ts` (imports `akanjs/base` only, never throws) |
|
|
96
|
+
| A React hook, browser or native-bridge code | `webkit/use<Thing>.tsx` |
|
|
97
|
+
| An adapter, guard, or code touching `node:*`, `Bun`, env or a secret | `srvkit/<name>.ts` |
|
|
98
|
+
| JSX or a look not bound to one model | `ui/<Component>.tsx`, `ui/Recipe/<name>.ts` |
|
|
99
|
+
| The color theme | semantic token values in `page/styles.css` |
|
|
100
|
+
| An iOS, Android or desktop app | `native: { … }` in `akan.config.ts`; an owned plugin in `native/<id>/` |
|
|
101
|
+
| A change to the stored document shape | `akan create-migration <name> <app>` |
|
|
102
|
+
|
|
103
|
+
## Secrets
|
|
104
|
+
|
|
105
|
+
Never print, summarise or commit secret values, credentials, tokens, private keys or `.env` contents; name env keys
|
|
106
|
+
with placeholders only. `AKAN_PUBLIC_*` values ship to the browser — never put a secret in one.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Akan app and library code: the lint gates, sync allowlists and the warts not to copy.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Akan App And Library Code
|
|
8
|
+
|
|
9
|
+
## Rules Every File Obeys
|
|
10
|
+
|
|
11
|
+
`biome.json` extends `@akanjs/devkit/biome.base.json`, which scopes every grit plugin in `@akanjs/devkit/lint/`;
|
|
12
|
+
each plugin's header and diagnostic carry its full reasoning.
|
|
13
|
+
|
|
14
|
+
- **Never construct a raw `Error`** (`no-throw-raw-error`). Throw `new Err("<module>.error.<key>")` with the key
|
|
15
|
+
registered as `[en, ko]` in the module dictionary's `.error({})` — imported from `"../dict"` on the server, from
|
|
16
|
+
`"@libs/<lib>/client"` / `"@apps/<app>/client"` in UI. A `throw` is an error; a raw `Error` rejected, returned or
|
|
17
|
+
stored loses the key and status too (a warning for now). Exempt: tests, `*.constant.ts`, a root `native/` folder
|
|
18
|
+
(plugins throw `AkanNativeError`), `script/migration/**` (an operator reads its message), and `common/**` / `env/**`,
|
|
19
|
+
which have no legal `Err` import — keep throwing code out of them.
|
|
20
|
+
- **Never import a third-party package** (`no-import-external-library`) from `page/**`, any barrel, a module logic file
|
|
21
|
+
(`*.{constant,dictionary,document,service,signal,store}.ts`) or module component
|
|
22
|
+
(`*.{Template,Unit,Util,View,Zone}.tsx`) — re-export it through a lib first (one-line shims in a lib's `common/`,
|
|
23
|
+
`webkit/`, `ui/` are load-bearing). `*.signal.test.ts` / `*.service.test.ts` too, though they may import `node:*` and
|
|
24
|
+
`bun:*` (`no-import-external-library-in-test`).
|
|
25
|
+
- **No `console.log` / `console.debug`** (`noConsole`; only `assert`, `error`, `info`, `warn`; server code uses
|
|
26
|
+
`this.logger` or `new Logger("ClassName")`), and **never `logger.log()` / `Logger.log()`** (`no-deprecated-log-level`)
|
|
27
|
+
— it emits at `info` while reading like its own level; write `.info()`. The ladder is
|
|
28
|
+
`trace verbose debug info warn error`.
|
|
29
|
+
- **Never touch `document.cookie`, `localStorage` or `sessionStorage`** (`no-document-cookie`, `no-web-storage`) — a
|
|
30
|
+
native shell's page keeps no cookies on iOS, macOS and Linux, and Web Storage throws during SSR. Use `getCookie` /
|
|
31
|
+
`setCookie` / `removeCookie`, `storage`, `secretStorage` from `akanjs/client`. Browser APIs a WebView lacks
|
|
32
|
+
(`navigator.share`, `serviceWorker`, `Notification`, `geolocation`, `vibrate`) live in a `webkit/` hook behind
|
|
33
|
+
`isNativeApp()` (`no-web-only-api-outside-webkit`, a warning). Both in full: `runtimeRule`.
|
|
34
|
+
- **No deep imports past a barrel** (`no-deep-internal-import`), except cross-module constants (`../map/map.constant`).
|
|
35
|
+
- **Suppress a grit diagnostic as `lint/plugin`** (`// biome-ignore lint/plugin: <reason>`,
|
|
36
|
+
`// biome-ignore-all lint/plugin: <reason>`); bare `plugin:` does nothing. `pkgs/` is out of scope.
|
|
37
|
+
- **`biome.json` is strict JSON** — a comment breaks config resolution without an error (Biome falls back to
|
|
38
|
+
discovery and aborts on a nested config); rename it `biome.jsonc` to document a disabled rule.
|
|
39
|
+
- **`akan lint` prints up to 200 diagnostics** (`--max-diagnostics <n>`, `0` = all); Biome's own uncounted 20 reads
|
|
40
|
+
as progress when the mix merely changed.
|
|
41
|
+
|
|
42
|
+
## Akan Sync Conventions
|
|
43
|
+
|
|
44
|
+
- App root files: `AGENTS.md`, `CLAUDE.md`, `akan.app.json`, `akan.baseline.json`, `akan.config.ts`, `client.ts`,
|
|
45
|
+
`main.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.tsbuildinfo`; folders: `.akan`, `common`, `env`,
|
|
46
|
+
`lib`, `native`, `page`, `plugin`, `private`, `public`, `script`, `secrets`, `srvkit`, `ui`, `webkit`. A Capacitor-era
|
|
47
|
+
`ios` / `android` / `mobile` folder or `capacitor.config.*` in an app root is refused as a leftover (native
|
|
48
|
+
projects live under `dist/native/<app>/<target>`).
|
|
49
|
+
- Lib root files: `AGENTS.md`, `CLAUDE.md`, `README.md`, `akan.baseline.json`, `akan.config.ts`, `akan.lib.json`,
|
|
50
|
+
`client.ts`, `index.ts`, `package.json`, `server.ts`, `tsconfig.json`, `tsconfig.spec.json`, `tsconfig.tsbuildinfo`;
|
|
51
|
+
folders: the app's minus `.akan`, `script`, `secrets` (no `main.ts` either — a lib is never booted).
|
|
52
|
+
- The allowlists' one source is `pkgs/@akanjs/devkit/workspaceLayout.ts`, read by `akan sync` (error), `akan doctor`
|
|
53
|
+
and `akan quality scan` — add an entry there and mirror it here.
|
|
54
|
+
- `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` carry a generated `## Recipes In Scope` block between the
|
|
55
|
+
`akan:agent` markers — never hand-edit it (outside the markers is yours); `akan lint` fails when it is stale.
|
|
56
|
+
- `plugin/<name>.plugin.ts` declares an Akan plugin. No `apps/*/base` or `libs/*/base` — use `common/`.
|
|
57
|
+
- `lib/` root holds only `cnst.ts`, `db.ts`, `dict.ts`, `option.ts`, `sig.ts`, `srv.ts`, `st.ts`, `useClient.ts`,
|
|
58
|
+
`useServer.ts` — no hand-written file or test.
|
|
59
|
+
- Modules are `lib/<model>`, `lib/_<service>`, `lib/__scalar/<scalar>`; their UI files are
|
|
60
|
+
`<Model>.Template|Unit|Util|View|Zone.tsx`, `<Service>.Util|Zone.tsx`, `<Scalar>.Template|Unit.tsx`. A test is
|
|
61
|
+
named after the one file it covers, so `<model>.<topic>.signal.test.ts` is refused like `<model>.<topic>.signal.ts`.
|
|
62
|
+
- `ui/`, `webkit/`, `srvkit/`, `common/`, `plugin/` and module `index.ts` barrels are generated
|
|
63
|
+
(`export * from "./name";` per 1-depth entry, `export {};` when empty, so a stale one heals on sync;
|
|
64
|
+
`akan create-library` starts `common/`, `srvkit/`, `webkit/`, `ui/` with that empty barrel) — never hand-edit or
|
|
65
|
+
track them. **Never hand-write an
|
|
66
|
+
`index.tsx` / `.jsx` / `.mts` at those roots**: Bun resolves it before the generated `index.ts`, so new exports are
|
|
67
|
+
`undefined` at runtime (`akan sync` refuses it, `akan doctor` reports `facet-index-shadowed`); a namespace belongs
|
|
68
|
+
in `ui/<Folder>/index.tsx`.
|
|
69
|
+
- Sync writes barrels, module indexes and `akan.*.json` exactly as Biome prints them (`akan lint --no-fix` passes
|
|
70
|
+
right after a sync), so a lint diff in one is a generator bug — fix the generator.
|
|
71
|
+
- **`akan sync` owns package.json `dependencies`**: it adds imports at the root's version, realigns root-declared
|
|
72
|
+
entries, and drops unimported ones (logged); undeclared-at-root entries are kept with a warning. Keep a package no
|
|
73
|
+
TS file imports (a CSS `@plugin`, a runtime-only package) with `akan.keepDependencies`; `externalLibs` and
|
|
74
|
+
`trustedDependencies` always stay; devDependencies are realigned, never pruned. `akan install-library` lets the
|
|
75
|
+
root win — it adds only what the root lacks and warns when the lib wants a newer version.
|
|
76
|
+
|
|
77
|
+
## Present In The Code — Do Not Imitate
|
|
78
|
+
|
|
79
|
+
Warts in older files — never copy them; when two shapes disagree, follow the newer neighbour: `children: any`
|
|
80
|
+
(use `ReactNode`); hard-coded API keys or secrets (they belong in `option.ts` or env); large commented-out blocks;
|
|
81
|
+
stale `// TODO: Implement …` above implemented methods; `{cond && <X/>}`, hard-coded Korean bypassing `l()`,
|
|
82
|
+
`window.alert(...)`; bare `/* eslint-disable */` blocks; raw palette grays like `text-gray-400`. A store reaching
|
|
83
|
+
another through `(this as unknown as RootStore)` is **not** a wart — it is the sanctioned way.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Guards and authorization on signals and srvkit: slice guard maps, endpoint guards, the acting user.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.signal.ts"
|
|
5
|
+
- "{apps,libs}/**/srvkit/**"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Authorization
|
|
9
|
+
|
|
10
|
+
- **Every `slice()` takes an explicit `{ guards: {…} }` second argument, and `root:` is always `Admin`.**
|
|
11
|
+
`guards: { cru: false }` (or per verb) takes a generated verb off HTTP; `mcp: { cru: false }` only keeps it off the
|
|
12
|
+
agent shelf.
|
|
13
|
+
- **Every custom `mutation` / `query` / `message` names its own `guards: [...]`** — the slice map reaches only
|
|
14
|
+
generated endpoints, and a `pubsub` / `message` without its own is unguarded. `Public` belongs on a slice `get:`;
|
|
15
|
+
on a mutation only for an act that must work signed out (sign-up/in, token refresh, an OAuth route), which also
|
|
16
|
+
declares a `rateLimit`. A guardless endpoint is warned at boot and never published to MCP, which also refuses a
|
|
17
|
+
mutation guarded only by `Public`.
|
|
18
|
+
- Guards serve HTTP and websocket alike: read `context.get<T>("account")`, never `getHttpContext()` /
|
|
19
|
+
`getWebSocketContext()`; keep them side-effect free and re-runnable. The acting user comes from `.with(Self)` /
|
|
20
|
+
`.with(CurrentUserId)` / `.with(Me)` (never a client-supplied id) and the caller's address from `.with(Ip)`.
|
|
21
|
+
- Keep `static name = "User";` on guard classes — `fetch` serializes it and the API explorer filters on it. It looks
|
|
22
|
+
dead, so comment it.
|
|
23
|
+
- **Every guard declares `static scope: GuardScope`, no default**: `"account"` reads only the caller (MCP listings
|
|
24
|
+
evaluate it to hide entries), `"resource"` needs the call's arguments and fails closed without them. `SignedIn` /
|
|
25
|
+
`Admin` / roles are `"account"`, every `Can<Verb><Model>` is `"resource"`; `Person` adds `static agents = false`.
|
|
26
|
+
- `Can<Verb><Model>` guards in `srvkit/guards.ts` fail closed and ship with the model's library (`transportRule`).
|
|
27
|
+
Services re-check ownership behind a guard — two independent gates.
|
|
28
|
+
|
|
29
|
+
- **Every endpoint and named slice names its guards** (`no-unguarded-endpoint`, a warning) — a `query` / `mutation` /
|
|
30
|
+
`pubsub` / `message`, a named slice's `init()`, or a `slice()` map without `root` that names none (or `guards: []`)
|
|
31
|
+
answers every caller. Write `guards: [Public]` when anonymous access is the intent.
|
|
32
|
+
|
|
33
|
+
- **A `slice()` takes its guard map as a second argument**, `slice(srv.task, { guards: { root: Admin, get: SignedIn,
|
|
34
|
+
cru: SignedIn } }, (init) => ({...}))`. An `endpoint()` takes no guard argument at all —
|
|
35
|
+
`endpoint(srv.task, ({ mutation }) => ({...}))` — so **every custom `mutation` / `query` / `message` names its own
|
|
36
|
+
`guards: [...]` array**: `mutation(cnst.Task, { guards: [SignedIn] })`. `Public` always allows; other guards
|
|
37
|
+
implement the `Guard` interface in `srvkit/` (server-only).
|
|
38
|
+
- **Read the caller inside a guard** with `context.get<T>("account")`, which works on HTTP and websocket calls
|
|
39
|
+
alike — never branch on `getHttpContext()` / `getWebSocketContext()`. Every guard class also declares
|
|
40
|
+
`static scope: GuardScope`, `"account"` or `"resource"`, with no default.
|
|
41
|
+
- **Read the current user inside a custom endpoint** by injecting an `InternalArg` with `.with(...)`:
|
|
42
|
+
`mutation(cnst.Task, { guards: [SignedIn] }).with(CurrentUserId).exec(async function (currentUserId) { ... })`.
|
|
43
|
+
- **Auto-generated CRUD and `serve()` service methods / lifecycle hooks do not receive session context.** If an
|
|
44
|
+
operation needs the acting user, expose a custom endpoint that takes it via `.with(CurrentUserId)` — never trust a
|
|
45
|
+
client-supplied user id.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Runtime and build configuration: akan.config.ts, main.ts, env narrowing, native apps, database modes.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/*/akan.config.ts"
|
|
5
|
+
- "{apps,libs}/*/main.ts"
|
|
6
|
+
- "{apps,libs}/*/env/**"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Runtime And Build Configuration
|
|
10
|
+
|
|
11
|
+
Declared in `akan.config.ts`, narrowed — never widened — by an env at boot; domain code reaches none of it
|
|
12
|
+
(`runtimeRule`).
|
|
13
|
+
|
|
14
|
+
- **`web: true | false | { csr: boolean }`** — `{ csr: false }` drops the CSR bundle native apps ship, `false` is
|
|
15
|
+
API-only.
|
|
16
|
+
- **Route prefixes move together**: `new AkanApp({ prefix, websocketPrefix })` in `main.ts`, mirrored in
|
|
17
|
+
`api: { … }` in `akan.config.ts` for a CSR shell or native bundle. Read them with `getApiPrefix()` /
|
|
18
|
+
`getWsPrefix()` (`akanjs/base`); never write `/api` or `/ws`, never pass one as a prop.
|
|
19
|
+
- **`main.ts` imports `AkanApp` from `akanjs/server/akanApp`**, not the barrel.
|
|
20
|
+
- Give every log sink a floor (`Logger.addSink(sink, { minLevel })`), never log per delivered record in anything
|
|
21
|
+
that delivers records, and tail with `akan logs <app>`.
|
|
22
|
+
- **`docker` is `string | { image, preRuns, postRuns, command }`**; the generated image installs only
|
|
23
|
+
`ca-certificates` and `tzdata`.
|
|
24
|
+
- **Native apps are the `native` section** (iOS, Android, desktop). A desktop app's carried server listens on a
|
|
25
|
+
loopback port any local program can call — guard it as a network server — and ships `private/` and its env
|
|
26
|
+
readable on the user's computer; read runtime files from `AKAN_APP_DIR`, and keep a secret the user gives it with
|
|
27
|
+
`NativeSecret` (the OS credential store), never in a file.
|
|
28
|
+
- **`database: { modes: [...] }`** (`single`, `multiple`, `cluster`), chosen by `AKAN_DATABASE_MODE`; an app running
|
|
29
|
+
in two modes avoids `q.raw`.
|
|
30
|
+
|
|
31
|
+
## Running An App
|
|
32
|
+
|
|
33
|
+
- After changing application code, run `bun run akan start <appName>` (`a,b`, `a b`, or `all` for several); check
|
|
34
|
+
the production build with `bun run akan build <appName>`.
|
|
35
|
+
- A supervised session writes `local/apps/<app>/runtime/dev.log` (previous: `dev.prev.log`) — hand over that path,
|
|
36
|
+
not a paste of the repainting full-screen view. Keys, `--plain`, boot waves, `--kill`, watch scope, running a
|
|
37
|
+
built artifact, booting a server in a test: `runtimeRule`.
|
|
38
|
+
|
|
39
|
+
## Native Apps
|
|
40
|
+
|
|
41
|
+
`native: { desktop: { server: true } }` in `akan.config.ts` is all a desktop app that carries its own server needs.
|
|
42
|
+
A `start-*` command loads its pages from `akan start`, so run that first; a desktop app that carries its server
|
|
43
|
+
starts it itself. The full contract — targets, updates, what the carried server ships — is
|
|
44
|
+
`akan guideline show runtimeRule`.
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
akan start-desktop <app> # Run the desktop app on this computer
|
|
48
|
+
akan start-ios <app> # Run it in a simulator or on an iPhone (start-android alike)
|
|
49
|
+
akan build-desktop <app> # Build it for this computer into dist/native/<app>/<target>/build
|
|
50
|
+
akan build-desktop <app> --installer true # Windows: add a per-user setup program
|
|
51
|
+
akan update-keygen <app> # Make the update signing key once; print its public key
|
|
52
|
+
akan publish-update <app> # Build a key-signed release for updates.url; --sign true also code-signs it
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
A device capability the framework lacks is a plugin the app owns in `native/<id>/`: `native-plugin.json`,
|
|
56
|
+
`src/index.ts` (the page API, used from a `webkit/` hook), `src/desktop.ts`, Kotlin and Swift.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Model and scalar shapes in *.constant.ts: the five layers, scalars, defaults and field kinds.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.constant.ts"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Scalar Modeling
|
|
8
|
+
|
|
9
|
+
- Models use `via` from `akanjs/constant`, all five layers (`Input`, `Object`, `Light<Model>`, `<Model>`,
|
|
10
|
+
`<Model>Insight`). `Int` for counts, `Float` only for decimals, `ID` for references; structured fields over `Any`.
|
|
11
|
+
- Import `Int`, `Float`, `ID`, `Any`, `Binary`, `Upload`, `ImageResult`, `enumOf`, `dayjs` from `akanjs/base`;
|
|
12
|
+
`String` / `Boolean` / `Date` are globals. No `JSON` scalar (use `Any`), no `Number`, and `Binary` / `Upload` are
|
|
13
|
+
never fields — a file is `field(File).optional()` / `field([File])`, uploaded by the generated
|
|
14
|
+
`upload<Field>On<Model>` (which `Field.Img` / `Files` and siblings use when handed the generated setter); it marks
|
|
15
|
+
the field in `<model>FormUploading` while the request runs and drops a result whose form was set whole meanwhile
|
|
16
|
+
(or, on a single field, re-picked) — gate a hand-written submit on it.
|
|
17
|
+
- Defaults: a literal for scalars, a thunk for anything constructed (`default: () => dayjs()`). Arrays
|
|
18
|
+
`field([T])`; optional `.optional()`.
|
|
19
|
+
- **`field.hidden` / `field.secret` read `null` on the client while the type declares them** — guard with `??` or
|
|
20
|
+
`== null`, never `=== undefined` or a default. `field.visual(T)` is rendered but stripped from every agent and MCP
|
|
21
|
+
read. Full contract: `fieldRule`.
|
|
22
|
+
|
|
23
|
+
- **No `static` on an `XObject` or `LightX` class** (`no-static-in-object-light-model`) — `via()` mixes in their
|
|
24
|
+
prototypes only; use `XInput` (or a scalar), `X`, or `XInsight`.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: The akan lint gates on size, store reach, where writes start and per-item calls, and the baseline.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
- "{apps,libs}/**/*.{store,service,document}.ts"
|
|
6
|
+
- "{apps,libs}/*/{ui,webkit}/**"
|
|
7
|
+
- "{apps,libs}/*/akan.baseline.json"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Lint Gates
|
|
11
|
+
|
|
12
|
+
- **Size, store reach, where writes start, and per-item calls fail `akan lint`** for an app or lib, each failure
|
|
13
|
+
naming its rule and the `akan workflow plan …` path that fixes it:
|
|
14
|
+
- `akan.size.file`: a `Zone` / `Util` / `Template` / `Unit` / `View`, a `*.store.ts`, or a `ui/` / `webkit/` file
|
|
15
|
+
over 400 lines; a service or document over 500; an abstract over 300. `akan.size.component`: a component or hook
|
|
16
|
+
over 250. `akan.component.store-access`: a component or hook reaching `st` more than 16 times (form setters aside).
|
|
17
|
+
- `akan.write.placement`: a server write leaves the browser only through a store action, started by a module
|
|
18
|
+
component — no `fetch.<mutation>` outside a `*.store.ts`, and no writing `st.do.*` in `ui/` or `webkit/`, which
|
|
19
|
+
take the write as an `onX` prop or hook argument.
|
|
20
|
+
- `akan.store.multi-write`, `akan.store.root-write-chain`, `akan.component.write-chain`: a store action, a store
|
|
21
|
+
`static`, or one handler (a hook's included) sending two or more writes — directly, through a sibling action,
|
|
22
|
+
through another store via `RootStore`, or once per item in a loop or `map`. Make them one service method
|
|
23
|
+
(`this.transaction(fn)`, a side effect in `this.afterCommit(fn)`) behind one endpoint, taking the list, that the
|
|
24
|
+
action calls once.
|
|
25
|
+
- `akan.service.call-in-loop`: a service method an `endpoint` or `slice` reaches calling a service, a model or a
|
|
26
|
+
generated query once per item (`for … of`, `map`, `forEach`); load the set once (`load<Model>Many`, one
|
|
27
|
+
filter query) or write it once. An `internal` job and a counted loop (a retry, paging) are spared.
|
|
28
|
+
- `akan.baseline.json` (`akan.baseline.growth`) records, per rule, the debt adopted with the gate, and is compared
|
|
29
|
+
with its copy at the fork point of the default branch, so it only ever shrinks: never add or raise an entry. A size,
|
|
30
|
+
store-reach or per-item entry with a `reasons` line is an exception a person decided on, never an agent; the write
|
|
31
|
+
rules take no exceptions.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: The shared layers common/, webkit/, srvkit/, ui/, plugin/, native/: what each admits.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/*/{common,webkit,srvkit,ui,plugin,native}/**"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Layer Placement
|
|
8
|
+
|
|
9
|
+
| Folder | Admission test | Naming |
|
|
10
|
+
|---|---|---|
|
|
11
|
+
| `common/` | pure, isomorphic, zero-dependency; imports only sibling `common/*` and `akanjs/base` (so no `Err`, and no throwing code) | camelCase file named after its single export |
|
|
12
|
+
| `webkit/` | touches `window` / `navigator` / the native bridge (`akanjs/client/native[/<plugin id>]`), or is a React hook; sends no server write | `use<Thing>.tsx`, `.tsx` even without JSX |
|
|
13
|
+
| `srvkit/` | touches `node:*`, `Bun`, `process.env`, a secret, or a server SDK | camelCase file, PascalCase class |
|
|
14
|
+
| `ui/` | renders JSX or defines a look (`Recipe/`, a lib's `tokens.css`), not bound to one model; sends no server write | PascalCase component, camelCase sidecar, `Recipe/<name>.ts` |
|
|
15
|
+
| `plugin/` | a build- or CLI-time `AkanPlugin` | `<name>.plugin.ts`, registered in `akan.config.ts` |
|
|
16
|
+
| `native/` | a native plugin the app or lib owns — its page API reached only through a `webkit/` hook (`runtimeRule`) | `native/<id>/` |
|
|
17
|
+
|
|
18
|
+
- Hooks return a named object of async closures, never a tuple.
|
|
19
|
+
- Recipes live in `ui/`: `webkit/` hooks are `"use client"`, and `common/` cannot import `akanjs/ui`.
|
|
20
|
+
- A layer-root `index.ts` is generated; a `ui/<Folder>/index.tsx` building a namespace is hand-written (a generated
|
|
21
|
+
barrel holds only `export *` lines). `ui/<Folder>/index_.tsx` is the `"use client"` + `lazy()` boundary beside a
|
|
22
|
+
server-safe `index.tsx` — merging the pair breaks RSC.
|
|
23
|
+
|
|
24
|
+
- **No `//!` or `/*!` in browser-reachable code** (`ui/`, `webkit/`, `common/`, `page/**/*.tsx`, `*.constant.ts`,
|
|
25
|
+
`*.store.ts`, module components; `no-bang-comment-in-client`) — Bun keeps both through minification. Use `// FIXME:`.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Data migrations under script/migration: table() writes, plan hashing and resumable applies.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/*/script/migration/**"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Data Migrations
|
|
8
|
+
|
|
9
|
+
A change that reshapes stored documents ships a migration: `akan create-migration <name> <app>` writes
|
|
10
|
+
`script/migration/<yyyyMMddHHmm>_<name>.ts`, a default-exported `migration(title)` from `akanjs/server`, which
|
|
11
|
+
`akan migrate <app>` runs locally and `bun main.js ops migrate` in a built container (the `cheatsheet/dev/migration`
|
|
12
|
+
docs page).
|
|
13
|
+
|
|
14
|
+
- The new code reads both shapes until every environment has applied it — a deploy serves traffic first.
|
|
15
|
+
- Write only through `table(refName)`, never a service, a document or raw `sql` — a service write runs the model's
|
|
16
|
+
hooks, and none of them reaches the change log a rollback reverts. Call nothing outside the database.
|
|
17
|
+
- `plan` reads only and must hash the same on unchanged data: a timestamp, `createId()` or random value in it makes
|
|
18
|
+
every `apply --expect <planHash>` refuse as `planChanged`.
|
|
19
|
+
- Past about five seconds on SQLite, an apply's one transaction makes the live server's writes fail. Take
|
|
20
|
+
`.config({ transaction: false })`, which commits each `rewrite` batch and resumes a `partial` run from the top of
|
|
21
|
+
`apply` — so a second run must change nothing (a `where` the new shape no longer matches).
|
|
22
|
+
- `$ne` leaves out rows whose path is missing or `null` (match them with `{ path: null }`; `$exists: false` misses a
|
|
23
|
+
stored `null`); `find`, `count` and `rewrite` include removed rows unless `{ withRemoved: false }`; a `table()` write
|
|
24
|
+
leaves `updatedAt` alone.
|
|
25
|
+
- Throw a plain `Error` an operator can act on. Never edit a migration an environment has applied — write another;
|
|
26
|
+
delete it once every environment has, unless its `.rollback(fn)` may still be needed: without the file a rollback
|
|
27
|
+
runs the default undo.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Domain modules under lib/: what each module file owns, and the modeling gotchas.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/lib/**"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Domain Modules
|
|
8
|
+
|
|
9
|
+
A business concept is one `lib/` folder holding its logic files
|
|
10
|
+
(`<model>.constant|dictionary|document|service|signal|store.ts`) and components
|
|
11
|
+
(`<Model>.Template|Unit|View|Zone|Util.tsx`). `constant`, `dictionary` and
|
|
12
|
+
`signal` are shared contracts with no platform-specific dependency; persistence and queries live in `document`,
|
|
13
|
+
orchestration in `service`, client state in `store`; `Template` is forms, `Unit` list/card items, `View` details,
|
|
14
|
+
`Zone` page sections, `Util` domain UI helpers.
|
|
15
|
+
|
|
16
|
+
- **`<model>.constant.ts`** — `enumOf("camelName", [...] as const)` classes, then
|
|
17
|
+
`XInput → XObject → LightX → X → XInsight`, one blank line apart, `XInsight` even when empty. **Display and
|
|
18
|
+
predicate logic goes on `LightX`** (`isNew()`, `canWrite(user?)`), which server and client both hold, never a util
|
|
19
|
+
module — the most commonly missed rule. Collection helpers are `static` on `X`; a non-obvious field gets a short
|
|
20
|
+
trailing comment. `Date` fields are prototype accessors that a spread drops — copy with `new cnst.X().set(user)`
|
|
21
|
+
(`fieldRule`).
|
|
22
|
+
- **`<model>.document.ts`** — `XFilter extends from(...)` → `X extends by(...)` → `XModel extends into(...)`,
|
|
23
|
+
`sort: {}` always present. Chain methods validate → mutate → `return this`, never `save()` (the caller saves, so
|
|
24
|
+
`org.removeUser(id).removeInvite(id).save()` composes), with a one-line transition comment above each. Atomic
|
|
25
|
+
counters live on the Model class with the updater callback, returning `!!modifiedCount`; indexes and derived
|
|
26
|
+
totals go in `static override _onSchema`. **Removal is soft** and reads see live rows unless
|
|
27
|
+
`{ withRemoved: true }`; the one hard delete is `purge<Filter>` / `purgeMany`, for data past retention.
|
|
28
|
+
`updateById` / `removeById` fire no hooks — a cascading or `_postRemove` model removes through
|
|
29
|
+
`remove<Model>(id)`, and `pickAndWrite` writes through the save hooks (`queryRule`).
|
|
30
|
+
- **`<model>.service.ts`** — a few lines: load → chain → `return await ….save()` (keep the `return await`). Side
|
|
31
|
+
effects go in `override async _preUpdate` / `_postCreate`; fire-and-forget is `void`-ed. Load every referenced
|
|
32
|
+
document, then save, then notify; writes that must land together go in `this.transaction(async () => …)` and
|
|
33
|
+
their notification in `this.afterCommit(…)` (`queryRule`). Return `null` / `false` for not allowed or not found;
|
|
34
|
+
the signal decides whether that is an error.
|
|
35
|
+
- **`<model>.signal.ts`** — `XInternal` → `XSlice` → `XEndpoint`, all three even when empty; `exec` is a one-liner
|
|
36
|
+
calling the service.
|
|
37
|
+
- **`<model>.store.ts`** — custom actions only for a toast, an optimistic update, or a multi-field write:
|
|
38
|
+
`await fetch.X` → `this.setX(...)` → toast, or mutate the client model, `void fetch.*`, then commit.
|
|
39
|
+
`this.pick(...)` when the value must exist, `this.get()` when it may not, `this.set({...})` to write; lists through
|
|
40
|
+
the collection API (`xList.set(x).save()`), not spread. **Another store is reached through `this`**:
|
|
41
|
+
`import type { RootStore } from "../st"` (type-only — `st.ts` imports every store), then
|
|
42
|
+
`(this as unknown as RootStore).logout()` or `.set({ … })` / `.get()`; every store is mixed into one root at
|
|
43
|
+
runtime, so the cast only names what `this` already is.
|
|
44
|
+
- **`<model>.dictionary.ts`** — empty stages still written:
|
|
45
|
+
`.of() → .model() → .insight() → .query() → .sort() → .enum() → .slice() → .endpoint() → .error() → .translate()`;
|
|
46
|
+
every `.arg()` named, framework `skip` / `limit` / `sort` included; `modelDictionary` / `scalarDictionary` /
|
|
47
|
+
`serviceDictionary` by module kind.
|
|
48
|
+
- **`<module>.abstract.md`** — a title, one sentence naming what the module owns, a `## Rules` list of two to five
|
|
49
|
+
invariants the code cannot show, an optional workflow chain (`draft -> signed -> active`). Never restate fields or
|
|
50
|
+
types; update it when an invariant or workflow changes.
|
|
51
|
+
|
|
52
|
+
- **`{name}`, never `{{name}}`** (`no-double-brace-placeholder`), in a dictionary `.error()` / `.translate()` entry —
|
|
53
|
+
only single braces interpolate.
|
|
54
|
+
- **Never return a value from a store action** (`no-return-in-store-action`) — actions dispatch through `st.do.*` as
|
|
55
|
+
`void`; write state with `this.set({ ... })`. A bare `return;`, a nested callback's `return`, a getter, and a `static`
|
|
56
|
+
helper are fine.
|
|
57
|
+
- **Never redeclare a generated CRUD endpoint name** in `*.signal.ts` (`no-redeclare-predefined-endpoint`).
|
|
58
|
+
- **Never ask a list for more than 500 rows** (`no-oversized-list-limit`) — the server serves at most 500 per
|
|
59
|
+
request and drops the rest without an error, so `fetch.xListInY(0, 10000)` silently stops at row 500. Page with
|
|
60
|
+
skip/limit or `st.do.loadMoreOf<X>()` while `hasMoreOf<X>`, or compute the figure in an insight or an endpoint.
|
|
61
|
+
|
|
62
|
+
## Modeling And Query Gotchas
|
|
63
|
+
|
|
64
|
+
- **Slices return a query, not a list.** A slice `exec` must return `this.<model>Service.query<Filter>(...)`, never
|
|
65
|
+
a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
|
|
66
|
+
`Unknown document field path: 0`. (See Recipe 3.)
|
|
67
|
+
- **Custom endpoint names must not collide with generated CRUD.** `create/update/remove/view/edit/merge<Model>`
|
|
68
|
+
already exist wherever the slice mounts the verb. A collision builds green and the server refuses to boot
|
|
69
|
+
(`[DI:fetch]`) — pick a distinct verb.
|
|
70
|
+
- **Numbers are `Int` or `Float`, never `Number`.** `field(Number)` / `.body("x", Number)` fail to typecheck.
|
|
71
|
+
- **Array fields use `field([T])`** — `tags: field([String])`, `images: field([File])`.
|
|
72
|
+
- **Reading a secret field needs an explicit select, and the two call sites spell it differently.**
|
|
73
|
+
`field(...).secret()` values are stripped from query results by default. The model facade takes the projection
|
|
74
|
+
**bare** — `this.userModel.pickById(id, { passwordHash: true })`, likewise `pickOne` / `find` / `findOne` /
|
|
75
|
+
`findById`. A generated filter accessor takes it **inside the option object** —
|
|
76
|
+
`this.userModel.findByAccountId(accountId, statuses, { select: { passwordHash: true } })`. Handing `{ select: … }`
|
|
77
|
+
to the facade projects a field named `select`, which no model has, and throws `Unknown document field path`.
|
|
78
|
+
- **`cascade` names a direction, and the wrong one is a data loss** — `removeRef` on the relation the owner holds,
|
|
79
|
+
`removeWith` on the child's reference to its owner. A query-level removal fires no hooks and therefore no cascade.
|
|
80
|
+
- **`q.search()` is a filter node, not a slice requirement.** `bySearch: filter().arg("text", String).query((text,
|
|
81
|
+
q) => q.search(text, { prefix: true }))` generates `listBySearch` / `countBySearch` / `queryBySearch` /
|
|
82
|
+
`insightBySearch` for free. Only add a search *slice* when the model's data is safe to enumerate.
|
|
83
|
+
|
|
84
|
+
## Akan Module Abstracts
|
|
85
|
+
|
|
86
|
+
- Before changing a domain, service, or scalar module, read its `*.abstract.md` file first.
|
|
87
|
+
- Update the abstract when business invariants, workflows, or public behavior change.
|
|
88
|
+
- Do not update the abstract for formatting-only, import-only, or style-only changes.
|
|
89
|
+
- Service modules live in `lib/_<service>`, but their abstract file is `<service>.abstract.md`.
|
|
90
|
+
- Keep an abstract short — the invariants the code cannot show, and nothing it already states. `akan quality scan` warns past 300 lines.
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Route files under page/: the one chain, params, heads, guards and lib pages.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/page/**"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Akan Page Routing
|
|
8
|
+
|
|
9
|
+
Full contract — guards, apps, heads, CSR root layouts, typed params, lib pages, `devOnly`: `pageRule`.
|
|
10
|
+
|
|
11
|
+
- `page/` holds `.tsx` route modules only: `<routeName>.tsx` or `_index.tsx`, `_layout.tsx`, `_overrides.tsx` — no
|
|
12
|
+
other `_*.tsx`, helpers, `.ts` / `.js` files, or uppercase filenames. `[id]` is a dynamic segment, `(group)` a
|
|
13
|
+
route group.
|
|
14
|
+
- **A route file exports one chain** — `page()`, `layout()` in a `_layout.tsx`, `rootLayout()` in a root
|
|
15
|
+
`_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
|
|
16
|
+
`.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
|
|
17
|
+
A named export beside it fails the build.
|
|
18
|
+
- **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`; values
|
|
19
|
+
arrive typed. `lang` is never declared — every stage receives it.
|
|
20
|
+
- `.head()` takes JSX or a function returning it — never a metadata object; deeper heads replace by tag identity,
|
|
21
|
+
and a canonical link / `og:url` comes only from the page's own `.head()`.
|
|
22
|
+
- In a CSR bundle a root layout's own markup is hidden: what a person must see from it renders through
|
|
23
|
+
`createPortal(…, document.body)`.
|
|
24
|
+
- `_overrides.tsx` is one `export default override({ Slot: AppComponent })` (`akanjs/ui`), no logic, no
|
|
25
|
+
`"use client"`. The legacy `export default async function Page` shape is never written anew.
|
|
26
|
+
- `libs/<lib>/page` reaches an app through `syncPageLibs`, linked into the generated `page/(libs)/(<lib>)`; edit the
|
|
27
|
+
lib source, never the link. `.config({ devOnly: true })` (a literal) keeps a route out of `akan build`.
|
|
28
|
+
|
|
29
|
+
```tsx
|
|
30
|
+
export default page()
|
|
31
|
+
.param("orgId", ID)
|
|
32
|
+
.config({ transition: "stack" })
|
|
33
|
+
.guard(() => signedIn())
|
|
34
|
+
.render(({ orgId }) => {
|
|
35
|
+
const { l } = usePage();
|
|
36
|
+
const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
|
|
37
|
+
return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
|
|
38
|
+
});
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
|
|
42
|
+
return; auth is the chain's `.guard()`, which runs before anything renders. Hand `fetch.init*` / `view*` / `edit*` fields to sections unawaited; await only what the shell reads
|
|
43
|
+
(title, redirect, link id) in one `Promise.all`.
|
|
44
|
+
- **A route never writes while it renders**: a `fetch.<mutation>()` in a stage or a component it renders throws
|
|
45
|
+
`base.error.mutationInRender`, since opening a link would perform it. Send it from a user action;
|
|
46
|
+
`{ duringRender: true }` only for a write harmless to repeat and safe for anyone to trigger (`ssrRule`).
|
|
47
|
+
- Gate auth with `.guard(() => signedIn())` (`@libs/shared/webkit`; a new workspace has that lib only with
|
|
48
|
+
`create-workspace --libs true`) at `_layout.tsx`, and repeat it on a page that needs more; it is a courtesy, the
|
|
49
|
+
endpoint guards are the gate. `getSelf({ unauthorize })` in a body still works. `async` only when the body awaits;
|
|
50
|
+
the callback is not a React component, so it takes no name and no return type. No `useState`, `useEffect`, or
|
|
51
|
+
comments in page files.
|
|
52
|
+
|
|
53
|
+
- **SSR auth-gated pages: guard at the layout.** `.guard(() => signedIn())` on the `_layout.tsx` chain answers a
|
|
54
|
+
real 307 before any of it renders, so nested pages never render for signed-out users; a check in `.render()`
|
|
55
|
+
after awaited I/O redirects in-page, as an HTTP 200. `signedIn()` comes from `@libs/shared/webkit`, which a new
|
|
56
|
+
workspace has only with `create-workspace --libs true`.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Secret and env files: never print, commit or summarise their values.
|
|
3
|
+
paths:
|
|
4
|
+
- "**/.env*"
|
|
5
|
+
- "**/*secret*"
|
|
6
|
+
- "**/*credential*"
|
|
7
|
+
- "infra/**"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Secrets And Env Safety
|
|
11
|
+
|
|
12
|
+
- Never print, summarize, commit, or expose real secret values, credentials, tokens, private keys, or `.env`
|
|
13
|
+
contents; document env keys by name with placeholders only.
|
|
14
|
+
- Preserve the env/secret flow through `bun run downloadEnv`, `uploadEnv`, `downloadSecret`, `uploadSecret`, and
|
|
15
|
+
keep Jenkins and deployment assumptions intact unless the task asks otherwise.
|
|
16
|
+
- Treat generated env/secret artifacts as sensitive even when they are not named `.env`.
|