@akanjs/cli 2.3.11-rc.6 → 2.3.11-rc.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "2.3.11-rc.6",
+  "version": "2.3.11-rc.8",
   "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.3.11-rc.6",
+    "akanjs": "2.3.11-rc.8",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/templates/appSample/lib/task/task.service.ts

@@ -10,7 +10,7 @@ import * as db from "../db";
 // Convention: <module>.service.ts — business logic orchestration for a database module.
 // Extends serve(db.<module>, depsCallback) from akanjs/service — binds to the DB model, receives DI deps.
 // Auto-generated by akan sync (do not write manually):
-//   getTask(id), createModel(data), updateModel(id, data), removeModel(id),
+//   getTask(id), createTask(data), updateTask(id, data), removeTask(id),
 //   listByStatus(status), searchDocs(text), and all filter+query methods from document.ts.
 // Manual below: lifecycle hooks, custom business logic methods.
 // Registered by akan sync into srv.ts barrel.

package/templates/module/__Model__.Template.tsx

@@ -11,7 +11,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
     content: `
 "use client";
 import { Field, Layout } from "akanjs/ui";
-import { cnst, st, usePage } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
+import { st, usePage } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
 
 interface GeneralProps {
   className?: string;
@@ -23,10 +23,9 @@ export const General = ({ className }: GeneralProps) => {
   return (
     <Layout.Template className={className}>
       <Field.Text
-        label={l("${dict.model}.id")}
-        desc={l("${dict.model}.id.desc")}
-        value={${dict.model}Form.id}
-        onChange={st.do.setIdOn${dict.Model}}
+        label={l("${dict.model}.name")}
+        value={${dict.model}Form.name}
+        onChange={st.do.setNameOn${dict.Model}}
       />
     </Layout.Template>
   );

package/templates/module/__Model__.Unit.tsx

@@ -17,7 +17,7 @@ export const Card = ({ ${dict.model}, href }: ModelProps<"${dict.model}", cnst.L
   const { l } = usePage();
   return (
     <Link href={href} className="w-full">
-      <div>{l("${dict.model}.id")}:{${dict.model}.id}</div>
+      <div>{l("${dict.model}.name")}: {${dict.model}.name}</div>
     </Link>
   );
 };

package/templates/module/__Model__.View.tsx

@@ -20,7 +20,7 @@ export const General = ({ className, ${dict.model} }: GeneralProps) => {
   const { l } = usePage();
   return (
     <div className={clsx("w-full", className)}>
-      <div>{l("${dict.model}.id")}: {${dict.model}.id}</div>
+      <div>{l("${dict.model}.name")}: {${dict.model}.name}</div>
     </div>
   );
 };

package/templates/module/__Model__.Zone.tsx

@@ -11,7 +11,9 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
     content: `
 "use client";
 import { Load } from "akanjs/ui";
