@akanjs/cli 3.1.2-rc.3 → 3.2.0-rc.0

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 (130) hide show
  1. package/.build-stamp +1 -1
  2. package/{CodeAgent-n2tkg59z.js → CodeAgent-h6g8dg3a.js} +2 -2
  3. package/{CodeTui-9wsdx7ap.js → CodeTui-n9gacepn.js} +1 -1
  4. package/README.ko.md +9 -0
  5. package/README.md +9 -0
  6. package/TunnelShare-k3ja4w9x.js +14 -0
  7. package/{agent.command-tffz6wdn.js → agent.command-2f657613.js} +19 -17
  8. package/akanCode.js +2 -2
  9. package/{application.command-7bkxbrsp.js → application.command-yb8v177e.js} +45 -22
  10. package/{applicationBuildRunner-s13x3zqb.js → applicationBuildRunner-sctcmkyx.js} +57 -17
  11. package/buildBatch.proc.js +7 -7
  12. package/{cloud.command-a792bc10.js → cloud.command-et06ja22.js} +35 -18
  13. package/cloud.script-s6rbrwer.js +30 -0
  14. package/{code.command-ma8dtzww.js → code.command-7m67c7zc.js} +6 -6
  15. package/commandManifest.json +1 -1
  16. package/{context.command-80a1qhps.js → context.command-569z0rqf.js} +20 -19
  17. package/context.runner-ms8v1rxy.js +29 -0
  18. package/{guideline.command-195g0h9a.js → guideline.command-gnv3e8p8.js} +2 -2
  19. package/guidelines/akanApi/akanApi.instruction.md +317 -0
  20. package/guidelines/conventions/rules/app.md +5 -5
  21. package/guidelines/conventions/rules/config.md +1 -1
  22. package/guidelines/conventions/rules/gates.md +10 -5
  23. package/guidelines/conventions/rules/page.md +4 -2
  24. package/guidelines/conventions/rules/server.md +2 -0
  25. package/guidelines/conventions/rules/style.md +3 -1
  26. package/guidelines/conventions/rules/ts.md +2 -1
  27. package/guidelines/cssRule/cssRule.instruction.md +3 -1
  28. package/guidelines/pageRule/pageRule.instruction.md +3 -0
  29. package/incrementalBuilder.proc.js +70 -14
  30. package/{index-tns543wd.js → index-0fb3cpbt.js} +3 -3
  31. package/{index-zbrwnmf1.js → index-1q1cjn8s.js} +21 -11
  32. package/{index-wrmq92vk.js → index-3wjbhj2n.js} +1 -1
  33. package/{index-361ex3rb.js → index-48d5qsj3.js} +4 -4
  34. package/{index-aayg4dqf.js → index-5w9my9qe.js} +8 -8
  35. package/{index-1h2jc0x3.js → index-6wpaq392.js} +61 -15
  36. package/{index-tp56652m.js → index-7xdpww43.js} +69 -12
  37. package/index-7y5yghjg.js +2969 -0
  38. package/{index-zttm13c3.js → index-8g7tdsk4.js} +249 -696
  39. package/{index-m02tdq8a.js → index-8pb9yvp8.js} +63 -21
  40. package/{index-gbp1q1b5.js → index-8ts9774g.js} +4 -4
  41. package/{index-9zy8479y.js → index-93ewzmp6.js} +43 -14
  42. package/{index-zdpte1pj.js → index-9tbgb4d8.js} +1 -1
  43. package/index-abgh0jve.js +126 -0
  44. package/{index-khk05tsf.js → index-aj3ehkcx.js} +1 -1
  45. package/{index-84h43kg6.js → index-d4n1wmrz.js} +37 -4
  46. package/{index-gr9thy79.js → index-drz9e84d.js} +22 -8
  47. package/{index-hapx5myy.js → index-e3vmjtph.js} +2 -2
  48. package/{index-k64mhwbw.js → index-eajbmk10.js} +2 -1
  49. package/{index-0j1t1h2b.js → index-ed6ea0qp.js} +1 -1
  50. package/{index-sjabnf7j.js → index-fjr4d6yd.js} +444 -368
  51. package/index-hqrkqxx2.js +176 -0
  52. package/{index-z7kbxdqg.js → index-jdamtr7e.js} +3 -3
  53. package/{index-scck6h6d.js → index-kpdv34rq.js} +4 -4
  54. package/{index-ppvqy5bc.js → index-ktb3wcqz.js} +73 -34
  55. package/{index-sveq36gh.js → index-mmym5xmb.js} +4 -2
  56. package/{index-y4kcmbt2.js → index-mqntfzv5.js} +2 -2
  57. package/{index-4am4dvmf.js → index-ny2k80mv.js} +15 -3
  58. package/index-p6hjwt2d.js +1668 -0
  59. package/{index-wwe9rsrx.js → index-r0a604h4.js} +12 -2
  60. package/{index-jb2sreps.js → index-rc5fvqj2.js} +18 -18
  61. package/{index-db2nqrad.js → index-ryrm5z2c.js} +71 -19
  62. package/{index-eft5c2mp.js → index-s2grpzef.js} +331 -27
  63. package/{index-g500c5j9.js → index-sr5da35e.js} +33 -10
  64. package/{index-defp4gmb.js → index-sy481q2x.js} +1 -1
  65. package/{index-j9d3mjx1.js → index-thckcabc.js} +2 -2
  66. package/{index-9z3egsmg.js → index-vkzfk7qt.js} +25 -23
  67. package/index-w639tvkd.js +166 -0
  68. package/index-ygdbn9jn.js +122 -0
  69. package/{index-sp0qsr7a.js → index-zpv14wpy.js} +3 -3
  70. package/{index-sx91nf4z.js → index-zxsygkda.js} +18 -9
  71. package/index.js +24 -23
  72. package/{library.command-63hgt9te.js → library.command-1gp5qe3r.js} +3 -3
  73. package/{localRegistry.command-343ksmn9.js → localRegistry.command-v3g21rex.js} +25 -16
  74. package/{module.command-2hce9m6k.js → module.command-4xz9he6h.js} +6 -6
  75. package/{package.command-96eheyvd.js → package.command-s7qpnn1g.js} +12 -3
  76. package/package.json +2 -2
  77. package/{page.command-gs6d841d.js → page.command-fan34c49.js} +3 -3
  78. package/{pipeline.command-wdfvdbfj.js → pipeline.command-ph4fnn9w.js} +2 -2
  79. package/{primitive.command-7tdj12wn.js → primitive.command-3fqh8emf.js} +7 -7
  80. package/{projectTypecheck-kqj1t6hb.js → projectTypecheck-vkb40hjc.js} +1 -1
  81. package/{quality.command-29bgarh1.js → quality.command-ecj6exsh.js} +15 -10
  82. package/{repair.command-yng4rf5d.js → repair.command-fe9jw719.js} +6 -6
  83. package/{scalar.command-1nk4329t.js → scalar.command-cnvfhk0n.js} +5 -5
  84. package/skills/akan-debug/SKILL.md +2 -1
  85. package/skills/akan-page/SKILL.md +30 -2
  86. package/skills/akan-service/SKILL.md +77 -1
  87. package/{subspace.command-5cehmcdd.js → subspace.command-yxtt3v3e.js} +8 -8
  88. package/templates/app/lib/___appName__/__appName__.abstract.md.template +6 -0
  89. package/templates/app/page/_index.tsx +4 -284
  90. package/templates/app/page/_layout.tsx +1 -26
  91. package/templates/app/page/styles.css.template +58 -318
  92. package/templates/appSample/page/_index.tsx +281 -0
  93. package/templates/appSample/page/_layout.tsx +55 -0
  94. package/templates/appSample/page/styles.css.template +327 -0
  95. package/templates/libRoot/lib/___libName__/__libName__.abstract.md.template +6 -0
  96. package/templates/workspaceRoot/package.json.template +1 -12
  97. package/{tunnel.command-yrd4atqy.js → tunnel.command-ggj38mqf.js} +7 -7
  98. package/{typeChecker-j2jdnqsr.js → typeChecker-s640r6c0.js} +1 -1
  99. package/typecheck.proc.js +1 -1
  100. package/{verify.command-kbq0fcg8.js → verify.command-w9ttxkdz.js} +16 -14
  101. package/{workflow.command-274qfa8z.js → workflow.command-ss8devj0.js} +12 -12
  102. package/{workspace.command-r6hgmawy.js → workspace.command-rw1p0xeq.js} +50 -38
  103. package/TunnelShare-6d7z36sr.js +0 -14
  104. package/cloud.script-t2n13gv6.js +0 -27
  105. package/context.runner-wxqb3qcy.js +0 -28
  106. package/index-j2dgmzbj.js +0 -1259
  107. package/index-p6x5b7hr.js +0 -839
  108. package/index-vzpnr12w.js +0 -65
  109. package/templates/workspaceRoot/patches/zod@3.25.76.patch.template +0 -22
  110. package/templates/workspaceRoot/patches/zod@4.4.3.patch.template +0 -11
  111. /package/templates/{app → appSample}/page/_overrides.tsx +0 -0
  112. /package/templates/{app → appSample}/public/fonts/Pretendard-Black.woff2 +0 -0
  113. /package/templates/{app → appSample}/public/fonts/Pretendard-Bold.woff2 +0 -0
  114. /package/templates/{app → appSample}/public/fonts/Pretendard-ExtraBold.woff2 +0 -0
  115. /package/templates/{app → appSample}/public/fonts/Pretendard-ExtraLight.woff2 +0 -0
  116. /package/templates/{app → appSample}/public/fonts/Pretendard-Light.woff2 +0 -0
  117. /package/templates/{app → appSample}/public/fonts/Pretendard-Medium.woff2 +0 -0
  118. /package/templates/{app → appSample}/public/fonts/Pretendard-Regular.woff2 +0 -0
  119. /package/templates/{app → appSample}/public/fonts/Pretendard-SemiBold.woff2 +0 -0
  120. /package/templates/{app → appSample}/public/fonts/Pretendard-Thin.woff2 +0 -0
  121. /package/templates/{app → appSample}/public/jelly/cloud.webp +0 -0
  122. /package/templates/{app → appSample}/public/jelly/comet.webp +0 -0
  123. /package/templates/{app → appSample}/public/jelly/moon.webp +0 -0
  124. /package/templates/{app → appSample}/public/jelly/planet.webp +0 -0
  125. /package/templates/{app → appSample}/public/jelly/rocket.webp +0 -0
  126. /package/templates/{app → appSample}/public/jelly/star.webp +0 -0
  127. /package/templates/{app → appSample}/public/jelly/sugar.webp +0 -0
  128. /package/templates/{app → appSample}/public/logo.png +0 -0
  129. /package/templates/{app → appSample}/ui/Recipe/index.ts +0 -0
  130. /package/templates/{app → appSample}/ui/Recipe/jellyButton.ts +0 -0
