@matthesketh/fleet 1.8.1 → 1.11.1

package/dist/commands/start.js

@@ -1,22 +1,19 @@
+import { z } from 'zod';
 import { load, findApp } from '../core/registry.js';
 import { startService } from '../core/systemd.js';
-import { AppNotFoundError } from '../core/errors.js';
-import { success, error } from '../ui/output.js';
-export function startCommand(args) {
-    const appName = args[0];
-    if (!appName) {
-        error('Usage: fleet start <app>');
-        process.exit(1);
-    }
-    const reg = load();
-    const app = findApp(reg, appName);
-    if (!app)
-        throw new AppNotFoundError(appName);
-    if (startService(app.serviceName)) {
-        success(`Started ${app.name}`);
-    }
-    else {
-        error(`Failed to start ${app.name}`);
-        process.exit(1);
-    }
-}
+import { defineCommand } from '../registry/registry.js';
+export const startCommand = defineCommand({
+    name: 'start',
+    summary: 'Start an app via systemctl',
+    args: z.object({ app: z.string() }),
+    async run(args) {
+        const app = findApp(load(), args.app);
+        if (!app) {
+            return { ok: false, summary: `app not found: ${args.app}`, data: { app: args.app, service: '' } };
+        }
+        if (!startService(app.serviceName)) {
+            return { ok: false, summary: `failed to start ${app.name}`, data: { app: app.name, service: app.serviceName } };
+        }
+        return { ok: true, summary: `started ${app.name}`, data: { app: app.name, service: app.serviceName } };
+    },
+});

package/dist/commands/status.d.ts

@@ -11,4 +11,4 @@ export interface StatusData {
     unhealthy: number;
 }
 export declare function getStatusData(): StatusData;
-export declare function statusCommand(args: string[]): void;
+export declare const statusCommand: import("../registry/types.js").CommandDef<StatusData>;

package/dist/commands/status.js

@@ -1,7 +1,8 @@
+import { z } from 'zod';
 import { load } from '../core/registry.js';
 import { getMultipleServiceStatuses, systemdAvailable } from '../core/systemd.js';
 import { listContainers } from '../core/docker.js';
-import { c, icon, heading, table, info } from '../ui/output.js';
+import { defineCommand } from '../registry/registry.js';
 export function getStatusData() {
     const reg = load();
     const containers = listContainers();
@@ -47,28 +48,22 @@ export function getStatusData() {
         unhealthy: apps.filter(a => a.health !== 'healthy').length,
     };
 }
-export function statusCommand(args) {
-    const json = args.includes('--json');
-    const data = getStatusData();
-    if (json) {
-        process.stdout.write(JSON.stringify(data, null, 2) + '\n');
-        return;
-    }
-    heading('Fleet Dashboard');
-    info(`${data.totalApps} apps | ${c.green}${data.healthy} healthy${c.reset} | ${data.unhealthy > 0 ? c.red : c.dim}${data.unhealthy} unhealthy${c.reset}`);
-    const rows = data.apps.map(app => {
-        const healthIcon = app.health === 'healthy' ? icon.ok
-            : app.health === 'frozen' ? icon.info
-                : app.health === 'degraded' ? icon.warn
-                    : icon.err;
-        const systemdColor = app.systemd === 'active' ? c.green : c.red;
-        return [
-            `${c.bold}${app.name}${c.reset}`,
-            `${systemdColor}${app.systemd}${c.reset}`,
-            app.containers,
-            `${healthIcon} ${app.health}`,
-        ];
-    });
-    table(['APP', 'SYSTEMD', 'CONTAINERS', 'HEALTH'], rows);
-    process.stdout.write('\n');
-}
+export const statusCommand = defineCommand({
+    name: 'status',
+    summary: 'Dashboard: all apps, systemd state, containers, health',
+    args: z.object({}),
+    tui: { view: 'dashboard' },
+    async run() {
+        const data = getStatusData();
+        return {
+            ok: true,
+            summary: `${data.totalApps} apps | ${data.healthy} healthy | ${data.unhealthy} unhealthy`,
+            data,
+            render: {
+                kind: 'table',
+                columns: ['APP', 'SYSTEMD', 'CONTAINERS', 'HEALTH'],
+                rows: data.apps.map(a => [a.name, a.systemd, a.containers, a.health]),
+            },
+        };
+    },
+});

package/dist/commands/stop.d.ts

@@ -1 +1,4 @@
-export declare function stopCommand(args: string[]): void;
+export declare const stopCommand: import("../registry/types.js").CommandDef<{
+    app: string;
+    service: string;
+}>;

