@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
@@ -1,291 +0,0 @@
1
- ## Workspace Layout
2
-
3
- - `apps/<app>` contains application pages, app UI, app domain modules, env files, and `akan.config.ts`.
4
- - `libs/<lib>` contains shared domain and utility code reused by apps.
5
- - `apps/<app>/lib/<model>` holds database-backed domain modules, `lib/_<service>` service modules, and
6
- `lib/__scalar/<scalar>` reusable value types. Module abstracts sit beside the code as `<name>.abstract.md`.
7
- - `apps/<app>/page` holds server-side file-routed pages: `<routeName>.tsx` serves `/routeName`, a directory's
8
- `_index.tsx` serves that directory, `_layout.tsx` nests a layout, and `[modelId]` is a dynamic segment. Each route
9
- file is one chain — `export default page()…render()`, or `layout()` / `rootLayout()` in a `_layout.tsx`.
10
- - The `native` section of `akan.config.ts` makes the app an iOS, Android and desktop app built from the same pages,
11
- and `apps/<app>/native/<id>` holds a native plugin the app owns.
12
-
13
- The file roles inside a module — which file owns persistence, business logic, state, and each UI shape — are in
14
- the convention set above under **Domain Module Conventions**.
15
-
16
- ## Agent Workflow
17
-
18
- 1. Read the nearby module and convention before creating files. If `*.abstract.md` exists, read it first.
19
- 2. Put new files in the established Akan location instead of adding parallel architecture.
20
- 3. Prefer Akan MCP workflows before direct source edits. Start with `akan mcp --mode plan` for `list_workflows`, `explain_workflow`, and `plan_workflow`.
21
- 4. If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call `apply_workflow({ planPath })` before direct source edits.
22
- 5. Use `akan mcp --mode apply` only for allowlisted `apply_workflow`, `run_validation`, and repair tools.
23
- 6. After `apply_workflow`, run `run_validation` with `validationTarget` when present; otherwise use `applyReportPath`.
24
- 7. Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
25
- 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.
26
- 9. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
27
- 10. Add or update tests when behavior, contracts, or CLI output changes.
28
- 11. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
29
- 12. Run the smallest relevant verification command after changes. After touching any `.tsx`, that includes
30
- `akan quality ssr`.
31
-
32
- The rules for where code goes, the client/server boundary, and SSR discipline are in the convention set above;
33
- this section covers only the order of operations.
34
-
35
- ## Common Commands
36
-
37
- Run commands from the workspace root unless a task says otherwise.
38
-
39
- ### Module Addition Workflow
40
-
41
- When adding a new database-backed domain module (e.g., product, user):
42
-
43
- ```bash
44
- # 1. Scaffold the module with Akan CLI (creates constant, service, signal, store, document files)
45
- # The target app/lib is a POSITIONAL argument, not a --app flag.
46
- akan create-module <module-name> <%= appName %>
47
-
48
- # 2. Start dev server with HMR and type checking at http://localhost:8282
49
- akan start <%= appName %>
50
- ```
51
-
52
- ### Change Verification Workflow
53
-
54
- After any code change, run these in order:
55
-
56
- ```bash
57
- # 1. Fast lint check — Akan.js conventions and Biome rules
58
- akan lint <%= appName %>
59
-
60
- # 2. Type-only check — catches server/client boundary violations and import errors
61
- akan typecheck <%= appName %>
62
-
63
- # 3. Test — Run the test code (lib/*/*.signal.test.ts or others)
64
- akan test <%= appName %>
65
-
66
- # 4. SSR balance — only after touching .tsx files. Reports the server render share
67
- # per app/lib and flags client code that should render on the server.
68
- akan quality ssr
69
-
70
- # 5. Full production build — bundles the app, runs all type/lint checks combined
71
- akan build <%= appName %>
72
- ```
73
-
74
- **Verify endpoints with signal tests, not raw HTTP.** The canonical way to check a query/mutation/slice
75
- contract is an in-memory signal test (`<model>.signal.test.ts`), using the test fetch harness
76
- (`getOrSetupSignalTestFetch`) — it is fast, needs no running server, and exercises `fetch.*`, `view/edit/merge<Model>`,
77
- and slice `init`/`list`/`insight` directly. Prefer it over `curl`: the dev gateway locale-prefixes routes (`/en/...`),
78
- so hand-rolled HTTP calls against a raw path can redirect unexpectedly. See `akan test <%= appName %>`.
79
-
80
- ### Other Frequently Used Commands
81
-
82
- ```bash
83
- akan create-scalar <scalar-name> <%= appName %> # Add a scalar module (lib/__scalar/<scalar-name>/)
84
- akan create-service <service-name> <%= appName %> # Add a service module (lib/_<service-name>/)
85
- akan test <%= appName %> # Run the test code (lib/*/*.signal.test.ts or others)
86
- akan lint <%= appName %> # Lint only (no typecheck)
87
- akan quality scan # All code-quality warnings + SSR balance
88
- akan quality ssr # SSR balance and client-boundary warnings only
89
- ```
90
-
91
- **CLI argument conventions.** Two argument styles, and mixing them up is a common mistake:
92
-
93
- - Scaffolding and whole-app commands take the target app/lib as a **positional** argument, not a flag:
94
-
95
- ```bash
96
- akan create-module photo <%= appName %>
97
- akan create-scalar money <%= appName %>
98
- akan create-service billing <%= appName %>
99
- akan sync <%= appName %>
100
- ```
101
-
102
- - Only the source-limited field commands use `--app`/`--module` flags:
103
-
104
- ```bash
105
- akan add-field --app <%= appName %> --module photo --field width --type Int
106
- akan add-enum-field --app <%= appName %> --module photo --field status --values draft,active
107
- ```
108
-
109
- Passing `--app` to `create-module` is not recognized, and the target app will not resolve.
110
-
111
- For the default generated app, start with:
112
-
113
- ```bash
114
- akan start <%= appName %>
115
- ```
116
-
117
- ### Native Apps — iOS, Android, Desktop
118
-
119
- `native: { desktop: { server: true } }` in `akan.config.ts` is all a desktop app that carries its own server needs.
120
- A `start-*` command loads its pages from `akan start`, so run that first; a desktop app that carries its server
121
- starts it itself. The full contract — targets, updates, what the carried server ships — is
122
- `akan guideline show runtimeRule`.
123
-
124
- ```bash
125
- akan start-desktop <%= appName %> # Run the desktop app on this computer
126
- akan start-ios <%= appName %> # Run it in a simulator or on an iPhone (start-android alike)
127
- akan build-desktop <%= appName %> # Build it for this computer into dist/native/<%= appName %>/<target>/build
128
- akan build-desktop <%= appName %> --installer true # Windows: add a per-user setup program
129
- akan update-keygen <%= appName %> # Make the update signing key once; print its public key
130
- akan publish-update <%= appName %> # Build a key-signed release for updates.url; --sign true also code-signs it
131
- ```
132
-
133
- ### The Essential Loop: Workflow -> Sync -> Check
134
-
135
- Almost every Akan.js change follows this pattern. **Missing sync or repair is the #1 cause of agent confusion.**
136
-
137
- > **If the Akan MCP tools are not connected in your agent, skip straight to the CLI-only fallback below.**
138
- > `akan mcp --mode plan/apply` starts a stdio MCP server that only works when your agent is wired to it as an
139
- > MCP client. When those `list_workflows` / `plan_workflow` / `apply_workflow` tools are not available, the CLI
140
- > commands are a fully supported, first-class path — you are not losing any capability by using them.
141
-
142
- 1. **Plan** — Ask the Akan MCP server for the workflow first.
143
- ```
144
- akan mcp --mode plan
145
- # use list_workflows, explain_workflow, and plan_workflow
146
- ```
147
-
148
- 2. **Apply the plan** — If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call
149
- `apply_workflow({ planPath })`. Do not copy the workflow plan into direct source edits.
150
- ```
151
- akan mcp --mode apply
152
- # use apply_workflow, run_validation, repair_generated, repair_imports, or repair_module_shape
153
- ```
154
-
155
- Direct edits are fallback only: use them after `list_workflows`/`explain_workflow` confirm no matching workflow, or
156
- after apply reports unsupported/no-op/failed diagnostics that require manual action. Keep fallback edits to owning
157
- source files such as `task.constant.ts`, `task.dictionary.ts`, `Task.Template.tsx`, or `Task.Unit.tsx`.
158
-
159
- 3. **Validate the apply report** — Use the apply report artifact, not the original raw plan, when it is available.
160
- ```
161
- # run_validation with validationTarget first; otherwise use applyReportPath
162
- ```
163
-
164
- 4. **Sync or repair** — Regenerate barrel files so Akan discovers your change. This regenerates:
165
- `cnst.ts`, `db.ts`, `srv.ts`, `sig.ts`, `st.ts`, `dict.ts`, `useClient.ts`, `useServer.ts`,
166
- `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and all module `index.ts` files.
167
- ```
168
- akan sync <%= appName %>
169
- # or: akan repair generated --app <%= appName %>
170
- ```
171
- **CRITICAL**: Sync after EVERY file add, delete, or rename. Without sync, other modules cannot
172
- `import * as cnst from "../cnst"` and find your new model.
173
-
174
- 5. **Check** — Verify your change compiles and lints.
175
- ```
176
- akan start <%= appName %> # dev server with live feedback (preferred)
177
- akan lint <%= appName %> # quick lint-only check
178
- akan doctor --strict # structured workspace diagnostics
179
- ```
180
-
181
- If `akan sync` gives errors, try:
182
- - `akan build <%= appName %>` — full rebuild catches type errors sync may miss
183
- - Re-run `akan create-module <name> <%= appName %>` if the scaffold is corrupted
184
-
185
- For compound natural-language requests, split the request into workflows and apply each artifact in order. For example,
186
- "create a project module and add a budget field" should run `create-module` plan/apply first, then `add-field`
187
- plan/apply, then validation/doctor on the returned `validationTarget`.
188
-
189
- ### CLI-Only Fallback (MCP Not Connected)
190
-
191
- When the Akan MCP tools are not loaded, run the CLI commands directly. Each MCP tool maps 1:1 to a CLI command,
192
- and the CLI emits the same structured report via `--format json`:
193
-
194
- | MCP tool | CLI-only equivalent |
195
- |----------|---------------------|
196
- | `list_workflows` | `akan workflow list` |
197
- | `explain_workflow <name>` | `akan workflow explain <name>` |
198
- | `plan_workflow <name> ...` | `akan workflow plan <name> ... --format json --out <planPath>` |
199
- | `apply_workflow { planPath }` | `akan workflow apply <planPath> --format json` (add `--dry-run` to preview) |
200
- | `run_validation { validationTarget }` | `akan doctor --strict --format json` (or `akan typecheck <%= appName %>`) |
201
- | `repair_generated` / `repair_imports` / `repair_module_shape` | `akan repair generated\|imports\|module-shape --app <%= appName %> --format json` |
202
-
203
- The scaffolding primitives (`akan create-module`, `akan create-scalar`, `akan create-service`, `akan add-field`,
204
- `akan add-enum-field`) are the same primitives the workflows call, so `create-module <name> <%= appName %>` followed
205
- by `akan sync <%= appName %>` is equivalent to running the `create-module` workflow. Direct source edits remain the
206
- final fallback when no CLI command covers the change.
207
-
208
- ## Quick Decision Matrix — "Where do I put this code?"
209
-
210
- | You want to... | Create in... | Run after... |
211
- |----------------|-------------|--------------|
212
- | Define a new database-backed noun (e.g., User, Product) | `lib/<model>/` → constant, document, service, signal, store, dictionary, abstract | `akan sync <name>` |
213
- | Add a pure workflow / integration (e.g., Payment, Email) | `lib/_<service>/` → service, signal, store, dictionary, abstract | `akan sync <name>` |
214
- | Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan sync <name>` |
215
- | Create a new URL-visitable page | `page/` → `_index.tsx`, `_layout.tsx`, `[param]/_index.tsx` | Rebuild (akan start auto-detects) |
216
- | Change the app color theme / design tokens | `apps/<app>/page/styles.css` → override the semantic token values under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--primary`, `--background`, `--foreground`, …) | akan start hot-reloads |
217
- | Add a form or reusable UI component | `ui/` → PascalCase `.tsx`, **no** `"use client"` unless it uses a hook, event handler, store, or browser API | `akan sync <name>` |
218
- | Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan sync <name>` |
219
- | Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan sync <name>` |
220
- | Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan sync <name>` |
221
- | Make the app an iOS, Android or desktop app | `akan.config.ts` → `native: { … }`; `desktop: { server: true }` puts the server in the desktop app | `akan start-desktop <name>` (or `start-ios` / `start-android`) |
222
- | Add a device capability the framework lacks | `native/<id>/` → `native-plugin.json`, `src/index.ts` (page API, used from a `webkit/` hook), `src/desktop.ts`, Kotlin, Swift | the platform's `akan start-*` |
223
-
224
- ## Workflow Recipes
225
-
226
- Six worked recipes carry the full code for the most frequent Akan changes, together with the reference of what
227
- `akan sync` generates at each layer. They are **not** inlined here — fetch them when you are about to do one:
228
- `get_guideline` with `workspaceRecipes`, or `akan guideline show workspaceRecipes`.
229
-
230
- | Recipe | Covers |
231
- |---|---|
232
- | 1. Adding a field to a model | the five `constant.ts` classes, the dictionary entry, the store form, `akan sync` |
233
- | 2. Injecting a dependency into a service | `service<srv.XService>()`, `plug(Adapter)`, `env(...)`, `use<T>()`, writing an `adapt()` adapter |
234
- | 3. Creating and using a slice | `slice()` guards, the generated `init<Model><Suffix>`, `Load.Units` hydration |
235
- | 4. Creating a mutation endpoint | the document chain method, the service call, the signal `guards`, the store action |
236
- | 5. Internal triggers | `internal()` with interval and cron, queue retries and the dead letter |
237
- | 6. Creating an insight | the `XInsight` class, the aggregation, the dashboard tile |
238
- | Data Flow Summary | how a value travels page → store → signal → service → document → DB |
239
- | Auto-Generated API Reference | what signal, service, store, and document each generate — never hand-write these |
240
-
241
- The rules those recipes obey are in this file; the recipes only show the code. When you edit a file, read the
242
- existing content first and change only the relevant sections — never rewrite a whole file.
243
-
244
- ## Modeling & Query Gotchas
245
-
246
- A short list of things the type system does not always catch. The full rules for text search, `cascade`, and the
247
- query-level writes are in `queryRule`; these are the shapes that build green and fail later.
248
-
249
- - **Slices return a query, not a list.** A slice `exec` must return `this.<model>Service.query<Filter>(...)`, never
250
- a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
251
- `Unknown document field path: 0`. (See Recipe 3.)
252
- - **Custom endpoint names must not collide with generated CRUD.** `create/update/remove/view/edit/merge<Model>`
253
- already exist wherever the slice mounts the verb. A collision builds green and the server refuses to boot
254
- (`[DI:fetch]`) — pick a distinct verb.
255
- - **Numbers are `Int` or `Float`, never `Number`.** `field(Number)` / `.body("x", Number)` fail to typecheck.
256
- - **Array fields use `field([T])`** — `tags: field([String])`, `images: field([File])`.
257
- - **Reading a secret field needs an explicit select, and the two call sites spell it differently.**
258
- `field(...).secret()` values are stripped from query results by default. The model facade takes the projection
259
- **bare** — `this.userModel.pickById(id, { passwordHash: true })`, likewise `pickOne` / `find` / `findOne` /
260
- `findById`. A generated filter accessor takes it **inside the option object** —
261
- `this.userModel.findByAccountId(accountId, statuses, { select: { passwordHash: true } })`. Handing `{ select: … }`
262
- to the facade projects a field named `select`, which no model has, and throws `Unknown document field path`.
263
- - **`cascade` names a direction, and the wrong one is a data loss** — `removeRef` on the relation the owner holds,
264
- `removeWith` on the child's reference to its owner. A query-level removal fires no hooks and therefore no cascade.
265
- - **`q.search()` is a filter node, not a slice requirement.** `bySearch: filter().arg("text", String).query((text,
266
- q) => q.search(text, { prefix: true }))` generates `listBySearch` / `countBySearch` / `queryBySearch` /
267
- `insightBySearch` for free. Only add a search *slice* when the model's data is safe to enumerate.
268
-
269
- ## Current User, Guards & Auth-Gated Pages
270
-
271
- Built-in user authentication (session / JWT / password hashing) ships as a separate Akan auth library, not in the
272
- core framework. The core framework gives you the composition points below; wire the auth library through them.
273
-
274
- - **A `slice()` takes its guard map as a second argument**, `slice(srv.task, { guards: { root: Admin, get: SignedIn,
275
- cru: SignedIn } }, (init) => ({...}))`. An `endpoint()` takes no guard argument at all —
276
- `endpoint(srv.task, ({ mutation }) => ({...}))` — so **every custom `mutation` / `query` / `message` names its own
277
- `guards: [...]` array**: `mutation(cnst.Task, { guards: [SignedIn] })`. `Public` always allows; other guards
278
- implement the `Guard` interface in `srvkit/` (server-only).
279
- - **Read the caller inside a guard** with `context.get<T>("account")`, which works on HTTP and websocket calls
280
- alike — never branch on `getHttpContext()` / `getWebSocketContext()`. Every guard class also declares
281
- `static scope: GuardScope`, `"account"` or `"resource"`, with no default.
282
- - **Read the current user inside a custom endpoint** by injecting an `InternalArg` with `.with(...)`:
283
- `mutation(cnst.Task, { guards: [SignedIn] }).with(CurrentUserId).exec(async function (currentUserId) { ... })`.
284
- - **Auto-generated CRUD and `serve()` service methods / lifecycle hooks do not receive session context.** If an
285
- operation needs the acting user, expose a custom endpoint that takes it via `.with(CurrentUserId)` — never trust a
286
- client-supplied user id.
287
- - **SSR auth-gated pages: guard at the layout.** `.guard(() => signedIn())` on the `_layout.tsx` chain answers a
288
- real 307 before any of it renders, so nested pages never render for signed-out users; a check in `.render()`
289
- after awaited I/O redirects in-page, as an HTTP 200. `signedIn()` comes from `@libs/shared/webkit`, which a new
290
- workspace has only with `create-workspace --libs true`.
291
-
package/index-4t4qb8jg.js DELETED
@@ -1,279 +0,0 @@
1
- // @bun
2
- import {
3
- runner,
4
- script
5
- } from "./index-00ke4phc.js";
6
- import {
7
- AGENT_BLOCK_START,
8
- AGENT_BLOCK_END,
9
- stampBlockVersion,
10
- readDevkitVersion,
11
- upsertAgentBlock,
12
- renderRecipeEntries,
13
- CLAUDE_COMMENT_RULE,
14
- AppExecutor,
15
- LibExecutor
16
- } from "./index-921cxqrd.js";
17
- import {
18
- collectRecipeSources2,
19
- scanRecipes2
20
- } from "./index-hj6w4ka1.js";
21
- import {
22
- AkanContextAnalyzer
23
- } from "./index-s4c2y5gs.js";
24
- import {
25
- Prompter2
26
- } from "./index-zzvvc845.js";
27
-
28
- // pkgs/@akanjs/cli/agent/agent.script.ts
29
- import { Logger as Logger2 } from "akanjs/common";
30
-
31
- // pkgs/@akanjs/cli/agent/agent.runner.ts
32
- import { Logger } from "akanjs/common";
33
- var targetPaths = {
34
- cursor: ".cursor/rules/akan.mdc",
35
- "agents-md": "AGENTS.md",
36
- claude: "CLAUDE.md"
37
- };
38
- var SAMPLE_ARTIFACTS = [
39
- { probe: "lib/task/task.constant.ts", target: "lib/task", label: "sample database module" },
40
- { probe: "lib/_noti/noti.service.ts", target: "lib/_noti", label: "sample service module" },
41
- {
42
- probe: "lib/__scalar/workHistory/workHistory.dictionary.ts",
43
- target: "lib/__scalar/workHistory",
44
- label: "sample scalar module"
45
- },
46
- { probe: "page/task/_index.tsx", target: "page/task", label: "sample task pages" }
47
- ];
48
- var DEFAULT_INDEX_MARKER = "Akan.js template";
49
- var renderSampleCleanup = async (workspace, appNames) => {
50
- const items = [];
51
- for (const appName of appNames) {
52
- for (const artifact of SAMPLE_ARTIFACTS) {
53
- if (await workspace.exists(`apps/${appName}/${artifact.probe}`)) {
54
- items.push(`- \`apps/${appName}/${artifact.target}\` \u2014 ${artifact.label}; delete it once you no longer need the reference.`);
55
- }
56
- }
57
- const indexPath = `apps/${appName}/page/_index.tsx`;
58
- if (await workspace.exists(indexPath)) {
59
- const content = await workspace.readFile(indexPath).catch(() => "");
60
- if (content.includes(DEFAULT_INDEX_MARKER)) {
61
- items.push(`- \`${indexPath}\` \u2014 default Akan landing page; replace it with your own home page.`);
62
- }
63
- }
64
- }
65
- if (items.length === 0)
66
- return "";
67
- return `## Start Clean (Remove Scaffolded Samples)
68
-
69
- This workspace was scaffolded with reference samples so the Akan conventions are visible in real code. They are
70
- not part of your product. Before building real features, remove the samples below and run \`akan sync <app>\`:
71
-
72
- ${items.join(`
73
- `)}
74
-
75
- Keep a sample only while you are still learning its pattern; delete it once your own modules cover the same ground.
76
-
77
- `;
78
- };
79
- var renderRecipeIndex = async (workspace) => {
80
- const sources = await collectRecipeSources2(`${workspace.workspaceRoot}/pkgs/akanjs/ui`, "akanjs/ui", "recipe");
81
- const recipes = scanRecipes2(sources);
82
- const scopeIndexPointer = `App and lib recipes are **not** listed here. Each app/lib carries its own generated index \u2014
83
- \`apps/<app>/AGENTS.md\` / \`libs/<lib>/AGENTS.md\` (\`## Recipes In Scope\`) \u2014 regenerated by \`akan sync\` and
84
- verified by \`akan lint\`. When working inside an app or lib, consult that file before consuming or authoring a look.`;
85
- if (recipes.length === 0)
86
- return `## Recipes
87
-
88
- ${scopeIndexPointer}
89
-
90
- `;
91
- return `## Recipes
92
-
93
- Framework UI recipes (Tailwind-variant look factories), importable from every app and lib: \`import { <name> } from
94
- "akanjs/ui"\`, then \`<name>(variants?, className?)\`. The second arg merges internally and takes **an array too**, so
95
- never wrap it in \`cn()\`: \`<name>({}, ["h-full", isWide && "w-full", className])\`. The list below is the full
96
- contract (\`*\` marks the default, \`key?\` is a boolean flag) \u2014 do not guess a name, path, or variant value, and do
97
- not open the recipe file to consume one. **Before inlining a repeated surface (card, box, tile, \u2026): reuse a recipe,
98
- or add one as \`apps/<app>/ui/Recipe/<name>.ts\`, one per file, re-exported from that folder's \`index.ts\` \u2014 never
99
- re-implement the same look inline in several places, and never author a near-duplicate.** Full policy: the
100
- \`recipeRule\` guideline.
101
-
102
- ${renderRecipeEntries(recipes)}
103
-
104
- ${scopeIndexPointer}
105
-
106
- `;
107
- };
108
- var renderGuides = async (context) => {
109
- const conventions = (await Prompter2.getInstruction("conventions")).trim();
110
- if (context.pkgs.some((pkg) => pkg.name === "akanjs"))
111
- return conventions;
112
- const onboarding = (await Prompter2.getInstruction("workspaceOnboarding")).trim();
113
- const appName = context.apps[0]?.name ?? "app";
114
- return `${conventions}
115
-
116
- ${onboarding.replaceAll("<%= appName %>", appName)}`;
117
- };
118
- var renderManagedBlock = async (workspace) => {
119
- const context = await AkanContextAnalyzer.analyze(workspace);
120
- const frameworkGuide = await Prompter2.getInstruction("framework");
121
- const appNames = context.apps.map((app) => app.name);
122
- const sampleCleanup = await renderSampleCleanup(workspace, appNames);
123
- const recipeIndex = await renderRecipeIndex(workspace);
124
- const guides = await renderGuides(context);
125
- const version = await readDevkitVersion();
126
- const block = `## Workspace
127
-
128
- - Repo: ${context.repoName}
129
- - Apps: ${appNames.join(", ") || "none"}
130
- - Libraries: ${context.libs.map((lib) => lib.name).join(", ") || "none"}
131
- - Packages: ${context.pkgs.map((pkg) => pkg.name).join(", ") || "none"}
132
-
133
- ${guides}
134
-
135
- ${sampleCleanup}## Akan Module Abstracts
136
-
137
- - Before changing a domain, service, or scalar module, read its \`*.abstract.md\` file first.
138
- - Update the abstract when business invariants, workflows, or public behavior change.
139
- - Do not update the abstract for formatting-only, import-only, or style-only changes.
140
- - Service modules live in \`lib/_<service>\`, but their abstract file is \`<service>.abstract.md\`.
141
- - Keep an abstract short \u2014 the invariants the code cannot show, and nothing it already states. \`akan quality scan\` warns past 300 lines.
142
-
143
- ## Generated Files
144
-
145
- Do not hand-edit generated Akan files such as ${context.generatedFiles.map((file) => `\`${file}\``).join(", ")}.
146
- If generated output is stale or broken, update the owning source file and run \`akan repair generated\` or \`akan sync <app-or-lib>\`.
147
-
148
- ${recipeIndex}## MCP Workflow Policy
149
-
150
- - **Prefer an Akan workflow to a direct source edit.** A direct edit is denied when an allowlisted workflow or repair tool can make the change.
151
- - Inspect with \`akan mcp --mode plan\` (\`list_workflows\`, \`explain_workflow\`, \`plan_workflow\`); apply with \`akan mcp --mode apply\`, which allowlists \`apply_workflow\`, \`run_validation\`, and three of the five repair tools \u2014 \`repair_generated\`, \`repair_imports\` and \`repair_module_shape\`. \`akan repair format\` and \`akan repair dictionary\` are CLI-only.
152
- - If \`plan_workflow\` returns \`planPath\` or \`next.tool=apply_workflow\`, call \`apply_workflow({ planPath })\` before editing source. Then run \`run_validation\` with \`validationTarget\` when present, otherwise \`applyReportPath\`.
153
- - Split a compound request into workflows and apply each \`planPath\` in order, such as \`create-module\` followed by \`add-field\`.
154
- - When no workflow exists, or apply reports unsupported/no-op/failed diagnostics needing manual action, keep edits scoped to owning source files and never patch generated files directly.
155
- - **MCP not connected?** The CLI is a first-class equivalent \u2014 \`akan workflow list\` / \`explain\` / \`plan\` / \`apply\`, \`akan doctor\`, \`akan repair\`. See the onboarding guide's CLI-only fallback for the exact flags.
156
-
157
- ## Validation
158
-
159
- ${context.validationCommands.map((command) => `- \`${command}\``).join(`
160
- `)}
161
-
162
- ## Framework Guide
163
-
164
- ${frameworkGuide.trim()}
165
-
166
- ## Before You Finish
167
-
168
- 1. \`bun run akan lint <appName>\` \u2014 Tailwind class order, \`Err\`, \`console\`, \`#private\` scope, unused imports.
169
- 2. \`bun run akan typecheck <appName>\` \u2014 server/client boundary violations, and the tests and specs nothing imports.
170
- 3. \`bun run akan sync <appName>\` if you added, renamed, or deleted any file.
171
- 4. Did you write or change a \`.tsx\` file? \`bun run akan quality ssr\` \u2014 did the server share hold, and did you add
172
- a \`"use client"\` you cannot justify?
173
- 5. Re-read the file you wrote against its section above.
174
- 6. Did you add a comment? Delete it unless it documents an external constraint or a security decision.
175
- 7. Did behavior or an invariant change? Update the module's \`*.abstract.md\`.`;
176
- return version ? stampBlockVersion(block, version) : block;
177
- };
178
- var renderAgentsMd = async (workspace, existing) => {
179
- const block = await renderManagedBlock(workspace);
180
- if (existing?.trim())
181
- return upsertAgentBlock(existing, block);
182
- const context = await AkanContextAnalyzer.analyze(workspace);
183
- return `# ${context.repoName} Agent Guide
184
-
185
- This file is the single source of truth for coding agents in this workspace. Claude Code reads it through
186
- \`CLAUDE.md\` (\`@AGENTS.md\`) and Cursor through \`.cursor/rules/akan.mdc\`. The section between the
187
- \`akan:agent\` markers is regenerated by \`akan agent install\`; edit anything outside the markers freely.
188
-
189
- ${AGENT_BLOCK_START}
190
- ${block}
191
- ${AGENT_BLOCK_END}
192
- `;
193
- };
194
- var renderClaudeMd = async (workspace) => {
195
- const context = await AkanContextAnalyzer.analyze(workspace);
196
- return `# ${context.repoName} \u2014 Claude Code Guide
197
-
198
- @AGENTS.md
199
-
200
- ${CLAUDE_COMMENT_RULE}
201
- `;
202
- };
203
- var renderCursorRule = () => `---
204
- description: Akan workspace agent guide
205
- alwaysApply: true
206
- ---
207
-
208
- Follow the workspace agent guide, which is the single source of truth for Akan conventions,
209
- generated-file rules, and the MCP workflow policy.
210
-
211
- @AGENTS.md
212
- `;
213
- var renderTarget = async (workspace, target, existing) => {
214
- if (target === "agents-md")
215
- return await renderAgentsMd(workspace, existing);
216
- if (target === "claude")
217
- return await renderClaudeMd(workspace);
218
- return renderCursorRule();
219
- };
220
-
221
- class AgentRunner extends runner("agent") {
222
- async install(workspace, targets, { force = false } = {}) {
223
- const written = [];
224
- for (const target of targets) {
225
- const filePath = targetPaths[target];
226
- const exists = await workspace.exists(filePath);
227
- if (exists && !force && target !== "agents-md") {
228
- throw new Error(`${filePath} already exists. Re-run with --force to overwrite it.`);
229
- }
230
- const existing = exists ? await workspace.readFile(filePath) : null;
231
- const content = await renderTarget(workspace, target, existing);
232
- await workspace.writeFile(filePath, content, { overwrite: true });
233
- written.push(filePath);
234
- }
235
- if (targets.includes("agents-md"))
236
- written.push(...await this.#installScopeIndexes(workspace));
237
- return written;
238
- }
239
- async#installScopeIndexes(workspace) {
240
- const [appNames, libNames] = await workspace.getExecs();
241
- const written = [];
242
- const syncScope = async (exec) => {
243
- try {
244
- await exec.syncAgentsIndex();
245
- written.push(`${exec.type}s/${exec.name}/AGENTS.md`);
246
- } catch (error) {
247
- const message = error instanceof Error ? error.message : String(error);
248
- Logger.rawLog(`Skipped ${exec.type}s/${exec.name}/AGENTS.md (${message})`, undefined, "error");
249
- }
250
- };
251
- for (const name of libNames)
252
- await syncScope(LibExecutor.from(workspace, name));
253
- for (const name of appNames)
254
- await syncScope(AppExecutor.from(workspace, name));
255
- return written;
256
- }
257
- }
258
-
259
- // pkgs/@akanjs/cli/agent/agent.script.ts
260
- var resolveTargets = (target) => {
261
- if (!target || target === "all")
262
- return ["cursor", "agents-md", "claude"];
263
- if (target === "cursor" || target === "agents-md" || target === "claude")
264
- return [target];
265
- throw new Error(`Unknown agent target: ${target}. Use cursor, agents-md, claude, or all.`);
266
- };
267
-
268
- class AgentScript extends script("agent", [AgentRunner]) {
269
- async agent(workspace, action, target, { force = false } = {}) {
270
- if (action !== "install")
271
- throw new Error(`Unknown agent action: ${action}. Use "install".`);
272
- const written = await this.agentRunner.install(workspace, resolveTargets(target), { force });
273
- Logger2.rawLog(`Agent rules written:
274
- ${written.map((file) => `- ${file}`).join(`
275
- `)}`);
276
- }
277
- }
278
-
279
- export { AgentScript };