@gencow/core 0.1.28 → 0.1.29

package/src/reactive.ts

@@ -1,593 +0,0 @@
-import type { WSContext } from "hono/ws";
-import type { Storage } from "./storage.js";
-import type { Scheduler } from "./scheduler.js";
-import { type Validator, type InferArgs } from "./v.js";
-import type { HybridSearchOptions, SearchOptions, SearchResponse, VectorSearchOptions } from "./search-types.js";
-import type { GencowServicesCtx } from "./document-types.js";
-import type { GroundingRuntime } from "./grounded-answer-types.js";
-
-// ─── GencowCtx — 사용자 함수에 주입되는 컨텍스트 ──────────
-
-export interface UserIdentity {
-  id: string;
-  email: string;
-  name?: string;
-}
-
-export interface AuthCtx {
-  /** 현재 유저 반환 (비로그인 시 null) — Convex의 ctx.auth.getUserIdentity() */
-  getUserIdentity(): UserIdentity | null;
-  /** 현재 유저 반환 (비로그인 시 401 throw) */
-  requireAuth(): UserIdentity;
-}
-
-/**
- * mutation handler 내에서 구독자들에게 데이터를 즉시 push합니다.
- * 클라이언트는 이 데이터를 받아 re-fetch 없이 state를 업데이트합니다.
- */
-export interface RealtimeCtx {
-  /**
-   * 특정 queryKey를 구독 중인 클라이언트에 데이터를 즉시 push합니다.
-   * 초고빈도 mutation (채팅 등)에서 query re-run 비용을 회피할 때 사용.
-   *
-   * @param queryKey - 업데이트할 쿼리 키 (예: "tasks.list")
-   * @param data     - push할 데이터 (해당 query 결과와 동일한 타입)
-   *
-   * @example
-   *   const freshList = await ctx.db.select().from(tasks);
-   *   ctx.realtime.emit("tasks.list", freshList);
-   */
-  emit(queryKey: string, data: unknown): void;
-
-  /**
-   * 수동 mutation에서 리얼타임 업데이트의 기본 권장 방식.
-   * mutation handler 완료 후 서버가 해당 query를 re-run하여 결과를 push합니다.
-   * 복잡한 JOIN query도 queryKey만 지정하면 됩니다.
-   *
-   * @param queryKey - re-run할 쿼리 키 (예: "dashboard.revenue")
-   *
-   * @example
-   *   mutation("orders.place", {
-   *       handler: async (ctx, args) => {
-   *           await ctx.db.insert(orders).values(args);
-   *           ctx.realtime.refresh("orders.list");
-   *           ctx.realtime.refresh("dashboard.revenue");  // JOIN query도 OK
-   *       }
-   *   });
-   */
-  refresh(queryKey: string): void;
-}
-
-/**
- * 사용자 함수(query/mutation)에 주입되는 컨텍스트.
- * Convex의 ctx 패턴과 동일하게, 이 객체를 통해서만 DB/Storage/Auth에 접근 가능.
- * fs, child_process 등 원시 Node.js API는 노출되지 않음.
- */
-// ─── AI Context ─────────────────────────────────────────
-
-export interface AIMessage {
-  role: "user" | "system" | "assistant";
-  content: string;
-}
-
-export interface AIResult {
-  text: string;
-  usage: { promptTokens: number; completionTokens: number; totalTokens: number };
-  creditsCharged: number;
-  model: string;
-}
-
-export interface AIContext {
-  /** AI 텍스트 생성 */
-  chat: (opts: {
-    model?: string;
-    messages: AIMessage[];
-    /** System prompt — shorthand for adding a system message */
-    system?: string;
-    temperature?: number;
-    maxTokens?: number;
-    /** Response format — e.g. { type: "json_object" } for JSON mode */
-    responseFormat?: { type: string };
-  }) => Promise<AIResult>;
-  /** 텍스트 임베딩 (단일) */
-  embed: (text: string) => Promise<number[]>;
-  /** 배치 임베딩 */
-  embedMany: (texts: string[]) => Promise<number[][]>;
-}
-
-export interface GencowCtx {
-  /** Drizzle DB 인스턴스 (scoped) — 스키마 filter 자동 적용, execute 차단 */
-  db: any; // typed per-app via generic
-  /** Raw Drizzle DB — 필터 없음, execute 허용. ⚠️ 이름이 곧 경고. */
-  unsafeDb: any;
-  /** 인증 컨텍스트 — ctx.auth.getUserIdentity() */
-  auth: AuthCtx;
-  /** 파일 스토리지 — ctx.storage.store(), ctx.storage.getUrl() */
-  storage: Storage;
-  /** 스케줄러 — ctx.scheduler.runAfter(), ctx.scheduler.cron() */
-  scheduler: Scheduler;
-  /** 실시간 push — ctx.realtime.emit(queryKey, data) */
-  realtime: RealtimeCtx;
-  /** 재시도 — ctx.retry(fn, opts) — exponential backoff + jitter */
-  retry: <T>(fn: () => Promise<T>, options?: import("./retry.js").RetryOptions) => Promise<T>;
-  /** 프레임워크 서비스 헬퍼 — workflow 전용 service는 별도 ctx에서 노출 */
-  services: GencowServicesCtx;
-  /** AI 헬퍼 */
-  ai?: AIContext;
-  /** Full-text / hybrid search helper */
-  search: (table: string, query: string, options: SearchOptions) => Promise<SearchResponse>;
-  /** Vector / semantic search helper */
-  vectorSearch: (table: string, options: VectorSearchOptions) => Promise<SearchResponse>;
-  /** Hybrid search helper (lexical + vector) */
-  hybridSearch: (table: string, query: string, options: HybridSearchOptions) => Promise<SearchResponse>;
-  /** Grounded answer helper over canonical rag_* tables */
-  grounding?: GroundingRuntime;
-}
-
-// ─── Types ──────────────────────────────────────────────
-
-type QueryHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
-type MutationHandler<TArgs = any, TReturn = any> = (ctx: GencowCtx, args: TArgs) => Promise<TReturn>;
-
-/**
- * httpAction 핸들러의 Request/Response 타입.
- * Hono의 Context를 직접 받아 full HTTP 제어 가능.
- */
-export type HttpActionHandler = (ctx: GencowCtx, req: HttpActionRequest) => Promise<HttpActionResponse>;
-
-export interface HttpActionRequest {
-  /** HTTP method (GET, POST, PUT, DELETE, PATCH) */
-  method: string;
-  /** Full URL */
-  url: string;
-  /** URL path (e.g. /api/cli/auth-start) */
-  path: string;
-  /** Route params (e.g. { id: "abc" } for /api/apps/:id) */
-  params: Record<string, string>;
-  /** Query string params */
-  query: Record<string, string>;
-  /** Request headers */
-  headers: Record<string, string>;
-  /** Parse JSON body */
-  json: <T = unknown>() => Promise<T>;
-  /** Parse form data */
-  formData: () => Promise<FormData>;
-  /** Raw body as ArrayBuffer */
-  arrayBuffer: () => Promise<ArrayBuffer>;
-  /** Raw body as text */
-  text: () => Promise<string>;
-}
-
-export interface HttpActionResponse {
-  status?: number;
-  headers?: Record<string, string>;
-  body?: unknown;
-}
-
-export interface QueryDef<TSchema = any, TReturn = any> {
-  key: string;
-  handler: QueryHandler<InferArgs<TSchema>, TReturn>;
-  argsSchema?: TSchema;
-  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
-  isPublic: boolean;
-  _args?: InferArgs<TSchema>;
-  _return?: TReturn;
-}
-
-export interface MutationDef<TSchema = any, TReturn = any> {
-  handler: MutationHandler<InferArgs<TSchema>, TReturn>;
-  argsSchema?: TSchema;
-  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 (Secure by Default) */
-  isPublic: boolean;
-  _args?: InferArgs<TSchema>;
-  _return?: TReturn;
-}
-
-/** httpAction 정의. 커스텀 HTTP 엔드포인트를 선언적으로 등록. */
-export interface HttpActionDef {
-  /** HTTP method */
-  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-  /** URL path (Hono 패턴 — /api/cli/:code 형태 지원) */
-  path: string;
-  /** true = 인증 없이 접근 가능, false(기본) = auth 필수 */
-  isPublic: boolean;
-  /** 핸들러 */
-  handler: HttpActionHandler;
-}
-
-// ─── Registry ───────────────────────────────────────────
-//
-// globalThis 기반 — 서버 번들(인라인)과 node_modules/@gencow/core 양쪽에서
-// 동일한 레지스트리 인스턴스를 공유. Dual-Module Registry 버그 방지.
-// See: docs/analysis/analysis-dual-module-registry.md
-
-declare global {
-  var __gencow_queryRegistry: Map<string, QueryDef<any, any>>;
-  var __gencow_mutationRegistry: (MutationDef<any, any> & { name: string })[];
-  var __gencow_subscribers: Map<string, Set<WSContext>>;
-  var __gencow_connectedClients: Set<WSContext>;
-  var __gencow_httpActionRegistry: HttpActionDef[];
-}
-
-if (!globalThis.__gencow_queryRegistry) globalThis.__gencow_queryRegistry = new Map();
-if (!globalThis.__gencow_mutationRegistry) globalThis.__gencow_mutationRegistry = [];
-if (!globalThis.__gencow_subscribers) globalThis.__gencow_subscribers = new Map();
-if (!globalThis.__gencow_connectedClients) globalThis.__gencow_connectedClients = new Set();
-if (!globalThis.__gencow_httpActionRegistry) globalThis.__gencow_httpActionRegistry = [];
-
-const queryRegistry = globalThis.__gencow_queryRegistry;
-const mutationRegistry = globalThis.__gencow_mutationRegistry;
-const httpActionRegistry = globalThis.__gencow_httpActionRegistry;
-const subscribers = globalThis.__gencow_subscribers;
-
-/**
- * Every WebSocket client that ever establishes a connection is tracked here.
- * This allows broadcasting invalidation events to clients that never subscribed
- * to a specific query (e.g. the admin dashboard's raw WebSocket connection).
- */
-const connectedClients = globalThis.__gencow_connectedClients;
-
-// ─── Public API (Convex-style) ──────────────────────────
-
-export function query<TSchema = any, TReturn = any>(
-  key: string,
-  handlerOrDef:
-    | QueryHandler<InferArgs<TSchema>, TReturn>
-    | { args?: TSchema; public?: boolean; handler: QueryHandler<InferArgs<TSchema>, TReturn> },
-): QueryDef<TSchema, TReturn> {
-  let handler: QueryHandler<InferArgs<TSchema>, TReturn>;
-  let argsSchema: TSchema | undefined;
-  let isPublic = false;
-
-  if (typeof handlerOrDef === "function") {
-    handler = handlerOrDef;
-  } else {
-    handler = handlerOrDef.handler;
-    argsSchema = handlerOrDef.args;
-    isPublic = handlerOrDef.public === true;
-  }
-
-  const def: QueryDef<TSchema, TReturn> = { key, handler, argsSchema, isPublic };
-  queryRegistry.set(key, def);
-  return def;
-}
-
-let mutationCounter = 0;
-
-/**
- * mutation — 데이터 변경 함수를 선언적으로 등록합니다.
- *
- * 3가지 호출 방식 지원 (query와 동일한 패턴 우선):
- *
- * @example
- * ```typescript
- * // ✅ 권장: query와 동일한 (name, def) 패턴
- * mutation("tasks.create", {
- *     args: { title: v.string() },
- *     handler: async (ctx, args) => { ... },
- * });
- *
- * // ✅ 객체 스타일 (하위 호환)
- * mutation({
- *     name: "tasks.create",
- *     handler: async (ctx) => { ... },
- * });
- *
- * // ⚠️ Legacy 배열 스타일 (비권장)
- * mutation(["tasks.list"], handler, "tasks.create");
- * ```
- *
- * @note invalidates 필드는 deprecated — 전달해도 무시됩니다.
- *       리얼타임 UI 갱신에는 ctx.realtime.emit() 또는 ctx.realtime.refresh()를 사용하세요.
- */
-export function mutation<TSchema = any, TReturn = any>(
-  nameOrInvalidatesOrDef:
-    | string
-    | string[]
-    | {
-        name?: string;
-        args?: TSchema;
-        public?: boolean;
-        invalidates?: string[];
-        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
-      },
-  handlerOrDef?:
-    | MutationHandler<InferArgs<TSchema>, TReturn>
-    | {
-        invalidates?: string[];
-        args?: TSchema;
-        public?: boolean;
-        handler: MutationHandler<InferArgs<TSchema>, TReturn>;
-      },
-  name?: string,
-): MutationDef<TSchema, TReturn> {
-  let argsSchema: TSchema | undefined;
-  let actualHandler: MutationHandler<InferArgs<TSchema>, TReturn>;
-  let mutName: string;
-  let isPublic = false;
-
-  if (typeof nameOrInvalidatesOrDef === "string") {
-    // New primary style: mutation("name", { args?, public?, handler })
-    mutName = nameOrInvalidatesOrDef;
-    const def = handlerOrDef as {
-      args?: TSchema;
-      public?: boolean;
-      handler: MutationHandler<InferArgs<TSchema>, TReturn>;
-    };
-    actualHandler = def.handler;
-    argsSchema = def.args;
-    isPublic = def.public === true;
-  } else if (Array.isArray(nameOrInvalidatesOrDef)) {
-    // Legacy style: mutation([...], handler, "name") — invalidates ignored
-    actualHandler = handlerOrDef as MutationHandler<InferArgs<TSchema>, TReturn>;
-    mutName = name || `mutation_${++mutationCounter}`;
-  } else {
-    // Object style: mutation({ name?, args?, public?, handler })
-    actualHandler = nameOrInvalidatesOrDef.handler;
-    argsSchema = nameOrInvalidatesOrDef.args;
-    isPublic = nameOrInvalidatesOrDef.public === true;
-    mutName =
-      nameOrInvalidatesOrDef.name ||
-      (typeof name === "string" ? name : "") ||
-      `mutation_${++mutationCounter}`;
-  }
-
-  // 이름 미지정 시 경고 — 디버깅 지원
-  if (mutName.startsWith("mutation_")) {
-    console.warn(
-      `[gencow] mutation registered without explicit name → "${mutName}". ` +
-        `Use mutation("myMutation", { handler }) for better debugging.`,
-    );
-  }
-
-  const def: MutationDef<TSchema, TReturn> & { name: string } = {
-    name: mutName,
-    handler: actualHandler,
-    argsSchema,
-    isPublic,
-  };
-  mutationRegistry.push(def);
-  return def;
-}
-
-// ─── httpAction (커스텀 HTTP 엔드포인트) ────────────────
-
-/**
- * 커스텀 HTTP 엔드포인트를 선언적으로 등록합니다.
- * query/mutation은 RPC 패턴이지만, httpAction은 RESTful HTTP 라우트를 직접 정의합니다.
- *
- * 사용 사례:
- *   - CLI Device Auth (POST /api/cli/auth-start)
- *   - 파일 업로드 (POST /api/apps/:id/deploy)
- *   - Webhook 수신
- *   - 외부 서비스 콜백
- *
- * @example
- * ```typescript
- * import { httpAction } from "@gencow/core";
- *
- * export const authStart = httpAction({
- *     method: "POST",
- *     path: "/api/cli/auth-start",
- *     public: true,
- *     handler: async (ctx, req) => {
- *         const code = crypto.randomUUID().slice(0, 8);
- *         return { body: { code, url: `https://gencow.com/cli-auth?code=${code}` } };
- *     },
- * });
- * ```
- */
-export function httpAction(def: {
-  method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
-  path: string;
-  public?: boolean;
-  handler: HttpActionHandler;
-}): HttpActionDef {
-  const actionDef: HttpActionDef = {
-    method: def.method,
-    path: def.path,
-    isPublic: def.public === true,
-    handler: def.handler,
-  };
-  httpActionRegistry.push(actionDef);
-  return actionDef;
-}
-
-export function getRegisteredHttpActions(): HttpActionDef[] {
-  return [...httpActionRegistry];
-}
-
-// ─── WebSocket subscription management ──────────────────
-
-export function subscribe(queryKey: string, ws: WSContext) {
-  connectedClients.add(ws);
-  if (!subscribers.has(queryKey)) {
-    subscribers.set(queryKey, new Set());
-  }
-  subscribers.get(queryKey)!.add(ws);
-}
-
-export function unsubscribe(ws: WSContext) {
-  connectedClients.delete(ws);
-  for (const clients of subscribers.values()) {
-    clients.delete(ws);
-  }
-}
-
-/** Register a raw WS connection without any query subscription (e.g. admin dashboard) */
-export function registerClient(ws: WSContext) {
-  connectedClients.add(ws);
-}
-
-export function deregisterClient(ws: WSContext) {
-  connectedClients.delete(ws);
-  for (const clients of subscribers.values()) {
-    clients.delete(ws);
-  }
-}
-
-/**
- * mutation 실행 시점에 생성되는 RealtimeCtx.
- * emit(): 데이터를 직접 push (초고빈도 mutation용).
- * refresh(): queryKey를 pending 큐에 추가, mutation 완료 후 서버가 query re-run하여 push.
- *
- * 💡 Batching: 같은 queryKey에 대한 emit이 50ms 내에 여러 번 호출되면
- * 마지막 데이터만 push하여 불필요한 전송을 방지합니다.
- *
- * ⚠️ 매 mutation 호출마다 새로 생성해야 합니다 (debounce timer가 mutation scope에 격리).
- *
- * @param options.httpCallback  BaaS 모드: Platform WS Gateway에 HTTP로 emit 전달.
- *                              설정되면 WS 직접 push 대신 이 콜백을 호출.
- *                              로컬 dev에서는 미설정 → 기존 WS 직접 push 유지.
- * @param options.queryMap      query 레지스트리 — refresh()에서 query handler를 찾아 re-run.
- * @param options.buildCtxForRefresh  refresh 시 query handler에 전달할 ctx 생성 함수.
- */
-export function buildRealtimeCtx(options?: {
-  httpCallback?: (event: { type: "emit"; queryKey: string; data: unknown }) => void;
-  queryMap?: Map<string, QueryDef<any, any>>;
-  buildCtxForRefresh?: () => GencowCtx;
-}): RealtimeCtx & { _hasEmitted: boolean; _pendingRefresh: string[]; _flushRefresh: () => Promise<void> } {
-  const pendingEmits = new Map<string, { data: unknown; timer: ReturnType<typeof setTimeout> }>();
-  const _pendingRefresh: string[] = [];
-  let _hasEmitted = false;
-
-  return {
-    emit(queryKey: string, data: unknown) {
-      _hasEmitted = true;
-      // 기존 pending timer가 있으면 취소 (debounce)
-      const existing = pendingEmits.get(queryKey);
-      if (existing) clearTimeout(existing.timer);
-
-      const timer = setTimeout(() => {
-        pendingEmits.delete(queryKey);
-
-        // BaaS 모드: Platform WS Gateway에 HTTP callback
-        if (options?.httpCallback) {
-          options.httpCallback({ type: "emit", queryKey, data });
-          return;
-        }
-
-        // 로컬 dev: WS 직접 push (기존 동작)
-        const clients = subscribers.get(queryKey);
-        if (!clients || clients.size === 0) return;
-
-        const message = JSON.stringify({
-          type: "query:updated",
-          query: queryKey,
-          data,
-        });
-        for (const ws of clients) {
-          try {
-            ws.send(message);
-          } catch {
-            clients.delete(ws);
-          }
-        }
-      }, 50); // 50ms batch window
-
-      pendingEmits.set(queryKey, { data, timer });
-    },
-
-    refresh(queryKey: string) {
-      _hasEmitted = true; // 경고 억제
-      if (!_pendingRefresh.includes(queryKey)) {
-        _pendingRefresh.push(queryKey);
-      }
-    },
-
-    get _hasEmitted() {
-      return _hasEmitted;
-    },
-    get _pendingRefresh() {
-      return [..._pendingRefresh];
-    },
-
-    async _flushRefresh() {
-      if (_pendingRefresh.length === 0) return;
-
-      // queryMap이 없으면 refresh 동작 불가 (로그 경고)
-      const qMap = options?.queryMap ?? queryRegistry;
-
-      for (const key of _pendingRefresh) {
-        const queryDef = qMap.get(key);
-        if (!queryDef) {
-          console.warn(`[gencow] refresh("${key}"): query not found in registry. Skipping.`);
-          continue;
-        }
-        try {
-          // refresh용 ctx 생성 (mutation ctx와 동일한 DB/auth 스코프)
-          if (!options?.buildCtxForRefresh) {
-            console.warn(
-              `[gencow] ⚠️  refresh("${key}"): buildCtxForRefresh not provided. ` +
-                `Query handler will receive an empty ctx — ctx.db will be undefined. ` +
-                `This is a framework configuration error. ` +
-                `💡 Ensure buildRealtimeCtx() receives a buildCtxForRefresh callback.`,
-            );
-          }
-          const refreshCtx = options?.buildCtxForRefresh?.() ?? ({} as GencowCtx);
-          const result = await queryDef.handler(refreshCtx, {});
-
-          // emit과 동일한 경로로 push
-          if (options?.httpCallback) {
-            options.httpCallback({ type: "emit", queryKey: key, data: result });
-          } else {
-            const clients = subscribers.get(key);
-            if (clients && clients.size > 0) {
-              const message = JSON.stringify({
-                type: "query:updated",
-                query: key,
-                data: result,
-              });
-              for (const ws of clients) {
-                try {
-                  ws.send(message);
-                } catch {
-                  clients.delete(ws);
-                }
-              }
-            }
-          }
-        } catch (e) {
-          console.warn(`[gencow] refresh("${key}") failed:`, e instanceof Error ? e.message : e);
-        }
-      }
-      _pendingRefresh.length = 0;
-    },
-  };
-}
-
-// ─── WebSocket message handler ──────────────────────────
-
-export function handleWsMessage(ws: WSContext, raw: string | ArrayBuffer) {
-  try {
-    const msg = typeof raw === "string" ? JSON.parse(raw) : JSON.parse(raw.toString());
-
-    if (msg.type === "subscribe" && msg.query) {
-      subscribe(msg.query, ws);
-      ws.send(JSON.stringify({ type: "subscribed", query: msg.query }));
-    }
-
-    if (msg.type === "unsubscribe" && msg.query) {
-      const clients = subscribers.get(msg.query);
-      if (clients) clients.delete(ws);
-    }
-  } catch {
-    // ignore malformed messages
-  }
-}
-
-export function getQueryHandler(key: string): QueryHandler | undefined {
-  return queryRegistry.get(key)?.handler;
-}
-
-export function getQueryDef(key: string): QueryDef | undefined {
-  return queryRegistry.get(key);
-}
-
-export function getRegisteredQueries(): string[] {
-  return Array.from(queryRegistry.keys());
-}
-
-export function getRegisteredMutations(): (MutationDef & { name: string })[] {
-  return [...mutationRegistry];
-}