Project Facts

• Project name: Actual Budget Multi-Instance Sync Server Admin CLI.

• CLI executable: abssctl (Actual Budget Sync Server ConTroL).

The project is currently in the Alpha (foundations) phase. The repository builds on the bootstrap work from Pre-Alpha and now focuses on wiring core services: configuration, state management, and read-only workflows that unlock future instance operations.

Key Objectives

• Provide a predictable Python package that can be installed with pip or pipx and exposes an abssctl executable.

• Establish documentation sources in reStructuredText with Sphinx as the build system (see docs/source).

• Enforce quality gates via linting, type checking, and tests in continuous integration.

• Capture all architectural decisions in docs/adrs and maintain living requirements under docs/requirements.

Quick Start (Alpha Foundations)

1. Create a Python 3.11 virtual environment stored in .venv with a prompt label dev and activate it:

   python3.11 -m venv .venv --prompt dev
   source .venv/bin/activate

2. Install the package in editable mode together with developer dependencies:

   pip install -e .[dev]

   This registers abssctl with your virtualenv so commands and tests import without needing to tweak PYTHONPATH.

3. Run the basic quality checks:

   ruff check src tests
   mypy src
   pytest

4. Invoke the CLI skeleton:

   abssctl --help
   abssctl --version
   abssctl config show
   abssctl version list --json
   abssctl instance list --json

Repository Layout

• src/abssctl — Python package containing the Typer-based CLI scaffold.

• tests — Pytest suite covering CLI entry points and future modules.

• docs — Requirements, ADRs, Sphinx sources, and generated support matrix.

• tools — Utility scripts used during development (e.g., support matrix generator).

Configuration Basics

The configuration loader follows ADR-023 precedence: built-in defaults, /etc/abssctl/config.yml, environment variables prefixed with ABSSCTL_, and finally CLI overrides such as --config-file. Use abssctl config show (or --json) to inspect the merged values and confirm environment overrides are applied as expected.

Read-only registry commands are now wired up: abssctl version list and abssctl instance list surface the contents of versions.yml and instances.yml respectively, while abssctl instance show <name> displays details for a single instance. Use --remote with version list to pull published versions from npm when the CLI is available (falls back gracefully if npm is missing). All commands accept --config-file so you can point at alternate configuration sources when testing or operating multiple environments.

Roadmap & Specifications

• Requirements & project plan: docs/requirements/abssctl-app-specs.txt

• Milestone roadmap tracker: docs/roadmap.rst

• Architecture Decision Records: docs/adrs

• Support matrix source: docs/support/actual-support-matrix.yml

Community & Licensing

The project is released under the MIT License (LICENSE). Contributions are welcome—please review the developer guide skeleton under docs/source for the expected workflow and coding standards as they evolve.

Branch Strategy

• main — production-ready releases tagged for PyPI.

• dev — integration branch for upcoming development builds.

• dev-alpha — working branch for the foundations milestone and experimental CLI work.

• Short-lived feature branches support focused working sessions.

Roadmap Snapshot

• Pre-Alpha — Repo Bootstrap (complete): scaffold layout, pyproject.toml, docs skeleton, CI with lint/test.

• Alpha Builds — Foundations: CLI skeleton beyond placeholders, config loader, logging, state/lock primitives, template engine, read-only commands, JSON output plumbing. Publish dev builds to PyPI from tags on dev.

• Beta Releases — Core Features: Version operations, instance lifecycle, systemd/nginx providers, doctor basics. All updates become non-destructive or ship with migration hooks.

• Release Candidate — Quality & Docs: Support bundle, robust errors, man pages & completion, full docs & examples, CI integration tests on TurnKey Linux VMs. Automate PyPI release from GitHub actions.

• Release — v1.0.0: Burn-in testing across supported Actual versions, release on a green pipeline with documentation sign-off.