@electriccitizen/bolt 0.1.0 → 0.2.0

package/README.md

@@ -157,16 +157,19 @@ bolt update [options]
   --dry-run             Show what would be updated without doing it
   --skip-refresh        Skip the pre-update refresh step
   --skip-test           Skip the baseline test
+  --no-ai               Disable AI reasoning (use scripted fallback)
   --yes                 Skip confirmation prompts
 ```
 
 What it does:
-1. Pre-flight: refreshes local state, runs baseline test, gets outdated packages
-2. Per-module loop: creates branch, updates via Composer, runs `drush updb`, runs full test suite
+1. Pre-flight: refreshes local state, runs baseline test, captures VR baselines, gets outdated packages
+2. Per-module loop: creates branch, updates via Composer, runs `drush updb`, runs full test suite + VR comparison
 3. If tests pass: exports config, commits on update branch
 4. If tests fail: rolls back changes, deletes branch, continues to next module
 5. Produces summary report with per-module results
 
+**Visual regression:** Before any updates begin, bolt captures screenshots of all representative pages. After each module update, it compares against those baselines. Module updates should produce zero visual changes — any difference triggers a test failure and rollback. VR runs automatically during updates even if skipped in `.bolt.yml`.
+
 Each update gets its own branch (`update/<package>-<version>`) off the base branch for clean per-module PRs.
 
 **Exit codes:** 0 = at least one update succeeded, 1 = all failed, 2 = error.
@@ -191,13 +194,17 @@ bolt pr [options]
   --reviewers <list>    Comma-separated GitHub usernames
   --draft               Create as draft PR
   --all                 Create PRs for all update/* branches
+  --no-ai               Disable AI-generated PR descriptions
+  --yes                 Skip confirmation prompts
 ```
 
 What it does:
-1. Finds update branches (current branch or `--all` for all `update/*` branches)
-2. Parses commit messages for update details (package, versions, test results)
-3. Pushes branch to remote
-4. Creates PR with structured body via `gh pr create`
+1. Warns if uncommitted changes exist (PRs only include committed state)
+2. Finds update branches (current branch or `--all` for all `update/*` branches)
+3. Confirms before pushing (lists branches that will be pushed)
+4. Parses commit messages for update details (package, versions, test results)
+5. Pushes branch to remote
+6. Creates PR with structured body via `gh pr create`
 5. Checks for existing PRs to avoid duplicates
 
 **Examples:**
