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:

{
  "schemaVersion": 1,
  "product": "fabric-harness",
  "cliVersion": "2.2.2",
  "protocolVersion": 1,
  "buildManifestVersion": 2,
  "commands": ["init", "run", "build", "deploy", "doctor", "capabilities"],
  "buildTargets": ["node", "temporal-worker", "docker", "databricks-app", "databricks-serving"],
  "runtimes": ["inline", "temporal"],
  "features": ["cli.preview-deploy", "databricks.app-build", "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.

Consumer example

import { execFileSync } from 'node:child_process';

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

const required = [
  'cli.preview-deploy',
  '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 exact package versions. Upgrade those pins only after the packed-artifact compatibility gate passes; this prevents a new transitive CLI release from changing an existing scaffold without review.