dev-cockpit 0.1.0

package/dist/core/notifier.js

@@ -0,0 +1,100 @@
+export function detectTransitions(prev, next) {
+    const prevMap = new Map();
+    for (const s of prev) {
+        prevMap.set(s.id, s);
+    }
+    const transitions = [];
+    for (const nextStatus of next) {
+        const prevStatus = prevMap.get(nextStatus.id);
+        if (!prevStatus) {
+            if (nextStatus.severity === 'error') {
+                transitions.push({
+                    event: 'health-failed',
+                    id: nextStatus.id,
+                    label: nextStatus.label,
+                    detail: nextStatus.detail,
+                });
+            }
+            continue;
+        }
+        const wasOk = prevStatus.severity !== 'error';
+        const isOk = nextStatus.severity !== 'error';
+        if (wasOk && !isOk) {
+            transitions.push({
+                event: 'health-failed',
+                id: nextStatus.id,
+                label: nextStatus.label,
+                detail: nextStatus.detail,
+            });
+        }
+        else if (!wasOk && isOk) {
+            transitions.push({
+                event: 'health-recovered',
+                id: nextStatus.id,
+                label: nextStatus.label,
+                detail: nextStatus.detail,
+            });
+        }
+    }
+    return transitions;
+}
+export function notify(transition, opts) {
+    const { config, sessionEnabled, sender, appName = 'cockpit' } = opts;
+    if (!sessionEnabled)
+        return;
+    if (!config.enabled)
+        return;
+    if (config.exclude.includes(transition.event))
+        return;
+    const title = `${appName} — ${transition.label}`;
+    const message = transition.detail;
+    if (sender) {
+        sender(title, message);
+        return;
+    }
+    defaultPlatformNotify(title, message);
+}
+/**
+ * OS notification via a detached child process. The child runs independently
+ * (`detached: true`, `stdio: 'ignore'`, `unref()`) so it never enters the
+ * parent's event loop — the cockpit can exit while the notification helper
+ * is still flushing without leaving an unreaped ChildProcess handle.
+ *
+ * Platforms:
+ *  - darwin: `osascript -e 'display notification …'`
+ *  - linux:  `notify-send`
+ *  - other:  silently skipped
+ */
+function defaultPlatformNotify(title, message) {
+    // Lazy require so test environments don't pull child_process at import time.
+    void import('node:child_process').then(({ spawn }) => {
+        try {
+            let child = null;
+            if (process.platform === 'darwin') {
+                const safeTitle = title.replace(/(["\\])/g, '\\$1');
+                const safeMsg = message.replace(/(["\\])/g, '\\$1');
+                child = spawn('osascript', ['-e', `display notification "${safeMsg}" with title "${safeTitle}"`], { detached: true, stdio: 'ignore' });
+            }
+            else if (process.platform === 'linux') {
+                child = spawn('notify-send', [title, message], {
+                    detached: true,
+                    stdio: 'ignore',
+                });
+            }
+            child?.unref();
+        }
+        catch {
+            // Notification is best-effort. Don't crash the cockpit if the helper
+            // binary is missing (e.g. headless Linux without notify-send).
+        }
+    });
+}
+export function notifyTransitions(prev, next, opts) {
+    const transitions = detectTransitions(prev, next);
+    for (const t of transitions) {
+        notify(t, opts);
+    }
+}
+export function emitEvent(event, label, detail, opts) {
+    notify({ event, id: String(event), label, detail }, opts);
+}

package/dist/core/paths.d.ts

@@ -0,0 +1,15 @@
+export interface StatePaths {
+    /** Root state directory for this workspace: `<xdg_state_home>/<appName>/<hash>/` */
+    stateDir: string;
+    /** Lock file to prevent parallel cockpits on the same workspace. */
+    lockFile: string;
+    /** Structured log file for this workspace's session. */
+    logFile: string;
+}
+export interface StatePathsOptions {
+    /** Used as the directory name under XDG_STATE_HOME (e.g. `~/.local/state/<appName>/...`). */
+    appName: string;
+}
+export declare function hashWorkspacePath(workspaceRoot: string): string;
+export declare function getStatePaths(workspaceRoot: string, opts: StatePathsOptions): StatePaths;
+//# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/core/paths.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,UAAU;IACzB,oFAAoF;IACpF,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,iBAAiB,GAAG,UAAU,CAcxF"}

package/dist/core/paths.js

@@ -0,0 +1,18 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export function hashWorkspacePath(workspaceRoot) {
+    return crypto.createHash('sha256').update(workspaceRoot).digest('hex').slice(0, 8);
+}
+export function getStatePaths(workspaceRoot, opts) {
+    const xdgStateHome = process.env['XDG_STATE_HOME'] ?? path.join(os.homedir(), '.local', 'state');
+    const hash = hashWorkspacePath(workspaceRoot);
+    const stateDir = path.join(xdgStateHome, opts.appName, hash);
+    fs.mkdirSync(stateDir, { recursive: true });
+    return {
+        stateDir,
+        lockFile: path.join(stateDir, 'cockpit.lock'),
+        logFile: path.join(stateDir, 'cockpit.log'),
+    };
+}

package/dist/core/subprocess.d.ts

@@ -0,0 +1,20 @@
+import { type Subprocess } from 'execa';
+export interface SpawnOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    onStdout?: (line: string) => void;
+    onStderr?: (line: string) => void;
+}
+export interface ProcessHandle {
+    exitCode: Promise<number>;
+    kill: (signal?: NodeJS.Signals) => void;
+    child: Subprocess;
+}
+export declare function spawnStream(cmd: string, args: string[], opts?: SpawnOptions): ProcessHandle;
+/**
+ * Send SIGTERM to every still-running spawnStream child and await each one's
+ * reap. After {@link sigkillAfterMs} the holdouts are SIGKILLed so the sweep
+ * cannot hang indefinitely on an unresponsive subprocess.
+ */
+export declare function killAllSpawned(sigkillAfterMs?: number): Promise<void>;
+//# sourceMappingURL=subprocess.d.ts.map

package/dist/core/subprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess.d.ts","sourceRoot":"","sources":["../../src/core/subprocess.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,UAAU,EAAE,MAAM,OAAO,CAAC;AAE/C,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1B,IAAI,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,KAAK,IAAI,CAAC;IACxC,KAAK,EAAE,UAAU,CAAC;CACnB;AAWD,wBAAgB,WAAW,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,YAAiB,GACtB,aAAa,CA0Cf;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,cAAc,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBzE"}

package/dist/core/subprocess.js

@@ -0,0 +1,82 @@
+import { execa } from 'execa';
+/**
+ * Module-level registry of every currently-running spawnStream child. Each
+ * spawn auto-registers; auto-deregisters when the child exits. Callers that
+ * own a long-running session (typically the `dev` command) sweep this on
+ * teardown via {@link killAllSpawned} so no rogue subprocess keeps the Node
+ * event loop alive after the cockpit unmounts.
+ */
+const ACTIVE = new Set();
+export function spawnStream(cmd, args, opts = {}) {
+    const child = execa(cmd, args, {
+        cwd: opts.cwd,
+        env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        all: false,
+        lines: true,
+        reject: false,
+        stdout: 'pipe',
+        stderr: 'pipe',
+    });
+    if (opts.onStdout && child.stdout) {
+        child.stdout.on('data', (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split('\n')) {
+                if (line)
+                    opts.onStdout(line);
+            }
+        });
+    }
+    if (opts.onStderr && child.stderr) {
+        child.stderr.on('data', (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split('\n')) {
+                if (line)
+                    opts.onStderr(line);
+            }
+        });
+    }
+    const exitCode = child.then((result) => result.exitCode ?? 0);
+    const handle = {
+        exitCode,
+        kill: (signal = 'SIGTERM') => {
+            child.kill(signal);
+        },
+        child,
+    };
+    ACTIVE.add(handle);
+    void exitCode.finally(() => ACTIVE.delete(handle));
+    return handle;
+}
+/**
+ * Send SIGTERM to every still-running spawnStream child and await each one's
+ * reap. After {@link sigkillAfterMs} the holdouts are SIGKILLed so the sweep
+ * cannot hang indefinitely on an unresponsive subprocess.
+ */
+export async function killAllSpawned(sigkillAfterMs = 1500) {
+    if (ACTIVE.size === 0)
+        return;
+    const handles = Array.from(ACTIVE);
+    for (const h of handles)
+        h.kill('SIGTERM');
+    const reaps = handles.map((h) => h.exitCode.catch(() => undefined));
+    let timer = null;
+    const guard = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            for (const h of handles) {
+                try {
+                    h.kill('SIGKILL');
+                }
+                catch {
+                    // already dead
+                }
+            }
+            resolve();
+        }, sigkillAfterMs);
+    });
+    await Promise.race([Promise.all(reaps), guard]);
+    if (timer)
+        clearTimeout(timer);
+    // After the SIGKILL fallback, drain the original exitCodes so handles are
+    // fully released from the event loop.
+    await Promise.all(reaps);
+}

