@nexttylabs/echo 0.4.0 → 0.5.0

package/docs/plans/2026-01-09-phase2-3-plan.md

@@ -1,654 +0,0 @@
-# Phase 2 & Phase 3 Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Deliver Phase 2 (JWT identify + portal theming + portal copy + sorting + contributors + analytics + sharing) and Phase 3 (project switcher + anonymous submissions + portal SEO + multilingual + portal module toggle).
-
-**Architecture:** Add a JWT identify endpoint for frictionless sessions, a portal theme/copy/sorting config layer that drives UI and defaults, and contributor/leaderboard settings that can be toggled or anonymized. Extend portal capabilities with analytics, sharing, project filters, anonymous submissions, SEO configuration, multilingual support, and module enable/disable switches.
-
-**Tech Stack:** Next.js App Router, React 19, TypeScript, Tailwind v4, Drizzle, bun:test
-
----
-
-## Phase 2 (Growth)
-
-### Task 1: JWT Identify API
-
-**Files:**
-- Create: `app/api/identify/jwt/route.ts`
-- Create: `lib/auth/jwt-identity.ts`
-- Test: `tests/api/identify-jwt.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { parseJwtIdentity } from "@/lib/auth/jwt-identity";
-
-describe("parseJwtIdentity", () => {
-  it("returns null when token is empty", () => {
-    expect(parseJwtIdentity("")).toBe(null);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/api/identify-jwt.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/auth/jwt-identity'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function parseJwtIdentity(token: string) {
-  if (!token) return null;
-  return { token };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/api/identify-jwt.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/api/identify/jwt/route.ts lib/auth/jwt-identity.ts tests/api/identify-jwt.test.ts
-
-git commit -m "feat: add jwt identify endpoint"
-```
-
----
-
-### Task 2: Portal Theme Templates + Branding
-
-**Files:**
-- Create: `lib/portal/theme.ts`
-- Create: `app/(dashboard)/settings/portal-theme/page.tsx`
-- Modify: `app/portal/page.tsx`
-- Test: `tests/lib/portal-theme.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getDefaultPortalTheme } from "@/lib/portal/theme";
-
-describe("portal theme", () => {
-  it("returns a default theme", () => {
-    expect(getDefaultPortalTheme()).toHaveProperty("name");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-theme.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/theme'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getDefaultPortalTheme() {
-  return { name: "clean" };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-theme.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/theme.ts app/(dashboard)/settings/portal-theme/page.tsx app/portal/page.tsx tests/lib/portal-theme.test.ts
-
-git commit -m "feat: add portal theme config"
-```
-
----
-
-### Task 3: Portal Copy + CTA Customization
-
-**Files:**
-- Create: `lib/portal/portal-copy.ts`
-- Create: `app/(dashboard)/settings/portal-copy/page.tsx`
-- Modify: `components/portal/portal-shell.tsx`
-- Test: `tests/lib/portal-copy.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getDefaultPortalCopy } from "@/lib/portal/portal-copy";
-
-describe("portal copy", () => {
-  it("returns defaults", () => {
-    const copy = getDefaultPortalCopy();
-    expect(copy).toHaveProperty("title");
-    expect(copy).toHaveProperty("ctaLabel");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-copy.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/portal-copy'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getDefaultPortalCopy() {
-  return { title: "反馈中心", description: "", ctaLabel: "提交反馈" };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-copy.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/portal-copy.ts app/(dashboard)/settings/portal-copy/page.tsx components/portal/portal-shell.tsx tests/lib/portal-copy.test.ts
-
-git commit -m "feat: add portal copy settings"
-```
-
----
-
-### Task 4: Default Sorting Configuration
-
-**Files:**
-- Create: `lib/portal/sorting.ts`
-- Modify: `components/portal/portal-shell.tsx`
-- Test: `tests/lib/portal-sorting.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getDefaultPortalSorting } from "@/lib/portal/sorting";
-
-describe("portal sorting", () => {
-  it("defaults to top", () => {
-    expect(getDefaultPortalSorting().order).toBe("top");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-sorting.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/sorting'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getDefaultPortalSorting() {
-  return { order: "top" } as const;
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-sorting.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/sorting.ts components/portal/portal-shell.tsx tests/lib/portal-sorting.test.ts
-
-git commit -m "feat: add portal default sorting"
-```
-
----
-
-### Task 5: Contributor Levels & Badges
-
-**Files:**
-- Create: `lib/portal/contributors.ts`
-- Create: `components/portal/contributor-badge.tsx`
-- Modify: `components/feedback/feedback-detail.tsx`
-- Test: `tests/lib/portal-contributors.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getContributorLevel } from "@/lib/portal/contributors";
-
-describe("contributors", () => {
-  it("returns level 1 by default", () => {
-    expect(getContributorLevel({ votes: 0, comments: 0, accepted: 0 })).toBe(1);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-contributors.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/contributors'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getContributorLevel() {
-  return 1;
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-contributors.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/contributors.ts components/portal/contributor-badge.tsx components/feedback/feedback-detail.tsx tests/lib/portal-contributors.test.ts
-
-git commit -m "feat: add contributor levels"
-```
-
----
-
-### Task 6: Leaderboard Visibility + Anonymize Toggle
-
-**Files:**
-- Create: `lib/portal/leaderboard-settings.ts`
-- Create: `components/portal/leaderboard.tsx`
-- Modify: `app/portal/page.tsx`
-- Test: `tests/lib/portal-leaderboard-settings.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getDefaultLeaderboardSettings } from "@/lib/portal/leaderboard-settings";
-
-describe("portal leaderboard settings", () => {
-  it("defaults to visible", () => {
-    expect(getDefaultLeaderboardSettings().enabled).toBe(true);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-leaderboard-settings.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/leaderboard-settings'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getDefaultLeaderboardSettings() {
-  return { enabled: true, anonymizeUsers: false };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-leaderboard-settings.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/leaderboard-settings.ts components/portal/leaderboard.tsx app/portal/page.tsx tests/lib/portal-leaderboard-settings.test.ts
-
-git commit -m "feat: add leaderboard visibility settings"
-```
-
----
-
-### Task 7: Portal Analytics Dashboard
-
-**Files:**
-- Create: `lib/portal/analytics.ts`
-- Create: `app/(dashboard)/analytics/portal/page.tsx`
-- Test: `tests/lib/portal-analytics.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getEmptyPortalAnalytics } from "@/lib/portal/analytics";
-
-describe("portal analytics", () => {
-  it("returns default analytics structure", () => {
-    expect(getEmptyPortalAnalytics()).toHaveProperty("timeseries");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-analytics.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/analytics'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getEmptyPortalAnalytics() {
-  return { timeseries: [], topViewed: [], topVoted: [], topCommented: [] };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-analytics.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/analytics.ts app/(dashboard)/analytics/portal/page.tsx tests/lib/portal-analytics.test.ts
-
-git commit -m "feat: add portal analytics dashboard"
-```
-
----
-
-### Task 8: Portal Sharing Settings
-
-**Files:**
-- Create: `lib/portal/sharing.ts`
-- Create: `app/(dashboard)/settings/portal-sharing/page.tsx`
-- Test: `tests/lib/portal-sharing.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getPortalShareMethods } from "@/lib/portal/sharing";
-
-describe("portal sharing", () => {
-  it("lists share methods", () => {
-    expect(getPortalShareMethods()).toEqual(["link", "widget", "embedded"]);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-sharing.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/sharing'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getPortalShareMethods() {
-  return ["link", "widget", "embedded"] as const;
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-sharing.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/sharing.ts app/(dashboard)/settings/portal-sharing/page.tsx tests/lib/portal-sharing.test.ts
-
-git commit -m "feat: add portal sharing settings"
-```
-
----
-
-## Phase 3 (Expansion)
-
-### Task 9: Portal Project Switcher
-
-**Files:**
-- Create: `components/portal/project-switcher.tsx`
-- Modify: `app/portal/page.tsx`
-- Test: `tests/components/portal-project-switcher.test.tsx`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { ProjectSwitcher } from "@/components/portal/project-switcher";
-
-describe("ProjectSwitcher", () => {
-  it("exports a component", () => {
-    expect(typeof ProjectSwitcher).toBe("function");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/components/portal-project-switcher.test.tsx`
-Expected: FAIL with "Cannot find module '@/components/portal/project-switcher'"
-
-**Step 3: Write minimal implementation**
-
-```tsx
-export function ProjectSwitcher() {
-  return null;
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/components/portal-project-switcher.test.tsx`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add components/portal/project-switcher.tsx app/portal/page.tsx tests/components/portal-project-switcher.test.tsx
-
-git commit -m "feat: add portal project switcher"
-```
-
----
-
-### Task 10: Anonymous Submissions
-
-**Files:**
-- Modify: `lib/validators/feedback.ts`
-- Modify: `components/feedback/embedded-feedback-form.tsx`
-- Modify: `app/api/feedback/route.ts`
-- Test: `tests/lib/feedback-schema.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { feedbackSchema } from "@/lib/validators/feedback";
-
-describe("feedback schema", () => {
-  it("supports anonymous", () => {
-    const result = feedbackSchema.safeParse({
-      title: "t",
-      description: "d",
-      isAnonymous: true,
-    });
-    expect(result.success).toBe(true);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/feedback-schema.test.ts`
-Expected: FAIL with "Unknown key 'isAnonymous'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export const feedbackSchema = baseFeedbackSchema.extend({
-  submittedOnBehalf: z.boolean().optional().default(false),
-  customerInfo: customerInfoSchema.optional(),
-  isAnonymous: z.boolean().optional().default(false),
-});
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/feedback-schema.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/validators/feedback.ts components/feedback/embedded-feedback-form.tsx app/api/feedback/route.ts tests/lib/feedback-schema.test.ts
-
-git commit -m "feat: support anonymous feedback"
-```
-
----
-
-### Task 11: Portal SEO Configuration
-
-**Files:**
-- Create: `lib/portal/seo.ts`
-- Create: `app/(dashboard)/settings/portal-seo/page.tsx`
-- Modify: `app/portal/page.tsx`
-- Test: `tests/lib/portal-seo.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getDefaultPortalSeo } from "@/lib/portal/seo";
-
-describe("portal seo", () => {
-  it("returns defaults", () => {
-    expect(getDefaultPortalSeo()).toHaveProperty("title");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-seo.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/seo'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getDefaultPortalSeo() {
-  return { title: "反馈中心" };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-seo.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/seo.ts app/(dashboard)/settings/portal-seo/page.tsx app/portal/page.tsx tests/lib/portal-seo.test.ts
-
-git commit -m "feat: add portal seo config"
-```
-
----
-
-### Task 12: Multilingual Portal Settings
-
-**Files:**
-- Create: `lib/portal/i18n.ts`
-- Create: `app/(dashboard)/settings/portal-languages/page.tsx`
-- Modify: `app/portal/page.tsx`
-- Test: `tests/lib/portal-i18n.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getDefaultPortalI18n } from "@/lib/portal/i18n";
-
-describe("portal i18n", () => {
-  it("returns default locale", () => {
-    expect(getDefaultPortalI18n().defaultLocale).toBe("en");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-i18n.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/i18n'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getDefaultPortalI18n() {
-  return { defaultLocale: "en", supportedLocales: ["en", "zh-CN"] };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-i18n.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/i18n.ts app/(dashboard)/settings/portal-languages/page.tsx app/portal/page.tsx tests/lib/portal-i18n.test.ts
-
-git commit -m "feat: add portal language settings"
-```
-
----
-
-### Task 13: Portal Module Toggle (Disable Feedback View)
-
-**Files:**
-- Create: `lib/portal/modules.ts`
-- Modify: `app/portal/page.tsx`
-- Test: `tests/lib/portal-modules.test.ts`
-
-**Step 1: Write the failing test**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { getDefaultPortalModules } from "@/lib/portal/modules";
-
-describe("portal modules", () => {
-  it("enables feedback module by default", () => {
-    expect(getDefaultPortalModules().feedback).toBe(true);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/portal-modules.test.ts`
-Expected: FAIL with "Cannot find module '@/lib/portal/modules'"
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function getDefaultPortalModules() {
-  return { feedback: true, roadmap: true, changelog: true, help: true };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/portal-modules.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add lib/portal/modules.ts app/portal/page.tsx tests/lib/portal-modules.test.ts
-
-git commit -m "feat: add portal module toggles"
-```