tlc-claude-code 2.5.0 → 2.6.0

package/server/lib/release/changelog-generator.test.js

@@ -0,0 +1,113 @@
+import { describe, it, expect, vi } from 'vitest';
+import changelogGenerator from './changelog-generator.js';
+
+const {
+  generateChangelog,
+  prependToChangelog,
+} = changelogGenerator;
+
+describe('changelog-generator', () => {
+  describe('generateChangelog', () => {
+    it('returns grouped markdown for conventional commits', () => {
+      const markdown = generateChangelog({
+        version: 'v1.2.3',
+        date: '2026-03-31',
+        commits: [
+          { sha: '1111111aaaa', message: 'fix: handle empty API payloads' },
+          { sha: '2222222bbbb', message: 'feat(auth): add SSO login flow' },
+          { sha: '3333333cccc', message: 'docs: update release runbook' },
+          { sha: '4444444dddd', message: 'cleanup old release notes' },
+        ],
+      });
+
+      expect(markdown).toContain('## v1.2.3 - 2026-03-31');
+      expect(markdown).toContain('### Features');
+      expect(markdown).toContain('- add SSO login flow (`2222222`)');
+      expect(markdown).toContain('### Fixes');
+      expect(markdown).toContain('- handle empty API payloads (`1111111`)');
+      expect(markdown).toContain('### Documentation');
+      expect(markdown).toContain('- update release runbook (`3333333`)');
+      expect(markdown).toContain('### Other');
+      expect(markdown).toContain('- cleanup old release notes (`4444444`)');
+    });
+
+    it('returns a fallback message when there are no commits', () => {
+      const markdown = generateChangelog({
+        version: 'v1.2.4',
+        date: '2026-03-31',
+        commits: [],
+      });
+
+      expect(markdown).toBe('## v1.2.4 - 2026-03-31\n\n- No changes recorded');
+    });
+
+    it('accepts string commits and omits missing shas', () => {
+      const markdown = generateChangelog({
+        version: 'v1.2.5',
+        commits: ['feat: add changelog endpoint', 'misc cleanup'],
+      });
+
+      expect(markdown).toContain('## v1.2.5');
+      expect(markdown).toContain('- add changelog endpoint');
+      expect(markdown).toContain('- misc cleanup');
+      expect(markdown).not.toContain('(`');
+    });
+  });
+
+  describe('prependToChangelog', () => {
+    it('prepends content below the changelog title when file already exists', () => {
+      const fs = {
+        readFileSync: vi.fn(() => '# Changelog\n\n## v1.2.2 - 2026-03-30\n\n- Previous entry\n'),
+        writeFileSync: vi.fn(),
+      };
+
+      const result = prependToChangelog({
+        changelogPath: '/tmp/CHANGELOG.md',
+        content: '## v1.2.3 - 2026-03-31\n\n- New entry',
+        fs,
+      });
+
+      expect(result).toBe(
+        '# Changelog\n\n## v1.2.3 - 2026-03-31\n\n- New entry\n\n## v1.2.2 - 2026-03-30\n\n- Previous entry\n'
+      );
+      expect(fs.writeFileSync).toHaveBeenCalledWith('/tmp/CHANGELOG.md', result, 'utf8');
+    });
+
+    it('creates a new changelog file when one does not exist', () => {
+      const fs = {
+        readFileSync: vi.fn(() => {
+          const error = new Error('missing');
+          error.code = 'ENOENT';
+          throw error;
+        }),
+        writeFileSync: vi.fn(),
+      };
+
+      const result = prependToChangelog({
+        changelogPath: '/tmp/CHANGELOG.md',
+        content: '## v1.2.3 - 2026-03-31\n\n- Initial entry',
+        fs,
+      });
+
+      expect(result).toBe('# Changelog\n\n## v1.2.3 - 2026-03-31\n\n- Initial entry\n');
+      expect(fs.writeFileSync).toHaveBeenCalledWith('/tmp/CHANGELOG.md', result, 'utf8');
+    });
+
+    it('prepends directly when the existing file has no top-level changelog title', () => {
+      const fs = {
+        readFileSync: vi.fn(() => '## v1.2.2 - 2026-03-30\n\n- Previous entry\n'),
+        writeFileSync: vi.fn(),
+      };
+
+      const result = prependToChangelog({
+        changelogPath: '/tmp/CHANGELOG.md',
+        content: '## v1.2.3 - 2026-03-31\n\n- New entry',
+        fs,
+      });
+
+      expect(result).toBe(
+        '## v1.2.3 - 2026-03-31\n\n- New entry\n\n## v1.2.2 - 2026-03-30\n\n- Previous entry\n'
+      );
+    });
+  });
+});

