@simplysm/sd-claude 14.0.88 → 14.0.90

package/claude/references/sd-simplysm14/apis/sd-cli/SdTsCompiler.md

@@ -1,70 +1,117 @@
 # @simplysm/sd-cli — SdTsCompiler
 
-패키지 디렉토리의 `.ts` 를 TS 또는 Angular AOT 로 **증분** 컴파일하는 클래스. 한 번의 `compileAsync` 호출로 직렬화된 진단 + emit 결과 + lint + SCSS 결과를 묶어 반환. tsconfig 의 `angularCompilerOptions` 존재 여부로 Angular/일반 모드를 자동 판별. 빌드 엔진·`sdAngularPlugin` 내부에서 사용. 진단은 worker 경계를 통과하도록 `SerializedDiagnostic` 으로 직렬화됨.
+패키지 디렉토리의 `.ts` 를 TypeScript 또는 Angular AOT 로 **증분** 컴파일하는 클래스. 한 번의 `compileAsync` 호출로 직렬화된 진단 + emit 결과 + lint + SCSS 결과를 한 묶음(`ISdTsCompilerResult`)으로 반환한다. tsconfig 의 `angularCompilerOptions` 존재 여부로 Angular/일반 모드를 자동 판별. 빌드 엔진과 `sdAngularPlugin` 내부에서 사용. 진단은 worker 경계를 통과하도록 `SerializedDiagnostic` 으로 직렬화되며, 내부 크래시는 단계별로 잡아 진단으로 보고(부분 복구)한다.
 
-## SdTsCompiler
+## ISdTsCompilerOptions (생성자 인자)
+
+```typescript
+interface ISdTsCompilerOptions {
+  pkgDir: string;
+  cwd: string;
+  output: { js: boolean; dts: boolean };
+  includeTests?: boolean;
+  env?: TypecheckEnv;
+  // Angular 전용 (isForAngular 시 활성)
+  sourceFileCache?: AngularSourceFileCache;
+  transformStylesheet?: (data: string, containingFile: string, stylesheetFile?: string) => Promise<string | null>;
+  externalStylesheets?: Map<string, string>;
+  compilerOptionsTransformer?: (options: ts.CompilerOptions) => ts.CompilerOptions;
+  // SCSS/lint 통합
+  lint?: boolean;
+  globalScss?: boolean;
+}
+```
+
+- pkgDir: string — 컴파일 대상 패키지 디렉토리. `<pkgDir>/tsconfig.json` 을 파싱하고 `<pkgDir>/dist` 로 emit, `<pkgDir>/.cache` 에 tsbuildinfo 를 둔다.
+- cwd: string — 워크스페이스 루트. 진단 필터링(`isWorkspaceDiagnostic`)·경로 상대화·에러 포맷 기준점.
+- output.js: boolean — JS emit 여부. true 면 `.js` 산출(non-Angular 은 import 에 `.js` 확장자 부착 + 경로 재작성, Angular 은 `emitResults` 로 반환).
+- output.dts: boolean — `.d.ts` emit 여부. `js`/`dts` 조합에 따라 emit-only·declaration-only·noEmit(둘 다 false = 타입체크만) 으로 분기.
+- includeTests?: boolean — `tests/` 파일을 rootNames 에 포함할지. 기본 false. 테스트까지 컴파일해야 하면 true(예: `sdAngularPlugin`).
+- env?: TypecheckEnv — 타입체크 환경. 지정 시 `getCompilerOptionsForEnv()` 로 환경별 compilerOptions 를 적용하고 tsbuildinfo 파일명에 접미사를 붙임. 환경 분리 타입체크에 쓴다.
+- sourceFileCache?: AngularSourceFileCache — Angular 증분용 SourceFile 캐시. 미제공 시 내부 생성. 여러 `compileAsync` 라운드 간 캐시를 공유하려면 외부에서 주입.
+- transformStylesheet?: (data, containingFile, stylesheetFile?) => Promise<string|null> — 컴포넌트 스타일 변환 콜백(Angular only). `null` 반환 시 변환 안 함. 미제공이고 Angular 면 라이브러리용 SCSS 변환 콜백을 자동 생성. 클라이언트 빌드처럼 커스텀 스타일 파이프라인이 필요할 때 직접 제공.
+- externalStylesheets?: Map<string, string> — 외부 스타일시트 맵(클라이언트 빌드용). 지정 시 비-템플릿 스타일 리소스를 해시 기반 `.css` 외부 파일명으로 매핑(`resourceNameToFileName`). 스타일을 별도 청크로 뽑을 때.
+- compilerOptionsTransformer?: (options) => ts.CompilerOptions — 최종 compilerOptions 후처리 훅. 클라이언트의 `target`/`module`/`rootDir` 강제 등에 쓴다.
+- lint?: boolean — true 면 `compileAsync` 가 program 기반 lint 를 함께 돌려 결과를 `result.lint` 에 담는다(affected 파일만 대상). 컴파일과 동시에 lint 하고 싶을 때.
+- globalScss?: boolean — true 면 `scss/styles.scss` → `dist/styles.css` 글로벌 SCSS 를 컴파일하고 에러를 `result.scssErrors` 에 더한다.
+
+## ISdTsCompilerEmitOptions (compileAsync 2번째 인자)
+
+```typescript
+interface ISdTsCompilerEmitOptions {
+  sourceFilter?: (fileName: string) => boolean;
+  additionalTransformers?: {
+    before?: ts.TransformerFactory<ts.SourceFile>[];
+    after?: ts.TransformerFactory<ts.SourceFile>[];
+  };
+}
+```
+
+- sourceFilter?: (fileName) => boolean — emit 결과 필터(Angular only). true 인 소스만 `emitResults` 에 남긴다. 특정 파일의 emit 만 필요할 때(예: HMR 단일 파일).
+- additionalTransformers?.before / .after — Angular 기본 transformers 앞/뒤에 끼울 추가 TS transformer 배열(Angular only). 커스텀 코드 변환을 주입할 때.
+
+## SdTsCompiler — 메서드
 
 ```typescript
 class SdTsCompiler {
   constructor(options: ISdTsCompilerOptions);
   compileAsync(modifiedFiles?: ReadonlySet<string>, emitOptions?: ISdTsCompilerEmitOptions): Promise<ISdTsCompilerResult>;
+  get sideEffectScssRegistry(): Map<string, SideEffectScssEntry>;
   compileSideEffectScss(): void;
   findAffectedByScss(scssPath: string): string[];
-  get sideEffectScssRegistry(): Map<string, SideEffectScssEntry>;
 }
 ```
 
