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

9.6 KB
Raw Blame
/**
 * The wire contract between `scripts/pregate-attest.js` (which posts a commit
 * status after a complete local pregate) and `scripts/ci-test-plan.js` (which
 * reads it back on the pull request and skips the stages it attests to).
 *
 * The status is bound to a TREE hash, not a commit: the receipt hashes the
 * exact working tree pregate validated, and the planner compares it with
 * `<head>^{tree}` — the same "content, not SHA" reasoning as
 * `scripts/verify-ci-status.js`. The description also names the platform and
 * Node major the stages ran on, so the plan summary can show what vouched for
 * a Linux job. A description is at most 140 characters (GitHub's limit),
 * which fits every stage name plus those two fields.
 *
 * Builtins only: the planner loads this before any dependency install.
 */

/** The commit-status `context` the attestation is posted under. */
export const PREGATE_STATUS_CONTEXT = 'pregate';

/** GitHub truncates a status description past this many characters. */
export const STATUS_DESCRIPTION_MAX_LENGTH = 140;

/**
 * Receipt `suite` names a status may attest to, in the order they are
 * encoded. `scan` is informational (the hidden-content scan runs inside the
 * impact job and is never skipped); every other name maps to a CI job or step
 * the planner can leave out — see `applyAttestation` in scripts/ci-test-plan.js.
 */
export const ATTESTABLE_STAGES = Object.freeze([
  'scan', 'prompt-history', 'lint', 'server', 'client', 'build', 'smoke', 'browser', 'db',
]);

const TREE_RE = /^[0-9a-f]{40}$/;
const ATTESTABLE = new Set(ATTESTABLE_STAGES);

/**
 * The stages a receipt vouches for: every receipt stage of that suite ran and
 * passed, and the suite ran CI's selection for it.
 *
 * A downgraded full plan ran only the always-run guards in the server and
 * client stages (`downgradeFullPlan` in scripts/pregate.js), so those two
 * suites are never attested from such a receipt even though their stages
 * passed; lint runs whole either way. Stages that were skipped, not run,
 * or absent from the receipt are simply not attested — CI keeps running them.
 *
 * @param {object} report - a `.cache/pregate/report.json` receipt
 * @returns {string[]} in ATTESTABLE_STAGES order
 */
export function attestedStagesFromReceipt(report) {
  // Focused local checks are not CI suite proof, even if stage names coincide.
  if (report?.validationMode === 'focused' || (report?.version >= 3 && report?.validationMode !== 'ci')) return [];
  const stages = Array.isArray(report?.stages) ? report.stages : [];
  const reduced = report?.plan?.downgraded === true ? new Set(['server', 'client']) : new Set();
  return ATTESTABLE_STAGES.filter((suite) => {
    if (reduced.has(suite)) return false;
    const records = stages.filter((stage) => stage?.suite === suite);
    return records.length > 0 && records.every((stage) => stage.status === 'passed');
  });
}

/** `process.version` → its major, e.g. `v26.10.0` → 26. */
export const nodeMajor = (version) => {
  const match = /^v?(\d+)/.exec(String(version ?? ''));
  return match ? Number(match[1]) : null;
};

/**
 * The status description for a tree, the platform it ran on, and its stages.
 *
 * @param {{tree: string, stages: string[], os: string, node: number}} attestation
 * @returns {string}
 */
export function encodeAttestation({ tree, stages, os, node }) {
  if (!TREE_RE.test(tree ?? '')) throw new Error('attestation needs a 40-hex tree hash');
  if (!/^[a-z0-9]+$/.test(os ?? '')) throw new Error('attestation needs a platform name (process.platform)');
  if (!Number.isInteger(node) || node <= 0) throw new Error('attestation needs a Node major version');
  const ordered = ATTESTABLE_STAGES.filter((stage) => stages.includes(stage));
  const unknown = stages.filter((stage) => !ATTESTABLE.has(stage));
  if (unknown.length > 0) throw new Error(`unknown attestation stage(s): ${unknown.join(', ')}`);
  if (ordered.length === 0) throw new Error('attestation needs at least one stage');
  const description = `tree=${tree} os=${os} node=${node} stages=${ordered.join(',')}`;
  if (description.length > STATUS_DESCRIPTION_MAX_LENGTH) {
    throw new Error(`attestation description exceeds ${STATUS_DESCRIPTION_MAX_LENGTH} characters`);
  }
  return description;
}

/**
 * The tree, platform, Node major and stages a status description claims, or
 * null when it is not an attestation this module wrote: any unknown stage
 * name, a malformed tree, or extra fields make the whole description
 * unreadable rather than partially trusted.
 *
 * @param {string} description
 * @returns {{tree: string, stages: string[], os: string, node: number}|null}
 */
export function parseAttestation(description) {
  const match = /^tree=([0-9a-f]{40}) os=([a-z0-9]+) node=(\d{1,3}) stages=([a-z,-]+)$/.exec(String(description ?? '').trim());
  if (!match) return null;
  const stages = match[4].split(',');
  if (stages.length === 0 || stages.some((stage) => !ATTESTABLE.has(stage))) return null;
  if (new Set(stages).size !== stages.length) return null;
  return { tree: match[1], os: match[2], node: Number(match[3]), stages: ATTESTABLE_STAGES.filter((stage) => stages.includes(stage)) };
}

