@akanjs/cli 3.1.1-rc.16 → 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.
Files changed (118) hide show
  1. package/.build-stamp +1 -1
  2. package/{CodeAgent-23ewzxqa.js → CodeAgent-fbcq8vks.js} +2 -2
  3. package/{CodeTui-kc99fk78.js → CodeTui-0626gxqd.js} +1 -1
  4. package/TunnelShare-2p24xxza.js +14 -0
  5. package/agent.command-hpza0pg9.js +46 -0
  6. package/akanCode.js +5 -3
  7. package/{application.command-bvfd1680.js → application.command-3a7q1hs2.js} +11 -10
  8. package/{applicationBuildRunner-4ajaesk1.js → applicationBuildRunner-s7yt71j4.js} +5 -5
  9. package/buildBatch.proc.js +6 -6
  10. package/{cloud.command-f2w40fyy.js → cloud.command-4vg0pcea.js} +15 -14
  11. package/cloud.script-nkmeyhet.js +25 -0
  12. package/{code.command-dbhhnahn.js → code.command-fbntb67p.js} +6 -6
  13. package/commandManifest.json +1 -1
  14. package/{context.command-yswjwv6y.js → context.command-31rm54v0.js} +18 -18
  15. package/context.runner-w01a32ph.js +26 -0
  16. package/{guideline.command-ztx6dkpk.js → guideline.command-cv3by2ng.js} +3 -3
  17. package/guidelines/conventions/core.md +104 -0
  18. package/guidelines/conventions/rules/app.md +83 -0
  19. package/guidelines/conventions/rules/auth.md +45 -0
  20. package/guidelines/conventions/rules/config.md +56 -0
  21. package/guidelines/conventions/rules/constant.md +24 -0
  22. package/guidelines/conventions/rules/gates.md +31 -0
  23. package/guidelines/conventions/rules/layer.md +25 -0
  24. package/guidelines/conventions/rules/migration.md +27 -0
  25. package/guidelines/conventions/rules/module.md +90 -0
  26. package/guidelines/conventions/rules/page.md +56 -0
  27. package/guidelines/conventions/rules/sensitive.md +16 -0
  28. package/guidelines/conventions/rules/server.md +86 -0
  29. package/guidelines/conventions/rules/ssr.md +47 -0
  30. package/guidelines/conventions/rules/style.md +43 -0
  31. package/guidelines/conventions/rules/test.md +34 -0
  32. package/guidelines/conventions/rules/ts.md +95 -0
  33. package/guidelines/conventions/rules/tsx.md +75 -0
  34. package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
  35. package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +3 -3
  36. package/incrementalBuilder.proc.js +6 -6
  37. package/{index-xjwcp91m.js → index-05nxx4m5.js} +43 -12
  38. package/{index-k9k18vq9.js → index-0ht91675.js} +37 -59
  39. package/{index-er16p89s.js → index-0zwznvv1.js} +1 -1
  40. package/{index-76jwsm3g.js → index-0zyatd10.js} +2 -2
  41. package/{index-97fsvy66.js → index-12kzwak1.js} +3 -3
  42. package/{index-005dqc83.js → index-1dhf8ymv.js} +2 -2
  43. package/{index-00ke4phc.js → index-3gccwenr.js} +1 -1
  44. package/{index-2epb3wgh.js → index-3txrjt6n.js} +2 -2
  45. package/{index-7ndgffg4.js → index-57q1ayd2.js} +18 -1240
  46. package/index-5kh9scvs.js +514 -0
  47. package/index-5n5hds19.js +1246 -0
  48. package/{index-9sa6abze.js → index-6269mf2s.js} +10 -9
  49. package/{index-921cxqrd.js → index-64g9fsjy.js} +41 -12
  50. package/index-7zeb5r1p.js +653 -0
  51. package/{index-s4c2y5gs.js → index-8s8b4eba.js} +45 -4
  52. package/{index-4332q6yj.js → index-922k2zwq.js} +3 -3
  53. package/{index-m6qgr1rx.js → index-9ndw5d8j.js} +7 -7
  54. package/{index-xfp4dcnx.js → index-et6ce601.js} +1 -1
  55. package/{index-saj9cx3a.js → index-f5adsa58.js} +4 -4
  56. package/{index-vgt25eh1.js → index-fbewhg4g.js} +7 -32
  57. package/{index-ysyt782g.js → index-hm7x0c11.js} +4 -4
  58. package/{index-2p1brf5e.js → index-hvv5rnaq.js} +2 -2
  59. package/index-jje9qzyq.js +27 -0
  60. package/{index-rxse80x6.js → index-js1gj6f6.js} +12 -10
  61. package/{index-p2pahmsa.js → index-kjrvwzav.js} +3 -3
  62. package/index-m6r88hhr.js +3582 -0
  63. package/{index-mk391h0z.js → index-mt0wa941.js} +4 -4
  64. package/{index-m93qg20j.js → index-mwj9q2ya.js} +1 -1
  65. package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
  66. package/index-r2wedvqn.js +138 -0
  67. package/{index-gxj80jz7.js → index-rvynj5gz.js} +1 -1
  68. package/{index-m54n0v29.js → index-tdv66eah.js} +4 -4
  69. package/{index-vq77g679.js → index-w134p86k.js} +1 -1
  70. package/{index-deeskxjh.js → index-wfczhj1z.js} +14 -36
  71. package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
  72. package/{index-qx4r4cj2.js → index-x5ecanqh.js} +2 -2
  73. package/{index-nzfgyw3b.js → index-zre4m2ce.js} +4 -4
  74. package/index.js +23 -22
  75. package/{library.command-hmbkcwzw.js → library.command-sh70fyvy.js} +3 -3
  76. package/{localRegistry.command-sq5p4c9x.js → localRegistry.command-2nbyy84d.js} +14 -13
  77. package/{module.command-n4z29zcv.js → module.command-n0bmtzwy.js} +5 -5
  78. package/{package.command-20025dy3.js → package.command-7h9r51bz.js} +3 -3
  79. package/package.json +2 -2
  80. package/{page.command-q8fvpjer.js → page.command-vjtpfbb1.js} +3 -3
  81. package/{pipeline.command-8j97fq88.js → pipeline.command-c93se3ar.js} +2 -2
  82. package/{primitive.command-e5y6dqp1.js → primitive.command-a3075qp2.js} +6 -6
  83. package/{projectTypecheck-tbdye9k3.js → projectTypecheck-sf9xwaga.js} +1 -1
  84. package/{prompter-76k56b37.js → prompter-hgcta8pb.js} +1 -1
  85. package/quality.command-dw1y9hmy.js +76 -0
  86. package/{repair.command-dq1gckth.js → repair.command-tg57d8yt.js} +5 -5
  87. package/{scalar.command-5vwf152w.js → scalar.command-cwzge353.js} +4 -4
  88. package/skills/akan-agent/SKILL.md +36 -0
  89. package/skills/akan-debug/SKILL.md +3 -3
  90. package/skills/akan-deps/SKILL.md +1 -2
  91. package/skills/akan-mcp/SKILL.md +40 -0
  92. package/skills/akan-page/SKILL.md +44 -0
  93. package/skills/akan-query/SKILL.md +38 -0
  94. package/skills/akan-runtime/SKILL.md +40 -0
  95. package/skills/akan-scaffold/SKILL.md +16 -6
  96. package/skills/akan-transport/SKILL.md +40 -0
  97. package/skills/akan-validate/SKILL.md +13 -11
  98. package/{subspace.command-182be8vj.js → subspace.command-3h03c7kc.js} +8 -8
  99. package/templates/workspaceRoot/.gitignore.template +3 -0
  100. package/templates/workspaceRoot/AGENTS.md.template +4 -10
  101. package/{tunnel.command-bfzj7xkb.js → tunnel.command-czaz6ys4.js} +7 -7
  102. package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
  103. package/typecheck.proc.js +6 -1
  104. package/verify.command-nzwhtz71.js +91 -0
  105. package/{workflow.command-3g53242s.js → workflow.command-srhky88x.js} +23 -13
  106. package/{workspace.command-h7399jwv.js → workspace.command-9stchcd2.js} +31 -29
  107. package/TunnelShare-dk2gw78d.js +0 -14
  108. package/agent.command-knp5j7bq.js +0 -25
  109. package/cloud.script-2r82sv0f.js +0 -24
  110. package/context.runner-c3wsh2jw.js +0 -26
  111. package/guidelines/conventions/conventions.instruction.md +0 -663
  112. package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
  113. package/index-4t4qb8jg.js +0 -279
  114. package/index-hvg3esm0.js +0 -1844
  115. package/index-zzvvc845.js +0 -74
  116. package/quality.command-168pt5vm.js +0 -1788
  117. package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
  118. package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
