brn-toolkit 1.0.0

package/GEMINI.md

@@ -0,0 +1,92 @@
+# BRN - AI Developer Workflow Toolkit
+
+**BRN** is a modular skills toolkit designed to supercharge AI assistants (like Claude Code and GitHub Copilot CLI) by automating complex developer workflows. It bridges the gap between high-level AI intent and low-level system operations (Git, GitHub API, JIRA API).
+
+## Project Overview
+
+*   **Goal**: Centralize tools, agents, and skills to automate daily dev workflows (planning, coding, testing, PRs).
+*   **Core Concepts**:
+    *   **Workspaces**: Isolated configurations (tokens, directories) for different contexts (e.g., "personal" vs "work").
+    *   **Skills**: Modular units of functionality (e.g., "github", "jira", "git-worktree").
+    *   **Git Worktrees**: Efficiently manages multiple branches/features without re-cloning repositories.
+*   **Tech Stack**:
+    *   **Runtime**: Node.js
+    *   **Language**: TypeScript
+    *   **Execution**: `tsx` (TypeScript Execute)
+    *   **Shell Integration**: `zx` (for seamless shell command execution)
+    *   **Configuration**: YAML (`~/.brn/config.yaml`)
+
+## Architecture
+
+The project is structured into a core CLI and a set of modular skills.
+
+```text
+/
+├── cli/                # Core CLI logic
+│   └── brn.ts          # Main entry point (setup, workspace management)
+├── skills/             # Modular skills directory
+│   ├── github/         # GitHub integration
+│   ├── jira/           # JIRA integration
+│   ├── git-worktree/   # Git worktree management
+│   ├── workflow/       # End-to-end workflow orchestration
+│   └── workspace-manager/ # Workspace configuration scripts
+├── lib/                # Shared utilities
+│   └── utils.ts
+└── package.json        # Dependencies (zx, yaml, tsx)
+```
+
+### Skills Structure
+Each skill typically contains:
+*   `SKILL.md`: Documentation for the AI/User describing the skill's purpose and usage.
+*   `scripts/`: Executable scripts (TypeScript or Shell) that perform the actual tasks.
+*   `references/`: (Optional) Helper docs like API patterns.
+
+## Building and Running
+
+### Prerequisites
+*   Node.js 18+
+*   Git
+
+### Installation
+1.  **Install Dependencies**:
+    ```bash
+    npm install
+    ```
+2.  **Link Globally**:
+    ```bash
+    npm link
+    ```
+    This makes the `brn` command available globally.
+
+### Usage
+*   **Setup**: Run the interactive wizard to configure workspaces.
+    ```bash
+    brn setup
+    ```
+*   **Workspace Management**:
+    ```bash
+    brn workspace list
+    brn workspace switch <name>
+    ```
+*   **Running Skills Manually**:
+    Scripts can be run directly via `npm run` (defined in `package.json`) or `npx tsx`:
+    ```bash
+    # Example: List GitHub repos
+    npm run github:repos -- <org_name>
+    # OR
+    npx tsx skills/github/scripts/list_repos.ts <org_name>
+    ```
+
+## Configuration
+
+Configuration is stored in `~/.brn/config.yaml`. It manages:
+*   **Active Workspace**: The currently selected context.
+*   **Workspaces**: Key-value map of workspace names to configs (paths, tokens).
+*   **Automation Flags**: Safety toggles (default: OFF) for actions like auto-pushing or auto-commenting.
+
+## Development Conventions
+
+*   **TypeScript**: Use TypeScript for all new logic. Use `tsx` for execution.
+*   **Shell Integration**: Use `zx` (`import { $ } from "zx"`) for running shell commands within TypeScript files.
+*   **Modularity**: Keep skills self-contained. If logic is shared, put it in `lib/utils.ts`.
+*   **Safety First**: All mutative actions (push, delete, update) should be gated by automation flags or explicit user confirmation.

package/README.md

