finos / finos/architecture-as-code

Hub read commands in the browser: CORS on hub.calm.finos.org and a shared read core

Open
#3,027 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
399
Forks
138
Avg merge
2d 14h
Merged PRs (30d)
37

Description

## Feature Proposal

### Target Project:
`shared` (`@finos/calm-shared`) and the hosted CALM Hub deployment (hub.calm.finos.org); consumed by the in-browser learning lab (#2879).

### Description of Feature:
Let browser consumers run the CLI's Hub read commands (`hub pull`, `hub list`) against the public CALM Hub through `@finos/calm-shared/browser`, so lab lessons can pull real published architectures and patterns.

### User Stories:
- As a **learner in the browser lab**, I want `calm hub pull architecture …` and `calm hub list …` to work, so I can start a lesson from a real published document.
- As a **workshop facilitator**, I want attendees to browse the public Hub from the lab without installing anything.

### Current Limitations:
`CalmHubDocumentLoader` and `CalmHubClient` are already browser-safe (axios), but the hosted Hub does not send CORS headers, so a browser cannot call it from calm.finos.org. The `hub` command wrappers also live in the CLI (`cli/src/command-helpers/hub-commands.ts`) rather than in `shared`, so there is no core to expose. `BROWSER_COMMAND_SUPPORT` reports `hub pull`/`hub list` as `unsupported` for exactly this reason.

### Proposed Implementation:
1. CORS on hub.calm.finos.org for read endpoints (`GET` only), allow-listing the docs origin(s).
2. Move the read-only orchestration of `hub pull`/`hub list` from the CLI into a `shared` core (`hub-read-core.ts`) that takes a `CalmHubClient` and returns documents/summaries, with the CLI's formatting/file writing left in the CLI.
3. Export the core from `src/browser.ts`; flip the two manifest entries to `supported`; extend the guard probe with a mocked-HTTP read.
Writes (`hub push`, `hub create`) stay `unsupported` in browsers; the lab simulates publishing (MSW) per #2879.

### Alternatives Considered:
- A CORS proxy in front of the Hub — rejected: adds infrastructure and an abuse surface for a docs feature.
- Bundling a static snapshot of Hub content into the docs — possible fallback for offline lessons, but it is not "real Hub reads".

### Testing Strategy:
Unit tests for the read core with a mocked `CalmHubClient`; an MSW-backed browser-surface spec; a smoke check in the lab against the live Hub once CORS is deployed.

### Documentation Requirements:
`shared/AGENTS.md` entry-point section; Hub deployment docs noting the CORS allow-list.

### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed

### Additional Context:
Follow-up to #2880 / PR #3022; Phase C of #2879. I would like input from the other maintainers here on whether the CORS change on the hosted Hub is acceptable, and which origins to allow.

Contributor guide

Open the contributing guide

Research direction

Start with cli/src/command-helpers/hub-commands.ts and the existing CalmHubDocumentLoader, CalmHubClient, and src/browser.ts entry points to map the read-only orchestration. Add the shared read core, browser export, manifest support, mocked-HTTP guard probe, and the stated unit and MSW browser tests; completion also requires the shared/AGENTS.md and Hub CORS deployment documentation, with maintainer agreement on allowed origins.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
api, cli, documentation, web-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.