sonamu 0.8.26 → 0.9.0

package/src/skills/sonamu/fixture-cli.md

@@ -25,19 +25,19 @@ production/development master (live DB)
 
 ### Role of Each DB
 
-| DB | Purpose | Data origin |
-|----|---------|-------------|
-| `project` | Production/development live DB | Real user data |
+| DB                | Purpose                          | Data origin                             |
+| ----------------- | -------------------------------- | --------------------------------------- |
+| `project`         | Production/development live DB   | Real user data                          |
 | `project_fixture` | Reference data store for testing | Imported via fetch or generated via gen |
-| `project_test` | Test execution environment | Synced from fixture |
+| `project_test`    | Test execution environment       | Synced from fixture                     |
 
 ### Which DB Each Command Uses
 
-| Command | sourceDb | targetDb | Description |
-|---------|----------|----------|-------------|
-| `fixture gen` | fixture DB | fixture DB | Resolves and generates relations within the fixture DB |
-| `fixture fetch` | production master | fixture DB | Imports from live DB → fixture DB |
-| `fixture sync` | fixture DB | test DB | Synchronizes fixture DB → test DB (existing behavior) |
+| Command         | sourceDb          | targetDb   | Description                                            |
+| --------------- | ----------------- | ---------- | ------------------------------------------------------ |
+| `fixture gen`   | fixture DB        | fixture DB | Resolves and generates relations within the fixture DB |
+| `fixture fetch` | production master | fixture DB | Imports from live DB → fixture DB                      |
+| `fixture sync`  | fixture DB        | test DB    | Synchronizes fixture DB → test DB (existing behavior)  |
 
 **CRITICAL**: Incorrect sourceDb or targetDb settings will cause FK reference errors.
 
@@ -125,13 +125,14 @@ pnpm sonamu fixture fetch --all --strategy recent --limit 3
 
 #### Strategies
 
-| Strategy | Description | Example |
-|----------|-------------|---------|
+| Strategy | Description                      | Example                        |
+| -------- | -------------------------------- | ------------------------------ |
 | `recent` | Most recent data (by created_at) | `--strategy recent --limit 10` |
-| `sample` | Uniform sampling | `--strategy sample --limit 10` |
-| `random` | Random sampling | `--strategy random --limit 10` |
+| `sample` | Uniform sampling                 | `--strategy sample --limit 10` |
+| `random` | Random sampling                  | `--strategy random --limit 10` |
 
 **CRITICAL**: fetch retrieves related data **recursively** (maxDepth: 2)
+
 - Fetching User → also imports User's department and institution
 - Fetching Post → also imports Post's author (User)
 
@@ -229,10 +230,12 @@ pnpm sonamu fixture sync
 FixtureGenerator automatically generates Korean data for specific field names:
 
 **Fields with automatic Korean generation**:
+
 - `name`, `username`: Korean full name (`fakerKO.person.fullName()`)
 - Entity is `Department` and prop is `name`: Korean department name
 
 **Example output**:
+
 ```typescript
 // User
 { name: "김민준", username: "이서연" }
@@ -242,6 +245,7 @@ FixtureGenerator automatically generates Korean data for specific field names:
 ```
 
 **Customization**:
+
 ```typescript
 // Edit in fixture-generator.ts
 if (entity?.id === "Department" && prop.name === "name") {
@@ -255,21 +259,23 @@ if (entity?.id === "Department" && prop.name === "name") {
 Fields with unique constraints require a deduplication strategy.
 
 **Problem**:
+
 ```sql
 -- departments table
 UNIQUE (company_id, name)
 ```
 
 **Solution: Automatic variation**
+
 ```typescript
 // Prevents "개발팀" from being generated multiple times under the same company_id
 // Automatically adds prefix/suffix with 70% probability
 
 // Result:
