ravensight-playtest 0.1.0 → 0.2.3

package/src/run/repoTools.js

@@ -1,4 +1,5 @@
-import { readFile, readdir, stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, readdir, realpath, rename, stat, unlink, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { scanForSecrets } from './secretScan.js';
 
@@ -8,8 +9,16 @@ import { scanForSecrets } from './secretScan.js';
  * `routing.json`'s `game_profile.triage` allows (and `read_file` alone on
  * `game_profile.synthesis` and `aggregate.synthesis`).
  *
- * Read-only is enforced here, not asked for in a prompt. There is no write,
- * no shell, no network, and:
+ * `fix.apply` is the one step that also gets `write_file`, and it gets it
+ * through `WRITE_TOOLS` rather than through `PROFILE_TOOLS`: a step that is
+ * allowed to read a repository should not gain the ability to write to it
+ * because somebody appended to the wrong array. `write_file` is refused
+ * outright unless the caller asked for it by name, so `createRepoTools()`
+ * with its default tool set answers "there is no tool called write_file",
+ * exactly as it did before that tool existed.
+ *
+ * Read-only is enforced here, not asked for in a prompt. There is no shell,
+ * no network, and:
  *
  * - every path is resolved and refused if it leaves the root, so `../../`
  *   and a symlink out of the tree both fail;
@@ -33,6 +42,16 @@ export const SKIP_DIRS = Object.freeze([
   '.venv', 'venv', '__pycache__', '.next', '.cache', 'coverage'
 ]);
 
