@akanjs/cli 3.0.0-alpha.5 → 3.0.0-alpha.7

package/templates/workspaceRoot/.cursor/rules/scalar-modeling.mdc.template

@@ -56,3 +56,44 @@ alwaysApply: false
 - Declare an image/file field as a relation to `File`: `image: field(File).optional()` for one, `images: field([File])` for many (see `libs/shared/lib/user/user.constant.ts`, `libs/shared/lib/banner/banner.constant.ts`).
 - The store then auto-generates an `upload<Field>On<Model>(fileList)` action that calls the framework upload mutation and polls file status until it leaves `"uploading"` (`pkgs/akanjs/store/action.ts`).
 - Storage is wired through the `StorageAdaptor` DI role (default `BlobStorage`, `pkgs/akanjs/service/predefinedAdaptor/storage.adaptor.ts`); the reference implementation is the `file` lib (`libs/shared/lib/file/*`). Do not hand-roll data-URL fallbacks.
+
+### Cascade Remove — the `cascade` option
+
+**The value names the direction, and getting it wrong is a data loss.** The two actions can sit on the same field
+shape, so `cascade` never means "related" — it means one of exactly these:
+
+- `removeRef` — *when I am removed, remove what this field points at.* Declared on the relation the owner holds:
+  `image: field(File, { cascade: "removeRef" })`, arrays included. Only a relation accepts it; a primitive, a bare
+  `ID`, and a scalar each fail the class build, because none of them names a document to remove.
+- `removeWith` — *when what this field points at is removed, remove me.* Declared on the child's own reference to
+  its owner, so the owner never learns about its children and a lib model can be extended by an app's. Three forms:
+  a relation (`agentSession: field(AgentSession, { cascade: "removeWith" })`), an id with `ref`
+  (`field(ID, { ref: "agentSession", cascade: "removeWith" })`), or a polymorphic id with `refPath`
+  (`field(ID, { refPath: "parentType", cascade: "removeWith" })`). An array, a Map, `ref` together with `refPath`,
+  and a field naming no owner each fail the class build.
+- **A `refPath` must name an `enumOf` field.** A free-form owner type is unknowable at build time, so every model's
+  removal would have to sweep the polymorphic table on the chance it is the owner. The enum names the candidates and
+  the reverse index reaches only them.
+- **A cascade goes through the target's service, never its model** — unless it provably makes no difference. The
+  service path is what runs the target's `_postRemove`, which is where a module puts the side effect the removal has
+  to carry (`FileService._postRemove` deletes the stored blob there).
+- **Bulk is decided at boot, per target model, for both directions.** When the target has no `remove` schema hook, no
+  `_pre`/`_postRemove` (its own or a lib's), no cascade of its own, and no children, one `removeManyByQuery` leaves
+  exactly the rows the loop would, so the framework takes it. Adding a `_postRemove` to that model silently flips it
+  back to one document at a time — the boot log (`info` summary, `verbose` per edge) is the only place that shows.
+- **The plan is sealed after every service is live**, so a `listenPost("remove")` registered in `onInit` still counts
+  and a `removeRef` target the app never mounted fails the boot rather than the first removal. An unmounted
+  `removeWith` owner fails the boot too; an unmounted `refPath` candidate only warns, since that list spans optional
+  modules by design.
+- **Nothing checks whether another document still references the same target.** `File` in particular is deduped by
+  `origin`, so two parents can share one row; declaring `removeRef` says the field owns its target exclusively, and
+  that judgement is the declaring model's to make.
+- Removal is soft (`removedAt`) but the storage delete a `_postRemove` performs is not — a cascade is not
+  restorable, and reviving the owner does not revive what went with it.
+- A `removeWith` declaration **auto-creates its index** (`{ removedAt, fk }`, or `{ removedAt, typeKey, fk }` when
+  polymorphic). Every non-base field lives in the `_doc` JSON column, so the lookup would otherwise scan the table
+  on every owner removal.
+- **Query-level removes fire no hooks and therefore no cascade.** `removeManyByQuery` / `updateManyByQuery`, the generated `remove<Filter>` / `update<Filter>`, and the facade's `removeById` / `updateById` stamp
+  `removedAt` in one atomic UPDATE, so nothing downstream runs. Remove one document at a time when it cascades.
+- Cascades are **idempotent**: `removedAt IS NULL` is ANDed into every query-level write, so a retry after a partial
+  failure re-stamps nothing. Cycles are cut by a visited set carried down the whole chain, with a depth cap of 16.

package/templates/workspaceRoot/AGENTS.md.template

@@ -261,8 +261,10 @@ final fallback when no CLI command covers the change.
 | Use JS `#private` in `*.constant.ts`, `*.document.ts`, `*.service.ts`, or `*.store.ts` | `no-js-private-class-method.grit` bans `#private` in exactly those four file suffixes. The rule is scoped by file path, not class shape — `#private` stays the house style under `srvkit/`, including `adapt()` classes. | `private _methodName()` in those four files; `#methodName()` in `srvkit/` |
 | Use `console.log()` | Biome lint forbids `console.log`. Only `console.error`, `console.info`, `console.warn` are allowed. | Use one of the three allowed console methods, or `this.logger.*` / `new Logger("ClassName")` on the server |
 | Write a `//!` marker in `ui/`, `webkit/`, `common/`, `page/**/*.tsx`, `*.constant.ts`, `*.store.ts`, or a module component file | `no-bang-comment-in-client.grit` bans it. Bun classifies `//!` and `/*!` as legal comments and keeps them through minification, so the note ships to every visitor. | `// FIXME:` in browser-reachable code; `//!` stays legal in server, `srvkit/`, and CLI files |
-| `throw new Error("...")` | `no-throw-raw-error.grit` bans raw errors outside tests, `*.constant.ts`, and `common/`. Raw errors carry no dictionary key, so they cannot be localized or toasted. | `throw new Err("task.error.<key>")` plus an `[en, ko]` entry in the module dictionary's `.error({})` |
-| Hand-order Tailwind classes, or reorder them to "fix" a diff | `useSortedClasses` is an error and also sorts the string arguments to `clsx()` and `cva()`. Sorter output like `font-bold text-2xl` looks wrong but is correct. | Write classes in any order and let `akan lint` sort them |
+| `return` a value from a store action | `no-return-in-store-action.grit` bans it. Every method of a `store(...)` class dispatches through `st.do.<action>()`, which is typed `void` / `Promise<void>`, so the value never reaches the caller. | `this.set({ ... })` with the result; a bare `return;` guard, a `return` inside a nested callback, a getter, and a `static` helper all stay legal |
+| `throw new Error("...")` | `no-throw-raw-error.grit` bans raw errors outside tests, `*.constant.ts`, `common/`, and `apps/akan/env/`. Raw errors carry no dictionary key, so they cannot be localized or toasted. | `throw new Err("task.error.<key>")` plus an `[en, ko]` entry in the module dictionary's `.error({})` |
+| Hand-order Tailwind classes, or reorder them to "fix" a diff | `useSortedClasses` is an error and also sorts the string arguments to `cn()`. Sorter output like `font-bold text-2xl` looks wrong but is correct. | Write classes in any order and let `akan lint` sort them |
+| A colour outside the semantic vocabulary — `bg-red-500`, `bg-[#3b82f6]`, `btn-primary`, `text-base-content`, `style={{ color: "#fff" }}` | The theme closes the vocabulary, so these produce **no CSS at all** — the element renders unstyled, and without the lint rules there is no error and no warning either. Raw-palette, arbitrary-colour, daisyUI-legacy and inline-colour rules all catch this. | Semantic tokens: `bg-primary`, `text-foreground/70`, `border-border`. A genuinely fixed colour takes a `// biome-ignore lint/plugin: <reason>` |
 | `import` a third-party package inside a page, a barrel, or a module file | `no-import-external-library.grit` covers `page/**`, all barrels, and every `*.{constant,dictionary,document,service,signal,store}.ts` and `*.{Template,Unit,Util,View,Zone}.tsx`. | Re-export the symbol from a one-line shim in `base/`, `webkit/`, or `ui/` first, then import that |
 | Import server APIs (`fs`, `Bun`, `process.env`) in `ui/`, `webkit/`, or `common/` | Server-only imports in client code cause build failures. | Keep server dependencies in `lib/`, `srvkit/`, or `private/` only |
 | Skip running `akan sync` after deleting a file | Deleted files remain referenced in barrel exports, causing import errors everywhere. | Run `akan sync <name>` after every file add, remove, or rename |
@@ -421,11 +423,14 @@ is convention that keeps hand-written code reading like generated code.
   `.Template.tsx` files contain zero `useState`: forms are store-driven with `Field.*`, `value={taskForm.x}`, and
   `onChange={st.do.setXOnTask}` passed by reference.
 - Read with `st.use.*` and write with `st.do.*`. Client components do not call `fetch.*`.
-- Static class strings stay plain strings. Use `clsx` only for a conditional or to merge an incoming `className`,
-  and merge the caller last: `clsx("base", conditional, className)`. `clsx` comes from `akanjs/client`. No
-  `twMerge`, no `cn()`.
-- Use daisyUI semantic tokens with opacity modifiers (`text-base-content/60`, `bg-base-100/70`). Never `dark:` —
-  theming is the daisyUI theme block in `page/*/styles.css`.
+- Reach for a recipe before writing a look by hand: `buttonRecipe`, `badgeRecipe` and `inputRecipe` from
+  `akanjs/ui` carry the button, badge and field surfaces. Call them as `buttonRecipe(variants?, className?)` —
+  the second argument merges internally and takes an array, so never wrap it in `cn()`.
+- Static class strings stay plain strings. Reach for `cn` only for a conditional or to merge an incoming
+  `className`, and merge the caller last: `cn("base", conditional, className)`. `cn` comes from `akanjs/client`
+  and is the only class-combining function — no `clsx`, no raw `twMerge`.
+- Use semantic tokens with opacity modifiers (`text-foreground/60`, `bg-background/70`, `border-border`). Never
+  `dark:` — theming is the token block in `page/*/styles.css`, where each token has a `-foreground` pair.
 - Hoist enum→class lookups to a module-scope `as const` map typed `{ [key in cnst.TaskStatus["value"]]: string }`,
   not `Record<...>`.
 

package/templates/workspaceRoot/biome.json.template

@@ -143,7 +143,8 @@
         "!**/*.spec.ts",
         "!**/*.spec.tsx",
         "!**/*.constant.ts",
-        "!**/common/**"
+        "!**/common/**",
+        "!apps/akan/env/**"
       ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-throw-raw-error.grit"]
     },
