@caoscompanybr/merlin 3.5.0

package/.merlin-core/core/config/env-interpolator.js

@@ -0,0 +1,123 @@
+/**
+ * Environment Variable Interpolator
+ *
+ * Resolves ${ENV_VAR} and ${ENV_VAR:-default} patterns in configuration values.
+ * Applied at load time after merge.
+ *
+ * Rules:
+ * - ${VAR}: resolves to process.env.VAR; warns if missing, returns ''
+ * - ${VAR:-default}: resolves to process.env.VAR or 'default' if unset
+ * - Recursive: walks nested objects and arrays
+ * - L0/L1 linting: lintEnvPatterns() flags ${...} in committed config files
+ *
+ * @module core/config/env-interpolator
+ * @version 3.0.0
+ */
+
+const { isPlainObject } = require("./merge-utils");
+
+/**
+ * Regex for ${ENV_VAR} and ${ENV_VAR:-default_value}
+ * Captures: group 1 = var name, group 2 = default value (optional, after :-)
+ */
+const ENV_VAR_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-(.*?))?\}/g;
+
+/**
+ * Interpolate environment variables in a string value.
+ *
+ * @param {string} value - String potentially containing ${VAR} patterns
+ * @param {Object} options - Options
+ * @param {string[]} options.warnings - Array to collect warning messages
+ * @returns {string} Interpolated string
+ */
+function interpolateString(value, options = {}) {
+  const warnings = options.warnings || [];
+
+  return value.replace(ENV_VAR_PATTERN, (match, varName, defaultValue) => {
+    const envValue = process.env[varName];
+
+    if (envValue !== undefined) {
+      return envValue;
+    }
+
+    if (defaultValue !== undefined) {
+      return defaultValue;
+    }
+
+    // Missing required env var (no default)
+    warnings.push(`Missing environment variable: ${varName} (no default set)`);
+    return "";
+  });
+}
+
+/**
+ * Recursively interpolate environment variables in a config object.
+ *
+ * @param {*} config - Configuration value (object, array, or scalar)
+ * @param {Object} options - Options
+ * @param {string[]} options.warnings - Array to collect warning messages
+ * @returns {*} Interpolated configuration
+ */
+function interpolateEnvVars(config, options = {}) {
+  const warnings = options.warnings || [];
+
+  if (typeof config === "string") {
+    return interpolateString(config, { warnings });
+  }
+
+  if (Array.isArray(config)) {
+    return config.map((item) => interpolateEnvVars(item, { warnings }));
+  }
+
+  if (isPlainObject(config)) {
+    const result = {};
+    for (const [key, value] of Object.entries(config)) {
+      result[key] = interpolateEnvVars(value, { warnings });
+    }
+    return result;
+  }
+
+  // Numbers, booleans, null -- return as-is
+  return config;
+}
+
+/**
+ * Check a config object for ${...} patterns that probably shouldn't be
+ * in committed files (L0/L1). Returns an array of findings.
+ *
+ * @param {Object} config - Configuration to lint
+ * @param {string} sourceFile - File name for reporting
+ * @returns {string[]} Array of warning strings
+ */
+function lintEnvPatterns(config, sourceFile) {
+  const findings = [];
+
+  function walk(obj, keyPath) {
+    // C5 fix: Reset lastIndex BEFORE test() to avoid stale state from global regex
+    ENV_VAR_PATTERN.lastIndex = 0;
+    if (typeof obj === "string" && ENV_VAR_PATTERN.test(obj)) {
+      ENV_VAR_PATTERN.lastIndex = 0;
+      findings.push(
+        `${sourceFile}: ${keyPath} contains env variable pattern: ${obj}`,
+      );
+    } else if (isPlainObject(obj)) {
+      for (const [key, value] of Object.entries(obj)) {
+        walk(value, keyPath ? `${keyPath}.${key}` : key);
+      }
+    } else if (Array.isArray(obj)) {
+      obj.forEach((item, i) => {
+        walk(item, `${keyPath}[${i}]`);
+      });
+    }
+  }
+
+  walk(config, "");
+  return findings;
+}
+
+module.exports = {
+  interpolateEnvVars,
+  interpolateString,
+  lintEnvPatterns,
+  ENV_VAR_PATTERN,
+};

