├── tests
    ├── __init__.py
    ├── requirements.txt
    ├── test_commands__cron.py
    ├── conftest.py
    ├── test_commands__list.py
    ├── test_commands__add.py
    ├── test_commands__run.py
    └── test_commands__remove.py
├── requirements.txt
├── runchain
    ├── __main__.py
    ├── __init__.py
    ├── exceptions.py
    ├── commands.py
    └── chain.py
├── docs
    ├── requirements.txt
    ├── environment.rst
    ├── changelog.rst
    ├── index.rst
    ├── Makefile
    ├── make.bat
    ├── contributing.rst
    ├── api.rst
    ├── quickstart.rst
    ├── conf.py
    ├── howto-backup.rst
    └── commands.rst
├── .readthedocs.yaml
├── .pre-commit-config.yaml
├── .github
    ├── workflows
    │   ├── pypi.yml
    │   └── ci.yml
    └── FUNDING.yml
├── samples
    └── backup-dup.sh
├── pyproject.toml
├── LICENSE
├── README.md
└── .gitignore


/tests/__init__.py:
--------------------------------------------------------------------------------
1 | 


--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | click
2 | crondir
3 | 


--------------------------------------------------------------------------------
/tests/requirements.txt:
--------------------------------------------------------------------------------
1 | -r ../requirements.txt
2 | 
3 | pytest
4 | pytest-cov
5 | time_machine
6 | 


--------------------------------------------------------------------------------
/runchain/__main__.py:
--------------------------------------------------------------------------------
1 | from .commands import invoke
2 | 
3 | if __name__ == "__main__":
4 |     invoke()
5 | 


--------------------------------------------------------------------------------
/runchain/__init__.py:
--------------------------------------------------------------------------------
1 | from __future__ import annotations
2 | 
3 | from runchain.chain import Chain, list_chains
4 | 
5 | __version__ = "0.2.0"
6 | 


--------------------------------------------------------------------------------
/docs/requirements.txt:
--------------------------------------------------------------------------------
1 | -r ../requirements.txt
2 | 
3 | # Core build requirements
4 | sphinx
5 | -e git+https://github.com/radiac/sphinx_radiac_theme.git#egg=sphinx_radiac_theme
6 | 
7 | # Optional
8 | # sphinx-autobuild
9 | 


--------------------------------------------------------------------------------
/docs/environment.rst:
--------------------------------------------------------------------------------
 1 | =====================
 2 | Environment variables
 3 | =====================
 4 | 
 5 | You can set the following environment variables:
 6 | 
 7 | ``RUNCHAIN_PATH=<path>``:
 8 |   Change the default runchain directory from ``~/.runchain/``
 9 | 
10 | This can be set in your ``.bashrc``::
11 | 
12 |     export RUNCHAIN_PATH=~/my_chains/
13 | 


--------------------------------------------------------------------------------
/runchain/exceptions.py:
--------------------------------------------------------------------------------
 1 | from __future__ import annotations
 2 | 
 3 | from click import ClickException
 4 | 
 5 | 
 6 | class RunchainException(ClickException):
 7 |     """Base exception for all runchain errors."""
 8 | 
 9 |     pass
10 | 
11 | 
12 | class ChainError(RunchainException):
13 |     """Exception raised for chain-related errors."""
14 | 
15 |     pass
16 | 


--------------------------------------------------------------------------------
/.readthedocs.yaml:
--------------------------------------------------------------------------------
 1 | # .readthedocs.yaml
 2 | # Read the Docs configuration file
 3 | # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 4 | 
 5 | version: 2
 6 | 
 7 | build:
 8 |   os: ubuntu-22.04
 9 |   tools:
10 |     python: "3.11"
11 | 
12 | sphinx:
13 |    configuration: docs/conf.py
14 | 
15 | python:
16 |    install:
17 |    - requirements: docs/requirements.txt
18 | 


--------------------------------------------------------------------------------
/docs/changelog.rst:
--------------------------------------------------------------------------------
 1 | =========
 2 | Changelog
 3 | =========
 4 | 
 5 | 0.2.0 - 2025-09-05
 6 | ------------------
 7 | 
 8 | Initial release
 9 | 
10 | Features:
11 | 
12 | * Move to `~/.runchain/`
13 | * Rewrite as Python command with `build`, `add`, `remove` and `list`
14 | 
15 | 
16 | 0.1.0 - 2022-12-02
17 | ------------------
18 | 
19 | Initial bash script
20 | 
21 | Features:
22 | 
23 | * Run a chain of scripts from `~/scripts/`
24 | 


--------------------------------------------------------------------------------
/.pre-commit-config.yaml:
--------------------------------------------------------------------------------
 1 | exclude: .*migrations\/.*
 2 | repos:
 3 |   - repo: https://github.com/pre-commit/pre-commit-hooks
 4 |     rev: v5.0.0
 5 |     hooks:
 6 |       - id: check-merge-conflict
 7 |       - id: trailing-whitespace
 8 |   - repo: https://github.com/astral-sh/ruff-pre-commit
 9 |     rev: v0.9.9
10 |     hooks:
11 |       # Run the linter with import sorting
12 |       - id: ruff
13 |         args: ["check", "--select", "I", "--fix"]
14 |       # Run the formatter
15 |       - id: ruff-format
16 | 


--------------------------------------------------------------------------------
/docs/index.rst:
--------------------------------------------------------------------------------
 1 | ========
 2 | runchain
 3 | ========
 4 | 
 5 | Manage and execute chains of scripts.
 6 | 
 7 | Runchain allows you to group scripts into named chains, schedule them with cron, and
 8 | run them in a predictable order. Perfect for backup scripts and maintenance tasks.
 9 | 
10 | - Group scripts into ordered chains
11 | - Schedule chains with crondir integration
12 | - Simple Python API and CLI interface
13 | 
14 | .. toctree::
15 |     :maxdepth: 2
16 |     :caption: Contents:
17 | 
18 |     quickstart
19 |     commands
20 |     environment
21 |     howto-backup
22 |     api
23 |     changelog
24 |     contributing
25 | 


--------------------------------------------------------------------------------
/docs/Makefile:
--------------------------------------------------------------------------------
 1 | # Minimal makefile for Sphinx documentation
 2 | #
 3 | 
 4 | # You can set these variables from the command line, and also
 5 | # from the environment for the first two.
 6 | SPHINXOPTS    ?=
 7 | SPHINXBUILD   ?= sphinx-build
 8 | SOURCEDIR     = .
 9 | BUILDDIR      = _build
10 | 
11 | # Put it first so that "make" without argument is like "make help".
12 | help:
13 | 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14 | 
15 | .PHONY: help Makefile
16 | 
17 | # Catch-all target: route all unknown targets to Sphinx using the new
18 | # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
19 | %: Makefile
20 | 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21 | 


--------------------------------------------------------------------------------
/.github/workflows/pypi.yml:
--------------------------------------------------------------------------------
 1 | name: PyPI
 2 | 
 3 | on:
 4 |    push:
 5 |      tags:
 6 |        - 'v*'
 7 | 
 8 | jobs:
 9 |   publish:
10 |     name: Build and publish to PyPI
11 |     runs-on: ubuntu-latest
12 |     permissions:
13 |       id-token: write
14 |     steps:
15 |     - uses: actions/checkout@v4
16 |     - uses: actions/setup-python@v5
17 |       with:
18 |         python-version: 3.11
19 |     - name: Install dependencies
20 |       run: |
21 |         python -m pip install --upgrade pip
22 |         pip install --upgrade setuptools build wheel
23 |     - name: Build a binary wheel and a source tarball
24 |       run: |
25 |         python -m build
26 |     - name: Publish to PyPI
27 |       if: startsWith(github.ref, 'refs/tags')
28 |       uses: pypa/gh-action-pypi-publish@release/v1
29 | 


--------------------------------------------------------------------------------
/samples/backup-dup.sh:
--------------------------------------------------------------------------------
 1 | #!/bin/bash
 2 | # Back up ~/backup to B2 using duplicity
 3 | set -e
 4 | 
 5 | # Secrets
 6 | B2_KEY_ID="your-key-id"
 7 | B2_APP_KEY="your-application-key"
 8 | B2_BUCKET="your-bucket-name"
 9 | 
10 | # Env
11 | LOCAL_ROOT="~/backup/"
12 | 
13 | # Build bucket URL
14 | B2_URL="b2://$B2_KEY_ID:$B2_APP_KEY@$B2_BUCKET"
15 | 
16 | # Clear out anything older than 90 days
17 | duplicity remove-older-than 90D -v9 --force $B2_URL
18 | 
19 | # Perform the backup
20 | #
21 | # * Take a full backup of files every 30D, incremental in between
22 | # * Resolve synlinks to back up the files themselves
23 | # * To exclude files in ~/backup, add: --exclude  '**/.git'
24 | #
25 | # For more options see https://duplicity.gitlab.io/stable/duplicity.1.html
26 | /usr/bin/duplicity \
27 |     --verbosity 1 \
28 |     --full-if-older-than 30D \
29 |     --copy-links \
30 |     --exclude-device-files \
31 |     $LOCAL_ROOT \
32 |     $B2_URL
33 | 


