sonamu 0.10.7 → 0.10.9

package/src/skills/sonamu-entity/references/design-guides.md

@@ -1,243 +0,0 @@
-# Situation-Specific Design Guides
-
-## Situation-Specific Guides
-
-### Adding a string field
-
-```json
-{ "name": "title", "type": "string", "length": 255, "desc": "Title" }
-```
-
-- Omitting `length` → stored as `text` type (for long text)
-
-### Adding an enum field
-
-```json
-// 1. Add to props
-{ "name": "status", "type": "enum", "id": "ProductStatus", "desc": "Status" }
-
-// 2. Define in enums (MUST — missing this causes errors)
-"ProductStatus": { "draft": "Draft", "published": "Published", "archived": "Archived" }
-```
-
-### IMPORTANT: Always use enum for fixed-value fields
-
-Defining a field with a fixed set of choices as `string` breaks DB integrity.
-
-**Rule: "Can this value be freely entered from outside the code?"** No → enum, Yes → string
-
-**Enum candidates**: strings that look like `faker.helpers.arrayElement([...])`, fields described as "one of the following / type / category", select boxes / radio buttons
-
-```json
-// WRONG: defined as string
-{ "name": "budget_item", "type": "string", "desc": "Budget item" }
-// CORRECT: defined as enum
-{ "name": "budget_item", "type": "enum", "id": "BudgetItem", "desc": "Budget item" }
-```
-
-### Adding a nullable field
-
-```json
-{ "name": "deleted_at", "type": "date", "nullable": true, "desc": "Deleted at" }
-```
-
-**CRITICAL: Importance of the nullable attribute**
-
-A field without `nullable: true` is treated as **required**.
-
-Sonamu's `ubUpsert` uses PostgreSQL `ON CONFLICT ... DO UPDATE`, so **all required fields** must be included even on updates.
-
-```json
-// example
-{
-  "props": [
-    { "name": "title", "type": "string" }, // required (no nullable)
-    { "name": "content", "type": "string" }, // required (no nullable)
-    { "name": "category", "type": "string", "nullable": true } // optional
-  ]
-}
-```
-
-**Rules**:
-
-- Do not add `nullable: true` to fields that are not optional
-- Always specify `nullable: true` for optional fields
-- Required fields must always have a value in tests and API calls
-
-**Details:** see `sonamu-testing` and "CRITICAL: Required fields must be included" in `sonamu-query`
-
-### Adding a JSON field
-
-```json
-{
-  "name": "metadata",
-  "type": "json",
-  "id": "ProductMetadata",
-  "desc": "Metadata"
-}
-```
-
-- `id` is required (used as the type name)
-- A separate TypeScript type definition is needed
-
-### Adding a searchText field (for pg_trgm Fuzzy Search)
-
-A dedicated prop type that consolidates multiple columns into a single generated column. Used with a GIN index.
-
-```json
-{
-  "props": [
-    { "name": "title_ko", "type": "string" },
-    { "name": "title_en", "type": "string" },
-    { "name": "tags", "type": "string[]" },
-    {
-      "name": "search_text",
-      "type": "searchText",
-      "sourceColumns": [
-        { "name": "title_ko" },
-        { "name": "title_en", "caseInsensitive": true },
-        { "name": "tags" }
-      ]
-    }
-  ],
-  "indexes": [
-    {
-      "name": "idx_items_search_text",
-      "type": "index",
-      "columns": [{ "name": "search_text", "opclass": "gin_trgm_ops" }],
-      "using": "gin"
-    }
-  ]
-}
-```
-
-SQL expressions per source column type:
-
-| source type                  | caseInsensitive: true         | caseInsensitive: false (default)     |
-| ---------------------------- | ----------------------------- | ------------------------------------ |
-| `string`                     | `lower(COALESCE(col, ''))`    | `COALESCE(col, '')`                  |
-| `string[]`                   | `sonamu_text_array_agg(col)`  | `sonamu_text_array_agg(col, false)`  |
-| `json` (z.array(z.string())) | `sonamu_jsonb_array_agg(col)` | `sonamu_jsonb_array_agg(col, false)` |
-
-- If a `string[]` or `json(string[])` source is present, helper function DDL is automatically inserted in the migration
-- `searchText` columns are generated columns and are excluded from SaveParams — INSERT/UPDATE is not allowed
-- For query usage: see the "pg_trgm Fuzzy Search" section in `sonamu-query`
-
-### Adding a unique constraint
-
-```json
-{
-  "name": "products_sku_unique",
-  "type": "unique",
-  "columns": [{ "name": "sku" }]
-}
-```
-
-### Composite unique constraint
-
-```json
-{
-  "name": "cart_items_unique",
-  "type": "unique",
-  "columns": [{ "name": "user_id" }, { "name": "product_id" }]
-}
-```
-
-### Partial index (`where`)
-
-`where` declares a PostgreSQL partial index predicate. Provide a raw SQL condition **without** the `WHERE` keyword; it is appended to the generated `CREATE INDEX`. Works for every index type (`index`, `unique`, `hnsw`, `ivfflat`, pgroonga).
-
-```json
-{
-  "name": "uniq_users_email_active",
-  "type": "unique",
-  "columns": [{ "name": "email" }],
-  "where": "deleted_at IS NULL"
-}
-```
-
-→ `CREATE UNIQUE INDEX uniq_users_email_active ON users (email) WHERE deleted_at IS NULL;`
-(Enforces email uniqueness only among non-deleted rows.)
-
-### `nullsNotDistinct` (unique only)
-
-By default PostgreSQL treats `NULL`s as distinct, so a unique index allows multiple `NULL` rows. Set `nullsNotDistinct: true` to emit `NULLS NOT DISTINCT`, treating `NULL`s as equal (at most one `NULL` allowed).
-
-```json
-{
-  "name": "uniq_accounts_external_id",
-  "type": "unique",
-  "columns": [{ "name": "external_id" }],
-  "nullsNotDistinct": true
-}
-```
-
-→ `CREATE UNIQUE INDEX uniq_accounts_external_id ON accounts (external_id) NULLS NOT DISTINCT;`
-
-### IMPORTANT: Use the actual DB column name in indexes
-
-**The way FK columns are referenced differs between indexes and subsets. Do not confuse them.**
-
-| Location  | Format                     | Example                               |
-| --------- | -------------------------- | ------------------------------------- |
-| `indexes` | Actual DB column name      | `role_id`, `user_id`, `department_id` |
-| `subsets` | FieldExpr (relation.field) | `role.id`, `user.id`, `department.id` |
-
-**DO NOT:**
-
-```json
-// Using FieldExpr in indexes → error
-"indexes": [
-  { "name": "ix_role", "type": "index", "columns": [{ "name": "role.id" }] }
-]
-```
-
-**DO:**
-
-```json
-// indexes use actual DB column names
-"indexes": [
-  { "name": "ix_role_id", "type": "index", "columns": [{ "name": "role_id" }] }
-]
-
-// subsets use FieldExpr
-"subsets": {
-  "A": ["id", "role.id", "role.name"]
-}
-```
-
-### IMPORTANT: Unique constraints based on business rules
-
-Not a technical decision — ask **"What if the same combination is inserted twice?"** → if it should error, use unique; if it should be allowed, use index only.
-
-**Patterns that need composite unique**: per-year settings (`type, dept_id, year`), user-role mappings, per-year budgets (`project_id, year, budget_item`), likes/bookmarks (`user_id, entity_id`)
-
-## Common Mistakes
-
-| Mistake                                          | Fix                                                                                   |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------- |
-| Missing `id` prop                                | Recommended to add (needed by most Model logic)                                       |
-| Missing `created_at` prop                        | Recommended to add with `dbDefault: "CURRENT_TIMESTAMP"`                              |
-| Missing `OrderBy` enum                           | Add `{EntityId}OrderBy` (needed for findMany sorting)                                 |
-| Missing `SearchField` enum                       | Add `{EntityId}SearchField` (needed for search)                                       |
-| enum prop `id` not defined in enums              | Add definition to the enums section                                                   |
-| Missing `id` on json prop                        | Add the `id` field                                                                    |
-| Using `"type": "text"` directly                  | `text` is invalid. Use `"type": "string"` without a length                            |
-| Adding multiple values to `OrderBy` enum         | **Default is `id-desc` only** (see below)                                             |
-| Defining fixed-choice fields as `string`         | Convert to enum (check for fields with arrayElement-style fixtureGenerator)           |
-| Yearly/mapping tables without unique constraints | Add composite unique based on business rules                                          |
-| Using `number` type for integer fields           | Use `integer` (use `numeric` only when decimal precision is needed)                   |
-| Using `role.id` format in indexes                | indexes use actual DB column name (`role_id`); only subsets use FieldExpr (`role.id`) |
-
-## Resolving Entity Schema Validation Errors
-
-**→ See `references/creation-workflow.md` PHASE 1** (missing index type, Subset FieldExpr, duplicate columns, Boolean dbDefault, etc.)
-
-**Quick checklist:**
-
-- [ ] Does every index have a `type` field? (`"index"` | `"unique"` | `"hnsw"` | `"ivfflat"`)
-- [ ] Does the subset reference FK using `relation.id` format? (`user_id` ✗ → `user.id` ✓)
-- [ ] No duplicate definition of BelongsToOne relation and FK column?
-- [ ] Is Boolean `dbDefault` a string (`"true"` / `"false"`)? (0, 1 ✗)
-- [ ] Are all fields included in Subset A?
-- [ ] Do index columns use actual DB column names (`role_id`)? (FieldExpr `role.id` ✗)

