Add CodeFlow Card GitHub Action (v1)

README.md

@@ -17,6 +17,32 @@
 
 ---
 
+## :sparkles: New: CodeFlow Card — a slick repo-stats GitHub Action
+
+Drop a self-updating SVG card on your README that shows your repo's **health grade**, **scale**, **fragility (top blast-radius files)**, and **hidden costs** — recomputed on every merge. Same analyzer as the web app; zero drift.
+
+```yaml
+# .github/workflows/codeflow-card.yml
+on: { push: { branches: [main] }, pull_request: { types: [closed] }, workflow_dispatch: {} }
+jobs:
+  card:
+    runs-on: ubuntu-latest
+    permissions: { contents: write, pull-requests: write }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: braedonsaunders/codeflow/card@v1
+```
+
+Then in your README:
+
+```markdown
+<img src=".github/codeflow-card.svg" alt="CodeFlow card" />
+```
+
+Optional opt-in `receipts: true` posts a thermal-receipt-style sticky comment on every merged PR, itemizing the merge: `+/- LOC`, blast-radius before/after, grade delta. See [card/README.md](./card/README.md) for full inputs.
+
+---
+
 ## Why CodeFlow?
 
 Ever opened a new codebase and felt completely lost? **CodeFlow** turns any GitHub repository or local codebase into an interactive architecture map in seconds.
@@ -71,6 +97,9 @@ Color files by commit frequency to see which parts of your codebase are most act
 ### PR Impact Analysis
 Paste a PR URL to see exactly which files it affects and calculate the blast radius of proposed changes.
 
+### CodeFlow Card (GitHub Action)
+Auto-updating SVG card on your README — health grade, scale, fragility, hidden costs — recomputed every merge. Optional thermal-receipt PR comments. See [card/](./card/).
+
 ### Markdown & Wiki-Link Graph
 Point CodeFlow at an Obsidian vault or any markdown directory to see notes as a connected graph. Both `[[wiki-links]]` and `[text](./relative.md)` links become edges; each note is a `note`-layer node (distinct color) with a `dependencies[]` array in the JSON export.
 
@@ -347,6 +376,55 @@ node --test tests/
 
 ---
 
+## Card Style Gallery
+
+All examples below are real cards rendered by the [CodeFlow Card Action](./card/) against this very repo. Pick one and drop it on your README.
+
+### `style: compact` — default
+
+<img src="./card/examples/compact.svg" alt="compact" width="100%" />
+
+### `style: compact` with `show-grade: false, show-score: false`
+
+For public READMEs where you'd rather show data than a letter grade. The card stays informational — files, functions, LOC, languages, tests — without the judgmental bits.
+
+<img src="./card/examples/compact-private.svg" alt="compact private" width="100%" />
+
+### `accent` — any preset or CSS color
+
+The accent recolors the sparklines, links, and pin. Presets: `purple` (default), `teal`, `cyan`, `green`, `pink`, `blue`, `amber`, `red`. Or pass any CSS color (e.g. `#ff6b6b`).
+
+<img src="./card/examples/compact-teal.svg" alt="compact teal" width="100%" />
+<img src="./card/examples/compact-pink.svg" alt="compact pink" width="100%" />
+
+### `style: row` — status-bar strip
+
+<img src="./card/examples/row.svg" alt="row" width="100%" />
+
+### `style: minimal` — single text line
+
+<img src="./card/examples/minimal.svg" alt="minimal" width="100%" />
+
+### `style: hero` — splashy gradient
+
+<img src="./card/examples/hero.svg" alt="hero" width="100%" />
+
+`hero` with `show-grade: false`:
+
+<img src="./card/examples/hero-private.svg" alt="hero private" width="100%" />
+
+### `style: detailed` — information-rich
+
+Everything: grade, scale, language breakdown, composition (connections, tests, folders, function stats, patterns), top folders, fragility, hidden costs.
+
+<img src="./card/examples/detailed.svg" alt="detailed" width="100%" />
+
+`detailed` with `show-grade: false`:
+
+<img src="./card/examples/detailed-private.svg" alt="detailed private" width="100%" />
+
+---
+
 ## Star History
 
 If you find CodeFlow useful, please star the repo.

card/README.md

