@laphilosophia/steady-watch 1.0.1 → 2.0.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Erdem Arslan
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Erdem Arslan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -8,6 +8,7 @@
 ## The Problem
 
 Standard file watchers trigger on every save, including:
+
 - Editor auto-saves that don't change content
 - IDE temp file operations
 - Multiple rapid saves
@@ -24,6 +25,35 @@ This leads to unnecessary rebuilds, wasted CPU cycles, and noisy logs.
 npm install -g @laphilosophia/steady-watch
 ```
 
+## Configuration File
+
+You can also use a config file instead of CLI options. Supported files:
+
+- `.steady-watchrc`
+- `.steady-watchrc.json`
+- `steady-watch.config.json`
+
+Example `steady-watch.config.json`:
+
+```json
+{
+  "pattern": "src/**/*.ts",
+  "cmd": "npm run build",
+  "delay": 300,
+  "verbose": false,
+  "quiet": false,
+  "ignore": ["*.test.ts"],
+  "ext": [".ts", ".tsx"],
+  "killTimeout": 10000,
+  "retry": 3,
+  "hash": "sha256",
+  "mtimeOnly": false,
+  "clearScreen": false,
+  "json": false,
+  "theme": "default"
+}
+```
+
 ## Usage
 
 ```bash
@@ -40,9 +70,21 @@ sw "src/**/*.ts" -c "npm run build"
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `-c, --cmd <command>` | Command to execute on change | *required* |
+| `files` | Glob pattern to watch (e.g., `"src/**/*.ts"`) | *required* |
+| `-c, --cmd <command>` | Command(s) to execute on change (supports `&&`) | *required* |
 | `-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* |
+| `--config <path>` | Path to config file | auto-detect |
+| `--kill-timeout <ms>` | Force kill process after timeout (0 = disabled) | `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` |
+| `--clear` | Clear screen on each trigger | `false` |
+| `--json` | Output in JSON format | `false` |
+| `--theme <theme>` | Color theme (default, minimal, none) | `default` |
 
 ### Examples
 
@@ -55,8 +97,72 @@ sw "src/**/*.{ts,tsx}" -c "npm test" -d 500
 
 # Verbose mode to see what's happening
 sw "lib/**/*.js" -c "node build.js" -v
+
+# Quiet mode (minimal output)
+sw "src/**/*.ts" -c "npm run build" -q
+
+# Filter by extensions
+sw "src/**/*" -c "npm run build" --ext .ts,.tsx
+
+# Custom ignore patterns
+sw "src/**/*" -c "npm run build" --ignore "*.test.ts,tmp/*"
+
+# Kill stuck processes after 10 seconds
+sw "src/**/*.ts" -c "npm run build" --kill-timeout 10000
+
+# Retry failed commands up to 3 times
+sw "src/**/*.ts" -c "npm run build" --retry 3
+
+# Multiple commands (using &&)
+sw "src/**/*.ts" -c "npm run build && npm run test"
+
+# Use config file
+sw --config .steady-watchrc
+```
+
+## Programmatic API
+
+You can also use Steady Watch as a library in your Node.js code:
+
+```typescript
+import { SteadyWatcher, steadyWatch } from '@laphilosophia/steady-watch';
+
+// Using the function
+const watcher = steadyWatch({
+  pattern: 'src/**/*.ts',
+  cmd: 'npm run build',
+  delay: 300
+});
+
+// Or using the class
+const watcher = new SteadyWatcher({
+  pattern: 'src/**/*.ts',
+  cmd: 'npm run build',
+  delay: 300
+});
+
+// Listen to events
+watcher.on('ready', () => console.log('Ready!'));
+watcher.on('change', (file) => console.log(`Changed: ${file}`));
+watcher.on('trigger', (cmd) => console.log(`Running: ${cmd}`));
+watcher.on('done', (duration) => console.log(`Done in ${duration}s`));
+watcher.on('fail', (code) => console.log(`Failed: ${code}`));
+
+await watcher.start();
+
+// Get tracked files
+console.log(watcher.getTrackedFiles());
+
+// Stop watching
+await watcher.close();
 ```
 
+## Themes
+
+- `default` - Full color output
+- `minimal` - Monochrome output
+- `none` - No colors at all
+
 ## Features
 
 - 🎯 **Content Hashing** — Only triggers when file content actually changes

package/bin/steady-watch

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import './index.js';

package/dist/index.d.mts