package/src/skills/sonamu-entity/references/field-types.md

@@ -1,170 +0,0 @@
-# Field Types and Options
-
-## Minimal Template
-
-```json
-{
-  "id": "Product",
-  "table": "products",
-  "title": "Product",
-  "props": [
-    { "name": "id", "type": "integer", "desc": "ID" },
-    {
-      "name": "created_at",
-      "type": "date",
-      "dbDefault": "CURRENT_TIMESTAMP",
-      "desc": "Created at"
-    },
-    { "name": "name", "type": "string", "length": 255, "desc": "Product name" }
-  ],
-  "indexes": [],
-  "subsets": { "A": ["id", "name", "created_at"] },
-  "enums": {
-    "ProductOrderBy": { "id-desc": "Newest" },
-    "ProductSearchField": { "id": "ID", "name": "Name" }
-  }
-}
-```
-
-
-## IMPORTANT: OrderBy Enum Generation Rule
-
-**IMPORTANT: It is strongly recommended to use only `id-desc` during initial scaffolding.**
-
-```json
-// RECOMMENDED — for initial scaffolding
-"ProductOrderBy": { "id-desc": "Newest" }
-
-// AVOID — do not add these before scaffolding
-"ProductOrderBy": { "id-desc": "Newest", "name-asc": "Name (A-Z)", "created_at-desc": "Newest first" }
-```
-
-### Why only id-desc?
-
-The model code generated by scaffolding handles only `id-desc` automatically. If the OrderBy enum has other values:
-
-1. Scaffolding succeeds, but a type error occurs in the model's `exhaustive()` function
-2. The developer must manually add cases to the model
-3. If this is missed, a runtime error may occur
-
-**This is not a technical constraint — it is scaffolding best practice.** Add complex OrderBy values after scaffolding is complete.
-
-### When additional sort options are needed
-
-When sort options are required later:
-
-1. Add values to the OrderBy enum in entity.json
-2. Add the corresponding cases to the orderBy branch in the model
-
-```typescript
-// model.ts — adding orderBy cases
-if (params.orderBy === "id-desc") {
-  qb.orderBy("products.id", "desc");
-} else if (params.orderBy === "name-asc") {
-  // added
-  qb.orderBy("products.name", "asc");
-} else {
-  exhaustive(params.orderBy);
-}
-```
-
-**Rule**: start with `id-desc` only → add others as needed after scaffolding
-
-## IMPORTANT: integer vs number Type Selection
-
-**CRITICAL: Always follow the criteria below when creating numeric fields. Wrong type choice causes unnecessary ALTER migrations.**
-
-PostgreSQL mapping:
-
-- `integer` → DB `integer` (whole numbers)
-- `number` → DB `numeric(p,s)` (precise decimal numbers)
-
-| Use case                                | Entity type                       | Example                          |
-| --------------------------------------- | --------------------------------- | -------------------------------- |
-| PK, FK, count, order, quantity          | `integer`                         | id, user_id, order_num, quantity |
-| Amount, ratio, values requiring decimal | `number` (+ `precision`, `scale`) | price, rate, weight, score       |
-
-**DO NOT:**
-
-```json
-{ "name": "order_num", "type": "number", "desc": "Sort order" }
-{ "name": "quantity", "type": "number", "desc": "Quantity" }
-```
-
-**DO:**
-
-```json
-{ "name": "order_num", "type": "integer", "desc": "Sort order" }
-{ "name": "quantity", "type": "integer", "desc": "Quantity" }
-{ "name": "price", "type": "number", "precision": 12, "scale": 2, "desc": "Price" }
-{ "name": "rate", "type": "number", "precision": 5, "scale": 2, "desc": "Rate" }
-```
-
-**Decision rule: "Does this value ever need a decimal point?"**
-
-- No → `integer`
-- Yes → `number` (always specify `precision` and `scale`)
-
-## Common Options (CommonProp)
-
-Options applicable to all prop types:
-
-| Option     | Type    | Description                                               |
-| ---------- | ------- | --------------------------------------------------------- |
-| `name`     | string  | Field name (required)                                     |
-| `desc`     | string  | Field description                                         |
-| `nullable` | boolean | Whether NULL is allowed (default: false)                  |
-| `toFilter` | true    | Register as a sonamuFilter filtering target. See model.md |
-| `cone`     | Cone    | LLM-based fixture generation metadata. See cone.md        |
-
-## Required Options by Type
-
-| Type         | Required     | Optional                                                           |
-| ------------ | ------------ | ------------------------------------------------------------------ |
-| `string`     | —            | `length` (text if omitted), `zodFormat` (email, uuid, etc.)        |
-| `integer`    | —            | —                                                                  |
-| `bigInteger` | —            | —                                                                  |
-| `number`     | —            | `precision`, `scale`, `numberType` (real/double precision/numeric) |
-| `numeric`    | —            | `precision`, `scale`                                               |
-| `enum`       | `id`         | `nullable`, `dbDefault`, `length`                                  |
-| `json`       | `id`         | `dbDefault: "{}"`                                                  |
-| `date`       | —            | `dbDefault`, `precision`                                           |
-| `boolean`    | —            | `dbDefault: "false"`                                               |
-| `virtual`    | `id`         | `virtualType` (query/code, default: code)                          |
-| `vector`     | `dimensions` | —                                                                  |
-| `tsvector`   | —            | —                                                                  |
-
-## IMPORTANT: ENUM Type dbDefault Setting
-
-When setting a default value on an ENUM field, the value must be wrapped in **escaped double quotes**.
-
-### DO NOT - Incorrect Examples
-
-```json
-// Incorrect: no quotes — interpreted as a column reference in SQL, causes error
-{ "name": "status", "type": "enum", "id": "ApprovalStatus", "dbDefault": "pending" }
-// Error: cannot use column reference in DEFAULT expression
-
-// Incorrect: single quotes — causes oxfmt format error
-{ "name": "status", "type": "enum", "id": "ApprovalStatus", "dbDefault": "'pending'" }
-```
-
-### DO - Correct Example
-
-```json
-// Correct: escaped double quotes
-{
-  "name": "status",
-  "type": "enum",
-  "id": "ApprovalStatus",
-  "dbDefault": "\"pending\"",
-  "desc": "Approval status"
-}
-```
-
-### Generated SQL
-
-```sql
--- Correct output
-"status" text not null default 'pending'
-```

