@akanjs/cli 2.4.0-rc.0 → 2.4.0-rc.1

package/guidelines/componentRule/componentRule.instruction.md

@@ -15,6 +15,14 @@ Use this for shared UI rules across module, scalar, app UI, and docs components.
 - Client components can use store hooks and event handlers where interaction is required.
 - Use generated model types from app client or module constants; do not invent duplicate UI-only model shapes.
 
+## Customizing Framework Components (Slot Overrides)
+- When a default `akanjs/ui` component (Button, Select, Modal, Table, Input, Radio, DatePicker, Loading, …) is too restrictive for the design, re-skin it per route with a slot override instead of forking, wrapping every call site, or fighting it with `!important`.
+- Write the drop-in replacement in `apps/<app>/ui/`, typed against the slot contract — `AkanModalComponent`, or `AkanUiOverrides["<Slot>"]` for any other slot — so it is compile-checked as a real substitute. Compose the framework's headless parts (e.g. `Dialog`) rather than re-implementing focus trapping, portals, or scroll-lock.
+- Bind it in a logic-free `page/**/_overrides.tsx` manifest: imports plus a single `export default override({ Slot: BrandComponent })` (from `akanjs/ui`), no `"use client"`.
+- Place the manifest at `page/` for an app-wide skin, or inside a route group/segment to scope it; nested manifests merge over ancestors slot-by-slot (closest ancestor wins, unlisted slots keep inheriting).
+- Compound components expose one slot per leaf named `<Base><Sub>` (e.g. `InputPassword`, `RadioItem`, `LoadingSpin`); override only the leaves you need.
+- See the `references/ui/customize` docs page for the full slot list and examples.
+
 ## Codegen Rules
 - Do not put business workflow decisions in render code.
 - Do not use undocumented UI components or props.

package/guidelines/cssRule/cssRule.instruction.md

@@ -15,6 +15,24 @@ Use TailwindCSS and DaisyUI in a theme-safe, composable way for Akan UI and docs
 - Use consistent density and spacing within one component family.
 - Keep custom CSS files rare and scoped to cases utilities cannot express cleanly.
 
+## Theme Customization (`apps/<app>/page/styles.css`)
+- The app theme is defined in `apps/<app>/page/styles.css` with daisyUI v5 `@plugin "daisyui/theme"` blocks (typically `light` and a `default: true` `dark`).
+- Brand-level customization means tuning the whole theme block, not only the color tokens. A theme that only changes `--color-*` still looks like the default framework skin.
+- Color tokens: `--color-primary`, `--color-secondary`, `--color-accent`, `--color-neutral`, `--color-info`, `--color-success`, `--color-warning`, `--color-error`, `--color-base-100/200/300`, and their `*-content` pairs.
+- Shape and feel tokens (set these too):
+  - `--radius-selector` — rounding for checkbox, toggle, badge.
+  - `--radius-field` — rounding for button, input, select, tab.
+  - `--radius-box` — rounding for card, modal, alert.
+  - `--size-selector`, `--size-field` — base scale (density) of selector and field controls.
+  - `--border` — component border width (e.g. `1px`, `2px`).
+  - `--depth` — `0` flat, `1` adds a subtle 3D lift to components.
+  - `--noise` — `0` off, `1` adds a grain texture to surfaces.
+- Keep shape/feel tokens consistent across the light and dark theme blocks unless the design deliberately differs by mode.
+
+## When Utilities Are Not Enough
+- Prefer theme tokens and DaisyUI component classes over one-off utility stacks that re-implement a component's look.
+- When a framework `akanjs/ui` component is structurally too restrictive, re-skin it with a `page/**/_overrides.tsx` slot override (see the componentRule guideline), not with `!important` utilities or a fork.
+
 ## Codegen Rules
 - Do not hardcode hex colors or one-off brand colors unless the existing file already defines that design system.
 - Do not use important flags to fight component composition.

package/guidelines/framework/framework.instruction.md

@@ -22,6 +22,12 @@ Use this as the compact framework context for AI codegen. It should explain how
 - Keep business decisions in constant, document, or service; keep API exposure in signal; keep client coordination in store; keep rendering in UI files.
 - Use direct module imports where scanner rules expect them, and avoid inventing new top-level app folders.
 
