fix: encode file keys in API paths

[goanpeca]

Summary

• Adds proxy-safe /files-by-key query-parameter API routes for metadata, download, preview, and delete while keeping the legacy path routes available.
• Updates the web API client to send file keys in query parameters, reject empty keys, and fall back to legacy routes when /files-by-key is unavailable during rolling deploys.
• Guards legacy fallback against route-collision and traversal-shaped keys so fallback does not return another route response shape.
• Adds regression coverage for nested keys, reserved characters, route-name collisions, traversal-like keys, endpoint suffix collisions, old-API fallback, and client request construction.
• Pins Vitest to 2.1.9 so the test dependency tree stays compatible with the repo Node >=20 policy.
• Updates the file browser feature doc with the new key-based API contract.

Linked issue

Closes #15

Tests run

• git diff --check
• pnpm lint
• pnpm --filter @vibe-coding-starter-kit/web test
• pnpm build
• pnpm lint:api
• pnpm test:api
• pnpm check:structure

Follow-up notes

• None.

[Copilot]

Pull request overview

This PR makes file-key operations proxy-safe by moving file keys out of URL path segments and into query parameters, while keeping the legacy path-based endpoints for compatibility. It updates both the FastAPI runtime and the Next.js web client, adds regression tests for tricky key shapes, and documents the new API contract.

Changes:

• Added /files-by-key/* query-parameter routes (metadata/download/preview/delete) and refactored legacy /files/{key:path} routes to reuse shared handlers.
• Updated the web API client to construct file-key requests via ?key=... and reject empty keys client-side.
• Added backend + frontend regression tests for reserved characters, nested keys, and traversal-like inputs; updated the file-browser feature doc.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
services/api/tests/test_file_key_routes.py	Adds API-level coverage to ensure the new query-param routes accept reserved key shapes and reject invalid keys without touching the repo layer.
services/api/app/runtime/files.py	Introduces /files-by-key endpoints and refactors existing key routes to share response/exception handling helpers.
apps/web/src/lib/api-client.ts	Switches file-key operations to query-parameter requests and adds a client-side empty-key guard.
apps/web/src/lib/api-client.test.ts	Adds Vitest coverage to ensure the client constructs the correct paths and rejects empty keys before calling fetch.
docs/features/file-browser.md	Updates the feature contract and verification steps to reflect the new /files-by-key API.
apps/web/package.json	Adds a test script and Vitest dependency for the web package.
pnpm-lock.yaml	Lockfile updates to include Vitest/Vite dependency graph changes.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[Copilot]

Pull request overview

Copilot reviewed 6 out of 7 changed files in this pull request and generated no new comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[sophiecarreras]

✅ B2 standards verified: S3-compatible API, custom user agent, and standardized B2_* env vars all pass. Good to merge.