chore(repo): v3

.charlie/instructions/pull-request.md

@@ -0,0 +1,59 @@
+# Charlie instructions for jsx-email (next/v3 branch)
+
+Repo‑specific rules that keep Charlie aligned with this codebase and review preferences. Keep diffs small, mirror existing patterns, and don’t widen scope beyond the request.
+
+## Scope
+Applies to the entire repository, with extra focus on `packages/jsx-email` and its tests.
+
+## Context
+- Monorepo using pnpm + Moon. Most tasks are run with `pnpm moon run <project>:<task>`.
+- Task inheritance lives in `.moon/tasks.yml`. Each project can add/override tasks in its own `moon.yml` (for example, `packages/jsx-email/moon.yml`). The root `moon.yml` defines repository tasks and is aliased as the `repo` project.
+- TypeScript uses ESM with NodeNext resolution; relative imports in source include the `.js` suffix.
+- Tests use Vitest; snapshots live in `.snapshots` next to tests (custom resolver).
+- GitHub Actions sets `FORCE_COLOR=1` when running tests; local runs must mirror this to avoid ANSI snapshot diffs.
+- Conventional Commits are the norm (e.g., `fix(jsx-email): …`). PRs should use the repository template.
+- Conventional Commit scopes map to affected project name(s) under `packages/` (e.g., `(jsx-email)`, `(plugin-inline)`, `(create-jsx-email)`). When multiple projects are affected, list each name in the scope, comma‑separated with no spaces (e.g., `(plugin-inline,plugin-pretty)`). PRs should use the repository template.
+- For the ongoing `next/v3` alignment work on `<Raw>` / `<Conditional>` behavior and core correctness (tracked in #348), branch from `origin/next/v3` and open pull requests with `base` set to `next/v3` (not `main`). Mention `#348` in the PR description for traceability.
+
+## Rules
+- [R1] Stay on task. Do not add refactors, helpers, or style tweaks outside the explicit ask. Keep diffs minimal.
+- [R2] Tests and snapshots:
+  - Run with `FORCE_COLOR=1` to match CI.
+  - Never change log/ANSI‑colored snapshots to “de‑colorize” or “stabilize” output. If a log snapshot fails, fix the cause or mirror CI settings; do not rewrite the assertion shape.
+  - Do not introduce “snapshot normalization” helpers (e.g., projecting only parts of config objects) unless a maintainer requests it.
+  - Place/update snapshots under `.snapshots` alongside the test file; prefer targeted assertions plus snapshots when behavior changes intentionally.
+- [R3] Writing tests for `packages/jsx-email`:
+  - Prefer importing from package source (e.g., `../src/index.ts`) for new tests to avoid prebuild coupling. If an existing suite imports from `dist`, keep that pattern for that suite.
+  - Avoid adding `// @ts-ignore` to suppress React imports; tests can rely on the React automatic JSX runtime. Don’t add new ignores.
+  - Follow NodeNext import style in source files (relative imports include `.js`).
+- [R4] Verification commands (run locally before marking a PR Ready for changes that affect code, tests, or tooling config):
+  - Build artifacts used by tests:
+    - `pnpm moon run plugin-inline:build plugin-minify:build plugin-pretty:build`
+    - `pnpm moon run jsx-email:build`
+  - Lint: `pnpm moon run repo:lint`
+  - Tests (jsx-email package, mirroring the `next/v3` CI setup): `pnpm moon run jsx-email:test`
+  - TypeScript (package): `pnpm moon run jsx-email:tsc`
+  - Do not change tool configs or CI to make checks pass.
+  - For documentation-only or `.charlie`-only changes that do not affect CI, code, or tests, you may skip these commands, but prefer running at least `pnpm moon run repo:lint` when in doubt.
+- [R4.1] Linting (must run before pushing any commits):
+  - Run repo linting via Moon: `pnpm moon run repo:lint`.
+  - Do not push if linting reports errors anywhere. Fix them or coordinate a follow‑up if they are unrelated but surfaced by your changes.
+  - If linting reports warnings in files you modified, resolve those warnings before pushing.
+  - For quick checks while iterating, you may run ESLint scoped to touched files, but always run the full `repo:lint` before the final push.
+- [R5] Git & PRs:
+  - Branch names (from humans): `{type}/{project}/{short-desc}` — for example, `fix/jsx-email/conditional-endif-slash`. Use the package with the most changes (or the intended target) for `{project}`, and let `{short-desc}` be a descriptive phrase or a short slug.
+  - Conventional Commits scope = affected project name(s) from `packages/`. Examples: `fix(jsx-email): …`, `refactor(plugin-inline,plugin-pretty): …`. For multiple projects, list names comma-separated with no spaces.
+  - Commit messages use Conventional Commits; ≤ 72 chars in the subject; no emojis.
+  - PRs must use the repository template as-is — Charlie is not allowed to remove sections from the template.
+  - Start as Draft when work is in flux; mark Ready only after local verification passes and the description reflects the actual changes.
+  - Don’t add novel labels. Assign and request review from the human requester when appropriate.
+
+> Conditional/Raw specifics have been moved to a dedicated playbook. See `.charlie/playbooks/conditional-and-raw.md`.
+
+## References
+1. CI workflow (test color): `.github/workflows/test-*.yml` (see `FORCE_COLOR=1` in test steps)
+2. Vitest shared config: `shared/vitest.config.ts`
+3. Moon tasks inheritance: `.moon/tasks.yml`; per-project tasks: `apps/*/moon.yml`, `packages/*/moon.yml`, `test/*/moon.yml`; repository tasks: `moon.yml` (project `repo`)
+4. jsx-email package tasks: `packages/jsx-email/moon.yml`
+5. Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/
+6. Conditional/Raw playbook: `.charlie/playbooks/conditional-and-raw.md`

.charlie/playbooks/conditional-and-raw.md

@@ -0,0 +1,33 @@
+# Conditional + Raw playbook (renderer and tests) — next/v3 branch
+
+Apply this when changing how `<Conditional>` or `<Raw>` render (MSO/expr tokens, wrappers, or how nested Raw is inlined).
+
+This copy lives on the `next/v3` branch. For the ongoing alignment work on `<Raw>` / `<Conditional>` semantics and tests (tracked in #348):
+- Branch from `origin/next/v3`.
+- Open pull requests with `base` set to `next/v3` (not `main`).
+- Mention `#348` in the PR description so reviewers can tie the change back to the alignment effort.
+
+Rules
+- Include targeted tests and keep snapshot updates minimal (only intentional markup diffs).
+- Do not introduce token “centralization” helpers or adjacency tests unless a maintainer explicitly requests them.
+- Import from source for new tests to avoid prebuild coupling: `import { Conditional, Raw, render } from '../src/index.ts'`.
+
+Test guidelines
+- Closer/opener integrity
+  - Assert exactly one opener and closer for MSO: `<!--[if mso]>` and the current closer `<![endif]/-->`.
+  - Add a small case for the expression path (e.g., `expression="gte mso 16"`) and assert the same closer.
+- No‑duplication when nesting Raw
+  - For `<Conditional mso><Raw …/></Conditional>`, assert the inner payload appears exactly once and not outside the block.
+  - Use `lastIndexOf` for closer slicing and allow opener at index `>= 0`.
+- Snapshots and colorized logs
+  - Run with `FORCE_COLOR=1` to match CI. Never “de‑colorize” or normalize log snapshots.
+
+Commands (jsx-email)
+- Build artifacts some suites rely on: `pnpm moon run plugin-inline:build plugin-minify:build plugin-pretty:build && pnpm moon run jsx-email:build`
+- Tests (CI‑aligned for `next/v3`): `pnpm moon run jsx-email:test` (the Moon task sets `FORCE_COLOR=1` like CI)
+- TypeScript: `pnpm moon run jsx-email:tsc`
+
+References
+- CI workflow (color): `.github/workflows/test-*.yml` (look for `FORCE_COLOR=1`)
+- Shared Vitest config: `shared/vitest.config.ts`
+- Package tasks: `packages/jsx-email/moon.yml`

.charlie/playbooks/run-jsx-email-tests-like-ci.md

@@ -0,0 +1,37 @@
+# Run jsx-email tests locally exactly like CI (Moon + FORCE_COLOR) — next/v3 branch
+
+## Overview
+Run the `packages/jsx-email` test suite locally with the same settings the `next/v3` branch uses in CI so snapshots (including ANSI color) match exactly.
+
+For the ongoing `next/v3` alignment work on `<Raw>` / `<Conditional>` behavior and core correctness (tracked in #348), branch from `origin/next/v3`, open PRs with `base` set to `next/v3` (not `main`), and mention `#348` in the PR description.
+
+## Prerequisites
+- Capabilities: GitHub + Devbox write access (local or CI).
+- Tools: pnpm, Moon tasks (configured in this repo).
+- Context: Some suites import from `dist/esm`, so plugin packages must be built first.
+
+## Steps
+1. Install deps and build required artifacts
+   - `pnpm install`
+   - `pnpm moon run plugin-inline:build plugin-minify:build plugin-pretty:build`
+   - `pnpm moon run jsx-email:build`
+2. Run tests with color forced (matches CI)
+   - `pnpm moon run jsx-email:test`  <!-- task sets FORCE_COLOR=1 in Moon config on next/v3 -->
+3. Optional: update snapshots only for intentional HTML/markup changes (never for log/ANSI deltas)
+   - `cd packages/jsx-email && pnpm vitest -u --config ../../shared/vitest.config.ts && cd -`
+4. TypeScript check (package)
+   - `pnpm moon run jsx-email:tsc`
+
+## Verify
+- Expect: `Test Files 44 passed`, `Tests 187 passed` (numbers may grow over time).
+- No snapshot diffs for logs when `FORCE_COLOR=1` is set (the `jsx-email:test` Moon task configures this automatically).
+
+## Rollback
+- If you mistakenly updated snapshots for log/ANSI output, reset them:
+  - `git restore --source=origin/$(git rev-parse --abbrev-ref HEAD) -- "packages/jsx-email/test/**/.snapshots/*.snap" || true`
+  - Or discard all local changes: `git reset --hard`
+
+## References
+- CI workflow (color): `.github/workflows/test-*.yml` (look for `FORCE_COLOR=1`)
+- Shared Vitest config: `shared/vitest.config.ts`
+- Moon project tasks: `packages/jsx-email/moon.yml`

.eslintignore

@@ -4,4 +4,4 @@ dist
 node_modules
 
 # Starter template files
-packages/create-jsx-email/starter
+packages/create-mail/starter

.github/.keep/release.yml

@@ -0,0 +1,58 @@
+name: Release Projects
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+    tags-ignore:
+      - '*-v*'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  release:
+    if: |
+      !startsWith(github.event.head_commit.message, 'chore(release):') &&
+      !startsWith(github.event.head_commit.message, 'chore(repo):')
+
+    runs-on: ubuntu-latest
+
+    name: release
+
+    steps:
+      - name: Checkout Commit
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 100
+          fetch-tags: true
+          ref: main
+          token: ${{ secrets.GH_TOKEN }}
+
+      - name: Fetch Tags
+        run: git fetch --tags
+
+      - name: Set Git Config
+        run: |
+          git config pull.rebase false
+          git config --global user.email "[email protected]"
+          git config --global user.name "Release Workflow"
+          git remote set-url origin https://github.com/${{ github.repository }}
+
+      - name: Setup
+        uses: ./.github/actions/setup
+
+      - name: Build Projects
+        run: |
+          moon jsx-email:build
+          moon create-mail:build
+          moon run :build --query "project~plugin-*"
+
+      - name: Release
+        run: moon run :release --affected --concurrency 1 --remote
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test-smoke.yml → .github/.keep/test-smoke.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Build Projects
         run: |
           moon jsx-email:build
-          moon create-jsx-email:build
+          moon create-mail:build
           moon run :build --query "project~plugin-*"
 
       - name: Smoke Test

.github/actions/setup/action.yml

@@ -14,7 +14,7 @@ runs:
     - name: Setup Node
       uses: actions/setup-node@v3
       with:
-        node-version: 20
+        node-version: 20.19.0
 
     - name: Install PNPM
       uses: pnpm/action-setup@v4

.github/workflows/release.yml

@@ -9,9 +9,9 @@ on:
       - '*-v*'
 
 permissions:
+  # Jobs requiring OIDC (e.g., npm publish) must request `id-token: write` at the job level.
   contents: read
   pages: write
-  id-token: write
 
 jobs:
   release:
@@ -20,7 +20,9 @@ jobs:
       !startsWith(github.event.head_commit.message, 'chore(repo):')
 
     permissions:
+      # Required for `versioner` to push release commits/tags and for npm OIDC publish.
       contents: write
+      id-token: write
 
     runs-on: ubuntu-latest
 
@@ -51,11 +53,19 @@ jobs:
       - name: Build Projects
         run: |
           moon jsx-email:build
-          moon create-jsx-email:build
+          moon create-mail:build
           moon run :build --query "project~plugin-*"
 
+      - name: OIDC Preflight
+        shell: bash
+        run: |
+          if [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ]; then
+            echo "Missing GitHub Actions OIDC env vars (ACTIONS_ID_TOKEN_REQUEST_URL/TOKEN)." >&2
+            echo "Ensure the job requests permissions: id-token: write." >&2
+            exit 1
+          fi
+
+          echo "OIDC env vars detected."
+
       - name: Release
         run: moon run :release --affected --concurrency 1 --remote
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/test-cli.yml

@@ -34,7 +34,7 @@ jobs:
       - name: Build Projects
         run: |
           moon jsx-email:build
-          moon create-jsx-email:build
+          moon create-mail:build
           moon run :build --query "project~plugin-*"
 
       - name: Run Tests