@redwoodjs/agent-ci 0.3.4 → 0.5.0

package/README.md

@@ -46,12 +46,13 @@ DOCKER_HOST=ssh://user@remote-server npx agent-ci run --workflow .github/workflo
 
 Run GitHub Actions workflow jobs locally.
 
-| Flag                 | Short | Description                                                    |
-| -------------------- | ----- | -------------------------------------------------------------- |
-| `--workflow <path>`  | `-w`  | Path to the workflow file                                      |
-| `--all`              | `-a`  | Discover and run all relevant workflows for the current branch |
-| `--pause-on-failure` | `-p`  | Pause on step failure for interactive debugging                |
-| `--quiet`            | `-q`  | Suppress animated rendering (also enabled by `AI_AGENT=1`)     |
+| Flag                 | Short | Description                                                                       |
+| -------------------- | ----- | --------------------------------------------------------------------------------- |
+| `--workflow <path>`  | `-w`  | Path to the workflow file                                                         |
+| `--all`              | `-a`  | Discover and run all relevant workflows for the current branch                    |
+| `--pause-on-failure` | `-p`  | Pause on step failure for interactive debugging                                   |
+| `--quiet`            | `-q`  | Suppress animated rendering (also enabled by `AI_AGENT=1`)                        |
+| `--no-matrix`        |       | Collapse all matrix combinations into a single job (uses first value of each key) |
 
 ### `agent-ci retry`
 

package/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: agent-ci
+description: Run GitHub Actions workflows locally with pause-on-failure for AI-agent-driven CI iteration
+keywords: [github-actions, local-ci, pause-on-failure, ai-agent, runner]
+---
+
+## What agent-ci does
+
+Runs the official GitHub Actions runner binary locally (in Docker), emulating GitHub's cloud API.
+Cache is bind-mounted (instant). When a step fails, the container pauses — you can fix and retry the failed step without restarting.
+
+## When to use agent-ci (not `act`)
+
+- You want bit-for-bit compatibility with remote GitHub Actions
+- You need pause-on-failure for AI agent debugging loops
+- Cache round-trip speed matters
+
+## Key commands
+
+- Run workflow: `npx @redwoodjs/agent-ci run --workflow <path>`
+- Run all relevant workflows (those whose `on` triggers match the current branch/event, just like GitHub): `npx @redwoodjs/agent-ci run --all`
+- Retry after fix: `npx @redwoodjs/agent-ci retry --name <runner>`
+- Abort: `npx @redwoodjs/agent-ci abort --name <runner>`
+
+## Common mistakes
+
+- Don't push to remote CI to test changes — use `npx @redwoodjs/agent-ci run` locally first
+- Don't use `--from-start` when only the last step failed — use `retry` with no flags to re-run only the failed step
+- The `AI_AGENT=1` env variable disables animated output for cleaner agent logs
+- Use `--no-matrix` to collapse matrix jobs into a single run — your local machine is likely faster than GitHub's runners, so parallelizing across matrix combinations is unnecessary

package/dist/cli.js

@@ -7,7 +7,7 @@ import { getNextLogNum } from "./output/logger.js";
 import { setWorkingDirectory, DEFAULT_WORKING_DIR, PROJECT_ROOT, } from "./output/working-directory.js";
 import { debugCli } from "./output/debug.js";
 import { executeLocalJob } from "./runner/local-job.js";
-import { getWorkflowTemplate, parseWorkflowSteps, parseWorkflowServices, parseWorkflowContainer, validateSecrets, parseMatrixDef, expandMatrixCombinations, isWorkflowRelevant, getChangedFiles, parseJobOutputDefs, parseJobIf, evaluateJobIf, parseFailFast, } from "./workflow/workflow-parser.js";
+import { getWorkflowTemplate, parseWorkflowSteps, parseWorkflowServices, parseWorkflowContainer, validateSecrets, parseMatrixDef, expandMatrixCombinations, collapseMatrixToSingle, isWorkflowRelevant, getChangedFiles, parseJobOutputDefs, parseJobIf, evaluateJobIf, parseFailFast, } from "./workflow/workflow-parser.js";
 import { resolveJobOutputs } from "./runner/result-builder.js";
 import { createConcurrencyLimiter, getDefaultMaxConcurrentJobs } from "./output/concurrency.js";
 import { isWarmNodeModules, computeLockfileHash } from "./output/cleanup.js";
