VaultysClaw control-plane.instructions.md

Control Plane Conventions

API Routes

File structure: app/api/<resource>/route.ts (collection), app/api/<resource>/[param]/route.ts (item).

Every handler follows this order: auth check → permission check → DB query → response.

export async function GET(request: NextRequest) {
  const auth = await getAuthContext(request);
  if (!auth) return unauthorized();
  if (!auth.canAccessWorkspace(workspaceId)) return forbidden();

  const db = getDb();
  // raw SQL via better-sqlite3 — no ORM
  return NextResponse.json({ success: true, data: result });
}

Pagination (use for all list endpoints):

const page = Math.max(1, parseInt(searchParams.get("page") ?? "1") || 1);
const pageSize = Math.min(
  100,
  Math.max(1, parseInt(searchParams.get("pageSize") ?? "20") || 20)
);
// response shape:
return NextResponse.json({ items, total, page, pageSize, totalPages });

Error responses: return NextResponse.json({ error: "Message" }, { status: 400 }). Wrap non-trivial handlers in try/catch and log with console.error("POST /api/... error:", err).

Shared API response types live in lib/api-types.ts (PaginationMeta, ListResponse<T>, AgentSummary, etc.). Import from there before defining local types.

Database

Access the SQLite singleton via getDb() from @/lib/db. Use raw prepared statements:

const db = getDb();
const row = db.prepare("SELECT * FROM agents WHERE did = ?").get(did);
db.prepare("INSERT INTO agents (did, name) VALUES (?, ?)").run(did, name);

Schema changes go directly in createTables() in lib/db.ts — there are no migration files. Add CREATE TABLE IF NOT EXISTS and CREATE INDEX IF NOT EXISTS statements.

Auth

Import from @/lib/auth-utils:

• getAuthContext(request?) — returns AuthContext | null (null = unauthenticated). Always pass the request parameter so API key authentication works in addition to session auth.
• unauthorized() / forbidden() — return typed NextResponse with 401/403
• Permission methods: canAccessWorkspace, canAdminWorkspace, canAccessAgent, canAdminAgent