watchfix 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,99 @@
+# watchfix
+
+CLI tool that watches logs, detects errors, and dispatches AI agents to fix them.
+
+## Features
+
+- **Log watching**: Monitor file logs, command output, or Docker container logs
+- **Error detection**: Configurable patterns to identify errors in your logs
+- **AI-powered fixes**: Automatically dispatch Claude, Gemini, or Codex to analyze and fix errors
+- **Context awareness**: Generates relevant context files for AI agents
+- **Deduplication**: Groups similar errors to avoid redundant fixes
+- **Daemon mode**: Run in the background on Linux/macOS
+
+## Installation
+
+```bash
+npm install -g watchfix
+```
+
+## Requirements
+
+- Node.js 18+
+- One of the following AI CLI tools:
+  - [Claude CLI](https://github.com/anthropics/claude-code)
+  - [Gemini CLI](https://github.com/google-gemini/gemini-cli)
+  - [Codex CLI](https://github.com/openai/codex)
+
+## Quick Start
+
+1. Initialize a configuration file in your project:
+
+```bash
+watchfix init
+```
+
+2. Edit `watchfix.yaml` to configure your log sources and error patterns:
+
+```yaml
+version: "1"
+
+sources:
+  - name: app
+    type: file
+    path: ./logs/app.log
+
+patterns:
+  - name: node-error
+    regex: "Error: .+"
+    severity: error
+
+agent:
+  provider: claude
+```
+
+3. Start watching logs:
+
+```bash
+watchfix watch
+```
+
+4. When an error is detected, fix it:
+
+```bash
+watchfix fix <error-id>
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `watchfix init` | Create `watchfix.yaml` in current directory |
+| `watchfix watch` | Watch logs in foreground (use `--daemon` for background) |
+| `watchfix fix [id]` | Analyze and fix a specific error (or `--all` for all pending) |
+| `watchfix show <id>` | Show full error details and analysis |
+| `watchfix status` | Show watcher state and pending errors |
+| `watchfix stop` | Stop background watcher |
+| `watchfix ignore <id>` | Mark error as ignored |
+| `watchfix logs` | Show activity log |
+| `watchfix clean` | Remove old context files |
+| `watchfix config validate` | Validate configuration file |
+
+### Global Options
+
+- `-c, --config <path>`: Use alternate config file
+- `--verbose`: Increase output verbosity
+- `-q, --quiet`: Suppress non-essential output
+
+## Platform Notes
+
+- **Daemon mode** (`watchfix watch --daemon`) is only available on Linux and macOS
+- Windows users should run `watchfix watch` in a terminal window or use a process manager
+
+## Documentation
+
+For detailed configuration options and advanced usage, see the [specification document](./spec/watchfix-spec-v8.md).
+
+## License
+
+[MIT](./LICENSE)

package/dist/agents/base.d.ts

@@ -0,0 +1,19 @@
+import type { Agent, AgentConfig, AgentResult } from './types.js';
+import { Logger } from '../utils/logger.js';
+type BaseAgentOptions = {
+    projectRoot: string;
+    logger?: Logger;
+    terminalEnabled?: boolean;
+};
+export declare class BaseAgent implements Agent {
+    config: AgentConfig;
+    private readonly projectRoot;
+    private readonly logger;
+    private readonly terminalEnabled;
+    constructor(config: AgentConfig, options: BaseAgentOptions);
+    analyze(contextPath: string): Promise<AgentResult>;
+    fix(contextPath: string): Promise<AgentResult>;
+    private run;
+    private executeOnce;
+}
+export {};

package/dist/agents/base.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { Logger } from '../utils/logger.js';
+const KILL_GRACE_PERIOD_MS = 5000;
+const PROMPTS = {
+    analyze: (contextPath) => `Read ${contextPath} and follow the instructions.`,
+    fix: (contextPath) => `Read ${contextPath} and follow the instructions.`,
+};
+const outputPathForContext = (contextPath) => {
+    if (contextPath.endsWith('-analyze.md')) {
+        return contextPath.replace(/-analyze\.md$/, '-analysis.yaml');
+    }
+    if (contextPath.endsWith('-fix.md')) {
+        return contextPath.replace(/-fix\.md$/, '-result.yaml');
+    }
+    return null;
+};
+export class BaseAgent {
+    config;
+    projectRoot;
+    logger;
+    terminalEnabled;
+    constructor(config, options) {
+        this.config = config;
+        this.projectRoot = options.projectRoot;
+        this.terminalEnabled = options.terminalEnabled ?? true;
+        this.logger =
+            options.logger ??
+                new Logger({ rootDir: this.projectRoot, terminalEnabled: this.terminalEnabled });
+    }
+    async analyze(contextPath) {
+        return await this.run('analyze', contextPath);
+    }
+    async fix(contextPath) {
+        return await this.run('fix', contextPath);
+    }
+    async run(mode, contextPath) {
+        const attempts = Math.max(0, this.config.retries) + 1;
+        let lastResult = null;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            lastResult = await this.executeOnce(mode, contextPath);
+            if (lastResult.success) {
+                return lastResult;
+            }
+            if (attempt < attempts) {
+                this.logger.warn(`Agent ${this.config.provider} ${mode} attempt ${attempt} failed; retrying`);
+            }
+        }
+        return (lastResult ?? {
+            success: false,
+            stdout: '',
+            stderr: 'Agent execution failed',
+            exitCode: -1,
+            timedOut: false,
+            outputFileExists: false,
+        });
+    }
+    async executeOnce(mode, contextPath) {
+        const prompt = PROMPTS[mode](contextPath);
+        const command = this.config.command;
+        const args = [...this.config.args, prompt];
+        const resolvedContextPath = path.isAbsolute(contextPath)
+            ? contextPath
+            : path.resolve(this.projectRoot, contextPath);
+        const outputPathRaw = outputPathForContext(resolvedContextPath);
+        const outputPath = outputPathRaw && !path.isAbsolute(outputPathRaw)
+            ? path.resolve(this.projectRoot, outputPathRaw)
+            : outputPathRaw;
+        return await new Promise((resolve) => {
+            const child = spawn(command, args, {
+                cwd: this.projectRoot,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let stdout = '';
+            let stderr = '';
+            let timedOut = false;
+            let resolved = false;
+            const finalize = (result) => {
+                if (resolved) {
+                    return;
+                }
+                resolved = true;
+                resolve(result);
+            };
+            const timeoutId = setTimeout(() => {
+                timedOut = true;
+                child.kill('SIGTERM');
+                const killTimer = setTimeout(() => {
+                    if (child.exitCode === null && child.signalCode === null) {
+                        child.kill('SIGKILL');
+                    }
+                }, KILL_GRACE_PERIOD_MS);
+                child.once('close', () => clearTimeout(killTimer));
+            }, this.config.timeout);
+            if (child.stdout) {
+                child.stdout.on('data', (data) => {
+                    stdout += String(data);
+                });
+            }
+            if (child.stderr) {
+                child.stderr.on('data', (data) => {
+                    const chunk = String(data);
+                    stderr += chunk;
+                    if (this.config.stderrIsProgress && this.terminalEnabled) {
+                        process.stderr.write(chunk);
+                    }
+                });
+            }
+            child.on('error', (error) => {
+                clearTimeout(timeoutId);
+                const outputFileExists = outputPath ? fs.existsSync(outputPath) : false;
+                finalize({
+                    success: false,
+                    stdout,
+                    stderr: error.message,
+                    exitCode: -1,
+                    timedOut: false,
+                    outputFileExists,
+                });
+            });
+            child.on('close', (code) => {
+                clearTimeout(timeoutId);
+                const outputFileExists = outputPath ? fs.existsSync(outputPath) : false;
+                const trimmedStderr = stderr.trim();
+                if (trimmedStderr && !this.config.stderrIsProgress) {
+                    this.logger.warn(`Agent stderr: ${trimmedStderr}`);
+                }
+                finalize({
+                    success: code === 0 && !timedOut,
+                    stdout,
+                    stderr,
+                    exitCode: code ?? -1,
+                    timedOut,
+                    outputFileExists,
+                });
+            });
+        });
+    }
+}

package/dist/agents/claude.d.ts

@@ -0,0 +1,11 @@
+import type { AgentConfig } from './types.js';
+import { BaseAgent } from './base.js';
+import type { Logger } from '../utils/logger.js';
+export type ClaudeAgentOptions = {
+    projectRoot: string;
+    logger?: Logger;
+    terminalEnabled?: boolean;
+};
+export declare class ClaudeAgent extends BaseAgent {
+    constructor(config: AgentConfig, options: ClaudeAgentOptions);
+}

package/dist/agents/claude.js

@@ -0,0 +1,6 @@
+import { BaseAgent } from './base.js';
+export class ClaudeAgent extends BaseAgent {
+    constructor(config, options) {
+        super(config, options);
+    }
+}

package/dist/agents/codex.d.ts

@@ -0,0 +1,11 @@
+import type { AgentConfig } from './types.js';
+import { BaseAgent } from './base.js';
+import type { Logger } from '../utils/logger.js';
+export type CodexAgentOptions = {
+    projectRoot: string;
+    logger?: Logger;
+    terminalEnabled?: boolean;
+};
+export declare class CodexAgent extends BaseAgent {
+    constructor(config: AgentConfig, options: CodexAgentOptions);
+}

package/dist/agents/codex.js

@@ -0,0 +1,6 @@
+import { BaseAgent } from './base.js';
+export class CodexAgent extends BaseAgent {
+    constructor(config, options) {
+        super(config, options);
+    }
+}

package/dist/agents/defaults.d.ts

@@ -0,0 +1,21 @@
+export declare const AGENT_DEFAULTS: {
+    readonly claude: {
+        readonly command: "claude";
+        readonly args: readonly ["--model", "sonnet", "--dangerously-skip-permissions", "-p"];
+        readonly stderrIsProgress: false;
+    };
+    readonly gemini: {
+        readonly command: "gemini";
+        readonly args: readonly ["--yolo", "-p"];
+        readonly stderrIsProgress: true;
+    };
+    readonly codex: {
+        readonly command: "codex";
+        readonly args: readonly ["exec", "--yolo"];
+        readonly stderrIsProgress: true;
+    };
+};
+export declare const AGENT_CONFIG_DEFAULTS: {
+    readonly timeout: number;
+    readonly retries: 2;
+};

package/dist/agents/defaults.js

@@ -0,0 +1,21 @@
+export const AGENT_DEFAULTS = {
+    claude: {
+        command: "claude",
+        args: ["--model", "sonnet", "--dangerously-skip-permissions", "-p"],
+        stderrIsProgress: false,
+    },
+    gemini: {
+        command: "gemini",
+        args: ["--yolo", "-p"],
+        stderrIsProgress: true,
+    },
+    codex: {
+        command: "codex",
+        args: ["exec", "--yolo"],
+        stderrIsProgress: true,
+    },
+};
+export const AGENT_CONFIG_DEFAULTS = {
+    timeout: 5 * 60 * 1000,
+    retries: 2,
+};

package/dist/agents/gemini.d.ts

@@ -0,0 +1,11 @@
+import type { AgentConfig } from './types.js';
+import { BaseAgent } from './base.js';
+import type { Logger } from '../utils/logger.js';
+export type GeminiAgentOptions = {
+    projectRoot: string;
+    logger?: Logger;
+    terminalEnabled?: boolean;
+};
+export declare class GeminiAgent extends BaseAgent {
+    constructor(config: AgentConfig, options: GeminiAgentOptions);
+}

package/dist/agents/gemini.js

@@ -0,0 +1,6 @@
+import { BaseAgent } from './base.js';
+export class GeminiAgent extends BaseAgent {
+    constructor(config, options) {
+        super(config, options);
+    }
+}

package/dist/agents/index.d.ts

@@ -0,0 +1,19 @@
+import type { Agent, AgentProvider } from './types.js';
+import type { Logger } from '../utils/logger.js';
+export type AgentConfigInput = {
+    provider: AgentProvider;
+    command?: string;
+    args?: string[];
+    stderrIsProgress?: boolean;
+    timeout?: number;
+    retries?: number;
+};
+export type CreateAgentOptions = {
+    projectRoot: string;
+    logger?: Logger;
+    terminalEnabled?: boolean;
+};
+export type AgentConfigOverrides = Omit<AgentConfigInput, 'provider'>;
+export declare function createAgent(provider: AgentProvider, config: AgentConfigOverrides, options: CreateAgentOptions): Agent;
+export declare function createAgent(provider: AgentProvider, options: CreateAgentOptions): Agent;
+export declare function createAgent(config: AgentConfigInput, options: CreateAgentOptions): Agent;

package/dist/agents/index.js

@@ -0,0 +1,63 @@
+import { AGENT_CONFIG_DEFAULTS, AGENT_DEFAULTS } from './defaults.js';
+import { checkCliExists } from '../utils/process.js';
+import { ClaudeAgent } from './claude.js';
+import { GeminiAgent } from './gemini.js';
+import { CodexAgent } from './codex.js';
+function resolveAgentConfig(input) {
+    const defaults = AGENT_DEFAULTS[input.provider];
+    return {
+        provider: input.provider,
+        command: input.command ?? defaults.command,
+        args: input.args ? [...input.args] : [...defaults.args],
+        stderrIsProgress: input.stderrIsProgress ?? defaults.stderrIsProgress,
+        timeout: input.timeout ?? AGENT_CONFIG_DEFAULTS.timeout,
+        retries: input.retries ?? AGENT_CONFIG_DEFAULTS.retries,
+    };
+}
+function assertCliExists(command) {
+    const result = checkCliExists(command);
+    if (!result.exists) {
+        const detail = result.error ? ` (${result.error})` : '';
+        throw new Error(`Agent CLI '${command}' not found${detail}`);
+    }
+}
+const isCreateAgentOptions = (value) => typeof value.projectRoot === 'string';
+export function createAgent(providerOrConfig, configOrOptions, maybeOptions) {
+    let config;
+    let options;
+    if (typeof providerOrConfig === 'string') {
+        const provider = providerOrConfig;
+        if (isCreateAgentOptions(configOrOptions)) {
+            config = { provider };
+            options = configOrOptions;
+        }
+        else {
+            if (!maybeOptions) {
+                throw new Error('createAgent requires options with projectRoot');
+            }
+            config = { provider, ...configOrOptions };
+            options = maybeOptions;
+        }
+    }
+    else {
+        config = providerOrConfig;
+        if (!isCreateAgentOptions(configOrOptions)) {
+            throw new Error('createAgent requires options with projectRoot');
+        }
+        options = configOrOptions;
+    }
+    const resolvedConfig = resolveAgentConfig(config);
+    assertCliExists(resolvedConfig.command);
+    switch (resolvedConfig.provider) {
+        case 'claude':
+            return new ClaudeAgent(resolvedConfig, options);
+        case 'gemini':
+            return new GeminiAgent(resolvedConfig, options);
+        case 'codex':
+            return new CodexAgent(resolvedConfig, options);
+        default: {
+            const exhaustive = resolvedConfig.provider;
+            throw new Error(`Unsupported agent provider: ${exhaustive}`);
+        }
+    }
+}

package/dist/agents/types.d.ts

@@ -0,0 +1,22 @@
+export type AgentProvider = 'claude' | 'gemini' | 'codex';
+export interface AgentConfig {
+    provider: AgentProvider;
+    command: string;
+    args: string[];
+    stderrIsProgress: boolean;
+    timeout: number;
+    retries: number;
+}
+export interface AgentResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    outputFileExists: boolean;
+}
+export interface Agent {
+    config: AgentConfig;
+    analyze(contextPath: string): Promise<AgentResult>;
+    fix(contextPath: string): Promise<AgentResult>;
+}

package/dist/agents/types.js

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

package/dist/cli/commands/clean.d.ts

@@ -0,0 +1,9 @@
+type CleanOptions = {
+    config?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+};
+export declare const cleanCommand: (options: CleanOptions) => Promise<void>;
+export {};

package/dist/cli/commands/clean.js

@@ -0,0 +1,173 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { loadConfig } from '../../config/loader.js';
+import { Database } from '../../db/index.js';
+import { getErrorsByStatus } from '../../db/queries.js';
+import { checkSchemaVersion, initializeSchema } from '../../db/schema.js';
+import { UserError } from '../../utils/errors.js';
+const DAY_MS = 24 * 60 * 60 * 1000;
+const buildDatabasePath = (rootDir) => path.join(rootDir, '.watchfix', 'errors.db');
+const buildContextDir = (rootDir) => path.join(rootDir, '.watchfix', 'context');
+const parseContextFilename = (filename) => {
+    const match = filename.match(/^(\d{4}-\d{2}-\d{2})-error-(\d+)-attempt-\d+-/);
+    if (!match) {
+        return null;
+    }
+    const errorId = Number.parseInt(match[2] ?? '', 10);
+    if (!Number.isFinite(errorId)) {
+        return null;
+    }
+    return { date: match[1], errorId };
+};
+const parseDatePrefix = (dateValue) => {
+    const parsed = Date.parse(`${dateValue}T00:00:00Z`);
+    if (Number.isNaN(parsed)) {
+        return null;
+    }
+    return parsed;
+};
+const formatSize = (bytes) => {
+    if (bytes <= 0) {
+        return '0 B';
+    }
+    const mb = bytes / (1024 * 1024);
+    if (mb >= 1) {
+        return `${mb.toFixed(1)} MB`;
+    }
+    const kb = bytes / 1024;
+    return `${Math.max(1, Math.round(kb))} KB`;
+};
+const promptForConfirmation = async (label) => {
+    if (!process.stdin.isTTY) {
+        throw new UserError('Cannot prompt for confirmation in non-interactive mode. Use --force to proceed.');
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    try {
+        const answer = await rl.question(`${label} [y/N] `);
+        const normalized = answer.trim().toLowerCase();
+        return normalized === 'y' || normalized === 'yes';
+    }
+    finally {
+        rl.close();
+    }
+};
+const findInProgressErrorIds = (db) => {
+    const inProgress = getErrorsByStatus(db, ['analyzing', 'fixing']);
+    return new Set(inProgress.map((error) => error.id));
+};
+const loadContextFiles = (contextDir, rootDir) => {
+    let entries;
+    try {
+        entries = fs.readdirSync(contextDir, { withFileTypes: true });
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return [];
+        }
+        throw new UserError(`Failed to read context directory ${contextDir}: ${err.message ?? String(err)}`);
+    }
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.isFile()) {
+            continue;
+        }
+        const parsed = parseContextFilename(entry.name);
+        if (!parsed) {
+            continue;
+        }
+        const fullPath = path.join(contextDir, entry.name);
+        let stats;
+        try {
+            stats = fs.statSync(fullPath);
+        }
+        catch {
+            continue;
+        }
+        files.push({
+            filename: entry.name,
+            fullPath,
+            relativePath: path.relative(rootDir, fullPath),
+            errorId: parsed.errorId,
+            date: parsed.date,
+            sizeBytes: stats.size,
+        });
+    }
+    return files;
+};
+const selectFilesToRemove = (files, inProgress, maxAgeDays) => {
+    const cutoffMs = Date.now() - maxAgeDays * DAY_MS;
+    return files.filter((file) => {
+        if (inProgress.has(file.errorId)) {
+            return false;
+        }
+        const fileDate = parseDatePrefix(file.date);
+        if (!fileDate) {
+            return false;
+        }
+        return fileDate < cutoffMs;
+    });
+};
+const summarizeRemoval = (files) => {
+    const totalBytes = files.reduce((sum, file) => sum + file.sizeBytes, 0);
+    return `${files.length} file${files.length === 1 ? '' : 's'} (${formatSize(totalBytes)})`;
+};
+const listFiles = (files) => {
+    for (const file of files) {
+        process.stdout.write(`- ${file.relativePath}\n`);
+    }
+};
+export const cleanCommand = async (options) => {
+    const config = loadConfig(options.config);
+    const contextDir = buildContextDir(config.project.root);
+    const dbPath = buildDatabasePath(config.project.root);
+    const db = new Database(dbPath);
+    let inProgress = new Set();
+    try {
+        initializeSchema(db);
+        checkSchemaVersion(db);
+        inProgress = findInProgressErrorIds(db);
+    }
+    finally {
+        db.close();
+    }
+    const allFiles = loadContextFiles(contextDir, config.project.root);
+    const maxAgeDays = config.cleanup.context_max_age_days;
+    const candidates = selectFilesToRemove(allFiles, inProgress, maxAgeDays);
+    if (candidates.length === 0) {
+        process.stdout.write(`No context files older than ${maxAgeDays} day${maxAgeDays === 1 ? '' : 's'} found.\n`);
+        return;
+    }
+    process.stdout.write(`Context files older than ${maxAgeDays} day${maxAgeDays === 1 ? '' : 's'}:\n`);
+    listFiles(candidates);
+    if (options.dryRun) {
+        process.stdout.write(`Would remove ${summarizeRemoval(candidates)}.\n`);
+        return;
+    }
+    if (!options.force) {
+        const confirmed = await promptForConfirmation(`Remove ${summarizeRemoval(candidates)}?`);
+        if (!confirmed) {
+            process.stdout.write('Cleanup aborted.\n');
+            return;
+        }
+    }
+    let removedCount = 0;
+    let removedBytes = 0;
+    for (const file of candidates) {
+        try {
+            fs.unlinkSync(file.fullPath);
+            removedCount += 1;
+            removedBytes += file.sizeBytes;
+        }
+        catch (error) {
+            const err = error;
+            throw new UserError(`Failed to remove ${file.relativePath}: ${err.message ?? String(err)}`);
+        }
+    }
+    const removedSummary = `${removedCount} file${removedCount === 1 ? '' : 's'} (${formatSize(removedBytes)})`;
+    process.stdout.write(`Removed ${removedSummary}.\n`);
+};