@sealant/os-integration-buildkit

Purpose

@sealant/os-integration-buildkit is the concrete OS integration that compiles a normalized WorkspaceBlueprint into build artifacts using Docker BuildKit.

It currently ships executors for fedora, arch, and nix target OS families.

Why this package exists

• Translate composition-level contracts into concrete image build plans.
• Keep BuildKit-specific implementation details outside core composition.
• Produce reproducible artifacts for later registry publishing and runtime launch.

Execution model

The package implements one concrete executor class (BuildkitDistroOsExecutor) with two phases:

1. supports(input) validates whether the executor can compile the blueprint.
2. compile(input) renders a BuildKit context, runs Docker BuildKit, and emits standardized executor artifacts.

High-level flow:

1. Parse/validate input via parseBuildkitOsExecutorCompileInput(...).
2. Gate with getBuildkitExecutorSupport(...).
3. Map blueprint to ResolvedImagePlan.
4. Render build context files (Containerfile, entrypoint.sh, JSON metadata).
5. Run docker build and docker save.
6. Return a normalized BuildkitOsExecutorCompileResult.

Module map (exact responsibilities)

• src/buildkit-executor.ts
  • process execution (defaultCommandRunner)
  • distro catalog (distroDefinitions)
  • support gate (getBuildkitExecutorSupport)
  • package resolution (resolvePackages)
  • blueprint -> resolved plan mapping (mapBlueprintToResolvedImagePlan)
  • renderers for Containerfile, entrypoint, dotfiles step, lifecycle steps
  • build context writing (writeBuildContext)
  • docker invocation (buildImageTarball)
  • executor class and public factory/helpers
• src/index.ts
  • public exports only

Public surface

• BuildkitDistroOsExecutor
• createBuildkitOsExecutor(osFamily, options)
• mapBlueprintToBuildkitImagePlan(blueprint, osFamily)
• BuildkitCommandRunner
• BuildkitCommandResult
• BuildkitCommandOptions
• BuildkitOsExecutorOptions

Exports are defined in packages/os-integration-buildkit/src/index.ts.

Supported OS families

• fedora
• arch
• nix

Distro definitions

distroDefinitions drives almost all distro-specific behavior.

The same structure also includes:

• package id mappings (packageMap)
• mandatory internal packages (certs, ssh, shell/core tooling)
• shell binary paths for bash, zsh, fish

Support gate (supports)

supports(...) and compile(...) both use the same gate logic.

The executor rejects with normalized support failures when:

• target OS family is neither auto nor this executor's family (unsupported-os)
• harness id is not registered in @sealant/ai-harness-integrations (unsupported-harness)
• any package request includes a version pin (unsupported-package)
• any input source purpose is not dotfiles (unsupported-runtime-requirement)
• more than one dotfiles source is provided (unsupported-runtime-requirement)

Blueprint to image plan mapping

mapBlueprintToBuildkitImagePlan(...) returns a ResolvedImagePlan that is fully concrete for rendering.

Package resolution rules

Package requests are assembled in this order:

1. user-requested blueprint.tooling.packages
2. harness-required packages from harnessIntegration.installPackages
3. default shell package when non-bash shell is selected
4. dotfiles helper packages when dotfiles apply is enabled
   • always add git
   • add chezmoi and/or stow based on manager (auto adds both)

Each request resolves via distro packageMap if present; otherwise it falls back to passthrough (installPackages: [request.id]).

Duplicate install packages are removed later by normalizeInstallPackages(...) before rendering the install command.

Secret and dotfiles planning rules

• blueprint.sources.workspace.authRef -> runtime secret workspace_git_key
• dotfiles authRef with prefix github-installation-repository:<id>
  • dotfiles are marked applyAt: runtime
  • no build secret mount is emitted
  • githubInstallationRepositoryId is recorded in plan
• dotfiles authRef without that prefix
  • dotfiles are marked applyAt: build
  • build secret dotfiles_git_key is emitted
  • dotfiles plan contains authSecretId: dotfiles_git_key

Build context rendering

writeBuildContext(...) creates a temp directory like sealant-buildkit-<os>-* and writes:

• Containerfile
• entrypoint.sh
• resolved-image-plan.json
• buildkit-spec.json

It also calculates:

• image tarball output path: workspace-image.tar
• image name: sealant-workspace-<os>-<harness>
• image reference tag: <image-name>:<harness>

