@polymorphism-tech/morph-spec 8.31.0 → 8.32.0

package/src/lib/git/pending-prs.js

@@ -0,0 +1,89 @@
+/**
+ * pending-prs.js — as features que existem SÓ como PR aberto.
+ *
+ * `finish --pr` deixa o root primário sem vestígio da feature: o
+ * `shedRootFeatureScope` apaga `.morph/features/{f}` e o archive foi commitado
+ * na branch `morph/{f}`, chegando na default apenas no merge. Entre abrir e
+ * mergear, portanto, nenhuma superfície local sabe que aquela branch tem dono —
+ * foi assim que uma branch com PR #51 aberto quase foi varrida.
+ *
+ * Este módulo devolve o dono. Não há estado persistido a consultar, e é de
+ * propósito: o PR aberto no GitHub É o registro, a branch é sempre
+ * `morph/{feature}`, e o `pr-index.js` já é o leitor único desse fato. Lembrar
+ * o número numa segunda cópia só criaria como divergir dele.
+ *
+ * `null` (do índice ou daqui) significa DESCONHECIDO e jamais "não há
+ * pendência" — a mesma regra que torna seguros os caminhos destrutivos que
+ * leem o índice.
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { buildPrIndex } from './pr-index.js';
+
+/** As branches que o framework cria por feature. */
+export const MORPH_BRANCH_RE = /^morph\/(.+)$/;
+
+const DAY_MS = 86400000;
+
+/**
+ * O PR da branch canônica de uma feature.
+ *
+ * @param {Map<string,object>|null} index - de buildPrIndex
+ * @param {string} feature
+ * @returns {{number:number,state:string,mergedAt:string|null,url:string|null,createdAt:string|null}|null}
+ *   null = desconhecido OU sem PR; quem precisa distinguir os dois olha o índice.
+ */
+export function prForFeature(index, feature) {
+  if (!index) return null;
+  return index.get(`morph/${feature}`) || null;
+}
+
+/** A feature tem pasta (ativa ou arquivada) nesta árvore? */
+function hasLocalFolder(root, feature) {
+  return existsSync(join(root, '.morph', 'features', feature))
+    || existsSync(join(root, '.morph', 'archive', feature));
+}
+
+/**
+ * As features aguardando merge: PR OPEN numa branch `morph/*` cujo slug não
+ * tem pasta nesta árvore.
+ *
+ * @param {string} root - a raiz a inspecionar (e de onde o `gh` roda)
+ * @param {{ index?: Map<string,object>|null, now?: Date }} [opts]
+ *   `index` injeta um índice já construído (o `list`/`fleet` constroem um por
+ *   processo e reaproveitam; os testes passam um sintético). Ausente = constrói.
+ * @returns {Array<{feature:string,branch:string,number:number,state:string,url:string|null,createdAt:string|null,ageDays:number|null}>|null}
+ *   null = DESCONHECIDO. Nunca lista vazia por falta de informação.
+ */
+export function pendingPrFeatures(root, opts = {}) {
+  const index = opts.index !== undefined ? opts.index : buildPrIndex(root);
+  if (!index) return null;
+
+  const now = opts.now instanceof Date ? opts.now : new Date();
+  const out = [];
+  for (const [branch, pr] of index) {
+    const m = branch.match(MORPH_BRANCH_RE);
+    if (!m) continue;
+    if (pr.state !== 'OPEN') continue;
+    const feature = m[1];
+    if (hasLocalFolder(root, feature)) continue;
+
+    let ageDays = null;
+    if (pr.createdAt) {
+      const t = Date.parse(pr.createdAt);
+      if (!Number.isNaN(t)) ageDays = Math.floor((now.getTime() - t) / DAY_MS);
+    }
+    out.push({
+      feature,
+      branch,
+      number: pr.number,
+      state: pr.state,
+      url: pr.url ?? null,
+      createdAt: pr.createdAt ?? null,
+      ageDays,
+    });
+  }
+  out.sort((a, b) => a.feature.localeCompare(b.feature));
+  return out;
+}

