edsger 0.46.0 → 0.48.0

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

@@ -10,7 +10,8 @@
  * 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 { createHash } from 'crypto';
+import { closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, unlinkSync, writeFileSync, } from 'fs';
 import { join } from 'path';
 import { getGitHubConfigByProduct } from '../../api/github.js';
 import { getProduct } from '../../api/products.js';
@@ -18,29 +19,33 @@ 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 { fetchAllCompareCommits, getDefaultBranchHead, } 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 };
+        return { text: '', list: [], 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,
-        };
+        const { commits, truncated } = await fetchAllCompareCommits(owner, repo, base, head, token);
+        const list = commits.map((c) => {
+            const message = c.commit.message ?? '';
+            const summary = message.split('\n')[0];
+            return {
+                sha: c.sha,
+                short_sha: c.sha.slice(0, 7),
+                summary,
+                message,
+                author: c.commit.author?.name ?? '',
+                url: c.html_url ?? '',
+            };
+        });
+        const text = list.map((c) => `- ${c.short_sha} ${c.summary}`).join('\n');
+        return { text, list, truncated };
     }
     catch (err) {
-        logWarning(`Could not fetch commits for run sheet: ${err instanceof Error ? err.message : String(err)}`);
-        return { text: '', truncated: false };
+        const message = err instanceof Error ? err.message : String(err);
+        logWarning(`Could not fetch commits for run sheet: ${message}`);
+        return { text: '', list: [], truncated: false, error: message };
     }
 }
 // Stale locks (e.g. left behind by a crashed or SIGKILLed CLI) are
@@ -119,6 +124,87 @@ export function releaseFileLock(lockPath) {
         // Best-effort — lock will expire via LOCK_STALE_MS anyway.
     }
 }