+## Theming And UI Customization
+When a request implies a distinct look and feel, do not stop at colors — customize both the theme and, when needed, the components.
+
+- **Theme (`apps/<app>/page/styles.css`).** The app theme is one or more daisyUI v5 `@plugin "daisyui/theme"` blocks. Match the brand by tuning the whole block, not only the `--color-*` tokens: set corner rounding (`--radius-selector`, `--radius-field`, `--radius-box`), control density (`--size-selector`, `--size-field`), outline weight (`--border`), and surface treatment (`--depth`, `--noise`). New workspaces ship these knobs at neutral defaults so they are visible to tune. Fetch `get_guideline` with `cssRule` for the full variable reference before a deep theme pass.
+- **Components (`page/**/_overrides.tsx`).** When a default `akanjs/ui` component (Button, Modal, Table, Input, Select, …) is too restrictive for the design, re-skin it per route instead of forking, wrapping, or fighting it with utility classes. Write a drop-in replacement in `apps/<app>/ui/` typed against the slot contract (`AkanModalComponent`, or `AkanUiOverrides["<Slot>"]`), composing the framework's headless parts, then bind it in a `page/**/_overrides.tsx` manifest with a single `export default override({ Slot: BrandComponent })`. Overrides cascade down the route tree like layouts (closest ancestor wins). Fetch `get_guideline` with `componentRule` and read the `references/ui/customize` docs page for the slot list and patterns.
+
 ## Review Checklist
 - The instruction points to current docs pages, not removed docs routes.
 - Generated examples use current Akan builder APIs and scanner-friendly filenames.

package/incrementalBuilder.proc.js

@@ -4287,9 +4287,10 @@ class IncrementalBuilderHost {
 // pkgs/@akanjs/devkit/akanApp/akanApp.host.ts
 var backendMsgTypeSet = new Set(["build-route"]);
 var BACKEND_RESTART_DEBOUNCE_MS = 120;
-var BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
+var BACKEND_GRACEFUL_TIMEOUT_MS = 8000;
 var BACKEND_RECOVERY_BASE_DELAY_MS = 1000;
 var BACKEND_RECOVERY_MAX_DELAY_MS = 30000;
+var BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
@@ -4314,6 +4315,8 @@ var shouldRestartBackendByDevPlan = (message) => {
   return message.devPlan.actions.includes("restart-backend");
 };
 var shouldRestartBuilderByDevPlan = (message) => message.devPlan?.actions.includes("restart-builder") ?? false;
+var shouldAbandonBackendRecovery = (attempts, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS) => attempts >= maxAttempts;
+var normalizeBackendReportedGeneration = (generation) => generation >= 0 ? generation : undefined;
 var shouldRestartDevHostByDevPlan = (message) => message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
 var RESTART_ROLE_ORDER = ["server", "shared", "barrel", "config"];
 var generationValue = (generation) => generation ?? -1;
@@ -4562,6 +4565,16 @@ class AkanAppHost {
           this.#replayBuilderState();
           return;
         }
+        if (msg.type === "build-status") {
+          const status = this.#recordBackendBuildStatus({
+            generation: normalizeBackendReportedGeneration(msg.data.generation),
+            ok: msg.data.ok,
+            files: msg.data.files,
+            message: msg.data.message
+          });
+          this.#sendOrQueueBuildStatus(status);
+          return;
+        }
         if (backendMsgTypeSet.has(msg.type))
           this.#sendToBuilder(msg);
       },
@@ -4723,6 +4736,19 @@ class AkanAppHost {
   #scheduleBackendRecovery(reason) {
     if (this.#backendRecoveryTimer || this.#backend)
       return;
+    if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
+      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for a server-side edit to retry.`;
+      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
+      this.logger.error(`[backend-recovery] ${message}`);
+      if (this.#backendStderrTail.length > 0) {
+        this.logger.error(`[backend-recovery] recent backend stderr:
+${this.#backendStderrTail.join(`
+`)}`);
+      }
+      const abandonedStatus = this.#recordBackendBuildStatus({ ok: false, files: [], message });
+      this.#sendOrQueueBuildStatus(abandonedStatus);
+      return;
+    }
     this.#setBackendLifecycleState("recovering", reason);
     const attempt = this.#backendRecoveryAttempts;
     const delay = Math.min(BACKEND_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BACKEND_RECOVERY_MAX_DELAY_MS);