package/dist/core/types.d.ts

@@ -0,0 +1,125 @@
+import type { Command } from 'commander';
+import type { z } from 'zod';
+import type { HealthCheck } from '../health/types.js';
+import type { BaseCockpitConfig } from './config.js';
+export type Severity = 'ok' | 'warn' | 'error';
+export type RepoStatus = 'idle' | 'running' | 'failing';
+export type LintStatus = 'unknown' | 'pass' | 'fail';
+/** Open: profiles can use any string; built-in panes treat 'docker' as a special kind that disables watch/lint actions. */
+export type RepoKind = 'repo' | 'docker' | (string & {});
+export interface RepoState {
+    name: string;
+    status: RepoStatus;
+    kind: RepoKind;
+}
+export interface HealthStatus {
+    id: string;
+    label: string;
+    severity: Severity;
+    detail: string;
+    remediationKey: string | null;
+}
+export interface OutputLine {
+    ts: number;
+    source: string;
+    severity: 'info' | 'warn' | 'error';
+    text: string;
+}
+export type BuiltinNotifiableEvent = 'health-failed' | 'health-recovered' | 'build-failed' | 'build-recovered';
+export type NotifiableEvent = BuiltinNotifiableEvent | (string & {});
+export interface Transition {
+    event: NotifiableEvent;
+    id: string;
+    label: string;
+    detail: string;
+}
+export interface Watcher {
+    id: string;
+    label?: string;
+    command: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    color?: string;
+    restartOn?: string[];
+    notify?: false | {
+        onTransitionTo?: NotifiableEvent[];
+    };
+}
+export interface Service {
+    name: string;
+    tail?: boolean;
+}
+export interface Repo {
+    id: string;
+    path: string;
+    label?: string;
+}
+export interface Mount {
+    hostPath: string;
+    containerPath: string;
+}
+export interface HelpSource {
+    id: string;
+    title?: string;
+    path?: string;
+    content?: string;
+    omit?: boolean;
+}
+export interface Workspace {
+    root: string;
+}
+/** Dispatched action that briefly banners the active operation. */
+export interface ProfileAsyncActionDispatch {
+    label: string;
+    promise: Promise<void>;
+}
+export interface ProfileCockpitHandlers {
+    /** Triggered by `r` on the Repos pane. Return null to skip. */
+    runRepoAction?: (repoKey: string, repo: RepoState) => ProfileAsyncActionDispatch | null;
+    /** Triggered by `w` for repo-kind entries. Fire-and-forget. */
+    onWatchToggle?: (repoKey: string, repo: RepoState) => void;
+    /** Triggered by `l` for repo-kind entries. Fire-and-forget. */
+    onLint?: (repoKey: string, repo: RepoState) => void;
+    /** Triggered by `e` on the Output pane with the most-recent file:line error (or null). */
+    onOpenError?: (error: {
+        file: string;
+        line: number;
+        service: string;
+        text: string;
+    } | null) => void;
+    /** Per-tab footer legend overrides. */
+    footerLegends?: Record<string, string>;
+}
+export interface ProfileBootContext {
+    /** Parsed cockpit.yaml. Profile narrows the `profile.<appName>` block via configSchemaExt. */
+    config: BaseCockpitConfig;
+    /** Resolved workspace root (profile.discoverer's result, or the config file's dir). */
+    workspaceRoot: string;
+}
+export interface ProfileBootResult {
+    /** Cockpit pane handlers + footer overrides. */
+    cockpitHandlers?: ProfileCockpitHandlers;
+    /** fs-event source piped into useHealth (typically WatcherManager.subscribeFsEvents). */
+    subscribeFsEvents?: (listener: (filePath: string) => void) => () => void;
+    /** Awaited at teardown — release any owned subprocesses, watchers, timers. */
+    cleanup?: () => Promise<void> | void;
+}
+export type ProfileBootHook = (ctx: ProfileBootContext) => ProfileBootResult | Promise<ProfileBootResult>;
+export interface Profile {
+    appName: string;
+    discoverer?: () => Workspace;
+    /**
+     * Returns repos for the Repos pane. Receives the same context as `boot`
+     * so the profile can read its validated `profile.<appName>` namespace.
+     */
+    reposProvider?: (ctx: ProfileBootContext) => Repo[];
+    healthChecks?: HealthCheck[];
+    setupCli?: (program: Command) => void;
+    helpSources?: HelpSource[];
+    defaultHelpPage?: string;
+    configSchemaExt?: z.ZodObject<z.ZodRawShape>;
+    mountCandidatesProvider?: () => Mount[];
+    /** Lifecycle hook — see ProfileBootContext / ProfileBootResult. */
+    boot?: ProfileBootHook;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"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"}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/docker/highlights.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Highlight pattern matcher for log lines.
+ *
+ * Pure: no I/O. Patterns are compiled once via `compileHighlights` and the
+ * resulting matcher is cheap to call per line.
+ *
+ * Severity inference: lines containing "fatal", "error", "exception", or
+ * "stack trace" → 'error'. Lines containing "warning" → 'warn'. Otherwise
+ * 'info'.
+ *
+ * Default patterns ship a domain-neutral minimum (ERROR / FATAL / WARN /
+ * Stack trace). Consumers add language-specific patterns via config or a
+ * profile-specific default.
+ */
+export type HighlightSeverity = 'info' | 'warn' | 'error';
+export interface HighlightMatch {
+    matched: boolean;
+    severity: HighlightSeverity;
+    /** The first matching pattern source, or null. */
+    pattern: string | null;
+    /**
+     * True when the matched pattern represents a NEW error event (eligible for
+     * a notification). False for continuation lines like "Stack trace" that
+     * accompany an already-notified fatal.
+     */
+    isInitiator: boolean;
+}
+export interface CompiledHighlights {
+    patterns: Array<{
+        source: string;
+        regex: RegExp;
+    }>;
+    match: (line: string) => HighlightMatch;
+}
+/**
+ * Domain-neutral default highlight patterns. Case-insensitive substring
+ * matches. Consumers who want language-specific shapes (PHP fatals,
+ * stack frames, framework-specific markers) add them via config.
+ */
+export declare const DEFAULT_HIGHLIGHT_PATTERNS: readonly string[];
+/**
+ * Compile a list of pattern sources into a matcher. Each source is treated
+ * as a case-insensitive substring (regex metacharacters escaped).
+ */
+export declare function compileHighlights(sources: readonly string[]): CompiledHighlights;
+/** One-shot match without an explicit compile step. Slower per call. */
+export declare function matchHighlights(line: string, patterns: readonly string[]): HighlightMatch;
+//# sourceMappingURL=highlights.d.ts.map

