junte/assessment-model
1
0
Fork 0
mirror of https://github.com/Hestia-Homes/assessment-model.git synced 2026-07-27 22:45:03 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(ara-projects): projects list, empty state and create-project modal

Browse source 
Setup wizard step 1/5 (#409).

The list is a Server Component, so the visibility rule runs before anything
reaches the browser and a project the user may not see is never serialised
to it. The rule itself is not restated: `listVisibleProjects` loads each
project's facts and asks `canViewProject` from `@/lib/projects/authz`.
Writing the `domna_admin_access OR owning-org OR contractor-org`
disjunction a second time in SQL would have given it two definitions free
to drift, and the acceptance criteria (client sees its own, contractor sees
what it is assigned to, internal sees all subject to `domna_admin_access`)
fall out of the one definition instead of being re-derived.

The cost is filtering in the app rather than the database, over two round
trips and no N+1. That is the right trade while a project is a works
programme and they number in the tens; if the table grows, the fix is a
superset prefilter that still lets `canViewProject` decide, not a WHERE
clause that re-implements it. Flagged in the function's own docs.

Creation reuses the same guard rather than inventing a "can create" rule:
`prospectiveProjectFacts` builds the facts the project *would* have, and
`canManageProject` judges them. One consequence is worth knowing, and is
covered by a test — `domna_admin_access` gates the `internal` role, so a
Domna user creating for an organisation they are not a member of must grant
that access. Without it they would be creating a project they could not
then see, and the guard refuses rather than producing an orphan. The modal
offers only organisations the user may pick, but the route handler re-checks
the submitted one: a hidden option is not a permission.

`createProjectSchema` is shared by the form (as a zodResolver) and the route
handler (as the body parser), so the two cannot disagree about what a valid
draft is. Empty strings from untouched inputs normalise to undefined rather
than reaching the columns as "".

Also updates projects-shell.cy.js. Its "renders the per-project dashboard
shell" test passed only because the authz stub could never return false;
with the real lib wired in, /projects/<id> is a 404 without standing on
that project, so the test now asserts that instead.

TESTS: the vitest unit tests pass (50, no database connection). Cypress was
NOT run — this environment's DATABASE_URL points at production. The new
spec is therefore unverified, and its end-to-end half, which INSERTs, is
gated behind CYPRESS_ARA_PROJECTS_E2E_WRITES so it cannot fire by accident;
it also needs the #407 seed migration (0274) applied, which has not been run
against any database yet either.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Daniel Roth 2026-07-21 16:52:53 +00:00
parent 2ba36470df
commit a7a1f8ee98
8 changed files with 1254 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

191
cypress/e2e/projects/create-project.cy.js Normal file
View file

@ -0,0 +1,191 @@
/**
* Ara Projects — projects list, empty state and create-project modal (#409)
*
* Two groups, because one of them writes:
*
* 1. The UI group stubs POST /api/projects with cy.intercept. It exercises
* the empty state, the modal, client-side validation and the navigation
* to workstream selection without touching the database, so it is safe to
* run anywhere.
*
* 2. The end-to-end group performs a real create and is the acceptance
* criterion's "create a project end-to-end". It INSERTs, so it is gated
* behind CYPRESS_ARA_PROJECTS_E2E_WRITES and must only ever be pointed at
* a non-production database. It also needs the #407 reference-data
* migration (0274) applied, or the project-type select will be empty and
* the page will not offer the CTA at all.
*
* Like the shell spec, this uses `cy.login` (cypress/support/commands.ts) to
* mint a real next-auth JWE cookie, so NEXTAUTH_JWT_SECRET must be set.
*
* NOT YET RUN. The environment this was written in has DATABASE_URL pointing at
* production, so Cypress was deliberately not executed. Treat the selectors and
* assertions below as unverified until someone runs them against a scratch DB.
*/
const JWT_SECRET = Cypress.env("NEXTAUTH_JWT_SECRET");
const E2E_WRITES = Cypress.env("ARA_PROJECTS_E2E_WRITES");
const INTERNAL_USER = {
email: "dev@domna.homes",
name: "Internal User",
onboarded: true,
sub: "cypress-internal",
};
describe("Ara Projects — create project (stubbed)", function () {
beforeEach(function () {
if (!JWT_SECRET) {
cy.log("NEXTAUTH_JWT_SECRET not set — skipping");
this.skip();
}
cy.login(INTERNAL_USER);
});
it("offers the Create project CTA from the list", function () {
cy.visit("/projects");
// The CTA sits inside the welcome card when there are no projects, and in
// the page header once there are — either way there is exactly one.
cy.get("[data-testid=create-project-trigger]").should("be.visible").click();
cy.get("[data-testid=create-project-form]").should("be.visible");
cy.contains("Project details").should("be.visible");
});
it("shows the welcome empty state when the user has no visible projects", function () {
// Only meaningful on an instance with no projects visible to this user;
// where there are some, the list renders instead and this is skipped.
cy.visit("/projects");
cy.get("body").then(($body) => {
if ($body.find("[data-testid=projects-list-empty]").length === 0) {
cy.log("user has visible projects — empty state not applicable");
return;
}
cy.contains("Welcome to Ara Projects").should("be.visible");
cy.contains("How setup works").should("be.visible");
cy.get("[data-testid=create-project-trigger]").should("be.visible");
});
});
it("refuses to submit without a name and a project type", function () {
cy.visit("/projects");
cy.get("[data-testid=create-project-trigger]").click();
cy.intercept("POST", "/api/projects", cy.spy().as("createCall"));
cy.get("[data-testid=create-project-submit]").click();
cy.contains("Enter a project name").should("be.visible");
cy.get("@createCall").should("not.have.been.called");
});
it("rejects an end date before the start date", function () {
cy.visit("/projects");
cy.get("[data-testid=create-project-trigger]").click();
cy.get("[data-testid=create-project-name]").type("Backwards dates");
cy.get("[data-testid=create-project-start-date]").type("2026-09-30");
cy.get("[data-testid=create-project-end-date]").type("2026-03-01");
cy.get("[data-testid=create-project-submit]").click();
cy.contains("The end date cannot be before the start date").should(
"be.visible",
);
});
it("navigates to workstream selection on success", function () {
cy.intercept("POST", "/api/projects", {
statusCode: 201,
body: { id: "4242" },
}).as("createProject");
cy.visit("/projects");
cy.get("[data-testid=create-project-trigger]").click();
cy.get("[data-testid=create-project-name]").type("Riverside retrofit 2026");
selectFirstOption("create-project-organisation");
selectFirstOption("create-project-type");
cy.get("[data-testid=create-project-domna-admin-access]").click();
cy.get("[data-testid=create-project-submit]").click();
cy.wait("@createProject").then(({ request }) => {
expect(request.body.name).to.eq("Riverside retrofit 2026");
expect(request.body.domnaAdminAccess).to.eq(true);
});
cy.location("pathname").should("eq", "/projects/4242/setup/workstreams");
});
it("surfaces the server's error message on a refusal", function () {
cy.intercept("POST", "/api/projects", {
statusCode: 403,
body: { error: "You cannot create a project for that organisation." },
}).as("createProject");
cy.visit("/projects");
cy.get("[data-testid=create-project-trigger]").click();
cy.get("[data-testid=create-project-name]").type("Not mine");
selectFirstOption("create-project-organisation");
selectFirstOption("create-project-type");
cy.get("[data-testid=create-project-submit]").click();
cy.wait("@createProject");
cy.get("[data-testid=create-project-error]")
.should("be.visible")
.and("contain", "cannot create a project for that organisation");
cy.location("pathname").should("eq", "/projects");
});
});
describe("Ara Projects — create project (end to end, writes)", function () {
beforeEach(function () {
if (!JWT_SECRET || !E2E_WRITES) {
cy.log(
"ARA_PROJECTS_E2E_WRITES not set — skipping the writing happy path",
);
this.skip();
}
cy.login(INTERNAL_USER);
});
it("creates a project and lands on workstream selection", function () {
// Unique per run so repeated runs do not collide on a name a human is
// eyeballing later. `project.name` has no unique constraint; this is for
// legibility, not correctness.
const name = `Cypress project ${Date.now()}`;
cy.visit("/projects");
cy.get("[data-testid=create-project-trigger]").click();
cy.get("[data-testid=create-project-name]").type(name);
selectFirstOption("create-project-organisation");
selectFirstOption("create-project-type");
cy.get("[data-testid=create-project-description]").type(
"Created by the Cypress happy path.",
);
cy.get("[data-testid=create-project-start-date]").type("2026-03-01");
cy.get("[data-testid=create-project-end-date]").type("2026-09-30");
// Required for an internal user creating on behalf of an organisation they
// are not a member of — without it the guard refuses, by design.
cy.get("[data-testid=create-project-domna-admin-access]").click();
cy.get("[data-testid=create-project-submit]").click();
cy.location("pathname").should("match", /^\/projects\/\d+\/setup\/workstreams$/);
// The new project is now visible in the list, which is the visibility rule
// agreeing with the write that just happened.
cy.visit("/projects");
cy.get("[data-testid=projects-list]").should("exist");
cy.contains("[data-testid=projects-list-item]", name).should("be.visible");
});
});
/**
* Pick the first item in a shadcn/Radix `Select`. The options live in a portal
* outside the trigger, so this opens the trigger and then reaches for the
* listbox at the document root.
*/
function selectFirstOption(testId) {
cy.get(`[data-testid=${testId}]`).click();
cy.get("[role=option]").first().click();
}

32
cypress/e2e/projects/projects-shell.cy.js
View file

@ -76,7 +76,17 @@ describe("Ara Projects route shell", function () {
cy.get("[data-testid=projects-shell]").should("exist");
});
it("renders the per-project dashboard shell and its nav", function () {
// This assertion changed with #409. While the authz stub was in place,
// `canViewProject` could never return false, so /projects/<anything> rendered
// the dashboard shell for any signed-in user — which is what this test used
// to check. The real lib (#408) is now wired in, so a project the user has no
// standing on is a 404, and a project id that does not exist is the same 404
// (deliberately indistinguishable, so Project existence does not leak).
//
// Rendering the dashboard shell therefore now needs a real, visible project,
// which is covered by the create-project happy path in create-project.cy.js
// rather than by a hardcoded id here.
it("404s on a project the user has no standing on", function () {
cy.login({
email: "dev@domna.homes",
name: "Internal User",
@ -84,13 +94,21 @@ describe("Ara Projects route shell", function () {
sub: "cypress-internal",
});
cy.visit("/projects/1");
cy.request({ url: "/projects/999999999", failOnStatusCode: false })
.its("status")
.should("eq", 404);
});
cy.get("[data-testid=project-shell]").should("exist");
cy.get("[data-testid=project-dashboard-heading]").should("be.visible");
["dashboard", "workOrders", "import", "settings"].forEach((item) => {
cy.get(`[data-testid=projects-nav-${item}]`).should("be.visible");
it("404s on a malformed project id", function () {
cy.login({
email: "dev@domna.homes",
name: "Internal User",
onboarded: true,
sub: "cypress-internal",
});
cy.request({ url: "/projects/not-an-id", failOnStatusCode: false })
.its("status")
.should("eq", 404);
});
});

80
src/app/api/projects/route.ts Normal file
View file

@ -0,0 +1,80 @@
import { NextRequest, NextResponse } from "next/server";
import { getServerSession } from "next-auth";
import { AuthOptions } from "@/app/api/auth/[...nextauth]/authOptions";
import { canManageProject } from "@/lib/projects/authz";
import {
createProjectSchema,
prospectiveProjectFacts,
} from "@/lib/projects/createProject";
import { loadAuthzUserByEmail } from "@/app/repositories/projects/authzRepository";
import {
insertProject,
organisationExists,
projectTypeExists,
} from "@/app/repositories/projects/projectsRepository";
/**
* POST /api/projects — create an Ara Project (issue #409).
*
* The authorization question "may this user create a project for this
* organisation?" is answered by the *existing* guard: build the facts the
* project would have once created and ask `canManageProject`. That keeps
* creation on the same rule as every other management action instead of
* inventing a parallel one.
*
* The rule has a consequence worth naming: `domna_admin_access` gates the
* `internal` role, so a Domna user creating a project for an organisation they
* are not a member of must grant that access. Without it they would be
* creating a project they could not then see, and the guard refuses rather
* than producing an orphan.
*/
export async function POST(req: NextRequest) {
const session = await getServerSession(AuthOptions);
if (!session?.user?.email) {
return NextResponse.json({ error: "Unauthorised" }, { status: 401 });
}
const user = await loadAuthzUserByEmail(session.user.email);
if (!user) {
return NextResponse.json({ error: "Unauthorised" }, { status: 401 });
}
const parsed = createProjectSchema.safeParse(await req.json().catch(() => null));
if (!parsed.success) {
return NextResponse.json(
{ error: parsed.error.issues[0]?.message ?? "Invalid body" },
{ status: 400 },
);
}
const draft = parsed.data;
if (!canManageProject(user, prospectiveProjectFacts(draft))) {
return NextResponse.json(
{
error:
"You cannot create a project for that organisation. Granting Domna admin access is required for an organisation you are not a member of.",
},
{ status: 403 },
);
}
// Checked after authorization so an unauthorized caller cannot use the
// difference between 400 and 403 to probe which organisations exist.
const projectTypeId = BigInt(draft.projectTypeId);
const [orgOk, typeOk] = await Promise.all([
organisationExists(draft.organisationId),
projectTypeExists(projectTypeId),
]);
if (!orgOk) {
return NextResponse.json({ error: "Unknown organisation" }, { status: 400 });
}
if (!typeOk) {
return NextResponse.json({ error: "Unknown project type" }, { status: 400 });
}
const id = await insertProject({ ...draft, projectTypeId });
// `id` is a bigint; JSON cannot carry one, so the client gets a string and
// uses it to build the next wizard step's path.
return NextResponse.json({ id: id.toString() }, { status: 201 });
}

333
src/app/projects/components/CreateProjectDialog.tsx Normal file
View file

@ -0,0 +1,333 @@
"use client";
import { useState } from "react";
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import { useMutation } from "@tanstack/react-query";
import { useRouter } from "next/navigation";
import { PlusIcon } from "@heroicons/react/24/outline";
import {
createProjectSchema,
type CreateProjectFormValues,
type SelectOption,
} from "@/lib/projects/createProject";
import { Button } from "@/app/shadcn_components/ui/button";
import { Checkbox } from "@/app/shadcn_components/ui/checkbox";
import {
Dialog,
DialogContent,
DialogDescription,
DialogFooter,
DialogHeader,
DialogTitle,
} from "@/app/shadcn_components/ui/dialog";
import {
Form,
FormControl,
FormDescription,
FormField,
FormItem,
FormLabel,
FormMessage,
} from "@/app/shadcn_components/ui/form";
import { Input } from "@/app/shadcn_components/ui/input";
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/app/shadcn_components/ui/select";
/**
* The HTTP call, kept outside the component so the component itself contains
* no `fetch` — TanStack Query owns the request lifecycle.
*
* Route handlers in this codebase answer errors as `{ error: string }`, so a
* failure is surfaced with the server's own message rather than a generic one.
*/
async function createProject(
values: CreateProjectFormValues,
): Promise<{ id: string }> {
const response = await fetch("/api/projects", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(values),
});
const body = await response.json().catch(() => null);
if (!response.ok) {
throw new Error(body?.error ?? "Could not create the project");
}
return body;
}
export interface CreateProjectDialogProps {
organisations: SelectOption[];
projectTypes: SelectOption[];
/** Rendered as the trigger's label — "Create project" everywhere so far. */
label?: string;
}
/**
* Create-project modal — step 1 of the setup wizard.
*
* On success it navigates to workstream selection (#410) rather than back to
* the list: creating a project is the start of setup, not the end of it.
*/
export function CreateProjectDialog({
organisations,
projectTypes,
label = "Create project",
}: CreateProjectDialogProps) {
const router = useRouter();
const [open, setOpen] = useState(false);
const form = useForm<CreateProjectFormValues>({
resolver: zodResolver(createProjectSchema),
defaultValues: {
name: "",
// A client user typically belongs to exactly one organisation, so the
// select is pre-filled and effectively fixed. Internal users, offered
// every organisation, start with no choice made.
organisationId: organisations.length === 1 ? organisations[0].id : "",
projectTypeId: "",
description: "",
startDate: "",
endDate: "",
domnaAdminAccess: false,
},
});
const mutation = useMutation(createProject, {
onSuccess: ({ id }) => router.push(`/projects/${id}/setup/workstreams`),
});
// Deliberately not reset on close: a user who dismissed the dialog by
// accident gets their typing back. A completed creation navigates away, so
// stale values are never shown against a project that already exists.
function onOpenChange(next: boolean) {
if (!next && mutation.isLoading) return;
setOpen(next);
if (next) mutation.reset();
}
return (
<>
<Button
onClick={() => onOpenChange(true)}
data-testid="create-project-trigger"
>
<PlusIcon className="h-4 w-4 mr-2" />
{label}
</Button>
<Dialog open={open} onOpenChange={onOpenChange}>
<DialogContent className="sm:max-w-lg max-h-[90vh] overflow-y-auto">
<DialogHeader>
<DialogTitle>Project details</DialogTitle>
<DialogDescription>
Step 1 of 5 — name the project and choose who it belongs to. You
will pick its workstreams next.
</DialogDescription>
</DialogHeader>
<Form {...form}>
<form
onSubmit={form.handleSubmit((values) => mutation.mutate(values))}
className="space-y-4"
data-testid="create-project-form"
>
<FormField
control={form.control}
name="name"
render={({ field }) => (
<FormItem>
<FormLabel>Project name</FormLabel>
<FormControl>
<Input
{...field}
autoFocus
placeholder="e.g. Riverside retrofit 2026"
data-testid="create-project-name"
/>
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="organisationId"
render={({ field }) => (
<FormItem>
<FormLabel>Client</FormLabel>
<Select
onValueChange={field.onChange}
value={field.value}
disabled={organisations.length <= 1}
>
<FormControl>
<SelectTrigger data-testid="create-project-organisation">
<SelectValue placeholder="Select client..." />
</SelectTrigger>
</FormControl>
<SelectContent>
{organisations.map((option) => (
<SelectItem key={option.id} value={option.id}>
{option.name}
</SelectItem>
))}
</SelectContent>
</Select>
{organisations.length === 1 && (
<FormDescription>
Projects you create belong to your organisation.
</FormDescription>
)}
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="projectTypeId"
render={({ field }) => (
<FormItem>
<FormLabel>Project type</FormLabel>
<Select onValueChange={field.onChange} value={field.value}>
<FormControl>
<SelectTrigger data-testid="create-project-type">
<SelectValue placeholder="Select type..." />
</SelectTrigger>
</FormControl>
<SelectContent>
{projectTypes.map((option) => (
<SelectItem key={option.id} value={option.id}>
{option.name}
</SelectItem>
))}
</SelectContent>
</Select>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="description"
render={({ field }) => (
<FormItem>
<FormLabel>Description</FormLabel>
<FormControl>
<textarea
{...field}
rows={3}
className="flex w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50"
placeholder="What is this programme of works for?"
data-testid="create-project-description"
/>
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<div className="grid grid-cols-2 gap-4">
<FormField
control={form.control}
name="startDate"
render={({ field }) => (
<FormItem>
<FormLabel>Start date</FormLabel>
<FormControl>
<Input
{...field}
type="date"
data-testid="create-project-start-date"
/>
</FormControl>
<FormMessage />
</FormItem>
)}
/>
<FormField
control={form.control}
name="endDate"
render={({ field }) => (
<FormItem>
<FormLabel>Estimated end date</FormLabel>
<FormControl>
<Input
{...field}
type="date"
data-testid="create-project-end-date"
/>
</FormControl>
<FormMessage />
</FormItem>
)}
/>
</div>
<FormField
control={form.control}
name="domnaAdminAccess"
render={({ field }) => (
<FormItem className="flex flex-row items-start gap-3 rounded-md border p-4">
<FormControl>
<Checkbox
checked={field.value}
onCheckedChange={field.onChange}
data-testid="create-project-domna-admin-access"
/>
</FormControl>
<div className="space-y-1 leading-none">
<FormLabel>Grant Domna admin access</FormLabel>
<FormDescription>
Domna admins can help configure this project, support
imports, and view project data. This can be revoked at
any time.
</FormDescription>
</div>
</FormItem>
)}
/>
{mutation.isError && (
<p
role="alert"
className="text-sm text-red-600"
data-testid="create-project-error"
>
{(mutation.error as Error).message}
</p>
)}
<DialogFooter>
<Button
type="button"
variant="outline"
onClick={() => onOpenChange(false)}
disabled={mutation.isLoading}
>
Cancel
</Button>
<Button
type="submit"
disabled={mutation.isLoading}
data-testid="create-project-submit"
>
{mutation.isLoading ? "Creating…" : "Create and continue"}
</Button>
</DialogFooter>
</form>
</Form>
</DialogContent>
</Dialog>
</>
);
}

207
src/app/projects/page.tsx
View file

@ -1,49 +1,194 @@
import { Squares2X2Icon } from "@heroicons/react/24/outline";
import { requireProjectsSession } from "./guards";
import Link from "next/link";
import { FolderOpenIcon } from "@heroicons/react/24/outline";
import { requireProjectsUser } from "./guards";
import { CreateProjectDialog } from "./components/CreateProjectDialog";
import {
listOrganisationOptions,
listProjectTypes,
listVisibleProjects,
} from "@/app/repositories/projects/projectsRepository";
import type { ProjectListItem } from "@/lib/projects/createProject";
import {
Card,
CardContent,
CardDescription,
CardHeader,
CardTitle,
} from "@/app/shadcn_components/ui/card";
export const metadata = {
title: "Projects | Ara",
};
/** The wizard's shape, shown on the empty state so setup is not a surprise. */
const SETUP_STEPS = [
{
title: "Project details",
body: "Name the project, choose the client organisation and the type of works.",
},
{
title: "Workstreams and stages",
body: "Pick the categories of work and the stage ladder each one follows.",
},
{
title: "Documents and permissions",
body: "Say what evidence each workstream needs, and who may upload it.",
},
{
title: "Import and validate work orders",
body: "Bring in the work orders and check them before they go live.",
},
];
function formatDateRange(project: ProjectListItem): string | null {
const format = (value: string) =>
new Intl.DateTimeFormat("en-GB", {
day: "2-digit",
month: "short",
year: "numeric",
timeZone: "UTC",
}).format(new Date(`${value}T00:00:00Z`));
if (project.startDate && project.endDate) {
return `${format(project.startDate)} — ${format(project.endDate)}`;
}
if (project.startDate) return `From ${format(project.startDate)}`;
if (project.endDate) return `Until ${format(project.endDate)}`;
return null;
}
/**
* Projects list.
* Projects list — the entry point to Ara Projects (issue #409).
*
* Stub for now — the real list (and its visibility rule: internal users see
* everything, client-org members see their org's Projects, contractor-org
* members see Projects their org is assigned to a Workstream on) arrives with
* the list issue on top of the authorization work in #408.
* A Server Component: the visibility rule is enforced before anything reaches
* the browser, so a project the user may not see is never serialised to it.
* Only the create-project modal is client-side, and it is handed its select
* options as props rather than fetching them — the server already knows which
* organisations this user may choose.
*/
export default async function ProjectsListPage() {
await requireProjectsSession();
const user = await requireProjectsUser();
const [projects, organisations, projectTypes] = await Promise.all([
listVisibleProjects(user),
listOrganisationOptions(user),
listProjectTypes(),
]);
// A user with no organisation to create *for*, or an instance whose
// reference data has not been seeded, cannot complete the form — so the CTA
// is not offered. (The route handler refuses these cases regardless; this
// only avoids presenting a dead end.)
const canCreate = organisations.length > 0 && projectTypes.length > 0;
return (
<div className="max-w-4xl mx-auto px-6 py-10">
<div className="mb-8">
<p className="text-xs font-semibold text-gray-400 uppercase tracking-widest mb-1">
Ara Projects
</p>
<h1 className="text-3xl font-extrabold text-gray-900 tracking-tight">
Projects
</h1>
<p className="text-sm text-gray-500 mt-1">
Works programmes owned by your organisation.
</p>
<div className="mb-8 flex items-start justify-between gap-4">
<div>
<p className="text-xs font-semibold text-gray-400 uppercase tracking-widest mb-1">
Ara Projects
</p>
<h1 className="text-3xl font-extrabold text-gray-900 tracking-tight">
Projects
</h1>
<p className="text-sm text-gray-500 mt-1">
Works programmes owned by your organisation.
</p>
</div>
{projects.length > 0 && canCreate && (
<CreateProjectDialog
organisations={organisations}
projectTypes={projectTypes}
/>
)}
</div>
<div
className="flex flex-col items-center justify-center py-24 border-2 border-dashed border-gray-200 rounded-2xl text-center"
data-testid="projects-list-empty"
>
<div className="w-14 h-14 rounded-full bg-gray-100 flex items-center justify-center mb-4">
<Squares2X2Icon className="h-7 w-7 text-gray-400" />
{projects.length === 0 ? (
<div data-testid="projects-list-empty">
<Card className="text-center py-12">
<CardHeader>
<div className="mx-auto w-14 h-14 rounded-full bg-gray-100 flex items-center justify-center mb-2">
<FolderOpenIcon className="h-7 w-7 text-gray-400" />
</div>
<CardTitle className="text-2xl">Welcome to Ara Projects</CardTitle>
<CardDescription className="max-w-md mx-auto">
You don&apos;t have any active projects yet. Start by creating a
project to organise your workstreams, track progress and manage
contractors.
</CardDescription>
</CardHeader>
{canCreate && (
<CardContent className="flex justify-center">
<CreateProjectDialog
organisations={organisations}
projectTypes={projectTypes}
/>
</CardContent>
)}
</Card>
<div className="mt-10">
<h2 className="text-sm font-semibold text-gray-700 mb-4">
How setup works
</h2>
<ol className="grid gap-3 sm:grid-cols-2">
{SETUP_STEPS.map((step, index) => (
<li
key={step.title}
className="flex gap-3 rounded-xl border border-gray-200 p-4"
>
<span className="shrink-0 w-6 h-6 rounded-full bg-gray-100 text-gray-600 text-xs font-semibold flex items-center justify-center">
{index + 1}
</span>
<div>
<p className="text-sm font-semibold text-gray-800">
{step.title}
</p>
<p className="text-sm text-gray-500 mt-0.5">{step.body}</p>
</div>
</li>
))}
</ol>
</div>
</div>
<p className="text-base font-semibold text-gray-700 mb-1">
No projects to show yet
</p>
<p className="text-sm text-gray-400">
The projects list is not built yet.
</p>
</div>
) : (
<ul className="space-y-3" data-testid="projects-list">
{projects.map((project) => {
const dates = formatDateRange(project);
return (
<li key={project.id}>
<Link
href={`/projects/${project.id}`}
className="block rounded-xl border border-gray-200 p-5 hover:border-gray-300 hover:bg-gray-50 transition-colors"
data-testid="projects-list-item"
>
<div className="flex items-baseline justify-between gap-4">
<h2 className="text-base font-semibold text-gray-900">
{project.name}
</h2>
<span className="shrink-0 text-xs font-medium text-gray-500 bg-gray-100 rounded-full px-2.5 py-1">
{project.projectTypeName}
</span>
</div>
{project.organisationName && (
<p className="text-sm text-gray-500 mt-1">
{project.organisationName}
</p>
)}
{project.description && (
<p className="text-sm text-gray-600 mt-2 line-clamp-2">
{project.description}
</p>
)}
{dates && (
<p className="text-xs text-gray-400 mt-3">{dates}</p>
)}
</Link>
</li>
);
})}
</ul>
)}
</div>
);
}

192
src/app/repositories/projects/projectsRepository.ts Normal file
View file

@ -0,0 +1,192 @@
/**
* Ara Projects persistence for the projects list and the create-project flow
* (issue #409).
*
* Same boundary as `./authzRepository`: Drizzle lives here, decisions live in
* `@/lib/projects/*`. Nothing in this file decides who may see what — it loads
* facts and hands them to `canViewProject`.
*/
import { db } from "@/app/db/db";
import { asc, desc, eq, inArray } from "drizzle-orm";
import { organisation } from "@/app/db/schema/organisation";
import {
project,
projectType,
projectWorkstream,
projectWorkstreamContractor,
} from "@/app/db/schema/projects/projects";
import {
canViewProject,
isInternalEmail,
type AuthzUser,
type ProjectAuthzFacts,
} from "@/lib/projects/authz";
import type { ProjectListItem, SelectOption } from "@/lib/projects/createProject";
/**
* Every project the user may see, newest first.
*
* The visibility rule is **not** restated in SQL. Doing so would mean writing
* the `domna_admin_access OR owning-org OR contractor-org` disjunction a second
* time, in a second language, free to drift from `resolveProjectRole`. Instead
* this loads each project's facts and asks `canViewProject` — so the rule has
* exactly one definition, and the acceptance criteria (client sees its own,
* contractor sees what it is assigned to, internal sees all subject to
* `domna_admin_access`) are satisfied by construction.
*
* The cost is that the filtering happens in the app rather than the database,
* over two round trips and no N+1. That is the right trade at v1 scale, where
* a project is a works programme and they number in the tens. If the table
* grows by orders of magnitude, the fix is a **superset** prefilter in SQL —
* narrowing the rows loaded while still letting `canViewProject` make the
* final call — not a reimplementation of the rule in a WHERE clause.
*/
export async function listVisibleProjects(
user: AuthzUser,
): Promise<ProjectListItem[]> {
const [rows, contractorRows] = await Promise.all([
db
.select({
id: project.id,
name: project.name,
description: project.description,
startDate: project.startDate,
endDate: project.endDate,
organisationId: project.organisationId,
organisationName: organisation.name,
domnaAdminAccess: project.domnaAdminAccess,
projectTypeName: projectType.name,
})
.from(project)
.innerJoin(projectType, eq(project.projectTypeId, projectType.id))
.leftJoin(organisation, eq(project.organisationId, organisation.id))
.orderBy(desc(project.id)),
db
.selectDistinct({
projectId: projectWorkstream.projectId,
organisationId: projectWorkstreamContractor.organisationId,
})
.from(projectWorkstreamContractor)
.innerJoin(
projectWorkstream,
eq(projectWorkstreamContractor.projectWorkstreamId, projectWorkstream.id),
),
]);
const contractorsByProject = new Map<string, string[]>();
for (const row of contractorRows) {
const key = row.projectId.toString();
const existing = contractorsByProject.get(key);
if (existing) existing.push(row.organisationId);
else contractorsByProject.set(key, [row.organisationId]);
}
return rows
.filter((row) => {
const facts: ProjectAuthzFacts = {
id: row.id,
organisationId: row.organisationId,
domnaAdminAccess: row.domnaAdminAccess,
contractorOrganisationIds:
contractorsByProject.get(row.id.toString()) ?? [],
};
return canViewProject(user, facts);
})
.map((row) => ({
id: row.id.toString(),
name: row.name,
projectTypeName: row.projectTypeName,
organisationName: row.organisationName,
description: row.description,
startDate: row.startDate,
endDate: row.endDate,
}));
}
/** The seeded project types, for the modal's Project type select. */
export async function listProjectTypes(): Promise<SelectOption[]> {
const rows = await db
.select({ id: projectType.id, name: projectType.name })
.from(projectType)
.orderBy(asc(projectType.name));
return rows.map((r) => ({ id: r.id.toString(), name: r.name }));
}
/**
* The organisations the user may create a project *for*.
*
* Internal users pick any organisation; everyone else is confined to the ones
* they belong to — which for a typical client user is exactly one, so the
* select is effectively fixed. This only shapes the choices offered: the
* server still re-checks the submitted organisation against
* `canManageProject`, because a hidden option is not a permission.
*
* `organisation.name` is nullable in the schema; unnamed rows are dropped
* rather than rendered as a blank option nobody can identify.
*/
export async function listOrganisationOptions(
user: AuthzUser,
): Promise<SelectOption[]> {
if (!isInternalEmail(user.email) && user.organisationIds.length === 0) {
return [];
}
const rows = await db
.select({ id: organisation.id, name: organisation.name })
.from(organisation)
.where(
isInternalEmail(user.email)
? undefined
: inArray(organisation.id, user.organisationIds),
)
.orderBy(asc(organisation.name));
return rows.flatMap((r) => (r.name ? [{ id: r.id, name: r.name }] : []));
}
/** Whether a project type id names a seeded row. */
export async function projectTypeExists(id: bigint): Promise<boolean> {
const [found] = await db
.select({ id: projectType.id })
.from(projectType)
.where(eq(projectType.id, id))
.limit(1);
return Boolean(found);
}
/** Whether an organisation id names a real organisation. */
export async function organisationExists(id: string): Promise<boolean> {
const [found] = await db
.select({ id: organisation.id })
.from(organisation)
.where(eq(organisation.id, id))
.limit(1);
return Boolean(found);
}
/** Insert the project row and return its new id. */
export async function insertProject(values: {
name: string;
organisationId: string;
projectTypeId: bigint;
description?: string;
startDate?: string;
endDate?: string;
domnaAdminAccess: boolean;
}): Promise<bigint> {
const [created] = await db
.insert(project)
.values({
name: values.name,
organisationId: values.organisationId,
projectTypeId: values.projectTypeId,
description: values.description ?? null,
startDate: values.startDate ?? null,
endDate: values.endDate ?? null,
domnaAdminAccess: values.domnaAdminAccess,
})
.returning({ id: project.id });
return created.id;
}

163
src/lib/projects/createProject.test.ts Normal file
View file

@ -0,0 +1,163 @@
import { describe, expect, it } from "vitest";
import {
createProjectSchema,
prospectiveProjectFacts,
} from "./createProject";
import { canManageProject, type AuthzUser } from "./authz";
const CLIENT_ORG = "11111111-1111-1111-1111-111111111111";
const OTHER_ORG = "22222222-2222-2222-2222-222222222222";
function validDraft(overrides: Record<string, unknown> = {}) {
return {
name: "Riverside retrofit 2026",
organisationId: CLIENT_ORG,
projectTypeId: "1",
description: "",
startDate: "",
endDate: "",
domnaAdminAccess: false,
...overrides,
};
}
function makeUser(overrides: Partial<AuthzUser> = {}): AuthzUser {
return {
id: 1n,
email: "someone@landlord.example",
organisationIds: [],
...overrides,
};
}
describe("createProjectSchema", () => {
it("accepts a minimal draft", () => {
const parsed = createProjectSchema.parse(validDraft());
expect(parsed.name).toBe("Riverside retrofit 2026");
expect(parsed.organisationId).toBe(CLIENT_ORG);
expect(parsed.domnaAdminAccess).toBe(false);
});
it("normalises the untouched optional fields to undefined", () => {
// An untouched <input> submits "", which must not be written to the column
// as an empty string masquerading as a description or a date.
const parsed = createProjectSchema.parse(validDraft());
expect(parsed.description).toBeUndefined();
expect(parsed.startDate).toBeUndefined();
expect(parsed.endDate).toBeUndefined();
});
it("trims and keeps a real description", () => {
const parsed = createProjectSchema.parse(
validDraft({ description: " Phase one " }),
);
expect(parsed.description).toBe("Phase one");
});
it("rejects a blank or whitespace-only name", () => {
expect(createProjectSchema.safeParse(validDraft({ name: "" })).success).toBe(
false,
);
expect(
createProjectSchema.safeParse(validDraft({ name: " " })).success,
).toBe(false);
});
it("rejects an organisation id that is not a uuid", () => {
expect(
createProjectSchema.safeParse(validDraft({ organisationId: "acme" })).success,
).toBe(false);
});
it("rejects a non-numeric project type id", () => {
expect(
createProjectSchema.safeParse(validDraft({ projectTypeId: "retrofit" }))
.success,
).toBe(false);
});
it("rejects a malformed date", () => {
expect(
createProjectSchema.safeParse(validDraft({ startDate: "01/02/2026" }))
.success,
).toBe(false);
});
it("accepts an end date on or after the start date", () => {
for (const endDate of ["2026-03-01", "2026-09-30"]) {
const parsed = createProjectSchema.safeParse(
validDraft({ startDate: "2026-03-01", endDate }),
);
expect(parsed.success).toBe(true);
}
});
it("rejects an end date before the start date, against the end field", () => {
const parsed = createProjectSchema.safeParse(
validDraft({ startDate: "2026-09-30", endDate: "2026-03-01" }),
);
expect(parsed.success).toBe(false);
if (!parsed.success) {
expect(parsed.error.issues[0].path).toEqual(["endDate"]);
}
});
it("allows one date without the other", () => {
expect(
createProjectSchema.safeParse(validDraft({ startDate: "2026-03-01" }))
.success,
).toBe(true);
expect(
createProjectSchema.safeParse(validDraft({ endDate: "2026-03-01" })).success,
).toBe(true);
});
});
describe("prospectiveProjectFacts", () => {
it("lets a member of the owning organisation create the project", () => {
const user = makeUser({ organisationIds: [CLIENT_ORG] });
const draft = createProjectSchema.parse(validDraft());
expect(canManageProject(user, prospectiveProjectFacts(draft))).toBe(true);
});
it("refuses a user with no standing on the chosen organisation", () => {
const user = makeUser({ organisationIds: [OTHER_ORG] });
const draft = createProjectSchema.parse(validDraft());
expect(canManageProject(user, prospectiveProjectFacts(draft))).toBe(false);
});
it("lets an internal user create for any organisation when access is granted", () => {
const user = makeUser({ email: "dev@domna.homes" });
const draft = createProjectSchema.parse(
validDraft({ domnaAdminAccess: true }),
);
expect(canManageProject(user, prospectiveProjectFacts(draft))).toBe(true);
});
it("refuses an internal non-member who withholds Domna admin access", () => {
// `domna_admin_access` gates the internal role, so this draft would create
// a project its own author could not then see. Refusing is the rule
// working, not a gap in it.
const user = makeUser({ email: "dev@domna.homes" });
const draft = createProjectSchema.parse(
validDraft({ domnaAdminAccess: false }),
);
expect(canManageProject(user, prospectiveProjectFacts(draft))).toBe(false);
});
it("still lets an internal user who is a genuine member create without the toggle", () => {
const user = makeUser({
email: "dev@domna.homes",
organisationIds: [CLIENT_ORG],
});
const draft = createProjectSchema.parse(
validDraft({ domnaAdminAccess: false }),
);
expect(canManageProject(user, prospectiveProjectFacts(draft))).toBe(true);
});
it("grants nobody a contractor role on a project that has no workstreams yet", () => {
const draft = createProjectSchema.parse(validDraft());
expect(prospectiveProjectFacts(draft).contractorOrganisationIds).toEqual([]);
});
});

94
src/lib/projects/createProject.ts Normal file
View file

@ -0,0 +1,94 @@
/**
* The create-project draft: what the form collects, what the route handler
* accepts, and how it is turned into facts the authz guards can judge.
*
* Pure and db-free, like `./authz` — the schema is imported by both the client
* form (as a `zodResolver`) and `POST /api/projects` (as the request-body
* parser), so the two cannot drift into disagreeing about what a valid draft
* is. The client validates for the user's benefit; the server validates
* because the client cannot be trusted.
*
* Everything crossing the wire is a string: `project_type.id` is a bigint that
* JSON cannot carry, and `project.start_date` / `end_date` are Drizzle `date`
* columns, which round-trip as `YYYY-MM-DD`.
*/
import { z } from "zod";
import type { ProjectAuthzFacts } from "./authz";
/** `YYYY-MM-DD`, the wire and column format for the two date fields. */
const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
/**
* An optional free-text or date field. Empty strings are what an untouched
* `<input>` submits, so they are normalised to `undefined` rather than being
* written to the column as `""`.
*/
const optionalText = (schema: z.ZodString) =>
z
.union([schema, z.literal("")])
.optional()
.transform((value) => (value ? value : undefined));
export const createProjectSchema = z
.object({
name: z.string().trim().min(1, "Enter a project name").max(255),
organisationId: z.string().uuid("Select a client organisation"),
projectTypeId: z
.string()
.regex(/^\d+$/, "Select a project type"),
description: optionalText(z.string().trim().max(2000)),
startDate: optionalText(z.string().regex(ISO_DATE, "Enter a valid date")),
endDate: optionalText(z.string().regex(ISO_DATE, "Enter a valid date")),
domnaAdminAccess: z.boolean(),
})
// Lexicographic comparison is exact for zero-padded ISO dates, so this needs
// no Date parsing (and no timezone to get wrong).
.refine(
(draft) => !draft.startDate || !draft.endDate || draft.endDate >= draft.startDate,
{ message: "The end date cannot be before the start date", path: ["endDate"] },
);
/** The validated draft — the output type, after empty strings are dropped. */
export type CreateProjectDraft = z.output<typeof createProjectSchema>;
/** The form's working type — the input type, before the transforms run. */
export type CreateProjectFormValues = z.input<typeof createProjectSchema>;
/**
* The `ProjectAuthzFacts` a draft *would* have once created, so the same
* guards that police an existing project can police its creation — there is no
* separate "can create" rule to keep in step.
*
* `id` is a placeholder: the row has no key until it is inserted, and no guard
* in `./authz` reads it. `contractorOrganisationIds` is genuinely empty — a
* brand-new project has no workstreams, so nobody holds a contractor role on
* it and only the client (or an internal user the draft grants access to) can
* pass `canManageProject`.
*/
export function prospectiveProjectFacts(
draft: Pick<CreateProjectDraft, "organisationId" | "domnaAdminAccess">,
): ProjectAuthzFacts {
return {
id: 0n,
organisationId: draft.organisationId,
domnaAdminAccess: draft.domnaAdminAccess,
contractorOrganisationIds: [],
};
}
/** A project as the list page renders it. Ids are strings for the same reason. */
export interface ProjectListItem {
id: string;
name: string;
projectTypeName: string;
organisationName: string | null;
description: string | null;
startDate: string | null;
endDate: string | null;
}
/** An option in the modal's Client / Project type selects. */
export interface SelectOption {
id: string;
name: string;
}