create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/hooks/unified/hook-interface.js

@@ -0,0 +1,159 @@
+/**
+ * Unified Hook Interface
+ * Story GEMINI-INT.8 - Cross-CLI Hook Abstraction
+ *
+ * Write hooks once, run on both Claude Code and Gemini CLI.
+ */
+
+/**
+ * Hook lifecycle event mapping between CLIs
+ */
+const EVENT_MAPPING = {
+  // AIOX Event -> { claude: ClaudeEvent, gemini: GeminiEvent }
+  sessionStart: { claude: null, gemini: 'SessionStart' },
+  beforeAgent: { claude: 'PreToolUse', gemini: 'BeforeAgent' },
+  beforeTool: { claude: 'PreToolUse', gemini: 'BeforeTool' },
+  afterTool: { claude: 'PostToolUse', gemini: 'AfterTool' },
+  sessionEnd: { claude: 'Stop', gemini: 'SessionEnd' },
+};
+
+/**
+ * Base class for unified hooks
+ */
+class UnifiedHook {
+  /**
+   * Create a unified hook
+   * @param {Object} config - Hook configuration
+   * @param {string} config.name - Hook name
+   * @param {string} config.event - AIOX event name
+   * @param {string} [config.matcher='*'] - Tool/event matcher pattern
+   */
+  constructor(config) {
+    this.name = config.name;
+    this.event = config.event;
+    this.matcher = config.matcher || '*';
+    this.timeout = config.timeout || 5000;
+  }
+
+  /**
+   * Execute the hook (override in subclass)
+   * @param {HookContext} context - Execution context
+   * @returns {Promise<HookResult>} Hook result
+   */
+  async execute(context) {
+    throw new Error('execute() must be implemented by subclass');
+  }
+
+  /**
+   * Get Claude Code hook configuration
+   * @returns {Object|null} Claude hook config or null if not supported
+   */
+  toClaudeConfig() {
+    const claudeEvent = EVENT_MAPPING[this.event]?.claude;
+    if (!claudeEvent) return null;
+
+    // TODO: Restore when runners/ directory is implemented (Story MIS-2)
+    // Runners not yet implemented - path .aiox-core/hooks/unified/runners/ does not exist
+    return null;
+
+    // return {
+    //   event: claudeEvent,
+    //   matcher: this.matcher,
+    //   handler: `node .aiox-core/hooks/unified/runners/claude-runner.js ${this.name}`,
+    // };
+  }
+
+  /**
+   * Get Gemini CLI hook configuration
+   * @returns {Object} Gemini hook config
+   */
+  toGeminiConfig() {
+    const geminiEvent = EVENT_MAPPING[this.event]?.gemini;
+
+    // TODO: Restore when runners/ directory is implemented (Story MIS-2)
+    // Runners not yet implemented - path .aiox-core/hooks/unified/runners/ does not exist
+    return null;
+
+    // return {
+    //   matcher: this.matcher,
+    //   hooks: [
+    //     {
+    //       name: this.name,
+    //       type: 'command',
+    //       command: `node .aiox-core/hooks/unified/runners/gemini-runner.js ${this.name}`,
+    //       timeout: this.timeout,
+    //     },
+    //   ],
+    // };
+  }
+}
+
+/**
+ * Hook execution context
+ * @typedef {Object} HookContext
+ * @property {string} projectDir - Project directory
+ * @property {string} sessionId - Session identifier
+ * @property {string} [toolName] - Tool being executed (for tool hooks)
+ * @property {Object} [toolArgs] - Tool arguments
+ * @property {Object} [toolResult] - Tool result (for after hooks)
+ * @property {string} provider - Current provider ('claude' or 'gemini')
+ */
+
+/**
+ * Hook execution result
+ * @typedef {Object} HookResult
+ * @property {'allow'|'block'|'modify'} status - Result status
+ * @property {string} [message] - Status message
+ * @property {Object} [contextInjection] - Context to inject
+ * @property {Object} [modifiedArgs] - Modified tool arguments
+ */
+
+/**
+ * Create context from environment (works for both CLIs)
+ * @param {string} provider - Provider name
+ * @returns {HookContext} Execution context
+ */
+function createContext(provider) {
+  const isGemini = provider === 'gemini';
+
+  return {
+    projectDir: isGemini
+      ? process.env.GEMINI_PROJECT_DIR || process.cwd()
+      : process.env.CLAUDE_PROJECT_DIR || process.cwd(),
+    sessionId: isGemini
+      ? process.env.GEMINI_SESSION_ID || `session-${Date.now()}`
+      : process.env.CLAUDE_SESSION_ID || `session-${Date.now()}`,
+    provider,
+  };
+}
+
+/**
+ * Format result for CLI consumption
+ * @param {HookResult} result - Hook result
+ * @param {string} provider - Provider name
+ * @returns {string} JSON string
+ */
+function formatResult(result, provider) {
+  if (provider === 'gemini') {
+    // Gemini expects specific format
+    return JSON.stringify({
+      status: result.status === 'block' ? 'block' : 'success',
+      message: result.message,
+      contextInjection: result.contextInjection,
+    });
+  }
+
+  // Claude format
+  return JSON.stringify({
+    continue: result.status !== 'block',
+    message: result.message,
+    context: result.contextInjection,
+  });
+}
+
+module.exports = {
+  UnifiedHook,
+  EVENT_MAPPING,
+  createContext,
+  formatResult,
+};

