Codex/configurable api base

[PatrickJS]

Introduce a new server.apiBase config (default /__jsondb) to scope built-in dev-tool routes (viewer, schema, batch, import, events, log, and fork routes) without changing root REST resources or the standalone GraphQL path. Propagate the setting through the client, server, REST handler, Vite integration, and mock logic: client restBatch and fork paths use apiBase, vite plugin resolves apiBase from plugin options then server config, mock behavior skips the configured apiBase, and REST batch handling uses an effective batch path helper. Add normalizeBasePath and batchPathForOptions helpers, update TypeScript types, sample config, docs, and many tests to cover the new behavior.

Summary by CodeRabbit

• New Features
  • Added viewer manifest generation with configurable output file support
  • Support for custom API base paths via server.apiBase configuration
  • Multiple REST response formats including HTML, Markdown, and YAML
  • Configurable custom viewer links in server.viewerLinks
  • New jsondb viewer manifest CLI command for generating and exporting viewer metadata

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 263afa3b-e565-40ba-9251-925234e23d29

📥 Commits

Reviewing files that changed from the base of the PR and between 4f77e1e and fd7309e.

📒 Files selected for processing (38)

• README.md
• SPEC.md
• docs/architecture.md
• docs/configuration.md
• docs/generated-files.md
• docs/integrations.md
• docs/package-api.md
• docs/server-and-viewer.md
• examples/basic/jsondb.config.mjs
• jsondb.config.example.mjs
• src/cli/commands/viewer.js
• src/cli/index.js
• src/cli/output.js
• src/client.js
• src/client.test.js
• src/features/config/defaults.js
• src/features/config/load.js
• src/features/sync/index.js
• src/features/viewer/manifest.js
• src/index.d.ts
• src/index.js
• src/integrations/vite.js
• src/mock.test.js
• src/rest/formats.js
• src/rest/handler.js
• src/rest/handler.test.js
• src/server.js
• src/server.test.js
• src/shared/mock.js
• src/viewer-manifest.js
• src/vite.d.ts
• src/vite.test.js
• src/web/json-viewer.js
• src/web/viewer.js
• src/web/viewer.test.js
• test/cli/cli.test.js
• test/config/config.test.js
• test/viewer/manifest.test.js

---

📝 Walkthrough

Walkthrough

PR introduces viewer manifest generation for JSONDB: adds REST format registry with content negotiation for json/html/md, implements generateViewerManifest/renderViewerManifest for schema-derived metadata, wires manifest endpoints into server routing, integrates manifest fetching into web viewer, adds CLI viewer command, and supports configurable apiBase for scoped dev routes.

Changes

Viewer Manifest Implementation

Layer / File(s)	Summary
Type system and public API contracts src/index.d.ts, src/index.js, src/vite.d.ts, src/viewer-manifest.js	Type contracts for REST format contexts (resource vs manifest targets), renderer types, and extended JsonDbOptions with apiBase/viewerLinks/viewerManifestOutFile; public API exports for generateViewerManifest and renderViewerManifest.
Viewer manifest generation and rendering src/features/viewer/manifest.js, test/viewer/manifest.test.js	Core viewer manifest artifact generation: loads schema, computes API route metadata, derives capability flags, normalizes viewer links and routes, includes per-resource endpoint definitions; comprehensive test coverage for manifest structure and output file generation.
REST format registry and content negotiation src/rest/formats.js	Format registry with built-in json/html/md formats; normalizes user-configured formats; negotiates format from Accept header; resolves renderers for resource/manifest targets; computes metadata and manifest paths; includes Markdown and JSON viewer rendering helpers.
Configuration defaults and path resolution src/features/config/defaults.js, src/features/config/load.js, test/config/config.test.js	Adds viewerManifestOutFile, server.apiBase, server.viewerLinks to DEFAULT_CONFIG; resolves viewerManifestOutFile paths relative to cwd; validates default apiBase value.
Server-side manifest route definition and handling src/server.js, src/rest/handler.js	Derives manifest route paths from configurable apiBase; updates fork routing to include manifest endpoints; detects manifest format from path extension or negotiation; responds with appropriate format renderers; validates manifest route paths; adds batch path computation.
Sync workflow and manifest generation src/features/sync/index.js	Conditionally generates and logs viewer manifest when viewerManifestOutFile is configured; outputs generated file paths relative to cwd.
REST discovery endpoints and format metadata src/rest/handler.test.js, src/rest/handler.js	Updates root discovery to include manifest routes, viewer links, and REST format metadata; replaces hardcoded "Data Viewer" link with computed viewer links; changes HTML preference to use format negotiation; normalizes batch path computation; updates viewer HTML to pass manifestPath; comprehensive discovery and format negotiation tests.
Client library apiBase normalization src/client.js, src/client.test.js, src/integrations/vite.js, src/vite.test.js	Normalizes apiBase in client; derives default restBatchPath and fork paths from configurable apiBase; updates Vite plugin apiBase resolution (plugin option → server.apiBase → default); includes client and plugin tests verifying apiBase path derivation.
Web viewer manifest integration and JSON display src/web/json-viewer.js, src/web/viewer.js, src/web/viewer.test.js	New renderJsonViewer for standalone JSON display with theme and format toggles; updates renderJsonDbViewer to fetch manifest concurrently with schema, build resource list from manifest metadata, use manifest diagnostics, resolve per-resource API endpoints; viewer tests assert manifest path presence.
CLI viewer command and help system src/cli/commands/viewer.js, src/cli/index.js, src/cli/output.js, test/cli/cli.test.js	New runViewer command handler validating manifest subcommand, loading schema, generating manifest; integrates viewer command into CLI dispatch and help; includes CLI test for manifest generation with --out option.
Mock behavior exemption for viewer routes src/shared/mock.js, src/mock.test.js	Updates mock behavior to skip mocking for requests under server.apiBase; replaces hardcoded path check with dynamic shouldSkipMock deriving path from config; includes test for mock bypass on API base routes.
Server-level manifest endpoint and route tests src/server.test.js	Updates server tests with YAML format configuration; adds manifest endpoint assertions; adds comprehensive test for server.apiBase-derived standalone dev-tool routes; extends fork routing test for manifest endpoints; updates test helpers (makeRequest parameter names, new makeRawRequest).
Configuration examples and documentation examples/basic/jsondb.config.mjs, jsondb.config.example.mjs, README.md, SPEC.md, docs/*	Adds viewerManifestOutFile, server.apiBase, server.viewerLinks to example configs with YAML format examples; updates all documentation to describe manifest-driven UI integration, manifest endpoints, format negotiation, CLI command, and apiBase routing behavior.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• PatrickJS/jsondb#6: Both PRs modify the REST format dispatch path in src/rest/handler.js; main PR's viewer-manifest endpoint additions build on REST formats layer refactored in that PR.
• PatrickJS/jsondb#5: Both PRs extend syncJsonFixtureDb in src/features/sync/index.js to conditionally generate and write committed manifest artifacts (main PR for viewerManifestOutFile, related PR for schemaOutFile).

Poem

🐇 A manifest of routes and formats sweet,
With viewers nested in a REST retreat,
From /__jsondb/manifest flows the light,
JSON, HTML, Markdown—each format bright!
The web viewer dances with fetched metadata,
While CLI commands generate the data!

✨ 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 codex/configurable-api-base

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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