@@ -3,13 +3,16 @@ import {
3
3
  Pkg,
4
4
  Workspace,
5
5
  command
6
- } from "./index-9zy8479y.js";
6
+ } from "./index-93ewzmp6.js";
7
7
  import"./index-bns3wcpc.js";
8
- import"./index-g500c5j9.js";
8
+ import"./index-sr5da35e.js";
9
9
  import"./index-qd7xn2bk.js";
10
+ import"./index-7y5yghjg.js";
11
+ import"./index-abgh0jve.js";
12
+ import"./index-hqrkqxx2.js";
10
13
  import {
11
14
  PackageScript
12
- } from "./index-84h43kg6.js";
15
+ } from "./index-d4n1wmrz.js";
13
16
 
14
17
  // pkgs/@akanjs/cli/package/package.command.ts
15
18
  class PackageCommand extends command("package", [PackageScript], ({ public: target }) => ({
@@ -33,6 +36,12 @@ class PackageCommand extends command("package", [PackageScript], ({ public: targ
33
36
  }),
34
37
  verifyAkanPublishPackages: target({ devOnly: true, desc: "Verify all Akan publish dist packages" }).with(Workspace).exec(async function(workspace) {
35
38
  await this.packageScript.verifyAkanPublishPackages(workspace);
39
+ }),
40
+ syncArchitecture: target({
41
+ devOnly: true,
42
+ desc: "Regenerate the generated part of pkgs/akanjs/ARCHITECTURE.md from the framework source"
43
+ }).with(Workspace).exec(async function(workspace) {
44
+ await this.packageScript.syncArchitecture(workspace);
36
45
  })
37
46
  })) {
38
47
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@akanjs/cli",
3
- "version": "3.1.2-rc.3",
3
+ "version": "3.2.0-rc.0",
4
4
  "sourceType": "module",
5
5
  "type": "module",
6
6
  "publishConfig": {
@@ -39,7 +39,7 @@
39
39
  "@earendil-works/pi-tui": "1.3.0",
40
40
  "@inquirer/prompts": "^8.7.3",
41
41
  "@tailwindcss/node": "^4.3.3",
42
- "akanjs": "3.1.2-rc.3",
42
+ "akanjs": "3.2.0-rc.0",
43
43
  "chalk": "^6.0.1",
44
44
  "commander": "^15.0.0",
45
45
  "dayjs": "^1.11.23",
@@ -3,12 +3,12 @@ import {
3
3
  App,
4
4
  Module,
5
5
  command
6
- } from "./index-9zy8479y.js";
6
+ } from "./index-93ewzmp6.js";
7
7
  import"./index-bns3wcpc.js";
8
- import"./index-g500c5j9.js";
8
+ import"./index-sr5da35e.js";
9
9
  import {
10
10
  PageScript
11
- } from "./index-khk05tsf.js";
11
+ } from "./index-aj3ehkcx.js";
12
12
 
13
13
  // pkgs/@akanjs/cli/page/page.command.ts
14
14
  class PageCommand extends command("page", [PageScript], ({ public: target }) => ({
@@ -4,7 +4,7 @@ import {
4
4
  runner,
5
5
  script,
6
6
  command
7
- } from "./index-9zy8479y.js";
7
+ } from "./index-93ewzmp6.js";
8
8
  import {
9
9
  FileSys2
10
10
  } from "./index-bns3wcpc.js";
@@ -12,7 +12,7 @@ import {
12
12
  AkanAppConfig,
13
13
  AkanWorkspaceConfig,
14
14
  AppExecutor
15
- } from "./index-g500c5j9.js";
15
+ } from "./index-sr5da35e.js";
16
16
  import {
17
17
  resolveMobileTargets
18
18
  } from "./index-m9jj544v.js";
@@ -2,18 +2,18 @@
2
2
  import {
3
3
  Workspace,
4
4
  command
5
- } from "./index-9zy8479y.js";
5
+ } from "./index-93ewzmp6.js";
6
6
  import"./index-bns3wcpc.js";
7
- import"./index-g500c5j9.js";
7
+ import"./index-sr5da35e.js";
8
8
  import {
9
9
  renderPrimitiveReport
10
- } from "./index-m02tdq8a.js";
11
- import"./index-j2dgmzbj.js";
12
- import"./index-khk05tsf.js";
13
- import"./index-gbp1q1b5.js";
10
+ } from "./index-8pb9yvp8.js";
11
+ import"./index-7y5yghjg.js";
12
+ import"./index-aj3ehkcx.js";
13
+ import"./index-8ts9774g.js";
14
14
  import {
15
15
  PrimitiveScript
16
- } from "./index-361ex3rb.js";
16
+ } from "./index-48d5qsj3.js";
17
17
 
