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

5.8 KB
Raw Blame
/**
 * The machine-readable receipt `npm run pregate` leaves behind.
 *
 * A later step (an attestation posted to the pull request, a merge gate) needs
 * to know three things a terminal transcript cannot prove: which stages ran
 * and passed, which suites were NOT run and why, and the exact working tree
 * that was validated. The tree hash is the seam: it covers untracked and
 * uncommitted files, so committing the validated state later yields an
 * identical `HEAD^{tree}` and the receipt can be matched to that commit.
 *
 * Builtins only: `scripts/pregate.js` loads this module from the bare fixture
 * checkouts its own tests build.
 */
import { execFileSync } from 'node:child_process';
import { createHash } from 'node:crypto';
import { copyFileSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';

/** Repo-relative location of the receipt; gitignored under `/.cache/`. */
export const PREGATE_REPORT_PATH = '.cache/pregate/report.json';

/**
 * Version 3 adds validationMode: focused receipts never attest CI suites.
 * Version 2 added `plan.downgraded`: whether a full plan was replaced by the
 * always-run guards. `scripts/pregate-attest.js` refuses a receipt without it,
 * because a downgraded server stage passing is not CI's server selection passing.
 */
export const PREGATE_REPORT_VERSION = 3;

/**
 * Hash the exact working tree as it stands: tracked, modified, deleted and
 * untracked files alike, ignored files excluded.
 *
 * Builds a throwaway index (a copy of the real one, so git reuses its stat
 * cache instead of rehashing every file), stages the whole tree into it and
 * writes a tree object. The real index and HEAD are never touched. `git add -A`
 * and `git commit` share the same ignore rules, so a commit of this same state
 * produces the same tree id.
 */
export function validatedTreeHash(cwd, { env = process.env } = {}) {
  const git = (args, extraEnv = {}) => execFileSync('git', args, { cwd, encoding: 'utf8', env: { ...env, ...extraEnv } }).trim();
  const scratch = mkdtempSync(join(tmpdir(), 'portos-pregate-index-'));
  try {
    const temporaryIndex = join(scratch, 'index');
    const liveIndex = resolve(cwd, git(['rev-parse', '--git-path', 'index']));
    if (existsSync(liveIndex)) copyFileSync(liveIndex, temporaryIndex);
    const indexEnv = { GIT_INDEX_FILE: temporaryIndex };
    git(['add', '-A', '--', '.'], indexEnv);
    return git(['write-tree'], indexEnv);
  } finally {
    rmSync(scratch, { recursive: true, force: true });
  }
}

// This cache lives only for one pregate invocation. Tree scanners deliberately
// cannot use the persistent module memo: their inputs include the index and Git
// refs as well as every working-tree file. Any unreadable input means no reuse.
export function guardInputSnapshot(cwd) {
  try {
    const digest = createHash('sha256').update(validatedTreeHash(cwd));
    for (const args of [
      ['rev-parse', 'HEAD'], ['ls-files', '--stage', '-z'],
      ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
      ['for-each-ref', '--format=%(refname) %(objectname)'],
    ]) {
      digest.update(execFileSync('git', args, { cwd, maxBuffer: 32 * 1024 * 1024,
        env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } }));
    }
    return digest.digest('hex');
  } catch {
    return null;
  }
}

/**
 * Shape the receipt. Pure: every input is a value the gate already holds.
 *
 * `stages` carry only names, commands and outcomes — never their environment,
 * which can hold database credentials. `skipped` names each suite CI would run
 * that this run did not, with the reason, so a consumer can never read a green
 * receipt as proof of a suite it never saw.
 */
export function buildPregateReport({
  plan,
  options,
  base,
  head,
  tree,
  treeAfterRun = tree,
  stages,
  skipped,
  runtime,
  startedAt,
  finishedAt,
  downgraded = false,
}) {
  const stageRecords = stages.map(({ name, suite, command, status, durationMs, exitCode = null, signal = null, guard, files, guardReuse }) => ({
    name, suite, command, status, durationMs, exitCode, signal,
    ...(guard ? { guard: true, files } : {}),
    ...(guardReuse ? { guardReuse } : {}),
  }));
  const passed = stageRecords.length > 0 && stageRecords.every((stage) => stage.status === 'passed');
  return {
    version: PREGATE_REPORT_VERSION,
    validationMode: options.full ? 'ci' : 'focused',
    startedAt,
    finishedAt,
    passed,
    treeStable: tree === treeAfterRun,
    base,
    head,
    tree,
    treeAfterRun,
    runtime,
    options,
    plan: {
      full: plan.full,
      // True when the local selection reduced CI coverage (no `--full`):
      // the server and client stages below then prove less than CI's selection.
      downgraded: Boolean(downgraded),
      reason: plan.reason,
      server: { mode: plan.server.mode, files: plan.server.files, sources: plan.server.sources },
      client: { mode: plan.client.mode, files: plan.client.files, sources: plan.client.sources },
      lint: { mode: plan.lint.mode, files: plan.lint.files },
      browser: { files: plan.browser.files },
      db: plan.db,
      build: plan.build,
      smoke: plan.smoke,
      windows: plan.windows,
      promptHistory: plan.promptHistory,
      linuxContainment: plan.linuxContainment,
      supercolliderLive: plan.supercolliderLive,
      dockerContainmentLive: plan.dockerContainmentLive,
      suiteReasons: plan.suiteReasons ?? {},
    },
    stages: stageRecords,
    skipped: skipped.map(({ suite, reason, remedy }) => ({ suite, reason, remedy })),
  };
}

/** Write the receipt under the checkout root and return its absolute path. */
export function writePregateReport(root, report) {
  const path = join(root, PREGATE_REPORT_PATH);
  mkdirSync(dirname(path), { recursive: true });
  writeFileSync(path, `${JSON.stringify(report, null, 2)}\n`);
  return path;
}