@@ -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 lint <app>`, `akan typecheck <app>`, `akan sync <app>`, then the boot log above.
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. `workspaceOnboarding` carries the index and the rules; this is the worked code behind them.
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 typecheck <app>` and `bun run akan lint <app>`.
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 typecheck <app>`, `bun run akan lint <app>`, and one agent turn in the browser to confirm the
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
- } from "./index-5nd1wtkv.js";
4
+ WatchRootResolver,
5
+ ApplicationBuildReporter
6
+ } from "./index-p6x5b7hr.js";
7
7
  import {
8
8
  CodegenLock,
9
9
  WorkspaceExecutor,
10
10
  AppExecutor
11
- } from "./index-921cxqrd.js";
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-97fsvy66.js";
22
+ } from "./index-12kzwak1.js";
23
23
  import {
24
24
  ServerGraphFile
25
- } from "./index-er16p89s.js";
25
+ } from "./index-0zwznvv1.js";
26
26
  import {
27
27
  prepareDevWatchBatch
28
28
  } from "./index-a5vmm6x4.js";
@@ -2,7 +2,10 @@
2
2
  import {
3
3
  AppExecutor,
4
4
  LibExecutor
5
- } from "./index-921cxqrd.js";
5
+ } from "./index-64g9fsjy.js";
6
+ import {
7
+ camelToKebabCase
8
+ } from "./index-3gccwenr.js";
6
9
 
7
10
  // pkgs/@akanjs/devkit/workflow/artifacts.ts
8
11
  import { capitalize as capitalize2 } from "akanjs/common";
@@ -287,6 +290,14 @@ var statusForValidationKind = (commands, kind) => {
287
290
  return "unknown";
288
291
  return matching.some((command) => command.status === "failed") ? "failed" : "passed";
289
292
  };
293
+ var generatedSyncStatus = (commands) => {
294
+ const sync = statusForValidationKind(commands, "sync");
295
+ const verify = commands.filter((command) => command.kind === "verify");
296
+ if (sync !== "unknown" || verify.length === 0)
297
+ return sync;
298
+ const syncFailed = verify.some((command) => /^verify fail \u00B7 .*\bsync \d+ errors?\b/m.test(command.stdout ?? ""));
299
+ return syncFailed ? "failed" : "passed";
300
+ };
290
301
  var statusForCommands = (commands) => {
291
302
  if (commands.length === 0)
292
303
  return "unknown";
@@ -380,7 +391,7 @@ var createValidationStatuses = (commands, reportDiagnostics, baselineDiagnostics
380
391
  overallStatus,
381
392
  summary: {
382
393
  sourceChange: sourceStatus,
383
- generatedSync: statusForValidationKind(commands, "sync"),
394
+ generatedSync: generatedSyncStatus(commands),
384
395
  validationCommands: validationCommandsStatus,
385
396
  baseline: baselineStatus,
386
397
  workspaceConfig: statusForScope(commands, diagnostics, scopes, "workspace-config"),
@@ -585,12 +596,10 @@ var moduleSourcePaths = (moduleName) => {
585
596
  };
586
597
  var generatedFilesForSync = (sys, reason = "Generated files may change after sync.") => generatedFilePathsForTarget(getSysRoot(sys), reason);
587
598
  var validationCommandsForTarget = (target) => [
588
- { command: `akan sync ${target}`, reason: "Refresh generated Akan files from source conventions." },
589
- { command: `akan lint ${target}`, reason: "Validate formatting, imports, and static lint rules." }
599
+ { command: `akan verify ${target}`, reason: "Sync, lint, typecheck and build the target in one run." }
590
600
  ];
591
601
  var nextActionsForTarget = (target) => [
592
- { command: `akan sync ${target}`, reason: "Refresh generated Akan files after source changes." },
593
- { command: `akan lint ${target}`, reason: "Validate the target after generated files are refreshed." }
602
+ { command: `akan verify ${target}`, reason: "Refresh generated files and validate the target in one run." }
594
603
  ];
595
604
  var createPrimitiveWriteReport = ({
596
605
  command,
@@ -1262,19 +1271,41 @@ var ensureConstantTypeImport = (content, constantPath, typeName) => {
1262
1271
  return `import type { ${typeName} } from "${constantPath}";