+// A `run-sheet-<release-id>` workspace whose lock is stale and whose
+// dir hasn't been touched for this long is considered abandoned. 30 days
+// is long enough to keep caches warm across normal release cadences,
+// short enough that disk usage doesn't grow unboundedly.
+const WORKSPACE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Delete `run-sheet-*` workspaces that are both:
+ *   - not currently locked (lock file missing or stale), AND
+ *   - older than WORKSPACE_MAX_AGE_MS by mtime.
+ *
+ * Best-effort: any error on a single entry is logged and skipped so a
+ * corrupt dir doesn't block the current generation.
+ *
+ * Exported for unit tests.
+ */
+export function pruneStaleRunSheetWorkspaces(workspaceRoot, now = Date.now(), maxAgeMs = WORKSPACE_MAX_AGE_MS) {
+    const removed = [];
+    let entries;
+    try {
+        entries = readdirSync(workspaceRoot);
+    }
+    catch {
+        return { removed };
+    }
+    for (const entry of entries) {
+        if (!entry.startsWith('run-sheet-')) {
+            continue;
+        }
+        const entryPath = join(workspaceRoot, entry);
+        const lockPath = `${entryPath}.lock`;
+        let ageMs;
+        try {
+            const stat = statSync(entryPath);
+            if (!stat.isDirectory()) {
+                continue;
+            }
+            ageMs = now - stat.mtimeMs;
+        }
+        catch {
+            continue;
+        }
+        if (ageMs < maxAgeMs) {
+            continue;
+        }
+        // Don't delete a dir with a live lock — another CLI is mid-run.
+        try {
+            readFileSync(lockPath, 'utf-8');
+            if (!isLockStale(lockPath)) {
+                continue;
+            }
+        }
+        catch {
+            // Lock missing — safe to delete.
+        }
+        try {
+            rmSync(entryPath, { recursive: true, force: true });
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                // Lock file may not exist; that's fine.
+            }
+            removed.push(entry);
+        }
+        catch (err) {
+            logWarning(`Could not prune stale workspace ${entry}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { removed };
+}
+function computeInputHash(parts) {
+    const h = createHash('sha256');
+    h.update(`template:${parts.template}\n`);
+    h.update(`tag:${parts.tag}\n`);
+    h.update(`prev:${parts.previousTag ?? ''}\n`);
+    for (const f of [...parts.filesRead].sort((a, b) => a.path.localeCompare(b.path))) {
+        h.update(`file:${f.path}:${f.bytes}\n`);
+    }
+    h.update(`commits:${parts.commitShas.join(',')}\n`);
+    return h.digest('hex');
+}
 function runSheetIsFresh(existing, template, tag) {
     if (!existing || !existing.content) {
         return false;
@@ -192,15 +278,30 @@ export async function runRunSheet(options) {
     // whatever metadata we have).
     let repoDir = null;
     let cloneError = null;
+    let commitsError = null;
     let commits = '';
+    let commitsList = [];
     let commitsTruncated = false;
     let lockPath = null;
+    // Draft mode: the release's tag doesn't exist on GitHub yet (e.g. a
+    // Maven SNAPSHOT being planned pre-cut). We still want to produce a
+    // useful run sheet, so we fall back to the default branch HEAD for
+    // both the checkout and the commits compare.
+    let isDraft = false;
+    let draftBaseRef = null;
     if (repoConfigured && gh.owner && gh.repo && gh.token) {
         const { owner, repo, token } = gh;
         // 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();
+        // Sweep old per-release workspaces before cloning. Cheap (one
+        // readdir + stat per entry); silent unless something is actually
+        // removed.
+        const pruned = pruneStaleRunSheetWorkspaces(workspaceRoot);
+        if (pruned.removed.length > 0) {
+            logInfo(`Pruned ${pruned.removed.length} stale run-sheet workspace(s).`);
+        }
         const workspaceName = `run-sheet-${release.id}`;
         const repoPathAhead = getFeatureRepoPath(workspaceRoot, workspaceName);
         lockPath = `${repoPathAhead}.lock`;
@@ -223,22 +324,39 @@ export async function runRunSheet(options) {
                 syncRepoToRef(repoPath, { tag: release.tag }, token);
             }
             catch (err) {
-                cloneError = `Could not checkout tag ${release.tag}: ${err instanceof Error ? err.message : String(err)}`;
-                logWarning(cloneError);
+                const tagErr = err instanceof Error ? err.message : String(err);
+                logWarning(`Tag ${release.tag} not found — generating draft run sheet from default branch.`);
+                try {
+                    const { branch } = await getDefaultBranchHead(owner, repo, token);
+                    syncRepoToRef(repoPath, { branch }, token);
+                    isDraft = true;
+                    draftBaseRef = branch;
+                    cloneError = `Tag ${release.tag} not found; fell back to default branch ${branch}. (${tagErr})`;
+                }
+                catch (fallbackErr) {
+                    cloneError = `Could not checkout tag ${release.tag} or fall back to default branch: ${fallbackErr instanceof Error ? fallbackErr.message : String(fallbackErr)}`;
+                    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);
+        const head = isDraft && draftBaseRef ? draftBaseRef : release.tag;
+        const c = await fetchCommitsBetween(owner, repo, release.previous_tag, head, token);
         commits = c.text;
+        commitsList = c.list;
         commitsTruncated = c.truncated;
+        commitsError = c.error ?? null;
     }
     else {
         cloneError = 'Product is not linked to a GitHub repository';
     }
-    const { rendered, missing } = await renderTemplate(template, {
+    const draftNotice = isDraft
+        ? `> ⚠️ **Draft run sheet** — tag \`${release.tag}\` does not exist on GitHub yet. Rendered from default branch${draftBaseRef ? ` \`${draftBaseRef}\`` : ''}; regenerate after the tag is cut for final content.`
+        : '';
+    const { rendered, missing, filesRead } = await renderTemplate(template, {
         name: product?.name ?? 'Unknown product',
         github_repository_full_name: product?.github_repository_full_name ?? null,
     }, {
@@ -251,7 +369,14 @@ export async function runRunSheet(options) {
         previous_published_at: release.previous_published_at,
         diff_summary: release.diff_summary,
         diff_stats: release.diff_stats ?? {},
-    }, repoDir, commits);
+    }, repoDir, commits, draftNotice, commitsList);
+    const inputHash = computeInputHash({
+        template,
+        tag: release.tag,
+        previousTag: release.previous_tag,
+        filesRead,
+        commitShas: commitsList.map((c) => c.sha),
+    });
     try {
         const saved = await upsertRunSheet({
             release_id: release.id,
@@ -261,9 +386,14 @@ export async function runRunSheet(options) {
             metadata: {
                 missing_placeholders: missing,
                 clone_error: cloneError,
+                commits_error: commitsError,
                 repo: product?.github_repository_full_name ?? null,
                 tag: release.tag,
                 commits_truncated: commitsTruncated,
+                is_draft: isDraft,
+                draft_base_ref: draftBaseRef,
+                input_hash: inputHash,
+                commits_count: commitsList.length,
             },
             generated_at: new Date().toISOString(),
         }, verbose);
@@ -276,7 +406,9 @@ export async function runRunSheet(options) {
             summary: `Rendered ${rendered.length} characters`,
             missingPlaceholders: missing,
             cloneError,
+            commitsError,
             commitsTruncated,
+            isDraft,
         };
     }
     catch (err) {

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

@@ -1,10 +1,9 @@
 /**
  * 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.
+ * The CLI is the sole authoritative renderer today — if the web app
+ * ever grows its own run-sheet generation path, it should call into
+ * this module (or a published copy of it) rather than forking.
  */
 export declare const MAX_FILE_INCLUDE_BYTES: number;
 export declare const MAX_TOTAL_FILE_BYTES: number;
@@ -33,10 +32,29 @@ export declare function safeReadRepoFile(repoDir: string, relPath: string, remai
 export interface RenderResult {
     rendered: string;
     missing: string[];
+    filesRead: {
+        path: string;
+        bytes: number;
+    }[];
+}
+export interface TemplateCommit {
+    sha: string;
+    short_sha: string;
+    summary: string;
+    message: string;
+    author: string;
+    url: 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>;
+/**
+ * Escape CommonMark-significant characters so untrusted strings
+ * (commit messages, author names, release bodies) can be safely
+ * dropped into a markdown run sheet without injecting headings,
+ * blockquotes, links, images, or HTML.
+ */
+export declare function escapeMarkdown(raw: string): string;
+export declare function renderTemplate(template: string, product: TemplateProduct, release: TemplateRelease, repoDir: string | null, commits: string, draftNotice?: string, commitsList?: TemplateCommit[]): Promise<RenderResult>;

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

@@ -1,12 +1,11 @@
 /**
  * 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.
+ * The CLI is the sole authoritative renderer today — if the web app
+ * ever grows its own run-sheet generation path, it should call into
+ * this module (or a published copy of it) rather than forking.
  */
-import { statSync } from 'fs';
+import { lstatSync, realpathSync, statSync } from 'fs';
 import { readFile } from 'fs/promises';
 import { join, resolve } from 'path';
 export const MAX_FILE_INCLUDE_BYTES = 256 * 1024;
@@ -32,6 +31,29 @@ export async function safeReadRepoFile(repoDir, relPath, remainingBudget) {
     if (abs !== repoDirResolved && !abs.startsWith(`${repoDirResolved}/`)) {
         return { content: null, bytes: 0, reason: 'path escape' };
     }
+    // Refuse symlinks at the leaf. `resolve()` only collapses `..`; it does
+    // not follow symlinks, so a symlink *inside* the repo pointing at
+    // `/etc/passwd` would otherwise be readable.
+    try {
+        if (lstatSync(abs).isSymbolicLink()) {
+            return { content: null, bytes: 0, reason: 'symlink refused' };
+        }
+    }
+    catch {
+        return { content: null, bytes: 0, reason: 'not found' };
+    }
+    // Also verify the fully-resolved real path still lives inside the repo
+    // root — catches symlinked parent directories.
+    try {
+        const realAbs = realpathSync(abs);
+        const realRoot = realpathSync(repoDirResolved);
+        if (realAbs !== realRoot && !realAbs.startsWith(`${realRoot}/`)) {
+            return { content: null, bytes: 0, reason: 'symlink escapes repo' };
+        }
+    }
+    catch {
+        return { content: null, bytes: 0, reason: 'not found' };
+    }
     let size;
     try {
         const stat = statSync(abs);
@@ -73,32 +95,134 @@ export async function safeReadRepoFile(repoDir, relPath, remainingBudget) {
 export function normalizeTemplate(template) {
     return template.replace(/\{\{([^}]*)\}\}/g, (_match, inner) => `{{${inner.replace(/\\([_.\-\\/])/g, '$1')}}}`);
 }
-// eslint-disable-next-line complexity -- template expansion branches per placeholder type
-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,
+function isTruthy(value) {
+    if (!value) {
+        return false;
+    }
+    const v = value.trim();
+    return v !== '' && v !== 'false' && v !== '0';
+}
+/**
+ * Split a block body on a top-level `{{else}}` so `{{#if}}A{{else}}B{{/if}}`
+ * resolves. Because we don't support nested same-keyword blocks, a naive
+ * first-occurrence split is safe enough.
+ */
+function splitOnElse(body) {
+    const m = body.match(/\{\{\s*else\s*\}\}/);
+    if (!m || m.index === undefined) {
+        return { main: body, alt: '' };
+    }
+    return {
+        main: body.slice(0, m.index),
+        alt: body.slice(m.index + m[0].length),
     };
+}
+/**
+ * Replace `{{#if key}}...{{else}}...{{/if}}` and
+ * `{{#unless key}}...{{else}}...{{/unless}}` blocks. Runs repeatedly
+ * until a fixed point so two sibling (non-nested) blocks both resolve.
+ * Nested blocks of the *same* keyword aren't supported; that's an
+ * intentional simplicity/safety choice.
+ */
+function substituteConditionals(template, ctx) {
+    const IF_RE = /\{\{\s*#if\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}([\s\S]*?)\{\{\s*\/if\s*\}\}/g;
+    const UNLESS_RE = /\{\{\s*#unless\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}([\s\S]*?)\{\{\s*\/unless\s*\}\}/g;
+    let out = template;
+    for (let i = 0; i < 5; i++) {
+        const before = out;
+        out = out.replace(IF_RE, (_, key, body) => {
+            const { main, alt } = splitOnElse(body);
+            return isTruthy(ctx[key] ?? '') ? main : alt;
+        });
+        out = out.replace(UNLESS_RE, (_, key, body) => {
+            const { main, alt } = splitOnElse(body);
+            return isTruthy(ctx[key] ?? '') ? alt : main;
+        });
+        if (out === before) {
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * Expand `{{#each commits}}...{{/each}}`. Each iteration renders the body
+ * with a merged ctx of (outer vars + commit fields), running the full
+ * conditional + variable substitution on the body so `{{#if url}}` /
+ * `{{formatDate ...}}` / outer vars all work per-commit.
+ */
+function substituteEachCommits(template, commits, outerCtx) {
+    const EACH_RE = /\{\{\s*#each\s+commits\s*\}\}([\s\S]*?)\{\{\s*\/each\s*\}\}/g;
+    return template.replace(EACH_RE, (_match, body) => commits
+        .map((c) => {
+        const localCtx = {
+            ...outerCtx,
+            sha: c.sha,
+            short_sha: c.short_sha,
+            summary: c.summary,
+            message: c.message,
+            author: c.author,
+            url: c.url,
+        };
+        let rendered = substituteConditionals(body, localCtx);
+        rendered = substituteDateHelper(rendered, localCtx);
+        rendered = substituteEscapeHelper(rendered, localCtx);
+        rendered = rendered.replace(/\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g, (match, key) => (key in localCtx ? localCtx[key] : match));
+        return rendered;
+    })
+        .join(''));
+}
+/**
+ * Escape CommonMark-significant characters so untrusted strings
+ * (commit messages, author names, release bodies) can be safely
+ * dropped into a markdown run sheet without injecting headings,
+ * blockquotes, links, images, or HTML.
+ */
+export function escapeMarkdown(raw) {
+    if (!raw) {
+        return '';
+    }
+    // Backslash-escape every CommonMark-significant punctuation character.
+    // This also neutralises line-start markers (`#`, `>`, `-`, `+`, `*`,
+    // `1.`) because their first char always ends up escaped.
+    return raw.replace(/([\\`*_{}\[\]()#+\-.!|<>~])/g, '\\$1');
+}
+function substituteEscapeHelper(template, ctx) {
+    const RE = /\{\{\s*escape\s+([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g;
+    return template.replace(RE, (_match, key) => escapeMarkdown(ctx[key] ?? ''));
+}
+/**
+ * `{{formatDate key 'YYYY-MM-DD HH:mm'}}` — resolves `key` from ctx (must
+ * be a parseable date), formats with a tiny token set. Invalid dates or
+ * empty values render as empty string (matches the "degrade gracefully"
+ * convention the rest of the template follows).
+ */
+function substituteDateHelper(template, ctx) {
+    const RE = /\{\{\s*formatDate\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+['"]([^'"]+)['"]\s*\}\}/g;
+    return template.replace(RE, (_match, key, format) => {
+        const raw = ctx[key];
+        if (!raw) {
+            return '';
+        }
+        const d = new Date(raw);
+        if (Number.isNaN(d.getTime())) {
+            return '';
+        }
+        const pad = (n) => n.toString().padStart(2, '0');
+        return format
+            .replace(/YYYY/g, String(d.getUTCFullYear()))
+            .replace(/MM/g, pad(d.getUTCMonth() + 1))
+            .replace(/DD/g, pad(d.getUTCDate()))
+            .replace(/HH/g, pad(d.getUTCHours()))
+            .replace(/mm/g, pad(d.getUTCMinutes()))
+            .replace(/ss/g, pad(d.getUTCSeconds()));
+    });
+}
+async function expandFileIncludes(template, repoDir) {
+    const missing = [];
+    const filesRead = [];
     const fileRegex = /\{\{\s*file:([^}]+?)\s*\}\}/g;
     const fileMatches = [];
-    for (const m of normalized.matchAll(fileRegex)) {
+    for (const m of template.matchAll(fileRegex)) {
         fileMatches.push({ match: m[0], path: m[1].trim() });
     }
     let remainingBudget = MAX_TOTAL_FILE_BYTES;
@@ -112,7 +236,6 @@ export async function renderTemplate(template, product, release, repoDir, commit
             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'})`);
@@ -120,10 +243,49 @@ export async function renderTemplate(template, product, release, repoDir, commit
         }
         else {
             remainingBudget -= res.bytes;
+            filesRead.push({ path, bytes: res.bytes });
             fileResults.set(match, res.content);
         }
     }
-    let rendered = normalized.replace(fileRegex, (match) => fileResults.get(match) ?? match);
+    const rendered = template.replace(fileRegex, (match) => fileResults.get(match) ?? match);
+    return { rendered, missing, filesRead };
+}
+function buildSimpleVars(product, release, commits, draftNotice) {
+    const stats = release.diff_stats ?? {};
+    return {
+        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,
+        draft_notice: draftNotice,
+    };
+}
+export async function renderTemplate(template, product, release, repoDir, commits, draftNotice = '', commitsList = []) {
+    const missing = [];
+    const simpleVars = buildSimpleVars(product, release, commits, draftNotice);
+    // Pipeline: normalize → file includes → #each (self-contained, renders
+    // its body with per-commit ctx) → outer #if/#unless → date helper →
+    // variable substitution. Running `#each` first lets it fully resolve
+    // per-commit `{{#if url}}` without bleeding into outer-scope `{{#if}}`.
+    const normalized = normalizeTemplate(template);
+    const fileExpansion = await expandFileIncludes(normalized, repoDir);
+    missing.push(...fileExpansion.missing);
+    let rendered = substituteEachCommits(fileExpansion.rendered, commitsList, simpleVars);
+    rendered = substituteConditionals(rendered, simpleVars);
+    rendered = substituteDateHelper(rendered, simpleVars);
+    rendered = substituteEscapeHelper(rendered, simpleVars);
     rendered = rendered.replace(/\{\{\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\}\}/g, (match, key) => {
         if (key in simpleVars) {
             return simpleVars[key];
@@ -131,5 +293,5 @@ export async function renderTemplate(template, product, release, repoDir, commit
         missing.push(key);
         return match;
     });
-    return { rendered, missing };
+    return { rendered, missing, filesRead: fileExpansion.filesRead };
 }

package/dist/phases/smoke-test/__tests__/agent.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Unit tests for smoke-test agent response parsing.
+ */
+export {};

package/dist/phases/smoke-test/__tests__/agent.test.js

@@ -0,0 +1,84 @@
+/**
+ * Unit tests for smoke-test agent response parsing.
+ */
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { extractJson, findBalancedJsonObject } from '../agent.js';
+void describe('extractJson', () => {
+    void it('parses a plain JSON object', () => {
+        const raw = `{
+      "summary": "one thing changed",
+      "test_cases": [
+        { "name": "login still works", "description": "step 1", "is_critical": true }
+      ]
+    }`;
+        const parsed = extractJson(raw);
+        assert.strictEqual(parsed.summary, 'one thing changed');
+        assert.strictEqual(parsed.test_cases.length, 1);
+        assert.strictEqual(parsed.test_cases[0].is_critical, true);
+    });
+    void it('strips ```json fences', () => {
+        const raw = '```json\n{"summary":"x","test_cases":[{"name":"a","description":"b"}]}\n```';
+        const parsed = extractJson(raw);
+        assert.strictEqual(parsed.summary, 'x');
+        assert.strictEqual(parsed.test_cases[0].name, 'a');
+    });
+    void it('strips unlabeled fences', () => {
+        const raw = '```\n{"summary":"x","test_cases":[]}\n```';
+        const parsed = extractJson(raw);
+        assert.deepStrictEqual(parsed.test_cases, []);
+    });
+    void it('tolerates leading and trailing prose', () => {
+        const raw = `Here you go:
+{"summary":"x","test_cases":[{"name":"a","description":"b"}]}
+
+Hope that helps.`;
+        const parsed = extractJson(raw);
+        assert.strictEqual(parsed.summary, 'x');
+    });
+    void it('throws when test_cases is missing', () => {
+        assert.throws(() => extractJson('{"summary":"x"}'), /test_cases/);
+    });
+    void it('throws on invalid JSON', () => {
+        assert.throws(() => extractJson('not json'));
+    });
+    void it('picks the first balanced object when prose contains decoy braces', () => {
+        const raw = 'Note: { pseudo-json example } but the real answer is:\n' +
+            '{"summary":"x","test_cases":[{"name":"a","description":"b"}]}\n' +
+            'Let me know if you want changes.';
+        const parsed = extractJson(raw);
+        assert.strictEqual(parsed.summary, 'x');
+        assert.strictEqual(parsed.test_cases[0].name, 'a');
+    });
+    void it('preserves braces inside JSON string values', () => {
+        const raw = '{"summary":"changes to {pricing} and {checkout}","test_cases":[{"name":"n","description":"d"}]}';
+        const parsed = extractJson(raw);
+        assert.strictEqual(parsed.summary, 'changes to {pricing} and {checkout}');
+    });
+    void it('throws when test_cases is not an array', () => {
+        assert.throws(() => extractJson('{"summary":"x","test_cases":"nope"}'), /test_cases/);
+    });
+});
+void describe('findBalancedJsonObject', () => {
+    void it('returns null when there is no opening brace', () => {
+        assert.strictEqual(findBalancedJsonObject('no braces here'), null);
+    });
+    void it('returns the first balanced top-level object', () => {
+        assert.strictEqual(findBalancedJsonObject('prefix {"a": 1} and {"b": 2} suffix'), '{"a": 1}');
+    });
+    void it('handles nested braces', () => {
+        const text = 'xxx {"a": {"b": {"c": 1}}} yyy';
+        assert.strictEqual(findBalancedJsonObject(text), '{"a": {"b": {"c": 1}}}');
+    });
+    void it('ignores braces inside strings', () => {
+        const text = '{"msg": "this has { and } inside", "ok": true}';
+        assert.strictEqual(findBalancedJsonObject(text), text);
+    });
+    void it('handles escaped quotes inside strings', () => {
+        const text = '{"msg": "she said \\"hi\\" {not object}"}';
+        assert.strictEqual(findBalancedJsonObject(text), text);
+    });
+    void it('returns null on unbalanced input', () => {
+        assert.strictEqual(findBalancedJsonObject('{"a": 1'), null);
+    });
+});