Skip to content

CLAUDE.md

Latest commit

 

History

History
89 lines (70 loc) · 2.9 KB

CLAUDE.md

File metadata and controls

89 lines (70 loc) · 2.9 KB

CLAUDE.md

Overview

f2u (file-to-url) — temporary file hosting CLI for AI agents. Monorepo with Cloudflare Worker + CLI tool.

Structure

packages/
  worker/     # Cloudflare Worker (Hono) — R2 storage + D1 metadata + cron cleanup
  cli/        # CLI tool (Commander.js) — JSON-only output for AI agents

Development

pnpm install          # Install all deps
pnpm dev:worker       # Local Worker (wrangler dev)
pnpm dev:cli          # Run CLI via tsx
pnpm build            # Build all packages
pnpm build:cli        # Build CLI only
pnpm build:worker     # Build Worker only (dry-run deploy)
pnpm deploy           # Deploy Worker to Cloudflare

Key Patterns

  • Worker routing: Hono with explicit route ordering — specific paths before wildcards
  • Auth: Bearer token middleware on protected routes; GET /:id/:filename is public
  • CLI output: All stdout is JSON. Errors to stderr as JSON + non-zero exit code
  • Config: ~/.config/f2u/config.json with 0600 permissions; env var override (F2U_ENDPOINT, F2U_API_KEY)
  • Cron: Every 1 minute, cleanup expired files (batch 50, mark deleted in D1, remove from R2)

Worker Routes

Method Path Auth Handler
POST /upload Bearer routes/upload-route.ts
GET /:id/:filename No routes/serve-route.ts
GET /files Bearer routes/files-route.ts
GET /info/:id Bearer routes/files-route.ts
DELETE /:id Bearer index.ts (inline)
GET /usage Bearer routes/usage-route.ts
GET /health No index.ts
GET /login, /dashboard, / Cookie routes/web-route.ts
GET /auth/github, /auth/github/callback No routes/oauth-route.ts
POST /auth/logout Cookie routes/oauth-route.ts
GET /api/me Cookie routes/dashboard-api-route.ts
GET/POST/DELETE /api/keys[/:id] Cookie routes/dashboard-api-route.ts

Auth modes:

  • Bearer: API key (legacy API_KEY env OR sha-256 hashed key in D1 api_keys)
  • Cookie: HttpOnly f2u_session cookie set after GitHub OAuth login
  • No: Public

CLI Commands

Command File
f2u auth commands/auth-command.ts
f2u up commands/upload-command.ts
f2u ls commands/list-command.ts
f2u rm commands/delete-command.ts
f2u info commands/info-command.ts
f2u usage commands/usage-command.ts

Testing

# Type check
cd packages/worker && npx tsc --noEmit
cd packages/cli && npx tsc --noEmit

# Test CLI locally
cd packages/cli && npx tsx src/index.ts --help
cd packages/cli && npx tsx src/index.ts up -f ./test.png -t 5m

# Test Worker locally
cd packages/worker && wrangler dev
curl http://localhost:8787/health
curl -X POST http://localhost:8787/upload -H "Authorization: Bearer test" -F "file=@test.png"

Deployment

  1. Fill database_id in packages/worker/wrangler.toml
  2. wrangler secret put API_KEY
  3. pnpm deploy