devlyn-cli 0.5.1 → 0.5.3

package/optional-skills/better-auth-setup/references/proxy-setup.md

@@ -0,0 +1,284 @@
+# Reverse Proxy Architecture — Complete Setup Guide
+
+When the frontend (e.g., Next.js on Cloudflare Workers) is a separate application that proxies auth requests to the backend (e.g., Hono on Fly.io), several non-obvious configurations are required for OAuth, cookies, and redirects to work correctly.
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Proxy Route Configuration](#proxy-route-configuration)
+3. [Forwarding Headers](#forwarding-headers)
+4. [Location Header Rewriting](#location-header-rewriting)
+5. [Dynamic baseURL with allowedHosts](#dynamic-baseurl-with-allowedhosts)
+6. [Frontend Middleware Cookie Detection](#frontend-middleware-cookie-detection)
+7. [OAuth Provider Configuration](#oauth-provider-configuration)
+8. [CSP Configuration](#csp-configuration)
+9. [Edge Runtime (Cloudflare Workers)](#edge-runtime-cloudflare-workers)
+
+---
+
+## Architecture Overview
+
+```
+Browser (your-frontend.com)
+  |
+  |-- POST /api/auth/sign-in/social  -->  Proxy  -->  Backend /auth/sign-in/social
+  |                                                     |
+  |                                                     v
+  |                                              Sets state cookie
+  |                                              Returns redirect to Google
+  |
+  |-- Browser redirects to Google OAuth
+  |
+  |-- Google redirects to callback URL
+  |       (MUST go through proxy, not directly to backend)
+  |
+  |-- GET /auth/callback/google  -->  Proxy  -->  Backend /auth/callback/google
+  |                                                     |
+  |                                                     v
+  |                                              Reads state cookie (same domain!)
+  |                                              Creates session
+  |                                              Sets session cookie
+  |                                              Redirects to /dashboard
+```
+
+The critical insight: **OAuth callbacks MUST go through the same proxy as the initial request**, so cookies (state and session) are on the same domain.
+
+---
+
+## Proxy Route Configuration
+
+Two proxy routes are needed — one for API calls, one for OAuth callbacks:
+
+| Frontend Route | Backend Route | Purpose |
+|---|---|---|
+| `/api/auth/*` | `/auth/*` | Auth-client API calls (browser SDK) |
+| `/auth/*` | `/auth/*` | OAuth callbacks (provider redirects here) |
+
+The auth-client (browser) sends requests to `/api/auth/*`. OAuth callbacks arrive at `/auth/*` because Better Auth constructs callback URLs from `{baseURL}{basePath}/callback/{provider}`, and the derived baseURL from `allowedHosts` is the frontend origin.
+
+### Next.js API Route Example
+
+```typescript
+// src/app/api/auth/[...path]/route.ts
+import { NextRequest, NextResponse } from "next/server";
+
+const API_URL = process.env.API_URL; // e.g., "https://backend.fly.dev"
+
+async function proxyRequest(request: NextRequest) {
+  const url = new URL(request.url);
+  const authPath = url.pathname.replace("/api/auth", "/auth");
+  const targetUrl = `${API_URL}${authPath}${url.search}`;
+
+  const headers = new Headers(request.headers);
+
+  // Strip then set forwarding headers (see next section)
+  headers.delete("x-forwarded-for");
+  headers.delete("x-forwarded-host");
+  headers.delete("x-forwarded-proto");
+  headers.delete("x-real-ip");
+  headers.delete("cf-connecting-ip");
+  headers.set("x-forwarded-host", url.host);
+  headers.set("x-forwarded-proto", url.protocol.replace(":", ""));
+
+  const response = await fetch(targetUrl, {
+    method: request.method,
+    headers,
+    body: request.method !== "GET" && request.method !== "HEAD"
+      ? await request.text()
+      : undefined,
+    redirect: "manual",
+  });
+
+  const responseHeaders = new Headers(response.headers);
+
+  // Rewrite Location headers (see section below)
+  const location = responseHeaders.get("location");
+  if (location && API_URL && location.startsWith(API_URL)) {
+    const frontendOrigin = url.origin;
+    responseHeaders.set("location", location.replace(API_URL, frontendOrigin));
+  }
+
+  return new NextResponse(response.body, {
+    status: response.status,
+    headers: responseHeaders,
+  });
+}
+
+export const GET = proxyRequest;
+export const POST = proxyRequest;
+```
+
+```typescript
+// src/app/auth/[...path]/route.ts
+// Same handler — reuse for OAuth callbacks
+export { GET, POST } from "../api/auth/[...path]/route";
+```
+
+---
+
+## Forwarding Headers
+
+The proxy MUST set `X-Forwarded-Host` and `X-Forwarded-Proto` so Better Auth knows the real origin. This is how Better Auth constructs the correct OAuth callback URL.
+
+```typescript
+// Strip user-provided headers to prevent spoofing
+headers.delete("x-forwarded-for");
+headers.delete("x-forwarded-host");
+headers.delete("x-forwarded-proto");
+headers.delete("x-real-ip");
+headers.delete("cf-connecting-ip");
+
+// Then set correct values from the actual request
+headers.set("x-forwarded-host", url.host);
+headers.set("x-forwarded-proto", url.protocol.replace(":", ""));
+```
+
+**Why both strip AND set?** Stripping prevents clients from spoofing these headers. Setting them tells the backend the true origin of the request. The proxy is the trusted boundary — it's the only thing that knows the real origin.
+
+---
+
+## Location Header Rewriting
+
+When the backend returns a redirect (302), the `Location` header points to the backend's origin. The proxy must rewrite it to the frontend:
+
+```typescript
+const location = responseHeaders.get("location");
+if (location && API_URL && location.startsWith(API_URL)) {
+  const frontendOrigin = new URL(request.url).origin;
+  responseHeaders.set("location", location.replace(API_URL, frontendOrigin));
+}
+```
+
+Without this, redirects after OAuth callback would send the user to the backend domain instead of the frontend.
+
+---
+
+## Dynamic baseURL with allowedHosts
+
+**DO NOT** use a static `baseURL` string in the backend's Better Auth config. It breaks the proxy architecture because:
+
+- A static baseURL caches on first request (often a health check with `Host: backend.internal`), permanently setting the wrong origin
+- `trustedProxyHeaders: true` alone does NOT work when `baseURL` is set — the static value takes precedence
+- The `BETTER_AUTH_URL` env var also overrides forwarded headers (it's checked before headers in the priority chain)
+
+**The correct approach** — use `allowedHosts` with a `fallback`:
+
+```typescript
+export const auth = betterAuth({
+  baseURL: {
+    allowedHosts: [
+      "your-frontend.com",      // Frontend domain (via proxy)
+      "your-backend.fly.dev",   // Backend domain (direct access)
+      "localhost",              // Local development
+      "*.fly.dev",              // Platform internal routing
+    ],
+    fallback: process.env.BETTER_AUTH_URL, // For health checks / unmatched hosts
+  },
+  basePath: "/auth",
+
+  advanced: {
+    // Required for allowedHosts to read X-Forwarded-Host from the proxy
+    trustedProxyHeaders: true,
+  },
+  // ...
+});
+```
+
+**How allowedHosts works internally:**
+1. Reads `X-Forwarded-Host` header (set by proxy), falls back to `Host` header
+2. Validates against the allowedHosts list (supports wildcards like `*.fly.dev`)
+3. Constructs baseURL per-request (not cached!)
+4. If no match, uses `fallback`
+5. OAuth callback URL = `{derived-baseURL}{basePath}/callback/{provider}`
+
+**The `getBaseURL()` priority chain** (why `trustedProxyHeaders` alone isn't enough):
+1. Static `baseURL` string (if set) — **always wins**
+2. `BETTER_AUTH_URL` environment variable — **checked before headers**
+3. `X-Forwarded-Host` / `X-Forwarded-Proto` headers — only reached if 1 and 2 are absent
+4. Request URL — last resort
+
+`allowedHosts` bypasses this entire priority chain by explicitly reading the forwarded headers and constructing the URL per-request.
+
+---
+
+## Frontend Middleware Cookie Detection
+
+In production with HTTPS, Better Auth adds a `__Secure-` prefix to cookie names. Your frontend middleware MUST check for both:
+
+```typescript
+const SESSION_COOKIES = [
+  "__Secure-better-auth.session_token",  // Production (HTTPS)
+  "better-auth.session_token",            // Development (HTTP)
+];
+
+const hasSession = SESSION_COOKIES.some(
+  (name) => !!request.cookies.get(name)?.value,
+);
+```
+
+**Why this happens:** When `baseURL` is a dynamic config object (allowedHosts), Better Auth can't determine the protocol at initialization time. In production (`NODE_ENV=production`), it defaults to secure cookies with the `__Secure-` prefix. If your middleware only checks for `better-auth.session_token`, it will never find the cookie and will redirect authenticated users to sign-in.
+
+This is the most insidious gotcha in the proxy architecture — OAuth completes successfully, session is created, cookie is set, but the frontend doesn't recognize it.
+
+---
+
+## OAuth Provider Configuration
+
+### Google Console Settings
+
+- **Authorized JavaScript origins**: `https://your-frontend.com`
+- **Authorized redirect URIs**: `https://your-frontend.com/auth/callback/google`
+
+The redirect URI uses `/auth/callback/google` (NOT `/api/auth/callback/google`) because Better Auth constructs it from `{baseURL}{basePath}/callback/google`, and the derived baseURL from `allowedHosts` is the frontend origin.
+
+### Google Console Propagation
+
+Changes take up to 5 minutes to propagate. If you get `redirect_uri_mismatch` immediately after updating, wait and retry before changing configuration.
+
+### Backend Social Provider Config
+
+```typescript
+socialProviders: {
+  google: {
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+  },
+  // Add more as needed:
+  // github: { clientId: ..., clientSecret: ... },
+},
+```
+
+---
+
+## CSP Configuration
+
+If using Content Security Policy headers on the frontend, add required domains:
+
+```typescript
+const cspDirectives = [
+  "default-src 'self'",
+  `script-src 'self' 'unsafe-inline' https://static.cloudflareinsights.com`,
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: https://lh3.googleusercontent.com", // Google avatars
+  "connect-src 'self'",
+  "font-src 'self'",
+  "frame-ancestors 'none'",
+];
+```
+
+---
+
+## Edge Runtime (Cloudflare Workers)
+
+If deploying the frontend to Cloudflare Workers, the middleware must use the correct runtime:
+
+```typescript
+// Next.js 16
+export const runtime = "experimental-edge";
+// NOT "edge" — Next.js 16 requires "experimental-edge"
+```
+
+For earlier Next.js versions:
+```typescript
+export const runtime = "edge";
+```

package/optional-skills/dokkit/ANALYSIS.md

@@ -0,0 +1,198 @@
+# Analysis Knowledge
+
+Template analysis patterns and field detection strategies for the dokkit-analyzer agent. Covers field identification, confidence scoring, and the analysis output schema.
+
+## Table of Contents
+
+- [Field Detection Strategy](#field-detection-strategy)
+- [Section Detection](#section-detection)
+- [Cross-Language Mapping](#cross-language-mapping)
+- [Confidence Scoring](#confidence-scoring)
+- [Analysis Output Format](#analysis-output-format)
+
+---
+
+## Field Detection Strategy
+
+Detect ALL fillable locations in a template. Fields appear in these patterns:
+
+### 1. Placeholder Text
+- `{{field_name}}` or `<<field_name>>` — explicit placeholders
+- `[field_name]` or `(field_name)` — bracket patterns
+- `___` (underscores) — blank line indicators
+- `...` (dots) — fill-in indicators
+
+### 2. Empty Table Cells
+In form-like documents (especially Korean templates):
+- A label cell (e.g., "Name") with an adjacent empty cell = fill target
+- Pattern: `[Label Cell] [Empty Cell]`
+
+### 3. Instruction Text
+Text telling the user what to enter:
+- "(enter name here)", "(type your answer)"
+- Korean: "(날짜를 입력하세요)", "(내용을 기재)"
+- These should be REPLACED with the actual value
+
+### 4. Form Controls (DOCX only)
+- Content controls (`w:sdt`) with explicit placeholder values
+- Legacy form fields (`w:fldChar`)
+
+### 5. Underline Runs
+Runs styled with underline containing only spaces or underscores:
+- Indicates a blank line for handwriting
+- In digital filling, replace with the value
+
+### 6. Image Fields
+Fields requiring an image rather than text:
+- `{{사진}}`, `{{photo}}`, `<<signature>>` — image placeholder text
+- Existing `<w:drawing>` (DOCX) or `<hp:pic>` (HWPX) in table cells
+- Empty cells adjacent to cells with image keywords
+
+**Image keywords** (Korean): 사진, 증명사진, 여권사진, 로고, 서명, 날인, 도장, 직인
+**Image keywords** (English): Photo, Picture, Logo, Signature, Stamp, Seal, Image, Portrait
+
+**Classification** (`image_type`): `photo`, `logo`, `signature`, or `figure`
+
+### 7. Writing Tip Boxes (작성 팁)
+Standalone 1x1 tables with DASH borders containing guidance text:
+- HWPX: `rowCnt="1"`, `colCnt="1"` with `※` text
+- DOCX: Single `<w:tr>/<w:tc>` with dashed borders
+- Often styled in red (#FF0000)
+
+Detect as `field_type: "tip_box"` with `action: "delete"`.
+
+**Container types**:
+- `"standalone"` — top-level 1x1 table between other content
+- `"nested"` — inside `<hp:subList>` within a fill-target cell; include `parent_field_id`
+
+**`has_formatting` flag**: For mapped fields where `mapped_value` is >100 chars and contains markdown syntax (`**bold**`, `## heading`, `- bullet`, `1. numbered`), set `has_formatting: true`.
+
+## Section Detection
+
+Group fields into logical sections:
+1. Use document headings (H1, H2) as section boundaries
+2. In table-based forms, use spanning header rows
+3. In Korean templates, look for: "인적사항", "학력", "경력", "자격증"
+4. If no clear sections, use "General" as default
+
+## Cross-Language Mapping
+
+Common Korean-English field equivalents:
+
+| Korean | English |
+|--------|---------|
+| 성명 / 이름 | Name / Full Name |
+| 생년월일 | Date of Birth |
+| 주소 | Address |
+| 전화번호 / 연락처 | Phone / Contact |
+| 이메일 | Email |
+| 학력 | Education |
+| 경력 | Work Experience |
+| 자격증 | Certifications |
+| 직위 / 직책 | Position / Title |
+| 회사명 | Company Name |
+| 기간 | Period / Duration |
+
+## Confidence Scoring
+
+### High Confidence
+- Exact label match between source and template field
+- Unambiguous data (one clear value in sources)
+- Same language label match
+
+### Medium Confidence
+- Semantic match (different wording, same meaning)
+- Cross-language match (Korean-English)
+- Multiple candidate values in sources
+- Partial data match
+
+### Low Confidence
+- Indirect inference (value derived from context)
+- Ambiguous mapping (could match multiple fields)
+- Best guess from limited data
+
+## Analysis Output Format
+
+Write to `.dokkit/analysis.json`:
+
+```json
+{
+  "template": {
+    "file_path": "...",
+    "file_type": "docx|hwpx",
+    "display_name": "..."
+  },
+  "sections": [
+    {
+      "name": "Section Name",
+      "fields": [
+        {
+          "id": "field_001",
+          "label": "Field Label",
+          "field_type": "placeholder_text|empty_cell|underline|form_control|instruction_text|image|tip_box|section_content|table_content",
+          "xml_path": {
+            "file": "word/document.xml",
+            "element_path": "body/tbl[0]/tr[1]/tc[2]/p[0]/r[0]",
+            "namespaced_path": "w:body/w:tbl[0]/w:tr[1]/w:tc[2]/w:p[0]/w:r[0]"
+          },
+          "pattern": "{{name}}",
+          "current_content": "{{name}}",
+          "mapped_value": "John Doe",
+          "source": "resume.pdf",
+          "source_location": "key_value_pairs.Name",
+          "confidence": "high",
+          "has_formatting": false
+        },
+        {
+          "id": "field_015",
+          "label": "tip box label",
+          "field_type": "tip_box",
+          "action": "delete",
+          "container": "standalone",
+          "xml_path": { "file": "...", "element_path": "...", "namespaced_path": "..." },
+          "pattern": "(tip box: 1x1 table)",
+          "current_content": "※ 작성 팁: ...",
+          "mapped_value": null,
+          "confidence": "high"
+        },
+        {
+          "id": "field_020",
+          "label": "사진",
+          "field_type": "image",
+          "image_type": "photo",
+          "xml_path": { "file": "...", "element_path": "...", "namespaced_path": "..." },
+          "pattern": "(empty cell, image label)",
+          "current_content": "",
+          "image_source": "ingested",
+          "image_file": ".dokkit/sources/photo.jpg",
+          "dimensions": { "width_emu": 1260000, "height_emu": 1620000 },
+          "confidence": "high"
+        }
+      ]
+    }
+  ],
+  "summary": {
+    "total_fields": 22,
+    "mapped": 18,
+    "unmapped": 4,
+    "high_confidence": 15,
+    "medium_confidence": 2,
+    "low_confidence": 1,
+    "image_fields": 2,
+    "image_fields_sourced": 1,
+    "image_fields_pending": 1,
+    "tip_boxes": 3
+  }
+}
+```
+
+### Critical Rules for Analysis Output
+
+- For `table_content` fields that are pre-filled from source: set `mapped_value: null` with `action: "preserve"`. NEVER set `mapped_value` to a placeholder string — the filler treats any non-null `mapped_value` as literal data and will destroy the table.
+- For `image` fields: search `.dokkit/sources/` for matching images first. Set `image_source: "ingested"` if found, or leave `image_file: null` (pending).
+- For `section_content` fields: scan for visual enhancement opportunities (max 3 per field, max 12 total). Record with `generation_prompt`, `dimensions`, `status: "pending"`.
+
+## References
+
+See `references/field-detection-patterns.md` for advanced detection heuristics (9 DOCX + 6 HWPX).
+See `references/image-opportunity-heuristics.md` for AI image opportunity detection in section content.