@intentius/chant-lexicon-github 0.18.12 → 0.18.14

package/dist/components/generate-pipeline.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Generate mode — component → GitHub Actions workflow YAML (#891, epic #885).
+ *
+ * The github counterpart to the gitlab generator (`../../gitlab/src/components/generate-pipeline.ts`,
+ * #563/#688): the same `chant build --components --generate <lexicon>` seam,
+ * synthesizing a **thin** `.github/workflows/*.yml` from the discovered
+ * component graph instead of interpreting it directly.
+ *
+ * The generated workflow is a trigger, not the deploy logic:
+ *  - Ordering + parallel-safe waves are resolved once, generically, by
+ *    `resolveComponentGraph` (core's driver) — the exact function the local
+ *    interpret driver and the gitlab generator both use. This module does not
+ *    re-derive or duplicate that graph logic.
+ *  - GitHub Actions has no `stage` concept, so wave ordering is expressed
+ *    entirely through `needs:` edges between jobs: one job per component,
+ *    with `needs:` pointing at the jobs for its direct `dependsOn` entries.
+ *    Independent components therefore run in parallel, and dependents wait
+ *    on their dependencies via GitHub's own `needs:` scheduling.
+ *    `ComponentPipelineResult.stages` is still populated with the wave-ordered
+ *    names (one per wave) purely for parity with gitlab's machine-readable
+ *    `--format json` view — GitHub's YAML itself has no `stages:` section.
+ *  - Each job's trigger step is exactly one invocation that hands off to the
+ *    component's own composition (`chant run --components <name> ...` by
+ *    default) — never inlined build/publish/apply steps. The deploy logic
+ *    lives in the component's `deploy` phases and the capabilities they
+ *    reference, not in this YAML.
+ *  - A component that something else depends on can't hand its resolved
+ *    stack outputs to a dependent in-memory, since each job is a separate
+ *    GitHub Actions runner. It dumps its outputs to a file and uploads that
+ *    file as a workflow artifact (`actions/upload-artifact`); each direct
+ *    dependent downloads it (`actions/download-artifact`) and seeds from it,
+ *    so a `stackOutput()` / `@<dep>.publish.*` reference still resolves even
+ *    though the producer ran in a different job. This mirrors the dump/seed
+ *    model `cli-support.ts` (`runComponents`'s `componentOutputs`) already
+ *    uses, and matches gitlab's artifact-passing 1:1 in intent — only the
+ *    transport differs (explicit upload/download steps vs. GitLab's implicit
+ *    `needs:` artifact passing).
+ *
+ * Cross-cutting changes (e.g. "sign every image before deploy") are made by
+ * editing `GenerateGithubOptions.extraScript`/`beforeScript` (or the
+ * component's own composition) ONCE here — never per generated job. See
+ * `generate-pipeline.test.ts`'s "cross-cutting change" cases for a
+ * demonstration: one generator-option edit reflects in every job without
+ * touching the component declarations.
+ */
+import { type DriverComponent } from "@intentius/chant/components/driver";
+import type { ComponentPipelineJob as GeneratedJob, ComponentPipelineOptions as GenerateGithubOptions, ComponentPipelineResult as GenerateGithubResult } from "@intentius/chant/lexicon";
+export type { GeneratedJob, GenerateGithubOptions, GenerateGithubResult };
+/**
+ * Synthesize a `.github/workflows/*.yml` pipeline from a set of components:
+ * one job per component, `needs:` expressing the wave-ordered dependency DAG
+ * from `resolveComponentGraph`. Throws `DependencyCycleError`/
+ * `UnknownDependencyError` (from core's driver) exactly like the interpret
+ * driver and the gitlab generator do, since all three consume the same graph
+ * resolution. Wired into core's generate mode via the github lexicon plugin's
+ * `generateComponentPipeline` (../plugin.ts).
+ */
+export declare function generateGithubPipeline(components: DriverComponent[], options?: GenerateGithubOptions): GenerateGithubResult;
+//# sourceMappingURL=generate-pipeline.d.ts.map

package/dist/components/generate-pipeline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/generate-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAGH,OAAO,EAAyB,KAAK,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACjG,OAAO,KAAK,EACV,oBAAoB,IAAI,YAAY,EACpC,wBAAwB,IAAI,qBAAqB,EACjD,uBAAuB,IAAI,oBAAoB,EAChD,MAAM,0BAA0B,CAAC;AAElC,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAmB1E;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,eAAe,EAAE,EAC7B,OAAO,GAAE,qBAA0B,GAClC,oBAAoB,CAyFtB"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "0a6298aa6e014ce8b90ed77e3d275e9e384eb4847bc195e6aa3ff7589cd11f9b",
+    "manifest.json": "5e6635f5045cb84027fe7fff1b39b2cceec7fc8336463bb644a32a07822e5930",
     "meta.json": "798c5f5f37b0174756d2451299acfdc95c014f11d06d32b9153bbdfa9f3a580c",
     "types/index.d.ts": "39c0791f0e58025bcef82e0f7a92240508f899fc2771d5dd51b2369b4d330f13",
     "rules/deprecated-action-version.ts": "d41e6e532ab7f623af1bee4ac5279fcb2baada7defa1c5d022a5bc71983e8797",
@@ -67,5 +67,5 @@
     "skills/chant-github-patterns.md": "bb3abef289a8fdfcf07d6bb2d7289dcb2f38bc0cb0321ea320b78b45a6f548c0",
     "skills/chant-github-security.md": "aab111cb0871cad30281ce48d7da23663689619351029219e2be019a1a61e394"
   },
-  "composite": "d46c8ea3bd79952d46683228aa5309206736bb37c6718f3f517ac4cab8579aa2"
+  "composite": "cd7930421da0be3f6164dcbfa2a988b2f9b2c84761166ab1c6a37bc97025df5e"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github",
-  "version": "0.18.12",
+  "version": "0.18.14",
   "chantVersion": ">=0.1.0",
   "namespace": "GitHub",
   "intrinsics": [

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA2B7F,eAAO,MAAM,YAAY,EAAE,aA6S1B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AA4B7F,eAAO,MAAM,YAAY,EAAE,aA+S1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-github",
-  "version": "0.18.12",
+  "version": "0.18.14",
   "description": "GitHub Actions lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -61,7 +61,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.18.12",
+    "@intentius/chant": "^0.18.14",
     "typescript": "^5.9.3"
   }
 }

package/src/components/generate-pipeline.test.ts

@@ -0,0 +1,279 @@
+/**
+ * Tests for generate mode's component → GitHub Actions workflow YAML
+ * synthesis (#891, epic #885). Mirrors the gitlab generator's own test suite
+ * (`lexicons/gitlab/src/components/generate-pipeline.test.ts`) so both
+ * providers prove the same seam contract:
+ *
+ *  1. A component set produces a structurally valid GitHub Actions workflow
+ *     (parses back via `../yaml.ts`'s `parseYAML`, with `on:` + a `jobs:` map
+ *     carrying one entry per component, each job with `runs-on:`/`steps:`).
+ *  2. Jobs map onto components in wave order — a component's job depends
+ *     (`needs:`) only on its own `dependsOn` edges, never on unrelated jobs,
+ *     and lands in the same wave `resolveComponentGraph` (the driver's own
+ *     graph resolution) computes — even though GitHub Actions has no `stage`
+ *     concept, so ordering is expressed purely through `needs:`.
+ *  3. A cross-cutting generator change (e.g. "sign every image before
+ *     deploy") is a single edit to the generator's options — reflected in
+ *     every job's steps — never a per-component edit.
+ */
+
+import { describe, test, expect } from "vitest";
+import { parseYAML } from "@intentius/chant/yaml";
+import { generateGithubPipeline } from "./generate-pipeline";
+import { resolveComponentGraph, DependencyCycleError, UnknownDependencyError, type DriverComponent } from "@intentius/chant/components/driver";
+import { searchService } from "@intentius/chant/components/pilots/alb-ecs.pilot";
+import { ordersTable } from "@intentius/chant/components/pilots/dynamodb.pilot";
+
+/** Real pilot components (#555) plus the shared-alb infra `search-service` depends on, as a realistic multi-wave input. */
+function pilotComponents(): DriverComponent[] {
+  return [
+    { name: ordersTable.name, dependsOn: ordersTable.dependsOn, deploy: ordersTable.deploy },
+    { name: "shared-alb", dependsOn: [], deploy: [] },
+    { name: searchService.name, dependsOn: searchService.dependsOn, deploy: searchService.deploy },
+  ];
+}
+
+interface ParsedStep {
+  name?: string;
+  uses?: string;
+  run?: string;
+  with?: Record<string, unknown>;
+}
+
+interface ParsedJob {
+  "runs-on"?: string;
+  container?: string;
+  needs?: string[];
+  steps: ParsedStep[];
+}
+
+function parsedJobs(yaml: string): Record<string, ParsedJob> {
+  const parsed = parseYAML(yaml);
+  return (parsed.jobs ?? {}) as Record<string, ParsedJob>;
+}
+
+function runLines(job: ParsedJob): string[] {
+  return job.steps.filter((s) => typeof s.run === "string").map((s) => s.run as string);
+}
+
+describe("generateGithubPipeline: cross-stack output threading (artifacts)", () => {
+  test("a depended-upon component uploads its outputs as an artifact; its dependents download and seed from it", () => {
+    // search-service dependsOn shared-alb; orders-table is depended on by nothing.
+    const jobs = parsedJobs(generateGithubPipeline(pilotComponents()).yaml);
+
+    // Producer: shared-alb hands its resolved outputs to a separate downstream
+    // job, so it dumps them and uploads the file as a workflow artifact.
+    const shared = jobs["shared-alb"];
+    expect(runLines(shared).some((line) => line.includes("--dump-outputs shared-alb.outputs.json"))).toBe(true);
+    const uploadStep = shared.steps.find((s) => s.uses === "actions/upload-artifact@v4");
+    expect(uploadStep?.with).toEqual({ name: "shared-alb-outputs", path: "shared-alb.outputs.json" });
+
+    // Consumer: search-service downloads shared-alb's uploaded artifact and
+    // seeds from the dumped file so its stackOutput() references resolve.
+    const svc = jobs["search-service"];
+    const downloadStep = svc.steps.find((s) => s.uses === "actions/download-artifact@v4");
+    expect(downloadStep?.with).toEqual({ name: "shared-alb-outputs", path: "." });
+    expect(runLines(svc).some((line) => line.includes("--seed-outputs shared-alb.outputs.json"))).toBe(true);
+
+    // A component nothing depends on neither dumps nor uploads an artifact.
+    const orders = jobs["orders-table"];
+    expect(runLines(orders).some((line) => line.includes("--dump-outputs"))).toBe(false);
+    expect(orders.steps.some((s) => s.uses === "actions/upload-artifact@v4")).toBe(false);
+    expect(orders.steps.some((s) => s.uses === "actions/download-artifact@v4")).toBe(false);
+    expect(runLines(orders).some((line) => line.includes("--seed-outputs"))).toBe(false);
+  });
+});
+
+describe("generateGithubPipeline: structurally valid YAML", () => {
+  test("produces YAML with an on: trigger and one job per component under jobs:", () => {
+    const result = generateGithubPipeline(pilotComponents(), { env: "staging" });
+
+    const parsed = parseYAML(result.yaml);
+    expect(parsed.on).toEqual({ workflow_dispatch: {} });
+    expect(result.stages).toEqual(["wave-1", "wave-2"]);
+
+    const jobs = parsedJobs(result.yaml);
+    for (const name of ["orders-table", "shared-alb", "search-service"]) {
+      const job = jobs[name];
+      expect(job).toBeDefined();
+      expect(job["runs-on"]).toBe("ubuntu-latest");
+      expect(typeof job.container).toBe("string");
+      expect(Array.isArray(job.steps)).toBe(true);
+      expect(job.steps.length).toBeGreaterThan(0);
+      // Every job starts with a checkout step — a job runs on a fresh runner
+      // with no repo present, unlike GitLab's auto-cloned workspace.
+      expect(job.steps[0].uses).toBe("actions/checkout@v4");
+    }
+  });
+
+  test("every job's trigger step is a single thin invocation, not inlined deploy steps", () => {
+    const result = generateGithubPipeline(pilotComponents(), { env: "staging" });
+    const jobs = parsedJobs(result.yaml);
+
+    for (const job of result.jobs) {
+      const props = jobs[job.jobName];
+      const lines = runLines(props);
+      // The thin trigger: hands off to the component via `chant run`, carrying
+      // no build/publish/apply/cfn-deploy/ecs-update-service keywords — those
+      // verbs live in the component's own composition, never in the YAML.
+      expect(lines.some((line) => line.includes(`chant run --components ${job.component}`))).toBe(true);
+      for (const line of lines) {
+        expect(line).not.toMatch(/docker build|docker push|aws cloudformation|ecs update-service/);
+      }
+    }
+  });
+
+  test("an empty component set produces a pipeline with no jobs", () => {
+    const result = generateGithubPipeline([]);
+    expect(result.stages).toEqual([]);
+    expect(result.jobs).toEqual([]);
+    const jobs = parsedJobs(result.yaml);
+    expect(Object.keys(jobs)).toHaveLength(0);
+  });
+
+  test("propagates a dependency cycle error the same way the interpret driver's own graph resolution does", () => {
+    const cyclical: DriverComponent[] = [
+      { name: "a", dependsOn: ["b"], deploy: [] },
+      { name: "b", dependsOn: ["a"], deploy: [] },
+    ];
+    expect(() => generateGithubPipeline(cyclical)).toThrow(DependencyCycleError);
+  });
+
+  test("propagates an unknown-dependency error for a dangling dependsOn", () => {
+    const dangling: DriverComponent[] = [{ name: "a", dependsOn: ["ghost"], deploy: [] }];
+    expect(() => generateGithubPipeline(dangling)).toThrow(UnknownDependencyError);
+  });
+});
+
+describe("generateGithubPipeline: jobs map to components in wave order", () => {
+  test("independent components share a wave; a dependent lands in a strictly later wave", () => {
+    const components = pilotComponents();
+    const { waves } = resolveComponentGraph(components);
+    const result = generateGithubPipeline(components);
+
+    // Same wave count/membership as the driver's own graph resolution — no
+    // separate, divergent ordering logic in the generator.
+    expect(result.stages).toHaveLength(waves.length);
+
+    const stageOf = (name: string) => result.jobs.find((j) => j.component === name)!.stage;
+    expect(stageOf("orders-table")).toBe(stageOf("shared-alb")); // independent, same wave
+    expect(result.stages.indexOf(stageOf("search-service"))).toBeGreaterThan(
+      result.stages.indexOf(stageOf("shared-alb")),
+    ); // dependent, later wave
+  });
+
+  test("a job's needs: are exactly its component's dependsOn edges, no more and no less", () => {
+    const result = generateGithubPipeline(pilotComponents());
+
+    const ordersJob = result.jobs.find((j) => j.component === "orders-table")!;
+    const albJob = result.jobs.find((j) => j.component === "shared-alb")!;
+    const searchJob = result.jobs.find((j) => j.component === "search-service")!;
+
+    expect(ordersJob.needs).toEqual([]);
+    expect(albJob.needs).toEqual([]);
+    expect(searchJob.needs).toEqual(["shared-alb"]);
+
+    // needs: renders in the YAML too, not just the result object.
+    const jobs = parsedJobs(generateGithubPipeline(pilotComponents()).yaml);
+    expect(jobs["search-service"].needs).toEqual(["shared-alb"]);
+    expect(jobs["orders-table"].needs ?? []).toEqual([]);
+  });
+
+  test("a three-wave fan-out produces three waves in dependency order", () => {
+    const components: DriverComponent[] = [
+      { name: "base", dependsOn: [], deploy: [] },
+      { name: "middle", dependsOn: ["base"], deploy: [] },
+      { name: "top", dependsOn: ["middle"], deploy: [] },
+    ];
+    const result = generateGithubPipeline(components);
+
+    expect(result.stages).toEqual(["wave-1", "wave-2", "wave-3"]);
+    expect(result.jobs.find((j) => j.component === "base")!.stage).toBe("wave-1");
+    expect(result.jobs.find((j) => j.component === "middle")!.stage).toBe("wave-2");
+    expect(result.jobs.find((j) => j.component === "top")!.stage).toBe("wave-3");
+  });
+});
+
+describe("generateGithubPipeline: a cross-cutting change is one generator edit, not per-pipeline", () => {
+  test("adding extraScript (e.g. image signing) appears in every job with no per-component changes", () => {
+    const components = pilotComponents();
+
+    const before = generateGithubPipeline(components, { env: "production" });
+    const beforeJobs = parsedJobs(before.yaml);
+    for (const job of before.jobs) {
+      expect(runLines(beforeJobs[job.jobName])).not.toContain("cosign sign --yes $IMAGE_REF");
+    }
+
+    // Simulates the cross-cutting change from the epic's worked example
+    // ("sign every image"): ONE edit to the generator's options, applied
+    // uniformly, with the component declarations themselves untouched.
+    const after = generateGithubPipeline(components, {
+      env: "production",
+      extraScript: ["cosign sign --yes $IMAGE_REF"],
+    });
+
+    const afterJobs = parsedJobs(after.yaml);
+    expect(after.jobs.length).toBe(before.jobs.length);
+    for (const job of after.jobs) {
+      expect(runLines(afterJobs[job.jobName])).toContain("cosign sign --yes $IMAGE_REF");
+    }
+  });
+
+  test("changing the trigger command (runCommand) updates every job's script uniformly", () => {
+    const components = pilotComponents();
+    const result = generateGithubPipeline(components, {
+      runCommand: ["chant", "run", "--components", "{name}", "--env", "staging", "--temporal"],
+    });
+    const jobs = parsedJobs(result.yaml);
+
+    for (const job of result.jobs) {
+      const lines = runLines(jobs[job.jobName]);
+      // The runCommand prefix reflects in every job; output-threading flags
+      // (--seed-outputs/--dump-outputs) may be appended per the dependency graph.
+      expect(lines[0].startsWith(`chant run --components ${job.component} --env staging --temporal`)).toBe(true);
+    }
+  });
+
+  test("changing beforeScript (e.g. a registry login) prepends to every job uniformly", () => {
+    const components = pilotComponents();
+    const result = generateGithubPipeline(components, {
+      beforeScript: ["echo $REGISTRY_PASSWORD | docker login -u $REGISTRY_USER --password-stdin $REGISTRY"],
+    });
+    const jobs = parsedJobs(result.yaml);
+
+    for (const job of result.jobs) {
+      const lines = runLines(jobs[job.jobName]);
+      expect(lines[0]).toMatch(/docker login/);
+    }
+  });
+});
+
+describe("generateGithubPipeline: options", () => {
+  test("emits a top-level env: block when variables are provided", () => {
+    const result = generateGithubPipeline(pilotComponents(), {
+      variables: { CHANT_ENV: "staging" },
+    });
+    const parsed = parseYAML(result.yaml);
+    expect(parsed.env).toEqual({ CHANT_ENV: "staging" });
+  });
+
+  test("omits the env: block when no variables are provided", () => {
+    const result = generateGithubPipeline(pilotComponents());
+    const parsed = parseYAML(result.yaml);
+    expect(parsed.env).toBeUndefined();
+  });
+
+  test("uses a custom container image for every job when provided", () => {
+    const result = generateGithubPipeline(pilotComponents(), { image: "chant/cli:latest" });
+    const jobs = parsedJobs(result.yaml);
+    for (const job of result.jobs) {
+      expect(jobs[job.jobName].container).toBe("chant/cli:latest");
+    }
+  });
+
+  test("defaults env to production when not provided", () => {
+    const result = generateGithubPipeline(pilotComponents());
+    const jobs = parsedJobs(result.yaml);
+    expect(runLines(jobs["shared-alb"])[0]).toContain("--env production");
+  });
+});

package/src/components/generate-pipeline.ts

@@ -0,0 +1,175 @@
+/**
+ * Generate mode — component → GitHub Actions workflow YAML (#891, epic #885).
+ *
+ * The github counterpart to the gitlab generator (`../../gitlab/src/components/generate-pipeline.ts`,
+ * #563/#688): the same `chant build --components --generate <lexicon>` seam,
+ * synthesizing a **thin** `.github/workflows/*.yml` from the discovered
+ * component graph instead of interpreting it directly.
+ *
+ * The generated workflow is a trigger, not the deploy logic:
+ *  - Ordering + parallel-safe waves are resolved once, generically, by
+ *    `resolveComponentGraph` (core's driver) — the exact function the local
+ *    interpret driver and the gitlab generator both use. This module does not
+ *    re-derive or duplicate that graph logic.
+ *  - GitHub Actions has no `stage` concept, so wave ordering is expressed
+ *    entirely through `needs:` edges between jobs: one job per component,
+ *    with `needs:` pointing at the jobs for its direct `dependsOn` entries.
+ *    Independent components therefore run in parallel, and dependents wait
+ *    on their dependencies via GitHub's own `needs:` scheduling.
+ *    `ComponentPipelineResult.stages` is still populated with the wave-ordered
+ *    names (one per wave) purely for parity with gitlab's machine-readable
+ *    `--format json` view — GitHub's YAML itself has no `stages:` section.
+ *  - Each job's trigger step is exactly one invocation that hands off to the
+ *    component's own composition (`chant run --components <name> ...` by
+ *    default) — never inlined build/publish/apply steps. The deploy logic
+ *    lives in the component's `deploy` phases and the capabilities they
+ *    reference, not in this YAML.
+ *  - A component that something else depends on can't hand its resolved
+ *    stack outputs to a dependent in-memory, since each job is a separate
+ *    GitHub Actions runner. It dumps its outputs to a file and uploads that
+ *    file as a workflow artifact (`actions/upload-artifact`); each direct
+ *    dependent downloads it (`actions/download-artifact`) and seeds from it,
+ *    so a `stackOutput()` / `@<dep>.publish.*` reference still resolves even
+ *    though the producer ran in a different job. This mirrors the dump/seed
+ *    model `cli-support.ts` (`runComponents`'s `componentOutputs`) already
+ *    uses, and matches gitlab's artifact-passing 1:1 in intent — only the
+ *    transport differs (explicit upload/download steps vs. GitLab's implicit
+ *    `needs:` artifact passing).
+ *
+ * Cross-cutting changes (e.g. "sign every image before deploy") are made by
+ * editing `GenerateGithubOptions.extraScript`/`beforeScript` (or the
+ * component's own composition) ONCE here — never per generated job. See
+ * `generate-pipeline.test.ts`'s "cross-cutting change" cases for a
+ * demonstration: one generator-option edit reflects in every job without
+ * touching the component declarations.
+ */
+
+import { emitYAML } from "@intentius/chant/yaml";
+import { resolveComponentGraph, type DriverComponent } from "@intentius/chant/components/driver";
+import type {
+  ComponentPipelineJob as GeneratedJob,
+  ComponentPipelineOptions as GenerateGithubOptions,
+  ComponentPipelineResult as GenerateGithubResult,
+} from "@intentius/chant/lexicon";
+
+export type { GeneratedJob, GenerateGithubOptions, GenerateGithubResult };
+
+/** GitHub Actions job ids must match `[a-zA-Z_][a-zA-Z0-9_-]*`; component names are already kebab-case in every fixture, but normalize defensively (mirrors gitlab's `toJobName`). */
+function toJobName(componentName: string): string {
+  return componentName.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+const DEFAULT_IMAGE = "node:22-slim";
+
+/** The file a producer dumps its resolved outputs to, and a dependent seeds from — one per component, matching gitlab's naming so both generators produce interchangeable artifacts. */
+function outputsFile(name: string): string {
+  return `${name}.outputs.json`;
+}
+
+/** The workflow artifact name a producer's dumped outputs are uploaded under. */
+function artifactName(name: string): string {
+  return `${name}-outputs`;
+}
+
+/**
+ * Synthesize a `.github/workflows/*.yml` pipeline from a set of components:
+ * one job per component, `needs:` expressing the wave-ordered dependency DAG
+ * from `resolveComponentGraph`. Throws `DependencyCycleError`/
+ * `UnknownDependencyError` (from core's driver) exactly like the interpret
+ * driver and the gitlab generator do, since all three consume the same graph
+ * resolution. Wired into core's generate mode via the github lexicon plugin's
+ * `generateComponentPipeline` (../plugin.ts).
+ */
+export function generateGithubPipeline(
+  components: DriverComponent[],
+  options: GenerateGithubOptions = {},
+): GenerateGithubResult {
+  const env = options.env ?? "production";
+  const image = options.image ?? DEFAULT_IMAGE;
+  const runCommand = options.runCommand ?? ["chant", "run", "--components", "{name}", "--env", env];
+  const beforeScript = options.beforeScript ?? [];
+  const extraScript = options.extraScript ?? [];
+
+  const { waves } = resolveComponentGraph(components);
+  const byName = new Map(components.map((c) => [c.name, c]));
+
+  // Components that something else depends on must hand their resolved outputs
+  // (stack outputs, published artifact refs) to their dependents, which run as
+  // separate jobs on separate runners. Each such producer dumps its outputs to
+  // a file and uploads it as a workflow artifact; each dependent downloads that
+  // artifact and seeds from it, so a `stackOutput()` / `@<dep>.publish.*`
+  // reference resolves even though the producer ran in a different job.
+  // Without this, a single-component job has no in-memory outputs for its
+  // dependencies — see epic #551 / the adopt-alb-services example.
+  const dependedUpon = new Set<string>();
+  for (const c of components) for (const dep of c.dependsOn ?? []) dependedUpon.add(dep);
+
+  const stages = waves.map((_, i) => `wave-${i + 1}`);
+  const jobs: GeneratedJob[] = [];
+  const jobNameByComponent = new Map<string, string>();
+  for (const wave of waves) {
+    for (const name of wave) jobNameByComponent.set(name, toJobName(name));
+  }
+
+  const jobsDoc: Record<string, unknown> = {};
+
+  waves.forEach((wave, waveIndex) => {
+    const stage = stages[waveIndex];
+    for (const name of wave) {
+      const component = byName.get(name)!;
+      const jobName = jobNameByComponent.get(name)!;
+      const needs = (component.dependsOn ?? []).map((dep) => jobNameByComponent.get(dep)!).sort();
+
+      jobs.push({ jobName, component: name, stage, needs });
+
+      // Build the run invocation, then append output-threading flags: seed from
+      // each dependency's dumped outputs (downloaded as an artifact below), and
+      // dump this component's own outputs if a dependent will need them.
+      const runParts = runCommand.map((part) => part.replace("{name}", name));
+      for (const dep of component.dependsOn ?? []) runParts.push("--seed-outputs", outputsFile(dep));
+      if (dependedUpon.has(name)) runParts.push("--dump-outputs", outputsFile(name));
+
+      // One step per script line — mirrors gitlab's `script:` array of
+      // discrete shell lines, rather than a single multi-line `run:` block, so
+      // each line is independently inspectable (and machine-parseable).
+      const steps: Array<Record<string, unknown>> = [{ uses: "actions/checkout@v4" }];
+
+      for (const dep of component.dependsOn ?? []) {
+        steps.push({
+          name: `Download ${dep} outputs`,
+          uses: "actions/download-artifact@v4",
+          with: { name: artifactName(dep), path: "." },
+        });
+      }
+
+      for (const line of beforeScript) steps.push({ run: line });
+      steps.push({ run: runParts.join(" ") });
+      for (const line of extraScript) steps.push({ run: line });
+
+      if (dependedUpon.has(name)) {
+        steps.push({
+          name: `Upload ${name} outputs`,
+          uses: "actions/upload-artifact@v4",
+          with: { name: artifactName(name), path: outputsFile(name) },
+        });
+      }
+
+      const jobProps: Record<string, unknown> = {
+        "runs-on": "ubuntu-latest",
+        ...(needs.length > 0 ? { needs } : {}),
+        container: image,
+        steps,
+      };
+      jobsDoc[jobName] = jobProps;
+    }
+  });
+
+  const sections: string[] = [];
+  sections.push("on:" + emitYAML({ workflow_dispatch: {} }, 1));
+  if (options.variables && Object.keys(options.variables).length > 0) {
+    sections.push("env:" + emitYAML(options.variables, 1));
+  }
+  sections.push("jobs:" + emitYAML(jobsDoc, 1));
+
+  return { yaml: sections.join("\n\n") + "\n", stages, jobs };
+}

package/src/plugin.ts

@@ -31,10 +31,13 @@ import { githubHover } from "./lsp/hover";
 import { GitHubActionsParser } from "./import/parser";
 import { GitHubActionsGenerator } from "./import/generator";
 import { githubContextTools } from "./mcp/context-tools";
+import { generateGithubPipeline } from "./components/generate-pipeline";
 
 export const githubPlugin: LexiconPlugin = {
   name: "github",
   auditCatalog: () => githubAuditCatalog,
+  // Generate mode (#891): synthesize a GitHub Actions workflow from the component graph.
+  generateComponentPipeline: (components, options) => generateGithubPipeline(components, options),
   serializer: githubSerializer,
 
   lintRules(): LintRule[] {