@akanjs/cli 2.3.9-rc.0 → 2.3.9-rc.10

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 (35) hide show
  1. package/incrementalBuilder.proc.js +3945 -532
  2. package/index.js +12712 -7496
  3. package/package.json +2 -2
  4. package/templates/appSample/common/formatters.ts +1 -1
  5. package/templates/appSample/common/validators.ts +1 -1
  6. package/templates/appSample/lib/_noti/noti.dictionary.ts +1 -1
  7. package/templates/appSample/lib/_noti/noti.service.ts +1 -1
  8. package/templates/appSample/lib/_noti/noti.signal.ts +1 -1
  9. package/templates/appSample/lib/_noti/noti.store.ts +1 -1
  10. package/templates/appSample/lib/task/task.abstract.ts +1 -1
  11. package/templates/appSample/lib/task/task.constant.ts +1 -1
  12. package/templates/appSample/lib/task/task.dictionary.ts +1 -1
  13. package/templates/appSample/lib/task/task.document.ts +3 -3
  14. package/templates/appSample/lib/task/task.service.ts +2 -2
  15. package/templates/appSample/lib/task/task.signal.spec.ts +70 -0
  16. package/templates/appSample/lib/task/task.signal.test.ts +20 -0
  17. package/templates/appSample/lib/task/task.signal.ts +2 -2
  18. package/templates/appSample/lib/task/task.store.ts +2 -2
  19. package/templates/appSample/srvkit/AuthGuard.ts +1 -1
  20. package/templates/appSample/srvkit/SessionInternalArg.ts +1 -1
  21. package/templates/appSample/ui/GlobalLoading.tsx +1 -1
  22. package/templates/appSample/ui/QuantityControl.tsx +1 -1
  23. package/templates/appSample/webkit/useDebounce.ts +1 -1
  24. package/templates/lib/useClient.ts +1 -4
  25. package/templates/module/__Model__.Unit.tsx +1 -4
  26. package/templates/module/__model__.constant.ts +0 -1
  27. package/templates/module/__model__.dictionary.ts +10 -4
  28. package/templates/workspaceRoot/.cursor/rules/{akan-scan-conventions.mdc.template → akan-sync-conventions.mdc.template} +3 -3
  29. package/templates/workspaceRoot/.cursor/rules/akan.mdc.template +12 -0
  30. package/templates/workspaceRoot/AGENTS.md.template +91 -58
  31. package/templates/workspaceRoot/biome.json.template +6 -6
  32. package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +51 -0
  33. package/templates/workspaceRoot/docs/GENERATED.md.template +54 -0
  34. package/templates/workspaceRoot/package.json.template +26 -0
  35. package/templates/workspaceRoot/Untitled +0 -1
@@ -3,6 +3,9 @@
3
3
  This is an Akan.js workspace. Akan is convention-driven: keep business intent in the expected place and let
4
4
  the framework generate the repeated surfaces.
5
5
 
6
+ For agent-neutral documentation that Claude Code, Codex, Devin, GitHub Copilot Coding Agent, and other tools can
7
+ also read, see `docs/AI-DEVELOPMENT.md` and `docs/GENERATED.md`.
8
+
6
9
  ## Workspace Layout
7
10
 
8
11
  - `apps/<app>` contains application pages, app UI, app domain modules, env files, and `akan.config.ts`.
@@ -16,25 +19,26 @@ the framework generate the repeated surfaces.
16
19
 
17
20
  ## Generated Files
18
21
 
19
- Do not hand-edit generated Akan files. Regenerate them through Akan scan, lint, start, build, or the matching
22
+ Do not hand-edit generated Akan files. Regenerate them through Akan sync, lint, start, build, or the matching
20
23
  CLI command instead.
21
24
 
22
25
  Common generated files include:
23
26
  - `apps/*/client.ts`
24
27
  - `apps/*/server.ts`
