@josstei/maestro 1.6.4-rc.1

package/plugins/maestro/src/hooks/logic/after-agent-logic.js

@@ -0,0 +1,54 @@
+'use strict';
+
+const { log } = require('../../core/logger');
+const hookState = require('./hook-state');
+
+/**
+ * After-agent hook logic (runtime-agnostic).
+ *
+ * Field name mapping: the Gemini adapter maps ctx.promptResponse → ctx.agentResult
+ * before calling this function.
+ *
+ * @param {object} ctx - Internal context contract
+ * @param {string} ctx.sessionId
+ * @param {string|null} ctx.agentResult  - the agent response text
+ * @param {boolean} ctx.stopHookActive
+ * @returns {{ action: string, message: null, reason: string|null }}
+ */
+function handleAfterAgent(ctx) {
+  const agentName = hookState.getActiveAgent(ctx.sessionId);
+  if (!agentName) {
+    hookState.clearActiveAgent(ctx.sessionId);
+    return { action: 'allow', message: null, reason: null };
+  }
+
+  const agentResult = ctx.agentResult || '';
+  const hasTaskReport = agentResult.includes('## Task Report') || agentResult.includes('# Task Report');
+  const hasDownstream = agentResult.includes('## Downstream Context') || agentResult.includes('# Downstream Context');
+
+  const warnings = [];
+  if (!hasTaskReport) warnings.push('Missing Task Report section (expected ## Task Report heading)');
+  if (!hasDownstream) warnings.push('Missing Downstream Context section (expected ## Downstream Context heading)');
+
+  if (warnings.length > 0) {
+    const reason = warnings.join('; ');
+    if (ctx.stopHookActive) {
+      log('WARN', `AfterAgent [${agentName}]: Retry still malformed: ${reason} — allowing to prevent infinite loop`);
+    } else {
+      log('WARN', `AfterAgent [${agentName}]: WARN: ${reason} — requesting retry`);
+      hookState.clearActiveAgent(ctx.sessionId);
+      return {
+        action: 'deny',
+        message: null,
+        reason: `Handoff report validation failed: ${reason}. Please include both a ## Task Report section and a ## Downstream Context section in your response.`,
+      };
+    }
+  } else {
+    log('INFO', `AfterAgent [${agentName}]: Handoff report validated`);
+  }
+
+  hookState.clearActiveAgent(ctx.sessionId);
+  return { action: 'allow', message: null, reason: null };
+}
+
+module.exports = { handleAfterAgent };

package/plugins/maestro/src/hooks/logic/before-agent-logic.js

@@ -0,0 +1,57 @@
+'use strict';
+
+const { log } = require('../../core/logger');
+const { detectAgentFromPrompt, normalizeAgentName } = require('../../core/agent-registry');
+const { assertSessionId } = require('../../lib/validation');
+const { readFileSafe } = require('../../lib/io');
+const hookState = require('./hook-state');
+const state = require('../../state/session-state');
+
+/**
+ * Before-agent hook logic (runtime-agnostic).
+ *
+ * Field name mapping: the Gemini adapter maps ctx.prompt → ctx.agentInput
+ * before calling this function.
+ *
+ * @param {object} ctx - Internal context contract
+ * @param {string} ctx.sessionId
+ * @param {string} ctx.cwd
+ * @param {string|null} ctx.agentInput  - the agent prompt text
+ * @param {string} [ctx.event]          - hook event name (used in context message)
+ * @returns {{ action: string, message: string|null, reason: null }}
+ */
+function handleBeforeAgent(ctx) {
+  hookState.pruneStale();
+
+  const agentName = detectAgentFromPrompt(ctx.agentInput) || normalizeAgentName(ctx.agentName);
+
+  let validSession = false;
+  try { assertSessionId(ctx.sessionId); validSession = true; } catch (_) {}
+
+  if (agentName && validSession) {
+    hookState.setActiveAgent(ctx.sessionId, agentName);
+    log('INFO', `BeforeAgent: Detected agent '${agentName}' — set active agent [session=${ctx.sessionId}]`);
+  }
+
+  const sessionPath = state.resolveActiveSessionPath(ctx.cwd);
+  let contextParts = '';
+
+  const content = readFileSafe(sessionPath, '');
+  if (content) {
+    const parts = [];
+    const phaseMatch = content.match(/current_phase:\s*(\S+)/);
+    if (phaseMatch) parts.push(`current_phase=${phaseMatch[1]}`);
+    const statusMatch = content.match(/status:\s*(\S+)/);
+    if (statusMatch) parts.push(`status=${statusMatch[1]}`);
+    if (parts.length > 0) {
+      contextParts = `Active session: ${parts.join(', ')}`;
+    }
+  }
+
+  if (contextParts) {
+    return { action: 'allow', message: contextParts, reason: null };
+  }
+  return { action: 'allow', message: null, reason: null };
+}
+
+module.exports = { handleBeforeAgent };

package/plugins/maestro/src/hooks/logic/hook-state.js

@@ -0,0 +1,127 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { log } = require('../../core/logger');
+const { assertSessionId } = require('../../lib/validation');
+const { atomicWriteSync, readFileSafe } = require('../../lib/io');
+
+const HOOK_STATE_TTL_MS = 2 * 60 * 60 * 1000;
+
+const uid = process.getuid ? process.getuid() : 'default';
+const DEFAULT_BASE_DIR = process.env.MAESTRO_HOOKS_DIR
+  || path.join(os.tmpdir(), `maestro-hooks-${uid}`);
+
+function ensureBaseDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stats = fs.lstatSync(dir);
+  if (stats.isSymbolicLink()) {
+    throw new Error('Hook state directory must not be a symlink');
+  }
+}
+
+function createHookState(baseDir = DEFAULT_BASE_DIR) {
+  function getBaseDir() {
+    return baseDir;
+  }
+
+  function pruneStale() {
+    ensureBaseDir(baseDir);
+    if (!fs.existsSync(baseDir)) return;
+
+    const now = Date.now();
+    let entries;
+    try {
+      entries = fs.readdirSync(baseDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const dirPath = path.join(baseDir, entry.name);
+      try {
+        const stat = fs.lstatSync(dirPath);
+        if (now - stat.mtimeMs > HOOK_STATE_TTL_MS) {
+          fs.rmSync(dirPath, { recursive: true, force: true });
+        }
+      } catch {}
+    }
+  }
+
+  function setActiveAgent(sessionId, agentName) {
+    try {
+      assertSessionId(sessionId);
+    } catch {
+      log('ERROR', 'Invalid session_id: contains unsafe characters');
+      return false;
+    }
+    const agentFile = path.join(baseDir, sessionId, 'active-agent');
+    atomicWriteSync(agentFile, agentName);
+    return true;
+  }
+
+  function getActiveAgent(sessionId) {
+    try {
+      assertSessionId(sessionId);
+    } catch {
+      return '';
+    }
+    const agentFile = path.join(baseDir, sessionId, 'active-agent');
+    return readFileSafe(agentFile, '').trim();
+  }
+
+  function clearActiveAgent(sessionId) {
+    try {
+      assertSessionId(sessionId);
+    } catch {
+      return;
+    }
+    const agentFile = path.join(baseDir, sessionId, 'active-agent');
+    try {
+      fs.unlinkSync(agentFile);
+    } catch {}
+  }
+
+  function ensureSessionDir(sessionId) {
+    try {
+      assertSessionId(sessionId);
+    } catch {
+      return false;
+    }
+    ensureBaseDir(baseDir);
+    fs.mkdirSync(path.join(baseDir, sessionId), { recursive: true, mode: 0o700 });
+    return true;
+  }
+
+  function removeSessionDir(sessionId) {
+    try {
+      assertSessionId(sessionId);
+    } catch {
+      return false;
+    }
+    try {
+      fs.rmSync(path.join(baseDir, sessionId), { recursive: true, force: true });
+    } catch {}
+    return true;
+  }
+
+  return {
+    getBaseDir,
+    pruneStale,
+    setActiveAgent,
+    getActiveAgent,
+    clearActiveAgent,
+    ensureSessionDir,
+    removeSessionDir,
+  };
+}
+
+const defaultInstance = createHookState();
+
+module.exports = {
+  createHookState,
+  DEFAULT_BASE_DIR,
+  ...defaultInstance,
+};

package/plugins/maestro/src/hooks/logic/session-end-logic.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const hookState = require('./hook-state');
+
+/**
+ * Session-end hook logic (runtime-agnostic).
+ *
+ * @param {object} ctx - Internal context contract
+ * @param {string} ctx.sessionId
+ * @returns {{ action: string, message: null, reason: null }}
+ */
+function handleSessionEnd(ctx) {
+  hookState.removeSessionDir(ctx.sessionId);
+  return { action: 'advisory', message: null, reason: null };
+}
+
+module.exports = { handleSessionEnd };

package/plugins/maestro/src/hooks/logic/session-start-logic.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const hookState = require('./hook-state');
+const state = require('../../state/session-state');
+
+/**
+ * Session-start hook logic (runtime-agnostic).
+ *
+ * @param {object} ctx - Internal context contract
+ * @param {string} ctx.sessionId
+ * @param {string} ctx.cwd
+ * @returns {{ action: string, message: null, reason: null }}
+ */
+function handleSessionStart(ctx) {
+  hookState.pruneStale();
+
+  if (!state.hasActiveSession(ctx.cwd)) {
+    return { action: 'advisory', message: null, reason: null };
+  }
+
+  hookState.ensureSessionDir(ctx.sessionId);
+  return { action: 'advisory', message: null, reason: null };
+}
+
+module.exports = { handleSessionStart };

package/plugins/maestro/src/lib/discovery/index.js

@@ -0,0 +1,172 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { readFileSafe, writeIfChanged } = require('../io');
+
+/**
+ * @typedef {Object} DiscoveryEntry
+ * @property {string} id - Unique identifier derived by the identity function
+ * @property {string} path - Absolute path to the discovered file
+ */
+
+/**
+ * @typedef {Object} DiscoverOptions
+ * @property {string} dir - Absolute path to the directory to scan
+ * @property {string} pattern - File-matching pattern (e.g., '*.js', '*-logic.js', '**\/*.md')
+ * @property {Function} identity - (filepath: string) => string — derives the entry identifier
+ * @property {Function} [metadata] - (filepath: string, content: string) => Object — extracts metadata per file
+ * @property {Function} [validate] - (entry: DiscoveryEntry) => boolean — false excludes the entry
+ * @property {boolean} [recursive=false] - Whether to recurse into subdirectories
+ */
+
+/**
+ * Convert a simple glob pattern into a RegExp for matching filenames.
+ *
+ * Supports:
+ *   - `*` matches any sequence of characters except path separators
+ *   - Literal characters are escaped for safe regex usage
+ *   - The pattern is anchored to match the full filename
+ *
+ * @param {string} pattern - The glob pattern (filename portion only, no directory prefix)
+ * @returns {RegExp} Compiled regular expression
+ */
+function patternToRegex(pattern) {
+  let regex = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const char = pattern[i];
+    if (char === '*') {
+      regex += '[^/]*';
+    } else if ('.+?^${}()|[]\\'.includes(char)) {
+      regex += '\\' + char;
+    } else {
+      regex += char;
+    }
+  }
+  return new RegExp('^' + regex + '$');
+}
+
+/**
+ * Parse a discovery pattern into its file-matching regex and whether
+ * recursive scanning is implied by a `**\/` prefix.
+ *
+ * @param {string} pattern - The discovery pattern (e.g., '*.md', '**\/*.md')
+ * @returns {{ regex: RegExp, impliedRecursive: boolean }}
+ */
+function parsePattern(pattern) {
+  if (pattern.startsWith('**/')) {
+    return {
+      regex: patternToRegex(pattern.slice(3)),
+      impliedRecursive: true,
+    };
+  }
+  return {
+    regex: patternToRegex(pattern),
+    impliedRecursive: false,
+  };
+}
+
+/**
+ * Collect file paths from a directory, optionally recursing into subdirectories.
+ *
+ * @param {string} dir - Absolute path to scan
+ * @param {boolean} recursive - Whether to descend into child directories
+ * @returns {string[]} Absolute paths of all regular files found
+ */
+function collectFiles(dir, recursive) {
+  const results = [];
+
+  if (!fs.existsSync(dir)) {
+    return results;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory() && recursive) {
+      results.push(...collectFiles(fullPath, true));
+    } else if (entry.isFile()) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Scan a directory for files matching a pattern and produce an array of
+ * structured discovery entries.
+ *
+ * @param {DiscoverOptions} options
+ * @returns {Array<DiscoveryEntry>} Entries sorted by id
+ */
+function discover({ dir, pattern, identity, metadata, validate, recursive = false }) {
+  const { regex, impliedRecursive } = parsePattern(pattern);
+  const shouldRecurse = recursive || impliedRecursive;
+
+  const filePaths = collectFiles(dir, shouldRecurse);
+
+  const entries = [];
+
+  for (const filePath of filePaths) {
+    const filename = path.basename(filePath);
+
+    if (!regex.test(filename)) {
+      continue;
+    }
+
+    const id = identity(filePath);
+
+    let extra = {};
+    if (metadata) {
+      const content = readFileSafe(filePath);
+      extra = metadata(filePath, content) || {};
+    }
+
+    const entry = { id, path: filePath, ...extra };
+
+    if (validate && !validate(entry)) {
+      continue;
+    }
+
+    entries.push(entry);
+  }
+
+  entries.sort((a, b) => a.id.localeCompare(b.id));
+
+  return entries;
+}
+
+/**
+ * Serialize data as JSON and write it to a file, skipping the write when
+ * the content has not changed.
+ *
+ * @param {*} data - Any JSON-serializable value
+ * @param {string} outputPath - Absolute path to the output file
+ * @returns {boolean} True if the file was written, false if content was identical
+ */
+function generateRegistry(data, outputPath) {
+  const content = serializeRegistry(data);
+  return writeIfChanged(outputPath, content);
+}
+
+/**
+ * Serialize registry data to stable, newline-terminated JSON.
+ *
+ * @param {*} data - Any JSON-serializable registry value
+ * @returns {string} JSON content ready to write
+ */
+function serializeRegistry(data) {
+  return JSON.stringify(data, null, 2) + '\n';
+}
+
+module.exports = {
+  discover,
+  generateRegistry,
+  serializeRegistry,
+  patternToRegex,
+  parsePattern,
+  collectFiles,
+};

package/plugins/maestro/src/lib/errors/index.js

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * Base error class for the Maestro platform.
+ * Provides structured error metadata via `code`, `details`, and `context` properties.
+ *
+ * @extends Error
+ */
+class MaestroError extends Error {
+  /**
+   * @param {string} message - Human-readable error description
+   * @param {object} [opts]
+   * @param {string} [opts.code='MAESTRO_ERROR'] - Machine-readable error code
+   * @param {*} [opts.details=null] - Structured payload describing the failure
+   * @param {*} [opts.context=null] - Ambient context at the point of failure
+   */
+  constructor(message, { code = 'MAESTRO_ERROR', details = null, context = null } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.details = details;
+    this.context = context;
+  }
+}
+
+/**
+ * Raised when input data or arguments fail validation constraints.
+ *
+ * @extends MaestroError
+ */
+class ValidationError extends MaestroError {
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code='VALIDATION_ERROR'] - Subtype code for specific failures (e.g. HANDOFF_INCOMPLETE)
+   * @param {*} [opts.details]
+   * @param {*} [opts.context]
+   */
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: opts.code || 'VALIDATION_ERROR' });
+  }
+}
+
+/**
+ * Raised when a requested resource (agent, session, file, etc.) does not exist.
+ *
+ * @extends MaestroError
+ */
+class NotFoundError extends MaestroError {
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code='NOT_FOUND'] - Subtype code for specific failures
+   * @param {*} [opts.details]
+   * @param {*} [opts.context]
+   */
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: opts.code || 'NOT_FOUND' });
+  }
+}
+
+/**
+ * Raised when configuration is missing, malformed, or internally inconsistent.
+ *
+ * @extends MaestroError
+ */
+class ConfigError extends MaestroError {
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code='CONFIG_ERROR'] - Subtype code for specific failures
+   * @param {*} [opts.details]
+   * @param {*} [opts.context]
+   */
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: opts.code || 'CONFIG_ERROR' });
+  }
+}
+
+/**
+ * Raised when an operation is invalid for the current session or workflow state.
+ *
+ * @extends MaestroError
+ */
+class StateError extends MaestroError {
+  /**
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {string} [opts.code='STATE_ERROR'] - Subtype code for specific failures (e.g. DESIGN_GATE_UNAPPROVED, RECONCILIATION_PENDING)
+   * @param {*} [opts.details]
+   * @param {*} [opts.context]
+   */
+  constructor(message, opts = {}) {
+    super(message, { ...opts, code: opts.code || 'STATE_ERROR' });
+  }
+}
+
+module.exports = {
+  MaestroError,
+  ValidationError,
+  NotFoundError,
+  ConfigError,
+  StateError,
+};

package/plugins/maestro/src/lib/framework-detection.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const CONFIG_FILES = [
+  '.eslintrc',
+  '.prettierrc',
+  'tsconfig.json',
+  'webpack.config.js',
+  'vite.config.js',
+  'next.config.js',
+  '.env',
+  'docker-compose.yml',
+  'Dockerfile',
+  'Makefile',
+];
+
+const SKIP_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  '.next',
+  '__pycache__',
+  'venv',
+  '.venv',
+  'target',
+  'vendor',
+  '.cache',
+  '.output',
+  'coverage',
+  '.nyc_output',
+  '.pytest_cache',
+]);
+
+const FRAMEWORK_INDICATORS = {
+  react: ['react', 'react-dom'],
+  vue: ['vue'],
+  angular: ['@angular/core'],
+  next: ['next'],
+  express: ['express'],
+  fastify: ['fastify'],
+  django: ['django'],
+  flask: ['flask'],
+  rails: ['rails'],
+};
+
+module.exports = {
+  CONFIG_FILES,
+  SKIP_DIRS,
+  FRAMEWORK_INDICATORS,
+};