--------------------------------------------------------------------------------
/docs/make.bat:
--------------------------------------------------------------------------------
 1 | @ECHO OFF
 2 | 
 3 | pushd %~dp0
 4 | 
 5 | REM Command file for Sphinx documentation
 6 | 
 7 | if "%SPHINXBUILD%" == "" (
 8 | 	set SPHINXBUILD=sphinx-build
 9 | )
10 | set SOURCEDIR=.
11 | set BUILDDIR=_build
12 | 
13 | %SPHINXBUILD% >NUL 2>NUL
14 | if errorlevel 9009 (
15 | 	echo.
16 | 	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
17 | 	echo.installed, then set the SPHINXBUILD environment variable to point
18 | 	echo.to the full path of the 'sphinx-build' executable. Alternatively you
19 | 	echo.may add the Sphinx directory to PATH.
20 | 	echo.
21 | 	echo.If you don't have Sphinx installed, grab it from
22 | 	echo.https://www.sphinx-doc.org/
23 | 	exit /b 1
24 | )
25 | 
26 | if "%1" == "" goto help
27 | 
28 | %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29 | goto end
30 | 
31 | :help
32 | %SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33 | 
34 | :end
35 | popd
36 | 


--------------------------------------------------------------------------------
/.github/FUNDING.yml:
--------------------------------------------------------------------------------
 1 | # These are supported funding model platforms
 2 | 
 3 | github: radiac # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
 4 | patreon: # Replace with a single Patreon username
 5 | open_collective: # Replace with a single Open Collective username
 6 | ko_fi: # Replace with a single Ko-fi username
 7 | tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
 8 | community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
 9 | liberapay: # Replace with a single Liberapay username
10 | issuehunt: # Replace with a single IssueHunt username
11 | lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
12 | polar: # Replace with a single Polar username
13 | buy_me_a_coffee: # Replace with a single Buy Me a Coffee username
14 | thanks_dev: # Replace with a single thanks.dev username
15 | custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
16 | 


--------------------------------------------------------------------------------
/.github/workflows/ci.yml:
--------------------------------------------------------------------------------
 1 | name: Tests
 2 | 
 3 | on:
 4 |   push:
 5 |   pull_request:
 6 | 
 7 | jobs:
 8 |   test:
 9 |     name: py-${{ matrix.python }}
10 |     runs-on: ubuntu-latest
11 |     strategy:
12 |       matrix:
13 |         include:
14 |           - python: "3.11"
15 | 
16 |     steps:
17 |       - uses: actions/checkout@v4
18 |       - name: Set up Python ${{ matrix.python }}
19 |         uses: actions/setup-python@v5
20 |         with:
21 |           python-version: ${{ matrix.python }}
22 |       - name: Install dependencies
23 |         run: |
24 |           python -m pip install --upgrade pip
25 |           pip install -r tests/requirements.txt
26 |       - name: Set Python path
27 |         run: |
28 |             echo "PYTHONPATH=." >> $GITHUB_ENV
29 |       - name: Test
30 |         run: |
31 |           pytest
32 |       - name: Upload coverage to Codecov
33 |         uses: codecov/codecov-action@v4
34 |         with:
35 |           name: ${{ matrix.python }}
36 |         env:
37 |           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
38 | 


--------------------------------------------------------------------------------
/docs/contributing.rst:
--------------------------------------------------------------------------------
 1 | ============
 2 | Contributing
 3 | ============
 4 | 
 5 | Contributions are welcome, preferably via pull request. Check the GitHub issues to see
 6 | what needs work, or if you have an idea for a new feature it may be worth raising an
 7 | issue to discuss it first.
 8 | 
 9 | 
10 | Installing
11 | ==========
12 | 
13 | The easiest way to work on this is to fork the project on GitHub, then check it out and
14 | set it up::
15 | 
16 |     git clone git@github.com:USERNAME/runchain.git
17 |     cd runchain/
18 |     uv venv .venv
19 |     source .venv/bin/activate
20 |     uv pip install -r tests/requirements.txt
21 |     pre-commit install
22 | 
23 | (replacing ``USERNAME`` with your username).
24 | 
25 | This will install the development dependencies too.
26 | 
27 | 
28 | Running locally
29 | ===============
30 | 
31 | You can now run the local installation from your repository root with::
32 | 
33 |     python -m runchain <cmd> [<options>]
34 | 
35 | 
36 | Testing
37 | =======
38 | 
39 | It's always easier to merge PRs when they come with tests.
40 | 
41 | Run the tests with pytest from your repository root::
42 | 
43 |     pytest
44 | 


--------------------------------------------------------------------------------
/docs/api.rst:
--------------------------------------------------------------------------------
 1 | ===
 2 | API
 3 | ===
 4 | 
 5 | You can use runchain from your Python code
 6 | 
 7 | .. code-block:: python
 8 | 
 9 |     from runchain import Chain, list_chains
10 | 
11 |     # List all chains
12 |     chains = list_chains()
13 |     print("Available chains:", chains)
14 | 
15 |     # Work with a specific chain
16 |     backup_chain = Chain("backup")
17 |     
18 |     if backup_chain.exists():
19 |         print("Scripts in backup chain:", backup_chain.list())
20 |     
21 |     # Add a script file
22 |     backup_chain.add_file("~/scripts/database.sh", "10")
23 |     backup_chain.add_file("~/scripts/files.py", "20-backup-files")
24 |     
25 |     # Add a script from string content
26 |     backup_chain.add_string(
27 |         "#!/bin/bash",
28 |         "echo 'Hello from string script'",
29 |         target="30-hello"
30 |     )
31 |     
32 |     # Schedule the chain
33 |     backup_chain.cron("0 2 * * *")
34 |     
35 |     # Run the chain
36 |     success = backup_chain.run()
37 |     if success:
38 |         print("Backup completed successfully")
39 |     
40 |     # Remove a script
41 |     backup_chain.remove("10-database.sh")
42 |     
43 |     # Remove entire chain
44 |     backup_chain.destroy()
45 | 
46 | 
47 | API reference
48 | =============
49 | 
50 | .. autoclass:: runchain.chain.Chain
51 | 	:members:
52 | 	:show-inheritance:
53 | 
54 | .. autofunction:: runchain.chain.list_chains
55 | 


--------------------------------------------------------------------------------
/tests/test_commands__cron.py:
--------------------------------------------------------------------------------
 1 | from __future__ import annotations
 2 | 
 3 | from runchain.commands import cli
 4 | 
 5 | 
 6 | def test_cron_success(mock_crondir, runner, home_dir, test_script):
 7 |     """
 8 |     Test scheduling a chain with cron.
 9 |     """
10 |     # Add a script to create the chain
11 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
12 |     
13 |     result = runner.invoke(cli, ["cron", "testchain", "0 2 * * *"])
14 |     assert result.exit_code == 0
15 |     assert "Scheduled chain 'testchain' with crondir" in result.output
16 |     
17 |     # Check crondir was called correctly
18 |     mock_crondir.add_string.assert_called_once_with(
19 |         "0 2 * * * runchain run testchain",
20 |         snippet="runchain-testchain",
21 |         force=True
22 |     )
23 | 
24 | 
25 | def test_cron_nonexistent_chain(runner, home_dir):
26 |     """
27 |     Test scheduling a nonexistent chain.
28 |     """
29 |     result = runner.invoke(cli, ["cron", "nonexistent", "0 2 * * *"])
30 |     assert result.exit_code != 0
31 |     assert "does not exist" in result.output
32 | 
33 | 
34 | def test_cron_invalid_chain_name(runner, home_dir):
35 |     """
36 |     Test scheduling with invalid chain name.
37 |     """
38 |     result = runner.invoke(cli, ["cron", "invalid-name", "0 2 * * *"])
39 |     assert result.exit_code != 0
40 |     assert "must contain only lowercase letters" in result.output


