dev-cockpit 0.1.0

package/dist/lint/reactive.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Reactive lint engine.
+ *
+ * Pure command-selection function: given a file extension and a repo's lint
+ * config, returns the lint command (or undefined if none configured).
+ *
+ * The debounced runner lives here too, backed by spawnStream. Debounce is
+ * per-file (keyed by absolute path), 300ms.
+ *
+ * Lint result is reported via `onLintResult` — this module never mutates
+ * watcher status. Watcher lifecycle (idle/running/failing) is exclusively
+ * owned by WatcherManager.
+ */
+import type { NormalizedRepoConfig } from '../watchers/types.js';
+import type { OutputLine } from '../cockpit/state/store.js';
+import type { LintStatus } from '../cockpit/state/store.js';
+import { spawnStream } from '../core/subprocess.js';
+/** Returns the lint command for a file, or undefined if none configured. Pure. */
+export declare function selectLintCommand(filePath: string, lintConfig: NormalizedRepoConfig['lint']): string | undefined;
+export interface LintRunnerOptions {
+    repoName: string;
+    repoRootDir: string;
+    lintConfig: NormalizedRepoConfig['lint'];
+    appendOutput: (line: OutputLine) => void;
+    onLintResult: (result: LintStatus) => void;
+    spawn?: typeof spawnStream;
+}
+/**
+ * Schedule a lint run for `filePath`, debounced 300ms per file. Files with
+ * no matching lint command are silently skipped.
+ */
+export declare function scheduleLint(filePath: string, opts: LintRunnerOptions): void;
+/**
+ * Run all configured lint commands for a repo (js, css, php) in parallel.
+ * Aggregates pass/fail — any failing kind → overall 'fail', all pass → 'pass'.
+ */
+export declare function runAllLints(opts: LintRunnerOptions): Promise<void>;
+//# sourceMappingURL=reactive.d.ts.map

package/dist/lint/reactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../../src/lint/reactive.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAgBpD,kFAAkF;AAClF,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,oBAAoB,CAAC,MAAM,CAAC,GACvC,MAAM,GAAG,SAAS,CAKpB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC;IACzC,YAAY,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,YAAY,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAC3C,KAAK,CAAC,EAAE,OAAO,WAAW,CAAC;CAC5B;AAKD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAa5E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDxE"}

package/dist/lint/reactive.js