package/.merlin-core/core/config/merge-utils.js

@@ -0,0 +1,102 @@
+/**
+ * Merge Utilities for Layered Configuration
+ *
+ * Implements the merge strategy for Merlin's 4-level config hierarchy:
+ *   L0 Core -> L1 Framework -> L2 Project -> L3 Local
+ *
+ * Rules:
+ * - Scalars: last-wins
+ * - Objects: deep merge
+ * - Arrays: replace (default)
+ * - Arrays with +append: concatenate
+ * - null values: delete key
+ *
+ * @module core/config/merge-utils
+ * @version 3.0.0
+ */
+
+/**
+ * Check if value is a plain object (not array, null, Date, etc.)
+ *
+ * @param {*} value - Value to check
+ * @returns {boolean} True if plain object
+ */
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return false;
+
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep merge two configuration objects.
+ *
+ * Merge strategy:
+ * - Scalars (string, number, boolean): last-wins (source overrides target)
+ * - Objects/Maps: recursive deep merge
+ * - Arrays (default): replace (source replaces target)
+ * - Arrays with +append suffix: concatenate source onto target
+ * - null values: delete the key from result
+ *
+ * @param {Object} target - Base configuration (lower priority)
+ * @param {Object} source - Override configuration (higher priority)
+ * @returns {Object} Merged configuration (new object, inputs unchanged)
+ */
+function deepMerge(target, source) {
+  if (!isPlainObject(target) || !isPlainObject(source)) {
+    return source !== undefined ? source : target;
+  }
+
+  const result = { ...target };
+
+  for (const [key, value] of Object.entries(source)) {
+    // Handle +append modifier for arrays
+    if (key.endsWith("+append")) {
+      const baseKey = key.slice(0, -7); // Remove '+append'
+      if (Array.isArray(value)) {
+        const existing = result[baseKey];
+        result[baseKey] = Array.isArray(existing)
+          ? [...existing, ...value]
+          : value;
+      }
+      continue;
+    }
+
+    // Handle null = delete key
+    if (value === null) {
+      delete result[key];
+      continue;
+    }
+
+    // Deep merge plain objects
+    if (isPlainObject(value) && isPlainObject(result[key])) {
+      result[key] = deepMerge(result[key], value);
+      continue;
+    }
+
+    // Arrays and scalars: replace (last-wins)
+    result[key] = value;
+  }
+
+  return result;
+}
+
+/**
+ * Merge multiple config layers in order (left to right, last wins).
+ *
+ * @param {...Object} layers - Configuration layers in priority order (lowest first)
+ * @returns {Object} Merged configuration
+ */
+function mergeAll(...layers) {
+  return layers.reduce((result, layer) => {
+    if (!layer || !isPlainObject(layer)) return result;
+    return deepMerge(result, layer);
+  }, {});
+}
+
+module.exports = {
+  deepMerge,
+  mergeAll,
+  isPlainObject,
+};

