@geraldmaron/construct 1.0.0 → 1.0.1

package/lib/plugin-registry.mjs

@@ -0,0 +1,268 @@
+/**
+ * lib/plugin-registry.mjs — load and validate Construct plugin manifests.
+ *
+ * Built-in integrations and external manifests share one registry so new
+ * integrations can plug into Construct without editing core source files.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const MANIFEST_VERSION = 1;
+
+function readJson(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function normalizeMcp(mcp, plugin) {
+  return {
+    ...mcp,
+    pluginId: plugin.id,
+    pluginName: plugin.name,
+    aliases: Array.isArray(mcp.aliases) ? mcp.aliases : [],
+    args: Array.isArray(mcp.args) ? mcp.args : [],
+    env: isPlainObject(mcp.env) ? mcp.env : {},
+    headers: isPlainObject(mcp.headers) ? mcp.headers : {},
+    requiredEnv: Array.isArray(mcp.requiredEnv) ? mcp.requiredEnv : [],
+    setupModes: Array.isArray(mcp.setupModes) ? mcp.setupModes : ["manual"],
+    usedBy: Array.isArray(mcp.usedBy) ? mcp.usedBy : [],
+    hostSupport: isPlainObject(mcp.hostSupport) ? mcp.hostSupport : {},
+  };
+}
+
+function validateMcp(mcp, { pluginId, manifestPath }) {
+  const errors = [];
+  const label = `${pluginId}:${mcp?.id ?? "(missing-id)"}`;
+  if (!isPlainObject(mcp)) {
+    return [`${manifestPath}: MCP entry must be an object (${label})`];
+  }
+  if (!mcp.id || typeof mcp.id !== "string") errors.push(`${manifestPath}: MCP entry missing string id (${label})`);
+  if (!mcp.name || typeof mcp.name !== "string") errors.push(`${manifestPath}: MCP entry missing string name (${label})`);
+  if (!mcp.category || typeof mcp.category !== "string") errors.push(`${manifestPath}: MCP entry missing string category (${label})`);
+  if (!mcp.description || typeof mcp.description !== "string") errors.push(`${manifestPath}: MCP entry missing string description (${label})`);
+  if (!Array.isArray(mcp.requiredEnv)) errors.push(`${manifestPath}: MCP ${label} missing requiredEnv array`);
+  if (!Array.isArray(mcp.usedBy)) errors.push(`${manifestPath}: MCP ${label} missing usedBy array`);
+  if (!isPlainObject(mcp.env)) errors.push(`${manifestPath}: MCP ${label} missing env object`);
+  if (mcp.headers !== undefined && !isPlainObject(mcp.headers)) errors.push(`${manifestPath}: MCP ${label} headers must be an object when present`);
+  if (mcp.type === "url" && typeof mcp.url !== "string") errors.push(`${manifestPath}: MCP ${label} with type=url must declare url`);
+  if (mcp.type !== "url" && typeof mcp.command !== "string") errors.push(`${manifestPath}: MCP ${label} must declare command unless type=url`);
+  return errors;
+}
+
+export function validatePluginManifest(manifest, { manifestPath = "<memory>" } = {}) {
+  const errors = [];
+  if (!isPlainObject(manifest)) {
+    return { valid: false, errors: [`${manifestPath}: manifest must be a JSON object`] };
+  }
+  if (manifest.version !== MANIFEST_VERSION) {
+    errors.push(`${manifestPath}: unsupported manifest version ${JSON.stringify(manifest.version)} (expected ${MANIFEST_VERSION})`);
+  }
+  if (!Array.isArray(manifest.plugins) || manifest.plugins.length === 0) {
+    errors.push(`${manifestPath}: manifest must contain a non-empty plugins array`);
+  }
+
+  const pluginIds = new Set();
+  for (const plugin of manifest.plugins ?? []) {
+    const pluginLabel = plugin?.id ?? "(missing-id)";
+    if (!isPlainObject(plugin)) {
+      errors.push(`${manifestPath}: plugin entry must be an object (${pluginLabel})`);
+      continue;
+    }
+    if (!plugin.id || typeof plugin.id !== "string") errors.push(`${manifestPath}: plugin missing string id`);
+    if (!plugin.name || typeof plugin.name !== "string") errors.push(`${manifestPath}: plugin ${pluginLabel} missing string name`);
+    if (!plugin.version || typeof plugin.version !== "string") errors.push(`${manifestPath}: plugin ${pluginLabel} missing string version`);
+    if (!plugin.description || typeof plugin.description !== "string") errors.push(`${manifestPath}: plugin ${pluginLabel} missing string description`);
+    if (plugin.capabilities !== undefined && !Array.isArray(plugin.capabilities)) {
+      errors.push(`${manifestPath}: plugin ${pluginLabel} capabilities must be an array when present`);
+    }
+    if (!Array.isArray(plugin.mcps)) errors.push(`${manifestPath}: plugin ${pluginLabel} missing mcps array`);
+    if (plugin.id) {
+      if (pluginIds.has(plugin.id)) errors.push(`${manifestPath}: duplicate plugin id ${plugin.id}`);
+      pluginIds.add(plugin.id);
+    }
+    for (const mcp of plugin.mcps ?? []) {
+      errors.push(...validateMcp(mcp, { pluginId: pluginLabel, manifestPath }));
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
+function loadBuiltinPlugin(rootDir) {
+  const rootCatalogPath = join(rootDir, "lib", "mcp-catalog.json");
+  const catalogPath = existsSync(rootCatalogPath) ? rootCatalogPath : join(__dirname, "mcp-catalog.json");
+  const catalog = readJson(catalogPath);
+  const plugin = {
+    id: "construct-builtins",
+    name: "Construct Built-ins",
+    version: "1.0.0",
+    description: "Built-in Construct integrations bundled with the CLI.",
+    capabilities: ["mcp"],
+    manifestPath: catalogPath,
+    builtIn: true,
+  };
+  plugin.mcps = (catalog.mcps ?? []).map((mcp) => ({
+    ...normalizeMcp(mcp, plugin),
+    manifestPath: catalogPath,
+  }));
+  return plugin;
+}
+
+export function resolvePluginDirs({ cwd = process.cwd(), homeDir = homedir(), env = process.env } = {}) {
+  const extra = String(env.CONSTRUCT_PLUGIN_DIRS || "")
+    .split(env.PATH?.includes(";") ? ";" : ":")
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return [...new Set([
+    join(cwd, ".cx", "plugins"),
+    join(cwd, ".construct", "plugins"),
+    join(homeDir, ".construct", "plugins"),
+    ...extra,
+  ].map((dir) => resolve(dir)))];
+}
+
+function findManifestFiles(pluginDirs) {
+  const files = [];
+  for (const dir of pluginDirs) {
+    if (!existsSync(dir)) continue;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      if (extname(entry.name).toLowerCase() !== ".json") continue;
+      files.push(join(dir, entry.name));
+    }
+  }
+  return files.sort();
+}
+
+export function loadPluginRegistry({ cwd = process.cwd(), homeDir = homedir(), rootDir = resolve(__dirname, ".."), env = process.env } = {}) {
+  const errors = [];
+  const plugins = [loadBuiltinPlugin(rootDir)];
+  const pluginDirs = resolvePluginDirs({ cwd, homeDir, env });
+
+  for (const manifestPath of findManifestFiles(pluginDirs)) {
+    try {
+      const manifest = readJson(manifestPath);
+      const validation = validatePluginManifest(manifest, { manifestPath });
+      if (!validation.valid) {
+        errors.push(...validation.errors);
+        continue;
+      }
+      for (const rawPlugin of manifest.plugins) {
+        const plugin = {
+          ...rawPlugin,
+          capabilities: Array.isArray(rawPlugin.capabilities) ? rawPlugin.capabilities : ["mcp"],
+          manifestPath,
+          builtIn: false,
+        };
+        plugin.mcps = (rawPlugin.mcps ?? []).map((mcp) => ({
+          ...normalizeMcp(mcp, plugin),
+          manifestPath,
+        }));
+        plugins.push(plugin);
+      }
+    } catch (error) {
+      errors.push(`${manifestPath}: failed to load manifest (${error.message})`);
+    }
+  }
+
+  const pluginIds = new Set();
+  const mcpIds = new Set();
+  const dedupedPlugins = [];
+  const mcps = [];
+
+  for (const plugin of plugins) {
+    if (pluginIds.has(plugin.id)) {
+      errors.push(`${plugin.manifestPath}: duplicate plugin id ${plugin.id}`);
+      continue;
+    }
+    pluginIds.add(plugin.id);
+    dedupedPlugins.push(plugin);
+    for (const mcp of plugin.mcps ?? []) {
+      if (mcpIds.has(mcp.id)) {
+        errors.push(`${mcp.manifestPath}: duplicate MCP id ${mcp.id}`);
+        continue;
+      }
+      mcpIds.add(mcp.id);
+      mcps.push(mcp);
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+    pluginDirs,
+    plugins: dedupedPlugins,
+    mcps,
+  };
+}
+
+export function getPluginById(id, options = {}) {
+  const registry = loadPluginRegistry(options);
+  return registry.plugins.find((plugin) => plugin.id === id) ?? null;
+}
+
+export function getMcpById(id, options = {}) {
+  const registry = loadPluginRegistry(options);
+  return registry.mcps.find((mcp) => mcp.id === id) ?? null;
+}
+
+export function initPluginManifest(id, {
+  cwd = process.cwd(),
+  force = false,
+  version = "0.1.0",
+  name = null,
+  description = "External Construct plugin.",
+} = {}) {
+  if (!id || typeof id !== "string" || !id.trim()) {
+    throw new Error("plugin id is required");
+  }
+  const safeId = id.trim();
+  const dir = join(cwd, ".cx", "plugins");
+  const filePath = join(dir, `${safeId}.json`);
+  if (existsSync(filePath) && !force) {
+    throw new Error(`plugin manifest already exists at ${filePath}`);
+  }
+
+  mkdirSync(dir, { recursive: true });
+  const manifest = {
+    version: MANIFEST_VERSION,
+    plugins: [
+      {
+        id: safeId,
+        name: name ?? safeId,
+        version,
+        description,
+        capabilities: ["mcp"],
+        mcps: [
+          {
+            id: `${safeId}-example`,
+            name: `${name ?? safeId} Example`,
+            category: "integration",
+            description: "Example MCP entry. Replace with your real integration.",
+            command: "npx",
+            args: ["-y", "@example/mcp-server"],
+            env: {},
+            requiredEnv: [],
+            setupModes: ["manual"],
+            hostSupport: {
+              claude: { mode: "managed" },
+              opencode: { mode: "managed" },
+              codex: { mode: "managed" },
+            },
+            usedBy: ["construct"],
+            degradedMessage: "Example integration unavailable.",
+          },
+        ],
+      },
+    ],
+  };
+  writeFileSync(filePath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+  return filePath;
+}

package/lib/policy/engine.mjs

@@ -0,0 +1,130 @@
+/**
+ * lib/policy/engine.mjs — role-based policy decisions for tool / action access.
+ *
+ * Reads role permissions from `agents/role-manifests.json` and decides
+ * whether a given (role, project, tool, action, risk) tuple is allowed,
+ * needs approval, or is denied outright. Powers the MCP broker for team
+ * and enterprise deployments; solo mode leaves the broker off so this
+ * engine returns allow-without-approval everywhere.
+ *
+ * Decision precedence:
+ *   1. Explicit deny in the role's fence → denied + typed reason.
+ *   2. Action falls in the role's approvalRequired list → allowed but
+ *      approvalRequired = true (UI must collect human consent).
+ *   3. risk === 'high' and role is not in HIGH_RISK_AUTONOMOUS → approval required.
+ *   4. Otherwise → allowed.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_MANIFEST_PATH = path.join(MODULE_DIR, '..', '..', 'agents', 'role-manifests.json');
+
+const HIGH_RISK_AUTONOMOUS = new Set(['security', 'sre', 'release-manager']);
+
+let cachedManifests = null;
+
+export function loadRoleManifests(manifestPath = DEFAULT_MANIFEST_PATH) {
+  if (cachedManifests && cachedManifests.path === manifestPath) return cachedManifests.data;
+  if (!existsSync(manifestPath)) {
+    cachedManifests = { path: manifestPath, data: { personas: {} } };
+    return cachedManifests.data;
+  }
+  const raw = readFileSync(manifestPath, 'utf8');
+  const data = JSON.parse(raw);
+  cachedManifests = { path: manifestPath, data };
+  return data;
+}
+
+export function clearManifestCache() {
+  cachedManifests = null;
+}
+
+function manifestFor(role, manifests) {
+  return manifests?.personas?.[role] || null;
+}
+
+function actionMatches(pattern, action) {
+  if (!pattern || !action) return false;
+  if (pattern === action) return true;
+  if (pattern.endsWith(':**')) return action.startsWith(pattern.slice(0, -3));
+  if (pattern.endsWith('/**')) return action.startsWith(pattern.slice(0, -3));
+  return false;
+}
+
+function isExplicitlyDenied(action, manifest) {
+  const deny = manifest?.fence?.deniedActions || [];
+  return deny.some((p) => actionMatches(p, action));
+}
+
+function needsApprovalFromManifest(action, manifest) {
+  const list = manifest?.fence?.approvalRequired || [];
+  return list.some((p) => actionMatches(p, action));
+}
+
+/**
+ * Decide whether a tool / action is allowed for a role.
+ *
+ * @param {object} input
+ * @param {string} input.role
+ * @param {string} [input.project]
+ * @param {string} input.tool
+ * @param {string} input.action
+ * @param {string} [input.risk]
+ * @param {object} [opts]
+ * @returns {{allowed: boolean, reason: string, approvalRequired: boolean, source: string}}
+ */
+export function policyDecision(input = {}, opts = {}) {
+  const { role, tool, action, risk = 'low' } = input;
+  if (!role) return { allowed: false, reason: 'role is required', approvalRequired: false, source: 'engine' };
+  if (!tool) return { allowed: false, reason: 'tool is required', approvalRequired: false, source: 'engine' };
+  if (!action) return { allowed: false, reason: 'action is required', approvalRequired: false, source: 'engine' };
+
+  const manifests = opts.manifests || loadRoleManifests(opts.manifestPath);
+  const manifest = manifestFor(role, manifests);
+
+  if (!manifest) {
+    return {
+      allowed: false,
+      reason: `no role manifest for "${role}"; explicit allowlist required for tool access in team / enterprise mode`,
+      approvalRequired: false,
+      source: 'engine',
+    };
+  }
+
+  if (isExplicitlyDenied(action, manifest)) {
+    return {
+      allowed: false,
+      reason: `action "${action}" is in deny list for role "${role}"`,
+      approvalRequired: false,
+      source: 'manifest.deniedActions',
+    };
+  }
+
+  if (needsApprovalFromManifest(action, manifest)) {
+    return {
+      allowed: true,
+      reason: `action "${action}" requires approval per role "${role}" manifest`,
+      approvalRequired: true,
+      source: 'manifest.approvalRequired',
+    };
+  }
+
+  if (risk === 'high' && !HIGH_RISK_AUTONOMOUS.has(role)) {
+    return {
+      allowed: true,
+      reason: `high-risk action "${action}" needs approval for non-autonomous role "${role}"`,
+      approvalRequired: true,
+      source: 'risk-tier',
+    };
+  }
+
+  return {
+    allowed: true,
+    reason: `action "${action}" permitted for role "${role}"`,
+    approvalRequired: false,
+    source: 'default',
+  };
+}

