agentweaver 0.1.3 → 0.1.4

package/README.md

@@ -11,9 +11,10 @@ The package is designed to run as an npm CLI and includes an interactive termina
 ## What It Does
 
 - Fetches a Jira issue by key or browse URL
-- Generates workflow artifacts such as design, implementation plan, QA plan, reviews, and summaries
-- Runs workflow stages like `plan`, `implement`, `review`, `review-fix`, `test`, and `auto`
-- Persists `auto` pipeline state on disk so runs can resume
+- Generates workflow artifacts such as design, implementation plan, QA plan, bug analysis, reviews, and summaries
+- For bug-analysis flows, structured JSON artifacts are the machine-readable source of truth, while Markdown artifacts are for human inspection
+- Runs workflow stages like `bug-analyze`, `bug-fix`, `mr-description`, `plan`, `task-describe`, `implement`, `review`, `review-fix`, `test`, and `auto`
+- Persists compact `auto` pipeline state on disk so runs can resume without storing large agent outputs
 - Uses Docker runtime services for isolated Codex execution and build verification
 
 ## Architecture
@@ -23,7 +24,7 @@ The CLI now uses an executor + node + declarative flow architecture.
 - `src/index.ts` remains the CLI entrypoint and high-level orchestration layer
 - `src/executors/` contains first-class executors for external actions such as Jira fetch, local Codex, Docker-based build verification, Claude, Claude summaries, and process execution
 - `src/pipeline/nodes/` contains reusable runtime nodes built on top of executors
-- `src/pipeline/flow-specs/` contains declarative JSON flow specs for `preflight`, `plan`, `implement`, `review`, `review-fix`, `test`, `test-fix`, `test-linter-fix`, and `auto`
+- `src/pipeline/flow-specs/` contains declarative JSON flow specs for `preflight`, `bug-analyze`, `bug-fix`, `mr-description`, `plan`, `task-describe`, `implement`, `review`, `review-fix`, `test`, `test-fix`, `test-linter-fix`, `run-tests-loop`, `run-linter-loop`, and `auto`
 - `src/runtime/` contains shared runtime services such as command resolution, Docker runtime environment setup, and subprocess execution
 
 This keeps command handlers focused on choosing a flow and providing parameters instead of assembling prompts and subprocess wiring inline.
@@ -41,7 +42,9 @@ This keeps command handlers focused on choosing a flow and providing parameters
 - `src/runtime/` — shared runtime services used by executors
 - `docker-compose.yml` — runtime services for Codex and build verification
 - `Dockerfile.codex` — container image for Codex runtime
-- `verify_build.sh` — project-specific verification entrypoint used by `verify-build`
+- `verify_build.sh` — aggregated verification entrypoint used by `verify-build`
+- `run_tests.sh` — isolated test and coverage verification entrypoint
+- `run_linter.sh` — isolated generate + lint verification entrypoint
 - `package.json` — npm package metadata and scripts
 - `tsconfig.json` — TypeScript configuration
 
@@ -50,7 +53,7 @@ This keeps command handlers focused on choosing a flow and providing parameters
 - Node.js `>= 18.19.0`
 - npm
 - Docker with `docker compose` or `docker-compose`
-- `codex` CLI for `plan` and Codex-driven steps
+- `codex` CLI for `bug-analyze`, `bug-fix`, `mr-description`, `plan`, and other Codex-driven steps
 - `claude` CLI for review and summary steps
 
 ## Installation
@@ -112,8 +115,14 @@ Direct CLI usage:
 
 ```bash
 agentweaver plan DEMO-3288
+agentweaver bug-analyze DEMO-3288
+agentweaver bug-fix DEMO-3288
+agentweaver mr-description DEMO-3288
+agentweaver task-describe DEMO-3288
 agentweaver implement DEMO-3288
 agentweaver review DEMO-3288
+agentweaver run-tests-loop DEMO-3288
+agentweaver run-linter-loop DEMO-3288
 agentweaver auto DEMO-3288
 ```
 
@@ -121,6 +130,10 @@ From source checkout:
 
 ```bash
 node dist/index.js plan DEMO-3288
+node dist/index.js bug-analyze DEMO-3288
+node dist/index.js bug-fix DEMO-3288
+node dist/index.js mr-description DEMO-3288
+node dist/index.js task-describe DEMO-3288
 node dist/index.js auto DEMO-3288
 ```
 
