@simplysm/sd-cli 14.0.11 → 14.0.12

package/docs/config.md

@@ -0,0 +1,340 @@
+# Config
+
+## `BuildTarget`
+
+Build target type (built with esbuild).
+
+```typescript
+type BuildTarget = "node" | "browser" | "neutral";
+```
+
+| Value | Description |
+|---|---|
+| `"node"` | Node.js only package |
+| `"browser"` | Browser only package |
+| `"neutral"` | Node/browser shared package |
+
+## `SdBuildPackageConfig`
+
+Configuration for buildable packages (node/browser/neutral).
+
+```typescript
+interface SdBuildPackageConfig {
+  target: BuildTarget;
+  publish?: SdPublishConfig;
+  copySrc?: string[];
+  watch?: SdWatchHookConfig;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `BuildTarget` | Build target |
+| `publish` | `SdPublishConfig` | Publish configuration |
+| `copySrc` | `string[]` | Glob patterns for files to copy from `src/` to `dist/` (relative path based on `src/`) |
+| `watch` | `SdWatchHookConfig` | Watch hook configuration (when set, hook runs alongside build engine in watch mode) |
+
+## `SdClientPackageConfig`
+
+Configuration for client (Angular/Vite) packages.
+
+```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;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `"client"` | Fixed value |
+| `server` | `string \| number` | Server package name to connect to (e.g., `"solid-demo-server"`), or Vite port number (backward compatibility) |
+| `env` | `Record<string, string>` | Environment variables to substitute during build (replaces `process.env` with object) |
+| `publish` | `SdPublishConfig` | Publish configuration |
+| `capacitor` | `SdCapacitorConfig` | Capacitor mobile build configuration |
+| `electron` | `SdElectronConfig` | Electron desktop build configuration |
+| `configs` | `Record<string, unknown>` | Runtime config (written to `dist/.config.json` during build) |
+| `exclude` | `string[]` | Packages to exclude from Vite optimizeDeps and add to Capacitor/Electron `package.json` |
+| `browserSupport` | `SdBrowserSupportConfig` | Browser compatibility settings (browserslist, PostCSS, legacyModule) |
+| `pwa` | `false \| SdPwaConfig` | PWA configuration. `false` to disable. Enabled with defaults when not specified |
+
+## `SdServerPackageConfig`
+
+Configuration for server (Fastify) packages.
+
+```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";
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `"server"` | Fixed value |
+| `env` | `Record<string, string>` | Environment variables to substitute during build (replaces `process.env.KEY` with constant) |
+| `publish` | `SdPublishConfig` | Publish configuration |
+| `configs` | `Record<string, unknown>` | Runtime config (written to `dist/.config.json` during build) |
+| `externals` | `string[]` | External modules not to include in esbuild bundle (in addition to automatic `binding.gyp` detection) |
+| `pm2` | `{ name?: string; ignoreWatchPaths?: string[] }` | PM2 configuration (generates `dist/pm2.config.cjs` when specified). `name` defaults to a name generated from `package.json` |
+| `packageManager` | `"volta" \| "mise"` | Package manager to use (affects `mise.toml` or `volta` settings generation) |
+
+## `SdScriptsPackageConfig`
+
+Configuration for scripts-only packages (excluded from watch/typecheck unless watch hook is configured).
+
+```typescript
+interface SdScriptsPackageConfig {
+  target: "scripts";
+  publish?: SdPublishConfig;
+  watch?: SdWatchHookConfig;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `"scripts"` | Fixed value |
+| `publish` | `SdPublishConfig` | Publish configuration |
+| `watch` | `SdWatchHookConfig` | Watch hook configuration (when set, package is included in watch mode) |
+
+## `SdWatchHookConfig`
+
+Watch hook configuration for running commands on file changes.
+
+```typescript
+interface SdWatchHookConfig {
+  target: string[];
+  cmd: string;
+  args?: string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `target` | `string[]` | Glob patterns to watch (relative to package directory) |
+| `cmd` | `string` | Command to execute on change |
+| `args` | `string[]` | Command arguments |
+
+## `SdPackageConfig`
+
+Union of all package configuration types. Discriminated by the `target` field.
+
+```typescript
+type SdPackageConfig =
+  | SdBuildPackageConfig
+  | SdClientPackageConfig
+  | SdServerPackageConfig
+  | SdScriptsPackageConfig;
+```
+
+| Variant | Discriminant (`target`) |
+|---------|------------------------|
+| `SdBuildPackageConfig` | `"node"`, `"browser"`, `"neutral"` |
+| `SdClientPackageConfig` | `"client"` |
+| `SdServerPackageConfig` | `"server"` |
+| `SdScriptsPackageConfig` | `"scripts"` |
+
+## `SdConfig`
+
+The main configuration object for `sd.config.ts`.
+
+```typescript
+interface SdConfig {
+  packages: Record<string, SdPackageConfig | undefined>;
+  replaceDeps?: Record<string, string>;
+  postPublish?: SdPostPublishScriptConfig[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `packages` | `Record<string, SdPackageConfig \| undefined>` | Per-package configuration (key: subdirectory name under `packages/`, e.g., `"core-common"`) |
+| `replaceDeps` | `Record<string, string>` | Dependency replacement configuration (replace `node_modules` packages with local sources via symlink). Key is a package glob pattern (e.g., `"@simplysm/*"`), value is a source directory path. Captured values from key's `*` are substituted into value's `*` |
+| `postPublish` | `SdPostPublishScriptConfig[]` | Scripts to execute after deployment completes |
+
+## `SdConfigParams`
+
+Parameters passed to the `sd.config.ts` function.
+
+```typescript
+interface SdConfigParams {
+  cwd: string;
+  dev: boolean;
+  options: string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `cwd` | `string` | Current working directory |
+| `dev` | `boolean` | Development mode flag |
+| `options` | `string[]` | Additional options (from CLI's `-o` flag) |
+
+## `SdConfigFn`
+
+The type for the default export of `sd.config.ts`.
+
+```typescript
+type SdConfigFn = (params: SdConfigParams) => SdConfig | Promise<SdConfig>;
+```
+
+## `SdBrowserSupportConfig`
+
+Browser support configuration for client packages.
+
+```typescript
+interface SdBrowserSupportConfig {
+  browserslist?: string | string[];
+  postCss?: { plugins: unknown[] };
+  legacyModule?: boolean;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `browserslist` | `string \| string[]` | Browserslist query (e.g., `"last 2 Chrome versions"` or `["ie 11", "last 2 versions"]`) |
+| `postCss` | `{ plugins: unknown[] }` | PostCSS plugins configuration |
+| `legacyModule` | `boolean` | Legacy module support (disables code splitting + replaces `import.meta`) |
+
+## `SdCapacitorConfig`
+
+Capacitor configuration.
+
+```typescript
+interface SdCapacitorConfig {
+  appId: string;
+  appName: string;
+  plugins?: Record<string, Record<string, unknown> | true>;
+  icon?: string;
+  debug?: boolean;
+  platform?: { android?: SdCapacitorAndroidConfig };
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `appId` | `string` | App ID (e.g., `"com.example.app"`) |
+| `appName` | `string` | App display name |
+| `plugins` | `Record<string, Record<string, unknown> \| true>` | Capacitor plugin configuration (key: package name, value: `true` or plugin options) |
+| `icon` | `string` | App icon path (relative to package directory) |
+| `debug` | `boolean` | Debug build flag |
+| `platform` | `{ android?: SdCapacitorAndroidConfig }` | Per-platform configuration |
+
+## `SdCapacitorAndroidConfig`
+
+Capacitor Android platform configuration.
+
+```typescript
+interface SdCapacitorAndroidConfig {
+  config?: Record<string, string>;
+  bundle?: boolean;
+  intentFilters?: SdCapacitorIntentFilter[];
+  sign?: SdCapacitorSignConfig;
+  sdkVersion?: number;
+  permissions?: SdCapacitorPermission[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `config` | `Record<string, string>` | `AndroidManifest.xml` application tag attributes (e.g., `{ requestLegacyExternalStorage: "true" }`) |
+| `bundle` | `boolean` | AAB bundle build flag (`true` for AAB, `false` for APK) |
+| `intentFilters` | `SdCapacitorIntentFilter[]` | Intent Filter configuration |
+| `sign` | `SdCapacitorSignConfig` | APK/AAB signing configuration |
+| `sdkVersion` | `number` | Android SDK version (minSdk, targetSdk) |
+| `permissions` | `SdCapacitorPermission[]` | Additional permission configuration |
+
+## `SdCapacitorSignConfig`
+
+Capacitor Android sign configuration.
+
+```typescript
+interface SdCapacitorSignConfig {
+  keystore: string;
+  storePassword: string;
+  alias: string;
+  password: string;
+  keystoreType?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `keystore` | `string` | Keystore file path (relative to package directory) |
+| `storePassword` | `string` | Keystore password |
+| `alias` | `string` | Key alias |
+| `password` | `string` | Key password |
+| `keystoreType` | `string` | Keystore type (default: `"jks"`) |
+
+## `SdCapacitorPermission`
+
+Capacitor Android permission configuration.
+
+```typescript
+interface SdCapacitorPermission {
+  name: string;
+  maxSdkVersion?: number;
+  ignore?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Permission name (e.g., `"CAMERA"`, `"WRITE_EXTERNAL_STORAGE"`) |
+| `maxSdkVersion` | `number` | Maximum SDK version |
+| `ignore` | `string` | `tools:ignore` attribute value |
+
+## `SdCapacitorIntentFilter`
+
+Capacitor Android Intent Filter configuration.
+
+```typescript
+interface SdCapacitorIntentFilter {
+  action?: string;
+  category?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `action` | `string` | Intent action (e.g., `"android.intent.action.VIEW"`) |
+| `category` | `string` | Intent category (e.g., `"android.intent.category.DEFAULT"`) |
+
+## `SdElectronConfig`
+
+Electron configuration.
+
+```typescript
+interface SdElectronConfig {
+  appId: string;
+  portable?: boolean;
+  installerIcon?: string;
+  reinstallDependencies?: string[];
+  postInstallScript?: string;
+  nsisOptions?: Record<string, unknown>;
+  env?: Record<string, string>;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `appId` | `string` | Electron app ID (e.g., `"com.example.myapp"`) |
+| `portable` | `boolean` | `true` for portable `.exe`, `false`/unspecified for NSIS installer |
+| `installerIcon` | `string` | Installer icon path (`.ico`, relative to package directory) |
+| `reinstallDependencies` | `string[]` | npm packages to include in Electron (native modules, etc.) |
+| `postInstallScript` | `string` | npm postinstall script |
+| `nsisOptions` | `Record<string, unknown>` | NSIS options (when `portable` is `false`) |
+| `env` | `Record<string, string>` | Environment variables (accessible via `process.env` in `electron-main.ts`) |

package/docs/publish-configuration-types.md

@@ -0,0 +1,87 @@
+# Publish Configuration Types
+
+## `SdPublishConfig`
+
+Union of all publish configuration types. Discriminated by the `type` field.
+
+```typescript
+type SdPublishConfig = SdNpmPublishConfig | SdLocalDirectoryPublishConfig | SdStoragePublishConfig;
+```
+
+| Variant | Discriminant (`type`) |
+|---------|----------------------|
+| `SdNpmPublishConfig` | `"npm"` |
+| `SdLocalDirectoryPublishConfig` | `"local-directory"` |
+| `SdStoragePublishConfig` | `"ftp"`, `"ftps"`, `"sftp"` |
+
+## `SdNpmPublishConfig`
+
+npm registry publish configuration.
+
+```typescript
+interface SdNpmPublishConfig {
+  type: "npm";
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"npm"` | Publish type discriminator |
+
+## `SdLocalDirectoryPublishConfig`
+
+Copy build output to a local directory.
+
+```typescript
+interface SdLocalDirectoryPublishConfig {
+  type: "local-directory";
+  path: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"local-directory"` | Publish type discriminator |
+| `path` | `string` | Deployment target path (supports environment variable substitution: `%VER%`, `%PROJECT%`) |
+
+## `SdStoragePublishConfig`
+
+Upload build output to FTP/FTPS/SFTP server.
+
+```typescript
+interface SdStoragePublishConfig {
+  type: "ftp" | "ftps" | "sftp";
+  host: string;
+  port?: number;
+  path?: string;
+  user?: string;
+  password?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"ftp" \| "ftps" \| "sftp"` | Protocol |
+| `host` | `string` | Server hostname |
+| `port` | `number` | Server port |
+| `path` | `string` | Remote path |
+| `user` | `string` | Username |
+| `password` | `string` | Password |
+
+## `SdPostPublishScriptConfig`
+
+Script to run after publish completes.
+
+```typescript
+interface SdPostPublishScriptConfig {
+  type: "script";
+  cmd: string;
+  args: string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `"script"` | Config type discriminator |
+| `cmd` | `string` | Command to execute |
+| `args` | `string[]` | Command arguments (supports environment variable substitution: `%VER%`, `%PROJECT%`) |

package/docs/pwa-configuration-types.md

@@ -0,0 +1,55 @@
+# PWA Configuration Types
+
+## `SdPwaConfig`
+
+PWA configuration.
+
+```typescript
+interface SdPwaConfig {
+  manifest?: SdPwaManifestConfig;
+  workbox?: SdPwaWorkboxConfig;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `manifest` | `SdPwaManifestConfig` | PWA manifest options |
+| `workbox` | `SdPwaWorkboxConfig` | Workbox service worker options |
+
+## `SdPwaManifestConfig`
+
+PWA manifest configuration (subset of VitePWA manifest options).
+
+```typescript
+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` | App name |
+| `short_name` | `string` | Short app name |
+| `display` | `"standalone" \| "fullscreen" \| "minimal-ui" \| "browser"` | Display mode |
+| `theme_color` | `string` | Theme color |
+| `background_color` | `string` | Background color |
+| `icons` | `Array<{ src: string; sizes: string; type?: string }>` | App icons |
+
+## `SdPwaWorkboxConfig`
+
+PWA workbox configuration.
+
+```typescript
+interface SdPwaWorkboxConfig {
+  globPatterns?: string[];
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `globPatterns` | `string[]` | Glob patterns for precaching |

package/docs/vitest-plugin.md

@@ -0,0 +1,47 @@
+# Vitest Plugin
+
+## `angularVitestPlugin`
+
+Vite plugin for Angular AOT compilation in Vitest. Compiles `src/` files and `.fixture.` files using Angular's `NgtscProgram`, caching the compiled output in memory and returning it from the `transform` hook.
+
+```typescript
+function angularVitestPlugin(options: AngularVitestPluginOptions): Plugin;
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `options` | `AngularVitestPluginOptions` | Plugin options |
+
+**Returns:** A Vite `Plugin` object with `buildStart` and `transform` hooks.
+
+**Behavior:**
+
+- `buildStart`: Reads `tsconfig.json`, creates an Angular `NgtscProgram`, runs AOT analysis, and emits compiled JavaScript for each source file into an in-memory cache.
+- `transform`: For `.ts` files (excluding `node_modules`), returns the cached compiled output if available.
+
+**Usage:**
+
+```typescript
+import { angularVitestPlugin } from "@simplysm/sd-cli/vitest-plugin";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  plugins: [angularVitestPlugin({ tsconfig: "./tsconfig.json" })],
+});
+```
+
+## `AngularVitestPluginOptions`
+
+Options for `angularVitestPlugin`.
+
+```typescript
+interface AngularVitestPluginOptions {
+  tsconfig: string;
+  cwd?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tsconfig` | `string` | Angular package's `tsconfig.json` absolute path |
+| `cwd` | `string` | Monorepo workspace root path. When not specified, uses two directories above the `tsconfig` path |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/sd-cli",
-  "version": "14.0.11",
+  "version": "14.0.12",
   "description": "Simplysm package - CLI tool",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -14,21 +14,23 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "docs",
     "src",
     "tests"
   ],
   "sideEffects": false,
   "dependencies": {
-    "@angular/build": "^21.2.5",
-    "@angular/compiler-cli": "^21.2.6",
+    "@angular/build": "^21.2.6",
+    "@angular/compiler-cli": "^21.2.7",
     "@fastify/http-proxy": "^11.4.3",
     "@inquirer/prompts": "^8.3.2",
     "browserslist-to-esbuild": "^2.1.1",
     "consola": "^3.4.2",
-    "esbuild": "^0.27.4",
+    "esbuild": "^0.27.5",
     "eslint": "^9.39.4",
     "glob": "^13.0.6",
     "jiti": "^2.6.1",
+    "mime": "^4.1.0",
     "postcss": "^8.5.8",
     "sass": "^1.98.0",
     "semver": "^7.7.4",
@@ -39,9 +41,9 @@
     "vite-plugin-pwa": "^1.2.0",
     "vite-tsconfig-paths": "^6.1.1",
     "yargs": "^18.0.0",
-    "@simplysm/core-common": "14.0.11",
-    "@simplysm/core-node": "14.0.11",
-    "@simplysm/storage": "14.0.11"
+    "@simplysm/core-node": "14.0.12",
+    "@simplysm/storage": "14.0.12",
+    "@simplysm/core-common": "14.0.12"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",

package/src/angular/client-transform-stylesheet.ts

@@ -52,7 +52,7 @@ export function createClientTransformStylesheet(
           return "/* SCSS compilation error */";
         }
       }
-      // .css → readResource가 처리
+      // .css → externalStylesheets의 SHA256 ID 매핑으로 처리
       return null;
     }