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
/** Local validation selection, stage execution, process ownership and receipt
* contracts. Hosted CI owns the broader test-impact plan.
*/
import { cosWorkerBudget } from './lib/cosWorkerBudget.js';
import { afterAll, afterEach, beforeAll, beforeEach, describe, it, expect } from 'vitest';
import { execFileSync, spawn, spawnSync } from 'child_process';
import { copyFileSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, symlinkSync, existsSync, lstatSync, readdirSync } from 'fs';
import { tmpdir } from 'os';
import { cp } from 'fs/promises';
import { delimiter, dirname, join } from 'path';
import { fileURLToPath } from 'url';
import { destroyGitSandbox, makeGitSandbox } from '../server/lib/gitTestRepo.js';
import {
buildCiTestPlan,
collectPlanInputs,
ALWAYS_RUN_TESTS,
} from './ci-test-plan.js';
import {
collectPregateChangedFiles,
resolvePlanStages,
describeBrowserSelection,
describeStageCommand,
downgradeFullPlan,
focusedLocalPlan,
parseArgs,
pregateWorkerEnv,
stageSpawnEnv,
sweepStageGroup,
suiteSelected,
uncoveredSuites,
UNCOVERED_SUITES,
unmergedIndexPaths,
} from './pregate.js';
import { buildPregateReport, PREGATE_REPORT_PATH, validatedTreeHash } from './lib/pregateReport.js';
import { probeTestDatabase, TEST_DATABASE, uncreatableExtensions, testDatabaseStageEnv } from './lib/pregateResources.js';
import { BROWSER_SUITES } from './lib/browserSuites.js';
import { BROWSER_FIDELITY_FILES } from './lib/browserTestProfiles.js';
const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const planWith = (overrides = {}) => ({
full: false,
reason: 'test plan',
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,
supercolliderLive: false,
dockerContainmentLive: false,
...overrides,
});
const DEFAULT_OPTIONS = {
base: null, full: false, skipLint: false, planOnly: false, help: false, guardsOnly: false, mergedWith: null,
skipDb: false, skipBrowser: false, skipBuild: false, skipSmoke: false,
};
describe('owned stage group settlement', () => {
const pgid = 424242;
const fail = code => { throw Object.assign(new Error(code), { code }); };
it('waits through a zombie-only EPERM until a fresh exact-group probe returns ESRCH', async () => {
let elapsed = 0;
const calls = [];
const result = await sweepStageGroup(pgid, {
kill: (pid, signal) => {
calls.push([pid, signal]);
// Reproduce the held-zombie -> reaped transition without timing sleeps.
return fail(elapsed === 0 ? 'EPERM' : 'ESRCH');
},
now: () => elapsed,
wait: async ms => { elapsed += ms; },
inspect: group => { expect(group).toBe(pgid); return `${pgid}:Z`; },
});
expect(result).toEqual({ settled: true, lingered: true });
expect(calls).toEqual([[-pgid, 'SIGKILL'], [-pgid, 0], [-pgid, 0]]);
expect(elapsed).toBe(25);
});
it.each([
['live', 'present', '424242:S'],
['uninspectable', 'EPERM', 'unavailable (EACCES)'],
['zombie-only', 'EPERM', '424242:Z'],
['empty snapshot with denied probe', 'EPERM', 'none observed'],
['failed probe', 'EIO', 'unavailable (EIO)'],
])('refuses a %s group without a fresh ESRCH', async (_state, probe, members) => {
let elapsed = 0;
const signals = [];
const result = await sweepStageGroup(pgid, {
kill: (pid, signal) => {
expect(pid).toBe(-pgid);
signals.push(signal);
if (signal === 'SIGKILL') return fail('EPERM');
if (probe !== 'present') return fail(probe);
},
now: () => elapsed,
wait: async ms => { elapsed += ms; },
inspect: group => { expect(group).toBe(pgid); return members; },
});
expect(result).toEqual({ settled: false, reason: `group kill failed (EPERM); pgid=${pgid}; probe=${probe}; members=${members}` });
expect(signals[0]).toBe('SIGKILL');
expect(signals.slice(1).every(signal => signal === 0)).toBe(true);
expect(elapsed).toBe(probe === 'EIO' ? 0 : 5000);
});
});
describe('resolvePlanStages', () => {
it('runs only the scopes the plan selected', () => {
const stages = resolvePlanStages(planWith());
expect(stages.map((stage) => stage.name)).toEqual(['hidden-content scan', 'server tests']);
});
it('hands each runner the plan\'s own selector lists', () => {
const [, stage] = resolvePlanStages(planWith({
server: { mode: 'related', files: ['server/lib/a.test.js'], sources: ['server/lib/a.js'] },
}));
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"]',
PORTOS_PREGATE_GUARDS: '',
});
});
it('scans hidden content before lint and tests using the resolved base', () => {
const stages = resolvePlanStages(planWith({
lint: { mode: 'files', files: ['client/src/App.jsx'] },
client: { mode: 'files', files: ['client/src/App.test.jsx'], sources: [] },
}), { 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', 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"]' });
for (const stage of stages.filter((item) => item.script === 'run-ci-tests.js')) {
expect(stage.env.CI_BASE_SHA).toBe('resolved-base');
}
});
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');
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: {},
});
});
it('drops the lint stage under --skip-lint but keeps the test stages', () => {
const stages = resolvePlanStages(
planWith({ lint: { mode: 'files', files: ['client/src/App.jsx'] } }),
{ skipLint: true },
);
expect(stages.map((stage) => stage.name)).toEqual(['hidden-content scan', 'server tests']);
});
it.each(['related', 'full'])('runs shared guards before every costly %s stage without changing the broad selection', (mode) => {
const tracked = ['server/lib/index.test.js', ALWAYS_RUN_TESTS[0], 'client/src/fooConventions.test.js'];
const plan = planWith({
server: { mode, files: tracked.slice(0, 2), sources: ['server/lib/helper.js'] },
client: { mode, files: tracked.slice(2), sources: [] },
lint: { mode: 'full', files: [] },
build: true, smoke: true, db: true, browser: { files: BROWSER_SUITES.slice(0, 1) },
});
const stages = resolvePlanStages(plan, { guardPlan: downgradeFullPlan(plan, tracked, ['server/lib/helper.js']) });
expect(stages.map(stage => stage.name)).toEqual([
'hidden-content scan', 'server structural guards', 'client structural guards',
'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)',
]);
for (const scope of ['server', 'client']) {
expect(stages.find(stage => stage.name === `${scope} tests`).env).toMatchObject({
CI_TEST_MODE: mode, CI_TEST_FILES: JSON.stringify(plan[scope].files), CI_TEST_SOURCES: JSON.stringify(plan[scope].sources),
});
}
expect(stages.filter(stage => stage.guard).flatMap(stage => stage.files).sort()).toEqual(tracked.sort());
});
});
// These regressions need the actual CLI and Git, not mocked stage dispatch:
// a later Git state can hide an earlier addition, no-index uses exit 1 for
// success, and even a read-only `git status` can refresh the caller's index.
describe('pregate hidden-content invocation', () => {
let scratch;
let root;
let base;
let template;
const trackedPath = 'docs/tracked note.md';
const clean = '# Example\n';
const hidden = `${clean}hidden: \u200B\n`;
const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
const write = (path, content) => writeFileSync(join(root, path), content);
const run = (...args) => spawnSync(process.execPath, ['scripts/pregate.js', '--base', base, ...args], {
cwd: root, encoding: 'utf8',
env: { ...process.env, PATH: `${join(scratch, 'fake-bin')}${delimiter}${process.env.PATH}` },
});
const snapshot = () => ({
status: git('--no-optional-locks', 'status', '--porcelain=v1', '-z', '--untracked-files=all'),
index: readFileSync(join(root, '.git', 'index')),
});
beforeAll(async () => {
template = await makeGitSandbox({ prefix: 'portos-pregate-template-' });
root = template.repo;
scratch = template.scratch;
git('config', 'core.hooksPath', join(scratch, 'empty-hooks'));
git('config', 'core.excludesFile', join(scratch, 'empty-excludes'));
// Copy the real builtin-only entrypoints so REPO_ROOT targets this fixture.
// No runners or test files: docs-only changes produce an empty test plan.
for (const path of [
'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/importReach.js', 'scripts/lib/workspaceTests.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/lib/pregateReport.js', 'scripts/lib/cosWorkerBudget.js', 'scripts/lib/pregateAttestation.js',
'scripts/migrations/shippedPromptHistory.js', 'server/lib/aiToolkit/internal/windowsSafeSpawn.js',
'server/lib/diffHiddenContentScan.js', 'server/lib/modelAbuseGuard.js',
'server/lib/textUtils.js',
]) {
mkdirSync(dirname(join(root, path)), { recursive: true });
copyFileSync(join(REPO_ROOT, path), join(root, path));
}
// The real npm script and its Windows shim, so the harness exercises what `npm run pregate` runs.
write('package.json', JSON.stringify({ type: 'module', scripts: { pregate: JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8')).scripts.pregate } }) + '\n');
copyFileSync(join(REPO_ROOT, 'exec.cmd'), join(root, 'exec.cmd'));
// 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: { '': {} } }));
}
mkdirSync(join(root, 'docs'));
write(trackedPath, clean);
git('add', '--all');
git('commit', '-qm', 'pregate fixture');
base = git('rev-parse', 'HEAD');
});
beforeEach(async () => {
scratch = mkdtempSync(join(tmpdir(), 'portos-pregate-cli-'));
root = join(scratch, 'primary');
// Clone the fully committed fixture, not the raw git template. Windows
// otherwise repeats source copies, git add and git commit for every case.
await cp(template.repo, root, { recursive: true });
// The copied index still holds the template files' stat data. Refresh it
// before the test snapshots its bytes, or the CLI's ordinary Git reads
// appear to mutate the index even when they only notice the copy.
git('update-index', '--refresh');
base = git('rev-parse', 'HEAD');
});
afterEach(async () => {
await destroyGitSandbox(scratch);
});
afterAll(async () => {
if (template?.scratch) await destroyGitSandbox(template.scratch);
});
function prepareGuardFixture({ browser = false } = {}) {
write('server/lib/index.js', 'export {};\n');
write('server/lib/README.md', '# Shared helpers\n');
// This fixture guard pins the catalog failure at the CLI boundary; the real
// catalog suite separately owns the complete barrel/README contract.
write('server/lib/index.test.js', `
import { appendFileSync, existsSync, readFileSync } from 'fs';
appendFileSync('.cache/events', 'catalog\\n');
if (existsSync('server/lib/helper.js') &&
(!readFileSync('server/lib/index.js', 'utf8').includes('helper') ||
!readFileSync('server/lib/README.md', 'utf8').includes('helper'))) {
throw new Error('Missing helper barrel/catalog registration');
}
`);
write('server/lib/expensive.test.js', 'export {};\n');
write('scripts/run-ci-tests.js', `
import { appendFileSync } from 'fs';
import { resolve } from 'path';
import { pathToFileURL } from 'url';
const files = JSON.parse(process.env.CI_TEST_FILES);
const excluded = JSON.parse(process.env.PORTOS_PREGATE_GUARDS || '{}').files || [];
const broad = process.env.CI_TEST_MODE !== 'files' || files.includes('server/lib/expensive.test.js');
appendFileSync('.cache/events', JSON.stringify({ broad, excluded }) + '\\n');
if (files.includes('server/lib/index.test.js') && !excluded.includes('server/lib/index.test.js')) {
await import(pathToFileURL(resolve('server/lib/index.test.js')));
}
`);
write('scripts/run-ci-lint.js', `
import { appendFileSync, existsSync, writeFileSync } from 'fs';
appendFileSync('.cache/events', 'lint\\n');
if (existsSync('.cache/mutate')) writeFileSync('server/lib/helper.js', 'export const helper = 2;\\n');
`);
write('scripts/smoke-boot.js', `
import { appendFileSync } from 'fs';
appendFileSync('.cache/events', 'smoke\\n');
`);
if (browser) {
write(BROWSER_SUITES[0], 'export {};\n');
write('scripts/lib/pregateResources.js', `
import { writeFileSync } from 'fs';
writeFileSync('.cache/probe-started', 'unexpected probe');
throw new Error('Resource probe ran before structural refusal');
`);
}
git('add', '--all');
git('commit', '-qm', 'structural gate fixture');
base = git('rev-parse', 'HEAD');
mkdirSync(join(root, '.cache'), { recursive: true });
write('.cache/events', '');
write('server/lib/helper.js', 'export const helper = 1;\n');
if (browser) write(BROWSER_SUITES[0], 'export const changed = true;\n');
}
it('prints the selected guard, broad and browser stages without starting any process', () => {
prepareGuardFixture({ browser: true });
const result = run('--plan-only', '--full');
expect(result.status, result.stderr).toBe(0);
expect(result.stdout).toContain('Planning against');
expect(result.stdout).toContain('changed file');
expect(result.stdout).toContain('server structural guards');
expect(result.stdout).toContain('server tests');
expect(result.stdout).toContain('Browser suites: 1 selected');
expect(readFileSync(join(root, '.cache/events'), 'utf8')).toBe('');
expect(existsSync(join(root, '.cache/probe-started'))).toBe(false);
expect(existsSync(join(root, PREGATE_REPORT_PATH))).toBe(false);
});
// A structural refusal must precede both related-test dispatch and Chrome's
// prerequisite probe, with the unfinished broad stages preserved in the receipt.
it('refuses a missing helper catalog registration before broad tests or browser probes start', () => {
prepareGuardFixture({ browser: true });
const result = run('--skip-lint', '--full');
expect(result.status).not.toBe(0);
expect(result.stderr).toContain('Missing helper barrel/catalog registration');
const events = readFileSync(join(root, '.cache/events'), 'utf8');
expect(events).not.toContain('"broad":true');
expect(existsSync(join(root, '.cache/probe-started'))).toBe(false);
const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));
expect(report.passed).toBe(false);
expect(report.stages.find(stage => stage.guard)).toMatchObject({ status: 'failed', files: ['server/lib/index.test.js'] });
expect(report.stages.filter(stage => ['server tests', 'browser suites'].includes(stage.name)))
.toEqual(expect.arrayContaining([
expect.objectContaining({ name: 'server tests', status: 'not-run' }),
expect.objectContaining({ name: 'browser suites', status: 'not-run' }),
]));
});
// Unlike the persistent module memo, this reuse includes tree scanners. A
// modification between stages invalidates it even when the test file is stable.
it.each([false, true])('rechecks guard inputs before broad dispatch (changed: %s)', (changed) => {
prepareGuardFixture();
write('server/lib/index.js', "export { helper } from './helper.js';\n");
write('server/lib/README.md', '# Shared helpers\nhelper\n');
if (changed) write('.cache/mutate', 'mutate during lint');
const result = run('--full');
expect(result.status, result.stderr).toBe(0);
const events = readFileSync(join(root, '.cache/events'), 'utf8').trim().split('\n');
expect(events.filter(event => event === 'catalog')).toHaveLength(changed ? 2 : 1);
expect(events.indexOf('catalog')).toBeLessThan(events.indexOf('lint'));
expect(events.at(-1)).toBe('smoke');
const broad = events.filter(event => event.startsWith('{')).map(event => JSON.parse(event)).find(event => event.broad);
expect(broad.excluded).toEqual(changed ? [] : ['server/lib/index.test.js']);
const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));
expect(report.stages.every(stage => stage.status === 'passed')).toBe(true);
expect(report.treeStable).toBe(!changed);
expect(report.stages.find(stage => stage.name === 'server tests').guardReuse?.files)
.toEqual(changed ? undefined : ['server/lib/index.test.js']);
});
// A branch and base can each be green while their combined route inventory fails.
it('runs guards on the exact merged tree, propagates failure, and preserves caller state and receipt', () => {
git('config', 'core.autocrlf', 'true');
mkdirSync(join(root, 'server/routes'), { recursive: true });
write('server/routes/universe-builder.js', 'export const mutation = false;\n');
write('server/lib/strict.js', 'export const strict = false;\n');
write('server/lib/hostControlRoutes.test.js', `
import { readFileSync } from 'fs';
import { strict } from './strict.js';
if (strict && readFileSync('server/routes/universe-builder.js', 'utf8').includes('mutation = true')) {
throw new Error('hostControlRoutes.test.js: unclassified Universe Builder mutation');
}
`);
write('scripts/run-ci-tests.js', `
import { resolve } from 'path';
import { pathToFileURL } from 'url';
if (process.env.PORTOS_TEST_MEMO !== 'off') throw new Error('merged guards reused memo');
for (const file of JSON.parse(process.env.CI_TEST_FILES)) {
if (file.endsWith('hostControlRoutes.test.js')) await import(pathToFileURL(resolve(file)));
}
`);
git('add', '--all');
git('commit', '-qm', 'green common guard');
const common = git('rev-parse', 'HEAD');
git('checkout', '-qb', 'new-base');
write('docs/tracked note.md', '# Unrelated base move\n');
git('add', '--all'); git('commit', '-qm', 'base move');
const movedBase = git('rev-parse', 'HEAD');
git('checkout', '-qb', 'feature', common);
const invoke = (...flags) => spawnSync(process.execPath, ['scripts/pregate.js', ...flags], {
cwd: root, encoding: 'utf8', env: { ...process.env, PORTOS_TEST_MEMO: 'on' },
});
mkdirSync(join(root, '.cache/pregate'), { recursive: true });
write(PREGATE_REPORT_PATH, 'original attestation receipt');
const original = { ...snapshot(), refs: git('show-ref'), worktrees: git('worktree', 'list', '--porcelain') };
const green = invoke('--guards-only', '--merged-with', movedBase);
expect(green.status, green.stderr).toBe(0);
expect(green.stdout).toContain('Merged-tree guards: HEAD');
expect(green.stdout).not.toContain('hidden-content scan');
expect(green.stdout).not.toContain('client/server lint');
expect({ ...snapshot(), refs: git('show-ref'), worktrees: git('worktree', 'list', '--porcelain') }).toEqual(original);
expect(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8')).toBe('original attestation receipt');
// The base tightens its guard independently; feature remains green in its own tree.
write('server/routes/universe-builder.js', 'export const mutation = true;\n');
git('add', '--all'); git('commit', '-qm', 'feature mutation before stricter guard');
const branchOnly = invoke('--guards-only', '--base', common);
expect(branchOnly.status, branchOnly.stderr).toBe(0);
// The stricter base policy and feature route change do not conflict textually.
git('checkout', 'new-base');
write('server/lib/strict.js', 'export const strict = true;\n');
git('add', '--all'); git('commit', '-qm', 'strict inventory');
const strictBase = git('rev-parse', 'HEAD');
git('checkout', 'feature');
const before = { ...snapshot(), refs: git('show-ref'), worktrees: git('worktree', 'list', '--porcelain') };
const failed = invoke('--guards-only', '--merged-with', strictBase);
expect(failed.status).not.toBe(0);
expect(failed.stderr).toContain('hostControlRoutes.test.js: unclassified Universe Builder mutation');
expect(failed.stdout).not.toContain('Pregate passed');
expect({ ...snapshot(), refs: git('show-ref'), worktrees: git('worktree', 'list', '--porcelain') }).toEqual(before);
expect(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8')).toBe('original attestation receipt');
const originalDocBytes = readFileSync(join(root, 'docs/tracked note.md'));
write('docs/tracked note.md', '# Pending local work\n');
const dirty = snapshot();
const refused = invoke('--guards-only', '--merged-with', strictBase);
expect(refused.status).not.toBe(0);
expect(refused.stderr).toContain('requires a clean committed checkout');
expect(snapshot()).toEqual(dirty);
writeFileSync(join(root, 'docs/tracked note.md'), originalDocBytes);
git('checkout', 'new-base');
write('server/routes/universe-builder.js', 'export const mutation = "conflicting";\n');
git('add', '--all'); git('commit', '-qm', 'conflicting mutation');
const conflictBase = git('rev-parse', 'HEAD');
git('checkout', 'feature');
const preConflict = snapshot();
const conflict = invoke('--guards-only', '--merged-with', conflictBase);
expect(conflict.status).not.toBe(0);
expect(conflict.stderr).toContain('Cannot construct merged guard tree');
expect(conflict.stdout).not.toContain('Pregate passed');
expect(snapshot()).toEqual(preConflict);
});
it('merges a remote-only base from a shallow source and still reports real conflicts', () => {
write('scripts/run-ci-tests.js', `
import { readFileSync } from 'fs';
if (readFileSync('docs/tracked note.md', 'utf8').trim() !== '# Base update'
|| readFileSync('docs/feature.md', 'utf8').trim() !== '# Independent feature') {
throw new Error('guard did not receive both merge inputs');
}
`);
git('add', '--all'); git('commit', '-qm', 'merged guard fixture');
const upstream = root;
const shallow = join(scratch, 'shallow');
git('clone', '--quiet', '--no-local', '--depth', '1', '--', upstream, shallow);
write(trackedPath, '# Base update\n');
git('add', '--all'); git('commit', '-qm', 'base update');
const movedBase = git('rev-parse', 'HEAD');
root = shallow;
for (const workspace of ['', 'client', 'server', 'autofixer']) {
mkdirSync(join(root, workspace, 'node_modules'), { recursive: true });
}
git('config', 'user.name', 'Example Agent');
git('config', 'user.email', '[email protected]');
git('config', 'commit.gpgsign', 'false');
git('config', 'core.hooksPath', join(scratch, 'empty-hooks'));
git('checkout', '-qb', 'feature');
write('docs/feature.md', '# Independent feature\n');
git('add', '--all'); git('commit', '-qm', 'feature update');
git('fetch', '--quiet', 'origin', 'main:refs/remotes/origin/main');
expect(git('rev-parse', '--is-shallow-repository')).toBe('true');
expect(git('rev-parse', 'origin/main')).toBe(movedBase);
expect(git('for-each-ref', '--format=%(refname)', '--points-at', movedBase, 'refs/heads')).toBe('');
const tree = git('merge-tree', '--write-tree', 'HEAD', 'origin/main').split('\n')[0];
const invoke = () => spawnSync(process.execPath, ['scripts/pregate.js', '--guards-only', '--merged-with', 'origin/main'], {
cwd: root, encoding: 'utf8',
});
const sourceState = () => ({ ...snapshot(), refs: git('show-ref'), shallow: readFileSync(join(root, '.git/shallow')) });
const before = sourceState();
const merged = invoke();
expect(merged.status, merged.stderr).toBe(0);
expect(merged.stdout).toContain(`= tree ${tree.slice(0, 12)}.`);
expect(sourceState()).toEqual(before);
write(trackedPath, '# Conflicting feature update\n');
git('add', '--all'); git('commit', '-qm', 'conflicting feature update');
const preConflict = sourceState();
const conflict = invoke();
expect(conflict.status).not.toBe(0);
expect(conflict.stderr).toContain('Cannot construct merged guard tree');
expect(conflict.stderr).toContain('CONFLICT (content)');
expect(conflict.stdout).not.toContain('Pregate passed');
expect(sourceState()).toEqual(preConflict);
});
// This regression catches stale inherited packages before any lint/test child
// can produce a misleading product failure or repair the shared source tree.
it.each(['matching', 'stale', 'missing-package', 'unreadable-package', 'dangling'])(
'checks %s linked dependencies read-only before executing stages', (state) => {
const shared = join(scratch, 'source', 'server', 'node_modules');
const installed = join(shared, 'express', 'package.json');
const modules = join(root, 'server', 'node_modules');
mkdirSync(dirname(installed), { recursive: true });
writeFileSync(installed, state === 'unreadable-package' ? '{broken' : JSON.stringify({ version: state === 'stale' ? '5.2.1' : '5.3.0' }));
if (state === 'missing-package') rmSync(installed);
const sourceReceipt = join(scratch, 'source', 'deps-hashes.json');
writeFileSync(sourceReceipt, '{"server":"legacy"}');
writeFileSync(join(shared, '.package-lock.json'), '{"packages":{"node_modules/express":{"version":"5.3.0"}}}');
const sourceSnapshot = () => Object.fromEntries(readdirSync(join(scratch, 'source'), { recursive: true })
.filter(path => lstatSync(join(scratch, 'source', path)).isFile())
.map(path => [path, readFileSync(join(scratch, 'source', path), 'utf8')]));
const before = sourceSnapshot();
const fakeBin = join(scratch, 'fake-bin');
mkdirSync(fakeBin);
writeFileSync(join(fakeBin, 'npm'), '#!/usr/bin/env node\nrequire("fs").writeFileSync("unexpected-npm", "called");', { mode: 0o755 });
writeFileSync(join(fakeBin, 'npm.cmd'), '@node "%~dp0npm" %*\r\n');
rmSync(modules, { recursive: true });
const target = state === 'dangling' ? join(scratch, 'absent-deps') : shared;
symlinkSync(target, modules, process.platform === 'win32' ? 'junction' : 'dir');
write('server/package-lock.json', JSON.stringify({ packages: {
'': {}, 'node_modules/express': { version: '5.3.0' },
'node_modules/optional-platform-package': { version: '1.0.0', optional: true },
} }));
// Changing scripts selects full lint; any accidental stage run leaves a
// durable marker. Startup/package-manager repair is a separate trap.
for (const name of ['run-ci-lint.js', 'run-ci-tests.js', 'ensure-deps.js']) {
write(`scripts/${name}`, `import { writeFileSync } from 'fs'; writeFileSync('unexpected-stage', '${name}');`);
}
const result = run();
if (state === 'matching') {
expect(result.status, result.stderr).toBe(0);
expect(result.stdout).toContain('Dependency consistency preflight passed');
expect(existsSync(join(root, 'unexpected-stage'))).toBe(true);
} else {
expect(result.status).toBe(1);
expect(result.stderr).toContain('server (linked node_modules)');
expect(result.stderr).toContain('owning source checkout');
expect(result.stderr).toContain('Never run npm install/ci through worktree links');
const diagnostic = {
stale: 'expected 5.3.0, installed 5.2.1',
'missing-package': 'missing package.json (ENOENT)',
'unreadable-package': 'unreadable package.json (invalid JSON)',
dangling: 'linked target unavailable',
}[state];
expect(result.stderr).toContain(diagnostic);
expect(existsSync(join(root, 'unexpected-stage'))).toBe(false);
}
expect(lstatSync(modules).isSymbolicLink()).toBe(true);
expect(sourceSnapshot()).toEqual(before);
expect(existsSync(join(root, 'unexpected-npm'))).toBe(false);
expect(readFileSync(sourceReceipt, 'utf8')).toBe('{"server":"legacy"}');
if (state === 'dangling') expect(existsSync(target)).toBe(false);
},
);
it('diagnoses a production-only install before spawning development checks', () => {
write('server/package-lock.json', JSON.stringify({ packages: {
'': {}, 'node_modules/vitest': { version: '5.0.4', dev: true },
} }));
write('scripts/run-ci-tests.js', 'throw new Error("unexpected test stage");');
const result = run();
expect(result.status).toBe(1);
expect(result.stderr).toContain('node_modules/vitest: missing package.json');
expect(result.stderr).toContain('pregate requires development dependencies (--include=dev)');
expect(result.stderr).not.toContain('unexpected test stage');
});
it('refuses missing and unreadable lock evidence rather than calling it a match', () => {
rmSync(join(root, 'client', 'package-lock.json'));
write('autofixer/package-lock.json', '{invalid');
const result = run();
expect(result.status).toBe(1);
expect(result.stderr).toContain('client (owned node_modules)');
expect(result.stderr).toContain('package-lock.json missing (ENOENT)');
expect(result.stderr).toContain('autofixer (owned node_modules)');
expect(result.stderr).toContain('package-lock.json unreadable (invalid JSON)');
});
it.each(['committed', 'staged', 'unstaged', 'untracked'])(
'rejects %s hidden content without changing files or staging state', (state) => {
const path = state === 'untracked' ? 'docs/untracked note.md' : trackedPath;
write(path, hidden);
if (state === 'committed' || state === 'staged') git('add', '--', path);
if (state === 'committed') git('commit', '-qm', 'hidden fixture');
// A clean worktree must not conceal the staged or committed addition.
if (state === 'committed' || state === 'staged') write(path, clean);
const before = snapshot();
const contents = readFileSync(join(root, path));
const result = run('--skip-lint');
expect(result.status, result.stderr).toBe(1);
expect(result.stderr).toContain(`${path}:2 — hidden-unicode:`);
expect(result.stdout).not.toContain('Pregate passed');
expect(snapshot()).toEqual(before);
expect(readFileSync(join(root, path))).toEqual(contents);
if (state === 'committed') {
const ci = spawnSync(process.execPath, ['scripts/scan-diff-hidden-content.js', '--base', base], {
cwd: root, encoding: 'utf8',
});
expect(ci.status).toBe(1);
expect(result.stderr).toContain(ci.stderr.trim());
}
},
);
// Only the fixture-owned scan process is signaled; no real test runner starts.
it.skipIf(process.platform === 'win32')('attributes owner cancellation to its active stage and preserves SIGTERM', async () => {
write('scripts/scan-diff-hidden-content.js', `
console.log('fixture-stage-ready');
setInterval(() => {}, 1000);
`);
const runner = spawn(process.execPath, ['scripts/pregate.js', '--base', base, '--skip-lint'], {
cwd: root, stdio: ['ignore', 'pipe', 'pipe'],
});
let stdout = '';
let stderr = '';
runner.stderr.on('data', (data) => { stderr += data; });
runner.stdout.on('data', (data) => {
stdout += data;
if (stdout.includes('fixture-stage-ready')) runner.kill('SIGTERM');
});
try {
const result = await new Promise((resolve, reject) => {
runner.once('error', reject);
runner.once('close', (status, signal) => resolve({ status, signal }));
});
expect(result).toEqual({ status: null, signal: 'SIGTERM' });
expect(stderr).toContain(`Pregate incomplete: stage="hidden-content scan" owner_pid=${runner.pid}`);
expect(stderr).toMatch(/child_pid=\d+ received_signal=SIGTERM/);
expect(stdout).not.toContain('Pregate passed');
} finally {
runner.kill('SIGKILL');
}
});
// #12641/#12670: a Ctrl-C reaches pregate from the terminal group AND from
// npm's forwarding; the duplicate used to kill pregate before it signalled the
// stage, orphaning the runner. A group SIGTERM also kills the `sh -c` wrapper
// npm runs the script under (dash on Linux does not always exec its last
// command), and npm exits the moment that wrapper dies. The simulated shell
// below never execs on its own, so only the script's own `exec` keeps the
// wrapper out of the way. The fixture stage mirrors run-ci-tests.js: a
// launcher that settles its own separately grouped child on a signal, plus
// an in-group descendant that ignores signals and keeps writing.
it.skipIf(process.platform === 'win32').each(['SIGINT', 'SIGTERM'])('settles every owned stage process before npm exits on a group %s', async (signal) => {
const heartbeat = join(scratch, 'heartbeat');
write('scripts/scan-diff-hidden-content.js', `
import { spawn } from 'child_process';
import { existsSync } from 'fs';
const straggler = spawn(process.execPath, ['-e', "process.on('SIGINT', () => {}); process.on('SIGTERM', () => {});"
+ " setInterval(() => require('fs').appendFileSync(process.env.FIXTURE_HEARTBEAT, '.'), 10);"], { stdio: 'ignore' });
const launched = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore', detached: true });
const settle = () => {
process.kill(-launched.pid, 'SIGKILL');
launched.once('exit', () => setTimeout(() => process.exit(1), 100));
};
process.on('SIGINT', settle);
process.on('SIGTERM', settle);
// Ready only once the straggler is provably writing.
const ready = setInterval(() => {
if (!existsSync(process.env.FIXTURE_HEARTBEAT)) return;
clearInterval(ready);
console.log('fixture-stage-ready ' + JSON.stringify([process.ppid, process.pid, straggler.pid, launched.pid]));
}, 10);
setInterval(() => {}, 1000);
`);
const unrelated = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore', detached: true });
const nonExecShell = join(scratch, 'non-exec-shell');
writeFileSync(nonExecShell, '#!/bin/sh\nexec /bin/sh "$1" "$2 ; :"\n', { mode: 0o755 });
const npm = spawn('npm', ['run', 'pregate', '--', '--base', base, '--skip-lint'], {
cwd: root, stdio: ['ignore', 'pipe', 'pipe'], detached: true,
env: { ...process.env, FIXTURE_HEARTBEAT: heartbeat, npm_config_script_shell: nonExecShell },
});
const alive = (pid) => {
try { process.kill(pid, 0); return true; } catch (error) { return error.code !== 'ESRCH'; }
};
let pregatePid = null;
let owned = [];
let stdout = '';
let stderr = '';
npm.stderr.on('data', (data) => { stderr += data; });
npm.stdout.on('data', (data) => {
stdout += data;
const ready = /fixture-stage-ready (\[[\d,]+\])/.exec(stdout);
if (ready && owned.length === 0) {
[pregatePid, ...owned] = JSON.parse(ready[1]);
// Ctrl-C reaches the whole foreground group: npm and pregate alike.
process.kill(-npm.pid, signal);
}
});
try {
const closed = new Promise((resolve) => npm.once('close', resolve));
const result = await new Promise((resolve, reject) => {
npm.once('error', reject);
npm.once('exit', (status, exitSignal) => resolve({ status, signal: exitSignal }));
});
// The boundary is npm's own exit: nothing pregate owns may outlive it.
expect(alive(pregatePid)).toBe(false);
expect(owned).toHaveLength(3);
expect(owned.filter(alive)).toEqual([]);
// Output is read after `close`, which a survivor holding the pipes would delay.
await Promise.race([closed, new Promise((resolve) => setTimeout(resolve, 5000))]);
expect(result.status === null ? result.signal : result.status).not.toBe(0);
expect(stderr).toMatch(new RegExp(`stage="hidden-content scan" owner_pid=${pregatePid} child_pid=${owned[0]} received_signal=${signal}`));
expect(stderr).toContain(`stage="hidden-content scan" cancelled by ${signal}; its process group has exited.`);
expect(stdout).not.toContain('Pregate passed');
const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));
expect(report.passed).toBe(false);
expect(report.stages[0]).toMatchObject({ name: 'hidden-content scan', status: 'failed', signal });
const written = readFileSync(heartbeat, 'utf8').length;
await new Promise((resolve) => setTimeout(resolve, 100));
expect(readFileSync(heartbeat, 'utf8').length).toBe(written);
expect(alive(unrelated.pid)).toBe(true);
} finally {
for (const pid of [npm.pid, unrelated.pid, ...owned].filter(Boolean)) {
try { process.kill(-pid, 'SIGKILL'); } catch { /* not a live group */ }
try { process.kill(pid, 'SIGKILL'); } catch { /* already gone */ }
}
}
});
// #13458: replay the kernel's exit/signal crossing at the CLI boundary.
// Only an actually absent group gets the injected refusal; the subsequent
// probe must still go to the kernel, and the receipt must remain truthful.
it.skipIf(process.platform === 'win32')('verifies exact group absence after an exit-crossing EPERM', () => {
const preload = join(scratch, 'exit-crossing.cjs');
writeFileSync(preload, `
const kill = process.kill.bind(process);
process.kill = (pid, signal) => {
if (pid < 0 && signal === 'SIGKILL') {
try { kill(pid, 0); } catch (error) {
if (error.code !== 'ESRCH') throw error;
console.log('fixture-exit-crossing pgid=' + -pid);
throw Object.assign(new Error('exit crossing'), { code: 'EPERM' });
}
}
return kill(pid, signal);
};
`);
write(trackedPath, `${clean}updated\n`);
const result = spawnSync(process.execPath, ['--require', preload, 'scripts/pregate.js', '--base', base, '--skip-lint'], {
cwd: root, encoding: 'utf8',
});
expect(result.stdout).toMatch(/fixture-exit-crossing pgid=\d+/);
expect(result.status, result.stderr).toBe(0);
expect(result.stdout).toContain('Pregate passed');
const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));
expect(report.passed).toBe(true);
expect(report.stages[0]).toMatchObject({ name: 'hidden-content scan', status: 'passed' });
});
// run-ci-tests.js leaves npm and Vitest in pregate's stage group, so pregate
// owns them on every exit path, not only on cancellation.
it.skipIf(process.platform === 'win32')('kills a descendant still running in the stage group after the stage exits', () => {
const marker = join(scratch, 'straggler-pid');
write('scripts/scan-diff-hidden-content.js', `
import { spawn } from 'child_process';
import { writeFileSync } from 'fs';
const straggler = spawn(process.execPath, ['-e', "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);"], { stdio: 'ignore' });
writeFileSync(${JSON.stringify(marker)}, String(straggler.pid));
setTimeout(() => process.exit(0), 200);
`);
const result = run('--skip-lint');
const pid = Number(readFileSync(marker, 'utf8'));
let alive = true;
try { process.kill(pid, 0); } catch (error) { alive = error.code !== 'ESRCH'; }
if (alive) process.kill(pid, 'SIGKILL');
expect(alive).toBe(false);
// Later stages are not fixtures here; only the scan stage's outcome matters.
expect(result.stdout).toContain('hidden-content scan passed');
expect(result.stderr).toContain('Stage "hidden-content scan" exited before its process group settled; verified group exit.');
});
// #12833: a stage's exit status is its only verdict; a failing provisioning
// command must never be recorded as `passed` in the receipt.
it('records a stage that exits non-zero as failed and ends with its status', () => {
write('scripts/scan-diff-hidden-content.js', "console.error('fixture provisioning failure'); process.exit(3);\n");
const result = run('--skip-lint');
expect(result.status).toBe(3);
expect(result.stderr).toContain('hidden-content scan failed after');
expect(result.stdout).not.toContain('Pregate passed');
const report = JSON.parse(readFileSync(join(root, PREGATE_REPORT_PATH), 'utf8'));
expect(report.stages[0]).toMatchObject({ name: 'hidden-content scan', status: 'failed', exitCode: 3 });
});
it.skipIf(process.platform === 'win32')('reports a stage child signal as incomplete rather than an ordinary assertion failure', () => {
write('scripts/scan-diff-hidden-content.js', "process.kill(process.pid, 'SIGTERM');\n");
const result = run('--skip-lint');
expect(result.status).toBe(143);
expect(result.stderr).toMatch(/Pregate incomplete: stage="hidden-content scan" owner_pid=\d+ child_pid=\d+ child_signal=SIGTERM/);
expect(result.stderr).not.toContain('failed — fix it');
expect(result.stdout).not.toContain('Pregate passed');
});
it('passes clean uncommitted changes even when the plan selects no lint or tests', () => {
git('config', 'core.autocrlf', 'true');
write(trackedPath, `${clean}staged\n`);
git('add', '--', trackedPath);
write(trackedPath, `${clean}unstaged\n`);
write('docs/new note.md', 'ordinary text\n');
const before = snapshot();
const result = run('--skip-lint');
expect(result.status, result.stderr).toBe(0);
expect(result.stdout).toContain('Pregate passed: hidden-content scan.');
expect(snapshot()).toEqual(before);
});
it('lists the mandatory scan in plan-only mode without scanning hidden content', () => {
write('docs/new note.md', hidden);
const before = snapshot();
const result = run('--plan-only', '--skip-lint');
expect(result.status, result.stderr).toBe(0);
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('leaves DB-only changes to hosted CI by default and plans portos_test only with explicit full validation', () => {
mkdirSync(join(root, 'server/routes'), { recursive: true });
write('server/routes/decks.db.test.js', "import { it } from 'vitest';\nit('db contract', () => {});\n");
const focused = run('--plan-only');
expect(focused.status, focused.stderr).toBe(0);
expect(focused.stdout).toContain('CI will also run: db');
expect(focused.stdout).not.toContain('• DB suite');
const result = run('--plan-only', '--full');
expect(result.status, result.stderr).toBe(0);
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', () => {
const emptyPath = 'docs/empty\u200B.md';
write(emptyPath, '');
write('docs/payload.bin', Buffer.from([0, 1, 2]));
write('-', hidden);
const before = snapshot();
const result = run('--skip-lint');
expect(result.status, result.stderr).toBe(1);
expect(result.stderr).toContain(`${emptyPath}:1 — hidden-unicode: filename`);
expect(result.stderr).toContain('docs/payload.bin:1 — opaque-binary:');
expect(result.stderr).toContain('./-:2 — hidden-unicode:');
expect(snapshot()).toEqual(before);
});
it('rejects a no-index read error even when Git reports the difference exit code', () => {
// Git lists an untracked nested repository as a directory. Comparing that
// path with /dev/null fails with exit 1 and no patch, rather than exit 2.
git('init', '-q', 'docs/nested');
write('docs/nested/example.md', clean);
const result = run('--skip-lint');
expect(result.status).toBe(2);
expect(result.stderr).toContain('Cannot read untracked diff for docs/nested/');
expect(result.stdout).not.toContain('Pregate passed');
});
it('fails closed when Git cannot read a blob in the requested committed diff', () => {
const blob = git('rev-parse', `HEAD:${trackedPath}`);
write(trackedPath, `${clean}ordinary addition\n`);
git('add', '--', trackedPath);
git('commit', '-qm', 'changed fixture');
rmSync(join(root, '.git', 'objects', blob.slice(0, 2), blob.slice(2)));
const result = run('--skip-lint');
expect(result.status).toBe(2);
expect(result.stderr).toContain('Hidden-content scan failed:');
expect(result.stdout).not.toContain('Pregate passed');
});
});
describe('pregateWorkerEnv', () => {
it('derives the budget from the CoS settings but honors an explicit handoff', () => {
expect(pregateWorkerEnv({}).PORTOS_PREGATE_MAX_WORKERS).toBe(String(cosWorkerBudget()));
expect(pregateWorkerEnv({ PORTOS_PREGATE_MAX_WORKERS: '2' }).PORTOS_PREGATE_MAX_WORKERS).toBe('2');
});
});
describe('downgradeFullPlan', () => {
it('replaces the full suite with the tracked always-run guards', () => {
const serverGuards = ALWAYS_RUN_TESTS.slice(0, 3);
const clientGuards = [
'client/src/asyncEffectDisposalConventions.test.js',
'client/src/fooConventions.test.js',
'client/src/hooks/mountedRefConventions.test.js',
];
const tracked = [...serverGuards, ...clientGuards,
'client/src/App.test.jsx', 'client/src/fooConventions.js',
'server/fooConventions.test.js',
];
const downgraded = downgradeFullPlan(planWith({ full: true }), tracked);
expect(downgraded.full).toBe(false);
expect(downgraded.server).toEqual({ mode: 'files', files: serverGuards, sources: [] });
expect(downgraded.client).toEqual({ mode: 'files', files: clientGuards, sources: [] });
const stages = resolvePlanStages(downgraded);
expect(stages.map((stage) => stage.name)).toContain('client tests');
expect(stages.find((stage) => stage.name === 'client tests').env).toMatchObject({
CI_TEST_MODE: 'files', CI_TEST_FILES: JSON.stringify(clientGuards), CI_TEST_SOURCES: '[]',
});
});
it('drops a guard this checkout does not track, so Vitest is never given a missing path', () => {
// A fork that deleted a guard, or a branch predating one, still has it in
// ALWAYS_RUN_TESTS; passing that path to Vitest is an error, not a skip.
const downgraded = downgradeFullPlan(planWith({ full: true }), []);
expect(downgraded.server.files).toEqual([]);
});
it('keeps structural guards selected by a large diff when downgrading a full plan', () => {
const tracked = [...ALWAYS_RUN_TESTS, 'server/lib/index.test.js'];
const changedFiles = Array.from({ length: 31 }, (_, index) => `server/lib/module-${index}.js`);
const downgraded = downgradeFullPlan(planWith({ full: true }), tracked, changedFiles);
expect(downgraded.server.files).toContain('server/lib/index.test.js');
});
});
describe('parseArgs', () => {
it('reads --base as a value, not a boolean', () => {
expect(parseArgs(['--base', 'origin/release', '--full'])).toEqual({
...DEFAULT_OPTIONS, base: 'origin/release', full: true,
});
});
it('accepts guard-only merged validation and rejects combinations that can skip it', () => {
expect(parseArgs(['--guards-only', '--merged-with', 'origin/main'])).toMatchObject({ guardsOnly: true, mergedWith: 'origin/main' });
expect(() => parseArgs(['--merged-with', 'origin/main'])).toThrow('requires --guards-only');
expect(() => parseArgs(['--guards-only', '--merged-with'])).toThrow('requires a value');
expect(() => parseArgs(['--guards-only', '--full'])).toThrow('cannot be combined');
expect(() => parseArgs(['--guards-only', '--skip-lint'])).toThrow('cannot be combined');
expect(() => parseArgs(['--guards-only', '--merged-with', 'origin/main', '--base', 'HEAD'])).toThrow('cannot be combined');
});
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,
});
});
it('keeps the first --base when the option is repeated', () => {
expect(parseArgs(['--base', 'origin/release', '--base', 'origin/main']).base).toBe('origin/release');
});
it('defaults to a null base so the caller resolves the remote default branch', () => {
expect(parseArgs([])).toEqual(DEFAULT_OPTIONS);
});
it('recognizes both help flags and rejects unknown flags or a missing base value', () => {
expect(parseArgs(['--help']).help).toBe(true);
expect(parseArgs(['-h']).help).toBe(true);
expect(() => parseArgs(['--unexpected'])).toThrow('Unknown option: --unexpected.');
expect(() => parseArgs(['--base'])).toThrow('--base requires a value.');
expect(() => parseArgs(['--base', '--full'])).toThrow('--base requires a value.');
});
});
describe('unmergedIndexPaths', () => {
it('returns each repo-relative path from NUL-delimited index stages', () => {
expect(unmergedIndexPaths([
'100644 abc 1\tconflict name.md',
'100644 def 2\tconflict name.md',
'100644 ghi 3\tother.md',
'',
].join('\0')))
.toEqual(['conflict name.md', 'other.md']);
});
});
describe('UNCOVERED_SUITES', () => {
/**
* The gate reports these by reading `plan[key]`. A rename in ci-test-plan.js
* would make every one of them read `undefined` — the warnings would just
* 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: 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);
});
});
describe('the gate end to end', () => {
it.each([
{ args: ['--help'], status: 0, expected: 'Usage: node scripts/pregate.js', stderr: false },
{ args: ['-h'], status: 0, expected: 'Usage: node scripts/pregate.js', stderr: false },
{ args: ['--unknown'], status: 2, expected: 'Unknown option: --unknown.', stderr: true },
{ args: ['--base'], status: 2, expected: '--base requires a value.', stderr: true },
{ args: ['--base', '--full'], status: 2, expected: '--base requires a value.', stderr: true },
])('handles $args before starting any subprocess', ({ args, status, expected, stderr }) => {
const preload = `
import childProcess from 'node:child_process';
import { syncBuiltinESMExports } from 'node:module';
const unexpectedSubprocess = () => { throw new Error('Subprocess started before argument validation'); };
childProcess.spawn = unexpectedSubprocess;
childProcess.exec = unexpectedSubprocess;
childProcess.execFile = unexpectedSubprocess;
childProcess.fork = unexpectedSubprocess;
childProcess.execSync = unexpectedSubprocess;
childProcess.spawnSync = unexpectedSubprocess;
childProcess.execFileSync = unexpectedSubprocess;
syncBuiltinESMExports();
`;
const result = spawnSync(process.execPath, [
'--import', `data:text/javascript,${encodeURIComponent(preload)}`,
join(REPO_ROOT, 'scripts', 'pregate.js'), ...args,
], { cwd: REPO_ROOT, encoding: 'utf8' });
expect(result.status, result.stderr).toBe(status);
expect(stderr ? result.stderr : result.stdout).toContain(expected);
expect(`${result.stdout}\n${result.stderr}`).toContain('Usage: node scripts/pregate.js');
expect(`${result.stdout}\n${result.stderr}`).not.toContain('Subprocess started before argument validation');
expect(result.stdout).not.toContain('Planning against');
});
// This catches validation deferred until after Git/planning, even when no
// expensive check would run (plan-only). Every subprocess is a tripwire.
it.each([{ flags: [] }, { flags: ['--full'] }, { flags: ['--plan-only'] }])('rejects unsupported Node before any subprocess with flags $flags', ({ flags }) => {
const preload = `
import childProcess from 'node:child_process';
import { syncBuiltinESMExports } from 'node:module';
Object.defineProperty(process.versions, 'node', { value: '24.14.1' });
const unexpectedSubprocess = () => { throw new Error('Subprocess started before runtime validation'); };
childProcess.spawnSync = unexpectedSubprocess;
childProcess.execFileSync = unexpectedSubprocess;
syncBuiltinESMExports();
`;
const result = spawnSync(process.execPath, [
'--import', `data:text/javascript,${encodeURIComponent(preload)}`,
join(REPO_ROOT, 'scripts', 'pregate.js'), ...flags,
], { cwd: REPO_ROOT, encoding: 'utf8' });
expect(result.status).toBe(1);
expect(result.stderr).toContain('required (found v24.14.1)');
expect(result.stderr).toContain('see .nvmrc');
expect(result.stderr).not.toContain('Subprocess started');
expect(result.stdout).toBe('');
});
it('passes an uncommitted new test through the planner override', () => {
const root = mkdtempSync(join(tmpdir(), 'portos-pregate-'));
const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
const test = 'server/services/example/newBehavior.test.js';
try {
git('init', '-q');
git('config', 'core.hooksPath', join(root, 'empty-hooks'));
writeFileSync(join(root, 'README.md'), 'fixture\n');
git('add', '--all');
git('-c', 'user.name=Example Contributor', '-c', '[email protected]',
'-c', 'commit.gpgsign=false', 'commit', '-qm', 'fixture');
const base = git('rev-parse', 'HEAD');
mkdirSync(dirname(join(root, test)), { recursive: true });
writeFileSync(join(root, test), "import { it } from 'vitest';\nit('works', () => {});\n");
const { changedFiles, workingTreeFiles } = collectPregateChangedFiles(base, { cwd: root });
const inputs = collectPlanInputs({ baseSha: base, changedFiles, cwd: root });
const plan = buildCiTestPlan(inputs.changedFiles, {
trackedFiles: inputs.trackedFiles,
appRouteOnly: false,
pathContractTests: inputs.pathContractTests,
});
expect(workingTreeFiles).toContain(test);
expect(plan.server.files).toContain(test);
} finally {
rmSync(root, { recursive: true, force: true });
}
});
it('refuses a base this checkout cannot resolve instead of planning against nothing', () => {
const run = () => execFileSync(
process.execPath,
[join(REPO_ROOT, 'scripts', 'pregate.js'), '--plan-only', '--base', 'origin/no-such-branch-for-tests'],
{ cwd: REPO_ROOT, encoding: 'utf8', stdio: 'pipe' },
);
// Exit 2, not 0: an unresolvable base is a broken invocation. Planning an
// empty diff instead would report a green gate that checked nothing —
// exactly the false green this whole script exists to prevent.
expect(run).toThrow(/Cannot resolve a merge base/);
});
it('refuses an actual unresolved merge before planning or running checks', () => {
const root = mkdtempSync(join(tmpdir(), 'portos-pregate-conflict-'));
const git = (...args) => execFileSync('git', args, { cwd: root, encoding: 'utf8' }).trim();
const run = () => spawnSync(process.execPath, [join(root, 'scripts', 'pregate.js'), '--plan-only', '--base', 'HEAD'], {
cwd: root, encoding: 'utf8',
});
try {
git('init', '-q', '-b', 'main');
git('config', 'core.hooksPath', join(root, 'empty-hooks'));
git('config', 'user.name', 'Example Contributor');
git('config', 'user.email', '[email protected]');
for (const path of [
'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/importReach.js', 'scripts/lib/workspaceTests.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/lib/pregateReport.js', 'scripts/lib/cosWorkerBudget.js', 'scripts/lib/pregateAttestation.js',
'scripts/migrations/shippedPromptHistory.js', 'server/lib/aiToolkit/internal/windowsSafeSpawn.js',
'server/lib/diffHiddenContentScan.js', 'server/lib/modelAbuseGuard.js',
'server/lib/textUtils.js',
]) {
mkdirSync(dirname(join(root, path)), { recursive: true });
copyFileSync(join(REPO_ROOT, path), join(root, path));
}
writeFileSync(join(root, 'package.json'), '{"type":"module"}\n');
writeFileSync(join(root, 'conflict.txt'), 'base\n');
git('add', 'conflict.txt');
git('commit', '-qm', 'base');
const base = git('rev-parse', 'HEAD');
git('checkout', '-qb', 'other');
writeFileSync(join(root, 'conflict.txt'), 'other\n');
git('commit', '-qam', 'other change');
git('checkout', '-q', 'main');
writeFileSync(join(root, 'conflict.txt'), 'main\n');
git('commit', '-qam', 'main change');
const merge = spawnSync('git', ['merge', 'other'], { cwd: root, encoding: 'utf8' });
expect(merge.status).not.toBe(0);
writeFileSync(join(root, 'staged.txt'), 'staged\n');
git('add', 'staged.txt');
writeFileSync(join(root, 'ordinary.txt'), 'unstaged\n');
git('add', 'ordinary.txt');
writeFileSync(join(root, 'ordinary.txt'), 'staged and unstaged\n');
writeFileSync(join(root, 'untracked.txt'), 'untracked\n');
const result = run();
expect(result.status).toBe(1);
expect(result.stderr).toContain('unresolved Git conflicts:');
expect(result.stderr).toContain(' conflict.txt');
expect(result.stdout).not.toContain('Planning against');
expect(result.stdout).not.toContain('Pregate passed');
expect(git('--no-optional-locks', 'status', '--porcelain=v1', '-z', '--untracked-files=all'))
.toContain('staged.txt');
expect(git('rev-parse', 'HEAD')).not.toBe(base);
} finally {
rmSync(root, { recursive: true, force: true });
}
});
});
describe('describeBrowserSelection', () => {
const selected = BROWSER_SUITES.slice(0, 10);
const fidelity = BROWSER_FIDELITY_FILES[0];
it('distinguishes no selection from a selection with fidelity cases', () => {
expect(describeBrowserSelection([]).join('\n')).toContain('none selected');
const some = describeBrowserSelection([fidelity, ...selected]).join('\n');
expect(some).toContain('selected');
expect(some).toContain('nightly and on the release PR');
expect(describeBrowserSelection(selected.filter((file) => !BROWSER_FIDELITY_FILES.includes(file))).join('\n'))
.not.toContain('Fidelity cases');
});
});
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({ supercolliderLive: true })))
.toEqual([{ suite: 'supercolliderLive', reason: 'needs a native Linux Docker engine on amd64 and arm64', remedy: UNCOVERED_SUITES.supercolliderLive }]);
expect(uncoveredSuites(planWith({ dockerContainmentLive: true })))
.toEqual([{ suite: 'dockerContainmentLive', reason: 'needs a real Docker engine and pulls the pinned Node image', remedy: UNCOVERED_SUITES.dockerContainmentLive }]);
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', 'local focused mode; hosted CI runs it (opt in locally with --full)'],
['browser', 'local focused mode; hosted CI runs it (opt in locally with --full)'],
['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('reports a probe lifecycle failure apart from a missing prerequisite and keeps browser uncovered', () => {
const probeFailed = uncoveredSuites(selected, {
prerequisites: { browser: { ok: false, reason: 'Chrome with H.264 probe failed (teardown-failed)', category: 'probe-failed' } },
}).find(({ suite }) => suite === 'browser');
expect(probeFailed.reason).toBe('probe failed: Chrome with H.264 probe failed (teardown-failed)');
expect(probeFailed.category).toBe('probe-failed');
expect(probeFailed.remedy).not.toBe(UNCOVERED_SUITES.browser);
expect(probeFailed.remedy).not.toMatch(/installed/);
const missing = uncoveredSuites(selected, {
prerequisites: { browser: { ok: false, reason: 'missing ffmpeg', category: 'missing' } },
}).find(({ suite }) => suite === 'browser');
expect(missing).toMatchObject({ reason: 'prerequisite missing: missing ffmpeg', category: 'missing', remedy: UNCOVERED_SUITES.browser });
const skip = Object.fromEntries([probeFailed].map(({ suite }) => [suite, true]));
expect(resolvePlanStages(selected, { skip }).some((stage) => stage.suite === 'browser')).toBe(false);
});
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' }, { ownsGroup: false });
expect(env).toEqual({ KEEP: 'x', PGDATABASE: 'portos_test', PORTOS_PREGATE_MAX_WORKERS: String(cosWorkerBudget()) });
expect('TEST_DB_OK' in env).toBe(false);
});
it('keeps the test runner\'s npm and Vitest inside the stage group pregate owns', () => {
expect(stageSpawnEnv({}, {}, { ownsGroup: true }).PORTOS_CI_TEST_SUPERVISED_GROUP).toBe('1');
});
});
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('uncreatableExtensions', () => {
it('flags a missing extension a non-superuser cannot create, and nothing else', () => {
expect(uncreatableExtensions({ installed: ['pgcrypto'], trusted: [], superuser: false })).toEqual(['vector']);
expect(uncreatableExtensions({ installed: [], trusted: ['vector', 'pgcrypto'], superuser: false })).toEqual([]);
expect(uncreatableExtensions({ installed: ['vector', 'pgcrypto'], trusted: [], superuser: false })).toEqual([]);
expect(uncreatableExtensions({ installed: [], trusted: [], superuser: true })).toEqual([]);
});
});
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`);
});
// A single pg connection queues overlapping queries (and pg@9 drops that), so the probe must await them in turn.
const fakeClient = ({ installed = [], trusted = [], superuser = true }) => {
let inFlight = false;
const respond = (sql) => {
if (sql.includes('pg_extension')) return { rows: installed.map((extname) => ({ extname })) };
if (sql.includes('pg_available_extension_versions')) return { rows: trusted.map((name) => ({ name })) };
if (sql.includes('pg_roles')) return { rows: [{ rolsuper: superuser }] };
return { rows: [] };
};
return {
connect: async () => {},
end: async () => {},
query(sql) {
if (inFlight) throw new Error('overlapping query on one client');
inFlight = true;
return Promise.resolve().then(() => {
inFlight = false;
return respond(sql);
});
},
};
};
const probeWith = (opts) => probeTestDatabase(
{ PGHOST: '127.0.0.1', PGPORT: '5432', PGUSER: 'portos', PGPASSWORD: 'portos' },
{ repoRoot: REPO_ROOT, createClient: () => fakeClient(opts) },
);
it('awaits its extension and role probes in turn on the single client', async () => {
const result = await probeWith({ installed: ['vector', 'pgcrypto'] });
expect(result).toEqual({ ok: true, endpoint: `127.0.0.1:5432/${TEST_DATABASE}`, provision: false });
});
it('still names a missing extension a non-superuser cannot create', async () => {
const result = await probeWith({ installed: ['pgcrypto'], superuser: false });
expect(result.ok).toBe(false);
expect(result.reason).toMatch(/^Postgres extension\(s\) vector missing/);
});
});
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(3);
expect(report.plan.downgraded).toBe(false);
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);
expect(buildPregateReport({
plan: planWith(), options: {}, base: {}, head: {}, tree: 't', stages: [], skipped: [], runtime: {}, startedAt: 's', finishedAt: 'f', downgraded: true,
}).plan.downgraded).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 });
}
});
});
describe('focused local policy', () => {
it('runs direct behavior owners and edited unit tests without transitive or resource suites', () => {
const tracked = ['server/lib/a.js', 'server/lib/a.test.js', 'server/lib/unrelated.test.js', 'server/lib/a.db.test.js', 'server/lib/a.browser.test.js', 'client/src/Card.jsx', 'client/src/Card.test.jsx', 'scripts/tool.test.js', 'server/services/htmlComposition/index.test.js'];
const changed = ['server/lib/a.js', 'client/src/Card.jsx', 'scripts/tool.test.js', 'server/lib/a.db.test.js', 'server/lib/a.browser.test.js', 'docs/README.md', 'server/services/htmlComposition/index.test.js'];
const local = focusedLocalPlan(planWith({ browser: { files: ['server/services/htmlComposition/index.test.js'] }, server: { mode: 'related', files: ['server/lib/unrelated.test.js'], sources: ['server/lib/a.js'] } }), tracked, changed);
expect(local.server).toEqual({ mode: 'files', files: ['server/lib/a.test.js', 'scripts/tool.test.js'], sources: [] });
expect(local.client.files).toContain('client/src/Card.test.jsx');
expect(resolvePlanStages(local, { skip: { db: true, browser: true, build: true, smoke: true } }).every(stage => !['db', 'browser', 'build', 'smoke'].includes(stage.suite))).toBe(true);
});
});