package/src/skills/sonamu-entity/references/relations-detail.md

@@ -1,245 +0,0 @@
-# Relationship Details — FK Rules, Subsets, ManyToMany Types
-
-## FK Reference Rules (FieldExpr)
-
-When a BelongsToOne relationship is defined, a `{name}_id` column is automatically created. **In subsets, reference using the `{name}.id` form (FieldExpr)**, and **in indexes, use the actual DB column name (`{name}_id`)**.
-
-### Where It Applies
-
-| Location | Format                       | Example               |
-| -------- | ---------------------------- | --------------------- |
-| subsets  | FieldExpr (`relation.field`) | `"user.id"`           |
-| indexes  | actual DB column name        | `"user_id"`           |
-| unique   | actual DB column name        | `["user_id", "date"]` |
-| search   | FieldExpr (`relation.field`) | `"user.id"`           |
-
-### Example
-
-```json
-{
-  "id": "ApiLog",
-  "props": [{ "type": "relation", "name": "user", "with": "User", "relationType": "BelongsToOne" }],
-  "subsets": {
-    "A": ["id", "user.id", "api_path"] // use FieldExpr
-  },
-  "indexes": [
-    {
-      "type": "index",
-      "name": "api_logs_user_id_index",
-      "columns": [{ "name": "user_id" }]
-    }
-  ]
-}
-```
-
-### Error Message in Subsets
-
-```
-Error: ApiLog -- invalid FieldExpr 'user_id' (available props: id, created_at, ..., user)
-```
-
-If you see this error in subsets, change `user_id` → `user.id`. In indexes, `user_id` is the correct format.
-
-> **Note:** For a detailed explanation of the difference in reference methods between indexes and subsets, see the "IMPORTANT: In indexes, use the actual DB column name for FK columns" section in `sonamu-entity`.
-
----
-
-## Common Mistakes
-
-| Mistake                                       | Fix                                                                                          |
-| --------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Using a separate `"relations": [...]` section | Define with `"type": "relation"` inside `props`                                              |
-| Directly defining `{name}_id` in BelongsToOne | Delete it (auto-generated)                                                                   |
-| Using `user_id` directly in Subset            | Change to `user.id` form                                                                     |
-| Mismatch of FK intent in OneToOne             | Explicitly set `hasJoinColumn: true` on the side holding the FK (optional, no FK if omitted) |
-| Missing `joinColumn` in HasMany               | Specify the FK column name in the related table                                              |
-| Missing `onUpdate/onDelete` in ManyToMany     | Add as required                                                                              |
-| Inconsistent joinTable name                   | Consistent naming recommended (alphabetical order)                                           |
-| `nullable: false` in self-reference           | Change to `nullable: true`                                                                   |
-
-## Using Relationships in Subsets
-
-- See `references/subset.md`
-
-```json
-{
-  "subsets": {
-    "A": ["id", "title", "author.id", "author.username", "author.department.name"]
-  }
-}
-```
-
-- Nesting is possible via dot notation
-- JOIN is auto-generated
-
----
-
-## Type Definitions for ManyToMany Relationships
-
-ManyToMany relationships are defined in Entity JSON, but SaveParams must pass join table data as an array.
-
-Reference: sonamu/examples/miomock/api/src/application/project
-
-### Handling ManyToMany in SaveParams
-
-**Pattern: Use BaseSchema.partial().extend()**
-
-```typescript
-// project.types.ts (miomock example)
-import { z } from "zod";
-import { ProjectBaseSchema } from "../sonamu.generated";
-
-export const ProjectSaveParams = ProjectBaseSchema.partial({
-  id: true,
-  created_at: true,
-})
-  .extend({
-    employee_ids: z.array(z.number().int().positive()), // ManyToMany: employee
-    tag_ids: z.array(z.number().int().positive()), // ManyToMany: tags
-  })
-  .omit({
-    virtual_test: true, // remove virtual fields
-    virtual_query_test: true,
-    textsearchable_index_col: true, // remove generated fields
-  });
-export type ProjectSaveParams = z.infer<typeof ProjectSaveParams>;
-```
-
-**Important:**
-
-- Since BaseSchema does not have ManyToMany relation fields, add them with `.extend()`
-- Field name should be in the `{relation_name}_ids` form (e.g. employee → employee_ids, tags → tag_ids)
-- Type validation: `z.array(z.number().int().positive())` - only positive integers allowed
-- Remove virtual/generated fields with `.omit()`
-- Bidirectional ManyToMany is managed from one side only (Project only, not Employee)
-
-### Handling in Model.save() (Recommended Pattern)
-
-**Efficient pattern: Delete only changed entries with whereNotIn**
-
-```typescript
-// project.model.ts (miomock example)
-async save(spa: ProjectSaveParams[]): Promise<number[]> {
-  const puri = this.getPuri("w");
-
-  // register
-  spa.forEach(({ employee_ids, tag_ids, ...sp }) => {
-    const project_id = puri.ubRegister("projects", sp);
-
-    employee_ids.forEach((employee_id) => {
-      puri.ubRegister("projects__employees", {
-        project_id,
-        employee_id,
-      });
-    });
-
-    tag_ids.forEach((tag_id) => {
-      puri.ubRegister("project_tags", {
-        project_id,
-        tag_id,
-      });
-    });
-  });
-
-  return puri.transaction(async (trx) => {
-    const ids = await trx.ubUpsert("projects");
-    const peIds = await trx.ubUpsert("projects__employees");
-    const ptIds = await trx.ubUpsert("project_tags");
-
-    // Key: delete only relationships not in the current request with whereNotIn (efficient)
-    await trx
-      .table("projects__employees")
-      .whereIn("project_id", ids)
-      .whereNotIn("id", peIds)  // delete only those not in ubUpsert result
-      .delete();
-
-    await trx
-      .table("project_tags")
-      .whereIn("project_id", ids)
-      .whereNotIn("id", ptIds)
-      .delete();
-
-    return ids;
-  });
-}
-```
-
-**Basic pattern: Delete all then re-register (simple but inefficient)**
-
-```typescript
-async save(spa: QuestionCollectionSaveParams[]): Promise<number[]> {
-  const wdb = this.getPuri("w");
-
-  const categoryIdsList: (number[] | undefined)[] = [];
-  spa.forEach((sp) => {
-    const { category_ids, ...collectionData } = sp as QuestionCollectionSaveParams;
-    categoryIdsList.push(category_ids);
-    wdb.ubRegister("question_collections", collectionData);
-  });
-
-  return wdb.transaction(async (trx) => {
-    const ids = await trx.ubUpsert("question_collections");
-
-    // Delete all (inefficient but simple)
-    await trx
-      .table("question_collections__survey_categories")
-      .whereIn("question_collection_id", ids)
-      .delete();
-
-    // Register new relationships
-    ids.forEach((collectionId, index) => {
-      const categoryIds = categoryIdsList[index];
-      if (categoryIds && categoryIds.length > 0) {
-        categoryIds.forEach((categoryId) => {
-          trx.ubRegister("question_collections__survey_categories", {
-            question_collection_id: collectionId,
-            survey_category_id: categoryId,
-          });
-        });
-      }
-    });
-
-    await trx.ubUpsert("question_collections__survey_categories");
-    return ids;
-  });
-}
-```
-
-### Notes on Update
-
-When re-saving data queried in an update test, ManyToMany relationship fields must be provided again:
-
-```typescript
-// WRONG - saving without category_ids will delete all relationships
-const { categories, ...collectionData } = collection;
-await QuestionCollectionModel.save([{ ...collectionData, title: "Updated Title" }]);
-
-// CORRECT - extract ids from categories and pass them
-const { categories, ...collectionData } = collection;
-const category_ids = categories?.map((c) => c.id) ?? [];
-await QuestionCollectionModel.save([{ ...collectionData, category_ids, title: "Updated Title" }]);
-```
-
-### Managing Bidirectional ManyToMany
-
-**Principle: Manage from one side only**
-
-```typescript
-// Project Entity: employee (ManyToMany)
-// Employee Entity: projs (ManyToMany, same join table)
-
-// project.types.ts - manages employee_ids
-export const ProjectSaveParams = ProjectBaseSchema.extend({
-  employee_ids: z.array(z.number().int().positive()),
-});
-
-// employee.types.ts - does not manage proj_ids
-export const EmployeeSaveParams = EmployeeBaseSchema.partial({ id: true, created_at: true });
-// proj_ids is not added
-```
-
-**Reason:**
-
-- Managing from both sides causes synchronization issues
-- Managing from the primary Entity (Project) only is clearer
-- When querying Employee, projs are automatically joined and returned