vibe-coding-master 0.9.1 → 0.9.3

package/scripts/claude-plugins/vcm-lsp-bridge/vcm-lsp-proxy.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+// Stdio proxy between Claude Code's LSP client and one language server.
+//
+// Usage: node vcm-lsp-proxy.mjs -- <server-command> [server-args...]
+//
+// A language server that is still loading or indexing answers navigation
+// queries with partial or empty results, which reads as "no references".
+// The proxy tracks the server's work-done progress (and rust-analyzer's
+// quiescence status), holds navigation queries until the server is idle, and
+// fails a query with an explicit "still indexing" error when the server does
+// not become idle in time. Every other message passes through unchanged.
+
+import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const NAVIGATION_METHODS = new Set([
+  "textDocument/definition",
+  "textDocument/declaration",
+  "textDocument/typeDefinition",
+  "textDocument/implementation",
+  "textDocument/references",
+  "textDocument/hover",
+  "textDocument/documentSymbol",
+  "textDocument/prepareCallHierarchy",
+  "callHierarchy/incomingCalls",
+  "callHierarchy/outgoingCalls",
+  "workspace/symbol"
+]);
+
+const READY_TIMEOUT_MS = positiveNumber(process.env.VCM_LSP_READY_TIMEOUT_MS, 180_000);
+// Servers announce indexing shortly after "initialized"; a query sent before
+// any progress appears waits this long for indexing to start.
+const STARTUP_GRACE_MS = positiveNumber(process.env.VCM_LSP_STARTUP_GRACE_MS, 2_000);
+const REQUEST_FAILED = -32803;
+const REQUEST_CANCELLED = -32800;
+
+function positiveNumber(raw, fallback) {
+  const value = Number(raw);
+  return Number.isFinite(value) && value >= 0 ? value : fallback;
+}
+
+// Parses Content-Length framed JSON-RPC messages from a byte stream.
+export function createMessageReader(onMessage) {
+  let buffer = Buffer.alloc(0);
+  return (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (true) {
+      const headerEnd = buffer.indexOf("\r\n\r\n");
+      if (headerEnd < 0) {
+        return;
+      }
+      const header = buffer.subarray(0, headerEnd).toString("ascii");
+      const match = /content-length:\s*(\d+)/i.exec(header);
+      if (!match) {
+        // Unframed bytes cannot be routed; drop the header and resynchronize.
+        buffer = buffer.subarray(headerEnd + 4);
+        continue;
+      }
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      if (buffer.length < bodyStart + length) {
+        return;
+      }
+      const body = buffer.subarray(bodyStart, bodyStart + length).toString("utf8");
+      buffer = buffer.subarray(bodyStart + length);
+      onMessage(JSON.parse(body));
+    }
+  };
+}
+
+export function frameMessage(message) {
+  const body = Buffer.from(JSON.stringify(message), "utf8");
+  return Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii"), body]);
+}
+
+// Readiness state shared by both directions of the proxy.
+export function createReadinessTracker(options = {}) {
+  const now = options.now ?? Date.now;
+  const activeProgress = new Map();
+  let quiescent = true;
+  let initializedAt;
+  let progressSeen = false;
+  const listeners = new Set();
+
+  function notify() {
+    for (const listener of [...listeners]) {
+      listener();
+    }
+  }
+
+  return {
+    markInitialized() {
+      initializedAt = now();
+    },
+    progressBegin(token, title) {
+      progressSeen = true;
+      activeProgress.set(String(token), title || "indexing");
+      notify();
+    },
+    progressEnd(token) {
+      activeProgress.delete(String(token));
+      notify();
+    },
+    serverStatus(isQuiescent) {
+      progressSeen = true;
+      quiescent = isQuiescent;
+      notify();
+    },
+    // Remaining startup grace in ms, or 0 once it no longer applies.
+    graceRemaining() {
+      if (progressSeen || initializedAt === undefined) {
+        return 0;
+      }
+      return Math.max(0, initializedAt + (options.startupGraceMs ?? STARTUP_GRACE_MS) - now());
+    },
+    isBusy() {
+      return activeProgress.size > 0 || !quiescent;
+    },
+    busyReason() {
+      const titles = [...new Set(activeProgress.values())];
+      if (!quiescent) {
+        titles.push("server not quiescent");
+      }
+      return titles.join(", ") || "starting up";
+    },
+    onChange(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }
+  };
+}
+
+export function startProxy({ command, args, input, output, errorOutput, readyTimeoutMs = READY_TIMEOUT_MS, startupGraceMs = STARTUP_GRACE_MS }) {
+  const server = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"] });
+  const readiness = createReadinessTracker({ startupGraceMs });
+  const pending = new Map();
+  let clientWantsProgress = false;
+  let clientWantsServerStatus = false;
+
+  const toClient = (message) => output.write(frameMessage(message));
+  const toServer = (message) => {
+    if (server.stdin.writable) {
+      server.stdin.write(frameMessage(message));
+    }
+  };
+
+  server.stderr.pipe(errorOutput);
+  server.on("error", (error) => {
+    errorOutput.write(`vcm-lsp-proxy: cannot start ${command}: ${error.message}\n`);
+    process.exitCode = 1;
+    output.end?.();
+  });
+  server.on("exit", (code, signal) => {
+    for (const entry of pending.values()) {
+      entry.dispose();
+    }
+    process.exitCode = code ?? (signal ? 1 : 0);
+    output.end?.();
+  });
+
+  function releaseWhenReady(message) {
+    const key = String(message.id);
+    let timer;
+    let graceTimer;
+    let unsubscribe = () => undefined;
+    const dispose = () => {
+      clearTimeout(timer);
+      clearTimeout(graceTimer);
+      unsubscribe();
+      pending.delete(key);
+    };
+    const attempt = () => {
+      const grace = readiness.graceRemaining();
+      if (grace > 0) {
+        clearTimeout(graceTimer);
+        graceTimer = setTimeout(attempt, grace);
+        return;
+      }
+      if (!readiness.isBusy()) {
+        dispose();
+        toServer(message);
+      }
+    };
+    pending.set(key, {
+      dispose,
+      cancel() {
+        dispose();
+        toClient({ jsonrpc: "2.0", id: message.id, error: { code: REQUEST_CANCELLED, message: "Request cancelled." } });
+      }
+    });
+    unsubscribe = readiness.onChange(attempt);
+    timer = setTimeout(() => {
+      dispose();
+      toClient({
+        jsonrpc: "2.0",
+        id: message.id,
+        error: {
+          code: REQUEST_FAILED,
+          message: `Language server is still indexing (${readiness.busyReason()}) after ${Math.round(readyTimeoutMs / 1000)}s; ${message.method} results would be incomplete. Retry after indexing finishes, or record the relationship as unresolved.`
+        }
+      });
+    }, readyTimeoutMs);
+    attempt();
+  }
+
+  input.on("data", createMessageReader((message) => {
+    if (message.method === "initialize" && message.params) {
+      const capabilities = message.params.capabilities ?? {};
+      clientWantsProgress = capabilities.window?.workDoneProgress === true;
+      clientWantsServerStatus = capabilities.experimental?.serverStatusNotification === true;
+      message.params.capabilities = {
+        ...capabilities,
+        window: { ...capabilities.window, workDoneProgress: true },
+        experimental: { ...capabilities.experimental, serverStatusNotification: true }
+      };
+    }
+    if (message.method === "initialized") {
+      readiness.markInitialized();
+    }
+    if (message.method === "$/cancelRequest" && pending.has(String(message.params?.id))) {
+      pending.get(String(message.params.id)).cancel();
+      return;
+    }
+    if (message.id !== undefined && NAVIGATION_METHODS.has(message.method)) {
+      releaseWhenReady(message);
+      return;
+    }
+    toServer(message);
+  }));
+  input.on("end", () => server.stdin.end());
+
+  server.stdout.on("data", createMessageReader((message) => {
+    if (message.method === "window/workDoneProgress/create") {
+      if (!clientWantsProgress) {
+        toServer({ jsonrpc: "2.0", id: message.id, result: null });
+        return;
+      }
+    } else if (message.method === "$/progress") {
+      const value = message.params?.value;
+      if (value?.kind === "begin") {
+        readiness.progressBegin(message.params.token, value.title);
+      } else if (value?.kind === "end") {
+        readiness.progressEnd(message.params.token);
+      }
+      if (!clientWantsProgress) {
+        return;
+      }
+    } else if (message.method === "experimental/serverStatus") {
+      readiness.serverStatus(message.params?.quiescent !== false);
+      if (!clientWantsServerStatus) {
+        return;
+      }
+    }
+    toClient(message);
+  }));
+
+  return { server, readiness };
+}
+
+const separator = process.argv.indexOf("--");
+if (separator >= 0 && process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const [command, ...args] = process.argv.slice(separator + 1);
+  if (!command) {
+    process.stderr.write("usage: vcm-lsp-proxy.mjs -- <server-command> [args...]\n");
+    process.exit(2);
+  }
+  const { server } = startProxy({ command, args, input: process.stdin, output: process.stdout, errorOutput: process.stderr });
+  // Exit with the server so Claude Code sees the crash and restarts it; an open
+  // stdin would otherwise keep the proxy alive with no server behind it.
+  server.on("exit", (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
+  server.on("error", () => process.exit(1));
+}

package/scripts/harness-tools/check-docs-sync

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+"use strict";
+// Check that the architecture plan's Docs Impact covers every module the task
+// touched. Without .ai/generated/module-index.json the repository is one module
+// named "." whose owning doc is docs/ARCHITECTURE.md (or its docs/architecture/
+// area docs).
+//
+// Usage:
+//   .ai/tools/check-docs-sync [--base <commit>] [--json]
+//
+// The check compares the task's commits (base..HEAD, excluding [VCM Harness]
+// commits) with .ai/generated/module-index.json and the Docs Impact table of
+// .ai/vcm/handoffs/architecture-plan.md:
+//   - every module touched by a code change had its owning architecture doc
+//     changed in the task or has a Docs Impact row for that doc;
+//   - a Docs Impact row that records no change gives its reason;
+//   - every document Docs Impact records as changed was changed.
+// A task without a complete architecture plan (an Architect Debug Flow or an
+// Architecture Diagnosis Flow) is skipped.
+// The base defaults to the merge-base of HEAD with the base repository's HEAD.
+
+const childProcess = require("node:child_process");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const HARNESS_COMMIT_PREFIX = "[VCM Harness] ";
+const PLAN_PATH = ".ai/vcm/handoffs/architecture-plan.md";
+const MODULE_INDEX_PATH = ".ai/generated/module-index.json";
+const PROJECT_DOC = "docs/ARCHITECTURE.md";
+const AREA_DOC_DIR = "docs/architecture/";
+const USAGE = "usage: check-docs-sync [-h] [--base BASE] [--json]";
+
+function usageError(message) {
+  process.stderr.write(USAGE + "\ncheck-docs-sync: error: " + message + "\n");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const args = { base: undefined, json: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "-h" || argument === "--help") {
+      process.stdout.write(USAGE + "\n\nCheck that the architecture plan's Docs Impact covers every touched module.\n");
+      process.exit(0);
+    } else if (argument === "--json") {
+      args.json = true;
+    } else if (argument === "--base") {
+      if (index + 1 >= argv.length) {
+        usageError("argument " + argument + ": expected one argument");
+      }
+      index += 1;
+      args.base = argv[index];
+    } else {
+      usageError("unrecognized arguments: " + argument);
+    }
+  }
+  return args;
+}
+
+function git(root, args) {
+  const result = childProcess.spawnSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 256 * 1024 * 1024 });
+  return result.status === 0 ? result.stdout.trim() : "";
+}
+
+function repositoryRoot() {
+  return git(process.cwd(), ["rev-parse", "--show-toplevel"]) || process.cwd();
+}
+
+// The task branch forks from the base repository's checked-out branch, which
+// is the main worktree sharing this repository's git directory.
+function resolveBase(root, explicit) {
+  if (explicit) {
+    return git(root, ["rev-parse", "--verify", explicit + "^{commit}"]) || undefined;
+  }
+  const fromEnv = (process.env.VCM_BASE_COMMIT || "").trim();
+  if (fromEnv && git(root, ["rev-parse", "--verify", fromEnv + "^{commit}"])) {
+    return fromEnv;
+  }
+  const commonDir = git(root, ["rev-parse", "--path-format=absolute", "--git-common-dir"]);
+  const baseHead = commonDir ? git(root, ["--git-dir", commonDir, "rev-parse", "HEAD"]) : "";
+  const head = git(root, ["rev-parse", "HEAD"]);
+  if (baseHead && baseHead !== head) {
+    return git(root, ["merge-base", "HEAD", baseHead]) || undefined;
+  }
+  const upstream = git(root, ["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}"]);
+  return upstream ? git(root, ["merge-base", "HEAD", upstream]) || undefined : undefined;
+}
+
+function taskCommits(root, base) {
+  const lines = git(root, ["log", "--format=%H%x09%s", base + "..HEAD"]).split("\n").filter(Boolean);
+  return lines
+    .map((line) => {
+      const separator = line.indexOf("\t");
+      return { sha: line.slice(0, separator), subject: line.slice(separator + 1) };
+    })
+    .filter((commit) => !commit.subject.startsWith(HARNESS_COMMIT_PREFIX))
+    .map((commit) => ({
+      ...commit,
+      files: git(root, ["show", "--format=", "--name-only", "--no-renames", commit.sha]).split("\n").filter(Boolean)
+    }));
+}
+
+function isArchitectureDoc(file) {
+  return file === PROJECT_DOC || file.startsWith(AREA_DOC_DIR) || path.posix.basename(file) === "ARCHITECTURE.md";
+}
+
+// Files that describe or derive from code rather than change it.
+function isDocumentationFile(file) {
+  return isArchitectureDoc(file) || file.startsWith("docs/") || file.startsWith(".ai/") || /\.md$/i.test(file);
+}
+
+// The repository as one module, for projects without a module index (the
+// generator supports Cargo and npm workspaces only).
+const ROOT_MODULE = { name: ".", path: ".", doc: PROJECT_DOC };
+
+function loadModules(root) {
+  const target = path.join(root, MODULE_INDEX_PATH);
+  if (!fs.existsSync(target)) {
+    return [ROOT_MODULE];
+  }
+  const index = JSON.parse(fs.readFileSync(target, "utf8"));
+  return (index.layers || []).flatMap((layer) => layer.modules || []).map((module) => ({
+    name: module.name,
+    path: module.path || ".",
+    doc: module.path && module.path !== "." ? module.architectureDoc || module.path + "/ARCHITECTURE.md" : PROJECT_DOC
+  }));
+}
+
+function owningModule(modules, file) {
+  let best;
+  for (const module of modules) {
+    const prefix = module.path === "." ? "" : module.path + "/";
+    if ((prefix === "" || file.startsWith(prefix)) && (!best || prefix.length > best.prefix.length)) {
+      best = { module, prefix };
+    }
+  }
+  return best && best.module;
+}
+
+function sectionContent(content, heading) {
+  const match = new RegExp("^#{1,6}\\s+" + heading.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&") + "\\s*$", "im").exec(content);
+  if (!match) {
+    return undefined;
+  }
+  const after = content.slice(match.index + match[0].length);
+  const next = /\n#{1,6}\s+\S/.exec(after);
+  return (next ? after.slice(0, next.index) : after).replace(/<!--[\s\S]*?-->/g, "").trim();
+}
+
+function tableRows(section) {
+  const lines = (section || "").split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith("|"));
+  return lines.slice(2).map((line) => line.replace(/^\|/, "").replace(/\|$/, "").split("|").map((cell) => cell.trim().replace(/^`|`$/g, "")));
+}
+
+function finding(code, subject, message) {
+  return { code, subject, message };
+}
+
+function planIsComplete(content) {
+  return /^Planning Result:\s*complete\s*$/im.test(content);
+}
+
+// A module's doc is the project doc or one of its area docs for the root module.
+function documentsModule(module, document) {
+  return module.doc === PROJECT_DOC
+    ? document === PROJECT_DOC || document.startsWith(AREA_DOC_DIR)
+    : document === module.doc;
+}
+
+function check(root, planContent, base) {
+  const findings = [];
+  const modules = loadModules(root);
+  const commits = taskCommits(root, base);
+  const changed = new Set(commits.flatMap((commit) => commit.files));
+
+  const touched = new Map();
+  for (const file of changed) {
+    if (isDocumentationFile(file)) {
+      continue;
+    }
+    const module = owningModule(modules, file);
+    if (module) {
+      touched.set(module.path, module);
+    }
+  }
+
+  const rows = tableRows(sectionContent(planContent, "Docs Impact")).map(([documentCell, change, reason]) => ({
+    document: (documentCell || "").split(/\s+/)[0],
+    change: change || "",
+    reason: reason || ""
+  }));
+  const docChanged = (module) => [...changed].some((file) => documentsModule(module, file));
+
+  for (const module of touched.values()) {
+    if (!docChanged(module) && !rows.some((row) => documentsModule(module, row.document))) {
+      findings.push(finding("DS_MODULE_NOT_COVERED", module.path,
+        "Module " + module.name + " (" + module.path + ") changed in the task, but neither its owning doc " + module.doc
+          + " changed nor does Docs Impact list it with the reason no owned fact changed."));
+    }
+  }
+
+  for (const row of rows) {
+    if (!/\.md$/i.test(row.document)) {
+      continue;
+    }
+    const unchanged = !row.change || /^(none|unchanged|no change)\b/i.test(row.change);
+    if (unchanged && !/\w/.test(row.reason.replace(/^(none|tbd)\.?$/i, ""))) {
+      findings.push(finding("DS_UNCHANGED_WITHOUT_REASON", row.document,
+        "Docs Impact records no change to " + row.document + " without the reason no owned fact changed."));
+    } else if (!unchanged && !changed.has(row.document)) {
+      findings.push(finding("DS_PLANNED_DOC_NOT_CHANGED", row.document,
+        "Docs Impact records a change to " + row.document + ", but the task did not change it."));
+    }
+  }
+  return findings;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const root = repositoryRoot();
+  const planPath = path.join(root, PLAN_PATH);
+  const plan = fs.existsSync(planPath) ? fs.readFileSync(planPath, "utf8") : "";
+  if (!planIsComplete(plan)) {
+    const reason = "No complete " + PLAN_PATH + "; the task has no Docs Impact to check.";
+    process.stdout.write(args.json ? JSON.stringify({ skipped: reason, findings: [] }, null, 2) + "\n" : reason + "\n");
+    return 0;
+  }
+  const base = resolveBase(root, args.base);
+  if (!base) {
+    process.stderr.write("check-docs-sync: cannot determine the task base commit; pass --base <commit>.\n");
+    return 2;
+  }
+  const findings = check(root, plan, base);
+  if (args.json) {
+    process.stdout.write(JSON.stringify({ base, findings }, null, 2) + "\n");
+  } else if (findings.length === 0) {
+    process.stdout.write("Docs sync check passed.\n");
+  } else {
+    for (const item of findings) {
+      process.stdout.write(item.code + " " + item.subject + ": " + item.message + "\n");
+    }
+  }
+  return findings.length === 0 ? 0 : 1;
+}
+
+process.exitCode = main();

