runcloud 0.1.2

package/dist/commands/services.js

@@ -0,0 +1,39 @@
+import { friendlyApiError } from '../api.js';
+import { readProjectLink, resolveProject } from '../config.js';
+import { readBackendServices, serviceUrl } from '../services-manifest.js';
+export function renderServices(services = readBackendServices(process.cwd()), opts = {}) {
+    const lines = ['name  type    path          public  url'];
+    for (const service of services) {
+        const isPublic = service.public !== false;
+        const url = opts.projectId && isPublic ? serviceUrl(opts.projectId, opts.env ?? 'dev', service.name) : '-';
+        lines.push([
+            service.name.padEnd(5),
+            service.type.padEnd(7),
+            service.path.padEnd(13),
+            String(isPublic).padEnd(7),
+            url,
+        ].join(' '));
+    }
+    return lines.join('\n');
+}
+export function registerServices(program) {
+    const services = program.command('services').description('Inspect backend services');
+    services
+        .command('list')
+        .description('List backend services from backend/newly.services.json')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--project <id>', 'project id (defaults to the linked directory when present)')
+        .action(async (opts) => {
+        try {
+            if (opts.env !== 'dev' && opts.env !== 'prod')
+                throw new Error('--env must be dev or prod');
+            const projectId = opts.project ?? readProjectLink(process.cwd())?.projectId;
+            const resolved = projectId ? resolveProject(process.cwd(), projectId) : undefined;
+            console.log(renderServices(readBackendServices(process.cwd()), { projectId: resolved, env: opts.env }));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/stack.js

@@ -0,0 +1,31 @@
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+export async function getStack(client, projectId) {
+    return (await client.get(`/newly_backend/stack/${projectId}`));
+}
+export function formatStack(out) {
+    const stack = out.stack ?? 'unknown';
+    const cli = out.cli_deployable
+        ? '✓ CLI-deployable — Newly backend'
+        : '✗ not CLI-deployable — use the Newly web app to deploy this project.';
+    return `stack: ${stack}\n${cli}`;
+}
+export function registerStack(program) {
+    program
+        .command('stack')
+        .description('Show which backend type a project uses and whether it supports CLI deploys')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .action(async (opts) => {
+        try {
+            const creds = requireCredentials();
+            const projectId = resolveProject(process.cwd(), opts.project);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            const out = await getStack(client, projectId);
+            console.log(formatStack(out));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/status.js

@@ -0,0 +1,110 @@
+import { ApiClient, friendlyApiError } from '../api.js';
+import { requireCredentials, resolveProject } from '../config.js';
+function elapsed(since) {
+    if (!since)
+        return '';
+    const ms = Date.now() - new Date(since).getTime();
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m ${s % 60}s`;
+    return `${Math.floor(s / 3600)}h ${Math.floor((s % 3600) / 60)}m`;
+}
+function renderProvisioningStages(s) {
+    const done = '  [✓]';
+    const current = '  [→]';
+    const todo = '  [ ]';
+    const stages = [
+        {
+            label: 'Project created',
+            note: 'backend entry registered in Newly',
+            complete: true,
+        },
+        {
+            label: 'Newly server assigned',
+            note: 'Newly server workspace allocated for your backend',
+            complete: s.cloud_env_assigned,
+        },
+        {
+            label: 'Newly resources provisioned',
+            note: 'Newly storage and backend services provisioned',
+            complete: s.database_ready,
+        },
+        {
+            label: 'Newly DB created',
+            note: 'Newly DB ready for your backend',
+            complete: s.database_ready,
+        },
+        {
+            label: 'Backend configuration stored',
+            note: 'Newly DB credentials, API keys, and auth settings encrypted and stored',
+            complete: s.secrets_wired,
+        },
+        {
+            label: "Run 'newly deploy'",
+            note: 'builds and deploys your backend code for the first time',
+            complete: false,
+        },
+    ];
+    let foundCurrent = false;
+    const lines = [];
+    for (const stage of stages) {
+        const note = `  — ${stage.note}`;
+        if (stage.complete) {
+            lines.push(`${done} ${stage.label}${note}`);
+        }
+        else if (!foundCurrent) {
+            foundCurrent = true;
+            lines.push(`${current} ${stage.label}${note}`);
+        }
+        else {
+            lines.push(`${todo} ${stage.label}${note}`);
+        }
+    }
+    return lines;
+}
+export function renderStatus(body) {
+    const lines = [];
+    for (const env of ['dev', 'prod']) {
+        const s = body[env];
+        if (!s) {
+            lines.push(`${env}: not provisioned`);
+            continue;
+        }
+        if (s.status === 'provisioning') {
+            const age = elapsed(s.created_at);
+            lines.push(`${env}: provisioning${age ? ` (${age})` : ''}`);
+            lines.push(...renderProvisioningStages(s));
+        }
+        else {
+            lines.push(`${env}: ${s.status}`);
+            lines.push(`  auth: ${s.auth_hostname}`);
+            lines.push(`  api:  ${s.api_hostname}`);
+            if (s.current_git_sha)
+                lines.push(`  deployed sha: ${s.current_git_sha}`);
+        }
+        if (s.last_error)
+            lines.push(`  last error: ${s.last_error}`);
+    }
+    return lines.join('\n');
+}
+export function registerStatus(program) {
+    program
+        .command('status')
+        .description('Show backend status and service URLs')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .action(async (opts) => {
+        try {
+            const creds = requireCredentials();
+            const projectId = resolveProject(process.cwd(), opts.project);
+            const client = new ApiClient(creds.apiUrl, creds.token);
+            const body = await client.get(`/newly_backend/status/${projectId}`);
+            console.log(renderStatus(body));
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/commands/website.js

@@ -0,0 +1,218 @@
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, resolve } from 'node:path';
+import { create as tarCreate } from 'tar';
+import { ApiClient, friendlyApiError } from '../api.js';
+import { createSnapshot } from '../archive.js';
+import { requireCredentials, resolveProject } from '../config.js';
+function makeClient(project) {
+    const creds = requireCredentials();
+    return {
+        client: new ApiClient(creds.apiUrl, creds.token),
+        projectId: resolveProject(process.cwd(), project),
+    };
+}
+const BUILD_ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export function renderDeployment(d) {
+    const at = d.published_at ?? d.created_at ?? '';
+    const suffix = d.error_message ? ` (${d.error_message})` : '';
+    return `${d.id}  ${d.status}${at ? `  ${at}` : ''}${suffix}`;
+}
+function archiveKib(size) {
+    return size < 1024 ? '<1' : Math.round(size / 1024).toString();
+}
+function assertDirectory(path, label) {
+    if (!existsSync(path))
+        throw new Error(`${label} does not exist: ${path}`);
+    if (!statSync(path).isDirectory())
+        throw new Error(`${label} is not a directory: ${path}`);
+}
+function collect(value, previous) {
+    return [...previous, value];
+}
+function parseBuildEnvPair(pair) {
+    const index = pair.indexOf('=');
+    if (index <= 0)
+        throw new Error(`Invalid --build-env "${pair}" (expected KEY=value).`);
+    const key = pair.slice(0, index).trim();
+    const value = pair.slice(index + 1);
+    if (!BUILD_ENV_KEY.test(key)) {
+        throw new Error(`Invalid build env var name "${key}".`);
+    }
+    return [key, value];
+}
+function unquoteEnvValue(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed
+            .slice(1, -1)
+            .replace(/\\n/g, '\n')
+            .replace(/\\"/g, '"')
+            .replace(/\\\\/g, '\\');
+    }
+    if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+export function parseBuildEnvFile(path) {
+    const env = {};
+    const body = readFileSync(path, 'utf8');
+    for (const [index, rawLine] of body.split(/\r?\n/).entries()) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const equals = line.indexOf('=');
+        if (equals <= 0)
+            throw new Error(`Invalid env file line ${index + 1}: expected KEY=value.`);
+        const key = line.slice(0, equals).trim();
+        if (!BUILD_ENV_KEY.test(key))
+            throw new Error(`Invalid env file key "${key}".`);
+        env[key] = unquoteEnvValue(line.slice(equals + 1));
+    }
+    return env;
+}
+export function parseBuildEnv(pairs = [], envFile) {
+    const env = envFile ? parseBuildEnvFile(envFile) : {};
+    for (const pair of pairs) {
+        const [key, value] = parseBuildEnvPair(pair);
+        env[key] = value;
+    }
+    return env;
+}
+export async function createStaticSiteArchive(dir) {
+    const root = resolve(dir);
+    assertDirectory(root, 'Static site directory');
+    if (!existsSync(`${root}/index.html`)) {
+        throw new Error(`Static site directory must contain index.html at its root: ${root}`);
+    }
+    const chunks = [];
+    const stream = tarCreate({
+        gzip: true,
+        cwd: root,
+        portable: true,
+        filter: (path) => {
+            const name = basename(path);
+            return name !== '.DS_Store' && name !== '.env' && !name.startsWith('.env.');
+        },
+    }, ['.']);
+    for await (const chunk of stream) {
+        chunks.push(Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+export async function runWebsitePublish(client, projectId, opts = {}, log = console.log) {
+    let result;
+    if (opts.remoteBuild) {
+        const sourceDir = opts.localPath ?? '.';
+        assertDirectory(sourceDir, 'Website source directory');
+        log('Packaging website source...');
+        const archive = await createSnapshot(sourceDir);
+        log(`Uploading source snapshot (${archiveKib(archive.length)} KiB) for remote build...`);
+        const form = new FormData();
+        form.set('request', JSON.stringify({
+            build_env: opts.buildEnv ?? {},
+            build_command: opts.buildCommand,
+            output_dir: opts.outputDir,
+        }));
+        form.set('source', new Blob([new Uint8Array(archive)], { type: 'application/gzip' }), 'source.tar.gz');
+        result = (await client.uploadForm(`/projects/${projectId}/website/build-upload`, form));
+    }
+    else if (opts.localPath) {
+        log('Packaging static site...');
+        const archive = await createStaticSiteArchive(opts.localPath);
+        log(`Uploading static site (${archiveKib(archive.length)} KiB)...`);
+        result = (await client.upload(`/projects/${projectId}/website/publish-upload`, archive, 'application/gzip'));
+    }
+    else {
+        result = (await client.post(`/projects/${projectId}/website/publish`, {
+            source_path: opts.sourcePath ?? 'website/out',
+        }));
+    }
+    log(`Published ${result.deployment.id}`);
+    log(`URL: ${result.default_url}`);
+}
+export async function runWebsiteDeployments(client, projectId, log = console.log) {
+    const result = (await client.get(`/projects/${projectId}/website/deployments`));
+    const deployments = result.deployments ?? [];
+    if (deployments.length === 0) {
+        log('No website deployments yet.');
+        return;
+    }
+    log(deployments.map(renderDeployment).join('\n'));
+}
+export async function runWebsiteRollback(client, projectId, deploymentId, log = console.log) {
+    const result = (await client.post(`/projects/${projectId}/website/rollback`, {
+        deployment_id: deploymentId,
+    }));
+    log(`Rolled back to ${result.deployment.id}`);
+}
+export function registerWebsite(program) {
+    const website = program.command('website').description('Publish and manage static website deployments');
+    website
+        .command('publish')
+        .description('Publish a static website directory to Cloudflare')
+        .argument('[path]', 'local static output directory to upload, for example ./dist')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .option('--source-path <path>', 'committed static export path in project storage')
+        .option('--remote-build', 'upload source files and ask the backend to build dist remotely', false)
+        .option('--build-env <KEY=value>', 'build-time env var for --remote-build (repeatable)', collect, [])
+        .option('--build-env-file <path>', 'dotenv-style file of build-time env vars for --remote-build')
+        .option('--build-command <command>', 'build command for --remote-build')
+        .option('--output-dir <path>', 'static output directory produced by --remote-build')
+        .action(async (localPath, opts) => {
+        try {
+            if (localPath && opts.sourcePath) {
+                throw new Error('Pass either a local path or --source-path, not both.');
+            }
+            if (opts.remoteBuild && opts.sourcePath) {
+                throw new Error('--remote-build uploads local source and cannot be combined with --source-path.');
+            }
+            if (!opts.remoteBuild &&
+                (opts.buildEnv.length > 0 || opts.buildEnvFile || opts.buildCommand || opts.outputDir)) {
+                throw new Error('--build-env, --build-env-file, --build-command, and --output-dir require --remote-build.');
+            }
+            const { client, projectId } = makeClient(opts.project);
+            await runWebsitePublish(client, projectId, {
+                localPath,
+                sourcePath: opts.sourcePath,
+                remoteBuild: opts.remoteBuild,
+                buildEnv: parseBuildEnv(opts.buildEnv, opts.buildEnvFile),
+                buildCommand: opts.buildCommand,
+                outputDir: opts.outputDir,
+            });
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    website
+        .command('deployments')
+        .description('List website deployments')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .action(async (opts) => {
+        try {
+            const { client, projectId } = makeClient(opts.project);
+            await runWebsiteDeployments(client, projectId);
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+    website
+        .command('rollback')
+        .description('Rollback website domains to a previous deployment')
+        .argument('<deployment-id>')
+        .option('--project <id>', 'project id (defaults to the linked directory)')
+        .action(async (deploymentId, opts) => {
+        try {
+            const { client, projectId } = makeClient(opts.project);
+            await runWebsiteRollback(client, projectId, deploymentId);
+        }
+        catch (e) {
+            console.error(friendlyApiError(e));
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/config.js

@@ -0,0 +1,95 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+function credentialsHome() {
+    if (process.env.RUN_CLOUD_HOME)
+        return process.env.RUN_CLOUD_HOME;
+    if (process.env.NEWLY_HOME)
+        return process.env.NEWLY_HOME;
+    const invoked = basename(process.argv[1] ?? '');
+    if (invoked === 'runcloud' || invoked === 'run-cloud.js')
+        return join(homedir(), '.run-cloud');
+    return process.env.NEWLY_HOME ?? join(homedir(), '.newly');
+}
+function credentialsPath() {
+    return join(credentialsHome(), 'credentials');
+}
+export function credentialsDisplayPath() {
+    const path = credentialsPath();
+    const home = homedir();
+    return path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+function loginCommandName() {
+    const invoked = basename(process.argv[1] ?? '');
+    return invoked === 'runcloud' || invoked === 'run-cloud.js' ? 'runcloud login' : 'newly login';
+}
+export function normalizeApiUrl(url) {
+    const trimmed = url.replace(/\/+$/, '');
+    return trimmed.endsWith('/api') ? trimmed : `${trimmed}/api`;
+}
+export function saveCredentials(creds) {
+    mkdirSync(credentialsHome(), { recursive: true, mode: 0o700 });
+    const normalized = { ...creds, apiUrl: normalizeApiUrl(creds.apiUrl) };
+    writeFileSync(credentialsPath(), JSON.stringify(normalized, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(credentialsPath(), 0o600);
+}
+export function loadCredentials() {
+    const envToken = process.env.NEWLY_API_TOKEN ?? process.env.NEWLY_CLI_TOKEN;
+    const envApiUrl = process.env.NEWLY_API_URL ?? process.env.NEWLY_API_HOST ?? process.env.NEXT_PUBLIC_API_HOST;
+    if (envToken?.trim() && envApiUrl?.trim()) {
+        return {
+            token: envToken.trim(),
+            apiUrl: normalizeApiUrl(envApiUrl.trim()),
+            appUrl: process.env.NEWLY_APP_URL ?? 'https://newly.dev',
+            expiresAt: Number.MAX_SAFE_INTEGER,
+        };
+    }
+    if (!existsSync(credentialsPath()))
+        return null;
+    try {
+        const creds = JSON.parse(readFileSync(credentialsPath(), 'utf8'));
+        if (!creds.token || creds.expiresAt < Date.now() / 1000)
+            return null;
+        return { ...creds, apiUrl: normalizeApiUrl(creds.apiUrl) };
+    }
+    catch {
+        return null;
+    }
+}
+export function clearCredentials() {
+    rmSync(credentialsPath(), { force: true });
+}
+export function requireCredentials() {
+    const creds = loadCredentials();
+    if (!creds) {
+        throw new Error(`Not logged in (or session expired). Run: ${loginCommandName()}`);
+    }
+    return creds;
+}
+export function writeProjectLink(dir, link) {
+    const linkDir = join(dir, '.newly');
+    mkdirSync(linkDir, { recursive: true });
+    const gitignorePath = join(linkDir, '.gitignore');
+    if (!existsSync(gitignorePath))
+        writeFileSync(gitignorePath, '*\n');
+    writeFileSync(join(linkDir, 'project.json'), JSON.stringify(link, null, 2) + '\n');
+}
+export function readProjectLink(dir) {
+    const path = join(dir, '.newly', 'project.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function resolveProject(dir, explicit) {
+    if (explicit)
+        return explicit;
+    const link = readProjectLink(dir);
+    if (link?.projectId)
+        return link.projectId;
+    throw new Error('No project linked to this directory. Run `newly pull <project-id>` first, or pass --project <id>.');
+}

package/dist/diagnose.js

@@ -0,0 +1,159 @@
+const DEFAULT_URLS = {
+    dev: {
+        apiOps: 'https://cp-api-ops-dev.newly.app',
+        worker: 'https://cp-worker-dev.newly.app',
+    },
+    prod: {
+        apiOps: 'https://cp-api-ops-prod.newly.app',
+        worker: 'https://cp-worker-prod.newly.app',
+    },
+};
+function stripSlash(url) {
+    return url.replace(/\/+$/, '');
+}
+export function resolveTargets(env) {
+    if (env !== 'dev' && env !== 'prod') {
+        throw new Error(`--env must be dev or prod (got "${env}")`);
+    }
+    const upper = env.toUpperCase();
+    const apiOps = process.env[`DIAGNOSE_CP_API_OPS_URL_${upper}`] ??
+        process.env.DIAGNOSE_CP_API_OPS_URL ??
+        DEFAULT_URLS[env].apiOps;
+    const worker = process.env[`DIAGNOSE_CP_WORKER_URL_${upper}`] ??
+        process.env.DIAGNOSE_CP_WORKER_URL ??
+        DEFAULT_URLS[env].worker;
+    return [
+        { service: 'cp-api', url: stripSlash(apiOps) },
+        { service: 'cp-worker', url: stripSlash(worker) },
+    ];
+}
+function extractAuthorization(headers) {
+    if (headers instanceof Headers) {
+        return headers.get('authorization') ?? undefined;
+    }
+    const h = headers;
+    return h?.Authorization ?? h?.authorization;
+}
+export async function resolveOpsAuthHeader(env = process.env) {
+    const audience = env.DIAGNOSE_OIDC_AUDIENCE ?? 'newly-diagnose-ops';
+    try {
+        const { GoogleAuth } = await import('google-auth-library');
+        const auth = new GoogleAuth();
+        const client = await auth.getIdTokenClient(audience);
+        const authz = extractAuthorization(await client.getRequestHeaders());
+        if (authz) {
+            return authz;
+        }
+    }
+    catch {
+    }
+    const token = env.DIAGNOSE_OPS_TOKEN;
+    if (token) {
+        return `Bearer ${token}`;
+    }
+    throw new Error('No ops credential available. Run `gcloud auth application-default login` (ADC/OIDC), ' +
+        'or export DIAGNOSE_OPS_TOKEN with the break-glass ops token.');
+}
+function truncate(value, max = 200) {
+    const trimmed = value.trim();
+    return trimmed.length > max ? `${trimmed.slice(0, max)}...` : trimmed;
+}
+export async function fetchDiagnose(target, authHeader) {
+    try {
+        const res = await fetch(`${target.url}/diagnose`, { headers: { Authorization: authHeader } });
+        if (!res.ok) {
+            const body = await res.text().catch(() => '');
+            return {
+                service: target.service,
+                error: `HTTP ${res.status}${body ? `: ${truncate(body)}` : ''}`,
+            };
+        }
+        return (await res.json());
+    }
+    catch (e) {
+        return { service: target.service, error: e instanceof Error ? e.message : String(e) };
+    }
+}
+function isDoc(result) {
+    return !('error' in result);
+}
+export function rollupVerdict(services) {
+    const names = Object.keys(services);
+    const down = names.filter((name) => !isDoc(services[name]));
+    if (down.length) {
+        return `DOWN - unreachable: ${down.join(', ')}`;
+    }
+    const degraded = [];
+    for (const name of names) {
+        const doc = services[name];
+        const bad = Object.entries(doc.health)
+            .filter(([, probe]) => !probe.ok)
+            .map(([probeName]) => probeName);
+        if (bad.length) {
+            degraded.push(`${name} (${bad.join(', ')})`);
+        }
+    }
+    if (degraded.length) {
+        return `DEGRADED - ${degraded.join('; ')}`;
+    }
+    return `OK - ${names.length} service(s) healthy`;
+}
+export async function fanoutDiagnose(env) {
+    const targets = resolveTargets(env);
+    const authHeader = await resolveOpsAuthHeader();
+    const results = await Promise.all(targets.map((target) => fetchDiagnose(target, authHeader)));
+    const services = {};
+    results.forEach((result, index) => {
+        services[targets[index].service] = result;
+    });
+    return { rollup: rollupVerdict(services), services };
+}
+export function renderRollup(result, session) {
+    const lines = [result.rollup];
+    if (session) {
+        lines.push(`session: ${session}`);
+    }
+    lines.push('');
+    for (const [name, service] of Object.entries(result.services)) {
+        if (!isDoc(service)) {
+            lines.push(`${name}: UNREACHABLE - ${service.error}`);
+            continue;
+        }
+        const sha = service.deploy.git_sha ?? '(sha unknown)';
+        const revision = service.deploy.revision ?? '(revision unknown)';
+        lines.push(`${name}: ${sha} @ ${revision} [env=${service.env}]`);
+        const badProbes = Object.entries(service.health)
+            .filter(([, probe]) => !probe.ok)
+            .map(([probeName, probe]) => `${probeName}${probe.detail ? ` (${probe.detail})` : ''}`);
+        lines.push(`  health: ${badProbes.length ? `DEGRADED - ${badProbes.join(', ')}` : 'all ok'}`);
+        for (const verdict of service.diagnosis) {
+            lines.push(`  - ${verdict}`);
+        }
+    }
+    return lines.join('\n');
+}
+export function registerDiagnose(program) {
+    program
+        .command('diagnose')
+        .description('Fan out /diagnose across control-plane services and roll up a verdict (dev/ops only)')
+        .option('--env <env>', 'dev or prod', 'dev')
+        .option('--session <id>', 'annotate the rollup with a session id you are investigating')
+        .option('--json', 'emit the merged JSON document instead of the human rollup')
+        .action(async (opts) => {
+        try {
+            if (opts.env !== 'dev' && opts.env !== 'prod') {
+                throw new Error('--env must be dev or prod');
+            }
+            const result = await fanoutDiagnose(opts.env);
+            if (opts.json) {
+                console.log(JSON.stringify({ session: opts.session ?? null, ...result }, null, 2));
+                return;
+            }
+            console.log(renderRollup(result, opts.session));
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            process.exitCode = 1;
+        }
+    });
+}