@jens_astrup/release-manager 0.1.0-alpha.2

package/README.md

@@ -0,0 +1,95 @@
+# release-manager
+
+Interactive CLI for creating release version-bump PRs and full releases with AI-generated release notes. Built with [Ink](https://github.com/vadimdemedes/ink).
+
+Designed to be installed once and run from inside any project directory; per-project configuration is saved to `~/.config/release-manager/projects/` so each repo remembers its own build command, issue source (Linear or GitHub Issues), branch names, and OpenAI model.
+
+## Install
+
+```bash
+npm install -g release-manager
+```
+
+Or with `npx`:
+
+```bash
+npx release-manager
+```
+
+## Required environment variables
+
+These are read from the project's `.env.local` (if present) or from your shell:
+
+| Variable | When required |
+| --- | --- |
+| `GITHUB_TOKEN` | Always — used to open PRs and (optionally) read GitHub Issues |
+| `OPENAI_API_KEY` | When generating release notes or asking for a suggested bump |
+| `LINEAR_API_KEY` (or `LINEAR_API_TOKEN`) | When `issueSource` is `linear` |
+
+## Usage
+
+Run with no arguments inside a git project for the interactive menu:
+
+```bash
+cd ~/code/my-app
+release-manager
+```
+
+Or jump straight to an action:
+
+```bash
+release-manager bump          # version bump PR
+release-manager release       # develop → main release PR
+release-manager suggest       # AI-suggested bump
+release-manager config        # edit project settings
+release-manager --skip-build  # skip the build check during a bump
+release-manager --cwd ~/code/my-app
+```
+
+## Features
+
+1. **Version bump PR** — choose major / minor / patch / alpha / beta / specific version, or ask the AI to suggest one based on commits.
+2. **Release PR with AI notes** — pulls eligible issues from Linear or GitHub Issues, formats them into release notes, and opens a PR from `develop` → `main`.
+3. **Suggested bump** — analyzes commits between branches and recommends `major`, `minor`, or `patch`.
+4. **Specific version input** — type any valid semver (including prereleases like `2.0.0-rc.1`).
+5. **Configurable build check** — runs the configured command before bumping; can be skipped per run with `--skip-build` or by toggling in settings.
+6. **Per-project issue source** — each project chooses Linear or GitHub Issues independently.
+7. **Alpha / beta prereleases** — auto-increments existing prerelease tags (`1.2.4-alpha.0` → `1.2.4-alpha.1`).
+8. **Configurable build command** — defaults to `yarn build`; change in settings to `npm run build`, `pnpm build`, etc.
+9. **Per-project configuration** — keyed by absolute project path, stored centrally:
+
+   ```text
+   ~/.config/release-manager/projects/<sha256(projectDir)>.json
+   ```
+
+   Honors `XDG_CONFIG_HOME` if set.
+
+## Progress and errors
+
+- Long operations show a determinate progress bar where possible (build check, AI notes streaming) and a spinner everywhere else.
+- Errors are mapped to friendly panels with a short title, a plain-language message, and a hint for common cases (missing API key, dirty git tree, network failure, build failure). Build failures include the last 80 lines of build output.
+
+## Development
+
+```bash
+git clone <this repo>
+cd release-manager
+npm install
+npm run build
+node dist/bin/release-manager.js
+```
+
+Watch mode:
+
+```bash
+npm run dev
+```
+
+## Publishing
+
+```bash
+npm version patch   # or minor / major
+npm publish --access public
+```
+
+The `prepublishOnly` script runs `npm run build`, and only `dist/` and `README.md` ship in the package.

package/dist/bin/release-manager.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import React from 'react';
+import { render } from 'ink';
+import meow from 'meow';
+import { App } from '../src/app.js';
+const cli = meow(`
+  Usage
+    $ release-manager [command]
+
+  Commands
+    bump        Create a version bump PR (major/minor/patch/alpha/beta/explicit)
+    release     Create a release PR (develop -> main) with AI-generated notes
+    suggest     Get AI-suggested version bump type
+    config      View or edit per-project configuration
+    (default)   Open interactive menu
+
+  Options
+    --cwd       Project directory to operate on (default: current working directory)
+    --skip-build  Skip the build check during version bump
+    --version   Show version
+    --help      Show help
+
+  Examples
+    $ release-manager
+    $ release-manager bump
+    $ release-manager release
+    $ release-manager --cwd ~/code/spades
+  `, {
+    importMeta: import.meta,
+    flags: {
+        cwd: { type: 'string' },
+        skipBuild: { type: 'boolean', default: false }
+    }
+});
+const projectDir = cli.flags.cwd ? resolve(cli.flags.cwd) : process.cwd();
+const initialCommand = cli.input[0];
+render(React.createElement(App, {
+    projectDir,
+    initialCommand,
+    skipBuildFlag: cli.flags.skipBuild
+}));

package/dist/src/app.js

@@ -0,0 +1,98 @@
+import React, { useEffect, useState } from 'react';
+import { Box, Text, useApp, useInput } from 'ink';
+import Spinner from 'ink-spinner';
+import { ErrorPanel } from './components/ErrorPanel.js';
+import { Header } from './components/Header.js';
+import { toFriendlyError } from './errors.js';
+import { defaultConfig, loadOrInitConfig, saveConfig } from './lib/config.js';
+import { isGitRepo, inferGithubRepo } from './lib/git.js';
+import { BumpVersion } from './screens/BumpVersion.js';
+import { CreateRelease } from './screens/CreateRelease.js';
+import { MainMenu } from './screens/MainMenu.js';
+import { Settings } from './screens/Settings.js';
+import { SuggestBumpScreen } from './screens/SuggestBump.js';
+export function App({ projectDir, initialCommand, skipBuildFlag }) {
+    const { exit } = useApp();
+    const [loading, setLoading] = useState(true);
+    const [config, setConfig] = useState(null);
+    const [error, setError] = useState(null);
+    const [route, setRoute] = useState(initialCommand ?? 'menu');
+    // Allow Ctrl+C globally and a handy "q" shortcut from menu
+    useInput((input, key) => {
+        if (key.ctrl && input === 'c')
+            exit();
+    });
+    useEffect(() => {
+        let cancelled = false;
+        async function bootstrap() {
+            try {
+                if (!(await isGitRepo({ cwd: projectDir }))) {
+                    throw new Error('Not a git repository');
+                }
+                let cfg = await loadOrInitConfig(projectDir);
+                // First-run convenience: try to fill in repo owner/name from git remote
+                if (!cfg.github.owner || !cfg.github.repo) {
+                    const inferred = await inferGithubRepo({ cwd: projectDir });
+                    if (inferred) {
+                        cfg = {
+                            ...cfg,
+                            github: {
+                                ...cfg.github,
+                                owner: cfg.github.owner || inferred.owner,
+                                repo: cfg.github.repo || inferred.repo
+                            }
+                        };
+                        await saveConfig(cfg);
+                    }
+                }
+                if (!cancelled) {
+                    setConfig(cfg);
+                    setLoading(false);
+                }
+            }
+            catch (e) {
+                if (!cancelled) {
+                    setError(toFriendlyError(e));
+                    setLoading(false);
+                    // Provide a placeholder config so settings can still be edited
+                    setConfig(defaultConfig(projectDir));
+                }
+            }
+        }
+        void bootstrap();
+        return () => {
+            cancelled = true;
+        };
+    }, [projectDir]);
+    if (loading) {
+        return (React.createElement(Box, null,
+            React.createElement(Text, { color: "cyan" },
+                React.createElement(Spinner, { type: "dots" })),
+            React.createElement(Text, null, " Loading project config\u2026")));
+    }
+    if (error && route !== 'config') {
+        return (React.createElement(Box, { flexDirection: "column" },
+            React.createElement(ErrorPanel, { error: error }),
+            React.createElement(Box, { marginTop: 1 },
+                React.createElement(Text, { color: "gray" }, "Press Ctrl+C to quit, or run `release-manager config` to set up the project."))));
+    }
+    if (!config)
+        return null;
+    const handleMenu = (choice) => {
+        if (choice === 'quit') {
+            exit();
+            return;
+        }
+        setRoute(choice);
+    };
+    return (React.createElement(Box, { flexDirection: "column" },
+        React.createElement(Header, { config: config }),
+        route === 'menu' && React.createElement(MainMenu, { config: config, onSelect: handleMenu }),
+        route === 'bump' && (React.createElement(BumpVersion, { config: config, initialSkipBuild: skipBuildFlag, onDone: () => setRoute('menu') })),
+        route === 'release' && (React.createElement(CreateRelease, { config: config, onDone: () => setRoute('menu') })),
+        route === 'suggest' && (React.createElement(SuggestBumpScreen, { config: config, onDone: () => setRoute('menu') })),
+        route === 'config' && (React.createElement(Settings, { config: config, onSave: (c) => {
+                setConfig(c);
+                setRoute('menu');
+            }, onDone: () => setRoute('menu') }))));
+}

package/dist/src/components/ErrorPanel.js

@@ -0,0 +1,25 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+/**
+ * A bordered panel that displays a user-friendly error: short title, message,
+ * an optional remediation hint, and an optional collapsed detail (last lines
+ * of build output, stack trace) shown in dim text.
+ */
+export function ErrorPanel({ error }) {
+    return (React.createElement(Box, { flexDirection: "column", borderStyle: "round", borderColor: "red", paddingX: 1 },
+        React.createElement(Text, { color: "red", bold: true },
+            "\u2717 ",
+            error.title),
+        React.createElement(Text, null, error.message),
+        error.hint ? (React.createElement(Box, { marginTop: 1 },
+            React.createElement(Text, { color: "yellow" }, "Hint: "),
+            React.createElement(Text, null, error.hint))) : null,
+        error.detail ? (React.createElement(Box, { marginTop: 1, flexDirection: "column" },
+            React.createElement(Text, { color: "gray" }, "Details:"),
+            React.createElement(Text, { color: "gray" }, truncate(error.detail, 1200)))) : null));
+}
+function truncate(s, max) {
+    if (s.length <= max)
+        return s;
+    return s.slice(0, max) + '\n…(truncated)';
+}

package/dist/src/components/Header.js

@@ -0,0 +1,24 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+/**
+ * Top header: shows project name, repo, and branch targets.
+ */
+export function Header({ config }) {
+    const repo = config.github.owner && config.github.repo
+        ? `${config.github.owner}/${config.github.repo}`
+        : '(repo not configured)';
+    return (React.createElement(Box, { flexDirection: "column", marginBottom: 1 },
+        React.createElement(Box, null,
+            React.createElement(Text, { bold: true, color: "magenta" }, "release-manager"),
+            React.createElement(Text, { color: "gray" }, " \u00B7 "),
+            React.createElement(Text, null, config.name ?? config.projectDir)),
+        React.createElement(Box, null,
+            React.createElement(Text, { color: "gray" }, "repo: "),
+            React.createElement(Text, null, repo),
+            React.createElement(Text, { color: "gray" }, "  branches: "),
+            React.createElement(Text, null, config.github.developBranch),
+            React.createElement(Text, { color: "gray" }, " \u2192 "),
+            React.createElement(Text, null, config.github.mainBranch),
+            React.createElement(Text, { color: "gray" }, "  issues: "),
+            React.createElement(Text, null, config.issueSource))));
+}

package/dist/src/components/ProgressBar.js

@@ -0,0 +1,28 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+/**
+ * A simple horizontal progress bar. When `progress` is null/undefined we render
+ * a striped indeterminate state. The bar character is drawn with full-width
+ * blocks so it feels solid in modern terminals.
+ */
+export function ProgressBar({ progress, width = 30, label }) {
+    const indeterminate = progress === null || progress === undefined;
+    let filled = 0;
+    if (!indeterminate && typeof progress === 'number') {
+        filled = Math.max(0, Math.min(width, Math.round(progress * width)));
+    }
+    const bar = indeterminate
+        ? '─'.repeat(width)
+        : '█'.repeat(filled) + '░'.repeat(width - filled);
+    const pctText = indeterminate
+        ? '...'
+        : `${Math.round((progress ?? 0) * 100).toString().padStart(3, ' ')}%`;
+    return (React.createElement(Box, null,
+        React.createElement(Text, { color: indeterminate ? 'gray' : 'cyan' }, bar),
+        React.createElement(Text, null,
+            " ",
+            pctText),
+        label ? React.createElement(Text, { color: "gray" },
+            " ",
+            label) : null));
+}

package/dist/src/components/StepList.js

@@ -0,0 +1,28 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import Spinner from 'ink-spinner';
+import { ProgressBar } from './ProgressBar.js';
+/**
+ * Render a vertical list of steps. Running steps show a spinner; if a step
+ * exposes a numeric progress value, render a determinate progress bar beneath
+ * the label. Completed steps show a green check, failed steps show a red x,
+ * skipped steps show a gray dash.
+ */
+export function StepList({ steps }) {
+    return (React.createElement(Box, { flexDirection: "column" }, steps.map((step) => (React.createElement(Box, { key: step.id, flexDirection: "column", marginBottom: 0 },
+        React.createElement(Box, null,
+            React.createElement(Box, { width: 3 }, step.status === 'running' ? (React.createElement(Text, { color: "cyan" },
+                React.createElement(Spinner, { type: "dots" }))) : step.status === 'done' ? (React.createElement(Text, { color: "green" }, "\u2713")) : step.status === 'failed' ? (React.createElement(Text, { color: "red" }, "\u2717")) : step.status === 'skipped' ? (React.createElement(Text, { color: "gray" }, "\u2014")) : (React.createElement(Text, { color: "gray" }, "\u00B7"))),
+            React.createElement(Text, { color: step.status === 'failed'
+                    ? 'red'
+                    : step.status === 'done'
+                        ? 'green'
+                        : step.status === 'skipped'
+                            ? 'gray'
+                            : 'white' }, step.label),
+            step.detail ? React.createElement(Text, { color: "gray" },
+                "  ",
+                step.detail) : null),
+        step.status === 'running' && step.progress !== undefined ? (React.createElement(Box, { marginLeft: 3 },
+            React.createElement(ProgressBar, { progress: step.progress, width: 28 }))) : null)))));
+}

package/dist/src/errors.js

@@ -0,0 +1,63 @@
+/**
+ * Convert an unknown error into a user-friendly error object,
+ * adding hints for common cases (missing env vars, dirty git tree, network).
+ */
+export function toFriendlyError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    if (/working directory is not clean/i.test(raw)) {
+        return {
+            title: 'Uncommitted changes',
+            message: 'Your git working directory has uncommitted changes.',
+            hint: 'Commit or stash your changes, then try again.'
+        };
+    }
+    if (/LINEAR_API_(KEY|TOKEN)/i.test(raw)) {
+        return {
+            title: 'Linear API token missing',
+            message: 'No LINEAR_API_KEY or LINEAR_API_TOKEN is set.',
+            hint: 'Add it to your shell or to an .env.local file in the project directory, then re-run.'
+        };
+    }
+    if (/OPENAI_API_KEY/i.test(raw)) {
+        return {
+            title: 'OpenAI API key missing',
+            message: 'OPENAI_API_KEY is not set.',
+            hint: 'Add OPENAI_API_KEY to your shell or .env.local in the project directory.'
+        };
+    }
+    if (/GITHUB_TOKEN/i.test(raw)) {
+        return {
+            title: 'GitHub token missing',
+            message: 'GITHUB_TOKEN is not set.',
+            hint: 'Generate a personal access token with repo scope and add it to your shell or .env.local.'
+        };
+    }
+    if (/ENOTFOUND|ECONNREFUSED|getaddrinfo/i.test(raw)) {
+        return {
+            title: 'Network error',
+            message: 'Could not reach a remote service.',
+            hint: 'Check your internet connection and try again.',
+            detail: raw
+        };
+    }
+    if (/Build Failed|build failed/i.test(raw)) {
+        return {
+            title: 'Build failed',
+            message: 'The configured build command exited with an error.',
+            hint: 'Run the build manually to debug, or skip the build check during version bump.',
+            detail: raw
+        };
+    }
+    if (/not a git repository/i.test(raw)) {
+        return {
+            title: 'Not a git repository',
+            message: 'The project directory does not contain a git repository.',
+            hint: 'Run `git init` or change to a project that is under git source control.'
+        };
+    }
+    return {
+        title: 'Something went wrong',
+        message: raw,
+        detail: error instanceof Error && error.stack ? error.stack : undefined
+    };
+}

