agent-workflow-kit-cli 1.2.0 → 1.3.0

package/dist/cli/commands/workflow.js

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import chalk from "chalk";
+import { promises as fs } from "fs";
+import path from "path";
+import { WorkflowRegistry } from "../../core/awos/registry.js";
+import { WorkflowRuntime } from "../../core/awos/runtime.js";
+const DEFAULT_WORKFLOW_DIR = ".agents/workflows";
+export async function listWorkflows() {
+    const cwd = process.cwd();
+    console.log(chalk.bold.cyan("\n📋 Discovered AWOS Workflow Packs"));
+    console.log(chalk.dim("------------------------------------------"));
+    const dir = path.join(cwd, DEFAULT_WORKFLOW_DIR);
+    const list = await WorkflowRegistry.discover(dir);
+    if (list.length === 0) {
+        console.log(chalk.gray(`No workflows found under '${DEFAULT_WORKFLOW_DIR}/'.`));
+        return;
+    }
+    for (const wf of list) {
+        console.log(`${chalk.bold.green(`- ${wf.id}`)} v${wf.version} : ${wf.name}`);
+        console.log(chalk.gray(`  ${wf.description}`));
+        console.log(chalk.gray(`  Roles: ${wf.requiredRoles.join(", ")} | Architectures: ${wf.supportedArchitectures.join(", ")}\n`));
+    }
+}
+export async function showWorkflow(id) {
+    const cwd = process.cwd();
+    const dir = path.join(cwd, DEFAULT_WORKFLOW_DIR);
+    const wf = await WorkflowRegistry.load(id, dir);
+    console.log(chalk.bold.cyan(`\n🔍 Workflow Details: ${wf.id}`));
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(`${chalk.bold("Name:")}        ${wf.name}`);
+    console.log(`${chalk.bold("Version:")}     ${wf.version}`);
+    console.log(`${chalk.bold("Description:")} ${wf.description}`);
+    console.log(`${chalk.bold("Architectures:")} ${wf.supportedArchitectures.join(", ")}`);
+    console.log(`${chalk.bold("Required Roles:")} ${wf.requiredRoles.join(", ")}`);
+    console.log(chalk.dim("------------------------------------------"));
+    console.log(chalk.bold("Graph Execution Steps:"));
+    for (const node of wf.graph.nodes) {
+        const roleStr = node.role ? ` (Role: ${node.role})` : "";
+        const execStr = node.executor ? ` [Executor: ${node.executor}]` : "";
+        console.log(`  - [${node.type.toUpperCase()}] ${chalk.green(node.id)}: "${node.name}"${roleStr}${execStr}`);
+    }
+    console.log(chalk.dim("------------------------------------------\n"));
+}
+export async function validateWorkflow(id) {
+    const cwd = process.cwd();
+    const dir = path.join(cwd, DEFAULT_WORKFLOW_DIR);
+    try {
+        const wf = await WorkflowRegistry.load(id, dir);
+        WorkflowRegistry.validate(wf);
+        console.log(chalk.bold.green(`\n✔️ Workflow '${id}' is structurally valid and acyclic!`));
+    }
+    catch (err) {
+        console.error(chalk.bold.red(`\n❌ Workflow '${id}' is invalid:`));
+        console.error(chalk.red(`  ${err instanceof Error ? err.message : String(err)}`));
+        process.exit(1);
+    }
+}
+export async function runWorkflowById(id, options) {
+    const cwd = process.cwd();
+    const dir = path.join(cwd, DEFAULT_WORKFLOW_DIR);
+    const wf = await WorkflowRegistry.load(id, dir);
+    let inputs = {};
+    if (options.inputs) {
+        try {
+            const inputsPath = path.resolve(cwd, options.inputs);
+            const content = await fs.readFile(inputsPath, "utf8");
+            inputs = JSON.parse(content);
+        }
+        catch {
+            try {
+                inputs = JSON.parse(options.inputs);
+            }
+            catch (err) {
+                throw new Error(`Failed to parse inputs parameters: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    console.log(chalk.bold.cyan(`\n🚀 Executing Discovered Workflow: ${wf.id}`));
+    console.log(chalk.dim("------------------------------------------"));
+    const runtime = new WorkflowRuntime(cwd);
+    const result = await runtime.run(wf.graph, inputs, { dryRun: options.dryRun });
+    console.log(chalk.dim("\n------------------------------------------"));
+    if (result.status === "SUCCESS") {
+        console.log(chalk.bold.green(`✔️ Workflow execution succeeded! Run ID: ${result.runId}`));
+    }
+    else if (result.status === "PAUSED") {
+        console.log(chalk.bold.yellow(`⚠️ Workflow execution paused. Resume using: awk resume ${result.runId}`));
+    }
+    else {
+        console.log(chalk.bold.red(`❌ Workflow execution failed. Run ID: ${result.runId}`));
+    }
+}

package/dist/cli/index.js

@@ -9,12 +9,17 @@ import { runAdd } from "./commands/add.js";
 import { runSync } from "./commands/sync.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runExport } from "./commands/export.js";
+import { runWorkflowCommand, resumeWorkflowCommand } from "./commands/run.js";
+import { runProfileCheck } from "./commands/profile.js";
+import { listWorkflows, showWorkflow, validateWorkflow, runWorkflowById } from "./commands/workflow.js";
+import { listRoles, showRole, validateRoles } from "./commands/role.js";
+import { createAdrCommand, listAdrsCommand, showAdrCommand, searchAdrsCommand } from "./commands/adr.js";
 const program = new Command();
 export function runCli() {
     program
         .name("agent-workflow-kit")
         .description("Generate AI coding workflows/rules/templates for Codex and Antigravity")
-        .version("1.2.0");
+        .version("1.3.0");
     program
         .command("init")
         .description("Initialize agent guidelines and skills for the repository")
@@ -75,14 +80,200 @@ export function runCli() {
         .command("export <target>")
         .description("Export custom workflows/skills for the target agent (e.g., 'antigravity')")
         .option("--no-clipboard", "Do not copy the exported instructions to clipboard", false)
+        .option("-o, --output <file>", "Write the exported guidelines to a specific file")
         .action(async (target, options) => {
         try {
-            await runExport(target, { clipboard: options.clipboard });
+            await runExport(target, { clipboard: options.clipboard, output: options.output });
         }
         catch (err) {
             console.error(chalk.red(`Error running export: ${err instanceof Error ? err.message : String(err)}`));
             process.exit(1);
         }
     });
+    program
+        .command("run <workflow>")
+        .description("Execute an AWOS graph workflow")
+        .option("--inputs <inputs>", "Path to input JSON file or inline JSON string")
+        .option("--dry-run", "Execute workflow steps in simulation mode", false)
+        .action(async (workflow, options) => {
+        try {
+            await runWorkflowCommand(workflow, options);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error running workflow: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    program
+        .command("resume <runId>")
+        .description("Resume a suspended AWOS workflow")
+        .action(async (runId) => {
+        try {
+            await resumeWorkflowCommand(runId);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error resuming workflow: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    program
+        .command("profile")
+        .description("Validate directory architecture structure and rules boundaries")
+        .option("--profile <profile>", "Target profile name (e.g. clean-architecture)")
+        .action(async (options) => {
+        try {
+            await runProfileCheck(options);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error validation profile rules: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    // --- Workflow Group Subcommands ---
+    const workflowCmd = program.command("workflow").description("Manage and execute AWOS workflow packs");
+    workflowCmd
+        .command("list")
+        .description("List discovered workflow packs")
+        .action(async () => {
+        try {
+            await listWorkflows();
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    workflowCmd
+        .command("show <id>")
+        .description("Show workflow pack steps and metadata")
+        .action(async (id) => {
+        try {
+            await showWorkflow(id);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    workflowCmd
+        .command("validate <id>")
+        .description("Validate a workflow pack schema and graph cyclic constraints")
+        .action(async (id) => {
+        try {
+            await validateWorkflow(id);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    workflowCmd
+        .command("run <id>")
+        .description("Run a registered workflow pack by ID")
+        .option("--inputs <inputs>", "Path to inputs parameter JSON file or inline string")
+        .option("--dry-run", "Run nodes in dry-run mode", false)
+        .action(async (id, options) => {
+        try {
+            await runWorkflowById(id, options);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error running workflow: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    // --- Role Group Subcommands ---
+    const roleCmd = program.command("role").description("Manage agent role profiles");
+    roleCmd
+        .command("list")
+        .description("List all discovered role profiles in catalog")
+        .action(async () => {
+        try {
+            await listRoles();
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    roleCmd
+        .command("show <id>")
+        .description("Show agent role details, checklists and inputs schema")
+        .action(async (id) => {
+        try {
+            await showRole(id);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    roleCmd
+        .command("validate")
+        .description("Validate all roles catalog files schema parameters")
+        .action(async () => {
+        try {
+            await validateRoles();
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    // --- ADR Group Subcommands ---
+    const adrCmd = program.command("adr").description("Manage Architectural Decision Records");
+    adrCmd
+        .command("create")
+        .description("Create a new numbered architectural decision record (ADR)")
+        .option("--title <title>", "ADR decision title")
+        .option("--status <status>", "Initial status: proposed | accepted | rejected | superseded", "proposed")
+        .option("--context <context>", "Context background explanation")
+        .option("--decision <decision>", "Architectural decision detail statement")
+        .option("--consequences <consequences>", "Repercussions of decision taken")
+        .option("--decision-maker <maker>", "Role or name of decider", "AWOS System")
+        .action(async (options) => {
+        try {
+            await createAdrCommand(options);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    adrCmd
+        .command("list")
+        .description("List all saved ADR documents")
+        .action(async () => {
+        try {
+            await listAdrsCommand();
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    adrCmd
+        .command("show <id>")
+        .description("Display details of a numbered ADR document")
+        .action(async (id) => {
+        try {
+            await showAdrCommand(id);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
+    adrCmd
+        .command("search <keyword>")
+        .description("Search all ADR documents for keyword text matches")
+        .action(async (keyword) => {
+        try {
+            await searchAdrsCommand(keyword);
+        }
+        catch (err) {
+            console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            process.exit(1);
+        }
+    });
     program.parse(process.argv);
 }

package/dist/core/awos/adr.js

@@ -0,0 +1,208 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { promises as fs } from "fs";
+import path from "path";
+import Handlebars from "handlebars";
+const ADR_DIR = "docs/adr";
+const DEFAULT_TEMPLATE = `---
+id: {{id}}
+title: {{{title}}}
+status: {{status}}
+date: {{date}}
+{{#if metadata.decisionMakerRole}}
+decisionMakerRole: {{metadata.decisionMakerRole}}
+{{/if}}
+{{#if metadata.affectedModules}}
+affectedModules: {{#each metadata.affectedModules}}{{#if @index}}, {{/if}}{{this}}{{/each}}
+{{/if}}
+---
+
+# {{{title}}}
+
+## Context
+{{{context}}}
+
+## Decision
+{{{decision}}}
+
+## Consequences
+{{{consequences}}}
+`;
+export class ADRService {
+    /**
+     * Helper to parse a markdown ADR file back into a structured ADRDefinition.
+     */
+    static parseMarkdown(content, id) {
+        const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+        const match = content.match(frontmatterRegex);
+        let title = "Untitled ADR";
+        let status = 'proposed';
+        let date = new Date().toISOString().split("T")[0];
+        let body = content;
+        const metadata = {};
+        if (match) {
+            const frontmatter = match[1];
+            body = match[2];
+            const lines = frontmatter.split("\n");
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith("#"))
+                    continue;
+                const eqIdx = trimmed.indexOf(":");
+                if (eqIdx !== -1) {
+                    const key = trimmed.substring(0, eqIdx).trim();
+                    const value = trimmed.substring(eqIdx + 1).trim();
+                    if (key === "title")
+                        title = value.replace(/^['"]|['"]$/g, "");
+                    else if (key === "status") {
+                        const parsedStatus = value.replace(/^['"]|['"]$/g, "");
+                        if (['proposed', 'accepted', 'rejected', 'superseded'].includes(parsedStatus)) {
+                            status = parsedStatus;
+                        }
+                    }
+                    else if (key === "date")
+                        date = value;
+                    else if (key === "decisionMakerRole")
+                        metadata.decisionMakerRole = value;
+                    else if (key === "affectedModules") {
+                        metadata.affectedModules = value.split(",").map((s) => s.trim());
+                    }
+                }
+            }
+        }
+        // Extract headers for sections (Context, Decision, Consequences)
+        let context = "";
+        let decision = "";
+        let consequences = "";
+        const contextMatch = body.match(/##\s+Context\r?\n([\s\S]*?)(?=##\s+Decision|##\s+Consequences|$)/i);
+        const decisionMatch = body.match(/##\s+Decision\r?\n([\s\S]*?)(?=##\s+Context|##\s+Consequences|$)/i);
+        const consequencesMatch = body.match(/##\s+Consequences\r?\n([\s\S]*?)(?=##\s+Context|##\s+Decision|$)/i);
+        if (contextMatch)
+            context = contextMatch[1].trim();
+        if (decisionMatch)
+            decision = decisionMatch[1].trim();
+        if (consequencesMatch)
+            consequences = consequencesMatch[1].trim();
+        // In case of headers missing
+        if (!context && !decision && !consequences) {
+            context = body.trim();
+        }
+        return {
+            id,
+            title,
+            date,
+            status,
+            context,
+            decision,
+            consequences,
+            metadata,
+        };
+    }
+    /**
+     * Scans docs/adr/ and calculates the next incremental number (e.g. ADR-0003).
+     */
+    static async getNextId(workspaceRoot) {
+        const fullDir = path.join(workspaceRoot, ADR_DIR);
+        try {
+            const files = await fs.readdir(fullDir);
+            let maxNum = 0;
+            for (const file of files) {
+                const match = file.match(/^ADR-(\d{4})\.md$/);
+                if (match) {
+                    const num = parseInt(match[1], 10);
+                    if (num > maxNum) {
+                        maxNum = num;
+                    }
+                }
+            }
+            const nextNum = maxNum + 1;
+            return `ADR-${String(nextNum).padStart(4, "0")}`;
+        }
+        catch {
+            return "ADR-0001";
+        }
+    }
+    /**
+     * Generates a new ADR file in the docs/adr/ directory.
+     */
+    static async create(workspaceRoot, adr, templateString) {
+        const id = await ADRService.getNextId(workspaceRoot);
+        const date = new Date().toISOString().split("T")[0];
+        const fullDir = path.join(workspaceRoot, ADR_DIR);
+        const definition = {
+            ...adr,
+            id,
+            date,
+        };
+        const template = Handlebars.compile(templateString || DEFAULT_TEMPLATE);
+        const rendered = template(definition);
+        await fs.mkdir(fullDir, { recursive: true });
+        const filePath = path.join(fullDir, `${id}.md`);
+        await fs.writeFile(filePath, rendered, "utf8");
+        return definition;
+    }
+    /**
+     * Loads a specific ADR by ID.
+     */
+    static async load(workspaceRoot, id) {
+        const fullDir = path.join(workspaceRoot, ADR_DIR);
+        const filePath = path.join(fullDir, `${id}.md`);
+        try {
+            const content = await fs.readFile(filePath, "utf8");
+            return ADRService.parseMarkdown(content, id);
+        }
+        catch (err) {
+            throw new Error(`Failed to load ADR '${id}': ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Lists all ADRs sorted by ID.
+     */
+    static async list(workspaceRoot) {
+        const fullDir = path.join(workspaceRoot, ADR_DIR);
+        const adrs = [];
+        try {
+            const files = await fs.readdir(fullDir);
+            for (const file of files) {
+                if (file.match(/^ADR-\d{4}\.md$/)) {
+                    const id = path.basename(file, ".md");
+                    const adr = await ADRService.load(workspaceRoot, id);
+                    adrs.push(adr);
+                }
+            }
+        }
+        catch {
+            // Directory may not exist yet
+        }
+        return adrs.sort((a, b) => a.id.localeCompare(b.id));
+    }
+    /**
+     * Performs case-insensitive search across titles, contexts, decisions, and consequences.
+     */
+    static async search(workspaceRoot, keyword) {
+        const all = await ADRService.list(workspaceRoot);
+        const searchLower = keyword.toLowerCase();
+        return all.filter((adr) => {
+            return (adr.title.toLowerCase().includes(searchLower) ||
+                adr.context.toLowerCase().includes(searchLower) ||
+                adr.decision.toLowerCase().includes(searchLower) ||
+                adr.consequences.toLowerCase().includes(searchLower));
+        });
+    }
+    /**
+     * Updates status metadata parameter for an ADR.
+     */
+    static async updateStatus(workspaceRoot, id, newStatus) {
+        const adr = await ADRService.load(workspaceRoot, id);
+        adr.status = newStatus;
+        // Render it back
+        const template = Handlebars.compile(DEFAULT_TEMPLATE);
+        const rendered = template(adr);
+        const fullDir = path.join(workspaceRoot, ADR_DIR);
+        const filePath = path.join(fullDir, `${id}.md`);
+        await fs.writeFile(filePath, rendered, "utf8");
+        return adr;
+    }
+}