@@ -0,0 +1,131 @@
+/**
+ * Reactive lint engine.
+ *
+ * Pure command-selection function: given a file extension and a repo's lint
+ * config, returns the lint command (or undefined if none configured).
+ *
+ * The debounced runner lives here too, backed by spawnStream. Debounce is
+ * per-file (keyed by absolute path), 300ms.
+ *
+ * Lint result is reported via `onLintResult` — this module never mutates
+ * watcher status. Watcher lifecycle (idle/running/failing) is exclusively
+ * owned by WatcherManager.
+ */
+import path from 'node:path';
+import { spawnStream } from '../core/subprocess.js';
+const EXT_TO_LINT_KEY = {
+    '.js': 'js',
+    '.jsx': 'js',
+    '.ts': 'js',
+    '.tsx': 'js',
+    '.mjs': 'js',
+    '.cjs': 'js',
+    '.css': 'css',
+    '.scss': 'css',
+    '.sass': 'css',
+    '.less': 'css',
+    '.php': 'php',
+};
+/** Returns the lint command for a file, or undefined if none configured. Pure. */
+export function selectLintCommand(filePath, lintConfig) {
+    const ext = path.extname(filePath).toLowerCase();
+    const key = EXT_TO_LINT_KEY[ext];
+    if (!key)
+        return undefined;
+    return lintConfig[key];
+}
+const debounceTimers = new Map();
+const DEBOUNCE_MS = 300;
+/**
+ * Schedule a lint run for `filePath`, debounced 300ms per file. Files with
+ * no matching lint command are silently skipped.
+ */
+export function scheduleLint(filePath, opts) {
+    const cmd = selectLintCommand(filePath, opts.lintConfig);
+    if (!cmd)
+        return;
+    const existing = debounceTimers.get(filePath);
+    if (existing !== undefined)
+        clearTimeout(existing);
+    const timer = setTimeout(() => {
+        debounceTimers.delete(filePath);
+        void runLintCmd(filePath, cmd, opts);
+    }, DEBOUNCE_MS);
+    debounceTimers.set(filePath, timer);
+}
+/**
+ * Run all configured lint commands for a repo (js, css, php) in parallel.
+ * Aggregates pass/fail — any failing kind → overall 'fail', all pass → 'pass'.
+ */
+export async function runAllLints(opts) {
+    const { repoName, repoRootDir, lintConfig, appendOutput, onLintResult } = opts;
+    const spawnFn = opts.spawn ?? spawnStream;
+    const kinds = ['js', 'css', 'php'];
+    const toRun = [];
+    for (const kind of kinds) {
+        const cmd = lintConfig[kind];
+        if (cmd)
+            toRun.push({ kind, cmd });
+    }
+    if (toRun.length === 0) {
+        appendOutput({
+            ts: Date.now(),
+            source: repoName,
+            severity: 'info',
+            text: 'lint: no linters configured for this repo',
+        });
+        return;
+    }
+    const results = await Promise.all(toRun.map(async ({ kind, cmd }) => {
+        const [exe, ...args] = cmd.split(/\s+/);
+        if (!exe)
+            return { kind, passed: false };
+        const handle = spawnFn(exe, args, {
+            cwd: repoRootDir,
+            onStdout: (line) => appendOutput({ ts: Date.now(), source: repoName, severity: 'info', text: line }),
+            onStderr: (line) => appendOutput({ ts: Date.now(), source: repoName, severity: 'warn', text: line }),
+        });
+        const code = await handle.exitCode;
+        const passed = code === 0;
+        appendOutput({
+            ts: Date.now(),
+            source: repoName,
+            severity: passed ? 'info' : 'error',
+            text: `lint [${kind}]: ${passed ? 'passed' : `FAILED (exit ${code})`}`,
+        });
+        return { kind, passed };
+    }));
+    const allPassed = results.every((r) => r.passed);
+    onLintResult(allPassed ? 'pass' : 'fail');
+}
+async function runLintCmd(filePath, cmd, opts) {
+    const { repoName, repoRootDir, appendOutput, onLintResult } = opts;
+    const spawnFn = opts.spawn ?? spawnStream;
+    const [exe, ...args] = cmd.split(/\s+/);
+    if (!exe)
+        return;
+    const handle = spawnFn(exe, args, {
+        cwd: repoRootDir,
+        onStdout: (line) => appendOutput({ ts: Date.now(), source: repoName, severity: 'info', text: line }),
+        onStderr: (line) => appendOutput({ ts: Date.now(), source: repoName, severity: 'warn', text: line }),
+    });
+    const code = await handle.exitCode;
+    if (code === 0) {
+        appendOutput({
+            ts: Date.now(),
+            source: repoName,
+            severity: 'info',
+            text: `lint passed for ${path.basename(filePath)}`,
+        });
+        onLintResult('pass');
+    }
+    else {
+        appendOutput({
+            ts: Date.now(),
+            source: repoName,
+            severity: 'error',
+            text: `lint FAILED for ${path.basename(filePath)} (exit ${code})`,
+        });
+        onLintResult('fail');
+    }
+}

package/dist/react.d.ts

@@ -0,0 +1,3 @@
+export { useState, useEffect, useMemo, useCallback, useRef, useReducer, useContext, useLayoutEffect, createContext, Fragment, } from 'react';
+export type { ReactNode, ReactElement, FC, PropsWithChildren, Dispatch, SetStateAction, MutableRefObject, RefObject, } from 'react';
+//# sourceMappingURL=react.d.ts.map