-- compileAsync(modifiedFiles?, emitOptions?) — 1회 증분 컴파일. `modifiedFiles` = 직전 변경 파일 절대경로 집합(전달 시 sourceFileCache·packageJsonCache 무효화, 미전달 시 전체). `emitOptions` = emit 세부 제어. 위험 구간을 단계별 try/catch 로 감싸 부분 복구하며, 잡힌 크래시는 결과의 `diagnostics`/`errors` 에 합산됨(silent skip 아님).
-- compileSideEffectScss() — `sideEffectScssRegistry` 에 등록된 side-effect SCSS 항목을 모두 CSS 로 컴파일. emit 코드가 항목을 레지스트리에 채운 뒤 호출.
-- findAffectedByScss(scssPath) — 주어진 SCSS 경로에 의존하는 소스 파일 목록 반환(역방향 탐색). watch 에서 SCSS 변경 시 재컴파일 대상을 찾을 때.
-- sideEffectScssRegistry — side-effect SCSS 항목 맵(소스경로 → 엔트리). emit 코드가 항목을 등록하는 통로.
+- compileAsync(modifiedFiles?, emitOptions?) — 1회 증분 컴파일 실행. `modifiedFiles` = 직전 변경된 파일 절대경로 집합(증분 무효화용, 미지정·빈 집합이면 캐시 그대로 사용; node_modules 포함 변경 시 packageJsonCache 클리어). `emitOptions` 는 위 emit 필터/transformer. 같은 인스턴스로 반복 호출해 증분 빌드를 이어간다.
+- sideEffectScssRegistry (getter) — side-effect SCSS 등록부(`Map<소스, SideEffectScssEntry>`) 참조. emit 코드가 항목을 등록하는 통로.
+- compileSideEffectScss() — 위 레지스트리의 모든 항목을 CSS 로 컴파일하고 에러/의존성을 내부 상태에 반영.
+- findAffectedByScss(scssPath) — 주어진 SCSS 경로에 의존하는 소유자 파일 경로 배열을 반환(역방향 탐색). watch 에서 SCSS 변경 시 재컴파일 대상 산출에 쓴다.
 
-`compileAsync` 동작 요약: tsconfig 파싱 → `includeTests` 에 따라 rootNames 결정 → `output` 플래그로 compilerOptions 구성(`compilerOptionsTransformer` 마지막 적용) → Angular 면 `NgtscProgram.analyzeAsync`, 아니면 `EmitAndSemanticDiagnosticsBuilderProgram` → affected 파일 추적 → emit → 진단 수집·직렬화·필터(workspace 내부만) → `globalScss`/`lint` 병렬 실행. 비-Angular emit 은 writeFile 훅으로 디스크에 직접 쓰고(`emitResults` undefined), Angular emit 은 `emitResults` 로 메모리 반환.
+사용 예:
 
 ```typescript
 import { SdTsCompiler } from "@simplysm/sd-cli";
-const compiler = new SdTsCompiler({ pkgDir, cwd, output: { js: true, dts: true }, lint: true });
+
+const compiler = new SdTsCompiler({
+  pkgDir: "/repo/packages/core-common",
+  cwd: "/repo",
+  output: { js: true, dts: true },
+});
 const result = await compiler.compileAsync();
 if (result.errorCount > 0) console.error(result.errors);
+// watch 라운드: 변경 파일만 넘겨 증분 컴파일
+const next = await compiler.compileAsync(new Set(["/repo/packages/core-common/src/foo.ts"]));
 ```
 
