sonamu 0.7.21 → 0.7.23

package/src/ssr/registry.ts

@@ -0,0 +1,52 @@
+import type { SSRRoute } from "./types";
+
+const ssrRoutes: SSRRoute[] = [];
+
+export function registerSSR(route: SSRRoute): void {
+  ssrRoutes.push(route);
+}
+
+export function getSSRRoutes(): SSRRoute[] {
+  return ssrRoutes;
+}
+
+export function clearSSRRoutes(): void {
+  ssrRoutes.length = 0;
+}
+
+export function matchSSRRoute(
+  url: string,
+): { route: SSRRoute; params: Record<string, string> } | null {
+  for (const route of ssrRoutes) {
+    const params = matchPath(route.path, url);
+    if (params !== null) {
+      return { route, params };
+    }
+  }
+  return null;
+}
+
+// 간단한 path matching
+export function matchPath(pattern: string, url: string): Record<string, string> | null {
+  const patternParts = pattern.split("/").filter(Boolean);
+  const urlParts = url.split("?")[0].split("/").filter(Boolean);
+
+  if (patternParts.length !== urlParts.length) {
+    return null;
+  }
+
+  const params: Record<string, string> = {};
+
+  for (let i = 0; i < patternParts.length; i++) {
+    const patternPart = patternParts[i];
+    const urlPart = urlParts[i];
+
+    if (patternPart.startsWith(":")) {
+      params[patternPart.slice(1)] = urlPart;
+    } else if (patternPart !== urlPart) {
+      return null;
+    }
+  }
+
+  return params;
+}

package/src/ssr/renderer.ts

@@ -0,0 +1,105 @@
+import path from "node:path";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import type { ViteDevServer } from "vite";
+import type { SonamuFastifyConfig } from "../types/types";
+import type { PreloadedData, SSRRoute } from "./types";
+
+export async function renderSSR(
+  url: string,
+  route: SSRRoute,
+  params: Record<string, string>,
+  request: FastifyRequest,
+  reply: FastifyReply,
+  config: SonamuFastifyConfig,
+  vite?: ViteDevServer,
+): Promise<string> {
+  const { Sonamu } = await import("../api/sonamu");
+
+  // 1. preload 실행 → SSRQuery[] 획득 (dev/prod 공통)
+  const preloadConfig = route.preload ? route.preload(params) : [];
+  const preloadedData: PreloadedData[] = [];
+
+  for (const { modelName, methodName, params: apiParams, serviceKey } of preloadConfig) {
+    const api = Sonamu.syncer.apis.find(
+      (a) => a.modelName === modelName && a.methodName === methodName,
+    );
+
+    if (!api) {
+      console.warn(`API not found: ${modelName}.${methodName}`);
+      continue;
+    }
+
+    try {
+      const result = await Sonamu.invokeApiForSSR(api, apiParams, config, request, reply);
+      preloadedData.push({
+        queryKey: [...serviceKey, ...apiParams],
+        data: result,
+      });
+    } catch (e) {
+      console.error(`Failed to preload ${modelName}.${methodName}:`, e);
+    }
+  }
+
+  // 2. Dev/Prod 스크립트 추출
+  let viteScripts: string;
+  let render: (
+    url: string,
+    preloadedData: PreloadedData[],
+  ) => Promise<{ html: string; dehydratedState: unknown }>;
+
+  if (vite) {
+    // Dev: Vite Dev Server
+    const fs = await import("node:fs/promises");
+    const indexHtmlPath = path.join(vite.config.root, "index.html");
+    const originalHtml = await fs.readFile(indexHtmlPath, "utf-8");
+    const transformedHtml = await vite.transformIndexHtml(url, originalHtml);
+
+    // Vite가 주입한 스크립트 추출
+    viteScripts = extractScriptTags(transformedHtml);
+
+    const entryModule = await vite.ssrLoadModule("/src/entry-server.generated.tsx");
+    render = entryModule.render;
+  } else {
+    // Prod: 빌드된 파일
+    const fs = await import("node:fs");
+    const webDistPath = path.join(Sonamu.apiRootPath, "public", "web");
+    const ssrPath = path.join(Sonamu.apiRootPath, "dist", "ssr");
+
+    // 빌드된 index.html에서 스크립트 추출
+    const builtHtml = fs.readFileSync(path.join(webDistPath, "index.html"), "utf-8");
+    viteScripts = extractScriptTags(builtHtml);
+
+    const entryModule = await import(path.join(ssrPath, "entry-server.generated.js"));
+    render = entryModule.render;
+  }
+
+  // 3. RouterProvider 렌더링 (full document)
+  const { html: fullDocHtml, dehydratedState } = await render(url, preloadedData);
+
+  // 4. SSR 데이터 스크립트 생성
+  const ssrDataScript = dehydratedState
+    ? `<script>window.__SONAMU_SSR__ = ${JSON.stringify(dehydratedState).replace(/</g, "\\u003c")};</script>`
+    : "";
+
+  // 5. SSR Config 스크립트 생성 (disableHydrate)
+  const ssrConfigScript = route.disableHydrate
+    ? `<script>window.__SONAMU_SSR_CONFIG__ = ${JSON.stringify({ disableHydrate: true })};</script>`
+    : "";
+
+  // 6. Vite 스크립트와 SSR 데이터를 </body> 직전에 주입
+  const finalHtml = fullDocHtml.replace(
+    "</body>",
+    `${ssrConfigScript}\n${ssrDataScript}\n${viteScripts}\n</body>`,
+  );
+
+  return finalHtml;
+}
+
+/**
+ * HTML에서 <script>, <link> 태그를 추출
+ */
+function extractScriptTags(html: string): string {
+  const scriptRegex = /<script[^>]*>[\s\S]*?<\/script>|<link[^>]*>/gi;
+  const matches = html.match(scriptRegex) || [];
+  return matches.join("\n");
+}