@@ -145,28 +158,35 @@ agentweaver auto-status DEMO-3288
 agentweaver auto-reset DEMO-3288
 ```
 
+Notes:
+
+- `--verbose` streams child process `stdout/stderr` in direct CLI mode
+- the interactive `Activity` pane is intentionally structured: it shows launch separators, prompts, summaries, and short status messages instead of raw Codex/Claude logs by default
+
 ## Interactive TUI
 
 Interactive mode opens a full-screen terminal UI with:
 
-- command input
+- flow list
+- current flow progress
 - activity log
 - task summary pane
-- command list/help
 - keyboard navigation between panes
 
 Current navigation:
 
-- `Enter` — run command
+- `Enter` — run selected flow
 - `Tab` / `Shift+Tab` — switch panes
-- `Ctrl+J` — focus activity log
-- `Ctrl+K` — focus command input
-- `Ctrl+U` — focus task summary
-- `Ctrl+H` — focus commands pane
 - `PgUp` / `PgDn` / `Home` / `End` — scroll focused panes
-- `?` or `F1` — help overlay
+- `h` — help overlay
 - `q` or `Ctrl+C` — exit
 
+Activity pane behavior:
+
+- each external launch is separated with a framed block that shows the current `node`, `executor`, and `model` when available
+- prompts and summaries are rendered as plain text for readability
+- live raw Codex/Claude output is not shown there in normal mode
+
 ## Docker Runtime
 
 Docker is used as an isolated execution environment for Codex and build/test verification.
@@ -176,6 +196,8 @@ Main services:
 - `codex` — interactive Codex container
 - `codex-exec` — non-interactive `codex exec`
 - `verify-build` — project verification script inside container
+- `run-tests` — isolated `run_tests.sh` execution inside container
+- `run-linter` — isolated `run_linter.sh` execution inside container
 - `codex-login` — interactive login container
 - `dockerd` — internal Docker daemon for testcontainers/build flows
 
@@ -205,6 +227,18 @@ Build verification:
 PROJECT_DIR="$PWD" docker compose -f "$AGENTWEAVER_HOME/docker-compose.yml" run --rm verify-build
 ```
 
+Tests only:
+
+```bash
+PROJECT_DIR="$PWD" docker compose -f "$AGENTWEAVER_HOME/docker-compose.yml" run --rm run-tests
+```
+
+Linter only:
+
+```bash
+PROJECT_DIR="$PWD" docker compose -f "$AGENTWEAVER_HOME/docker-compose.yml" run --rm run-linter
+```
+
 ## Development
 
 Install dependencies and build:

package/dist/artifacts.js

