agent-workflow-kit-cli 1.2.1 → 1.3.1

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.1");
+        .version("1.3.1");
     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;
+    }
+}

package/dist/core/awos/intelligence.js

@@ -0,0 +1,235 @@
+/**
+ * @license
+ * SPDX-License-Identifier: MIT
+ */
+import { promises as fs } from "fs";
+import path from "path";
+import crypto from "crypto";
+import { detectProjectModules } from "../detector.js";
+import { parseImports } from "../parser.js";
+import { loadAWOSPlugins } from "./registry.js";
+const CACHE_DIR = ".agents/cache";
+const CACHE_FILE = path.join(CACHE_DIR, "repo_context.json");
+/**
+ * Calculates a composite MD5/SHA256 hash of all configuration manifest files in the repository.
+ */
+export async function calculateManifestHash(workspaceRoot) {
+    const manifests = [
+        "package.json",
+        "package-lock.json",
+        "pom.xml",
+        "build.gradle",
+        "build.gradle.kts",
+        "pyproject.toml",
+        "requirements.txt",
+        "Pipfile",
+        "tsconfig.json",
+    ];
+    const hash = crypto.createHash("sha256");
+    let foundAny = false;
+    for (const file of manifests) {
+        const fullPath = path.join(workspaceRoot, file);
+        try {
+            const stat = await fs.stat(fullPath);
+            if (stat.isFile()) {
+                const content = await fs.readFile(fullPath);
+                hash.update(file);
+                hash.update(content);
+                foundAny = true;
+            }
+        }
+        catch {
+            // Ignore missing manifest files
+        }
+    }
+    // Also include directory structure hash of sub-modules
+    try {
+        const submodules = await detectProjectModules(workspaceRoot);
+        for (const sub of submodules) {
+            hash.update(sub.name);
+            hash.update(sub.stacks.join(","));
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return foundAny ? hash.digest("hex") : "no-manifests-hash";
+}
+/**
+ * Parses files in a directory to identify imports and build a dependency relationship between directories.
+ */
+async function analyzeImportGraph(workspaceRoot, modules) {
+    const dependencies = {};
+    for (const mod of modules) {
+        dependencies[mod] = new Set();
+    }
+    // Helper to find files recursively
+    async function scanDir(dir, currentModule) {
+        try {
+            const entries = await fs.readdir(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name.startsWith(".") ||
+                        entry.name === "node_modules" ||
+                        entry.name === "dist" ||
+                        entry.name === "build" ||
+                        entry.name === "target") {
+                        continue;
+                    }
+                    await scanDir(fullPath, currentModule);
+                }
+                else if (entry.isFile() && /\.(ts|tsx|java|py)$/.test(entry.name)) {
+                    const content = await fs.readFile(fullPath, "utf8");
+                    const parsedImports = await parseImports(fullPath, content);
+                    for (const importedRef of parsedImports) {
+                        for (const mod of modules) {
+                            if (mod !== currentModule &&
+                                (importedRef.includes(`/${mod}`) || importedRef.includes(`.${mod}`))) {
+                                dependencies[currentModule].add(mod);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch {
+            // Ignore read errors
+        }
+    }
+    for (const mod of modules) {
+        const modulePath = path.join(workspaceRoot, mod);
+        await scanDir(modulePath, mod);
+    }
+    // Convert Sets to arrays
+    const result = {};
+    for (const [key, val] of Object.entries(dependencies)) {
+        result[key] = Array.from(val);
+    }
+    return result;
+}
+/**
+ * Builds a complete RepositoryContext for the given directory.
+ */
+export async function buildRepositoryContext(workspaceRoot) {
+    const manifestHash = await calculateManifestHash(workspaceRoot);
+    // 1. Detect modules
+    const detectedModules = await detectProjectModules(workspaceRoot);
+    const moduleNames = detectedModules.map((m) => m.name === "." ? "root" : m.name);
+    // Analyze import boundaries
+    const importGraph = await analyzeImportGraph(workspaceRoot, detectedModules.map((m) => m.name));
+    const moduleBoundaries = detectedModules.map((m) => {
+        const name = m.name === "." ? "root" : m.name;
+        const dependencies = importGraph[m.name] || [];
+        return {
+            name,
+            path: m.dir,
+            dependencies,
+        };
+    });
+    // Determine main stack & architecture
+    let mainStack = "custom";
+    const stackCounts = {};
+    for (const m of detectedModules) {
+        for (const s of m.stacks) {
+            stackCounts[s] = (stackCounts[s] || 0) + 1;
+        }
+    }
+    const sortedStacks = Object.entries(stackCounts).sort((a, b) => b[1] - a[1]);
+    if (sortedStacks.length > 0) {
+        mainStack = sortedStacks[0][0];
+    }
+    // Determine default architecture style based on stack
+    let architecture = "layered";
+    if (mainStack === "spring-boot") {
+        architecture = "clean-architecture";
+    }
+    else if (mainStack === "react-ts") {
+        architecture = "feature-first";
+    }
+    else if (mainStack === "fastapi") {
+        architecture = "vertical-slice";
+    }
+    // Testing strategy defaults
+    const frameworks = [];
+    if (mainStack === "react-ts")
+        frameworks.push("vitest", "testing-library");
+    else if (mainStack === "spring-boot")
+        frameworks.push("junit", "mockito");
+    else if (mainStack === "fastapi")
+        frameworks.push("pytest");
+    const testing = {
+        frameworks,
+        coverageGoal: 80,
+    };
+    // Validation libraries defaults
+    const validationLibraries = [];
+    if (mainStack === "spring-boot") {
+        validationLibraries.push("jakarta.validation");
+    }
+    else if (mainStack === "react-ts") {
+        validationLibraries.push("zod");
+    }
+    else if (mainStack === "fastapi") {
+        validationLibraries.push("pydantic");
+    }
+    const registry = await loadAWOSPlugins(workspaceRoot);
+    let context = {
+        stack: mainStack,
+        architecture,
+        modules: moduleBoundaries,
+        testing,
+        validation: {
+            libraries: validationLibraries,
+        },
+        hash: manifestHash,
+    };
+    for (const analyzer of registry.analyzers) {
+        try {
+            const partial = await analyzer.detect(workspaceRoot);
+            context = {
+                ...context,
+                ...partial,
+                testing: {
+                    ...context.testing,
+                    ...(partial.testing || {}),
+                },
+                validation: {
+                    ...context.validation,
+                    ...(partial.validation || {}),
+                },
+            };
+        }
+        catch (err) {
+            console.warn(`[AWOS Intelligence] Custom analyzer failed:`, err);
+        }
+    }
+    return context;
+}
+/**
+ * Loads the RepositoryContext, using cached results if valid.
+ */
+export async function getRepositoryContext(workspaceRoot) {
+    const currentHash = await calculateManifestHash(workspaceRoot);
+    const fullCachePath = path.join(workspaceRoot, CACHE_FILE);
+    try {
+        const cacheContent = await fs.readFile(fullCachePath, "utf8");
+        const cachedCtx = JSON.parse(cacheContent);
+        if (cachedCtx.hash === currentHash) {
+            return cachedCtx;
+        }
+    }
+    catch {
+        // Cache miss or read failure
+    }
+    // Re-build and write to cache
+    const context = await buildRepositoryContext(workspaceRoot);
+    try {
+        await fs.mkdir(path.dirname(fullCachePath), { recursive: true });
+        await fs.writeFile(fullCachePath, JSON.stringify(context, null, 2), "utf8");
+    }
+    catch {
+        // Non-blocking cache write failure
+    }
+    return context;
+}