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

package/.build-stamp

@@ -1 +1 @@
-8978ecc29bed4933e395dd03d27e5e3f76ba864e8e303fd3500ea45c948ca8de
+5f4cb4962f5027c269281e372337f2349defcfca97ac7c862b17e452e9749c5d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/cli",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-alpha.3",
   "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": "3.0.0-alpha.1",
+    "akanjs": "3.0.0-alpha.3",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/templates/lib/db.ts

@@ -16,7 +16,9 @@ ${databaseModules.map((module) => `import * as ${module}Db from "./${module}/${m
 ${libs.map((lib) => `export { db as ${lib} } from "@libs/${lib}/server";`).join("\n")}
 
 ${databaseModules.map((module) => `class ${capitalize(module)}Input extends by(cnst.${capitalize(module)}Input) {}`).join("\n")}
+${databaseModules.map((module) => `class ${capitalize(module)}Insight extends by(cnst.${capitalize(module)}Insight) {}`).join("\n")}
 ${databaseModules.length ? `export type { ${databaseModules.map((module) => `${capitalize(module)}Input`).join(", ")} };` : ""}
+${databaseModules.length ? `export type { ${databaseModules.map((module) => `${capitalize(module)}Insight`).join(", ")} };` : ""}
 
 ${scalarModules.map((module) => `export type * from "./__scalar/${module}/${module}.document";`).join("\n")}
 ${databaseModules.map((module) => `export type * from "./${module}/${module}.document";`).join("\n")}
@@ -24,7 +26,7 @@ ${databaseModules.map((module) => `export type * from "./${module}/${module}.doc
 ${databaseModules
   .map((module) => {
     const names = { Module: module.charAt(0).toUpperCase() + module.slice(1) };
-    return `export const ${module} = DatabaseRegistry.buildModel("${module}" as const, ${names.Module}Input, ${module}Db.${names.Module}, ${module}Db.${names.Module}Model, cnst.${names.Module}, cnst.${names.Module}Insight, ${module}Db.${names.Module}Filter);`;
+    return `export const ${module} = DatabaseRegistry.buildModel("${module}" as const, ${names.Module}Input, ${module}Db.${names.Module}, ${module}Db.${names.Module}Model, cnst.${names.Module}, ${names.Module}Insight, ${module}Db.${names.Module}Filter);`;
   })
   .join("\n")}
 ${scalarModules.map((module) => `export const ${module} = DatabaseRegistry.buildScalar("${module}" as const, ${capitalize(module)});`).join("\n")}

package/templates/workspaceRoot/AGENTS.md.template

@@ -650,7 +650,7 @@ export class TaskService extends serve(db.task, ({ plug }) => ({
 For a custom adapter class (not a predefined role), pass the class itself, e.g. `ipfsApi: plug(IpfsApi)`
 (see `libs/shared/lib/file/file.service.ts`). Injecting a file/image field is usually simpler than calling
 storage directly: declare `image: field(File).optional()` (or `images: field([File])`) on the model and let the
-store's generated `upload<Field>On<Model>(fileList)` action handle the upload. Add `{ cascade: "remove" }` to that
+store's generated `upload<Field>On<Model>(fileList)` action handle the upload. Add `{ cascade: "removeRef" }` to that
 field when the file belongs to the model alone, and removing the model removes the file and its stored object.
 
 ---
@@ -868,12 +868,23 @@ A short list of things the type system does not always catch:
   `secret` / `hidden` / `resolve()` fields with `text` throw at class-build time — the mirror is plaintext. Search
   runs on sqlite/libsql only; `q.search()` against Postgres throws. `thumb` is mirrored for rendering and is not
   indexed.
-- **`cascade: "remove"` takes a relation's target down with its owner.** Declare it on the relation itself —
-  `image: field(File, { cascade: "remove" })`, arrays included. The removal runs through the **target's service**,
-  so the target's own `_postRemove` runs too; that is how removing a model also deletes the file's stored object.
-  Only a relation accepts it: a `String`, an `ID`, or a scalar throws while the class is being built. Nothing
-  checks for other references to the same target, so declaring it asserts exclusive ownership. Document removal is
-  soft but the storage delete is not, and query-level removal fires no hooks and therefore no cascade.
+- **`cascade` names a direction, and the wrong one is a data loss.** Both actions can sit on the same field shape,
+  so the value has to say which end goes away. `cascade: "removeRef"` on the relation an owner holds
+  (`image: field(File, { cascade: "removeRef" })`, arrays included) removes the target when the owner is removed;
+  only a relation accepts it. `cascade: "removeWith"` on a child's own reference to its owner
+  (`field(ID, { ref: "agentSession", cascade: "removeWith" })`, or a relation, or `refPath` for a polymorphic
+  owner whose type field must be an `enumOf`) removes the child when the owner is — the owner never learns its
+  children exist. The removal runs through the **target's service** so its `_postRemove` runs too, unless the
+  target provably has no removal side effect, in which case the boot-time plan collapses it into one query. A
+  `removeWith` field gets its index automatically. Nothing checks for other references to the same target, so
+  `removeRef` asserts exclusive ownership. Removal is soft but a storage delete is not, and a query-level removal
+  fires no hooks and therefore no cascade.
+- **Removal is always soft, and `delete` is reserved.** `remove(id)`, the facade's `removeMany(query)`, and the
+  store's `removeManyByQuery` all stamp `removedAt`; the framework has no hard delete for a model table.
+- **The model facade spells out `Many`/`One` on its writes** — `updateOne`, `updateMany`, `removeOne`, `removeMany`
+  — because a bare `update`/`remove` would read like the document-path `update(id)` / `doc.remove()` while hitting
+  every match. Reads keep the short `find`/`findOne` pair, and counting is `count(query)` (`countDocuments` is
+  `@deprecated`).
 - **`q.search()` is a filter node, not a slice requirement.** Prefer
   `bySearch: filter().arg("text", String).query((text, q) => q.search(text, { prefix: true }))` — the generated
   `listBySearch` / `countBySearch` / `queryBySearch` / `insightBySearch` come for free. Only add a search slice when
@@ -951,8 +962,12 @@ akan sync automatically generates APIs across all layers. Only write custom logi
 | `pick[Query](args)`, `pickId[Query](args)` | Find one (throw if not found) |
 | `exists[Query](args)`, `count[Query](args)` | Existence check and count |
 | `insight[Query](args)`, `query[Query](args)` | Insight and raw query |
+| `remove[Query](args)`, `removeOne[Query](args)` | Query-level soft remove — all matches, or the newest one (`createdAt` desc, not caller-chosen) |
+| `update[Query](args).set(patch)`, `updateOne[Query](args).set(patch)` | Query-level update — the patch lands on a terminal `.set()`, because a filter's trailing args may be optional |
 
-**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 10 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+**Rule**: Define `Filter` with `.query()` conditions in `document.ts`. akan sync auto-generates all 14 query helper methods per filter. Write `Document` chain methods only for state transitions with validation.
+
+**The four query-level writes fire no hooks**, so no `_pre`/`_postRemove` and no cascade run — same as `updateManyByQuery`. Reach for them when the model carries no removal side effect; otherwise remove documents one at a time. A filter keyed after its own model (filter `chat` on model `chat`) is rejected at boot, because `removeChat`/`updateChat` would otherwise shadow the generated single-document CRUD.
 
 ## Generated Context
 

package/templates/libRoot/base/baseLogic.ts

@@ -1,14 +0,0 @@
-interface Dict {
-  libName: string;
-}
-export default function getContent(scanInfo: null, dict: Dict) {
-  return `
-// 현 디렉토리에서는 프로젝트 내 전체적으로 사용되는 로직을 구현하며, 따라서 백/프론트 비의존적인 pure js 코드만 구현 가능합니다.
-// common폴더와 다른점은, base 코드는 시스템 전체에서 import되어 사용되므로, 가장 핵심적인 로직과 추상화된 기능만 구현해야합니다.
-// @${dict.libName}/base에서는 서버/클라이언트 관련 라이브러리(@*/server, @*/server, @*/client, @*/client)를 모두 import할 수 없으며, @*/base 라이브러리만 import 가능합니다.
-
-export const someBaseLogic = () => {
-  //
-};
-  `;
-}

package/templates/libRoot/base/index.ts

@@ -1,8 +0,0 @@
-interface Dict {
-  [key: string]: string;
-}
-export default function getContent(scanInfo: null, dict: Dict = {}) {
-  return `
-export * from "./baseLogic";
-  `;
-}