diff --git a/.claude/skills/review-dev/SKILL.md b/.claude/skills/review-dev/SKILL.md new file mode 100644 index 000000000..b190cb883 --- /dev/null +++ b/.claude/skills/review-dev/SKILL.md @@ -0,0 +1,72 @@ +--- +description: Run a code review of changes on the current branch against origin/dev +disable-model-invocation: true +--- + + + +Run a code review of changes on the current branch against origin/dev. + +## Setup + +1. Run: `git fetch origin dev && git diff $(git merge-base HEAD origin/dev) HEAD` +2. If the diff exceeds 2000 lines, summarize changes per file first, then deep-dive into critical files. + +## Ignore List + +Skip reviewing these files — they are auto-generated or non-logic: +- `pnpm-lock.yaml`, `package-lock.json` +- `prisma/generated/**`, `dist/**` +- `*.min.js`, `*.map` + +## Review Against CLAUDE.md Rules + +Check every changed file against these categories: + +### Type Safety (Code Standards 1–3) +- No `any` types — proper types must be defined +- No non-null assertions (`!`) — handle nullability explicitly +- No `as unknown as T` casts — find type-safe alternatives + +### Code Quality (Code Standards 4–7) +- Single quotes for strings; template literals over concatenation +- Full code only — no placeholders, stubs, or TODOs left in +- Type prefixes: `T` for types, `I` for interfaces, `_` for unused params +- Named exports over default exports + +### Code Review Checklist +1. **No duplication** — reuse existing components, utils, patterns +2. **Error handling** — proper types, no swallowed errors, no silent catches +3. **Import hygiene** — use path aliases (`@react/*`, `@shared/*`), no circular deps, no deprecated `@src/*` +4. **Naming** — consistent with codebase conventions +5. **Comments** — inline for non-obvious logic; JSDoc for exported APIs + +### Security +- No hardcoded secrets, API keys, or tokens +- No `.env` files committed +- User input is validated/sanitized +- Public endpoints have rate limiting + +### "Do NOT" Violations +- New dependencies without justification +- Pre-commit hook bypass (`--no-verify`) +- Missing error handling on external calls + +## Output Format + +For each issue found, report: +- **Severity**: Critical / High / Medium / Low +- **File**: path and line number +- **Rule**: which rule or checklist item was violated +- **Issue**: what's wrong +- **Fix**: how to remediate + +## Summary + +End with: +1. Total issues by severity +2. Overall verdict: **Approve** or **Request Changes** +3. If Request Changes, list the blocking issues that must be fixed diff --git a/.claude/skills/security-review-dev/SKILL.md b/.claude/skills/security-review-dev/SKILL.md new file mode 100644 index 000000000..25728f49b --- /dev/null +++ b/.claude/skills/security-review-dev/SKILL.md @@ -0,0 +1,82 @@ +--- +description: Run a security-focused review of changes on the current branch against origin/dev +disable-model-invocation: true +--- + + + +Run a security-focused review of changes on the current branch against origin/dev. + +## Setup + +1. Run: `git fetch origin dev && git diff $(git merge-base HEAD origin/dev) HEAD` +2. Run: `pnpm audit` to check for known vulnerabilities in dependencies. + +## Security Checks + +Analyze ONLY for security issues across these categories: + +### Injection Attacks +- **SQL injection** — raw queries with unsanitized input, missing parameterized queries +- **Command injection** — user input in `exec`, `spawn`, `execSync`, or shell commands +- **XSS** — unescaped user content rendered in HTML/JSX (bypass of DOMPurify) +- **Template injection** — user input in EJS templates or string interpolation +- **LDAP injection** — unsanitized input in directory queries + +### Hardcoded Secrets +- API keys, tokens, passwords, connection strings in source code +- `.env` files or secret values committed to the repository +- Secrets logged to console or written to error responses + +### Authentication & Authorization +- Missing or broken permission checks on routes/endpoints +- JWT/session validation gaps +- Privilege escalation paths (e.g., user accessing admin routes) +- Missing CSRF protection on state-changing endpoints + +### Sensitive Data Exposure +- PII or tokens in logs, error messages, or client responses +- Stack traces or internal paths exposed to clients +- Sensitive data in URL query parameters + +### Dependency Security +- Newly added packages — flag for review and justify necessity +- `pnpm audit` findings — report any critical/high vulnerabilities +- Packages with known CVEs or low maintenance activity + +### Server Configuration +- **CORS misconfiguration** — overly permissive origins (`*`), missing credential restrictions +- **CSP misconfiguration** — missing or overly permissive Content-Security-Policy headers +- **Missing security headers** — Helmet is available; check it is applied correctly +- **Rate limiting** — new public endpoints without `express-rate-limit` + +### Unsafe Code Patterns +- **Unsafe deserialization** — untrusted input passed to `JSON.parse` without try/catch, `eval`, or dynamic `require`/`import` +- **Prototype pollution** — `Object.assign`, spread, or deep-merge with user-controlled keys +- **Path traversal** — user-controlled input in `fs.readFile`, `path.join`, or file upload paths without sanitization +- **SSRF** — user-controlled URLs passed to `fetch`, `axios`, or `http.request` without allowlist validation +- **Regex DoS (ReDoS)** — complex regex patterns on user-supplied input + +## Reporting + +Report ALL findings regardless of confidence level. + +Format each finding as: +- **Severity**: Critical / High / Medium / Low +- **File**: path and line number +- **Issue**: what's wrong +- **Impact**: what an attacker could achieve +- **Fix**: how to remediate (with code example if applicable) + +## Summary + +End with: +1. Count of findings by severity +2. `pnpm audit` results summary +3. Overall security verdict: **Pass** / **Needs Remediation** / **Fail** +4. If Fail, list the blocking issues diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..fc76bce0e --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,92 @@ +# CLAUDE.md - SmythOS UI + +Open-source pnpm monorepo for building and deploying AI agents. + +## Project Structure + +- `packages/app` — Builder UI, React 18 frontend (Vite + Rollup), Express backend +- `packages/middleware` — Core API (Prisma/MySQL), auth, services +- `packages/runtime` — Agent execution server + +## Quick Reference + +```bash +pnpm install # Install all dependencies +pnpm build # Production build (all packages) +pnpm dev # Start all packages in dev mode + +# packages/app +pnpm --filter smyth-builder type-check # TypeScript type checking +pnpm --filter smyth-builder format # Prettier format +pnpm --filter smyth-builder knip # Dead code detection + +# packages/middleware +pnpm --filter middleware test # Run Vitest tests +pnpm --filter middleware lint # ESLint +pnpm --filter middleware prisma:generate # Regenerate Prisma client +pnpm --filter middleware prisma:migrate # Run DB migrations +``` + +## Path Aliases (`packages/app`) + +| Alias | Resolves to | +|-------|-------------| +| `@react/*` | `src/react/*` | +| `@shared/*` | `src/shared/*` | +| `@src/*` | `src/*` *(deprecated — do not use in new code)* | + +## Tech Stack + +- **Runtime**: Node.js, TypeScript 5.x (strict mode in React app) +- **Frontend**: React 18, Zustand, TanStack Query, Tailwind CSS 3, Radix UI, shadcn/ui +- **Backend**: Express 4, Prisma ORM, Redis (ioredis), Winston logging +- **Testing**: Vitest (middleware + runtime), Supertest for API tests +- **Build**: Rollup (app + middleware), Vite (React dev server) +- **Linting**: ESLint 9 flat config (app), ESLint 8 legacy (middleware/runtime), Prettier + +## Code Standards (Strictly Enforced) + +1. **No `any` type** — define proper types always +2. **No non-null assertions (`!`)** — handle nullability explicitly +3. **No `as unknown as T` casts** — find type-safe alternatives +4. **Single quotes** for strings; template literals over concatenation +5. **Full code only** — no placeholders or stubs +6. **Types**: prefix `T` for types (`TChatMessage`), `I` for interfaces (`IChatState`), `_` for unused params +7. **Named exports** over default exports + +## Code Review Checklist + +1. **Type safety** — no `any`, no `!`, no unsafe casts +2. **No duplication** — reuse existing components, utils, patterns +3. **Error handling** — proper types, no swallowed errors, no silent catches +4. **Import hygiene** — use path aliases (`@react/*`, `@shared/*`), no circular deps +5. **Naming** — consistent with codebase conventions (see file names in context) +6. **Comments** — inline for non-obvious logic; JSDoc for exported APIs + +## Testing Conventions + +- Test files live alongside source: `*.test.ts` or `*.spec.ts` +- Use Vitest (`describe`, `it`, `expect`) — not Jest +- API tests use Supertest with `node-mocks-http` +- Mock external services; never hit real APIs in tests + +## Security Context + +- Secrets must use env vars — never hardcoded in source +- Never commit `.env` files or `.env.*` variants +- No API keys, tokens, or passwords in code or logs +- Sanitize user input (DOMPurify is available for HTML) +- Use `express-rate-limit` on public-facing endpoints + +## Pull Requests + +- When creating a GitHub PR, always use the template from `.github/pull_request_template.md` and fill in all sections. +- Ask the user for an optional ClickUp ticket link before creating the PR. + +## Do NOT + +- Introduce new dependencies without justification +- Bypass pre-commit hooks (`--no-verify`) +- Skip error handling for external calls +- Use the deprecated `@src/*` alias in new code +- Commit generated files (`dist/`, `prisma/generated/`)