@intentius/chant-lexicon-github 0.0.18 → 0.0.24

package/src/skills/chant-github.md

@@ -0,0 +1,594 @@
+---
+skill: chant-github
+description: Build, validate, and deploy GitHub Actions workflows from a chant project
+user-invocable: true
+---
+
+# GitHub Actions Operational Playbook
+
+## How chant and GitHub Actions relate
+
+chant is a **synthesis compiler** — it compiles TypeScript source files into `.github/workflows/*.yml` (YAML). `chant build` does not call GitHub APIs; synthesis is pure and deterministic. Your job as an agent is to bridge synthesis and deployment:
+
+- Use **chant** for: build, lint, diff (local YAML comparison)
+- Use **git + gh CLI** for: push, pull requests, workflow monitoring, run logs, deployments, and all GitHub operations
+
+The source of truth for workflow configuration is the TypeScript in `src/`. The generated `.github/workflows/*.yml` files are intermediate artifacts — never edit them by hand.
+
+## Scaffolding a new project
+
+### Initialize with a template
+
+```bash
+chant init --lexicon github                       # default: Workflow + Job skeleton
+chant init --lexicon github --template node-ci     # NodeCI composite
+chant init --lexicon github --template docker-build # DockerBuild composite
+```
+
+This creates `src/` with chant workflow definitions. It does NOT create application files — you bring your own app code.
+
+### Available init templates
+
+| Template | What it generates | Best for |
+|----------|-------------------|----------|
+| *(default)* | `pipeline.ts` with Workflow, Job, Checkout, SetupNode | Custom workflows from scratch |
+| `node-ci` | `NodeCI` composite with checkout, setup-node, install, build, test | Node.js apps |
+| `docker-build` | Workflow + Job with checkout, docker build step | Containerized apps |
+
+### Project layout after init
+
+```
+src/
+  pipeline.ts          # chant source — your workflow definition
+.github/
+  workflows/
+    ci.yml             # generated by chant build (do not edit)
+package.json           # your app code
+```
+
+## Building and validating
+
+### Build the workflow
+
+```bash
+chant build src/ --output .github/workflows/ci.yml
+```
+
+Options:
+- `--format yaml` — emit YAML (default for GitHub)
+- `--watch` — rebuild on source changes
+- `--output <path>` — write to a specific file
+
+### Lint the source
+
+```bash
+chant lint src/
+```
+
+Options:
+- `--fix` — auto-fix violations where possible
+- `--format sarif` — SARIF output for CI integration
+- `--watch` — re-lint on changes
+
+### Validate with actionlint
+
+After `chant build`, run `actionlint` to catch GitHub-specific YAML issues that chant's lint rules do not cover:
+
+```bash
+actionlint .github/workflows/ci.yml
+```
+
+Install: `brew install actionlint` (macOS) or `go install github.com/rhysd/actionlint/cmd/actionlint@latest`.
+
+### What each step catches
+
+| Step | Catches | When to run |
+|------|---------|-------------|
+| `chant lint` | Use typed composites (GHA001), use Expression helpers (GHA002), hardcoded tokens (GHA003), inline matrix extraction (GHA004), deep nesting (GHA005), raw expressions (GHA008), missing version inputs (GHA010), deprecated action versions (GHA012), missing timeout (GHA014), suggest caching (GHA015), concurrency without group (GHA016), potential secrets in source (GHA020) | Every edit |
+| `chant build` | Post-synth checks: duplicate workflow names (GHA006), too many jobs per file (GHA007), empty matrix dimensions (GHA009), invalid needs references (GHA011), missing permissions (GHA017), checkout with pull_request_target (GHA018), circular needs chains (GHA019), checkout without pinned SHA (GHA021), job without timeout (GHA022), deprecated set-output (GHA023), deploy without concurrency (GHA024), pull_request_target without restrictions (GHA025), secrets without environment protection (GHA026), cleanup steps without `if: always()` (GHA027), workflow with no triggers (GHA028) | Before push |
+| `actionlint` | GitHub-specific YAML schema errors, unknown action inputs, shell syntax, expression type errors, runner label validation | Before merge |
+
+Always run all three before deploying. `chant lint` catches TypeScript-level issues, `chant build` catches structural problems in the synthesized YAML, and `actionlint` catches GitHub-specific schema violations.
+
+## Deploying to GitHub
+
+### What goes in the GitHub repo
+
+The GitHub repo needs TWO things:
+1. **`.github/workflows/*.yml`** — generated by `chant build`
+2. **Your application files** — whatever the workflow scripts reference
+
+chant only generates the YAML. Application files (`package.json`, `Dockerfile`, source code, tests) are your responsibility.
+
+### Typical project structure in the GitHub repo
+
+**Node.js project:**
+```
+.github/workflows/ci.yml   # generated by chant
+package.json                # your app's package.json with build/test scripts
+package-lock.json           # required if using npm ci (NodeCI default)
+src/                        # your app code
+test/                       # your tests
+```
+
+**Python project:**
+```
+.github/workflows/ci.yml
+requirements.txt            # must include pytest, pytest-cov if using PythonCI defaults
+app.py
+test_app.py
+```
+
+**Go project:**
+```
+.github/workflows/ci.yml
+go.mod
+go.sum
+main.go
+main_test.go
+```
+
+**Docker project:**
+```
+.github/workflows/ci.yml
+Dockerfile
+src/                        # your app source
+```
+
+### Important: npm ci vs npm install
+
+The `NodeCI` composite defaults to `npm ci`, which requires a `package-lock.json` in the repo. If your repo does not have a lockfile, override with:
+
+```typescript
+NodeCI({
+  installCommand: "npm install",  // use instead of npm ci
+  ...
+})
+```
+
+Or generate a lockfile: `npm install && git add package-lock.json`.
+
+### Step-by-step: push to GitHub
+
+```bash
+# 1. Build the YAML from chant source
+chant build src/ --output .github/workflows/ci.yml
+
+# 2. Initialize git (if needed) and commit everything
+git init -b main
+git add .github/workflows/ci.yml package.json src/ test/  # add your app files
+git commit -m "Initial workflow"
+
+# 3. Push to GitHub
+git remote add origin git@github.com:YOUR_ORG/YOUR_REPO.git
+git push -u origin main
+```
+
+The workflow triggers automatically on push (if configured with a push trigger). Do NOT commit the chant `src/` directory, `node_modules/`, or `.chant/` to the application repo — those are local development files.
+
+## Diffing and change preview
+
+### Local diff
+
+Compare generated workflow YAML against the version on the remote branch:
+
+```bash
+# Build the proposed config
+chant build src/ --output .github/workflows/ci.yml
+
+# Diff against the remote version
+git diff origin/main -- .github/workflows/ci.yml
+```
+
+### Pull request preview
+
+Push to a branch and open a pull request. Reviewers can see the exact YAML diff in the PR files tab. This is the safest way to preview workflow changes for production:
+
+```bash
+git checkout -b feature/workflow-update
+chant build src/ --output .github/workflows/ci.yml
+git add .github/workflows/ci.yml
+git commit -m "Update workflow"
+git push -u origin feature/workflow-update
+gh pr create --title "Update CI workflow" --body "Workflow changes generated by chant"
+```
+
+### Safe preview checklist
+
+Before merging workflow changes, verify:
+1. All jobs have valid `runs-on:` labels
+2. `needs:` references point to existing job names
+3. `on:` triggers match the intended branches/events
+4. Environment names match those configured in repo settings
+5. Docker images referenced in jobs are accessible from GitHub runners
+6. Secrets referenced in `${{ secrets.* }}` exist in repository or environment settings
+7. Permissions are scoped to least privilege
+
+## Composites reference
+
+Composites are high-level building blocks that emit pre-wired Workflow + Job combinations.
+
+| Composite | What it produces | Key props |
+|-----------|-----------------|-----------|
+| `NodeCI` | Workflow + job: checkout, setup-node, install, build, test | `nodeVersion`, `packageManager`, `buildScript`, `testScript`, `installCommand` |
+| `NodePipeline` | Workflow + separate build/test jobs with artifact handoff | `nodeVersion`, `packageManager`, `buildScript`, `testScript`, `buildArtifactPaths`, `artifactName` |
+| `BunPipeline` | NodePipeline preset with `packageManager: "bun"` | Same as NodePipeline |
+| `PnpmPipeline` | NodePipeline preset with `packageManager: "pnpm"` | Same as NodePipeline |
+| `YarnPipeline` | NodePipeline preset with `packageManager: "yarn"` | Same as NodePipeline |
+| `PythonCI` | Workflow + test job + optional lint job (ruff) | `pythonVersion`, `testCommand`, `lintCommand`, `requirementsFile`, `usePoetry` |
+| `GoCI` | Workflow + build/test/lint jobs | `goVersion`, `testCommand`, `buildCommand`, `lintCommand` |
+| `DockerBuild` | Workflow + job: checkout, registry login, buildx, metadata, build-push | `tag`, `dockerfile`, `registry`, `imageName`, `platforms`, `push` |
+| `DeployEnvironment` | Deploy job + cleanup job with concurrency control | `name`, `deployScript`, `cleanupScript`, `url`, `concurrencyGroup` |
+
+### Utility composites
+
+| Composite | Purpose | Key props |
+|-----------|---------|-----------|
+| `Checkout` | `actions/checkout@v4` step | `fetchDepth`, `ref`, `token` |
+| `SetupNode` | `actions/setup-node@v4` step | `nodeVersion`, `cache` |
+| `SetupGo` | `actions/setup-go@v5` step | `goVersion` |
+| `SetupPython` | `actions/setup-python@v5` step | `pythonVersion`, `cache` |
+| `CacheAction` | `actions/cache` step | `path`, `key`, `restoreKeys` |
+| `UploadArtifact` | `actions/upload-artifact` step | `name`, `path`, `retentionDays` |
+| `DownloadArtifact` | `actions/download-artifact` step | `name`, `path` |
+
+### Composite usage example
+
+```typescript
+import { NodeCI } from "@intentius/chant-lexicon-github";
+
+export const app = NodeCI({
+  nodeVersion: "22",
+  installCommand: "npm ci",
+  buildScript: "build",
+  testScript: "test",
+});
+```
+
+### Customizing composites with defaults
+
+Every composite accepts a `defaults` prop to override job or workflow properties:
+
+```typescript
+NodeCI({
+  nodeVersion: "22",
+  defaults: {
+    job: { "runs-on": "ubuntu-24.04", "timeout-minutes": 15 },
+    workflow: { name: "My Custom CI" },
+  },
+})
+```
+
+## Workflow run monitoring
+
+Use the `gh` CLI for all monitoring. Do not use raw API calls.
+
+### List recent workflow runs
+
+```bash
+# All runs for the repo
+gh run list --limit 10
+
+# Runs for a specific workflow
+gh run list --workflow ci.yml --limit 5
+
+# Runs for a specific branch
+gh run list --branch main --limit 5
+
+# Filter by status
+gh run list --status failure --limit 5
+```
+
+### View a specific run
+
+```bash
+# Summary view
+gh run view <run-id>
+
+# Show job details
+gh run view <run-id> --json jobs --jq '.jobs[] | {name, status, conclusion}'
+```
+
+### Watch a run in progress
+
+```bash
+gh run watch <run-id>
+```
+
+This streams status updates until the run completes. Useful after pushing a workflow change.
+
+### Read job logs
+
+```bash
+# View logs for a specific run
+gh run view <run-id> --log
+
+# View logs for a failed run (filtered to failures)
+gh run view <run-id> --log-failed
+
+# View logs for a specific job within a run
+gh run view <run-id> --job <job-id> --log
+```
+
+### Download artifacts from a run
+
+```bash
+# Download all artifacts
+gh run download <run-id>
+
+# Download a specific artifact
+gh run download <run-id> --name build-output
+```
+
+### Re-run a failed workflow
+
+```bash
+# Re-run all jobs
+gh run rerun <run-id>
+
+# Re-run only failed jobs
+gh run rerun <run-id> --failed
+```
+
+### Cancel a running workflow
+
+```bash
+gh run cancel <run-id>
+```
+
+## Environment protection and deployment
+
+### Configuring environments
+
+Environments are configured in the GitHub repo settings (Settings > Environments), not in YAML. The workflow references them by name:
+
+```typescript
+DeployEnvironment({
+  name: "production",
+  url: "https://example.com",
+  deployScript: "./deploy.sh",
+})
+```
+
+### Environment protection rules
+
+Configure these in the GitHub UI (or via `gh api`):
+
+- **Required reviewers** — one or more approvers must approve before deploy
+- **Wait timer** — delay in minutes before deployment proceeds
+- **Branch restrictions** — limit which branches can deploy to this environment
+- **Deployment branch policy** — restrict to specific branches or tags
+
+### Deployment flow: dev -> staging -> production
+
+```typescript
+import { DeployEnvironment } from "@intentius/chant-lexicon-github";
+
+export const deployDev = DeployEnvironment({
+  name: "dev",
+  deployScript: "./deploy.sh dev",
+  url: "https://dev.example.com",
+});
+
+export const deployStaging = DeployEnvironment({
+  name: "staging",
+  deployScript: "./deploy.sh staging",
+  url: "https://staging.example.com",
+});
+
+export const deployProd = DeployEnvironment({
+  name: "production",
+  deployScript: "./deploy.sh production",
+  url: "https://example.com",
+});
+```
+
+Add `needs:` to chain the deploy jobs in sequence, gated by environment protection rules configured in the GitHub UI.
+
+### Checking deployment status
+
+```bash
+# List deployments for an environment
+gh api repos/{owner}/{repo}/deployments --jq '.[0:5] | .[] | {id, environment, sha: .sha[0:8], created_at}'
+
+# Check deployment status
+gh api repos/{owner}/{repo}/deployments/<deploy-id>/statuses --jq '.[0] | {state, description}'
+```
+
+## Deploying workflow changes
+
+### Safe path (production workflows)
+
+1. Build: `chant build src/ --output .github/workflows/ci.yml`
+2. Lint: `chant lint src/`
+3. Validate: `actionlint .github/workflows/ci.yml`
+4. Push to feature branch: `git push -u origin feature/workflow-update`
+5. Open PR: `gh pr create --title "Update CI workflow"`
+6. Review YAML diff in PR, wait for status checks
+7. Merge — workflow runs on the default branch
+
+### Fast path (dev/iteration)
+
+```bash
+chant build src/ --output .github/workflows/ci.yml
+git add .github/workflows/ci.yml && git commit -m "Update workflow" && git push
+```
+
+### Which path to use
+
+| Scenario | Path |
+|----------|------|
+| Production workflow with deploy jobs | Safe path (PR review) |
+| Workflow with environment/secrets changes | Safe path (PR review) |
+| Dev/test workflow iteration | Fast path (direct push) |
+| Workflow with protected environments | Safe path + branch protection |
+
+## Rollback patterns
+
+### Revert the workflow change
+
+The simplest rollback: revert the commit that introduced the bad workflow.
+
+```bash
+# Find the commit that broke things
+gh run list --status failure --limit 5
+git log --oneline -10 -- .github/workflows/
+
+# Revert it
+git revert <bad-commit-sha>
+git push
+```
+
+### Re-run a previous successful workflow
+
+If the workflow YAML was fine but the run failed due to a transient issue:
+
+```bash
+# Find the last successful run
+gh run list --status success --workflow ci.yml --limit 1
+
+# Re-run it
+gh run rerun <run-id>
+```
+
+### Rebuild from a previous chant source version
+
+If you version-control the chant `src/` alongside the generated YAML:
+
+```bash
+# Check out the previous working version of chant source
+git checkout <good-commit-sha> -- src/
+
+# Rebuild
+chant build src/ --output .github/workflows/ci.yml
+
+# Commit the rollback
+git add .github/workflows/ci.yml
+git commit -m "Rollback workflow to known-good version"
+git push
+```
+
+### Emergency: disable a workflow
+
+```bash
+gh workflow disable ci.yml
+```
+
+Re-enable later: `gh workflow enable ci.yml`.
+
+## Troubleshooting decision tree
+
+### Step 1: Check the run status
+
+```bash
+gh run list --limit 5
+```
+
+### Step 2: Branch on status
+
+- **`in_progress` / `queued`** — Wait. Do not take action while the run is in progress.
+- **`failure`** — Read the failed job logs (Step 3).
+- **`success`** — Run is healthy. If behavior is wrong, check job scripts and workflow triggers.
+- **`cancelled`** — Re-run if needed: `gh run rerun <run-id>`
+- **No runs appear** — Workflow was not triggered. Check `on:` triggers and branch filters.
+
+### Step 3: Read failed job logs
+
+```bash
+# View failure output
+gh run view <run-id> --log-failed
+```
+
+### Step 4: Diagnose by error pattern
+
+| Error pattern | Likely cause | Fix |
+|---------------|-------------|-----|
+| `no matching runner` | No runner with matching `runs-on` label | Check runner label, use `ubuntu-latest` for hosted |
+| `image not found` / `pull access denied` | Docker image not found or auth failed | Check image name, registry credentials |
+| `Process completed with exit code 1` | Script command failed | Read full job log for the failing command |
+| `Error: ENOENT` / `file not found` | Missing application file | Ensure app files are committed to the repo |
+| `npm ERR! could not determine executable` | Missing `package-lock.json` for `npm ci` | Run `npm install` and commit lockfile, or use `installCommand: "npm install"` |
+| `Error: Input required and not supplied` | Action input missing | Check `with:` values for the action step |
+| `Node.js 16 actions are deprecated` | Action uses Node 16 runtime | Upgrade to latest action version (GHA012) |
+| `Unrecognized named-value: 'env'` | Expression context error | Use correct context (`github`, `secrets`, `env`, `steps`) |
+| `This request was denied` / `403` | Insufficient GITHUB_TOKEN permissions | Add explicit `permissions:` block to workflow or job |
+| `annotations` / `reviewdog` errors | Status check misconfiguration | Check `pull-requests: write` permission |
+| `all jobs filtered` | All jobs skipped by `if:` conditions | Check `on:` triggers and job-level `if:` expressions |
+| `job needs non-existent job` | `needs:` points to wrong job name | Check job names in the synthesized YAML (GHA011) |
+| `circular dependency detected` | Jobs form a needs cycle | Break the cycle in chant source (GHA019) |
+| `yaml: line N: ...` | YAML syntax error | Run `actionlint` and `chant lint` to find the issue |
+| `::set-output` deprecation warning | Using old output mechanism | Switch to `$GITHUB_OUTPUT` (GHA023) |
+| `timeout` / `The job running on runner ... has exceeded the maximum execution time` | Job exceeded timeout | Add or increase `timeout-minutes` |
+
+## Quick reference commands
+
+### Full build-to-deploy pipeline
+
+```bash
+# 1. Lint
+chant lint src/
+
+# 2. Build
+chant build src/ --output .github/workflows/ci.yml
+
+# 3. Validate with actionlint
+actionlint .github/workflows/ci.yml
+
+# 4. Push to feature branch
+git checkout -b feature/workflow-update
+git add .github/workflows/ci.yml
+git commit -m "Update workflow"
+git push -u origin feature/workflow-update
+
+# 5. Open PR
+gh pr create --title "Update CI workflow" --body "Workflow changes generated by chant"
+
+# 6. Watch the PR checks
+gh pr checks
+
+# 7. Merge when green
+gh pr merge --squash
+```
+
+### Monitoring commands
+
+```bash
+gh run list --limit 10                      # recent runs
+gh run list --workflow ci.yml --limit 5     # runs for a specific workflow
+gh run view <run-id>                        # run summary
+gh run view <run-id> --log-failed           # failed job logs
+gh run watch <run-id>                       # stream live status
+gh run rerun <run-id> --failed              # re-run failed jobs
+gh run cancel <run-id>                      # cancel a run
+gh run download <run-id> --name <artifact>  # download artifact
+```
+
+### Workflow management commands
+
+```bash
+gh workflow list                            # list all workflows
+gh workflow view ci.yml                     # view workflow details
+gh workflow run ci.yml                      # manually trigger (needs workflow_dispatch)
+gh workflow disable ci.yml                  # disable a workflow
+gh workflow enable ci.yml                   # re-enable a workflow
+```
+
+### Environment and deployment commands
+
+```bash
+gh api repos/{owner}/{repo}/environments --jq '.environments[].name'   # list environments
+gh api repos/{owner}/{repo}/deployments --jq '.[0:5] | .[].environment' # recent deployments
+```
+
+### chant commands summary
+
+```bash
+chant init --lexicon github                 # scaffold a new project
+chant init --lexicon github --template node-ci  # scaffold with NodeCI composite
+chant build src/ --output .github/workflows/ci.yml  # synthesize YAML
+chant build src/ --output .github/workflows/ci.yml --watch  # watch mode
+chant lint src/                             # lint chant source
+chant lint src/ --fix                       # auto-fix lint violations
+chant lint src/ --format sarif              # SARIF output for CI
+chant diff src/                             # diff current vs last build
+```

