@williambeto/ai-workflow 2.4.8 → 2.6.3

package/src/core/finalization/workspace-snapshot.js

@@ -1,110 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import crypto from "node:crypto";
-import { execSync } from "node:child_process";
-
-export class WorkspaceSnapshot {
-  constructor({ cwd = process.cwd() } = {}) {
-    this.cwd = cwd;
-  }
-
-  isIgnored(relativePath) {
-    const norm = relativePath.replaceAll("\\", "/");
-    if (norm === "node_modules" || norm.startsWith("node_modules/")) return true;
-    if (norm === "vendor" || norm.startsWith("vendor/")) return true;
-    if (norm === ".git" || norm.startsWith(".git/")) return true;
-    if (norm === "EVIDENCE.json") return true;
-    if (norm === ".ai-workflow/EVIDENCE.json") return true;
-    if (norm.startsWith(".ai-workflow/history/")) return true;
-    if (norm.startsWith(".ai-workflow/handoffs/")) return true;
-    return false;
-  }
-
-  async capture() {
-    const files = {};
-    await this.scanDir(this.cwd, files);
-
-    const execGit = (args) => {
-      try {
-        return execSync(`git ${args}`, { cwd: this.cwd, encoding: "utf8", stdio: "pipe" }).trim();
-      } catch {
-        return "";
-      }
-    };
-
-    const branch = execGit("rev-parse --abbrev-ref HEAD");
-    const head = execGit("rev-parse HEAD");
-    const indexTree = execGit("write-tree");
-
-    const stagedDiff = execGit("diff --cached");
-    const unstagedDiff = execGit("diff");
-    const untrackedFiles = execGit("status --porcelain");
-
-    const hashString = (str) => {
-      return crypto.createHash("sha256").update(str).digest("hex");
-    };
-
-    return {
-      branch,
-      head,
-      indexTree,
-      files,
-      stagedDiffHash: hashString(stagedDiff),
-      unstagedDiffHash: hashString(unstagedDiff),
-      untrackedFilesHash: hashString(untrackedFiles)
-    };
-  }
-
-  async scanDir(dir, filesMap) {
-    try {
-      const entries = await fs.readdir(dir, { withFileTypes: true });
-      for (const entry of entries) {
-        const fullPath = path.join(dir, entry.name);
-        const relativePath = path.relative(this.cwd, fullPath);
-
-        if (this.isIgnored(relativePath)) {
-          continue;
-        }
-
-        if (entry.isDirectory()) {
-          await this.scanDir(fullPath, filesMap);
-        } else if (entry.isFile()) {
-          try {
-            const stat = await fs.stat(fullPath);
-            const content = await fs.readFile(fullPath);
-            const sha256 = crypto.createHash("sha256").update(content).digest("hex");
-            const isExecutable = (stat.mode & 0o111) !== 0;
-            const mode = isExecutable ? "100755" : "100644";
-
-            filesMap[relativePath] = {
-              sha256,
-              mode
-            };
-          } catch {
-            // ignore unreadable/locked files
-          }
-        }
-      }
-    } catch {
-      // ignore
-    }
-  }
-
-  calculateHash(snapshot) {
-    const hash = crypto.createHash("sha256");
-    hash.update(snapshot.branch || "");
-    hash.update(snapshot.head || "");
-    hash.update(snapshot.indexTree || "");
-    hash.update(snapshot.stagedDiffHash || "");
-    hash.update(snapshot.unstagedDiffHash || "");
-    hash.update(snapshot.untrackedFilesHash || "");
-
-    const sortedFiles = Object.keys(snapshot.files || {}).sort();
-    for (const file of sortedFiles) {
-      hash.update(file);
-      hash.update(snapshot.files[file].sha256);
-      hash.update(snapshot.files[file].mode);
-    }
-    return hash.digest("hex");
-  }
-}

package/src/core/gates/branch-gate.js

