gagen 0.3.1 → 0.3.2

package/README.md

@@ -16,7 +16,7 @@ initial code is more easily maintainable.
 ## Basic usage
 
 ```ts
-#!/usr/bin/env -S deno run --allow-read=ci.yml --allow-write=ci.yml
+#!/usr/bin/env -S deno run --allow-read=ci.generated.yml --allow-write=ci.generated.yml
 import { conditions, createWorkflow, step } from "gagen";
 
 const checkout = step({
@@ -56,17 +56,17 @@ createWorkflow({
     steps: [lint, test],
   }],
 }).writeOrLint({
-  filePath: new URL("./ci.yml", import.meta.url),
-  header: "# GENERATED BY ./ci.generate.ts -- DO NOT DIRECTLY EDIT",
+  filePath: new URL("./ci.generated.yml", import.meta.url),
+  header: "# GENERATED BY ./ci.ts -- DO NOT DIRECTLY EDIT",
 });
 ```
 
-This generates a `ci.yml` with steps in the correct order and figures out that
-it should only install deno when the lint step should be run and it defers that
-step only until it's necessary.
+This generates a `ci.generated.yml` with steps in the correct order and figures
+out that it should only install deno when the lint step should be run and it
+defers that step only until it's necessary.
 
 ```yaml
-# GENERATED BY ./ci.generate.ts -- DO NOT DIRECTLY EDIT
+# GENERATED BY ./ci.ts -- DO NOT DIRECTLY EDIT
 
 name: ci
 on:
@@ -92,15 +92,15 @@ jobs:
 # gagen:pin denoland/setup-deno@v2 = 667a34cdef165d8d2b2e98dde39547c9daac7282
 ```
 
-When run normally, this writes `ci.yml`. When run with `--lint`, it reads the
-existing file and compares the parsed YAML — exiting with a non-zero code if
-they differ. This lets you add a CI step to verify the generated file is up to
-date:
+When run normally, this writes `ci.generated.yml`. When run with `--lint`, it
+reads the existing file and compares the parsed YAML — exiting with a non-zero
+code if they differ. This lets you add a CI step to verify the generated file is
+up to date:
 
 ```ts
 const lintStep = step({
   name: "Lint CI generation",
-  run: "./.github/workflows/ci.generate.ts --lint",
+  run: "./.github/workflows/ci.ts --lint",
 });
 ```
 
@@ -133,7 +133,7 @@ dependencies.
 To force re-resolving all pins, run with the `--update-pins` flag:
 
 ```sh
-./ci.generate.ts --update-pins
+./ci.ts --update-pins
 ```
 
 Pinning can be disabled by setting `pinDeps` to `false`:
@@ -238,7 +238,7 @@ const runner = os.equals("linux").then("ubuntu-latest")
 
 // use in job config
 createWorkflow({
-  ...,
+  // ...,
   jobs: [
     { id: "build", runsOn: runner, steps: [test] },
   ],
@@ -411,17 +411,16 @@ Error: Cycle detected in step ordering: A → B → A
 `defineMatrix()` gives you typed access to matrix values:
 
 ```ts
-import { defineMatrix } from "gagen";
+import { createWorkflow, defineMatrix } from "gagen";
 
 const matrix = defineMatrix({
   include: [
-    { os: "linux", runner: "ubuntu-latest" },
-    { os: "macos", runner: "macos-latest" },
+    { runner: "ubuntu-latest" },
+    { runner: "macos-latest" },
   ],
 });
 
-matrix.os; // ExpressionValue("matrix.os") — autocompletes
-matrix.runner; // ExpressionValue("matrix.runner")
+matrix.runner; // ExpressionValue("matrix.runner") — autocompletes
 matrix.foo; // TypeScript error — not a matrix key
 
 createWorkflow({
@@ -499,57 +498,6 @@ createWorkflow({
 Permission scopes (`contents`, `packages`, `id-token`, etc.) and levels (`read`,
 `write`, `none`) are fully typed.
 
-## Reusable workflows
-
-Define reusable workflows with `workflow_call` triggers and call them from other
-jobs:
-
-```ts
-import { createWorkflow } from "gagen";
-
-// define a reusable workflow
-const wf = createWorkflow({
-  name: "Reusable Build",
-  on: {
-    workflow_call: {
-      inputs: {
-        environment: { type: "string", required: true },
-        debug: { type: "boolean", default: false },
-      },
-      outputs: {
-        build_id: {
-          description: "The build ID",
-          value: "${{ jobs.build.outputs.id }}",
-        },
-      },
-      secrets: {
-        deploy_key: { required: true },
-      },
-    },
-  },
-});
-```
-
-Call a reusable workflow from a job using `uses` instead of `runsOn`:
-
-```ts
-const wf = createWorkflow({
-  name: "CI",
-  on: ["push", "pull_request"],
-  jobs: [
-    {
-      id: "build",
-      uses: "octo-org/example/.github/workflows/build.yml@main",
-      with: { environment: "production" },
-      secrets: "inherit",
-    },
-  ],
-});
-```
-
-Reusable jobs support `with`, `secrets` (either `"inherit"` or a record), and
-all common job fields (`name`, `needs`, `if`, `permissions`, `concurrency`).
-
 ## Artifacts
 
 Link upload and download artifact steps across jobs with automatic `needs`
@@ -564,22 +512,30 @@ import {
 
 const artifact = defineArtifact("build-output");
 
-const buildStep = step({ name: "Build", run: "make build" });
-const upload = artifact.upload({ path: "dist/" });
-
-const download = artifact.download({ dirPath: "output/" });
-const deployStep = step.dependsOn(download)({
-  name: "Deploy",
-  run: "make deploy",
-});
-
 const wf = createWorkflow({
   name: "CI",
   on: ["push", "pull_request"],
   jobs: [
-    { id: "build", runsOn: "ubuntu-latest", steps: [buildStep, upload] },
-    // needs: [build] is inferred automatically from the artifact link
-    { id: "deploy", runsOn: "ubuntu-latest", steps: [deployStep] },
+    {
+      id: "build",
+      runsOn: "ubuntu-latest",
+      steps: [
+        step({ name: "Build", run: "make build" }),
+        artifact.upload({ path: "dist/" }),
+      ],
+    },
+    // `needs: [build]` is inferred automatically from the artifact link
+    {
+      id: "deploy",
+      runsOn: "ubuntu-latest",
+      steps: [
+        artifact.download({ dirPath: "output/" }),
+        step({
+          name: "Deploy",
+          run: "make deploy",
+        }),
+      ],
+    },
   ],
 });
 ```
@@ -601,8 +557,8 @@ const artifact = defineArtifact("build-output", {
 ```ts
 const matrix = defineMatrix({
   include: [
-    { os: "linux", runner: "ubuntu-latest" },
-    { os: "macos", runner: "macos-latest" },
+    { runner: "ubuntu-latest" },
+    { runner: "macos-latest" },
   ],
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gagen",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Generate complex GitHub Actions YAML files using a declarative API.",
   "repository": {
     "type": "git",