feat: rebuild workspaces as the reference plugin

plugins/workspaces/tests/backend/activate.test.ts

@@ -0,0 +1,76 @@
+import { afterEach, describe, expect, it } from "vitest";
+import express from "express";
+import {
+  createMockCtx,
+  createTestDb,
+  type TestDb,
+} from "@termix/plugin-sdk/testing";
+import { PluginCapabilityError } from "@termix/plugin-sdk/backend";
+import { activate } from "../../src/backend/index.js";
+import { manifest, pluginDir, startServer, type TestServer } from "./helpers";
+
+let db: TestDb | null = null;
+let server: TestServer | null = null;
+
+afterEach(async () => {
+  db?.close();
+  db = null;
+  await server?.close();
+  server = null;
+});
+
+describe("workspaces activate", () => {
+  it("registers a sync entity that leaves the per-install last session out", async () => {
+    server = await startServer();
+    const [entity] = server.mock.syncEntities;
+    expect(entity.type).toBe("workspaces");
+    expect(entity.shouldSync?.({ kind: "manual" })).toBe(true);
+    expect(entity.shouldSync?.({ kind: "last_session" })).toBe(false);
+  });
+
+  it("offers the user's manual workspaces as a service", async () => {
+    server = await startServer();
+    await server.request("POST", "/", {
+      body: { name: "Prod", payload: { version: 1, tabs: [] } },
+    });
+    await server.request("PUT", "/last-session", {
+      body: { payload: { version: 1, tabs: [] } },
+    });
+
+    const service = server.mock.services.get("workspaces.saved") as {
+      list: () => Promise<unknown>;
+    };
+    const listed = await server.mock.ctx.asUser("user-1", () => service.list());
+    expect(listed).toEqual([
+      { id: expect.any(Number), name: "Prod", isDefault: false },
+    ]);
+  });
+
+  it("fails closed without db:own", async () => {
+    db = await createTestDb(pluginDir);
+    const mock = createMockCtx({
+      pluginId: manifest.id,
+      manifest,
+      capabilities: ["network:serve", "ui:surface"],
+      db: db.database,
+      router: () => express.Router(),
+    });
+    await expect(activate(mock.ctx)).rejects.toBeInstanceOf(
+      PluginCapabilityError,
+    );
+  });
+
+  it("fails closed without network:serve", async () => {
+    db = await createTestDb(pluginDir);
+    const mock = createMockCtx({
+      pluginId: manifest.id,
+      manifest,
+      capabilities: ["db:own", "ui:surface"],
+      db: db.database,
+      router: () => express.Router(),
+    });
+    await expect(activate(mock.ctx)).rejects.toBeInstanceOf(
+      PluginCapabilityError,
+    );
+  });
+});

plugins/workspaces/tests/backend/helpers.ts

