feat: support env var substitution in API server URLs

[rsbh]

Summary

• Add ${VAR} env var substitution for server.url in chronicle.yaml API config
• Substitution happens in loadApiSpecs — single place covers UI, API proxy, .md route, and /api/specs endpoint
• Resolved server URL shown in API reference page and playground dialog (replaces {domain} placeholder)
• Missing env var throws a clear error
• Build once, deploy to multiple environments with different server.url values

Usage

api:
  - name: MyAPI
    spec: ./openapi.yaml
    basePath: /apis
    server:
      url: ${API_SERVER_URL}

API_SERVER_URL=https://api.example.com chronicle start

Test plan

• Proxy resolves ${VAR} and forwards requests to correct URL
• .md route resolves ${VAR} in cURL snippets
• UI shows resolved server URL in API reference page and playground dialog
• /api/specs returns resolved URLs to client
• Missing env var returns clear error message
• Existing tests pass (116/116)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
chronicle	Ready	Preview, Comment	May 18, 2026 5:46am

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces environment variable substitution for OpenAPI server URLs. A new substituteEnvVars utility function replaces ${VAR} placeholders with process.env values, and is integrated into the API proxy handler and API markdown generator to support dynamic server URL configuration.

Changes

Environment Variable Substitution in API URLs

Layer / File(s)	Summary
Environment variable substitution utility packages/chronicle/src/lib/env.ts	substituteEnvVars function performs global regex substitution of ${name} patterns with corresponding process.env values, throwing an error if any referenced variable is undefined.
API proxy server URL substitution packages/chronicle/src/server/api/apis-proxy.ts	API proxy handler imports substituteEnvVars and applies it to spec.server.url before concatenating the request path for the proxy target URL.
API markdown server URL substitution packages/chronicle/src/server/utils/api-markdown.ts	API markdown handler imports substituteEnvVars and applies it to the OpenAPI server URL before Markdown generation, affecting documentation and embedded cURL snippets.

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 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
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding environment variable substitution support for API server URLs.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description clearly explains the feature (environment variable substitution in API server URLs), provides concrete usage examples, and includes a comprehensive test plan.

_{✏️ 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/env-config-support

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 2

🤖 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.

Inline comments:
In `@packages/chronicle/src/server/api/apis-proxy.ts`:
- Line 41: The code builds a resolved URL with
substituteEnvVars(spec.server.url) + path and later returns it in client-facing
errors (variable url), leaking env-derived values; change the error path to
avoid exposing the env-resolved URL by (1) retaining substituteEnvVars(...) for
internal requests but never interpolating that into client error strings, (2)
replace uses of url in responses with either the original spec.server.url
(unresolved) or a generic message like "Could not reach upstream service" and
(3) log the full resolved URL and error details only to server logs (e.g.,
inside the same function that calls substituteEnvVars/spec.server.url and
constructs url) while returning the sanitized message to clients; update
references to url and the error string in apis-proxy.ts accordingly.

In `@packages/chronicle/src/server/utils/api-markdown.ts`:
- Line 25: The call to substituteEnvVars inside the generateApiMarkdown
invocation can throw a raw Error for missing env vars; update the markdown route
so that any error from substituteEnvVars (or generateApiMarkdown) is caught and
re-thrown or returned as an instance of HTTPError (preserving message and status
like 400/422 as appropriate). Locate the code that calls
generateApiMarkdown(match.method, match.path, match.operation,
substituteEnvVars(...), match.spec.auth) and wrap the
substituteEnvVars/generateApiMarkdown call in a try/catch, and in the catch
create and throw a new HTTPError with the original error message (and suitable
HTTP status) so the route consistently returns HTTPError types.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a4459b15-0353-4cba-8080-a14fc9cfc987

📥 Commits

Reviewing files that changed from the base of the PR and between 08f2641 and b5c5199.

📒 Files selected for processing (3)

• packages/chronicle/src/lib/env.ts
• packages/chronicle/src/server/api/apis-proxy.ts
• packages/chronicle/src/server/utils/api-markdown.ts