package/server/lib/release/ci-watcher.js

@@ -0,0 +1,83 @@
+/**
+ * Poll GitHub Actions runs for a branch until CI passes, fails, or no run is found.
+ *
+ * @param {Object} options
+ * @param {string} options.branch
+ * @param {number} [options.maxAttempts=3]
+ * @param {(command: string) => Promise<{stdout?: string}>} options.exec
+ * @returns {Promise<'green'|'failed'|'no_run'>}
+ */
+async function watchCi({ branch, maxAttempts = 3, exec }) {
+  if (!branch || typeof branch !== 'string') {
+    throw new Error('branch is required');
+  }
+
+  if (typeof exec !== 'function') {
+    throw new Error('exec is required');
+  }
+
+  const attempts = Number.isInteger(maxAttempts) && maxAttempts > 0 ? maxAttempts : 3;
+  let sawRun = false;
+
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const listResult = await exec(
+      `gh run list --branch ${shellQuote(branch)} --limit 1 --json databaseId,status,conclusion`,
+    );
+    const runs = parseJson(listResult && listResult.stdout, []);
+
+    if (!Array.isArray(runs) || runs.length === 0) {
+      continue;
+    }
+
+    sawRun = true;
+    const latestRun = runs[0];
+    const runId = latestRun.databaseId;
+
+    const viewResult = await exec(
+      `gh run view ${runId} --json status,conclusion`,
+    );
+    const run = parseJson(viewResult && viewResult.stdout, {});
+
+    if (run.conclusion === 'success') {
+      return 'green';
+    }
+
+    if (isFailedConclusion(run.conclusion)) {
+      return 'failed';
+    }
+
+    if (run.status === 'completed') {
+      return 'failed';
+    }
+  }
+
+  return sawRun ? 'failed' : 'no_run';
+}
+
+function parseJson(input, fallback) {
+  if (typeof input !== 'string' || input.trim() === '') {
+    return fallback;
+  }
+
+  return JSON.parse(input);
+}
+
+function isFailedConclusion(conclusion) {
+  return [
+    'failure',
+    'cancelled',
+    'timed_out',
+    'action_required',
+    'startup_failure',
+    'stale',
+    'skipped',
+  ].includes(conclusion);
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+module.exports = {
+  watchCi,
+};

package/server/lib/release/ci-watcher.test.js

@@ -0,0 +1,81 @@
+import { describe, expect, it, vi } from 'vitest';
+
+const { watchCi } = require('./ci-watcher.js');
+
+describe('ci-watcher', () => {
+  it('returns green when the latest run completes successfully', async () => {
+    const exec = vi.fn()
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify([
+          { databaseId: 101, status: 'completed', conclusion: 'success' },
+        ]),
+      })
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify({ status: 'completed', conclusion: 'success' }),
+      });
+
+    const result = await watchCi({ branch: 'main', maxAttempts: 2, exec });
+
+    expect(result).toBe('green');
+    expect(exec).toHaveBeenNthCalledWith(
+      1,
+      "gh run list --branch 'main' --limit 1 --json databaseId,status,conclusion",
+    );
+    expect(exec).toHaveBeenNthCalledWith(
+      2,
+      'gh run view 101 --json status,conclusion',
+    );
+  });
+
+  it('returns failed when the latest run completes unsuccessfully', async () => {
+    const exec = vi.fn()
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify([
+          { databaseId: 202, status: 'completed', conclusion: 'failure' },
+        ]),
+      })
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify({ status: 'completed', conclusion: 'failure' }),
+      });
+
+    const result = await watchCi({ branch: 'release/1.2.3', maxAttempts: 3, exec });
+
+    expect(result).toBe('failed');
+  });
+
+  it('returns no_run when no workflow runs are found after all attempts', async () => {
+    const exec = vi.fn().mockResolvedValue({
+      stdout: JSON.stringify([]),
+    });
+
+    const result = await watchCi({ branch: 'feature/missing-ci', maxAttempts: 2, exec });
+
+    expect(result).toBe('no_run');
+    expect(exec).toHaveBeenCalledTimes(2);
+  });
+
+  it('retries pending runs until they turn green', async () => {
+    const exec = vi.fn()
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify([
+          { databaseId: 303, status: 'in_progress', conclusion: '' },
+        ]),
+      })
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify({ status: 'in_progress', conclusion: '' }),
+      })
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify([
+          { databaseId: 303, status: 'completed', conclusion: 'success' },
+        ]),
+      })
+      .mockResolvedValueOnce({
+        stdout: JSON.stringify({ status: 'completed', conclusion: 'success' }),
+      });
+
+    const result = await watchCi({ branch: 'develop', maxAttempts: 3, exec });
+
+    expect(result).toBe('green');
+    expect(exec).toHaveBeenCalledTimes(4);
+  });
+});

