@laphilosophia/steady-watch 2.0.3 → 2.1.0

package/README.md

@@ -39,12 +39,19 @@ Example `steady-watch.config.json`:
 {
   "pattern": "src/**/*.ts",
   "cmd": "npm run build",
+  "start": "node dist/server.js",
+  "restartOnSuccess": true,
+  "restartOnChange": false,
+  "initialRun": true,
   "delay": 300,
   "verbose": false,
   "quiet": false,
   "ignore": ["*.test.ts"],
   "ext": [".ts", ".tsx"],
+  "gitChanged": false,
+  "gitBase": "HEAD",
   "killTimeout": 10000,
+  "restartDelay": 0,
   "retry": 3,
   "hash": "sha256",
   "mtimeOnly": false,
@@ -71,14 +78,22 @@ sw "src/**/*.ts" -c "npm run build"
 | Option | Description | Default |
 |--------|-------------|---------|
 | `files` | Glob pattern to watch (e.g., `"src/**/*.ts"`) | *required* |
-| `-c, --cmd <command>` | Command(s) to execute on change (supports `&&`) | *required* |
+| `-c, --cmd <command>` | Short lifecycle command to execute on change (supports `&&`) | *required unless using `--start --restart-on-change`* |
+| `--start <command>` | Long-running process command to start or restart | *none* |
+| `--restart-on-success` | Restart `--start` only when `--cmd` exits with code `0` | `false` |
+| `--restart-on-change` | Restart `--start` directly on change when no `--cmd` is configured | `false` |
+| `--initial-run` | Run the lifecycle when the watcher starts | `true` when `--start` is used |
+| `--no-initial-run` | Wait for the first file change before running the lifecycle | `false` |
 | `-d, --delay <ms>` | Debounce delay in milliseconds | `300` |
 | `-v, --verbose` | Show hash calculations and file indexing | `false` |
 | `-q, --quiet` | Minimize output | `false` |
 | `--ignore <patterns>` | Additional ignore patterns (comma-separated) | `node_modules, .git, dist, build` |
 | `--ext <extensions>` | Filter by file extensions (e.g., `.ts,.tsx`) | *none* |
+| `--git-changed` | Only trigger for files changed from the git base ref | `false` |
+| `--git-base <ref>` | Git base ref for `--git-changed` | `HEAD` |
 | `--config <path>` | Path to config file | auto-detect |
-| `--kill-timeout <ms>` | Force kill process after timeout (0 = disabled) | `0` |
+| `--kill-timeout <ms>` | Force kill lifecycle commands and graceful process shutdown after timeout | `5000` with `--start`, otherwise `0` |
+| `--restart-delay <ms>` | Delay between stopping and starting `--start` | `0` |
 | `--retry <count>` | Retry failed command (0 = disabled) | `0` |
 | `--hash <algo>` | Hash algorithm (md5, sha1, sha256) | `md5` |
 | `--no-hash` | Use mtime only instead of content hash (fastest) | `false` |
@@ -104,6 +119,12 @@ sw "src/**/*.ts" -c "npm run build" -q
 # Filter by extensions
 sw "src/**/*" -c "npm run build" --ext .ts,.tsx
 
+# Only trigger for files changed from HEAD, including staged, unstaged, and untracked files
+sw "src/**/*" -c "npm test" --git-changed
+
+# Compare against a specific base ref
+sw "src/**/*" -c "npm test" --git-changed --git-base main
+
 # Custom ignore patterns
 sw "src/**/*" -c "npm run build" --ignore "*.test.ts,tmp/*"
 
@@ -116,10 +137,21 @@ sw "src/**/*.ts" -c "npm run build" --retry 3
 # Multiple commands (using &&)
 sw "src/**/*.ts" -c "npm run build && npm run test"
 
+# Build first, then start or restart the server only after success
+sw "src/**/*.ts" -c "npm run build" --start "node dist/server.js" --restart-on-success
+
+# Restart a server directly on change without a build command
+sw "src/**/*" --start "node server.js" --restart-on-change
+
+# Keep the old server running when build or tests fail
+sw "src/**/*" -c "npm run build && npm test" --start "node dist/server.js" --restart-on-success --kill-timeout 10000
+
 # Use config file
 sw --config .steady-watchrc
 ```
 
+When `--cmd` and `--start` are used together, `--cmd` is treated as a short lifecycle command. The running `--start` process is only replaced after a successful lifecycle command. If the lifecycle command fails, the current long-running process is preserved. File changes that arrive while a lifecycle cycle is already running are coalesced into one additional cycle.
+
 ## Programmatic API
 
 You can also use Steady Watch as a library in your Node.js code:
@@ -131,6 +163,8 @@ import { SteadyWatcher, steadyWatch } from '@laphilosophia/steady-watch';
 const watcher = steadyWatch({
   pattern: 'src/**/*.ts',
   cmd: 'npm run build',
+  start: 'node dist/server.js',
+  restartOnSuccess: true,
   delay: 300
 });
 
@@ -138,6 +172,8 @@ const watcher = steadyWatch({
 const watcher = new SteadyWatcher({
   pattern: 'src/**/*.ts',
   cmd: 'npm run build',
+  start: 'node dist/server.js',
+  restartOnSuccess: true,
   delay: 300
 });
 
@@ -145,6 +181,8 @@ const watcher = new SteadyWatcher({
 watcher.on('ready', () => console.log('Ready!'));
 watcher.on('change', (file) => console.log(`Changed: ${file}`));
 watcher.on('trigger', (cmd) => console.log(`Running: ${cmd}`));
+watcher.on('start', (cmd, pid) => console.log(`Started: ${cmd} (${pid})`));
+watcher.on('startExit', (code, signal, expected) => console.log({ code, signal, expected }));
 watcher.on('done', (duration) => console.log(`Done in ${duration}s`));
 watcher.on('fail', (code) => console.log(`Failed: ${code}`));
 
@@ -153,10 +191,45 @@ await watcher.start();
 // Get tracked files
 console.log(watcher.getTrackedFiles());
 
+// Lifecycle command state and long-running process state are separate
+console.log(watcher.isCurrentlyRunning());
+console.log(watcher.isStartedProcessRunning());
+
 // Stop watching
 await watcher.close();
 ```
 
+Lifecycle hooks are available through the programmatic API. They are not loaded from JSON config files or CLI flags.
+
+```typescript
+const watcher = steadyWatch({
+  pattern: 'src/**/*.ts',
+  cmd: 'pnpm build',
+  start: 'node dist/src/app/main.js',
+  restartOnSuccess: true,
+  hooks: {
+    beforeCommand: async () => {
+      await validateWorkspace();
+    },
+    afterCommand: async ({ exitCode }) => {
+      if (exitCode !== 0) return;
+      await validateBuildArtifacts();
+    },
+    beforeStart: async () => {
+      await validateRuntimeConfig();
+    },
+    afterStart: async ({ pid }) => {
+      await warmupProcess(pid);
+    },
+    onSkip: ({ skipReason, file }) => {
+      console.log(`Skipped ${file}: ${skipReason}`);
+    }
+  }
+});
+```
+
+`beforeCommand`, `afterCommand`, `beforeStop`, and `beforeStart` are lifecycle gates. If they throw, the active cycle is failed and the next phase is not run. During restart, `beforeStart` runs before `beforeStop`, so runtime validation can fail without stopping the current process. `afterStop`, `afterStart`, and `onSkip` are notification hooks; failures are reported through the `hookError` event without changing the lifecycle result.
+
 ## Themes
 
 - `default` - Full color output
@@ -169,6 +242,7 @@ await watcher.close();
 - ⏱️ **Debouncing** — Batches rapid changes into single rebuilds
 - 🚀 **Process Management** — Won't start new build while previous is running
 - 🚫 **Smart Ignores** — Auto-ignores `node_modules`, `.git`, `dist`, `build`
+- 🧩 **Lifecycle Hooks** — Integrate custom checks, validation, cleanup, and warmup in code
 - 🎨 **Pretty Output** — Color-coded, timestamped logs
 
 ## Output Example

package/bin/steady-watch

@@ -2,4 +2,4 @@
 
 const path = require('path');
 const distPath = path.join(path.dirname(process.argv[1]), '..', 'dist', 'index.js');
-require(distPath);
+require(distPath).runCli();

package/dist/index.d.mts

@@ -2,13 +2,28 @@ import { EventEmitter } from 'events';
 
 interface SteadyWatchOptions {
     pattern: string;
-    cmd: string;
+    cmd?: string;
+    start?: string;
+    restartOnSuccess?: boolean;
+    restartOnChange?: boolean;
+    initialRun?: boolean;
+    hooks?: SteadyWatchHooks;
+    beforeCommand?: SteadyWatchHook;
+    afterCommand?: SteadyWatchHook;
+    beforeStop?: SteadyWatchHook;
+    afterStop?: SteadyWatchHook;
+    beforeStart?: SteadyWatchHook;
+    afterStart?: SteadyWatchHook;
+    onSkip?: SteadyWatchHook;
     delay?: number;
     verbose?: boolean;
     quiet?: boolean;
     ignore?: (string | RegExp)[];
     ext?: string[];
+    gitChanged?: boolean;
+    gitBase?: string;
     killTimeout?: number;
+    restartDelay?: number;
     retry?: number;
     hash?: HashAlgorithm;
     mtimeOnly?: boolean;
@@ -21,6 +36,11 @@ interface SteadyWatchEvents {
     ready: () => void;
     change: (file: string) => void;
     trigger: (cmd: string) => void;
+    start: (cmd: string, pid?: number) => void;
+    startExit: (exitCode: number | null, signal?: string, expected?: boolean) => void;
+    restart: (cmd: string) => void;
+    stop: (cmd: string, signal?: string) => void;
+    hookError: (hook: keyof SteadyWatchHooks, error: Error) => void;
     done: (duration: number) => void;
     fail: (exitCode: number | null, signal?: string) => void;
     error: (error: Error) => void;
@@ -28,15 +48,48 @@ interface SteadyWatchEvents {
 }
 type HashAlgorithm = 'md5' | 'sha1' | 'sha256';
 type ThemeName = 'default' | 'minimal' | 'none';
+type SteadyWatchHookPhase = 'beforeCommand' | 'afterCommand' | 'beforeStop' | 'afterStop' | 'beforeStart' | 'afterStart' | 'onSkip';
+interface SteadyWatchHookContext {
+    phase: SteadyWatchHookPhase;
+    reason?: string;
+    command?: string;
+    startCommand?: string;
+    file?: string;
+    skipReason?: string;
+    attempt?: number;
+    exitCode?: number | null;
+    signal?: string | null;
+    duration?: number;
+    pid?: number;
+    timestamp: Date;
+}
+type SteadyWatchHook = (context: Readonly<SteadyWatchHookContext>) => void | Promise<void>;
+interface SteadyWatchHooks {
+    beforeCommand?: SteadyWatchHook;
+    afterCommand?: SteadyWatchHook;
+    beforeStop?: SteadyWatchHook;
+    afterStop?: SteadyWatchHook;
+    beforeStart?: SteadyWatchHook;
+    afterStart?: SteadyWatchHook;
+    onSkip?: SteadyWatchHook;
+}
 interface NormalizedOptions {
     pattern: string;
     cmd: string;
+    start: string;
+    restartOnSuccess: boolean;
+    restartOnChange: boolean;
+    initialRun: boolean;
+    hooks: SteadyWatchHooks;
     delay: number;
     verbose: boolean;
     quiet: boolean;
     ignore: (string | RegExp)[];
     ext: string[];
+    gitChanged: boolean;
+    gitBase: string;
     killTimeout: number;
+    restartDelay: number;
     retry: number;
     hash: HashAlgorithm;
     mtimeOnly: boolean;
@@ -50,15 +103,22 @@ interface ValidationResult {
 }
 interface CliOptions {
     cmd?: string;
+    start?: string;
+    restartOnSuccess?: boolean;
+    restartOnChange?: boolean;
+    initialRun?: boolean;
     config?: string;
     delay?: string;
     verbose?: boolean;
     quiet?: boolean;
     ignore?: string;
     ext?: string;
+    gitChanged?: boolean;
+    gitBase?: string;
     killTimeout?: string;
+    restartDelay?: string;
     retry?: string;
-    hash?: string;
+    hash?: string | boolean;
     noHash?: boolean;
     clear?: boolean;
     json?: boolean;
@@ -85,13 +145,19 @@ declare function getTheme(name: ThemeName): Theme;
 declare class SteadyWatcher extends EventEmitter {
     private options;
     private watcher;
+    private watcherReady;
     private fileHashes;
+    private gitChangedFiles;
     private timeout;
-    private isRunning;
-    private activeProcess;
-    private killTimer;
+    private cycleRunning;
+    private pendingCycle;
+    private lifecycleProcess;
+    private lifecycleKillTimer;
+    private startedProcess;
+    private stoppingStartedProcess;
     private retryCount;
     private disposed;
+    private closePromise;
     private t;
     private static readonly DEFAULT_IGNORE;
     private static readonly VALID_HASH_ALGORITHMS;
@@ -102,21 +168,55 @@ declare class SteadyWatcher extends EventEmitter {
     validate(): ValidationResult;
     private getEffectivePattern;
     private getHash;
+    private normalizeGitPath;
+    private runGit;
+    private refreshGitChangedFiles;
+    private isGitChangedFile;
     private log;
     private logVerbose;
     private logJson;
     private timestamp;
+    private runHook;
+    private notifyHook;
+    private sleep;
     private parseCommand;
-    private runCommand;
+    private commandNeedsShell;
+    private resolveWindowsCommand;
+    private shouldUseShell;
+    private spawnCommand;
+    private runTaskkill;
+    private forceKillProcess;
+    private terminateProcess;
+    private runSingleCommand;
+    private runCommandWithRetry;
+    private stopStartedProcess;
+    private startLongRunningProcess;
+    private restartStartedProcess;
+    private runCycle;
+    private requestCycle;
+    private skip;
+    private scheduleFileCycle;
     private handleFileChange;
     start(): Promise<void>;
+    private handleFileAdd;
+    private handleFileUnlink;
     close(): Promise<void>;
+    private closeInternal;
     getTrackedFiles(): string[];
     isCurrentlyRunning(): boolean;
+    isStartedProcessRunning(): boolean;
     isDisposed(): boolean;
 }
 declare function steadyWatch(options: SteadyWatchOptions): SteadyWatcher;
 
+declare const CLI_VERSION = "2.1.0";
+declare function loadConfig(configPath?: string): Record<string, unknown>;
+declare function mergeOptions(cliArgs: CliArgs, cliOpts: CliOptions, config: Record<string, unknown>): SteadyWatchOptions;
+declare function parseCliArgs(argv?: string[]): {
+    args: CliArgs;
+    opts: CliOptions;
+};
+
 declare function runCli(): void;
 
-export { type ChalkStyle, type CliArgs, type CliOptions, type HashAlgorithm, type NormalizedOptions, type SteadyWatchEvents, type SteadyWatchOptions, SteadyWatcher, type Theme, type ThemeName, type ValidationResult, getTheme, runCli, steadyWatch, themes };
+export { CLI_VERSION, type ChalkStyle, type CliArgs, type CliOptions, type HashAlgorithm, type NormalizedOptions, type SteadyWatchEvents, type SteadyWatchHook, type SteadyWatchHookContext, type SteadyWatchHookPhase, type SteadyWatchHooks, type SteadyWatchOptions, SteadyWatcher, type Theme, type ThemeName, type ValidationResult, getTheme, loadConfig, mergeOptions, parseCliArgs, runCli, steadyWatch, themes };

package/dist/index.d.ts

@@ -2,13 +2,28 @@ import { EventEmitter } from 'events';
 
 interface SteadyWatchOptions {
     pattern: string;
-    cmd: string;
+    cmd?: string;
+    start?: string;
+    restartOnSuccess?: boolean;
+    restartOnChange?: boolean;
+    initialRun?: boolean;
+    hooks?: SteadyWatchHooks;
+    beforeCommand?: SteadyWatchHook;
+    afterCommand?: SteadyWatchHook;
+    beforeStop?: SteadyWatchHook;
+    afterStop?: SteadyWatchHook;
+    beforeStart?: SteadyWatchHook;
+    afterStart?: SteadyWatchHook;
+    onSkip?: SteadyWatchHook;
     delay?: number;
     verbose?: boolean;
     quiet?: boolean;
     ignore?: (string | RegExp)[];
     ext?: string[];
+    gitChanged?: boolean;
+    gitBase?: string;
     killTimeout?: number;
+    restartDelay?: number;
     retry?: number;
     hash?: HashAlgorithm;
     mtimeOnly?: boolean;
@@ -21,6 +36,11 @@ interface SteadyWatchEvents {
     ready: () => void;
     change: (file: string) => void;
     trigger: (cmd: string) => void;
+    start: (cmd: string, pid?: number) => void;
+    startExit: (exitCode: number | null, signal?: string, expected?: boolean) => void;
+    restart: (cmd: string) => void;
+    stop: (cmd: string, signal?: string) => void;
+    hookError: (hook: keyof SteadyWatchHooks, error: Error) => void;
     done: (duration: number) => void;
     fail: (exitCode: number | null, signal?: string) => void;
     error: (error: Error) => void;
@@ -28,15 +48,48 @@ interface SteadyWatchEvents {
 }
 type HashAlgorithm = 'md5' | 'sha1' | 'sha256';
 type ThemeName = 'default' | 'minimal' | 'none';
+type SteadyWatchHookPhase = 'beforeCommand' | 'afterCommand' | 'beforeStop' | 'afterStop' | 'beforeStart' | 'afterStart' | 'onSkip';
+interface SteadyWatchHookContext {
+    phase: SteadyWatchHookPhase;
+    reason?: string;
+    command?: string;
+    startCommand?: string;
+    file?: string;
+    skipReason?: string;
+    attempt?: number;
+    exitCode?: number | null;
+    signal?: string | null;
+    duration?: number;
+    pid?: number;
+    timestamp: Date;
+}
+type SteadyWatchHook = (context: Readonly<SteadyWatchHookContext>) => void | Promise<void>;
+interface SteadyWatchHooks {
+    beforeCommand?: SteadyWatchHook;
+    afterCommand?: SteadyWatchHook;
+    beforeStop?: SteadyWatchHook;
+    afterStop?: SteadyWatchHook;
+    beforeStart?: SteadyWatchHook;
+    afterStart?: SteadyWatchHook;
+    onSkip?: SteadyWatchHook;
+}
 interface NormalizedOptions {
     pattern: string;
     cmd: string;
+    start: string;
+    restartOnSuccess: boolean;
+    restartOnChange: boolean;
+    initialRun: boolean;
+    hooks: SteadyWatchHooks;
     delay: number;
     verbose: boolean;
     quiet: boolean;
     ignore: (string | RegExp)[];
     ext: string[];
+    gitChanged: boolean;
+    gitBase: string;
     killTimeout: number;
+    restartDelay: number;
     retry: number;
     hash: HashAlgorithm;
     mtimeOnly: boolean;
@@ -50,15 +103,22 @@ interface ValidationResult {
 }
 interface CliOptions {
     cmd?: string;
+    start?: string;
+    restartOnSuccess?: boolean;
+    restartOnChange?: boolean;
+    initialRun?: boolean;
     config?: string;
     delay?: string;
     verbose?: boolean;
     quiet?: boolean;
     ignore?: string;
     ext?: string;
+    gitChanged?: boolean;
+    gitBase?: string;
     killTimeout?: string;
+    restartDelay?: string;
     retry?: string;
-    hash?: string;
+    hash?: string | boolean;
     noHash?: boolean;
     clear?: boolean;
     json?: boolean;
@@ -85,13 +145,19 @@ declare function getTheme(name: ThemeName): Theme;
 declare class SteadyWatcher extends EventEmitter {
     private options;
     private watcher;
+    private watcherReady;
     private fileHashes;
+    private gitChangedFiles;
     private timeout;
-    private isRunning;
-    private activeProcess;
-    private killTimer;
+    private cycleRunning;
+    private pendingCycle;
+    private lifecycleProcess;
+    private lifecycleKillTimer;
+    private startedProcess;
+    private stoppingStartedProcess;
     private retryCount;
     private disposed;
+    private closePromise;
     private t;
     private static readonly DEFAULT_IGNORE;
     private static readonly VALID_HASH_ALGORITHMS;
@@ -102,21 +168,55 @@ declare class SteadyWatcher extends EventEmitter {
     validate(): ValidationResult;
     private getEffectivePattern;
     private getHash;
+    private normalizeGitPath;
+    private runGit;
+    private refreshGitChangedFiles;
+    private isGitChangedFile;
     private log;
     private logVerbose;
     private logJson;
     private timestamp;
+    private runHook;
+    private notifyHook;
+    private sleep;
     private parseCommand;
-    private runCommand;
+    private commandNeedsShell;
+    private resolveWindowsCommand;
+    private shouldUseShell;
+    private spawnCommand;
+    private runTaskkill;
+    private forceKillProcess;
+    private terminateProcess;
+    private runSingleCommand;
+    private runCommandWithRetry;
+    private stopStartedProcess;
+    private startLongRunningProcess;
+    private restartStartedProcess;
+    private runCycle;
+    private requestCycle;
+    private skip;
+    private scheduleFileCycle;
     private handleFileChange;
     start(): Promise<void>;
+    private handleFileAdd;
+    private handleFileUnlink;
     close(): Promise<void>;
+    private closeInternal;
     getTrackedFiles(): string[];
     isCurrentlyRunning(): boolean;
+    isStartedProcessRunning(): boolean;
     isDisposed(): boolean;
 }
 declare function steadyWatch(options: SteadyWatchOptions): SteadyWatcher;
 
+declare const CLI_VERSION = "2.1.0";
+declare function loadConfig(configPath?: string): Record<string, unknown>;
+declare function mergeOptions(cliArgs: CliArgs, cliOpts: CliOptions, config: Record<string, unknown>): SteadyWatchOptions;
+declare function parseCliArgs(argv?: string[]): {
+    args: CliArgs;
+    opts: CliOptions;
+};
+
 declare function runCli(): void;
 
-export { type ChalkStyle, type CliArgs, type CliOptions, type HashAlgorithm, type NormalizedOptions, type SteadyWatchEvents, type SteadyWatchOptions, SteadyWatcher, type Theme, type ThemeName, type ValidationResult, getTheme, runCli, steadyWatch, themes };
+export { CLI_VERSION, type ChalkStyle, type CliArgs, type CliOptions, type HashAlgorithm, type NormalizedOptions, type SteadyWatchEvents, type SteadyWatchHook, type SteadyWatchHookContext, type SteadyWatchHookPhase, type SteadyWatchHooks, type SteadyWatchOptions, SteadyWatcher, type Theme, type ThemeName, type ValidationResult, getTheme, loadConfig, mergeOptions, parseCliArgs, runCli, steadyWatch, themes };