package/dist/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../src/react.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,SAAS,EACT,OAAO,EACP,WAAW,EACX,MAAM,EACN,UAAU,EACV,UAAU,EACV,eAAe,EACf,aAAa,EACb,QAAQ,GACT,MAAM,OAAO,CAAC;AACf,YAAY,EACV,SAAS,EACT,YAAY,EACZ,EAAE,EACF,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,gBAAgB,EAChB,SAAS,GACV,MAAM,OAAO,CAAC"}

package/dist/react.js

@@ -0,0 +1 @@
+export { useState, useEffect, useMemo, useCallback, useRef, useReducer, useContext, useLayoutEffect, createContext, Fragment, } from 'react';

package/dist/runCockpit.d.ts

@@ -0,0 +1,34 @@
+/**
+ * runCockpit — boot the cockpit TUI.
+ *
+ * Responsibilities (Phase 3, shell-only):
+ *  - Switch the terminal into the alternate-screen buffer (so the cockpit fills
+ *    the window without scrolling shell history out of view; restored on exit
+ *    or uncaughtException).
+ *  - Seed `cockpitStore.helpConfig` from `profile.helpSources` + `profile.defaultHelpPage`.
+ *  - Render `<Cockpit>` with the caller-supplied handlers via `ink.render`.
+ *  - Return `waitUntilExit` and `restore` for the caller to await + clean up.
+ *
+ * Domain-specific boot (loading config, building watchers, scheduling health
+ * checks, docker tailers) lives in the consumer's `dev` command; this entry
+ * stays narrow and reusable.
+ */
+import { type Instance } from 'ink';
+import { type CockpitProps } from './cockpit/Cockpit.js';
+import type { Profile } from './core/types.js';
+export interface RunCockpitOptions extends CockpitProps {
+    /** Optional profile — used to seed helpConfig (sources + defaultPage). */
+    profile?: Profile;
+    /** Skip the alternate-screen-buffer dance (e.g. for tests). Default: false. */
+    noAltScreen?: boolean;
+}
+export interface RunCockpitHandle {
+    /** Promise that resolves when the user quits (q or Ctrl-C with exitOnCtrlC). */
+    waitUntilExit: () => Promise<void>;
+    /** Manually restore the screen buffer. Called automatically on exit. */
+    restore: () => void;
+    /** Underlying Ink render instance. */
+    ink: Instance;
+}
+export declare function runCockpit(opts?: RunCockpitOptions): RunCockpitHandle;
+//# sourceMappingURL=runCockpit.d.ts.map

package/dist/runCockpit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runCockpit.d.ts","sourceRoot":"","sources":["../src/runCockpit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,KAAK,CAAC;AAC5C,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAElE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C,MAAM,WAAW,iBAAkB,SAAQ,YAAY;IACrD,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,wEAAwE;IACxE,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,sCAAsC;IACtC,GAAG,EAAE,QAAQ,CAAC;CACf;AAKD,wBAAgB,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,gBAAgB,CAyDzE"}

package/dist/runCockpit.js