package/dist/commands/stop.js

@@ -1,22 +1,19 @@
+import { z } from 'zod';
 import { load, findApp } from '../core/registry.js';
 import { stopService } from '../core/systemd.js';
-import { AppNotFoundError } from '../core/errors.js';
-import { success, error } from '../ui/output.js';
-export function stopCommand(args) {
-    const appName = args[0];
-    if (!appName) {
-        error('Usage: fleet stop <app>');
-        process.exit(1);
-    }
-    const reg = load();
-    const app = findApp(reg, appName);
-    if (!app)
-        throw new AppNotFoundError(appName);
-    if (stopService(app.serviceName)) {
-        success(`Stopped ${app.name}`);
-    }
-    else {
-        error(`Failed to stop ${app.name}`);
-        process.exit(1);
-    }
-}
+import { defineCommand } from '../registry/registry.js';
+export const stopCommand = defineCommand({
+    name: 'stop',
+    summary: 'Stop an app via systemctl',
+    args: z.object({ app: z.string() }),
+    async run(args) {
+        const app = findApp(load(), args.app);
+        if (!app) {
+            return { ok: false, summary: `app not found: ${args.app}`, data: { app: args.app, service: '' } };
+        }
+        if (!stopService(app.serviceName)) {
+            return { ok: false, summary: `failed to stop ${app.name}`, data: { app: app.name, service: app.serviceName } };
+        }
+        return { ok: true, summary: `stopped ${app.name}`, data: { app: app.name, service: app.serviceName } };
+    },
+});

package/dist/commands/testflight.d.ts

@@ -0,0 +1 @@
+export declare function testflightCommand(args: string[]): Promise<void>;

package/dist/commands/testflight.js