package/src/ssr/types.ts

@@ -0,0 +1,20 @@
+// Branded type - 실수로 일반 객체 사용 방지
+export type SSRQuery = {
+  modelName: string; // 'UserModel' - 서버 모델 호출용
+  methodName: string; // 'findById' - 서버 메서드 호출용
+  params: unknown[]; // [subset, id] - Context 제외한 실제 파라미터
+  serviceKey: [string, string]; // ['User', 'getUsers'] - React Query queryKey용
+} & { __brand: "SSRQuery" };
+
+export type PreloadConfig = SSRQuery[];
+
+export type SSRRoute = {
+  path: string;
+  preload?: (params: Record<string, string>) => PreloadConfig;
+  disableHydrate?: boolean;
+};
+
+export type PreloadedData = {
+  queryKey: unknown[];
+  data: unknown;
+};

package/src/syncer/syncer.ts

@@ -12,6 +12,7 @@ import type { WorkflowMetadata } from "..";
 import { registeredApis } from "../api/decorators";
 import { Sonamu } from "../api/sonamu";
 import { EntityManager, type EntityNamesRecord } from "../entity/entity-manager";
+import { AlreadyProcessedException } from "../exceptions/so-exceptions";
 import { Naite } from "../naite/naite";
 import { TemplateManager } from "../template/template-manager";
 import type { GenerateOptions, PathAndCode } from "../types/types";