package/template/.aiox-core/hooks/unified/hook-registry.js

@@ -0,0 +1,143 @@
+/**
+ * Unified Hook Registry
+ * Story GEMINI-INT.8 - Cross-CLI Hook Abstraction
+ *
+ * Central registry for unified hooks.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { UnifiedHook, EVENT_MAPPING } = require('./hook-interface');
+
+/**
+ * Hook Registry - manages all unified hooks
+ */
+class HookRegistry {
+  constructor() {
+    this.hooks = new Map();
+  }
+
+  /**
+   * Register a hook
+   * @param {UnifiedHook} hook - Hook to register
+   */
+  register(hook) {
+    if (!(hook instanceof UnifiedHook)) {
+      throw new Error('Hook must extend UnifiedHook');
+    }
+    this.hooks.set(hook.name, hook);
+  }
+
+  /**
+   * Get a hook by name
+   * @param {string} name - Hook name
+   * @returns {UnifiedHook|undefined}
+   */
+  get(name) {
+    return this.hooks.get(name);
+  }
+
+  /**
+   * Get all hooks for an event
+   * @param {string} event - Event name
+   * @returns {UnifiedHook[]}
+   */
+  getByEvent(event) {
+    return Array.from(this.hooks.values()).filter((h) => h.event === event);
+  }
+
+  /**
+   * Generate Claude Code hooks configuration
+   * @returns {Object} Claude hooks config for .claude/settings.json
+   */
+  toClaudeConfig() {
+    const config = {};
+
+    for (const hook of this.hooks.values()) {
+      const claudeConfig = hook.toClaudeConfig();
+      if (!claudeConfig) continue;
+
+      const event = claudeConfig.event;
+      if (!config[event]) {
+        config[event] = [];
+      }
+
+      config[event].push({
+        matcher: claudeConfig.matcher,
+        command: claudeConfig.handler,
+      });
+    }
+
+    return config;
+  }
+
+  /**
+   * Generate Gemini CLI hooks configuration
+   * @returns {Object} Gemini hooks config for .gemini/settings.json
+   */
+  toGeminiConfig() {
+    const config = {};
+
+    for (const hook of this.hooks.values()) {
+      const geminiConfig = hook.toGeminiConfig();
+      const event = EVENT_MAPPING[hook.event]?.gemini;
+
+      if (!event) continue;
+
+      if (!config[event]) {
+        config[event] = [];
+      }
+
+      config[event].push(geminiConfig);
+    }
+
+    return { hooks: config };
+  }
+
+  /**
+   * Write configurations to project
+   * @param {string} projectDir - Project directory
+   */
+  async writeConfigs(projectDir) {
+    // Write Gemini config
+    const geminiDir = path.join(projectDir, '.gemini');
+    if (!fs.existsSync(geminiDir)) {
+      fs.mkdirSync(geminiDir, { recursive: true });
+    }
+
+    const geminiConfig = this.toGeminiConfig();
+    const geminiSettingsPath = path.join(geminiDir, 'settings.json');
+
+    let existingGemini = {};
+    if (fs.existsSync(geminiSettingsPath)) {
+      existingGemini = JSON.parse(fs.readFileSync(geminiSettingsPath, 'utf8'));
+    }
+
+    const mergedGemini = {
+      ...existingGemini,
+      hooks: {
+        ...existingGemini.hooks,
+        ...geminiConfig.hooks,
+      },
+    };
+
+    fs.writeFileSync(geminiSettingsPath, JSON.stringify(mergedGemini, null, 2));
+
+    // Write Claude config (if applicable)
+    const claudeConfig = this.toClaudeConfig();
+    if (Object.keys(claudeConfig).length > 0) {
+      const claudeDir = path.join(projectDir, '.claude');
+      if (!fs.existsSync(claudeDir)) {
+        fs.mkdirSync(claudeDir, { recursive: true });
+      }
+
+      const hooksPath = path.join(claudeDir, 'hooks.json');
+      fs.writeFileSync(hooksPath, JSON.stringify(claudeConfig, null, 2));
+    }
+  }
+}
+
+// Singleton instance
+const registry = new HookRegistry();
+
+module.exports = { HookRegistry, registry };

