edsger 0.44.0 → 0.45.0

package/dist/api/run-sheets.d.ts

@@ -0,0 +1,22 @@
+export interface RunSheet {
+    id: string;
+    release_id: string;
+    title: string | null;
+    content: string;
+    template_snapshot: string | null;
+    metadata: Record<string, unknown>;
+    generated_at: string | null;
+    created_by: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface UpsertRunSheetParams {
+    release_id: string;
+    content: string;
+    title?: string | null;
+    template_snapshot?: string | null;
+    metadata?: Record<string, unknown>;
+    generated_at?: string;
+}
+export declare function getRunSheetByRelease(releaseId: string, verbose?: boolean): Promise<RunSheet | null>;
+export declare function upsertRunSheet(params: UpsertRunSheetParams, verbose?: boolean): Promise<RunSheet>;

package/dist/api/run-sheets.js

@@ -0,0 +1,13 @@
+import { logDebug } from '../utils/logger.js';
+import { callMcpEndpoint } from './mcp-client.js';
+export async function getRunSheetByRelease(releaseId, verbose) {
+    logDebug(`Fetching run sheet for release ${releaseId}`, verbose);
+    const result = (await callMcpEndpoint('run_sheets/get', {
+        release_id: releaseId,
+    }));
+    return result.run_sheet;
+}
+export async function upsertRunSheet(params, verbose) {
+    logDebug(`Upserting run sheet for release ${params.release_id}`, verbose);
+    return (await callMcpEndpoint('run_sheets/upsert', params));
+}

package/dist/commands/run-sheet/index.d.ts

@@ -0,0 +1,6 @@
+export interface RunSheetCliOptions {
+    releaseId: string;
+    force?: boolean;
+    verbose?: boolean;
+}
+export declare const runRunSheetCommand: (options: RunSheetCliOptions) => Promise<void>;

package/dist/commands/run-sheet/index.js

@@ -0,0 +1,48 @@
+import { runRunSheet, } from '../../phases/run-sheet/index.js';
+import { deregisterSession, registerSession, } from '../../system/session-manager.js';
+import { logError, logInfo } from '../../utils/logger.js';
+import { validateConfiguration } from '../../utils/validation.js';
+export const runRunSheetCommand = async (options) => {
+    const { releaseId } = options;
+    if (!releaseId) {
+        throw new Error('Release ID is required for run-sheet');
+    }
+    validateConfiguration({ verbose: options.verbose });
+    await registerSession({ command: 'run-sheet' });
+    logInfo(`Starting run sheet generation for release: ${releaseId}`);
+    try {
+        const result = await runRunSheet({
+            releaseId,
+            force: options.force,
+            verbose: options.verbose,
+        });
+        if (result.status === 'error') {
+            logError(`Run sheet generation failed: ${result.summary}`);
+            process.exitCode = 1;
+            return;
+        }
+        if (result.status === 'cached') {
+            logInfo(`Run sheet unchanged for ${result.releaseTag} — skipped clone.`);
+        }
+        else {
+            logInfo(`Generated run sheet for ${result.releaseTag}`);
+        }
+        if (result.cloneError) {
+            logInfo(`Clone warning: ${result.cloneError}`);
+        }
+        if (result.missingPlaceholders && result.missingPlaceholders.length > 0) {
+            logInfo(`Unresolved placeholders: ${result.missingPlaceholders.join(', ')}`);
+        }
+        if (result.commitsTruncated) {
+            logInfo('Commit list truncated at GitHub 250-commit cap.');
+        }
+        logInfo('View it in the Release detail page of your product dashboard.');
+    }
+    catch (error) {
+        logError(`Run sheet generation failed: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+    }
+    finally {
+        await deregisterSession();
+    }
+};

package/dist/index.js

@@ -20,6 +20,7 @@ import { runPRResolve } from './commands/pr-resolve/index.js';
 import { runPRReview } from './commands/pr-review/index.js';
 import { runRefactor } from './commands/refactor/refactor.js';
 import { runReleaseSyncCommand } from './commands/release-sync/index.js';
+import { runRunSheetCommand } from './commands/run-sheet/index.js';
 import { runSmokeTestCommand } from './commands/smoke-test/index.js';
 import { runTaskWorker } from './commands/task-worker/index.js';
 import { runWorkflow } from './commands/workflow/index.js';
@@ -314,6 +315,27 @@ program
     }
 });
 // ============================================================
+// Subcommand: edsger run-sheet <releaseId>
+// ============================================================
+program
+    .command('run-sheet <releaseId>')
+    .description('Render the product run sheet template against a release (clones the repo at the release tag to resolve {{file:...}} placeholders)')
+    .option('-f, --force', 'Regenerate even if the cached run sheet is fresh')
+    .option('-v, --verbose', 'Verbose output')
+    .action(async (releaseId, opts) => {
+    try {
+        await runRunSheetCommand({
+            releaseId,
+            force: opts.force,
+            verbose: opts.verbose,
+        });
+    }
+    catch (error) {
+        logError(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+});
+// ============================================================
 // Subcommand: edsger pr-review <productId>
 // ============================================================
 program

package/dist/phases/run-sheet/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Run-sheet generation for a release.
+ *
+ * Given a release, fetches the product's `run_sheet_template`, clones the
+ * repo at the release tag (reusing the workspace layout used by
+ * smoke-test), renders placeholders, and upserts the result to the
+ * `run_sheets` table.
+ *
+ * Release tags are immutable, so if an existing run sheet has the same
+ * template_snapshot + tag and no clone error, we short-circuit without
+ * re-cloning. Pass `{ force: true }` to regenerate anyway.
+ */
+export interface RunSheetOptions {
+    releaseId: string;
+    force?: boolean;
+    verbose?: boolean;
+}
+export interface RunSheetResult {
+    status: 'success' | 'error' | 'cached';
+    releaseId: string;
+    releaseTag?: string;
+    summary: string;
+    runSheetId?: string;
+    missingPlaceholders?: string[];
+    cloneError?: string | null;
+    commitsTruncated?: boolean;
+}
+/**
+ * Atomic-create a `.lock` file alongside the workspace dir. Returns
+ * true if we acquired the lock, false if another CLI instance holds a
+ * fresh one. Stale locks (> LOCK_STALE_MS old) are stolen via a single
+ * unlink + create pair; concurrent stealers race fairly via O_EXCL on
+ * the second create.
+ */
+/** Exported for unit tests; not part of the public CLI surface. */
+export declare function tryAcquireFileLock(lockPath: string): boolean;
+/** Exported for unit tests; not part of the public CLI surface. */
+export declare function releaseFileLock(lockPath: string): void;
+export declare function runRunSheet(options: RunSheetOptions): Promise<RunSheetResult>;

package/dist/phases/run-sheet/index.js

@@ -0,0 +1,297 @@
+/**
+ * Run-sheet generation for a release.
+ *
+ * Given a release, fetches the product's `run_sheet_template`, clones the
+ * repo at the release tag (reusing the workspace layout used by
+ * smoke-test), renders placeholders, and upserts the result to the
+ * `run_sheets` table.
+ *
+ * Release tags are immutable, so if an existing run sheet has the same
+ * template_snapshot + tag and no clone error, we short-circuit without
+ * re-cloning. Pass `{ force: true }` to regenerate anyway.
+ */
+import { closeSync, mkdirSync, openSync, readFileSync, unlinkSync, writeFileSync, } from 'fs';
+import { join } from 'path';
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getProduct } from '../../api/products.js';
+import { getRelease } from '../../api/releases.js';
+import { getRunSheetByRelease, upsertRunSheet, } from '../../api/run-sheets.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cloneFeatureRepo, ensureWorkspaceDir, getFeatureRepoPath, syncRepoToRef, } from '../../workspace/workspace-manager.js';
+import { fetchCompare } from '../release-sync/github.js';
+import { isSafeGitRef, renderTemplate } from './render.js';
+// GitHub's compare endpoint is paginated; we don't page, so we warn when
+// we hit the first-page cap.
+const GITHUB_COMPARE_MAX_COMMITS = 250;
+async function fetchCommitsBetween(owner, repo, base, head, token) {
+    if (!base) {
+        return { text: '', truncated: false };
+    }
+    try {
+        const compare = await fetchCompare(owner, repo, base, head, token);
+        const commits = compare.commits ?? [];
+        const text = commits
+            .map((c) => `- ${c.sha.slice(0, 7)} ${(c.commit.message || '').split('\n')[0]}`)
+            .join('\n');
+        return {
+            text,
+            truncated: commits.length >= GITHUB_COMPARE_MAX_COMMITS,
+        };
+    }
+    catch (err) {
+        logWarning(`Could not fetch commits for run sheet: ${err instanceof Error ? err.message : String(err)}`);
+        return { text: '', truncated: false };
+    }
+}
+// Stale locks (e.g. left behind by a crashed or SIGKILLed CLI) are
+// considered abandoned after this many ms.
+const LOCK_STALE_MS = 15 * 60 * 1000;
+function writeLockFile(fd) {
+    const payload = { pid: process.pid, ts: Date.now() };
+    writeFileSync(fd, JSON.stringify(payload));
+    closeSync(fd);
+}
+function tryCreateLock(lockPath) {
+    try {
+        const fd = openSync(lockPath, 'wx');
+        writeLockFile(fd);
+        return true;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            return false;
+        }
+        throw err;
+    }
+}
+function isLockStale(lockPath) {
+    try {
+        const raw = readFileSync(lockPath, 'utf-8').trim();
+        let ts;
+        try {
+            ts = JSON.parse(raw).ts;
+        }
+        catch {
+            ts = Number(raw);
+        }
+        return !Number.isFinite(ts) || Date.now() - ts > LOCK_STALE_MS;
+    }
+    catch {
+        // Lock vanished between exists-check and read — treat as not held.
+        return true;
+    }
+}
+/**
+ * Atomic-create a `.lock` file alongside the workspace dir. Returns
+ * true if we acquired the lock, false if another CLI instance holds a
+ * fresh one. Stale locks (> LOCK_STALE_MS old) are stolen via a single
+ * unlink + create pair; concurrent stealers race fairly via O_EXCL on
+ * the second create.
+ */
+/** Exported for unit tests; not part of the public CLI surface. */
+export function tryAcquireFileLock(lockPath) {
+    mkdirSync(join(lockPath, '..'), { recursive: true });
+    // Pass 1: clean acquisition.
+    if (tryCreateLock(lockPath)) {
+        return true;
+    }
+    // Pass 2: someone holds it — only steal if their lock is stale.
+    if (!isLockStale(lockPath)) {
+        return false;
+    }
+    // Try to steal. Best-effort unlink (another stealer may have beaten
+    // us); the O_EXCL create then arbitrates fairly.
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Already gone — fine, race the create below.
+    }
+    return tryCreateLock(lockPath);
+}
+/** Exported for unit tests; not part of the public CLI surface. */
+export function releaseFileLock(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch {
+        // Best-effort — lock will expire via LOCK_STALE_MS anyway.
+    }
+}
+function runSheetIsFresh(existing, template, tag) {
+    if (!existing || !existing.content) {
+        return false;
+    }
+    if (existing.template_snapshot !== template) {
+        return false;
+    }
+    const meta = existing.metadata ?? {};
+    if (meta.tag !== tag) {
+        return false;
+    }
+    if (meta.clone_error) {
+        return false;
+    }
+    return true;
+}
+export async function runRunSheet(options) {
+    const { releaseId, force, verbose } = options;
+    let release;
+    try {
+        release = await getRelease(releaseId, verbose);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            status: 'error',
+            releaseId,
+            summary: `Failed to load release: ${message}`,
+        };
+    }
+    if (!isSafeGitRef(release.tag)) {
+        return {
+            status: 'error',
+            releaseId,
+            releaseTag: release.tag,
+            summary: `Unsafe release tag: ${release.tag}`,
+        };
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mcp product shape is open
+    const product = (await getProduct(release.product_id, verbose));
+    const template = product?.run_sheet_template;
+    if (!template || !template.trim()) {
+        return {
+            status: 'error',
+            releaseId,
+            releaseTag: release.tag,
+            summary: 'Product has no run_sheet_template configured. Set one in product settings.',
+        };
+    }
+    // Short-circuit cache: identical template + tag, no prior clone error.
+    if (!force) {
+        const existing = await getRunSheetByRelease(releaseId, verbose).catch(() => null);
+        if (runSheetIsFresh(existing, template, release.tag)) {
+            logInfo(`Run sheet for ${release.tag} is already up-to-date (template unchanged).`);
+            return {
+                status: 'cached',
+                releaseId,
+                releaseTag: release.tag,
+                runSheetId: existing.id,
+                summary: 'Cached (no change since last render)',
+                missingPlaceholders: existing.metadata?.missing_placeholders ?? [],
+                cloneError: null,
+                commitsTruncated: Boolean(existing.metadata?.commits_truncated),
+            };
+        }
+    }
+    const gh = await getGitHubConfigByProduct(release.product_id, verbose);
+    const repoConfigured = gh.configured && gh.token && gh.owner && gh.repo;
+    // Clone at tag + fetch commits (both best-effort — we still render with
+    // whatever metadata we have).
+    let repoDir = null;
+    let cloneError = null;
+    let commits = '';
+    let commitsTruncated = false;
+    let lockPath = null;
+    if (repoConfigured) {
+        const owner = gh.owner;
+        const repo = gh.repo;
+        const token = gh.token;
+        // Serialise concurrent CLI invocations for the *same release* by
+        // taking a file lock next to the clone dir. Different releases get
+        // different lock files (per-release workspace).
+        const workspaceRoot = ensureWorkspaceDir();
+        const workspaceName = `run-sheet-${release.id}`;
+        const repoPathAhead = getFeatureRepoPath(workspaceRoot, workspaceName);
+        lockPath = `${repoPathAhead}.lock`;
+        if (!tryAcquireFileLock(lockPath)) {
+            return {
+                status: 'error',
+                releaseId: release.id,
+                releaseTag: release.tag,
+                summary: 'Another run-sheet generation is in progress for this release. Wait for it to finish or retry.',
+            };
+        }
+        try {
+            // Clone into a per-release directory so two releases of the same
+            // product don't stomp each other's checkout during concurrent
+            // generation. (smoke-test uses `release-${product_id}` — that races;
+            // we don't want to inherit that bug here.)
+            const { repoPath } = cloneFeatureRepo(workspaceRoot, workspaceName, owner, repo, token);
+            repoDir = repoPath;
+            try {
+                syncRepoToRef(repoPath, { tag: release.tag }, token);
+            }
+            catch (err) {
+                cloneError = `Could not checkout tag ${release.tag}: ${err instanceof Error ? err.message : String(err)}`;
+                logWarning(cloneError);
+            }
+        }
+        catch (err) {
+            cloneError = err instanceof Error ? err.message : String(err);
+            logWarning(`Clone failed: ${cloneError}`);
+        }
+        const c = await fetchCommitsBetween(owner, repo, release.previous_tag, release.tag, token);
+        commits = c.text;
+        commitsTruncated = c.truncated;
+    }
+    else {
+        cloneError = 'Product is not linked to a GitHub repository';
+    }
+    const { rendered, missing } = await renderTemplate(template, {
+        name: product?.name ?? 'Unknown product',
+        github_repository_full_name: product?.github_repository_full_name ?? null,
+    }, {
+        tag: release.tag,
+        name: release.name,
+        body: release.body,
+        url: release.url,
+        published_at: release.published_at,
+        previous_tag: release.previous_tag,
+        previous_published_at: release.previous_published_at,
+        diff_summary: release.diff_summary,
+        diff_stats: (release.diff_stats ?? {}),
+    }, repoDir, commits);
+    try {
+        const saved = await upsertRunSheet({
+            release_id: release.id,
+            content: rendered,
+            title: `Run Sheet — ${product?.name ?? ''} ${release.tag}`.trim(),
+            template_snapshot: template,
+            metadata: {
+                missing_placeholders: missing,
+                clone_error: cloneError,
+                repo: product?.github_repository_full_name ?? null,
+                tag: release.tag,
+                commits_truncated: commitsTruncated,
+            },
+            generated_at: new Date().toISOString(),
+        }, verbose);
+        logSuccess(`Generated run sheet for ${release.tag}`);
+        return {
+            status: 'success',
+            releaseId: release.id,
+            releaseTag: release.tag,
+            runSheetId: saved.id,
+            summary: `Rendered ${rendered.length} characters`,
+            missingPlaceholders: missing,
+            cloneError,
+            commitsTruncated,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logError(`Failed to upsert run sheet: ${message}`);
+        return {
+            status: 'error',
+            releaseId: release.id,
+            releaseTag: release.tag,
+            summary: `Failed to upsert run sheet: ${message}`,
+        };
+    }
+    finally {
+        if (lockPath) {
+            releaseFileLock(lockPath);
+        }
+    }
+}

package/dist/phases/run-sheet/render.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure template-rendering logic for run sheets.
+ *
+ * Intentionally identical to `web/src/services/run-sheets/render.ts` — any
+ * change here should mirror the web side (and its unit tests) so the CLI
+ * and the web `/api/releases/[id]/generate-run-sheet` route produce the
+ * exact same output for the same template + release.
+ */
+export declare const MAX_FILE_INCLUDE_BYTES: number;
+export declare const MAX_TOTAL_FILE_BYTES: number;
+export interface TemplateProduct {
+    name: string;
+    github_repository_full_name: string | null;
+}
+export interface TemplateRelease {
+    tag: string;
+    name: string | null;
+    body: string | null;
+    url: string | null;
+    published_at: string | null;
+    previous_tag: string | null;
+    previous_published_at: string | null;
+    diff_summary: string | null;
+    diff_stats: Record<string, unknown>;
+}
+export declare function isSafeGitRef(ref: string): boolean;
+export interface FileReadResult {
+    content: string | null;
+    bytes: number;
+    reason?: string;
+}
+export declare function safeReadRepoFile(repoDir: string, relPath: string, remainingBudget: number): Promise<FileReadResult>;
+export interface RenderResult {
+    rendered: string;
+    missing: string[];
+}
+/**
+ * Strip Markdown-style backslash escapes inside `{{ ... }}` spans so the
+ * Rich-text editor roundtrip doesn't break placeholder matching.
+ */
+export declare function normalizeTemplate(template: string): string;
+export declare function renderTemplate(template: string, product: TemplateProduct, release: TemplateRelease, repoDir: string | null, commits: string): Promise<RenderResult>;

package/dist/phases/run-sheet/render.js

@@ -0,0 +1,133 @@
+/**
+ * Pure template-rendering logic for run sheets.
+ *
+ * Intentionally identical to `web/src/services/run-sheets/render.ts` — any
+ * change here should mirror the web side (and its unit tests) so the CLI
+ * and the web `/api/releases/[id]/generate-run-sheet` route produce the
+ * exact same output for the same template + release.
+ */
+import { statSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { join, resolve } from 'path';
+export const MAX_FILE_INCLUDE_BYTES = 256 * 1024;
+export const MAX_TOTAL_FILE_BYTES = 1024 * 1024;
+export function isSafeGitRef(ref) {
+    if (typeof ref !== 'string' || ref.length === 0 || ref.length > 200) {
+        return false;
+    }
+    if (/\s/.test(ref) || /^[-.]/.test(ref)) {
+        return false;
+    }
+    if (ref.includes('..') || ref.includes('@{')) {
+        return false;
+    }
+    return /^[A-Za-z0-9._\-+/@]+$/.test(ref);
+}
+export async function safeReadRepoFile(repoDir, relPath, remainingBudget) {
+    if (!relPath || relPath.startsWith('/') || relPath.includes('\0')) {
+        return { content: null, bytes: 0, reason: 'invalid path' };
+    }
+    const repoDirResolved = resolve(repoDir);
+    const abs = resolve(join(repoDirResolved, relPath));
+    if (abs !== repoDirResolved && !abs.startsWith(`${repoDirResolved}/`)) {
+        return { content: null, bytes: 0, reason: 'path escape' };
+    }
+    let size;
+    try {
+        const stat = statSync(abs);
+        if (!stat.isFile()) {
+            return { content: null, bytes: 0, reason: 'not a file' };
+        }
+        size = stat.size;
+    }
+    catch {
+        return { content: null, bytes: 0, reason: 'not found' };
+    }
+    if (size > MAX_FILE_INCLUDE_BYTES) {
+        return {
+            content: null,
+            bytes: 0,
+            reason: `too large (${size} > ${MAX_FILE_INCLUDE_BYTES} bytes)`,
+        };
+    }
+    if (size > remainingBudget) {
+        return {
+            content: null,
+            bytes: 0,
+            reason: 'total file-inclusion budget exhausted',
+        };
+    }
+    try {
+        const content = await readFile(abs, 'utf-8');
+        return { content, bytes: size };
+    }
+    catch {
+        return { content: null, bytes: 0, reason: 'read failed' };
+    }
+}
+/**
+ * Strip Markdown-style backslash escapes inside `{{ ... }}` spans so the
+ * Rich-text editor roundtrip doesn't break placeholder matching.
+ */
+export function normalizeTemplate(template) {
+    return template.replace(/\{\{([^}]*)\}\}/g, (_match, inner) => `{{${inner.replace(/\\([_.\-\\/])/g, '$1')}}}`);
+}
+export async function renderTemplate(template, product, release, repoDir, commits) {
+    const missing = [];
+    const stats = release.diff_stats ?? {};
+    const normalized = normalizeTemplate(template);
+    const simpleVars = {
+        product_name: product.name,
+        release_tag: release.tag,
+        release_name: release.name ?? release.tag,
+        release_body: release.body ?? '',
+        release_url: release.url ?? '',
+        previous_tag: release.previous_tag ?? '',
+        published_at: release.published_at ?? '',
+        previous_published_at: release.previous_published_at ?? '',
+        diff_summary: release.diff_summary ?? '',
+        files_changed: String(stats.files_changed ?? ''),
+        additions: String(stats.additions ?? ''),
+        deletions: String(stats.deletions ?? ''),
+        commits_count: String(stats.commits_count ?? stats.total_commits ?? ''),
+        repository: product.github_repository_full_name ?? '',
+        generated_at: new Date().toISOString(),
+        commits,
+    };
+    const fileRegex = /\{\{\s*file:([^}]+?)\s*\}\}/g;
+    const fileMatches = [];
+    for (const m of normalized.matchAll(fileRegex)) {
+        fileMatches.push({ match: m[0], path: m[1].trim() });
+    }
+    let remainingBudget = MAX_TOTAL_FILE_BYTES;
+    const fileResults = new Map();
+    for (const { match, path } of fileMatches) {
+        if (fileResults.has(match)) {
+            continue;
+        }
+        if (!repoDir) {
+            missing.push(`file:${path} (no repo)`);
+            fileResults.set(match, `<!-- file ${path} unavailable: repo not cloned -->`);
+            continue;
+        }
+        // eslint-disable-next-line no-await-in-loop -- sequential so the byte budget is enforced
+        const res = await safeReadRepoFile(repoDir, path, remainingBudget);
+        if (res.content === null) {
+            missing.push(`file:${path} (${res.reason ?? 'unavailable'})`);
+            fileResults.set(match, `<!-- file ${path} unavailable: ${res.reason ?? 'unknown'} -->`);
+        }
+        else {
+            remainingBudget -= res.bytes;
+            fileResults.set(match, res.content);
+        }
+    }
+    let rendered = normalized.replace(fileRegex, (match) => fileResults.get(match) ?? match);
+    rendered = rendered.replace(/\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g, (match, key) => {
+        if (key in simpleVars) {
+            return simpleVars[key];
+        }
+        missing.push(key);
+        return match;
+    });
+    return { rendered, missing };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"
@@ -10,6 +10,9 @@
     "dev": "tsc --watch",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
+    "test": "npm run test:unit",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -49,7 +52,11 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "@types/turndown": "^5.0.6",
+    "marked": "^15.0.12",
+    "turndown": "^7.2.2",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.0"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/claude-agent-sdk": {

package/tsconfig.json

@@ -19,6 +19,7 @@
   ],
   "exclude": [
     "node_modules",
-    "dist"
+    "dist",
+    "src/**/*.test.ts"
   ]
 }

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    // The other __tests__ folders in this package use the node:test API
+    // (assert + node --test), not vitest. We scope vitest to just the
+    // run-sheet tests for now; migrating the rest can happen separately.
+    include: ['src/phases/run-sheet/__tests__/**/*.test.ts'],
+    exclude: ['dist/**', 'node_modules/**'],
+    environment: 'node',
+  },
+})