From 5f389e816bcf881e514d8e2d201659f9d67c15de Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Thu, 11 Dec 2025 03:15:59 -0500 Subject: [PATCH 1/4] docs: restructure quality gates documentation with detailed validation rules - Reorganize quality gates into mandatory sections for main project and UI - Add comprehensive ESLint and TypeScript configuration tables - Include automatic enforcement and pre-commit hook information - Update development server usage instructions - Expand Pre-PR checklist with separate validation steps --- CLAUDE.md | 155 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 86 insertions(+), 69 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index cc88bcd1..c83fbf0e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,92 +13,105 @@ CLI wrapper for instant switching between multiple Claude accounts and alternati - **DRY**: One source of truth (config.json) - **CLI-First**: All features must have CLI interface -## TypeScript Quality Gates +## Quality Gates (MANDATORY) -**The npm package is 100% TypeScript. Quality gates MUST pass before publish.** +Quality gates MUST pass before committing. Run from project root. + +### Main Project (src/) -**Package Manager: bun** - 10-25x faster than npm ```bash -bun install # Install dependencies (creates bun.lockb) -bun run build # Compile src/ → dist/ -bun run validate # Full validation: typecheck + lint:fix + format:check + test +# Full validation (REQUIRED before commit/PR) +bun run validate # typecheck + lint:fix + format:check + test:all + +# Individual commands +bun run typecheck # tsc --noEmit +bun run lint:fix # eslint src/ --fix +bun run format:check # prettier --check src/ +bun run test:all # bun test + +# Fix issues +bun run lint:fix # Auto-fix lint issues +bun run format # Auto-fix formatting (prettier --write) ``` -**Fix issues before committing:** +**ESLint rules (eslint.config.mjs) - ALL errors:** +| Rule | Level | Notes | +|------|-------|-------| +| `@typescript-eslint/no-unused-vars` | error | Ignore `_` prefix | +| `@typescript-eslint/no-explicit-any` | error | Use proper types or `unknown` | +| `@typescript-eslint/no-non-null-assertion` | error | No `!` assertions | +| `prefer-const`, `no-var`, `eqeqeq` | error | Code quality | + +**TypeScript (tsconfig.json) - strict mode:** +| Option | Value | Notes | +|--------|-------|-------| +| `strict` | true | All strict flags enabled | +| `noUnusedLocals` | true | No unused variables | +| `noUnusedParameters` | true | No unused params | +| `noImplicitReturns` | true | All paths must return | +| `noFallthroughCasesInSwitch` | true | Explicit case handling | + +### UI Project (ui/) + ```bash +cd ui + +# Full validation (REQUIRED before commit/PR) +bun run validate # typecheck + lint:fix + format:check (no tests) + +# Individual commands +bun run typecheck # tsc -b --noEmit +bun run lint:fix # eslint . --fix +bun run format:check # prettier --check src/ + +# Fix issues bun run lint:fix # Auto-fix lint issues bun run format # Auto-fix formatting ``` -**Automatic enforcement:** -- `prepublishOnly` / `prepack` runs `validate` + `sync-version.js` +**ESLint rules (ui/eslint.config.js) - ALL errors:** +| Rule | Level | Notes | +|------|-------|-------| +| `@typescript-eslint/no-unused-vars` | error | Ignore `_` prefix | +| `@typescript-eslint/no-explicit-any` | error | Use proper types or `unknown` | +| `@typescript-eslint/no-non-null-assertion` | error | No `!` assertions | +| `prefer-const`, `no-var`, `eqeqeq` | error | Code quality | +| `react-hooks/*` | recommended | Hooks rules from plugin | +| `react-refresh/*` | vite | Fast refresh compatibility | + +**TypeScript (ui/tsconfig.app.json) - strict mode:** +| Option | Value | Notes | +|--------|-------|-------| +| `strict` | true | All strict flags enabled | +| `noUnusedLocals` | true | No unused variables | +| `noUnusedParameters` | true | No unused params | +| `noFallthroughCasesInSwitch` | true | Explicit case handling | +| `erasableSyntaxOnly` | true | No runtime type constructs | +| `noUncheckedSideEffectImports` | true | Validate side-effect imports | + +### Automatic Enforcement + +- `prepublishOnly` / `prepack` runs `build:all` + `validate` + `sync-version.js` - CI/CD runs `bun run validate` on every PR +- husky pre-commit hooks enforce conventional commits -**File structure:** -- `src/` - TypeScript source (55 modules) -- `dist/` - Compiled JavaScript (npm package) -- `lib/` - Native shell scripts (bash, PowerShell) -- `ui/` - React dashboard (Vite + React 19 + shadcn/ui) +### File Structure -**Development server (ALWAYS use for testing UI changes):** -```bash -bun run dev # Start dev server with hot reload (http://localhost:3000) ``` -**IMPORTANT:** Use `bun run dev` at CCS root level for always up-to-date code. Do NOT use `ccs config` during development as it uses the globally installed (outdated) version. - -## UI Quality Gates (React Dashboard) - -**The ui/ directory has IDENTICAL quality gates to the main project.** - -**Package Manager: bun** (same as root) -```bash -cd ui -bun install # Install dependencies -bun run build # TypeScript + Vite build -bun run validate # Full validation: typecheck + lint:fix + format:check +src/ → TypeScript source (main project) +dist/ → Compiled JavaScript (npm package) +lib/ → Native shell scripts (bash, PowerShell) +ui/src/ → React components, hooks, pages +ui/src/components/ui/ → shadcn/ui components +dist/ui/ → Built UI bundle (served by Express) ``` -**Fix issues before committing:** +### Development Server + ```bash -cd ui -bun run typecheck # Type check only -bun run lint:fix # Auto-fix lint issues -bun run format # Auto-fix formatting -bun run format:check # Verify formatting (no changes) +bun run dev # Build + start config server (http://localhost:3000) ``` - -**Linting rules (ui/eslint.config.js) - ALL errors:** -- `@typescript-eslint/no-unused-vars` - error (ignore `_` prefix) -- `@typescript-eslint/no-explicit-any` - error -- `@typescript-eslint/no-non-null-assertion` - error -- `prefer-const`, `no-var`, `eqeqeq` - error -- `react-hooks/exhaustive-deps` - warning -- `react-refresh/only-export-components` - error - -**Type safety (ui/tsconfig.app.json):** -- `strict: true` with `verbatimModuleSyntax` enabled -- `noUnusedLocals`, `noUnusedParameters` - enabled -- Type-only imports required: `import type { X }` for types - -**UI file structure:** -- `ui/src/` - React components, hooks, pages -- `ui/src/components/ui/` - shadcn/ui components -- `ui/src/hooks/` - Custom React hooks -- `ui/src/pages/` - Route pages -- `ui/src/providers/` - Context providers -- `dist/ui/` - Built bundle (served by Express) - -**Linting rules (eslint.config.mjs) - ALL errors:** -- `@typescript-eslint/no-unused-vars` - error (ignore `_` prefix) -- `@typescript-eslint/no-explicit-any` - error -- `@typescript-eslint/no-non-null-assertion` - error -- `prefer-const`, `no-var`, `eqeqeq` - error - -**Type safety (tsconfig.json):** -- `strict: true` with all strict flags enabled -- `noUnusedLocals`, `noUnusedParameters`, `noImplicitReturns` - enabled -- Avoid `any` types - use proper typing or `unknown` -- Avoid `@ts-ignore` - fix the type error properly +**IMPORTANT:** Use `bun run dev` at CCS root for always up-to-date code. Do NOT use `ccs config` during development as it uses the globally installed version. ## Critical Constraints (NEVER VIOLATE) @@ -375,7 +388,11 @@ rm -rf ~/.ccs # Clean environment ## Pre-PR Checklist (MANDATORY) -- [ ] `bun run validate` passes (typecheck + lint:fix + format:check + tests) +**Quality Gates:** +- [ ] `bun run validate` passes (main: typecheck + lint:fix + format:check + tests) +- [ ] `cd ui && bun run validate` passes (ui: typecheck + lint:fix + format:check) + +**Code Quality:** - [ ] All commits follow conventional format (`feat:`, `fix:`, etc.) - [ ] `--help` updated and consistent across src/ccs.ts, lib/ccs, lib/ccs.ps1 - [ ] ASCII only (NO emojis), NO_COLOR respected From 3de9083959bfd7214e06e46e7386cf2683c00ed5 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 11 Dec 2025 08:32:10 +0000 Subject: [PATCH 2/4] chore(release): 5.15.0-dev.1 [skip ci] --- VERSION | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/VERSION b/VERSION index 8635c562..60493838 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -5.15.0 +5.15.0-dev.1 diff --git a/package.json b/package.json index 7ed1a9c7..a805b258 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@kaitranntt/ccs", - "version": "5.15.0", + "version": "5.15.0-dev.1", "description": "Claude Code Switch - Instant profile switching between Claude Sonnet 4.5 and GLM 4.6", "keywords": [ "cli", From bff6acb2af4cb384ea2308b8b48270a2e7db5b5d Mon Sep 17 00:00:00 2001 From: kaitranntt Date: Thu, 11 Dec 2025 20:52:17 -0500 Subject: [PATCH 3/4] chore: add GitHub Sponsors funding configuration Add FUNDING.yml to enable "Sponsor" button on repository --- .github/FUNDING.yml | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 .github/FUNDING.yml diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 00000000..5134f32b --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,7 @@ +# These are supported funding model platforms + +github: kaitranntt +# ko_fi: kaitranntt +# buy_me_a_coffee: kaitranntt +# polar: kaitranntt +custom: ['https://ccs.kaitran.ca/sponsor'] From a50d2605c937bdd2238e0ea7f253ef097cb375ea Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 12 Dec 2025 01:54:50 +0000 Subject: [PATCH 4/4] chore(release): 5.15.0-dev.2 [skip ci] --- VERSION | 2 +- package.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/VERSION b/VERSION index 60493838..9228ee11 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -5.15.0-dev.1 +5.15.0-dev.2 diff --git a/package.json b/package.json index a805b258..f9e63504 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@kaitranntt/ccs", - "version": "5.15.0-dev.1", + "version": "5.15.0-dev.2", "description": "Claude Code Switch - Instant profile switching between Claude Sonnet 4.5 and GLM 4.6", "keywords": [ "cli",