package/template/.aiox-core/hooks/unified/index.js

@@ -0,0 +1,36 @@
+/**
+ * Unified Hooks Module
+ * Story GEMINI-INT.8 - Cross-CLI Hook Abstraction
+ *
+ * Write hooks once, run on both Claude Code and Gemini CLI.
+ */
+
+const { UnifiedHook, EVENT_MAPPING, createContext, formatResult } = require('./hook-interface');
+const { HookRegistry, registry } = require('./hook-registry');
+
+module.exports = {
+  // Core classes
+  UnifiedHook,
+  HookRegistry,
+
+  // Singleton registry
+  registry,
+
+  // Utilities
+  EVENT_MAPPING,
+  createContext,
+  formatResult,
+
+  // Convenience function to create hooks
+  createHook: (config, executeFunc) => {
+    class CustomHook extends UnifiedHook {
+      constructor() {
+        super(config);
+      }
+      async execute(context) {
+        return executeFunc(context);
+      }
+    }
+    return new CustomHook();
+  },
+};

package/template/.aiox-core/hooks/unified/runners/precompact-runner.js

@@ -0,0 +1,96 @@
+/**
+ * PreCompact Hook Runner - Session Digest Trigger
+ *
+ * Captures session knowledge before context compact via PreCompact hook.
+ * Uses fire-and-forget async execution to avoid blocking the compact operation.
+ *
+ * Architecture: Open Core
+ * - aiox-core: Hook runner (this file) + pro detection
+ * - aiox-pro: Digest extraction logic (memory/session-digest/)
+ *
+ * @module .aiox-core/hooks/unified/runners/precompact-runner
+ * @see Story MIS-3 - Session Digest (PreCompact Hook)
+ * @see Story PRO-5 - aiox-pro Repository Bootstrap
+ */
+
+'use strict';
+
+const path = require('path');
+const proDetectorPath = path.resolve(__dirname, '../../../..', 'bin', 'utils', 'pro-detector');
+const { isProAvailable, loadProModule } = require(proDetectorPath);
+
+/**
+ * PreCompact hook handler - Fire-and-forget session digest
+ *
+ * Execution flow:
+ * 1. Detect aiox-pro availability via pro-detector
+ * 2. If available, fire-and-forget async digest extraction
+ * 3. If not available, graceful no-op (log and return)
+ * 4. NEVER block the compact operation (< 5s)
+ *
+ * @param {Object} context - Hook context from Claude Code
+ * @param {string} context.sessionId - Current session identifier
+ * @param {string} context.projectDir - Project root directory
+ * @param {Object} context.conversation - Conversation metadata
+ * @param {string} context.provider - CLI provider ('claude' or 'gemini')
+ * @returns {Promise<void>}
+ */
+async function onPreCompact(context) {
+  try {
+    // 1. Detect aiox-pro availability
+    const proAvailable = isProAvailable();
+
+    if (!proAvailable) {
+      console.log('[PreCompact] aiox-pro not available, skipping session digest');
+      return; // Graceful degradation - no-op
+    }
+
+    // 2. Fire-and-forget async execution (don't block compact)
+    setImmediate(async () => {
+      try {
+        // Dynamic import from aiox-pro
+        const digestModule = loadProModule('memory/session-digest/extractor.js');
+
+        if (!digestModule || typeof digestModule.extractSessionDigest !== 'function') {
+          console.error('[PreCompact] Digest extractor not found or invalid in aiox-pro');
+          return;
+        }
+
+        // Execute digest extraction
+        await digestModule.extractSessionDigest(context);
+
+        console.log('[PreCompact] Session digest completed successfully');
+      } catch (err) {
+        // Silent failure - log but don't propagate (never block user)
+        console.error('[PreCompact] Digest extraction failed (silent):', err.message);
+      }
+    });
+
+    // 3. Return immediately - don't wait for digest to complete
+    return;
+  } catch (err) {
+    // Outer error boundary - silent failure
+    console.error('[PreCompact] Hook runner error:', err.message);
+    // Never throw - graceful degradation
+  }
+}
+
+/**
+ * Get hook configuration for registration
+ *
+ * @returns {Object} Hook configuration metadata
+ */
+function getHookConfig() {
+  return {
+    name: 'precompact-session-digest',
+    event: 'PreCompact',
+    handler: onPreCompact,
+    timeout: 5000, // Max 5s to avoid delaying compact
+    description: 'Capture session knowledge before context compact (MIS-3)',
+  };
+}
+
+module.exports = {
+  onPreCompact,
+  getHookConfig,
+};

