Forage

Forage is a privacy-first GitHub repository rediscovery tool. Users authorize GitHub, import starred repositories into browser-local IndexedDB, run local analysis, review scores/categories, and export results without storing repository data server-side.

The current repo contains the real Astro/Svelte web app, Cloudflare Worker auth/import API, shared packages, infrastructure configuration, hosted smoke checks, and the retained pre-MVP spike.

Documentation Map

Start with docs/README.md for the full link tree and current hosted environment map.

High-signal docs:

• Architecture
• Auth And Privacy
• Storage Schema
• Import Pipeline
• Hosting UI Setup
• Cloudflare Token Permissions

Current App

The real app is split into:

• apps/web: Astro browser app with Svelte islands, IndexedDB storage, local analysis, dashboard, and exports.
• apps/worker: Cloudflare Worker for GitHub auth, session/settings, and GitHub API proxying.
• packages/*: shared contracts, core import state, GitHub normalization, analysis/scoring, and reporting.

Repository data imported through the real app is stored in browser IndexedDB, not in the Worker.

Pre-MVP Spike

The minimal pre-MVP spike remains as a reference for the first proven vertical slice:

• GitHub App user authorization
• Authenticated starred repository import
• starred_at preservation
• GitHub field availability
• Local IndexedDB storage
• Browser Web Worker analysis
• JSON export

Copy .env.example to .env or export the variables in your shell:

GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...
GITHUB_REDIRECT_URI=http://localhost:5173/auth/github/callback

Run:

npm run dev:pre-mvp

Then open:

http://localhost:5173

This app is intentionally small and dependency-free. It is not the final Astro/Cloudflare implementation.

Real App Local Dev

Copy the Worker env example:

cp apps/worker/.dev.vars.example apps/worker/.dev.vars

Set the GitHub App values in apps/worker/.dev.vars. The local callback URL is:

http://127.0.0.1:8787/auth/github/callback

Run the Worker:

npm run dev:worker

Run the web app in another terminal:

npm run dev:web

Then open:

http://127.0.0.1:4321

Hosted Setup

Hosted testing uses Cloudflare Pages for apps/web, a Cloudflare Worker for apps/worker, a Durable Object for auth/session coordination, and KV only for small settings records.

Manual GitHub and Cloudflare UI setup is tracked in:

• Hosting UI Setup
• Hosting And Security Plan

AI Central Context

This repo uses AI Central steering and local Codex skill links.

Tracked files:

• AGENTS.md
• .codex/steering/*.md

Ignored local links:

• .codex/skills/

Refresh local skill symlinks with:

npm run codex:links