@@ -0,0 +1,103 @@
+import http from "node:http";
+import type { AddressInfo } from "node:net";
+import { fileURLToPath } from "node:url";
+import express, { type Router } from "express";
+import {
+  createMockCtx,
+  createTestDb,
+  type MockPluginContext,
+  type TestDb,
+} from "@termix/plugin-sdk/testing";
+import type { PluginManifest } from "@termix/plugin-sdk/manifest";
+import manifestJson from "../../manifest.json";
+
+export const pluginDir = fileURLToPath(new URL("../..", import.meta.url));
+export const manifest = manifestJson as unknown as PluginManifest;
+
+export interface TestServer {
+  db: TestDb;
+  mock: MockPluginContext;
+  request: (
+    method: string,
+    path: string,
+    options?: { user?: string; body?: unknown },
+    // Route bodies vary per test; asserting on them is the point.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ) => Promise<{ status: number; body: any }>;
+  close: () => Promise<void>;
+}
+
+/**
+ * The plugin activated against a real in-memory database, its router mounted
+ * on an express app the way core mounts it: JSON parsed, the acting user set
+ * from the request, everything else left to the plugin.
+ */
+export async function startServer(
+  options: { permissions?: string[]; users?: string[] } = {},
+): Promise<TestServer> {
+  const db = await createTestDb(pluginDir);
+  for (const user of options.users ?? ["user-1", "user-2"]) {
+    db.sqlite
+      .prepare("INSERT INTO users (id, username) VALUES (?, ?)")
+      .run(user, user);
+  }
+
+  let router: Router | null = null;
+  const mock = createMockCtx({
+    pluginId: manifest.id,
+    manifest,
+    capabilities: manifest.capabilities,
+    db: db.database,
+    router: () => (router = express.Router()),
+    permissions: options.permissions ?? ["workspaces.use"],
+  });
+
+  const { activate } = await import("../../src/backend/index.js");
+  await activate(mock.ctx);
+
+  const app = express();
+  app.use(express.json());
+  app.use((req, _res, next) => {
+    mock.setActor(req.header("x-test-user") ?? undefined);
+    next();
+  });
+  app.use((req, res, next) => router!(req, res, next));
+
+  const server = http.createServer(app);
+  await new Promise<void>((resolve) => server.listen(0, resolve));
+  const { port } = server.address() as AddressInfo;
+
+  return {
+    db,
+    mock,
+    async request(method, path, { user = "user-1", body: given } = {}) {
+      const body = method === "GET" ? undefined : given;
+      const response = await fetch(`http://127.0.0.1:${port}${path}`, {
+        method,
+        headers: {
+          "x-test-user": user,
+          ...(body !== undefined ? { "content-type": "application/json" } : {}),
+        },
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+      });
+      const text = await response.text();
+      return { status: response.status, body: text ? JSON.parse(text) : null };
+    },
+    async close() {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+      db.close();
+    },
+  };
+}
+
+export const layout = (
+  tabs: unknown[] = [{ slotId: "a", type: "terminal" }],
+) => ({
+  version: 1,
+  tabs,
+  activeSlotId: null,
+  splitMode: "none",
+  paneTabIds: [],
+  rowSizes: [],
+  rowColSizes: [],
+});

plugins/workspaces/tests/backend/migrations.test.ts

@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { createTestDb, type TestDb } from "@termix/plugin-sdk/testing";
+import { pluginDir } from "./helpers";
+
+// user_workspaces as core's SQLite bootstrap created it before 2.9.0, plus the
+// index performance-indexes.ts added.
+const LEGACY_DDL = `
+  CREATE TABLE user_workspaces (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name TEXT NOT NULL,
+    color TEXT,
+    icon TEXT,
+    kind TEXT NOT NULL DEFAULT 'manual',
+    is_default INTEGER NOT NULL DEFAULT 0,
+    payload TEXT NOT NULL DEFAULT '{}',
+    sync_id TEXT UNIQUE,
+    created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    last_used_at TEXT
+  );
+  CREATE INDEX idx_user_workspaces_user_id ON user_workspaces (user_id);
+`;
+
+let db: TestDb | null = null;
+
+afterEach(() => {
+  db?.close();
+  db = null;
+});
+
+const tableExists = (name: string) =>
+  !!db!.sqlite
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = ?")
+    .get(name);
+
+const indexOn = (table: string) =>
+  (
+    db!.sqlite
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = ? AND name NOT LIKE 'sqlite_%'",
+      )
+      .all(table) as { name: string }[]
+  ).map((row) => row.name);
+
+describe("adopting user_workspaces", () => {
+  it("keeps every existing row when the legacy table is there", async () => {
+    db = await createTestDb(pluginDir, {
+      before: (sqlite) => {
+        sqlite.exec("INSERT INTO users (id) VALUES ('user-1'), ('user-2')");
+        sqlite.exec(LEGACY_DDL);
+        sqlite
+          .prepare(
+            "INSERT INTO user_workspaces (user_id, name, kind, is_default, payload, sync_id, last_used_at) VALUES (?, ?, ?, ?, ?, ?, ?)",
+          )
+          .run(
+            "user-1",
+            "Prod",
+            "manual",
+            1,
+            '{"version":1,"tabs":[{"type":"terminal"}]}',
+            "sync-a",
+            "2026-01-01T00:00:00.000Z",
+          );
+        sqlite
+          .prepare(
+            "INSERT INTO user_workspaces (user_id, name, kind, payload, sync_id) VALUES (?, ?, ?, ?, ?)",
+          )
+          .run("user-2", "Last Session", "last_session", "{}", "sync-b");
+      },
+    });
+
+    expect(db.applied).toEqual(["0001_adopt_user_workspaces"]);
+    expect(tableExists("user_workspaces")).toBe(false);
+    expect(tableExists("p_workspaces_workspaces")).toBe(true);
+
+    const rows = db.sqlite
+      .prepare(
+        "SELECT user_id, name, kind, is_default, payload, sync_id, last_used_at FROM p_workspaces_workspaces ORDER BY id",
+      )
+      .all();
+    expect(rows).toEqual([
+      {
+        user_id: "user-1",
+        name: "Prod",
+        kind: "manual",
+        is_default: 1,
+        payload: '{"version":1,"tabs":[{"type":"terminal"}]}',
+        sync_id: "sync-a",
+        last_used_at: "2026-01-01T00:00:00.000Z",
+      },
+      {
+        user_id: "user-2",
+        name: "Last Session",
+        kind: "last_session",
+        is_default: 0,
+        payload: "{}",
+        sync_id: "sync-b",
+        last_used_at: null,
+      },
+    ]);
+    expect(indexOn("p_workspaces_workspaces")).toEqual([
+      "idx_user_workspaces_user_id",
+    ]);
+  });
+
+  it("creates the table fresh when there is no legacy one", async () => {
+    db = await createTestDb(pluginDir);
+
+    expect(tableExists("user_workspaces")).toBe(false);
+    expect(tableExists("p_workspaces_workspaces")).toBe(true);
+    expect(indexOn("p_workspaces_workspaces")).toEqual([
+      "idx_user_workspaces_user_id",
+    ]);
+    expect(
+      db.sqlite.prepare("SELECT * FROM p_workspaces_workspaces").all(),
+    ).toEqual([]);
+  });
+
+  it("removes a user's workspaces when the user is deleted", async () => {
+    db = await createTestDb(pluginDir, {
+      before: (sqlite) => {
+        sqlite.exec("INSERT INTO users (id) VALUES ('user-1'), ('user-2')");
+      },
+    });
+    const insert = db.sqlite.prepare(
+      "INSERT INTO p_workspaces_workspaces (user_id, name) VALUES (?, ?)",
+    );
+    insert.run("user-1", "Mine");
+    insert.run("user-2", "Theirs");
+
+    db.sqlite.exec("DELETE FROM users WHERE id = 'user-1'");
+
+    const names = (
+      db.sqlite.prepare("SELECT name FROM p_workspaces_workspaces").all() as {
+        name: string;
+      }[]
+    ).map((row) => row.name);
+    expect(names).toEqual(["Theirs"]);
+  });
+});

plugins/workspaces/tests/backend/repositories/workspace-repository.test.ts

