@gencow/core 0.1.28 → 0.1.30

package/src/config.ts

@@ -0,0 +1,119 @@
+/**
+ * User-facing project configuration for `gencow.config.ts`.
+ *
+ * The config file is intentionally small today, but we expose a stable typed
+ * contract so editors can offer autocomplete and inline explanations.
+ */
+
+/**
+ * Cloud deployment settings written to `gencow.config.ts`.
+ *
+ * @example
+ * ```ts
+ * deploy: {
+ *   app: "my-todo",
+ * }
+ * ```
+ */
+export interface GencowDeployConfig {
+  /**
+   * Default cloud app name to target for CLI flows that attach project metadata.
+   *
+   * This is commonly added automatically after `gencow app create`.
+   */
+  app?: string;
+}
+
+/**
+ * Local database settings for the Gencow dev server.
+ *
+ * @example
+ * ```ts
+ * db: {
+ *   url: "./.gencow/data",
+ * }
+ * ```
+ */
+export interface GencowDbConfig {
+  /**
+   * Local database path used by the default PGlite setup.
+   *
+   * Default: `"./.gencow/data"`
+   */
+  url?: string;
+}
+
+/**
+ * Project configuration for `gencow.config.ts`.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from "@gencow/core";
+ *
+ * export default defineConfig({
+ *   functionsDir: "./gencow",
+ *   schema: ["./gencow/schema.ts", "./gencow/auth-schema.ts"],
+ *   codegenOutDir: "./src/gencow",
+ *   storage: "./.gencow/uploads",
+ *   db: { url: "./.gencow/data" },
+ *   port: 5456,
+ *   deploy: { app: "my-app" },
+ * });
+ * ```
+ */
+export interface GencowConfig {
+  /**
+   * Directory containing your backend modules such as `index.ts`, `schema.ts`,
+   * and optional files like `crons.ts` or `seed.ts`.
+   *
+   * Default: `"./gencow"`
+   */
+  functionsDir?: string;
+
+  /**
+   * Path to the Drizzle schema file, or multiple schema files when your project
+   * splits auth and application tables.
+   *
+   * Default: `"./gencow/schema.ts"`
+   */
+  schema?: string | string[];
+
+  /**
+   * Output directory for generated frontend codegen artifacts such as `api.ts`
+   * and declaration files.
+   *
+   * Default: `"./src/gencow"`
+   */
+  codegenOutDir?: string;
+
+  /**
+   * Directory used for uploaded file storage in local development.
+   *
+   * Default: `"./.gencow/uploads"`
+   */
+  storage?: string;
+
+  /**
+   * Local database configuration.
+   */
+  db?: GencowDbConfig;
+
+  /**
+   * Port used by the local dev server.
+   *
+   * Default: `5456`
+   */
+  port?: number;
+
+  /**
+   * Optional cloud deployment metadata.
+   */
+  deploy?: GencowDeployConfig;
+}
+
+/**
+ * Helper for authoring typed `gencow.config.ts` files with editor autocomplete.
+ */
+export function defineConfig(config: GencowConfig): GencowConfig {
+  return config;
+}

package/src/context.ts

