@akanjs/cli 2.4.2-rc.3 → 3.0.0-alpha.1

package/templates/workspaceRoot/AGENTS.md.template

@@ -74,11 +74,12 @@ Use the local module shape before adding a new abstraction.
 9. Keep page and layout files server-oriented: route-level `usePage`, headers, static layout, and `akanjs/ui` `Tab` composition belong there.
 10. Put interactive loading, submit/import actions, local form state, and `router.push` in client `Util`, `Template`, or `Zone` components.
 11. Prefer `Tab` for static mode selection instead of extra `useState`; render one focused client component inside each `Tab.Panel`.
-12. Keep server-only logic out of client surfaces and client-only code out of server imports.
-13. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
-14. Add or update tests when behavior, contracts, or CLI output changes.
-15. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
-16. Run the smallest relevant verification command after changes.
+12. Default to server rendering. Add `"use client"` only for a real client-only capability, and keep markup out of the component that carries it — see **SSR First** below.
+13. Keep server-only logic out of client surfaces and client-only code out of server imports.
+14. Treat `AKAN_PUBLIC_*` env vars as public. Never put secrets in them.
+15. Add or update tests when behavior, contracts, or CLI output changes.
+16. Update `*.abstract.md` when business invariants, workflows, or public behavior change.
+17. Run the smallest relevant verification command after changes. After touching any `.tsx`, that includes `akan quality ssr`.
 
 ## Common Commands
 
@@ -111,7 +112,11 @@ akan typecheck <%= appName %>
 # 3. Test — Run the test code (lib/*/*.signal.test.ts or others)
 akan test <%= appName %>
 
-# 4. Full production build — bundles the app, runs all type/lint checks combined
+# 4. SSR balance — only after touching .tsx files. Reports the server render share
+#    per app/lib and flags client code that should render on the server.
+akan quality ssr
+
+# 5. Full production build — bundles the app, runs all type/lint checks combined
 akan build <%= appName %>
 ```
 
@@ -128,6 +133,8 @@ akan create-scalar <scalar-name> <%= appName %>          # Add a scalar module (
 akan create-service <service-name> <%= appName %>        # Add a service module (lib/_<service-name>/)
 akan test <%= appName %>                             # Run the test code (lib/*/*.signal.test.ts or others)
 akan lint <%= appName %>                             # Lint only (no typecheck)
+akan quality scan                                # All code-quality warnings + SSR balance
+akan quality ssr                                 # SSR balance and client-boundary warnings only
 ```
 
 **CLI argument conventions.** Two argument styles, and mixing them up is a common mistake:
@@ -239,8 +246,8 @@ final fallback when no CLI command covers the change.
 | Add a pure workflow / integration (e.g., Payment, Email) | `lib/_<service>/` → service, signal, store, dictionary, abstract | `akan sync <name>` |
 | Add a reusable value type (e.g., Address, WorkHistory) | `lib/__scalar/<type>/` → constant, dictionary, abstract | `akan sync <name>` |
 | Create a new URL-visitable page | `page/` → `_index.tsx`, `_layout.tsx`, `[param]/_index.tsx` | Rebuild (akan start auto-detects) |
-| Change the app color theme / design tokens | `apps/<app>/page/styles.css` → edit the daisyUI `@plugin "daisyui/theme"` blocks (`light`/`dark`, the `--color-*` variables) | akan start hot-reloads |
-| Add a form or reusable UI component | `ui/` → PascalCase `.tsx` with `"use client"` if needed | `akan sync <name>` |
+| Change the app color theme / design tokens | `apps/<app>/page/styles.css` → override the semantic token values under `:root, [data-theme="dark"]` and `[data-theme="light"]` (`--primary`, `--background`, `--foreground`, …) | akan start hot-reloads |
+| Add a form or reusable UI component | `ui/` → PascalCase `.tsx`, **no** `"use client"` unless it uses a hook, event handler, store, or browser API | `akan sync <name>` |
 | Add a React hook or browser helper | `webkit/` → camelCase `.ts` with `"use client"` | `akan sync <name>` |
 | Add a server-only guard, middleware, or adaptor | `srvkit/` → PascalCase `.ts` | `akan sync <name>` |
 | Add a pure helper (no DOM, no server API) | `common/` → camelCase `.ts` | `akan sync <name>` |