package/scripts/harness-tools/check-durable-docs

@@ -303,6 +303,29 @@ function checkGeneratedArchitectureFacts(root, findings) {
   });
 }
 
+// Area docs under docs/architecture/ split the project doc's detailed design,
+// so docs/ARCHITECTURE.md must link each one.
+function checkAreaDocLinks(root, findings) {
+  const areaDir = path.join(root, "docs/architecture");
+  let entries;
+  try {
+    entries = fs.readdirSync(areaDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const projectDoc = path.join(root, "docs/ARCHITECTURE.md");
+  const projectText = isFile(projectDoc) ? fs.readFileSync(projectDoc, "utf8") : "";
+  for (const entry of entries.sort((left, right) => (left.name < right.name ? -1 : 1))) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) {
+      continue;
+    }
+    if (!projectText.includes("architecture/" + entry.name)) {
+      findings.push(finding("DD_AREA_DOC_UNLINKED", "docs/architecture/" + entry.name, 1,
+        "Area architecture doc is not linked from docs/ARCHITECTURE.md."));
+    }
+  }
+}
+
 function main(argv) {
   const args = parseArgs(argv);
   const root = repositoryRoot();
@@ -312,6 +335,7 @@ function main(argv) {
   checkArchitectureHistory(root, findings);
   checkTestingHistory(root, findings);
   checkGeneratedArchitectureFacts(root, findings);
+  checkAreaDocLinks(root, findings);
   findings.sort((left, right) =>
     left.path < right.path ? -1 : left.path > right.path ? 1
       : left.line !== right.line ? left.line - right.line

package/scripts/harness-tools/run-long-check

@@ -9,7 +9,7 @@
 // wrappers are rejected because they can hide the validation command's exit code.
 //
 // The command runs in a detached worker process group. The worker itself
-// enforces the job ceiling (--timeout, max 60m) and a supervision lease: when
+// enforces the job ceiling (--timeout, max 100m) and a supervision lease: when
 // no foreground watcher renews .ai/vcm/jobs/<job-id>/lease, the worker kills
 // the command process group and records the job as orphaned. Watch the job
 // with .ai/tools/watch-job in the same turn.
@@ -22,7 +22,7 @@ const fs = require("node:fs");
 const os = require("node:os");
 const path = require("node:path");
 
-const MAX_TIMEOUT_SECONDS = 60 * 60;
+const MAX_TIMEOUT_SECONDS = 100 * 60;
 const DEFAULT_TIMEOUT_SECONDS = MAX_TIMEOUT_SECONDS;
 const QUEUED_STALE_SECONDS = 60;
 const ACTIVE_STATUSES = new Set(["queued", "starting", "running"]);
@@ -584,7 +584,7 @@ async function main(argv) {
     return 2;
   }
   if (timeoutSeconds > MAX_TIMEOUT_SECONDS) {
-    process.stderr.write("error: timeout exceeds maximum 60m; split the work or get user approval\n");
+    process.stderr.write("error: timeout exceeds maximum 100m; split the work or get user approval\n");
     return 2;
   }
 

package/scripts/verify-package.mjs

@@ -7,7 +7,9 @@ const requiredFiles = [
   "package.json",
   "scripts/fix-node-pty-spawn-helper.mjs",
   "scripts/claude-plugins/vcm-lsp-bridge/.claude-plugin/plugin.json",
+  "scripts/claude-plugins/vcm-lsp-bridge/vcm-lsp-proxy.mjs",
   "scripts/harness-tools/check-durable-docs",
+  "scripts/harness-tools/check-docs-sync",
   "scripts/harness-tools/generate-module-index",
   "scripts/harness-tools/generate-public-surface",
   "scripts/harness-tools/run-long-check",