package/.merlin-core/core/config/schemas/core-config.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "core-config.schema.json",
+  "title": "Merlin Core Configuration (L0)",
+  "description": "Read-only core constants. Never modified at runtime.",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "object",
+      "properties": {
+        "type": { "type": "string" },
+        "version": { "type": "string" }
+      }
+    },
+    "user_profile": { "type": "string" },
+    "qa": { "type": "object" },
+    "prd": { "type": "object" },
+    "architecture": { "type": "object" },
+    "devLoadAlwaysFiles": { "type": "array", "items": { "type": "string" } },
+    "devDebugLog": { "type": "string" },
+    "devStoryLocation": { "type": "string" },
+    "slashPrefix": { "type": "string" },
+    "toolsLocation": { "type": "string" },
+    "commandsLocation": { "type": "string" },
+    "skillsLocation": { "type": "string" },
+    "thoughtsLocation": { "type": "string" },
+    "ide": { "type": "object" },
+    "mcp": { "type": "object" },
+    "lazyLoading": { "type": "object" },
+    "git": { "type": "object" },
+    "decisionLogging": { "type": "object" },
+    "projectStatus": { "type": "object" },
+    "agentIdentity": { "type": "object" },
+    "github": { "type": "object" },
+    "storyBacklog": { "type": "object" },
+    "ideSync": { "type": "object" },
+    "approval": { "type": "object" },
+    "skills": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/.merlin-core/core/config/schemas/framework-config.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "framework-config.schema.json",
+  "title": "Merlin Framework Configuration (L1)",
+  "description": "Framework defaults shipped with the package. Customizable per-project in L2.",
+  "type": "object",
+  "properties": {
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "level": { "type": "string" },
+        "description": { "type": "string" },
+        "mutability": { "type": "string" }
+      }
+    },
+    "resource_locations": { "type": "object" },
+    "performance_defaults": { "type": "object" },
+    "utility_scripts_registry": { "type": "object" },
+    "alkimia": { "type": "object" },
+    "context_brackets": { "type": "object" },
+    "quality_gates": { "type": "object" }
+  },
+  "additionalProperties": true
+}

package/.merlin-core/core/config/schemas/local-config.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "local-config.schema.json",
+  "title": "Merlin Local Configuration (L3)",
+  "description": "Machine-specific settings stored in .merlin-core/local-config.yaml (gitignored)",
+  "type": "object",
+  "properties": {
+    "user_profile": { "type": "string" },
+    "mcp": {
+      "type": "object",
+      "description": "MCP server local overrides"
+    },
+    "approval": {
+      "type": "object",
+      "description": "Approval channel overrides"
+    },
+    "ide": {
+      "type": "object",
+      "description": "IDE-specific overrides"
+    }
+  },
+  "additionalProperties": true
+}