package/dist/src/lib/build.js

@@ -0,0 +1,54 @@
+import { execa } from 'execa';
+/**
+ * Run the configured build command, streaming progress updates by tracking
+ * the cumulative output line count against an exponential expectation curve.
+ * Throws an Error with `.detail` set to the last 80 lines on failure.
+ */
+export async function runBuildCheck(command, cwd, onProgress, signal) {
+    const [bin, ...args] = command.trim().split(/\s+/);
+    if (!bin) {
+        throw new Error('Build command is empty');
+    }
+    // Doppler-generated .env.local sets NODE_ENV=development, which can leak
+    // into Next.js builds. Force production for the build subprocess.
+    const { NODE_ENV: _ignored, ...envWithoutNodeEnv } = process.env;
+    const subprocess = execa(bin, args, {
+        cwd,
+        all: true,
+        env: { ...envWithoutNodeEnv, NODE_ENV: 'production' },
+        cancelSignal: signal
+    });
+    // Approximate progress: typical webpack/next builds emit ~150-400 lines.
+    // We map line count to progress with diminishing returns so the bar moves
+    // quickly at first and slows as we approach 95%, never hitting 100% until done.
+    const EXPECTED_LINES = 250;
+    let lineCount = 0;
+    let lastEmitted = -1;
+    const handleChunk = (chunk) => {
+        const text = typeof chunk === 'string' ? chunk : chunk.toString('utf-8');
+        const lines = text.split(/\r?\n/).filter(Boolean);
+        if (lines.length === 0)
+            return;
+        lineCount += lines.length;
+        const ratio = 1 - Math.exp(-lineCount / EXPECTED_LINES);
+        const progress = Math.min(0.95, ratio);
+        // Throttle to whole-percent changes
+        const pct = Math.floor(progress * 100);
+        if (pct !== lastEmitted) {
+            lastEmitted = pct;
+            onProgress({ progress, line: lines[lines.length - 1] ?? '' });
+        }
+    };
+    subprocess.all?.on('data', handleChunk);
+    try {
+        await subprocess;
+        onProgress({ progress: 1, line: 'Build complete' });
+    }
+    catch (error) {
+        const all = error.all ?? '';
+        const tail = all.split('\n').slice(-80).join('\n');
+        const friendly = new Error('Build Failed, release process aborted');
+        friendly.detail = tail;
+        throw friendly;
+    }
+}

