@dalzoubi/dev-agents-sync 1.0.1 → 1.0.3

package/tests/fetcher.test.mjs

@@ -1,1247 +1,1247 @@
-/**
- * tests/fetcher.test.mjs
- *
- * Failing tests for the real implementations of:
- *   - defaultGithubTagLister(repo, token, { httpClient })
- *   - defaultGithubFetcher(repo, tag, token, { httpClient, tarExtractor })
- *
- * No real network is used. All HTTP is stubbed via the injectable `httpClient`
- * seam. The `tarExtractor` seam is also injected so real tar decompression
- * is out of scope.
- *
- * These tests FAIL against the current stub implementation and PASS only
- * after the Implement agent wires up real logic.
- *
- * Target API (the Implement agent must match these signatures):
- *
- *   defaultGithubTagLister(repo, token, { httpClient })
- *     -> Promise<string[]>   bare semver strings, sorted newest-first
- *
- *   defaultGithubFetcher(repo, tag, token, { httpClient, tarExtractor })
- *     -> Promise<FileMap>    { [relativePath]: content }
- *     `tag` is bare semver e.g. "1.0.0" (no "v" prefix)
- */
-
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-
-import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import * as tar from 'tar';
-
-import {
-  defaultGithubTagLister,
-  defaultGithubFetcher,
-  defaultTarExtractor,
-  STUB_NOT_IMPLEMENTED,
-} from '../src/fetcher.mjs';
-
-// ---------------------------------------------------------------------------
-// Mock / helper factories
-// ---------------------------------------------------------------------------
-
-/**
- * Creates a minimal httpClient mock.
- *
- * `responses` is a Map<url-substring, responseShape> used to dispatch.
- * A responseShape is:
- *   { status, ok, jsonBody?, bufferBody?, headers? }
- *
- * The mock returns the first entry whose key is a substring of the requested URL.
- * If nothing matches, it throws to make test failures obvious.
- *
- * Signature mirrors the Fetch API:
- *   (url: string, init?: { headers?: object }) => Promise<Response-like>
- */
-function makeHttpClient(responses) {
-  return async function stubHttpClient(url, _init) {
-    for (const [key, shape] of Object.entries(responses)) {
-      if (url.includes(key)) {
-        return {
-          ok: shape.ok ?? (shape.status >= 200 && shape.status < 300),
-          status: shape.status ?? 200,
-          async json() {
-            return shape.jsonBody ?? null;
-          },
-          async arrayBuffer() {
-            const body = shape.bufferBody ?? new ArrayBuffer(0);
-            return body;
-          },
-          headers: {
-            get(name) {
-              return (shape.headers ?? {})[name.toLowerCase()] ?? null;
-            },
-          },
-        };
-      }
-    }
-    throw new Error(`stubHttpClient: no mock registered for URL: ${url}`);
-  };
-}
-
-/**
- * Creates a minimal tarExtractor mock.
- *
- * Returns a fixed FileMap for any buffer, simulating a tarball that contains
- * the provided entries.
- *
- * The entries object maps tar entry paths (as they appear inside the tarball)
- * to their string content.
- */
-function makeTarExtractor(entries) {
-  return async function stubTarExtractor(_buffer) {
-    return entries;
-  };
-}
-
-/** Builds a fake releases list response body matching the GitHub Releases API shape. */
-function makeReleasesBody(releases) {
-  // Each element: { tag_name, draft, prerelease, assets: [] }
-  return releases;
-}
-
-/** Builds a fake single-release response body with assets attached. */
-function makeReleaseBody({ tagName, assets = [] }) {
-  return {
-    tag_name: tagName,
-    draft: false,
-    prerelease: false,
-    assets,
-  };
-}
-
-/** Builds a fake asset descriptor as GitHub returns in the releases API. */
-function makeAsset({ name, url, size = 100 }) {
-  return { name, url, size };
-}
-
-// ---------------------------------------------------------------------------
-// Fixture data
-// ---------------------------------------------------------------------------
-
-const REPO = 'dalzoubi/dev-agents';
-const TOKEN = 'ghp_TESTTOKEN000000';
-
-// A tarball that contains a dist/ subtree as the implement agent should emit.
-// Keys mirror the tarball entry paths before the fetcher strips the dist/ prefix.
-const FAKE_TARBALL_ENTRIES = {
-  'dist/claude/agents/define.md': '# define agent',
-  'dist/claude/commands/preflight.md': '# preflight command',
-  'dist/cursor/rules/define.mdc': '# define rule',
-  // An entry outside dist/ — must be filtered out by the fetcher.
-  'README.md': '# should be ignored',
-  // A directory entry (no content) — must be skipped.
-  'dist/claude/agents/': '',
-};
-
-// The expected FileMap after path-rewriting: dist/ is stripped.
-const EXPECTED_FILE_MAP = {
-  'claude/agents/define.md': '# define agent',
-  'claude/commands/preflight.md': '# preflight command',
-  'cursor/rules/define.mdc': '# define rule',
-};
-
-// ---------------------------------------------------------------------------
-// defaultGithubTagLister — HTTP contract
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubTagLister — HTTP contract', () => {
-  it('calls GET /repos/<repo>/releases with Authorization Bearer header', async () => {
-    let capturedUrl = null;
-    let capturedInit = null;
-
-    const spyHttpClient = async (url, init) => {
-      capturedUrl = url;
-      capturedInit = init;
-      return {
-        ok: true,
-        status: 200,
-        async json() { return []; },
-        headers: { get: () => null },
-      };
-    };
-
-    await defaultGithubTagLister(REPO, TOKEN, { httpClient: spyHttpClient });
-
-    assert.ok(
-      capturedUrl !== null,
-      'httpClient must be called',
-    );
-    assert.ok(
-      capturedUrl.includes(`/repos/${REPO}/releases`),
-      `URL must include /repos/${REPO}/releases, got: ${capturedUrl}`,
-    );
-    const authHeader =
-      (capturedInit?.headers?.Authorization) ??
-      (capturedInit?.headers?.authorization);
-    assert.ok(
-      authHeader === `Bearer ${TOKEN}`,
-      `Authorization header must be "Bearer <token>", got: ${authHeader}`,
-    );
-  });
-
-  it('sends Accept: application/vnd.github+json', async () => {
-    let capturedInit = null;
-
-    const spyHttpClient = async (_url, init) => {
-      capturedInit = init;
-      return {
-        ok: true,
-        status: 200,
-        async json() { return []; },
-        headers: { get: () => null },
-      };
-    };
-
-    await defaultGithubTagLister(REPO, TOKEN, { httpClient: spyHttpClient });
-
-    const acceptHeader =
-      (capturedInit?.headers?.Accept) ??
-      (capturedInit?.headers?.accept);
-    assert.ok(
-      acceptHeader === 'application/vnd.github+json',
-      `Accept header must be "application/vnd.github+json", got: ${acceptHeader}`,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubTagLister — response parsing
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubTagLister — response parsing', () => {
-  it('returns bare semver strings (no "v" prefix)', async () => {
-    const releases = makeReleasesBody([
-      { tag_name: 'v1.2.3', draft: false, prerelease: false },
-      { tag_name: 'v1.0.0', draft: false, prerelease: false },
-    ]);
-
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
-    });
-
-    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-
-    for (const t of tags) {
-      assert.ok(
-        !t.startsWith('v'),
-        `tag must not start with "v", got: ${t}`,
-      );
-    }
-  });
-
-  it('filters out drafts', async () => {
-    const releases = makeReleasesBody([
-      { tag_name: 'v1.2.3', draft: false, prerelease: false },
-      { tag_name: 'v1.1.0', draft: true,  prerelease: false },
-    ]);
-
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
-    });
-
-    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-
-    assert.ok(!tags.includes('1.1.0'), 'draft release must be filtered out');
-    assert.ok(tags.includes('1.2.3'), '1.2.3 must be present');
-  });
-
-  it('filters out prereleases', async () => {
-    const releases = makeReleasesBody([
-      { tag_name: 'v2.0.0', draft: false, prerelease: false },
-      { tag_name: 'v2.0.0-beta.1', draft: false, prerelease: true },
-    ]);
-
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
-    });
-
-    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-
-    assert.ok(!tags.includes('2.0.0-beta.1'), 'prerelease must be filtered out');
-    assert.ok(tags.includes('2.0.0'), '2.0.0 must be present');
-  });
-
-  it('filters out tags that do not match ^v\\d+\\.\\d+\\.\\d+$ pattern', async () => {
-    const releases = makeReleasesBody([
-      { tag_name: 'v1.0.0',   draft: false, prerelease: false },
-      { tag_name: 'latest',   draft: false, prerelease: false },
-      { tag_name: 'v1.0.0-rc.1', draft: false, prerelease: false },
-      { tag_name: 'v1.0',     draft: false, prerelease: false },
-    ]);
-
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
-    });
-
-    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-
-    assert.ok(tags.includes('1.0.0'), '1.0.0 must be included');
-    assert.ok(!tags.includes('latest'), '"latest" must be excluded');
-    assert.ok(!tags.includes('1.0.0-rc.1'), 'rc tag must be excluded');
-    assert.ok(!tags.includes('1.0'), 'partial semver must be excluded');
-    assert.ok(!tags.includes('v1.0.0'), 'tags must not include "v" prefix');
-  });
-
-  it('sorts results descending by semver (newest first)', async () => {
-    const releases = makeReleasesBody([
-      { tag_name: 'v1.0.0', draft: false, prerelease: false },
-      { tag_name: 'v1.2.0', draft: false, prerelease: false },
-      { tag_name: 'v1.1.0', draft: false, prerelease: false },
-      { tag_name: 'v2.0.0', draft: false, prerelease: false },
-    ]);
-
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
-    });
-
-    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-
-    assert.deepEqual(
-      tags,
-      ['2.0.0', '1.2.0', '1.1.0', '1.0.0'],
-      'tags must be sorted descending by semver',
-    );
-  });
-
-  it('returns empty array when releases list is empty', async () => {
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: [] },
-    });
-
-    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-
-    assert.deepEqual(tags, [], 'empty releases must return []');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubTagLister — error handling
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubTagLister — error handling', () => {
-  it('throws AuthError-shaped error on 401 (mentions GITHUB_TOKEN)', async () => {
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 401, ok: false, jsonBody: { message: 'Requires authentication' } },
-    });
-
-    let thrown = null;
-    try {
-      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-    } catch (err) {
-      thrown = err;
-    }
-
-    assert.ok(thrown !== null, 'must throw on 401');
-    assert.ok(
-      thrown.message.includes('GITHUB_TOKEN'),
-      `error message must mention GITHUB_TOKEN, got: ${thrown.message}`,
-    );
-    assert.equal(thrown.exitCode, 2, 'exitCode must be 2 on auth error');
-  });
-
-  it('throws AuthError-shaped error on 401 (mentions gh auth login)', async () => {
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 401, ok: false, jsonBody: { message: 'Requires authentication' } },
-    });
-
-    let message = '';
-    try {
-      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-    } catch (err) {
-      message = err.message;
-    }
-
-    assert.ok(
-      message.includes('gh auth login'),
-      `error message must mention 'gh auth login', got: ${message}`,
-    );
-  });
-
-  it('throws AuthError-shaped error on 403', async () => {
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 403, ok: false, jsonBody: { message: 'Forbidden' } },
-    });
-
-    let thrown = null;
-    try {
-      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-    } catch (err) {
-      thrown = err;
-    }
-
-    assert.ok(thrown !== null, 'must throw on 403');
-    assert.equal(thrown.exitCode, 2, 'exitCode must be 2 on auth error');
-    assert.ok(
-      thrown.message.includes('GITHUB_TOKEN'),
-      'error message must mention GITHUB_TOKEN on 403',
-    );
-  });
-
-  it('throws on 5xx without STUB_NOT_IMPLEMENTED code', async () => {
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 503, ok: false, jsonBody: { message: 'Service unavailable' } },
-    });
-
-    let thrown = null;
-    try {
-      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-    } catch (err) {
-      thrown = err;
-    }
-
-    assert.ok(thrown !== null, 'must throw on 5xx');
-    assert.ok(
-      thrown.code !== STUB_NOT_IMPLEMENTED,
-      `5xx error must not use STUB_NOT_IMPLEMENTED code; code was: ${thrown.code}`,
-    );
-  });
-
-  it('token does not appear in error messages', async () => {
-    const httpClient = makeHttpClient({
-      [`/repos/${REPO}/releases`]: { status: 401, ok: false, jsonBody: { message: 'Requires authentication' } },
-    });
-
-    let message = '';
-    try {
-      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
-    } catch (err) {
-      message = err.message;
-    }
-
-    assert.ok(
-      !message.includes(TOKEN),
-      `error message must not contain the token, got: ${message}`,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubFetcher — HTTP contract
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubFetcher — HTTP contract', () => {
-  it('calls GET /repos/<repo>/releases/tags/v<tag>', async () => {
-    const TAG = '1.0.0';
-    let capturedReleaseUrl = null;
-
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const httpClient = async (url, init) => {
-      if (url.includes(`/releases/tags/v${TAG}`)) {
-        capturedReleaseUrl = url;
-        return {
-          ok: true,
-          status: 200,
-          async json() {
-            return makeReleaseBody({
-              tagName: `v${TAG}`,
-              assets: [
-                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://example.com/assets/dist.tar.gz' }),
-              ],
-            });
-          },
-          headers: { get: () => null },
-        };
-      }
-      if (url.includes('assets/dist.tar.gz')) {
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() { return new ArrayBuffer(8); },
-          headers: { get: () => null },
-        };
-      }
-      throw new Error(`stubHttpClient: unexpected URL ${url}`);
-    };
-
-    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-
-    assert.ok(
-      capturedReleaseUrl !== null,
-      'must call GET on the releases/tags endpoint',
-    );
-    assert.ok(
-      capturedReleaseUrl.includes(`/repos/${REPO}/releases/tags/v${TAG}`),
-      `URL must include /repos/${REPO}/releases/tags/v${TAG}, got: ${capturedReleaseUrl}`,
-    );
-  });
-
-  it('downloads the asset using Accept: application/octet-stream and bearer token', async () => {
-    const TAG = '1.0.0';
-    let capturedAssetInit = null;
-
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const httpClient = async (url, init) => {
-      if (url.includes(`/releases/tags/v${TAG}`)) {
-        return {
-          ok: true,
-          status: 200,
-          async json() {
-            return makeReleaseBody({
-              tagName: `v${TAG}`,
-              assets: [
-                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://example.com/assets/dist.tar.gz' }),
-              ],
-            });
-          },
-          headers: { get: () => null },
-        };
-      }
-      if (url.includes('assets/dist.tar.gz')) {
-        capturedAssetInit = init;
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() { return new ArrayBuffer(8); },
-          headers: { get: () => null },
-        };
-      }
-      throw new Error(`stubHttpClient: unexpected URL ${url}`);
-    };
-
-    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-
-    assert.ok(capturedAssetInit !== null, 'httpClient must be called for asset download');
-
-    const acceptHeader =
-      (capturedAssetInit?.headers?.Accept) ??
-      (capturedAssetInit?.headers?.accept);
-    assert.ok(
-      acceptHeader === 'application/octet-stream',
-      `asset download must use Accept: application/octet-stream, got: ${acceptHeader}`,
-    );
-
-    const authHeader =
-      (capturedAssetInit?.headers?.Authorization) ??
-      (capturedAssetInit?.headers?.authorization);
-    assert.ok(
-      authHeader === `Bearer ${TOKEN}`,
-      `asset download must include Authorization: Bearer <token>, got: ${authHeader}`,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubFetcher — asset resolution
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubFetcher — asset resolution', () => {
-  it('finds the asset named dist-v<tag>.tar.gz', async () => {
-    const TAG = '1.2.3';
-    let downloadedUrl = null;
-
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const httpClient = async (url, init) => {
-      if (url.includes(`/releases/tags/v${TAG}`)) {
-        return {
-          ok: true,
-          status: 200,
-          async json() {
-            return makeReleaseBody({
-              tagName: `v${TAG}`,
-              assets: [
-                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://example.com/assets/main.tar.gz' }),
-                makeAsset({ name: 'something-else.zip', url: 'https://example.com/assets/other.zip' }),
-              ],
-            });
-          },
-          headers: { get: () => null },
-        };
-      }
-      if (url.includes('assets/main.tar.gz')) {
-        downloadedUrl = url;
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() { return new ArrayBuffer(8); },
-          headers: { get: () => null },
-        };
-      }
-      throw new Error(`stubHttpClient: unexpected URL ${url}`);
-    };
-
-    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-
-    assert.ok(
-      downloadedUrl !== null && downloadedUrl.includes('assets/main.tar.gz'),
-      `must download the correct asset URL, got: ${downloadedUrl}`,
-    );
-  });
-
-  it('throws when the expected asset is absent (error mentions asset name)', async () => {
-    const TAG = '1.0.0';
-
-    const tarExtractor = makeTarExtractor({});
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 200,
-        jsonBody: makeReleaseBody({
-          tagName: `v${TAG}`,
-          assets: [
-            // Wrong asset name — the correct one is dist-v1.0.0.tar.gz
-            makeAsset({ name: 'wrong-asset.zip', url: 'https://example.com/assets/wrong.zip' }),
-          ],
-        }),
-      },
-    });
-
-    let thrown = null;
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      thrown = err;
-    }
-
-    assert.ok(thrown !== null, 'must throw when asset is absent');
-    assert.ok(
-      thrown.message.includes(`dist-v${TAG}.tar.gz`),
-      `error message must mention the missing asset name "dist-v${TAG}.tar.gz", got: ${thrown.message}`,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubFetcher — tarExtractor integration
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubFetcher — tarExtractor integration', () => {
-  /**
-   * Builds a standard happy-path httpClient for a given tag, returning a
-   * release with the dist tarball asset. The asset download returns an
-   * ArrayBuffer of 8 zero bytes (content doesn't matter for stub extraction).
-   */
-  function makeHappyHttpClient(tag) {
-    return async (url, _init) => {
-      if (url.includes(`/releases/tags/v${tag}`)) {
-        return {
-          ok: true,
-          status: 200,
-          async json() {
-            return makeReleaseBody({
-              tagName: `v${tag}`,
-              assets: [
-                makeAsset({ name: `dist-v${tag}.tar.gz`, url: 'https://example.com/assets/dist.tar.gz' }),
-              ],
-            });
-          },
-          headers: { get: () => null },
-        };
-      }
-      if (url.includes('assets/dist.tar.gz')) {
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() { return new ArrayBuffer(8); },
-          headers: { get: () => null },
-        };
-      }
-      throw new Error(`stubHttpClient: unexpected URL ${url}`);
-    };
-  }
-
-  it('calls tarExtractor with the downloaded buffer', async () => {
-    const TAG = '1.0.0';
-    let extractorWasCalled = false;
-
-    const tarExtractor = async (buffer) => {
-      extractorWasCalled = true;
-      assert.ok(buffer instanceof ArrayBuffer, 'tarExtractor must receive an ArrayBuffer');
-      return FAKE_TARBALL_ENTRIES;
-    };
-
-    await defaultGithubFetcher(REPO, TAG, TOKEN, {
-      httpClient: makeHappyHttpClient(TAG),
-      tarExtractor,
-    });
-
-    assert.ok(extractorWasCalled, 'tarExtractor must be called');
-  });
-
-  it('strips dist/ prefix from tarball entry paths', async () => {
-    const TAG = '1.0.0';
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
-      httpClient: makeHappyHttpClient(TAG),
-      tarExtractor,
-    });
-
-    for (const key of Object.keys(fileMap)) {
-      assert.ok(
-        !key.startsWith('dist/'),
-        `FileMap key must not start with "dist/", got: ${key}`,
-      );
-    }
-  });
-
-  it('includes expected keys after prefix rewriting', async () => {
-    const TAG = '1.0.0';
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
-      httpClient: makeHappyHttpClient(TAG),
-      tarExtractor,
-    });
-
-    assert.ok(
-      'claude/agents/define.md' in fileMap,
-      'FileMap must contain "claude/agents/define.md"',
-    );
-    assert.ok(
-      'cursor/rules/define.mdc' in fileMap,
-      'FileMap must contain "cursor/rules/define.mdc"',
-    );
-    assert.ok(
-      'claude/commands/preflight.md' in fileMap,
-      'FileMap must contain "claude/commands/preflight.md"',
-    );
-  });
-
-  it('excludes entries outside dist/', async () => {
-    const TAG = '1.0.0';
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
-      httpClient: makeHappyHttpClient(TAG),
-      tarExtractor,
-    });
-
-    assert.ok(
-      !('README.md' in fileMap),
-      'README.md (outside dist/) must not appear in FileMap',
-    );
-  });
-
-  it('skips directory entries (empty trailing slash)', async () => {
-    const TAG = '1.0.0';
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
-      httpClient: makeHappyHttpClient(TAG),
-      tarExtractor,
-    });
-
-    for (const key of Object.keys(fileMap)) {
-      assert.ok(
-        !key.endsWith('/'),
-        `FileMap must not contain directory entries (keys ending with "/"), got: ${key}`,
-      );
-    }
-  });
-
-  it('returns the correct file content', async () => {
-    const TAG = '1.0.0';
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
-      httpClient: makeHappyHttpClient(TAG),
-      tarExtractor,
-    });
-
-    assert.equal(
-      fileMap['claude/agents/define.md'],
-      FAKE_TARBALL_ENTRIES['dist/claude/agents/define.md'],
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubFetcher — sha256 sidecar verification (optional but preferred)
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubFetcher — sha256 sidecar verification', () => {
-  it('throws a mismatch error when sidecar hash does not match downloaded content', async () => {
-    const TAG = '1.0.0';
-
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    // Provide both a .tar.gz and a .sha256 asset, but give a wrong hash.
-    const httpClient = async (url, _init) => {
-      if (url.includes(`/releases/tags/v${TAG}`)) {
-        return {
-          ok: true,
-          status: 200,
-          async json() {
-            return makeReleaseBody({
-              tagName: `v${TAG}`,
-              assets: [
-                makeAsset({ name: `dist-v${TAG}.tar.gz`,     url: 'https://example.com/assets/dist.tar.gz' }),
-                makeAsset({ name: `dist-v${TAG}.tar.gz.sha256`, url: 'https://example.com/assets/dist.sha256' }),
-              ],
-            });
-          },
-          headers: { get: () => null },
-        };
-      }
-      if (url.includes('assets/dist.tar.gz')) {
-        return {
-          ok: true,
-          status: 200,
-          // Return 8 zero bytes as the tarball.
-          async arrayBuffer() { return new ArrayBuffer(8); },
-          headers: { get: () => null },
-        };
-      }
-      if (url.includes('assets/dist.sha256')) {
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() {
-            // A deliberately wrong sha256 hash (64 hex chars).
-            const badHash = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
-            const enc = new TextEncoder();
-            const buf = enc.encode(badHash);
-            return buf.buffer;
-          },
-          headers: { get: () => null },
-        };
-      }
-      throw new Error(`stubHttpClient: unexpected URL ${url}`);
-    };
-
-    let thrown = null;
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      thrown = err;
-    }
-
-    // If sha256 verification is implemented, it must throw here.
-    // The test may be skipped by the implementation returning the FileMap
-    // without verification only if the sidecar is genuinely absent — since
-    // it IS present in this test, a mismatch must throw.
-    assert.ok(
-      thrown !== null,
-      'must throw when sha256 sidecar is present and hash does not match',
-    );
-    assert.ok(
-      thrown.message.toLowerCase().includes('sha256') ||
-      thrown.message.toLowerCase().includes('checksum') ||
-      thrown.message.toLowerCase().includes('hash') ||
-      thrown.message.toLowerCase().includes('mismatch'),
-      `error message must mention sha256/checksum/hash/mismatch, got: ${thrown.message}`,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubFetcher — error handling
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubFetcher — error handling', () => {
-  it('throws on 404 with message mentioning the missing tag', async () => {
-    const TAG = '9.9.9';
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 404,
-        ok: false,
-        jsonBody: { message: 'Not Found' },
-      },
-    });
-
-    const tarExtractor = makeTarExtractor({});
-
-    let thrown = null;
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      thrown = err;
-    }
-
-    assert.ok(thrown !== null, 'must throw on 404');
-    assert.ok(
-      thrown.message.includes(TAG) || thrown.message.includes(`v${TAG}`),
-      `error message must mention the missing tag, got: ${thrown.message}`,
-    );
-  });
-
-  it('404 yields exitCode 2', async () => {
-    const TAG = '9.9.9';
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 404,
-        ok: false,
-        jsonBody: { message: 'Not Found' },
-      },
-    });
-
-    const tarExtractor = makeTarExtractor({});
-
-    let exitCode = null;
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      exitCode = err.exitCode;
-    }
-
-    assert.equal(exitCode, 2, '404 must yield exitCode 2');
-  });
-
-  it('404 does NOT use STUB_NOT_IMPLEMENTED error code', async () => {
-    const TAG = '9.9.9';
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 404,
-        ok: false,
-        jsonBody: { message: 'Not Found' },
-      },
-    });
-
-    const tarExtractor = makeTarExtractor({});
-
-    let code = null;
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      code = err.code;
-    }
-
-    assert.ok(
-      code !== STUB_NOT_IMPLEMENTED,
-      `404 error must not use STUB_NOT_IMPLEMENTED code; got: ${code}`,
-    );
-  });
-
-  it('throws AuthError-shaped error on 401 (exitCode 2, mentions GITHUB_TOKEN)', async () => {
-    const TAG = '1.0.0';
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 401,
-        ok: false,
-        jsonBody: { message: 'Requires authentication' },
-      },
-    });
-
-    const tarExtractor = makeTarExtractor({});
-
-    let thrown = null;
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      thrown = err;
-    }
-
-    assert.ok(thrown !== null, 'must throw on 401');
-    assert.equal(thrown.exitCode, 2, 'exitCode must be 2 on 401');
-    assert.ok(
-      thrown.message.includes('GITHUB_TOKEN'),
-      `error message must mention GITHUB_TOKEN on 401, got: ${thrown.message}`,
-    );
-  });
-
-  it('throws AuthError-shaped error on 403 (mentions gh auth login)', async () => {
-    const TAG = '1.0.0';
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 403,
-        ok: false,
-        jsonBody: { message: 'Forbidden' },
-      },
-    });
-
-    const tarExtractor = makeTarExtractor({});
-
-    let thrown = null;
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      thrown = err;
-    }
-
-    assert.ok(thrown !== null, 'must throw on 403');
-    assert.ok(
-      thrown.message.includes('gh auth login'),
-      `error message must mention 'gh auth login' on 403, got: ${thrown.message}`,
-    );
-  });
-
-  it('token never appears in error messages (404 case)', async () => {
-    const TAG = '9.9.9';
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 404,
-        ok: false,
-        jsonBody: { message: 'Not Found' },
-      },
-    });
-
-    const tarExtractor = makeTarExtractor({});
-
-    let message = '';
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      message = err.message;
-    }
-
-    assert.ok(
-      !message.includes(TOKEN),
-      `error message must not contain the token, got: ${message}`,
-    );
-  });
-
-  it('token never appears in error messages (401 case)', async () => {
-    const TAG = '1.0.0';
-
-    const httpClient = makeHttpClient({
-      [`/releases/tags/v${TAG}`]: {
-        status: 401,
-        ok: false,
-        jsonBody: { message: 'Requires authentication' },
-      },
-    });
-
-    const tarExtractor = makeTarExtractor({});
-
-    let message = '';
-    try {
-      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-    } catch (err) {
-      message = err.message;
-    }
-
-    assert.ok(
-      !message.includes(TOKEN),
-      `error message must not contain the token, got: ${message}`,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultGithubFetcher — redirect handling (auth stripping on hop 2)
-// ---------------------------------------------------------------------------
-
-describe('defaultGithubFetcher — redirect handling', () => {
-  it('strips Authorization header when following 302 from GitHub asset URL to S3', async () => {
-    const TAG = '1.0.0';
-    const S3_URL = 'https://s3.example/presigned/dist.tar.gz?sig=abc';
-    const calls = [];
-
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const httpClient = async (url, init) => {
-      calls.push({ url, init });
-      if (url.includes(`/releases/tags/v${TAG}`)) {
-        return {
-          ok: true,
-          status: 200,
-          async json() {
-            return makeReleaseBody({
-              tagName: `v${TAG}`,
-              assets: [
-                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://api.github.com/assets/123' }),
-              ],
-            });
-          },
-          headers: { get: () => null },
-        };
-      }
-      if (url === 'https://api.github.com/assets/123') {
-        return {
-          ok: false,
-          status: 302,
-          async arrayBuffer() { return new ArrayBuffer(0); },
-          headers: {
-            get(name) {
-              return name.toLowerCase() === 'location' ? S3_URL : null;
-            },
-          },
-        };
-      }
-      if (url === S3_URL) {
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() { return new ArrayBuffer(8); },
-          headers: { get: () => null },
-        };
-      }
-      throw new Error(`stubHttpClient: unexpected URL ${url}`);
-    };
-
-    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-
-    const s3Call = calls.find((c) => c.url === S3_URL);
-    assert.ok(s3Call, 'must issue a second request to the S3 redirect target');
-
-    const s3AuthHeader =
-      (s3Call.init?.headers?.Authorization) ??
-      (s3Call.init?.headers?.authorization);
-    assert.equal(
-      s3AuthHeader,
-      undefined,
-      `redirect hop must NOT include Authorization header, got: ${s3AuthHeader}`,
-    );
-
-    const s3Accept =
-      (s3Call.init?.headers?.Accept) ??
-      (s3Call.init?.headers?.accept);
-    assert.equal(
-      s3Accept,
-      'application/octet-stream',
-      `redirect hop must use Accept: application/octet-stream, got: ${s3Accept}`,
-    );
-
-    const serialized = JSON.stringify(s3Call.init ?? {});
-    assert.ok(
-      !serialized.includes(TOKEN),
-      `token must not appear in redirect hop init, got: ${serialized}`,
-    );
-
-    const firstAssetCall = calls.find((c) => c.url === 'https://api.github.com/assets/123');
-    assert.equal(
-      firstAssetCall.init?.redirect,
-      'manual',
-      'first asset hop must use redirect: manual',
-    );
-  });
-
-  it('strips Authorization header when following 302 from sidecar URL to S3', async () => {
-    const TAG = '1.0.0';
-    const SIDECAR_S3 = 'https://s3.example/presigned/dist.sha256?sig=def';
-    const TARBALL_S3 = 'https://s3.example/presigned/dist.tar.gz?sig=abc';
-    const calls = [];
-
-    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
-
-    const { createHash } = await import('node:crypto');
-    const correctHash = createHash('sha256').update(Buffer.alloc(8)).digest('hex');
-
-    const httpClient = async (url, init) => {
-      calls.push({ url, init });
-      if (url.includes(`/releases/tags/v${TAG}`)) {
-        return {
-          ok: true,
-          status: 200,
-          async json() {
-            return makeReleaseBody({
-              tagName: `v${TAG}`,
-              assets: [
-                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://api.github.com/assets/tar' }),
-                makeAsset({ name: `dist-v${TAG}.tar.gz.sha256`, url: 'https://api.github.com/assets/sha' }),
-              ],
-            });
-          },
-          headers: { get: () => null },
-        };
-      }
-      if (url === 'https://api.github.com/assets/tar') {
-        return {
-          ok: false,
-          status: 302,
-          async arrayBuffer() { return new ArrayBuffer(0); },
-          headers: {
-            get(name) {
-              return name.toLowerCase() === 'location' ? TARBALL_S3 : null;
-            },
-          },
-        };
-      }
-      if (url === TARBALL_S3) {
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() { return new ArrayBuffer(8); },
-          headers: { get: () => null },
-        };
-      }
-      if (url === 'https://api.github.com/assets/sha') {
-        return {
-          ok: false,
-          status: 302,
-          async arrayBuffer() { return new ArrayBuffer(0); },
-          headers: {
-            get(name) {
-              return name.toLowerCase() === 'location' ? SIDECAR_S3 : null;
-            },
-          },
-        };
-      }
-      if (url === SIDECAR_S3) {
-        const enc = new TextEncoder();
-        const buf = enc.encode(`${correctHash}  dist-v${TAG}.tar.gz\n`);
-        return {
-          ok: true,
-          status: 200,
-          async arrayBuffer() { return buf.buffer; },
-          headers: { get: () => null },
-        };
-      }
-      throw new Error(`stubHttpClient: unexpected URL ${url}`);
-    };
-
-    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
-
-    const sidecarS3Call = calls.find((c) => c.url === SIDECAR_S3);
-    assert.ok(sidecarS3Call, 'must issue a second request to the sidecar S3 URL');
-
-    const authHeader =
-      (sidecarS3Call.init?.headers?.Authorization) ??
-      (sidecarS3Call.init?.headers?.authorization);
-    assert.equal(
-      authHeader,
-      undefined,
-      `sidecar redirect hop must NOT include Authorization header, got: ${authHeader}`,
-    );
-
-    const serialized = JSON.stringify(sidecarS3Call.init ?? {});
-    assert.ok(
-      !serialized.includes(TOKEN),
-      `token must not appear in sidecar redirect hop init, got: ${serialized}`,
-    );
-  });
-});
-
-// ---------------------------------------------------------------------------
-// defaultTarExtractor — real extraction from an in-memory .tar.gz fixture
-// ---------------------------------------------------------------------------
-
-describe('defaultTarExtractor — real extraction', () => {
-  it('extracts a real .tar.gz buffer into a FileMap, skipping directories', async () => {
-    const tmp = await mkdtemp(join(tmpdir(), 'tar-fixture-'));
-    try {
-      await writeFile(join(tmp, 'a.md'), '# alpha\n', 'utf8');
-      await mkdir(join(tmp, 'nested'), { recursive: true });
-      await writeFile(join(tmp, 'nested', 'b.md'), '# beta\n', 'utf8');
-
-      const chunks = [];
-      const stream = tar.create(
-        { gzip: true, cwd: tmp, portable: true },
-        ['a.md', 'nested/b.md'],
-      );
-      for await (const chunk of stream) {
-        chunks.push(chunk);
-      }
-      const buffer = Buffer.concat(chunks);
-
-      const entries = await defaultTarExtractor(buffer);
-
-      assert.equal(entries['a.md'], '# alpha\n', 'a.md must be present with content');
-      assert.equal(
-        entries['nested/b.md'],
-        '# beta\n',
-        'nested/b.md must be present with content',
-      );
-
-      for (const key of Object.keys(entries)) {
-        assert.ok(
-          !key.endsWith('/'),
-          `extractor must skip directory entries, got: ${key}`,
-        );
-      }
-    } finally {
-      await rm(tmp, { recursive: true, force: true });
-    }
-  });
-});
+/**
+ * tests/fetcher.test.mjs
+ *
+ * Failing tests for the real implementations of:
+ *   - defaultGithubTagLister(repo, token, { httpClient })
+ *   - defaultGithubFetcher(repo, tag, token, { httpClient, tarExtractor })
+ *
+ * No real network is used. All HTTP is stubbed via the injectable `httpClient`
+ * seam. The `tarExtractor` seam is also injected so real tar decompression
+ * is out of scope.
+ *
+ * These tests FAIL against the current stub implementation and PASS only
+ * after the Implement agent wires up real logic.
+ *
+ * Target API (the Implement agent must match these signatures):
+ *
+ *   defaultGithubTagLister(repo, token, { httpClient })
+ *     -> Promise<string[]>   bare semver strings, sorted newest-first
+ *
+ *   defaultGithubFetcher(repo, tag, token, { httpClient, tarExtractor })
+ *     -> Promise<FileMap>    { [relativePath]: content }
+ *     `tag` is bare semver e.g. "1.0.0" (no "v" prefix)
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import * as tar from 'tar';
+
+import {
+  defaultGithubTagLister,
+  defaultGithubFetcher,
+  defaultTarExtractor,
+  STUB_NOT_IMPLEMENTED,
+} from '../src/fetcher.mjs';
+
+// ---------------------------------------------------------------------------
+// Mock / helper factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates a minimal httpClient mock.
+ *
+ * `responses` is a Map<url-substring, responseShape> used to dispatch.
+ * A responseShape is:
+ *   { status, ok, jsonBody?, bufferBody?, headers? }
+ *
+ * The mock returns the first entry whose key is a substring of the requested URL.
+ * If nothing matches, it throws to make test failures obvious.
+ *
+ * Signature mirrors the Fetch API:
+ *   (url: string, init?: { headers?: object }) => Promise<Response-like>
+ */
+function makeHttpClient(responses) {
+  return async function stubHttpClient(url, _init) {
+    for (const [key, shape] of Object.entries(responses)) {
+      if (url.includes(key)) {
+        return {
+          ok: shape.ok ?? (shape.status >= 200 && shape.status < 300),
+          status: shape.status ?? 200,
+          async json() {
+            return shape.jsonBody ?? null;
+          },
+          async arrayBuffer() {
+            const body = shape.bufferBody ?? new ArrayBuffer(0);
+            return body;
+          },
+          headers: {
+            get(name) {
+              return (shape.headers ?? {})[name.toLowerCase()] ?? null;
+            },
+          },
+        };
+      }
+    }
+    throw new Error(`stubHttpClient: no mock registered for URL: ${url}`);
+  };
+}
+
+/**
+ * Creates a minimal tarExtractor mock.
+ *
+ * Returns a fixed FileMap for any buffer, simulating a tarball that contains
+ * the provided entries.
+ *
+ * The entries object maps tar entry paths (as they appear inside the tarball)
+ * to their string content.
+ */
+function makeTarExtractor(entries) {
+  return async function stubTarExtractor(_buffer) {
+    return entries;
+  };
+}
+
+/** Builds a fake releases list response body matching the GitHub Releases API shape. */
+function makeReleasesBody(releases) {
+  // Each element: { tag_name, draft, prerelease, assets: [] }
+  return releases;
+}
+
+/** Builds a fake single-release response body with assets attached. */
+function makeReleaseBody({ tagName, assets = [] }) {
+  return {
+    tag_name: tagName,
+    draft: false,
+    prerelease: false,
+    assets,
+  };
+}
+
+/** Builds a fake asset descriptor as GitHub returns in the releases API. */
+function makeAsset({ name, url, size = 100 }) {
+  return { name, url, size };
+}
+
+// ---------------------------------------------------------------------------
+// Fixture data
+// ---------------------------------------------------------------------------
+
+const REPO = 'dalzoubi/dev-agents';
+const TOKEN = 'ghp_TESTTOKEN000000';
+
+// A tarball that contains a dist/ subtree as the implement agent should emit.
+// Keys mirror the tarball entry paths before the fetcher strips the dist/ prefix.
+const FAKE_TARBALL_ENTRIES = {
+  'dist/claude/agents/define.md': '# define agent',
+  'dist/claude/commands/preflight.md': '# preflight command',
+  'dist/cursor/rules/define.mdc': '# define rule',
+  // An entry outside dist/ — must be filtered out by the fetcher.
+  'README.md': '# should be ignored',
+  // A directory entry (no content) — must be skipped.
+  'dist/claude/agents/': '',
+};
+
+// The expected FileMap after path-rewriting: dist/ is stripped.
+const EXPECTED_FILE_MAP = {
+  'claude/agents/define.md': '# define agent',
+  'claude/commands/preflight.md': '# preflight command',
+  'cursor/rules/define.mdc': '# define rule',
+};
+
+// ---------------------------------------------------------------------------
+// defaultGithubTagLister — HTTP contract
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubTagLister — HTTP contract', () => {
+  it('calls GET /repos/<repo>/releases with Authorization Bearer header', async () => {
+    let capturedUrl = null;
+    let capturedInit = null;
+
+    const spyHttpClient = async (url, init) => {
+      capturedUrl = url;
+      capturedInit = init;
+      return {
+        ok: true,
+        status: 200,
+        async json() { return []; },
+        headers: { get: () => null },
+      };
+    };
+
+    await defaultGithubTagLister(REPO, TOKEN, { httpClient: spyHttpClient });
+
+    assert.ok(
+      capturedUrl !== null,
+      'httpClient must be called',
+    );
+    assert.ok(
+      capturedUrl.includes(`/repos/${REPO}/releases`),
+      `URL must include /repos/${REPO}/releases, got: ${capturedUrl}`,
+    );
+    const authHeader =
+      (capturedInit?.headers?.Authorization) ??
+      (capturedInit?.headers?.authorization);
+    assert.ok(
+      authHeader === `Bearer ${TOKEN}`,
+      `Authorization header must be "Bearer <token>", got: ${authHeader}`,
+    );
+  });
+
+  it('sends Accept: application/vnd.github+json', async () => {
+    let capturedInit = null;
+
+    const spyHttpClient = async (_url, init) => {
+      capturedInit = init;
+      return {
+        ok: true,
+        status: 200,
+        async json() { return []; },
+        headers: { get: () => null },
+      };
+    };
+
+    await defaultGithubTagLister(REPO, TOKEN, { httpClient: spyHttpClient });
+
+    const acceptHeader =
+      (capturedInit?.headers?.Accept) ??
+      (capturedInit?.headers?.accept);
+    assert.ok(
+      acceptHeader === 'application/vnd.github+json',
+      `Accept header must be "application/vnd.github+json", got: ${acceptHeader}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubTagLister — response parsing
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubTagLister — response parsing', () => {
+  it('returns bare semver strings (no "v" prefix)', async () => {
+    const releases = makeReleasesBody([
+      { tag_name: 'v1.2.3', draft: false, prerelease: false },
+      { tag_name: 'v1.0.0', draft: false, prerelease: false },
+    ]);
+
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
+    });
+
+    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+
+    for (const t of tags) {
+      assert.ok(
+        !t.startsWith('v'),
+        `tag must not start with "v", got: ${t}`,
+      );
+    }
+  });
+
+  it('filters out drafts', async () => {
+    const releases = makeReleasesBody([
+      { tag_name: 'v1.2.3', draft: false, prerelease: false },
+      { tag_name: 'v1.1.0', draft: true,  prerelease: false },
+    ]);
+
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
+    });
+
+    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+
+    assert.ok(!tags.includes('1.1.0'), 'draft release must be filtered out');
+    assert.ok(tags.includes('1.2.3'), '1.2.3 must be present');
+  });
+
+  it('filters out prereleases', async () => {
+    const releases = makeReleasesBody([
+      { tag_name: 'v2.0.0', draft: false, prerelease: false },
+      { tag_name: 'v2.0.0-beta.1', draft: false, prerelease: true },
+    ]);
+
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
+    });
+
+    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+
+    assert.ok(!tags.includes('2.0.0-beta.1'), 'prerelease must be filtered out');
+    assert.ok(tags.includes('2.0.0'), '2.0.0 must be present');
+  });
+
+  it('filters out tags that do not match ^v\\d+\\.\\d+\\.\\d+$ pattern', async () => {
+    const releases = makeReleasesBody([
+      { tag_name: 'v1.0.0',   draft: false, prerelease: false },
+      { tag_name: 'latest',   draft: false, prerelease: false },
+      { tag_name: 'v1.0.0-rc.1', draft: false, prerelease: false },
+      { tag_name: 'v1.0',     draft: false, prerelease: false },
+    ]);
+
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
+    });
+
+    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+
+    assert.ok(tags.includes('1.0.0'), '1.0.0 must be included');
+    assert.ok(!tags.includes('latest'), '"latest" must be excluded');
+    assert.ok(!tags.includes('1.0.0-rc.1'), 'rc tag must be excluded');
+    assert.ok(!tags.includes('1.0'), 'partial semver must be excluded');
+    assert.ok(!tags.includes('v1.0.0'), 'tags must not include "v" prefix');
+  });
+
+  it('sorts results descending by semver (newest first)', async () => {
+    const releases = makeReleasesBody([
+      { tag_name: 'v1.0.0', draft: false, prerelease: false },
+      { tag_name: 'v1.2.0', draft: false, prerelease: false },
+      { tag_name: 'v1.1.0', draft: false, prerelease: false },
+      { tag_name: 'v2.0.0', draft: false, prerelease: false },
+    ]);
+
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: releases },
+    });
+
+    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+
+    assert.deepEqual(
+      tags,
+      ['2.0.0', '1.2.0', '1.1.0', '1.0.0'],
+      'tags must be sorted descending by semver',
+    );
+  });
+
+  it('returns empty array when releases list is empty', async () => {
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 200, jsonBody: [] },
+    });
+
+    const tags = await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+
+    assert.deepEqual(tags, [], 'empty releases must return []');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubTagLister — error handling
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubTagLister — error handling', () => {
+  it('throws AuthError-shaped error on 401 (mentions GITHUB_TOKEN)', async () => {
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 401, ok: false, jsonBody: { message: 'Requires authentication' } },
+    });
+
+    let thrown = null;
+    try {
+      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+    } catch (err) {
+      thrown = err;
+    }
+
+    assert.ok(thrown !== null, 'must throw on 401');
+    assert.ok(
+      thrown.message.includes('GITHUB_TOKEN'),
+      `error message must mention GITHUB_TOKEN, got: ${thrown.message}`,
+    );
+    assert.equal(thrown.exitCode, 2, 'exitCode must be 2 on auth error');
+  });
+
+  it('throws AuthError-shaped error on 401 (mentions gh auth login)', async () => {
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 401, ok: false, jsonBody: { message: 'Requires authentication' } },
+    });
+
+    let message = '';
+    try {
+      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+    } catch (err) {
+      message = err.message;
+    }
+
+    assert.ok(
+      message.includes('gh auth login'),
+      `error message must mention 'gh auth login', got: ${message}`,
+    );
+  });
+
+  it('throws AuthError-shaped error on 403', async () => {
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 403, ok: false, jsonBody: { message: 'Forbidden' } },
+    });
+
+    let thrown = null;
+    try {
+      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+    } catch (err) {
+      thrown = err;
+    }
+
+    assert.ok(thrown !== null, 'must throw on 403');
+    assert.equal(thrown.exitCode, 2, 'exitCode must be 2 on auth error');
+    assert.ok(
+      thrown.message.includes('GITHUB_TOKEN'),
+      'error message must mention GITHUB_TOKEN on 403',
+    );
+  });
+
+  it('throws on 5xx without STUB_NOT_IMPLEMENTED code', async () => {
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 503, ok: false, jsonBody: { message: 'Service unavailable' } },
+    });
+
+    let thrown = null;
+    try {
+      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+    } catch (err) {
+      thrown = err;
+    }
+
+    assert.ok(thrown !== null, 'must throw on 5xx');
+    assert.ok(
+      thrown.code !== STUB_NOT_IMPLEMENTED,
+      `5xx error must not use STUB_NOT_IMPLEMENTED code; code was: ${thrown.code}`,
+    );
+  });
+
+  it('token does not appear in error messages', async () => {
+    const httpClient = makeHttpClient({
+      [`/repos/${REPO}/releases`]: { status: 401, ok: false, jsonBody: { message: 'Requires authentication' } },
+    });
+
+    let message = '';
+    try {
+      await defaultGithubTagLister(REPO, TOKEN, { httpClient });
+    } catch (err) {
+      message = err.message;
+    }
+
+    assert.ok(
+      !message.includes(TOKEN),
+      `error message must not contain the token, got: ${message}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubFetcher — HTTP contract
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubFetcher — HTTP contract', () => {
+  it('calls GET /repos/<repo>/releases/tags/v<tag>', async () => {
+    const TAG = '1.0.0';
+    let capturedReleaseUrl = null;
+
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const httpClient = async (url, init) => {
+      if (url.includes(`/releases/tags/v${TAG}`)) {
+        capturedReleaseUrl = url;
+        return {
+          ok: true,
+          status: 200,
+          async json() {
+            return makeReleaseBody({
+              tagName: `v${TAG}`,
+              assets: [
+                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://example.com/assets/dist.tar.gz' }),
+              ],
+            });
+          },
+          headers: { get: () => null },
+        };
+      }
+      if (url.includes('assets/dist.tar.gz')) {
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() { return new ArrayBuffer(8); },
+          headers: { get: () => null },
+        };
+      }
+      throw new Error(`stubHttpClient: unexpected URL ${url}`);
+    };
+
+    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+
+    assert.ok(
+      capturedReleaseUrl !== null,
+      'must call GET on the releases/tags endpoint',
+    );
+    assert.ok(
+      capturedReleaseUrl.includes(`/repos/${REPO}/releases/tags/v${TAG}`),
+      `URL must include /repos/${REPO}/releases/tags/v${TAG}, got: ${capturedReleaseUrl}`,
+    );
+  });
+
+  it('downloads the asset using Accept: application/octet-stream and bearer token', async () => {
+    const TAG = '1.0.0';
+    let capturedAssetInit = null;
+
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const httpClient = async (url, init) => {
+      if (url.includes(`/releases/tags/v${TAG}`)) {
+        return {
+          ok: true,
+          status: 200,
+          async json() {
+            return makeReleaseBody({
+              tagName: `v${TAG}`,
+              assets: [
+                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://example.com/assets/dist.tar.gz' }),
+              ],
+            });
+          },
+          headers: { get: () => null },
+        };
+      }
+      if (url.includes('assets/dist.tar.gz')) {
+        capturedAssetInit = init;
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() { return new ArrayBuffer(8); },
+          headers: { get: () => null },
+        };
+      }
+      throw new Error(`stubHttpClient: unexpected URL ${url}`);
+    };
+
+    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+
+    assert.ok(capturedAssetInit !== null, 'httpClient must be called for asset download');
+
+    const acceptHeader =
+      (capturedAssetInit?.headers?.Accept) ??
+      (capturedAssetInit?.headers?.accept);
+    assert.ok(
+      acceptHeader === 'application/octet-stream',
+      `asset download must use Accept: application/octet-stream, got: ${acceptHeader}`,
+    );
+
+    const authHeader =
+      (capturedAssetInit?.headers?.Authorization) ??
+      (capturedAssetInit?.headers?.authorization);
+    assert.ok(
+      authHeader === `Bearer ${TOKEN}`,
+      `asset download must include Authorization: Bearer <token>, got: ${authHeader}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubFetcher — asset resolution
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubFetcher — asset resolution', () => {
+  it('finds the asset named dist-v<tag>.tar.gz', async () => {
+    const TAG = '1.2.3';
+    let downloadedUrl = null;
+
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const httpClient = async (url, init) => {
+      if (url.includes(`/releases/tags/v${TAG}`)) {
+        return {
+          ok: true,
+          status: 200,
+          async json() {
+            return makeReleaseBody({
+              tagName: `v${TAG}`,
+              assets: [
+                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://example.com/assets/main.tar.gz' }),
+                makeAsset({ name: 'something-else.zip', url: 'https://example.com/assets/other.zip' }),
+              ],
+            });
+          },
+          headers: { get: () => null },
+        };
+      }
+      if (url.includes('assets/main.tar.gz')) {
+        downloadedUrl = url;
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() { return new ArrayBuffer(8); },
+          headers: { get: () => null },
+        };
+      }
+      throw new Error(`stubHttpClient: unexpected URL ${url}`);
+    };
+
+    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+
+    assert.ok(
+      downloadedUrl !== null && downloadedUrl.includes('assets/main.tar.gz'),
+      `must download the correct asset URL, got: ${downloadedUrl}`,
+    );
+  });
+
+  it('throws when the expected asset is absent (error mentions asset name)', async () => {
+    const TAG = '1.0.0';
+
+    const tarExtractor = makeTarExtractor({});
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 200,
+        jsonBody: makeReleaseBody({
+          tagName: `v${TAG}`,
+          assets: [
+            // Wrong asset name — the correct one is dist-v1.0.0.tar.gz
+            makeAsset({ name: 'wrong-asset.zip', url: 'https://example.com/assets/wrong.zip' }),
+          ],
+        }),
+      },
+    });
+
+    let thrown = null;
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      thrown = err;
+    }
+
+    assert.ok(thrown !== null, 'must throw when asset is absent');
+    assert.ok(
+      thrown.message.includes(`dist-v${TAG}.tar.gz`),
+      `error message must mention the missing asset name "dist-v${TAG}.tar.gz", got: ${thrown.message}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubFetcher — tarExtractor integration
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubFetcher — tarExtractor integration', () => {
+  /**
+   * Builds a standard happy-path httpClient for a given tag, returning a
+   * release with the dist tarball asset. The asset download returns an
+   * ArrayBuffer of 8 zero bytes (content doesn't matter for stub extraction).
+   */
+  function makeHappyHttpClient(tag) {
+    return async (url, _init) => {
+      if (url.includes(`/releases/tags/v${tag}`)) {
+        return {
+          ok: true,
+          status: 200,
+          async json() {
+            return makeReleaseBody({
+              tagName: `v${tag}`,
+              assets: [
+                makeAsset({ name: `dist-v${tag}.tar.gz`, url: 'https://example.com/assets/dist.tar.gz' }),
+              ],
+            });
+          },
+          headers: { get: () => null },
+        };
+      }
+      if (url.includes('assets/dist.tar.gz')) {
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() { return new ArrayBuffer(8); },
+          headers: { get: () => null },
+        };
+      }
+      throw new Error(`stubHttpClient: unexpected URL ${url}`);
+    };
+  }
+
+  it('calls tarExtractor with the downloaded buffer', async () => {
+    const TAG = '1.0.0';
+    let extractorWasCalled = false;
+
+    const tarExtractor = async (buffer) => {
+      extractorWasCalled = true;
+      assert.ok(buffer instanceof ArrayBuffer, 'tarExtractor must receive an ArrayBuffer');
+      return FAKE_TARBALL_ENTRIES;
+    };
+
+    await defaultGithubFetcher(REPO, TAG, TOKEN, {
+      httpClient: makeHappyHttpClient(TAG),
+      tarExtractor,
+    });
+
+    assert.ok(extractorWasCalled, 'tarExtractor must be called');
+  });
+
+  it('strips dist/ prefix from tarball entry paths', async () => {
+    const TAG = '1.0.0';
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
+      httpClient: makeHappyHttpClient(TAG),
+      tarExtractor,
+    });
+
+    for (const key of Object.keys(fileMap)) {
+      assert.ok(
+        !key.startsWith('dist/'),
+        `FileMap key must not start with "dist/", got: ${key}`,
+      );
+    }
+  });
+
+  it('includes expected keys after prefix rewriting', async () => {
+    const TAG = '1.0.0';
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
+      httpClient: makeHappyHttpClient(TAG),
+      tarExtractor,
+    });
+
+    assert.ok(
+      'claude/agents/define.md' in fileMap,
+      'FileMap must contain "claude/agents/define.md"',
+    );
+    assert.ok(
+      'cursor/rules/define.mdc' in fileMap,
+      'FileMap must contain "cursor/rules/define.mdc"',
+    );
+    assert.ok(
+      'claude/commands/preflight.md' in fileMap,
+      'FileMap must contain "claude/commands/preflight.md"',
+    );
+  });
+
+  it('excludes entries outside dist/', async () => {
+    const TAG = '1.0.0';
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
+      httpClient: makeHappyHttpClient(TAG),
+      tarExtractor,
+    });
+
+    assert.ok(
+      !('README.md' in fileMap),
+      'README.md (outside dist/) must not appear in FileMap',
+    );
+  });
+
+  it('skips directory entries (empty trailing slash)', async () => {
+    const TAG = '1.0.0';
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
+      httpClient: makeHappyHttpClient(TAG),
+      tarExtractor,
+    });
+
+    for (const key of Object.keys(fileMap)) {
+      assert.ok(
+        !key.endsWith('/'),
+        `FileMap must not contain directory entries (keys ending with "/"), got: ${key}`,
+      );
+    }
+  });
+
+  it('returns the correct file content', async () => {
+    const TAG = '1.0.0';
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const fileMap = await defaultGithubFetcher(REPO, TAG, TOKEN, {
+      httpClient: makeHappyHttpClient(TAG),
+      tarExtractor,
+    });
+
+    assert.equal(
+      fileMap['claude/agents/define.md'],
+      FAKE_TARBALL_ENTRIES['dist/claude/agents/define.md'],
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubFetcher — sha256 sidecar verification (optional but preferred)
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubFetcher — sha256 sidecar verification', () => {
+  it('throws a mismatch error when sidecar hash does not match downloaded content', async () => {
+    const TAG = '1.0.0';
+
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    // Provide both a .tar.gz and a .sha256 asset, but give a wrong hash.
+    const httpClient = async (url, _init) => {
+      if (url.includes(`/releases/tags/v${TAG}`)) {
+        return {
+          ok: true,
+          status: 200,
+          async json() {
+            return makeReleaseBody({
+              tagName: `v${TAG}`,
+              assets: [
+                makeAsset({ name: `dist-v${TAG}.tar.gz`,     url: 'https://example.com/assets/dist.tar.gz' }),
+                makeAsset({ name: `dist-v${TAG}.tar.gz.sha256`, url: 'https://example.com/assets/dist.sha256' }),
+              ],
+            });
+          },
+          headers: { get: () => null },
+        };
+      }
+      if (url.includes('assets/dist.tar.gz')) {
+        return {
+          ok: true,
+          status: 200,
+          // Return 8 zero bytes as the tarball.
+          async arrayBuffer() { return new ArrayBuffer(8); },
+          headers: { get: () => null },
+        };
+      }
+      if (url.includes('assets/dist.sha256')) {
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() {
+            // A deliberately wrong sha256 hash (64 hex chars).
+            const badHash = 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa';
+            const enc = new TextEncoder();
+            const buf = enc.encode(badHash);
+            return buf.buffer;
+          },
+          headers: { get: () => null },
+        };
+      }
+      throw new Error(`stubHttpClient: unexpected URL ${url}`);
+    };
+
+    let thrown = null;
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      thrown = err;
+    }
+
+    // If sha256 verification is implemented, it must throw here.
+    // The test may be skipped by the implementation returning the FileMap
+    // without verification only if the sidecar is genuinely absent — since
+    // it IS present in this test, a mismatch must throw.
+    assert.ok(
+      thrown !== null,
+      'must throw when sha256 sidecar is present and hash does not match',
+    );
+    assert.ok(
+      thrown.message.toLowerCase().includes('sha256') ||
+      thrown.message.toLowerCase().includes('checksum') ||
+      thrown.message.toLowerCase().includes('hash') ||
+      thrown.message.toLowerCase().includes('mismatch'),
+      `error message must mention sha256/checksum/hash/mismatch, got: ${thrown.message}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubFetcher — error handling
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubFetcher — error handling', () => {
+  it('throws on 404 with message mentioning the missing tag', async () => {
+    const TAG = '9.9.9';
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 404,
+        ok: false,
+        jsonBody: { message: 'Not Found' },
+      },
+    });
+
+    const tarExtractor = makeTarExtractor({});
+
+    let thrown = null;
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      thrown = err;
+    }
+
+    assert.ok(thrown !== null, 'must throw on 404');
+    assert.ok(
+      thrown.message.includes(TAG) || thrown.message.includes(`v${TAG}`),
+      `error message must mention the missing tag, got: ${thrown.message}`,
+    );
+  });
+
+  it('404 yields exitCode 2', async () => {
+    const TAG = '9.9.9';
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 404,
+        ok: false,
+        jsonBody: { message: 'Not Found' },
+      },
+    });
+
+    const tarExtractor = makeTarExtractor({});
+
+    let exitCode = null;
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      exitCode = err.exitCode;
+    }
+
+    assert.equal(exitCode, 2, '404 must yield exitCode 2');
+  });
+
+  it('404 does NOT use STUB_NOT_IMPLEMENTED error code', async () => {
+    const TAG = '9.9.9';
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 404,
+        ok: false,
+        jsonBody: { message: 'Not Found' },
+      },
+    });
+
+    const tarExtractor = makeTarExtractor({});
+
+    let code = null;
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      code = err.code;
+    }
+
+    assert.ok(
+      code !== STUB_NOT_IMPLEMENTED,
+      `404 error must not use STUB_NOT_IMPLEMENTED code; got: ${code}`,
+    );
+  });
+
+  it('throws AuthError-shaped error on 401 (exitCode 2, mentions GITHUB_TOKEN)', async () => {
+    const TAG = '1.0.0';
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 401,
+        ok: false,
+        jsonBody: { message: 'Requires authentication' },
+      },
+    });
+
+    const tarExtractor = makeTarExtractor({});
+
+    let thrown = null;
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      thrown = err;
+    }
+
+    assert.ok(thrown !== null, 'must throw on 401');
+    assert.equal(thrown.exitCode, 2, 'exitCode must be 2 on 401');
+    assert.ok(
+      thrown.message.includes('GITHUB_TOKEN'),
+      `error message must mention GITHUB_TOKEN on 401, got: ${thrown.message}`,
+    );
+  });
+
+  it('throws AuthError-shaped error on 403 (mentions gh auth login)', async () => {
+    const TAG = '1.0.0';
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 403,
+        ok: false,
+        jsonBody: { message: 'Forbidden' },
+      },
+    });
+
+    const tarExtractor = makeTarExtractor({});
+
+    let thrown = null;
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      thrown = err;
+    }
+
+    assert.ok(thrown !== null, 'must throw on 403');
+    assert.ok(
+      thrown.message.includes('gh auth login'),
+      `error message must mention 'gh auth login' on 403, got: ${thrown.message}`,
+    );
+  });
+
+  it('token never appears in error messages (404 case)', async () => {
+    const TAG = '9.9.9';
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 404,
+        ok: false,
+        jsonBody: { message: 'Not Found' },
+      },
+    });
+
+    const tarExtractor = makeTarExtractor({});
+
+    let message = '';
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      message = err.message;
+    }
+
+    assert.ok(
+      !message.includes(TOKEN),
+      `error message must not contain the token, got: ${message}`,
+    );
+  });
+
+  it('token never appears in error messages (401 case)', async () => {
+    const TAG = '1.0.0';
+
+    const httpClient = makeHttpClient({
+      [`/releases/tags/v${TAG}`]: {
+        status: 401,
+        ok: false,
+        jsonBody: { message: 'Requires authentication' },
+      },
+    });
+
+    const tarExtractor = makeTarExtractor({});
+
+    let message = '';
+    try {
+      await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+    } catch (err) {
+      message = err.message;
+    }
+
+    assert.ok(
+      !message.includes(TOKEN),
+      `error message must not contain the token, got: ${message}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultGithubFetcher — redirect handling (auth stripping on hop 2)
+// ---------------------------------------------------------------------------
+
+describe('defaultGithubFetcher — redirect handling', () => {
+  it('strips Authorization header when following 302 from GitHub asset URL to S3', async () => {
+    const TAG = '1.0.0';
+    const S3_URL = 'https://s3.example/presigned/dist.tar.gz?sig=abc';
+    const calls = [];
+
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const httpClient = async (url, init) => {
+      calls.push({ url, init });
+      if (url.includes(`/releases/tags/v${TAG}`)) {
+        return {
+          ok: true,
+          status: 200,
+          async json() {
+            return makeReleaseBody({
+              tagName: `v${TAG}`,
+              assets: [
+                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://api.github.com/assets/123' }),
+              ],
+            });
+          },
+          headers: { get: () => null },
+        };
+      }
+      if (url === 'https://api.github.com/assets/123') {
+        return {
+          ok: false,
+          status: 302,
+          async arrayBuffer() { return new ArrayBuffer(0); },
+          headers: {
+            get(name) {
+              return name.toLowerCase() === 'location' ? S3_URL : null;
+            },
+          },
+        };
+      }
+      if (url === S3_URL) {
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() { return new ArrayBuffer(8); },
+          headers: { get: () => null },
+        };
+      }
+      throw new Error(`stubHttpClient: unexpected URL ${url}`);
+    };
+
+    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+
+    const s3Call = calls.find((c) => c.url === S3_URL);
+    assert.ok(s3Call, 'must issue a second request to the S3 redirect target');
+
+    const s3AuthHeader =
+      (s3Call.init?.headers?.Authorization) ??
+      (s3Call.init?.headers?.authorization);
+    assert.equal(
+      s3AuthHeader,
+      undefined,
+      `redirect hop must NOT include Authorization header, got: ${s3AuthHeader}`,
+    );
+
+    const s3Accept =
+      (s3Call.init?.headers?.Accept) ??
+      (s3Call.init?.headers?.accept);
+    assert.equal(
+      s3Accept,
+      'application/octet-stream',
+      `redirect hop must use Accept: application/octet-stream, got: ${s3Accept}`,
+    );
+
+    const serialized = JSON.stringify(s3Call.init ?? {});
+    assert.ok(
+      !serialized.includes(TOKEN),
+      `token must not appear in redirect hop init, got: ${serialized}`,
+    );
+
+    const firstAssetCall = calls.find((c) => c.url === 'https://api.github.com/assets/123');
+    assert.equal(
+      firstAssetCall.init?.redirect,
+      'manual',
+      'first asset hop must use redirect: manual',
+    );
+  });
+
+  it('strips Authorization header when following 302 from sidecar URL to S3', async () => {
+    const TAG = '1.0.0';
+    const SIDECAR_S3 = 'https://s3.example/presigned/dist.sha256?sig=def';
+    const TARBALL_S3 = 'https://s3.example/presigned/dist.tar.gz?sig=abc';
+    const calls = [];
+
+    const tarExtractor = makeTarExtractor(FAKE_TARBALL_ENTRIES);
+
+    const { createHash } = await import('node:crypto');
+    const correctHash = createHash('sha256').update(Buffer.alloc(8)).digest('hex');
+
+    const httpClient = async (url, init) => {
+      calls.push({ url, init });
+      if (url.includes(`/releases/tags/v${TAG}`)) {
+        return {
+          ok: true,
+          status: 200,
+          async json() {
+            return makeReleaseBody({
+              tagName: `v${TAG}`,
+              assets: [
+                makeAsset({ name: `dist-v${TAG}.tar.gz`, url: 'https://api.github.com/assets/tar' }),
+                makeAsset({ name: `dist-v${TAG}.tar.gz.sha256`, url: 'https://api.github.com/assets/sha' }),
+              ],
+            });
+          },
+          headers: { get: () => null },
+        };
+      }
+      if (url === 'https://api.github.com/assets/tar') {
+        return {
+          ok: false,
+          status: 302,
+          async arrayBuffer() { return new ArrayBuffer(0); },
+          headers: {
+            get(name) {
+              return name.toLowerCase() === 'location' ? TARBALL_S3 : null;
+            },
+          },
+        };
+      }
+      if (url === TARBALL_S3) {
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() { return new ArrayBuffer(8); },
+          headers: { get: () => null },
+        };
+      }
+      if (url === 'https://api.github.com/assets/sha') {
+        return {
+          ok: false,
+          status: 302,
+          async arrayBuffer() { return new ArrayBuffer(0); },
+          headers: {
+            get(name) {
+              return name.toLowerCase() === 'location' ? SIDECAR_S3 : null;
+            },
+          },
+        };
+      }
+      if (url === SIDECAR_S3) {
+        const enc = new TextEncoder();
+        const buf = enc.encode(`${correctHash}  dist-v${TAG}.tar.gz\n`);
+        return {
+          ok: true,
+          status: 200,
+          async arrayBuffer() { return buf.buffer; },
+          headers: { get: () => null },
+        };
+      }
+      throw new Error(`stubHttpClient: unexpected URL ${url}`);
+    };
+
+    await defaultGithubFetcher(REPO, TAG, TOKEN, { httpClient, tarExtractor });
+
+    const sidecarS3Call = calls.find((c) => c.url === SIDECAR_S3);
+    assert.ok(sidecarS3Call, 'must issue a second request to the sidecar S3 URL');
+
+    const authHeader =
+      (sidecarS3Call.init?.headers?.Authorization) ??
+      (sidecarS3Call.init?.headers?.authorization);
+    assert.equal(
+      authHeader,
+      undefined,
+      `sidecar redirect hop must NOT include Authorization header, got: ${authHeader}`,
+    );
+
+    const serialized = JSON.stringify(sidecarS3Call.init ?? {});
+    assert.ok(
+      !serialized.includes(TOKEN),
+      `token must not appear in sidecar redirect hop init, got: ${serialized}`,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// defaultTarExtractor — real extraction from an in-memory .tar.gz fixture
+// ---------------------------------------------------------------------------
+
+describe('defaultTarExtractor — real extraction', () => {
+  it('extracts a real .tar.gz buffer into a FileMap, skipping directories', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'tar-fixture-'));
+    try {
+      await writeFile(join(tmp, 'a.md'), '# alpha\n', 'utf8');
+      await mkdir(join(tmp, 'nested'), { recursive: true });
+      await writeFile(join(tmp, 'nested', 'b.md'), '# beta\n', 'utf8');
+
+      const chunks = [];
+      const stream = tar.create(
+        { gzip: true, cwd: tmp, portable: true },
+        ['a.md', 'nested/b.md'],
+      );
+      for await (const chunk of stream) {
+        chunks.push(chunk);
+      }
+      const buffer = Buffer.concat(chunks);
+
+      const entries = await defaultTarExtractor(buffer);
+
+      assert.equal(entries['a.md'], '# alpha\n', 'a.md must be present with content');
+      assert.equal(
+        entries['nested/b.md'],
+        '# beta\n',
+        'nested/b.md must be present with content',
+      );
+
+      for (const key of Object.keys(entries)) {
+        assert.ok(
+          !key.endsWith('/'),
+          `extractor must skip directory entries, got: ${key}`,
+        );
+      }
+    } finally {
+      await rm(tmp, { recursive: true, force: true });
+    }
+  });
+});