@@ -25,6 +25,24 @@ export function designFile(taskKey) {
 export function planFile(taskKey) {
     return artifactFile("plan", taskKey, 1);
 }
+export function bugAnalyzeFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-analyze-${taskKey}.md`);
+}
+export function bugAnalyzeJsonFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-analyze-${taskKey}.json`);
+}
+export function bugFixDesignFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-design-${taskKey}.md`);
+}
+export function bugFixDesignJsonFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-design-${taskKey}.json`);
+}
+export function bugFixPlanFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-plan-${taskKey}.md`);
+}
+export function bugFixPlanJsonFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `bug-fix-plan-${taskKey}.json`);
+}
 export function qaFile(taskKey) {
     return artifactFile("qa", taskKey, 1);
 }
@@ -37,12 +55,28 @@ export function readyToMergeFile(taskKey) {
 export function jiraTaskFile(taskKey) {
     return taskWorkspaceFile(taskKey, `${taskKey}.json`);
 }
+export function jiraDescriptionFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `jira-${taskKey}-description.md`);
+}
+export function mrDescriptionFile(taskKey) {
+    return taskWorkspaceFile(taskKey, `mr-description-${taskKey}.md`);
+}
 export function autoStateFile(taskKey) {
     return taskWorkspaceFile(taskKey, `.agentweaver-state-${taskKey}.json`);
 }
 export function planArtifacts(taskKey) {
     return [designFile(taskKey), planFile(taskKey), qaFile(taskKey)];
 }
+export function bugAnalyzeArtifacts(taskKey) {
+    return [
+        bugAnalyzeFile(taskKey),
+        bugAnalyzeJsonFile(taskKey),
+        bugFixDesignFile(taskKey),
+        bugFixDesignJsonFile(taskKey),
+        bugFixPlanFile(taskKey),
+        bugFixPlanJsonFile(taskKey),
+    ];
+}
 export function requireArtifacts(paths, message) {
     const missing = paths.filter((filePath) => !existsSync(filePath));
     if (missing.length > 0) {

package/dist/executors/verify-build-executor.js

@@ -1,22 +1,123 @@
 import { verifyBuildExecutorDefaultConfig } from "./configs/verify-build-config.js";
+import { TaskRunnerError } from "../errors.js";
 import { processExecutor } from "./process-executor.js";
+function parseStructuredResult(output, service) {
+    const lines = output
+        .split(/\r?\n/)
+        .map((line) => line.replace(/\u001b\[[0-9;]*m/g, "").trim())
+        .filter(Boolean);
+    if (lines.length === 0) {
+        throw new TaskRunnerError(`Structured result is missing from service '${service}' output.`);
+    }
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index];
+        if (!line) {
+            continue;
+        }
+        const candidates = [];
+        if (line.startsWith("{") && line.endsWith("}")) {
+            candidates.push(line);
+        }
+        const firstBrace = line.indexOf("{");
+        const lastBrace = line.lastIndexOf("}");
+        if (firstBrace >= 0 && lastBrace > firstBrace) {
+            const slice = line.slice(firstBrace, lastBrace + 1).trim();
+            if (slice && !candidates.includes(slice)) {
+                candidates.push(slice);
+            }
+        }
+        for (const rawJson of candidates) {
+            let parsed;
+            try {
+                parsed = JSON.parse(rawJson);
+            }
+            catch {
+                continue;
+            }
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+                continue;
+            }
+            const candidate = parsed;
+            if (typeof candidate.ok !== "boolean" ||
+                typeof candidate.kind !== "string" ||
+                typeof candidate.stage !== "string" ||
+                typeof candidate.exitCode !== "number" ||
+                typeof candidate.summary !== "string" ||
+                typeof candidate.command !== "string") {
+                continue;
+            }
+            const details = candidate.details;
+            if (details !== undefined && (!details || typeof details !== "object" || Array.isArray(details))) {
+                continue;
+            }
+            return {
+                ok: candidate.ok,
+                kind: candidate.kind,
+                stage: candidate.stage,
+                exitCode: candidate.exitCode,
+                summary: candidate.summary,
+                command: candidate.command,
+                details: details ?? {},
+            };
+        }
+    }
+    throw new TaskRunnerError(`Structured result is missing or invalid in service '${service}' output.`);
+}
 export const verifyBuildExecutor = {
     kind: "verify-build",
     version: 1,
     defaultConfig: verifyBuildExecutorDefaultConfig,
     async execute(context, input, config) {
         const composeCommand = context.runtime.resolveDockerComposeCmd();
-        const result = await processExecutor.execute(context, {
-            argv: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, config.service],
-            env: context.runtime.dockerRuntimeEnv(),
-            verbose: config.verbose,
-            label: config.service,
-        }, {
-            printFailureOutput: config.printFailureOutput,
-        });
+        const service = input.service ?? config.service;
+        if (context.dryRun) {
+            await processExecutor.execute(context, {
+                argv: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, service],
+                env: context.runtime.dockerRuntimeEnv(),
+                verbose: config.verbose,
+                label: service,
+            }, {
+                printFailureOutput: config.printFailureOutput,
+            });
+            return {
+                output: "",
+                composeCommand,
+                parsed: {
+                    ok: true,
+                    kind: service,
+                    stage: "dry_run",
+                    exitCode: 0,
+                    summary: `Dry run for service '${service}'`,
+                    command: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, service].join(" "),
+                    details: {},
+                },
+            };
+        }
+        let output = "";
+        let exitCode = 0;
+        try {
+            const result = await processExecutor.execute(context, {
+                argv: [...composeCommand, config.composeFileFlag, input.dockerComposeFile, ...config.runArgs, service],
+                env: context.runtime.dockerRuntimeEnv(),
+                verbose: config.verbose,
+                label: service,
+            }, {
+                printFailureOutput: config.printFailureOutput,
+            });
+            output = result.output;
+        }
+        catch (error) {
+            output = String(error.output ?? "");
+            exitCode = Number(error.returnCode ?? 1);
+        }
+        const parsed = parseStructuredResult(output, service);
+        if (parsed.exitCode !== exitCode && exitCode !== 0) {
+            throw new TaskRunnerError(`Structured result exit code mismatch for service '${service}': script=${parsed.exitCode}, runtime=${exitCode}.`);
+        }
         return {
-            output: result.output,
+            output,
             composeCommand,
+            parsed,
         };
     },
 };

package/dist/index.js

@@ -3,9 +3,10 @@ import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from "no
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
-import { REVIEW_FILE_RE, REVIEW_REPLY_FILE_RE, autoStateFile, ensureTaskWorkspaceDir, jiraTaskFile, planArtifacts, readyToMergeFile, requireArtifacts, taskWorkspaceDir, taskSummaryFile, } from "./artifacts.js";
+import { REVIEW_FILE_RE, REVIEW_REPLY_FILE_RE, autoStateFile, bugAnalyzeArtifacts, bugAnalyzeJsonFile, bugFixDesignJsonFile, bugFixPlanJsonFile, ensureTaskWorkspaceDir, jiraTaskFile, planArtifacts, readyToMergeFile, requireArtifacts, taskWorkspaceDir, taskSummaryFile, } from "./artifacts.js";
 import { TaskRunnerError } from "./errors.js";
 import { buildJiraApiUrl, buildJiraBrowseUrl, extractIssueKey, requireJiraTaskFile } from "./jira.js";
+import { validateStructuredArtifacts } from "./structured-artifacts.js";
 import { summarizeBuildFailure as summarizeBuildFailureViaPipeline } from "./pipeline/build-failure-summary.js";
 import { createPipelineContext } from "./pipeline/context.js";
 import { loadAutoFlow } from "./pipeline/auto-flow.js";
@@ -18,18 +19,24 @@ import { runCommand } from "./runtime/process-runner.js";
 import { InteractiveUi } from "./interactive-ui.js";
 import { bye, printError, printInfo, printPanel, printSummary, setFlowExecutionState } from "./tui.js";
 const COMMANDS = [
+    "bug-analyze",
+    "bug-fix",
+    "mr-description",
     "plan",
+    "task-describe",
     "implement",
     "review",
     "review-fix",
     "test",
     "test-fix",
     "test-linter-fix",
+    "run-tests-loop",
+    "run-linter-loop",
     "auto",
     "auto-status",
     "auto-reset",
 ];
-const AUTO_STATE_SCHEMA_VERSION = 2;
+const AUTO_STATE_SCHEMA_VERSION = 3;
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = path.resolve(MODULE_DIR, "..");
 const runtimeServices = {
@@ -42,13 +49,19 @@ function usage() {
     return `Usage:
   agentweaver <jira-browse-url|jira-issue-key>
   agentweaver --force <jira-browse-url|jira-issue-key>
