From 9d1ad51900e5dfba6bc175fcefe71c3b8658e17b Mon Sep 17 00:00:00 2001 From: Forhad Hosain Date: Wed, 4 Mar 2026 16:32:10 +0600 Subject: [PATCH 1/3] add CLAUDE.md; /review-dev and /security-review-dev commands --- .claude/commands/review-dev.md | 62 ++++++++++++++++++ .claude/commands/security-review-dev.md | 70 ++++++++++++++++++++ CLAUDE.md | 87 +++++++++++++++++++++++++ 3 files changed, 219 insertions(+) create mode 100644 .claude/commands/review-dev.md create mode 100644 .claude/commands/security-review-dev.md create mode 100644 CLAUDE.md diff --git a/.claude/commands/review-dev.md b/.claude/commands/review-dev.md new file mode 100644 index 000000000..c457e476d --- /dev/null +++ b/.claude/commands/review-dev.md @@ -0,0 +1,62 @@ +Review code changes on the current branch against origin/main. + +## Setup + +1. Run: `git diff $(git merge-base HEAD origin/main) 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: +- **File:line** — exact location +- **Severity** — Critical / Warning / Nit +- **Rule** — which rule or checklist item was violated +- **Issue** — what's wrong +- **Fix** — how to remediate + +## Summary + +End with: +1. Total issues by severity (Critical / Warning / Nit) +2. Overall verdict: **Approve** or **Request Changes** +3. If Request Changes, list the blocking issues that must be fixed diff --git a/.claude/commands/security-review-dev.md b/.claude/commands/security-review-dev.md new file mode 100644 index 000000000..b452bea25 --- /dev/null +++ b/.claude/commands/security-review-dev.md @@ -0,0 +1,70 @@ +Run a security-focused review of changes on the current branch against origin/main. + +## Setup + +1. Run: `git diff $(git merge-base HEAD origin/main) 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..55e3bde7c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,87 @@ +# 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 + +## 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/`) From bc80c9211ce175a29fb9af49db0cbee169cdf9a1 Mon Sep 17 00:00:00 2001 From: Forhad Hosain Date: Wed, 4 Mar 2026 22:04:06 +0600 Subject: [PATCH 2/3] migrate review-dev and security-review-dev command to skill --- .../review-dev/SKILL.md} | 26 +++++++++++++------ .../security-review-dev/SKILL.md} | 16 ++++++++++-- 2 files changed, 32 insertions(+), 10 deletions(-) rename .claude/{commands/review-dev.md => skills/review-dev/SKILL.md} (69%) rename .claude/{commands/security-review-dev.md => skills/security-review-dev/SKILL.md} (81%) diff --git a/.claude/commands/review-dev.md b/.claude/skills/review-dev/SKILL.md similarity index 69% rename from .claude/commands/review-dev.md rename to .claude/skills/review-dev/SKILL.md index c457e476d..b190cb883 100644 --- a/.claude/commands/review-dev.md +++ b/.claude/skills/review-dev/SKILL.md @@ -1,8 +1,18 @@ -Review code changes on the current branch against origin/main. +--- +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 diff $(git merge-base HEAD origin/main) HEAD` +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 @@ -48,15 +58,15 @@ Check every changed file against these categories: ## Output Format For each issue found, report: -- **File:line** — exact location -- **Severity** — Critical / Warning / Nit -- **Rule** — which rule or checklist item was violated -- **Issue** — what's wrong -- **Fix** — how to remediate +- **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 (Critical / Warning / Nit) +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/commands/security-review-dev.md b/.claude/skills/security-review-dev/SKILL.md similarity index 81% rename from .claude/commands/security-review-dev.md rename to .claude/skills/security-review-dev/SKILL.md index b452bea25..25728f49b 100644 --- a/.claude/commands/security-review-dev.md +++ b/.claude/skills/security-review-dev/SKILL.md @@ -1,8 +1,20 @@ -Run a security-focused review of changes on the current branch against origin/main. +--- +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 diff $(git merge-base HEAD origin/main) HEAD` +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 From b9586b978bb6386b05e4f68e23bc652cb79cdcff Mon Sep 17 00:00:00 2001 From: Forhad Hosain Date: Fri, 3 Apr 2026 11:20:44 +0600 Subject: [PATCH 3/3] add PR instruction to CLAUDE.md --- CLAUDE.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 55e3bde7c..fc76bce0e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -78,6 +78,11 @@ pnpm --filter middleware prisma:migrate # Run DB migrations - 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