package/template/.aiox-core/manifests/schema/manifest-schema.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "AIOX Manifest Schema",
+  "description": "Schema definitions for AIOX manifest CSV files",
+  "version": "1.0.0",
+  "definitions": {
+    "agents": {
+      "description": "Schema for agents.csv",
+      "type": "object",
+      "columns": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "Unique agent identifier (e.g., dev, qa, architect)"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": true,
+          "description": "Display name of the agent (e.g., Dex, Quinn)"
+        },
+        {
+          "name": "archetype",
+          "type": "string",
+          "required": true,
+          "description": "Agent archetype (e.g., Builder, Tester, Architect)"
+        },
+        {
+          "name": "icon",
+          "type": "string",
+          "required": true,
+          "description": "Emoji icon for the agent"
+        },
+        {
+          "name": "version",
+          "type": "string",
+          "required": true,
+          "description": "Agent version (semver format)"
+        },
+        {
+          "name": "status",
+          "type": "string",
+          "required": true,
+          "enum": ["active", "deprecated", "experimental"],
+          "description": "Agent status"
+        },
+        {
+          "name": "file_path",
+          "type": "string",
+          "required": true,
+          "description": "Relative path to agent definition file"
+        },
+        {
+          "name": "when_to_use",
+          "type": "string",
+          "required": false,
+          "description": "Description of when to use this agent"
+        }
+      ],
+      "header": "id,name,archetype,icon,version,status,file_path,when_to_use"
+    },
+    "workers": {
+      "description": "Schema for workers.csv",
+      "type": "object",
+      "columns": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "Unique worker identifier"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": true,
+          "description": "Display name of the worker"
+        },
+        {
+          "name": "category",
+          "type": "string",
+          "required": true,
+          "description": "Worker category (task, script, template, etc.)"
+        },
+        {
+          "name": "subcategory",
+          "type": "string",
+          "required": false,
+          "description": "Worker subcategory"
+        },
+        {
+          "name": "executor_types",
+          "type": "string",
+          "required": true,
+          "description": "Comma-separated executor types (Worker, Agent)"
+        },
+        {
+          "name": "tags",
+          "type": "string",
+          "required": false,
+          "description": "Comma-separated tags"
+        },
+        {
+          "name": "file_path",
+          "type": "string",
+          "required": true,
+          "description": "Relative path to worker file"
+        },
+        {
+          "name": "status",
+          "type": "string",
+          "required": true,
+          "enum": ["active", "deprecated", "experimental"],
+          "description": "Worker status"
+        }
+      ],
+      "header": "id,name,category,subcategory,executor_types,tags,file_path,status"
+    },
+    "tasks": {
+      "description": "Schema for tasks.csv",
+      "type": "object",
+      "columns": [
+        {
+          "name": "id",
+          "type": "string",
+          "required": true,
+          "description": "Unique task identifier"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": true,
+          "description": "Display name of the task"
+        },
+        {
+          "name": "category",
+          "type": "string",
+          "required": true,
+          "description": "Task category"
+        },
+        {
+          "name": "format",
+          "type": "string",
+          "required": true,
+          "description": "Task format (TASK-FORMAT-V1, CHECKLIST, etc.)"
+        },
+        {
+          "name": "has_elicitation",
+          "type": "boolean",
+          "required": true,
+          "description": "Whether task requires user interaction"
+        },
+        {
+          "name": "file_path",
+          "type": "string",
+          "required": true,
+          "description": "Relative path to task file"
+        },
+        {
+          "name": "status",
+          "type": "string",
+          "required": true,
+          "enum": ["active", "deprecated", "experimental"],
+          "description": "Task status"
+        }
+      ],
+      "header": "id,name,category,format,has_elicitation,file_path,status"
+    }
+  },
+  "validation": {
+    "rules": [
+      {
+        "name": "unique_ids",
+        "description": "All IDs must be unique within their manifest"
+      },
+      {
+        "name": "file_exists",
+        "description": "All file_path values must point to existing files"
+      },
+      {
+        "name": "valid_status",
+        "description": "Status must be one of: active, deprecated, experimental"
+      },
+      {
+        "name": "required_columns",
+        "description": "All required columns must have non-empty values"
+      }
+    ]
+  }
+}