@akanjs/cli 3.1.1-rc.15 → 3.1.1-rc.17
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-gtwn7tmb.js → CodeAgent-fbcq8vks.js} +2 -2
- package/{CodeTui-v941fqdh.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-j1reb9p1.js → application.command-3a7q1hs2.js} +11 -10
- package/{applicationBuildRunner-w20x63mz.js → applicationBuildRunner-s7yt71j4.js} +6 -5
- package/buildBatch.proc.js +6 -6
- package/{cloud.command-zd2mfkm0.js → cloud.command-4vg0pcea.js} +15 -14
- package/cloud.script-nkmeyhet.js +25 -0
- package/{code.command-dyet4xn6.js → code.command-fbntb67p.js} +6 -6
- package/commandManifest.json +1 -1
- package/{context.command-79gxczm4.js → context.command-31rm54v0.js} +18 -17
- package/context.runner-w01a32ph.js +26 -0
- package/{guideline.command-xwkskvky.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-pqdz7rat.js → index-05nxx4m5.js} +952 -47
- package/{index-41d3zx66.js → index-0ht91675.js} +37 -59
- package/{index-cz9g85xh.js → index-0zwznvv1.js} +1 -1
- package/{index-7ktk2hnz.js → index-0zyatd10.js} +2 -2
- package/{index-8jb5ep2e.js → index-12kzwak1.js} +3 -3
- package/{index-yknrmkmt.js → index-1dhf8ymv.js} +2 -2
- package/{index-qmeh0s05.js → index-3gccwenr.js} +2 -2
- package/{index-hdzjaq7s.js → index-3txrjt6n.js} +2 -2
- package/{index-tzzs52h0.js → index-57q1ayd2.js} +18 -1240
- package/index-5kh9scvs.js +514 -0
- package/index-5n5hds19.js +1246 -0
- package/{index-pc9ps0hx.js → index-6269mf2s.js} +10 -9
- package/{index-1e2955yd.js → index-64g9fsjy.js} +43 -12
- package/index-7zeb5r1p.js +653 -0
- package/{index-kr62ph5a.js → index-8s8b4eba.js} +45 -4
- package/{index-wvvwdzfw.js → index-922k2zwq.js} +3 -3
- package/{index-brpk7gd8.js → index-9ndw5d8j.js} +7 -7
- package/{index-xeh7m2j5.js → index-et6ce601.js} +1 -1
- package/{index-jtydvvq7.js → index-f5adsa58.js} +4 -4
- package/index-fbewhg4g.js +590 -0
- package/{index-7abjzny1.js → index-hm7x0c11.js} +33 -37
- package/{index-rshwdv9w.js → index-hvv5rnaq.js} +2 -2
- package/index-jje9qzyq.js +27 -0
- package/index-js1gj6f6.js +410 -0
- package/{index-2qzzp0c9.js → index-kjrvwzav.js} +3 -3
- package/index-m5n3ka0p.js +18 -0
- package/index-m6r88hhr.js +3582 -0
- package/{index-4rwfh2de.js → index-mt0wa941.js} +4 -4
- package/{index-553xyb55.js → index-mwj9q2ya.js} +1 -1
- package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
- package/index-r2wedvqn.js +138 -0
- package/{index-ygy8c12j.js → index-rvynj5gz.js} +1 -1
- package/{index-nmy1rana.js → index-tdv66eah.js} +4 -4
- package/{index-8rvwgd1r.js → index-w134p86k.js} +1 -1
- package/{index-jjd97ya6.js → index-wfczhj1z.js} +14 -36
- package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
- package/{index-kbbyzs6j.js → index-x5ecanqh.js} +2 -2
- package/{index-ch1sv7ke.js → index-zre4m2ce.js} +9 -21
- package/index.js +23 -22
- package/{library.command-td8t85kb.js → library.command-sh70fyvy.js} +3 -3
- package/{localRegistry.command-jx9zkmxf.js → localRegistry.command-2nbyy84d.js} +17 -14
- package/{module.command-j70mqgpp.js → module.command-n0bmtzwy.js} +5 -5
- package/{package.command-1b1v6k5v.js → package.command-7h9r51bz.js} +3 -3
- package/package.json +2 -2
- package/{page.command-m31w2tsz.js → page.command-vjtpfbb1.js} +3 -3
- package/{pipeline.command-q7b8wy55.js → pipeline.command-c93se3ar.js} +2 -2
- package/{primitive.command-4zrbhkb9.js → primitive.command-a3075qp2.js} +6 -6
- package/{projectTypecheck-synx6qff.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-98n6zxg7.js → repair.command-tg57d8yt.js} +5 -5
- package/{scalar.command-rak5pjk3.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-ej0rk116.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-kdx3amrc.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-gffk9nj9.js → workflow.command-srhky88x.js} +47 -13
- package/workspace.command-9stchcd2.js +262 -0
- package/TunnelShare-26ty9skr.js +0 -14
- package/agent.command-h82gepwn.js +0 -25
- package/cloud.script-vdj8ymch.js +0 -24
- package/context.runner-ejag7mhr.js +0 -25
- package/guidelines/conventions/conventions.instruction.md +0 -617
- package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
- package/index-6pzt55w3.js +0 -279
- package/index-y5m4j2w6.js +0 -856
- package/index-zzvvc845.js +0 -74
- package/quality.command-cy0pgqjz.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-097hv6n1.js +0 -521
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Styling: Tailwind order, the semantic colour vocabulary, cn(), recipes and the app theme.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
- "{apps,libs}/**/*.css"
|
|
6
|
+
- "{apps,libs}/*/ui/Recipe/**"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Styling
|
|
10
|
+
|
|
11
|
+
- **Never hand-order Tailwind classes** — `nursery/useSortedClasses` sorts them, `cn()` arguments included, and its
|
|
12
|
+
output (`font-bold text-2xl text-foreground`) is correct.
|
|
13
|
+
- **Stay inside the color vocabulary** (`no-raw-palette-class`, `no-arbitrary-color`, `no-interpolated-arbitrary-class`,
|
|
14
|
+
`no-daisyui-legacy-class`, `no-inline-color`): no raw palette (`bg-blue-500`), arbitrary or interpolated color classes
|
|
15
|
+
(`bg-[#3b82f6]`), daisyUI classes or slots (`btn-primary`, `bg-base-100`), or color literals in `style={{}}` — they
|
|
16
|
+
render no CSS. Use semantic tokens (`bg-primary`, `text-foreground/70`); a legitimate fixed color takes
|
|
17
|
+
`// biome-ignore lint/plugin: <reason>`. Slot replacements, SVG / `el.style` warnings, legal values: `cssRule`.
|
|
18
|
+
|
|
19
|
+
- Static class strings stay plain. `cn` (from `akanjs/client`) only for a conditional or to merge an incoming
|
|
20
|
+
`className`, caller last: `cn("base", cond && "extra", className)` — the only combiner: no `clsx`, raw `twMerge`,
|
|
21
|
+
or object syntax.
|
|
22
|
+
- Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
|
|
23
|
+
- Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
|
|
24
|
+
`Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
|
|
25
|
+
name map (`BadgeVariants["variant"]`) moves to `webkit/`.
|
|
26
|
+
|
|
27
|
+
## Theme And Component Overrides
|
|
28
|
+
|
|
29
|
+
When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
|
|
30
|
+
|
|
31
|
+
- **Theme (`apps/<app>/page/styles.css`).** The app imports Tailwind and `akanjs/ui/styles.css`, then overrides semantic token *values* per theme under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, … each with a `-foreground` pair for text). The framework maps them to Tailwind color names, so `bg-primary` / `text-foreground` follow the `data-theme` attribute; corner rounding uses `--radius-box` / `--radius-field`. Fetch `get_guideline` with `cssRule` for the full token set before a deep theme pass.
|
|
32
|
+
- **Lib tokens (`libs/<lib>/ui/tokens.css`).** The one CSS file a lib owns: colors its own components pin that must **not** follow the theme — a vendor brand color, a fixed surface — declared once as plain `:root` custom properties and compiled automatically into every app whose pages reach the lib, ahead of the app's stylesheets, so nothing is imported by hand. Reference them as `bg-[var(--kakao)]`; never copy the block into each app. `@theme` extensions stay in the app stylesheet, because the color vocabulary is closed per stylesheet, and theme-following colors are the app's.
|
|
33
|
+
- **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
|
|
34
|
+
|
|
35
|
+
## Recipes
|
|
36
|
+
|
|
37
|
+
Framework UI recipes (Tailwind-variant look factories) import from `akanjs/ui`: `<name>(variants?, className?)`.
|
|
38
|
+
The second argument merges internally and takes an array too, so never wrap it in `cn()`:
|
|
39
|
+
`<name>({}, ["h-full", isWide && "w-full", className])`. Do not guess a recipe name or variant value, and do not open
|
|
40
|
+
the recipe file to consume one. Before inlining a repeated surface (card, box, tile): reuse a recipe, or add one as
|
|
41
|
+
`apps/<app>/ui/Recipe/<name>.ts`, one per file, re-exported from that folder's `index.ts` — never a near-duplicate.
|
|
42
|
+
Each app and lib lists its own recipes in `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` (`## Recipes In Scope`),
|
|
43
|
+
regenerated by `akan sync`. Full policy: the `recipeRule` guideline.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Tests: Bun's runner, one suite per module file, the signal test split and how to run them.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.{test,spec}.ts"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Test Code
|
|
8
|
+
|
|
9
|
+
- Bun's runner (`describe`, `expect`, `test` from `bun:test`); colocated `*.test.ts` / `*.spec.ts`; focused behavior
|
|
10
|
+
tests of public contracts and edge cases. A placeholder `it` with a descriptive title is the floor; a
|
|
11
|
+
security-relevant behaviour gets a real suite.
|
|
12
|
+
- Run `bun run akan test <pkg> [files]` from the root (`files`: comma-separated paths from the target or the root;
|
|
13
|
+
the only way a signal test runs), or `cd <pkg> && bun test --isolate ./<file>`. Plain `bun test` shares one global
|
|
14
|
+
object across files and fails dozens of tests from that pollution (`bunfig.toml` `[test] isolate` is not honored as
|
|
15
|
+
of Bun 1.4.4); from the repo root it breaks subprocess stdio pipes.
|
|
16
|
+
- Signal tests split in two: `<model>.signal.spec.ts` holds fixtures on `sampleOf(cnst.XInput)` with explicit
|
|
17
|
+
`Promise<cnst.X>` returns and **no assertions**; `<model>.signal.test.ts` holds `describe("<Model> Signal")`,
|
|
18
|
+
describe-scope `let` fixtures, one `beforeAll`, story-ordered `it`s, negatives via
|
|
19
|
+
`await expect(p).rejects.toThrow()`. Each `fetch.clone()` reports its own address (`198.18.x.y`), so an `ip` rate
|
|
20
|
+
limit counts it apart: clone once per simulated user, signup included (`clone({ clientIp })` names one).
|
|
21
|
+
- **One suite per module file**: `<model>.<role>.test.ts` beside the file it covers — never topic splits
|
|
22
|
+
(`chatMessage.trim.signal.test.ts`); add a `describe`. A suite spanning modules goes in `srvkit/`
|
|
23
|
+
(`libs/shared/srvkit/guards.signal.test.ts`), never the `lib/` root; `akan sync` refuses all three shapes. Only
|
|
24
|
+
`akan verify` and `akan typecheck <app-or-lib>` typecheck tests (`bun:test` types included) and the `script/`
|
|
25
|
+
files nothing imports.
|
|
26
|
+
- Delete an export only tests reference together with its test (`akan quality scan` reports
|
|
27
|
+
`akan.global.test-only-export` in an app's `common/`, `webkit/`, `srvkit/`, `ui/`).
|
|
28
|
+
- Import `UserAgent` / `AdminAgent` from `lib/user/user.signal.spec.ts`, the one place agent types are re-typed.
|
|
29
|
+
|
|
30
|
+
**Verify endpoints with signal tests, not raw HTTP.** The canonical way to check a query/mutation/slice
|
|
31
|
+
contract is an in-memory signal test (`<model>.signal.test.ts`), using the test fetch harness
|
|
32
|
+
(`getOrSetupSignalTestFetch`) — it is fast, needs no running server, and exercises `fetch.*`, `view/edit/merge<Model>`,
|
|
33
|
+
and slice `init`/`list`/`insight` directly. Prefer it over `curl`: the dev gateway locale-prefixes routes (`/en/...`),
|
|
34
|
+
so hand-rolled HTTP calls against a raw path can redirect unexpectedly. See `akan test <app>`.
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: TypeScript house style: classes, naming, file size, type shape, imports, comments.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.{ts,tsx}"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# TypeScript Style
|
|
8
|
+
|
|
9
|
+
## Coding Style
|
|
10
|
+
|
|
11
|
+
- Run a large unit of work through a class instance; prefer class or `static` methods over unrelated top-level
|
|
12
|
+
helpers, and keep a class file's functions and variables inside the class when they reasonably can be.
|
|
13
|
+
- `#private` over TypeScript `private`, except in the four lint-banned suffixes, which use `private`.
|
|
14
|
+
- `const` function expressions over `function` declarations, unless hoisting, overloads, generators, or a framework
|
|
15
|
+
convention make `function` the better fit.
|
|
16
|
+
- One class per file, named after it (`RouteClientBuilder.ts`, not `buildRouteClient.ts`). Migrate callers off an
|
|
17
|
+
exported function that only instantiates a class and calls one method.
|
|
18
|
+
- TypeScript filenames are camelCase, except React component and convention files.
|
|
19
|
+
- One-off `className` strings stay inline; extract a constant only when reused, conditionally composed, or too large
|
|
20
|
+
to read in JSX.
|
|
21
|
+
|
|
22
|
+
### File Size And Duplication
|
|
23
|
+
|
|
24
|
+
- Keep files small (house median well under 50 lines); split a component before ~150 lines rather than adding
|
|
25
|
+
section comments.
|
|
26
|
+
- Ship every scaffold file even when empty — `export class XInternal extends internal(srv.x, () => ({})) {}`, empty
|
|
27
|
+
dictionary stages, the `// state` / `// action` markers. They mark where things go.
|
|
28
|
+
- Never add a sibling helper file inside `lib/<model>/`; helpers go to `common/`, `webkit/`, `srvkit/`, or `ui/`.
|
|
29
|
+
- Prefer duplication to premature abstraction at the leaf: near-identical sibling modules and per-vendor pages are
|
|
30
|
+
copied with changed literals, not parameterised; share enums by import only.
|
|
31
|
+
|
|
32
|
+
### TypeScript Shape
|
|
33
|
+
|
|
34
|
+
- `interface` for object shapes, `type` only for unions and aliases.
|
|
35
|
+
- `interface <ComponentName>Props` sits directly above the component (no blank line), `className?: string` first,
|
|
36
|
+
named for the component (`CardProps`), never the model; exported only when a sibling imports it.
|
|
37
|
+
- No non-null assertions — narrow with `?.`, an early return, or a type predicate
|
|
38
|
+
(`.filter((id): id is string => !!id)`). Escape with `as unknown as T`, never `as any`.
|
|
39
|
+
- Never annotate a component's return type; annotate a helper only for a union, tuple, or type predicate.
|
|
40
|
+
- `as const` on every `enumOf(...)` array (even though `enumOf` infers its literals, so a typo already fails to
|
|
41
|
+
compile), `via(Model, [...] as const, …)` Light tuple, and module-scope lookup map; never the `enum` keyword.
|
|
42
|
+
- Async functions carry no `Async` suffix.
|
|
43
|
+
|
|
44
|
+
- **`#private` is banned in exactly `*.constant.ts`, `*.document.ts`, `*.service.ts`, `*.store.ts`**
|
|
45
|
+
(`no-js-private-class-method`, by path, so it stays the house style everywhere else, `srvkit/` and `adapt()` classes
|
|
46
|
+
included).
|
|
47
|
+
|
|
48
|
+
## TypeScript And Imports
|
|
49
|
+
|
|
50
|
+
- Bun and ESM per the root `tsconfig.json`. Path aliases across packages: `akanjs/*`, `@apps/*`, `@libs/*`,
|
|
51
|
+
`@contract/*`, respecting the `/client` and `/server` entrypoints. Let Biome organize imports.
|
|
52
|
+
- Backend `.ts` namespaces the generated barrels — `import * as cnst from "../cnst"`, `* as db`, `* as srv` —
|
|
53
|
+
with `import type * as srv` in services (keeps the runtime graph lazy) and a value import in signals.
|
|
54
|
+
- `.tsx` uses one flat named import from the package client path
|
|
55
|
+
(`import { cnst, fetch, st, Ticket, usePage } from "@apps/<app>/client"`), never a relative `../` import.
|
|
56
|
+
|
|
57
|
+
- Biome formats: 2-space indent, 120 columns, double quotes.
|
|
58
|
+
|
|
59
|
+
## Naming And Language
|
|
60
|
+
|
|
61
|
+
- Component exports are role names (`Card`, `General`, `Preview`, `Admin`, `Remove`) — the namespace carries the
|
|
62
|
+
model (`<Floor.Unit.Card>`, never `FloorCard`). `Util` exports are the endpoint verb minus the noun (`Serve`,
|
|
63
|
+
`Refund`).
|
|
64
|
+
- Layer the verbs: the document chain method drops the model (`sign()`), the service keeps the bare verb, signal,
|
|
65
|
+
store and dictionary re-add it (`signScContract`) — clear of generated CRUD, and `st.do.X` reads like `fetch.X`.
|
|
66
|
+
- Slice and filter names are prepositional (`inOrg`, `byStatuses`, `ofPortfolio`), never `getXInY` or `listX`.
|
|
67
|
+
- Handlers are `onX` props taking inline arrows, never an extracted `handleX`.
|
|
68
|
+
- Booleans `is*` / `has*` / `can*` / `show*` / `disable*`; counters `*Num`; indices `idx`; collections `*List` or
|
|
69
|
+
plural; no `SCREAMING_SNAKE` — module-scope tables are camelCase + `as const`.
|
|
70
|
+
- Keep existing domain vocabulary and its typos — transliterated terms and misspellings in use are load-bearing, and
|
|
71
|
+
renaming silently breaks callers that match on the name.
|
|
72
|
+
- Identifiers, type names, endpoint names, and log messages are **English**. Everything a user reads goes through
|
|
73
|
+
`l("model.field")` or `l.trans({ en, ko })` — never a hard-coded JSX string, never `window.alert`.
|
|
74
|
+
- Dictionary entries are `[en, ko]` pairs, nearly every label with a `.desc([en, ko])` even when repetitive; English
|
|
75
|
+
in Title Case, Korean the plain domain term, `.error()` Korean ending in `다.`.
|
|
76
|
+
|
|
77
|
+
## Comments
|
|
78
|
+
|
|
79
|
+
Do not narrate code. Do document the thing the code cannot say. Both halves are the rule.
|
|
80
|
+
|
|
81
|
+
- Never restate the identifier, the signature, or the control flow; prefer names and structure. No JSDoc, section
|
|
82
|
+
banners, or "why/how" comments on ordinary logic.
|
|
83
|
+
- Density tracks the layer: pages carry none, product `lib/` and `ui/` stay under 1 %, `srvkit/` adapters and
|
|
84
|
+
`guards.ts` (what would leak without each guard) carry what the external constraints require. `akan quality scan`
|
|
85
|
+
reports a `lib/` module or `ui/` entry past 1 % once it holds five comment lines (`akan.comment.density`).
|
|
86
|
+
- Mark a retired field or function `/** @deprecated <what to use instead> */` on its declaration, never a
|
|
87
|
+
`// deprecated` comment — only the tag strikes through every use site.
|
|
88
|
+
- Warranted for: a vendor or protocol quirk; an infrastructure constraint; a library gotcha; security reasoning; why
|
|
89
|
+
an arbitrary-looking rule is correct; a math derivation; a domain field's business meaning; a state transition above
|
|
90
|
+
a document chain method; why an obvious alternative was rejected.
|
|
91
|
+
- Markers: `TODO` (tracked unfinished work), `FIXME` (known broken), `XXX` (a hazard a reader must not miss), `//!`
|
|
92
|
+
(disabled or must-fix — server, `srvkit/`, CLI only), `//?` (an aside), `//*` (a design note), and a deletion
|
|
93
|
+
caution saying why removing a line would break something non-obvious.
|
|
94
|
+
- One short line each. Every suppression carries a reason (`// biome-ignore lint/<rule>: <why>`), never a bare
|
|
95
|
+
disable block. Match the nearby density.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: React components: the five roles, forms, loading states, hooks and the lint rules on .tsx files.
|
|
3
|
+
paths:
|
|
4
|
+
- "{apps,libs}/**/*.tsx"
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# React Components
|
|
8
|
+
|
|
9
|
+
A screen that grows keeps five roles: an **assembly** `Zone` that reads the store and places pieces, with no
|
|
10
|
+
branching; **pieces** (`Unit`, `View`, small components) that only display, server-rendered where they can be; a
|
|
11
|
+
**kind table** `{ [kind in cnst.X["value"]]: Component }` instead of mode flags, so a new enum value without an entry
|
|
12
|
+
is a type error — each entry is a component of the module that owns that kind's data (a tab of video scenes is
|
|
13
|
+
`VideoScene.Zone.<X>`), so a screen spanning several models adds no folder; an **interaction hook**
|
|
14
|
+
`webkit/use<X>.tsx` over a pure, tested `common/<x>.ts` class for drag, selection and keys, handed its writes as
|
|
15
|
+
arguments; and **writes** as one-line store actions, one endpoint each. Kinds a screen invents rather than a model
|
|
16
|
+
(canvas node kinds) key the table by an `as const` union in `common/`. A screen choosing along two axes (what to
|
|
17
|
+
pick, and where the pick lands) keeps two tables, the second mapping each purpose to its one commit action. State
|
|
18
|
+
several components or an agent tool read stays in the store, where `st.tool` sees it; the hook keeps only gesture
|
|
19
|
+
state. Reach for the path, not the nearest file:
|
|
20
|
+
|
|
21
|
+
| Task | Path |
|
|
22
|
+
|---|---|
|
|
23
|
+
| A state-changing act, or chained writes in an action or handler | `akan workflow plan add-mutation --app <app> --module <m> --mutation <verbModel> --guard <Guard>[,…] [--with <ref>.<method>] [--after <ref>.<method>]` |
|
|
24
|
+
| Event, keyboard, pointer or layout logic growing in a component | `akan workflow plan create-interaction --app <app> --interaction <name>` |
|
|
25
|
+
| A missing `View` / `Unit` / `Template` / `Zone` / `Util` | `akan workflow plan create-ui --app <app> --module <m> --surface <surface>` |
|
|
26
|
+
|
|
27
|
+
- `export const X = ({ … }: XProps) => { return (…); };` — `export default` only for pages, layouts, `lazy()`
|
|
28
|
+
targets. No `React.FC`, `defaultProps`, `PropsWithChildren`; defaults in the destructuring, `children: ReactNode`.
|
|
29
|
+
- `cond ? <X/> : null`, never `{cond && <X/>}` (renders `"false"` in a `className`); early `return null` only for
|
|
30
|
+
guard clauses.
|
|
31
|
+
- Never hand-roll loading, empty, or list states: `Load.Units` / `Load.View` / `Load.Edit` (`renderItem`,
|
|
32
|
+
`renderList`, `renderView`, `renderEmpty`), `<Empty />`, `Model.New` / `Model.Edit` / `Model.SureToRemove`.
|
|
33
|
+
Otherwise `<Load.Stream of={promise} fallback={…}>{(value) => …}</Load.Stream>` awaits one promise behind its own
|
|
34
|
+
boundary (a resolved value renders in the shell).
|
|
35
|
+
- Avoid hooks. `useState` only for modal-open, tab, draft-input, and drag state, never server data; `useEffect` only
|
|
36
|
+
for a genuine effect (subscribe-with-cleanup, one-shot init); `Tab` over a mode switch; zero `useState` in a
|
|
37
|
+
`.Template.tsx`.
|
|
38
|
+
- Forms are store-driven: `value={xForm.field}`, `onChange={st.do.setFieldOnX}` **by reference** — that emits the
|
|
39
|
+
`data-akan-action` / `data-akan-state` the in-page agent, E2E selectors and browser agents read. Always `Field.*`,
|
|
40
|
+
never a bare `<input>` for a model field; nested rows use `st.do.writeOnX("payments.3.name", v)` and the generated
|
|
41
|
+
`add<Field>OnX` / `sub<Field>OnX`. Never hand-write `data-akan-*`.
|
|
42
|
+
- Read with `st.use.*`, write with `st.do.*`; client components never call `fetch.*`.
|
|
43
|
+
- A raw `<button>` defaults to `type="submit"`, so a click inside any `<form>` also submits it. Write
|
|
44
|
+
`type="button"` on every raw `<button>` that does not submit; `<Button>` from `akanjs/ui` already defaults to it.
|
|
45
|
+
- **Never persist form values yourself** — `Load.Edit`, `Model.EditModal` and `Model.New` save and recover the whole
|
|
46
|
+
`<model>Form` per record or route and user (`draft={false}` off, `draft="<scope>"` to name it; secret and hidden
|
|
47
|
+
values never saved; field `cache` / `cacheKey` props are deprecated no-ops — `modelStore`).
|
|
48
|
+
- `<Link>` from `akanjs/ui` for internal navigation; `<a>` only for `mailto:` and external links. A `<Link>` handed
|
|
49
|
+
an absolute URL (any scheme, any case) or a `//host` path passes it through untouched and opens it outside the app;
|
|
50
|
+
only an app path gets the locale and basePath. `Href.isExternal(href)` from `akanjs/client` is that test.
|
|
51
|
+
|
|
52
|
+
## Lint Rules On Components
|
|
53
|
+
|
|
54
|
+
- **Never type a `*.Util.tsx` / `*.Zone.tsx` prop as a `cnst` model** (`no-model-type-in-util-zone`) — the server would
|
|
55
|
+
hand a class instance to a client component; take `bannerId: string` and read the model from the store. Exempt:
|
|
56
|
+
`cnst.<Enum>["value"]`, a `ClientInit` / `ClientView` / `ClientEdit` / `ModelsProps<…>` type argument, a
|
|
57
|
+
function-typed prop, a `cnst` type that never leaves the file; `ModelProps<…>` and other indexed accesses stay
|
|
58
|
+
flagged.
|
|
59
|
+
- **Never wrap a form setter in a pass-through arrow** (`no-unpublished-form-setter`) —
|
|
60
|
+
`(v) => st.do.setTypeOnTicket(v)` emits no `data-akan-action` and publishes no agent tool. A wrapper that transforms,
|
|
61
|
+
adds a statement, or calls `writeOnX` is legal; publish it with an explicit `st.tool`.
|
|
62
|
+
- **Never call a hook conditionally** — a skipped call shifts every later hook, and production React crashes
|
|
63
|
+
elsewhere. Biome's `useHookAtTopLevel` checks plain hooks (`useState`, `useEffect`), early returns included.
|
|
64
|
+
`no-conditional-st-hook` checks the `st` hooks it cannot see — `st.use.*`, `st.slice.<x>.use.*`, `st.sel`, `st.ref`,
|
|
65
|
+
`st.tool(…).exec()` / `.card()`, `st.useState(…).init()`, `st.expose(…).value()` — behind `||` / `&&` / `??`, in a
|
|
66
|
+
ternary, an `if`, a `switch`, a loop, a `catch`, a default value, an optional call or a callback; not after an early
|
|
67
|
+
`return` or inside a helper the component calls. Read each into its own `const` at the top, then combine.
|
|
68
|
+
- **No async component under `ui/`** (`no-async-component-in-ui`) — React has no async client component. Await in the
|
|
69
|
+
page, or hand an unawaited `fetch.*` field to a `Zone` / `<Load.Stream of={…}>`, and take the data as a prop. An async
|
|
70
|
+
handler in a synchronous component and `lazy(async () => import(…))` are untouched.
|
|
71
|
+
- **Never call `fetch.init<Model><Suffix>` / `fetch.get<Model>Init<Suffix>` from a client file** (`"use client"` or
|
|
72
|
+
`*.store.ts`; `no-init-fetch-in-client`) — it is the hydration snapshot. Load it in the page and pass `init` down;
|
|
73
|
+
reload with `st.do.init<Model><Suffix>()`.
|
|
74
|
+
- `noArrayIndexKey` and `useExhaustiveDependencies` are **off** on purpose — `key={idx}` for embedded scalars and
|
|
75
|
+
short dependency arrays are intentional.
|
|
@@ -580,7 +580,7 @@ element, beside the tools it explains. Exactly these texts reach every client: `
|
|
|
580
580
|
|
|
581
581
|
## Verifying An App
|
|
582
582
|
|
|
583
|
-
- `akan
|
|
583
|
+
- `akan verify <app>`, then the boot log above.
|
|
584
584
|
- The lib's own suites run wherever it is mounted: the OAuth signal test (metadata, registration, both `authorize`
|
|
585
585
|
redirects, code exchange, `/mcp` with the minted token and the refusal of a first-party or forged one, refresh
|
|
586
586
|
rotation) and the refresh-session and option unit tests.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# Workspace Recipes — Worked Examples And The Auto-Generated API
|
|
2
2
|
|
|
3
3
|
Step-by-step recipes for the most frequent Akan.js changes, and the reference of what `akan sync` generates for
|
|
4
|
-
you at each layer. `
|
|
4
|
+
you at each layer. The `conventions` guideline carries the rules; this is the worked code behind them.
|
|
5
5
|
Read the whole recipe before editing, and change only the sections it names — do not rewrite a file.
|
|
6
6
|
|
|
7
7
|
## Workflow Recipes
|
|
@@ -394,7 +394,7 @@ export const Insight = ({ sliceName }: { sliceName: string }) => {
|
|
|
394
394
|
A route file used to be a default function beside named exports (`pageConfig`, `head`, `generateHead`, `Loading`,
|
|
395
395
|
`fonts`, …). It is now one chain, and the chain is also what publishes a screen to agents. The legacy shape still
|
|
396
396
|
loads and logs one warning per file at boot (`… uses the legacy route shape …`); migrate file by file, then run
|
|
397
|
-
`bun run akan
|
|
397
|
+
`bun run akan verify <app>`.
|
|
398
398
|
|
|
399
399
|
```tsx
|
|
400
400
|
// before — page/(user)/project/[projectId]/_index.tsx
|
|
@@ -514,7 +514,7 @@ surface (`akan context`, the MCP tools, `akan guideline show`) is what feeds a c
|
|
|
514
514
|
|
|
515
515
|
`~/.akan/config.json` keeps an `llm` entry if it had one. It is ignored; delete it, because it holds an API key.
|
|
516
516
|
|
|
517
|
-
Then: `bun run akan
|
|
517
|
+
Then: `bun run akan verify <app>` and one agent turn in the browser to confirm the
|
|
518
518
|
provider answers.
|
|
519
519
|
|
|
520
520
|
### Data Flow Summary
|
|
@@ -1,14 +1,14 @@
|
|
|
1
1
|
// @bun
|
|
2
2
|
import {
|
|
3
|
-
ApplicationBuildReporter,
|
|
4
3
|
HmrWatcher,
|
|
5
|
-
WatchRootResolver
|
|
6
|
-
|
|
4
|
+
WatchRootResolver,
|
|
5
|
+
ApplicationBuildReporter
|
|
6
|
+
} from "./index-p6x5b7hr.js";
|
|
7
7
|
import {
|
|
8
8
|
CodegenLock,
|
|
9
9
|
WorkspaceExecutor,
|
|
10
10
|
AppExecutor
|
|
11
|
-
} from "./index-
|
|
11
|
+
} from "./index-64g9fsjy.js";
|
|
12
12
|
import"./index-52w0fvh8.js";
|
|
13
13
|
import {
|
|
14
14
|
GraphClientEntryDiscovery,
|
|
@@ -19,10 +19,10 @@ import {
|
|
|
19
19
|
DevChangePlanner,
|
|
20
20
|
DevGeneratedIndexSync,
|
|
21
21
|
SsrDevBundler
|
|
22
|
-
} from "./index-
|
|
22
|
+
} from "./index-12kzwak1.js";
|
|
23
23
|
import {
|
|
24
24
|
ServerGraphFile
|
|
25
|
-
} from "./index-
|
|
25
|
+
} from "./index-0zwznvv1.js";
|
|
26
26
|
import {
|
|
27
27
|
prepareDevWatchBatch
|
|
28
28
|
} from "./index-a5vmm6x4.js";
|