sonamu 0.10.7 → 0.10.9

package/src/skills/sonamu-naite/SKILL.md

@@ -1,266 +0,0 @@
----
-name: sonamu-naite
-description: Traces values through Sonamu internals to explain unexpected behaviour. Use when a query or save produces the wrong result and the cause is unclear, or when a test needs to assert on internal state. Covers Naite.t(), Naite.get(), chaining filters (fromFile, fromFunction, where), wildcard keys, and DevRunner trace output.
----
-
-# Naite (Tracing System)
-
-Naite is a tracing system for recording values in source code and verifying them in tests.
-
-**Source code:** `modules/sonamu/src/naite/naite.ts`
-
-**How it works:**
-
-1. **Source code**: Record values with `Naite.t("key", value)`
-2. **Test code**: Retrieve recorded values with `Naite.get("key")`
-
----
-
-## Recording in Source Code (Naite.t)
-
-```typescript
-// In Model or library code
-import { Naite } from "sonamu";
-
-// Record a query
-Naite.t("esq-query", qb.toQuery());
-
-// Inside UpsertBuilder
-Naite.t("puri:ub-register", { tableName, uuid, isUuidReused, row });
-Naite.t("puri:ub-upserted", { tableName, mode, rowCount, returnedIds });
-```
-
----
-
-## Verifying in Tests (Naite.get)
-
-```typescript
-// In test code
-import { Naite } from "sonamu";
-
-// Verify a recorded query
-expect(Naite.get("esq-query").first()).not.contain("limit");
-
-// Verify UpsertBuilder behavior
-const trace = Naite.get("puri:ub-upserted").first();
-expect(trace).toMatchObject({ tableName: "users", rowCount: 3 });
-```
-
----
-
-## Built-in Naite Keys (Sonamu)
-
-| Key                                  | Description                    | Data                                                |
-| ------------------------------------ | ------------------------------ | --------------------------------------------------- |
-| `esq-query`                          | Executed SQL query             | Query string                                        |
-| `puri:executed-query`                | Query executed by Puri         | Query string                                        |
-| `puri:ub-register`                   | UpsertBuilder register call    | `{ tableName, uuid, isUuidReused, row }`            |
-| `puri:ub-upserted`                   | UpsertBuilder upsert complete  | `{ tableName, mode, rowCount, returnedIds }`        |
-| `puri:ub-ref-resolved`               | UBRef → actual ID substitution | `{ tableName, field, from, to }`                    |
-| `puri:ub-batch-updated`              | updateBatch complete           | `{ tableName, rowCount, whereColumns }`             |
-| `puri:ub-clean-orphans`              | cleanOrphans executed          | `{ tableName, cleanOrphans, deletedCount }`         |
-| `puri:ub-inherit`                    | inherit option applied         | `{ tableName, inheritColumns, excludedFromUpdate }` |
-| `mock:fs/promises:virtualFileSystem` | Virtual file system path       | File path string                                    |
-| `fs/promises:writeFile`              | writeFile call                 | `{ path, data }`                                    |
-| `fs/promises:rm`                     | rm call                        | `{ path, options }`                                 |
-
----
-
-## Recording with Custom Keys
-
-```typescript
-// Record with a custom key in source code
-Naite.t("user:created", { userId: 1, email: "test@test.com" });
-
-// Virtual file system for mocking
-Naite.t("mock:fs/promises:virtualFileSystem", "/path/to/virtual/file.ts");
-```
-
----
-
-## Naite.get() Retrieval Methods
-
-```typescript
-// Basic retrieval
-Naite.get("key").first(); // first entry
-Naite.get("key").last(); // last entry
-Naite.get("key").at(2); // nth entry
-Naite.get("key").result(); // all entries as an array
-Naite.get("key").getTraces(); // raw trace array (includes call stack)
-
-// Wildcard patterns
-Naite.get("puri:*").result(); // all with puri: prefix
-Naite.get("syncer:*:user").result(); // syncer:XXX:user pattern
-```
-
----
-
-## Chaining Filters
-
-```typescript
-// Filter by file name
-Naite.get("esq-query")
-  .fromFile("user.model.ts") // only entries recorded from this file
-  .result();
-
-// Filter by function name
-Naite.get("puri:executed-query")
-  .fromFunction("findById") // only entries called from this function
-  .result();
-
-// fromFunction options
-Naite.get("key")
-  .fromFunction("save", { from: "direct" }) // direct calls only (stack[0])
-  .fromFunction("save", { from: "indirect" }) // indirect calls only (stack[1+])
-  .fromFunction("save", { from: "both" }); // both (default)
-
-// Filter by data path (radash get path)
-Naite.get("puri:ub-register")
-  .where("data.tableName", "=", "users") // only where tableName is "users"
-  .where("data.rowCount", ">", 5) // rowCount > 5
-  .result();
-
-// where operators: ">", "<", ">=", "<=", "=", "!=", "includes"
-Naite.get("key")
-  .where("data.query", "includes", "WHERE") // check if string includes substring
-  .result();
-
-// Combining filters
-Naite.get("puri:executed-query")
-  .fromFunction("findMany")
-  .where("data", "includes", "users")
-  .first();
-```
-
----
-
-## Naite.del() - Delete Values
-
-```typescript
-Naite.t("mock:fs/promises:virtualFileSystem", "/virtual/path");
-// ... test ...
-Naite.del("mock:fs/promises:virtualFileSystem");
-```
-
----
-
-## Test Examples
-
-```typescript
-test("query should not have a limit", async () => {
-  await UserModel.findMany("A", { num: 0, page: 1 });
-
-  expect(Naite.get("esq-query").first()).not.contain("limit");
-  expect(Naite.get("esq-query").first()).not.contain("offset");
-});
-
-test("trace UpsertBuilder register", async () => {
-  const ub = new UpsertBuilder();
-  const ref = ub.register("users", { email: "test@test.com", username: "test" });
-
-  const trace = Naite.get("puri:ub-register").first();
-  expect(trace).toMatchObject({
-    tableName: "users",
-    uuid: ref.uuid,
-    isUuidReused: false,
-  });
-});
-
-test("trace upsert completion", async () => {
-  // ... run upsert ...
-
-  const trace = Naite.get("puri:ub-upserted").first();
-  expect(trace).toMatchObject({
-    tableName: "users",
-    mode: "upsert",
-    rowCount: 3,
-  });
-});
-```
-
----
-
-## Viewing Traces in DevRunner
-
-Use the `sonamu test --traces` flag to view Naite traces directly in the CLI:
-
-```bash
-sonamu test user.model --traces
-sonamu test user.model -t
-```
-
-Example output:
-
-```
-Tests: 5 passed, 0 failed, 5 total
-Duration: 791ms
-
-Traces:
-
-  UserModel > BaseModel basic functionality > Model.findMany() with num = 0
-  user.model.test.ts
-
-    [esq-query] user.model.ts:113
-    select "users"."id" as "id", ...
-
-    [puri:executed-query] puri.ts:1349
-    select COUNT(*)::integer as "total" from "users" limit 1
-```
-
-Trace data is fetched from `testCase.meta().traces` (collected in `afterEach` of `bootstrap.ts`) and serialized as the `SerializedTrace` type (exported from `naite.ts`).
-
-See `sonamu-testing` for DevRunner details.
-
----
-
-## Internal Structure
-
-### NaiteStore
-
-```typescript
-type NaiteStore = Map<string, NaiteTrace[]>;
-
-interface NaiteTrace {
-  key: string;
-  data: any;
-  stack: StackFrame[]; // call stack information
-  at: Date;
-}
-
-interface StackFrame {
-  functionName: string | null;
-  filePath: string; // path relative to TS file
-  lineNumber: number; // line number in TS file
-}
-```
-
-### SerializedTrace (for API responses / DevRunner)
-
-```typescript
-type SerializedTrace = {
-  key: string;
-  value: any;
-  filePath: string;
-  lineNumber: number;
-  at: string;
-};
-```
-
----
-
-## Debugging Uses
-
-Naite can also be used for source code behavior analysis beyond tests:
-
-- **Query tracing**: Use `esq-query` and `puri:executed-query` to see the actual SQL being executed
-- **UpsertBuilder analysis**: Trace the full flow (register → upsert → ref-resolved → batch-updated) with `puri:ub-*` keys
-- **File I/O tracing**: Use `fs/promises:*` keys to see file operations performed by the syncer and others
-- **Isolate a specific function**: Use `.fromFunction("findById")` chaining to filter traces to only those originating from a specific method
-
----
-
-## References
-
-- **Testing guide**: `sonamu-testing`
-- **DevRunner details**: `sonamu-testing`
-- **expectQuery helper** (Naite-based): see "Test Helper: expectQuery" in `sonamu-testing`

