@healflow/shared

Shared types, enums, contracts, events, and configuration for the HealFlow platform.

Overview

Foundation package used across CLI, Playwright plugin, API, and internal engines. Provides domain models, policy rules, the 179-entry healing matrix, and the healflow.yml config schema.

Published to npm as a transitive dependency of @healflow/playwright and @healflow/cli. You typically do not install it directly.

Installation

npm install @healflow/shared

Exports

| Subpath | Purpose | | ---------------------------- | --------------------------------------------- | | @healflow/shared | Enums, domain types, policy, healing matrix | | @healflow/shared/config | HealFlowConfig, YAML loader, artifact types | | @healflow/shared/events | Domain events for the job pipeline | | @healflow/shared/contracts | API and service contracts |

Healing matrix

Canonical failure spec: docs/product/HEALING_MATRIX.md (target product behavior).

Encoded in code:

• HEALING_MATRIX_ENTRIES — 179 sub-failures across 23 families
• matchMatrixEntry, resolveMatrixOutcome, getRuntimeHealableMatrixIds
• AUTOMATION_FIXABLE_CATEGORIES, DIAGNOSE_ONLY_CATEGORIES, BLOCKED_CATEGORIES

Implementation status (what auto-heals vs diagnose-only): docs/product/MATRIX_COVERAGE.md.

Config

import { loadHealFlowConfig, mergeHealFlowConfig } from '@healflow/shared/config';

const config = loadHealFlowConfig(process.cwd());
// reads healflow.yml or healflow.yaml

Example healflow.yml (all runtime healing toggles default to true):

mode: local
output: verbose

healing:
  selector: true
  timing: true
  overlay: true
  iframe: true
  shadowDom: true
  auth: true
  network: true
  navigation: true
  mobile: true
  i18n: true
  upload: true
  multiTab: true

validation:
  requiredRuns: 3

Key types

• FailureCategory — 26 categories (selector, timing, overlay, iframe, …)
• FailureFamily — 23 matrix families (§1–§23)
• HealingStrategyType — 16 plan strategies
• HealFlowConfig — local/cloud mode, healing toggles, backend sync
• RuntimeHealRecord, FixProposalRecord, HealFlowRunArtifacts — .healflow/ artifact shapes

Development

pnpm --filter @healflow/shared build
pnpm --filter @healflow/shared typecheck
pnpm --filter @healflow/shared test

Related packages

• @healflow/classification — failure classification
• @healflow/playwright — runtime plugin

License

MIT