@simplysm/sd-cli 14.0.49 → 14.0.51

package/docs/config/sd-publish-config.md

@@ -0,0 +1,72 @@
+# SdPublishConfig
+
+패키지 배포 설정. `type` 필드로 분기하는 discriminated union이다.
+
+```typescript
+export type SdPublishConfig =
+  | SdNpmPublishConfig
+  | SdLocalDirectoryPublishConfig
+  | SdStoragePublishConfig;
+```
+
+| `type` 값 | 타입 | 설명 |
+|-----------|------|------|
+| `"npm"` | `SdNpmPublishConfig` | npm 레지스트리 배포 |
+| `"local-directory"` | `SdLocalDirectoryPublishConfig` | 로컬 디렉토리 복사 |
+| `"ftp"` \| `"ftps"` \| `"sftp"` | `SdStoragePublishConfig` | 스토리지 업로드 |
+
+## Related Types
+
+### `SdNpmPublishConfig`
+
+npm 레지스트리에 배포한다. 버전은 자동으로 증가된다.
+
+```typescript
+export interface SdNpmPublishConfig {
+  type: "npm";
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"npm"` | 배포 타입 식별자 |
+
+### `SdLocalDirectoryPublishConfig`
+
+로컬 디렉토리로 빌드 산출물을 복사한다.
+
+```typescript
+export interface SdLocalDirectoryPublishConfig {
+  type: "local-directory";
+  path: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"local-directory"` | 배포 타입 식별자 |
+| `path` | `string` | 배포 대상 경로. 환경 변수 치환 지원: `%VER%` (버전), `%PROJECT%` (프로젝트명) |
+
+### `SdStoragePublishConfig`
+
+FTP/FTPS/SFTP 서버에 빌드 산출물을 업로드한다.
+
+```typescript
+export interface SdStoragePublishConfig {
+  type: "ftp" | "ftps" | "sftp";
+  host: string;
+  port?: number;
+  path?: string;
+  user?: string;
+  password?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"ftp" \| "ftps" \| "sftp"` | 스토리지 프로토콜 |
+| `host` | `string` | 서버 호스트 |
+| `port` | `number?` | 서버 포트 |
+| `path` | `string?` | 원격 경로 |
+| `user` | `string?` | 사용자명 |
+| `password` | `string?` | 비밀번호 |

package/docs/config/sd-pwa-config.md

