Files
bible/rules/patterns/app-binary/contract.md
T

2.1 KiB

Contract: Application Binary

Version: 1.2

Purpose

Правила сборки, упаковки ресурсов и первого запуска Go-приложений.

See README.md for deployment examples and a sample config template.

Rules

  • When the agent deploys or runs commands on a host, the application lives in /appdata/<appname>/.
  • Do not suggest alternate default install paths such as /opt, /usr/local/bin, or ~/.
  • The binary must be self-contained. Templates, static assets, config templates, and DB migrations are embedded with //go:embed or an equivalent application-owned mechanism.
  • Startup and local UI operation must work without public internet access. Vendor and embed all required third-party assets and code; do not require a CDN, remote font, package download, package manager or separately installed UI library at runtime. Configured remote data sources may require connectivity for their own operations.
  • The application creates its config automatically on first run if it does not exist yet.
  • Default config path:
    • single-user mode: ~/.config/<appname>/config.yaml
    • server or multi-user mode: /etc/<appname>/config.yaml or next to the binary
  • Config stores application settings and centralized DB credentials only. It must not store user data, cache/state, or SQLite path configuration.
  • For local SQLite mode, the database file lives next to the config and its path is derived by the application, not configured separately.
  • On first run with no config, the application must create the config, print its path, exit 0, and stop. It must not continue startup with a fresh placeholder config.
  • The binary must not depend on the caller's working directory.
  • Assets bundled at compile time (//go:embed and equivalents) do not hot-reload. Before diagnosing a bug reported against a generated or served artifact, confirm the running process was rebuilt and restarted after the last change; use the displayed build version (build-version-display) to check.
  • Build with CGO_ENABLED=0 when possible. Enable CGO only when the chosen storage/runtime actually requires it, such as SQLite drivers that need CGO.