@josstei/maestro 1.6.4-rc.1

package/src/generator/entry-point-expander.js

@@ -0,0 +1,182 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { toTitleCase } = require('../lib/naming');
+const { emitInlineQuotedList } = require('../lib/yaml-emit');
+
+const DEFAULT_SRC = path.resolve(__dirname, '..');
+
+// Host platform names that must never appear as public skill names.
+// Confirmed: Claude /review shadows the built-in PR review command.
+// Confirmed: Codex review, debug, resume conflict with built-in commands.
+// Defensive: Claude debug and resume preemptively reserved.
+const HOST_RESERVED_NAMES = {
+  codex: new Set(['review', 'debug', 'resume']),
+  claude: new Set(['review', 'debug', 'resume']),
+};
+
+const ENTRY_POINT_CONFIG = {
+  gemini: {
+    templateFile: 'gemini-command.toml.tmpl',
+    outputPath: (e) => `commands/maestro/${e.name}.toml`,
+    preamblePlaceholder: 'skills_block',
+  },
+  claude: {
+    templateFile: 'claude-skill.md.tmpl',
+    outputPath: (e) => `claude/skills/${e.name}/SKILL.md`,
+    preamblePlaceholder: 'protocol_block',
+  },
+  codex: {
+    templateFile: 'codex-skill.md.tmpl',
+    outputPath: (e) => `plugins/maestro/skills/${e.name}/SKILL.md`,
+    preamblePlaceholder: 'refs_list',
+  },
+  qwen: null,
+};
+
+const CORE_COMMAND_CONFIG = {
+  gemini: {
+    templateFile: 'gemini-core-command.toml.tmpl',
+    outputPath: (e) => `commands/maestro/${e.name}.toml`,
+  },
+  claude: {
+    templateFile: 'claude-core-command.md.tmpl',
+    outputPath: (e) => `claude/skills/${e.name}/SKILL.md`,
+  },
+  codex: {
+    templateFile: 'codex-core-command.md.tmpl',
+    outputPath: (e) => `plugins/maestro/skills/${e.name}/SKILL.md`,
+  },
+  qwen: null,
+};
+
+const GEMINI_SESSION_STATE_BLOCK = `The current session state is provided below:
+
+<session-state>
+!{extension_root="\${MAESTRO_EXTENSION_PATH:-$HOME/.gemini/extensions/maestro}"; script="$extension_root/src/scripts/read-active-session.js"; if [[ -f "$script" ]]; then node "$script"; else echo "No active session"; fi}
+</session-state>
+
+Use the injected session state above as the source of truth for resume position.
+
+`;
+
+/**
+ * @param {{ name: string, runtimeNames?: Record<string, string> }} entry
+ * @param {string} runtimeName
+ * @returns {string}
+ */
+function getEntryPointRuntimeName(entry, runtimeName) {
+  return entry.runtimeNames?.[runtimeName] || entry.name;
+}
+
+/**
+ * @param {string} resolvedName
+ * @param {string} runtimeName
+ * @throws {Error}
+ */
+function assertNotHostReserved(resolvedName, runtimeName) {
+  const reserved = HOST_RESERVED_NAMES[runtimeName];
+  if (reserved && reserved.has(resolvedName)) {
+    throw new Error(
+      `Reserved ${runtimeName} host command name "${resolvedName}" conflicts with a built-in — ` +
+      'add a runtimeNames entry to the registry to remap it'
+    );
+  }
+}
+
+function applySubstitutions(template, substitutions) {
+  let content = template;
+  for (const [key, value] of Object.entries(substitutions)) {
+    const pattern = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+    content = content.replace(pattern, value);
+  }
+  return content;
+}
+
+function runTemplateExpansion({ runtimeName, registry, templatePath, outputPathFn, buildSubstitutions }) {
+  const template = fs.readFileSync(templatePath, 'utf8');
+  return registry.map((entry) => {
+    const runtimeEntry = {
+      ...entry,
+      name: getEntryPointRuntimeName(entry, runtimeName),
+    };
+    assertNotHostReserved(runtimeEntry.name, runtimeName);
+    return {
+      outputPath: outputPathFn(runtimeEntry),
+      content: applySubstitutions(template, buildSubstitutions(runtimeEntry)),
+    };
+  });
+}
+
+function resolveRuntimeConfig(configMap, runtimeName, kind) {
+  const config = configMap[runtimeName];
+  if (config === null) return null;
+  if (!config) {
+    throw new Error(`Unknown runtime for ${kind} expansion: "${runtimeName}"`);
+  }
+  return config;
+}
+
+/**
+ * @param {string} runtimeName
+ * @param {string} [srcDir]
+ * @returns {Array<{ outputPath: string, content: string }>}
+ */
+function expandEntryPoints(runtimeName, srcDir = DEFAULT_SRC) {
+  const config = resolveRuntimeConfig(ENTRY_POINT_CONFIG, runtimeName, 'entry-point');
+  if (!config) return [];
+
+  const registry = require(path.join(srcDir, 'entry-points', 'registry'));
+  const preambleBuilders = require(path.join(srcDir, 'entry-points', 'preamble-builders'));
+  const templatePath = path.join(srcDir, 'entry-points', 'templates', config.templateFile);
+  const buildPreamble = preambleBuilders[runtimeName];
+
+  return runTemplateExpansion({
+    runtimeName,
+    registry,
+    templatePath,
+    outputPathFn: config.outputPath,
+    buildSubstitutions: (runtimeEntry) => ({
+      name: runtimeEntry.name,
+      Name: toTitleCase(runtimeEntry.name),
+      description: runtimeEntry.description,
+      workflow_numbered: runtimeEntry.workflow.map((step, i) => `${i + 1}. ${step}`).join('\n'),
+      constraints_list: (runtimeEntry.constraints || []).map((c) => `- ${c}`).join('\n'),
+      [config.preamblePlaceholder]: buildPreamble(runtimeEntry),
+    }),
+  });
+}
+
+/**
+ * @param {string} runtimeName
+ * @param {string} [srcDir]
+ * @returns {Array<{ outputPath: string, content: string }>}
+ */
+function expandCoreCommands(runtimeName, srcDir = DEFAULT_SRC) {
+  const config = resolveRuntimeConfig(CORE_COMMAND_CONFIG, runtimeName, 'core-command');
+  if (!config) return [];
+
+  const registry = require(path.join(srcDir, 'entry-points', 'core-command-registry'));
+  const templatePath = path.join(srcDir, 'entry-points', 'templates', config.templateFile);
+
+  return runTemplateExpansion({
+    runtimeName,
+    registry,
+    templatePath,
+    outputPathFn: config.outputPath,
+    buildSubstitutions: (runtimeEntry) => ({
+      name: runtimeEntry.name,
+      description: runtimeEntry.description,
+      firstLine: runtimeEntry.firstLine,
+      requestType: runtimeEntry.requestType,
+      executeInstructions: runtimeEntry.executeInstructions,
+      preloadList: emitInlineQuotedList(runtimeEntry.preload),
+      sessionStateBlock: (runtimeName === 'gemini' && runtimeEntry.geminiSessionStateInjection)
+        ? GEMINI_SESSION_STATE_BLOCK
+        : '',
+    }),
+  });
+}
+
+module.exports = { expandEntryPoints, expandCoreCommands };