-"개발팀"           // 30%
-"개발팀 1팀"       // 20%
-"개발팀 본부"      // 20%
-"글로벌 개발팀"    // 30%
+"개발팀"; // 30%
+"개발팀 1팀"; // 20%
+"개발팀 본부"; // 20%
+"글로벌 개발팀"; // 30%
 ```
 
 **Implementation location**: `generateDefaultValue()` in `fixture-generator.ts`
@@ -279,6 +285,7 @@ UNIQUE (company_id, name)
 BelongsToOne relations auto-generate a `{name}_id` column, so code must use the `_id` suffix.
 
 **Entity definition**:
+
 ```json
 {
   "type": "relation",
@@ -289,15 +296,17 @@ BelongsToOne relations auto-generate a `{name}_id` column, so code must use the
 ```
 
 **Inside FixtureGenerator**:
+
 ```typescript
 // ✓ CORRECT
-fixture[`${prop.name}_id`] = relationValue;  // company_id
+fixture[`${prop.name}_id`] = relationValue; // company_id
 
 // ✗ WRONG
-fixture[prop.name] = relationValue;  // company (FK saved as NULL!)
+fixture[prop.name] = relationValue; // company (FK saved as NULL!)
 ```
 
 **Easy to get wrong because**:
+
 - Entity JSON defines `name: "company"`
 - DB column is auto-created as `company_id`
 - Code must use `company_id`
@@ -307,6 +316,7 @@ fixture[prop.name] = relationValue;  // company (FK saved as NULL!)
 fixture gen **automatically sorts by dependency order** (uses FixtureManager's RelationGraph).
 
 **Example**:
+
 ```bash
 # Department references Company, but no need to worry about order
 pnpm sonamu fixture gen --include Department,Company --count 5
@@ -327,6 +337,7 @@ pnpm sonamu fixture gen --include Department,Company --count 5
 After generating fixtures, ID sequences may be out of sync.
 
 **Check**:
+
 ```bash
 PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project_fixture -c "
 SELECT sequencename, last_value
@@ -337,6 +348,7 @@ ORDER BY sequencename;
 ```
 
 **Reset**:
+
 ```sql
 -- Per table
 SELECT setval('departments_id_seq', (SELECT MAX(id) FROM departments), true);
@@ -344,6 +356,7 @@ SELECT setval('companies_id_seq', (SELECT MAX(id) FROM companies), true);
 ```
 
 **Automated**:
+
 ```bash
 # Reset all sequences script
 PGPASSWORD=1234 psql -h 0.0.0.0 -U postgres -d project_fixture -c "
@@ -371,6 +384,7 @@ git commit -m "Add user fixtures for testing"
 ```
 
 **When to use**:
+
 - Consistent test data needed in CI/CD environments
 - Reproducing specific scenarios
 - Sharing test data across team members
@@ -404,6 +418,7 @@ Adding `cone` metadata to Entity JSON gives you finer control over fixture gener
 ```
 
 **Supported strategies**:
+
 - `sample`: Uniform sampling
 - `recent`: Most recent data (by created_at)
 - `random`: Random sampling
@@ -450,10 +465,12 @@ Adding `cone` metadata to Entity JSON gives you finer control over fixture gener
 ```
 
 **How it works**:
+
 - Without `--use-llm`: serves only as a reference description for developers/LLMs (used by cone-generator when generating metadata)
 - With `--use-llm`: fixture gen calls the Claude API and generates actual values based on the note content
 
 **Use cases**:
+
 - Contextual text that is hard to express with simple faker.js (self-introductions, descriptions, etc.)
 - Explaining the field's meaning and generation pattern to developers
 - No length limit (short patterns or long descriptions are both fine)
@@ -511,11 +528,11 @@ export default defineConfig({
 
 #### When to choose note vs fixtureGenerator
 
-| Situation | Recommended |
-|-----------|-------------|
-| Simple values such as email, name, number | `fixtureGenerator` (faker.js) |
-| Contextual text such as self-introductions or descriptions | `cone.note` + `--use-llm` (LLM) |
-| Selecting from a specific list of values | `fixtureGenerator` (arrayElement) |
+| Situation                                                  | Recommended                       |
+| ---------------------------------------------------------- | --------------------------------- |
+| Simple values such as email, name, number                  | `fixtureGenerator` (faker.js)     |
+| Contextual text such as self-introductions or descriptions | `cone.note` + `--use-llm` (LLM)   |
+| Selecting from a specific list of values                   | `fixtureGenerator` (arrayElement) |
 
 ---
 
@@ -523,12 +540,12 @@ export default defineConfig({
 
 **Source:** `modules/sonamu/src/testing/fixture-generator.ts`
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `locale` | `"ko"` \| `"en"` \| `"ja"` | `"ko"` | Locale for generated data |
-| `useLLM` | boolean | `false` | LLM-based data generation (`--use-llm`) |
-| `enableLLMCache` | boolean | `true` | Cache LLM results (disable with `--no-cache`) |
-| `llmModel` | string | `"claude-sonnet-4-5"` | LLM model to use |
+| Option           | Type                       | Default               | Description                                   |
+| ---------------- | -------------------------- | --------------------- | --------------------------------------------- |
+| `locale`         | `"ko"` \| `"en"` \| `"ja"` | `"ko"`                | Locale for generated data                     |
+| `useLLM`         | boolean                    | `false`               | LLM-based data generation (`--use-llm`)       |
+| `enableLLMCache` | boolean                    | `true`                | Cache LLM results (disable with `--no-cache`) |
+| `llmModel`       | string                     | `"claude-sonnet-4-5"` | LLM model to use                              |
 
 ---
 
@@ -539,6 +556,7 @@ export default defineConfig({
 **Cause**: BelongsToOne relation is non-nullable but there is no data to reference
 
 **Solution**:
+
 ```bash
 # Generate the referenced Entity first
 pnpm sonamu fixture gen --include Company --count 5
@@ -548,6 +566,7 @@ pnpm sonamu fixture gen --include Department --count 10
 ```
 
 Or:
+
 ```bash
 # Generate together (auto-sorted by dependency order)
 pnpm sonamu fixture gen --include Company,Department --count 5
@@ -558,6 +577,7 @@ pnpm sonamu fixture gen --include Company,Department --count 5
 **Cause**: Duplicate values generated for a field with a unique constraint
 
 **Solution**:
+
 1. Modify the per-field generation logic for that Entity in `fixture-generator.ts`
 2. Add prefix/suffix or use UUID
 3. Reduce count
@@ -567,6 +587,7 @@ pnpm sonamu fixture gen --include Company,Department --count 5
 **Cause**: Incorrect sourceDb/targetDb configuration
 
 **Check**:
+
 ```typescript
 // Verify in fixture.ts
 const fixtureDb = createKnexInstance(Sonamu.dbConfig.fixture);
@@ -574,6 +595,7 @@ const generator = new FixtureGenerator(fixtureDb, fixtureDb, "fixture", EntityMa
 ```
 
 **Correct configuration**:
+
 - `fixture gen`: sourceDb = fixtureDb, targetDb = fixtureDb
 - `fixture fetch`: sourceDb = production, targetDb = fixtureDb
 

package/src/skills/sonamu/framework-change.md

@@ -13,12 +13,12 @@ Criteria for deciding whether to directly modify the framework or apply a projec
 
 Evaluate along the following 4 axes:
 
-| Axis | Project workaround | Framework fix |
-|----|-------------|----------------|
-| **Reproduction scope** | Only occurs in specific usage patterns | Occurs regardless of usage pattern |
-| **Workaround cost** | Resolved by modifying one place in the project | Workaround must be propagated to all projects |
-| **Impact scope** | Uncertain ripple effects on other projects if framework is changed | Change scope is isolated and side effects are clear |
-| **Ownership** | The code has a known author and discussion is needed | Bug is clear and a review path is available |
+| Axis                   | Project workaround                                                 | Framework fix                                       |
+| ---------------------- | ------------------------------------------------------------------ | --------------------------------------------------- |
+| **Reproduction scope** | Only occurs in specific usage patterns                             | Occurs regardless of usage pattern                  |
+| **Workaround cost**    | Resolved by modifying one place in the project                     | Workaround must be propagated to all projects       |
+| **Impact scope**       | Uncertain ripple effects on other projects if framework is changed | Change scope is isolated and side effects are clear |
+| **Ownership**          | The code has a known author and discussion is needed               | Bug is clear and a review path is available         |
 
 **Criteria for choosing project workaround**: If 2 or more of the 4 axes lean toward "project workaround", apply the workaround first.
 
@@ -62,6 +62,7 @@ async upload(entity_type: string, entity_id: number, file_type: string)
 ```
 
 Generated result:
+
 ```typescript
 // mutationFn only passes params.params and params.files (entity_id and file_type are missing)
 mutationFn: (params: { params: string; ... }) => upload(params.params, params.files)
@@ -77,11 +78,12 @@ async upload(params: { entity_type: string; entity_id: number; file_type: string
 The Sonamu backend automatically deserializes nested formData in the form `params[entity_type]` using `qs`, so this has no effect on runtime behavior.
 
 Call-site pattern:
+
 ```typescript
 uploadMutation.mutate({
   params: { entity_type, entity_id, file_type },
   files,
-})
+});
 ```
 
 **Rule**: If an `@upload` method requires 2 or more parameters, always wrap them in a single object.

package/src/skills/sonamu/frontend.md

@@ -9,56 +9,56 @@ description: Sonamu frontend integration. Auto-generated Service, TanStack Query
 
 ### Hooks
 
-| Hook            | Purpose                              | Key Return Values                                        |
-| --------------- | ------------------------------------ | -------------------------------------------------------- |
-| `useTypeForm`   | Form state management (Zod-based)    | form, setForm, register, submit, addError, reset |
-| `useListParams` | URL-synced list parameters           | listParams, setListParams, register              |
-| `useSelection`  | Checkbox multi-selection             | selectedKeys, toggle, selectAll, deselectAll     |
-| `useModal`      | Modal state management               | open, modal                                      |
-| `useToast`      | Toast notifications                  | toast                                            |
+| Hook            | Purpose                           | Key Return Values                                |
+| --------------- | --------------------------------- | ------------------------------------------------ |
+| `useTypeForm`   | Form state management (Zod-based) | form, setForm, register, submit, addError, reset |
+| `useListParams` | URL-synced list parameters        | listParams, setListParams, register              |
+| `useSelection`  | Checkbox multi-selection          | selectedKeys, toggle, selectAll, deselectAll     |
+| `useModal`      | Modal state management            | open, modal                                      |
+| `useToast`      | Toast notifications               | toast                                            |
 
 ### Components
 
-| Component     | Purpose              | Key Props                                           |
-| ------------- | -------------------- | --------------------------------------------------- |
-| `Input`       | Text input           | value, onValueChange                                |
-| `Textarea`    | Multi-line input     | value, onValueChange                                |
-| `Checkbox`    | Checkbox             | value (boolean), onValueChange, label               |
-| `Select`      | Single select        | items, value, onValueChange, placeholder, clearable |
-| `MultiSelect` | Multi-select         | options, value (array), onValueChange, maxCount     |
-| `EnumSelect`  | Enum select          | enum, labels, value, onValueChange                  |
-| `FileInput`   | File upload          | uploadMode, viewMode, multiple, maxFiles            |
+| Component     | Purpose          | Key Props                                           |
+| ------------- | ---------------- | --------------------------------------------------- |
+| `Input`       | Text input       | value, onValueChange                                |
+| `Textarea`    | Multi-line input | value, onValueChange                                |
+| `Checkbox`    | Checkbox         | value (boolean), onValueChange, label               |
+| `Select`      | Single select    | items, value, onValueChange, placeholder, clearable |
+| `MultiSelect` | Multi-select     | options, value (array), onValueChange, maxCount     |
+| `EnumSelect`  | Enum select      | enum, labels, value, onValueChange                  |
+| `FileInput`   | File upload      | uploadMode, viewMode, multiple, maxFiles            |
 
 ### Service (Auto-generated)
 
-| Method            | Purpose                  | Example                                |
-| ----------------- | ------------------------ | -------------------------------------- |
-| `get{Entity}`     | Fetch single record      | `UserService.getUser("A", 123)`        |
-| `get{Entities}`   | Fetch list               | `UserService.getUsers("P", params)`    |
-| `save`            | Save (create/update)     | `UserService.save([data])`             |
-| `del`             | Delete                   | `UserService.del([1, 2, 3])`           |
-| `use{Entity}`     | Single fetch hook        | `UserService.useUser("A", id)`         |
-| `use{Entities}`   | List fetch hook          | `UserService.useUsers("P", params)`    |
-| `useSaveMutation` | Save mutation            | `UserService.useSaveMutation()`        |
+| Method            | Purpose              | Example                             |
+| ----------------- | -------------------- | ----------------------------------- |
+| `get{Entity}`     | Fetch single record  | `UserService.getUser("A", 123)`     |
+| `get{Entities}`   | Fetch list           | `UserService.getUsers("P", params)` |
+| `save`            | Save (create/update) | `UserService.save([data])`          |
+| `del`             | Delete               | `UserService.del([1, 2, 3])`        |
+| `use{Entity}`     | Single fetch hook    | `UserService.useUser("A", id)`      |
+| `use{Entities}`   | List fetch hook      | `UserService.useUsers("P", params)` |
+| `useSaveMutation` | Save mutation        | `UserService.useSaveMutation()`     |
 
 ### Utilities
 
-| Function           | Purpose                      | Example                                              |
-| ------------------ | ---------------------------- | ---------------------------------------------------- |
-| `dateF`            | Date formatting              | `dateF(new Date())` → `"2024-01-15"`              |
-| `datetimeF`        | Datetime formatting          | `datetimeF(new Date())` → `"2024-01-15 10:30:00"` |
-| `numF`             | Number formatting            | `numF(1234567)` → `"1,234,567"`                   |
-| `hidden`           | Conditional hidden class     | `hidden(true)` → `"hidden"`                       |
-| `arrayableToArray` | Convert to array             | `arrayableToArray("a")` → `["a"]`                 |
+| Function           | Purpose                  | Example                                           |
+| ------------------ | ------------------------ | ------------------------------------------------- |
+| `dateF`            | Date formatting          | `dateF(new Date())` → `"2024-01-15"`              |
+| `datetimeF`        | Datetime formatting      | `datetimeF(new Date())` → `"2024-01-15 10:30:00"` |
+| `numF`             | Number formatting        | `numF(1234567)` → `"1,234,567"`                   |
+| `hidden`           | Conditional hidden class | `hidden(true)` → `"hidden"`                       |
+| `arrayableToArray` | Convert to array         | `arrayableToArray("a")` → `["a"]`                 |
 
 ### Configuration
 
-| Item             | Description                                      | Required                                  |
-| ---------------- | ------------------------------------------------ | ----------------------------------------- |
+| Item             | Description                                        | Required                                   |
+| ---------------- | -------------------------------------------------- | ------------------------------------------ |
 | `SonamuProvider` | Global configuration Provider (uploader, auth, SD) | Required (uploader required for FileInput) |
-| `uploader`       | File upload function                             | Required when using FileInput             |
-| `auth`           | Authentication state and functions               | Optional                                  |
-| `SD`             | Internationalization function                    | Optional                                  |
+| `uploader`       | File upload function                               | Required when using FileInput              |
+| `auth`           | Authentication state and functions                 | Optional                                   |
+| `SD`             | Internationalization function                      | Optional                                   |
 
 ---
 
@@ -76,9 +76,7 @@ const user = await UserService.getUser("A", 123);
 const { rows, total } = await UserService.getUsers("P", { num: 20, page: 1 });
 
 // Save
-const [userId] = await UserService.save([
-  { email: "new@test.com", username: "newuser" },
-]);
+const [userId] = await UserService.save([{ email: "new@test.com", username: "newuser" }]);
 
 // Delete
 const count = await UserService.del([1, 2, 3]);
@@ -139,28 +137,22 @@ Type-safe form management based on Zod schemas (react-components v0.1.8+)
 ### Return Values
 
 ```typescript
-const {
-  form,
-  setForm,
-  register,
-  submit,
-  addError,
-  removeError,
-  clearError,
-  reset,
-} = useTypeForm(Schema, defaultValue);
+const { form, setForm, register, submit, addError, removeError, clearError, reset } = useTypeForm(
+  Schema,
+  defaultValue,
+);
 ```
 
-| Return Value  | Type                                                | Description                              |
-| ------------- | --------------------------------------------------- | ---------------------------------------- |
-| `form`        | `z.infer<Schema>`                                   | Current form data                        |
-| `setForm`     | `React.Dispatch<SetStateAction<...>>`               | Form state update function               |
-| `register`    | `(field: string) => RegisterReturn`                 | Field registration function              |
-| `submit`      | `(callback) => () => Promise<R>`                    | Submit handler factory                   |
-| `addError`    | `(path: string, error: string \| ErrorObj) => void` | Manually add an error                    |
-| `removeError` | `(path: string) => void`                            | Remove error for a specific field        |
-| `clearError`  | `() => void`                                        | Clear all errors                         |
-| `reset`       | `() => void`                                        | Reset form to defaultValue               |
+| Return Value  | Type                                                | Description                       |
+| ------------- | --------------------------------------------------- | --------------------------------- |
+| `form`        | `z.infer<Schema>`                                   | Current form data                 |
+| `setForm`     | `React.Dispatch<SetStateAction<...>>`               | Form state update function        |
+| `register`    | `(field: string) => RegisterReturn`                 | Field registration function       |
+| `submit`      | `(callback) => () => Promise<R>`                    | Submit handler factory            |
+| `addError`    | `(path: string, error: string \| ErrorObj) => void` | Manually add an error             |
+| `removeError` | `(path: string) => void`                            | Remove error for a specific field |
+| `clearError`  | `() => void`                                        | Clear all errors                  |
+| `reset`       | `() => void`                                        | Reset form to defaultValue        |
 
 ### register Return Object
 
@@ -197,9 +189,7 @@ function RegisterForm() {
   return (
     <form>
       <Input {...emailProps} />
-      {emailProps.error && (
-        <span className="error">{emailProps.error.content}</span>
-      )}
+      {emailProps.error && <span className="error">{emailProps.error.content}</span>}
 
       {/* Method 2: inline (for short cases) */}
       <Input {...register("username")} />
@@ -258,14 +248,14 @@ import { Input, Checkbox, Select, Textarea } from "@sonamu-kit/react-components/
 
 Fields defined as required in SaveParams **must be included** in the form initial values:
 
-| Type              | Initial Value          |
-| ----------------- | ---------------------- |
-| string (required) | `""`                   |
-| number (required) | `0`                    |
-| Date (required)   | `new Date()`           |
+| Type              | Initial Value                  |
+| ----------------- | ------------------------------ |
+| string (required) | `""`                           |
+| number (required) | `0`                            |
+| Date (required)   | `new Date()`                   |
 | enum (required)   | Default value (e.g. `"draft"`) |
-| FK (required)     | `0`                    |
-| nullable          | `null`                 |
+| FK (required)     | `0`                            |
+| nullable          | `null`                         |
 
 ```typescript
 const { form, setForm, register } = useTypeForm(TaskSaveParams, {
@@ -286,14 +276,7 @@ If a scaffolded form accesses relation objects like `row.collection?.id`, that r
 
 ```json
 // question.entity.json > subsets > A
-[
-  "id",
-  "content",
-  "collection.id",
-  "collection.title",
-  "parent.id",
-  "answer_group.id"
-]
+["id", "content", "collection.id", "collection.title", "parent.id", "answer_group.id"]
 ```
 
 **Alternative**: If the FK is already on `row`, using `...row` alone is sufficient without accessing the relation (no subset modification needed)
@@ -542,11 +525,13 @@ function UserForm() {
 ```
 
 **Notes**:
+
 - You must explicitly reset lower values to `null` when a higher-level value changes. IdAsyncSelect does not reset automatically.
 - Using the `disabled` prop to disable lower levels when the parent is not selected improves UX.
 - If `baseListParams` is `undefined`, IdAsyncSelect stays in enabled=false state and does not fetch.
 
 **Items to specify in Spec** (recommended to add to acceptanceCriteria in spec.json when cascade is present):
+
 ```json
 "acceptanceCriteria": [
   "When a department is selected, only divisions belonging to that department appear in the dropdown",
@@ -850,10 +835,7 @@ import { registerSSR } from "sonamu/ssr";
 
 registerSSR({
   path: "/companies/:companyId",
-  preload: (params) => [
-    UserService.me(),
-    CompanyService.findById("A", Number(params.companyId)),
-  ],
+  preload: (params) => [UserService.me(), CompanyService.findById("A", Number(params.companyId))],
 });
 ```