Codex MCP integration, runtime overhaul, docs, and Next fork CI

.github/PUBLISHING.md

@@ -0,0 +1,213 @@
+# Publishing Guide
+
+This document explains how the automated publishing system works for `happy-next`.
+
+## Overview
+
+**Every push to the preview branch automatically publishes to npm!** No manual steps needed.
+
+For stable releases, the package is automatically published to npm when the version changes.
+
+## Automated Workflows
+
+### 1. Automatic Preview Publishing (`publish-preview.yml`) ⭐ NEW
+
+**Triggers on every push to preview branches!**
+
+**What it does:**
+- Generates unique version: `<version>-preview.<timestamp>.<commit-hash>`
+- Installs dependencies
+- Runs build and tests
+- Publishes to npm with `@preview` tag
+
+**Installation:**
+```bash
+# Get the latest preview (recommended)
+npm install -g happy-next@preview
+
+# Or install a specific preview version
+npm install -g happy-next@0.11.3-preview.20251118120000.abc1234
+```
+
+**No manual intervention needed!** Just push your changes and wait 2-3 minutes.
+
+### 2. Version Bumping (`bump-version.yml`)
+
+Manually trigger this workflow to bump the version:
+
+**Via GitHub UI:**
+1. Go to Actions → Bump Version
+2. Click "Run workflow"
+3. Select bump type: `prerelease`, `patch`, `minor`, or `major`
+4. Click "Run workflow"
+
+**What it does:**
+- Bumps the version in `package.json`
+- Builds the project (updates `dist/`)
+- Commits changes with `[skip-build]` tag
+- Creates and pushes git tag (`v0.11.3-preview.8`, etc.)
+- Updates `latest-preview` tag for prerelease versions
+
+### 3. Publishing to NPM (`publish-npm.yml`)
+
+Automatically triggers when:
+- Version in `package.json` changes on `main` branch
+- Manually triggered via workflow_dispatch
+
+**What it does:**
+- Detects version change
+- Builds the project
+- Publishes to npm with `--access public`
+- Creates GitHub release
+- Adds install instructions to release notes
+
+**Note:** For preview/development work, use the automatic preview publishing instead!
+
+## Publishing a New Version
+
+### For Preview Releases (Automatic!) ⭐
+
+**Just push your changes!** That's it.
+
+```bash
+git add .
+git commit -m "your changes"
+git push
+# Wait 2-3 minutes - your changes are now published to npm!
+```
+
+Install with: `npm install -g happy-next@preview`
+
+### For Named Preview Releases (Manual)
+
+If you want a specific preview version number:
+
+```bash
+# Option 1: Use GitHub Actions
+# Go to Actions → Bump Version → Run workflow → Select "prerelease"
+
+# Option 2: Manually
+npm version prerelease --preid=preview
+git push
+git push --tags
+# Publishing happens automatically
+```
+
+### For Stable Releases
+
+```bash
+# Option 1: Use GitHub Actions (Recommended)
+# Go to Actions → Bump Version → Run workflow → Select "patch/minor/major"
+
+# Option 2: Manually
+npm version patch  # or minor, major
+git push
+git push --tags
+# Publishing happens automatically
+```
+
+## Installation After Publishing
+
+Once published to npm, users can install with:
+
+```bash
+# Latest stable version
+npm install -g happy-next
+
+# Latest preview version
+npm install -g happy-next@preview
+
+# Specific version
+npm install -g happy-next@0.11.3-preview.7
+```
+
+## Benefits of NPM Publishing
+
+✅ **No GitHub install issues** - Works perfectly with NVM
+✅ **No path problems** - npm handles bin wrappers automatically
+✅ **Faster installs** - Pre-built dist, no compilation needed
+✅ **Better caching** - npm registry is more reliable than GitHub
+✅ **Works like original** - Same experience as `happy-coder`
+
+## NPM Token Setup
+
+The `NPM_TOKEN` secret is already configured in the repository:
+- **Location:** Repository Settings → Secrets and variables → Actions
+- **Name:** `NPM_TOKEN`
+- **Used by:** `publish-npm.yml` workflow
+
+To regenerate the token:
+1. Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
+2. Generate new token (Automation type)
+3. Update the `NPM_TOKEN` secret in GitHub
+
+## Distribution Tags
+
+The package uses npm distribution tags:
+
+- `latest` - Stable releases (default when running `npm install -g happy-next`)
+- `preview` - Preview/beta releases (install with `npm install -g happy-next@preview`)
+
+Prerelease versions automatically get the `preview` tag.
+
+## Troubleshooting
+
+### Publish Failed - Version Already Exists
+
+If you try to publish a version that already exists on npm:
+1. Bump the version: `npm version prerelease --preid=preview`
+2. Commit and push
+3. Publishing will retry automatically
+
+### Publish Failed - Authentication Error
+
+Check that the `NPM_TOKEN` secret is valid:
+1. Go to Repository Settings → Secrets
+2. Update `NPM_TOKEN` with a fresh token from npmjs.com
+
+### Build Failed During Publish
+
+The build must succeed before publishing:
+1. Run `npm run build` locally to check for errors
+2. Fix any TypeScript or build issues
+3. Commit and push fixes
+4. Workflow will retry
+
+## Manual Publishing (Emergency)
+
+If you need to publish manually:
+
+```bash
+# Build the project
+npm run build
+
+# Login to npm (first time only)
+npm login
+
+# Publish
+npm publish --access public
+
+# For preview releases, also tag as preview
+npm dist-tag add happy-next@0.11.3-preview.7 preview
+```
+
+## Checking Published Versions
+
+```bash
+# View all published versions
+npm view happy-next versions
+
+# View latest version
+npm view happy-next version
+
+# View all dist-tags
+npm view happy-next dist-tags
+```
+
+## Next Steps
+
+After setting up publishing:
+1. Merge this branch to `main`
+2. Use "Bump Version" workflow to create first npm release
+3. Update documentation to use `npm install -g happy-next`
+4. Announce to users that they can now install from npm!

