Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

13.3 KB
Raw Blame
/** Fresh forge facts for an operator's checkout-retirement review. No fetch,
 * policy write or saved grant: missing local objects require a separate fetch.
 */
import { createHash } from 'node:crypto';
import { execGit } from '../lib/execGit.js';
import { getOriginInfo } from '../lib/gitRemote.js';
import { parsePullRequestUrl } from '../lib/gitForge.js';

const oid = value => typeof value === 'string' && /^[a-f0-9]{40}(?:[a-f0-9]{24})?$/.test(value);
const safePath = value => typeof value === 'string' && value.length > 0 && !value.includes('\0') && !value.startsWith('/') && !value.split('/').some(part => part === '..' || part === '.');
const git = (args, cwd) => execGit(args, cwd, { maxBuffer: 4 * 1024 * 1024 }).then(r => r.stdout);

/** Selects the merged PR for an exact local tip. Selection is not proof: callers
 * re-read the PR with `readRetirementForgeEvidence` before acting on it.
 * `mergedAt` is the forge's merge time, or null for a historical-branch match.
 */
export async function findMergedPullRequest(repoPath, branch, tip, { forgeAccount = null } = {}) {
  const [{ execGh }, { resolveForgeExecOptions }, { githubRepoSpec }] = await Promise.all([
    import('./github.js'), import('./forgeExecOptions.js'), import('../lib/workTracker.js'),
  ]);
  const origin = await getOriginInfo(repoPath);
  const spec = githubRepoSpec(origin);
  if (!spec) throw new Error('retirement-forge-unsupported');
  const options = await resolveForgeExecOptions(repoPath, { forgeAccount });
  if (!oid(tip)) throw new Error('retirement-pr-ambiguous');
  // Query the exact commit, not an unbounded reused-branch history. A capped
  // association result cannot establish uniqueness and stays held.
  const association = await execGh(['api', '--hostname', origin.host,
    `repos/${origin.fullName}/commits/${tip}/pulls?per_page=100`], undefined, options)
    .catch(error => {
      // An unpublished/rebased local tip may not exist on the forge. That
      // endpoint's missing-commit response does not establish empty history: permit only the
      // bounded historical lookup below, which must independently succeed.
      const detail = error.ghStderr || '';
      if (/\(HTTP 404\)/.test(detail)
        || (detail.includes(`No commit found for SHA: ${tip}`) && /\(HTTP 422\)/.test(detail))) return null;
      throw new Error('retirement-forge-unavailable');
    });
  const rows = association === null ? [] : JSON.parse(association);
  if (!Array.isArray(rows) || rows.length >= 100
    || new Set(rows.map(row => row?.html_url)).size !== rows.length
    || rows.some(row => {
      const parsed = parsePullRequestUrl(row?.html_url);
      return !parsed || parsed.host !== origin.host || `${parsed.owner}/${parsed.repo}` !== origin.fullName
        || typeof row.head?.ref !== 'string' || !oid(row.head?.sha);
    })) throw new Error('retirement-pr-ambiguous');
  const matches = rows.filter(row => row.head.sha === tip && row.head.ref === branch
    && row.head.repo?.full_name === origin.fullName && row.base?.repo?.full_name === origin.fullName
    && row.state === 'closed' && typeof row.merged_at === 'string' && Number.isFinite(Date.parse(row.merged_at)));
  if (matches.length > 1) throw new Error('retirement-pr-ambiguous');
  if (matches.length === 1) return { url: matches[0].html_url, mergedAt: matches[0].merged_at };
  // Preserve historical review of an older local tip only when branch history
  // itself has exactly one candidate. Never choose among mismatching heads.
  const historical = await execGh(['pr', 'list', '--repo', spec, '--head', branch, '--state', 'merged',
    '--limit', '2', '--json', 'url'], undefined, options).then(JSON.parse)
    .catch(() => { throw new Error('retirement-forge-unavailable'); });
  const selected = Array.isArray(historical) && historical.length === 1 && parsePullRequestUrl(historical[0]?.url);
  if (!selected || selected.host !== origin.host || `${selected.owner}/${selected.repo}` !== origin.fullName) throw new Error('retirement-pr-ambiguous');
  return { url: historical[0].url, mergedAt: null };
}

