go-engine

module

v0.0.0-...-89d81dd Latest Latest Go to latest Published: Aug 11, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Artexis10/endstate

Links

Open Source Insights

README ¶

Endstate Go Engine

Go rewrite of the Endstate engine — a declarative system provisioning and recovery tool for Windows.

Module

github.com/Artexis10/endstate/go-engine

Requires Go 1.22 or later.

Structure

go-engine/
  cmd/endstate/main.go         CLI entrypoint (os.Args parsing, dispatch, JSON envelope output)
  internal/envelope/
    envelope.go                Envelope construction (NewSuccess, NewFailure, Marshal, BuildRunID)
    errors.go                  ErrorCode constants and Error type
    envelope_test.go           Table-driven unit tests
  internal/config/
    version.go                 VERSION and SCHEMA_VERSION file reading
    paths.go                   Repo root resolution, profile dir, ExpandWindowsEnvVars
  internal/manifest/
    types.go                   Manifest, App, RestoreEntry, VerifyEntry types
    loader.go                  JSONC comment stripping, includes resolution, circular detection
    validator.go               Profile validation per profile-contract.md
    loader_test.go             Table-driven manifest and validator tests
  internal/events/
    types.go                   NDJSON event types (Phase, Item, Summary, Error, Artifact)
    emitter.go                 Event emitter (writes NDJSON to stderr)
    emitter_test.go            Event emission and format tests
  internal/driver/
    driver.go                  Driver interface (Detect, Install)
    winget/
      detect.go                Winget package detection via winget list
      winget.go                Winget package installation with exit code parsing
      winget_test.go           Exec-mocked winget driver tests
  internal/commands/
    capabilities.go            capabilities command handler
    verify.go                  verify command (manifest load, detect, results envelope)
    apply.go                   apply command (plan/apply/verify phases, dry-run support)
    commands_test.go           Command tests with mock driver

Build

cd go-engine
go mod tidy
go build ./cmd/endstate

Run

# Capabilities handshake (JSON)
./endstate capabilities --json

# Human-readable
./endstate capabilities

# Debug flag resolution
./endstate apply --manifest ./manifest.jsonc --dry-run --debug-cli --json

Test

go test ./internal/envelope/...
go test ./...

Design Rules

No external CLI framework. Arg parsing uses os.Args only.
JSON envelope emitted as the last line of stdout, compact (no indentation).
RunId format: <command>-YYYYMMDD-HHMMSS-<HOSTNAME>
Every function returns (result, error). No panics.
Version strings read from VERSION and SCHEMA_VERSION files at repo root. ENDSTATE_ROOT env var overrides repo root detection.

Capabilities Response