@@ -1,204 +0,0 @@
-import { afterEach, describe, expect, it } from "vitest";
-import { TestSqliteDatabase } from "../../../../../src/backend/tests/database/repositories/test-support.js";
-import { WorkspaceRepository } from "../../../../../src/backend/database/repositories/workspace-repository.js";
-
-describe("WorkspaceRepository", () => {
-  let adapter: TestSqliteDatabase | null = null;
-
-  afterEach(async () => {
-    if (adapter) {
-      await adapter.close();
-      adapter = null;
-    }
-  });
-
-  async function createRepository(
-    onWrite?: () => void | Promise<void>,
-  ): Promise<WorkspaceRepository> {
-    adapter = new TestSqliteDatabase();
-    const context = await adapter.connect();
-    await adapter.exec(`
-      INSERT INTO users (id, username, password_hash)
-      VALUES ('user-1', 'alice', 'hash'), ('user-2', 'bob', 'hash');
-    `);
-
-    return new WorkspaceRepository(context, onWrite);
-  }
-
-  it("creates and lists manual workspaces scoped to the owning user", async () => {
-    const repo = await createRepository();
-
-    await repo.create("user-1", { name: "Prod Debugging", payload: "{}" });
-    await repo.create("user-2", { name: "Other user's", payload: "{}" });
-
-    const list = await repo.listByUser("user-1");
-    expect(list).toHaveLength(1);
-    expect(list[0]).toMatchObject({
-      userId: "user-1",
-      name: "Prod Debugging",
-      kind: "manual",
-      isDefault: false,
-    });
-    expect(list[0].syncId).toBeTruthy();
-  });
-
-  it("finds a workspace by id scoped to the owner", async () => {
-    const repo = await createRepository();
-    const created = await repo.create("user-1", {
-      name: "Test A",
-      payload: "{}",
-    });
-
-    expect(await repo.findById("user-1", created.id)).toMatchObject({
-      id: created.id,
-    });
-    expect(await repo.findById("user-2", created.id)).toBeNull();
-  });
-
-  it("upsertLastSession creates then updates a single row, never a second one", async () => {
-    const repo = await createRepository();
-
-    const first = await repo.upsertLastSession("user-1", '{"tabs":[]}');
-    expect(first.kind).toBe("last_session");
-
-    const second = await repo.upsertLastSession(
-      "user-1",
-      '{"tabs":[{"slotId":"a"}]}',
-    );
-    expect(second.id).toBe(first.id);
-    expect(second.payload).toBe('{"tabs":[{"slotId":"a"}]}');
-
-    const all = await repo.listByUser("user-1");
-    expect(all.filter((w) => w.kind === "last_session")).toHaveLength(1);
-  });
-
-  it("update renames/recolors a manual workspace but rejects last_session", async () => {
-    const repo = await createRepository();
-    const manual = await repo.create("user-1", {
-      name: "Old Name",
-      payload: "{}",
-    });
-    const lastSession = await repo.upsertLastSession("user-1", "{}");
-
-    const updated = await repo.update("user-1", manual.id, {
-      name: "New Name",
-      color: "#fff",
-    });
-    expect(updated).toMatchObject({ name: "New Name", color: "#fff" });
-
-    const rejected = await repo.update("user-1", lastSession.id, {
-      name: "Should not work",
-    });
-    expect(rejected).toBeNull();
-  });
-
-  it("updateContent overwrites payload for a manual workspace but rejects last_session", async () => {
-    const repo = await createRepository();
-    const manual = await repo.create("user-1", {
-      name: "Test A",
-      payload: "{}",
-    });
-    const lastSession = await repo.upsertLastSession("user-1", "{}");
-
-    const updated = await repo.updateContent(
-      "user-1",
-      manual.id,
-      '{"tabs":[1]}',
-    );
-    expect(updated?.payload).toBe('{"tabs":[1]}');
-
-    const rejected = await repo.updateContent(
-      "user-1",
-      lastSession.id,
-      '{"tabs":[2]}',
-    );
-    expect(rejected).toBeNull();
-  });
-
-  it("setDefault clears any prior default and rejects last_session", async () => {
-    const repo = await createRepository();
-    const a = await repo.create("user-1", { name: "A", payload: "{}" });
-    const b = await repo.create("user-1", { name: "B", payload: "{}" });
-    const lastSession = await repo.upsertLastSession("user-1", "{}");
-
-    await repo.setDefault("user-1", a.id);
-    expect((await repo.findById("user-1", a.id))?.isDefault).toBe(true);
-
-    await repo.setDefault("user-1", b.id);
-    expect((await repo.findById("user-1", a.id))?.isDefault).toBe(false);
-    expect((await repo.findById("user-1", b.id))?.isDefault).toBe(true);
-
-    const rejected = await repo.setDefault("user-1", lastSession.id);
-    expect(rejected).toBeNull();
-  });
-
-  it("unsetDefault clears isDefault on a manual workspace and rejects last_session", async () => {
-    const repo = await createRepository();
-    const a = await repo.create("user-1", { name: "A", payload: "{}" });
-    const lastSession = await repo.upsertLastSession("user-1", "{}");
-
-    await repo.setDefault("user-1", a.id);
-    expect((await repo.findById("user-1", a.id))?.isDefault).toBe(true);
-
-    await repo.unsetDefault("user-1", a.id);
-    expect((await repo.findById("user-1", a.id))?.isDefault).toBe(false);
-
-    const rejected = await repo.unsetDefault("user-1", lastSession.id);
-    expect(rejected).toBeNull();
-  });
-
-  it("touchLastUsed sets lastUsedAt", async () => {
-    const repo = await createRepository();
-    const workspace = await repo.create("user-1", {
-      name: "A",
-      payload: "{}",
-    });
-    expect(workspace.lastUsedAt).toBeNull();
-
-    await repo.touchLastUsed(
-      "user-1",
-      workspace.id,
-      "2026-08-11T00:00:00.000Z",
-    );
-    expect((await repo.findById("user-1", workspace.id))?.lastUsedAt).toBe(
-      "2026-08-11T00:00:00.000Z",
-    );
-  });
-
-  it("delete removes a manual workspace but rejects last_session", async () => {
-    const repo = await createRepository();
-    const manual = await repo.create("user-1", { name: "A", payload: "{}" });
-    const lastSession = await repo.upsertLastSession("user-1", "{}");
-
-    await expect(repo.delete("user-1", lastSession.id)).resolves.toBe(false);
-    await expect(repo.delete("user-1", manual.id)).resolves.toBe(true);
-    expect(await repo.findById("user-1", manual.id)).toBeNull();
-  });
-
-  it("triggers writes on create/update/delete", async () => {
-    let writeCount = 0;
-    const repo = await createRepository(() => {
-      writeCount += 1;
-    });
-
-    const created = await repo.create("user-1", {
-      name: "A",
-      payload: "{}",
-    });
-    await repo.update("user-1", created.id, { name: "B" });
-    await repo.delete("user-1", created.id);
-
-    expect(writeCount).toBe(3);
-  });
-
-  it("deleteByUserId removes every workspace owned by the user", async () => {
-    const repo = await createRepository();
-    await repo.create("user-1", { name: "A", payload: "{}" });
-    await repo.create("user-1", { name: "B", payload: "{}" });
-    await repo.create("user-2", { name: "C", payload: "{}" });
-
-    await expect(repo.deleteByUserId("user-1")).resolves.toBe(2);
-    expect(await repo.listByUser("user-1")).toHaveLength(0);
-    expect(await repo.listByUser("user-2")).toHaveLength(1);
-  });
-});

