@laphilosophia/steady-watch 2.0.2 → 2.1.0

package/dist/index.js

@@ -30,8 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CLI_VERSION: () => CLI_VERSION,
   SteadyWatcher: () => SteadyWatcher,
   getTheme: () => getTheme,
+  loadConfig: () => loadConfig,
+  mergeOptions: () => mergeOptions,
+  parseCliArgs: () => parseCliArgs,
   runCli: () => runCli,
   steadyWatch: () => steadyWatch,
   themes: () => themes
@@ -87,13 +91,19 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
   constructor(options) {
     super();
     this.watcher = null;
+    this.watcherReady = false;
     this.fileHashes = /* @__PURE__ */ new Map();
+    this.gitChangedFiles = /* @__PURE__ */ new Set();
     this.timeout = null;
-    this.isRunning = false;
-    this.activeProcess = null;
-    this.killTimer = null;
+    this.cycleRunning = false;
+    this.pendingCycle = false;
+    this.lifecycleProcess = null;
+    this.lifecycleKillTimer = null;
+    this.startedProcess = null;
+    this.stoppingStartedProcess = null;
     this.retryCount = 0;
     this.disposed = false;
+    this.closePromise = null;
     this.options = this.normalizeOptions(options);
     this.t = getTheme(this.options.theme);
   }
@@ -104,15 +114,34 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
       ..._SteadyWatcher.DEFAULT_IGNORE,
       ...this.normalizeIgnorePatterns(options.ignore || [])
     ];