.github/workflows/build-dist.yml

@@ -0,0 +1,79 @@
+name: Build and Commit Dist
+
+on:
+  push:
+    branches:
+      - main
+      - new/**
+      - feature/**
+      - fix/**
+    paths-ignore:
+      - 'dist/**'
+      - '**.md'
+      - '.github/**'
+
+  workflow_dispatch:
+
+jobs:
+  build-dist:
+    runs-on: ubuntu-latest
+
+    # Prevent infinite loops - skip if commit message contains [skip-build]
+    if: "!contains(github.event.head_commit.message, '[skip-build]')"
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Check for dist changes
+        id: check-changes
+        run: |
+          git add dist
+          if git diff --cached --quiet; then
+            echo "has_changes=false" >> $GITHUB_OUTPUT
+            echo "No changes to dist folder"
+          else
+            echo "has_changes=true" >> $GITHUB_OUTPUT
+            echo "Dist folder has changes"
+          fi
+
+      - name: Commit and push dist
+        if: steps.check-changes.outputs.has_changes == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+          git add dist
+          git commit -m "chore: update dist folder [skip-build]
+
+Built from commit ${{ github.sha }}
+
+This commit was automatically generated by GitHub Actions."
+
+          git push
+
+      - name: Summary
+        run: |
+          echo "## Build Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          if [ "${{ steps.check-changes.outputs.has_changes }}" == "true" ]; then
+            echo "✅ Dist folder updated and committed" >> $GITHUB_STEP_SUMMARY
+          else
+            echo "ℹ️ No changes to dist folder" >> $GITHUB_STEP_SUMMARY
+          fi

.github/workflows/bump-version.yml

@@ -0,0 +1,91 @@
+name: Bump Version
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump_type:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - prerelease
+          - patch
+          - minor
+          - major
+
+jobs:
+  bump-version:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        id: bump
+        run: |
+          OLD_VERSION=$(node -p "require('./package.json').version")
+          echo "old_version=$OLD_VERSION" >> $GITHUB_OUTPUT
+
+          # Bump version based on input
+          if [ "${{ inputs.bump_type }}" = "prerelease" ]; then
+            npm version prerelease --preid=preview --no-git-tag-version
+          else
+            npm version ${{ inputs.bump_type }} --no-git-tag-version
+          fi
+
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+          echo "Bumped version: $OLD_VERSION → $NEW_VERSION"
+
+      - name: Build
+        run: |
+          npm ci
+          npm run build
+
+      - name: Commit changes
+        run: |
+          git add package.json package-next.json dist
+          git commit -m "chore: bump version to ${{ steps.bump.outputs.new_version }} [skip-build]
+
+          Automated version bump: ${{ steps.bump.outputs.old_version }} → ${{ steps.bump.outputs.new_version }}
+
+          🤖 Generated by GitHub Actions"
+
+          git push
+
+      - name: Create and push tag
+        run: |
+          TAG="v${{ steps.bump.outputs.new_version }}"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
+
+          # Update latest-preview tag if this is a prerelease
+          if [[ "${{ steps.bump.outputs.new_version }}" == *"preview"* ]]; then
+            git tag -f latest-preview
+            git push origin latest-preview -f
+          fi
+
+      - name: Summary
+        run: |
+          echo "## 🏷️ Version Bumped" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "**Old Version:** ${{ steps.bump.outputs.old_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "**New Version:** ${{ steps.bump.outputs.new_version }}" >> $GITHUB_STEP_SUMMARY
+          echo "**Bump Type:** ${{ inputs.bump_type }}" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+          echo "The publish workflow will automatically publish this to npm." >> $GITHUB_STEP_SUMMARY