@@ -0,0 +1,193 @@
+import { resolveAscCredentials, hasAscCredentials } from '../core/testflight/credentials.js';
+import { ghVersion, resolveRepo, repoSecrets, dispatchWorkflow, latestRun, watchRun, } from '../core/testflight/workflow.js';
+import { listBuilds, expireBuild, setWhatsNew, verifyApp } from '../core/testflight/asc.js';
+import { resolveTestflightTarget, appSecretsEnv } from '../core/testflight/resolve.js';
+import { heading, success, error, info, warn, table } from '../ui/output.js';
+// the build workflow this command dispatches by default — a macos-runner
+// workflow committed to the app's repo at .github/workflows/.
+const DEFAULT_WORKFLOW = 'ios-testflight.yml';
+// the actions secrets the build workflow needs to sign and upload an .ipa.
+const REQUIRED_REPO_SECRETS = [
+    'ASC_API_KEY_ID', 'ASC_API_KEY_ISSUER_ID', 'ASC_API_KEY_B64', 'APPLE_TEAM_ID',
+];
+const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+// `fleet testflight` — publish a mobile app to TestFlight by dispatching its
+// repo's macOS build workflow, and manage its builds through the App Store
+// Connect API. an iOS .ipa can only be built on macOS, so publish runs the
+// build on a github-hosted runner rather than locally.
+export async function testflightCommand(args) {
+    switch (args[0]) {
+        case 'doctor': return tfDoctor(args.slice(1));
+        case 'publish': return tfPublish(args.slice(1));
+        case 'builds': return tfBuilds(args.slice(1));
+        case 'update': return tfUpdate(args.slice(1));
+        case 'delete': return tfDelete(args.slice(1));
+        default:
+            error('Usage: fleet testflight <doctor|publish|builds|update|delete>');
+            process.exit(1);
+    }
+}
+function extractFlag(args, flag) {
+    const idx = args.indexOf(flag);
+    if (idx === -1 || idx + 1 >= args.length)
+        return undefined;
+    return args[idx + 1];
+}
+async function tfDoctor(args) {
+    heading('TestFlight — readiness');
+    const gh = ghVersion();
+    if (gh)
+        success(`GitHub CLI available: ${gh}`);
+    else
+        error('GitHub CLI (gh) not found — required to dispatch the build workflow');
+    const appName = args.find(a => !a.startsWith('-'));
+    if (!appName) {
+        info('Pass an app name to check its repo + credentials: fleet testflight doctor <app>');
+        return;
+    }
+    const { app, projectPath } = resolveTestflightTarget(appName);
+    const repo = resolveRepo(projectPath);
+    if (repo) {
+        success(`GitHub repo: ${repo}`);
+        const secrets = repoSecrets(repo);
+        if (secrets) {
+            const missing = REQUIRED_REPO_SECRETS.filter(s => !secrets.includes(s));
+            if (missing.length === 0)
+                success('Repo Actions secrets present — the build workflow can sign and upload');
+            else
+                warn(`Repo Actions secrets missing: ${missing.join(', ')} — set them with "gh secret set"`);
+        }
+        else {
+            warn('Could not list repo Actions secrets — check "gh auth status"');
+        }
+    }
+    else {
+        warn(`No GitHub repo resolved for ${app} — publish needs a gh checkout at ${projectPath}`);
+    }
+    const env = appSecretsEnv(app);
+    if (!hasAscCredentials(env)) {
+        error(`App Store Connect credentials missing for ${app}`);
+        info('Required vault secrets: ASC_API_KEY_ID, ASC_API_KEY_ISSUER_ID, ASC_API_KEY_B64');
+        process.exit(1);
+    }
+    success('App Store Connect credentials present (builds/update/delete)');
+    const ascAppId = env.ASC_APP_ID;
+    if (!ascAppId) {
+        warn('ASC_APP_ID not set — builds/update/delete need it');
+        return;
+    }
+    try {
+        const name = await verifyApp(resolveAscCredentials(env), ascAppId);
+        success(`App Store Connect reachable — app: ${name}`);
+    }
+    catch (err) {
+        error(`App Store Connect check failed: ${err.message}`);
+        process.exit(1);
+    }
+}
+async function tfPublish(args) {
+    const appName = args.find(a => !a.startsWith('-'));
+    if (!appName) {
+        error('Usage: fleet testflight publish <app> [--workflow <file>] [--ref <branch>] [--watch]');
+        process.exit(1);
+    }
+    const workflow = extractFlag(args, '--workflow') ?? DEFAULT_WORKFLOW;
+    const ref = extractFlag(args, '--ref');
+    const watch = args.includes('--watch');
+    const { app, projectPath } = resolveTestflightTarget(appName);
+    heading(`TestFlight publish: ${app}`);
+    if (!ghVersion()) {
+        error('GitHub CLI (gh) not found — required to dispatch the build workflow');
+        process.exit(1);
+    }
+    const repo = resolveRepo(projectPath);
+    if (!repo) {
+        error(`Could not resolve a GitHub repo for ${app} — is ${projectPath} a gh checkout?`);
+        process.exit(1);
+    }
+    // remember the newest run so the one this dispatch queues can be told
+    // apart from it — `gh workflow run` returns no run id of its own.
+    const before = latestRun(repo, workflow)?.databaseId ?? 0;
+    info(`Dispatching ${workflow} on ${repo}${ref ? ` (${ref})` : ''}...`);
+    const dispatch = dispatchWorkflow(repo, workflow, ref);
+    if (!dispatch.ok) {
+        error(`Workflow dispatch failed: ${dispatch.message}`);
+        process.exit(1);
+    }
+    success('Workflow dispatched — the iOS build runs on a macOS runner (~15-30 min)');
+    // the queued run is not addressable straight away; poll briefly for it.
+    let run = latestRun(repo, workflow);
+    for (let i = 0; i < 10 && (!run || run.databaseId === before); i++) {
+        await sleep(3000);
+        run = latestRun(repo, workflow);
+    }
+    if (!run || run.databaseId === before) {
+        info(`Track it at https://github.com/${repo}/actions/workflows/${workflow}`);
+        return;
+    }
+    info(`Run: ${run.url}`);
+    if (watch) {
+        const code = watchRun(repo, run.databaseId);
+        if (code !== 0) {
+            error('The build workflow failed — see the run log above');
+            process.exit(1);
+        }
+        success(`${app} built and uploaded to TestFlight`);
+    }
+}
+async function tfBuilds(args) {
+    const appName = args.find(a => !a.startsWith('-'));
+    const json = args.includes('--json');
+    if (!appName) {
+        error('Usage: fleet testflight builds <app> [--app-id <id>] [--json]');
+        process.exit(1);
+    }
+    const { app } = resolveTestflightTarget(appName);
+    const env = appSecretsEnv(app);
+    const ascAppId = extractFlag(args, '--app-id') ?? env.ASC_APP_ID;
+    if (!ascAppId) {
+        error('App Store Connect app id required — set ASC_APP_ID or pass --app-id');
+        process.exit(1);
+    }
+    const builds = await listBuilds(resolveAscCredentials(env), ascAppId);
+    if (json) {
+        process.stdout.write(JSON.stringify(builds, null, 2) + '\n');
+        return;
+    }
+    heading(`TestFlight builds: ${app}`);
+    if (builds.length === 0) {
+        info('No builds found.');
+        return;
+    }
+    table(['BUILD', 'VERSION', 'STATE', 'EXPIRED', 'UPLOADED'], builds.map(b => [
+        b.version,
+        b.shortVersion,
+        b.processingState,
+        b.expired ? 'yes' : 'no',
+        b.uploadedDate.slice(0, 10),
+    ]));
+    process.stdout.write('\n');
+}
+async function tfUpdate(args) {
+    const appName = args.find(a => !a.startsWith('-'));
+    const buildId = extractFlag(args, '--build');
+    const whatsNew = extractFlag(args, '--whats-new');
+    if (!appName || !buildId || !whatsNew) {
+        error('Usage: fleet testflight update <app> --build <build-id> --whats-new "..."');
+        process.exit(1);
+    }
+    const { app } = resolveTestflightTarget(appName);
+    await setWhatsNew(resolveAscCredentials(appSecretsEnv(app)), buildId, whatsNew);
+    success(`Updated the "What to Test" notes for build ${buildId}`);
+}
+async function tfDelete(args) {
+    const appName = args.find(a => !a.startsWith('-'));
+    const buildId = extractFlag(args, '--build');
+    if (!appName || !buildId) {
+        error('Usage: fleet testflight delete <app> --build <build-id>');
+        process.exit(1);
+    }
+    const { app } = resolveTestflightTarget(appName);
+    await expireBuild(resolveAscCredentials(appSecretsEnv(app)), buildId);
+    success(`Expired build ${buildId} — it is no longer installable from TestFlight`);
+}

