@electriccitizen/bolt 0.1.0

package/modules/bolt_inspect/src/Service/SiteProfiler.php

@@ -0,0 +1,362 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Drupal\bolt_inspect\Service;
+
+use Drupal\Core\Entity\EntityFieldManagerInterface;
+use Drupal\Core\Entity\EntityTypeManagerInterface;
+use Drupal\Core\Extension\ModuleExtensionList;
+use Drupal\Core\Menu\MenuLinkTreeInterface;
+use Drupal\Core\Menu\MenuTreeParameters;
+use Drupal\Core\Routing\RouteProviderInterface;
+
+/**
+ * Builds a complete site profile for the Bolt test runner.
+ */
+class SiteProfiler {
+
+  public function __construct(
+    private readonly EntityTypeManagerInterface $entityTypeManager,
+    private readonly EntityFieldManagerInterface $entityFieldManager,
+    private readonly ModuleExtensionList $moduleExtensionList,
+    private readonly RouteProviderInterface $routeProvider,
+    private readonly MenuLinkTreeInterface $menuLinkTree,
+  ) {}
+
+  /**
+   * Build the full site profile.
+   *
+   * @return array<string, mixed>
+   */
+  public function profile(): array {
+    return [
+      'boltInspectVersion' => $this->getModuleVersion(),
+      'contentTypes' => $this->getContentTypes(),
+      'paragraphBundles' => $this->getParagraphBundles(),
+      'enabledModules' => $this->getEnabledModules(),
+      'routes' => $this->getRoutes(),
+      'mediaTypes' => $this->getMediaTypes(),
+      'menus' => $this->getMenus(),
+      'representativeUrls' => $this->getRepresentativeUrls(),
+    ];
+  }
+
+  /**
+   * Get the bolt_inspect module version from info.yml.
+   */
+  private function getModuleVersion(): string {
+    $info = $this->moduleExtensionList->getExtensionInfo('bolt_inspect');
+    return $info['version'] ?? 'unknown';
+  }
+
+  /**
+   * Get all content types with their field definitions.
+   *
+   * @return array<int, array<string, mixed>>
+   */
+  private function getContentTypes(): array {
+    $types = [];
+    $nodeTypes = $this->entityTypeManager->getStorage('node_type')->loadMultiple();
+
+    foreach ($nodeTypes as $nodeType) {
+      $bundle = $nodeType->id();
+      $fields = $this->getFieldDefinitions('node', $bundle);
+      $types[] = [
+        'id' => $bundle,
+        'label' => $nodeType->label(),
+        'fields' => $fields,
+      ];
+    }
+
+    return $types;
+  }
+
+  /**
+   * Get all paragraph bundles with their field definitions.
+   *
+   * @return array<int, array<string, mixed>>
+   */
+  private function getParagraphBundles(): array {
+    $bundles = [];
+
+    if (!$this->entityTypeManager->hasDefinition('paragraphs_type')) {
+      return $bundles;
+    }
+
+    $paragraphTypes = $this->entityTypeManager->getStorage('paragraphs_type')->loadMultiple();
+
+    foreach ($paragraphTypes as $paragraphType) {
+      $bundle = $paragraphType->id();
+      $fields = $this->getFieldDefinitions('paragraph', $bundle);
+      $bundles[] = [
+        'id' => $bundle,
+        'label' => $paragraphType->label(),
+        'fields' => $fields,
+      ];
+    }
+
+    return $bundles;
+  }
+
+  /**
+   * Get field definitions for an entity type + bundle.
+   *
+   * @return array<int, array<string, mixed>>
+   */
+  private function getFieldDefinitions(string $entityType, string $bundle): array {
+    $definitions = $this->entityFieldManager->getFieldDefinitions($entityType, $bundle);
+    $fields = [];
+
+    foreach ($definitions as $fieldName => $definition) {
+      // Skip base fields (nid, uuid, etc.) — only configurable fields.
+      if (!$definition instanceof \Drupal\field\FieldConfigInterface) {
+        continue;
+      }
+
+      $storage = $definition->getFieldStorageDefinition();
+      $fields[] = [
+        'name' => $fieldName,
+        'label' => $definition->getLabel(),
+        'type' => $definition->getType(),
+        'required' => $definition->isRequired(),
+        'cardinality' => $storage->getCardinality(),
+        'settings' => $definition->getSettings(),
+      ];
+    }
+
+    return $fields;
+  }
+
+  /**
+   * Get accessible frontend routes.
+   *
+   * @return string[]
+   */
+  private function getRoutes(): array {
+    $routes = [];
+
+    foreach ($this->routeProvider->getAllRoutes() as $name => $route) {
+      $path = $route->getPath();
+
+      // Skip admin, system, internal, and utility routes.
+      if (str_starts_with($path, '/admin')
+        || str_starts_with($path, '/batch')
+        || str_starts_with($path, '/devel')
+        || str_starts_with($path, '/editor')
+        || str_starts_with($path, '/entity_reference_autocomplete')
+        || str_starts_with($path, '/machine_name')
+        || str_starts_with($path, '/antibot')
+        || str_starts_with($path, '/ckeditor')
+        || str_starts_with($path, '/contextual')
+        || str_starts_with($path, '/history')
+        || str_starts_with($path, '/media')
+        || str_starts_with($path, '/node/add')
+        || str_starts_with($path, '/user')
+        || $path === '/<current>'
+        || $path === '/<front>'
+        || $path === '/<nolink>'
+        || $path === '/<none>'
+        || str_contains($name, 'system.')
+        || str_contains($name, 'entity.node.edit_form')
+        || str_contains($name, 'entity.node.delete_form')
+        || $route->getOption('_admin_route')
+        || str_contains($path, '{')
+      ) {
+        continue;
+      }
+
+      // Only include GET-able routes.
+      $methods = $route->getMethods();
+      if (!empty($methods) && !in_array('GET', $methods, TRUE)) {
+        continue;
+      }
+
+      $routes[] = $path;
+    }
+
+    return array_values(array_unique($routes));
+  }
+
+  /**
+   * Get list of enabled modules.
+   *
+   * @return string[]
+   */
+  private function getEnabledModules(): array {
+    $installed = $this->moduleExtensionList->getAllInstalledInfo();
+    return array_keys($installed);
+  }
+
+  /**
+   * Get media types.
+   *
+   * @return string[]
+   */
+  private function getMediaTypes(): array {
+    if (!$this->entityTypeManager->hasDefinition('media_type')) {
+      return [];
+    }
+
+    $mediaTypes = $this->entityTypeManager->getStorage('media_type')->loadMultiple();
+    return array_map(fn($t) => $t->id(), array_values($mediaTypes));
+  }
+
+  /**
+   * Get main menu structure (first level).
+   *
+   * @return array<int, array<string, mixed>>
+   */
+  private function getMenus(): array {
+    $parameters = new MenuTreeParameters();
+    $parameters->setMaxDepth(1);
+    $tree = $this->menuLinkTree->load('main', $parameters);
+    $manipulators = [
+      ['callable' => 'menu.default_tree_manipulators:checkAccess'],
+      ['callable' => 'menu.default_tree_manipulators:generateIndexAndSort'],
+    ];
+    $tree = $this->menuLinkTree->transform($tree, $manipulators);
+
+    $items = [];
+    foreach ($tree as $element) {
+      $link = $element->link;
+      $url = $link->getUrlObject();
+      try {
+        $path = $url->toString();
+      }
+      catch (\Exception) {
+        continue;
+      }
+      $items[] = [
+        'title' => $link->getTitle(),
+        'url' => $path,
+      ];
+    }
+
+    return [
+      [
+        'name' => 'main',
+        'items' => $items,
+      ],
+    ];
+  }
+
+  /**
+   * Build representative URLs for browser-smoke and visual-regression.
+   *
+   * Includes: homepage, main menu items, one node per content type.
+   *
+   * @return array<int, array<string, mixed>>
+   */
+  private function getRepresentativeUrls(): array {
+    $urls = [];
+
+    // Homepage.
+    $urls[] = [
+      'url' => '/',
+      'source' => 'homepage',
+      'label' => 'Homepage',
+    ];
+
+    // Main menu items.
+    $menus = $this->getMenus();
+    foreach ($menus as $menu) {
+      foreach ($menu['items'] as $item) {
+        $urls[] = [
+          'url' => $item['url'],
+          'source' => 'menu',
+          'label' => $item['title'],
+        ];
+      }
+    }
+
+    // Views with page displays.
+    if (\Drupal::moduleHandler()->moduleExists('views')) {
+      $viewsUrls = $this->getViewsPageUrls();
+      // Only add views URLs that aren't already covered by menu items.
+      $existingPaths = array_map(fn($u) => $u['url'], $urls);
+      foreach ($viewsUrls as $viewUrl) {
+        if (!in_array($viewUrl['url'], $existingPaths, TRUE)) {
+          $urls[] = $viewUrl;
+        }
+      }
+    }
+
+    // One node per content type (most recent published).
+    $nodeTypes = $this->entityTypeManager->getStorage('node_type')->loadMultiple();
+    $nodeStorage = $this->entityTypeManager->getStorage('node');
+
+    foreach ($nodeTypes as $nodeType) {
+      $bundle = $nodeType->id();
+      $query = $nodeStorage->getQuery()
+        ->accessCheck(TRUE)
+        ->condition('type', $bundle)
+        ->condition('status', 1)
+        ->sort('created', 'DESC')
+        ->range(0, 1);
+      $nids = $query->execute();
+
+      if (!empty($nids)) {
+        $nid = reset($nids);
+        $node = $nodeStorage->load($nid);
+        if ($node && $node->hasLinkTemplate('canonical')) {
+          try {
+            $url = $node->toUrl()->toString();
+            $urls[] = [
+              'url' => $url,
+              'source' => 'content_type',
+              'label' => $nodeType->label() . ': ' . $node->label(),
+              'contentType' => $bundle,
+            ];
+          }
+          catch (\Exception) {
+            // Node may not have a routable path.
+          }
+        }
+      }
+    }
+
+    return $urls;
+  }
+
+  /**
+   * Get URLs for all enabled views with page displays.
+   *
+   * @return array<int, array<string, mixed>>
+   */
+  private function getViewsPageUrls(): array {
+    $urls = [];
+    $views = \Drupal\views\Views::getEnabledViews();
+
+    foreach ($views as $view) {
+      foreach ($view->get('display') as $displayId => $display) {
+        if (($display['display_plugin'] ?? '') !== 'page') {
+          continue;
+        }
+        $path = $display['display_options']['path'] ?? NULL;
+        if (!$path || str_contains($path, '%') || str_contains($path, '{')) {
+          continue;
+        }
+        // Skip admin paths and Drupal defaults nobody visits directly.
+        if (str_starts_with($path, 'admin')
+          || $path === 'node'
+          || $path === 'rss.xml'
+          || $path === 'search'
+        ) {
+          continue;
+        }
+
+        $urls[] = [
+          'url' => '/' . ltrim($path, '/'),
+          'source' => 'view',
+          'label' => 'View: ' . ($view->label() ?? $view->id()) . ' (' . ($display['display_title'] ?? $displayId) . ')',
+          'viewId' => $view->id(),
+          'displayId' => $displayId,
+        ];
+      }
+    }
+
+    return $urls;
+  }
+
+}

