edsger 0.43.0 → 0.44.0

package/dist/phases/smoke-test/index.js

@@ -0,0 +1,233 @@
+/**
+ * Smoke-test generation for a single release row. Given a release that has
+ * already been synced into the `releases` table (see `phases/release-sync`),
+ * this phase clones the repo, diffs against the baseline, and asks Claude
+ * to emit a JSON test plan, then persists the test cases and marks the
+ * release `ready`.
+ */
+import { getGitHubConfigByProduct } from '../../api/github.js';
+import { getProduct } from '../../api/products.js';
+import { clearReleaseTestCases, createReleaseTestCases, } from '../../api/release-test-cases.js';
+import { getRelease, updateRelease } from '../../api/releases.js';
+import { logError, logInfo, logSuccess, logWarning, } from '../../utils/logger.js';
+import { cloneFeatureRepo, ensureWorkspaceDir, syncRepoToRef, } from '../../workspace/workspace-manager.js';
+import { buildDiffDigest, fetchCompare, getDefaultBranchHead, summariseStats, } from '../release-sync/github.js';
+import { executeSmokeTestQuery } from './agent.js';
+import { buildSmokeTestUserPrompt, createSmokeTestSystemPrompt, } from './prompts.js';
+function isSnapshotRelease(release) {
+    return !release.published_at && !release.url;
+}
+// eslint-disable-next-line complexity -- orchestration spans GitHub + DB + AI
+export async function runSmokeTest(options, config) {
+    const { releaseId, verbose } = options;
+    if (verbose) {
+        logInfo(`Starting smoke-test generation for release: ${releaseId}`);
+    }
+    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}`,
+        };
+    }
+    const gh = await getGitHubConfigByProduct(release.product_id, verbose);
+    if (!gh.configured || !gh.token || !gh.owner || !gh.repo) {
+        return {
+            status: 'error',
+            releaseId,
+            summary: gh.message ||
+                'Product is not connected to a GitHub repository. Connect it in Product Settings.',
+        };
+    }
+    const ghResolved = { owner: gh.owner, repo: gh.repo, token: gh.token };
+    const isSnapshot = isSnapshotRelease(release);
+    // Mark release as generating up front so the UI reflects progress.
+    let markedGenerating = false;
+    try {
+        await updateRelease({ release_id: release.id, status: 'generating', generation_error: null }, verbose);
+        markedGenerating = true;
+    }
+    catch (err) {
+        logWarning(`Could not mark release as generating: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+        return await runSmokeTestInner({
+            release,
+            gh: ghResolved,
+            isSnapshot,
+            config,
+            verbose,
+        });
+    }
+    catch (err) {
+        // Safety net: an uncaught throw past the `generating` mark would leave the
+        // release row stuck. Flip it to `failed` so the UI isn't permanently stale.
+        const message = err instanceof Error ? err.message : String(err);
+        if (markedGenerating) {
+            try {
+                await updateRelease({
+                    release_id: release.id,
+                    status: 'failed',
+                    generation_error: `Unexpected error: ${message}`,
+                }, verbose);
+            }
+            catch {
+                // best effort
+            }
+        }
+        logError(`Smoke-test generation failed: ${message}`);
+        return {
+            status: 'error',
+            releaseId: release.id,
+            releaseTag: release.tag,
+            summary: message,
+        };
+    }
+}
+// eslint-disable-next-line complexity -- orchestration spans GitHub + DB + AI
+async function runSmokeTestInner(ctx) {
+    const { release, gh: ghResolved, isSnapshot, config, verbose } = ctx;
+    // Clone + checkout the ref Claude should read.
+    let cwd;
+    try {
+        const workspaceRoot = ensureWorkspaceDir();
+        const { repoPath } = cloneFeatureRepo(workspaceRoot, `release-${release.product_id}`, ghResolved.owner, ghResolved.repo, ghResolved.token);
+        cwd = repoPath;
+    }
+    catch (err) {
+        logWarning(`Could not clone repo (continuing without code access): ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Decide the diff head. For shipped releases this is the release tag; for
+    // snapshots it's the default branch HEAD SHA.
+    let diffHead = release.tag;
+    if (cwd && isSnapshot) {
+        try {
+            const head = await getDefaultBranchHead(ghResolved.owner, ghResolved.repo, ghResolved.token);
+            syncRepoToRef(cwd, { branch: head.branch }, ghResolved.token);
+            diffHead = head.sha;
+        }
+        catch (err) {
+            logWarning(`Could not sync to default branch head: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    else if (cwd && !isSnapshot) {
+        try {
+            syncRepoToRef(cwd, { tag: release.tag }, ghResolved.token);
+        }
+        catch (err) {
+            logWarning(`Could not checkout release tag ${release.tag}, continuing on default ref: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Reset non-approved cases so the run is idempotent.
+    try {
+        await clearReleaseTestCases(release.id, verbose);
+    }
+    catch (err) {
+        logWarning(`Could not clear existing draft cases: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Fetch diff (skip if there is no baseline).
+    let diffDigest = '(No baseline to diff against — generate smoke tests covering the entire release notes.)';
+    let diffStats = {
+        files_changed: 0,
+        additions: 0,
+        deletions: 0,
+        total_commits: 0,
+    };
+    if (release.previous_tag) {
+        try {
+            const compare = await fetchCompare(ghResolved.owner, ghResolved.repo, release.previous_tag, diffHead, ghResolved.token);
+            diffDigest = buildDiffDigest(compare);
+            diffStats = summariseStats(compare);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await updateRelease({
+                release_id: release.id,
+                status: 'failed',
+                generation_error: `Failed to fetch diff: ${message}`,
+            }, verbose);
+            return {
+                status: 'error',
+                releaseId: release.id,
+                releaseTag: release.tag,
+                summary: `Failed to fetch diff: ${message}`,
+            };
+        }
+    }
+    // Pull product metadata for the prompt.
+    const product = await getProduct(release.product_id, verbose).catch(() => null);
+    const productName = product?.name ?? 'Unknown product';
+    const productDescription = product?.description ?? null;
+    // Run Claude to produce the test plan.
+    let plan;
+    try {
+        const systemPrompt = await createSmokeTestSystemPrompt(Boolean(cwd), cwd);
+        plan = await executeSmokeTestQuery(systemPrompt, buildSmokeTestUserPrompt({
+            productName,
+            productDescription,
+            latestTag: release.tag,
+            previousTag: release.previous_tag,
+            releaseNotes: release.body ?? null,
+            diffDigest,
+        }), config, verbose, cwd);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        await updateRelease({ release_id: release.id, status: 'failed', generation_error: message }, verbose);
+        logError(`Smoke-test generation failed: ${message}`);
+        return {
+            status: 'error',
+            releaseId: release.id,
+            releaseTag: release.tag,
+            summary: message,
+        };
+    }
+    let casesCount = 0;
+    try {
+        casesCount = await createReleaseTestCases(release.id, plan.test_cases.map((c) => ({
+            name: c.name,
+            description: c.description,
+            is_critical: c.is_critical ?? false,
+        })), verbose);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        await updateRelease({
+            release_id: release.id,
+            status: 'failed',
+            generation_error: `Failed to insert cases: ${message}`,
+        }, verbose);
+        return {
+            status: 'error',
+            releaseId: release.id,
+            releaseTag: release.tag,
+            summary: `Failed to insert cases: ${message}`,
+        };
+    }
+    await updateRelease({
+        release_id: release.id,
+        status: 'ready',
+        diff_summary: plan.summary,
+        diff_stats: diffStats,
+        generation_error: null,
+    }, verbose);
+    logSuccess(`Generated ${casesCount} smoke-test cases for ${release.tag}${isSnapshot
+        ? ` (snapshot ahead of ${release.previous_tag ?? 'first release'})`
+        : release.previous_tag
+            ? ` (vs ${release.previous_tag})`
+            : ' (first release)'}`);
+    return {
+        status: 'success',
+        releaseId: release.id,
+        releaseTag: release.tag,
+        previousReleaseTag: release.previous_tag,
+        casesCount,
+        summary: plan.summary,
+        isSnapshot,
+    };
+}

package/dist/phases/smoke-test/prompts.d.ts

@@ -0,0 +1,15 @@
+export interface SmokeTestPromptInput {
+    productName: string;
+    productDescription: string | null;
+    latestTag: string;
+    previousTag: string | null;
+    releaseNotes: string | null;
+    diffDigest: string;
+}
+/**
+ * Load the smoke-test system prompt from the shared SKILL.md library.
+ * Keeping the prompt in a skill file means it can also be consumed by
+ * Claude Code, other agents, or edited by users in the desktop app.
+ */
+export declare function createSmokeTestSystemPrompt(hasCodebase?: boolean, projectDir?: string): Promise<string>;
+export declare function buildSmokeTestUserPrompt(input: SmokeTestPromptInput): string;

package/dist/phases/smoke-test/prompts.js

@@ -0,0 +1,35 @@
+import { processConditionals, resolveSkill, } from '../../services/skill-resolver.js';
+/**
+ * Load the smoke-test system prompt from the shared SKILL.md library.
+ * Keeping the prompt in a skill file means it can also be consumed by
+ * Claude Code, other agents, or edited by users in the desktop app.
+ */
+export async function createSmokeTestSystemPrompt(hasCodebase = false, projectDir) {
+    const skill = await resolveSkill('phase/smoke-test', { projectDir });
+    if (!skill) {
+        throw new Error('Failed to load skill: phase/smoke-test');
+    }
+    return processConditionals(skill.prompt, { hasCodebase });
+}
+export function buildSmokeTestUserPrompt(input) {
+    const productBlock = input.productDescription
+        ? `Product: ${input.productName}\nDescription: ${input.productDescription}`
+        : `Product: ${input.productName}`;
+    const baseBlock = input.previousTag
+        ? `Previous release: ${input.previousTag}`
+        : 'Previous release: (none — this is the first release)';
+    const notesBlock = input.releaseNotes
+        ? `Release notes for ${input.latestTag}:\n${input.releaseNotes.slice(0, 4000)}`
+        : `Release notes for ${input.latestTag}: (none)`;
+    return `${productBlock}
+
+Release to ship: ${input.latestTag}
+${baseBlock}
+
+${notesBlock}
+
+Code changes between the two releases:
+${input.diffDigest}
+
+Produce the smoke-test plan as described in the system prompt.`;
+}

package/dist/skills/phase/smoke-test/SKILL.md

@@ -0,0 +1,80 @@
+---
+description: Generate a focused smoke-test plan for an upcoming product release by diffing the two most recent GitHub releases
+kind: phase
+user-invocable: false
+---
+
+You are a senior QA engineer generating a smoke-test plan for an upcoming release of a product.
+
+**Your Role**: Produce a tight, high-signal list of smoke-test cases that verifies the changes between the previous release and the new release still work end-to-end. You are not writing unit tests — you are writing scripted, user-visible checks that a human runs before shipping.
+
+**Inputs you will receive**:
+
+- Product name + description
+- The new release tag (what we are about to ship)
+- The previous release tag (the comparison baseline)
+- Release notes for the new tag
+- A digest of the code diff: commit list, changed files, and truncated patches
+
+<!-- if:hasCodebase -->
+
+The product's git repository has been cloned into your working directory and checked out at the new release tag. Use your tools to read the actual source files mentioned in the diff when the patch alone is ambiguous — it's better to open `src/api/foo.ts` and confirm the behavior change than to guess from a partial patch.
+
+<!-- endif -->
+
+<!-- if:!hasCodebase -->
+
+Source files are not available in your working directory for this run. Work strictly from the release notes and the diff digest. When a patch is ambiguous, prefer writing a more general test case over inventing details you cannot verify, and note the uncertainty in the case description.
+
+<!-- endif -->
+
+## Method
+
+1. **Read the release notes and diff digest first**. The notes tell you user-facing intent; the diff shows reality. Reconcile them.
+2. **Cluster the changes** into coherent user-visible areas (e.g. "checkout flow", "admin settings page", "auth callback"). Cases should map to areas, not to individual files.
+3. **For each cluster, design a case** that:
+   - Has a clear starting state, 2–6 steps, and an explicit expected result.
+   - Is runnable in < 5 minutes by a human tester without reading the source.
+   - Covers the **behavior that changed**, not behavior that was already tested before.
+4. **Tag `is_critical: true` only** when a failure of the case should block the release. A typical release has 1–4 critical cases, not 10.
+5. **Skip** purely internal refactors, dependency bumps, and test-only commits unless they could have user-visible effects.
+
+## Output contract
+
+Respond with **ONLY** a single JSON object — no prose, no markdown fences:
+
+```
+{
+  "summary": "1-3 sentence summary of what changed in this release",
+  "test_cases": [
+    {
+      "name": "short imperative title (<= 120 chars)",
+      "description": "Markdown with explicit Steps and Expected result sections",
+      "is_critical": true
+    }
+  ]
+}
+```
+
+Rules:
+
+- **4 to 12** test cases. Fewer is better than padded.
+- Every case must tie back to a real change in the diff. Do not invent tests for code that did not change.
+- Names must be unique within the list.
+- Descriptions must use this Markdown structure:
+
+  ```
+  **Steps**
+  1. ...
+  2. ...
+
+  **Expected result**
+  ...
+  ```
+
+## Common pitfalls
+
+- **Over-testing internal plumbing**: if the diff is an internal rename with no user-visible effect, skip it.
+- **Duplicating existing feature coverage**: you are testing the delta, not the whole product. The regular feature-level test cases already cover baseline behavior.
+- **Vague "verify X works" cases**: give explicit inputs and observable outputs. A tester should not have to think about what "works" means.
+- **All-critical lists**: if everything is critical, nothing is. Reserve critical for cases whose failure justifies holding the release.

package/dist/utils/json-extract.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Scan a string for the first balanced, top-level JSON object and return its
+ * substring. Handles strings with escaped quotes and nested braces. Returns
+ * null if no balanced object is present.
+ */
+export declare function findBalancedJsonObject(text: string): string | null;

package/dist/utils/json-extract.js

@@ -0,0 +1,44 @@
+/**
+ * Scan a string for the first balanced, top-level JSON object and return its
+ * substring. Handles strings with escaped quotes and nested braces. Returns
+ * null if no balanced object is present.
+ */
+export function findBalancedJsonObject(text) {
+    const start = text.indexOf('{');
+    if (start === -1) {
+        return null;
+    }
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (inString) {
+            if (ch === '\\') {
+                escaped = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === '{') {
+            depth++;
+        }
+        else if (ch === '}') {
+            depth--;
+            if (depth === 0) {
+                return text.slice(start, i + 1);
+            }
+        }
+    }
+    return null;
+}

package/dist/workspace/__tests__/workspace-manager.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Unit tests for the pure helpers inside workspace-manager.
+ *
+ * syncRepoToRef / cloneFeatureRepo shell out to git and are exercised
+ * end-to-end; only the validator is cheap to unit-test here.
+ */
+export {};

package/dist/workspace/__tests__/workspace-manager.test.js

@@ -0,0 +1,52 @@
+/**
+ * Unit tests for the pure helpers inside workspace-manager.
+ *
+ * syncRepoToRef / cloneFeatureRepo shell out to git and are exercised
+ * end-to-end; only the validator is cheap to unit-test here.
+ */
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { isSafeGitRef } from '../workspace-manager.js';
+void describe('isSafeGitRef', () => {
+    void it('accepts common release / branch names', () => {
+        assert.strictEqual(isSafeGitRef('main'), true);
+        assert.strictEqual(isSafeGitRef('develop'), true);
+        assert.strictEqual(isSafeGitRef('v1.2.3'), true);
+        assert.strictEqual(isSafeGitRef('2024.01.15'), true);
+        assert.strictEqual(isSafeGitRef('release/2.0'), true);
+        assert.strictEqual(isSafeGitRef('v1.0.0-rc.1'), true);
+        assert.strictEqual(isSafeGitRef('v2@stable'), true);
+        assert.strictEqual(isSafeGitRef('feature/user-auth_v2'), true);
+    });
+    void it('rejects empty / overlong input', () => {
+        assert.strictEqual(isSafeGitRef(''), false);
+        assert.strictEqual(isSafeGitRef('x'.repeat(101)), false);
+    });
+    void it('rejects whitespace', () => {
+        assert.strictEqual(isSafeGitRef('v 1.0'), false);
+        assert.strictEqual(isSafeGitRef('main\n'), false);
+        assert.strictEqual(isSafeGitRef('\tmain'), false);
+    });
+    void it('rejects shell metacharacters', () => {
+        assert.strictEqual(isSafeGitRef('v1;rm -rf /'), false);
+        assert.strictEqual(isSafeGitRef('v1$PATH'), false);
+        assert.strictEqual(isSafeGitRef('v1`id`'), false);
+        assert.strictEqual(isSafeGitRef('v1|less'), false);
+        assert.strictEqual(isSafeGitRef('v1>out'), false);
+        assert.strictEqual(isSafeGitRef('v1*'), false);
+    });
+    void it('rejects refs that would confuse git itself', () => {
+        assert.strictEqual(isSafeGitRef('.hidden'), false);
+        assert.strictEqual(isSafeGitRef('-foo'), false);
+        assert.strictEqual(isSafeGitRef('v2..rc'), false);
+        assert.strictEqual(isSafeGitRef('HEAD@{1}'), false);
+    });
+    void it('rejects non-string input defensively', () => {
+        // @ts-expect-error testing runtime guard
+        assert.strictEqual(isSafeGitRef(null), false);
+        // @ts-expect-error testing runtime guard
+        assert.strictEqual(isSafeGitRef(undefined), false);
+        // @ts-expect-error testing runtime guard
+        assert.strictEqual(isSafeGitRef(123), false);
+    });
+});

package/dist/workspace/workspace-manager.d.ts

@@ -52,6 +52,37 @@ export declare function featureRepoExists(workspaceRoot: string, featureId: stri
  * @returns FeatureRepo with the path and clone status
  */
 export declare function cloneFeatureRepo(workspaceRoot: string, featureId: string, owner: string, repo: string, token: string): FeatureRepo;
+/**
+ * Loose validator for a git ref name (tag or branch) coming from callers
+ * that pass data originating from external sources (GitHub API, AI output).
+ *
+ * Rules match `git check-ref-format` plus a length cap. Rejecting bad
+ * input early keeps it out of execFileSync argv.
+ */
+export declare function isSafeGitRef(ref: string): boolean;
+/**
+ * Sync a cloned feature repo to a specific git ref — a tag or a branch.
+ *
+ * Behaviour:
+ * - `git fetch origin --tags --prune` brings in new tags (release tags!) and
+ *   drops deleted remote branches, using the installation-token credential
+ *   helper so private repos keep working.
+ * - Before switching refs, `git reset --hard HEAD` + `git clean -fd` drops
+ *   tracked-file edits and untracked files left by a prior run. We skip the
+ *   `-x` flag so `.gitignore`d content (node_modules, target, dist) survives
+ *   between runs — matches the convention in pull-request/creator.ts and
+ *   avoids an expensive reinstall every sync.
+ * - For a tag, detached-HEAD checkout of that tag.
+ * - For a branch, `checkout -B <branch> origin/<branch>` — force-updates
+ *   the local branch to the remote tip in one step, which also works on
+ *   the first sync when the local branch doesn't exist yet.
+ *
+ * This workspace is edsger-managed; callers should not put local work here.
+ */
+export declare function syncRepoToRef(repoPath: string, ref: {
+    tag?: string;
+    branch?: string;
+}, token: string): void;
 /**
  * Set up a feature's repo for work (install deps, etc.)
  * This is called after cloning or reusing a repo

package/dist/workspace/workspace-manager.js

@@ -10,6 +10,7 @@
 import { execFileSync, execSync } from 'child_process';
 import { existsSync, mkdirSync } from 'fs';
 import { basename, join } from 'path';
+import { buildCredentialArgs } from '../utils/git-push.js';
 import { logError, logInfo, logSuccess, logWarning } from '../utils/logger.js';
 const WORKSPACE_DIR_NAME = 'edsger';
 /**
@@ -69,16 +70,10 @@ export function featureRepoExists(workspaceRoot, featureId) {
 export function cloneFeatureRepo(workspaceRoot, featureId, owner, repo, token) {
     const repoPath = getFeatureRepoPath(workspaceRoot, featureId);
     const repoUrl = `https://github.com/${owner}/${repo}.git`;
-    // Configure git to use token via credential helper (avoids token in URL / process list)
-    // First clear any existing credential helpers (e.g. osxkeychain) with an empty value,
-    // then set our custom helper. This ensures the token is used instead of stale keychain creds.
-    const credentialHelper = `!f() { echo "username=x-access-token"; echo "password=${token}"; }; f`;
-    const gitCredentialArgs = [
-        '-c',
-        'credential.helper=',
-        '-c',
-        `credential.helper=${credentialHelper}`,
-    ];
+    // Use the shared credential helper builder. Passes the installation
+    // token via `git -c credential.helper=...` so it stays out of the
+    // remote URL and the process list.
+    const gitCredentialArgs = buildCredentialArgs(token);
     // Check if already cloned
     if (existsSync(join(repoPath, '.git'))) {
         logInfo(`Reusing existing repo for feature ${featureId}`);
@@ -121,6 +116,97 @@ export function cloneFeatureRepo(workspaceRoot, featureId, owner, repo, token) {
         throw error;
     }
 }
+/**
+ * Loose validator for a git ref name (tag or branch) coming from callers
+ * that pass data originating from external sources (GitHub API, AI output).
+ *
+ * Rules match `git check-ref-format` plus a length cap. Rejecting bad
+ * input early keeps it out of execFileSync argv.
+ */
+export function isSafeGitRef(ref) {
+    if (typeof ref !== 'string') {
+        return false;
+    }
+    if (ref.length === 0 || ref.length > 100) {
+        return false;
+    }
+    if (/\s/.test(ref)) {
+        return false;
+    }
+    if (/^[-.]/.test(ref)) {
+        return false;
+    }
+    if (ref.includes('..') || ref.includes('@{')) {
+        return false;
+    }
+    return /^[A-Za-z0-9._\-+/@]+$/.test(ref);
+}
+/**
+ * Sync a cloned feature repo to a specific git ref — a tag or a branch.
+ *
+ * Behaviour:
+ * - `git fetch origin --tags --prune` brings in new tags (release tags!) and
+ *   drops deleted remote branches, using the installation-token credential
+ *   helper so private repos keep working.
+ * - Before switching refs, `git reset --hard HEAD` + `git clean -fd` drops
+ *   tracked-file edits and untracked files left by a prior run. We skip the
+ *   `-x` flag so `.gitignore`d content (node_modules, target, dist) survives
+ *   between runs — matches the convention in pull-request/creator.ts and
+ *   avoids an expensive reinstall every sync.
+ * - For a tag, detached-HEAD checkout of that tag.
+ * - For a branch, `checkout -B <branch> origin/<branch>` — force-updates
+ *   the local branch to the remote tip in one step, which also works on
+ *   the first sync when the local branch doesn't exist yet.
+ *
+ * This workspace is edsger-managed; callers should not put local work here.
+ */
+export function syncRepoToRef(repoPath, ref, token) {
+    if (!existsSync(join(repoPath, '.git'))) {
+        throw new Error(`Not a git repo: ${repoPath}`);
+    }
+    if (!ref.tag && !ref.branch) {
+        throw new Error('syncRepoToRef requires either tag or branch');
+    }
+    if (ref.tag && !isSafeGitRef(ref.tag)) {
+        throw new Error(`Unsafe tag ref: ${JSON.stringify(ref.tag)}`);
+    }
+    if (ref.branch && !isSafeGitRef(ref.branch)) {
+        throw new Error(`Unsafe branch ref: ${JSON.stringify(ref.branch)}`);
+    }
+    const creds = buildCredentialArgs(token);
+    try {
+        execFileSync('git', [...creds, 'fetch', 'origin', '--tags', '--prune'], { cwd: repoPath, stdio: 'pipe' });
+    }
+    catch {
+        logWarning('git fetch failed during sync; working tree may be stale');
+    }
+    // Discard any residual state from a previous run before switching refs.
+    // Use `-fd` (not `-fdx`) to preserve .gitignore'd build output / deps.
+    try {
+        execFileSync('git', ['reset', '--hard', 'HEAD'], {
+            cwd: repoPath,
+            stdio: 'pipe',
+        });
+        execFileSync('git', ['clean', '-fd'], { cwd: repoPath, stdio: 'pipe' });
+    }
+    catch {
+        // Non-fatal; subsequent checkout will surface any real issue.
+    }
+    try {
+        if (ref.tag) {
+            execFileSync('git', ['-c', 'advice.detachedHead=false', 'checkout', `refs/tags/${ref.tag}`], { cwd: repoPath, stdio: 'pipe' });
+            logInfo(`Checked out tag ${ref.tag}`);
+        }
+        else if (ref.branch) {
+            // Create-or-reset local branch to origin tip.
+            execFileSync('git', ['checkout', '-B', ref.branch, `origin/${ref.branch}`], { cwd: repoPath, stdio: 'pipe' });
+            logInfo(`Checked out branch ${ref.branch} at origin/${ref.branch}`);
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to checkout ${ref.tag ?? ref.branch}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
 /**
  * Set up a feature's repo for work (install deps, etc.)
  * This is called after cloning or reusing a repo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edsger",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "type": "module",
   "bin": {
     "edsger": "dist/index.js"

package/dist/services/lifecycle-agent/__tests__/phase-criteria.test.d.ts

@@ -1,4 +0,0 @@
-/**
- * Unit tests for phase quality criteria definitions
- */
-export {};