@@ -0,0 +1,75 @@
+/**
+ * runCockpit — boot the cockpit TUI.
+ *
+ * Responsibilities (Phase 3, shell-only):
+ *  - Switch the terminal into the alternate-screen buffer (so the cockpit fills
+ *    the window without scrolling shell history out of view; restored on exit
+ *    or uncaughtException).
+ *  - Seed `cockpitStore.helpConfig` from `profile.helpSources` + `profile.defaultHelpPage`.
+ *  - Render `<Cockpit>` with the caller-supplied handlers via `ink.render`.
+ *  - Return `waitUntilExit` and `restore` for the caller to await + clean up.
+ *
+ * Domain-specific boot (loading config, building watchers, scheduling health
+ * checks, docker tailers) lives in the consumer's `dev` command; this entry
+ * stays narrow and reusable.
+ */
+import React from 'react';
+import { render } from 'ink';
+import { Cockpit } from './cockpit/Cockpit.js';
+import { cockpitStore } from './cockpit/state/store.js';
+const ENTER_ALT_SCREEN = '\x1b[?1049h\x1b[H';
+const EXIT_ALT_SCREEN = '\x1b[?1049l';
+export function runCockpit(opts = {}) {
+    const { profile, noAltScreen, ...cockpitProps } = opts;
+    // Seed helpConfig from profile.
+    if (profile) {
+        const sources = (profile.helpSources ?? []).map((src) => ({
+            page: src.path == null && src.content != null
+                ? {
+                    slug: src.id,
+                    title: src.title ?? src.id,
+                    path: '',
+                    body: src.content,
+                }
+                : undefined,
+            path: src.path,
+            id: src.id,
+            omit: src.omit,
+        }));
+        cockpitStore.getState().setHelpConfig({
+            sources,
+            defaultPage: profile.defaultHelpPage,
+        });
+    }
+    // Alternate-screen buffer.
+    let restored = false;
+    const restore = () => {
+        if (restored)
+            return;
+        restored = true;
+        if (!noAltScreen) {
+            process.stdout.write(EXIT_ALT_SCREEN);
+        }
+    };
+    if (!noAltScreen) {
+        process.stdout.write(ENTER_ALT_SCREEN);
+        process.once('exit', restore);
+        process.once('uncaughtException', (err) => {
+            restore();
+            throw err;
+        });
+    }
+    const ink = render(React.createElement(Cockpit, cockpitProps), { exitOnCtrlC: true });
+    return {
+        waitUntilExit: async () => {
+            try {
+                await ink.waitUntilExit();
+            }
+            finally {
+                restore();
+            }
+        },
+        restore,
+        ink,
+    };
+}

package/dist/watchers/manager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * WatcherManager — orchestrates chokidar filesystem watchers and per-repo
+ * watcher subprocesses.
+ *
+ * Responsibilities:
+ *  - Subscribe to chokidar for the union of all repo discover globs.
+ *  - On file change in an idle repo → spawn the repo's watch command.
+ *  - On watcher exit (code 0) → mark repo idle; non-zero → failing.
+ *  - Trigger reactive lint via scheduleLint on each change.
+ *
+ * Public API: start(), stop(), toggle(repoName), rebuild(repoName), lint(repoName).
+ *
+ * All subprocess work goes through `core/subprocess.spawnStream` (DRY).
+ */
+import type { NormalizedRepoConfig } from './types.js';
+import type { LintStatus, OutputLine, RepoStatus } from '../cockpit/state/store.js';
+import { spawnStream } from '../core/subprocess.js';
+export interface WatcherManagerDeps {
+    appendOutput: (line: OutputLine) => void;
+    setRepoStatus: (key: string, status: RepoStatus) => void;
+    /** Lint result — never mutates watcher status. */
+    setLintStatus: (key: string, lintStatus: LintStatus) => void;
+    /** Inject a custom spawner (tests). Defaults to spawnStream. */
+    spawn?: typeof spawnStream;
+    /**
+     * Optional build-outcome notification hook. Called when a watcher exits
+     * with a state transition (clean→fail or fail→clean). Pass `emitEvent`
+     * from `core/notifier` here to wire OS notifications.
+     */
+    onBuildOutcome?: (repoName: string, outcome: 'build-failed' | 'build-recovered') => void;
+}
+export interface ManagedRepo {
+    config: NormalizedRepoConfig;
+    /** Absolute path to the repo's root directory. */
+    rootDir: string;
+}
+type FsEventListener = (filePath: string) => void;
+export declare class WatcherManager {
+    private readonly repos;
+    private readonly prefixEntries;
+    private readonly handles;
+    private fsWatcher;
+    private readonly deps;
+    private readonly buildOutcomes;
+    private readonly fsEventListeners;
+    constructor(repos: ManagedRepo[], deps: WatcherManagerDeps);
+    start(): void;
+    stop(): Promise<void>;
+    toggle(repoName: string): void;
+    rebuild(repoName: string): void;
+    lint(repoName: string): void;
+    /**
+     * Subscribe to filesystem-event notifications. The listener is called for
+     * every detected change before the watcher-launch logic. Returns an
+     * unsubscribe function.
+     */
+    subscribeFsEvents(listener: FsEventListener): () => void;
+    private handleChange;
+    private spawnWatcher;
+    private killHandle;
+}
+export {};
+//# sourceMappingURL=manager.d.ts.map

