@williambeto/ai-workflow 1.19.1 → 2.1.0

package/src/adapters/platforms/gemini.js

@@ -0,0 +1,232 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { COMPLETION_STATUS_TEXT } from "../../core/statuses.js";
+
+/**
+ * Maps OpenCode agent names to primary agent roles.
+ * @type {Record<string, string>}
+ */
+const PERSONA_MAPPING = {
+  "atlas": "Atlas",
+  "orion": "Orion",
+  "sage": "Sage",
+  "nexus": "Nexus",
+  "astra": "Astra",
+  "sage-validation": "Sage",
+  "orion-release": "Orion",
+  "orion-deploy": "Orion",
+  "nexus-discovery": "Nexus",
+  "phoenix": "Phoenix"
+};
+
+/**
+ * Gemini Adapter - Transforms OpenCode .md to Gemini Skill format and manages .gemini/ integration.
+ */
+export class GeminiAdapter {
+  constructor({ cwd }) {
+    this.cwd = cwd;
+  }
+
+  /**
+   * Transforms an OpenCode agent or specialized skill file to a Gemini Skill.
+   * @param {string} filePath - Path to the source .md file.
+   * @returns {Promise<{content: string, name: string}>}
+   */
+  async transform(filePath) {
+    const content = await fs.readFile(filePath, "utf8");
+    const fileName = path.basename(filePath, ".md") === "SKILL" 
+      ? path.basename(path.dirname(filePath)) 
+      : path.basename(filePath, ".md");
+      
+    const persona = PERSONA_MAPPING[fileName.toLowerCase()] || "Astra";
+    
+    // Check if already has frontmatter
+    if (content.trim().startsWith("---")) {
+      return { content, name: fileName };
+    }
+
+    // Extract description from the first paragraph after the title
+    const descriptionMatch = content.match(/^# .*\n\n(.*)/m);
+    const description = descriptionMatch ? descriptionMatch[1].trim() : `Specialized agent for ${fileName}.`;
+
+    const skillContent = `---
+name: ${fileName}
+description: ${description}
+---
+# ${persona} Persona
+
+${content}
+
+##  Completion Contract (Mandatory)
+Every task completion MUST provide the following payload:
+1. **Status**: ${COMPLETION_STATUS_TEXT}
+2. **Scope reviewed**: Brief summary of what was analyzed.
+3. **Findings**: Evidence-based discoveries.
+4. **Files affected**: List of all concrete paths modified or created.
+5. **Validation/evidence**: Commands run and their results.
+6. **Risks/notes**: Any caveats or technical debt introduced.
+7. **Required manager action**: Clear next step for the orchestrator.
+8. **Can manager continue**: [yes/no]
+`;
+
+    return {
+      content: skillContent,
+      name: fileName
+    };
+  }
+
+  /**
+   * Deploys transformed skills and agents to their respective directories.
+   * Also orchestrates the .gemini/ native integration.
+   */
+  async deploy(transformedItems, installRoot = ".ai-workflow") {
+    const agentsDir = path.join(this.cwd, installRoot, "opencode/agents");
+    const skillsDir = path.join(this.cwd, installRoot, "opencode/skills");
+    const geminiDir = path.join(this.cwd, ".gemini");
+    
+    await fs.mkdir(agentsDir, { recursive: true });
+    await fs.mkdir(skillsDir, { recursive: true });
+
+    for (const item of transformedItems) {
+      const isAgent = PERSONA_MAPPING[item.name.toLowerCase()];
+      const targetDir = isAgent ? agentsDir : path.join(skillsDir, item.name);
+      const fileName = isAgent ? `${item.name}.md` : "SKILL.md";
+      
+      const absoluteTargetDir = isAgent ? agentsDir : targetDir;
+      await fs.mkdir(absoluteTargetDir, { recursive: true });
+      await fs.writeFile(path.join(absoluteTargetDir, fileName), item.content);
+    }
+    
+    // Deploy native Gemini CLI extensions (.gemini/)
+    await this.deployNativeExtensions(installRoot);
+
+    // Also deploy root GEMINI.md if it doesn't exist
+    await this.deployInstructions();
+  }
+
+  /**
+   * Orchestrates the .gemini/ directory with copies of .ai-workflow/ assets.
+   * Using hard copies instead of symlinks ensures native discovery across all platforms.
+   */
+  async deployNativeExtensions(installRoot = ".ai-workflow") {
+    const geminiDir = path.join(this.cwd, ".gemini");
+    const geminiAgents = path.join(geminiDir, "agents");
+    const geminiSkills = path.join(geminiDir, "skills");
+    const geminiCommands = path.join(geminiDir, "commands");
+
+    await fs.mkdir(geminiAgents, { recursive: true });
+    await fs.mkdir(geminiSkills, { recursive: true });
+    await fs.mkdir(geminiCommands, { recursive: true });
+
+    // 1. Copy Agents
+    const sourceAgentsDir = path.join(this.cwd, installRoot, "opencode/agents");
+    const agentFiles = await fs.readdir(sourceAgentsDir).catch(() => []);
+    for (const file of agentFiles) {
+      if (!file.endsWith(".md")) continue;
+      const content = await fs.readFile(path.join(sourceAgentsDir, file), "utf8");
+      await fs.writeFile(path.join(geminiAgents, file), content);
+    }
+
+    // 2. Copy Skills
+    const sourceSkillsDir = path.join(this.cwd, installRoot, "opencode/skills");
+    const skillFolders = await fs.readdir(sourceSkillsDir).catch(() => []);
+    for (const folder of skillFolders) {
+      const skillSource = path.join(sourceSkillsDir, folder, "SKILL.md");
+      if (await this.exists(skillSource)) {
+        await fs.mkdir(path.join(geminiSkills, folder), { recursive: true });
+        const content = await fs.readFile(skillSource, "utf8");
+        await fs.writeFile(path.join(geminiSkills, folder, "SKILL.md"), content);
+      }
+    }
+
+    // 3. Copy Commands (from dist-assets/commands)
+    const sourceCommandsDir = path.join(this.cwd, installRoot, "opencode/commands");
+    if (await this.exists(sourceCommandsDir)) {
+      const commandFiles = await fs.readdir(sourceCommandsDir).catch(() => []);
+      for (const file of commandFiles) {
+        if (!file.endsWith(".md") && !file.endsWith(".toml")) continue;
+        const content = await fs.readFile(path.join(sourceCommandsDir, file), "utf8");
+        await fs.writeFile(path.join(geminiCommands, file), content);
+      }
+    }
+
+    // 4. Inject project settings.json
+    const settingsPath = path.join(geminiDir, "settings.json");
+    if (!(await this.exists(settingsPath))) {
+      const settings = {
+        model: { name: "auto" },
+        ui: { theme: "Ayu" }
+      };
+      await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2));
+    }
+  }
+
+  async exists(p) {
+    try {
+      await fs.access(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Deploys the main GEMINI.md and .geminiignore instructions to the project root.
+   */
+  async deployInstructions() {
+    const targetPath = path.join(this.cwd, "GEMINI.md");
+    const ignorePath = path.join(this.cwd, ".geminiignore");
+    
+    // Deploy GEMINI.md if it doesn't exist
+    try {
+      await fs.access(targetPath);
+    } catch {
+      const instructions = `# AI Workflow Kit - Engineering Governance
+
+## Mandate: Atlas Authority Protocol
+All architectural changes must align with the specifications issued by the **Specification Authority** (./specs).
+
+## Ternary Architecture
+- **Root:** Orchestration and config.
+- **.ai-workflow/:** Implementation (The Muscle).
+- **./specs:** Specifications (The Brain).
+
+## Branch Gates
+- **main Branch:** READ-ONLY.
+- **Validation:** Merges require successful observed validation; full/release workflows may persist EVIDENCE.json.
+
+## Primary Agents
+- **Atlas (Orchestrator)**
+- **Orion (Strategist)**
+- **Sage (Auditor)**
+- **Nexus (Spec Architect)**
+- **Astra (Developer)**
+- **Phoenix (Healer)**
+
+## Operational Preferences
+- Use \`token-economy\` and \`minimal-context\` skills.
+- **Native Discovery**: This project uses workspace-specific extensions in \`.gemini/\`.
+- **Workflow Entry**: Use \`/atlas\` to begin any task.
+`;
+      await fs.writeFile(targetPath, instructions);
+    }
+
+    // Deploy .geminiignore if it doesn't exist
+    try {
+      await fs.access(ignorePath);
+    } catch {
+      const ignoreContent = `.ai-workflow/
+.ai-workflow-backups/
+node_modules/
+.git/
+EVIDENCE.json
+*.tgz
+*.zip
+*.tar
+.gemini/tmp/
+.gemini/history/
+`;
+      await fs.writeFile(ignorePath, ignoreContent);
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,96 @@
+import { getPackageVersion } from "./core/package-assets.js";
+import { runInit } from "./commands/init.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runCollectEvidence } from "./commands/collect-evidence.js";
+import { runMasterOrchestrator } from "./commands/run.js";
+
+function printHelp() {
+  console.log(`ai-workflow
+
+Usage:
+  ai-workflow run --spec-path=<path>
+  ai-workflow init [--yes] [--force] [--dry-run] [--no-install] [--no-overwrite] [--gemini] [--claude] [--codex] [--profile=<profile>]
+  ai-workflow collect-evidence [--task=<slug>] [--mode=<quick|standard|full>] [--dry-run]
+  ai-workflow doctor
+
+Commands:
+  run               Proportionate orchestrator with branch safety, validation, and bounded remediation
+  init              Install AI workflow defaults (OpenCode). --profile=standard (default) or --profile=full (adds examples)
+  collect-evidence  Run observed project validation; persists EVIDENCE.json only for full mode
+  doctor            Verify local ai-workflow installation
+`);
+}
+
+function parseFlags(args) {
+  const specPathArg = args.find((arg) => arg.startsWith("--spec-path="));
+  const profileEqArg = args.find((arg) => arg.startsWith("--profile="));
+  const taskArg = args.find((arg) => arg.startsWith("--task="));
+  const modeArg = args.find((arg) => arg.startsWith("--mode="));
+  const profileIdx = args.indexOf("--profile");
+  const profileVal = profileEqArg
+    ? profileEqArg.replace("--profile=", "")
+    : profileIdx >= 0 && profileIdx + 1 < args.length && !args[profileIdx + 1].startsWith("--")
+      ? args[profileIdx + 1]
+      : undefined;
+
+  return {
+    yes: args.includes("--yes"),
+    force: args.includes("--force"),
+    dryRun: args.includes("--dry-run"),
+    noInstall: args.includes("--no-install"),
+    noOverwrite: args.includes("--no-overwrite"),
+    gemini: args.includes("--gemini"),
+    claude: args.includes("--claude"),
+    codex: args.includes("--codex"),
+    "dev-mode": args.includes("--dev-mode"),
+    specPath: specPathArg ? specPathArg.replace("--spec-path=", "") : undefined,
+    profile: profileVal || undefined,
+    taskSlug: taskArg ? taskArg.replace("--task=", "") : undefined,
+    mode: modeArg ? modeArg.replace("--mode=", "") : undefined
+  };
+}
+
+
+export async function runCli(args) {
+  const [command] = args;
+
+  if (command === "--version" || command === "-v") {
+    console.log(getPackageVersion() || "unknown");
+    return;
+  }
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp();
+    return;
+  }
+
+  if (command === "run") {
+    await runMasterOrchestrator({
+      cwd: process.cwd(),
+      ...parseFlags(args.slice(1))
+    });
+    return;
+  }
+
+  if (command === "init") {
+    await runInit({
+      cwd: process.cwd(),
+      ...parseFlags(args.slice(1))
+    });
+    return;
+  }
+
+  if (command === "collect-evidence") {
+    const flags = parseFlags(args.slice(1));
+    if (flags.mode && !["quick", "standard", "full"].includes(flags.mode)) throw new Error("--mode must be quick, standard, or full");
+    await runCollectEvidence({ cwd: process.cwd(), taskSlug: flags.taskSlug, mode: flags.mode, dryRun: flags.dryRun });
+    return;
+  }
+
+  if (command === "doctor") {
+    await runDoctor({ cwd: process.cwd() });
+    return;
+  }
+
+  throw new Error(`unknown command: ${command}`);
+}

package/src/commands/collect-evidence.js

@@ -0,0 +1,61 @@
+import { EvidenceCollector } from "../core/validation/evidence-collector.js";
+import { QualityGuard } from "../core/validation/quality-guard.js";
+import { buildDeliverySummary, formatDeliverySummary } from "../core/validation/canonical-finalization.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+function 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");
+}
+
+function addScriptTask(tasks, scripts, name, command, { rejectNoOp = false } = {}) {
+  const script = scripts[name];
+  if (!script) return;
+  if (!rejectNoOp && name === "test" && isNoOpScript(script)) return;
+  if (rejectNoOp && 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 });
+}
+
+function isManagedValidationPath(file = "") {
+  return /(^|\/)(node_modules|vendor|dist|coverage|\.cache)(\/|$)/.test(String(file).replaceAll("\\", "/"));
+}
+
+export async function runCollectEvidence({ cwd, exitOnError = true, taskSlug = null, mode = null, dryRun = false, profile = "generic", branchRecovery = "NOT_RECORDED" }) {
+  const tasks = [];
+  const qualityGuard = new QualityGuard({ cwd, taskSlug, mode });
+  try {
+    const pkg = JSON.parse(await fs.readFile(path.join(cwd, "package.json"), "utf8"));
+    const scripts = pkg.scripts || {};
+    const executableBehavior = await qualityGuard.hasExecutableBehaviorChanges();
+    addScriptTask(tasks, scripts, "lint", "npm run lint");
+    addScriptTask(tasks, scripts, "test", "npm test", { rejectNoOp: executableBehavior });
+    addScriptTask(tasks, scripts, "build", "npm run build");
+    addScriptTask(tasks, scripts, "typecheck", "npm run typecheck");
+    if (scripts.validate && !String(scripts.validate).includes("ai-workflow collect-evidence")) addScriptTask(tasks, scripts, "validate", "npm run validate");
+
+    const changed = qualityGuard.getChangedFiles().filter((file) => !isManagedValidationPath(file));
+    const hasTs = changed.some((file) => /\.(ts|tsx)$/.test(file)) || await fs.access(path.join(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 {
+    // Non-Node projects can still supply validation through project-specific commands.
+  }
+
+  const persist = !dryRun && mode === "full";
+  const collector = new EvidenceCollector({ cwd, timeout: 60000, taskSlug, mode, profile, branchRecovery });
+  const evidence = await collector.collect(tasks, { writeArtifact: persist });
+  const summary = buildDeliverySummary({ evidence });
+
+  console.log("\n--- Delivery Summary ---");
+  console.log(formatDeliverySummary(summary));
+  console.log(persist ? "\nArtifact: EVIDENCE.json" : "\nArtifact: NOT_REQUIRED for quick/standard mode");
+  console.log(`Commands processed: ${evidence.commands.length}\n`);
+
+  if (evidence.status === "BLOCKED" && exitOnError) process.exit(1);
+  return evidence;
+}

package/src/commands/doctor.js

@@ -0,0 +1,186 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { exists, readJson, readJsonc } from "../core/filesystem.js";
+
+const REQUIRED_FILES = [
+  ".ai-workflow",
+  "opencode/README.md"
+];
+
+async function isSymlink(filePath) {
+  try {
+    const stat = await fs.lstat(filePath);
+    return stat.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
+export async function runDoctor({ cwd }) {
+  let hasFailure = false;
+  let hasWarning = false;
+  let managedBlocks = [];
+
+  console.log("Doctor report:");
+
+  for (const relativePath of REQUIRED_FILES) {
+    const ok = await exists(path.join(cwd, relativePath));
+
+    if (ok) {
+      console.log(`PASS ${relativePath}`);
+    } else {
+      hasFailure = true;
+      console.log(`FAIL ${relativePath} missing`);
+    }
+  }
+
+  const configPathV2 = path.join(cwd, ".ai-workflow/config.json");
+  const configPathLegacy = path.join(cwd, ".ai-workflow.json");
+  let configPath = null;
+
+  if (await exists(configPathV2)) {
+    configPath = configPathV2;
+  } else if (await exists(configPathLegacy)) {
+    configPath = configPathLegacy;
+  }
+
+  if (configPath) {
+    try {
+      const config = await readJson(configPath);
+
+      if (config.installMode === "project-local" || config.mode === "standalone") {
+        console.log("PASS install mode is project-local/standalone");
+      } else {
+        hasWarning = true;
+        console.log(`WARN install mode is not project-local/standalone in ${path.basename(configPath)}`);
+      }
+
+      if (config.profile) {
+        console.log(`PASS profile detected: ${config.profile}`);
+      } else {
+        hasWarning = true;
+        console.log(`WARN profile is missing in ${path.basename(configPath)}`);
+      }
+
+      if (config.runtime) {
+        console.log(`PASS runtime: ${config.runtime}`);
+      } else {
+        console.log(`NOTE runtime field not present in ${path.basename(configPath)}`);
+      }
+
+      if (Array.isArray(config.managedBlocks)) {
+        managedBlocks = config.managedBlocks;
+      } else {
+        console.log(`NOTE managedBlocks not present in ${path.basename(configPath)} (legacy field)`);
+      }
+
+      if (Array.isArray(config.managedFiles)) {
+        for (const relativePath of config.managedFiles) {
+          const fileExists = await exists(path.join(cwd, relativePath));
+          if (!fileExists) {
+            hasWarning = true;
+            console.log(`WARN managed file missing: ${relativePath}`);
+          }
+        }
+      }
+
+      if (Array.isArray(config.managedLinks)) {
+        for (const relativePath of config.managedLinks) {
+          const absolutePath = path.join(cwd, relativePath);
+          const linkExists = await exists(absolutePath);
+          if (!linkExists) {
+            hasWarning = true;
+            console.log(`WARN managed link missing: ${relativePath}`);
+            continue;
+          }
+
+          const isLink = await isSymlink(absolutePath);
+          if (!isLink) {
+            hasWarning = true;
+            console.log(`WARN managed link is not a symlink: ${relativePath}`);
+          }
+        }
+      }
+    } catch {
+      hasFailure = true;
+      console.log(`FAIL ${path.basename(configPath)} is not valid JSON`);
+    }
+  }
+
+  const opencodePath = path.join(cwd, "opencode.jsonc");
+  if (!(await exists(opencodePath))) {
+    hasFailure = true;
+    console.log("FAIL opencode.jsonc missing");
+  } else {
+    try {
+      const opencodeConfig = await readJsonc(opencodePath);
+      console.log("PASS opencode.jsonc is valid JSONC");
+
+      const needsAgentDefault = managedBlocks.includes("opencode.jsonc:agent.default");
+      if (!needsAgentDefault || opencodeConfig.agent?.default) {
+        console.log("PASS opencode agent.default available");
+      } else {
+        hasFailure = true;
+        console.log("FAIL opencode agent.default missing");
+      }
+
+      const requiredCommands = managedBlocks
+        .filter((block) => block.startsWith("opencode.jsonc:command."))
+        .map((block) => block.replace("opencode.jsonc:command.", ""));
+
+      if (requiredCommands.length === 0) {
+        console.log("PASS no managed opencode commands required");
+      } else {
+        const missingCommands = requiredCommands.filter((command) => !opencodeConfig.command?.[command]);
+        if (missingCommands.length === 0) {
+          console.log(`PASS opencode managed commands available (${requiredCommands.length})`);
+        } else {
+          hasFailure = true;
+          console.log(`FAIL opencode command entries missing: ${missingCommands.join(", ")}`);
+        }
+      }
+
+      const requiredAgents = managedBlocks
+        .filter((block) => block.startsWith("opencode.jsonc:agent.") && !block.endsWith(".default"))
+        .map((block) => block.replace("opencode.jsonc:agent.", ""));
+
+      if (requiredAgents.length === 0) {
+        console.log("PASS no managed opencode agents required");
+      } else {
+        const missingAgents = requiredAgents.filter((agent) => !opencodeConfig.agent?.[agent]);
+        if (missingAgents.length === 0) {
+          console.log(`PASS opencode managed agents available (${requiredAgents.length})`);
+        } else {
+          hasFailure = true;
+          console.log(`FAIL opencode agent entries missing: ${missingAgents.join(", ")}`);
+        }
+      }
+    } catch {
+      hasFailure = true;
+      console.log("FAIL opencode.jsonc is not valid JSONC");
+    }
+  }
+
+  const packageJsonPath = path.join(cwd, "package.json");
+  if (await exists(packageJsonPath)) {
+    try {
+      const packageJson = await readJson(packageJsonPath);
+      const scripts = packageJson.scripts ?? {};
+
+      if (!scripts.validate) {
+        hasWarning = true;
+        console.log("WARN package.json has no validate script");
+      }
+    } catch {
+      hasFailure = true;
+      console.log("FAIL package.json is not valid JSON");
+    }
+  }
+
+  const finalStatus = hasFailure ? "FAIL" : hasWarning ? "PASS_WITH_NOTES" : "PASS";
+  console.log(`Final status: ${finalStatus}`);
+
+  if (hasFailure) {
+    process.exitCode = 1;
+  }
+}