@simplysm/sd-cli 13.0.69 → 13.0.71

package/README.md

@@ -1,974 +1,27 @@
 # @simplysm/sd-cli
 
-The CLI tool for the Simplysm framework. It provides project initialization, ESLint/Stylelint linting, TypeScript type-checking, combined check (typecheck + lint + test), library/client/server package builds, development mode, deployment, Android device execution, and Electron desktop app build capabilities.
+CLI tool for the Simplysm framework. Provides project initialization, lint, typecheck, watch, dev server, build, publish, and device commands. Also exports configuration types and Vite utilities for use in `sd.config.ts` and `vite.config.ts` files.
 
 ## Installation
 
-```bash
-npm install --save-dev @simplysm/sd-cli
-# or
-pnpm add -D @simplysm/sd-cli
 ```
-
-## Main Commands
-
-The CLI binary name is `sd-cli`. All commands support the `--debug` option to output detailed logs.
-
-### lint
-
-Runs ESLint and Stylelint. ESLint lints `.ts`/`.tsx`/`.js`/`.jsx` files; Stylelint lints `.css` files (only when a Stylelint config file is present). Extracts globalIgnores patterns from `eslint.config.ts`. Caches results in `.cache/eslint.cache` and `.cache/stylelint.cache`.
-
-```bash
-# Lint all
-sd-cli lint
-
-# Lint specific path
-sd-cli lint packages/core-common
-
-# Lint multiple paths
-sd-cli lint packages/core-common tests/orm
-
-# Auto-fix
-sd-cli lint --fix
-
-# Output rule execution times
-sd-cli lint --timing
-```
-
-**Options:**
-
-| Option     | Description                                                | Default |
-| ---------- | ---------------------------------------------------------- | ------- |
-| `--fix`    | Auto-fix                                                   | `false` |
-| `--timing` | Output rule execution times (sets ESLint `TIMING` env var) | `false` |
-| `--debug`  | Output debug logs                                          | `false` |
-
-### typecheck
-
-Runs TypeScript type-checking. It performs parallel type-checking per package environment (`node`/`browser`) based on `tsconfig.json` and `sd.config.ts`. Uses worker threads to run concurrently up to 7/8 of CPU cores.
-
-```bash
-# Type-check all
-sd-cli typecheck
-
-# Type-check specific path
-sd-cli typecheck packages/core-common
-
-# Type-check multiple paths
-sd-cli typecheck packages/core-common tests/orm
-
-# Pass options to sd.config.ts
-sd-cli typecheck -o key=value
-```
-
-**Options:**
-
-| Option            | Description                                                | Default |
-| ----------------- | ---------------------------------------------------------- | ------- |
-| `--options`, `-o` | Additional options to pass to sd.config.ts (multi-use)     | `[]`    |
-| `--debug`         | Output debug logs                                          | `false` |
-
-**Type-check environment by target:**
-
-| Target              | Environment             |
-| ------------------- | ----------------------- |
-| `node`              | node environment once   |
-| `browser`, `client` | browser environment once |
-| `neutral`           | node + browser environment twice |
-| `scripts`           | Excluded from type-check |
-
-### check
-
-Runs typecheck, lint, and test in parallel and prints a consolidated summary. Lint auto-fix is always enabled when run via `check`. Exits with code `1` if any check fails.
-
-```bash
-# Run all checks (typecheck + lint + test)
-sd-cli check
-
-# Run specific check types
-sd-cli check --type typecheck,lint
-
-# Filter paths
-sd-cli check packages/core-common
-```
-
-**Options:**
-
-| Option     | Description                                                          | Default                  |
-| ---------- | -------------------------------------------------------------------- | ------------------------ |
-| `--type`   | Comma-separated list of check types to run: `typecheck`, `lint`, `test` | `typecheck,lint,test` |
-| `--debug`  | Output debug logs                                                    | `false`                  |
-
-**Output format:**
-
-Each check type prints a section header followed by its result summary. A final `SUMMARY` section lists overall pass/fail status and total error/warning counts.
-
-### watch
-
-Watches **library packages** (`node`/`browser`/`neutral` targets) in watch mode. Automatically rebuilds on file changes and generates `.d.ts` type definition files.
-
-> **Note**: Use the `dev` command for `client`/`server` targets.
-
-```bash
-# Watch all library packages
-sd-cli watch
-
-# Watch specific package
-sd-cli watch solid
-
-# Watch multiple packages
-sd-cli watch solid core-common
-```
-
-**Options:**
-
-| Option            | Description                                                | Default |
-| ----------------- | ---------------------------------------------------------- | ------- |
-| `--options`, `-o` | Additional options to pass to sd.config.ts (multi-use)     | `[]`    |
-| `--debug`         | Output debug logs                                          | `false` |
-
-### dev
-
-Runs **Client and Server packages** in development mode. `client` targets run with Vite dev server, and `server` targets run with Server Build Worker + Server Runtime Worker. Supports Server-Client proxy connection and Capacitor initialization.
-
-```bash
-# Run all client/server packages
-sd-cli dev
-
-# Run specific package
-sd-cli dev solid-demo
-
-# Run multiple packages
-sd-cli dev solid-demo my-server
-```
-
-**Options:**
-
-| Option            | Description                                                | Default |
-| ----------------- | ---------------------------------------------------------- | ------- |
-| `--options`, `-o` | Additional options to pass to sd.config.ts (multi-use)     | `[]`    |
-| `--debug`         | Output debug logs                                          | `false` |
-
-**How it works:**
-
-- `client` target: Starts Vite dev server. If `server` config is a string (package name), connects proxy to that server
-- `server` target: Builds in esbuild watch mode, then runs server runtime in separate Worker. Auto-rebuilds and restarts server on file changes
-- Client packages with Capacitor config perform Capacitor initialization after build completes
-- Client packages with Electron config launch Electron in dev mode after build completes
-- Terminates on SIGINT/SIGTERM signals
-
-**Scope Package HMR:**
-
-When using `replaceDeps` to develop scope packages locally, the Vite dev server automatically watches scope package dist files and triggers HMR when they change. This allows changes to `@simplysm/*` packages to be reflected in the dev app without manual reload.
-
-### build
-
-Runs production build. Performs lint, dist folder cleanup, and build sequentially.
-
-```bash
-# Build all packages
-sd-cli build
-
-# Build specific packages
-sd-cli build solid core-common
-```
-
-**Options:**
-
-| Option            | Description                                                | Default |
-| ----------------- | ---------------------------------------------------------- | ------- |
-| `--options`, `-o` | Additional options to pass to sd.config.ts (multi-use)     | `[]`    |
-| `--debug`         | Output debug logs                                          | `false` |
-
-**Build behavior by target:**
-
-| Target                     | JS build        | .d.ts generation | Type-check | Note                                  |
-| -------------------------- | --------------- | ---------------- | ---------- | ------------------------------------- |
-| `node`/`browser`/`neutral` | esbuild         | O                | O          | Library package                       |
-| `client`                   | Vite production | X                | O          | Client app (+ Capacitor/Electron build) |
-| `server`                   | esbuild         | X                | X          | Server app                            |
-| `scripts`                  | Excluded        | Excluded         | Excluded   | -                                     |
-
-**Public Files & Assets:**
-
-Both client and server packages support serving static files from a `public/` directory:
-
-- **Client packages** (`dev` mode): Vite serves `public/` at the configured base path (`/{name}/`)
-- **Server packages** (`dev` mode): Copies `public/` to `dist/`, watches for changes, and automatically rebuilds
-- **Server packages** (`build` mode): Copies `public/` to `dist/` (production deployment)
-- **Client packages** (`dev` mode only): Optional `public-dev/` directory files are served with priority over `public/` files, allowing dev-specific overrides without affecting production builds
-
-Directory structure:
-```
-packages/my-server/
-├── public/              # Static files (both dev and build)
-│   ├── index.html
-│   ├── style.css
-│   └── assets/
-└── public-dev/          # Dev-only overrides (dev mode only, ignored in build)
-    └── index.html       # Overrides public/index.html in dev
-```
-
-**How it works:**
-
-- In `dev` mode, both `public/` and `public-dev/` are copied to `dist/`, with `public-dev/` changes taking priority
-- If a `public-dev/` file is deleted, the corresponding `public/` file is served as fallback
-- In `build` mode, only `public/` is copied to `dist/` (no `public-dev/`)
-- The copy operation preserves directory structure
-
-**Runtime Configuration File (.config.json):**
-
-If a `server` or `client` package defines a `configs` field in `sd.config.ts`, the build automatically generates `dist/.config.json` containing that configuration. This is useful for storing environment-specific settings (database config, API endpoints, etc.) that are read at runtime via `ctx.getConfig()` in `service-server`.
-
-**Server Build: Externals & Production Deployment Files:**
-
-Server builds (`target: "server"`) automatically detect modules that cannot be bundled by esbuild and mark them as external. Three sources of externals are combined:
-
-1. **Uninstalled optional peer dependencies** — automatically detected via `peerDependenciesMeta`
-2. **Native modules (node-gyp)** — automatically detected by scanning for `binding.gyp` files in the dependency tree
-3. **Manual externals** — specified via `externals` in `sd.config.ts`
-
-During production build (`sd-cli build`), the following deployment files are generated in `dist/`:
-
-| File | Description |
-|------|-------------|
-| `package.json` | Minimal package.json with externalized dependencies (version `"*"`) for `npm install` on the deployment server |
-| `mise.toml` | Node.js version specification (read from root `mise.toml`) — only generated when `packageManager: "mise"` is set |
-| `openssl.cnf` | Legacy OpenSSL provider activation (required for MSSQL and other legacy TLS connections) |
-| `pm2.config.cjs` | PM2 process manager config (only generated when `pm2` is configured) |
-
-> **Note**: Production deployment files are only generated during `sd-cli build`, not during `sd-cli dev` (watch mode).
-
-### publish
-
-Publishes packages. For safety, proceeds in the following order:
-
-1. Pre-validation (npm authentication, Git uncommitted changes check)
-2. Version upgrade (increment prerelease if prerelease, otherwise patch)
-3. Build (Git rollback on failure)
-4. Git commit/tag/push (Git rollback on failure)
-5. npm/FTP/local deployment
-6. postPublish script execution
-
-```bash
-# Publish all packages with publish config
-sd-cli publish
-
-# Publish specific packages
-sd-cli publish solid core-common
-
-# Publish without build (dangerous)
-sd-cli publish --no-build
-
-# Simulate without actual deployment
-sd-cli publish --dry-run
-```
-
-**Options:**
-
-| Option                   | Description                                                | Default |
-| ------------------------ | ---------------------------------------------------------- | ------- |
-| `--build` / `--no-build` | Whether to run build (skip with `--no-build`)             | `true`  |
-| `--dry-run`              | Simulate without actual deployment                         | `false` |
-| `--options`, `-o`        | Additional options to pass to sd.config.ts (multi-use)     | `[]`    |
-| `--debug`                | Output debug logs                                          | `false` |
-
-### init
-
-Initializes a new Simplysm project in the current directory. The directory must be empty and the directory name must be a valid npm scope name (lowercase, numbers, hyphens only).
-
-Creates a skeleton project with:
-- `sd.config.ts`, `tsconfig.json`, `eslint.config.ts`, `pnpm-workspace.yaml`
-- `.gitignore`, `.prettierrc.yaml`, `.prettierignore`, `mise.toml`
-
-After rendering templates, runs `pnpm install` automatically.
-
-```bash
-# Create an empty directory and run init
-mkdir my-project && cd my-project
-sd-cli init
-```
-
-After initialization, use `sd-cli add client` and `sd-cli add server` to add packages.
-
-> **Note**: Claude Code skills/agents are automatically installed via `@simplysm/sd-claude` postinstall.
-
-### add client
-
-Adds a client package to an existing project. Must be run from the project root (where `sd.config.ts` exists).
-
-Runs an interactive prompt to collect:
-1. Client package name suffix (creates `client-{suffix}` package)
-2. Whether to use router
-
-After collecting inputs, it:
-1. Renders client package from Handlebars templates into `packages/client-{suffix}/`
-2. Adds the package entry to `sd.config.ts` (via ts-morph AST editing)
-3. Adds tailwind CSS settings to `eslint.config.ts` (if first client)
-4. Runs `pnpm install`
-
-```bash
-sd-cli add client
-```
-
-### add server
-
-Adds a server package to an existing project. Must be run from the project root (where `sd.config.ts` exists).
-
-Runs an interactive prompt to collect:
-1. Server name suffix (leave empty for just `server`, otherwise creates `server-{suffix}`)
-2. Which existing client packages this server should serve (multi-select)
-
-After collecting inputs, it:
-1. Renders server package from Handlebars templates into `packages/{server-name}/`
-2. Adds the server package entry to `sd.config.ts`
-3. Updates selected client packages' `server` field in `sd.config.ts`
-4. Runs `pnpm install`
-
-```bash
-sd-cli add server
-```
-
-### replace-deps
-
-Sets up local dependency replacement according to `replaceDeps` configuration in `sd.config.ts`. Useful for local development of dependent packages across separate repositories.
-
-```bash
-# Set up replacements (symlink or copy mode based on config)
-sd-cli replace-deps
-
-# With additional options
-sd-cli replace-deps -o key=value
-```
-
-**Options:**
-
-| Option            | Description                                                | Default |
-| ----------------- | ---------------------------------------------------------- | ------- |
-| `--options`, `-o` | Additional options to pass to sd.config.ts (multi-use)     | `[]`    |
-| `--debug`         | Output debug logs                                          | `false` |
-
-### device
-
-Runs Capacitor app on Android device. Only available for `client` target packages with `capacitor` config in `sd.config.ts`.
-
-```bash
-# Specify package (required)
-sd-cli device -p my-app
-
-# Specify dev server URL directly
-sd-cli device -p my-app -u http://192.168.0.10:3000
-```
-
-**Options:**
-
-| Option            | Description                                                               | Default |
-| ----------------- | ------------------------------------------------------------------------- | ------- |
-| `--package`, `-p` | Package name (required)                                                   | -       |
-| `--url`, `-u`     | Dev server URL (uses server port from sd.config.ts if not specified)      | -       |
-| `--options`, `-o` | Additional options to pass to sd.config.ts (multi-use)                    | `[]`    |
-| `--debug`         | Output debug logs                                                         | `false` |
-
-## Exported Types and Utilities
-
-This package exports configuration types for `sd.config.ts` and Vite utilities. All are importable from `@simplysm/sd-cli`.
-
-```typescript
-import type {
-  SdConfigFn,
-  SdConfigParams,
-  SdConfig,
-  SdPackageConfig,
-  BuildTarget,
-  SdBuildPackageConfig,
-  SdClientPackageConfig,
-  SdServerPackageConfig,
-  SdScriptsPackageConfig,
-  SdPublishConfig,
-  SdLocalDirectoryPublishConfig,
-  SdStoragePublishConfig,
-  SdPostPublishScriptConfig,
-  SdCapacitorConfig,
-  SdCapacitorAndroidConfig,
-  SdCapacitorSignConfig,
-  SdCapacitorPermission,
-  SdCapacitorIntentFilter,
-  SdElectronConfig,
-  ViteConfigOptions,
-} from "@simplysm/sd-cli";
-import { createViteConfig } from "@simplysm/sd-cli";
+pnpm add @simplysm/sd-cli
 ```
 
