@erclx/aitk 0.8.0

package/tooling/vite-react/configs/playwright.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig, devices } from '@playwright/test'
+
+const isCI = !!process.env.CI
+
+export default defineConfig({
+  testDir: 'e2e',
+  forbidOnly: isCI,
+  retries: isCI ? 2 : 0,
+  workers: isCI ? 1 : undefined,
+  reporter: isCI ? 'list' : 'html',
+  use: {
+    trace: 'on-first-retry',
+    baseURL: 'http://localhost:5173',
+  },
+  projects: [
+    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+  ],
+  webServer: {
+    command: 'bun run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !isCI,
+  },
+})

package/tooling/vite-react/configs/tsconfig.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": [
+      "vite/client",
+      "vitest/globals",
+      "@testing-library/jest-dom",
+      "node"
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "src",
+    "vite.config.ts",
+    "vitest.config.ts",
+    "e2e",
+    "playwright.config.ts"
+  ]
+}

package/tooling/vite-react/configs/vite.config.ts

@@ -0,0 +1,14 @@
+import tailwindcss from '@tailwindcss/vite'
+import react from '@vitejs/plugin-react'
+import path from 'path'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+  base: process.env.VITE_BASE_URL ?? '/',
+})

package/tooling/vite-react/configs/vitest.config.ts

@@ -0,0 +1,26 @@
+import { defineConfig, mergeConfig } from 'vitest/config'
+
+import viteConfig from './vite.config'
+
+export default mergeConfig(
+  viteConfig,
+  defineConfig({
+    test: {
+      environment: 'jsdom',
+      globals: true,
+      setupFiles: ['src/test/setup.ts'],
+      passWithNoTests: true,
+      exclude: [
+        '**/node_modules/**',
+        '**/dist/**',
+        '**/e2e/**',
+        '**/.{idea,git,cache,output,temp}/**',
+      ],
+      coverage: {
+        provider: 'v8',
+        reporter: ['text', 'json', 'html'],
+        exclude: ['node_modules/', 'src/test/setup.ts', 'e2e/'],
+      },
+    },
+  }),
+)

package/tooling/vite-react/manifest.toml

@@ -0,0 +1,21 @@
+[stack]
+name = "vite-react"
+extends = "web"
+runtime = "bun"
+scaffold = "bun create vite@latest {{name}} --template react-ts"
+
+[dependencies.dev]
+packages = [
+  "vite",
+  "@vitejs/plugin-react",
+]
+
+[scripts]
+"dev" = "vite"
+"build" = "tsc --noEmit && vite build"
+"preview" = "vite preview"
+"typecheck" = "tsc --noEmit"
+"setup" = "./scripts/setup.sh"
+
+[scripts.override]
+"build" = "tsc --noEmit && vite build"

package/tooling/vite-react/reference.md

