Plan 2026

Personal full-stack portfolio app: Next.js App Router task and plan management with Google sign-in, PostgreSQL/Prisma data modeling, JSON export APIs, server actions, optional rich task notes, urgency levels, due dates, and Google Calendar event creation.

Production: https://plan2026.ca

Features

• Google sign-in with NextAuth v4 and Prisma-backed database sessions
• Actions – The app logo links to /actions, a page showing urgent and upcoming tasks (urgency 6+ or due within the next three days). Overdue tasks show an alarm icon; you can edit, mark done, or add to calendar from the list.
• Tasks – A single /tasks page for day-to-day work:
  • Optional completed-task visibility via a header toggle; choice is stored in a first-party cookie (updated with POST /api/list-prefs, not the URL)
  • Add and edit tasks in dialogs (title, rich text notes, due date, urgency 1–7)
  • Mark tasks done, restore them, or delete them
  • Export tasks (or a single task from the edit dialog) to JSON for debugging or AI ingestion
  • Add a task to Google Calendar and keep track of whether it has already been linked
  • Tasks can be linked to a plan; task rows show a “Plan: …” link when set
• Plans – A /plans area to group tasks and track progress:
  • List of plans ordered by priority (1–7, like task urgency); each plan has name, status (draft / started / on hold / completed / abandoned), percent completed, dates, and optional image (paste URL)
  • Refresh button and “Show completed / abandoned” toggle on the plans list (same cookie + POST /api/list-prefs persistence as tasks); each row has an Edit link and a status dropdown
  • Full-page create at /plans/new and edit at /plans/[id] (no modals)
  • Add existing tasks or create new tasks when editing a plan; on the plan detail page you can edit any task in the plan via an edit-task modal
  • Export plans (or a single plan from its detail page) to JSON for debugging or AI ingestion
  • Plan fields: goal, actual start/end dates, notes, color
  • Public share links: from the plan detail page, owners can create a shareable link; anyone with the link can view the plan and its tasks in read-only form and, when allowed, mark tasks done or restore them (no sign-in required). Only explicitly shared plans are exposed.
• Settings page to disconnect Google Calendar access
• Server actions for UI mutations and JSON API routes for programmatic access

Tech stack

• Next.js 16
• React 19
• TypeScript
• Tailwind CSS v4
• Prisma ORM 7 (PostgreSQL via driver adapter; see prisma.config.ts)
• PostgreSQL
• NextAuth v4
• Zod 4
• Tiptap
• Sonner

Requirements

• Node.js 20+ and pnpm (the repo pins the version via packageManager in package.json; with Corepack: corepack enable)
• A PostgreSQL database for local development and testing
• A Google OAuth client with Calendar access enabled

Environment variables

Set these in .env for local development:

• DATABASE_URL - PostgreSQL connection string
• AUTH_SECRET - NextAuth secret (required in production; see DEPLOY.md for secret rotation)
• GOOGLE_CLIENT_ID - Google OAuth client id
• GOOGLE_CLIENT_SECRET - Google OAuth client secret
• NEXTAUTH_URL - usually http://localhost:3000 locally
• BLOB_READ_WRITE_TOKEN - (optional) Vercel Blob token for task file attachments; create a Blob store in the Vercel project and pull env with vercel env pull
• AUTH_FACEBOOK_ID - (optional) Facebook app client ID for Facebook login
• AUTH_FACEBOOK_SECRET - (optional) Facebook app client secret
• AUTH_FACEBOOK_ENABLED - (optional) Set to true to show Facebook login (requires ID + secret). Production already has this set.

Local development

This app uses PostgreSQL in every environment, including local development, local testing, and production.

1. Install dependencies:

pnpm install

2. Configure the environment variables listed above in .env, pointing DATABASE_URL at your local development or test Postgres database.

3. Run Prisma migrations against your local Postgres database:

pnpm exec prisma migrate dev

4. Start the app:

pnpm run dev

5. Open http://localhost:3000.

Testing

The project uses Vitest for unit and integration tests. Run tests with:

• pnpm test – run tests once
• pnpm run test:watch – run tests in watch mode
• pnpm run test:coverage – run tests with coverage report
• pnpm run bulk:next -- <PR_NUMBER> – merge that PR, update main, check out the next open PR’s branch and merge main into it; prints what to test (see danf-skills bulk-task-pr skill and AGENTS.md).

Tests live next to source files (e.g. src/lib/export.test.ts). Good candidates for unit tests:

