@akanjs/cli 3.1.1-rc.9 → 3.1.1

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 (184) hide show
  1. package/.build-stamp +1 -1
  2. package/CodeAgent-35wnb7w5.js +9 -0
  3. package/{CodeTui-z5vkm9ea.js → CodeTui-h6yz2kvq.js} +1 -1
  4. package/TunnelShare-xyjpa7gx.js +14 -0
  5. package/agent.command-3r4jsck8.js +46 -0
  6. package/akanCode.js +10 -6
  7. package/{application.command-wthg8nn9.js → application.command-g7xv6ad0.js} +44 -11
  8. package/{applicationBuildRunner-t2r84sz6.js → applicationBuildRunner-qvjnhr9j.js} +9 -6
  9. package/buildBatch.proc.js +6 -6
  10. package/{cloud.command-sz11hpre.js → cloud.command-6ebygmhw.js} +17 -15
  11. package/cloud.script-0s1jybd5.js +26 -0
  12. package/{code.command-9h3yrzhe.js → code.command-mpkm2emr.js} +6 -6
  13. package/commandManifest.json +1 -1
  14. package/{context.command-15j9b7c0.js → context.command-svdh6b2w.js} +18 -17
  15. package/context.runner-ch0z3a8g.js +26 -0
  16. package/{devTui-q7k7bakd.js → devTui-evr3b35y.js} +1 -1
  17. package/{guideline.command-snh85ctf.js → guideline.command-qwp3tnjx.js} +3 -3
  18. package/guidelines/conventions/core.md +106 -0
  19. package/guidelines/conventions/rules/app.md +83 -0
  20. package/guidelines/conventions/rules/auth.md +45 -0
  21. package/guidelines/conventions/rules/config.md +56 -0
  22. package/guidelines/conventions/rules/constant.md +24 -0
  23. package/guidelines/conventions/rules/gates.md +31 -0
  24. package/guidelines/conventions/rules/layer.md +25 -0
  25. package/guidelines/conventions/rules/migration.md +27 -0
  26. package/guidelines/conventions/rules/module.md +90 -0
  27. package/guidelines/conventions/rules/page.md +56 -0
  28. package/guidelines/conventions/rules/sensitive.md +16 -0
  29. package/guidelines/conventions/rules/server.md +86 -0
  30. package/guidelines/conventions/rules/ssr.md +47 -0
  31. package/guidelines/conventions/rules/style.md +43 -0
  32. package/guidelines/conventions/rules/test.md +34 -0
  33. package/guidelines/conventions/rules/ts.md +95 -0
  34. package/guidelines/conventions/rules/tsx.md +75 -0
  35. package/guidelines/mcpRule/mcpRule.instruction.md +1 -1
  36. package/guidelines/pageRule/pageRule.instruction.md +4 -3
  37. package/guidelines/queryRule/queryRule.instruction.md +4 -0
  38. package/guidelines/workspaceRecipes/workspaceRecipes.instruction.md +3 -3
  39. package/incrementalBuilder.proc.js +6 -6
  40. package/{index-pcwzkdqb.js → index-1p0qbq3m.js} +1 -1
  41. package/{index-xb8809yb.js → index-1shvxzt0.js} +3 -3
  42. package/{index-a58emady.js → index-266dewjs.js} +11 -11
  43. package/{index-bt438yxm.js → index-3yz30c07.js} +5 -4
  44. package/{index-xjf5j657.js → index-4mj92tsh.js} +952 -47
  45. package/index-4pdts00b.js +1604 -0
  46. package/{index-42j4a8zq.js → index-8559hsz4.js} +4 -3
  47. package/{index-wcej7g4z.js → index-8scw1pjk.js} +93 -23
  48. package/{index-a5dhqkdr.js → index-96wzdhfh.js} +74 -233
  49. package/index-9bv479q5.js +1 -0
  50. package/index-9rvcs76p.js +653 -0
  51. package/index-am36s3jh.js +3582 -0
  52. package/index-b8c289dx.js +444 -0
  53. package/{index-espk51ah.js → index-dd44g6vz.js} +3 -3
  54. package/{index-3wypz6xj.js → index-eja64h28.js} +7 -3
  55. package/index-fbewhg4g.js +590 -0
  56. package/index-jje9qzyq.js +27 -0
  57. package/{index-j9vyj3dj.js → index-k5jbcxyh.js} +3 -3
  58. package/{index-2mwc0g0d.js → index-ksfgqq1x.js} +1 -1
  59. package/index-m5n3ka0p.js +18 -0
  60. package/{index-5nd1wtkv.js → index-p6x5b7hr.js} +1 -1
  61. package/{index-6txx6a9p.js → index-payhwt51.js} +21 -29
  62. package/{index-2azahjaw.js → index-qkkdhjm6.js} +2 -2
  63. package/{index-74tjjsnc.js → index-qxzrp5xt.js} +33 -37
  64. package/{index-qfp55x1y.js → index-r0k3ham2.js} +4 -4
  65. package/{index-hmt54t45.js → index-r2w2eh93.js} +4 -4
  66. package/index-r2wedvqn.js +138 -0
  67. package/{index-skk9zc1x.js → index-rnphv731.js} +2 -2
  68. package/{index-9th4gszy.js → index-s6da8ta9.js} +82 -1227
  69. package/index-tenw3mah.js +225 -0
  70. package/{index-31es1yev.js → index-tgt2fnd6.js} +107 -6
  71. package/{index-55j120r8.js → index-vxmy1p4f.js} +16 -36
  72. package/{index-301pdbzz.js → index-w4k2ragk.js} +7 -7
  73. package/{index-js6geqjn.js → index-w7q6h97v.js} +1 -1
  74. package/{index-dy0jx9ay.js → index-wwe9rsrx.js} +14 -0
  75. package/{index-2xcc2ax5.js → index-xq543a5y.js} +2 -2
  76. package/{index-0fz95kxe.js → index-xqgwjz7a.js} +1 -1
  77. package/{index-40brg4px.js → index-xxfy1jp2.js} +4 -4
  78. package/{index-905qdgqp.js → index-z4b84y6k.js} +1 -1
  79. package/index-zcf6k8a5.js +410 -0
  80. package/index.js +23 -22
  81. package/{library.command-gycrwhf1.js → library.command-2853y6mk.js} +3 -3
  82. package/{localRegistry.command-jtd8gaes.js → localRegistry.command-76ds31p4.js} +19 -15
  83. package/{module.command-v6hgs1bc.js → module.command-yfnb0abs.js} +5 -5
  84. package/{package.command-shzpcfph.js → package.command-d9s86hp9.js} +3 -3
  85. package/package.json +2 -2
  86. package/{page.command-ptxn5kqk.js → page.command-6a8a8rd1.js} +3 -3
  87. package/{pipeline.command-zz31pgax.js → pipeline.command-rt3rwd2z.js} +2 -2
  88. package/{primitive.command-a1vse91z.js → primitive.command-emcebgrq.js} +6 -6
  89. package/{projectTypecheck-2ztky9cf.js → projectTypecheck-51m7eh1f.js} +1 -1
  90. package/{prompter-76k56b37.js → prompter-hgcta8pb.js} +1 -1
  91. package/quality.command-xtrk0n3x.js +76 -0
  92. package/{repair.command-cvazbz99.js → repair.command-51szxnxx.js} +5 -5
  93. package/{routeSourceValidator-6jd0q6r6.js → routeSourceValidator-4h947v7c.js} +13 -3
  94. package/{scalar.command-0acvyp26.js → scalar.command-8qv27t82.js} +4 -4
  95. package/skills/akan-agent/SKILL.md +36 -0
  96. package/skills/akan-code/SKILL.md +1 -0
  97. package/skills/akan-debug/SKILL.md +40 -6
  98. package/skills/akan-deps/SKILL.md +1 -2
  99. package/skills/akan-mcp/SKILL.md +40 -0
  100. package/skills/akan-page/SKILL.md +44 -0
  101. package/skills/akan-query/SKILL.md +38 -0
  102. package/skills/akan-runtime/SKILL.md +40 -0
  103. package/skills/akan-scaffold/SKILL.md +16 -6
  104. package/skills/akan-transport/SKILL.md +40 -0
  105. package/skills/akan-validate/SKILL.md +13 -11
  106. package/{subspace.command-822qx2bx.js → subspace.command-pn56pnh8.js} +8 -8
  107. package/templates/__scalar/__model__/__model__.constant.ts +3 -5
  108. package/templates/__scalar/__model__/__model__.dictionary.ts +6 -5
  109. package/templates/__scalar/__model__/__model__.document.ts +3 -3
  110. package/templates/app/akan.config.ts +2 -3
  111. package/templates/app/env/env.client.ts +2 -4
  112. package/templates/app/env/env.client.type.ts +2 -3
  113. package/templates/app/env/env.server.ts +2 -3
  114. package/templates/app/lib/___appName__/__appName__.dictionary.ts +1 -2
  115. package/templates/app/lib/___appName__/__appName__.service.ts +3 -3
  116. package/templates/app/lib/___appName__/__appName__.signal.ts +5 -5
  117. package/templates/app/lib/___appName__/__appName__.store.ts +4 -6
  118. package/templates/app/lib/option.ts +2 -3
  119. package/templates/app/main.ts +2 -4
  120. package/templates/app/page/_index.tsx +3 -3
  121. package/templates/app/page/_layout.tsx +13 -10
  122. package/templates/appSample/lib/__scalar/workHistory/workHistory.constant.ts +1 -5
  123. package/templates/appSample/lib/__scalar/workHistory/workHistory.dictionary.ts +1 -1
  124. package/templates/appSample/lib/_noti/noti.signal.ts +1 -1
  125. package/templates/appSample/lib/task/Task.Template.tsx +2 -1
  126. package/templates/appSample/lib/task/Task.Unit.tsx +3 -2
  127. package/templates/appSample/lib/task/Task.Util.tsx +16 -4
  128. package/templates/appSample/lib/task/task.constant.ts +1 -5
  129. package/templates/appSample/lib/task/task.dictionary.ts +2 -8
  130. package/templates/appSample/lib/task/task.document.ts +1 -1
  131. package/templates/appSample/page/task/_index.tsx +2 -1
  132. package/templates/appSample/page/task/new.tsx +2 -1
  133. package/templates/appSample/ui/QuantityControl.tsx +5 -9
  134. package/templates/biomeForm.ts +144 -0
  135. package/templates/crudPages/[__model__Id]/edit/page.tsx +3 -3
  136. package/templates/crudPages/[__model__Id]/page.tsx +5 -5
  137. package/templates/crudPages/new/page.tsx +4 -3
  138. package/templates/crudPages/page.tsx +3 -3
  139. package/templates/crudSinglePage/page.tsx +9 -5
  140. package/templates/libRoot/akan.config.ts +2 -3
  141. package/templates/libRoot/lib/___libName__/__libName__.dictionary.ts +1 -2
  142. package/templates/libRoot/lib/___libName__/__libName__.service.ts +5 -4
  143. package/templates/libRoot/lib/___libName__/__libName__.signal.ts +6 -5
  144. package/templates/libRoot/lib/___libName__/__libName__.store.ts +5 -6
  145. package/templates/libRoot/lib/option.ts +1 -2
  146. package/templates/module/__Model__.Template.tsx +11 -10
  147. package/templates/module/__Model__.Unit.tsx +18 -5
  148. package/templates/module/__Model__.Util.tsx +9 -7
  149. package/templates/module/__Model__.View.tsx +9 -6
  150. package/templates/module/__Model__.Zone.tsx +25 -17
  151. package/templates/module/__model__.constant.ts +8 -9
  152. package/templates/module/__model__.dictionary.ts +16 -17
  153. package/templates/module/__model__.document.ts +6 -8
  154. package/templates/module/__model__.service.ts +3 -3
  155. package/templates/module/__model__.signal.ts +11 -10
  156. package/templates/module/__model__.store.ts +3 -5
  157. package/templates/service/__model__.dictionary.ts +6 -5
  158. package/templates/service/__model__.service.ts +3 -3
  159. package/templates/service/__model__.signal.ts +5 -4
  160. package/templates/service/__model__.store.ts +3 -5
  161. package/templates/workspaceRoot/.gitignore.template +3 -0
  162. package/templates/workspaceRoot/.vscode/settings.json.template +21 -21
  163. package/templates/workspaceRoot/AGENTS.md.template +4 -10
  164. package/{tunnel.command-ycmja19q.js → tunnel.command-q2h0j2en.js} +7 -7
  165. package/{typeChecker-px49mezc.js → typeChecker-j2jdnqsr.js} +1 -1
  166. package/typecheck.proc.js +6 -1
  167. package/verify.command-z1dsbmrt.js +91 -0
  168. package/{workflow.command-abb1d5xy.js → workflow.command-r3y67jeq.js} +47 -13
  169. package/workspace.command-t2f0xsrw.js +263 -0
  170. package/CodeAgent-8d5qs787.js +0 -9
  171. package/TunnelShare-qkm8zp03.js +0 -14
  172. package/agent.command-ydftceda.js +0 -25
  173. package/cloud.script-nqevg5qw.js +0 -24
  174. package/context.runner-8gg030b0.js +0 -25
  175. package/guidelines/conventions/conventions.instruction.md +0 -617
  176. package/guidelines/workspaceOnboarding/workspaceOnboarding.instruction.md +0 -291
  177. package/index-4vgbysa0.js +0 -279
  178. package/index-7md2g9vw.js +0 -6
  179. package/index-b70zct19.js +0 -856
  180. package/index-zzvvc845.js +0 -74
  181. package/quality.command-ah8qcakd.js +0 -1478
  182. package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template +0 -69
  183. package/templates/workspaceRoot/docs/GENERATED.md.template +0 -55
  184. package/workspace.command-qm7cw29v.js +0 -521
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  ProjectTypecheck2
4
- } from "./index-wcej7g4z.js";
4
+ } from "./index-8scw1pjk.js";
5
5
  export {
6
6
  ProjectTypecheck2 as ProjectTypecheck
7
7
  };
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  Prompter2
4
- } from "./index-zzvvc845.js";
4
+ } from "./index-r2wedvqn.js";
5
5
  import"./index-52w0fvh8.js";