25
- - `apps/*/lib/cnst.ts`
26
- - `apps/*/lib/dict.ts`
27
- - `apps/*/lib/db.ts`
28
- - `apps/*/lib/srv.ts`
29
- - `apps/*/lib/st.ts`
30
- - `apps/*/lib/sig.ts`
31
- - `apps/*/lib/useClient.ts`
32
- - `apps/*/lib/useServer.ts`
33
- - `apps/*/lib/*/index.ts`
34
- - `apps/*/ui/index.ts`
35
- - `apps/*/webkit/index.ts`
36
- - `apps/*/srvkit/index.ts`
37
- - `apps/*/common/index.ts`
28
+ - `*/lib/cnst.ts`
29
+ - `*/lib/db.ts`
30
+ - `*/lib/dict.ts`
31
+ - `*/lib/option.ts`
32
+ - `*/lib/sig.ts`
33
+ - `*/lib/srv.ts`
34
+ - `*/lib/st.ts`
35
+ - `*/lib/useClient.ts`
36
+ - `*/lib/useServer.ts`
37
+ - `*/lib/**/index.ts`
38
+ - `*/ui/index.ts`
39
+ - `*/webkit/index.ts`
40
+ - `*/srvkit/index.ts`
41
+ - `*/common/index.ts`
38
42
 
39
43
  ## Domain Module Responsibilities
40
44
 
@@ -58,15 +62,20 @@ Use the local module shape before adding a new abstraction.
58
62
 
59
63
  1. Read the nearby module and convention before creating files. If `*.abstract.md` exists, read it first.
60
64
  2. Put new files in the established Akan location instead of adding parallel architecture.
61
- 3. Prefer CLI generation commands for new apps, libraries, modules, scalars, pages, and generated references.
62
- 4. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
63
- 5. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
64
- 6. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
65
- 7. Keep server-only logic out of client surfaces and client-only code out of server imports.
66
- 8. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
67
- 9. Add or update tests when behavior, contracts, or CLI output changes.
68
- 10. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
69
- 11. Run the smallest relevant verification command after changes.
65
+ 3. Prefer Akan MCP workflows before direct source edits. Start with `akan mcp --mode plan` for `list_workflows`, `explain_workflow`, and `plan_workflow`.
66
+ 4. If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call `apply_workflow({ planPath })` before direct source edits.
67
+ 5. Use `akan mcp --mode apply` only for allowlisted `apply_workflow`, `run_validation`, and repair tools.
68
+ 6. After `apply_workflow`, run `run_validation` with `validationTarget` when present; otherwise use `applyReportPath`.
69
+ 7. Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
70
+ 8. If no workflow exists, or apply reports unsupported/no-op/failed diagnostics that require manual action, edit only the owning source files and never patch generated files directly.
71
+ 9. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
72
+ 10. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
73
+ 11. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
74
+ 12. Keep server-only logic out of client surfaces and client-only code out of server imports.
75
+ 13. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
76
+ 14. Add or update tests when behavior, contracts, or CLI output changes.
77
+ 15. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
78
+ 16. Run the smallest relevant verification command after changes.
70
79
 
71
80
  ## Common Commands
72
81
 
@@ -117,77 +126,101 @@ For the default generated app, start with:
117
126
  akan start <%= appName %>
118
127
  ```
119
128
 
120
- ### The Essential Loop: Edit Scan Check
129
+ ### The Essential Loop: Workflow -> Sync -> Check
121
130
 
122
- Almost every Akan.js change follows this pattern. **Missing step 2 is the #1 cause of agent confusion.**
131
+ Almost every Akan.js change follows this pattern. **Missing sync or repair is the #1 cause of agent confusion.**
123
132
 
124
- 1. **Edit** — Create or modify source files in the correct location.
133
+ 1. **Plan** — Ask the Akan MCP server for the workflow first.
134
+ ```
135
+ akan mcp --mode plan
136
+ # use list_workflows, explain_workflow, and plan_workflow
125
137
  ```
126
- vi apps/<%= appName %>/lib/task/task.constant.ts # e.g., add a priority field
138
+
139
+ 2. **Apply the plan** — If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call
140
+ `apply_workflow({ planPath })`. Do not copy the workflow plan into direct source edits.
127
141
  ```
