linear-github-cli 1.0.0

package/.env.example

@@ -0,0 +1,3 @@
+# Linear API Key
+# Get your API key from: https://linear.app/settings/api
+LINEAR_API_KEY=lin_api_...

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025 negoth
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+# Linear + GitHub CLI Tool
+
+A CLI tool for creating GitHub issues with Linear integration, providing an interactive experience with autocomplete and dropdown selections.
+
+## Installation
+
+### Option 1: Install from npm (Recommended)
+
+```bash
+npm install -g linear-github-cli
+```
+
+After installation, use `lg` or `linear-github` from anywhere:
+
+```bash
+lg create-parent
+lg create-sub
+lg --help
+```
+
+### Option 2: Install from Source
+
+```bash
+git clone <repository-url>
+cd linear-github-cli
+npm install
+npm install -g .
+```
+
+### Option 3: Development Mode
+
+```bash
+git clone <repository-url>
+cd linear-github-cli
+npm install
+npm run dev create-parent
+npm run dev create-sub
+```
+
+## Setup
+
+### 1. Install Dependencies (if installing from source)
+
+```bash
+npm install
+```
+
+### 2. Configure Environment Variables
+
+**Option 1: Using .env file (Recommended)**
+
+Create a `.env` file in the project root:
+
+```bash
+cp .env.example .env
+# Then edit .env and add your API key: LINEAR_API_KEY=lin_api_...
+```
+
+Or create it directly:
+
+```bash
+echo 'LINEAR_API_KEY=lin_api_...' > .env
+```
+
+**Option 2: Export in shell (Temporary)**
+
+```bash
+export LINEAR_API_KEY="lin_api_..."
+```
+
+**Get your Linear API key:**
+1. Go to [Linear Settings > API](https://linear.app/settings/api)
+2. Create a new Personal API Key
+3. Copy the key (starts with `lin_api_`)
+
+**Note:** The `.env` file is already in `.gitignore`, so it won't be committed to Git.
+
+### 3. Authenticate GitHub CLI
+
+```bash
+gh auth login
+gh auth status  # Verify
+```
+
+## Usage
+
+### Create Parent Issue
+
+```bash
+lg create-parent
+# or
+lg parent
+```
+
+Follow the interactive prompts:
+1. Select repository from dropdown
+2. Enter issue title
+3. Enter description (opens in editor)
+4. Optionally set due date (YYYY-MM-DD)
+5. Select GitHub labels (checkboxes). Choices: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `research`
+6. Optionally select GitHub project
+7. Optionally select Linear project (after sync)
+
+### Create Sub-Issue
+
+```bash
+lg create-sub
+# or
+lg sub
+```
+
+Follow the interactive prompts:
+1. Select repository from dropdown
+2. Select parent issue from list
+3. Enter sub-issue title
+4. Enter description (opens in editor)
+5. Optionally set due date (YYYY-MM-DD)
+6. Select GitHub labels (same predefined list as above)
+7. Optionally select Linear project (after sync)
+
+### Show Help
+
+```bash
+lg --help
+lg create-parent --help
+lg create-sub --help
+```
+
+## Features
+
+- ✅ **Interactive repository selection**: Choose from accessible GitHub repositories
+- ✅ **Project autocomplete**: Select GitHub and Linear projects from dropdowns
+- ✅ **Parent issue selection**: Browse and select parent issues when creating sub-issues
+- ✅ **GitHub label sync**: Multi-select from the seven standard labels (feat, fix, chore, docs, refactor, test, research); selections are mirrored to matching Linear team labels
+- ✅ **Due date input**: Optional date picker with validation
+- ✅ **Automatic Linear sync**: Waits for Linear sync and updates metadata (due date, project, labels)
+- ✅ **Parent-child relationships**: Automatically links sub-issues to parent issues
+- ✅ **Status automation**: Issues start in Linear backlog; rely on the Linear × GitHub PR automation for status changes
+
+## Examples
+
+### Basic Usage
+
+```bash
+# Create a parent issue
+lg create-parent
+
+# Create a sub-issue
+lg create-sub
+```
+
+### With Environment Variable
+
+```bash
+LINEAR_API_KEY="lin_api_..." lg create-parent
+```
+
+## Requirements
+
+- **Node.js** 18+ and npm
+- **GitHub CLI** (`gh`) installed and authenticated
+- **Linear API key** (get from [Linear Settings](https://linear.app/settings/api))
+
+## Building from Source
+
+```bash
+npm install
+npm run build
+```
+
+The compiled JavaScript will be in the `dist/` directory.
+
+## Troubleshooting
+
+### "LINEAR_API_KEY environment variable is required"
+
+Make sure you've set the environment variable:
+
+```bash
+export LINEAR_API_KEY="lin_api_..."
+```
+
+### "lg: command not found"
+
+If you installed globally, make sure npm's global bin directory is in your PATH:
+
+```bash
+# Check npm global prefix
+npm config get prefix
+
+# Add to PATH (macOS/Linux)
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+### "gh: command not found"
+
+Install GitHub CLI:
+- **macOS**: `brew install gh`
+- **Linux/Windows**: See [GitHub CLI installation](https://cli.github.com/manual/installation)
+
+### Repository list is empty
+
+Make sure you're authenticated:
+
+```bash
+gh auth status
+gh auth login  # if not authenticated
+```
+
+### Projects not showing
+
+GitHub Projects might not be available via CLI in all repositories. This is optional - you can skip project selection.
+
+### Linear issue not found after sync
+
+The tool waits 5 seconds for Linear sync. If the issue still isn't found:
+- Check Linear GitHub integration is enabled
+- Wait a bit longer and manually update metadata in Linear
+- The GitHub Actions workflow will also set metadata automatically
+
+## Architecture
+
+```
+lg (CLI)
+├── cli.ts                    # CLI entry point (Commander.js)
+├── commands/
+│   ├── create-parent.ts     # Parent issue command
+│   └── create-sub.ts        # Sub-issue command
+├── linear-client.ts          # Linear SDK wrapper
+├── github-client.ts          # GitHub CLI/API wrapper
+└── input-handler.ts          # Interactive prompts (Inquirer.js)
+```
+
+## Development
+
+### Run in Development Mode
+
+```bash
+npm run dev create-parent
+npm run dev create-sub
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+## Label Behaviour
+
+- The CLI surfaces the seven standard GitHub labels: `feat`, `fix`, `chore`, `docs`, `refactor`, `test`, `research`. (Custom GitHub labels can still be added manually after creation.)
+- When an issue syncs to Linear, the CLI ensures team-scoped Linear labels exist. New labels are created for the linked team if necessary and then attached to the issue.
+- Linear issues are always created in the backlog ("No status"). Move them forward by opening PRs and letting the Linear × GitHub integration handle status updates automatically.
+
+## Future Enhancements
+
+- Caching of repositories and projects
+- Configuration file for defaults
+- Better error handling and retry logic
+- Additional commands (list, update, close issues)
+- Template support for issue creation
+
+## PR Creation Workflow
+
+After creating issues with `lg`, use the Linear-GitHub integration workflow to manage PRs and track progress.
+
+### Recommended Approach: Aliases
+
+The simplest approach is to use `gh` aliases or interactive mode:
+
+```bash
+# Set up aliases (optional)
+gh alias set prd 'pr create --draft --title "$1" --body "solve: #$2"'
+gh alias set prms 'pr merge --squash --delete-branch'
+
+# Or use interactive mode (recommended)
+gh pr create --draft --fill
+gh pr ready  # Standard command, use directly when starting work
+gh prms      # Merge with squash and delete branch
+```
+
+### Workflow Overview
+
+1. **Create issue** - Use `lg parent/sub` command
+2. **Create branch** - Include issue number (e.g., `feat/LEA-123-task`)
+3. **Create draft PR** - Right after branch creation, before work begins
+   - Include Linear issue ID in title (copy with `Cmd + .` in Linear)
+   - Include `solve: #123` or `Closes #123` in body
+   - Linear status: `Todo`
+4. **Start work** - Begin actual development
+5. **Mark PR ready** - Use `gh pr ready` when ready for review
+   - Linear status: `In Progress`
+6. **Continue work** - More commits, add PR/issue comments for progress
+7. **Merge** - When task is complete
+   - Linear status: `Done`
+   - GitHub issue: Closed automatically
+
+### Two PR Types
+
+**Completing PRs (Issue Completion):**
+- Include Linear issue ID in title: `LEA-123 Implement login`
+- Use `solve: #123` or `Closes #123` in body
+- Merging sets Linear status to `Done` and closes GitHub issue
+
+**Partial Progress PRs (Non-Completing):**
+- Do NOT include Linear issue ID in title: `Add login form`
+- Use `Ref: #123` in body
+- Merging keeps Linear status unchanged and doesn't close GitHub issue
+- Useful for tracking incremental work on large issues
+
+### Linear Settings
+
+Configure Linear's GitHub integration:
+
+1. Linear Settings → Integrations → GitHub
+2. Open "Pull request and commit automations"
+3. Configure:
+   - **On draft PR open** → `Todo` ✅
+   - **On PR open (ready)** → `In Progress` ✅ (triggered by `gh pr ready`)
+   - **On PR review request** → `No Action`
+   - **On PR ready for merge** → `No Action`
+   - **On PR merge** → `Done` ✅
+
+### Additional Notes
+
+For branch name auto-extraction or more complex logic, you can create custom shell functions or use `gh pr create --fill` interactively, which allows you to manually enter the issue number.
+
+For most cases, aliases or `gh pr create --fill` are simpler and sufficient.
+
+### Documentation
+
+See `workflow.md` for complete workflow documentation, examples, and troubleshooting.
+
+## License
+
+ISC

package/dist/branch-utils.js

@@ -0,0 +1,270 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sanitizeBranchName = sanitizeBranchName;
+exports.selectBranchPrefix = selectBranchPrefix;
+exports.generateBranchName = generateBranchName;
+exports.extractLinearIssueId = extractLinearIssueId;
+exports.extractBranchPrefix = extractBranchPrefix;
+exports.checkUnpushedCommitsOnCurrentBranch = checkUnpushedCommitsOnCurrentBranch;
+exports.createGitBranch = createGitBranch;
+const child_process_1 = require("child_process");
+const inquirer_1 = __importDefault(require("inquirer"));
+/**
+ * Valid branch prefix types (must match commit_typed.sh)
+ */
+const VALID_BRANCH_PREFIXES = ['feat', 'fix', 'chore', 'docs', 'refactor', 'test', 'research'];
+/**
+ * Maps GitHub labels to branch prefix types
+ * Since GitHub labels are already updated to match the standard list,
+ * labels should directly map to branch prefixes.
+ * @param label - GitHub label name (should be one of: feat, fix, chore, docs, refactor, test, research)
+ * @returns Branch prefix (same as label if valid, otherwise returns label as-is)
+ */
+function mapLabelToBranchPrefix(label) {
+    const labelLower = label.toLowerCase();
+    // If label is already a valid branch prefix, return it as-is
+    if (VALID_BRANCH_PREFIXES.includes(labelLower)) {
+        return labelLower;
+    }
+    // Fallback: return label as-is (shouldn't happen if labels are properly configured)
+    return labelLower;
+}
+/**
+ * Sanitizes a title string to be used as part of a git branch name
+ * - Converts to lowercase
+ * - Replaces spaces with hyphens
+ * - Removes special characters (keeps alphanumeric and hyphens)
+ * - Removes leading/trailing hyphens
+ * - Collapses multiple consecutive hyphens
+ * - Limits length to 50 characters
+ *
+ * @param title - The title to sanitize
+ * @returns Sanitized branch name portion
+ */
+function sanitizeBranchName(title) {
+    if (!title || title.trim().length === 0) {
+        return '';
+    }
+    // Convert to lowercase and replace spaces with hyphens
+    let sanitized = title.toLowerCase().replace(/\s+/g, '-');
+    // Remove special characters except hyphens and alphanumeric
+    sanitized = sanitized.replace(/[^a-z0-9-]/g, '');
+    // Collapse multiple consecutive hyphens
+    sanitized = sanitized.replace(/-+/g, '-');
+    // Remove leading and trailing hyphens
+    sanitized = sanitized.replace(/^-+|-+$/g, '');
+    // Limit length to 50 characters
+    if (sanitized.length > 50) {
+        sanitized = sanitized.substring(0, 50);
+        // Remove trailing hyphen if truncated
+        sanitized = sanitized.replace(/-+$/, '');
+    }
+    return sanitized;
+}
+/**
+ * Standard branch prefix options when no labels are available
+ */
+const STANDARD_PREFIXES = [
+    { name: 'feat', value: 'feat' },
+    { name: 'fix', value: 'fix' },
+    { name: 'chore', value: 'chore' },
+    { name: 'docs', value: 'docs' },
+    { name: 'refactor', value: 'refactor' },
+    { name: 'test', value: 'test' },
+    { name: 'research', value: 'research' },
+];
+/**
+ * Selects a branch prefix from GitHub labels
+ * - If no labels: prompts user to select from standard prefixes
+ * - If one label: maps and returns branch prefix
+ * - If multiple labels: prompts user to select one
+ *
+ * @param labels - Array of GitHub label names
+ * @returns Branch prefix string or null if user cancels
+ */
+async function selectBranchPrefix(labels) {
+    // Map all labels to branch prefixes
+    const mappedPrefixes = labels && labels.length > 0
+        ? labels.map(label => ({
+            label,
+            prefix: mapLabelToBranchPrefix(label),
+        }))
+        : [];
+    // If no labels: prompt user to select from standard prefixes
+    if (mappedPrefixes.length === 0) {
+        const { selectedPrefix } = await inquirer_1.default.prompt([
+            {
+                type: 'list',
+                name: 'selectedPrefix',
+                message: 'Select branch prefix (no labels selected):',
+                choices: STANDARD_PREFIXES,
+            },
+        ]);
+        return selectedPrefix;
+    }
+    // If only one label, return its mapped prefix
+    if (mappedPrefixes.length === 1) {
+        return mappedPrefixes[0].prefix;
+    }
+    // Multiple labels: prompt user to select
+    const choices = mappedPrefixes.map(({ label, prefix }) => ({
+        name: `${label} → ${prefix}`,
+        value: prefix,
+    }));
+    const { selectedPrefix } = await inquirer_1.default.prompt([
+        {
+            type: 'list',
+            name: 'selectedPrefix',
+            message: 'Select branch prefix (multiple labels selected):',
+            choices,
+        },
+    ]);
+    return selectedPrefix;
+}
+/**
+ * Generates a branch name from prefix, Linear ID, and title
+ * Format: prefix/LinearID-sanitized-title
+ *
+ * @param prefix - Branch prefix (e.g., 'feat', 'docs')
+ * @param linearId - Linear issue ID (e.g., 'LEA-123')
+ * @param title - Issue title to sanitize
+ * @returns Full branch name
+ */
+function generateBranchName(prefix, linearId, title) {
+    const sanitizedTitle = sanitizeBranchName(title);
+    if (!sanitizedTitle) {
+        // If title is empty after sanitization, just use prefix and ID
+        return `${prefix}/${linearId}`;
+    }
+    return `${prefix}/${linearId}-${sanitizedTitle}`;
+}
+/**
+ * Extracts Linear issue ID from a branch name
+ * - Matches pattern: prefix/LEA-123-title or prefix/LEA-123
+ * - Uses regex to find Linear issue ID format: [A-Z]+-\d+
+ *
+ * @param branchName - Branch name (e.g., 'feat/LEA-123-implement-login')
+ * @returns Linear issue ID (e.g., 'LEA-123') or null if not found
+ */
+function extractLinearIssueId(branchName) {
+    if (!branchName || branchName.trim().length === 0) {
+        return null;
+    }
+    // Match Linear issue ID pattern: [A-Z]+-\d+ (e.g., LEA-123)
+    const match = branchName.match(/([A-Z]+-\d+)/);
+    return match ? match[1] : null;
+}
+/**
+ * Extracts branch prefix (commit type) from a branch name
+ * - Extracts the part before the first '/' (e.g., 'research' from 'research/LEA-75-probit-model')
+ * - Validates against VALID_BRANCH_PREFIXES
+ * - Returns 'feat' as default if prefix is not found or invalid
+ *
+ * @param branchName - Branch name (e.g., 'research/LEA-75-probit-model')
+ * @returns Branch prefix (e.g., 'research') or 'feat' as default
+ */
+function extractBranchPrefix(branchName) {
+    if (!branchName || branchName.trim().length === 0) {
+        return 'feat';
+    }
+    // Extract prefix before first '/'
+    const parts = branchName.split('/');
+    if (parts.length === 0 || !parts[0]) {
+        return 'feat';
+    }
+    const prefix = parts[0].toLowerCase();
+    // Validate against valid prefixes
+    if (VALID_BRANCH_PREFIXES.includes(prefix)) {
+        return prefix;
+    }
+    // Return 'feat' as default if prefix is invalid
+    return 'feat';
+}
+/**
+ * Checks for unpushed commits on the current branch
+ * - Gets current branch name
+ * - Checks if remote branch exists
+ * - Counts unpushed commits
+ * - Returns information about unpushed commits
+ *
+ * @returns Object with hasUnpushed flag, count, and commit list
+ */
+function checkUnpushedCommitsOnCurrentBranch() {
+    try {
+        // Check if we're in a git repository
+        try {
+            (0, child_process_1.execSync)('git rev-parse --git-dir', { stdio: 'pipe' });
+        }
+        catch (error) {
+            // Not in a git repository, return no unpushed commits
+            return { hasUnpushed: false, count: 0, commits: [] };
+        }
+        // Get current branch
+        const currentBranch = (0, child_process_1.execSync)('git branch --show-current', { encoding: 'utf-8' }).trim();
+        if (!currentBranch) {
+            return { hasUnpushed: false, count: 0, commits: [] };
+        }
+        // Check if remote branch exists
+        try {
+            (0, child_process_1.execSync)(`git rev-parse --verify origin/${currentBranch}`, { stdio: 'pipe' });
+        }
+        catch (error) {
+            // Remote branch doesn't exist, no unpushed commits
+            return { hasUnpushed: false, count: 0, commits: [] };
+        }
+        // Count unpushed commits
+        const countOutput = (0, child_process_1.execSync)(`git rev-list --count origin/${currentBranch}..${currentBranch}`, { encoding: 'utf-8' }).trim();
+        const count = parseInt(countOutput, 10) || 0;
+        if (count === 0) {
+            return { hasUnpushed: false, count: 0, commits: [] };
+        }
+        // Get commit list
+        const commitsOutput = (0, child_process_1.execSync)(`git log origin/${currentBranch}..${currentBranch} --oneline`, { encoding: 'utf-8' }).trim();
+        const commits = commitsOutput ? commitsOutput.split('\n') : [];
+        return { hasUnpushed: true, count, commits };
+    }
+    catch (error) {
+        // On error, assume no unpushed commits to avoid blocking workflow
+        return { hasUnpushed: false, count: 0, commits: [] };
+    }
+}
+/**
+ * Creates a git branch and switches to it
+ * - Checks if in git repository
+ * - Checks if branch already exists
+ * - Creates branch using 'git switch -c'
+ *
+ * @param branchName - Name of the branch to create
+ * @returns true if successful, false otherwise
+ */
+async function createGitBranch(branchName) {
+    try {
+        // Check if we're in a git repository
+        try {
+            (0, child_process_1.execSync)('git rev-parse --git-dir', { stdio: 'pipe' });
+        }
+        catch (error) {
+            console.log('⚠️  Not in a git repository. Branch creation skipped.');
+            return false;
+        }
+        // Check if branch already exists
+        try {
+            (0, child_process_1.execSync)(`git show-ref --verify --quiet refs/heads/${branchName}`, { stdio: 'pipe' });
+            console.log(`⚠️  Branch '${branchName}' already exists. Branch creation skipped.`);
+            return false;
+        }
+        catch (error) {
+            // Branch doesn't exist, which is what we want
+        }
+        // Create and switch to branch
+        (0, child_process_1.execSync)(`git switch -c ${branchName}`, { stdio: 'inherit' });
+        return true;
+    }
+    catch (error) {
+        console.error(`❌ Failed to create branch '${branchName}':`, error instanceof Error ? error.message : error);
+        return false;
+    }
+}

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const commander_1 = require("commander");
+const dotenv_1 = require("dotenv");
+const path_1 = require("path");
+const create_parent_1 = require("./commands/create-parent");
+const create_sub_1 = require("./commands/create-sub");
+// Load .env file from the project root
+// __dirname points to dist/ in compiled output, so we go up one level
+(0, dotenv_1.config)({ path: (0, path_1.resolve)(__dirname, '..', '.env') });
+const program = new commander_1.Command();
+program
+    .name('lg')
+    .description('Linear + GitHub Integration CLI - Create GitHub issues with Linear sync')
+    .version('1.0.0');
+program
+    .command('create-parent')
+    .alias('parent')
+    .description('Create a parent GitHub issue with Linear integration')
+    .action(async () => {
+    try {
+        await (0, create_parent_1.createParentIssue)();
+    }
+    catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program
+    .command('create-sub')
+    .alias('sub')
+    .description('Create a sub-issue linked to a parent issue')
+    .action(async () => {
+    try {
+        await (0, create_sub_1.createSubIssue)();
+    }
+    catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+program.parse();