@celilo/cli 0.1.0

package/src/hooks/executor.ts

@@ -0,0 +1,469 @@
+/**
+ * Hook Executor
+ *
+ * Executes hook scripts in a controlled environment with:
+ * - Timeout management (total + idle)
+ * - Input validation
+ * - Output validation
+ * - Structured logging
+ *
+ * Execution function (Rule 10.1) - performs side effects (script execution)
+ */
+
+import { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isCompiledHook } from '@celilo/capabilities';
+import {
+  type ContractHookSignature,
+  resolveContract,
+  supportedContractVersions,
+} from '../manifest/contracts';
+import type { HookContext, HookDefinition, HookLogger, HookResult } from './types';
+
+/** Default total timeout: 60 seconds */
+const DEFAULT_TIMEOUT_MS = 60_000;
+
+/** Default idle timeout: 30 seconds since last log message */
+const IDLE_TIMEOUT_MS = 30_000;
+
+/**
+ * Validate hook inputs against a contract signature.
+ *
+ * Policy function (Rule 10.1) - validates inputs.
+ *
+ * The set of required inputs comes from the contract version registered for
+ * the manifest's `celilo_contract`, NOT from the manifest itself. See
+ * `apps/celilo/src/manifest/contracts/v1.ts`.
+ *
+ * @param signature - Contract hook signature for this hook name
+ * @param inputs - Provided input values
+ * @returns Error message if validation fails, null if valid
+ */
+export function validateHookInputs(
+  signature: ContractHookSignature,
+  inputs: Record<string, unknown>,
+): string | null {
+  const required = Object.entries(signature.inputs)
+    .filter(([, def]) => def.required)
+    .map(([name]) => name);
+
+  const missing = required.filter((name) => !(name in inputs));
+  if (missing.length > 0) {
+    return `Missing required hook inputs: ${missing.join(', ')}`;
+  }
+
+  return null;
+}
+
+/**
+ * Validate hook outputs against a contract signature.
+ *
+ * Policy function (Rule 10.1) - validates outputs.
+ *
+ * @param signature - Contract hook signature for this hook name
+ * @param outputs - Returned output values
+ * @returns Error message if validation fails, null if valid
+ */
+export function validateHookOutputs(
+  signature: ContractHookSignature,
+  outputs: Record<string, unknown>,
+): string | null {
+  const required = Object.entries(signature.outputs)
+    .filter(([, def]) => def.required)
+    .map(([name]) => name);
+
+  const missing = required.filter((name) => !(name in outputs));
+  if (missing.length > 0) {
+    return `Hook did not return required outputs: ${missing.join(', ')}`;
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the absolute path to a hook script
+ *
+ * Policy function (Rule 10.1) - validates path
+ *
+ * @param modulePath - Absolute path to module directory
+ * @param scriptPath - Relative script path from manifest
+ * @returns Resolved absolute path
+ */
+export function resolveHookScript(modulePath: string, scriptPath: string): string {
+  const resolved = resolve(modulePath, scriptPath);
+
+  // Security: ensure resolved path is within module directory
+  const normalizedModule = resolve(modulePath);
+  if (!resolved.startsWith(normalizedModule)) {
+    throw new Error(`Hook script path escapes module directory: ${scriptPath}`);
+  }
+
+  return resolved;
+}
+
+/**
+ * Execute a hook script
+ *
+ * Execution function (Rule 10.1) - performs side effects
+ *
+ * @param scriptPath - Absolute path to the hook script
+ * @param context - Hook context with config, secrets, logger, and inputs
+ * @param timeoutMs - Total timeout in milliseconds
+ * @returns Hook result with outputs
+ */
+export async function executeHookScript(
+  scriptPath: string,
+  context: HookContext,
+  timeoutMs: number = DEFAULT_TIMEOUT_MS,
+): Promise<Record<string, unknown>> {
+  if (!existsSync(scriptPath)) {
+    throw new Error(`Hook script not found: ${scriptPath}`);
+  }
+
+  // Create an idle timeout tracker
+  let lastActivity = Date.now();
+  const originalLogger = context.logger;
+
+  // Wrap logger to track activity for idle timeout
+  const trackedLogger: HookLogger = {
+    info(message: string) {
+      lastActivity = Date.now();
+      originalLogger.info(message);
+    },
+    warn(message: string) {
+      lastActivity = Date.now();
+      originalLogger.warn(message);
+    },
+    error(message: string) {
+      lastActivity = Date.now();
+      originalLogger.error(message);
+    },
+    success(message: string) {
+      lastActivity = Date.now();
+      originalLogger.success(message);
+    },
+  };
+
+  const trackedContext: HookContext = {
+    ...context,
+    logger: trackedLogger,
+  };
+
+  // Execute with timeout — disable idle timeout in debug mode
+  const promises: Promise<Record<string, unknown>>[] = [
+    runScript(scriptPath, trackedContext),
+    createTimeoutPromise(timeoutMs, 'total'),
+  ];
+  if (!context.debug) {
+    promises.push(createIdleTimeoutPromise(() => Date.now() - lastActivity, IDLE_TIMEOUT_MS));
+  }
+  const result = await Promise.race(promises);
+
+  return result;
+}
+
+/**
+ * Run a hook script by dynamically importing it.
+ *
+ * HOOK_API_V2 Phase 8 (D8): the executor only accepts hook scripts that
+ * use `defineHook` from `@celilo/capabilities`. The compiled output
+ * carries a brand symbol (`CELILO_HOOK_BRAND`) that this function
+ * checks via `isCompiledHook`. Raw `async function(context)` exports are
+ * rejected with a clear error pointing at the migration guide — no more
+ * silent failures from forgotten brand registration.
+ *
+ * @param scriptPath - Absolute path to script
+ * @param context - Hook context
+ * @returns Script outputs
+ */
+async function runScript(
+  scriptPath: string,
+  context: HookContext,
+): Promise<Record<string, unknown>> {
+  const module = await import(scriptPath);
+
+  if (typeof module.default !== 'function') {
+    throw new Error(`Hook script must export a default function: ${scriptPath}`);
+  }
+
+  if (!isCompiledHook(module.default)) {
+    throw new Error(
+      `Hook script ${scriptPath} does not use defineHook(). As of HOOK_API_V2 Phase 8, all hook scripts must wrap their handler with defineHook from @celilo/capabilities so the executor can verify the brand and apply pre-flight checks. See design/MODULE_DEVELOPMENT_GUIDE.md "Hooks" section for the migration pattern.`,
+    );
+  }
+
+  const result = await module.default(context);
+
+  if (result === null || result === undefined) {
+    return {};
+  }
+
+  if (typeof result !== 'object' || Array.isArray(result)) {
+    throw new Error('Hook script must return an object (or nothing)');
+  }
+
+  return result as Record<string, unknown>;
+}
+
+/**
+ * Create a promise that rejects after a total timeout
+ */
+function createTimeoutPromise(timeoutMs: number, type: string): Promise<never> {
+  return new Promise((_, reject) => {
+    setTimeout(() => {
+      reject(new Error(`Hook ${type} timeout exceeded (${Math.round(timeoutMs / 1000)}s)`));
+    }, timeoutMs);
+  });
+}
+
+/**
+ * Create a promise that rejects when idle timeout is exceeded
+ * Polls every 5 seconds to check idle duration
+ */
+function createIdleTimeoutPromise(
+  getIdleDuration: () => number,
+  idleTimeoutMs: number,
+): Promise<never> {
+  return new Promise((_, reject) => {
+    const interval = setInterval(() => {
+      if (getIdleDuration() >= idleTimeoutMs) {
+        clearInterval(interval);
+        reject(
+          new Error(
+            `Hook idle timeout exceeded (no log output for ${Math.round(idleTimeoutMs / 1000)}s)`,
+          ),
+        );
+      }
+    }, 5000);
+
+    // Don't block process exit
+    if (interval.unref) {
+      interval.unref();
+    }
+  });
+}
+
+export interface InvokeHookOptions {
+  debug?: boolean;
+  /** Pre-loaded capability function interfaces to inject into context */
+  capabilities?: Record<string, unknown>;
+  /**
+   * Names of capabilities the hook's module declares in
+   * `requires.capabilities`. The executor checks each one is present in
+   * `capabilities` before invoking the hook handler and fails fast with a
+   * clear error if any are missing. Added in HOOK_API_V2 Phase 3 (D3).
+   *
+   * Optional for backwards compatibility — callers that don't pass this
+   * skip the pre-flight check, matching the pre-Phase-3 behavior.
+   */
+  requiredCapabilities?: string[];
+}
+
+/**
+ * Verify every required capability is present in the loaded capability map.
+ *
+ * Policy function (Rule 10.1) — pure check, no side effects.
+ *
+ * @returns Error message listing missing capabilities, or null if all present
+ */
+export function checkRequiredCapabilities(
+  hookName: string,
+  requiredCapabilities: string[],
+  loadedCapabilities: Record<string, unknown>,
+): string | null {
+  const missing = requiredCapabilities.filter((name) => !(name in loadedCapabilities));
+  if (missing.length === 0) return null;
+
+  const lines = [
+    `Hook '${hookName}' requires capability ${missing.length === 1 ? '' : 'capabilities '}${missing.map((n) => `'${n}'`).join(', ')} but no provider${missing.length === 1 ? ' is' : 's are'} loaded.`,
+    `Install a module that provides ${missing.length === 1 ? missing[0] : 'each missing capability'} and retry.`,
+  ];
+  return lines.join(' ');
+}
+
+/**
+ * Find the most recently created screenshot in a directory
+ *
+ * @param dir - Directory to scan
+ * @param since - Only consider files created after this timestamp (ms)
+ * @returns Path to screenshot, or undefined
+ */
+function findRecentScreenshot(dir: string, since: number): string | undefined {
+  if (!existsSync(dir)) return undefined;
+
+  try {
+    const files = readdirSync(dir).filter((f) => f.endsWith('.png'));
+    for (const file of files) {
+      const fullPath = join(dir, file);
+      const stat = statSync(fullPath);
+      if (stat.mtimeMs >= since) {
+        return fullPath;
+      }
+    }
+  } catch {
+    // Best effort — don't mask the original error
+  }
+  return undefined;
+}
+
+/**
+ * Execute a named hook for a module
+ *
+ * Orchestration function - coordinates validation, resolution, and execution.
+ *
+ * Resolves the hook's inputs/outputs signature from the contract registry
+ * keyed by `contractVersion`, validates the provided inputs against it,
+ * runs the script, and validates the returned outputs.
+ *
+ * @param modulePath - Absolute path to module directory
+ * @param hookName - Name of the hook to execute
+ * @param contractVersion - Celilo contract version from `manifest.celilo_contract`
+ * @param definition - Hook definition from manifest (script + timeout only)
+ * @param inputs - Input values for the hook
+ * @param config - Module configuration values
+ * @param secrets - Module secret values (decrypted)
+ * @param logger - Logger instance
+ * @param options - Debug and other options
+ * @returns Hook result
+ */
+export async function invokeHook(
+  modulePath: string,
+  hookName: string,
+  contractVersion: string,
+  definition: HookDefinition,
+  inputs: Record<string, unknown>,
+  config: Record<string, unknown>,
+  secrets: Record<string, string>,
+  logger: HookLogger,
+  options: InvokeHookOptions = {},
+): Promise<HookResult> {
+  const startTime = Date.now();
+  const debug = options.debug ?? false;
+
+  // Resolve the hook's contract signature
+  const contract = resolveContract(contractVersion);
+  if (!contract) {
+    return {
+      success: false,
+      outputs: {},
+      error: `Unsupported celilo_contract version '${contractVersion}'. Supported: ${supportedContractVersions().join(', ')}`,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  const signature = contract.hooks[hookName];
+  if (!signature) {
+    return {
+      success: false,
+      outputs: {},
+      error: `Hook '${hookName}' is not part of celilo_contract ${contractVersion}`,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  // Validate inputs against the contract signature
+  const inputError = validateHookInputs(signature, inputs);
+  if (inputError) {
+    return {
+      success: false,
+      outputs: {},
+      error: inputError,
+      duration: Date.now() - startTime,
+    };
+  }
+
+  // Resolve script path
+  let scriptPath: string;
+  try {
+    scriptPath = resolveHookScript(modulePath, definition.script);
+  } catch (error) {
+    return {
+      success: false,
+      outputs: {},
+      error: error instanceof Error ? error.message : String(error),
+      duration: Date.now() - startTime,
+    };
+  }
+
+  // Prepare screenshot directory
+  const screenshotDir = join(modulePath, 'screenshots');
+  mkdirSync(screenshotDir, { recursive: true });
+
+  // Build context
+  const loadedCapabilities = options.capabilities ?? {};
+  const context: HookContext = {
+    ...inputs,
+    config,
+    secrets,
+    logger,
+    debug,
+    screenshotDir,
+    capabilities: loadedCapabilities,
+  };
+
+  // Pre-flight: every required capability must be loaded (HOOK_API_V2 D3).
+  // Fail before invoking the handler so the script never sees a missing
+  // capability. Skipped if the caller didn't pass requiredCapabilities,
+  // for backwards compatibility with pre-Phase-3 invocation sites.
+  if (options.requiredCapabilities && options.requiredCapabilities.length > 0) {
+    const capError = checkRequiredCapabilities(
+      hookName,
+      options.requiredCapabilities,
+      loadedCapabilities,
+    );
+    if (capError) {
+      return {
+        success: false,
+        outputs: {},
+        error: capError,
+        duration: Date.now() - startTime,
+      };
+    }
+  }
+
+  // In debug mode, use much longer timeouts for interactive debugging
+  const timeoutMs = debug
+    ? 600_000 // 10 minutes
+    : (definition.timeout ?? DEFAULT_TIMEOUT_MS);
+
+  // Execute
+  try {
+    logger.info(`Executing hook: ${hookName}`);
+    const outputs = await executeHookScript(scriptPath, context, timeoutMs);
+
+    // Validate outputs against the contract signature
+    const outputError = validateHookOutputs(signature, outputs);
+    if (outputError) {
+      return {
+        success: false,
+        outputs,
+        error: outputError,
+        duration: Date.now() - startTime,
+      };
+    }
+
+    logger.success(`Hook ${hookName} completed successfully`);
+    return {
+      success: true,
+      outputs,
+      duration: Date.now() - startTime,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(`Hook ${hookName} failed: ${message}`);
+
+    // Check for screenshots captured by the hook
+    const screenshotPath = findRecentScreenshot(screenshotDir, startTime);
+    if (screenshotPath) {
+      logger.info(`Screenshot saved: ${screenshotPath}`);
+    }
+
+    return {
+      success: false,
+      outputs: {},
+      error: message,
+      screenshotPath,
+      duration: Date.now() - startTime,
+    };
+  }
+}

package/src/hooks/logger.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from 'bun:test';
+import { createCapturingLogger, createConsoleLogger } from './logger';
+
+describe('Hook Logger', () => {
+  describe('createCapturingLogger', () => {
+    test('captures info messages', () => {
+      const { logger, messages } = createCapturingLogger();
+      logger.info('test message');
+      expect(messages).toEqual([{ level: 'info', message: 'test message' }]);
+    });
+
+    test('captures warn messages', () => {
+      const { logger, messages } = createCapturingLogger();
+      logger.warn('warning message');
+      expect(messages).toEqual([{ level: 'warn', message: 'warning message' }]);
+    });
+
+    test('captures error messages', () => {
+      const { logger, messages } = createCapturingLogger();
+      logger.error('error message');
+      expect(messages).toEqual([{ level: 'error', message: 'error message' }]);
+    });
+
+    test('captures success messages', () => {
+      const { logger, messages } = createCapturingLogger();
+      logger.success('success message');
+      expect(messages).toEqual([{ level: 'success', message: 'success message' }]);
+    });
+
+    test('captures messages in order', () => {
+      const { logger, messages } = createCapturingLogger();
+      logger.info('first');
+      logger.warn('second');
+      logger.error('third');
+      logger.success('fourth');
+
+      expect(messages).toHaveLength(4);
+      expect(messages[0]).toEqual({ level: 'info', message: 'first' });
+      expect(messages[1]).toEqual({ level: 'warn', message: 'second' });
+      expect(messages[2]).toEqual({ level: 'error', message: 'third' });
+      expect(messages[3]).toEqual({ level: 'success', message: 'fourth' });
+    });
+  });
+
+  describe('createConsoleLogger', () => {
+    test('creates a logger with all methods', () => {
+      const logger = createConsoleLogger('test-module', 'container_created');
+      expect(typeof logger.info).toBe('function');
+      expect(typeof logger.warn).toBe('function');
+      expect(typeof logger.error).toBe('function');
+      expect(typeof logger.success).toBe('function');
+    });
+  });
+});

package/src/hooks/logger.ts

@@ -0,0 +1,95 @@
+/**
+ * Hook Logger
+ *
+ * Provides a structured logger for hook scripts to report progress
+ * back to the CLI. Integrates with FuelGauge for visual feedback.
+ */
+
+import type { FuelGauge } from '../cli/fuel-gauge';
+import type { HookLogger } from './types';
+
+/**
+ * Create a hook logger that outputs to a FuelGauge progress indicator
+ *
+ * @param gauge - FuelGauge instance for visual output
+ * @param moduleId - Module ID for log prefix
+ * @param hookName - Hook name for log prefix
+ * @returns HookLogger instance
+ */
+export function createGaugeLogger(
+  gauge: FuelGauge,
+  moduleId: string,
+  hookName: string,
+): HookLogger {
+  const prefix = `[${moduleId}:${hookName}]`;
+
+  return {
+    info(message: string) {
+      gauge.addOutput(`${prefix} ${message}`);
+    },
+    warn(message: string) {
+      gauge.addOutput(`${prefix} ⚠ ${message}`);
+    },
+    error(message: string) {
+      gauge.addOutput(`${prefix} ✗ ${message}`);
+    },
+    success(message: string) {
+      gauge.addOutput(`${prefix} ✓ ${message}`);
+    },
+  };
+}
+
+/**
+ * Create a hook logger that outputs to console (for testing/debugging)
+ *
+ * @param moduleId - Module ID for log prefix
+ * @param hookName - Hook name for log prefix
+ * @returns HookLogger instance
+ */
+export function createConsoleLogger(moduleId: string, hookName: string): HookLogger {
+  const prefix = `[${moduleId}:${hookName}]`;
+
+  return {
+    info(message: string) {
+      console.log(`${prefix} ${message}`);
+    },
+    warn(message: string) {
+      console.warn(`${prefix} ⚠ ${message}`);
+    },
+    error(message: string) {
+      console.error(`${prefix} ✗ ${message}`);
+    },
+    success(message: string) {
+      console.log(`${prefix} ✓ ${message}`);
+    },
+  };
+}
+
+/**
+ * Create a hook logger that captures messages for testing
+ *
+ * @returns Object with logger and captured messages array
+ */
+export function createCapturingLogger(): {
+  logger: HookLogger;
+  messages: Array<{ level: string; message: string }>;
+} {
+  const messages: Array<{ level: string; message: string }> = [];
+
+  const logger: HookLogger = {
+    info(message: string) {
+      messages.push({ level: 'info', message });
+    },
+    warn(message: string) {
+      messages.push({ level: 'warn', message });
+    },
+    error(message: string) {
+      messages.push({ level: 'error', message });
+    },
+    success(message: string) {
+      messages.push({ level: 'success', message });
+    },
+  };
+
+  return { logger, messages };
+}

package/src/hooks/test-fixtures/failing-hook.ts

@@ -0,0 +1,13 @@
+/**
+ * Test fixture: hook script that throws an error. Migrated to
+ * defineHook in HOOK_API_V2 Phase 8.
+ */
+
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  requires: [],
+  handler: async () => {
+    throw new Error('Hook execution failed: simulated error');
+  },
+});

package/src/hooks/test-fixtures/no-default-hook.ts

@@ -0,0 +1,6 @@
+/**
+ * Test fixture: hook script without default export
+ */
+export function notDefault() {
+  return { result: 'wrong export' };
+}

package/src/hooks/test-fixtures/success-hook.ts

@@ -0,0 +1,20 @@
+/**
+ * Test fixture: successful hook script. Migrated to defineHook in
+ * HOOK_API_V2 Phase 8 — the executor now requires the brand.
+ *
+ * Uses `hook: 'container_created'` because that hook's contract output
+ * is `SecretCapturingHookOutput` (Record<string, unknown> | void), so
+ * returning an `api_key` field is allowed.
+ */
+
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  hook: 'container_created',
+  requires: [],
+  handler: async (ctx) => {
+    ctx.logger.info('Starting test hook');
+    ctx.logger.success('Test hook completed');
+    return { api_key: `test-key-for-${(ctx.vps_ip as string | undefined) ?? 'unknown'}` };
+  },
+});

package/src/hooks/test-fixtures/unbranded-hook.ts

@@ -0,0 +1,11 @@
+/**
+ * Test fixture: a default-exported function that does NOT use defineHook.
+ *
+ * The executor's brand check (HOOK_API_V2 Phase 8 / D8) must reject
+ * this with a clear error pointing at the migration guide. Used by
+ * executor.test.ts to verify the brand-enforcement code path.
+ */
+
+export default async function unbrandedHook() {
+  return { ok: true };
+}

package/src/hooks/test-fixtures/void-hook.ts

@@ -0,0 +1,13 @@
+/**
+ * Test fixture: hook script that returns nothing. Migrated to
+ * defineHook in HOOK_API_V2 Phase 8.
+ */
+
+import { defineHook } from '@celilo/capabilities';
+
+export default defineHook({
+  requires: [],
+  handler: async (ctx) => {
+    ctx.logger.info('Void hook ran');
+  },
+});