package/modules/bolt_inspect/src/Service/TestEntityTracker.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Drupal\bolt_inspect\Service;
+
+use Drupal\Core\Database\Connection;
+use Drupal\Core\Entity\EntityTypeManagerInterface;
+use Drupal\Core\State\StateInterface;
+
+/**
+ * Tracks test entities created by bolt-inspect:generate for cleanup.
+ */
+class TestEntityTracker {
+
+  private const STATE_KEY = 'bolt_inspect.tracked_entities';
+
+  public function __construct(
+    private readonly StateInterface $state,
+    private readonly EntityTypeManagerInterface $entityTypeManager,
+  ) {}
+
+  /**
+   * Track a created entity for later cleanup.
+   */
+  public function track(string $entityType, int $id, string $label = ''): void {
+    $tracked = $this->getTracked();
+    $tracked[] = [
+      'entity_type' => $entityType,
+      'id' => $id,
+      'label' => $label,
+      'created' => time(),
+    ];
+    $this->state->set(self::STATE_KEY, $tracked);
+  }
+
+  /**
+   * Get all tracked entities.
+   *
+   * @return array<int, array{entity_type: string, id: int, label: string, created: int}>
+   */
+  public function getTracked(): array {
+    return $this->state->get(self::STATE_KEY, []);
+  }
+
+  /**
+   * Check if any tracked entities exist.
+   */
+  public function hasTracked(): bool {
+    return !empty($this->getTracked());
+  }
+
+  /**
+   * Delete all tracked entities in reverse order and clear tracking state.
+   *
+   * @return array<string, int>
+   *   Count of deleted entities per type.
+   */
+  public function cleanupAll(): array {
+    $tracked = $this->getTracked();
+    $counts = [];
+
+    // Delete in reverse order (children before parents).
+    foreach (array_reverse($tracked) as $entry) {
+      $entityType = $entry['entity_type'];
+      $id = $entry['id'];
+      try {
+        $storage = $this->entityTypeManager->getStorage($entityType);
+        $entity = $storage->load($id);
+        if ($entity) {
+          $entity->delete();
+          $counts[$entityType] = ($counts[$entityType] ?? 0) + 1;
+        }
+      }
+      catch (\Exception $e) {
+        // Entity API delete may fail if hooks (e.g. auto_entitylabel) interfere.
+        // Ensure the entity has a valid title and retry.
+        try {
+          $entity = $storage->load($id);
+          if ($entity && method_exists($entity, 'setTitle')) {
+            $entity->setTitle('Bolt Cleanup');
+          }
+          if ($entity) {
+            $entity->delete();
+            $counts[$entityType] = ($counts[$entityType] ?? 0) + 1;
+          }
+        }
+        catch (\Exception) {
+          // Still failed — continue with others.
+        }
+      }
+    }
+
+    $this->state->delete(self::STATE_KEY);
+    return $counts;
+  }
+
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@electriccitizen/bolt",
+  "version": "0.1.0",
+  "description": "CLI tool for Drupal 11+ site testing and operations",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/electriccitizen/bolt.git"
+  },
+  "bin": {
+    "bolt": "./dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "modules/bolt_inspect/",
+    "scripts/setup.sh",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepare": "tsc",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "^4.11.1",
+    "commander": "^13.1.0",
+    "pixelmatch": "^7.1.0",
+    "playwright": "^1.52.0",
+    "pngjs": "^7.0.0",
+    "yaml": "^2.7.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "@types/pngjs": "^6.0.5",
+    "typescript": "^5.8.0",
+    "vitest": "^4.0.18"
+  }
+}

package/scripts/setup.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#
+# Set up bolt for development (git clone) or verify an npm global install.
+#
+# Dev setup (from git clone):
+#   cd ~/projects/bolt && ./scripts/setup.sh
+#
+# Post npm install:
+#   bolt doctor && npx playwright install chromium
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_DIR"
+
+echo "Installing dependencies..."
+npm install
+
+echo "Building TypeScript..."
+npm run build
+
+echo "Linking CLI globally..."
+npm link
+
+echo "Installing Playwright browsers..."
+npx playwright install chromium
+
+echo ""
+echo "Setup complete."
+echo "  bolt --version    Verify installation"
+echo "  bolt doctor       Check environment"
+echo ""