export async function readRetirementForgeEvidence(repoPath, branch, prUrl, { forgeAccount = null, exactAliasHead = null, sourceSupersessionHead = null } = {}) {
  const origin = await getOriginInfo(repoPath);
  const parsed = parsePullRequestUrl(prUrl);
  if (!origin || !parsed || parsed.host !== origin.host || `${parsed.owner}/${parsed.repo}` !== origin.fullName) {
    throw new Error('retirement-pr-repository-mismatch');
  }
  const [{ execGh }, { resolveForgeExecOptions }] = await Promise.all([import('./github.js'), import('./forgeExecOptions.js')]);
  const options = await resolveForgeExecOptions(repoPath, { forgeAccount });
  const read = args => execGh(args, undefined, options).then(JSON.parse).catch(() => { throw new Error('retirement-forge-unavailable'); });
  const api = path => read(['api', '--hostname', origin.host, path]);
  const remote = await read(['pr', 'view', prUrl, '--json', 'url,state,headRefName,headRefOid,isCrossRepository,mergeCommit,baseRefName']);
  const repository = await api(`repos/${origin.fullName}`);
  const defaultBranch = repository.default_branch;
  const supersession = typeof branch === 'string' && oid(sourceSupersessionHead);
  // Explicit whole-checkout review may name a local repair alias, but only
  // when its exact tip is the merged PR head. Similar names are never evidence.
  const alias = remote.headRefName !== branch && oid(exactAliasHead) && exactAliasHead === remote.headRefOid;
  if (remote.url !== prUrl || remote.state !== 'MERGED' || (remote.headRefName !== branch && !alias && !supersession)
    || remote.isCrossRepository !== false || remote.baseRefName !== defaultBranch || !oid(remote.headRefOid) || !oid(remote.mergeCommit?.oid)) {
    throw new Error('retirement-pr-not-matching-merged');
  }
  if (supersession) {
    // A replacement delivery never authorizes abandoning an open delivery of
    // the original local branch. Unavailable/uncertain forge reads retain it.
    const open = await api(`repos/${origin.fullName}/pulls?state=open&head=${encodeURIComponent(`${origin.fullName.split('/')[0]}:${branch}`)}&per_page=100`);
    if (!Array.isArray(open)) throw new Error('retirement-forge-unavailable');
    if (open.length) throw new Error('retirement-source-delivery-open');
  }
  // A current-main merge base loses the original scope after a normal merge.
  // Use complete original PR metadata, and refuse API caps or ambiguous roots.
  const pullPath = `repos/${origin.fullName}/pulls/${parsed.number}`;
  const detail = await api(pullPath);
  if (detail.head?.sha !== remote.headRefOid || detail.base?.ref !== defaultBranch || detail.merged !== true
    || !Number.isInteger(detail.changed_files) || detail.changed_files < 1 || detail.changed_files > 3000
    || !Number.isInteger(detail.commits) || detail.commits < 1 || detail.commits > 250) {
    throw new Error('retirement-original-scope-unavailable');
  }
  const pages = async suffix => {
    const value = await read(['api', '--hostname', origin.host, '--paginate', '--slurp', `${pullPath}/${suffix}?per_page=100`]);
    if (!Array.isArray(value) || !value.every(Array.isArray)) throw new Error('retirement-original-scope-unavailable');
    return value.flat();
  };
  const files = await pages('files');
  const commits = await pages('commits');
  if (files.length !== detail.changed_files || commits.length !== detail.commits
    || new Set(files.map(file => file.filename)).size !== files.length
    || new Set(commits.map(commit => commit.sha)).size !== commits.length
    || !commits.every(commit => oid(commit.sha)) || commits.at(-1)?.sha !== remote.headRefOid
    || commits[0]?.parents?.length !== 1 || !oid(commits[0].parents[0].sha)
    || files.some(file => !safePath(file.filename) || (file.status === 'renamed' && !safePath(file.previous_filename)))) {
    throw new Error('retirement-original-scope-unavailable');
  }
  const changedPaths = [...new Set(files.flatMap(file => file.status === 'renamed' ? [file.filename, file.previous_filename] : [file.filename]))].sort();
  const changeBase = commits[0].parents[0].sha;
  const firstCommit = commits[0].sha;
  const target = await api(`repos/${origin.fullName}/git/ref/heads/${encodeURIComponent(defaultBranch)}`);
  if (!oid(target.object?.sha)) throw new Error('retirement-default-unreadable');
  // ls-remote returns an empty successful result only for actual ref absence.
  const remoteHead = branch ? (await git(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], repoPath)
    .catch(() => { throw new Error('retirement-remote-ref-unreadable'); })).trim() : '';
  if (remoteHead && remoteHead !== `${supersession ? sourceSupersessionHead : remote.headRefOid}\trefs/heads/${branch}`) throw new Error('retirement-remote-head-changed');
  const publishedRemoteHead = alias || supersession ? (await git(['ls-remote', '--heads', 'origin', `refs/heads/${remote.headRefName}`], repoPath)
    .catch(() => { throw new Error('retirement-remote-ref-unreadable'); })).trim() : null;
  if (publishedRemoteHead && publishedRemoteHead !== `${remote.headRefOid}\trefs/heads/${remote.headRefName}`) throw new Error('retirement-remote-head-changed');
  return { repository: `${origin.host}/${origin.fullName}`, prUrl, prHead: remote.headRefOid,
    mergeCommit: remote.mergeCommit.oid, changedPaths, changeBase, firstCommit, defaultBranch, defaultHead: target.object.sha, remoteHead: remoteHead || null,
    ...(alias || supersession ? { ...(alias && { exactAliasHead }), ...(supersession && { sourceSupersessionHead }),
      publishedBranch: remote.headRefName, publishedRemoteHead: publishedRemoteHead || null } : {}) };
}