@@ -0,0 +1,152 @@
+import type { Storage } from "./storage.js";
+import type { Scheduler } from "./scheduler.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";
+import type { RetryOptions } from "./retry.js";
+import type { GencowProcedureDef } from "./procedure.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;
+
+  /**
+   * 특정 queryKey 구독자에게 재조회 신호만 보냅니다.
+   * private/RLS query처럼 서버가 안전하게 full payload를 만들 수 없는 경우 기본값입니다.
+   */
+  invalidate(queryKey: string | string[]): 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;
+}
+
+export type RealtimeNotifyEvent =
+  | { type: "emit"; queryKey: string; data: unknown }
+  | { type: "invalidate"; queryKeys: string[] };
+
+/**
+ * 사용자 함수(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?: 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;
+}
+
+export interface GencowDefinition {
+  [procedureName: string]: GencowProcedureDef<any, any, any, any>;
+}
+
+export interface GencowApiDefinition {
+  procedures: GencowDefinition;
+}
+
+export function defineApi<const TApi extends GencowApiDefinition>(api: TApi): TApi {
+  return api;
+}

package/src/crud.ts

@@ -57,7 +57,9 @@ import {
 } from "drizzle-orm";
 import type { PgTable, AnyPgColumn } from "drizzle-orm/pg-core";
 import { getTableConfig } from "drizzle-orm/pg-core";
-import { query, mutation } from "./reactive.js";
+import { buildQuerySubscriptionKey } from "./reactive-realtime.js";
+import { query } from "./reactive-query.js";
+import { mutation } from "./reactive-mutation.js";
 import { v } from "./v.js";
 import { getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
 
@@ -473,23 +475,12 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
     return await fn(db);
   }
 
-  // ── 내부 헬퍼: list+count 데이터 가져오기 (realtime push용 재사용) ──
-  // Runs inside db.transaction so createRlsDb() RLS session vars apply for RLS.
-  // ⚠️ limit/offset 없이 전체 SELECT — 대량 데이터 시 성능 저하 주의
-  // TODO(P2): realtime emit 시 invalidation 메시지만 전송하고 클라이언트가 re-fetch하는 패턴 검토
-  async function fetchListWithTotal(db: any, whereClause?: SQL, userId?: string) {
-    // ownerRls 적용 시 realtime emit에도 userId 필터 추가
-    // → 다른 사용자에게 타인 데이터가 push되지 않도록
-    let effectiveWhere = whereClause;
-    if (ownerMeta && userId && !ownerMeta.readPublic) {
-      const ownerFilter = eq(ownerMeta.column, userId);
-      effectiveWhere = effectiveWhere ? and(effectiveWhere, ownerFilter) : ownerFilter;
-    }
-    return await inRlsOrPlainTx(db, async (tx: any) => {
-      const data = await tx.select().from(anyTable).where(effectiveWhere).orderBy(desc(defaultOrderCol));
-      const countResult = await tx.select({ count: drizzleCount() }).from(anyTable).where(effectiveWhere);
-      return { data, total: Number(countResult[0]?.count ?? 0) };
-    });
+  function invalidateListRealtime(ctx: any) {
+    ctx.realtime.invalidate(`${prefix}.list`);
+  }
+
+  function invalidateGetRealtime(ctx: any, id: unknown) {
+    ctx.realtime.invalidate(buildQuerySubscriptionKey(`${prefix}.get`, { id }));
   }
 
   // ── methods 필터링: 지정된 메서드만 레지스트리 등록 ──
@@ -636,13 +627,9 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
             tx.insert(anyTable).values(insertData).returning(),
           );
 
-          // Realtime push — { data, total } 형태로 emit
-          // ownerRls 시 해당 사용자 데이터만 push (타 사용자에게 누출 방지)
-          // S5: requireAuth로 확실한 userId 획득 (getUserIdentity null 방지)
+          // Realtime push: list는 payload 없이 invalidation으로 갱신
           if (useRealtime && enabledMethods.has("list")) {
-            const currentUserId = user?.id;
-            const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
-            ctx.realtime.emit(`${prefix}.list`, listResult);
+            invalidateListRealtime(ctx);
           }
 
           return result;
@@ -690,16 +677,15 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
             tx.update(anyTable).set(updateData).where(updateWhere).returning(),
           );
 
-          // Realtime push (list + get 양쪽) — { data, total } 형태
-          // S5: ownerRls 시 user.id 사용 (getUserIdentity null 방지)
+          // Realtime push: list는 invalidation, public exact-id get만 full payload 유지
           if (useRealtime) {
-            const currentUserId = ownerMeta ? user?.id : undefined;
             if (enabledMethods.has("list")) {
-              const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
-              ctx.realtime.emit(`${prefix}.list`, listResult);
+              invalidateListRealtime(ctx);
             }
             if (enabledMethods.has("get")) {
-              ctx.realtime.emit(`${prefix}.get`, result);
+              const getKey = buildQuerySubscriptionKey(`${prefix}.get`, { id });
+              if (isPublic && !ownerMeta) ctx.realtime.emit(getKey, result);
+              else invalidateGetRealtime(ctx, id);
             }
           }
 
@@ -736,12 +722,9 @@ export function crud<T extends PgTable>(table: T, options?: CrudOptions<T>) {
             }
           });
 
-          // Realtime push — { data, total } 형태
-          // S5: ownerRls 시 user.id 사용
+          // Realtime push: list는 payload 없이 invalidation으로 갱신
           if (useRealtime && enabledMethods.has("list")) {
-            const currentUserId = ownerMeta ? user?.id : undefined;
-            const listResult = await fetchListWithTotal(ctx.db, undefined, currentUserId);
-            ctx.realtime.emit(`${prefix}.list`, listResult);
+            invalidateListRealtime(ctx);
           }
 
           return { success: true };

package/src/document-types.ts

@@ -6,9 +6,16 @@ export type DocumentConvertMode =
   | "prefer-external"
   | "force-external"
   | "force-ocr";
-export type DocumentConvertProvider = "auto" | "local_text" | "gemini" | "openai" | "ocr" | "custom_vlm";
+export type DocumentConvertProvider =
+  | "auto"
+  | "local_text"
+  | "opendataloader"
+  | "gemini"
+  | "openai"
+  | "ocr"
+  | "custom_vlm";
 export type DocumentResolvedProvider = Exclude<DocumentConvertProvider, "auto">;
-export type DocumentProviderRoute = "local_text" | "vlm" | "ocr_fallback";
+export type DocumentProviderRoute = "local_text" | "opendataloader" | "vlm" | "ocr_fallback";
 export type DocumentCacheArtifact = "convert" | "embedding" | "summary" | "rerank";
 
 export type DocumentConvertInput = {

package/src/http-action.ts

@@ -0,0 +1,101 @@
+import type { GencowCtx } from "./context.js";
+
+/** httpAction 핸들러 — Hono 대신 Request/Response 타입으로 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;
+}
+
+/** 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;
+}
+
+// ─── httpAction registry (globalThis) ───────────────────
+// globalThis shared singleton — dual-bundle safe (see analysis-dual-module-registry.md).
+
+declare global {
+  var __gencow_httpActionRegistry: HttpActionDef[];
+}
+
+if (!globalThis.__gencow_httpActionRegistry) globalThis.__gencow_httpActionRegistry = [];
+
+export const httpActionRegistry = globalThis.__gencow_httpActionRegistry;
+
+/**
+ * 커스텀 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];
+}

package/src/index.ts

@@ -9,17 +9,21 @@ export type {
   GencowCtx,
   AuthCtx,
   UserIdentity,
-  QueryDef,
-  MutationDef,
   RealtimeCtx,
+  RealtimeNotifyEvent,
+  AIContext,
+  AIMessage,
+  AIResult,
+} from "./context.js";
+export { defineApi } from "./context.js";
+export type { QueryDef } from "./reactive-query-types.js";
+export type { MutationDef } from "./reactive-mutation-types.js";
+export type {
   HttpActionDef,
   HttpActionRequest,
   HttpActionResponse,
   HttpActionHandler,
-  AIContext,
-  AIMessage,
-  AIResult,
-} from "./reactive.js";
+} from "./http-action.js";
 export type {
   SearchPrimitive,
   SearchScope,
@@ -47,6 +51,28 @@ export type {
   WorkflowDocumentServicesCtx,
 } from "./document-types.js";
 export { buildDocumentCacheKey } from "./document-types.js";
+export type {
+  WakeAppBootFailedResult,
+  WakeAppDeferredResult,
+  WakeAppDeferredStatus,
+  WakeAppResult,
+  WakeAppSuccessResult,
+  WakeAppSuccessStatus,
+} from "./wake-app-result.js";
+export {
+  DEFAULT_WAKE_RETRY_AFTER_SEC,
+  buildWakeAppBootFailedResult,
+  buildWakeAppSuccessResult,
+  isWakeAppDeferredResult,
+} from "./wake-app-result.js";
+export type { PlatformCapacityPreset, PlatformCapacityProfileName } from "./platform-capacity-profile.js";
+export {
+  PLATFORM_CAPACITY_ENV_KEYS,
+  PLATFORM_CAPACITY_PRESETS,
+  PLATFORM_CAPACITY_PROFILE_ENV,
+  detectPlatformCapacityProfile,
+  resolvePlatformCapacityPreset,
+} from "./platform-capacity-profile.js";
 export type {
   RagIngestReindexMode,
   RagIngestInput,
@@ -83,23 +109,33 @@ export type {
   RagReindexMode,
   RagReindexPlan,
 } from "./rag-operations-types.js";
-export { ragCorpora, ragSources, ragSections, ragChunks, ragIngestJobs, ragOperationMetrics } from "./rag-schema.js";
 export {
-  query,
-  mutation,
-  httpAction,
-  buildRealtimeCtx,
+  ragCorpora,
+  ragSources,
+  ragSections,
+  ragChunks,
+  ragIngestJobs,
+  ragOperationMetrics,
+} from "./rag-schema.js";
+export { buildQuerySubscriptionKey, subscriptionKeyMatchesQueryKey } from "./reactive-realtime.js";
+export { query, getQueryHandler, getQueryDef, getRegisteredQueries } from "./reactive-query.js";
+export { mutation, getRegisteredMutations } from "./reactive-mutation.js";
+export { procQuery, procMutation } from "./procedure.js";
+export type {
+  GencowProcedureBuilder,
+  GencowProcedureDef,
+  GencowProcedureMiddleware,
+  GencowProcedureHandler,
+} from "./procedure.js";
+export { httpAction, getRegisteredHttpActions } from "./http-action.js";
+export {
   subscribe,
   unsubscribe,
   registerClient,
   deregisterClient,
+  buildRealtimeCtx,
   handleWsMessage,
-  getQueryHandler,
-  getQueryDef,
-  getRegisteredQueries,
-  getRegisteredMutations,
-  getRegisteredHttpActions,
-} from "./reactive.js";
+} from "./reactive-realtime.js";
 export type { Storage, StoredFile } from "./storage.js";
 export { createScheduler, getSchedulerInfo } from "./scheduler.js";
 export type {
@@ -150,14 +186,36 @@ export { filterTenantRuntimeEnvVars, isReservedTenantRuntimeEnvKey } from "./run
 export { cronJobs } from "./crons.js";
 export type { CronJobsBuilder, CronJobDef, IntervalOptions, DailyOptions, WeeklyOptions } from "./crons.js";
 export { defineAuth } from "./auth-config.js";
-export type { GencowAuthConfig, AuthEmailVerification } from "./auth-config.js";
+export type {
+  GencowAuthConfig,
+  AuthEmailVerification,
+  AuthPasswordReset,
+  AuthEvents,
+  AuthHookContext,
+  AuthUserLike,
+  AuthOAuthConfig,
+  SocialProviderConfig,
+  SocialProvidersConfig,
+  KakaoConfig,
+  NaverConfig,
+  CustomOAuthProvider,
+  OAuthUserInfo,
+} from "./auth-config.js";
+export { defineConfig } from "./config.js";
+export type { GencowConfig, GencowDbConfig, GencowDeployConfig } from "./config.js";
 
 // ─── RLS + CRUD Factory ───────────
 export { ownerRls, getOwnerRlsMeta, registerOwnerRls } from "./rls.js";
 export type { OwnerRlsMeta } from "./rls.js";
 export { createRlsDb } from "./rls-db.js";
 export type { RlsSessionContext } from "./rls-db.js";
-export { crud, parseFilterNode, applyFilterOp, getOwnerRlsTables, getRegisteredCrudCodegenMeta } from "./crud.js";
+export {
+  crud,
+  parseFilterNode,
+  applyFilterOp,
+  getOwnerRlsTables,
+  getRegisteredCrudCodegenMeta,
+} from "./crud.js";
 export type { CrudCodegenMeta } from "./crud.js";
 
 // Deprecated alias — 하위호환용, 향후 메이저 버전에서 제거 예정