restic-profile-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{restic_profile_cli-0.4.0 → restic_profile_cli-0.5.0}/.ansible-lint

@@ -2,11 +2,10 @@
 # ansible-lint configuration
 # https://ansible.readthedocs.io/projects/lint/configuring/
 #
-# Run with:  ansible-lint
-#            ansible-lint
-
-# Use the 'basic' profile - enforces the most important rules without
-# being overly strict for a project that is still evolving.
+# Run with: ansible-lint
+#
+# Use the 'production' profile - the strictest built-in profile, which
+# includes the checks from every lower profile as well.
 # Profiles in ascending order of strictness:
 #   min → basic → moderate → safety → shared → production
 profile: production
@@ -15,13 +14,13 @@ profile: production
 exclude_paths:
   - .venv/
   - .git/
+  - .molecule/
   - site/
   - dist/
-  - molecule/
   - examples/
   - playbooks/host_vars/
   - playbooks/group_vars/
-  - mkdocs.yaml
+  - mkdocs.yml
 
 # Rules to warn about instead of failing on.
 # These are either stylistic preferences or rules that generate too many
@@ -38,13 +37,7 @@ warn_list:
 skip_list:
   - name[casing]
 
-# Lint only the paths relevant to Ansible content; ignore the Python
-# source tree and documentation.
-kinds:
-  - playbook: "playbooks/*.yaml"
-  - tasks: "roles/*/tasks/*.yaml"
-  - handlers: "roles/*/handlers/*.yaml"
-  - vars: "roles/*/vars/*.yaml"
-  - defaults: "roles/*/defaults/*.yaml"
-  - meta: "roles/*/meta/*.yaml"
-  - yaml: "roles/*/molecule/**/*.yaml"
+# Do not add a `kinds:` mapping back. The default kind detection already
+# covers every path in this repository; remapping role `defaults/` or `vars/`
+# files to a custom kind silently disables `var-naming[no-role-prefix]`, and
+# remapping Molecule playbooks to the plain "yaml" kind skips playbook rules.

restic_profile_cli-0.5.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+---
+# Keep SHA-pinned GitHub Actions and uv dependencies up to date. Version
+# updates wait out a 7-day cooldown (security updates are exempt) so a
+# compromised release is likely to be yanked before Dependabot opens a PR.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7
+
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    cooldown:
+      default-days: 7

restic_profile_cli-0.5.0/.github/workflows/ci.yaml

@@ -0,0 +1,127 @@
+---
+name: ci
+
+on:
+  # Reusable entry point for publish-to-pypi and any future caller.
+  workflow_call: ~
+  workflow_dispatch: ~
+  push:
+    branches:
+      - master
+      - dev
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  python:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+          - "3.14"
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install the project
+        run: uv sync --locked --group dev
+
+      - name: Lint and format check
+        run: |
+          uv run ruff check src/ tests/ plugins/
+          uv run ruff format --check src/ tests/ plugins/
+
+      - name: Type check
+        run: uv run ty check src/ plugins/
+
+      - name: Run tests
+        run: uv run pytest -v tests/
+
+      - name: Build documentation
+        if: matrix.python-version == '3.13'
+        run: NO_MKDOCS_2_WARNING=1 uv run mkdocs build --strict
+
+  ansible-lint:
+    name: Ansible lint
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.13"
+
+      - name: Install the project
+        run: uv sync --locked --group dev
+
+      - name: Install the collection and scenario requirements
+        run: |
+          mkdir -p .ansible/collections
+          uv run ansible-galaxy collection install --force --collections-path .ansible/collections .
+          uv run ansible-galaxy collection install -r requirements.yaml -p .ansible/collections
+
+      - name: Run ansible-lint
+        run: uv run ansible-lint
+
+  molecule:
+    name: Molecule
+    runs-on: ubuntu-24.04
+    timeout-minutes: 60
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.13"
+
+      - name: Install the project
+        run: uv sync --locked --group dev
+
+      # Rootful Podman is required for the systemd containers (the same
+      # recipe as ak1ra-lab/docker-systemd). The runner needs Python and uv
+      # for Molecule and for the role's local wheel build.
+      - name: Install Podman
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y podman
+
+      - name: Install the collection and scenario requirements
+        run: |
+          mkdir -p .ansible/collections
+          uv run ansible-galaxy collection install --force --collections-path .ansible/collections .
+          uv run ansible-galaxy collection install -r requirements.yaml -p .ansible/collections
+
+      - name: Run the Molecule scenarios
+        run: >-
+          sudo env "PATH=${PWD}/.venv/bin:${PATH}"
+          MOLECULE_GLOB='extensions/molecule/**/molecule.yml'
+          molecule test --all

{restic_profile_cli-0.4.0 → restic_profile_cli-0.5.0}/.github/workflows/docs.yaml

@@ -8,50 +8,55 @@ on:
       - master
     paths:
       - "docs/**"
-      - "README.md"
       - "mkdocs.yml"
       - ".github/workflows/docs.yaml"
 
 permissions:
   contents: read
 
-  pages: write
-  id-token: write
-
 concurrency:
   group: docs
   cancel-in-progress: false
 
 jobs:
   build:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
     steps:
-      - uses: actions/checkout@v6
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
+          persist-credentials: false
           fetch-depth: 0
           fetch-tags: true
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v7
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.13"
 
       - name: Install the project
         run: uv sync --locked --group docs
 
       - name: Build documentation
-        run: NO_MKDOCS_2_WARNING=1 uv run mkdocs build
+        run: NO_MKDOCS_2_WARNING=1 uv run mkdocs build --strict
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: site
 
   deploy:
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

restic_profile_cli-0.5.0/.github/workflows/publish-to-pypi.yaml

@@ -0,0 +1,57 @@
+---
+name: publish-to-pypi
+
+on:
+  workflow_dispatch: ~
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  # Run the complete reusable suite (Python tests, ansible-lint, Molecule)
+  # before anything is uploaded.
+  ci:
+    permissions:
+      contents: read
+    # ./ is used instead of the newer $/ self-repository syntax because
+    # actionlint 1.7.12 (latest at the time of writing) cannot parse $/ yet.
+    uses: ./.github/workflows/ci.yaml
+
+  build-n-push:
+    name: upload release to PyPI
+    needs: ci
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    environment:
+      name: pypi
+      url: https://pypi.org/project/restic-profile/
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out the repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+          fetch-tags: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.13"
+          enable-cache: false
+
+      - name: Install the project
+        run: uv sync --locked --group dev
+
+      - name: Build a binary wheel and a source tarball
+        run: uv build -v
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

{restic_profile_cli-0.4.0 → restic_profile_cli-0.5.0}/.gitignore

@@ -327,6 +327,7 @@ __marimo__/
 
 # Ansible
 .ansible/*
+.molecule/
 inventory/*.yaml
 playbooks/host_vars/**/*.yaml
 playbooks/group_vars/**/*.yaml