@@ -1,134 +0,0 @@
-import { execSync } from "node:child_process";
-import fs from "node:fs";
-import path from "node:path";
-
-function slugify(value = "task") {
-  return String(value)
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 48) || "task";
-}
-
-/**
- * BranchGate - Protects main/master and can recover safely onto a scoped branch.
- */
-export class BranchGate {
-  constructor({ protectedBranches = ["main", "master"], memoryDir, cwd = process.cwd() } = {}) {
-    this.protectedBranches = protectedBranches;
-    this.logPath = memoryDir ? path.join(memoryDir, "GATE_ALERTS.log") : null;
-    this.cwd = cwd;
-  }
-
-  run(command) {
-    return execSync(command, {
-      cwd: this.cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"]
-    }).trim();
-  }
-
-  log(event) {
-    if (!this.logPath) return;
-    const timestamp = new Date().toISOString();
-    const logEntry = `[${timestamp}] ${event}\n`;
-    try {
-      if (!fs.existsSync(path.dirname(this.logPath))) fs.mkdirSync(path.dirname(this.logPath), { recursive: true });
-      fs.appendFileSync(this.logPath, logEntry);
-    } catch (error) {
-      console.error(`Failed to write to gate log: ${error.message}`);
-    }
-  }
-
-  getDirtyState() {
-    const lines = this.run("git status --short").split("\n").filter(Boolean);
-    const tracked = lines.filter((line) => !line.startsWith("??"));
-    const untracked = lines.filter((line) => line.startsWith("??"));
-    return { clean: lines.length === 0, tracked, untracked, lines };
-  }
-
-  createScopedBranch(taskSlug) {
-    const base = `feat/${slugify(taskSlug)}`;
-    let candidate = base;
-    let suffix = 2;
-    while (true) {
-      try {
-        this.run(`git show-ref --verify --quiet refs/heads/${candidate}`);
-        candidate = `${base}-${suffix++}`;
-      } catch {
-        break;
-      }
-    }
-    this.run(`git switch -c ${candidate}`);
-    return candidate;
-  }
-
-  getCurrentBranch() {
-    try {
-      return this.run("git branch --show-current") || this.run("git symbolic-ref --short HEAD") || "unknown";
-    } catch {
-      try {
-        return this.run("git symbolic-ref --short HEAD") || "unknown";
-      } catch {
-        return "unknown";
-      }
-    }
-  }
-
-  /**
-   * Strictly verifies branch safety without any override bypasses.
-   */
-  check(overrideIgnored = "", { taskSlug = "implementation", readOnly = false } = {}) {
-    if (readOnly) {
-      const currentBranch = this.getCurrentBranch();
-      return { blocked: false, branch: currentBranch, recovered: false, readOnly: true };
-    }
-
-    try {
-      // 1. Verify inside worktree (Git availability)
-      try {
-        this.run("git rev-parse --is-inside-work-tree");
-      } catch (e) {
-        const reason = "Git is unavailable or not inside a Git repository. Implementation work is blocked.";
-        this.log(`BLOCKED: ${reason}`);
-        return { blocked: true, branch: "unknown", reason };
-      }
-
-      // 2. Get current branch
-      const currentBranch = this.getCurrentBranch();
-      if (!currentBranch || currentBranch === "unknown" || currentBranch.trim() === "") {
-        const reason = "Could not determine current Git branch name. Implementation work is blocked.";
-        this.log(`BLOCKED: ${reason}`);
-        return { blocked: true, branch: "unknown", reason };
-      }
-
-      const isProtected = this.protectedBranches.includes(currentBranch);
-      if (!isProtected) {
-        return { blocked: false, branch: currentBranch, recovered: false };
-      }
-
-      // 3. Protected branch checks - any dirty file blocks
-      const dirty = this.getDirtyState();
-      if (!dirty.clean) {
-        const reason = `Direct writes to protected branch '${currentBranch}' are prohibited and the branch is dirty (has changes).`;
-        this.log(`BLOCKED: ${reason}`);
-        return { blocked: true, branch: currentBranch, reason, dirtyState: dirty };
-      }
-
-      // 4. Create scoped branch (Auto-recover)
-      const recoveredBranch = this.createScopedBranch(taskSlug);
-      this.log(`AUTO-RECOVERED '${currentBranch}' -> '${recoveredBranch}'`);
-      return {
-        blocked: false,
-        branch: recoveredBranch,
-        branchBefore: currentBranch,
-        recovered: true,
-        dirtyState: dirty
-      };
-    } catch (error) {
-      const reason = `Git command failure on branch gate check: ${error.message}`;
-      this.log(`BLOCKED: ${reason}`);
-      return { blocked: true, branch: "unknown", error: error.message, reason, recovered: false };
-    }
-  }
-}

package/src/core/gates/merge-gate.js