@@ -162,6 +163,10 @@
       "includes": ["**/*.constant.ts", "**/*.document.ts", "**/*.service.ts", "**/*.store.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
     },
+    {
+      "includes": ["**/*.store.ts"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-return-in-store-action.grit"]
+    },
     {
       "includes": ["**/*.signal.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
@@ -232,6 +237,25 @@
         "**/*.Zone.tsx"
       ],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-import-external-library.grit"]
+    },
+    {
+      "includes": [
+        "apps/**/*.ts",
+        "apps/**/*.tsx",
+        "libs/**/*.ts",
+        "libs/**/*.tsx",
+        "!**/*.test.ts",
+        "!**/*.test.tsx",
+        "!**/*.spec.ts",
+        "!**/*.spec.tsx"
+      ],
+      "plugins": [
+        "./node_modules/@akanjs/devkit/lint/no-raw-palette-class.grit",
+        "./node_modules/@akanjs/devkit/lint/no-arbitrary-color.grit",
+        "./node_modules/@akanjs/devkit/lint/no-daisyui-legacy-class.grit",
+        "./node_modules/@akanjs/devkit/lint/no-inline-color.grit",
+        "./node_modules/@akanjs/devkit/lint/no-interpolated-arbitrary-class.grit"
+      ]
     }
   ]
 }

