The small adventure
Custom apps should be able to ask Formulus and ODE Desktop the same question and
get the same bridge contract. Formulus has the canonical
FORMULUS_INTERFACE_VERSION, while Desktop currently repeats that version as a
string constant.
That works until one side changes and the other forgets. Let's add a tripwire so
CI spots the drift before a custom app does.
Where to start
formulus/src/webview/FormulusInterfaceDefinition.ts
desktop/src/lib/formPreviewBridge.ts
desktop/src/lib/__tests__/formPreviewBridge.test.ts
formulus-formplayer/scripts/sync-interface.js for an existing example of
synchronizing the contract
formulus/AGENTS.md and desktop/AGENTS.md
What to change
Add a lightweight automated check proving that Desktop's reported preview
interface version matches Formulus's canonical FORMULUS_INTERFACE_VERSION.
A focused Vitest test or a small validation script is acceptable. Prefer the
smallest solution that:
- reads the canonical value rather than introducing a third copied constant;
- works on Windows and Unix-like CI runners;
- fails with a clear message explaining which two values differ;
- does not make the Desktop production bundle import source code from another
package at runtime.
Please add the check to an existing Desktop test or validation command that CI
already runs. If that requires changing workflow files, ask a maintainer first;
we may prefer to keep the first version entirely inside the package test suite.
Guardrails
- Do not move the whole bridge contract into a new shared package in this issue.
- Do not silently rewrite generated/copied files during a test.
- Keep
formulus/src/webview/FormulusInterfaceDefinition.ts as the source of
truth.
Done when
Verify it
From desktop/:
pnpm run lint
pnpm run format:check
pnpm test
pnpm run typecheck
As a quick confidence check, temporarily change one version locally and confirm
that the new test fails. Revert that temporary edit before opening the PR.
What you will meet along the way
This bridge is how Formplayer and custom HTML apps ask their host for storage,
forms, attachments, sync, and native capabilities. Keeping the contract aligned
is what lets the same app idea run on a field device and in the Desktop
workbench.
AI tools are welcome, not required
An AI assistant can compare options for reading a sibling TypeScript file in a
test. Please choose the mechanism yourself and explain why it is build-time
only, cross-platform, and easy for the next contributor to understand.
The small adventure
Custom apps should be able to ask Formulus and ODE Desktop the same question and
get the same bridge contract. Formulus has the canonical
FORMULUS_INTERFACE_VERSION, while Desktop currently repeats that version as astring constant.
That works until one side changes and the other forgets. Let's add a tripwire so
CI spots the drift before a custom app does.
Where to start
formulus/src/webview/FormulusInterfaceDefinition.tsdesktop/src/lib/formPreviewBridge.tsdesktop/src/lib/__tests__/formPreviewBridge.test.tsformulus-formplayer/scripts/sync-interface.jsfor an existing example ofsynchronizing the contract
formulus/AGENTS.mdanddesktop/AGENTS.mdWhat to change
Add a lightweight automated check proving that Desktop's reported preview
interface version matches Formulus's canonical
FORMULUS_INTERFACE_VERSION.A focused Vitest test or a small validation script is acceptable. Prefer the
smallest solution that:
package at runtime.
Please add the check to an existing Desktop test or validation command that CI
already runs. If that requires changing workflow files, ask a maintainer first;
we may prefer to keep the first version entirely inside the package test suite.
Guardrails
formulus/src/webview/FormulusInterfaceDefinition.tsas the source oftruth.
Done when
verification command fail.
Verify it
From
desktop/:pnpm run lint pnpm run format:check pnpm test pnpm run typecheckAs a quick confidence check, temporarily change one version locally and confirm
that the new test fails. Revert that temporary edit before opening the PR.
What you will meet along the way
This bridge is how Formplayer and custom HTML apps ask their host for storage,
forms, attachments, sync, and native capabilities. Keeping the contract aligned
is what lets the same app idea run on a field device and in the Desktop
workbench.
AI tools are welcome, not required
An AI assistant can compare options for reading a sibling TypeScript file in a
test. Please choose the mechanism yourself and explain why it is build-time
only, cross-platform, and easy for the next contributor to understand.