Containerfile generation

renderContainerfile(...) emits:

1. base image (FROM ...)
2. distro package install step
   • dnf: upgrade + install + clean
   • pacman: sync/update + install + cache clean
   • nix: nix profile add with flake refs
3. harness install step from integration metadata
   • nix rewrites npm install -g ... to npm install -g --prefix /usr/local ...
4. default shell setup
   • nix: ENV SHELL=...
   • others: usermod -s ... root
5. entrypoint copy + permissions
6. optional build-time dotfiles apply step when dotfiles.applyAt === "build"

Entrypoint generation

renderWorkspaceEntrypoint(...) is the runtime control script. It does all of the following:

• bootstraps runtime directories and base env (HOME, USER, PATH)
• fixes glibc loader symlink for nix images when missing (/lib64/ld-linux-x86-64.so.2)
• configures workspace clone auth from env
  • SSH key path via SEALANT_WORKSPACE_AUTH_KEY_BASE64
  • HTTP askpass via SEALANT_WORKSPACE_HTTP_TOKEN
• conditionally configures and starts SSHD when SEALANT_ENABLE_SSH is truthy
  • authorized keys from file or SEALANT_SSH_AUTHORIZED_KEYS_BASE64
  • generates host key if missing
  • creates forced shell wrapper at /usr/local/bin/workspace-ssh-shell
• clones workspace repository when .git is absent
• clears clone auth material after clone (cleanup_workspace_clone_auth)
• optionally applies dotfiles at runtime when plan requires runtime apply
• runs lifecycle setup and startup steps from blueprint
• executes foreground command in this precedence:
  1. SEALANT_FOREGROUND_COMMAND override
  2. blueprint startup command (if foreground.kind === "command")
  3. harness launch command in selected default shell

Docker execution

buildImageTarball(...) runs exactly two commands:

1. docker build --file <Containerfile> ... --tag <image-ref> <context-dir>
2. docker save --output <workspace-image.tar> <image-ref>

Build-time secrets are passed as Docker BuildKit --secret flags from spec.secrets.

The default command runner (defaultCommandRunner) also:

• sets DOCKER_BUILDKIT=1
• captures stdout/stderr
• throws buildkit-command-failed on non-zero exit or signal

Compile output contract

compile(...) returns a parsed BuildkitOsExecutorCompileResult with:

• executor identity (id, osFamily)
• artifacts
  • oci-image tarball (loader: docker-load)
  • metadata JSON for resolved image plan
  • metadata JSON for buildkit spec
• metadata notes and default artifact name
• buildkit extension object containing full imagePlan and spec

This result is the bridge used by downstream registry/runtime orchestration.

Runtime environment variables consumed by entrypoint

Primary runtime controls read by generated entrypoint.sh:

• SEALANT_ENABLE_SSH, SEALANT_SSH_PORT
• SEALANT_SSH_AUTHORIZED_KEYS_FILE, SEALANT_SSH_AUTHORIZED_KEYS_BASE64
• SEALANT_WORKSPACE_AUTH_KEY_BASE64
• SEALANT_WORKSPACE_HTTP_TOKEN, SEALANT_WORKSPACE_HTTP_USERNAME
• SEALANT_DOTFILES_HTTP_TOKEN, SEALANT_DOTFILES_HTTP_USERNAME (runtime dotfiles only)
• SEALANT_FOREGROUND_COMMAND
• SEALANT_OCI_RUNTIME (special shell handling for runsc)

Current constraints and non-goals

• only one dotfiles input source is supported
• non-dotfiles input purposes are rejected
• package version pinning is rejected
• package id compatibility is mostly best-effort (unknown ids pass through)
• build spec is generated for local build output (push: false) and tarball export

Cross-package dependency

• Depends on @sealant/ai-harness-integrations for harness install/launch contracts.
• Depends on @sealant/workspace-composition for schemas/contracts and compile result types.

Internal dependencies

• Internal package dependencies:
  • @sealant/ai-harness-integrations
  • @sealant/workspace-composition
• External runtime dependencies:
  • Docker CLI and daemon (for build/save)
  • Node.js child process and fs APIs

Scripts

• pnpm --filter @sealant/os-integration-buildkit lint
• pnpm --filter @sealant/os-integration-buildkit test
• pnpm --filter @sealant/os-integration-buildkit typecheck