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

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.js
new file mode 100644
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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 });
+ }
+ });
+});