From d2e544484f7e09c4729239de5cdeee4715f6b59c Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 8 Sep 2026 14:19:14 -0500 Subject: [PATCH 1/7] fix(client): request the server's max page size for the Projects list (BUG #12) useProjects() called apiRequestPaginated("/projects") with no pageSize, so the server defaulted to DEFAULT_PAGE_SIZE=25 (repository.types.ts). The hook then discarded the response's pagination `meta` entirely, and ProjectList has no "load more"/pager UI -- so an account with more than 25 projects silently lost access to the 26th+ project from the Projects page. No error, no count, no indicator that more existed. Reproduced live: created 26 test projects via the API (27 total), reloaded /app, and confirmed only 25 rendered with zero way to reach the rest through the UI. Fixed by requesting the server's hard cap (MAX_PAGE_SIZE=100) instead of relying on the default. This resolves the reported symptom for any realistic project count; a true paginated/infinite-scroll UI for counts beyond 100 is tracked separately as the "add missing pagination/caching" work already scoped in Plan.md's hardening phase. The same apiRequestPaginated-with-discarded-meta pattern also appears in use-runs.ts, use-evidence.ts, use-reports.ts, and use-project-members.ts; none were reproduced as broken via the browser in this pass, so they're flagged for the same follow-up rather than changed speculatively here. Verified live: created 26 test projects (27 total), confirmed all 27 now render after the fix, then deleted the 26 test projects via the API to restore the account to its prior state (Debug Test only). Co-Authored-By: Claude Sonnet 5 --- .../workspace/api/use-projects.test.tsx | 44 +++++++++++++++++++ .../features/workspace/api/use-projects.ts | 9 +++- 2 files changed, 52 insertions(+), 1 deletion(-) create mode 100644 client/src/features/workspace/api/use-projects.test.tsx diff --git a/client/src/features/workspace/api/use-projects.test.tsx b/client/src/features/workspace/api/use-projects.test.tsx new file mode 100644 index 0000000..c71d2aa --- /dev/null +++ b/client/src/features/workspace/api/use-projects.test.tsx @@ -0,0 +1,44 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; +import { renderHook, waitFor } from "@testing-library/react"; +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import type { ReactNode } from "react"; +import { apiRequestPaginated } from "@/lib/api-client"; +import { useProjects } from "./use-projects"; + +vi.mock("@/lib/api-client", () => ({ + apiRequest: vi.fn(), + apiRequestPaginated: vi.fn(), +})); + +function wrapper({ children }: { children: ReactNode }) { + const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + return {children}; +} + +const PROJECT = { + id: "11111111-1111-1111-1111-111111111111", + name: "Acme Corp", + slug: "acme-corp", + scope: {}, + createdAt: new Date(), + updatedAt: new Date(), +}; + +describe("useProjects", () => { + afterEach(() => { + vi.clearAllMocks(); + }); + + it("requests the server's max page size instead of the 25-item default (BUG #12)", async () => { + // With no pageSize, the server defaults to DEFAULT_PAGE_SIZE=25 (repository.types.ts) and + // ProjectList has no "load more"/pager UI -- an account with more than 25 projects silently + // lost access to the rest from the Projects page, with no error or indicator of any kind. + // Requesting the server's hard cap (MAX_PAGE_SIZE=100) closes that gap for any realistic + // project count. + vi.mocked(apiRequestPaginated).mockResolvedValue({ items: [PROJECT] }); + + renderHook(() => useProjects(), { wrapper }); + + await waitFor(() => expect(apiRequestPaginated).toHaveBeenCalledWith("/projects?pageSize=100")); + }); +}); diff --git a/client/src/features/workspace/api/use-projects.ts b/client/src/features/workspace/api/use-projects.ts index 48bb45b..47071f5 100644 --- a/client/src/features/workspace/api/use-projects.ts +++ b/client/src/features/workspace/api/use-projects.ts @@ -21,7 +21,14 @@ export function useProjects() { return useQuery({ queryKey: ["projects"] as const, queryFn: async () => { - const { items } = await apiRequestPaginated("/projects"); + // The server paginates every list endpoint (PERF-001) and defaults to + // DEFAULT_PAGE_SIZE=25 when no `pageSize` is given. ProjectList has no "load more"/pager UI + // (that's tracked separately as future pagination/caching work per Plan.md), so without an + // explicit pageSize an account with more than 25 projects silently lost access to the rest + // from the Projects page -- no error, no indicator, nothing (BUG #12). Requesting the + // server's hard cap (MAX_PAGE_SIZE=100, repository.types.ts) closes that gap for any + // realistic project count; a true paginated UI is still needed beyond 100. + const { items } = await apiRequestPaginated("/projects?pageSize=100"); return projectListSchema.parse(items); }, }); From db422fb2a1fa8922b524e650605625d53b90e4c6 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 8 Sep 2026 15:01:24 -0500 Subject: [PATCH 2/7] fix: request server max page size in remaining list hooks (BUG #12 sibling) use-runs.ts, use-evidence.ts, use-reports.ts, and use-project-members.ts all called apiRequestPaginated without a pageSize param, so the server silently truncated results at DEFAULT_PAGE_SIZE=25. None of the corresponding UIs (RunsList, EvidenceGrid, reports list, MembersPanel) have pager/load-more controls, so any project with more than 25 runs, evidence files, reports, or members would silently lose access to the rest with zero indication -- the exact same root cause already fixed in use-projects.ts under BUG #12. Applied the identical fix: request the server's hard cap (?pageSize=100) instead of relying on the default. Updated each hook's existing test to assert the corrected URL and added coverage where a query param already existed (evidence's nodeId case). Full client suite verified green: 63 files / 190 tests passing. Co-Authored-By: Claude Sonnet 5 --- client/src/features/evidence/api/use-evidence.test.tsx | 8 +++++--- client/src/features/evidence/api/use-evidence.ts | 7 +++++-- client/src/features/reports/api/use-reports.test.tsx | 6 ++++-- client/src/features/reports/api/use-reports.ts | 5 ++++- client/src/features/runs/api/use-runs.test.tsx | 6 ++++-- client/src/features/runs/api/use-runs.ts | 5 ++++- .../features/settings/api/use-project-members.test.tsx | 6 ++++-- client/src/features/settings/api/use-project-members.ts | 5 ++++- 8 files changed, 34 insertions(+), 14 deletions(-) diff --git a/client/src/features/evidence/api/use-evidence.test.tsx b/client/src/features/evidence/api/use-evidence.test.tsx index 42bdee1..ef1d0f6 100644 --- a/client/src/features/evidence/api/use-evidence.test.tsx +++ b/client/src/features/evidence/api/use-evidence.test.tsx @@ -23,13 +23,15 @@ const EVIDENCE = { describe("useEvidence", () => { afterEach(() => vi.clearAllMocks()); - it("fetches and Zod-parses the project's evidence list", async () => { + it("fetches and Zod-parses the project's evidence list, requesting the server's max page size (BUG #12 sibling)", async () => { + // EvidenceGrid has no pager UI -- without an explicit pageSize, a project with more than + // DEFAULT_PAGE_SIZE=25 evidence files would silently lose access to the rest, with no indication. vi.mocked(apiRequestPaginated).mockResolvedValue({ items: [EVIDENCE] }); const { result } = renderHook(() => useEvidence(PROJECT_ID), { wrapper: queryClientWrapper() }); await waitFor(() => expect(result.current.data).toHaveLength(1)); - expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence`); + expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence?pageSize=100`); }); it("scopes the query by nodeId when provided", async () => { @@ -38,7 +40,7 @@ describe("useEvidence", () => { renderHook(() => useEvidence(PROJECT_ID, "node-1"), { wrapper: queryClientWrapper() }); await waitFor(() => - expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence?nodeId=node-1`), + expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/evidence?nodeId=node-1&pageSize=100`), ); }); }); diff --git a/client/src/features/evidence/api/use-evidence.ts b/client/src/features/evidence/api/use-evidence.ts index 3208784..a22ed56 100644 --- a/client/src/features/evidence/api/use-evidence.ts +++ b/client/src/features/evidence/api/use-evidence.ts @@ -25,9 +25,12 @@ export function useEvidence(projectId: string, nodeId?: string) { return useQuery({ queryKey: ["projects", projectId, "evidence", { nodeId: nodeId ?? null }] as const, queryFn: async () => { + // Same fix as use-projects.ts (BUG #12): request the server's hard page-size cap since + // EvidenceGrid has no pager UI, so anything past DEFAULT_PAGE_SIZE=25 would otherwise + // silently vanish from view. const path = nodeId - ? `/projects/${projectId}/evidence?nodeId=${encodeURIComponent(nodeId)}` - : `/projects/${projectId}/evidence`; + ? `/projects/${projectId}/evidence?nodeId=${encodeURIComponent(nodeId)}&pageSize=100` + : `/projects/${projectId}/evidence?pageSize=100`; const { items } = await apiRequestPaginated(path); return evidenceFileListSchema.parse(items); }, diff --git a/client/src/features/reports/api/use-reports.test.tsx b/client/src/features/reports/api/use-reports.test.tsx index fc220f5..e198acb 100644 --- a/client/src/features/reports/api/use-reports.test.tsx +++ b/client/src/features/reports/api/use-reports.test.tsx @@ -22,12 +22,14 @@ const REPORT = { describe("useReports", () => { afterEach(() => vi.clearAllMocks()); - it("fetches and Zod-parses the project's report list", async () => { + it("fetches and Zod-parses the project's report list, requesting the server's max page size (BUG #12 sibling)", async () => { + // The reports list has no pager UI -- without an explicit pageSize, a project with more than + // DEFAULT_PAGE_SIZE=25 reports would silently lose access to the rest, with no indication. vi.mocked(apiRequestPaginated).mockResolvedValue({ items: [REPORT] }); const { result } = renderHook(() => useReports(PROJECT_ID), { wrapper: queryClientWrapper() }); await waitFor(() => expect(result.current.data).toHaveLength(1)); - expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/reports`); + expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/reports?pageSize=100`); }); }); diff --git a/client/src/features/reports/api/use-reports.ts b/client/src/features/reports/api/use-reports.ts index a574cee..e1bb85a 100644 --- a/client/src/features/reports/api/use-reports.ts +++ b/client/src/features/reports/api/use-reports.ts @@ -28,7 +28,10 @@ export function useReports(projectId: string) { return useQuery({ queryKey: ["projects", projectId, "reports"] as const, queryFn: async () => { - const { items } = await apiRequestPaginated(`/projects/${projectId}/reports`); + // Same fix as use-projects.ts (BUG #12): request the server's hard page-size cap since + // the reports list has no pager UI, so anything past DEFAULT_PAGE_SIZE=25 would otherwise + // silently vanish from view. + const { items } = await apiRequestPaginated(`/projects/${projectId}/reports?pageSize=100`); return reportListSchema.parse(items); }, enabled: projectId.length > 0, diff --git a/client/src/features/runs/api/use-runs.test.tsx b/client/src/features/runs/api/use-runs.test.tsx index 9f76c9e..efa9177 100644 --- a/client/src/features/runs/api/use-runs.test.tsx +++ b/client/src/features/runs/api/use-runs.test.tsx @@ -35,13 +35,15 @@ describe("isNonTerminal", () => { describe("useRuns", () => { afterEach(() => vi.clearAllMocks()); - it("fetches and Zod-parses the project's run list", async () => { + it("fetches and Zod-parses the project's run list, requesting the server's max page size (BUG #12 sibling)", async () => { + // RunsList has no pager UI -- without an explicit pageSize, a project with more than + // DEFAULT_PAGE_SIZE=25 runs would silently lose access to the rest, with no indication. vi.mocked(apiRequestPaginated).mockResolvedValue({ items: [RUN] }); const { result } = renderHook(() => useRuns(PROJECT_ID), { wrapper: queryClientWrapper() }); await waitFor(() => expect(result.current.data).toHaveLength(1)); - expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/runs`); + expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/runs?pageSize=100`); }); }); diff --git a/client/src/features/runs/api/use-runs.ts b/client/src/features/runs/api/use-runs.ts index 70a6886..ef7de48 100644 --- a/client/src/features/runs/api/use-runs.ts +++ b/client/src/features/runs/api/use-runs.ts @@ -27,7 +27,10 @@ export function useRuns(projectId: string) { return useQuery({ queryKey: ["projects", projectId, "runs"] as const, queryFn: async () => { - const { items } = await apiRequestPaginated(`/projects/${projectId}/runs`); + // Same fix as use-projects.ts (BUG #12): request the server's hard page-size cap since + // RunsList has no pager UI, so anything past DEFAULT_PAGE_SIZE=25 would otherwise silently + // vanish from view. + const { items } = await apiRequestPaginated(`/projects/${projectId}/runs?pageSize=100`); return toolRunListSchema.parse(items); }, enabled: projectId.length > 0, diff --git a/client/src/features/settings/api/use-project-members.test.tsx b/client/src/features/settings/api/use-project-members.test.tsx index b63a0ca..efc970a 100644 --- a/client/src/features/settings/api/use-project-members.test.tsx +++ b/client/src/features/settings/api/use-project-members.test.tsx @@ -20,13 +20,15 @@ const MEMBER = { describe("useProjectMembers", () => { afterEach(() => vi.clearAllMocks()); - it("fetches and Zod-parses the project's member list", async () => { + it("fetches and Zod-parses the project's member list, requesting the server's max page size (BUG #12 sibling)", async () => { + // MembersPanel has no pager UI -- without an explicit pageSize, a project with more than + // DEFAULT_PAGE_SIZE=25 members would silently lose access to the rest, with no indication. vi.mocked(apiRequestPaginated).mockResolvedValue({ items: [MEMBER] }); const { result } = renderHook(() => useProjectMembers(PROJECT_ID), { wrapper: queryClientWrapper() }); await waitFor(() => expect(result.current.data).toHaveLength(1)); - expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/members`); + expect(apiRequestPaginated).toHaveBeenCalledWith(`/projects/${PROJECT_ID}/members?pageSize=100`); }); }); diff --git a/client/src/features/settings/api/use-project-members.ts b/client/src/features/settings/api/use-project-members.ts index 52acc75..92ff76c 100644 --- a/client/src/features/settings/api/use-project-members.ts +++ b/client/src/features/settings/api/use-project-members.ts @@ -22,7 +22,10 @@ export function useProjectMembers(projectId: string) { return useQuery({ queryKey: ["projects", projectId, "members"] as const, queryFn: async () => { - const { items } = await apiRequestPaginated(`/projects/${projectId}/members`); + // Same fix as use-projects.ts (BUG #12): request the server's hard page-size cap since + // MembersPanel has no pager UI, so anything past DEFAULT_PAGE_SIZE=25 would otherwise + // silently vanish from view. + const { items } = await apiRequestPaginated(`/projects/${projectId}/members?pageSize=100`); return projectMemberListSchema.parse(items); }, enabled: projectId.length > 0, From a32054475045dc749ab1704229030c324b993692 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 8 Sep 2026 20:38:26 -0500 Subject: [PATCH 3/7] refactor(client): extract Hero particle background into a shared effect BackgroundLayer/useParticleField had no Hero-specific coupling beyond an optional focusRef prop, so move them from features/hero/background to components/effects verbatim. This lets /login and /register reuse the same animated background without duplicating the canvas logic. Co-Authored-By: Claude Sonnet 5 --- .../hero/background => components/effects}/BackgroundLayer.tsx | 0 .../hero/background => components/effects}/useParticleField.ts | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename client/src/{features/hero/background => components/effects}/BackgroundLayer.tsx (100%) rename client/src/{features/hero/background => components/effects}/useParticleField.ts (100%) diff --git a/client/src/features/hero/background/BackgroundLayer.tsx b/client/src/components/effects/BackgroundLayer.tsx similarity index 100% rename from client/src/features/hero/background/BackgroundLayer.tsx rename to client/src/components/effects/BackgroundLayer.tsx diff --git a/client/src/features/hero/background/useParticleField.ts b/client/src/components/effects/useParticleField.ts similarity index 100% rename from client/src/features/hero/background/useParticleField.ts rename to client/src/components/effects/useParticleField.ts From 28188846af8f4396ddc8d936afb75912910db7d7 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 8 Sep 2026 20:38:44 -0500 Subject: [PATCH 4/7] feat(client): wire the Hero's navigation to the rest of the app MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The brand mark and 'Request access'/'Explore the graph engine' CTAs in the marketing Hero rendered but had no href/onClick, leaving first-time visitors with no way to reach /register, /login, or /app. - Export buttonVariants from ui/button.tsx so a next/link can be styled as a button without nesting inside - + ) } diff --git a/client/src/features/hero/components/Navbar.test.tsx b/client/src/features/hero/components/Navbar.test.tsx new file mode 100644 index 0000000..87ccb29 --- /dev/null +++ b/client/src/features/hero/components/Navbar.test.tsx @@ -0,0 +1,27 @@ +import { afterEach, describe, expect, it } from "vitest"; +import { cleanup, render, screen } from "@testing-library/react"; +import { Navbar } from "./Navbar"; + +describe("Navbar", () => { + afterEach(cleanup); + + it("links the CTA to registration when the visitor has no session", () => { + render(); + + const cta = screen.getByRole("link", { name: "Request access" }); + expect(cta).toHaveAttribute("href", "/register"); + }); + + it("links the CTA to the app once the visitor has a session", () => { + render(); + + const cta = screen.getByRole("link", { name: "Go to app" }); + expect(cta).toHaveAttribute("href", "/app"); + }); + + it("links the brand mark back to the homepage", () => { + render(); + + expect(screen.getByRole("link", { name: /Attack Surface Studio/ })).toHaveAttribute("href", "/"); + }); +}); diff --git a/client/src/features/hero/components/Navbar.tsx b/client/src/features/hero/components/Navbar.tsx index c560b76..515bc8e 100644 --- a/client/src/features/hero/components/Navbar.tsx +++ b/client/src/features/hero/components/Navbar.tsx @@ -1,5 +1,6 @@ +import Link from 'next/link' import { Radar } from 'lucide-react' -import { Button } from '@/components/ui/button' +import { buttonVariants } from '@/components/ui/button' const NAV_LINKS = [ { label: 'Platform', href: '#platform' }, @@ -7,13 +8,20 @@ const NAV_LINKS = [ { label: 'Docs', href: '#' }, ] -export function Navbar() { +interface NavbarProps { + isAuthenticated: boolean +} + +export function Navbar({ isAuthenticated }: NavbarProps) { + const ctaHref = isAuthenticated ? '/app' : '/register' + const ctaLabel = isAuthenticated ? 'Go to app' : 'Request access' + return (
- + Attack Surface Studio - + - + + {ctaLabel} +
) } From 0bb6104e097315da5cea0e83f0ccf31902b1ca34 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 8 Sep 2026 20:38:52 -0500 Subject: [PATCH 5/7] feat(client): give login/register visual continuity with the Hero MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit /login and /register were flat, unstyled pages with no relationship to the marketing Hero a visitor just came from. Mount the shared BackgroundLayer behind each form, add a branded header (Radar icon + wordmark linking back to '/'), and wrap the form in a bordered/glow card using existing design tokens. LoginForm/RegisterForm/AuthField internals are untouched — this is wrapper-level only. Co-Authored-By: Claude Sonnet 5 --- client/src/app/login/page.tsx | 21 +++++++++++++++------ client/src/app/register/page.tsx | 21 +++++++++++++++------ 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/client/src/app/login/page.tsx b/client/src/app/login/page.tsx index 999324d..4f386d0 100644 --- a/client/src/app/login/page.tsx +++ b/client/src/app/login/page.tsx @@ -1,6 +1,8 @@ import Link from "next/link"; import type { Metadata } from "next"; +import { Radar } from "lucide-react"; import { LoginForm } from "@/features/auth/components/LoginForm"; +import { BackgroundLayer } from "@/components/effects/BackgroundLayer"; export const metadata: Metadata = { title: "Sign in — Attack Surface Studio", @@ -8,13 +10,20 @@ export const metadata: Metadata = { export default function LoginPage() { return ( -
-
-
-

Sign in

-

Access your Attack Surface Studio workspace.

+
+ +
+ + + Attack Surface Studio + +
+
+

Sign in

+

Access your Attack Surface Studio workspace.

+
+
-

Don't have an account?{" "} diff --git a/client/src/app/register/page.tsx b/client/src/app/register/page.tsx index 2927678..9d6537a 100644 --- a/client/src/app/register/page.tsx +++ b/client/src/app/register/page.tsx @@ -1,6 +1,8 @@ import Link from "next/link"; import type { Metadata } from "next"; +import { Radar } from "lucide-react"; import { RegisterForm } from "@/features/auth/components/RegisterForm"; +import { BackgroundLayer } from "@/components/effects/BackgroundLayer"; export const metadata: Metadata = { title: "Create account — Attack Surface Studio", @@ -8,13 +10,20 @@ export const metadata: Metadata = { export default function RegisterPage() { return ( -

-
-
-

Create your account

-

Start mapping your attack surface.

+
+ +
+ + + Attack Surface Studio + +
+
+

Create your account

+

Start mapping your attack surface.

+
+
-

Already have an account?{" "} From deca0571b4999c2aef9fa89836afb8c0e208ae12 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 8 Sep 2026 20:39:06 -0500 Subject: [PATCH 6/7] feat(client): match workspace brand mark to the Hero's WorkspaceShell's header used plain text for the brand link while the Hero used a Radar icon + wordmark. Add the same icon so the brand mark is visually consistent whether a user is on the marketing site or inside the authenticated app. Also commit the AGENTS.md/CLAUDE.md pair that 'next dev' regenerates on every start, per its own note that committing keeps the tree clean. Co-Authored-By: Claude Sonnet 5 --- client/AGENTS.md | 9 +++++++++ client/CLAUDE.md | 1 + .../src/features/workspace/components/WorkspaceShell.tsx | 4 +++- 3 files changed, 13 insertions(+), 1 deletion(-) create mode 100644 client/AGENTS.md create mode 100644 client/CLAUDE.md diff --git a/client/AGENTS.md b/client/AGENTS.md new file mode 100644 index 0000000..643577d --- /dev/null +++ b/client/AGENTS.md @@ -0,0 +1,9 @@ + + +# This is NOT the Next.js you know + +This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices. + +This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean. + + diff --git a/client/CLAUDE.md b/client/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/client/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/client/src/features/workspace/components/WorkspaceShell.tsx b/client/src/features/workspace/components/WorkspaceShell.tsx index 680f565..4f1e689 100644 --- a/client/src/features/workspace/components/WorkspaceShell.tsx +++ b/client/src/features/workspace/components/WorkspaceShell.tsx @@ -2,6 +2,7 @@ import { useMemo, type ReactNode } from "react"; import Link from "next/link"; +import { Radar } from "lucide-react"; import { useRouter, usePathname } from "next/navigation"; import { useAuthUser } from "@/features/auth/auth.store"; import { useLogout } from "@/features/auth/auth.api"; @@ -45,7 +46,8 @@ export function WorkspaceShell({ children }: Props) {

- + + Attack Surface Studio From f3066d108a8dfa39adf1e2ea3a98fc8bf77fa956 Mon Sep 17 00:00:00 2001 From: Alexander Date: Tue, 8 Sep 2026 20:39:14 -0500 Subject: [PATCH 7/7] docs: add project README Covers vision, stack, folder layout, and a concrete getting-started sequence (docker-compose -> server -> client) using the env vars each package already documents in its own .env.example, plus pointers into .claude/ for the deeper architecture/security/roadmap docs. Co-Authored-By: Claude Sonnet 5 --- README.md | 102 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..20d237a --- /dev/null +++ b/README.md @@ -0,0 +1,102 @@ +# Attack Surface Studio + +A Knowledge Graph platform for security reconnaissance and assessment. It orchestrates +external security tools (Nmap, ffuf, Nuclei, …), normalizes their heterogeneous output into +a single graph model, and turns an engagement's accumulated evidence — scans, manual +findings, screenshots, notes, reports — into one navigable, queryable body of knowledge. + +The Knowledge Graph is the product. Security tools are data sources only: every adapter +ultimately produces exactly three things — **Nodes**, **Edges**, and **Metadata** — and +those are what the rest of the platform (UI, reports, AI assistant) reads from. See +[`.claude/Claude.md`](.claude/Claude.md) for the full project philosophy and architecture +docs (`ARCHITECTURE.md`, `DATA_MODEL.md`, `INTEGRATION_SYSTEM.md`, `SECURITY_MODEL.md`, +`Plan.md`). + +## Stack + +| Layer | Choice | +|---|---| +| Frontend | Next.js 16 (App Router), React 19, TypeScript strict, Tailwind v4, React Flow, Zustand, TanStack Query | +| Backend | NestJS, TypeScript, Drizzle ORM, BullMQ (Redis-backed job queue) | +| Database | PostgreSQL 16 | +| Tool execution | `child_process` (local) / `dockerode` (Docker) behind a Tool Adapter registry (`nmap`, `ffuf`, `nuclei`, …) | +| Auth | JWT (short-lived access + rotating refresh), Argon2id password hashing | +| Testing | Vitest + Supertest (integration), Playwright (E2E) | + +## Project layout + +``` +Attack Surface Studio/ +├── client/ Next.js frontend (marketing Hero + Graph Engine + authenticated Workspace) +├── server/ NestJS backend (auth, orchestrator, adapters, knowledge graph, reports) +├── db/ Postgres bootstrap scripts (docker-entrypoint-initdb.d) +├── docker-compose.yml Local Postgres + Redis +└── .claude/ Architecture and planning documentation (source of truth) +``` + +## Prerequisites + +- Node.js 20+ +- [pnpm](https://pnpm.io/) 9 +- Docker (for local Postgres + Redis via `docker-compose`) + +## Getting started + +1. **Start the datastores** + + ```bash + cp .env.example .env # fill in real values before running in anything but local dev + docker-compose up -d + ``` + +2. **Backend** (`server/`) + + ```bash + cd server + pnpm install + cp .env.example .env # DATABASE_URL, JWT secrets, REDIS_URL, etc. — see file comments + pnpm migrate + pnpm start:dev # API on http://localhost:3001 + pnpm start:worker:dev # separate process: executes queued tool runs + ``` + +3. **Frontend** (`client/`) + + ```bash + cd client + pnpm install + cp .env.example .env # NEXT_PUBLIC_API_URL=http://localhost:3001 + pnpm dev # App on http://localhost:3000 + ``` + +4. Open [http://localhost:3000](http://localhost:3000). The landing page's "Request access" / + "Sign in" buttons lead to `/register` and `/login`; once authenticated you land on `/app`. + +## Testing + +```bash +# Frontend +cd client && pnpm test # Vitest + Testing Library +cd client && pnpm e2e # Playwright + +# Backend +cd server && pnpm test # Vitest + Supertest +cd server && pnpm test:coverage +``` + +Both projects enforce an 80% coverage floor. Adapter tests run against recorded real tool +output fixtures rather than live scans. + +## Documentation + +Everything beyond this quick-start — vision, data model, security posture, the phased +roadmap, and the development log — lives in [`.claude/`](.claude): + +- [`Claude.md`](.claude/Claude.md) — vision, philosophy, stack, standards (start here) +- [`ARCHITECTURE.md`](.claude/ARCHITECTURE.md) — system decomposition +- [`DATA_MODEL.md`](.claude/DATA_MODEL.md) — PostgreSQL schema for the graph +- [`INTEGRATION_SYSTEM.md`](.claude/INTEGRATION_SYSTEM.md) — the Tool Adapter contract +- [`SECURITY_MODEL.md`](.claude/SECURITY_MODEL.md) — cross-cutting security posture +- [`Plan.md`](.claude/Plan.md) — the phased roadmap +- [`Progress.md`](.claude/Progress.md) — development log +- [`Routes.md`](.claude/Routes.md) — routing registry