package/lib/policy/unified-gates.mjs

@@ -0,0 +1,96 @@
+// lib/policy/unified-gates.mjs
+// Single policy declaration for all enforcement layers
+
+export const POLICIES = {
+  commentStyle: {
+    id: 'comment-style',
+    description: 'Comments must follow project standards',
+    layers: ['write', 'commit', 'ci'],
+    bypass: 'CONSTRUCT_SKIP_COMMENT_STYLE',
+    critical: false,
+  },
+  docCoupling: {
+    id: 'doc-coupling',
+    description: 'Code changes require documentation updates',
+    layers: ['commit', 'push'],
+    bypass: 'CONSTRUCT_SKIP_DOCS',
+    critical: false,
+  },
+  secretScan: {
+    id: 'secret-scan',
+    description: 'No secrets in committed code',
+    layers: ['commit', 'push', 'ci'],
+    bypass: 'CONSTRUCT_SKIP_SECRET_SCAN',
+    critical: true,
+  },
+  ciStatus: {
+    id: 'ci-status',
+    description: 'CI must be green before push',
+    layers: ['push', 'session-end'],
+    bypass: 'CONSTRUCT_SKIP_CI_CHECK',
+    critical: true,
+  },
+};
+
+export class UnifiedGateEngine {
+  constructor(options = {}) {
+    this.env = options.env || process.env;
+  }
+  
+  isBypassed(policyId) {
+    const policy = POLICIES[policyId];
+    if (!policy) return { bypassed: false };
+    
+    if (policy.bypass && this.env[policy.bypass] === '1') {
+      return { bypassed: true, envVar: policy.bypass };
+    }
+    
+    if (this.env.CONSTRUCT_SKIP_ALL_GATES === '1') {
+      return { bypassed: true, envVar: 'CONSTRUCT_SKIP_ALL_GATES' };
+    }
+    
+    return { bypassed: false };
+  }
+  
+  async evaluateLayer(layer, context = {}) {
+    const results = [];
+    
+    for (const [id, policy] of Object.entries(POLICIES)) {
+      if (policy.layers.includes(layer)) {
+        const bypass = this.isBypassed(id);
+        results.push({
+          policy: id,
+          passed: bypass.bypassed || true,
+          bypassed: bypass.bypassed,
+          bypassEnvVar: bypass.envVar,
+          critical: policy.critical,
+        });
+      }
+    }
+    
+    const failed = results.filter(r => !r.passed && r.critical);
+    
+    return {
+      layer,
+      passed: failed.length === 0,
+      canProceed: failed.length === 0,
+      results,
+      summary: `${results.filter(r => r.passed).length}/${results.length} passed`,
+    };
+  }
+}
+
+export async function checkGates(layer, context = {}, options = {}) {
+  const engine = new UnifiedGateEngine(options);
+  return await engine.evaluateLayer(layer, context);
+}
+
+export function listPolicies() {
+  return Object.entries(POLICIES).map(([id, policy]) => ({
+    id,
+    description: policy.description,
+    layers: policy.layers,
+    bypass: policy.bypass,
+    critical: policy.critical,
+  }));
+}