package/src/skills/sonamu-query/SKILL.md

@@ -1,48 +0,0 @@
----
-name: sonamu-query
-description: Reads and writes data through Sonamu Models and the Puri query builder. Use when implementing a Model CRUD method, writing a SELECT/WHERE/JOIN query, batch-saving relation data, or when a query returns unexpected rows or an excessively deep type error. Covers BaseModelClass, findMany, executeSubsetQuery, getPuri, transactions, UpsertBuilder, tsvector and PGroonga full-text search, pgvector, and pg_trgm.
----
-
-# Sonamu Data Access
-
-**Working code references:**
-
-- `sonamu/examples/miomock/api/src/application/employee/employee.model.ts` — basic CRUD
-- `sonamu/examples/miomock/api/src/application/project/project.model.ts` — ManyToMany save
-- `sonamu/examples/miomock/api/src/application/project/project.model.test.ts` — tests
-
-## Reference Map
-
-| Need | Read |
-| --- | --- |
-| Model class structure, CRUD methods, getSubsetQueries, executeSubsetQuery options, enhancers, types file | `references/model.md` |
-| Transactions, validation patterns, orderBy after scaffolding, code conventions | `references/model-patterns.md` |
-| SELECT, WHERE, JOIN, GROUP BY, INSERT/UPDATE/DELETE, result methods | `references/puri.md` |
-| tsvector / PGroonga full-text search, pgvector, pg_trgm fuzzy search | `references/search.md` |
-| Batch-saving relations, save order, ManyToMany, bulk insert, UpsertOptions | `references/upsert.md` |
-
-Embedding generation and chunking live in the `sonamu-vector` skill.
-Subset definition lives in `sonamu-entity`.
-
----
-
-## Non-negotiable rules
-
-**Puri**
-
-- Puri is the standard for BOTH reads and writes in ALL contexts (Model, Frame, scripts) — do NOT run queries on a raw `DB.getDB()` handle (exceptions: migration files, `db.ts`, tests, and the `.knex` escape hatch)
-- MUST use `getPuri("r")` for read queries, `getPuri("w")` for write queries
-- MUST include a WHERE condition for UPDATE/DELETE
-- MUST use `transaction()` for multiple write operations
-- Inside a Frame, use the associated Model's `getPuri` (Frame exposes only `getDB` / `getUpsertBuilder`)
-- Outside a Model, wrap knex with `new PuriWrapper(DB.getDB(which), new UpsertBuilder())`
-- Use the `puri.knex` escape hatch only for non-entity / framework-internal tables (e.g. `workflow_runs`)
-- JSON/JSONB columns are automatically JSON.stringify'd on insert/update
-
-**UpsertBuilder**
-
-- MUST use inside `transaction()`
-- MUST call `ubUpsert()` for FK-referenced tables first (correct order)
-- `UBRef` can ONLY be used inside `ubRegister`, never for direct DB queries
-- Self-reference is auto-handled by level-based insertion
-- Unique index conflicts are auto-resolved by pre-fetching existing IDs