142
+ akan mcp --mode apply
143
+ # use apply_workflow, run_validation, repair_generated, repair_imports, or repair_module_shape
144
+ ```
145
+
146
+ Direct edits are fallback only: use them after `list_workflows`/`explain_workflow` confirm no matching workflow, or
147
+ after apply reports unsupported/no-op/failed diagnostics that require manual action. Keep fallback edits to owning
148
+ source files such as `task.constant.ts`, `task.dictionary.ts`, `Task.Template.tsx`, or `Task.Unit.tsx`.
128
149
 
129
- 2. **Scan** — Regenerate barrel files so Akan discovers your change. This regenerates:
150
+ 3. **Validate the apply report** — Use the apply report artifact, not the original raw plan, when it is available.
151
+ ```
152
+ # run_validation with validationTarget first; otherwise use applyReportPath
153
+ ```
154
+
155
+ 4. **Sync or repair** — Regenerate barrel files so Akan discovers your change. This regenerates:
130
156
  `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`,
131
157
  `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and all module `index.ts` files.
132
158
  ```
133
- akan scan app <%= appName %>
159
+ akan sync <%= appName %>
160
+ # or: akan repair generated --app <%= appName %>
134
161
  ```
135
- **CRITICAL**: Scan after EVERY file add, delete, or rename. Without scan, other modules cannot
162
+ **CRITICAL**: Sync after EVERY file add, delete, or rename. Without sync, other modules cannot
136
163
  `import * as cnst from "../cnst"` and find your new model.
137
164
 
138
- 3. **Check** — Verify your change compiles and lints.
165
+ 5. **Check** — Verify your change compiles and lints.
139
166
  ```
140
167
  akan start <%= appName %> # dev server with live feedback (preferred)
141
168
  akan lint <%= appName %> # quick lint-only check
169
+ akan doctor --strict # structured workspace diagnostics
142
170
  ```
143
171
 
144
- If `akan scan` gives errors, try:
145
- - `akan build <%= appName %>` — full rebuild catches type errors scan may miss
146
- - Re-run `akan create-model <name> --app <%= appName %>` if the scaffold is corrupted
172
+ If `akan sync` gives errors, try:
173
+ - `akan build <%= appName %>` — full rebuild catches type errors sync may miss
174
+ - Re-run `akan create-module <name> --app <%= appName %>` if the scaffold is corrupted
175
+
176
+ For compound natural-language requests, split the request into workflows and apply each artifact in order. For example,
177
+ "create a project module and add a budget field" should run `create-module` plan/apply first, then `add-field`
178
+ plan/apply, then validation/doctor on the returned `validationTarget`.
147
179
 
148
180
  ## Quick Decision Matrix — "Where do I put this code?"
149
181
 
150
182
  | You want to... | Create in... | Run after... |
151
183
  |----------------|-------------|--------------|
152
- | Define a new database-backed noun (e.g., User, Product) | `lib/<model>/` → constant, document, service, signal, store, dictionary, abstract | `akan scan app <name>` |
153
- | Add a pure workflow / integration (e.g., Payment, Email) | `lib/_<service>/` → service, signal, store, dictionary, abstract | `akan scan app <name>` |
154
- | Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan scan app <name>` |
184
+ | Define a new database-backed noun (e.g., User, Product) | `lib/<model>/` → constant, document, service, signal, store, dictionary, abstract | `akan sync <name>` |
185
+ | Add a pure workflow / integration (e.g., Payment, Email) | `lib/_<service>/` → service, signal, store, dictionary, abstract | `akan sync <name>` |
186
+ | Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan sync <name>` |
155
187
  | Create a new URL-visitable page | `page/` → `_index.tsx`, `_layout.tsx`, `[param]/_index.tsx` | Rebuild (akan start auto-detects) |
156
- | Add a form or reusable UI component | `ui/` → PascalCase `.tsx` with `"use client"` if needed | `akan scan app <name>` |
157
- | Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan scan app <name>` |
158
- | Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan scan app <name>` |
159
- | Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan scan app <name>` |
188
+ | Add a form or reusable UI component | `ui/` → PascalCase `.tsx` with `"use client"` if needed | `akan sync <name>` |
189
+ | Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan sync <name>` |
190
+ | Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan sync <name>` |
191
+ | Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan sync <name>` |
160
192
 
