feat(api): GET /projects list endpoint

[thewrz]

Why

The examples/web_ui_demo project switcher needs to enumerate projects. listProjects() exists in the DB layer (backs the MCP list_projects tool) but had no REST endpoint — GET /projects 404'd. Second of the roadmap-first reads unblocking the demo (after #226 / #227).

What

• GET /projects → ApiResponse<ProjectListItem[]> ({id, name}, ordered by name), reusing listProjects(pool).
• Adds the get: op to the existing /projects: openapi path + a ProjectListItem schema; contract gate response-covers it.

Testing

• Integration: GET /projects lists {id, name} incl. the test project (added to projects.integration.test.ts)
• Contract gate green (route↔spec + response-schema validation)
• pnpm lint clean (eslint + tsc + prettier)
• CI green

⚠️ Same pre-existing src/parser/docx/cpi.integration.test.ts failure on main (CPI source-inference) is unrelated to this PR.

🤖 Co-authored by Claude Opus 4.8. Closes #228.

Summary by CodeRabbit

New Features

• Added an unauthenticated GET /projects endpoint that returns a list of projects (including each project’s identifier and name) and orders them by project name.

Tests

• Expanded API integration coverage to validate the new /projects response, including contract/schema checks and deterministic name ordering.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: de89fdf6-4aef-4c88-98c2-6a5e82e106ea

📥 Commits

Reviewing files that changed from the base of the PR and between f935847 and 7819acb.

📒 Files selected for processing (1)

• src/api/projects.integration.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/api/projects.integration.test.ts

---

📝 Walkthrough

Walkthrough

Adds a GET /projects REST endpoint that returns all projects ordered by name. The change introduces the ProjectListItem schema and path operation in openapi.yaml, implements listProjectsHandler in src/api/projects.ts reusing the existing listProjects(pool) DB function, registers the route in router.ts, and validates with integration and contract tests.

Changes

GET /projects list endpoint

Layer / File(s)	Summary
OpenAPI schema and endpoint definition openapi.yaml	Adds the ProjectListItem schema (id UUID, name string) and the GET /projects path operation (operationId: listProjects) with 200 returning an array of ProjectListItem and 500 mapping to InternalServerError.
Handler implementation and router wiring src/api/projects.ts, src/api/router.ts	Extends the ../db/index.js import to include listProjects, adds the exported listProjectsHandler (returns 200 with projects array on success, 500 on error), imports the handler in router.ts, and registers router.get('/projects', listProjectsHandler).
Integration and contract tests src/api/contract.integration.test.ts, src/api/projects.integration.test.ts	Adds get /projects to RESPONSE_COVERED, adds a contract test asserting the 200 response matches the OpenAPI schema, and adds a GET /projects integration test verifying response shape and presence of a seeded project.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• wrzonance/SpecR#212: Established the response-contract gate infrastructure (RESPONSE_COVERED, assertResponse) that this PR directly extends by adding get /projects to the covered operations.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(api): GET /projects list endpoint' directly and clearly summarizes the main change: adding a GET /projects API endpoint to list projects.
Linked Issues check	✅ Passed	All acceptance criteria from issue #228 are met: OpenAPI documentation is added with contract validation, integration tests verify endpoint returns projects with {id, name}, and code passes linting.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing the GET /projects endpoint as defined in issue #228; no unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/api-projects-list

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

src/api/projects.integration.test.ts (1)

210-226: ⚡ Quick win

Pin the documented name-order guarantee in this integration test.

This test currently checks shape and membership, but not the “ordered by name” behavior the endpoint promises. Add an assertion that body.data is nondecreasing by name (and id as tie-breaker if you want to mirror DB ordering).

Suggested test assertion

   expect(Array.isArray(body.data)).toBe(true);
+  const sorted = [...body.data].sort((a, b) => {
+    const byName = a.name.localeCompare(b.name);
+    return byName !== 0 ? byName : a.id.localeCompare(b.id);
+  });
+  expect(body.data).toEqual(sorted);
+
   const mine = body.data.find((p) => p.id === testProjectId);

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/api/projects.integration.test.ts` around lines 210 - 226, The integration
test for listing projects does not verify the documented ordering guarantee that
results are sorted by name. After the existing loop that validates each
project's structure (in the test function that checks 'returns 200 listing
projects as {id, name}, including the test project'), add an assertion that
validates body.data is sorted in non-decreasing order by the name field,
optionally using id as a tie-breaker to match database ordering if needed. This
ensures the test pins down the documented API contract about result ordering.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/api/projects.integration.test.ts`:
- Around line 210-226: The integration test for listing projects does not verify
the documented ordering guarantee that results are sorted by name. After the
existing loop that validates each project's structure (in the test function that
checks 'returns 200 listing projects as {id, name}, including the test
project'), add an assertion that validates body.data is sorted in non-decreasing
order by the name field, optionally using id as a tie-breaker to match database
ordering if needed. This ensures the test pins down the documented API contract
about result ordering.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a876a28b-cad9-4ba0-8e24-23f1d4570765

📥 Commits

Reviewing files that changed from the base of the PR and between 9dceb3f and f935847.

📒 Files selected for processing (5)

• openapi.yaml
• src/api/contract.integration.test.ts
• src/api/projects.integration.test.ts
• src/api/projects.ts
• src/api/router.ts

[thewrz]

CodeRabbit body nitpick addressed (no inline thread to resolve): pin the name-order guarantee in projects.integration.test.ts. Fixed in 7819acb.

I implemented it deterministically rather than the suggested global expect(body.data).toEqual(sorted): that assertion compares the Postgres ORDER BY name result against a JS localeCompare sort, which is flaky when the DB collation differs from JS ordering and when other suites' projects (e.g. the contract test's lowercase contract-… project) are present in the shared DB. Instead I insert two controlled projects (zzz-order-a/zzz-order-b) and assert that subset comes back in order — pinning the guarantee without collation/cross-suite flakiness.