create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/hooks/ids-post-commit.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * IDS Post-Commit Hook (Story IDS-3)
+ *
+ * Runs asynchronously after each commit to update the entity registry
+ * with changes from the committed files. Does NOT block the commit.
+ *
+ * Usage: node .aiox-core/hooks/ids-post-commit.js
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+
+function isDocsOnlyPath(relativePath) {
+  const p = String(relativePath || '').replace(/\\/g, '/');
+  if (!p) return false;
+
+  if (p.startsWith('docs/')) return true;
+  if (p === 'README.md') return true;
+  if (p === 'CHANGELOG.md') return true;
+  if (p === 'CONTRIBUTING.md') return true;
+  if (p === 'CODE_OF_CONDUCT.md') return true;
+  if (p === 'AGENTS.md') return true;
+
+  return false;
+}
+
+function isDocsOnlyCommit(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) return false;
+  return changes.every((c) => isDocsOnlyPath(c.relativePath));
+}
+
+function getChangedFilesFromLastCommit() {
+  try {
+    const output = execSync('git diff-tree --no-commit-id --name-status -r HEAD', {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+
+    const changes = [];
+    const lines = output.trim().split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      const [status, ...fileParts] = line.split('\t');
+
+      if (fileParts.length === 0) continue;
+
+      let action;
+      let filePath;
+
+      if (status === 'A') {
+        action = 'add';
+        filePath = fileParts[0];
+      } else if (status === 'M') {
+        action = 'change';
+        filePath = fileParts[0];
+      } else if (status === 'D') {
+        action = 'unlink';
+        filePath = fileParts[0];
+      } else if (status.startsWith('R') || status.startsWith('C')) {
+        // Rename/copy: use destination path (second path)
+        action = status.startsWith('C') ? 'add' : 'change';
+        filePath = fileParts[fileParts.length - 1];
+      } else {
+        continue;
+      }
+
+      if (!filePath) continue;
+      changes.push({
+        action,
+        relativePath: filePath,
+        filePath: path.resolve(REPO_ROOT, filePath),
+      });
+    }
+
+    return changes;
+  } catch (err) {
+    console.error(`[IDS-Hook] Failed to get changed files: ${err.message}`);
+    return [];
+  }
+}
+
+async function main() {
+  const changes = getChangedFilesFromLastCommit();
+
+  if (changes.length === 0) return;
+
+  if (process.env.AIOX_IDS_FORCE !== '1' && isDocsOnlyCommit(changes)) {
+    console.log('[IDS-Hook] Docs-only commit detected, skipping registry update.');
+    return;
+  }
+
+  try {
+    const { RegistryUpdater } = require(path.resolve(REPO_ROOT, '.aiox-core/core/ids/registry-updater.js'));
+    const updater = new RegistryUpdater();
+    const result = await updater.processChanges(changes);
+
+    if (result.updated > 0) {
+      console.log(`[IDS-Hook] Registry updated: ${result.updated} entities processed.`);
+    }
+
+    if (result.errors.length > 0) {
+      console.warn(`[IDS-Hook] ${result.errors.length} errors during update.`);
+    }
+  } catch (err) {
+    // Post-commit hook should NEVER block workflow
+    console.error(`[IDS-Hook] Registry update failed (non-blocking): ${err.message}`);
+  }
+}
+
+main();

package/template/.aiox-core/hooks/ids-pre-push.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * IDS Pre-Push Hook (Story IDS-3)
+ *
+ * Runs synchronously before push to ensure registry is up-to-date.
+ * Processes all files that differ between local HEAD and remote tracking branch.
+ * Exits with 0 (success) even on errors — registry issues should not block push.
+ *
+ * Usage: node .aiox-core/hooks/ids-pre-push.js
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const REPO_ROOT = path.resolve(__dirname, '../..');
+
+function isDocsOnlyPath(relativePath) {
+  const p = String(relativePath || '').replace(/\\/g, '/');
+  if (!p) return false;
+
+  if (p.startsWith('docs/')) return true;
+  if (p === 'README.md') return true;
+  if (p === 'CHANGELOG.md') return true;
+  if (p === 'CONTRIBUTING.md') return true;
+  if (p === 'CODE_OF_CONDUCT.md') return true;
+  if (p === 'AGENTS.md') return true;
+
+  return false;
+}
+
+function isDocsOnlyPush(changes) {
+  if (!Array.isArray(changes) || changes.length === 0) return false;
+  return changes.every((c) => isDocsOnlyPath(c.relativePath));
+}
+
+function getChangedFilesSinceRemote() {
+  try {
+    const trackingBranch = execSync('git rev-parse --abbrev-ref --symbolic-full-name @{u}', {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      timeout: 5000,
+    }).trim();
+
+    const output = execSync(`git diff --name-status ${trackingBranch}...HEAD`, {
+      cwd: REPO_ROOT,
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+
+    const changes = [];
+    const lines = output.trim().split('\n').filter(Boolean);
+
+    for (const line of lines) {
+      const [status, ...fileParts] = line.split('\t');
+
+      if (fileParts.length === 0) continue;
+
+      let action;
+      let filePath;
+
+      if (status === 'A') {
+        action = 'add';
+        filePath = fileParts[0];
+      } else if (status === 'M') {
+        action = 'change';
+        filePath = fileParts[0];
+      } else if (status === 'D') {
+        action = 'unlink';
+        filePath = fileParts[0];
+      } else if (status.startsWith('R') || status.startsWith('C')) {
+        action = status.startsWith('C') ? 'add' : 'change';
+        filePath = fileParts[fileParts.length - 1];
+      } else {
+        continue;
+      }
+
+      if (!filePath) continue;
+      changes.push({
+        action,
+        relativePath: filePath,
+        filePath: path.resolve(REPO_ROOT, filePath),
+      });
+    }
+
+    return changes;
+  } catch {
+    // No tracking branch or git error — skip
+    return [];
+  }
+}
+
+async function main() {
+  const changes = getChangedFilesSinceRemote();
+
+  if (changes.length === 0) {
+    console.log('[IDS-Hook] No relevant changes for registry update.');
+    process.exit(0);
+  }
+
+  if (process.env.AIOX_IDS_FORCE !== '1' && isDocsOnlyPush(changes)) {
+    console.log('[IDS-Hook] Docs-only push detected, skipping registry update.');
+    process.exit(0);
+  }
+
+  try {
+    const { RegistryUpdater } = require(path.resolve(REPO_ROOT, '.aiox-core/core/ids/registry-updater.js'));
+    const updater = new RegistryUpdater();
+    const result = await updater.processChanges(changes);
+
+    if (result.updated > 0) {
+      console.log(`[IDS-Hook] Registry synced: ${result.updated} entities updated before push.`);
+    }
+  } catch (err) {
+    // Pre-push hook should warn but NOT block push
+    console.warn(`[IDS-Hook] Registry sync failed (non-blocking): ${err.message}`);
+  }
+
+  process.exit(0);
+}
+
+main();

package/template/.aiox-core/hooks/unified/README.md

@@ -0,0 +1,338 @@
+# Unified Hooks System
+
+**Module:** `.aiox-core/hooks/unified`
+**Purpose:** Cross-CLI hook abstraction layer
+**Supported CLIs:** Claude Code, Gemini Code
+
+---
+
+## Overview
+
+The Unified Hooks System provides a consistent interface for lifecycle hooks across different AI coding assistants (Claude Code, Gemini Code, future CLIs).
+
+### Architecture
+
+```
+CLI-Specific Hooks (.claude/hooks/, .gemini/hooks/)
+         ↓
+Hook Interface (hook-interface.js)
+         ↓
+Hook Runners (runners/*.js)
+         ↓
+Application Logic (aiox-core, aiox-pro)
+```
+
+---
+
+## Components
+
+### 1. Hook Interface (`hook-interface.js`)
+
+**Purpose:** Normalize hook events across CLIs
+
+**Event Mapping:**
+
+| Unified Event | Claude Code | Gemini Code |
+|---------------|-------------|-------------|
+| `sessionStart` | N/A | `SessionStart` |
+| `beforeAgent` | `PreToolUse` | `BeforeAgent` |
+| `beforeTool` | `PreToolUse` | `BeforeTool` |
+| `afterTool` | `PostToolUse` | `AfterTool` |
+| `sessionEnd` | `Stop` | `SessionEnd` |
+
+**Usage:**
+
+```javascript
+const { UnifiedHook, EVENT_MAPPING } = require('./hook-interface');
+
+class MyHook extends UnifiedHook {
+  constructor() {
+    super({
+      name: 'my-hook',
+      event: 'beforeTool',
+      matcher: 'write_file',
+      timeout: 5000,
+    });
+  }
+
+  async execute(context) {
+    // Your logic here
+    return { status: 'allow' };
+  }
+}
+```
+
+### 2. Hook Runners (`runners/`)
+
+**Purpose:** Implement specific hook logic
+
+**Current Runners:**
+
+- **`precompact-runner.js`** (Story MIS-3)
+  - Captures session digest before context compact
+  - Open Core architecture (delegates to aiox-pro)
+  - Fire-and-forget async execution
+
+**Runner Pattern:**
+
+```javascript
+async function onHookEvent(context) {
+  try {
+    // 1. Check preconditions
+    // 2. Execute async (setImmediate for non-blocking)
+    // 3. Return immediately
+  } catch (err) {
+    // Silent failure - never block user
+  }
+}
+
+function getHookConfig() {
+  return {
+    name: 'hook-name',
+    event: 'UnifiedEvent',
+    handler: onHookEvent,
+    timeout: 5000,
+  };
+}
+```
+
+### 3. Hook Registry (`hook-registry.js`)
+
+**Purpose:** Register and discover hooks
+
+**API:**
+
+```javascript
+const registry = require('./hook-registry');
+
+// Register hook
+registry.register(myHook);
+
+// Get hooks for event
+const hooks = registry.getHooksForEvent('beforeTool');
+
+// Execute hooks
+await registry.executeHooks('beforeTool', context);
+```
+
+---
+
+## PreCompact Hook (Story MIS-3)
+
+### Purpose
+
+Capture session knowledge before context compact to preserve institutional learnings.
+
+### Architecture
+
+```
+Claude Code PreCompact Event
+         ↓
+.claude/hooks/precompact-session-digest.cjs
+         ↓
+runners/precompact-runner.js
+         ↓ (pro-detector check)
+pro/memory/session-digest/extractor.js
+         ↓
+.aiox/session-digests/{session-id}-{timestamp}.yaml
+```
+
+### Performance
+
+- **Hook return:** < 50ms (fire-and-forget)
+- **Digest completion:** < 5s
+- **Never blocks compact**
+
+### Graceful Degradation
+
+- If aiox-pro not available: no-op (log and return)
+- If extraction fails: silent failure (log error)
+- If write fails: error propagated to logger
+
+---
+
+## Creating New Hooks
+
+### Step 1: Create Runner
+
+```javascript
+// .aiox-core/hooks/unified/runners/my-runner.js
+
+async function onMyEvent(context) {
+  try {
+    // Implement your logic
+    console.log('[MyHook] Event fired');
+
+    // Fire-and-forget if needed
+    setImmediate(async () => {
+      await doAsyncWork(context);
+    });
+
+    return; // Return immediately
+  } catch (err) {
+    console.error('[MyHook] Error:', err.message);
+  }
+}
+
+function getHookConfig() {
+  return {
+    name: 'my-hook',
+    event: 'beforeTool',
+    handler: onMyEvent,
+    timeout: 5000,
+  };
+}
+
+module.exports = { onMyEvent, getHookConfig };
+```
+
+### Step 2: Register Hook
+
+**IMPORTANT:** Claude Code hooks must be registered as `type: "command"` in `settings.json`. They run as separate processes reading JSON from stdin — NOT as module exports.
+
+```javascript
+// .claude/hooks/my-hook.cjs — Process-based hook (reads stdin)
+#!/usr/bin/env node
+'use strict';
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => {
+      try { resolve(JSON.parse(data)); }
+      catch (e) { reject(e); }
+    });
+  });
+}
+
+async function main() {
+  const input = await readStdin();
+  const { onMyEvent } = require('../../.aiox-core/hooks/unified/runners/my-runner');
+  await onMyEvent(input);
+}
+
+if (require.main === module) {
+  main().then(() => process.exit(0)).catch(() => process.exit(0));
+}
+```
+
+Then add the mapping to `HOOK_EVENT_MAP` in `packages/installer/src/wizard/ide-config-generator.js`:
+
+```javascript
+'my-hook.cjs': {
+  event: 'PreToolUse', // or UserPromptSubmit, PreCompact, etc.
+  matcher: null,       // or 'Write|Edit' for PreToolUse filtering
+  timeout: 10,
+},
+```
+
+### Step 3: Test Hook
+
+```javascript
+// tests/hooks/unified/runners/my-runner.test.js
+
+describe('My Hook', () => {
+  it('should execute without blocking', async () => {
+    const startTime = Date.now();
+    await onMyEvent(context);
+    const duration = Date.now() - startTime;
+
+    expect(duration).toBeLessThan(50); // Fire-and-forget
+  });
+});
+```
+
+---
+
+## Testing
+
+### Unit Tests
+
+```bash
+npm test -- tests/hooks/unified/
+```
+
+### Integration Tests
+
+```bash
+npm test -- tests/integration/hooks/
+```
+
+---
+
+## Best Practices
+
+### 1. Fire-and-Forget Pattern
+
+```javascript
+// ✓ Good: Non-blocking
+setImmediate(async () => {
+  await slowOperation();
+});
+return; // Return immediately
+
+// ✗ Bad: Blocking
+await slowOperation();
+return;
+```
+
+### 2. Silent Failures
+
+```javascript
+// ✓ Good: Silent failure
+catch (err) {
+  console.error('[Hook] Failed:', err.message);
+  // Don't throw - graceful degradation
+}
+
+// ✗ Bad: Propagates error
+catch (err) {
+  throw err; // Blocks user!
+}
+```
+
+### 3. Timeout Limits
+
+```javascript
+// ✓ Good: < 5s timeout
+{
+  timeout: 5000
+}
+
+// ✗ Bad: Long timeout
+{
+  timeout: 30000 // May delay user
+}
+```
+
+### 4. Pro Detection (Open Core)
+
+```javascript
+// ✓ Good: Graceful degradation
+const { isProAvailable } = require('../../../bin/utils/pro-detector');
+
+if (!isProAvailable()) {
+  console.log('[Hook] aiox-pro not available, skipping');
+  return;
+}
+
+// ✗ Bad: Hard dependency
+const proModule = require('../../pro/...'); // Fails if pro absent
+```
+
+---
+
+## Related Stories
+
+- **Story GEMINI-INT.8:** Unified Hook Interface (completed)
+- **Story MIS-2:** Dead Code Cleanup (restored hooks foundation)
+- **Story MIS-3:** Session Digest (PreCompact Hook)
+- **Story MIS-3.1:** Fix Session-Digest Hook Registration ← **CURRENT**
+- **Story PRO-5:** aiox-pro Repository Bootstrap (pro-detector pattern)
+
+---
+
+*Unified Hooks System - AIOX Core*
+*Updated: 2026-02-26 - Story MIS-3.1*