wishforge-ide/scripts/local-poc-service.mjs
eust-w f02c3c649c 🩺 Check in doctor what POC runs need beyond this machine
doctor only looked at the local services. A POC run also needs the
cluster API to build and deploy, the Gitea branch to start from and
push to, the public application to accept a release on, the Claude CLI
and room on the disk; when one of them was down, doctor still said
ready, and a wish found out minutes later, at its build.

doctor now checks them read only, without a model call: the cluster's
readiness, the branch head as builds read it and as integration reaches
it over the operator's SSH login, the build commit the application
reports and whether it is the branch head, the CLI's version and the
free space where runs live. A failing one is named with the first line
of its error and makes the report degraded. start does not wait on
them, so a network problem cannot hold up starting the service.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-27 11:18:51 +08:00

360 lines
14 KiB
JavaScript

#!/usr/bin/env node
// This is an opt-in user LaunchAgent; importing or running without arguments only reports status.
import { spawn, spawnSync } from 'node:child_process';
import {
appendFileSync,
chmodSync,
existsSync,
mkdirSync,
readFileSync,
renameSync,
rmSync,
statSync,
writeFileSync,
} from 'node:fs';
import { homedir } from 'node:os';
import path from 'node:path';
import { fileURLToPath, pathToFileURL } from 'node:url';
import { setTimeout as delay } from 'node:timers/promises';
import { localPocDoctor, waitForReadiness } from './local-poc-doctor.mjs';
export const LABEL = 'cc.d-robotics.wishforge.local-poc';
export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const NODE = '/opt/homebrew/bin/node';
const SCRIPT = path.join(ROOT, 'scripts/local-poc-service.mjs');
const STATE_ROOT = path.join(ROOT, '.wishforge/local-poc');
const LOG_ROOT = path.join(STATE_ROOT, 'logs');
const STATE_FILE = path.join(STATE_ROOT, 'service-state.json');
const RUNNER_ENV = path.join(STATE_ROOT, 'runner.env');
const PLIST = path.join(homedir(), 'Library/LaunchAgents', `${LABEL}.plist`);
const DOMAIN = `gui/${process.getuid?.()}`;
const SERVICE = `${DOMAIN}/${LABEL}`;
const MAX_LOG_BYTES = 5 * 1024 * 1024;
export function parseServiceAction(argv) {
if (!argv.length) return 'status';
if (argv.length !== 1 || !['install', 'start', 'status', 'doctor', 'stop', 'run'].includes(argv[0]))
throw new Error('Usage: local-poc-service.mjs install|start|status|doctor|stop');
return argv[0];
}
export function minimalEnvironment(home = homedir()) {
return {
PATH: '/opt/homebrew/bin:/usr/bin:/bin:/usr/sbin:/sbin',
HOME: home,
LANG: 'en_US.UTF-8',
TMPDIR: path.join(STATE_ROOT, 'tmp'),
};
}
const escapeXml = value =>
String(value).replace(
/[<>&"']/g,
character => ({ '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&apos;' })[character],
);
export function launchAgentPlist(root = ROOT, home = homedir()) {
const strings = values => values.map(value => `<string>${escapeXml(value)}</string>`).join('');
const env = minimalEnvironment(home);
return `<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0"><dict>
<key>Label</key><string>${LABEL}</string>
<key>ProgramArguments</key><array>${strings([NODE, path.join(root, 'scripts/local-poc-service.mjs'), 'run'])}</array>
<key>WorkingDirectory</key><string>${escapeXml(root)}</string>
<key>EnvironmentVariables</key><dict>${Object.entries(env)
.map(([key, value]) => `<key>${key}</key><string>${escapeXml(value)}</string>`)
.join('')}</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key><true/>
<key>ThrottleInterval</key><integer>15</integer>
<key>ExitTimeOut</key><integer>30</integer>
<key>Umask</key><integer>63</integer>
<key>ProcessType</key><string>Background</string>
<key>StandardOutPath</key><string>/dev/null</string>
<key>StandardErrorPath</key><string>/dev/null</string>
</dict></plist>\n`;
}
export function rotateAppend(file, bytes, maxBytes = MAX_LOG_BYTES, backups = 3) {
const content = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes));
mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
chmodSync(path.dirname(file), 0o700);
if (existsSync(file) && statSync(file).size + content.length > maxBytes) {
rmSync(`${file}.${backups}`, { force: true });
for (let index = backups - 1; index >= 1; index--)
if (existsSync(`${file}.${index}`)) renameSync(`${file}.${index}`, `${file}.${index + 1}`);
renameSync(file, `${file}.1`);
}
appendFileSync(file, content.subarray(Math.max(0, content.length - maxBytes)), { mode: 0o600 });
chmodSync(file, 0o600);
}
const log = message => rotateAppend(path.join(LOG_ROOT, 'supervisor.log'), `${new Date().toISOString()} ${message}\n`);
function requirePrivateFile(file) {
const info = statSync(file);
if (!info.isFile() || info.uid !== process.getuid() || info.mode & 0o077)
throw new Error(`${file} must be owned by the current user with permissions 0600`);
}
function preflight() {
if (process.platform !== 'darwin') throw new Error('This service uses the macOS user LaunchAgent domain');
if (existsSync(path.join(STATE_ROOT, 'web-build.lock')))
throw new Error('A protected web build is in progress; finish or recover it before starting services');
for (const file of [NODE, SCRIPT, path.join(ROOT, 'scripts/dev.mjs'), path.join(ROOT, 'apps/runner/src/main.ts')])
if (!statSync(file).isFile()) throw new Error(`Missing required file: ${file}`);
requirePrivateFile(path.join(ROOT, '.env.local'));
requirePrivateFile(RUNNER_ENV);
const keys = readFileSync(RUNNER_ENV, 'utf8')
.split('\n')
.filter(line => line.trim() && !line.trim().startsWith('#'))
.map(line => line.match(/^([A-Z][A-Z0-9_]*)=/)?.[1]);
if (
keys.some(
key =>
!key ||
!/^(WF_RUNNER_[A-Z0-9_]+|WF_POC_PROFILE_FILE|WF_CONTROL_PLANE_URL|WF_TENANT_ID|WF_ENVIRONMENT_ID|WF_DEPLOYMENT_MODE)$/.test(
key,
),
)
)
throw new Error('runner.env contains unsupported variables; keep API, model and database credentials out of it');
for (const directory of [STATE_ROOT, LOG_ROOT, minimalEnvironment().TMPDIR]) {
mkdirSync(directory, { recursive: true, mode: 0o700 });
chmodSync(directory, 0o700);
}
}
function launchctl(args, checked = true) {
const result = spawnSync('/bin/launchctl', args, { encoding: 'utf8', env: minimalEnvironment(), timeout: 35000 });
if (checked && result.status !== 0)
throw new Error(`launchctl ${args[0]} failed: ${(result.stderr || result.error?.message || '').trim()}`);
return result;
}
const registered = () => launchctl(['print', SERVICE], false).status === 0;
export function processStatus(result, state) {
const pid = result.status === 0 ? Number(result.stdout.match(/^\s*pid = (\d+)$/m)?.[1]) || null : null;
const current = Boolean(pid && state?.supervisorPid === pid);
return {
label: LABEL,
installed: existsSync(PLIST),
registered: result.status === 0,
state: result.status === 0 ? (result.stdout.match(/^\s*state = (.+)$/m)?.[1] ?? 'unknown') : 'stopped',
pid,
lastExitCode: result.stdout?.match(/^\s*last exit code = (.+)$/m)?.[1] ?? null,
workspace: ROOT,
logs: LOG_ROOT,
stateSnapshot: current ? 'current' : state ? 'stale' : 'absent',
children:
current && Array.isArray(state.children)
? state.children
.filter(
child => ['platform', 'runner'].includes(child.name) && Number.isSafeInteger(child.pid) && child.pid > 0,
)
.map(({ name, pid }) => ({ name, pid }))
: [],
};
}
function status() {
const result = launchctl(['print', SERVICE], false);
let state = null;
try {
state = JSON.parse(readFileSync(STATE_FILE, 'utf8'));
} catch {
/* A stopped or never-started service has no state. */
}
return processStatus(result, state);
}
function remainingOwnedProcesses(tracked) {
if (!tracked.length) return [];
const result = spawnSync('/bin/ps', ['-axo', 'pid=,command='], { encoding: 'utf8', timeout: 3000 });
if (result.status !== 0) return null;
const current = new Map(
result.stdout.split('\n').flatMap(line => {
const match = line.trim().match(/^(\d+)\s+(.+)$/);
return match ? [[Number(match[1]), match[2]]] : [];
}),
);
// Parent IDs can change while launchd tears down the service. Match the captured
// PID and its known script, so an orphan is still awaited and a reused PID is not.
return tracked.filter(item => current.get(item.pid)?.includes(item.script)).map(item => item.pid);
}
export async function stopLocalService({
inspect = status,
control = launchctl,
remaining = remainingOwnedProcesses,
timeoutMs = 45000,
intervalMs = 500,
now = Date.now,
sleep = delay,
} = {}) {
const deadline = now() + timeoutMs;
const before = inspect();
const tracked = [
...(before.pid ? [{ pid: before.pid, script: SCRIPT }] : []),
...(before.children ?? []).map(child => ({
pid: child.pid,
script: path.join(ROOT, child.name === 'platform' ? 'scripts/dev.mjs' : 'apps/runner/src/main.ts'),
})),
];
control(['disable', SERVICE]);
if (before.registered) control(['bootout', SERVICE]);
while (true) {
const report = inspect();
const active = remaining(tracked);
if (!report.registered && active !== null && !active.length)
return { ...report, stopCompleted: true, remainingOwnedProcesses: [] };
if (now() >= deadline)
return {
...report,
stopCompleted: false,
remainingOwnedProcesses: active,
stopDetail:
active === null
? 'Could not verify owned process termination; inspect status before building or starting'
: 'Timed out waiting for launchd removal and owned process termination; inspect status before building or starting',
};
await sleep(Math.min(intervalMs, Math.max(0, deadline - now())));
}
}
async function supervise() {
preflight();
process.umask(0o077);
const children = [];
let stopping = false;
let finish;
const stopped = new Promise(resolve => {
finish = resolve;
});
const stop = async code => {
if (stopping) return;
stopping = true;
log(`Stopping this supervisor's ${children.length} children`);
await Promise.all(
children.map(
child =>
new Promise(resolve => {
if (child.exitCode !== null || child.signalCode !== null) return resolve();
const timer = setTimeout(() => child.kill('SIGKILL'), 20000);
child.once('close', () => {
clearTimeout(timer);
resolve();
});
child.kill('SIGTERM');
}),
),
);
rmSync(STATE_FILE, { force: true });
finish(code);
};
for (const signal of ['SIGTERM', 'SIGINT'])
process.once(signal, () => {
void stop(0);
});
const specifications = [
{ name: 'platform', args: [path.join(ROOT, 'scripts/dev.mjs')] },
{
name: 'runner',
args: [`--env-file=${RUNNER_ENV}`, '--import', 'tsx', path.join(ROOT, 'apps/runner/src/main.ts')],
},
];
for (const specification of specifications) {
// Deliberately build a fresh environment for each child. Only dev.mjs loads .env.local;
// Node loads the separate runner.env directly for the runner process.
const child = spawn(NODE, specification.args, {
cwd: ROOT,
// dev.mjs must not adopt a service still answering from an earlier, possibly older start.
env: {
...minimalEnvironment(),
...(specification.name === 'platform' ? { WF_LOCAL_REUSE_SERVICES: 'false' } : {}),
},
shell: false,
stdio: ['ignore', 'pipe', 'pipe'],
});
children.push(child);
for (const stream of [child.stdout, child.stderr])
stream.on('data', bytes => rotateAppend(path.join(LOG_ROOT, `${specification.name}.log`), bytes));
child.once('error', error => {
log(`${specification.name}: ${error.message}`);
void stop(1);
});
child.once('exit', code => {
log(`${specification.name} exited ${code ?? 'by signal'}`);
if (!stopping) void stop(code || 1);
});
log(`Started ${specification.name} pid=${child.pid}`);
}
writeFileSync(
STATE_FILE,
`${JSON.stringify({ supervisorPid: process.pid, startedAt: new Date().toISOString(), children: children.map((child, index) => ({ name: specifications[index].name, pid: child.pid })) }, null, 2)}\n`,
{ mode: 0o600 },
);
return stopped;
}
export async function main(argv = process.argv.slice(2)) {
const action = parseServiceAction(argv);
if (action === 'run') return supervise();
if (process.platform !== 'darwin') throw new Error('This service uses macOS launchd');
if (action === 'doctor') {
// Only here, not while start waits: these reach the cluster, Gitea and the public application.
const report = await localPocDoctor(ROOT, status(), { dependencies: true });
console.log(JSON.stringify(report, null, 2));
return report.status === 'ready' ? 0 : 1;
}
if (action === 'install') {
preflight();
const content = launchAgentPlist();
if (existsSync(PLIST) && readFileSync(PLIST, 'utf8') !== content && registered())
throw new Error('Stop this LaunchAgent before changing its installed configuration');
mkdirSync(path.dirname(PLIST), { recursive: true });
const temporary = `${PLIST}.tmp`;
writeFileSync(temporary, content, { mode: 0o600 });
chmodSync(temporary, 0o600);
const validated = spawnSync('/usr/bin/plutil', ['-lint', temporary], { encoding: 'utf8' });
if (validated.status !== 0) {
rmSync(temporary, { force: true });
throw new Error('Generated LaunchAgent plist failed validation');
}
renameSync(temporary, PLIST);
launchctl(['enable', SERVICE]);
if (!registered()) launchctl(['bootstrap', DOMAIN, PLIST]);
launchctl(['kickstart', SERVICE]);
} else if (action === 'start') {
preflight();
if (!existsSync(PLIST)) throw new Error('Run install once to create this user LaunchAgent');
if (readFileSync(PLIST, 'utf8') !== launchAgentPlist())
throw new Error('Installed LaunchAgent differs from this checkout; stop and install it again');
launchctl(['enable', SERVICE]);
if (!registered()) launchctl(['bootstrap', DOMAIN, PLIST]);
launchctl(['kickstart', SERVICE]);
} else if (action === 'stop') {
const report = await stopLocalService();
console.log(JSON.stringify(report, null, 2));
return report.stopCompleted ? 0 : 1;
}
if (action === 'install' || action === 'start') {
const report = await waitForReadiness(() => localPocDoctor(ROOT, status()));
console.log(JSON.stringify(report, null, 2));
// Local listeners alone are insufficient when the requested LAN entry is rejected.
return report.status === 'ready' ? 0 : 1;
}
console.log(JSON.stringify(status(), null, 2));
return 0;
}
if (process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === import.meta.url)
main()
.then(code => {
process.exitCode = code;
})
.catch(error => {
if (process.argv[2] === 'run') log(error.message);
else console.error(error.message);
process.exitCode = 1;
});