@josstei/maestro 1.6.4-rc.1

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

package/claude/src/lib/naming/index.js

@@ -0,0 +1,94 @@
+'use strict';
+
+const TITLE_SPECIAL_CASES = {
+  'a11y-audit': 'Accessibility Audit',
+  'seo-audit': 'SEO Audit',
+};
+
+/**
+ * Convert a kebab-case name to snake_case.
+ * @param {string} name - Name in kebab-case (e.g. 'api-designer')
+ * @returns {string} Name in snake_case (e.g. 'api_designer')
+ */
+function toSnakeCase(name) {
+  return name.replace(/-/g, '_');
+}
+
+/**
+ * Convert a snake_case name to kebab-case.
+ * @param {string} name - Name in snake_case (e.g. 'api_designer')
+ * @returns {string} Name in kebab-case (e.g. 'api-designer')
+ */
+function toKebabCase(name) {
+  return name.replace(/_/g, '-');
+}
+
+/**
+ * Convert a kebab-case name to PascalCase.
+ * @param {string} name - Name in kebab-case (e.g. 'session-start')
+ * @returns {string} Name in PascalCase (e.g. 'SessionStart')
+ */
+function toPascalCase(name) {
+  return name
+    .split('-')
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join('');
+}
+
+/**
+ * Convert a kebab-case name to title case for display.
+ * Includes special-case handling for abbreviations and accessibility terms.
+ *
+ * @param {string} name - Name in kebab-case (e.g. 'perf-check')
+ * @returns {string} Display-friendly title (e.g. 'Perf Check')
+ */
+function toTitleCase(name) {
+  if (TITLE_SPECIAL_CASES[name]) {
+    return TITLE_SPECIAL_CASES[name];
+  }
+  return name
+    .split('-')
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+/**
+ * Replace all occurrences of canonical kebab-case names in content
+ * with the target naming convention.
+ *
+ * When targetCase is 'snake_case', each name in the provided list
+ * is matched using word-boundary regexes and replaced with its snake_case
+ * equivalent. When targetCase is 'kebab-case', content is returned unchanged
+ * since kebab-case is the canonical format.
+ *
+ * @param {string} content - Text content containing name references
+ * @param {string[]} names - Canonical kebab-case names to replace
+ * @param {string} targetCase - Target convention: 'snake_case' or 'kebab-case'
+ * @returns {string} Content with names converted to the target convention
+ */
+function replaceInContent(content, names, targetCase) {
+  if (targetCase !== 'snake_case') {
+    return content;
+  }
+
+  if (!names || names.length === 0) {
+    return content;
+  }
+
+  let result = content;
+  for (const name of names) {
+    const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`\\b${escaped}\\b`, 'g');
+    result = result.replace(pattern, toSnakeCase(name));
+  }
+  return result;
+}
+
+module.exports = {
+  TITLE_SPECIAL_CASES,
+  toSnakeCase,
+  toKebabCase,
+  toPascalCase,
+  toTitleCase,
+  replaceInContent,
+};

package/claude/src/lib/validation/index.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { ValidationError } = require('../errors');
+
+const SESSION_ID_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * @param {*} value
+ * @param {string} label
+ * @throws {ValidationError}
+ */
+function assertNonEmptyArray(value, label) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new ValidationError(`${label} must be a non-empty array`, {
+      details: { value, label },
+    });
+  }
+}
+
+/**
+ * @param {*} id
+ * @throws {ValidationError}
+ */
+function assertSessionId(id) {
+  if (typeof id !== 'string' || !SESSION_ID_PATTERN.test(id)) {
+    throw new ValidationError(
+      'Invalid session_id: must match pattern [a-zA-Z0-9_-]+',
+      { details: { value: id } }
+    );
+  }
+}
+
+/**
+ * @param {string|string[]} value
+ * @param {string[]|Record<string, *>} allowlist
+ * @param {string} label
+ * @throws {ValidationError}
+ */
+function assertAllowlisted(value, allowlist, label) {
+  const entries = Array.isArray(value) ? value : [value];
+  const permitted = Array.isArray(allowlist) ? allowlist : Object.keys(allowlist);
+  const invalid = entries.filter((entry) => !permitted.includes(entry));
+
+  if (invalid.length > 0) {
+    throw new ValidationError(
+      `Unknown ${label}: ${invalid.map((v) => `"${v}"`).join(', ')}. Known identifiers: ${permitted.join(', ')}`,
+      { details: { invalid, permitted, label } }
+    );
+  }
+}
+
+/**
+ * @param {string} p
+ * @throws {ValidationError}
+ */
+function assertRelativePath(p) {
+  if (typeof p !== 'string') {
+    throw new ValidationError('Path must be a string', {
+      details: { value: p },
+    });
+  }
+
+  if (p.includes('\0')) {
+    throw new ValidationError('Path contains null bytes', {
+      details: { value: p },
+    });
+  }
+
+  if (path.isAbsolute(p)) {
+    throw new ValidationError('Path must be relative', {
+      details: { value: p },
+    });
+  }
+
+  const segments = p.split(/[/\\]/);
+  if (segments.includes('..')) {
+    throw new ValidationError('Path traversal not allowed', {
+      details: { value: p },
+    });
+  }
+}
+
+/**
+ * @param {string} p
+ * @param {string} base
+ * @throws {ValidationError}
+ */
+function assertContainedIn(p, base) {
+  let resolved = path.resolve(p);
+  let resolvedBase = path.resolve(base);
+
+  try { resolved = fs.realpathSync(resolved); } catch {}
+  try { resolvedBase = fs.realpathSync(resolvedBase); } catch {}
+
+  const basePrefix = resolvedBase + path.sep;
+
+  if (!resolved.startsWith(basePrefix) && resolved !== resolvedBase) {
+    throw new ValidationError('Path escapes base directory', {
+      details: { path: resolved, base: resolvedBase },
+    });
+  }
+}
+
+/**
+ * @param {*} value
+ * @returns {*}
+ */
+function coercePositiveInteger(value) {
+  if (value == null || typeof value === 'number') return value;
+  if (typeof value !== 'string') return value;
+  const num = Number(value);
+  return Number.isFinite(num) && Number.isInteger(num) && num > 0 ? num : value;
+}
+
+module.exports = {
+  assertNonEmptyArray,
+  assertSessionId,
+  assertAllowlisted,
+  assertRelativePath,
+  assertContainedIn,
+  coercePositiveInteger,
+};