@@ -0,0 +1,55 @@
+# Tooling vite-react reference
+
+> Extends: `web`. Apply web stack first.
+
+## Overview
+
+The vite-react stack covers Vite + React + TypeScript projects: web apps and Chrome extensions. It ships golden configs for `vite.config.ts`, `vitest.config.ts` (merging from vite config), `playwright.config.ts`, and a unified `tsconfig.json` with `@/` path alias. Shared web tooling (ESLint, screenshot template, VS Code, CI, verify script) comes from the `web` layer.
+
+## Scaffold checklist
+
+1. Scaffold with `bunx create-vite@latest <name> --template react-ts` (web apps) or `bunx create-crxjs@latest` (Chrome extensions).
+2. Install base and web tooling: `aitk tooling sync web .`
+3. Install vite-react deps and configs: `aitk tooling sync vite-react .`
+4. Extend `.claude/context/ci.md` and `.claude/context/development.md` per the web reference's extend sections plus the vite-react rows below.
+5. Run `bun run lint:fix` then `bun run check`.
+
+## What ships as golden configs
+
+- `vite.config.ts`: `@vitejs/plugin-react`, `@tailwindcss/vite`, `@` path alias to `./src`, `VITE_BASE_URL` env for base path.
+- `vitest.config.ts`: merges from `vite.config.ts`, jsdom, globals, setup file, `passWithNoTests: true`, v8 coverage.
+- `playwright.config.ts`: all browsers, `webServer` on `bun run dev` at port 5173, trace under `use`.
+- `tsconfig.json`: unified, `noEmit: true`, `skipLibCheck: true`, `@/` paths, `vitest/globals` and `@testing-library/jest-dom` in types.
+
+## Chrome extension variant
+
+When scaffolding a Chrome extension, override the installed golden configs:
+
+- `vite.config.ts`: use `crx({ manifest })` and `zip()` from `@crxjs/vite-plugin` instead of `react()` alone. Set `server.port: 5173`, `server.strictPort: true`, `server.hmr.clientPort: 5173`, and `chrome-extension://` in CORS origins. Drop `VITE_BASE_URL`.
+- `vitest.config.ts`: use a standalone `defineConfig` (no `mergeConfig`). crxjs plugin breaks Vitest. Declare `@vitejs/plugin-react` and `@tailwindcss/vite` directly. Add `**/release/**` to excludes and `manifest.config.ts`, `**/*.d.ts` to coverage excludes.
+- `playwright.config.ts`: chromium-only (Firefox and WebKit cannot run extensions). Bundled `chromium` channel. No `baseURL` or `webServer`. Tests load the built extension directly from `dist/`.
+- `e2e/fixtures.ts`: extend Playwright base `test` with `context` (persistent context loading the extension from `dist/`) and `extensionId` (extracted from service worker URL). Rename `use` to `apply` to avoid the React hooks ESLint rule. `waitForEvent('serviceworker')` blocks until the MV3 service worker registers.
+- `manifest.config.ts`: use `defineManifest` from `@crxjs/vite-plugin`. Read `name` and `version` from `package.json`. Entry points `src/popup/index.html`, `src/sidepanel/index.html`, `src/background/index.ts`, `src/content/main.tsx`. Permissions `sidePanel`, `contentSettings`, `storage`. Icon `public/logo.png` at size 48.
+- `screenshot` script: `bun run build && bun e2e/screenshot.ts` (no preview server).
+- Additional gitignore entries: `*.crx`, `*.pem`, `release/`.
+
+## Setup script
+
+- File: `scripts/setup.sh`. Destructive: deletes `.git` and self-removes after running. Run once immediately after scaffolding.
+- Prompt for project name, normalize to kebab-case, derive title-cased display name.
+- Update `package.json` name and version, inject verify/clean/update scripts, remove setup.
+- Update `<title>` tags in HTML files.
+- Wipe `.git`, re-init, make scripts executable, commit as `chore(root): initialize <name>`.
+
+## Development docs (extend)
+
+Append to the `## Scripts` table:
+
+| `bun run dev` | Start the Vite dev server on port 5173. |
+| `bun run build` | Typecheck then build the production bundle. |
+| `bun run preview` | Serve the built bundle locally. |
+| `bun run typecheck` | Run `tsc --noEmit`. |
+
+## CI docs (extend)
+
+In `.claude/context/ci.md`, the Typecheck row's assertion reads: `` `tsc --noEmit` passes ``.

package/tooling/vite-react/seeds/.cspell/project-terms.txt

@@ -0,0 +1 @@
+

package/tooling/vite-react/seeds/.cspell/tech-stack.txt

@@ -0,0 +1 @@
+Vite

package/tooling/web/configs/.github/workflows/verify.yml

@@ -0,0 +1,134 @@
+name: Verify
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  static-checks:
+    name: 🔍 Static Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Install Shell Tools
+        run: sudo apt-get install -y shfmt shellcheck
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Lint
+        run: bun run lint
+
+      - name: Check Formatting
+        run: bun run check:format
+
+      - name: Check Spelling
+        run: bun run check:spell
+
+      - name: Check Shell
+        run: bun run check:shell
+
+  unit-tests:
+    name: 🧪 Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run Tests
+        run: bun run test:coverage
+
+  build-verify:
+    name: 🏗️ Build
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+  e2e-tests:
+    name: 🎭 E2E Tests
+    runs-on: ubuntu-latest
+    needs: [static-checks, unit-tests, build-verify]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install Dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Cache Playwright Browsers
+        id: playwright-cache
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('**/package.json') }}
+
+      - name: Install Playwright Chromium
+        if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: bunx playwright install chromium
+
+      - name: Run E2E Tests
+        run: bun run test:e2e --project=chromium
+
+      - name: Upload E2E Report
+        uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 7

package/tooling/web/configs/.vscode/extensions.json

@@ -0,0 +1,13 @@
+{
+  "recommendations": [
+    "esbenp.prettier-vscode",
+    "streetsidesoftware.code-spell-checker",
+    "mkhl.shfmt",
+    "timonwong.shellcheck",
+    "mads-hartmann.bash-ide-vscode",
+    "dbaeumer.vscode-eslint",
+    "bradlc.vscode-tailwindcss",
+    "ms-playwright.playwright",
+    "vitest.explorer"
+  ]
+}

package/tooling/web/configs/.vscode/settings.json

@@ -0,0 +1,10 @@
+{
+  "shellcheck.customArgs": ["--severity=warning"],
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": "explicit"
+  },
+  "files.associations": {
+    "*.css": "tailwindcss"
+  }
+}

package/tooling/web/configs/e2e/home.spec.ts

@@ -0,0 +1,6 @@
+import { expect, test } from '@playwright/test'
+
+test('home page loads', async ({ page }) => {
+  await page.goto('/')
+  await expect(page).toHaveTitle(/.+/)
+})