@@ -1,74 +0,0 @@
-import { execSync } from "node:child_process";
-
-/**
- * MergeGate verifies that commit history on integration branches respects
- * the non-fast-forward (--no-ff) merge strategy, preserving feature branch
- * topology instead of flattening/fast-forwarding.
- */
-export class MergeGate {
-  constructor({ cwd = process.cwd() } = {}) {
-    this.cwd = cwd;
-  }
-
-  runGit(command) {
-    return execSync(command, {
-      cwd: this.cwd,
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "pipe"]
-    }).trim();
-  }
-
-  /**
-   * Checks the commit history of the repository/branch.
-   * @param {string} branchName The branch to check.
-   * @returns {{ status: "PASS" | "FAIL_QUALITY_GATE" | "ERROR", reason?: string }}
-   */
-  check(branchName) {
-    try {
-      // Get the last 50 commits with parent hashes and subjects
-      const logOutput = this.runGit('git log -n 50 --format="%H|%P|%s"');
-      const lines = logOutput.split("\n").filter(Boolean);
-
-      const commits = lines.map((line) => {
-        const parts = line.split("|");
-        const hash = parts[0] || "";
-        const parentsStr = parts[1] || "";
-        const parents = parentsStr.split(" ").filter(Boolean);
-        const subject = parts[2] || "";
-        return { hash, parents, subject };
-      });
-
-      // 1. Enforce that any commit containing merge-like patterns in its subject must have at least 2 parents
-      for (const commit of commits) {
-        const isMergeSubject = /merge\b/i.test(commit.subject) || /pull request/i.test(commit.subject);
-        if (isMergeSubject && commit.parents.length < 2) {
-          return {
-            status: "FAIL_QUALITY_GATE",
-            reason: `Linear or fast-forward merge detected for commit '${commit.hash.slice(0, 7)}' ("${commit.subject}"). Merges into integration branches must use the non-fast-forward (--no-ff) strategy to preserve topology.`
-          };
-        }
-      }
-
-      // 2. If the current branch is an integration branch, ensure it contains at least one merge commit (2+ parents)
-      // to establish non-linear history, unless the repository has very few commits (e.g. initial setup).
-      const isIntegrationBranch = ["main", "master"].includes(branchName) || String(branchName).startsWith("release");
-      if (isIntegrationBranch && commits.length > 5) {
-        const hasMergeCommit = commits.some((c) => c.parents.length >= 2);
-        if (!hasMergeCommit) {
-          return {
-            status: "FAIL_QUALITY_GATE",
-            reason: `Integration branch '${branchName}' has a purely linear commit history. Integrated branches must use non-fast-forward (--no-ff) merges to preserve feature branches.`
-          };
-        }
-      }
-
-      return { status: "PASS" };
-    } catch (error) {
-      // If we are not inside a git repo or git is not available, we fail-closed or report error
-      return {
-        status: "ERROR",
-        reason: `Failed to check merge integrity: ${error.message}`
-      };
-    }
-  }
-}

package/src/core/handoff/handoff-engine.js

