Compatibility Contract

Fabric Harness exposes a machine-readable contract so an integrating application can verify behavior before it runs a command. Use capability negotiation together with a supported version range. A version check alone cannot prove that a build includes the commands, targets, and protocol versions your application needs.

fh capabilities --json

The command writes JSON to stdout and does not inspect a workspace or read credentials. Abridged output (the installed version and arrays vary by release):

{
  "schemaVersion": 1,
  "product": "fabric-harness",
  "cliVersion": "<installed version>",
  "protocolVersion": 1,
  "buildManifestVersion": 2,
  "commands": ["init", "run", "build", "deploy", "doctor", "capabilities"],
  "buildTargets": ["node", "temporal-worker", "docker", "cloudflare", "databricks-app", "databricks-serving"],
  "runtimes": ["inline", "temporal"],
  "features": ["cli.preview-deploy", "buzz.doctor", "databricks.app-build", "databricks.app-deploy", "databricks.ai-gateway"]
}

The arrays can gain values in a compatible release. Consumers should require the values they use and ignore values they do not recognize. A changed schemaVersion, protocolVersion, or buildManifestVersion requires an explicit compatibility decision.

flowchart LR
  A[Desktop or automation] --> B[Resolve fh executable]
  B --> C[Check supported semver range]
  C --> D[Run fh capabilities --json]
  D --> E{Required protocol and features present?}
  E -->|Yes| F[Run init, build, deploy, or run]
  E -->|No| G[Stop with an upgrade or compatibility error]

Consumer example

import { execFileSync } from 'node:child_process';

const capabilities = JSON.parse(
  execFileSync('fh', ['capabilities', '--json'], { encoding: 'utf8' }),
);

const required = [
  'cli.preview-deploy',
  'buzz.doctor',
  'databricks.app-build',
  'databricks.app-deploy',
  'databricks.ai-gateway',
];

if (capabilities.protocolVersion !== 1) {
  throw new Error(`Unsupported Harness protocol ${capabilities.protocolVersion}`);
}

const missing = required.filter((feature) => !capabilities.features.includes(feature));
if (missing.length > 0) {
  throw new Error(`Harness is missing: ${missing.join(', ')}`);
}

Release testing

Fabric Desktop tests both its minimum certified Harness release and the current npm latest. Harness contributors can test an unpublished CLI against the adjacent Desktop checkout:

pnpm test:desktop-compat

The command builds and packs @fabric-harness/cli, installs that tarball in isolation, then drives Desktop's real Databricks bridge through scaffold, mock run, build validation, and deploy preview for every bundled template. It also verifies the capability contract and scans generated files for leaked credentials.

Keep application templates on the compatible ranges emitted by the installed CLI. Fabric packages are independently versioned, so matching majors are not a compatibility signal. CI builds the executable CLI, scaffolds every platform template, and compares each generated range with the corresponding workspace package so a release cannot leave a fresh project on a stale or invented version. See release and documentation status for the current published versions and runtime requirements.