@@ -261,6 +268,120 @@ final fallback when no CLI command covers the change.
 | Use "use client" or `useState`/`useEffect` in pages/*.tsx, *.Unit.tsx, and *.View.tsx files | Server code cannot use React hooks. Wrap in a separate `"use client"` component. | Move hook logic to `webkit/` or a `"use client"` UI component |
 | Use `<a>` tag for internal navigation between pages | Akan.js uses `<Link>` from `akanjs/ui` for client-side navigation — avoids full page reloads. | `import { Link } from "akanjs/ui"` and use `<Link href="/task">...</Link>` |
 | Name a custom `Endpoint`/`Slice` like a generated CRUD op — `create<Model>`, `update<Model>`, `remove<Model>`, `view<Model>`, `edit<Model>`, `merge<Model>` | These names are already auto-generated. A collision can pass sync/typecheck/build and only fail at runtime. | Pick a distinct verb, e.g. `startTask`/`archiveTask`, never `createTask` for a custom endpoint |
+| Add `"use client"` to a file that renders markup but uses no hook, event handler, store, or browser API | The directive is a cost, not a formality: everything behind it ships twice, as HTML and as JS that re-runs in the browser. | Delete the directive. `akan quality ssr` flags this as `akan.ssr.unnecessary-use-client` |
+| Put a large static subtree inside a client component that only needs one `onClick` | The whole subtree lands in the bundle for the sake of one handler. | Keep the handler in a small client shell and pass the static markup in as `children`, or move it to a `Unit`/`View` |
+| Load server data with `useEffect(() => { void st.do.initTaskInTodo(); }, [])` | The page renders an empty shell, hydrates, then round-trips for data the server already had. | `await fetch.initTaskInTodo()` in the page and pass `init` to the `Zone` |
+
+## SSR First — Server Rendering Is The Default
+
+Akan is SSR-first. Every JSX element that renders on the server ships as HTML and costs nothing to hydrate; every
+element behind `"use client"` ships twice — as markup and as bundled JS that must re-run in the browser. The
+boundary question is not which file *may* be client, it is **how little** ends up on the client side.
+
+**The default is server. `"use client"` is a cost you justify per component, not a habit.** A component earns the
+directive only by using a client-only capability: a React hook, a JSX event handler, the store (`st.use.*` /
+`st.do.*`), a browser global, or a client-only third-party package. Rendering markup, mapping over data, reading a
+route param, and calling `l()` are all server work — `usePage()` and `l()` are legal in server components and never
+force a boundary.
+
+The file role decides *where* the boundary sits (`Template`/`Zone`/`Util` are client, `Unit`/`View` are server); it
+does not decide how much markup sits behind it. A `Zone` that hoards markup is still an SSR regression.
+
+Measure with `akan quality ssr` (`--format json` for tooling). It reports the server render share per app and lib —
+server-rendered JSX elements over total — plus the warnings below. Treat **50% server share as the floor** and a
+falling share as a regression to justify or revert.
+
+| Rule | Means |
+|---|---|
+| `akan.ssr.unnecessary-use-client` | The directive is there but nothing in the file needs it. Delete it. |
+| `akan.ssr.client-static-component` | A component in a client file renders real markup with zero client-only capability — pure server work sitting in the bundle. |
+| `akan.ssr.client-static-markup` | A large subtree wraps one or two interactive touches. Split it: interaction stays client, markup goes server. |
+| `akan.ssr.client-mount-load` | A `useEffect(…, [])` loads server data. The page can fetch it before the first byte. |
+| `akan.ssr.module-missing-server-view` | A module renders only from `Template`/`Zone`/`Util` and has no `Unit`/`View` at all. |
+| `akan.ssr.template-client-state` | A `Template` holds form state in `useState` instead of the store. |
+
+A third-party client package and the `ui/<Folder>/index_.tsx` + `lazy()` boundary both justify the directive and are
+not flagged. Interaction-driven `fetch.*` inside an `onClick` is not flagged either — only mount-time loads are,
+because those are the ones the server could have performed.
+
+### Server-Side Implementation Playbook
+
+**① Wrap the interaction, not the UI.** The smallest useful client component adds one behaviour and renders
+`children` untouched, so the markup inside never reaches the bundle.
+
+```tsx
+// apps/<%= appName %>/ui/ClickWrapper.tsx
+"use client";
+export const ClickWrapper = ({ children, onPick }: ClickWrapperProps) => <div onClick={onPick}>{children}</div>;
+
+// in a server page — Task.Unit.Card stays server-rendered
+<ClickWrapper onPick={…}>
+  <Task.Unit.Card task={task} />
+</ClickWrapper>
+```
+
+**② Split compound components so panels stay on the server.** A tab, accordion, or disclosure needs client state
+only for *which* part is visible — never for what the parts contain. `Tab` / `Tab.Menus` / `Tab.Menu` / `Tab.Panel`
+from `akanjs/ui` is the reference shape: only the provider and menu hold state, and `<Tab.Panel>` renders its
+children as-is, so a server `Unit`/`View` passed in stays server-rendered.
+
+```tsx
+<Tab defaultMenu="detail">
+  <Tab.Menus>
+    <Tab.Menu menu="detail">{l("task.detail")}</Tab.Menu>
+    <Tab.Menu menu="history">{l("task.history")}</Tab.Menu>
+  </Tab.Menus>
+  <Tab.Panel menu="detail">
+    <Task.View.General task={task} />
+  </Tab.Panel>
+</Tab>
+```
+
+Never collapse this into one `"use client"` file with a mode `useState` and every panel body inlined.
+
+**③ Sync state instead of fetching it.** A server component cannot hold state, so render the initial data on the
+server and hand it across the boundary as a serializable object. That is what `init` / `view` props are: the page
+calls `fetch.initTaskInTodo()` / `fetch.viewTask(id)`, passes the result into a `Zone`, and `Load.Units` /
+`Load.View` hydrate the store from it.
+
+```tsx
+export default async function Page() {
+  const [{ taskInitInTodo }] = await Promise.all([fetch.initTaskInTodo()]);
+  return <Task.Zone.Card init={taskInitInTodo} sliceName="taskInTodo" />;
+}
+```
+
+**④ Push the boundary down to the leaf that needs it.** When a `Zone` reads the store, it should hold *zero* markup
+and delegate to a server `View`, so the whole detail surface renders server-side wherever a page uses the `View`
+directly.
+
+```tsx
+"use client";
+export const Self = () => <Task.View.General task={st.use.task()} />;
+```
+
+**⑤ Hand the promise across, not the awaited value.** `ClientInit` / `ClientView` are `PromiseOrObject<T>`, so a
+page may pass an unawaited `fetch.initTaskInTodo()` and `Load.*` resolves it behind a skeleton. `await` blocks the
+shell for data the page needs immediately; passing the promise streams the rest. Independent fetches still go
+through one `Promise.all`.
+
+**⑥ Use named `ReactNode` slots, not just `children`.** A client shell can take several server-rendered subtrees:
+`Layout.Navbar` accepts `title`, `back`, `left`, `right`, and `children`, so it composes server content in five
+places instead of absorbing it.
+
+**⑦ Let the server do the derived work.** Display and predicate logic belongs on `LightTask` (`isNew()`,
+`canWrite(user?)`, `formatTimes()`), and enum→class lookups belong in a module-scope `as const` map. Both sides call
+the same method, so a client component that exists only to compute a label is markup in the wrong place.
+
+**⑧ Gate auth on the server.** Check the session in `_layout.tsx` and redirect there, before any HTML is sent. A
+client-side auth check costs a hydration round-trip and flashes the wrong UI first.
+
+**⑨ Prefer CSS over client state for pure visibility.** A `data-*` attribute plus `group-data-[…]` variants, or
+`<details>`/`<summary>`, keeps both branches server-rendered. Reach for `useState` when the state is real, not when
+a Tailwind variant would do.
+
+**⑩ Keep the heavy island out of the first load.** A large client-only widget goes behind the
+`ui/<Folder>/index_.tsx` + `lazy()` pair so the server renders the page around it.
 
 ## Code Style
 
@@ -439,11 +560,9 @@ const form = st.use.taskForm();
 
 // 4. apps/<app>/lib/<model>/<Model>.Unit.tsx
 // Display the new field in card/list views
-<span className={clsx("badge badge-sm", {
-  "badge-error": task.priority === "high",
-  "badge-warning": task.priority === "medium",
-  "badge-ghost": task.priority === "low",
-})}>{task.priority}</span>
+<Badge variant={task.priority === "high" ? "error" : task.priority === "medium" ? "warning" : "default"}>
+  {task.priority}
+</Badge>
 
 // 5. Regenerate barrels
 // akan sync <name>
@@ -632,7 +751,7 @@ async startTask(taskId: string) {
 
 // 6. <Model>.Util.tsx — Reusable button component
 export const Start = ({ taskId }: { taskId: string }) => (
-  <button className="btn btn-xs btn-primary" onClick={() => st.do.startTask(taskId)}>
+  <button className={buttonRecipe({ variant: "primary", size: "xs" })} onClick={() => st.do.startTask(taskId)}>
     Start
   </button>
 );
@@ -694,13 +813,13 @@ export class TaskInsight extends via(Task, (field) => ({
 // 3. <Model>.View.tsx — Display component consuming an Insight model
 export const Stats = ({ taskInsight }: { taskInsight: cnst.TaskInsight }) => (
   <div className="grid grid-cols-2 gap-4">
-    <div className="stat rounded-lg border border-base-content/10 bg-base-100 p-4">
-      <div className="stat-title text-base-content/60">{l("task.totalCount")}</div>
-      <div className="stat-value text-primary">{taskInsight.totalCount}</div>
+    <div className="rounded-lg border border-border bg-card p-4">
+      <div className="text-muted-foreground text-sm">{l("task.totalCount")}</div>
+      <div className="font-bold text-2xl text-primary">{taskInsight.totalCount}</div>
     </div>
-    <div className="stat rounded-lg border border-base-content/10 bg-base-100 p-4">
-      <div className="stat-title text-base-content/60">{l("task.completedCount")}</div>
-      <div className="stat-value text-success">{taskInsight.completedCount}</div>
+    <div className="rounded-lg border border-border bg-card p-4">
+      <div className="text-muted-foreground text-sm">{l("task.completedCount")}</div>
+      <div className="font-bold text-2xl text-success">{taskInsight.completedCount}</div>
     </div>
   </div>
 );

package/templates/workspaceRoot/biome.json.template

@@ -93,7 +93,7 @@
           "fix": "safe",
           "options": {
             "attributes": ["classList"],
-            "functions": ["clsx", "cva"]
+            "functions": ["clsx", "cn"]
           }
         }
       },

package/{workflow.command-yy0d9gk3.js → workflow.command-e0tt0vk2.js}

@@ -1,32 +1,33 @@
 // @bun
 import {
   WorkflowRunner
-} from "./index-h971erkm.js";
-import {
-  ScalarScript
-} from "./index-z5v766nx.js";
+} from "./index-2q1f5j9k.js";
 import {
   PrimitiveScript
-} from "./index-acwxfncv.js";
+} from "./index-bekddz9q.js";
 import {
   ModuleScript
-} from "./index-04as43rp.js";
-import"./index-dgeaqwmw.js";
+} from "./index-yzmhasdb.js";
+import"./index-bbkek1bp.js";
+import {
+  ScalarScript
+} from "./index-ec09pws3.js";
 import"./index-ss469dec.js";
-import"./index-v9jqrdd1.js";
+import"./index-0cj2zxbm.js";
+import"./index-a00jg8x8.js";
 import {
   createWorkflowStepRegistry
-} from "./index-pfnh87f9.js";
-import"./index-xftstr5s.js";
-import"./index-nsj2ftxj.js";
+} from "./index-rzwcpcc3.js";
+import"./index-tdbas9r0.js";
 import {
   Workspace,
   command,
   script
-} from "./index-d0h48d2f.js";
-import"./index-xwfg9bam.js";
+} from "./index-8hsbnyes.js";
+import"./index-hgna5rjy.js";
+import"./index-mxvakhsm.js";
+import"./index-xys926f2.js";
 import"./index-67546d0j.js";
-import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/cli/workflow/workflow.script.ts

package/{workspace.command-stv9g4a0.js → workspace.command-fpda0evj.js}

@@ -1,61 +1,74 @@
 // @bun
 import {
   ContextScript
-} from "./index-y1e79mz3.js";
-import"./index-7ppn9v4n.js";
-import"./index-h971erkm.js";
+} from "./index-1pvex4az.js";
+import"./index-mr5s7mqd.js";
+import"./index-2q1f5j9k.js";
+import"./index-bekddz9q.js";
+import"./index-yzmhasdb.js";
+import"./index-bbkek1bp.js";
 import {
   CloudScript
-} from "./index-h6eav7zx.js";
-import"./index-z5v766nx.js";
-import"./index-acwxfncv.js";
-import"./index-04as43rp.js";
-import"./index-dgeaqwmw.js";
-import"./index-ss469dec.js";
-import"./index-zfp1gz9f.js";
-import {
-  AgentScript
-} from "./index-zn9rh7sh.js";
-import"./index-v9jqrdd1.js";
-import"./index-pfnh87f9.js";
-import"./index-xftstr5s.js";
+} from "./index-nm6wghb6.js";
 import {
   getLatestPackageVersion,
   getNpmRegistryUrl
-} from "./index-h5cvg9z9.js";
+} from "./index-zasydjxd.js";
 import {
   PackageScript
-} from "./index-z36qzgzp.js";
+} from "./index-k95xkh4p.js";
+import"./index-ec09pws3.js";
+import"./index-ss469dec.js";
+import"./index-t3723f99.js";
 import {
   GlobalConfig
-} from "./index-nsj2ftxj.js";
+} from "./index-0cj2zxbm.js";
+import {
+  AgentScript
+} from "./index-ej426mcr.js";
+import"./index-a00jg8x8.js";
+import"./index-rzwcpcc3.js";
+import"./index-tdbas9r0.js";
 import {
   ApplicationScript
-} from "./index-fbv96xaw.js";
+} from "./index-e16gnn26.js";
 import"./index-76rn3g2c.js";
 import {
   LibraryScript
-} from "./index-s9s0n5fz.js";
+} from "./index-7c6k4yvg.js";
 import {
   Exec,
   Workspace,
   command,
   runner,
   script
-} from "./index-d0h48d2f.js";
+} from "./index-8hsbnyes.js";
 import"./index-fgc8r6dj.js";
+import {
+  ThemeValidator,
+  countBlocking,
+  formatStyleContract
+} from "./index-xjd3rqzj.js";
+import"./index-bjpxzr6s.js";
 import {
   AppExecutor,
   LibExecutor,
   PkgExecutor,
-  WorkspaceExecutor
-} from "./index-xwfg9bam.js";
+  SysExecutor,
+  WorkspaceExecutor,
+  collectScopeRecipeSources,
+  extractAgentBlock,
+  renderScopeAgentBlock
+} from "./index-hgna5rjy.js";
+import"./index-mxvakhsm.js";
+import {
+  collectRecipeSources,
+  scanRecipes
+} from "./index-xys926f2.js";
 import"./index-46tjzh6s.js";
 import {
   FileSys
 } from "./index-67546d0j.js";
-import"./index-bjpxzr6s.js";
-import"./index-6pz1j0zj.js";
 import"./index-r24hmh0q.js";
 
 // pkgs/@akanjs/cli/workspace/workspace.script.ts
@@ -69,7 +82,6 @@ var defaultWorkspacePeerDependencies = new Set([
   "@use-gesture/react",
   "chance",
   "croner",
-  "daisyui",
   "react",
   "react-dom",
   "react-icons",
@@ -231,6 +243,54 @@ class WorkspaceRunner extends runner("workspace") {
       "--no-errors-on-unmatched",
       exec.cwdPath
     ]);
+    await this.#enforceStyleContract(exec);
+    await this.#enforceRecipeGate(exec);
+    await this.#enforceAgentsIndex(exec);
+  }
+  async#enforceAgentsIndex(exec) {
+    if (!(exec instanceof SysExecutor))
+      return;
+    const scope = { type: exec.type, name: exec.name };
+    const scanInfo = await exec.scan({ write: false });
+    const sources = await collectScopeRecipeSources(exec.workspace.workspaceRoot, scope, scanInfo.getScanResult().libDeps);
+    const expected = renderScopeAgentBlock(scope, scanRecipes(sources));
+    const existing = await exec.exists("AGENTS.md") ? await exec.readFile("AGENTS.md") : null;
+    const actual = existing ? extractAgentBlock(existing) : null;
+    if (actual === expected.trim())
+      return;
+    throw new Error(`[agentsIndex] ${scope.type}s/${scope.name}/AGENTS.md \uC758 recipe \uC0C9\uC778\uC774 \uC18C\uC2A4\uC640 \uB2E4\uB985\uB2C8\uB2E4(stale). ` + `\`akan sync ${scope.name}\` \uC744 \uC2E4\uD589\uD574 \uC7AC\uC0DD\uC131\uD558\uC138\uC694.`);
+  }
+  async#enforceRecipeGate(exec) {
+    const cwdPath = exec.cwdPath;
+    if (!cwdPath)
+      return;
+    const uiDir = path.join(cwdPath, "ui");
+    const sources = [
+      ...await collectRecipeSources(uiDir, "ui/Recipe"),
+      ...await collectRecipeSources(uiDir, "ui/recipe", "recipe")
+    ];
+    if (sources.length === 0)
+      return;
+    const offenders = scanRecipes(sources).filter((recipe) => !Object.values(recipe.variants).some((values) => values.length >= 2 || values.length === 1 && values[0] === "true"));
+    if (offenders.length === 0)
+      return;
+    throw new Error(`[recipeGate] variant-less recipe(s): ${offenders.map((recipe) => recipe.name).join(", ")}
+` + "\uACE0\uB97C \uC635\uC158 \uC5C6\uB294 look \uC740 recipe \uB85C \uB450\uC9C0 \uB9C8\uC138\uC694 \u2014 \uC790\uAE30 \uB9C8\uD06C\uC5C5\uC774 \uC788\uC73C\uBA74 \uCEF4\uD3EC\uB10C\uD2B8\uB85C \uC2B9\uACA9\uD558\uACE0, " + "\uB2E4\uB978 \uCEF4\uD3EC\uB10C\uD2B8\uC758 className \uC5D0 \uC8FC\uC785\uD558\uB294 \uC2A4\uD0A8\uC774\uBA74 \uACF5\uC720 \uD074\uB798\uC2A4 \uC0C1\uC218\uB85C \uB450\uC138\uC694.");
+  }
+  async#enforceStyleContract(exec) {
+    const cwdPath = exec.cwdPath;
+    if (!cwdPath)
+      return;
+    const stylesCssPath = path.join(cwdPath, "page", "styles.css");
+    const theme = await Bun.file(stylesCssPath).exists() ? new ThemeValidator().validate(await Bun.file(stylesCssPath).text()) : [];
+    const violations = { style: [], theme };
+    const blocking = countBlocking(violations);
+    if (blocking === 0)
+      return;
+    throw new Error(`[themeValidator] ${blocking} blocking contrast violation(s):
+${formatStyleContract(violations)}
+
+` + "\uD14C\uB9C8 \uD1A0\uD070 \uAC12\uC758 \uC804\uACBD/\uBC30\uACBD \uCF58\uD2B8\uB77C\uC2A4\uD2B8\uB97C WCAG \uAE30\uC900 \uC774\uC0C1\uC73C\uB85C \uC870\uC815\uD558\uC138\uC694.");
   }
   async writeTopLevelEnv(workspace, devProjectId) {
     await workspace.writeFile(".env", `AKAN_WORKSPACE_ID=${devProjectId}