@akanjs/cli 2.3.9-rc.0 → 2.3.9-rc.10

package/package.json

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

package/templates/appSample/common/formatters.ts

@@ -7,7 +7,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Convention: common/ folder — only pure functions that run on both server and client.
 // Cannot import window, Bun, process.env, or any runtime-specific API.
 // Naming: camelCase .ts, file name = primary export name.
-// Scanned by akan scan into common/index.ts barrel automatically.
+// Scanned by akan sync into common/index.ts barrel automatically.
 
 export function trimString(str: string, maxLength = 50, suffix = "...") {
   if (str.length <= maxLength) return str;

package/templates/appSample/common/validators.ts

@@ -7,7 +7,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Convention: common/ folder — only pure functions that run on both server and client.
 // Cannot import window, Bun, process.env, or any runtime-specific API.
 // Naming: camelCase .ts, file name = primary export name.
-// Scanned by akan scan into common/index.ts barrel automatically.
+// Scanned by akan sync into common/index.ts barrel automatically.
 
 export function isValidEmail(email: string): boolean {
   const emailRegex = /^[^s@]+@[^s@]+.[^s@]+$/;

package/templates/appSample/lib/_noti/noti.dictionary.ts

@@ -9,7 +9,7 @@ import type { NotiEndpoint } from "./noti.signal";
 // Uses serviceDictionary(["en", "ko"]) from akanjs/dictionary — the framework convention for service dictionaries.
 // Unlike modelDictionary, no model/lightModel/query/sort/enum sections (service modules have no DB model).
 // Sections: .endpoint() for signal endpoint names, .translate() for UI messages.
-// Registered by akan scan into dict.ts barrel.
+// Registered by akan sync into dict.ts barrel.
 
 export const dictionary = serviceDictionary(["en", "ko"])
   .endpoint<NotiEndpoint>((fn) => ({

package/templates/appSample/lib/_noti/noti.service.ts

@@ -8,7 +8,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Extends serve("noti" as const, ...) — named service (string literal), no DB model binding.
 // DB modules use serve(db.<module>, ...); service modules use serve("<name>" as const, ...).
 // DI deps available: { service, use, signal, plug, env, memory }.
-// Registered by akan scan into srv.ts barrel.
+// Registered by akan sync into srv.ts barrel.
 
 export class NotiService extends serve("noti" as const, () => ({})) {}
 

package/templates/appSample/lib/_noti/noti.signal.ts

@@ -10,7 +10,7 @@ import * as srv from "../srv";
 // Extends endpoint(srv.<module>, ...) — pubsub endpoint for real-time server→client communication.
 // pubsub() is the Akan.js convention for publish-subscribe: server publishes, all connected clients receive.
 // Client subscribes via fetch.subscribeSend((data) => { ... }).
-// Registered by akan scan into sig.ts barrel.
+// Registered by akan sync into sig.ts barrel.
 
 export class NotiInternal extends internal(srv.noti, () => ({})) {}
 

package/templates/appSample/lib/_noti/noti.store.ts

@@ -9,7 +9,7 @@ import { store } from "akanjs/store";
 // Extends store("noti" as const, ...) — named store (string literal), no signal binding.
 // DB modules use store(sig.<module>, ...); service modules use store("<name>" as const, ...).
 // State definitions use direct property assignment. Actions use this.set() / this.get().
-// Registered by akan scan into st.ts barrel.
+// Registered by akan sync into st.ts barrel.
 
 export class NotiStore extends store("noti" as const, () => ({
   notiList: [] as { id: string; type: string; message: string; sentAt: Dayjs }[],

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

@@ -28,7 +28,7 @@ Every database module in Akan.js follows this layered architecture:
 
 ## Convention: scan-registered barrels
 
-akan scan auto-discovers each file and registers it in the corresponding barrel:
+akan sync auto-discovers each file and registers it in the corresponding barrel:
 cnst.ts, db.ts, dict.ts, srv.ts, sig.ts, st.ts
 
 ## Related Modules

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

@@ -12,7 +12,7 @@ import { WorkHistory } from "../__scalar/workHistory/workHistory.constant";
 // Scalars are embedded via field([ScalarType], ...) — see WorkHistory embedding below.
 // Layer order: enum → Input → Object → Light → Full.
 //   Input = user-provided fields; Object = Input + system fields + embedded scalars; Light = subset for list views; Full = Object + Light.
-// Registered by akan scan into cnst.ts barrel.
+// Registered by akan sync into cnst.ts barrel.
 
 export class TaskStatus extends enumOf("taskStatus", [
   "todo",

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

@@ -11,7 +11,7 @@ import type { TaskFilter } from "./task.document";
 // Uses modelDictionary(["en", "ko"]) from akanjs/dictionary — the framework convention for bilingual module dictionaries.
 // Sections: .of() module name, .model() field labels, .lightModel() list-view labels, .query() filter labels,
 // .sort() labels, .enum() value labels, .error() messages (thrown via Err()), .translate() UI messages (used in store via msg.xxx).
-// Registered by akan scan into dict.ts barrel.
+// Registered by akan sync into dict.ts barrel.
 
 export const dictionary = modelDictionary(["en", "ko"])
   .of((t) =>

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

@@ -10,10 +10,10 @@ import * as cnst from "../cnst";
 // ===== task.document.ts =====
 // Convention: <module>.document.ts — the database query and persistence layer.
 // Import from/into/by from akanjs/document — the framework convention for Filter, Document, and Model classes.
-// Filter defines query/sort conditions (auto-generates List/Find/Pick/Exists/Count methods via akan scan).
+// Filter defines query/sort conditions (auto-generates List/Find/Pick/Exists/Count methods via akan sync).
 // Document defines chainable per-document methods (e.g., task.start().save()).
 // Model = into(Document, Filter, cnst.module, ...) — collection-level operations, schema hooks.
-// Registered by akan scan into db.ts barrel.
+// Registered by akan sync into db.ts barrel.
 
 export class TaskFilter extends from(cnst.Task, (filter) => ({
   query: {
@@ -34,7 +34,7 @@ export class Task extends by(cnst.Task) {
   start() {
     if (this.status !== "todo") throw new Err("task.error.cannotStartFromNonTodo");
     this.status = "inProgress";
-    this.workHistory.push({ action: "completed", at: dayjs(), note: "" });
+    this.workHistory.push({ action: "started", at: dayjs(), note: "" });
     return this;
   }
 

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

@@ -9,11 +9,11 @@ import * as db from "../db";
 // ===== task.service.ts =====
 // 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 scan (do not write manually):
+// Auto-generated by akan sync (do not write manually):
 //   getTask(id), createModel(data), updateModel(id, data), removeModel(id),
 //   listByStatus(status), searchDocs(text), and all filter+query methods from document.ts.
 // Manual below: lifecycle hooks, custom business logic methods.
-// Registered by akan scan into srv.ts barrel.
+// Registered by akan sync into srv.ts barrel.
 
 export class TaskService extends serve(db.task, () => ({})) {
   // Lifecycle hook: runs before every document creation.

package/templates/appSample/lib/task/task.signal.spec.ts

@@ -0,0 +1,70 @@
+import type { AppInfo, LibInfo } from "akanjs";
+
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { appName: string }) {
+  return `import { expect } from "bun:test";
+import type { DocumentModel } from "akanjs/constant";
+import { getOrSetupSignalTestFetch, sampleOf } from "akanjs/test";
+
+import * as cnst from "../cnst";
+import type { fetch as appFetch } from "../useServer";
+
+type AppFetch = typeof appFetch;
+
+const getFetch = async () => await getOrSetupSignalTestFetch<AppFetch>();
+
+export interface TaskAgent {
+  task: cnst.Task;
+  fetch: AppFetch;
+  taskInput: DocumentModel<cnst.TaskInput>;
+}
+
+export const createTask = async (overrides: Partial<DocumentModel<cnst.TaskInput>> = {}): Promise<TaskAgent> => {
+  const fetch = await getFetch();
+  const taskInput = {
+    ...sampleOf(cnst.TaskInput),
+    ...overrides,
+  };
+
+  const task = await fetch.createTask(taskInput);
+
+  expect(task).toMatchObject({
+    title: taskInput.title,
+    content: taskInput.content,
+    status: "todo",
+  });
+  expect(task.workHistory.map((entry) => entry.action)).toEqual(["created"]);
+
+  return {
+    task,
+    fetch,
+    taskInput,
+  };
+};
+
+export const getStartedTask = async (overrides: Partial<DocumentModel<cnst.TaskInput>> = {}): Promise<TaskAgent> => {
+  const agent = await createTask(overrides);
+  const task = await agent.fetch.startTask(agent.task.id);
+
+  expect(task.status).toBe("inProgress");
+  expect(task.workHistory.map((entry) => entry.action)).toEqual(["created", "started"]);
+
+  return {
+    ...agent,
+    task,
+  };
+};
+
+export const getCompletedTask = async (overrides: Partial<DocumentModel<cnst.TaskInput>> = {}): Promise<TaskAgent> => {
+  const agent = await getStartedTask(overrides);
+  const task = await agent.fetch.completeTask(agent.task.id);
+
+  expect(task.status).toBe("completed");
+  expect(task.workHistory.map((entry) => entry.action)).toEqual(["created", "started", "completed"]);
+
+  return {
+    ...agent,
+    task,
+  };
+};
+`;
+}

package/templates/appSample/lib/task/task.signal.test.ts

@@ -0,0 +1,20 @@
+import type { AppInfo, LibInfo } from "akanjs";
+
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { appName: string }) {
+  return `import { describe, expect, test } from "bun:test";
+import { configureSignalTest } from "akanjs/test";
+
+import * as taskSpec from "./task.signal.spec";
+
+configureSignalTest({ databaseMode: "memory" });
+
+describe("Task signal smoke", () => {
+  test("exposes custom task mutations over fetch", async () => {
+    const { task } = await taskSpec.getCompletedTask({ title: "Signal smoke task" });
+
+    expect(task.status).toBe("completed");
+    expect(task.workHistory.map((entry) => entry.action)).toEqual(["created", "started", "completed"]);
+  });
+});
+`;
+}

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

@@ -12,12 +12,12 @@ import * as srv from "../srv";
 // endpoint() receives: { query, mutation, pubsub, message } — each typed with the model's return type.
 // .param() = URL path parameter, .body() = request body, .search() = query string.
 //
-// Auto-generated by akan scan (do not write manually):
+// Auto-generated by akan sync (do not write manually):
 //   viewTask(id) — fetch single task for detail view
 //   editTask(id) — fetch task for edit view
 //   mergeTask(id, data) — create/update task
 // Manual endpoints below: only define endpoints that need custom business logic.
-// Registered by akan scan into sig.ts barrel.
+// Registered by akan sync into sig.ts barrel.
 
 export class TaskInternal extends internal(srv.task, ({ interval }) => ({})) {}
 

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

@@ -8,13 +8,13 @@ import { fetch, msg, sig } from "../useClient";
 // ===== task.store.ts =====
 // Convention: <module>.store.ts — client-side state management for a database module.
 // Extends store(sig.<module>, ...) from akanjs/store — binds to the signal to auto-generate model states/actions.
-// Auto-generated by akan scan (do not write manually):
+// Auto-generated by akan sync (do not write manually):
 //   taskForm — form state bound to model fields (create + edit)
 //   setTitleOnTask, setContentOnTask, setDueOnTask — auto-setters for form fields
 //   createTask(data), updateTask(id, data), removeTask(id) — CRUD actions
 //   task (cached model), taskLoading, taskModal — model display states
 // Manual below: custom actions wrapping auto-generated fetch with toast feedback.
-// Registered by akan scan into st.ts barrel.
+// Registered by akan sync into st.ts barrel.
 
 export class TaskStore extends store(sig.task, () => ({})) {
   async startTask(taskId: string) {

package/templates/appSample/srvkit/AuthGuard.ts

@@ -10,7 +10,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // Implements the Guard interface from akanjs/signal.
 // Guards are applied at endpoint/slice declaration: { guards: { root: SignedIn } }.
 // Naming: PascalCase .ts, static name property matches the guard identifier.
-// Scanned by akan scan into srvkit/index.ts barrel automatically.
+// Scanned by akan sync into srvkit/index.ts barrel automatically.
 
 export class SignedIn implements Guard {
   static name = "SignedIn";

package/templates/appSample/srvkit/SessionInternalArg.ts

@@ -11,7 +11,7 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { a
 // InternalArg is an auto-injected argument for resolveField/endpoint .with() chains.
 // Appended to a query/mutation via: .with(CurrentUserId, { nullable: true }).exec(...)
 // Naming: PascalCase .ts, class name = arg identifier.
-// Scanned by akan scan into srvkit/index.ts barrel automatically.
+// Scanned by akan sync into srvkit/index.ts barrel automatically.
 
 export class CurrentUserId implements InternalArg<string | null> {
   getArg(context: SignalContext): string | null {

package/templates/appSample/ui/GlobalLoading.tsx

@@ -10,7 +10,7 @@ import { clsx } from "akanjs/client";
 // ===== GlobalLoading.tsx =====
 // Convention: ui/ folder — reusable visual components. PascalCase .tsx, "use client" directive.
 // File name = exported component name.
-// Scanned by akan scan into ui/index.ts barrel automatically.
+// Scanned by akan sync into ui/index.ts barrel automatically.
 
 interface GlobalLoadingProps {
   className?: string;

package/templates/appSample/ui/QuantityControl.tsx

@@ -10,7 +10,7 @@ import { clsx } from "akanjs/client";
 // ===== QuantityControl.tsx =====
 // Convention: ui/ folder — reusable visual components. PascalCase .tsx, "use client" directive.
 // File name = exported component name.
-// Scanned by akan scan into ui/index.ts barrel automatically.
+// Scanned by akan sync into ui/index.ts barrel automatically.
 
 interface QuantityControlProps {
   className?: string;

package/templates/appSample/webkit/useDebounce.ts

@@ -11,7 +11,7 @@ import { useEffect, useState } from "react";
 // Convention: webkit/ folder — browser-only hooks; "use client" directive required.
 // useEffect/useState are React client-side primitives that only work in the browser.
 // Naming: camelCase .ts, file name = primary export name.
-// Scanned by akan scan into webkit/index.ts barrel automatically.
+// Scanned by akan sync into webkit/index.ts barrel automatically.
 
 export function useDebounce<T>(value: T, delay = 300): T {
   const [debouncedValue, setDebouncedValue] = useState<T>(value);

package/templates/lib/useClient.ts

@@ -1,9 +1,6 @@
 import type { AppInfo, LibInfo } from "akanjs";
 
-export default function getContent(
-  scanInfo: AppInfo | LibInfo | null,
-  dict: { [key: string]: string } = {},
-) {
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: { [key: string]: string } = {}) {
   return `
 import { makePageProto, registerClientRuntime } from "akanjs/client";
 import { FetchClient } from "akanjs/fetch";

package/templates/module/__Model__.Unit.tsx

@@ -5,10 +5,7 @@ interface Dict {
   model: string;
   sysName: string;
 }
-export default function getContent(
-  scanInfo: AppInfo | LibInfo | null,
-  dict: Dict,
-) {
+export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dict) {
   return {
     filename: `${dict.Model}.Unit.tsx`,
     content: `

package/templates/module/__model__.constant.ts

@@ -10,7 +10,6 @@ export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dic
 import { via } from "akanjs/constant";
 
 export class ${dict.Model}Input extends via((field) => ({
-  field: field(String).optional(),
 })) {}
 
 export class ${dict.Model}Object extends via(${dict.Model}Input, (field) => ({})) {}

package/templates/module/__model__.dictionary.ts

@@ -3,9 +3,17 @@ import type { AppInfo, LibInfo } from "akanjs";
 interface Dict {
   Model: string;
   model: string;
+  modelDescEn?: string;
+  modelDescKo?: string;
+  modelLabelEn?: string;
+  modelLabelKo?: string;
   sysName: string;
 }
 export default function getContent(scanInfo: AppInfo | LibInfo | null, dict: Dict) {
+  const modelLabelEn = dict.modelLabelEn ?? dict.Model;
+  const modelLabelKo = dict.modelLabelKo ?? dict.Model;
+  const modelDescEn = dict.modelDescEn ?? `Manage ${modelLabelEn.toLowerCase()}.`;
+  const modelDescKo = dict.modelDescKo ?? `${modelLabelKo}을 관리합니다.`;
   return `
 import { modelDictionary } from "akanjs/dictionary";
 
@@ -14,11 +22,9 @@ import type { ${dict.Model}Endpoint, ${dict.Model}Slice } from "./${dict.model}.
 
 export const dictionary = modelDictionary(["en", "ko"])
   .of((t) =>
-    t(["${dict.Model}", "${dict.Model}"]).desc(["${dict.Model} description", "${dict.Model} 설명"])
+    t(["${modelLabelEn}", "${modelLabelKo}"]).desc(["${modelDescEn}", "${modelDescKo}"])
   )
-  .model<${dict.Model}>((t) => ({
-    field: t(["Field", "필드"]).desc(["Field description", "필드 설명"]),
-  }))
+  .model<${dict.Model}>((t) => ({}))
   .insight<${dict.Model}Insight>((t) => ({}))
   .slice<${dict.Model}Slice>((fn) => ({
     inPublic: fn(["${dict.Model} In Public", "${dict.Model} 공개"]).arg((t) => ({})),

package/templates/workspaceRoot/.cursor/rules/{akan-scan-conventions.mdc.template → akan-sync-conventions.mdc.template}

@@ -1,10 +1,10 @@
 ---
-description: scanSync-enforced Akan app/lib layout and generated index conventions
+description: sync-enforced Akan app/lib layout and generated index conventions
 globs: apps/**/*,libs/**/*
 alwaysApply: false
 ---
 
-# Akan Scan Conventions
+# Akan Sync Conventions
 
 - `apps/<appName>` root may only contain these files: `akan.app.json`, `akan.config.ts`, `capacitor.config.ts`, `client.ts`, `main.ts`, `package.json`, `server.ts`, `tsconfig.json`.
 - `apps/<appName>` root may only contain these folders: `.akan`, `android`, `common`, `env`, `ios`, `lib`, `page`, `private`, `public`, `script`, `srvkit`, `ui`, `webkit`.
@@ -15,5 +15,5 @@ alwaysApply: false
 - Service module UI files are limited to `<Service>.Util.tsx` and `<Service>.Zone.tsx`.
 - Scalar module UI files are limited to `<Scalar>.Template.tsx` and `<Scalar>.Unit.tsx`.
 - Module `*.test.ts`, `*.test.tsx`, `*.spec.ts`, and `*.spec.tsx` files are allowed.
-- `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and module `lib/**/index.ts` files are generated by scanSync; do not hand-edit or track them.
+- `ui/index.ts`, `webkit/index.ts`, `srvkit/index.ts`, `common/index.ts`, and module `lib/**/index.ts` files are generated by `akan sync`; do not hand-edit or track them.
 - Generated facet indexes export only 1-depth files/folders with `export * from "./name";`.

package/templates/workspaceRoot/.cursor/rules/akan.mdc.template

@@ -15,6 +15,18 @@ alwaysApply: true
 - Do not hand-edit generated Akan files such as `akan.app.json`, `client.ts`, `server.ts`, generated facet indexes,
   `lib/cnst.ts`, `lib/dict.ts`, `lib/db.ts`, `lib/srv.ts`, `lib/st.ts`, `lib/sig.ts`, `lib/useClient.ts`, or
   `lib/useServer.ts`.
+- Prefer Akan MCP workflows before direct source edits: use `akan mcp --mode plan` for workflow discovery and
+  planning, then `akan mcp --mode apply` only for allowlisted apply, validation, and repair tools.
+- If `plan_workflow` returns `planPath` or `next.tool=apply_workflow`, call `apply_workflow({ planPath })` before
+  editing source files directly.
+- After `apply_workflow`, run `run_validation` with `validationTarget` when present; otherwise use `applyReportPath`.
+- Direct source edits are denied when an allowlisted Akan workflow or repair tool can perform the change.
+- Direct edits are fallback only after `list_workflows`/`explain_workflow` show no matching workflow, or after
+  `apply_workflow` reports unsupported/no-op/failed diagnostics that require manual action.
+- For compound requests, split the request into workflows and apply each `planPath` in order, such as `create-module`
+  followed by `add-field`.
+- If generated output is stale or broken, update the owning source file and run `akan repair generated` or
+  `akan sync <app-or-lib>` instead of patching generated files.
 - For new domain behavior, inspect sibling `constant`, `dictionary`, `signal`, `document`, `service`, `store`, and UI
   module files before changing shape.
 - Update `*.abstract.md` when business invariants, workflows, or public behavior change. Do not update it for