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
import { spawn } from './childProcess.js';
import { mkdtempSync, rmSync } from 'node:fs';
import { createRequire } from 'node:module';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
// The one Chrome resolver lives in scripts/lib so client tests can share it (#12315).
export { resolveTestChrome } from '../../scripts/lib/testChrome.js';
const CLIENT_BUNDLER_PACKAGES = Object.freeze(['vite', '@vitejs/plugin-react', '@tailwindcss/postcss']);
/**
* The resolved paths of the client workspace's bundler packages (Vite, its
* React plugin, Tailwind's PostCSS plugin), or undefined when any is missing —
* the shape a `browserSuiteCanRun` prerequisite map treats as absent. Only
* MODULE_NOT_FOUND counts as missing; any other resolution error throws.
*/
export function resolveClientBundler(repoRoot) {
try {
const requireClient = createRequire(join(repoRoot, 'client', 'package.json'));
return CLIENT_BUNDLER_PACKAGES.map((name) => requireClient.resolve(name));
} catch (error) {
if (error.code !== 'MODULE_NOT_FOUND') throw error;
return undefined;
}
}
/**
* Keep cross-workspace browser suites as visible skips on machines without
* Chrome, ffmpeg or the client workspace, while letting the one CI job that
* provisions them fail fast instead of passing green on a skip.
*
* `prerequisites` maps a human label to whatever was discovered (a path, a
* resolved bundler list, or undefined/null when absent; `chromeWithH264` may
* also report `{ probeFailure }` for a probe that ran and failed). `onUnavailable` runs
* before the skip or the throw: prerequisite discovery can initialize mocked
* path fixtures, and Vitest runs no cleanup hooks for a skipped (or failed) file.
*
* `browserSuiteBlockReason` is the verdict alone (null when every prerequisite
* is present), so a caller that only reports — the local pregate — can share
* the exact wording the suites print without the skip/throw side effects.
*/
export function browserSuiteBlockReason(prerequisites) {
const entries = Object.entries(prerequisites);
// A probe that ran but failed is a distinct verdict from an absent prerequisite.
const failed = entries.filter(([, found]) => found?.probeFailure);
const missing = entries.filter(([, found]) => !found).map(([name]) => name);
if (missing.length === 0 && failed.length === 0) return null;
return [
...(missing.length ? [`missing ${missing.join(', ')}`] : []),
...failed.map(([name, found]) => `${name} probe failed (${found.probeFailure})`),
].join('; ');
}
export function browserSuiteCanRun(label, prerequisites, { onUnavailable } = {}) {
const reason = browserSuiteBlockReason(prerequisites);
if (reason === null) return true;
onUnavailable?.();
if (process.env.PORTOS_REQUIRE_BROWSER_SUITES) {
throw new Error(`${label}: browser suite skipped but PORTOS_REQUIRE_BROWSER_SUITES is set — ${reason}`);
}
console.log(`⏭️ ${label}: skipping suite — ${reason}`);
return false;
}
const H264_PROBE_PAGE = `data:text/html,<body><script>document.body.textContent='H264:'+document.createElement('video').canPlayType('video/mp4; codecs="avc1.640028"')</script></body>`;
// Kept free of bufferedSpawn.js on purpose: this module is imported ahead of
// `vi.mock('./paths.js')` factories, and that import graph reaches paths.js.
const IS_WIN32 = process.platform === 'win32';
const MAX_OUTPUT_BYTES = 64 * 1024;
// Signals the probe's whole process group (it was spawned detached) so Chrome's
// helper processes go with it; Windows takes the tree down with taskkill.
function killProbeTree(child, signal, processGroup) {
if (IS_WIN32 && child.pid) {
spawn('taskkill', ['/T', '/F', '/PID', String(child.pid)], { stdio: 'ignore' }).on('error', () => {}).unref();
return;
}
if (processGroup && child.pid) {
try { process.kill(-child.pid, signal); return; } catch { /* group already gone */ }
}
child.kill(signal);
}
const PROBE_TIMEOUT_MS = 20000;
const PROBE_KILL_GRACE_MS = 5000;
// Runs the probe as an owned child: its own process group on POSIX, a bounded
// deadline, and a SIGTERM -> SIGKILL ladder that waits for `close` so the
// outcome says whether cleanup was actually observed. stderr is discarded, so
// no raw browser output (paths, PIDs) can reach a caller.
function runOwnedProbe(file, args, { timeoutMs, graceMs }) {
return new Promise((resolve) => {
const processGroup = !IS_WIN32;
const child = spawn(file, args, { stdio: ['ignore', 'pipe', 'ignore'], detached: processGroup });
const timers = [];
let stdout = '';
let timedOut = false;
let settled = false;
const finish = (outcome) => {
if (settled) return;
settled = true;
timers.forEach(clearTimeout);
// Reap renderer/GPU helpers a slow-exiting Chrome may have left behind.
killProbeTree(child, 'SIGKILL', processGroup);
child.stdout?.destroy();
resolve({ stdout, timedOut, ...outcome });
};
child.stdout.on('data', (chunk) => {
stdout = (stdout + chunk).slice(-MAX_OUTPUT_BYTES);
});
child.on('error', (error) => finish({ spawnErrorCode: error.code ?? 'UNKNOWN', cleanupVerified: true }));
child.on('close', (code, signal) => finish({ code, signal, cleanupVerified: true }));
timers.push(setTimeout(() => {
timedOut = true;
killProbeTree(child, 'SIGTERM', processGroup);
timers.push(setTimeout(() => {
killProbeTree(child, 'SIGKILL', processGroup);
timers.push(setTimeout(() => finish({ cleanupVerified: false }), graceMs));
}, graceMs));
}, timeoutMs));
});
}
/**
* Probes whether a Chrome binary can decode H.264 and says why when it cannot.
* Resolves `{ ok: true, chromePath }` or `{ ok: false, cause, ... }` with cause:
* - `missing-executable` — no path, or the file does not exist
* - `codec-unavailable` — Chrome answered cleanly and reported no H.264
* - `probe-timeout` — no exit within the deadline (`cleanupVerified` says whether
* the child was observed to close after the kill ladder)
* - `teardown-failed` — Chrome answered but then exited nonzero or by signal;
* the codec answer is NOT trusted from a probe that did not shut down cleanly
* - `no-answer` — Chrome did not report a codec verdict at all
* Never rejects; the profile directory is removed once the child is settled.
*/
export async function probeChromeH264(chromePath, { timeoutMs = PROBE_TIMEOUT_MS, graceMs = PROBE_KILL_GRACE_MS } = {}) {
if (!chromePath) return { ok: false, cause: 'missing-executable' };
const profile = mkdtempSync(join(tmpdir(), 'portos-h264-probe-'));
try {
const run = await runOwnedProbe(chromePath, [
'--headless=new', '--disable-gpu', '--no-sandbox',
'--no-first-run', '--no-default-browser-check',
'--disable-background-networking', '--disable-component-update',
'--disable-sync', '--disable-breakpad',
'--password-store=basic', '--use-mock-keychain',
`--user-data-dir=${profile}`, '--virtual-time-budget=2000', '--dump-dom', H264_PROBE_PAGE,
], { timeoutMs, graceMs });
if (run.spawnErrorCode) {
return { ok: false, cause: ['ENOENT', 'ENOTDIR'].includes(run.spawnErrorCode) ? 'missing-executable' : 'no-answer' };
}
if (run.timedOut) return { ok: false, cause: 'probe-timeout', timeoutMs, cleanupVerified: run.cleanupVerified };
const answer = /H264:(\w*)/.exec(run.stdout);
if (run.code !== 0) {
return { ok: false, cause: answer ? 'teardown-failed' : 'no-answer', exit: run.code ?? run.signal };
}
if (!answer) return { ok: false, cause: 'no-answer', exit: 0 };
return answer[1] ? { ok: true, chromePath } : { ok: false, cause: 'codec-unavailable' };
} finally {
rmSync(profile, { recursive: true, force: true });
}
}
/** One-line, path/PID-free description of a failed `probeChromeH264` result. */
export function describeH264Probe({ cause, exit, timeoutMs, cleanupVerified }) {
switch (cause) {
case 'missing-executable': return 'Chrome executable not found';
case 'codec-unavailable': return 'Chrome reports no H.264 decode support';
case 'probe-timeout':
return `Chrome H.264 probe timed out after ${Math.round(timeoutMs / 1000)}s; child cleanup ${cleanupVerified ? 'verified' : 'unverified'}`;
case 'teardown-failed':
return `Chrome answered the H.264 probe but then failed to shut down cleanly (exit ${exit}); a browser lifecycle failure, not a missing codec`;
default: return `Chrome H.264 probe produced no codec answer${exit === undefined ? '' : ` (exit ${exit})`}`;
}
}
/**
* Whether a Chrome binary can decode H.264 (Playwright's bundled Chromium has
* no proprietary codecs). Resolves the binary path when it can, null when the
* executable or the codec is genuinely absent — so it drops straight into a
* `browserSuiteCanRun` prerequisite map — and `{ probeFailure }` when the probe
* itself failed, which `browserSuiteCanRun` reports as a lifecycle failure
* rather than a missing prerequisite.
*/
export async function chromeWithH264(chromePath, options) {
const result = await probeChromeH264(chromePath, options);
if (result.ok) return result.chromePath;
if (result.cause === 'missing-executable' || result.cause === 'codec-unavailable') return null;
return { probeFailure: result.cause === 'probe-timeout' && !result.cleanupVerified
? 'probe-timeout, cleanup unverified' : result.cause };
}