18
18
  // pkgs/@akanjs/cli/primitive/primitive.command.ts
19
19
  import { Logger } from "akanjs/common";
@@ -1,7 +1,7 @@
1
1
  // @bun
2
2
  import {
3
3
  ProjectTypecheck2
4
- } from "./index-g500c5j9.js";
4
+ } from "./index-sr5da35e.js";
5
5
  export {
6
6
  ProjectTypecheck2 as ProjectTypecheck
7
7
  };
@@ -3,24 +3,28 @@ import {
3
3
  Workspace,
4
4
  script,
5
5
  command
6
- } from "./index-9zy8479y.js";
6
+ } from "./index-93ewzmp6.js";
7
7
  import"./index-bns3wcpc.js";
8
8
  import {
9
9
  AppExecutor,
10
- LibExecutor
11
- } from "./index-g500c5j9.js";
10
+ LibExecutor,
11
+ PkgExecutor
12
+ } from "./index-sr5da35e.js";
13
+ import {
14
+ MaintainabilityBaseline
15
+ } from "./index-hqrkqxx2.js";
12
16
  import {
13
- MaintainabilityBaseline,
14
17
  WorkspaceRunner,
15
18
  AkanQualityScanner,
16
19
  formatQualityScanResult,
17
20
  formatSsrScanResult
18
- } from "./index-sjabnf7j.js";
19
- import"./index-j2dgmzbj.js";
21
+ } from "./index-fjr4d6yd.js";
22
+ import"./index-7y5yghjg.js";
20
23
  import"./index-62md4dwy.js";
