feat: Deep Reverse mode — detailed prompts via DeepWiki analysis

[beekamai]

What Changed

Added Deep Reverse — an optional mode that generates detailed, comprehensive prompts (2000–4000 words) by combining DeepWiki documentation analysis with LLM synthesis.

New files

• lib/deepwiki-client.ts — DeepWiki MCP client (wiki structure, full wiki fetch, section extraction, error detection)
• lib/fingerprint.ts — Client-side browser fingerprint (SHA-256 from stable signals)
• lib/fingerprint-server.ts — Server-side combined fingerprint (IP + UA + client hash)
• lib/deep-reverse-prompts.ts — System prompts for analysis and synthesis phases
• lib/llm-client.ts — Shared LLM client extracted from reverse-prompt/route.ts (eliminates duplication)
• app/api/deep-reverse/route.ts — GET eligibility + POST SSE streaming pipeline
• .env.example — Documents all environment variables (was referenced in README but missing)

Modified files

• app/api/reverse-prompt/route.ts — Refactored to use shared lib/llm-client.ts
• app/api/library/route.ts — Deep prompts shown in priority over standard ones
• components/reverse-prompt-home.tsx — Deep Reverse toggle, SSE progress reader, DeepWiki link
• README.md — Deep Reverse documentation and env var reference
• .gitignore — Added !.env.example exception

How it works

1. Wiki structure — Fetches repository documentation structure from DeepWiki MCP API (read_wiki_structure)
2. Analysis — LLM selects 1–5 key documentation topics to examine
3. Full wiki fetch — Fetches complete wiki documentation (read_wiki_contents) and extracts the selected sections by page title matching
4. Synthesis — LLM generates one detailed, actionable prompt from the extracted sections

Progress is streamed to the client via SSE events (progress → complete/error).

If a repository is not indexed by DeepWiki, the request is declined and the usage attempt is refunded. A DeepWiki link is shown next to the toggle so users can index the repo themselves before retrying.

Rate limiting & rollout

• Combined fingerprint: server-side SHA-256(IP + User-Agent + Accept-Language + client_hash) — resistant to both incognito and VPN bypass. X-Fingerprint header is required.
• Configurable uses per week per fingerprint (default 3)
• Gradual rollout: DEEP_REVERSE_ROLLOUT_PERCENT env var (0–100, default 50) — deterministic per fingerprint, no reshuffling when expanding

Setup required

1. Environment variables (optional)

DEEP_REVERSE_ROLLOUT_PERCENT=50          # 0-100, percentage of users who see the toggle
DEEP_REVERSE_MAX_USES_PER_WEEK=3         # uses per fingerprint per week
DEEP_CACHE_TTL_HOURS=168                 # cache lifetime, default 7 days
DEEPWIKI_MCP_URL=https://mcp.deepwiki.com/mcp  # default DeepWiki endpoint

2. Supabase tables (required for Deep Reverse)

Run the following SQL in your Supabase SQL Editor:

CREATE TABLE IF NOT EXISTS deep_prompt_cache (
  id serial PRIMARY KEY,
  owner text NOT NULL,
  repo text NOT NULL,
  prompt text NOT NULL,
  cached_at timestamptz DEFAULT now(),
  views integer DEFAULT 0,
  UNIQUE(owner, repo)
);

CREATE TABLE IF NOT EXISTS deep_reverse_usage (
  id serial PRIMARY KEY,
  fingerprint text NOT NULL,
  ip text,
  owner text,
  repo text,
  used_at timestamptz DEFAULT now()
);

CREATE INDEX IF NOT EXISTS idx_deep_usage_fp_date
  ON deep_reverse_usage(fingerprint, used_at);

Deep Reverse gracefully degrades — if Supabase is not configured, the toggle simply won't appear and standard reverse works as before.

Design note

DeepWiki's MCP ask_question endpoint is currently returning "Repository not found" for all public repositories (confirmed across facebook/react, vercel/next.js, torvalds/linux and others). This appears to be a DeepWiki-side outage. The implementation uses read_wiki_contents instead, which reliably returns full documentation for indexed repos. Section extraction is done server-side by parsing page titles — no extra API calls needed. If/when ask_question is restored, it could be added as an alternative path without code changes to the current flow.

Why This Change

The current reverse prompt is ~150 words based only on README + root file tree. For complex projects, this is too shallow to faithfully recreate the codebase. Deep Reverse leverages DeepWiki's repository analysis to produce prompts that cover architecture, data models, API design, and implementation details.

Testing Done

• Standard reverse still works unchanged
• Deep Reverse SSE streaming with progress indicators
• Non-indexed repos correctly detected and rejected (usage refunded)
• DeepWiki link shown next to toggle for easy indexing
• Section extraction from full wiki by page title matching
• Fallback to full wiki (truncated) when no sections match
• Rate limiting per fingerprint
• Gradual rollout toggle (tested at 50% and 100%)
• Library shows deep prompts in priority when available
• TypeScript strict mode — no errors
• ESLint — no errors on all changed files

Type of Change

• feat: New feature
• refactor: Code refactoring (shared LLM client)

Security & Quality Checklist

• No secrets or API keys committed
• Follows the project's coding standards
• No sensitive data exposed in logs or output
• Fingerprint never logged or stored raw — only SHA-256 hash

[vercel]

@beekamai is attempting to deploy a commit to the filiksyos' projects Team on Vercel.

A member of the Team first needs to authorize it.