+    const start = options.start || "";
+    const hooks = {
+      ...options.hooks || {},
+      beforeCommand: options.beforeCommand || options.hooks?.beforeCommand,
+      afterCommand: options.afterCommand || options.hooks?.afterCommand,
+      beforeStop: options.beforeStop || options.hooks?.beforeStop,
+      afterStop: options.afterStop || options.hooks?.afterStop,
+      beforeStart: options.beforeStart || options.hooks?.beforeStart,
+      afterStart: options.afterStart || options.hooks?.afterStart,
+      onSkip: options.onSkip || options.hooks?.onSkip
+    };
     return {
       pattern: options.pattern,
-      cmd: options.cmd,
+      cmd: options.cmd || "",
+      start,
+      restartOnSuccess: options.restartOnSuccess ?? false,
+      restartOnChange: options.restartOnChange ?? false,
+      initialRun: options.initialRun ?? Boolean(start),
+      hooks,
       delay: Math.max(0, options.delay ?? 300),
       verbose: options.verbose ?? false,
       quiet: options.quiet ?? false,
       ignore: mergedIgnore,
       ext: options.ext || [],
-      killTimeout: Math.max(0, options.killTimeout ?? 0),
+      gitChanged: options.gitChanged ?? false,
+      gitBase: options.gitBase || "HEAD",
+      killTimeout: Math.max(0, options.killTimeout ?? (start ? 5e3 : 0)),
+      restartDelay: Math.max(0, options.restartDelay ?? 0),
       retry: Math.max(0, options.retry ?? 0),
       hash,
       mtimeOnly: options.mtimeOnly ?? false,
@@ -136,8 +165,23 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
     if (!this.options.pattern) {
       errors.push("Pattern is required");
     }
-    if (!this.options.cmd) {
-      errors.push("Command is required");
+    if (!this.options.cmd && !this.options.start) {
+      errors.push("Command is required. Use --cmd, or use --start with --restart-on-change");
+    }
+    if (this.options.start && !this.options.restartOnSuccess && !this.options.restartOnChange) {
+      errors.push("A start command requires --restart-on-success or --restart-on-change");
+    }
+    if (this.options.restartOnSuccess && (!this.options.cmd || !this.options.start)) {
+      errors.push("--restart-on-success requires both --cmd and --start");
+    }
+    if (this.options.restartOnChange && !this.options.start) {
+      errors.push("--restart-on-change requires --start");
+    }
+    if (this.options.restartOnChange && this.options.cmd) {
+      errors.push("--restart-on-change cannot be combined with --cmd; use --restart-on-success");
+    }
+    if (!this.options.cmd && this.options.start && !this.options.restartOnChange) {
+      errors.push("--restart-on-change is required when --start is used without --cmd");
     }
     if (this.options.delay < 0) {
       errors.push("Delay must be a non-negative number");
@@ -145,6 +189,12 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
     if (this.options.killTimeout < 0) {
       errors.push("Kill timeout must be a non-negative number");
     }
+    if (this.options.restartDelay < 0) {
+      errors.push("Restart delay must be a non-negative number");
+    }
+    if (this.options.gitChanged && !this.options.gitBase) {
+      errors.push("Git base must be set when git-changed mode is enabled");
+    }
     if (this.options.retry < 0) {
       errors.push("Retry must be a non-negative number");
     }
@@ -171,6 +221,36 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
       return null;
     }
   }
+  normalizeGitPath(filePath) {
+    return import_path.default.relative(process.cwd(), import_path.default.resolve(filePath)).replace(/\\/g, "/");
+  }
+  runGit(args) {
+    return new Promise((resolve, reject) => {
+      (0, import_child_process.execFile)("git", args, { cwd: process.cwd(), maxBuffer: 1024 * 1024 }, (error, stdout, stderr) => {
+        if (error) {
+          const message = stderr.trim() || error.message;
+          reject(new Error(`git ${args.join(" ")} failed: ${message}`));
+          return;
+        }
+        resolve(stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+      });
+    });
+  }
+  async refreshGitChangedFiles() {
+    if (!this.options.gitChanged) return;
+    const [unstaged, staged, untracked] = await Promise.all([
+      this.runGit(["diff", "--name-only", "--relative", this.options.gitBase, "--"]),
+      this.runGit(["diff", "--name-only", "--cached", "--relative", this.options.gitBase, "--"]),
+      this.runGit(["ls-files", "--others", "--exclude-standard"])
+    ]);
+    this.gitChangedFiles = new Set([...unstaged, ...staged, ...untracked].map((file) => file.replace(/\\/g, "/")));
+  }
+  async isGitChangedFile(filePath) {
+    if (!this.options.gitChanged) return true;
+    await this.refreshGitChangedFiles();
+    const relativePath = this.normalizeGitPath(filePath);
+    return this.gitChangedFiles.has(relativePath);
+  }
   log(...args) {
     if (!this.options.quiet && !this.disposed) console.log(...args);
   }
@@ -187,6 +267,33 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
   timestamp() {
     return this.t.gray(`[${(/* @__PURE__ */ new Date()).toLocaleTimeString()}]`);
   }
+  async runHook(hook, context, mode) {
+    const callback = this.options.hooks[hook];
+    if (!callback) return true;
+    const hookContext = {
+      phase: hook,
+      timestamp: /* @__PURE__ */ new Date(),
+      ...context
+    };
+    try {
+      await callback(Object.freeze(hookContext));
+      return true;
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.log(this.t.red(`Hook ${hook} failed: ${err.message}`));
+      this.logJson("hook_error", { hook, error: err.message });
+      this.emit("hookError", hook, err);
+      if (mode === "notify") return true;
+      this.emit("fail", null);
+      return false;
+    }
+  }
+  notifyHook(hook, context) {
+    void this.runHook(hook, context, "notify");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
   parseCommand(cmdString) {
     const tokens = [];
     let current = "";
@@ -195,7 +302,6 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
     let escaped = false;
     for (let i = 0; i < cmdString.length; i++) {
       const char = cmdString[i];
-      const prevChar = i > 0 ? cmdString[i - 1] : "";
       if (escaped) {
         current += char;
         escaped = false;
@@ -225,92 +331,380 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
     }
     return { cmd: tokens[0] || "", args: tokens.slice(1) };
   }
-  runCommand() {
-    if (this.disposed) return;
-    if (this.isRunning) {
-      this.logVerbose(this.t.yellow("\u26A0\uFE0F  Previous command still running, skipping..."));
-      this.emit("skip", "previous command still running");
-      return;
+  commandNeedsShell(command) {
+    return /(?:&&|\|\||[|<>])/.test(command);
+  }
+  resolveWindowsCommand(command) {
+    if (process.platform !== "win32") return null;
+    if (import_path.default.isAbsolute(command) || command.includes("\\") || command.includes("/")) {
+      return import_fs.default.existsSync(command) ? command : null;
     }
-    if (this.options.clearScreen) {
-      console.clear();
+    const pathEntries = (process.env.PATH || "").split(import_path.default.delimiter).filter(Boolean);
+    const pathExts = (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+    const hasExt = Boolean(import_path.default.extname(command));
+    const candidates = hasExt ? [command] : pathExts.map((ext) => `${command}${ext.toLowerCase()}`);
+    for (const entry of pathEntries) {
+      for (const candidate of candidates) {
+        const fullPath = import_path.default.join(entry, candidate);
+        if (import_fs.default.existsSync(fullPath)) return fullPath;
+      }
     }
-    this.isRunning = true;
-    const retryInfo = this.retryCount > 0 ? ` (Retry ${this.retryCount}/${this.options.retry})` : "";
-    this.log(`${this.timestamp()} ${this.t.cyan("\u{1F680} Triggering:")} ${this.t.bold(this.options.cmd)}${retryInfo}`);
-    this.logJson("trigger", { command: this.options.cmd, retry: this.retryCount });
-    this.emit("trigger", this.options.cmd);
-    const { cmd, args } = this.parseCommand(this.options.cmd);
-    const startTime = Date.now();
-    this.activeProcess = (0, import_child_process.spawn)(cmd, args, {
+    return null;
+  }
+  shouldUseShell(command, preferShell) {
+    if (preferShell || this.commandNeedsShell(command)) return true;
+    const parsed = this.parseCommand(command);
+    if (!parsed.cmd) return true;
+    if (process.platform !== "win32") return false;
+    const resolved = this.resolveWindowsCommand(parsed.cmd);
+    if (!resolved) return true;
+    return /\.(cmd|bat)$/i.test(resolved);
+  }
+  spawnCommand(command, preferShell) {
+    const useShell = this.shouldUseShell(command, preferShell);
+    const parsed = this.parseCommand(command);
+    const child = useShell ? (0, import_child_process.spawn)(command, {
       stdio: "inherit",
       shell: true,
-      env: { ...process.env }
+      env: { ...process.env },
+      detached: process.platform !== "win32",
+      windowsHide: false
+    }) : (0, import_child_process.spawn)(parsed.cmd, parsed.args, {
+      stdio: "inherit",
+      env: { ...process.env },
+      detached: process.platform !== "win32",
+      windowsHide: false
     });
-    if (this.options.killTimeout > 0) {
-      this.killTimer = setTimeout(() => {
-        if (this.activeProcess && !this.disposed) {
-          this.log(this.t.yellow(`\u26A0\uFE0F  Process timeout (${this.options.killTimeout}ms), force killing...`));
-          this.activeProcess.kill("SIGKILL");
-        }
-      }, this.options.killTimeout);
-    }
-    this.activeProcess.on("error", (err) => {
-      this.log(this.t.red(`Process error: ${err.message}`));
-      this.emit("error", err);
+    return Object.assign(child, { steadyWatchUsesShell: useShell });
+  }
+  runTaskkill(pid, force) {
+    return new Promise((resolve) => {
+      const args = ["/pid", String(pid), "/T"];
+      if (force) args.push("/F");
+      const killer = (0, import_child_process.spawn)("taskkill", args, {
+        stdio: "ignore",
+        windowsHide: true
+      });
+      let settled = false;
+      const finish = (ok) => {
+        if (settled) return;
+        settled = true;
+        resolve(ok);
+      };
+      killer.on("close", (code) => finish(code === 0));
+      killer.on("error", () => finish(false));
     });
-    this.activeProcess.on("close", (code, signal) => {
-      if (this.disposed) return;
-      this.isRunning = false;
-      if (this.killTimer) {
-        clearTimeout(this.killTimer);
-        this.killTimer = null;
-      }
-      this.activeProcess = null;
-      const duration = ((Date.now() - startTime) / 1e3).toFixed(2);
-      if (code === 0) {
-        this.log(`${this.timestamp()} ${this.t.green("\u2714 Done")} in ${duration}s`);
-        this.logJson("done", { duration: parseFloat(duration) });
-        this.emit("done", parseFloat(duration));
-        this.retryCount = 0;
+  }
+  async forceKillProcess(child, label) {
+    if (process.platform === "win32" && child.pid) {
+      const killedTree = await this.runTaskkill(child.pid, true);
+      if (killedTree) return;
+    }
+    try {
+      if (process.platform !== "win32" && child.pid) {
+        process.kill(-child.pid, "SIGKILL");
       } else {
-        const exitMessage = signal ? ` (Signal: ${signal})` : ` (Exit code: ${code})`;
-        this.log(`${this.timestamp()} ${this.t.red("\u2718 Failed")}${exitMessage}`);
-        this.logJson("failed", { exitCode: code, signal });
-        this.emit("fail", code, signal ?? void 0);
-        if (this.options.retry > 0 && this.retryCount < this.options.retry) {
-          this.retryCount++;
-          this.log(this.t.yellow(`\u{1F504} Retrying in 1s... (${this.retryCount}/${this.options.retry})`));
-          setTimeout(() => this.runCommand(), 1e3);
+        child.kill("SIGKILL");
+      }
+    } catch {
+      this.logVerbose(this.t.gray(`Process already exited before force kill: ${label}`));
+    }
+  }
+  terminateProcess(child, command, label) {
+    return new Promise((resolve) => {
+      let settled = false;
+      const timeoutMs = this.options.killTimeout > 0 ? this.options.killTimeout : 5e3;
+      let forceTimer = null;
+      const finish = () => {
+        if (settled) return;
+        settled = true;
+        if (forceTimer) clearTimeout(forceTimer);
+        resolve();
+      };
+      if (child.exitCode !== null || child.signalCode !== null) {
+        finish();
+        return;
+      }
+      child.once("close", finish);
+      this.emit("stop", command, "SIGTERM");
+      const requestGracefulStop = async () => {
+        try {
+          if (process.platform === "win32" && child.pid) {
+            const killedTree = await this.runTaskkill(child.pid, false);
+            if (killedTree) {
+              finish();
+              return;
+            }
+          }
+          if (process.platform !== "win32" && child.pid) {
+            process.kill(-child.pid, "SIGTERM");
+          } else {
+            child.kill("SIGTERM");
+          }
+        } catch {
+          finish();
           return;
         }
+      };
+      void requestGracefulStop();
+      forceTimer = setTimeout(() => {
+        if (!settled) {
+          this.log(this.t.yellow(`Process did not exit after ${timeoutMs}ms, force killing ${label}...`));
+          void (async () => {
+            await this.forceKillProcess(child, label);
+            finish();
+          })();
+        }
+      }, timeoutMs);
+    });
+  }
+  runSingleCommand(attempt) {
+    if (this.disposed) {
+      return Promise.resolve({ code: null, signal: null, duration: 0 });
+    }
+    this.retryCount = attempt;
+    const retryInfo = attempt > 0 ? ` (Retry ${attempt}/${this.options.retry})` : "";
+    this.log(`${this.timestamp()} ${this.t.cyan("Triggering:")} ${this.t.bold(this.options.cmd)}${retryInfo}`);
+    this.logJson("trigger", { command: this.options.cmd, retry: attempt });
+    this.emit("trigger", this.options.cmd);
+    const startTime = Date.now();
+    const child = this.spawnCommand(this.options.cmd, false);
+    this.lifecycleProcess = child;
+    const commandTimeout = this.options.killTimeout;
+    if (commandTimeout > 0) {
+      this.lifecycleKillTimer = setTimeout(() => {
+        if (this.lifecycleProcess === child && !this.disposed) {
+          this.log(this.t.yellow(`Process timeout (${commandTimeout}ms), force killing...`));
+          void this.forceKillProcess(child, this.options.cmd);
+        }
+      }, commandTimeout);
+    }
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = (code, signal) => {
+        if (settled) return;
+        settled = true;
+        if (this.lifecycleKillTimer) {
+          clearTimeout(this.lifecycleKillTimer);
+          this.lifecycleKillTimer = null;
+        }
+        if (this.lifecycleProcess === child) {
+          this.lifecycleProcess = null;
+        }
+        const duration = (Date.now() - startTime) / 1e3;
+        if (!this.disposed) {
+          if (code === 0) {
+            this.log(`${this.timestamp()} ${this.t.green("Done")} in ${duration.toFixed(2)}s`);
+            this.logJson("done", { duration: parseFloat(duration.toFixed(2)) });
+            this.emit("done", parseFloat(duration.toFixed(2)));
+          } else {
+            const exitMessage = signal ? ` (Signal: ${signal})` : ` (Exit code: ${code})`;
+            this.log(`${this.timestamp()} ${this.t.red("Failed")}${exitMessage}`);
+            this.logJson("failed", { exitCode: code, signal });
+            this.emit("fail", code, signal ?? void 0);
+          }
+        }
+        resolve({ code, signal, duration });
+      };
+      child.on("error", (err) => {
+        if (!this.disposed) {
+          this.log(this.t.red(`Process error: ${err.message}`));
+        }
+        finish(null, null);
+      });
+      child.on("close", finish);
+    });
+  }
+  async runCommandWithRetry() {
+    let attempt = 0;
+    while (!this.disposed) {
+      const result = await this.runSingleCommand(attempt);
+      if (result.code === 0) {
         this.retryCount = 0;
+        return result;
+      }
+      if (this.options.retry > 0 && attempt < this.options.retry) {
+        attempt++;
+        this.log(this.t.yellow(`Retrying in 1s... (${attempt}/${this.options.retry})`));
+        await this.sleep(1e3);
+        continue;
+      }
+      this.retryCount = 0;
+      return result;
+    }
+    return { code: null, signal: null, duration: 0 };
+  }
+  async stopStartedProcess() {
+    if (!this.startedProcess) return;
+    const child = this.startedProcess;
+    const pid = child.pid;
+    this.stoppingStartedProcess = child;
+    await this.terminateProcess(child, this.options.start, this.options.start);
+    if (this.startedProcess === child) {
+      this.startedProcess = null;
+    }
+    if (this.stoppingStartedProcess === child) {
+      this.stoppingStartedProcess = null;
+    }
+    this.notifyHook("afterStop", { command: this.options.start, startCommand: this.options.start, pid });
+  }
+  startLongRunningProcess() {
+    if (this.disposed || !this.options.start) return;
+    this.log(`${this.timestamp()} ${this.t.cyan("Starting:")} ${this.t.bold(this.options.start)}`);
+    this.logJson("start", { command: this.options.start });
+    const child = this.spawnCommand(this.options.start, false);
+    this.startedProcess = child;
+    this.emit("start", this.options.start, child.pid);
+    setImmediate(() => {
+      if (this.startedProcess === child && !this.disposed && child.exitCode === null && child.signalCode === null) {
+        this.notifyHook("afterStart", { command: this.options.start, startCommand: this.options.start, pid: child.pid });
       }
-      this.log(this.t.dim("\u2500".repeat(40)));
     });
+    child.on("error", (err) => {
+      if (!this.disposed) {
+        this.log(this.t.red(`Start process error: ${err.message}`));
+        this.logJson("start_error", { command: this.options.start, error: err.message });
+        this.emit("fail", null);
+      }
+      if (this.startedProcess === child) {
+        this.startedProcess = null;
+      }
+    });
+    child.on("close", (code, signal) => {
+      const expectedStop = this.disposed || this.stoppingStartedProcess === child;
+      if (this.startedProcess === child) {
+        this.startedProcess = null;
+      }
+      if (this.stoppingStartedProcess === child) {
+        this.stoppingStartedProcess = null;
+      }
+      if (!expectedStop && !this.disposed) {
+        const exitMessage = signal ? ` (Signal: ${signal})` : ` (Exit code: ${code})`;
+        this.log(`${this.timestamp()} ${this.t.yellow("Start process exited")}${exitMessage}`);
+        this.logJson("start_exit", { exitCode: code, signal, expected: false });
+      }
+      if (!this.disposed) {
+        this.emit("startExit", code, signal ?? void 0, expectedStop);
+      }
+    });
+  }
+  async restartStartedProcess() {
+    if (!this.options.start) return;
+    this.emit("restart", this.options.start);
+    const canStart = await this.runHook("beforeStart", {
+      command: this.options.start,
+      startCommand: this.options.start
+    }, "gate");
+    if (!canStart) return;
+    if (this.startedProcess) {
+      const canStop = await this.runHook("beforeStop", {
+        command: this.options.start,
+        startCommand: this.options.start,
+        pid: this.startedProcess.pid
+      }, "gate");
+      if (!canStop) return;
+      await this.stopStartedProcess();
+    }
+    if (this.options.restartDelay > 0 && !this.disposed) {
+      await this.sleep(this.options.restartDelay);
+    }
+    this.startLongRunningProcess();
   }
-  handleFileChange(filePath) {
+  async runCycle(reason) {
     if (this.disposed) return;
-    const currentHash = this.getHash(filePath);
-    const lastHash = this.fileHashes.get(filePath);
-    if (currentHash === lastHash) {
-      this.logVerbose(this.t.gray(`Skipping ghost change: ${import_path.default.basename(filePath)}`));
-      this.emit("skip", "content unchanged", filePath);
+    if (this.cycleRunning) {
+      this.pendingCycle = true;
+      this.logVerbose(this.t.yellow(`Lifecycle already running, coalescing ${reason} change...`));
+      this.skip("lifecycle already running");
       return;
     }
-    if (currentHash) {
-      this.fileHashes.set(filePath, currentHash);
+    this.cycleRunning = true;
+    try {
+      if (this.options.clearScreen) {
+        console.clear();
+      }
+      if (this.options.cmd) {
+        const canRunCommand = await this.runHook("beforeCommand", {
+          reason,
+          command: this.options.cmd,
+          startCommand: this.options.start || void 0
+        }, "gate");
+        if (!canRunCommand) return;
+        const result = await this.runCommandWithRetry();
+        const canContinue = await this.runHook("afterCommand", {
+          reason,
+          command: this.options.cmd,
+          startCommand: this.options.start || void 0,
+          exitCode: result.code,
+          signal: result.signal,
+          duration: result.duration
+        }, "gate");
+        if (!canContinue) return;
+        if (result.code === 0 && this.options.start && this.options.restartOnSuccess) {
+          await this.restartStartedProcess();
+        }
+      } else if (this.options.start && this.options.restartOnChange) {
+        await this.restartStartedProcess();
+      }
+    } finally {
+      this.cycleRunning = false;
+      if (!this.disposed) {
+        this.log(this.t.dim("-".repeat(40)));
+      }
+      if (this.pendingCycle && !this.disposed) {
+        this.pendingCycle = false;
+        setImmediate(() => {
+          void this.runCycle("coalesced");
+        });
+      }
     }
+  }
+  requestCycle(reason) {
+    void this.runCycle(reason);
+  }
+  skip(reason, filePath) {
+    this.emit("skip", reason, filePath);
+    this.notifyHook("onSkip", { skipReason: reason, file: filePath });
+  }
+  scheduleFileCycle(filePath, reason) {
     this.emit("change", filePath);
     if (this.timeout) clearTimeout(this.timeout);
     this.timeout = setTimeout(() => {
       if (!this.disposed) {
-        this.log(`${this.timestamp()} ${this.t.yellow("\u26A1 Change detected:")} ${import_path.default.basename(filePath)}`);
-        this.logJson("change", { file: import_path.default.basename(filePath) });
-        this.runCommand();
+        this.log(`${this.timestamp()} ${this.t.yellow("Change detected:")} ${import_path.default.basename(filePath)}`);
+        this.logJson("change", { file: import_path.default.basename(filePath), reason });
+        this.requestCycle(reason);
       }
     }, this.options.delay);
   }
+  async handleFileChange(filePath) {
+    if (this.disposed) return;
+    const currentHash = this.getHash(filePath);
+    const lastHash = this.fileHashes.get(filePath);
+    if (currentHash === lastHash) {
+      this.logVerbose(this.t.gray(`Skipping ghost change: ${import_path.default.basename(filePath)}`));
+      this.skip("content unchanged", filePath);
+      return;
+    }
+    if (currentHash) {
+      this.fileHashes.set(filePath, currentHash);
+    }
+    let isGitChanged = true;
+    try {
+      isGitChanged = await this.isGitChangedFile(filePath);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.log(this.t.red(`Git changed-file check failed: ${err.message}`));
+      this.emit("error", err);
+      return;
+    }
+    if (!isGitChanged) {
+      this.logVerbose(this.t.gray(`Skipping unchanged git file: ${import_path.default.basename(filePath)}`));
+      this.skip("not changed from git base", filePath);
+      return;
+    }
+    this.scheduleFileCycle(filePath, "file");
+  }
   async start() {
     const validation = this.validate();
     if (!validation.valid) {
@@ -320,17 +714,23 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
       throw new Error(errorMsg);
     }
     const effectivePattern = this.getEffectivePattern();
-    this.log(this.t.bold(`
-\u{1F52D} Steady Watch Initialized`));
+    this.log(this.t.bold("\nSteady Watch Initialized"));
     this.log(`   ${this.t.dim("Pattern:")} ${effectivePattern}`);
-    this.log(`   ${this.t.dim("Command:")} ${this.options.cmd}`);
+    if (this.options.cmd) this.log(`   ${this.t.dim("Command:")} ${this.options.cmd}`);
+    if (this.options.start) this.log(`   ${this.t.dim("Start:")}   ${this.options.start}`);
     this.log(`   ${this.t.dim("Delay:")}   ${this.options.delay}ms`);
     if (this.options.quiet) this.log(`   ${this.t.dim("Mode:")}   quiet`);
     if (this.options.killTimeout > 0) this.log(`   ${this.t.dim("Kill:")}    ${this.options.killTimeout}ms`);
+    if (this.options.restartDelay > 0) this.log(`   ${this.t.dim("Restart delay:")} ${this.options.restartDelay}ms`);
     if (this.options.retry > 0) this.log(`   ${this.t.dim("Retry:")}   ${this.options.retry}x`);
+    if (this.options.gitChanged) this.log(`   ${this.t.dim("Git:")}     changed from ${this.options.gitBase}`);
+    if (this.options.initialRun) this.log(`   ${this.t.dim("Initial:")} enabled`);
     if (this.options.mtimeOnly) this.log(`   ${this.t.dim("Hash:")}    mtime-only (fastest)`);
     else this.log(`   ${this.t.dim("Hash:")}    ${this.options.hash}`);
     this.log("");
+    if (this.options.gitChanged) {
+      await this.refreshGitChangedFiles();
+    }
     this.watcher = import_chokidar.default.watch(effectivePattern, {
       ignored: this.options.ignore,
       ignoreInitial: false,
@@ -340,55 +740,103 @@ var _SteadyWatcher = class _SteadyWatcher extends import_events.EventEmitter {
       }
     });
     this.watcher.on("ready", () => {
-      this.log(this.t.green("\u{1F441}\uFE0F  Watcher ready. Monitoring for changes..."));
+      this.watcherReady = true;
+      this.log(this.t.green("Watcher ready. Monitoring for changes..."));
       this.logVerbose(this.t.dim(`   Tracking ${this.fileHashes.size} file(s)`));
       this.emit("ready");
+      if (this.options.initialRun) {
+        this.requestCycle("initial");
+      }
     });
     this.watcher.on("error", (error) => {
       this.log(this.t.red(`Watcher error: ${error.message}`));
       this.emit("error", error);
     });
     this.watcher.on("add", (filePath) => {
-      if (this.disposed) return;
-      const hash = this.getHash(filePath);
-      if (hash) this.fileHashes.set(filePath, hash);
-      this.logVerbose(this.t.dim(`Indexed: ${import_path.default.basename(filePath)}`));
+      void this.handleFileAdd(filePath);
+    });
+    this.watcher.on("change", (filePath) => {
+      void this.handleFileChange(filePath);
     });
-    this.watcher.on("change", (filePath) => this.handleFileChange(filePath));
     this.watcher.on("unlink", (filePath) => {
-      if (this.disposed) return;
-      this.fileHashes.delete(filePath);
-      this.logVerbose(this.t.dim(`Removed: ${import_path.default.basename(filePath)}`));
+      void this.handleFileUnlink(filePath);
     });
   }
+  async handleFileAdd(filePath) {
+    if (this.disposed) return;
+    const hash = this.getHash(filePath);
+    if (hash) this.fileHashes.set(filePath, hash);
+    this.logVerbose(this.t.dim(`Indexed: ${import_path.default.basename(filePath)}`));
+    if (!this.watcherReady || !this.options.gitChanged) return;
+    try {
+      if (await this.isGitChangedFile(filePath)) {
+        this.scheduleFileCycle(filePath, "file added");
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.log(this.t.red(`Git changed-file check failed: ${err.message}`));
+      this.emit("error", err);
+    }
+  }
+  async handleFileUnlink(filePath) {
+    if (this.disposed) return;
+    this.fileHashes.delete(filePath);
+    this.logVerbose(this.t.dim(`Removed: ${import_path.default.basename(filePath)}`));
+    if (!this.watcherReady || !this.options.gitChanged) return;
+    try {
+      if (await this.isGitChangedFile(filePath)) {
+        this.scheduleFileCycle(filePath, "file removed");
+      }
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.log(this.t.red(`Git changed-file check failed: ${err.message}`));
+      this.emit("error", err);
+    }
+  }
   async close() {
+    if (this.closePromise) {
+      return this.closePromise;
+    }
+    this.closePromise = this.closeInternal();
+    return this.closePromise;
+  }
+  async closeInternal() {
     if (this.disposed) return;
-    this.disposed = true;
-    this.log(this.t.yellow("\n\u{1F6D1} Shutting down..."));
+    this.log(this.t.yellow("\nShutting down..."));
     this.logJson("shutdown", {});
+    this.disposed = true;
     if (this.timeout) {
       clearTimeout(this.timeout);
       this.timeout = null;
     }
-    if (this.killTimer) {
-      clearTimeout(this.killTimer);
-      this.killTimer = null;
-    }
-    if (this.activeProcess) {
-      this.activeProcess.kill("SIGTERM");
-      this.activeProcess = null;
+    if (this.lifecycleKillTimer) {
+      clearTimeout(this.lifecycleKillTimer);
+      this.lifecycleKillTimer = null;
     }
+    const lifecycleProcess = this.lifecycleProcess;
+    const startedProcess = this.startedProcess;
+    await Promise.all([
+      lifecycleProcess ? this.terminateProcess(lifecycleProcess, this.options.cmd, this.options.cmd) : Promise.resolve(),
+      startedProcess ? this.terminateProcess(startedProcess, this.options.start, this.options.start) : Promise.resolve()
+    ]);
+    this.lifecycleProcess = null;
+    this.startedProcess = null;
+    this.stoppingStartedProcess = null;
     if (this.watcher) {
       await this.watcher.close();
       this.watcher = null;
     }
+    this.watcherReady = false;
     this.removeAllListeners();
   }
   getTrackedFiles() {
     return Array.from(this.fileHashes.keys());
   }
   isCurrentlyRunning() {
-    return this.isRunning;
+    return this.cycleRunning || Boolean(this.lifecycleProcess);
+  }
+  isStartedProcessRunning() {
+    return Boolean(this.startedProcess);
   }
   isDisposed() {
     return this.disposed;
@@ -406,14 +854,16 @@ function steadyWatch(options) {
 var import_fs2 = __toESM(require("fs"));
 var import_path2 = __toESM(require("path"));
 var import_commander = require("commander");
+var CLI_VERSION = "2.1.0";
 function loadConfig(configPath) {
   const searchPaths = [
     configPath,
     ".steady-watchrc",
     ".steady-watchrc.json",
     "steady-watch.config.json"
-  ].filter(Boolean);
+  ];
   for (const cfgPath of searchPaths) {
+    if (!cfgPath) continue;
     try {
       const fullPath = import_path2.default.resolve(cfgPath);
       if (import_fs2.default.existsSync(fullPath)) {
@@ -446,28 +896,54 @@ function parseNumber(value, defaultValue) {
   }
   return defaultValue;
 }
+function unsetDefaultedCliOptions(program, opts) {
+  const getSource = program.getOptionValueSource.bind(program);
+  const optionKeys = [
+    "delay",
+    "verbose",
+    "quiet",
+    "gitBase",
+    "retry",
+    "hash",
+    "theme"
+  ];
+  for (const key of optionKeys) {
+    if (getSource(key) === "default") {
+      delete opts[key];
+    }
+  }
+}
 function mergeOptions(cliArgs, cliOpts, config) {
   return {
     pattern: cliArgs.pattern || config.pattern || "",
     cmd: cliOpts.cmd || config.cmd || "",
+    start: cliOpts.start || config.start || "",
+    restartOnSuccess: parseBoolean(cliOpts.restartOnSuccess ?? config.restartOnSuccess),
+    restartOnChange: parseBoolean(cliOpts.restartOnChange ?? config.restartOnChange),
+    initialRun: cliOpts.initialRun ?? config.initialRun,
     delay: parseNumber(cliOpts.delay ?? config.delay, 300),
     verbose: parseBoolean(cliOpts.verbose ?? config.verbose),
     quiet: parseBoolean(cliOpts.quiet ?? config.quiet),
     ignore: [...parseIgnorePatterns(cliOpts.ignore), ...config.ignore || []],
     ext: cliOpts.ext ? parseExtFilter(cliOpts.ext) : config.ext || [],
-    killTimeout: parseNumber(cliOpts.killTimeout ?? config.killTimeout, 0),
+    gitChanged: parseBoolean(cliOpts.gitChanged ?? config.gitChanged),
+    gitBase: cliOpts.gitBase || config.gitBase || "HEAD",
+    killTimeout: cliOpts.killTimeout !== void 0 || config.killTimeout !== void 0 ? parseNumber(cliOpts.killTimeout ?? config.killTimeout, 0) : void 0,
+    restartDelay: parseNumber(cliOpts.restartDelay ?? config.restartDelay, 0),
     retry: parseNumber(cliOpts.retry ?? config.retry, 0),
-    hash: cliOpts.hash || config.hash || "md5",
-    mtimeOnly: cliOpts.noHash ?? config.mtimeOnly ?? false,
+    hash: (typeof cliOpts.hash === "string" ? cliOpts.hash : void 0) || config.hash || "md5",
+    mtimeOnly: cliOpts.hash === false || config.mtimeOnly || false,
     clearScreen: parseBoolean(cliOpts.clear ?? config.clearScreen),
     json: parseBoolean(cliOpts.json ?? config.json),
     theme: cliOpts.theme || config.theme || "default"
   };
 }
-function parseCliArgs() {
-  import_commander.program.name("steady-watch").description("Intelligent file watcher with debouncing and content hashing.").argument("<files>", 'Glob pattern to watch (e.g., "src/**/*.ts")').requiredOption("-c, --cmd <command>", "Command(s) to execute on change (supports quotes)").option("-d, --delay <ms>", "Debounce delay in milliseconds", "300").option("-v, --verbose", "Show hash calculations", false).option("-q, --quiet", "Minimize output", false).option("--ignore <patterns>", "Additional ignore patterns (comma-separated)").option("--ext <extensions>", "Filter by file extensions (e.g., .ts,.tsx)").option("--config <path>", "Path to config file").option("--kill-timeout <ms>", "Force kill process after timeout", "0").option("--retry <count>", "Retry failed command (0 = disabled)", "0").option("--hash <algorithm>", "Hash algorithm (md5, sha1, sha256)", "md5").option("--no-hash", "Use mtime only instead of content hash (fastest)").option("--clear", "Clear screen on each trigger").option("--json", "Output in JSON format").option("--theme <theme>", "Color theme (default, minimal, none)", "default").version("2.0.0").parse();
-  const cliOpts = import_commander.program.opts();
-  const cliArgs = { pattern: import_commander.program.args[0] || "" };
+function parseCliArgs(argv = process.argv) {
+  const program = new import_commander.Command();
+  program.name("steady-watch").description("Intelligent file watcher with debouncing and content hashing.").argument("[files]", 'Glob pattern to watch (e.g., "src/**/*.ts")').option("-c, --cmd <command>", "Command(s) to execute on change (supports quotes)").option("--start <command>", "Long-running command to start or restart after a successful lifecycle command").option("--restart-on-success", "Restart --start only when --cmd exits with code 0").option("--restart-on-change", "Restart --start directly on change when no --cmd is configured").option("--initial-run", "Run the initial lifecycle when the watcher starts").option("--no-initial-run", "Wait for the first file change before running the lifecycle").option("-d, --delay <ms>", "Debounce delay in milliseconds", "300").option("-v, --verbose", "Show hash calculations", false).option("-q, --quiet", "Minimize output", false).option("--ignore <patterns>", "Additional ignore patterns (comma-separated)").option("--ext <extensions>", "Filter by file extensions (e.g., .ts,.tsx)").option("--git-changed", "Only trigger for files changed from the git base ref").option("--git-base <ref>", "Git base ref for --git-changed", "HEAD").option("--config <path>", "Path to config file").option("--kill-timeout <ms>", "Force kill lifecycle commands and process shutdown after timeout").option("--restart-delay <ms>", "Delay between stopping and starting --start").option("--retry <count>", "Retry failed command (0 = disabled)", "0").option("--hash <algorithm>", "Hash algorithm (md5, sha1, sha256)", "md5").option("--no-hash", "Use mtime only instead of content hash (fastest)").option("--clear", "Clear screen on each trigger").option("--json", "Output in JSON format").option("--theme <theme>", "Color theme (default, minimal, none)", "default").version(CLI_VERSION).parse(argv);
+  const cliOpts = program.opts();
+  unsetDefaultedCliOptions(program, cliOpts);
+  const cliArgs = { pattern: program.args[0] || "" };
   return { args: cliArgs, opts: cliOpts };
 }
 
@@ -475,44 +951,48 @@ function parseCliArgs() {
 function runCli() {
   const { args, opts } = parseCliArgs();
   const config = loadConfig(opts.config);
-  if (opts.config && config.cmd) {
-    opts.cmd = config.cmd;
-  }
   const options = mergeOptions(args, opts, config);
-  if (!options.cmd) {
-    console.error("Error: Command is required. Use -c option or config file.");
-    process.exit(1);
-  }
   const watcher = new SteadyWatcher(options);
+  let exiting = false;
+  const shutdown = async (exitCode, message) => {
+    if (exiting) return;
+    exiting = true;
+    if (message) console.error(message);
+    try {
+      await watcher.close();
+    } finally {
+      process.exit(exitCode);
+    }
+  };
   watcher.on("error", (err) => {
-    console.error(`Error: ${err.message}`);
-    process.exit(1);
+    void shutdown(1, `Error: ${err.message}`);
   });
   watcher.start().catch((err) => {
-    console.error(`Failed to start: ${err.message}`);
-    process.exit(1);
+    void shutdown(1, `Failed to start: ${err.message}`);
   });
-  const shutdown = async (signal) => {
+  const shutdownSignal = async (signal) => {
+    if (exiting) return;
     console.log(`
 Received ${signal}, shutting down...`);
-    await watcher.close();
-    process.exit(0);
+    await shutdown(0);
   };
-  process.on("SIGINT", () => shutdown("SIGINT"));
-  process.on("SIGTERM", () => shutdown("SIGTERM"));
+  process.on("SIGINT", () => void shutdownSignal("SIGINT"));
+  process.on("SIGTERM", () => void shutdownSignal("SIGTERM"));
   process.on("uncaughtException", (err) => {
-    console.error("Uncaught exception:", err);
-    process.exit(1);
+    void shutdown(1, `Uncaught exception: ${err instanceof Error ? err.stack || err.message : String(err)}`);
   });
 }
-var isMain = require.main === module || process.argv[1]?.includes("index.js") || process.argv[1]?.includes("steady-watch");
-if (isMain) {
+if (require.main === module) {
   runCli();
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CLI_VERSION,
   SteadyWatcher,
   getTheme,
+  loadConfig,
+  mergeOptions,
+  parseCliArgs,
   runCli,
   steadyWatch,
   themes