@akanjs/cli 3.1.1-rc.8 → 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-rqxarxsn.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-14xsthcr.js → application.command-g7xv6ad0.js} +46 -13
  8. package/{applicationBuildRunner-t2r84sz6.js → applicationBuildRunner-qvjnhr9j.js} +9 -6
  9. package/buildBatch.proc.js +6 -6
  10. package/{cloud.command-rmw1kcf1.js → cloud.command-6ebygmhw.js} +17 -15
  11. package/cloud.script-0s1jybd5.js +26 -0
  12. package/{code.command-719k3e9q.js → code.command-mpkm2emr.js} +6 -6
  13. package/commandManifest.json +1 -1
  14. package/{context.command-c4t4z1vy.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-8w76g4rm.js → index-266dewjs.js} +11 -11
  43. package/{index-5max10jx.js → index-3yz30c07.js} +72 -53
  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-5phjb48k.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-hmmv2cah.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-0p37cz91.js → index-payhwt51.js} +21 -29
  62. package/{index-myc22sgv.js → index-qkkdhjm6.js} +5 -4
  63. package/{index-74tjjsnc.js → index-qxzrp5xt.js} +33 -37
  64. package/{index-zrte51fn.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-pa3c2mb8.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-8ap5z1n5.js → index-vxmy1p4f.js} +16 -36
  72. package/{index-mdqr41sp.js → index-w4k2ragk.js} +7 -7
  73. package/{index-qd5km521.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-2t3fghje.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-kvxmyxtf.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-kxv0ddmp.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-3sy7kjgj.js +0 -9
  171. package/TunnelShare-2ef94kha.js +0 -14
  172. package/agent.command-ydftceda.js +0 -25
  173. package/cloud.script-v1ysyerg.js +0 -24
  174. package/context.runner-qb15sjf8.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-tsc99yec.js +0 -521
@@ -2,10 +2,124 @@
2
2
  import {
3
3
  AppExecutor,
4
4
  LibExecutor
5
- } from "./index-wcej7g4z.js";
5
+ } from "./index-8scw1pjk.js";
6
+ import {
7
+ camelToKebabCase
8
+ } from "./index-eja64h28.js";
6
9
 
7
10
  // pkgs/@akanjs/devkit/workflow/artifacts.ts
8
- import { capitalize } from "akanjs/common";
11
+ import { capitalize as capitalize2 } from "akanjs/common";
12
+
13
+ // pkgs/@akanjs/devkit/workflow/interactionScaffold.ts
14
+ import { capitalize, lowerlize } from "akanjs/common";
15
+
16
+ class InteractionScaffold {
17
+ name;
18
+ className;
19
+ hookName;
20
+ #commonSpecifier;
21
+ constructor(sys, name) {
22
+ this.name = name;
23
+ this.className = capitalize(name);
24
+ this.hookName = `use${this.className}`;
25
+ this.#commonSpecifier = `@${sys.type}s/${sys.name}/common`;
26
+ }
27
+ static nameOf(raw) {
28
+ const name = lowerlize(raw.replace(/^use(?=[A-Z])/, ""));
29
+ return /^[a-z][A-Za-z0-9]*$/.test(name) ? name : null;
30
+ }
31
+ static async build(sys, raw) {
32
+ const diagnostics = [];
33
+ const name = raw ? InteractionScaffold.nameOf(raw) : null;
34
+ if (!name) {
35
+ diagnostics.push({
36
+ severity: "error",
37
+ code: "create-interaction-name-invalid",
38
+ input: "interaction",
39
+ message: `Interaction name "${raw ?? ""}" must be camelCase (boardKeys), optionally prefixed with use.`
40
+ });
41
+ return { diagnostics, files: [] };
42
+ }
43
+ const scaffold = new InteractionScaffold(sys, name);
44
+ const files = scaffold.files;
45
+ const taken = (await Promise.all(scaffold.claimedPaths.map(async (path) => await sys.exists(path) ? `${sys.type}s/${sys.name}/${path}` : null))).filter((path) => !!path);
46
+ if (taken.length)
47
+ diagnostics.push({
48
+ severity: "error",
49
+ code: "create-interaction-exists",
50
+ input: "interaction",
51
+ message: `${taken.join(", ")} already exists; pick another interaction name or extend the existing files.`
52
+ });
53
+ return { diagnostics, files: taken.length ? [] : files };
54
+ }
55
+ get claimedPaths() {
56
+ const { name, hookName } = this;
57
+ return [
58
+ `common/${name}.ts`,
59
+ `common/${name}.tsx`,
60
+ `common/${name}.test.ts`,
61
+ `webkit/${hookName}.tsx`,
62
+ `webkit/${hookName}.ts`
63
+ ];
64
+ }
65
+ get files() {
66
+ return [
67
+ {
68
+ path: `common/${this.name}.ts`,
69
+ content: this.logicSource,
70
+ action: "create",
71
+ reason: "Pure interaction logic."
72
+ },
73
+ {
74
+ path: `common/${this.name}.test.ts`,
75
+ content: this.testSource,
76
+ action: "create",
77
+ reason: "Test of the pure interaction logic."
78
+ },
79
+ { path: `webkit/${this.hookName}.tsx`, content: this.hookSource, action: "create", reason: "Client hook." }
80
+ ];
81
+ }
82
+ get logicSource() {
83
+ return [
84
+ `export class ${this.className} {`,
85
+ " static next<State extends object>(state: State, input: Partial<State>) {",
86
+ " return { ...state, ...input };",
87
+ " }",
88
+ "}",
89
+ ""
90
+ ].join(`
91
+ `);
92
+ }
93
+ get testSource() {
94
+ return [
95
+ 'import { describe, expect, it } from "bun:test";',
96
+ `import { ${this.className} } from "./${this.name}";`,
97
+ "",
98
+ `describe(${JSON.stringify(this.className)}, () => {`,
99
+ ' it("applies an input over the state it is handed", () => {',
100
+ ` expect(${this.className}.next({ idx: 0, isOpen: false }, { idx: 1 })).toEqual({ idx: 1, isOpen: false });`,
101
+ " });",
102
+ "});",
103
+ ""
104
+ ].join(`
105
+ `);
106
+ }
107
+ get hookSource() {
108
+ return [
109
+ '"use client";',
110
+ `import { ${this.className} } from "${this.#commonSpecifier}";`,
111
+ "",
112
+ `export const ${this.hookName} = <State extends object>(state: State, commit: (next: State) => void) => {`,
113
+ " const change = async (input: Partial<State>) => {",
114
+ ` commit(${this.className}.next(state, input));`,
115
+ " };",
116
+ " return { change };",
117
+ "};",
118
+ ""
119
+ ].join(`
120
+ `);
121
+ }
122
+ }
9
123
 
10
124
  // pkgs/@akanjs/devkit/workflow/utils.ts
11
125
  var jsonText = (value, { trailingNewline = true } = {}) => `${JSON.stringify(value, null, 2)}${trailingNewline ? `
