From 041f870035f6b968d63cce33d28140cfd219db20 Mon Sep 17 00:00:00 2001
From: jstet <mail@jstet.net>
Date: Thu, 24 Sep 2026 14:36:05 +0200
Subject: [PATCH] ci(release): attach a prebuilt package tarball and the skill
 archive to releases

On release publish, release-assets.yml builds and attaches:

- correlaid-formtransform-<version>.tgz (npm pack; dist/ prebuilt), which
  installs with no build step, no TypeScript and install scripts disabled
- cdl-survey-types-<version>.tar.gz (skills/cdl-survey-types/), a stable URL
  for formulaid instead of a git archive of this repo's layout

package.json is the version source; the job fails when the release tag isn't
v<version>. Before uploading, it installs the tarball into an empty project with
--ignore-scripts, imports it and runs the CLI. A manual dispatch with a tag
backfills an existing release.

README: install from the release tarball, and a short release checklist.

Closes #4

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release-assets.yml | 77 ++++++++++++++++++++++++++++
 README.md                            | 25 ++++++++-
 2 files changed, 101 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/release-assets.yml

diff --git a/.github/workflows/release-assets.yml b/.github/workflows/release-assets.yml
new file mode 100644
index 0000000..e5b1be4
--- /dev/null
+++ b/.github/workflows/release-assets.yml
@@ -0,0 +1,77 @@
+name: Attach release assets
+
+# Attaches prebuilt artifacts to a GitHub release, so consumers pin a URL
+# instead of building from git on every install (formtransform#4):
+#
+# - correlaid-formtransform-<version>.tgz: the npm package (`npm pack`, dist/
+#   prebuilt). Installing it runs no build and needs no TypeScript:
+#     "@correlaid/formtransform": "https://github.com/CorrelAid/formtransform/releases/download/v<version>/correlaid-formtransform-<version>.tgz"
+# - cdl-survey-types-<version>.tar.gz: the generated skills/cdl-survey-types/
+#   sub-skill, unpacking to cdl-survey-types/, so formulaid needn't know this
+#   repo's layout.
+#
+# package.json is the version source: bump it in a PR, then publish release
+# v<version>. The job fails if the tag and package.json disagree.
+#
+# Runs when a release is published. Run it manually with an existing tag to
+# (re)attach assets to an older release; --clobber replaces them.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing release tag, e.g. v0.1.0"
+        required: true
+
+jobs:
+  assets:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      TAG: ${{ github.event.release.tag_name || inputs.tag }}
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.TAG }}
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+
+      - name: Check tag matches package.json
+        id: version
+        run: |
+          version=$(node -p "require('./package.json').version")
+          if [ "$TAG" != "v$version" ]; then
+            echo "::error::tag $TAG does not match package.json version $version (expected v$version)"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+
+      # npm ci runs `prepare`, which builds dist/.
+      - name: Install and build
+        run: npm ci
+
+      - name: Pack
+        run: |
+          mkdir -p assets
+          npm pack --ignore-scripts --pack-destination assets
+          tar czf "assets/cdl-survey-types-${{ steps.version.outputs.version }}.tar.gz" \
+            -C skills cdl-survey-types
+
+      - name: Smoke-test the tarball without install scripts
+        run: |
+          mkdir -p "$RUNNER_TEMP/consumer" && cd "$RUNNER_TEMP/consumer"
+          npm init -y >/dev/null
+          npm pkg set type=module
+          npm install --ignore-scripts "$GITHUB_WORKSPACE"/assets/correlaid-formtransform-*.tgz
+          node -e "import('@correlaid/formtransform').then((m) => { if (!m.XLSFormToTSVConverter) process.exit(1); })"
+          npx --no-install formtransform --help >/dev/null
+
+      - name: Upload to the release
+        run: gh release upload "$TAG" assets/* --clobber
diff --git a/README.md b/README.md
index ee02361..6559f3c 100644
--- a/README.md
+++ b/README.md
@@ -23,10 +23,23 @@ in-repo only.
 
 ### As a library
 
+Each [release](https://github.com/CorrelAid/formtransform/releases) carries a
+prebuilt package. Installing it runs no build step:
+
+```bash
+npm install https://github.com/CorrelAid/formtransform/releases/download/v0.1.0/correlaid-formtransform-0.1.0.tgz
+```
+
+Installing from git also works, but builds `dist/` on install through the
+`prepare` script, which needs TypeScript and install scripts enabled:
+
 ```bash
-npm install github:CorrelAid/formtransform
+npm install github:CorrelAid/formtransform#v0.1.0
 ```
 
+Releases also attach `cdl-survey-types-<version>.tar.gz`, the generated
+[`skills/cdl-survey-types/`](skills/cdl-survey-types/) sub-skill.
+
 ### As a CLI tool
 
 ```bash
@@ -188,6 +201,16 @@ uv run codegen
 npm run bless
 ```
 
+### Releasing
+
+1. Bump `version` in `package.json` in a PR and merge it.
+2. Publish a GitHub release tagged `v<version>` on that commit.
+
+Publishing the tag builds the `schematron-worker` image
+(`worker-image.yml`). Publishing the release attaches the package tarball and
+the skill archive (`release-assets.yml`). That job fails if the tag and
+`package.json` disagree.
+
 ## Documentation
 
 - [Architecture](ARCHITECTURE.md) — Technical architecture and internal structure