chore: add release workflows (#45)

* chore: add release workflows

* docs: clarify GitHub Releases are not automated

Author: mahyarmlk

.github/workflows/publish-alpha.yml

@@ -0,0 +1,66 @@
+name: Publish Alpha
+
+on:
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}
+
+permissions:
+  contents: read
+
+jobs:
+  publish-alpha:
+    name: Publish Alpha
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Validate npm token
+        run: |
+          if [ -z "${NPM_TOKEN:-}" ]; then
+            echo "::error::NPM_TOKEN secret is required for publishing."
+            exit 1
+          fi
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Test
+        run: pnpm test
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+      - name: Build
+        run: pnpm build
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Pack Check
+        run: pnpm pack:check
+
+      - name: Configure npm auth
+        run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > "$HOME/.npmrc"
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish Alpha
+        run: pnpm release:alpha
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/version-packages.yml

@@ -0,0 +1,41 @@
+name: Version Packages
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  version:
+    name: Version Packages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repo
+        uses: actions/checkout@v6
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Install Dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create Version Packages PR
+        uses: changesets/action@v2
+        with:
+          version: pnpm version:packages
+          title: "chore: version packages"
+          commit: "chore: version packages"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

README.md

@@ -276,7 +276,7 @@ Current limitations include:
 * No backend persistence yet
 * No real resource cache policy yet
 * No DevTools package yet
-* No automated publish workflow yet (Changesets is configured, release workflow pending)
+* Automated version PR workflow and manual publish workflow are set up (Changesets configured)
 * Demo side panels use manual DOM
 * Demo diagnostics panel uses `MutationObserver`
 * Demo data is in memory only

docs/Release-Readiness.md

@@ -4,7 +4,7 @@
 
 Intent is in early experimental development. No packages have been published to npm. No GitHub Releases have been created.
 
-The repository has five workspace packages under `packages/*`. The four publishable packages are at version `0.1.0-alpha.0`. The private server package remains at `0.1.0`. All use `workspace:*` dependency references. The codebase is functional and validated by CI. Changesets is installed and configured. The remaining blocker before a first alpha release is the release workflow and npm publish automation.
+The repository has five workspace packages under `packages/*`. The four publishable packages are at version `0.1.0-alpha.0`. The private server package remains at `0.1.0`. All use `workspace:*` dependency references. The codebase is functional and validated by CI. Changesets is installed and configured. Release workflows exist for automated version PRs and manual alpha publishing.
 
 Four packages are intended for first-alpha publishing. `packages/server` is a private workspace package for now.
 
@@ -179,23 +179,28 @@ The `files` field in every package is `["dist"]`. Based on `npm pack --dry-run`
 
 No unnecessary files (source maps, config files, tests, node_modules) leak into the tarball. The `files` policy is correct.
 
-## Release workflow recommendation
+## Release workflows
 
-### Use Changesets
+### Version Packages PR workflow
 
-[Changesets](https://github.com/changesets/changesets) is recommended for:
+A Changesets-based [version-packages.yml](../.github/workflows/version-packages.yml) workflow runs on pushes to `main`:
 
-- Version bumping (independent versioning per package)
-- Changelog generation per package
-- Coordinated publishing across the workspace
+1. Checks out the repository
+2. Installs dependencies
+3. Runs `pnpm version:packages` via `changesets/action`
+4. Opens or updates a "Version Packages" PR when changeset files are present
 
-### Recommended GitHub Action
+This workflow does **not** publish to npm. It only manages the version PR.
 
-Add a Changeset-based GitHub Action (e.g., `changesets/action`) that:
+### Manual Publish Alpha workflow
 
-1. Runs on pushes to `main`
-2. Opens or updates a "Version Packages" PR when changeset files are present
-3. Publishes to npm when the version PR is merged
+A [publish-alpha.yml](../.github/workflows/publish-alpha.yml) workflow exists for publishing:
+
+- **Trigger**: manual only (`workflow_dispatch`)
+- **Environment**: requires the `npm` GitHub environment
+- **Pre-publish validation**: test, typecheck, build, lint, pack:check
+- **Publish command**: `pnpm release:alpha` (builds, runs pack check, then `changeset publish --tag alpha`)
+- **npm auth**: configured at runtime via `NODE_AUTH_TOKEN`; no committed `.npmrc` file
 
 ### Publish cadence
 
@@ -229,22 +234,25 @@ Do not manually create GitHub Releases.
 - [x] MIT confirmed as intended public license
 - [x] Confirm package metadata (`repository` field in all packages)
 - [x] Server is private — not a publishing blocker
-- [x] Package exports point to correct `dist/` paths
-- [x] Package `files: ["dist"]` is correct
-- [x] Declaration files (`dist/index.d.ts`) exist after build
+- [x] Confirm package exports (all point to correct `dist/` paths)
+- [x] Confirm package files (`files: ["dist"]`)
+- [x] Confirm declaration files (`dist/index.d.ts` exists)
 - [x] Clean-dist validation passes
-- [x] `pnpm pack:check` passes
 - [x] Changesets installed and configured
-- [x] First alpha package versions set to `0.1.0-alpha.0`
-- [ ] Add release workflow (GitHub Action for Changesets)
-- [ ] Publish first alpha (`pnpm changeset publish`)
-- [ ] Create GitHub Release (automatic via Changesets, or manual)
+- [x] Release workflows added:
+  - Version Packages PR workflow (push-to-main)
+  - Manual Publish Alpha workflow (manual dispatch only)
+- [ ] NPM_TOKEN secret added to GitHub repository secrets
+- [ ] Publish first alpha via manual Publish Alpha workflow
+- [ ] Optionally create a GitHub Release manually after npm publish
 
 ## Current blockers
 
-- repository fields are present
-- GitHub repository home is https://github.com/intent-framework/intent
-- remaining first-alpha blocker after this PR: Release workflow not yet added, including npm publish automation and required secrets.
+- repository fields: present
+- GitHub repository home: `intent-framework/intent`
+- Changesets: installed and configured
+- Release workflows: version-packages.yml (automated version PRs) and publish-alpha.yml (manual publish) are added
+- Remaining first-alpha blocker: add `NPM_TOKEN` secret, then manually run Publish Alpha
 
 ## Future server-package decisions
 
@@ -253,12 +261,30 @@ Do not manually create GitHub Releases.
 
 ## Do not do yet
 
-- Do not publish any package to npm.
-- Do not create a GitHub Release.
-- Do not add a release GitHub Action yet.
+- Do not publish any package to npm until the manual Publish Alpha workflow is triggered.
+- Do not create a GitHub Release yet. The current manual Publish Alpha workflow publishes npm packages only. GitHub Releases are not automated yet.
 - Do not change runtime or public APIs.
 - Do not add new dependencies unless required for a specific task.
 
+## Required secret: NPM_TOKEN
+
+Before running the Publish Alpha workflow, a GitHub Actions secret must be added:
+
+| Secret | Purpose |
+|---|---|
+| `NPM_TOKEN` | npm access token with publish permission for `@intent-framework/*` packages |
+
+The token must:
+- Have **publish** permission for the `@intent-framework` npm organization
+- Be stored as a GitHub Actions secret (not in the repository)
+- Be configured in the `npm` GitHub environment used by the Publish Alpha workflow
+
+Do not commit the token value to the repository.
+
+### Future improvement: trusted publishing
+
+Migrate npm publishing to trusted publishing / OIDC once the initial package publishing flow is stable.
+
 ## Pack check command
 
 The root `pack:check` command: