sonamu 0.10.3 → 0.10.5

package/dist/ui-web/index.html

@@ -5,7 +5,7 @@
     <link rel="icon" type="image/svg+xml" href="/sonamu-ui/setting.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>{{projectName}}: Sonamu UI</title>
-    <script type="module" crossorigin src="/sonamu-ui/assets/index-CDd6xT-F.js"></script>
+    <script type="module" crossorigin src="/sonamu-ui/assets/index-BLX4zN8c.js"></script>
     <link rel="stylesheet" crossorigin href="/sonamu-ui/assets/index-Dx4ap5i4.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sonamu",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "Sonamu — TypeScript Fullstack API Framework",
   "keywords": [
     "framework",
@@ -131,8 +131,8 @@
     "vitest": "^4.1.9",
     "@sonamu-kit/hmr-hook": "^0.5.1",
     "@sonamu-kit/hmr-runner": "^0.2.0",
-    "@sonamu-kit/ts-loader": "^2.2.0",
-    "@sonamu-kit/tasks": "^0.3.1"
+    "@sonamu-kit/tasks": "^0.3.1",
+    "@sonamu-kit/ts-loader": "^2.2.0"
   },
   "devDependencies": {
     "@types/bcrypt": "^6",

package/src/bin/cli.ts

@@ -197,8 +197,8 @@ async function bootstrap() {
         stub_entity,
         scaffold_model,
         scaffold_model_test,
-        // scaffold_view_list,
-        // scaffold_view_form,
+        scaffold_view_list,
+        scaffold_view_form,
         cone_gen,
         sync,
         build_all,
@@ -983,6 +983,19 @@ async function scaffold_model_test(entityId: string) {
   });
 }
 