24
+ import"./index-ygdbn9jn.js";
21
25
  import"./index-hj6w4ka1.js";
22
- import"./index-4am4dvmf.js";
23
- import"./index-k64mhwbw.js";
26
+ import"./index-ny2k80mv.js";
27
+ import"./index-eajbmk10.js";
24
28
 
25
29
  // pkgs/@akanjs/cli/quality/quality.script.ts
26
30
  import { Logger } from "akanjs/common";
@@ -39,10 +43,11 @@ class QualityScript extends script("quality", [WorkspaceRunner]) {
39
43
  Logger.rawLog(format === "json" ? JSON.stringify(result, null, 2) : formatSsrScanResult(result));
40
44
  }
41
45
  async baseline(workspace, { force = false } = {}) {
42
- const [appNames, libNames] = await workspace.getExecs();
46
+ const [appNames, libNames, pkgNames] = await workspace.getExecs();
43
47
  const execs = [
44
48
  ...appNames.map((appName) => AppExecutor.from(workspace, appName)),
45
- ...libNames.map((libName) => LibExecutor.from(workspace, libName))
49
+ ...libNames.map((libName) => LibExecutor.from(workspace, libName)),
50
+ ...pkgNames.map((pkgName) => PkgExecutor.from(workspace, pkgName))
46
51
  ];
47
52
  const { fileName } = MaintainabilityBaseline;
48
53
  for (const exec of execs) {
@@ -3,16 +3,16 @@ import {
3
3
  Workspace,
4
4
  script,
5
5
  command
6
- } from "./index-9zy8479y.js";
6
+ } from "./index-93ewzmp6.js";
7
7
  import"./index-bns3wcpc.js";
8
- import"./index-g500c5j9.js";
8
+ import"./index-sr5da35e.js";
9
9
  import"./index-hj6w4ka1.js";
10
- import"./index-m02tdq8a.js";
11
- import"./index-j2dgmzbj.js";
12
- import"./index-j9d3mjx1.js";
10
+ import"./index-8pb9yvp8.js";
11
+ import"./index-7y5yghjg.js";
12
+ import"./index-thckcabc.js";
13
13
  import {
14
14
  RepairRunner
15
- } from "./index-tns543wd.js";
15
+ } from "./index-0fb3cpbt.js";
16
16
 