package/server/lib/release/health-checker.js

@@ -0,0 +1,111 @@
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_RETRIES = 3;
+
+function toErrorMessage(error) {
+  if (!error) {
+    return 'Unknown health check failure';
+  }
+
+  if (typeof error === 'string') {
+    return error;
+  }
+
+  if (error.message) {
+    return error.message;
+  }
+
+  return 'Unknown health check failure';
+}
+
+async function checkHealth({
+  healthUrl,
+  timeout = DEFAULT_TIMEOUT_MS,
+  maxRetries = DEFAULT_MAX_RETRIES,
+  fetch,
+} = {}) {
+  if (!healthUrl) {
+    return {
+      ok: false,
+      attempts: 0,
+      status: null,
+      error: 'healthUrl is required',
+    };
+  }
+
+  if (typeof fetch !== 'function') {
+    throw new TypeError('fetch must be provided');
+  }
+
+  const maxAttempts = Math.max(1, Number(maxRetries) || 0);
+  let lastError = null;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    const controller = typeof AbortController === 'function' ? new AbortController() : null;
+    let timeoutId = null;
+
+    try {
+      if (controller && Number.isFinite(timeout) && timeout >= 0) {
+        timeoutId = setTimeout(() => {
+          const timeoutError = new Error(`Health check timed out after ${timeout}ms`);
+          timeoutError.name = 'AbortError';
+          controller.abort(timeoutError);
+        }, timeout);
+      }
+
+      const response = await fetch(healthUrl, controller ? { signal: controller.signal } : {});
+      const status = response && typeof response.status === 'number' ? response.status : null;
+
+      if (response && response.ok) {
+        return {
+          ok: true,
+          attempts: attempt,
+          status,
+          error: null,
+        };
+      }
+
+      lastError = new Error(`Health check failed with status ${status}`);
+    } catch (error) {
+      lastError = error;
+    } finally {
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+    }
+  }
+
+  return {
+    ok: false,
+    attempts: maxAttempts,
+    status: null,
+    error: toErrorMessage(lastError),
+  };
+}
+
+async function rollback({ branch, previousSha, exec } = {}) {
+  if (!branch) {
+    throw new Error('branch is required');
+  }
+
+  if (!previousSha) {
+    throw new Error('previousSha is required');
+  }
+
+  if (typeof exec !== 'function') {
+    throw new TypeError('exec must be provided');
+  }
+
+  await exec(`git checkout ${branch}`);
+  await exec(`git reset --hard ${previousSha}`);
+
+  return {
+    ok: true,
+    branch,
+    previousSha,
+  };
+}
+
+module.exports = {
+  checkHealth,
+  rollback,
+};

package/server/lib/release/health-checker.test.js