package/dist/src/lib/config.js

@@ -0,0 +1,116 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, join } from 'node:path';
+/**
+ * Returns the root config directory for release-manager.
+ * Honors $XDG_CONFIG_HOME if set, otherwise uses ~/.config/release-manager.
+ */
+export function getConfigRoot() {
+    const xdg = process.env.XDG_CONFIG_HOME;
+    const base = xdg && xdg.length > 0 ? xdg : join(homedir(), '.config');
+    return join(base, 'release-manager');
+}
+function getProjectsDir() {
+    return join(getConfigRoot(), 'projects');
+}
+/**
+ * Compute a stable filename-safe id for a given absolute project directory.
+ * We use sha256 of the absolute path so different paths on different machines
+ * never collide, and so renamed paths get fresh configs.
+ */
+export function getProjectId(projectDir) {
+    return createHash('sha256').update(projectDir).digest('hex').slice(0, 16);
+}
+function getProjectConfigPath(projectDir) {
+    return join(getProjectsDir(), `${getProjectId(projectDir)}.json`);
+}
+/**
+ * Build a sensible default config for a new project.
+ * Repo owner/name are best-effort guesses; the user can override in the Settings screen.
+ */
+export function defaultConfig(projectDir) {
+    const now = new Date().toISOString();
+    return {
+        projectDir,
+        name: basename(projectDir),
+        buildCommand: 'yarn build',
+        buildCheckEnabled: true,
+        issueSource: 'linear',
+        github: {
+            owner: process.env.GITHUB_REPO_OWNER ?? '',
+            repo: process.env.GITHUB_REPO_NAME ?? basename(projectDir),
+            developBranch: 'develop',
+            mainBranch: 'main'
+        },
+        linear: {
+            readyForDeployStateId: '',
+            teamKey: ''
+        },
+        openaiModel: 'gpt-4o-mini',
+        createdAt: now,
+        updatedAt: now
+    };
+}
+/**
+ * Load the config for a project directory, or null if not yet configured.
+ */
+export async function loadConfig(projectDir) {
+    const path = getProjectConfigPath(projectDir);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = await readFile(path, 'utf-8');
+        const parsed = JSON.parse(raw);
+        // If the saved config drifted (older version), fill in defaults.
+        return { ...defaultConfig(projectDir), ...parsed, projectDir };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Persist a project config to disk. Creates the projects directory if needed.
+ */
+export async function saveConfig(config) {
+    const dir = getProjectsDir();
+    if (!existsSync(dir)) {
+        await mkdir(dir, { recursive: true });
+    }
+    const next = { ...config, updatedAt: new Date().toISOString() };
+    await writeFile(getProjectConfigPath(config.projectDir), JSON.stringify(next, null, 2), 'utf-8');
+}
+/**
+ * Load existing config or initialize and persist a default one.
+ */
+export async function loadOrInitConfig(projectDir) {
+    const existing = await loadConfig(projectDir);
+    if (existing)
+        return existing;
+    const fresh = defaultConfig(projectDir);
+    await saveConfig(fresh);
+    return fresh;
+}
+/**
+ * List all known project configs (used by potential future "list projects" UI).
+ */
+export async function listProjectConfigs() {
+    const dir = getProjectsDir();
+    if (!existsSync(dir))
+        return [];
+    const files = await readdir(dir);
+    const results = [];
+    for (const file of files) {
+        if (!file.endsWith('.json'))
+            continue;
+        try {
+            const raw = await readFile(join(dir, file), 'utf-8');
+            results.push(JSON.parse(raw));
+        }
+        catch {
+            // ignore corrupt entries
+        }
+    }
+    return results;
+}

package/dist/src/lib/env.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Best-effort .env.local loader. We avoid pulling in `dotenv` to keep the
+ * dependency surface tight; we only need a tiny KEY=VALUE parser.
+ *
+ * Values that are already set on process.env are NOT overridden.
+ */
+export function loadProjectEnv(projectDir) {
+    const envPath = join(projectDir, '.env.local');
+    if (!existsSync(envPath))
+        return;
+    const raw = readFileSync(envPath, 'utf-8');
+    for (const rawLine of raw.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        if (!(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+}
+/**
+ * Throw a descriptive error if a required env var is missing.
+ */
+export function requireEnv(name) {
+    const value = process.env[name];
+    if (!value || value.length === 0) {
+        throw new Error(`${name} environment variable is not set`);
+    }
+    return value;
+}