@nexttylabs/echo 0.3.0 → 0.5.0

package/docs/plans/2026-01-03-roles-permissions.md

@@ -1,266 +0,0 @@
-# Roles and Permissions Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add a minimal RBAC module with a `customer` role and keep user schema and validation aligned with the role model.
-
-**Architecture:** Implement a pure RBAC helper module in `lib/auth/permissions.ts`, update Drizzle `user` table schema to include a `role` column with default `customer`, and add a Zod role schema in `lib/validations/auth.ts`. Cover behavior with focused bun tests.
-
-**Tech Stack:** Next.js, TypeScript, Bun test runner, Drizzle ORM, Zod.
-
-### Task 1: Permissions tests
-
-**Files:**
-- Create: `tests/lib/permissions.test.ts`
-
-**Step 1: Write the failing test**
-
-```typescript
-import { describe, expect, it } from "bun:test";
-import {
-  PERMISSIONS,
-  ROLE_PERMISSIONS,
-  hasPermission,
-  canSubmitOnBehalf,
-} from "@/lib/auth/permissions";
-
-describe("permissions", () => {
-  it("maps roles to expected permissions", () => {
-    expect(ROLE_PERMISSIONS.admin).toEqual(
-      expect.arrayContaining([
-        PERMISSIONS.CREATE_FEEDBACK,
-        PERMISSIONS.SUBMIT_ON_BEHALF,
-        PERMISSIONS.DELETE_FEEDBACK,
-        PERMISSIONS.MANAGE_ORG,
-      ]),
-    );
-
-    expect(ROLE_PERMISSIONS.product_manager).toEqual(
-      expect.arrayContaining([
-        PERMISSIONS.CREATE_FEEDBACK,
-        PERMISSIONS.SUBMIT_ON_BEHALF,
-        PERMISSIONS.DELETE_FEEDBACK,
-      ]),
-    );
-
-    expect(ROLE_PERMISSIONS.developer).toEqual(
-      expect.arrayContaining([PERMISSIONS.CREATE_FEEDBACK]),
-    );
-
-    expect(ROLE_PERMISSIONS.customer_support).toEqual(
-      expect.arrayContaining([
-        PERMISSIONS.CREATE_FEEDBACK,
-        PERMISSIONS.SUBMIT_ON_BEHALF,
-      ]),
-    );
-
-    expect(ROLE_PERMISSIONS.customer).toEqual(
-      expect.arrayContaining([PERMISSIONS.CREATE_FEEDBACK]),
-    );
-  });
-
-  it("checks permissions by role", () => {
-    expect(hasPermission("admin", PERMISSIONS.MANAGE_ORG)).toBe(true);
-    expect(hasPermission("developer", PERMISSIONS.DELETE_FEEDBACK)).toBe(false);
-    expect(hasPermission("customer", PERMISSIONS.CREATE_FEEDBACK)).toBe(true);
-  });
-
-  it("checks submit-on-behalf permission", () => {
-    expect(canSubmitOnBehalf("customer_support")).toBe(true);
-    expect(canSubmitOnBehalf("customer")).toBe(false);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/permissions.test.ts`
-Expected: FAIL because `@/lib/auth/permissions` does not exist.
-
-**Step 3: Commit**
-
-```bash
-git add tests/lib/permissions.test.ts
-git commit -m "test: add permissions coverage"
-```
-
-### Task 2: Implement permissions module
-
-**Files:**
-- Create: `lib/auth/permissions.ts`
-
-**Step 1: Write minimal implementation**
-
-```typescript
-export type UserRole =
-  | "admin"
-  | "product_manager"
-  | "developer"
-  | "customer_support"
-  | "customer";
-
-export const PERMISSIONS = {
-  CREATE_FEEDBACK: "create_feedback",
-  SUBMIT_ON_BEHALF: "submit_on_behalf",
-  DELETE_FEEDBACK: "delete_feedback",
-  MANAGE_ORG: "manage_org",
-} as const;
-
-export type Permission = (typeof PERMISSIONS)[keyof typeof PERMISSIONS];
-
-export const ROLE_PERMISSIONS: Record<UserRole, Permission[]> = {
-  admin: [
-    PERMISSIONS.CREATE_FEEDBACK,
-    PERMISSIONS.SUBMIT_ON_BEHALF,
-    PERMISSIONS.DELETE_FEEDBACK,
-    PERMISSIONS.MANAGE_ORG,
-  ],
-  product_manager: [
-    PERMISSIONS.CREATE_FEEDBACK,
-    PERMISSIONS.SUBMIT_ON_BEHALF,
-    PERMISSIONS.DELETE_FEEDBACK,
-  ],
-  developer: [PERMISSIONS.CREATE_FEEDBACK],
-  customer_support: [
-    PERMISSIONS.CREATE_FEEDBACK,
-    PERMISSIONS.SUBMIT_ON_BEHALF,
-  ],
-  customer: [PERMISSIONS.CREATE_FEEDBACK],
-};
-
-export function hasPermission(role: UserRole, permission: Permission): boolean {
-  return ROLE_PERMISSIONS[role]?.includes(permission) ?? false;
-}
-
-export function canSubmitOnBehalf(role: UserRole): boolean {
-  return hasPermission(role, PERMISSIONS.SUBMIT_ON_BEHALF);
-}
-```
-
-**Step 2: Run test to verify it passes**
-
-Run: `bun test tests/lib/permissions.test.ts`
-Expected: PASS
-
-**Step 3: Commit**
-
-```bash
-git add lib/auth/permissions.ts
-git commit -m "feat: add rbac permissions module"
-```
-
-### Task 3: Role validation
-
-**Files:**
-- Create: `tests/lib/user-role-schema.test.ts`
-- Modify: `lib/validations/auth.ts`
-
-**Step 1: Write the failing test**
-
-```typescript
-import { describe, expect, it } from "bun:test";
-import { userRoleSchema } from "@/lib/validations/auth";
-
-describe("userRoleSchema", () => {
-  it("accepts known roles", () => {
-    expect(userRoleSchema.safeParse("customer").success).toBe(true);
-    expect(userRoleSchema.safeParse("admin").success).toBe(true);
-    expect(userRoleSchema.safeParse("product_manager").success).toBe(true);
-    expect(userRoleSchema.safeParse("developer").success).toBe(true);
-    expect(userRoleSchema.safeParse("customer_support").success).toBe(true);
-  });
-
-  it("rejects unknown roles", () => {
-    expect(userRoleSchema.safeParse("guest").success).toBe(false);
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/user-role-schema.test.ts`
-Expected: FAIL because `userRoleSchema` is missing.
-
-**Step 3: Write minimal implementation**
-
-```typescript
-import { z } from "zod";
-
-export const userRoleSchema = z.enum([
-  "admin",
-  "product_manager",
-  "developer",
-  "customer_support",
-  "customer",
-]);
-
-export type UserRoleInput = z.infer<typeof userRoleSchema>;
-```
-
-(Add the above to `lib/validations/auth.ts` while keeping existing schemas.)
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/user-role-schema.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add tests/lib/user-role-schema.test.ts lib/validations/auth.ts
-git commit -m "feat: add user role validation"
-```
-
-### Task 4: User schema role column
-
-**Files:**
-- Create: `tests/lib/user-schema.test.ts`
-- Modify: `lib/db/schema/auth.ts`
-
-**Step 1: Write the failing test**
-
-```typescript
-import { describe, expect, it } from "bun:test";
-import { user } from "@/lib/db/schema";
-
-describe("user schema", () => {
-  it("includes role column", () => {
-    expect(user.role).toBeDefined();
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/lib/user-schema.test.ts`
-Expected: FAIL because `user.role` is undefined.
-
-**Step 3: Write minimal implementation**
-
-```typescript
-role: text("role").notNull().default("customer"),
-```
-
-(Add to `lib/db/schema/auth.ts` in the `user` table definition.)
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/lib/user-schema.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add tests/lib/user-schema.test.ts lib/db/schema/auth.ts
-git commit -m "feat: add user role column"
-```
-
----
-
-**Plan complete and saved to `docs/plans/2026-01-03-roles-permissions.md`. Two execution options:**
-
-**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration
-
-**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints
-
-**Which approach?**

package/docs/plans/2026-01-05-authentication-middleware.md

@@ -1,207 +0,0 @@
-# Authentication Middleware Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add session-aware auth guarding in Next.js middleware so `/dashboard` and `/feedback` require login while `/login`, `/register`, `/invite/*`, and `/api/auth/*` stay public, without breaking existing request-id/logging behavior.
-
-**Architecture:** Keep the current global middleware (for `x-request-id` and request logging) and add a protected-route check inside it. Implement a small `getServerSession` helper that wraps `better-auth`’s `auth.api.getSession({ headers })` so middleware can request session data from `NextRequest` headers. Only protected routes trigger session checks; public routes pass through.
-
-**Tech Stack:** Next.js App Router middleware, TypeScript, better-auth, Bun test runner.
-
-### Task 1: Add middleware auth behavior tests (failing first)
-
-**Files:**
-- Modify: `middleware.test.ts`
-
-**Step 1: Write the failing tests**
-
-Add tests that cover:
-- Protected route unauthenticated → redirect to `/login`
-- Public route unauthenticated → allowed
-- Protected route authenticated → allowed
-
-```ts
-import { describe, it, expect, mock } from "bun:test";
-import { NextRequest } from "next/server";
-
-mock.module("@/lib/auth/session", () => ({
-  getServerSession: async (req: NextRequest) => {
-    const isAuthed = req.headers.get("x-test-auth") === "1";
-    return isAuthed ? { user: { id: "u_test" } } : null;
-  },
-}));
-
-const { middleware } = await import("./middleware");
-
-describe("middleware auth", () => {
-  it("redirects unauthenticated users from protected routes", async () => {
-    const req = new NextRequest("http://localhost/dashboard");
-    const res = await middleware(req);
-    expect(res.headers.get("location")).toBe("http://localhost/login");
-  });
-
-  it("allows unauthenticated users on public routes", async () => {
-    const req = new NextRequest("http://localhost/login");
-    const res = await middleware(req);
-    expect(res.headers.get("location")).toBeNull();
-  });
-
-  it("allows authenticated users on protected routes", async () => {
-    const req = new NextRequest("http://localhost/dashboard", {
-      headers: { "x-test-auth": "1" },
-    });
-    const res = await middleware(req);
-    expect(res.headers.get("location")).toBeNull();
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test middleware.test.ts`
-Expected: FAIL because middleware does not yet enforce auth redirect.
-
-**Step 3: Commit**
-
-```bash
-git add middleware.test.ts
-git commit -m "test: cover auth redirect behavior in middleware"
-```
-
-### Task 2: Implement getServerSession helper
-
-**Files:**
-- Create: `lib/auth/session.ts`
-
-**Step 1: Write the failing test (optional if skipping unit test)**
-
-If adding a unit test, create `tests/auth/session.test.ts` verifying `getServerSession` returns `null` when no session is found. Otherwise, proceed to implementation and rely on middleware tests.
-
-**Step 2: Run test to verify it fails**
-
-Run (if test added): `bun test tests/auth/session.test.ts`
-Expected: FAIL because helper does not exist.
-
-**Step 3: Write minimal implementation**
-
-```ts
-import type { NextRequest } from "next/server";
-import { auth } from "@/lib/auth/config";
-
-export async function getServerSession(req: NextRequest) {
-  return auth.api.getSession({ headers: req.headers });
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/auth/session.test.ts`
-Expected: PASS (if test added).
-
-**Step 5: Commit**
-
-```bash
-git add lib/auth/session.ts tests/auth/session.test.ts
-git commit -m "feat: add getServerSession helper for middleware"
-```
-
-### Task 3: Enforce authentication in middleware
-
-**Files:**
-- Modify: `middleware.ts`
-
-**Step 1: Write the failing test (already in Task 1)**
-
-Use the tests from Task 1; they should still be failing.
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test middleware.test.ts`
-Expected: FAIL because `/dashboard` is not redirected yet.
-
-**Step 3: Write minimal implementation**
-
-Update middleware to:
-- Define `publicRoutes` and `protectedRoutes` lists
-- Skip session check for public routes
-- For protected routes, call `getServerSession(req)` and redirect if falsy
-- Preserve existing `x-request-id` and logging behavior
-
-```ts
-import { NextRequest, NextResponse } from "next/server";
-import { generateRequestId } from "@/lib/middleware/request-id";
-import { logRequest, logResponse } from "@/lib/middleware/request-logger";
-import { getServerSession } from "@/lib/auth/session";
-
-const publicRoutes = ["/login", "/register", "/invite", "/invite/", "/api/auth"];
-const protectedRoutes = ["/dashboard", "/feedback"];
-
-function isRouteMatch(pathname: string, routes: string[]) {
-  return routes.some((route) => pathname === route || pathname.startsWith(route));
-}
-
-export async function middleware(req: NextRequest) {
-  const startTime = Date.now();
-  const reqId = req.headers.get("x-request-id") || generateRequestId();
-
-  const requestHeaders = new Headers(req.headers);
-  requestHeaders.set("x-request-id", reqId);
-
-  logRequest(new Request(req.url, { method: req.method, headers: requestHeaders }));
-
-  const pathname = req.nextUrl.pathname;
-  const isPublic = isRouteMatch(pathname, publicRoutes);
-  const isProtected = isRouteMatch(pathname, protectedRoutes);
-
-  let response = NextResponse.next({
-    request: {
-      headers: requestHeaders,
-    },
-  });
-
-  if (isProtected && !isPublic) {
-    const session = await getServerSession(req);
-    if (!session) {
-      response = NextResponse.redirect(new URL("/login", req.url));
-    }
-  }
-
-  response.headers.set("x-request-id", reqId);
-  const duration = Date.now() - startTime;
-  logResponse(reqId, response.status, duration);
-
-  return response;
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test middleware.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add middleware.ts
-git commit -m "feat: enforce auth on protected routes in middleware"
-```
-
-### Task 4: Full validation
-
-**Files:**
-- None
-
-**Step 1: Run lint and tests**
-
-Run: `bun run lint`
-Expected: PASS
-
-Run: `bun test`
-Expected: PASS
-
-**Step 2: Commit (if any fixes were made)**
-
-```bash
-git add .
-git commit -m "chore: fix lint/test issues"
-```

package/docs/plans/2026-01-05-member-removal.md

@@ -1,186 +0,0 @@
-# Member Removal Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Allow organization admins to remove members while preventing removal of the last admin or self-removal.
-
-**Architecture:** Add a DELETE handler using the existing build*Handler pattern and Drizzle queries for role checks and deletion. Render a server-fetched members list in the org settings page, and use a client component with a confirmation dialog to call the DELETE API and update local state.
-
-**Tech Stack:** Next.js App Router (RSC), TypeScript, Drizzle ORM, Bun test runner, shadcn/ui components.
-
-### Task 1: Add member removal API (handler + route)
-
-**Files:**
-- Create: `app/api/organizations/[orgId]/members/[memberId]/handler.ts`
-- Create: `app/api/organizations/[orgId]/members/[memberId]/route.ts`
-- Test: `tests/api/organization-members.test.ts`
-
-**Step 1: Write the failing tests**
-
-```ts
-import { describe, expect, it } from "bun:test";
-import { buildRemoveMemberHandler } from "@/app/api/organizations/[orgId]/members/[memberId]/handler";
-import { organizationMembers } from "@/lib/db/schema";
-
-// Tests:
-// - 401 when unauthenticated
-// - 403 when requester is not admin
-// - 404 when target member not found
-// - 400 when target is last admin (message: 组织至少需要一个管理员)
-// - 400 when requester tries to remove self (message: 不能移除自己)
-// - 200 on success and delete called
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `bun test tests/api/organization-members.test.ts`
-Expected: FAIL with "buildRemoveMemberHandler is not defined" (or module not found).
-
-**Step 3: Write minimal implementation**
-
-```ts
-export function buildRemoveMemberHandler(deps: RemoveMemberDeps) {
-  return async function DELETE(req: Request, context: { params: { orgId: string; memberId: string } }) {
-    const session = await deps.auth.api.getSession({ headers: req.headers });
-    if (!session) return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
-
-    const { orgId, memberId } = await Promise.resolve(context.params);
-
-    if (memberId === session.user.id) {
-      return NextResponse.json({ error: "不能移除自己" }, { status: 400 });
-    }
-
-    const [requester] = await deps.db
-      .select()
-      .from(organizationMembers)
-      .where(and(eq(organizationMembers.organizationId, orgId), eq(organizationMembers.userId, session.user.id)))
-      .limit(1);
-
-    if (!requester || requester.role !== "admin") {
-      return NextResponse.json({ error: "Forbidden" }, { status: 403 });
-    }
-
-    const [target] = await deps.db
-      .select()
-      .from(organizationMembers)
-      .where(and(eq(organizationMembers.organizationId, orgId), eq(organizationMembers.userId, memberId)))
-      .limit(1);
-
-    if (!target) {
-      return NextResponse.json({ error: "Member not found" }, { status: 404 });
-    }
-
-    const [adminCount] = await deps.db
-      .select({ count: count() })
-      .from(organizationMembers)
-      .where(and(eq(organizationMembers.organizationId, orgId), eq(organizationMembers.role, "admin")));
-
-    if (target.role === "admin" && adminCount.count === 1) {
-      return NextResponse.json({ error: "组织至少需要一个管理员" }, { status: 400 });
-    }
-
-    await deps.db
-      .delete(organizationMembers)
-      .where(and(eq(organizationMembers.organizationId, orgId), eq(organizationMembers.userId, memberId)));
-
-    return NextResponse.json({ message: "成员已移除" }, { status: 200 });
-  };
-}
-```
-
-**Step 4: Run test to verify it passes**
-
-Run: `bun test tests/api/organization-members.test.ts`
-Expected: PASS
-
-**Step 5: Commit**
-
-```bash
-git add app/api/organizations/[orgId]/members/[memberId]/handler.ts app/api/organizations/[orgId]/members/[memberId]/route.ts tests/api/organization-members.test.ts
-git commit -m "feat: add member removal API"
-```
-
-### Task 2: Render member list and removal UI
-
-**Files:**
-- Modify: `app/(dashboard)/settings/organizations/[orgId]/members/page.tsx`
-- Create: `components/settings/organization-members-list.tsx`
-
-**Step 1: Add a server-side members query**
-
-```ts
-const members = db
-  ? await db
-      .select({
-        userId: organizationMembers.userId,
-        role: organizationMembers.role,
-        name: user.name,
-        email: user.email,
-      })
-      .from(organizationMembers)
-      .leftJoin(user, eq(user.id, organizationMembers.userId))
-      .where(eq(organizationMembers.organizationId, params.orgId))
-  : [];
-```
-
-**Step 2: Implement client list with removal**
-
-```tsx
-<AlertDialog>
-  <AlertDialogTrigger asChild>
-    <Button variant="destructive">移除</Button>
-  </AlertDialogTrigger>
-  <AlertDialogContent>
-    <AlertDialogTitle>确认移除？</AlertDialogTitle>
-    <AlertDialogAction onClick={() => removeMember(member.userId)}>确认</AlertDialogAction>
-  </AlertDialogContent>
-</AlertDialog>
-```
-
-**Step 3: Disable remove for self**
-
-```ts
-const isSelf = member.userId === currentUserId;
-<Button disabled={isSelf}>移除</Button>
-```
-
-**Step 4: Run UI smoke check**
-
-Run: `bun dev`
-Expected: Members page shows list, remove button opens confirmation, success removes row from UI.
-
-**Step 5: Commit**
-
-```bash
-git add app/(dashboard)/settings/organizations/[orgId]/members/page.tsx components/settings/organization-members-list.tsx
-git commit -m "feat: render members list with removal UI"
-```
-
-### Task 3: Edge cases + validation
-
-**Files:**
-- Modify: `tests/api/organization-members.test.ts`
-
-**Step 1: Add edge-case tests (self-removal + missing member)**
-
-```ts
-it("rejects removing self", async () => {
-  // expect 400 "不能移除自己"
-});
-
-it("returns 404 when target member missing", async () => {
-  // expect 404
-});
-```
-
-**Step 2: Run test suite**
-
-Run: `bun test tests/api/organization-members.test.ts`
-Expected: PASS
-
-**Step 3: Commit**
-
-```bash
-git add tests/api/organization-members.test.ts
-git commit -m "test: cover member removal edge cases"
-```