@@ -0,0 +1,121 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { checkHealth, rollback } = require('./health-checker.js');
+
+describe('release/health-checker', () => {
+  describe('checkHealth', () => {
+    it('returns an error result when healthUrl is missing', async () => {
+      const fetch = vi.fn();
+
+      const result = await checkHealth({ fetch });
+
+      expect(result).toEqual({
+        ok: false,
+        attempts: 0,
+        status: null,
+        error: 'healthUrl is required',
+      });
+      expect(fetch).not.toHaveBeenCalled();
+    });
+
+    it('retries failed responses until a later attempt succeeds', async () => {
+      const fetch = vi
+        .fn()
+        .mockResolvedValueOnce({ ok: false, status: 503 })
+        .mockResolvedValueOnce({ ok: false, status: 502 })
+        .mockResolvedValueOnce({ ok: true, status: 200 });
+
+      const result = await checkHealth({
+        healthUrl: 'https://release.example.com/health',
+        timeout: 100,
+        maxRetries: 3,
+        fetch,
+      });
+
+      expect(fetch).toHaveBeenCalledTimes(3);
+      expect(result).toEqual({
+        ok: true,
+        attempts: 3,
+        status: 200,
+        error: null,
+      });
+    });
+
+    it('retries thrown fetch errors and returns the final error message', async () => {
+      const fetch = vi.fn().mockRejectedValue(new Error('connection refused'));
+
+      const result = await checkHealth({
+        healthUrl: 'https://release.example.com/health',
+        timeout: 100,
+        maxRetries: 2,
+        fetch,
+      });
+
+      expect(fetch).toHaveBeenCalledTimes(2);
+      expect(result).toEqual({
+        ok: false,
+        attempts: 2,
+        status: null,
+        error: 'connection refused',
+      });
+    });
+
+    it('aborts a hanging request when the timeout is reached', async () => {
+      vi.useFakeTimers();
+
+      const fetch = vi.fn((_url, options = {}) => new Promise((_, reject) => {
+        options.signal.addEventListener('abort', () => {
+          reject(options.signal.reason || new Error('aborted'));
+        });
+      }));
+
+      const healthPromise = checkHealth({
+        healthUrl: 'https://release.example.com/health',
+        timeout: 50,
+        maxRetries: 1,
+        fetch,
+      });
+
+      await vi.advanceTimersByTimeAsync(50);
+      const result = await healthPromise;
+
+      expect(fetch).toHaveBeenCalledTimes(1);
+      expect(result.ok).toBe(false);
+      expect(result.attempts).toBe(1);
+      expect(result.error).toContain('timed out');
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('rollback', () => {
+    it('runs git checkout and reset using the injected exec', async () => {
+      const exec = vi.fn().mockResolvedValue(undefined);
+
+      const result = await rollback({
+        branch: 'main',
+        previousSha: 'abc123def456',
+        exec,
+      });
+
+      expect(exec).toHaveBeenNthCalledWith(1, 'git checkout main');
+      expect(exec).toHaveBeenNthCalledWith(2, 'git reset --hard abc123def456');
+      expect(result).toEqual({
+        ok: true,
+        branch: 'main',
+        previousSha: 'abc123def456',
+      });
+    });
+
+    it('throws when required rollback arguments are missing', async () => {
+      await expect(rollback({ previousSha: 'abc123', exec: vi.fn() })).rejects.toThrow(
+        'branch is required'
+      );
+      await expect(rollback({ branch: 'main', exec: vi.fn() })).rejects.toThrow(
+        'previousSha is required'
+      );
+    });
+  });
+});

package/server/lib/release/release-pipeline.js

@@ -0,0 +1,187 @@
+const fsp = require('node:fs/promises');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { watchCi } = require('./ci-watcher.js');
+const { determineNextVersion, applyVersionBump } = require('./version-bumper.js');
+const { generateChangelog, prependToChangelog } = require('./changelog-generator.js');
+const { checkHealth, rollback } = require('./health-checker.js');
+
+const COMPLETIONS_PATH = path.resolve(process.cwd(), '.tlc', '.agent-completions.json');
+
+async function runRelease({ branch, config, exec, fetch }) {
+  validateInputs({ branch, config, exec, fetch });
+
+  const packageJsonPath = path.resolve(process.cwd(), 'package.json');
+  const changelogPath = path.resolve(process.cwd(), 'CHANGELOG.md');
+  const previousSha = await getHeadSha(exec);
+  const ciStatus = await watchCi({ branch, exec });
+
+  if (ciStatus !== 'green') {
+    const result = {
+      ok: false,
+      status: 'stuck',
+      branch,
+      ciStatus,
+      summary: `Release halted because CI is ${ciStatus}`,
+    };
+    await writeCompletion(result);
+    return result;
+  }
+
+  const currentVersion = await readCurrentVersion(packageJsonPath);
+  const commits = await readCommits(exec);
+  const nextVersion = determineNextVersion({
+    currentVersion,
+    commits,
+  });
+  const changelog = generateChangelog({
+    version: `v${nextVersion}`,
+    date: new Date().toISOString().slice(0, 10),
+    commits,
+  });
+
+  await applyVersionBump({
+    version: nextVersion,
+    packageJsonPath,
+    fs: fsp,
+  });
+  prependToChangelog({
+    changelogPath,
+    content: changelog,
+    fs,
+  });
+
+  await exec(`git add ${shellQuote(packageJsonPath)} ${shellQuote(changelogPath)}`);
+  await exec(`git commit -m ${shellQuote(`chore(release): v${nextVersion}`)}`);
+  await exec(`git tag v${nextVersion}`);
+  await exec(`git push origin ${shellQuote(branch)}`);
+  await exec(`git push origin v${nextVersion}`);
+
+  let published = false;
+  if (config.publish && config.publish.npm) {
+    await exec('npm publish');
+    published = true;
+  }
+
+  const health = await checkHealth({
+    healthUrl: config.deploy.healthUrl,
+    fetch,
+  });
+
+  if (!health.ok) {
+    const rollbackResult = await rollback({
+      branch,
+      previousSha,
+      exec,
+    });
+    const result = {
+      ok: false,
+      status: 'rolled_back',
+      branch,
+      version: nextVersion,
+      ciStatus,
+      published,
+      health,
+      rollback: rollbackResult,
+      summary: `Release rolled back after failing health checks for v${nextVersion}`,
+    };
+    await writeCompletion(result);
+    return result;
+  }
+
+  const result = {
+    ok: true,
+    status: 'released',
+    branch,
+    version: nextVersion,
+    ciStatus,
+    published,
+    health,
+    summary: `Release completed for v${nextVersion}`,
+  };
+  await writeCompletion(result);
+  return result;
+}
+
+function validateInputs({ branch, config, exec, fetch }) {
+  if (!branch || typeof branch !== 'string') {
+    throw new Error('branch is required');
+  }
+
+  if (!config || typeof config !== 'object') {
+    throw new Error('config is required');
+  }
+
+  if (!config.deploy || !config.deploy.healthUrl) {
+    throw new Error('config.deploy.healthUrl is required');
+  }
+
+  if (typeof exec !== 'function') {
+    throw new TypeError('exec is required');
+  }
+
+  if (typeof fetch !== 'function') {
+    throw new TypeError('fetch is required');
+  }
+}
+
+async function getHeadSha(exec) {
+  const result = await exec('git rev-parse HEAD');
+  return String((result && result.stdout) || '').trim();
+}
+
+async function readCurrentVersion(packageJsonPath) {
+  const packageJson = await fsp.readFile(packageJsonPath, 'utf8');
+  const parsed = JSON.parse(packageJson);
+
+  if (!parsed.version || typeof parsed.version !== 'string') {
+    throw new Error('package.json version is required');
+  }
+
+  return parsed.version;
+}
+
+async function readCommits(exec) {
+  const result = await exec('git log -20 --pretty=format:%H%x09%s');
+  return String((result && result.stdout) || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [sha = '', message = ''] = line.split('\t');
+      return { sha, message };
+    });
+}
+
+async function writeCompletion(result) {
+  await fsp.mkdir(path.dirname(COMPLETIONS_PATH), { recursive: true });
+
+  let completions = [];
+  try {
+    const existing = await fsp.readFile(COMPLETIONS_PATH, 'utf8');
+    const parsed = JSON.parse(existing);
+    if (Array.isArray(parsed)) {
+      completions = parsed;
+    }
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  completions.push({
+    ...result,
+    completedAt: new Date().toISOString(),
+  });
+
+  await fsp.writeFile(COMPLETIONS_PATH, `${JSON.stringify(completions, null, 2)}\n`, 'utf8');
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+module.exports = {
+  runRelease,
+};