@@ -0,0 +1,145 @@
+# BRN - AI Developer Workflow Toolkit
+
+**BRN** is a modular skills toolkit designed to supercharge AI assistants and developers by automating complex workflows. It bridges the gap between high-level intent (e.g., "Start working on ticket PROJ-123") and low-level system operations (Git, GitHub API, JIRA API).
+
+## Core Concepts
+
+*   **Workspaces**: Isolated environments for different contexts (e.g., "personal", "work"). Each workspace has its own configuration (API tokens, root directory).
+*   **Skills**: Modular units of functionality. Each skill (e.g., `github`, `jira`, `git-worktree`) provides a set of specific commands.
+*   **Git Worktrees**: The toolkit manages repositories using the Git worktree pattern, allowing you to work on multiple branches simultaneously in sibling directories without re-cloning.
+*   **CLI First**: All functionality is exposed through a unified `brn` CLI.
+
+## Installation
+
+### Prerequisites
+*   **Node.js** (v18 or later)
+*   **Git**
+
+### Setup
+1.  **Clone the repository**:
+    ```bash
+    git clone https://github.com/zfael/brn.git ~/.brn-toolkit
+    cd ~/.brn-toolkit
+    ```
+
+2.  **Install dependencies**:
+    ```bash
+    npm install
+    ```
+
+3.  **Link globally**:
+    ```bash
+    npm link
+    ```
+    This makes the `brn` command available globally in your terminal.
+
+---
+
+## Quick Start
+
+### 1. Configure BRN
+Run the interactive setup wizard to create your first workspace and configure API tokens.
+```bash
+brn setup
+```
+This will create `~/.brn/config.yaml` and prompt you for:
+- Workspace name (e.g., "personal")
+- Work directory (where code will be stored)
+- GitHub & JIRA tokens (optional but recommended)
+
+### 2. Start a Task
+To start working on a JIRA ticket:
+```bash
+brn start PROJ-123
+```
+This single command:
+1.  Fetches ticket details from JIRA.
+2.  Finds or clones the correct repository.
+3.  Creates a new Git worktree for the feature.
+4.  Updates the JIRA ticket status to "In Progress".
+
+---
+
+## Usage Guide
+
+The CLI follows the pattern: `brn <skill> <command> [arguments]`
+
+### 🛠 Workflow
+High-level orchestration of development tasks.
+- `brn start <ticket_id>`: Start working on a ticket (shortcut for `brn workflow start`).
+
+### 🐙 GitHub (`brn github ...`)
+- `list_repos [org]`: List repositories.
+- `get_repo_info <owner/repo>`: Get details about a repo.
+- `create_pr <owner/repo> <head> <base> <title>`: Create a Pull Request.
+- `list_prs <owner/repo>`: List open PRs.
+
+### 📋 JIRA (`brn jira ...`)
+- `list_tickets [status]`: List tickets assigned to you.
+- `get_ticket <key>`: Get ticket details.
+- `update_ticket <key> <status>`: Update ticket status.
+- `add_comment <key> <comment>`: Add a comment to a ticket.
+
+### 🌳 Git Worktree (`brn git-worktree ...`)
+- `clone_repo <url> [name]`: Clone a repo for worktree usage.
+- `create_worktree <repo> <branch>`: Create a new worktree.
+- `list_worktrees <repo>`: List active worktrees.
+- `remove_worktree <repo> <branch>`: Remove a worktree.
+
+### ⚙️ Workspace (`brn workspace ...`)
+- `list`: List all configured workspaces.
+- `switch <name>`: Switch the active workspace.
+
+---
+
+## Configuration
+
+Configuration is stored in `~/.brn/config.yaml`.
+
+```yaml
+version: "1.0"
+active_workspace: personal
+workspaces:
+  personal:
+    path: /Users/me/dev/personal
+    github_token: ghp_...
+    jira_url: https://myorg.atlassian.net
+    jira_email: me@myorg.com
+    jira_token: ATATT...
+    automation:
+      github_auto_push: false
+      jira_auto_transition: false
+```
+
+### Automation Flags
+For safety, automated actions (like pushing code or updating JIRA) are **disabled by default**. You can enable them in `config.yaml` or during `brn setup`.
+
+---
+
+## Architecture
+
+```text
+/
+├── cli/                # Core CLI logic (brn.ts)
+├── skills/             # Modular skills
+│   ├── github/         # GitHub integration
+│   ├── jira/           # JIRA integration
+│   ├── git-worktree/   # Git worktree management
+│   ├── workflow/       # Orchestration
+│   └── workspace-manager/
+├── lib/                # Shared utilities
+└── package.json
+```
+
+## Development
+
+### Tech Stack
+*   **Runtime**: Node.js
+*   **Language**: TypeScript
+*   **Execution**: `tsx` (TypeScript Execute)
+*   **Shell Integration**: `zx` (Google's tool for writing shell scripts in JS)
+
+### Conventions
+1.  **TypeScript First**: All new scripts should be written in TypeScript using `zx`.
+2.  **Modularity**: Skills should be self-contained in `skills/<skill_name>`.
+3.  **Safety**: Destructive actions must be gated by automation flags or confirmation prompts.

package/cli/brn.ts

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/**
+ * BRN-Toolkit CLI - Main entry point
+ * Usage: brn <command> [options]
+ */
+import { $ } from "zx";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import * as readline from "readline";
+import YAML from "yaml";
+
+$.verbose = false;
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Handle both source (cli/brn.ts) and compiled (dist/cli/brn.js) locations
+const isCompiled = __dirname.includes(join("dist", "cli"));
+const PROJECT_ROOT = isCompiled ? join(__dirname, "..", "..") : join(__dirname, "..");
+
+const BRN_DIR = join(homedir(), ".brn");
+const CONFIG_FILE = join(BRN_DIR, "config.yaml");
+
+// Simple readline interface for prompts
+function prompt(question: string): Promise<string> {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+
+async function runSkill(skill: string, script: string, args: string[]) {
+    // Determine where to look for scripts
+    // Prefer dist/skills/.../*.js for speed, fallback to skills/.../*.ts
+    const distScriptsDir = join(PROJECT_ROOT, "dist", "skills", skill, "scripts");
+    const srcScriptsDir = join(PROJECT_ROOT, "skills", skill, "scripts");
+    
+    const jsPath = join(distScriptsDir, `${script}.js`);
+    const tsPath = join(srcScriptsDir, `${script}.ts`);
+    const shPath = join(srcScriptsDir, `${script}.sh`);
+
+    // Enable verbose to show output of the child script
+    const previousVerbose = $.verbose;
+    $.verbose = true;
+    
+    try {
+        if (existsSync(jsPath)) {
+            // Run compiled JS with node
+            await $`node ${jsPath} ${args}`;
+        } else if (existsSync(tsPath)) {
+            // Run TS with tsx
+            await $`npx tsx ${tsPath} ${args}`;
+        } else if (existsSync(shPath)) {
+            // Run shell
+            await $`bash ${shPath} ${args}`;
+        } else {
+            // Try without extension in src
+            const exactPath = join(srcScriptsDir, script);
+            if (existsSync(exactPath)) {
+                if (script.endsWith(".sh")) await $`bash ${exactPath} ${args}`;
+                else await $`npx tsx ${exactPath} ${args}`;
+            } else {
+                console.error(`Skill script not found: ${skill}/${script}`);
+                process.exit(1);
+            }
+        }
+    } finally {
+        $.verbose = previousVerbose;
+    }
+}
+
+async function setup() {
+    console.log("");
+    console.log("🚀 BRN Setup Wizard");
+    console.log("===================");
+    console.log("");
+
+    // Create config directory
+    if (!existsSync(BRN_DIR)) {
+        mkdirSync(BRN_DIR, { recursive: true });
+        console.log(`✓ Created ${BRN_DIR}`);
+    }
+
+    // Check for existing config
+    let config: any = { version: "1.0", active_workspace: "", workspaces: {} };
+    if (existsSync(CONFIG_FILE)) {
+        config = YAML.parse(readFileSync(CONFIG_FILE, "utf-8"));
+        console.log(`✓ Found existing config with ${Object.keys(config.workspaces).length} workspace(s)`);
+        console.log("");
+    }
+
+    // Workspace name
+    const defaultName = Object.keys(config.workspaces).length === 0 ? "personal" : "";
+    const name = await prompt(`Workspace name [${defaultName}]: `) || defaultName;
+
+    if (!name) {
+        console.log("❌ Workspace name is required");
+        process.exit(1);
+    }
+
+    // Work directory
+    const defaultPath = join(homedir(), "dev", name, "auto");
+    const workDir = await prompt(`Work directory [${defaultPath}]: `) || defaultPath;
+
+    // GitHub token (optional)
+    console.log("");
+    console.log("📦 GitHub Configuration (optional, press Enter to skip)");
+    const githubToken = await prompt("GitHub token: ");
+    const githubOrg = await prompt("Default GitHub Organization/User: ");
+
+    // JIRA config (optional)
+    console.log("");
+    console.log("📋 JIRA Configuration (optional, press Enter to skip)");
+    const jiraUrl = await prompt("JIRA URL (e.g., https://company.atlassian.net): ");
+    let jiraEmail = "";
+    let jiraToken = "";
+    if (jiraUrl) {
+        jiraEmail = await prompt("JIRA email: ");
+        jiraToken = await prompt("JIRA API token: ");
+    }
+
+    // Automation settings
+    console.log("");
+    console.log("⚙️  Automation Settings");
+    console.log("   By default, all automation is OFF for safety.");
+    const enableAuto = await prompt("Enable any automation? (y/N): ");
+
+    let automation: Record<string, boolean> = {
+        github_auto_push: false,
+        github_auto_pr: false,
+        jira_auto_transition: false,
+        jira_auto_comment: false,
+    };
+
+    if (enableAuto.toLowerCase() === "y") {
+        const autoPush = await prompt("  Auto-push commits? (y/N): ");
+        const autoPr = await prompt("  Auto-create PRs? (y/N): ");
+        const autoTransition = await prompt("  Auto-update JIRA status? (y/N): ");
+        const autoComment = await prompt("  Auto-add JIRA comments? (y/N): ");
+
+        automation = {
+            github_auto_push: autoPush.toLowerCase() === "y",
+            github_auto_pr: autoPr.toLowerCase() === "y",
+            jira_auto_transition: autoTransition.toLowerCase() === "y",
+            jira_auto_comment: autoComment.toLowerCase() === "y",
+        };
+    }
+
+    // Build workspace config
+    const workspace: any = {
+        path: workDir,
+        automation,
+    };
+
+    if (githubToken) workspace.github_token = githubToken;
+    if (githubOrg) workspace.github_org = githubOrg;
+    if (jiraUrl) {
+        workspace.jira_url = jiraUrl;
+        workspace.jira_email = jiraEmail;
+        workspace.jira_token = jiraToken;
+    }
+
+    // Save config
+    config.workspaces[name] = workspace;
+    if (!config.active_workspace) {
+        config.active_workspace = name;
+    }
+
+    writeFileSync(CONFIG_FILE, YAML.stringify(config));
+
+    // Create work directory
+    if (!existsSync(workDir)) {
+        mkdirSync(workDir, { recursive: true });
+    }
+
+    console.log("");
+    console.log("✅ Setup complete!");
+    console.log("");
+    console.log(`   Workspace: ${name}`);
+    console.log(`   Work dir:  ${workDir}`);
+    console.log(`   Config:    ${CONFIG_FILE}`);
+    console.log("");
+    console.log("Next steps:");
+    console.log("  • Use 'brn workspace list' to see workspaces");
+    console.log("  • Use 'brn workspace switch <name>' to change workspace");
+    console.log("  • Ask your AI assistant to 'list my JIRA tickets'");
+    console.log("");
+}
+
+async function workspaceList() {
+    if (!existsSync(CONFIG_FILE)) {
+        console.log("No workspaces configured. Run: brn setup");
+        return;
+    }
+
+    const config = YAML.parse(readFileSync(CONFIG_FILE, "utf-8"));
+    const active = config.active_workspace;
+
+    console.log("Workspaces:");
+    console.log("===========");
+
+    for (const [name, ws] of Object.entries(config.workspaces)) {
+        const workspace = ws as any;
+        const marker = name === active ? "* " : "  ";
+        const activeLabel = name === active ? " [ACTIVE]" : "";
+        console.log(`${marker}${name} (${workspace.path})${activeLabel}`);
+    }
+}
+
+async function workspaceSwitch(name: string) {
+    if (!existsSync(CONFIG_FILE)) {
+        console.log("No workspaces configured. Run: brn setup");
+        return;
+    }
+
+    const config = YAML.parse(readFileSync(CONFIG_FILE, "utf-8"));
+
+    if (!config.workspaces[name]) {
+        console.log(`Workspace '${name}' not found.`);
+        console.log("Available:", Object.keys(config.workspaces).join(", "));
+        return;
+    }
+
+    config.active_workspace = name;
+    writeFileSync(CONFIG_FILE, YAML.stringify(config));
+    console.log(`✓ Switched to workspace '${name}'`);
+}
+
+function showHelp() {
+    console.log(`
+BRN - AI Developer Workflow Toolkit
+
+Usage:
+  brn <command> [options]
+  brn <skill> <script> [args]
+
+Commands:
+  start <ticket>        Shortcut for workflow start <ticket>
+  setup                 Interactive setup wizard
+  workspace list        List all workspaces
+  workspace switch <n>  Switch to workspace <n>
+  help                  Show this help
+
+Skills:
+  github <script>       Run a GitHub skill script (e.g., list_repos)
+  jira <script>         Run a JIRA skill script (e.g., list_tickets)
+  git-worktree <script> Run a Git Worktree skill script (e.g., clone_repo)
+
+Examples:
+  brn start PROJ-123
+  brn github list_repos
+  brn jira list_tickets
+  brn workspace switch work
+`);
+}
+
+// Main
+const args = process.argv.slice(2);
+const command = args[0];
+
+switch (command) {
+    case "start":
+        await runSkill("workflow", "start", args.slice(1));
+        break;
+    case "setup":
+        await setup();
+        break;
+    case "workspace":
+        if (args[1] === "list") {
+            await workspaceList();
+        } else if (args[1] === "switch" && args[2]) {
+            await workspaceSwitch(args[2]);
+        } else {
+            console.log("Usage: brn workspace [list|switch <name>]");
+        }
+        break;
+    case "help":
+    case "--help":
+    case "-h":
+    case undefined:
+        showHelp();
+        break;
+    default:
+        // Generic skill runner: brn <skill> <script> [...args]
+        if (command && args[1]) {
+            await runSkill(command, args[1], args.slice(2));
+        } else {
+            console.log(`Unknown command: ${command}`);
+            showHelp();
+            process.exit(1);
+        }
+}