svn-agent-mcp 1.0.0

package/docs/decisions/ADR-001-use-spec-v1-architecture.md

@@ -0,0 +1,25 @@
+# ADR-001: Use The SPEC v1.0 Architecture
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-07
+
+## Context
+
+The project needs a new SVN MCP that reduces agent SVN housekeeping, prevents line-ending churn, and exposes guarded SVN operations. The existing plan in `docs/SPEC.md` already captures pain points, rejected alternatives, the process model, tool contracts, guard rules, and phased verification gates.
+
+## Decision
+
+Implement the project from scratch as an ESM TypeScript/Node stdio MCP server following `docs/SPEC.md` version 1.0. Keep the server small and auditable, with process execution isolated in a runner module, structured response envelopes, explicit guard logic, parser modules, and separated read-only/composite/mutating tool families.
+
+## Consequences
+
+- The implementation has one written source of truth.
+- Future changes that affect tool behavior should update the spec deliberately.
+- Release layout and registration should follow the `releases/v<version>` plus `current` junction convention from the spec.
+- This ADR records the initial v1.0 architecture decision; the current spec version may be newer
+  and remains authoritative for tool contracts and release status.

package/docs/decisions/ADR-002-use-capability-based-generic-svn-policy.md

@@ -0,0 +1,31 @@
+# ADR-002: Use Capability-Based Generic SVN Policy
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-07
+
+## Context
+
+The MCP must describe SVN safety in terms of client capabilities instead of deployment-specific
+tool names. The same SVN problems occur across many projects, and write-capable or read-only
+capabilities can be assigned to different clients in different deployments.
+
+## Decision
+
+Make the MCP specification generic and capability-based. The implementation will refer to
+write-capable clients, read-only clients, project working copies, and deployment-provided paths. It will not
+hard-code deployment-specific names, hostnames, paths, or product names into behavior or
+documentation.
+
+## Consequences
+
+- One MCP can serve multiple SVN projects with the same safety model.
+- Read-only safety is enforced by launching that MCP instance with `--readonly`, independent of
+  which client is assigned read-only behavior. The legacy/dev `SVN_AGENT_READONLY=1` override remains
+  available for tests.
+- Project-specific path, hook, auto-props, build, and allowlist examples must remain templates or
+  deployment notes.

package/docs/decisions/ADR-003-use-plug-and-play-global-registration.md

@@ -0,0 +1,39 @@
+# ADR-003: Use Plug-And-Play Global Registration
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-07
+
+## Context
+
+The MCP may be used on machines with many SVN working copies. Tying the MCP client registration to
+a fixed launch `cwd`, or requiring end-user environment variables, creates avoidable setup friction
+and causes clients to spend setup time locating tools or reconfiguring per project.
+
+The runtime already bundles SVN and EOL converter binaries, so the remaining friction was
+working-copy selection and read-only client configuration.
+
+## Decision
+
+Register the SVN MCP once globally without a project-specific launch `cwd` and without normal-use
+environment variables. Tool calls that provide absolute paths infer the nearest SVN working copy
+for those paths. Relative paths continue to resolve against explicit per-call `cwd`, or the MCP
+process cwd when no `cwd` is provided.
+
+Read-only clients use the `--readonly` launch argument. `SVN_AGENT_*` variables remain only
+as development/test escape hatches.
+
+## Consequences
+
+- One MCP registration can serve many SVN repositories on the same machine.
+- End users do not need to locate `svn`, `svnadmin`, `dos2unix`, `unix2dos`, or configure PATH.
+- Clients should prefer absolute paths for zero-friction multi-repo tool calls.
+- Client registration remains static; the MCP does not rewrite client configuration at runtime.
+- Relative-path-only workflows still need either a meaningful client process cwd or explicit
+  per-call `cwd`.
+- `svn_self_check` verifies the local release pointer and bundled runtime; `svn_diagnose` verifies
+  read-only working-copy health without adding repo-specific client configuration.

package/docs/decisions/ADR-004-borrow-diagnostics-not-external-mcp-surface.md

