@josstei/maestro 1.6.4-rc.1

package/src/generator/payload-builder.js

@@ -0,0 +1,217 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { isAdapterFile, extractRuntime } = require('../platforms/shared/adapters/conventions');
+
+const VERSION_JSON_FILENAME = 'version.json';
+
+const ADAPTER_PATH_PREFIX = 'platforms/shared/adapters/';
+
+/**
+ * Determine whether a relative path is an adapter file belonging to a
+ * different runtime. Returns true when the file is a foreign adapter that
+ * should be excluded from the payload.
+ * @param {string} relativePath - Posix-style relative path from src/
+ * @param {string} runtimeName - Target runtime name
+ * @returns {boolean}
+ */
+function isForeignAdapter(relativePath, runtimeName) {
+  if (!relativePath.startsWith(ADAPTER_PATH_PREFIX)) {
+    return false;
+  }
+  const filename = relativePath.slice(ADAPTER_PATH_PREFIX.length);
+  if (!isAdapterFile(filename)) {
+    return false;
+  }
+  return extractRuntime(filename) !== runtimeName;
+}
+
+/**
+ * Base allowlist of src/ prefixes included in detached payloads.
+ * Each entry is a directory prefix (trailing slash) or a specific file path.
+ * @type {ReadonlyArray<string>}
+ */
+const DETACHED_PAYLOAD_BASE_ALLOWLIST = Object.freeze([
+  'core/',
+  'lib/',
+  'config/',
+  'hooks/',
+  'mcp/',
+  'platforms/shared/',
+  'state/',
+  'agents/',
+  'skills/',
+  'references/',
+  'templates/',
+  'entry-points/',
+  'generated/',
+]);
+
+/**
+ * Build a payload allowlist for a specific runtime by extending the base
+ * allowlist with the runtime-specific config file entry.
+ * @param {string} runtimeName
+ * @returns {string[]}
+ */
+function buildPayloadAllowlist(runtimeName) {
+  return [
+    ...DETACHED_PAYLOAD_BASE_ALLOWLIST,
+    `platforms/${runtimeName}/runtime-config.js`,
+  ];
+}
+
+/**
+ * Determine whether a file at the given relative path should be included
+ * in a detached payload based on the provided allowlist.
+ * @param {string} relativePath - Posix-style relative path from src/
+ * @param {string[]} [allowlist] - Allowlist to check against; defaults to base
+ * @returns {boolean}
+ */
+function shouldIncludeInPayload(relativePath, allowlist) {
+  const list = allowlist || DETACHED_PAYLOAD_BASE_ALLOWLIST;
+  return list.some((prefix) => relativePath.startsWith(prefix));
+}
+
+/**
+ * Determine whether a directory walk should descend into the given directory.
+ * Returns true when the directory is either a parent of an allowlisted prefix
+ * or a child within an allowlisted prefix.
+ * @param {string} relativeDir - Posix-style relative directory path from src/
+ * @param {string[]} [allowlist] - Allowlist to check against; defaults to base
+ * @returns {boolean}
+ */
+function shouldDescendInto(relativeDir, allowlist) {
+  const dir = relativeDir.endsWith('/') ? relativeDir : `${relativeDir}/`;
+  const list = allowlist || DETACHED_PAYLOAD_BASE_ALLOWLIST;
+  return list.some(
+    (prefix) => prefix.startsWith(dir) || dir.startsWith(prefix)
+  );
+}
+
+/**
+ * Walk srcDir, copy allowed files into outputDir, then remove stale files
+ * from outputDir that are no longer present in the source.
+ * @param {string} srcDir - Absolute path to the source directory
+ * @param {string} outputDir - Absolute path to the output payload directory
+ * @param {string} [runtimeName] - Runtime name for allowlist extension
+ * @returns {{ copied: number, removed: number, skipped: number }}
+ */
+function buildDetachedPayload(srcDir, outputDir, runtimeName) {
+  const allowlist = runtimeName
+    ? buildPayloadAllowlist(runtimeName)
+    : [...DETACHED_PAYLOAD_BASE_ALLOWLIST];
+  const stats = { copied: 0, removed: 0, skipped: 0 };
+  const keptOutputs = new Set();
+
+  function walkAndCopy(dir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path
+        .relative(srcDir, fullPath)
+        .split(path.sep)
+        .join('/');
+
+      if (entry.isDirectory()) {
+        if (shouldDescendInto(relativePath, allowlist)) {
+          walkAndCopy(fullPath);
+        } else {
+          stats.skipped++;
+        }
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      if (!shouldIncludeInPayload(relativePath, allowlist)) {
+        stats.skipped++;
+        continue;
+      }
+
+      if (runtimeName && isForeignAdapter(relativePath, runtimeName)) {
+        stats.skipped++;
+        continue;
+      }
+
+      keptOutputs.add(relativePath);
+      const outputPath = path.join(outputDir, relativePath);
+      fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+      const content = fs.readFileSync(fullPath, 'utf8');
+      const existing = fs.existsSync(outputPath)
+        ? fs.readFileSync(outputPath, 'utf8')
+        : null;
+      if (existing !== content) {
+        fs.writeFileSync(outputPath, content, 'utf8');
+        stats.copied++;
+      }
+    }
+  }
+
+  function cleanStale(dir) {
+    if (!fs.existsSync(dir)) {
+      return;
+    }
+
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path
+        .relative(outputDir, fullPath)
+        .split(path.sep)
+        .join('/');
+      if (entry.isDirectory()) {
+        cleanStale(fullPath);
+        if (
+          fs.existsSync(fullPath) &&
+          fs.readdirSync(fullPath).length === 0
+        ) {
+          fs.rmdirSync(fullPath);
+        }
+      } else if (!keptOutputs.has(relativePath)) {
+        fs.unlinkSync(fullPath);
+        stats.removed++;
+      }
+    }
+  }
+
+  walkAndCopy(srcDir);
+  if (runtimeName) {
+    keptOutputs.add(VERSION_JSON_FILENAME);
+  }
+  cleanStale(outputDir);
+  return stats;
+}
+
+/**
+ * Write a version.json file to each payload directory.
+ * Only writes when the content has changed (avoids unnecessary churn).
+ * @param {string[]} payloadDirs - Absolute paths to payload output directories
+ * @param {string} version - Semantic version string to stamp
+ */
+function stampVersion(payloadDirs, version) {
+  const versionContent = JSON.stringify({ version }, null, 2) + '\n';
+
+  for (const payloadDir of payloadDirs) {
+    const versionPath = path.join(payloadDir, VERSION_JSON_FILENAME);
+    const existingContent = fs.existsSync(versionPath)
+      ? fs.readFileSync(versionPath, 'utf8')
+      : null;
+
+    if (existingContent !== versionContent) {
+      fs.writeFileSync(versionPath, versionContent, 'utf8');
+    }
+  }
+}
+
+module.exports = {
+  DETACHED_PAYLOAD_BASE_ALLOWLIST,
+  buildPayloadAllowlist,
+  shouldIncludeInPayload,
+  isForeignAdapter,
+  shouldDescendInto,
+  buildDetachedPayload,
+  stampVersion,
+};

package/src/generator/registry-scanner.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { discover, generateRegistry } = require('../lib/discovery');
+const { serializeRegistry } = require('../lib/discovery');
+const { parse } = require('../lib/frontmatter');
+const { toPascalCase } = require('../lib/naming');
+
+function buildAgentRegistry(srcDir) {
+  const agentEntries = discover({
+    dir: path.join(srcDir, 'agents'),
+    pattern: '*.md',
+    identity: (filepath) => path.basename(filepath, '.md'),
+    metadata: (filepath, content) => {
+      const { frontmatter } = parse(content);
+      const name = frontmatter.name || path.basename(filepath, '.md');
+      const capabilities = frontmatter.capabilities || 'read_only';
+      const rawTools = frontmatter.tools || [];
+      const tools = Array.isArray(rawTools) ? rawTools : [rawTools];
+      return { name, capabilities, tools };
+    },
+  });
+
+  return agentEntries.map(({ name, capabilities, tools }) => ({ name, capabilities, tools }));
+}
+
+function buildResourceRegistry(srcDir) {
+  const skillsParentDir = path.join(srcDir, 'skills');
+  const skillEntries = discover({
+    dir: path.join(srcDir, 'skills', 'shared'),
+    pattern: '**/*.md',
+    identity: (filepath) => {
+      if (path.basename(filepath) === 'SKILL.md') {
+        return path.basename(path.dirname(filepath));
+      }
+      return path.basename(filepath, '.md');
+    },
+    metadata: (filepath) => {
+      const relativePath = 'skills/' + path.relative(skillsParentDir, filepath)
+        .split(path.sep)
+        .join('/');
+      return { relativePath };
+    },
+  });
+
+  const templateEntries = discover({
+    dir: path.join(srcDir, 'templates'),
+    pattern: '*.md',
+    identity: (filepath) => path.basename(filepath, '.md'),
+    metadata: (filepath) => ({
+      relativePath: `templates/${path.basename(filepath)}`,
+    }),
+  });
+
+  const referenceEntries = discover({
+    dir: path.join(srcDir, 'references'),
+    pattern: '*.md',
+    identity: (filepath) => path.basename(filepath, '.md'),
+    metadata: (filepath) => ({
+      relativePath: `references/${path.basename(filepath)}`,
+    }),
+  });
+
+  const resources = {};
+  for (const entry of [...skillEntries, ...templateEntries, ...referenceEntries]) {
+    resources[entry.id] = entry.relativePath;
+  }
+
+  return resources;
+}
+
+function buildHookRegistry(srcDir) {
+  const hookEntries = discover({
+    dir: path.join(srcDir, 'hooks', 'logic'),
+    pattern: '*-logic.js',
+    identity: (filepath) => path.basename(filepath).replace(/-logic\.js$/, ''),
+    metadata: (filepath) => {
+      const file = path.basename(filepath);
+      const hookName = file.replace(/-logic\.js$/, '');
+      return {
+        module: `hooks/logic/${file}`,
+        fn: `handle${toPascalCase(hookName)}`,
+      };
+    },
+  });
+
+  const hooks = {};
+  for (const entry of hookEntries) {
+    hooks[entry.id] = { module: entry.module, fn: entry.fn };
+  }
+
+  return hooks;
+}
+
+function buildRegistries(srcDir) {
+  return [
+    { fileName: 'agent-registry.json', data: buildAgentRegistry(srcDir) },
+    { fileName: 'resource-registry.json', data: buildResourceRegistry(srcDir) },
+    { fileName: 'hook-registry.json', data: buildHookRegistry(srcDir) },
+  ];
+}
+
+function collectRegistryOutputs(srcDir, rootDir = path.dirname(srcDir)) {
+  const generatedDir = path.join(srcDir, 'generated');
+
+  return buildRegistries(srcDir).map(({ fileName, data }) => ({
+    outputPath: path.relative(rootDir, path.join(generatedDir, fileName)),
+    content: serializeRegistry(data),
+  }));
+}
+
+/**
+ * Run all discovery scans and write the resulting JSON registry files to
+ * src/generated/.
+ * @param {string} srcDir - Absolute path to the src/ directory
+ */
+function generateRegistries(srcDir) {
+  const generatedDir = path.join(srcDir, 'generated');
+  fs.mkdirSync(generatedDir, { recursive: true });
+
+  for (const { fileName, data } of buildRegistries(srcDir)) {
+    generateRegistry(data, path.join(generatedDir, fileName));
+  }
+}
+
+module.exports = {
+  collectRegistryOutputs,
+  generateRegistries,
+};