package/dist/docker/highlights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlights.d.ts","sourceRoot":"","sources":["../../src/docker/highlights.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,kDAAkD;IAClD,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnD,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,cAAc,CAAC;CACzC;AAED;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,MAAM,EAKvD,CAAC;AA4BF;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,kBAAkB,CAsBhF;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAEzF"}

package/dist/docker/highlights.js

@@ -0,0 +1,79 @@
+/**
+ * Highlight pattern matcher for log lines.
+ *
+ * Pure: no I/O. Patterns are compiled once via `compileHighlights` and the
+ * resulting matcher is cheap to call per line.
+ *
+ * Severity inference: lines containing "fatal", "error", "exception", or
+ * "stack trace" → 'error'. Lines containing "warning" → 'warn'. Otherwise
+ * 'info'.
+ *
+ * Default patterns ship a domain-neutral minimum (ERROR / FATAL / WARN /
+ * Stack trace). Consumers add language-specific patterns via config or a
+ * profile-specific default.
+ */
+/**
+ * Domain-neutral default highlight patterns. Case-insensitive substring
+ * matches. Consumers who want language-specific shapes (PHP fatals,
+ * stack frames, framework-specific markers) add them via config.
+ */
+export const DEFAULT_HIGHLIGHT_PATTERNS = [
+    'ERROR',
+    'FATAL',
+    'WARN',
+    'Stack trace',
+];
+function inferSeverity(source) {
+    const lower = source.toLowerCase();
+    if (lower.includes('fatal') ||
+        lower.includes('error') ||
+        lower.includes('exception') ||
+        lower.includes('stack trace')) {
+        return 'error';
+    }
+    if (lower.includes('warning') || lower.includes('warn'))
+        return 'warn';
+    return 'info';
+}
+/**
+ * Initiator = a NEW error event (worth notifying). Continuation = a
+ * follow-on line (stack frame, trace header) that accompanies an
+ * initiator already notified — should still highlight in Output but
+ * shouldn't trigger its own notification.
+ */
+function isInitiatorPattern(source) {
+    const lower = source.toLowerCase();
+    if (lower.includes('stack trace'))
+        return false;
+    return true;
+}
+/**
+ * Compile a list of pattern sources into a matcher. Each source is treated
+ * as a case-insensitive substring (regex metacharacters escaped).
+ */
+export function compileHighlights(sources) {
+    const patterns = sources.map((source) => ({
+        source,
+        regex: new RegExp(source.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i'),
+    }));
+    return {
+        patterns,
+        match(line) {
+            for (const p of patterns) {
+                if (p.regex.test(line)) {
+                    return {
+                        matched: true,
+                        severity: inferSeverity(p.source),
+                        pattern: p.source,
+                        isInitiator: isInitiatorPattern(p.source),
+                    };
+                }
+            }
+            return { matched: false, severity: 'info', pattern: null, isInitiator: false };
+        },
+    };
+}
+/** One-shot match without an explicit compile step. Slower per call. */
+export function matchHighlights(line, patterns) {
+    return compileHighlights(patterns).match(line);
+}

package/dist/docker/logs.d.ts

@@ -0,0 +1,84 @@
+/**
+ * DockerLogTailer — tails `docker compose logs -f` for configured services,
+ * routes lines into the Output pane, surfaces highlight matches into the
+ * Recent Errors ring buffer, and emits OS notifications via the shared
+ * notifier.
+ *
+ * Discipline:
+ *   - Subprocess goes through `core/subprocess.spawnStream` (DRY).
+ *   - Notifications go through `core/notifier.emitEvent` (DRY).
+ *   - Notification debounce: identical errors (same file:line OR same text
+ *     fingerprint) within `DEBOUNCE_MS` produce ONE notification, not N.
+ *
+ * Line format: `docker compose logs --no-color` emits `<service>  | <body>`
+ * (variable spaces). The leading service token is parsed; the rest is the
+ * line body.
+ */
+import { spawnStream } from '../core/subprocess.js';
+import { type NotifyOptions } from '../core/notifier.js';
+import type { OutputLine, RecentError } from '../cockpit/state/store.js';
+import type { NotifiableEvent } from '../core/types.js';
+/** Debounce window for identical errors (default 30s). */
+export declare const DEBOUNCE_MS = 30000;
+/** Liveness threshold — a service silent for this long is treated as down. */
+export declare const SILENT_THRESHOLD_MS = 90000;
+export interface DockerLogTailerOptions {
+    workspaceRoot: string;
+    services: readonly string[];
+    /** Pattern sources from cockpit.yaml `highlights[]` (or defaults). */
+    highlightPatterns: readonly string[];
+    /** Push a line into the Output pane. */
+    appendOutput: (line: OutputLine) => void;
+    /** Push a recent-error entry. */
+    pushRecentError: (err: RecentError) => void;
+    /**
+     * Notification options. Read fresh on every notify so the session-toggle
+     * keystroke takes effect immediately.
+     */
+    notifyOpts: () => NotifyOptions;
+    /** Optional explicit compose-file path. If absent, docker auto-discovers. */
+    composeFile?: string;
+    /**
+     * Event name emitted on a highlighted error initiator. Defaults to
+     * 'docker-error'. Consumers with existing `notifications.exclude` lists
+     * keyed on a specific name can override (e.g. 'php-fatal').
+     */
+    errorEventName?: NotifiableEvent;
+    /** Inject a custom spawner for tests. */
+    spawn?: typeof spawnStream;
+    /** Inject a clock for tests (defaults to Date.now). */
+    now?: () => number;
+}
+export declare class DockerLogTailer {
+    private readonly opts;
+    private handle;
+    private compiled;
+    private spawn;
+    private now;
+    /** fingerprint → timestamp of last notify. Used for debounce. */
+    private lastNotified;
+    private serviceState;
+    private liveCheckInterval;
+    constructor(opts: DockerLogTailerOptions);
+    /**
+     * Resolve the docker-compose file path. If `opts.composeFile` is set
+     * and exists, use it. Otherwise return null and let docker auto-discover.
+     */
+    private resolveComposeFile;
+    start(): void;
+    stop(): Promise<void>;
+    /**
+     * Parse a single docker-compose log line: `<service>  | <body>`.
+     * Returns null if the line doesn't match (e.g. compose preamble).
+     */
+    parseLine(raw: string): {
+        service: string;
+        body: string;
+    } | null;
+    /** Public for testing — exercise per-line logic without a real subprocess. */
+    handleLine(raw: string): void;
+    private maybeNotifyError;
+    /** If a tracked service has been silent past the threshold, notify once. */
+    private checkLiveness;
+}
+//# sourceMappingURL=logs.d.ts.map

package/dist/docker/logs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logs.d.ts","sourceRoot":"","sources":["../../src/docker/logs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,WAAW,EAAsB,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAa,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExD,0DAA0D;AAC1D,eAAO,MAAM,WAAW,QAAS,CAAC;AAElC,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,sEAAsE;IACtE,iBAAiB,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,wCAAwC;IACxC,YAAY,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,IAAI,CAAC;IACzC,iCAAiC;IACjC,eAAe,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;IAC5C;;;OAGG;IACH,UAAU,EAAE,MAAM,aAAa,CAAC;IAChC,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,eAAe,CAAC;IACjC,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,WAAW,CAAC;IAC3B,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAOD,qBAAa,eAAe;IAUd,OAAO,CAAC,QAAQ,CAAC,IAAI;IATjC,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,KAAK,CAAqB;IAClC,OAAO,CAAC,GAAG,CAAe;IAC1B,iEAAiE;IACjE,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,YAAY,CAAmC;IACvD,OAAO,CAAC,iBAAiB,CAA+B;gBAE3B,IAAI,EAAE,sBAAsB;IASzD;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAU1B,KAAK,IAAI,IAAI;IAwBP,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB3B;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAMhE,8EAA8E;IAC9E,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAwC7B,OAAO,CAAC,gBAAgB;IAqBxB,4EAA4E;IAC5E,OAAO,CAAC,aAAa;CAetB"}