@@ -0,0 +1,122 @@
+import { EventEmitter } from 'events';
+
+interface SteadyWatchOptions {
+    pattern: string;
+    cmd: string;
+    delay?: number;
+    verbose?: boolean;
+    quiet?: boolean;
+    ignore?: (string | RegExp)[];
+    ext?: string[];
+    killTimeout?: number;
+    retry?: number;
+    hash?: HashAlgorithm;
+    mtimeOnly?: boolean;
+    clearScreen?: boolean;
+    json?: boolean;
+    theme?: ThemeName;
+}
+
+interface SteadyWatchEvents {
+    ready: () => void;
+    change: (file: string) => void;
+    trigger: (cmd: string) => void;
+    done: (duration: number) => void;
+    fail: (exitCode: number | null, signal?: string) => void;
+    error: (error: Error) => void;
+    skip: (reason: string, file?: string) => void;
+}
+type HashAlgorithm = 'md5' | 'sha1' | 'sha256';
+type ThemeName = 'default' | 'minimal' | 'none';
+interface NormalizedOptions {
+    pattern: string;
+    cmd: string;
+    delay: number;
+    verbose: boolean;
+    quiet: boolean;
+    ignore: (string | RegExp)[];
+    ext: string[];
+    killTimeout: number;
+    retry: number;
+    hash: HashAlgorithm;
+    mtimeOnly: boolean;
+    clearScreen: boolean;
+    json: boolean;
+    theme: ThemeName;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+interface CliOptions {
+    cmd?: string;
+    config?: string;
+    delay?: string;
+    verbose?: boolean;
+    quiet?: boolean;
+    ignore?: string;
+    ext?: string;
+    killTimeout?: string;
+    retry?: string;
+    hash?: string;
+    noHash?: boolean;
+    clear?: boolean;
+    json?: boolean;
+    theme?: string;
+}
+interface CliArgs {
+    pattern: string;
+}
+
+type ChalkStyle = (s: string) => string;
+interface Theme {
+    blue: ChalkStyle;
+    green: ChalkStyle;
+    yellow: ChalkStyle;
+    red: ChalkStyle;
+    cyan: ChalkStyle;
+    gray: ChalkStyle;
+    dim: ChalkStyle;
+    bold: ChalkStyle;
+}
+declare const themes: Record<ThemeName, Theme>;
+declare function getTheme(name: ThemeName): Theme;
+
+declare class SteadyWatcher extends EventEmitter {
+    private options;
+    private watcher;
+    private fileHashes;
+    private timeout;
+    private isRunning;
+    private activeProcess;
+    private killTimer;
+    private retryCount;
+    private disposed;
+    private t;
+    private static readonly DEFAULT_IGNORE;
+    private static readonly VALID_HASH_ALGORITHMS;
+    private static readonly VALID_THEMES;
+    constructor(options: SteadyWatchOptions);
+    private normalizeOptions;
+    private normalizeIgnorePatterns;
+    validate(): ValidationResult;
+    private getEffectivePattern;
+    private getHash;
+    private log;
+    private logVerbose;
+    private logJson;
+    private timestamp;
+    private parseCommand;
+    private runCommand;
+    private handleFileChange;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    getTrackedFiles(): string[];
+    isCurrentlyRunning(): boolean;
+    isDisposed(): boolean;
+}
+declare function steadyWatch(options: SteadyWatchOptions): SteadyWatcher;
+
+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 };

package/dist/index.d.ts

@@ -0,0 +1,122 @@
+import { EventEmitter } from 'events';
+
+interface SteadyWatchOptions {
+    pattern: string;
+    cmd: string;
+    delay?: number;
+    verbose?: boolean;
+    quiet?: boolean;
+    ignore?: (string | RegExp)[];
+    ext?: string[];
+    killTimeout?: number;
+    retry?: number;
+    hash?: HashAlgorithm;
+    mtimeOnly?: boolean;
+    clearScreen?: boolean;
+    json?: boolean;
+    theme?: ThemeName;
+}
+
+interface SteadyWatchEvents {
+    ready: () => void;
+    change: (file: string) => void;
+    trigger: (cmd: string) => void;
+    done: (duration: number) => void;
+    fail: (exitCode: number | null, signal?: string) => void;
+    error: (error: Error) => void;
+    skip: (reason: string, file?: string) => void;
+}
+type HashAlgorithm = 'md5' | 'sha1' | 'sha256';
+type ThemeName = 'default' | 'minimal' | 'none';
+interface NormalizedOptions {
+    pattern: string;
+    cmd: string;
+    delay: number;
+    verbose: boolean;
+    quiet: boolean;
+    ignore: (string | RegExp)[];
+    ext: string[];
+    killTimeout: number;
+    retry: number;
+    hash: HashAlgorithm;
+    mtimeOnly: boolean;
+    clearScreen: boolean;
+    json: boolean;
+    theme: ThemeName;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+interface CliOptions {
+    cmd?: string;
+    config?: string;
+    delay?: string;
+    verbose?: boolean;
+    quiet?: boolean;
+    ignore?: string;
+    ext?: string;
+    killTimeout?: string;
+    retry?: string;
+    hash?: string;
+    noHash?: boolean;
+    clear?: boolean;
+    json?: boolean;
+    theme?: string;
+}
+interface CliArgs {
+    pattern: string;
+}
+
+type ChalkStyle = (s: string) => string;
+interface Theme {
+    blue: ChalkStyle;
+    green: ChalkStyle;
+    yellow: ChalkStyle;
+    red: ChalkStyle;
+    cyan: ChalkStyle;
+    gray: ChalkStyle;
+    dim: ChalkStyle;
+    bold: ChalkStyle;
+}
+declare const themes: Record<ThemeName, Theme>;
+declare function getTheme(name: ThemeName): Theme;
+
+declare class SteadyWatcher extends EventEmitter {
+    private options;
+    private watcher;
+    private fileHashes;
+    private timeout;
+    private isRunning;
+    private activeProcess;
+    private killTimer;
+    private retryCount;
+    private disposed;
+    private t;
+    private static readonly DEFAULT_IGNORE;
+    private static readonly VALID_HASH_ALGORITHMS;
+    private static readonly VALID_THEMES;
+    constructor(options: SteadyWatchOptions);
+    private normalizeOptions;
+    private normalizeIgnorePatterns;
+    validate(): ValidationResult;
+    private getEffectivePattern;
+    private getHash;
+    private log;
+    private logVerbose;
+    private logJson;
+    private timestamp;
+    private parseCommand;
+    private runCommand;
+    private handleFileChange;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    getTrackedFiles(): string[];
+    isCurrentlyRunning(): boolean;
+    isDisposed(): boolean;
+}
+declare function steadyWatch(options: SteadyWatchOptions): SteadyWatcher;
+
+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 };