@akanjs/cli 3.1.1-rc.16 → 3.1.1-rc.18
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.build-stamp +1 -1
- package/{CodeAgent-23ewzxqa.js → CodeAgent-fbcq8vks.js} +2 -2
- package/{CodeTui-kc99fk78.js → CodeTui-0626gxqd.js} +1 -1
- package/TunnelShare-2p24xxza.js +14 -0
- package/agent.command-hpza0pg9.js +46 -0
- package/akanCode.js +5 -3
- package/{application.command-bvfd1680.js → application.command-3a7q1hs2.js} +11 -10
- package/{applicationBuildRunner-4ajaesk1.js → applicationBuildRunner-s7yt71j4.js} +5 -5
- package/buildBatch.proc.js +6 -6
- package/{cloud.command-f2w40fyy.js → cloud.command-4vg0pcea.js} +15 -14
- package/cloud.script-nkmeyhet.js +25 -0
- package/{code.command-dbhhnahn.js → code.command-fbntb67p.js} +6 -6
- package/commandManifest.json +1 -1
- package/{context.command-yswjwv6y.js → context.command-31rm54v0.js} +18 -18
- package/context.runner-w01a32ph.js +26 -0
- package/{guideline.command-ztx6dkpk.js → guideline.command-cv3by2ng.js} +3 -3
- package/guidelines/conventions/core.md +104 -0
- package/guidelines/conventions/rules/app.md +83 -0
- package/guidelines/conventions/rules/auth.md +45 -0
- package/guidelines/conventions/rules/config.md +56 -0
- package/guidelines/conventions/rules/constant.md +24 -0
- package/guidelines/conventions/rules/gates.md +31 -0
- package/guidelines/conventions/rules/layer.md +25 -0
- package/guidelines/conventions/rules/migration.md +27 -0
- package/guidelines/conventions/rules/module.md +90 -0
- package/guidelines/conventions/rules/page.md +56 -0
- package/guidelines/conventions/rules/sensitive.md +16 -0
- package/guidelines/conventions/rules/server.md +86 -0
- package/guidelines/conventions/rules/ssr.md +47 -0
- package/guidelines/conventions/rules/style.md +43 -0
- package/guidelines/conventions/rules/test.md +34 -0
- package/guidelines/conventions/rules/ts.md +95 -0
- package/guidelines/conventions/rules/tsx.md +75 -0
- package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
- package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +3 -3
- package/incrementalBuilder.proc.js +6 -6
- package/{index-xjwcp91m.js → index-05nxx4m5.js} +43 -12
- package/{index-k9k18vq9.js → index-0ht91675.js} +37 -59
- package/{index-er16p89s.js → index-0zwznvv1.js} +1 -1
- package/{index-76jwsm3g.js → index-0zyatd10.js} +2 -2
- package/{index-97fsvy66.js → index-12kzwak1.js} +3 -3
- package/{index-005dqc83.js → index-1dhf8ymv.js} +2 -2
- package/{index-00ke4phc.js → index-3gccwenr.js} +1 -1
- package/{index-2epb3wgh.js → index-3txrjt6n.js} +2 -2
- package/{index-7ndgffg4.js → index-57q1ayd2.js} +18 -1240
- package/index-5kh9scvs.js +514 -0
- package/index-5n5hds19.js +1246 -0
- package/{index-9sa6abze.js → index-6269mf2s.js} +10 -9
- package/{index-921cxqrd.js → index-64g9fsjy.js} +41 -12
- package/index-7zeb5r1p.js +653 -0
- package/{index-s4c2y5gs.js → index-8s8b4eba.js} +45 -4
- package/{index-4332q6yj.js → index-922k2zwq.js} +3 -3
- package/{index-m6qgr1rx.js → index-9ndw5d8j.js} +7 -7
- package/{index-xfp4dcnx.js → index-et6ce601.js} +1 -1
- package/{index-saj9cx3a.js → index-f5adsa58.js} +4 -4
- package/{index-vgt25eh1.js → index-fbewhg4g.js} +7 -32
- package/{index-ysyt782g.js → index-hm7x0c11.js} +4 -4
- package/{index-2p1brf5e.js → index-hvv5rnaq.js} +2 -2
- package/index-jje9qzyq.js +27 -0
- package/{index-rxse80x6.js → index-js1gj6f6.js} +12 -10
- package/{index-p2pahmsa.js → index-kjrvwzav.js} +3 -3
- package/index-m6r88hhr.js +3582 -0
- package/{index-mk391h0z.js → index-mt0wa941.js} +4 -4
- package/{index-m93qg20j.js → index-mwj9q2ya.js} +1 -1
- package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
- package/index-r2wedvqn.js +138 -0
- package/{index-gxj80jz7.js → index-rvynj5gz.js} +1 -1
- package/{index-m54n0v29.js → index-tdv66eah.js} +4 -4
- package/{index-vq77g679.js → index-w134p86k.js} +1 -1
- package/{index-deeskxjh.js → index-wfczhj1z.js} +14 -36
- package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
- package/{index-qx4r4cj2.js → index-x5ecanqh.js} +2 -2
- package/{index-nzfgyw3b.js → index-zre4m2ce.js} +4 -4
- package/index.js +23 -22
- package/{library.command-hmbkcwzw.js → library.command-sh70fyvy.js} +3 -3
- package/{localRegistry.command-sq5p4c9x.js → localRegistry.command-2nbyy84d.js} +14 -13
- package/{module.command-n4z29zcv.js → module.command-n0bmtzwy.js} +5 -5
- package/{package.command-20025dy3.js → package.command-7h9r51bz.js} +3 -3
- package/package.json +2 -2
- package/{page.command-q8fvpjer.js → page.command-vjtpfbb1.js} +3 -3
- package/{pipeline.command-8j97fq88.js → pipeline.command-c93se3ar.js} +2 -2
- package/{primitive.command-e5y6dqp1.js → primitive.command-a3075qp2.js} +6 -6
- package/{projectTypecheck-tbdye9k3.js → projectTypecheck-sf9xwaga.js} +1 -1
- package/{prompter-76k56b37.js → prompter-hgcta8pb.js} +1 -1
- package/quality.command-dw1y9hmy.js +76 -0
- package/{repair.command-dq1gckth.js → repair.command-tg57d8yt.js} +5 -5
- package/{scalar.command-5vwf152w.js → scalar.command-cwzge353.js} +4 -4
- package/skills/akan-agent/SKILL.md +36 -0
- package/skills/akan-debug/SKILL.md +3 -3
- package/skills/akan-deps/SKILL.md +1 -2
- package/skills/akan-mcp/SKILL.md +40 -0
- package/skills/akan-page/SKILL.md +44 -0
- package/skills/akan-query/SKILL.md +38 -0
- package/skills/akan-runtime/SKILL.md +40 -0
- package/skills/akan-scaffold/SKILL.md +16 -6
- package/skills/akan-transport/SKILL.md +40 -0
- package/skills/akan-validate/SKILL.md +13 -11
- package/{subspace.command-182be8vj.js → subspace.command-3h03c7kc.js} +8 -8
- package/templates/workspaceRoot/.gitignore.template +3 -0
- package/templates/workspaceRoot/AGENTS.md.template +4 -10
- package/{tunnel.command-bfzj7xkb.js → tunnel.command-czaz6ys4.js} +7 -7
- package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
- package/typecheck.proc.js +6 -1
- package/verify.command-nzwhtz71.js +91 -0
- package/{workflow.command-3g53242s.js → workflow.command-srhky88x.js} +23 -13
- package/{workspace.command-h7399jwv.js → workspace.command-9stchcd2.js} +31 -29
- package/TunnelShare-dk2gw78d.js +0 -14
- package/agent.command-knp5j7bq.js +0 -25
- package/cloud.script-2r82sv0f.js +0 -24
- package/context.runner-c3wsh2jw.js +0 -26
- package/guidelines/conventions/conventions.instruction.md +0 -663
- package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
- package/index-4t4qb8jg.js +0 -279
- package/index-hvg3esm0.js +0 -1844
- package/index-zzvvc845.js +0 -74
- package/quality.command-168pt5vm.js +0 -1788
- package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
- package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
|
@@ -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`.
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Services, signals, documents and srvkit adapters: calls, queries, injection and where errors are thrown.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.{service,signal,document}.ts"
|
|
5
|
+
- "{apps,libs}/**/srvkit/**"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Services And Signals
|
|
9
|
+
|
|
10
|
+
- `serve(...)` services hold business operations. Signals hold contracts: `internal(...)` for init, interval, cron
|
|
11
|
+
and queue jobs (retries, dead letter: `workspaceRecipes` Recipe 5), `slice(...)` for focused data views feeding
|
|
12
|
+
stores and zones, `endpoint(...)` for queries and mutations. External APIs and infrastructure go through
|
|
13
|
+
`srvkit/` adapters injected into services, never vendor clients in domain logic.
|
|
14
|
+
|
|
15
|
+
## Calls, Queries, Agents
|
|
16
|
+
|
|
17
|
+
- **Wire (`transportRule`)**: a deadline is the endpoint's `{ timeout: <ms> }` (undeclared, the client quits at
|
|
18
|
+
30 s; the handler is not cancelled); `{ cache }` only on a `query` with no internal argument, capped at one day,
|
|
19
|
+
dropped early by `invalidate(endpoint, args?)` on a plugged `EndpointCacheControl`; `{ rateLimit }` per endpoint,
|
|
20
|
+
`option.setRateLimit` per app, `plug(RateLimit)` for a business key. `socketId` names a connection, not a caller. A
|
|
21
|
+
device proves itself with a `MachineToken`. Server to server, `fetch.clone({ origin })` opens no socket
|
|
22
|
+
without `connect: true`, retries through `retry`, and rethrows a remote `Err` as is — never wrapped or re-keyed.
|
|
23
|
+
- **Body types**: `.body()` / `.param()` take scalars, model refs, or `enumOf(...)`; `Int` / `Float`, never
|
|
24
|
+
`Number` (`pkgs/akanjs/signal/endpointInfo.ts`); `Upload` only in a `fileUpload: true` mutation; bytes are
|
|
25
|
+
`Binary`, never `Any`. A model or scalar argument is checked against the request schema on every transport: a
|
|
26
|
+
wrong JSON type, a value outside its enum or a missing required field answers 400 with `data.name` naming the
|
|
27
|
+
path (`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's
|
|
28
|
+
input keeps an absent field absent.
|
|
29
|
+
- **Reserved names**: generated CRUD (`create<Model>`, `update<Model>`, `remove<Model>`, …) exists for every model
|
|
30
|
+
whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
|
|
31
|
+
name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
|
|
32
|
+
- **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
|
|
33
|
+
`query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
|
|
34
|
+
A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
|
|
35
|
+
only way to read a `field.secret`. More rows: `loadMoreOf<Model>()` / `hasMoreOf<Model>`, never
|
|
36
|
+
`count > page * limit`. A filter's `remove*` / `update*` are hookless (no cascade). No value is `q.empty`, never
|
|
37
|
+
`q.missing`.
|
|
38
|
+
- **Search**: `q.search(text, { prefix: true })` in a filter, at an AND position, over `text`-role fields; a search
|
|
39
|
+
*slice* only on data safe to enumerate; blank input matches nothing — never a passthrough.
|
|
40
|
+
- **`cascade` names a direction; the wrong one loses data**: `removeRef` on the owner's relation, `removeWith` on
|
|
41
|
+
the child's reference to its owner. A query-level removal runs no cascade.
|
|
42
|
+
- **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
|
|
43
|
+
mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
|
|
44
|
+
`.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
|
|
45
|
+
required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
|
|
46
|
+
screen with `page().prompt(name, description)`, and publish one component a host draws with
|
|
47
|
+
`page().app(name, description, load)` — a read-only tool whose `load` may only query.
|
|
48
|
+
- **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
|
|
49
|
+
every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
|
|
50
|
+
`option.setAgentRequestPolicy`; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
|
|
51
|
+
The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
|
|
52
|
+
`st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
|
|
53
|
+
`visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
|
|
54
|
+
`<Agent.Guide instructions="…" />`; model-facing text is English.
|
|
55
|
+
|
|
56
|
+
## Injection And Adapters
|
|
57
|
+
|
|
58
|
+
- A field named `<refName>Service` / `<refName>Signal` resolves to that registration — the suffix is required
|
|
59
|
+
(`pkgs/akanjs/service/injectInfo.ts`). In a service: `service<srv.XService>()` · `plug(AdapterClass)` /
|
|
60
|
+
`plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
|
|
61
|
+
- `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
|
|
62
|
+
`String` memory.
|
|
63
|
+
- A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
|
|
64
|
+
`storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
|
|
65
|
+
`readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
|
|
66
|
+
`access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
|
|
67
|
+
- **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
|
|
68
|
+
register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
|
|
69
|
+
lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy
|
|
70
|
+
`constructor(options)` adapters migrate only when already being changed. Example and adapter conventions (one
|
|
71
|
+
`#api<T>` with a timeout, pagination, secrets, parameter shapes): `workspaceRecipes` Recipe 2.
|
|
72
|
+
|
|
73
|
+
## Error Placement
|
|
74
|
+
|
|
75
|
+
- State-machine preconditions throw in `document.ts`, cross-document rules in `service.ts`, request policy in
|
|
76
|
+
`signal.ts` guards. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no Result types.
|
|
77
|
+
- A `pick` or generated `get<Model>` that finds no live row answers 404 `base.error.documentNotFound` by itself
|
|
78
|
+
(`NoDocumentError`); load with a nullable `load<Model>` and throw `Err.NotFound` only to say more than that.
|
|
79
|
+
- An endpoint names the errors it throws on purpose — `errors: { 409: ["ticket.error.locked"] }` in its signal
|
|
80
|
+
option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
|
|
81
|
+
of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
|
|
82
|
+
`Err.is(error, "ticket.error.locked")`.
|
|
83
|
+
- `try/catch` turns an exception into a decision: guards → `logger.warn` → `false`; adapters → `logger.error` →
|
|
84
|
+
`null`; UI `try/finally` resets a spinner. A bodyless `catch {}` needs a one-line reason.
|
|
85
|
+
- Store actions do not `try/catch` (the framework toasts the `Err`); client validation is `msg.error("<key>")` plus
|
|
86
|
+
an early return, never a throw.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: The client/server boundary and SSR-first rendering for .tsx files and pages.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
- "{apps,libs}/**/page/**"
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Client/Server Boundary And SSR
|
|
9
|
+
|
|
10
|
+
## Client / Server Boundaries
|
|
11
|
+
|
|
12
|
+
- `"use client";` tops client component files. It is mechanical by role: `Template`, `Zone`, `Util` always carry it
|
|
13
|
+
on line 1; `Unit`, `View` never do. `usePage()` is legal in server files.
|
|
14
|
+
- A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never `export *` — the server knows a
|
|
15
|
+
client module only by the names it spells out, so `akan start` / `akan build` stop on a star re-export.
|
|
16
|
+
- Keep page props serializable unless the route pattern clearly allows otherwise; be careful importing client-only
|
|
17
|
+
code into pages and layouts. Preserve file roles (`.document.ts`, `.service.ts`, `.store.ts`, `.constant.ts`,
|
|
18
|
+
`.client.ts`), and inspect nearby files before introducing a new boundary pattern.
|
|
19
|
+
|
|
20
|
+
- **Never import across the client/server boundary** (`apps/**`, `libs/**`; `no-import-server-in-client`,
|
|
21
|
+
`no-import-client-in-server`). Client files (`ui/`, `webkit/`, `page/`, `*.store.ts`, every `.tsx`) never import a
|
|
22
|
+
`*.document|dictionary|service|signal.ts`, `srvkit/`, a package `server` entrypoint, or the `db` / `srv` / `sig` /
|
|
23
|
+
`dict` / `option` / `useServer` barrels. Server files (those four suffixes, `srvkit/`) never import a `*.store.ts`, a
|
|
24
|
+
module component, `ui/`, `webkit/`, a package `client` entrypoint, or the `st` / `store` / `useClient` barrels.
|
|
25
|
+
`common/` and `*.constant.ts` obey both. `import type` is legal everywhere; a mixed value-and-type import is not.
|
|
26
|
+
- **Server-component discipline** on `page/**`, `*.Unit.tsx`, `*.View.tsx` (`no-import-client-functions`,
|
|
27
|
+
`no-use-client-in-server`, `non-scalar-props-restricted`).
|
|
28
|
+
|
|
29
|
+
## SSR First — Server Rendering Is The Default
|
|
30
|
+
|
|
31
|
+
Server-rendered JSX ships as HTML and costs nothing to hydrate; `"use client"` ships it twice (markup plus JS that
|
|
32
|
+
re-runs). **The default is server; the directive is a cost justified per component** by a React hook, a JSX event
|
|
33
|
+
handler, the store, a browser global, or a client-only package — never by markup, params, `l()` or mapping data.
|
|
34
|
+
`akan quality ssr` (`--format json`) prints each app's and lib's server share: **50% is the floor, and a falling
|
|
35
|
+
share is a regression** to justify in the PR or revert. A client package or an `index_.tsx` `lazy()` boundary
|
|
36
|
+
justifies the directive; a `fetch.*` inside `onClick` is not flagged, only mount-time loads.
|
|
37
|
+
|
|
38
|
+
Playbook (warning table, code, checklist: `ssrRule`): ① wrap the interaction and render `children` untouched;
|
|
39
|
+
② split compound components (`Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`) — never one client file with a mode
|
|
40
|
+
`useState` and every panel inlined; ③ fetch in the route and pass `init` / `view` to a `Zone`, never a
|
|
41
|
+
`useEffect(…, [])` load; ④ a store-reading `Zone` holds no markup and delegates to a server `View`; ⑤ hand each
|
|
42
|
+
promise across — `const { xInitInY, xListInY } = fetch.initXInY(id)`, `xInitInY` to a `Zone`, `xListInY` to
|
|
43
|
+
`<Load.Stream>` (model instances, server-only) — and `await` only what the shell must contain; ⑥ named `ReactNode`
|
|
44
|
+
slots (`Layout.Navbar`); ⑦ derived display logic on `Light<Model>`; ⑧ `.guard(() => signedIn())`
|
|
45
|
+
(`@libs/shared/webkit`) on `_layout.tsx` (a real 3xx before anything renders; `getSelf({ unauthorize })` in a body
|
|
46
|
+
redirects in-page after I/O); ⑨ CSS (`data-*` + `group-data-[…]`, `<details>`) over client state for visibility;
|
|
47
|
+
⑩ heavy islands behind `index_.tsx` + `lazy()`.
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Styling: Tailwind order, the semantic colour vocabulary, cn(), recipes and the app theme.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
- "{apps,libs}/**/*.css"
|
|
6
|
+
- "{apps,libs}/*/ui/Recipe/**"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Styling
|
|
10
|
+
|
|
11
|
+
- **Never hand-order Tailwind classes** — `nursery/useSortedClasses` sorts them, `cn()` arguments included, and its
|
|
12
|
+
output (`font-bold text-2xl text-foreground`) is correct.
|
|
13
|
+
- **Stay inside the color vocabulary** (`no-raw-palette-class`, `no-arbitrary-color`, `no-interpolated-arbitrary-class`,
|
|
14
|
+
`no-daisyui-legacy-class`, `no-inline-color`): no raw palette (`bg-blue-500`), arbitrary or interpolated color classes
|
|
15
|
+
(`bg-[#3b82f6]`), daisyUI classes or slots (`btn-primary`, `bg-base-100`), or color literals in `style={{}}` — they
|
|
16
|
+
render no CSS. Use semantic tokens (`bg-primary`, `text-foreground/70`); a legitimate fixed color takes
|
|
17
|
+
`// biome-ignore lint/plugin: <reason>`. Slot replacements, SVG / `el.style` warnings, legal values: `cssRule`.
|
|
18
|
+
|
|
19
|
+
- Static class strings stay plain. `cn` (from `akanjs/client`) only for a conditional or to merge an incoming
|
|
20
|
+
`className`, caller last: `cn("base", cond && "extra", className)` — the only combiner: no `clsx`, raw `twMerge`,
|
|
21
|
+
or object syntax.
|
|
22
|
+
- Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
|
|
23
|
+
- Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
|
|
24
|
+
`Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
|
|
25
|
+
name map (`BadgeVariants["variant"]`) moves to `webkit/`.
|
|
26
|
+
|
|
27
|
+
## Theme And Component Overrides
|
|
28
|
+
|
|
29
|
+
When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
|
|
30
|
+
|
|
31
|
+
- **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
|
|
32
|
+
- **Lib tokens (`libs/<lib>/ui/tokens.css`).** The one CSS file a lib owns: colors its own components pin that must **not** follow the theme — a vendor brand color, a fixed surface — declared once as plain `:root` custom properties and compiled automatically into every app whose pages reach the lib, ahead of the app's stylesheets, so nothing is imported by hand. Reference them as `bg-[var(--kakao)]`; never copy the block into each app. `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet, and theme-following colors are the app's.
|
|
33
|
+
- **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
|
|
34
|
+
|
|
35
|
+
## Recipes
|
|
36
|
+
|
|
37
|
+
Framework UI recipes (Tailwind-variant look factories) import from `akanjs/ui`: `<name>(variants?, className?)`.
|
|
38
|
+
The second argument merges internally and takes an array too, so never wrap it in `cn()`:
|
|
39
|
+
`<name>({}, ["h-full", isWide && "w-full", className])`. Do not guess a recipe name or variant value, and do not open
|
|
40
|
+
the recipe file to consume one. Before inlining a repeated surface (card, box, tile): reuse a recipe, or add one as
|
|
41
|
+
`apps/<app>/ui/Recipe/<name>.ts`, one per file, re-exported from that folder's `index.ts` — never a near-duplicate.
|
|
42
|
+
Each app and lib lists its own recipes in `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` (`## Recipes In Scope`),
|
|
43
|
+
regenerated by `akan sync`. Full policy: the `recipeRule` guideline.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Tests: Bun's runner, one suite per module file, the signal test split and how to run them.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.{test,spec}.ts"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Test Code
|
|
8
|
+
|
|
9
|
+
- Bun's runner (`describe`, `expect`, `test` from `bun:test`); colocated `*.test.ts` / `*.spec.ts`; focused behavior
|
|
10
|
+
tests of public contracts and edge cases. A placeholder `it` with a descriptive title is the floor; a
|
|
11
|
+
security-relevant behaviour gets a real suite.
|
|
12
|
+
- Run `bun run akan test <pkg> [files]` from the root (`files`: comma-separated paths from the target or the root;
|
|
13
|
+
the only way a signal test runs), or `cd <pkg> && bun test --isolate ./<file>`. Plain `bun test` shares one global
|
|
14
|
+
object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not honored as
|
|
15
|
+
of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
|
|
16
|
+
- Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
|
|
17
|
+
`Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
|
|
18
|
+
describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
|
|
19
|
+
`await expect(p).rejects.toThrow()`. Each `fetch.clone()` reports its own address (`198.18.x.y`), so an `ip` rate
|
|
20
|
+
limit counts it apart: clone once per simulated user, signup included (`clone({ clientIp })` names one).
|
|
21
|
+
- **One suite per module file**: `<model>.<role>.test.ts` beside the file it covers — never topic splits
|
|
22
|
+
(`chatMessage.trim.signal.test.ts`); add a `describe`. A suite spanning modules goes in `srvkit/`
|
|
23
|
+
(`libs/shared/srvkit/guards.signal.test.ts`), never the `lib/` root; `akan sync` refuses all three shapes. Only
|
|
24
|
+
`akan verify` and `akan typecheck <app-or-lib>` typecheck tests (`bun:test` types included) and the `script/`
|
|
25
|
+
files nothing imports.
|
|
26
|
+
- Delete an export only tests reference together with its test (`akan quality scan` reports
|
|
27
|
+
`akan.global.test-only-export` in an app's `common/`, `webkit/`, `srvkit/`, `ui/`).
|
|
28
|
+
- Import `UserAgent` / `AdminAgent` from `lib/user/user.signal.spec.ts`, the one place agent types are re-typed.
|
|
29
|
+
|
|
30
|
+
**Verify endpoints with signal tests, not raw HTTP.** The canonical way to check a query/mutation/slice
|
|
31
|
+
contract is an in-memory signal test (`<model>.signal.test.ts`), using the test fetch harness
|
|
32
|
+
(`getOrSetupSignalTestFetch`) — it is fast, needs no running server, and exercises `fetch.*`, `view/edit/merge<Model>`,
|
|
33
|
+
and slice `init`/`list`/`insight` directly. Prefer it over `curl`: the dev gateway locale-prefixes routes (`/en/...`),
|
|
34
|
+
so hand-rolled HTTP calls against a raw path can redirect unexpectedly. See `akan test <app>`.
|