@@ -0,0 +1,39 @@
+# ADR-004: Borrow Diagnostics, Not External SVN MCP Semantics
+
+## Status
+
+Accepted
+
+## Date
+
+2026-07-07
+
+## Context
+
+Existing public SVN MCP projects contain useful operator ideas: health checks, command
+diagnostics, and clearer categorization for common SVN errors. Some also expose behavior that
+conflicts with this MCP's purpose: PATH-based setup, end-user environment variables for
+credentials and working directory, permissive force/update options, optional broad commit scope,
+shell/string command execution, and plain-text-oriented responses.
+
+This MCP is meant to be plug-and-play, multi-working-copy, bundled, no-shell, explicit-path,
+guarded, and safe for separate write-capable and read-only clients.
+
+## Decision
+
+Use external SVN MCPs as reference material only. Borrow read-only diagnostics, error taxonomy,
+and documentation lessons when they fit the guard model. Do not fork or import mutating semantics,
+credential configuration, launch configuration, or shell execution patterns that increase setup
+friction or weaken commit/update safety.
+
+The v0.1.10 implementation applies this by adding `svn_diagnose` and expanding SVN error
+classification while preserving bundled runtime binaries, zero normal-use environment variables,
+explicit-path commits, readonly mode, and structured envelopes.
+
+## Consequences
+
+- Future comparisons should produce a small "borrow/reject" list, not a rewrite.
+- Diagnostics may improve without expanding the mutating surface.
+- End users still configure the MCP once globally and do not set SVN credential env vars.
+- The MCP remains opinionated about safety even when generic SVN tools expose more permissive
+  flags.

package/docs/svnrules.md