package/dist/commands/update.d.ts

@@ -0,0 +1,16 @@
+export interface UpdateData {
+    channel: 'stable' | 'prerelease';
+    remoteBranch: string;
+    localBranch: string;
+    available: boolean;
+    behind: number;
+    latestSubject: string;
+    /** populated only when an apply actually ran. */
+    pulled?: number;
+    buildOk?: boolean;
+    output?: string;
+    error?: string;
+}
+/** CLI surface for self-update. equivalent to the TUI banner + U key, but
+ *  driveable from a dumb terminal, a cron job, or a Claude session. */
+export declare const updateCommand: import("../registry/types.js").CommandDef<UpdateData>;

package/dist/commands/update.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { checkForUpdate, applyUpdate, resolveChannel } from '../core/self-update.js';
+import { defineCommand } from '../registry/registry.js';
+/** CLI surface for self-update. equivalent to the TUI banner + U key, but
+ *  driveable from a dumb terminal, a cron job, or a Claude session. */
+export const updateCommand = defineCommand({
+    name: 'update',
+    summary: 'Check for or install a fleet update from the configured channel',
+    args: z.object({
+        check: z.boolean().default(false),
+        channel: z.enum(['stable', 'prerelease']).optional(),
+        branch: z.string().optional(),
+    }),
+    async run(args, _ctx) {
+        // env-var overrides apply for the lifetime of this invocation so the
+        // existing resolveChannel logic stays the single source of truth. we
+        // restore the prior environment afterward so an in-process MCP call
+        // doesn't leak the override into subsequent commands.
+        const previous = {
+            channel: process.env.FLEET_UPDATE_CHANNEL,
+            branch: process.env.FLEET_UPDATE_BRANCH,
+        };
+        if (args.channel)
+            process.env.FLEET_UPDATE_CHANNEL = args.channel;
+        if (args.branch)
+            process.env.FLEET_UPDATE_BRANCH = args.branch;
+        try {
+            const info = await checkForUpdate();
+            const channelInfo = resolveChannel();
+            const base = {
+                channel: info.channel,
+                remoteBranch: info.remoteBranch,
+                localBranch: info.branch,
+                available: info.available,
+                behind: info.behind,
+                latestSubject: info.latestSubject,
+                ...(info.error ? { error: info.error } : {}),
+            };
+            if (info.error) {
+                return {
+                    ok: false,
+                    summary: `check failed: ${info.error}`,
+                    data: base,
+                };
+            }
+            if (!info.available) {
+                return {
+                    ok: true,
+                    summary: `up to date (channel=${channelInfo.channel}, branch=${channelInfo.branch})`,
+                    data: base,
+                };
+            }
+            if (args.check) {
+                const subject = info.latestSubject ? ` — ${info.latestSubject}` : '';
+                return {
+                    ok: true,
+                    summary: `update available (channel=${channelInfo.channel}): ${info.behind} commit${info.behind === 1 ? '' : 's'} ahead${subject}`,
+                    data: base,
+                };
+            }
+            const result = await applyUpdate();
+            const data = {
+                ...base,
+                pulled: result.pulled,
+                buildOk: result.buildOk,
+                output: result.output,
+            };
+            if (!result.ok) {
+                return {
+                    ok: false,
+                    summary: `update failed: ${result.output}`,
+                    data,
+                };
+            }
+            return {
+                ok: true,
+                summary: result.pulled === 0
+                    ? 'no changes pulled; rebuild ran'
+                    : `updated ${result.pulled} commit${result.pulled === 1 ? '' : 's'}, rebuilt`,
+                data,
+            };
+        }
+        finally {
+            // restore the prior env unconditionally — even if the call threw.
+            if (previous.channel === undefined)
+                delete process.env.FLEET_UPDATE_CHANNEL;
+            else
+                process.env.FLEET_UPDATE_CHANNEL = previous.channel;
+            if (previous.branch === undefined)
+                delete process.env.FLEET_UPDATE_BRANCH;
+            else
+                process.env.FLEET_UPDATE_BRANCH = previous.branch;
+        }
+    },
+});

