@amenophis1er/foreman 0.1.6 → 0.1.8

package/src/deck.ts

@@ -759,6 +759,25 @@ async function artifactsFor(folder: string, runId: string, since: number | undef
   return out.slice(0, ARTIFACT_CAP);
 }
 
+/** Listed files per project tree. */
+const TREE_CAP = 2_000;
+
+/**
+ * The project's working tree as it stands: every file the deck would consider,
+ * minus `.foreman`, which is Foreman's own. No baseline, no diff — this is the
+ * view for a project between missions, where "what is in this folder" is the
+ * question and every run shares the answer.
+ */
+export async function projectTree(folder: string): Promise<{ files: DeckArtifact[]; truncated: boolean }> {
+  const { files, truncated } = await walk(folder, { skipWork: true, limit: TREE_CAP });
+  const out: DeckArtifact[] = [];
+  for (const f of files) {
+    if (f.rel === '.foreman' || f.rel.startsWith('.foreman/')) continue;
+    out.push({ path: f.rel, kind: artifactKind(f.rel), size: f.size, mtimeMs: f.mtimeMs });
+  }
+  return { files: out, truncated };
+}
+
 /**
  * Resolve an artifact path for serving, or null if it is not something the
  * deck may hand out. The jail is the realpath of `folder`: `..`, absolute
@@ -820,30 +839,37 @@ function sendJson(res: ServerResponse, code: number, body: unknown): void {
 }
 
 /**
- * `GET /runs/{id}/deck`, `GET /runs/{id}/artifact?path=<rel>` and
- * `GET /runs/{id}/preview/<rel>` (sandboxed render, see below). Returns
+ * `GET /runs/{id}/deck`, `GET /projects/{id}/tree`, `GET …/artifact?path=<rel>`
+ * and `GET …/preview/<rel>` (sandboxed render, see below). Returns
  * true when the URL was one of ours (whatever the outcome), false so the
  * caller's router falls through. `lookup` maps a run id to its folder; null
  * means unknown run, which is a 404 rather than an error.
  */
 export async function handleDeckRoute(
   req: IncomingMessage, res: ServerResponse, url: URL,
-  lookup: (runId: string) => Promise<{ folder: string } | null>,
+  lookup: (scope: 'runs' | 'projects', id: string) => Promise<{ folder: string } | null>,
 ): Promise<boolean> {
-  const m = url.pathname.match(/^\/runs\/([^/]+)\/(deck|artifact|preview)(?:\/(.*))?$/);
+  // The same jail and the same viewer serve two scopes: a run (its deck,
+  // relative to a baseline) and a project (its tree as it stands, no baseline).
+  const m = url.pathname.match(/^\/(runs|projects)\/([^/]+)\/(deck|tree|artifact|preview)(?:\/(.*))?$/);
   if (!m) return false;
-  const [, runId, what, previewRel] = m;
+  const [, scope, runId, what, previewRel] = m;
   if ((what === 'preview') !== (previewRel !== undefined)) return false;
+  if ((what === 'deck' && scope !== 'runs') || (what === 'tree' && scope !== 'projects')) return false;
   try {
     if (req.method !== 'GET') { sendJson(res, 405, { error: 'method not allowed' }); return true; }
     if (!RUN_ID_RE.test(runId)) { sendJson(res, 404, { error: 'not found' }); return true; }
-    const run = await lookup(runId);
+    const run = await lookup(scope as 'runs' | 'projects', runId);
     if (!run) { sendJson(res, 404, { error: 'not found' }); return true; }
 
     if (what === 'deck') {
       sendJson(res, 200, await deckFor(run.folder, runId));
       return true;
     }
+    if (what === 'tree') {
+      sendJson(res, 200, await projectTree(run.folder));
+      return true;
+    }
 
     if (what === 'preview') {
       // A rendered look at an HTML artifact. Files come out with their real

package/src/fleet-planner.ts

@@ -152,8 +152,9 @@ that project's planner; otherwise it comes to you.
 WHAT YOU CAN DO — through the tools, nothing else:
   - list_projects / project_detail / run_report: answer "how is X doing",
     "what needs me", "what happened to Y".
-  - create_project / link_project: a new folder under the projects root, or
-    an existing one, linked into the fleet.
+  - create_project / link_project: a new folder under the projects root, an
+    existing one, or a Git repository cloned under the root (link_project
+    with the URL), linked into the fleet.
   - open_planning: hand a request about an EXISTING codebase to that
     project's planner, which can read the folder. Use this whenever the right
     mission depends on what is already there. After you call it, that planner
@@ -280,8 +281,8 @@ export async function runFleetTurn(turn: FleetTurn): Promise<FleetResult> {
     tool('create_project', 'Create a new folder under the projects root and link it as a project. Use when the human wants to start something that has no home yet.',
       { name: z.string().describe('What to call it; becomes the folder name') },
       async ({ name }) => text(await safe(() => host.createProject(name)))),
-    tool('link_project', 'Link an existing folder as a project. The folder must already exist.',
-      { folder: z.string().describe('Absolute path, or ~/…') },
+    tool('link_project', 'Link an existing folder as a project — or clone a Git repository (a GitHub URL, a git@ URL, or owner/repo) under the projects root and link it. Cloning runs as the human with their own git credentials and can take a minute; wait for the result.',
+      { folder: z.string().describe('Absolute path, ~/…, or a Git repository URL') },
       async ({ folder }) => text(await safe(() => host.linkProject(folder)))),
     tool('open_planning', 'Hand the request to that project\'s planner, which can read the folder and will propose a mission. After this, the planner owns the conversation: tell the human in one line and stop.',
       {

package/src/gitwork.test.ts

@@ -0,0 +1,95 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { closeMissionBranch, ensureMissionBranch, gitInfo, missionBranchName, startMissionBranch } from './gitwork.js';
+
+const sh = (cwd: string, ...args: string[]) => execFileSync('git', args, { cwd, stdio: 'pipe', env: { ...process.env, GIT_CONFIG_GLOBAL: '/dev/null' } }).toString();
+
+async function repo(): Promise<string> {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'gitwork-'));
+  sh(dir, 'init', '-q', '-b', 'main');
+  sh(dir, 'config', 'user.email', 'me@example.com');
+  sh(dir, 'config', 'user.name', 'Me');
+  await writeFile(path.join(dir, 'README.md'), 'hello\n');
+  sh(dir, 'add', '-A'); sh(dir, 'commit', '-q', '-m', 'init');
+  return dir;
+}
+
+test('missionBranchName: readable, bounded, unique per run', () => {
+  assert.equal(missionBranchName('Build Tick, a vanilla Pomodoro timer\nmore', '1788713434983-226123af'), 'foreman/build-tick-a-vanilla-pomodoro-timer-23af');
+  assert.match(missionBranchName('   \n!!!', 'run-xyz9'), /^foreman\/mission-xyz9$/);
+  assert.ok(missionBranchName('a '.repeat(80), 'r1').length < 60);
+});
+
+test('gitInfo: a plain folder is not a repo; a repo reports branch, head, dirty, remote', async () => {
+  const plain = await mkdtemp(path.join(os.tmpdir(), 'gitwork-plain-'));
+  assert.deepEqual(await gitInfo(plain), { repo: false });
+  const dir = await repo();
+  const info = await gitInfo(dir);
+  assert.equal(info.repo, true); assert.equal(info.branch, 'main'); assert.equal(info.dirty, false); assert.ok(info.head);
+  sh(dir, 'remote', 'add', 'origin', 'git@github.com:acme/widget.git');
+  await writeFile(path.join(dir, 'x.txt'), 'x');
+  const again = await gitInfo(dir);
+  assert.equal(again.dirty, true); assert.equal(again.remote, 'git@github.com:acme/widget.git');
+});
+
+test('a mission gets its own branch from the current one, and closing commits the work on it', async () => {
+  const dir = await repo();
+  const g = await startMissionBranch(dir, 'Add a footer to the page', 'run-1234abcd');
+  assert.ok(!('error' in g), JSON.stringify(g));
+  if ('error' in g) return;
+  assert.equal(g.branch, 'foreman/add-a-footer-to-the-page-abcd');
+  assert.equal(g.base, 'main');
+  assert.equal(sh(dir, 'rev-parse', '--abbrev-ref', 'HEAD').trim(), g.branch);
+
+  // Nothing to commit yet: no commit, zero commits ahead.
+  const idle = await closeMissionBranch(dir, g, 'foreman: nothing');
+  assert.equal(idle.committed, false); assert.equal(idle.commits, 0); assert.equal(idle.error, undefined);
+
+  await writeFile(path.join(dir, 'footer.html'), '<footer/>');
+  const closed = await closeMissionBranch(dir, g, 'foreman: Add a footer');
+  assert.equal(closed.committed, true); assert.equal(closed.commits, 1); assert.ok(closed.commit);
+  assert.equal(sh(dir, 'status', '--porcelain').trim(), '');
+  assert.match(sh(dir, 'log', '-1', '--format=%s'), /^foreman: Add a footer/);
+  // main is untouched.
+  assert.equal(sh(dir, 'rev-list', '--count', 'main').trim(), '1');
+});
+
+test('ensureMissionBranch goes back to the branch for a resume, and says why when it cannot', async () => {
+  const dir = await repo();
+  const g = await startMissionBranch(dir, 'Thing', 'run-1');
+  if ('error' in g) throw new Error(g.error);
+  sh(dir, 'checkout', '-q', 'main');
+  assert.equal(await ensureMissionBranch(dir, g.branch), null);
+  assert.equal(sh(dir, 'rev-parse', '--abbrev-ref', 'HEAD').trim(), g.branch);
+  assert.match((await ensureMissionBranch(dir, 'foreman/does-not-exist')) ?? '', /checkout/);
+});
+
+test('startMissionBranch on a plain folder says so instead of throwing', async () => {
+  const plain = await mkdtemp(path.join(os.tmpdir(), 'gitwork-plain2-'));
+  assert.deepEqual(await startMissionBranch(plain, 'x', 'r'), { error: 'not a git repository' });
+});
+
+test('remoteWebUrl and compareUrl: the three hosts people use, and a plain page elsewhere', async () => {
+  const { remoteWebUrl, compareUrl } = await import('./gitwork.js');
+  assert.deepEqual(remoteWebUrl('git@github.com:acme/widget.git'), { host: 'github.com', path: 'acme/widget', web: 'https://github.com/acme/widget' });
+  assert.deepEqual(remoteWebUrl('https://gitlab.com/group/sub/widget.git'), { host: 'gitlab.com', path: 'group/sub/widget', web: 'https://gitlab.com/group/sub/widget' });
+  assert.equal(remoteWebUrl(undefined), null);
+  assert.equal(compareUrl('git@github.com:acme/widget.git', 'main', 'foreman/x-1'), 'https://github.com/acme/widget/compare/main...foreman%2Fx-1?expand=1');
+  assert.match(compareUrl('https://gitlab.com/g/w.git', 'main', 'foreman/x') ?? '', /merge_requests\/new\?merge_request%5Bsource_branch%5D=foreman%2Fx/);
+  assert.match(compareUrl('git@bitbucket.org:t/w.git', 'main', 'foreman/x') ?? '', /pull-requests\/new\?source=foreman%2Fx&dest=main/);
+  assert.equal(compareUrl('https://git.example.com/a/b', 'main', 'x'), 'https://git.example.com/a/b');
+});
+
+test('prDraft: the run title, the brief, the boxes as the mission left them, and a footer', async () => {
+  const { prDraft } = await import('./gitwork.js');
+  const d = prDraft({ title: 'Add a footer', mission: 'Add a footer to the page.\nKeep it small.', costUsd: 0.42, costBasis: 'priced', git: { branch: 'foreman/add-a-footer-ab12', base: 'main', baseHead: null } },
+    '# Mission\n- [x] footer.html exists\n- [ ] linked from index\n');
+  assert.equal(d.title, 'Add a footer');
+  assert.match(d.body, /## Mission\n\nAdd a footer to the page\.\nKeep it small\./);
+  assert.match(d.body, /## Done when\n\n- \[x\] footer\.html exists\n- \[ \] linked from index/);
+  assert.match(d.body, /branch `foreman\/add-a-footer-ab12` from `main` · spend \$0\.42/);
+});

package/src/gitwork.ts

@@ -0,0 +1,239 @@
+/**
+ * Git around a mission: which branch a folder is on, a branch of its own for
+ * each mission, and the commit that closes one.
+ *
+ * A mission is a unit of work; in a repository, a branch makes it one in
+ * git too — isolation, a diff that is exactly the mission, an easy revert,
+ * a pull request if there is a remote. Foreman creates the branch and
+ * commits on it. It never merges, and it pushes only when the human presses
+ * the button that says so — once, for that branch, to open the pull request.
+ */
+import { execFile } from 'node:child_process';
+
+export interface GitInfo {
+  repo: boolean;
+  /** Current branch; a short sha when detached. */
+  branch?: string;
+  /** Uncommitted changes, tracked or untracked. */
+  dirty?: boolean;
+  head?: string | null;
+  /** `origin`'s URL when there is one, so the UI can say "has a remote". */
+  remote?: string;
+}
+
+/** Recorded on a run that got a branch of its own. */
+export interface MissionGit {
+  branch: string;
+  /** Where it was made from: the branch (or short sha) that was checked out. */
+  base: string;
+  baseHead: string | null;
+  /** Commits on the branch since `baseHead`, updated when the mission closes. */
+  commits?: number;
+  /** The closing commit, when the mission's work was committed. */
+  commit?: string;
+}
+
+function git(args: string[], cwd: string, timeoutMs = 15_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('git', args, {
+      cwd, timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024, encoding: 'utf8',
+      env: { ...process.env, GIT_PAGER: 'cat', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' },
+    }, (err, stdout, stderr) => {
+      if (err) reject(new Error(`git ${args[0]}: ${(stderr || err.message).trim()}`));
+      else resolve(String(stdout));
+    });
+  });
+}
+
+/** What git says about a folder; `{ repo: false }` for anything that is not a work tree. Never throws. */
+export async function gitInfo(folder: string): Promise<GitInfo> {
+  try {
+    const inside = (await git(['rev-parse', '--is-inside-work-tree'], folder)).trim();
+    if (inside !== 'true') return { repo: false };
+  } catch {
+    return { repo: false };
+  }
+  const info: GitInfo = { repo: true };
+  try {
+    const ref = (await git(['rev-parse', '--abbrev-ref', 'HEAD'], folder)).trim();
+    info.branch = ref === 'HEAD' ? (await git(['rev-parse', '--short', 'HEAD'], folder)).trim() : ref;
+  } catch {
+    // An empty repository: HEAD names a branch with no commits yet.
+    try { info.branch = (await git(['symbolic-ref', '--short', 'HEAD'], folder)).trim(); } catch { /* leave unset */ }
+  }
+  try { info.head = (await git(['rev-parse', '--verify', 'HEAD'], folder)).trim() || null; } catch { info.head = null; }
+  try { info.dirty = (await git(['status', '--porcelain', '--untracked-files=normal'], folder)).trim().length > 0; } catch { /* unknown */ }
+  try { info.remote = (await git(['remote', 'get-url', 'origin'], folder)).trim() || undefined; } catch { /* no remote */ }
+  return info;
+}
+
+/** `foreman/<first words of the brief>-<id tail>`: readable in `git branch`, unique per run. */
+export function missionBranchName(mission: string, runId: string): string {
+  const first = mission.split('\n').find((l) => l.trim())?.trim() ?? 'mission';
+  const slug = first.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').split('-').filter(Boolean).slice(0, 6).join('-').slice(0, 40).replace(/-+$/, '') || 'mission';
+  const tail = runId.replace(/[^a-z0-9]/gi, '').slice(-4).toLowerCase();
+  return `foreman/${slug}-${tail}`;
+}
+
+/**
+ * A branch of the mission's own, made from what is checked out now.
+ * Uncommitted changes come along, as `checkout -b` always does. Resolves to
+ * the record for the run, or to one sentence on why it could not.
+ */
+export async function startMissionBranch(folder: string, mission: string, runId: string): Promise<MissionGit | { error: string }> {
+  const info = await gitInfo(folder);
+  if (!info.repo) return { error: 'not a git repository' };
+  const branch = missionBranchName(mission, runId);
+  try {
+    await git(['checkout', '-b', branch], folder);
+  } catch (err) {
+    return { error: err instanceof Error ? err.message : String(err) };
+  }
+  return { branch, base: info.branch ?? 'HEAD', baseHead: info.head ?? null };
+}
+
+/**
+ * Back on the mission's branch for a resume. Returns null when already or
+ * now there, else why not — a dirty tree that would be clobbered, typically.
+ */
+export async function ensureMissionBranch(folder: string, branch: string): Promise<string | null> {
+  const info = await gitInfo(folder);
+  if (!info.repo) return 'the folder is no longer a git repository';
+  if (info.branch === branch) return null;
+  try {
+    await git(['checkout', branch], folder);
+    return null;
+  } catch (err) {
+    return err instanceof Error ? err.message : String(err);
+  }
+}
+
+/**
+ * Commits whatever the mission left uncommitted, on its branch, as the user
+ * (their git config), falling back to a Foreman identity only when the
+ * repository has none. Then counts the branch's commits since its base.
+ */
+export async function closeMissionBranch(folder: string, g: MissionGit, message: string): Promise<MissionGit & { committed: boolean; error?: string }> {
+  const out: MissionGit & { committed: boolean; error?: string } = { ...g, committed: false };
+  try {
+    const info = await gitInfo(folder);
+    if (!info.repo) return { ...out, error: 'not a git repository' };
+    if (info.branch !== g.branch) return { ...out, error: `the folder is on ${info.branch ?? 'another branch'}, not ${g.branch}; nothing committed` };
+    if (info.dirty) {
+      await git(['add', '-A', '--', '.'], folder);
+      const identity = ['-c', 'user.name=Foreman', '-c', 'user.email=foreman@localhost'];
+      const hasName = await git(['config', 'user.name'], folder).then((v) => v.trim().length > 0).catch(() => false);
+      await git([...(hasName ? [] : identity), 'commit', '-q', '-m', message], folder);
+      out.commit = (await git(['rev-parse', '--short', 'HEAD'], folder)).trim();
+      out.committed = true;
+    }
+    if (g.baseHead) {
+      out.commits = Number((await git(['rev-list', '--count', `${g.baseHead}..HEAD`], folder)).trim()) || 0;
+    } else {
+      out.commits = Number((await git(['rev-list', '--count', 'HEAD'], folder)).trim()) || 0;
+    }
+  } catch (err) {
+    out.error = err instanceof Error ? err.message : String(err);
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The pull request: the one outward-facing act, and only ever on a button
+// ---------------------------------------------------------------------------
+
+/** `git@github.com:o/r.git` or `https://host/o/r(.git)` → the repository's web page. Null for anything else. */
+export function remoteWebUrl(remote: string | undefined): { host: string; web: string; path: string } | null {
+  if (!remote) return null;
+  let m = /^git@([^:]+):(.+?)(?:\.git)?\/?$/.exec(remote.trim());
+  if (m) return { host: m[1].toLowerCase(), path: m[2], web: `https://${m[1]}/${m[2]}` };
+  m = /^ssh:\/\/(?:[^@/]+@)?([^/:]+)(?::\d+)?\/(.+?)(?:\.git)?\/?$/.exec(remote.trim());
+  if (m) return { host: m[1].toLowerCase(), path: m[2], web: `https://${m[1]}/${m[2]}` };
+  m = /^https?:\/\/(?:[^@/]+@)?([^/]+)\/(.+?)(?:\.git)?\/?$/.exec(remote.trim());
+  if (m) return { host: m[1].toLowerCase(), path: m[2], web: `https://${m[1]}/${m[2]}` };
+  return null;
+}
+
+/** Where a human finishes the pull request in a browser when `gh` is not around: GitHub, GitLab and Bitbucket forms; null elsewhere. */
+export function compareUrl(remote: string | undefined, base: string, branch: string): string | null {
+  const r = remoteWebUrl(remote);
+  if (!r) return null;
+  const enc = encodeURIComponent;
+  if (r.host === 'github.com' || r.host.endsWith('.github.com')) return `${r.web}/compare/${enc(base)}...${enc(branch)}?expand=1`;
+  if (r.host.includes('gitlab')) return `${r.web}/-/merge_requests/new?merge_request%5Bsource_branch%5D=${enc(branch)}&merge_request%5Btarget_branch%5D=${enc(base)}`;
+  if (r.host.includes('bitbucket')) return `${r.web}/pull-requests/new?source=${enc(branch)}&dest=${enc(base)}`;
+  return `${r.web}`;
+}
+
+/** The pull request as Foreman drafts it: the run's title, and a body a reviewer can read without opening Foreman. */
+export function prDraft(run: { title?: string; mission: string; costUsd: number; costBasis?: string; git?: MissionGit }, missionDoc: string | null): { title: string; body: string } {
+  const first = run.mission.split('\n').find((l) => l.trim())?.trim() ?? 'Mission';
+  const title = (run.title || first).slice(0, 120);
+  const boxes = (missionDoc ?? '').split('\n').filter((l) => /^\s*[-*] \[[ xX]\]/.test(l)).map((l) => l.trim());
+  const spend = run.costBasis === 'priced' || run.costBasis === undefined ? `$${run.costUsd.toFixed(2)}` : run.costBasis;
+  const parts = [
+    '## Mission', '', run.mission.trim(), '',
+  ];
+  if (boxes.length) parts.push('## Done when', '', ...boxes, '');
+  parts.push('---', `Run by [Foreman](https://github.com/amenophis1er/foreman) on branch \`${run.git?.branch ?? ''}\` from \`${run.git?.base ?? ''}\` · spend ${spend}.`);
+  return { title, body: parts.join('\n') };
+}
+
+/** `git push -u origin <branch>`, as the user. Null on success, git's reason otherwise. */
+export async function pushBranch(folder: string, branch: string): Promise<string | null> {
+  try {
+    await git(['push', '-u', 'origin', branch], folder, 5 * 60_000);
+    return null;
+  } catch (err) {
+    const t = err instanceof Error ? err.message : String(err);
+    if (/could not read Username|Authentication failed|Permission denied|terminal prompts disabled/i.test(t)) {
+      return 'Git could not authenticate to the remote. Set up a credential helper or gh auth, or use an SSH remote with a key this machine has.';
+    }
+    return t.replace(/^git push:\s*/, 'git push failed: ');
+  }
+}
+
+/** Is GitHub's CLI here and signed in? Best effort, a few seconds at most. */
+export async function ghReady(): Promise<{ present: boolean; authed: boolean }> {
+  return new Promise((resolve) => {
+    execFile('gh', ['auth', 'status'], { timeout: 8_000 }, (err) => {
+      if (err && (err as NodeJS.ErrnoException).code === 'ENOENT') return resolve({ present: false, authed: false });
+      resolve({ present: true, authed: !err });
+    });
+  });
+}
+
+/** What became of a pull request, from gh: open, merged or closed. Null when gh cannot say. */
+export function pullRequestState(folder: string, url: string): Promise<{ state: 'open' | 'merged' | 'closed'; mergedAt?: string; number?: number } | null> {
+  return new Promise((resolve) => {
+    execFile('gh', ['pr', 'view', url, '--json', 'state,mergedAt,number'], {
+      cwd: folder, timeout: 15_000, env: { ...process.env, GH_PROMPT_DISABLED: '1' },
+    }, (err, stdout) => {
+      if (err) return resolve(null);
+      try {
+        const d = JSON.parse(String(stdout)) as { state?: string; mergedAt?: string | null; number?: number };
+        const state = d.state === 'MERGED' ? 'merged' : d.state === 'CLOSED' ? 'closed' : d.state === 'OPEN' ? 'open' : null;
+        resolve(state ? { state, mergedAt: d.mergedAt ?? undefined, number: d.number } : null);
+      } catch { resolve(null); }
+    });
+  });
+}
+
+/** `gh pr create`, as the user. Resolves to the PR's URL, or to why not. */
+export function createPullRequest(folder: string, opts: { base: string; branch: string; title: string; body: string }): Promise<{ url?: string; error?: string }> {
+  return new Promise((resolve) => {
+    execFile('gh', ['pr', 'create', '--base', opts.base, '--head', opts.branch, '--title', opts.title, '--body', opts.body], {
+      cwd: folder, timeout: 60_000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, GH_PROMPT_DISABLED: '1', GIT_TERMINAL_PROMPT: '0' },
+    }, (err, stdout, stderr) => {
+      if (err) {
+        if ((err as NodeJS.ErrnoException).code === 'ENOENT') return resolve({ error: 'gh is not installed' });
+        const t = String(stderr || err.message).trim();
+        const existing = /already exists:\s*(https?:\S+)/.exec(t);
+        if (existing) return resolve({ url: existing[1] });
+        return resolve({ error: `gh pr create: ${t.split('\n').filter(Boolean).pop() ?? t}` });
+      }
+      const url = String(stdout).split('\n').map((l) => l.trim()).find((l) => /^https?:\/\//.test(l));
+      resolve(url ? { url } : { error: 'gh did not return a pull request URL' });
+    });
+  });
+}

package/src/guard.test.ts

@@ -0,0 +1,104 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import type http from 'node:http';
+import { requestAllowed, pathPermitted } from './guard.js';
+
+const PORT = 4177;
+const TAILNET = { ip: '100.94.221.98', dnsName: 'laptop.tail1234.ts.net' };
+const OPTS = { port: PORT, tailnet: TAILNET };
+
+/** A request as the guard sees one: a method and a bag of headers. */
+function req(method: string, headers: Record<string, string>) {
+  return { method, headers: headers as http.IncomingHttpHeaders };
+}
+
+test('requestAllowed: the hosts Foreman answers to', () => {
+  assert.deepEqual(requestAllowed(req('GET', { host: `localhost:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: `127.0.0.1:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: `[::1]:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: `100.94.221.98:${PORT}` }), OPTS), { ok: true });
+  // The MagicDNS name with Foreman's port, and with whatever port
+  // `tailscale serve` put in front of it — including none at all (443).
+  assert.deepEqual(requestAllowed(req('GET', { host: `laptop.tail1234.ts.net:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: 'laptop.tail1234.ts.net' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: 'laptop.tail1234.ts.net:8443' }), OPTS), { ok: true });
+  // Case never matters in a host name.
+  assert.deepEqual(requestAllowed(req('GET', { host: 'LapTop.Tail1234.TS.net' }), OPTS), { ok: true });
+});
+
+test('requestAllowed: an unrecognised or missing Host is 421 (DNS rebinding)', () => {
+  assert.deepEqual(requestAllowed(req('GET', { host: `evil.example:${PORT}` }), OPTS), {
+    ok: false, status: 421, error: 'unrecognised Host',
+  });
+  assert.deepEqual(requestAllowed(req('GET', {}), OPTS), {
+    ok: false, status: 421, error: 'unrecognised Host',
+  });
+  // A neighbouring name is not the tailnet name.
+  assert.equal(requestAllowed(req('GET', { host: 'notlaptop.tail1234.ts.net' }), OPTS).ok, false);
+  // No tailnet: its address is not special.
+  assert.equal(requestAllowed(req('GET', { host: `100.94.221.98:${PORT}` }), { port: PORT, tailnet: null }).ok, false);
+});
+
+test('requestAllowed: safe methods pass on Host alone, whatever the Origin', () => {
+  const ok = req('GET', { host: `localhost:${PORT}`, origin: 'http://evil.example' });
+  assert.deepEqual(requestAllowed(ok, OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('HEAD', { host: `localhost:${PORT}`, origin: 'http://evil.example' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('OPTIONS', { host: `localhost:${PORT}`, origin: 'http://evil.example' }), OPTS), { ok: true });
+  // Including the event stream, which is how the dashboard stays live.
+  assert.deepEqual(requestAllowed(req('GET', { host: `127.0.0.1:${PORT}`, 'sec-fetch-site': 'cross-site' }), OPTS), { ok: true });
+});
+
+test('requestAllowed: an unsafe method with a foreign Origin is refused', () => {
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'http://evil.example' }), OPTS), {
+    ok: false, status: 403, error: 'cross-site request refused',
+  });
+  // Right name, wrong port: a different origin to the browser and to us.
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'http://localhost:9999' }), OPTS).ok, false);
+  // Not a web origin at all.
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'null' }), OPTS).ok, false);
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: 'file://' }), OPTS).ok, false);
+});
+
+test('requestAllowed: an unsafe method from Foreman’s own page is allowed', () => {
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, origin: `http://localhost:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('DELETE', { host: `127.0.0.1:${PORT}`, origin: `http://127.0.0.1:${PORT}` }), OPTS), { ok: true });
+  // The phone, through `tailscale serve` on 443: HTTPS, no port in the Origin.
+  assert.deepEqual(requestAllowed(req('POST', { host: 'laptop.tail1234.ts.net', origin: 'https://laptop.tail1234.ts.net' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `100.94.221.98:${PORT}`, origin: `http://100.94.221.98:${PORT}` }), OPTS), { ok: true });
+});
+
+test('requestAllowed: with no Origin, Sec-Fetch-Site decides', () => {
+  // curl, src/cli.ts, the Telegram paths and the tests: neither header.
+  assert.deepEqual(requestAllowed(req('POST', { host: `127.0.0.1:${PORT}` }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'same-origin' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'none' }), OPTS), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'cross-site' }), OPTS), {
+    ok: false, status: 403, error: 'cross-site request refused',
+  });
+  assert.equal(requestAllowed(req('POST', { host: `localhost:${PORT}`, 'sec-fetch-site': 'same-site' }), OPTS).ok, false);
+});
+
+test('requestAllowed: FOREMAN_BIND=all takes any Host, and Origin must match it', () => {
+  const all = { port: PORT, tailnet: null, bindAll: true };
+  assert.deepEqual(requestAllowed(req('GET', { host: '192.168.1.20:4177' }), all), { ok: true });
+  assert.deepEqual(requestAllowed(req('GET', { host: 'foreman.lan' }), all), { ok: true });
+  assert.deepEqual(requestAllowed(req('POST', { host: 'foreman.lan', origin: 'http://foreman.lan' }), all), { ok: true });
+  assert.equal(requestAllowed(req('POST', { host: 'foreman.lan', origin: 'http://evil.example' }), all).ok, false);
+  // Even wide open, a request with no Host at all is not one we can place.
+  assert.equal(requestAllowed(req('GET', {}), all).ok, false);
+});
+
+test('pathPermitted: at a root, under one, and never through ..', () => {
+  const roots = ['/Users/me/Projects', '/Users/me/work'];
+  assert.equal(pathPermitted('/Users/me/Projects', roots), true);
+  assert.equal(pathPermitted('/Users/me/Projects/foreman/src', roots), true);
+  assert.equal(pathPermitted('/Users/me/work', roots), true);
+  assert.equal(pathPermitted('/etc', roots), false);
+  assert.equal(pathPermitted('/Users/me', roots), false);
+  // A neighbour that merely shares a prefix is outside.
+  assert.equal(pathPermitted('/Users/me/Projects-backup', roots), false);
+  // Traversal is resolved before it is judged.
+  assert.equal(pathPermitted('/Users/me/Projects/../../../etc/passwd', roots), false);
+  assert.equal(pathPermitted('/Users/me/Projects/foreman/../other', roots), true);
+  assert.equal(pathPermitted('/Users/me/Projects/foreman', []), false);
+});