chore(env): add repo-wide .env.example and adopt provider-aware site resolution for docs#115
Merged
Conversation
…resolution for docs
Contributor
📝 WalkthroughWalkthroughAdds a canonical Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches
🧪 Generate unit tests (beta)
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. Comment |
Contributor
✅ Contributor ReportUser: @yacosta738
Contributor Report evaluates based on public GitHub activity. Analysis period: 2025-03-01 to 2026-03-01 |
Deploying corvus with
|
| Latest commit: |
9bada94
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://fa39578b.corvus-42x.pages.dev |
| Branch Preview URL: | https://chore-add-env-example.corvus-42x.pages.dev |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (4)
clients/web/apps/docs/astro.config.mjs (2)
12-25: Add regression coverage for URL precedence and port resolution.This block changes deployment-critical behavior (
DOCS_URL/ provider keys /SITE_URLfallback and derived port). A small config-level test matrix would prevent regressions.As per coding guidelines, "Testing: Verify that tests cover critical paths and follow established naming conventions (e.g., backticks for Kotlin tests)."
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@clients/web/apps/docs/astro.config.mjs` around lines 12 - 25, Add regression tests that exercise resolveSiteUrl and getPortFromUrl to cover DOCS_URL, providerKeys (CF_PAGES_URL, VERCEL_URL, URL), and generic SITE_URL fallback plus port derivation; create a small matrix of cases setting env values for DOCS_URL, each provider key, and SITE_URL (including absent values) and assert that docsUrl equals the expected resolved URL and resolvedPort matches getPortFromUrl expectations; put tests alongside existing config tests, name them to reflect the matrix (e.g., `resolveSiteUrl_prefers_DOCS_URL_over_providers_and_falls_back_to_SITE_URL` and `getPortFromUrl_derives_port_from_docsUrl`), and include both production and dev mode variants to verify isProdLike behavior.
29-29: DerivebasefromdocsUrlpathname instead of hardcoding root.If
DOCS_URL(or provider URL) ever includes a path segment, Line 29 will force root asset paths and break routing/assets on subpath deploys. Consider computingbasefromnew URL(docsUrl).pathname.Proposed refactor
+const docsBasePath = (() => { + const pathname = new URL(docsUrl).pathname; + return pathname.endsWith("/") ? pathname : `${pathname}/`; +})(); export default defineConfig({ site: docsUrl, - base: "/", // ← Root level for custom domain + base: docsBasePath, server: {🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@clients/web/apps/docs/astro.config.mjs` at line 29, The hardcoded base: "/" should be computed from the docs URL so subpath deployments work; replace the literal with a derived value using the DOCS_URL/docsUrl (the env var used in this file) by parsing new URL(docsUrl).pathname, normalizing it (ensure it starts with "/" and remove trailing slash except for root) and falling back to "/" when docsUrl is missing or parsing fails; update the base assignment in astro.config.mjs to use that normalized pathname instead of the hardcoded "/" so asset and route paths follow the provider URL path segments..env.example (2)
22-128: Optional: normalize key ordering to satisfy dotenv-linter warnings.Current ordering triggers many
UnorderedKeywarnings. If linting is enforced in CI, reordering keys per section will reduce noise.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.env.example around lines 22 - 128, Reorder the environment keys within each commented section so they are consistently sorted (e.g., alphabetically) to eliminate dotenv-linter UnorderedKey warnings; for example in the "Web apps / Static sites" group ensure MARKETING_PORT, MARKETING_URL, DOCS_PORT, DOCS_URL are in the same logical order, in "Agent runtime / backend (Corvus)" group sort CORVUS_API_KEY, CORVUS_GATEWAY_HOST, CORVUS_GATEWAY_PORT, CORVUS_TEST_SURREALDB_* and CORVUS_SURREALDB_* keys consistently, and similarly sort third-party keys like ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY and CI keys like GITHUB_TOKEN, GH_TOKEN — preserve section comments and blank lines while only reordering the key/value lines so dotenv-linter no longer reports UnorderedKey.
148-149: Remove AI assistant prompt text from the committed template.Lines 148-149 are conversational and not part of canonical env documentation; removing them will keep this file clean and tooling-focused.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.env.example around lines 148 - 149, Remove the two conversational prompt lines ("If you want me to run an exhaustive scan..." and the follow-up instruction) from the .env.example so the template contains only canonical environment docs/comments; locate the exact text block present in the file and delete those lines (no replacement needed).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.env.example:
- Line 85: Update the ANTHROPIC_API_KEY placeholder in .env.example to correct
the typo: replace "sk_antropic_xxx" with a properly spelled placeholder such as
"sk_anthropic_xxx" or a neutral value like "<YOUR_ANTHROPIC_API_KEY>" so the
ANTHROPIC_API_KEY entry uses "anthropic" spelled correctly.
- Around line 51-53: The .env.example contains secret-like example values (e.g.,
CORVUS_API_KEY=sk_corvus_xxx) that can trigger secret scanners; update the
example values to neutral placeholders (for example use
CORVUS_API_KEY=your_corvus_api_key_here) and similarly replace other token-like
examples in the file (lines referenced in the review, e.g., the block around
82-111) with non-secret, clearly-labeled placeholders so no real-looking secrets
(sk_*, ghp_*, AIza*, token-shaped UUIDs) remain in the template.
---
Nitpick comments:
In @.env.example:
- Around line 22-128: Reorder the environment keys within each commented section
so they are consistently sorted (e.g., alphabetically) to eliminate
dotenv-linter UnorderedKey warnings; for example in the "Web apps / Static
sites" group ensure MARKETING_PORT, MARKETING_URL, DOCS_PORT, DOCS_URL are in
the same logical order, in "Agent runtime / backend (Corvus)" group sort
CORVUS_API_KEY, CORVUS_GATEWAY_HOST, CORVUS_GATEWAY_PORT,
CORVUS_TEST_SURREALDB_* and CORVUS_SURREALDB_* keys consistently, and similarly
sort third-party keys like ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY and
CI keys like GITHUB_TOKEN, GH_TOKEN — preserve section comments and blank lines
while only reordering the key/value lines so dotenv-linter no longer reports
UnorderedKey.
- Around line 148-149: Remove the two conversational prompt lines ("If you want
me to run an exhaustive scan..." and the follow-up instruction) from the
.env.example so the template contains only canonical environment docs/comments;
locate the exact text block present in the file and delete those lines (no
replacement needed).
In `@clients/web/apps/docs/astro.config.mjs`:
- Around line 12-25: Add regression tests that exercise resolveSiteUrl and
getPortFromUrl to cover DOCS_URL, providerKeys (CF_PAGES_URL, VERCEL_URL, URL),
and generic SITE_URL fallback plus port derivation; create a small matrix of
cases setting env values for DOCS_URL, each provider key, and SITE_URL
(including absent values) and assert that docsUrl equals the expected resolved
URL and resolvedPort matches getPortFromUrl expectations; put tests alongside
existing config tests, name them to reflect the matrix (e.g.,
`resolveSiteUrl_prefers_DOCS_URL_over_providers_and_falls_back_to_SITE_URL` and
`getPortFromUrl_derives_port_from_docsUrl`), and include both production and dev
mode variants to verify isProdLike behavior.
- Line 29: The hardcoded base: "/" should be computed from the docs URL so
subpath deployments work; replace the literal with a derived value using the
DOCS_URL/docsUrl (the env var used in this file) by parsing new
URL(docsUrl).pathname, normalizing it (ensure it starts with "/" and remove
trailing slash except for root) and falling back to "/" when docsUrl is missing
or parsing fails; update the base assignment in astro.config.mjs to use that
normalized pathname instead of the hardcoded "/" so asset and route paths follow
the provider URL path segments.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
.env.exampleclients/web/apps/docs/astro.config.mjs
…sure schema link removed
…om site URL; add env resolution tests
|
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.env.example:
- Around line 31-33: The example uses shell-style interpolation for DOCS_URL and
MARKETING_URL (DOCS_URL, MARKETING_URL referencing DOCS_PORT, MARKETING_PORT)
which many env loaders won't expand; either replace those entries with concrete
default literals (e.g., use explicit port numbers) or add a short comment above
these lines explaining that ${DOCS_PORT} and ${MARKETING_PORT} require shell
expansion (or recommend using dotenv-expand) and showing the literal fallback
format so users know to set full URLs when using non-shell env loaders.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (4)
.env.example.github/config/changelog.jsonclients/web/apps/docs/astro.config.mjsclients/web/packages/shared/test/env.test.mjs
Comment on lines
+31
to
+33
| DOCS_URL=http://localhost:${DOCS_PORT} | ||
| # Marketing site - provider-aware. Local default uses MARKETING_PORT above. | ||
| MARKETING_URL=http://localhost:${MARKETING_PORT} |
Contributor
There was a problem hiding this comment.
Shell variable interpolation may not work with all env loaders.
The ${DOCS_PORT} and ${MARKETING_PORT} syntax relies on shell interpolation, which won't work with many env loaders (e.g., Node.js dotenv doesn't expand variables by default). Consider using literal values or documenting this limitation.
Option 1: Use literal values
-DOCS_URL=http://localhost:${DOCS_PORT}
+DOCS_URL=http://localhost:4321
# Marketing site - provider-aware. Local default uses MARKETING_PORT above.
-MARKETING_URL=http://localhost:${MARKETING_PORT}
+MARKETING_URL=http://localhost:9988Option 2: Add a note about interpolation
Add a comment above these lines:
+# Note: ${VAR} interpolation requires shell expansion or dotenv-expand; use literal ports if your loader doesn't support it.
DOCS_URL=http://localhost:${DOCS_PORT}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| DOCS_URL=http://localhost:${DOCS_PORT} | |
| # Marketing site - provider-aware. Local default uses MARKETING_PORT above. | |
| MARKETING_URL=http://localhost:${MARKETING_PORT} | |
| DOCS_URL=http://localhost:4321 | |
| # Marketing site - provider-aware. Local default uses MARKETING_PORT above. | |
| MARKETING_URL=http://localhost:9988 |
Suggested change
| DOCS_URL=http://localhost:${DOCS_PORT} | |
| # Marketing site - provider-aware. Local default uses MARKETING_PORT above. | |
| MARKETING_URL=http://localhost:${MARKETING_PORT} | |
| # Note: ${VAR} interpolation requires shell expansion or dotenv-expand; use literal ports if your loader doesn't support it. | |
| DOCS_URL=http://localhost:${DOCS_PORT} | |
| # Marketing site - provider-aware. Local default uses MARKETING_PORT above. | |
| MARKETING_URL=http://localhost:${MARKETING_PORT} |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.env.example around lines 31 - 33, The example uses shell-style
interpolation for DOCS_URL and MARKETING_URL (DOCS_URL, MARKETING_URL
referencing DOCS_PORT, MARKETING_PORT) which many env loaders won't expand;
either replace those entries with concrete default literals (e.g., use explicit
port numbers) or add a short comment above these lines explaining that
${DOCS_PORT} and ${MARKETING_PORT} require shell expansion (or recommend using
dotenv-expand) and showing the literal fallback format so users know to set full
URLs when using non-shell env loaders.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces a canonical
.env.examplefile for environment variable documentation and refactors the documentation site's configuration to use a shared environment resolution helper. The main goal is to standardize environment variable usage across the repository and make local development and deployment more robust and provider-agnostic.Environment variable standardization and configuration improvements:
.env.examplefile at the root (corvus/.env.example) documenting all environment variables used across the repository, including development, production, CI, and third-party provider keys. This file serves as a template and reference for local development and CI/CD setups.Documentation site configuration refactor:
clients/web/apps/docs/astro.config.mjsto use the shared@corvus/shared/envhelpers (resolveSiteUrl,getPortFromUrl,PORTS) for dynamic site URL and port resolution, supporting multiple hosting providers and local development.Summary by CodeRabbit
Documentation
Chores
Tests
Documentation