Hackathon workspace for CodePiece — swipe through real TypeScript snippets, like or skip, and optionally take private notes. Visual direction: docs/STYLE.md.

What this repo is (spec)

CodePiece is a small swipe-based app for discovering and rating code snippets from a local corpus. A Bun CLI scans a repo on disk into SQLite; Next.js serves a home screen (pick a focus repository, see progress) and a swipe deck. Sessions are anonymous (cookie); no OAuth. Attribution stays symbol / path / repo label only — see docs/GUARDRAILS.md.

Full product intent and mechanics: docs/SPEC.md.

Features

Shipped

• ✅ Home (/) — choose focus repo, progress (reviewed / pending), stats snapshot, link to swipe.
• ✅ Swipe (/swipe) — card stack, like / skip persisted, drag + buttons, copy snippet.
• ✅ Feed — unswiped cards first from focus repo (ordered), then random global fallback; or all-random with no focus.
• ✅ Snippet memos — private note per card (600 code points max), Save closes popover.
• ✅ Stats panel — slide-over dashboard + library sidebar (your likes ranking); symbol / repo / path only.
• ✅ Themes — picker in chrome.
• ✅ Ingestion — bun run scan / bun run seed:samples → cards in SQLite; bundled TheAlgorithms/TypeScript sample under samples/the-algorithms-typescript/.
• ✅ APIs — /api/users, /api/cards/next, /api/swipes, /api/cards/memo, /api/dashboard/stats, /api/queue, /api/cards/browse.
• ✅ Tests — bun test; bun run db:clear wipes default DB + scan memory for a clean re-seed.

In progress & backlog

• 🚧 vs full SPEC — personal stats only (no global popularity feed); no “seen without swipe” store; discovery quality is mostly scan heuristics, not ML ranking (plan/FEATURES.md).
• 📋 Matching / owners — not in scope (no identity graph).
• 📋 Polish — .tsx ingestion, keyboard shortcuts, formal migrations beyond runtime INIT_SQL, optional memo listing — see plan/FEATURES.md and plan/PRODUCTION.md for ops.

Tooling: Bun

This repo uses Bun as the package manager and runtime for scripts: bun install, bun test, bun run scan, and bun run for Next.js. Do not use npm, yarn, or pnpm for installs (they will not respect bun.lock).

1. Install Bun — follow the official Installation guide (install script, Homebrew tap oven-sh/bun/bun, Docker image, etc.).
2. command not found: bun — see docs/TROUBLESHOOTING.md (Bun PATH).

Quick start

The feed reads Card rows created only by bun run scan. Until you scan at least once, /api/cards/next may return nothing useful.

bun install
bun run db:clear   # optional: wipe SQLite + scan memory under data/
bun run seed:samples
bun run dev

Wait until the terminal shows Ready, then open http://localhost:4000 (Home). Use Start swiping or /swipe for the deck. This app uses port 4000 only — http://localhost:3000 will not respond unless you changed the scripts yourself. Optional env vars (CODEPIECE_DB, SCAN_MEMORY_PATH, REPO_LABEL) are listed in docs/TECHNICAL.md. If the feed stays empty after a scan, see docs/TROUBLESHOOTING.md.

Build and run

From the repo root:

bun install

Development (port 4000 only, Turbopack, hot reload / Fast Refresh):

bun run dev

Production (optimized bundle, then serve):

bun run build
bun run start

bun run build type-checks, lints (Next defaults), and writes .next/; bun run start serves that build on port 4000. Stop the server with Ctrl+C.

Use the same CODEPIECE_DB for bun run scan, bun run dev, and bun run start (default data/codepiece.db). SQLite is opened via Bun or Node depending on the process — see docs/TECHNICAL.md.

Inspect the DB (read-only): bun run db:stats prints row counts (users, cards, swipes), swipe totals by action, per-user swipe counts, cards grouped by repo_label, SQLite logical size, and on-disk sizes for the main file, WAL, and shm. Uses CODEPIECE_DB; fails fast if the path is :memory: or missing.

Ports, Docker file-watching, scan --force, and other fixes: docs/TROUBLESHOOTING.md.

Docker (optional)

docker-compose.yml runs Next.js dev in oven/bun:1 with the repo and ./data mounted; port 4000. docker compose up, then open http://localhost:4000. Run bun run scan on the host with CODEPIECE_DB=data/codepiece.db so cards share the same DB file. Details (hot reload, restarts): docs/TROUBLESHOOTING.md.

---

bun --version
bun test

Docs

• AGENTS.md (repo root) — shortcut to agent guidance; full text in docs/AGENTS.md
• docs/COMMANDS.md — bun run … cheat sheet (agents: start with docs/AGENTS.md)
• docs/TEST-SPEC.md — test commands and DB/runtime notes
• docs/TROUBLESHOOTING.md — ports, Docker, scan, UI quirks
• docs/SPEC.md — product specification
• docs/GUARDRAILS.md — what not to do (product guardrails)
• docs/TECHNICAL.md — stack, storage, ingestion, Docker overview
• plan/FEATURES.md — implementation map vs SPEC (detailed)
• docs/AGENTS.md — how to use these docs as a coding agent (includes plan/ read order for implementers)
• plan/v1-plan.md — execution checklist and API surface

AI tooling (Cursor / agents)

Parts of this repo are adapted from everything-claude-code (MIT — upstream agent harness patterns for Claude Code, Cursor, and related tools):

Location	Role
.cursor/rules/	Project rules (e.g. coding style, testing expectations).
.cursor/skills/	Optional workflows (e.g. Bun runtime, Next.js Turbopack, documentation lookup).
agents/	Subagent-style prompts (e.g. planner, TypeScript reviewer).

Use them together with docs/AGENTS.md (or root AGENTS.md). CodePiece-specific docs (docs/GUARDRAILS.md, plan/v1-plan.md, docs/TEST-SPEC.md) win if anything conflicts with generic upstream guidance.

Sample scan targets

• samples/the-algorithms-typescript/ — vendored snapshot of TheAlgorithms/TypeScript (see samples/the-algorithms-typescript/CODEPIECE.md). bun run seed:samples scans it with REPO_LABEL=TheAlgorithms/TypeScript.
• For other corpora, clone locally and set TARGET_REPO (see samples/README.md), e.g. Lugriz/typescript-algorithms.