sonamu 0.8.26 → 0.9.0

package/src/skills/sonamu/api.md

@@ -15,29 +15,29 @@ async findById(id: number): Promise<User> { }
 
 ## Options
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `httpMethod` | GET, POST, PUT, DELETE, PATCH | GET |
-| `clients` | Client types to generate | `["axios"]` |
-| `resourceName` | queryKey for TanStack Query | - |
-| `guards` | Authentication/authorization guards | - |
-| `path` | Custom path | `/{model}/{method}` |
-| `description` | API description (for documentation) | - |
-| `timeout` | Request timeout (ms) | - |
-| `contentType` | Response Content-Type | `application/json` |
-| `cacheControl` | Cache-Control header setting | - |
-| `compress` | Response compression setting (can disable with `false`) | - |
+| Option         | Description                                             | Default             |
+| -------------- | ------------------------------------------------------- | ------------------- |
+| `httpMethod`   | GET, POST, PUT, DELETE, PATCH                           | GET                 |
+| `clients`      | Client types to generate                                | `["axios"]`         |
+| `resourceName` | queryKey for TanStack Query                             | -                   |
+| `guards`       | Authentication/authorization guards                     | -                   |
+| `path`         | Custom path                                             | `/{model}/{method}` |
+| `description`  | API description (for documentation)                     | -                   |
+| `timeout`      | Request timeout (ms)                                    | -                   |
+| `contentType`  | Response Content-Type                                   | `application/json`  |
+| `cacheControl` | Cache-Control header setting                            | -                   |
+| `compress`     | Response compression setting (can disable with `false`) | -                   |
 
 ## clients Options
 
-| Client | Purpose |
-|--------|---------|
-| `axios` | General API calls |
-| `axios-multipart` | File upload (axios) |
-| `tanstack-query` | Query hook for reads |
-| `tanstack-mutation` | Mutation hook for writes |
-| `tanstack-mutation-multipart` | File upload Mutation |
-| `window-fetch` | Browser fetch API |
+| Client                        | Purpose                  |
+| ----------------------------- | ------------------------ |
+| `axios`                       | General API calls        |
+| `axios-multipart`             | File upload (axios)      |
+| `tanstack-query`              | Query hook for reads     |
+| `tanstack-mutation`           | Mutation hook for writes |
+| `tanstack-mutation-multipart` | File upload Mutation     |
+| `window-fetch`                | Browser fetch API        |
 
 ## Pattern Examples
 
@@ -81,16 +81,16 @@ async me(): Promise<User | null> {
 }
 ```
 
-| Context Property | Description |
-|-----------------|-------------|
-| `user` | Authenticated user (better-auth User, null if unauthenticated) |
-| `session` | Current session info (better-auth Session, null if unauthenticated) |
-| `request` | FastifyRequest |
-| `reply` | FastifyReply |
-| `headers` | HTTP request headers |
-| `bufferedFiles` | Buffer mode uploaded files |
-| `uploadedFiles` | Stream mode uploaded files |
-| `locale` | Request locale |
+| Context Property | Description                                                         |
+| ---------------- | ------------------------------------------------------------------- |
+| `user`           | Authenticated user (better-auth User, null if unauthenticated)      |
+| `session`        | Current session info (better-auth Session, null if unauthenticated) |
+| `request`        | FastifyRequest                                                      |
+| `reply`          | FastifyReply                                                        |
+| `headers`        | HTTP request headers                                                |
+| `bufferedFiles`  | Buffer mode uploaded files                                          |
+| `uploadedFiles`  | Stream mode uploaded files                                          |
+| `locale`         | Request locale                                                      |
 
 ## File Upload (@upload)
 
@@ -111,13 +111,13 @@ async upload(...): Promise<number[]> { }
 
 **`@upload` supported options** (`httpMethod`, `clients` are not supported — set automatically)
 
-| Option | Description |
-|--------|-------------|
-| `guards` | Authentication/authorization guards |
-| `limits` | File count/size limits (`{ files: N }`) |
-| `consume` | `"buffer"` (default) or `"stream"` |
-| `description` | API documentation description |
-| `destination` | Stream mode only: storage driver key |
+| Option         | Description                                         |
+| -------------- | --------------------------------------------------- |
+| `guards`       | Authentication/authorization guards                 |
+| `limits`       | File count/size limits (`{ files: N }`)             |
+| `consume`      | `"buffer"` (default) or `"stream"`                  |
+| `description`  | API documentation description                       |
+| `destination`  | Stream mode only: storage driver key                |
 | `keyGenerator` | Stream mode only: function to generate storage path |
 
 ### Parameter Rule: Must Wrap in a Single Object
@@ -135,11 +135,12 @@ async upload(params: { entity_type: string; entity_id: number; file_type: string
 ```
 
 Call site pattern:
