finos / finos/architecture-as-code
Browser support for template and docify in @finos/calm-shared/browser
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 38
Description
## Feature Proposal
### Target Project:
`shared` (`@finos/calm-shared`), consumed by the in-browser learning lab (#2879).
### Description of Feature:
Extend the browser entry point added in #2880 (`@finos/calm-shared/browser`) to cover `template` and `docify`, so browser consumers can run the real Handlebars template pipeline and produce docify output without a filesystem.
### User Stories:
- As a **learner in the browser lab**, I want `calm template` and `calm docify` to run in my browser, so I can see the generated documentation for the architecture I just modelled.
- As a **Studio/Guard maintainer**, I want the template engine to work against an injected filesystem, so serverless and browser consumers stop working around Node-coupled loaders.
### Current Limitations:
`template/` and `docify/` are filesystem-bound end to end: `template-bundle-file-loader.ts` walks bundle directories with `readdirSync`/`readFileSync`; `strategies/abstract-output-strategy.ts` writes with `mkdirSync`/`writeFileSync`; `template-processor.ts` loads user transformers from disk via `pathToFileURL` + dynamic `import`; `docifier.ts` resolves template bundles from `__dirname` and rasterises diagrams with playwright. The `BROWSER_COMMAND_SUPPORT` manifest therefore reports both commands as `unsupported`.
### Proposed Implementation:
- Introduce a `TemplateBundleSource` seam (in-memory bundle: `Record` + the bundle's `index.json`) alongside the existing directory loader, and an `OutputSink` seam (in-memory map) alongside the fs output strategies — mirroring the `DocumentLoader` / `InMemoryDocumentLoader` pattern from #2880.
- Transformers become injectable objects (`CalmTemplateTransformer` instances passed in), with the disk-loading path kept behind the Node entry.
- `docify` in the browser is the template pipeline only; diagram rasterisation stays Node-only (browser consumers render live, e.g. the lab's Hub visualizer pipeline).
- Add `template`/`docify` cores to `src/browser.ts`, flip their manifest entries to `supported`, and extend `scripts/browser-probe.ts` to render a small bundle.
### Alternatives Considered:
- Keep the lab's own mini template renderer — rejected: forks the CLI's behaviour and drifts (the reason #2880 exists).
- Ship a virtual-fs shim for `fs` in browser bundles — rejected: `template-processor.ts`'s dynamic `import()` of transformer files has no browser analogue, and shims hide rather than remove the coupling.
### Testing Strategy:
Unit tests for the in-memory bundle source and output sink; a browser-surface spec rendering the `ants` bundle end to end through the browser entry; the existing `check-browser-entry.mjs` guard and probe extended to template/docify; full downstream workspace sweep.
### Documentation Requirements:
`shared/AGENTS.md` "Entry points" section and README browser section updated; `BROWSER_COMMAND_SUPPORT` reasons updated.
### 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; enables the remaining rows of the per-command feasibility table in https://github.com/finos/architecture-as-code/issues/2879#issuecomment-5078188900.
Contributor guide
Research direction
Start with src/browser.ts and the existing DocumentLoader/InMemoryDocumentLoader pattern from #2880, then inspect template-bundle-file-loader.ts, strategies/abstract-output-strategy.ts, template-processor.ts, and docifier.ts. Run the browser probe and check-browser-entry guard while adding the proposed unit and browser-surface coverage. Done means template and docify render the ants bundle in the browser without filesystem or rasterisation dependencies, with manifest and documentation updates.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- handlebars, node.js, playwright, typescript
- Domain
- tooling, web-dev
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100