package/claude/src/lib/yaml-emit.js

@@ -0,0 +1,38 @@
+'use strict';
+
+/**
+ * Minimal YAML fragment emitters used by the generator.
+ *
+ * Neither function escapes its inputs — callers MUST pass YAML-safe
+ * scalars (identifiers, numbers, or pre-escaped strings). Values
+ * containing `:`, `"`, `\`, or leading/trailing whitespace will
+ * produce invalid YAML.
+ *
+ * Current callers (entry-point-expander, preamble-builders) pass
+ * agent names, skill names, and reference names — all controlled
+ * inputs from the canonical source tree — so the raw interpolation
+ * is safe in practice.
+ */
+
+/**
+ * Emit a block-style list under `key`. Returns [] when the list is
+ * empty so callers can append without producing an orphaned `key:`
+ * line.
+ */
+function emitBlockList(key, items) {
+  if (!items || items.length === 0) return [];
+  return [`${key}:`, ...items.map((item) => `  - ${item}`)];
+}
+
+/**
+ * Emit an inline comma-separated list of double-quoted scalars.
+ * Intended for embedding inside flow-style arrays like `[...]`.
+ */
+function emitInlineQuotedList(items) {
+  return items.map((item) => `"${item}"`).join(', ');
+}
+
+module.exports = {
+  emitBlockList,
+  emitInlineQuotedList,
+};

package/claude/src/mcp/content/provider.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const { resolveCanonicalSrcFromExtensionRoot } = require('../utils/extension-root');
+const {
+  readResourceFromFilesystem,
+  readAgentFromFilesystem,
+} = require('./runtime-content');
+
+const CONTENT_SOURCES = Object.freeze({
+  FILESYSTEM: 'filesystem',
+  NONE: 'none',
+});
+
+function createFilesystemProvider(runtimeConfig, canonicalSrcRoot = resolveCanonicalSrcFromExtensionRoot()) {
+  const srcRoot = canonicalSrcRoot;
+
+  return {
+    readResource(id) {
+      return readResourceFromFilesystem(id, runtimeConfig, srcRoot);
+    },
+
+    readAgent(agentName) {
+      return readAgentFromFilesystem(agentName, runtimeConfig, srcRoot);
+    },
+  };
+}
+
+function normalizeContentPolicy(runtimeConfig) {
+  const content = runtimeConfig && runtimeConfig.content;
+
+  return {
+    primary: content && content.primary ? content.primary : CONTENT_SOURCES.FILESYSTEM,
+    fallback: content && content.fallback ? content.fallback : CONTENT_SOURCES.NONE,
+  };
+}
+
+/**
+ * Every runtime configures `primary=filesystem, fallback=none`, so the
+ * chain collapses to the filesystem provider with a shaped error for
+ * `none`. If a future source is introduced, reintroduce chaining here.
+ */
+function createContentProvider(runtimeConfig, canonicalSrcRoot = resolveCanonicalSrcFromExtensionRoot()) {
+  const { primary } = normalizeContentPolicy(runtimeConfig);
+
+  if (primary === CONTENT_SOURCES.NONE) {
+    return {
+      readResource(id) {
+        return { error: `No content provider could read resource "${id}"` };
+      },
+      readAgent(agentName) {
+        return { error: `No content provider could read agent "${agentName}"` };
+      },
+    };
+  }
+
+  if (primary !== CONTENT_SOURCES.FILESYSTEM) {
+    throw new Error(`Unknown content source: "${primary}"`);
+  }
+
+  return createFilesystemProvider(runtimeConfig, canonicalSrcRoot);
+}
+
+module.exports = {
+  CONTENT_SOURCES,
+  createContentProvider,
+  createFilesystemProvider,
+  normalizeContentPolicy,
+};