sonamu 0.8.26 → 0.9.0

package/src/skills/sonamu/create-sonamu.md

@@ -23,23 +23,23 @@ pnpm create sonamu [project-name] --yes
 
 ### General Options
 
-| Option | Description | Default |
-|------|------|--------|
-| `--yes`, `-y` | Use all options with default values | - |
-| `--skip-pnpm` | Skip pnpm install | false |
-| `--skip-docker` | Skip Docker setup | false |
-| `--pnpm y/n` | Whether to install pnpm | y |
-| `--docker y/n` | Whether to configure Docker | y |
+| Option          | Description                         | Default |
+| --------------- | ----------------------------------- | ------- |
+| `--yes`, `-y`   | Use all options with default values | -       |
+| `--skip-pnpm`   | Skip pnpm install                   | false   |
+| `--skip-docker` | Skip Docker setup                   | false   |
+| `--pnpm y/n`    | Whether to install pnpm             | y       |
+| `--docker y/n`  | Whether to configure Docker         | y       |
 
 ### Docker/DB Options
 
-| Option | Description | Default |
-|------|------|--------|
-| `--docker-project` | Docker project name | `[project-name]-docker` |
-| `--container-name` | Container name | `[project-name]-container` |
-| `--db-name` | Database name | `[project-name]` |
-| `--db-user` | DB user | `postgres` |
-| `--db-password` | DB password | `1234` |
+| Option             | Description         | Default                    |
+| ------------------ | ------------------- | -------------------------- |
+| `--docker-project` | Docker project name | `[project-name]-docker`    |
+| `--container-name` | Container name      | `[project-name]-container` |
+| `--db-name`        | Database name       | `[project-name]`           |
+| `--db-user`        | DB user             | `postgres`                 |
+| `--db-password`    | DB password         | `1234`                     |
 
 ## Usage Examples
 
@@ -97,20 +97,25 @@ pnpm create sonamu my_project \
 ## Next Steps After Creation
 
 1. Start the DB container (if Docker was configured)
+
    ```bash
    cd [project-name]/packages/api/
    pnpm docker:up
    ```
+
    > If a port conflict error occurs → see `database.md`
 
 2. Sync Skills
+
    ```bash
    cd [project-name]/packages/api
    pnpm sonamu skills sync
    ```
+
    > Will fail if sonamu is an npm version. See "Sonamu Link Setup" below.
 
 3. Start the dev server
+
    ```bash
    cd [project-name]/packages/api
    pnpm dev
@@ -137,6 +142,7 @@ Check the sonamu dependency in `packages/api/package.json`:
 ### How to change to a link
 
 1. Change the sonamu version to a link in `packages/api/package.json`:
+
    ```json
    "dependencies": {
      "sonamu": "link:/path/to/sonamu/modules/sonamu"
@@ -149,10 +155,10 @@ Check the sonamu dependency in `packages/api/package.json`:
 
 ### Link path examples
 
-| sonamu location | Link path |
-|------------|----------|
-| `~/Development/sonamu` | `link:~/Development/sonamu/modules/sonamu` |
-| Same directory as project | `link:../../sonamu/modules/sonamu` |
+| sonamu location           | Link path                                  |
+| ------------------------- | ------------------------------------------ |
+| `~/Development/sonamu`    | `link:~/Development/sonamu/modules/sonamu` |
+| Same directory as project | `link:../../sonamu/modules/sonamu`         |
 
 ## Renaming the Project (when creating a new project)
 
@@ -161,28 +167,34 @@ After generating the project, you need to replace the "Sonamu" text in the front
 **4 files to update:**
 
 1. **`packages/web/index.html`** - Browser tab title
+
 ```html
 <title>{project-name}</title>
 ```
 
 2. **`packages/web/src/routes/__root.tsx`** - TanStack Router head configuration (most important!)
+
 ```typescript
 head: () => ({
   meta: [{ title: "{project-name}" }],
 }),
 ```
+
 **Important:** If you don't update `__root.tsx`, the title will revert to "Sonamu" on HMR!
 
 3. **`packages/web/src/routes/index.tsx`** - Main page title
+
 ```tsx
-<h1 className="text-2xl font-bold mb-4">Welcome to {project-name}</h1>
+<h1 className="text-2xl font-bold mb-4">Welcome to {project - name}</h1>
 ```
 
 4. **`packages/web/src/components/Sidebar.tsx`** - Sidebar app name
+
 ```typescript
 const title = isAdmin ? "Admin" : "{project-name}";
 ```
 
 **How to verify:**
+
 - Check that the project name is shown in the browser tab
 - Confirm that the tab title does not change on file save via HMR (if it does, `__root.tsx` is missing)

package/src/skills/sonamu/database.md

@@ -26,34 +26,40 @@ production/development master (actual DB)
 
 ### Role of Each DB
 
-| DB | Purpose | Data Source | Command |
-|----|---------|------------|---------|
-| `project` | Production/development actual DB | Real user data | Created directly |
+| DB                | Purpose                          | Data Source                                   | Command                         |
+| ----------------- | -------------------------------- | --------------------------------------------- | ------------------------------- |
+| `project`         | Production/development actual DB | Real user data                                | Created directly                |
 | `project_fixture` | Reference data store for testing | Fetched from production or generated with gen | `pnpm sonamu fixture gen/fetch` |
-| `project_test` | Test execution environment | Synced from fixture | `pnpm sonamu fixture sync` |
+| `project_test`    | Test execution environment       | Synced from fixture                           | `pnpm sonamu fixture sync`      |
 
 ### Data Flow
 
 **1. fixture fetch (fetch real data)**
+
 ```bash
 pnpm sonamu fixture fetch --include User --limit 10
 ```
+
 - production/development master → fixture DB
 - Copies actual production data for testing
 - Related data (FKs) is also fetched
 
 **2. fixture gen (generate dummy data)**
+
 ```bash
 pnpm sonamu fixture gen --include Department --count 5
 ```
+
 - Generated inside fixture DB using faker
 - Automatically resolves reference relationships (FKs)
 - Supports Korean data generation
 
 **3. fixture sync (sync test DB)**
+
 ```bash
 pnpm sonamu fixture sync
 ```
+
 - fixture DB → test DB
 - Sync to the latest state before running tests
 - Each test is isolated with a transaction that auto-rolls back
@@ -67,6 +73,7 @@ pnpm sonamu fixture sync
 - Incorrect configuration causes FK reference errors
 
 **Example (correct configuration)**:
+
 ```typescript
 // fixture gen: reference and save within fixture DB
 const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
@@ -90,10 +97,10 @@ Base data for testing (seed data) is managed by adding it to dump files.
 
 Seed data management proceeds in 2 phases:
 
-| Phase | Purpose | Target DB |
-|-------|---------|-----------|
+| Phase       | Purpose                              | Target DB                         |
+| ----------- | ------------------------------------ | --------------------------------- |
 | **Phase 1** | Prepare seed for development/testing | `project_test`, `project_fixture` |
-| **Phase 2** | Apply seed to the actual DB | `project` (actual DB) |
+| **Phase 2** | Apply seed to the actual DB          | `project` (actual DB)             |
 
 ---
 
@@ -108,6 +115,7 @@ pnpm dump
 ```
 
 The `database/scripts/dump.sql` generated at this point contains:
+
 - CREATE TABLE statements
 - CREATE SEQUENCE statements
 - ALTER TABLE ... PRIMARY KEY
@@ -119,6 +127,7 @@ The `database/scripts/dump.sql` generated at this point contains:
 Open `database/scripts/dump.sql` and add INSERT statements **before the FK CONSTRAINT** section.
 
 **Important: Write in order considering FK dependency order**
+
 ```sql
 -- Independent tables first
 INSERT INTO public.institutions (id, created_at, name, code) VALUES
@@ -140,6 +149,7 @@ pnpm seed
 ```
 
 `database/scripts/seed.sh` runs and:
+
 - `SOURCE_DB="${DATABASE_NAME}_test"` → applies dump.sql to the test DB
 
 #### 1-4. Sync to Fixture DB
@@ -155,11 +165,13 @@ Copies test DB data to the fixture DB.
 ### Phase 2: Apply Seed to Actual DB
 
 **⚠️ CRITICAL WARNING:**
+
 - This step inserts data into the actual DB (`project`)
 - Existing data may be overwritten
 - **You must confirm with the user before proceeding**
 
 **Claude Code Rules:**
+
 ```
 Before applying seed to the actual DB:
 1. Ask the user: "Would you like to apply seed data to the actual database (project)?"
@@ -225,13 +237,13 @@ FIXTURE_DB="${DATABASE_NAME}_fixture"  # restored
 
 ### Summary: Phase 1 vs Phase 2
 
-| Item | Phase 1 (Development/Testing) | Phase 2 (Actual DB) |
-|------|-------------------------------|---------------------|
-| **Timing** | Preparing test data during development | Preparing actual data after development is complete |
-| **Dump count** | 1 time (table structure) | 2 times (includes data) |
-| **Target DB** | `project_test` → `project_fixture` | `project` |
-| **seed.sh** | `FIXTURE_DB="${DATABASE_NAME}_fixture"` | `FIXTURE_DB="${DATABASE_NAME}"` |
-| **User approval** | Not required | **Required** |
+| Item              | Phase 1 (Development/Testing)           | Phase 2 (Actual DB)                                 |
+| ----------------- | --------------------------------------- | --------------------------------------------------- |
+| **Timing**        | Preparing test data during development  | Preparing actual data after development is complete |
+| **Dump count**    | 1 time (table structure)                | 2 times (includes data)                             |
+| **Target DB**     | `project_test` → `project_fixture`      | `project`                                           |
+| **seed.sh**       | `FIXTURE_DB="${DATABASE_NAME}_fixture"` | `FIXTURE_DB="${DATABASE_NAME}"`                     |
+| **User approval** | Not required                            | **Required**                                        |
 
 ---
 
@@ -288,7 +300,7 @@ ALTER TABLE ONLY public.companies ADD CONSTRAINT companies_pkey PRIMARY KEY (id)
 CREATE INDEX projects_name_description_pgroonga_index ON public.projects ...;
 
 -- 2024~: ALTER TABLE ... FOREIGN KEY (FK constraint - data must exist before this!)
-ALTER TABLE ONLY public.departments 
+ALTER TABLE ONLY public.departments
     ADD CONSTRAINT departments_company_id_foreign FOREIGN KEY (company_id) REFERENCES public.companies(id);
 ```
 
@@ -296,10 +308,10 @@ ALTER TABLE ONLY public.departments
 
 **Seed data must be added before FK CONSTRAINTs.**
 
-| Position | Result |
-|----------|--------|
-| Before FK CONSTRAINT | OK - FK check after data insertion |
-| After FK CONSTRAINT | FAIL - FK violation because referenced table has no data |
+| Position             | Result                                                   |
+| -------------------- | -------------------------------------------------------- |
+| Before FK CONSTRAINT | OK - FK check after data insertion                       |
+| After FK CONSTRAINT  | FAIL - FK violation because referenced table has no data |
 
 ### Table Dependency Order
 
@@ -330,11 +342,11 @@ SELECT pg_catalog.setval('public.departments_id_seq', 5, true);
 
 ```sql
 -- institutions (independent)
-INSERT INTO public.institutions (id, created_at, name, code) VALUES 
+INSERT INTO public.institutions (id, created_at, name, code) VALUES
   (1, '2024-01-01 00:00:00+09', 'Headquarters', 'HQ');
 
 -- departments (references institutions)
-INSERT INTO public.departments (id, created_at, name, code, institution_id, is_active) VALUES 
+INSERT INTO public.departments (id, created_at, name, code, institution_id, is_active) VALUES
   (1, '2024-01-01 00:00:00+09', 'Research', 'RND', 1, true);
 
 -- Set sequences
@@ -357,6 +369,7 @@ docker ps --format "table {{.Names}}\t{{.Ports}}"
 ### Step 2: Compare Container Names
 
 **Check the current project's container name:**
+
 ```bash
 # Check CONTAINER_NAME in packages/api/.env
 cat packages/api/.env | grep CONTAINER_NAME
@@ -381,6 +394,7 @@ Another project is using the same port. The new project's port must be changed.
 **Two files to modify:**
 
 1. `packages/api/.env`
+
 ```bash
 # Before
 DB_PORT=5432
@@ -390,6 +404,7 @@ DB_PORT=5433
 ```
 
 2. `packages/api/database/docker-compose.yml`
+
 ```yaml
 # Before
 ports:
@@ -401,6 +416,7 @@ ports:
 ```
 
 3. `packages/api/src/sonamu.config.ts`
+
 ```typescript
 // Before
 port: 5432,
@@ -410,6 +426,7 @@ port: 5433,
 ```
 
 **Port Selection Guide:**
+
 - PostgreSQL default port: 5432
 - Available range: 5433 ~ 5439
 - Check currently used ports with `docker ps` and choose a number that is not duplicated
@@ -422,11 +439,11 @@ pnpm docker:up
 
 ## DB Connection Configuration Files
 
-| File | Purpose |
-|------|---------|
-| `packages/api/.env` | Environment variables (DB_HOST, DB_PORT, DB_USER, etc.) |
-| `packages/api/database/docker-compose.yml` | Docker container configuration |
-| `packages/api/src/sonamu.config.ts` | Sonamu DB connection configuration |
+| File                                       | Purpose                                                 |
+| ------------------------------------------ | ------------------------------------------------------- |
+| `packages/api/.env`                        | Environment variables (DB_HOST, DB_PORT, DB_USER, etc.) |
+| `packages/api/database/docker-compose.yml` | Docker container configuration                          |
+| `packages/api/src/sonamu.config.ts`        | Sonamu DB connection configuration                      |
 
 ## .env Default Settings
 

package/src/skills/sonamu/entity-basic.md

@@ -216,12 +216,12 @@ A top-level option used when a child entity is managed as a dependent of a paren
 
 ### When to use parentId
 
-| Situation | parentId | Example |
-|-----------|----------|---------|
-| Cannot exist without a parent | Yes | OrderItem → Order |
-| Created and deleted together with parent | Yes | Chapter → Course, Lesson → Chapter |
-| Can be independently CRUD'd | No | Comment → Post |
-| Can belong to multiple parents | No | Tag → Post (ManyToMany) |
+| Situation                                | parentId | Example                            |
+| ---------------------------------------- | -------- | ---------------------------------- |
+| Cannot exist without a parent            | Yes      | OrderItem → Order                  |
+| Created and deleted together with parent | Yes      | Chapter → Course, Lesson → Chapter |
+| Can be independently CRUD'd              | No       | Comment → Post                     |
+| Can belong to multiple parents           | No       | Tag → Post (ManyToMany)            |
 
 ### parentId usage example
 
@@ -243,12 +243,12 @@ Child entities with parentId set (e.g., Chapter, Lesson) do not get their own `t
 
 Child entities with parentId must be placed **in the same folder as the root parent entity**.
 
-| Structure | Description |
-|-----------|-------------|
-| `course/course.entity.json` | Root entity |
-| `course/chapter.entity.json` | parentId: "Course" → same folder |
-| `course/lesson.entity.json` | parentId: "Chapter" → same folder (based on root) |
-| `course/course.types.ts` | types.ts generated only for root |
+| Structure                    | Description                                       |
+| ---------------------------- | ------------------------------------------------- |
+| `course/course.entity.json`  | Root entity                                       |
+| `course/chapter.entity.json` | parentId: "Course" → same folder                  |
+| `course/lesson.entity.json`  | parentId: "Chapter" → same folder (based on root) |
+| `course/course.types.ts`     | types.ts generated only for root                  |
 
 **Note:** Do not create child entities in a separate folder (e.g., `chapter/chapter.entity.json`).
 
@@ -344,8 +344,8 @@ Sonamu's `ubUpsert` uses PostgreSQL `ON CONFLICT ... DO UPDATE`, so **all requir
 // example
 {
   "props": [
-    { "name": "title", "type": "string" },    // required (no nullable)
-    { "name": "content", "type": "string" },  // required (no nullable)
+    { "name": "title", "type": "string" }, // required (no nullable)
+    { "name": "content", "type": "string" }, // required (no nullable)
     { "name": "category", "type": "string", "nullable": true } // optional
   ]
 }
@@ -382,7 +382,7 @@ A dedicated prop type that consolidates multiple columns into a single generated
   "props": [
     { "name": "title_ko", "type": "string" },
     { "name": "title_en", "type": "string" },
-    { "name": "tags",     "type": "string[]" },
+    { "name": "tags", "type": "string[]" },
     {
       "name": "search_text",
       "type": "searchText",
@@ -406,10 +406,10 @@ A dedicated prop type that consolidates multiple columns into a single generated
 
 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)` |
+| 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
@@ -440,9 +440,9 @@ SQL expressions per source column type:
 
 **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` |
+| 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:**
@@ -476,20 +476,20 @@ Not a technical decision — ask **"What if the same combination is inserted twi
 
 ## 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`) |
+| 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
 
@@ -556,10 +556,10 @@ 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 |
+| 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:**
 
@@ -586,30 +586,30 @@ PostgreSQL mapping:
 
 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 |
+| 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` | — | — |
+| 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