/**
 * The description a revocation posts: a `failure` state whose text says why,
 * so the planner's refusal names it and a reader of the commit's statuses
 * sees the operator's reason.
 */
export function encodeRevocation(reason) {
  const text = `revoked: ${String(reason ?? '').trim() || 'pregate result withdrawn'}`.replace(/[\r\n]+/g, ' ');
  return text.length > STATUS_DESCRIPTION_MAX_LENGTH ? `${text.slice(0, STATUS_DESCRIPTION_MAX_LENGTH - 1)}…` : text;
}

/**
 * GitHub's SSH endpoint hosts answer for github.com. Same rule as
 * `server/lib/gitRemote.js`: the host is what the API is addressed to.
 */
const API_HOST_ALIASES = { 'ssh.github.com': 'github.com' };

/**
 * Parse an `owner/repo` out of a git remote URL — the SSH and HTTPS shapes
 * `server/lib/gitRemote.js#parseGitRemoteUrl` accepts, without that module's
 * ssh-config alias resolution or its import closure. `ssh.github.com` is
 * folded to `github.com`. A personal ssh alias (`git@github-acme:…`, no dot in
 * the host) parses but `hostIsResolvable` is false for it: the caller then
 * learns the real host from `gh repo view`. Null for anything that is not
 * exactly two path segments.
 *
 * @param {string} url
 * @returns {{host: string, owner: string, repo: string, hostIsResolvable: boolean}|null}
 */
export function parseRemoteRepository(url) {
  if (typeof url !== 'string' || !url.trim()) return null;
  const trimmed = url.trim().replace(/\/$/, '');
  const stripGit = (value) => value.replace(/\.git$/i, '');
  const normalizeHost = (host) => {
    const bare = host.replace(/:\d+$/, '').toLowerCase();
    return API_HOST_ALIASES[bare] ?? bare;
  };
  const shape = (host, owner, repo) => ({ host, owner, repo: stripGit(repo), hostIsResolvable: host.includes('.') });
  const scp = /^[a-zA-Z0-9._-]+@([^:]+):(?:\d+\/)?([^/]+)\/([^/]+)$/.exec(trimmed);
  if (scp) return shape(normalizeHost(scp[1]), scp[2], scp[3]);
  const urlStyle = /^[a-zA-Z]+:\/\/(?:[^@/]+@)?([^/]+)\/([^/]+)\/([^/]+)$/.exec(trimmed);
  if (urlStyle) return shape(normalizeHost(urlStyle[1]), urlStyle[2], urlStyle[3]);
  return null;
}

/**
 * The newest `pregate` status decides, whatever its state: a later `failure`
 * (a revocation, `pregate-attest.js --revoke`) or `pending`/`error` withdraws
 * an earlier success on the same commit, and a later success by someone else
 * blocks it too — the newest word on the commit is not the owner's.
 *
 * Trust rests on three facts, each checked here: only a repository writer can
 * create a status on this repository (a fork's `pull_request` token is
 * read-only); the status was created by the repository owner; and the tree it
 * names is the tree of the head commit.
 *
 * @param {Array<object>} statuses - `/repos/{repo}/commits/{sha}/statuses` rows
 * @param {{owner: string, headTree: string}} expected
 * @returns {{attestation: {tree: string, stages: string[], os: string, node: number, creator: string, createdAt: string}|null, reason: string}}
 */
export function selectAttestation(statuses, { owner, headTree }) {
  if (!Array.isArray(statuses)) return { attestation: null, reason: 'statuses unreadable' };
  const candidates = statuses
    .filter((status) => status?.context === PREGATE_STATUS_CONTEXT)
    .sort((a, b) => String(b?.created_at ?? '').localeCompare(String(a?.created_at ?? '')));
  if (candidates.length === 0) return { attestation: null, reason: `no "${PREGATE_STATUS_CONTEXT}" status on the head` };
  const newest = candidates[0];
  if (newest?.state !== 'success') {
    const detail = typeof newest?.description === 'string' && newest.description ? ` (${newest.description.slice(0, 80)})` : '';
    return { attestation: null, reason: `newest pregate status is ${newest?.state ?? 'unknown'}, not success${detail}` };
  }
  const creator = newest?.creator?.login;
  if (!owner || creator !== owner) {
    return { attestation: null, reason: `newest pregate status was created by ${creator ? `"${creator}"` : 'an unknown actor'}, not the repository owner` };
  }
  const parsed = parseAttestation(newest.description);
  if (!parsed) return { attestation: null, reason: 'newest pregate status has an unreadable description' };
  if (!TREE_RE.test(headTree ?? '') || parsed.tree !== headTree) {
    return { attestation: null, reason: `attested tree ${parsed.tree.slice(0, 12)} is not the head tree ${String(headTree ?? '').slice(0, 12) || '(unknown)'}` };
  }
  return { attestation: { ...parsed, creator, createdAt: String(newest.created_at ?? '') }, reason: `attested by ${creator} at ${newest.created_at} on ${parsed.os}/node ${parsed.node}` };
}