package/src/generator/file-writer.js

@@ -0,0 +1,167 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+
+/**
+ * @param {string} relativePath
+ * @param {string} rootDir
+ * @returns {string}
+ * @throws {Error} If the resolved path escapes the root directory
+ */
+function safeResolve(relativePath, rootDir) {
+  const resolved = path.resolve(rootDir, relativePath);
+  if (!resolved.startsWith(rootDir + path.sep) && resolved !== rootDir) {
+    throw new Error(`Path traversal detected: "${relativePath}" resolves outside project root`);
+  }
+  return resolved;
+}
+
+/**
+ * @param {string} absOutputPath
+ * @param {string} content
+ * @param {string} displayPath
+ */
+function executeDiff(absOutputPath, content, displayPath) {
+  if (!fs.existsSync(absOutputPath)) {
+    console.log(`+++ NEW: ${displayPath}`);
+    return;
+  }
+
+  const current = fs.readFileSync(absOutputPath, 'utf8');
+  if (current === content) {
+    return;
+  }
+
+  const tmpPath = absOutputPath + '.gen-tmp';
+  fs.writeFileSync(tmpPath, content, 'utf8');
+  try {
+    execFileSync('diff', ['-u', absOutputPath, tmpPath], { encoding: 'utf8' });
+  } catch (err) {
+    console.log(`--- ${displayPath}`);
+    console.log(err.stdout);
+  } finally {
+    fs.unlinkSync(tmpPath);
+  }
+}
+
+/**
+ * @param {string} absOutputPath
+ * @param {string} content
+ * @param {string} displayPath
+ */
+function executeDryRun(absOutputPath, content, displayPath) {
+  const exists = fs.existsSync(absOutputPath);
+  const current = exists ? fs.readFileSync(absOutputPath, 'utf8') : null;
+
+  let status;
+  if (!exists) {
+    status = 'CREATE';
+  } else if (current === content) {
+    status = 'UNCHANGED';
+  } else {
+    status = 'UPDATE';
+  }
+
+  console.log(`[${status}] ${displayPath}`);
+}
+
+/**
+ * @param {string} absOutputPath
+ * @param {string} content
+ * @param {{ written: number, unchanged: number, errors: number }} stats
+ */
+function executeWrite(absOutputPath, content, stats) {
+  fs.mkdirSync(path.dirname(absOutputPath), { recursive: true });
+
+  const exists = fs.existsSync(absOutputPath);
+  const current = exists ? fs.readFileSync(absOutputPath, 'utf8') : null;
+
+  if (current === content) {
+    stats.unchanged++;
+  } else {
+    fs.writeFileSync(absOutputPath, content, 'utf8');
+    stats.written++;
+  }
+}
+
+/**
+ * @typedef {Object} FileWriterOptions
+ * @property {string} rootDir - Absolute path to the project root directory
+ * @property {boolean} [dryRun=false] - Log intended actions without writing files
+ * @property {boolean} [diffMode=false] - Show unified diffs against existing files
+ */
+
+/**
+ * @typedef {Object} FileWriterStats
+ * @property {number} written - Number of files written (new or changed)
+ * @property {number} unchanged - Number of files skipped (content identical)
+ * @property {number} errors - Number of files that failed to write
+ */
+
+/**
+ * @typedef {Object} FileWriter
+ * @property {(outputPath: string, content: string) => void} write
+ * @property {(outputPaths: string[]) => void} clean
+ * @property {() => FileWriterStats} getStats
+ */
+
+/**
+ * Creates a file writer that handles write, diff, dry-run, and clean operations.
+ *
+ * @param {FileWriterOptions} opts
+ * @returns {FileWriter}
+ */
+function createFileWriter(opts) {
+  const { rootDir, dryRun = false, diffMode = false } = opts;
+  const stats = { written: 0, unchanged: 0, errors: 0 };
+  const readOnlyMode = dryRun || diffMode;
+
+  /**
+   * @param {string} outputPath - Relative path from rootDir
+   * @param {string} content - File content to write
+   */
+  function write(outputPath, content) {
+    try {
+      const absOutputPath = safeResolve(outputPath, rootDir);
+      if (diffMode) {
+        executeDiff(absOutputPath, content, outputPath);
+      } else if (dryRun) {
+        executeDryRun(absOutputPath, content, outputPath);
+      } else {
+        executeWrite(absOutputPath, content, stats);
+      }
+    } catch (err) {
+      console.error(`ERROR writing ${outputPath}: ${err.message}`);
+      stats.errors++;
+    }
+  }
+
+  /**
+   * @param {string[]} outputPaths - Relative paths from rootDir to delete
+   */
+  function clean(outputPaths) {
+    if (readOnlyMode) {
+      return;
+    }
+
+    for (const outputPath of outputPaths) {
+      const absPath = safeResolve(outputPath, rootDir);
+      if (fs.existsSync(absPath)) {
+        fs.unlinkSync(absPath);
+      }
+    }
+  }
+
+  /**
+   * @returns {FileWriterStats}
+   */
+  function getStats() {
+    return { written: stats.written, unchanged: stats.unchanged, errors: stats.errors };
+  }
+
+  return { write, clean, getStats };
+}
+
+module.exports = { createFileWriter, safeResolve };