The capabilities command returns the full handshake response expected by the Endstate GUI, including supported schema versions, commands with their flags, feature flags, and platform information. See docs/contracts/gui-integration-contract.md for the authoritative schema.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
endstate command Command endstate is the Go implementation of the Endstate CLI engine.	Command endstate is the Go implementation of the Endstate CLI engine.
endstate-validation command Command endstate-validation executes one repository-declared synthetic validation scenario through an already-built Endstate engine.	Command endstate-validation executes one repository-declared synthetic validation scenario through an already-built Endstate engine.
internal
arp Package arp reads Windows Add/Remove Programs inventory.	Package arp reads Windows Add/Remove Programs inventory.
backup Package backup wires the hosted-backup component stack from environment configuration.	Package backup wires the hosted-backup component stack from environment configuration.
backup/auth Package auth orchestrates the Hosted Backup login/logout/refresh/recover flows defined in docs/contracts/hosted-backup-contract.md §5–§6.	Package auth orchestrates the Hosted Backup login/logout/refresh/recover flows defined in docs/contracts/hosted-backup-contract.md §5–§6.
backup/client Package client provides a thin HTTP wrapper around the substrate Hosted Backup API.	Package client provides a thin HTTP wrapper around the substrate Hosted Backup API.
backup/crypto Package crypto implements the cryptographic primitives required by Endstate Hosted Backup as locked in docs/contracts/hosted-backup-contract.md (sections 1, 2, 3 and 6).	Package crypto implements the cryptographic primitives required by Endstate Hosted Backup as locked in docs/contracts/hosted-backup-contract.md (sections 1, 2, 3 and 6).
backup/download Package download orchestrates the chunked, encrypted download of a backup version from Endstate Hosted Backup.	Package download orchestrates the chunked, encrypted download of a backup version from Endstate Hosted Backup.
backup/keychain Package keychain provides a narrow Store/Load/Delete interface around the platform-native secret store.	Package keychain provides a narrow Store/Load/Delete interface around the platform-native secret store.
backup/manifest Package manifest models the encrypted-version manifest defined in docs/contracts/hosted-backup-contract.md §3 and the version-selection helpers used by `endstate backup pull`.	Package manifest models the encrypted-version manifest defined in docs/contracts/hosted-backup-contract.md §3 and the version-selection helpers used by `endstate backup pull`.
backup/oidc Package oidc fetches and caches the OIDC discovery document advertised by the substrate backend (or any self-host equivalent), validates the `endstate_extensions` block, and exposes the discovered endpoints + JWKS to the auth and client packages.	Package oidc fetches and caches the OIDC discovery document advertised by the substrate backend (or any self-host equivalent), validates the `endstate_extensions` block, and exposes the discovered endpoints + JWKS to the auth and client packages.
backup/storage Package storage wraps the substrate `/api/backups/*` API surface defined in docs/contracts/hosted-backup-contract.md §7.	Package storage wraps the substrate `/api/backups/*` API surface defined in docs/contracts/hosted-backup-contract.md §7.
backup/upload Package upload orchestrates the chunked, encrypted upload of a profile to Endstate Hosted Backup.	Package upload orchestrates the chunked, encrypted upload of a profile to Endstate Hosted Backup.
bootstrap Package bootstrap implements the backend-agnostic "the engine installs its own package backend when it is absent" contract: detect → consent → official install → verify → proceed-or-decline.	Package bootstrap implements the backend-agnostic "the engine installs its own package backend when it is absent" contract: detect → consent → official install → verify → proceed-or-decline.
bundle Package bundle provides zip-based profile bundle creation and extraction for the Endstate Go engine.	Package bundle provides zip-based profile bundle creation and extraction for the Endstate Go engine.
catalogplan Package catalogplan resolves one tracked bundle into revision-bound catalog module actions without selecting any package or application intent.	Package catalogplan resolves one tracked bundle into revision-bound catalog module actions without selecting any package or application intent.
commands Package commands contains the handler implementations for each Endstate CLI command.	Package commands contains the handler implementations for each Endstate CLI command.
config Package config provides version reading and path resolution for the Endstate Go engine.	Package config provides version reading and path resolution for the Endstate Go engine.
configdoc Package configdoc provides strict deterministic JSON and INI document edits.	Package configdoc provides strict deterministic JSON and INI document edits.
configrestore Package configrestore turns one successful generation staging result into a deterministic set of concrete target actions, verified pre-mutation snapshots, and durable transaction records.	Package configrestore turns one successful generation staging result into a deterministic set of concrete target actions, verified pre-mutation snapshots, and durable transaction records.
configtarget Package configtarget holds the canonical restore-target normalization and overlap semantics shared by the restore planner (which fails colliding sets) and the capture-time collision guard (which keeps one winner before a collision ever reaches a manifest).	Package configtarget holds the canonical restore-target normalization and overlap semantics shared by the restore planner (which fails colliding sets) and the capture-time collision guard (which keeps one winner before a collision ever reaches a manifest).
configvalidate Package configvalidate applies the engine-owned validation primitives to a staged or committed config-set root.	Package configvalidate applies the engine-owned validation primitives to a staged or committed config-set root.
driver Package driver defines the abstract Driver interface used by all package manager adapters (e.g.	Package driver defines the abstract Driver interface used by all package manager adapters (e.g.
driver/brew Package brew implements the driver.Driver interface for the macOS Homebrew package manager (`brew`).	Package brew implements the driver.Driver interface for the macOS Homebrew package manager (`brew`).
driver/chocolatey Package chocolatey implements Endstate's per-package driver for Chocolatey.	Package chocolatey implements Endstate's per-package driver for Chocolatey.
driver/winget Package winget implements the driver.Driver interface for Windows Package Manager (winget).	Package winget implements the driver.Driver interface for Windows Package Manager (winget).
envelope Package envelope provides the standard JSON output envelope for Endstate CLI commands as defined in the CLI JSON Contract v1.0.	Package envelope provides the standard JSON output envelope for Endstate CLI commands as defined in the CLI JSON Contract v1.0.
events Package events provides NDJSON streaming event emission for the Endstate engine as defined in docs/contracts/event-contract.md.	Package events provides NDJSON streaming event emission for the Endstate engine as defined in docs/contracts/event-contract.md.
importer Package importer parses external package-list formats (currently UniGetUI `.ubundle` backups/bundles) and maps them onto Endstate manifest app entries.	Package importer parses external package-list formats (currently UniGetUI `.ubundle` backups/bundles) and maps them onto Endstate manifest app entries.
manifest Package manifest provides JSONC manifest loading, include resolution, and profile validation for the Endstate engine.	Package manifest provides JSONC manifest loading, include resolution, and profile validation for the Endstate engine.
migration
modules Package modules provides config module catalog loading, app matching, and manifest expansion for the Endstate Go engine.	Package modules provides config module catalog loading, app matching, and manifest expansion for the Endstate Go engine.
packagesource Package packagesource owns the stable source identity used by package manifests, drivers, capture, and provisioning history.	Package packagesource owns the stable source identity used by package manifests, drivers, capture, and provisioning history.
planner Package planner computes a declarative plan by detecting each app in a manifest against the current system state via the driver interface.	Package planner computes a declarative plan by detecting each app in a manifest against the current system state via the driver interface.
provision Package provision owns the engine's Provisioning Generation: a numbered, inspectable, install-only record of the package set committed by a successful apply, written for both package backends (the winget driver and the Nix realizer).	Package provision owns the engine's Provisioning Generation: a numbered, inspectable, install-only record of the package set committed by a successful apply, written for both package backends (the winget driver and the Nix realizer).
realizer Package realizer defines the whole-set, declarative package backend interface used on platforms whose package manager converges a desired set as one atomic generation switch (e.g.	Package realizer defines the whole-set, declarative package backend interface used on platforms whose package manager converges a desired set as one atomic generation switch (e.g.
realizer/nix Package nix implements realizer.Realizer for Nix via `nix profile`.	Package nix implements realizer.Realizer for Nix via `nix profile`.
registryfile Package registryfile validates and semantically rewrites reg.exe documents without executing operating-system registry commands.	Package registryfile validates and semantically rewrites reg.exe documents without executing operating-system registry commands.
restore Package restore implements restore strategies (copy, merge-json, merge-ini, append, delete-glob), backup creation, journaling, and revert for the Endstate Go engine.	Package restore implements restore strategies (copy, merge-json, merge-ini, append, delete-glob), backup creation, journaling, and revert for the Endstate Go engine.
safepath Package safepath resolves strict portable paths beneath an engine-owned root.	Package safepath resolves strict portable paths beneath an engine-owned root.
schedule Package schedule provides the task-registration layer for the Endstate scheduled drift-check feature.	Package schedule provides the task-registration layer for the Endstate scheduled drift-check feature.
snapshot Package snapshot captures the current system state by running winget list and parsing the tabular output into structured SnapshotApp entries.	Package snapshot captures the current system state by running winget list and parsing the tabular output into structured SnapshotApp entries.
state Package state provides persistence for Endstate engine run state and history.	Package state provides persistence for Endstate engine run state and history.
validationci Package validationci owns compact, commit-bound CI evidence for the existing production validation planner and harness.	Package validationci owns compact, commit-bound CI evidence for the existing production validation planner and harness.
validationharness Package validationharness executes repository-owned validation scenarios through a separately built Endstate engine.	Package validationharness executes repository-owned validation scenarios through a separately built Endstate engine.
validationmatrix Package validationmatrix loads and validates repository-owned module validation sidecars without duplicating production module interpretation.	Package validationmatrix loads and validates repository-owned module validation sidecars without duplicating production module interpretation.
validationmode Package validationmode provides the fail-closed, disposable host boundary used by production-engine validation scenarios.	Package validationmode provides the fail-closed, disposable host boundary used by production-engine validation scenarios.
verifier Package verifier provides state assertion checkers for the Endstate verify pipeline.	Package verifier provides state assertion checkers for the Endstate verify pipeline.