@@ -63,6 +64,18 @@ export class Syncer {
     const changedFiles = await findChangedFilesUsingChecksums();
     if (changedFiles.length === 0) {
       console.log(chalk.black.bgGreen(centerText("All files are synced!")));
+
+      // 변경사항이 없어도 SSR 템플릿은 생성 (초기 설정 시, 이미 존재하면 스킵)
+      try {
+        await generateTemplate("queries", {}, { overwrite: false });
+        await generateTemplate("entry_server", {}, { overwrite: false });
+      } catch (e) {
+        // 파일이 이미 존재하면 무시
+        if (!(e instanceof AlreadyProcessedException)) {
+          console.error("Failed to generate SSR templates:", e);
+        }
+      }
+
       return;
     }
 
@@ -91,6 +104,18 @@ export class Syncer {
       return;
     }
 
+    // SSR 설정 파일 변경 감지
+    if (diffFilePath.includes("/src/ssr/")) {
+      console.log(chalk.bold.yellow("SSR config changed - reloading..."));
+      // SSR 파일도 invalidate 후 reload
+      if (!isTest()) {
+        await hot.invalidateFile(diffFilePath, event);
+      }
+      await this.autoloadSSRRoutes();
+      this.eventEmitter.emit("onHMRCompleted");
+      return;
+    }
+
     // 일단 변경된 파일과 dependent 파일들을 invalidate 합니다.
     // 한 번 이상 import된 친구들에 대해서만 실제 작업이 일어납니다.
     // 그러니 안심하고 invalidate 해도 됩니다.
@@ -229,6 +254,36 @@ export class Syncer {
     await Sonamu.workflows.synchronize(this.workflows);
   }
 
+  async autoloadSSRRoutes(): Promise<void> {
+    const ssrConfigPath = path.join(Sonamu.apiRootPath, "src/ssr");
+
+    // 기존 routes 초기화
+    const { clearSSRRoutes } = await import("../ssr");
+    clearSSRRoutes();
+
+    // ssr 폴더 없으면 스킵
+    if (!(await exists(ssrConfigPath))) {
+      return;
+    }
+
+    // ssr 폴더 안의 모든 .ts 파일 로드
+    const { globAsync } = await import("../utils/async-utils");
+    const { importMembers } = await import("../utils/esm-utils");
+    const { runtimePath } = await import("../utils/path-utils");
+
+    // runtimePath를 사용하여 개발/프로덕션 환경에 맞는 확장자 처리
+    const files = await globAsync(path.join(ssrConfigPath, runtimePath("**/*.ts")));
+
+    for (const file of files) {
+      try {
+        // importMembers를 사용하면 파일의 side effect(registerSSR 호출)가 실행됨
+        await importMembers(file);
+      } catch (e) {
+        console.error(`Failed to load SSR route: ${file}`, e);
+      }
+    }
+  }
+
   /**
    * 실제 싱크를 수행하는 본체입니다.
    * 변경된 파일들을 타입별로 분류하고 각 타입에 맞는 액션을 실행합니다.
@@ -371,6 +426,10 @@ export class Syncer {
 
     await this.actionGenerateServices(params);
     await this.actionGenerateHttps();
+
+    // queries.generated.ts 및 entry-server.generated.tsx 재생성
+    await generateTemplate("queries", {}, { overwrite: true });
+    await generateTemplate("entry_server", {}, { overwrite: true });
   }
 
   // web/.sonamu.env 에 현재 설정값 저장

package/src/tasks/decorator.ts

@@ -45,12 +45,22 @@ export type DefineWorkflowOptions<
 // 이것들은 syncer에서 한번에 load한 다음, WorkflowManager에서 synchronize를 통해 등록됨.
 export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undefined = undefined>(
   options: DefineWorkflowOptions<Input, Output, TSchema>,
-) {
-  return (fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => {
+): (fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => WorkflowMetadata;
+export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undefined = undefined>(
+  options: DefineWorkflowOptions<Input, Output, TSchema>,
+  fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>,
+): WorkflowMetadata;
+export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undefined = undefined>(
+  options: DefineWorkflowOptions<Input, Output, TSchema>,
+  fn?: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>,
+):
+  | WorkflowMetadata
+  | ((fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => WorkflowMetadata) {
+  const decorated = (fn: WorkflowFunction<SchemaOutput<TSchema, Input>, Output>) => {
     const id = randomUUID();
     const workflowName = options.name ?? inflection.underscore(fn.name);
 
-    const decorated: WorkflowMetadata = {
+    const metadata: WorkflowMetadata = {
       type: "workflow" as const,
       id,
       name: workflowName,
@@ -66,6 +76,12 @@ export function workflow<Input, Output, TSchema extends StandardSchemaV1 | undef
       fn: fn as WorkflowFunction<unknown, unknown>,
     };
 
-    return decorated;
+    return metadata;
   };
+
+  if (!fn) {
+    return decorated;
+  }
+
+  return decorated(fn);
 }

package/src/tasks/step-wrapper.ts

@@ -70,11 +70,20 @@ export class StepWrapper {
     }
 
     return {
-      run: ((stepApi: StepApi) => {
-        return (...args: TArgs) => {
-          return stepApi.run(config, () => fn(...args));
-        };
-      })(this.#stepApi),
+      run: ((stepApi: StepApi, ...args: TArgs) => {
+        return stepApi.run(config, () => fn(...args));
+      }).bind(null, this.#stepApi),
+    };
+  }
+
+  define<TArgs extends unknown[], TResult>(
+    config: { name: string },
+    fn: StepFunction<TArgs, TResult>,
+  ) {
+    return {
+      run: ((stepApi: StepApi, ...args: TArgs) => {
+        return stepApi.run(config, () => fn(...args));
+      }).bind(null, this.#stepApi),
     };
   }
 

package/src/tasks/workflow-manager.ts

@@ -1,3 +1,4 @@
+import { getLogger, type Logger } from "@logtape/logtape";
 import { BackendPostgres, OpenWorkflow, type Worker } from "@sonamu-kit/tasks";
 import type {
   RunnableWorkflow,
@@ -14,6 +15,7 @@ import { schedule as cronSchedule, type ScheduledTask } from "node-cron";
 import type { ZodObject } from "zod";
 import type { Context } from "../api/context";
 import { Sonamu } from "../api/sonamu";
+import { convertDomainToCategory } from "../logger/category";
 import { Naite } from "../naite/naite";
 import { createMockSSEFactory } from "../stream/sse";
 import type { Executable } from "../types/types";
@@ -34,6 +36,7 @@ export interface WorkflowOptions {
 // Workflow 함수의 타입, @sonamu-kit/tasks와 다른 점은 step을 한번 감싼 형태.
 export type WorkflowFunction<Input, Output> = (
   params: Readonly<{
+    logger: Logger;
     input: Input;
     step: StepWrapper;
     version: string | null;
@@ -266,7 +269,12 @@ export class WorkflowManager {
 
       const step = new StepWrapper(params.step);
       return Sonamu.asyncLocalStorage.run({ context }, () =>
-        options.function({ input: params.input, step, version: params.version }),
+        options.function({
+          input: params.input,
+          step,
+          version: params.version,
+          logger: getLogger(convertDomainToCategory(options.name, "workflow")),
+        }),
       );
     };
 

package/src/template/implementations/entry-server.template.ts

@@ -0,0 +1,81 @@
+import type { TemplateOptions } from "../../types/types";
+import { Template } from "../template";
+
+export class Template__entry_server extends Template {
+  constructor() {
+    super("entry_server");
+  }
+
+  getTargetAndPath() {
+    return {
+      target: "web/src",
+      path: `entry-server.generated.tsx`,
+    };
+  }
+
+  render({}: TemplateOptions["entry_server"]) {
+    const body = `
+import { QueryClient, dehydrate } from '@tanstack/react-query';
+import { createMemoryHistory, createRouter, RouterProvider } from '@tanstack/react-router';
+import { renderToString } from 'react-dom/server';
+import { routeTree } from './routeTree.gen';
+import { Suspense } from "react";
+
+export type PreloadedData = {
+  queryKey: any[];
+  data: any;
+};
+
+export async function render(url: string, preloadedData: PreloadedData[] = []) {
+  // QueryClient 생성
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 5000,
+        retry: false,
+      },
+    },
+  });
+
+  // Preloaded 데이터를 queryClient에 직접 주입
+  for (const { queryKey, data } of preloadedData) {
+    queryClient.setQueryData(queryKey, data);
+  }
+
+  // Dehydrate
+  const dehydratedState = dehydrate(queryClient);
+
+  // SSR용 메모리 히스토리 생성
+  const memoryHistory = createMemoryHistory({
+    initialEntries: [url],
+  });
+
+  // Router 생성 (SSR 모드)
+  const router = createRouter({
+    routeTree,
+    context: { queryClient },
+    history: memoryHistory,
+    defaultPreload: 'intent',
+  });
+
+  // 라우터 초기화: SSR에서 반드시 await router.load() 호출 필요
+  await router.load();
+
+  // RouterProvider만 렌더링 (Suspense로 래핑 - hydration mismatch 방지)
+  const appHtml = renderToString(<Suspense fallback={null}><RouterProvider router={router} /></Suspense>);
+
+  return {
+    html: appHtml,
+    dehydratedState,
+  };
+}
+    `.trim();
+
+    return {
+      ...this.getTargetAndPath(),
+      body,
+      importKeys: [],
+      customHeaders: [],
+    };
+  }
+}

package/src/template/implementations/model.template.ts

@@ -61,7 +61,9 @@ class ${entityId}ModelClass extends BaseModelClass<
   typeof ${names.camel}SubsetQueries,
   typeof ${names.camel}LoaderQueries
 > {
-  modelName = "${entityId}";
+  constructor() {
+    super("${entityId}", ${names.camel}SubsetQueries, ${names.camel}LoaderQueries);
+  }
 
   @api({ httpMethod: "GET", clients: ["axios", "tanstack-query"], resourceName: "${entityId}" })
   async findById<T extends ${entityId}SubsetKey>(
@@ -188,7 +190,7 @@ class ${entityId}ModelClass extends BaseModelClass<
   }
 }
 
-export const ${entityId}Model = new ${entityId}ModelClass(${names.camel}SubsetQueries, ${names.camel}LoaderQueries);
+export const ${entityId}Model = new ${entityId}ModelClass();
       `.trim(),
       importKeys: [],
     };

package/src/template/implementations/queries.template.ts

@@ -0,0 +1,111 @@
+import inflection from "inflection";
+import { diff, unique } from "radashi";
+import { apiParamToTsCode, apiParamTypeToTsType } from "../../api/code-converters";
+import type { ExtendedApi } from "../../api/decorators";
+import { Sonamu } from "../../api/sonamu";
+import type { TemplateOptions } from "../../types/types";
+import { ApiParamType } from "../../types/types";
+import { Template } from "../template";
+
+export class Template__queries extends Template {
+  constructor() {
+    super("queries");
+  }
+
+  getTargetAndPath() {
+    const { dir } = Sonamu.config.api;
+    return {
+      target: `${dir}/src/application`,
+      path: `queries.generated.ts`,
+    };
+  }
+
+  render({}: TemplateOptions["queries"]) {
+    const { apis } = Sonamu.syncer;
+
+    // tanstack-query를 포함한 API만 필터링
+    const queryApis = apis.filter((api) => api.options.clients?.includes("tanstack-query"));
+
+    // 모델별로 그룹화
+    const apisByModel = new Map<string, ExtendedApi[]>();
+    for (const api of queryApis) {
+      const modelName = api.modelName.replace(/Model$/, "").replace(/Frame$/, "");
+      if (!apisByModel.has(modelName)) {
+        apisByModel.set(modelName, []);
+      }
+      apisByModel.get(modelName)?.push(api);
+    }
+
+    const namespaces: string[] = [];
+    const importKeys: string[] = [];
+    let typeParamNames: string[] = [];
+
+    for (const [modelName, modelApis] of apisByModel) {
+      const functions: string[] = [];
+
+      for (const api of modelApis) {
+        // Context 제외한 파라미터
+        const paramsWithoutContext = api.parameters.filter(
+          (param) =>
+            !ApiParamType.isContext(param.type) &&
+            !ApiParamType.isRefKnex(param.type) &&
+            !(param.optional === true && param.name.startsWith("_")),
+        );
+
+        // 타입 파라미터 이름 수집
+        typeParamNames = typeParamNames.concat(api.typeParameters.map((tp) => tp.id));
+
+        // 타입 파라미터 정의
+        const typeParametersAsTsType = api.typeParameters
+          .map((typeParam) => {
+            return apiParamTypeToTsType(typeParam, importKeys);
+          })
+          .join(", ");
+        const typeParamsDef = typeParametersAsTsType ? `<${typeParametersAsTsType}>` : "";
+
+        // 파라미터 정의
+        const paramsDef = apiParamToTsCode(paramsWithoutContext, importKeys);
+        const paramNames = paramsWithoutContext.map((p) => p.name).join(", ");
+
+        // serviceMethodName 계산 (services.template.ts와 동일한 로직)
+        const serviceMethodName = api.options.resourceName
+          ? `get${inflection.camelize(api.options.resourceName)}`
+          : api.methodName;
+
+        // SSRQuery 함수 생성 (함수명도 serviceMethodName 사용)
+        functions.push(
+          `
+  export const ${serviceMethodName} = ${typeParamsDef}(${paramsDef}): SSRQuery =>
+    createSSRQuery('${api.modelName}', '${api.methodName}', [${paramNames}], ['${modelName}', '${serviceMethodName}']);
+          `.trim(),
+        );
+      }
+
+      namespaces.push(
+        `
+export namespace ${modelName}Service {
+${functions.join("\n\n")}
+}
+      `.trim(),
+      );
+    }
+
+    return {
+      ...this.getTargetAndPath(),
+      body: namespaces.join("\n\n"),
+      importKeys: diff(unique(importKeys), typeParamNames),
+      customHeaders: [
+        "/** biome-ignore-all lint: generated는 무시 */",
+        "/** biome-ignore-all assist: generated는 무시 */",
+        "",
+        `import type { SSRQuery } from 'sonamu/ssr';`,
+        "",
+        `// SSRQuery 헬퍼 함수`,
+        `function createSSRQuery(modelName: string, methodName: string, params: any[], serviceKey: [string, string]): SSRQuery {`,
+        `  return { modelName, methodName, params, serviceKey, __brand: 'SSRQuery' } as SSRQuery;`,
+        `}`,
+        "",
+      ],
+    };
+  }
+}

