@electriccitizen/bolt 0.1.0 → 0.2.0

package/dist/ai/knowledge/drupal-internals.md

@@ -0,0 +1,52 @@
+# Drupal Internals
+
+Understanding common failure modes after module updates.
+
+## Why Updates Break Things
+
+### Hook system
+- Modules implement hooks that fire during entity operations
+- Updated modules may change hook implementations
+- `auto_entitylabel` can null titles during entity hooks — set title before delete
+- Search index hooks run during content operations — warnings are normal during cleanup
+
+### Entity lifecycle
+- Content entities (nodes, media, terms) have create/update/delete hooks
+- Entity reference fields create dependencies between entities
+- Deleting referenced entities can fail if the reference field has constraints
+- Paragraph entities must be deleted before their host entities
+
+### Caching
+- Drupal aggressively caches render output, config, and routes
+- After module updates, stale caches cause "white screen" or outdated behavior
+- Always `drush cr` after any module update
+- If `drush cr` doesn't fix it, try `drush cache:rebuild` (same thing, full form)
+- Twig template cache is separate — cleared by `drush cr` but can be sticky
+
+### Configuration schema
+- Modules define config schemas in `config/schema/*.yml`
+- Schema changes in updated modules may require `drush updb` to migrate
+- Missing schema warnings in logs are cosmetic but indicate potential issues
+
+## Common Post-Update Issues
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| White screen / WSOD | PHP fatal from incompatible code | Check `ddev logs`, may need rollback |
+| "Class not found" | Autoloader cache stale | `ddev composer dump-autoload && ddev drush cr` |
+| "Schema not found" | Config schema changed | `ddev drush updb -y` |
+| Missing permissions | New permissions added by module | Check `ddev drush role:list` |
+| Broken views | Views plugins changed | `ddev drush views:rebuild` |
+| Missing routes | Route definitions changed | `ddev drush cr` (rebuilds routing) |
+
+## Watchdog Interpretation
+
+```bash
+ddev drush watchdog:show --count=20 --severity=Error
+```
+
+- **PHP warnings/notices:** Usually cosmetic, don't block updates
+- **Entity reference errors:** May indicate orphaned references
+- **Access denied (403):** Permissions may have changed
+- **Page not found (404):** Routes may have moved
+- **Database errors:** Schema mismatch — need `drush updb`

package/dist/ai/knowledge/drupal-updates.md

@@ -0,0 +1,90 @@
+# Drupal Update Safety
+
+You are updating modules on a Drupal site. Follow these safety patterns.
+
+## Core Compatibility Checking
+
+Before attempting a major version update, verify the target version is compatible with the current Drupal core.
+
+### How to check
+```bash
+# Get current core version
+ddev composer show drupal/core --format=json | jq -r '.versions[0]'
+
+# Check all available versions of a module
+ddev composer show --all drupal/<module> --format=json
+```
+
+### Constraint interpretation
+- `^10.2` means `>=10.2.0 <11.0.0` — Drupal 10 only
+- `^11` means `>=11.0.0 <12.0.0` — Drupal 11 only
+- `^9.5 || ^10 || ^11` means any of those major versions
+- `>=10.2` means 10.2.0 and above (including 11.x)
+
+### Decision logic
+- If the target version requires a Drupal core version you don't have → find the highest compatible version instead
+- If no compatible version exists above current → skip the update and report why
+- If the module supports your core version → proceed with update
+
+## Update Categories
+
+### Security updates (auto-apply)
+- Identified via `composer audit`
+- Apply immediately without asking
+- These fix known vulnerabilities
+
+### Patch updates (X.Y.Z → X.Y.Z+1)
+- Backward compatible bug fixes
+- Safe to apply automatically
+- Rarely cause issues
+
+### Minor updates (X.Y → X.Y+1)
+- New features, backward compatible
+- May include deprecations
+- Usually safe but test afterward
+
+### Major updates (X → X+1)
+- May contain breaking changes
+- Require compatibility checking
+- May need config migration
+- Test thoroughly after applying
+
+## Post-Update Verification
+
+After every update:
+
+1. **Database updates:** `ddev drush updb -y`
+   - Read the output — note what hooks ran
+   - If it fails, the update may need manual intervention
+
+2. **Check for errors:** `ddev drush watchdog:show --count=10 --severity=Error`
+   - New errors after update indicate problems
+   - Compare to pre-update error count
+
+3. **Clear caches:** `ddev drush cr`
+   - Some updates require a cache rebuild to take effect
+
+4. **Export config:** `ddev drush cex -y`
+   - Some updates introduce new configuration
+   - Review what changed before committing
+
+5. **Run tests:** `bolt test --output=json`
+   - Verify no regressions
+   - If tests fail, the update introduced a problem
+
+## Common Drupal Update Patterns
+
+- **Admin theme updates (gin):** Often require `gin_toolbar` to be updated together
+- **Core updates:** Always update `drupal/core-recommended`, `drupal/core-composer-scaffold`, and `drupal/core-project-message` together
+- **Paragraphs ecosystem:** `drupal/paragraphs`, `drupal/entity_reference_revisions` are tightly coupled
+- **Media modules:** `drupal/media_library_form_element`, `drupal/focal_point`, `drupal/crop` may have interdependencies
+- **CKEditor modules:** `drupal/ckeditor5_premium_features` depends on core CKEditor version
+
+## Rollback
+
+If an update causes problems:
+```bash
+git checkout .
+git clean -fd
+```
+This restores composer.json, composer.lock, and config to pre-update state.