package/.merlin-core/core/config/schemas/project-config.schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "project-config.schema.json",
+  "title": "Merlin Project Configuration (L2)",
+  "description": "Team-shared project settings stored in .merlin-core/project-config.yaml",
+  "type": "object",
+  "properties": {
+    "project": {
+      "type": "object",
+      "properties": {
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": ["fullstack", "api", "frontend", "library", "cli", "monorepo"]
+        },
+        "repository": { "type": "string" }
+      }
+    },
+    "team": { "type": "object" },
+    "agents": { "type": "object" },
+    "workflows": { "type": "object" },
+    "mcp_servers": { "type": "object" },
+    "approval": { "type": "object" },
+    "operations": {
+      "type": "object",
+      "description": "Project-specific operational instructions for commit, build, deploy, CI/CD, and publish workflows. Read by agents (Dex for git/build, Gage for deploy/ci/publish) to execute project-aware operations.",
+      "properties": {
+        "git": {
+          "type": "object",
+          "description": "Git workflow and commit conventions. Read by Dex (dev) and /commit command.",
+          "properties": {
+            "branch_strategy": {
+              "type": "string",
+              "enum": ["gitflow", "trunk", "github-flow", "custom"],
+              "description": "Branching model used by the project"
+            },
+            "main_branch": {
+              "type": "string",
+              "default": "main",
+              "description": "Name of the primary branch (main, master, develop, etc.)"
+            },
+            "protected_branches": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Branches that require PR review before merge"
+            },
+            "commit_convention": {
+              "type": "string",
+              "enum": ["conventional", "jira", "plain", "custom"],
+              "description": "Commit message format convention"
+            },
+            "commit_prefix": {
+              "type": "string",
+              "description": "Prefix for commit messages (e.g., 'PROJ-' for Jira ticket IDs)"
+            },
+            "pre_commit_hooks": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "What runs on commit (lint, test, typecheck, etc.)"
+            }
+          }
+        },
+        "build": {
+          "type": "object",
+          "description": "Build configuration. Read by Dex (dev) during implementation.",
+          "properties": {
+            "command": {
+              "type": "string",
+              "description": "Build command (e.g., 'npm run build', 'cargo build --release')"
+            },
+            "output_dir": {
+              "type": "string",
+              "description": "Build output directory (e.g., 'dist/', 'build/', '.next/')"
+            },
+            "env_file": {
+              "type": "string",
+              "description": "Environment file for production builds (e.g., '.env.production')"
+            },
+            "pre_build": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Commands to run before build (e.g., 'npm install', 'prisma generate')"
+            }
+          }
+        },
+        "deploy": {
+          "type": "array",
+          "description": "Deploy targets. A project can have multiple (staging, production, VPS). Read by Gage (devops).",
+          "items": {
+            "type": "object",
+            "required": ["name", "platform"],
+            "properties": {
+              "name": {
+                "type": "string",
+                "description": "Deploy target name (e.g., 'production', 'staging', 'vps-primary')"
+              },
+              "platform": {
+                "type": "string",
+                "enum": [
+                  "firebase", "vercel", "netlify", "cloudflare",
+                  "vps", "docker", "azure", "aws", "manual", "none"
+                ],
+                "description": "Hosting platform. Determines which external skill to reference."
+              },
+              "command": {
+                "type": "string",
+                "description": "Deploy command (e.g., 'firebase deploy --only hosting')"
+              },
+              "url": {
+                "type": "string",
+                "description": "Production/staging URL after deploy"
+              },
+              "approval": {
+                "type": "string",
+                "enum": ["LOW", "MEDIUM", "HIGH"],
+                "default": "HIGH",
+                "description": "Approval level required. HIGH = explicit human approval, MEDIUM = YOLO-able"
+              },
+              "env_vars_location": {
+                "type": "string",
+                "description": "Where env vars are configured (e.g., 'Firebase Console > Project Settings')"
+              },
+              "vps": {
+                "type": "object",
+                "description": "VPS-specific config. Only used when platform is 'vps'.",
+                "properties": {
+                  "host": { "type": "string", "description": "VPS hostname or IP" },
+                  "user": { "type": "string", "description": "SSH user" },
+                  "port": { "type": "integer", "default": 22, "description": "SSH port" },
+                  "deploy_path": { "type": "string", "description": "Remote path to the project" },
+                  "deploy_steps": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Ordered commands to run on the VPS after SSH connect"
+                  },
+                  "rollback": {
+                    "type": "string",
+                    "description": "Command to rollback a failed deploy"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "ci": {
+          "type": "object",
+          "description": "CI/CD pipeline configuration. Read by Gage (devops).",
+          "properties": {
+            "provider": {
+              "type": "string",
+              "enum": ["github-actions", "gitlab-ci", "azure-pipelines", "circleci", "none"],
+              "description": "CI/CD provider"
+            },
+            "config_file": {
+              "type": "string",
+              "description": "Path to CI config (e.g., '.github/workflows/deploy.yml')"
+            },
+            "pipeline_url": {
+              "type": "string",
+              "description": "URL to the CI/CD pipeline dashboard"
+            }
+          }
+        },
+        "publish": {
+          "type": "object",
+          "description": "Package/extension publishing config. Read by Gage (devops).",
+          "properties": {
+            "platform": {
+              "type": "string",
+              "enum": ["npm", "pypi", "cargo", "chrome-web-store", "play-store", "app-store", "none"],
+              "description": "Publishing platform"
+            },
+            "command": {
+              "type": "string",
+              "description": "Publish command (e.g., 'npm publish', 'cargo publish')"
+            },
+            "pre_publish": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Commands to run before publish (e.g., 'npm run build', 'npm test')"
+            }
+          }
+        }
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/.merlin-core/core/docs-consistency.js

@@ -0,0 +1,140 @@
+/**
+ * docs-consistency.js — release-file consistency helpers.
+ *
+ * Reads the real release files + counts the real on-disk artifacts so the
+ * doc-consistency test (docs-consistency.test.js) can assert that declared
+ * version strings and counts never drift from reality. No expected values are
+ * hardcoded here — everything is read from disk, so it stays correct as the
+ * framework grows. Born from the v3.1.0 count-drift cleanup (2026-06-01).
+ */
+const fs = require("fs");
+const path = require("path");
+
+/** Repo root, resolved from this file's location (.merlin-core/core/). */
+function getRepoRoot() {
+  return path.resolve(__dirname, "..", "..");
+}
+
+function read(root, rel) {
+  return fs.readFileSync(path.join(root, rel), "utf8");
+}
+
+function extract(text, regex, idx = 1) {
+  const m = text.match(regex);
+  return m ? m[idx] : null;
+}
+
+/** The framework version string as declared in each canonical release file. */
+function declaredVersions(root) {
+  return {
+    "framework-config.yaml": extract(
+      read(root, ".merlin-core/framework-config.yaml"),
+      /framework_version:\s*"([^"]+)"/,
+    ),
+    "project-config.yaml": extract(
+      read(root, ".merlin-core/project-config.yaml"),
+      /\n\s*version:\s*"([^"]+)"/,
+    ),
+    "constitution.md": extract(
+      read(root, ".merlin-core/constitution.md"),
+      /\*\*Version:\*\*\s*([0-9.]+)/,
+    ),
+    "CLAUDE.md": extract(
+      read(root, ".claude/CLAUDE.md"),
+      /Orchestration Framework \| v([0-9.]+)/,
+    ),
+    "README.md": extract(read(root, "README.md"), /badge\/version-([0-9.]+)-/),
+  };
+}
+
+function countSkillDirs(root, sub) {
+  const base = path.join(root, ".merlin-core", "skills", sub);
+  if (!fs.existsSync(base)) return 0;
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter(
+      (d) =>
+        d.isDirectory() && fs.existsSync(path.join(base, d.name, "SKILL.md")),
+    ).length;
+}
+
+/** On-disk skill counts: { general, domain, total }. */
+function diskSkillCounts(root) {
+  const general = countSkillDirs(root, "general");
+  const domain = countSkillDirs(root, "domain");
+  return { general, domain, total: general + domain };
+}
+
+/** Skill counts as declared in docs, one entry per source. */
+function declaredSkillCounts(root) {
+  const out = [];
+  const readme = read(root, "README.md");
+  const badge = extract(readme, /badge\/skills-(\d+)-/);
+  if (badge) out.push({ source: "README badge", total: Number(badge) });
+  const prose = readme.match(
+    /(\d+) auto-activating skills\*\* \((\d+) built-in \+ (\d+) domain\)/,
+  );
+  if (prose)
+    out.push({
+      source: "README prose",
+      total: Number(prose[1]),
+      general: Number(prose[2]),
+      domain: Number(prose[3]),
+    });
+  const claude = read(root, ".claude/CLAUDE.md");
+  const cm = claude.match(
+    /(\d+) built-in \+ (\d+) domain skills \((\d+) total\)/,
+  );
+  if (cm)
+    out.push({
+      source: "CLAUDE.md",
+      general: Number(cm[1]),
+      domain: Number(cm[2]),
+      total: Number(cm[3]),
+    });
+  return out;
+}
+
+/** Count .md files in a directory (optionally recursive), excluding README.md. */
+function countMarkdown(dir, recursive) {
+  if (!fs.existsSync(dir)) return 0;
+  let n = 0;
+  for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (e.isDirectory()) {
+      if (recursive) n += countMarkdown(path.join(dir, e.name), recursive);
+    } else if (e.name.endsWith(".md") && e.name !== "README.md") {
+      n++;
+    }
+  }
+  return n;
+}
+
+function diskAgentCount(root) {
+  return countMarkdown(
+    path.join(root, ".merlin-core", "development", "agents"),
+    false,
+  );
+}
+
+function diskCommandCount(root) {
+  return countMarkdown(path.join(root, ".merlin-core", "commands"), true);
+}
+
+function declaredAgentCount(root) {
+  return Number(extract(read(root, "README.md"), /badge\/agents-(\d+)-/));
+}
+
+function declaredCommandCount(root) {
+  return Number(extract(read(root, "README.md"), /badge\/commands-(\d+)-/));
+}
+
+module.exports = {
+  getRepoRoot,
+  declaredVersions,
+  diskSkillCounts,
+  declaredSkillCounts,
+  diskAgentCount,
+  diskCommandCount,
+  declaredAgentCount,
+  declaredCommandCount,
+};