17
17
  // pkgs/@akanjs/cli/repair/repair.script.ts
18
18
  import { Logger } from "akanjs/common";
@@ -2,16 +2,16 @@
2
2
  import {
3
3
  Sys,
4
4
  command
5
- } from "./index-9zy8479y.js";
5
+ } from "./index-93ewzmp6.js";
6
6
  import"./index-bns3wcpc.js";
7
- import"./index-g500c5j9.js";
7
+ import"./index-sr5da35e.js";
8
8
  import {
9
9
  renderPrimitiveReport
10
- } from "./index-m02tdq8a.js";
11
- import"./index-j2dgmzbj.js";
10
+ } from "./index-8pb9yvp8.js";
11
+ import"./index-7y5yghjg.js";
12
12
  import {
13
13
  ScalarScript
14
- } from "./index-hapx5myy.js";
14
+ } from "./index-e3vmjtph.js";
15
15
 
16
16
  // pkgs/@akanjs/cli/scalar/scalar.command.ts
17
17
  import { Logger, lowerlize } from "akanjs/common";
@@ -15,7 +15,8 @@ the server errors logged meanwhile, console errors and warnings, and layout smel
15
15
  stops it after; `--keep` leaves it up for the next preview. It never starts a second server beside a
16
16
  running one.
17
17
  - Paths are comma-separated (`akan preview <app> /board,/board/new`) and get the default locale when they lack