@@ -0,0 +1,41 @@
+# SdPwaConfig
+
+PWA(Progressive Web App) 설정. [`SdClientPackageConfig`](./sd-client-package-config.md)의 `pwa` 필드에 사용한다.
+
+```typescript
+export interface SdPwaConfig {
+  manifest?: SdPwaManifestConfig;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `manifest` | `SdPwaManifestConfig?` | PWA manifest 설정 |
+
+## Related Types
+
+### `SdPwaManifestConfig`
+
+PWA `manifest.json` 설정.
+
+```typescript
+export interface SdPwaManifestConfig {
+  name?: string;
+  short_name?: string;
+  display?: "standalone" | "fullscreen" | "minimal-ui" | "browser";
+  theme_color?: string;
+  background_color?: string;
+  icons?: Array<{ src: string; sizes: string; type?: string }>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string?` | 앱 이름 |
+| `short_name` | `string?` | 앱 짧은 이름 |
+| `display` | `"standalone" \| "fullscreen" \| "minimal-ui" \| "browser"?` | 디스플레이 모드 |
+| `theme_color` | `string?` | 테마 색상 (hex 코드) |
+| `background_color` | `string?` | 배경 색상 (hex 코드) |
+| `icons` | `Array<{ src: string; sizes: string; type?: string }>?` | 아이콘 목록 |

package/docs/config/sd-scripts-package-config.md

@@ -0,0 +1,19 @@
+# SdScriptsPackageConfig
+
+`scripts` 타겟 패키지 설정. 빌드 엔진이 없으며, `watch` 훅이 설정된 경우에만 watch/typecheck 대상에 포함된다.
+
+```typescript
+export interface SdScriptsPackageConfig {
+  target: "scripts";
+  publish?: SdPublishConfig;
+  watch?: SdWatchHookConfig;
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `"scripts"` | 빌드 타겟 식별자 |
+| `publish` | [`SdPublishConfig?`](./sd-publish-config.md) | 배포 설정 |
+| `watch` | [`SdWatchHookConfig?`](./sd-watch-hook-config.md) | watch 훅 설정. 설정 시 watch 모드에 패키지가 포함된다 |

package/docs/config/sd-server-package-config.md

@@ -0,0 +1,32 @@
+# SdServerPackageConfig
+
+`server` 타겟 패키지 설정. esbuild로 단일 번들 빌드되며 Fastify 서버로 실행된다.
+
+```typescript
+export interface SdServerPackageConfig {
+  target: "server";
+  env?: Record<string, string>;
+  publish?: SdPublishConfig;
+  configs?: Record<string, unknown>;
+  externals?: string[];
+  pm2?: {
+    name?: string;
+    ignoreWatchPaths?: string[];
+  };
+  packageManager?: "volta" | "mise";
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `"server"` | 빌드 타겟 식별자 |
+| `env` | `Record<string, string>?` | 빌드 시 치환할 환경 변수. `process.env.KEY`를 상수로 치환 |
+| `publish` | [`SdPublishConfig?`](./sd-publish-config.md) | 배포 설정 |
+| `configs` | `Record<string, unknown>?` | 런타임 설정. 빌드 시 `dist/.config.json`으로 기록 |
+| `externals` | `string[]?` | esbuild 번들에 포함하지 않을 외부 모듈. 자동 `binding.gyp` 감지 목록에 추가 |
+| `pm2` | `{ name?: string; ignoreWatchPaths?: string[] }?` | PM2 설정. 지정 시 `dist/pm2.config.cjs` 생성 |
+| `pm2.name` | `string?` | PM2 프로세스 이름. 미지정 시 `package.json`의 `name`에서 생성 |
+| `pm2.ignoreWatchPaths` | `string[]?` | PM2 watch에서 제외할 경로 |
+| `packageManager` | `"volta" \| "mise"?` | 사용할 패키지 매니저. `mise.toml` 또는 `volta` 설정 생성에 영향 |

package/docs/config/sd-watch-hook-config.md

@@ -0,0 +1,19 @@
+# SdWatchHookConfig
+
+watch 모드에서 파일 변경을 감지하고 명령어를 실행하는 훅 설정. [`SdBuildPackageConfig`](./sd-build-package-config.md) 및 [`SdScriptsPackageConfig`](./sd-scripts-package-config.md)의 `watch` 필드에 사용한다.
+
+```typescript
+export interface SdWatchHookConfig {
+  target: string[];
+  cmd: string;
+  args?: string[];
+}
+```
+
+## Members
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `string[]` | 감시할 glob 패턴 목록. 패키지 디렉토리 기준 상대 경로 |
+| `cmd` | `string` | 파일 변경 시 실행할 명령어 |
+| `args` | `string[]?` | 명령어 인수 |

package/docs/ts-compiler/sd-ts-compiler.md

@@ -0,0 +1,152 @@
+# SdTsCompiler
+
+TypeScript AOT 컴파일러. Angular 패키지(`angularCompilerOptions`가 `tsconfig.json`에 있는 경우)와 일반 TypeScript 패키지를 모두 지원한다. 증분 빌드, lint 통합, SCSS 컴파일을 관리한다.
+
+```typescript
+export class SdTsCompiler {
+  constructor(options: ISdTsCompilerOptions);
+
+  async compileAsync(
+    modifiedFiles?: ReadonlySet<string>,
+    emitOptions?: ISdTsCompilerEmitOptions,
+  ): Promise<ISdTsCompilerResult>;
+
+  compileSideEffectScss(): void;
+
+  findAffectedByScss(scssPath: string): string[];
+
+  get sideEffectScssRegistry(): Map<string, SideEffectScssEntry>;
+}
+```
+
+## Members
+
+| Member | Kind | Type | Description |
+|--------|------|------|-------------|
+| `compileAsync` | method | `(modifiedFiles?, emitOptions?) => Promise<ISdTsCompilerResult>` | TypeScript 컴파일 실행. `modifiedFiles` 지정 시 증분 빌드 수행 |
+| `compileSideEffectScss` | method | `() => void` | `sideEffectScssRegistry`의 모든 항목을 CSS로 컴파일 |
+| `findAffectedByScss` | method | `(scssPath: string) => string[]` | SCSS 경로에 의존하는 TypeScript 파일 목록 반환. watch 역방향 추적용 |
+| `sideEffectScssRegistry` | getter | `Map<string, SideEffectScssEntry>` | Angular 컴포넌트 `@Component.styles` 항목 저장소 |
+
+## Related Types
+
+### `ISdTsCompilerOptions`
+
+`SdTsCompiler` 생성 옵션.
+
+```typescript
+export interface ISdTsCompilerOptions {
+  pkgDir: string;
+  cwd: string;
+  output: { js: boolean; dts: boolean };
+  includeTests?: boolean;
+  env?: TypecheckEnv;
+  sourceFileCache?: AngularSourceFileCache;
+  transformStylesheet?: (
+    data: string,
+    containingFile: string,
+    stylesheetFile?: string,
+  ) => Promise<string | null>;
+  externalStylesheets?: Map<string, string>;
+  compilerOptionsTransformer?: (options: ts.CompilerOptions) => ts.CompilerOptions;
+  lint?: boolean;
+  globalScss?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `pkgDir` | `string` | 패키지 디렉토리 (절대 경로) |
+| `cwd` | `string` | workspace 루트. diagnostics 필터링 등에 사용 |
+| `output` | `{ js: boolean; dts: boolean }` | emit 제어 플래그. `js`: JavaScript emit, `dts`: 타입 선언 emit |
+| `includeTests` | `boolean?` | `tests/` 파일을 rootNames에 포함할지 여부. 기본값 `false` |
+| `env` | `TypecheckEnv?` | 타입체크 환경. 설정 시 `getCompilerOptionsForEnv()` 적용 |
+| `sourceFileCache` | `AngularSourceFileCache?` | Angular 증분 빌드용 SourceFile 캐시. 미제공 시 내부 생성 |
+| `transformStylesheet` | `(data, containingFile, stylesheetFile?) => Promise<string \| null>?` | 스타일시트 변환 콜백. Angular 패키지 전용 |
+| `externalStylesheets` | `Map<string, string>?` | 외부 스타일시트 맵. 클라이언트 빌드용, `resourceNameToFileName`에서 사용 |
+| `compilerOptionsTransformer` | `(options: ts.CompilerOptions) => ts.CompilerOptions?` | `compilerOptions` 후처리. 클라이언트의 `target`/`module` 강제 등에 사용 |
+| `lint` | `boolean?` | lint 실행 여부. `true`이면 `compileAsync` 결과에 lint 결과 포함 |
+| `globalScss` | `boolean?` | 글로벌 SCSS 컴파일 여부. `true`이면 `scss/styles.scss` → `dist/styles.css` 생성 |
+
+### `ISdTsCompilerResult`
+
+`compileAsync()` 반환 타입.
+
+```typescript
+export interface ISdTsCompilerResult {
+  program: ts.Program;
+  builderProgram: ts.EmitAndSemanticDiagnosticsBuilderProgram;
+  isForAngular: boolean;
+  affectedFiles: ReadonlySet<string> | undefined;
+  diagnostics: SerializedDiagnostic[];
+  errorCount: number;
+  warningCount: number;
+  errors?: string[];
+  ngtscProgram?: NgtscProgram;
+  emitResults?: EmitResult[];
+  lint?: LintWithProgramResult;
+  scssErrors: string[];
+  scssDependencies: ReadonlyMap<string, ReadonlySet<string>>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `program` | `ts.Program` | TypeScript Program 참조. lint, 외부 도구용 |
+| `builderProgram` | `ts.EmitAndSemanticDiagnosticsBuilderProgram` | Builder Program 참조. 증분 빌드 상태 보유 |
+| `isForAngular` | `boolean` | Angular 패키지 여부. `tsconfig.json`에 `angularCompilerOptions` 존재 시 `true` |
+| `affectedFiles` | `ReadonlySet<string> \| undefined` | 이 빌드에서 영향받은 파일 (posix 경로). `undefined` = 전역 변경 (전체 리빌드) |
+| `diagnostics` | `SerializedDiagnostic[]` | 직렬화된 진단 정보. Worker 경계 통과용 |
+| `errorCount` | `number` | Error 카테고리 진단 수 |
+| `warningCount` | `number` | Warning 카테고리 진단 수 |
+| `errors` | `string[]?` | Error 카테고리 진단을 `"파일:줄:열: TS코드: 메시지"` 형식으로 포맷한 배열. 에러 없으면 `undefined` |
+| `ngtscProgram` | `NgtscProgram?` | NgtscProgram 참조. Angular 패키지 전용, HMR용. Non-Angular이면 `undefined` |
+| `emitResults` | `EmitResult[]?` | Angular emit 결과. Non-Angular이면 `undefined` (writeFile 훅으로 디스크 직접 쓰기) |
+| `lint` | `LintWithProgramResult?` | lint 결과. `lint` 옵션 활성 시 반환 |
+| `scssErrors` | `string[]` | SCSS 컴파일 에러 목록 |
+| `scssDependencies` | `ReadonlyMap<string, ReadonlySet<string>>` | SCSS 의존성 맵. key: 소유자 파일, value: 의존 SCSS 경로 집합. watch 역방향 탐색용 |
+
+## Usage
+
+### 초기 컴파일
+
+```typescript
+import { SdTsCompiler } from "@simplysm/sd-cli";
+
+const compiler = new SdTsCompiler({
+  pkgDir: "/workspace/packages/my-lib",
+  cwd: "/workspace",
+  output: { js: true, dts: true },
+  lint: true,
+  globalScss: true,
+});
+
+const result = await compiler.compileAsync();
+
+if (result.errors) {
+  console.error("Compilation errors:", result.errors);
+  process.exit(1);
+}
+```
+
+### watch 모드에서 증분 컴파일
+
+```typescript
+import { SdTsCompiler } from "@simplysm/sd-cli";
+
+const compiler = new SdTsCompiler({
+  pkgDir: "/workspace/packages/my-lib",
+  cwd: "/workspace",
+  output: { js: true, dts: true },
+});
+
+// 초기 컴파일
+let result = await compiler.compileAsync();
+
+// 파일 변경 감지 시 증분 컴파일
+const changedFiles = new Set(["/workspace/packages/my-lib/src/foo.ts"]);
+result = await compiler.compileAsync(changedFiles);
+
+// SCSS 의존성이 변경된 TS 파일 찾기
+const affectedByScss = compiler.findAffectedByScss("/workspace/packages/my-lib/scss/variables.scss");
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-cli",
-  "version": "14.0.49",
+  "version": "14.0.51",
   "description": "Simplysm package - CLI tool",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -15,7 +15,8 @@
   "files": [
     "dist",
     "src",
-    "tests"
+    "tests",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
@@ -44,9 +45,9 @@
     "ws": "^8.20.0",
     "yaml": "^2.8.3",
     "yargs": "^18.0.0",
-    "@simplysm/core-node": "14.0.49",
-    "@simplysm/storage": "14.0.49",
-    "@simplysm/core-common": "14.0.49"
+    "@simplysm/core-common": "14.0.51",
+    "@simplysm/storage": "14.0.51",
+    "@simplysm/core-node": "14.0.51"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/engines/EsbuildClientEngine.ts

@@ -96,8 +96,7 @@ export class EsbuildClientEngine implements BuildEngine {
 
     // serverReady를 감지하여 포트 캡처 (EsbuildClientEngine 전용)
     this._worker!.on("serverReady", (data) => {
-      const event = data as { port: number };
-      this.port = event.port;
+      this.port = data.port;
     });
 
     // 공통 이벤트 처리 (buildStart/build/error)

package/src/esbuild/esbuild-angular-compiler-plugin.ts

@@ -96,7 +96,7 @@ export function createCompilerOptionsTransformer(
       _enableHmr: !!options.templateUpdates,
       supportTestBed: !!options.includeTestMetadata,
       supportJitMode: !!options.includeTestMetadata,
-    } as ts.CompilerOptions;
+    };
   };
 }
 

package/src/lint/lint-core.ts

@@ -52,7 +52,7 @@ function isGlobalIgnoresConfig(item: unknown): item is { ignores: string[] } {
   if (item == null || typeof item !== "object") return false;
   if (!("ignores" in item)) return false;
   if ("files" in item) return false; // files가 있으면 globalIgnores가 아님
-  const ignores = (item as { ignores: unknown }).ignores;
+  const ignores = item.ignores;
   if (!Array.isArray(ignores)) return false;
   return ignores.every((i) => typeof i === "string");
 }

package/src/orchestrators/DevOrchestrator.ts

@@ -8,7 +8,7 @@ import type {
 import { filterPackagesByTargets, classifyDevPackages } from "../utils/package-classify";
 import { printDiagnostics, printServers } from "../utils/output-utils";
 import { createBuildEngine } from "../engines/engine-factory";
-import type { BuildEngine, ClientPackageInfo, ServerPackageInfo } from "../engines/types";
+import type { BuildEngine } from "../engines/types";
 import { Capacitor } from "../capacitor/capacitor";
 import { BaseOrchestrator } from "./BaseOrchestrator";
 import { ServerRuntimeManager } from "./ServerRuntimeManager";
@@ -85,7 +85,7 @@ export class DevOrchestrator extends BaseOrchestrator implements OrchestratorLif
       const engineConfig = { ...config, env: { ...this._baseEnv, ...config.env } };
 
       const engine = createBuildEngine(
-        { name, dir, config: engineConfig } as ServerPackageInfo,
+        { name, dir, config: engineConfig },
         {
           cwd: this._cwd,
           replaceDeps: this._replaceDeps,
@@ -100,7 +100,7 @@ export class DevOrchestrator extends BaseOrchestrator implements OrchestratorLif
     for (const { name, dir, config } of this._clientPackages) {
       const engineConfig = { ...config, env: { ...this._baseEnv, ...config.env } };
       const engine = createBuildEngine(
-        { name, dir, config: engineConfig } as ClientPackageInfo,
+        { name, dir, config: engineConfig },
         {
           cwd: this._cwd,
           replaceDeps: this._replaceDeps,

package/src/orchestrators/ServerRuntimeManager.ts

@@ -2,7 +2,6 @@ import type { ConsolaInstance } from "consola";
 import { Worker, type WorkerProxy } from "@simplysm/core-node";
 import { err as errNs } from "@simplysm/core-common";
 import type * as ServerRuntimeWorkerModule from "../workers/server-runtime.worker";
-import type { ServerReadyEventData, ErrorEventData } from "../runtime/worker-events";
 import type { ResultCollector } from "../runtime/ResultCollector";
 
 /**
@@ -42,25 +41,23 @@ export class ServerRuntimeManager {
 
     // 런타임 이벤트 핸들러
     runtimeWorker.on("serverReady", (readyData) => {
-      const readyEvent = readyData as ServerReadyEventData;
       params.resultCollector.add({
         name: params.serverName,
         target: "server",
         type: "server",
         status: "running",
-        port: readyEvent.port,
+        port: readyData.port,
       });
       params.onServerReady();
     });
 
     runtimeWorker.on("error", (errorData) => {
-      const errorEvent = errorData as ErrorEventData;
       params.resultCollector.add({
         name: params.serverName,
         target: "server",
         type: "server",
         status: "error",
-        message: errorEvent.message,
+        message: errorData.message,
       });
     });