package/src/template/implementations/view_enums_select.template.ts

@@ -22,33 +22,47 @@ export class Template__view_enums_select extends Template {
     return {
       ...this.getTargetAndPath(names, enumId),
       body: `
-import React from 'react';
-import {
-  Dropdown,
-  DropdownProps,
-} from 'semantic-ui-react';
+
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@sonamu-kit/react-components/components';
 
 import { ${enumId}, ${enumId}Label } from '@/services/sonamu.generated';
 
 export type ${enumId}SelectProps = {
+  value?: string;
+  onValueChange?: (value: string | null | undefined) => void;
   placeholder?: string;
   textPrefix?: string;
-} & DropdownProps;
-export function ${enumId}Select({placeholder, textPrefix, ...props}: ${enumId}SelectProps) {
-  const typeOptions = ${enumId}.options.map((key) => ({
-    key,
-    value: key,
-    text: (textPrefix ?? '${label}: ') + ${enumId}Label[key],
-  }));
+  clearable?: boolean;
+  disabled?: boolean;
+  className?: string;
+};
+
+export function ${enumId}Select({
+  value,
+  onValueChange,
+  placeholder,
+  textPrefix,
+  clearable,
+  disabled,
+  className,
+}: ${enumId}SelectProps) {
+  // Filter out empty string from options (Radix UI doesn't allow empty string as SelectItem value)
+  const validOptions = ${enumId}.options.filter((key) => (key as string) !== "");
 
   return (
-    <Dropdown
-      placeholder={placeholder ?? "${label}"}
-      selection
-      options={typeOptions}
-      selectOnBlur={false}
-      {...props}
-    />
+    <Select value={value ?? ""} onValueChange={onValueChange} disabled={disabled}>
+      <SelectTrigger className={className}>
+        <SelectValue placeholder={placeholder ?? "${label}"} />
+      </SelectTrigger>
+      <SelectContent>
+        {clearable && <SelectItem value="">전체</SelectItem>}
+        {validOptions.map((key) => (
+          <SelectItem key={key} value={key}>
+            {(textPrefix ?? "") + ${enumId}Label[key]}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
   );
 }
       `.trim(),