package/lib/project-detection.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * lib/project-detection.mjs — Shared utilities for detecting project initialization state.
+ *
+ * Backs hooks that decide whether to create .cx directories or perform other
+ * project-specific operations.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Check if a directory looks like an initialized project.
+ * 
+ * Criteria (any of the following):
+ * 1. Has package.json (npm project)
+ * 2. Has .git directory (git repository)
+ * 3. Has .claude/settings.json or .codex/settings.json (Claude/OpenCode configured)
+ * 4. Has AGENTS.md or plan.md (Construct project)
+ * 5. Has .cx directory already (already has Construct context)
+ * 
+ * @param {string} cwd Directory path to check
+ * @returns {boolean} True if this appears to be an initialized project
+ */
+export function isProjectInitialized(cwd) {
+  // Check for package.json (npm project)
+  const hasPackageJson = existsSync(join(cwd, 'package.json'));
+  
+  // Check for .git (git repository)
+  const hasGit = existsSync(join(cwd, '.git'));
+  
+  // Check for Claude/OpenCode configuration
+  const hasCliSurface = existsSync(join(cwd, '.claude', 'settings.json')) || 
+                        existsSync(join(cwd, '.codex', 'settings.json'));
+  
+  // Check for Construct project markers
+  const hasConstructConfig = existsSync(join(cwd, 'AGENTS.md')) || 
+                             existsSync(join(cwd, 'plan.md'));
+  
+  // Check if .cx already exists (already has Construct context)
+  const hasCxDir = existsSync(join(cwd, '.cx'));
+  
+  // Also check for common project files
+  const hasProjectFile = existsSync(join(cwd, 'Cargo.toml')) || // Rust
+                         existsSync(join(cwd, 'pyproject.toml')) || // Python
+                         existsSync(join(cwd, 'go.mod')) || // Go
+                         existsSync(join(cwd, 'pom.xml')) || // Maven
+                         existsSync(join(cwd, 'build.gradle')) || // Gradle
+                         existsSync(join(cwd, 'composer.json')) || // PHP
+                         existsSync(join(cwd, 'Gemfile')) || // Ruby
+                         existsSync(join(cwd, 'requirements.txt')); // Python
+  
+  return hasPackageJson || hasGit || hasCliSurface || hasConstructConfig || hasCxDir || hasProjectFile;
+}
+
+/**
+ * Check if a directory should have .cx directories created.
+ * More restrictive than isProjectInitialized - only creates .cx for:
+ * 1. Already has .cx directory
+ * 2. Has Construct config (AGENTS.md, plan.md)
+ * 3. Has Claude/OpenCode configuration
+ * 4. Has package.json AND .git (established npm project)
+ * 
+ * @param {string} cwd Directory path to check
+ * @returns {boolean} True if .cx should be created
+ */
+export function shouldCreateCx(cwd) {
+  // Already has .cx directory
+  if (existsSync(join(cwd, '.cx'))) {
+    return true;
+  }
+  
+  // Has Construct project markers
+  const hasConstructConfig = existsSync(join(cwd, 'AGENTS.md')) || 
+                             existsSync(join(cwd, 'plan.md'));
+  if (hasConstructConfig) {
+    return true;
+  }
+  
+  // Has Claude/OpenCode configuration
+  const hasCliSurface = existsSync(join(cwd, '.claude', 'settings.json')) || 
+                        existsSync(join(cwd, '.codex', 'settings.json'));
+  if (hasCliSurface) {
+    return true;
+  }
+  
+  // Has both package.json and .git (established npm project)
+  const hasPackageJson = existsSync(join(cwd, 'package.json'));
+  const hasGit = existsSync(join(cwd, '.git'));
+  if (hasPackageJson && hasGit) {
+    return true;
+  }
+  
+  // Default: don't create .cx in uninitialized directories
+  return false;
+}
+
+/**
+ * Check if this is likely a new project setup phase.
+ * Returns true if directory looks empty/uninitialized.
+ * 
+ * @param {string} cwd Directory path to check
+ * @returns {boolean} True if this appears to be a new project setup
+ */
+export function isNewProjectSetup(cwd) {
+  // Has no project markers
+  const hasPackageJson = existsSync(join(cwd, 'package.json'));
+  const hasGit = existsSync(join(cwd, '.git'));
+  const hasConstructConfig = existsSync(join(cwd, 'AGENTS.md')) || 
+                             existsSync(join(cwd, 'plan.md'));
+  const hasCliSurface = existsSync(join(cwd, '.claude', 'settings.json')) || 
+                        existsSync(join(cwd, '.codex', 'settings.json'));
+  const hasCxDir = existsSync(join(cwd, '.cx'));
+  
+  return !hasPackageJson && !hasGit && !hasConstructConfig && !hasCliSurface && !hasCxDir;
+}
+
+/**
+ * Check if this is a Construct project.
+ * 
+ * @param {string} cwd Directory path to check
+ * @returns {boolean} True if this is a Construct project
+ */
+export function isConstructProject(cwd) {
+  return existsSync(join(cwd, 'AGENTS.md')) || 
+         existsSync(join(cwd, 'plan.md')) ||
+         existsSync(join(cwd, '.cx', 'context.md')) ||
+         existsSync(join(cwd, '.cx', 'context.json'));
+}