package/src/lib/git/pr-index.js

@@ -0,0 +1,70 @@
+/**
+ * pr-index.js — one `gh pr list` per process, shared by every caller that needs
+ * to answer "does a branch have a PR, and in what state".
+ *
+ * Extracted from `fleet-scanner.js` because three independent leaders now ask
+ * the SAME question and must get the SAME answer:
+ *
+ *   • `morph-spec fleet`        — the PR column
+ *   • `morph-spec branch prune` — a branch with an OPEN PR is never deleted,
+ *                                 and a MERGED one is deletable even when git
+ *                                 cannot see the merge (squash-merge)
+ *   • `morph-spec doctor --worktrees` — a worktree whose branch carries an open
+ *                                 PR must NOT be offered up for removal
+ *
+ * Fail-open by construction: no `gh`, not authenticated, not GitHub, or a
+ * timeout all yield `null`. `null` means "unknown", NEVER "no PR" — every
+ * caller must treat the two differently, because the destructive paths
+ * (prune, remove) are only safe when the answer is a positive fact.
+ */
+
+import { execFileSync } from 'child_process';
+import { resolveGh } from './gh.js';
+
+/**
+ * Build the branch → PR index for a repository.
+ *
+ * Gated on the origin URL actually pointing at github.com: `gh` against any
+ * other host is a guaranteed error, and paying its start-up cost to learn that
+ * on every call is pure latency.
+ *
+ * `--state all` on purpose: a MERGED PR is exactly the evidence a squash-merge
+ * erases from git history, and it is the whole reason `branch prune` exists.
+ * First wins — `gh` lists newest-first, so an OPEN PR shadows an older closed
+ * one on the same branch.
+ *
+ * @param {string} root - repository root to run `gh` from
+ * @param {{ limit?: number, timeout?: number }} [opts]
+ * @returns {Map<string,{number:number,state:string,mergedAt:string|null,url:string|null,createdAt:string|null}>|null}
+ *   null = DESCONHECIDO (sem gh / não é GitHub / falhou), não "sem PRs"
+ */
+export function buildPrIndex(root, opts = {}) {
+  const limit = String(opts.limit ?? 200);
+  const timeout = opts.timeout ?? 8000;
+  try {
+    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, stdio: 'pipe' }).toString();
+    if (!/github\.com/i.test(url)) return null;
+    const { bin, prefix } = resolveGh();
+    const out = execFileSync(
+      bin,
+      [...prefix, 'pr', 'list', '--state', 'all', '--limit', limit,
+        '--json', 'number,state,headRefName,mergedAt,url,createdAt'],
+      { cwd: root, stdio: 'pipe', timeout },
+    ).toString();
+    const map = new Map();
+    for (const pr of JSON.parse(out)) {
+      if (pr?.headRefName && !map.has(pr.headRefName)) {
+        map.set(pr.headRefName, {
+          number: pr.number,
+          state: pr.state,
+          mergedAt: pr.mergedAt ?? null,
+          url: pr.url ?? null,
+          createdAt: pr.createdAt ?? null,
+        });
+      }
+    }
+    return map;
+  } catch {
+    return null;
+  }
+}

package/src/lib/worktree/fleet-scanner.js

@@ -28,6 +28,8 @@ import {
   pendingGatesFrom,
 } from '../../../framework/hooks/shared/state-reader.js';
 import { listClaims } from '../../../framework/hooks/shared/claim-registry.js';