-## ISdTsCompilerOptions
-
-생성자 옵션.
-
-- pkgDir: string — 컴파일 대상 패키지 디렉토리 절대경로. rootNames·outDir·SCSS loadPath 기준.
-- cwd: string — workspace 루트. diagnostics 필터링(워크스페이스 내부 진단만 남김)·상대경로 로깅 기준.
-- output: { js: boolean; dts: boolean } — 출력 제어. `js` = `.js` emit 여부, `dts` = `.d.ts` emit 여부. 둘 다 false 면 noEmit(타입체크만). 조합에 따라 declaration/sourceMap/tsBuildInfoFile 이름이 달라짐.
-- includeTests?: boolean — `tests/` 파일을 rootNames 에 포함할지. 기본 false. 테스트 AOT 컴파일(Vitest)에서 true.
-- env?: "node" | "browser" — 타입체크 환경. 설정 시 환경별 compilerOptions 조정(`getCompilerOptionsForEnv`) 적용. 동일 패키지를 환경별로 분리 검증할 때.
-- sourceFileCache?: AngularSourceFileCache — Angular 증분 빌드용 SourceFile 캐시. 미제공 시 내부 생성. 인스턴스 간 캐시 공유로 증분 속도 확보.
-- transformStylesheet?: (data, containingFile, stylesheetFile?) => Promise<string | null> — 스타일시트 변환 콜백(Angular 전용). 인라인/외부 스타일을 가공해 반환, `null` 이면 미변환. 미제공 + Angular 면 라이브러리용 SCSS 변환 콜백이 자동 생성됨.
-- externalStylesheets?: Map<string, string> — 외부 스타일시트 맵(클라이언트 빌드용). `resourceNameToFileName` 에서 비-템플릿 리소스를 해시 기반 `.css` 외부 ID 로 치환할 때 채워짐.
-- compilerOptionsTransformer?: (options) => ts.CompilerOptions — compilerOptions 최종 후처리. 내부 구성 이후 마지막에 적용되어 target/module/rootDir 등을 강제 가능. 클라이언트·Vitest 빌드에서 사용.
-- lint?: boolean — true 면 `compileAsync` 가 lint 를 함께 실행하고 결과를 `result.lint` 에 포함. lint runner 는 lazy init 후 인스턴스 재사용.
-- globalScss?: boolean — true 면 `scss/styles.scss` → `dist/styles.css` 글로벌 SCSS 컴파일 수행. 글로벌 스타일 산출이 필요한 패키지에서.
-
-## ISdTsCompilerEmitOptions
+## ISdTsCompilerResult (compileAsync 반환)
 
-`compileAsync` 의 두 번째 인자(emit 세부 제어, Angular 전용).
-
-- sourceFilter?: (fileName: string) => boolean — emit 대상 소스 필터. 지정 시 통과한 소스의 EmitResult 만 결과에 포함. 일부 파일만 재emit 할 때.
-- additionalTransformers?: { before?; after? } — Angular transformers 외 추가 TS transformer factory. `before`/`after` 각각 `ts.TransformerFactory<ts.SourceFile>[]`. 컴파일 파이프라인에 사용자 변환을 끼울 때.
-
-## ISdTsCompilerResult
-
-`compileAsync` 반환값.
+```typescript
+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[]; // EmitResult: { filename; contents; sourceFileName }
+  lint?: LintWithProgramResult;
+  scssErrors: string[];
+  scssDependencies: ReadonlyMap<string, ReadonlySet<string>>;
+}
+```
 
-- program: ts.Program — TypeScript Program 참조. lint·외부 도구용.
-- builderProgram: ts.EmitAndSemanticDiagnosticsBuilderProgram — Builder Program 참조. 다음 증분 호출에 재사용됨.
-- isForAngular: boolean — Angular 패키지 여부(tsconfig `angularCompilerOptions` 존재로 판별).
-- 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 용). 비-Angular 이면 undefined.
-- emitResults?: EmitResult[] — Angular emit 결과 배열(`{ filename, contents, sourceFileName }`). 비-Angular 면 undefined(writeFile 훅이 디스크에 직접 씀).
-- lint?: LintWithProgramResult — lint 결과. `lint` 옵션 활성 시에만 존재.
+- program: ts.Program — TS Program 참조. lint·외부 도구에 넘길 때.
+- builderProgram — 증분 BuilderProgram 참조.
+- isForAngular: boolean — Angular 모드로 컴파일됐는지(tsconfig 의 `angularCompilerOptions` 유무로 결정). 후속 처리 분기에 쓴다.
+- affectedFiles: ReadonlySet<string> | undefined — 이번 빌드에서 영향받은 파일(posix 경로). `undefined` = 전역 변경(전체 리빌드). 부분 재처리 범위 판단에 쓴다.
+- diagnostics: SerializedDiagnostic[] — 직렬화된 진단 전체(worker 경계 통과용). 내부 크래시 진단도 합산됨.
+- errorCount / warningCount: number — Error / Warning 카테고리 진단 수. 크래시는 errorCount 에 가산.
+- errors?: string[] — Error 진단을 `"파일:줄:열: TS코드: 메시지"` 형식으로 포맷한 배열(없으면 undefined). 로그 출력에 바로 쓴다.
+- ngtscProgram?: NgtscProgram — NgtscProgram 참조(Angular only, HMR 용). non-Angular 이면 undefined.
+- emitResults?: EmitResult[] — Angular emit 결과 배열. 각 항목 `{ filename; contents; sourceFileName }`(sourceFileName = 원본 소스 경로). non-Angular 은 writeFile 훅으로 디스크에 직접 쓰므로 undefined. 메모리상 컴파일 결과가 필요한 플러그인이 소비.
+- lint?: LintWithProgramResult — lint 결과(`lint: true` 일 때만).
 - scssErrors: string[] — SCSS 컴파일 에러 목록.
 - scssDependencies: ReadonlyMap<string, ReadonlySet<string>> — SCSS 의존성 맵(소유자 파일 → 의존 SCSS 경로 집합). watch 역방향 탐색용.

package/claude/references/sd-simplysm14/apis/sd-cli/sd-config-types.md

@@ -1,173 +1,291 @@
 # @simplysm/sd-cli — sd.config.ts 설정 타입
 
