@akanjs/cli 3.3.0-rc.10 → 3.3.0-rc.12
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 +2 -2
- package/guidelines/akanApi/akanApi.instruction.md +10 -0
- package/guidelines/conventions/rules/page.md +1 -3
- package/guidelines/conventions/rules/server.md +21 -81
- package/guidelines/conventions/rules/ssr.md +4 -25
- package/guidelines/conventions/rules/style.md +9 -32
- package/guidelines/cssRule/cssRule.instruction.md +11 -4
- package/guidelines/recipeRule/recipeRule.instruction.md +3 -3
- package/guidelines/ssrRule/ssrRule.instruction.md +3 -0
- package/guidelines/transportRule/transportRule.instruction.md +4 -0
- package/package.json +2 -2
- package/skills/akan-err/SKILL.md +11 -2
- package/skills/akan-page/SKILL.md +4 -14
package/.build-stamp
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
fe2b1ec6e46be41a3fcddc26ae1d606607135418af33f89dec14b82ce61a6fc9
|
|
2
|
+
94aaa09f-82a1-4735-9985-542e6b279b8b
|
|
@@ -21,6 +21,16 @@ import { BookApi } from "@apps/<app>/srvkit"; // a layer barrel: common, srvkit,
|
|
|
21
21
|
import { signedIn } from "@libs/shared/webkit"; // a workspace created with --libs true
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
+
What these subpaths hold:
|
|
25
|
+
|
|
26
|
+
- `akanjs/dictionary` — locales, translations and the dictionaries behind labels, descriptions and `Err` keys.
|
|
27
|
+
- `akanjs/document` — database documents, filters, query builders, full-text search and persistence.
|
|
28
|
+
- `akanjs/service` — services, adapters, dependency injection and the business-logic runtime.
|
|
29
|
+
- `akanjs/store` — domain state, actions and the in-page agent's `st.tool` / `st.use` surface.
|
|
30
|
+
- `akanjs/client/native` — the native bridge and the built-in plugins of iOS, Android and desktop apps.
|
|
31
|
+
- `akanjs/native/desktop` — what an app's or a lib's own native plugin builds its desktop part from.
|
|
32
|
+
- `akanjs/test` — signal-test setup, MCP catalogue checks and sample data (`sampleOf`).
|
|
33
|
+
|
|
24
34
|
## Routes (`page/`)
|
|
25
35
|
|
|
26
36
|
### `page` · `akanjs/client`
|
|
@@ -15,7 +15,7 @@ apps, heads, CSR root layouts, lib pages, `devOnly`: `pageRule`.
|
|
|
15
15
|
- **A route file exports one chain** — `page()`, `layout()` in a `_layout.tsx`, `rootLayout()` in a root
|
|
16
16
|
`_layout.tsx` — and every setting is a stage (`.param`, `.search`, `.config`, `.guard`, `.head`, `.loading`;
|
|
17
17
|
`.notFound` / `.error` on layouts; `.fonts` / `.theme` / `.manifest` / … on the root; `.prompt` / `.app` on a page).
|
|
18
|
-
A named export beside it fails the build.
|
|
18
|
+
A named export beside it fails the build, and the legacy `export default async function Page` is never written anew.
|
|
19
19
|
- **Name every `[x]` segment with `.param("x", Type)`** and read query keys only via `.search("k", Type)`; a layout
|
|
20
20
|
may declare a subset. `akan sync` reads the names off the `export default` chain itself, so it refuses a chain bound
|
|
21
21
|
to a variable first and a `[x]` folder whose page declares no `.param("x")`. `lang` is never declared — every stage
|
|
@@ -24,8 +24,6 @@ apps, heads, CSR root layouts, lib pages, `devOnly`: `pageRule`.
|
|
|
24
24
|
and a canonical link / `og:url` comes only from the page's own `.head()`.
|
|
25
25
|
- In a CSR bundle a root layout's own markup is hidden: what a person must see from it renders through
|
|
26
26
|
`createPortal(…, document.body)`.
|
|
27
|
-
- `_overrides.tsx` is one `export default override({ Slot: AppComponent })` (`akanjs/ui`), no logic, no
|
|
28
|
-
`"use client"`. The legacy `export default async function Page` shape is never written anew.
|
|
29
27
|
- `libs/<lib>/page` reaches an app through `syncPageLibs`, linked into the generated `page/(libs)/(<lib>)`; edit the
|
|
30
28
|
lib source, never the link. `.config({ devOnly: true })` (a literal) keeps a route out of `akan build`.
|
|
31
29
|
- `.render()` gets the declared args flat and typed (no `PageProps`, no `loader=` prop). Order: `usePage()`, fetch,
|
|
@@ -7,84 +7,24 @@ paths:
|
|
|
7
7
|
|
|
8
8
|
# Services And Signals
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- **
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
- **
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
whose slice mounts the verb. `fetch.*` is one namespace across modules and a pubsub or message is routed by its bare
|
|
32
|
-
name, so the server refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
|
|
33
|
-
- **Queries (`queryRule`)**: the root slice takes `queryKey` + `args`, never a raw query. A slice `exec` returns a
|
|
34
|
-
`query<Filter>(…)` descriptor (never a `list<Filter>` array) and is paged through `initX(…, { sort, page, limit })`.
|
|
35
|
-
A projection is bare on the facade (`pickById(id, { secret: true })`), under `select` on a filter accessor — the
|
|
36
|
-
only way to read a `field.secret`. More rows: `loadMoreOf<Model>()` / `hasMoreOf<Model>`, never
|
|
37
|
-
`count > page * limit`. A filter's `remove*` / `update*` are hookless (no cascade). No value is `q.empty`, never
|
|
38
|
-
`q.missing`.
|
|
39
|
-
- **Search**: `q.search(text, { prefix: true })` in a filter, at an AND position, over `text`-role fields; a search
|
|
40
|
-
*slice* only on data safe to enumerate; blank input matches nothing — never a passthrough.
|
|
41
|
-
- **`cascade` names a direction; the wrong one loses data**: `removeRef` on the owner's relation, `removeWith` on
|
|
42
|
-
the child's reference to its owner. A query-level removal runs no cascade.
|
|
43
|
-
- **MCP (`mcpRule`)**: `/mcp` publishes every guarded endpoint by default; `mcp: false` (or a `slice()` `mcp` map
|
|
44
|
-
mirroring `guards`) is curation, not authorization. `guards: [Every, Person]` reserves an act for a person;
|
|
45
|
-
`.with(AgentCall)` narrows an agent's call. Settings are `option.setMcp` in `lib/option.ts`; `JWT_SECRET` is
|
|
46
|
-
required outside `local`. Never make a refusal message more helpful. Every entry needs a `.desc()`; brief a
|
|
47
|
-
screen with `page().prompt(name, description)`, and publish one component a host draws with
|
|
48
|
-
`page().app(name, description, load)` — a read-only tool whose `load` may only query.
|
|
49
|
-
- **In-page agent (`agentRule`)**: mount `<Agent.Chat />` once in a layout; it never executes tools and refuses
|
|
50
|
-
every call until `option.setAgentAccess(<guard>)`, which decides who — what a turn may ask is
|
|
51
|
-
`option.setAgentRequestPolicy`, size-capped until one is set; the LLM is `option.setLlm({ apiKey, model, host })`, never env.
|
|
52
|
-
The surface is what components declare — `st.tool(…).exec(fn)` beside its control, `st.use` / `st.sel` /
|
|
53
|
-
`st.ref` keys — never a store class. `st.use.x({ agent: false })` hides a key; its model's `hidden` / `secret` /
|
|
54
|
-
`visual` fields are stripped at read. A tool value is capped at 20,000 characters. Route guidance is
|
|
55
|
-
`<Agent.Guide instructions="…" />`; model-facing text is English.
|
|
56
|
-
|
|
57
|
-
## Injection And Adapters
|
|
58
|
-
|
|
59
|
-
- A field named `<refName>Service` / `<refName>Signal` resolves to that registration — the suffix is required
|
|
60
|
-
(`pkgs/akanjs/service/injectInfo.ts`). In a service: `service<srv.XService>()` · `plug(AdapterClass)` /
|
|
61
|
-
`plug(StorageAdaptorRole)` · `use<T>()` only for a legacy `option.ts` singleton · `env(...)` for config.
|
|
62
|
-
- `memory(...)` takes a scalar or model class (`memory(Map, { of: CallStateInput })`); never hand-encode JSON into a
|
|
63
|
-
`String` memory.
|
|
64
|
-
- A file your own code stored through `plug(StorageAdaptorRole)` has its disk path at
|
|
65
|
-
`storage.resolveLocalPath?.(path, access)` (`fieldRule`): `null` means refused (answer 404, never fall back to
|
|
66
|
-
`readData()`), `undefined` means the adaptor keeps no local files, and a key that comes from a request passes
|
|
67
|
-
`access: "public"`. A `File` field is not one: `libs/shared` stores it through its own `StorageApi`.
|
|
68
|
-
- **A new adapter is an `adapt()` singleton in `srvkit/`**, injected with `plug(TheClass)`, key `as const`. Never
|
|
69
|
-
register it in `lib/option.ts` (it self-registers); never construct a `Logger` in it (`this.logger` exists);
|
|
70
|
-
lifecycle work in `override async onInit()`. A per-use value object is a plain class. Legacy
|
|
71
|
-
`constructor(options)` adapters migrate only when already being changed. Example and adapter conventions (one
|
|
72
|
-
`#api<T>` with a timeout, pagination, secrets, parameter shapes): `workspaceRecipes` Recipe 2.
|
|
73
|
-
|
|
74
|
-
## Error Placement
|
|
75
|
-
|
|
76
|
-
- State-machine preconditions throw in `document.ts`, cross-document rules in `service.ts`, request policy in
|
|
77
|
-
`signal.ts` guards. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no Result types.
|
|
78
|
-
- A `pick` or generated `get<Model>` that finds no live row answers 404 `base.error.documentNotFound` by itself
|
|
79
|
-
(`NoDocumentError`); load with a nullable `load<Model>` and throw `Err.NotFound` only to say more than that.
|
|
80
|
-
- An endpoint names the errors it throws on purpose — `errors: { 409: ["ticket.error.locked"] }` in its signal
|
|
81
|
-
option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
|
|
82
|
-
of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
|
|
83
|
-
`Err.is(error, "ticket.error.locked")`.
|
|
84
|
-
- An `srvkit/` adapter belongs to no module: its keys go in the app's or lib's own service dictionary,
|
|
85
|
-
`lib/_<name>/<name>.dictionary.ts`, thrown as `new Err("<name>.error.<key>")` with `Err` from `"../lib/dict"`.
|
|
86
|
-
- `try/catch` turns an exception into a decision: guards → `logger.warn` → `false`; adapters → `logger.error` →
|
|
87
|
-
`null`; UI `try/finally` resets a spinner. A bodyless `catch {}` needs a one-line reason.
|
|
88
|
-
- Store actions do not `try/catch` (the framework toasts the `Err`); one no screen waits on (a token refresh) is
|
|
89
|
-
listed in the store's `static silent`, rejecting untoasted to the caller that handles it. Client validation is
|
|
90
|
-
`msg.error("<key>")` plus an early return, never a throw.
|
|
10
|
+
`serve(...)` services hold business operations. Signals hold contracts: `internal(...)` for init, interval, cron and
|
|
11
|
+
queue jobs, `slice(...)` for data views feeding stores and zones, `endpoint(...)` for queries and mutations. Guards
|
|
12
|
+
are the `auth` rule, queries and cascades the `module` rule. How-to and detail: the `akan-service`, `akan-transport`,
|
|
13
|
+
`akan-query`, `akan-mcp`, `akan-agent` and `akan-err` skills.
|
|
14
|
+
|
|
15
|
+
- **External APIs and infrastructure go through a `srvkit/` adapter**, never a vendor client in domain logic: an
|
|
16
|
+
`adapt()` singleton injected with `plug(TheClass)`. It registers itself, so it never goes in `lib/option.ts`.
|
|
17
|
+
- **An injected field is named `<refName>Service` / `<refName>Signal`** — the suffix is required
|
|
18
|
+
(`pkgs/akanjs/service/injectInfo.ts`).
|
|
19
|
+
- **`fetch.*` is one namespace across modules and a pubsub or message is routed by its bare name**, so the server
|
|
20
|
+
refuses to boot on two claims of one name (`[DI:fetch]`, `[DI:socket]`), naming both.
|
|
21
|
+
- **On the wire**: `.body()` / `.param()` take `Int` / `Float`, never `Number`; bytes are `Binary`, never `Any`;
|
|
22
|
+
`Upload` only in a `fileUpload: true` mutation. Without `{ timeout }` the client quits at 30 s and the handler runs
|
|
23
|
+
on. A remote `Err` from `fetch.clone({ origin })` is rethrown as is, never wrapped or re-keyed.
|
|
24
|
+
- **MCP**: `/mcp` publishes every guarded endpoint by default; `mcp: false` is curation, not authorization. Never
|
|
25
|
+
make a refusal message more helpful.
|
|
26
|
+
- **In-page agent**: `<Agent.Chat />` refuses every call until `option.setAgentAccess(<guard>)`; the LLM is
|
|
27
|
+
`option.setLlm({ apiKey, model, host })`, never env; the surface is what components declare, never a store class.
|
|
28
|
+
- **Errors**: a state-machine precondition throws in `document.ts`, a cross-document rule in `service.ts`, request
|
|
29
|
+
policy in a `signal.ts` guard. Best-effort code returns a sentinel (`null`, `undefined`, `[0, 0]`, `{}`) — no
|
|
30
|
+
Result types. `try/catch` turns an exception into a decision, and a bodyless `catch {}` needs a one-line reason.
|
|
@@ -7,16 +7,10 @@ paths:
|
|
|
7
7
|
|
|
8
8
|
# Client/Server Boundary And SSR
|
|
9
9
|
|
|
10
|
-
## Client / Server Boundaries
|
|
11
|
-
|
|
12
10
|
- `"use client";` tops client component files. It is mechanical by role: `Template`, `Zone`, `Util` always carry it
|
|
13
11
|
on line 1; `Unit`, `View` never do. `usePage()` is legal in server files.
|
|
14
12
|
- A `"use client"` file re-exports by name (`export { A, B } from "./x"`), never `export *` — the server knows a
|
|
15
13
|
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
14
|
- **Never import across the client/server boundary** (`apps/**`, `libs/**`; `no-import-server-in-client`,
|
|
21
15
|
`no-import-client-in-server`). Client files (`ui/`, `webkit/`, `page/`, `*.store.ts`, every `.tsx`) never import a
|
|
22
16
|
`*.document|dictionary|service|signal.ts`, `srvkit/`, a package `server` entrypoint, or the `db` / `srv` / `sig` /
|
|
@@ -25,22 +19,7 @@ paths:
|
|
|
25
19
|
`common/` and `*.constant.ts` obey both. `import type` is legal everywhere; a mixed value-and-type import is not.
|
|
26
20
|
- **Server-component discipline** on `page/**`, `*.Unit.tsx`, `*.View.tsx` (`no-import-client-functions`,
|
|
27
21
|
`no-use-client-in-server`, `non-scalar-props-restricted`).
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
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>`; ⑧ gate auth with
|
|
45
|
-
`.guard(() => signedIn())` on `_layout.tsx`, not in a body after I/O (the `page` rule); ⑨ CSS (`data-*` +
|
|
46
|
-
`group-data-[…]`, `<details>`) over client state for visibility; ⑩ heavy islands behind `index_.tsx` + `lazy()`.
|
|
22
|
+
- **Server is the default.** `akan quality ssr` prints each app's and lib's server share: 50% is the floor, and a
|
|
23
|
+
falling share is a regression to justify in the PR or revert. Why, what earns the directive and the ten-step
|
|
24
|
+
playbook (wrap the interaction, split compound components, fetch in the route, hand promises across, …): `ssrRule`
|
|
25
|
+
in the `akan-ui` skill.
|
|
@@ -8,38 +8,15 @@ paths:
|
|
|
8
8
|
|
|
9
9
|
# Styling
|
|
10
10
|
|
|
11
|
+
The theme, lib tokens, `cn`, recipes and component overrides: `cssRule`, `recipeRule` and `componentRule` in the
|
|
12
|
+
`akan-ui` skill.
|
|
13
|
+
|
|
11
14
|
- **Never hand-order Tailwind classes** — `nursery/useSortedClasses` sorts them, `cn()` arguments included, and its
|
|
12
15
|
output (`font-bold text-2xl text-foreground`) is correct.
|
|
13
16
|
- **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
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
- Static class strings stay plain. `cn` (from `akanjs/client`) only for a conditional or to merge an incoming
|
|
22
|
-
`className`, caller last: `cn("base", cond && "extra", className)` — the only combiner: no `clsx`, raw `twMerge`,
|
|
23
|
-
or object syntax.
|
|
24
|
-
- Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
|
|
25
|
-
- Enum→class lookups: a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
|
|
26
|
-
`Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
|
|
27
|
-
name map (`BadgeVariants["variant"]`) moves to `webkit/`.
|
|
28
|
-
|
|
29
|
-
## Theme And Component Overrides
|
|
30
|
-
|
|
31
|
-
When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
|
|
32
|
-
|
|
33
|
-
- **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.
|
|
34
|
-
- **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.
|
|
35
|
-
- **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.
|
|
36
|
-
|
|
37
|
-
## Recipes
|
|
38
|
-
|
|
39
|
-
Framework UI recipes (Tailwind-variant look factories) import from `akanjs/ui`: `<name>(variants?, className?)`.
|
|
40
|
-
The second argument merges internally and takes an array too, so never wrap it in `cn()`:
|
|
41
|
-
`<name>({}, ["h-full", isWide && "w-full", className])`. Do not guess a recipe name or variant value, and do not open
|
|
42
|
-
the recipe file to consume one. Before inlining a repeated surface (card, box, tile): reuse a recipe, or add one as
|
|
43
|
-
`apps/<app>/ui/Recipe/<name>.ts`, one per file, re-exported from that folder's `index.ts` — never a near-duplicate.
|
|
44
|
-
Each app and lib lists its own recipes in `apps/<app>/AGENTS.md` / `libs/<lib>/AGENTS.md` (`## Recipes In Scope`),
|
|
45
|
-
regenerated by `akan sync`. Full policy: the `recipeRule` guideline.
|
|
17
|
+
`no-daisyui-legacy-class`, `no-inline-color`): no raw palette (`bg-blue-500`), arbitrary or interpolated color
|
|
18
|
+
classes, daisyUI classes or slots, or color literals in `style={{}}` — they render no CSS. Use semantic tokens
|
|
19
|
+
(`bg-primary`, `text-foreground/70`); a legitimate fixed color takes `// biome-ignore lint/plugin: <reason>`.
|
|
20
|
+
- **Never guess a recipe name or variant value**, nor open a recipe file to call one: an app's and a lib's recipes
|
|
21
|
+
are listed in its `AGENTS.md` (`## Recipes In Scope`), the framework's below. A recipe's second argument merges by
|
|
22
|
+
itself and takes an array, so it is never wrapped in `cn()`.
|
|
@@ -9,7 +9,12 @@ Use TailwindCSS with Akan's semantic design-token layer and the `akanjs/ui` prim
|
|
|
9
9
|
- Surfaces/text: `bg-background`, `text-foreground`, `bg-muted`, `text-muted-foreground`, `bg-card`, `bg-popover`, `border-border`, `border-input`, `ring-ring`.
|
|
10
10
|
- Brand/status: `primary`, `secondary`, `accent`, `destructive`, `success`, `warning`, `info`, `neutral`, `open` — each with a `-foreground` pair for text on that surface (e.g. `bg-primary text-primary-foreground`).
|
|
11
11
|
- Compose classes with `cn` from `akanjs/client` (token-aware tailwind-merge) — the only class-combining function. No object syntax: write `cond && "x"`.
|
|
12
|
-
-
|
|
12
|
+
- Static class strings stay plain: `cn` only for a conditional or to merge an incoming `className`.
|
|
13
|
+
- Forward `className` last so callers can extend styles: `cn("base", cond && "extra", className)`.
|
|
14
|
+
- Multi-slot components take named props (`wrapperClassName`), never a `classNames` object.
|
|
15
|
+
- An enum→class lookup is a module-scope `as const` map typed `{ [key in cnst.XStatus["value"]]: string }`, not
|
|
16
|
+
`Record<...>`. Shared by a second module, the classes become a recipe variant in `ui/Recipe/`; only an enum→variant
|
|
17
|
+
name map (`BadgeVariants["variant"]`) moves to `webkit/`.
|
|
13
18
|
|
|
14
19
|
## Color Vocabulary — What Lint Refuses
|
|
15
20
|
- Vocabulary closure strips the raw Tailwind palette, so these render as no CSS and fail lint: raw palette classes
|
|
@@ -34,10 +39,11 @@ Use TailwindCSS with Akan's semantic design-token layer and the `akanjs/ui` prim
|
|
|
34
39
|
- `buttonRecipe({ variant: "primary", size: "lg" }, "w-full rounded-2xl")`
|
|
35
40
|
- Prefer the `akanjs/ui` primitives (`Button`, `Badge`, `Input`, `Field`, `Table` …) over re-implementing a component's look with utility stacks. There is **no `Card`/`Box` primitive** — a card/box is a recipe surface (e.g. `appCard`), not an `akanjs/ui` component; do not `import { Card }`.
|
|
36
41
|
- App-specific repeated surfaces go one-per-file in `apps/<app>/ui/Recipe/` (server-safe, no `"use client"`) via `recipe(tv({ base, variants }))`, imported from `@apps/<app>/ui`. App recipes **extend** (surfaces the lib lacks — chat bubble, tile); they never re-define a lib component in parallel.
|
|
37
|
-
- Full recipe authoring/consumption policy: the `recipeRule` guideline. Never guess recipe names/imports — the authoritative
|
|
42
|
+
- Full recipe authoring/consumption policy: the `recipeRule` guideline. Never guess recipe names/imports — the authoritative lists are the `style` rule (framework recipes) and each app's or lib's `AGENTS.md` (`## Recipes In Scope`).
|
|
38
43
|
|
|
39
44
|
## Customization Decision (where a design delta goes)
|
|
40
|
-
|
|
45
|
+
When a request implies a distinct look and feel, do not stop at colors — customize the theme and, when needed, the
|
|
46
|
+
components. Screen code is invariant — a plain `<Button variant="primary">` never changes. Only these config files do:
|
|
41
47
|
- **Theme differs** (color/radius/font) → override token *values* in `apps/<app>/page/styles.css`.
|
|
42
48
|
- **A lib component's look differs** → recipe override: `export default override({ recipes: { button: neonButtonRecipe } })` in a `page/**/_overrides.tsx`. Every `<Button>` in that route subtree re-skins; behavior (async states, focus, a11y) is untouched. The swap recipe must accept the framework recipe's full variant surface.
|
|
43
49
|
- **Structure/behavior differs** (modal → drawer) → component override (`override({ Modal: BrandModal })`), reassembling headless parts.
|
|
@@ -70,7 +76,8 @@ Screen code is invariant — a plain `<Button variant="primary">` never changes.
|
|
|
70
76
|
```
|
|
71
77
|
- The framework maps these variables to Tailwind color names (`@theme inline` in `akanjs/ui/styles.css`), so a class like `bg-primary` / `text-foreground` resolves to different colors per `data-theme` — the app only sets values, never re-declares the mapping.
|
|
72
78
|
- Switching themes is toggling the `data-theme` attribute. Keep every token defined in both the dark and light blocks.
|
|
73
|
-
- Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes)
|
|
79
|
+
- Radius uses `rounded-box` (cards/modals), `rounded-field` (buttons/inputs), `rounded-selector` (toggles/checkboxes);
|
|
80
|
+
the theme retunes corner rounding through `--radius-box` / `--radius-field`.
|
|
74
81
|
|
|
75
82
|
## Lib-Owned Tokens (`libs/<lib>/ui/tokens.css`)
|
|
76
83
|
- A lib that needs colors of its own — vendor brand colors pinned by someone else's guide (Kakao `#fee500`, Naver `#1ec800`), fixed in-game surfaces — declares them **once** in `libs/<lib>/ui/tokens.css`. Never copy the block into each app's stylesheet.
|
|
@@ -22,8 +22,8 @@ hallucinated, re-derived inline, or duplicated across an app.
|
|
|
22
22
|
- The second arg is a `ClassNameValue`, so it takes **an array (and falsy entries), not just one string**:
|
|
23
23
|
`<name>({}, ["h-full", isWide && "w-full", className])`. Reaching for `cn()` to combine several classes is the
|
|
24
24
|
usual way the no-`cn` contract leaks — there is nothing `cn()` adds here that the recipe does not already do.
|
|
25
|
-
- **Do not guess** recipe names or import paths. The authoritative index is split by ownership: the
|
|
26
|
-
|
|
25
|
+
- **Do not guess** recipe names or import paths. The authoritative index is split by ownership: the `style` path rule
|
|
26
|
+
(loaded with every `.tsx`) lists **framework** recipes, and each app/lib's own `AGENTS.md` (`## Recipes In Scope`)
|
|
27
27
|
lists what that scope may additionally import — its own recipes plus its dependency libs'. Both carry every recipe's
|
|
28
28
|
variant surface and default, so consuming one never requires opening its file. The scoped index is regenerated by
|
|
29
29
|
`akan sync <name>` and kept honest by `akan lint <name>`, which fails when it is stale.
|
|
@@ -46,7 +46,7 @@ The form of a shared look is decided by **counting**, not judgment (`akan lint`
|
|
|
46
46
|
## Authoring Recipes
|
|
47
47
|
- A **reusable or repeated surface** (card, box, tile, chat bubble, hero, …) belongs in a recipe, **not** inline. If the same
|
|
48
48
|
token-class stack appears in more than one place, extract it into a recipe.
|
|
49
|
-
- **Before authoring, check the existing recipe indexes** (
|
|
49
|
+
- **Before authoring, check the existing recipe indexes** (the `style` path rule for framework recipes, the
|
|
50
50
|
scope's own `AGENTS.md` `## Recipes In Scope` for app/lib recipes) and **reuse** a matching recipe instead of
|
|
51
51
|
creating a near-duplicate — registry sprawl comes from re-inventing looks that already exist.
|
|
52
52
|
- Add a new recipe as its own file, `ui/Recipe/<name>.ts` holding a single
|
|
@@ -15,6 +15,9 @@ on the client side**.
|
|
|
15
15
|
- In domain UI the file role fixes the directive: `Template`, `Zone`, and `Util` are client; `Unit` and `View` are
|
|
16
16
|
server. That decides *where* the boundary sits, not how much markup sits behind it — a `Zone` that hoards markup
|
|
17
17
|
is still an SSR regression.
|
|
18
|
+
- Keep page props serializable unless the route pattern clearly allows otherwise, and be careful importing
|
|
19
|
+
client-only code into pages and layouts. Preserve file roles (`.document.ts`, `.service.ts`, `.store.ts`,
|
|
20
|
+
`.constant.ts`, `.client.ts`) and inspect nearby files before introducing a new boundary pattern.
|
|
18
21
|
- Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and
|
|
19
22
|
lib as server-rendered JSX elements over total. Treat **50% server share as the floor** and a falling share as a
|
|
20
23
|
regression to justify or revert.
|
|
@@ -286,6 +286,10 @@ HTTP verb a mutation is mounted under. `conventions` carries the invariants —
|
|
|
286
286
|
|
|
287
287
|
- `.body(...)` / `.param(...)` args accept `ConstantFieldTypeInput` only: scalars, model refs, or `enumOf(...)`.
|
|
288
288
|
Numbers are `Int` or `Float` — `Number` is rejected (`pkgs/akanjs/signal/endpointInfo.ts`).
|
|
289
|
+
- **A model or scalar argument is checked against the request schema on every transport**: a wrong JSON type, a
|
|
290
|
+
value outside its enum or a missing required field answers 400 with `data.name` naming the path
|
|
291
|
+
(`data.items.2.price`); a defaulted field may be left out, an undeclared key is dropped, and a stored model's input
|
|
292
|
+
keeps an absent field absent.
|
|
289
293
|
- **`Upload` is valid only inside a mutation flagged for file upload**:
|
|
290
294
|
`mutation([cnst.File], { fileUpload: true }).body("files", [Upload])`, as the `file` module does. It is not a
|
|
291
295
|
model field type. The other body args of such a mutation arrive typed as in a JSON body. A file's `type` on the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@akanjs/cli",
|
|
3
|
-
"version": "3.3.0-rc.
|
|
3
|
+
"version": "3.3.0-rc.12",
|
|
4
4
|
"sourceType": "module",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"publishConfig": {
|
|
@@ -40,7 +40,7 @@
|
|
|
40
40
|
"@earendil-works/pi-tui": "1.5.2",
|
|
41
41
|
"@inquirer/prompts": "^8.7.3",
|
|
42
42
|
"@tailwindcss/node": "^4.3.3",
|
|
43
|
-
"akanjs": "3.3.0-rc.
|
|
43
|
+
"akanjs": "3.3.0-rc.12",
|
|
44
44
|
"chalk": "^6.0.1",
|
|
45
45
|
"commander": "^15.0.0",
|
|
46
46
|
"dayjs": "^1.11.23",
|
package/skills/akan-err/SKILL.md
CHANGED
|
@@ -30,10 +30,19 @@ import path at all**, so keep throwing code out of them entirely rather than rea
|
|
|
30
30
|
|
|
31
31
|
Best-effort code returns a sentinel (`null`, `undefined`, `{}`) instead of throwing. `try/catch` is rare and
|
|
32
32
|
always converts an exception into a decision: a guard catches, warns, and returns `false`; an adapter
|
|
33
|
-
catches, logs, and returns `null
|
|
34
|
-
the store's `static silent` when no screen waits on it
|
|
33
|
+
catches, logs (`logger.error`), and returns `null`; a UI `try/finally` resets a spinner. A store action never
|
|
34
|
+
catches — let the framework toast the `Err`, or list it in the store's `static silent` when no screen waits on it
|
|
35
|
+
and its caller handles the rejection.
|
|
35
36
|
Client-side validation failure is `msg.error("<key>")` plus an early return, never a throw.
|
|
36
37
|
|
|
38
|
+
An `srvkit/` adapter belongs to no module: its keys go in the app's or lib's own service dictionary,
|
|
39
|
+
`lib/_<name>/<name>.dictionary.ts`, thrown as `new Err("<name>.error.<key>")` with `Err` from `"../lib/dict"`.
|
|
40
|
+
|
|
41
|
+
**An endpoint names the errors it throws on purpose** — `errors: { 409: ["ticket.error.locked"] }` in its signal
|
|
42
|
+
option, with keys its dictionary defines and never `base.error.*`. That is the status's OpenAPI response and a line
|
|
43
|
+
of the MCP tool's description; outside production a thrown key it leaves out warns once. A caller narrows with
|
|
44
|
+
`Err.is(error, "ticket.error.locked")`.
|
|
45
|
+
|
|
37
46
|
**A failure another process reported travels as itself.** A server-to-server `fetch.<endpoint>(…, { origin })`
|
|
38
47
|
restores the remote `Err` with its class, key and data. Rethrow it as-is — wrapping it in a `new Error`
|
|
39
48
|
discards what the endpoint chose to say, and a bare `Error` is generalized to "Internal Server Error" on the
|
|
@@ -33,19 +33,13 @@ export default page()
|
|
|
33
33
|
dropped. `lang` reaches every stage and is never declared.
|
|
34
34
|
3. Gate with `.guard(() => signedIn())` on the `_layout.tsx`, and repeat a stricter guard on a page that needs more.
|
|
35
35
|
`.guard((_, { path }) => signedIn({ path }))` sends a refused visitor to `/signin?redirect=<path>`.
|
|
36
|
-
4. In `.render()`: `usePage()`, then fetch, then return.
|
|
37
|
-
|
|
38
|
-
5. `.head()` takes JSX (or a function returning it), never a metadata object.
|
|
39
|
-
6. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
|
|
36
|
+
4. In `.render()`: `usePage()`, then fetch, then return.
|
|
37
|
+
5. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
|
|
40
38
|
`export default override({ Slot: AppComponent })`, no logic. Nested ones merge slot by slot, the closest winning;
|
|
41
39
|
`componentRule` lists the slots.
|
|
42
40
|
|
|
43
41
|
## API at a glance
|
|
44
42
|
|
|
45
|
-
`page`, `layout` and `router` come from `akanjs/client`, `Link` from `akanjs/ui`, `usePageLocation` from
|
|
46
|
-
`akanjs/webkit`, and `fetch`, `usePage` and the model namespaces from `@apps/<app>/client`. A stage receives the
|
|
47
|
-
declared params and search keys plus `lang`.
|
|
48
|
-
|
|
49
43
|
- Data-driven title: `.head(async ({ id }) => <title>{((await fetch.book(id)) as Book | null)?.title}</title>)`,
|
|
50
44
|
where `Book` is the `common/` interface for the query's `Any` return (`akan-service`).
|
|
51
45
|
- Async page: `.render(async ({ id }) => { const book = (await fetch.book(id)) as Book | null; if (!book) return router.notFound(); … })`;
|
|
@@ -65,12 +59,8 @@ declared params and search keys plus `lang`.
|
|
|
65
59
|
scrollToTop: false })`` in a `"use client"` component, read back with `usePageLocation().searchParams`. Shallow
|
|
66
60
|
holds only while the path stays the same; a server `.search()` sees the value at the next full navigation.
|
|
67
61
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
- A `fetch.<mutation>()` while rendering — it throws `base.error.mutationInRender`, because opening a link would
|
|
71
|
-
perform it. Send writes from a user action.
|
|
72
|
-
- `useState`, `useEffect`, comments, a named export beside the chain, or the legacy `export default async function`.
|
|
73
|
-
- Editing a lib page through its link in `page/(libs)/` — edit the lib's own `page/` source.
|
|
62
|
+
What a route file must never do — write while rendering, hooks, a second export — is the `page` rule, loaded with
|
|
63
|
+
any `page/` file.
|
|
74
64
|
|
|
75
65
|
Full detail: `get_guideline` with `pageRule` (guards in depth, heads, MCP apps, CSR root layouts, lib pages), or
|
|
76
66
|
`ssrRule` for what may render on the server. Every stage's signature, the router's methods, Link's props and every
|