+import { buildPrIndex } from '../git/pr-index.js';
+import { pendingPrFeatures } from '../git/pending-prs.js';
 
 function countFrom(raw) {
   const data = JSON.parse(raw);
@@ -133,32 +135,18 @@ function remoteHeads(root) {
 /**
  * One `gh pr list` for the whole scan → Map<headRefName, {number, state}>.
  *
- * Gated on the origin URL actually pointing at github.com — `gh` against any
- * other host is a guaranteed error, and paying its start-up cost to learn that
- * on every `fleet` call is pure latency. Fail-open: no `gh`, not authenticated,
- * or a timeout all yield `null`, which just leaves the PR half of the column
- * empty while `pushed` still works.
+ * Delegates to the shared `buildPrIndex` so `fleet`, `branch prune` and
+ * `doctor --worktrees` cannot answer "does this branch have a PR" differently
+ * — the destructive two read it to decide what NOT to delete.
+ *
+ * Fail-open: `null` (no `gh`, not authenticated, not GitHub, timeout) just
+ * leaves the PR half of the column empty while `pushed` still works.
  *
  * @param {string} root
  * @returns {Map<string,{number:number,state:string}>|null}
  */
 function remotePrs(root) {
-  try {
-    const url = execFileSync('git', ['remote', 'get-url', 'origin'], { cwd: root, stdio: 'pipe' }).toString();
-    if (!/github\.com/i.test(url)) return null;
-    const out = execFileSync('gh', ['pr', 'list', '--state', 'all', '--limit', '100', '--json', 'number,state,headRefName'], {
-      cwd: root, stdio: 'pipe', timeout: 8000,
-    }).toString();
-    const map = new Map();
-    for (const pr of JSON.parse(out)) {
-      // First wins: `gh` lists newest-first, so an OPEN PR shadows an older
-      // closed one on the same branch.
-      if (pr?.headRefName && !map.has(pr.headRefName)) map.set(pr.headRefName, { number: pr.number, state: pr.state });
-    }
-    return map;
-  } catch {
-    return null;
-  }
+  return buildPrIndex(root, { limit: 100 });
 }
 
 /**
@@ -297,5 +285,47 @@ export function scanFleet(cwd = process.cwd()) {
     }
   } catch { /* fail-open */ }
 
+  // Features that exist ONLY as an open PR: no registered worktree, no
+  // `.morph/features/*` folder in this tree. This is exactly what
+  // `finish --pr` leaves behind — and without this pass `fleet` would say
+  // "nothing in flight" about work that is under review on GitHub.
+  //
+  // `prs` was attempted above whenever `heads` is truthy (`remotePrs` runs —
+  // see `const prs = heads ? remotePrs(root) : null;` — regardless of
+  // whether that `gh` call itself succeeded). Gate on the SAME condition
+  // `remotePrs` used, not on `prs !== null`: `remotePrs`/`buildPrIndex` can
+  // fail (timeout, not authenticated, malformed JSON) and legitimately
+  // return `null` even after really invoking `gh`. Passing that `null`
+  // through lets `pendingPrFeatures` short-circuit on its own documented
+  // contract (explicit `null` index = known unknown, never a fallback build)
+  // instead of retrying `gh` a second time in the same scan. Only when
+  // `remotePrs` was never attempted at all (`heads` falsy) does
+  // `pendingPrFeatures` get no index, so it makes the first (and only) `gh`
+  // call itself.
+  try {
+    const seen = new Set(entries.map((e) => e.feature));
+    const pendOpts = heads ? { index: prs } : {};
+    for (const p of pendingPrFeatures(root, pendOpts) || []) {
+      if (seen.has(p.feature)) continue;
+      entries.push({
+        feature: p.feature,
+        workType: null,
+        phase: 'aguardando-merge',
+        status: 'in_progress',
+        pendingGates: [],
+        location: 'pr-pending',
+        path: null,
+        branch: p.branch,
+        tasks: null,
+        env: null,
+        handoff: { exists: false, generatedAt: null },
+        lastCommit: null,
+        dirty: null,
+        remote: { branch: p.branch, pushed: true, sha: null, pr: { number: p.number, state: p.state } },
+        claim: null,
+      });
+    }
+  } catch { /* fail-open — a pendency not listed must never take down the scan */ }
+
   return { root, entries };
 }