/** Returned differences are review material, not executable instructions or an
 * automated supersession verdict. Every byte and identity participates in digest.
 */
export async function buildCheckoutRetirementReview({ repoPath, release, prUrl, kind, contentFingerprint, administrationFingerprint, policy }, {
  readForge = readRetirementForgeEvidence, forgeAccount = null,
} = {}) {
  const forge = await readForge(repoPath, release.branch, prUrl, { forgeAccount });
  if (!forge || !oid(forge.prHead) || !oid(forge.mergeCommit) || !oid(forge.defaultHead)) throw new Error('retirement-forge-unreadable');
  if (release.branch === forge.defaultBranch) throw new Error('protected-branch');
  if (!oid(forge.changeBase) || !oid(forge.firstCommit) || !Array.isArray(forge.changedPaths)
    || !forge.changedPaths.length || !forge.changedPaths.every(safePath)) throw new Error('retirement-original-scope-unavailable');
  // Independent reads run together (each Git spawn is mostly launch latency);
  // the verdicts keep their original precedence.
  await Promise.all([...new Set([forge.prHead, forge.mergeCommit, forge.defaultHead, forge.changeBase, forge.firstCommit])]
    .map(head => git(['cat-file', '-e', `${head}^{commit}`], repoPath).catch(() => { throw new Error('retirement-local-objects-missing'); })));
  const [inDefault, parents, inPr] = await Promise.allSettled([
    git(['merge-base', '--is-ancestor', forge.mergeCommit, forge.defaultHead], repoPath),
    git(['rev-list', '--parents', '-n', '1', forge.firstCommit], repoPath),
    git(['merge-base', '--is-ancestor', forge.firstCommit, forge.prHead], repoPath),
  ]);
  if (inDefault.status === 'rejected') throw new Error('retirement-merge-not-in-default');
  if (parents.status === 'rejected') throw parents.reason;
  const parent = parents.value.trim().split(/\s+/);
  if (parent.length !== 2 || parent[1] !== forge.changeBase) throw new Error('retirement-original-scope-unavailable');
  if (inPr.status === 'rejected') throw new Error('retirement-original-scope-unavailable');
  const base = (await git(['merge-base', release.head, kind ? forge.defaultHead : forge.changeBase], repoPath)).trim();
  if (base === release.head && !kind) throw new Error('retirement-original-scope-unavailable');
  const [localPathsOut, localPatch] = await Promise.all([
    git(['diff', '--name-only', '-z', base, release.head], repoPath),
    git(['diff', '--binary', '--no-ext-diff', '--no-textconv', base, release.head], repoPath),
  ]);
  const localPaths = localPathsOut.split('\0').filter(Boolean);
  // An exact merged PR head can carry previously merged/squashed history and
  // upstream merges before its first listed commit. Those inherited files are
  // not this PR's change scope. Older/replacement source heads still need the
  // complete local patch comparison so unpublished work cannot disappear.
  const paths = [...new Set(release.head === forge.prHead && !kind
    ? forge.changedPaths : [...forge.changedPaths, ...localPaths])].sort();
  const difference = paths.length ? await git(['--literal-pathspecs', 'diff', '--binary', '--no-ext-diff', '--no-textconv', release.head, forge.defaultHead, '--', ...paths], repoPath) : '';
  // Exact delivered PR heads remain delivered after later changes to shared
  // files. Older/replacement heads still need content equivalence or review.
  const exactMergedDelivery = !kind && release.head === forge.prHead;
  const mechanicallyEquivalent = (difference === '' || exactMergedDelivery) && kind !== 'source-supersession';
  const evidence = { repoPath, release, forge, contentFingerprint, administrationFingerprint, policy,
    ...(kind && { kind }),
    comparison: { base, paths, localPatch, difference, exactMergedDelivery, disposition: mechanicallyEquivalent ? 'integrated' : 'review-supersession' } };
  return { digest: createHash('sha256').update(JSON.stringify(evidence)).digest('hex'), ...evidence };
}