-프로젝트 루트 `sd.config.ts` 작성에 쓰는 타입 묶음. `sd.config.ts` 는 `SdConfigFn`(=`(params: SdConfigParams) => SdConfig | Promise<SdConfig>`)을 default export 해야 함. 권위 소스는 `packages/sd-cli/src/sd-config.types.ts`.
+프로젝트 루트 `sd.config.ts` 작성·수정 시 함께 읽히는 타입 묶음. `sd.config.ts` 는 `SdConfigFn` 을 default export 해야 한다. 권위 소스는 `packages/sd-cli/src/sd-config.types.ts`. 모든 타입은 `import type { ... } from "@simplysm/sd-cli"` 로 가져온다.
 
-## SdConfigFn / SdConfigParams
-
-`sd.config.ts` 의 default export 시그니처. `SdConfig` 또는 그 Promise 를 반환.
+## SdConfigFn / SdConfigParams / SdConfig
 
 ```typescript
 type SdConfigFn = (params: SdConfigParams) => SdConfig | Promise<SdConfig>;
+
+interface SdConfigParams {
+  cwd: string;
+  dev: boolean;
+  opt: string[];
+}
+
+interface SdConfig {
+  packages: Record<string, SdPackageConfig | undefined>;
+  replaceDeps?: Record<string, string>;
+  postPublish?: SdPostPublishScriptConfig[];
+}
 ```
 
-`SdConfigParams` (함수에 주입되는 인자):
+`SdConfigParams` (sd-cli 가 설정 함수에 주입):
+
+- cwd: string — 현재 작업 디렉토리(워크스페이스 루트). 설정에서 경로를 절대화할 때 쓴다.
+- dev: boolean — 개발 모드 플래그. true 면 dev 실행(watch/dev). env·publish 를 모드별로 분기할 때 쓴다.
+- opt: string[] — CLI 의 `-o` 플래그로 넘어온 추가 옵션 배열. 임의 빌드 변형(예: 특정 환경 타겟)을 분기할 때 쓴다.
 
-- cwd: string — 현재 작업 디렉토리(워크스페이스 루트). 경로 계산 기준.
-- dev: boolean — 개발 모드 플래그. true 면 dev 실행, false 면 빌드/배포. env 분기에 사용.
-- opt: string[] — CLI 의 `-o` 플래그로 전달된 추가 옵션 문자열 배열. 조건부 설정 분기용.
+`SdConfig`:
+
+- packages: Record<string, SdPackageConfig | undefined> — 키는 `packages/` 하위 디렉토리명(예: `"core-common"`), 값은 해당 패키지 빌드 설정. `undefined` 면 그 패키지를 빌드 대상에서 제외. 워크스페이스의 어떤 패키지를 어떤 타겟으로 빌드할지 한 곳에 모은다.
+- replaceDeps?: Record<string, string> — 의존성 교체(심링크). 키는 node_modules 에서 찾을 패키지 glob(예: `"@simplysm/*"`), 값은 로컬 소스 디렉토리 경로로 키의 `*` 캡처가 값의 `*` 에 치환됨(예: `"../simplysm/packages/*"`). 배포된 패키지 대신 로컬 소스를 곧바로 쓰고 싶을 때.
+- postPublish?: SdPostPublishScriptConfig[] — 배포 완료 후 순차 실행할 스크립트 목록. 배포 후 알림·태깅 등 후처리에 쓴다.
+
+사용 예:
 
 ```typescript
 import type { SdConfigFn } from "@simplysm/sd-cli";
+
 const config: SdConfigFn = ({ dev }) => ({
   packages: {
     "core-common": { target: "neutral" },
-    "core-node": { target: "node" },
+    "core-node": { target: "node", publish: { type: "npm" } },
+    "demo-client": dev ? { target: "client", server: "demo-server" } : undefined,
   },
 });
 export default config;
 ```
 
-## SdConfig
+## SdPackageConfig (빌드 타겟 분기 유니온)
 
-`sd.config.ts` 최상위 설정 객체.
+```typescript
+type SdPackageConfig =
+  | SdBuildPackageConfig    // target: "node" | "browser" | "neutral"
+  | SdClientPackageConfig   // target: "client"
+  | SdServerPackageConfig   // target: "server"
+  | SdScriptsPackageConfig; // target: "scripts"
+```
 
-- packages: Record<string, SdPackageConfig | undefined> — 패키지별 설정. key 는 `packages/` 하위 디렉토리명(예: `"core-common"`). 값을 `undefined` 로 두면 해당 패키지 비활성. 빌드 대상·타겟을 패키지마다 지정.
-- replaceDeps?: Record<string, string> — 의존성 교체. key 는 node_modules 에서 찾을 패키지 glob(예: `"@simplysm/*"`), value 는 소스 디렉토리 경로이며 key 의 `*` 캡처가 value 의 `*` 에 치환됨. node_modules 패키지를 로컬 소스로 심링크해 빌드 없이 소스 import 할 때.
-- postPublish?: SdPostPublishScriptConfig[] — 배포 완료 후 순차 실행할 스크립트 목록. 배포 후 후처리(태깅·알림 등)에 사용.
+판별자는 `target`. enum literal 별 의미:
 
-## SdPackageConfig (타겟별 패키지 설정)
+- "node" / "browser" / "neutral" (→ `SdBuildPackageConfig`) — esbuild 라이브러리 패키지. "node" = Node.js 전용, "browser" = 브라우저 전용, "neutral" = 공용. npm 배포 라이브러리에 쓴다.
+- "client" (→ `SdClientPackageConfig`) — Frontend 앱(Angular + Capacitor/Electron/PWA 옵션). esbuild + define 으로 env 주입.
+- "server" (→ `SdServerPackageConfig`) — Fastify 서버 앱. esbuild banner 로 env 주입, PM2 옵션.
+- "scripts" (→ `SdScriptsPackageConfig`) — 유틸 패키지. watch 훅이 없으면 watch/typecheck 대상에서 제외됨.
 
