@shrkcrft/inspector 0.1.0-alpha.2

package/dist/release-smoke.js

@@ -0,0 +1,459 @@
+/**
+ * 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)
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import * as nodePath from 'node:path';
+export const RELEASE_SMOKE_SCHEMA = 'sharkcraft.release-smoke/v1';
+const SCENARIOS = {
+    'unconfigured-repo': {
+        id: 'unconfigured-repo',
+        title: 'Unconfigured repo onboarding',
+        description: 'Create a minimal Bun/TS repo and onboard SharkCraft.',
+        setup: [
+            {
+                title: 'Initialise fixture package.json',
+                command: ['__fixture__:init-unconfigured'],
+                notes: 'Inline fixture step (no external command).',
+            },
+        ],
+        steps: [
+            {
+                title: 'Onboard dry-run',
+                command: ['shrk', 'onboard', '--dry-run'],
+                assertions: [
+                    { type: 'stdout-contains', value: 'onboard', required: false, note: 'onboard ran' },
+                    { type: 'output-not-empty', required: true },
+                ],
+            },
+            {
+                title: 'Doctor',
+                command: ['shrk', 'doctor'],
+                // doctor exits non-zero in an unconfigured repo by design; both 0 and 1 are OK here.
+                allowedExitCodes: [0, 1],
+                assertions: [
+                    { type: 'stdout-contains', value: 'doctor', required: false },
+                    { type: 'output-not-empty', required: true },
+                ],
+            },
+        ],
+        expectArtifacts: ['package.json'],
+    },
+    'dev-workflow': {
+        id: 'dev-workflow',
+        title: 'Dev workflow',
+        description: 'Start a dev session against the dogfood fixture and produce a report.',
+        setup: [
+            {
+                title: 'Initialise fixture from dogfood-target',
+                command: ['__fixture__:copy-dogfood'],
+            },
+        ],
+        steps: [
+            {
+                title: 'Brief',
+                command: ['shrk', 'brief', 'smoke-test-task'],
+                assertions: [
+                    { type: 'output-not-empty', required: true },
+                    { type: 'stdout-contains', value: 'smoke-test-task', required: false },
+                ],
+            },
+            {
+                title: 'Doctor',
+                command: ['shrk', 'doctor'],
+                assertions: [
+                    { type: 'stdout-contains', value: 'Verdict', required: false },
+                ],
+            },
+        ],
+        expectArtifacts: ['sharkcraft'],
+    },
+    'pr-review': {
+        id: 'pr-review',
+        title: 'PR review',
+        description: 'Render impact + review surfaces against the dogfood fixture.',
+        setup: [
+            {
+                title: 'Initialise fixture from dogfood-target',
+                command: ['__fixture__:copy-dogfood'],
+            },
+        ],
+        steps: [
+            {
+                title: 'Impact (JSON)',
+                command: ['shrk', 'impact', '--format', 'json'],
+                assertions: [
+                    { type: 'json-path-exists', jsonPath: 'schema', fromStdoutJson: true, required: false },
+                    { type: 'output-not-empty', required: true },
+                ],
+            },
+            {
+                title: 'Report site',
+                command: ['shrk', 'report', 'site', '--output', '.sharkcraft/reports/site'],
+                expectArtifacts: ['.sharkcraft/reports/site/index.html'],
+                assertions: [
+                    { type: 'file-exists', file: '.sharkcraft/reports/site/index.html', required: true },
+                ],
+            },
+        ],
+        expectArtifacts: ['.sharkcraft'],
+    },
+    governance: {
+        id: 'governance',
+        title: 'Governance',
+        description: 'Run quality, commands doctor, runtime doctor, safety audit, release readiness.',
+        setup: [
+            {
+                title: 'Initialise fixture from dogfood-target',
+                command: ['__fixture__:copy-dogfood'],
+            },
+        ],
+        steps: [
+            { title: 'Quality', command: ['shrk', 'quality'], assertions: [{ type: 'output-not-empty', required: true }] },
+            {
+                title: 'Commands doctor',
+                command: ['shrk', 'commands', 'doctor'],
+                assertions: [
+                    { type: 'stdout-contains', value: 'errors:', required: false, note: 'doctor mentions error count' },
+                ],
+            },
+            { title: 'Safety audit', command: ['shrk', 'safety', 'audit'], assertions: [{ type: 'output-not-empty', required: false }] },
+            {
+                title: 'Release readiness',
+                command: ['shrk', 'release', 'readiness'],
+                assertions: [
+                    { type: 'stdout-contains', value: 'Verdict', required: false },
+                ],
+            },
+        ],
+        expectArtifacts: [],
+    },
+    'pack-authoring': {
+        id: 'pack-authoring',
+        title: 'Pack authoring',
+        description: 'Scaffold a demo pack and run release-check + compat against it.',
+        setup: [
+            {
+                title: 'Initialise empty fixture',
+                command: ['__fixture__:init-empty-pack-root'],
+            },
+        ],
+        steps: [
+            {
+                title: 'Pack release check (smoke)',
+                command: ['shrk', 'packs', 'doctor', '--release'],
+                allowedExitCodes: [0, 1],
+                assertions: [
+                    { type: 'stdout-contains', value: 'Pack', required: false },
+                ],
+            },
+        ],
+        expectArtifacts: [],
+    },
+};
+export function listSmokeScenarios() {
+    return Object.keys(SCENARIOS);
+}
+export function getSmokeScenario(id) {
+    const s = SCENARIOS[id];
+    if (!s)
+        throw new Error(`Unknown smoke scenario: ${id}`);
+    return s;
+}
+export function pickScenarios(scope) {
+    if (scope === 'all')
+        return listSmokeScenarios().map((id) => SCENARIOS[id]);
+    return [getSmokeScenario(scope)];
+}
+export function createFixtureRoot(input) {
+    const base = input.baseDir ?? tmpdir();
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const root = nodePath.join(base, `sharkcraft-smoke-${input.scenarioId}-${ts}`);
+    mkdirSync(root, { recursive: true });
+    return { fixtureRoot: root, keep: input.keep ?? false };
+}
+/** Recursively collect file paths inside a fixture (deterministic order). */
+export function collectFixtureFiles(root) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = readdirSync(dir).sort();
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const full = nodePath.join(dir, entry);
+            let stat;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory())
+                walk(full);
+            else
+                out.push(nodePath.relative(root, full));
+        }
+    };
+    walk(root);
+    return out;
+}
+/** Source-write safety: assert no files were written outside allowed prefixes. */
+const ALLOWED_WRITE_PREFIXES = [
+    '.sharkcraft',
+    'sharkcraft',
+    'examples',
+    'package.json',
+    'README.md',
+    'tsconfig.json',
+    'bun.lock',
+    'bun.lockb',
+];
+export function assertSafeWrites(files) {
+    const violations = [];
+    for (const f of files) {
+        const allowed = ALLOWED_WRITE_PREFIXES.some((p) => f === p || f.startsWith(p + nodePath.sep) || f.startsWith(p + '/'));
+        if (!allowed)
+            violations.push(f);
+    }
+    return violations;
+}
+/** Render the smoke report as plain text. */
+export function renderSmokeReportText(report) {
+    const lines = [];
+    lines.push(`# Release smoke — ${report.passed ? 'PASS ✓' : 'FAIL ✕'}`);
+    lines.push(`Total: ${report.scenarios.length} scenario(s), ${report.totalDurationMs}ms`);
+    for (const s of report.scenarios) {
+        lines.push('');
+        lines.push(`## ${s.scenarioId}  [${s.status}]  (${s.durationMs}ms)`);
+        lines.push(`fixture: ${s.fixtureRoot}`);
+        for (const step of s.steps) {
+            lines.push(`  • ${step.step.title}  [${step.status}]  exit=${step.exitCode ?? '?'}  (${step.durationMs}ms)`);
+            if (step.artifactsMissing.length > 0) {
+                lines.push(`    missing artifacts: ${step.artifactsMissing.join(', ')}`);
+            }
+            if (step.forbiddenArtifactsFound.length > 0) {
+                lines.push(`    ⚠ forbidden artifacts present: ${step.forbiddenArtifactsFound.join(', ')}`);
+            }
+            if (step.assertionResults && step.assertionResults.length > 0) {
+                const passed = step.assertionResults.filter((a) => a.status === 'pass').length;
+                const failed = step.assertionResults.filter((a) => a.status === 'fail').length;
+                lines.push(`    assertions: ${passed}/${step.assertionResults.length} passed${failed > 0 ? ` (${failed} failed)` : ''}`);
+                for (const a of step.assertionResults) {
+                    if (a.status === 'fail') {
+                        lines.push(`      ✗ ${a.assertion.type}: ${a.detail ?? ''}`);
+                    }
+                }
+            }
+            if (step.status === 'fail') {
+                const tail = (step.stderrTail || step.stdoutTail).split(/\r?\n/).slice(-6).join('\n      ');
+                if (tail)
+                    lines.push(`    last output:\n      ${tail}`);
+            }
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+export function renderSmokeReportMarkdown(report) {
+    const lines = [];
+    lines.push(`# Release smoke — ${report.passed ? 'PASS' : 'FAIL'}`);
+    lines.push('');
+    lines.push(`Generated: ${report.generatedAt}`);
+    lines.push(`Scenarios: ${report.scenarios.length}  ·  Duration: ${report.totalDurationMs}ms`);
+    lines.push('');
+    for (const s of report.scenarios) {
+        lines.push(`## \`${s.scenarioId}\` — ${s.status.toUpperCase()}`);
+        lines.push('');
+        lines.push(`Fixture: \`${s.fixtureRoot}\``);
+        lines.push('');
+        lines.push('| Step | Status | Exit | Duration | Notes |');
+        lines.push('|------|--------|------|----------|-------|');
+        for (const step of s.steps) {
+            const notes = [];
+            if (step.artifactsMissing.length > 0)
+                notes.push(`missing: ${step.artifactsMissing.join(', ')}`);
+            if (step.forbiddenArtifactsFound.length > 0)
+                notes.push(`⚠ ${step.forbiddenArtifactsFound.join(', ')}`);
+            lines.push(`| ${step.step.title} | ${step.status} | ${step.exitCode ?? '?'} | ${step.durationMs}ms | ${notes.join('; ') || ''} |`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n') + '\n';
+}
+function escHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function renderSmokeReportHtml(report) {
+    const out = [];
+    out.push(`<!doctype html><html><head><meta charset="utf-8"><title>Release smoke — ${report.passed ? 'PASS' : 'FAIL'}</title>`);
+    out.push('<style>body{font:14px/1.5 -apple-system,system-ui,sans-serif;max-width:920px;margin:24px auto;padding:0 16px}h1{font-size:22px}h2{font-size:16px;margin-top:24px;border-bottom:1px solid #e1e4e8;padding-bottom:4px}table{border-collapse:collapse;width:100%}th,td{border:1px solid #d0d7de;padding:6px 10px;text-align:left}.pass{color:#1a7f37}.fail{color:#b31d28}.muted{color:#586069}@media (prefers-color-scheme: dark){body{background:#0d1117;color:#c9d1d9}th{background:#161b22}.muted{color:#8b949e}}</style></head><body>');
+    out.push(`<h1>Release smoke <span class="${report.passed ? 'pass' : 'fail'}">${report.passed ? 'PASS' : 'FAIL'}</span></h1>`);
+    out.push(`<p class="muted">${escHtml(report.generatedAt)} · scenarios ${report.scenarios.length} · ${report.totalDurationMs}ms</p>`);
+    for (const s of report.scenarios) {
+        out.push(`<h2>${escHtml(s.scenarioId)} — <span class="${s.status === 'pass' ? 'pass' : 'fail'}">${escHtml(s.status)}</span></h2>`);
+        out.push(`<p class="muted">${escHtml(s.fixtureRoot)} · ${s.durationMs}ms</p>`);
+        out.push('<table><thead><tr><th>Step</th><th>Status</th><th>Exit</th><th>Duration</th><th>Notes</th></tr></thead><tbody>');
+        for (const step of s.steps) {
+            const notes = [];
+            if (step.artifactsMissing.length > 0)
+                notes.push(`missing: ${step.artifactsMissing.join(', ')}`);
+            if (step.forbiddenArtifactsFound.length > 0)
+                notes.push(`⚠ ${step.forbiddenArtifactsFound.join(', ')}`);
+            out.push(`<tr><td>${escHtml(step.step.title)}</td><td class="${step.status === 'pass' ? 'pass' : 'fail'}">${escHtml(step.status)}</td><td>${step.exitCode ?? '?'}</td><td>${step.durationMs}ms</td><td>${escHtml(notes.join('; '))}</td></tr>`);
+        }
+        out.push('</tbody></table>');
+    }
+    out.push('</body></html>');
+    return out.join('\n') + '\n';
+}
+export function renderSmokeReport(report, format) {
+    if (format === 'json')
+        return JSON.stringify(report, null, 2) + '\n';
+    if (format === 'markdown')
+        return renderSmokeReportMarkdown(report);
+    if (format === 'html')
+        return renderSmokeReportHtml(report);
+    return renderSmokeReportText(report);
+}
+/** Used by the CLI to confirm the fixture dir was prepared cleanly. */
+export function fixtureSummary(root) {
+    if (!existsSync(root))
+        return { exists: false, fileCount: 0, files: [] };
+    const files = collectFixtureFiles(root);
+    return { exists: true, fileCount: files.length, files };
+}
+/**
+ * Walk a dotted JSON path and report whether the leaf exists.
+ * `a.b.c` walks into nested objects; numeric segments index arrays.
+ */
+function hasJsonPath(value, path) {
+    if (!path)
+        return value !== undefined;
+    const parts = path.split('.');
+    let cursor = value;
+    for (const part of parts) {
+        if (cursor === null || cursor === undefined)
+            return false;
+        if (typeof cursor !== 'object')
+            return false;
+        const idx = Number(part);
+        if (Number.isInteger(idx) && Array.isArray(cursor)) {
+            cursor = cursor[idx];
+        }
+        else {
+            cursor = cursor[part];
+        }
+    }
+    return cursor !== undefined;
+}
+/**
+ * Evaluate a single assertion. Pure — uses fs only for `file-*` types.
+ */
+export function evaluateSmokeAssertion(input) {
+    const a = input.assertion;
+    const required = a.required ?? true;
+    const pass = (detail) => ({
+        assertion: a,
+        status: 'pass',
+        ...(detail ? { detail } : {}),
+    });
+    const fail = (detail) => ({
+        assertion: a,
+        status: required ? 'fail' : 'skipped',
+        detail,
+    });
+    switch (a.type) {
+        case 'stdout-contains': {
+            if (!a.value)
+                return fail('stdout-contains requires `value`');
+            return input.stdout.includes(a.value)
+                ? pass()
+                : fail(`stdout did not contain "${a.value.slice(0, 80)}"`);
+        }
+        case 'stderr-not-contains': {
+            if (!a.value)
+                return pass();
+            return input.stderr.includes(a.value)
+                ? fail(`stderr contained "${a.value.slice(0, 80)}"`)
+                : pass();
+        }
+        case 'output-not-empty': {
+            const combined = (input.stdout + input.stderr).trim();
+            return combined.length > 0 ? pass() : fail('combined output was empty');
+        }
+        case 'file-exists': {
+            if (!a.file)
+                return fail('file-exists requires `file`');
+            const full = nodePath.join(input.fixtureRoot, a.file);
+            return existsSync(full) ? pass(full) : fail(`missing file: ${a.file}`);
+        }
+        case 'file-contains': {
+            if (!a.file || !a.value)
+                return fail('file-contains requires `file` and `value`');
+            const full = nodePath.join(input.fixtureRoot, a.file);
+            if (!existsSync(full))
+                return fail(`missing file: ${a.file}`);
+            try {
+                const body = readFileSync(full, 'utf8');
+                return body.includes(a.value) ? pass() : fail(`file did not contain "${a.value.slice(0, 60)}"`);
+            }
+            catch (e) {
+                return fail(`could not read ${a.file}: ${e.message}`);
+            }
+        }
+        case 'json-path-exists': {
+            if (!a.jsonPath)
+                return fail('json-path-exists requires `jsonPath`');
+            if (a.fromStdoutJson) {
+                try {
+                    // Some CLI commands prepend a banner (`$ ...`) before the JSON body.
+                    const candidate = input.stdout.trim();
+                    const start = candidate.indexOf('{');
+                    if (start < 0)
+                        return fail('stdout did not contain a JSON object');
+                    const parsed = JSON.parse(candidate.slice(start));
+                    return hasJsonPath(parsed, a.jsonPath)
+                        ? pass()
+                        : fail(`stdout JSON did not have path "${a.jsonPath}"`);
+                }
+                catch (e) {
+                    return fail(`stdout was not JSON: ${e.message}`);
+                }
+            }
+            if (!a.file)
+                return fail('json-path-exists requires `file` or `fromStdoutJson`');
+            const full = nodePath.join(input.fixtureRoot, a.file);
+            if (!existsSync(full))
+                return fail(`missing file: ${a.file}`);
+            try {
+                const parsed = JSON.parse(readFileSync(full, 'utf8'));
+                return hasJsonPath(parsed, a.jsonPath)
+                    ? pass()
+                    : fail(`file JSON did not have path "${a.jsonPath}"`);
+            }
+            catch (e) {
+                return fail(`could not parse ${a.file}: ${e.message}`);
+            }
+        }
+        default:
+            return fail(`unknown assertion type ${a.type}`);
+    }
+}

package/dist/release-train.d.ts

@@ -0,0 +1,33 @@
+export declare const RELEASE_TRAIN_SCHEMA = "sharkcraft.release-train/v1";
+export declare enum ReleaseTrainStatus {
+    Planning = "planning",
+    InProgress = "in-progress",
+    ReadyToTag = "ready-to-tag",
+    Released = "released",
+    Cancelled = "cancelled"
+}
+export interface IReleaseTrain {
+    schema: typeof RELEASE_TRAIN_SCHEMA;
+    id: string;
+    version: string;
+    targetDate: string;
+    goals: readonly string[];
+    includedBundles: readonly string[];
+    requiredChecks: readonly string[];
+    status: ReleaseTrainStatus;
+}
+export declare function releaseTrainDir(projectRoot: string): string;
+export declare function listReleaseTrains(projectRoot: string): readonly IReleaseTrain[];
+export declare function getReleaseTrain(projectRoot: string, id: string): IReleaseTrain | undefined;
+export declare function buildReleaseTrainDraft(version: string, opts?: {
+    goals?: readonly string[];
+}): IReleaseTrain;
+export declare function writeReleaseTrainDraft(projectRoot: string, train: IReleaseTrain): string;
+export interface IReleaseTrainReadiness {
+    trainId: string;
+    ready: boolean;
+    missingBundles: readonly string[];
+    pendingChecks: readonly string[];
+}
+export declare function computeReleaseTrainReadiness(projectRoot: string, train: IReleaseTrain): IReleaseTrainReadiness;
+//# sourceMappingURL=release-train.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"release-train.d.ts","sourceRoot":"","sources":["../src/release-train.ts"],"names":[],"mappings":"AAaA,eAAO,MAAM,oBAAoB,gCAAgC,CAAC;AAElE,oBAAY,kBAAkB;IAC5B,QAAQ,aAAa;IACrB,UAAU,gBAAgB;IAC1B,UAAU,iBAAiB;IAC3B,QAAQ,aAAa;IACrB,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,OAAO,oBAAoB,CAAC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AASD,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,aAAa,EAAE,CA8B/E;AAED,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAE1F;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GAAG,aAAa,CAY/G;AAED,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,aAAa,GAAG,MAAM,CAMxF;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,aAAa,GACnB,sBAAsB,CAaxB"}

package/dist/release-train.js

@@ -0,0 +1,104 @@
+/**
+ * Local release train model.
+ *
+ * A release train groups bundles + checks under a target version. Teams
+ * use it to plan grouped releases without ever auto-publishing or
+ * tagging.
+ *
+ * Source: `sharkcraft/release-trains/<version>.json`. Read-only at the
+ * inspector layer; the CLI handles dry-run writes.
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import * as nodePath from 'node:path';
+export const RELEASE_TRAIN_SCHEMA = 'sharkcraft.release-train/v1';
+export var ReleaseTrainStatus;
+(function (ReleaseTrainStatus) {
+    ReleaseTrainStatus["Planning"] = "planning";
+    ReleaseTrainStatus["InProgress"] = "in-progress";
+    ReleaseTrainStatus["ReadyToTag"] = "ready-to-tag";
+    ReleaseTrainStatus["Released"] = "released";
+    ReleaseTrainStatus["Cancelled"] = "cancelled";
+})(ReleaseTrainStatus || (ReleaseTrainStatus = {}));
+const DEFAULT_REQUIRED_CHECKS = [
+    'typecheck',
+    'tests',
+    'shrk release readiness --strict',
+    'shrk release smoke --scenario all',
+];
+export function releaseTrainDir(projectRoot) {
+    return nodePath.join(projectRoot, 'sharkcraft', 'release-trains');
+}
+export function listReleaseTrains(projectRoot) {
+    const dir = releaseTrainDir(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    let files = [];
+    try {
+        files = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(nodePath.join(dir, f), 'utf8'));
+            if (!parsed.id || !parsed.version)
+                continue;
+            out.push({
+                schema: RELEASE_TRAIN_SCHEMA,
+                id: parsed.id,
+                version: parsed.version,
+                targetDate: parsed.targetDate ?? '',
+                goals: parsed.goals ?? [],
+                includedBundles: parsed.includedBundles ?? [],
+                requiredChecks: parsed.requiredChecks ?? DEFAULT_REQUIRED_CHECKS,
+                status: parsed.status ?? ReleaseTrainStatus.Planning,
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return out;
+}
+export function getReleaseTrain(projectRoot, id) {
+    return listReleaseTrains(projectRoot).find((t) => t.id === id);
+}
+export function buildReleaseTrainDraft(version, opts = {}) {
+    const id = `train-${version.replace(/[^a-zA-Z0-9]+/g, '-')}`;
+    return {
+        schema: RELEASE_TRAIN_SCHEMA,
+        id,
+        version,
+        targetDate: '',
+        goals: opts.goals ?? [],
+        includedBundles: [],
+        requiredChecks: DEFAULT_REQUIRED_CHECKS,
+        status: ReleaseTrainStatus.Planning,
+    };
+}
+export function writeReleaseTrainDraft(projectRoot, train) {
+    const dir = releaseTrainDir(projectRoot);
+    mkdirSync(dir, { recursive: true });
+    const file = nodePath.join(dir, `${train.id}.json`);
+    writeFileSync(file, JSON.stringify(train, null, 2), 'utf8');
+    return file;
+}
+export function computeReleaseTrainReadiness(projectRoot, train) {
+    const missingBundles = [];
+    for (const b of train.includedBundles) {
+        const path = nodePath.join(projectRoot, '.sharkcraft', 'bundles', b);
+        if (!existsSync(path))
+            missingBundles.push(b);
+    }
+    // Pending checks are advisory only — the user runs them locally.
+    return {
+        trainId: train.id,
+        ready: missingBundles.length === 0,
+        missingBundles,
+        pendingChecks: train.requiredChecks,
+    };
+}