@josstei/maestro 1.6.4-rc.1

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

package/src/lib/frontmatter/index.js

@@ -0,0 +1,262 @@
+'use strict';
+
+/**
+ * Unified frontmatter parsing module.
+ *
+ * Consolidates three distinct boundary-detection implementations and two YAML
+ * escaping implementations into a single authoritative module.
+ *
+ * Boundary detection approaches unified:
+ *   - Character-offset indexOf (agent-stub.js, parseFrontmatterOnly)
+ *   - Line-split iteration (core/frontmatter-parser.js parse)
+ *   - Regex multiline match (skill-metadata.js)
+ *
+ * @module lib/frontmatter
+ */
+
+/**
+ * Parse a double-quoted string value with escape sequence support.
+ *
+ * Handles \n, \r, \t, \\, and \" escape sequences. Unknown escape sequences
+ * preserve the backslash character.
+ *
+ * @param {string} raw - The inner content of a double-quoted string (without outer quotes).
+ * @returns {string} The unescaped string value.
+ */
+function parseDoubleQuotedValue(raw) {
+  let value = '';
+
+  for (let i = 0; i < raw.length; i++) {
+    const char = raw[i];
+    const next = raw[i + 1];
+
+    if (char !== '\\' || next == null) {
+      value += char;
+      continue;
+    }
+
+    switch (next) {
+      case '"':
+        value += '"';
+        i++;
+        break;
+      case '\\':
+        value += '\\';
+        i++;
+        break;
+      case 'n':
+        value += '\n';
+        i++;
+        break;
+      case 'r':
+        value += '\r';
+        i++;
+        break;
+      case 't':
+        value += '\t';
+        i++;
+        break;
+      default:
+        value += char;
+        break;
+    }
+  }
+
+  return value;
+}
+
+/**
+ * Parse a YAML-like scalar value with type coercion.
+ *
+ * Supports inline arrays ([a, b, c]), double-quoted strings with escape
+ * sequences, single-quoted strings with '' escaping, numeric literals, and
+ * bare string values.
+ *
+ * @param {string} raw - The raw value string to parse.
+ * @returns {string|number|string[]} The parsed value.
+ */
+function parseValue(raw) {
+  if (raw.startsWith('[') && raw.endsWith(']')) {
+    const inner = raw.slice(1, -1);
+    if (inner.trim() === '') return [];
+    return inner.split(',').map((s) => s.trim());
+  }
+
+  if (raw.startsWith('"') && raw.endsWith('"')) {
+    return parseDoubleQuotedValue(raw.slice(1, -1));
+  }
+
+  if (raw.startsWith("'") && raw.endsWith("'")) {
+    return raw.slice(1, -1).replace(/''/g, "'");
+  }
+
+  const num = Number(raw);
+  if (raw !== '' && !isNaN(num)) {
+    return num;
+  }
+
+  return raw;
+}
+
+/**
+ * Split content at the frontmatter boundary using line iteration.
+ *
+ * Unifies the three boundary-detection approaches into one canonical
+ * implementation. Uses line-split iteration (the most permissive approach)
+ * which handles all edge cases including content without a trailing newline
+ * after the closing delimiter.
+ *
+ * @param {string} content - The full content string with optional frontmatter.
+ * @returns {{ raw: string, body: string }} The raw frontmatter text (between
+ *   delimiters, excluding them) and the remaining body. When no valid
+ *   frontmatter block is found, raw is '' and body is the original content.
+ */
+function splitAtBoundary(content) {
+  const lines = content.split('\n');
+
+  if (lines[0] !== '---') {
+    return { raw: '', body: content };
+  }
+
+  let endIndex = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === '---') {
+      endIndex = i;
+      break;
+    }
+  }
+
+  if (endIndex === -1) {
+    return { raw: '', body: content };
+  }
+
+  const raw = lines.slice(1, endIndex).join('\n');
+  const body = lines.slice(endIndex + 1).join('\n');
+
+  return { raw, body };
+}
+
+/**
+ * Parse frontmatter key-value lines into an object.
+ *
+ * @param {string[]} lines - Lines between frontmatter delimiters.
+ * @param {function} valueFn - Function to apply to each raw value string.
+ * @returns {Object} Parsed frontmatter object.
+ */
+function parseLines(lines, valueFn) {
+  const frontmatter = {};
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.substring(0, colonIndex).trim();
+    const rawValue = line.substring(colonIndex + 1).trim();
+
+    frontmatter[key] = valueFn(rawValue);
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Parse frontmatter with full type coercion (rich parser).
+ *
+ * Splits content on `---` delimiters and parses key-value pairs with type
+ * coercion via {@link parseValue}. Arrays, numbers, and quoted strings are
+ * converted to their native types.
+ *
+ * Returns empty frontmatter and the full content as body when no valid
+ * frontmatter block is found (missing opening or closing `---`).
+ *
+ * @param {string} content - The full content string with optional frontmatter.
+ * @returns {{ frontmatter: Object, body: string }} Parsed frontmatter object and remaining body.
+ */
+function parse(content) {
+  const { raw, body } = splitAtBoundary(content);
+
+  if (raw === '' && body === content) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const fmLines = raw.split('\n');
+  const frontmatter = parseLines(fmLines, parseValue);
+
+  return { frontmatter, body };
+}
+
+/**
+ * Parse frontmatter returning raw string values without type coercion (simple parser).
+ *
+ * Uses substring-based boundary detection (`---\n` prefix and `\n---\n`
+ * closing). Returns a wrapper object with a frontmatter map (raw string
+ * values) and the remaining body text.
+ *
+ * This intentionally uses stricter boundary detection than {@link parse} or
+ * {@link splitAtBoundary}: it requires a newline after the closing `---`
+ * delimiter. This preserves the historical contract where content ending
+ * exactly at `---` (no trailing newline) returns empty frontmatter with the
+ * full content as body.
+ *
+ * Returns empty frontmatter and the full content as body when no valid
+ * frontmatter block is found.
+ *
+ * @param {string} content - The full content string with optional frontmatter.
+ * @returns {{ frontmatter: Object<string, string>, body: string }} Raw frontmatter map and remaining body.
+ */
+function parseFrontmatterOnly(content) {
+  if (!content.startsWith('---\n')) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const end = content.indexOf('\n---\n', 4);
+  if (end === -1) {
+    return { frontmatter: {}, body: content };
+  }
+
+  const lines = content.slice(4, end).split('\n');
+  const frontmatter = parseLines(lines, (v) => v);
+  const body = content.slice(end + 5);
+
+  return { frontmatter, body };
+}
+
+/**
+ * Extract a single frontmatter value by key via regex.
+ *
+ * Searches for `key: value` on its own line within the content. Does not
+ * require the content to have valid frontmatter delimiters -- works on any
+ * text that contains `key: value` lines.
+ *
+ * @param {string} content - The content string to search.
+ * @param {string} key - The frontmatter key to extract.
+ * @returns {string|null} The trimmed value string, or null if the key is not found.
+ */
+function extractValue(content, key) {
+  const match = content.match(new RegExp(`(?:^|\\n)${key}:\\s*(.+)$`, 'm'));
+  return match ? match[1].trim() : null;
+}
+
+/**
+ * Escape special characters in a YAML string value.
+ *
+ * Escapes backslashes and double quotes for safe embedding inside a
+ * double-quoted YAML scalar. Non-string inputs are coerced via String().
+ *
+ * @param {string} value - Value to escape.
+ * @returns {string} Escaped value safe for double-quoted YAML context.
+ */
+function escapeYaml(value) {
+  if (typeof value !== 'string') return String(value);
+  return value.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+module.exports = {
+  parse,
+  parseFrontmatterOnly,
+  extractValue,
+  escapeYaml,
+  splitAtBoundary,
+  parseValue,
+  parseDoubleQuotedValue,
+};

package/src/lib/io/index.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+let counter = 0;
+
+/**
+ * Creates parent directories and writes content atomically via temp-file + rename.
+ * The parent directory is created with mode 0o700 and the file with mode 0o600.
+ *
+ * @param {string} filePath - Absolute path to the target file
+ * @param {string} content - Content to write
+ */
+function atomicWriteSync(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmpFile = `${filePath}.tmp.${process.pid}.${++counter}`;
+  try {
+    fs.writeFileSync(tmpFile, content, { mode: 0o600 });
+    fs.renameSync(tmpFile, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmpFile); } catch {}
+    throw err;
+  }
+}
+
+/**
+ * Reads a file and returns its contents as a UTF-8 string.
+ * Returns the fallback value on any error (missing file, permission denied, etc.).
+ *
+ * @param {string} filePath - Absolute or relative path to the file
+ * @param {string} [fallback=''] - Value returned when reading fails
+ * @returns {string} File contents or fallback
+ */
+function readFileSafe(filePath, fallback = '') {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Reads a file and parses its contents as JSON.
+ * Returns the fallback value on any error (missing file, invalid JSON, etc.).
+ *
+ * @param {string} filePath - Absolute or relative path to the file
+ * @param {*} [fallback=null] - Value returned when reading or parsing fails
+ * @returns {*} Parsed JSON value or fallback
+ */
+function readJsonSafe(filePath, fallback = null) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Writes content to a file only when it differs from existing content.
+ * Creates parent directories if they do not exist.
+ *
+ * @param {string} filePath - Absolute path to the target file
+ * @param {string} content - Content to write
+ * @returns {boolean} True if the file was written, false if content was identical
+ */
+function writeIfChanged(filePath, content) {
+  const existing = fs.existsSync(filePath)
+    ? fs.readFileSync(filePath, 'utf8')
+    : null;
+
+  if (existing === content) {
+    return false;
+  }
+
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  return true;
+}
+
+/**
+ * Ensures a directory exists, creating it and all parent directories as needed.
+ *
+ * @param {string} dirPath - Absolute path to the directory
+ */
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+module.exports = {
+  atomicWriteSync,
+  readFileSafe,
+  readJsonSafe,
+  writeIfChanged,
+  ensureDir,
+};