@@ -351,6 +352,8 @@ credentials.yaml
 examples/*
 
 ## LLM
-docs/sessions/*
+.agents/sessions/*
 .agents/state/sessions/*
 .antigravitycli/*
+.opencode/
+openspec/

{restic_profile_cli-0.4.0 → restic_profile_cli-0.5.0}/.pre-commit-config.yaml

@@ -28,14 +28,14 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.15.20
+    rev: v0.17.2
     hooks:
       - id: ruff-check
         args: [--fix]
       - id: ruff-format
 
   - repo: https://github.com/astral-sh/uv-pre-commit
-    rev: 0.11.27
+    rev: 0.12.10
     hooks:
       - id: uv-lock
 
@@ -43,15 +43,16 @@ repos:
     hooks:
       - id: ty
         name: ty
-        entry: uv run ty check
+        entry: uv run ty check src/ plugins/
         language: system
-        files: ^src/
+        files: ^(src|plugins)/
         types_or: [python, pyi]
+        pass_filenames: false
         require_serial: true
 
       - id: ansible-lint
         name: ansible-lint
-        entry: ansible-lint
+        entry: uv run ansible-lint
         language: system
         types: [yaml]
         require_serial: true

restic_profile_cli-0.5.0/AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md
+
+`restic-profile` = a Python CLI (`src/restic_profile/`, tests mirror it under
+`tests/`) plus Ansible roles (`roles/restic_profile`, `roles/restic_rest_server`).
+See `README.md` for the deployment workflow.
+
+## Tooling - use these, not the defaults
+
+`just <recipe>` is a convenience wrapper for humans; each recipe is a thin
+`uv run ...` (see `justfile`). Agents can call `uv run ...` directly when that is
+more flexible - the two are equivalent, not mutually exclusive.
+
+- Env/deps: **uv** (`just sync` = `uv sync --group dev`). Never `pip`/`poetry`/`pipenv`.
+  The `dev` group includes the Ansible toolchain (`ansible-core`, `ansible-lint`,
+  `molecule`).
+- Lint+format: **ruff** (`just lint` = `uv run ruff check --fix` then
+  `uv run ruff format`, over `src/ tests/ plugins/`). Never `black`/`isort`/`flake8`.
+- Typecheck: **ty** (astral-sh/ty), `src/ plugins/` only
+  (`just typecheck` = `uv run ty check src/ plugins/`). Never `mypy`.
+- Tests: **pytest**. `just test *ARGS` = `uv run pytest -v {{ARGS}} tests/` - ARGS
+  go *before* `tests/`, so `just test -k <pattern>`. Or run
+  `uv run pytest -v tests/test_file.py` directly.
+- Ansible lint: `just ansible-lint` (installs the collection and requirements
+  first, then runs `uv run ansible-lint`).
+- Molecule: `just molecule-test` / `just molecule-test-one <scenario>` /
+  `just molecule-list` (see Testing below).
+- Docs: `just docs-build` = `NO_MKDOCS_2_WARNING=1 uv run mkdocs build`.
+- Build: `just build` = `uv build`.
+
+Python changes MUST pass lint, typecheck, and test before commit.
+
+## Ansible (self-contained layout)
+
+`ansible.cfg` pins `roles_path=./roles` and `collections_path=./.ansible/collections`
+so role and collection resolution never reaches user-level/parent paths. The
+inventory path still includes `~/.ansible/inventory` by design. Playbooks
+reference roles by FQCN (`ak1ra_lab.restic_profile.*`). Before running
+`ansible-lint` or any playbook, install the dependencies into the project-local
+tree:
+
+```shell
+ansible-galaxy collection install -r requirements.yaml -p ./.ansible/collections
+```
+
+- `requirements.yaml` deps: `ansible.posix`, `community.general`,
+  `containers.podman`, `community.docker`, and `ak1ra_lab.general` (not on
+  Galaxy, pulled from git).
+- `ansible-lint` (non-`offline` mode, run from repo root) auto-installs
+  `requirements.yaml` into its own cache dir `./.ansible/collections` - computed
+  by ansible-compat from the project dir, ignoring `ansible.cfg`'s `collections_path`.
+
+Ansible changes MUST pass `ansible-lint` before commit.
+
+## Testing (Molecule)
+
+Ansible behavior is covered by ansible-native Molecule scenarios under
+`extensions/molecule/` (collection layout; the old role-level legacy scenario
+has been removed).
+
+- `config.yml` - shared config: test inventory, project-local collections path,
+  `shared_state: true`, and the component test sequence.
+- `default/` - the only lifecycle manager (`create` / `destroy`); it creates the
+  shared systemd containers from `ghcr.io/ak1ra-lab/docker-systemd`.
+- `restic_profile/basic` - system-scope backup and retention-only profiles on
+  Debian 13, Ubuntu 26.04, Rocky 10, and Fedora 44.
+- `restic_profile/user_scope` - user-scope timer on Debian 13, including the
+  PAM/linger prerequisites for the per-user systemd manager.
+- `restic_rest_server/basic` - Debian package deployment, htpasswd auth, and
+  explicit test teardown.
+
+Prerequisites: `just ansible-collection-install` and
+`just ansible-requirements-install`, plus `uv` and a container runtime
+(rootless Podman works; CI uses rootful Podman). The container images and
+supported host matrix are documented in `extensions/molecule/inventory/`.
+Role, task, or template changes SHOULD pass the relevant Molecule scenario;
+run the full suite before a release. Molecule caches scenario state: after
+changing a `molecule.yml`, run `uv run molecule reset` (or `molecule destroy`)
+so prepare/create are re-run. A distro is eligible for the matrix only when
+its image's bundled Python satisfies the project's `>=3.11` floor; drop the
+distro instead of installing a newer Python next to it.
+
+## Docs (bilingual)
+
+`docs/` is served by mkdocs with the i18n plugin (`docs_structure: suffix`):
+every page has an English `*.md` and a Simplified-Chinese `*.zh.md` sibling
+(e.g. `cli.md` + `cli.zh.md`). When adding or changing user-facing behavior,
+update BOTH language files.

{restic_profile_cli-0.4.0 → restic_profile_cli-0.5.0}/CHANGELOG.md

@@ -5,6 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-10-24
+
+### Added
+
+- Add Python 3.14 to the published package classifiers
+- Validate `restic_profile_state` against `present`/`absent` during preflight
+- Create the `restic_rest_server_backup_dir` storage root with service-user
+  ownership before starting `rest-server`
+
+### Changed
+
+- Limit the official distribution matrix to the latest tested releases:
+  Debian 13, Ubuntu 26.04, Rocky Linux 10, and Fedora 44; drop EL 9 and
+  Fedora 43 from the role metadata
+- Raise the minimum supported `ansible-core` version to 2.18
+- Escape user-provided values when rendering `restic-profile.toml` so quotes,
+  backslashes, and newlines in credentials or paths produce valid TOML
+- Treat notification delivery as best-effort: transport errors are logged and
+  no longer mask the backup or retention result
+- Use `module.run_command` in the `systemd_timer_state` module instead of
+  calling `subprocess` directly
+
+### Removed
+
+- Remove the Test PyPI publishing workflow and its README badge
+
+### Fixed
+
+- Accept the required profile name with `--unlock` instead of rejecting the
+  combination as invalid
+- Keep `--unlock` in dry-run mode when `--dry-run notify` is used
+- Report inline retention failures as retention failures instead of backup
+  failures
+- Stop active timers before `daemon-reload` when their scheduling changes
+- Align package-cache refresh and platform metadata across all supported
+  distributions
+- Reject unknown keys in the TOML configuration instead of silently ignoring
+  them
+
+## [0.4.1] - 2026-08-11
+
+### Changed
+
+- Update the built-in `notify_success.md.j2` template formatting for headings
+  and diff summary list items
+
 ## [0.4.0] - 2026-08-11
 
 ### Added

restic_profile_cli-0.5.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.5
+Name: restic-profile-cli
+Version: 0.5.0
+Summary: Profile-based restic wrapper with Ansible deployment support
+Project-URL: Homepage, https://github.com/ak1ra-lab/restic-profile
+Project-URL: Repository, https://github.com/ak1ra-lab/restic-profile
+Project-URL: Documentation, https://ak1ra-lab.github.io/restic-profile/
+Author-email: ak1ra <git@ak1ra.xyz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ansible,backup,restic
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Requires-Dist: argcomplete>=3.7.0
+Requires-Dist: chaos-utils>=0.5.0
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: pydantic>=2.13.3
+Description-Content-Type: text/markdown
+
+# restic-profile
+
+**English** | [简体中文](https://github.com/ak1ra-lab/restic-profile/blob/master/README.zh-CN.md)
+
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/restic-profile/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/restic-profile/actions/workflows/publish-to-pypi.yaml)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli)](https://pypi.org/project/restic-profile-cli/)
+[![Docs](https://img.shields.io/badge/docs-online-0a7ea4)](https://ak1ra-lab.github.io/restic-profile/)
+
+Profile-based [restic](https://restic.net/) wrapper, deployed with Ansible.
+
+This repository is an Ansible collection (`ak1ra_lab.restic_profile`) plus the
+`restic-profile` CLI it installs:
+
+- **restic-profile** - reads a TOML config and runs `restic backup` / `forget` /
+  `prune` with hooks and IM notifications.
+- **restic_profile** role - deploys the CLI, renders the TOML config, and manages
+  one systemd timer per profile (including user-level `systemd_scope: user`).
+- **restic_rest_server** role - deploys a [rest-server](https://github.com/restic/rest-server)
+  instance for remote backup storage.
+
+## Install the CLI
+
+Install the CLI on its own - Ansible, root, and systemd are not needed. `restic`
+must be installed and on `PATH`:
+
+```shell
+uv tool install restic-profile-cli
+restic-profile --help
+```
+
+Start from the [TOML config template][toml].
+
+## Deploy with Ansible
+
+```shell
+git clone https://github.com/ak1ra-lab/restic-profile.git
+cd restic-profile
+ansible-galaxy collection install -r requirements.yaml -p ./.ansible/collections
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+Pick an example from [Ansible examples][examples], fill in your `host_vars`, and
+run the playbook. See [Ansible toolchain][toolchain] for the control-node setup;
+building restic from source (`restic_profile_restic_install_source: go_build`)
+also needs a `go` toolchain.
+
+## Documentation
+
+Full documentation: <https://ak1ra-lab.github.io/restic-profile/>
+
+- [Ansible examples][examples]
+- [TOML config template][toml]
+- [CLI reference][cli]
+- [restic-rest-server][server]
+- [Ansible toolchain][toolchain]
+
+## Development
+
+```shell
+uv sync --group dev
+just lint
+just typecheck
+just test
+```
+
+See [AGENTS.md](https://github.com/ak1ra-lab/restic-profile/blob/master/AGENTS.md)
+for the Ansible, Molecule, and documentation workflow.
+
+[examples]: https://ak1ra-lab.github.io/restic-profile/restic-profile/examples/
+[toml]: https://ak1ra-lab.github.io/restic-profile/restic-profile/toml-config/
+[cli]: https://ak1ra-lab.github.io/restic-profile/restic-profile/cli/
+[server]: https://ak1ra-lab.github.io/restic-profile/restic-rest-server/
+[toolchain]: https://ak1ra-lab.github.io/restic-profile/ansible-toolchain/