@akanjs/cli 3.0.0-beta.8 → 3.0.0

package/skills/akan-store/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: akan-store
+description: "Fill in a module store, or call module data and actions from UI — what store() already generates (CRUD, form setters, slice actions) and what belongs in your subclass."
+---
+
+# Akan store: what is already generated
+
+`class CommentStore extends store(sig.comment, () => ({ /* extra state */ })) { /* extra actions */ }`
+gives you the whole CRUD and form surface for free. **Redeclaring any of it is a typecheck error
+("already exists"), and the fix is to delete your version and call the generated one** — never rename around
+it, never cast, never reimplement.
+
+For a model `comment` (`<Slice>` is a signal slice suffix, e.g. `InPublic`):
+
+## Generated actions — `st.do.*`
+
+- write: `createComment(input)`, `updateComment(id, input)`, `removeComment(id)`
+- form: `newComment()`, `editComment(model)`, `writeOnComment(path, value)`, `set<Field>OnComment(value)`,
+  `add<Field>OnComment(value)` / `sub<Field>OnComment(idx)` for arrays, `upload<Field>OnComment(fileList)`
+  for file fields, `checkCommentSubmitable()`, `submitComment()`, `createCommentInForm()`,
+  `updateCommentInForm()`
+- single: `viewComment(model)`, `mergeComment(model, data)`, `setComment(...models)`, `resetComment()`
+- per slice: `initComment<Slice>(...args)`, `refreshComment<Slice>()`, `selectComment<Slice>(model)`,
+  `setPageOfComment<Slice>(page)`, `loadMoreOfComment<Slice>()`, `setLimitOfComment<Slice>(limit)`,
+  `setQueryArgsOfComment<Slice>(...)`, `setSortOfComment<Slice>(sort)`
+
+## Generated state — `st.use.*`
+
+`comment`, `commentLoading`, `commentForm`, `commentFormLoading`, `commentSubmit`, `commentModal`,
+`commentViewAt`, `commentOperation`; per slice `commentList<Slice>`, `commentListLoading<Slice>`,
+`commentInitList<Slice>`, `commentSelection<Slice>`, `commentInsight<Slice>`, `pageOfComment<Slice>`,
+`lastPageOfComment<Slice>`, `hasMoreOfComment<Slice>`, `limitOfComment<Slice>`, `sortOfComment<Slice>`.
+
+## What your subclass is for
+
+Only what the generated set does not cover: extra client state, a multi-step or cross-model workflow, and
+calls to the non-CRUD endpoints you added in the signal. Each is an `async` method using `this.set(...)` /
+`this.get()` / `this.pick(...)`.
+
+To reach another store, cast `this`: `import type { RootStore } from "../st"`, then
+`(this as unknown as RootStore).logout()` to call its action or `(this as unknown as RootStore).set({ … })` /
+`.get()` to write or read its state. Every store is mixed into one root at runtime, so the cast only tells the
+type what `this` already is. Keep it `import type` — `st.ts` imports every store, so a value import is a cycle.
+
+A store that needs none of this stays empty. `store(sig.comment, () => ({}))` with an empty body is the
+correct, complete result — an empty store is not an unfinished one.
+
+## The rule the linter enforces
+
+- **An action returns nothing.** Every method dispatches through `st.do.<action>()` and is typed `void`, so a
+  returned value is unreachable. Write it into state with `this.set({ … })`.
+
+## From UI
+
+Read with `st.use.commentListInPublic()`, act with `st.do.createComment(input)` / `st.do.submitComment()`.
+Do not wrap a generated action in a store method just to rename it.
+
+**Pass a form setter by reference**: `onChange={st.do.setTypeOnComment}`, never
+`onChange={(v) => st.do.setTypeOnComment(v)}`. The two run identically, but the arrow is an anonymous
+closure, so the control emits no `data-akan-action` and publishes no agent tool for the field —
+`no-unpublished-form-setter.grit` fails the build on it.
+
+## Signal side
+
+The scaffolded `slice(…, { guards: { root, get, cru } })` already exposes get / list / create / update /
+remove. Add a query or mutation only for behaviour beyond CRUD, and give it its own `guards` array — a
+custom endpoint never inherits the slice's.

package/skills/akan-ui/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: akan-ui
+description: "Build Akan pages and components: the server-by-default rule, the Unit/View vs Template/Zone/Util split, forms, and what never to hand-roll."
+---
+
+# Akan UI
+
+A new View / Unit / Template / Zone / Util for an existing module comes from the `create-ui` workflow (the
+`akan-scaffold` skill). Edit the scaffolded component instead of authoring one from scratch.
+
+## The boundary is mechanical, not a judgement call
+
+| role | side | directive |
+| --- | --- | --- |
+| `<Model>.Unit.tsx`, `<Model>.View.tsx` | server | never `"use client"` |
+| `<Model>.Template.tsx`, `<Model>.Zone.tsx`, `<Model>.Util.tsx` | client | `"use client"` on line 1 |
+| `page/**` | server | never |
+
+**Server is the default and `"use client"` is a cost you justify per component.** A component earns the
+directive only by using a hook, a JSX event handler, the store, a browser global, or a client-only package.
+Rendering markup, reading a param, calling `l()`, and mapping over data are all server work. Measure with
+`akan quality ssr`; treat 50% server share as the floor and a falling share as a regression.
+
+Four moves that keep markup on the server: wrap the interaction and render `children` untouched; split a
+compound component so only the provider holds state; fetch in the route and pass the result into a `Zone` as
+an `init` prop; push the boundary down to the leaf that needs it.
+
+## Never hand-roll these
+
+- loading / empty / list states → `Load.Units` / `Load.View` / `Load.Edit` with `renderItem`, `renderList`,
+  `renderView`, `renderEmpty`; `<Empty />` for a bare placeholder; `Model.New` / `Model.Edit` /
+  `Model.SureToRemove` for CRUD modals.
+- a mount-time fetch → the route calls `fetch.init<Model><Slice>(…)` before the first byte. A
+  `useEffect(…, [])` that loads data is flagged by `akan quality ssr`, and `fetch.init*` from a client file
+  fails lint outright.
+- a model field input → `Field.*`, never a bare `<input>`.
+- a mode switch → `Tab`, not a `useState`.
+
+## Component shape
+
+`export const X = ({ … }: XProps) => { return (…); };` — arrow const, block body. Never `React.FC`, never
+`defaultProps`, never `PropsWithChildren`; children are `children: ReactNode`. Declare
+`interface XProps` directly above the component with `className?: string` first.
+
+Conditional render is `cond ? <X/> : null`. **Never `{cond && <X/>}`** — in a `className` context it renders
+the literal string `"false"`.
+
+## Classes
+
+Never hand-order Tailwind classes; the formatter sorts them and its output is correct. Stay inside the
+semantic token vocabulary — `bg-primary`, `text-foreground/70` — because a raw palette class (`bg-blue-500`),
+an arbitrary colour (`bg-[#3b82f6]`), a daisyUI legacy class, and a colour literal in `style={{…}}` all
+render no CSS and fail lint. Reach for `cn` only for a conditional or to merge an incoming `className`, and
+merge the caller last.
+
+## Forms
+
+Store-driven end to end: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`, **the setter passed by
+reference**. An inline arrow silently drops the control's agent annotation and fails
+`no-unpublished-form-setter.grit`. Nested rows use `st.do.writeOnX("payments.3.name", v)`.
+
+Full detail: `get_guideline` with `ssrRule`, `componentRule`, `cssRule`, `recipeRule`, or the per-role
+`modelUnit` / `modelView` / `modelZone` / `modelTemplate` / `modelUtil`.

package/skills/akan-validate/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: akan-validate
+description: "Run the akan check loop after editing and fix each failure class the right way — no silencing, no lint-disable, no gaming the checker."
+---
+
+# Akan validation loop
+
+## One call does the whole chain
+
+`akan_verify` runs sync → lint → typecheck → `quality ssr` over everything the working tree has changed, in
+the right order, and reports only what failed. **Call it after editing, before you say you are done.** It
+also runs itself at the end of a turn that changed source, so a failure comes back to you either way.
+
+The same chain by hand, for the app you are editing:
+
+- `akan sync <app>` — after adding, renaming, or deleting any file. Regenerates the barrels.
+- `akan lint <app>` — fast; run after every edit. Prints up to 200 diagnostics.
+- `akan typecheck <app>` — the client/server boundary violations land here, not in lint.
+- `akan quality ssr` — only when you wrote or changed a `.tsx`. Did the server share hold?
+- `akan build <app>` — the full production build; slower, and only when the build itself is in question.
+
+Raw `tsc` misses the generated barrels and reports false errors. Do not reach for it.
+
+## Fixing rules
+
+**Apply the real fix the rule intends. Do not silence the checker.** No blanket lint-disable, no throwaway
+re-export, no export-in-place trick, no `as any`, no non-null assertion. Gaming a check is a defect, not a
+fix. When a suppression is genuinely right it carries a reason:
+`// biome-ignore lint/<rule>: <why>` — and a grit plugin diagnostic is suppressed as `lint/plugin`, not the
+bare `plugin` category Biome's own message suggests.
+
+Common classes and their real fix:
+
+| symptom | fix |
+| --- | --- |
+| a member "already exists" or conflicts with the base class | you redeclared something Akan generates, usually store CRUD. **Delete your version** and call the generated one — do not rename, cast, or suppress. See `akan-store`. |
+| `throw new Error` | a typed `Err` with a dictionary key. See `akan-err`. |
+| an edit to a generated file | regenerate instead: `akan sync <app>` or `repair_generated`. |
+| a file in the wrong place | relocate to `common/` / `webkit/` / `srvkit/` / `ui/`. Never a sibling helper `.ts` inside `lib/<model>/`. |
+| a missing dependency | declare it in the owning app or lib `package.json`. See `akan-deps`. |
+| a Tailwind class order or colour complaint | let the formatter sort; use semantic tokens. See `akan-ui`. |
+
+Re-run until clean. If a failure is genuinely outside the scope of what you changed, say so in your reply
+instead of forcing it.

package/{subspace.command-eddzqpx3.js → subspace.command-3k2pmrs4.js}

@@ -1,29 +1,28 @@
 // @bun
 import {
-  FileSys
-} from "./index-q0y2jq9j.js";
+  FileSys2
+} from "./index-52w0fvh8.js";
 import {
   GlobalConfig
-} from "./index-m0xccmmm.js";
+} from "./index-94s080qm.js";
 import {
   Workspace,
   CommandContainer,
   runner,
   script,
   command
-} from "./index-0g7r8xz3.js";
+} from "./index-vpj42xwt.js";
 import {
   Executor,
   WorkspaceExecutor,
   AppExecutor
-} from "./index-2tv3fdx4.js";
-import"./index-6wwzs1bc.js";
+} from "./index-3w94e7n3.js";
 import {
   SlicePlanner
-} from "./index-j9yhg404.js";
+} from "./index-jmrn54tt.js";
 import {
   LibSource
-} from "./index-3d9y066c.js";
+} from "./index-bjwxs904.js";
 
 // pkgs/@akanjs/devkit/subspace.ts
 import { mkdir, readdir, rename, rm } from "fs/promises";
@@ -118,16 +117,16 @@ class Subspace {
       return true;
     const normalize = (content) => {
       try {
-        const manifest = JSON.parse(content);
-        delete manifest[LibSource.manifestKey];
-        return JSON.stringify(manifest);
+        return LibSource.unstamped(content);
       } catch {
         return content;
       }
     };
     return normalize(theirs) !== normalize(ours);
   }