--------------------------------------------------------------------------------
/pyproject.toml:
--------------------------------------------------------------------------------
 1 | [build-system]
 2 | requires = ["setuptools", "wheel"]
 3 | build-backend = "setuptools.build_meta"
 4 | 
 5 | [project]
 6 | name = "runchain"
 7 | description = "A tool for running command chains"
 8 | dynamic = ["version"]
 9 | authors = [
10 |     { name="Richard Terry", email="code@radiac.net" },
11 | ]
12 | license = "BSD-3-Clause"
13 | readme = "README.md"
14 | classifiers = [
15 |     "Development Status :: 4 - Beta",
16 |     "Programming Language :: Python :: 3",
17 |     "Operating System :: OS Independent",
18 | ]
19 | requires-python = ">=3.9"
20 | dependencies = ["click", "crondir"]
21 | 
22 | [project.scripts]
23 | runchain = "runchain.commands:invoke"
24 | 
25 | [project.urls]
26 | Homepage = "https://radiac.net/projects/runchain/"
27 | Documentation = "https://github.com/radiac/runchain"
28 | Changelog = "https://runchain.readthedocs.io/en/latest/changelog.html"
29 | Repository = "https://github.com/radiac/runchain"
30 | Issues = "https://github.com/radiac/runchain/issues"
31 | 
32 | [tool.setuptools]
33 | packages = ["runchain"]
34 | 
35 | [tool.setuptools.dynamic]
36 | version = {attr = "runchain.__version__"}
37 | 
38 | [tool.pytest.ini_options]
39 | addopts = "--cov=runchain --cov-report=term --cov-report=html"
40 | testpaths = [
41 |     "runchain",
42 |     "tests",
43 | ]
44 | pythonpath = ["."]
45 | 
46 | [tool.coverage.run]
47 | source = ["runchain"]
48 | 
49 | [tool.ruff]
50 | line-length = 88
51 | lint.select = ["E", "F"]
52 | lint.ignore = [
53 |     "E501",  # line length
54 | ]
55 | exclude = [
56 |     ".git",
57 |     "dist",
58 | ]
59 | 


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | BSD 3-Clause License
 2 | 
 3 | Copyright (c) 2025, Richard Terry
 4 | 
 5 | Redistribution and use in source and binary forms, with or without
 6 | modification, are permitted provided that the following conditions are met:
 7 | 
 8 | 1. Redistributions of source code must retain the above copyright notice, this
 9 |    list of conditions and the following disclaimer.
10 | 
11 | 2. Redistributions in binary form must reproduce the above copyright notice,
12 |    this list of conditions and the following disclaimer in the documentation
13 |    and/or other materials provided with the distribution.
14 | 
15 | 3. Neither the name of the copyright holder nor the names of its
16 |    contributors may be used to endorse or promote products derived from
17 |    this software without specific prior written permission.
18 | 
19 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
20 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
22 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
23 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
25 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
26 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
27 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
28 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
29 | 


--------------------------------------------------------------------------------
/docs/quickstart.rst:
--------------------------------------------------------------------------------
 1 | ==========
 2 | Quickstart
 3 | ==========
 4 | 
 5 | Installation
 6 | ------------
 7 | 
 8 | Install using ``pip``::
 9 | 
10 |     pip install runchain
11 | 
12 | or run directly using `uv <https://docs.astral.sh/uv/>`_ (recommended)::
13 | 
14 |     uvx runchain <command> [<options>]
15 | 
16 | 
17 | Basic usage
18 | -----------
19 | 
20 | Create a backup chain by adding scripts::
21 | 
22 |   runchain add backup ~/scripts/database-backup.sh 10
23 |   runchain add backup /usr/local/bin/file-backup.py 20-files
24 |   runchain add backup ./30-cleanup.sh
25 | 
26 | List your chains::
27 | 
28 |   runchain list
29 | 
30 | List scripts in a specific chain::
31 | 
32 |   runchain list backup
33 | 
34 | Run a chain manually::
35 | 
36 |   runchain run backup
37 | 
38 | Schedule a chain with crondir::
39 | 
40 |   runchain cron backup "0 2 * * *"
41 | 
42 | Remove a script from a chain::
43 | 
44 |   runchain remove backup 20-files
45 | 
46 | Remove an entire chain::
47 | 
48 |   runchain remove backup
49 | 
50 | 
51 | Scripts and naming
52 | ------------------
53 | 
54 | Scripts in chains use init-style numbering (e.g., ``10-backup.sh``, ``20-cleanup.py``)
55 | and are executed in alphabetical order. You can:
56 | 
57 | - specify the number to control the order: ``runchain add mychain script.sh 25`` → ``25-script.sh``
58 | - add with a number and custom name: ``runchain add mychain script.sh 25-backup`` → ``25-backup``
59 | - add scripts that already have numbers: ``runchain add mychain 30-deploy.sh``
60 | 
61 | Chain names must contain only lowercase letters (a-z).
62 | 
63 | For full command line options, see :doc:`commands`.
64 | 


--------------------------------------------------------------------------------
/tests/conftest.py:
--------------------------------------------------------------------------------
 1 | from __future__ import annotations
 2 | 
 3 | from unittest.mock import Mock
 4 | 
 5 | import pytest
 6 | from click.testing import CliRunner
 7 | 
 8 | from runchain.commands import cli
 9 | 
10 | 
11 | @pytest.fixture
12 | def runner():
13 |     """
14 |     Click test runner.
15 |     """
16 |     return CliRunner()
17 | 
18 | 
19 | @pytest.fixture
20 | def home_dir(tmp_path, monkeypatch):
21 |     """
22 |     Set HOME to a temporary directory.
23 |     """
24 |     monkeypatch.setenv("HOME", str(tmp_path))
25 |     return tmp_path
26 | 
27 | 
28 | @pytest.fixture
29 | def mock_subprocess(monkeypatch):
30 |     """
31 |     Mock subprocess.run for testing script execution.
32 |     """
33 |     mock = Mock()
34 |     mock.return_value.returncode = 0
35 |     monkeypatch.setattr("subprocess.run", mock)
36 |     return mock
37 | 
38 | 
39 | @pytest.fixture
40 | def mock_crondir(monkeypatch):
41 |     """
42 |     Mock crondir.Crondir for testing cron scheduling.
43 |     """
44 |     mock_class = Mock()
45 |     mock_instance = Mock()
46 |     mock_class.return_value = mock_instance
47 |     monkeypatch.setattr("runchain.chain.Crondir", mock_class)
48 |     return mock_instance
49 | 
50 | 
51 | @pytest.fixture
52 | def test_script(tmp_path):
53 |     """
54 |     Create a test script file.
55 |     """
56 |     script_path = tmp_path / "test_script.sh"
57 |     script_path.write_text("#!/bin/bash\necho 'Hello from test script'\n")
58 |     return script_path
59 | 
60 | 
61 | @pytest.fixture
62 | def numbered_script(tmp_path):
63 |     """
64 |     Create a test script with NN- prefix.
65 |     """
66 |     script_path = tmp_path / "10-numbered.py"
67 |     script_path.write_text("#!/usr/bin/env python3\nprint('Hello from numbered script')\n")
68 |     return script_path
69 | 
70 | 
71 | @pytest.fixture
72 | def failing_script(tmp_path):
73 |     """
74 |     Create a test script that fails.
75 |     """
76 |     script_path = tmp_path / "fail_script.sh"
77 |     script_path.write_text("#!/bin/bash\necho 'This will fail'\nexit 1\n")
78 |     return script_path


--------------------------------------------------------------------------------
/docs/conf.py:
--------------------------------------------------------------------------------
 1 | # Configuration file for the Sphinx documentation builder.
 2 | #
 3 | # For the full list of built-in configuration values, see the documentation:
 4 | # https://www.sphinx-doc.org/en/master/usage/configuration.html
 5 | 
 6 | # -- Project information -----------------------------------------------------
 7 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 8 | 
 9 | import re
10 | import sys
11 | from pathlib import Path
12 | 
13 | # Add the project root to Python path for autodoc
14 | sys.path.insert(0, str(Path(__file__).parent.parent))
15 | 
16 | project = "runchain"
17 | copyright = "2025, Richard Terry"
18 | author = "Richard Terry"
19 | 
20 | 
21 | def find_version(*paths):
22 |     path = Path(*paths)
23 |     content = path.read_text()
24 |     match = re.search(r"^__version__\s*=\s*['\"]([^'\"]*)['\"]", content, re.M)
25 |     if match:
26 |         return match.group(1)
27 |     raise RuntimeError("Unable to find version string.")
28 | 
29 | 
30 | release = find_version("..", project.replace("-", "_"), "__init__.py")
31 | 
32 | 
33 | # -- General configuration ---------------------------------------------------
34 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
35 | 
36 | extensions = [
37 |     "sphinx_radiac_theme",
38 |     "sphinx.ext.autodoc",
39 |     "sphinx.ext.autosummary",
40 |     "sphinx.ext.napoleon",
41 | ]
42 | templates_path = ["_templates"]
43 | exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
44 | 
45 | 
46 | # -- Options for HTML output -------------------------------------------------
47 | # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
48 | 
49 | html_theme = "sphinx_radiac_theme"
50 | 
51 | html_static_path = ["_static"]
52 | 
53 | html_theme_options = {
54 |     "logo_only": False,
55 |     "display_version": True,
56 |     # Toc options
57 |     "collapse_navigation": True,
58 |     "sticky_navigation": True,
59 |     "navigation_depth": 4,
60 |     "includehidden": True,
61 |     "titles_only": False,
62 |     # radiac.net theme
63 |     "radiac_project_slug": project,
64 |     "radiac_project_name": project,
65 |     "radiac_subsite_links": [
66 |         # (f"https://radiac.net/projects/{project}/demo/", "Demo"),
67 |     ],
68 | }
69 | 


