Reintroduce FDC3 example apps to Sail (npm package vs hosted AppD)

[SeeWhatsOn]

Context

Follow-up to #321 — Chore: Remove in-repo example apps (now in FDC3 toolbox).

The in-repo packages/fdc3-example-apps workspace has been removed; the canonical examples now live in the main FDC3 toolbox and are published as @finos/fdc3-example-apps.

PR #321 was merged with the proviso that we revisit how Sail should surface those example apps again — either by pulling in the npm package locally, or by hosting them and consuming them via an App Directory entry.

Related prior issues:

• Create Examples package #181 — Create Examples package
• Track migration of fdc3-example-apps from @robmoffat/* to official FDC3 npm packages #264 — Track migration of fdc3-example-apps from @robmoffat/* to official FDC3 npm packages (largely superseded by the toolbox move)

---

Problem

After removing the bundled examples, Sail no longer provides a turnkey way to demonstrate the full set of FDC3 example apps out of the box. Users must manually configure application directories and know where to find hosted toolbox URLs.

We need a deliberate integration approach that:

• Lets Sail demonstrate the example apps with minimal setup
• Aligns with FDC3 App Directory patterns where possible
• Avoids re-introducing duplicate maintenance burden in this repo

---

Options under consideration

Option A — Pull in @finos/fdc3-example-apps and run it locally

Suggested by @robmoffat on PR #321:

I would have thought this should pull in https://www.npmjs.com/package/@finos/fdc3-example-apps and run that so that Sail can demonstrate all the example apps too?

The published package includes a dev orchestrator (npx @finos/fdc3-example-apps / fdc3-example-apps bin) that:

1. Discovers apps under front-end-apps/ and server-apps/
2. Starts per-app Express + Vite dev servers on assigned ports
3. Merges static/appd.v2.json fragments into a combined directory at http://localhost:4005/static/generated/fdc3-example-apps.json

Sail would depend on the npm package, run the orchestrator (e.g. alongside npm start), and point its default App Directory configuration at the generated local directory URL.

Pros

• Single source of truth — examples stay in the FDC3 toolbox repo / npm package
• Local dev experience similar to the old in-repo setup
• No need to operate separate hosted infrastructure for demos

Cons / open questions

• Adds a runtime dependency and port orchestration to Sail's dev/start scripts
• Example apps run as separate local processes — lifecycle, CI, and cross-platform startup need design
• May feel less aligned with "production-like" AppD consumption if URLs are always localhost

Option B — Host example apps and consume via App Directory (preferred direction)

Raised by @SeeWhatsOn on PR #321:

Isn't the plan to host the example apps?

We can then have an appd entry that Sail consumes. Doing this will mean that we can lead by example and use the AppD to serve example apps to Sail.

Are there any technical limitations that mean pulling the apps in directly would be a better approach?

Example apps (or their built artefacts) would be hosted at stable URLs. Sail would register a default App Directory entry (or merge a fixture similar to conformance-appd.json) that references those hosted applications — demonstrating the same AppD-driven discovery flow we expect integrators to use.

Pros

• Dogfoods the App Directory model — Sail consumes examples the same way a production deployment would
• No extra local processes beyond Sail itself
• Hosted URLs can be shared across Workbench, Sail, conformance harness, and documentation

Cons / open questions

• Requires hosted deployment of example app builds (where, who maintains, release cadence)
• Local/offline dev may need a fallback (hosted-only vs optional local npm orchestrator)
• Server-side example apps (Express/WebSocket backends) may need different hosting considerations than static front-end apps

---

Decision needed

Before implementing, we should agree:

1. Primary integration model — npm-orchestrated local dev (A), hosted AppD (B), or a hybrid (hosted by default, npm package for offline/local)?
2. Technical blockers — Are there limitations (server apps, ports, auth/security demos, CI) that make one approach clearly better?
3. Default Sail configuration — Should example apps appear in Sail's default app directory list out of the box, or only when explicitly enabled?
4. Relationship to existing fixtures — How does this interact with packages/sail-conformance-harness/conformance-appd.json and the FINOS public directory?

---

Suggested acceptance criteria (draft)

• Approach agreed and documented (ADR or README section)
• Sail can launch/discover the FDC3 example apps with minimal or zero manual AppD configuration
• Implementation does not re-vendor example app source into this repo
• Dev and CI paths are defined (including any hosted URL stability requirements)
• Documentation updated (website/docs/run-sail.md, add-your-app.md, README)

---

References

• PR: Chore: Remove in-repo example apps (now in FDC3 toolbox) #321
• npm: https://www.npmjs.com/package/@finos/fdc3-example-apps
• FDC3 toolbox source: toolbox/fdc3-example-apps in https://github.com/finos/FDC3
• Sail conformance fixture pattern: packages/sail-conformance-harness/conformance-appd.json