@@ -45,6 +45,7 @@ async function run() {
         let workflow;
         let pauseOnFailure = false;
         let runAll = false;
+        let noMatrix = false;
         for (let i = 1; i < args.length; i++) {
             if ((args[i] === "--workflow" || args[i] === "-w") && args[i + 1]) {
                 workflow = args[i + 1];
@@ -59,6 +60,9 @@ async function run() {
             else if (args[i] === "--quiet" || args[i] === "-q") {
                 setQuietMode(true);
             }
+            else if (args[i] === "--no-matrix") {
+                noMatrix = true;
+            }
             else if (!args[i].startsWith("-")) {
                 sha = args[i];
             }
@@ -119,7 +123,12 @@ async function run() {
                 console.log(`[Agent CI] No relevant workflows found for branch '${branch}'.`);
                 process.exit(0);
             }
-            const results = await runWorkflows({ workflowPaths: relevant, sha, pauseOnFailure });
+            const results = await runWorkflows({
+                workflowPaths: relevant,
+                sha,
+                pauseOnFailure,
+                noMatrix,
+            });
             printSummary(results);
             const anyFailed = results.some((r) => !r.succeeded);
             process.exit(anyFailed ? 1 : 0);
@@ -146,7 +155,12 @@ async function run() {
             ];
             workflowPath = pathsToTry.find((p) => fs.existsSync(p)) || pathsToTry[1];
         }
-        const results = await runWorkflows({ workflowPaths: [workflowPath], sha, pauseOnFailure });
+        const results = await runWorkflows({
+            workflowPaths: [workflowPath],
+            sha,
+            pauseOnFailure,
+            noMatrix,
+        });
         printSummary(results);
         if (results.some((r) => !r.succeeded)) {
             process.exit(1);
@@ -223,7 +237,7 @@ async function run() {
 // Single entry point for both `--workflow` and `--all`.
 // One workflow = --all with a single entry.
 async function runWorkflows(options) {
-    const { workflowPaths, sha, pauseOnFailure } = options;
+    const { workflowPaths, sha, pauseOnFailure, noMatrix = false } = options;
     // Create the run state store — single source of truth for all progress
     const runId = `run-${Date.now()}`;
     const storeFilePath = path.join(getWorkingDirectory(), "runs", runId, "run-state.json");
@@ -309,6 +323,7 @@ async function runWorkflows(options) {
                 workflowPath: workflowPaths[0],
                 sha,
                 pauseOnFailure,
+                noMatrix,
                 store,
             });
             allResults.push(...results);
@@ -332,12 +347,13 @@ async function runWorkflows(options) {
                     workflowPath: workflowPaths[0],
                     sha,
                     pauseOnFailure,
+                    noMatrix,
                     store,
                 });
                 allResults.push(...firstResults);
                 const settled = await Promise.allSettled(workflowPaths
                     .slice(1)
-                    .map((wf) => handleWorkflow({ workflowPath: wf, sha, pauseOnFailure, store })));
+                    .map((wf) => handleWorkflow({ workflowPath: wf, sha, pauseOnFailure, noMatrix, store })));
                 for (const s of settled) {
                     if (s.status === "fulfilled") {
                         allResults.push(...s.value);
@@ -348,7 +364,7 @@ async function runWorkflows(options) {
                 }
             }
             else {
-                const settled = await Promise.allSettled(workflowPaths.map((wf) => handleWorkflow({ workflowPath: wf, sha, pauseOnFailure, store })));
+                const settled = await Promise.allSettled(workflowPaths.map((wf) => handleWorkflow({ workflowPath: wf, sha, pauseOnFailure, noMatrix, store })));
                 for (const s of settled) {
                     if (s.status === "fulfilled") {
                         allResults.push(...s.value);
@@ -380,7 +396,7 @@ async function runWorkflows(options) {
 // Processes a single workflow file: parses jobs, handles matrix expansion,
 // wave scheduling, warm-cache serialization, and concurrency limiting.
 async function handleWorkflow(options) {
-    const { sha, pauseOnFailure, store } = options;
+    const { sha, pauseOnFailure, noMatrix = false, store } = options;
     let workflowPath = options.workflowPath;
     try {
         if (!fs.existsSync(workflowPath)) {
@@ -406,17 +422,21 @@ async function handleWorkflow(options) {
             const id = job.id.toString();
             const matrixDef = await parseMatrixDef(workflowPath, id);
             if (matrixDef) {
-                const combos = expandMatrixCombinations(matrixDef);
+                const combos = noMatrix
+                    ? collapseMatrixToSingle(matrixDef)
+                    : expandMatrixCombinations(matrixDef);
                 const total = combos.length;
                 for (let ci = 0; ci < combos.length; ci++) {
                     expandedJobs.push({
                         workflowPath,
                         taskName: id,
-                        matrixContext: {
-                            ...combos[ci],
-                            __job_total: String(total),
-                            __job_index: String(ci),
-                        },
+                        matrixContext: noMatrix
+                            ? combos[ci]
+                            : {
+                                ...combos[ci],
+                                __job_total: String(total),
+                                __job_index: String(ci),
+                            },
                     });
                 }
             }
@@ -697,6 +717,7 @@ function printUsage() {
     console.log("  -a, --all                     Discover and run all relevant workflows");
     console.log("  -p, --pause-on-failure         Pause on step failure for interactive debugging");
     console.log("  -q, --quiet                   Suppress animated rendering (also enabled by AI_AGENT=1)");
+    console.log("      --no-matrix               Collapse all matrix combinations into a single job (uses first value of each key)");
 }
 function resolveRepoRoot() {
     let repoRoot = process.cwd();

package/dist/workflow/matrix-collapse.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import { collapseMatrixToSingle, expandMatrixCombinations } from "./workflow-parser.js";
+// ─── collapseMatrixToSingle ───────────────────────────────────────────────────
+//
+// These tests cover the --no-matrix flag behavior: when the flag is active,
+// all matrix combinations are collapsed into a single job that carries the
+// first value of each matrix key plus __job_total="1" and __job_index="0".
+//
+// The Developer must export `collapseMatrixToSingle` from workflow-parser.ts
+// with the signature:
+//   collapseMatrixToSingle(matrixDef: Record<string, any[]>): Record<string, string>[]
+describe("collapseMatrixToSingle", () => {
+    // ── Core collapse behavior ──────────────────────────────────────────────────
+    it("returns exactly one job regardless of how many matrix values exist", () => {
+        const result = collapseMatrixToSingle({
+            shard: ["1", "2", "3", "4", "5", "6", "7", "8"],
+        });
+        expect(result).toHaveLength(1);
+    });
+    it("uses the first value of a single-key matrix", () => {
+        const result = collapseMatrixToSingle({
+            shard: ["1", "2", "3", "4", "5", "6", "7", "8"],
+        });
+        expect(result[0].shard).toBe("1");
+    });
+    it("sets __job_total to '1' on the collapsed job", () => {
+        const result = collapseMatrixToSingle({ shard: ["1", "2", "3"] });
+        expect(result[0].__job_total).toBe("1");
+    });
+    it("sets __job_index to '0' on the collapsed job", () => {
+        const result = collapseMatrixToSingle({ shard: ["1", "2", "3"] });
+        expect(result[0].__job_index).toBe("0");
+    });
+    // ── Multi-key matrix ────────────────────────────────────────────────────────
+    it("collapses a multi-key matrix: all keys present, each set to its first value", () => {
+        const result = collapseMatrixToSingle({
+            browser: ["chrome", "firefox", "safari"],
+            shard: ["1", "2", "3", "4"],
+        });
+        expect(result).toHaveLength(1);
+        expect(result[0].browser).toBe("chrome");
+        expect(result[0].shard).toBe("1");
+    });
+    it("sets __job_total and __job_index to '1'/'0' regardless of combination count across multiple keys", () => {
+        // 3 × 3 = 9 combinations without collapse; must still produce one job
+        const result = collapseMatrixToSingle({
+            os: ["ubuntu", "macos", "windows"],
+            node: ["18", "20", "22"],
+        });
+        expect(result).toHaveLength(1);
+        expect(result[0].__job_total).toBe("1");
+        expect(result[0].__job_index).toBe("0");
+    });
+    // ── Degenerate / edge cases ─────────────────────────────────────────────────
+    it("handles a matrix that already has exactly one combination (degenerate case)", () => {
+        const result = collapseMatrixToSingle({ shard: ["1"] });
+        expect(result).toHaveLength(1);
+        expect(result[0].shard).toBe("1");
+        expect(result[0].__job_total).toBe("1");
+        expect(result[0].__job_index).toBe("0");
+    });
+    it("does not throw when a matrix key has an empty value list", () => {
+        expect(() => collapseMatrixToSingle({ shard: [] })).not.toThrow();
+    });
+    it("coerces numeric matrix values to strings", () => {
+        // Matrix values in YAML may be parsed as numbers (e.g. shard: [1, 2, 3])
+        const result = collapseMatrixToSingle({ shard: [1, 2, 3] });
+        expect(result[0].shard).toBe("1");
+    });
+});
+// ─── Default expansion unaffected when --no-matrix is absent ─────────────────
+//
+// Without --no-matrix, the normal `expandMatrixCombinations` path must continue
+// to produce one job per combination. These tests guard against regressions.
+describe("expandMatrixCombinations (default path, no --no-matrix)", () => {
+    it("expands a single-key matrix into one job per value", () => {
+        const result = expandMatrixCombinations({ shard: ["1", "2", "3"] });
+        expect(result).toHaveLength(3);
+        expect(result.map((r) => r.shard)).toEqual(["1", "2", "3"]);
+    });
+    it("expands a multi-key matrix into the full cartesian product", () => {
+        const result = expandMatrixCombinations({
+            browser: ["chrome", "firefox"],
+            shard: ["1", "2"],
+        });
+        // 2 × 2 = 4 combinations
+        expect(result).toHaveLength(4);
+    });
+    it("does not include __job_total or __job_index in expanded jobs", () => {
+        const result = expandMatrixCombinations({ shard: ["1", "2"] });
+        for (const job of result) {
+            expect(job).not.toHaveProperty("__job_total");
+            expect(job).not.toHaveProperty("__job_index");
+        }
+    });
+});

package/dist/workflow/workflow-parser.js

@@ -247,6 +247,22 @@ export async function getWorkflowTemplate(filePath) {
     }
     return await convertWorkflowTemplate(result.context, result.value);
 }
+/**
+ * Collapse a matrix definition to a single job using the first value of each key.
+ * Sets __job_total to "1" and __job_index to "0".
+ * Used by the --no-matrix flag to run a matrix workflow as a single container.
+ */
+export function collapseMatrixToSingle(matrixDef) {
+    const combo = {};
+    for (const [key, values] of Object.entries(matrixDef)) {
+        if (values.length > 0) {
+            combo[key] = String(values[0]);
+        }
+    }
+    combo.__job_total = "1";
+    combo.__job_index = "0";
+    return [combo];
+}
 /**
  * Compute the Cartesian product of a matrix definition.
  * Values are always coerced to strings.

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@redwoodjs/agent-ci",
-  "version": "0.3.4",
-  "description": "Local GitHub Actions runner",
-  "keywords": [],
+  "version": "0.5.0",
+  "description": "Local GitHub Actions runner — pause on failure, ~0ms cache, official runner binary. Built for AI coding agents.",
+  "keywords": [
+    "act-alternative",
+    "ai-agent",
+    "ci",
+    "coding-agent",
+    "devtools",
+    "github-actions",
+    "local-ci",
+    "local-runner",
+    "pause-on-failure",
+    "runner",
+    "workflow"
+  ],
   "license": "FSL-1.1-MIT",
   "author": "",
   "repository": {
@@ -15,7 +27,8 @@
   },
   "files": [
     "dist",
-    "shim.sh"
+    "shim.sh",
+    "SKILL.md"
   ],
   "type": "module",
   "publishConfig": {
@@ -27,7 +40,7 @@
     "log-update": "^7.2.0",
     "minimatch": "^10.2.1",
     "yaml": "^2.8.2",
-    "dtu-github-actions": "0.3.4"
+    "dtu-github-actions": "0.5.0"
   },
   "devDependencies": {
     "@types/dockerode": "^3.3.34",