1263
1272
  ${content}`;
1264
1273
  };
1274
+ var dictionaryChainOf = (node) => {
1275
+ if (ts2.isCallExpression(node) && outermostFluentCall(node) === node && protectedDictionaryChainOrder.some((method) => chainMethodsForCall(node).includes(method)))
1276
+ return node;
1277
+ return ts2.forEachChild(node, dictionaryChainOf);
1278
+ };
1279
+ var chainMethodNames = (call) => {
1280
+ if (!ts2.isCallExpression(call) || !ts2.isPropertyAccessExpression(call.expression))
1281
+ return [];
1282
+ const name = call.expression.name;
1283
+ return [...chainMethodNames(call.expression.expression), ...ts2.isIdentifier(name) ? [name] : []];
1284
+ };
1265
1285
  var insertDictionaryEnum = (content, enumClassName, enumName, values) => {
1266
1286
  if (content.includes(`.enum<${enumClassName}>("${enumName}"`))
1267
1287
  return content;
1288
+ const source = sourceFileFor("dictionary.ts", content);
1289
+ if (hasParseDiagnostics(source))
1290
+ return null;
1291
+ const chain = dictionaryChainOf(source);
1292
+ if (!chain)
1293
+ return null;
1268
1294
  const enumBlock = ` .enum<${enumClassName}>("${enumName}", (t) => ({
1269
1295
  ${values.map((value) => ` ${value}: t([${JSON.stringify(titleize(value))}, ${JSON.stringify(titleize(value))}]),`).join(`
1270
1296
  `)}
1271
1297
  }))
1272
1298
  `;
1273
- const chainEndIndex = content.lastIndexOf(";");
1274
- const insertBeforeIndex = [content.indexOf(".error("), content.indexOf(".translate("), chainEndIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0];
1275
- if (insertBeforeIndex === undefined)
1276
- return null;
1277
- return `${content.slice(0, insertBeforeIndex)}${enumBlock}${content.slice(insertBeforeIndex)}`;
1299
+ const later = chainMethodNames(chain).find((name) => name.text === "error" || name.text === "translate");
1300
+ if (!later)
1301
+ return spliceText(content, chain.getEnd(), chain.getEnd(), `
1302
+ ${enumBlock.trimEnd()}`);
1303
+ const dot = content.lastIndexOf(".", later.getStart(source));
1304
+ const lineStart = lineStartAt(content, dot);
1305
+ if (content.slice(lineStart, dot).trim() === "")
1306
+ return spliceText(content, lineStart, lineStart, enumBlock);
1307
+ return spliceText(content, dot, dot, `
1308
+ ${enumBlock}`);
1278
1309
  };
1279
1310
  var parseValues = (value) => value?.split(",").map((item) => item.trim()).filter(Boolean) ?? [];
1280
1311
  var hasSourceParseErrors = (content, fileName = "source.ts") => hasParseDiagnostics(sourceFileFor(fileName, content));
@@ -3335,7 +3366,7 @@ var renderWorkflowExplain = (spec) => [
3335
3366
  ""
3336
3367
  ] : [],
3337
3368
  "## Inputs",
3338
- ...Object.entries(spec.inputs).map(([name, input]) => `- \`${name}\`${input.required ? " (required)" : ""}: ${input.description}${input.allowedValues ? ` Allowed: ${input.allowedValues.join(", ")}.` : ""}`),
3369
+ ...Object.entries(spec.inputs).map(([name, input]) => `- \`${name}\`${camelToKebabCase(name) === name ? "" : ` (\`--${camelToKebabCase(name)}\`)`}${input.required ? " (required)" : ""}: ${input.description}${input.allowedValues ? ` Allowed: ${input.allowedValues.join(", ")}.` : ""}`),
3339
3370
  "",
3340
3371
  "## Optional Surfaces",
3341
3372
  ...Object.entries(spec.optionalSurfaces ?? {}).map(([name, mode]) => `- \`${name}\`: ${mode}`),