package/src/generator/stale-pruner.js

@@ -0,0 +1,101 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Recursively collect all file paths under a directory.
+ * Returns relative paths using forward-slash separators.
+ * @param {string} dir - Relative directory path (forward-slash separated)
+ * @param {string} rootDir - Absolute path to the project root
+ * @returns {string[]} Relative file paths within the directory
+ */
+function walkDir(dir, rootDir) {
+  const results = [];
+  const absDir = path.join(rootDir, dir);
+  if (!fs.existsSync(absDir)) {
+    return results;
+  }
+  const entries = fs.readdirSync(absDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const relPath = `${dir}/${entry.name}`;
+    if (entry.isDirectory()) {
+      results.push(...walkDir(relPath, rootDir));
+    } else {
+      results.push(relPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Recursively collect all subdirectory paths under a directory.
+ * Returns leaf-first ordering suitable for bottom-up deletion.
+ * @param {string} dir - Relative directory path (forward-slash separated)
+ * @param {string} rootDir - Absolute path to the project root
+ * @returns {string[]} Relative subdirectory paths, deepest first within each subtree
+ */
+function walkSubdirs(dir, rootDir) {
+  const results = [];
+  const absDir = path.join(rootDir, dir);
+  if (!fs.existsSync(absDir)) {
+    return results;
+  }
+  const entries = fs.readdirSync(absDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const relPath = `${dir}/${entry.name}`;
+    results.push(...walkSubdirs(relPath, rootDir));
+    results.push(relPath);
+  }
+  return results;
+}
+
+/**
+ * Prune stale generated files and empty directories from owned directories.
+ *
+ * Walks each owned directory, identifies files not present in the manifest path set,
+ * deletes them, then removes any empty directories left behind (deepest first).
+ *
+ * @param {Object} opts
+ * @param {string} opts.rootDir - Absolute path to the project root
+ * @param {Set<string>} opts.manifestPaths - Set of all valid manifest output paths (forward-slash relative)
+ * @param {string[]} opts.ownedDirs - Relative directory paths the generator owns
+ * @returns {{ pruned: string[], emptyDirsRemoved: string[] }}
+ */
+function pruneStaleFiles({ rootDir, manifestPaths, ownedDirs }) {
+  const pruned = [];
+  const emptyDirsRemoved = [];
+
+  const allOwnedFiles = [];
+  for (const dir of ownedDirs) {
+    allOwnedFiles.push(...walkDir(dir, rootDir));
+  }
+
+  const staleFiles = allOwnedFiles.filter((filePath) => !manifestPaths.has(filePath));
+  for (const filePath of staleFiles) {
+    fs.unlinkSync(path.join(rootDir, filePath));
+    pruned.push(filePath);
+  }
+
+  const ownedSubdirs = ownedDirs
+    .flatMap((dir) => walkSubdirs(dir, rootDir))
+    .sort((a, b) => b.length - a.length);
+
+  for (const dir of ownedSubdirs) {
+    const absDir = path.join(rootDir, dir);
+    if (!fs.existsSync(absDir)) {
+      continue;
+    }
+    if (fs.readdirSync(absDir).length === 0) {
+      fs.rmdirSync(absDir);
+      emptyDirsRemoved.push(dir);
+    }
+  }
+
+  return { pruned, emptyDirsRemoved };
+}
+
+module.exports = { pruneStaleFiles };

package/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/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/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/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 };