Skip to main content
The registry subsystem handles loading and validating facet manifests, and reading/writing the project config files (facets.yaml and facets.lock).

​
loadManifest(path)

Loads and validates a facet.yaml manifest from disk. Three-phase process: read file, parse YAML, validate with Zod. 
import { loadManifest } from '@ex-machina/facets'

const result = await loadManifest('/path/to/facet.yaml')
if (result.success) {
  console.log(result.manifest.name, result.manifest.version)
} else {
  console.error(result.error)
}
Parameters:
ParameterTypeDescription
manifestPathstringAbsolute path to a facet.yaml file
Returns: Promise<LoadManifestResult> 
type LoadManifestResult =
  | { success: true; manifest: FacetManifest }
  | { success: false; error: string }

​
Config file functions

​
readFacetsYaml(projectRoot)

Reads and parses .opencode/facets.yaml. Returns a default empty object if the file doesn’t exist or is invalid. 
const yaml = await readFacetsYaml('/path/to/project')
// { remote: { viper: { url: '...', version: '1.0.0' } }, local: [] }

​
writeFacetsYaml(projectRoot, data)

Writes facets.yaml back to disk, serializing the data as YAML. 
await writeFacetsYaml('/path/to/project', {
  remote: { viper: { url: 'https://...', version: '1.0.0' } },
  local: [],
})

​
readFacetsLock(projectRoot)

Reads and parses .opencode/facets.lock. Returns a default empty object if the file doesn’t exist.

​
writeFacetsLock(projectRoot, data)

Writes facets.lock back to disk.

​
Schemas

All schemas are defined with Zod v4 and exported for reuse:

​
FacetManifestSchema

Validates a single facet’s facet.yaml. See Manifest Reference for the full field list.

​
FacetsYamlSchema

Validates the project-level facets.yaml: 
{
  remote?: Record<string, { url: string; version?: string }>
  local?: string[]
}

​
FacetsLockSchema

Validates the lock file facets.lock: 
{
  remote?: Record<string, { url: string; version: string; integrity: string }>
}

​
Helper functions

​
normalizeRequires(requires)

Normalizes a requires field (string, string array, or undefined) to always return a string[].

​
resolvePromptPath(prompt)

Resolves a prompt field to a local file path. Returns null for URL-based prompts.