ravensight-playtest 0.1.0 → 0.2.0

package/src/run/git.js

@@ -0,0 +1,331 @@
+import { execFile } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { skippedDirIn } from './repoTools.js';
+
+/**
+ * The only module in this CLI that runs git, and the only one that ever will.
+ *
+ * `fix` is the one command that changes the developer's working copy, so the
+ * rules about how it does that are worth having in one file where they can be
+ * read at a glance:
+ *
+ * - **It never publishes anything.** There is no `commit`, no `push`, no tag,
+ *   no `gh`. The command ends by printing the pull request command for the
+ *   developer to run when they have read the diff. A tool that edits your
+ *   source and pushes the result is a tool you cannot leave running.
+ * - **It never rewrites history.** No `reset`, no `rebase`, no `checkout --`
+ *   of a path. The only mutation is creating and checking out one new branch,
+ *   and that is refused if the branch already exists, so an earlier attempt's
+ *   work is never landed on.
+ * - **It refuses a dirty tree** unless the developer says otherwise, because
+ *   the changeset is computed as a diff against the recorded HEAD and a tree
+ *   that was already dirty makes that diff a mixture of two people's work.
+ * - **Everything goes through `execFile`**, never a shell, and every value
+ *   the developer or the server supplied is an argument rather than a word in
+ *   a command line. A branch name is the obvious injection vector here.
+ *
+ * Every call is scoped by `-C <root>`, so the repository is the one the rest
+ * of the command is working in rather than whatever directory the process
+ * happens to be in.
+ */
+
+const run = promisify(execFile);
+
+/** Branch names git itself refuses, checked before git is asked. */
+const BAD_BRANCH = /(^-|^\.|\.\.|[~^:?*[\\ ]|@\{|\.lock$|\/$|^\/|\/\/)/;
+
+/**
+ * Where a fix lands by default: one branch per attempt, named after the
+ * finding, with six hex characters so two attempts at the same finding do not
+ * collide (and so the second one is not silently refused).
+ *
+ * @param {string} label the finding's label, e.g. F002
+ * @param {() => string} [suffix] test seam
+ * @returns {string}
+ */
+export function fixBranchName(label, suffix = () => randomBytes(3).toString('hex')) {
+  const slug = String(label || 'finding').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'finding';
+  return `ravensight/fix-${slug}-${suffix()}`;
+}
+
+/**
+ * @param {string} name
+ * @returns {string|null} why the name is not usable, or null
+ */
+export function branchNameRefusal(name) {
+  const value = String(name || '');
+  if (!value) return 'A branch name cannot be empty.';
+  if (BAD_BRANCH.test(value)) return `"${value}" is not a usable branch name.`;
+  return null;
+}
+
+/**
+ * A git surface bound to one repository.
+ *
+ * @param {Object} options
+ * @param {string} options.root the repository working directory
+ * @param {Function} [options.exec] test seam, shaped like promisified execFile
+ * @returns {Object}
+ */
+export function createGit({ root, exec = run }) {
+  /**
+   * @param {string[]} args
+   * @returns {Promise<{ok: boolean, stdout: string, stderr: string, code: number|null}>}
+   */
+  async function git(args) {
+    try {
+      const answer = await exec('git', ['-C', root, ...args], { encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+      return { ok: true, stdout: String(answer.stdout || ''), stderr: String(answer.stderr || ''), code: 0 };
+    } catch (error) {
+      return {
+        ok: false,
+        stdout: String((error && error.stdout) || ''),
+        stderr: String((error && error.stderr) || (error && error.message) || ''),
+        // ENOENT (no git on the PATH) has no exit code at all, which is how
+        // "git is missing" is told apart from "git said no".
+        code: typeof (error && error.code) === 'number' ? error.code : null,
+        missing: error && error.code === 'ENOENT'
+      };
+    }
+  }
+
+  return {
+    root,
+    git,
+
+    /** Whether a git binary exists at all. */
+    async available() {
+      const answer = await git(['--version']);
+      return answer.ok;
+    },
+
+    /** Whether `root` is inside a work tree. */
+    async isRepo() {
+      const answer = await git(['rev-parse', '--is-inside-work-tree']);
+      return answer.ok && answer.stdout.trim() === 'true';
+    },
+
+    /** The commit `fix` records as the base of its changeset. */
+    async head() {
+      const answer = await git(['rev-parse', 'HEAD']);
+      return answer.ok ? answer.stdout.trim() : null;
+    },
+
+    /** The branch checked out now, or null on a detached HEAD. */
+    async currentBranch() {
+      const answer = await git(['rev-parse', '--abbrev-ref', 'HEAD']);
+      const name = answer.ok ? answer.stdout.trim() : '';
+      return name && name !== 'HEAD' ? name : null;
+    },
+
+    /**
+     * The uncommitted paths that matter, tracked or not.
+     *
+     * Untracked files count: an edit the model makes to a file the developer
+     * had not committed yet is still their work being mixed into the
+     * changeset. Generated directories do not, and `.ravensight` least of all:
+     * a repository that has not gitignored `.ravensight/jobs/` yet would
+     * otherwise be permanently "dirty" because of this CLI's own journals, and
+     * every fix would be refused for a reason that has nothing to do with the
+     * developer's work.
+     *
+     * @param {number} [limit]
+     * @returns {Promise<Array<string>>}
+     */
+    async dirtyPaths(limit = Number.POSITIVE_INFINITY) {
+      const answer = await git(['status', '--porcelain', '--untracked-files=normal']);
+      if (!answer.ok) return [];
+      return answer.stdout.split('\n')
+        .map(line => line.slice(3).trim())
+        // A rename is `old -> new`; the new path is the one that exists.
+        .map(entry => (entry.includes(' -> ') ? entry.split(' -> ').pop().trim() : entry))
+        .filter(entry => entry && !skippedDirIn(entry))
+        .slice(0, limit);
+    },
+
+    /** Whether the tree has uncommitted work worth refusing over. */
+    async isDirty() {
+      return (await this.dirtyPaths(1)).length > 0;
+    },
+
+    /** @param {string} name */
+    async branchExists(name) {
+      const answer = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${name}`]);
+      return answer.ok && answer.stdout.trim().length > 0;
+    },
+
+    /**
+     * Create the branch and check it out. `switch -c` rather than
+     * `checkout -b`: it only ever changes branches, where `checkout` also
+     * takes paths and would discard a file if a name were ever mistaken for
+     * one.
+     *
+     * @param {string} name
+     * @returns {Promise<{ok: boolean, reason?: string}>}
+     */
+    async createBranch(name) {
+      const answer = await git(['switch', '-c', name]);
+      return answer.ok ? { ok: true } : { ok: false, reason: firstLine(answer.stderr) };
+    },
+
+    /**
+     * The changeset's file list.
+     *
+     * `git diff --numstat` against the working tree is the source, as the
+     * contract says. It sees changes to tracked files and nothing else, so
+     * files the fix created are counted separately: a new file is the most
+     * ordinary kind of fix there is, and a changeset that reported none of
+     * them would call a real edit "no change" and refund a fix that worked.
+     *
+     * Generated and vendored directories are left out, and `.ravensight`
+     * first among them: the run journal and the changeset are written inside
+     * the repository while the fix is running, and a repository without
+     * `.ravensight/jobs/` in its `.gitignore` would otherwise report the
+     * command's own bookkeeping as part of the change it made. Nothing a fix
+     * is allowed to write can be in one of these, since `write_file` refuses
+     * them by the same rule.
+     *
+     * @returns {Promise<Array<{path: string, additions: number, deletions: number}>>}
+     */
+    async diffStat() {
+      const out = [];
+      const tracked = await git(['diff', '--numstat']);
+      if (tracked.ok) {
+        for (const line of tracked.stdout.split('\n')) {
+          if (!line.trim()) continue;
+          const [additions, deletions, ...rest] = line.split('\t');
+          const file = rest.join('\t').trim();
+          if (!file || skippedDirIn(file)) continue;
+          out.push({
+            path: file,
+            // A binary file is `-\t-\t<path>` in numstat, which is zero lines
+            // rather than an unknown number of them.
+            additions: Number.parseInt(additions, 10) || 0,
+            deletions: Number.parseInt(deletions, 10) || 0
+          });
+        }
+      }
+      const untracked = await git(['ls-files', '--others', '--exclude-standard']);
+      if (untracked.ok) {
+        for (const line of untracked.stdout.split('\n')) {
+          const file = line.trim();
+          if (!file || skippedDirIn(file)) continue;
+          out.push({ path: file, additions: await countLines(path.join(root, file)), deletions: 0 });
+        }
+      }
+      return out.sort((a, b) => a.path.localeCompare(b.path));
+    },
+
+    /** Whether anything at all changed, which is what decides the refund. */
+    async hasChanges() {
+      return (await this.diffStat()).length > 0;
+    }
+  };
+}
+
+/**
+ * The checks `fix` runs before it edits anything, in the order that answers
+ * the developer soonest.
+ *
+ * Every refusal is one sentence, because it is the whole of what gets
+ * printed: a developer who is told "not a git repository" can act on it, and
+ * one who is shown a git error with a hint block cannot tell which half is
+ * the problem.
+ *
+ * `create` is false when the caller wants every refusal now and the one
+ * mutation later: `fix` checks all of this before it quotes a price, and
+ * creates the branch only once the developer has agreed to pay, so declining
+ * the price does not leave a branch behind.
+ *
+ * @param {Object} options
+ * @param {Object} options.git a `createGit` surface
+ * @param {string} options.branch the branch to create
+ * @param {boolean} [options.allowDirty]
+ * @param {boolean} [options.create] create and check out the branch now
+ * @returns {Promise<{ok: true, head: string, branch: string, from: string|null, dirty: boolean, created: boolean}|{ok: false, reason: string}>}
+ */
+export async function preflight({ git, branch, allowDirty = false, create = true }) {
+  if (!(await git.available())) {
+    return { ok: false, reason: 'This command needs git on the PATH, and there is none here.' };
+  }
+  if (!(await git.isRepo())) {
+    return { ok: false, reason: `${git.root} is not a git repository, and a fix has to be reviewable as a branch.` };
+  }
+  const named = branchNameRefusal(branch);
+  if (named) return { ok: false, reason: named };
+
+  const dirty = await git.isDirty();
+  if (!allowDirty && dirty) {
+    const paths = await git.dirtyPaths(5);
+    const listed = paths.length > 0 ? ` (${paths.join(', ')})` : '';
+    return { ok: false, reason: `The working tree has uncommitted changes${listed}. Commit or stash them, or pass --allow-dirty to mix them into this fix.` };
+  }
+  const head = await git.head();
+  if (!head) {
+    return { ok: false, reason: 'This repository has no commits yet, so there is nothing to branch from.' };
+  }
+  if (await git.branchExists(branch)) {
+    return { ok: false, reason: `The branch ${branch} already exists. Pass --branch <name> to use another one.` };
+  }
+
+  const from = await git.currentBranch();
+  if (!create) return { ok: true, head, branch, from, dirty, created: false };
+
+  const made = await startBranch({ git, branch });
+  if (!made.ok) return made;
+  return { ok: true, head, branch, from, dirty, created: true };
+}
+
+/**
+ * Create the branch and check it out, refusing one that already exists.
+ *
+ * Separate from `preflight` so a caller can put the refusals before a price
+ * prompt and this one mutation after it. The existence check is repeated here
+ * rather than trusted from earlier: it is the check that stops an earlier
+ * attempt's work being landed on.
+ *
+ * @param {{git: Object, branch: string}} options
+ * @returns {Promise<{ok: true, branch: string}|{ok: false, reason: string}>}
+ */
+export async function startBranch({ git, branch }) {
+  const named = branchNameRefusal(branch);
+  if (named) return { ok: false, reason: named };
+  if (await git.branchExists(branch)) {
+    return { ok: false, reason: `The branch ${branch} already exists. Pass --branch <name> to use another one.` };
+  }
+  const created = await git.createBranch(branch);
+  if (!created.ok) {
+    return { ok: false, reason: `The branch ${branch} could not be created: ${created.reason}` };
+  }
+  return { ok: true, branch };
+}
+
+/**
+ * Lines in a file the fix created. Read rather than counted with git, because
+ * git does not have a number for a file it has never seen.
+ *
+ * @param {string} absolute
+ * @returns {Promise<number>}
+ */
+async function countLines(absolute) {
+  try {
+    const info = await stat(absolute);
+    // A new file big enough to be worth guarding against is not something a
+    // fix writes; `write_file` caps one at 200 kB.
+    if (!info.isFile() || info.size > 4 * 1024 * 1024) return 0;
+    const text = await readFile(absolute, 'utf8');
+    if (text.length === 0) return 0;
+    return text.endsWith('\n') ? text.split('\n').length - 1 : text.split('\n').length;
+  } catch {
+    return 0;
+  }
+}
+
+function firstLine(text) {
+  return String(text || '').split('\n').map(line => line.trim()).find(Boolean) || 'git gave no reason';
+}
+
+export default { createGit, preflight, startBranch, fixBranchName, branchNameRefusal };

package/src/run/index.js

@@ -2,21 +2,23 @@
  * The runner's entry point, and the only module cli-core's CLI imports from
  * this directory.
  *
- * It lazy-imports exactly three names, so those three are the contract:
+ * It lazy-imports exactly four names, so those four are the contract:
  *
  * | Name | Called with | Answers |
  * |---|---|---|
  * | `runCommand(flags)` | commander's flags plus `flags.argv` (the run-specific options, which `src/run/args.js` parses) | an exit code |
  * | `profileCommand(flags)` | the same | an exit code |
+ * | `fixCommand(target, flags)` | the finding to fix, then the same flags | an exit code |
  * | `resumeJob({ api, gameId, jobId, job, runs, state, repoRoot, flags })` | cli-core's `resume` hand-off | an exit code |
  *
  * Everything else exported here is for tests and for cli-godot's driver: the
  * driver interface, the model client, and the pieces `resume` shares with
- * `run`. Nothing in cli-core should reach past the three names above.
+ * `run`. Nothing in cli-core should reach past the four names above.
  */
 
-export { runCommand, playJob, playPersonaRun } from '../commands/run.js';
+export { runCommand, playJob, playPersonaRun, deliver } from '../commands/run.js';
 export { profileCommand } from '../commands/profile.js';
+export { fixCommand } from '../commands/fix.js';
 export { resumeJob } from './resume.js';
 
 export { EXIT } from './exit.js';
@@ -26,6 +28,8 @@ export { createModelClient, callStep, callStepWithRetry, ModelUnavailableError,
 export { getDeps, setDeps, resetDeps } from './deps.js';
 export { runPersona } from './personaLoop.js';
 export { runGameProfile } from './profile.js';
+export { applyFix, planFix, summariseFix } from './fixLoop.js';
+export { createGit, preflight as gitPreflight } from './git.js';
 export { buildAggregate } from './aggregate.js';
 export { scanForSecrets, assertNoSecrets } from './secretScan.js';
 export { parseRunArgv, optionsFrom } from './args.js';

package/src/run/model.js

@@ -48,7 +48,13 @@ export const STEPS = Object.freeze({
   profileSynthesis: 'game_profile.synthesis',
   aggregateDedup: 'aggregate.dedup',
   aggregateSynthesis: 'aggregate.synthesis',
-  briefValidate: 'brief.validate'
+  briefValidate: 'brief.validate',
+  // The `fix` module's three. They are spendable only from a run whose module
+  // is `fix`, and `fix.apply` is the one step on this whole surface whose tool
+  // allowlist includes `write_file`.
+  fixPlan: 'fix.plan',
+  fixApply: 'fix.apply',
+  fixSummarize: 'fix.summarize'
 });
 
 /** Default retry budget for the answers that are worth retrying. */