@yiaany/ghostapi 0.1.6 → 0.1.8

package/dist/cli/index.js

@@ -2,22 +2,35 @@
 import http from "node:http";
 import https from "node:https";
 import net from "node:net";
-import { access, mkdir } from "node:fs/promises";
+import { access, lstat, mkdir, readFile, realpath } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
 import { constants } from "node:fs";
-import { spawn } from "node:child_process";
 import { generate } from "selfsigned";
 import { createServer } from "../server/createServer.js";
 import { clearCache } from "../cache/index.js";
 import { clearState } from "../state/stateStore.js";
 import { clearEvents } from "../server/eventsStore.js";
 import { DEFAULT_MODEL, loadServerConfig } from "../config/serverConfig.js";
-import { CONFIG_PATH, GHOSTAPI_DIR, initializeLocalConfig, readLocalConfig, writeLocalConfig } from "../config/localConfig.js";
-import { isRegisteredProvider, providerRegistry } from "../providers/registry.js";
+import { initializeLocalConfig, readLocalConfig, writeLocalConfig } from "../config/localConfig.js";
+import { getDataPaths } from "../config/dataPaths.js";
+import { detectEgressCapabilities, formatEgressCapabilityReport } from "../egress/capabilities.js";
+import { EgressRunError, runEgressCommand } from "../egress/run.js";
+import { PolicyValidationError, evaluatePolicy, formatPolicyDecision, loadPolicyFile } from "../policy/index.js";
+import { isLoopbackHost } from "../server/accessControl.js";
+import { getProviderManifests, isRegisteredProvider, providerRegistry } from "../providers/registry.js";
 import { parseCliArgs } from "./parser.js";
 import { CliError } from "./errors.js";
 import { startMcpServer } from "../mcp/server.js";
 import { generateRepoSetup, writeRepoSetup } from "../setup/setupGenerator.js";
 import { generateSafetyReport } from "../report/safetyReport.js";