• src/lib/* – export helpers, sanitize, validations, rate limiter (no DB)
• Zod schemas – parse/refine behavior in src/lib/validations/task.ts and plan.ts

For React components, add @vitest-environment jsdom at the top of the test file and use React Testing Library (already installed). For API routes or server actions that hit the database, use a test database or mock Prisma. Optional: Playwright for end-to-end flows (e.g. login, create task).

Before you push

A pre-push Git hook (via Husky) runs pnpm run prepush, which runs lint and typecheck only so pushes stay fast. Full pnpm run build (Prisma generate + Next.js build) runs in CI and will catch build failures. To run the same checks manually: pnpm run prepush. For a full build: pnpm run build.

Port 3000 already in use

If you see "Port 3000 is in use" or "Unable to acquire lock at .next/dev/lock", a previous dev server is still running. On Windows this often happens when the terminal is closed without stopping the server, or when the process doesn’t receive a shutdown signal.

• Stop the server properly: Use Ctrl+C in the terminal where pnpm run dev is running instead of closing the window.
• Free the port: Run pnpm run dev:kill to kill the process on port 3000, then run pnpm run dev again.
• Manual kill (Windows): netstat -ano | findstr :3000, then taskkill /PID <pid> /F. Or use Task Manager → Details → end the node.exe process (or "End process tree" on the pnpm parent).

The root route redirects to /tasks. The app shell includes Tasks, Plans, Help, and About nav links; Plans lists your plans and links to Add plan (/plans/new) and to each plan’s detail/edit page (/plans/[id]). Help (/help) shows how to use tasks and plans plus recent updates; About (/about) shows app version and contributor info.

Google OAuth setup

In Google Cloud Console:

1. Enable the Google Calendar API for the same project as your OAuth client.
2. Add this local origin:
   • http://localhost:3000
3. Add this local redirect URI:
   • http://localhost:3000/api/auth/callback/google

The app requests these Google scopes during sign-in:

• openid
• email
• profile
• https://www.googleapis.com/auth/calendar.events

Google sign-in forces a fresh Google consent step so revoked Calendar permissions can be granted again on reconnect.

Facebook login (optional)

To enable "Continue with Facebook" on the login page:

1. Create an app at developers.facebook.com and add the Facebook Login product.
2. In Facebook Login settings, add a Valid OAuth Redirect URI: https://<your-domain>/api/auth/callback/facebook. Production lists only https://plan2026.ca/api/auth/callback/facebook (localhost is not listed; Strict mode is on).
3. Set AUTH_FACEBOOK_ID, AUTH_FACEBOOK_SECRET, and AUTH_FACEBOOK_ENABLED=true in your environment. Vercel Production already has all three.
4. Request only public_profile and email. As of 18 October 2026, public_profile has Advanced access and email is Standard access with Verification required. The business Anthony & Omolola Enterprises is Verified.

The OAuth endpoints pin Graph API v26.0 (FACEBOOK_GRAPH_VERSION in src/lib/facebook-login.ts; NextAuth v4's default still points at the retired v11.0). Data deletion instructions are at /privacy#data-deletion. An optional Data Deletion Callback is implemented at POST /api/facebook/data-deletion, with a status page at /privacy/deletion-status. Meta calls it only if that URL is set instead of the instructions URL.

Production go-live: follow GO-LIVE-FACEBOOK.md.

API

All API routes require an authenticated session. Responses use JSON; errors return { error: "message" } with an appropriate status code (401 Unauthorized, 400 Bad Request, 404 Not Found, 429 Too Many Requests). Rate limiting applies per user (in-memory; see TECH-1005 for production notes).

• GET /api/tasks — List all tasks for the signed-in user. No pagination (returns full list). Order: completedAt desc, then createdAt desc. Response: { tasks }. Each task includes plan: { id, name } and attachments when present.
• POST /api/tasks — Create a task. Body: see below. Response: { task }, 201.
• PATCH /api/tasks/:id — Update completion. Body: { "completed": true | false }. Sets completedAt to now or null.
• DELETE /api/tasks/:id — Delete a task (owner only).
• POST /api/tasks/:id/calendar — Create a Google Calendar event for the task.
• POST /api/list-prefs — Persist list UI preferences for the signed-in user. JSON body: optional tasksShowCompleted and/or plansShowArchived (booleans). Sets first-party cookies used by /tasks and /plans (not server actions, to avoid an RSC refresh on every toggle).
• GET /api/plans — List plans (owned + shared). Paginated. Query: page (default 1), limit (default 20, max 100), showArchived=1 to include completed/abandoned. Order: priority desc, then createdAt desc. Response: { plans, total, page, limit, totalPages }. Each plan includes tasks: { id, completedAt }.
• POST /api/plans/cleanup-invites — Delete expired plan invites (e.g. for cron). Requires auth.

POST /api/tasks body

{
  "title": "Book flights",
  "content": "<p>Use the points portal first.</p>",
  "dueAt": "2026-03-10T14:30",
  "urgency": 4,
  "planId": "c..."
}

Notes:

• title is required
• content is optional rich text HTML and is sanitized before storing/rendering
• dueAt is optional; when present it is converted to a date
• urgency is optional and defaults to 4 (1–7)
• planId is optional; when present the plan must exist and be owned by the user

PATCH /api/tasks/:id body

{
  "completed": true
}

Assets

• Header logo: public/plan2026-logo-c.png — trimmed in GIMP to remove transparent padding (TECH-0033). If you replace it, crop tight to the artwork or the header may show extra space.

Deployment

Deployment instructions live in DEPLOY.md.

In short:

1. Create a Vercel project.
2. Provision PostgreSQL and set the required env vars.
3. Configure Google OAuth with your production callback URL (https://plan2026.ca/api/auth/callback/google) and Calendar API access. Before advertising a public demo, follow GO-LIVE.md (privacy URL, Vercel env, Google verification).
4. Deploy. The Vercel production build runs prisma migrate deploy (using DATABASE_URL), then prisma generate and next build. Preview builds, GitHub Actions, and local pnpm run build do not migrate. See DEPLOY.md for the one-shot command that applies a pending migration to the live database.

The database story is intentionally the same in every environment: PostgreSQL for local work and PostgreSQL in production.