6
6
  export {
7
7
  Prompter2 as Prompter
@@ -0,0 +1,76 @@
1
+ // @bun
2
+ import {
3
+ Workspace,
4
+ script,
5
+ command
6
+ } from "./index-eja64h28.js";
7
+ import"./index-52w0fvh8.js";
8
+ import {
9
+ AppExecutor,
10
+ LibExecutor
11
+ } from "./index-8scw1pjk.js";
12
+ import {
13
+ MaintainabilityBaseline,
14
+ WorkspaceRunner,
15
+ AkanQualityScanner,
16
+ formatQualityScanResult,
17
+ formatSsrScanResult
18
+ } from "./index-am36s3jh.js";
19
+ import"./index-62md4dwy.js";
20
+ import"./index-hj6w4ka1.js";
21
+ import"./index-fbewhg4g.js";
22
+
23
+ // pkgs/@akanjs/cli/quality/quality.script.ts
24
+ import { Logger } from "akanjs/common";
25
+ class QualityScript extends script("quality", [WorkspaceRunner]) {
26
+ async scan(workspace, format = "text") {
27
+ const spinner = workspace.spinning("Scanning Akan code quality...");
28
+ const result = await new AkanQualityScanner().scan(workspace.workspaceRoot);
29
+ spinner.succeed(`Quality scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
30
+ Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatQualityScanResult(result));
31
+ }
32
+ async ssr(workspace, format = "text") {
33
+ const spinner = workspace.spinning("Measuring Akan server/client render balance...");
34
+ const scanned = await new AkanQualityScanner().scan(workspace.workspaceRoot);
35
+ const result = { ...scanned, warnings: scanned.warnings.filter((warning) => warning.scope === "ssr") };
36
+ spinner.succeed(`SSR scan completed (${result.scannedFiles} files, ${result.warnings.length} warnings)`);
37
+ Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatSsrScanResult(result));
38
+ }
39
+ async baseline(workspace, { force = false } = {}) {
40
+ const [appNames, libNames] = await workspace.getExecs();
41
+ const execs = [
42
+ ...appNames.map((appName) => AppExecutor.from(workspace, appName)),
43
+ ...libNames.map((libName) => LibExecutor.from(workspace, libName))
44
+ ];
45
+ const { fileName } = MaintainabilityBaseline;
46
+ for (const exec of execs) {
47
+ const contract = await this.workspaceRunner.maintainabilityContractOf(exec);
48
+ const { result, violations } = await contract.seed({ force });
49
+ const outcome = {
50
+ written: `wrote ${fileName} with ${violations.length} entries`,
51
+ kept: `kept the existing ${fileName} (${violations.length} current violations); --force rewrites it`,
52
+ removed: `no violations, removed ${fileName}`,
53
+ clean: "no violations"
54
+ }[result];
55
+ Logger.rawLog(`${contract.sysPath}: ${outcome}`);
56
+ }
57
+ }
58
+ }
59
+
60
+ // pkgs/@akanjs/cli/quality/quality.command.ts
61
+ class QualityCommand extends command("quality", [QualityScript], ({ public: target }) => ({
62
+ quality: target({ desc: "Scan apps and libs for Akan code quality warnings" }).arg("action", String, { desc: "quality action", default: "scan", enum: ["scan", "ssr", "baseline"] }).option("format", String, { desc: "output format", default: "text", enum: ["text", "json"] }).option("force", Boolean, { flag: "F", desc: "baseline: rewrite an existing akan.baseline.json", default: false }).with(Workspace).exec(async function(action, format, force, workspace) {
63
+ if (action === "scan")
64
+ await this.qualityScript.scan(workspace, format);
65
+ else if (action === "ssr")
66
+ await this.qualityScript.ssr(workspace, format);
67
+ else if (action === "baseline")
68
+ await this.qualityScript.baseline(workspace, { force });
69
+ else
70
+ throw new Error(`Unknown quality action: ${action}. Use "scan", "ssr" or "baseline".`);
71
+ })
72
+ })) {
73
+ }
74
+ export {
75
+ QualityCommand
76
+ };
@@ -3,15 +3,15 @@ import {
3
3
  Workspace,
4
4
  script,
5
5
  command
6
- } from "./index-3wypz6xj.js";
6
+ } from "./index-eja64h28.js";
7
7
  import"./index-52w0fvh8.js";
8
- import"./index-wcej7g4z.js";
8
+ import"./index-8scw1pjk.js";
9
9
  import"./index-hj6w4ka1.js";
10
- import"./index-xjf5j657.js";
11
- import"./index-31es1yev.js";
10
+ import"./index-4mj92tsh.js";
11
+ import"./index-tgt2fnd6.js";
12
12
  import {
13
13
  RepairRunner
14
- } from "./index-j9vyj3dj.js";
14
+ } from "./index-k5jbcxyh.js";
15
15
 
16
16
  // pkgs/@akanjs/cli/repair/repair.script.ts
17
17
  import { Logger } from "akanjs/common";
@@ -77,7 +77,9 @@ class RouteSourceValidator {
77
77
  kind: chain.kind,
78
78
  params: chain.params,
79
79
  ...chain.prompt ? { prompt: chain.prompt } : {},
80
- apps: chain.apps
80
+ apps: chain.apps,
81
+ search: chain.search,
82
+ guarded: chain.guarded
81
83
  }
82
84
  };
83
85
  }
@@ -128,8 +130,10 @@ class RouteSourceValidator {
128
130
  static #chainOf(kind, stages, filePath) {
129
131
  const params = [];
130
132
  const apps = [];
133
+ const search = [];
131
134
  let prompt;
132
135
  let devOnly = false;
136
+ let guarded = false;
133
137
  const literal = (stage) => {
134
138
  const first = stage.args[0];
135
139
  if (!first || !ts.isStringLiteralLike(first))
@@ -143,10 +147,16 @@ class RouteSourceValidator {
143
147
  prompt = literal(stage);
144
148
  else if (stage.name === "app")
145
149
  apps.push(literal(stage));
146
- else if (stage.name === "config")
150
+ else if (stage.name === "guard")
151
+ guarded = true;
152
+ else if (stage.name === "search") {
153
+ const first = stage.args[0];
154
+ if (first && ts.isStringLiteralLike(first))
155
+ search.push(first.text);
156
+ } else if (stage.name === "config")
147
157
  devOnly = RouteSourceValidator.#devOnlyOf(RouteSourceValidator.#unwrapExpression(stage.args[0]), filePath);
148
158
  }
149
- return { kind, params, prompt, apps, devOnly };
159
+ return { kind, params, prompt, apps, search, guarded, devOnly };
150
160
  }
151
161
  static #assertChainParams(chain, pattern, filePath) {
152
162
  const inPath = pattern.split("/").filter((part) => part.startsWith(":")).map((part) => part.slice(1)).filter((name) => name !== "lang");
@@ -2,15 +2,15 @@
2
2
  import {
3
3
  Sys,
4
4
  command
5
- } from "./index-3wypz6xj.js";
5
+ } from "./index-eja64h28.js";
6
6
  import"./index-52w0fvh8.js";
7
- import"./index-wcej7g4z.js";
7
+ import"./index-8scw1pjk.js";
8
8
  import {
9
9
  renderPrimitiveReport
10
- } from "./index-xjf5j657.js";
10
+ } from "./index-4mj92tsh.js";
11
11
  import {
12
12
  ScalarScript
13
- } from "./index-skk9zc1x.js";
13
+ } from "./index-rnphv731.js";
14
14
 
15
15
  // pkgs/@akanjs/cli/scalar/scalar.command.ts
16
16
  import { Logger, lowerlize } from "akanjs/common";
@@ -0,0 +1,36 @@
1
+ ---
2
+ name: akan-agent
3
+ description: "Build the in-page agent: mounting Agent.Chat, setAgentAccess and the request policy, the LLM, publishing st.tool actions and cards, forms, readable state, zones, route guidance and slash commands."
4
+ ---
5
+
6
+ # Akan in-page agent
7
+
8
+ **The surface is what components declare, exactly.** `st.tool` publishes one action and `st.use` / `st.sel` /
9
+ `st.ref` make one store key readable while the reading component is mounted. A method on a store class gives an
10
+ agent nothing, and only the current page's declarations are live.
11
+
12
+ ## Mount it
13
+
14
+ 1. Mount `<Agent.Chat />` once, in a layout. It never executes tools: every tool runs in the caller's browser,
15
+ gated by guards and the approval card.
16
+ 2. It refuses every call until `option.setAgentAccess(<guard>)` in `lib/option.ts` names who may use it
17
+ (`SignedIn` for a product with accounts). What a turn may ask is `option.setAgentRequestPolicy`.
18
+ 3. The LLM is `option.setLlm({ apiKey, model, host })`, never env.
19
+
20
+ ## Publish actions
21
+
22
+ - Declare the tool beside the control that already does it, and hand the result to the control:
23
+ `st.tool("x").desc("…").arg("id", ID).exec((id) => st.do.removeX(id))`. One handler serves the person and the
24
+ agent; `.desc()` is required and first.
25
+ - `.card(({ submit, cancel }) => <Form … />)` parks the call in the chat for an answer that is the user's to give.
26
+ - Store-driven forms publish themselves: `onChange={st.do.setFieldOnX}` by reference emits the `data-akan-action`
27
+ the agent drives. A pass-through arrow publishes nothing and fails lint.
28
+ - Every `st.tool(…).exec()` / `.card()` is a hook: never behind a condition.
29
+
30
+ ## Reads and guidance
31
+
32
+ - `st.use.x({ agent: false })` hides a key; `hidden`, `secret` and `visual` fields are stripped from every read.
33
+ - A tool value is capped at 20,000 characters.
34
+ - Route guidance is `<Agent.Guide instructions="…" />`; model-facing text is English.
35
+
36
+ Full detail: `get_guideline` with `agentRule`.
@@ -85,6 +85,7 @@ Stored under `.akan/code/sessions` — project history, so a second checkout of
85
85
  ## Model, effort, keys
86
86
 
87
87
  - `/model <provider>/<id>`, e.g. `/model deepseek/deepseek-v4-pro`. `/effort <level>` for how hard it thinks.
88
+ A `task` sub-agent starts on the model the session is on at that moment.
88
89
  - A provider is authorized by **`<PROVIDER>_API_KEY`** — `DEEPSEEK_API_KEY`, `ANTHROPIC_API_KEY`. The
89
90
  workspace's own `.env` is read as well as the environment, and a key found there is used for the run and
90
91
  never copied anywhere.
@@ -1,10 +1,42 @@
1
1
  ---
2
2
  name: akan-debug
3
- description: "Debug a running Akan app: where the dev-server log is, how to read it, and how to tell a runtime failure from a build one."
3
+ description: "Check and debug a running Akan app: akan preview for what a page shows and throws, where the dev-server log is, how to read it, and how to tell a runtime failure from a build one."
4
4
  ---
5
5
 
6
6
  # Akan debug
7
7
 
8
+ ## See the change run: `akan preview`
9
+
10
+ `akan preview <app> [paths]` opens pages of the app's dev server in a headless browser and prints, per page,
11
+ the HTTP status, the title, a slice of the visible text, the uncaught errors and rejections the page reported,
12
+ the server errors logged meanwhile, console errors and warnings, and layout smells. It exits 1 when a page failed.
13
+
14
+ - It uses the dev server that answers for this app and checkout. With none, it starts one for the run and
15
+ stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
16
+ running one.
17
+ - Paths are comma-separated and get the default locale when they lack one: `akan preview <app> /board,/board/new`.
18
+ `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
19
+ path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
20
+ - The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native
21
+ shells load. `--screenshot` saves a PNG per page under `local/apps/<app>/runtime/preview/`, for a model
22
+ that reads images. `--format json` gives the same report as data.
23
+
24
+ ### Which platforms that covers
25
+
26
+ - Every change: the server-rendered web page and, with `--csr`, the bundle the iOS, Android and desktop
27
+ shells run.
28
+ - A change to `native/`, `plugin/`, an `isNativeApp()` branch, `native` in `akan.config.ts` or an
29
+ `@akanjs/native` plugin also needs that shell: `akan start-ios`, `start-android` or `start-desktop` on top of
30
+ the running dev server. Errors thrown in the shell reach the same dev-server log as `ClientReport` lines
31
+ tagged with the platform and target. Capture the shell with `xcrun simctl io booted screenshot <file>.png` or
32
+ `adb exec-out screencap -p > <file>.png`. When you cannot run the shell, say so: "not checked on iOS".
33
+ - Real devices, memory, OTA updates and store builds are for whoever releases.
34
+
35
+ ### What goes in your answer
36
+
37
+ The verdict lines of the pages you changed (`ok /en/board 200 "Board" 1.4s`) and every finding you left
38
+ unfixed. "Not opened in a browser" is not an answer once `akan preview` can run.
39
+
8
40
  ## The log is a file, and that file is the whole session
9
41
 
10
42
  A supervised `akan start` writes **`local/apps/<app>/runtime/dev.log`** — no ANSI, nothing truncated, every
@@ -17,12 +49,14 @@ what survives in the scrollback is bordered and truncated to the pane.
17
49
  - `tail -n 200 local/apps/<app>/runtime/dev.log` after an edit, to see what the reload produced.
18
50
  - `akan logs <app>` tails a running server with `--level --grep --endpoint --trace --child --role --origin
19
51
  --since` and `--json`.
20
- - The dev server's URL is printed in that log, and the port is allocated rather than fixed — the log is the
21
- only source for it.
52
+ - The dev server's URL is printed in that log. A server `akan preview` started logs to
53
+ `local/apps/<app>/runtime/preview/server.log` instead.
54
+ - An uncaught error or unhandled rejection in a page reaches the server log as a `ClientReport` error line,
55
+ naming the page, the client (`ssr` or `csr`) and the native target.
22
56
 
23
57
  ## Which loop you are in
24
58
 
25
- - **A type or lint failure** is the `akan-validate` loop. `akan_verify`.
59
+ - **A type or lint failure** is the `akan-validate` loop: `akan verify`.
26
60
  - **A runtime or SSR failure** is the dev log. The page renders blank, an overlay appears, or a request
27
61
  500s — none of that shows up in a typecheck.
28
62
 
@@ -38,5 +72,5 @@ reads like its own level is not one.
38
72
 
39
73
  ## Before you conclude
40
74
 
41
- A change that renders is not a change that passed. Run `akan_verify`, and for a `.tsx` change check
42
- `akan quality ssr` too — a UI edit that moves markup into a client bundle typechecks perfectly.
75
+ A change that renders is not a change that passed. Run `akan verify`; for a `.tsx` change it also runs the
76
+ SSR check, since a UI edit that moves markup into a client bundle typechecks perfectly.
@@ -46,5 +46,4 @@ the package client path — `import { cnst, fetch, st, usePage } from "@apps/<ap
46
46
 
47
47
  ## Validate
48
48
 
49
- `akan_verify`, or `akan sync <app>` then `akan lint <app>` then `akan typecheck <app>`. Raw `tsc` misses the
50
- generated barrels and reports false errors.
49
+ `akan verify`. Raw `tsc` misses the generated barrels and reports false errors.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: akan-mcp
3
+ description: "Expose an app to MCP clients: what /mcp publishes from guards, mcp: false curation, option.setMcp settings, OAuth, refusals, page prompts and MCP Apps, and the exposure test."
4
+ ---
5
+
6
+ # Akan MCP
7
+
8
+ Every app serves its signals as an MCP server on `POST /mcp`, mounted by default. **Exposure follows the guards**:
9
+ an endpoint with a real guard is published, one with none is refused, and so is a mutation guarded only by
10
+ `Public`. There is no per-endpoint opt-in.
11
+
12
+ ## Curation is not authorization
13
+
14
+ - `mcp: false` on an endpoint, or a `slice()` `mcp` map mirroring `guards`, keeps a perfectly guarded step (a UI
15
+ state-machine step a model would only call by mistake) off the shelf. It is an opt-out; everything else still
16
+ publishes.
17
+ - `guards: [Every, Person]` reserves an act for a person; `.with(AgentCall)` narrows what an agent's call may do.
18
+ - A guard's `static scope` decides whether a listing can hide the entry: `"account"` guards are evaluated per
19
+ caller, `"resource"` guards stay visible and stop the call.
20
+
21
+ ## Settings
22
+
23
+ - `option.setMcp({ … })` in the app's `lib/option.ts`, never `main.ts`; `AKAN_MCP=false` takes the surface off.
24
+ - `JWT_SECRET` is required outside `local`.
25
+ - Every published entry needs a `.desc()`; model-facing text is English.
26
+ - Never make a refusal message more helpful.
27
+
28
+ ## Pages for the host
29
+
30
+ - `page().prompt(name, description)` briefs a screen as an MCP prompt.
31
+ - `page().app(name, description, load)` publishes one component a host draws in the chat, as a read-only tool
32
+ whose `load` may only query.
33
+
34
+ ## Verify
35
+
36
+ - One exposure test per app in `srvkit/mcpExposure.signal.test.ts`: list the tools with a user token, pin the names
37
+ with `toEqual`, and assert the curated and admin-only ones are absent. A guard change fails it first.
38
+ - Then `akan verify <app>` and the boot log.
39
+
40
+ Full detail: `get_guideline` with `mcpRule`, or `transportRule` for guards and rate limits.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: akan-page
3
+ description: "Add or change a route under page/: the one page()/layout() chain, typed params and search, guards, heads, loading and errors, overrides, and lib pages."
4
+ ---
5
+
6
+ # Akan pages
7
+
8
+ A route file exports one chain and nothing else. Every setting is a stage of it.
9
+
10
+ ```tsx
11
+ export default page()
12
+ .param("orgId", ID)
13
+ .guard(() => signedIn())
14
+ .render(({ orgId }) => {
15
+ const { l } = usePage();
16
+ const { taskInitInOrg } = fetch.initTaskInOrg(orgId);
17
+ return <Task.Zone.Card init={taskInitInOrg} prefix={`/org/${orgId}`} />;
18
+ });
19
+ ```
20
+
21
+ ## Steps
22
+
23
+ 1. Place the file: `<route>.tsx` or `<dir>/_index.tsx` serves the path, `_layout.tsx` nests a layout (`layout()`;
24
+ the root one is `rootLayout()`), `[id]` is a dynamic segment, `(group)` groups without a segment. `page/` holds
25
+ route modules only — no helpers, no `.ts` files.
26
+ 2. Name every `[x]` segment with `.param("x", Type)` and read a query key only with `.search("k", Type)`. Values
27
+ arrive typed; `lang` reaches every stage and is never declared.
28
+ 3. Gate with `.guard(() => signedIn())` on the `_layout.tsx` (a real redirect before anything renders), and repeat
29
+ a stricter guard on a page that needs more. The endpoint guards are still the real gate.
30
+ 4. In `.render()`: `usePage()`, then fetch, then return. Hand `fetch.init*` / `view*` / `edit*` fields to sections
31
+ unawaited; await only what the shell reads, in one `Promise.all`.
32
+ 5. `.head()` takes JSX (or a function returning it), never a metadata object. A canonical link comes only from the
33
+ page's own head.
34
+ 6. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
35
+ `export default override({ Slot: AppComponent })`, no logic.
36
+
37
+ ## Never
38
+
39
+ - A `fetch.<mutation>()` while rendering — it throws `base.error.mutationInRender`, because opening a link would
40
+ perform it. Send writes from a user action.
41
+ - `useState`, `useEffect`, comments, a named export beside the chain, or the legacy `export default async function`.
42
+ - Editing a lib page through its link in `page/(libs)/` — edit the lib's own `page/` source.
43
+
44
+ Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server.
@@ -0,0 +1,38 @@
1
+ ---
2
+ name: akan-query
3
+ description: "Write filters, slices and list loading: query descriptors, init paging and loadMoreOf, soft removal and hookless writes, q.search text search, and the cascade direction."
4
+ ---
5
+
6
+ # Akan queries and slices
7
+
8
+ ## Filters and slices
9
+
10
+ - A filter in `<model>.document.ts` declares its args; a slice in `<model>.signal.ts` serves it to stores. A slice
11
+ `exec` returns a `query<Filter>(…)` descriptor — never a `list<Filter>` array — and you cannot chain sort or
12
+ limit on it.
13
+ - Page through the store: `initX(…, { sort, page, limit })`, then `st.do.loadMoreOf<Model>()` while
14
+ `hasMoreOf<Model>`. Never compare `count > page * limit`.
15
+ - Never ask for more than 500 rows: the server serves at most 500 per request and drops the rest silently.
16
+ A figure over the whole set belongs in an insight or an endpoint.
17
+ - The root slice takes a filter name and its args, never a raw query, and its `root:` guard is always `Admin`.
18
+ - No value is `q.empty`, never `q.missing`.
19
+ - A projection is bare on the facade (`pickById(id, { secret: true })`) and under `select` on a filter accessor —
20
+ the only way to read a `field.secret` value.
21
+
22
+ ## Writes and removal
23
+
24
+ - Removal is soft: reads see live rows unless `{ withRemoved: true }`. The one hard delete is `purge<Filter>` /
25
+ `purgeMany`, for data past retention.
26
+ - A filter's `remove*` / `update*`, `updateById` and `removeById` run no hooks and no cascade. A model with a
27
+ cascade or `_postRemove` removes through `remove<Model>(id)`.
28
+ - Load a set once (`load<Model>Many`, one filter query) instead of one call per item in a loop — lint fails a
29
+ per-item service call an endpoint reaches.
30
+
31
+ ## Search and cascade
32
+
33
+ - `q.search(text, { prefix: true })` sits in a filter at an AND position, over fields with the `text` role. Blank
34
+ input matches nothing — never a passthrough. A search slice only over data safe to enumerate.
35
+ - `cascade` names a direction, and the wrong one loses data: `removeRef` on the owner's relation, `removeWith` on
36
+ the child's reference to its owner.
37
+
38
+ Full detail: `get_guideline` with `queryRule`, and `workspaceRecipes` for a worked slice.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: akan-runtime
3
+ description: "Configure how an app runs: web surfaces, route prefixes, gateway vs solo, akan start and logs, the Docker image, native and desktop apps, database modes, ops, assets and the build pipeline."
4
+ ---
5
+
6
+ # Akan runtime
7
+
8
+ Runtime and build settings are declared in `akan.config.ts` and narrowed — never widened — by an env at boot.
9
+ Domain code reaches none of them.
10
+
11
+ ## Where each setting lives
12
+
13
+ | Want | Setting |
14
+ | --- | --- |
15
+ | API only, or no CSR bundle for native apps | `web: false`, `web: { csr: false }` |
16
+ | Move the API or websocket mount | `new AkanApp({ prefix, websocketPrefix })` in `main.ts`, mirrored in `api: { … }`; read with `getApiPrefix()` / `getWsPrefix()` |
17
+ | The production image | `docker: string \| { image, preRuns, postRuns, command }` |
18
+ | iOS, Android, desktop | the `native` section; `desktop: { server: true }` carries the server |
19
+ | SQLite, several databases, a cluster | `database: { modes: [...] }`, picked by `AKAN_DATABASE_MODE` |
20
+
21
+ - `main.ts` imports `AkanApp` from `akanjs/server/akanApp`, never the barrel.
22
+ - Never write `/api` or `/ws` literally, and never pass a prefix as a prop.
23
+ - The generated image installs only `ca-certificates` and `tzdata`; add the rest in `preRuns`.
24
+ - An app running in two database modes avoids `q.raw`.
25
+
26
+ ## Running and logs
27
+
28
+ - `akan start <app>` (`a,b` or `all` for several) runs the dev server; `akan build <app>` checks the production
29
+ build. A supervised session writes `local/apps/<app>/runtime/dev.log` — hand over that path, not a paste of the
30
+ live view. Tail with `akan logs <app>`.
31
+ - Give every log sink a floor (`Logger.addSink(sink, { minLevel })`) and never log once per delivered record.
32
+
33
+ ## Native and desktop
34
+
35
+ - `akan start-desktop <app>`, `akan start-ios <app>`, `akan start-android <app>` load pages from a running
36
+ `akan start`; a desktop app carrying its server starts it itself.
37
+ - A desktop app's carried server listens on a loopback port any local program can call — guard it like a network
38
+ server. Read runtime files from `AKAN_APP_DIR`, and keep a user's secret with `NativeSecret`, never in a file.
39
+
40
+ Full detail: `get_guideline` with `runtimeRule`.
@@ -43,8 +43,8 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
43
43
  and each workflow's inputs.)
44
44
  2. `apply_workflow({ planPath })` — writes the scaffold and syncs the generated barrels. Returns
45
45
  `validationTarget`.
46
- 3. `run_validation({ runIdOrPlan: <validationTarget> })`, or just call `akan_verify`, which runs the whole
47
- chain over everything the working tree changed.
46
+ 3. `run_validation({ runIdOrPlan: <validationTarget> })`, or run `akan verify` (`akan_verify` in akan code);
47
+ both are the whole chain in one process.
48
48
  4. **Read each scaffolded file before editing it.** They are a few lines each and they extend base classes
49
49
  that already generated the CRUD surface. Read the `akan-store` skill before touching a store or adding
50
50
  signal endpoints, or you will redeclare `create<Model>` and hit an "already exists" typecheck error.
@@ -60,9 +60,19 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
60
60
  - Hand-writing files is the fallback, used only when no workflow matches, or when apply reports
61
61
  unsupported / no-op / failed diagnostics telling you to act manually. Say which case applied.
62
62
  - Never hand-edit a generated file to "finish" a scaffold — use `repair_generated` or `akan sync <app>`.
63
- - No workflow tools this turn? The same order through bash:
64
- `akan workflow list` → `akan workflow plan create-module --app <app> --module comment --format json --out <path>`
65
- → `akan workflow apply <path> --format json`.
63
+
64
+ ## No workflow tools? The CLI is the same chain
65
+
66
+ The tools come from `akan mcp` (`--mode plan` reads, `--mode apply` writes). When they are not connected, each
67
+ has a command that prints the same report:
68
+
69
+ | tool | command |
70
+ | --- | --- |
71
+ | `list_workflows` / `explain_workflow` | `akan workflow list` / `akan workflow explain <name>` |
72
+ | `plan_workflow` | `akan workflow plan create-module --app <app> --module comment --format json --out <path>` |
73
+ | `apply_workflow` | `akan workflow apply <path> --format json` (`--dry-run` previews) |
74
+ | `run_validation` | `akan verify <app>` |
75
+ | `repair_generated` / `repair_imports` / `repair_module_shape` | `akan repair generated\|imports\|module-shape --app <app>` |
66
76
 
67
77
  ## Worked example — "an intro page, two detail pages, and a comment zone with a database"
68
78
 
@@ -73,4 +83,4 @@ Each result names the next call in `next.tool`. Follow it; do not improvise.
73
83
  leave the store body empty unless you need extra state.
74
84
  4. Write the pages and the comment UI against the generated actions — `st.do.createComment`,
75
85
  `st.do.initCommentInPublic`, `st.use.commentListInPublic`.
76
- 5. `akan_verify` until clean.
86
+ 5. `akan verify` until it prints `verify ok`.
@@ -0,0 +1,40 @@
1
+ ---
2
+ name: akan-transport
3
+ description: "Guard and tune endpoints on the wire: writing a Can<Verb><Model> guard, deadlines, cache, idempotency, rate limits, server-to-server calls, body types, bytes and HTTP verbs."
4
+ ---
5
+
6
+ # Akan transport
7
+
8
+ ## Guards
9
+
10
+ - Every custom `query` / `mutation` / `pubsub` / `message` names its own `guards: [...]`; every `slice()` takes an
11
+ explicit guard map with `root: Admin`. `Public` belongs on a slice `get:`, and on a mutation only for an act that
12
+ must work signed out (sign-up, sign-in, token refresh, an OAuth route), which also declares a `rateLimit`.
13
+ - A resource guard is a `Can<Verb><Model>` class in the model library's `srvkit/guards.ts` that fails closed:
14
+ no resource named, or a load that throws, is `false` (after a `logger.warn`). Admin bypass goes first.
15
+ - Every guard declares `static scope`: `"account"` reads only the caller (`SignedIn`, `Admin`, roles), and
16
+ `"resource"` needs the call's arguments (every `Can<Verb><Model>`). Keep `static name = "User";` with a comment.
17
+ - Guards read `context.get<T>("account")`, serve HTTP and websocket alike, and stay side-effect free. The acting
18
+ user comes from `.with(Self)` / `.with(CurrentUserId)` / `.with(Me)`, the address from `.with(Ip)` — never a
19
+ client-supplied id. The service re-checks ownership: two independent gates.
20
+
21
+ ## Endpoint options
22
+
23
+ - `{ timeout: <ms> }` is the deadline on both ends; undeclared, the client quits at 30 s and the handler is not
24
+ cancelled.
25
+ - `{ cache }` only on a `query` with no internal argument, capped at one day; `invalidate(endpoint, args?)` drops
26
+ it early through a plugged `EndpointCacheControl`.
27
+ - `{ rateLimit: { calls, windowMs?, by? } }` per endpoint, `option.setRateLimit` per app, `plug(RateLimit)` for a
28
+ business key.
29
+ - A mutation repeated under one `Idempotency-Key` header runs once and replays its first answer.
30
+ - `{ method: "PATCH" | "PUT" | "DELETE" }` moves a mutation off `POST` — only when a foreign protocol forces it.
31
+ - `errors: { 409: ["ticket.error.locked"] }` names the errors an endpoint throws on purpose.
32
+
33
+ ## Bodies and other servers
34
+
35
+ - `.body()` / `.param()` take scalars, model refs or `enumOf(...)`; `Int` / `Float`, never `Number`; bytes are
36
+ `Binary`, never `Any`; `Upload` only in a `fileUpload: true` mutation.
37
+ - Server to server, `fetch.clone({ origin })` opens no socket without `connect: true`, retries through `retry`,
38
+ and rethrows a remote `Err` as it is — never wrap or re-key it.
39
+
40
+ Full detail: `get_guideline` with `transportRule`, or `mcpRule` for what a guard's scope does to an MCP listing.
@@ -7,17 +7,19 @@ description: "Run the akan check loop after editing and fix each failure class t
7
7
 
8
8
  ## One call does the whole chain
9
9
 
10
- `akan_verify` runs sync → lint → typecheck → `quality ssr` over everything the working tree has changed, in
11
- the right order, and reports only what failed. **Call it after editing, before you say you are done.** It
12
- also runs itself at the end of a turn that changed source, so a failure comes back to you either way.
13
-
14
- The same chain by hand, for the app you are editing:
15
-
16
- - `akan sync <app>` — after adding, renaming, or deleting any file. Regenerates the barrels.
17
- - `akan lint <app>` — fast; run after every edit. Prints up to 200 diagnostics.
18
- - `akan typecheck <app>` — the client/server boundary violations land here, not in lint.
19
- - `akan quality ssr` — only when you wrote or changed a `.tsx`. Did the server share hold?
20
- - `akan build <app>` — the full production build; slower, and only when the build itself is in question.
10
+ `akan verify` (the `akan_verify` tool in akan code) syncs, lints with fixes, typechecks, fast-builds each
11
+ changed app, and runs the SSR check for a `.tsx` change — over everything the working tree has changed, in one
12
+ process. It prints one line when it passes and one line per problem when it fails. **Run it after editing,
13
+ before you say you are done.** In akan code it also runs itself at the end of a turn that changed source.
14
+
15
+ Never run `akan lint`, `akan typecheck` and `akan build` in turn: that is the same work three times over, at
16
+ three times the output. Narrow the one command instead:
17
+
18
+ - `akan verify <app-or-lib-or-pkg>` — that target whole, changed or not.
19
+ - `akan verify --lint-only` — the quick pass between edits.
20
+ - `akan verify --no-build` — leave the app build out.
21
+ - `akan verify --max 0` — every line, when the report ends in `+N more`.
22
+ - `fixed N files` in the header means lint rewrote them on disk: re-read before editing them again.
21
23
 
22
24
  Raw `tsc` misses the generated barrels and reports false errors. Do not reach for it.
23
25
 
@@ -5,7 +5,7 @@ import {
5
5
  runner,
6
6
  script,
7
7
  command
8
- } from "./index-3wypz6xj.js";
8
+ } from "./index-eja64h28.js";
9
9
  import {
10
10
  FileSys2
11
11
  } from "./index-52w0fvh8.js";
@@ -14,20 +14,20 @@ import {
14
14
  Executor,
15
15
  WorkspaceExecutor,
16
16
  AppExecutor
17
- } from "./index-wcej7g4z.js";
17
+ } from "./index-8scw1pjk.js";
18
18
  import {
19
19
  GlobalConfig
20
- } from "./index-2azahjaw.js";
20
+ } from "./index-qkkdhjm6.js";
21
21
  import"./index-m9jj544v.js";
22
- import"./index-bt438yxm.js";
23
- import"./index-xb8809yb.js";
24
- import"./index-0fz95kxe.js";
22
+ import"./index-3yz30c07.js";
23
+ import"./index-1shvxzt0.js";
24
+ import"./index-xqgwjz7a.js";
25
25
  import {
26
26
  SubspaceConfig
27
27
  } from "./index-4pf8g7ff.js";
28
28
  import {
29
29
  SlicePlanner
30
- } from "./index-pcwzkdqb.js";
30
+ } from "./index-1p0qbq3m.js";
31
31
 
32
32
  // pkgs/@akanjs/devkit/subspace.ts
33
33
  import { mkdir as mkdir2 } from "fs/promises";
@@ -816,7 +816,7 @@ class SubspaceRunner extends runner("subspace") {
816
816
  if (!asked)
817
817
  return { name: subspace.name, workspaceId, host, apps, libs: [], outcome: "cancelled", files: [] };
818
818
  const { libs } = await subspace.slice();
819
- const { CloudScript } = await import("./cloud.script-nqevg5qw.js");
819
+ const { CloudScript } = await import("./cloud.script-0s1jybd5.js");
820
820
  const { files } = await CommandContainer.get(CloudScript).uploadEnv(workspace, {
821
821
  host,
822
822
  workspaceId,