package/dist/core/audit/cache.d.ts

@@ -0,0 +1,4 @@
+import type { AuditCache, AuditRecord } from './types.js';
+export declare function loadAuditCache(path?: string): AuditCache;
+export declare function saveAuditRecord(record: AuditRecord, path?: string): void;
+export declare function auditCachePath(): string;

package/dist/core/audit/cache.js

@@ -0,0 +1,37 @@
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CACHE_PATH = join(__dirname, '..', '..', '..', 'data', 'audit-cache.json');
+function emptyCache() {
+    return { version: 1, audits: {} };
+}
+// load the audit cache, returning an empty cache when the file is absent or
+// unreadable — a stale/corrupt cache must never block a fresh audit.
+export function loadAuditCache(path = DEFAULT_CACHE_PATH) {
+    if (!existsSync(path))
+        return emptyCache();
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || typeof parsed !== 'object' || !parsed.audits)
+            return emptyCache();
+        return parsed;
+    }
+    catch {
+        return emptyCache();
+    }
+}
+// upsert one audit record, keyed by target, via an atomic tmp-file rename.
+export function saveAuditRecord(record, path = DEFAULT_CACHE_PATH) {
+    const cache = loadAuditCache(path);
+    cache.audits[record.target] = record;
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify(cache, null, 2) + '\n');
+    renameSync(tmp, path);
+}
+export function auditCachePath() {
+    return DEFAULT_CACHE_PATH;
+}

package/dist/core/audit/config.d.ts

@@ -0,0 +1,5 @@
+import type { AuditConfig } from './types.js';
+export declare function defaultAuditConfig(): AuditConfig;
+export declare function loadAuditConfig(path?: string): AuditConfig;
+export declare function saveAuditConfig(config: AuditConfig, path?: string): void;
+export declare function auditConfigPath(): string;

package/dist/core/audit/config.js

@@ -0,0 +1,35 @@
+import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_CONFIG_PATH = join(__dirname, '..', '..', '..', 'data', 'audit-config.json');
+export function defaultAuditConfig() {
+    return { version: 1, ignore: [] };
+}
+// load the audit config (ignore rules). a missing or corrupt file yields the
+// default empty config — a bad config must never abort an audit.
+export function loadAuditConfig(path = DEFAULT_CONFIG_PATH) {
+    if (!existsSync(path))
+        return defaultAuditConfig();
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (!parsed || !Array.isArray(parsed.ignore))
+            return defaultAuditConfig();
+        return { version: 1, ignore: parsed.ignore };
+    }
+    catch {
+        return defaultAuditConfig();
+    }
+}
+// persist the audit config via an atomic tmp-file rename.
+export function saveAuditConfig(config, path = DEFAULT_CONFIG_PATH) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const tmp = path + '.tmp';
+    writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n');
+    renameSync(tmp, path);
+}
+export function auditConfigPath() {
+    return DEFAULT_CONFIG_PATH;
+}

package/dist/core/audit/greenlight.d.ts