plugins/workspaces/tests/backend/repository.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createTestDb, type TestDb } from "@termix/plugin-sdk/testing";
+import { workspaces } from "../../src/backend/tables.js";
+import {
+  createWorkspaceRepository,
+  type WorkspaceRepository,
+} from "../../src/backend/repository.js";
+import { pluginDir } from "./helpers";
+
+let db: TestDb;
+let repo: WorkspaceRepository;
+
+beforeEach(async () => {
+  db = await createTestDb(pluginDir, {
+    before: (sqlite) =>
+      sqlite.exec("INSERT INTO users (id) VALUES ('user-1'), ('user-2')"),
+  });
+  repo = createWorkspaceRepository(
+    db.database,
+    await db.database.define(workspaces),
+  );
+});
+
+afterEach(() => db.close());
+
+describe("workspace repository", () => {
+  it("reads a new row back by its own sync id", async () => {
+    const a = await repo.create("user-1", { name: "A", payload: "{}" });
+    const b = await repo.create("user-1", { name: "B", payload: "{}" });
+    expect(a.name).toBe("A");
+    expect(b.name).toBe("B");
+    expect(a.syncId).not.toBe(b.syncId);
+    expect(a.createdAt).toBe(a.updatedAt);
+  });
+
+  it("returns the updated last session rather than a new one", async () => {
+    const first = await repo.upsertLastSession("user-1", '{"tabs":[]}', "t1");
+    const second = await repo.upsertLastSession("user-1", '{"tabs":[1]}', "t2");
+    expect(second.id).toBe(first.id);
+    expect(second.payload).toBe('{"tabs":[1]}');
+    expect(second.updatedAt).toBe("t2");
+  });
+
+  it("switches the default without touching another user's", async () => {
+    const theirs = await repo.create("user-2", { name: "T", payload: "{}" });
+    await repo.setDefault("user-2", theirs.id);
+
+    const a = await repo.create("user-1", { name: "A", payload: "{}" });
+    const b = await repo.create("user-1", { name: "B", payload: "{}" });
+    await repo.setDefault("user-1", a.id);
+    await repo.setDefault("user-1", b.id);
+
+    expect((await repo.findById("user-1", a.id))?.isDefault).toBe(false);
+    expect((await repo.findById("user-1", b.id))?.isDefault).toBe(true);
+    expect((await repo.findById("user-2", theirs.id))?.isDefault).toBe(true);
+  });
+
+  it("refuses to edit or delete the last session", async () => {
+    const last = await repo.upsertLastSession("user-1", "{}");
+    expect(await repo.update("user-1", last.id, { name: "x" })).toBeNull();
+    expect(await repo.setDefault("user-1", last.id)).toBeNull();
+    expect(await repo.delete("user-1", last.id)).toBe(false);
+  });
+});

plugins/workspaces/tests/backend/routes.test.ts

@@ -1,518 +1,203 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import type { Request, Response, Router } from "express";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { layout, startServer, type TestServer } from "./helpers";
 
-type WorkspaceRow = {
-  id: number;
-  userId: string;
-  name: string;
-  color: string | null;
-  icon: string | null;
-  kind: "manual" | "last_session";
-  isDefault: boolean;
-  payload: string;
-  syncId: string;
-  createdAt: string;
-  updatedAt: string;
-  lastUsedAt: string | null;
-};
+let server: TestServer;
 
