@josstei/maestro 1.6.4-rc.1

package/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/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/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/src/manifest.js

@@ -0,0 +1,11 @@
+module.exports = [
+  // ── Agent discovery stubs — Gemini, Claude, and Qwen ───────────────
+  { glob: 'agents/*.md',
+    transforms: ['parse-frontmatter', 'extract-examples', 'rebuild-frontmatter', 'agent-stub'],
+    runtimes: ['gemini', 'claude', 'qwen'] },
+
+  // ── Shared skill discovery stubs — Claude + Codex only ─────────────
+  { glob: 'skills/shared/**/SKILL.md',
+    transforms: ['skill-discovery-stub'],
+    runtimes: ['claude', 'codex'] },
+];

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

package/src/mcp/content/runtime-content.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatterOnly, splitAtBoundary } = require('../../lib/frontmatter');
+const { replaceInContent } = require('../../lib/naming');
+const { stripFeatureBlocks: stripFeatureBlocksCore } = require('../../core/feature-blocks');
+
+const agentRegistry = require('../../generated/agent-registry.json');
+
+const DEFAULT_RUNTIME_NAME = 'gemini';
+
+const RESOURCE_ALLOWLIST = Object.freeze(require('../../generated/resource-registry.json'));
+
+const AGENT_ALLOWLIST = Object.freeze(agentRegistry.map((entry) => entry.name));
+
+function applyReplacePaths(content, runtimeConfig) {
+  let result = content;
+  const env = runtimeConfig.env || {};
+
+  if (env.extensionPath) {
+    const replacement = env.extensionPath.startsWith('${')
+      ? env.extensionPath
+      : '${' + env.extensionPath + '}';
+    result = result.replace(/\$\{extensionPath\}/g, replacement);
+  }
+
+  if (env.workspacePath) {
+    result = result.replace(/\$\{workspacePath\}/g, '${' + env.workspacePath + '}');
+  }
+
+  return result;
+}
+
+function applySkillMetadata(content, runtimeConfig, resourcePath) {
+  if (runtimeConfig.name !== 'claude' || !resourcePath.endsWith('SKILL.md')) {
+    return content;
+  }
+
+  return content.replace(
+    /^(---\n[\s\S]*?)(^---)/m,
+    '$1user-invocable: false\n$2'
+  );
+}
+
+function applyReplaceAgentNames(content, runtimeConfig) {
+  return replaceInContent(
+    content,
+    AGENT_ALLOWLIST.filter((n) => n.includes('-')),
+    runtimeConfig.agentNaming
+  );
+}
+
+function applyStripFeature(content, runtimeConfig) {
+  return stripFeatureBlocksCore(content, runtimeConfig.features || {});
+}
+
+const AGENT_NAME_RESOURCES = new Set([
+  'references/architecture.md',
+  'skills/shared/delegation/SKILL.md',
+  'skills/shared/execution/SKILL.md',
+  'skills/shared/validation/SKILL.md',
+  'skills/shared/code-review/SKILL.md',
+]);
+
+function applyRuntimeTransforms(content, runtimeConfig, resourcePath) {
+  let result = content;
+
+  if (resourcePath === 'references/architecture.md') {
+    result = applyStripFeature(result, runtimeConfig);
+  }
+
+  if (AGENT_NAME_RESOURCES.has(resourcePath)) {
+    result = applyReplaceAgentNames(result, runtimeConfig);
+  }
+
+  result = applyReplacePaths(result, runtimeConfig);
+  result = applySkillMetadata(result, runtimeConfig, resourcePath);
+
+  return result;
+}
+
+function stripFrontmatter(content) {
+  const { raw, body } = splitAtBoundary(content);
+  if (!raw) {
+    return content;
+  }
+  return body;
+}
+
+function stripFeatureBlocks(content, runtimeConfig) {
+  return stripFeatureBlocksCore(content, runtimeConfig.features || {}, { mode: 'lenient' });
+}
+
+function parseInlineArray(raw) {
+  if (!raw || !raw.startsWith('[') || !raw.endsWith(']')) {
+    return [];
+  }
+
+  return raw
+    .slice(1, -1)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseFrontmatter(content) {
+  return parseFrontmatterOnly(content).frontmatter;
+}
+
+function mapTools(frontmatter, runtimeConfig) {
+  const runtimeName = runtimeConfig.name || DEFAULT_RUNTIME_NAME;
+  const overrideKey = `tools.${runtimeName}`;
+  const configuredTools = frontmatter[overrideKey]
+    ? parseInlineArray(frontmatter[overrideKey])
+    : parseInlineArray(frontmatter.tools);
+
+  return configuredTools.flatMap((toolName) => {
+    const mapped = runtimeConfig.tools && runtimeConfig.tools[toolName];
+    if (Array.isArray(mapped)) {
+      return mapped;
+    }
+    return mapped || toolName;
+  });
+}
+
+function readResourceFromFilesystem(id, runtimeConfig, srcRoot) {
+  const relativePath = RESOURCE_ALLOWLIST[id];
+  if (!relativePath) {
+    return {
+      error: `Unknown resource identifier: "${id}". Known identifiers: ${Object.keys(RESOURCE_ALLOWLIST).join(', ')}`,
+    };
+  }
+
+  const absolutePath = path.join(srcRoot, relativePath);
+  try {
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    return {
+      content: applyRuntimeTransforms(content, runtimeConfig, relativePath),
+    };
+  } catch (err) {
+    return {
+      error: `Failed to read resource "${id}": ${err.code || 'UNKNOWN'}`,
+    };
+  }
+}
+
+function readAgentFromFilesystem(agentName, runtimeConfig, srcRoot) {
+  if (!AGENT_ALLOWLIST.includes(agentName)) {
+    return {
+      error: `Unknown agent identifier: "${agentName}". Known identifiers: ${AGENT_ALLOWLIST.join(', ')}`,
+    };
+  }
+
+  const absolutePath = path.join(srcRoot, 'agents', `${agentName}.md`);
+  try {
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    const frontmatter = parseFrontmatter(content);
+    return {
+      agent: {
+        body: stripFrontmatter(stripFeatureBlocks(content, runtimeConfig)),
+        tools: mapTools(frontmatter, runtimeConfig),
+      },
+    };
+  } catch (err) {
+    return {
+      error: `Failed to read agent "${agentName}": ${err.code || 'UNKNOWN'}`,
+    };
+  }
+}
+
+module.exports = {
+  DEFAULT_RUNTIME_NAME,
+  RESOURCE_ALLOWLIST,
+  AGENT_ALLOWLIST,
+  applyReplacePaths,
+  applySkillMetadata,
+  applyReplaceAgentNames,
+  applyStripFeature,
+  applyRuntimeTransforms,
+  stripFrontmatter,
+  stripFeatureBlocks,
+  parseInlineArray,
+  parseFrontmatter,
+  mapTools,
+  readResourceFromFilesystem,
+  readAgentFromFilesystem,
+};

package/src/mcp/contracts/cache-path-rejector.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const path = require('node:path');
+
+const CACHE_PATH_SEGMENTS = [
+  path.join('.codex', 'plugins'),
+  path.join('.claude', 'plugins'),
+  path.join('.gemini', 'extensions'),
+];
+
+function segmentWindows(segments, size) {
+  const windows = [];
+  for (let i = 0; i <= segments.length - size; i += 1) {
+    windows.push(segments.slice(i, i + size).join(path.sep));
+  }
+  return windows;
+}
+
+/**
+ * Returns true when the given path falls inside a host extension cache directory.
+ * Matches on contiguous two-segment windows so that substring-only matches
+ * (e.g. `.codex-plugins-research`) are correctly distinguished from genuine cache directories and not misclassified as cache paths.
+ *
+ * @param {string} candidate - Filesystem path. Absolute paths are used as-is; relative paths are resolved against process.cwd(), so callers should pass absolute paths for deterministic behavior.
+ * @returns {boolean}
+ */
+function isExtensionCachePath(candidate) {
+  if (typeof candidate !== 'string' || candidate.length === 0) {
+    return false;
+  }
+  const segments = path
+    .resolve(candidate)
+    .split(path.sep)
+    .filter((segment) => segment.length > 0);
+  const windows = segmentWindows(segments, 2);
+  return CACHE_PATH_SEGMENTS.some((cacheSegment) => windows.includes(cacheSegment));
+}
+
+module.exports = { CACHE_PATH_SEGMENTS, isExtensionCachePath };

package/src/mcp/contracts/downstream-context.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Canonical downstream-context contract.
+ *
+ * The handoff between orchestrator and child agents is documented (in
+ * agent-base-protocol) as a five-field structure. Agents may emit each field as
+ * either a string (`"none"`, `"X uses Y"`) or an array of strings. The canonical
+ * storage shape is an array of strings; normalization here is the single source
+ * of truth used by every handler that reads, writes, or validates the context.
+ *
+ * Strings and the tokens `"none"` / `"n/a"` / empty strings are all treated as
+ * absent so agent protocol examples like `"or none"` don't produce phantom
+ * entries in session state.
+ */
+
+const CANONICAL_FIELDS = Object.freeze([
+  'key_interfaces_introduced',
+  'patterns_established',
+  'integration_points',
+  'assumptions',
+  'warnings',
+]);
+
+const EMPTY_VALUE_TOKENS = new Set(['', 'none', 'n/a', 'not applicable']);
+
+function isEmptyValueToken(value) {
+  return EMPTY_VALUE_TOKENS.has(String(value).trim().toLowerCase());
+}
+
+function normalizeFieldValue(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) {
+    return value
+      .filter((item) => typeof item === 'string')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0 && !isEmptyValueToken(item));
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || isEmptyValueToken(trimmed)) return [];
+    return [trimmed];
+  }
+  return [];
+}
+
+/**
+ * @returns {Object<string, string[]>} a fresh empty canonical context.
+ */
+function createEmptyDownstreamContext() {
+  const empty = {};
+  for (const field of CANONICAL_FIELDS) {
+    empty[field] = [];
+  }
+  return empty;
+}
+
+/**
+ * Normalize any input to the canonical `{ field: string[] }` shape.
+ * Accepts null, arrays-of-strings, strings, and unknown keys are dropped.
+ *
+ * @param {unknown} input
+ * @returns {Object<string, string[]>}
+ */
+function normalizeDownstreamContext(input) {
+  const normalized = createEmptyDownstreamContext();
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return normalized;
+  }
+  for (const field of CANONICAL_FIELDS) {
+    normalized[field] = normalizeFieldValue(input[field]);
+  }
+  return normalized;
+}
+
+/**
+ * True when the normalized context has at least one non-empty field.
+ * @param {unknown} input
+ * @returns {boolean}
+ */
+function isDownstreamContextPopulated(input) {
+  const normalized = normalizeDownstreamContext(input);
+  return CANONICAL_FIELDS.some((field) => normalized[field].length > 0);
+}
+
+/**
+ * Human-readable description of the contract, suitable for embedding in error
+ * messages so callers can adapt without reading source.
+ * @returns {string}
+ */
+function describeShape() {
+  return (
+    'downstream_context must contain at least one of: ' +
+    CANONICAL_FIELDS.join(', ') +
+    '. Each field accepts a non-empty string or a non-empty array of strings. ' +
+    'Empty strings and the tokens "none" / "n/a" / "not applicable" are treated as absent.'
+  );
+}
+
+module.exports = {
+  CANONICAL_FIELDS,
+  createEmptyDownstreamContext,
+  normalizeDownstreamContext,
+  isDownstreamContextPopulated,
+  describeShape,
+};