-| Type | Description |
-|------|-------------|
-| `SdConfigFn` | Function type for `sd.config.ts` default export: `(params: SdConfigParams) => SdConfig \| Promise<SdConfig>` |
-| `SdConfigParams` | Parameters passed to the config function (`cwd`, `dev`, `opt`) |
-| `SdConfig` | Root configuration object (`packages`, `replaceDeps?`, `postPublish?`) |
-| `SdPackageConfig` | Union of all package config types |
-| `BuildTarget` | Library build target: `"node" \| "browser" \| "neutral"` |
-| `SdBuildPackageConfig` | Config for library packages (`node`/`browser`/`neutral` targets) |
-| `SdClientPackageConfig` | Config for client packages (`client` target) |
-| `SdServerPackageConfig` | Config for server packages (`server` target, with `externals` and `pm2` options) |
-| `SdScriptsPackageConfig` | Config for scripts-only packages (`scripts` target) |
-| `SdPublishConfig` | Deployment config: `"npm" \| SdLocalDirectoryPublishConfig \| SdStoragePublishConfig` |
-| `SdLocalDirectoryPublishConfig` | Local directory deployment config (`type: "local-directory"`, `path`) |
-| `SdStoragePublishConfig` | FTP/FTPS/SFTP deployment config (`type`, `host`, `port?`, `path?`, `user?`, `pass?`) |
-| `SdPostPublishScriptConfig` | Post-publish script config (`type: "script"`, `cmd`, `args`) |
-| `SdCapacitorConfig` | Capacitor config for Android app builds |
-| `SdCapacitorAndroidConfig` | Android platform-specific Capacitor config |
-| `SdCapacitorSignConfig` | APK/AAB signing config (`keystore`, `storePassword`, `alias`, `password`, `keystoreType?`) |
-| `SdCapacitorPermission` | Android permission entry (`name`, `maxSdkVersion?`, `ignore?`) |
-| `SdCapacitorIntentFilter` | Android intent filter entry (`action?`, `category?`) |
-| `SdElectronConfig` | Electron desktop app build config |
-| `ViteConfigOptions` | Options passed to `createViteConfig()` — see fields below |
+## Usage
 
