[kineticsystem]

Summary

API documentation

• The server describes its API in OpenAPI 3.1 at /api/openapi.json and serves Swagger UI at /api/docs, where each endpoint can be browsed and tried ("Try it out").
• Swagger UI comes from the swagger-ui-dist npm package, so the page works offline. The install script of its telemetry dependency @scarf/scarf is disabled in pnpm-workspace.yaml.
• The description is written by hand in src/server/openapi.ts. Its servers entry is filled in with the address the client used (from Host, and X-Forwarded-Proto behind a proxy), so Postman can import it without setting baseUrl.
• The README has a new "The HTTP API" section: the two URLs, importing into Postman, and a warning that tried requests change the real files.

HTTP conventions for files (breaking for other clients of the API; the editor's frontend is the only one and is updated)

• PUT/DELETE /api/file?path=a/b.xml → PUT/DELETE /api/files/a/b.xml. Slashes may be sent plain or as %2F; everything still goes through safePath, and malformed encoding gets a 400.
• PUT answers 201 Created when it creates the file, 200 OK when it overwrites it.
• Other methods on a file answer 405 Method Not Allowed with Allow: PUT, DELETE.

Test plan

• pnpm run typecheck and pnpm run test: 123 tests pass, including new ones for 201/200, 405 + Allow, encoded slashes, bad encoding, the docs page and its assets, and a check that every route in the spec exists
• Redocly lint --extends=recommended: valid (one warning: GET /api/workspace has no 4xx response, which is accurate)
• Against the running editor: create 201, create again with If-None-Match: * 412, overwrite 200, POST 405, delete 200; /api/docs and its assets 200 on both the production and the dev server
• Postman import (not tried: Postman was not available)

🤖 Generated with Claude Code