161
193
  ## Anti-patterns: Never Do These
162
194
 
163
195
  | Don't | Why | Do Instead |
164
196
  |-------|-----|------------|
165
- | Edit `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`, or any `index.ts` | These are **generated by `akan scan`**. Your changes will be overwritten. | Edit the source files in `lib/<model>/` directories and run `akan scan` |
166
- | Create a file without running scan | New files won't appear in barrel exports. Imports like `import * as cnst from "../cnst"` will fail. | Always run `akan scan app <name>` after creating, renaming, or deleting any module file |
197
+ | Edit `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`, or any `index.ts` | These are **generated by `akan sync`**. Your changes will be overwritten. | Edit the source files in `lib/<model>/` directories and run `akan sync <name>` |
198
+ | Create a file without running sync | New files won't appear in barrel exports. Imports like `import * as cnst from "../cnst"` will fail. | Always run `akan sync <name>` after creating, renaming, or deleting any module file |
167
199
  | Use JS `#private` methods in service classes | Akan's build system rejects `#private`. Use TypeScript `private` keyword instead. | `private _methodName()` — never `#_methodName()` |
168
200
  | Use `console.log()` | Biome lint forbids `console.log`. Only `console.error`, `console.info`, `console.warn` are allowed. | Use one of the three allowed console methods |
169
201
  | Import server APIs (`fs`, `Bun`, `process.env`) in `ui/`, `webkit/`, or `common/` | Server-only imports in client code cause build failures. | Keep server dependencies in `lib/`, `srvkit/`, or `private/` only |
170
- | Skip running `akan scan` after deleting a file | Deleted files remain referenced in barrel exports, causing import errors everywhere. | Run `akan scan app <name>` after every file add, remove, or rename |
202
+ | Skip running `akan sync` after deleting a file | Deleted files remain referenced in barrel exports, causing import errors everywhere. | Run `akan sync <name>` after every file add, remove, or rename |
171
203
  | Use "use client" or `useState`/`useEffect` in pages/*.tsx, *.Unit.tsx, and *.View.tsx files | Server code cannot use React hooks. Wrap in a separate `"use client"` component. | Move hook logic to `webkit/` or a `"use client"` UI component |
172
204
  | Use `<a>` tag for internal navigation between pages | Akan.js uses `<Link>` from `akanjs/ui` for client-side navigation — avoids full page reloads. | `import { Link } from "akanjs/ui"` and use `<Link href="/task">...</Link>` |
173
205
 
174
206
  ## Generated File Tracker (Quick Reference)
175
207
 
176
- These files are regenerated by `akan scan` and overwritten on every scan. **Do not hand-edit them.**
208
+ These files are regenerated by `akan sync` and overwritten on every sync. **Do not hand-edit them.**
177
209
 
178
210
  | File | Generated From | Purpose |
179
211
  |------|---------------|---------|
180
- | `apps/*/lib/cnst.ts` | All `*/lib/*/**.constant.ts` | Barrel for all constants |
181
- | `apps/*/lib/dict.ts` | All `*/lib/*/**.dictionary.ts` | Barrel for all dictionaries |
182
- | `apps/*/lib/db.ts` | All `*/lib/<model>/*.document.ts` | Barrel for all document models |
183
- | `apps/*/lib/srv.ts` | All `*/lib/**/**.service.ts` | Barrel for all services |
184
- | `apps/*/lib/sig.ts` | All `*/lib/**/**.signal.ts` | Barrel for all signals |
185
- | `apps/*/lib/st.ts` | All `*/lib/**/**.store.ts` | Barrel for all stores |
186
- | `apps/*/lib/useClient.ts` | Client-safe module re-exports | Client-side import entry |
187
- | `apps/*/lib/useServer.ts` | Server-only module re-exports | Server-side import entry |
212
+ | `*/lib/cnst.ts` | All `*/lib/*/**.constant.ts` | Barrel for all constants |
213
+ | `*/lib/db.ts` | All `*/lib/<model>/*.document.ts` | Barrel for all document models |
214
+ | `*/lib/dict.ts` | All `*/lib/*/**.dictionary.ts` | Barrel for all dictionaries |
215
+ | `*/lib/option.ts` | Generated option helpers | Option helper entry |
216
+ | `*/lib/sig.ts` | All `*/lib/**/**.signal.ts` | Barrel for all signals |
217
+ | `*/lib/srv.ts` | All `*/lib/**/**.service.ts` | Barrel for all services |
218
+ | `*/lib/st.ts` | All `*/lib/**/**.store.ts` | Barrel for all stores |
219
+ | `*/lib/useClient.ts` | Client-safe module re-exports | Client-side import entry |
220
+ | `*/lib/useServer.ts` | Server-only module re-exports | Server-side import entry |
188
221
  | `apps/*/client.ts` | App-wide client barrel | The `fetch` and `st` instances |
189
222
  | `apps/*/server.ts` | App-wide server barrel | Server-side service resolution |
190
- | `*/lib/*/index.ts` | Per-module barrel | Module-level re-exports |
223
+ | `*/lib/**/index.ts` | Per-module barrel | Module-level re-exports |
191
224
  | `*/ui/index.ts` | All UI component files | UI barrel |
192
225
  | `*/webkit/index.ts` | All webkit files | Webkit barrel |
193
226
  | `*/srvkit/index.ts` | All srvkit files | Srvkit barrel |
@@ -206,7 +239,7 @@ rewrite the entire file.
206
239
 
207
240
  ### Recipe 1: Adding a New Field to a Model
208
241
 
209
- **Files to edit (in order):** `constant.ts` → `dictionary.ts` → `Template.tsx` → `Unit.tsx` → `akan scan`
242
+ **Files to edit (in order):** `constant.ts` → `dictionary.ts` → `Template.tsx` → `Unit.tsx` → `akan sync`
210
243
 
211
244
  ```typescript