-## Vite Utilities
-
-### createViteConfig
-
-Creates pre-configured Vite configuration for Simplysm client packages.
-
-```typescript
-import { createViteConfig, type ViteConfigOptions } from "@simplysm/sd-cli";
-
-const options: ViteConfigOptions = {
-  pkgDir: "/path/to/package",
-  name: "my-app",
-  tsconfigPath: "/path/to/tsconfig.json",
-  compilerOptions: {},
-  mode: "build",
-};
-
-export default createViteConfig(options);
-```
-
-**`ViteConfigOptions` fields:**
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `pkgDir` | `string` | Yes | Absolute path to the package directory |
-| `name` | `string` | Yes | Package name used as Vite base path (`/{name}/`) |
-| `tsconfigPath` | `string` | Yes | Absolute path to `tsconfig.json` |
-| `compilerOptions` | `Record<string, unknown>` | Yes | TypeScript compiler options passed to esbuild |
-| `env` | `Record<string, string>` | No | Environment variables to substitute for `process.env` at build time |
-| `mode` | `"build" \| "dev"` | Yes | Build mode: `"build"` for production, `"dev"` for development server |
-| `serverPort` | `number` | No | Dev server port (`0` for auto-assign). Only used in `"dev"` mode |
-| `watchScopes` | `string[]` | No | Scope package prefixes to watch for HMR (e.g., `["@simplysm"]`) |
-| `onScopeRebuild` | `() => void` | No | Callback invoked when a watched scope package dist file changes |
-
-The `createViteConfig()` function configures:
-- Development server configuration
-- Production build optimization
-- SolidJS + TailwindCSS plugin integration
-- PWA (service worker + web app manifest) generation
-- Environment variable substitution support
-- Scope package watch/HMR (automatically watches scope package dist files and triggers HMR on changes via `replaceDeps`)
-
-## Configuration (sd.config.ts)
-
-Create an `sd.config.ts` file in the project root to define build targets and deployment settings per package. Used by `typecheck`, `watch`, `dev`, `build`, `publish`, and `device` commands.
-
-The `typecheck` command treats all packages as `neutral` target if no config file exists. The `watch`, `dev`, `build`, and `publish` commands require this file.
-
-### Basic Example
-
-```typescript
-import type { SdConfigFn } from "@simplysm/sd-cli";
-
-const config: SdConfigFn = () => ({
-  packages: {
-    "core-common": { target: "neutral" },
-    "core-node": { target: "node" },
-    "core-browser": { target: "browser" },
-    "solid": { target: "browser", publish: "npm" },
-    "solid-demo": { target: "client", server: "solid-demo-server" },
-    "solid-demo-server": { target: "server" },
-    "my-scripts": { target: "scripts" },
-  },
-});
-
-export default config;
-```
-
-### Target Types
-
-| Target    | Description                                                        | Type-check         | watch | dev | build        |
-| --------- | ------------------------------------------------------------------ | ------------------ | ----- | --- | ------------ |
-| `node`    | Node.js-only package. Removes DOM lib, includes `@types/node`     | O (node)           | O     | X   | O (JS + dts) |
-| `browser` | Browser-only package. Keeps DOM lib, excludes `@types/node`       | O (browser)        | O     | X   | O (JS + dts) |
-| `neutral` | Node/browser common. Keeps DOM lib, includes `@types/node`        | O (node + browser) | O     | X   | O (JS + dts) |
-| `client`  | Vite dev server-based client app                                   | O (browser)        | X     | O   | O (Vite)     |
-| `server`  | Fastify-based server app                                           | X                  | X     | O   | O (JS)       |
-| `scripts` | Excluded from typecheck/watch/build                                | X                  | X     | X   | X            |
-
-### Function Parameters
-
-The `sd.config.ts` function receives a `SdConfigParams` object as an argument:
-
-```typescript
-import type { SdConfigFn, SdConfigParams } from "@simplysm/sd-cli";
-
-const config: SdConfigFn = (params: SdConfigParams) => {
-  // params.cwd  - Current working directory
-  // params.dev  - Whether in dev mode (true for dev command, false for build/publish)
-  // params.opt  - Additional options array passed via CLI's -o flag
-
-  return {
-    packages: {
-      "my-app": {
-        target: "client",
-        server: params.dev ? 3000 : "my-server",
-      },
-    },
-  };
-};
-
-export default config;
-```
-
-### Package Configuration Types
-
-#### Library Package (SdBuildPackageConfig)
-
-```typescript
-{
-  target: "node" | "browser" | "neutral";
-  publish?: SdPublishConfig;  // Deployment config (optional)
-  copySrc?: string[];         // Glob patterns for copying assets from src/ to dist/ (optional)
-}
-```
-
-**Asset Copying (copySrc)**
-
-The `copySrc` option allows copying non-TypeScript files (CSS, images, etc.) from `src/` to `dist/` during build and watch mode:
-
-```typescript
-"my-lib": {
-  target: "browser",
-  publish: "npm",
-  copySrc: ["**/*.css", "**/*.png"],  // Copy all CSS and PNG files
-}
-```
-
-**How it works:**
-- Glob patterns are relative to `src/` directory
-- File directory structure is preserved during copy (e.g., `src/styles/theme.css` → `dist/styles/theme.css`)
-- Applied during both production build (`sd-cli build`) and watch mode (`sd-cli watch`)
-- Useful for including CSS files with component libraries when consuming apps may not bundle them automatically
-
-#### Client Package (SdClientPackageConfig)
-
-```typescript
-{
-  target: "client";
-  server: string | number;      // Server package name or direct port number
-  env?: Record<string, string>; // Environment variables to replace during build
-  publish?: SdPublishConfig;    // Deployment config (optional)
-  capacitor?: SdCapacitorConfig; // Capacitor config (optional)
-  electron?: SdElectronConfig;  // Electron config (optional)
-  configs?: Record<string, unknown>; // Runtime config (written to dist/.config.json during build)
-}
-```
-
-##### Progressive Web App (PWA) Support
-
-All client packages automatically generate PWA files during build. No configuration is required to enable PWA.
-
-**Generated Files:**
-
-- `sw.js` - Service worker (handles offline caching and precache of all build assets)
-- `manifest.webmanifest` - Web app manifest (for app install/launch)
-- `registerSW.js` - Service worker registration script (injected automatically)
-
-**Key behaviors:**
-
-- **Build mode**: Service worker is fully enabled with offline support and asset precaching via Workbox
-- **Dev mode**: Service worker registration is disabled by default for safe development (no stale cache issues)
-- **Precache strategy**: All build assets (`*.js`, `*.css`, `*.html`, `*.ico`, `*.png`, `*.svg`, `*.woff2`) are precached for instant loading
-- **HTTPS requirement**: Service workers require HTTPS at runtime (localhost dev mode is exempt)
-- **Offline capability**: Once cached, the app works offline with all precached resources available
-
-Users can install the app on their home screen on supported browsers and devices. No additional code or dependencies are needed.
-
-#### Server Package (SdServerPackageConfig)
-
-```typescript
-{
-  target: "server";
-  env?: Record<string, string>;      // Environment variables to replace during build
-  publish?: SdPublishConfig;         // Deployment config (optional)
-  configs?: Record<string, unknown>; // Runtime config (written to dist/.config.json during build)
-  externals?: string[];              // Additional modules to exclude from bundle (optional)
-  packageManager?: "volta" | "mise"; // Package manager for Node.js version management (optional)
-  pm2?: {                            // PM2 config — generates dist/pm2.config.cjs (optional)
-    name?: string;                   // PM2 process name (defaults to package name)
-    ignoreWatchPaths?: string[];     // Paths to ignore in PM2 watch
-  };
-}
-```
-
-#### Scripts Package (SdScriptsPackageConfig)
-
-```typescript
-{
-  target: "scripts";
-}
-```
-
-### Deployment Configuration (SdPublishConfig)
-
-Three deployment methods are supported:
-
-| Method           | Config Value                                                            | Description                           |
-| ---------------- | ----------------------------------------------------------------------- | ------------------------------------- |
-| npm              | `"npm"`                                                                 | Deploy to npm registry                |
-| Local directory  | `{ type: "local-directory", path: "..." }`                              | Copy dist to local path               |
-| Storage          | `{ type: "ftp" \| "ftps" \| "sftp", host, port?, path?, user?, pass? }` | Upload to FTP/FTPS/SFTP server        |
-
-Environment variable substitution is supported in `path` for local directory and storage: `%VER%` (version), `%PROJECT%` (project path).
-
-```typescript
-// npm deployment
-"core-common": { target: "neutral", publish: "npm" },
-
-// Local directory deployment
-"my-app": {
-  target: "client",
-  server: 3000,
-  publish: { type: "local-directory", path: "/deploy/%VER%/my-app" },
-},
-
-// SFTP upload
-"my-server": {
-  target: "server",
-  publish: {
-    type: "sftp",
-    host: "deploy.example.com",
-    port: 22,
-    path: "/opt/app",
-    user: "deploy",
-    pass: "secret",
-  },
-},
-```
-
-### Runtime Configuration (configs)
-
-Define runtime configuration for `server` or `client` packages using the `configs` field. This configuration is automatically written to `dist/.config.json` during build and can be read at runtime via `ctx.getConfig()` in the `service-server` package.
-
-```typescript
-import type { SdConfigFn } from "@simplysm/sd-cli";
-
-const config: SdConfigFn = () => ({
-  packages: {
-    "my-server": {
-      target: "server",
-      configs: {
-        // Runtime configuration sections
-        orm: {
-          default: {
-            dialect: "mysql",
-            host: process.env.DB_HOST || "localhost",
-            port: 3306,
-            database: "mydb",
-            user: process.env.DB_USER || "root",
-            password: process.env.DB_PASSWORD,
-          },
-        },
-        smtp: {
-          default: {
-            host: "smtp.example.com",
-            port: 587,
-            secure: false,
-            user: process.env.SMTP_USER,
-            pass: process.env.SMTP_PASS,
-          },
-        },
-      },
-    },
-    "my-app": {
-      target: "client",
-      server: "my-server",
-      configs: {
-        api: {
-          baseUrl: process.env.API_URL || "http://localhost:3000",
-          timeout: 30000,
-        },
-      },
-    },
-  },
-});
-
-export default config;
-```
-
-At runtime, services access configuration sections:
-
-```typescript
-// In a service class
-const ormConfig = await this.getConfig<Record<string, DbConfig>>("orm");
-const dbConfig = ormConfig.default;  // Access specific DB config by name
-```
-
-**Key points:**
-
-- Configuration sections can be nested objects with any structure
-- Environment variable substitution can be used in config values
-- Generated `dist/.config.json` files are not included in version control (add to `.gitignore`)
-- Client and server both support `configs`, but typically only servers expose configuration via `ctx.getConfig()`
-
-### Dependency Replacement (replaceDeps)
-
-Replace `node_modules` packages with local source directories via symlinks. Useful for local development of dependent packages across separate repositories.
-
-The key is a glob pattern to match packages in `node_modules`, and the value is the local source directory path. The `*` wildcard in the key is substituted into the `*` in the value.
-
-```typescript
-import type { SdConfigFn } from "@simplysm/sd-cli";
-
-const config: SdConfigFn = () => ({
-  packages: {
-    "my-app": { target: "client", server: "my-server" },
-  },
-  replaceDeps: {
-    // Replaces @simplysm/* packages in node_modules
-    // with symlinks to ../simplysm/packages/*/dist
-    "@simplysm/*": "../simplysm/packages/*",
-  },
-});
-
-export default config;
-```
-
-### postPublish Scripts
-
-You can define scripts to run after deployment completes. Supports environment variable substitution (`%VER%`, `%PROJECT%`). On script failure, only a warning is printed and execution continues.
-
-```typescript
-import type { SdConfigFn } from "@simplysm/sd-cli";
-
-const config: SdConfigFn = () => ({
-  packages: {
-    /* ... */
-  },
-  postPublish: [
-    {
-      type: "script",
-      cmd: "curl",
-      args: ["-X", "POST", "https://hooks.example.com/deploy?version=%VER%"],
-    },
-  ],
-});
-
-export default config;
-```
-
-### Capacitor Configuration (SdCapacitorConfig)
-
-Capacitor configuration for Android app builds in `client` target packages.
-
-```typescript
-"my-app": {
-  target: "client",
-  server: 3000,
-  capacitor: {
-    appId: "com.example.myapp",
-    appName: "My App",
-    icon: "resources/icon.png",          // App icon (relative to package directory)
-    debug: true,                          // Whether debug build
-    plugins: {                            // Capacitor plugins
-      "@capacitor/camera": true,
-      "@capacitor/storage": { group: "myGroup" },
-    },
-    platform: {
-      android: {
-        config: {                         // AndroidManifest.xml application attributes
-          requestLegacyExternalStorage: "true",
-        },
-        bundle: true,                     // AAB bundle build (APK if false)
-        sdkVersion: 33,                   // Android SDK version
-        permissions: [                    // Additional permissions
-          { name: "CAMERA" },
-          { name: "WRITE_EXTERNAL_STORAGE", maxSdkVersion: 29 },
-        ],
-        intentFilters: [                  // Intent Filters
-          { action: "android.intent.action.VIEW", category: "android.intent.category.DEFAULT" },
-        ],
-        sign: {                           // APK/AAB signing
-          keystore: "keystore.jks",
-          storePassword: "password",
-          alias: "key0",
-          password: "password",
-          keystoreType: "jks",              // Keystore type (optional, defaults to "jks")
-        },
-      },
-    },
-  },
-},
 ```