@@ -0,0 +1,84 @@
+# SVN Rules
+
+Read when source-changing work reaches diff/commit prep, imports, EOL problems, or tasks
+specifically about SVN state.
+
+## Principle
+
+SVN is for preserving completed work, not for warming up. Do the requested work first. Use SVN only when it is needed for exact diff, EOL diagnosis, conflict diagnosis, or commit.
+
+## When SVN is allowed
+
+- **Before editing:** no SVN command unless the task is about SVN/EOL, the target file is ambiguous, or the user asks.
+- **After editing tracked files:** run scoped diff/status only on touched/intended paths when needed for handoff or commit.
+- **Commit prep:** use scoped MCP `svn_status` and `svn_diff` on intended paths. `svn_diff` runs `svn diff --internal-diff -x "--ignore-eol-style"` by default. Confirm the diff is exactly the requested change.
+- **Property work:** use MCP `svn_propget` and guarded `svn_propset` for generic working-copy properties. Use `svn_propset_eol_style` for `svn:eol-style` when normalizing EOL policy.
+- **`svn update .`:** only when the user explicitly asks or the task is specifically to update/sync the working copy. Never run it as default preflight.
+
+## MCP Registration
+
+Register the SVN MCP once globally. Do not configure a project-specific launch `cwd` or normal-use
+environment variables. For frictionless multi-repo use, pass absolute paths to MCP tools; the MCP
+will infer the matching SVN working copy. Use explicit per-call `cwd` only when working with
+relative paths.
+
+Use `svn_self_check` when the MCP release pointer or bundled toolchain is in question. Use
+`svn_diagnose` when SVN behavior is unclear or raw SVN errors mention authentication, network
+access, working-copy locks, database problems, or stale remote reachability.
+
+## Failsafe: raw svn CLI when the MCP is down
+
+If the SVN MCP fails mechanically — the server is not registered or not responding, tool calls
+error at the protocol level, or envelopes/`svn_diagnose` report "MCP svn runtime unavailable" —
+switch to scoped raw `svn` CLI for the rest of the session instead of stalling:
+
+- Follow the same rules in this file by hand: scoped explicit paths, ignored-EOL diff
+  (`svn diff --internal-diff -x --ignore-eol-style <paths…>`), commit via `-F` message file plus
+  explicit file list, never `--force`, update only on user request with `--accept postpone`,
+  never-commit list still applies, EOL repair via `unix2dos`/`dos2unix` binaries only.
+- A guard refusal is not a failure. Never use the CLI to redo something the MCP refused
+  (READONLY, never-commit, riskAck, explicit-paths, containment). Read-only instances stay
+  read-only in failsafe mode.
+- SVN-level errors (authentication, network, working-copy locks) are not failsafe triggers —
+  the CLI fails the same way; use `svn_diagnose` output to report them instead.
+- Report that the MCP was unavailable and failsafe was used, so it can be repaired;
+  verify with `svn_self_check` once it is back.
+
+## Frequent commits
+
+- Write-capable clients commit after completed, verified, requested-scope, non-risky slices.
+- A commit is never the first step. Implement → verify → inspect diff → commit.
+- Commit only intended paths, one slice at a time.
+- Use a message file and explicit file list: `svn commit -F <msgfile> <path1> <path2>`. Never use bare inline `-m` from an automated session.
+- After commit, report the revision and clean scoped status.
+- If verification fails, fix it or report the exact failure. Do not commit a known-bad slice.
+
+## Risky slices stop before commit
+
+Ask for explicit approval before committing when the slice is large, destructive, schema-changing, version-bumping, build-system-changing, delete-heavy, security-sensitive, or scope-unclear.
+
+## Read-Only Clients
+
+Read-only instances never commit, stage, revert, update, or change SVN state. They may
+describe the intended fix or commit plan for a write-capable client.
+
+## EOL and encoding
+
+- Preserve existing encoding and EOL. Do not normalize whole files.
+- EOL-only churn is not a code change. Check with MCP `svn_diff`; it ignores EOL style by default.
+- If SVN reports inconsistent line endings, use MCP `eol_fix_verified` on that one file. The MCP chooses `unix2dos` or `dos2unix` from `svn:eol-style`, runs the real binary, then re-checks the ignored-EOL diff.
+- Do not use PowerShell byte rewrites, scripts, pipes, or redirects on tracked text files.
+
+## Never commit
+
+In managed project working copies, never commit `bin/`, `dist/`, `node_modules/`, `coverage/`, `obj/`, `.vs/`, `.cache/`, `*.tsbuildinfo`, generated output, `*.db`, `scratch/**`, secrets, keys, certificates, tool caches, or unrelated drive-by changes. The root `bin/` folder in this MCP repository is versioned source for the bundled runtime tools.
+
+## Commit message format
+
+```text
+<short summary>
+
+- <logical change group>
+- <verification performed>
+- <behavior impact, or "No behavior changes">
+```

package/docs/toolrules.md

@@ -0,0 +1,34 @@
+# Tool And PowerShell Rules
+
+Read only when choosing a command/tool, debugging shell behavior, or doing mechanical edits. Do not
+run capability sweeps unless the task is about tool availability.
+
+## Local toolchain
+
+Prefer these tools when available: `rg`, `fd`, `sg`, `jq`, `yq`, `duckdb`, `xsv`, `uv`,
+`python`, `node`, `npm`, `npx`, `dotnet`, `git`, `svn`, `bat`, `glow`, `pandoc`, `ffmpeg`,
+and `ctags`. Project-specific build commands must come from that project's README,
+project instructions, or build scripts.
+
+- `rg` before manual text inspection; `fd` / `rg --files` only to locate a specific named file/pattern (not broad discovery); `sg` for
+  syntax-aware search/edits; `jq`/`duckdb`/`xsv` for structured data.
+- Read-only review roles may only read/search/extract; scripts must print/extract only, never
+  write files or run project code.
+- `graphify` is read/navigation only; the graph lives in the parent repo `.graphify/`. Do not rebuild
+  it unless the user asks.
+- If a tool is missing, say so and use the nearest installed fallback.
+
+## PowerShell
+
+- Prefer simple, targeted commands. Avoid broad recursive `Get-ChildItem` when `rg --files`/`fd` works.
+- Do not use `Set-Content`/`Out-File` on tracked text files; use the Edit/Write tool. Keep tracked
+  text UTF-8 (no BOM where the file already is) and the file's existing EOL.
+- For line slices use `$lines = Get-Content -LiteralPath path; $lines[120..170]`, or
+  `Get-Content path | Select-Object -Skip 120 -First 50`. Do not pass `120..170` directly to
+  `Select-Object -Index`; PowerShell treats it as a string in some invocation contexts.
+- Use single-quoted strings for literal Windows paths. Use `curl.exe`, not `curl`, for real HTTP.
+- Multi-line strings to native exes: single-quoted here-strings with the closing `'@` at column 0.
+- For SVN EOL repair, use MCP `eol_fix_verified` or the bundled `unix2dos`/`dos2unix` binaries.
+  Do not use PowerShell byte rewrites or redirects on tracked text files.
+- For SVN property reads/writes, use MCP `svn_propget` and guarded `svn_propset` before falling
+  back to raw `svn propget` / `svn propset`.