@@ -1,104 +0,0 @@
-import { execSync } from "node:child_process";
-import fs from "node:fs/promises";
-import path from "node:path";
-
-/**
- * HandoffEngine - Bundles project context into a single Markdown packet.
- */
-export class HandoffEngine {
-  constructor({ cwd }) {
-    this.cwd = cwd;
-  }
-
-   /**
-   * Generates a handoff packet.
-   * @param {Object} data - Context data.
-   * @returns {Promise<string>} The generated packet content.
-   */
-  async generate({ taskId, author, status, specPaths = [], nextActions, evidence = null }) {
-    const timestamp = new Date().toISOString();
-    
-    // 1. Collect Specs content
-    let specsContent = "";
-    for (const specPath of specPaths) {
-      const absolutePath = path.isAbsolute(specPath) ? specPath : path.join(this.cwd, specPath);
-      try {
-        const content = await fs.readFile(absolutePath, "utf8");
-        specsContent += `### File: ${specPath}\n\n${content}\n\n`;
-      } catch (err) {
-        specsContent += `### File: ${specPath}\n\n[Error reading file: ${err.message}]\n\n`;
-      }
-    }
-
-    // 2. Capture Git Diff
-    let gitDiff = "No changes detected.";
-    try {
-      gitDiff = execSync("git diff HEAD", { cwd: this.cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || "No changes detected.";
-    } catch (err) {
-      gitDiff = `[Error capturing diff: ${err.message}]`;
-    }
-
-    // 3. Read EVIDENCE.json or use provided in-memory evidence
-    let evidenceJson = "{}";
-    let evidenceSummary = "No evidence found.";
-    if (evidence) {
-      const data = typeof evidence === "string" ? JSON.parse(evidence) : evidence;
-      evidenceJson = JSON.stringify(data, null, 2);
-      evidenceSummary = `Status: ${data.status || data.internalStatus || "unknown"}, Commands: ${data.commands?.length || 0}`;
-    } else {
-      const evidencePath = path.join(this.cwd, "EVIDENCE.json");
-      try {
-        const content = await fs.readFile(evidencePath, "utf8");
-        const data = JSON.parse(content);
-        evidenceJson = JSON.stringify(data, null, 2);
-        evidenceSummary = `Status: ${data.status}, Commands: ${data.commands?.length || 0}`;
-      } catch (err) {
-        // Optional: don't fail if evidence is missing
-      }
-    }
-
-    // 4. Populate Template
-    const possibleTemplatePaths = [
-      path.join(this.cwd, ".ai-workflow/templates/HANDOFF.template.md"),
-      path.join(this.cwd, ".ai-workflow/harness/handoffs/HANDOFF.template.md"),
-      path.join(import.meta.dirname, "../../../dist-assets/templates/HANDOFF.template.md"),
-      path.join(import.meta.dirname, "../../../assets/templates/HANDOFF.template.md")
-    ];
-
-    let template = null;
-    let lastError = null;
-
-    for (const tPath of possibleTemplatePaths) {
-      try {
-        template = await fs.readFile(tPath, "utf8");
-        break;
-      } catch (err) {
-        lastError = err;
-      }
-    }
-
-    if (!template) {
-      throw new Error(`CRITICAL FAILURE: Could not locate HANDOFF.template.md. Tried paths:\n${possibleTemplatePaths.join("\n")}\nLast error: ${lastError?.message}`);
-    }
-
-    const packet = template
-      .replace("${TASK_ID}", taskId || "unknown")
-      .replace("${TIMESTAMP}", timestamp)
-      .replace("${AUTHOR}", author || "AI Workflow Kit")
-      .replace("${STATUS}", status || "IN_PROGRESS")
-      .replace("${SPECS_CONTENT}", specsContent || "No specs provided.")
-      .replace("${EVIDENCE_SUMMARY}", evidenceSummary)
-      .replace("${EVIDENCE_JSON}", evidenceJson)
-      .replace("${GIT_DIFF}", gitDiff)
-      .replace("${NEXT_ACTIONS}", nextActions || "Awaiting manager assignment.");
-
-    const handoffDir = path.join(this.cwd, ".ai-workflow/handoffs");
-    await fs.mkdir(handoffDir, { recursive: true });
-    
-    const packetName = `HANDOFF-${taskId || "TMP"}-${Date.now()}.md`;
-    const packetPath = path.join(handoffDir, packetName);
-    await fs.writeFile(packetPath, packet);
-
-    return packetPath;
-  }
-}

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

@@ -1,153 +0,0 @@
-import { spawnSync, execSync } from "node:child_process";
-import fs from "node:fs/promises";
-import path from "node:path";
-
-/**
- * Determines which npm scripts are available in the consumer project.
- * @param {string} cwd
- * @returns {Promise<Record<string, string>>}
- */
-async function readScripts(cwd) {
-  try {
-    const pkg = JSON.parse(await fs.readFile(path.join(cwd, "package.json"), "utf8"));
-    return pkg.scripts || {};
-  } catch {
-    return {};
-  }
-}
-
-/**
- * Returns the list of files changed since the last commit.
- * Used to detect whether remediation produced any observable change.
- * @param {string} cwd
- * @returns {string[]}
- */
-function getChangedFiles(cwd) {
-  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 [];
-  }
-}
-
-/**
- * Maps an affectedCheck source string to likely npm script names to re-run.
- * e.g. "check:branchSafety" → [] (no command can fix a branch issue)
- *      "evidence" with failed test → ["test"]
- * @param {string[]} affectedChecks
- * @param {Record<string, string>} scripts
- * @returns {string[]} ordered list of script names to retry
- */
-function resolveRetryScripts(affectedChecks, scripts) {
-  const retry = new Set();
-
-  for (const check of affectedChecks) {
-    // Evidence failures → re-run the failing validation scripts
-    if (check === "evidence" || check === "result") {
-      if (scripts.test) retry.add("test");
-      if (scripts.lint) retry.add("lint");
-      if (scripts.build) retry.add("build");
-      if (scripts.typecheck) retry.add("typecheck");
-    }
-    // Specific check types
-    if (check.includes("test")) retry.add("test");
-    if (check.includes("lint")) retry.add("lint");
-    if (check.includes("build")) retry.add("build");
-    if (check.includes("typecheck")) retry.add("typecheck");
-  }
-
-  // Filter to only scripts that actually exist
-  return [...retry].filter((name) => !!scripts[name]);
-}
-
-/**
- * CLI Remediation Executor — default implementation for `ai-workflow run`.
- *
- * Plugs into HealerEngine as the `remediate` function. On each attempt it:
- *   1. Reads the remediation-request.json to understand what failed
- *   2. Re-runs the affected npm scripts (lint, test, build, typecheck)
- *   3. Reports changed files and whether any script now passes
- *
- * Design constraints:
- *   - This executor does NOT modify source code — it only re-runs validation commands.
- *   - It is effective for transient failures (e.g. flaky tests, stale build artifacts).
- *   - For structural failures (missing tests, broken implementation), it will exhaust
- *     its attempt budget and return applied:false, triggering a BLOCKED status.
- *   - The user is shown clear output on each attempt.
- *
- * @param {Object} ctx - Context provided by HealerEngine.run()
- * @param {number} ctx.attempt
- * @param {number} ctx.maxAttempts
- * @param {string} ctx.mode
- * @param {string} ctx.taskSlug
- * @param {Object} ctx.result - Current combined validation result
- * @param {string[]} ctx.affectedChecks
- * @param {string}  ctx.requestPath - Path to remediation-request.json
- * @param {string}  cwd - Consumer project working directory (bound via closure)
- * @returns {Promise<{applied: boolean, changedFiles?: string[], evidenceAdded?: string[], reason?: string}>}
- */
-export function createCliRemediationExecutor(cwd) {
-  return async function remediationExecutor({ attempt, maxAttempts, mode, affectedChecks, requestPath }) {
-    console.log(`\n[HEALER] Attempt ${attempt}/${maxAttempts} — mode: ${mode}`);
-    console.log(`[HEALER] Affected: ${affectedChecks.join(", ")}`);
-
-    const scripts = await readScripts(cwd);
-    const filesBefore = getChangedFiles(cwd);
-    const toRetry = resolveRetryScripts(affectedChecks, scripts);
-
-    if (toRetry.length === 0) {
-      console.log("[HEALER] No retryable scripts found for the affected checks.");
-      console.log(`[HEALER] Review ${requestPath} for details.`);
-      return {
-        applied: false,
-        reason: `No npm scripts available to address: ${affectedChecks.join(", ")}. Manual remediation required.`
-      };
-    }
-
-    console.log(`[HEALER] Re-running: ${toRetry.map((s) => `npm run ${s}`).join(", ")}`);
-
-    const results = [];
-    let anyPassed = false;
-
-    for (const scriptName of toRetry) {
-      process.stdout.write(`  → npm run ${scriptName} ... `);
-      const isWin32 = process.platform === "win32";
-      const cmd = isWin32 ? "npm.cmd" : "npm";
-      const result = spawnSync(cmd, ["run", scriptName], {
-        cwd,
-        shell: false,
-        encoding: "utf8",
-        timeout: 120000
-      });
-      const passed = result.status === 0;
-      if (passed) anyPassed = true;
-      console.log(passed ? "PASS" : "FAIL");
-      results.push({ script: scriptName, passed, exitCode: result.status });
-    }
-
-    const filesAfter = getChangedFiles(cwd);
-    const changedFiles = filesAfter.filter((f) => !filesBefore.includes(f));
-
-    if (!anyPassed && changedFiles.length === 0) {
-      console.log("[HEALER] No scripts passed and no files changed — remediation had no effect.");
-      return {
-        applied: false,
-        reason: `Re-ran ${toRetry.join(", ")} — all failed. Structural fix required by the implementing agent.`
-      };
-    }
-
-    console.log(`[HEALER] Applied: ${results.filter((r) => r.passed).map((r) => r.script).join(", ") || "none passed"}`);
-    if (changedFiles.length) console.log(`[HEALER] Changed files: ${changedFiles.join(", ")}`);
-
-    return {
-      applied: true,
-      changedFiles,
-      evidenceAdded: anyPassed ? ["validation-output"] : []
-    };
-  };
-}