+  agentweaver bug-analyze [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
+  agentweaver bug-fix [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
+  agentweaver mr-description [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver plan [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
+  agentweaver task-describe [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver implement [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver review [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver review-fix [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver test [--dry] [--verbose] <jira-browse-url|jira-issue-key>
   agentweaver test-fix [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver test-linter-fix [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
+  agentweaver run-tests-loop [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
+  agentweaver run-linter-loop [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver auto [--dry] [--verbose] [--prompt <text>] <jira-browse-url|jira-issue-key>
   agentweaver auto [--dry] [--verbose] [--prompt <text>] --from <phase> <jira-browse-url|jira-issue-key>
   agentweaver auto --help-phases
@@ -67,7 +80,7 @@ Flags:
   --prompt        Extra prompt text appended to the base prompt
 
 Required environment variables:
-  JIRA_API_KEY    Jira API key used in Authorization: Bearer <token> for plan
+  JIRA_API_KEY    Jira API key used in Authorization: Bearer <token> for Jira-backed flows
 
 Optional environment variables:
   JIRA_BASE_URL
@@ -370,13 +383,20 @@ function buildConfig(command, jiraRef, options = {}) {
     };
 }
 function checkPrerequisites(config) {
-    if (config.command === "plan" || config.command === "review") {
+    if (config.command === "bug-analyze" ||
+        config.command === "bug-fix" ||
+        config.command === "mr-description" ||
+        config.command === "plan" ||
+        config.command === "task-describe" ||
+        config.command === "review" ||
+        config.command === "run-tests-loop" ||
+        config.command === "run-linter-loop") {
         resolveCmd("codex", "CODEX_BIN");
     }
     if (config.command === "review") {
         resolveCmd("claude", "CLAUDE_BIN");
     }
-    if (["implement", "review-fix", "test"].includes(config.command)) {
+    if (["implement", "review-fix", "test", "run-tests-loop", "run-linter-loop"].includes(config.command)) {
         resolveDockerComposeCmd();
         if (!existsSync(config.dockerComposeFile)) {
             throw new TaskRunnerError(`docker-compose file not found: ${config.dockerComposeFile}`);
@@ -431,13 +451,19 @@ function autoFlowDefinition() {
 function interactiveFlowDefinitions() {
     return [
         autoFlowDefinition(),
+        declarativeFlowDefinition("bug-analyze", "bug-analyze", "bug-analyze.json"),
+        declarativeFlowDefinition("bug-fix", "bug-fix", "bug-fix.json"),
+        declarativeFlowDefinition("mr-description", "mr-description", "mr-description.json"),
         declarativeFlowDefinition("plan", "plan", "plan.json"),
+        declarativeFlowDefinition("task-describe", "task-describe", "task-describe.json"),
         declarativeFlowDefinition("implement", "implement", "implement.json"),
         declarativeFlowDefinition("review", "review", "review.json"),
         declarativeFlowDefinition("review-fix", "review-fix", "review-fix.json"),
         declarativeFlowDefinition("test", "test", "test.json"),
         declarativeFlowDefinition("test-fix", "test-fix", "test-fix.json"),
         declarativeFlowDefinition("test-linter-fix", "test-linter-fix", "test-linter-fix.json"),
+        declarativeFlowDefinition("run-tests-loop", "run-tests-loop", "run-tests-loop.json"),
+        declarativeFlowDefinition("run-linter-loop", "run-linter-loop", "run-linter-loop.json"),
     ];
 }
 function publishFlowState(flowId, executionState) {
@@ -589,6 +615,49 @@ async function executeCommand(config, runFollowupVerify = true) {
         });
         return false;
     }
+    if (config.command === "bug-analyze") {
+        if (config.verbose) {
+            process.stdout.write(`Fetching Jira issue from browse URL: ${config.jiraBrowseUrl}\n`);
+            process.stdout.write(`Resolved Jira API URL: ${config.jiraApiUrl}\n`);
+            process.stdout.write(`Saving Jira issue JSON to: ${config.jiraTaskFile}\n`);
+        }
+        await runDeclarativeFlowBySpecFile("bug-analyze.json", config, {
+            jiraApiUrl: config.jiraApiUrl,
+            taskKey: config.taskKey,
+            extraPrompt: config.extraPrompt,
+        });
+        return false;
+    }
+    if (config.command === "bug-fix") {
+        requireJiraTaskFile(config.jiraTaskFile);
+        requireArtifacts(bugAnalyzeArtifacts(config.taskKey), "Bug-fix mode requires bug-analyze artifacts from the bug analysis phase.");
+        validateStructuredArtifacts([
+            { path: bugAnalyzeJsonFile(config.taskKey), schemaId: "bug-analysis/v1" },
+            { path: bugFixDesignJsonFile(config.taskKey), schemaId: "bug-fix-design/v1" },
+            { path: bugFixPlanJsonFile(config.taskKey), schemaId: "bug-fix-plan/v1" },
+        ], "Bug-fix mode requires valid structured artifacts from the bug analysis phase.");
+        await runDeclarativeFlowBySpecFile("bug-fix.json", config, {
+            taskKey: config.taskKey,
+            extraPrompt: config.extraPrompt,
+        });
+        return false;
+    }
+    if (config.command === "mr-description") {
+        requireJiraTaskFile(config.jiraTaskFile);
+        await runDeclarativeFlowBySpecFile("mr-description.json", config, {
+            taskKey: config.taskKey,
+            extraPrompt: config.extraPrompt,
+        });
+        return false;
+    }
+    if (config.command === "task-describe") {
+        requireJiraTaskFile(config.jiraTaskFile);
+        await runDeclarativeFlowBySpecFile("task-describe.json", config, {
+            taskKey: config.taskKey,
+            extraPrompt: config.extraPrompt,
+        });
+        return false;
+    }
     if (config.command === "implement") {
         requireJiraTaskFile(config.jiraTaskFile);
         requireArtifacts(planArtifacts(config.taskKey), "Implement mode requires plan artifacts from the planning phase.");
@@ -674,6 +743,14 @@ async function executeCommand(config, runFollowupVerify = true) {
         });
         return false;
     }
+    if (config.command === "run-tests-loop" || config.command === "run-linter-loop") {
+        await runDeclarativeFlowBySpecFile(config.command === "run-tests-loop" ? "run-tests-loop.json" : "run-linter-loop.json", config, {
+            taskKey: config.taskKey,
+            dockerComposeFile: config.dockerComposeFile,
+            extraPrompt: config.extraPrompt,
+        });
+        return false;
+    }
     throw new TaskRunnerError(`Unsupported command: ${config.command}`);
 }
 async function runAutoPipelineDryRun(config) {