watchfix 0.3.0 → 0.5.0

package/HELP.md

@@ -0,0 +1,416 @@
+# watchfix - Agent Reference
+
+> Run `watchfix manual` to display this document.
+
+## Quick Context
+
+watchfix is a CLI tool that watches log files, detects errors via configurable patterns, and dispatches AI agents (Claude, Gemini, or Codex) to analyze and fix them automatically. Prerequisites: a `watchfix.yaml` config file in your project root, one of the supported AI CLIs installed and in PATH, and at least one log source configured. All state is stored locally in `.watchfix/errors.db` (SQLite).
+
+## Commands
+
+### Setup Commands
+
+#### `watchfix init`
+
+Create a `watchfix.yaml` config file in the current directory.
+
+```
+watchfix init [--agent <provider>] [--force]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--agent <provider>` | Set agent provider: `claude`, `gemini`, or `codex` (default: `claude`) |
+| `--force` | Overwrite existing `watchfix.yaml` |
+
+Output: writes `watchfix.yaml` and adds `.watchfix/` to `.gitignore`.
+
+#### `watchfix config validate`
+
+Validate the configuration file.
+
+```
+watchfix config validate [-c <path>]
+```
+
+Exit code 0 if valid, 1 if invalid (error message on stderr).
+
+### Watching Commands
+
+#### `watchfix watch`
+
+Start watching configured log sources for errors.
+
+```
+watchfix watch [--daemon] [--autonomous]
+```
+
+| Flags | Mode | Behavior |
+|-------|------|----------|
+| _(none)_ | Foreground, manual | Detects errors, queues for manual `fix` |
+| `--autonomous` | Foreground, autonomous | Detects and auto-fixes without approval |
+| `--daemon` | Background, manual | Runs detached; logs to activity log only |
+| `--daemon --autonomous` | Background, autonomous | Runs detached; auto-fixes in background |
+
+Exit code 2 if a watcher is already running.
+
+#### `watchfix stop`
+
+Stop a running background watcher.
+
+```
+watchfix stop
+```
+
+Exit code 2 if no watcher is running.
+
+#### `watchfix status`
+
+Show watcher state and pending errors.
+
+```
+watchfix status
+```
+
+Output format (plain text, one error per line):
+
+```
+Watcher: running (pid 12345, mode: autonomous)
+Uptime: 2h 15m
+
+Errors:
+  #1  [pending]    TypeError: Cannot read property 'x' of null  (app)
+  #3  [suggested]  ReferenceError: foo is not defined  (api)
+  #7  [fixing]     FATAL: connection refused  (db)
+```
+
+When no errors exist: `No errors recorded.`
+When watcher is not running: `Watcher: not running`
+
+### Error Management Commands
+
+#### `watchfix show <id>`
+
+Show full error details and analysis.
+
+```
+watchfix show <id> [--json]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Output machine-readable JSON (see JSON Output Format below) |
+
+Without `--json`, outputs human-readable text with error metadata, stack trace, analysis, fix result, and activity log.
+
+#### `watchfix fix [id]`
+
+Analyze and fix an error. Without an id, requires `--all`.
+
+```
+watchfix fix <id> [-y] [--analyze-only] [--reanalyze]
+watchfix fix --all [--confirm-each] [--analyze-only] [--reanalyze]
+```
+
+| Flag | Description |
+|------|-------------|
+| `-y, --yes` | Skip confirmation prompt |
+| `--all` | Fix all pending/suggested errors sequentially |
+| `--confirm-each` | With `--all`: prompt before each fix |
+| `--analyze-only` | Stop after analysis, don't apply the fix |
+| `--reanalyze` | Force re-analysis even if already in `suggested` status |
+
+Exit code 3 if the error is not in an actionable status or not found.
+
+#### `watchfix ignore <id>`
+
+Mark an error as ignored. It will not be processed further.
+
+```
+watchfix ignore <id>
+```
+
+### Utility Commands
+
+#### `watchfix logs`
+
+Show the activity log.
+
+```
+watchfix logs [--tail] [-n <count>]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--tail` | Follow the log (stream new entries) |
+| `-n, --lines <count>` | Number of lines to show (default: 50) |
+
+#### `watchfix clean`
+
+Remove old context files from `.watchfix/context/`.
+
+```
+watchfix clean [--dry-run] [--force]
+```
+
+| Flag | Description |
+|------|-------------|
+| `--dry-run` | Show what would be removed without deleting |
+| `--force` | Skip confirmation prompt |
+
+#### `watchfix version`
+
+Show version, Node.js version, config status, and agent provider.
+
+```
+watchfix version
+```
+
+#### `watchfix manual`
+
+Output this reference document to stdout.
+
+```
+watchfix manual
+```
+
+### Global Options
+
+These flags work with all commands:
+
+| Flag | Description |
+|------|-------------|
+| `-c, --config <path>` | Use alternate config file (default: `./watchfix.yaml`) |
+| `--verbose` | Increase output verbosity |
+| `-q, --quiet` | Suppress non-essential output |
+| `-h, --help` | Show help for command |
+| `-v, --version` | Show version and exit |
+
+## Common Workflows
+
+### Check if watchfix is set up
+
+```bash
+# Look for config file
+ls watchfix.yaml
+
+# Validate it
+watchfix config validate
+```
+
+### Start watching and monitor
+
+```bash
+# Start watcher in foreground
+watchfix watch
+
+# Or in background (Linux/macOS)
+watchfix watch --daemon
+
+# Poll for errors
+watchfix status
+
+# Stream activity log
+watchfix logs --tail
+```
+
+### Investigate and fix one error
+
+```bash
+# See what errors exist
+watchfix status
+
+# Get full details (machine-readable)
+watchfix show 3 --json
+
+# Fix it (with confirmation)
+watchfix fix 3
+
+# Or skip confirmation
+watchfix fix 3 -y
+```
+
+### Fix all pending errors
+
+```bash
+watchfix fix --all
+```
+
+### Fully automated operation
+
+```bash
+# Start autonomous daemon
+watchfix watch --daemon --autonomous
+
+# Monitor progress
+watchfix status
+watchfix logs --tail
+
+# Stop when done
+watchfix stop
+```
+
+### Analyze without fixing
+
+```bash
+# Get analysis only (no code changes)
+watchfix fix 3 --analyze-only
+
+# View the analysis
+watchfix show 3
+```
+
+## Exit Codes
+
+| Code | Constant | Meaning |
+|------|----------|---------|
+| 0 | `SUCCESS` | Command completed successfully |
+| 1 | `GENERAL_ERROR` | General error (invalid config, agent failure, etc.) |
+| 2 | `WATCHER_CONFLICT` | Watcher state conflict (already running / not running) |
+| 3 | `NOT_ACTIONABLE` | Target not actionable (error not found, wrong status, locked) |
+| 4 | `SCHEMA_MISMATCH` | Database schema version mismatch (requires migration) |
+| 130 | `INTERRUPTED` | Interrupted by user (SIGINT / Ctrl+C) |
+
+## Error Statuses
+
+### Status Lifecycle
+
+```
+pending → analyzing → suggested → fixing → fixed
+                                         → failed (after max attempts)
+Any status → ignored (via watchfix ignore)
+```
+
+### Status Reference
+
+| Status | Description | Actionable? |
+|--------|-------------|-------------|
+| `pending` | Detected, awaiting analysis | Yes — `fix` will start analysis |
+| `analyzing` | Agent is currently analyzing | No — locked |
+| `suggested` | Analysis complete, awaiting fix | Yes — `fix` will apply the suggestion |
+| `fixing` | Agent is currently applying fix | No — locked |
+| `fixed` | Fix applied and verified | No — terminal |
+| `failed` | Max attempts exceeded | Manual retry only (`fix <id>`, excluded from `--all`) |
+| `ignored` | User chose to ignore | No — terminal |
+| `resolved` | Fixed by a previous fix to another error | No — terminal |
+| `deferred` | Non-code issue (infrastructure/config) | No — shows remediation guidance |
+
+### Deduplication
+
+When a new error matches an existing one (by hash):
+- If existing is `pending`, `analyzing`, `suggested`, or `fixing`: new error is dropped
+- If existing is `fixed`, `failed`, or `ignored`: a new entry is created (error recurred)
+
+## JSON Output Format
+
+`watchfix show <id> --json` returns a JSON object with this shape:
+
+```json
+{
+  "error": {
+    "id": 1,
+    "hash": "abc123...",
+    "source": "app",
+    "timestamp": "2026-01-29T12:00:00.000Z",
+    "errorType": "TypeError",
+    "message": "Cannot read property 'x' of null",
+    "stackTrace": "TypeError: Cannot read property...\n    at foo (src/app.ts:10:5)\n    ...",
+    "rawLog": "[2026-01-29 12:00:00] ERROR TypeError: Cannot read property...",
+    "status": "suggested",
+    "suggestion": "{\"summary\":\"...\",\"root_cause\":\"...\",\"suggested_fix\":\"...\"}",
+    "fixResult": null,
+    "fixAttempts": 0,
+    "lockedBy": null,
+    "lockedAt": null,
+    "createdAt": "2026-01-29T12:00:01.000Z",
+    "updatedAt": "2026-01-29T12:00:05.000Z"
+  },
+  "analysis": {
+    "summary": "Null pointer access in foo()",
+    "root_cause": "Variable 'x' is not initialized before access",
+    "suggested_fix": "Add null check before accessing property",
+    "files_to_modify": ["src/app.ts"],
+    "confidence": "high",
+    "category": "code"
+  },
+  "fixResult": null,
+  "activityLog": [
+    {
+      "id": 1,
+      "timestamp": "2026-01-29T12:00:01.000Z",
+      "action": "error_detected",
+      "error_id": 1,
+      "details": "TypeError: Cannot read property 'x' of null"
+    }
+  ]
+}
+```
+
+### Key Fields
+
+- `error.status` — current lifecycle status (see Error Statuses above)
+- `error.suggestion` — raw JSON string of agent analysis (parse it to get the `analysis` object)
+- `error.fixResult` — raw JSON string of fix result (null if not yet fixed)
+- `analysis` — parsed suggestion object; `null` if not yet analyzed
+  - `analysis.category` — `"code"`, `"infrastructure"`, or `"configuration"`
+  - `analysis.confidence` — `"high"`, `"medium"`, or `"low"`
+  - `analysis.remediation_guidance` — present for `deferred` (non-code) errors
+- `fixResult` — parsed fix result object; `null` if not yet fixed
+  - `fixResult.success` — boolean indicating if verification passed
+  - `fixResult.files_changed` — array of `{ "path": "...", "change": "..." }`
+- `activityLog` — chronological list of actions taken on this error
+
+## Configuration Quick Reference
+
+watchfix uses a `watchfix.yaml` file in the project root. Run `watchfix init` to generate a template.
+
+### Key Sections
+
+```yaml
+project:
+  name: my-app          # Project identifier
+  root: .               # Project root (paths resolve relative to this)
+
+agent:
+  provider: claude       # Required: claude | gemini | codex
+  timeout: 5m            # Max agent execution time (default: 5m)
+  retries: 2             # Retries on agent timeout/crash (default: 2)
+
+logs:
+  sources:               # At least one source required
+    - name: app          # Source identifier
+      type: file         # file | docker | command
+      path: ./logs/app.log
+  context_lines_before: 10
+  context_lines_after: 5
+
+verification:
+  test_commands:         # Run after fix, in order; stop on first failure
+    - npm run lint
+    - npm test
+  health_checks:         # HTTP GET, expect 2xx
+    - http://localhost:3000/health
+
+patterns:
+  match:                 # Additional error patterns
+    - "FATAL:"
+    - "regex:OOM.*killed"
+  ignore:                # Patterns to skip
+    - "DeprecationWarning"
+
+limits:
+  max_attempts_per_error: 3
+
+cleanup:
+  context_max_age_days: 7
+```
+
+### Source Types
+
+| Type | Required Fields | Description |
+|------|----------------|-------------|
+| `file` | `path` | Watch a log file (supports `format: ndjson` for structured JSON logs) |
+| `docker` | `container` | Watch Docker container logs |
+| `command` | `run`, `interval` | Run a command periodically and scan output |
+
+For full configuration details and NDJSON options, run `watchfix init` to see the annotated template.

package/dist/cli/commands/init.js

@@ -27,6 +27,19 @@ logs:
       type: file
       path: ./logs/app.log
 
+  # Example NDJSON source (for structured JSON logs like Pino, Bunyan, Winston):
+  # - name: app-json
+  #   type: file
+  #   path: ./logs/app.ndjson
+  #   format: ndjson
+  #   ndjson:
+  #     messageField: msg           # Required: field containing log message
+  #     timestampField: time        # Optional: field with timestamp
+  #     levelField: level           # Optional: field with log level
+  #     levelFilter:                # Optional: only process these levels
+  #       - error
+  #       - fatal
+
   # Example docker source:
   # - name: api
   #   type: docker

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

@@ -0,0 +1 @@
+export declare const manualCommand: () => Promise<void>;

package/dist/cli/commands/manual.js

@@ -0,0 +1,14 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { UserError } from '../../utils/errors.js';
+export const manualCommand = async () => {
+    const helpPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'HELP.md');
+    try {
+        const content = await fs.readFile(helpPath, 'utf8');
+        process.stdout.write(content);
+    }
+    catch {
+        throw new UserError('HELP.md not found. This file should be included in the watchfix package.');
+    }
+};

package/dist/cli/index.js

@@ -12,6 +12,7 @@ import { logsCommand } from './commands/logs.js';
 import { configValidateCommand } from './commands/config.js';
 import { cleanCommand } from './commands/clean.js';
 import { versionCommand } from './commands/version.js';
+import { manualCommand } from './commands/manual.js';
 import { EXIT_CODES, InternalError, UserError } from '../utils/errors.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../../package.json');
@@ -105,6 +106,12 @@ const registerCommands = (program) => {
         .action(async (options) => {
         await versionCommand(options);
     }));
+    program
+        .command('manual')
+        .description('Show detailed reference documentation')
+        .action(async () => {
+        await manualCommand();
+    });
 };
 const program = new Command();
 program
@@ -114,6 +121,7 @@ addGlobalOptions(program);
 program
     .helpOption('-h, --help', 'Show help for command')
     .version(pkg.version ?? '0.0.0', '-v, --version', 'Show version and exit');
+program.addHelpText('after', '\nRun "watchfix manual" for detailed reference documentation.');
 registerCommands(program);
 const handleError = (error) => {
     if (error instanceof UserError) {

package/dist/config/schema.d.ts

@@ -1,29 +1,76 @@
 import { z } from 'zod';
 declare const durationSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+declare const ndjsonConfigSchema: z.ZodObject<{
+    messageField: z.ZodString;
+    timestampField: z.ZodOptional<z.ZodString>;
+    levelField: z.ZodOptional<z.ZodString>;
+    levelFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    messageField: string;
+    timestampField?: string | undefined;
+    levelField?: string | undefined;
+    levelFilter?: string[] | undefined;
+}, {
+    messageField: string;
+    timestampField?: string | undefined;
+    levelField?: string | undefined;
+    levelFilter?: string[] | undefined;
+}>;
 declare const fileSourceSchema: z.ZodObject<{
     name: z.ZodString;
     type: z.ZodLiteral<"file">;
     path: z.ZodString;
+    format: z.ZodOptional<z.ZodEnum<["text", "ndjson"]>>;
+    ndjson: z.ZodOptional<z.ZodObject<{
+        messageField: z.ZodString;
+        timestampField: z.ZodOptional<z.ZodString>;
+        levelField: z.ZodOptional<z.ZodString>;
+        levelFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    }, {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     path: string;
-    name: string;
     type: "file";
+    name: string;
+    ndjson?: {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    } | undefined;
+    format?: "text" | "ndjson" | undefined;
 }, {
     path: string;
-    name: string;
     type: "file";
+    name: string;
+    ndjson?: {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    } | undefined;
+    format?: "text" | "ndjson" | undefined;
 }>;
 declare const dockerSourceSchema: z.ZodObject<{
     name: z.ZodString;
     type: z.ZodLiteral<"docker">;
     container: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     type: "docker";
+    name: string;
     container: string;
 }, {
-    name: string;
     type: "docker";
+    name: string;
     container: string;
 }>;
 declare const commandSourceSchema: z.ZodObject<{
@@ -32,13 +79,13 @@ declare const commandSourceSchema: z.ZodObject<{
     run: z.ZodString;
     interval: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     type: "command";
+    name: string;
     run: string;
     interval: string;
 }, {
-    name: string;
     type: "command";
+    name: string;
     run: string;
     interval: string;
 }>;
@@ -46,25 +93,56 @@ declare const logSourceSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     name: z.ZodString;
     type: z.ZodLiteral<"file">;
     path: z.ZodString;
+    format: z.ZodOptional<z.ZodEnum<["text", "ndjson"]>>;
+    ndjson: z.ZodOptional<z.ZodObject<{
+        messageField: z.ZodString;
+        timestampField: z.ZodOptional<z.ZodString>;
+        levelField: z.ZodOptional<z.ZodString>;
+        levelFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    }, {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     path: string;
-    name: string;
     type: "file";
+    name: string;
+    ndjson?: {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    } | undefined;
+    format?: "text" | "ndjson" | undefined;
 }, {
     path: string;
-    name: string;
     type: "file";
+    name: string;
+    ndjson?: {
+        messageField: string;
+        timestampField?: string | undefined;
+        levelField?: string | undefined;
+        levelFilter?: string[] | undefined;
+    } | undefined;
+    format?: "text" | "ndjson" | undefined;
 }>, z.ZodObject<{
     name: z.ZodString;
     type: z.ZodLiteral<"docker">;
     container: z.ZodString;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     type: "docker";
+    name: string;
     container: string;
 }, {
-    name: string;
     type: "docker";
+    name: string;
     container: string;
 }>, z.ZodObject<{
     name: z.ZodString;
@@ -72,13 +150,13 @@ declare const logSourceSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
     run: z.ZodString;
     interval: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
 }, "strip", z.ZodTypeAny, {
-    name: string;
     type: "command";
+    name: string;
     run: string;
     interval: string;
 }, {
-    name: string;
     type: "command";
+    name: string;
     run: string;
     interval: string;
 }>]>;
@@ -117,29 +195,60 @@ declare const configSchema: z.ZodObject<{
         stderr_is_progress?: boolean | undefined;
     }>;
     logs: z.ZodObject<{
-        sources: z.ZodEffects<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        sources: z.ZodEffects<z.ZodEffects<z.ZodArray<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
             name: z.ZodString;
             type: z.ZodLiteral<"file">;
             path: z.ZodString;
+            format: z.ZodOptional<z.ZodEnum<["text", "ndjson"]>>;
+            ndjson: z.ZodOptional<z.ZodObject<{
+                messageField: z.ZodString;
+                timestampField: z.ZodOptional<z.ZodString>;
+                levelField: z.ZodOptional<z.ZodString>;
+                levelFilter: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+            }, "strip", z.ZodTypeAny, {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            }, {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            }>>;
         }, "strip", z.ZodTypeAny, {
             path: string;
-            name: string;
             type: "file";
+            name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
         }, {
             path: string;
-            name: string;
             type: "file";
+            name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
         }>, z.ZodObject<{
             name: z.ZodString;
             type: z.ZodLiteral<"docker">;
             container: z.ZodString;
         }, "strip", z.ZodTypeAny, {
-            name: string;
             type: "docker";
+            name: string;
             container: string;
         }, {
-            name: string;
             type: "docker";
+            name: string;
             container: string;
         }>, z.ZodObject<{
             name: z.ZodString;
@@ -147,39 +256,93 @@ declare const configSchema: z.ZodObject<{
             run: z.ZodString;
             interval: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
         }, "strip", z.ZodTypeAny, {
-            name: string;
             type: "command";
+            name: string;
             run: string;
             interval: string;
         }, {
-            name: string;
             type: "command";
+            name: string;
             run: string;
             interval: string;
         }>]>, "many">, ({
             path: string;
-            name: string;
             type: "file";
-        } | {
             name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
             type: "docker";
+            name: string;
             container: string;
         } | {
-            name: string;
             type: "command";
+            name: string;
             run: string;
             interval: string;
         })[], ({
             path: string;
-            name: string;
             type: "file";
+            name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
+            type: "docker";
+            name: string;
+            container: string;
         } | {
+            type: "command";
+            name: string;
+            run: string;
+            interval: string;
+        })[]>, ({
+            path: string;
+            type: "file";
             name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
             type: "docker";
+            name: string;
             container: string;
         } | {
+            type: "command";
             name: string;
+            run: string;
+            interval: string;
+        })[], ({
+            path: string;
+            type: "file";
+            name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
+            type: "docker";
+            name: string;
+            container: string;
+        } | {
             type: "command";
+            name: string;
             run: string;
             interval: string;
         })[]>;
@@ -189,15 +352,22 @@ declare const configSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         sources: ({
             path: string;
-            name: string;
             type: "file";
-        } | {
             name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
             type: "docker";
+            name: string;
             container: string;
         } | {
-            name: string;
             type: "command";
+            name: string;
             run: string;
             interval: string;
         })[];
@@ -207,15 +377,22 @@ declare const configSchema: z.ZodObject<{
     }, {
         sources: ({
             path: string;
-            name: string;
             type: "file";
-        } | {
             name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
             type: "docker";
+            name: string;
             container: string;
         } | {
-            name: string;
             type: "command";
+            name: string;
             run: string;
             interval: string;
         })[];
@@ -295,15 +472,22 @@ declare const configSchema: z.ZodObject<{
     logs: {
         sources: ({
             path: string;
-            name: string;
             type: "file";
-        } | {
             name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
             type: "docker";
+            name: string;
             container: string;
         } | {
-            name: string;
             type: "command";
+            name: string;
             run: string;
             interval: string;
         })[];
@@ -349,15 +533,22 @@ declare const configSchema: z.ZodObject<{
     logs: {
         sources: ({
             path: string;
-            name: string;
             type: "file";
-        } | {
             name: string;
+            ndjson?: {
+                messageField: string;
+                timestampField?: string | undefined;
+                levelField?: string | undefined;
+                levelFilter?: string[] | undefined;
+            } | undefined;
+            format?: "text" | "ndjson" | undefined;
+        } | {
             type: "docker";
+            name: string;
             container: string;
         } | {
-            name: string;
             type: "command";
+            name: string;
             run: string;
             interval: string;
         })[];
@@ -389,5 +580,5 @@ declare const configSchema: z.ZodObject<{
     } | undefined;
 }>;
 type Config = z.infer<typeof configSchema>;
-export { commandSourceSchema, configSchema, dockerSourceSchema, durationSchema, fileSourceSchema, logSourceSchema, patternSchema, };
+export { commandSourceSchema, configSchema, dockerSourceSchema, durationSchema, fileSourceSchema, logSourceSchema, ndjsonConfigSchema, patternSchema, };
 export type { Config };

package/dist/config/schema.js

@@ -17,10 +17,18 @@ const durationSchema = z
     };
     return amount * msByUnit[unit] <= MAX_DURATION_MS;
 }, 'Duration cannot exceed 24 hours');
+const ndjsonConfigSchema = z.object({
+    messageField: z.string().min(1),
+    timestampField: z.string().min(1).optional(),
+    levelField: z.string().min(1).optional(),
+    levelFilter: z.array(z.string().min(1)).optional(),
+});
 const fileSourceSchema = z.object({
     name: z.string().min(1),
     type: z.literal('file'),
     path: z.string().min(1),
+    format: z.enum(['text', 'ndjson']).optional(),
+    ndjson: ndjsonConfigSchema.optional(),
 });
 const dockerSourceSchema = z.object({
     name: z.string().min(1),
@@ -59,7 +67,15 @@ const configSchema = z.object({
             .refine((sources) => {
             const names = sources.map((source) => source.name);
             return names.length === new Set(names).size;
-        }, { message: 'Log source names must be unique' }),
+        }, { message: 'Log source names must be unique' })
+            .refine((sources) => {
+            return sources.every((source) => {
+                if (source.type === 'file' && source.format === 'ndjson') {
+                    return source.ndjson !== undefined;
+                }
+                return true;
+            });
+        }, { message: 'ndjson config is required when format is "ndjson"' }),
         context_lines_before: z.number().int().min(0).default(10),
         context_lines_after: z.number().int().min(0).default(5),
         max_line_buffer: z.number().int().min(100).default(10000),
@@ -102,4 +118,4 @@ const configSchema = z.object({
     })
         .default({}),
 });
-export { commandSourceSchema, configSchema, dockerSourceSchema, durationSchema, fileSourceSchema, logSourceSchema, patternSchema, };
+export { commandSourceSchema, configSchema, dockerSourceSchema, durationSchema, fileSourceSchema, logSourceSchema, ndjsonConfigSchema, patternSchema, };

package/dist/watcher/sources/file.d.ts

@@ -9,6 +9,8 @@ export declare class FileSource implements LogSource {
     private readonly filePath;
     private readonly logger;
     private readonly emitter;
+    private readonly format;
+    private readonly ndjsonConfig;
     private watcher;
     private position;
     private partialLine;
@@ -26,5 +28,6 @@ export declare class FileSource implements LogSource {
     private readLoop;
     private readNewLines;
     private processChunk;
+    private handleLine;
 }
 export {};

package/dist/watcher/sources/file.js

@@ -3,11 +3,14 @@ import path from 'node:path';
 import { EventEmitter } from 'node:events';
 import chokidar from 'chokidar';
 import { Logger } from '../../utils/logger.js';
+import { parseNdjsonLine } from './ndjson.js';
 export class FileSource {
     config;
     filePath;
     logger;
     emitter;
+    format;
+    ndjsonConfig;
     watcher = null;
     position = 0;
     partialLine = '';
@@ -23,6 +26,8 @@ export class FileSource {
         this.logger =
             options?.logger ?? new Logger({ terminalEnabled: false, verbosity: 'normal' });
         this.emitter = new EventEmitter();
+        this.format = config.format ?? 'text';
+        this.ndjsonConfig = config.ndjson ?? null;
     }
     async start() {
         if (this.watcher) {
@@ -164,12 +169,40 @@ export class FileSource {
         const lines = combined.split('\n');
         this.partialLine = lines.pop() ?? '';
         for (const rawLine of lines) {
-            const line = rawLine.replace(/\r$/, '');
+            this.handleLine(rawLine.replace(/\r$/, ''));
+        }
+    }
+    handleLine(line) {
+        if (this.format !== 'ndjson' || !this.ndjsonConfig) {
             this.emitter.emit('line', {
                 source: this.config.name,
                 line,
                 timestamp: new Date(),
             });
+            return;
+        }
+        const result = parseNdjsonLine(line, this.ndjsonConfig);
+        if (result.success) {
+            this.emitter.emit('line', {
+                source: this.config.name,
+                line: result.data.message,
+                timestamp: result.data.timestamp,
+            });
+            return;
+        }
+        // Handle different failure reasons
+        if (result.reason === 'filtered') {
+            // Line was filtered by level - silently skip
+            return;
+        }
+        if (result.reason === 'missing_message') {
+            this.logger.debug(`NDJSON line missing message field "${this.ndjsonConfig.messageField}": ${line.slice(0, 100)}`);
         }
+        // For parse errors or missing message, fall back to emitting raw line
+        this.emitter.emit('line', {
+            source: this.config.name,
+            line,
+            timestamp: new Date(),
+        });
     }
 }

package/dist/watcher/sources/ndjson.d.ts

@@ -0,0 +1,16 @@
+import type { NdjsonConfig } from './types.js';
+export type ParsedNdjsonLine = {
+    message: string;
+    timestamp: Date;
+};
+export type NdjsonParseResult = {
+    success: true;
+    data: ParsedNdjsonLine;
+} | {
+    success: false;
+    reason: 'parse_error' | 'missing_message' | 'filtered';
+};
+export declare function getNestedValue(obj: unknown, path: string): unknown;
+export declare function parseTimestamp(value: unknown): Date | null;
+export declare function shouldProcessLevel(value: unknown, levelFilter: string[] | undefined): boolean;
+export declare function parseNdjsonLine(line: string, config: NdjsonConfig): NdjsonParseResult;

package/dist/watcher/sources/ndjson.js

@@ -0,0 +1,108 @@
+export function getNestedValue(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== 'object') {
+            return undefined;
+        }
+        current = current[part];
+    }
+    return current;
+}
+export function parseTimestamp(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    if (typeof value === 'string') {
+        const date = new Date(value);
+        if (!Number.isNaN(date.getTime())) {
+            return date;
+        }
+        return null;
+    }
+    if (typeof value === 'number') {
+        // Handle Unix timestamps in seconds or milliseconds
+        // If the number is less than 10^12, treat as seconds; otherwise as milliseconds
+        const MS_THRESHOLD = 1e12;
+        const timestamp = value < MS_THRESHOLD ? value * 1000 : value;
+        const date = new Date(timestamp);
+        if (!Number.isNaN(date.getTime())) {
+            return date;
+        }
+        return null;
+    }
+    return null;
+}
+export function shouldProcessLevel(value, levelFilter) {
+    if (!levelFilter || levelFilter.length === 0) {
+        return true;
+    }
+    if (value === null || value === undefined) {
+        // If no level is present but filter is configured, skip the line
+        return false;
+    }
+    // Handle string levels (most common)
+    if (typeof value === 'string') {
+        const lowerValue = value.toLowerCase();
+        return levelFilter.some((filter) => filter.toLowerCase() === lowerValue);
+    }
+    // Handle numeric levels (Bunyan style: 10=trace, 20=debug, 30=info, 40=warn, 50=error, 60=fatal)
+    if (typeof value === 'number') {
+        const bunyanLevels = {
+            10: 'trace',
+            20: 'debug',
+            30: 'info',
+            40: 'warn',
+            50: 'error',
+            60: 'fatal',
+        };
+        const levelName = bunyanLevels[value];
+        if (levelName) {
+            return levelFilter.some((filter) => filter.toLowerCase() === levelName.toLowerCase());
+        }
+        // Unknown numeric level - don't match
+        return false;
+    }
+    return false;
+}
+export function parseNdjsonLine(line, config) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return { success: false, reason: 'parse_error' };
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        return { success: false, reason: 'parse_error' };
+    }
+    // Check level filter first (before extracting message)
+    if (config.levelField) {
+        const levelValue = getNestedValue(parsed, config.levelField);
+        if (!shouldProcessLevel(levelValue, config.levelFilter)) {
+            return { success: false, reason: 'filtered' };
+        }
+    }
+    // Extract message
+    const messageValue = getNestedValue(parsed, config.messageField);
+    if (messageValue === null || messageValue === undefined) {
+        return { success: false, reason: 'missing_message' };
+    }
+    const message = String(messageValue);
+    // Extract timestamp
+    let timestamp = new Date();
+    if (config.timestampField) {
+        const timestampValue = getNestedValue(parsed, config.timestampField);
+        const parsedTimestamp = parseTimestamp(timestampValue);
+        if (parsedTimestamp) {
+            timestamp = parsedTimestamp;
+        }
+    }
+    return {
+        success: true,
+        data: { message, timestamp },
+    };
+}

package/dist/watcher/sources/types.d.ts

@@ -3,10 +3,18 @@ export type LogEvent = {
     line: string;
     timestamp: Date;
 };
+export type NdjsonConfig = {
+    messageField: string;
+    timestampField?: string;
+    levelField?: string;
+    levelFilter?: string[];
+};
 export type FileSourceConfig = {
     name: string;
     type: 'file';
     path: string;
+    format?: 'text' | 'ndjson';
+    ndjson?: NdjsonConfig;
 };
 export type DockerSourceConfig = {
     name: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchfix",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "CLI tool that watches logs, detects errors, and dispatches AI agents to fix them",
   "keywords": [
     "cli",
@@ -30,6 +30,7 @@
     "dist",
     "LICENSE",
     "README.md",
+    "HELP.md",
     "package.json"
   ],
   "dependencies": {