scopegate: Instructions file for Claude Code

CLAUDE.md

@.darkflow.d/claude.md

Commands

pnpm dev            # dev server → localhost:3000
pnpm build          # prisma generate + migrate deploy + next build (requires live DB)
pnpm test           # vitest run
pnpm lint           # eslint
bash ~/.darkflow/darkflow-run.sh        # Dark Flow routine dispatcher (global worker)

Commits & CI

Do NOT run pnpm build before or after commits. The Dark Flow CI gate (.github/workflows/darkflow-ci-gate.yml) runs install → build (prisma generate && tsc --noEmit) → lint → test on every push/PR on the project's self-hosted runner; it does not file anything itself. The ci-watch routine reads that workflow's conclusion and files a source:ci task on failure. This overrides the global "always run pnpm build before committing" rule because pnpm build runs migrations and requires a live DB. Failing checks → source:ci task → the fix-ci-issue worker pushes a fix (retries up to 3x, then needs-human); the task closes on green. Running pnpm lint/pnpm test locally for fast feedback is fine but not required. See docs/ci-runner.md for the full split between the workflow and ci-watch.

Architecture

Next.js 16 App Router · Prisma 7 + PostgreSQL · Auth: better-auth · MCP server: MCP SDK Streamable HTTP at /api/mcp/[apiKey] · OTel → SigNoz.

src/
  app/
    (auth)/           # login / register
    (dashboard)/      # admin / projects / settings / notifications
    api/
      mcp/[apiKey]/   # MCP HTTP endpoint (SSE keep-alive pings every 30s)
      cron/           # refresh-tokens (CRON_SECRET-guarded)
      oauth/          # OAuth callback handlers
      admin/          # invites / projects / users management
      notifications/  # notification API
      csp-report/     # CSP violation sink → SigNoz OTel span + structured log
      projects/[projectId]/  # per-project API
  lib/
    mcp/
      tools/          # per-service tool files (gmail, linkedin, stripe, airtable, calendar, calendly, openrouter, telegram, twitter-ads, …)
        index.ts      # TOOL_DEFINITIONS — aggregates all service tools
        types.ts      # ToolDefinition · ToolContext
      permissions.ts  # per-action permission definitions; PERMISSION_GROUPS derived from PROVIDER_REGISTRY
      handler.ts      # tool execution + audit logging; 30s per-tool timeout; OAuthTokenError detection
      metrics.ts      # lazy-init OTel counters (mcp.invalid_requests, mcp.blocked_requests)
      service-fetch.ts # unified transport — TRANSPORT_CONFIGS derived from PROVIDER_REGISTRY + SSRF-safe fetch
      safe-fetch.ts   # SSRF/DNS-rebinding-safe fetch (node:https); validates all A/AAAA records
      retry.ts        # retryWithDelays(), isRetriableNetworkError(), retryAfterDelayMs(), sleep()
      rate-limit.ts   # checkRateLimit() — atomic upsert into RateLimitBucket; injectable DB for tests
      image-utils.ts  # image/video download helpers (uses media-body.ts for streaming size limits)
      media-body.ts   # readBodyWithLimit(res, maxBytes, label) — streaming download with size cap
      email-parser.ts # email parsing utilities
      gmail.ts        # gmailFetch(), listGmailMessages(), getGmailMessage(), attachment helpers
      <service>.ts    # service-specific helpers (ahrefs, semrush, email, youtube, …)
      tools/
        fetch-tool.ts # createFetchTool() / createFetchTools() — declarative tool factory for REST endpoints
    auth.ts
    auth-middleware.ts   # AuthError / ForbiddenError / NotFoundError; requireAuth/requireProject helpers
    project-auth.ts      # project-level auth guards (verifies team membership)
    project-roles.ts     # PROJECT_ROLE constants; isProjectOwner()
    admin.ts             # isAdmin() helper (checks ADMIN_EMAIL env var)
    audit.ts             # recordAudit() — thin wrapper around mcp/audit-utils
    crypto.ts         # AES-256-GCM encrypt/decrypt (uses BETTER_AUTH_SECRET)
    oauth-flow.ts     # shared handleOAuthStart/handleOAuthCallback base logic
    oauth-state.ts    # HMAC-signed OAuth state (uses BETTER_AUTH_SECRET)
    oauth-callback-config.ts  # OAUTH_CALLBACK_REGISTRY — per-provider config factory (lazy-import)
    oauth-callback-route.ts   # createOAuthCallbackRoute(routeKey) — collapses OAuth callback boilerplate
    oauth-token-lifecycle.ts  # unified token refresh for all 26 providers; OAuthTokenError class; derives config from provider-registry
    token-refresh.ts  # cron token refresh service — PERMANENT_OAUTH_ERRORS, RefreshResult, refreshConnections(); injectable DB/clock for tests
    endpoint-permissions.ts   # createProjectEndpoint(), applyEndpointPermissions(), deleteEndpoint(), regenerateEndpointKey(), EndpointPermissionError
    cron-auth.ts              # checkCronAuth(request, secret?) — Bearer-token check for /api/cron/* routes; returns {ok:true} | {ok:false, status:401|500, error}
    provider-registry.ts      # PROVIDER_REGISTRY — single source of truth for all 26 providers (token strategy, transport, retry, permissions); add/remove a provider here only
    db.ts             # Prisma client
    provider-names.ts # OAuth provider display name map
  instrumentation.ts        # OTel hook (browser-safe entry point)
  instrumentation.node.ts   # OTel SDK init + PrismaInstrumentation (Node.js only)
prisma/
  schema.prisma       # User · Session · Account · Project · TeamMember ·
                      # ServiceConnection · McpEndpoint · EndpointPermission ·
                      # AuditLog · RateLimitBucket · Notification · InviteToken
docker/
  prisma.config.ts    # runtime Prisma config for migrate deploy (supplies DATABASE_URL; no dotenv)