@@ -114,8 +228,10 @@ var planInputString = (plan, key) => {
114
228
  var workflowPathsForPlan = (plan) => {
115
229
  const app = planInputString(plan, "app");
116
230
  const module = planInputString(plan, "module");
117
- const moduleClass = module ? capitalize(module) : "<Module>";
118
- return plan.predictedChanges.map((change) => change.target.replace(/^\*\//, app ? `apps/${app}/` : "").replaceAll("<module>", module || "<module>").replaceAll("<Module>", moduleClass));
231
+ const moduleClass = module ? capitalize2(module) : "<Module>";
232
+ const rawInteraction = planInputString(plan, "interaction");
233
+ const interaction = rawInteraction ? InteractionScaffold.nameOf(rawInteraction) ?? rawInteraction : null;
234
+ return plan.predictedChanges.map((change) => change.target.replace(/^\*\//, app ? `apps/${app}/` : "").replaceAll("<module>", module || "<module>").replaceAll("<Module>", moduleClass).replaceAll("<interaction>", interaction || "<interaction>").replaceAll("<Interaction>", interaction ? capitalize2(interaction) : "<Interaction>"));
119
235
  };
120
236
  var workflowRunsDir = ".akan/workflows/runs";
121
237
  var createWorkflowRunId = (prefix = "run") => `${prefix}-${new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14)}-${Math.random().toString(36).slice(2, 8)}`;
@@ -174,6 +290,14 @@ var statusForValidationKind = (commands, kind) => {
174
290
  return "unknown";
175
291
  return matching.some((command) => command.status === "failed") ? "failed" : "passed";
176
292
  };
293
+ var generatedSyncStatus = (commands) => {
294
+ const sync = statusForValidationKind(commands, "sync");
295
+ const verify = commands.filter((command) => command.kind === "verify");
296
+ if (sync !== "unknown" || verify.length === 0)
297
+ return sync;
298
+ const syncFailed = verify.some((command) => /^verify fail \u00B7 .*\bsync \d+ errors?\b/m.test(command.stdout ?? ""));
299
+ return syncFailed ? "failed" : "passed";
300
+ };
177
301
  var statusForCommands = (commands) => {
178
302
  if (commands.length === 0)
179
303
  return "unknown";
@@ -267,7 +391,7 @@ var createValidationStatuses = (commands, reportDiagnostics, baselineDiagnostics
267
391
  overallStatus,
268
392
  summary: {
269
393
  sourceChange: sourceStatus,
270
- generatedSync: statusForValidationKind(commands, "sync"),
394
+ generatedSync: generatedSyncStatus(commands),
271
395
  validationCommands: validationCommandsStatus,
272
396
  baseline: baselineStatus,
273
397
  workspaceConfig: statusForScope(commands, diagnostics, scopes, "workspace-config"),
@@ -386,7 +510,7 @@ var createRepairReport = ({
386
510
  ...syncedAt ? { syncedAt } : {}
387
511
  });
388
512
  // pkgs/@akanjs/devkit/workflow/executor.ts
389
- import { capitalize as capitalize2 } from "akanjs/common";
513
+ import { capitalize as capitalize3 } from "akanjs/common";
390
514
  import ts4 from "typescript";
391
515
 
392
516
  // pkgs/@akanjs/devkit/workflow/moduleIndex.ts
@@ -395,7 +519,7 @@ import path from "path";
395
519
  import ts3 from "typescript";
396
520
 
397
521
  // pkgs/@akanjs/devkit/workflow/source.ts
398
- import { lowerlize } from "akanjs/common";
522
+ import { lowerlize as lowerlize2 } from "akanjs/common";
399
523
  import ts2 from "typescript";
400
524
 
401
525
  // pkgs/@akanjs/devkit/workflow/sourceAst.ts
@@ -459,6 +583,7 @@ var moduleSourcePaths = (moduleName) => {
459
583
  abstract: `lib/${moduleName}/${moduleName}.abstract.md`,
460
584
  constant: `lib/${moduleName}/${moduleName}.constant.ts`,
461
585
  dictionary: `lib/${moduleName}/${moduleName}.dictionary.ts`,
586
+ document: `lib/${moduleName}/${moduleName}.document.ts`,
462
587
  service: `lib/${moduleName}/${moduleName}.service.ts`,
463
588
  signal: `lib/${moduleName}/${moduleName}.signal.ts`,
464
589
  store: `lib/${moduleName}/${moduleName}.store.ts`,
@@ -471,12 +596,10 @@ var moduleSourcePaths = (moduleName) => {
471
596
  };
472
597
  var generatedFilesForSync = (sys, reason = "Generated files may change after sync.") => generatedFilePathsForTarget(getSysRoot(sys), reason);
473
598
  var validationCommandsForTarget = (target) => [
474
- { command: `akan sync ${target}`, reason: "Refresh generated Akan files from source conventions." },
475
- { command: `akan lint ${target}`, reason: "Validate formatting, imports, and static lint rules." }
599
+ { command: `akan verify ${target}`, reason: "Sync, lint, typecheck and build the target in one run." }
476
600
  ];
477
601
  var nextActionsForTarget = (target) => [
478
- { command: `akan sync ${target}`, reason: "Refresh generated Akan files after source changes." },
479
- { command: `akan lint ${target}`, reason: "Validate the target after generated files are refreshed." }
602
+ { command: `akan verify ${target}`, reason: "Refresh generated files and validate the target in one run." }
480
603
  ];
481
604
  var createPrimitiveWriteReport = ({
482
605
  command,
@@ -542,7 +665,7 @@ var koLabelForField = (fieldName) => {
542
665
  if (koLabels[fieldName])
543
666
  return koLabels[fieldName];
544
667
  const words = splitFieldWords(fieldName);
545
- const translated = words.map((word) => koLabels[word] ?? koLabels[lowerlize(word)] ?? null);
668
+ const translated = words.map((word) => koLabels[word] ?? koLabels[lowerlize2(word)] ?? null);
546
669
  return translated.every(Boolean) ? translated.join(" ") : null;
547
670
  };
548
671
  var bilingualLabelForField = (fieldName) => {
@@ -569,17 +692,48 @@ var normalizeFieldType = (typeName) => {
569
692
  };
570
693
  return normalizedTypes[typeName.toLowerCase()] ?? typeName;
571
694
  };
695
+ var importOrder = (a, b) => {
696
+ const [lowerA, lowerB] = [a.toLowerCase(), b.toLowerCase()];
697
+ if (lowerA !== lowerB)
698
+ return lowerA < lowerB ? -1 : 1;
699
+ return a < b ? -1 : a > b ? 1 : 0;
700
+ };
572
701
  var ensureNamedImport = (content, moduleSpecifier, name) => {
573
702
  const source = sourceFileFor("source.ts", content);
574
- const namedImport = findNamedImport(source, moduleSpecifier);
575
- if (namedImport) {
576
- if (namedImport.names.includes(name))
577
- return content;
578
- const nextNames = [...namedImport.names, name].sort();
579
- return spliceText(content, namedImport.namedBindingsStart, namedImport.namedBindingsEnd, `{ ${nextNames.join(", ")} }`);
580
- }
581
- return `import { ${name} } from "${moduleSpecifier}";
582
- ${content}`;
703
+ const namedImport = findNamedImport(source, moduleSpecifier, { valueOnly: true });
704
+ if (!namedImport)
705
+ return ensureImportDeclaration(content, moduleSpecifier, `{ ${name} }`);
706
+ if (namedImport.names.includes(name))
707
+ return content;
708
+ const nextElements = [...namedImport.elements, { name, text: name }].sort((a, b) => importOrder(a.name, b.name));
709
+ return spliceText(content, namedImport.namedBindingsStart, namedImport.namedBindingsEnd, `{ ${nextElements.map((element) => element.text).join(", ")} }`);
710
+ };
711
+ var ensureImportDeclaration = (content, moduleSpecifier, clause) => {
712
+ const line = `import ${clause} from "${moduleSpecifier}";`;
713
+ if (content.includes(line))
714
+ return content;
715
+ const source = sourceFileFor("source.ts", content);
716
+ const imports = source.statements.filter((statement) => ts2.isImportDeclaration(statement)).flatMap((statement) => ts2.isStringLiteral(statement.moduleSpecifier) ? [{ specifier: statement.moduleSpecifier.text, start: statement.getStart(source), end: statement.getEnd() }] : []);
717
+ const isRelative = (specifier) => specifier.startsWith(".");
718
+ const peers = imports.filter((entry) => isRelative(entry.specifier) === isRelative(moduleSpecifier));
719
+ const before = peers.find((entry) => importOrder(entry.specifier, moduleSpecifier) > 0);
720
+ if (before) {
721
+ const insertAt = lineStartAt(content, before.start);
722
+ return spliceText(content, insertAt, insertAt, `${line}
723
+ `);
724
+ }
725
+ const after = peers.at(-1) ?? (isRelative(moduleSpecifier) ? imports.at(-1) : undefined);
726
+ if (after) {
727
+ const insertAt = lineEndAt(content, after.end);
728
+ return spliceText(content, insertAt, insertAt, peers.length ? `${line}
729
+ ` : `
730
+ ${line}
731
+ `);
732
+ }
733
+ const insertAt = imports[0] ? lineStartAt(content, imports[0].start) : 0;
734
+ return spliceText(content, insertAt, insertAt, `${line}
735
+
736
+ `);
583
737
  };
584
738
  var ensureBaseImport = (content, name) => ensureNamedImport(content, "akanjs/base", name);
585
739
  var ensureBaseTypeImport = (content, typeName) => {
@@ -800,17 +954,18 @@ var dictionaryChainOrderValid = (chainMethods) => {
800
954
  }
801
955
  return true;
802
956
  };
803
- var findDictionaryModelObject = (source, moduleClassName) => {
957
+ var findDictionaryModelObject = (source, moduleClassName) => findDictionaryStageObject(source, "model", moduleClassName);
958
+ var findDictionaryStageObject = (source, stage, typeName) => {
804
959
  let locator = null;
805
960
  const visit = (node) => {
806
961
  if (locator)
807
962
  return;
808
- if (!ts2.isCallExpression(node) || callExpressionName(node) !== "model") {
963
+ if (!ts2.isCallExpression(node) || callExpressionName(node) !== stage) {
809
964
  ts2.forEachChild(node, visit);
810
965
  return;
811
966
  }
812
967
  const typeArgument = node.typeArguments?.[0];
813
- if (!typeArgument || typeArgument.getText(source) !== moduleClassName) {
968
+ if (!typeArgument || typeArgument.getText(source) !== typeName) {
814
969
  ts2.forEachChild(node, visit);
815
970
  return;
816
971
  }
@@ -852,17 +1007,20 @@ var findLightProjectionArray = (source, moduleClassName) => {
852
1007
  ts2.forEachChild(source, visit);
853
1008
  return locator;
854
1009
  };
855
- var findNamedImport = (source, moduleSpecifier) => {
1010
+ var findNamedImport = (source, moduleSpecifier, { valueOnly = false } = {}) => {
856
1011
  for (const statement of source.statements) {
857
1012
  if (!ts2.isImportDeclaration(statement) || !ts2.isStringLiteral(statement.moduleSpecifier))
858
1013
  continue;
859
1014
  if (statement.moduleSpecifier.text !== moduleSpecifier)
860
1015
  continue;
1016
+ if (valueOnly && statement.importClause?.isTypeOnly)
1017
+ continue;
861
1018
  const namedBindings = statement.importClause?.namedBindings;
862
1019
  if (!namedBindings || !ts2.isNamedImports(namedBindings))
863
1020
  continue;
864
1021
  return {
865
1022
  names: namedBindings.elements.map((element) => element.name.text),
1023
+ elements: namedBindings.elements.map((element) => ({ name: element.name.text, text: element.getText(source) })),
866
1024
  namedBindingsStart: namedBindings.getStart(source),
867
1025
  namedBindingsEnd: namedBindings.getEnd()
868
1026
  };
@@ -1090,6 +1248,17 @@ var hasDictionaryModelField = (content, moduleClassName, fieldName) => {
1090
1248
  return false;
1091
1249
  return findDictionaryModelObject(source, moduleClassName)?.fields.some((field) => field.name === fieldName) ?? false;
1092
1250
  };
1251
+ var hasDictionaryEndpointEntry = (content, moduleClassName, entryName) => {
1252
+ const source = sourceFileFor("dictionary.ts", content);
1253
+ return findDictionaryStageObject(source, "endpoint", `${moduleClassName}Endpoint`)?.fields.some((field) => field.name === entryName) ?? false;
1254
+ };
1255
+ var insertDictionaryEndpointEntry = (content, moduleClassName, entryName, entryText) => {
1256
+ const source = sourceFileFor("dictionary.ts", content);
1257
+ const locator = findDictionaryStageObject(source, "endpoint", `${moduleClassName}Endpoint`);
1258
+ if (!locator)
1259
+ return null;
1260
+ return insertOrderedFieldLine(content, locator, entryName, entryText, { fieldIndent: " ", closingIndent: " " });
1261
+ };
1093
1262
  var ensureConstantTypeImport = (content, constantPath, typeName) => {
1094
1263
  if (new RegExp(`import type \\{[^}]*\\b${typeName}\\b[^}]*\\} from "${constantPath}";`).test(content))
1095
1264
  return content;
@@ -1102,19 +1271,41 @@ var ensureConstantTypeImport = (content, constantPath, typeName) => {
1102
1271
  return `import type { ${typeName} } from "${constantPath}";
1103
1272
  ${content}`;
1104
1273
  };
1274
+ var dictionaryChainOf = (node) => {
1275
+ if (ts2.isCallExpression(node) && outermostFluentCall(node) === node && protectedDictionaryChainOrder.some((method) => chainMethodsForCall(node).includes(method)))
1276
+ return node;
1277
+ return ts2.forEachChild(node, dictionaryChainOf);
1278
+ };
1279
+ var chainMethodNames = (call) => {
1280
+ if (!ts2.isCallExpression(call) || !ts2.isPropertyAccessExpression(call.expression))
1281
+ return [];
1282
+ const name = call.expression.name;
1283
+ return [...chainMethodNames(call.expression.expression), ...ts2.isIdentifier(name) ? [name] : []];
1284
+ };
1105
1285
  var insertDictionaryEnum = (content, enumClassName, enumName, values) => {
1106
1286
  if (content.includes(`.enum<${enumClassName}>("${enumName}"`))
1107
1287
  return content;
1288
+ const source = sourceFileFor("dictionary.ts", content);
1289
+ if (hasParseDiagnostics(source))
1290
+ return null;
1291
+ const chain = dictionaryChainOf(source);
1292
+ if (!chain)
1293
+ return null;
1108
1294
  const enumBlock = ` .enum<${enumClassName}>("${enumName}", (t) => ({
1109
1295
  ${values.map((value) => ` ${value}: t([${JSON.stringify(titleize(value))}, ${JSON.stringify(titleize(value))}]),`).join(`
1110
1296
  `)}
1111
1297
  }))
1112
1298
  `;
1113
- const chainEndIndex = content.lastIndexOf(";");
1114
- const insertBeforeIndex = [content.indexOf(".error("), content.indexOf(".translate("), chainEndIndex].filter((index) => index >= 0).sort((a, b) => a - b)[0];
1115
- if (insertBeforeIndex === undefined)
1116
- return null;
1117
- return `${content.slice(0, insertBeforeIndex)}${enumBlock}${content.slice(insertBeforeIndex)}`;
1299
+ const later = chainMethodNames(chain).find((name) => name.text === "error" || name.text === "translate");
1300
+ if (!later)
1301
+ return spliceText(content, chain.getEnd(), chain.getEnd(), `
1302
+ ${enumBlock.trimEnd()}`);
1303
+ const dot = content.lastIndexOf(".", later.getStart(source));
1304
+ const lineStart = lineStartAt(content, dot);
1305
+ if (content.slice(lineStart, dot).trim() === "")
1306
+ return spliceText(content, lineStart, lineStart, enumBlock);
1307
+ return spliceText(content, dot, dot, `
1308
+ ${enumBlock}`);
1118
1309
  };
1119
1310
  var parseValues = (value) => value?.split(",").map((item) => item.trim()).filter(Boolean) ?? [];
1120
1311
  var hasSourceParseErrors = (content, fileName = "source.ts") => hasParseDiagnostics(sourceFileFor(fileName, content));
@@ -1144,6 +1335,14 @@ var hasClassMethod = (content, className, methodName) => {
1144
1335
  const node = findClassDeclaration(sourceFileFor("service.ts", content), className);
1145
1336
  return Boolean(node?.members.some((member) => ts2.isMethodDeclaration(member) && nodeName(member.name) === methodName));
1146
1337
  };
1338
+ var classMethodParameters = (content, className, methodName) => {
1339
+ const source = sourceFileFor("service.ts", content);
1340
+ const method = findClassDeclaration(source, className)?.members.find((member) => ts2.isMethodDeclaration(member) && nodeName(member.name) === methodName);
1341
+ return method?.parameters.map((parameter) => ({
1342
+ name: nodeName(parameter.name),
1343
+ optional: !!parameter.questionToken || !!parameter.initializer || !!parameter.dotDotDotToken
1344
+ })) ?? null;
1345
+ };
1147
1346
  var insertClassMethod = (content, className, methodBlock) => {
1148
1347
  const source = sourceFileFor("service.ts", content);
1149
1348
  const node = findClassDeclaration(source, className);
@@ -1228,6 +1427,33 @@ var insertSignalFactoryEntry = (content, className, entryName, entryLine, param)
1228
1427
  return null;
1229
1428
  return paramEdit === "unchanged" ? withEntry : spliceText(withEntry, paramEdit.start, paramEdit.end, paramEdit.text);
1230
1429
  };
1430
+ var appendTopLevelTestCases = (content, describeTitle, render) => {
1431
+ const bunImport = findNamedImport(sourceFileFor("test.ts", content), "bun:test", { valueOnly: true });
1432
+ const itName = !bunImport?.names.includes("it") && bunImport?.names.includes("test") ? "test" : "it";
1433
+ const imported = ensureNamedImport(content, "bun:test", itName);
1434
+ const source = sourceFileFor("test.ts", imported);
1435
+ const body = source.statements.flatMap((statement) => {
1436
+ if (!ts2.isExpressionStatement(statement) || !ts2.isCallExpression(statement.expression))
1437
+ return [];
1438
+ if (expressionName(statement.expression.expression) !== "describe")
1439
+ return [];
1440
+ const callback = factoryArrowOf(statement.expression);
1441
+ return callback && ts2.isBlock(callback.body) ? [callback.body] : [];
1442
+ })[0];
1443
+ if (!body) {
1444
+ const block = [`describe(${JSON.stringify(describeTitle)}, () => {`, ...render(itName, " "), "});", ""];
1445
+ return `${ensureNamedImport(imported, "bun:test", "describe").trimEnd()}
1446
+
1447
+ ${block.join(`
1448
+ `)}`;
1449
+ }
1450
+ const firstStatement = body.statements[0];
1451
+ const indent = firstStatement ? lineIndentAt(imported, firstStatement.getStart(source)) : `${lineIndentAt(imported, body.getStart(source))} `;
1452
+ const insertAt = lineStartAt(imported, body.getEnd() - 1);
1453
+ return spliceText(imported, insertAt, insertAt, `${render(itName, indent).join(`
1454
+ `)}
1455
+ `);
1456
+ };
1231
1457
 
1232
1458
  // pkgs/@akanjs/devkit/workflow/moduleIndex.ts
1233
1459
  var indexFileKinds = [
@@ -1891,10 +2117,10 @@ var addMutationActionSurfaceInspection = (plan) => {
1891
2117
  const moduleClassName = moduleComponentName(module);
1892
2118
  return surfaceReview(plan, {
1893
2119
  code: "add-mutation-action-surface-review",
1894
- target: `*/${moduleSourcePaths(module).store}`,
1895
- action: `Name the endpoint's guards and add its dictionary .endpoint() entry with a .desc(). After sync, fetch.${mutation} exists; write a store action only for a toast, an optimistic update, or a multi-field write, and put the control that calls it in ${moduleClassName}.Util.tsx.`,
1896
- message: `Workflow apply does not write store or UI code for ${module}.${mutation}; review whether a screen should call it.`,
1897
- reason: "Review action surface guidance before manually editing store or UI files."
2120
+ target: `*/${moduleSourcePaths(module).util}`,
2121
+ action: `Fill the ${moduleClassName} chain method (validate, mutate, return this) and replace its transition comment. After sync, call st.do.${mutation}(id) from the control in ${moduleClassName}.Util.tsx; a second write that must land with it is another with/after entry, never a second fetch in the store action.`,
2122
+ message: `Workflow apply does not write UI code for ${module}.${mutation}; review which screen calls it.`,
2123
+ reason: "Review action surface guidance before manually editing UI files."
1898
2124
  });
1899
2125
  };
1900
2126
  var addSliceViewSurfaceInspection = (plan) => {
@@ -1904,7 +2130,7 @@ var addSliceViewSurfaceInspection = (plan) => {
1904
2130
  return surfaceReview(plan, {
1905
2131
  code: "add-slice-view-surface-review",
1906
2132
  target: `*/${moduleSourcePaths(module).zone}`,
1907
- action: `Fill in the service query stub and add the dictionary .slice() entry. After sync, load fetch.init${moduleClassName}${capitalize2(slice)}() in the page and pass the result to a ${moduleClassName}.Zone as an init prop.`,
2133
+ action: `Fill in the service query stub and add the dictionary .slice() entry. After sync, load fetch.init${moduleClassName}${capitalize3(slice)}() in the page and pass the result to a ${moduleClassName}.Zone as an init prop.`,
1908
2134
  message: `Workflow apply does not write page or Zone code for ${module}.${slice}; review where the list should render.`,
1909
2135
  reason: "Review view surface guidance before manually editing Zone or page files."
1910
2136
  });
@@ -1917,7 +2143,8 @@ var createWorkflowStepRegistry = ({
1917
2143
  addField,
1918
2144
  addEnumField,
1919
2145
  addMutation,
1920
- addSlice
2146
+ addSlice,
2147
+ createInteraction
1921
2148
  }) => {
1922
2149
  const inspect = async () => {
1923
2150
  return;
@@ -1994,13 +2221,24 @@ var createWorkflowStepRegistry = ({
1994
2221
  })),
1995
2222
  [workflowStepKey("add-enum-field", "update-dictionary")]: inspect,
1996
2223
  [workflowStepKey("add-enum-field", "update-option")]: inspect,
1997
- [workflowStepKey("add-mutation", "update-service")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addMutation({
2224
+ [workflowStepKey("add-mutation", "update-document")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addMutation({
1998
2225
  app: workflowStringInput(plan.inputs.app),
1999
2226
  module: workflowStringInput(plan.inputs.module),
2000
- mutation: workflowStringInput(plan.inputs.mutation)
2227
+ mutation: workflowStringInput(plan.inputs.mutation),
2228
+ guards: workflowStringArrayInput(plan.inputs.guard),
2229
+ withCalls: workflowStringArrayInput(plan.inputs.with),
2230
+ afterCalls: workflowStringArrayInput(plan.inputs.after)
2001
2231
  })),
2232
+ [workflowStepKey("add-mutation", "update-service")]: inspect,
2002
2233
  [workflowStepKey("add-mutation", "update-signal")]: inspect,
2003
- [workflowStepKey("add-mutation", "update-action-surfaces")]: async (_step, plan) => addMutationActionSurfaceInspection(plan),
2234
+ [workflowStepKey("add-mutation", "update-store")]: inspect,
2235
+ [workflowStepKey("add-mutation", "update-dictionary")]: inspect,
2236
+ [workflowStepKey("add-mutation", "add-signal-test")]: inspect,
2237
+ [workflowStepKey("add-mutation", "connect-action-ui")]: async (_step, plan) => addMutationActionSurfaceInspection(plan),
2238
+ [workflowStepKey("create-interaction", "create-interaction")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await createInteraction({
2239
+ app: workflowStringInput(plan.inputs.app),
2240
+ interaction: workflowStringInput(plan.inputs.interaction)
2241
+ })),
2004
2242
  [workflowStepKey("add-slice", "update-service-query")]: async (_step, plan) => primitiveReportToWorkflowStepResult(await addSlice({
2005
2243
  app: workflowStringInput(plan.inputs.app),
2006
2244
  module: workflowStringInput(plan.inputs.module),
@@ -2084,8 +2322,626 @@ class WorkflowExecutor {
2084
2322
  return report();
2085
2323
  }
2086
2324
  }
2325
+ // pkgs/@akanjs/devkit/workflow/guardCatalog.ts
2326
+ class GuardCatalog {
2327
+ static frameworkGuards = ["Public"];
2328
+ static #actingArgOf = new Map([
2329
+ ["User", { argName: "Self", param: "self", value: "self.id", serviceParam: "selfId" }],
2330
+ [
2331
+ "SignedIn",
2332
+ { argName: "CurrentUserId", param: "currentUserId", value: "currentUserId", serviceParam: "currentUserId" }
2333
+ ]
2334
+ ]);
2335
+ #guards;
2336
+ #internalArgs;
2337
+ reachedLibs;
2338
+ constructor(guards, internalArgs, reachedLibs) {
2339
+ this.#guards = guards;
2340
+ this.#internalArgs = internalArgs;
2341
+ this.reachedLibs = reachedLibs;
2342
+ }
2343
+ static async load(sys) {
2344
+ const reachedLibs = await GuardCatalog.#reachedLibs(sys);
2345
+ const scopes = [{ type: sys.type, name: sys.name }, ...reachedLibs.map((name) => ({ type: "lib", name }))];
2346
+ const exports = (await Promise.all(scopes.map((scope) => GuardCatalog.#srvkitExports(sys, scope)))).flat();
2347
+ const frameworkGuards = GuardCatalog.frameworkGuards.map((name) => ({ name, specifier: "akanjs/signal" }));
2348
+ return new GuardCatalog([...exports.filter((entry) => entry.kind === "Guard"), ...frameworkGuards], exports.filter((entry) => entry.kind === "InternalArg"), reachedLibs);
2349
+ }
2350
+ get names() {
2351
+ return [...new Set(this.#guards.map((guard) => guard.name))];
2352
+ }
2353
+ resolve(name) {
2354
+ const matches = this.#guards.filter((guard) => guard.name === name);
2355
+ const specifiers = [...new Set(matches.map((guard) => guard.specifier))];
2356
+ return { specifier: specifiers[0] ?? null, ambiguous: specifiers.length > 1 ? specifiers : null };
2357
+ }
2358
+ actingUserOf(guards) {
2359
+ for (const guard of guards) {
2360
+ const acting = GuardCatalog.#actingArgOf.get(guard);
2361
+ const specifier = acting ? this.#internalArgs.find((entry) => entry.name === acting.argName)?.specifier : undefined;
2362
+ if (acting && specifier)
2363
+ return { ...acting, specifier };
2364
+ }
2365
+ return null;
2366
+ }
2367
+ static async#reachedLibs(sys) {
2368
+ const workspaceLibs = await sys.workspace.getLibs();
2369
+ const depsOf = async (type, name) => {
2370
+ const jsonPath = `${type}s/${name}/akan.${type}.json`;
2371
+ if (!await sys.workspace.exists(jsonPath))
2372
+ return null;
2373
+ const { libDeps } = await sys.workspace.readJson(jsonPath);
2374
+ return Array.isArray(libDeps) ? libDeps.filter((lib) => workspaceLibs.includes(lib)) : [];
2375
+ };
2376
+ const direct = await depsOf(sys.type, sys.name);
2377
+ if (!direct)
2378
+ return workspaceLibs.filter((lib) => sys.type !== "lib" || lib !== sys.name);
2379
+ const reached = new Set;
2380
+ const queue = [...direct];
2381
+ while (queue.length) {
2382
+ const lib = queue.shift();
2383
+ if (!lib || reached.has(lib) || sys.type === "lib" && lib === sys.name)
2384
+ continue;
2385
+ reached.add(lib);
2386
+ queue.push(...await depsOf("lib", lib) ?? []);
2387
+ }
2388
+ return [...reached];
2389
+ }
2390
+ static async#srvkitExports(sys, scope) {
2391
+ const dir = `${scope.type}s/${scope.name}/srvkit`;
2392
+ const files = (await sys.workspace.readdir(dir)).filter((file) => /\.tsx?$/.test(file) && !/\.(test|spec)\.tsx?$/.test(file) && file !== "index.ts");
2393
+ const specifier = `@${scope.type}s/${scope.name}/srvkit`;
2394
+ const contents = await Promise.all(files.map((file) => sys.workspace.readFile(`${dir}/${file}`)));
2395
+ return contents.flatMap((content) => [...content.matchAll(/export class ([A-Z][A-Za-z0-9_]*)\s+implements\s+([^{]+)\{/g)].flatMap((match) => {
2396
+ const implemented = (match[2] ?? "").split(",").map((name) => name.replace(/<.*$/s, "").trim());
2397
+ const kind = implemented.includes("Guard") ? "Guard" : implemented.includes("InternalArg") ? "InternalArg" : null;
2398
+ return kind && match[1] ? [{ kind, name: match[1], specifier }] : [];
2399
+ }));
2400
+ }
2401
+ }
2402
+ // pkgs/@akanjs/devkit/workflow/mutationScaffold.ts
2403
+ import { lowerlize as lowerlize4 } from "akanjs/common";
2404
+
2405
+ // pkgs/@akanjs/devkit/workflow/mutationSource.ts
2406
+ import { lowerlize as lowerlize3 } from "akanjs/common";
2407
+ class MutationSource {
2408
+ static #irregularParticiples = new Map([
2409
+ ["admit", "admitted"],
2410
+ ["bind", "bound"],
2411
+ ["build", "built"],
2412
+ ["choose", "chosen"],
2413
+ ["commit", "committed"],
2414
+ ["control", "controlled"],
2415
+ ["cut", "cut"],
2416
+ ["find", "found"],
2417
+ ["freeze", "frozen"],
2418
+ ["get", "got"],
2419
+ ["give", "given"],
2420
+ ["hide", "hidden"],
2421
+ ["hold", "held"],
2422
+ ["keep", "kept"],
2423
+ ["lead", "led"],
2424
+ ["leave", "left"],
2425
+ ["lose", "lost"],
2426
+ ["make", "made"],
2427
+ ["omit", "omitted"],
2428
+ ["pay", "paid"],
2429
+ ["permit", "permitted"],
2430
+ ["put", "put"],
2431
+ ["read", "read"],
2432
+ ["run", "run"],
2433
+ ["sell", "sold"],
2434
+ ["send", "sent"],
2435
+ ["set", "set"],
2436
+ ["show", "shown"],
2437
+ ["shut", "shut"],
2438
+ ["split", "split"],
2439
+ ["submit", "submitted"],
2440
+ ["take", "taken"],
2441
+ ["transfer", "transferred"],
2442
+ ["win", "won"],
2443
+ ["write", "written"]
2444
+ ]);
2445
+ spec;
2446
+ modelClassName;
2447
+ model;
2448
+ idParam;
2449
+ chainMethod;
2450
+ constructor(spec) {
2451
+ this.spec = spec;
2452
+ this.modelClassName = moduleComponentName(spec.module);
2453
+ this.model = lowerlize3(this.modelClassName);
2454
+ this.idParam = `${this.model}Id`;
2455
+ this.chainMethod = MutationSource.chainMethodOf(spec.mutation, this.modelClassName);
2456
+ }
2457
+ static chainMethodOf(mutation, modelClassName) {
2458
+ const dropped = mutation.replace(modelClassName, "");
2459
+ return dropped && dropped !== mutation ? lowerlize3(dropped) : mutation;
2460
+ }
2461
+ static participleOf(verb) {
2462
+ const irregular = MutationSource.#irregularParticiples.get(verb);
2463
+ if (irregular)
2464
+ return irregular;
2465
+ if (verb.endsWith("e"))
2466
+ return `${verb}d`;
2467
+ if (/[^aeiou]y$/.test(verb))
2468
+ return `${verb.slice(0, -1)}ied`;
2469
+ if (/^[^aeiou]*[aeiou][^aeiouwxy]$/.test(verb))
2470
+ return `${verb}${verb.at(-1)}ed`;
2471
+ return `${verb}ed`;
2472
+ }
2473
+ get isPublic() {
2474
+ return this.spec.guards.includes("Public");
2475
+ }
2476
+ get #verb() {
2477
+ return this.chainMethod.replace(/[A-Z].*$/s, "");
2478
+ }
2479
+ get #noun() {
2480
+ return titleize(this.model).toLowerCase();
2481
+ }
2482
+ get chainMethodBlock() {
2483
+ return [
2484
+ ` // any \u2192 ${MutationSource.participleOf(this.#verb)}.`,
2485
+ ` ${this.chainMethod}() {`,
2486
+ " return this;",
2487
+ " }"
2488
+ ].join(`
2489
+ `);
2490
+ }
2491
+ get serviceMethod() {
2492
+ return this.chainMethod;
2493
+ }
2494
+ get serviceMethodBlock() {
2495
+ const { acting } = this.spec;
2496
+ const params = [`${this.idParam}: string`, ...acting ? [`${acting.serviceParam}: string`] : []];
2497
+ const load = `const ${this.model} = await this.get${this.modelClassName}(${this.idParam});`;
2498
+ const owned = acting ? [
2499
+ `// TODO: ${this.spec.guards.join(" and ")} admits any signed-in caller; refuse a ${acting.serviceParam} that may not ${this.#verb} this ${this.#noun}.`
2500
+ ] : [];
2501
+ const chained = `${this.model}.${this.chainMethod}().save()`;
2502
+ const head = ` async ${this.serviceMethod}(${params.join(", ")}) {`;
2503
+ if (!this.spec.withCalls.length && !this.spec.afterCalls.length)
2504
+ return [head, ` ${load}`, ...owned.map((line) => ` ${line}`), ` return await ${chained};`, " }"].join(`
2505
+ `);
2506
+ return [
2507
+ head,
2508
+ " return await this.transaction(async () => {",
2509
+ ` ${load}`,
2510
+ ...owned.map((line) => ` ${line}`),
2511
+ ` await ${chained};`,
2512
+ ...this.spec.withCalls.map((call) => ` await ${MutationSource.#callOf(call)};`),
2513
+ ...this.spec.afterCalls.map((call) => ` await this.afterCommit(() => ${MutationSource.#callOf(call)});`),
2514
+ ` return ${this.model};`,
2515
+ " });",
2516
+ " }"
2517
+ ].join(`
2518
+ `);
2519
+ }
2520
+ get signalEntry() {
2521
+ const options = this.isPublic ? `{ guards: [${this.spec.guards.join(", ")}], rateLimit: { calls: 20 } }` : `{ guards: [${this.spec.guards.join(", ")}] }`;
2522
+ const { acting } = this.spec;
2523
+ const execParams = [this.idParam, ...acting ? [acting.param] : []];
2524
+ const serviceArgs = [this.idParam, ...acting ? [acting.value] : []];
2525
+ return [
2526
+ `${this.spec.mutation}: mutation(cnst.${this.modelClassName}, ${options})`,
2527
+ ` .param("${this.idParam}", ID)`,
2528
+ ...acting ? [` .with(${acting.argName})`] : [],
2529
+ ` .exec(async function (${execParams.join(", ")}) {`,
2530
+ ` return await this.${this.model}Service.${this.serviceMethod}(${serviceArgs.join(", ")});`,
2531
+ " }),"
2532
+ ].join(`
2533
+ `);
2534
+ }
2535
+ get storeActionBlock() {
2536
+ return [
2537
+ ` async ${this.spec.mutation}(${this.idParam}: string) {`,
2538
+ ` this.set${this.modelClassName}(await fetch.${this.spec.mutation}(${this.idParam}));`,
2539
+ " }"
2540
+ ].join(`
2541
+ `);
2542
+ }
2543
+ dictionaryEntryOf(modelKo) {
2544
+ const label = bilingualLabelForField(this.spec.mutation);
2545
+ const modelLabel = { ...bilingualLabelForField(this.model), ...modelKo ? { ko: modelKo } : {} };
2546
+ const pair = (en, ko) => `[${JSON.stringify(en)}, ${JSON.stringify(ko)}]`;
2547
+ const idPair = pair(`${modelLabel.en} ID`, `${modelLabel.ko} ID`);
2548
+ return [
2549
+ `${this.spec.mutation}: fn(${pair(label.en, label.ko)})`,
2550
+ ` .desc(${pair(`API to ${label.en.toLowerCase()}`, `${label.ko} API`)})`,
2551
+ " .arg((t) => ({",
2552
+ ` ${this.idParam}: t(${idPair}).desc(${idPair}),`,
2553
+ " })),"
2554
+ ].join(`
2555
+ `);
2556
+ }
2557
+ get testTitles() {
2558
+ const guards = this.spec.guards.join(" and ");
2559
+ const participle = MutationSource.participleOf(this.#verb);
2560
+ return [
2561
+ `${this.spec.mutation} leaves the ${this.#noun} ${participle} for a caller ${guards} admits`,
2562
+ ...this.spec.guards.every((guard) => guard === "Public") ? [] : [`${this.spec.mutation} refuses a caller ${guards} turns away`],
2563
+ ...this.spec.acting ? [`${this.spec.mutation} refuses a signed-in caller who may not ${this.#verb} the ${this.#noun}`] : []
2564
+ ];
2565
+ }
2566
+ testCaseLines(itName, indent) {
2567
+ return this.testTitles.map((title) => `${indent}${itName}.todo(${JSON.stringify(title)});`);
2568
+ }
2569
+ get testFile() {
2570
+ return [
2571
+ 'import { describe, it } from "bun:test";',
2572
+ "",
2573
+ `describe(${JSON.stringify(`${this.modelClassName} Signal`)}, () => {`,
2574
+ ...this.testCaseLines("it", " "),
2575
+ "});",
2576
+ ""
2577
+ ].join(`
2578
+ `);
2579
+ }
2580
+ static #callOf(call) {
2581
+ const target = call.field ? `this.${call.field}` : "this";
2582
+ return `${target}.${call.method}(${call.args.join(", ")})`;
2583
+ }
2584
+ }
2585
+
2586
+ // pkgs/@akanjs/devkit/workflow/mutationScaffold.ts
2587
+ class MutationScaffold {
2588
+ static #documentMethods = new Set(["isModified", "refresh", "remove", "save", "set", "toJSON", "toObject"]);
2589
+ static #serviceMethods = new Set(["afterCommit", "logger", "onDestroy", "onInit", "transaction"]);
2590
+ static #callPattern = /^_?([a-z][A-Za-z0-9]*)\.([A-Za-z_$][\w$]*)$/;
2591
+ #sys;
2592
+ #catalog;
2593
+ #strict;
2594
+ #diagnostics = [];
2595
+ constructor(sys, catalog, { strict }) {
2596
+ this.#sys = sys;
2597
+ this.#catalog = catalog;
2598
+ this.#strict = strict;
2599
+ }
2600
+ static reservedNamesOf(modelClassName) {
2601
+ const model = lowerlize4(modelClassName);
2602
+ const prefixed = ["light", "create", "update", "remove", "view", "edit", "merge", "get", "load", "set", "reset"];
2603
+ return new Set([
2604
+ model,
2605
+ ...[...prefixed, "new", "submit", "invalidate"].map((prefix) => `${prefix}${modelClassName}`),
2606
+ `create${modelClassName}InForm`,
2607
+ `update${modelClassName}InForm`,
2608
+ `load${modelClassName}Many`,
2609
+ `get${modelClassName}View`,
2610
+ `get${modelClassName}Edit`,
2611
+ `add${modelClassName}Files`,
2612
+ `check${modelClassName}Submitable`,
2613
+ `writeOn${modelClassName}`,
2614
+ ...["load", "restore", "discard"].map((prefix) => `${prefix}${modelClassName}FormDraft`)
2615
+ ]);
2616
+ }
2617
+ static generates(modelClassName, name) {
2618
+ return MutationScaffold.reservedNamesOf(modelClassName).has(name) || new RegExp(`^(init${modelClassName}|get${modelClassName}Init|(set|add|sub|upload)\\w+On${modelClassName}$)`).test(name);
2619
+ }
2620
+ static inputDiagnostics(input) {
2621
+ const diagnostics = [];
2622
+ const error = (code, inputName, message) => diagnostics.push({ severity: "error", code, input: inputName, message });
2623
+ const { module, mutation } = input;
2624
+ if (mutation && !/^[a-z][A-Za-z0-9]*$/.test(mutation))
2625
+ error("add-mutation-name-invalid", "mutation", `Mutation name "${mutation}" must be a camelCase identifier.`);
2626
+ if (module && mutation) {
2627
+ const modelClassName = moduleComponentName(module);
2628
+ if (MutationScaffold.generates(modelClassName, mutation))
2629
+ error("add-mutation-name-reserved", "mutation", `"${mutation}" collides with a name Akan generates for ${modelClassName} (CRUD endpoints, store actions, form setters). Name the act, e.g. archive${modelClassName}.`);
2630
+ const chainMethod = MutationSource.chainMethodOf(mutation, modelClassName);
2631
+ if (MutationScaffold.#documentMethods.has(chainMethod))
2632
+ error("add-mutation-name-reserved", "mutation", `"${mutation}" drops to the document chain method ${chainMethod}(), which every document already has.`);
2633
+ else if (MutationScaffold.#serviceMethods.has(chainMethod))
2634
+ error("add-mutation-name-reserved", "mutation", `"${mutation}" drops to the service method ${chainMethod}(), which every service already has.`);
2635
+ }
2636
+ const guards = input.guards ?? [];
2637
+ if (!guards.length)
2638
+ error("add-mutation-guard-missing", "guard", "Name the guard(s) that admit a caller (guard=Admin, guard=Every,Person); add-mutation has no default guard.");
2639
+ for (const guard of guards) {
2640
+ if (guard === "None")
2641
+ error("add-mutation-guard-none", "guard", "None answers no caller, so the endpoint would ship dead; name the guard that admits the intended caller.");
2642
+ else if (!/^[A-Z][A-Za-z0-9]*$/.test(guard))
2643
+ error("add-mutation-guard-invalid", "guard", `Guard "${guard}" must be a guard class name.`);
2644
+ }
2645
+ for (const [inputName, calls] of [
2646
+ ["with", input.withCalls],
2647
+ ["after", input.afterCalls]
2648
+ ]) {
2649
+ for (const call of calls ?? [])
2650
+ if (!MutationScaffold.#callPattern.test(call))
2651
+ error("add-mutation-call-invalid", inputName, `"${call}" must name a service method as <serviceRef>.<method>, e.g. courtPc.pushPcCommand.`);
2652
+ }
2653
+ return diagnostics;
2654
+ }
2655
+ static async build(sys, input, { strict = true } = {}) {
2656
+ return await new MutationScaffold(sys, await GuardCatalog.load(sys), { strict }).#build(input);
2657
+ }
2658
+ async#build(input) {
2659
+ const files = [];
2660
+ const recommendations = [];
2661
+ this.#diagnostics.push(...MutationScaffold.inputDiagnostics(input));
2662
+ const { module, mutation } = input;
2663
+ const guards = [...new Set(input.guards ?? [])];
2664
+ const guardSpecifiers = this.#resolveGuards(guards);
2665
+ if (this.#hasGuardError())
2666
+ recommendations.push({
2667
+ code: "add-mutation-guard-choices",
2668
+ kind: "input-guidance",
2669
+ confidence: "high",
2670
+ message: `Guards this target reaches: ${this.#catalog.names.join(", ") || "none"}.`,
2671
+ action: "Re-plan with guard set to one or more of these names."
2672
+ });
2673
+ if (!module || !mutation || this.#hasError())
2674
+ return this.#result(files, recommendations);
2675
+ const paths = moduleSourcePaths(module);
2676
+ const sourcePaths = [paths.document, paths.service, paths.signal, paths.store, paths.dictionary];
2677
+ const present = await Promise.all(sourcePaths.map((path) => this.#sys.exists(path)));
2678
+ const missing = sourcePaths.filter((_, idx) => !present[idx]);
2679
+ if (missing.length) {
2680
+ this.#report("add-mutation-module-missing", `Module ${module} lacks ${missing.join(", ")}; add-mutation writes into an existing database module (create-module first).`, { input: "module" });
2681
+ return this.#result(files, recommendations);
2682
+ }
2683
+ const acting = this.#catalog.actingUserOf(guards);
2684
+ if (acting)
2685
+ recommendations.push({
2686
+ code: "add-mutation-ownership",
2687
+ kind: "manual-action",
2688
+ confidence: "high",
2689
+ message: `${guards.join(" and ")} admits any signed-in caller, so the service receives ${acting.serviceParam} and a TODO where it must refuse a caller who may not act on this ${module}.`,
2690
+ action: `Check ${acting.serviceParam} against the ${module} before the chain, or guard the mutation with a Can<Verb><Model> resource guard.`
2691
+ });
2692
+ const source = new MutationSource({
2693
+ module,
2694
+ mutation,
2695
+ guards,
2696
+ acting,
2697
+ withCalls: [],
2698
+ afterCalls: []
2699
+ });
2700
+ const [document, service, signal, store, dictionary] = await Promise.all(sourcePaths.map((path) => this.#sys.readFile(path)));
2701
+ await this.#checkNameFree(source, { service, signal, store, dictionary });
2702
+ const withCalls = await this.#resolveCalls(source, input.withCalls ?? [], "with", acting);
2703
+ const afterCalls = await this.#resolveCalls(source, input.afterCalls ?? [], "after", acting);
2704
+ if (this.#hasError())
2705
+ return this.#result(files, recommendations);
2706
+ const shaped = new MutationSource({ module, mutation, guards, acting, withCalls, afterCalls });
2707
+ const testPath = `lib/${module}/${module}.signal.test.ts`;
2708
+ const testExists = await this.#sys.exists(testPath);
2709
+ const edits = [
2710
+ [paths.document, this.#editDocument(document, shaped), "Document chain method was added.", "modify"],
2711
+ [
2712
+ paths.service,
2713
+ this.#editService(service, shaped, [...withCalls, ...afterCalls]),
2714
+ "Service mutation was added.",
2715
+ "modify"
2716
+ ],
2717
+ [paths.signal, this.#editSignal(signal, shaped, guardSpecifiers, acting), "Signal mutation was added.", "modify"],
2718
+ [paths.store, this.#editStore(store, shaped), "Store action was added.", "modify"],
2719
+ [paths.dictionary, this.#editDictionary(dictionary, shaped), "Dictionary endpoint entry was added.", "modify"],
2720
+ [
2721
+ testPath,
2722
+ testExists ? appendTopLevelTestCases(await this.#sys.readFile(testPath), `${shaped.modelClassName} Signal`, (itName, indent) => shaped.testCaseLines(itName, indent)) : shaped.testFile,
2723
+ "Signal test placeholders were added.",
2724
+ testExists ? "modify" : "create"
2725
+ ]
2726
+ ];
2727
+ for (const [path, content, reason, action] of edits) {
2728
+ if (content === null)
2729
+ continue;
2730
+ if (hasSourceParseErrors(content, path))
2731
+ this.#report("add-mutation-post-edit-parse-failed", `Edited ${path} did not parse; refusing to write source.`, {
2732
+ severity: "error"
2733
+ });
2734
+ files.push({ path, content, reason, action });
2735
+ }
2736
+ return this.#result(files, recommendations);
2737
+ }
2738
+ #result(files, recommendations) {
2739
+ const diagnostics = this.#diagnostics;
2740
+ return { diagnostics, recommendations, files: this.#hasError() ? [] : files };
2741
+ }
2742
+ #hasError() {
2743
+ return this.#diagnostics.some((diagnostic) => diagnostic.severity === "error");
2744
+ }
2745
+ #hasGuardError() {
2746
+ return this.#diagnostics.some((diagnostic) => diagnostic.code.startsWith("add-mutation-guard"));
2747
+ }
2748
+ #report(code, message, { input, severity } = {}) {
2749
+ this.#diagnostics.push({
2750
+ severity: severity ?? (this.#strict ? "error" : "warning"),
2751
+ code,
2752
+ message,
2753
+ input,
2754
+ failureScope: "source-change"
2755
+ });
2756
+ }
2757
+ #resolveGuards(guards) {
2758
+ const specifiers = new Map;
2759
+ for (const guard of guards) {
2760
+ if (guard === "None")
2761
+ continue;
2762
+ const { specifier, ambiguous } = this.#catalog.resolve(guard);
2763
+ if (ambiguous)
2764
+ this.#report("add-mutation-guard-ambiguous", `Guard "${guard}" is exported by ${ambiguous.join(" and ")}.`, {
2765
+ input: "guard",
2766
+ severity: "error"
2767
+ });
2768
+ else if (!specifier)
2769
+ this.#report("add-mutation-guard-unknown", `Guard "${guard}" is not exported by ${this.#sys.type}s/${this.#sys.name}/srvkit, the srvkit of a lib it reaches (${this.#catalog.reachedLibs.join(", ") || "none"}), or akanjs/signal.`, { input: "guard", severity: "error" });
2770
+ else
2771
+ specifiers.set(guard, specifier);
2772
+ }
2773
+ return specifiers;
2774
+ }
2775
+ async#checkNameFree(source, files) {
2776
+ const { mutation } = source.spec;
2777
+ const { modelClassName } = source;
2778
+ const taken = [
2779
+ hasClassMethod(files.service, `${modelClassName}Service`, source.serviceMethod) && `${modelClassName}Service.${source.serviceMethod}()`,
2780
+ ["Internal", "Slice", "Endpoint"].some((kind) => hasSignalFactoryEntry(files.signal, `${modelClassName}${kind}`, mutation)) && `${source.spec.module}.signal.ts`,
2781
+ hasClassMethod(files.store, `${modelClassName}Store`, mutation) && `${modelClassName}Store`,
2782
+ hasDictionaryEndpointEntry(files.dictionary, modelClassName, mutation) && `${source.spec.module}.dictionary.ts`,
2783
+ ...await this.#signalsDeclaring(mutation, source.spec.module)
2784
+ ].filter((place) => !!place);
2785
+ if (taken.length)
2786
+ this.#report("add-mutation-name-exists", `"${mutation}" already exists in ${taken.join(", ")}.`, {
2787
+ input: "mutation",
2788
+ severity: "error"
2789
+ });
2790
+ }
2791
+ async#signalsDeclaring(mutation, ownModule) {
2792
+ const pattern = new RegExp(`^\\s*${mutation}:\\s*(mutation|query|pubsub|message)\\(`, "m");
2793
+ const roots = [`${this.#sys.type}s/${this.#sys.name}`, ...this.#catalog.reachedLibs.map((lib) => `libs/${lib}`)];
2794
+ const hits = await Promise.all(roots.map(async (root) => {
2795
+ if (!await this.#sys.workspace.exists(`${root}/lib`))
2796
+ return [];
2797
+ const folders = (await this.#sys.workspace.readdir(`${root}/lib`)).filter((folder) => !folder.includes(".") && !folder.startsWith("__") && !(root === roots[0] && folder === ownModule));
2798
+ return await Promise.all(folders.map(async (folder) => {
2799
+ const name = folder.replace(/^_+/, "");
2800
+ const base = `${root}/lib/${folder}/${name}`;
2801
+ if (await this.#sys.workspace.exists(`${base}.document.ts`) && MutationScaffold.generates(moduleComponentName(name), mutation))
2802
+ return `${root}/lib/${folder} (generated for ${moduleComponentName(name)})`;
2803
+ if (!await this.#sys.workspace.exists(`${base}.signal.ts`))
2804
+ return null;
2805
+ return pattern.test(await this.#sys.workspace.readFile(`${base}.signal.ts`)) ? `${base}.signal.ts` : null;
2806
+ }));
2807
+ }));
2808
+ return hits.flat().filter((hit) => !!hit);
2809
+ }
2810
+ async#resolveCalls(source, calls, inputName, acting) {
2811
+ const resolved = [];
2812
+ for (const call of calls) {
2813
+ const [rawRef = "", method = ""] = call.split(".");
2814
+ const ref = rawRef.replace(/^_+/, "");
2815
+ const isOwn = ref === source.model;
2816
+ const service = await this.#serviceSourceOf(ref, isOwn);
2817
+ if (!service) {
2818
+ this.#report("add-mutation-call-service-missing", `${inputName}: no ${moduleComponentName(ref)}Service in ${this.#sys.name} or the libs it reaches.`, { input: inputName });
2819
+ continue;
2820
+ }
2821
+ const params = this.#parametersOf(service, ref, method);
2822
+ if (!params) {
2823
+ this.#report("add-mutation-call-method-missing", `${inputName}: ${service.className} has no ${method}().`, {
2824
+ input: inputName
2825
+ });
2826
+ continue;
2827
+ }
2828
+ const scope = new Map([
2829
+ [source.idParam, `${source.model}.id`],
2830
+ [source.model, source.model],
2831
+ ...isOwn ? [["id", `${source.model}.id`]] : [],
2832
+ ...acting ? [[acting.serviceParam, acting.serviceParam]] : []
2833
+ ]);
2834
+ const args = [];
2835
+ for (const param of params) {
2836
+ const value = param.name ? scope.get(param.name) : undefined;
2837
+ if (value) {
2838
+ args.push(value);
2839
+ continue;
2840
+ }
2841
+ if (!param.optional)
2842
+ this.#report("add-mutation-call-args-unresolved", `${inputName}: ${service.className}.${method}() takes "${param.name ?? "?"}", which add-mutation cannot supply. Name a method taking the ${source.model}, its id or the acting user, or call this one by hand after apply.`, { input: inputName, severity: "error" });
2843
+ break;
2844
+ }
2845
+ const field = isOwn ? null : `${ref}Service`;
2846
+ resolved.push({
2847
+ ref,
2848
+ method,
2849
+ field,
2850
+ args,
2851
+ injection: field ? { field, typeRef: service.typeRef } : null
2852
+ });
2853
+ }
2854
+ return resolved;
2855
+ }
2856
+ async#serviceSourceOf(ref, isOwn) {
2857
+ const className = `${moduleComponentName(ref)}Service`;
2858
+ const scopes = [
2859
+ { root: `${this.#sys.type}s/${this.#sys.name}`, typeRef: `srv.${className}` },
2860
+ ...isOwn ? [] : this.#catalog.reachedLibs.map((lib) => ({ root: `libs/${lib}`, typeRef: `srv.${lib}.${className}` }))
2861
+ ];
2862
+ for (const { root, typeRef } of scopes) {
2863
+ for (const folder of [ref, `_${ref}`]) {
2864
+ const path = `${root}/lib/${folder}/${ref}.service.ts`;
2865
+ if (await this.#sys.workspace.exists(path))
2866
+ return { className, typeRef, content: await this.#sys.workspace.readFile(path) };
2867
+ }
2868
+ }
2869
+ return null;
2870
+ }
2871
+ #parametersOf(service, ref, method) {
2872
+ const declared = classMethodParameters(service.content, service.className, method);
2873
+ if (declared)
2874
+ return declared;
2875
+ const modelClassName = moduleComponentName(ref);
2876
+ const generated = {
2877
+ [`get${modelClassName}`]: [{ name: "id", optional: false }],
2878
+ [`load${modelClassName}`]: [{ name: "id", optional: true }],
2879
+ [`load${modelClassName}Many`]: [{ name: "ids", optional: false }],
2880
+ [`create${modelClassName}`]: [{ name: "data", optional: false }],
2881
+ [`update${modelClassName}`]: [
2882
+ { name: "id", optional: false },
2883
+ { name: "data", optional: false }
2884
+ ],
2885
+ [`remove${modelClassName}`]: [{ name: "id", optional: false }]
2886
+ };
2887
+ return generated[method] ?? null;
2888
+ }
2889
+ #editDocument(content, source) {
2890
+ if (hasClassMethod(content, source.modelClassName, source.chainMethod)) {
2891
+ this.#report("add-mutation-chain-method-reused", `${source.modelClassName}.${source.chainMethod}() already exists; the service chains it as is.`, { severity: "warning" });
2892
+ return null;
2893
+ }
2894
+ return this.#required(insertClassMethod(content, source.modelClassName, source.chainMethodBlock), `class ${source.modelClassName} in the document`);
2895
+ }
2896
+ #editService(content, source, calls) {
2897
+ const className = `${source.modelClassName}Service`;
2898
+ let next = content;
2899
+ for (const { injection } of calls) {
2900
+ if (!next || !injection || hasSignalFactoryEntry(next, className, injection.field))
2901
+ continue;
2902
+ next = insertSignalFactoryEntry(next, className, injection.field, `${injection.field}: service<${injection.typeRef}>(),`, {
2903
+ mode: "destructure",
2904
+ name: "service"
2905
+ });
2906
+ if (next && !/\* as srv from "\.\.\/srv";/.test(next))
2907
+ next = ensureImportDeclaration(next, "../srv", "type * as srv");
2908
+ }
2909
+ next = next && insertClassMethod(next, className, source.serviceMethodBlock);
2910
+ return this.#required(next, `${className} and its serve() factory`);
2911
+ }
2912
+ #editSignal(content, source, guardSpecifiers, acting) {
2913
+ let next = insertSignalFactoryEntry(content, `${source.modelClassName}Endpoint`, source.spec.mutation, source.signalEntry, { mode: "destructure", name: "mutation" });
2914
+ if (!next)
2915
+ return this.#required(next, `${source.modelClassName}Endpoint and its endpoint() factory`);
2916
+ next = ensureNamedImport(next, "akanjs/base", "ID");
2917
+ if (!/\* as cnst from "\.\.\/cnst";/.test(next))
2918
+ next = ensureImportDeclaration(next, "../cnst", "* as cnst");
2919
+ for (const [guard, specifier] of guardSpecifiers)
2920
+ next = ensureNamedImport(next, specifier, guard);
2921
+ if (acting)
2922
+ next = ensureNamedImport(next, acting.specifier, acting.argName);
2923
+ return next;
2924
+ }
2925
+ #editStore(content, source) {
2926
+ const next = insertClassMethod(content, `${source.modelClassName}Store`, source.storeActionBlock);
2927
+ return this.#required(next && ensureNamedImport(next, "../useClient", "fetch"), `${source.modelClassName}Store`);
2928
+ }
2929
+ #editDictionary(content, source) {
2930
+ return this.#required(insertDictionaryEndpointEntry(content, source.modelClassName, source.spec.mutation, source.dictionaryEntryOf(MutationScaffold.#modelKoOf(content))), `.endpoint<${source.modelClassName}Endpoint>() in the dictionary`);
2931
+ }
2932
+ static #modelKoOf(dictionary) {
2933
+ return dictionary.match(/\.of\(\s*\(t\)\s*=>\s*t\(\s*\[\s*"[^"]*"\s*,\s*"([^"]+)"\s*\]/)?.[1];
2934
+ }
2935
+ #required(content, shape) {
2936
+ if (!content)
2937
+ this.#report("add-mutation-shape-unsupported", `Could not find ${shape}; refusing to write source.`, {
2938
+ severity: "error"
2939
+ });
2940
+ return content;
2941
+ }
2942
+ }
2087
2943
  // pkgs/@akanjs/devkit/workflow/plan.ts
2088
- import { capitalize as capitalize3 } from "akanjs/common";
2944
+ import { capitalize as capitalize4 } from "akanjs/common";
2089
2945
  var surfaceModes = new Set(["infer", "include", "skip"]);
2090
2946
  var parseStringList = (value) => {
2091
2947
  if (Array.isArray(value)) {
@@ -2228,7 +3084,7 @@ var createAddFieldRecommendations = (inputs) => {
2228
3084
  kind: "placement",
2229
3085
  target: paths.constant,
2230
3086
  confidence: "high",
2231
- message: `Insert ${field}: field(${normalizedType}) in ${capitalize3(module)}Input.`
3087
+ message: `Insert ${field}: field(${normalizedType}) in ${capitalize4(module)}Input.`
2232
3088
  },
2233
3089
  {
2234
3090
  code: "add-field-placement-dictionary",
@@ -2260,12 +3116,12 @@ var createAddFieldRecommendations = (inputs) => {
2260
3116
  kind: "placement",
2261
3117
  target: paths.constant,
2262
3118
  confidence: "high",
2263
- message: `Add ${field} to Light${capitalize3(module)} projection fields.`
3119
+ message: `Add ${field} to Light${capitalize4(module)} projection fields.`
2264
3120
  } : {
2265
3121
  code: "add-field-light-projection-choice",
2266
3122
  kind: "manual-action",
2267
3123
  target: paths.constant,
2268
- action: `Pass includeInLight=true when users should see ${field} in list/card data. Without it, the field can exist on ${capitalize3(module)}Input but stay absent from Light${capitalize3(module)} projections.`,
3124
+ action: `Pass includeInLight=true when users should see ${field} in list/card data. Without it, the field can exist on ${capitalize4(module)}Input but stay absent from Light${capitalize4(module)} projections.`,
2269
3125
  confidence: "medium",
2270
3126
  message: `${module}.${field} is not selected for list/card projection data.`
2271
3127
  },
@@ -2283,7 +3139,7 @@ var createAddFieldRecommendations = (inputs) => {
2283
3139
  code: "add-field-ui-manual-review",
2284
3140
  kind: "manual-action",
2285
3141
  target: paths.template,
2286
- action: `After apply, verify what users can see: Template form auto-edit only runs when a generated ${module}Form hook and Layout.Template field list are present. Unit/View cards are not auto-edited, so ${field} may be stored on ${capitalize3(module)} but not shown in list/card UI until you place it in the local card layout.`,
3142
+ action: `After apply, verify what users can see: Template form auto-edit only runs when a generated ${module}Form hook and Layout.Template field list are present. Unit/View cards are not auto-edited, so ${field} may be stored on ${capitalize4(module)} but not shown in list/card UI until you place it in the local card layout.`,
2287
3143
  confidence: "medium",
2288
3144
  message: `${app}:${module}.${field} may need UI review for user-visible Template, Unit, and View behavior.`
2289
3145
  },
@@ -2435,6 +3291,45 @@ var createWorkflowPlan = (spec, rawInputs) => {
2435
3291
  approval: workflowPlanApproval
2436
3292
  };
2437
3293
  };
3294
+ var planString = (inputs, name) => typeof inputs[name] === "string" ? inputs[name] : null;
3295
+ var planStrings = (inputs, name) => Array.isArray(inputs[name]) ? inputs[name] : null;
3296
+ var inspectWorkflowPlan = async (workspace, plan) => {
3297
+ if (plan.workflow !== "add-mutation" && plan.workflow !== "create-interaction")
3298
+ return plan;
3299
+ const app = planString(plan.inputs, "app");
3300
+ if (!app)
3301
+ return plan;
3302
+ const sys = await resolveWorkflowSys(workspace, app).catch(() => null);
3303
+ if (!sys)
3304
+ return {
3305
+ ...plan,
3306
+ diagnostics: [
3307
+ ...plan.diagnostics,
3308
+ {
3309
+ severity: "error",
3310
+ code: "workflow-target-missing",
3311
+ input: "app",
3312
+ message: `No app or library named ${app}.`
3313
+ }
3314
+ ]
3315
+ };
3316
+ const inspected = plan.workflow === "add-mutation" ? await MutationScaffold.build(sys, {
3317
+ module: planString(plan.inputs, "module"),
3318
+ mutation: planString(plan.inputs, "mutation"),
3319
+ guards: planStrings(plan.inputs, "guard"),
3320
+ withCalls: planStrings(plan.inputs, "with"),
3321
+ afterCalls: planStrings(plan.inputs, "after")
3322
+ }, { strict: false }) : { ...await InteractionScaffold.build(sys, planString(plan.inputs, "interaction")), recommendations: [] };
3323
+ const failedInputs = new Set(plan.diagnostics.filter((diagnostic) => diagnostic.severity === "error").map((diagnostic) => diagnostic.input));
3324
+ return {
3325
+ ...plan,
3326
+ diagnostics: [
3327
+ ...plan.diagnostics,
3328
+ ...inspected.diagnostics.filter((diagnostic) => !diagnostic.input || !failedInputs.has(diagnostic.input))
3329
+ ],
3330
+ recommendations: [...plan.recommendations, ...inspected.recommendations]
3331
+ };
3332
+ };
2438
3333
  // pkgs/@akanjs/devkit/workflow/render.ts
2439
3334
  var listOr = (items, render, empty = "- none") => items?.length ? items.map(render) : [empty];
2440
3335
  var renderDiagnostic = (diagnostic) => `- [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`;
@@ -2448,7 +3343,11 @@ var renderRecommendation = (recommendation) => {
2448
3343
  var renderWorkflowList = (specs) => [
2449
3344
  "# Akan Workflows",
2450
3345
  "",
2451
- ...specs.flatMap((spec) => [`- \`${spec.name}\`: ${spec.description}`, ` - When: ${spec.whenToUse}`]),
3346
+ ...specs.flatMap((spec) => [
3347
+ `- \`${spec.name}\`: ${spec.description}`,
3348
+ ` - When: ${spec.whenToUse}`,
3349
+ ...spec.replacesRules?.length ? [` - Fixes: ${spec.replacesRules.map((rule) => `\`${rule}\``).join(", ")}`] : []
3350
+ ]),
2452
3351
  ""
2453
3352
  ].join(`
2454
3353
  `);
@@ -2460,8 +3359,14 @@ var renderWorkflowExplain = (spec) => [
2460
3359
  "## When To Use",
2461
3360
  spec.whenToUse,
2462
3361
  "",
3362
+ ...spec.replacesRules?.length ? [
3363
+ "## Replaces Rules",
3364
+ "This path is the fix when lint or the gate reports:",
3365
+ ...spec.replacesRules.map((rule) => `- \`${rule}\``),
3366
+ ""
3367
+ ] : [],
2463
3368
  "## Inputs",
2464
- ...Object.entries(spec.inputs).map(([name, input]) => `- \`${name}\`${input.required ? " (required)" : ""}: ${input.description}${input.allowedValues ? ` Allowed: ${input.allowedValues.join(", ")}.` : ""}`),
3369
+ ...Object.entries(spec.inputs).map(([name, input]) => `- \`${name}\`${camelToKebabCase(name) === name ? "" : ` (\`--${camelToKebabCase(name)}\`)`}${input.required ? " (required)" : ""}: ${input.description}${input.allowedValues ? ` Allowed: ${input.allowedValues.join(", ")}.` : ""}`),
2465
3370
  "",
2466
3371
  "## Optional Surfaces",
2467
3372
  ...Object.entries(spec.optionalSurfaces ?? {}).map(([name, mode]) => `- \`${name}\`: ${mode}`),
@@ -2752,4 +3657,4 @@ for (const candidate of toolingRolloutCandidates) {
2752
3657
  if (isRestrictedCandidate(candidate))
2753
3658
  restrictedCandidates.set(candidate.packageName, candidate);
2754
3659
  }
2755
- export { jsonText, workflowStatus, compactDiagnostics, workflowPlanApproval, createWorkflowApplyReport, workflowCommandsForPlan, workflowPathsForPlan, workflowRunArtifactPath, writeWorkflowRunArtifact, workflowSyncDir, generatedFilePathsForTarget, writeGeneratedSyncState, readWorkflowRunArtifact, createWorkflowBaselineSummary, createWorkflowValidationRunReport, createDryRunWorkflowApplyReport, createRepairReport, sourceFile, moduleComponentName, moduleSourcePaths, generatedFilesForSync, validationCommandsForTarget, nextActionsForTarget, createPrimitiveWriteReport, createPassedPrimitiveReport, scalarChangedFiles, bilingualLabelForField, bilingualDescriptionForField, normalizeFieldType, ensureNamedImport, ensureBaseImport, ensureBaseTypeImport, coerceFieldDefault, fieldExpression, viaBuilderParameterName, insertIntoObject, insertLightProjectionField, insertTemplateField, ensureEnumImport, insertEnumClass, insertDictionaryModelField, hasConstantInputField, hasDictionaryModelField, ensureConstantTypeImport, insertDictionaryEnum, parseValues, hasSourceParseErrors, hasClassMethod, insertClassMethod, hasSignalFactoryEntry, insertSignalFactoryEntry, buildAkanModuleContextIndex, addFieldUiPolicyForType, createWorkflowStepRegistry, WorkflowExecutor, listWorkflowSpecs, getWorkflowSpec, compactWorkflowInputs, createWorkflowPlan, renderWorkflowList, renderWorkflowExplain, renderWorkflowPlan, renderWorkflowApply, renderWorkflowValidation, renderRepairReport, renderWorkflowRunArtifact, renderPrimitiveReport, toolingRolloutGate };
3660
+ export { InteractionScaffold, jsonText, workflowStatus, compactDiagnostics, workflowPlanApproval, createWorkflowApplyReport, workflowCommandsForPlan, workflowPathsForPlan, workflowRunArtifactPath, writeWorkflowRunArtifact, workflowSyncDir, generatedFilePathsForTarget, writeGeneratedSyncState, readWorkflowRunArtifact, createWorkflowBaselineSummary, createWorkflowValidationRunReport, createDryRunWorkflowApplyReport, createRepairReport, sourceFile, moduleComponentName, moduleSourcePaths, generatedFilesForSync, validationCommandsForTarget, nextActionsForTarget, createPrimitiveWriteReport, createPassedPrimitiveReport, scalarChangedFiles, bilingualLabelForField, bilingualDescriptionForField, normalizeFieldType, ensureNamedImport, ensureBaseImport, ensureBaseTypeImport, coerceFieldDefault, fieldExpression, viaBuilderParameterName, insertIntoObject, insertLightProjectionField, insertTemplateField, ensureEnumImport, insertEnumClass, insertDictionaryModelField, hasConstantInputField, hasDictionaryModelField, ensureConstantTypeImport, insertDictionaryEnum, parseValues, hasSourceParseErrors, hasClassMethod, insertClassMethod, hasSignalFactoryEntry, insertSignalFactoryEntry, buildAkanModuleContextIndex, addFieldUiPolicyForType, createWorkflowStepRegistry, WorkflowExecutor, MutationScaffold, listWorkflowSpecs, getWorkflowSpec, compactWorkflowInputs, createWorkflowPlan, inspectWorkflowPlan, renderWorkflowList, renderWorkflowExplain, renderWorkflowPlan, renderWorkflowApply, renderWorkflowValidation, renderRepairReport, renderWorkflowRunArtifact, renderPrimitiveReport, toolingRolloutGate };