package/src/generator/generation-session.js

@@ -0,0 +1,62 @@
+'use strict';
+
+const { createFileWriter } = require('./file-writer');
+
+function createGenerationSession({ rootDir, dryRun = false, diffMode = false }) {
+  const writer = createFileWriter({ rootDir, dryRun, diffMode });
+  const processingErrors = [];
+  const readOnlyMode = dryRun || diffMode;
+
+  function reportError(message, error) {
+    const formatted =
+      error && error.message ? `${message}: ${error.message}` : message;
+    console.error(`ERROR: ${formatted}`);
+    processingErrors.push(formatted);
+  }
+
+  function write(outputPath, content) {
+    writer.write(outputPath, content);
+  }
+
+  function writeAll(outputs) {
+    for (const output of outputs) {
+      write(output.outputPath, output.content);
+    }
+  }
+
+  function clean(outputPaths) {
+    try {
+      writer.clean(outputPaths);
+    } catch (error) {
+      reportError('cleaning generated files', error);
+    }
+  }
+
+  function getStats() {
+    const fileStats = writer.getStats();
+    return {
+      written: fileStats.written,
+      unchanged: fileStats.unchanged,
+      errors: fileStats.errors + processingErrors.length,
+      write_errors: fileStats.errors,
+      processing_errors: processingErrors.slice(),
+    };
+  }
+
+  return {
+    diffMode,
+    dryRun,
+    clean,
+    getStats,
+    isReadOnlyMode() {
+      return readOnlyMode;
+    },
+    reportError,
+    write,
+    writeAll,
+  };
+}
+
+module.exports = {
+  createGenerationSession,
+};

