@shrkcrft/inspector 0.1.0-alpha.2

package/dist/release-readiness.js

@@ -0,0 +1,456 @@
+/**
+ * Aggregated release-readiness gate. Composes the existing read-only audits
+ * into one verdict so reviewers can answer "is this safe to tag?" without
+ * remembering every individual command.
+ *
+ * Pure read-only: never writes, never publishes, never invokes shells.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import * as nodePath from 'node:path';
+import { buildCoverageReport } from "./coverage-report.js";
+import { runDoctor } from "./sharkcraft-inspector.js";
+import { buildPackDoctorReport, runPackReleaseChecksForReport, mergePackReleaseChecks } from "./pack-doctor.js";
+import { buildDocsCheck } from "./docs-check.js";
+import { buildExamplesCheck } from "./examples-check.js";
+import { buildPackSignatureStatusReport } from "./pack-signature-status.js";
+/** Max age in days for a preflight summary file before it's flagged stale. */
+export const PREFLIGHT_STALE_AFTER_DAYS = 7;
+export const RELEASE_READINESS_SCHEMA = 'sharkcraft.release-readiness/v1';
+export var ReleaseReadinessSeverity;
+(function (ReleaseReadinessSeverity) {
+    ReleaseReadinessSeverity["Info"] = "info";
+    ReleaseReadinessSeverity["Warning"] = "warning";
+    ReleaseReadinessSeverity["Error"] = "error";
+})(ReleaseReadinessSeverity || (ReleaseReadinessSeverity = {}));
+/** Auto-discover the newest preflight summary file. */
+export function findNewestPreflightSummary(projectRoot) {
+    const candidates = [];
+    const knownDirs = [
+        nodePath.join(projectRoot, '.sharkcraft', 'reports'),
+        nodePath.join(projectRoot, '.sharkcraft', 'release'),
+        projectRoot,
+    ];
+    for (const dir of knownDirs) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            if (!/preflight/i.test(e) || !e.endsWith('.json'))
+                continue;
+            candidates.push(nodePath.join(dir, e));
+        }
+    }
+    if (candidates.length === 0)
+        return null;
+    let best = null;
+    for (const file of candidates) {
+        let mtime = 0;
+        try {
+            mtime = statSync(file).mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (!best || mtime > best.mtime)
+            best = { file, mtime };
+    }
+    return best ? best.file : null;
+}
+function resolvePreflightFile(projectRoot, optionValue) {
+    if (!optionValue)
+        return undefined;
+    if (optionValue === 'auto') {
+        return findNewestPreflightSummary(projectRoot) ?? undefined;
+    }
+    const abs = nodePath.isAbsolute(optionValue) ? optionValue : nodePath.resolve(projectRoot, optionValue);
+    if (!existsSync(abs))
+        return abs;
+    let stat;
+    try {
+        stat = statSync(abs);
+    }
+    catch {
+        return abs;
+    }
+    if (stat.isDirectory()) {
+        // Find newest preflight*.json inside.
+        let best = null;
+        let entries = [];
+        try {
+            entries = readdirSync(abs);
+        }
+        catch {
+            return abs;
+        }
+        for (const e of entries) {
+            if (!e.endsWith('.json'))
+                continue;
+            const full = nodePath.join(abs, e);
+            try {
+                const s = statSync(full);
+                if (!s.isFile())
+                    continue;
+                if (!best || s.mtimeMs > best.mtime)
+                    best = { file: full, mtime: s.mtimeMs };
+            }
+            catch {
+                continue;
+            }
+        }
+        return best ? best.file : abs;
+    }
+    return abs;
+}
+function severityFor(status, strict) {
+    if (status === 'fail')
+        return ReleaseReadinessSeverity.Error;
+    if (status === 'warn')
+        return strict ? ReleaseReadinessSeverity.Error : ReleaseReadinessSeverity.Warning;
+    if (status === 'skipped')
+        return ReleaseReadinessSeverity.Info;
+    return ReleaseReadinessSeverity.Info;
+}
+function pass(id, title, message) {
+    return { id, title, status: 'pass', severity: ReleaseReadinessSeverity.Info, message };
+}
+function warn(id, title, message, suggestion) {
+    return {
+        id,
+        title,
+        status: 'warn',
+        severity: ReleaseReadinessSeverity.Warning,
+        message,
+        ...(suggestion ? { suggestion } : {}),
+    };
+}
+function fail(id, title, message, suggestion) {
+    return {
+        id,
+        title,
+        status: 'fail',
+        severity: ReleaseReadinessSeverity.Error,
+        message,
+        ...(suggestion ? { suggestion } : {}),
+    };
+}
+function skip(id, title, message) {
+    return { id, title, status: 'skipped', severity: ReleaseReadinessSeverity.Info, message };
+}
+function checkReadmeRequiredSections(projectRoot) {
+    const file = nodePath.join(projectRoot, 'README.md');
+    if (!existsSync(file)) {
+        return fail('readme-present', 'README.md present', 'README.md is missing at the project root.');
+    }
+    let body = '';
+    try {
+        body = readFileSync(file, 'utf8').toLowerCase();
+    }
+    catch {
+        return warn('readme-readable', 'README.md readable', 'README.md exists but could not be read.');
+    }
+    const required = ['quick demo', 'onboard'];
+    const missing = required.filter((s) => !body.includes(s));
+    if (missing.length > 0) {
+        return warn('readme-required-sections', 'README required sections', `README.md is missing section keywords: ${missing.join(', ')}`, 'Add a "Quick demo" and "Onboard" section so adopters land on something runnable.');
+    }
+    return pass('readme-required-sections', 'README required sections', 'README.md has the expected sections.');
+}
+function checkPackageMetadata(projectRoot) {
+    const file = nodePath.join(projectRoot, 'package.json');
+    if (!existsSync(file)) {
+        return fail('package-json', 'package.json present', 'package.json missing at project root.');
+    }
+    try {
+        const pkg = JSON.parse(readFileSync(file, 'utf8'));
+        const missing = [];
+        if (!pkg.name)
+            missing.push('name');
+        if (!pkg.version)
+            missing.push('version');
+        if (!pkg.license)
+            missing.push('license');
+        if (!pkg.repository)
+            missing.push('repository');
+        if (missing.length > 0) {
+            return warn('package-metadata', 'package.json metadata', `Missing fields: ${missing.join(', ')}`, 'Fill in name/version/license/repository so the publish step has everything it needs.');
+        }
+        return pass('package-metadata', 'package.json metadata', `name=${pkg.name} version=${pkg.version} license=${pkg.license}`);
+    }
+    catch (e) {
+        return fail('package-metadata', 'package.json metadata', `Failed to parse package.json: ${e.message}`);
+    }
+}
+function checkExamplesPresent(projectRoot) {
+    const examplesDir = nodePath.join(projectRoot, 'examples');
+    if (!existsSync(examplesDir)) {
+        return warn('examples-dir', 'examples/ present', 'No examples/ directory found.');
+    }
+    return pass('examples-dir', 'examples/ present', 'examples/ exists.');
+}
+function checkPreflightSummary(file) {
+    if (!file) {
+        return skip('preflight-summary', 'release:preflight summary', 'Pass --preflight <file|auto> to fold in the latest release:preflight result.');
+    }
+    if (!existsSync(file)) {
+        return warn('preflight-summary', 'release:preflight summary', `release:preflight summary not found at ${file}.`, 'Run `bun run release:preflight` and pass the captured JSON via --preflight.');
+    }
+    let mtimeMs = 0;
+    try {
+        mtimeMs = statSync(file).mtimeMs;
+    }
+    catch {
+        mtimeMs = 0;
+    }
+    const ageDays = mtimeMs > 0 ? Math.floor((Date.now() - mtimeMs) / (1000 * 60 * 60 * 24)) : -1;
+    try {
+        const data = JSON.parse(readFileSync(file, 'utf8'));
+        if (data.passed === true) {
+            if (ageDays > PREFLIGHT_STALE_AFTER_DAYS) {
+                return warn('preflight-summary', 'release:preflight summary', `release:preflight passed, but the report is ${ageDays} day(s) old. Re-run before tagging.`, 'bun run release:preflight');
+            }
+            return pass('preflight-summary', 'release:preflight summary', `release:preflight passed (${ageDays >= 0 ? `${ageDays}d old` : 'age unknown'}).`);
+        }
+        const failed = (data.steps ?? []).filter((s) => !s.passed).map((s) => s.id);
+        return fail('preflight-summary', 'release:preflight summary', `release:preflight reports failures in: ${failed.join(', ') || 'unknown step'}`);
+    }
+    catch (e) {
+        return warn('preflight-summary', 'release:preflight summary', `Failed to parse preflight summary: ${e.message}`);
+    }
+}
+export async function buildReleaseReadiness(inspection, options = {}) {
+    const projectRoot = inspection.projectRoot;
+    const strict = options.strict === true;
+    const checks = [];
+    // 1. Doctor
+    const doctor = runDoctor(inspection);
+    if (doctor.summary.errors === 0) {
+        checks.push(pass('doctor', 'shrk doctor', `${doctor.summary.ok} OK, ${doctor.summary.warnings} warnings.`));
+    }
+    else {
+        checks.push(fail('doctor', 'shrk doctor', `${doctor.summary.errors} errors detected.`, 'Run `shrk doctor` and fix the listed errors.'));
+    }
+    // 2. Coverage
+    const coverage = buildCoverageReport(inspection);
+    if (coverage.overall < 50) {
+        checks.push(fail('coverage', 'Coverage', `Overall score ${coverage.overall}/100.`));
+    }
+    else if (coverage.overall < 80) {
+        checks.push(warn('coverage', 'Coverage', `Overall score ${coverage.overall}/100.`, 'Run `shrk coverage` and follow the recommendations to fill remaining gaps.'));
+    }
+    else {
+        checks.push(pass('coverage', 'Coverage', `Overall score ${coverage.overall}/100.`));
+    }
+    // 3. Safety audit — delegated to `shrk safety audit` (requires CLI catalog).
+    checks.push(pass('safety-audit', 'Safety audit', 'Delegated to `shrk safety audit` — the readiness gate trusts the standalone audit.'));
+    // 4. Pack doctor + release-check
+    try {
+        const packReport = buildPackDoctorReport(inspection, { requireSignatures: false });
+        const releaseChecks = await runPackReleaseChecksForReport(inspection);
+        mergePackReleaseChecks(inspection, packReport, releaseChecks, { strict });
+        if (packReport.summary.errors > 0) {
+            checks.push(fail('pack-doctor', 'Pack doctor (release-aware)', `${packReport.summary.errors} errors across ${packReport.packsChecked} pack(s).`, 'Run `shrk packs doctor --release --strict` to see suggested fixes.'));
+        }
+        else if (packReport.summary.warnings > 0) {
+            checks.push(warn('pack-doctor', 'Pack doctor (release-aware)', `${packReport.summary.warnings} warning(s) across ${packReport.packsChecked} pack(s).`));
+        }
+        else {
+            checks.push(pass('pack-doctor', 'Pack doctor (release-aware)', `${packReport.packsChecked} pack(s) clean.`));
+        }
+    }
+    catch (e) {
+        checks.push(skip('pack-doctor', 'Pack doctor (release-aware)', `Skipped: ${e.message}`));
+    }
+    // 5. Docs presence (canonical docs)
+    const docsDir = nodePath.join(projectRoot, 'docs');
+    const requiredDocs = ['overview.md', 'philosophy.md', 'safety-model.md', 'testing.md'];
+    const missingDocs = requiredDocs.filter((d) => !existsSync(nodePath.join(docsDir, d)));
+    if (missingDocs.length > 0) {
+        checks.push(warn('docs', 'Canonical docs', `Missing: ${missingDocs.join(', ')}`));
+    }
+    else {
+        checks.push(pass('docs', 'Canonical docs', `${requiredDocs.length} required doc(s) present.`));
+    }
+    // 6. README + package.json + examples
+    checks.push(checkReadmeRequiredSections(projectRoot));
+    checks.push(checkPackageMetadata(projectRoot));
+    checks.push(checkExamplesPresent(projectRoot));
+    // 6a. Pack signature release-readiness gate.
+    // FAIL CLOSED on any dev-signed pack when SHARKCRAFT_PACK_SECRET is unset.
+    // Dev signatures verify locally but are never release-trusted.
+    try {
+        checks.push(buildPackSignatureReleaseGate(inspection));
+    }
+    catch (e) {
+        checks.push(skip('pack-signature-release', 'Pack signatures (release-readiness)', `Skipped: ${e.message}`));
+    }
+    // 7. Optional preflight summary fold-in (auto-discover supported).
+    const preflightFile = resolvePreflightFile(projectRoot, options.preflightSummaryFile);
+    checks.push(checkPreflightSummary(preflightFile));
+    // 7a. release notes presence (strict mode treats missing as blocker).
+    const versionFile = (() => {
+        try {
+            const pkg = JSON.parse(readFileSync(nodePath.join(projectRoot, 'package.json'), 'utf8'));
+            return pkg.version ?? null;
+        }
+        catch {
+            return null;
+        }
+    })();
+    const releaseNotesDir = nodePath.join(projectRoot, 'docs', 'releases');
+    const releaseNotesFile = versionFile ? nodePath.join(releaseNotesDir, `${versionFile}.md`) : null;
+    const releaseNotesAlpha = nodePath.join(releaseNotesDir, '0.1.0-alpha.2.md');
+    const limitsFile = nodePath.join(projectRoot, 'docs', 'public-alpha-limitations.md');
+    const externalQuickstart = nodePath.join(projectRoot, 'docs', 'external-repo-quickstart.md');
+    const releaseNotesExists = (releaseNotesFile && existsSync(releaseNotesFile)) || existsSync(releaseNotesAlpha);
+    if (!releaseNotesExists) {
+        checks.push(warn('release-notes', 'Public alpha release notes', `Missing docs/releases/${versionFile ?? '<version>'}.md or docs/releases/0.1.0-alpha.2.md`, 'Add release notes — strict release readiness treats this as a blocker.'));
+    }
+    else {
+        checks.push(pass('release-notes', 'Public alpha release notes', 'Release notes file present.'));
+    }
+    if (!existsSync(limitsFile)) {
+        checks.push(warn('public-alpha-limitations', 'Public alpha limitations doc', 'Missing docs/public-alpha-limitations.md', 'List the known limitations adopters should be aware of.'));
+    }
+    else {
+        checks.push(pass('public-alpha-limitations', 'Public alpha limitations doc', 'Limitations doc present.'));
+    }
+    if (!existsSync(externalQuickstart)) {
+        checks.push(warn('external-quickstart', 'External repo quickstart', 'Missing docs/external-repo-quickstart.md', 'Add a 5-minute external-adopter quickstart.'));
+    }
+    else {
+        checks.push(pass('external-quickstart', 'External repo quickstart', 'Quickstart doc present.'));
+    }
+    const changelogFile = nodePath.join(projectRoot, 'CHANGELOG.md');
+    if (!existsSync(changelogFile)) {
+        checks.push(warn('changelog', 'CHANGELOG.md', 'CHANGELOG.md missing at project root.'));
+    }
+    else {
+        checks.push(pass('changelog', 'CHANGELOG.md', 'CHANGELOG.md present.'));
+    }
+    // 7b. optional docs check + examples check fold-in.
+    if (options.includeDocsCheck) {
+        const docs = buildDocsCheck(projectRoot);
+        if (!docs.ok) {
+            const errs = docs.findings.filter((f) => f.severity === 'error');
+            checks.push(fail('docs-check', 'Docs check', `${errs.length} blocking finding(s); run \`shrk docs check\` for details.`, 'shrk docs check'));
+        }
+        else if (docs.findings.some((f) => f.severity === 'warning')) {
+            checks.push(warn('docs-check', 'Docs check', 'Docs check reports warnings.', 'shrk docs check'));
+        }
+        else {
+            checks.push(pass('docs-check', 'Docs check', 'README + canonical docs look fine.'));
+        }
+    }
+    if (options.includeExamplesCheck) {
+        const ex = buildExamplesCheck(projectRoot);
+        if (!ex.ok) {
+            checks.push(fail('examples-check', 'Examples check', `Examples check found ${ex.findings.filter((f) => f.severity === 'error').length} error(s).`, 'shrk examples check'));
+        }
+        else if (ex.findings.some((f) => f.severity === 'warning')) {
+            checks.push(warn('examples-check', 'Examples check', 'Examples check reports warnings.', 'shrk examples check'));
+        }
+        else {
+            checks.push(pass('examples-check', 'Examples check', `${ex.examples.length} example(s) look fine.`));
+        }
+    }
+    // 8. MCP no-write audit — assert by static knowledge: tools index has no write tools.
+    // We can't run the MCP server here, but every tool we register goes through the
+    // ALL_TOOLS array; a separate test asserts the audit list matches runtime.
+    checks.push(pass('mcp-no-write', 'MCP read-only contract', 'No write tools registered (see packages/mcp-server/src/tools/index.ts).'));
+    // Apply strict severity escalation.
+    for (const c of checks)
+        c.severity = severityFor(c.status, strict);
+    const blockers = checks.filter((c) => c.severity === ReleaseReadinessSeverity.Error);
+    const warnings = checks.filter((c) => c.severity === ReleaseReadinessSeverity.Warning);
+    const passed = checks.filter((c) => c.status === 'pass');
+    const skipped = checks.filter((c) => c.status === 'skipped');
+    const ready = blockers.length === 0;
+    const checklist = [
+        'shrk doctor → green',
+        'shrk commands doctor → 0 errors / 0 warnings',
+        'shrk safety audit → no error findings',
+        'shrk coverage → green',
+        'shrk packs doctor --release --strict → green',
+        'bun x tsc -p tsconfig.base.json --noEmit → clean',
+        'bun test → all green',
+        'bun run release:preflight → all required steps passed',
+        'README.md has Quick demo + Onboard sections',
+        'package.json has name/version/license/repository',
+    ];
+    return {
+        schema: RELEASE_READINESS_SCHEMA,
+        generatedAt: new Date().toISOString(),
+        projectRoot,
+        ready,
+        strict,
+        blockers,
+        warnings,
+        passed,
+        skipped,
+        checklist,
+    };
+}
+/** Render a release readiness report as JS-free HTML. */
+export function renderReleaseReadinessHtml(report) {
+    const verdict = report.ready ? 'READY ✓' : 'NOT READY ✕';
+    const sev = (s) => s.toUpperCase();
+    function esc(s) {
+        return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+    }
+    function block(title, items) {
+        if (items.length === 0)
+            return '';
+        const rows = items
+            .map((c) => `<tr><td>${esc(c.id)}</td><td>${esc(c.title)}</td><td>${esc(sev(c.status))}</td><td>${esc(c.message)}</td><td>${esc(c.suggestion ?? '')}</td></tr>`)
+            .join('\n');
+        return `<h2>${esc(title)} (${items.length})</h2>
+<table><thead><tr><th>id</th><th>title</th><th>status</th><th>message</th><th>suggestion</th></tr></thead>
+<tbody>${rows}</tbody></table>`;
+    }
+    const checklist = report.checklist.map((s) => `<li>${esc(s)}</li>`).join('');
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Release readiness — ${esc(verdict)}</title>
+<style>
+body{font:14px/1.5 -apple-system,system-ui,sans-serif;max-width:920px;margin:24px auto;padding:0 16px;color:#1a1a1a;background:#fff}
+h1{font-size:24px}h2{font-size:18px;margin-top:24px;border-bottom:1px solid #e1e4e8;padding-bottom:4px}
+.muted{color:#586069}
+.verdict{display:inline-block;padding:4px 12px;border-radius:6px;font-weight:600}
+.ready{background:#e6f4ea;color:#1a7f37}
+.notready{background:#ffeef0;color:#b31d28}
+table{border-collapse:collapse;width:100%}
+th,td{padding:6px 10px;border:1px solid #d0d7de;text-align:left}
+th{background:#f6f8fa}
+@media (prefers-color-scheme: dark){body{background:#0d1117;color:#c9d1d9}th{background:#161b22}.muted{color:#8b949e}.ready{background:#0f5132;color:#a7f3d0}.notready{background:#3f1620;color:#fda4af}}
+</style></head><body>
+<h1>Release readiness <span class="verdict ${report.ready ? 'ready' : 'notready'}">${esc(verdict)}</span></h1>
+<p class="muted">${esc(report.projectRoot)} · generated ${esc(report.generatedAt)} · strict=${report.strict}</p>
+${block('Blockers', report.blockers)}
+${block('Warnings', report.warnings)}
+${block('Passed', report.passed)}
+${block('Skipped', report.skipped)}
+<h2>Checklist</h2><ol>${checklist}</ol>
+</body></html>
+`;
+}
+/**
+ * Extract the pack-signature release gate so it can be unit-tested
+ * without invoking the full release-readiness pipeline (which runs doctor +
+ * coverage and needs a full inspection shape).
+ */
+export function buildPackSignatureReleaseGate(inspection) {
+    const sigReport = buildPackSignatureStatusReport(inspection);
+    const devPacks = sigReport.packs.filter((p) => p.dev === true);
+    const secretAvailable = sigReport.secretAvailable;
+    if (devPacks.length === 0) {
+        return pass('pack-signature-release', 'Pack signatures (release-readiness)', `No dev-signed packs (release secret ${secretAvailable ? 'available' : 'not set'}).`);
+    }
+    if (secretAvailable) {
+        return warn('pack-signature-release', 'Pack signatures (release-readiness)', `${devPacks.length} dev-signed pack(s): ${devPacks.map((p) => p.packageName).join(', ')}. Release secret is available — re-sign before tagging.`, `Run \`shrk packs sign <pack>\` (no --dev) for each pack to produce a release signature.`);
+    }
+    return fail('pack-signature-release', 'Pack signatures (release-readiness)', `${devPacks.length} dev-signed pack(s) and SHARKCRAFT_PACK_SECRET is not set. Release would publish dev signatures.`, `Set SHARKCRAFT_PACK_SECRET in env, then run \`shrk packs sign <pack>\` (no --dev) for: ${devPacks.map((p) => p.packageName).join(', ')}.`);
+}

package/dist/release-smoke.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Release smoke harness.
+ *
+ * Runs a safe, local, deterministic smoke suite against SharkCraft's own
+ * surfaces. The harness does NOT execute external commands itself — it
+ * declares the scenarios in a structured form so the CLI can run them
+ * with the inherited environment, and validates expected artifacts.
+ *
+ * This module is the planner. The CLI command wires it to actual `bun`
+ * subprocess invocations under a temp fixture root.
+ *
+ * Constraints (must hold):
+ *  - never publishes
+ *  - never calls the network
+ *  - never calls external APIs
+ *  - never runs `rm -rf`, `dd`, `mkfs`
+ *  - writes only under the per-scenario temp dir (or the user-specified --temp-dir)
+ */
+export declare const RELEASE_SMOKE_SCHEMA = "sharkcraft.release-smoke/v1";
+export type SmokeScenarioId = 'unconfigured-repo' | 'dev-workflow' | 'pr-review' | 'governance' | 'pack-authoring';
+export type SmokeAssertionType = 'stdout-contains' | 'stderr-not-contains' | 'json-path-exists' | 'file-exists' | 'file-contains' | 'output-not-empty';
+export interface ISmokeAssertion {
+    type: SmokeAssertionType;
+    /** Pattern (stdout/stderr/file-contains) or path-relative-to-fixture (file-exists). */
+    value?: string;
+    /** Dotted path for json-path-exists (e.g. `summary.totalChanges`). */
+    jsonPath?: string;
+    /** When true, capture step stdout, parse as JSON, then walk jsonPath. */
+    fromStdoutJson?: boolean;
+    /** Relative path within fixture root (file-exists / file-contains). */
+    file?: string;
+    /** When true, failure marks the step as failed. Default true. */
+    required?: boolean;
+    /** Human note shown in the report. */
+    note?: string;
+}
+export interface ISmokeStep {
+    /** Short human-readable label for the step. */
+    title: string;
+    /** Command tokens (NOT a shell string). Used to spawn directly. */
+    command: readonly string[];
+    /** Allowed exit codes (defaults to [0]). */
+    allowedExitCodes?: readonly number[];
+    /** Files/directories that must exist after the step (relative to fixtureRoot). */
+    expectArtifacts?: readonly string[];
+    /** Files/directories that must NOT exist after the step (safety guard). */
+    forbidArtifacts?: readonly string[];
+    /** Content assertions evaluated after the step finishes. */
+    assertions?: readonly ISmokeAssertion[];
+    /** Note for reviewers — shown verbatim. */
+    notes?: string;
+}
+export interface ISmokeAssertionResult {
+    assertion: ISmokeAssertion;
+    status: 'pass' | 'fail' | 'skipped';
+    detail?: string;
+}
+export interface ISmokeScenario {
+    id: SmokeScenarioId;
+    title: string;
+    description: string;
+    /** Setup steps that prepare the fixture before the scenario runs. */
+    setup: readonly ISmokeStep[];
+    /** Main steps. */
+    steps: readonly ISmokeStep[];
+    /** Expected artifact directories at the end of the run. */
+    expectArtifacts: readonly string[];
+}
+export interface ISmokeStepResult {
+    step: ISmokeStep;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    exitCode: number | null;
+    status: 'pass' | 'fail' | 'skipped';
+    stdoutTail: string;
+    stderrTail: string;
+    artifactsFound: readonly string[];
+    artifactsMissing: readonly string[];
+    forbiddenArtifactsFound: readonly string[];
+    /** Per-assertion results. */
+    assertionResults?: readonly ISmokeAssertionResult[];
+}
+export interface ISmokeScenarioResult {
+    scenarioId: SmokeScenarioId;
+    fixtureRoot: string;
+    startedAt: string;
+    finishedAt: string;
+    durationMs: number;
+    status: 'pass' | 'fail';
+    steps: readonly ISmokeStepResult[];
+}
+export interface IReleaseSmokeReport {
+    schema: typeof RELEASE_SMOKE_SCHEMA;
+    generatedAt: string;
+    scenarios: readonly ISmokeScenarioResult[];
+    totalDurationMs: number;
+    passed: boolean;
+}
+export declare function listSmokeScenarios(): SmokeScenarioId[];
+export declare function getSmokeScenario(id: SmokeScenarioId): ISmokeScenario;
+export declare function pickScenarios(scope: SmokeScenarioId | 'all'): ISmokeScenario[];
+export interface IFixtureCreateInput {
+    scenarioId: SmokeScenarioId;
+    baseDir?: string;
+    /** When true, do not delete fixtures after the scenario runs. */
+    keep?: boolean;
+}
+export interface IFixtureCreateResult {
+    fixtureRoot: string;
+    keep: boolean;
+}
+export declare function createFixtureRoot(input: IFixtureCreateInput): IFixtureCreateResult;
+/** Recursively collect file paths inside a fixture (deterministic order). */
+export declare function collectFixtureFiles(root: string): string[];
+export declare function assertSafeWrites(files: readonly string[]): string[];
+/** Render the smoke report as plain text. */
+export declare function renderSmokeReportText(report: IReleaseSmokeReport): string;
+export declare function renderSmokeReportMarkdown(report: IReleaseSmokeReport): string;
+export declare function renderSmokeReportHtml(report: IReleaseSmokeReport): string;
+export declare function renderSmokeReport(report: IReleaseSmokeReport, format: 'text' | 'markdown' | 'html' | 'json'): string;
+/** Used by the CLI to confirm the fixture dir was prepared cleanly. */
+export declare function fixtureSummary(root: string): {
+    exists: boolean;
+    fileCount: number;
+    files: readonly string[];
+};
+export interface IEvaluateAssertionInput {
+    assertion: ISmokeAssertion;
+    stdout: string;
+    stderr: string;
+    fixtureRoot: string;
+}
+/**
+ * Evaluate a single assertion. Pure — uses fs only for `file-*` types.
+ */
+export declare function evaluateSmokeAssertion(input: IEvaluateAssertionInput): ISmokeAssertionResult;
+//# sourceMappingURL=release-smoke.d.ts.map

package/dist/release-smoke.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release-smoke.d.ts","sourceRoot":"","sources":["../src/release-smoke.ts"],"names":[],"mappings":"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"}