devharness 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CDP Tools MCP 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,185 @@
+# devharness
+
+[![npm version](https://img.shields.io/npm/v/devharness.svg)](https://www.npmjs.com/package/devharness)
+[![license](https://img.shields.io/npm/l/devharness.svg)](https://github.com/InDate/devharness/blob/main/LICENSE)
+
+MCP server. Your agent runs the app, sees what happened, and redoes none of it by
+hand.
+
+```bash
+npx devharness@latest
+```
+
+> Was `cdp-tools-mcp`. That name described the transport. CDP is now one of three
+> things this does. [Migrating](#migrating).
+
+## Why
+
+Three things burn a debugging session, and only the first is about seeing.
+
+**You are the eyes.** You start the app, click the thing, paste the stack trace
+back into chat, reload and report whether it worked.
+
+**Everything gets re-driven by hand.** Relaunch the browser, log in again, refill
+the form, click back to the screen where the bug lives — every iteration. Slow,
+and the retyped arguments drift from what actually ran.
+
+**One failure stalls the whole session.** A dead dev server, a missing parameter,
+a wedged tool: the agent stops and waits for you.
+
+devharness closes all three. Real execution instead of guesses. Every call it has
+already made is replayable by index. Failures have recovery paths the agent takes
+itself.
+
+## What it does
+
+24 tool modules. 802 tests across 57 files, ~7s.
+
+**See** — pause real execution and read the real frame: breakpoints (line,
+conditional, logpoint, DOM mutation, event, XHR), call stack and scope, source
+maps so TypeScript breakpoints hit TypeScript lines. Chrome and Node.js
+(`node --inspect`), both at once. Console, network, storage, DOM. `content verify`
+reports dead buttons, dead links, small touch targets, and overflow clipping from
+CDP facts, not heuristics.
+
+**Repeat** — every tool response carries its own history index:
+
+```
+**Repeat:** replay({ action: 'repeat', indices: [58] })
+```
+
+`indices` takes a list, so four steps re-run in one call. Whatever the agent
+already did, it redoes by reference rather than by retyping. Worth keeping?
+`replay({ action: 'create', ... })` promotes it to a named sequence, exportable as
+a Playwright or Puppeteer test.
+
+**Recover** — a call that fails validation comes back with a `continuationToken`
+and the list of what was missing; the retry sends only the missing field. A
+validated call blocked by a guard is already recorded, so acknowledging the block
+and replaying resumes the exact call. If the server itself wedges,
+`config({ action: 'restart' })` respawns it and replays the MCP handshake, so the
+host session never reconnects.
+
+**Prove** — dev servers run under management (npm, flask, docker, compose) with
+port monitoring. Issues bind a bug to its reproduction: `workOn` navigates back to
+the failing state, `resolve` replays the sequence against the fix.
+
+## Design decisions
+
+- **A dead server blocks tools rather than warning.** An agent clicking away at a
+  dead server produces a long, confident, entirely fictional debugging session.
+  Configurable: `inform`, `error`, `block`.
+- **Closing an issue needs a human click.** `resolve` waits on a browser overlay
+  no agent can dismiss. Recording findings is automated; declaring something
+  actually fixed stays a human judgement.
+- **Repeat is on every response, not just failures.** Recovery and ordinary
+  re-running are the same mechanism, so there's nothing extra to reach for when
+  the session gets long.
+- **`getVariables` degrades, never errors.** full → reduced depth → names →
+  counts. A truncated answer that says it truncated beats a tool error.
+- **Connections are named.** Every tool takes `connectionReason`, so nested agents
+  each drive their own tab in one Chrome without fighting over "the current page".
+- **Text beats screenshots.** `extractText` costs a fraction of an image and
+  answers most page questions. Screenshot when the question is genuinely visual.
+
+## Setup
+
+**Claude Code:**
+```bash
+claude mcp add devharness -- npx devharness@latest
+```
+
+**Claude Desktop:**
+```json
+{
+  "mcpServers": {
+    "devharness": {
+      "command": "npx",
+      "args": ["-y", "devharness@latest"]
+    }
+  }
+}
+```
+
+**Other clients** — `npx devharness@latest` over stdio.
+
+### Skill
+
+Bundled [Agent Skill](https://agentskills.io) at `skills/devharness/`. Same
+guidance as `docs/instructions.md`, split for progressive disclosure: name and
+description at session start, full catalogue only when debugging starts.
+
+```bash
+mkdir -p .claude/skills
+ln -s ../../node_modules/devharness/skills/devharness .claude/skills/devharness
+```
+
+Installing as a Claude Code plugin does this for you.
+
+## Example
+
+Node service:
+
+```
+1. node --inspect=9229 app.js
+2. connectDebugger({ reference: "api", port: 9229 })
+3. breakpoint({ action: 'set', connectionReason: "api", file: "user.ts", line: 42 })
+4. Trigger the request.
+5. inspect({ action: 'getVariables', connectionReason: "api" })
+   → real frame: what userId and userRole actually were
+```
+
+Browser fix:
+
+```
+1. launchChrome({ reference: "app" })   # launches and connects
+2. Record the five clicks that reproduce it.
+3. Fix the code.
+4. Replay → pass or fail, against the real app
+```
+
+[docs/GUIDE.md](./docs/GUIDE.md) for depth, [docs/instructions.md](./docs/instructions.md)
+for the tool reference. [examples/test-app](./examples/test-app/README.md) ships
+eight seeded bugs to exercise it against known-wrong code.
+
+## vs Chrome DevTools MCP
+
+[Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) is
+better at performance tracing, device emulation, advanced browser automation.
+
+devharness adds breakpoint debugging with variable inspection, Node.js targets,
+simultaneous connections, logpoints, server lifecycle, and — the part that
+compounds over a long session — replayable call history and self-service recovery.
+
+Browser-only and performance-shaped → theirs. Backend code, stepping execution,
+long sessions where the agent keeps re-driving the same setup → this.
+
+## Migrating
+
+`cdp-tools-mcp` is deprecated on npm and points here. Tools unchanged. Package,
+repo, and skill renamed.
+
+```diff
+-"args": ["-y", "cdp-tools-mcp@latest"]
++"args": ["-y", "devharness@latest"]
+```
+
+Your MCP server name (`cdp-tools`, or whatever you called it) is yours and keeps
+working. Renaming it is cosmetic — but tools are addressed as
+`mcp__<server-name>__<tool>`, so update project docs if you do.
+
+## From source
+
+```bash
+git clone https://github.com/InDate/devharness.git
+cd devharness
+npm install && npm run build && npm test
+```
+
+## Contributing
+
+Issues and PRs welcome. Reporting a bug? Attach a recorded reproduction sequence.
+
+## License
+
+MIT

package/build/atomic-write.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Clean up stale temp files left behind by crashed/killed processes.
+ * Removes temp files older than maxAgeMs (default: 5 minutes).
+ */
+export declare function cleanupStaleTempFiles(directory: string, maxAgeMs?: number): Promise<{
+    cleaned: string[];
+    errors: string[];
+}>;
+/**
+ * Synchronous version for use during shutdown.
+ * Uses maxAgeMs=0 by default to clean all temp files.
+ */
+export declare function cleanupStaleTempFilesSync(directory: string, maxAgeMs?: number): {
+    cleaned: string[];
+    errors: string[];
+};
+/**
+ * Atomically write content to a file using temp + rename pattern.
+ * Safe against process crashes and concurrent writes to the same file.
+ *
+ * How it works:
+ * 1. Creates parent directories if they don't exist
+ * 2. Writes content to a hidden temp file in the same directory
+ * 3. Renames temp file to target (atomic on POSIX systems)
+ * 4. Cleans up temp file if any step fails
+ */
+export declare function atomicWriteFile(filePath: string, content: string | Buffer, encoding?: BufferEncoding): Promise<void>;
+//# sourceMappingURL=atomic-write.d.ts.map

package/build/atomic-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic-write.d.ts","sourceRoot":"","sources":["../src/atomic-write.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAsB,GAC/B,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAwBlD;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAU,GACnB;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAwBzC;AA0BD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,QAAQ,GAAE,cAAwB,GACjC,OAAO,CAAC,IAAI,CAAC,CAmBf"}

package/build/atomic-write.js

@@ -0,0 +1,126 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/** Pattern: .{basename}.tmp.{timestamp}.{random} */
+const TEMP_FILE_PATTERN = /^\.(.+)\.tmp\.(\d+)\.[a-z0-9]+$/;
+/**
+ * Parse a temp file entry and return its age if it matches the pattern.
+ * Returns null if the entry doesn't match the temp file pattern.
+ */
+function getTempFileAge(entry, now) {
+    const match = entry.match(TEMP_FILE_PATTERN);
+    if (!match)
+        return null;
+    const timestamp = parseInt(match[2], 10);
+    return { basename: match[1], age: now - timestamp };
+}
+/**
+ * Clean up stale temp files left behind by crashed/killed processes.
+ * Removes temp files older than maxAgeMs (default: 5 minutes).
+ */
+export async function cleanupStaleTempFiles(directory, maxAgeMs = 5 * 60 * 1000) {
+    const cleaned = [];
+    const errors = [];
+    try {
+        const entries = await fs.promises.readdir(directory);
+        const now = Date.now();
+        for (const entry of entries) {
+            const parsed = getTempFileAge(entry, now);
+            if (!parsed || parsed.age <= maxAgeMs)
+                continue;
+            try {
+                await fs.promises.unlink(path.join(directory, entry));
+                cleaned.push(entry);
+            }
+            catch (err) {
+                errors.push(`${entry}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read - not an error
+    }
+    return { cleaned, errors };
+}
+/**
+ * Synchronous version for use during shutdown.
+ * Uses maxAgeMs=0 by default to clean all temp files.
+ */
+export function cleanupStaleTempFilesSync(directory, maxAgeMs = 0) {
+    const cleaned = [];
+    const errors = [];
+    try {
+        const entries = fs.readdirSync(directory);
+        const now = Date.now();
+        for (const entry of entries) {
+            const parsed = getTempFileAge(entry, now);
+            if (!parsed || parsed.age <= maxAgeMs)
+                continue;
+            try {
+                fs.unlinkSync(path.join(directory, entry));
+                cleaned.push(entry);
+            }
+            catch (err) {
+                errors.push(`${entry}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read - not an error
+    }
+    return { cleaned, errors };
+}
+/**
+ * Clean up stale temp files for a specific target file.
+ * Called before each atomic write to prevent accumulation.
+ */
+async function cleanupStaleForFile(dir, targetBasename, maxAgeMs = 30 * 1000) {
+    try {
+        const entries = await fs.promises.readdir(dir);
+        const now = Date.now();
+        for (const entry of entries) {
+            const parsed = getTempFileAge(entry, now);
+            if (!parsed || parsed.basename !== targetBasename || parsed.age <= maxAgeMs)
+                continue;
+            try {
+                await fs.promises.unlink(path.join(dir, entry));
+            }
+            catch {
+                // Ignore - file may have been cleaned up already
+            }
+        }
+    }
+    catch {
+        // Directory doesn't exist or can't be read - not an error
+    }
+}
+/**
+ * Atomically write content to a file using temp + rename pattern.
+ * Safe against process crashes and concurrent writes to the same file.
+ *
+ * How it works:
+ * 1. Creates parent directories if they don't exist
+ * 2. Writes content to a hidden temp file in the same directory
+ * 3. Renames temp file to target (atomic on POSIX systems)
+ * 4. Cleans up temp file if any step fails
+ */
+export async function atomicWriteFile(filePath, content, encoding = 'utf-8') {
+    const dir = path.dirname(filePath);
+    const basename = path.basename(filePath);
+    const tempPath = path.join(dir, `.${basename}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`);
+    await fs.promises.mkdir(dir, { recursive: true });
+    await cleanupStaleForFile(dir, basename);
+    try {
+        await fs.promises.writeFile(tempPath, content, encoding);
+        await fs.promises.rename(tempPath, filePath);
+    }
+    catch (err) {
+        try {
+            await fs.promises.unlink(tempPath);
+        }
+        catch {
+            // Ignore cleanup errors
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=atomic-write.js.map

package/build/atomic-write.js.map

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