-`SdBuildPackageConfig | SdClientPackageConfig | SdServerPackageConfig | SdScriptsPackageConfig` 의 union. `target` 값으로 분기된다.
+### SdBuildPackageConfig (node/browser/neutral)
 
-### SdBuildPackageConfig (라이브러리: node/browser/neutral)
+```typescript
+interface SdBuildPackageConfig {
+  target: BuildTarget; // "node" | "browser" | "neutral"
+  publish?: SdPublishConfig;
+  copySrc?: string[];
+  watch?: SdWatchHookConfig;
+}
+```
 
-- target: "node" | "browser" | "neutral" — esbuild 라이브러리 빌드 타겟. "node" = Node.js 전용, "browser" = 브라우저 전용, "neutral" = 공용. 패키지 실행 환경에 맞춰 선택.
-- publish?: SdPublishConfig — 배포 설정. 미지정 시 배포 제외.
-- copySrc?: string[] — `src/` 에서 `dist/` 로 그대로 복사할 파일의 glob 패턴(src/ 기준 상대 경로). 비-TS 리소스 동봉용.
-- watch?: SdWatchHookConfig — watch 훅. 지정 시 watch 모드에서 빌드 엔진과 함께 훅 명령 실행.
+- target: "node"|"browser"|"neutral" — 빌드 런타임 타겟(위 풀이 참조). 라이브러리가 어느 환경에서 돌지에 맞춰 고른다.
+- publish?: SdPublishConfig — 배포 대상 설정. 미지정 시 배포 안 함. npm 배포 라이브러리면 `{ type: "npm" }`.
+- copySrc?: string[] — `src/` 에서 `dist/` 로 그대로 복사할 파일 glob(src 기준 상대). 컴파일 대상 아닌 정적 리소스를 산출물에 포함할 때.
+- watch?: SdWatchHookConfig — watch 모드에서 빌드 엔진과 함께 실행할 훅. 빌드 외 부수 작업(코드 생성 등)을 watch 에 끼울 때.
 
-### SdClientPackageConfig (Frontend 앱: target "client")
+### SdClientPackageConfig (client)
 
-- target: "client" — esbuild 기반 Angular 클라이언트 앱 빌드.
-- server: string | number — 연결할 서버. string = 서버 패키지명(예: `"demo-server"`), number = 포트 직접 지정(하위 호환). 개발 프록시/API 대상 결정.
-- env?: Record<string, string> — 빌드 시 `process.env` 를 객체로 치환할 환경 변수. 클라이언트 코드의 env 주입.
-- publish?: SdPublishConfig — 배포 설정.
-- capacitor?: SdCapacitorConfig — Capacitor(모바일) 패키징 설정. 지정 시 앱 패키징.
-- electron?: SdElectronConfig — Electron(데스크톱) 패키징 설정. 지정 시 데스크톱 패키징.
-- configs?: Record<string, unknown> — 런타임 설정. 빌드 시 `dist/.config.json` 으로 기록되어 런타임에 로드됨.
-- exclude?: string[] — Capacitor/Electron package.json 에 추가할 패키지(또는 제외 목록). 패키징 의존성 조정.
-- browserSupport?: SdBrowserSupportConfig — 브라우저 지원(browserslist·PostCSS·legacyModule) 설정.
-- pwa?: false | SdPwaConfig — PWA 설정. `false` 면 비활성, 미지정 시 기본값으로 활성화. PWA manifest 제어.
+```typescript
+interface SdClientPackageConfig {
+  target: "client";
+  server: string | number;
+  env?: Record<string, string>;
+  publish?: SdPublishConfig;
+  capacitor?: SdCapacitorConfig;
+  electron?: SdElectronConfig;
+  configs?: Record<string, unknown>;
+  exclude?: string[];
+  browserSupport?: SdBrowserSupportConfig;
+  pwa?: false | SdPwaConfig;
+}
+```
 
-### SdServerPackageConfig (Fastify 서버: target "server")
+- server: string | number — 연결할 dev 서버. string = 서버 패키지명(예: `"demo-server"`), number = 포트 직접 지정(하위 호환). 보통 같은 워크스페이스의 서버 패키지명을 준다.
+- env?: Record<string, string> — 빌드 시 `process.env` 를 객체로 치환할 환경 변수. 프론트 코드에 빌드 타임 상수를 주입할 때.
+- publish?: SdPublishConfig — 산출물 배포 설정.
+- capacitor?: SdCapacitorConfig — Capacitor 모바일 앱 패키징 설정. 지정 시 Android 등으로 패키징.
+- electron?: SdElectronConfig — Electron 데스크톱 앱 패키징 설정.
+- configs?: Record<string, unknown> — 런타임 설정. 빌드 시 `dist/.config.json` 으로 기록되어 앱이 런타임에 읽음. 배포 환경별 가변 값.
+- exclude?: string[] — Capacitor/Electron `package.json` 에 추가(번들 제외)할 패키지 목록.
+- browserSupport?: SdBrowserSupportConfig — 브라우저 호환(browserslist/PostCSS/legacyModule) 설정.
+- pwa?: false | SdPwaConfig — PWA 설정. `false` 면 비활성화, 미지정 시 기본값으로 활성화, 객체면 manifest 커스텀. PWA 가 필요 없으면 `false`.
 
