agent-workflow-kit-cli 1.2.1 → 1.3.0

package/dist/core/awos/runtime.js

@@ -0,0 +1,322 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { promises as fs } from "fs";
+import path from "path";
+import crypto from "crypto";
+import { exec } from "child_process";
+import { promisify } from "util";
+const execAsync = promisify(exec);
+const RUNS_DIR = ".agents/state/runs";
+/**
+ * Validates a DirectedWorkflowGraph to guarantee it is Acyclic and structurally correct.
+ */
+export function validateWorkflowGraph(graph) {
+    const nodeMap = new Map();
+    const adjList = new Map();
+    const inDegree = new Map();
+    for (const node of graph.nodes) {
+        nodeMap.set(node.id, node);
+        adjList.set(node.id, []);
+        inDegree.set(node.id, 0);
+    }
+    for (const edge of graph.edges) {
+        if (!nodeMap.has(edge.sourceId) || !nodeMap.has(edge.targetId)) {
+            throw new Error(`Edge references non-existent node: ${edge.sourceId} -> ${edge.targetId}`);
+        }
+        adjList.get(edge.sourceId).push(edge.targetId);
+        inDegree.set(edge.targetId, (inDegree.get(edge.targetId) || 0) + 1);
+    }
+    // 1. Cycle Detection using DFS
+    const visited = new Set();
+    const recStack = new Set();
+    function dfs(nodeId) {
+        visited.add(nodeId);
+        recStack.add(nodeId);
+        const neighbors = adjList.get(nodeId) || [];
+        for (const neighbor of neighbors) {
+            if (!visited.has(neighbor)) {
+                dfs(neighbor);
+            }
+            else if (recStack.has(neighbor)) {
+                // Exclude self-referencing retry/rollback configurations if explicit
+                const node = nodeMap.get(nodeId);
+                if (node?.type !== "retry" && node?.type !== "rollback") {
+                    throw new Error(`Cycle detected involving node: ${nodeId} -> ${neighbor}`);
+                }
+            }
+        }
+        recStack.delete(nodeId);
+    }
+    for (const node of graph.nodes) {
+        if (!visited.has(node.id)) {
+            dfs(node.id);
+        }
+    }
+    // 2. Fork/Join balance validation
+    const forkNodes = graph.nodes.filter((n) => n.type === "fork");
+    const joinNodes = graph.nodes.filter((n) => n.type === "join");
+    if (forkNodes.length !== joinNodes.length) {
+        throw new Error(`Fork/Join count mismatch. Forks: ${forkNodes.length}, Joins: ${joinNodes.length}`);
+    }
+}
+/**
+ * Helper to evaluate condition expressions.
+ */
+function evaluateCondition(expression, context) {
+    try {
+        // Simple sandbox execution for safe expressions
+        const keys = Object.keys(context);
+        const values = Object.values(context);
+        const fn = new Function(...keys, `return ${expression};`);
+        return !!fn(...values);
+    }
+    catch (err) {
+        console.warn(`Condition evaluation failed for '${expression}':`, err);
+        return false;
+    }
+}
+/**
+ * Workflow Runtime execution engine.
+ */
+export class WorkflowRuntime {
+    workspaceRoot;
+    runState;
+    constructor(workspaceRoot) {
+        this.workspaceRoot = workspaceRoot;
+    }
+    /**
+     * Initializes or resumes execution state file.
+     */
+    async initRunState(graph, initialCtx) {
+        const runId = "run_" + crypto.randomBytes(4).toString("hex");
+        this.runState = {
+            runId,
+            workflowId: graph.id,
+            status: "IDLE",
+            context: { ...initialCtx },
+            currentStepIndex: 0,
+            steps: graph.nodes.map((n) => ({
+                id: n.id,
+                name: n.name,
+                status: "PENDING",
+            })),
+        };
+        await this.persistState();
+    }
+    async persistState() {
+        const runDir = path.join(this.workspaceRoot, RUNS_DIR);
+        const runFile = path.join(runDir, `${this.runState.runId}.json`);
+        await fs.mkdir(runDir, { recursive: true });
+        await fs.writeFile(runFile, JSON.stringify(this.runState, null, 2), "utf8");
+    }
+    getRunState() {
+        return this.runState;
+    }
+    /**
+     * Runs the workflow graph execution loop.
+     */
+    async run(graph, initialContext = {}, options = {}) {
+        validateWorkflowGraph(graph);
+        await this.initRunState(graph, initialContext);
+        this.runState.status = "EXECUTING";
+        await this.persistState();
+        const nodeMap = new Map();
+        for (const node of graph.nodes) {
+            nodeMap.set(node.id, node);
+        }
+        const inDegree = new Map();
+        const parentsMap = new Map();
+        for (const n of graph.nodes) {
+            inDegree.set(n.id, 0);
+            parentsMap.set(n.id, []);
+        }
+        for (const edge of graph.edges) {
+            inDegree.set(edge.targetId, inDegree.get(edge.targetId) + 1);
+            parentsMap.get(edge.targetId).push(edge.sourceId);
+        }
+        // Nodes ready to execute
+        const queue = graph.nodes
+            .filter((n) => (inDegree.get(n.id) || 0) === 0)
+            .map((n) => n.id);
+        // Keep track of resolved step status
+        const stepStatuses = new Map();
+        for (const s of this.runState.steps) {
+            stepStatuses.set(s.id, "PENDING");
+        }
+        while (queue.length > 0) {
+            const nodeId = queue.shift();
+            const node = nodeMap.get(nodeId);
+            const stepIdx = this.runState.steps.findIndex((s) => s.id === nodeId);
+            this.runState.steps[stepIdx].status = "RUNNING";
+            this.runState.steps[stepIdx].startedAt = new Date().toISOString();
+            await this.persistState();
+            // Resolve role checks if configured
+            if (node.role) {
+                try {
+                    const { loadAWOSPlugins } = await import("./registry.js");
+                    const registry = await loadAWOSPlugins(this.workspaceRoot);
+                    const customRole = registry.roles.get(node.role);
+                    if (customRole) {
+                        console.log(`[AWOS Runtime] Custom Role '${node.role}' loaded for step '${node.name}'. Asserting hooks...`);
+                        if (customRole.hooks?.preStep) {
+                            const { getRepositoryContext } = await import("./intelligence.js");
+                            const { loadProfile } = await import("./profiles.js");
+                            const repoContext = await getRepositoryContext(this.workspaceRoot);
+                            const archProfile = await loadProfile(repoContext.architecture);
+                            const res = await customRole.hooks.preStep({
+                                runId: this.runState.runId,
+                                workspaceRoot: this.workspaceRoot,
+                                repoContext,
+                                profile: archProfile
+                            }, node);
+                            if (!res.proceed) {
+                                throw new Error(`Role preStep hook rejected execution: ${res.error || "Unknown rejection"}`);
+                            }
+                        }
+                    }
+                    else {
+                        const { RoleRegistry } = await import("./registry.js");
+                        const roleDef = await RoleRegistry.load(node.role, path.join(this.workspaceRoot, ".agents/roles"));
+                        console.log(`[AWOS Runtime] Role '${roleDef.id}' loaded for step '${node.name}'. Asserting responsibilities...`);
+                    }
+                }
+                catch (err) {
+                    console.log(`[AWOS Runtime] Warning: Active role metadata for '${node.role}' could not be loaded: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            try {
+                let success = true;
+                let outputs = {};
+                // Execute by step type
+                if (node.type === "task") {
+                    const executor = node.executor || "command";
+                    const params = node.params || {};
+                    const { loadAWOSPlugins } = await import("./registry.js");
+                    const registry = await loadAWOSPlugins(this.workspaceRoot);
+                    if (registry.executors.has(executor)) {
+                        if (options.dryRun) {
+                            console.log(`[Dry Run] Would execute custom executor '${executor}' with params:`, params);
+                            outputs = node.mockOutput || { log: "Custom dry run completed." };
+                        }
+                        else {
+                            const executeFn = registry.executors.get(executor);
+                            outputs = await executeFn(params, this.runState);
+                        }
+                    }
+                    else if (executor === "command" && params.command) {
+                        if (options.dryRun) {
+                            console.log(`[Dry Run] Would execute shell command: ${params.command}`);
+                            outputs = node.mockOutput || { log: "Dry run completed." };
+                        }
+                        else {
+                            const { stdout, stderr } = await execAsync(params.command, { cwd: this.workspaceRoot });
+                            outputs = { stdout, stderr };
+                        }
+                    }
+                    else if (executor === "adr-generate") {
+                        if (options.dryRun) {
+                            console.log(`[Dry Run] Would generate ADR: ${params.title || "Decision"}`);
+                            outputs = node.mockOutput || { adrId: "ADR-MOCK", status: "proposed" };
+                        }
+                        else {
+                            const { ADRService } = await import("./adr.js");
+                            const generated = await ADRService.create(this.workspaceRoot, {
+                                title: params.title || "Decision",
+                                status: params.status || "proposed",
+                                context: params.context || "",
+                                decision: params.decision || "",
+                                consequences: params.consequences || "",
+                                metadata: params.metadata || {},
+                            });
+                            outputs = { adrId: generated.id, status: generated.status };
+                            console.log(`[AWOS Runtime] Generated Architectural Decision Record: ${generated.id}`);
+                        }
+                    }
+                }
+                else if (node.type === "conditional") {
+                    const expression = node.params?.expression || "true";
+                    const evalResult = evaluateCondition(expression, this.runState.context);
+                    outputs = { conditionResult: evalResult };
+                }
+                else if (node.type === "approval") {
+                    // Pause execution and ask for human approval
+                    this.runState.steps[stepIdx].status = "WAITING_APPROVAL";
+                    this.runState.status = "PAUSED";
+                    await this.persistState();
+                    console.log(`\n⚠️ Workflow paused at step '${node.name}'. Requires human approval to resume.`);
+                    console.log(`Run 'awk run resume ${this.runState.runId}' to proceed.\n`);
+                    return this.runState; // Suspends execution
+                }
+                if (success) {
+                    stepStatuses.set(nodeId, "COMPLETED");
+                    this.runState.steps[stepIdx].status = "COMPLETED";
+                    this.runState.steps[stepIdx].outputs = outputs;
+                    this.runState.steps[stepIdx].completedAt = new Date().toISOString();
+                    // Merge outcomes into runtime context
+                    this.runState.context = {
+                        ...this.runState.context,
+                        [nodeId]: outputs,
+                    };
+                }
+                else {
+                    throw new Error(`Execution failed at node '${node.name}'`);
+                }
+            }
+            catch (err) {
+                stepStatuses.set(nodeId, "FAILED");
+                this.runState.steps[stepIdx].status = "FAILED";
+                this.runState.steps[stepIdx].completedAt = new Date().toISOString();
+                await this.persistState();
+                // Handle retry and rollback
+                if (node.rollbackNodeId) {
+                    console.warn(`Node failed. Triggering rollback node: ${node.rollbackNodeId}`);
+                    queue.push(node.rollbackNodeId);
+                }
+                else {
+                    this.runState.status = "FAILURE";
+                    await this.persistState();
+                    throw err;
+                }
+            }
+            await this.persistState();
+            // Find children next nodes to push to queue
+            const edges = graph.edges.filter((e) => e.sourceId === nodeId);
+            for (const edge of edges) {
+                const targetId = edge.targetId;
+                const targetNode = nodeMap.get(targetId);
+                // Verify if condition is met
+                if (node.type === "conditional" && edge.conditionExpression) {
+                    const condPassed = evaluateCondition(edge.conditionExpression, this.runState.context);
+                    if (!condPassed) {
+                        stepStatuses.set(targetId, "SKIPPED");
+                        const targetIdx = this.runState.steps.findIndex((s) => s.id === targetId);
+                        this.runState.steps[targetIdx].status = "SKIPPED";
+                        continue;
+                    }
+                }
+                // Check incoming paths dependency for JOIN nodes
+                if (targetNode.type === "join") {
+                    const parents = parentsMap.get(targetId) || [];
+                    const allParentsFinished = parents.every((p) => {
+                        const status = stepStatuses.get(p);
+                        return status === "COMPLETED" || status === "SKIPPED" || status === "FAILED";
+                    });
+                    if (allParentsFinished && !queue.includes(targetId)) {
+                        queue.push(targetId);
+                    }
+                }
+                else {
+                    if (!queue.includes(targetId)) {
+                        queue.push(targetId);
+                    }
+                }
+            }
+        }
+        const hasFailures = Array.from(stepStatuses.values()).includes("FAILED");
+        this.runState.status = hasFailures ? "FAILURE" : "SUCCESS";
+        await this.persistState();
+        return this.runState;
+    }
+}

package/dist/core/awos/types.js

@@ -0,0 +1,5 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+export {};

package/dist/core/config.js

@@ -0,0 +1,27 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { promises as fs } from "fs";
+import path from "path";
+let loadedConfig = null;
+let isLoaded = false;
+export async function loadConfig(cwd = process.cwd()) {
+    if (isLoaded) {
+        return loadedConfig || {};
+    }
+    const configPath = path.join(cwd, "awk.config.json");
+    try {
+        const content = await fs.readFile(configPath, "utf8");
+        loadedConfig = JSON.parse(content);
+    }
+    catch {
+        loadedConfig = {};
+    }
+    isLoaded = true;
+    return loadedConfig || {};
+}
+export function clearConfigCache() {
+    loadedConfig = null;
+    isLoaded = false;
+}

package/dist/core/parser.js

@@ -0,0 +1,143 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import ts from "typescript";
+import { execa } from "execa";
+function parseTsImports(content) {
+    const sourceFile = ts.createSourceFile("file.ts", content, ts.ScriptTarget.Latest, true);
+    const imports = [];
+    function visit(node) {
+        if (ts.isImportDeclaration(node)) {
+            if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+                imports.push(node.moduleSpecifier.text);
+            }
+        }
+        else if (ts.isExportDeclaration(node)) {
+            if (node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+                imports.push(node.moduleSpecifier.text);
+            }
+        }
+        else if (ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+            node.arguments.length > 0) {
+            const arg = node.arguments[0];
+            if (ts.isStringLiteral(arg)) {
+                imports.push(arg.text);
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return imports;
+}
+function fallbackPyImports(content) {
+    const lines = content.split("\n");
+    const imports = [];
+    let inMultiline = false;
+    let multilineQuote = "";
+    for (let line of lines) {
+        line = line.trim();
+        if (!line)
+            continue;
+        if (!inMultiline) {
+            if (line.startsWith('"""')) {
+                inMultiline = true;
+                multilineQuote = '"""';
+                if (line.endsWith('"""') && line.length > 3) {
+                    inMultiline = false;
+                }
+                continue;
+            }
+            if (line.startsWith("'''")) {
+                inMultiline = true;
+                multilineQuote = "'''";
+                if (line.endsWith("'''") && line.length > 3) {
+                    inMultiline = false;
+                }
+                continue;
+            }
+            const hashIdx = line.indexOf("#");
+            if (hashIdx !== -1) {
+                line = line.substring(0, hashIdx).trim();
+            }
+            const importFromMatch = line.match(/^from\s+([a-zA-Z0-9._]+)\s+import/);
+            if (importFromMatch) {
+                imports.push(importFromMatch[1]);
+            }
+            else {
+                const importMatch = line.match(/^import\s+([a-zA-Z0-9._\s,]+)/);
+                if (importMatch) {
+                    const modules = importMatch[1].split(",").map(m => m.trim());
+                    imports.push(...modules);
+                }
+            }
+        }
+        else {
+            if (line.endsWith(multilineQuote)) {
+                inMultiline = false;
+            }
+        }
+    }
+    return imports;
+}
+async function parsePyImports(content) {
+    const pyScript = `
+import ast, sys, json
+try:
+    tree = ast.parse(sys.stdin.read())
+    imports = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for name in node.names:
+                imports.append(name.name)
+        elif isinstance(node, ast.ImportFrom):
+            if node.module:
+                imports.append(node.module)
+    print(json.dumps(imports))
+except Exception:
+    sys.exit(1)
+  `.trim();
+    try {
+        const { stdout } = await execa("python", ["-c", pyScript], {
+            input: content,
+            timeout: 2000,
+        });
+        return JSON.parse(stdout);
+    }
+    catch {
+        return fallbackPyImports(content);
+    }
+}
+function parseJavaImports(content) {
+    const cleaned = content.replace(/\/\*[\s\S]*?\*\//g, "");
+    const lines = cleaned.split("\n");
+    const imports = [];
+    for (let line of lines) {
+        line = line.trim();
+        const doubleSlashIdx = line.indexOf("//");
+        if (doubleSlashIdx !== -1) {
+            line = line.substring(0, doubleSlashIdx).trim();
+        }
+        if (line.startsWith("import ")) {
+            const match = line.match(/^import\s+(?:static\s+)?([a-zA-Z0-9._*]+)\s*;/);
+            if (match) {
+                imports.push(match[1]);
+            }
+        }
+    }
+    return imports;
+}
+export async function parseImports(filePath, content) {
+    const ext = filePath.split(".").pop()?.toLowerCase();
+    if (ext === "ts" || ext === "tsx") {
+        return parseTsImports(content);
+    }
+    if (ext === "py") {
+        return parsePyImports(content);
+    }
+    if (ext === "java") {
+        return parseJavaImports(content);
+    }
+    return [];
+}

package/dist/core/renderer.js

@@ -6,6 +6,7 @@ import handlebars from "handlebars";
 import { promises as fs } from "fs";
 import path from "path";
 import { fileURLToPath } from "url";
+import { loadConfig } from "./config.js";
 // Register custom Handlebars helpers
 handlebars.registerHelper("eq", function (a, b) {
     return a === b;
@@ -14,13 +15,30 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 // The templates directory is located at '../../templates' relative to 'dist/core/renderer.js'
 const TEMPLATES_DIR = path.resolve(__dirname, "../../templates");
+/**
+ * Resolves the path of a template file, prioritizing the customTemplatesPath if configured.
+ */
+async function resolveTemplatePath(relativePath) {
+    const config = await loadConfig();
+    if (config.customTemplatesPath) {
+        const customFullPath = path.resolve(process.cwd(), config.customTemplatesPath, relativePath);
+        try {
+            await fs.access(customFullPath);
+            return customFullPath;
+        }
+        catch {
+            // Fallback to default
+        }
+    }
+    return path.join(TEMPLATES_DIR, relativePath);
+}
 /**
  * Loads a Handlebars template, compiles it, and renders it with the given context.
  * @param templatePath Relative path to the template inside the templates directory (e.g. 'common/AGENTS.md.hbs')
  * @param context Key-value context data for compilation
  */
 export async function renderTemplate(templatePath, context) {
-    const fullPath = path.join(TEMPLATES_DIR, templatePath);
+    const fullPath = await resolveTemplatePath(templatePath);
     const fileContent = await fs.readFile(fullPath, "utf8");
     const compiled = handlebars.compile(fileContent);
     return compiled(context);
@@ -31,7 +49,7 @@ export async function renderTemplate(templatePath, context) {
  * @param context Optional key-value data for compilation
  */
 export async function readStaticTemplateFile(filePath, context) {
-    const fullPath = path.join(TEMPLATES_DIR, filePath);
+    const fullPath = await resolveTemplatePath(filePath);
     const fileContent = await fs.readFile(fullPath, "utf8");
     if (context) {
         const compiled = handlebars.compile(fileContent);
@@ -43,38 +61,71 @@ export async function readStaticTemplateFile(filePath, context) {
  * Gets all rules files for a stack.
  */
 export async function getStackRules(stack) {
-    const rulesDir = path.join(TEMPLATES_DIR, stack, "rules");
+    const relativeRulesDir = path.join(stack, "rules");
+    const rules = new Set();
+    // Try custom first
+    const config = await loadConfig();
+    if (config.customTemplatesPath) {
+        const customRulesDir = path.resolve(process.cwd(), config.customTemplatesPath, relativeRulesDir);
+        try {
+            const files = await fs.readdir(customRulesDir);
+            for (const f of files) {
+                if (f.endsWith(".md"))
+                    rules.add(f);
+            }
+        }
+        catch {
+            // Ignore
+        }
+    }
+    // Fallback default
+    const defaultRulesDir = path.join(TEMPLATES_DIR, stack, "rules");
     try {
-        const files = await fs.readdir(rulesDir);
-        return files.filter((f) => f.endsWith(".md"));
+        const files = await fs.readdir(defaultRulesDir);
+        for (const f of files) {
+            if (f.endsWith(".md"))
+                rules.add(f);
+        }
     }
     catch {
-        return [];
+        // Ignore
     }
+    return Array.from(rules);
 }
 /**
  * Gets all skills for a stack.
  */
 export async function getStackSkills(stack) {
-    const skillsDir = path.join(TEMPLATES_DIR, stack, "skills");
-    try {
-        const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-        const skills = [];
-        for (const entry of entries) {
-            if (entry.isDirectory()) {
-                const skillFilePath = path.join(skillsDir, entry.name, "SKILL.md");
-                try {
-                    await fs.access(skillFilePath);
-                    skills.push(`${entry.name}/SKILL.md`);
-                }
-                catch {
-                    // Ignore if SKILL.md doesn't exist
+    const relativeSkillsDir = path.join(stack, "skills");
+    const skills = new Set();
+    const checkDir = async (dirPath) => {
+        try {
+            const entries = await fs.readdir(dirPath, { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isDirectory()) {
+                    const skillFilePath = path.join(dirPath, entry.name, "SKILL.md");
+                    try {
+                        await fs.access(skillFilePath);
+                        skills.add(`${entry.name}/SKILL.md`);
+                    }
+                    catch {
+                        // Ignore
+                    }
                 }
             }
         }
-        return skills;
-    }
-    catch {
-        return [];
+        catch {
+            // Ignore
+        }
+    };
+    // Check custom
+    const config = await loadConfig();
+    if (config.customTemplatesPath) {
+        const customSkillsDir = path.resolve(process.cwd(), config.customTemplatesPath, relativeSkillsDir);
+        await checkDir(customSkillsDir);
     }
+    // Check default
+    const defaultSkillsDir = path.join(TEMPLATES_DIR, stack, "skills");
+    await checkDir(defaultSkillsDir);
+    return Array.from(skills);
 }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "agent-workflow-kit-cli",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "AI-Ready Repository Workflow Generator & Guideline Optimizer for Codex and Antigravity",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
-    "agent-workflow-kit": "./dist/index.js"
+    "agent-workflow-kit": "./dist/index.js",
+    "agent-workflow-kit-cli": "./dist/index.js"
   },
   "files": [
     "dist",