package/dist/ai/knowledge/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/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/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`

package/dist/ai/knowledge/knowledge/drupal-debugging.md

@@ -0,0 +1,89 @@
+# Drupal Debugging
+
+Common failure patterns and debugging workflows for Drupal 11+ sites.
+
+## Bug Categories and Where to Look
+
+### Rendering / Display Issues
+- **Blank page (WSOD):** Check `sites/default/files/php/twig/` for Twig errors, `drush ws --severity=error`, PHP error log
+- **Wrong content shown:** Cache issue — `drush cr`, check `cache_render`, `cache_page` tables. Check Views cache settings.
+- **Missing fields:** Field display mode config (`core.entity_view_display.*`), check field formatter settings
+- **Broken layout:** Layout Builder config (`core.entity_view_display.*.*.default`), check block placement and visibility
+- **Wrong template:** `drush twig:debug`, check template suggestions, theme override hierarchy
+
+### Form / Input Issues
+- **Form validation errors:** Form alter hooks in custom modules, field widget settings, required field config
+- **Submit does nothing:** JS error blocking form submit — check browser console. AJAX form handler may be broken.
+- **Media upload fails:** Media library widget config, file system permissions (`sites/default/files/`), PHP upload limits
+- **Field not saving:** Check field storage config vs field config, entity presave hooks, auto_entitylabel interference
+- **WYSIWYG broken:** CKEditor 5 plugin config, text format settings (`filter.format.*`), allowed HTML tags
+
+### Access / Permissions Issues
+- **403 on content:** Role permissions (`drush role:perm:list`), content access modules (node_access, content_moderation)
+- **Menu item missing:** Menu link content access, menu block visibility, role permissions
+- **Admin page 403:** Permission name change after module update — check `user.role.*` config
+
+### JS / Frontend Issues
+- **JS error on page:** Drupal.behaviors not attaching — check `once()` calls, library dependencies in `*.libraries.yml`
+- **AJAX broken:** Check `drupalSettings`, AJAX callback routes, session/CSRF token issues
+- **Dialog/modal broken:** jQuery UI dialog deprecated in D11, check for contrib modules still using it
+- **CSS not loading:** Aggregation cache stale (`drush cr`), library not attached, conditional library loading
+
+### Caching Issues
+- **Changes not appearing:** `drush cr`, check cache tags, cache max-age on blocks/views, Varnish/CDN layer
+- **Different content per user:** Cache context missing — add `user` or `user.roles` cache context
+- **Stale after deploy:** `drush deploy:hook` not running, config import didn't trigger cache invalidation
+
+### Configuration Issues
+- **Config mismatch:** `drush cst` (config status) — shows what's different between active and exported
+- **Missing config on deploy:** Check `config_ignore` settings, confirm `drush cim` ran, check config split
+- **Config import fails:** Schema version mismatch — run `drush updb` before `drush cim`
+
+### Module / Dependency Issues
+- **Class not found:** Composer autoload stale — `ddev composer dump-autoload`
+- **Service not found:** Module not enabled, service definition changed in update, container needs rebuild
+- **Hook not firing:** Module weight/order, hook name changed in Drupal 11, check `module.module` vs event subscribers
+- **Deprecated code warnings:** Drupal 11 removed many D9/D10 APIs — check deprecation docs, update to new APIs
+
+### Data / Content Issues
+- **Missing content:** Content may exist but be unpublished — check `status` field, content moderation state
+- **Entity reference broken:** Referenced entity deleted, target bundle changed, orphan references
+- **Paragraphs issues:** Nested paragraph references, orphaned paragraph entities, revision table bloat
+- **Search not finding content:** Search index stale — `drush sapi-rt && drush sapi-i`, check tracked/indexed counts
+
+## Debugging Commands
+
+```bash
+# Error logs
+ddev drush ws --severity=error --count=20
+
+# Config inspection
+ddev drush cget <config.name>                    # View specific config
+ddev drush cst                                    # Config status (active vs exported)
+ddev drush config:diff <collection>               # What changed
+
+# Entity inspection
+ddev drush entity:list                            # All entity types
+ddev drush sql:query "SELECT type, count(*) FROM node_field_data GROUP BY type"
+
+# Module info
+ddev drush pm:list --status=enabled               # Enabled modules
+ddev drush pm:info <module>                       # Detailed module info
+ddev drush eval "print_r(\Drupal::service('<service.id>'))"
+
+# Cache
+ddev drush cr                                     # Rebuild cache
+ddev drush cache:get <cid> <bin>                  # Inspect cache entry
+
+# Permissions
+ddev drush role:perm:list <role>                  # Role permissions
+ddev drush user:info <uid>                        # User details
+```
+
+## Common Fix Patterns
+
+- **Config fix:** Export correct config (`drush cex`), edit YAML, import (`drush cim`)
+- **Permission fix:** `drush role:perm:add <role> '<permission>'`
+- **Cache fix:** `drush cr` + verify cache tags and contexts
+- **Code fix:** Custom module or theme code, then `drush cr` to pick up changes
+- **Data fix:** Entity update via Drush eval or custom update hook

package/dist/ai/knowledge/knowledge/drupal-internals.md

@@ -0,0 +1,52 @@
+# Drupal Internals
+
+Understanding common failure modes after module updates.
+
+## Why Updates Break Things
+
+### Hook system
+- Modules implement hooks that fire during entity operations
+- Updated modules may change hook implementations
+- `auto_entitylabel` can null titles during entity hooks — set title before delete
+- Search index hooks run during content operations — warnings are normal during cleanup
+
+### Entity lifecycle
+- Content entities (nodes, media, terms) have create/update/delete hooks
+- Entity reference fields create dependencies between entities
+- Deleting referenced entities can fail if the reference field has constraints
+- Paragraph entities must be deleted before their host entities
+
+### Caching
+- Drupal aggressively caches render output, config, and routes
+- After module updates, stale caches cause "white screen" or outdated behavior
+- Always `drush cr` after any module update
+- If `drush cr` doesn't fix it, try `drush cache:rebuild` (same thing, full form)
+- Twig template cache is separate — cleared by `drush cr` but can be sticky
+
+### Configuration schema
+- Modules define config schemas in `config/schema/*.yml`
+- Schema changes in updated modules may require `drush updb` to migrate
+- Missing schema warnings in logs are cosmetic but indicate potential issues
+
+## Common Post-Update Issues
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| White screen / WSOD | PHP fatal from incompatible code | Check `ddev logs`, may need rollback |
+| "Class not found" | Autoloader cache stale | `ddev composer dump-autoload && ddev drush cr` |
+| "Schema not found" | Config schema changed | `ddev drush updb -y` |
+| Missing permissions | New permissions added by module | Check `ddev drush role:list` |
+| Broken views | Views plugins changed | `ddev drush views:rebuild` |
+| Missing routes | Route definitions changed | `ddev drush cr` (rebuilds routing) |
+
+## Watchdog Interpretation
+
+```bash
+ddev drush watchdog:show --count=20 --severity=Error
+```
+
+- **PHP warnings/notices:** Usually cosmetic, don't block updates
+- **Entity reference errors:** May indicate orphaned references
+- **Access denied (403):** Permissions may have changed
+- **Page not found (404):** Routes may have moved
+- **Database errors:** Schema mismatch — need `drush updb`

package/dist/ai/knowledge/knowledge/drupal-updates.md

@@ -0,0 +1,90 @@
+# Drupal Update Safety
+
+You are updating modules on a Drupal site. Follow these safety patterns.
+
+## Core Compatibility Checking
+
+Before attempting a major version update, verify the target version is compatible with the current Drupal core.
+
+### How to check
+```bash
+# Get current core version
+ddev composer show drupal/core --format=json | jq -r '.versions[0]'
+
+# Check all available versions of a module
+ddev composer show --all drupal/<module> --format=json
+```
+
+### Constraint interpretation
+- `^10.2` means `>=10.2.0 <11.0.0` — Drupal 10 only
+- `^11` means `>=11.0.0 <12.0.0` — Drupal 11 only
+- `^9.5 || ^10 || ^11` means any of those major versions
+- `>=10.2` means 10.2.0 and above (including 11.x)
+
+### Decision logic
+- If the target version requires a Drupal core version you don't have → find the highest compatible version instead
+- If no compatible version exists above current → skip the update and report why
+- If the module supports your core version → proceed with update
+
+## Update Categories
+
+### Security updates (auto-apply)
+- Identified via `composer audit`
+- Apply immediately without asking
+- These fix known vulnerabilities
+
+### Patch updates (X.Y.Z → X.Y.Z+1)
+- Backward compatible bug fixes
+- Safe to apply automatically
+- Rarely cause issues
+
+### Minor updates (X.Y → X.Y+1)
+- New features, backward compatible
+- May include deprecations
+- Usually safe but test afterward
+
+### Major updates (X → X+1)
+- May contain breaking changes
+- Require compatibility checking
+- May need config migration
+- Test thoroughly after applying
+
+## Post-Update Verification
+
+After every update:
+
+1. **Database updates:** `ddev drush updb -y`
+   - Read the output — note what hooks ran
+   - If it fails, the update may need manual intervention
+
+2. **Check for errors:** `ddev drush watchdog:show --count=10 --severity=Error`
+   - New errors after update indicate problems
+   - Compare to pre-update error count
+
+3. **Clear caches:** `ddev drush cr`
+   - Some updates require a cache rebuild to take effect
+
+4. **Export config:** `ddev drush cex -y`
+   - Some updates introduce new configuration
+   - Review what changed before committing
+
+5. **Run tests:** `bolt test --output=json`
+   - Verify no regressions
+   - If tests fail, the update introduced a problem
+
+## Common Drupal Update Patterns
+
+- **Admin theme updates (gin):** Often require `gin_toolbar` to be updated together
+- **Core updates:** Always update `drupal/core-recommended`, `drupal/core-composer-scaffold`, and `drupal/core-project-message` together
+- **Paragraphs ecosystem:** `drupal/paragraphs`, `drupal/entity_reference_revisions` are tightly coupled
+- **Media modules:** `drupal/media_library_form_element`, `drupal/focal_point`, `drupal/crop` may have interdependencies
+- **CKEditor modules:** `drupal/ckeditor5_premium_features` depends on core CKEditor version
+
+## Rollback
+
+If an update causes problems:
+```bash
+git checkout .
+git clean -fd
+```
+This restores composer.json, composer.lock, and config to pre-update state.

package/dist/ai/prompts/analyze-ticket.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Prompt template for ticket analysis — examines a Jira ticket (or description)
+ * against the site profile and produces an investigation plan.
+ */
+import type { AgentTask } from '../agent.js';
+import type { SiteProfile } from '../../types.js';
+export interface AnalyzeTicketContext {
+    /** Ticket key (e.g. PROJ-123) — empty if manual description. */
+    ticketKey: string;
+    /** Ticket summary/title. */
+    ticketSummary: string;
+    /** Full ticket description text. */
+    ticketDescription: string;
+    /** Ticket type (Bug, Task, Story, etc.). */
+    ticketType: string;
+    /** Ticket priority. */
+    ticketPriority: string;
+    /** Comments from the ticket (if available). */
+    ticketComments?: string[];
+    /** Site profile from bolt-inspect:profile. */
+    siteProfile: SiteProfile;
+    /** Recent git log (last ~20 commits). */
+    recentGitLog?: string;
+    /** Current bolt test results summary (if available). */
+    testResults?: string;
+}
+/**
+ * Build an AgentTask for analyzing a ticket.
+ */
+export declare function buildAnalyzeTicketTask(ctx: AnalyzeTicketContext): AgentTask;