+async function scaffold_view_list(entityId: string) {
+  await Sonamu.syncer.generateTemplate("view_list", {
+    entityId,
+    extra: undefined,
+  });
+}
+
+async function scaffold_view_form(entityId: string) {
+  await Sonamu.syncer.generateTemplate("view_form", {
+    entityId,
+  });
+}
+
 /**
  * pnpm sonamu skills sync 하면 실행되는 함수입니다.
  * 공식 Skills를 로컬 프로젝트 또는 글로벌 ~/.claude/로 동기화합니다.

package/src/database/__tests__/puri.test.ts

@@ -7,6 +7,16 @@ type TestSchema = {
   users: {
     id: number;
     name: string;
+    payload: {
+      actor: {
+        id: string;
+        role: string;
+      };
+      message: string;
+    };
+    tags: string[];
+    state: string;
+    readonly __json__: readonly ["payload", "tags", "state"];
   };
 };
 
@@ -33,3 +43,59 @@ describe("Puri locking methods", () => {
     expect(query).toBe('select * from "users" where "id" = 1 limit 1 for share');
   });
 });
+
+describe("Puri JSONB containment", () => {
+  it("object array scalar and hostile-looking values remain serialized bindings", () => {
+    const hostileValue = `x' OR 1=1 --`;
+    const objectQuery = usersQuery()
+      .whereJsonSupersetOf("users.payload", {
+        actor: { id: hostileValue },
+      })
+      .rawQuery()
+      .toSQL();
+    const arrayQuery = usersQuery().whereJsonSupersetOf("tags", [hostileValue]).rawQuery().toSQL();
+    const scalarQuery = usersQuery().whereJsonSupersetOf("state", hostileValue).rawQuery().toSQL();
+
+    expect(objectQuery.sql).toBe('select * from "users" where "users"."payload" @> ?');
+    expect(objectQuery.bindings).toEqual([
+      JSON.stringify({
+        actor: { id: hostileValue },
+      }),
+    ]);
+    expect(arrayQuery.sql).toBe('select * from "users" where "tags" @> ?');
+    expect(arrayQuery.bindings).toEqual([JSON.stringify([hostileValue])]);
+    expect(scalarQuery.sql).toBe('select * from "users" where "state" @> ?');
+    expect(scalarQuery.bindings).toEqual([JSON.stringify(hostileValue)]);
+
+    expect(objectQuery.sql).not.toContain(hostileValue);
+    expect(arrayQuery.sql).not.toContain(hostileValue);
+    expect(scalarQuery.sql).not.toContain(hostileValue);
+  });
+
+  it("WhereGroup preserves AND OR ordering and undefined is rejected", () => {
+    const groupedQuery = usersQuery()
+      .where("id", 1)
+      .whereGroup((group) => {
+        group
+          .whereJsonSupersetOf("payload", { actor: { role: "admin" } })
+          .orWhereJsonSupersetOf("tags", ["urgent"]);
+      })
+      .rawQuery()
+      .toSQL();
+
+    expect(groupedQuery.sql).toBe(
+      'select * from "users" where "id" = ? and ("payload" @> ? or "tags" @> ?)',
+    );
+    expect(groupedQuery.bindings).toEqual([
+      1,
+      JSON.stringify({ actor: { role: "admin" } }),
+      JSON.stringify(["urgent"]),
+    ]);
+
+    const query = usersQuery();
+    expect(() => Reflect.apply(query.whereJsonSupersetOf, query, ["payload", undefined])).toThrow(
+      "Puri JSONB containment value must be JSON-serializable; JSON.stringify returned undefined.",
+    );
+    expect(query.rawQuery().toSQL().sql).toBe('select * from "users"');
+  });
+});

package/src/database/puri.ts

@@ -20,6 +20,8 @@ import {
   type FuzzyOperator,
   type InsertData,
   type InsertResult,
+  type JsonColumns,
+  type JsonSupersetValue,
   type LeftJoinedMarker,
   type LeftJoinMarkerFor,
   type NumericColumns,
@@ -70,6 +72,18 @@ function normalizeFuzzyOperator(operator?: string): FuzzyOperator {
   return fuzzyOperator;
 }
 
+function serializeJsonSupersetValue(value: unknown): string {
+  const serialized = JSON.stringify(value);
+
+  if (serialized === undefined) {
+    throw new TypeError(
+      "Puri JSONB containment value must be JSON-serializable; JSON.stringify returned undefined.",
+    );
+  }
+
+  return serialized;
+}
+
 function normalizeOrderByDirection(direction: PuriOrderByDirection = "asc"): PuriOrderByDirection {
   if (direction !== "asc" && direction !== "desc") {
     throw new Error(`Invalid order direction: ${direction}`);
@@ -784,6 +798,15 @@ export class Puri<TSchema, TTables extends Record<string, any>, TResult> {
     return this as any;
   }
 
+  // WHERE JSONB SUPERSET (@>)
+  whereJsonSupersetOf<TColumn extends JsonColumns<TTables>>(
+    column: TColumn,
+    value: JsonSupersetValue<ExtractColumnType<TTables, TColumn>>,
+  ): this {
+    this.knexQuery.whereJsonSupersetOf(column, serializeJsonSupersetValue(value));
+    return this;
+  }
+
   // WHERE MATCH
   whereMatch<TColumn extends FulltextColumns<TTables>>(column: TColumn, value: string): this {
     this.knexQuery.whereRaw(`MATCH (${String(column)}) AGAINST (?)`, [value]);
@@ -1449,6 +1472,23 @@ export class WhereGroup<TTables extends Record<string, any>> {
     return this;
   }
 
+  // WHERE JSONB SUPERSET (@>)
+  whereJsonSupersetOf<TColumn extends JsonColumns<TTables>>(
+    column: TColumn,
+    value: JsonSupersetValue<ExtractColumnType<TTables, TColumn>>,
+  ): this {
+    this.builder.whereJsonSupersetOf(column, serializeJsonSupersetValue(value));
+    return this;
+  }
+
+  orWhereJsonSupersetOf<TColumn extends JsonColumns<TTables>>(
+    column: TColumn,
+    value: JsonSupersetValue<ExtractColumnType<TTables, TColumn>>,
+  ): this {
+    this.builder.orWhereJsonSupersetOf(column, serializeJsonSupersetValue(value));
+    return this;
+  }
+
   // WHERE MATCH
   whereMatch<TColumn extends FulltextColumns<TTables>>(column: TColumn, value: string): this;
   whereMatch(...args: any[]): this {

package/src/database/puri.types.test-d.ts

@@ -1,9 +1,11 @@
 import { describe, expectTypeOf, it } from "vitest";
 
-import { type Puri } from "./puri";
+import { Puri } from "./puri";
 import {
   type AvailableColumns,
   type ExtractColumnType,
+  type JsonColumns,
+  type JsonSupersetValue,
   type LeftJoinedMarker,
   type ParseSelectObject,
 } from "./puri.types";
@@ -18,6 +20,28 @@ type MockSchema = {
     name: string;
     email: string;
     department_id: number | null;
+    preferences: {
+      theme: "light" | "dark";
+      notifications: {
+        email: boolean;
+        sms: boolean;
+      };
+      labels: string[];
+      sessions: {
+        id: string;
+        active: boolean;
+      }[];
+    };
+    json_tags: string[];
+    json_scalar: string;
+    nullable_payload: {
+      enabled: boolean;
+    } | null;
+    native_tags: string[];
+    created_at: Date;
+    embedding: number[];
+    readonly __json__: readonly ["preferences", "json_tags", "json_scalar", "nullable_payload"];
+    readonly __vector__: readonly ["embedding"];
   };
   departments: {
     id: number;
@@ -458,6 +482,96 @@ describe("AvailableColumns", () => {
   });
 });
 
+describe("JsonColumns and JsonSupersetValue", () => {
+  it("JSON metadata selects only JSON columns and preserves recursive RHS types", () => {
+    type Tables = { users: MockSchema["users"] };
+    type Columns = JsonColumns<Tables>;
+    type PreferencesValue = JsonSupersetValue<MockSchema["users"]["preferences"]>;
+    type NullablePayloadValue = JsonSupersetValue<MockSchema["users"]["nullable_payload"]>;
+
+    expectTypeOf<Columns>().toEqualTypeOf<
+      | "users.preferences"
+      | "users.json_tags"
+      | "users.json_scalar"
+      | "users.nullable_payload"
+      | "preferences"
+      | "json_tags"
+      | "json_scalar"
+      | "nullable_payload"
+    >();
+
+    const partialObject: PreferencesValue = {
+      notifications: { email: true },
+      sessions: [{ active: false }],
+    };
+    const arrayRoot: JsonSupersetValue<MockSchema["users"]["json_tags"]> = ["urgent"];
+    const scalarRoot: JsonSupersetValue<MockSchema["users"]["json_scalar"]> = "active";
+    const nullableColumnValue: NullablePayloadValue = { enabled: true };
+
+    expectTypeOf(partialObject).toExtend<PreferencesValue>();
+    expectTypeOf(arrayRoot).toEqualTypeOf<string[]>();
+    expectTypeOf(scalarRoot).toEqualTypeOf<string>();
+    expectTypeOf(nullableColumnValue).toExtend<NullablePayloadValue>();
+
+    // @ts-expect-error nested boolean property must not accept a string.
+    const wrongNestedType: PreferencesValue = { notifications: { email: "yes" } };
+    // @ts-expect-error array element types are preserved.
+    const wrongArrayElement: JsonSupersetValue<MockSchema["users"]["json_tags"]> = [1];
+    // @ts-expect-error object array elements retain their recursive partial shape.
+    const wrongObjectArrayElement: PreferencesValue = { sessions: [{ active: "yes" }] };
+    // @ts-expect-error nullable JSON columns do not accept top-level null as a containment value.
+    const nullRoot: NullablePayloadValue = null;
+    // @ts-expect-error undefined cannot be serialized as a JSONB containment value.
+    const undefinedRoot: PreferencesValue = undefined;
+
+    const unknownValue: unknown = { notifications: { email: true } };
+    // @ts-expect-error unknown must be narrowed before it can be used as a containment value.
+    const unknownRoot: PreferencesValue = unknownValue;
+
+    expectTypeOf(wrongNestedType).toExtend<PreferencesValue>();
+    expectTypeOf(wrongArrayElement).toEqualTypeOf<string[]>();
+    expectTypeOf(wrongObjectArrayElement).toExtend<PreferencesValue>();
+    expectTypeOf(nullRoot).toExtend<NullablePayloadValue>();
+    expectTypeOf(undefinedRoot).toExtend<PreferencesValue>();
+    expectTypeOf(unknownRoot).toExtend<PreferencesValue>();
+
+    type Query = Puri<MockSchema, Tables, MockSchema["users"]>;
+    const query = {} as Query;
+
+    expectTypeOf(
+      query.whereJsonSupersetOf("preferences", {
+        notifications: { sms: false },
+      }),
+    ).toEqualTypeOf<Query>();
+    expectTypeOf(
+      query.whereGroup((group) =>
+        group
+          .whereJsonSupersetOf("users.preferences", { theme: "dark" })
+          .orWhereJsonSupersetOf("users.json_tags", ["urgent"]),
+      ),
+    ).toEqualTypeOf<Query>();
+
+    // @ts-expect-error ordinary string columns are not JSON columns.
+    query.whereJsonSupersetOf("name", "Noa");
+    // @ts-expect-error date columns are not JSON columns.
+    query.whereJsonSupersetOf("created_at", new Date());
+    // @ts-expect-error native PostgreSQL array columns are not JSON columns.
+    query.whereJsonSupersetOf("native_tags", ["urgent"]);
+    // @ts-expect-error vector columns are not JSON columns.
+    query.whereJsonSupersetOf("embedding", [0.1, 0.2]);
+    // @ts-expect-error scalar JSON roots retain their scalar type.
+    query.whereJsonSupersetOf("json_scalar", { state: "active" });
+    // @ts-expect-error top-level null is rejected even when the JSON column itself is nullable.
+    query.whereJsonSupersetOf("nullable_payload", null);
+    // @ts-expect-error top-level undefined is not JSON-serializable.
+    query.whereJsonSupersetOf("preferences", undefined);
+    // @ts-expect-error unknown must be narrowed before calling the public method.
+    query.whereJsonSupersetOf("preferences", unknownValue);
+    // @ts-expect-error top-level OR is intentionally exposed only through whereGroup.
+    query.orWhereJsonSupersetOf("preferences", { theme: "light" });
+  });
+});
+
 describe("Puri locking methods", () => {
   it("forUpdate 체이닝 후 first 결과 타입을 유지한다", () => {
     type Query = Puri<MockSchema, { users: MockSchema["users"] }, MockSchema["users"]>;

package/src/database/puri.types.ts

@@ -16,6 +16,7 @@ type LeftJoinedKey = "__leftJoined__";
 type HasDefault = "__hasDefault__";
 type GeneratedKey = "__generated__";
 type VectorKey = "__vector__";
+type JsonKey = "__json__";
 type VirtualQueryKey = "__virtual_query__";
 
 type InternalTypeKeys =
@@ -25,6 +26,7 @@ type InternalTypeKeys =
   | HasDefault
   | GeneratedKey
   | VectorKey
+  | JsonKey
   | VirtualQueryKey;
 
 // ============================================
@@ -42,6 +44,23 @@ export type VectorColumns<TTables extends Record<string, any>> =
     }[keyof TTables]
   | (IsSingleKey<TTables> extends true ? VectorColumnKeys<TTables[keyof TTables]> : never);
 
+// __json__ 메타데이터에서 JSON 컬럼 추출
+type JsonColumnKeys<T> = T extends { [K in JsonKey]: readonly (infer J)[] } ? J & string : never;
+
+export type JsonColumns<TTables extends Record<string, any>> =
+  | {
+      [TAlias in keyof TTables]: `${TAlias & string}.${JsonColumnKeys<TTables[TAlias]>}`;
+    }[keyof TTables]
+  | (IsSingleKey<TTables> extends true ? JsonColumnKeys<TTables[keyof TTables]> : never);
+
+type JsonSupersetNestedValue<T> = T extends readonly (infer Element)[]
+  ? JsonSupersetNestedValue<Element>[]
+  : T extends object
+    ? { [K in keyof T]?: JsonSupersetNestedValue<T[K]> }
+    : T;
+
+export type JsonSupersetValue<T> = JsonSupersetNestedValue<NonNullable<T>>;
+
 // 테이블명 타입
 export type TableName<TSchema> = keyof TSchema & string;
 

package/src/migration/postgresql-schema-reader.ts

@@ -90,8 +90,7 @@ class PostgreSQLSchemaReaderClass {
       if (e instanceof Error && e.message.includes("Table not found")) {
         return null;
       }
-      console.error(e);
-      return null;
+      throw e;
     }
 
     // vector 컬럼의 dimensions 조회

package/src/naite/naite-reporter.ts

@@ -42,6 +42,12 @@ function getSocketPath(): string {
     : join(homedir(), ".sonamu", `naite-${hash}.sock`);
 }
 
+/**
+ * 연결 실패가 지속될 때(extension 미실행 등) buffer가 무한히 커지지 않도록
+ * 최근 메시지만 이 개수만큼 유지합니다.
+ */
+const MAX_BUFFERED_MESSAGES = 1000;
+
 class NaiteReporterClass {
   private socketPath: string | null = null;
   private socket: Socket | null = null;
@@ -97,8 +103,11 @@ class NaiteReporterClass {
     if (this.connected && this.socket) {
       this.socket.write(msg);
     } else {
-      // 연결 대기 중이면 버퍼에 저장
+      // 연결 대기 중이면 버퍼에 저장, 상한 초과 시 오래된 메시지부터 폐기
       this.buffer.push(msg);
+      if (this.buffer.length > MAX_BUFFERED_MESSAGES) {
+        this.buffer.shift();
+      }
     }
   }
 

package/src/skills/sonamu/puri.md

@@ -171,6 +171,34 @@ db.where("status", "active").orWhereGroup((g) => {
 });
 ```
 
+### JSONB Containment (`@>`)
+
+Use `whereJsonSupersetOf()` to require a JSONB column to contain a JSON value. The column and
+containment value are checked against the generated Entity type, and the value is serialized and
+bound internally.
+
+```typescript
+db.table("products").whereJsonSupersetOf("metadata", { warranty: 2 });
+
+// Aliased columns are supported.
+db.table({ p: "products" }).whereJsonSupersetOf("p.metadata", {
+  tags: ["featured"],
+});
+```
+
+Inside a WHERE group, both AND and OR variants are available:
+
+```typescript
+db.whereGroup((g) => {
+  g.where("status", "active").orWhereJsonSupersetOf("metadata", {
+    tags: ["featured"],
+  });
+});
+```
+
+Do not call `JSON.stringify()` yourself. For other JSONB operators such as `->>`, `->`, and `?`,
+continue to use parameterized `whereRaw()`.
+
 ## JOIN
 
 ```typescript

package/src/template/__tests__/generated.template.search-text.test.ts

@@ -62,6 +62,8 @@ async function registerEntityWithFileCustomScalar() {
     table: `generated_template_file_${entitySeq}`,
     props: [
       { name: "id", type: "integer" as const },
+      { name: "title", type: "string" as const },
+      { name: "created_at", type: "date" as const },
       {
         name: "file_props",
         type: "json" as const,
@@ -70,7 +72,7 @@ async function registerEntityWithFileCustomScalar() {
     ],
     indexes: [],
     subsets: {
-      A: ["id", "file_props"],
+      A: ["id", "title", "created_at", "file_props"],
     },
     enums: {},
   };
@@ -82,7 +84,7 @@ async function registerEntityWithFileCustomScalar() {
     image: SonamuFileSchema.nullable(),
   });
 
-  return { typeId };
+  return { entity: registeredEntity, typeId };
 }
 
 describe("Template__generated searchText", () => {
@@ -151,3 +153,16 @@ describe("Template__generated searchText", () => {
     );
   });
 });