package/src/generator/manifest-curator.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * Collect every output path a generation run is expected to produce.
+ *
+ * Combines manifest-entry outputs with entry-point expander outputs so callers
+ * (e.g. the stale-pruner) can reason about the full artifact surface without
+ * re-implementing the expander iteration.
+ *
+ * @param {Array<{ outputs: Record<string, string> }>} manifest - Expanded manifest entries
+ * @param {Record<string, object>} runtimes - Runtime configs keyed by name
+ * @param {string} srcDir - Absolute path to the source directory
+ * @param {Array<Function>} entryPointExpanders - Expander fns, each (runtimeName, srcDir) => [{ outputPath }, ...]
+ * @returns {Set<string>} All output paths produced by this run
+ */
+function collectManifestPaths(manifest, runtimes, srcDir, entryPointExpanders) {
+  const paths = new Set();
+  for (const entry of manifest) {
+    for (const p of Object.values(entry.outputs)) paths.add(p);
+  }
+  for (const fn of entryPointExpanders) {
+    for (const rt of Object.keys(runtimes)) {
+      for (const { outputPath } of fn(rt, srcDir)) paths.add(outputPath);
+    }
+  }
+  return paths;
+}
+
+module.exports = {
+  collectManifestPaths,
+};

package/src/generator/manifest-expander.js