package/dist/watchers/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../../src/watchers/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,EAAE,WAAW,EAAsB,MAAM,uBAAuB,CAAC;AAIxE,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IACzD,kDAAkD;IAClD,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,KAAK,IAAI,CAAC;IAC7D,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,WAAW,CAAC;IAC3B;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,iBAAiB,KAAK,IAAI,CAAC;CAC1F;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;CACjB;AAyBD,KAAK,eAAe,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;AAElD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;IAC7D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAyB;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;IACjE,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8C;IAC5E,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAmC;gBAExD,KAAK,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,kBAAkB;IAe1D,KAAK,IAAI,IAAI;IAgCP,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAiB3B,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAU9B,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAK/B,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAc5B;;;;OAIG;IACH,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;IASxD,OAAO,CAAC,YAAY;YAyBN,YAAY;IA8E1B,OAAO,CAAC,UAAU;CAOnB"}

package/dist/watchers/manager.js

@@ -0,0 +1,239 @@
+/**
+ * WatcherManager — orchestrates chokidar filesystem watchers and per-repo
+ * watcher subprocesses.
+ *
+ * Responsibilities:
+ *  - Subscribe to chokidar for the union of all repo discover globs.
+ *  - On file change in an idle repo → spawn the repo's watch command.
+ *  - On watcher exit (code 0) → mark repo idle; non-zero → failing.
+ *  - Trigger reactive lint via scheduleLint on each change.
+ *
+ * Public API: start(), stop(), toggle(repoName), rebuild(repoName), lint(repoName).
+ *
+ * All subprocess work goes through `core/subprocess.spawnStream` (DRY).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import chokidar from 'chokidar';
+import { spawnStream } from '../core/subprocess.js';
+import { mapPathToRepo } from './path-mapper.js';
+import { scheduleLint, runAllLints } from '../lint/reactive.js';
+/**
+ * Detect WSL2 by reading /proc/version (Linux-only).
+ * Native Linux + macOS don't need polling. Set DEV_COCKPIT_CHOKIDAR_POLLING=1
+ * to force polling as an escape hatch.
+ */
+function detectUsePolling() {
+    if (process.env['DEV_COCKPIT_CHOKIDAR_POLLING'] === '1')
+        return true;
+    try {
+        const version = fs.readFileSync('/proc/version', 'utf8');
+        return /microsoft|wsl/i.test(version);
+    }
+    catch {
+        return false;
+    }
+}
+export class WatcherManager {
+    repos = new Map();
+    prefixEntries = [];
+    handles = new Map();
+    fsWatcher = null;
+    deps;
+    buildOutcomes = new Map();
+    fsEventListeners = new Set();
+    constructor(repos, deps) {
+        this.deps = {
+            appendOutput: deps.appendOutput,
+            setRepoStatus: deps.setRepoStatus,
+            setLintStatus: deps.setLintStatus,
+            spawn: deps.spawn ?? spawnStream,
+            onBuildOutcome: deps.onBuildOutcome ?? null,
+        };
+        for (const repo of repos) {
+            this.repos.set(repo.config.name, repo);
+            this.prefixEntries.push({ name: repo.config.name, rootDir: repo.rootDir });
+        }
+    }
+    start() {
+        if (this.fsWatcher)
+            return;
+        const globs = [];
+        for (const [, managed] of this.repos) {
+            for (const pattern of managed.config.discover) {
+                globs.push(path.join(managed.rootDir, pattern));
+            }
+        }
+        if (globs.length === 0)
+            return;
+        const usePolling = detectUsePolling();
+        this.fsWatcher = chokidar.watch(globs, {
+            usePolling,
+            ignoreInitial: true,
+            ignored: /(^|[/\\])\../,
+        });
+        this.fsWatcher.on('change', (filePath) => this.handleChange(filePath));
+        this.fsWatcher.on('add', (filePath) => this.handleChange(filePath));
+        this.fsWatcher.on('error', (err) => {
+            this.deps.appendOutput({
+                ts: Date.now(),
+                source: 'watcher',
+                severity: 'error',
+                text: `chokidar error: ${String(err)}`,
+            });
+        });
+    }
+    async stop() {
+        // Snapshot exitCode promises before killing so we can await reap after
+        // SIGTERM is delivered. Without awaiting, Node's event loop keeps the
+        // ChildProcess + stdio socket handles alive, which blocks process exit
+        // on the consumer side.
+        const reaps = [];
+        for (const [name, handle] of this.handles) {
+            reaps.push(handle.exitCode.catch(() => undefined));
+            this.killHandle(name);
+        }
+        await Promise.all(reaps);
+        if (this.fsWatcher) {
+            await this.fsWatcher.close();
+            this.fsWatcher = null;
+        }
+    }
+    toggle(repoName) {
+        const handle = this.handles.get(repoName);
+        if (handle) {
+            this.killHandle(repoName);
+            this.deps.setRepoStatus(repoName, 'idle');
+        }
+        else {
+            void this.spawnWatcher(repoName);
+        }
+    }
+    rebuild(repoName) {
+        this.killHandle(repoName);
+        void this.spawnWatcher(repoName);
+    }
+    lint(repoName) {
+        const managed = this.repos.get(repoName);
+        if (!managed)
+            return;
+        void runAllLints({
+            repoName,
+            repoRootDir: managed.rootDir,
+            lintConfig: managed.config.lint,
+            appendOutput: this.deps.appendOutput,
+            onLintResult: (result) => this.deps.setLintStatus(repoName, result),
+            spawn: this.deps.spawn,
+        });
+    }
+    /**
+     * Subscribe to filesystem-event notifications. The listener is called for
+     * every detected change before the watcher-launch logic. Returns an
+     * unsubscribe function.
+     */
+    subscribeFsEvents(listener) {
+        this.fsEventListeners.add(listener);
+        return () => {
+            this.fsEventListeners.delete(listener);
+        };
+    }
+    // ─── Private ────────────────────────────────────────────────────────────
+    handleChange(filePath) {
+        const repoName = mapPathToRepo(filePath, this.prefixEntries);
+        if (!repoName)
+            return;
+        const managed = this.repos.get(repoName);
+        if (!managed)
+            return;
+        for (const listener of this.fsEventListeners) {
+            listener(filePath);
+        }
+        scheduleLint(filePath, {
+            repoName,
+            repoRootDir: managed.rootDir,
+            lintConfig: managed.config.lint,
+            appendOutput: this.deps.appendOutput,
+            onLintResult: (result) => this.deps.setLintStatus(repoName, result),
+            spawn: this.deps.spawn,
+        });
+        if (!this.handles.has(repoName)) {
+            void this.spawnWatcher(repoName);
+        }
+    }
+    async spawnWatcher(repoName) {
+        const managed = this.repos.get(repoName);
+        if (!managed || !managed.config.watch) {
+            return;
+        }
+        const cmd = managed.config.watch;
+        const [exe, ...args] = cmd.split(/\s+/);
+        if (!exe)
+            return;
+        this.deps.setRepoStatus(repoName, 'running');
+        this.deps.appendOutput({
+            ts: Date.now(),
+            source: repoName,
+            severity: 'info',
+            text: `starting watcher: ${cmd}`,
+        });
+        const handle = this.deps.spawn(exe, args, {
+            cwd: managed.rootDir,
+            onStdout: (line) => this.deps.appendOutput({
+                ts: Date.now(),
+                source: repoName,
+                severity: 'info',
+                text: line,
+            }),
+            onStderr: (line) => this.deps.appendOutput({
+                ts: Date.now(),
+                source: repoName,
+                severity: 'warn',
+                text: line,
+            }),
+        });
+        this.handles.set(repoName, handle);
+        // Capture this spawn's handle identity. If rebuild() replaces the handle
+        // before exitCode resolves, the stale exit handler must not clobber the
+        // new watcher's status.
+        const thisHandle = handle;
+        const code = await handle.exitCode;
+        if (this.handles.get(repoName) !== thisHandle)
+            return;
+        this.handles.delete(repoName);
+        if (code === 0) {
+            this.deps.setRepoStatus(repoName, 'idle');
+            this.deps.appendOutput({
+                ts: Date.now(),
+                source: repoName,
+                severity: 'info',
+                text: `watcher exited cleanly`,
+            });
+            // Transition: fail→clean only (not on first-ever clean exit).
+            if (this.deps.onBuildOutcome && this.buildOutcomes.get(repoName) === 'fail') {
+                this.deps.onBuildOutcome(repoName, 'build-recovered');
+            }
+            this.buildOutcomes.set(repoName, 'success');
+        }
+        else {
+            this.deps.setRepoStatus(repoName, 'failing');
+            this.deps.appendOutput({
+                ts: Date.now(),
+                source: repoName,
+                severity: 'error',
+                text: `watcher exited with code ${code}`,
+            });
+            // Transition: clean→fail only (not on repeated failures).
+            if (this.deps.onBuildOutcome && this.buildOutcomes.get(repoName) !== 'fail') {
+                this.deps.onBuildOutcome(repoName, 'build-failed');
+            }
+            this.buildOutcomes.set(repoName, 'fail');
+        }
+    }
+    killHandle(repoName) {
+        const handle = this.handles.get(repoName);
+        if (handle) {
+            handle.kill('SIGTERM');
+            this.handles.delete(repoName);
+        }
+    }
+}

