auto-toolkit 0.1.0b1__tar.gz

auto_toolkit-0.1.0b1/.github/workflows/pypi-publish.yml

@@ -0,0 +1,25 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    environment:
+      name: release
+      url: https://pypi.org/p/auto-toolkit
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

auto_toolkit-0.1.0b1/.gitignore

@@ -0,0 +1,66 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# C extension build artifacts
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# UV caches
+.uv/
+
+# Testing and linters
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# Editor and IDE directories
+.vscode/
+.idea/
+*.sublime-project
+*.sublime-workspace
+
+# Operating System files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Backups and temporary files
+*.swp
+*.swo
+*.bak
+*.tmp
+*~
+#*#

auto_toolkit-0.1.0b1/.python-version

@@ -0,0 +1 @@
+3.12

auto_toolkit-0.1.0b1/ARCHITECTURE.md

@@ -0,0 +1,83 @@
+# Architecture Overview
+
+The **Personal Automation Toolkit (`auto-toolkit`)** is a modular automation engine and CLI designed to discover, document, validate, and execute automation scripts and application lifecycle tasks across single or multiple repositories from any directory.
+
+## 1. Core Execution Pipeline
+
+```text
+User Command: auto <name|app|verb> [args...]
+      │
+      ▼
+1. Configuration & Multi-Repo Resolution (src/config.py)
+   Loads registered repositories from AUTO_REPOS env var and ~/.auto-toolkit/config.toml
+      │
+      ▼
+2. Multi-Root Dynamic Discovery (src/discovery.py)
+   Scans data/scripts/ & data/apps/ across all repos, strips extensions (.sh, .py), creates aliases
+      │
+      ▼
+3. Metadata Parsing (src/metadata.py)
+   Extracts DESCRIPTION, TAGS, DEPENDS, ENV, VERSION, AUTHOR, USAGE from file header comments
+      │
+      ▼
+4. Resolution & Search (src/search.py / src/cli.py)
+   Exact match -> Alias match -> Prefix match -> Ranked multi-token search
+      │
+      ▼
+5. Pre-Flight Validation (src/executor.py)
+   Verifies executable permissions (+x) and checks $PATH for declared dependencies
+      │
+      ▼
+6. Process Handover (os.execvp)
+   Replaces CLI process image directly with target script (zero wrapping overhead)
+```
+
+## 2. Directory Layout & Module Roles
+
+```text
+├── bin/
+│   └── auto                  # CLI entrypoint executable
+│
+├── src/                      # Python Core Engine
+│   ├── cli.py                # Command routing, terminal presentation, and subcommand handlers
+│   ├── colors.py             # ANSI terminal colors with toggle support
+│   ├── config.py             # Multi-repository configuration loader (env vars + TOML)
+│   ├── constants.py          # Central paths, extensions, exclusions, and synonyms
+│   ├── discovery.py          # Multi-root file scanner, extension stripper, and alias generator
+│   ├── enums.py              # HeaderKey and Severity enums
+│   ├── executor.py           # Pre-flight checks and os.execvp process replacement
+│   ├── installer.py          # PATH management and symlink installer
+│   ├── metadata.py           # Header comment parser (Bash, Python, C-style comments)
+│   ├── search.py             # Multi-token ranked search scoring engine
+│   └── validator.py          # Repository health diagnostics (shebangs, permissions, dependencies)
+│
+├── data/                     # Executable Assets & Libraries
+│   ├── apps/                 # Multi-action application packages (e.g. auto-toolkit/install.sh)
+│   ├── scripts/              # Category-organized utilities (docker/, files/, setup/, system/, etc.)
+│   └── libs/                 # Reusable shell helpers (args.sh, common.sh, download.sh, gpg.sh, pkg.sh)
+│
+├── tests/                    # Pytest test suite (100% unit & integration test coverage)
+└── pyproject.toml            # Hatchling build configuration & PyPI metadata
+```
+
+## 3. Multi-Repository & Extensibility Architecture
+
+To enable users to maintain personal or proprietary scripts without polluting or forking the core engine repository, `auto-toolkit` implements a **Kernel / Userspace** separation:
+
+1. **Core Repository (`core`)**: Contains the Python engine (`src/`), base shell libraries (`data/libs/`), and starter scripts.
+2. **User Repositories (`personal`, `work`, etc.)**: Independent Git repositories structured with their own `data/scripts/`, `data/apps/`, and `data/libs/`.
+3. **Repository Resolution Order**:
+   - `core`: Root of the installed `auto-toolkit` repository (always first).
+   - `AUTO_REPOS`: Environment variable (e.g. `export AUTO_REPOS="personal=~/.auto-toolkit/repos/automations"`).
+   - `~/.auto-toolkit/config.toml`: Persistent TOML configuration file (`[repos]` section).
+4. **Source Tagging**: When multiple repositories are active, `auto list` and `auto search` annotate items with their source repository tag (e.g. `[core]`, `[personal]`).
+5. **Update Lifecycle**:
+   - `auto self-update`: Orchestrates `git pull` on the core engine repo.
+   - `auto repo-update [name]`: Orchestrates `git pull` across user-added repositories.
+
+## 4. Key Design Decisions
+
+- **Process Handover (`os.execvp`)**: Rather than running scripts inside subshells or pipes, the CLI replaces its own process with the target executable. This preserves standard I/O (interactive prompts), terminal TTY colors, signal handling (`SIGINT`/`Ctrl+C`), and exact exit codes.
+- **Convention Over Configuration**: No central JSON or YAML script registry. Adding a script to `data/scripts/<category>/` or `data/apps/<app>/` automatically makes it discoverable.
+- **Extension-Free CLI**: Scripts retain clear file extensions (`.sh`, `.py`) in the repository for editor tooling and linters, but users invoke them cleanly (`auto docker-cleanup` or `auto install auto-toolkit`).
+- **Zero Third-Party Production Dependencies**: The core CLI is built strictly with the Python standard library.

