Merge pull request #171 from lambda-curry/changeset-release/main

Author: jaruesink

.cursor/rules/versioning-with-npm.mdc

@@ -8,7 +8,7 @@ You are an expert release manager for a Yarn 4 monorepo who uses the npm CLI for
 - Treat new components and minor fixes as patch releases when they are additive and low-risk.
 - Reserve minor/major only for notable feature waves or breaking changes.
 
-Note: While the repo supports Changesets for broader release coordination, this rule documents the npm CLI flow for quick iterations.
+Note: The primary release workflow uses Changesets (`yarn changeset` → `yarn changeset version` → automatic CI/CD publish). This rule documents the npm CLI flow for quick iterations when bypassing changesets.
 
 ## What Counts As “Small”
 - Additive components (new UI or form wrappers) without breaking changes
@@ -47,7 +47,8 @@ Guidelines:
 
 ## Open PR and Merge
 - Push your branch and open a PR.
-- When the PR merges into `main`, GitHub CI publishes the package. No manual tagging or `npm publish` needed.
+- When the PR merges into `main`, GitHub CI automatically publishes the package using npm trusted publishers (OIDC). No manual tagging or `npm publish` needed, and no npm tokens required.
+- **Note:** The release workflow uses [npm trusted publishers](https://docs.npmjs.com/trusted-publishers) for secure, tokenless publishing. Ensure the trusted publisher is configured on npmjs.com for the package.
 
 ## Minor / Major (When Needed)
 - Minor: larger feature sets or notable additions across multiple components

.github/workflows/release.yml

@@ -7,27 +7,32 @@ on:
 
 concurrency: ${{ github.workflow }}-${{ github.ref }}
 
+permissions:
+  id-token: write # Required for OIDC trusted publishing
+  contents: read
+
 jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
     steps:
       - name: Checkout Repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
-      - name: Setup Node.js 20.x
-        uses: actions/setup-node@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
         with:
-          node-version: 20.x
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
 
       - name: Enable Corepack
         run: corepack enable
 
       - name: Install Correct Yarn Version
-        run: corepack prepare yarn@4.4.1 --activate
+        run: corepack prepare yarn@4.9.1 --activate
 
       - name: Install Dependencies
-        run: yarn
+        run: yarn install --immutable
 
       - name: Create Release Pull Request or Publish to npm
         id: changesets
@@ -37,4 +42,4 @@ jobs:
           publish: yarn release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+          # No NPM_TOKEN needed - using trusted publishing via OIDC

AGENTS.md

@@ -36,10 +36,12 @@
 - PRs: clear description, linked issues, screenshots or Storybook links, notes on testing.
 - Required checks: `yarn lint` passes; build succeeds; tests updated/added.
 - Versioning: when changing published package(s), add a Changeset (`yarn changeset`) before merge.
+- Publishing: Releases are automatically published via CI/CD using [npm trusted publishers](https://docs.npmjs.com/trusted-publishers) (OIDC). No npm tokens required. See README.md for setup instructions.
 
 ## Security & Configuration
 - Node `22.9.0` (`.nvmrc`) and Yarn 4 (`packageManager`).
 - Do not commit secrets. Keep large artifacts out of VCS (`dist`, `node_modules`).
+- Publishing uses npm trusted publishers (OIDC) - no long-lived tokens needed.
 - PR previews for Storybook are published via GitHub Pages; verify links in PR comments.
 
 ## Cursor Rules Review
@@ -48,7 +50,7 @@
 - `.cursor/rules/form-component-patterns.mdc`: Remix Hook Form + Zod wrappers, errors, server actions.
 - `.cursor/rules/storybook-testing.mdc`: Storybook play tests, router stub decorator, local/CI flows.
 - `.cursor/rules/monorepo-organization.mdc`: Imports/exports, package boundaries, Turbo/Vite/TS paths.
-- `.cursor/rules/versioning-with-npm.mdc`: npm CLI version bumps (patch-first), CI publishes on merge.
+- `.cursor/rules/versioning-with-npm.mdc`: npm CLI version bumps for quick iterations (patch-first). Primary workflow uses Changesets with automatic CI/CD publishing via npm trusted publishers.
 
 ## Agent OS
 

README.md

@@ -128,3 +128,134 @@ The PR preview is deployed to the `gh-pages` branch in a directory structure lik
 ```
 /pr-preview/pr-[PR_NUMBER]/
 ```
+
+## Publishing
+
+Releases can be published either automatically via CI/CD (using npm trusted publishers) or manually from the command line.
+
+### Automatic Publishing (CI/CD)
+
+When you merge changes to `main` with version updates, the GitHub Actions workflow will automatically publish to npm using [npm trusted publishers](https://docs.npmjs.com/trusted-publishers). This uses OIDC authentication and doesn't require npm tokens.
+
+**Setup required:** Configure trusted publishers on npmjs.com for the `@lambdacurry/forms` package (see setup instructions below).
+
+#### Setting Up Trusted Publishers
+
+1. Go to your package on npmjs.com: https://www.npmjs.com/package/@lambdacurry/forms
+2. Navigate to **Settings** → **Trusted Publisher** section
+3. Click **"Select your publisher"** → **GitHub Actions**
+4. Configure the following:
+   - **Organization or user**: `lambda-curry` (or your GitHub username)
+   - **Repository**: `forms`
+   - **Workflow filename**: `release.yml` (must match exactly, including `.yml` extension)
+5. Click **Save**
+
+The workflow file must exist at `.github/workflows/release.yml` in your repository. Once configured, publishes from the `main` branch will use OIDC authentication automatically.
+
+### Manual Publishing
+
+You can also publish manually from the command line when needed.
+
+### Prerequisites
+
+1. **Ensure you're logged into npm:**
+   ```bash
+   npm login
+   ```
+   You must be logged in as a user with publish permissions for the `@lambdacurry` organization.
+
+2. **Verify your npm credentials:**
+   ```bash
+   npm whoami
+   ```
+
+3. **Ensure you're on the `main` branch and up to date:**
+   ```bash
+   git checkout main
+   git pull origin main
+   ```
+
+### Release Process
+
+#### Step 1: Create Changesets (if needed)
+
+If you have changes that need to be documented in the changelog, create a changeset:
+
+```bash
+yarn changeset
+```
+
+Follow the prompts to:
+- Select which packages to include
+- Choose the version bump type (patch, minor, major)
+- Write a summary of the changes
+
+#### Step 2: Version Packages
+
+This updates package versions and generates the changelog:
+
+```bash
+yarn changeset version
+```
+
+This will:
+- Update `packages/components/package.json` with the new version
+- Update `packages/components/CHANGELOG.md` with the new entries
+- Remove the consumed changeset files
+
+#### Step 3: Build and Test
+
+Before publishing, ensure everything builds and tests pass:
+
+```bash
+yarn build
+yarn test
+```
+
+#### Step 4: Publish to npm
+
+Publish the package to npm using changesets:
+
+```bash
+yarn release
+```
+
+This command runs `changeset publish`, which:
+- Runs `yarn build` (via `prepublishOnly` hook in package.json)
+- Publishes `@lambdacurry/forms` to npm (uses npm under the hood)
+- Creates git tags for the release
+- Requires you to be logged into npm (`npm login`)
+
+**Note:** `changeset publish` uses npm CLI internally, so you must be authenticated with npm. The changeset system handles versioning, changelog generation, and publishing all in one workflow.
+
+#### Step 5: Commit and Push
+
+After successful publishing, commit the version changes and push:
+
+```bash
+git add .
+git commit -m "chore(release): publish vX.Y.Z"
+git push origin main
+```
+
+### Alternative: Direct npm Publish (Without Changesets)
+
+If you need to publish without using changesets (e.g., for a hotfix), you can use npm directly:
+
+```bash
+# From the packages/components directory
+cd packages/components
+npm version patch -m "chore: bump version to %s"
+cd ../..
+yarn install  # Update yarn.lock
+yarn workspace @lambdacurry/forms build
+npm publish --workspace=packages/components
+```
+
+**Note:** This bypasses the changeset workflow, so you'll need to manually update the CHANGELOG.md if you want to document the release.
+
+### Troubleshooting
+
+- **"Not logged in" error**: Run `npm login` and verify with `npm whoami`
+- **"Permission denied"**: Ensure your npm user has publish permissions for `@lambdacurry` organization
+- **Build fails**: Fix build errors before publishing. The `prepublishOnly` hook will prevent publishing if the build fails