-import { type cnst, ${dict.Model} } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
+// Alias the domain namespace so the Card/View exports below never collide with the model name
+// (a model literally named "card" or "view" would otherwise shadow this import).
+import { type cnst, ${dict.Model} as ${dict.Model}Domain } from "@${scanInfo?.type ?? "apps"}/${dict.sysName}/client";
 import type { ClientInit, ClientView, SliceMeta } from "akanjs/fetch";
 
 interface CardProps {
@@ -25,7 +27,7 @@ export const Card = ({ className, init, slice }: CardProps) => {
       className={className}
       init={init}
       renderItem={(${dict.model}) => (
-        <${dict.Model}.Unit.Card key={${dict.model}.id} href={\`/${dict.model}/\${${dict.model}.id}\`} ${dict.model}={${dict.model}} />
+        <${dict.Model}Domain.Unit.Card key={${dict.model}.id} href={\`/${dict.model}/\${${dict.model}.id}\`} ${dict.model}={${dict.model}} />
       )}
     />
   );
@@ -36,7 +38,7 @@ interface ViewProps {
   view: ClientView<"${dict.model}", cnst.${dict.Model}>;
 }
 export const View = ({ view }: ViewProps) => {
-  return <Load.View view={view} renderView={(${dict.model}) => <${dict.Model}.View.General ${dict.model}={${dict.model}} />} />;
+  return <Load.View view={view} renderView={(${dict.model}) => <${dict.Model}Domain.View.General ${dict.model}={${dict.model}} />} />;
 };
 `,
   };

package/templates/module/__model__.constant.ts

@@ -10,11 +10,12 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
 import { via } from "akanjs/constant";
 
 export class ${dict.Model}Input extends via((field) => ({
+  name: field(String),
 })) {}
 
 export class ${dict.Model}Object extends via(${dict.Model}Input, (field) => ({})) {}
 
-export class Light${dict.Model} extends via(${dict.Model}Object, [] as const, (resolve) => ({})) {}
+export class Light${dict.Model} extends via(${dict.Model}Object, ["name"] as const, (resolve) => ({})) {}
 
 export class ${dict.Model} extends via(${dict.Model}Object, Light${dict.Model}, (resolve) => ({})) {}
 

package/templates/module/__model__.dictionary.ts

@@ -24,7 +24,9 @@ export const dictionary = modelDictionary(["en", "ko"])
   .of((t) =>
     t(["${modelLabelEn}", "${modelLabelKo}"]).desc(["${modelDescEn}", "${modelDescKo}"])
   )
-  .model<${dict.Model}>((t) => ({}))
+  .model<${dict.Model}>((t) => ({
+    name: t(["Name", "이름"]),
+  }))
   .insight<${dict.Model}Insight>((t) => ({}))
   .slice<${dict.Model}Slice>((fn) => ({
     inPublic: fn(["${dict.Model} In Public", "${dict.Model} 공개"]).arg((t) => ({})),

package/templates/workspaceRoot/.gitignore.template

@@ -67,7 +67,9 @@ local.properties
 **/public/fallback-*.js
 **/public/libs
 **/private/libs
+**/public/firebase-messaging-sw.js
 
+**/android/keystore.properties
 **/vendor/bundle/
 **/ios/App/App/public
 **/ios/App/App/Podfile.lock

package/templates/workspaceRoot/AGENTS.md.template

@@ -28,7 +28,6 @@ Common generated files include:
 - `*/lib/cnst.ts`
 - `*/lib/db.ts`
 - `*/lib/dict.ts`
-- `*/lib/option.ts`
 - `*/lib/sig.ts`
 - `*/lib/srv.ts`
 - `*/lib/st.ts`
@@ -112,6 +111,12 @@ akan test <%= appName %>
 akan build <%= appName %>
 ```
 
+**Verify endpoints with signal tests, not raw HTTP.** The canonical way to check a query/mutation/slice
+contract is an in-memory signal test (`<model>.signal.test.ts`), using the test fetch harness
+(`getOrSetupSignalTestFetch`) — it is fast, needs no running server, and exercises `fetch.*`, `view/edit/merge<Model>`,
+and slice `init`/`list`/`insight` directly. Prefer it over `curl`: the dev gateway locale-prefixes routes (`/en/...`),
+so hand-rolled HTTP calls against a raw path can redirect unexpectedly. See `akan test <%= appName %>`.
+
 ### Other Frequently Used Commands
 
 ```bash
@@ -230,6 +235,7 @@ 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>` |
 | 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>` |
@@ -247,6 +253,7 @@ final fallback when no CLI command covers the change.
 | 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 |
 | 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 |
 
 ## Generated File Tracker (Quick Reference)
 
@@ -257,7 +264,6 @@ These files are regenerated by `akan sync` and overwritten on every sync. **Do n
 | `*/lib/cnst.ts` | All `*/lib/*/**.constant.ts` | Barrel for all constants |
 | `*/lib/db.ts` | All `*/lib/<model>/*.document.ts` | Barrel for all document models |
 | `*/lib/dict.ts` | All `*/lib/*/**.dictionary.ts` | Barrel for all dictionaries |
-| `*/lib/option.ts` | Generated option helpers | Option helper entry |
 | `*/lib/sig.ts` | All `*/lib/**/**.signal.ts` | Barrel for all signals |
 | `*/lib/srv.ts` | All `*/lib/**/**.service.ts` | Barrel for all services |
 | `*/lib/st.ts` | All `*/lib/**/**.store.ts` | Barrel for all stores |
@@ -338,6 +344,10 @@ Three patterns: injecting an **external adapter** (`use<>()`), another **module'
 or a **predefined framework adapter** (`plug()`). A field named `<refName>Service` resolves to the service
 registered under `<refName>` — the `Service`/`Signal` suffix is required and stripped to derive the lookup key.
 
+> `apps/<app>/lib/option.ts` is a **user-owned** file scaffolded once — edit it to register adapters/DI. Unlike the
+> barrels (`cnst.ts`, `db.ts`, `srv.ts`, …) it is **not** overwritten by `akan sync`, so your `.use(...)` registrations
+> are safe.
+
 **A. Adapter injection via `use<>()` (for external clients / global singletons)**
 
 ```typescript
@@ -411,12 +421,19 @@ store's generated `upload<Field>On<Model>(fileList)` action handle the upload.
 
 A Slice is a named, filtered data view. Add file entries and connect from a page.
 
+> **Silent failure — a slice `exec` must return a query descriptor, never an executed list.**
+> Return `this.taskService.queryByStatuses(...)` (the `query<Filter>` builder), **not**
+> `this.taskService.listByStatuses(...)` / `listBy...(...)` (which returns a `Promise<Doc[]>`).
+> Returning an array type-checks but throws at runtime during insight aggregation with the opaque
+> `Error: Unknown document field path: 0`. If you see that error, your slice is returning a list, not a query.
+
 ```typescript
 // 1. apps/<app>/lib/<model>/<model>.signal.ts — Define the slice
 export class TaskSlice extends slice(srv.task, (init) => ({
   inTodo: init()
     .search("statuses", [cnst.TaskStatus])
     .exec(function (statuses?) {
+      // ✅ query<Filter> — a query descriptor.  ❌ listByStatuses(...) returns an array and fails at runtime.
       return this.taskService.queryByStatuses(statuses ?? ["todo", "inProgress"]);
     }),
 })) {}
@@ -595,6 +612,41 @@ For each business question, follow this chain:
 | What client state is shared? | `store.ts` — `store()` with auto-generated form/insight state + custom actions |
 | What should users see? | `View.tsx` + `Zone.tsx` (detail/container), `Template.tsx` (forms), `Unit.tsx` (cards), `Util.tsx` (buttons) |
 
+## Modeling & Query Gotchas
+
+A short list of things the type system does not always catch:
+
+- **Slices return a query, not a list.** A slice `exec` must return `this.<model>Service.query<Filter>(...)`, never
+  a `list<Filter>(...)` / `listBy...(...)` array. Returning an array type-checks but fails at runtime with
+  `Unknown document field path: 0`. (See Recipe 3.)
+- **Custom endpoint names must not collide with generated CRUD.** `create/update/remove/view/edit/merge<Model>`
+  already exist. A collision can build green and fail only at runtime — pick a distinct verb.
+- **Numbers are `Int` or `Float`, never `Number`.** `field(Number)` / `.body("x", Number)` fail to typecheck. Use
+  `Int` for counts, `Float` for decimals.
+- **Array fields use `field([T])`.** e.g. `tags: field([String])`, `images: field([File])` — not `field(String)` with
+  a suffix.
+- **Reading a secret field needs an explicit select.** `field(...).secret()` values (e.g. `passwordHash`) are stripped
+  from query results by default. Fetch them with `{ select: { <field>: true } }`, e.g.
+  `this.userModel.pickById(id, { select: { passwordHash: true } })`.
+
+## Current User, Guards & Auth-Gated Pages
+
+Built-in user authentication (session / JWT / password hashing) ships as a separate Akan auth library, not in the
+core framework. The core framework gives you the composition points below; wire the auth library through them.
+
+- **Guards** attach at the signal declaration, not per-method:
+  `endpoint(srv.task, { guards: { root: SignedIn } }, ({ mutation }) => ({...}))` or
+  `slice(srv.task, { guards: { root: SignedIn, get: Public, cru: Public } }, ...)`. `Public` always allows; other
+  guards implement the `Guard` interface in `srvkit/` (server-only) and read the request context.
+- **Read the current user inside a custom endpoint** by injecting an `InternalArg` with `.with(...)`:
+  `mutation(cnst.Task).with(CurrentUserId).exec(async function (currentUserId) { ... })`. The `Guard` /
+  `InternalArg` helpers live in `srvkit/` and read `context.getHttpContext().req.user`.
+- **Auto-generated CRUD and `serve()` service methods / lifecycle hooks do not receive session context.** If an
+  operation needs the acting user, expose a custom endpoint that takes it via `.with(CurrentUserId)` — never trust a
+  client-supplied user id.
+- **SSR auth-gated pages: guard at the layout.** Check the session in the `_layout.tsx` loader and redirect when it is
+  absent, so nested pages never render for signed-out users.
+
 ## Auto-Generated API Reference
 
 akan sync automatically generates APIs across all layers. Only write custom logic — never hand-write what the framework generates.
@@ -618,7 +670,7 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 |---------------|-------------|
 | `this.<model>Model` | Auto-injected model adaptor |
 | `get<Model>(id)`, `load<Model>(id)` | Single document lookup |
-| `createModel(data)`, `updateModel(id, data)`, `removeModel(id)` | CRUD operations |
+| `create<Model>(data)`, `update<Model>(id, data)`, `remove<Model>(id)` | CRUD operations — named after the model, e.g. `createTask`/`updateTask`/`removeTask` (there is no literal `createModel`) |
 | `list<Query>(args)`, `find<Query>(args)`, `pick<Query>(args)` | Filter-based queries |
 | `exists<Query>(args)`, `count<Query>(args)`, `insight<Query>(args)` | Filter-based helpers |
 | `_preCreate`, `_postCreate`, `_preUpdate`, `_postUpdate`, `_preRemove`, `_postRemove` | Lifecycle hooks (override to add logic) |

package/templates/workspaceRoot/biome.json.template

@@ -147,6 +147,10 @@
       "includes": ["**/*.constant.ts", "**/*.document.ts", "**/*.service.ts", "**/*.store.ts"],
       "plugins": ["./node_modules/@akanjs/devkit/lint/no-js-private-class-method.grit"]
     },
+    {
+      "includes": ["**/*.signal.ts"],
+      "plugins": ["./node_modules/@akanjs/devkit/lint/no-redeclare-predefined-endpoint.grit"]
+    },
     {
       "includes": [
         "**/*.constant.ts",

package/templates/workspaceRoot/docs/GENERATED.md.template

@@ -17,7 +17,6 @@ sync or build can overwrite local changes.
 | `apps/*/lib/cnst.ts` | Re-exports constants and model shapes from module `*.constant.ts` files. |
 | `apps/*/lib/db.ts` | Re-exports database models from module `*.document.ts` files. |
 | `apps/*/lib/dict.ts` | Re-exports dictionaries from module `*.dictionary.ts` files. |
-| `apps/*/lib/option.ts` | Re-exports generated option helpers. |
 | `apps/*/lib/srv.ts` | Re-exports services from module `*.service.ts` files. |
 | `apps/*/lib/sig.ts` | Re-exports endpoints, slices, and internals from module `*.signal.ts` files. |
 | `apps/*/lib/st.ts` | Re-exports stores from module `*.store.ts` files. |

package/templates/workspaceRoot/package.json.template

@@ -13,9 +13,9 @@
     "agent:setup": "akan agent install all --force",
     "agent:doctor": "akan doctor --strict --format json",
     "agent:context": "akan context --format json",
-    "agent:mcp:readonly": "akan mcp-install cursor --mode readonly --force",
-    "agent:mcp:plan": "akan mcp-install cursor --mode plan --force",
-    "agent:mcp:apply": "akan mcp-install cursor --mode apply --force",
+    "agent:mcp:readonly": "akan mcp-install all --mode readonly --force",
+    "agent:mcp:plan": "akan mcp-install all --mode plan --force",
+    "agent:mcp:apply": "akan mcp-install all --mode apply --force",
     "agent:workflows": "akan workflow list",
     "agent:sample:context": "akan context --format markdown --app <%= appName %> --module project",
     "agent:sample:service": "akan create-service billing <%= appName %> --format json",