sonamu 0.9.0 → 0.9.2

package/src/auth/plugins/entity-definitions/api-key.ts

@@ -43,19 +43,13 @@ export const apiKeyEntityDef: BetterAuthEntityDef = {
         { name: "enabled", type: "boolean", desc: "활성화 여부" },
         { name: "permissions", type: "string", nullable: true, desc: "권한" },
         { name: "metadata", type: "string", nullable: true, desc: "메타데이터 (JSON)" },
+        { name: "reference_id", type: "string", desc: "참조 대상 ID" },
+        { name: "config_id", type: "string", dbDefault: "'default'", desc: "설정 ID" },
         { name: "created_at", type: "date", dbDefault: "CURRENT_TIMESTAMP", desc: "생성일시" },
         { name: "updated_at", type: "date", nullable: true, desc: "수정일시" },
-        {
-          type: "relation",
-          name: "user",
-          with: "User",
-          relationType: "BelongsToOne",
-          onDelete: "CASCADE",
-          desc: "사용자",
-        },
       ],
       indexes: [
-        { type: "index", name: "api_keys_user_id_idx", columns: [{ name: "user_id" }] },
+        { type: "index", name: "api_keys_reference_id_idx", columns: [{ name: "reference_id" }] },
         { type: "unique", name: "api_keys_key_unique", columns: [{ name: "key" }] },
       ],
       subsets: {
@@ -80,7 +74,8 @@ export const apiKeyEntityDef: BetterAuthEntityDef = {
           "metadata",
           "created_at",
           "updated_at",
-          "user.id",
+          "reference_id",
+          "config_id",
         ],
       },
       enums: {

package/src/auth/plugins/wrappers/api-key.ts

@@ -1,9 +1,8 @@
-import { apiKey as _apiKey } from "better-auth/plugins";
-import { type ApiKeyOptions } from "better-auth/plugins";
+import { apiKey as _apiKey, type ApiKeyOptions } from "@better-auth/api-key";
 
 import { merge } from "../../../utils/utils";
 
-export type { ApiKeyOptions } from "better-auth/plugins";
+export type { ApiKeyOptions } from "@better-auth/api-key";
 
 /**
  * API Key 플러그인 스키마
@@ -17,7 +16,8 @@ export const API_KEY_SCHEMA: ApiKeyOptions["schema"] = {
   apikey: {
     modelName: "api_keys",
     fields: {
-      userId: "user_id",
+      referenceId: "reference_id",
+      configId: "config_id",
       lastRequest: "last_request",
       requestCount: "request_count",
       rateLimitEnabled: "rate_limit_enabled",

package/src/bin/cli.ts

@@ -309,7 +309,9 @@ function spawnApiDevServer(options?: { extraEnv?: Record<string, string> }) {
  * Sonamu.init 없이 호출될 것을 상정하여 구현되었습니다.
  */
 function dev_all() {
-  console.log(chalk.yellow.bold("Starting Sonamu dev server...\n"));
+  const require = createRequire(import.meta.url);
+  const { version } = require("../../package.json");
+  console.log(`🌲 Sonamu v${version}\n`);
   spawnApiDevServer();
 }
 
@@ -498,6 +500,10 @@ async function runBuildSteps<T>(
  * Sonamu.init 없이 호출될 것을 상정하여 구현되었습니다.
  */
 async function start() {
+  const require = createRequire(import.meta.url);
+  const { version } = require("../../package.json");
+  console.log(`🌲 Sonamu v${version}\n`);
+
   const apiRoot = findApiRootPath();
   const entryPoint = "dist/index.js";
 

package/src/database/knex.ts

@@ -12,12 +12,20 @@ export function createKnexInstance(config: Knex.Config): Knex {
   }
 
   config.pool = {
+    maxConnectionLifetimeMillis: 1800000,
+    maxConnectionLifetimeJitterMillis: 300000,
     ...config.pool,
     propagateCreateError: false,
     idleTimeoutMillis: 10000,
     reapIntervalMillis: 1000,
     acquireTimeoutMillis: 30000,
     createTimeoutMillis: 30000,
+    validate: (connection: unknown) => {
+      if (typeof connection !== "object" || connection === null) return false;
+      const conn = connection as Record<string, unknown>;
+      if (conn._ending === true || conn._closed === true) return false;
+      return true;
+    },
     afterCreate: ((
       conn: Knex.Client & Record<string, unknown>,
       done: (err: Error | null, conn: Knex.Client) => void,
@@ -30,27 +38,9 @@ export function createKnexInstance(config: Knex.Config): Knex {
         stream.stream.setKeepAlive(true, 10000);
       }
 
-      conn.on("error", (err: Error) => {
-        Object.defineProperty(conn, "__knex__disposed", {
-          value: err,
-          writable: true,
-          configurable: true,
-          enumerable: true,
-        });
-      });
-
       done(null, conn);
     }) satisfies Knex.PoolConfig["afterCreate"],
   };
 
-  const knexInstance = knex(config);
-  knexInstance.client.validateConnection = (connection: unknown) => {
-    if (typeof connection !== "object" || connection === null) return false;
-    if ("__knex__disposed" in connection) return false;
-    const conn = connection as Record<string, unknown>;
-    if (conn._ending === true || conn._closed === true) return false;
-    return true;
-  };
-
-  return knexInstance;
+  return knex(config);
 }

package/src/database/puri.ts

@@ -225,23 +225,23 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   }
 
   // Raw functions for SELECT
-  static rawString(sql: string, params: unknown[] = []): SqlExpression<"string"> {
+  static rawString(sql: string, params: Knex.RawBinding[] = []): SqlExpression<"string"> {
     return { _type: "sql_expression", _return: "string", _sql: sql, _params: params };
   }
 
-  static rawStringArray(sql: string, params: unknown[] = []): SqlExpression<"string[]"> {
+  static rawStringArray(sql: string, params: Knex.RawBinding[] = []): SqlExpression<"string[]"> {
     return { _type: "sql_expression", _return: "string[]", _sql: sql, _params: params };
   }
 
-  static rawNumber(sql: string, params: unknown[] = []): SqlExpression<"number"> {
+  static rawNumber(sql: string, params: Knex.RawBinding[] = []): SqlExpression<"number"> {
     return { _type: "sql_expression", _return: "number", _sql: sql, _params: params };
   }
 
-  static rawBoolean(sql: string, params: unknown[] = []): SqlExpression<"boolean"> {
+  static rawBoolean(sql: string, params: Knex.RawBinding[] = []): SqlExpression<"boolean"> {
     return { _type: "sql_expression", _return: "boolean", _sql: sql, _params: params };
   }
 
-  static rawDate(sql: string, params: unknown[] = []): SqlExpression<"date"> {
+  static rawDate(sql: string, params: Knex.RawBinding[] = []): SqlExpression<"date"> {
     return { _type: "sql_expression", _return: "date", _sql: sql, _params: params };
   }
 
@@ -814,7 +814,7 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
   }
 
   // WHERE RAW
-  whereRaw(sql: string, bindings?: readonly unknown[]): this {
+  whereRaw(sql: string, bindings?: readonly Knex.RawBinding[]): this {
     this.knexQuery.whereRaw(sql, bindings);
     return this;
   }

package/src/database/puri.types.ts

@@ -1,5 +1,6 @@
 /* oxlint-disable @typescript-eslint/no-explicit-any */ // Puri.types.ts는 다양한 타입을 사용하고 있습니다.
 
+import { type Knex } from "knex";
 import { type QueryResult } from "pg";
 
 import { type DatabaseForeignKeys, type DatabaseSchemaExtend } from "../types/types";
@@ -308,7 +309,7 @@ export type SqlExpression<
   _type: "sql_expression"; // 또는 "computed_value"
   _return: T;
   _sql: string;
-  _params: unknown[];
+  _params: Knex.RawBinding[];
 };
 
 // 결과 타입 가독성을 위한 타입 확장

package/src/database/upsert-builder.ts

@@ -458,7 +458,7 @@ export class UpsertBuilder {
 
         // 각 FK 컬럼에 대한 WHERE IN 조건 추가
         for (const { column, values } of fkConditions) {
-          deleteQuery = deleteQuery.whereIn(column, values);
+          deleteQuery = deleteQuery.whereIn(column, values as Knex.Value[]);
         }
 
         // 방금 upsert한 ID는 제외

package/src/skills/AGENTS.md

@@ -39,7 +39,7 @@ See `.claude/skills/sonamu/SKILL.md` for the full skill list.
 
 ## Cross-workspace gate
 
-- For changes in this scope, root `pnpm check` (Biome) must pass before handoff.
+- For changes in this scope, root `pnpm check` (oxlint + oxfmt) must pass before handoff.
 
 ## TypeScript type safety policy
 
@@ -54,9 +54,9 @@ See `.claude/skills/sonamu/SKILL.md` for the full skill list.
 After editing any `.ts` or `.tsx` file, always run both checks before considering the task done:
 
 1. `npx tsc --noEmit --skipLibCheck` — type errors
-2. `pnpm biome check <file>` — lint and format
+2. `pnpm check` — lint and format (oxlint + oxfmt)
 
-Do not skip biome check even when tsc passes. Biome catches `noNonNullAssertion`, import order, and formatting issues that tsc does not.
+Do not skip lint/format check even when tsc passes. oxlint catches `noNonNullAssertion`, import order, and other issues that tsc does not.
 
 ## Skill read triggers
 

package/src/skills/project/README.md

@@ -4,9 +4,7 @@
 
 ## 용도
 
-- **requirements.md**: 프로젝트 요구사항 명세
-- **business-logic.md**: 비즈니스 로직 상세 (선택)
-- **architecture.md**: 아키텍처 설계 문서 (선택)
+- **architecture.md**: 아키텍처 설계 문서
 
 ## 사용 방법
 

package/src/skills/sonamu/auth-plugins.md

@@ -18,18 +18,18 @@ Use the `auth generate --plugins` command to auto-generate plugin entities.
 
 ## Supported Plugins
 
-| Plugin ID      | Wrapper function | Package                | Purpose                                               |
-| -------------- | ---------------- | ---------------------- | ----------------------------------------------------- |
-| `admin`        | `admin()`        | `better-auth/plugins`  | Admin features, user ban/unban, session impersonation |
-| `organization` | `organization()` | `better-auth/plugins`  | Organization, team, member, and invitation management |
-| `2fa`          | `twoFactor()`    | `better-auth/plugins`  | TOTP-based two-factor authentication                  |
-| `username`     | `username()`     | `better-auth/plugins`  | Username-based authentication                         |
-| `phone-number` | `phoneNumber()`  | `better-auth/plugins`  | Phone number authentication                           |
-| `api-key`      | `apiKey()`       | `better-auth/plugins`  | API key issuance/management, rate limiting            |
-| `jwt`          | `jwt()`          | `better-auth/plugins`  | JWT tokens + JWKS key management                      |
-| `passkey`      | `passkey()`      | `@better-auth/passkey` | WebAuthn/Passkey authentication                       |
-| `sso`          | `sso()`          | `@better-auth/sso`     | OIDC/SAML SSO integration                             |
-| `anonymous`    | `anonymous()`    | `better-auth/plugins`  | Anonymous user support                                |
+| Plugin ID      | Wrapper function | Package                 | Purpose                                               |
+| -------------- | ---------------- | ----------------------- | ----------------------------------------------------- |
+| `admin`        | `admin()`        | `better-auth/plugins`   | Admin features, user ban/unban, session impersonation |
+| `organization` | `organization()` | `better-auth/plugins`   | Organization, team, member, and invitation management |
+| `2fa`          | `twoFactor()`    | `better-auth/plugins`   | TOTP-based two-factor authentication                  |
+| `username`     | `username()`     | `better-auth/plugins`   | Username-based authentication                         |
+| `phone-number` | `phoneNumber()`  | `better-auth/plugins`   | Phone number authentication                           |
+| `api-key`      | `apiKey()`       | `@better-auth/api-key`  | API key issuance/management, rate limiting            |
+| `jwt`          | `jwt()`          | `better-auth/plugins`   | JWT tokens + JWKS key management                      |
+| `passkey`      | `passkey()`      | `@better-auth/passkey`  | WebAuthn/Passkey authentication                       |
+| `sso`          | `sso()`          | `@better-auth/sso`      | OIDC/SAML SSO integration                             |
+| `anonymous`    | `anonymous()`    | `better-auth/plugins`   | Anonymous user support                                |
 
 ---
 
@@ -183,6 +183,11 @@ Schema mapping:
 ### api-key
 
 **Additional entities:** ApiKey (table: `api_keys`)
+**Package:** `@better-auth/api-key` (must be installed separately)
+
+```bash
+pnpm add @better-auth/api-key
+```
 
 ```typescript
 import { apiKey } from "sonamu/auth/plugins";
@@ -192,12 +197,15 @@ apiKey();
 
 Schema mapping:
 
-- `userId` → `user_id`, `lastRequest` → `last_request`, `requestCount` → `request_count`
+- `referenceId` → `reference_id`, `configId` → `config_id`
+- `lastRequest` → `last_request`, `requestCount` → `request_count`
 - `rateLimitEnabled` → `rate_limit_enabled`, `rateLimitTimeWindow` → `rate_limit_time_window`
 - `rateLimitMax` → `rate_limit_max`, `refillInterval` → `refill_interval`
 - `refillAmount` → `refill_amount`, `lastRefillAt` → `last_refill_at`
 - `expiresAt` → `expires_at`, `createdAt` → `created_at`, `updatedAt` → `updated_at`
 
+Note: v1.5.0에서 `userId`가 `referenceId`로 변경됨. `referenceId`는 user 또는 organization을 참조하는 polymorphic ID.
+
 ### jwt
 
 **Additional entities:** Jwks (table: `jwks`)

package/src/skills/sonamu/auth.md

@@ -71,6 +71,23 @@ The 4 entities generated (`betterAuthV1` array):
 - Fields with changed types are updated automatically
 - Uses snake_case column names (better-auth uses camelCase)
 
+## Adding Fixture Companions (`auth add-companions`)
+
+After running `auth generate`, run this command once to add `fixtureCompanions` to the `id` prop of better-auth entities (User, etc.).
+
+```bash
+pnpm sonamu auth add-companions
+```
+
+**Purpose:** Enables automatic Account fixture creation when generating User fixtures. Without this, fixture gen creates User records without a corresponding credentials Account, breaking auth-dependent tests.
+
+**What it does:**
+- Reads `fixtureCompanions` from the `betterAuthV1` definitions
+- Adds them to the existing entity.json `id` prop's cone
+- Skips if `fixtureCompanions` already exists
+
+**When to run:** Once, after `auth generate`, before running `fixture gen` for the first time. Re-running is safe (idempotent).
+
 ## Field Mapping (Applied Automatically)
 
 **Source code:** `modules/sonamu/src/auth/better-auth-entities.ts` (BASE_FIELD_MAPPINGS)

package/src/skills/sonamu/cdd.md

@@ -12,7 +12,6 @@ description: CDD artifact technical reference. contract.md format, rules.json fo
 Documents domain rules and decision rationale in a cohesive form. Located at `contract/**/*.contract.md`.
 
 **Include:**
-
 - Domain rules and constraints ("Refunds are only allowed within 7 days of payment")
 - Decision rationale ("Due to PG provider policy")
 - Cross-module domain workflows ("Order status: pending → confirmed → shipped → completed")
@@ -21,7 +20,6 @@ Documents domain rules and decision rationale in a cohesive form. Located at `co
 - Edge cases and intended handling
 
 **Exclude:**
-
 - Implementation details (file paths, function names, class structure)
 - API endpoints or data schemas
 - UI layouts or component structure
@@ -64,13 +62,13 @@ Records code conventions and UI/API rules.
 }
 ```
 
-| Field                 | Description                            |
-| --------------------- | -------------------------------------- |
-| `description`         | Scope and intent of the rule-set       |
-| `rules[].id`          | Stable identifier                      |
-| `rules[].when`        | Condition under which the rule applies |
-| `rules[].instruction` | Specific directive to follow           |
-| `rules[].examples`    | Optional code/usage examples           |
+| Field | Description |
+|-------|-------------|
+| `description` | Scope and intent of the rule-set |
+| `rules[].id` | Stable identifier |
+| `rules[].when` | Condition under which the rule applies |
+| `rules[].instruction` | Specific directive to follow |
+| `rules[].examples` | Optional code/usage examples |
 
 ### `*.known-issues.json`
 
@@ -96,21 +94,14 @@ Records known bugs, framework constraints, and temporary workarounds. Include in
 ACs are not managed as separate documents. The describe/test names in test files are the ACs themselves.
 
 **AC writing principles:**
-
 - **Small and specific**: one AC = one behavior/outcome
 - **Include input and expected result in the name**: `"Returns 409 when email is duplicate"` > `"Returns an error"`
 
 ```typescript
-describe("sign up", () => {
-  test("returns 409 when email is duplicate", () => {
-    /* TODO */
-  });
-  test("returns 400 when password is shorter than 8 characters", () => {
-    /* TODO */
-  });
-  test("returns the created user_id on success", () => {
-    /* TODO */
-  });
+describe('sign up', () => {
+  test('returns 409 when email is duplicate', () => { /* TODO */ });
+  test('returns 400 when password is shorter than 8 characters', () => { /* TODO */ });
+  test('returns the created user_id on success', () => { /* TODO */ });
 });
 ```
 
@@ -122,13 +113,14 @@ describe("sign up", () => {
 pnpm cdd <command>
 ```
 
-| Command                         | Description                                                                                     |
-| ------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Command | Description |
+|---------|-------------|
 | `cdd ac add <file> <test-name>` | Add an empty test skeleton to a test file. Use `--describe <group>` to specify a describe block |
-| `cdd ac list [file]`            | Print the describe/test tree of a test file. Parses `test()`, `it()`, and `testAs()` patterns   |
-| `cdd rules validate`            | Validate the format of `contract/rules/*.rules.json`                                            |
-| `cdd agents init [--force]`     | Initialize CDD agent setup in the project (creates `.agents/`, `AGENTS.md`, and symlinks)       |
-| `cdd agents sync [--dry-run]`   | Update CDD agent prompts to the latest version                                                  |
+| `cdd ac list [file]` | Print the describe/test tree of a test file. Parses `test()`, `it()`, and `testAs()` patterns |
+| `cdd rules validate` | Validate the format of `contract/rules/*.rules.json` |
+| `cdd agents init [--force]` | Initialize CDD agent setup + contract scaffold (creates `.agents/`, `AGENTS.md`, `contract/planning.md`, `contract/rules/web.rules.json`, `contract/rules/api.rules.json`) |
+| `cdd agents sync [--dry-run]` | Update CDD agent prompts to the latest version |
+| `cdd contract init [--force]` | Scaffold contract directory only (`planning.md`, `rules/web.rules.json`, `rules/api.rules.json`). Alias: `cdd agents contract init` |
 
 ### Common options
 

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

@@ -114,6 +114,14 @@ pnpm create sonamu my_project \
 
    > Will fail if sonamu is an npm version. See "Sonamu Link Setup" below.
 
+   To create a new **project-local** skill file (in `.claude/skills/local/`):
+
+   ```bash
+   pnpm sonamu skills create <name>
+   ```
+
+   This creates `.claude/skills/local/<name>.md` with a frontmatter skeleton. Use it to document project-specific conventions or troubleshooting notes that aren't appropriate for the shared Sonamu skills.
+
 3. Start the dev server
 
    ```bash

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

@@ -622,7 +622,7 @@ When setting a default value on an ENUM field, the value must be wrapped in **es
 { "name": "status", "type": "enum", "id": "ApprovalStatus", "dbDefault": "pending" }
 // Error: cannot use column reference in DEFAULT expression
 
-// Incorrect: single quotes — causes Biome format error
+// Incorrect: single quotes — causes oxfmt format error
 { "name": "status", "type": "enum", "id": "ApprovalStatus", "dbDefault": "'pending'" }
 ```
 

package/src/skills/sonamu/scaffolding.md

@@ -19,6 +19,19 @@ description: Reference for using Sonamu UI Scaffolding. Common errors and soluti
 
 **DO NOT:** scaffold only model and model_test and skip the view-related items
 
+## CLI Scaffold Commands
+
+All scaffold types can be generated via CLI (in addition to Sonamu UI):
+
+```bash
+pnpm sonamu scaffold model <entityId>
+pnpm sonamu scaffold model_test <entityId>
+pnpm sonamu scaffold view_list <entityId>
+pnpm sonamu scaffold view_form <entityId>
+```
+
+`model_test` generates the test file skeleton (`{entity}.model.test.ts`) with the correct imports and `bootstrap(vi)` setup. Run it from `packages/api` after the entity's types.ts and migration are ready.
+
 ---
 
 ## Pre-Scaffolding Checklist

package/src/testing/fixture-manager.ts

@@ -342,7 +342,7 @@ export class FixtureManagerClass {
         }
       }
 
-      for await (const fixture of fixtures) {
+      for (const fixture of fixtures) {
         const entity = EntityManager.get(fixture.entityId);
 
         // 사용자 지정 컬럼 기준 중복 확인 → target
@@ -680,7 +680,7 @@ export class FixtureManagerClass {
               ]);
               !isTest() && console.log(chalk.green(`Reset sequence for ${tableName}: ${maxId}`));
             }
-          } catch (_err) {
+          } catch {
             // 시퀀스가 없는 테이블(join table 등)은 무시
             !isTest() && console.log(chalk.gray(`Skipped sequence reset for ${tableName}`));
           }