-- target: "server" — esbuild 기반 Fastify 서버 앱 빌드.
-- env?: Record<string, string> — 빌드 시 `process.env.KEY` 를 상수로 치환할 환경 변수.
-- publish?: SdPublishConfig — 배포 설정.
-- configs?: Record<string, unknown> — 런타임 설정. 빌드 시 `dist/.config.json` 으로 기록.
-- externals?: string[] — esbuild 번들에 포함하지 않을 외부 모듈. 네이티브 모듈(binding.gyp 자동 감지분에 추가)을 번들 제외할 때.
-- pm2?: { name?: string; ignoreWatchPaths?: string[] } — PM2 설정. 지정 시 `dist/pm2.config.cjs` 생성. `name` = 프로세스 이름(미지정 시 package.json name 기반), `ignoreWatchPaths` = PM2 watch 제외 경로.
-- packageManager?: "volta" | "mise" — 사용할 패키지 매니저. 생성되는 mise.toml/volta 설정에 영향. 배포 환경의 런타임 관리자 선택.
+### SdServerPackageConfig (server)
 
-### SdScriptsPackageConfig (유틸 스크립트: target "scripts")
+```typescript
+interface SdServerPackageConfig {
+  target: "server";
+  env?: Record<string, string>;
+  publish?: SdPublishConfig;
+  configs?: Record<string, unknown>;
+  externals?: string[];
+  pm2?: { name?: string; ignoreWatchPaths?: string[] };
+  packageManager?: "volta" | "mise";
+}
+```
+
+- env?: Record<string, string> — 빌드 시 `process.env.KEY` 를 상수로 치환(esbuild banner). 서버 빌드 타임 상수 주입.
+- configs?: Record<string, unknown> — 런타임 설정. `dist/.config.json` 으로 기록.
+- externals?: string[] — esbuild 번들에 포함하지 않을 외부 모듈. 자동 `binding.gyp` 감지 항목에 더해짐. 네이티브 모듈을 번들에서 뺄 때.
+- pm2?.name?: string — PM2 프로세스 이름. 미지정 시 `package.json` name 에서 생성. 지정 시 `dist/pm2.config.cjs` 생성.
+- pm2?.ignoreWatchPaths?: string[] — PM2 watch 에서 제외할 경로.
+- packageManager?: "volta" | "mise" — 산출물에 생성할 패키지 매니저 설정 종류. "volta" = volta 설정, "mise" = `mise.toml` 생성. 배포 서버의 매니저에 맞춘다.
 
-- target: "scripts" — 빌드 산출 없는 스크립트 전용 패키지. watch 훅 미설정 시 watch/typecheck 에서 제외됨.
-- publish?: SdPublishConfig — 배포 설정.
-- watch?: SdWatchHookConfig — watch 훅. 지정 시 watch 모드에 패키지 포함.
+### SdScriptsPackageConfig (scripts)
+
+```typescript
+interface SdScriptsPackageConfig {
+  target: "scripts";
+  publish?: SdPublishConfig;
+  watch?: SdWatchHookConfig;
+}
+```
+
+- watch?: SdWatchHookConfig — watch 훅. 지정해야만 이 패키지가 watch 모드에 포함됨(미지정 시 watch/typecheck 제외). 파일 변경 시 임의 명령 실행에 쓴다.
 
 ## SdWatchHookConfig
 
-watch 모드에서 파일 변경 시 임의 명령을 실행하는 훅. `SdBuildPackageConfig.watch` / `SdScriptsPackageConfig.watch` 에 사용.
+```typescript
+interface SdWatchHookConfig {
+  target: string[];
+  cmd: string;
+  args?: string[];
+}
+```
 
-- target: string[] — 감시할 glob 패턴(패키지 디렉토리 기준 상대 경로). 어떤 파일 변경을 트리거로 볼지.
-- cmd: string — 변경 시 실행할 명령어.
+- target: string[] — 감시할 glob 패턴(패키지 디렉토리 기준 상대). 어떤 파일 변경에 반응할지.
+- cmd: string — 변경 감지 시 실행할 명령어.
 - args?: string[] — 명령어 인수.
 
-## 배포 설정 (SdPublishConfig 계열)
+## 배포 설정 (SdPublishConfig 유니온 + SdPostPublishScriptConfig)
 
-`SdNpmPublishConfig | SdLocalDirectoryPublishConfig | SdStoragePublishConfig` union. `type` 으로 분기.
+```typescript
+type SdPublishConfig = SdNpmPublishConfig | SdLocalDirectoryPublishConfig | SdStoragePublishConfig;
+```
 
-- SdNpmPublishConfig — `{ type: "npm" }`. npm 레지스트리 배포.
-- SdLocalDirectoryPublishConfig — `{ type: "local-directory"; path: string }`. 로컬 디렉토리 복사 배포. `path` 는 환경 변수 치환(`%VER%`, `%PROJECT%`) 지원.
-- SdStoragePublishConfig — FTP/FTPS/SFTP 업로드 배포.
-  - type: "ftp" | "ftps" | "sftp" — 전송 프로토콜. 보안 필요 시 ftps/sftp.
-  - host: string — 서버 호스트.
-  - port?: number — 포트.
-  - path?: string — 업로드 대상 경로.
-  - user?: string — 접속 계정.
-  - password?: string — 접속 비밀번호.
+판별자는 `type`:
 