@@ -210,6 +217,76 @@ bolt update --all                      # creates multiple update branches
 bolt pr --all --draft                  # creates draft PRs for all of them
 ```
 
+### `bolt analyze`
+
+AI-powered ticket analysis — produces an investigation plan from a Jira ticket or description.
+
+```bash
+bolt analyze [options]
+  --ticket <key>          Jira ticket key (e.g. PROJ-123) — pulls via Jira MCP
+  --description <text>    Bug description (manual, no Jira needed)
+  --url <url>             Site URL (auto-detected from DDEV if omitted)
+  --output <format>       text | json | markdown (default: text)
+  --report <path>         Write analysis to file
+```
+
+**Requires AI** — there is no `--no-ai` fallback for this command, since analysis IS the AI.
+
+Input methods:
+- `--ticket PROJ-123` — pulls from Jira via Atlassian MCP (configured per user)
+- `--description "..."` — manual text input
+- `cat ticket.txt | bolt analyze` — stdin
+
+Output includes: problem summary, likely root causes (ranked), investigation steps with specific commands, risk assessment, suggested bolt tests to run after fix, and a confidence assessment for whether the issue can be fixed autonomously.
+
+**Examples:**
+
+```bash
+bolt analyze --ticket EC-42                          # Jira integration
+bolt analyze --description "Media upload broken"     # manual input
+bolt analyze --ticket EC-42 --output markdown --report analysis.md
+```
+
+### `bolt fix`
+
+Autonomous ticket resolution — analyze, fix, test, and create a PR.
+
+```bash
+bolt fix [options]
+  --ticket <key>          Jira ticket key (runs analysis internally)
+  --description <text>    Bug description (manual, no Jira needed)
+  --analysis <path>       Path to saved bolt analyze report (JSON)
+  --context <text>        Additional context (answers to questions from analyze)
+  --interactive           Launch interactive Claude session (converse instead of autonomous)
+  --dry-run               Show planned changes without modifying files
+  --skip-test             Skip post-fix test run
+  --skip-pr               Skip PR creation
+  --branch <name>         Branch name (default: fix/<ticket-key>)
+  --yes                   Skip confirmation prompts
+```
+
+**Requires AI** — no `--no-ai` fallback.
+
+Two modes:
+- **Autonomous** (default): Claude runs unattended with full tool access (ddev, drush, file editing). The confidence model from `bolt analyze` gates entry — if it says "needs info" or "needs human", bolt exits with instructions.
+- **Interactive** (`--interactive`): Launches a live Claude session with the ticket analysis, site profile, and Drupal knowledge pre-loaded. You converse with Claude to guide the fix.
+
+**Examples:**
+
+```bash
+# Full autonomous flow
+bolt fix --ticket EC-42                              # analyze → fix → test → PR
+
+# Provide answers to questions from analyze
+bolt fix --ticket EC-42 --context "Chrome only, content_editor role"
+
+# Interactive — converse with Claude
+bolt fix --ticket EC-42 --interactive
+
+# Dry run — see what would change
+bolt fix --description "footer logo broken" --dry-run
+```
+
 ### `bolt init`
 
 Connect bolt to a client site. Run from the site's project root.
@@ -218,16 +295,18 @@ Connect bolt to a client site. Run from the site's project root.
 bolt init [options]
   --skip-composer         Skip Composer setup
   --skip-module           Skip module enable
-  --upgrade               Update bolt_inspect module only (no config changes)
+  --upgrade               Update bolt-inspect module via Composer
+  --yes                   Skip confirmation prompts
 ```
 
 What it does:
-1. Warns if on `main`/`master` branch (bolt changes should go on a dedicated branch)
-2. Creates DDEV volume mount for `bolt_inspect` module
-3. Adds Composer path repository
-4. Installs and enables `bolt_inspect`
-5. Creates `.bolt.yml` config template
-6. Adds bolt artifacts to `.gitignore`
+1. Prompts if on `main`/`master` branch (bolt changes should go on a dedicated branch)
+2. Installs `electriccitizen/bolt-inspect` via Composer (from Packagist)
+3. Enables `bolt_inspect` Drupal module
+4. Creates `.bolt.yml` config template
+5. Adds bolt artifacts to `.gitignore`
+
+Other developers on the same project just run `composer install` — the module is in `composer.json` like any other dependency. No additional setup needed beyond installing the bolt CLI globally.
 
 Idempotent — safe to re-run.
 