package/jest.config.cjs

@@ -0,0 +1,14 @@
+module.exports = {
+  preset: "ts-jest/presets/default-esm",
+  testEnvironment: "node",
+  extensionsToTreatAsEsm: [".ts"],
+  transform: {
+    "^.+\\.tsx?$": ["ts-jest", { useESM: true }]
+  },
+  moduleNameMapper: {
+    "^(\\.{1,2}/.*)\\.js$": "$1"
+  },
+  roots: ["<rootDir>/src", "<rootDir>/tests"],
+  testMatch: ["**/__tests__/**/*.ts", "**/?(*.)+(spec|test).ts"],
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts"]
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "svn-agent-mcp",
+  "version": "1.0.0",
+  "description": "Strict SVN Model Context Protocol server for agent-safe SVN workflows.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shrishailrana-maker/svn-agent-mcp-v1.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shrishailrana-maker/svn-agent-mcp-v1/issues"
+  },
+  "homepage": "https://github.com/shrishailrana-maker/svn-agent-mcp-v1#readme",
+  "bin": {
+    "svn-agent-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --passWithNoTests",
+    "test:watch": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --watch",
+    "prepare:local": "npm run build && npm run release:prepare",
+    "release:prepare": "node scripts/prepare-release.mjs",
+    "clean": "node scripts/clean.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "svn",
+    "subversion",
+    "model-context-protocol"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fast-xml-parser": "^5.9.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  }
+}

package/scripts/clean.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const dryRun = process.argv.includes("--dry-run");
+const targets = ["dist"];
+
+for (const name of targets) {
+  const target = path.join(root, name);
+  assertInside(root, target);
+  if (dryRun) {
+    console.log(`Would remove ${target}`);
+    continue;
+  }
+  await fs.rm(target, { recursive: true, force: true });
+  console.log(`Removed ${target}`);
+}
+
+function assertInside(base, candidate) {
+  const relative = path.relative(base, candidate);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`refusing to remove outside project root: ${candidate}`);
+  }
+}