+import { compareEvidenceReports, formatEvidenceCompare, formatEvidenceReport, generateEvidenceReport, loadEvidenceReport, EvidenceReportError } from "../evidence/index.js";
+import { createScenarioReplayer, formatScenarioSanitizationSummary, loadScenarioBundle, prepareScenarioRecordingFromFile, ScenarioBundleError, writeScenarioBundle } from "../scenarios/scenarioBundle.js";
+import { ContractError, diffContracts, formatContractDiff, importHarContractFromFile, importOpenApiContractFromFile, loadContract, writeContract } from "../contracts/index.js";
+import { EvalError, formatEvalReport, runEval } from "../evals/index.js";
+import { SyntheticWorldError, createWorld, forkWorld, formatWorld, inspectWorld, resetWorld } from "../worlds/index.js";
+import { formatProductTelemetry, readProductTelemetry, recordProductTelemetry, setProductTelemetryEnabled } from "../productTelemetry/index.js";
+import { ActionGatewayError, createLocalActionGateway } from "../actions/index.js";
+import { openUrl } from "./openUrl.js";
 async function main() {
     const command = parseCliArgs(process.argv.slice(2));
     switch (command.name) {
@@ -42,7 +55,64 @@ async function main() {
             inspectProvider(command.provider);
             return;
         case "doctor":
-            await runDoctor(command.options.port);
+            await runDoctor(command.options);
+            return;
+        case "run": {
+            const result = await runEgressCommand(command.options);
+            await recordLocalProductTelemetry("enforced_run_completed");
+            process.exitCode = result.exitCode;
+            return;
+        }
+        case "policy-validate":
+            await validatePolicy(command.file);
+            return;
+        case "policy-explain":
+            await explainPolicy(command.file, command.event);
+            return;
+        case "evidence-generate":
+            await generateEvidence(command.options);
+            return;
+        case "evidence-view":
+            await viewEvidence(command.options);
+            return;
+        case "evidence-compare":
+            await compareEvidence(command.options);
+            return;
+        case "record":
+            await recordScenario(command.options);
+            return;
+        case "replay":
+            await replayBundle(command.options);
+            return;
+        case "contract-import-openapi":
+            await importOpenApi(command.options);
+            return;
+        case "contract-import-har":
+            await importHar(command.options);
+            return;
+        case "contract-diff":
+            await diffContractFiles(command.options);
+            return;
+        case "eval":
+            await runEvalCommand(command.options);
+            return;
+        case "world-create":
+            await createWorldCommand(command.options);
+            return;
+        case "world-inspect":
+            await inspectWorldCommand(command.id, command.json === true);
+            return;
+        case "world-reset":
+            await resetWorldCommand(command.id, command.json === true);
+            return;
+        case "world-fork":
+            await forkWorldCommand(command.sourceId, command.options);
+            return;
+        case "action-inspect":
+            await inspectActionCommand(command.actionId, command.json === true);
+            return;
+        case "telemetry":
+            await runTelemetryCommand(command.action, command.json === true);
             return;
         case "init":
             await initProject();
@@ -73,7 +143,9 @@ async function startServer(config, open = false) {
     server.on("error", (error) => {
         if (error.code === "EADDRINUSE") {
             console.error(`Error: Port ${config.port} is already in use.`);
-            console.error(`Hint: Run ghostapi start --port <free-port> or stop the process using ${config.port}.`);
+            console.error(`Reason: Another process is already listening on ${config.host}:${config.port}.`);
+            console.error(`Remediation: Run ghostapi start --port <free-port> or stop the process using ${config.port}.`);
+            console.error("Docs: README.md#quickstart and docs/usage.md");
             process.exit(1);
         }
         console.error(`Error: ${error.message}`);
@@ -81,11 +153,15 @@ async function startServer(config, open = false) {
     });
     server.listen(config.port, config.host, () => {
         const dashboardUrl = `${protocol}://${config.host}:${config.port}/dashboard`;
+        const remote = !isLoopbackHost(config.host);
         console.log(`GhostAPI listening on ${protocol}://${config.host}:${config.port}`);
         console.log(`Dashboard: ${dashboardUrl}`);
-        console.log(`Model: ${config.model}${config.offline ? " (offline)" : ""}`);
+        console.log(`Model: ${config.model}${config.offline ? " (offline)" : config.allowExternalLlm ? " (external LLM opt-in enabled)" : " (local only)"}`);
+        if (remote) {
+            console.warn("Warning: GhostAPI is bound beyond loopback. Use HTTPS or a secure tunnel because the dashboard token does not encrypt traffic.");
+        }
         if (open)
-            openUrl(dashboardUrl);
+            openUrl(remote && config.authToken ? `${dashboardUrl}?token=${encodeURIComponent(config.authToken)}` : dashboardUrl);
     });
 }
 async function createDevTlsOptions(host) {
@@ -112,8 +188,16 @@ async function clearTarget(target) {
 }
 async function initProject() {
     const result = await initializeLocalConfig();
-    console.log(result.created ? `Created ${CONFIG_PATH}.` : `${CONFIG_PATH} already exists.`);
+    const setup = await writeRepoSetup();
+    const configPath = getDataPaths().config;
+    console.log(result.created ? `Created ${configPath}.` : `${configPath} already exists.`);
     console.log(`Model: ${result.config.model ?? DEFAULT_MODEL}`);
+    console.log(`Created setup files: ${setup.result.created.length > 0 ? setup.result.created.join(", ") : "none"}.`);
+    console.log(`Skipped existing setup files: ${setup.result.skipped.length > 0 ? setup.result.skipped.join(", ") : "none"}.`);
+    console.log("Next: ghostapi doctor");
+    console.log("Then on supported Linux hosts: ghostapi run -- npm test");
+    console.log("Otherwise: ghostapi start --open and point SDKs at http://127.0.0.1:8080.");
+    await recordLocalProductTelemetry("init_completed");
 }
 async function printRepoSetup(write) {
     const written = write ? await writeRepoSetup() : null;
@@ -146,12 +230,6 @@ function openDashboard(options) {
     openUrl(url);
     console.log(`Opened ${url}`);
 }
-function openUrl(url) {
-    const command = process.platform === "win32" ? "cmd" : process.platform === "darwin" ? "open" : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
-    const child = spawn(command, args, { detached: true, stdio: "ignore" });
-    child.unref();
-}
 async function printSafetyReport() {
     const report = await generateSafetyReport();
     console.log(`GhostAPI safety report for ${report.projectRoot}`);
@@ -181,8 +259,9 @@ async function setModel(model) {
     console.log(`Model set to ${model}.`);
 }
 function listProviders() {
-    for (const adapter of Object.values(providerRegistry)) {
-        console.log(`${adapter.name.padEnd(8)} ${adapter.displayName}`);
+    for (const manifest of getProviderManifests()) {
+        const version = manifest.packVersion === null ? manifest.implementation : `pack ${manifest.packVersion}`;
+        console.log(`${manifest.name.padEnd(8)} ${manifest.displayName} (${version})`);
     }
 }
 function inspectProvider(provider) {
@@ -190,47 +269,301 @@ function inspectProvider(provider) {
         throw new CliError(`Unknown provider: ${provider}`, `Run ghostapi providers list to see supported providers.`);
     }
     const adapter = providerRegistry[provider];
+    const manifest = getProviderManifests().find((candidate) => candidate.name === provider);
+    if (manifest === undefined)
+        throw new CliError(`Provider manifest missing: ${provider}`);
     console.log(`${adapter.displayName}`);
     console.log(`Name: ${adapter.name}`);
-    console.log(`Mode: ${adapter.name === "generic" ? "fallback" : "built-in adapter"}`);
+    console.log(`Mode: ${manifest.implementation}`);
+    console.log(`Pack version: ${manifest.packVersion ?? "n/a"}`);
+    console.log(`API versions: ${manifest.apiVersions?.supported.join(", ") ?? "legacy"}`);
+    console.log(`Capabilities: ${Object.entries(manifest.capabilities).filter(([, enabled]) => enabled).map(([name]) => name).join(", ")}`);
     console.log("Error formatting: supported");
 }
-async function runDoctor(portOverride) {
-    const config = loadServerConfig(process.env, [], portOverride ? { port: portOverride } : {});
+async function runDoctor(options) {
+    if (options.egress) {
+        const report = detectEgressCapabilities();
+        console.log(options.json ? JSON.stringify(report, null, 2) : formatEgressCapabilityReport(report));
+        return;
+    }
     const checks = [];
+    let config = null;
+    try {
+        config = loadServerConfig(process.env, [], options.port ? { port: options.port } : {});
+        checks.push({ label: "Config", status: "ok", detail: "loaded", docs: "docs/usage.md#configuration" });
+    }
+    catch (error) {
+        checks.push({ label: "Config", status: "fail", detail: error instanceof Error ? error.message : "invalid configuration", remediation: "Fix GHOSTAPI_* environment values or .ghostapi/config.json, then re-run ghostapi doctor.", docs: "docs/usage.md#configuration" });
+    }
     const major = Number(process.versions.node.split(".")[0]);
-    checks.push({ label: "Node version", ok: major >= 20, detail: process.versions.node, hint: "Install Node.js 20 or newer." });
+    checks.push({ label: "Node version", status: major >= 20 ? "ok" : "fail", detail: process.versions.node, remediation: "Install Node.js 20 or newer.", docs: "README.md#quickstart" });
     const writeAccess = await canWriteGhostApiDir();
-    checks.push({ label: ".ghostapi write access", ok: writeAccess, detail: GHOSTAPI_DIR, hint: "Check directory permissions in the project root." });
-    const portAvailable = await isPortAvailable(config.host, config.port);
-    checks.push({ label: "Port availability", ok: portAvailable, detail: `${config.host}:${config.port}`, hint: `Run ghostapi start --port <free-port>.` });
-    checks.push({ label: "Model config", ok: config.model.trim() !== "", detail: config.model, hint: "Run ghostapi model set <model>." });
-    const hasApiKey = Boolean(config.apiKey);
+    checks.push({ label: "GhostAPI data write access", status: writeAccess ? "ok" : "fail", detail: getDataPaths().root, remediation: "Check GHOSTAPI_DATA_DIR and directory permissions.", docs: "README.md#local-files" });
+    if (config !== null) {
+        const portAvailable = await isPortAvailable(config.host, config.port);
+        checks.push({ label: "Port availability", status: portAvailable ? "ok" : "fail", detail: `${config.host}:${config.port}`, remediation: `Run ghostapi start --port <free-port> or stop the process using ${config.port}.`, docs: "README.md#quickstart" });
+        checks.push({ label: "Model config", status: config.model.trim() !== "" ? "ok" : "fail", detail: config.model, remediation: "Run ghostapi model set <model>.", docs: "docs/usage.md#configuration" });
+        const hasApiKey = Boolean(config.apiKey);
+        checks.push({
+            label: "LLM API key",
+            status: config.allowExternalLlm && !hasApiKey ? "fail" : "ok",
+            detail: config.offline ? "offline mode" : config.allowExternalLlm ? hasApiKey ? "explicitly enabled" : "enabled without GHOSTAPI_LLM_API_KEY" : "disabled; deterministic provider mocks enabled",
+            remediation: config.allowExternalLlm && !hasApiKey ? "Set GHOSTAPI_LLM_API_KEY or remove the external LLM opt-in." : undefined,
+            docs: "README.md#safety-model"
+        });
+        const remote = !isLoopbackHost(config.host);
+        checks.push({
+            label: "Remote bind auth",
+            status: !remote || (config.authToken !== undefined && config.authToken.length >= 24) ? "ok" : "fail",
+            detail: remote ? "non-loopback host configured" : "loopback only",
+            remediation: remote ? "Set a strong GHOSTAPI_AUTH_TOKEN and use HTTPS or a secure tunnel." : undefined,
+            docs: "README.md#safety-model"
+        });
+    }
+    const tlsBypass = process.env.NODE_TLS_REJECT_UNAUTHORIZED === "0";
+    checks.push({ label: "TLS safety", status: !tlsBypass ? "ok" : "fail", detail: tlsBypass ? "NODE_TLS_REJECT_UNAUTHORIZED=0" : "safe", remediation: "Unset NODE_TLS_REJECT_UNAUTHORIZED.", docs: "SECURITY.md" });
+    const egress = detectEgressCapabilities();
+    const linuxNamespace = egress.capabilities.find((capability) => capability.id === "linux-network-namespace");
+    const enforcementAvailable = process.platform === "linux" && linuxNamespace !== undefined;
     checks.push({
-        label: "LLM API key",
-        ok: true,
-        detail: config.offline ? "offline mode" : hasApiKey ? "present" : "not required; deterministic provider mocks enabled",
-        hint: hasApiKey || config.offline ? undefined : "Set GHOSTAPI_LLM_API_KEY only if you want AI-generated mocks."
+        label: "Enforcement capability",
+        status: enforcementAvailable ? "warn" : "warn",
+        detail: enforcementAvailable ? linuxNamespace.detail : `ghostapi run process isolation is unsupported/experimental on ${process.platform}`,
+        remediation: enforcementAvailable ? "Run ghostapi run to execute the real preflight; doctor does not launch the target." : "Use ghostapi start --open for local provider simulation, or run enforced tests on Linux.",
+        docs: "docs/security/egress-threat-model.md"
     });
-    const tlsBypass = process.env.NODE_TLS_REJECT_UNAUTHORIZED === "0";
-    checks.push({ label: "TLS safety", ok: !tlsBypass, detail: tlsBypass ? "NODE_TLS_REJECT_UNAUTHORIZED=0" : "safe", hint: "Unset NODE_TLS_REJECT_UNAUTHORIZED." });
-    let failed = 0;
-    for (const check of checks) {
-        const marker = check.ok ? "ok" : "fail";
-        console.log(`${marker.padEnd(4)} ${check.label}: ${check.detail}`);
-        if (!check.ok) {
-            failed += 1;
-            if (check.hint)
-                console.log(`     Hint: ${check.hint}`);
+    if (options.json) {
+        console.log(JSON.stringify({ schemaVersion: 1, checks, egress }, null, 2));
+    }
+    else {
+        for (const check of checks) {
+            console.log(`${check.status.padEnd(4)} ${check.label}: ${check.detail}`);
+            if (check.status !== "ok" && check.remediation)
+                console.log(`     Remediation: ${check.remediation}`);
+            if (check.status !== "ok" && check.docs)
+                console.log(`     Docs: ${check.docs}`);
         }
     }
+    const failed = checks.filter((check) => check.status === "fail").length;
     if (failed > 0)
-        throw new CliError(`Doctor found ${failed} issue${failed === 1 ? "" : "s"}.`);
+        throw new CliError(`Doctor found ${failed} issue${failed === 1 ? "" : "s"}.`, "Fix the failed checks above, then re-run ghostapi doctor.");
+}
+async function validatePolicy(file) {
+    const loaded = await loadPolicyFile(file, process.cwd(), true);
+    if (loaded === null)
+        throw new CliError("Policy file was not found.");
+    console.log(`Policy valid: ${loaded.path}`);
+    console.log(`Schema version: ${loaded.policy.version}`);
+    console.log(`SHA-256: ${loaded.hash}`);
+}
+async function explainPolicy(file, event) {
+    const loaded = await loadPolicyFile(file, process.cwd(), true);
+    if (loaded === null)
+        throw new CliError("Policy file was not found.");
+    console.log(formatPolicyDecision(evaluatePolicy(loaded.policy, event)));
+}
+async function generateEvidence(options) {
+    const { report, path } = await generateEvidenceReport({ policyPath: options.policyPath, runPath: options.runPath, outPath: options.outPath, contractBaselinePath: options.contractBaselinePath, contractCandidatePath: options.contractCandidatePath });
+    if (options.json)
+        console.log(JSON.stringify({ path, report }, null, 2));
+    else {
+        console.log(formatEvidenceReport(report));
+        console.log(`Artifact: ${path}`);
+    }
+    if (options.ci && !report.summary.passed)
+        process.exitCode = 2;
+    await recordLocalProductTelemetry("evidence_generated");
+}
+async function viewEvidence(options) {
+    const report = await loadEvidenceReport(options.path);
+    console.log(options.json ? JSON.stringify(report, null, 2) : formatEvidenceReport(report));
+}
+async function compareEvidence(options) {
+    const left = await loadEvidenceReport(options.leftPath);
+    const right = await loadEvidenceReport(options.rightPath);
+    const result = compareEvidenceReports(left, right);
+    console.log(options.json ? JSON.stringify(result, null, 2) : formatEvidenceCompare(result));
+    if (!result.equal)
+        process.exitCode = 1;
+}
+async function recordScenario(options) {
+    const bundle = await prepareScenarioRecordingFromFile(options.inputPath, {
+        title: options.title,
+        allowedSandboxHosts: options.allowedSandboxHosts,
+        pii: parsePiiRules(options.pii)
+    });
+    console.log(formatScenarioSanitizationSummary(bundle.sanitization));
+    if (bundle.sanitization.requiresApproval && !options.approve) {
+        throw new CliError("Recording was not saved because sanitization found potentially sensitive traffic.", "Review the summary, then re-run the exact command with --approve to save the sanitized bundle.");
+    }
+    const path = await writeScenarioBundle(bundle, options.outPath);
+    console.log(`Bundle: ${path}`);
+}
+async function replayBundle(options) {
+    const bundle = await loadScenarioBundle(options.bundlePath);
+    const requests = await loadReplayRequests(options.requestsPath);
+    const replayer = createScenarioReplayer(bundle);
+    const responses = requests.map((request) => replayer.replay(request));
+    if (replayer.remaining !== 0)
+        throw new CliError(`Replay ended with ${replayer.remaining} interaction${replayer.remaining === 1 ? "" : "s"} remaining.`, "Provide the complete ordered request sequence; GhostAPI never guesses a later match.");
+    if (options.json)
+        console.log(JSON.stringify({ responses }, null, 2));
+    else {
+        console.log(`Replay matched ${responses.length} interaction${responses.length === 1 ? "" : "s"}.`);
+        for (const response of responses)
+            console.log(`  ${response.index}: ${response.status}`);
+    }
+}
+async function importOpenApi(options) {
+    const contract = await importOpenApiContractFromFile(options.inputPath, { title: options.title });
+    const path = await writeContract(contract, options.outPath);
+    console.log(`Contract: ${path}`);
+    console.log(`Operations: ${contract.operations.length}`);
+}
+async function importHar(options) {
+    const { bundle, contract } = await importHarContractFromFile(options.inputPath, {
+        title: options.title,
+        allowedSandboxHosts: options.allowedSandboxHosts,
+        pii: parsePiiRules(options.pii)
+    });
+    console.log(formatScenarioSanitizationSummary(bundle.sanitization));
+    if (bundle.sanitization.requiresApproval && !options.approve) {
+        throw new CliError("HAR import was not saved because sanitization found potentially sensitive traffic.", "Review the summary, then re-run the exact command with --approve to save the sanitized bundle and contract.");
+    }
+    const bundlePath = await writeScenarioBundle(bundle, options.outPath);
+    const contractPath = await writeContract(contract, options.contractOutPath);
+    console.log(`Bundle: ${bundlePath}`);
+    console.log(`Contract: ${contractPath}`);
+}
+async function diffContractFiles(options) {
+    const [baseline, candidate, loadedPolicy] = await Promise.all([
+        loadContract(options.baselinePath),
+        loadContract(options.candidatePath),
+        options.policyPath === undefined ? Promise.resolve(null) : loadPolicyFile(options.policyPath, process.cwd(), true)
+    ]);
+    const diff = diffContracts(baseline, candidate);
+    const decision = loadedPolicy === null ? null : evaluatePolicy(loadedPolicy.policy, { type: "report", productionEgressAttempts: 0, forbiddenCredentialMatches: 0, breakingContractChanges: diff.summary.breaking });
+    if (options.json)
+        console.log(JSON.stringify({ diff, policy: decision }, null, 2));
+    else {
+        console.log(formatContractDiff(diff));
+        if (decision !== null)
+            console.log(`Policy: ${decision.allowed ? "PASS" : "FAIL"} - ${decision.reason}`);
+    }
+    if (options.ci && (decision === null ? diff.summary.breaking > 0 : !decision.allowed))
+        process.exitCode = 2;
+}
+async function runEvalCommand(options) {
+    const { report, path } = await runEval({ specPath: options.specPath, template: options.template, evidencePath: options.evidencePath, outPath: options.outPath });
+    if (options.json)
+        console.log(JSON.stringify({ path, report }, null, 2));
+    else {
+        console.log(formatEvalReport(report));
+        console.log(`Artifact: ${path}`);
+    }
+    if (options.ci && !report.score.passed)
+        process.exitCode = 2;
+    await recordLocalProductTelemetry("eval_completed");
+}
+async function createWorldCommand(options) {
+    const world = await createWorld(options);
+    console.log(options.json ? JSON.stringify(world, null, 2) : `${formatWorld(world)}\nPath: ${getDataPaths().worlds}`);
+}
+async function inspectWorldCommand(id, json) {
+    const world = await inspectWorld(id);
+    console.log(json ? JSON.stringify(world, null, 2) : formatWorld(world));
+}
+async function resetWorldCommand(id, json) {
+    const world = await resetWorld(id);
+    console.log(json ? JSON.stringify(world, null, 2) : `${formatWorld(world)}\nReset: restored baseline state.`);
+}
+async function forkWorldCommand(sourceId, options) {
+    const world = await forkWorld(sourceId, options);
+    console.log(options.json ? JSON.stringify(world, null, 2) : `${formatWorld(world)}\nForked from: ${sourceId}`);
+}
+async function inspectActionCommand(actionId, json) {
+    const record = await createLocalActionGateway().inspect(actionId);
+    console.log(json ? JSON.stringify(record, null, 2) : `Action: ${record.envelope.actionId}\nHash: ${record.actionHash}\nReceipts: ${record.receipts.map((receipt) => receipt.status).join(", ")}`);
+}
+async function runTelemetryCommand(action, json) {
+    const snapshot = action === "enable"
+        ? await setProductTelemetryEnabled(true)
+        : action === "disable"
+            ? await setProductTelemetryEnabled(false)
+            : await readProductTelemetry();
+    if (json) {
+        console.log(JSON.stringify(snapshot, null, 2));
+        return;
+    }
+    console.log(formatProductTelemetry(snapshot));
+    if (action === "disable")
+        console.log("Existing local counters were deleted.");
+    if (action === "enable")
+        console.log("Only aggregate event counts and up to eight ISO weeks are recorded locally after this command; no network export exists.");
+}
+async function recordLocalProductTelemetry(event) {
+    try {
+        await recordProductTelemetry(event);
+    }
+    catch {
+        console.error("Warning: local opt-in product telemetry was not recorded; no telemetry was sent.");
+    }
+}
+function parsePiiRules(value) {
+    if (value === undefined)
+        return undefined;
+    const selected = new Set(value === "none" ? [] : value.split(","));
+    return { emails: selected.has("emails"), phones: selected.has("phones"), addresses: selected.has("addresses") };
+}
+async function loadReplayRequests(path) {
+    const target = isAbsolute(path) ? resolve(path) : resolve(process.cwd(), path);
+    if (!isInsideAllowedRoots(target))
+        throw new CliError("Replay requests path traversal outside the project root or GHOSTAPI_DATA_DIR is not allowed.");
+    const info = await lstat(target);
+    if (!info.isFile() || info.isSymbolicLink())
+        throw new CliError("Replay requests input must be a regular non-symlink file.");
+    if (!await isRealPathInsideAllowedRoots(target))
+        throw new CliError("Replay requests input resolves outside the project root or GHOSTAPI_DATA_DIR through a symlink.");
+    const source = await readFile(target, "utf8");
+    if (Buffer.byteLength(source, "utf8") > 1024 * 1024)
+        throw new CliError("Replay requests input exceeds 1048576 bytes.");
+    let parsed;
+    try {
+        parsed = JSON.parse(source);
+    }
+    catch {
+        throw new CliError("Replay requests input is not valid JSON.");
+    }
+    const requests = Array.isArray(parsed) ? parsed : parsed !== null && typeof parsed === "object" && Array.isArray(parsed.requests) ? parsed.requests : null;
+    if (requests === null || requests.length === 0 || requests.length > 100)
+        throw new CliError("Replay requests input must contain 1-100 requests.");
+    return requests.map((request) => {
+        if (request === null || typeof request !== "object" || Array.isArray(request))
+            throw new CliError("Replay request must be an object.");
+        const candidate = request;
+        if (typeof candidate.method !== "string" || typeof candidate.path !== "string")
+            throw new CliError("Replay request requires string method and path.");
+        return { method: candidate.method, path: candidate.path, headers: candidate.headers, body: candidate.body };
+    });
+}
+function isInsideAllowedRoots(target) {
+    return isInside(process.cwd(), target) || isInside(getDataPaths().root, target);
+}
+function isInside(root, target) {
+    const relativePath = relative(resolve(root), target);
+    return relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
+}
+async function isRealPathInsideAllowedRoots(target) {
+    const realTarget = await realpath(target);
+    const realProjectRoot = await realpath(process.cwd());
+    const dataRoot = await realpath(getDataPaths().root).catch(() => null);
+    return isInside(realProjectRoot, realTarget) || (dataRoot !== null && isInside(dataRoot, realTarget));
 }
 async function canWriteGhostApiDir() {
+    const dataDir = getDataPaths().root;
     try {
-        await mkdir(GHOSTAPI_DIR, { recursive: true });
-        await access(GHOSTAPI_DIR, constants.W_OK);
+        await mkdir(dataDir, { recursive: true });
+        await access(dataDir, constants.W_OK);
         return true;
     }
     catch {
@@ -246,29 +579,76 @@ function isPortAvailable(host, port) {
     });
 }
 function printHelp() {
-    console.log(`GhostAPI CLI
-
-Usage:
-  ghostapi start [--host 127.0.0.1] [--port 8080] [--model gpt-4o-mini] [--offline] [--https] [--open]
-  ghostapi open [--host 127.0.0.1] [--port 8080] [--https]
-  ghostapi clear cache|state|events|all
-  ghostapi model get
-  ghostapi model set <model>
-  ghostapi providers list
-  ghostapi providers inspect <provider>
-  ghostapi setup [--write]
-  ghostapi report
-  ghostapi mcp
-  ghostapi doctor [--port 8080]
+    console.log(`GhostAPI CLI
+
+Usage:
+  ghostapi start [--host 127.0.0.1] [--port 8080] [--model gpt-4o-mini] [--offline] [--https] [--allow-external-llm] [--open]
+  ghostapi open [--host 127.0.0.1] [--port 8080] [--https]
+  ghostapi clear cache|state|events|all
+  ghostapi model get
+  ghostapi model set <model>
+  ghostapi providers list
+  ghostapi providers inspect <provider>
+  ghostapi setup [--write]
+  ghostapi report
+  ghostapi mcp
+  ghostapi doctor [--port 8080] [--json]
+  ghostapi doctor --egress [--json]
+  ghostapi run [--port 8080] [--allow-host localhost] [--policy ghostapi.policy.yaml] -- <command> [args...]
+  ghostapi policy validate [--file ghostapi.policy.yaml]
+  ghostapi policy explain <scenario-id>|network <host>|credential <value>|enforcement <mode>|report <production-attempts> <credential-matches> [--file ghostapi.policy.yaml]
+  ghostapi evidence generate [--policy ghostapi.policy.yaml] [--run .ghostapi/runs/<id>/run.json] [--out .ghostapi/reports/report.json] [--contract-baseline base.contract.json --contract-candidate head.contract.json] [--ci] [--json]
+  ghostapi evidence view <report.json> [--json]
+  ghostapi evidence compare <left.json> <right.json> [--json]
+  ghostapi record --input <capture.json|har.json> --allow-sandbox-host <host> [--out bundle.json] [--title title] [--pii emails,phones,addresses] [--approve]
+  ghostapi replay <bundle.json> --requests <requests.json> [--json]
+  ghostapi contract import-openapi --input <openapi.json> [--out contract.json] [--title title]
+  ghostapi contract import-har --input <capture.har> --allow-sandbox-host <host> [--out bundle.json] [--contract-out contract.json] [--title title] [--pii emails,phones,addresses] [--approve]
+  ghostapi contract diff --baseline <contract.json> --candidate <contract.json> [--policy ghostapi.policy.yaml] [--ci] [--json]
+  ghostapi eval --spec <eval.json>|--template <name> [--evidence report.json] [--out report.eval.json] [--ci] [--json]
+  ghostapi world create --id <world-id> --seed <seed> [--title title] [--json]
+  ghostapi world inspect <world-id> [--json]
+  ghostapi world reset <world-id> [--json]
+  ghostapi world fork <source-world-id> --id <fork-world-id> [--title title] [--json]
+  ghostapi action inspect <action-id> [--json]
+  ghostapi telemetry status|enable|disable|export [--json]
   ghostapi init`);
 }
 main().catch((error) => {
-    if (error instanceof CliError) {
+    if (error instanceof CliError || error instanceof EgressRunError) {
         console.error(`Error: ${error.message}`);
         if (error.hint)
             console.error(`Hint: ${error.hint}`);
         process.exit(1);
     }
+    if (error instanceof PolicyValidationError) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    if (error instanceof EvidenceReportError) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    if (error instanceof ScenarioBundleError) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    if (error instanceof ContractError) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    if (error instanceof EvalError) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    if (error instanceof SyntheticWorldError) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
+    if (error instanceof ActionGatewayError) {
+        console.error(`Error: ${error.message}`);
+        process.exit(1);
+    }
     const message = error instanceof Error ? error.message : "Unknown CLI error";
     console.error(`Error: ${message}`);
     console.error("Hint: Run ghostapi doctor for environment diagnostics.");