--------------------------------------------------------------------------------
/docs/howto-backup.rst:
--------------------------------------------------------------------------------
 1 | ============================
 2 | How to create a backup chain
 3 | ============================
 4 | 
 5 | Let's create a simple backup chain.
 6 | 
 7 | We're going to use `duplicity <https://duplicity.us/>`_ to upload everything in
 8 | ``~/backup/`` to `Backblaze B2 storage <https://www.backblaze.com/cloud-storage>`_ - a
 9 | cost-effective solution which will be encrypted at rest, with 90-day rolling history.
10 | 
11 | 
12 | Set up duplicity and B2
13 | -----------------------
14 | 
15 | Backblaze have a great `tutorial
16 | <https://www.backblaze.com/docs/cloud-storage-configure-backblaze-b2-with-duplicity-on-linux>`_
17 | for setting up a B2 bucket and installing duplicity. The short version::
18 | 
19 |     sudo add-apt-repository ppa:duplicity-team/ppa
20 |     sudo apt-get update
21 |     sudo apt-get --only-upgrade install duplicity
22 | 
23 | Now lets create our local backup directory::
24 | 
25 |     mkdir -p ~/backup
26 | 
27 | The duplicity commands to backup everything in ``~/backup/`` to B2 with a 90 day history
28 | will be::
29 | 
30 |     B2_URL="b2://[keyID]:[application key]@[B2 bucket name]"
31 |     duplicity remove-older-than 90D -v9 --force $B2_URL
32 |     duplicity --full-if-older-than 30D --copy-links ~/backup/ $B2_URL
33 | 
34 | You can download a fleshed out version of this from the runchain repo. Customise it then
35 | install it as ``90-dup.sh``, so it will run at the end of the backup chain::
36 | 
37 |     wget https://raw.githubusercontent.com/radiac/runchain/refs/heads/main/samples/backup-dup.sh
38 |     # Update the secrets in backup-dup.sh
39 |     runchain add backup backup-dup.sh 90-dup.sh
40 | 
41 | We can test the backup with::
42 | 
43 |     runchain run backup
44 | 
45 | Lastly, let's schedule the chain to run at 2am every day::
46 | 
47 |     runchain cron backup "0 2 * * *"
48 | 
49 | Now everything in your ``~/backup`` directory will be backed up to B2 at 2am.
50 | 
51 | 
52 | Back up a file or directory
53 | ---------------------------
54 | 
55 | Because we have ``--copy-links``, to back up a file or a directory, you can just symlink
56 | it in::
57 | 
58 |     ln -s ~/uploads ~/backup/uploads
59 | 
60 | 
61 | Back up something more complicated
62 | ----------------------------------
63 | 
64 | Let's see how we'd back up a PostgreSQL database running in a container.
65 | 
66 | Lets create ``dump-postgres.sh``::
67 | 
68 |     #!/bin/bash
69 |     set -e
70 |     docker exec postgres-container pg_dumpall > ~/backup/postgres_dump.sql
71 | 
72 | Now just add it to the ``backup`` chain before 90-dup.sh::
73 | 
74 |     runchain add backup dump-postgres.sh 50
75 | 


--------------------------------------------------------------------------------
/tests/test_commands__list.py:
--------------------------------------------------------------------------------
 1 | from __future__ import annotations
 2 | 
 3 | from runchain.commands import cli
 4 | 
 5 | 
 6 | def test_list_no_chains(runner, home_dir):
 7 |     """
 8 |     Test listing when no chains exist.
 9 |     """