package/src/validate.ts

@@ -2,7 +2,8 @@
  * Validate generated lexicon-github artifacts.
  */
 
-import { dirname } from "path";
+import { dirname, join } from "path";
+import { existsSync } from "fs";
 import { fileURLToPath } from "url";
 import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
 
@@ -23,6 +24,18 @@ const REQUIRED_NAMES = [
  */
 export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
   const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const generatedDir = join(basePath, "src", "generated");
+
+  if (!existsSync(generatedDir)) {
+    return {
+      success: false,
+      checks: [{
+        name: "generated-dir",
+        ok: false,
+        error: 'src/generated/ not found — run "chant dev generate" first',
+      }],
+    };
+  }
 
   return validateLexiconArtifacts({
     lexiconJsonFilename: "lexicon-github.json",

package/src/variables.test.ts

@@ -0,0 +1,48 @@
+import { describe, test, expect } from "bun:test";
+import { GitHub, Runner } from "./variables";
+
+describe("GitHub context variables", () => {
+  test("GitHub.Ref resolves to github.ref expression", () => {
+    expect(GitHub.Ref.toString()).toBe("${{ github.ref }}");
+  });
+
+  test("GitHub.Sha resolves to github.sha expression", () => {
+    expect(GitHub.Sha.toString()).toBe("${{ github.sha }}");
+  });
+
+  test("GitHub.Actor resolves to github.actor expression", () => {
+    expect(GitHub.Actor.toString()).toBe("${{ github.actor }}");
+  });
+
+  test("GitHub has all expected properties", () => {
+    const keys = Object.keys(GitHub);
+    expect(keys).toContain("Ref");
+    expect(keys).toContain("Sha");
+    expect(keys).toContain("Actor");
+    expect(keys).toContain("Repository");
+    expect(keys).toContain("EventName");
+    expect(keys).toContain("Token");
+    expect(keys).toContain("Workspace");
+    expect(keys.length).toBe(25);
+  });
+});
+
+describe("Runner context variables", () => {
+  test("Runner.Os resolves to runner.os expression", () => {
+    expect(Runner.Os.toString()).toBe("${{ runner.os }}");
+  });
+
+  test("Runner.Arch resolves to runner.arch expression", () => {
+    expect(Runner.Arch.toString()).toBe("${{ runner.arch }}");
+  });
+
+  test("Runner has all expected properties", () => {
+    const keys = Object.keys(Runner);
+    expect(keys).toContain("Os");
+    expect(keys).toContain("Arch");
+    expect(keys).toContain("Name");
+    expect(keys).toContain("Temp");
+    expect(keys).toContain("ToolCache");
+    expect(keys.length).toBe(5);
+  });
+});