212
245
  // 1. apps/<app>/lib/<model>/<model>.constant.ts
@@ -249,7 +282,7 @@ const form = st.use.taskForm();
249
282
  })}>{task.priority}</span>
250
283
 
251
284
  // 5. Regenerate barrels
252
- // akan scan app <name>
285
+ // akan sync <name>
253
286
  ```
254
287
 
255
288
  ---
@@ -491,7 +524,7 @@ For each business question, follow this chain:
491
524
 
492
525
  ## Auto-Generated API Reference
493
526
 
494
- akan scan automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
527
+ akan sync automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
495
528
 
496
529
  ### Signal — Endpoint Auto-Generation
497
530
 
@@ -542,4 +575,4 @@ akan scan automatically generates APIs across all layers. Only write custom logi
542
575
  | `exists[Query](args)`, `count[Query](args)` | Existence check and count |
543
576
  | `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
544
577
 
545
- **Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan scan auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
578
+ **Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
@@ -1,5 +1,5 @@
1
1
  {
2
- "$schema": "https://biomejs.dev/schemas/2.4.4/schema.json",
2
+ "$schema": "https://biomejs.dev/schemas/2.5.2/schema.json",
3
3
  "vcs": {
4
4
  "enabled": true,
5
5
  "clientKind": "git",
@@ -62,7 +62,7 @@
62
62
  "linter": {
63
63
  "enabled": true,
64
64
  "rules": {
65
- "recommended": true,
65
+ "preset": "recommended",
66
66
  "suspicious": {
67
67
  "noConsole": {
68
68
  "level": "error",
@@ -71,7 +71,10 @@
71
71
  }
72
72
  },
73
73
  "noArrayIndexKey": "off",
74
- "noShadowRestrictedNames": "off"
74
+ "noShadowRestrictedNames": "off",
75
+ "noUnnecessaryConditions": {
76
+ "level": "error"
77
+ }
75
78
  },
76
79
  "correctness": {
77
80
  "noUnusedFunctionParameters": "off",
@@ -91,9 +94,6 @@
91
94
  "attributes": ["classList"],
92
95
  "functions": ["clsx", "cva"]
93
96
  }
94
- },
95
- "noUnnecessaryConditions": {
96
- "level": "error"
97
97
  }
98
98
  },
99
99
  "a11y": "off",
@@ -0,0 +1,51 @@
1
+ # AI Development Guide
2
+
3
+ This workspace is an Akan.js project. Keep business intent in source files and let `akan sync` regenerate the
4
+ repeated surfaces.
5
+
6
+ ## Domain Module Shape
7
+
8
+ - `apps/<app>/lib/<model>` is for database-backed domain modules.
9
+ - `apps/<app>/lib/_<service>` is for service modules without their own database document.
10
+ - `apps/<app>/lib/__scalar/<scalar>` is for reusable embedded value shapes.
11
+ - Put model behavior in the local module before creating a parallel architecture.
12
+
13
+ ## Data Flow
14
+
15
+ Follow this order for domain changes:
16
+
17
+ 1. `constant` defines fields, enums, and model layers.
18
+ 2. `document` defines queries, filters, and document state transitions.
19
+ 3. `service` owns business workflows and orchestration.
20
+ 4. `signal` exposes typed endpoints, slices, and internal jobs.
21
+ 5. `store` owns reusable client workflow state and actions.
22
+ 6. UI files render forms, lists, details, and actions.
23
+
24
+ ## When To Run Sync
25
+
26
+ Run this after adding, deleting, or renaming module, UI, webkit, srvkit, or common files:
27
+
28
+ ```bash
29
+ akan sync <%= appName %>
30
+ ```
31
+
32
+ Sync regenerates barrels such as `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `useClient.ts`, `useServer.ts`,
33
+ and module `index.ts` files. Without sync, imports can point at stale generated files.
34
+
35
+ ## Generated Files
36
+
37
+ Do not hand-edit generated Akan files. Edit source files in the owning module and run sync or build instead.
38
+ See `docs/GENERATED.md` for the generated file list.
39
+
40
+ ## Server And Client Boundary
41
+
42
+ - Keep server-only APIs such as `fs`, `Bun`, secrets, database adaptors, and server env access out of client code.
43
+ - Client surfaces include `ui/`, `webkit/`, `*.Template.tsx`, `*.Zone.tsx`, and `*.Util.tsx` files that use
44
+ `"use client"`.
45
+ - Server-oriented surfaces include pages, `*.Unit.tsx`, `*.View.tsx`, `lib/`, `srvkit/`, and server entrypoints.
46
+ - Treat `AKAN_PUBLIC_*` values as public.
47
+
48
+ ## Abstract Documents
49
+
50
+ Update `*.abstract.md` when business invariants, workflows, user-visible behavior, cross-module relationships, or
51
+ agent guidance changes. Do not update it for purely mechanical formatting or regenerated file changes.
@@ -0,0 +1,54 @@
1
+ # Generated Akan Files
2
+
3
+ These files are generated by `akan sync`, `akan start`, or `akan build`. Do not edit them by hand because the next
4
+ sync or build can overwrite local changes.
5
+
6
+ ## App Entrypoints
7
+
8
+ | File | Purpose |
9
+ | --- | --- |
10
+ | `apps/*/client.ts` | App-wide client entrypoint for generated fetch, store, and client runtime exports. |
11
+ | `apps/*/server.ts` | App-wide server entrypoint for generated server, service, signal, database, and dictionary exports. |
12
+
13
+ ## App Library Barrels
14
+
15
+ | File | Purpose |
16
+ | --- | --- |
17
+ | `apps/*/lib/cnst.ts` | Re-exports constants and model shapes from module `*.constant.ts` files. |
18
+ | `apps/*/lib/db.ts` | Re-exports database models from module `*.document.ts` files. |
19
+ | `apps/*/lib/dict.ts` | Re-exports dictionaries from module `*.dictionary.ts` files. |
20
+ | `apps/*/lib/option.ts` | Re-exports generated option helpers. |
21
+ | `apps/*/lib/srv.ts` | Re-exports services from module `*.service.ts` files. |
22
+ | `apps/*/lib/sig.ts` | Re-exports endpoints, slices, and internals from module `*.signal.ts` files. |
23
+ | `apps/*/lib/st.ts` | Re-exports stores from module `*.store.ts` files. |
24
+ | `apps/*/lib/useClient.ts` | Client-safe generated imports for fetch, message, signal, and store usage. |
25
+ | `apps/*/lib/useServer.ts` | Server-safe generated imports for service, database, signal, and dictionary usage. |
26
+ | `apps/*/lib/**/index.ts` | Per-module generated barrel files. |
27
+
28
+ ## Shared Surface Barrels
29
+
30
+ | File | Purpose |
31
+ | --- | --- |
32
+ | `*/ui/index.ts` | Re-exports UI component files. |
33
+ | `*/webkit/index.ts` | Re-exports webkit/browser helper files. |
34
+ | `*/srvkit/index.ts` | Re-exports server-kit helper files. |
35
+ | `*/common/index.ts` | Re-exports common helper files. |
36
+
37
+ ## How To Change Generated Output
38
+
39
+ 1. Prefer `akan mcp --mode plan` to find an allowlisted workflow before editing files directly.
40
+ 2. If a workflow or repair tool exists, use `akan mcp --mode apply` for `apply_workflow`, `run_validation`, or
41
+ `repair_generated`.
42
+ 3. Edit the source file that owns the behavior, such as `task.constant.ts`, `task.document.ts`, `task.service.ts`,
43
+ `task.signal.ts`, or `task.store.ts`.
44
+ 4. Run:
45
+
46
+ ```bash
47
+ akan sync <%= appName %>
48
+ # or: akan repair generated --app <%= appName %>
49
+ ```
50
+
51
+ 5. Re-run the smallest relevant check, usually `akan test <%= appName %>`, `akan lint <%= appName %>`,
52
+ `akan doctor --strict`, or `akan build <%= appName %>`.
53
+
54
+ If a generated file looks wrong, fix the source convention or sync input rather than patching the generated file.
@@ -2,6 +2,32 @@
2
2
  "name": "<%= repoName %>",
3
3
  "description": "<%= repoName %> workspace",
4
4
  "version": "0.0.1",
5
+ "scripts": {
6
+ "sync": "akan sync",
7
+ "dev": "akan start",
8
+ "lint": "akan lint",
9
+ "typecheck": "akan typecheck",
10
+ "test": "akan test",
11
+ "build": "akan build",
12
+ "setup:agent": "akan agent install all --force",
13
+ "agent:setup": "akan agent install all --force",
14
+ "agent:doctor": "akan doctor --strict --format json",
15
+ "agent:context": "akan context --format json",
16
+ "agent:mcp:readonly": "akan mcp-install cursor --mode readonly --force",
17
+ "agent:mcp:plan": "akan mcp-install cursor --mode plan --force",
18
+ "agent:mcp:apply": "akan mcp-install cursor --mode apply --force",
19
+ "agent:workflows": "akan workflow list",
20
+ "agent:sample:context": "akan context --format markdown --app <%= appName %> --module project",
21
+ "agent:sample:service": "akan create-service billing <%= appName %> --format json",
22
+ "agent:sample:module": "akan create-module project <%= appName %> --page=true --format json",
23
+ "agent:sample:field": "akan add-field --app <%= appName %> --module project --field budget --type Int --default 0 --format json",
24
+ "agent:sample:status": "akan add-enum-field --app <%= appName %> --module project --field status --values draft,active,archived --default draft --format json",
25
+ "agent:sample:sync": "akan sync <%= appName %>",
26
+ "agent:sample:check": "akan doctor --strict --format json",
27
+ "agent:sample:workflow:explain": "akan workflow explain add-field",
28
+ "agent:sample:workflow:plan": "akan workflow plan add-field --app <%= appName %> --module task --field priority --type enum --values low,medium,high --default medium --format json --out .akan/workflows/plans/task-priority.json",
29
+ "agent:sample:workflow:dry-run": "akan workflow apply .akan/workflows/plans/task-priority.json --dry-run --format json"
30
+ },
5
31
  "dependencies": {},
6
32
  "devDependencies": {},
7
33
  "patchedDependencies": {
@@ -1 +0,0 @@
1
- android?: "auto" | "edge-to-edge" | "none";