@percepta/create 3.0.0

package/templates/monorepo/gitignore.template

@@ -0,0 +1,31 @@
+# Dependencies
+node_modules/
+.pnpm-store/
+
+# Build outputs
+dist/
+build/
+.turbo/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env files
+.env
+.env.local
+.env.*.local
+
+# Logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# Test coverage
+coverage/

package/templates/monorepo/npmrc.template

@@ -0,0 +1,4 @@
+@percepta:registry=https://registry.npmjs.org/
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+
+engine-strict=true

package/templates/monorepo/package.json.template

@@ -0,0 +1,25 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.0.1",
+  "private": true,
+  "description": "__APP_TITLE__",
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "dev": "pnpm -r --parallel run dev",
+    "build": "pnpm -r run build",
+    "clean": "pnpm -r run clean",
+    "lint": "pnpm -r --parallel --no-bail run lint",
+    "lint:fix": "pnpm -r --no-bail run lint:fix",
+    "test": "pnpm -r run test"
+  },
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=9"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0",
+    "eslint": "^9.18.0",
+    "rimraf": "^5.0.5",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/monorepo/pnpm-workspace.yaml

@@ -0,0 +1,2 @@
+packages:
+  - "packages/*"

package/templates/monorepo/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "resolveJsonModule": true
+  }
+}

package/templates/webapp/.claude/commands/sync.md

@@ -0,0 +1,19 @@
+Sync downstream template changes into this app.
+
+## Steps
+
+1. Read `.mosaic-template.json` in the current package directory to get the template type, current version, and placeholder mappings.
+2. Determine the mosaic repo path: use `$ARGUMENTS` if provided, otherwise check the `MOSAIC_TEMPLATE_PATH` environment variable. If neither is available, ask the user for the path to their local mosaic repo checkout.
+3. Run: `npx @percepta/create sync --mosaic-template-path <path>`
+4. If the command reports "Already up to date" or "No template file changes", inform the user and stop.
+5. Read the generated `.mosaic-sync-context.md` file.
+6. Apply the template changes described in the context file to this app:
+   - Replace placeholder tokens (e.g. `__APP_NAME__`) with actual values from the mapping table
+   - Check `mosaic-template-notes.md` for intentional divergences — preserve them
+   - For files not modified locally, apply changes directly
+   - For files modified locally, merge intelligently, preserving local customizations
+7. Run `pnpm install && pnpm build && pnpm lint` to verify the changes.
+8. Update `.mosaic-template.json`: set `templateVersion` to the new version and update `templateCommit`.
+9. If you made decisions about merge conflicts, add notes to `mosaic-template-notes.md`.
+10. Delete `.mosaic-sync-context.md`.
+11. Summarize what changed and ask the user to review before committing.

package/templates/webapp/.claude/commands/upstream.md

@@ -0,0 +1,17 @@
+Propose app improvements upstream to the mosaic template.
+
+## Steps
+
+1. Read `.mosaic-template.json` in the current package directory to get the template type, current version, and placeholder mappings.
+2. Determine which files to propose upstream: use `$ARGUMENTS` if provided (space-separated file paths), otherwise ask the user which files contain improvements they want to contribute back to the template.
+3. Determine the mosaic repo path: check the `MOSAIC_TEMPLATE_PATH` environment variable. If not set, ask the user for the path to their local mosaic repo checkout.
+4. Run: `npx @percepta/create upstream --mosaic-template-path <path> --files <file1> <file2> ...`
+5. Read the generated `.mosaic-upstream-context.md` file.
+6. For each file listed in the context:
+   - Compare the app version against the template version
+   - Determine which changes are generalizable (useful for all apps) vs app-specific
+   - For generalizable changes, apply them to the template files in the mosaic repo at the path specified in the context
+   - When applying, replace app-specific values with placeholder tokens using the mapping table (replace longest values first to avoid partial matches)
+7. Bump the version in `packages/create-mosaic-module/template-versions.json` in the mosaic repo.
+8. Delete `.mosaic-upstream-context.md`.
+9. Summarize what was changed in the template and ask the user to review the changes in the mosaic repo before committing.