@@ -1,11 +1,10 @@
1
1
  // @bun
2
2
  import {
3
3
  SubagentPool2,
4
- akanCodePaths2,
5
4
  McpServerConfig,
6
5
  McpSignIn,
7
6
  AkanCodeCompaction2
8
- } from "./index-deeskxjh.js";
7
+ } from "./index-wfczhj1z.js";
9
8
  import {
10
9
  stripAnsi
11
10
  } from "./index-7md2g9vw.js";
@@ -15,6 +14,9 @@ import {
15
14
  akanCodeModelSupportsImages2,
16
15
  akanCodeModelWarnings2
17
16
  } from "./index-c6eggbee.js";
17
+ import {
18
+ akanCodePaths2
19
+ } from "./index-jje9qzyq.js";
18
20
 
19
21
  // pkgs/@akanjs/devkit/codeAgent/agent/AkanCodeServices.ts
20
22
  import { existsSync as existsSync4, mkdirSync, mkdtempSync } from "fs";
@@ -150,7 +152,7 @@ var akanSystemPrompt2 = (profile) => {
150
152
  "- Never hand-edit a generated file (`lib/cnst.ts`, `db.ts`, `st.ts`, any `*/index.ts` barrel). Fix the owning source and run `repair_generated` or `akan sync`."
151
153
  ];
