@williambeto/ai-workflow 2.4.9 → 2.6.3

package/src/commands/init.js

@@ -1,359 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-import { createInstallPlan } from "../core/install-plan.js";
-import { buildAiWorkflowConfig, getTemplateFiles, isValidProfile } from "../core/templates.js";
-import { exists, writeFileSafe, readJson } from "../core/filesystem.js";
-import { createManagedBackup, createManagedPathBackup } from "../core/backup.js";
-import { mergeOpencodeConfig } from "../core/opencode-merge.js";
-import { buildSymlinkEntries, isSymlinkTo, setupInternalSymlinks } from "../core/symlink-layout.js";
-import { GeminiAdapter, ClaudeAdapter, CodexAdapter, AntigravityAdapter } from "../adapters/index.js";
-
-function summarize(actions) {
-  const createCount = actions.filter((a) => a.type === "create").length;
-  const conflictCount = actions.filter((a) => a.type === "conflict").length;
-
-  return { createCount, conflictCount };
-}
-
-function printPlan(actions) {
-  for (const action of actions) {
-    console.log(`- ${action.type.padEnd(8)} ${action.relativePath}`);
-  }
-}
-
-function toIgnoreEntries(linkPath) {
-  if (linkPath === "README.workflow.md") {
-    return [linkPath];
-  }
-
-  const normalized = linkPath.endsWith("/") ? linkPath.slice(0, -1) : linkPath;
-  return [normalized, `${normalized}/`];
-}
-
-function buildGitignoreBlock(entries) {
-  const unique = Array.from(new Set(entries));
-  const sorted = unique.sort((a, b) => a.localeCompare(b));
-
-  return [
-    "# BEGIN AI WORKFLOW KIT",
-    "# AI Workflow Kit generated files",
-    ...sorted,
-    "# END AI WORKFLOW KIT"
-  ].join("\n");
-}
-
-async function upsertGitignoreBlock(cwd, entries) {
-  const gitignorePath = path.join(cwd, ".gitignore");
-  const block = buildGitignoreBlock(entries);
-  const beginMarker = "# BEGIN AI WORKFLOW KIT";
-  const endMarker = "# END AI WORKFLOW KIT";
-
-  const hasGitignore = await exists(gitignorePath);
-  if (!hasGitignore) {
-    await writeFileSafe(gitignorePath, `${block}\n`);
-    return "created";
-  }
-
-  const current = await fs.readFile(gitignorePath, "utf8");
-  const beginIndex = current.indexOf(beginMarker);
-  const endIndex = current.indexOf(endMarker);
-
-  if (beginIndex >= 0 && endIndex > beginIndex) {
-    const before = current
-      .slice(0, beginIndex)
-      .replace(/\n?# AI Workflow Kit generated files\n?$/, "\n")
-      .replace(/[ \t]+$/gm, "")
-      .replace(/\n*$/, "\n");
-    const afterStart = endIndex + endMarker.length;
-    const after = current.slice(afterStart).replace(/^\n*/, "\n");
-    const next = `${before}${block}${after}`;
-    if (next !== current) {
-      await writeFileSafe(gitignorePath, next);
-      return "updated";
-    }
-    return "unchanged";
-  }
-
-  const separator = current.endsWith("\n") ? "\n" : "\n\n";
-  const next = `${current}${separator}${block}\n`;
-  await writeFileSafe(gitignorePath, next);
-  return "updated";
-}
-
-async function injectScripts(cwd) {
-  const pkgPath = path.join(cwd, "package.json");
-  if (!(await exists(pkgPath))) return;
-
-  try {
-    const pkg = await readJson(pkgPath);
-    if (!pkg.scripts) pkg.scripts = {};
-
-    if (!pkg.scripts.validate) {
-      pkg.scripts.validate = "ai-workflow collect-evidence";
-      await writeFileSafe(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
-      return true;
-    }
-  } catch {
-    // Ignore invalid package.json
-  }
-  return false;
-}
-
-export async function runInit({
- cwd, yes, force, dryRun, noInstall, noOverwrite, gemini, claude, codex, antigravity, "dev-mode": devMode, profile }) {
-  // Self-execution guard
-  if (!devMode) {
-    try {
-      const pkgPath = path.join(cwd, "package.json");
-      if (await exists(pkgPath)) {
-        const pkg = await readJson(pkgPath);
-        if (pkg.name === "@williambeto/ai-workflow") {
-          console.error("\nFATAL: Cannot run 'ai-workflow init' inside its own development repository.");
-          console.error("This would corrupt the development environment. Aborting.");
-          console.error("Use the --dev-mode flag if you are developing the kit itself and need to test the init command.\n");
-          process.exit(1);
-        }
-      }
-    } catch {
-      // Ignore if package.json is unreadable. The guard is a safety net.
-    }
-  }
-
-  const selectedProfile = profile || "standard";
-
-  if (!isValidProfile(selectedProfile)) {
-    console.error(`Invalid profile: "${selectedProfile}". Valid profiles: standard, full`);
-    process.exit(1);
-  }
-  const installRoot = ".ai-workflow";
-
-  const platforms = [];
-  if (gemini) platforms.push("gemini");
-  if (claude) platforms.push("claude");
-  if (codex) platforms.push("codex");
-  if (antigravity) platforms.push("antigravity");
-
-  console.log(`ai-workflow: initializing in ${cwd}`);
-  console.log(`Profile: ${selectedProfile}`);
-  if (platforms.length > 0) {
-    console.log(`Platforms: ${platforms.join(", ")}`);
-  }
-
-  const actions = await createInstallPlan({ cwd, exists, profile: selectedProfile });
-  const linkEntries = buildSymlinkEntries({ templateFiles: getTemplateFiles(selectedProfile), installRoot });
-  const { createCount, conflictCount } = summarize(actions);
-
-  console.log(`Plan: ${createCount} create, ${conflictCount} conflict`);
-  printPlan(actions);
-
-  if (!yes && conflictCount > 0 && !force && !noOverwrite) {
-    throw new Error(
-      "conflicts detected. Re-run with --force to replace managed files or resolve conflicts manually"
-    );
-  }
-
-  if (dryRun) {
-    console.log("Dry-run enabled. No files were written.");
-    if (platforms.length > 0) {
-      console.log("ai-workflow: (dry-run) platform migration would be executed after file writing.");
-    }
-    return;
-  }
-
-  const skipped = [];
-  const backups = [];
-  const backupRoot = ".ai-workflow-backups";
-
-  for (const action of actions) {
-    if (action.type === "conflict" && (noOverwrite || !force)) {
-      skipped.push(action.relativePath);
-      continue;
-    }
-
-    if (action.type === "conflict" && force) {
-      const backupPath = await createManagedBackup(action.absolutePath, {
-        cwd,
-        backupRoot,
-        maxPerFile: 20
-      });
-      backups.push(backupPath);
-    }
-
-    const content =
-      action.relativePath === ".ai-workflow/config.json"
-        ? `${JSON.stringify(
-            buildAiWorkflowConfig({
-              profile: selectedProfile
-            }),
-            null,
-            2
-          )}\n`
-        : action.content;
-
-    await writeFileSafe(action.absolutePath, content);
-  }
-
-  const linkBackups = [];
-  const linkCreated = [];
-
-  for (const { linkPath, targetPath } of linkEntries) {
-    const absoluteLinkPath = path.join(cwd, linkPath);
-    const absoluteTargetPath = path.join(cwd, targetPath);
-
-    if (!(await exists(absoluteTargetPath))) {
-      throw new Error(`missing link target: ${targetPath}`);
-    }
-
-    if (await isSymlinkTo(absoluteLinkPath, absoluteTargetPath)) {
-      continue;
-    }
-
-    if (await exists(absoluteLinkPath)) {
-      if (!force) {
-        throw new Error(
-          `cannot create symlink '${linkPath}' because path already exists. Re-run with --force to backup and replace. If symlink creation fails, see troubleshooting in docs/npm-consumer-quickstart.md.`
-        );
-      }
-      const backupPath = await createManagedPathBackup(absoluteLinkPath, {
-        cwd,
-        backupRoot,
-        maxPerFile: 20
-      });
-      linkBackups.push(backupPath);
-      // Ensure we remove the old path before symlinking if it's not already handled by backup
-      await fs.rm(absoluteLinkPath, { recursive: true, force: true });
-    }
-
-    const stat = await fs.lstat(absoluteTargetPath);
-    const type = process.platform === "win32" ? (stat.isDirectory() ? "junction" : "file") : (stat.isDirectory() ? "dir" : "file");
-    const linkTarget = process.platform === "win32" ? absoluteTargetPath : path.relative(path.dirname(absoluteLinkPath), absoluteTargetPath);
-
-    try {
-      await fs.mkdir(path.dirname(absoluteLinkPath), { recursive: true });
-      await fs.symlink(linkTarget, absoluteLinkPath, type);
-    } catch (error) {
-      throw new Error(
-        `failed to create symlink '${linkPath}' -> '${targetPath}' (${error.message}). ` +
-          "For Windows, enable Developer Mode or run terminal as Administrator. " +
-          "For Linux/macOS, verify write permissions in project root."
-      );
-    }
-    linkCreated.push(linkPath);
-  }
-
-  await setupInternalSymlinks(cwd, installRoot);
-
-  const opencodeResult = await mergeOpencodeConfig(cwd, { force, backupRoot });
-
-  const generatedIgnoreEntries = [
-    ".ai-workflow/",
-    ".ai-workflow-backups/",
-    "opencode.jsonc.backup.*",
-    ...linkEntries.flatMap((entry) => toIgnoreEntries(entry.linkPath))
-  ];
-
-  if (gemini) {
-    generatedIgnoreEntries.push(".gemini/");
-  }
-  if (codex) {
-    generatedIgnoreEntries.push(".agents/", ".codex/");
-  }
-  if (claude) {
-    generatedIgnoreEntries.push(".claude/");
-  }
-  if (antigravity) {
-    generatedIgnoreEntries.push(".agents/");
-  }
-
-  const gitignoreResult = await upsertGitignoreBlock(cwd, generatedIgnoreEntries);
-  const scriptInjected = await injectScripts(cwd);
-
-  if (platforms.length > 0) {
-    console.log("ai-workflow: migrating to native platforms...");
-    const agentsDir = path.join(cwd, installRoot, "opencode/agents");
-    const skillsDir = path.join(cwd, installRoot, "opencode/skills");
-
-    const agentFiles = (await fs.readdir(agentsDir).catch(() => []))
-      .filter((f) => f.endsWith(".md"))
-      .map((f) => path.join(agentsDir, f));
-
-    if (gemini) {
-      const adapter = new GeminiAdapter({ cwd });
-      
-      // Collect specialized skills from the new opencode/skills path
-      const skillFolders = await fs.readdir(skillsDir).catch(() => []);
-      const skillFiles = [];
-      for (const folder of skillFolders) {
-        const skillPath = path.join(skillsDir, folder, "SKILL.md");
-        if (await exists(skillPath)) {
-          skillFiles.push(skillPath);
-        }
-      }
-
-      const allFiles = [...agentFiles, ...skillFiles];
-      const transformed = await Promise.all(allFiles.map((f) => adapter.transform(f)));
-      await adapter.deploy(transformed, installRoot);
-      console.log(`- gemini: deployed AI Workflow Kit agents to .gemini/ (native discovery enabled)`);
-    }
-
-    if (claude) {
-      const adapter = new ClaudeAdapter({ cwd });
-      await adapter.deploy(installRoot);
-      console.log("- claude: deployed AI Workflow Kit agents to CLAUDE.md and .claude/rules/ (native discovery enabled)");
-    }
-
-    if (codex) {
-      const adapter = new CodexAdapter({ cwd });
-      await adapter.deploy(installRoot);
-      console.log("- codex: deployed AI Workflow Kit agents to .agents/, .codex/, and .github/ (native discovery enabled)");
-    }
-
-    if (antigravity) {
-      const adapter = new AntigravityAdapter({ cwd });
-      
-      // Collect specialized skills from the new opencode/skills path
-      const skillFolders = await fs.readdir(skillsDir).catch(() => []);
-      const skillFiles = [];
-      for (const folder of skillFolders) {
-        const skillPath = path.join(skillsDir, folder, "SKILL.md");
-        if (await exists(skillPath)) {
-          skillFiles.push(skillPath);
-        }
-      }
-
-      const allFiles = [...agentFiles, ...skillFiles];
-      const transformed = await Promise.all(allFiles.map((f) => adapter.transform(f)));
-      await adapter.deploy(transformed, installRoot);
-      console.log(`- antigravity: deployed AI Workflow Kit agents to .agents/ (native discovery enabled)`);
-    }
-  }
-
-  console.log("Installation complete.");
-  console.log(`- profile: ${selectedProfile}`);
-
-  console.log(`- opencode.jsonc: ${opencodeResult.reason}`);
-  console.log(`- .gitignore: ${gitignoreResult}`);
-  console.log(`- scripts: ${scriptInjected ? "injected 'validate'" : "already-up-to-date"}`);
-  console.log(`- symlink layout: ${linkCreated.length > 0 ? `created ${linkCreated.length}` : "already-up-to-date"}`);
-  if (backups.length > 0) {
-    console.log(`- backups created: ${backups.length}`);
-    for (const filePath of backups) {
-      console.log(`  ${filePath}`);
-    }
-  }
-  if (linkBackups.length > 0) {
-    console.log(`- symlink backups created: ${linkBackups.length}`);
-    for (const filePath of linkBackups) {
-      console.log(`  ${filePath}`);
-    }
-  }
-  if (skipped.length > 0) {
-    console.log(`- conflicts skipped: ${skipped.length}`);
-    for (const relativePath of skipped) {
-      console.log(`  ${relativePath}`);
-    }
-  }
-  console.log(`- dependency install: ${noInstall ? "skipped (--no-install)" : "not managed in this step"}`);
-  console.log("Next steps:");
-  console.log("  npx @williambeto/ai-workflow doctor");
-}

package/src/commands/run.js

@@ -1,112 +0,0 @@
-import { BranchGate } from "../core/gates/branch-gate.js";
-import { SpecValidator } from "../core/sdd/validator.js";
-import { HandoffEngine } from "../core/handoff/handoff-engine.js";
-import { runCollectEvidence } from "./collect-evidence.js";
-import { QualityGuard } from "../core/validation/quality-guard.js";
-import { HealerEngine } from "../core/healing/healer-engine.js";
-import { createCliRemediationExecutor } from "../core/healing/cli-remediation-executor.js";
-import { isRecoverableGateFailure, isTerminalFailure } from "../core/statuses.js";
-import path from "node:path";
-import fs from "node:fs/promises";
-import { getWorkflowProfile, resolveWorkflowProfile } from "../core/workflow-profiles.js";
-
-function normalizeTaskSlugFromSpec(specPath) {
-  const normalized = String(specPath).replaceAll("\\", "/");
-  const marker = "/docs/workflows/";
-  const index = normalized.includes(marker)
-    ? normalized.indexOf(marker) + marker.length
-    : normalized.startsWith("docs/workflows/") ? "docs/workflows/".length : -1;
-  if (index >= 0) {
-    const slug = normalized.slice(index).split("/")[0];
-    if (slug) return slug;
-  }
-  return path.basename(specPath, path.extname(specPath));
-}
-
-function combineValidation(evidence, quality) {
-  const statuses = [evidence.internalStatus, quality.overallStatus];
-  let overallStatus = "PASS";
-  if (statuses.includes("BLOCKED")) overallStatus = "BLOCKED";
-  else if (statuses.includes("FAIL")) overallStatus = "FAIL";
-  else if (statuses.includes("FAIL_DELEGATION_GATE")) overallStatus = "FAIL_DELEGATION_GATE";
-  else if (statuses.includes("FAIL_QUALITY_GATE")) overallStatus = "FAIL_QUALITY_GATE";
-  else if (statuses.includes("PASS_WITH_NOTES")) overallStatus = "PASS_WITH_NOTES";
-  return { overallStatus, evidence, quality };
-}
-
-/**
- * Coordinates branch safety, specification validation, observed validation, bounded remediation, and handoff.
- * Failed required validation can never be promoted to success.
- */
-export async function runMasterOrchestrator({ cwd, specPath, override, remediationExecutor = null }) {
-  console.log("\n[AI WORKFLOW] Starting evidence-backed orchestration...\n");
-
-  const branchGate = new BranchGate({ memoryDir: path.join(cwd, ".ai-workflow"), cwd });
-  const taskSlug = specPath ? normalizeTaskSlugFromSpec(specPath) : "implementation";
-  const gateResult = branchGate.check(override, { autoRecover: true, taskSlug });
-  if (gateResult.blocked) throw new Error(`[GATE BLOCKED] ${gateResult.reason}`);
-  console.log(`[PASS] Branch Gate: ${gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : `${gateResult.branch} is authorized`}.`);
-
-  if (!specPath) throw new Error("[SDD BLOCKED] Missing --spec-path. An approved specification is required.");
-
-  const validator = new SpecValidator();
-  const absoluteSpecPath = path.isAbsolute(specPath) ? specPath : path.join(cwd, specPath);
-  const validation = await validator.validate(absoluteSpecPath);
-  if (!validation.valid) throw new Error(`[SDD BLOCKED] Specification is not ready: ${validation.reason}`);
-
-  const executionMode = validation.tier === "deep" ? "full" : validation.tier === "tiny" ? "quick" : "standard";
-  const specContent = await fs.readFile(absoluteSpecPath, "utf8");
-  const workflowProfile = resolveWorkflowProfile({ request: specContent });
-  const profileDefinition = getWorkflowProfile(workflowProfile);
-  console.log(`[PASS] Specification: ${validation.tier.toUpperCase()} spec is APPROVED.`);
-  console.log(`[PROFILE] ${workflowProfile} -> ${profileDefinition.owner}; skills: ${profileDefinition.skills.join(", ") || "none"}.`);
-
-  const validateWorkflow = async () => {
-    const evidence = await runCollectEvidence({
-      cwd,
-      exitOnError: false,
-      taskSlug,
-      mode: executionMode,
-      profile: workflowProfile,
-      branchRecovery: gateResult.recovered ? `${gateResult.branchBefore} -> ${gateResult.branch}` : "NOT_REQUIRED"
-    });
-    const quality = await new QualityGuard({ cwd, taskSlug, mode: executionMode }).verify();
-    return combineValidation(evidence, quality);
-  };
-
-  let result = await validateWorkflow();
-  if (isRecoverableGateFailure(result.overallStatus)) {
-    console.log(`\n[REMEDIATION REQUIRED] ${result.overallStatus}. Starting bounded ${executionMode} remediation.`);
-    // Use the provided executor (programmatic API) or fall back to the default CLI executor.
-    // The CLI executor re-runs failed npm scripts; it does not modify source code.
-    const executor = typeof remediationExecutor === "function"
-      ? remediationExecutor
-      : createCliRemediationExecutor(cwd);
-    const healer = new HealerEngine({ cwd, mode: executionMode, taskSlug });
-    result = await healer.run({ initialResult: result, validate: validateWorkflow, remediate: executor });
-  }
-
-  if (isTerminalFailure(result.overallStatus)) {
-    throw new Error(`[WORKFLOW BLOCKED] ${result.overallStatus}: ${result.reason || "Validation could not be resolved safely."}`);
-  }
-  if (isRecoverableGateFailure(result.overallStatus)) {
-    throw new Error(`[WORKFLOW BLOCKED] Unresolved gate status after remediation: ${result.overallStatus}`);
-  }
-
-  console.log("\n--- Final Handoff ---");
-  const handoffEngine = new HandoffEngine({ cwd });
-  const handoffPath = await handoffEngine.generate({
-    taskId: path.basename(specPath, ".md"),
-    status: result.overallStatus,
-    specPaths: [specPath],
-    evidence: result.evidence,
-    nextActions: `Profile ${workflowProfile}. Observed validation completed. Ready for review or explicitly approved release actions.`
-  });
-
-  console.log(`\n[AI WORKFLOW COMPLETE] ${result.overallStatus}`);
-  if (result.remediation?.attempts) console.log(`Remediation attempts: ${result.remediation.attempts}`);
-  console.log(`Handoff Packet: ${path.relative(cwd, handoffPath)}\n`);
-  return { ...result, workflowProfile };
-}
-
-export { combineValidation };

package/src/core/backup.js

@@ -1,65 +0,0 @@
-import fs from "node:fs/promises";
-import path from "node:path";
-
-export function buildBackupPath(filePath, now = new Date()) {
-  const stamp = now.toISOString().replace(/[:.]/g, "-");
-  return `${filePath}.bak.${stamp}`;
-}
-
-export async function createBackup(filePath) {
-  const backupPath = buildBackupPath(filePath);
-  await fs.copyFile(filePath, backupPath);
-  return backupPath;
-}
-
-function escapeRelativePath(relativePath) {
-  return relativePath.replace(/[\\/]/g, "__");
-}
-
-export async function createManagedBackup(filePath, { cwd, backupRoot, maxPerFile = 20 }) {
-  const relativePath = path.relative(cwd, filePath);
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const backupName = `${escapeRelativePath(relativePath)}.${stamp}.bak`;
-  const absoluteBackupRoot = path.join(cwd, backupRoot);
-  const backupPath = path.join(absoluteBackupRoot, backupName);
-
-  await fs.mkdir(absoluteBackupRoot, { recursive: true });
-  await fs.copyFile(filePath, backupPath);
-
-  const prefix = `${escapeRelativePath(relativePath)}.`;
-  const entries = await fs.readdir(absoluteBackupRoot);
-  const matching = entries
-    .filter((entry) => entry.startsWith(prefix) && entry.endsWith(".bak"))
-    .sort();
-
-  if (matching.length > maxPerFile) {
-    const excess = matching.slice(0, matching.length - maxPerFile);
-    await Promise.all(excess.map((entry) => fs.unlink(path.join(absoluteBackupRoot, entry))));
-  }
-
-  return backupPath;
-}
-
-export async function createManagedPathBackup(targetPath, { cwd, backupRoot, maxPerFile = 20 }) {
-  const relativePath = path.relative(cwd, targetPath);
-  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-  const backupName = `${escapeRelativePath(relativePath)}.${stamp}.bak`;
-  const absoluteBackupRoot = path.join(cwd, backupRoot);
-  const backupPath = path.join(absoluteBackupRoot, backupName);
-
-  await fs.mkdir(absoluteBackupRoot, { recursive: true });
-  await fs.rename(targetPath, backupPath);
-
-  const prefix = `${escapeRelativePath(relativePath)}.`;
-  const entries = await fs.readdir(absoluteBackupRoot);
-  const matching = entries
-    .filter((entry) => entry.startsWith(prefix) && entry.endsWith(".bak"))
-    .sort();
-
-  if (matching.length > maxPerFile) {
-    const excess = matching.slice(0, matching.length - maxPerFile);
-    await Promise.all(excess.map((entry) => fs.rm(path.join(absoluteBackupRoot, entry), { recursive: true, force: true })));
-  }
-
-  return backupPath;
-}

package/src/core/completion-contract.js

@@ -1,35 +0,0 @@
-/**
- * Evaluates objective owner-output completeness. It does not judge visual taste.
- * A caller may resume the same owner once; a second incomplete result must block.
- */
-export function evaluateOwnerCompletion({
-  expectedFiles = [],
-  existingFiles = [],
-  validation = {},
-  ownerReportComplete = false,
-  resumeCount = 0
-} = {}) {
-  const existing = new Set(existingFiles);
-  const missingFiles = expectedFiles.filter((file) => !existing.has(file));
-  const missingValidation = Object.entries(validation)
-    .filter(([, value]) => value === "REQUIRED" || value === false)
-    .map(([key]) => key);
-  const missing = [
-    ...missingFiles.map((file) => `file:${file}`),
-    ...missingValidation.map((check) => `validation:${check}`),
-    ...(!ownerReportComplete ? ["owner-report"] : [])
-  ];
-
-  if (missing.length === 0) {
-    return { status: "PASS", action: "continue", missing: [] };
-  }
-  if (resumeCount < 1) {
-    return { status: "INCOMPLETE", action: "resume-same-owner", missing };
-  }
-  return {
-    status: "BLOCKED",
-    action: "stop",
-    reason: "Owner output remained incomplete after one resume",
-    missing
-  };
-}