-`SdPostPublishScriptConfig` (배포 후 스크립트):
+- `SdNpmPublishConfig` — `{ type: "npm" }`. npm 레지스트리 배포. 공개 라이브러리에 쓴다.
+- `SdLocalDirectoryPublishConfig` — `{ type: "local-directory"; path: string }`. 로컬 디렉토리로 복사. `path` 는 `%VER%`/`%PROJECT%` 치환 지원. 사내 공유 폴더 배포에.
+- `SdStoragePublishConfig` — `{ type: "ftp"|"ftps"|"sftp"; host; port?; path?; user?; password? }`. type 별 프로토콜 차이(ftp = 평문, ftps = TLS, sftp = SSH). 원격 서버 업로드 배포에. host 만 필수, 나머지는 선택.
 
-- type: "script" — 스크립트 실행 항목.
-- cmd: string — 실행 명령어.
-- args: string[] — 인수. 환경 변수 치환(`%VER%`, `%PROJECT%`) 지원.
+```typescript
+interface SdPostPublishScriptConfig {
+  type: "script";
+  cmd: string;
+  args: string[]; // %VER%, %PROJECT% 치환 지원
+}
+```
+
+- cmd: string — 배포 후 실행할 명령어.
+- args: string[] — 인수. `%VER%`(버전), `%PROJECT%`(프로젝트명) 치환됨.
 
-## Capacitor 설정 (SdClientPackageConfig.capacitor)
+## Capacitor 설정 (client 의 capacitor)
 
-`SdCapacitorConfig`:
+```typescript
+interface SdCapacitorConfig {
+  appId: string;
+  appName: string;
+  plugins?: Record<string, Record<string, unknown> | true>;
+  icon?: string;
+  debug?: boolean;
+  platform?: { android?: SdCapacitorAndroidConfig };
+}
+```
 
-- appId: string — 앱 ID(예: `"com.example.app"`).
-- appName: string — 앱 이름.
-- plugins?: Record<string, Record<string, unknown> | true> — Capacitor 플러그인 설정. key = 패키지명, value = `true`(옵션 없음) 또는 플러그인 옵션 객체.
-- icon?: string — 앱 아이콘 경로(패키지 디렉토리 기준 상대).
+- appId: string — 앱 ID(역도메인, 예: `"com.example.app"`). 스토어 식별자.
+- appName: string — 앱 표시 이름.
+- plugins?: Record<string, Record<string, unknown> | true> — Capacitor 플러그인. 키 = 패키지명, 값 = `true`(옵션 없이 활성) 또는 옵션 객체. 옵션이 필요 없으면 `true`.
+- icon?: string — 앱 아이콘 경로(패키지 기준 상대).
 - debug?: boolean — 디버그 빌드 플래그.
-- platform?: { android?: SdCapacitorAndroidConfig } — 플랫폼별 설정(현재 android).
+- platform?.android?: SdCapacitorAndroidConfig — Android 플랫폼별 설정.
 
-`SdCapacitorAndroidConfig`:
+```typescript
+interface SdCapacitorAndroidConfig {
+  config?: Record<string, string>;
+  bundle?: boolean;
+  intentFilters?: SdCapacitorIntentFilter[];
+  sign?: SdCapacitorSignConfig;
+  sdkVersion?: number;
+  permissions?: SdCapacitorPermission[];
+}
+```
 
-- config?: Record<string, string> — AndroidManifest.xml `application` 태그 속성(예: `{ requestLegacyExternalStorage: "true" }`).
-- bundle?: boolean — true 면 AAB 번들, false 면 APK 빌드.
-- intentFilters?: SdCapacitorIntentFilter[] — Intent Filter 목록.
-- sign?: SdCapacitorSignConfig — APK/AAB 서명 설정.
+- config?: Record<string, string> — `AndroidManifest.xml` 의 `<application>` 태그 속성(예: `{ requestLegacyExternalStorage: "true" }`).
+- bundle?: boolean — true = AAB 번들, false = APK. 스토어 배포면 true.
+- intentFilters?: SdCapacitorIntentFilter[] — 딥링크 등 Intent Filter 목록.
+- sign?: SdCapacitorSignConfig — APK/AAB 서명 설정. 릴리스 빌드에 필요.
 - sdkVersion?: number — Android SDK 버전(minSdk·targetSdk 공통).
 - permissions?: SdCapacitorPermission[] — 추가 권한 목록.
 
-`SdCapacitorIntentFilter`:
-
-- action?: string — intent 액션(예: `"android.intent.action.VIEW"`).
-- category?: string — intent 카테고리(예: `"android.intent.category.DEFAULT"`).
-
-`SdCapacitorSignConfig`:
-
-- keystore: string — keystore 파일 경로(패키지 디렉토리 기준 상대).
-- storePassword: string — keystore 비밀번호.
-- alias: string — 키 별칭.
-- password: string — 키 비밀번호.
-- keystoreType?: string — keystore 타입(기본 `"jks"`).
+```typescript
+interface SdCapacitorSignConfig { keystore: string; storePassword: string; alias: string; password: string; keystoreType?: string; }
+interface SdCapacitorPermission { name: string; maxSdkVersion?: number; ignore?: string; }
+interface SdCapacitorIntentFilter { action?: string; category?: string; }
+```
 
-`SdCapacitorPermission`:
+- SdCapacitorSignConfig.keystore — keystore 파일 경로(패키지 기준 상대). storePassword/alias/password = 서명 자격. keystoreType?: string — keystore 타입(기본값 `"jks"`).
+- SdCapacitorPermission.name — 권한 이름(예: `"CAMERA"`). maxSdkVersion?: number — 권한 적용 최대 SDK. ignore?: string — `tools:ignore` 속성 값.
+- SdCapacitorIntentFilter.action — intent 액션(예: `"android.intent.action.VIEW"`). category — intent 카테고리(예: `"android.intent.category.DEFAULT"`).
 
