Library Overview

Use @ex-machina/facets programmatically in your own tools.

The @ex-machina/facets package exports its core functions for programmatic use. Everything the CLI can do is available as a library.

Installation

bun add @ex-machina/facets

Import

import {
  // Registry
  loadManifest,
  FacetManifestSchema,
  FacetsYamlSchema,
  FacetsLockSchema,
  readFacetsYaml,
  writeFacetsYaml,
  readFacetsLock,
  writeFacetsLock,

  // Discovery
  listFacets,
  cacheFacet,
  updateFacet,
  updateAllFacets,
  clearCache,

  // Installation
  installFacet,
  uninstallFacet,
} from '@ex-machina/facets'

Subsystems

The library is organized into three subsystems:

Subsystem	Purpose	Key exports
Registry	Load manifests, read/write config files, validate schemas	loadManifest, FacetManifestSchema, readFacetsYaml
Discovery	List, cache, update, and clear facets	listFacets, cacheFacet, updateFacet, clearCache
Installation	Install and uninstall facet resources	installFacet, uninstallFacet

Result pattern

Most functions return discriminated union result types instead of throwing exceptions:

const result = await installFacet('my-facet', projectRoot)
if (result.success) {
  console.log(`Installed ${result.facet}`, result.resources)
} else {
  console.error(`Failed: ${result.reason}`)
}

This makes error handling explicit and type-safe.