152
154
  if (profile.tools.builtin.includes("write"))
153
- lines.push("- After editing, call `akan_verify`. It runs sync, lint, typecheck and the SSR check over what the working tree changed. A turn that edits and does not verify is not finished.");
155
+ lines.push("- After editing, call `akan_verify` once. It runs sync, lint, typecheck, a fast build and the SSR check over what the working tree changed; never run `akan lint`, `akan typecheck` or `akan build` separately. A turn that edits and does not verify is not finished.");
154
156
  else
155
157
  lines.push("- This session is read-only: there is no write, edit or bash tool. Report what should change instead of changing it.");
156
158
  if (profile.tools.subagent)
@@ -330,7 +332,7 @@ import { existsSync as existsSync5, statSync as statSync4 } from "fs";
330
332
  import path5 from "path";
331
333
 
332
334
  // pkgs/@akanjs/devkit/codeAgent/tools/AkanEditScope.ts
333
- var empty = { paths: [], apps: [], libs: [], needsSync: false, touchesTsx: false };
335
+ var empty = { paths: [], apps: [], libs: [], pkgs: [], needsSync: false, touchesTsx: false };
334
336
 
335
337
  class AkanEditScope2 {
336
338
  static async since(cwd, baseline) {
@@ -344,6 +346,7 @@ class AkanEditScope2 {
344
346
  paths,
345
347
  apps: AkanEditScope2.#targets(paths, "apps"),
346
348
  libs: AkanEditScope2.#targets(paths, "libs"),
349
+ pkgs: AkanEditScope2.#targets(paths, "pkgs"),
347
350
  needsSync: entries.some((entry) => /[ARD?]/.test(entry.code) && /^(apps|libs)\//.test(entry.file)),
348
351
  touchesTsx: paths.some((file) => file.endsWith(".tsx"))
349
352
  };
@@ -360,7 +363,10 @@ class AkanEditScope2 {
360
363
  `).filter((line) => line.trim().length > 3));
361
364
  }
362
365
  static #targets(paths, root) {
363
- const names = paths.filter((file) => file.startsWith(`${root}/`)).map((file) => file.split("/")[1] ?? "").filter(Boolean);
366
+ const names = paths.filter((file) => file.startsWith(`${root}/`)).map((file) => {
367
+ const [, first = "", second = ""] = file.split("/");
368
+ return first.startsWith("@") && second ? `${first}/${second}` : first;
369
+ }).filter(Boolean);
364
370
  return [...new Set(names)];
365
371
  }
366
372
  }
@@ -700,7 +706,7 @@ class AkanCli2 {
700
706
  cwd: this.#cwd,
701
707
  stdout: "pipe",
702
708
  stderr: "pipe",
703
- env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" }
709
+ env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1", AKAN_LOG_STDOUT_LEVEL: "warn" }
704
710
  });
705
711
  const timer = setTimeout(() => proc.kill(), timeoutMs);
706
712
  const [stdout, stderr, exitCode] = await Promise.all([
@@ -723,49 +729,28 @@ class AkanCli2 {
723
729
 
724
730
  // pkgs/@akanjs/devkit/codeAgent/tools/AkanVerifier.ts
725
731
  class AkanVerifier2 {
732
+ static tailLines = 20;
726
733
  #cli;
727
734
  constructor(cwd) {
728
735
  this.#cli = new AkanCli2(cwd);
729
736
  }
730
- async verify(scope) {
731
- const steps = [];
732
- const targets = [...scope.apps, ...scope.libs];
733
- if (scope.needsSync)
734
- for (const target of targets)
735
- steps.push(await this.#cli.run(["sync", target]));
736
- for (const target of targets)
737
- steps.push(await this.#cli.run(["lint", target]));
738
- for (const app of scope.apps)
739
- steps.push(await this.#cli.run(["typecheck", app]));
740
- if (scope.touchesTsx)
741
- steps.push(await this.#cli.run(["quality", "ssr"]));
742
- return { ok: steps.every((step) => step.ok), steps, scope };
743
- }
744
- static summarize(report, { tailLines = 40 } = {}) {
745
- if (!report.steps.length)
746
- return "No akan target was touched, so there was nothing to verify.";
747
- if (report.ok)
748
- return `Verification passed: ${report.steps.map((step) => step.command).join(", ")}.`;
749
- const failed = report.steps.filter((step) => !step.ok);
750
- const passed = report.steps.filter((step) => step.ok).map((step) => step.command);
751
- const blocks = failed.map((step) => `### ${step.command} (exit ${step.exitCode})
752
- ${tail(step.output, tailLines)}`);
753
- return [
754
- `Verification failed: ${failed.map((step) => step.command).join(", ")}.`,
755
- passed.length ? `Passed: ${passed.join(", ")}.` : "",
756
- ...blocks
757
- ].filter(Boolean).join(`
758
-
759
- `);
737
+ async verify(paths = []) {
738
+ const args = ["verify", ...paths.length ? ["--files", paths.join(",")] : []];
739
+ const result = await this.#cli.run(args, { timeoutMs: 600000 });
740
+ return { ok: result.ok, text: AkanVerifier2.summarize(result) };
760
741
  }
761
- }
762
- var tail = (text, lines) => {
763
- const all = text.split(`
742
+ static summarize(result) {
743
+ if (result.output.startsWith("verify "))
744
+ return result.output;
745
+ const lines = result.output.split(`
764
746
  `);
765
- return all.length <= lines ? text : `\u2026
766
- ${all.slice(-lines).join(`
747
+ const tail = lines.length <= AkanVerifier2.tailLines ? result.output : `\u2026
748
+ ${lines.slice(-AkanVerifier2.tailLines).join(`
767
749
  `)}`;
768
- };
750
+ return `${result.command} exited ${result.exitCode} before reporting:
751
+ ${tail}`;
752
+ }
753
+ }
769
754
 
770
755
  // pkgs/@akanjs/devkit/codeAgent/feedback/VerifyFeedback.ts
771
756
  class VerifyFeedback2 {
@@ -782,14 +767,12 @@ class VerifyFeedback2 {
782
767
  }
783
768
  async observe() {
784
769
  const scope = await AkanEditScope2.since(this.#options.cwd, this.#baseline);
785
- if (!scope.apps.length && !scope.libs.length)
770
+ if (!scope.apps.length && !scope.libs.length && !scope.pkgs.length)
786
771
  return;
787
772
  if (this.#options.readOnly)
788
773
  return VerifyFeedback2.#readOnlyNotice(scope.needsSync, [...scope.apps, ...scope.libs]);
789
- const report = await this.#verifier.verify(scope);
790
- if (report.ok)
791
- return;
792
- return AkanVerifier2.summarize(report);
774
+ const report = await this.#verifier.verify(scope.paths);
775
+ return report.ok ? undefined : report.text;
793
776
  }
794
777
  static #readOnlyNotice(needsSync, targets) {
795
778
  if (!needsSync)
@@ -809,7 +792,7 @@ class AkanToolPack2 {
809
792
  return { name: "akan-tools", factory: async (pi) => await this.#register(pi) };
810
793
  }
811
794
  async names() {
812
- const { ContextRunner } = await import("./context.runner-c3wsh2jw.js");
795
+ const { ContextRunner } = await import("./context.runner-w01a32ph.js");
813
796
  return [
814
797
  ...new ContextRunner().listMcpTools(this.#options.mode).map((tool) => tool.name),
815
798
  AkanToolPack2.verifyToolName
@@ -817,7 +800,7 @@ class AkanToolPack2 {
817
800
  }
818
801
  static verifyToolName = "akan_verify";
819
802
  async#register(pi) {
820
- const { ContextRunner } = await import("./context.runner-c3wsh2jw.js");
803
+ const { ContextRunner } = await import("./context.runner-w01a32ph.js");
821
804
  const runner = new ContextRunner;
822
805
  const guidelineNames = await AkanToolPack2.#guidelineNames();
823
806
  for (const tool of runner.listMcpTools(this.#options.mode, { guidelineNames })) {
@@ -844,23 +827,18 @@ class AkanToolPack2 {
844
827
  pi.registerTool({
845
828
  name: AkanToolPack2.verifyToolName,
846
829
  label: "akan verify",
847
- description: "Run the akan validation chain (sync, lint, typecheck, and quality ssr for .tsx changes) over everything the working tree has changed, and report what failed. Call this after editing before you finish.",
848
- promptSnippet: "akan_verify: run sync/lint/typecheck/quality over the working tree's changes",
830
+ description: "Run `akan verify` over everything the working tree has changed: sync, lint (with fixes), typecheck, a fast build of each changed app, and the SSR check for .tsx changes, in one call. It prints one line when it passes and one line per problem when it fails. Call this after editing, before you finish; never run lint, typecheck or build separately.",
831
+ promptSnippet: "akan_verify: sync, lint, typecheck and build what the working tree changed, in one call",
849
832
  parameters: Type.Object({}),
850
833
  execute: async () => {
851
- const scope = await AkanEditScope2.since(this.#options.cwd, new Set);
852
- const report = await verifier.verify(scope);
853
- return {
854
- content: [{ type: "text", text: AkanVerifier2.summarize(report) }],
855
- details: undefined,
856
- isError: !report.ok
857
- };
834
+ const report = await verifier.verify();
835
+ return { content: [{ type: "text", text: report.text }], details: undefined, isError: !report.ok };
858
836
  }
859
837
  });
860
838
  }
861
839
  static async#guidelineNames() {
862
840
  try {
863
- const { Prompter } = await import("./prompter-76k56b37.js");
841
+ const { Prompter } = await import("./prompter-hgcta8pb.js");
864
842
  return await Prompter.listGuidelines();
865
843
  } catch {
866
844
  return [];
@@ -2,7 +2,7 @@
2
2
  import {
3
3
  AsyncDefaultExportDetector,
4
4
  resolveSsrPageEntriesForApp
5
- } from "./index-921cxqrd.js";
5
+ } from "./index-64g9fsjy.js";
6
6
  import {
7
7
  FileSys2
8
8
  } from "./index-52w0fvh8.js";
@@ -9,10 +9,10 @@ import {
9
9
  UpdatePackFolder,
10
10
  NativePublicEnv,
11
11
  NativeApp
12
- } from "./index-p2pahmsa.js";
12
+ } from "./index-kjrvwzav.js";
13
13
  import {
14
14
  ExitCodeError
15
- } from "./index-00ke4phc.js";
15
+ } from "./index-3gccwenr.js";
16
16
  import {
17
17
  ConfigLock
18
18
  } from "./index-bqbf654f.js";
@@ -5,7 +5,7 @@ import {
5
5
  import {
6
6
  SOURCE_EXTS,
7
7
  WatchRootResolver
8
- } from "./index-5nd1wtkv.js";
8
+ } from "./index-p6x5b7hr.js";
9
9
  import {
10
10
  bundleDefine,
11
11
  CsrEntryFiles,
@@ -19,11 +19,11 @@ import {
19
19
  CsrDevPaths,
20
20
  PagesEntrySourceGenerator,
21
21
  PagesBundleBuilder
22
- } from "./index-er16p89s.js";
22
+ } from "./index-0zwznvv1.js";
23
23
  import {
24
24
  AsyncDefaultExportDetector,
25
25
  resolveSsrPageEntriesForApp
26
- } from "./index-921cxqrd.js";
26
+ } from "./index-64g9fsjy.js";
27
27
 
28
28
  // pkgs/@akanjs/devkit/frontendBuild/autoImportSync.ts
29
29
  import { readdir, readFile, stat } from "fs/promises";
@@ -1,13 +1,13 @@
1
1
  // @bun
2
2
  import {
3
3
  resolveSsrPageEntriesForApp
4
- } from "./index-921cxqrd.js";
4
+ } from "./index-64g9fsjy.js";
5
5
  import {
6
6
  bundleDefine,
7
7
  CsrEntryFiles,
8
8
  PagesEntrySourceGenerator,
9
9
  PagesBundleBuilder
10
- } from "./index-er16p89s.js";
10
+ } from "./index-0zwznvv1.js";
11
11
 
12
12
  // pkgs/@akanjs/devkit/frontendBuild/csrArtifactBuilder.ts
13
13
  import { mkdir as mkdir2, rm as rm2, unlink as unlink2 } from "fs/promises";
@@ -10,7 +10,7 @@ import {
10
10
  LibExecutor,
11
11
  PkgExecutor,
12
12
  ModuleExecutor
13
- } from "./index-921cxqrd.js";
13
+ } from "./index-64g9fsjy.js";
14
14
 
15
15
  // pkgs/@akanjs/devkit/commandDecorators/camelToKebabCase.ts
16
16
  var camelToKebabCase = (str) => str.replace(/([A-Z])/g, "-$1").toLowerCase();
@@ -2,13 +2,13 @@
2
2
  import {
3
3
  runner,
4
4
  script
5
- } from "./index-00ke4phc.js";
5
+ } from "./index-3gccwenr.js";
6
6
  import {
7
7
  FileSys2
8
8
  } from "./index-52w0fvh8.js";
9
9
  import {
10
10
  PkgExecutor
11
- } from "./index-921cxqrd.js";
11
+ } from "./index-64g9fsjy.js";
12
12
  import {
13
13
  TypeScriptDependencyScanner2
14
14
  } from "./index-tvehn2sp.js";