@@ -4771,6 +4797,7 @@ ${this.#backendStderrTail.join(`
     this.#sendToBackend(message);
   }
   async#handleInvalidate(message) {
+    this.#logDevPlan(message);
     if (shouldRestartBuilderByDevPlan(message)) {
       try {
         await this.#restartDevChildren(message);
@@ -4882,12 +4909,16 @@ ${this.#backendStderrTail.join(`
       this.#sendToBackend({ type: "build-status", data: status });
     }
   }
+  #logDevPlan(message) {
+    if (!message.devPlan)
+      return;
+    const { generation, roles, actions, reasonByFile } = message.devPlan;
+    this.logger.verbose(`[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`);
+  }
   async#shouldRestartBackend(message) {
     if (message.kinds.length === 1 && message.kinds[0] === "css")
       return false;
     if (message.devPlan) {
-      const { generation, roles, actions, reasonByFile } = message.devPlan;
-      this.logger.verbose(`[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`);
       const shouldRestart = shouldRestartBackendByDevPlan(message) ?? false;
       if (shouldRestart && message.kinds.includes("code"))
         await this.#backendGraph.refresh();
@@ -17269,14 +17300,18 @@ ${cssText}`).toString(36);
     }
     if (indexSync.changedFiles.length > 0)
       this.#sendBuildStatus("barrel", { generation, ok: true, files });
-    if (kinds.includes("code") && await this.batchMayChangePageKeys(appDir, expandedBatch)) {
+    const rebuildClient = devPlan.actions.includes("rebuild-client");
+    if (kinds.includes("code") && !rebuildClient) {
+      this.#logger.verbose(`client rebuild skipped; devPlan actions=${devPlan.actions.join(",") || "(none)"}`);
+    }
+    if (kinds.includes("code") && rebuildClient && await this.batchMayChangePageKeys(appDir, expandedBatch)) {
       const started = Date.now();
       await this.#app.getPageKeys({ refresh: true });
       this.#logger.verbose(`pageKeys updated, app pageKeys are refreshed (${Date.now() - started}ms)`);
-    } else if (kinds.includes("code") && this.batchTouchesPagesTree(appDir, expandedBatch)) {
+    } else if (kinds.includes("code") && rebuildClient && this.batchTouchesPagesTree(appDir, expandedBatch)) {
       this.#logger.verbose("pageKeys refresh skipped; changed page source cannot add/remove a route key");
     }
-    if (kinds.includes("code") && this.#shouldRebuildCsr()) {
+    if (kinds.includes("code") && rebuildClient && this.#shouldRebuildCsr()) {
       try {
         const started = Date.now();
         await new CsrArtifactBuilder(this.#app).build();
@@ -17287,11 +17322,11 @@ ${cssText}`).toString(36);
         this.#logger.error(`csr-rebundle failed: ${message}`);
         this.#sendBuildStatus("csr", { generation, ok: false, files, message });
       }
-    } else if (kinds.includes("code")) {
+    } else if (kinds.includes("code") && rebuildClient) {
       this.#logger.verbose(`csr-rebundle skipped; set AKAN_DEV_CSR_REBUILD=1 to enable per-save CSR rebuilds`);
     }
     process.send?.(event);
