@haystackeditor/cli 0.15.13 → 0.15.15

package/dist/verification/contract.js

@@ -0,0 +1,115 @@
+/**
+ * Haystack Verification Contract — `.haystack/verification.yml`
+ *
+ * The contract is the repo-local answer to five questions:
+ *   1. How do I set up and start the app?
+ *   2. How do I know the app is ready? (preflight)
+ *   3. How do I log in as useful test users? (personas)
+ *   4. Which verification flows can I run? (scenarios)
+ *   5. Where do logs, screenshots, and artifacts go?
+ *
+ * This is deliberately separate from `.haystack.json`: that file configures
+ * Haystack's own sandbox verification (services/flows/fixtures the sandbox
+ * drives). The contract instead describes commands the REPO owns — anything
+ * (Haystack, CI, a coding agent, a human) can run them and get the same
+ * evidence. See docs/VERIFICATION-CONTRACT.md.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { z } from 'zod';
+export const CONTRACT_RELATIVE_PATH = '.haystack/verification.yml';
+export const DEFAULT_ARTIFACT_DIR = '.haystack/artifacts';
+const commandString = z.string().min(1, 'command must be a non-empty string');
+const personaSchema = z.object({
+    login: commandString.describe('Command that logs the given persona in (or prints credentials)'),
+    description: z.string().optional(),
+});
+const scenarioSchema = z.object({
+    command: commandString,
+    description: z.string().optional(),
+    /** Free-form labels of what the scenario captures (screenshots, server_logs, ...). Informational. */
+    artifacts: z.array(z.string()).optional(),
+    /** Wall-clock cap for the scenario command. Default applied by the runner. */
+    timeout_seconds: z.number().int().positive().max(7200).optional(),
+    /**
+     * 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.boolean().default(true),
+});
+const safetySchema = z.object({
+    /** Command proving dev-only helpers are disabled in production builds. */
+    production_disabled_check: commandString.optional(),
+    external_services: z.enum(['sandbox_only', 'mocked', 'none']).optional(),
+    allow_real_email: z.boolean().default(false),
+    allow_real_payments: z.boolean().default(false),
+    allow_customer_data: z.boolean().default(false),
+});
+export const verificationContractSchema = z.object({
+    // Accept 1 or "1" — YAML authors will write both.
+    version: z
+        .union([z.literal(1), z.literal('1')])
+        .transform(() => 1),
+    app: z.object({
+        name: commandString,
+        framework: z.string().optional(),
+    }),
+    environment: z.object({
+        setup: commandString.optional(),
+        start: commandString.optional(),
+        preflight: commandString,
+        reset: commandString.optional(),
+        artifact_dir: z.string().default(DEFAULT_ARTIFACT_DIR),
+        log_paths: z.array(z.string()).default([]),
+    }),
+    personas: z.record(personaSchema).default({}),
+    scenarios: z
+        .record(scenarioSchema)
+        .refine((s) => Object.keys(s).length > 0, {
+        message: 'at least one scenario is required',
+    }),
+    safety: safetySchema,
+});
+/**
+ * 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 async function loadContract(rootDir = process.cwd()) {
+    const contractPath = path.join(rootDir, CONTRACT_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = await fs.readFile(contractPath, 'utf-8');
+    }
+    catch {
+        return { status: 'missing', path: contractPath };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+    }
+    catch (err) {
+        return {
+            status: 'invalid',
+            path: contractPath,
+            errors: [`YAML parse error: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    const result = verificationContractSchema.safeParse(parsed);
+    if (!result.success) {
+        return {
+            status: 'invalid',
+            path: contractPath,
+            errors: result.error.issues.map((issue) => `${issue.path.length ? issue.path.join('.') : '(root)'}: ${issue.message}`),
+        };
+    }
+    return { status: 'ok', contract: result.data, path: contractPath };
+}
+/** Resolve the artifact directory to an absolute path, creating it if needed. */
+export async function ensureArtifactDir(contract, rootDir = process.cwd()) {
+    const dir = path.resolve(rootDir, contract.environment.artifact_dir);
+    await fs.mkdir(path.join(dir, 'logs'), { recursive: true });
+    return dir;
+}