-  async#meaningfulFiles(ref, files) {
+  async#changedSliceFiles(ref, diffArgs) {
+    const files = (await this.#git(["diff", "--name-only", ...diffArgs])).split(`
+`).filter((file) => !!file.trim() && !this.#isSubspaceOwned(file));
     const kept = await Promise.all(files.map(async (file) => this.#isStamped(file) ? await this.#differsBeyondStamp(ref, file) : true));
     return files.filter((_, index) => kept[index]);
   }
@@ -140,14 +139,12 @@ class Subspace {
     if (!hasBranch)
       return { name: this.name, branch, hasBranch, anchor, behindPaths: [], driftedLibs: [] };
     const ref = `${this.#remote}/${branch}`;
-    const diff = await this.#git(["diff", "--name-only", "HEAD", ref, "--", ...paths]);
-    const behindPaths = await this.#meaningfulFiles(ref, diff.split(`
-`).filter((file) => !!file.trim()).filter((file) => !this.#isSubspaceOwned(file)));
+    const behindPaths = await this.#changedSliceFiles(ref, ["HEAD", ref, "--", ...paths]);
     const driftedLibs = libs.filter((lib) => behindPaths.some((file) => file.startsWith(`libs/${lib}/`)));
     return { name: this.name, branch, hasBranch, anchor, behindPaths, driftedLibs };
   }
   async#ensureClone(branch) {
-    if (!await FileSys.dirExists(path.join(this.#clonePath, ".git"))) {
+    if (!await FileSys2.dirExists(path.join(this.#clonePath, ".git"))) {
       await rm(this.#clonePath, { recursive: true, force: true });
       await mkdir(path.dirname(this.#clonePath), { recursive: true });
       await this.#workspace.spawn("git", ["clone", "--quiet", this.#declaration.repo, this.#clonePath]);
@@ -164,12 +161,12 @@ class Subspace {
     await rm(holdRoot, { recursive: true, force: true });
     for (const member of Subspace.memberDirs) {
       const memberRoot = path.join(this.#clonePath, member);
-      if (!await FileSys.dirExists(memberRoot))
+      if (!await FileSys2.dirExists(memberRoot))
         continue;
       for (const name of await readdir(memberRoot)) {
         for (const owned of Subspace.subspaceOwnedDirs) {
           const from = path.join(memberRoot, name, owned);
-          if (!await FileSys.dirExists(from))
+          if (!await FileSys2.dirExists(from))
             continue;
           const to = path.join(holdRoot, member, name, owned);
           await mkdir(path.dirname(to), { recursive: true });
@@ -192,14 +189,25 @@ class Subspace {
       const target = path.join(to, entry.name);
       if (entry.isDirectory())
         await Subspace.#copyMissing(source, target);
-      else if (!await FileSys.entryExists(target))
+      else if (!await FileSys2.entryExists(target))
         await rename(source, target);
     }
   }
   async#extract(paths, excludes = []) {
-    const pathspec = paths.map((entry) => `'${entry}'`).join(" ");
-    const excludeArgs = excludes.map((entry) => `--exclude='${entry}'`).join(" ");
-    await this.#workspace.exec(`git archive HEAD -- ${pathspec} | tar -x -C '${this.#clonePath}' ${excludeArgs}`.trim());
+    const archivePath = path.relative(this.#workspace.workspaceRoot, `${this.#clonePath}.tar`);
+    await this.#workspace.spawn("git", ["archive", "-o", archivePath, "HEAD", "--", ...paths]);
+    try {
+      await this.#workspace.spawn("tar", [
+        "-x",
+        "-f",
+        archivePath,
+        "-C",
+        this.#clonePath,
+        ...excludes.map((entry) => `--exclude=${entry}`)
+      ]);
+    } finally {
+      await rm(path.join(this.#workspace.workspaceRoot, archivePath), { force: true });
+    }
   }
   #localEnv() {
     const { serveDomain } = WorkspaceExecutor.getBaseDevEnv();
@@ -214,32 +222,32 @@ class Subspace {
   }
   async#writeLocalEnv() {
     const excludePath = path.join(this.#clonePath, ".git/info/exclude");
-    const exclude = await FileSys.fileExists(excludePath) ? await FileSys.readText(excludePath) : "";
+    const exclude = await FileSys2.fileExists(excludePath) ? await FileSys2.readText(excludePath) : "";
     if (!exclude.split(`
 `).includes("/.env")) {
       await mkdir(path.dirname(excludePath), { recursive: true });
-      await FileSys.writeText(excludePath, exclude.trim() ? `${exclude.replace(/\n*$/, `
+      await FileSys2.writeText(excludePath, exclude.trim() ? `${exclude.replace(/\n*$/, `
 `)}/.env
 ` : `/.env
 `);
     }
     const envPath = path.join(this.#clonePath, ".env");
-    if (await FileSys.fileExists(envPath))
+    if (await FileSys2.fileExists(envPath))
       return;
     const lines = Object.entries(this.#localEnv()).map(([key, value]) => `${key}=${value}`);
-    await FileSys.writeText(envPath, `${lines.join(`
+    await FileSys2.writeText(envPath, `${lines.join(`
 `)}
 `);
   }
   async#rewriteManifest(plans) {
     const manifestPath = path.join(this.#clonePath, "package.json");
-    if (!await FileSys.fileExists(manifestPath))
+    if (!await FileSys2.fileExists(manifestPath))
       return [];
-    const rootPackageJson = await FileSys.readJson(manifestPath);
+    const rootPackageJson = await FileSys2.readJson(manifestPath);
     const { packageJson, pruned, warnings } = await SlicePlanner.pruneDependencies(this.#workspace, rootPackageJson, plans.flatMap((plan) => plan.requiredDependencies));
     for (const warning of warnings)
       this.#workspace.logger.warn(warning);
-    await FileSys.writeJson(manifestPath, {
+    await FileSys2.writeJson(manifestPath, {
       ...packageJson,
       name: this.name,
       description: `${this.name} workspace`
@@ -266,11 +274,10 @@ class Subspace {
   }
   async#rewriteGitignore() {
     const gitignorePath = path.join(this.#clonePath, ".gitignore");
-    if (!await FileSys.fileExists(gitignorePath))
+    if (!await FileSys2.fileExists(gitignorePath))
       return;
     const [begin = "", end = ""] = Subspace.secretsMarkers;
-    const lines = (await FileSys.readText(gitignorePath)).split(`
-`);
+    const lines = (await FileSys2.readText(gitignorePath)).split(/\r?\n/);
     const beginIdx = lines.indexOf(begin);
     const endIdx = lines.indexOf(end);
     const filtered = beginIdx >= 0 && endIdx > beginIdx ? [
@@ -278,7 +285,7 @@ class Subspace {
       ...lines.slice(beginIdx + 1, endIdx).filter((line) => this.#declaration.apps.some((app) => line.startsWith(`apps/${app}/`))),
       ...lines.slice(endIdx)
     ] : lines;
-    await FileSys.writeText(gitignorePath, filtered.filter((line) => line.trim() !== "**/bun.lock").join(`
+    await FileSys2.writeText(gitignorePath, filtered.filter((line) => line.trim() !== "**/bun.lock").join(`
 `));
   }
   async#rewriteWorkspaceSection(libs) {
@@ -289,27 +296,27 @@ class Subspace {
     ];
     for (const file of ["AGENTS.md", "CLAUDE.md"]) {
       const filePath = path.join(this.#clonePath, file);
-      if (!await FileSys.fileExists(filePath))
+      if (!await FileSys2.fileExists(filePath))
         continue;
-      const content = await FileSys.readText(filePath);
+      const content = await FileSys2.readText(filePath);
       const rewritten = replacements.reduce((text, [pattern, value]) => text.replace(pattern, value), content);
       if (rewritten !== content)
-        await FileSys.writeText(filePath, rewritten);
+        await FileSys2.writeText(filePath, rewritten);
     }
   }
   async#stampLib(clone, lib, branch) {
     const manifestPath = path.join(this.#clonePath, "libs", lib, "package.json");
-    if (!await FileSys.fileExists(manifestPath))
+    if (!await FileSys2.fileExists(manifestPath))
       return;
     const origin = `${this.#workspace.repoName}#${branch}`;
     const sha = await this.headSha();
     const [hash, previous] = await Promise.all([this.#hashLib(clone, lib), this.#committedStamp(clone, lib)]);
-    const manifest = await FileSys.readJson(manifestPath);
+    const manifest = await FileSys2.readJson(manifestPath);
     const akan = manifest[LibSource.manifestKey] ?? {};
     const unchanged = previous?.origin === origin && previous.sha === sha && previous.hash === hash;
     const syncedAt = unchanged ? previous.syncedAt : new Date().toISOString();
     manifest[LibSource.manifestKey] = { ...akan, source: { origin, sha, hash, syncedAt } };
-    await FileSys.writeJson(manifestPath, manifest);
+    await FileSys2.writeJson(manifestPath, manifest);
   }
   async#committedStamp(clone, lib) {
     try {
@@ -332,22 +339,9 @@ class Subspace {
       `libs/${lib}`
     ]);
     const candidates = listed.split("\x00").filter((file) => !!file && !this.#isSubspaceOwned(file)).sort();
-    const present = await Promise.all(candidates.map(async (file) => await FileSys.entryExists(path.join(this.#clonePath, file))));
+    const present = await Promise.all(candidates.map(async (file) => await FileSys2.entryExists(path.join(this.#clonePath, file))));
     const files = candidates.filter((_, index) => present[index]);
-    const hasher = new Bun.CryptoHasher("sha256");
-    for (const file of files) {
-      const content = await FileSys.readText(path.join(this.#clonePath, file));
-      hasher.update(file);
-      hasher.update("\x00");
-      if (file === `libs/${lib}/package.json`) {
-        const manifest = JSON.parse(content);
-        delete manifest[LibSource.manifestKey];
-        hasher.update(JSON.stringify(manifest));
-      } else
-        hasher.update(content);
-      hasher.update("\x00");
-    }
-    return hasher.digest("hex").slice(0, 32);
+    return await LibSource.hashFiles(files, `libs/${lib}/package.json`, (file) => FileSys2.readText(path.join(this.#clonePath, file)));
   }
   async diff(branch, filter) {
     if (!await this.fetch(branch))
@@ -366,10 +360,7 @@ class Subspace {
     if (!scoped.length)
       return { files: [], patch: "" };
     const from = `${this.#remote}/${branch}`;
-    const pathspec = filter ? [filter] : scoped;
-    const names = await this.#git(["diff", "--name-only", from, "HEAD", "--", ...pathspec]);
-    const files = await this.#meaningfulFiles(from, names.split(`
-`).filter((file) => !!file.trim()).filter((file) => !this.#isSubspaceOwned(file)));
+    const files = await this.#changedSliceFiles(from, [from, "HEAD", "--", ...filter ? [filter] : scoped]);
     if (!files.length)
       return { files: [], patch: "" };
     return { files, patch: await this.#git(["diff", from, "HEAD", "--", ...files]) };
@@ -423,7 +414,7 @@ class Subspace {
     };
   }
   async#writeAnchorFile(branch) {
-    await FileSys.writeJson(path.join(this.#clonePath, Subspace.anchorFile), {
+    await FileSys2.writeJson(path.join(this.#clonePath, Subspace.anchorFile), {
       workspace: this.#workspace.repoName,
       hubSha: await this.headSha(),
       branch,
@@ -460,7 +451,7 @@ class Subspace {
   async#savePatch(range, files, label) {
     const patchPath = path.join(this.#workspace.workspaceRoot, ".akan/subspace", `${this.name}-${label}.patch`);
     await mkdir(path.dirname(patchPath), { recursive: true });
-    await FileSys.writeText(patchPath, await this.#git(["diff", range, "--", ...files]));
+    await FileSys2.writeText(patchPath, await this.#git(["diff", range, "--", ...files]));
     return { path: path.relative(this.#workspace.workspaceRoot, patchPath), absolute: patchPath, files };
   }
 }
@@ -582,7 +573,7 @@ class SubspaceConfig {
   static defaultPushableBranches = ["main", "develop", "debug"];
   static async from(workspace) {
     const configPath = path2.join(workspace.workspaceRoot, SubspaceConfig.fileName);
-    if (!await FileSys.fileExists(configPath))
+    if (!await FileSys2.fileExists(configPath))
       return null;
     const input = await import(configPath).then((mod) => mod.default);
     return new SubspaceConfig(input);
@@ -725,7 +716,7 @@ class SubspaceRunner extends runner("subspace") {
     if (!asked)
       return { name: subspace.name, workspaceId, host, apps, libs: [], outcome: "cancelled", files: [] };
     const { libs } = await subspace.slice();
-    const { CloudScript } = await import("./cloud.script-cm11xjdz.js");
+    const { CloudScript } = await import("./cloud.script-nemnzjpv.js");
     const { files } = await CommandContainer.get(CloudScript).uploadEnv(workspace, {
       host,
       workspaceId,

package/templates/__scalar/__model__/__model__.abstract.md.template

@@ -0,0 +1,8 @@
+# <%= model %> Abstract
+
+<One sentence: the value this scalar holds, and what embeds it.>
+
+## Rules
+
+- <What a caller may assume about the value that the constant file cannot say: an order, a unit, a fixed value.>
+- <Two to five of them. A single field's meaning goes in a trailing comment beside it in the constant file.>