From 7b5d31ed573c8ddedcab75a26ce809bfc3f48682 Mon Sep 17 00:00:00 2001 From: Brandon Corbett Date: Wed, 8 Jul 2026 17:23:42 -0400 Subject: [PATCH] chore: adopt Node 24 baseline and add AGENTS.md standards - .nvmrc -> 24 (single source of truth) - engines.node -> >=24 <25 - CI setup-node uses node-version-file: .nvmrc (ci.yml, prerelease.yml, release.yml) - AGENTS.md: repo guide with the fells-code baseline working standards --- .github/workflows/ci.yml | 2 +- .github/workflows/prerelease.yml | 2 +- .github/workflows/release.yml | 2 +- .nvmrc | 1 + AGENTS.md | 103 +++++++++++++++++++++++++++++++ package.json | 2 +- 6 files changed, 108 insertions(+), 4 deletions(-) create mode 100644 .nvmrc create mode 100644 AGENTS.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 8d6cd91..15dc169 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,7 +20,7 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 24 + node-version-file: '.nvmrc' cache: pnpm - name: Install dependencies diff --git a/.github/workflows/prerelease.yml b/.github/workflows/prerelease.yml index 69097f9..82ec663 100644 --- a/.github/workflows/prerelease.yml +++ b/.github/workflows/prerelease.yml @@ -37,7 +37,7 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 24 + node-version-file: '.nvmrc' cache: pnpm registry-url: https://registry.npmjs.org/ diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8307518..89796fe 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -27,7 +27,7 @@ jobs: - uses: actions/setup-node@v4 with: - node-version: 24 + node-version-file: '.nvmrc' cache: pnpm registry-url: https://registry.npmjs.org/ diff --git a/.nvmrc b/.nvmrc new file mode 100644 index 0000000..a45fd52 --- /dev/null +++ b/.nvmrc @@ -0,0 +1 @@ +24 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1f6debf --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,103 @@ +# AGENTS.md + +This file is for coding agents working in the `seamless-auth-server` repository. + +## Purpose + +`seamless-auth-server` is the pnpm workspace that publishes the server-side +building blocks of Seamless Auth: a small explicit core plus framework adapters. +It is the bridge adopters embed in their own backends to add passwordless, +session-based auth without opaque middleware chains. + +Published packages: + +- `@seamless-auth/core` (`packages/core`): framework-agnostic core. +- `@seamless-auth/express` (`packages/express`): the Express adapter. + +These are public, adopter-facing packages. Their public API is a contract, and +they bridge cookie sessions to the Bearer/JWKS contract of the +`seamless-auth-api`. Treat contract changes as coordinated, cross-repo work. + +## Working Standards (fells-code baseline) + +These rules apply to every repository in the fells-code org. Repo-specific +guidance may extend them but must not contradict them. + +### Attribution + +- Commit and open PRs solely under the repository owner's identity. Never + commit under an agent or assistant identity. +- Never attribute work to an AI assistant: no `Co-Authored-By: Claude` (or any + assistant) trailers, no "Generated with" / "Created with Claude" notes, and no + assistant branding or emoji anywhere in commit messages, PR or issue titles + and descriptions, changesets, code comments, or docs. + +### Comments + +- Comment only when the code genuinely needs explaining: a non-obvious reason, a + gotcha, or an invariant. Never narrate what the code plainly does. + +### TODOs + +- Every `TODO`/`FIXME` must reference a ticket, e.g. `// TODO(#123): ...`. + Do not leave a bare TODO. If no ticket exists, create one first. + +### Commits & branches + +- Conventional Commits (`feat:`, `fix:`, `chore:`, `docs:`, `ci:`, `test:`). +- Descriptive branch names (`feat/...`, `fix/...`); never a `claude/` or other + tool-generated prefix. + +### Public-facing text + +- No em dashes in commit messages, code comments, PR or issue text, changesets, + or docs. Use a comma, parentheses, or a separate sentence. + +### Before declaring work done + +- All code quality checks must pass before you open a PR or call the work done: + tests, linting, type checks, and formatting. Run them and report the real + output; do not open a PR while any check is failing. +- Typical commands: `pnpm build` and `pnpm test` at the workspace root (plus any + per-package checks). Never claim a change works without running them. +- Match the surrounding code's style, naming, and comment density. + +## Runtime Model + +- pnpm workspace (`pnpm-workspace.yaml`) with packages under `packages/*`. +- TypeScript libraries built and published via Changesets. +- `@seamless-auth/express` depends on `@seamless-auth/core`; keep the core free + of framework-specific code. + +## Architecture Map + +```text +packages/ + core/ framework-agnostic auth core and shared logic + express/ Express adapter built on top of core +``` + +- Keep framework specifics in the adapter package, not in `core`. +- The adapters bridge to `seamless-auth-api`; when behavior looks off, check the + API's route/token/JWKS contract before changing code here. + +## Tooling + +| Task | Command | +| ------- | -------------- | +| Install | `pnpm install` | +| Build | `pnpm build` | +| Test | `pnpm test` | + +- Node version is pinned by `.nvmrc` (Node 24); CI reads it via + `node-version-file`. Run `nvm use` and `corepack enable` locally to match. +- Releases use Changesets; a user-facing change needs a changeset. Do not + hand-edit versions or `CHANGELOG.md`. + +## Safe Change Workflow + +1. Run `nvm use`, `corepack enable`, and `pnpm install`. +2. Keep `core` framework-agnostic; put framework code in the adapter. +3. Run `pnpm build` and `pnpm test` before opening a PR. +4. For any public API or contract change, add a changeset and note the + cross-repo impact on `seamless-auth-api` and the SDKs. diff --git a/package.json b/package.json index 6d0ca2d..9356b57 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "private": true, "packageManager": "pnpm@10.33.0", "engines": { - "node": ">=20" + "node": ">=24 <25" }, "scripts": { "build": "pnpm -r --sort build",