+
+describe("Template__generated JSON metadata", () => {
+  test("only type=json properties appear in readonly __json__", async () => {
+    const { entity } = await registerEntityWithFileCustomScalar();
+    const template = new Template__generated();
+
+    const source = template.getBaseSchemaSourceCode(entity).lines.join("\n");
+
+    expect(source).toContain('readonly __json__: readonly ["file_props"],');
+    expect(source).not.toContain('readonly __json__: readonly ["title"');
+    expect(source).not.toContain('readonly __json__: readonly ["created_at"');
+  });
+});

package/src/template/implementations/generated.template.ts

@@ -215,6 +215,14 @@ export class Template__generated extends Template {
       .filter((prop) => prop.type === "vector" || prop.type === "vector[]")
       .map((prop) => prop.name);
 
+    /**
+     * JSON props
+     * - json 타입인 컬럼
+     */
+    const jsonColumns = entity.props
+      .filter((prop) => prop.type === "json")
+      .map((prop) => prop.name);
+
     /**
      * generated props
      * - generated 속성이 있는 컬럼 (INSERT/UPDATE 시 값 제공 불가)
@@ -232,7 +240,8 @@ export class Template__generated extends Template {
       virtualQueryProps.length > 0 ||
       hasDefaultColumns.length > 0 ||
       generatedColumns.length > 0 ||
-      hasVectorColumns.length > 0;
+      hasVectorColumns.length > 0 ||
+      jsonColumns.length > 0;
 
     const lines = [
       `export const ${schemaName} = ${schemaBody};`,
@@ -264,6 +273,11 @@ export class Template__generated extends Template {
                 ? `readonly __vector__: readonly [${hasVectorColumns
                     .map((col) => `"${col}"`)
                     .join(", ")}],`
+                : "") +
+              (jsonColumns.length > 0
+                ? `readonly __json__: readonly [${jsonColumns
+                    .map((col) => `"${col}"`)
+                    .join(", ")}],`
                 : "")
             }}`
           : "") +