package/src/skills/sonamu-query/references/model-patterns.md

@@ -1,390 +0,0 @@
-# Model — Transactions, Validation, Conventions
-
-## Transactions
-
-```typescript
-await this.getPuri("w").transaction(async (trx) => {
-  await trx.table("users").where("id", fromId).decrement("points", amount);
-  await trx.table("users").where("id", toId).increment("points", amount);
-});
-```
-
-## Validation Patterns
-
-### Step-by-step Validation
-
-A pattern for validating business rules step by step:
-
-```typescript
-async enroll(courseId: number, userId: number): Promise<Enrollment> {
-  // Step 1: Duplicate check
-  const existing = await this.findOne("A", {
-    course_id: courseId,
-    user_id: userId,
-  });
-
-  if (existing) {
-    throw new Error("Already enrolled in this course");
-  }
-
-  // Step 2: Capacity check
-  const course = await CourseModel.findById("A", courseId);
-  const { total } = await this.findMany({ course_id: courseId });
-
-  if (total >= course.max_students) {
-    throw new Error("The course is full");
-  }
-
-  // Step 3: Execute
-  const [id] = await this.save([{ course_id: courseId, user_id: userId }]);
-  return this.findById("A", id);
-}
-```
-
-### Conditional Validation
-
-Perform different validations depending on conditions:
-
-```typescript
-async save(spa: TaskSaveParams[]): Promise<number[]> {
-  for (const sp of spa) {
-    // completion date is required only when status is completed
-    if (sp.status === "completed" && !sp.completed_at) {
-      throw new Error("A completion date is required for completed status");
-    }
-
-    // Check amount range only when budget is present
-    if (sp.budget !== null && sp.budget < 0) {
-      throw new Error("Budget must be 0 or greater");
-    }
-  }
-
-  // Save after validation passes
-  const wdb = this.getPuri("w");
-  spa.forEach((sp) => wdb.ubRegister("tasks", sp));
-
-  return wdb.transaction(async (trx) => {
-    return trx.ubUpsert("tasks");
-  });
-}
-```
-
-### Validating Against Related Data
-
-Validate relationships with other tables:
-
-```typescript
-async save(spa: ResponseSaveParams[]): Promise<number[]> {
-  for (const sp of spa) {
-    // Check if the survey is still open
-    const collection = await CollectionModel.findById("A", sp.collection_id);
-
-    if (collection.status === "closed") {
-      throw new Error("This survey has already ended");
-    }
-
-    // Check response period
-    const now = new Date();
-    if (now < collection.begin_date || now > collection.end_date) {
-      throw new Error("This is not within the response period");
-    }
-  }
-
-  // Save after validation passes
-  const wdb = this.getPuri("w");
-  spa.forEach((sp) => wdb.ubRegister("responses", sp));
-
-  return wdb.transaction(async (trx) => {
-    return trx.ubUpsert("responses");
-  });
-}
-```
-
-**Key points:**
-
-- Clear error messages when validation fails
-- Only save after all validations pass
-- Enforce business rules through code
-
----
-
-## IMPORTANT: Verify orderBy After Scaffolding
-
-### Problem
-
-When scaffolding is run from Sonamu UI, the model file is **regenerated**, leaving only the default value (`id-desc`) and losing any custom orderBy cases.
-
-```
-Error: Argument of type 'xxx-asc' is not assignable to parameter of type 'never'
-```
-
-### Fix
-
-After scaffolding, you must exhaustively handle **all orderBy enum cases** from entity.json in the model file.
-
-```typescript
-// entity.json orderBy enum
-{ "TaskOrderBy": { "id-desc": "ID Latest", "created_at-desc": "By Date", "title-asc": "By Title" } }
-
-// model - must verify/add after scaffolding
-if (params.orderBy) {
-  if (params.orderBy === "id-desc") {
-    qb.orderBy("tasks.id", "desc");
-  } else if (params.orderBy === "created_at-desc") {
-    qb.orderBy("tasks.created_at", "desc");
-  } else if (params.orderBy === "title-asc") {
-    qb.orderBy("tasks.title", "asc");
-  } else {
-    exhaustive(params.orderBy);  // compile error if any case is missing
-  }
-}
-```
-
-### Checklist
-
-- Verify orderBy cases in model after scaffolding
-- Confirm they match the orderBy enum in entity.json
-- Also check other custom logic such as search cases and enhancers
-
----
-
-## Code Quality and Consistency
-
-### DRY principle: use this.modelName
-
-Use `this.modelName` instead of hardcoding the model name in error messages.
-
-**BAD: hardcoded model name**
-
-```typescript
-// department.model.ts
-if (!rows[0]) {
-  throw new NotFoundException(SD("notFound")("Department", id));
-}
-
-// user.model.ts
-if (!rows[0]) {
-  throw new NotFoundException(SD("notFound")("User", id));
-}
-```
-
-**GOOD: use this.modelName**
-
-```typescript
-// Common to all Models
-if (!rows[0]) {
-  throw new NotFoundException(SD("notFound")(this.modelName, id));
-}
-```
-
-**Benefits:**
-
-- Prevents copy-paste mistakes: no need to update the model name when copying from another model
-- Consistency: all models use the same pattern
-- Maintainability: changing modelName in the constructor automatically reflects in all error messages
-
-### Consistent i18n Key Usage
-
-Use the same i18n keys consistently for the same purpose across the entire project.
-
-**BAD: duplicate i18n keys**
-
-```typescript
-// Different keys used across models
-throw new NotFoundException(SD("error.entityNotFound")(this.modelName, id));
-throw new NotFoundException(SD("error.notFound")(this.modelName, id));
-throw new NotFoundException(SD("notFound")(this.modelName, id));
-
-// Search field error
-throw new BadRequestException(SD("error.unknownSearchField")(params.search));
-throw new BadRequestException(SD("error.invalidSearchField")(params.search));
-```
-
-**GOOD: use standard i18n keys**
-
-```typescript
-// Entity lookup failure - short and clear
-throw new NotFoundException(SD("notFound")(this.modelName, id));
-
-// Search field error - search namespace
-throw new BadRequestException(SD("search.invalidField")(params.search));
-```
-
-**Recommended i18n key patterns:**
-| Situation | i18n key | Used in |
-|------|---------|--------|
-| Entity lookup failure | `notFound` | findById |
-| Invalid search field | `search.invalidField` | findMany search |
-| Missing required field | `validation.required` | save validation |
-| Unauthorized | `error.forbidden` | guards failure |
-| Login required | `error.loginRequired` | Context.user null |
-
-### Bulk Refactoring Strategy
-
-When consistently modifying multiple model files, use sed for automation:
-
-**Step 1: Confirm pattern**
-
-```bash
-# Find files to modify
-grep -r 'SD("error.entityNotFound")' packages/api/src/application/*/
-```
-
-**Step 2: Validate changes (dry-run)**
-
-```bash
-# Preview changes before applying
-sed -n 's/SD("error.entityNotFound")(\(.*\), id)/SD("notFound")(this.modelName, id)/p' file.ts
-```
-
-**Step 3: Apply in bulk**
-
-```bash
-# Modify all model files
-find packages/api/src/application -name "*.model.ts" -exec sed -i '' \
-  's/SD("error.entityNotFound")(\(.*\), id)/SD("notFound")(this.modelName, id)/g' {} \;
-```
-
-**Step 4: Validate with build**
-
-```bash
-# TypeScript type check
-pnpm typecheck
-
-# Full build
-pnpm build
-```
-
-**Cautions:**
-
-- Always run after a git commit (to allow rollback)
-- Confirm changes with dry-run first
-- Check for type errors with build
-- Verify behavior with tests
-
-### Type Check Patterns
-
-**satisfies vs as const:**
-
-```typescript
-// BAD: bypasses type checking with type assertion
-const params = {
-  num: 24,
-  page: 1,
-  search: "id" as const,
-  orderBy: "wrong-value" as const, // error not detected
-  ...rawParams,
-} as RoleListParams;
-
-// GOOD: compile-time validation with satisfies
-const params = {
-  num: 24,
-  page: 1,
-  search: "id" as const,
-  orderBy: "wrong-value" as const, // compile error!
-  ...rawParams,
-} satisfies RoleListParams;
-```
-
-**Recommended usage locations:**
-
-- Default values for params in findMany
-- Complex object literals (where type checking is important)
-
-### IMPORTANT: ListParams / findMany / SearchField Synchronization
-
-The following three must always remain consistent. If any one is out of sync, the feature either exists as a declaration only with no behavior, or a runtime error will occur.
-
-1. `SearchField` enum values in `entity.json`
-2. `ListParams` field definitions in `types.ts`
-3. Filter/search handling code in `findMany` in `model.ts`
-
-**Checklist:**
-
-- [ ] Are all values declared in SearchField implemented in findMany?
-- [ ] If any filter branch is commented out, either remove it or implement it
-- [ ] Are "filter by ~", "search by ~" features from requirements reflected in ListParams?
-
-**In particular, entities with an approval workflow must always add a status filter.**
-(Clicking count by stage → filter to show only that list is a commonly required pattern)
-
-```typescript
-// types.ts - approval workflow entity example
-export const AchievementListParams = AchievementBaseListParams.extend({
-  status: z.nativeEnum(AchievementStatus).optional(),
-  achievement_type: z.nativeEnum(AchievementType).optional(),
-  submitter_id: z.string().optional(),
-});
-
-// model.ts - corresponding filter implementation
-if (params.status) qb.where("achievements.status", params.status);
-if (params.achievement_type) qb.where("achievements.achievement_type", params.achievement_type);
-if (params.submitter_id) qb.where("achievements.submitter_id", params.submitter_id);
-```
-
-**DO NOT - declaration/implementation mismatch:**
-
-```typescript
-// SearchField "title" declared in entity.json
-// model.ts only handles "id" case, "title" is commented out
-if (params.search === "id") {
-  // ...
-} /* else if (params.search === "title") {
-  // TODO: not implemented
-} */
-```
-
-### Code Review Checklist
-
-When writing a new Model:
-
-- [ ] Use `this.modelName` (no hardcoding)
-- [ ] Use standard i18n keys (`notFound`, `search.invalidField`)
-- [ ] Use the `satisfies` keyword (type safety)
-- [ ] Do not unnecessarily specify the debug option
-- [ ] Exhaustively handle all orderBy cases
-- [ ] If a ManyToMany relation exists, add \_ids array to SaveParams
-- [ ] Does the `@upload` method have `@api` on it? (`@upload` is used standalone; using both together causes a build error)
-- [ ] Do the SearchField enum and findMany implementation match?
-- [ ] For entities with approval workflows, are status/type filters present in both ListParams and findMany?
-
-When bulk-modifying 20+ Models:
-
-- [ ] Compare patterns with reference code like miomock
-- [ ] Prioritize inconsistent patterns
-- [ ] Write an automation script using sed or similar
-- [ ] Commit to git before making changes
-- [ ] Validate changes with dry-run
-- [ ] Check for type errors with pnpm typecheck
-- [ ] Verify behavior with pnpm test
-- [ ] Check for `any` type usage (prohibited)
-
-### Prohibition on any type
-
-The `any` type neutralizes TypeScript's type safety and must **never be used**.
-
-**BAD: using any**
-
-```typescript
-const { category_ids, ...data } = sp as any;
-function process(input: any) { ... }
-```
-
-**GOOD: use precise types or unknown**
-
-```typescript
-// Destructure with a precise type
-const { category_ids, ...data } = sp as QuestionCollectionSaveParams;
-
-// Use unknown when the type is not known (instead of any)
-function process(input: unknown) {
-  if (typeof input === "string") { ... }
-}
-```
-
-**Rules:**
-
-- `any` is prohibited
-- When the type is unknown, use `unknown` and narrow with a type guard
-- When a type assertion is needed during destructuring, specify the exact type name (`as ConcreteType`)
-- Suppression comments like `eslint-disable @typescript-eslint/no-explicit-any` are also prohibited