package/dist/verification/init.d.ts

@@ -0,0 +1,10 @@
+export interface InitResult {
+    created: string[];
+    skipped: string[];
+}
+export interface InitOptions {
+    force?: boolean;
+    /** Only write the agent skill file (for handing the integration to a coding agent). */
+    skillOnly?: boolean;
+}
+export declare function initVerification(rootDir?: string, options?: InitOptions): Promise<InitResult>;

package/dist/verification/init.js

@@ -0,0 +1,243 @@
+/**
+ * `haystack verification init` — scaffold the verification contract.
+ *
+ * Detection-driven where evidence exists (framework, package manager, dev
+ * command, port, auth-bypass env var), honest TODOs where it doesn't. The
+ * generated smoke scenario is real, not a placeholder: it boots the app,
+ * waits for readiness, captures the root page + server log, and shuts down.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectProject } from '../utils/detect.js';
+import { CONTRACT_RELATIVE_PATH, DEFAULT_ARTIFACT_DIR } from './contract.js';
+const SKILL_TARGET = '.haystack/skills/install-verification/SKILL.md';
+const AGENTS_TARGET = '.haystack/AGENTS.md';
+const PREFLIGHT_SCRIPT = 'scripts/haystack-preflight';
+const SMOKE_SCRIPT = 'scripts/haystack-smoke';
+export async function initVerification(rootDir = process.cwd(), options = {}) {
+    const result = { created: [], skipped: [] };
+    const writeFile = async (relPath, content, executable = false) => {
+        const target = path.join(rootDir, relPath);
+        if (!options.force && (await exists(target))) {
+            result.skipped.push(relPath);
+            return;
+        }
+        await fs.mkdir(path.dirname(target), { recursive: true });
+        await fs.writeFile(target, content, { encoding: 'utf-8', mode: executable ? 0o755 : 0o644 });
+        result.created.push(relPath);
+    };
+    await writeFile(SKILL_TARGET, await readSkillAsset());
+    if (options.skillOnly)
+        return result;
+    const detected = await detectProject(rootDir);
+    const appName = (await readPackageName(rootDir)) ?? path.basename(rootDir);
+    const setupCommand = setupCommandFor(detected.packageManager);
+    const port = detected.suggestedPort ?? 3000;
+    // Evidence-based auth bypass: only prefix the env var when detection found
+    // one in the repo's own env examples (never invent a flag the app ignores).
+    const startCommand = detected.suggestedAuthBypass
+        ? `${detected.suggestedAuthBypass} ${detected.suggestedDevCommand}`
+        : (detected.suggestedDevCommand ?? 'echo "TODO: set your dev-server command" && exit 1');
+    await writeFile(CONTRACT_RELATIVE_PATH, renderContract({ appName, framework: detected.framework, setupCommand, startCommand }));
+    await writeFile(PREFLIGHT_SCRIPT, renderPreflightScript(port), true);
+    await writeFile(SMOKE_SCRIPT, renderSmokeScript(port, startCommand), true);
+    await writeFile(AGENTS_TARGET, renderAgentsDoc());
+    return result;
+}
+async function exists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readPackageName(rootDir) {
+    try {
+        const pkg = JSON.parse(await fs.readFile(path.join(rootDir, 'package.json'), 'utf-8'));
+        return pkg.name?.replace(/^@[^/]+\//, '') ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function readSkillAsset() {
+    // dist/verification/init.js → dist/assets/skills/install-verification.md
+    const assetPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'assets', 'skills', 'install-verification.md');
+    return fs.readFile(assetPath, 'utf-8');
+}
+function setupCommandFor(pm) {
+    switch (pm) {
+        case 'pnpm':
+            return 'pnpm install --frozen-lockfile';
+        case 'yarn':
+            return 'yarn install --frozen-lockfile';
+        case 'bun':
+            return 'bun install';
+        default:
+            return 'npm ci';
+    }
+}
+function renderContract(opts) {
+    return `version: 1
+
+# Haystack Verification Contract
+#
+# Defines how Haystack (and any coding agent) verifies this app: how to set it
+# up, how to know it's ready, how to log in, which flows to run, and where
+# evidence goes. Check it with:
+#
+#   haystack verification validate
+#   haystack verification check-safety
+#   haystack verification run smoke
+
+app:
+  name: "${opts.appName}"
+${opts.framework ? `  framework: "${opts.framework}"\n` : ''}
+environment:
+  setup: "${opts.setupCommand}"
+  start: "${opts.startCommand}"
+  preflight: "bash ${PREFLIGHT_SCRIPT}"
+  # reset: "pnpm db:reset"   # optional: return the environment to a clean state
+  artifact_dir: "${DEFAULT_ARTIFACT_DIR}"
+  log_paths:
+    - "${DEFAULT_ARTIFACT_DIR}/logs/server.log"
+
+# Personas are seeded FAKE users an agent can act as. Wire these up once you
+# have a dev-only login helper — and add safety.production_disabled_check
+# proving that helper is disabled in production builds.
+# personas:
+#   admin:
+#     login: "pnpm haystack:login admin"
+#     description: "Workspace admin test user"
+#   member:
+#     login: "pnpm haystack:login member"
+#     description: "Regular workspace member"
+
+scenarios:
+  smoke:
+    command: "bash ${SMOKE_SCRIPT}"
+    description: "Boot the app, wait until it answers, capture the root page and server log"
+    preflight: false   # the smoke script boots the app itself
+    artifacts:
+      - "server_logs"
+      - "root_html"
+
+safety:
+  # production_disabled_check: "pnpm test:dev-routes-disabled"  # prove dev-only helpers are off in prod builds
+  external_services: "sandbox_only"
+  allow_real_email: false
+  allow_real_payments: false
+  allow_customer_data: false
+`;
+}
+function renderPreflightScript(port) {
+    return `#!/usr/bin/env bash
+# Haystack preflight — exits 0 only when the app is up and answering.
+# Prefer pointing PATH_SUFFIX at a real health endpoint over the root page.
+set -euo pipefail
+
+PORT="\${PORT:-${port}}"
+PATH_SUFFIX="\${PATH_SUFFIX:-/}"
+URL="http://localhost:\${PORT}\${PATH_SUFFIX}"
+TIMEOUT_S="\${TIMEOUT_S:-60}"
+
+for _ in $(seq 1 "\${TIMEOUT_S}"); do
+  if curl -sf -o /dev/null "\${URL}"; then
+    echo "preflight ok: \${URL} is responding"
+    exit 0
+  fi
+  sleep 1
+done
+
+echo "preflight failed: \${URL} did not respond within \${TIMEOUT_S}s" >&2
+exit 1
+`;
+}
+function renderSmokeScript(port, startCommand) {
+    return `#!/usr/bin/env bash
+# Haystack smoke scenario — boots the app, waits for readiness, captures
+# evidence into the artifact directory, then shuts the app down.
+#
+# Evidence produced:
+#   $ARTIFACT_DIR/logs/server.log   full server output
+#   $ARTIFACT_DIR/smoke-root.html   the rendered root page
+#
+# Adapt this to your app: navigate real flows, take screenshots, and append
+# anything you could NOT test to $ARTIFACT_DIR/gaps.txt (one line each).
+set -euo pipefail
+
+ARTIFACT_DIR="\${ARTIFACT_DIR:-${DEFAULT_ARTIFACT_DIR}}"
+PORT="\${PORT:-${port}}"
+mkdir -p "\${ARTIFACT_DIR}/logs"
+
+# Evidence integrity: if something is already listening on the port, captured
+# "evidence" would come from the wrong server. Refuse instead of lying.
+if curl -sf -o /dev/null "http://localhost:\${PORT}/"; then
+  echo "smoke failed: something is already listening on port \${PORT} — stop it or set PORT" >&2
+  exit 1
+fi
+
+${startCommand} > "\${ARTIFACT_DIR}/logs/server.log" 2>&1 &
+SERVER_PID=$!
+# Kill the server's children too — package-manager wrappers (pnpm dev) leave
+# the real dev server as a grandchild.
+cleanup() {
+  pkill -P "\${SERVER_PID}" 2>/dev/null || true
+  kill "\${SERVER_PID}" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+PORT="\${PORT}" bash ${PREFLIGHT_SCRIPT}
+
+curl -sf "http://localhost:\${PORT}/" -o "\${ARTIFACT_DIR}/smoke-root.html"
+test -s "\${ARTIFACT_DIR}/smoke-root.html"
+
+echo "smoke ok: captured \${ARTIFACT_DIR}/smoke-root.html and server log"
+`;
+}
+function renderAgentsDoc() {
+    return `# Haystack Verification — Agent Guide
+
+This repo has a Haystack verification contract at \`${CONTRACT_RELATIVE_PATH}\`.
+Use it whenever you need to prove a change works, not just that it compiles.
+
+## Commands
+
+\`\`\`bash
+haystack verification validate           # is the contract trustworthy?
+haystack verification preflight          # is the app up and answering?
+haystack verification run smoke          # run a scenario, capture evidence
+haystack verification run <scenario>     # any scenario defined in the contract
+haystack verification check-safety       # prove the setup can't hurt anyone
+haystack verification collect-artifacts  # rebuild the manifest from what's on disk
+\`\`\`
+
+## Conventions
+
+- **Artifacts** go under the contract's \`artifact_dir\`. Screenshots, logs,
+  captured pages — anything a human reviewer should see. Each \`run\` writes a
+  \`manifest-<scenario>.json\` and \`review-packet-<scenario>.md\` there.
+- **Gaps**: if a scenario could not test something (a path you skipped, a
+  service you mocked away), append one line describing it to
+  \`<artifact_dir>/gaps.txt\`. Gaps end up in the review packet — silence reads
+  as "covered", so declare what wasn't.
+- **Personas** are seeded fake users. Never use real accounts or customer data.
+
+## Safety rules
+
+- Verification must never send real email, charge real cards, call production
+  third-party APIs, or touch customer data.
+- Dev-only helpers (login shortcuts, seed endpoints) must be gated so they
+  cannot run in production, with a test proving it
+  (\`safety.production_disabled_check\`).
+- Don't write secrets into artifacts — \`check-safety\` scans for them.
+
+## Extending the contract
+
+Follow \`.haystack/skills/install-verification/SKILL.md\` when adding
+scenarios or personas, and keep changes dev-only and reviewable.
+`;
+}

package/dist/verification/manifest.d.ts

@@ -0,0 +1,49 @@
+import type { CommandRunRecord } from './runner.js';
+export type VerificationStatus = 'verified' | 'failed' | 'inconclusive' | 'environment_not_ready' | 'unsafe_to_verify' | 'missing_contract';
+export type ArtifactType = 'screenshot' | 'video' | 'log' | 'json' | 'html' | 'trace' | 'file';
+export interface ArtifactEntry {
+    type: ArtifactType;
+    /** Repo-relative path. */
+    path: string;
+    description?: string;
+    size_bytes?: number;
+}
+export interface ManifestSafety {
+    real_email_sent: boolean;
+    real_payment_attempted: boolean;
+    customer_data_accessed: boolean;
+}
+export interface VerificationManifest {
+    contract_version: '1';
+    status: VerificationStatus;
+    scenario: string;
+    commit_sha: string | null;
+    started_at: string;
+    completed_at: string;
+    commands_run: CommandRunRecord[];
+    artifacts: ArtifactEntry[];
+    /** Known untested paths, read from <artifact_dir>/gaps.txt if the scenario wrote one. */
+    gaps: string[];
+    safety: ManifestSafety;
+}
+export declare function classifyArtifact(filePath: string): ArtifactType;
+export declare function getHeadSha(cwd: string): string | null;
+export interface CollectOptions {
+    rootDir: string;
+    artifactDir: string;
+    /** Extra files (repo-relative or absolute) to include when they exist, e.g. contract log_paths. */
+    extraPaths?: string[];
+    /** Only include files modified at/after this time (a run's start). Omit to include everything. */
+    since?: Date;
+}
+/**
+ * Walk the artifact directory (plus configured log paths) and build the
+ * manifest's artifact list. Manifest/packet outputs from previous runs are
+ * excluded so evidence doesn't nest.
+ */
+export declare function collectArtifacts(opts: CollectOptions): Promise<ArtifactEntry[]>;
+/** Read scenario-declared gaps from `<artifact_dir>/gaps.txt` (one per line), if present. */
+export declare function readGaps(artifactDir: string): Promise<string[]>;
+export declare function writeManifest(manifest: VerificationManifest, artifactDir: string): Promise<string>;
+export declare function renderReviewPacket(manifest: VerificationManifest): string;
+export declare function writeReviewPacket(manifest: VerificationManifest, artifactDir: string): Promise<string>;