package/templates/workspaceRoot/docs/AI-DEVELOPMENT.md.template

@@ -49,8 +49,11 @@ See `docs/GENERATED.md` for the generated file list.
 
 `AGENTS.md` holds the full style guide. The rules agents break most often:
 
-- **Never hand-order Tailwind classes** — the linter sorts them, including inside `clsx()`, and its output looks
+- **Never hand-order Tailwind classes** — the linter sorts them, including inside `cn()`, and its output looks
   unnatural on purpose.
+- **Never use a colour outside the semantic vocabulary** — `bg-red-500`, `bg-[#3b82f6]` and `text-base-content`
+  compile to no CSS at all, so the element renders unstyled with no error. Use `bg-primary`, `text-foreground/70`
+  and the other tokens defined in `page/*/styles.css`.
 - **Never `throw new Error`** — throw `new Err("<module>.error.<key>")` with an `[en, ko]` entry in the module
   dictionary. `common/` cannot import `Err`, so keep throwing code out of it.
 - **Never import a third-party package** from a page, a barrel, or a module file. Re-export it through a one-line

package/{workflow.command-z0e0fk0z.js → workflow.command-91wmvm8k.js}

@@ -1,30 +1,30 @@
 // @bun
 import {
   WorkflowRunner
-} from "./index-c94nq3c1.js";
+} from "./index-5pmx7bkg.js";
 import {
   PrimitiveScript
-} from "./index-pfrt7qwh.js";
+} from "./index-bz2sfzzt.js";
 import {
   ModuleScript
-} from "./index-60a3jfcz.js";
-import"./index-hrwzz2wf.js";
+} from "./index-vtj3zps1.js";
+import"./index-4hek879p.js";
 import {
   ScalarScript
-} from "./index-wrrb8rxk.js";
+} from "./index-gmy45vz2.js";
 import"./index-ss469dec.js";
 import"./index-0cj2zxbm.js";