-- name: string — 권한 이름(예: `"CAMERA"`, `"WRITE_EXTERNAL_STORAGE"`).
-- maxSdkVersion?: number — 권한 적용 최대 SDK 버전.
-- ignore?: string — `tools:ignore` 속성 값.
+## Electron 설정 (client 의 electron)
 
-## Electron 설정 (SdElectronConfig)
+```typescript
+interface SdElectronConfig {
+  appId: string;
+  portable?: boolean;
+  installerIcon?: string;
+  reinstallDependencies?: string[];
+  postInstallScript?: string;
+  nsisOptions?: Record<string, unknown>;
+  env?: Record<string, string>;
+}
+```
 
-- appId: string — Electron 앱 ID(예: `"com.example.myapp"`).
-- portable?: boolean — true 면 포터블 `.exe`, false/미지정 시 NSIS 설치 프로그램.
-- installerIcon?: string — 설치 프로그램 아이콘 경로(`.ico`, 패키지 기준 상대).
-- reinstallDependencies?: string[] — Electron 에 포함할 npm 패키지(네이티브 모듈 등).
+- appId: string — Electron 앱 ID(역도메인, 예: `"com.example.myapp"`).
+- portable?: boolean — true = 포터블 `.exe`, false/미지정 = NSIS 설치 프로그램. 설치 없이 실행 배포면 true.
+- installerIcon?: string — 설치 프로그램 아이콘(`.ico`, 패키지 기준 상대).
+- reinstallDependencies?: string[] — Electron 에 포함할 npm 패키지(네이티브 모듈 등) 목록.
 - postInstallScript?: string — npm postinstall 스크립트.
 - nsisOptions?: Record<string, unknown> — NSIS 옵션(`portable` 이 false 일 때 적용).
-- env?: Record<string, string> — 환경 변수. `electron-main.ts` 에서 `process.env` 로 접근.
+- env?: Record<string, string> — 환경 변수. `electron-main.ts` 에서 `process.env` 로 접근 가능.
 
-## PWA 설정 (SdPwaConfig)
+## PWA 설정 (client 의 pwa)
 
-`SdPwaConfig`:
+```typescript
+interface SdPwaConfig { manifest?: SdPwaManifestConfig; }
+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 }>;
+}
+```
 
-- manifest?: SdPwaManifestConfig — PWA manifest 설정.
+- manifest?: SdPwaManifestConfig — PWA manifest 커스터마이징. 미지정 시 기본 manifest.
+- display?: "standalone"|"fullscreen"|"minimal-ui"|"browser" — 앱 표시 모드. "standalone" = 브라우저 UI 없는 앱 창, "fullscreen" = 전체 화면, "minimal-ui" = 최소 브라우저 UI, "browser" = 일반 탭. 네이티브 느낌이면 "standalone".
+- name/short_name/theme_color/background_color — manifest 표준 필드(앱 이름·축약명·테마색·배경색).
+- icons?: Array<{ src; sizes; type? }> — manifest 아이콘 목록(경로·크기·MIME).
 
-`SdPwaManifestConfig` (모두 선택):
+## SdBrowserSupportConfig (client 의 browserSupport)
 
-- name?: string — 앱 전체 이름.
-- short_name?: string — 짧은 이름(홈 화면 등).
-- display?: "standalone" | "fullscreen" | "minimal-ui" | "browser" — 표시 모드. "standalone" = 단독 앱처럼, "fullscreen" = 전체 화면, "minimal-ui" = 최소 브라우저 UI, "browser" = 일반 탭. 앱 체감 수준 선택.
-- theme_color?: string — 테마 색상.
-- background_color?: string — 스플래시 배경 색상.
-- icons?: Array<{ src: string; sizes: string; type?: string }> — 아이콘 목록. `src` = 경로, `sizes` = 크기 문자열(예: `"512x512"`), `type` = MIME 타입.
+```typescript
+interface SdBrowserSupportConfig {
+  browserslist?: string | string[];
+  postCss?: { plugins: [string, (object | string)?][] };
+  legacyModule?: boolean;
+}
+```
+
+- browserslist?: string | string[] — browserslist 쿼리(예: `"last 2 Chrome versions"` 또는 `["ie 11", "last 2 versions"]`). 트랜스파일·prefix 대상 브라우저 범위.
+- postCss?.plugins: [string, (object|string)?][] — PostCSS 플러그인 `[이름, 옵션?]` 튜플 배열.
+- legacyModule?: boolean — 레거시 모듈 지원. true 면 코드 분할 비활성화 + `import.meta` 치환. 구형 환경 대응이 필요할 때.
 
 ## 보조 타입
 
-- BuildTarget — `"node" | "browser" | "neutral"`. `SdBuildPackageConfig.target` 값 집합.
-- NpmConfig — npm `package.json` 구조 타입(`name`, `version`, `description?`, `dependencies?`, `devDependencies?`, `peerDependencies?`, `volta?`). 설정 코드에서 package.json 을 타입 있게 다룰 때.
+```typescript
+type BuildTarget = "node" | "browser" | "neutral";
+interface NpmConfig { name; version; description?; dependencies?; devDependencies?; peerDependencies?; volta?; }
+```
+
+- BuildTarget — esbuild 라이브러리 빌드 런타임 타겟 enum(위 `SdPackageConfig` 풀이 참조).
+- NpmConfig — `package.json` 구조 타입. name/version 필수, 나머지 선택. package.json 을 타입 안전하게 다룰 때.