brucelikeeat · brucelikeeat · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026 · Mar 18, 2026
diff --git a/.env.example b/.env.example
@@ -0,0 +1,22 @@
+# Database — Supabase PostgreSQL
+# Transaction pooler URL from Supabase dashboard (Settings → Database → Connection string, port 6543)
+DATABASE_URL="postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres?pgbouncer=true"
+# Direct connection URL (port 5432) — required by Prisma for migrations
+DIRECT_URL="postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres"
+
+# GitHub OAuth (NextAuth "Sign in with GitHub")
+# Callback URL in GitHub OAuth App settings MUST be:
+#   http://localhost:3000/api/auth/callback/github
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+# NextAuth — generate a secret: openssl rand -base64 32
+NEXTAUTH_SECRET=
+NEXTAUTH_URL=http://localhost:3000
+
+# AI
+OPENAI_API_KEY=
+ANTHROPIC_API_KEY=
+
+# Queue
+REDIS_URL=redis://localhost:6379
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -0,0 +1,3 @@
+{
+  "extends": ["next/core-web-vitals"]
+}
diff --git a/.gitignore b/.gitignore
@@ -27,3 +27,7 @@ yarn-error.log*
 # TypeScript
 *.tsbuildinfo
 next-env.d.ts
+
+# Local Prisma SQLite (created by migrate)
+prisma/*.db
+prisma/*.db-journal
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,60 @@
+# AGENTS.md
+
+Guidance for AI agents working in this repository.
+
+## Cursor Cloud specific instructions
+
+### Product
+
+Devlog is a single Next.js 14 app (not a monorepo). One process (`npm run dev` or `npm start`) serves the UI and all API routes. SQLite via Prisma stores users/sessions; GitHub OAuth and Anthropic APIs are external.
+
+### Update script vs manual setup
+
+The VM **update script** only runs `npm install` (which triggers `postinstall` → `prisma generate`). It does **not** start services, run migrations, or create `.env.local`.
+
+On a **fresh clone**, after `npm install`:
+
+1. `cp .env.example .env.local` and fill secrets (see README).
+2. Apply DB migrations (see SQLite note below).
+3. Start the dev server (see Running).
+
+### SQLite `DATABASE_URL` gotcha
+
+Prisma CLI resolves SQLite paths **relative to `prisma/schema.prisma`**, while the Next.js app resolves them **relative to the repo root**. The example `file:./prisma/dev.db` can create `prisma/prisma/dev.db` when using the CLI but `prisma/dev.db` at runtime.
+
+**Recommended for Cloud Agents:** use an absolute path in `.env.local`, e.g. `DATABASE_URL="file:/workspace/prisma/dev.db"`, then run migrations with that file sourced:
+
+```bash
+set -a && source .env.local && set +a && npx prisma migrate deploy
+```
+
+### Running the dev server
+
+Use a dedicated tmux session (do not rely on one-shot background shells):
+
+```bash
+SESSION_NAME="devlog-dev"
+tmux -f /exec-daemon/tmux.portal.conf has-session -t "=$SESSION_NAME" 2>/dev/null \
+  || tmux -f /exec-daemon/tmux.portal.conf new-session -d -s "$SESSION_NAME" -c /workspace -- "${SHELL:-bash}" -l
+tmux -f /exec-daemon/tmux.portal.conf send-keys -t "$SESSION_NAME:0.0" 'cd /workspace && npm run dev' C-m
+```
+
+App URL: http://localhost:3000
+
+### Lint / typecheck / build
+
+See `package.json` scripts: `npm run lint`, `npm run type-check`, `npm run build`. There is no `test` script or `tests/` directory in the repo today.
+
+### What works without secrets
+
+| Flow | Requirements |
+|------|----------------|
+| Landing, marketing UI | Dev server only |
+| Login UI | Dev server + placeholder or real `GITHUB_*` + `NEXTAUTH_*` |
+| GitHub sign-in, timeline, generate | Real GitHub OAuth app + user session; generate also needs `ANTHROPIC_API_KEY` |
+
+Protected app routes (e.g. `/timeline`, `/dashboard`) redirect to `/login` when unauthenticated.
+
+### Optional / unused today
+
+`REDIS_URL`, `OPENAI_API_KEY`, and Postgres are documented in `.env.example` but not used by current `src/` code. No Docker Compose or separate worker process.
diff --git a/README.md b/README.md
@@ -184,15 +184,19 @@ Help developers grow audiences, acquire early users, build communities, and laun
 
 ## Tech Stack
 
+Devlog is built on a modern, industry-standard web stack that’s common across SaaS dashboards and developer tools.
+
 | Layer | Technology | Purpose |
 |-------|-----------|---------|
-| **Frontend** | Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Geist font | Dashboard, timeline, content editor, analytics, calendar UI |
-| **Styling** | Tailwind CSS, `clsx`, `tailwind-merge`, `class-variance-authority`, `lucide-react` | Dark-mode design system, variant-based components, icon library |
-| **Backend** | Next.js Route Handlers, TypeScript | GitHub event processing, AI generation, API routing, platform integrations |
-| **AI** | OpenAI API, Anthropic API, local model support *(planned)* | Commit summarization, post generation, tone adaptation, thread formatting |
-| **Database** | PostgreSQL + Prisma | Users, repositories, generated posts, platform tokens, analytics |
-| **Queue** | Redis, BullMQ | AI job processing, scheduled posts, event pipelines |
-| **Infra** | Vercel, Railway / Fly.io, Supabase, Cloudflare | Frontend hosting, backend hosting, auth + database, edge security |
+| **Frontend** | Next.js 14 (App Router), React 18, TypeScript, Tailwind CSS, Geist font, Framer Motion | Modern, responsive dashboard UI, timeline, content editor, analytics, and calendar interactions |
+| **Styling** | Tailwind CSS, `clsx`, `tailwind-merge`, `class-variance-authority`, `lucide-react` | Dark-mode design system, variant-based components, utility composition, and icons |
+| **Backend** | Next.js Route Handlers, TypeScript | GitHub webhook handling, event processing, AI orchestration, API routing, and platform integrations |
+| **AI** | OpenAI API, Anthropic API, local model support *(planned)* | Commit summarization, outcome-focused narrative, multi-platform post generation, and tone adaptation |
+| **Database** | PostgreSQL + Prisma | Users, repositories, events, generated posts, privacy settings, and analytics |
+| **Queue** | Redis, BullMQ *(or equivalent)* | Background AI job processing, scheduled posts, and event pipelines |
+| **Infra** | Vercel, Railway / Fly.io, Supabase/Neon, Cloudflare | Frontend hosting, backend services, managed Postgres, auth, and edge security |
+
+Python and FastAPI are also strong candidates for AI-heavy backend components in the future, but the initial product surface is optimized around the React + TypeScript + Next.js ecosystem that most modern dev tools use.
 
 ---
 
@@ -201,8 +205,8 @@ Help developers grow audiences, acquire early users, build communities, and laun
 ### Prerequisites
 
 - Node.js 18+
-- PostgreSQL
-- Redis
+- A **GitHub OAuth App** (for “Sign in with GitHub”)
+- **SQLite** is used by default for local development (no Postgres required to start). Redis/Postgres remain optional for future features.
 
 ### Setup
 
@@ -215,20 +219,27 @@ cd devlog
 npm install
 
 # Configure environment variables
-cp .env.example .env
+cp .env.example .env.local
 ```
 
-Add your keys to `.env`:
+Add your keys to `.env.local` at minimum:
 
 ```env
-OPENAI_API_KEY=
+DATABASE_URL="file:./prisma/dev.db"
 GITHUB_CLIENT_ID=
 GITHUB_CLIENT_SECRET=
-DATABASE_URL=
-REDIS_URL=
+NEXTAUTH_SECRET=   # e.g. openssl rand -base64 32
+NEXTAUTH_URL=http://localhost:3000
 ```
 
+In your **GitHub OAuth App**, set **Authorization callback URL** to:
+
+`http://localhost:3000/api/auth/callback/github`
+
 ```bash
+# Create / update the local database
+npx prisma migrate dev
+
 # Start development server
 npm run dev
 ```
@@ -284,9 +295,47 @@ This keeps `main` clean for deployments while preserving a clear history of feat
 
 ---
 
+## Project Structure
+
+Devlog currently uses a **single-app structure** optimized for fast iteration, with a clean path to a future monorepo split if the backend grows significantly.
+
+```text
+docs/                 architecture, API contracts, decision records, agent coordination
+src/app/              Next.js routes and route handlers
+src/components/       reusable UI components
+src/features/         feature-level domains (github, timeline, privacy, post generation, etc.)
+src/lib/              shared helpers and infrastructure clients
+src/server/           server-only services, repositories, jobs, and schemas
+src/styles/           global styles
+src/types/            shared application types
+prisma/               database schema and migrations
+scripts/              local automation scripts
+tests/                unit and integration tests
+.github/workflows/    CI and automation workflows
+```
+
+### Agent coordination rule
+
+Every `feature/*` branch must update `docs/agent-worklog.md` in its first meaningful commit so each implementation chat can quickly understand:
+
+- what branch is active,
+- what area is being changed,
+- what files are expected to be touched,
+- and whether the work depends on any API or data model changes.
+
+Supporting docs:
+
+- `docs/CHANGELOG.md` — dated milestones (start here for “what changed when”)
+- `docs/architecture.md`
+- `docs/api-contracts.md`
+- `docs/agent-worklog.md`
+- `docs/decisions/`
+
+---
+
 ## Current Build Status
 
-> Last updated: Mar 19, 2026 · `v0.1.0` · branch `feature/dev-timeline-ui`
+> Last updated: Mar 19, 2026 · `v0.1.0` · merged into `main`
 
 | Area | Status | Notes |
 |------|--------|-------|
@@ -295,7 +344,7 @@ This keeps `main` clean for deployments while preserving a clear history of feat
 | Dashboard | ✅ Prototype | Static placeholder data |
 | Dev Timeline UI | ✅ Done | Fully componentized, fake data, live search + type filter |
 | Settings page | ✅ Prototype | UI shell only |
-| GitHub integration | 🔲 Planned | OAuth, webhook, event normalization |
+| GitHub integration | 🟡 In Progress | OAuth connect, repo picker, commit fetch (no webhooks yet) |
 | AI post generator | 🔲 Planned | LLM prompt pipeline |
 | Content editor | 🔲 Planned | Rich text, tone adjustment |
 | Multi-platform publishing | 🔲 Planned | X, LinkedIn, Reddit, Dev.to |
@@ -330,6 +379,36 @@ Community features, developer leaderboard, automatic devlogs, visual content gen
 
 ---
 
+## Release Milestones
+
+Devlog will use simple semantic versioning to mark meaningful product stages.
+
+### v0.1.0 – Internal MVP
+
+- GitHub OAuth + repo selection for a single user.
+- Basic event capture from commits and/or pull requests.
+- Simple internal-only dev timeline UI with fake or minimal AI summaries.
+- No external users yet, used only by the maker to test core workflows.
+
+### v0.2.0 – Early Access (Friends & Testers)
+
+- Reliable GitHub event ingestion for selected repos.
+- AI-generated summaries for meaningful events (commit/PR → outcome-focused text).
+- Editable dev timeline entries and a first version of privacy levels (e.g., high vs medium).
+- Ability to generate draft posts for at least reddit, maybe X and LinkedIn.
+- Onboarding that a small group of external testers can complete without hand-holding.
+
+### v1.0.0 – Public Launch
+
+- Stable GitHub integration with clear error handling and status.
+- Polished dev timeline and content calendar suitable for daily use.
+- Mature privacy controls, documented and easy to understand.
+- Multi-platform post generation with tone presets (X, LinkedIn, Reddit at minimum).
+- Basic analytics (consistency and top-performing posts) and a simple paid plan.
+- Public landing page, documentation, and GitHub release tagged `v1.0.0`.
+
+---
+
 ## Pricing (Planned)
 
 Devlog will ship with a simple, pragmatic pricing model designed to balance adoption and sustainability.
@@ -365,6 +444,7 @@ Devlog will ship with a simple, pragmatic pricing model designed to balance adop
 | **Automatic Devlogs** | AI-generated weekly progress reports |
 | **Visual Content Generation** | Feature screenshots, product mockups, diagrams |
 | **Audience Discovery** | Identify potential users by interest, engagement, and topic relevance |
+| **Devlog → Docs Integration** | Export timeline entries into long-form documentation (e.g. wiki-style pages) for design notes, changelogs, and internal knowledge bases |
 
 ---
 

diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
@@ -0,0 +1,83 @@
+# Documentation & product changelog
+
+This file lists **major milestones** so anyone opening `docs/` can see **what changed and when**.  
+For day-to-day task detail, see **`agent-worklog.md`**. For HTTP shapes, see **`api-contracts.md`**.
+
+Entries are **newest first**. Dates use **ISO-style `YYYY-MM-DD`** when known; otherwise **`YYYY-MM`**.
+
+---
+
+## 2026-05-04
+
+| Area | What changed |
+|------|----------------|
+| Post generator | **Phase A — enrichment layer:** `enrichEvent.ts` (Anthropic Haiku pre-pass), `sanitizeEvent.ts` (privacy levels). |
+| Post generator | **Phase B.1 — LinkedIn prompt template:** `templates/linkedinTemplate.ts` (`buildLinkedInPrompt`) — story-arc structure, tone-aware, ≤2 hashtags, hype-opener block. |
+| Post generator | **Phase B.2 — X prompt template:** `templates/xTemplate.ts` (`buildXPrompt`) — hook-first (first 8 words), ≤260 char hard cap, no `I`/`We`/`Just` openers, banned generic-spam hashtags, in-prompt char self-check. Replaces earlier same-day stub. |
+| Post generator | **Phase B.3 — Reddit prompt template:** `templates/redditTemplate.ts` (`buildRedditPrompt`) — title + body, devlog voice, banned-vocab list, tone-aware, no hashtags, uses `difficulty` for calibration. *(Renumbered from B.2 → B.3 on the same day when the X template took B.2.)* |
+| Post generator | **Phase C.1 — Core `generatePost`:** `generatePost.ts` (`Platform`, `GeneratedPost`, `generatePost`) — wires enricher + sanitizer + templates → Anthropic `claude-sonnet-4-6`, X retry-once-when-over-280 logic, throws `Failed to generate ${platform} post: ${message}` on any failure. |
+| API| **Phase C.2 — `POST /api/posts/generate` rewritten:** route now drives the full pipeline (enrich → sanitize → anchor pick → parallel generation). **Response shape changed** from bare `GeneratedPost[]` to `{ posts: GeneratedPost[] }`, and each post now includes `characterCount`. Internal HTTP `fetch /api/timeline` (session cookie forwarded) replaces direct Prisma access. |
+| App | **C.2-followup — Generator UI parse fixed:** `src/app/(app)/generate/page.tsx` now destructures `{ posts }` from the new `{ posts: GeneratedPost[] }` response envelope. One-line data-parsing change only; no UI, state, or other logic altered. |
+| Docs | `api-contracts.md` — `POST /api/posts/generate` rewritten with new pipeline semantics, anchor-event rule, and updated response shape. Internal modules for enrich, sanitize, LinkedIn / X / Reddit templates, and `generatePost` documented. |
+| Post generator | **C.3 — Retry wrapper + error resilience:** `withRetry.ts` (1 retry, 500 ms delay, returns `null` on total failure). Route now returns `207 { posts, failed }` on partial success and `500` only when all platforms fail. |
+| UI | **D.1 — `EventSelector` component:** `src/components/postGenerator/EventSelector.tsx` — selectable timeline event cards; amber/violet/blue/emerald badges by type; summary truncated at 100 chars; "Select all / Deselect all" toggle; keyboard accessible. |
+
+| UI | **D.2 — `OptionsPanel` component:** `src/components/postGenerator/OptionsPanel.tsx` — platform toggles (colored dots), 4-option tone selector with descriptions, 3-option privacy selector (emerald/amber/red accent per risk level). Fully controlled, `aria-pressed` on all toggles. |
+
+
+| UI | **D.3 — `ResultsPanel` component:** `src/components/postGenerator/ResultsPanel.tsx` — auto-resize textareas, X char counter (red >280, amber >90%), clipboard copy with 2s "Copied!" feedback, per-platform Regenerate button with spinner. |
+
+| UI | **D.4 — Generate page wired up:** `src/app/(app)/generate/page.tsx` rewritten — two-column desktop layout, all three D-components composed, generate + per-platform regenerate handlers, 207 partial-failure warning, scroll-to-results, loading skeleton. Sidebar nav unchanged (already had Generate). |
+---
+
+## 2026-05 (month; see `agent-worklog` for task IDs)
+
+| Area | What changed |
+|------|----------------|
+| GitHub & timeline | **Phase 1:** Prisma/env checks, NextAuth audit, `src/lib/github` helpers, GitHub API routes audit. |
+| GitHub & timeline | **Phase 2:** `fetchRepoPullRequests`, `fetchRepoReleases`, `normalizeEvents.ts`. |
+| API | **`GET /api/timeline`** — commits + PRs + releases → `TimelineEntry[]`. |
+| App | **Timeline page** wired to `/api/timeline` (server fetch with session). |
+| Post generator | **`POST /api/posts/generate`** — Anthropic, platform drafts. |
+| App | **Generate page** + sidebar link — select events, platforms, tone, privacy. |
+
+- !!!! important, the next step is to improve the landing hero page and the timeline UI ( for the timeline UI i want it to be more interactive and heavier on the motion graphic side, like a galaxy kind of vibe where each star is a cahnge and they can form some kind of timeline with dates and user can click to check on each of them, and together they form something big and cool that user can feel a sense of accomplishment when seeing them)
+- update pro plan idea(better post generations access to more niche platforms and analystics and also theres should be a limit for the number of post generated by free users like 20 posts? also how much should the pro plan be, 6.99? or 12.99? )
+- Question: should I integrate a function where users can one click posts the content through our website or just leave it as of right now where user can just copy and paste the content from our website and post it to social media platforms themselevs, and if i want to integrate this functionality, how much effort do I have to put in such as " I might have to connect the API of each social media platform to my website and some of them I believe costs money.  
+---
+
+## 2026-03-19
+
+| Area | What changed |
+|------|----------------|
+| App / UI | **`feature/dev-timeline-ui`** merged to `main` — timeline types, filters, demo data, dashboard/settings/timeline routes, app shell alignment. |
+
+---
+
+## 2026-03-18
+
+| Area | What changed |
+|------|----------------|
+| App / UI | **`feature/app-shell`** merged to `main` — sidebar, topbar, `(app)` layout (PR #3). |
+
+---
+
+## 2026-03-16
+
+| Area | What changed |
+|------|----------------|
+| Marketing | **`feature/landing-page`** merged to `main` — full marketing landing (PR #2). |
+
+---
+
+## Earlier foundation
+
+| When | What |
+|------|------|
+| **2026-03** (approx.) | Initial Next.js app, Tailwind, Prisma, NextAuth (GitHub), ADR-0001 structure. |
+
+---
+
+## How to update this file
+
+When you ship a **user-visible** or **contract-changing** milestone, add a **dated section** at the top (or append under the right month) with a short table. Link to PRs or commits when helpful.