package/templates/webapp/.dockerignore

@@ -0,0 +1,59 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.js
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# local env files
+.env*.local
+.env
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# IDE
+.vscode
+.idea
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Git
+.git
+.gitignore
+
+# Docker
+Dockerfile
+.dockerignore
+
+# Documentation
+README.md
+CHANGELOG.md
+
+# CI/CD
+.github

package/templates/webapp/.gitattributes

@@ -0,0 +1 @@
+src/drizzle/migrations/meta/*_snapshot.json linguist-generated=true

package/templates/webapp/.github/workflows/__APP_NAME__-ryvn-release.yaml

@@ -0,0 +1,114 @@
+name: Build & Release __APP_NAME__
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "packages/__APP_NAME__/src/**"
+      - "packages/__APP_NAME__/scripts/**"
+      - "packages/__APP_NAME__/Dockerfile"
+      - "packages/__APP_NAME__/package.json"
+      - "pnpm-lock.yaml"
+      - ".github/workflows/__APP_NAME__-ryvn-release.yaml"
+  pull_request:
+    branches:
+      - "main"
+    paths:
+      - "packages/__APP_NAME__/src/**"
+      - "packages/__APP_NAME__/scripts/**"
+      - "packages/__APP_NAME__/Dockerfile"
+      - "packages/__APP_NAME__/package.json"
+      - "pnpm-lock.yaml"
+  workflow_dispatch:
+
+env:
+  SERVICE_NAME: __APP_NAME__
+
+jobs:
+  build-and-release:
+    name: Build and Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Ryvn CLI
+        uses: ryvn-technologies/install-ryvn-cli@v1.0.0
+
+      - name: Generate Release Tag
+        id: generate-tag
+        env:
+          RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
+          RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
+        run: |
+          tag_info=$(ryvn generate-release-tag "$SERVICE_NAME" --prefix="${SERVICE_NAME}@" -o json --default-bump-minor)
+
+          version=$(echo "$tag_info" | jq -r '.version')
+          new_tag=$(echo "$tag_info" | jq -r '.tag')
+          channel=$(echo "$tag_info" | jq -r '.channel')
+          isPreview=$(echo "$tag_info" | jq -r '.isPreview')
+
+          echo "version=$version" >> $GITHUB_OUTPUT
+          echo "new_tag=$new_tag" >> $GITHUB_OUTPUT
+          echo "channel=$channel" >> $GITHUB_OUTPUT
+          echo "isPreview=$isPreview" >> $GITHUB_OUTPUT
+
+      - name: Build and Push
+        uses: ryvn-technologies/ryvn-build-action@v1.2.0
+        with:
+          service_name: ${{ env.SERVICE_NAME }}
+          version: ${{ steps.generate-tag.outputs.version }}
+          build_only: ${{ !(github.ref == format('refs/heads/{0}', github.event.repository.default_branch) || steps.generate-tag.outputs.isPreview == 'true') }}
+          ryvn_client_id: ${{ secrets.RYVN_CLIENT_ID }}
+          ryvn_client_secret: ${{ secrets.RYVN_CLIENT_SECRET }}
+
+      - name: Create Ryvn Release
+        if: |
+          !contains(github.event.head_commit.message, '[skip-release]') &&
+          !contains(github.event.pull_request.title, '[skip-release]') &&
+          (steps.generate-tag.outputs.isPreview == 'true' || github.ref == format('refs/heads/{0}', github.event.repository.default_branch))
+        env:
+          RYVN_CLIENT_ID: ${{ secrets.RYVN_CLIENT_ID }}
+          RYVN_CLIENT_SECRET: ${{ secrets.RYVN_CLIENT_SECRET }}
+        run: |
+          version="${{ steps.generate-tag.outputs.new_tag }}"
+          version="${version#"${SERVICE_NAME}@"}"
+          version="${version#@}"
+          channel="${{ steps.generate-tag.outputs.channel }}"
+
+          if [ -n "$channel" ] && [ "$channel" != "null" ]; then
+            ryvn create release "$SERVICE_NAME" "$version" --channel "$channel"
+          else
+            ryvn create release "$SERVICE_NAME" "$version"
+          fi
+
+      - name: Create GitHub Tag
+        if: |
+          github.ref == format('refs/heads/{0}', github.event.repository.default_branch) &&
+          !contains(github.event.head_commit.message, '[skip-release]') &&
+          !contains(github.event.pull_request.title, '[skip-release]')
+        run: |
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          git config --global user.name "github-actions[bot]"
+          git tag "${{ steps.generate-tag.outputs.new_tag }}"
+          git push origin "${{ steps.generate-tag.outputs.new_tag }}"
+
+      - name: Create GitHub Release
+        if: |
+          github.ref == format('refs/heads/{0}', github.event.repository.default_branch) &&
+          !contains(github.event.head_commit.message, '[skip-release]') &&
+          !contains(github.event.pull_request.title, '[skip-release]')
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ steps.generate-tag.outputs.new_tag }}
+          name: ${{ steps.generate-tag.outputs.new_tag }}
+          generate_release_notes: true
+          draft: false
+          prerelease: false

package/templates/webapp/.github/workflows/__APP_NAME__-terraform.yml

@@ -0,0 +1,28 @@
+name: Terraform Validate (__APP_NAME__)
+
+on:
+  push:
+    paths:
+      - "packages/__APP_NAME__/terraform/**"
+      - ".github/workflows/__APP_NAME__-terraform.yml"
+
+jobs:
+  terraform-validate:
+    name: Validate Terraform
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Terraform
+        uses: hashicorp/setup-terraform@v3
+
+      - name: Terraform Init
+        run: terraform -chdir=packages/__APP_NAME__/terraform init -backend=false
+
+      - name: Terraform Format Check
+        run: terraform fmt -check -recursive packages/__APP_NAME__/terraform/
+
+      - name: Terraform Validate
+        run: terraform -chdir=packages/__APP_NAME__/terraform validate

package/templates/webapp/.github/workflows/ci.yml

@@ -0,0 +1,149 @@
+name: Build
+
+on:
+  push: {}
+
+env:
+  PNPM_VERSION: 10.x
+
+jobs:
+  setup:
+    name: Setup
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".node-version"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Check packages are deduplicated
+        run: pnpm dedupe --check
+
+  build:
+    name: Build
+    needs: setup
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".node-version"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build project
+        run: pnpm build
+
+  lint:
+    name: Lint
+    needs: setup
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".node-version"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Run lint checks
+        run: pnpm lint
+
+  check-migrations:
+    name: Check for Migrations
+    needs: setup
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup PNPM
+        uses: pnpm/action-setup@v4
+        with:
+          version: ${{ env.PNPM_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ".node-version"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Generate migration check
+        run: pnpm db:generate
+
+      - name: Check for journal changes
+        run: git diff --exit-code src/drizzle/migrations/meta/_journal.json
+
+  # ──────────────────────────────────────────────────────────────────────────────
+  # Docker Build Validation
+  # ──────────────────────────────────────────────────────────────────────────────
+
+  changes:
+    name: Detect Changes
+    runs-on: ubuntu-latest
+    outputs:
+      root: ${{ steps.filter.outputs.root }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            root:
+              - 'src/**'
+              - 'scripts/**'
+              - 'Dockerfile'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'tsconfig.json'
+
+  docker-build-root:
+    name: Docker Build (root)
+    needs: changes
+    if: needs.changes.outputs.root == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build Docker image
+        run: docker build --build-arg NPM_TOKEN=${{ secrets.NPM_TOKEN }} -t __APP_NAME__:ci .
+      - name: Verify server.js is valid
+        run: docker run --rm __APP_NAME__:ci node --check server.js

package/templates/webapp/.node-version

@@ -0,0 +1,2 @@
+24.4.1
+

package/templates/webapp/.prettierrc.mjs

@@ -0,0 +1,5 @@
+import { createPrettierConfigReact } from "@percepta/build/prettier";
+
+export default createPrettierConfigReact({
+  tailwindStylesheet: "./src/styles/globals.css",
+});