-import"./index-jn9vfpwz.js";
+import"./index-mssqn2sq.js";
 import {
   createWorkflowStepRegistry
-} from "./index-m4kpmmtj.js";
-import"./index-qp089jp0.js";
+} from "./index-2c3e2xh8.js";
+import"./index-7myvn0f0.js";
 import {
   Workspace,
   command,
   script
-} from "./index-jkynkyfk.js";
-import"./index-47qxw1tz.js";
+} from "./index-6rhabeev.js";
+import"./index-vg0sj9nc.js";
 import"./index-mxvakhsm.js";
 import"./index-xys926f2.js";
 import"./index-67546d0j.js";

package/{workspace.command-3q1d6kk4.js → workspace.command-wa10mfd9.js}

@@ -1,48 +1,48 @@
 // @bun
 import {
   ContextScript
-} from "./index-p69fcwe1.js";
-import"./index-6npsfpxr.js";
-import"./index-c94nq3c1.js";
-import"./index-pfrt7qwh.js";
-import"./index-60a3jfcz.js";
-import"./index-hrwzz2wf.js";
+} from "./index-w6wbb612.js";
+import"./index-ztpw544k.js";
+import"./index-5pmx7bkg.js";
+import"./index-bz2sfzzt.js";
+import"./index-vtj3zps1.js";
+import"./index-4hek879p.js";
 import {
   CloudScript
-} from "./index-mn96y1nk.js";
+} from "./index-js368gk9.js";
 import {
   getLatestPackageVersion,
   getNpmRegistryUrl
-} from "./index-p6txr1ss.js";
+} from "./index-p3f4q532.js";
 import {
   PackageScript
-} from "./index-meh7mmz9.js";
-import"./index-wrrb8rxk.js";
+} from "./index-azv0xjb5.js";
+import"./index-gmy45vz2.js";
 import"./index-ss469dec.js";
-import"./index-mterpj70.js";
+import"./index-xhgtkekh.js";
 import {
   GlobalConfig
 } from "./index-0cj2zxbm.js";
 import {
   AgentScript
-} from "./index-nfxq39kj.js";
-import"./index-jn9vfpwz.js";
-import"./index-m4kpmmtj.js";
-import"./index-qp089jp0.js";
+} from "./index-gex7c8kd.js";
+import"./index-mssqn2sq.js";
+import"./index-2c3e2xh8.js";
+import"./index-7myvn0f0.js";
 import {
   ApplicationScript
-} from "./index-nx1vbtsc.js";
+} from "./index-5dw57f0d.js";
 import"./index-76rn3g2c.js";
 import {
   LibraryScript
-} from "./index-exhpp31y.js";
+} from "./index-a1e0j63x.js";
 import {
   Exec,
   Workspace,
   command,
   runner,
   script
-} from "./index-jkynkyfk.js";
+} from "./index-6rhabeev.js";
 import"./index-fgc8r6dj.js";
 import {
   ThemeValidator,
@@ -59,7 +59,7 @@ import {
   collectScopeRecipeSources,
   extractAgentBlock,
   renderScopeAgentBlock
-} from "./index-47qxw1tz.js";
+} from "./index-vg0sj9nc.js";
 import"./index-mxvakhsm.js";
 import {
   collectRecipeSources,