package/tooling/web/configs/e2e/screenshot.ts

@@ -0,0 +1,41 @@
+import type { Page } from '@playwright/test'
+
+const ROUTES = [{ name: 'home', path: '/', width: 1280, height: 800 }]
+
+type State = { name: string; setup?: (page: Page) => Promise<void> }
+const STATES: State[] = [
+  { name: 'default' },
+  { name: 'dark', setup: async (p) => p.emulateMedia({ colorScheme: 'dark' }) },
+]
+
+import { chromium } from '@playwright/test'
+import { mkdir } from 'fs/promises'
+import path from 'path'
+
+const BASE_URL = process.env.SCREENSHOT_BASE_URL ?? 'http://localhost:4173'
+const OUT_DIR = 'screenshots'
+
+const browser = await chromium.launch()
+await mkdir(OUT_DIR, { recursive: true })
+
+for (const route of ROUTES) {
+  for (const state of STATES) {
+    const ctx = await browser.newContext({
+      viewport: { width: route.width, height: route.height },
+    })
+    const page = await ctx.newPage()
+
+    if (state.setup) await state.setup(page)
+
+    await page.goto(`${BASE_URL}${route.path}`)
+    await page.waitForLoadState('networkidle')
+
+    const file = path.join(OUT_DIR, `${route.name}-${state.name}.png`)
+    await page.screenshot({ path: file, fullPage: true })
+    console.log(`captured ${file}`)
+
+    await ctx.close()
+  }
+}
+
+await browser.close()

package/tooling/web/configs/eslint.config.js

@@ -0,0 +1,82 @@
+import js from '@eslint/js'
+import { defineConfig, globalIgnores } from 'eslint/config'
+import prettier from 'eslint-config-prettier'
+import checkFile from 'eslint-plugin-check-file'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import simpleImportSort from 'eslint-plugin-simple-import-sort'
+import vitest from 'eslint-plugin-vitest'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+
+export default defineConfig([
+  globalIgnores([
+    'dist',
+    'dist-ssr',
+    'coverage',
+    'release',
+    '.claude',
+    '.vscode',
+    '.husky',
+    'test-results',
+    'playwright-report',
+    'blob-report',
+    'playwright/.cache',
+  ]),
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx,js,jsx}'],
+    plugins: {
+      'react-hooks': reactHooks,
+      'react-refresh': reactRefresh,
+      'simple-import-sort': simpleImportSort,
+      'check-file': checkFile,
+    },
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
+    },
+    rules: {
+      ...reactHooks.configs.recommended.rules,
+      'react-refresh/only-export-components': [
+        'warn',
+        { allowConstantExport: true },
+      ],
+      'simple-import-sort/imports': 'error',
+      'simple-import-sort/exports': 'error',
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        { varsIgnorePattern: '^_', argsIgnorePattern: '^_' },
+      ],
+      'check-file/filename-naming-convention': [
+        'error',
+        { '**/!(App).{ts,tsx}': 'KEBAB_CASE' },
+        { ignoreMiddleExtensions: true },
+      ],
+      'check-file/folder-naming-convention': [
+        'error',
+        { 'src/**/!(__tests__)': 'KEBAB_CASE' },
+      ],
+    },
+  },
+  {
+    files: ['**/*.test.{ts,tsx}', '**/*.spec.{ts,tsx}'],
+    ...vitest.configs.recommended,
+  },
+  {
+    files: [
+      '*.config.{js,mjs,cjs,ts}',
+      'vite.config.ts',
+      'vitest.config.ts',
+      'playwright.config.ts',
+    ],
+    languageOptions: {
+      globals: {
+        ...globals.node,
+      },
+    },
+  },
+  prettier,
+])

package/tooling/web/configs/scripts/screenshot.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+: "${PREVIEW_PORT:=4173}"
+
+if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Port $PREVIEW_PORT already in use. Stop the listening process or set PREVIEW_PORT." >&2
+  exit 1
+fi
+
+bun run build
+bun run preview >/dev/null 2>&1 &
+PREVIEW_PID=$!
+trap 'kill "$PREVIEW_PID" 2>/dev/null; wait "$PREVIEW_PID" 2>/dev/null || true' EXIT
+
+for _ in $(seq 1 40); do
+  if curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+    break
+  fi
+  sleep 0.25
+done
+
+if ! curl -sSf "http://localhost:$PREVIEW_PORT/" >/dev/null 2>&1; then
+  echo "Preview server not responding on port $PREVIEW_PORT after 10s." >&2
+  exit 1
+fi
+
+SCREENSHOT_BASE_URL="http://localhost:$PREVIEW_PORT" bun e2e/screenshot.ts

package/tooling/web/configs/scripts/verify.sh