package/scripts/prepare-release.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const packageJsonPath = path.join(root, "package.json");
+const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf8"));
+const version = packageJson.version;
+
+if (!version) {
+  throw new Error("package.json version is required");
+}
+
+const sourceDist = path.join(root, "dist");
+const sourceBin = path.join(root, "bin");
+const releasesRoot = path.join(root, "releases");
+const releaseRoot = path.join(releasesRoot, `v${version}`);
+const releaseDist = path.join(releaseRoot, "dist");
+const releaseBin = path.join(releaseRoot, "bin");
+const current = path.join(root, "current");
+
+for (const target of [releasesRoot, releaseRoot, releaseDist, releaseBin, current]) {
+  assertInside(root, target);
+}
+
+await assertDirectory(sourceDist, "dist is missing; run npm run build first");
+await assertDirectory(sourceBin, "bin is missing; bundled runtime payload is required");
+
+await fs.rm(releaseRoot, { recursive: true, force: true });
+await fs.mkdir(releaseRoot, { recursive: true });
+await fs.cp(sourceDist, releaseDist, { recursive: true });
+await fs.cp(sourceBin, releaseBin, { recursive: true });
+
+const binFileCount = await countFiles(releaseBin);
+const distFileCount = await countFiles(releaseDist);
+if (binFileCount < 35) {
+  throw new Error(`release bin payload is incomplete: expected at least 35 files, found ${binFileCount}`);
+}
+if (distFileCount < 60) {
+  throw new Error(`release dist payload is incomplete: expected at least 60 files, found ${distFileCount}`);
+}
+
+await fs.rm(current, { recursive: true, force: true });
+await fs.symlink(path.relative(root, releaseRoot), current, process.platform === "win32" ? "junction" : "dir");
+
+console.log(`Prepared release v${version}`);
+console.log(`  dist: ${releaseDist} (${distFileCount} files)`);
+console.log(`  bin: ${releaseBin} (${binFileCount} files)`);
+console.log(`  current -> ${releaseRoot}`);
+
+async function assertDirectory(candidate, message) {
+  try {
+    const stat = await fs.stat(candidate);
+    if (stat.isDirectory()) {
+      return;
+    }
+  } catch {
+    // handled below
+  }
+  throw new Error(message);
+}
+
+function assertInside(base, candidate) {
+  const relative = path.relative(base, candidate);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(`refusing to write outside project root: ${candidate}`);
+  }
+}
+
+async function countFiles(directory) {
+  const entries = await fs.readdir(directory, { withFileTypes: true });
+  let count = 0;
+  for (const entry of entries) {
+    const child = path.join(directory, entry.name);
+    if (entry.isDirectory()) {
+      count += await countFiles(child);
+    } else if (entry.isFile()) {
+      count += 1;
+    }
+  }
+  return count;
+}

package/src/envelope.ts

