edsger 0.42.1 → 0.44.0

package/dist/phases/test-cases-analysis/index.js

@@ -6,7 +6,9 @@ import { executeTestCasesAnalysisQuery, parseAnalysisResult } from './agent.js';
 import { prepareTestCasesAnalysisContext } from './context.js';
 import { buildTestCasesAnalysisResult, deleteSpecificTestCases, deleteTestCaseArtifacts, getAllDraftTestCaseIds, resetReadyTestCasesToDraft, saveTestCasesAsDraft, updateTestCasesToReady, } from './outcome.js';
 import { createTestCasesAnalysisSystemPrompt } from './prompts.js';
-export const analyseTestCases = async (options, config, checklistContext) => {
+export const analyseTestCases = async (options, config, checklistContext
+// eslint-disable-next-line complexity
+) => {
     const { featureId, verbose } = options;
     if (verbose) {
         logInfo(`Starting test cases analysis for feature ID: ${featureId}`);

package/dist/phases/user-stories-analysis/index.js

@@ -6,7 +6,9 @@ import { executeUserStoriesAnalysisQuery, parseAnalysisResult, } from './agent.j
 import { prepareUserStoriesAnalysisContext } from './context.js';
 import { buildUserStoriesAnalysisResult, deleteSpecificUserStories, deleteUserStoryArtifacts, getAllDraftUserStoryIds, resetReadyUserStoriesToDraft, saveUserStoriesAsDraft, updateUserStoriesToReady, } from './outcome.js';
 import { createUserStoriesAnalysisSystemPrompt } from './prompts.js';
-export const analyseUserStories = async (options, config, checklistContext) => {
+export const analyseUserStories = async (options, config, checklistContext
+// eslint-disable-next-line complexity
+) => {
     const { featureId, verbose } = options;
     if (verbose) {
         logInfo(`Starting user stories analysis for feature ID: ${featureId}`);

package/dist/services/phase-hooks/__tests__/hook-executor.test.js

@@ -163,6 +163,7 @@ void describe('executeHook', () => {
     ) {
         // Return a function that returns an async iterable
         return () => ({
+            // eslint-disable-next-line @typescript-eslint/require-await
             async *[Symbol.asyncIterator]() {
                 for (const msg of messages) {
                     yield msg;
@@ -172,7 +173,7 @@ void describe('executeHook', () => {
     }
     function makeDeps(overrides = {}) {
         return {
-            loadSkillFile: async () => defaultSkillFile,
+            loadSkillFile: () => Promise.resolve(defaultSkillFile),
             queryFn: mockQuery([
                 {
                     type: 'result',
@@ -184,7 +185,7 @@ void describe('executeHook', () => {
         };
     }
     void it('returns skipped when skill file not found', async () => {
-        const deps = makeDeps({ loadSkillFile: async () => null });
+        const deps = makeDeps({ loadSkillFile: () => Promise.resolve(null) });
         const result = await executeHook(makeBinding(), makeContext(), false, deps);
         assert.strictEqual(result.status, 'skipped');
         assert.ok(result.message.includes('not found'));
@@ -266,7 +267,7 @@ void describe('executeHook', () => {
     void it('passes correct model and maxTurns from frontmatter', async () => {
         let capturedOptions = {};
         const deps = makeDeps({
-            loadSkillFile: async () => ({
+            loadSkillFile: () => Promise.resolve({
                 frontmatter: { model: 'haiku', maxTurns: 5 },
                 body: 'Test prompt',
             }),
@@ -274,6 +275,7 @@ void describe('executeHook', () => {
             queryFn: ((opts) => {
                 capturedOptions = opts.options;
                 return {
+                    // eslint-disable-next-line @typescript-eslint/require-await
                     async *[Symbol.asyncIterator]() {
                         yield {
                             type: 'result',
@@ -292,7 +294,7 @@ void describe('executeHook', () => {
     void it('uses DEFAULT_MODEL when frontmatter has no model', async () => {
         let capturedOptions = {};
         const deps = makeDeps({
-            loadSkillFile: async () => ({
+            loadSkillFile: () => Promise.resolve({
                 frontmatter: {},
                 body: 'Test prompt',
             }),
@@ -300,6 +302,7 @@ void describe('executeHook', () => {
             queryFn: ((opts) => {
                 capturedOptions = opts.options;
                 return {
+                    // eslint-disable-next-line @typescript-eslint/require-await
                     async *[Symbol.asyncIterator]() {
                         yield {
                             type: 'result',

package/dist/services/phase-hooks/__tests__/hook-runner.test.js

@@ -37,10 +37,10 @@ function makeContext(overrides = {}) {
 }
 function makeDeps(overrides = {}) {
     return {
-        executeHook: async (binding) => makeResult(binding),
+        executeHook: (binding) => Promise.resolve(makeResult(binding)),
         getCachedBindings: () => null,
         getBindingsForPhase: () => [],
-        logHookEvent: async () => { },
+        logHookEvent: () => Promise.resolve(),
         ...overrides,
     };
 }
@@ -86,9 +86,9 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [binding],
-            executeHook: async (b) => {
+            executeHook: (b) => {
                 executeCalls.push(b);
-                return makeResult(b);
+                return Promise.resolve(makeResult(b));
             },
         });
         const result = await runHooksForPhase(makeContext(), deps);
@@ -109,9 +109,9 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [b1, b2],
-            executeHook: async (b) => {
+            executeHook: (b) => {
                 order.push(b.id);
-                return makeResult(b);
+                return Promise.resolve(makeResult(b));
             },
         });
         await runHooksForPhase(makeContext(), deps);
@@ -133,15 +133,15 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [b1, b2],
-            executeHook: async (b) => {
+            executeHook: (b) => {
                 executedIds.push(b.id);
                 if (b.id === 'blocker') {
-                    return makeResult(b, {
+                    return Promise.resolve(makeResult(b, {
                         status: 'error',
                         message: 'Validation failed',
-                    });
+                    }));
                 }
-                return makeResult(b);
+                return Promise.resolve(makeResult(b));
             },
         });
         const result = await runHooksForPhase(makeContext(), deps);
@@ -165,14 +165,14 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [b1, b2],
-            executeHook: async (b) => {
+            executeHook: (b) => {
                 if (b.id === 'warner') {
-                    return makeResult(b, {
+                    return Promise.resolve(makeResult(b, {
                         status: 'error',
                         message: 'Non-critical issue',
-                    });
+                    }));
                 }
-                return makeResult(b);
+                return Promise.resolve(makeResult(b));
             },
         });
         const result = await runHooksForPhase(makeContext(), deps);
@@ -192,11 +192,11 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [b1, b2],
-            executeHook: async (b) => {
+            executeHook: (b) => {
                 if (b.id === 'skipper') {
-                    return makeResult(b, { status: 'error', message: 'Ignored' });
+                    return Promise.resolve(makeResult(b, { status: 'error', message: 'Ignored' }));
                 }
-                return makeResult(b);
+                return Promise.resolve(makeResult(b));
             },
         });
         const result = await runHooksForPhase(makeContext(), deps);
@@ -214,8 +214,9 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [binding],
-            logHookEvent: async ({ result: r }) => {
+            logHookEvent: ({ result: r }) => {
                 logCalls.push(r.hookId);
+                return Promise.resolve();
             },
         });
         await runHooksForPhase(makeContext(), deps);
@@ -231,8 +232,8 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [binding],
-            logHookEvent: async () => {
-                throw new Error('Logging failed');
+            logHookEvent: () => {
+                return Promise.reject(new Error('Logging failed'));
             },
         });
         const result = await runHooksForPhase(makeContext(), deps);
@@ -250,7 +251,7 @@ void describe('runHooksForPhase', () => {
         const deps = makeDeps({
             getCachedBindings: () => cached,
             getBindingsForPhase: () => [binding],
-            executeHook: async (b) => makeResult(b, { status: 'skipped', message: 'Not found' }),
+            executeHook: (b) => Promise.resolve(makeResult(b, { status: 'skipped', message: 'Not found' })),
         });
         const result = await runHooksForPhase(makeContext(), deps);
         // 'skipped' is not an error, so on_failure policy should not apply

package/dist/services/phase-hooks/hook-executor.js

@@ -94,6 +94,7 @@ export async function executeHook(binding, context, verbose, deps = defaultDeps)
             if (message.type === 'assistant') {
                 // eslint-disable-next-line @typescript-eslint/no-explicit-any
                 for (const item of (message.message?.content ?? [])) {
+                    // eslint-disable-next-line max-depth
                     if (item.type === 'text') {
                         resultText += item.text;
                     }

package/dist/services/phase-hooks/plugin-loader.js

@@ -96,10 +96,12 @@ async function findPluginRootForName(pluginName, cacheDir) {
             try {
                 const subEntries = await fs.readdir(entryDir, { withFileTypes: true });
                 for (const sub of subEntries) {
+                    // eslint-disable-next-line max-depth
                     if (!sub.isDirectory() || sub.name !== pluginName) {
                         continue;
                     }
                     const found = await findPluginRoot(path.join(entryDir, sub.name));
+                    // eslint-disable-next-line max-depth
                     if (found) {
                         return found;
                     }
@@ -116,6 +118,7 @@ async function findPluginRootForName(pluginName, cacheDir) {
                 try {
                     const manifestPath = path.join(root, '.claude-plugin', 'plugin.json');
                     const rawJson = JSON.parse(await fs.readFile(manifestPath, 'utf-8'));
+                    // eslint-disable-next-line max-depth
                     if (typeof rawJson === 'object' &&
                         rawJson !== null &&
                         rawJson.name === pluginName) {

package/dist/services/video/screenshot-generator.js

@@ -103,7 +103,10 @@ async function applyDeviceFrame(screenshotPath, scene, browser, verbose) {
  */
 export async function captureScreenshots(scenes, options, verbose) {
     await ensurePlaywright(isPlaywrightAvailable);
-    const chromium = (await loadChromium());
+    const chromium = await loadChromium();
+    if (!chromium) {
+        throw new Error('Failed to load chromium');
+    }
     const { baseUrl, outputDir, viewportWidth = 1280, viewportHeight = 720, fullPage = false, } = options;
     // Ensure output directory exists
     await mkdir(outputDir, { recursive: true });
@@ -194,7 +197,10 @@ export async function captureScreenshots(scenes, options, verbose) {
  */
 export async function captureStaticScreenshots(scenes, outputDir, htmlTemplates, verbose) {
     await ensurePlaywright(isPlaywrightAvailable);
-    const chromium = (await loadChromium());
+    const chromium = await loadChromium();
+    if (!chromium) {
+        throw new Error('Failed to load chromium');
+    }
     await mkdir(outputDir, { recursive: true });
     if (verbose) {
         logInfo(`Rendering ${scenes.length} static HTML scenes`);

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.42.1",
+  "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 {};