18
- one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off.
18
+ one, unless the app sets `localePrefix: "as-needed"` and `--csr` is off. A `/_akan` route such as Studio
19
+ (`/_akan/studio?view=runtime`), a signal route or a file opens as written.
19
20
  `--changed` adds the pages your uncommitted page and layout edits reach. A dynamic route needs a concrete
20
21
  path (`/memo/1`); `akan context --app <app>` lists every route with its params and search names.
21
22
  - The viewport is a 390x844 phone; `--desktop` is 1280x800. `--csr` loads each page in the CSR boot the native
@@ -8,6 +8,11 @@ description: "Add or change a route under page/: the one page()/layout() chain,
8
8
  A route file exports one chain and nothing else. Every setting is a stage of it.
9
9
 
10
10
  ```tsx
11
+ import { fetch, Task, usePage } from "@apps/<app>/client";
12
+ import { signedIn } from "@libs/shared/webkit";
13
+ import { ID } from "akanjs/base";
14
+ import { page } from "akanjs/client";
15
+
11
16
  export default page()
12
17
  .param("orgId", ID)
13
18
  .guard(() => signedIn())
@@ -26,7 +31,8 @@ export default page()
26
31
  2. Name every `[x]` segment with `.param("x", Type)` and read a query key only with `.search("k", Type)`. Values
27
32
  arrive typed; `lang` reaches every stage and is never declared.
28
33
  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.
34
+ a stricter guard on a page that needs more. The endpoint guards are still the real gate. `signedIn` comes from
35
+ `@libs/shared/webkit`, and a new workspace has that lib only with `create-workspace --libs true`.
30
36
  4. In `.render()`: `usePage()`, then fetch, then return. Hand `fetch.init*` / `view*` / `edit*` fields to sections
31
37
  unawaited; await only what the shell reads, in one `Promise.all`.
32
38
  5. `.head()` takes JSX (or a function returning it), never a metadata object. A canonical link comes only from the
@@ -34,6 +40,27 @@ export default page()
34
40
  6. Re-skin an `akanjs/ui` component for a subtree with `_overrides.tsx`:
35
41
  `export default override({ Slot: AppComponent })`, no logic.
36
42
 
43
+ ## API at a glance
44
+
45
+ `page`, `layout` and `router` come from `akanjs/client`, `Link` from `akanjs/ui`, `usePageLocation` from
46
+ `akanjs/webkit`, and `fetch`, `usePage` and the model namespaces from `@apps/<app>/client`. A stage receives the
47
+ declared params and search keys plus `lang`.
48
+
49
+ - Data-driven title: `.head(async ({ id }) => <title>{((await fetch.book(id)) as Book | null)?.title}</title>)`,
50
+ where `Book` is the `common/` interface for the query's `Any` return (`akan-service`).
51
+ - Async page: `.render(async ({ id }) => { const book = (await fetch.book(id)) as Book | null; if (!book) return router.notFound(); … })`;
52
+ the same query in `.head()` and `.render()` is one request.
53
+ - `router.notFound()` from `.guard()`, `.head()` or `.render()` answers 404 with the nearest layout's `.notFound()`
54
+ above it (an unmatched URL: the deepest layout covering it), else the built-in 404.
55
+ - A layout's own 404 and error views: `.notFound(({ pathname }) => …)` and `.error(({ error }) => …)` on `layout()`
56
+ or `rootLayout()`.
57
+ - `<Link href="/books/OL45804W">`: write the path without the locale; Link adds it, or leaves it off for the default
58
+ locale under `i18n.localePrefix: "as-needed"`. `activeClassName` marks the current one.
59
+ - From a handler: `router.push(href)` / `router.replace(href)`; in a server stage, `router.redirect(href)`.
60
+ - A client filter kept in the URL without reloading the page: ``router.replace(`/books?q=${q}`, { shallow: true,
61
+ scrollToTop: false })`` in a `"use client"` component, read back with `usePageLocation().searchParams`. Shallow
62
+ holds only while the path stays the same; a server `.search()` sees the value at the next full navigation.
63
+
37
64
  ## Never
38
65
 
39
66
  - A `fetch.<mutation>()` while rendering — it throws `base.error.mutationInRender`, because opening a link would
@@ -41,4 +68,5 @@ export default page()
41
68
  - `useState`, `useEffect`, comments, a named export beside the chain, or the legacy `export default async function`.
42
69
  - Editing a lib page through its link in `page/(libs)/` — edit the lib's own `page/` source.
43
70
 
44
- Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server.
71
+ Full detail: `get_guideline` with `pageRule`, or `ssrRule` for what may render on the server; every stage's
72
+ signature, the router's methods, Link's props and every import path: `akanApi`.
@@ -20,6 +20,10 @@ dictionary is a `serviceDictionary`.
20
20
  explicitly `void`-ed.
21
21
  - Return `null` / `false` for "not allowed" or "not found" and let the signal decide whether that is an
22
22
  error.
23
+ - `serve(name, { serverMode: "batch" }, …)` mounts the module, endpoints included, only in a `batch` or `all`
24
+ process; a `federation` replica, the one serving requests in a split deployment, skips it. The app's own
25
+ `lib/_<app>/` service is scaffolded with it for cron and queue work. Leave it off a service a page calls, as
26
+ `akan create-service` does.
23
27
 
24
28
  ## Reaching other things
25
29
 
@@ -31,4 +35,76 @@ registered under `<refName>`, and the `Service` suffix is required.
31
35
  An external API or piece of infrastructure is an `adapt()` class in `srvkit/`, injected with `plug`. It
32
36
  self-registers, so do **not** add it to `lib/option.ts`.
33
37
 
34
- Full detail: `get_guideline` with `modelService`.
38
+ ## Recipe: pages backed by an external HTTP API
39
+
40
+ `akan create-service openlibrary <app>` scaffolds `lib/_openlibrary/`; the adapter beside it is yours.
41
+
42
+ ```ts
43
+ // srvkit/bookApi.ts — read at boot, so the built server takes API_BASE_URL from the host that runs it
44
+ import { adapt } from "akanjs/service";
45
+
46
+ export class BookApi extends adapt("bookApi" as const, ({ env }) => ({
47
+ baseUrl: env(() => process.env.API_BASE_URL ?? "http://localhost:9000"),
48
+ })) {
49
+ async get<T>(path: string): Promise<T | null> {
50
+ try {
51
+ const res = await fetch(`${this.baseUrl}/${path}`, { signal: AbortSignal.timeout(20_000) });
52
+ if (res.ok) return (await res.json()) as T;
53
+ if (res.status !== 404) this.logger.warn(`${path} answered ${res.status}`);
54
+ } catch (error) {
55
+ this.logger.warn(`${path} failed: ${String(error)}`);
56
+ }
57
+ return null;
58
+ }
59
+ }
60
+
61
+ // lib/_openlibrary/openlibrary.service.ts — shape the upstream JSON here, not in the page
62
+ import { BookApi } from "@apps/<app>/srvkit";
63
+ import { serve } from "akanjs/service";
64
+
65
+ interface ApiWork {
66
+ key: string;
67
+ title: string;
68
+ }
69
+
70
+ export class OpenlibraryService extends serve("openlibrary" as const, ({ plug }) => ({ bookApi: plug(BookApi) })) {
71
+ async getBook(id: string) {
72
+ const work = await this.bookApi.get<ApiWork>(`works/${id}.json`);
73
+ return work && { id, title: work.title };
74
+ }
75
+ }
76
+
77
+ // lib/_openlibrary/openlibrary.signal.ts — Any answers plain JSON; nullable lets it answer null for "not found"
78
+ import { Any } from "akanjs/base";
79
+ import { endpoint, internal, Public } from "akanjs/signal";
80
+
81
+ import * as srv from "../srv";
82
+
83
+ export class OpenlibraryInternal extends internal(srv.openlibrary, () => ({})) {}
84
+
85
+ export class OpenlibraryEndpoint extends endpoint(srv.openlibrary, ({ query }) => ({
86
+ book: query(Any, { guards: [Public], nullable: true })
87
+ .param("id", String)
88
+ .exec(async function (id) {
89
+ return await this.openlibraryService.getBook(id);
90
+ }),
91
+ })) {}
92
+
93
+ // lib/_openlibrary/openlibrary.dictionary.ts — typecheck asks a label for every endpoint
94
+ import { serviceDictionary } from "akanjs/dictionary";
95
+
96
+ import type { OpenlibraryEndpoint } from "../sig";
97
+
98
+ export const dictionary = serviceDictionary(["en", "ko"])
99
+ .endpoint<OpenlibraryEndpoint>((fn) => ({ book: fn(["Book", "책"]) }))
100
+ .error({})
101
+ .translate({});
102
+ ```
103
+
104
+ The page calls it as `await fetch.book(id)` (`fetch` from `@apps/<app>/client`) and ends with
105
+ `return router.notFound()` on `null`. An `Any` return reaches the page as `unknown`: type it with an interface in
106
+ `common/`, or return a scalar (`akan create-scalar`) for a typed wire shape. A query that answers `null` without
107
+ `nullable: true` fails the render, naming the endpoint.
108
+
109
+ Full detail: `get_guideline` with `modelService`; every import path and the exact signatures of serve, adapt,
110
+ endpoint and serviceDictionary: `akanApi`.
@@ -5,7 +5,7 @@ import {
5
5
  runner,
6
6
  script,
7
7
  command
8
- } from "./index-9zy8479y.js";
8
+ } from "./index-93ewzmp6.js";
9
9
  import {
10
10
  FileSys2
11
11
  } from "./index-bns3wcpc.js";
@@ -14,20 +14,20 @@ import {
14
14
  Executor,
15
15
  WorkspaceExecutor,
16
16
  AppExecutor
17
- } from "./index-g500c5j9.js";
17
+ } from "./index-sr5da35e.js";
18
18
  import {
19
19
  GlobalConfig
20
- } from "./index-gr9thy79.js";
20
+ } from "./index-drz9e84d.js";
21
21
  import"./index-m9jj544v.js";
22
- import"./index-sp0qsr7a.js";
23
- import"./index-zbrwnmf1.js";
24
- import"./index-sveq36gh.js";
22
+ import"./index-zpv14wpy.js";
23
+ import"./index-1q1cjn8s.js";
24
+ import"./index-mmym5xmb.js";
25
25
  import {
26
26
  SubspaceConfig
27
27
  } from "./index-h7hehkw6.js";
28
28
  import {
29
29
  SlicePlanner
30
- } from "./index-defp4gmb.js";
30
+ } from "./index-sy481q2x.js";
31
31
 
32
32
  // pkgs/@akanjs/devkit/subspace.ts
33
33
  import { mkdir as mkdir2 } from "fs/promises";
@@ -818,7 +818,7 @@ class SubspaceRunner extends runner("subspace") {
818
818
  if (!asked)
819
819
  return { name: subspace.name, workspaceId, host, apps, libs: [], outcome: "cancelled", files: [] };
820
820
  const { libs } = await subspace.slice();
821
- const { CloudScript } = await import("./cloud.script-t2n13gv6.js");
821
+ const { CloudScript } = await import("./cloud.script-s6rbrwer.js");
822
822
  const { files } = await CommandContainer.get(CloudScript).uploadEnv(workspace, {
823
823
  host,
824
824
  workspaceId,
@@ -0,0 +1,6 @@
1
+ # <%= appName %> Service Abstract
2
+ The app's own service module. It owns no endpoint, job or state yet.
3
+
4
+ ## Rules
5
+ - `serverMode: "batch"` mounts it only in a `batch` or `all` process, so it suits cron and queue work; an endpoint a
6
+ page calls belongs in a module from `akan create-service`.