Skip to content

test(desktop): catch Formulus bridge version drift before release #911

Description

@Mishael-2584

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

  • A mismatch between the two interface versions makes an existing
    verification command fail.
  • The failure message tells a contributor what needs synchronizing.
  • The current matching versions pass.
  • Desktop tests, type checking, lint, and formatting pass.

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.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions