Skip to content

SPEC-0011: tangent-shell: add /version api endpoint - #200

Draft
maxy-shpfy wants to merge 1 commit into
mainfrom
SPEC-0011
Draft

maxy-shpfy wants to merge 1 commit into
mainfrom
SPEC-0011

Conversation

@maxy-shpfy

Copy link
Copy Markdown
Collaborator

Implements SPEC-0011 — tangent-shell: add /version api endpoint.

Story

The tangent-shell server (@tangent/server) exposes GET /api/health but there's no way to read which build is running. Add a sibling GET /api/version endpoint that returns the server package's name and version as JSON: { "name": "", "version": "" }, read from its own package.json.

Mount it the same way as the existing health route, add no new dependencies, and include a test in the server's existing test setup that asserts a 200 and the JSON shape. No auth, no params. Follow the repo's own conventions (its CLAUDE.md / AGENTS.md).

Plan

SPEC-0011 — Server package version endpoint

Scope

Add unauthenticated GET /api/version beside GET /api/health, returning HTTP 200 and exactly { name, version } from apps/server/package.json. No dependencies, parameters, frontend changes, version bumps, or health refactoring.

flowchart LR
  P[apps/server/package.json] -->|static JSON import| H[routes/version.ts handler]
  H -->|esbuild inlines metadata| B[dist/index.js]
  R[GET /api/version] --> M[Existing Express middleware]
  M --> G[Sibling app.get registration]
  G --> H
  H --> J[HTTP 200 JSON: name and version]
  T[Isolated Express HTTP test] --> H
Loading

Implementation

  1. Enable resolveJsonModule explicitly in apps/server/tsconfig.json for typed server-local JSON imports. Leave shared configuration unchanged.
  2. Add apps/server/src/routes/version.ts, statically importing ../../package.json with with { type: "json" }. Export synchronous handleGetVersion with Express request/response types and a void return. Use res.json with only manifest name and version, not the complete manifest, hardcoded values, environment overrides, or Git metadata. Follow repo import conventions, including explicit .ts extensions for TypeScript imports; keep comments minimal.
  3. Import and register app.get("/api/version", handleGetVersion) in apps/server/src/index.ts directly beside health and before other API routers. Preserve middleware order, health behavior, and startup behavior. Do not introduce a router abstraction or extract health logic.
  4. Add co-located apps/server/src/routes/version.test.ts with node:test, node:assert/strict, Express, and fetch. Register the production handler at the full path in an isolated Express app, listen on an ephemeral loopback port, await readiness, and close reliably through test cleanup. Do not import the side-effectful server entrypoint. Request without authorization, cookies, or parameters; assert 200, JSON content type, and exact deep equality to { name: manifest.name, version: manifest.version }. Reject additional fields. No mocks or test dependencies.

Build and validation

  • Preserve existing build and Docker configuration: esbuild should inline static JSON imports. Avoid runtime filesystem reads because production deploys dist/ without the source manifest.
  • If dependencies are absent, run pnpm install --frozen-lockfile in this worktree; do not change manifests or lockfile to bypass installation problems.
  • Run pnpm --filter @tangent/server exec tsx --test src/routes/version.test.ts, then pnpm --filter @tangent/server test (validation skips tests).
  • Run targeted Prettier checks and root pnpm validate.
  • Inspect generated apps/server/dist/index.js for embedded metadata and absence of a runtime source-manifest dependency. Smoke-test an isolated bundled version-handler harness using existing esbuild and plain Node in a temporary .local/ directory without the source manifest. Verify the HTTP response against build-time metadata; keep harness uncommitted and avoid the full server entrypoint.
  • Review final diff: only the four listed implementation files should change.

Inspection findings

The session mount is on branch SPEC-0011, with tracked files clean. Repository CLAUDE.md and relevant project-conventions, TypeScript, server-testing, and code-navigation skills were reviewed; no applicable AGENTS.md found. Health registration is in apps/server/src/index.ts:411; HTTP testing conventions are in routes/attach.test.ts; production bundling is in build.mjs and Dockerfile. Compiler configuration inspection was blocked by unresolved @tangent/build/tsconfig/node.json; verify resolved configuration after installing dependencies. No implementation or tests performed. A gitignored planning note was saved under .local/.

Affected files

  • apps/server/tsconfig.json — modify: Enable typed static JSON imports locally for server package metadata.
  • apps/server/src/routes/version.ts — add: Provide an independently testable handler returning only manifest-derived name and version, bundled with production code.
  • apps/server/src/index.ts — modify: Register GET /api/version beside health without changing existing behavior or middleware.
  • apps/server/src/routes/version.test.ts — add: Assert unauthenticated HTTP access, 200, JSON content type, and exact manifest-derived response using existing Node tests.

Part of the SPEC-0011 slice spanning tangent-shell. This PR is one draft layer of that stack — review and undraft each layer per repo.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant