@slahon/lazykit 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# 🦥 LazyKit
+
+**Drop an issue, get a PR.**
+
+LazyKit wires Claude AI into your GitHub repo so that when you label an issue, Claude reads it, writes the code, and opens a pull request — while you do something else.
+
+## Quickstart
+
+```bash
+npx @slahon/lazykit init
+```
+
+Run this inside your project folder. It will:
+- Create `.github/workflows/lazykit.yml`
+- Create `CLAUDE.md` with project context for Claude
+- Create the trigger label on GitHub
+- Print the one manual step (adding your Claude token)
+
+## Requirements
+
+- Node.js 18+
+- A GitHub repository
+- A Claude Pro or Max subscription ([claude.ai](https://claude.ai))
+- Claude Code installed locally (`npm install -g @anthropic-ai/claude-code`)
+- GitHub CLI (`gh`) — optional but recommended
+
+## How it works
+
+1. You open a GitHub issue describing what you want
+2. You apply the `lazykit` label (or whatever you named it)
+3. A GitHub Actions workflow fires and runs Claude Code
+4. Claude reads the issue, explores your codebase, writes the changes
+5. Claude opens a pull request with a title and description
+6. You review and merge
+
+## Authentication
+
+LazyKit uses your Claude Pro/Max subscription via an OAuth token — no pay-per-token API billing.
+
+After running `npx lazykit init`, you need to:
+
+1. Generate your token:
+   ```bash
+   claude setup-token
+   ```
+
+2. Add it to your repo as a secret named `CLAUDE_CODE_OAUTH_TOKEN`
+
+## CLAUDE.md
+
+LazyKit creates a `CLAUDE.md` file at your repo root. This is Claude's project guide — it tells Claude about your stack, conventions, and what commands to run before opening a PR. Edit it to match your actual project.
+
+## Options
+
+During `npx lazykit init` you will be asked:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| Label name | `lazykit` | The GitHub label that triggers Claude |
+| Stack | — | Your tech stack (goes into CLAUDE.md) |
+| Lint command | `npm run lint` | Run before every PR |
+| Test command | `npm test` | Run before every PR |
+
+## Tips
+
+- **Keep issues small and specific.** "Add a /health endpoint that returns `{ status: 'ok' }`" works great. "Rewrite the auth system" does not.
+- **Edit CLAUDE.md** to describe your folder structure, naming conventions, and any rules Claude must follow.
+- The `lazykit` label is your control switch — Claude only runs when you apply it, so you stay in charge.
+
+## License
+
+MIT

package/claude-md.js

@@ -0,0 +1,30 @@
+'use strict';
+
+function generateClaudeMd({ stack, lintCommand, testCommand }) {
+  const hasLint = lintCommand && lintCommand !== 'skip';
+  const hasTest = testCommand && testCommand !== 'skip';
+
+  return `# LazyKit — Project Guide for Claude
+
+## Stack
+${stack || 'Describe your tech stack here (e.g. TypeScript + Next.js, Postgres via Prisma)'}
+
+## Conventions
+- Match the existing code style and patterns in whatever file you are editing.
+- Follow the folder structure already present in the repo.
+- Keep changes scoped to what the issue asks for — do not refactor unrelated code.
+
+## Before opening a PR, always:
+${hasLint ? `1. Run \`${lintCommand}\` and fix all errors and warnings.` : '1. Check your code for obvious errors.'}
+${hasTest ? `2. Run \`${testCommand}\` and make sure all tests pass.` : '2. Make sure existing functionality is not broken.'}
+3. If you cannot get lint/tests passing, comment on the issue explaining why instead of pushing broken code.
+
+## Never
+- Touch \`.github/workflows/\`, secrets, or CI configuration.
+- Add new dependencies without clearly noting them in the PR description.
+- Make changes outside the scope of the issue.
+- Merge your own pull requests.
+`;
+}
+
+module.exports = { generateClaudeMd };

package/git.js

@@ -0,0 +1,48 @@
+'use strict';
+
+const { execSync } = require('child_process');
+
+function getGitRemote() {
+  try {
+    const remote = execSync('git remote get-url origin', { stdio: 'pipe' })
+      .toString()
+      .trim();
+    return remote;
+  } catch {
+    return null;
+  }
+}
+
+function parseGitHubRepo(remoteUrl) {
+  if (!remoteUrl) return null;
+
+  // Handle SSH: git@github.com:owner/repo.git
+  const sshMatch = remoteUrl.match(/git@github\.com[:/](.+?)\/(.+?)(?:\.git)?$/);
+  if (sshMatch) return { owner: sshMatch[1], repo: sshMatch[2] };
+
+  // Handle HTTPS: https://github.com/owner/repo.git
+  const httpsMatch = remoteUrl.match(/https?:\/\/github\.com\/(.+?)\/(.+?)(?:\.git)?$/);
+  if (httpsMatch) return { owner: httpsMatch[1], repo: httpsMatch[2] };
+
+  return null;
+}
+
+function isGitRepo() {
+  try {
+    execSync('git rev-parse --git-dir', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isGhCliAvailable() {
+  try {
+    execSync('gh --version', { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { getGitRemote, parseGitHubRepo, isGitRepo, isGhCliAvailable };

package/index.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { init } = require('../src/commands/init');
+
+const [,, command] = process.argv;
+
+switch (command) {
+  case 'init':
+  case undefined:
+    init().catch(err => {
+      console.error('\n❌ Setup failed:', err.message);
+      process.exit(1);
+    });
+    break;
+  default:
+    console.log(`
+🦥  LazyKit — Drop an issue, get a PR.
+
+Usage:
+  npx lazykit init     Set up LazyKit in your current GitHub repo
+`);
+}

package/init.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const chalk = require('chalk');
+const ora = require('ora');
+
+const { log } = require('../utils/logger');
+const { ask, confirm, select } = require('../utils/prompt');
+const { isGitRepo, getGitRemote, parseGitHubRepo, isGhCliAvailable } = require('../utils/git');
+const { generateWorkflow } = require('../templates/workflow');
+const { generateClaudeMd } = require('../templates/claude-md');
+
+async function init() {
+  console.log(chalk.bold.white('\n🦥  LazyKit — Drop an issue, get a PR.\n'));
+  console.log(chalk.gray('  This will set up AI-powered issue-to-PR automation in your repo.\n'));
+
+  // ─── Step 1: Verify git repo ─────────────────────────────────────────────
+  if (!isGitRepo()) {
+    log.error('Not inside a git repository. Run this from your project root.');
+    process.exit(1);
+  }
+
+  const remote = getGitRemote();
+  const repoInfo = parseGitHubRepo(remote);
+
+  if (repoInfo) {
+    log.success(`Detected repo: ${chalk.cyan(`${repoInfo.owner}/${repoInfo.repo}`)}`);
+  } else {
+    log.warn('Could not detect GitHub repo from git remote. Continuing anyway.');
+  }
+
+  log.blank();
+
+  // ─── Step 2: Ask questions ───────────────────────────────────────────────
+  log.title('Configure LazyKit');
+  log.blank();
+
+  const label = await ask('Label name to trigger Claude', 'lazykit');
+
+  const stack = await ask('What is your stack?', 'e.g. TypeScript + Next.js, Postgres');
+
+  const lintCommand = await ask('Lint command', 'npm run lint');
+
+  const testCommand = await ask('Test command', 'npm test');
+
+  const wantClaudeMd = await confirm('Generate CLAUDE.md project guide?', true);
+
+  log.blank();
+
+  // ─── Step 3: Create workflow file ────────────────────────────────────────
+  const spinner = ora({ text: 'Creating workflow file...', color: 'cyan' }).start();
+
+  const workflowDir = path.join(process.cwd(), '.github', 'workflows');
+  fs.mkdirSync(workflowDir, { recursive: true });
+
+  const workflowPath = path.join(workflowDir, 'lazykit.yml');
+  const workflowContent = generateWorkflow({ label, lintCommand, testCommand });
+  fs.writeFileSync(workflowPath, workflowContent);
+
+  spinner.succeed(chalk.green('Created .github/workflows/lazykit.yml'));
+
+  // ─── Step 4: Create CLAUDE.md ────────────────────────────────────────────
+  if (wantClaudeMd) {
+    const claudeMdPath = path.join(process.cwd(), 'CLAUDE.md');
+    const claudeMdContent = generateClaudeMd({ stack, lintCommand, testCommand });
+
+    if (fs.existsSync(claudeMdPath)) {
+      const overwrite = await confirm('CLAUDE.md already exists. Overwrite?', false);
+      if (overwrite) {
+        fs.writeFileSync(claudeMdPath, claudeMdContent);
+        log.success('Updated CLAUDE.md');
+      } else {
+        log.warn('Skipped CLAUDE.md — keeping existing file.');
+      }
+    } else {
+      fs.writeFileSync(claudeMdPath, claudeMdContent);
+      log.success('Created CLAUDE.md');
+    }
+  }
+
+  // ─── Step 5: Create GitHub label ─────────────────────────────────────────
+  const ghAvailable = isGhCliAvailable();
+
+  if (ghAvailable && repoInfo) {
+    const labelSpinner = ora({ text: `Creating '${label}' label on GitHub...`, color: 'cyan' }).start();
+    try {
+      execSync(
+        `gh label create "${label}" --color "#7B61FF" --description "Let Claude handle this" --repo ${repoInfo.owner}/${repoInfo.repo}`,
+        { stdio: 'pipe' }
+      );
+      labelSpinner.succeed(chalk.green(`Created '${label}' label on GitHub`));
+    } catch (err) {
+      const msg = err.stderr?.toString() || '';
+      if (msg.includes('already exists')) {
+        labelSpinner.succeed(chalk.green(`Label '${label}' already exists — skipping`));
+      } else {
+        labelSpinner.warn(chalk.yellow(`Could not create label automatically — you'll need to create it manually`));
+      }
+    }
+  } else {
+    log.warn(`gh CLI not found — create the '${label}' label manually on GitHub`);
+  }
+
+  // ─── Step 6: Done! Print final instructions ───────────────────────────────
+  console.log('\n' + chalk.bold.green('  ✨ LazyKit is almost ready!\n'));
+  log.divider();
+
+  console.log(chalk.bold('\n  One manual step — add your Claude token as a repo secret:\n'));
+
+  console.log(chalk.gray('  1.') + ' Run in your terminal:');
+  console.log(chalk.cyan('       claude setup-token'));
+
+  console.log(chalk.gray('\n  2.') + ' Copy the token it prints  ' + chalk.gray('(sk-ant-oat01-...)'));
+
+  if (repoInfo) {
+    console.log(chalk.gray('\n  3.') + ' Go to:');
+    console.log(chalk.cyan(`       https://github.com/${repoInfo.owner}/${repoInfo.repo}/settings/secrets/actions`));
+  } else {
+    console.log(chalk.gray('\n  3.') + ' Go to:');
+    console.log(chalk.cyan('       Your repo → Settings → Secrets and variables → Actions'));
+  }
+
+  console.log(chalk.gray('\n  4.') + ' Click ' + chalk.bold('"New repository secret"') + ' and add:');
+  console.log(chalk.gray('       Name:  ') + chalk.cyan('CLAUDE_CODE_OAUTH_TOKEN'));
+  console.log(chalk.gray('       Value: ') + chalk.cyan('the token you copied'));
+
+  console.log(chalk.gray('\n  5.') + ' Also enable PR creation:');
+  if (repoInfo) {
+    console.log(chalk.cyan(`       https://github.com/${repoInfo.owner}/${repoInfo.repo}/settings/actions`));
+  } else {
+    console.log(chalk.cyan('       Repo → Settings → Actions → General → Workflow permissions'));
+  }
+  console.log(chalk.gray('       Enable: ') + '"Allow GitHub Actions to create and approve pull requests"');
+
+  log.divider();
+
+  console.log(chalk.bold('\n  Then commit and push the new files:\n'));
+  console.log(chalk.cyan('    git add .github/workflows/lazykit.yml' + (wantClaudeMd ? ' CLAUDE.md' : '')));
+  console.log(chalk.cyan('    git commit -m "Add LazyKit automation"'));
+  console.log(chalk.cyan('    git push'));
+
+  log.divider();
+
+  console.log(chalk.bold('\n  Done! Here is how to use it:\n'));
+  console.log(`  ${chalk.gray('1.')} Open a GitHub issue describing what you want`);
+  console.log(`  ${chalk.gray('2.')} Apply the ${chalk.bold.magenta(label)} label`);
+  console.log(`  ${chalk.gray('3.')} Watch Claude open a PR with the changes\n`);
+
+  console.log(chalk.bold.white('  🦥  LazyKit is ready. Go be lazy.\n'));
+}
+
+module.exports = { init };

package/logger.js

@@ -0,0 +1,16 @@
+'use strict';
+
+const chalk = require('chalk');
+
+const log = {
+  info:    (msg) => console.log(chalk.cyan('  →'), msg),
+  success: (msg) => console.log(chalk.green('  ✓'), msg),
+  warn:    (msg) => console.log(chalk.yellow('  ⚠'), msg),
+  error:   (msg) => console.log(chalk.red('  ✗'), msg),
+  title:   (msg) => console.log('\n' + chalk.bold.white(msg)),
+  divider: ()    => console.log(chalk.gray('  ' + '─'.repeat(50))),
+  blank:   ()    => console.log(),
+  raw:     (msg) => console.log(msg),
+};
+
+module.exports = { log };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@slahon/lazykit",
+  "version": "1.0.0",
+  "description": "Drop an issue, get a PR. AI-powered issue-to-PR automation using Claude.",
+  "bin": {
+    "lazykit": "./bin/index.js"
+  },
+  "scripts": {
+    "start": "node bin/index.js"
+  },
+  "keywords": [
+    "claude",
+    "ai",
+    "github-actions",
+    "automation",
+    "cli",
+    "issue-to-pr"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "ora": "^5.4.1"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/prompt.js

@@ -0,0 +1,64 @@
+'use strict';
+
+const readline = require('readline');
+const chalk = require('chalk');
+
+function ask(question, defaultValue = '') {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const display = defaultValue
+      ? `  ${chalk.bold(question)} ${chalk.gray(`(${defaultValue})`)} › `
+      : `  ${chalk.bold(question)} › `;
+
+    rl.question(display, (answer) => {
+      rl.close();
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+function confirm(question, defaultValue = true) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const hint = defaultValue ? chalk.gray('Y/n') : chalk.gray('y/N');
+    rl.question(`  ${chalk.bold(question)} ${hint} › `, (answer) => {
+      rl.close();
+      if (!answer.trim()) return resolve(defaultValue);
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+function select(question, options) {
+  return new Promise((resolve) => {
+    console.log(`\n  ${chalk.bold(question)}`);
+    options.forEach((opt, i) => {
+      console.log(`  ${chalk.gray(`${i + 1}.`)} ${opt.label}`);
+    });
+
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    rl.question(`\n  ${chalk.gray('Enter number')} › `, (answer) => {
+      rl.close();
+      const index = parseInt(answer.trim()) - 1;
+      if (index >= 0 && index < options.length) {
+        resolve(options[index].value);
+      } else {
+        resolve(options[0].value);
+      }
+    });
+  });
+}
+
+module.exports = { ask, confirm, select };

package/workflow.js

@@ -0,0 +1,64 @@
+'use strict';
+
+function generateWorkflow({ label, lintCommand, testCommand }) {
+  const hasLint = lintCommand && lintCommand !== 'skip';
+  const hasTest = testCommand && testCommand !== 'skip';
+
+  const checks = [
+    hasLint ? `Run \`${lintCommand}\` and fix any issues before committing.` : null,
+    hasTest ? `Run \`${testCommand}\` and make sure all tests pass before committing.` : null,
+    'If lint or tests fail and you cannot fix them, do NOT commit — instead post a comment on the issue explaining what went wrong.',
+  ].filter(Boolean);
+
+  const checkList = checks.map((c, i) => `            ${i + 1}. ${c}`).join('\n');
+
+  return `name: LazyKit
+
+on:
+  issues:
+    types: [opened, labeled]
+  issue_comment:
+    types: [created]
+
+concurrency:
+  group: lazykit-\${{ github.event.issue.number }}
+  cancel-in-progress: false
+
+jobs:
+  lazykit:
+    if: >
+      contains(github.event.issue.labels.*.name, '${label}') ||
+      contains(github.event.comment.body, '@claude')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: \${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          label_trigger: ${label}
+          claude_args: --max-turns 50 --dangerously-skip-permissions
+          prompt: |
+            You are an autonomous coding agent called LazyKit.
+            Your job is to read the GitHub issue, understand the requirement,
+            implement the changes in the codebase, and open a pull request.
+
+            Before opening the PR:
+${checkList}
+
+            When opening the PR:
+            - Use a clear title that summarises what was done
+            - Write a description explaining what changed and why
+            - Reference the issue number so it auto-closes on merge
+`;
+}
+
+module.exports = { generateWorkflow };