@haystackeditor/cli 0.15.13 → 0.15.15

package/dist/commands/verification.js

@@ -0,0 +1,291 @@
+/**
+ * `haystack verification ...` — repo-local verification contract commands.
+ *
+ *   init               scaffold .haystack/verification.yml + scripts + skill
+ *   validate           can Haystack trust this repo's verification setup?
+ *   preflight          is the app up and answering?
+ *   run <scenario>     run a scenario, capture artifacts, write manifest + review packet
+ *   collect-artifacts  rebuild a manifest from artifacts already on disk
+ *   check-safety       prove the verification setup can't hurt anyone
+ *
+ * See docs/VERIFICATION-CONTRACT.md for the product framing and schema.
+ */
+import * as path from 'node:path';
+import chalk from 'chalk';
+import { CONTRACT_RELATIVE_PATH, ensureArtifactDir, loadContract, } from '../verification/contract.js';
+import { initVerification } from '../verification/init.js';
+import { validateContract } from '../verification/validate.js';
+import { checkSafety } from '../verification/safety.js';
+import { runCommand } from '../verification/runner.js';
+import { collectArtifacts, getHeadSha, readGaps, writeManifest, writeReviewPacket, } from '../verification/manifest.js';
+const DEFAULT_SCENARIO_TIMEOUT_S = 900;
+const PREFLIGHT_TIMEOUT_S = 300;
+// ─── init ─────────────────────────────────────────────────────────────────────
+export async function verificationInitCommand(options) {
+    const result = await initVerification(process.cwd(), {
+        force: options.force,
+        skillOnly: options.skill,
+    });
+    for (const file of result.created) {
+        console.log(chalk.green('  created ') + file);
+    }
+    for (const file of result.skipped) {
+        console.log(chalk.yellow('  skipped ') + file + chalk.dim(' (exists, use --force to overwrite)'));
+    }
+    if (result.created.length > 0) {
+        console.log();
+        console.log(chalk.white('Next steps:'));
+        console.log(chalk.cyan('  1.') + ` Review ${CONTRACT_RELATIVE_PATH} — detection is a starting point, not truth`);
+        console.log(chalk.cyan('  2.') + ' haystack verification validate');
+        console.log(chalk.cyan('  3.') + ' haystack verification run smoke');
+        if (options.skill) {
+            console.log();
+            console.log(chalk.dim('Hand .haystack/skills/install-verification/SKILL.md to your coding agent to complete the integration.'));
+        }
+    }
+}
+// ─── validate ─────────────────────────────────────────────────────────────────
+export async function verificationValidateCommand(options) {
+    const report = await validateContract();
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        printValidationReport(report);
+    }
+    if (report.readiness === 'unsafe')
+        process.exit(2);
+    if (report.readiness === 'not_ready')
+        process.exit(1);
+}
+function printValidationReport(report) {
+    const styles = {
+        ready: chalk.green,
+        partially_ready: chalk.yellow,
+        not_ready: chalk.red,
+        unsafe: chalk.red,
+    };
+    console.log(chalk.white('Haystack Verification Contract: ') + styles[report.readiness](report.readiness));
+    console.log();
+    const sections = [
+        { title: 'Passed', level: 'pass', bullet: chalk.green('✓') },
+        { title: 'Missing', level: 'warn', bullet: chalk.yellow('•') },
+        { title: 'Broken', level: 'fail', bullet: chalk.red('✗') },
+        { title: 'Unsafe', level: 'unsafe', bullet: chalk.red('⚠') },
+    ];
+    for (const { title, level, bullet } of sections) {
+        const items = report.items.filter((i) => i.level === level);
+        if (items.length === 0)
+            continue;
+        console.log(chalk.white(`${title}:`));
+        for (const item of items) {
+            console.log(`${bullet} ${item.message}`);
+        }
+        console.log();
+    }
+}
+// ─── preflight ────────────────────────────────────────────────────────────────
+export async function verificationPreflightCommand() {
+    const contract = await requireContract();
+    const artifactDir = await ensureArtifactDir(contract);
+    const record = await runCommand(contract.environment.preflight, {
+        cwd: process.cwd(),
+        timeoutMs: PREFLIGHT_TIMEOUT_S * 1000,
+        logFile: path.join(artifactDir, 'logs', 'preflight.log'),
+        env: { ARTIFACT_DIR: artifactDir },
+    });
+    if (record.status === 'passed') {
+        console.log(chalk.green('✓ preflight passed') + chalk.dim(` (${(record.duration_ms / 1000).toFixed(1)}s)`));
+    }
+    else {
+        console.error(chalk.red(`✗ preflight ${record.status}`) + chalk.dim(` — see ${record.log_path}`));
+        process.exit(1);
+    }
+}
+// ─── run <scenario> ───────────────────────────────────────────────────────────
+export async function verificationRunCommand(scenarioName, options) {
+    const rootDir = process.cwd();
+    const contract = await requireContract();
+    const scenario = contract.scenarios[scenarioName];
+    if (!scenario) {
+        console.error(chalk.red(`Unknown scenario "${scenarioName}".`) +
+            ` Available: ${Object.keys(contract.scenarios).join(', ')}`);
+        process.exit(1);
+    }
+    const artifactDir = await ensureArtifactDir(contract);
+    const startedAt = new Date();
+    const commandsRun = [];
+    const env = { ARTIFACT_DIR: artifactDir };
+    // In --json mode stdout must carry ONLY the manifest — send progress to
+    // stderr and keep command streaming off (output still lands in log files).
+    const quiet = Boolean(options.json);
+    const progress = (msg) => (quiet ? console.error(msg) : console.log(msg));
+    const finish = async (status) => {
+        const manifest = {
+            contract_version: '1',
+            status,
+            scenario: scenarioName,
+            commit_sha: getHeadSha(rootDir),
+            started_at: startedAt.toISOString(),
+            completed_at: new Date().toISOString(),
+            commands_run: commandsRun,
+            artifacts: await collectArtifacts({
+                rootDir,
+                artifactDir,
+                extraPaths: contract.environment.log_paths,
+                since: startedAt,
+            }),
+            gaps: await readGaps(artifactDir),
+            safety: {
+                real_email_sent: contract.safety.allow_real_email,
+                real_payment_attempted: contract.safety.allow_real_payments,
+                customer_data_accessed: contract.safety.allow_customer_data,
+            },
+        };
+        const manifestPath = await writeManifest(manifest, artifactDir);
+        const packetPath = await writeReviewPacket(manifest, artifactDir);
+        if (options.json) {
+            console.log(JSON.stringify(manifest, null, 2));
+        }
+        else {
+            printRunSummary(manifest, manifestPath, packetPath, rootDir);
+        }
+        process.exit(status === 'verified' ? 0 : status === 'unsafe_to_verify' ? 2 : 1);
+    };
+    // Safety gate before anything runs.
+    const { safety } = contract;
+    if (safety.allow_real_email || safety.allow_real_payments || safety.allow_customer_data) {
+        console.error(chalk.red('Refusing to run: the safety policy permits real external side effects.') +
+            ' Fix the safety section of the contract first.');
+        await finish('unsafe_to_verify');
+    }
+    if (options.setup && contract.environment.setup) {
+        progress(chalk.dim(`$ ${contract.environment.setup}`));
+        const setup = await runCommand(contract.environment.setup, {
+            cwd: rootDir,
+            timeoutMs: 15 * 60 * 1000,
+            logFile: path.join(artifactDir, 'logs', 'setup.log'),
+            env,
+            quiet,
+        });
+        commandsRun.push(setup);
+        if (setup.status !== 'passed')
+            await finish('environment_not_ready');
+    }
+    if (!options.skipPreflight && scenario.preflight) {
+        progress(chalk.dim(`$ ${contract.environment.preflight}`));
+        const preflight = await runCommand(contract.environment.preflight, {
+            cwd: rootDir,
+            timeoutMs: PREFLIGHT_TIMEOUT_S * 1000,
+            logFile: path.join(artifactDir, 'logs', 'preflight.log'),
+            env,
+            quiet,
+        });
+        commandsRun.push(preflight);
+        if (preflight.status !== 'passed')
+            await finish('environment_not_ready');
+    }
+    const timeoutS = options.timeout ?? scenario.timeout_seconds ?? DEFAULT_SCENARIO_TIMEOUT_S;
+    progress(chalk.dim(`$ ${scenario.command}`));
+    const run = await runCommand(scenario.command, {
+        cwd: rootDir,
+        timeoutMs: timeoutS * 1000,
+        logFile: path.join(artifactDir, 'logs', `scenario-${scenarioName}.log`),
+        env,
+        quiet,
+    });
+    commandsRun.push(run);
+    await finish(run.status === 'passed' ? 'verified' : 'failed');
+}
+function printRunSummary(manifest, manifestPath, packetPath, rootDir) {
+    const statusStyle = {
+        verified: chalk.green,
+        failed: chalk.red,
+        inconclusive: chalk.yellow,
+        environment_not_ready: chalk.yellow,
+        unsafe_to_verify: chalk.red,
+        missing_contract: chalk.red,
+    };
+    console.log();
+    console.log(chalk.white('Scenario: ') + manifest.scenario);
+    console.log(chalk.white('Status:   ') + statusStyle[manifest.status](manifest.status));
+    console.log(chalk.white('Evidence: ') + `${manifest.artifacts.length} artifact(s)`);
+    if (manifest.gaps.length > 0) {
+        console.log(chalk.white('Gaps:     ') + chalk.yellow(`${manifest.gaps.length} declared`));
+    }
+    console.log();
+    console.log(chalk.dim(`Manifest:      ${path.relative(rootDir, manifestPath)}`));
+    console.log(chalk.dim(`Review packet: ${path.relative(rootDir, packetPath)}`));
+}
+// ─── collect-artifacts ────────────────────────────────────────────────────────
+export async function verificationCollectCommand(options) {
+    const rootDir = process.cwd();
+    const contract = await requireContract();
+    const artifactDir = await ensureArtifactDir(contract);
+    const now = new Date().toISOString();
+    const manifest = {
+        contract_version: '1',
+        // Artifacts without a recorded run prove presence, not success.
+        status: 'inconclusive',
+        scenario: options.scenario ?? 'collected',
+        commit_sha: getHeadSha(rootDir),
+        started_at: now,
+        completed_at: now,
+        commands_run: [],
+        artifacts: await collectArtifacts({
+            rootDir,
+            artifactDir,
+            extraPaths: contract.environment.log_paths,
+        }),
+        gaps: await readGaps(artifactDir),
+        safety: {
+            real_email_sent: contract.safety.allow_real_email,
+            real_payment_attempted: contract.safety.allow_real_payments,
+            customer_data_accessed: contract.safety.allow_customer_data,
+        },
+    };
+    const manifestPath = await writeManifest(manifest, artifactDir);
+    const packetPath = await writeReviewPacket(manifest, artifactDir);
+    if (options.json) {
+        console.log(JSON.stringify(manifest, null, 2));
+    }
+    else {
+        printRunSummary(manifest, manifestPath, packetPath, rootDir);
+    }
+}
+// ─── check-safety ─────────────────────────────────────────────────────────────
+export async function verificationCheckSafetyCommand(options) {
+    const report = await checkSafety();
+    if (options.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        for (const check of report.checks) {
+            const bullet = check.status === 'pass' ? chalk.green('✓') : check.status === 'warn' ? chalk.yellow('•') : chalk.red('✗');
+            console.log(`${bullet} ${chalk.white(check.name)}: ${check.detail}`);
+        }
+        console.log();
+        console.log(report.ok
+            ? chalk.green('Safety checks passed.')
+            : chalk.red('Safety checks failed — fix the items above before running verification.'));
+    }
+    if (!report.ok)
+        process.exit(1);
+}
+// ─── shared ───────────────────────────────────────────────────────────────────
+async function requireContract() {
+    const loaded = await loadContract();
+    if (loaded.status === 'missing') {
+        console.error(chalk.red(`No verification contract found at ${CONTRACT_RELATIVE_PATH}.`) +
+            ' Run `haystack verification init` to scaffold one.');
+        process.exit(1);
+    }
+    if (loaded.status === 'invalid') {
+        console.error(chalk.red(`Invalid ${CONTRACT_RELATIVE_PATH}:`));
+        for (const error of loaded.errors) {
+            console.error(chalk.red(`  ✗ ${error}`));
+        }
+        process.exit(1);
+    }
+    return loaded.contract;
+}

