App

Constructors

Constructor

new App(options?: object): App

Parameters

Parameter	Type	Description
options	{ header?: string | ((vars: HeaderVariables) => string) | null; lockfile?: string | null; options?: GhagenOptions; root?: string; transforms?: readonly Transform[]; }	‐
options.header?	string | ((vars: HeaderVariables) => string) | null	Header comment for every generated file. Four shapes are accepted: omit / undefined — emit ghagen’s default header. null — emit no header. string — emit the string verbatim. No {variable} substitution; literal braces are preserved. (vars) => string — invoke the closure with a fully-populated HeaderVariables (see the emitter module for the typed shape) and emit the returned string.
options.lockfile?	string | null	Path to the pin lockfile, relative to root. Set to null to disable lockfile auto-loading. Defaults to .ghagen.lock.yml.
options.options?	GhagenOptions	Pre-loaded project options. When omitted, App reads them from .ghagen.yml itself (standalone new App() works unchanged); pass a value to avoid a redundant read when the config was already parsed.
options.root?	string	Repository root directory. All registered output paths and the lockfile are resolved relative to this. Defaults to process.cwd().
options.transforms?	readonly Transform[]	Additional model transforms to apply during synthesis. The pin transform is auto-registered when a lockfile is present; these are appended after it.

Returns

App

Properties

Property	Modifier	Type
_userTransforms	readonly	readonly Transform[]
headerTxt	readonly	string | ((vars: HeaderVariables) => string) | null | undefined
lockfilePath	readonly	string | null
rootAbsPath	readonly	string

Methods

add()

add(item: Document, path: string): void

Register an item at an explicit path relative to root.

Use this escape hatch when you need to write to a path that doesn’t fit the standard conventions. For the common cases, prefer addWorkflow() / addAction().

Parameters

Parameter	Type
item	Document
path	string

Returns

void

---

addAction()

addAction(action: ActionModel, dir?: string): void

Register an action, writing {dir}/action.yml (defaults to repo root).

Parameters

Parameter	Type	Default value
action	ActionModel	undefined
dir	string	"."

Returns

void

---

addWorkflow()

addWorkflow(workflow: WorkflowModel, filename: string): void

Register a workflow at .github/workflows/{filename}.

Parameters

Parameter	Type
workflow	WorkflowModel
filename	string

Returns

void

---

check()

check(): [string, string][]

Check whether the on-disk YAML matches what synth() would write.

Returns one [path, diff] tuple for each file that’s stale or missing. An empty list means everything is in sync.

Returns

[string, string][]

---

documents()

documents(): Document[]

The registered Documents (Workflows and Actions), in registration order.

The public accessor for pin and other read-only consumers; the { item, relPath } storage stays internal to App.

Returns

Document[]

---

synth()

synth(): string[]

Synthesize all registered items to YAML files.

Returns the absolute paths of every file written. Synchronous: render and every transform are synchronous, and file writes use the sync node:fs API.

Returns

string[]