@@ -0,0 +1,256 @@
+'use strict';
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { toSnakeCase } = require('../lib/naming');
+
+/**
+ * Expand a glob pattern relative to srcDir.
+ * Supports `*` (wildcard within a single directory) and `**` (recursive).
+ * Returns sorted relative paths (posix separators).
+ * @param {string} pattern - Glob pattern to expand
+ * @param {string} srcDir - Absolute path to source directory
+ * @returns {string[]} Sorted array of matched relative paths
+ */
+function expandGlob(pattern, srcDir) {
+  const segments = pattern.split('/');
+  const results = [];
+
+  function walk(dir, segIndex) {
+    if (segIndex >= segments.length) return;
+
+    const segment = segments[segIndex];
+    const isLast = segIndex === segments.length - 1;
+
+    if (segment === '**') {
+      walk(dir, segIndex + 1);
+      let entries;
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          walk(path.join(dir, entry.name), segIndex);
+        }
+      }
+    } else {
+      const re = new RegExp(
+        '^' + segment.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*') + '$'
+      );
+
+      let entries;
+      try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        if (!re.test(entry.name)) continue;
+
+        const fullPath = path.join(dir, entry.name);
+        if (isLast) {
+          if (entry.isFile()) {
+            results.push(path.relative(srcDir, fullPath));
+          }
+        } else {
+          if (entry.isDirectory()) {
+            walk(fullPath, segIndex + 1);
+          }
+        }
+      }
+    }
+  }
+
+  walk(srcDir, 0);
+  return results.sort();
+}
+
+/**
+ * Apply the path-shape rewrites that differ per runtime but do NOT
+ * prepend outputDir. Handles skills/shared flattening and snake_case
+ * agent renaming.
+ * @param {string} srcRelPath
+ * @param {{ agentNaming?: string }} runtime
+ * @returns {string}
+ */
+function normalizeSrcRelPath(srcRelPath, runtime) {
+  let outPath = srcRelPath;
+
+  if (outPath.startsWith('skills/shared/')) {
+    outPath = 'skills/' + outPath.slice('skills/shared/'.length);
+  }
+
+  if (outPath.startsWith('agents/') && runtime.agentNaming === 'snake_case') {
+    const dir = path.dirname(outPath);
+    const base = path.basename(outPath);
+    outPath = dir + '/' + toSnakeCase(base);
+  }
+
+  return outPath;
+}
+
+/**
+ * Compute the output path for a source-relative path in a given runtime.
+ * Composes the name-shape rewrites with outputDir prepending.
+ * @param {string} srcRelPath - Source-relative path
+ * @param {{ agentNaming?: string, outputDir?: string }} runtime - Runtime configuration
+ * @returns {string} Computed output path
+ */
+function computeOutputPath(srcRelPath, runtime) {
+  return buildRuntimeOutputPath(runtime, normalizeSrcRelPath(srcRelPath, runtime));
+}
+
+/**
+ * Normalize an outputBase value for a given runtime.
+ * Accepts string, per-runtime object, or null/undefined.
+ * @param {string | Record<string, string> | null | undefined} outputBase - Base path specification
+ * @param {string} runtimeName - Name of the target runtime
+ * @returns {string} Normalized base path
+ */
+function normalizeOutputBase(outputBase, runtimeName) {
+  if (!outputBase) {
+    return '';
+  }
+
+  if (typeof outputBase === 'string') {
+    return outputBase;
+  }
+
+  if (typeof outputBase === 'object') {
+    return outputBase[runtimeName] || '';
+  }
+
+  throw new Error(`Invalid outputBase: ${JSON.stringify(outputBase)}`);
+}
+
+/**
+ * Join a base path with a relative path using posix separators.
+ * Returns the relative path unchanged when base is empty.
+ * @param {string} base - Base path prefix
+ * @param {string} relativePath - Path to append
+ * @returns {string} Joined path
+ */
+function joinRelativePath(base, relativePath) {
+  if (!base) {
+    return relativePath;
+  }
+
+  return path.posix.join(base, relativePath);
+}
+
+/**
+ * Prepend a runtime's outputDir to a relative path.
+ * Skips prepending when outputDir is absent or './'.
+ * @param {{ outputDir?: string }} runtime - Runtime configuration
+ * @param {string} relativePath - Path to prepend to
+ * @returns {string} Path with outputDir prepended
+ */
+function buildRuntimeOutputPath(runtime, relativePath) {
+  if (!runtime.outputDir || runtime.outputDir === './') {
+    return relativePath;
+  }
+
+  return runtime.outputDir + relativePath;
+}
+
+/**
+ * Validate that no manifest entries produce forbidden output paths.
+ * Throws if any entry targets a path reserved for src-first mode.
+ * @param {Array<{ outputs: Record<string, string> }>} manifest - Expanded manifest entries
+ */
+function assertNoMirroredSharedOutputs(manifest) {
+  for (const entry of manifest) {
+    for (const outputPath of Object.values(entry.outputs)) {
+      if (
+        outputPath === 'mcp/maestro-server-core.js' ||
+        outputPath === 'claude/mcp/maestro-server-core.js' ||
+        outputPath === 'plugins/maestro/mcp/maestro-server-core.js' ||
+        outputPath === 'lib/mcp/generated/resource-registry.js' ||
+        outputPath === 'plugins/maestro/lib/mcp/generated/resource-registry.js' ||
+        outputPath === 'plugins/maestro/lib/mcp/generated/agent-registry.js' ||
+        outputPath.startsWith('lib/') ||
+        outputPath.startsWith('claude/lib/') ||
+        outputPath.startsWith('plugins/maestro/lib/')
+      ) {
+        throw new Error(`Manifest output is not allowed in src-first mode: "${outputPath}"`);
+      }
+    }
+  }
+}
+
+/**
+ * Expand convention-based manifest rules into explicit entries.
+ *
+ * Three rule formats:
+ *   1. Legacy: has `outputs` field -- passed through unchanged
+ *   2. Explicit src + runtimes: has `src` and `runtimes` (no `glob`) -- expands to outputs per runtime
+ *   3. Glob: has `glob` and `runtimes` -- scans srcDir, produces one entry per matched file
+ *
+ * Does NOT merge entries for the same source file -- different rules may have different transforms.
+ * @param {Array<Object>} rules - Manifest rules to expand
+ * @param {Record<string, Object>} runtimes - Runtime configurations keyed by name
+ * @param {string} srcDir - Absolute path to source directory
+ * @returns {Array<{ src: string, transforms: string[], outputs: Record<string, string> }>}
+ */
+function expandManifest(rules, runtimes, srcDir) {
+  const entries = [];
+
+  for (const rule of rules) {
+    if (rule.outputs) {
+      entries.push(rule);
+      continue;
+    }
+
+    if (!rule.runtimes || !Array.isArray(rule.runtimes)) {
+      throw new Error(`Manifest rule missing "runtimes": ${JSON.stringify(rule)}`);
+    }
+    if (!rule.glob && !rule.src) {
+      throw new Error(`Manifest rule needs "glob" or "src": ${JSON.stringify(rule)}`);
+    }
+
+    let srcFiles;
+    if (rule.glob) {
+      srcFiles = expandGlob(rule.glob, srcDir);
+      if (rule.exclude) {
+        const excludeSet = new Set(rule.exclude);
+        srcFiles = srcFiles.filter((f) => !excludeSet.has(f));
+      }
+    } else {
+      srcFiles = [rule.src];
+    }
+
+    for (const srcRelPath of srcFiles) {
+      const outputs = {};
+      for (const runtimeName of rule.runtimes) {
+        const runtime = runtimes[runtimeName];
+        if (rule.outputName) {
+          outputs[runtimeName] = buildRuntimeOutputPath(runtime, rule.outputName);
+        } else if (rule.preserveSourcePath) {
+          const outputBase = normalizeOutputBase(rule.outputBase, runtimeName);
+          outputs[runtimeName] = buildRuntimeOutputPath(
+            runtime,
+            joinRelativePath(outputBase, srcRelPath)
+          );
+        } else {
+          const outputBase = normalizeOutputBase(rule.outputBase, runtimeName);
+          outputs[runtimeName] = buildRuntimeOutputPath(
+            runtime,
+            joinRelativePath(outputBase, normalizeSrcRelPath(srcRelPath, runtime))
+          );
+        }
+      }
+      entries.push({
+        src: srcRelPath,
+        transforms: rule.transforms,
+        outputs,
+      });
+    }
+  }
+
+  return entries;
+}
+
+module.exports = {
+  expandGlob,
+  normalizeSrcRelPath,
+  computeOutputPath,
+  normalizeOutputBase,
+  joinRelativePath,
+  buildRuntimeOutputPath,
+  assertNoMirroredSharedOutputs,
+  expandManifest,
+};