@arii/boomtick-mcp 0.3.3

package/actions/setup-workspace/action.yml

@@ -0,0 +1,179 @@
+name: 'Setup Workspace'
+description: 'Bootstraps the workspace by installing Node.js, Python, and dev-tools'
+inputs:
+  setup-node:
+    description: "Install Node.js and pnpm"
+    required: false
+    default: 'true'
+  setup-python:
+    description: "Install dev-tools (Python)"
+    required: false
+    default: 'true'
+  node-version-file:
+    description: "Path to .node-version file"
+    required: false
+    default: ".node-version"
+  pnpm-version:
+    description: "Version of pnpm to activate"
+    required: false
+    default: "10.28.2"
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup pnpm
+      if: inputs.setup-node == 'true'
+      uses: pnpm/action-setup@v6 # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+      with:
+        version: ${{ inputs.pnpm-version }}
+
+    - name: Get pnpm store directory
+      if: inputs.setup-node == 'true'
+      id: pnpm-cache
+      shell: bash
+      run: |
+        echo "STORE_PATH=$(pnpm store path)" >> "$GITHUB_OUTPUT"
+
+    - name: Cache pnpm store
+      if: inputs.setup-node == 'true'
+      uses: actions/cache@v4.2.0 # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+      with:
+        path: ${{ steps.pnpm-cache.outputs.STORE_PATH }}
+        key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+        restore-keys: |
+          ${{ runner.os }}-pnpm-store-
+
+    - name: Setup Node.js
+      if: inputs.setup-node == 'true'
+      uses: actions/setup-node@v7 # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+      with:
+        node-version-file: ${{ inputs.node-version-file }}
+
+    - name: Enable Corepack
+      if: inputs.setup-node == 'true'
+      run: corepack enable
+      shell: bash
+
+    - name: Activate pinned pnpm
+      if: inputs.setup-node == 'true'
+      env:
+        PNPM_VERSION: ${{ inputs.pnpm-version }}
+      run: corepack prepare pnpm@"$PNPM_VERSION" --activate
+      shell: bash
+
+    - name: Resolve Paths
+      id: resolve-paths
+      shell: bash
+      run: |
+        # Use centralized script for CLI path resolution
+        if [ -f "scripts/resolve-cli.sh" ]; then
+          CLI_DIR=$(bash scripts/resolve-cli.sh | sed "s|$(pwd)/||")
+        elif [ -f "boomtick-pkg/scripts/resolve-cli.sh" ]; then
+          CLI_DIR=$(bash boomtick-pkg/scripts/resolve-cli.sh | sed "s|$(pwd)/||")
+        elif [ -f "boomtick/scripts/resolve-cli.sh" ]; then
+          CLI_DIR=$(bash boomtick/scripts/resolve-cli.sh | sed "s|$(pwd)/||")
+        elif [ -f "${{ github.action_path }}/../../../scripts/resolve-cli.sh" ]; then
+          CLI_DIR=$(REPO_ROOT="${{ github.action_path }}/../../../" bash "${{ github.action_path }}/../../../scripts/resolve-cli.sh" | sed "s|$(pwd)/||")
+        elif [ -d "cli" ]; then
+          CLI_DIR="cli"
+        elif [ -d "boomtick-pkg/cli" ]; then
+          CLI_DIR="boomtick-pkg/cli"
+        elif [ -d "boomtick/cli" ]; then
+          CLI_DIR="boomtick/cli"
+        else
+          CLI_DIR="cli"
+        fi
+
+        # Validate that the resolved CLI directory exists
+        if [ -z "$CLI_DIR" ] || { [ ! -d "$CLI_DIR" ] && [ ! -d "${{ github.action_path }}/../../../$CLI_DIR" ]; }; then
+          echo "::error::Could not resolve a valid CLI directory. Resolved: '$CLI_DIR'"
+          exit 1
+        fi
+
+        echo "CLI_DIR=$CLI_DIR" >> "$GITHUB_OUTPUT"
+
+        # Consolidate GITHUB_PATH updates
+        echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+        echo "/github/home/.local/bin" >> "$GITHUB_PATH"
+
+    - name: Get pip cache directory
+      if: inputs.setup-python == 'true'
+      id: pip-cache
+      shell: bash
+      run: |
+        echo "DIR=$(pip cache dir)" >> "$GITHUB_OUTPUT"
+
+    - name: Cache pip
+      if: inputs.setup-python == 'true'
+      uses: actions/cache@v4.2.0 # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+      with:
+        path: ${{ steps.pip-cache.outputs.DIR }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dev-tools
+      if: inputs.setup-python == 'true'
+      env:
+        CLI_DIR: ${{ steps.resolve-paths.outputs.CLI_DIR }}
+      run: |
+        echo "::group::Install dev-tools"
+        if [ -f "requirements-dev.txt" ]; then
+          pip install -r requirements-dev.txt --break-system-packages
+        fi
+        pip install -e "$CLI_DIR" --break-system-packages
+
+        echo "::endgroup::"
+      shell: bash
+
+    - name: Export Environment Variables
+      if: inputs.setup-python == 'true'
+      id: export-env
+      env:
+        CLI_DIR: ${{ steps.resolve-paths.outputs.CLI_DIR }}
+      run: |
+        # Use $(pwd) to get the container-internal path, avoiding host-path leakage from $GITHUB_WORKSPACE
+        REPO_DIR=$(pwd)
+        if [[ "$CLI_DIR" = /* ]]; then
+          CLI_DIR_ABS="$CLI_DIR"
+        else
+          CLI_DIR_ABS="$REPO_DIR/$CLI_DIR"
+        fi
+
+        # 1. Update PYTHONPATH for subsequent steps
+        # Ensure it works even if PYTHONPATH is initially empty
+        if [ -z "$PYTHONPATH" ]; then
+          echo "PYTHONPATH=$CLI_DIR_ABS" >> "$GITHUB_ENV"
+        else
+          echo "PYTHONPATH=$CLI_DIR_ABS:$PYTHONPATH" >> "$GITHUB_ENV"
+        fi
+        echo "cli_dir_abs=$CLI_DIR_ABS" >> "$GITHUB_OUTPUT"
+
+        echo "✅ Environment configured: PYTHONPATH includes $CLI_DIR_ABS"
+      shell: bash
+
+    - name: Initialize Schemas and Contracts
+      if: inputs.setup-node == 'true' && inputs.setup-python == 'true'
+      env:
+        CLI_DIR_ABS: ${{ steps.export-env.outputs.cli_dir_abs }}
+      run: |
+        echo "::group::Initialize Schemas and Contracts"
+        export PYTHONPATH="$CLI_DIR_ABS:$PYTHONPATH"
+        python3 "$CLI_DIR_ABS/dev_tools/schema_gen.py"
+
+        MCP_DIR="mcp"
+
+        # Check for sync-contracts script in the resolved MCP directory
+        if [ -f "$MCP_DIR/package.json" ] && grep -q "sync-contracts" "$MCP_DIR/package.json"; then
+          echo "::group::Run sync-contracts in $MCP_DIR"
+          # Ensure dependencies are installed if we're in the MCP directory
+          if [ ! -d "$MCP_DIR/node_modules" ]; then
+             (cd "$MCP_DIR" && pnpm install --frozen-lockfile --prefer-offline)
+          fi
+          pnpm --filter "@arii/boomtick-mcp" run sync-contracts || (cd "$MCP_DIR" && pnpm run sync-contracts)
+          echo "::endgroup::"
+        else
+          echo "⚠️ Skipping: sync-contracts script not found in $MCP_DIR/package.json"
+        fi
+        echo "::endgroup::"
+      shell: bash

package/actions/test-build/action.yml

@@ -0,0 +1,71 @@
+name: BoomTick Build & Test
+description: Encapsulates build, bundle size check, Playwright E2E, and Lighthouse CI
+inputs:
+  github_token:
+    description: 'GitHub token'
+    required: true
+  run_lighthouse:
+    description: 'Whether to run Lighthouse CI'
+    required: false
+    default: 'true'
+runs:
+  using: composite
+  steps:
+    - uses: ./mcp/actions/setup
+
+    - name: pnpm install
+      run: pnpm install --frozen-lockfile --prefer-offline
+      shell: bash
+
+    - name: Build App
+      run: |
+        VITE_BASE_PATH=/; export VITE_BASE_PATH
+        pnpm run build
+      shell: bash
+
+    - name: Bundle Size Check
+      env:
+        GITHUB_TOKEN: ${{ inputs.github_token }}
+      run: |
+        export PATH="$HOME/.local/bin:/github/home/.local/bin:$PATH"
+        python3 -m dev_tools.cli gh bundle-size
+      shell: bash
+
+    - name: Run Playwright Smoke Test
+      run: |
+        VITE_BASE_PATH=/ pnpm run test:e2e
+      shell: bash
+
+    - name: Run Lighthouse CI
+      if: inputs.run_lighthouse == 'true'
+      run: |
+        set -eu
+        VITE_BASE_PATH="/"
+        CHROME_PATH="$(node -e "console.log(require('playwright').chromium.executablePath())")"
+        export VITE_BASE_PATH
+        export CHROME_PATH
+        echo "CHROME_PATH=$CHROME_PATH"
+        pnpm run lighthouse --collect.url="http://localhost:4173${VITE_BASE_PATH}"
+      env:
+        LHCI_GITHUB_TOKEN: ${{ inputs.github_token }}
+      shell: bash
+
+    - name: Check Playwright Report Exists
+      id: check_report
+      if: always()
+      run: |
+        if [ -d "playwright-report/" ]; then
+          echo "exists=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "exists=false" >> "$GITHUB_OUTPUT"
+        fi
+      shell: bash
+
+    - name: Upload Test Results
+      if: always() && steps.check_report.outputs.exists == 'true'
+      uses: actions/upload-artifact@v7 # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+      with:
+        name: playwright-report-${{ github.run_id }}
+        path: playwright-report/
+        retention-days: 7
+        if-no-files-found: ignore

package/actions/update-pr-comment/action.yml

@@ -0,0 +1,101 @@
+name: 'Update PR Comment'
+description: 'Updates or creates a PR comment with the given status and body'
+
+inputs:
+  github_token:
+    description: 'GitHub Token'
+    required: true
+  status_line:
+    description: 'Status line (e.g., ⏳ **Impact analysis running...**)'
+    required: true
+  impact_body:
+    description: 'Body text (leave empty for initial state)'
+    required: false
+    default: ''
+
+runs:
+  using: 'composite'
+  steps:
+    - uses: actions/github-script@v8 # nosemgrep: yaml.github-actions.security.github-actions-mutable-action-tag.github-actions-mutable-action-tag
+      env:
+        INPUT_STATUS_LINE: ${{ inputs.status_line }}
+        INPUT_IMPACT_BODY: ${{ inputs.impact_body }}
+      with:
+        github-token: ${{ inputs.github_token }}
+        script: |
+          const owner = context.repo.owner;
+          const repo = context.repo.repo;
+          const branchName = context.ref.replace('refs/heads/', '');
+
+          const pstTime = new Date().toLocaleString('en-US', {
+            timeZone: 'America/Los_Angeles',
+            dateStyle: 'medium',
+            timeStyle: 'short'
+          });
+
+          if (branchName === 'main') return;
+
+          const pullRequests = await github.paginate(github.rest.pulls.list, {
+            owner,
+            repo,
+            state: 'open'
+          });
+          const matchingPRs = pullRequests.filter(pr => pr.head.ref === branchName);
+
+          const statusLine = process.env.INPUT_STATUS_LINE;
+          // Simple sanitization to satisfy XSS concerns in GitHub comments
+          let impactBodyText = (process.env.INPUT_IMPACT_BODY || '')
+            .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '[REMOVED SCRIPT]');
+
+          for (const pr of matchingPRs) {
+            const commentTag = `<!-- impact-analysis-comment-${branchName} -->`;
+            const bodyParts = [
+              `🚀 **Impact Analysis Details** (Last updated: ${pstTime} PST)`,
+              '',
+              statusLine,
+              `- **Commit SHA:** \`${process.env.GITHUB_SHA.slice(0, 7)}\``,
+              `- [Link to artifacts](https://github.com/${owner}/${repo}/actions/runs/${context.runId})`,
+              ''
+            ];
+
+            if (impactBodyText) {
+              bodyParts.push(impactBodyText, '');
+            }
+
+            const MAX_LENGTH = 65536;
+            const truncationNotice = '\n\n... (truncated due to GitHub comment size limits)\n';
+            // Determine length of string we are about to join
+            let currentContent = bodyParts.join('\n');
+            // Adding 1 because joining `bodyParts` with `\n` and `commentTag` will add a newline
+            let projectedLength = currentContent.length + commentTag.length + 1;
+
+            if (projectedLength > MAX_LENGTH) {
+               // subtracting 2 to account for the newlines joining bodyParts
+               const availableLength = MAX_LENGTH - commentTag.length - truncationNotice.length - 2;
+               // Truncate safely, avoiding cutting midway through a unicode character or making things weird
+               let safeContent = currentContent.slice(0, availableLength);
+               // Simple attempt to cut at last newline if possible
+               let lastNewline = safeContent.lastIndexOf('\n');
+               if (lastNewline > availableLength * 0.9) {
+                   safeContent = safeContent.slice(0, lastNewline);
+               }
+               bodyParts = [safeContent, truncationNotice];
+            }
+
+            bodyParts.push(commentTag);
+            const body = bodyParts.join('\n');
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner,
+              repo,
+              issue_number: pr.number,
+            });
+
+            const existingComment = comments.find(c => c.body.includes(commentTag));
+
+            if (existingComment) {
+              await github.rest.issues.updateComment({ owner, repo, comment_id: existingComment.id, body });
+            } else {
+              await github.rest.issues.createComment({ issue_number: pr.number, owner, repo, body });
+            }
+          }

package/dist/config.js

@@ -0,0 +1,110 @@
+import dotenv from "dotenv";
+import path from "path";
+import fs from "fs";
+import { fileURLToPath } from "url";
+import { execSync } from "child_process";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({
+    path: path.resolve(__dirname, "../.env"),
+    quiet: true
+});
+function getGithubToken() {
+    if (process.env.GITHUB_TOKEN) {
+        return process.env.GITHUB_TOKEN;
+    }
+    try {
+        const token = execSync("gh auth token", { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        if (token) {
+            return token;
+        }
+    }
+    catch (e) {
+        throw e;
+    }
+    return undefined;
+}
+let cachedDynamicConfig = null;
+/**
+ * Explicitly initializes dynamic configuration from the Python CLI.
+ * Should be called once during server startup.
+ */
+export function initializeConfig() {
+    if (cachedDynamicConfig !== null) {
+        return cachedDynamicConfig;
+    }
+    try {
+        // Attempt to load core properties from the Python CLI to avoid duplication
+        const cmd = `td-cli config view`;
+        const output = execSync(cmd, {
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"]
+        });
+        cachedDynamicConfig = JSON.parse(output);
+        return cachedDynamicConfig;
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        const errorPrefix = `CRITICAL: Failed to load dynamic config from Python CLI. Ensure Python 3 is installed and boomtick-pkg/cli is in your PYTHONPATH. Details: ${message}`;
+        if (process.env.NODE_ENV === "development" || process.env.CI === "true") {
+            throw new Error(errorPrefix);
+        }
+        else {
+            console.warn(errorPrefix);
+        }
+        // Set an empty object to prevent repeated attempts if initialization fails in non-blocking mode
+        cachedDynamicConfig = {};
+    }
+    return cachedDynamicConfig;
+}
+function findRepoRoot() {
+    if (process.env.BOOMTICK_REPO_PATH) {
+        return process.env.BOOMTICK_REPO_PATH;
+    }
+    // Traverse up to find workspace.json or .git
+    let current = __dirname;
+    while (current !== path.parse(current).root) {
+        if (fs.existsSync(path.join(current, "workspace.json")) || fs.existsSync(path.join(current, ".git"))) {
+            return current;
+        }
+        current = path.dirname(current);
+    }
+    // Fallback to the monolithic relative path if discovery fails
+    return path.resolve(__dirname, "../../../");
+}
+export const config = {
+    get githubToken() { return getGithubToken(); },
+    get githubOwner() {
+        if (process.env.GITHUB_OWNER)
+            return process.env.GITHUB_OWNER;
+        const repoString = cachedDynamicConfig?.github_repo;
+        if (typeof repoString !== "string" || !repoString.includes("/")) {
+            throw new Error("GITHUB_OWNER must be set via environment variable or project_config.json");
+        }
+        return repoString.split("/")[0];
+    },
+    get githubRepo() {
+        if (process.env.GITHUB_REPO)
+            return process.env.GITHUB_REPO;
+        const repoString = cachedDynamicConfig?.github_repo;
+        if (typeof repoString !== "string" || !repoString.includes("/")) {
+            throw new Error("GITHUB_REPO must be set via environment variable or project_config.json");
+        }
+        return repoString.split("/")[1];
+    },
+    get repoPath() {
+        return findRepoRoot();
+    },
+    get defaultBaseBranch() {
+        return process.env.DEFAULT_BASE_BRANCH || cachedDynamicConfig?.base_branch?.split("/").pop() || "main";
+    },
+    get viteBasePath() {
+        const path = process.env.VITE_BASE_PATH || cachedDynamicConfig?.vite_base_path;
+        if (!path) {
+            throw new Error("VITE_BASE_PATH must be set via environment variable or project_config.json");
+        }
+        return path;
+    },
+    get ghPath() {
+        return process.env.GH_PATH || cachedDynamicConfig?.gh_path || "gh";
+    }
+};

package/dist/evals/run-evals.js

@@ -0,0 +1,38 @@
+import { healthHandler } from "../mcp/tools.js";
+import { searchOpenPrsHandler } from "../tools/github.search_open_prs.js";
+import { getPackageScriptsHandler } from "../tools/repo.get_package_scripts.js";
+async function runEvals() {
+    console.log("Starting Boomtick MCP Evaluations...");
+    try {
+        console.log("\n1. Health Check:");
+        try {
+            const health = await healthHandler({ checkDeep: false });
+            console.log(JSON.stringify(health, null, 2));
+        }
+        catch (e) {
+            console.log("Health check failed:", e instanceof Error ? e.message : String(e));
+        }
+        console.log("\n2. Repository Scripts:");
+        try {
+            const scripts = await getPackageScriptsHandler({ filter: "" });
+            console.log(`Found ${Object.keys(scripts.scripts).length} scripts.`);
+        }
+        catch (e) {
+            console.log("Repository scripts fetch failed:", e instanceof Error ? e.message : String(e));
+        }
+        console.log("\n3. GitHub PR Search (Dry Run):");
+        try {
+            const prs = await searchOpenPrsHandler({ state: "open", includeDrafts: true, limit: 100 });
+            console.log(`Found ${prs.prs.length} open PRs.`);
+        }
+        catch (e) {
+            console.log("GitHub search failed (likely due to environment/auth):", e instanceof Error ? e.message : String(e));
+        }
+        console.log("\nEvaluations complete.");
+    }
+    catch (error) {
+        console.error("\nEvaluation failed:", error);
+        process.exit(1);
+    }
+}
+runEvals();

package/dist/index.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { BoomtickMCPServer } from "./mcp/server.js";
+import { initializeConfig } from "./config.js";
+// Initialize configuration once at startup
+initializeConfig();
+const server = new BoomtickMCPServer();
+server.run().catch((error) => {
+    console.error("Fatal error running server:", error);
+    process.exit(1);
+});

package/dist/lib/error_utils.js

@@ -0,0 +1,8 @@
+/**
+ * Sanitizes stderr from CLI commands to prevent implementation detail leakage
+ * in error messages returned to the AI agent.
+ */
+export function sanitizeError(stderr) {
+    // Take first line and truncate to 200 chars to balance detail vs security
+    return (stderr.split("\n")[0] || "Unknown error").slice(0, 200);
+}

package/dist/lib/git.js

@@ -0,0 +1,33 @@
+import { runCommand } from "./shell.js";
+import path from "path";
+import fs from "fs/promises";
+function validatePrNumber(value) {
+    const prNumber = Number(value);
+    if (!Number.isInteger(prNumber) || prNumber <= 0) {
+        throw new Error("Invalid PR number");
+    }
+    return prNumber;
+}
+export async function createWorktree(branch, prNumber) {
+    const safePrNumber = validatePrNumber(prNumber);
+    const workspaceRoot = "/tmp/boomtick-worktrees";
+    // nosemgrep
+    const worktreePath = path.join(workspaceRoot, `boomtick-mcp-rescue-${safePrNumber}`);
+    // Clean up if exists
+    try {
+        await fs.rm(worktreePath, { recursive: true, force: true });
+        await runCommand("git", ["worktree", "prune"]);
+    }
+    catch (e) {
+        throw e;
+    }
+    const result = await runCommand("git", ["worktree", "add", "-b", `repair-pr-${prNumber}-${Date.now()}`, worktreePath, branch]);
+    if (result.exitCode !== 0) {
+        throw new Error(`Failed to create worktree: ${result.stderr}`);
+    }
+    return worktreePath;
+}
+export async function removeWorktree(worktreePath) {
+    await runCommand("git", ["worktree", "remove", "--force", worktreePath]);
+    await runCommand("git", ["worktree", "prune"]);
+}

package/dist/lib/result.js

@@ -0,0 +1,21 @@
+export function createSuccessResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof data === "string" ? data : JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function createErrorResult(message) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+        isError: true,
+    };
+}

package/dist/lib/shell.js

@@ -0,0 +1,91 @@
+import { spawn } from "child_process";
+import { config } from "../config.js";
+import path from "path";
+import fs from "fs";
+export const ALLOWED_COMMANDS = {
+    git: "git",
+    gh: "gh",
+    "td-cli": "td-cli",
+    pnpm: "pnpm",
+    ls: "ls",
+    rm: "rm",
+    mkdir: "mkdir",
+    cp: "cp",
+    python3: "python3"
+};
+export async function runCommand(cmd, args, options = {}) {
+    if (!(cmd in ALLOWED_COMMANDS)) {
+        throw new Error(`Command not allowed: ${cmd}`);
+    }
+    const safeCmd = cmd;
+    const start = Date.now();
+    const timeout = options.timeout || 60000;
+    // Resolve path for 'gh' or 'td-cli' if specified
+    let finalCmd = ALLOWED_COMMANDS[safeCmd];
+    if (safeCmd === "gh") {
+        finalCmd = config.ghPath;
+    }
+    else if (safeCmd === "td-cli") {
+        // If we have a repo-relative .venv, prioritize it
+        const venvBin = path.join(config.repoPath, ".venv", "bin", "td-cli");
+        const localVenvBin = path.join(process.cwd(), ".venv", "bin", "td-cli");
+        const parentVenvBin = path.join(config.repoPath, "..", ".venv", "bin", "td-cli");
+        // In standalone mode, config.repoPath is the boomtick-pkg root.
+        // We check common venv locations to ensure we call the isolated binary.
+        if (fs.existsSync(venvBin)) {
+            finalCmd = venvBin;
+        }
+        else if (fs.existsSync(localVenvBin)) {
+            finalCmd = localVenvBin;
+        }
+        else if (fs.existsSync(parentVenvBin)) {
+            finalCmd = parentVenvBin;
+        }
+    }
+    const env = {
+        ...process.env,
+        ...options.env,
+        GH_TOKEN: config.githubToken,
+        GITHUB_TOKEN: config.githubToken
+    };
+    return new Promise((resolve, reject) => {
+        // nosemgrep
+        const child = spawn(finalCmd, args, {
+            cwd: options.cwd || config.repoPath,
+            env
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (data) => {
+            stdout += data.toString();
+        });
+        child.stderr.on("data", (data) => {
+            stderr += data.toString();
+        });
+        const timer = setTimeout(() => {
+            child.kill();
+            reject(new Error(`Command timed out: ${cmd} ${args.join(" ")}`));
+        }, timeout);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            const durationMs = Date.now() - start;
+            // Redact token from output
+            if (config.githubToken) {
+                const redact = (str) => str.replace(new RegExp(config.githubToken, "g"), "REDACTED");
+                stdout = redact(stdout);
+                stderr = redact(stderr);
+            }
+            resolve({
+                stdout,
+                stderr,
+                exitCode: code,
+                durationMs,
+                command: `${cmd} ${args.join(" ")}`
+            });
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+    });
+}

package/dist/lib/shell.test.js

@@ -0,0 +1,10 @@
+import { describe, it, expect } from "vitest";
+import path from "path";
+// Simple test to verify environment and vitest setup
+describe("Basic Environment", () => {
+    it("should have a valid repo path", () => {
+        const repoPath = process.env.BOOMTICK_REPO_PATH || "/app";
+        expect(repoPath).toBeDefined();
+        expect(path.isAbsolute(repoPath)).toBe(true);
+    });
+});