@williambeto/ai-workflow 2.2.6 → 2.3.0

package/src/core/healing/runtime-remediation-executor.js

@@ -0,0 +1,136 @@
+import { OpenCodeAdapter } from "../runtime/opencode-adapter.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execSync } from "node:child_process";
+
+export function createRuntimeRemediationExecutor(cwd, ledger = null) {
+  const adapter = new OpenCodeAdapter({ cwd });
+
+  function getChangedFiles() {
+    try {
+      const output = execSync("git status --short", { cwd, encoding: "utf8" });
+      return output
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => line.slice(3).trim())
+        .filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+
+  return async function runtimeRemediationExecutor({ attempt, maxAttempts, mode, affectedChecks, requestPath, result }) {
+    console.log(`\n[HEALER] Running Runtime/Phoenix Structural Remediation [Attempt ${attempt}/${maxAttempts}]`);
+    console.log(`[HEALER] Affected checks: ${affectedChecks.join(", ")}`);
+
+    if (ledger) {
+      ledger.logEvent({
+        actor: "Phoenix",
+        actorType: "runtime-agent",
+        observed: true,
+        runtime: "opencode",
+        eventType: "remediation_start",
+        provenance: "opencode-adapter",
+        data: {
+          attempt,
+          affectedChecks,
+          event: "remediation.started"
+        }
+      });
+    }
+
+    let requestContent = {};
+    try {
+      requestContent = JSON.parse(await fs.readFile(requestPath, "utf8"));
+    } catch {
+      // ignore/fallback
+    }
+
+    const filesBefore = getChangedFiles();
+    const fileContentsBefore = {};
+    for (const file of filesBefore) {
+      try {
+        fileContentsBefore[file] = await fs.readFile(path.join(cwd, file), "utf8");
+      } catch {
+        fileContentsBefore[file] = null;
+      }
+    }
+    
+    // Extract concrete command outputs for failing checks
+    const failedCommands = (result?.evidence?.commands || [])
+      .filter(cmd => ["FAIL", "BLOCKED"].includes(cmd.status));
+    
+    let concreteOutput = "";
+    if (failedCommands.length > 0) {
+      concreteOutput = failedCommands.map(cmd => {
+        return `Command: ${cmd.name} (${Array.isArray(cmd.command) ? cmd.command.join(" ") : cmd.command})
+Exit Code: ${cmd.exitCode}
+Output:
+${cmd.output}`;
+      }).join("\n\n");
+    } else {
+      concreteOutput = JSON.stringify(result?.quality || result || {}, null, 2);
+    }
+
+    const promptMsg = `We are in remediation mode (attempt ${attempt}/${maxAttempts}).
+The following validation checks have failed:
+${affectedChecks.join(", ")}
+
+Details of the failure:
+\`\`\`
+${concreteOutput}
+\`\`\`
+
+Please inspect the code, identify the root cause of these failures (e.g. failing tests, syntax issues, build errors), and write a correction to the relevant files in the workspace to make the tests/validations pass.`;
+
+    console.log(`[HEALER] Sending structural healing request to Phoenix agent...`);
+    const runResult = await adapter.execute(promptMsg, {
+      agent: "Phoenix"
+    });
+
+    const filesAfter = getChangedFiles();
+    const changedFiles = [];
+    for (const file of filesAfter) {
+      if (!filesBefore.includes(file)) {
+        changedFiles.push(file);
+      } else {
+        try {
+          const contentAfter = await fs.readFile(path.join(cwd, file), "utf8");
+          if (contentAfter !== fileContentsBefore[file]) {
+            changedFiles.push(file);
+          }
+        } catch {
+          if (fileContentsBefore[file] !== null) {
+            changedFiles.push(file);
+          }
+        }
+      }
+    }
+    const success = runResult.success && changedFiles.length > 0;
+
+    if (!runResult.success) {
+      console.log(`[HEALER] Phoenix remediation failed: ${runResult.error || "Unknown error"}`);
+      return {
+        applied: false,
+        reason: `Phoenix runtime execution failed: ${runResult.error || "Unknown error"}`
+      };
+    }
+
+    if (changedFiles.length === 0) {
+      console.log(`[HEALER] Phoenix execution succeeded but no files were modified.`);
+      return {
+        applied: false,
+        reason: "Phoenix runtime executed but did not modify any files in the workspace."
+      };
+    }
+
+    console.log(`[HEALER] Phoenix successfully executed remediation commands.`);
+    console.log(`[HEALER] Files modified: ${changedFiles.join(", ")}`);
+
+    return {
+      applied: true,
+      changedFiles,
+      evidenceAdded: ["phoenix-healing-run"]
+    };
+  };
+}

package/src/core/runtime/opencode-adapter.js

@@ -1,4 +1,4 @@
-import { spawn, execSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import readline from "node:readline";
 
 /**
@@ -9,86 +9,161 @@ export class OpenCodeAdapter {
     this.cwd = cwd;
   }
 
+  /**
+   * Inspects the availability and capability of the OpenCode CLI.
+   * @returns {Promise<{available: boolean, supports: {run: boolean, formatJson: boolean, agent: boolean, model: boolean}}>}
+   */
+  async inspect() {
+    try {
+      const cliHelp = spawnSync("opencode", ["--help"], { encoding: "utf8" });
+      const runHelp = spawnSync("opencode", ["run", "--help"], { encoding: "utf8" });
+
+      const available = cliHelp.status === 0 && runHelp.status === 0;
+      if (!available) {
+        return {
+          available: false,
+          supports: { run: false, formatJson: false, agent: false, model: false }
+        };
+      }
+
+      return {
+        available: true,
+        supports: {
+          run: /\brun\b/.test(cliHelp.stdout),
+          formatJson: /--format/.test(runHelp.stdout),
+          agent: /--agent/.test(runHelp.stdout),
+          model: /--model/.test(runHelp.stdout),
+        }
+      };
+    } catch {
+      return {
+        available: false,
+        supports: { run: false, formatJson: false, agent: false, model: false }
+      };
+    }
+  }
+
   /**
    * Runs opencode with a prompt and options.
    * @param {string} message - The message prompt.
-   * @param {Object} options - CLI options (e.g. agent, model, dangerouslySkipPermissions).
-   * @returns {Promise<{success: boolean, commandsRun: string[], eventCount: number}>}
+   * @param {Object} options - CLI options (e.g. agent, model, readOnly).
+   * @returns {Promise<{success: boolean, commandsRun: string[], eventCount: number, error?: string}>}
    */
-  async execute(message, { agent = null, model = null, dangerouslySkipPermissions = false } = {}) {
-    return new Promise((resolve) => {
-      const args = ["run", message, "--format", "json"];
-      if (agent) {
-        args.push("--agent", agent);
-      }
-      if (model) {
-        args.push("--model", model);
-      }
-      if (dangerouslySkipPermissions) {
-        args.push("--dangerously-skip-permissions");
-      }
+  async execute(message, { agent = null, model = null, readOnly = false } = {}) {
+    const inspection = await this.inspect();
+    if (!inspection.available) {
+      return {
+        success: false,
+        commandsRun: [],
+        eventCount: 0,
+        error: "OpenCode CLI is not installed or not available in the system PATH."
+      };
+    }
+
+    const runInWorkspace = async (targetCwd) => {
+      return new Promise((resolve) => {
+        const args = ["run", message];
+        if (inspection.supports.formatJson) {
+          args.push("--format", "json");
+        }
+        if (agent && inspection.supports.agent) {
+          args.push("--agent", agent);
+        }
+        if (model && inspection.supports.model) {
+          args.push("--model", model);
+        }
 
-      console.log(`[RUNTIME] Delegating to OpenCode: opencode ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`);
+        console.log(`[RUNTIME] Delegating to OpenCode: opencode ${args.map(a => a.includes(" ") ? `"${a}"` : a).join(" ")}`);
 
-      const child = spawn("opencode", args, {
-        cwd: this.cwd,
-        shell: true,
-        stdio: ["ignore", "pipe", "inherit"] // Inherit stderr to show warnings directly
-      });
+        const child = spawn("opencode", args, {
+          cwd: targetCwd,
+          stdio: ["ignore", "pipe", "inherit"] // Inherit stderr to show warnings directly
+        });
 
-      const rl = readline.createInterface({
-        input: child.stdout,
-        terminal: false
-      });
+        const rl = readline.createInterface({
+          input: child.stdout,
+          terminal: false
+        });
 
-      const commandsRun = [];
-      let eventCount = 0;
+        const commandsRun = [];
+        let eventCount = 0;
 
-      rl.on("line", (line) => {
-        const trimmed = line.trim();
-        if (!trimmed) return;
+        rl.on("line", (line) => {
+          const trimmed = line.trim();
+          if (!trimmed) return;
 
-        try {
-          const event = JSON.parse(trimmed);
-          eventCount++;
+          try {
+            const event = JSON.parse(trimmed);
+            eventCount++;
 
-          // 1. Stream agent output text in real-time to user
-          if (event.type === "text" && event.part?.text) {
-            process.stdout.write(event.part.text);
-          }
+            // 1. Stream agent output text in real-time to user
+            if (event.type === "text" && event.part?.text) {
+              process.stdout.write(event.part.text);
+            }
 
-          // 2. Capture tool executions/commands
-          if (event.type === "step_start" && event.part?.toolCalls) {
-            for (const call of event.part.toolCalls) {
-              if (call.name === "run_command" && call.args?.CommandLine) {
-                commandsRun.push(call.args.CommandLine);
+            // 2. Capture tool executions/commands
+            if (event.type === "step_start" && event.part?.toolCalls) {
+              for (const call of event.part.toolCalls) {
+                if (call.name === "run_command" && call.args?.CommandLine) {
+                  commandsRun.push(call.args.CommandLine);
+                }
+                if (readOnly) {
+                  const name = call.name || "";
+                  const isWriteTool = name.startsWith("write_") || name.includes("write") || name.includes("replace") || name.includes("edit") || name.includes("delete") || name.includes("remove");
+                  let isDestructiveGit = false;
+                  if (name === "run_command" && call.args?.CommandLine) {
+                    const cmd = call.args.CommandLine;
+                    const destPattern = /\b(git\s+(commit|add|push|merge|reset|rm|branch|checkout|switch|stash|init)|touch|rm|mkdir|cp|mv|chmod|chown|tee|sed|awk)\b|>>|>/;
+                    if (destPattern.test(cmd)) {
+                      isDestructiveGit = true;
+                    }
+                  }
+                  if (isWriteTool || isDestructiveGit) {
+                    console.error(`\n[SECURITY WARNING] Read-only execution blocked attempt to write/modify workspace: tool '${name}' or command detected.`);
+                    child.kill();
+                    resolve({
+                      success: false,
+                      commandsRun,
+                      eventCount,
+                      error: `Read-only confinement violation: tool '${name}' or command attempted write/modify operation during read-only task.`
+                    });
+                    return;
+                  }
+                }
               }
             }
+          } catch {
+            // If a line is not valid JSON (e.g. starting/finishing logs), print it directly
+            console.log(trimmed);
           }
-        } catch {
-          // If a line is not valid JSON (e.g. starting/finishing logs), print it directly
-          console.log(trimmed);
-        }
-      });
+        });
 
-      child.on("close", (code) => {
-        console.log("\n[RUNTIME] OpenCode finished execution.");
-        resolve({
-          success: code === 0,
-          commandsRun,
-          eventCount
+        child.on("close", (code) => {
+          console.log("\n[RUNTIME] OpenCode finished execution.");
+          resolve({
+            success: code === 0,
+            commandsRun,
+            eventCount
+          });
         });
-      });
 
-      child.on("error", (err) => {
-        console.error(`\n[RUNTIME] Failed to launch opencode: ${err.message}`);
-        resolve({
-          success: false,
-          commandsRun,
-          eventCount: 0,
-          error: err.message
+        child.on("error", (err) => {
+          console.error(`\n[RUNTIME] Failed to launch opencode: ${err.message}`);
+          resolve({
+            success: false,
+            commandsRun,
+            eventCount: 0,
+            error: err.message
+          });
         });
       });
-    });
+    };
+
+    if (readOnly) {
+      const { runInReadOnlyWorkspace } = await import("../workspace/read-only-workspace.js");
+      return runInReadOnlyWorkspace(this.cwd, runInWorkspace);
+    } else {
+      return runInWorkspace(this.cwd);
+    }
   }
 }

package/src/core/templates.js

@@ -62,6 +62,14 @@ function buildRuntimeFiles({ includeFormalEvidence = false } = {}) {
     }
   }
 
+  // Copy governance policy into opencode/docs/policies/ so the relative link
+  // ../../docs/policies/SKILLS_COMMON_GOVERNANCE.md resolves correctly from
+  // opencode/skills/{skill}/SKILL.md for OpenCode and all platform adapters.
+  const opencodeGovernancePolicy = readPackageFile("dist-assets/docs/policies/SKILLS_COMMON_GOVERNANCE.md");
+  if (opencodeGovernancePolicy !== null) {
+    files["opencode/docs/policies/SKILLS_COMMON_GOVERNANCE.md"] = opencodeGovernancePolicy;
+  }
+
   const commandFiles = discoverPackageFiles("dist-assets/commands");
   for (const [relPath, content] of Object.entries(commandFiles)) {
     const targetPath = relPath.replace(/^dist-assets\//, "opencode/");

package/src/core/validation/evidence-collector.js

@@ -42,18 +42,45 @@ export class EvidenceCollector {
     if (task.presetStatus) {
       return { name: task.name, command: task.command, kind, status: task.presetStatus, exitCode: null, summary: task.summary, output: "" };
     }
-    const result = spawnSync(task.command, {
+
+    let cmd = task.command;
+    let args = [];
+    if (Array.isArray(cmd)) {
+      const [c, ...a] = cmd;
+      cmd = c;
+      args = a;
+    } else if (typeof cmd === "string") {
+      const parts = cmd.split(/\s+/);
+      cmd = parts[0];
+      args = parts.slice(1);
+    }
+
+    const isWin32 = process.platform === "win32";
+    const isUncPath = typeof this.cwd === "string" && (this.cwd.startsWith("\\\\") || this.cwd.startsWith("//"));
+    const shellOption = isWin32 && isUncPath ? "powershell.exe" : (isWin32 ? true : false);
+
+    const result = spawnSync(cmd, args, {
       cwd: this.cwd,
-      shell: true,
+      shell: shellOption,
       encoding: "utf8",
       timeout: this.timeout
     });
+
     let status = result.status === 0 ? "PASS" : "FAIL";
+    if (result.error) {
+      status = "FAIL";
+      if (result.error.code === "ETIMEDOUT") {
+        status = "BLOCKED";
+      }
+    }
+
     let summary = status === "PASS" ? "Command completed successfully." : "Command failed.";
     if (result.error?.code === "ETIMEDOUT") {
-      status = "BLOCKED";
       summary = `Command timed out after ${this.timeout / 1000}s.`;
+    } else if (result.error) {
+      summary = `Command execution error: ${result.error.message}`;
     }
+
     const rawOutput = `${result.stdout || ""}${result.stderr || ""}`.trim();
     const output = rawOutput.length > this.maxLogLength ? `${rawOutput.slice(0, this.maxLogLength)}\n... [TRUNCATED]` : rawOutput;
     return { name: task.name, command: task.command, kind, status, exitCode: result.status, signal: result.signal, summary, output };

package/src/core/validation/quality-guard.js

@@ -1,6 +1,7 @@
 import { execSync } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
+import { MergeGate } from "../gates/merge-gate.js";
 
 const PROTECTED_BRANCHES = new Set(["main", "master"]);
 
@@ -146,6 +147,13 @@ export class QualityGuard {
     if (implementation && PROTECTED_BRANCHES.has(branch)) {
       return { status: "FAIL_QUALITY_GATE", branch, reason: `Implementation changes are present on protected branch '${branch}'.` };
     }
+    if (this.mode === "full") {
+      const mergeGate = new MergeGate({ cwd: this.cwd });
+      const mergeResult = mergeGate.check(branch);
+      if (mergeResult.status === "FAIL_QUALITY_GATE") {
+        return { status: "FAIL_QUALITY_GATE", branch, reason: mergeResult.reason };
+      }
+    }
     return { status: "PASS", branch };
   }
 

package/src/core/validation/stack-detector.js

@@ -0,0 +1,65 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export class StackDetector {
+  constructor({ cwd = process.cwd() } = {}) {
+    this.cwd = cwd;
+  }
+
+  async detect() {
+    const stacks = [];
+
+    // 1. Node check
+    const packageJsonExists = await fs.access(path.join(this.cwd, "package.json")).then(() => true).catch(() => false);
+    if (packageJsonExists) {
+      stacks.push("node");
+    }
+
+    // 2. Python check
+    const pyprojectExists = await fs.access(path.join(this.cwd, "pyproject.toml")).then(() => true).catch(() => false) ||
+                             await fs.access(path.join(this.cwd, "requirements.txt")).then(() => true).catch(() => false) ||
+                             await fs.access(path.join(this.cwd, "setup.py")).then(() => true).catch(() => false) ||
+                             await fs.access(path.join(this.cwd, "Pipfile")).then(() => true).catch(() => false);
+    
+    let hasPythonFiles = pyprojectExists;
+    if (!hasPythonFiles) {
+      hasPythonFiles = await this.hasFileWithExtension(this.cwd, ".py");
+    }
+    if (hasPythonFiles) {
+      stacks.push("python");
+    }
+
+    // 3. PHP check
+    const composerExists = await fs.access(path.join(this.cwd, "composer.json")).then(() => true).catch(() => false);
+    let hasPhpFiles = composerExists;
+    if (!hasPhpFiles) {
+      hasPhpFiles = await this.hasFileWithExtension(this.cwd, ".php");
+    }
+    if (hasPhpFiles) {
+      stacks.push("php");
+    }
+
+    return stacks;
+  }
+
+  async hasFileWithExtension(dir, ext) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          if (["node_modules", "vendor", ".git", "dist", "build", ".cache"].includes(entry.name)) {
+            continue;
+          }
+          const subPath = path.join(dir, entry.name);
+          const found = await this.hasFileWithExtension(subPath, ext);
+          if (found) return true;
+        } else if (entry.isFile() && entry.name.endsWith(ext)) {
+          return true;
+        }
+      }
+    } catch {
+      // ignore
+    }
+    return false;
+  }
+}

package/src/core/validation/validation-planner.js

@@ -0,0 +1,134 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { StackDetector } from "./stack-detector.js";
+
+export class ValidationPlanner {
+  constructor({ cwd = process.cwd(), qualityGuard } = {}) {
+    this.cwd = cwd;
+    this.qualityGuard = qualityGuard;
+    this.stackDetector = new StackDetector({ cwd });
+  }
+
+  async plan(profile = "generic") {
+    const stacks = await this.stackDetector.detect();
+    const tasks = [];
+
+    const changedFiles = this.qualityGuard.getChangedFiles().filter((file) => {
+      return !/(^|\/)(node_modules|vendor|dist|coverage|\.cache)(\/|$)/.test(String(file).replaceAll("\\", "/"));
+    });
+    const executableBehavior = await this.qualityGuard.hasExecutableBehaviorChanges();
+
+    // Node Stack Planning
+    if (stacks.includes("node")) {
+      try {
+        const pkg = JSON.parse(await fs.readFile(path.join(this.cwd, "package.json"), "utf8"));
+        const scripts = pkg.scripts || {};
+
+        this.addNodeScriptTask(tasks, scripts, "lint", ["npm", "run", "lint"]);
+        this.addNodeScriptTask(tasks, scripts, "test", ["npm", "test"], { rejectNoOp: executableBehavior });
+        this.addNodeScriptTask(tasks, scripts, "build", ["npm", "run", "build"]);
+        this.addNodeScriptTask(tasks, scripts, "typecheck", ["npm", "run", "typecheck"]);
+
+        if (scripts.validate && !String(scripts.validate).includes("ai-workflow collect-evidence")) {
+          this.addNodeScriptTask(tasks, scripts, "validate", ["npm", "run", "validate"]);
+        }
+
+        const hasTs = changedFiles.some((file) => /\.(ts|tsx)$/.test(file)) ||
+                      await fs.access(path.join(this.cwd, "tsconfig.json")).then(() => true).catch(() => false);
+        if (hasTs && !scripts.typecheck) {
+          tasks.push({
+            name: "typecheck",
+            command: ["npm", "run", "typecheck"],
+            kind: "typecheck",
+            presetStatus: "FAIL_QUALITY_GATE",
+            summary: "TypeScript detected but no typecheck script is configured."
+          });
+        }
+      } catch {
+        // Fallback or ignore if pkg read fails
+      }
+    }
+
+    // Python Stack Planning
+    if (stacks.includes("python")) {
+      const pythonFiles = changedFiles.filter(f => f.endsWith(".py"));
+
+      // Compiler syntax check for changed python files
+      if (pythonFiles.length > 0) {
+        tasks.push({
+          name: "python-syntax",
+          command: ["python", "-m", "py_compile", ...pythonFiles],
+          kind: "lint"
+        });
+      }
+
+      // Check if testing is needed
+      if (executableBehavior) {
+        // Check if pytest or unittest is configured
+        const hasPytestConfig = await fs.access(path.join(this.cwd, "pytest.ini")).then(() => true).catch(() => false) ||
+                                await fs.access(path.join(this.cwd, "pyproject.toml")).then(() => true).catch(() => false);
+        
+        if (hasPytestConfig || pythonFiles.length > 0) {
+          tasks.push({
+            name: "python-test",
+            command: ["pytest"],
+            kind: "test"
+          });
+        }
+      }
+    }
+
+    // PHP Stack Planning
+    if (stacks.includes("php")) {
+      const phpFiles = changedFiles.filter(f => f.endsWith(".php") || f.endsWith(".inc"));
+
+      // Compiler syntax check for each changed PHP file - split into separate tasks
+      if (phpFiles.length > 0) {
+        for (const file of phpFiles) {
+          tasks.push({
+            name: `php-syntax:${file}`,
+            command: ["php", "-l", file],
+            kind: "lint"
+          });
+        }
+      }
+
+      // Check if testing is needed
+      if (executableBehavior) {
+        const hasPhpUnitXml = await fs.access(path.join(this.cwd, "phpunit.xml")).then(() => true).catch(() => false) ||
+                              await fs.access(path.join(this.cwd, "phpunit.xml.dist")).then(() => true).catch(() => false);
+        if (hasPhpUnitXml || phpFiles.length > 0) {
+          tasks.push({
+            name: "php-test",
+            command: ["vendor/bin/phpunit"],
+            kind: "test"
+          });
+        }
+      }
+    }
+
+    return tasks;
+  }
+
+  addNodeScriptTask(tasks, scripts, name, command, { rejectNoOp = false } = {}) {
+    const script = scripts[name];
+    if (!script) return;
+    if (!rejectNoOp && name === "test" && this.isNoOpScript(script)) return;
+    if (rejectNoOp && this.isNoOpScript(script)) {
+      tasks.push({
+        name,
+        command,
+        kind: name === "test" ? "test" : name,
+        presetStatus: "FAIL_QUALITY_GATE",
+        summary: `Configured ${name} script is a no-op: ${script}`
+      });
+      return;
+    }
+    tasks.push({ name, command, kind: name === "test" ? "test" : name });
+  }
+
+  isNoOpScript(script = "") {
+    const value = String(script).trim().toLowerCase();
+    return /^(echo\b|true$|exit\s+0$|node\s+-e\s+["']?console\.log)/.test(value) || value.includes("tests-pass");
+  }
+}