package/dist/index.js

@@ -41,6 +41,7 @@ import { setupCommand } from './commands/setup.js';
 import { schemaCommand, listSchemas } from './commands/schema-cmd.js';
 import { registerWebhook, listWebhooks, rotateWebhookSecret, setWebhookEnabled, listDeliveries, replayDelivery, } from './commands/webhooks.js';
 import { editRulesCommand, validateRulesCommand } from './commands/rules.js';
+import { verificationInitCommand, verificationValidateCommand, verificationPreflightCommand, verificationRunCommand, verificationCollectCommand, verificationCheckSafetyCommand, } from './commands/verification.js';
 import { headlessLoginCommand, headlessLogoutCommand, listTokensCommand, revokeTokenCommand, } from './commands/tokens.js';
 // `mcp` is imported lazily inside its command action (below), NOT at the top level.
 // It is the only module that pulls in `@modelcontextprotocol/sdk`; keeping it out of
@@ -817,6 +818,135 @@ rules
         process.exit(1);
     }
 });
+// ─── verification ────────────────────────────────────────────────────────────
+//
+// Repo-local verification contract (.haystack/verification.yml): how to boot
+// the app, prove it's ready, log in as test personas, run scenarios, and
+// collect evidence into a standard artifact manifest + review packet.
+// See docs/VERIFICATION-CONTRACT.md.
+const verification = program
+    .command('verification')
+    .description('Repo verification contract — validate, run scenarios, collect evidence');
+verification
+    .command('init')
+    .description('Scaffold .haystack/verification.yml, preflight/smoke scripts, and the agent skill')
+    .option('-f, --force', 'Overwrite existing files')
+    .option('--skill', 'Only write the install-verification agent skill (hand the integration to a coding agent)')
+    .addHelpText('after', `
+Creates:
+  .haystack/verification.yml                       the verification contract
+  scripts/haystack-preflight                       app-is-ready check
+  scripts/haystack-smoke                           boot + capture-evidence smoke scenario
+  .haystack/AGENTS.md                              how agents should use the contract
+  .haystack/skills/install-verification/SKILL.md   skill for completing the integration
+
+Detection fills in framework, package manager, dev command, port, and any
+auth-bypass env var found in the repo's own env examples. Review the output —
+detection is a starting point, not truth.
+`)
+    .action(async (opts) => {
+    try {
+        await verificationInitCommand(opts);
+    }
+    catch (err) {
+        console.error(chalk.red('init failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+verification
+    .command('validate')
+    .description('Check whether the repo satisfies the verification contract')
+    .option('--json', 'Machine-readable report')
+    .addHelpText('after', `
+Readiness verdicts:
+  ready            all checks pass (exit 0)
+  partially_ready  usable, with gaps (exit 0)
+  not_ready        contract missing/invalid or commands broken (exit 1)
+  unsafe           contract permits real side effects, or login helpers
+                   lack a production-disabled proof (exit 2)
+`)
+    .action(async (opts) => {
+    try {
+        await verificationValidateCommand(opts);
+    }
+    catch (err) {
+        console.error(chalk.red('validate failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+verification
+    .command('preflight')
+    .description('Run the contract preflight — is the app up and answering?')
+    .action(async () => {
+    try {
+        await verificationPreflightCommand();
+    }
+    catch (err) {
+        console.error(chalk.red('preflight failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+verification
+    .command('run <scenario>')
+    .description('Run a contract scenario and write the artifact manifest + review packet')
+    .option('--json', 'Print the manifest as JSON')
+    .option('--setup', 'Run environment.setup first (clean-clone mode)')
+    .option('--skip-preflight', 'Skip the preflight check')
+    .option('--timeout <seconds>', 'Override the scenario timeout', (v) => parseInt(v, 10))
+    .addHelpText('after', `
+Runs preflight, then the scenario command, capturing stdout/stderr to the
+artifact directory. Ends with a status:
+  verified               scenario passed (exit 0)
+  failed                 scenario failed (exit 1)
+  environment_not_ready  setup/preflight failed before the scenario ran (exit 1)
+  unsafe_to_verify       safety policy permits real side effects (exit 2)
+
+Evidence lands in the contract's artifact_dir:
+  manifest-<scenario>.json        machine-readable evidence manifest
+  review-packet-<scenario>.md     human-readable review packet
+  logs/                           captured command output
+
+Examples:
+  haystack verification run smoke
+  haystack verification run billing_upgrade --json
+  haystack verification run smoke --setup            # clean-clone mode (CI)
+`)
+    .action(async (scenario, opts) => {
+    try {
+        await verificationRunCommand(scenario, opts);
+    }
+    catch (err) {
+        console.error(chalk.red('run failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+verification
+    .command('collect-artifacts')
+    .description('Rebuild an evidence manifest from artifacts already on disk (status: inconclusive)')
+    .option('--scenario <name>', 'Scenario name to record in the manifest')
+    .option('--json', 'Print the manifest as JSON')
+    .action(async (opts) => {
+    try {
+        await verificationCollectCommand(opts);
+    }
+    catch (err) {
+        console.error(chalk.red('collect-artifacts failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+verification
+    .command('check-safety')
+    .description('Verify the verification setup is safe (policy, prod-disabled proof, dev-route gating, secret scan)')
+    .option('--json', 'Machine-readable report')
+    .action(async (opts) => {
+    try {
+        await verificationCheckSafetyCommand(opts);
+    }
+    catch (err) {
+        console.error(chalk.red('check-safety failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
 // ─── mcp ─────────────────────────────────────────────────────────────────────
 program
     .command('mcp')

package/dist/utils/detect.js

@@ -283,7 +283,9 @@ async function detectAuthBypass(rootDir) {
             // File not found
         }
     }
-    return 'SKIP_AUTH=true'; // Default suggestion
+    // No evidence of an auth-bypass variable — suggest nothing rather than
+    // fabricating a SKIP_AUTH the app doesn't read.
+    return undefined;
 }
 /**
  * Set suggestions based on detected framework

package/dist/verification/contract.d.ts

@@ -0,0 +1,240 @@
+import { z } from 'zod';
+export declare const CONTRACT_RELATIVE_PATH = ".haystack/verification.yml";
+export declare const DEFAULT_ARTIFACT_DIR = ".haystack/artifacts";
+declare const scenarioSchema: z.ZodObject<{
+    command: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    /** Free-form labels of what the scenario captures (screenshots, server_logs, ...). Informational. */
+    artifacts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Wall-clock cap for the scenario command. Default applied by the runner. */
+    timeout_seconds: z.ZodOptional<z.ZodNumber>;
+    /**
+     * Whether `run` gates this scenario on environment.preflight. Set false for
+     * self-contained scenarios that boot the app themselves (like the scaffolded
+     * smoke script) — preflight against a cold environment would always fail.
+     */
+    preflight: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    command: string;
+    preflight: boolean;
+    description?: string | undefined;
+    artifacts?: string[] | undefined;
+    timeout_seconds?: number | undefined;
+}, {
+    command: string;
+    description?: string | undefined;
+    artifacts?: string[] | undefined;
+    timeout_seconds?: number | undefined;
+    preflight?: boolean | undefined;
+}>;
+declare const safetySchema: z.ZodObject<{
+    /** Command proving dev-only helpers are disabled in production builds. */
+    production_disabled_check: z.ZodOptional<z.ZodString>;
+    external_services: z.ZodOptional<z.ZodEnum<["sandbox_only", "mocked", "none"]>>;
+    allow_real_email: z.ZodDefault<z.ZodBoolean>;
+    allow_real_payments: z.ZodDefault<z.ZodBoolean>;
+    allow_customer_data: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    allow_real_email: boolean;
+    allow_real_payments: boolean;
+    allow_customer_data: boolean;
+    production_disabled_check?: string | undefined;
+    external_services?: "none" | "sandbox_only" | "mocked" | undefined;
+}, {
+    production_disabled_check?: string | undefined;
+    external_services?: "none" | "sandbox_only" | "mocked" | undefined;
+    allow_real_email?: boolean | undefined;
+    allow_real_payments?: boolean | undefined;
+    allow_customer_data?: boolean | undefined;
+}>;
+export declare const verificationContractSchema: z.ZodObject<{
+    version: z.ZodEffects<z.ZodUnion<[z.ZodLiteral<1>, z.ZodLiteral<"1">]>, 1, 1 | "1">;
+    app: z.ZodObject<{
+        name: z.ZodString;
+        framework: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        framework?: string | undefined;
+    }, {
+        name: string;
+        framework?: string | undefined;
+    }>;
+    environment: z.ZodObject<{
+        setup: z.ZodOptional<z.ZodString>;
+        start: z.ZodOptional<z.ZodString>;
+        preflight: z.ZodString;
+        reset: z.ZodOptional<z.ZodString>;
+        artifact_dir: z.ZodDefault<z.ZodString>;
+        log_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        preflight: string;
+        artifact_dir: string;
+        log_paths: string[];
+        start?: string | undefined;
+        setup?: string | undefined;
+        reset?: string | undefined;
+    }, {
+        preflight: string;
+        start?: string | undefined;
+        setup?: string | undefined;
+        reset?: string | undefined;
+        artifact_dir?: string | undefined;
+        log_paths?: string[] | undefined;
+    }>;
+    personas: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        login: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        login: string;
+        description?: string | undefined;
+    }, {
+        login: string;
+        description?: string | undefined;
+    }>>>;
+    scenarios: z.ZodEffects<z.ZodRecord<z.ZodString, z.ZodObject<{
+        command: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        /** Free-form labels of what the scenario captures (screenshots, server_logs, ...). Informational. */
+        artifacts: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        /** Wall-clock cap for the scenario command. Default applied by the runner. */
+        timeout_seconds: z.ZodOptional<z.ZodNumber>;
+        /**
+         * Whether `run` gates this scenario on environment.preflight. Set false for
+         * self-contained scenarios that boot the app themselves (like the scaffolded
+         * smoke script) — preflight against a cold environment would always fail.
+         */
+        preflight: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        command: string;
+        preflight: boolean;
+        description?: string | undefined;
+        artifacts?: string[] | undefined;
+        timeout_seconds?: number | undefined;
+    }, {
+        command: string;
+        description?: string | undefined;
+        artifacts?: string[] | undefined;
+        timeout_seconds?: number | undefined;
+        preflight?: boolean | undefined;
+    }>>, Record<string, {
+        command: string;
+        preflight: boolean;
+        description?: string | undefined;
+        artifacts?: string[] | undefined;
+        timeout_seconds?: number | undefined;
+    }>, Record<string, {
+        command: string;
+        description?: string | undefined;
+        artifacts?: string[] | undefined;
+        timeout_seconds?: number | undefined;
+        preflight?: boolean | undefined;
+    }>>;
+    safety: z.ZodObject<{
+        /** Command proving dev-only helpers are disabled in production builds. */
+        production_disabled_check: z.ZodOptional<z.ZodString>;
+        external_services: z.ZodOptional<z.ZodEnum<["sandbox_only", "mocked", "none"]>>;
+        allow_real_email: z.ZodDefault<z.ZodBoolean>;
+        allow_real_payments: z.ZodDefault<z.ZodBoolean>;
+        allow_customer_data: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        allow_real_email: boolean;
+        allow_real_payments: boolean;
+        allow_customer_data: boolean;
+        production_disabled_check?: string | undefined;
+        external_services?: "none" | "sandbox_only" | "mocked" | undefined;
+    }, {
+        production_disabled_check?: string | undefined;
+        external_services?: "none" | "sandbox_only" | "mocked" | undefined;
+        allow_real_email?: boolean | undefined;
+        allow_real_payments?: boolean | undefined;
+        allow_customer_data?: boolean | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    app: {
+        name: string;
+        framework?: string | undefined;
+    };
+    environment: {
+        preflight: string;
+        artifact_dir: string;
+        log_paths: string[];
+        start?: string | undefined;
+        setup?: string | undefined;
+        reset?: string | undefined;
+    };
+    personas: Record<string, {
+        login: string;
+        description?: string | undefined;
+    }>;
+    scenarios: Record<string, {
+        command: string;
+        preflight: boolean;
+        description?: string | undefined;
+        artifacts?: string[] | undefined;
+        timeout_seconds?: number | undefined;
+    }>;
+    safety: {
+        allow_real_email: boolean;
+        allow_real_payments: boolean;
+        allow_customer_data: boolean;
+        production_disabled_check?: string | undefined;
+        external_services?: "none" | "sandbox_only" | "mocked" | undefined;
+    };
+}, {
+    version: 1 | "1";
+    app: {
+        name: string;
+        framework?: string | undefined;
+    };
+    environment: {
+        preflight: string;
+        start?: string | undefined;
+        setup?: string | undefined;
+        reset?: string | undefined;
+        artifact_dir?: string | undefined;
+        log_paths?: string[] | undefined;
+    };
+    scenarios: Record<string, {
+        command: string;
+        description?: string | undefined;
+        artifacts?: string[] | undefined;
+        timeout_seconds?: number | undefined;
+        preflight?: boolean | undefined;
+    }>;
+    safety: {
+        production_disabled_check?: string | undefined;
+        external_services?: "none" | "sandbox_only" | "mocked" | undefined;
+        allow_real_email?: boolean | undefined;
+        allow_real_payments?: boolean | undefined;
+        allow_customer_data?: boolean | undefined;
+    };
+    personas?: Record<string, {
+        login: string;
+        description?: string | undefined;
+    }> | undefined;
+}>;
+export type VerificationContract = z.infer<typeof verificationContractSchema>;
+export type VerificationScenario = z.infer<typeof scenarioSchema>;
+export type VerificationSafety = z.infer<typeof safetySchema>;
+export type ContractLoadResult = {
+    status: 'ok';
+    contract: VerificationContract;
+    path: string;
+} | {
+    status: 'missing';
+    path: string;
+} | {
+    status: 'invalid';
+    path: string;
+    errors: string[];
+};
+/**
+ * Load and validate the contract from `<rootDir>/.haystack/verification.yml`.
+ * Never throws — parse/schema failures come back as `status: 'invalid'` so
+ * callers can map them onto readiness / manifest statuses.
+ */
+export declare function loadContract(rootDir?: string): Promise<ContractLoadResult>;
+/** Resolve the artifact directory to an absolute path, creating it if needed. */
+export declare function ensureArtifactDir(contract: VerificationContract, rootDir?: string): Promise<string>;
+export {};