-    if (kinds.includes("code")) {
+    if (kinds.includes("code") && rebuildClient) {
       try {
         const started = Date.now();
         const next = await new PagesBundleBuilder(this.#app).build();
@@ -17326,6 +17361,10 @@ ${cssText}`).toString(36);
           return;
       }
     });
+    process.on("disconnect", () => {
+      this.#logger.warn("host IPC channel closed; exiting builder");
+      process.exit(0);
+    });
     if (this.#watch)
       await this.installWatcher();
     process.send?.({ type: "builder-ready" });

package/index.js

@@ -4285,9 +4285,10 @@ class IncrementalBuilderHost {
 // pkgs/@akanjs/devkit/akanApp/akanApp.host.ts
 var backendMsgTypeSet = new Set(["build-route"]);
 var BACKEND_RESTART_DEBOUNCE_MS = 120;
-var BACKEND_GRACEFUL_TIMEOUT_MS = 3000;
+var BACKEND_GRACEFUL_TIMEOUT_MS = 8000;
 var BACKEND_RECOVERY_BASE_DELAY_MS = 1000;
 var BACKEND_RECOVERY_MAX_DELAY_MS = 30000;
+var BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 var BACKEND_STDERR_TAIL_LIMIT = 40;
 var BUILDER_READY_TIMEOUT_MS = 150000;
 var BUILDER_START_MAX_ATTEMPTS = 3;
@@ -4312,6 +4313,8 @@ var shouldRestartBackendByDevPlan = (message) => {
   return message.devPlan.actions.includes("restart-backend");
 };
 var shouldRestartBuilderByDevPlan = (message) => message.devPlan?.actions.includes("restart-builder") ?? false;
+var shouldAbandonBackendRecovery = (attempts, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS) => attempts >= maxAttempts;
+var normalizeBackendReportedGeneration = (generation) => generation >= 0 ? generation : undefined;
 var shouldRestartDevHostByDevPlan = (message) => message.devPlan?.actions.includes("restart-dev-host") ?? message.kinds.includes("config");
 var RESTART_ROLE_ORDER = ["server", "shared", "barrel", "config"];
 var generationValue = (generation) => generation ?? -1;
@@ -4560,6 +4563,16 @@ class AkanAppHost {
           this.#replayBuilderState();
           return;
         }
+        if (msg.type === "build-status") {
+          const status = this.#recordBackendBuildStatus({
+            generation: normalizeBackendReportedGeneration(msg.data.generation),
+            ok: msg.data.ok,
+            files: msg.data.files,
+            message: msg.data.message
+          });
+          this.#sendOrQueueBuildStatus(status);
+          return;
+        }
         if (backendMsgTypeSet.has(msg.type))
           this.#sendToBuilder(msg);
       },
@@ -4721,6 +4734,19 @@ class AkanAppHost {
   #scheduleBackendRecovery(reason) {
     if (this.#backendRecoveryTimer || this.#backend)
       return;
+    if (shouldAbandonBackendRecovery(this.#backendRecoveryAttempts)) {
+      const message = `Backend exited ${this.#backendRecoveryAttempts} times in a row (${reason}); waiting for a server-side edit to retry.`;
+      this.#setBackendLifecycleState("stopped", `gave up after ${this.#backendRecoveryAttempts} recovery attempts`);
+      this.logger.error(`[backend-recovery] ${message}`);
+      if (this.#backendStderrTail.length > 0) {
+        this.logger.error(`[backend-recovery] recent backend stderr:
+${this.#backendStderrTail.join(`
+`)}`);
+      }
+      const abandonedStatus = this.#recordBackendBuildStatus({ ok: false, files: [], message });
+      this.#sendOrQueueBuildStatus(abandonedStatus);
+      return;
+    }
     this.#setBackendLifecycleState("recovering", reason);
     const attempt = this.#backendRecoveryAttempts;
     const delay = Math.min(BACKEND_RECOVERY_BASE_DELAY_MS * 2 ** attempt, BACKEND_RECOVERY_MAX_DELAY_MS);
@@ -4769,6 +4795,7 @@ ${this.#backendStderrTail.join(`
     this.#sendToBackend(message);
   }
   async#handleInvalidate(message) {
+    this.#logDevPlan(message);
     if (shouldRestartBuilderByDevPlan(message)) {
       try {
         await this.#restartDevChildren(message);
@@ -4880,12 +4907,16 @@ ${this.#backendStderrTail.join(`
       this.#sendToBackend({ type: "build-status", data: status });
     }
   }
+  #logDevPlan(message) {
+    if (!message.devPlan)
+      return;
+    const { generation, roles, actions, reasonByFile } = message.devPlan;
+    this.logger.verbose(`[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`);
+  }
   async#shouldRestartBackend(message) {
     if (message.kinds.length === 1 && message.kinds[0] === "css")
       return false;
     if (message.devPlan) {
-      const { generation, roles, actions, reasonByFile } = message.devPlan;
-      this.logger.verbose(`[dev-plan] generation=${generation} roles=${roles.join(",") || "(none)"} actions=${actions.join(",") || "(none)"} reasons=${Object.keys(reasonByFile).length}`);
       const shouldRestart = shouldRestartBackendByDevPlan(message) ?? false;
       if (shouldRestart && message.kinds.includes("code"))
         await this.#backendGraph.refresh();
@@ -22756,14 +22787,18 @@ class WorkspaceScript extends script("workspace", [
   ApplicationScript,
   LibraryScript,
   PackageScript,
-  CloudScript
+  CloudScript,
+  ContextScript,
+  AgentScript
 ]) {
   async createWorkspace(repoName, appName, {
     dirname: dirname2 = ".",
     installLibs = false,
     init = true,
     registryUrl,
-    owner
+    owner,
+    mcpInstall = true,
+    agentInstall = true
   }) {
     const akanVersion = await this.packageScript.version(null, { log: false });
     const workspace = await this.workspaceRunner.createWorkspace(repoName, appName, {
@@ -22784,6 +22819,10 @@ class WorkspaceScript extends script("workspace", [
       dict: { appName },
       options: { libs: installLibs ? ["util", "shared"] : [] }
     });
+    if (agentInstall)
+      await this.agentScript.agent(workspace, "install", "all", { force: true });
+    if (mcpInstall)
+      await this.contextScript.mcpInstall(workspace, "all", { force: true });
     const gitSpinner = workspace.spinning("Initializing git repository and commit...");
     try {
       await workspace.commit("Initial commit", { init: true });
@@ -22882,13 +22921,22 @@ class WorkspaceCommand extends command("workspace", [WorkspaceScript], ({ public
     desc: "owner of the workspace",
     default: process.env.GITHUB_OWNER,
     nullable: true
-  }).exec(async function(workspaceName, app, dir, libs, init, registry, owner) {
+  }).option("mcpInstall", Boolean, {
+    desc: "Install the Akan MCP server config for Cursor, Claude Code, and Codex? (Recommended)",
+    default: true
+  }).option("agentInstall", Boolean, {
+    flag: "A",
+    desc: "Install Akan agent rules (AGENTS.md, CLAUDE.md, Cursor)? (Recommended)",
+    default: true
+  }).exec(async function(workspaceName, app, dir, libs, init, registry, owner, mcpInstall, agentInstall) {
     const appName = app || "app";
     await this.workspaceScript.createWorkspace(workspaceName.toLowerCase().replace(/ /g, "-"), appName.toLowerCase().replace(/ /g, "-"), {
       dirname: dir,
       installLibs: libs,
       init,
       owner,
+      mcpInstall,
+      agentInstall,
       ...registry ? { registryUrl: registry } : {}
     });
   }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.4.0-rc.0",
+  "version": "2.4.0-rc.1",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -34,7 +34,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.0-rc.0",
+    "akanjs": "2.4.0-rc.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/app/page/styles.css.template

@@ -28,6 +28,18 @@
   --color-error-content: #fafafa;
   --color-open: #27ae60;
   --color-open-content: #fafafa;
+
+  /* Shape & feel — customize these too, not just colors, to make the theme yours.
+     These are daisyUI v5 theme variables; the values below are the neutral defaults.
+     See `akan guideline show cssRule` and https://daisyui.com/docs/themes/ for the full set. */
+  --radius-selector: 1rem; /* checkbox, toggle, badge corner rounding */
+  --radius-field: 0.5rem; /* button, input, select, tab corner rounding */
+  --radius-box: 1rem; /* card, modal, alert corner rounding */
+  --size-selector: 0.25rem; /* base scale (density) for selector controls */
+  --size-field: 0.25rem; /* base scale (density) for field controls */
+  --border: 1px; /* component border width */
+  --depth: 0; /* 1 = subtle 3D depth on components */
+  --noise: 0; /* 1 = grain texture on surfaces */
 }
 
 @plugin "daisyui/theme" {
@@ -51,4 +63,14 @@
   --color-error: #f02020;
   --color-error-content: #ffffff;
   --color-open: #10fc00;
+
+  /* Keep shape & feel consistent with the light theme (usually the same values across modes). */
+  --radius-selector: 1rem;
+  --radius-field: 0.5rem;
+  --radius-box: 1rem;
+  --size-selector: 0.25rem;
+  --size-field: 0.25rem;
+  --border: 1px;
+  --depth: 0;
+  --noise: 0;
 }