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
JavaScript ai-agentsdashboarddeveloper-toolsdigital-twinquantified-selfsecond-brainself-hostedtailscale
Run CI's build, smoke, browser and DB suites from pregate and leave a receipt
[._.]/ Adam Eivy6671eb4c6cf4
diff --git a/scripts/lib/pregateReport.js b/scripts/lib/pregateReport.jsnew file mode 100644index 0000000000..5f8c67ed82--- /dev/null+++ b/scripts/lib/pregateReport.js@@ -0,0 +1,112 @@+/**+ * 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 { 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';++export const PREGATE_REPORT_VERSION = 1;++/**+ * 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 });+ }+}++/**+ * 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,+}) {+ const stageRecords = stages.map(({ name, suite, command, status, durationMs, exitCode = null, signal = null }) => ({+ name, suite, command, status, durationMs, exitCode, signal,+ }));+ const passed = stageRecords.length > 0 && stageRecords.every((stage) => stage.status === 'passed');+ return {+ version: PREGATE_REPORT_VERSION,+ startedAt,+ finishedAt,+ passed,+ treeStable: tree === treeAfterRun,+ base,+ head,+ tree,+ treeAfterRun,+ runtime,+ options,+ plan: {+ full: plan.full,+ 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,+ 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;+}diff --git a/scripts/lib/pregateResources.js b/scripts/lib/pregateResources.jsnew file mode 100644index 0000000000..29b6ea9955--- /dev/null+++ b/scripts/lib/pregateResources.js@@ -0,0 +1,135 @@+/**+ * Prerequisite probes and stage environments for the resource suites pregate+ * runs locally: the serial Postgres suite and the cross-workspace browser+ * suites. Loaded by `scripts/pregate.js` only when a plan selects one of them,+ * because this module reaches installed packages (`pg`, `playwright-core`) and+ * server modules that a bare checkout does not have.+ *+ * A probe answers "can this machine honestly run the suite CI would run"; it+ * never substitutes for the suite. A failed probe leaves the suite reported+ * as not covered, with the remedy, rather than a green stage that ran nothing.+ */+import { existsSync } from 'node:fs';+import { createRequire } from 'node:module';+import { join } from 'node:path';+import databaseSettings from './databaseSettings.cjs';+import { parseEnvFile } from './envFile.js';+import { findFfmpeg } from '../../server/lib/ffmpeg.js';+import { browserSuiteBlockReason, chromeWithH264 } from '../../server/lib/browserSuiteGate.js';++/** The only database the DB stage may target; `server/lib/db.js` refuses the rest. */+export const TEST_DATABASE = 'portos_test';++// libpq routing variables that would redirect a connection away from the+// explicit PGHOST/PGPORT; dropped for the same reason scripts/setup-db.js drops them.+const ROUTING_ENV = ['PGHOSTADDR', 'PGSERVICE', 'PGSERVICEFILE', 'PGOPTIONS'];++/** The suite whose guard also needs a Chrome that decodes H.264. */+const H264_SUITE = 'server/services/musicVideo/documentRender.browser.test.js';++// The same candidate order every registered browser suite uses to find Chrome.+const CHROME_CANDIDATES = [+ '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',+ '/usr/bin/google-chrome', '/usr/bin/chromium', '/usr/bin/chromium-browser',+];+const CLIENT_BUNDLER_PACKAGES = ['vite', '@vitejs/plugin-react', '@tailwindcss/postcss'];++/**+ * Environment for the DB stages, pinned to `portos_test`.+ *+ * Host, port, user and password resolve the way `scripts/setup-db.js` resolves+ * them (exported env, then the checkout's saved `.env`, then the documented+ * defaults). The port follows PGMODE only when a mode is declared; otherwise it+ * is the native port `npm run test:db` already connects to. The database name+ * is not negotiable: both `PGDATABASE` and `PGTESTDATABASE` are forced, and+ * `TEST_DB_OK` is removed so an operator's shell cannot re-admit a non-test+ * database under the runner.+ */+export function testDatabaseStageEnv({ env = {}, saved = {} } = {}) {+ const settings = databaseSettings.resolveDatabaseSettings({ env, saved });+ const modeDeclared = Boolean(env.PGMODE || saved.PGMODE);+ const port = modeDeclared ? settings.port : settings.nativePort;+ return {+ PGHOST: settings.host,+ PGPORT: String(port),+ PGUSER: settings.user,+ PGPASSWORD: settings.password,+ PGDATABASE: TEST_DATABASE,+ PGTESTDATABASE: TEST_DATABASE,+ PORTOS_REQUIRE_DB: '1',+ TEST_DB_OK: undefined,+ ...Object.fromEntries(ROUTING_ENV.map((name) => [name, undefined])),+ };+}++/** The DB stage environment for a checkout, honoring its saved `.env`. */+export function resolveTestDatabaseStageEnv(repoRoot, env = process.env) {+ return testDatabaseStageEnv({ env, saved: parseEnvFile(join(repoRoot, '.env')) });+}++/**+ * Is a Postgres answering at the DB stage's endpoint? A missing `portos_test`+ * is fine (the provisioning stage creates it); an unreachable server, refused+ * credentials or an absent `pg` package are not. The reason stays free of+ * host and port so it can travel in the receipt; the endpoint is printed+ * separately for the operator.+ */+export async function probeTestDatabase(stageEnv, { repoRoot }) {+ const endpoint = `${stageEnv.PGHOST}:${stageEnv.PGPORT}/${TEST_DATABASE}`;+ let pg;+ try {+ pg = createRequire(join(repoRoot, 'server', 'package.json'))('pg');+ } catch (error) {+ return { ok: false, endpoint, reason: `pg package unavailable (${error.code ?? error.message})` };+ }+ const client = new pg.Client({+ host: stageEnv.PGHOST,+ port: Number(stageEnv.PGPORT),+ user: stageEnv.PGUSER,+ password: stageEnv.PGPASSWORD,+ database: TEST_DATABASE,+ connectionTimeoutMillis: 5000,+ });+ try {+ await client.connect();+ await client.query('SELECT 1');+ return { ok: true, endpoint, provision: false };+ } catch (error) {+ // 3D000: the database does not exist yet — `npm run setup:db:test` creates it.+ if (error.code === '3D000') return { ok: true, endpoint, provision: true };+ return { ok: false, endpoint, reason: `Postgres not reachable (${error.code ?? error.message})` };+ } finally {+ await client.end().catch(() => {});+ }+}++/**+ * Discover what the selected browser suites' `canRun` guards will look for —+ * Chrome, ffmpeg, the client bundler and, for the document renderer, H.264+ * decode — and return the guards' own wording when something is missing.+ */+export async function probeBrowserPrerequisites(files, { repoRoot, env = process.env }) {+ const requireServer = createRequire(join(repoRoot, 'server', 'package.json'));+ let bundledChrome;+ try {+ bundledChrome = requireServer('playwright-core').chromium.executablePath();+ } catch (error) {+ if (error.code !== 'MODULE_NOT_FOUND') throw error;+ }+ const chrome = [env.CHROME_PATH, bundledChrome, ...CHROME_CANDIDATES].find((path) => path && existsSync(path));+ let bundler;+ try {+ const requireClient = createRequire(join(repoRoot, 'client', 'package.json'));+ bundler = CLIENT_BUNDLER_PACKAGES.map((name) => requireClient.resolve(name));+ } catch (error) {+ if (error.code !== 'MODULE_NOT_FOUND') throw error;+ }+ const prerequisites = {+ Chrome: chrome,+ ffmpeg: await findFfmpeg(),+ 'client workspace dependencies': bundler,+ };+ if (files.includes(H264_SUITE)) prerequisites['Chrome with H.264'] = await chromeWithH264(chrome);+ const reason = browserSuiteBlockReason(prerequisites);+ return reason === null ? { ok: true, chrome } : { ok: false, reason };+}diff --git a/scripts/pregate.js b/scripts/pregate.jsindex f0c712e474..3a1b859b0b 100644--- a/scripts/pregate.js+++ b/scripts/pregate.js@@ -12,24 +12,37 @@* a log. They are all static and take seconds to answer here.** This runs CI's hidden-content scan and hands the SAME planner's plan to the- * SAME runners (`run-ci-lint.js`, `run-ci-tests.js`), so a green pregate means those Linux- * jobs are green for the same reasons — never a second, drifting opinion about- * which tests matter.+ * SAME runners (`run-ci-lint.js`, `run-ci-tests.js`, the client build, the+ * boot smoke, the browser suites and the serial `portos_test` suite), so a+ * green pregate means the Linux jobs are green for the same reasons — never+ * a second, drifting opinion about which tests matter. Stages run in CI's+ * dependency order, with the DB suite last and alone: it is serial and its+ * per-case budgets assume no concurrent suite (docs/CONTRIBUTING.md).** node scripts/pregate.js [--base <ref>] [--full] [--skip-lint] [--plan-only]+ * [--skip-db] [--skip-browser] [--skip-build] [--skip-smoke]*- * --base <ref> compare against <ref> instead of the remote default branch- * --full actually run the complete suite when the plan demands it- * (without this, a full plan runs the always-run guards only)- * --skip-lint skip linting in both client and server workspaces- * --plan-only print the plan and the stages, run nothing+ * --base <ref> compare against <ref> instead of the remote default branch+ * --full actually run the complete suite when the plan demands it+ * (without this, a full plan runs the always-run guards only+ * and reports the resource suites as not run)+ * --skip-lint skip linting in both client and server workspaces+ * --skip-db, --skip-browser, --skip-build, --skip-smoke+ * leave that suite to CI; it is reported as not run+ * --plan-only print the plan and the stages, run nothing*- * What it deliberately does NOT cover, because each needs a resource this- * checkout does not have: the DB suites (a provisioned `portos_test` —- * `npm run setup:db:test && npm run test:db`), the Windows job (a Windows- * runner), the Linux worker-containment job (bubblewrap namespaces), and the- * client build / boot smoke. The summary names the ones the- * plan flagged so they are a decision rather than a surprise.+ * A resource suite whose prerequisite this machine lacks (no reachable test+ * Postgres; no Chrome, ffmpeg or client bundler) is reported the same way, with+ * the remedy, and the run continues. The summary and the receipt both name+ * every suite that was NOT run, so a green result never claims a suite it+ * skipped. The Windows job and the Linux worker-containment job (bubblewrap+ * namespaces) are the suites only CI can prove.+ *+ * The receipt (`.cache/pregate/report.json`, see scripts/lib/pregateReport.js)+ * records the plan, each stage's outcome and duration, the skipped suites, the+ * base and HEAD commits, and the hash of the exact working tree validated —+ * untracked and uncommitted files included — so a later attestation can match+ * it to the commit that ships.*/import { spawn, spawnSync } from 'child_process';@@ -38,30 +51,65 @@ import { constants } from 'os';import { execFileSync } from 'child_process';import { dirname, join } from 'path';import { fileURLToPath } from 'url';+import { prepareWindowsSafeSpawn, resolveWindowsExecutable } from '../server/lib/aiToolkit/internal/windowsSafeSpawn.js';import { ALWAYS_RUN_TESTS, structuralTestsFor } from './ci-test-plan.js';import { assertNodeVersion } from './checkNodeVersion.js';import { isDirectlyInvoked } from './lib/directInvocation.js';import { needsBrowserFidelity } from './lib/browserFidelity.js';+import { buildPregateReport, PREGATE_REPORT_PATH, validatedTreeHash, writePregateReport } from './lib/pregateReport.js';import { dependencyConsistencyProblems } from './lib/workspaceDependencies.js';const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');+const IS_WIN32 = process.platform === 'win32';/**- * Suites the plan can request that this machine cannot honestly run.- *- * Keyed by the plan field, valued by what the operator would have to run- * instead. Reported rather than silently dropped: a pregate that stayed quiet- * about a DB-risk diff would read as "CI is covered" while the one suite that- * can destroy real data went unmentioned.+ * Suites CI runs that a local run may have to leave to CI, each valued by what+ * the operator can do about it. Reported rather than silently dropped: a+ * pregate that stayed quiet about a DB-risk diff would read as "CI is covered"+ * while the one suite that can destroy real data went unmentioned.*/export const UNCOVERED_SUITES = Object.freeze({- db: 'npm run setup:db:test && npm run test:db (never against the real `portos` database)',- windows: 'a Windows runner — no local equivalent; CI is the only proof',- linuxContainment: 'a Linux host with bubblewrap: PORTOS_REQUIRE_LINUX_CONTAINMENT=1 npm test --prefix server -- --run <LINUX_CONTAINMENT_TESTS>',- build: 'npm run build',+ db: 'needs a reachable test Postgres: npm run setup:db:test && npm run test:db (never against the real `portos` database)',+ browser: 'needs Chrome, ffmpeg and the client bundler; run `npm run pregate --full` once they are installed',+ build: 'npm run build && npm run test --prefix client -- ApiExplorer.bundle',smoke: 'npm run smoke',+ windows: 'CI is the only proof',+ linuxContainment: 'a Linux host with bubblewrap: PORTOS_REQUIRE_LINUX_CONTAINMENT=1 npm test --prefix server -- --run <LINUX_CONTAINMENT_TESTS>',});+/** Does the plan select this suite at all? `browser` is a file list, the rest flags. */+export function suiteSelected(plan, suite) {+ return suite === 'browser' ? (plan.browser?.files?.length ?? 0) > 0 : Boolean(plan[suite]);+}++/**+ * Every suite CI would run that this run does not, with the reason.+ *+ * Pure. A `--skip-*` flag outranks a downgraded full plan, which outranks a+ * failed prerequisite probe (`prerequisites[suite].ok === false`), so the+ * reason names the operator's own choice first. Windows and the Linux+ * containment job are always here when selected: neither has a local runner.+ */+export function uncoveredSuites(plan, { options = {}, downgraded = false, prerequisites = {} } = {}) {+ const flags = { db: options.skipDb, browser: options.skipBrowser, build: options.skipBuild, smoke: options.skipSmoke };+ const uncovered = [];+ for (const suite of ['build', 'smoke', 'browser', 'db']) {+ if (!suiteSelected(plan, suite)) continue;+ let reason = null;+ if (flags[suite]) reason = `skipped by --skip-${suite}`;+ else if (downgraded) reason = 'full plan downgraded; pass --full to run it';+ else if (prerequisites[suite]?.ok === false) reason = `prerequisite missing: ${prerequisites[suite].reason}`;+ if (reason) uncovered.push({ suite, reason, remedy: UNCOVERED_SUITES[suite] });+ }+ if (suiteSelected(plan, 'windows')) {+ uncovered.push({ suite: 'windows', reason: 'a Windows runner has no local equivalent', remedy: UNCOVERED_SUITES.windows });+ }+ if (suiteSelected(plan, 'linuxContainment')) {+ uncovered.push({ suite: 'linuxContainment', reason: 'needs a Linux host with bubblewrap namespaces', remedy: UNCOVERED_SUITES.linuxContainment });+ }+ return uncovered;+}+/*** Plan lines for the cross-workspace browser selection CI consumes* (`browser_files`). PRs run the smoke profile; the `[fidelity]` cases run in@@ -88,51 +136,122 @@ export function pregateWorkerEnv(env) {return { ...env, PORTOS_PREGATE_MAX_WORKERS: env.PORTOS_PREGATE_MAX_WORKERS || PREGATE_DEFAULT_MAX_WORKERS };}+/**+ * The child environment for one stage. A stage value of `undefined` REMOVES+ * the variable (the DB stages drop `TEST_DB_OK` this way), which is the only+ * way an inherited escape hatch can be kept away from a runner.+ */+export function stageSpawnEnv(baseEnv, stageEnv) {+ const env = { ...pregateWorkerEnv(baseEnv) };+ for (const [name, value] of Object.entries(stageEnv)) {+ if (value === undefined) delete env[name];+ else env[name] = value;+ }+ return env;+}++/** Human spelling of a stage's command for plan output and the receipt. */+export function describeStageCommand(stage) {+ return stage.npm ? `npm ${stage.npm.join(' ')}` : `node scripts/${stage.script}${stage.args.length ? ` ${stage.args.join(' ')}` : ''}`;+}+/*** The ordered stages to run for a plan, each a spawnable command.*- * Pure, so the plan -> stage mapping is testable without spawning Vitest.- * The hidden-content scan always runs first, even if lint/tests select no work.+ * Pure, so the plan -> stage mapping is testable without spawning anything.+ * The hidden-content scan always runs first, even if lint/tests select no+ * work, and the shipped prompt-history guard (CI's `prompt-history` job: one+ * git-history read, seconds locally) follows it when selected. Order after+ * that follows CI's own dependency order: lint, unit tests, the client build+ * and its bundle pin, the boot smoke, the browser suites, and the DB suite+ * last and alone. `skip` holds the suites that stay with CI+ * (see `uncoveredSuites`); `databaseEnv` is the pinned `portos_test`+ * environment from scripts/lib/pregateResources.js.*/-export function resolvePlanStages(plan, { skipLint = false, baseSha } = {}) {+export function resolvePlanStages(plan, { skipLint = false, baseSha, skip = {}, databaseEnv = {} } = {}) {+ const base = baseSha ? { CI_BASE_SHA: baseSha } : {};const stages = [{name: 'hidden-content scan',+ suite: 'scan',script: 'scan-diff-hidden-content.js',args: ['--base', baseSha, '--worktree'],env: {},}];+ if (plan.promptHistory) {+ stages.push({ name: 'shipped prompt history', suite: 'prompt-history', script: 'migrations/check-shipped-prompt-history.js', args: [], env: {} });+ }+if (!skipLint && plan.lint.mode !== 'skip') {stages.push({name: 'client/server lint',+ suite: 'lint',script: 'run-ci-lint.js',args: [],env: { CI_LINT_MODE: plan.lint.mode, CI_LINT_FILES: JSON.stringify(plan.lint.files) },});}+ // Same env the Linux unit jobs set: the registered browser suites belong to+ // the browser stage below, and passing output stays signal-dense.+ const scopeEnv = { server: { PORTOS_CI_BROWSER_OWNER: 'unit', PORTOS_TEST_QUIET: '1' }, client: {} };['server', 'client'].forEach((scope) => {const scoped = plan[scope];if (scoped.mode === 'skip') return;stages.push({name: `${scope} tests`,+ suite: scope,script: 'run-ci-tests.js',args: [scope],env: {+ ...scopeEnv[scope],CI_TEST_MODE: scoped.mode,CI_TEST_FILES: JSON.stringify(scoped.files),CI_TEST_SOURCES: JSON.stringify(scoped.sources),// Same base the planner just used. The import-growth guard fails// closed without it; omitting it here would make pregate compare// against a different ref than CI.- ...(baseSha ? { CI_BASE_SHA: baseSha } : {}),+ ...base,},});});- // CI's `prompt-history` job: one git-history read, seconds locally.- if (plan.promptHistory) {- stages.push({ name: 'shipped prompt history', script: 'migrations/check-shipped-prompt-history.js', args: [], env: {} });+ if (plan.build && !skip.build) {+ stages.push(+ { name: 'client build', suite: 'build', npm: ['run', 'build', '--prefix', 'client'], args: [], env: {} },+ // The Scalar-removal pin only sees dist/ after a real build.+ { name: 'API Explorer bundle pin', suite: 'build', npm: ['run', 'test', '--prefix', 'client', '--', 'ApiExplorer.bundle'], args: [], env: {} },+ );+ }++ if (plan.smoke && !skip.smoke) {+ stages.push({ name: 'boot smoke', suite: 'smoke', script: 'smoke-boot.js', args: [], env: {} });+ }++ if (suiteSelected(plan, 'browser') && !skip.browser) {+ stages.push({+ name: 'browser suites',+ suite: 'browser',+ script: 'run-ci-tests.js',+ args: ['server'],+ env: {+ CI_TEST_MODE: 'files',+ CI_TEST_FILES: JSON.stringify(plan.browser.files),+ CI_TEST_SOURCES: '[]',+ // PRs run the smoke profile; the guards fail closed instead of skipping.+ PORTOS_BROWSER_TEST_PROFILE: 'smoke',+ PORTOS_REQUIRE_BROWSER_SUITES: '1',+ PORTOS_TEST_QUIET: '1',+ ...base,+ },+ });+ }++ if (plan.db && !skip.db) {+ stages.push(+ { name: 'DB provision (portos_test)', suite: 'db', npm: ['run', 'setup:db:test', '--prefix', 'server'], args: [], env: databaseEnv },+ { name: 'DB suite (portos_test)', suite: 'db', npm: ['run', 'test:db:ci', '--prefix', 'server'], args: [], env: databaseEnv },+ );}return stages;@@ -145,7 +264,8 @@ export function resolvePlanStages(plan, { skipLint = false, baseSha } = {}) {* correct there and unusable here — the complete suite is far longer than* anyone runs before a push, so the honest local default is the subset that* catches always-run and diff-selected structural guards, plus a line saying- * what was dropped. `--full` opts back in.+ * what was dropped. The resource flags stay as the planner set them so the+ * summary can still name what CI will run; `--full` opts back in.*/export function downgradeFullPlan(plan, trackedFiles, changedFiles = []) {const tracked = new Set(trackedFiles);@@ -226,16 +346,26 @@ function defaultBaseRef() {}export const USAGE = `Usage: node scripts/pregate.js [--base <ref>] [--full] [--skip-lint] [--plan-only]+ [--skip-db] [--skip-browser] [--skip-build] [--skip-smoke]++ --base <ref> compare against <ref> instead of the remote default branch+ --full run the complete suite when the plan demands it+ --skip-lint skip linting in both client and server workspaces+ --skip-db leave the portos_test DB suite to CI (reported as not run)+ --skip-browser leave the cross-workspace browser suites to CI (reported as not run)+ --skip-build leave the client build and its bundle pin to CI (reported as not run)+ --skip-smoke leave the server boot smoke to CI (reported as not run)+ --plan-only print the plan and stages without running them+ -h, --help display this usage`;- --base <ref> compare against <ref> instead of the remote default branch- --full run the complete suite when the plan demands it- --skip-lint skip linting in both client and server workspaces- --plan-only print the plan and stages without running them- -h, --help display this usage`;+const SKIP_FLAGS = { '--skip-db': 'skipDb', '--skip-browser': 'skipBrowser', '--skip-build': 'skipBuild', '--skip-smoke': 'skipSmoke' };/** Parse argv before doing any Git inspection or starting a child process. */export function parseArgs(argv) {- const options = { base: null, full: false, skipLint: false, planOnly: false, help: false };+ const options = {+ base: null, full: false, skipLint: false, planOnly: false, help: false,+ skipDb: false, skipBrowser: false, skipBuild: false, skipSmoke: false,+ };for (let index = 0; index < argv.length; index += 1) {const flag = argv[index];switch (flag) {@@ -251,21 +381,33 @@ export function parseArgs(argv) {case '--plan-only': options.planOnly = true; break;case '--help':case '-h': options.help = true; break;- default: throw new Error(`Unknown option: ${flag}.`);+ default:+ if (SKIP_FLAGS[flag]) { options[SKIP_FLAGS[flag]] = true; break; }+ throw new Error(`Unknown option: ${flag}.`);}}return options;}+/** Spawn target for a stage: a repo script under node, or npm itself. */+function stageSpawn(stage, env) {+ if (!stage.npm) return { command: process.execPath, args: [join(REPO_ROOT, 'scripts', stage.script), ...stage.args] };+ // A bare `npm` is a `.cmd` shim on Windows; resolve and wrap it the way every+ // other npm spawn in this tree does (server/lib/bufferedSpawn.js).+ return prepareWindowsSafeSpawn(resolveWindowsExecutable('npm', IS_WIN32, env) || 'npm', stage.npm, IS_WIN32);+}+/** Wait asynchronously so owner signals can be attributed during a stage. */function runStage(stage) {return new Promise((resolve) => {- const child = spawn(process.execPath, [join(REPO_ROOT, 'scripts', stage.script), ...stage.args], {+ const env = stageSpawnEnv(process.env, stage.env);+ const { command, args } = stageSpawn(stage, env);+ const child = spawn(command, args, {cwd: REPO_ROOT,stdio: 'inherit',- env: { ...pregateWorkerEnv(process.env), ...stage.env },+ env,// A separate group lets cancellation reach only this stage's descendants.- detached: process.platform !== 'win32',+ detached: !IS_WIN32,});const handlers = new Map();const cleanup = () => {@@ -277,7 +419,7 @@ function runStage(stage) {writeSync(2, `❌ Pregate incomplete: stage="${stage.name}" owner_pid=${process.pid} child_pid=${child.pid ?? 'unavailable'} received_signal=${signal}.\n`);cleanup();try {- if (process.platform === 'win32') child.kill(signal);+ if (IS_WIN32) child.kill(signal);else if (child.pid) process.kill(-child.pid, signal);} catch (error) {if (error.code !== 'ESRCH') writeSync(2, `❌ Stage cancellation failed: ${error.code ?? 'unknown'}.\n`);@@ -298,6 +440,40 @@ function runStage(stage) {});}+const formatDuration = (ms) => (ms >= 60_000 ? `${(ms / 60_000).toFixed(1)}m` : `${(ms / 1000).toFixed(1)}s`);++function announceUncovered(uncovered) {+ uncovered.forEach(({ suite, reason, remedy }) => {+ console.log(`ℹ️ CI will also run: ${suite} — not run here (${reason}); ${remedy}`);+ });+}++/** Probe what the selected resource suites need; a failed probe keeps that suite with CI. */+async function probeResourceSuites(plan, { options, downgraded }) {+ const prerequisites = {};+ let databaseEnv = {};+ const wants = (suite, flag) => suiteSelected(plan, suite) && !flag && !downgraded;+ const wantsDb = wants('db', options.skipDb);+ const wantsBrowser = wants('browser', options.skipBrowser);+ if (!wantsDb && !wantsBrowser) return { prerequisites, databaseEnv };+ // Reaches `pg`, `playwright-core` and server modules: loaded only when needed.+ const resources = await import('./lib/pregateResources.js');+ if (wantsDb) {+ databaseEnv = resources.resolveTestDatabaseStageEnv(REPO_ROOT, process.env);+ prerequisites.db = await resources.probeTestDatabase(databaseEnv, { repoRoot: REPO_ROOT });+ if (prerequisites.db.ok) {+ console.log(`🗄️ Test database ${prerequisites.db.endpoint} ${prerequisites.db.provision ? 'will be provisioned' : 'is reachable'}.`);+ } else {+ console.warn(`⏭️ Test database ${prerequisites.db.endpoint}: ${prerequisites.db.reason}.`);+ }+ }+ if (wantsBrowser) {+ prerequisites.browser = await resources.probeBrowserPrerequisites(plan.browser.files, { repoRoot: REPO_ROOT });+ if (!prerequisites.browser.ok) console.warn(`⏭️ Browser suites: ${prerequisites.browser.reason}.`);+ }+ return { prerequisites, databaseEnv };+}+async function main() {let options;try {@@ -373,25 +549,30 @@ async function main() {smoke: raw.smoke,promptHistory: raw.prompt_history,linuxContainment: raw.linux_containment,+ suiteReasons: JSON.parse(raw.suite_reasons ?? '{}'),};console.log(`📋 ${raw.changed_files.length} changed file(s) — ${plan.reason}.`);- if (plan.full && !options.full) {+ const downgraded = plan.full && !options.full;+ if (downgraded) {plan = downgradeFullPlan(plan, git(['ls-files']).split('\n').filter(Boolean), changedFiles);- console.log('⚠️ CI will run the FULL suite for this diff — running always-run and diff-selected structural guards only. Pass --full to run everything.');+ console.log('⚠️ CI will run the FULL suite for this diff — running always-run and diff-selected structural guards only. Pass --full to run everything, including the build, smoke, browser and DB suites.');}- const stages = resolvePlanStages(plan, { skipLint: options.skipLint, baseSha });- const uncovered = Object.keys(UNCOVERED_SUITES).filter((key) => plan[key]);- uncovered.forEach((key) => {- console.log(`ℹ️ CI will also run: ${key} — not covered here; run ${UNCOVERED_SUITES[key]}`);- });+ describeBrowserSelection(plan.browser.files).forEach((line) => console.log(line));- describeBrowserSelection(plan.browser?.files ?? []).forEach((line) => console.log(line));+ /** Stages for the suites that stay here, after the uncovered ones are announced. */+ const planStages = (prerequisites, databaseEnv) => {+ const uncovered = uncoveredSuites(plan, { options, downgraded, prerequisites });+ announceUncovered(uncovered);+ const skip = Object.fromEntries(uncovered.map(({ suite }) => [suite, true]));+ return { uncovered, stages: resolvePlanStages(plan, { skipLint: options.skipLint, baseSha, skip, databaseEnv }) };+ };if (options.planOnly) {- stages.forEach((stage) => {- console.log(`• ${stage.name}: ${stage.script} ${stage.args.join(' ')}`);+ // Prerequisites are probed at run time; here every selected suite is a stage.+ planStages({}, {}).stages.forEach((stage) => {+ console.log(`• ${stage.name}: ${describeStageCommand(stage)}`);});process.exit(0);}@@ -409,25 +590,99 @@ async function main() {}console.log('✅ Dependency consistency preflight passed (installed package versions match workspace locks).');- for (const stage of stages) {- console.log(`▶️ ${stage.name}`);- const result = await runStage(stage);- if (result.error) {- console.error(`❌ ${stage.name} could not start: ${result.error.message}`);- process.exit(1);- }- if (result.signal) {- console.error(`❌ Pregate incomplete: stage="${stage.name}" owner_pid=${process.pid} child_pid=${result.pid} child_signal=${result.signal}.`);- process.exit(constants.signals[result.signal] ? 128 + constants.signals[result.signal] : 1);+ const { prerequisites, databaseEnv } = await probeResourceSuites(plan, { options, downgraded });+ const { uncovered, stages } = planStages(prerequisites, databaseEnv);++ const headSha = git(['rev-parse', 'HEAD']);+ // The receipt hashes the tree the stages validate. It is taken once the+ // hidden-content scan has passed: that scan is what proves every untracked+ // path is readable (an uncommitted nested repository fails both, and the+ // scan's diagnosis is the one the operator should read).+ let tree = null;+ const hashTree = () => {+ if (tree !== null) return;+ tree = validatedTreeHash(REPO_ROOT);+ console.log(`🌳 Validating working tree ${tree.slice(0, 12)} at HEAD ${headSha.slice(0, 9)}.`);+ };++ const startedAt = new Date().toISOString();+ const results = stages.map((stage) => ({ ...stage, command: describeStageCommand(stage), status: 'not-run', durationMs: 0 }));+ let exitCode = 0;+ let failure = null;+ for (const result of results) {+ if (failure) break;+ if (result.suite !== 'scan') {+ try {+ hashTree();+ } catch (error) {+ failure = `❌ Cannot hash the working tree for the receipt: ${error.message}`;+ exitCode = 2;+ break;+ }}- if (result.status !== 0) {- console.error(`❌ ${stage.name} failed — fix it before pushing (CI would fail the same way).`);- process.exit(result.status ?? 1);+ console.log(`▶️ ${result.name}`);+ const started = Date.now();+ const outcome = await runStage(result);+ result.durationMs = Date.now() - started;+ if (outcome.error) {+ result.status = 'failed';+ failure = `❌ ${result.name} could not start: ${outcome.error.message}`;+ exitCode = 1;+ } else if (outcome.signal) {+ result.status = 'failed';+ result.signal = outcome.signal;+ failure = `❌ Pregate incomplete: stage="${result.name}" owner_pid=${process.pid} child_pid=${outcome.pid} child_signal=${outcome.signal}.`;+ exitCode = constants.signals[outcome.signal] ? 128 + constants.signals[outcome.signal] : 1;+ } else if (outcome.status !== 0) {+ result.status = 'failed';+ result.exitCode = outcome.status;+ failure = `❌ ${result.name} failed after ${formatDuration(result.durationMs)} — fix it before pushing (CI would fail the same way).`;+ exitCode = outcome.status ?? 1;+ } else {+ result.status = 'passed';+ result.exitCode = 0;+ console.log(`✔️ ${result.name} passed in ${formatDuration(result.durationMs)}.`);}}- const caveat = uncovered.length > 0 ? ` (${uncovered.join(', ')} still only provable in CI)` : '';- console.log(`✅ Pregate passed: ${stages.map((stage) => stage.name).join(', ')}${caveat}.`);+ let treeAfterRun = null;+ try {+ if (!failure) hashTree();+ if (tree !== null) treeAfterRun = validatedTreeHash(REPO_ROOT);+ } catch (error) {+ failure ??= `❌ Cannot hash the working tree for the receipt: ${error.message}`;+ if (exitCode === 0) exitCode = 2;+ }+ const report = buildPregateReport({+ plan,+ options: { base: baseRef, full: options.full, skipLint: options.skipLint, skipDb: options.skipDb, skipBrowser: options.skipBrowser, skipBuild: options.skipBuild, skipSmoke: options.skipSmoke },+ base: { ref: baseRef, sha: baseSha },+ head: { sha: headSha },+ tree,+ treeAfterRun,+ stages: results,+ skipped: uncovered,+ runtime: { node: process.version, platform: process.platform, arch: process.arch, maxWorkers: pregateWorkerEnv(process.env).PORTOS_PREGATE_MAX_WORKERS },+ startedAt,+ finishedAt: new Date().toISOString(),+ });+ writePregateReport(REPO_ROOT, report);+ if (tree !== null && !report.treeStable) {+ console.warn(`⚠️ The working tree changed while pregate ran (${tree.slice(0, 12)} → ${treeAfterRun?.slice(0, 12) ?? 'unhashable'}); the receipt covers the tree it started with.`);+ }++ if (failure) {+ console.error(failure);+ console.error(`📄 Receipt: ${PREGATE_REPORT_PATH}`);+ process.exit(exitCode);+ }++ const ran = results.map((stage) => stage.name).join(', ');+ console.log(`✅ Pregate passed: ${ran}.`);+ if (uncovered.length > 0) {+ console.log(`⚠️ Not run here (CI still proves them): ${uncovered.map(({ suite, reason }) => `${suite} (${reason})`).join(', ')}.`);+ }+ console.log(`📄 Receipt: ${PREGATE_REPORT_PATH}`);}if (isDirectlyInvoked(import.meta.url)) {diff --git a/scripts/pregate.test.js b/scripts/pregate.test.jsindex ecd65005b3..4a0ccd8cfc 100644--- a/scripts/pregate.test.js+++ b/scripts/pregate.test.js@@ -24,12 +24,18 @@ import {collectPregateChangedFiles,resolvePlanStages,describeBrowserSelection,+ describeStageCommand,downgradeFullPlan,parseArgs,pregateWorkerEnv,+ stageSpawnEnv,+ suiteSelected,+ uncoveredSuites,UNCOVERED_SUITES,unmergedIndexPaths,} from './pregate.js';+import { buildPregateReport, PREGATE_REPORT_PATH, validatedTreeHash } from './lib/pregateReport.js';+import { probeTestDatabase, TEST_DATABASE, testDatabaseStageEnv } from './lib/pregateResources.js';import { BROWSER_SUITES } from './lib/browserSuites.js';import { BROWSER_FIDELITY_FILES } from './lib/browserTestProfiles.js';@@ -42,13 +48,21 @@ const planWith = (overrides = {}) => ({server: { mode: 'files', files: ['server/lib/a.test.js'], sources: [] },client: { mode: 'skip', files: [], sources: [] },lint: { mode: 'skip', files: [] },+ browser: { files: [] },db: false,windows: false,build: false,smoke: false,+ promptHistory: false,+ linuxContainment: false,...overrides,});+const DEFAULT_OPTIONS = {+ base: null, full: false, skipLint: false, planOnly: false, help: false,+ skipDb: false, skipBrowser: false, skipBuild: false, skipSmoke: false,+};+describe('resolvePlanStages', () => {it('runs only the scopes the plan selected', () => {const stages = resolvePlanStages(planWith());@@ -62,6 +76,8 @@ describe('resolvePlanStages', () => {expect(stage.script).toBe('run-ci-tests.js');expect(stage.args).toEqual(['server']);expect(stage.env).toEqual({+ PORTOS_CI_BROWSER_OWNER: 'unit',+ PORTOS_TEST_QUIET: '1',CI_TEST_MODE: 'related',CI_TEST_FILES: '["server/lib/a.test.js"]',CI_TEST_SOURCES: '["server/lib/a.js"]',@@ -75,7 +91,7 @@ describe('resolvePlanStages', () => {}), { baseSha: 'resolved-base' });expect(stages.map((stage) => stage.name)).toEqual(['hidden-content scan', 'client/server lint', 'server tests', 'client tests']);expect(stages[0]).toEqual({- name: 'hidden-content scan', script: 'scan-diff-hidden-content.js',+ name: 'hidden-content scan', suite: 'scan', script: 'scan-diff-hidden-content.js',args: ['--base', 'resolved-base', '--worktree'], env: {},});expect(stages[1].env).toEqual({ CI_LINT_MODE: 'files', CI_LINT_FILES: '["client/src/App.jsx"]' });@@ -84,11 +100,13 @@ describe('resolvePlanStages', () => {}});- it('runs the shipped prompt-history guard only when the plan selects it', () => {+ it('runs the shipped prompt-history guard right after the scan, only when the plan selects it', () => {expect(resolvePlanStages(planWith({ promptHistory: false })).map((stage) => stage.name)).not.toContain('shipped prompt history');- expect(resolvePlanStages(planWith({ promptHistory: true })).at(-1)).toEqual({- name: 'shipped prompt history', script: 'migrations/check-shipped-prompt-history.js', args: [], env: {},+ const stages = resolvePlanStages(planWith({ promptHistory: true, lint: { mode: 'full', files: [] } }));+ expect(stages.map((stage) => stage.name)).toEqual(['hidden-content scan', 'shipped prompt history', 'client/server lint', 'server tests']);+ expect(stages[1]).toEqual({+ name: 'shipped prompt history', suite: 'prompt-history', script: 'migrations/check-shipped-prompt-history.js', args: [], env: {},});});@@ -135,7 +153,8 @@ describe('pregate hidden-content invocation', () => {'scripts/pregate.js', 'scripts/checkNodeVersion.js', 'scripts/scan-diff-hidden-content.js','scripts/ci-test-plan.js', 'scripts/ci-base-sha.js', 'server/lib/staticImportGraph.js','scripts/lib/directInvocation.js', 'scripts/lib/browserFidelity.js', 'scripts/lib/browserTestProfiles.js', 'scripts/lib/githubOutput.js', 'scripts/lib/dbTestFiles.js',- 'scripts/lib/browserSuites.js', 'scripts/lib/workspaceDependencies.js', 'scripts/migrations/shippedPromptHistory.js',+ 'scripts/lib/browserSuites.js', 'scripts/lib/workspaceDependencies.js', 'scripts/lib/pregateReport.js',+ 'scripts/migrations/shippedPromptHistory.js', 'server/lib/aiToolkit/internal/windowsSafeSpawn.js','server/lib/diffHiddenContentScan.js', 'server/lib/modelAbuseGuard.js','server/lib/textUtils.js',]) {@@ -143,7 +162,8 @@ describe('pregate hidden-content invocation', () => {copyFileSync(join(REPO_ROOT, path), join(root, path));}write('package.json', '{"type":"module"}\n');- write('.gitignore', 'node_modules\n');+ // The receipt lands under /.cache/, which the real repository ignores too.+ write('.gitignore', 'node_modules\n/.cache/\n');for (const workspace of ['', 'client', 'server', 'autofixer']) {mkdirSync(join(root, workspace, 'node_modules'), { recursive: true });write(join(workspace, 'package-lock.json'), JSON.stringify({ packages: { '': {} } }));@@ -342,20 +362,48 @@ describe('pregate hidden-content invocation', () => {const before = snapshot();const result = run('--plan-only', '--skip-lint');expect(result.status, result.stderr).toBe(0);- expect(result.stdout).toContain(`hidden-content scan: scan-diff-hidden-content.js --base ${base} --worktree`);+ expect(result.stdout).toContain(`hidden-content scan: node scripts/scan-diff-hidden-content.js --base ${base} --worktree`);expect(result.stdout).not.toContain('▶️');expect(result.stderr).toBe('');expect(snapshot()).toEqual(before);});- it('reports database validation for an excluded DB-only suite in a scoped working-tree plan', () => {+ it('plans the portos_test stages for a DB-only suite in a scoped working-tree plan', () => {mkdirSync(join(root, 'server/routes'), { recursive: true });write('server/routes/decks.db.test.js', "import { it } from 'vitest';\nit('db contract', () => {});\n");const result = run('--plan-only');expect(result.status, result.stderr).toBe(0);- expect(result.stdout).toContain('CI will also run: db');- expect(result.stdout).toContain('npm run test:db');+ expect(result.stdout).toContain('• DB provision (portos_test): npm run setup:db:test --prefix server');+ expect(result.stdout).toContain('• DB suite (portos_test): npm run test:db:ci --prefix server');+ expect(result.stdout).not.toContain('CI will also run: db');expect(result.stdout).not.toContain('FULL suite');++ const skipped = run('--plan-only', '--skip-db');+ expect(skipped.status, skipped.stderr).toBe(0);+ expect(skipped.stdout).toContain('CI will also run: db — not run here (skipped by --skip-db)');+ expect(skipped.stdout).not.toContain('DB suite (portos_test)');+ });++ it('writes a receipt whose tree hash matches a commit of the validated state', () => {+ write(trackedPath, `${clean}edited\n`);+ write('docs/new note.md', 'untracked addition\n');+ const result = run('--skip-lint');+ expect(result.status, result.stderr).toBe(0);+ expect(result.stdout).toContain(`Receipt: ${PREGATE_REPORT_PATH}`);+ const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));+ expect(report.passed).toBe(true);+ expect(report.treeStable).toBe(true);+ expect(report.head.sha).toBe(git('rev-parse', 'HEAD'));+ expect(report.base.sha).toBe(base);+ expect(report.stages.map((stage) => [stage.name, stage.status])).toEqual([['hidden-content scan', 'passed']]);+ expect(report.stages[0]).not.toHaveProperty('env');+ expect(report.skipped).toEqual([]);+ expect(report.runtime).toMatchObject({ node: process.version, platform: process.platform });+ // The receipt itself is ignored, so committing exactly what was validated+ // reproduces the hashed tree.+ git('add', '--all');+ git('-c', 'user.name=Example Contributor', '-c', '[email protected]', '-c', 'commit.gpgsign=false', 'commit', '-qm', 'validated state');+ expect(git('rev-parse', 'HEAD^{tree}')).toBe(report.tree);});it('preserves binary, empty-file, and stdin-like path findings for untracked additions', () => {@@ -445,7 +493,13 @@ describe('downgradeFullPlan', () => {describe('parseArgs', () => {it('reads --base as a value, not a boolean', () => {expect(parseArgs(['--base', 'origin/release', '--full'])).toEqual({- base: 'origin/release', full: true, skipLint: false, planOnly: false, help: false,+ ...DEFAULT_OPTIONS, base: 'origin/release', full: true,+ });+ });++ it('accepts one skip flag per resource suite', () => {+ expect(parseArgs(['--skip-db', '--skip-browser', '--skip-build', '--skip-smoke'])).toEqual({+ ...DEFAULT_OPTIONS, skipDb: true, skipBrowser: true, skipBuild: true, skipSmoke: true,});});@@ -454,7 +508,7 @@ describe('parseArgs', () => {});it('defaults to a null base so the caller resolves the remote default branch', () => {- expect(parseArgs([])).toEqual({ base: null, full: false, skipLint: false, planOnly: false, help: false });+ expect(parseArgs([])).toEqual(DEFAULT_OPTIONS);});it('recognizes both help flags and rejects unknown flags or a missing base value', () => {@@ -485,11 +539,17 @@ describe('UNCOVERED_SUITES', () => {* stop appearing, and a DB-risk diff would leave here looking fully covered.*/it('names plan fields the planner actually emits', () => {- const plan = buildCiTestPlan([], { trackedFiles: [], forceFull: true, forceFullReason: 'test' });+ const plan = buildCiTestPlan([], { trackedFiles: BROWSER_SUITES, forceFull: true, forceFullReason: 'test' });Object.keys(UNCOVERED_SUITES).forEach((key) => {+ if (key === 'browser') {+ expect(Array.isArray(plan.browserFiles)).toBe(true);+ return;+ }expect(plan, `plan has no '${key}' field`).toHaveProperty(key);expect(typeof plan[key]).toBe('boolean');});+ const normalized = { ...plan, browser: { files: plan.browserFiles } };+ expect(Object.keys(UNCOVERED_SUITES).every((key) => suiteSelected(normalized, key))).toBe(true);});});@@ -624,7 +684,8 @@ describe('the gate end to end', () => {'scripts/pregate.js', 'scripts/checkNodeVersion.js', 'scripts/scan-diff-hidden-content.js','scripts/ci-test-plan.js', 'scripts/ci-base-sha.js', 'server/lib/staticImportGraph.js','scripts/lib/directInvocation.js', 'scripts/lib/browserFidelity.js', 'scripts/lib/browserTestProfiles.js', 'scripts/lib/githubOutput.js', 'scripts/lib/dbTestFiles.js',- 'scripts/lib/browserSuites.js', 'scripts/lib/workspaceDependencies.js', 'scripts/migrations/shippedPromptHistory.js',+ 'scripts/lib/browserSuites.js', 'scripts/lib/workspaceDependencies.js', 'scripts/lib/pregateReport.js',+ 'scripts/migrations/shippedPromptHistory.js', 'server/lib/aiToolkit/internal/windowsSafeSpawn.js','server/lib/diffHiddenContentScan.js', 'server/lib/modelAbuseGuard.js','server/lib/textUtils.js',]) {@@ -686,3 +747,264 @@ describe('describeBrowserSelection', () => {expect(out).toContain('Browser suites:');});});++describe('resource suite stages', () => {+ const fullPlan = planWith({+ lint: { mode: 'full', files: [] },+ client: { mode: 'files', files: ['client/src/App.test.jsx'], sources: [] },+ browser: { files: BROWSER_SUITES.slice(0, 2) },+ db: true, build: true, smoke: true, windows: true,+ });+ const databaseEnv = { PGDATABASE: TEST_DATABASE, TEST_DB_OK: undefined };++ it('orders every selected stage the way CI depends on them, DB suite last', () => {+ const stages = resolvePlanStages(fullPlan, { baseSha: 'base', databaseEnv });+ expect(stages.map((stage) => stage.name)).toEqual([+ 'hidden-content scan', 'client/server lint', 'server tests', 'client tests',+ 'client build', 'API Explorer bundle pin', 'boot smoke', 'browser suites',+ 'DB provision (portos_test)', 'DB suite (portos_test)',+ ]);+ expect(stages.map(describeStageCommand)).toEqual([+ 'node scripts/scan-diff-hidden-content.js --base base --worktree',+ 'node scripts/run-ci-lint.js',+ 'node scripts/run-ci-tests.js server',+ 'node scripts/run-ci-tests.js client',+ 'npm run build --prefix client',+ 'npm run test --prefix client -- ApiExplorer.bundle',+ 'node scripts/smoke-boot.js',+ 'node scripts/run-ci-tests.js server',+ 'npm run setup:db:test --prefix server',+ 'npm run test:db:ci --prefix server',+ ]);+ });++ it('gives the browser stage the exact env CI\'s browser job sets', () => {+ const browser = resolvePlanStages(fullPlan, { baseSha: 'base' }).find((stage) => stage.name === 'browser suites');+ expect(browser.env).toEqual({+ CI_TEST_MODE: 'files',+ CI_TEST_FILES: JSON.stringify(BROWSER_SUITES.slice(0, 2)),+ CI_TEST_SOURCES: '[]',+ PORTOS_BROWSER_TEST_PROFILE: 'smoke',+ PORTOS_REQUIRE_BROWSER_SUITES: '1',+ PORTOS_TEST_QUIET: '1',+ CI_BASE_SHA: 'base',+ });+ });++ it('hands both DB stages the pinned portos_test environment', () => {+ const dbStages = resolvePlanStages(fullPlan, { databaseEnv }).filter((stage) => stage.suite === 'db');+ expect(dbStages).toHaveLength(2);+ for (const stage of dbStages) {+ expect(stage.env).toBe(databaseEnv);+ expect(stage.npm).toContain('server');+ }+ });++ it('drops each skipped suite\'s stages and nothing else', () => {+ const names = (skip) => resolvePlanStages(fullPlan, { skip }).map((stage) => stage.suite);+ expect(names({ db: true })).not.toContain('db');+ expect(names({ browser: true })).not.toContain('browser');+ expect(names({ build: true })).not.toContain('build');+ expect(names({ smoke: true })).not.toContain('smoke');+ expect(names({ db: true, browser: true, build: true, smoke: true })).toEqual(['scan', 'lint', 'server', 'client']);+ expect(names({})).toEqual(['scan', 'lint', 'server', 'client', 'build', 'build', 'smoke', 'browser', 'db', 'db']);+ });++ it('plans no resource stage the planner did not select', () => {+ expect(resolvePlanStages(planWith(), { databaseEnv }).map((stage) => stage.suite)).toEqual(['scan', 'server']);+ });+});++describe('uncoveredSuites', () => {+ const selected = planWith({ browser: { files: [BROWSER_SUITES[0]] }, db: true, build: true, smoke: true, windows: true });++ it('reports only the CI-only jobs when every selected suite can run', () => {+ expect(uncoveredSuites(selected, { prerequisites: { db: { ok: true }, browser: { ok: true } } }))+ .toEqual([{ suite: 'windows', reason: 'a Windows runner has no local equivalent', remedy: UNCOVERED_SUITES.windows }]);+ expect(uncoveredSuites(planWith({ linuxContainment: true })))+ .toEqual([{ suite: 'linuxContainment', reason: 'needs a Linux host with bubblewrap namespaces', remedy: UNCOVERED_SUITES.linuxContainment }]);+ expect(uncoveredSuites(planWith())).toEqual([]);+ });++ it('keeps a suite with CI for a flag, a downgraded full plan, or a failed probe — in that precedence', () => {+ const flagged = uncoveredSuites(selected, { options: { skipDb: true, skipBuild: true }, downgraded: true });+ expect(flagged.map(({ suite, reason }) => [suite, reason])).toEqual([+ ['build', 'skipped by --skip-build'],+ ['smoke', 'full plan downgraded; pass --full to run it'],+ ['browser', 'full plan downgraded; pass --full to run it'],+ ['db', 'skipped by --skip-db'],+ ['windows', 'a Windows runner has no local equivalent'],+ ]);+ const probed = uncoveredSuites(selected, {+ prerequisites: {+ db: { ok: false, reason: 'Postgres not reachable (ECONNREFUSED)' },+ browser: { ok: false, reason: 'missing ffmpeg' },+ },+ });+ expect(probed.map(({ suite, reason }) => [suite, reason])).toEqual([+ ['browser', 'prerequisite missing: missing ffmpeg'],+ ['db', 'prerequisite missing: Postgres not reachable (ECONNREFUSED)'],+ ['windows', 'a Windows runner has no local equivalent'],+ ]);+ expect(probed.find(({ suite }) => suite === 'db').remedy).toBe(UNCOVERED_SUITES.db);+ });++ it('turns a failed probe into a skipped stage and a receipt that names it, never a green claim', () => {+ const prerequisites = { db: { ok: false, reason: 'Postgres not reachable (ECONNREFUSED)' } };+ const uncovered = uncoveredSuites(selected, { prerequisites, options: { skipBrowser: true, skipBuild: true, skipSmoke: true } });+ const skip = Object.fromEntries(uncovered.map(({ suite }) => [suite, true]));+ const stages = resolvePlanStages(selected, { skip });+ expect(stages.map((stage) => stage.suite)).toEqual(['scan', 'server']);+ const report = buildPregateReport({+ plan: selected, options: {}, base: { ref: 'origin/main', sha: 'b' }, head: { sha: 'h' }, tree: 't',+ stages: stages.map((stage) => ({ ...stage, command: describeStageCommand(stage), status: 'passed', durationMs: 1 })),+ skipped: uncovered, runtime: {}, startedAt: 's', finishedAt: 'f',+ });+ expect(report.passed).toBe(true);+ expect(report.skipped.map(({ suite }) => suite)).toEqual(['build', 'smoke', 'browser', 'db', 'windows']);+ expect(report.skipped.find(({ suite }) => suite === 'db').reason).toBe('prerequisite missing: Postgres not reachable (ECONNREFUSED)');+ });+});++describe('stageSpawnEnv', () => {+ it('applies stage values and removes the variables a stage sets to undefined', () => {+ const env = stageSpawnEnv({ TEST_DB_OK: '1', PGDATABASE: 'portos', KEEP: 'x' }, { TEST_DB_OK: undefined, PGDATABASE: 'portos_test' });+ expect(env).toEqual({ KEEP: 'x', PGDATABASE: 'portos_test', PORTOS_PREGATE_MAX_WORKERS: '4' });+ expect('TEST_DB_OK' in env).toBe(false);+ });+});++describe('testDatabaseStageEnv', () => {+ it('pins both database names to portos_test and strips the escape hatch and libpq routing', () => {+ const env = testDatabaseStageEnv({+ env: { PGDATABASE: 'portos', PGTESTDATABASE: 'other_test', TEST_DB_OK: '1', PGHOSTADDR: '192.0.2.10', PGSERVICE: 'x' },+ });+ expect(env.PGDATABASE).toBe('portos_test');+ expect(env.PGTESTDATABASE).toBe('portos_test');+ expect(env.PORTOS_REQUIRE_DB).toBe('1');+ expect(env).toHaveProperty('TEST_DB_OK', undefined);+ expect(env).toHaveProperty('PGHOSTADDR', undefined);+ expect(env).toHaveProperty('PGSERVICE', undefined);+ expect(env).toHaveProperty('PGSERVICEFILE', undefined);+ expect(env).toHaveProperty('PGOPTIONS', undefined);+ });++ it('resolves the endpoint like setup-db.js: exported env, then the saved .env, then defaults', () => {+ expect(testDatabaseStageEnv({})).toMatchObject({ PGHOST: 'localhost', PGPORT: '5432', PGUSER: 'portos', PGPASSWORD: 'portos' });+ expect(testDatabaseStageEnv({ env: { PGPORT: '6543' }, saved: { PGPORT: '7000', PGHOST: 'db.example.com' } }))+ .toMatchObject({ PGHOST: 'db.example.com', PGPORT: '6543' });+ // A declared Docker mode selects the Docker port; an undeclared mode keeps+ // the native port the plain `npm run test:db` already connects to.+ expect(testDatabaseStageEnv({ saved: { PGMODE: 'docker' } }).PGPORT).toBe('5561');+ expect(testDatabaseStageEnv({ saved: { PGMODE: 'docker', PGPORT_DOCKER: '5599' } }).PGPORT).toBe('5599');+ expect(testDatabaseStageEnv({ saved: { PGMODE: 'native', PGPORT: '5433' } }).PGPORT).toBe('5433');+ });+});++describe('probeTestDatabase', () => {+ it('reports an unreachable server as a missing prerequisite without the endpoint in the reason', async () => {+ const { createServer } = await import('node:net');+ // Bind then close a port so nothing answers there.+ const port = await new Promise((resolve) => {+ const server = createServer();+ server.listen(0, '127.0.0.1', () => {+ const { port: bound } = server.address();+ server.close(() => resolve(bound));+ });+ });+ const result = await probeTestDatabase(+ { PGHOST: '127.0.0.1', PGPORT: String(port), PGUSER: 'portos', PGPASSWORD: 'portos' },+ { repoRoot: REPO_ROOT },+ );+ expect(result.ok).toBe(false);+ expect(result.reason).toMatch(/^Postgres not reachable \(/);+ expect(result.reason).not.toContain(String(port));+ expect(result.endpoint).toBe(`127.0.0.1:${port}/portos_test`);+ });+});++describe('buildPregateReport', () => {+ const stage = (name, status, extra = {}) => ({ name, suite: 'server', command: 'node scripts/x.js', status, durationMs: 5, env: { SECRET: 'no' }, ...extra });++ it('keeps stage outcomes and skips, drops stage env, and derives passed/treeStable', () => {+ const report = buildPregateReport({+ plan: planWith({ suiteReasons: { server: 'why' } }),+ options: { full: false },+ base: { ref: 'origin/main', sha: 'b' },+ head: { sha: 'h' },+ tree: 'tree-a',+ treeAfterRun: 'tree-b',+ stages: [stage('a', 'passed', { exitCode: 0 }), stage('b', 'failed', { exitCode: 1 }), stage('c', 'not-run')],+ skipped: [{ suite: 'windows', reason: 'no local equivalent', remedy: 'CI', extra: 'dropped' }],+ runtime: { node: 'v1', platform: 'linux', arch: 'x64', maxWorkers: '3' },+ startedAt: 's',+ finishedAt: 'f',+ });+ expect(report.version).toBe(1);+ expect(report.passed).toBe(false);+ expect(report.treeStable).toBe(false);+ expect(report.stages).toEqual([+ { name: 'a', suite: 'server', command: 'node scripts/x.js', status: 'passed', durationMs: 5, exitCode: 0, signal: null },+ { name: 'b', suite: 'server', command: 'node scripts/x.js', status: 'failed', durationMs: 5, exitCode: 1, signal: null },+ { name: 'c', suite: 'server', command: 'node scripts/x.js', status: 'not-run', durationMs: 5, exitCode: null, signal: null },+ ]);+ expect(JSON.stringify(report)).not.toContain('SECRET');+ expect(report.skipped).toEqual([{ suite: 'windows', reason: 'no local equivalent', remedy: 'CI' }]);+ expect(report.plan.suiteReasons).toEqual({ server: 'why' });+ expect(report.plan.browser).toEqual({ files: [] });+ expect(report).toMatchObject({ base: { ref: 'origin/main', sha: 'b' }, head: { sha: 'h' }, tree: 'tree-a', treeAfterRun: 'tree-b', startedAt: 's', finishedAt: 'f' });+ });++ it('never passes an empty run and defaults the post-run tree to the validated one', () => {+ const report = buildPregateReport({+ plan: planWith(), options: {}, base: {}, head: {}, tree: 't', stages: [], skipped: [], runtime: {}, startedAt: 's', finishedAt: 'f',+ });+ expect(report.passed).toBe(false);+ expect(report.treeStable).toBe(true);+ });+});++describe('validatedTreeHash', () => {+ it('hashes the working tree — modified, deleted, untracked, not ignored — exactly as a commit of it would', () => {+ const root = mkdtempSync(join(tmpdir(), 'portos-pregate-tree-'));+ const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();+ try {+ git('init', '-q');+ git('config', 'core.hooksPath', join(root, 'empty-hooks'));+ git('config', 'user.name', 'Example Contributor');+ git('config', 'user.email', '[email protected]');+ git('config', 'commit.gpgsign', 'false');+ writeFileSync(join(root, '.gitignore'), '/.cache/\n*.log\n');+ writeFileSync(join(root, 'kept.txt'), 'kept\n');+ writeFileSync(join(root, 'edited.txt'), 'before\n');+ writeFileSync(join(root, 'removed.txt'), 'gone\n');+ git('add', '--all');+ git('commit', '-qm', 'base');+ const committedTree = git('rev-parse', 'HEAD^{tree}');++ writeFileSync(join(root, 'edited.txt'), 'after\n');+ rmSync(join(root, 'removed.txt'));+ mkdirSync(join(root, 'nested'));+ writeFileSync(join(root, 'nested', 'added.txt'), 'new\n');+ writeFileSync(join(root, 'noise.log'), 'ignored\n');+ mkdirSync(join(root, '.cache'));+ writeFileSync(join(root, '.cache', 'report.json'), '{}');+ const indexBefore = readFileSync(join(root, '.git', 'index'));+ const statusBefore = git('status', '--porcelain=v1', '--untracked-files=all');++ const hash = validatedTreeHash(root);++ expect(hash).not.toBe(committedTree);+ expect(readFileSync(join(root, '.git', 'index'))).toEqual(indexBefore);+ expect(git('status', '--porcelain=v1', '--untracked-files=all')).toBe(statusBefore);+ expect(validatedTreeHash(root)).toBe(hash);++ git('add', '--all');+ git('commit', '-qm', 'validated state');+ expect(git('rev-parse', 'HEAD^{tree}')).toBe(hash);+ expect(git('ls-tree', '-r', '--name-only', 'HEAD').split('\n')).toEqual(['.gitignore', 'edited.txt', 'kept.txt', 'nested/added.txt']);+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });+});