@@ -346,7 +425,7 @@ bolt init --upgrade
 bolt doctor    # verify versions match
 ```
 
-`bolt init --upgrade` updates the volume mount and module only — no config changes, no re-init.
+`bolt init --upgrade` runs `composer update electriccitizen/bolt-inspect` and clears caches — no config changes, no re-init.
 
 ## Roadmap
 

package/dist/ai/agent.d.ts

@@ -0,0 +1,66 @@
+/**
+ * AI agent infrastructure — spawns Claude Code as a subprocess
+ * for reasoning tasks (conflict resolution, error diagnosis, etc.).
+ *
+ * Pattern: deterministic TypeScript gathers context → Claude reasons → structured JSON back.
+ */
+export interface AgentTask {
+    /** Human-readable goal for the agent. */
+    goal: string;
+    /** Structured context data passed to the agent. */
+    context: Record<string, unknown>;
+    /** Knowledge domains to include in the prompt. */
+    knowledge: KnowledgeDomain[];
+    /** JSON schema description for expected output format. */
+    outputFormat: string;
+    /** Maximum turns the agent can take (default: 25). */
+    maxTurns?: number;
+    /** Timeout in milliseconds (default: 300_000 = 5 min). */
+    timeout?: number;
+    /** Allowed tools for the agent (default: Bash only). */
+    allowedTools?: string[];
+}
+export interface AgentResult {
+    /** Whether the agent completed successfully. */
+    success: boolean;
+    /** Parsed output matching the requested format. */
+    output: Record<string, unknown>;
+    /** Raw text response from Claude. */
+    rawResponse: string;
+    /** Number of turns the agent used. */
+    numTurns: number;
+    /** Duration in milliseconds. */
+    duration: number;
+    /** Cost in USD (if reported). */
+    costUsd?: number;
+}
+export type KnowledgeDomain = 'composer' | 'drupal-updates' | 'config-safety' | 'ddev-operations' | 'drupal-internals' | 'drupal-debugging';
+/**
+ * Check if Claude Code CLI is installed and accessible.
+ * Result is cached for the process lifetime.
+ */
+export declare function isClaudeAvailable(): Promise<boolean>;
+/**
+ * Get Claude Code version string, or null if not available.
+ */
+export declare function getClaudeVersion(): Promise<string | null>;
+/**
+ * Load a knowledge file from src/ai/knowledge/.
+ * Files are read at runtime from the dist directory.
+ */
+export declare function loadKnowledge(domain: KnowledgeDomain): string;
+/**
+ * Build a complete prompt from an AgentTask.
+ */
+export declare function buildPrompt(task: AgentTask): string;
+/**
+ * Parse a JSON code block from Claude's response text.
+ */
+export declare function parseJsonFromResponse(text: string): Record<string, unknown> | null;
+/**
+ * Run an agent task via Claude Code subprocess.
+ *
+ * Spawns `claude -p <prompt> --output-format json` and parses
+ * the structured result.
+ */
+export declare function runAgent(task: AgentTask): Promise<AgentResult>;

package/dist/ai/agent.js

@@ -0,0 +1,232 @@
+/**
+ * AI agent infrastructure — spawns Claude Code as a subprocess
+ * for reasoning tasks (conflict resolution, error diagnosis, etc.).
+ *
+ * Pattern: deterministic TypeScript gathers context → Claude reasons → structured JSON back.
+ */
+import { execFile, spawn } from 'child_process';
+import { promisify } from 'util';
+import { readFileSync } from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const execFileAsync = promisify(execFile);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// --- Claude Availability ---
+let claudeAvailable = null;
+/**
+ * Check if Claude Code CLI is installed and accessible.
+ * Result is cached for the process lifetime.
+ */
+export async function isClaudeAvailable() {
+    if (claudeAvailable !== null)
+        return claudeAvailable;
+    try {
+        const { stdout } = await execFileAsync('claude', ['--version'], {
+            timeout: 5_000,
+        });
+        claudeAvailable = stdout.trim().length > 0;
+    }
+    catch {
+        claudeAvailable = false;
+    }
+    return claudeAvailable;
+}
+/**
+ * Get Claude Code version string, or null if not available.
+ */
+export async function getClaudeVersion() {
+    try {
+        const { stdout } = await execFileAsync('claude', ['--version'], {
+            timeout: 5_000,
+        });
+        return stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+// --- Knowledge Loading ---
+const knowledgeCache = new Map();
+/**
+ * Load a knowledge file from src/ai/knowledge/.
+ * Files are read at runtime from the dist directory.
+ */
+export function loadKnowledge(domain) {
+    if (knowledgeCache.has(domain)) {
+        return knowledgeCache.get(domain);
+    }
+    const knowledgePath = resolve(__dirname, 'knowledge', `${domain}.md`);
+    try {
+        const content = readFileSync(knowledgePath, 'utf-8');
+        knowledgeCache.set(domain, content);
+        return content;
+    }
+    catch {
+        // Knowledge file not found — return empty (non-fatal).
+        return '';
+    }
+}
+// --- Prompt Building ---
+/**
+ * Build a complete prompt from an AgentTask.
+ */
+export function buildPrompt(task) {
+    const sections = [];
+    // Role and goal.
+    sections.push(`# Task\n\n${task.goal}`);
+    // Context data.
+    if (Object.keys(task.context).length > 0) {
+        sections.push(`# Context\n\n\`\`\`json\n${JSON.stringify(task.context, null, 2)}\n\`\`\``);
+    }
+    // Knowledge sections.
+    for (const domain of task.knowledge) {
+        const content = loadKnowledge(domain);
+        if (content) {
+            sections.push(content);
+        }
+    }
+    // Output format instructions.
+    sections.push(`# Output Format\n\n` +
+        `When you have completed the task, output your result as a single JSON code block.\n` +
+        `The JSON must match this format:\n\n` +
+        `\`\`\`\n${task.outputFormat}\n\`\`\`\n\n` +
+        `IMPORTANT: Your final message must contain exactly one JSON code block with the result. ` +
+        `Do not include any other text after the JSON block.`);
+    return sections.join('\n\n---\n\n');
+}
+// --- Agent Execution ---
+/**
+ * Parse a JSON code block from Claude's response text.
+ */
+export function parseJsonFromResponse(text) {
+    // Find all code blocks and try the last one first (most likely the final result).
+    const allBlocks = [...text.matchAll(/```(?:json)?\s*\n([\s\S]*?)\n```/g)];
+    if (allBlocks.length > 0) {
+        // Try last block first (agent's final answer).
+        for (let i = allBlocks.length - 1; i >= 0; i--) {
+            try {
+                return JSON.parse(allBlocks[i][1]);
+            }
+            catch {
+                // Try the next block.
+            }
+        }
+    }
+    // Try parsing the entire response as JSON (unlikely but possible).
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run an agent task via Claude Code subprocess.
+ *
+ * Spawns `claude -p <prompt> --output-format json` and parses
+ * the structured result.
+ */
+export async function runAgent(task) {
+    const startTime = Date.now();
+    const prompt = buildPrompt(task);
+    const timeout = task.timeout ?? 300_000;
+    const maxTurns = task.maxTurns ?? 25;
+    // Build claude CLI args — use --print with stdin to avoid arg length limits.
+    const args = [
+        '--print',
+        '--output-format', 'json',
+        '--max-turns', String(maxTurns),
+    ];
+    // Restrict tools if specified.
+    if (task.allowedTools && task.allowedTools.length > 0) {
+        args.push('--allowedTools', task.allowedTools.join(','));
+    }
+    try {
+        const stdout = await new Promise((resolvePromise, reject) => {
+            const child = spawn('claude', args, {
+                env: {
+                    ...process.env,
+                    CI: '1',
+                },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            const chunks = [];
+            let stderrOutput = '';
+            child.stdout.on('data', (chunk) => chunks.push(chunk));
+            child.stderr.on('data', (chunk) => { stderrOutput += chunk.toString(); });
+            child.on('close', (code) => {
+                const output = Buffer.concat(chunks).toString('utf-8');
+                if (code === 0) {
+                    resolvePromise(output);
+                }
+                else {
+                    reject(new Error(`claude exited with code ${code}: ${stderrOutput || output}`));
+                }
+            });
+            child.on('error', (err) => reject(err));
+            // Write prompt to stdin and close.
+            child.stdin.write(prompt);
+            child.stdin.end();
+            // Timeout handling.
+            const timer = setTimeout(() => {
+                child.kill('SIGTERM');
+                reject(new Error(`Agent timed out after ${timeout}ms`));
+            }, timeout);
+            child.on('close', () => clearTimeout(timer));
+        });
+        const duration = Date.now() - startTime;
+        // Parse Claude Code's JSON output format.
+        // { type: "result", result: "...", num_turns: N, cost_usd: N, ... }
+        let claudeOutput;
+        try {
+            claudeOutput = JSON.parse(stdout);
+        }
+        catch {
+            // If the output isn't valid JSON, treat the raw text as the response.
+            return {
+                success: false,
+                output: {},
+                rawResponse: stdout,
+                numTurns: 0,
+                duration,
+            };
+        }
+        const resultText = String(claudeOutput.result ?? '');
+        const numTurns = claudeOutput.num_turns ?? 0;
+        const costUsd = claudeOutput.cost_usd ?? undefined;
+        const isError = claudeOutput.is_error ?? false;
+        if (isError) {
+            return {
+                success: false,
+                output: { error: resultText },
+                rawResponse: resultText,
+                numTurns,
+                duration,
+                costUsd,
+            };
+        }
+        // Parse the structured JSON from Claude's response text.
+        const parsed = parseJsonFromResponse(resultText);
+        return {
+            success: parsed !== null,
+            output: parsed ?? { rawText: resultText },
+            rawResponse: resultText,
+            numTurns,
+            duration,
+            costUsd,
+        };
+    }
+    catch (err) {
+        const duration = Date.now() - startTime;
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            output: { error: message },
+            rawResponse: message,
+            numTurns: 0,
+            duration,
+        };
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/ai/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/ai/agent.ts"],"names":[],"mappings":"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"}

package/dist/ai/knowledge/composer.md

@@ -0,0 +1,90 @@
+# Composer Conflict Resolution
+
+You are an expert at resolving Composer dependency conflicts for Drupal projects.
+
+## Diagnostic Workflow
+
+When a `composer update` fails, follow this sequence:
+
+1. **Identify the blocker:** `composer why-not vendor/package <target-version>`
+   - Shows the dependency chain preventing the upgrade
+   - Read the output carefully — it tells you exactly which package constrains the version
+
+2. **Trace reverse dependencies:** `composer why vendor/package`
+   - Shows which installed packages depend on the blocked package
+   - Helps identify if updating a parent would unlock the target
+
+3. **Check available versions:** `composer show --all vendor/package`
+   - Lists all available versions
+   - Helps find the highest compatible version if the target isn't achievable
+
+4. **Apply the right update strategy** (see below)
+
+5. **Harden constraints after success:** `composer bump` (applications only, not libraries)
+   - Raises lower bounds to currently installed versions
+   - Prevents accidental downgrades
+
+## Update Strategies (in order of preference)
+
+### Strategy 1: Standard update with transitive deps
+```bash
+composer update vendor/package --with-dependencies
+```
+Tries first because it has the smallest blast radius.
+
+### Strategy 2: Update with all dependencies
+```bash
+composer update vendor/package --with-all-dependencies
+```
+Broader resolution — allows all transitive deps to change.
+
+### Strategy 3: Require with caret constraint
+```bash
+composer require vendor/package:^X.Y --update-with-all-dependencies
+```
+Rewrites the constraint in composer.json. Use when the existing constraint is too tight.
+
+### Strategy 4: Require with tilde constraint
+```bash
+composer require vendor/package:~X.Y --update-with-all-dependencies
+```
+More conservative — only allows patch updates within the minor version.
+
+### Strategy 5: Update alongside core
+```bash
+composer update vendor/package drupal/core-recommended drupal/core-composer-scaffold drupal/core-project-message --with-all-dependencies
+```
+Common Drupal pattern — many modules constrain against core version.
+
+### Strategy 6: Read the error and adapt
+If all standard strategies fail, READ the actual error output:
+- If it says "package X requires Y ^2.0 but Z is locked at 1.5" → update Z first
+- If it says "root composer.json requires X ^1.0" → you may need to change the constraint
+- If it says "package X conflicts with Y" → check if X has a newer version that resolves it
+- Use `composer why-not` output to understand the exact constraint chain
+
+## Version Constraint Reference
+
+| Constraint | Meaning |
+|------------|---------|
+| `^1.2.3` | `>=1.2.3 <2.0.0` (allows minor+patch) |
+| `~1.2.3` | `>=1.2.3 <1.3.0` (allows patch only) |
+| `>=1.0 <2.0` | Explicit range |
+| `1.2.*` | Any 1.2.x patch |
+| `*` | Any version |
+
+## Key Flags
+
+- `--dry-run` — simulate without applying (always safe to run first)
+- `--with-dependencies` — also update deps of specified packages
+- `--with-all-dependencies` — also update deps AND reverse deps
+- `--no-update` — modify composer.json without running update (combine with `composer update` separately)
+- `--prefer-stable` — prefer stable over dev versions
+
+## Important Rules
+
+- Always run `composer update` with package names specified — never bare `composer update` (too broad)
+- After resolving a conflict, verify with `composer show vendor/package` that the installed version is correct
+- If the target version requires a newer PHP, that's a hard blocker — skip the update
+- If the target version requires a newer Drupal core, check if core can also be updated
+- `composer audit` shows security advisories — security updates should be prioritized

package/dist/ai/knowledge/config-safety.md

@@ -0,0 +1,46 @@
+# Configuration Management Safety
+
+You are working with Drupal configuration. Follow these safety patterns.
+
+## Safe Config Export
+
+After a module update, export config changes:
+```bash
+ddev drush cex -y
+```
+
+### Review before committing
+- Check `git diff config/` to see what actually changed
+- Module updates may introduce new config files (new permissions, new field settings)
+- Module updates may modify existing config (schema changes, new default values)
+- Unexpected config changes may indicate a problem
+
+### What's normal after an update
+- New config files for new module features
+- Schema version changes in `.info.yml`
+- Updated default values in existing config
+- New permissions added by the module
+
+### What's suspicious after an update
+- Config deletions you didn't expect
+- Changes to content type or field config you didn't modify
+- Changes to views or blocks unrelated to the updated module
+- System config changes (site name, mail settings, etc.)
+
+## Config Status Check
+
+```bash
+# Check if config is in sync
+ddev drush config:status
+
+# Show diff without importing
+ddev drush cim --no --diff
+```
+
+## Important Rules
+
+- NEVER run `ddev drush cim -y` during an update pipeline — only `cex`
+- Config import (`cim`) is for syncing environments, not for updates
+- Always export (`cex`) after `drush updb` — database updates may generate config changes
+- If `config:status` shows unexpected changes, investigate before exporting
+- One module update per commit keeps config changes traceable

package/dist/ai/knowledge/ddev-operations.md

@@ -0,0 +1,41 @@
+# DDEV Operations
+
+All commands run through DDEV. Use `ddev` prefix for all drush and composer commands.
+
+## Essential Commands
+
+```bash
+ddev drush <command>          # Run drush in container
+ddev composer <command>       # Run composer in container
+ddev drush cr                 # Clear all caches
+ddev drush updb -y            # Apply database updates
+ddev drush cex -y             # Export configuration
+ddev drush status             # Check Drupal status
+ddev drush watchdog:show      # View recent log entries
+ddev describe                 # Show project info + URL
+ddev logs                     # View container logs
+ddev snapshot --name=<name>   # Create safety snapshot
+ddev snapshot restore --name=<name>  # Restore snapshot
+```
+
+## Safety Patterns
+
+- **Snapshot before risky operations:** `ddev snapshot --name=pre-update-$(date +%Y%m%d-%H%M%S)`
+- **Check DDEV is running:** `ddev describe` — if it fails, run `ddev start`
+- **After composer changes:** always run `ddev drush cr` to clear caches
+- **Diagnose problems:** `ddev logs -f` to follow container logs in real-time
+
+## Error Diagnosis
+
+When something fails:
+1. Check drush watchdog: `ddev drush watchdog:show --count=20 --severity=Error`
+2. Check container logs: `ddev logs`
+3. Verify database connection: `ddev drush status`
+4. Try cache rebuild: `ddev drush cr`
+
+## Important Notes
+
+- All file paths inside commands are container paths (e.g., `/var/www/html/web/`)
+- Host paths and container paths are different — DDEV maps them automatically
+- `composer install` syncs to lockfile (safe); `composer update` changes lockfile (update operation)
+- DDEV auto-starts services but may need manual restart after config changes: `ddev restart`