+/**
+ * The two names refused at any position in a path, not just as a directory.
+ * Both hold the machinery rather than the game: git's own database, and this
+ * CLI's journals and reports.
+ */
+export const NEVER_TOUCHED = Object.freeze(['.git', '.ravensight']);
+
+/** `SKIP_DIRS`, lowercased once, because the comparison is case insensitive. */
+const SKIP_DIRS_LOWER = Object.freeze(SKIP_DIRS.map(name => name.toLowerCase()));
+
 /** Files never read, whatever asks for them. */
 export const SECRET_FILE_PATTERNS = Object.freeze([
   /(^|\/)\.env($|\.)/i,
@@ -49,7 +68,13 @@ export const MAX_READ_BYTES = 120000;
 export const MAX_GLOB_RESULTS = 400;
 
 /** How many matching lines a grep answers with. */
-export const MAX_GREP_RESULTS = 200;
+/**
+ * Sixty, not two hundred: at three hundred characters a line the old cap
+ * let one grep put 60 KB into the context, and forty greps in one apply loop
+ * ate the whole model budget without a write. A capped answer says so, so
+ * the model narrows rather than repeats.
+ */
+export const MAX_GREP_RESULTS = 60;
 
 /** The tool definitions for `game_profile.triage`. */
 export const PROFILE_TOOLS = Object.freeze([
@@ -95,6 +120,60 @@ export const PROFILE_TOOLS = Object.freeze([
 /** The subset allowed on the synthesis steps. */
 export const READ_ONLY_TOOLS = Object.freeze(PROFILE_TOOLS.filter(tool => tool.name === 'read_file'));
 
+/**
+ * A NUL byte, built rather than written, so this source file stays plain text
+ * that a diff and a code review can read.
+ */
+const NUL = String.fromCharCode(0);
+
+/** How many bytes one `write_file` may put on disk. */
+export const MAX_WRITE_BYTES = 200000;
+
+/** How many distinct paths one run may write. A fix is a patch, not a rewrite. */
+export const MAX_WRITES_PER_RUN = 20;
+
+/**
+ * The two writing tools, defined here so nothing else can invent a third.
+ *
+ * `edit_file` exists because whole-file writes do not survive contact with a
+ * real codebase: the first production fix attempt read an 84 KB C++ file and
+ * then could not send it back inside the step's output ceiling, so its one
+ * write arrived as malformed input and the attempt ended with nothing on the
+ * branch. An exact-text replacement is a few hundred bytes for the same edit.
+ */
+export const EDIT_FILE_TOOL = Object.freeze({
+  name: 'edit_file',
+  description: 'Replace one exact passage of a text file in the repository with new text. Paths are relative to the repository root. old_text must appear exactly once in the file (or set replace_all for every occurrence); copy it verbatim from read_file, whitespace included. This is the tool for changing a file that already exists.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['path', 'old_text', 'new_text'],
+    properties: {
+      path: { type: 'string' },
+      old_text: { type: 'string' },
+      new_text: { type: 'string' },
+      replace_all: { type: 'boolean' }
+    }
+  }
+});
+
+export const WRITE_FILE_TOOL = Object.freeze({
+  name: 'write_file',
+  description: 'Write a text file in the repository, replacing it whole. Paths are relative to the repository root. Use it for a new file or a small one; for a change to an existing file use edit_file, because the content you send here is the whole file.',
+  input_schema: {
+    type: 'object',
+    additionalProperties: false,
+    required: ['path', 'content'],
+    properties: {
+      path: { type: 'string' },
+      content: { type: 'string' }
+    }
+  }
+});
+
+/** The tool definitions for `fix.apply`: the read-only three, plus the two writes. */
+export const WRITE_TOOLS = Object.freeze([...PROFILE_TOOLS, EDIT_FILE_TOOL, WRITE_FILE_TOOL]);
+
 /**
  * Compile a glob into a regular expression. Supports `**`, `*` and `?`,
  * which covers every pattern the profile skill actually asks for
@@ -133,6 +212,58 @@ export function globToRegExp(pattern) {
   return new RegExp(`^${source}$`);
 }
 
+/**
+ * Whether a path lives inside a directory the walk never enters.
+ *
+ * `listFiles` already skips these, so a read of one answers nothing useful;
+ * a write to one is worse than useless. `.git` is the reason this check exists
+ * at all: a model that can write into `.git` can rewrite history without ever
+ * running git, and this CLI never rewrites history.
+ *
+ * Two rules, not one:
+ *
+ * - The names are compared **case insensitively**, because macOS and Windows
+ *   filesystems are. `.GIT/hooks/pre-commit` is `.git/hooks/pre-commit` on the
+ *   developer's disk, and a case-sensitive check let exactly that through:
+ *   the hook was written, and the diff then reported no change, so the unit
+ *   was refunded while the repository had been modified.
+ * - `.git` and `.ravensight` are refused at **any** position, the last one
+ *   included. A file called `.git` is a gitfile whose contents repoint the
+ *   repository at another directory, so writing one is as bad as writing
+ *   inside `.git` itself. Every other name only matters as a directory: a
+ *   source file called `build` is ordinary.
+ *
+ * @param {string} relativePath
+ * @returns {string|null} the offending component, or null
+ */
+export function skippedDirIn(relativePath) {
+  const raw = String(relativePath).split(path.sep).join('/');
+  // A trailing slash means the caller is naming a directory, which is how
+  // `git status --porcelain` reports an untracked one (`?? node_modules/`).
+  // Then every segment is a directory; otherwise the last one is a file name.
+  const namesADirectory = raw.endsWith('/');
+  const segments = raw.split('/').filter(Boolean);
+  const lowered = segments.map(segment => segment.toLowerCase());
+
+  const always = lowered.findIndex(segment => NEVER_TOUCHED.includes(segment));
+  if (always !== -1) return segments[always];
+
+  const directories = namesADirectory ? lowered : lowered.slice(0, -1);
+  const at = directories.findIndex(segment => SKIP_DIRS_LOWER.includes(segment));
+  return at === -1 ? null : segments[at];
+}
+
+/**
+ * Whether one directory name is one the walk skips. Used by `listFiles`, which
+ * has the name on its own and needs the same case rules.
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function isSkippedDirName(name) {
+  return SKIP_DIRS_LOWER.includes(String(name).toLowerCase());
+}
+
 /**
  * @param {string} relativePath
  * @returns {boolean}
@@ -144,7 +275,11 @@ export function isSecretPath(relativePath) {
 
 /**
  * Resolve a model-supplied path against the root, refusing anything that
- * escapes it.
+ * escapes it **lexically**.
+ *
+ * This is the cheap half of the check and not the whole of it: `../` and an
+ * absolute path are caught here, a symbolic link is not. Every caller that
+ * then touches the filesystem goes through `resolveInsideReal` as well.
  *
  * @param {string} root
  * @param {string} candidate
@@ -159,6 +294,54 @@ export function resolveInside(root, candidate) {
   return target;
 }
 
+/**
+ * The other half: refuse a path that leaves the repository through a link.
+ *
+ * `resolveInside` compares strings, and a string comparison cannot see that
+ * `shared/` is a link to somewhere else entirely. A repository with such a
+ * link, which is ordinary in a monorepo or a shared-asset layout, would
+ * otherwise let a write land outside the tree with every lexical check
+ * passing. So every component from the root down that already exists is
+ * checked with `lstat` and refused by name if it is a link, the target
+ * included; components that do not exist yet are safe, because `mkdir` creates
+ * real directories and never links. The deepest component that does exist is
+ * then compared against the root's own real path, which also covers a root
+ * reached through a link itself (every temp directory on macOS is one).
+ *
+ * @param {string} root
+ * @param {string} candidate
+ * @returns {Promise<{absolute: string, relative: string}>}
+ */
+export async function resolveInsideReal(root, candidate) {
+  const base = path.resolve(root);
+  const target = resolveInside(base, candidate);
+  const realRoot = await realpath(base);
+
+  const parts = path.relative(base, target).split(path.sep).filter(Boolean);
+  let walked = base;
+  for (const part of parts) {
+    const next = path.join(walked, part);
+    let info;
+    try {
+      info = await lstat(next);
+    } catch {
+      // This component does not exist yet, so nothing below it does either.
+      break;
+    }
+    if (info.isSymbolicLink()) {
+      const named = path.relative(base, next).split(path.sep).join('/');
+      throw new Error(`${candidate} goes through ${named}, which is a symbolic link, and a link can point out of the repository`);
+    }
+    walked = next;
+  }
+
+  const real = await realpath(walked);
+  if (real !== realRoot && !real.startsWith(realRoot + path.sep)) {
+    throw new Error(`${candidate} resolves outside the repository`);
+  }
+  return { absolute: target, relative: path.relative(base, target).split(path.sep).join('/') };
+}
+
 /**
  * @param {string} root
  * @param {Object} [opts]
@@ -180,7 +363,7 @@ export async function listFiles(root, { limit = 20000 } = {}) {
       if (entry.isSymbolicLink()) continue;
       const absolute = path.join(dir, entry.name);
       if (entry.isDirectory()) {
-        if (SKIP_DIRS.includes(entry.name)) continue;
+        if (isSkippedDirName(entry.name) || NEVER_TOUCHED.includes(entry.name.toLowerCase())) continue;
         await walk(absolute);
         continue;
       }
@@ -200,6 +383,9 @@ export async function listFiles(root, { limit = 20000 } = {}) {
  */
 export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
   let cachedFiles = null;
+  const canWrite = tools.some(tool => tool.name === 'write_file');
+  /** The distinct paths this run has written, which is what the cap counts. */
+  const written = new Set();
 
   async function files() {
     if (!cachedFiles) cachedFiles = await listFiles(root);
@@ -209,6 +395,11 @@ export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
   return {
     tools,
 
+    /** Repository-relative paths this tool set has written, in write order. */
+    get written() {
+      return [...written];
+    },
+
     /**
      * @param {Object} toolUse
      */
@@ -216,6 +407,25 @@ export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
       const input = toolUse.input || {};
       try {
         if (toolUse.name === 'read_file') return { result: ok(toolUse.id, await doRead(root, input)) };
+        if (toolUse.name === 'write_file' && canWrite) {
+          // A refusal comes back as an `is_error` result naming the rule,
+          // never as a thrown error: the model has to be able to read why and
+          // try a legal write instead, and a thrown error would end the run.
+          const planned = await planWrite(root, input, written);
+          if (planned.refusal) return { result: ok(toolUse.id, planned.refusal, true) };
+          await doWrite(planned.absolute, input.content);
+          written.add(planned.relative);
+          const left = MAX_WRITES_PER_RUN - written.size;
+          return { result: ok(toolUse.id, `Wrote ${planned.relative} (${planned.bytes} bytes). ${left} more file(s) may be written in this run.`) };
+        }
+        if (toolUse.name === 'edit_file' && canWrite) {
+          const planned = await planEdit(root, input, written);
+          if (planned.refusal) return { result: ok(toolUse.id, planned.refusal, true) };
+          await doWrite(planned.absolute, planned.content);
+          written.add(planned.relative);
+          const left = MAX_WRITES_PER_RUN - written.size;
+          return { result: ok(toolUse.id, `Edited ${planned.relative}: ${planned.replaced} occurrence(s) replaced, now ${planned.bytes} bytes. ${left} more file(s) may be written in this run.`) };
+        }
         if (toolUse.name === 'glob') {
           const matcher = globToRegExp(input.pattern);
           const matched = (await files()).filter(file => matcher.test(file)).slice(0, MAX_GLOB_RESULTS);
@@ -231,11 +441,18 @@ export function createRepoTools({ root, tools = PROFILE_TOOLS }) {
 }
 
 async function doRead(root, input) {
-  const relative = String(input.path || '');
-  if (isSecretPath(relative)) {
-    return `Refused: ${relative} is a credential file and is never read. Note in warnings that credentials are checked into the repository, without quoting anything.`;
+  const asked = String(input.path || '');
+  if (isSecretPath(asked)) {
+    return `Refused: ${asked} is a credential file and is never read. Note in warnings that credentials are checked into the repository, without quoting anything.`;
+  }
+  // The same real-path check the write path makes, for the same reason: a
+  // symlinked directory would otherwise let a read leave the repository, and
+  // `/etc/passwd` read through `shared/` is still a read of `/etc/passwd`.
+  const { absolute, relative } = await resolveInsideReal(root, asked);
+  const skipped = skippedDirIn(relative);
+  if (skipped) {
+    return `Refused: ${relative} is under ${skipped}, which is not part of the game's source.`;
   }
-  const absolute = resolveInside(root, relative);
   const info = await stat(absolute);
   if (!info.isFile()) throw new Error(`${relative} is not a file`);
   const text = await readFile(absolute, 'utf8');
@@ -253,6 +470,131 @@ async function doRead(root, input) {
   return slice.length > MAX_READ_BYTES ? `${slice.slice(0, MAX_READ_BYTES)}\n... [truncated]` : slice;
 }
 
+/**
+ * Every rule a `write_file` has to pass, and the sentence that names the one
+ * it failed. The rules are checked in the order that is cheapest to answer
+ * and hardest to argue with: where the file is, then what is in it, then how
+ * many files this run has already touched.
+ *
+ * The path is canonicalised before any rule is applied and before it counts
+ * against the twenty file cap, so `./src/a.gd`, `src/./a.gd` and
+ * `src/ui/../a.gd` are one file rather than three.
+ *
+ * @param {string} root
+ * @param {Object} input the model's tool input
+ * @param {Set<string>} written the distinct paths written so far
+ * @returns {Promise<{relative: string, absolute: string, bytes: number}|{refusal: string}>}
+ */
+export async function planWrite(root, input, written = new Set()) {
+  const asked = String((input && input.path) || '').trim();
+  if (!asked) return { refusal: 'Refused: write_file needs a path relative to the repository root.' };
+
+  let absolute;
+  let relative;
+  try {
+    // The real check rather than the lexical one: a link is how a write leaves
+    // a tree that every string comparison says it is inside.
+    ({ absolute, relative } = await resolveInsideReal(root, asked));
+  } catch (error) {
+    return { refusal: `Refused: ${String(error && error.message ? error.message : error)}. A fix only ever writes inside the repository itself.` };
+  }
+  if (!relative) return { refusal: 'Refused: that is the repository root, not a file in it.' };
+
+  if (isSecretPath(relative)) {
+    return { refusal: `Refused: ${relative} is a credential file, and those are never read or written.` };
+  }
+  const skipped = skippedDirIn(relative);
+  if (skipped) {
+    return { refusal: `Refused: ${relative} is under ${skipped}, which is generated, vendored or this tool's own bookkeeping, and is never written.` };
+  }
+
+  const content = input && input.content;
+  if (typeof content !== 'string') {
+    return { refusal: 'Refused: content has to be a string. Send the whole file as text.' };
+  }
+  if (content.includes(NUL)) {
+    return { refusal: 'Refused: content holds a NUL byte, so that is not a text file. Only text files are written.' };
+  }
+  const bytes = Buffer.byteLength(content, 'utf8');
+  if (bytes > MAX_WRITE_BYTES) {
+    return { refusal: `Refused: ${relative} would be ${bytes} bytes and one write may be at most ${MAX_WRITE_BYTES}. Change less of it, or change a smaller file.` };
+  }
+  if (!written.has(relative) && written.size >= MAX_WRITES_PER_RUN) {
+    return { refusal: `Refused: this run has already written ${written.size} files and may write at most ${MAX_WRITES_PER_RUN}. Finish with the files you have already changed.` };
+  }
+  return { relative, absolute, bytes };
+}
+
+/**
+ * Temp file then rename, in the target's own directory, so an interrupted
+ * write leaves the developer's file exactly as it was rather than half of a
+ * new one. Rename inside one directory is atomic everywhere this CLI runs.
+ *
+ * @param {string} absolute
+ * @param {string} content
+ */
+/**
+ * Everything `planWrite` checks about the path, then the replacement itself:
+ * the file has to exist and be text, `old_text` has to be found exactly once
+ * unless `replace_all`, and the result has to fit the same byte ceiling a
+ * whole write does. Refusals name the count found, because "not found" and
+ * "found three times" call for different next moves.
+ *
+ * @param {string} root
+ * @param {Object} input
+ * @param {Set<string>} written
+ * @returns {Promise<{refusal: string}|{relative: string, absolute: string, content: string, bytes: number, replaced: number}>}
+ */
+export async function planEdit(root, input, written = new Set()) {
+  const oldText = input && input.old_text;
+  const newText = input && input.new_text;
+  if (typeof oldText !== 'string' || oldText.length === 0) {
+    return { refusal: 'Refused: edit_file needs old_text, the exact passage to replace, copied verbatim from read_file.' };
+  }
+  if (typeof newText !== 'string') return { refusal: 'Refused: new_text has to be a string (it may be empty to delete the passage).' };
+  // The path rules are the write rules; the placeholder content only has to be
+  // a string so the shared checks run.
+  const planned = await planWrite(root, { path: input && input.path, content: '' }, written);
+  if (planned.refusal) return { refusal: planned.refusal.replace('write_file', 'edit_file') };
+
+  let current;
+  try {
+    current = await readFile(planned.absolute, 'utf8');
+  } catch {
+    return { refusal: `Refused: ${planned.relative} does not exist yet. Use write_file to create a new file.` };
+  }
+  if (current.includes(NUL)) return { refusal: `Refused: ${planned.relative} is not a text file.` };
+
+  const occurrences = current.split(oldText).length - 1;
+  if (occurrences === 0) {
+    return { refusal: `Refused: old_text was not found in ${planned.relative}. Read the file again and copy the passage exactly, whitespace included.` };
+  }
+  if (occurrences > 1 && !(input && input.replace_all)) {
+    return { refusal: `Refused: old_text appears ${occurrences} times in ${planned.relative}. Include more surrounding lines so it is unique, or set replace_all.` };
+  }
+  const content = input && input.replace_all ? current.split(oldText).join(newText) : current.replace(oldText, () => newText);
+  if (content.includes(NUL)) return { refusal: 'Refused: new_text holds a NUL byte, so that is not text.' };
+  const bytes = Buffer.byteLength(content, 'utf8');
+  if (bytes > MAX_WRITE_BYTES) {
+    return { refusal: `Refused: ${planned.relative} would be ${bytes} bytes and one write may be at most ${MAX_WRITE_BYTES}.` };
+  }
+  return { relative: planned.relative, absolute: planned.absolute, content, bytes, replaced: input && input.replace_all ? occurrences : 1 };
+}
+
+async function doWrite(absolute, content) {
+  await mkdir(path.dirname(absolute), { recursive: true });
+  const tmp = `${absolute}.${process.pid}.${randomUUID()}.tmp`;
+  await writeFile(tmp, content, 'utf8');
+  try {
+    await rename(tmp, absolute);
+  } catch (error) {
+    // A failed rename would otherwise leave the half-named temp file in the
+    // developer's source tree, where the next glob would find it.
+    await unlink(tmp).catch(() => {});
+    throw error;
+  }
+}
+
 async function doGrep(root, all, input) {
   const regex = new RegExp(String(input.pattern), 'i');
   const matcher = input.glob ? globToRegExp(input.glob) : null;
@@ -276,11 +618,30 @@ async function doGrep(root, all, input) {
       if (regex.test(lines[i])) hits.push(`${relative}:${i + 1}: ${lines[i].trim().slice(0, 300)}`);
     }
   }
-  return hits.length > 0 ? hits.join('\n') : '(no matches)';
+  if (hits.length === 0) return '(no matches)';
+  const capped = hits.length >= MAX_GREP_RESULTS;
+  return capped
+    ? `${hits.join('\n')}\n(stopped at ${MAX_GREP_RESULTS} matches; narrow the pattern or add a glob)`
+    : hits.join('\n');
 }
 
 function ok(id, text, isError = false) {
   return { type: 'tool_result', tool_use_id: id, content: [{ type: 'text', text }], ...(isError ? { is_error: true } : {}) };
 }
 
-export default { createRepoTools, PROFILE_TOOLS, READ_ONLY_TOOLS, globToRegExp, listFiles, resolveInside, isSecretPath };
+export default {
+  createRepoTools,
+  PROFILE_TOOLS,
+  READ_ONLY_TOOLS,
+  WRITE_TOOLS,
+  EDIT_FILE_TOOL,
+  planEdit,
+  globToRegExp,
+  listFiles,
+  planWrite,
+  resolveInside,
+  resolveInsideReal,
+  isSecretPath,
+  isSkippedDirName,
+  skippedDirIn
+};