package/dist/verification/manifest.js

@@ -0,0 +1,186 @@
+/**
+ * Artifact manifest + review packet.
+ *
+ * The manifest is the standardized output of every verification run — it's
+ * what turns messy command output into reviewable evidence. The review packet
+ * is the same data rendered as markdown for humans (and for posting on PRs).
+ *
+ * Status vocabulary (distinct on purpose — "failed verification" is different
+ * from "could not verify"):
+ *   verified              scenario ran and passed
+ *   failed                scenario ran and failed
+ *   inconclusive          artifacts collected without a run (or mixed signal)
+ *   environment_not_ready preflight/setup failed before the scenario ran
+ *   unsafe_to_verify      safety policy forbids running (real side effects)
+ *   missing_contract      no valid .haystack/verification.yml
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+const EXTENSION_TYPES = {
+    '.png': 'screenshot',
+    '.jpg': 'screenshot',
+    '.jpeg': 'screenshot',
+    '.webp': 'screenshot',
+    '.gif': 'screenshot',
+    '.webm': 'video',
+    '.mp4': 'video',
+    '.mov': 'video',
+    '.log': 'log',
+    '.txt': 'log',
+    '.json': 'json',
+    '.html': 'html',
+    '.zip': 'trace',
+};
+export function classifyArtifact(filePath) {
+    return EXTENSION_TYPES[path.extname(filePath).toLowerCase()] ?? 'file';
+}
+export function getHeadSha(cwd) {
+    const res = spawnSync('git', ['rev-parse', 'HEAD'], { cwd, encoding: 'utf-8' });
+    if (res.status !== 0)
+        return null;
+    return res.stdout.trim() || null;
+}
+/**
+ * Walk the artifact directory (plus configured log paths) and build the
+ * manifest's artifact list. Manifest/packet outputs from previous runs are
+ * excluded so evidence doesn't nest.
+ */
+export async function collectArtifacts(opts) {
+    const entries = [];
+    const seen = new Set();
+    const sinceMs = opts.since ? opts.since.getTime() - 1000 : null; // 1s slack for coarse mtimes
+    const addFile = async (absPath, description) => {
+        const relPath = path.relative(opts.rootDir, absPath);
+        if (seen.has(relPath))
+            return;
+        if (/(^|\/)(manifest[^/]*\.json|review-packet[^/]*\.md)$/.test(relPath))
+            return;
+        let stat;
+        try {
+            stat = await fs.stat(absPath);
+        }
+        catch {
+            return;
+        }
+        if (!stat.isFile())
+            return;
+        if (sinceMs !== null && stat.mtimeMs < sinceMs)
+            return;
+        seen.add(relPath);
+        entries.push({
+            type: classifyArtifact(absPath),
+            path: relPath,
+            ...(description ? { description } : {}),
+            size_bytes: stat.size,
+        });
+    };
+    const walk = async (dir) => {
+        let dirEntries;
+        try {
+            dirEntries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of dirEntries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                await addFile(full);
+            }
+        }
+    };
+    await walk(opts.artifactDir);
+    for (const extra of opts.extraPaths ?? []) {
+        await addFile(path.resolve(opts.rootDir, extra), 'configured log path');
+    }
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return entries;
+}
+/** Read scenario-declared gaps from `<artifact_dir>/gaps.txt` (one per line), if present. */
+export async function readGaps(artifactDir) {
+    try {
+        const raw = await fs.readFile(path.join(artifactDir, 'gaps.txt'), 'utf-8');
+        return raw
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line.length > 0 && !line.startsWith('#'));
+    }
+    catch {
+        return [];
+    }
+}
+export async function writeManifest(manifest, artifactDir) {
+    await fs.mkdir(artifactDir, { recursive: true });
+    const manifestPath = path.join(artifactDir, `manifest-${manifest.scenario}.json`);
+    await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    return manifestPath;
+}
+const STATUS_HEADLINES = {
+    verified: '✅ Verified — evidence looks strong.',
+    failed: '❌ Blocked — verification failed.',
+    inconclusive: '🟡 Needs human review — verification is incomplete.',
+    environment_not_ready: '⚠️ Not ready — the environment could not be prepared, so nothing was verified.',
+    unsafe_to_verify: '🛑 Unsafe — the safety policy allows real external side effects; verification was not run.',
+    missing_contract: '⚠️ Not ready — repo verification contract is missing or broken.',
+};
+export function renderReviewPacket(manifest) {
+    const lines = [];
+    lines.push(`# Haystack Verification — \`${manifest.scenario}\``);
+    lines.push('');
+    lines.push(STATUS_HEADLINES[manifest.status]);
+    lines.push('');
+    lines.push(`- Commit: \`${manifest.commit_sha ?? 'unknown'}\``);
+    lines.push(`- Started: ${manifest.started_at}`);
+    lines.push(`- Completed: ${manifest.completed_at}`);
+    lines.push('');
+    if (manifest.commands_run.length > 0) {
+        lines.push('## Commands run');
+        lines.push('');
+        lines.push('| Command | Status | Duration |');
+        lines.push('|---------|--------|----------|');
+        for (const cmd of manifest.commands_run) {
+            const icon = cmd.status === 'passed' ? '✅' : cmd.status === 'timeout' ? '⏱ timeout' : '❌ failed';
+            lines.push(`| \`${cmd.command.replace(/\|/g, '\\|')}\` | ${icon} | ${(cmd.duration_ms / 1000).toFixed(1)}s |`);
+        }
+        lines.push('');
+    }
+    lines.push('## Artifacts');
+    lines.push('');
+    if (manifest.artifacts.length === 0) {
+        lines.push('_No artifacts were captured._');
+    }
+    else {
+        for (const artifact of manifest.artifacts) {
+            const desc = artifact.description ? ` — ${artifact.description}` : '';
+            lines.push(`- \`${artifact.path}\` (${artifact.type})${desc}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Gaps');
+    lines.push('');
+    if (manifest.gaps.length === 0) {
+        lines.push('_No gaps declared by this scenario._');
+    }
+    else {
+        for (const gap of manifest.gaps) {
+            lines.push(`- ${gap}`);
+        }
+    }
+    lines.push('');
+    lines.push('## Safety');
+    lines.push('');
+    lines.push(`- Real email sent: ${manifest.safety.real_email_sent ? '⚠️ yes' : 'no'}`);
+    lines.push(`- Real payment attempted: ${manifest.safety.real_payment_attempted ? '⚠️ yes' : 'no'}`);
+    lines.push(`- Customer data accessed: ${manifest.safety.customer_data_accessed ? '⚠️ yes' : 'no'}`);
+    lines.push('');
+    return lines.join('\n');
+}
+export async function writeReviewPacket(manifest, artifactDir) {
+    const packetPath = path.join(artifactDir, `review-packet-${manifest.scenario}.md`);
+    await fs.writeFile(packetPath, renderReviewPacket(manifest), 'utf-8');
+    return packetPath;
+}

package/dist/verification/runner.d.ts

@@ -0,0 +1,20 @@
+export type CommandStatus = 'passed' | 'failed' | 'timeout';
+export interface CommandRunRecord {
+    command: string;
+    status: CommandStatus;
+    exit_code: number | null;
+    duration_ms: number;
+    /** Repo-relative path to the captured stdout+stderr log, when one was written. */
+    log_path?: string;
+}
+export interface RunCommandOptions {
+    cwd: string;
+    /** Wall-clock cap; the process group is killed when exceeded. */
+    timeoutMs: number;
+    /** Absolute path to tee combined stdout+stderr into (created if missing). */
+    logFile?: string;
+    env?: Record<string, string>;
+    /** Suppress streaming to the terminal (still captured to logFile). */
+    quiet?: boolean;
+}
+export declare function runCommand(command: string, opts: RunCommandOptions): Promise<CommandRunRecord>;