@nexttylabs/echo 0.2.0

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

@@ -0,0 +1,266 @@
+# 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

@@ -0,0 +1,207 @@
+# 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

@@ -0,0 +1,186 @@
+# 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"
+```