package/src/lib/worktree/ignored-triage.js

@@ -0,0 +1,197 @@
+/**
+ * ignored-triage.js — decide, per gitignored leftover, whether removing a
+ * worktree would DESTROY something or merely delete a copy.
+ *
+ * WHY THIS EXISTS: `git worktree remove` deletes gitignored files outright and
+ * the clean-check that gates it (`git status --porcelain`) omits them by
+ * design, so a user's `.env` dies silently while the command reports success.
+ * The first fix for that refused the removal whenever ANY unrecognised
+ * gitignored path was present — correct, but blind: in the observed session a
+ * worktree carried `.env` and `.env.e2e` that were BYTE-IDENTICAL to the
+ * primary root's, alongside a `keys/key-*.xml` that existed nowhere else. The
+ * refusal treated them alike, and the only escape it offered
+ * (`--discard-ignored`) destroyed the unique one together with the replicas.
+ *
+ * The triage below replaces "recognised vs not" with the question that actually
+ * decides whether bytes are lost:
+ *
+ *   REPLICABLE — the primary root has the same relative path with identical
+ *                content. Deleting the worktree's copy loses nothing; the
+ *                original stays where it always was.
+ *   DISPOSABLE — a well-known build artifact (`bin/`, `obj/`, `node_modules/`,
+ *                `__pycache__/`, `test-results/`, `.auth/`, `*.tsbuildinfo`).
+ *                Reproducible from source, which is a STRONGER guarantee than
+ *                backed up.
+ *   EXCLUSIVE  — everything else: no counterpart in the root, or a counterpart
+ *                whose content differs. These are the only bytes at stake, and
+ *                the caller copies them to `finish-backup` before proceeding.
+ *
+ * Fail-CLOSED on every uncertainty: an unreadable file, a hash that cannot be
+ * computed, a directory too large to compare, a counterpart that is a link
+ * rather than a real file — all classify as EXCLUSIVE. Being wrong in that
+ * direction costs a backup copy; being wrong the other way costs the file.
+ */
+
+import { createHash } from 'crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Well-known, regenerable build artifacts. Deliberately narrow — do NOT add
+ * speculative patterns (`dist/`, `.next/`) that a project might legitimately
+ * hand-edit; anything unlisted still reaches the EXCLUSIVE bucket, where it is
+ * backed up rather than assumed disposable.
+ *
+ * `.auth/` (Playwright storage state) belongs here for a reason worth stating:
+ * it holds a captured session, so it LOOKS like precious local state — but it
+ * is regenerated by the auth setup project on the next run, and it expires on
+ * its own. Keeping it out of the backup avoids copying credentials around.
+ */
+const DISPOSABLE_DIR_NAMES = new Set([
+  'bin', 'obj', 'node_modules', '__pycache__', 'test-results', '.auth',
+]);
+const DISPOSABLE_FILE_RE = /\.tsbuildinfo$/;
+
+/**
+ * Comparing a directory recursively is only worth doing while it stays small:
+ * the point is to spare `.env`-sized replicas from a needless refusal, not to
+ * checksum a data set. Past either cap the answer becomes EXCLUSIVE (the safe
+ * direction), and the caller backs it up.
+ */
+const REPLICABLE_MAX_FILES = 500;
+const REPLICABLE_MAX_BYTES = 8 * 1024 * 1024;
+
+/**
+ * @param {string} p - forward-slash relative path
+ * @returns {boolean}
+ */
+export function isDisposableBuildArtifact(p) {
+  if (DISPOSABLE_FILE_RE.test(p)) return true;
+  return p.split('/').filter(Boolean).some((seg) => DISPOSABLE_DIR_NAMES.has(seg));
+}
+
+function sha256OfFile(path) {
+  try {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Real file (not a link, not a directory)? A reparse point must never be read
+ * THROUGH — following one is the exact failure mode the whole teardown path
+ * exists to prevent — so a link on either side makes the pair incomparable.
+ */
+function isRealFile(path) {
+  try {
+    return lstatSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isRealDir(path) {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Every real file under `dir`, relative to it. Returns null when the walk hits
+ * a link, an unreadable entry, or either cap — "cannot enumerate" and "too big
+ * to compare" both mean "do not claim this is replicable".
+ */
+function walkFiles(dir, budget) {
+  const out = [];
+  const stack = [''];
+  while (stack.length) {
+    const rel = stack.pop();
+    let entries;
+    try {
+      entries = readdirSync(join(dir, rel), { withFileTypes: true });
+    } catch {
+      return null;
+    }
+    for (const e of entries) {
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      const childAbs = join(dir, childRel);
+      if (e.isSymbolicLink()) return null; // never compare through a link
+      if (e.isDirectory()) { stack.push(childRel); continue; }
+      if (!e.isFile()) return null; // socket/fifo/unknown — incomparable
+      let size;
+      try { size = lstatSync(childAbs).size; } catch { return null; }
+      budget.files += 1;
+      budget.bytes += size;
+      if (budget.files > REPLICABLE_MAX_FILES || budget.bytes > REPLICABLE_MAX_BYTES) return null;
+      out.push(childRel);
+    }
+  }
+  return out;
+}
+
+/**
+ * Does `root/rel` hold exactly the same content as `worktree/rel`?
+ *
+ * Files compare by SHA-256; directories compare by having the SAME set of
+ * files, each with an identical hash — a root copy that is merely a SUPERSET
+ * is not a replica of the worktree's, because the worktree's own extra files
+ * would still be lost.
+ *
+ * @returns {boolean} false on ANY uncertainty
+ */
+export function isReplicatedInRoot(worktreePath, rootPath, rel) {
+  const src = join(worktreePath, rel);
+  const dst = join(rootPath, rel);
+  if (!existsSync(src) || !existsSync(dst)) return false;
+
+  if (isRealFile(src)) {
+    if (!isRealFile(dst)) return false;
+    const a = sha256OfFile(src);
+    const b = sha256OfFile(dst);
+    return a !== null && a === b;
+  }
+
+  if (isRealDir(src)) {
+    if (!isRealDir(dst)) return false;
+    const srcFiles = walkFiles(src, { files: 0, bytes: 0 });
+    if (srcFiles === null) return false;
+    const dstFiles = walkFiles(dst, { files: 0, bytes: 0 });
+    if (dstFiles === null) return false;
+    if (srcFiles.length !== dstFiles.length) return false;
+    const dstSet = new Set(dstFiles);
+    for (const f of srcFiles) {
+      if (!dstSet.has(f)) return false;
+      const a = sha256OfFile(join(src, f));
+      const b = sha256OfFile(join(dst, f));
+      if (a === null || a !== b) return false;
+    }
+    return true;
+  }
+
+  return false; // a link, or something that is neither — incomparable
+}
+
+/**
+ * Split gitignored worktree paths into the three buckets above.
+ *
+ * ORDER IS DELIBERATE: disposable is checked FIRST, so a `bin/` that happens to
+ * be byte-identical to the root's is discarded rather than hashed, and a
+ * `node_modules` never enters the comparison budget at all.
+ *
+ * @param {{ worktreePath: string, rootPath: string, paths: string[] }} args
+ * @returns {{ replicable: string[], disposable: string[], exclusive: string[] }}
+ */
+export function triageIgnoredPaths({ worktreePath, rootPath, paths }) {
+  const replicable = [];
+  const disposable = [];
+  const exclusive = [];
+  for (const rel of paths) {
+    if (isDisposableBuildArtifact(rel)) { disposable.push(rel); continue; }
+    if (isReplicatedInRoot(worktreePath, rootPath, rel)) { replicable.push(rel); continue; }
+    exclusive.push(rel);
+  }
+  return { replicable, disposable, exclusive };
+}