-const state = vi.hoisted(() => ({
-  currentUserId: "user-1",
-  workspaces: new Map<number, WorkspaceRow>(),
-  nextId: 1,
-}));
-
-vi.mock("../../../../src/backend/database/db/index.js", () => ({ db: {} }));
-
-vi.mock("../../../../src/backend/utils/logger.js", () => ({
-  databaseLogger: {
-    error: vi.fn(),
-    warn: vi.fn(),
-    info: vi.fn(),
-    success: vi.fn(),
-  },
-}));
-
-vi.mock("../../../../src/backend/utils/auth-manager.js", () => ({
-  AuthManager: {
-    getInstance: () => ({
-      createAuthMiddleware:
-        () =>
-        (req: Record<string, unknown>, _res: unknown, next: () => void) => {
-          req.userId = state.currentUserId;
-          next();
-        },
-      createDataAccessMiddleware:
-        () => (_req: unknown, _res: unknown, next: () => void) =>
-          next(),
-    }),
-  },
-}));
-
-function findByIdForUser(userId: string, id: number): WorkspaceRow | null {
-  const row = state.workspaces.get(id);
-  return row && row.userId === userId ? row : null;
-}
-
-vi.mock("../../../../src/backend/database/repositories/factory.js", () => ({
-  createCurrentWorkspaceRepository: () => ({
-    listByUser: async (userId: string) =>
-      [...state.workspaces.values()].filter((w) => w.userId === userId),
-    findById: async (userId: string, id: number) => findByIdForUser(userId, id),
-    findLastSession: async (userId: string) =>
-      [...state.workspaces.values()].find(
-        (w) => w.userId === userId && w.kind === "last_session",
-      ) ?? null,
-    upsertLastSession: async (userId: string, payload: string) => {
-      const existing = [...state.workspaces.values()].find(
-        (w) => w.userId === userId && w.kind === "last_session",
-      );
-      if (existing) {
-        existing.payload = payload;
-        existing.updatedAt = new Date().toISOString();
-        return existing;
-      }
-      const row: WorkspaceRow = {
-        id: state.nextId++,
-        userId,
-        name: "Last Session",
-        color: null,
-        icon: null,
-        kind: "last_session",
-        isDefault: false,
-        payload,
-        syncId: `sync-${state.nextId}`,
-        createdAt: new Date().toISOString(),
-        updatedAt: new Date().toISOString(),
-        lastUsedAt: null,
-      };
-      state.workspaces.set(row.id, row);
-      return row;
-    },
-    create: async (
-      userId: string,
-      input: {
-        name: string;
-        color?: string | null;
-        icon?: string | null;
-        payload: string;
-      },
-    ) => {
-      const row: WorkspaceRow = {
-        id: state.nextId++,
-        userId,
-        name: input.name,
-        color: input.color ?? null,
-        icon: input.icon ?? null,
-        kind: "manual",
-        isDefault: false,
-        payload: input.payload,
-        syncId: `sync-${state.nextId}`,
-        createdAt: new Date().toISOString(),
-        updatedAt: new Date().toISOString(),
-        lastUsedAt: null,
-      };
-      state.workspaces.set(row.id, row);
-      return row;
-    },
-    update: async (
-      userId: string,
-      id: number,
-      input: { name?: string; color?: string | null; icon?: string | null },
-    ) => {
-      const row = findByIdForUser(userId, id);
-      if (!row || row.kind !== "manual") return null;
-      if (input.name !== undefined) row.name = input.name;
-      if (input.color !== undefined) row.color = input.color;
-      if (input.icon !== undefined) row.icon = input.icon;
-      return row;
-    },
-    updateContent: async (userId: string, id: number, payload: string) => {
-      const row = findByIdForUser(userId, id);
-      if (!row || row.kind !== "manual") return null;
-      row.payload = payload;
-      return row;
-    },
-    setDefault: async (userId: string, id: number) => {
-      const row = findByIdForUser(userId, id);
-      if (!row || row.kind !== "manual") return null;
-      for (const w of state.workspaces.values()) {
-        if (w.userId === userId && w.kind === "manual") w.isDefault = false;
-      }
-      row.isDefault = true;
-      return row;
-    },
-    unsetDefault: async (userId: string, id: number) => {
-      const row = findByIdForUser(userId, id);
-      if (!row || row.kind !== "manual") return null;
-      row.isDefault = false;
-      return row;
-    },
-    touchLastUsed: async (userId: string, id: number) => {
-      const row = findByIdForUser(userId, id);
-      if (row) row.lastUsedAt = new Date().toISOString();
-    },
-    delete: async (userId: string, id: number) => {
-      const row = findByIdForUser(userId, id);
-      if (!row || row.kind !== "manual") return false;
-      state.workspaces.delete(id);
-      return true;
-    },
-  }),
-}));
-
-vi.mock(
-  "../../../../src/backend/database/routes/workspace-dispatch.js",
-  () => ({
-    registerWorkspacesRouter: vi.fn(),
-    unregisterWorkspacesRouter: vi.fn(),
-  }),
-);
-
-const { router } = await import("../../src/backend/routes.js");
-
-function findLayer(method: string, path: string) {
-  const stack = (router as unknown as Router).stack as Array<{
-    route?: {
-      path: string;
-      methods: Record<string, boolean>;
-      stack: Array<{ handle: (req: Request, res: Response) => unknown }>;
-    };
-  }>;
-  const layer = stack.find(
-    (l) => l.route?.path === path && l.route?.methods[method],
-  );
-  if (!layer?.route) throw new Error(`No route for ${method} ${path}`);
-  return layer.route.stack[layer.route.stack.length - 1].handle;
-}
-
-function makeReqRes(overrides: {
-  body?: Record<string, unknown>;
-  params?: Record<string, unknown>;
-}) {
-  const req = {
-    userId: state.currentUserId,
-    body: overrides.body ?? {},
-    params: overrides.params ?? {},
-    headers: {},
-  } as unknown as Request;
-
-  const res = {
-    statusCode: 200,
-    jsonBody: null as unknown,
-    status(code: number) {
-      (this as unknown as { statusCode: number }).statusCode = code;
-      return this;
-    },
-    json(payload: unknown) {
-      (this as unknown as { jsonBody: unknown }).jsonBody = payload;
-      return this;
-    },
-  } as unknown as Response & { statusCode: number; jsonBody: unknown };
-
-  return { req, res };
-}
-
-async function invoke(
-  method: string,
-  path: string,
-  overrides: {
-    body?: Record<string, unknown>;
-    params?: Record<string, unknown>;
-  } = {},
-) {
-  const handler = findLayer(method, path);
-  const { req, res } = makeReqRes(overrides);
-  await handler(req, res);
-  return res as unknown as {
-    statusCode: number;
-    jsonBody: Record<string, unknown> | null;
-  };
-}
-
-beforeEach(() => {
-  state.currentUserId = "user-1";
-  state.workspaces = new Map();
-  state.nextId = 1;
+beforeEach(async () => {
+  server = await startServer();
 });
 
-describe("GET /", () => {
-  it("returns the list with a computed tabCount", async () => {
-    await invoke("post", "/", {
-      body: {
-        name: "Test A",
-        payload: { version: 1, tabs: [{ slotId: "a" }, { slotId: "b" }] },
-      },
-    });
+afterEach(async () => {
+  await server.close();
+});
 
-    const res = await invoke("get", "/");
-    expect(res.statusCode).toBe(200);
-    expect(res.jsonBody).toHaveLength(1);
+async function create(name = "Prod", user = "user-1") {
+  const res = await server.request("POST", "/", {
+    user,
+    body: { name, color: "#ef4444", payload: layout() },
+  });
+  expect(res.status).toBe(200);
+  return res.body;
+}
+
+describe("workspace routes", () => {
+  it("creates and lists workspaces with a parsed payload and tab count", async () => {
+    const created = await create();
+    expect(created).toMatchObject({
+      name: "Prod",
+      color: "#ef4444",
+      kind: "manual",
+      isDefault: false,
+      tabCount: 1,
+    });
+    expect(created.payload.tabs).toHaveLength(1);
+    expect(created.syncId).toEqual(expect.any(String));
+
+    const list = await server.request("GET", "/");
+    expect(list.body).toHaveLength(1);
+    expect(list.body[0].id).toBe(created.id);
+  });
+
+  it("rejects a missing name or payload", async () => {
     expect(
-      (res.jsonBody as unknown as { tabCount: number }[])[0].tabCount,
-    ).toBe(2);
-  });
-});
-
-describe("POST /", () => {
-  it("400s when name is missing", async () => {
-    const res = await invoke("post", "/", {
-      body: { payload: { version: 1, tabs: [] } },
-    });
-    expect(res.statusCode).toBe(400);
-  });
-
-  it("400s when payload has no tabs array", async () => {
-    const res = await invoke("post", "/", {
-      body: { name: "Test A", payload: { version: 1 } },
-    });
-    expect(res.statusCode).toBe(400);
-  });
-
-  it("200s and creates a manual workspace", async () => {
-    const res = await invoke("post", "/", {
-      body: { name: "Test A", payload: { version: 1, tabs: [] } },
-    });
-    expect(res.statusCode).toBe(200);
-    expect(res.jsonBody).toMatchObject({ name: "Test A", kind: "manual" });
-  });
-});
-
-describe("PATCH /:id", () => {
-  it("rejects renaming the last_session row", async () => {
-    const created = await invoke("put", "/last-session", {
-      body: { payload: { version: 1, tabs: [] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const res = await invoke("patch", "/:id", {
-      params: { id: String(id) },
-      body: { name: "Nope" },
-    });
-    expect(res.statusCode).toBe(404);
-  });
-
-  it("renames a manual workspace", async () => {
-    const created = await invoke("post", "/", {
-      body: { name: "Old", payload: { version: 1, tabs: [] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const res = await invoke("patch", "/:id", {
-      params: { id: String(id) },
-      body: { name: "New" },
-    });
-    expect(res.statusCode).toBe(200);
-    expect(res.jsonBody).toMatchObject({ name: "New" });
-  });
-
-  it("404s for a nonexistent id", async () => {
-    const res = await invoke("patch", "/:id", {
-      params: { id: "999" },
-      body: { name: "New" },
-    });
-    expect(res.statusCode).toBe(404);
-  });
-});
-
-describe("PUT /:id/content", () => {
-  it("updates payload for a manual workspace", async () => {
-    const created = await invoke("post", "/", {
-      body: { name: "A", payload: { version: 1, tabs: [] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const res = await invoke("put", "/:id/content", {
-      params: { id: String(id) },
-      body: { payload: { version: 1, tabs: [{ slotId: "x" }] } },
-    });
-    expect(res.statusCode).toBe(200);
-    expect(res.jsonBody).toMatchObject({ tabCount: 1 });
-  });
-
-  it("404s on wrong owner", async () => {
-    const created = await invoke("post", "/", {
-      body: { name: "A", payload: { version: 1, tabs: [] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    state.currentUserId = "user-2";
-    const res = await invoke("put", "/:id/content", {
-      params: { id: String(id) },
-      body: { payload: { version: 1, tabs: [] } },
-    });
-    expect(res.statusCode).toBe(404);
-  });
-});
-
-describe("DELETE /:id", () => {
-  it("rejects deleting the last_session row", async () => {
-    const created = await invoke("put", "/last-session", {
-      body: { payload: { version: 1, tabs: [] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const res = await invoke("delete", "/:id", { params: { id: String(id) } });
-    expect(res.statusCode).toBe(404);
-  });
-
-  it("404s for a nonexistent id", async () => {
-    const res = await invoke("delete", "/:id", { params: { id: "999" } });
-    expect(res.statusCode).toBe(404);
-  });
-
-  it("deletes a manual workspace", async () => {
-    const created = await invoke("post", "/", {
-      body: { name: "A", payload: { version: 1, tabs: [] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const res = await invoke("delete", "/:id", { params: { id: String(id) } });
-    expect(res.statusCode).toBe(200);
-    expect(res.jsonBody).toEqual({ success: true });
-  });
-});
-
-describe("POST /:id/duplicate", () => {
-  it("produces a second independent row", async () => {
-    const created = await invoke("post", "/", {
-      body: {
-        name: "A",
-        payload: { version: 1, tabs: [{ slotId: "a" }] },
-      },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const dup = await invoke("post", "/:id/duplicate", {
-      params: { id: String(id) },
-      body: { name: "A (copy)" },
-    });
-    expect(dup.statusCode).toBe(200);
-    expect(dup.jsonBody).toMatchObject({ name: "A (copy)", tabCount: 1 });
-
-    const updateOriginal = await invoke("put", "/:id/content", {
-      params: { id: String(id) },
-      body: { payload: { version: 1, tabs: [] } },
-    });
-    expect(updateOriginal.jsonBody).toMatchObject({ tabCount: 0 });
-
-    const dupId = (dup.jsonBody as unknown as { id: number }).id;
-    const refetched = await invoke("get", "/");
-    const dupRow = (
-      refetched.jsonBody as unknown as { id: number; tabCount: number }[]
-    ).find((w) => w.id === dupId);
-    expect(dupRow?.tabCount).toBe(1);
-  });
-});
-
-describe("POST /:id/set-default", () => {
-  it("clears a previous default and sets the new one", async () => {
-    const a = await invoke("post", "/", {
-      body: { name: "A", payload: { version: 1, tabs: [] } },
-    });
-    const b = await invoke("post", "/", {
-      body: { name: "B", payload: { version: 1, tabs: [] } },
-    });
-    const aId = (a.jsonBody as unknown as { id: number }).id;
-    const bId = (b.jsonBody as unknown as { id: number }).id;
-
-    await invoke("post", "/:id/set-default", { params: { id: String(aId) } });
-    const second = await invoke("post", "/:id/set-default", {
-      params: { id: String(bId) },
-    });
-    expect(second.jsonBody).toMatchObject({ isDefault: true });
-
-    const list = await invoke("get", "/");
-    const aRow = (
-      list.jsonBody as unknown as { id: number; isDefault: boolean }[]
-    ).find((w) => w.id === aId);
-    expect(aRow?.isDefault).toBe(false);
-  });
-
-  it("is idempotent when re-called on an already-default row", async () => {
-    const a = await invoke("post", "/", {
-      body: { name: "A", payload: { version: 1, tabs: [] } },
-    });
-    const aId = (a.jsonBody as unknown as { id: number }).id;
-
-    await invoke("post", "/:id/set-default", { params: { id: String(aId) } });
-    const again = await invoke("post", "/:id/set-default", {
-      params: { id: String(aId) },
-    });
-    expect(again.statusCode).toBe(200);
-    expect(again.jsonBody).toMatchObject({ isDefault: true });
-  });
-});
-
-describe("POST /:id/unset-default", () => {
-  it("clears isDefault on a manual workspace", async () => {
-    const a = await invoke("post", "/", {
-      body: { name: "A", payload: { version: 1, tabs: [] } },
-    });
-    const aId = (a.jsonBody as unknown as { id: number }).id;
-
-    await invoke("post", "/:id/set-default", { params: { id: String(aId) } });
-    const res = await invoke("post", "/:id/unset-default", {
-      params: { id: String(aId) },
-    });
-    expect(res.statusCode).toBe(200);
-    expect(res.jsonBody).toMatchObject({ isDefault: false });
-  });
-
-  it("rejects unsetting the last_session row", async () => {
-    const created = await invoke("put", "/last-session", {
-      body: { payload: { version: 1, tabs: [] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const res = await invoke("post", "/:id/unset-default", {
-      params: { id: String(id) },
-    });
-    expect(res.statusCode).toBe(404);
-  });
-});
-
-describe("POST /:id/apply", () => {
-  it("touches lastUsedAt and returns the parsed payload", async () => {
-    const created = await invoke("post", "/", {
-      body: { name: "A", payload: { version: 1, tabs: [{ slotId: "a" }] } },
-    });
-    const id = (created.jsonBody as unknown as { id: number }).id;
-
-    const res = await invoke("post", "/:id/apply", {
-      params: { id: String(id) },
-    });
-    expect(res.statusCode).toBe(200);
-    expect(res.jsonBody).toMatchObject({
-      payload: { version: 1, tabs: [{ slotId: "a" }] },
-    });
+      (await server.request("POST", "/", { body: { payload: layout() } }))
+        .status,
+    ).toBe(400);
     expect(
-      (res.jsonBody as unknown as { lastUsedAt: string | null }).lastUsedAt,
-    ).toBeTruthy();
+      (await server.request("POST", "/", { body: { name: "x", payload: {} } }))
+        .status,
+    ).toBe(400);
+  });
+
+  it("keeps one last session row per user and never lists it as editable", async () => {
+    expect((await server.request("GET", "/last-session")).body).toBeNull();
+
+    await server.request("PUT", "/last-session", {
+      body: { payload: layout() },
+    });
+    const second = await server.request("PUT", "/last-session", {
+      body: { payload: layout([]) },
+    });
+    expect(second.body.tabCount).toBe(0);
+
+    const list = (await server.request("GET", "/")).body;
+    expect(
+      list.filter(
+        (w: { kind: string; isDefault: boolean; id: number }) =>
+          w.kind === "last_session",
+      ),
+    ).toHaveLength(1);
+
+    const id = second.body.id;
+    expect(
+      (await server.request("PATCH", `/${id}`, { body: { name: "x" } })).status,
+    ).toBe(404);
+    expect((await server.request("DELETE", `/${id}`)).status).toBe(404);
+  });
+
+  it("renames, replaces content and duplicates", async () => {
+    const created = await create();
+
+    const renamed = await server.request("PATCH", `/${created.id}`, {
+      body: { name: "  Staging  ", color: "#22c55e" },
+    });
+    expect(renamed.body).toMatchObject({ name: "Staging", color: "#22c55e" });
+
+    const replaced = await server.request("PUT", `/${created.id}/content`, {
+      body: { payload: layout([]) },
+    });
+    expect(replaced.body.tabCount).toBe(0);
+
+    const copy = await server.request("POST", `/${created.id}/duplicate`, {
+      body: { name: "Staging (copy)" },
+    });
+    expect(copy.body).toMatchObject({
+      name: "Staging (copy)",
+      color: "#22c55e",
+      tabCount: 0,
+    });
+    expect(copy.body.id).not.toBe(created.id);
+  });
+
+  it("keeps a single default", async () => {
+    const a = await create("A");
+    const b = await create("B");
+
+    await server.request("POST", `/${a.id}/set-default`);
+    await server.request("POST", `/${b.id}/set-default`);
+
+    const list = (await server.request("GET", "/")).body;
+    const defaults = list.filter(
+      (w: { kind: string; isDefault: boolean; id: number }) => w.isDefault,
+    );
+    expect(
+      defaults.map(
+        (w: { kind: string; isDefault: boolean; id: number }) => w.id,
+      ),
+    ).toEqual([b.id]);
+
+    const unset = await server.request("POST", `/${b.id}/unset-default`);
+    expect(unset.body.isDefault).toBe(false);
+  });
+
+  it("marks a workspace as used when it is applied", async () => {
+    const created = await create();
+    expect(created.lastUsedAt).toBeNull();
+
+    const applied = await server.request("POST", `/${created.id}/apply`);
+    expect(applied.status).toBe(200);
+
+    const list = (await server.request("GET", "/")).body;
+    expect(list[0].lastUsedAt).toEqual(expect.any(String));
+  });
+
+  it("deletes a workspace", async () => {
+    const created = await create();
+    expect((await server.request("DELETE", `/${created.id}`)).body).toEqual({
+      success: true,
+    });
+    expect((await server.request("GET", "/")).body).toEqual([]);
+    expect((await server.request("DELETE", `/${created.id}`)).status).toBe(404);
+  });
+
+  it("rejects ids that are not numbers", async () => {
+    expect((await server.request("DELETE", "/abc")).status).toBe(400);
+    expect((await server.request("POST", "/abc/apply")).status).toBe(400);
+  });
+
+  it("never shows or changes another user's workspaces", async () => {
+    const mine = await create("Mine", "user-1");
+
+    expect((await server.request("GET", "/", { user: "user-2" })).body).toEqual(
+      [],
+    );
+    for (const [method, path] of [
+      ["PATCH", `/${mine.id}`],
+      ["DELETE", `/${mine.id}`],
+      ["POST", `/${mine.id}/apply`],
+      ["POST", `/${mine.id}/set-default`],
+      ["POST", `/${mine.id}/duplicate`],
+    ] as const) {
+      const res = await server.request(method, path, {
+        user: "user-2",
+        body: { name: "stolen" },
+      });
+      expect(res.status).toBe(404);
+    }
+  });
+
+  it("flushes the database after every write", async () => {
+    const before = server.db.persisted;
+    const created = await create();
+    await server.request("POST", `/${created.id}/set-default`);
+    await server.request("DELETE", `/${created.id}`);
+    expect(server.db.persisted).toBeGreaterThanOrEqual(before + 3);
   });
 });
 
-describe("PUT /last-session and GET /last-session", () => {
-  it("returns null before any save", async () => {
-    const res = await invoke("get", "/last-session");
-    expect(res.jsonBody).toBeNull();
-  });
+describe("workspaces.use", () => {
+  it("refuses every route without it", async () => {
+    await server.close();
+    server = await startServer({ permissions: [] });
 
-  it("upserts idempotently - two calls produce one row", async () => {
-    await invoke("put", "/last-session", {
-      body: { payload: { version: 1, tabs: [] } },
-    });
-    await invoke("put", "/last-session", {
-      body: { payload: { version: 1, tabs: [{ slotId: "a" }] } },
-    });
-
-    const list = await invoke("get", "/");
-    const lastSessionRows = (
-      list.jsonBody as unknown as { kind: string }[]
-    ).filter((w) => w.kind === "last_session");
-    expect(lastSessionRows).toHaveLength(1);
-
-    const res = await invoke("get", "/last-session");
-    expect(res.jsonBody).toMatchObject({ tabCount: 1 });
+    for (const [method, path] of [
+      ["GET", "/"],
+      ["POST", "/"],
+      ["GET", "/last-session"],
+      ["PUT", "/last-session"],
+      ["PATCH", "/1"],
+      ["PUT", "/1/content"],
+      ["POST", "/1/duplicate"],
+      ["POST", "/1/set-default"],
+      ["POST", "/1/unset-default"],
+      ["POST", "/1/apply"],
+      ["DELETE", "/1"],
+    ] as const) {
+      const res = await server.request(method, path, {
+        body: { name: "x", payload: layout() },
+      });
+      expect(res.status, `${method} ${path}`).toBe(403);
+      expect(res.body.required).toBe("workspaces.use");
+    }
   });
 });