@@ -0,0 +1,11 @@
+import type { GreenlightReport } from './types.js';
+export declare const GREENLIGHT_INSTALL_HINT: string;
+export declare function findGreenlight(): string | null;
+export declare function requireGreenlight(): string;
+export declare function greenlightVersion(bin: string): string | null;
+export interface PreflightOptions {
+    ipaPath?: string;
+    timeoutMs?: number;
+}
+export declare function runPreflight(projectPath: string, opts?: PreflightOptions, bin?: string): GreenlightReport;
+export declare function runGuidelines(args: string[], bin?: string): string;

package/dist/core/audit/greenlight.js

@@ -0,0 +1,81 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { execSafe } from '../exec.js';
+import { FleetError } from '../errors.js';
+export const GREENLIGHT_INSTALL_HINT = [
+    'greenlight binary not found. Install it with one of:',
+    '  go install github.com/RevylAI/greenlight/cmd/greenlight@latest',
+    '  brew install revylai/tap/greenlight',
+    'Then re-run, or point GREENLIGHT_BIN at an absolute path.',
+].join('\n');
+// locate the greenlight binary. honours $GREENLIGHT_BIN first, then anything
+// on $PATH, then the usual `go install` and homebrew destinations. returns the
+// command/path execSafe should invoke, or null when nothing usable is found.
+export function findGreenlight() {
+    const override = process.env.GREENLIGHT_BIN;
+    if (override)
+        return existsSync(override) ? override : null;
+    if (execSafe('greenlight', ['--help'], { timeout: 10_000 }).ok) {
+        return 'greenlight';
+    }
+    const candidates = [];
+    if (process.env.GOBIN)
+        candidates.push(join(process.env.GOBIN, 'greenlight'));
+    const gopath = execSafe('go', ['env', 'GOPATH'], { timeout: 10_000 });
+    if (gopath.ok && gopath.stdout) {
+        candidates.push(join(gopath.stdout.split('\n')[0].trim(), 'bin', 'greenlight'));
+    }
+    candidates.push(join(homedir(), 'go', 'bin', 'greenlight'), '/opt/homebrew/bin/greenlight', '/usr/local/bin/greenlight');
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+// resolve the binary or fail loudly with install guidance.
+export function requireGreenlight() {
+    const bin = findGreenlight();
+    if (!bin)
+        throw new FleetError(GREENLIGHT_INSTALL_HINT);
+    return bin;
+}
+// best-effort version string for diagnostics; null if it can't be read.
+export function greenlightVersion(bin) {
+    const res = execSafe(bin, ['version'], { timeout: 10_000 });
+    if (res.ok && res.stdout)
+        return res.stdout.split('\n')[0].trim();
+    return null;
+}
+// run `greenlight preflight <project> --format json` and parse the report.
+// greenlight exits 0 for any successful scan regardless of how many issues it
+// finds — a non-zero exit means the scan itself failed (bad path, binary
+// error), so that is the only case treated as an error here.
+export function runPreflight(projectPath, opts = {}, bin = requireGreenlight()) {
+    const args = ['preflight', projectPath, '--format', 'json'];
+    if (opts.ipaPath)
+        args.push('--ipa', opts.ipaPath);
+    const res = execSafe(bin, args, { timeout: opts.timeoutMs ?? 120_000 });
+    if (!res.ok) {
+        throw new FleetError(`greenlight preflight failed: ${res.stderr || res.stdout || 'unknown error'}`);
+    }
+    // greenlight prints a human banner (project path, scanner list) to stdout
+    // before the json document even under --format json, so slice from the
+    // first brace. the banner is plain text and never contains one.
+    const jsonStart = res.stdout.indexOf('{');
+    if (jsonStart === -1) {
+        throw new FleetError(`greenlight produced no json report:\n${res.stdout.slice(0, 500)}`);
+    }
+    try {
+        return JSON.parse(res.stdout.slice(jsonStart));
+    }
+    catch {
+        throw new FleetError(`greenlight returned output that is not valid json:\n${res.stdout.slice(0, 500)}`);
+    }
+}
+// passthrough to `greenlight guidelines <args>` (list | show <section> |
+// search <term>) — returns the rendered text for the caller to print.
+export function runGuidelines(args, bin = requireGreenlight()) {
+    const res = execSafe(bin, ['guidelines', ...args], { timeout: 15_000 });
+    return (res.stdout || res.stderr).trim();
+}

package/dist/core/audit/reporters/cli.d.ts

@@ -0,0 +1,3 @@
+import type { GreenlightReport } from '../types.js';
+export declare function severityIcon(severity: string): string;
+export declare function formatReport(report: GreenlightReport): string[];