One live console to monitor Claude Code and Codex agents across machines, track context and spend, and unblock sessions that need you.
#!/usr/bin/env -S npx tsx
// SITREP install: the server as a user service, and a machine's reporters. The service is a systemd --user unit
// on Linux (with the linger hint) or a launchd agent on macOS, with a config file of KEY=VALUE lines, mode 0600, holding a
// generated admin secret. Both reporters are installed as plugins: a plugin marketplace, then install.
//
// Dry run by default: it prints every file it would write and every command it would run, and changes nothing until
// --apply. The `claude` and `codex` plugin commands make their own entries (marketplace, enable, options), and our Codex
// hooks are trusted through Codex's own app-server API as its /hooks screen does. The one provider setting it writes itself
// is Claude Code's telemetry, which a plugin cannot set: `env` and `otelHeadersHelper` in Claude Code's user settings,
// merged into what is there. No hook entry is ever touched. scripts/uninstall.ts removes what this adds.
import { spawn, spawnSync } from 'node:child_process';
import { randomBytes } from 'node:crypto';
import { once } from 'node:events';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { createInterface } from 'node:readline';
import { fileURLToPath } from 'node:url';
import { parseArgs } from 'node:util';
// The release's manifest, for the version this script gives as its own when it connects to Codex.
import release from '../package.json' with { type: 'json' };
const HELP = `install: set up the SITREP server and this machine's reporters.
Usage: npx tsx scripts/install.ts <component...> [options]
Dry run by default: prints every file it would write and every command it would run, and changes nothing.
Add --apply to make the changes. Run it again after an upgrade; it is safe to repeat.
Components (name at least one):
--server The dashboard server as a user service (systemd --user on Linux, launchd on macOS) and its
config ~/.sitrep/server.env, with a new admin secret
--claude The Claude Code plugin sitrep-reporter, from this repository's plugin marketplace; and
Claude Code's telemetry, which carries its sessions' usage, to the same server: env and
otelHeadersHelper in ~/.claude/settings.json, with the admin secret in
~/.sitrep/claude-otel-token
--codex The Codex plugin sitrep-codex (its hooks), from this repository's plugin marketplace; the
codex-reporter user service with its config ~/.sitrep/codex-reporter.env; and trust for
the plugin's hooks, written as Codex's /hooks screen writes it
Options:
--url URL The server URL the reporters send to. Without it, on a machine with a server config (--server in
this run, or ~/.sitrep/server.env), both reporters are set to that server's address on
every run: host = --bind, else the saved HOST, else 127.0.0.1 (0.0.0.0 and :: mean 127.0.0.1; any
other address as given); port = --port, else the saved PORT, else 7487. On a machine without one,
a reporter keeps the URL it has, and a new one sends to http://127.0.0.1:7487
--bind ADDR Where the server listens (default 127.0.0.1; 0.0.0.0 lets other machines report). With --server only
--port N The server's port (default 7487). With --server only
--token-stdin Read the server's admin secret for the reporters from stdin. Without it the reporters use the
secret in this machine's ~/.sitrep/server.env when there is one
--apply Make the changes
-h, --help Show this help
To try the Claude plugin in one session without changing any Claude Code settings:
claude --plugin-dir <repo>/mod/claude-reporter`;
// ---- Where things live --------------------------------------------------------------------------
export const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const HOME = os.homedir();
/** The product's own folder on each machine: configs, the server's database, macOS service logs, the Codex hook spool. */
export const DATA_HOME = path.join(HOME, '.sitrep');
export const SERVER_ENV = path.join(DATA_HOME, 'server.env');
export const REPORTER_ENV = path.join(DATA_HOME, 'codex-reporter.env');
export const DB_DIR = path.join(DATA_HOME, 'data');
/** Claude Code's config folder, `$CLAUDE_CONFIG_DIR` or `~/.claude` (code.claude.com/docs/en/settings), as the reporters find it. */
const CLAUDE_DIR = path.resolve(process.env.CLAUDE_CONFIG_DIR?.trim() || path.join(HOME, '.claude'));
/** The machine id both reporters share; the first one to start makes it. */
export const MACHINE_ID_FILE = path.join(CLAUDE_DIR, 'sitrep-machine-id');
/** Claude Code's user settings, where its telemetry is set (a plugin cannot set it; code.claude.com/docs/en/monitoring-usage). */
export const CLAUDE_SETTINGS = path.join(CLAUDE_DIR, 'settings.json');
/**
* The admin secret Claude Code's telemetry sends, alone on one line, mode 0600, read by OTEL_HELPER. The plugin's own copy is
* a `sensitive` option in Claude Code's secure store, which gives a headers helper no way to read it (code.claude.com/docs/en/
* plugins-reference, "Fields that run through a shell"; `claude plugin configure --json` shows it empty), so install keeps
* this one as it keeps codex-reporter's.
*/
export const OTEL_TOKEN = path.join(DATA_HOME, 'claude-otel-token');
/** Claude Code's otelHeadersHelper: prints the token and machine headers. */
export const OTEL_HELPER = path.join(REPO_ROOT, 'scripts', 'claude-otel-headers.sh');
/**
* The settings install writes into the two config files: the server's names as server/src/index.ts reads them, and the
* Codex reporter's. scripts/*.env.example and docs/OPERATIONS.md list every setting of both.
*/
const KEYS = {
serverHost: 'HOST',
serverPort: 'PORT',
serverToken: 'SITREP_TOKEN',
serverDb: 'SITREP_DB',
reporterUrl: 'CODEX_REPORTER_SERVER_URL',
reporterToken: 'CODEX_REPORTER_TOKEN',
} as const;
/** The Claude plugin's option names, `serverUrl` and `token`, as mod/claude-reporter/.claude-plugin/plugin.json declares them. */
const CLAUDE_OPTIONS = { url: 'serverUrl', token: 'token' } as const;
export interface Service {
title: string;
/** systemd user unit name. */
unit: string;
/** launchd label. */
label: string;
/** The built entry point, run with `node --env-file=<envFile>`. */
entry: string;
envFile: string;
/** Where launchd writes the process's output (systemd keeps it in the journal). */
log: string;
/** The oldest Node it runs on, as its package.json's `engines` says: "24", "22.15". */
minNode: string;
}
export const SERVER: Service = {
title: 'SITREP server',
unit: 'sitrep.service',
label: 'dev.sitrep.server',
entry: path.join(REPO_ROOT, 'server', 'dist', 'index.js'),
envFile: SERVER_ENV,
log: path.join(DATA_HOME, 'server.log'),
minNode: '24',
};
export const CODEX_REPORTER: Service = {
title: 'SITREP codex-reporter',
unit: 'sitrep-codex-reporter.service',
label: 'dev.sitrep.codex-reporter',
entry: path.join(REPO_ROOT, 'codex-reporter', 'dist', 'codex-reporter', 'src', 'main.js'),
envFile: REPORTER_ENV,
log: path.join(DATA_HOME, 'codex-reporter.log'),
minNode: '22.15',
};
export const PLATFORM = process.platform === 'darwin' ? 'launchd' : process.platform === 'linux' ? 'systemd' : null;
export function serviceFile(svc: Service): string {
return PLATFORM === 'launchd' ? path.join(HOME, 'Library', 'LaunchAgents', `${svc.label}.plist`) : path.join(HOME, '.config', 'systemd', 'user', svc.unit);
}
/** A plugin marketplace in this repository: its name and its one plugin's id (`plugin@marketplace`). */
function marketplace(relative: string): { file: string; name: string; plugin: string } {
const file = path.join(REPO_ROOT, relative);
const json = JSON.parse(fs.readFileSync(file, 'utf8')) as { name: string; plugins: { name: string }[] };
return { file, name: json.name, plugin: `${json.plugins[0].name}@${json.name}` };
}
export const claudeMarket = () => marketplace('.claude-plugin/marketplace.json');
export const codexMarket = () => marketplace('.agents/plugins/marketplace.json');
// ---- Plans --------------------------------------------------------------------------------------
export type Action =
| { kind: 'mkdir'; path: string; mode: number }
| { kind: 'write'; path: string; content: string; mode: number; shown: string }
/** A file left as it is; with `mode`, that mode is applied again. */
| { kind: 'keep'; path: string; why: string; mode?: number }
| { kind: 'remove'; path: string }
| { kind: 'rmdir-if-empty'; path: string }
| { kind: 'run'; argv: string[]; input?: string; shownInput?: string; mayFail?: boolean; quiet?: boolean }
/** launchd target `gui/<uid>/<label>`: wait until `launchctl print` no longer finds it, or fail after UNLOAD_WAIT_S. */
| { kind: 'await-unload'; target: string }
/** Trust `plugin`'s hooks that Codex lists as untrusted or modified, as Codex's /hooks screen does. */
| { kind: 'trust-codex-hooks'; plugin: string }
/**
* Set (or, with null, remove) the telemetry keys in Claude Code's user settings, every other key kept. The file is read when
* this runs, since the `claude plugin` commands before it write the same file; `shown` is the change as planned.
*/
| { kind: 'claude-telemetry'; set: TelemetrySettings | null; shown: string }
| { kind: 'note'; text: string };
/**
* `launchctl bootout` returns while the job is still being torn down, and a `bootstrap` in that window fails ("Bootstrap
* failed: 5: Input/output error"), leaving the service unloaded. Homebrew's `brew services` waits it out the same way:
* once a second while launchd still has the label, up to a limit (Library/Homebrew/services/cli.rb).
*/
const UNLOAD_WAIT_S = 10;
export interface Step {
title: string;
/** What must be fixed before this step is applied; --apply leaves the step out while any is left. */
blockers: string[];
actions: Action[];
/** The steps after it need it: when it is left out or fails, they are left out too. */
prerequisite?: boolean;
}
export const tilde = (p: string): string => (p === HOME || p.startsWith(`${HOME}/`) ? `~${p.slice(HOME.length)}` : p);
/** Homebrew installs node under Cellar/<formula>/<version>, which `brew upgrade` deletes; opt/<formula> survives it. */
function stableNodePath(execPath: string): string {
const stable = execPath.replace(/^(.*)\/Cellar\/([^/]+)\/[^/]+\/(.*)$/, '$1/opt/$2/$3');
try {
return stable !== execPath && fs.realpathSync(stable) === fs.realpathSync(execPath) ? stable : execPath;
} catch {
return execPath;
}
}
const NODE = stableNodePath(process.execPath);
/** Whether this Node is at least `min` ("24", "22.15"): its major, then its minor. */
export function nodeAtLeast(min: string, have: string = process.versions.node): boolean {
const [major = 0, minor = 0] = have.split('.').map(Number);
const [needMajor = 0, needMinor = 0] = min.split('.').map(Number);
return major > needMajor || (major === needMajor && minor >= needMinor);
}
function systemdUnit(svc: Service): string {
// systemd expands % specifiers in all three lines; ExecStart also splits on spaces and expands $VARIABLES, and an
// Environment= assignment with spaces needs quotes (systemd.service(5), systemd.exec(5)).
const spec = (s: string): string => s.replace(/%/g, '%%');
const quote = (s: string): string => `"${s.replace(/(["\\])/g, '\\$1')}"`;
const arg = (s: string): string => (/[\s"'\\$%]/.test(s) ? quote(spec(s).replace(/\$/g, '$$$$')) : s);
const env = (s: string): string => (/[\s"'\\]/.test(s) ? quote(spec(s)) : spec(s));
return `[Unit]
Description=${svc.title}
After=network-online.target
[Service]
Type=simple
WorkingDirectory=${spec(REPO_ROOT)}
Environment=${env(`PATH=${process.env.PATH ?? '/usr/bin:/bin'}`)}
ExecStart=${[NODE, `--env-file=${svc.envFile}`, svc.entry].map(arg).join(' ')}
Restart=on-failure
RestartSec=3
[Install]
WantedBy=default.target
`;
}
function launchdPlist(svc: Service): string {
const x = (s: string): string => s.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>');
const args = [NODE, `--env-file=${svc.envFile}`, svc.entry];
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>${x(svc.label)}</string>
<key>ProgramArguments</key>
<array>
${args.map((a) => ` <string>${x(a)}</string>`).join('\n')}
</array>
<key>WorkingDirectory</key><string>${x(REPO_ROOT)}</string>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key><string>${x(process.env.PATH ?? '/usr/bin:/bin')}</string>
</dict>
<key>RunAtLoad</key><true/>
<key>KeepAlive</key>
<dict><key>SuccessfulExit</key><false/></dict>
<key>StandardOutPath</key><string>${x(svc.log)}</string>
<key>StandardErrorPath</key><string>${x(svc.log)}</string>
</dict>
</plist>
`;
}
export const uid = (): number => os.userInfo().uid;
/** Write the unit and (re)start it: a restart applies a changed unit or config. */
function enableService(svc: Service): Action[] {
const file = serviceFile(svc);
if (PLATFORM === 'launchd') {
const target = `gui/${String(uid())}/${svc.label}`;
return [
{ kind: 'write', path: file, content: launchdPlist(svc), mode: 0o644, shown: launchdPlist(svc) },
{ kind: 'run', argv: ['launchctl', 'bootout', target], mayFail: true, quiet: true },
{ kind: 'await-unload', target },
{ kind: 'run', argv: ['launchctl', 'bootstrap', `gui/${String(uid())}`, file] },
{ kind: 'note', text: `Logs: ${tilde(svc.log)}` },
];
}
return [
{ kind: 'write', path: file, content: systemdUnit(svc), mode: 0o644, shown: systemdUnit(svc) },
{ kind: 'run', argv: ['systemctl', '--user', 'daemon-reload'] },
{ kind: 'run', argv: ['systemctl', '--user', 'enable', svc.unit] },
{ kind: 'run', argv: ['systemctl', '--user', 'restart', svc.unit] },
{ kind: 'note', text: `Logs: journalctl --user -u ${svc.unit} -f` },
{ kind: 'note', text: 'The service starts when you log in. To start it at boot and keep it running after you log out, run once: loginctl enable-linger $USER' },
];
}
/** Stop the service and remove its unit. Nothing to do when no unit file is there. */
export function disableService(svc: Service): Action[] {
const file = serviceFile(svc);
if (!fs.existsSync(file)) return [{ kind: 'note', text: `No service file at ${tilde(file)}; nothing to stop.` }];
if (PLATFORM === 'launchd') {
const target = `gui/${String(uid())}/${svc.label}`;
return [
{ kind: 'run', argv: ['launchctl', 'bootout', target], mayFail: true, quiet: true },
{ kind: 'await-unload', target },
{ kind: 'remove', path: file },
];
}
return [
{ kind: 'run', argv: ['systemctl', '--user', 'disable', '--now', svc.unit], mayFail: true },
{ kind: 'remove', path: file },
{ kind: 'run', argv: ['systemctl', '--user', 'daemon-reload'] },
];
}
/** Reads one KEY=VALUE from an env file's text; null when the key is absent. Quotes and a trailing comment are dropped. */
export function envValue(text: string, key: string): string | null {
for (const line of text.split('\n')) {
const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=(.*)$/.exec(line);
if (!m || m[1] !== key) continue;
const raw = m[2].trim();
const quoted = /^(["'`])(.*?)\1/.exec(raw);
return quoted ? quoted[2] : raw.replace(/\s+#.*$/, '').trim();
}
return null;
}
/** Sets keys in an env file's text, each on its own line in place, appended when missing. */
function setEnv(text: string, values: Record<string, string>): string {
let out = text;
for (const [key, value] of Object.entries(values)) {
const v = /[\s#"'`]/.test(value) ? `"${value}"` : value;
const re = new RegExp(`^(\\s*(?:export\\s+)?)${key}\\s*=.*$`, 'm');
out = re.test(out) ? out.replace(re, `$1${key}=${v}`) : `${out.replace(/\n?$/, '\n')}${key}=${v}\n`;
}
return out;
}
/** The text with the secret's value hidden, for printing. */
function hideSecret(text: string, key: string): string {
const value = envValue(text, key);
return value ? setEnv(text, { [key]: '(hidden)' }) : text;
}
/** Create a config from its template, or update only the given keys in the one there; keep it when nothing changes. */
function envFile(file: string, template: string, values: Record<string, string>, secretKey: string): Action {
const exists = fs.existsSync(file);
const base = fs.readFileSync(exists ? file : path.join(REPO_ROOT, 'scripts', template), 'utf8');
const content = setEnv(base, values);
if (exists && content === base) return { kind: 'keep', path: file, why: 'unchanged' };
return { kind: 'write', path: file, content, mode: 0o600, shown: hideSecret(content, secretKey) };
}
interface InstallOptions {
server: boolean;
claude: boolean;
codex: boolean;
url: string | null;
bind: string | null;
port: number | null;
secret: string | null;
}
/** The admin secret the reporters send: from stdin, else the one in this machine's server config (made in this run, or there already). */
function reporterSecret(o: InstallOptions, newServerSecret: string | null): string | null {
if (o.secret !== null) return o.secret;
if (newServerSecret) return newServerSecret;
if (!fs.existsSync(SERVER_ENV)) return null;
return envValue(fs.readFileSync(SERVER_ENV, 'utf8'), KEYS.serverToken) || null;
}
/**
* Where this machine's server listens after this run, as a URL its own reporters reach; null when the machine has no
* server config. server.env decides: this run's --bind and --port over its saved HOST and PORT, else the server's own
* defaults (server/src/index.ts). 0.0.0.0 and :: listen on every address, so 127.0.0.1 reaches them; a server bound to
* any other address listens only there (one on ::1 refuses 127.0.0.1; Node may bind localhost to ::1), so that address
* is used as given, an IPv6 one in brackets.
*/
export function localServerUrl(o: Pick<InstallOptions, 'server' | 'bind' | 'port'>): string | null {
const exists = fs.existsSync(SERVER_ENV);
if (!o.server && !exists) return null;
const saved = exists ? fs.readFileSync(SERVER_ENV, 'utf8') : '';
const host = (o.bind ?? envValue(saved, KEYS.serverHost)) || '127.0.0.1';
const port = o.port !== null ? String(o.port) : envValue(saved, KEYS.serverPort) || '7487';
const reach = host === '0.0.0.0' || host === '::' ? '127.0.0.1' : host.includes(':') ? `[${host}]` : host;
return `http://${reach}:${port}`;
}
/** Whether this machine's Claude Code has `plugin` installed, from `claude plugin list --json` (read only); null when it cannot tell. */
function claudeHasPlugin(plugin: string): boolean | null {
const r = spawnSync('claude', ['plugin', 'list', '--json'], { encoding: 'utf8', timeout: 30_000 });
if (r.status !== 0) return null;
try {
const list = JSON.parse(r.stdout) as unknown;
return Array.isArray(list) ? list.some((p) => (p as { id?: unknown } | null)?.id === plugin) : null;
} catch {
return null;
}
}
/** The Claude plugin's options as `claude plugin configure <plugin> --json` lists them: read only, secret values shown empty; null when it cannot tell. */
export function claudePluginOptions(plugin: string): { configured?: unknown; inputs?: { serverUrl?: unknown } } | null {
const r = spawnSync('claude', ['plugin', 'configure', plugin, '--json'], { encoding: 'utf8', timeout: 30_000 });
try {
return r.status === 0 ? (JSON.parse(r.stdout) as { configured?: unknown; inputs?: { serverUrl?: unknown } }) : null;
} catch {
return null;
}
}
/** The Claude plugin's default server URL, as mod/claude-reporter/.claude-plugin/plugin.json declares it. */
export const CLAUDE_DEFAULT_URL = 'http://127.0.0.1:7487';
/** The URL the Claude plugin sends to: its saved serverUrl, else its default. */
export function claudePluginUrl(options: ReturnType<typeof claudePluginOptions>): string {
const saved = options?.inputs?.serverUrl;
return (typeof saved === 'string' && saved ? saved : CLAUDE_DEFAULT_URL).replace(/\/+$/, '');
}
// ---- Claude Code telemetry ------------------------------------------------------------------------
export interface TelemetrySettings {
env: Record<string, string>;
otelHeadersHelper: string;
}
/**
* What install sets in Claude Code's user settings so its OTLP log events (one `claude_code.api_request` per API request,
* with that request's tokens) reach the server (code.claude.com/docs/en/monitoring-usage): logs only, their protocol and
* endpoint in the logs-only variables so no other exporter is touched, HTTP/JSON to the server's logs route as a full URL,
* which the exporter uses as given; exported each second, the reporters' cadence; no metrics or traces exporter.
* `otelHeadersHelper` prints the token and machine headers, so the secret stays out of the file; run by /bin/sh, it names no
* Node that a version manager or an upgrade can move.
*/
export function telemetrySettings(url: string): TelemetrySettings {
return {
env: {
CLAUDE_CODE_ENABLE_TELEMETRY: '1',
OTEL_LOGS_EXPORTER: 'otlp',
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL: 'http/json',
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: `${url}/api/fleet/v1/logs`,
OTEL_LOGS_EXPORT_INTERVAL: '1000',
},
otelHeadersHelper: ['/bin/sh', OTEL_HELPER].map(shellQuote).join(' '),
};
}
type Json = Record<string, unknown>;
const isObject = (v: unknown): v is Json => typeof v === 'object' && v !== null && !Array.isArray(v);
/** Claude Code's user settings; {} when there is no file. Throws when the file cannot be read or is not settings. */
export function readClaudeSettings(): Json {
let text: string;
try {
text = fs.readFileSync(CLAUDE_SETTINGS, 'utf8');
} catch (err) {
if ((err as NodeJS.ErrnoException).code === 'ENOENT') return {};
throw err;
}
const s = JSON.parse(text) as unknown;
if (!isObject(s) || (s.env !== undefined && !isObject(s.env))) throw new Error('not a JSON object with an object `env`');
return s;
}
/**
* Whether these settings run our helper, from any clone of this repository (its command ends in the script's own path, quoted
* or not; `.mjs`, run by Node, is the one installs wrote before): then their telemetry keys are the ones an install set, for
* install, uninstall and doctor to update, remove or check.
*/
export const ownsTelemetry = (s: Json): boolean => typeof s.otelHeadersHelper === 'string' && /\/scripts\/claude-otel-headers\.(?:sh|mjs)'?$/.test(s.otelHeadersHelper.trim());
/** The Claude step's telemetry: the secret for the helper, then the settings, merged into Claude Code's user settings. */
function telemetryPlan(url: string, secret: string | null): { blockers: string[]; actions: Action[] } {
let s: Json;
try {
s = readClaudeSettings();
} catch (err) {
return { blockers: [`${tilde(CLAUDE_SETTINGS)} cannot be read as Claude Code settings (${(err as Error).message}); fix it, then run this again`], actions: [] };
}
const env = (s.env ?? {}) as Json;
// Telemetry already set up by something else: its log events have one destination, and the dashboard would take it over.
const theirs = ownsTelemetry(s) ? [] : [
...Object.keys(env).filter((k) => k === 'CLAUDE_CODE_ENABLE_TELEMETRY' || k.startsWith('OTEL_')).map((k) => `env.${k}`),
...('otelHeadersHelper' in s ? ['otelHeadersHelper'] : []),
];
const blockers = theirs.length ? [`${tilde(CLAUDE_SETTINGS)} already sets Claude Code's telemetry (${theirs.join(', ')}); the dashboard would take over where its log events go. Remove those settings to send them to the dashboard instead`] : [];
const want = telemetrySettings(url);
const line = (key: string, value: string, old: unknown): string => `${key} = ${JSON.stringify(value)}${old === undefined ? '' : old === value ? ' (unchanged)' : ` (was ${JSON.stringify(old)})`}`;
const shown = [...Object.entries(want.env).map(([k, v]) => line(`env.${k}`, v, env[k])), line('otelHeadersHelper', want.otelHeadersHelper, s.otelHeadersHelper)].join('\n');
const actions: Action[] = [];
if (secret) {
const content = `${secret}\n`;
const same = fs.existsSync(OTEL_TOKEN) && fs.readFileSync(OTEL_TOKEN, 'utf8') === content;
actions.push({ kind: 'mkdir', path: DATA_HOME, mode: 0o700 }, same ? { kind: 'keep', path: OTEL_TOKEN, why: 'unchanged', mode: 0o600 } : { kind: 'write', path: OTEL_TOKEN, content, mode: 0o600, shown: '(the admin secret, hidden)' });
} else if (fs.existsSync(OTEL_TOKEN)) actions.push({ kind: 'keep', path: OTEL_TOKEN, why: 'no secret given; the one there stays', mode: 0o600 });
// Settings without a secret would have every export refused (401), which the exporter never retries: the usage is lost.
else blockers.push(`no admin secret for Claude Code's telemetry (none on stdin, in ${tilde(SERVER_ENV)} or in ${tilde(OTEL_TOKEN)}): re-run with --token-stdin`);
actions.push({ kind: 'claude-telemetry', set: want, shown });
if (!fs.existsSync(MACHINE_ID_FILE)) actions.push({ kind: 'note', text: `No machine id yet (${tilde(MACHINE_ID_FILE)}). Telemetry needs it; the plugin or codex-reporter makes it when it first starts, and the sessions started after that send their usage.` });
return { blockers, actions };
}
function serviceBlockers(svc: Service, built: string): string[] {
const out: string[] = [];
if (!PLATFORM) out.push(`user services are set up on Linux (systemd) and macOS (launchd) only, not ${process.platform}`);
if (!fs.existsSync(svc.entry)) out.push(`${path.relative(REPO_ROOT, svc.entry)} is missing: run \`npm ci && ${built}\` first`);
if (!nodeAtLeast(svc.minNode)) out.push(`the ${svc.title} needs Node ${svc.minNode} or later; this is Node ${process.versions.node} (${NODE})`);
return out;
}
function installPlan(o: InstallOptions): Step[] {
const steps: Step[] = [];
const port = o.port ?? 7487;
const localServer = localServerUrl(o);
// The URL both reporters are set to on this run, replacing a saved one: --url, else this machine's server. Null (no
// server here) keeps a reporter's saved URL, and a new one gets the Claude plugin's default.
const chosenUrl = o.url ?? localServer;
const url = chosenUrl ?? 'http://127.0.0.1:7487';
let newServerSecret: string | null = null;
if (o.server) {
const blockers = serviceBlockers(SERVER, 'npm run build');
if (!fs.existsSync(path.join(REPO_ROOT, 'frontend', 'dist', 'index.html'))) blockers.push('frontend/dist/index.html is missing: run `npm ci && npm run build` first');
const actions: Action[] = [{ kind: 'mkdir', path: DATA_HOME, mode: 0o700 }, { kind: 'mkdir', path: DB_DIR, mode: 0o700 }];
if (fs.existsSync(SERVER_ENV)) {
// An existing config keeps its secret and database; only --bind and --port change it, and they are saved there.
const values: Record<string, string> = {};
if (o.bind !== null) values[KEYS.serverHost] = o.bind;
if (o.port !== null) values[KEYS.serverPort] = String(o.port);
actions.push(envFile(SERVER_ENV, 'server.env.example', values, KEYS.serverToken));
} else {
// First install: a new admin secret.
newServerSecret = randomBytes(24).toString('hex');
actions.push(envFile(SERVER_ENV, 'server.env.example', {
[KEYS.serverHost]: o.bind ?? '127.0.0.1',
[KEYS.serverPort]: String(port),
[KEYS.serverDb]: path.join(DB_DIR, 'sitrep.sqlite'),
[KEYS.serverToken]: newServerSecret,
}, KEYS.serverToken));
actions.push({ kind: 'note', text: `The admin secret is in ${tilde(SERVER_ENV)} (${KEYS.serverToken}). You sign in with it to answer sessions, and every reporter sends it.` });
}
actions.push(...enableService(SERVER));
actions.push({ kind: 'note', text: `Open the dashboard at ${localServer ?? url}/ (from other machines: this machine's LAN address, with --bind 0.0.0.0 or that address).` });
// The server moves (a new HOST or PORT): this machine's reporters left out of this run still send to the old address.
const before = localServerUrl({ ...o, server: false, bind: null, port: null });
if (before !== null && before !== localServer) {
const left = [
...(!o.codex && fs.existsSync(REPORTER_ENV) ? [{ who: `codex-reporter (${tilde(REPORTER_ENV)})`, flag: '--codex' }] : []),
...(!o.claude && claudeHasPlugin(claudeMarket().plugin) ? [{ who: 'the Claude plugin', flag: '--claude' }] : []),
];
if (left.length) actions.push({ kind: 'note', text: `The server moves from ${before} to ${String(localServer)}: ${left.map((l) => l.who).join(' and ')} on this machine ${left.length > 1 ? 'keep their' : 'keeps its'} old URL. Re-run with ${left.map((l) => l.flag).join(' ')} to point them at the new address.` });
}
// The reporters below are given this server's address and secret, so they wait for it.
steps.push({ title: 'Server', blockers, actions, prerequisite: true });
}
const secret = reporterSecret(o, newServerSecret);
const reporterNotes: Action[] = secret ? [] : [{ kind: 'note', text: 'No admin secret given (--token-stdin) and none in this machine\'s server config: a reporter set up before keeps the secret it has, and a new one sends none, which a server with a secret refuses (HTTP 401).' }];
if (chosenUrl === null) reporterNotes.push({ kind: 'note', text: `No --url given and no server config on this machine: a reporter set up for the first time sends to ${url} (also the Claude plugin's default), and one set up before keeps its URL. Pass --url when the server runs on another machine.` });
if (o.codex) {
const market = codexMarket();
const blockers = serviceBlockers(CODEX_REPORTER, 'npm run build -w codex-reporter');
const manifest = path.join(REPO_ROOT, 'codex-reporter', 'plugin', '.codex-plugin', 'plugin.json');
if (!fs.existsSync(manifest)) blockers.push(`${path.relative(REPO_ROOT, manifest)} is missing: this checkout has no Codex plugin`);
const values: Record<string, string> = {};
if (chosenUrl !== null || !fs.existsSync(REPORTER_ENV)) values[KEYS.reporterUrl] = url;
if (secret) values[KEYS.reporterToken] = secret;
steps.push({
title: 'Codex',
blockers,
actions: [
// Codex reads this repository's .agents/plugins/marketplace.json and copies the plugin into its own cache.
{ kind: 'run', argv: ['codex', 'plugin', 'marketplace', 'add', REPO_ROOT] },
{ kind: 'run', argv: ['codex', 'plugin', 'add', market.plugin] },
{ kind: 'mkdir', path: DATA_HOME, mode: 0o700 },
envFile(REPORTER_ENV, 'codex-reporter.env.example', values, KEYS.reporterToken),
...enableService(CODEX_REPORTER),
...reporterNotes,
// Codex ties hook trust to the plugin's contents, so every `codex plugin add` above needs it again.
{ kind: 'trust-codex-hooks', plugin: market.plugin },
],
});
}
if (o.claude) {
const market = claudeMarket();
const blockers: string[] = [];
const manifest = path.join(REPO_ROOT, 'mod', 'claude-reporter', '.claude-plugin', 'plugin.json');
if (!fs.existsSync(manifest)) blockers.push(`${path.relative(REPO_ROOT, manifest)} is missing: this checkout has no Claude plugin`);
const actions: Action[] = [
// Claude Code reads this relative-path plugin from the checkout in place, but records its version with a copy in its cache
// (`claude plugin list --json`: readFromFolder, version, installPath), and `install` leaves an existing record as it is.
// `update` moves the record and the copy to this checkout's version (exit 0, "nothing to update", when they match), so the
// plugin is this version whichever one a Claude Code build loads. Open sessions take it once restarted (resumed), as
// `update` itself asks ("Restart to apply changes").
{ kind: 'run', argv: ['claude', 'plugin', 'marketplace', 'add', REPO_ROOT, '--scope', 'user'] },
{ kind: 'run', argv: ['claude', 'plugin', 'install', market.plugin, '--scope', 'user'] },
{ kind: 'run', argv: ['claude', 'plugin', 'update', market.plugin, '--scope', 'user'] },
];
// The URL is saved only when this run chose one (--url, or this machine's server); otherwise the one set before stays.
const values: Record<string, string> = {};
if (chosenUrl !== null) values[CLAUDE_OPTIONS.url] = chosenUrl;
if (secret) values[CLAUDE_OPTIONS.token] = secret;
if (Object.keys(values).length) {
// On stdin, so the secret never appears in a process list or shell history.
const shown = { ...values, ...(secret ? { [CLAUDE_OPTIONS.token]: '(hidden)' } : {}) };
actions.push({ kind: 'run', argv: ['claude', 'plugin', 'configure', market.plugin, '--values-stdin'], input: JSON.stringify(values), shownInput: JSON.stringify(shown) });
}
// Telemetry goes where the plugin reports: this run's URL, else the one the plugin has, its default only when Claude Code
// says it is not installed yet. A plugin whose options cannot be read, installed or not known to be absent, may send
// anywhere, so that is a blocker, not a guess.
let telemetryUrl = chosenUrl;
if (telemetryUrl === null) {
const options = claudePluginOptions(market.plugin);
if (options) telemetryUrl = claudePluginUrl(options);
else if (claudeHasPlugin(market.plugin) === false) telemetryUrl = CLAUDE_DEFAULT_URL;
else blockers.push(`the plugin's server URL cannot be read (\`claude plugin configure ${market.plugin} --json\` failed), so Claude Code's telemetry has no known destination: pass --url`);
}
if (telemetryUrl !== null) {
const telemetry = telemetryPlan(telemetryUrl, secret);
blockers.push(...telemetry.blockers);
actions.push(...telemetry.actions);
}
actions.push(...reporterNotes);
actions.push({ kind: 'note', text: 'Claude Code sessions started from now on report and send their usage. A running session does both once restarted (resumed): Claude Code reads its telemetry settings at start, and `claude plugin update` asks for a restart.' });
steps.push({ title: 'Claude Code', blockers, actions });
}
return steps;
}
/** A step that could not be done, with a message that says why; runPlan prints it and stops. */
class Failed extends Error {}
// ---- Codex hook trust ----------------------------------------------------------------------------
/**
* A JSON-RPC connection to a Codex app-server, reached the way Codex's own clients reach one: the managed daemon's socket
* when it runs (its path from `codex app-server daemon version`, then a WebSocket over the socket, as
* codex-reporter/src/daemon.ts connects), else a private `codex app-server` over stdio, one JSON message per line (the TUI
* likewise runs its own server when no daemon runs: codex-rs/tui/src/app_server_connection.rs). It only sends requests: a
* request from the server is never answered.
*/
export interface CodexAppServer {
/** Where it was reached, for messages. */
via: string;
call(method: string, params: unknown): Promise<unknown>;
close(): void;
}
const RPC_TIMEOUT_MS = 30_000;
class Rpc implements CodexAppServer {
private seq = 0;
private readonly pending = new Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }>();
private gone: Error | null = null;
constructor(readonly via: string, private readonly send: (text: string) => void, readonly close: () => void) {}
call(method: string, params: unknown): Promise<unknown> {
if (this.gone) return Promise.reject(this.gone);
const id = ++this.seq;
return new Promise((resolve, reject) => {
const timer = setTimeout(() => this.settle(id, new Error(`${method} got no answer in ${String(RPC_TIMEOUT_MS / 1000)} s`)), RPC_TIMEOUT_MS);
this.pending.set(id, {
resolve: (v) => {
clearTimeout(timer);
resolve(v);
},
reject: (e) => {
clearTimeout(timer);
reject(e);
},
});
this.send(JSON.stringify({ id, method, params }));
});
}
notify(method: string): void {
this.send(JSON.stringify({ method }));
}
/** One message from the server. Only answers to our requests count; notifications and server requests are dropped. */
receive(text: string): void {
let m: { id?: unknown; method?: unknown; result?: unknown; error?: { message?: unknown } | null } | null;
try {
m = JSON.parse(text) as typeof m;
} catch {
return;
}
if (!m || typeof m !== 'object' || typeof m.id !== 'number' || m.method !== undefined) return;
this.settle(m.id, m.error ? new Error(String(m.error.message ?? 'error')) : undefined, m.result);
}
/** The connection ended: every open request fails, and so does every later one. */
fail(err: Error): void {
this.gone ??= err;
for (const id of [...this.pending.keys()]) this.settle(id, err);
}
private settle(id: number, err: Error | undefined, result?: unknown): void {
const p = this.pending.get(id);
if (!p) return;
this.pending.delete(id);
if (err) p.reject(err);
else p.resolve(result);
}
}
/** The managed daemon's socket, from Codex's own passive probe; null when no daemon runs. */
function daemonSocket(): string | null {
const r = spawnSync('codex', ['app-server', 'daemon', 'version'], { encoding: 'utf8', timeout: 10_000 });
try {
const v = JSON.parse(r.stdout) as { status?: unknown; socketPath?: unknown };
return v.status === 'running' && typeof v.socketPath === 'string' && v.socketPath ? v.socketPath : null;
} catch {
return null;
}
}
async function overSocket(socketPath: string): Promise<Rpc> {
// Loaded here, not at the top, so a checkout without `npm ci` can still run doctor.ts and be told so.
const { default: WebSocket } = await import('ws');
const ws = new WebSocket(`ws+unix://${socketPath}:/`, { perMessageDeflate: false });
const rpc = new Rpc(`the Codex daemon at ${tilde(socketPath)}`, (text) => ws.send(text), () => ws.close());
ws.on('message', (data) => rpc.receive(String(data)));
ws.on('close', () => rpc.fail(new Error('the Codex daemon closed the connection')));
ws.on('error', (err) => rpc.fail(err));
// Rejects with the socket's error if it fails before it opens.
await once(ws, 'open');
return rpc;
}
function overStdio(): Rpc {
const child = spawn('codex', ['app-server'], { stdio: ['pipe', 'pipe', 'ignore'] });
const rpc = new Rpc('`codex app-server` over stdio', (text) => child.stdin.write(`${text}\n`), () => child.kill());
createInterface({ input: child.stdout }).on('line', (line) => rpc.receive(line));
child.stdin.on('error', (err) => rpc.fail(err));
child.on('error', (err) => rpc.fail(err));
child.on('exit', () => rpc.fail(new Error('codex app-server exited')));
return rpc;
}
/** An initialized connection, named as Codex's own passive daemon probe is, which leaves the daemon's identity alone. */
export async function openCodexAppServer(): Promise<CodexAppServer> {
const socket = daemonSocket();
const rpc = socket ? await overSocket(socket) : overStdio();
try {
await rpc.call('initialize', { clientInfo: { name: 'codex_app_server_daemon', title: 'SITREP install', version: release.version }, capabilities: null });
rpc.notify('initialized');
return rpc;
} catch (err) {
rpc.close();
throw err;
}
}
/** A hook as `hooks/list` lists it (codex-rs/app-server-protocol/src/protocol/v2/plugin.rs HookMetadata), the fields used here. */
export interface CodexHook {
key: string;
currentHash: string;
trustStatus: string;
}
/** `plugin`'s hooks as Codex lists them: the keys that start with `<plugin>:`. */
export async function codexHooksOf(server: CodexAppServer, plugin: string): Promise<CodexHook[]> {
const res = (await server.call('hooks/list', {})) as { data?: { hooks?: CodexHook[] }[] } | null;
const ours = new Map<string, CodexHook>();
for (const entry of res?.data ?? []) for (const h of entry.hooks ?? []) if (typeof h.key === 'string' && h.key.startsWith(`${plugin}:`)) ours.set(h.key, h);
return [...ours.values()];
}
/** The hooks Codex's /hooks screen asks to review (codex-rs/tui/src/hooks_rpc.rs `hook_needs_review`). */
export const needsTrust = (h: CodexHook): boolean => h.trustStatus === 'untrusted' || h.trustStatus === 'modified';
/** What the /hooks screen sends to trust hooks, each at its current hash (codex-rs/tui/src/hooks_rpc.rs `write_hook_trusts`). */
const trustWrite = (hashes: Record<string, string>) => ({
edits: [{ keyPath: 'hooks.state', value: Object.fromEntries(Object.entries(hashes).map(([key, hash]) => [key, { trusted_hash: hash }])), mergeStrategy: 'upsert' }],
reloadUserConfig: true,
});
async function trustCodexHooks(plugin: string): Promise<void> {
let server: CodexAppServer | null = null;
try {
server = await openCodexAppServer();
const hooks = await codexHooksOf(server, plugin);
if (!hooks.length) throw new Failed(`Codex lists no ${plugin} hooks (through ${server.via}); look for them in Codex's /hooks`);
const review = hooks.filter(needsTrust);
if (!review.length) {
console.log(` all ${String(hooks.length)} already trusted (${server.via})`);
return;
}
const res = (await server.call('config/batchWrite', trustWrite(Object.fromEntries(review.map((h) => [h.key, h.currentHash]))))) as { filePath?: unknown } | null;
const file = typeof res?.filePath === 'string' ? tilde(res.filePath) : "Codex's config.toml";
console.log(` trusted ${String(review.length)} of ${String(hooks.length)} in ${file} (${server.via})`);
} catch (err) {
if (err instanceof Failed) throw err;
throw new Failed(`could not trust the ${plugin} hooks${server ? ` through ${server.via}` : ''}: ${(err as Error).message}. Trust them in Codex's /hooks instead`);
} finally {
server?.close();
}
}
// ---- Running a plan -----------------------------------------------------------------------------
const shellQuote = (a: string): string => (/^[A-Za-z0-9_@%+=:,./-]+$/.test(a) ? a : `'${a.replace(/'/g, `'\\''`)}'`);
const indent = (text: string): string => text.replace(/\n$/, '').split('\n').map((l) => ` ${l}`).join('\n');
function describe(a: Action): string {
switch (a.kind) {
case 'mkdir': return `directory ${tilde(a.path)} (mode ${a.mode.toString(8)})`;
case 'write': return `write ${tilde(a.path)} (mode ${a.mode.toString(8)})${fs.existsSync(a.path) ? ', replacing the file there' : ''}:\n${indent(a.shown)}`;
case 'keep': return `keep ${tilde(a.path)} (${a.why})${a.mode === undefined ? '' : `, mode ${a.mode.toString(8)}`}`;
case 'remove': return `remove ${tilde(a.path)}`;
case 'rmdir-if-empty': return `remove ${tilde(a.path)} if it is empty`;
case 'run': return `run: ${a.argv.map(shellQuote).join(' ')}${a.shownInput ? ` (stdin: ${a.shownInput})` : ''}`;
case 'await-unload': return `wait until launchd has unloaded ${a.target} (launchctl print, once a second, up to ${String(UNLOAD_WAIT_S)} s)`;
case 'trust-codex-hooks': return `trust the ${a.plugin} hooks Codex lists as untrusted or modified, as its /hooks screen does, through the Codex daemon when one runs, else \`codex app-server\` over stdio:\n${indent(`hooks/list {}\nconfig/batchWrite ${JSON.stringify(trustWrite({ [`${a.plugin}:<hook>`]: '<current hash>' }))}`)}`;
case 'claude-telemetry': return `${a.set ? 'set' : 'remove'} Claude Code's telemetry settings in ${tilde(CLAUDE_SETTINGS)}, every other setting and hook entry kept:\n${indent(a.shown)}`;
case 'note': return `note: ${a.text}`;
}
}
async function perform(a: Action): Promise<void> {
switch (a.kind) {
case 'mkdir':
fs.mkdirSync(a.path, { recursive: true, mode: a.mode });
fs.chmodSync(a.path, a.mode);
return;
case 'write':
fs.mkdirSync(path.dirname(a.path), { recursive: true });
fs.writeFileSync(a.path, a.content, { mode: a.mode });
fs.chmodSync(a.path, a.mode);
return;
case 'remove':
fs.rmSync(a.path, { recursive: true, force: true });
return;
case 'rmdir-if-empty':
try {
fs.rmdirSync(a.path);
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
if (code === 'ENOTEMPTY' || code === 'EEXIST') console.log(` kept ${tilde(a.path)}: other files are still in it`);
else if (code !== 'ENOENT') throw err;
}
return;
case 'run': {
const r = spawnSync(a.argv[0], a.argv.slice(1), {
input: a.input,
stdio: [a.input === undefined ? 'inherit' : 'pipe', a.quiet ? 'ignore' : 'inherit', a.quiet ? 'ignore' : 'inherit'],
});
if (r.error) {
if (a.mayFail) return;
throw new Failed(`could not run ${a.argv[0]}: ${r.error.message}`);
}
if (r.status !== 0 && !a.mayFail) throw new Failed(`\`${a.argv.map(shellQuote).join(' ')}\` exited with ${String(r.status ?? r.signal)}`);
return;
}
case 'await-unload':
for (let waited = 0; ; waited++) {
const r = spawnSync('launchctl', ['print', a.target], { stdio: 'ignore' });
if (r.error) throw new Failed(`could not run launchctl: ${r.error.message}`);
if (r.status !== 0) return;
if (waited >= UNLOAD_WAIT_S) throw new Failed(`launchd still has ${a.target} loaded after ${String(UNLOAD_WAIT_S)} s; run \`launchctl bootout ${a.target}\`, wait until \`launchctl print ${a.target}\` finds nothing, then run this again`);
Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 1000);
}
case 'trust-codex-hooks':
return trustCodexHooks(a.plugin);
case 'claude-telemetry': {
let s: Json;
try {
s = readClaudeSettings();
} catch (err) {
throw new Failed(`${tilde(CLAUDE_SETTINGS)} cannot be read as Claude Code settings (${(err as Error).message})`);
}
const before = JSON.stringify(s);
const env = { ...(s.env as Json | undefined) };
if (a.set) {
s.env = Object.assign(env, a.set.env);
s.otelHeadersHelper = a.set.otelHeadersHelper;
} else {
if (!ownsTelemetry(s)) return;
for (const key of Object.keys(telemetrySettings('').env)) delete env[key];
delete s.otelHeadersHelper;
if (Object.keys(env).length) s.env = env;
else delete s.env;
}
// Settings already as wanted: the file is left as it is.
if (JSON.stringify(s) === before) return;
// A file this run emptied held only what install added.
if (!a.set && Object.keys(s).length === 0) fs.rmSync(CLAUDE_SETTINGS, { force: true });
else {
fs.mkdirSync(CLAUDE_DIR, { recursive: true });
// As Claude Code writes it: two-space JSON and a final newline. Written to a temporary file renamed over the old one, so
// Claude Code never reads half a file, as an atomic write is usually done: a symlink's target is written, and the
// temporary file is created with an existing file's mode (never wider, since the umask only narrows it), then given
// that mode exactly.
const old = fs.statSync(CLAUDE_SETTINGS, { throwIfNoEntry: false });
const file = old ? fs.realpathSync(CLAUDE_SETTINGS) : CLAUDE_SETTINGS;
const tmp = `${file}.${String(process.pid)}.tmp`;
const mode = old ? old.mode & 0o7777 : undefined;
try {
fs.writeFileSync(tmp, `${JSON.stringify(s, null, 2)}\n`, mode === undefined ? undefined : { mode });
if (mode !== undefined) fs.chmodSync(tmp, mode);
fs.renameSync(tmp, file);
} catch (err) {
fs.rmSync(tmp, { force: true });
throw err;
}
}
return;
}
case 'keep':
if (a.mode !== undefined) fs.chmodSync(a.path, a.mode);
return;
case 'note':
return;
}
}
/**
* Prints the plan; with `apply`, carries out each step by itself, in order: a step with a blocker is left out, and one whose
* action fails stops there, while the steps after it still run, unless it is their `prerequisite`. Returns the exit code, 1
* when any step was left out or failed.
*/
export async function runPlan(steps: Step[], apply: boolean, name: string): Promise<number> {
console.log(apply ? `${name}: applying.` : `${name}: dry run, nothing is changed. Re-run with --apply to make these changes.`);
const undone: string[] = [];
let needed: string | null = null;
for (const step of steps) {
console.log(`\n== ${step.title}`);
const blockers = needed === null ? step.blockers : [...step.blockers, `needs ${needed} first`];
for (const b of blockers) console.log(` blocked: ${b}`);
undone.push(...blockers.map((b) => `${step.title}: ${b}`));
let done = blockers.length === 0;
// Applying, a step left out lists no actions, as none is taken; the dry run lists them.
for (const a of apply && !done ? [] : step.actions) {
console.log(` ${describe(a)}`);
if (!apply) continue;
try {
await perform(a);
} catch (err) {
const why = err instanceof Failed ? err.message : String(err);
console.error(` failed: ${why}`);
undone.push(`${step.title}: failed, after the actions above it were done: ${why}`);
done = false;
break;
}
}
if (!done && step.prerequisite) needed = step.title;
}
if (undone.length) {
console.error(`\n${name}: ${apply ? 'not done; fix these, then run it again' : 'blocked, so --apply leaves these out'}:\n${undone.map((u) => ` - ${u}`).join('\n')}`);
return 1;
}
console.log(apply ? `\n${name}: done.` : `\n${name}: dry run only; add --apply to make these changes.`);
return 0;
}
// ---- CLI ------------------------------------------------------------------------------------------
/** The command line, read by Node's own parser, which refuses an unknown option, a missing value and a stray argument. */
function readArgs(argv: string[]): (InstallOptions & { apply: boolean; tokenStdin: boolean }) | 'help' {
const { values: v } = parseArgs({
args: argv,
options: {
help: { type: 'boolean', short: 'h' },
server: { type: 'boolean' },
claude: { type: 'boolean' },
codex: { type: 'boolean' },
url: { type: 'string' },
bind: { type: 'string' },
port: { type: 'string' },
'token-stdin': { type: 'boolean' },
apply: { type: 'boolean' },
},
});
if (v.help) return 'help';
const url = v.url === undefined ? null : v.url.replace(/\/+$/, '');
if (url !== null && !/^https?:\/\/[^\s/]+$/.test(url)) throw new Error(`--url must be http:// or https:// and a host, such as http://192.0.2.10:7487, not "${url}"`);
const port = v.port === undefined ? null : Number(v.port);
if (port !== null && (!Number.isInteger(port) || port < 1 || port > 65535)) throw new Error('--port must be a whole number from 1 to 65535');
const [server, claude, codex] = [v.server, v.claude, v.codex].map(Boolean);
if (!server && !claude && !codex) throw new Error('name what to install: --server, --claude and/or --codex');
if (!server && (v.bind !== undefined || port !== null)) throw new Error('--bind and --port set where the server listens and need --server; to point the reporters at a server, use --url');
return { server, claude, codex, url, bind: v.bind ?? null, port, secret: null, apply: Boolean(v.apply), tokenStdin: Boolean(v['token-stdin']) };
}
async function main(): Promise<number> {
let o: ReturnType<typeof readArgs>;
try {
o = readArgs(process.argv.slice(2));
} catch (err) {
console.error(`install: ${(err as Error).message} (see --help)`);
return 2;
}
if (o === 'help') {
console.log(HELP.replace('<repo>', REPO_ROOT));
return 0;
}
if (o.tokenStdin) {
const secret = fs.readFileSync(0, 'utf8').trim();
if (!secret || /\s/.test(secret)) {
console.error('install: --token-stdin read no secret (or one with spaces in it) from stdin');
return 2;
}
o.secret = secret;
}
return runPlan(installPlan(o), o.apply, 'install');
}
const invokedDirectly = (() => {
try {
return fs.realpathSync(process.argv[1] ?? '') === fs.realpathSync(fileURLToPath(import.meta.url));
} catch {
return false;
}
})();
if (invokedDirectly) process.exitCode = await main();