10 |     result = runner.invoke(cli, ["list"])
11 |     assert result.exit_code == 0
12 |     assert "No chains found." in result.output
13 | 
14 | 
15 | def test_list_all_chains(runner, home_dir):
16 |     """
17 |     Test listing all chains.
18 |     """
19 |     # Create some chain directories
20 |     runchain_dir = home_dir / ".runchain"
21 |     runchain_dir.mkdir()
22 |     (runchain_dir / "backup").mkdir()
23 |     (runchain_dir / "deploy").mkdir()
24 |     (runchain_dir / "maintenance").mkdir()
25 | 
26 |     result = runner.invoke(cli, ["list"])
27 |     assert result.exit_code == 0
28 |     assert "Chains found:" in result.output
29 |     assert "backup" in result.output
30 |     assert "deploy" in result.output
31 |     assert "maintenance" in result.output
32 | 
33 | 
34 | def test_list_chain_scripts_empty(runner, home_dir):
35 |     """
36 |     Test listing scripts in an empty chain.
37 |     """
38 |     runchain_dir = home_dir / ".runchain"
39 |     runchain_dir.mkdir()
40 |     (runchain_dir / "testchain").mkdir()
41 | 
42 |     result = runner.invoke(cli, ["list", "testchain"])
43 |     assert result.exit_code == 0
44 |     assert "No scripts found in chain 'testchain'." in result.output
45 | 
46 | 
47 | def test_list_chain_scripts_with_files(runner, home_dir):
48 |     """
49 |     Test listing scripts in a chain with files.
50 |     """
51 |     runchain_dir = home_dir / ".runchain"
52 |     runchain_dir.mkdir()
53 |     chain_dir = runchain_dir / "testchain"
54 |     chain_dir.mkdir()
55 |     
56 |     # Create some test scripts
57 |     script1 = chain_dir / "10-backup.sh"
58 |     script1.write_text("#!/bin/bash\necho test")
59 |     script1.chmod(0o755)
60 |     
61 |     script2 = chain_dir / "20-deploy.py"
62 |     script2.write_text("#!/usr/bin/env python3\nprint('test')")
63 |     # Don't make this one executable
64 | 
65 |     result = runner.invoke(cli, ["list", "testchain"])
66 |     assert result.exit_code == 0
67 |     assert "Scripts in chain testchain:" in result.output
68 |     assert "10-backup.sh (executable)" in result.output
69 |     assert "20-deploy.py (not executable)" in result.output
70 | 
71 | 
72 | def test_list_invalid_chain_name(runner, home_dir):
73 |     """
74 |     Test listing with invalid chain name.
75 |     """
76 |     result = runner.invoke(cli, ["list", "invalid-name"])
77 |     assert result.exit_code != 0
78 |     assert "must contain only lowercase letters" in result.output


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # runchain
 2 | 
 3 | [![PyPI](https://img.shields.io/pypi/v/runchain.svg)](https://pypi.org/project/runchain/)
 4 | [![Documentation](https://readthedocs.org/projects/runchain/badge/?version=latest)](https://runchain.readthedocs.io/en/latest/)
 5 | [![Tests](https://github.com/radiac/runchain/actions/workflows/ci.yml/badge.svg)](https://github.com/radiac/runchain/actions/workflows/ci.yml)
 6 | [![Coverage](https://codecov.io/gh/radiac/runchain/branch/main/graph/badge.svg?token=BCNM45T6GI)](https://codecov.io/gh/radiac/runchain)
 7 | 
 8 | Manage and execute chains of scripts.
 9 | 
10 | Runchain allows you to group scripts into named chains, schedule them with cron, and
11 | run them in a predictable order. Perfect for backup scripts and maintenance tasks.
12 | 
13 | - Group scripts into ordered chains
14 | - Schedule chains with crondir integration
15 | - Simple Python API and CLI interface
16 | 
17 | ## Usage
18 | 
19 | Install runchain:
20 | 
21 | ```bash
22 | pip install runchain
23 | ```
24 | 
25 | Create a backup chain by adding scripts:
26 | 
27 | ```bash
28 | runchain add backup ~/scripts/database-backup.sh 10
29 | runchain add backup /usr/local/bin/file-backup.py 20-files
30 | runchain add backup ./30-cleanup.sh
31 | ```
32 | 
33 | List your chains:
34 | 
35 | ```bash
36 | runchain list
37 | ```
38 | 
39 | List scripts in a specific chain:
40 | 
41 | ```bash
42 | runchain list backup
43 | ```
44 | 
45 | Run a chain manually:
46 | 
47 | ```bash
48 | runchain run backup
49 | ```
50 | 
51 | Schedule a chain with crondir:
52 | 
53 | ```bash
54 | runchain cron backup "0 2 * * *"
55 | ```
56 | 
57 | Remove a script or entire chain:
58 | 
59 | ```bash
60 | runchain remove backup 20-files
61 | runchain remove backup
62 | ```
63 | 
64 | Or you may find it easier to skip the install step and run it using [uv](https://docs.astral.sh/uv/):
65 | 
66 | ```bash
67 | uvx runchain add backup ~/scripts/backup.sh 10
68 | uvx runchain cron backup "0 2 * * *"
69 | uvx runchain run backup
70 | ```
71 | 
72 | By default, runchain stores chains in `~/.runchain/`, with each chain in its own subdirectory.
73 | 
74 | For full command line options, see [command documentation](https://runchain.readthedocs.io/en/latest/commands.html)
75 | 
76 | ## Example
77 | 
78 | For an example of setting up a backup chain, see
79 | [How to create a backup chain](https://runchain.readthedocs.io/en/latest/howto-backup.html)
80 | in the documentation.
81 | 
82 | ## Python API
83 | 
84 | ```python
85 | from runchain import Chain, list_chains
86 | 
87 | # List all chains
88 | chains = list_chains()
89 | 
90 | # Work with a specific chain
91 | backup = Chain("backup")
92 | backup.add("~/scripts/database.sh", "10")
93 | backup.cron("0 2 * * *")
94 | backup.run()
95 | ```
96 | 
97 | See the [API documentation](https://runchain.readthedocs.io/en/latest/api.html) for more details.
98 | 


--------------------------------------------------------------------------------
/tests/test_commands__add.py:
--------------------------------------------------------------------------------
 1 | from __future__ import annotations
 2 | 
 3 | import os
 4 | 
 5 | from runchain.commands import cli
 6 | 
 7 | 
 8 | def test_add_with_number(runner, home_dir, test_script):
 9 |     """
10 |     Test adding a script with a number.
11 |     """
12 |     result = runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
13 |     assert result.exit_code == 0
14 |     assert "Added 10-test_script.sh to chain 'testchain'" in result.output
15 |     
16 |     # Check file was created and is executable
17 |     chain_dir = home_dir / ".runchain" / "testchain"
18 |     target_file = chain_dir / "10-test_script.sh"
19 |     assert target_file.exists()
20 |     assert os.access(target_file, os.X_OK)
21 | 
22 | 
23 | def test_add_with_full_name(runner, home_dir, test_script):
24 |     """
25 |     Test adding a script with full NN-name format.
26 |     """
27 |     result = runner.invoke(cli, ["add", "testchain", str(test_script), "20-backup"])
28 |     assert result.exit_code == 0
29 |     assert "Added 20-backup to chain 'testchain'" in result.output
30 |     
31 |     chain_dir = home_dir / ".runchain" / "testchain"
32 |     target_file = chain_dir / "20-backup"
33 |     assert target_file.exists()
34 |     assert os.access(target_file, os.X_OK)
35 | 
36 | 
37 | def test_add_numbered_script_no_target(runner, home_dir, numbered_script):
38 |     """
39 |     Test adding a script that already has NN- format without target.
40 |     """
41 |     result = runner.invoke(cli, ["add", "testchain", str(numbered_script)])
42 |     assert result.exit_code == 0
43 |     assert "Added 10-numbered.py to chain 'testchain'" in result.output
44 | 
45 | 
46 | def test_add_script_no_target_invalid(runner, home_dir, test_script):
47 |     """
48 |     Test adding a script without NN- format and no target fails.
49 |     """
50 |     result = runner.invoke(cli, ["add", "testchain", str(test_script)])
51 |     assert result.exit_code != 0
52 |     assert "must start with NN- format when no target specified" in result.output
53 | 
54 | 
55 | def test_add_nonexistent_script(runner, home_dir):
56 |     """
57 |     Test adding a script that doesn't exist.
58 |     """
59 |     result = runner.invoke(cli, ["add", "testchain", "/nonexistent/script.sh", "10"])
60 |     assert result.exit_code != 0
61 |     assert "does not exist" in result.output
62 | 
63 | 
64 | def test_add_invalid_target(runner, home_dir, test_script):
65 |     """
66 |     Test adding with invalid target format.
67 |     """
68 |     result = runner.invoke(cli, ["add", "testchain", str(test_script), "invalid"])
69 |     assert result.exit_code != 0
70 |     assert "must be a number or start with NN- format" in result.output
71 | 
72 | 
73 | def test_add_creates_chain(runner, home_dir, test_script):
74 |     """
75 |     Test that adding a script creates the chain directory.
76 |     """
77 |     chain_dir = home_dir / ".runchain" / "newchain"
78 |     assert not chain_dir.exists()
79 |     
80 |     result = runner.invoke(cli, ["add", "newchain", str(test_script), "10"])
81 |     assert result.exit_code == 0
82 |     assert chain_dir.exists()
83 | 
84 | 
85 | def test_add_invalid_chain_name(runner, home_dir, test_script):
86 |     """
87 |     Test adding with invalid chain name.
88 |     """
89 |     result = runner.invoke(cli, ["add", "invalid-name", str(test_script), "10"])
90 |     assert result.exit_code != 0
91 |     assert "must contain only lowercase letters" in result.output


--------------------------------------------------------------------------------
/runchain/commands.py:
--------------------------------------------------------------------------------
  1 | from __future__ import annotations
  2 | 
  3 | import click
  4 | 
  5 | from runchain.chain import Chain, list_chains
  6 | 
  7 | 
  8 | class ChainType(click.ParamType):
  9 |     """
 10 |     Click parameter type for Chain objects.
 11 |     """
 12 |     name = "chain"
 13 |     
 14 |     def __init__(self, required: bool = True):
 15 |         self.required = required
 16 |     
 17 |     def convert(self, value, param, ctx):
 18 |         if value is None:
 19 |             if self.required:
 20 |                 self.fail("Chain name is required", param, ctx)
 21 |             return None
 22 |         return Chain(value)
 23 | 
 24 | 
 25 | @click.group()
 26 | @click.version_option()
 27 | def cli() -> None:
 28 |     """
 29 |     runchain: manage and run chains of scripts
 30 |     """
 31 |     pass
 32 | 
 33 | 
 34 | @cli.command()
 35 | @click.argument("chain", type=ChainType(required=False), required=False)
 36 | def list(chain: Chain | None) -> None:
 37 |     """
 38 |     List all chains or scripts within a specific chain.
 39 |     """
 40 |     if chain is None:
 41 |         chains = list_chains()
 42 |         if not chains:
 43 |             click.echo("No chains found.")
 44 |             return
 45 |         click.echo("Chains found:")
 46 |         for c in chains:
 47 |             click.echo(c)
 48 |     else:
 49 |         scripts = chain.list()
 50 |         if not scripts:
 51 |             click.echo(f"No scripts found in chain '{chain.name}'.")
 52 |             return
 53 |         click.echo(f"Scripts in chain {chain.name}:")
 54 |         for script in scripts:
 55 |             click.echo(script)
 56 | 
 57 | 
 58 | @cli.command()
 59 | @click.argument("chain", type=ChainType())
 60 | @click.argument("script")
 61 | @click.argument("target", required=False)
 62 | def add(chain: Chain, script: str, target: str | None) -> None:
 63 |     """
 64 |     Add a script to a chain.
 65 |     """
 66 |     filename = chain.add_file(script, target)
 67 |     click.echo(f"Added {filename} to chain '{chain.name}'")
 68 | 
 69 | 
 70 | @cli.command()
 71 | @click.argument("chain", type=ChainType())
 72 | @click.argument("script", required=False)
 73 | @click.argument("target", required=False)
 74 | @click.option("--force", is_flag=True, help="Skip confirmation prompts")
 75 | def remove(chain: Chain, script: str | None, target: str | None, force: bool) -> None:
 76 |     """
 77 |     Remove a script from a chain, or remove an entire chain.
 78 |     """
 79 |     if script is None:
 80 |         # Remove entire chain
 81 |         if not force and chain.exists():
 82 |             scripts = chain.list()
 83 |             if scripts and not click.confirm(f"Chain '{chain.name}' contains {len(scripts)} script(s). Remove anyway?"):
 84 |                 return
 85 |         
 86 |         chain.destroy()
 87 |         click.echo(f"Removed chain '{chain.name}'")
 88 |     else:
 89 |         # Remove script from chain
 90 |         chain.remove(script, target)
 91 |         click.echo(f"Removed script from chain '{chain.name}'")
 92 | 
 93 | 
 94 | @cli.command()
 95 | @click.argument("chain", type=ChainType())
 96 | @click.argument("schedule")
 97 | def cron(chain: Chain, schedule: str) -> None:
 98 |     """
 99 |     Register a chain to run on a cron schedule using crondir.
100 |     """
101 |     chain.cron(schedule)
102 |     click.echo(f"Scheduled chain '{chain.name}' with crondir")
103 | 
104 | 
105 | @cli.command()
106 | @click.argument("chain", type=ChainType())
107 | def run(chain: Chain) -> None:
108 |     """
109 |     Execute all scripts in a chain in alphabetical order.
110 |     """
111 |     success = chain.run()
112 |     if not success:
113 |         raise click.Abort()
114 | 
115 | 
116 | def invoke() -> None:
117 |     """
118 |     Entry point for the CLI.
119 |     """
120 |     cli()
121 | 


--------------------------------------------------------------------------------
/docs/commands.rst:
--------------------------------------------------------------------------------
  1 | ========
  2 | Commands
  3 | ========
  4 | 
  5 | If using `uv <https://docs.astral.sh/uv/>`_, add ``uvx`` to the start of the following
  6 | commands.
  7 | 
  8 | The ``runchain`` command supports the following operations:
  9 | 
 10 | 
 11 | ``runchain list``
 12 | =================
 13 | 
 14 | List all chains or scripts within a specific chain::
 15 | 
 16 |     runchain list [<chain>]
 17 | 
 18 | Without a chain argument, lists all available chains.
 19 | With a chain argument, lists all scripts in that chain in alphabetical order.
 20 | 
 21 | Examples
 22 | --------
 23 | 
 24 | List all chains::
 25 | 
 26 |     runchain list
 27 | 
 28 | List scripts in the backup chain::
 29 | 
 30 |     runchain list backup
 31 | 
 32 | 
 33 | ``runchain add``
 34 | ================
 35 | 
 36 | Add a script to a chain::
 37 | 
 38 |     runchain add <chain> <script> [<target>]
 39 | 
 40 | where:
 41 | 
 42 | * ``<chain>`` - the name of the chain (creates directory if it doesn't exist)
 43 | * ``<script>`` - path to the script file to add  
 44 | * ``<target>`` - optional naming specification:
 45 |   
 46 |   * Number (e.g., ``20``) - script will be named ``20-<basename>``
 47 |   * Full name starting with ``NN-`` (e.g., ``20-backup``) - uses exact name
 48 |   * If omitted - script basename must already follow ``NN-*`` format
 49 | 
 50 | Chain names must contain only lowercase letters (a-z).
 51 | 
 52 | Examples
 53 | --------
 54 | 
 55 | Add script with number target::
 56 | 
 57 |     runchain add backup ~/scripts/database.sh 10
 58 |     # Creates: 10-database.sh
 59 | 
 60 | Add script with full name target::
 61 | 
 62 |     runchain add backup ~/scripts/files.py 20-backup-files
 63 |     # Creates: 20-backup-files
 64 | 
 65 | Add script that already has correct format::
 66 | 
 67 |     runchain add backup ./30-cleanup.sh
 68 |     # Creates: 30-cleanup.sh
 69 | 
 70 | 
 71 | ``runchain remove``
 72 | ===================
 73 | 
 74 | Remove a script from a chain, or remove an entire chain::
 75 | 
 76 |     runchain remove <chain> [<script>] [<target>] [--force]
 77 | 
 78 | where:
 79 | 
 80 | * ``<chain>`` - name of the chain
 81 | * ``<script>`` - optional script filename in the chain
 82 | * ``<target>`` - optional full filename to remove
 83 | * ``--force`` - skip confirmation prompts when removing entire chains
 84 | 
 85 | If only ``<chain>`` is provided, removes the entire chain.
 86 | If ``<script>`` is provided, removes that specific script.
 87 | 
 88 | Examples
 89 | --------
 90 | 
 91 | Remove a specific script::
 92 | 
 93 |     runchain remove backup 10-database.sh
 94 | 
 95 | Remove entire chain with confirmation::
 96 | 
 97 |     runchain remove backup
 98 | 
 99 | Remove entire chain without confirmation::
100 | 
101 |     runchain remove backup --force
102 | 
103 | 
104 | ``runchain cron``
105 | =================
106 | 
107 | Register a chain to run on a cron schedule using crondir::
108 | 
109 |     runchain cron <chain> "<schedule>"
110 | 
111 | where:
112 | 
113 | * ``<chain>`` - name of the chain to schedule
114 | * ``<schedule>`` - cron schedule string (e.g., ``"0 2 * * *"`` for daily at 2am)
115 | 
116 | This integrates with crondir to manage the cron entries.
117 | 
118 | Examples
119 | --------
120 | 
121 | Schedule backup chain to run daily at 2am::
122 | 
123 |     runchain cron backup "0 2 * * *"
124 | 
125 | Schedule maintenance chain to run weekly on Sundays at 3am::
126 | 
127 |     runchain cron maintenance "0 3 * * 0"
128 | 
129 | 
130 | ``runchain run``
131 | ================
132 | 
133 | Execute all scripts in a chain in alphabetical order::
134 | 
135 |     runchain run <chain>
136 | 
137 | Scripts are executed in alphabetical order by filename.
138 | Execution stops on the first script failure (non-zero exit code).
139 | 
140 | Examples
141 | --------
142 | 
143 | Run the backup chain manually::
144 | 
145 |     runchain run backup
146 | 
147 | Run a maintenance chain::
148 | 
149 |     runchain run maintenance


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
  1 | # Byte-compiled / optimized / DLL files
  2 | __pycache__/
  3 | *.py[cod]
  4 | *$py.class
  5 | 
  6 | # C extensions
  7 | *.so
  8 | 
  9 | # Distribution / packaging
 10 | .Python
 11 | build/
 12 | develop-eggs/
 13 | dist/
 14 | downloads/
 15 | eggs/
 16 | .eggs/
 17 | lib/
 18 | lib64/
 19 | parts/
 20 | sdist/
 21 | var/
 22 | wheels/
 23 | share/python-wheels/
 24 | *.egg-info/
 25 | .installed.cfg
 26 | *.egg
 27 | MANIFEST
 28 | 
 29 | # PyInstaller
 30 | #  Usually these files are written by a python script from a template
 31 | #  before PyInstaller builds the exe, so as to inject date/other infos into it.
 32 | *.manifest
 33 | *.spec
 34 | 
 35 | # Installer logs
 36 | pip-log.txt
 37 | pip-delete-this-directory.txt
 38 | 
 39 | # Unit test / coverage reports
 40 | htmlcov/
 41 | .tox/
 42 | .nox/
 43 | .coverage
 44 | .coverage.*
 45 | .cache
 46 | nosetests.xml
 47 | coverage.xml
 48 | *.cover
 49 | *.py,cover
 50 | .hypothesis/
 51 | .pytest_cache/
 52 | cover/
 53 | 
 54 | # Translations
 55 | *.mo
 56 | *.pot
 57 | 
 58 | # Django stuff:
 59 | *.log
 60 | local_settings.py
 61 | db.sqlite3
 62 | db.sqlite3-journal
 63 | 
 64 | # Flask stuff:
 65 | instance/
 66 | .webassets-cache
 67 | 
 68 | # Scrapy stuff:
 69 | .scrapy
 70 | 
 71 | # Sphinx documentation
 72 | docs/_build/
 73 | 
 74 | # PyBuilder
 75 | .pybuilder/
 76 | target/
 77 | 
 78 | # Jupyter Notebook
 79 | .ipynb_checkpoints
 80 | 
 81 | # IPython
 82 | profile_default/
 83 | ipython_config.py
 84 | 
 85 | # pyenv
 86 | #   For a library or package, you might want to ignore these files since the code is
 87 | #   intended to run in multiple environments; otherwise, check them in:
 88 | # .python-version
 89 | 
 90 | # pipenv
 91 | #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
 92 | #   However, in case of collaboration, if having platform-specific dependencies or dependencies
 93 | #   having no cross-platform support, pipenv may install dependencies that don't work, or not
 94 | #   install all needed dependencies.
 95 | #Pipfile.lock
 96 | 
 97 | # UV
 98 | #   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
 99 | #   This is especially recommended for binary packages to ensure reproducibility, and is more
100 | #   commonly ignored for libraries.
101 | #uv.lock
102 | 
103 | # poetry
104 | #   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105 | #   This is especially recommended for binary packages to ensure reproducibility, and is more
106 | #   commonly ignored for libraries.
107 | #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108 | #poetry.lock
109 | 
110 | # pdm
111 | #   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
112 | #pdm.lock
113 | #   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
114 | #   in version control.
115 | #   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
116 | .pdm.toml
117 | .pdm-python
118 | .pdm-build/
119 | 
120 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
121 | __pypackages__/
122 | 
123 | # Celery stuff
124 | celerybeat-schedule
125 | celerybeat.pid
126 | 
127 | # SageMath parsed files
128 | *.sage.py
129 | 
130 | # Environments
131 | .env
132 | .venv
133 | env/
134 | venv/
135 | ENV/
136 | env.bak/
137 | venv.bak/
138 | 
139 | # Spyder project settings
140 | .spyderproject
141 | .spyproject
142 | 
143 | # Rope project settings
144 | .ropeproject
145 | 
146 | # mkdocs documentation
147 | /site
148 | 
149 | # mypy
150 | .mypy_cache/
151 | .dmypy.json
152 | dmypy.json
153 | 
154 | # Pyre type checker
155 | .pyre/
156 | 
157 | # pytype static type analyzer
158 | .pytype/
159 | 
160 | # Cython debug symbols
161 | cython_debug/
162 | 
163 | # PyCharm
164 | #  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
165 | #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
166 | #  and can be added to the global gitignore or merged into this file.  For a more nuclear
167 | #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
168 | #.idea/
169 | 
170 | # PyPI configuration file
171 | .pypirc
172 | 


--------------------------------------------------------------------------------
/tests/test_commands__run.py:
--------------------------------------------------------------------------------
  1 | from __future__ import annotations
  2 | 
  3 | from runchain.commands import cli
  4 | 
  5 | 
  6 | def test_run_success(mock_subprocess, runner, home_dir, test_script):
  7 |     """
  8 |     Test running a chain successfully.
  9 |     """
 10 |     # Add a script to create the chain
 11 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
 12 |     
 13 |     result = runner.invoke(cli, ["run", "testchain"])
 14 |     assert result.exit_code == 0
 15 |     assert "Running 10-test_script.sh..." in result.output
 16 |     assert "Chain 'testchain' completed successfully" in result.output
 17 |     
 18 |     # Check subprocess.run was called
 19 |     mock_subprocess.assert_called_once()
 20 | 
 21 | 
 22 | def test_run_script_failure(mock_subprocess, runner, home_dir, test_script):
 23 |     """
 24 |     Test running a chain with failing script.
 25 |     """
 26 |     mock_subprocess.return_value.returncode = 1
 27 |     
 28 |     # Add a script to create the chain
 29 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
 30 |     
 31 |     result = runner.invoke(cli, ["run", "testchain"])
 32 |     assert result.exit_code == 1
 33 |     assert "Running 10-test_script.sh..." in result.output
 34 |     assert "failed with exit code 1" in result.output
 35 | 
 36 | 
 37 | def test_run_multiple_scripts_in_order(mock_subprocess, runner, home_dir, test_script):
 38 |     """
 39 |     Test running multiple scripts in alphabetical order.
 40 |     """
 41 |     # Add multiple scripts
 42 |     runner.invoke(cli, ["add", "testchain", str(test_script), "30-third"])
 43 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10-first"])  
 44 |     runner.invoke(cli, ["add", "testchain", str(test_script), "20-second"])
 45 |     
 46 |     result = runner.invoke(cli, ["run", "testchain"])
 47 |     assert result.exit_code == 0
 48 |     
 49 |     # Check they ran in alphabetical order
 50 |     output_lines = result.output.strip().split('\n')
 51 |     running_lines = [line for line in output_lines if line.startswith("Running")]
 52 |     assert "Running 10-first..." in running_lines[0]
 53 |     assert "Running 20-second..." in running_lines[1]
 54 |     assert "Running 30-third..." in running_lines[2]
 55 | 
 56 | 
 57 | def test_run_stops_on_failure(mock_subprocess, runner, home_dir, test_script):
 58 |     """
 59 |     Test that running stops on first script failure.
 60 |     """
 61 |     # First call succeeds, second fails
 62 |     mock_subprocess.side_effect = [
 63 |         type('', (), {'returncode': 0})(),  # First script succeeds
 64 |         type('', (), {'returncode': 1})(),  # Second script fails
 65 |     ]
 66 |     
 67 |     # Add multiple scripts
 68 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10-first"])
 69 |     runner.invoke(cli, ["add", "testchain", str(test_script), "20-second"])
 70 |     runner.invoke(cli, ["add", "testchain", str(test_script), "30-third"])
 71 |     
 72 |     result = runner.invoke(cli, ["run", "testchain"])
 73 |     assert result.exit_code == 1
 74 |     
 75 |     # Should have run first two scripts but not the third
 76 |     assert "Running 10-first..." in result.output
 77 |     assert "Running 20-second..." in result.output
 78 |     assert "Running 30-third..." not in result.output
 79 |     assert "failed with exit code 1" in result.output
 80 | 
 81 | 
 82 | def test_run_nonexistent_chain(runner, home_dir):
 83 |     """
 84 |     Test running a nonexistent chain.
 85 |     """
 86 |     result = runner.invoke(cli, ["run", "nonexistent"])
 87 |     assert result.exit_code != 0
 88 |     assert "does not exist" in result.output
 89 | 
 90 | 
 91 | def test_run_invalid_chain_name(runner, home_dir):
 92 |     """
 93 |     Test running with invalid chain name.
 94 |     """
 95 |     result = runner.invoke(cli, ["run", "invalid-name"])
 96 |     assert result.exit_code != 0
 97 |     assert "must contain only lowercase letters" in result.output
 98 | 
 99 | 
100 | def test_run_empty_chain(mock_subprocess, runner, home_dir):
101 |     """
102 |     Test running an empty chain.
103 |     """
104 |     # Create empty chain directory
105 |     runchain_dir = home_dir / ".runchain"
106 |     runchain_dir.mkdir()
107 |     (runchain_dir / "empty").mkdir()
108 |     
109 |     result = runner.invoke(cli, ["run", "empty"])
110 |     assert result.exit_code == 0
111 |     
112 |     # Should complete successfully with no scripts to run
113 |     mock_subprocess.assert_not_called()


--------------------------------------------------------------------------------
/tests/test_commands__remove.py:
--------------------------------------------------------------------------------
  1 | from __future__ import annotations
  2 | 
  3 | from runchain.commands import cli
  4 | 
  5 | 
  6 | def test_remove_script(runner, home_dir, test_script):
  7 |     """
  8 |     Test removing a script from a chain.
  9 |     """
 10 |     # First add a script
 11 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
 12 |     
 13 |     # Then remove it
 14 |     result = runner.invoke(cli, ["remove", "testchain", "10-test_script.sh"])
 15 |     assert result.exit_code == 0
 16 |     assert "Removed script from chain 'testchain'" in result.output
 17 |     
 18 |     # Check file was removed
 19 |     chain_dir = home_dir / ".runchain" / "testchain"
 20 |     target_file = chain_dir / "10-test_script.sh"
 21 |     assert not target_file.exists()
 22 | 
 23 | 
 24 | def test_remove_script_removes_empty_chain(runner, home_dir, test_script):
 25 |     """
 26 |     Test that removing the last script removes the empty chain directory.
 27 |     """
 28 |     # Add a script
 29 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
 30 |     chain_dir = home_dir / ".runchain" / "testchain"
 31 |     assert chain_dir.exists()
 32 |     
 33 |     # Remove the script
 34 |     runner.invoke(cli, ["remove", "testchain", "10-test_script.sh"])
 35 |     
 36 |     # Chain directory should be gone
 37 |     assert not chain_dir.exists()
 38 | 
 39 | 
 40 | def test_remove_nonexistent_script(runner, home_dir, test_script):
 41 |     """
 42 |     Test removing a script that doesn't exist.
 43 |     """
 44 |     # Create chain with a script
 45 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
 46 |     
 47 |     result = runner.invoke(cli, ["remove", "testchain", "nonexistent.sh"])
 48 |     assert result.exit_code != 0
 49 |     assert "not found in chain" in result.output
 50 | 
 51 | 
 52 | def test_remove_chain_empty(runner, home_dir):
 53 |     """
 54 |     Test removing an empty chain.
 55 |     """
 56 |     # Create empty chain
 57 |     runchain_dir = home_dir / ".runchain"
 58 |     runchain_dir.mkdir()
 59 |     (runchain_dir / "testchain").mkdir()
 60 |     
 61 |     result = runner.invoke(cli, ["remove", "testchain"])
 62 |     assert result.exit_code == 0
 63 |     assert "Removed chain 'testchain'" in result.output
 64 |     assert not (runchain_dir / "testchain").exists()
 65 | 
 66 | 
 67 | def test_remove_chain_with_scripts_confirm_yes(runner, home_dir, test_script):
 68 |     """
 69 |     Test removing a chain with scripts, confirming yes.
 70 |     """
 71 |     # Add a script to create the chain
 72 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
 73 |     
 74 |     # Remove chain with confirmation
 75 |     result = runner.invoke(cli, ["remove", "testchain"], input="y\n")
 76 |     assert result.exit_code == 0
 77 |     assert "Removed chain 'testchain'" in result.output
 78 |     
 79 |     chain_dir = home_dir / ".runchain" / "testchain"
 80 |     assert not chain_dir.exists()
 81 | 
 82 | 
 83 | def test_remove_chain_with_scripts_confirm_no(runner, home_dir, test_script):
 84 |     """
 85 |     Test removing a chain with scripts, confirming no.
 86 |     """
 87 |     # Add a script to create the chain
 88 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
 89 |     
 90 |     # Remove chain, decline confirmation
 91 |     result = runner.invoke(cli, ["remove", "testchain"], input="n\n")
 92 |     assert result.exit_code == 0
 93 |     assert "Removed chain 'testchain'" not in result.output
 94 |     
 95 |     # Chain should still exist
 96 |     chain_dir = home_dir / ".runchain" / "testchain"
 97 |     assert chain_dir.exists()
 98 | 
 99 | 
100 | def test_remove_chain_force(runner, home_dir, test_script):
101 |     """
102 |     Test removing a chain with --force flag.
103 |     """
104 |     # Add a script to create the chain
105 |     runner.invoke(cli, ["add", "testchain", str(test_script), "10"])
106 |     
107 |     # Remove chain with force
108 |     result = runner.invoke(cli, ["remove", "testchain", "--force"])
109 |     assert result.exit_code == 0
110 |     assert "Removed chain 'testchain'" in result.output
111 |     
112 |     chain_dir = home_dir / ".runchain" / "testchain"
113 |     assert not chain_dir.exists()
114 | 
115 | 
116 | def test_remove_nonexistent_chain(runner, home_dir):
117 |     """
118 |     Test removing a nonexistent chain.
119 |     """
120 |     result = runner.invoke(cli, ["remove", "nonexistent"])
121 |     assert result.exit_code != 0
122 |     assert "does not exist" in result.output
123 | 
124 | 
125 | def test_remove_invalid_chain_name(runner, home_dir):
126 |     """
127 |     Test removing with invalid chain name.
128 |     """
129 |     result = runner.invoke(cli, ["remove", "invalid-name"])
130 |     assert result.exit_code != 0
131 |     assert "must contain only lowercase letters" in result.output


--------------------------------------------------------------------------------
/runchain/chain.py:
--------------------------------------------------------------------------------
  1 | from __future__ import annotations
  2 | 
  3 | import os
  4 | import re
  5 | import shutil
  6 | import stat
  7 | import subprocess
  8 | import tempfile
  9 | from pathlib import Path
 10 | 
 11 | from crondir import Crondir
 12 | from runchain.exceptions import ChainError
 13 | 
 14 | 
 15 | def list_chains(base_dir: Path | str | None = None) -> list[str]:
 16 |     """List all available chains."""
 17 |     if base_dir is None:
 18 |         base_dir = os.environ.get("RUNCHAIN_PATH", Path.home() / ".runchain")
 19 |     base_path = Path(base_dir)
 20 |     
 21 |     if not base_path.exists():
 22 |         return []
 23 |     
 24 |     chains = []
 25 |     for path in base_path.iterdir():
 26 |         if path.is_dir() and re.match(r'^[a-z]+$', path.name):
 27 |             chains.append(path.name)
 28 |     return sorted(chains)
 29 | 
 30 | 
 31 | class Chain:
 32 |     """Represents a single runchain chain."""
 33 |     
 34 |     def __init__(self, name: str, base_dir: Path | str | None = None):
 35 |         """
 36 |         Initialize Chain instance.
 37 |         
 38 |         Args:
 39 |             name: Name of the chain
 40 |             base_dir: Base directory for chains. Defaults to RUNCHAIN_PATH env var or ~/.runchain
 41 |         """
 42 |         if not re.match(r'^[a-z]+$', name):
 43 |             raise ChainError(f"Chain name '{name}' must contain only lowercase letters (a-z)")
 44 |         
 45 |         self.name = name
 46 |         
 47 |         if base_dir is None:
 48 |             base_dir = os.environ.get("RUNCHAIN_PATH", Path.home() / ".runchain")
 49 |         self.base_dir = Path(base_dir)
 50 |         self.base_dir.mkdir(exist_ok=True)
 51 |         
 52 |         self.path = self.base_dir / name
 53 |     
 54 |     def _create(self) -> None:
 55 |         """Create the chain directory."""
 56 |         self.path.mkdir(exist_ok=True)
 57 |     
 58 |     def log(self, message: str) -> None:
 59 |         """Log a message."""
 60 |         print(message)
 61 |     
 62 |     def exists(self) -> bool:
 63 |         """Check if this chain exists."""
 64 |         return self.path.exists() and self.path.is_dir()
 65 |     
 66 |     def list(self) -> list[str]:
 67 |         """List all scripts in this chain in alphabetical order."""
 68 |         if not self.exists():
 69 |             return []
 70 |         
 71 |         scripts = []
 72 |         for script_path in sorted(self.path.iterdir()):
 73 |             if script_path.is_file():
 74 |                 executable = os.access(script_path, os.X_OK)
 75 |                 status = " (executable)" if executable else " (not executable)"
 76 |                 scripts.append(f"{script_path.name}{status}")
 77 |         return scripts
 78 |     
 79 |     def add_file(self, script_path: str, target: str | None = None) -> str:
 80 |         """
 81 |         Add a script to this chain.
 82 |         
 83 |         Args:
 84 |             script_path: Path to the script file to add
 85 |             target: Optional naming specification
 86 |         
 87 |         Returns:
 88 |             The final filename in the chain
 89 |         """
 90 |         source_path = Path(script_path)
 91 |         if not source_path.exists():
 92 |             raise ChainError(f"Script file '{script_path}' does not exist")
 93 |         
 94 |         # Create chain directory if it doesn't exist
 95 |         if not self.exists():
 96 |             self._create()
 97 |         
 98 |         # Determine target filename
 99 |         if target is None:
100 |             # Must already follow NN-* format
101 |             basename = source_path.name
102 |             if not re.match(r'^\d+-', basename):
103 |                 raise ChainError(f"Script basename '{basename}' must start with NN- format when no target specified")
104 |             target_name = basename
105 |         elif target.isdigit():
106 |             # Number provided - use NN-basename format
107 |             target_name = f"{target}-{source_path.name}"
108 |         elif re.match(r'^\d+-', target):
109 |             # Full name starting with NN- provided
110 |             target_name = target
111 |         else:
112 |             # Invalid format
113 |             raise ChainError(f"Target '{target}' must be a number or start with NN- format")
114 |         
115 |         target_path = self.path / target_name
116 |         
117 |         # Copy script and make executable
118 |         shutil.copy2(source_path, target_path)
119 |         target_path.chmod(target_path.stat().st_mode | stat.S_IEXEC)
120 |         
121 |         return target_name
122 |     
123 |     def add_string(self, *contents: str, target: str) -> str:
124 |         """
125 |         Add a script string to this chain.
126 |         
127 |         Args:
128 |             contents: Script content lines
129 |             target: Required naming specification (number or NN-name format)
130 |         
131 |         Returns:
132 |             The final filename in the chain
133 |         """
134 |         with tempfile.NamedTemporaryFile(mode="w", suffix=".sh") as temp_file:
135 |             temp_file.write("\n".join(contents))
136 |             temp_file.flush()
137 |             return self.add_file(temp_file.name, target)
138 |     
139 |     def remove(self, script: str, target: str | None = None) -> None:
140 |         """Remove a script from this chain."""
141 |         if not self.exists():
142 |             raise ChainError(f"Chain '{self.name}' does not exist")
143 |         
144 |         # Use exact filename match only
145 |         filename = target if target is not None else script
146 |         target_path = self.path / filename
147 |         
148 |         if not target_path.exists():
149 |             raise ChainError(f"Script '{filename}' not found in chain '{self.name}'")
150 |         
151 |         target_path.unlink()
152 |         
153 |         # Delete chain directory if empty
154 |         if not any(self.path.iterdir()):
155 |             self.path.rmdir()
156 |     
157 |     def destroy(self) -> None:
158 |         """Remove this entire chain."""
159 |         if not self.exists():
160 |             raise ChainError(f"Chain '{self.name}' does not exist")
161 |         
162 |         shutil.rmtree(self.path)
163 |     
164 |     def cron(self, schedule: str) -> None:
165 |         """Schedule this chain to run with crondir."""
166 |         if not self.exists():
167 |             raise ChainError(f"Chain '{self.name}' does not exist")
168 |         
169 |         # Create cron entry string
170 |         cron_content = f"{schedule} runchain run {self.name}"
171 |         
172 |         # Use crondir Python API
173 |         crondir = Crondir()
174 |         crondir.add_string(
175 |             cron_content,
176 |             snippet=f'runchain-{self.name}',
177 |             force=True
178 |         )
179 |     
180 |     def run(self) -> bool:
181 |         """
182 |         Execute all scripts in this chain in alphabetical order.
183 |         
184 |         Returns:
185 |             True if all scripts succeeded, False if any failed
186 |         """
187 |         if not self.exists():
188 |             raise ChainError(f"Chain '{self.name}' does not exist")
189 |         
190 |         # Execute each script in alphabetical order
191 |         for script_path in sorted(self.path.iterdir()):
192 |             self.log(f"Running {script_path.name}...")
193 |             
194 |             result = subprocess.run([str(script_path)], 
195 |                                   cwd=script_path.parent,
196 |                                   capture_output=False)
197 |             
198 |             if result.returncode != 0:
199 |                 self.log(f"Script {script_path.name} failed with exit code {result.returncode}")
200 |                 return False
201 |         
202 |         self.log(f"Chain '{self.name}' completed successfully")
203 |         return True


--------------------------------------------------------------------------------