@@ -0,0 +1,88 @@
+# CodeFlow Card
+
+A GitHub Action that drops a slick auto-updating SVG card on your README — health grade, scale, fragility, hidden costs — recomputed every merge by [codeflow](https://github.com/braedonsaunders/codeflow).
+
+The card uses the **same analyzer** as the codeflow web app. There's no separate parser, no version drift — the Action reads codeflow's `index.html` and runs its analyzer in a Node `vm`.
+
+## Quick start
+
+Drop this file in `.github/workflows/codeflow-card.yml`:
+
+```yaml
+name: CodeFlow Card
+on:
+  push:
+    branches: [main]
+  pull_request:
+    types: [closed]
+  workflow_dispatch:
+
+jobs:
+  card:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: braedonsaunders/codeflow/card@v1
+        with:
+          theme: dark
+          receipts: false  # set true to post merged-PR comments
+```
+
+Then add this to your README:
+
+```markdown
+<img src=".github/codeflow-card.svg" alt="CodeFlow card" />
+```
+
+The Action commits the rendered SVG to `.github/codeflow-card.svg` (overwriting it on every run) and a small history file at `.github/codeflow-card.json` that powers the sparklines and deltas.
+
+## Inputs
+
+| Input | Default | Description |
+|---|---|---|
+| `output` | `.github/codeflow-card.svg` | Path to write the card SVG. |
+| `state` | `.github/codeflow-card.json` | Path to the JSON history file (sparklines, deltas). |
+| `theme` | `dark` | `dark` \| `light`. |
+| `panels` | `grade,scale,fragility,hidden-costs` | Comma-separated list. Drop any to exclude. |
+| `receipts` | `false` | Post a thermal-receipt-style sticky comment on each merged PR. |
+| `sparkline-window` | `30` | Recent runs to keep in state for sparklines. |
+| `pin` | `true` | Show the "Powered by codeflow" footer. |
+| `commit-message` | `chore: update codeflow card [skip ci]` | Commit message used by the Action. |
+| `github-token` | `${{ github.token }}` | Token for committing and posting receipts. |
+
+## What's on the card
+
+- **Health** — letter grade (A+ → F) with delta arrow vs the last run, plus the underlying score.
+- **Scale** — files / functions / LOC / languages, each with a 30-run sparkline (after the second run).
+- **Fragility** — top 3 highest-blast-radius files. The numbers nobody usually shows.
+- **Hidden costs** — circular deps, dead code %, average coupling. Lower-is-better arrows.
+
+## PR receipts (opt-in)
+
+When `receipts: true`, every merged PR gets a sticky comment with a thermal-receipt-style summary of what the merge changed:
+
+```
+--- CODEFLOW RECEIPT ---
+PR #482  @yourhandle
+--------------------------
+LOC           +312
+functions     +4
+dead code     −1
+circular deps −1
+blast radius  23 → 18 ▼
+health        B+ → A- ▲
+--------------------------
+   thank you for your merge
+```
+
+The comment is sticky (updates in place via `<!-- codeflow-card:receipt -->` marker) so re-runs don't spam the PR.
+
+## Notes
+
+- **First run**: with no history yet, sparklines and deltas don't render — the panels degrade gracefully.
+- **Permissions**: the workflow needs `contents: write` to commit the SVG, and `pull-requests: write` if `receipts: true`.
+- **CI cost**: analysis runs in pure Node (no Docker, no external APIs); typical run is 10–30 seconds depending on repo size.
+- **Privacy**: nothing leaves the runner. Same guarantee as the codeflow web app.

card/action.yml

@@ -0,0 +1,70 @@
+name: 'CodeFlow Card'
+description: 'Auto-updating SVG card of your repo health, fragility, and structure. Powered by codeflow.'
+author: 'braedonsaunders'
+branding:
+  icon: 'activity'
+  color: 'purple'
+inputs:
+  output:
+    description: 'Path to write the card SVG.'
+    required: false
+    default: '.github/codeflow-card.svg'
+  state:
+    description: 'Path to the JSON history file used for sparklines and deltas.'
+    required: false
+    default: '.github/codeflow-card.json'
+  theme:
+    description: 'Card theme: dark | light | auto.'
+    required: false
+    default: 'dark'
+  accent:
+    description: 'Accent color. Either a preset (purple|teal|cyan|green|pink|blue|amber|red) or any CSS color (e.g. #ff6b6b).'
+    required: false
+    default: ''
+  style:
+    description: 'Card style: compact | row | minimal | hero | detailed.'
+    required: false
+    default: 'compact'
+  panels:
+    description: 'Only used when style=detailed. Comma-separated: grade, scale, languages, fragility, hidden-costs, patterns.'
+    required: false
+    default: 'grade,scale'
+  show-grade:
+    description: 'Show the letter grade. Set to false on public READMEs to keep the card informational without judgment.'
+    required: false
+    default: 'true'
+  show-score:
+    description: 'Show the numeric score. Set to false to hide the granular health number while keeping the letter.'
+    required: false
+    default: 'true'
+  receipts:
+    description: 'Post a thermal-receipt-style PR comment when a PR is merged.'
+    required: false
+    default: 'false'
+  sparkline-window:
+    description: 'How many recent runs to keep in state for sparklines/deltas.'
+    required: false
+    default: '30'
+  pin:
+    description: 'Show "Powered by codeflow" footer link.'
+    required: false
+    default: 'true'
+  commit-message:
+    description: 'Commit message used when the SVG / state file change.'
+    required: false
+    default: 'chore: update codeflow card [skip ci]'
+  commit-author-name:
+    description: 'Git commit author name.'
+    required: false
+    default: 'codeflow-card[bot]'
+  commit-author-email:
+    description: 'Git commit author email.'
+    required: false
+    default: 'codeflow-card[bot]@users.noreply.github.com'
+  github-token:
+    description: 'Token used to commit and post receipts. Defaults to the workflow token.'
+    required: false
+    default: ${{ github.token }}
+runs:
+  using: 'node20'
+  main: 'index.js'