Metadata-Version: 2.4
Name: abssctl
Version: 0.1.0a1
Summary: Actual Budget Multi-Instance Sync Server Admin CLI
Author-email: Ken Robinson <doccyblade@homepost.org>
License: MIT License
        
        Copyright (c) 2025 Ken Robinson (DocCyblade)
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: actual,admin,budget,cli,turnkey
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
Requires-Dist: ruff>=0.5.5; extra == 'dev'
Requires-Dist: sphinx-autobuild>=2024.4; extra == 'dev'
Requires-Dist: sphinx-rtd-theme; extra == 'dev'
Requires-Dist: sphinx>=7.4; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Description-Content-Type: text/x-rst

======================================
abssctl — Actual Sync Server Admin CLI
======================================

.. image:: https://img.shields.io/badge/status-alpha-blue
   :alt: Project maturity badge showing Alpha status

``abssctl`` is a planned, batteries-included command line tool that installs and
manages multiple Actual Budget Sync Server instances on the TurnKey Linux
Node.js appliance. The CLI will own the full lifecycle: provisioning new
instances, performing upgrades or rollbacks, managing nginx and systemd
integrations, and producing support bundles for operators.

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)
===============================

.. note::
   The CLI is still stabilising APIs during Alpha. Initial commands focus on
   configuration and read-only inspection; mutating workflows arrive once the
   providers and state engine solidify.

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).

Roadmap & Specifications
========================

- Requirements & project plan: ``docs/requirements/abssctl-app-specs.txt``
- 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.