@@ -0,0 +1,80 @@
+#!/bin/bash
+set -e
+set -o pipefail
+
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+WHITE='\033[1;37m'
+GREY='\033[0;90m'
+NC='\033[0m'
+
+NESTED="${VERIFY_NESTED:-false}"
+
+log_info() { echo -e "${GREY}│${NC} ${GREEN}✓${NC} $1"; }
+log_error() {
+  echo -e "${GREY}│${NC} ${RED}✗${NC} $1"
+  exit 1
+}
+log_step() { echo -e "${GREY}│${NC}\n${GREY}├${NC} ${WHITE}$1${NC}"; }
+
+pipe_output() { while IFS= read -r line; do echo -e "${GREY}│${NC}  $line"; done; }
+
+check_dependencies() {
+  command -v bun >/dev/null 2>&1 || log_error "bun is not installed"
+}
+
+run_check() {
+  local cmd=$1
+  local err_msg=$2
+  local output
+  if ! output=$(eval "$cmd" 2>&1); then
+    echo "$output" | pipe_output
+    log_error "$err_msg"
+  fi
+  echo "$output" | pipe_output
+}
+
+main() {
+  check_dependencies
+
+  if [ "$NESTED" = false ]; then echo -e "${GREY}┌${NC}"; fi
+
+  echo -e "${GREY}├${NC} ${WHITE}Typecheck${NC}"
+  run_check "bun run typecheck" "Typecheck failed"
+  log_info "Typecheck passed"
+
+  log_step "Lint"
+  run_check "bun run lint" "Lint failed"
+  log_info "Lint passed"
+
+  log_step "Formatting"
+  run_check "bun run format" "Format failed"
+  log_info "Format applied"
+
+  log_step "Format check"
+  run_check "bun run check:format" "Format check failed"
+  log_info "Format check passed"
+
+  log_step "Spelling"
+  run_check "bun run check:spell" "Spell check failed"
+  log_info "Spell check passed"
+
+  log_step "Shell"
+  run_check "bun run check:shell" "Shell check failed"
+  log_info "Shell check passed"
+
+  log_step "Unit tests"
+  run_check "bun run test:run" "Unit tests failed"
+  log_info "Unit tests passed"
+
+  log_step "Build"
+  run_check "bun run build" "Build failed"
+  log_info "Build passed"
+
+  if [ "$NESTED" = false ]; then
+    echo -e "${GREY}└${NC}\n"
+    echo -e "${GREEN}✓ Verification passed${NC}"
+  fi
+}
+
+main "$@"

package/tooling/web/configs/src/test/setup.ts

@@ -0,0 +1,8 @@
+import '@testing-library/jest-dom'
+
+import { cleanup } from '@testing-library/react'
+import { afterEach } from 'vitest'
+
+afterEach(() => {
+  cleanup()
+})

package/tooling/web/manifest.toml

@@ -0,0 +1,57 @@
+[stack]
+name = "web"
+extends = "base"
+runtime = "bun"
+scaffold = ""
+
+[dependencies.dev]
+packages = [
+  "eslint@^9",
+  "eslint-config-prettier",
+  "eslint-plugin-check-file",
+  "eslint-plugin-react-hooks",
+  "eslint-plugin-react-refresh",
+  "eslint-plugin-simple-import-sort",
+  "eslint-plugin-vitest",
+  "globals",
+  "typescript-eslint",
+  "@eslint/js",
+  "typescript",
+  "react",
+  "react-dom",
+  "@types/react",
+  "@types/react-dom",
+  "@types/node",
+  "vitest@^3",
+  "@vitest/coverage-v8@^3",
+  "@vitest/ui@^3",
+  "jsdom",
+  "@testing-library/react",
+  "@testing-library/jest-dom",
+  "@testing-library/user-event",
+  "@playwright/test",
+  "tailwindcss",
+  "@tailwindcss/vite",
+  "prettier-plugin-tailwindcss",
+]
+
+[scripts]
+"lint" = "eslint . --max-warnings 0"
+"lint:fix" = "eslint . --fix --max-warnings 0"
+"test" = "vitest"
+"test:run" = "vitest run --reporter=verbose"
+"test:ui" = "vitest --ui"
+"test:coverage" = "vitest run --coverage"
+"test:e2e" = "playwright test"
+"test:e2e:ui" = "playwright test --ui"
+"test:e2e:report" = "playwright show-report"
+"check:full" = "./scripts/verify.sh && bun run test:e2e"
+
+[scripts.override]
+"screenshot" = "bash scripts/screenshot.sh"
+
+[gitignore]
+"# Build" = ["dist/"]
+"# Coverage" = ["coverage/"]
+"# Playwright" = ["test-results/", "playwright-report/", "blob-report/", "playwright/.cache/", "screenshots/"]
+"# VSCode" = [".vscode/*", "!.vscode/extensions.json", "!.vscode/settings.json"]