@@ -0,0 +1,182 @@
+import type { ChangedPath, Conflict, Envelope, RunResult } from "./types.js";
+
+const DEFAULT_SUMMARY_LINES = 200;
+
+export function redactArgv(executable: string, args: string[]): string {
+  const redacted = [executable, ...args];
+  for (let index = 0; index < redacted.length; index += 1) {
+    const value = redacted[index] ?? "";
+    const arg = value.toLowerCase();
+    if ((arg === "--password" || arg === "--username") && index + 1 < redacted.length) {
+      redacted[index + 1] = "***";
+      continue;
+    }
+    if (arg.startsWith("--password=") || arg.startsWith("--username=")) {
+      const equalsIndex = value.indexOf("=");
+      redacted[index] = `${value.slice(0, equalsIndex)}=***`;
+      continue;
+    }
+    redacted[index] = redactText(redacted[index] ?? "");
+  }
+
+  return redacted.map(quoteArgForDisplay).join(" ");
+}
+
+export function quoteArgForDisplay(arg: string): string {
+  if (arg.length === 0) {
+    return '""';
+  }
+
+  if (/[\s"]/.test(arg)) {
+    return `"${arg.replace(/"/g, '\\"')}"`;
+  }
+
+  return arg;
+}
+
+export function redactText(value: string): string {
+  const withSafeUrl = redactUrlUserinfo(value);
+  return withSafeUrl.replace(
+    /([?&](?:access_token|api[_-]?key|auth|key|pass(?:word)?|secret|token)=)[^&#\s]*/gi,
+    "$1***"
+  );
+}
+
+function redactUrlUserinfo(value: string): string {
+  return value.replace(/([a-z][a-z0-9+.-]*:\/\/)(?:[^\s/?#]*@)+/gi, "$1***:***@");
+}
+
+export function summarizeText(text: string, maxLines = DEFAULT_SUMMARY_LINES): { text: string; truncated: boolean } {
+  if (!text) {
+    return { text: "", truncated: false };
+  }
+
+  const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const lines = normalized.split("\n");
+  if (lines.length <= maxLines) {
+    return { text: normalized, truncated: false };
+  }
+
+  return {
+    text: lines.slice(0, maxLines).join("\n"),
+    truncated: true
+  };
+}
+
+export function createEnvelope(input: {
+  ok: boolean;
+  command: string;
+  cwd: string;
+  revision?: number | null | undefined;
+  changed_paths?: ChangedPath[] | undefined;
+  conflicts?: Conflict[] | undefined;
+  stdout?: string | undefined;
+  stderr?: string | undefined;
+  truncated?: boolean | undefined;
+  note?: string | undefined;
+}): Envelope {
+  const stdout = summarizeText(redactText(input.stdout ?? ""));
+  const stderr = summarizeText(redactText(input.stderr ?? ""));
+
+  return {
+    ok: input.ok,
+    command: input.command,
+    cwd: input.cwd,
+    revision: input.revision ?? null,
+    changed_paths: input.changed_paths ?? [],
+    conflicts: input.conflicts ?? [],
+    stdout_summary: stdout.text,
+    stderr_summary: stderr.text,
+    truncated: Boolean(input.truncated || stdout.truncated || stderr.truncated),
+    note: input.note ?? ""
+  };
+}
+
+export function envelopeFromRun(input: {
+  ok?: boolean | undefined;
+  run: RunResult;
+  revision?: number | null | undefined;
+  changed_paths?: ChangedPath[] | undefined;
+  conflicts?: Conflict[] | undefined;
+  note?: string | undefined;
+  truncated?: boolean | undefined;
+}): Envelope {
+  return createEnvelope({
+    ok: input.ok ?? input.run.exitCode === 0,
+    command: input.run.command,
+    cwd: input.run.cwd,
+    revision: input.revision ?? null,
+    changed_paths: input.changed_paths,
+    conflicts: input.conflicts,
+    stdout: input.run.stdout,
+    stderr: input.run.stderr,
+    truncated: input.truncated ?? input.run.truncated,
+    note: input.note ?? noteFromRun(input.run)
+  });
+}
+
+export function failEnvelope(command: string, cwd: string, note: string, extra?: Partial<Envelope>): Envelope {
+  return {
+    ...createEnvelope({
+      ok: false,
+      command,
+      cwd,
+      note
+    }),
+    ...extra,
+    ok: false,
+    command,
+    cwd,
+    note
+  };
+}
+
+export function noteFromRun(run: RunResult): string {
+  if (run.timedOut) {
+    return "svn timed out";
+  }
+
+  if (run.errorCode === "ENOENT" || run.errorCode === "EACCES" || run.errorCode === "EPERM") {
+    return "MCP svn runtime unavailable (executable failed to launch) - failsafe: use scoped raw svn CLI for this session per svnrules; guard refusals are not failures and must never be bypassed via CLI";
+  }
+
+  const text = `${run.stderr}\n${run.stdout}`;
+  if (/E155004|E155036/.test(text)) {
+    return "working copy locked - run svn_cleanup";
+  }
+  if (/E215004|No more credentials|we tried too many times|E170001|authorization failed|Authentication failed/i.test(text)) {
+    return "authentication failed - fix svn cached auth outside the MCP";
+  }
+  if (/E175002|Unable to connect|Connection refused|Network is unreachable|Could not resolve hostname/i.test(text)) {
+    return "network or repository connection failed";
+  }
+  if (/E155007/.test(text)) {
+    return "path is not inside a working copy";
+  }
+  if (/E135000|inconsistent newlines|inconsistent line ending style/i.test(text)) {
+    return "inconsistent line endings - run eol_fix_verified on affected files";
+  }
+  if (/E200009|is not a working copy|unversioned/i.test(text)) {
+    return "target not versioned";
+  }
+  if (/E200030|sqlite|database is locked|database disk image is malformed/i.test(text)) {
+    return "working copy database problem - run svn_cleanup";
+  }
+
+  return run.exitCode === 0 ? "" : "svn command failed";
+}
+
+export function toToolResult<T extends Envelope>(payload: T): {
+  content: Array<{ type: "text"; text: string }>;
+  structuredContent: T;
+} {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(payload, null, 2)
+      }
+    ],
+    structuredContent: payload
+  };
+}