package/dist/watchers/path-mapper.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure function: maps an absolute file path to the name of the owning repo.
+ *
+ * Strategy: longest-prefix match against each repo's root directory.
+ * Returns null if no repo claims the path.
+ */
+export interface RepoPrefixEntry {
+    name: string;
+    /** Absolute path to the repo root directory. */
+    rootDir: string;
+}
+/**
+ * Finds the repo that owns `filePath` by longest-prefix match on `rootDir`.
+ *
+ * Rules:
+ *  - `rootDir` must be a prefix of `filePath` with a path-separator boundary
+ *    (avoids `/foo-bar` matching `/foo`).
+ *  - When multiple repos match, the one with the longest `rootDir` wins.
+ *
+ * @returns the owning repo name, or null if no repo matches.
+ */
+export declare function mapPathToRepo(filePath: string, repos: RepoPrefixEntry[]): string | null;
+//# sourceMappingURL=path-mapper.d.ts.map

package/dist/watchers/path-mapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-mapper.d.ts","sourceRoot":"","sources":["../../src/watchers/path-mapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,EAAE,GAAG,MAAM,GAAG,IAAI,CAevF"}

package/dist/watchers/path-mapper.js

@@ -0,0 +1,29 @@
+/**
+ * Pure function: maps an absolute file path to the name of the owning repo.
+ *
+ * Strategy: longest-prefix match against each repo's root directory.
+ * Returns null if no repo claims the path.
+ */
+/**
+ * Finds the repo that owns `filePath` by longest-prefix match on `rootDir`.
+ *
+ * Rules:
+ *  - `rootDir` must be a prefix of `filePath` with a path-separator boundary
+ *    (avoids `/foo-bar` matching `/foo`).
+ *  - When multiple repos match, the one with the longest `rootDir` wins.
+ *
+ * @returns the owning repo name, or null if no repo matches.
+ */
+export function mapPathToRepo(filePath, repos) {
+    let bestMatch = null;
+    for (const repo of repos) {
+        const prefix = repo.rootDir.endsWith('/') ? repo.rootDir : `${repo.rootDir}/`;
+        const isMatch = filePath === repo.rootDir || filePath.startsWith(prefix);
+        if (isMatch) {
+            if (bestMatch === null || repo.rootDir.length > bestMatch.rootDir.length) {
+                bestMatch = repo;
+            }
+        }
+    }
+    return bestMatch?.name ?? null;
+}