@bluefly/openstandardagents 0.4.5 → 0.4.6

package/dist/adapters/drupal/drupal-utils.js

@@ -0,0 +1,313 @@
+/**
+ * Drupal Adapter Shared Utilities
+ *
+ * Extracted from adapter.ts, generator.ts, and manifest-exporter.ts
+ * to eliminate code duplication across the Drupal adapter layer.
+ *
+ * Contains:
+ * - Name sanitization (sanitizeModuleName, toClassName, toLabel)
+ * - Drupal-specific validation helpers
+ * - Composer/Info YAML generation helpers
+ * - OSSA-to-Drupal tool mapping (mapOssaToolToDrupalTool)
+ * - Shared TypeScript interfaces
+ *
+ * SOLID: Single Responsibility - Drupal utility functions only
+ * DRY: Single source of truth for all shared Drupal adapter logic
+ */
+// ===================================================================
+// Name Sanitization Utilities
+// ===================================================================
+/**
+ * Sanitize a name for use as a Drupal module machine name.
+ *
+ * Drupal machine names must be lowercase, alphanumeric with underscores,
+ * cannot start with a digit, and should not have leading/trailing underscores.
+ *
+ * @param name - Raw name string
+ * @returns Sanitized Drupal-compatible machine name
+ */
+export function sanitizeModuleName(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9_]/g, '_')
+        .replace(/^[0-9]+/, '')
+        .replace(/_+/g, '_')
+        .replace(/^_|_$/g, '');
+}
+/**
+ * Convert a Drupal module machine name to a PascalCase class name.
+ *
+ * Example: 'content_moderator' -> 'ContentModerator'
+ *
+ * @param moduleName - Drupal module machine name (snake_case)
+ * @returns PascalCase class name
+ */
+export function toClassName(moduleName) {
+    return moduleName
+        .split('_')
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
+}
+/**
+ * Convert a kebab-case or snake_case name to a Title Case label.
+ *
+ * Example: 'content_moderator' -> 'Content Moderator'
+ * Example: 'content-moderator' -> 'Content Moderator'
+ *
+ * @param name - Raw name string
+ * @returns Title Case label
+ */
+export function toLabel(name) {
+    return name.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+}
+// ===================================================================
+// Validation Utilities
+// ===================================================================
+/**
+ * Perform Drupal-specific validation on an OSSA manifest.
+ *
+ * Checks that the module name follows Drupal conventions and adds
+ * appropriate warnings. This is meant to be called after base validation
+ * and its results merged into the caller's error/warning arrays.
+ *
+ * @param manifest - OSSA agent manifest
+ * @returns Object containing Drupal-specific errors and warnings
+ */
+export function validateDrupalCompatibility(manifest) {
+    const errors = [];
+    const warnings = [];
+    const name = manifest.metadata?.name;
+    if (name && !/^[a-z0-9_]+$/.test(name)) {
+        warnings.push({
+            message: 'Module name should only contain lowercase letters, numbers, and underscores',
+            path: 'metadata.name',
+            suggestion: `Use: ${sanitizeModuleName(name)}`,
+        });
+    }
+    return { errors, warnings };
+}
+/**
+ * Build a complete ValidationResult from accumulated errors and warnings.
+ *
+ * @param errors - Array of validation errors
+ * @param warnings - Array of validation warnings
+ * @returns ValidationResult with proper undefined handling
+ */
+export function buildValidationResult(errors, warnings) {
+    return {
+        valid: errors.length === 0,
+        errors: errors.length > 0 ? errors : undefined,
+        warnings: warnings.length > 0 ? warnings : undefined,
+    };
+}
+// ===================================================================
+// Composer.json Generation
+// ===================================================================
+/**
+ * Generate a base composer.json for a Drupal module from an OSSA manifest.
+ *
+ * This produces the common structure shared by adapter.ts and generator.ts.
+ * Callers can extend the returned object with additional fields before
+ * serializing to JSON.
+ *
+ * @param manifest - OSSA agent manifest
+ * @param moduleName - Sanitized Drupal module name
+ * @param options - Additional Drupal module options
+ * @returns DrupalComposerJson object (serialize with JSON.stringify)
+ */
+export function buildComposerJson(manifest, moduleName, options) {
+    return {
+        name: `drupal/${moduleName}`,
+        type: 'drupal-module',
+        description: manifest.metadata?.description || 'OSSA agent module',
+        keywords: ['Drupal', 'OSSA', 'AI', 'Agent'],
+        license: manifest.metadata?.license || options?.license || 'GPL-2.0-or-later',
+        require: {
+            'drupal/core': options?.coreVersion || '^10 || ^11',
+            'drupal/ai': '^1.0',
+            'drupal/ai_agents': '^1.3',
+            'drupal/tool': '^1.0@alpha',
+        },
+        extra: {
+            ossa: {
+                version: manifest.metadata?.version,
+                apiVersion: manifest.apiVersion,
+                kind: manifest.kind,
+            },
+        },
+    };
+}
+// ===================================================================
+// Info YAML Generation
+// ===================================================================
+/**
+ * Generate the core .info.yml content shared between adapters.
+ *
+ * Produces the minimal OSSA metadata block that both adapter.ts and
+ * generator.ts include in their info YAML files.
+ *
+ * @param manifest - OSSA agent manifest
+ * @param moduleName - Sanitized Drupal module name
+ * @param options - Additional Drupal module options
+ * @returns YAML string for the .info.yml file
+ */
+export function generateBaseInfoYml(manifest, moduleName, options) {
+    const coreVersion = options?.coreVersion || '^10 || ^11';
+    const packageGroup = options?.packageGroup || 'OSSA Agents';
+    return `name: '${manifest.metadata?.name || moduleName}'
+type: module
+description: '${manifest.metadata?.description || 'OSSA agent module'}'
+core_version_requirement: ${coreVersion}
+package: '${packageGroup}'
+
+dependencies:
+  - ai:ai
+  - ai:ai_agents
+
+# OSSA metadata
+ossa:
+  version: '${manifest.metadata?.version || '1.0.0'}'
+  api_version: '${manifest.apiVersion || 'ossa/v{{VERSION}}'}'
+  kind: '${manifest.kind || 'Agent'}'
+`;
+}
+// ===================================================================
+// Capability / Tool Utilities
+// ===================================================================
+/**
+ * Extract capabilities as string array from an OSSA manifest.
+ *
+ * Handles: (1) array of strings or { name } objects, (2) object with grants[]
+ * (e.g. { policy, grants: [{ capability: '...' }] }), (3) missing -> [].
+ *
+ * @param manifest - OSSA agent manifest
+ * @returns Array of capability name strings
+ */
+export function extractCapabilities(manifest) {
+    const raw = manifest.spec?.capabilities;
+    if (raw == null)
+        return [];
+    if (Array.isArray(raw)) {
+        return raw.map((c) => typeof c === 'string' ? c : c.name || '');
+    }
+    if (typeof raw === 'object' &&
+        Array.isArray(raw.grants)) {
+        return raw.grants
+            .map((g) => g.capability)
+            .filter((s) => typeof s === 'string');
+    }
+    return [];
+}
+/**
+ * Extract tools as typed array from an OSSA manifest.
+ *
+ * @param manifest - OSSA agent manifest
+ * @returns Array of tool entries (empty if spec.tools is missing or not an array)
+ */
+export function extractTools(manifest) {
+    const raw = manifest.spec?.tools;
+    return Array.isArray(raw) ? raw : [];
+}
+/**
+ * Map an OSSA spec.tools[] entry to a Drupal Tool API plugin definition.
+ *
+ * This creates the structure used by Drupal's ai_agents contrib module
+ * to register tools as Drupal plugins. The output can be used to generate
+ * PHP plugin annotations or YAML tool definitions.
+ *
+ * @param tool - OSSA tool entry from spec.tools[]
+ * @param moduleName - Sanitized Drupal module name (used as provider)
+ * @returns DrupalToolDefinition with all plugin metadata
+ */
+export function mapOssaToolToDrupalTool(tool, moduleName) {
+    const toolName = tool.name || 'unknown_tool';
+    const toolId = `${moduleName}_${sanitizeModuleName(toolName)}`;
+    const toolLabel = toLabel(toolName);
+    const toolDescription = tool.description || `Tool: ${toolName}`;
+    const toolType = tool.type || 'api';
+    return {
+        id: toolId,
+        label: toolLabel,
+        description: toolDescription,
+        category: 'OSSA Agent Tools',
+        type: toolType,
+        provider: moduleName,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotation: {
+            id: toolId,
+            label: toolLabel,
+            description: toolDescription,
+        },
+    };
+}
+/**
+ * Map all tools from an OSSA manifest to Drupal Tool API plugin definitions.
+ *
+ * Convenience wrapper around mapOssaToolToDrupalTool for batch processing.
+ *
+ * @param manifest - OSSA agent manifest
+ * @param moduleName - Sanitized Drupal module name
+ * @returns Array of DrupalToolDefinition objects
+ */
+export function mapAllOssaToolsToDrupal(manifest, moduleName) {
+    const tools = extractTools(manifest);
+    return tools.map((tool) => mapOssaToolToDrupalTool(tool, moduleName));
+}
+// ===================================================================
+// PHP Tool Plugin Stub Generation (shared with manifest-exporter)
+// ===================================================================
+/**
+ * Escape a string for safe inclusion inside PHP single-quoted strings.
+ */
+export function escapePhpString(str) {
+    return str.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/**
+ * Map a JSON Schema type to a PHP/Drupal typed data type string.
+ */
+export function jsonSchemaTypeToPHP(jsonType) {
+    const typeMap = {
+        string: 'string',
+        number: 'float',
+        integer: 'integer',
+        boolean: 'boolean',
+        array: 'list',
+        object: 'map',
+    };
+    return typeMap[jsonType] || 'string';
+}
+/**
+ * Build a PHP array literal from a JSON Schema definition for Drupal Tool API.
+ *
+ * @param schema - JSON Schema object (properties, required)
+ * @returns PHP array literal string
+ */
+export function buildSchemaDefinitionArray(schema) {
+    if (!schema || Object.keys(schema).length === 0) {
+        return '[]';
+    }
+    const properties = schema.properties;
+    if (!properties || Object.keys(properties).length === 0) {
+        return '[]';
+    }
+    const required = schema.required || [];
+    const entries = [];
+    for (const [propName, propDef] of Object.entries(properties)) {
+        const phpType = jsonSchemaTypeToPHP(propDef.type || 'string');
+        const description = propDef.description
+            ? escapePhpString(propDef.description)
+            : `The ${propName} parameter`;
+        const isRequired = required.includes(propName) ? 'TRUE' : 'FALSE';
+        entries.push(`      '${propName}' => [
+        'type' => '${phpType}',
+        'label' => '${toLabel(propName)}',
+        'description' => '${escapePhpString(description)}',
+        'required' => ${isRequired},
+      ]`);
+    }
+    return `[
+${entries.join(',\n')},
+    ]`;
+}
+//# sourceMappingURL=drupal-utils.js.map

package/dist/adapters/drupal/generator.d.ts

@@ -2,27 +2,34 @@
  * Drupal Module Generator for OSSA Agents
  *
  * Generates complete, production-ready Drupal modules from OSSA agent manifests.
+ * Uses modern PHP 8 syntax: attributes instead of annotations, OO hook classes,
+ * constructor property promotion, and Drupal AI module integration.
  *
  * Generated modules include:
  * - MODULE.info.yml (module metadata)
  * - MODULE.services.yml (DI configuration)
- * - src/Service/AgentExecutor (wrapper around ossa/symfony-bundle)
- * - src/Plugin/QueueWorker (async execution support)
- * - src/Controller (admin UI and API endpoints)
- * - src/Entity (agent result storage)
- * - src/Form (configuration forms)
- * - MODULE.module (Drupal hooks: entity_presave, cron, etc.)
+ * - src/Service/AgentExecutorService.php (uses drupal/ai provider system)
+ * - src/Plugin/QueueWorker/ (async execution with #[QueueWorker] attribute)
+ * - src/Plugin/Tool/ (Tool API plugins with #[Tool] attributes)
+ * - src/Plugin/Action/ (Action plugins for CUD tools with #[Action] attributes)
+ * - src/Plugin/Condition/ (Condition plugins from safety guardrails with #[Condition] attributes)
+ * - src/Controller/ (admin UI and API endpoints)
+ * - src/Entity/ (agent result storage with #[ContentEntityType] attribute)
+ * - src/Form/ (configuration forms)
+ * - src/Hook/ (OO hook classes with #[Hook] attributes)
+ * - MODULE.module (minimal procedural hooks)
  * - templates/*.html.twig (Twig templates)
- * - composer.json (with ossa/symfony-bundle dependency)
+ * - composer.json (with drupal/ai, drupal/ai_agents, drupal/tool)
  * - config/schema/MODULE.schema.yml (configuration schema)
  * - config/install/*.yml (default configuration)
+ * - config/install/eca.model.*.yml (ECA event-condition-action models)
  *
  * SOLID Principles:
  * - Single Responsibility: Drupal module generation only
- * - Dependency Inversion: Uses ossa/symfony-bundle for agent execution
+ * - Dependency Inversion: Uses Drupal AI module for LLM provider access
  * - Interface Segregation: Separate interfaces for different module components
  *
- * DRY: Reuses Symfony bundle patterns, no duplication
+ * DRY: Reuses Drupal AI module patterns, no duplication
  */
 import { BaseAdapter } from '../base/adapter.interface.js';
 import type { OssaAgent, ExportOptions, ExportResult, ValidationResult } from '../base/adapter.interface.js';
@@ -39,13 +46,21 @@ export interface DrupalModuleGeneratorOptions extends ExportOptions {
     includeHooks?: boolean;
     /** Include Views integration */
     includeViews?: boolean;
+    /** Include Tool API plugins for each spec.tools[] entry */
+    includeToolPlugins?: boolean;
+    /** Include ECA model YAML for event-driven triggers */
+    includeEcaModels?: boolean;
+    /** Include Action plugins for CUD tools (create/update/delete) */
+    includeActionPlugins?: boolean;
+    /** Include Condition plugins from safety guardrails */
+    includeConditionPlugins?: boolean;
     /** Drupal core version requirement */
     coreVersion?: string;
 }
 export declare class DrupalModuleGenerator extends BaseAdapter {
     readonly platform = "drupal";
     readonly displayName = "Drupal Module (Full)";
-    readonly description = "Production-ready Drupal module with OSSA/Symfony integration";
+    readonly description = "Production-ready Drupal module with OSSA/AI module integration";
     readonly status: "beta";
     readonly supportedVersions: string[];
     /**
@@ -69,17 +84,41 @@ export declare class DrupalModuleGenerator extends BaseAdapter {
      */
     private generateServicesYml;
     /**
-     * Generate composer.json with ossa/symfony-bundle dependency
+     * Generate composer.json with Drupal AI module dependencies
      */
     private generateComposerJson;
     /**
-     * Generate MODULE.module with Drupal hooks
+     * Generate MODULE.module with minimal procedural hooks.
+     *
+     * Most hooks are now implemented as OO classes using PHP 8 #[Hook] attributes
+     * in src/Hook/. Only hook_help remains procedural as a legacy convention.
      */
     private generateModuleHooks;
+    /**
+     * Generate OO hook classes using PHP 8 #[Hook] attributes.
+     *
+     * Generates:
+     * - src/Hook/CronHooks.php (hook_cron)
+     * - src/Hook/EntityHooks.php (hook_entity_presave)
+     * - src/Hook/ThemeHooks.php (hook_theme)
+     */
+    private generateHookClasses;
+    /**
+     * Generate src/Hook/CronHooks.php
+     */
+    private generateCronHookClass;
+    /**
+     * Generate src/Hook/EntityHooks.php
+     */
+    private generateEntityHookClass;
+    /**
+     * Generate src/Hook/ThemeHooks.php
+     */
+    private generateThemeHookClass;
     /**
      * Generate src/Service/AgentExecutorService.php
      *
-     * Wraps Symfony bundle AgentExecutor with Drupal-specific features
+     * Uses Drupal AI module for LLM provider integration
      */
     private generateAgentExecutorService;
     /**
@@ -114,6 +153,128 @@ export declare class DrupalModuleGenerator extends BaseAdapter {
      * Generate MODULE.links.menu.yml
      */
     private generateMenuLinks;
+    /**
+     * Generate a Drupal Tool API plugin class for a single OSSA tool.
+     *
+     * Uses PHP 8 #[Tool] attributes (not annotations) and implements
+     * ContainerFactoryPluginInterface for proper dependency injection.
+     */
+    private generateToolPlugin;
+    /**
+     * Generate tool_ai_connector config YAML for a single tool.
+     *
+     * Registers the tool with Drupal's Tool API AI connector system
+     * so it is discoverable by AI-powered modules.
+     */
+    private generateToolAiConnectorConfig;
+    /**
+     * Build a PHP array literal from a JSON Schema definition.
+     *
+     * Converts OSSA tool input/output schema (JSON Schema) into a PHP array
+     * that Drupal's Tool API can consume for input/output definitions.
+     */
+    private buildSchemaDefinitionArray;
+    /**
+     * Map a JSON Schema type to a PHP/Drupal typed data type string.
+     */
+    private jsonSchemaTypeToPHP;
+    /**
+     * Escape a string for safe inclusion inside PHP single-quoted strings.
+     */
+    private escapePhpString;
+    /**
+     * Extract ECA event definitions from the manifest.
+     *
+     * Looks for extensions.drupal.eca_events in the manifest. Each entry
+     * is a string like 'entity:node:presave' or 'content_entity:presave'.
+     */
+    private extractEcaEvents;
+    /**
+     * Generate ECA model YAML config files for each event in eca_events.
+     *
+     * Creates config/install/eca.model.MODULE_on_EVENT.yml files that define
+     * the Event-Condition-Action models for Drupal's ECA module. Each model
+     * wires an event trigger to an OSSA agent condition check and tool execution.
+     */
+    private generateEcaModels;
+    /**
+     * Map ECA event parts to a Drupal ECA plugin ID.
+     *
+     * Converts OSSA event notation (e.g., ['entity', 'node', 'presave'])
+     * to ECA plugin IDs (e.g., 'content_entity:presave').
+     */
+    private mapEcaEventToPluginId;
+    /**
+     * Build ECA event configuration from event parts.
+     *
+     * Returns a key-value map that becomes the configuration block
+     * under the event entry in the ECA model YAML.
+     */
+    private buildEcaEventConfiguration;
+    /**
+     * Escape a string for safe inclusion in YAML single-quoted values.
+     */
+    private escapeYamlString;
+    /**
+     * Indent a key-value object as YAML at a given indentation level.
+     */
+    private indentYamlObject;
+    /**
+     * Generate Action plugin classes for tools with CUD operations.
+     *
+     * Filters tools where the operation field matches create, update, or delete,
+     * and generates a Drupal Action plugin class for each. Tools without an
+     * explicit operation field are skipped.
+     *
+     * Uses PHP 8 #[Action] attributes and implements ContainerFactoryPluginInterface.
+     */
+    private generateActionPlugins;
+    /**
+     * Infer the entity type a tool operates on from its metadata.
+     *
+     * Checks tool.config.entity_type, falls back to 'node'.
+     */
+    private inferEntityType;
+    /**
+     * Generate a single Action plugin PHP class.
+     *
+     * Produces a Drupal Action plugin using PHP 8 #[Action] attribute syntax,
+     * constructor property promotion, and ContainerFactoryPluginInterface.
+     */
+    private generateActionPluginClass;
+    /**
+     * Generate Condition plugin classes from OSSA safety guardrails.
+     *
+     * Maps spec.safety.guardrails[] entries to Drupal Condition plugins.
+     * Also always generates an AgentEnabledCondition that checks whether
+     * the OSSA agent is enabled in module configuration.
+     *
+     * Uses PHP 8 #[Condition] attributes and ConditionPluginBase.
+     */
+    private generateConditionPlugins;
+    /**
+     * Generate the AgentEnabledCondition plugin class.
+     *
+     * This condition checks whether the OSSA agent is enabled in module
+     * configuration. Used by ECA models to gate event-driven execution.
+     */
+    private generateAgentEnabledConditionClass;
+    /**
+     * Generate a Condition plugin class for a specific safety guardrail.
+     *
+     * Maps OSSA spec.safety.guardrails[] entries to Drupal Condition plugins.
+     * Supports 'input' guardrails (check blocked patterns) and 'output' guardrails
+     * (check response constraints like maxLength).
+     */
+    private generateGuardrailConditionClass;
+    /**
+     * Generate a Drupal Recipe YAML file for composable installation.
+     *
+     * Recipes are Drupal's modern approach to distributing reusable
+     * configuration sets. This generates a recipe that installs and
+     * configures the OSSA agent module along with its dependencies.
+     */
+    private generateRecipe;
     /**
      * Generate config/schema/MODULE.schema.yml
      */
@@ -138,13 +299,5 @@ export declare class DrupalModuleGenerator extends BaseAdapter {
      * Generate INSTALL.md
      */
     private generateInstallGuide;
-    /**
-     * Sanitize module name for Drupal
-     */
-    private sanitizeModuleName;
-    /**
-     * Convert module name to class name (PascalCase)
-     */
-    private toClassName;
 }
 //# sourceMappingURL=generator.d.ts.map