+
 ```typescript
 uploadMutation.mutate({
   params: { entity_type, entity_id, file_type },
   files,
-})
+});
 ```
 
 > For detailed root cause analysis, see the `@upload multiple parameters` section in `framework-change.md`.
@@ -187,7 +188,7 @@ async changeStatus(
   memo?: string
 ): Promise<Consultation> {
   const wdb = this.getPuri("w");
-  
+
   return wdb.transaction(async (trx) => {
     // 1. Update consultation
     await trx.ubRegister("consultations", {
@@ -196,7 +197,7 @@ async changeStatus(
       updated_at: new Date()
     });
     await trx.ubUpsert("consultations");
-    
+
     // 2. Record status change history
     await trx.ubRegister("consultation_histories", {
       consultation_id: id,
@@ -205,7 +206,7 @@ async changeStatus(
       created_at: new Date(),
     });
     await trx.ubUpsert("consultation_histories");
-    
+
     // 3. Return result
     return this.findById("A", id);
   });
@@ -213,6 +214,7 @@ async changeStatus(
 ```
 
 **Key points:**
+
 - Atomicity guaranteed by transaction
 - ubRegister + ubUpsert pattern
 - Return latest data after change
@@ -232,19 +234,19 @@ async enroll(
     course_id: courseId,
     user_id: userId,
   });
-  
+
   if (existing) {
     throw new Error("Already enrolled in this course");
   }
-  
+
   // 2. Check capacity
   const course = await CourseModel.findById("A", courseId);
   const { total } = await this.findMany({ course_id: courseId });
-  
+
   if (total >= course.max_students) {
     throw new Error("Course is at capacity");
   }
-  
+
   // 3. Enroll
   const [id] = await this.save([{ course_id: courseId, user_id: userId }]);
   return this.findById("A", id);
@@ -252,6 +254,7 @@ async enroll(
 ```
 
 **Key points:**
+
 - Step-by-step validation (duplicate → capacity)
 - Clear error messages
 - Save after validation passes
@@ -286,34 +289,34 @@ Validating custom APIs in Business Logic tests:
 describe("E. Business Logic", () => {
   test("Status change API", async () => {
     const { consultationId } = await createTestConsultationWithDeps();
-    
+
     // Call custom API
     const updated = await ConsultationModel.changeStatus(
       consultationId,
       "completed",
-      "Consultation complete"
+      "Consultation complete",
     );
-    
+
     expect(updated.status).toBe("completed");
-    
+
     // Verify history was recorded
     const histories = await ConsultationHistoryModel.findMany({
       consultation_id: consultationId,
     });
     expect(histories.rows).toHaveLength(1);
   });
-  
+
   test("Enrollment validation", async () => {
     const courseId = 1;
     const userId = 1;
-    
+
     // First enrollment succeeds
     await EnrollmentModel.enroll(courseId, userId);
-    
+
     // Duplicate enrollment fails
-    await expect(
-      EnrollmentModel.enroll(courseId, userId)
-    ).rejects.toThrow("Already enrolled in this course");
+    await expect(EnrollmentModel.enroll(courseId, userId)).rejects.toThrow(
+      "Already enrolled in this course",
+    );
   });
 });
 ```
@@ -327,6 +330,7 @@ describe("E. Business Logic", () => {
 Use `this.modelName` and the `SD()` function for consistent error messages.
 
 **BAD: Hardcoded model name**
+
 ```typescript
 // findById
 if (!rows[0]) {
@@ -338,6 +342,7 @@ throw new BadRequestException(SD("error.unknownSearchField")(params.search));
 ```
 
 **GOOD: Using this.modelName**
+
 ```typescript
 // findById - auto-detects model name
 if (!rows[0]) {
@@ -349,6 +354,7 @@ throw new BadRequestException(SD("search.invalidField")(params.search));
 ```
 
 **Benefits:**
+
 - DRY principle: model name managed in one place
 - Refactoring safe: error messages auto-reflect model name changes
 - Short i18n keys: `notFound`, `search.invalidField` are more concise
@@ -358,6 +364,7 @@ throw new BadRequestException(SD("search.invalidField")(params.search));
 Use TypeScript's satisfies keyword to preserve type inference while checking types.
 
 **BAD: Loss of type inference**
+
 ```typescript
 const params: RoleListParams = {
   num: 24,
@@ -369,6 +376,7 @@ const params: RoleListParams = {
 ```
 
 **GOOD: Type check + preserved inference with satisfies**
+
 ```typescript
 const params = {
   num: 24,
@@ -380,6 +388,7 @@ const params = {
 ```
 
 **Benefits:**
+
 - Compile-time verification: checks that params satisfies the RoleListParams type
 - Preserved type inference: params keeps its narrowed type
 - Better IDE support: more accurate autocomplete and type checking
@@ -389,17 +398,19 @@ const params = {
 The debug option in executeSubsetQuery defaults to false, so it does not need to be specified explicitly.
 
 **BAD: Unnecessary debug: false**
+
 ```typescript
 return this.executeSubsetQuery({
   subset,
   qb,
   params,
   enhancers,
-  debug: false,  // unnecessary — it's the default
+  debug: false, // unnecessary — it's the default
 });
 ```
 
 **GOOD: Use the default**
+
 ```typescript
 return this.executeSubsetQuery({
   subset,
@@ -410,13 +421,14 @@ return this.executeSubsetQuery({
 ```
 
 **When to use debug: true:**
+
 ```typescript
 // Only specify when debugging
 return this.executeSubsetQuery({
   subset,
   qb,
   params,
-  debug: true,  // Print SQL query log
+  debug: true, // Print SQL query log
 });
 ```
 
@@ -439,13 +451,13 @@ import { z } from "zod";
 async processStream() { ... }
 ```
 
-| Option | Description | Required |
-|--------|-------------|----------|
-| `type` | `"sse"` (only SSE currently supported) | Yes |
-| `events` | Define event keys and payloads with Zod schema | Yes |
-| `path` | Custom path | - |
-| `resourceName` | Resource name | - |
-| `guards` | Authentication/authorization guards | - |
+| Option         | Description                                    | Required |
+| -------------- | ---------------------------------------------- | -------- |
+| `type`         | `"sse"` (only SSE currently supported)         | Yes      |
+| `events`       | Define event keys and payloads with Zod schema | Yes      |
+| `path`         | Custom path                                    | -        |
+| `resourceName` | Resource name                                  | -        |
+| `guards`       | Authentication/authorization guards            | -        |
 
 ## @transactional Decorator
 
@@ -460,8 +472,8 @@ async transferFunds(fromId: number, toId: number, amount: number) {
 }
 ```
 
-| Option | Description | Default |
-|--------|-------------|---------|
-| `isolation` | Transaction isolation level (read uncommitted/read committed/repeatable read/serializable) | - |
-| `readOnly` | Read-only transaction | `false` |
-| `dbPreset` | DB preset | `"w"` |
+| Option      | Description                                                                                | Default |
+| ----------- | ------------------------------------------------------------------------------------------ | ------- |
+| `isolation` | Transaction isolation level (read uncommitted/read committed/repeatable read/serializable) | -       |
+| `readOnly`  | Read-only transaction                                                                      | `false` |
+| `dbPreset`  | DB preset                                                                                  | `"w"`   |

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

@@ -60,35 +60,23 @@ Correct order:
 ```typescript
 export async function up(knex: Knex): Promise<void> {
   // Step 1: Remove all FK constraints
-  await knex.raw(
-    'ALTER TABLE "accounts" DROP CONSTRAINT "accounts_user_id_foreign"',
-  );
-  await knex.raw(
-    'ALTER TABLE "sessions" DROP CONSTRAINT "sessions_user_id_foreign"',
-  );
+  await knex.raw('ALTER TABLE "accounts" DROP CONSTRAINT "accounts_user_id_foreign"');
+  await knex.raw('ALTER TABLE "sessions" DROP CONSTRAINT "sessions_user_id_foreign"');
   await knex.raw(
     'ALTER TABLE "evaluation_committees" DROP CONSTRAINT "evaluation_committees_evaluator_id_foreign"',
   );
   await knex.raw(
     'ALTER TABLE "project_participants" DROP CONSTRAINT "project_participants_user_id_foreign"',
   );
-  await knex.raw(
-    'ALTER TABLE "reports" DROP CONSTRAINT "reports_submitted_by_id_foreign"',
-  );
+  await knex.raw('ALTER TABLE "reports" DROP CONSTRAINT "reports_submitted_by_id_foreign"');
 
   // Step 2: Remove PK constraint
   await knex.raw('ALTER TABLE "users" DROP CONSTRAINT "users_pkey"');
 
   // Step 3: Change all column types (parent PK + child FKs)
-  await knex.raw(
-    'ALTER TABLE "users" ALTER COLUMN "id" TYPE text USING "id"::text',
-  );
-  await knex.raw(
-    'ALTER TABLE "accounts" ALTER COLUMN "user_id" TYPE text USING "user_id"::text',
-  );
-  await knex.raw(
-    'ALTER TABLE "sessions" ALTER COLUMN "user_id" TYPE text USING "user_id"::text',
-  );
+  await knex.raw('ALTER TABLE "users" ALTER COLUMN "id" TYPE text USING "id"::text');
+  await knex.raw('ALTER TABLE "accounts" ALTER COLUMN "user_id" TYPE text USING "user_id"::text');
+  await knex.raw('ALTER TABLE "sessions" ALTER COLUMN "user_id" TYPE text USING "user_id"::text');
   await knex.raw(
     'ALTER TABLE "evaluation_committees" ALTER COLUMN "evaluator_id" TYPE text USING "evaluator_id"::text',
   );
@@ -100,9 +88,7 @@ export async function up(knex: Knex): Promise<void> {
   );
 
   // Step 4: Restore PK constraint
-  await knex.raw(
-    'ALTER TABLE "users" ADD CONSTRAINT "users_pkey" PRIMARY KEY ("id")',
-  );
+  await knex.raw('ALTER TABLE "users" ADD CONSTRAINT "users_pkey" PRIMARY KEY ("id")');
 
   // Step 5: Restore FK constraints
   await knex.raw(
@@ -382,12 +368,12 @@ In Sonamu Entity, use the DB column name (snake_case) as-is:
 
 #### Plugin Categories
 
-| Category | Plugins | Impact |
-| ------------ | ----------------------------------------------------------- | ---------------------------------------- |
-| Basic auth | email/password, OAuth, magic link, email OTP, multi-session | User/Session/Account/Verification tables |
-| User extension | username, phone number, admin, anonymous | Adds fields to User table |
-| Security | two-factor, passkey | New tables needed (TwoFactor, Passkey) |
-| Enterprise | organization, API key, SSO, JWT | New tables needed (Organization, Member, etc.) |
+| Category       | Plugins                                                     | Impact                                         |
+| -------------- | ----------------------------------------------------------- | ---------------------------------------------- |
+| Basic auth     | email/password, OAuth, magic link, email OTP, multi-session | User/Session/Account/Verification tables       |
+| User extension | username, phone number, admin, anonymous                    | Adds fields to User table                      |
+| Security       | two-factor, passkey                                         | New tables needed (TwoFactor, Passkey)         |
+| Enterprise     | organization, API key, SSO, JWT                             | New tables needed (Organization, Member, etc.) |
 
 #### Classification by Schema Requirements
 

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

@@ -9,6 +9,7 @@ Sonamu wraps better-auth plugins with snake_case schema mapping.
 Use the `auth generate --plugins` command to auto-generate plugin entities.
 
 **Source code:**
+
 - Wrappers: `modules/sonamu/src/auth/plugins/wrappers/`
 - Entity definitions: `modules/sonamu/src/auth/plugins/entity-definitions/`
 - Generator: `modules/sonamu/src/auth/auth-generator.ts`
@@ -17,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/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                                |
 
 ---
 
@@ -68,12 +69,7 @@ export default defineConfig({
   server: {
     auth: {
       emailAndPassword: { enabled: true },
-      plugins: [
-        admin(),
-        organization(),
-        twoFactor(),
-        username(),
-      ],
+      plugins: [admin(), organization(), twoFactor(), username()],
     },
   },
 });
@@ -103,13 +99,14 @@ import { admin } from "sonamu/auth/plugins";
 import { admin } from "sonamu/auth/plugins";
 
 // Basic usage
-admin()
+admin();
 
 // Customize options (schema mapping is automatically merged)
-admin({ defaultRole: "user" })
+admin({ defaultRole: "user" });
 ```
 
 Schema mapping:
+
 - `banReason` → `ban_reason`
 - `banExpires` → `ban_expires`
 - `impersonatedBy` → `impersonated_by`
@@ -122,10 +119,11 @@ Schema mapping:
 ```typescript
 import { organization } from "sonamu/auth/plugins";
 
-organization()
+organization();
 ```
 
 Schema mapping:
+
 - All tables: `createdAt` → `created_at`
 - Member: `userId` → `user_id`, `organizationId` → `organization_id`
 - Invitation: `inviterId` → `inviter_id`, `organizationId` → `organization_id`, `teamId` → `team_id`, `expiresAt` → `expires_at`
@@ -141,10 +139,11 @@ Schema mapping:
 ```typescript
 import { twoFactor } from "sonamu/auth/plugins";
 
-twoFactor()
+twoFactor();
 ```
 
 Schema mapping:
+
 - User: `twoFactorEnabled` → `two_factor_enabled`
 - TwoFactor: `userId` → `user_id`, `backupCodes` → `backup_codes`
 
@@ -155,10 +154,11 @@ Schema mapping:
 ```typescript
 import { username } from "sonamu/auth/plugins";
 
-username()
+username();
 ```
 
 Schema mapping:
+
 - `displayUsername` → `display_username`
 
 ### phone-number
@@ -168,10 +168,15 @@ Schema mapping:
 ```typescript
 import { phoneNumber } from "sonamu/auth/plugins";
 
-phoneNumber({ sendOTP: async ({ phoneNumber, otp }) => { /* send SMS */ } })
+phoneNumber({
+  sendOTP: async ({ phoneNumber, otp }) => {
+    /* send SMS */
+  },
+});
 ```
 
 Schema mapping:
+
 - `phoneNumber` → `phone_number`
 - `phoneNumberVerified` → `phone_number_verified`
 
@@ -182,10 +187,11 @@ Schema mapping:
 ```typescript
 import { apiKey } from "sonamu/auth/plugins";
 
-apiKey()
+apiKey();
 ```
 
 Schema mapping:
+
 - `userId` → `user_id`, `lastRequest` → `last_request`, `requestCount` → `request_count`
 - `rateLimitEnabled` → `rate_limit_enabled`, `rateLimitTimeWindow` → `rate_limit_time_window`
 - `rateLimitMax` → `rate_limit_max`, `refillInterval` → `refill_interval`
@@ -199,10 +205,11 @@ Schema mapping:
 ```typescript
 import { jwt } from "sonamu/auth/plugins";
 
-jwt()
+jwt();
 ```
 
 Schema mapping:
+
 - `publicKey` → `public_key`, `privateKey` → `private_key`
 - `createdAt` → `created_at`, `expiresAt` → `expires_at`
 
@@ -218,10 +225,11 @@ pnpm add @better-auth/passkey
 ```typescript
 import { passkey } from "sonamu/auth/plugins";
 
-passkey({ rpID: "localhost", rpName: "My App" })
+passkey({ rpID: "localhost", rpName: "My App" });
 ```
 
 Schema mapping:
+
 - `publicKey` → `public_key`, `userId` → `user_id`, `credentialID` → `credential_id`
 - `deviceType` → `device_type`, `backedUp` → `backed_up`, `createdAt` → `created_at`
 
@@ -236,11 +244,12 @@ pnpm add @better-auth/sso
 ```typescript
 import { sso } from "sonamu/auth/plugins";
 
-sso()
+sso();
 ```
 
 Table: `sso_providers`
 Schema mapping:
+
 - `oidcConfig` → `oidc_config`, `samlConfig` → `saml_config`
 - `userId` → `user_id`, `providerId` → `provider_id`, `organizationId` → `organization_id`
 
@@ -251,10 +260,11 @@ Schema mapping:
 ```typescript
 import { anonymous } from "sonamu/auth/plugins";
 
-anonymous()
+anonymous();
 ```
 
 Schema mapping:
+
 - `isAnonymous` → `is_anonymous`
 
 ---
@@ -269,11 +279,11 @@ admin({
   schema: {
     user: {
       fields: {
-        customField: "custom_field",  // additional mapping
+        customField: "custom_field", // additional mapping
       },
     },
   },
-})
+});
 ```
 
 Internally, `merge(ADMIN_SCHEMA, options.schema)` is executed to preserve the Sonamu mapping.