auto_toolkit-0.1.0b1/CONTRIBUTING.md

@@ -0,0 +1,127 @@
+# Contributing Guide
+
+Guidelines for contributing to the core **`auto-toolkit`** repository or developing personal automation repositories.
+
+## 1. Core Repository vs. Personal Automation Repositories
+
+Before adding new scripts, decide whether they belong in the **upstream `auto-toolkit`** or in a **personal repository**:
+
+| Type                                   | Destination                                                        | Examples                                                                                          |
+| :------------------------------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ |
+| **General Utilities & Core Engine**    | `auto-toolkit` (this repository)                                   | Reusable system tools, general docker helpers, CLI enhancements, shared libraries in `data/libs/` |
+| **Personal / Proprietary Automations** | Personal Git repository (e.g. `~/.auto-toolkit/repos/automations`) | Personal dotfiles setups, company deployments, internal API scripts, private credentials          |
+
+To register your personal repository with `auto`:
+
+```toml
+# ~/.auto-toolkit/config.toml
+[repos]
+personal = "~/.auto-toolkit/repos/automations"
+```
+
+## 2. Quick Development Setup
+
+```bash
+# Sync virtual environment and development dependencies
+uv sync
+
+# Run the test suite
+uv run pytest -v
+
+# Check formatting and lint rules
+uv run ruff check src tests
+```
+
+## 3. Adding a General Script
+
+1. Create an executable script under `data/scripts/<category>/<name>.<ext>`:
+   ```bash
+   data/scripts/network/check-port.sh
+   ```
+2. Add a metadata header near the top of the file:
+
+   ```bash
+   #!/usr/bin/env bash
+   # DESCRIPTION: Test if a remote host port is open
+   # TAGS: network, port, tcp, ping
+   # DEPENDS: nc, curl
+   # USAGE: auto check-port <host> <port>
+
+   set -euo pipefail
+   HOST="${1:?Missing host}"
+   PORT="${2:?Missing port}"
+   nc -z -v -w5 "$HOST" "$PORT"
+   ```
+
+3. Make it executable:
+   ```bash
+   chmod +x data/scripts/network/check-port.sh
+   ```
+4. Test discovery and execution:
+   ```bash
+   auto list network
+   auto check-port localhost 8080
+   ```
+
+## 4. Adding a Dedicated Application Package
+
+When an application requires multi-stage lifecycles (downloads, PGP signature verification, package updates):
+
+1. Create a directory under `data/apps/<app-name>/`.
+2. Create `install.sh` and `update.sh`:
+
+   ```bash
+   #!/usr/bin/env bash
+   # DESCRIPTION: Install MyTool binary
+   # TAGS: app, mytool, install
+   # DEPENDS: curl, gpg
+
+   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+   LIB_DIR="$(cd "$SCRIPT_DIR/../../libs" && pwd)"
+   source "$LIB_DIR/common.sh"
+   source "$LIB_DIR/args.sh"
+   source "$LIB_DIR/gpg.sh"
+   source "$LIB_DIR/download.sh"
+
+   # Implement verified installation...
+   ```
+
+3. Make them executable (`chmod +x data/apps/<app-name>/*.sh`).
+4. Test verb-first routing:
+   ```bash
+   auto apps
+   auto install <app-name> --help
+   auto update <app-name> --help
+   ```
+
+## 5. Metadata Header Specification
+
+| Field         | Format          | Description                                        |
+| :------------ | :-------------- | :------------------------------------------------- |
+| `DESCRIPTION` | Text            | Short summary shown in `auto list` and `auto info` |
+| `TAGS`        | Comma-separated | Search keywords for `auto search`                  |
+| `DEPENDS`     | Comma-separated | Required binaries checked before execution         |
+| `ENV`         | Comma-separated | Required or optional environment variables         |
+| `VERSION`     | SemVer          | Script version string                              |
+| `AUTHOR`      | Text            | Author/maintainer contact                          |
+| `USAGE`       | Text            | Custom syntax shown in `auto info`                 |
+
+## 6. Shared Helper Libraries (`data/libs/`)
+
+When writing shell automations, reuse standard helpers:
+
+- **`data/libs/args.sh`**: Declarative CLI argument parsing and automatic `--help` generation.
+- **`data/libs/common.sh`**: Logging (`log_info`, `log_success`, `log_error`) and isolated temp directories.
+- **`data/libs/download.sh`**: Resilient HTTP downloads with retry logic.
+- **`data/libs/gpg.sh`**: Cryptographic detached signature and hash verification.
+- **`data/libs/pkg.sh`**: Linux package manager detection and installation routines.
+
+## 7. Quality & Pre-Commit Checklist
+
+Before submitting a PR or commit:
+
+- [ ] Script is marked executable (`chmod +x`).
+- [ ] Valid shebang line is present (`#!/usr/bin/env bash` or `#!/usr/bin/env python3`).
+- [ ] `auto validate` passes with 0 errors.
+- [ ] `uv run pytest -v` passes (all unit and integration tests).
+- [ ] `uv run ruff check src tests` passes.

auto_toolkit-0.1.0b1/Makefile

@@ -0,0 +1,30 @@
+.PHONY: test install uninstall validate check list clean dev
+
+test:
+	@if command -v uv >/dev/null 2>&1; then \
+		uv run pytest; \
+	else \
+		python3 -m unittest discover -s tests -v; \
+	fi
+
+dev:
+	uv sync
+
+install:
+	./data/apps/auto-toolkit/install.sh
+
+uninstall:
+	./bin/auto uninstall
+
+validate:
+	./bin/auto validate
+
+check: validate test
+
+list:
+	./bin/auto list
+
+clean:
+	find . -type d -name "__pycache__" -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+	rm -rf .pytest_cache .ruff_cache