-
-### Electron Configuration (SdElectronConfig)
-
-Electron configuration for Windows desktop app builds in `client` target packages. Requires `src/electron-main.ts` entry point in the package directory.
-
-```typescript
-"my-app": {
-  target: "client",
-  server: 3000,
-  electron: {
-    appId: "com.example.myapp",           // Electron app ID (required)
-    portable: false,                       // true: portable .exe, false: NSIS installer
-    installerIcon: "resources/icon.ico",   // Installer icon (.ico, relative to package directory)
-    reinstallDependencies: ["better-sqlite3"], // npm packages to include (native modules etc.)
-    postInstallScript: "node scripts/setup.js", // npm postinstall script
-    nsisOptions: {},                       // NSIS options (when portable is false)
-    env: {                                 // Environment variables (accessible via process.env in electron-main.ts)
-      API_URL: "https://api.example.com",
-    },
-  },
-},
+npx sd-cli <command> [options]
 ```
 
-**How it works:**
-
-- **Initialize**: Creates `.electron/src/package.json`, runs `npm install`, rebuilds native modules with `electron-rebuild`
-- **Build**: Bundles `electron-main.ts` with esbuild, copies web assets, runs `electron-builder` for Windows
-- **Dev mode**: Bundles `electron-main.ts`, launches Electron pointing to Vite dev server URL
-
-### Server Externals & PM2 Configuration
-
-Server packages can configure external modules, package manager selection, and PM2 deployment settings.
-
-#### Externals
-
-Native modules (with `binding.gyp`) are automatically detected and externalized. You can also manually specify additional modules to exclude from the bundle:
-
-```typescript
-"my-server": {
-  target: "server",
-  externals: ["cpu-features", "ssh2"],  // Manually externalize these modules
-},
-```
-
-#### Package Manager Selection
-
-The `packageManager` field controls which Node.js version management tool is used in production deployment:
-
-```typescript
-"my-server": {
-  target: "server",
-  packageManager: "volta",  // Use Volta for Node.js version management
-},
-```
-
-**Supported package managers:**
-
-| Value | Behavior | Generated Files |
-|-------|----------|-----------------|
-| `"volta"` | Uses Volta for Node.js version management. PM2 config will execute `node` directly (Volta manages version via `package.json` engines field). | `package.json` includes `volta` field with Node.js version |
-| `"mise"` | Uses mise for Node.js version management. PM2 config will resolve interpreter path via `mise which node`. | `mise.toml` is copied to `dist/` with Node.js version from root `mise.toml` |
-| `undefined` | No version management tool. PM2 config will execute `node` directly from system PATH. | No additional version management files |
-
-**Examples:**
-
-```typescript
-// Using Volta
-"my-server": {
-  target: "server",
-  packageManager: "volta",
-  pm2: {
-    name: "my-app-server",
-  },
-},
-
-// Using mise
-"my-server": {
-  target: "server",
-  packageManager: "mise",
-  pm2: {
-    name: "my-app-server",
-  },
-},
-
-// No package manager (use system PATH node)
-"my-server": {
-  target: "server",
-  pm2: {
-    name: "my-app-server",
-  },
-},
-```
-
-#### PM2 Configuration
-
-When `pm2` is configured, `dist/pm2.config.cjs` is generated during production build for use with [PM2](https://pm2.keymetrics.io/) process manager:
-
-```typescript
-"my-server": {
-  target: "server",
-  packageManager: "mise",  // Optional: specify package manager
-  env: {
-    CUSTOM_VAR: "value",
-  },
-  pm2: {
-    name: "my-app-server",           // PM2 process name (optional)
-    ignoreWatchPaths: ["uploads"],   // Additional paths to ignore in PM2 watch (optional)
-  },
-},
-```
-
-**Generated `pm2.config.cjs` includes:**
-
-- Process name (from `pm2.name` or derived from package name)
-- Watch mode enabled with configurable ignore paths (`node_modules`, `www` + custom paths)
-- Node.js interpreter path (resolved via `mise which node` if `packageManager: "mise"`, otherwise `node` from PATH)
-- `--openssl-config=openssl.cnf` interpreter argument for legacy TLS support
-- Environment variables: `NODE_ENV=production`, `TZ=Asia/Seoul`, plus custom `env` values
-
-**Deployment workflow:**
-
-```bash
-# 1. Build the server
-sd-cli build my-server
-
-# 2. Copy dist/ to deployment server
-
-# 3. On the deployment server:
-cd /path/to/my-server/dist
-
-# If using mise, install mise and activate
-mise install  # Only needed if packageManager: "mise"
-
-# Install externalized dependencies
-npm install
-
-# Start with PM2
-pm2 start pm2.config.cjs
-```
-
-## Cache
-
-| Command       | Cache Path                                           | Description                                                        |
-| ------------- | ---------------------------------------------------- | ------------------------------------------------------------------ |
-| `lint`        | `.cache/eslint.cache`                                | ESLint cache                                                       |
-| `lint`        | `.cache/stylelint.cache`                             | Stylelint cache                                                    |
-| `typecheck`   | `packages/{pkg}/.cache/typecheck-{env}.tsbuildinfo`  | Incremental type-check info (`{env}` is `node` or `browser`)      |
-| `watch` (dts) | `packages/{pkg}/.cache/dts.tsbuildinfo`              | Incremental .d.ts build info                                       |
-
-To reset cache, delete the `.cache` directory:
-
-```bash
-# Delete all caches
-rm -rf .cache packages/*/.cache
-```
+Commands: `init`, `add client`, `add server`, `lint`, `typecheck`, `check`, `watch`, `dev`, `build`, `publish`, `replace-deps`, `device`
 
-## Caveats
+## Source Index
 
-- `sd.config.ts` is required for `watch`, `dev`, `build`, `publish`, and `device` commands. `typecheck` and `lint` work without a config file.
-- The `publish` command automatically increments version and performs Git commit/tag/push. Execution is rejected if there are uncommitted changes.
-- `publish --no-build` deploys already-built artifacts as-is, so use with caution.
-- Before using the `device` command, run `sd-cli dev` or `sd-cli watch` first to initialize the Capacitor project.
-- During build, `VER` (project version) and `DEV` (`"true"` or `"false"`) environment variables are automatically set.
+| Source | Exports | Description | Test |
+|--------|---------|-------------|------|
+| `src/sd-config.types.ts` | `BuildTarget`, `SdConfig`, `SdConfigFn`, `SdConfigParams`, `SdPackageConfig`, `SdBuildPackageConfig`, `SdClientPackageConfig`, `SdServerPackageConfig`, `SdScriptsPackageConfig`, `SdPublishConfig`, `SdLocalDirectoryPublishConfig`, `SdStoragePublishConfig`, `SdPostPublishScriptConfig`, `SdCapacitorConfig`, `SdCapacitorAndroidConfig`, `SdCapacitorSignConfig`, `SdCapacitorPermission`, `SdCapacitorIntentFilter`, `SdElectronConfig` | All TypeScript types for `sd.config.ts` (packages, publish, Capacitor, Electron) | - |
+| `src/utils/vite-config.ts` | `ViteConfigOptions`, `createViteConfig` | Generates a Vite config for SolidJS + Tailwind CSS client packages | - |
 
 ## License