phoxtail 0.1.0__tar.gz

phoxtail-0.1.0/LICENSE

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

phoxtail-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include LICENSE
+include README.md
+recursive-include phoxtail/templates *
+prune phoxtail/tests
+prune phoxtail/docs
+prune docs-temp
+prune build
+exclude CLAUDE.md
+exclude uv.lock

phoxtail-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: phoxtail
+Version: 0.1.0
+Summary: The engine behind every Phoxtail project.
+Author-email: Phoxmor <info@phoxtail.com>
+Maintainer-email: Evangelos Pisinas <evangelos.pisinas@phoxtail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://phoxtail.com
+Project-URL: Repository, https://github.com/phoxmor/phoxtail
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: Django
+Classifier: Framework :: Wagtail
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: questionary>=2.0.0
+Requires-Dist: jinja2>=3.1.0
+Provides-Extra: dev
+Requires-Dist: pip-tools>=7.0.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.4.0; extra == "dev"
+Dynamic: license-file
+
+# Phoxtail
+
+The engine behind every Phoxtail project.
+
+Phoxtail is a CLI toolkit that automates the development and deployment workflow for Phoxtail projects — Docker configuration, environment setup, database operations, nginx, SSL, media sync, and more.
+
+## Requirements
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Installation
+
+### As a CLI tool
+
+```bash
+# Recommended: installs in an isolated environment
+uv tool install phoxtail
+
+# Or with pip/pipx
+pip install phoxtail
+```
+
+### For development
+
+```bash
+git clone git@github.com:phoxmor/phoxtail.git
+cd phoxtail
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+Run `phoxtail` from the root of any Phoxtail project (where `phoxtail.toml` lives):
+
+```bash
+phoxtail --help
+```
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `phoxtail docker up/down/restart` | Docker lifecycle management |
+| `phoxtail docker create compose` | Generate docker-compose.yaml |
+| `phoxtail docker create dockerfile` | Generate Dockerfile |
+| `phoxtail env create` | Generate .env files (dev/production) |
+| `phoxtail nginx create initial` | Nginx config for SSL certificate retrieval |
+| `phoxtail nginx create production` | Nginx config with SSL/TLS |
+| `phoxtail ssl obtain/renew` | SSL certificate management |
+| `phoxtail db backup/restore` | Database backup and restore |
+| `phoxtail db pull` | Pull database from remote server |
+| `phoxtail media pull` | Sync media files from remote server |
+| `phoxtail requirements compile` | Compile Python dependencies |
+| `phoxtail manage <command>` | Run Django management commands |
+| `phoxtail test` | Run the test suite |
+| `phoxtail lint` | Run linting and formatting |
+| `phoxtail version` | Show CLI version |
+
+## Project detection
+
+Phoxtail detects projects by looking for `phoxtail.toml` in the current directory. This file declares the project name, Docker image prefix, database clusters, and their dependencies.
+
+## Development
+
+### Running tests
+
+```bash
+pytest
+```
+
+### Project structure
+
+```
+phoxtail/
+  phoxtail/
+    __init__.py         # Package version
+    __main__.py         # CLI entry point (Typer app)
+    commands/           # Command modules
+    utils/              # Shared utilities (config, docker, env, templates)
+    templates/          # Jinja2 templates (Dockerfile, compose, nginx, env)
+    tests/              # Test suite
+  pyproject.toml
+  LICENSE
+  README.md
+```
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

phoxtail-0.1.0/README.md

@@ -0,0 +1,92 @@
+# Phoxtail
+
+The engine behind every Phoxtail project.
+
+Phoxtail is a CLI toolkit that automates the development and deployment workflow for Phoxtail projects — Docker configuration, environment setup, database operations, nginx, SSL, media sync, and more.
+
+## Requirements
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Installation
+
+### As a CLI tool
+
+```bash
+# Recommended: installs in an isolated environment
+uv tool install phoxtail
+
+# Or with pip/pipx
+pip install phoxtail
+```
+
+### For development
+
+```bash
+git clone git@github.com:phoxmor/phoxtail.git
+cd phoxtail
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+```
+
+## Usage
+
+Run `phoxtail` from the root of any Phoxtail project (where `phoxtail.toml` lives):
+
+```bash
+phoxtail --help
+```
+
+### Commands
+
+| Command | Description |
+|---|---|
+| `phoxtail docker up/down/restart` | Docker lifecycle management |
+| `phoxtail docker create compose` | Generate docker-compose.yaml |
+| `phoxtail docker create dockerfile` | Generate Dockerfile |
+| `phoxtail env create` | Generate .env files (dev/production) |
+| `phoxtail nginx create initial` | Nginx config for SSL certificate retrieval |
+| `phoxtail nginx create production` | Nginx config with SSL/TLS |
+| `phoxtail ssl obtain/renew` | SSL certificate management |
+| `phoxtail db backup/restore` | Database backup and restore |
+| `phoxtail db pull` | Pull database from remote server |
+| `phoxtail media pull` | Sync media files from remote server |
+| `phoxtail requirements compile` | Compile Python dependencies |
+| `phoxtail manage <command>` | Run Django management commands |
+| `phoxtail test` | Run the test suite |
+| `phoxtail lint` | Run linting and formatting |
+| `phoxtail version` | Show CLI version |
+
+## Project detection
+
+Phoxtail detects projects by looking for `phoxtail.toml` in the current directory. This file declares the project name, Docker image prefix, database clusters, and their dependencies.
+
+## Development
+
+### Running tests
+
+```bash
+pytest
+```
+
+### Project structure
+
+```
+phoxtail/
+  phoxtail/
+    __init__.py         # Package version
+    __main__.py         # CLI entry point (Typer app)
+    commands/           # Command modules
+    utils/              # Shared utilities (config, docker, env, templates)
+    templates/          # Jinja2 templates (Dockerfile, compose, nginx, env)
+    tests/              # Test suite
+  pyproject.toml
+  LICENSE
+  README.md
+```
+
+## License
+
+BSD 3-Clause. See [LICENSE](LICENSE).

phoxtail-0.1.0/phoxtail/__init__.py

@@ -0,0 +1,3 @@
+"""The engine behind every Phoxtail project."""
+
+__version__ = "0.1.0"

phoxtail-0.1.0/phoxtail/__main__.py

@@ -0,0 +1,80 @@
+"""Main CLI entry point for Phoxtail."""
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from phoxtail.commands import (
+    db,
+    docker,
+    env,
+    lint,
+    manage,
+    media,
+    nginx,
+    requirements,
+    ssl,
+    test,
+)
+from phoxtail.utils.config import _find_config_file
+
+app = typer.Typer(
+    name="phoxtail",
+    help="The engine behind every Phoxtail project.",
+    add_completion=True,
+    invoke_without_command=True,
+)
+console = Console()
+
+# Commands that don't require a phoxtail project.
+NO_PROJECT_COMMANDS = {"version"}
+
+
+@app.callback(invoke_without_command=True)
+def main(ctx: typer.Context):
+    """The engine behind every Phoxtail project."""
+    if ctx.invoked_subcommand is None:
+        console.print(ctx.get_help())
+        raise typer.Exit()
+
+    if ctx.invoked_subcommand in NO_PROJECT_COMMANDS or ctx.resilient_parsing:
+        return
+
+    if _find_config_file() is None:
+        console.print(
+            Panel(
+                "No [bold]phoxtail.toml[/bold] found in this directory or any parent.\n"
+                "Run this command from the root of a Phoxtail project.",
+                title="[red]Not a Phoxtail project[/red]",
+                border_style="red",
+                expand=False,
+            )
+        )
+        raise typer.Exit(code=1)
+
+
+# Command groups
+app.add_typer(docker.app, name="docker", help="Docker lifecycle and configuration")
+app.add_typer(db.app, name="db", help="Database operations")
+app.add_typer(media.app, name="media", help="Media file management")
+app.add_typer(nginx.app, name="nginx", help="Nginx configuration")
+app.add_typer(env.app, name="env", help="Environment configuration")
+app.add_typer(requirements.app, name="requirements", help="Python requirements")
+app.add_typer(ssl.app, name="ssl", help="SSL certificate management")
+
+# Top-level commands
+app.add_typer(manage.app, name="manage", help="Run Django management commands")
+app.add_typer(test.app, name="test", help="Run the test suite")
+app.add_typer(lint.app, name="lint", help="Run linting and formatting")
+
+
+@app.command()
+def version():
+    """Show the CLI version."""
+    from phoxtail import __version__
+
+    console.print(f"Phoxtail CLI v{__version__}", style="bold green")
+
+
+if __name__ == "__main__":
+    app()

phoxtail-0.1.0/phoxtail/commands/__init__.py

@@ -0,0 +1 @@
+"""Command modules for Phoxtail CLI."""

phoxtail-0.1.0/phoxtail/commands/db.py

@@ -0,0 +1,323 @@
+"""Database management commands for Phoxtail."""
+
+import ipaddress
+import json
+import subprocess
+from enum import Enum
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from phoxtail.utils.config import get_cluster_names, get_clusters, resolve_cluster_order
+from phoxtail.utils.docker import docker_db, docker_manage
+from phoxtail.utils.env import read_env_value
+
+app = typer.Typer()
+console = Console()
+
+
+def _build_data_cluster_enum():
+    """Build DataCluster enum from phoxtail.toml cluster names + 'all'."""
+    members = {name.upper(): name for name in get_cluster_names()}
+    members["ALL"] = "all"
+    return Enum("DataCluster", members, type=str)
+
+
+DataCluster = _build_data_cluster_enum()
+
+
+def _deep_localize(val, hostname_map: dict[str, str]):
+    """Recursively replace hostnames in a data structure.
+
+    Handles plain dicts/lists and JSON-encoded strings that may
+    contain hostname references (e.g. StreamField data).
+    """
+    if isinstance(val, dict):
+        return {k: _deep_localize(v, hostname_map) for k, v in val.items()}
+    elif isinstance(val, list):
+        # Natural key format: ["hostname", port]
+        if len(val) == 2 and isinstance(val[0], str) and isinstance(val[1], int):
+            h = val[0].lower()
+            if h in hostname_map:
+                return [hostname_map[h], val[1]]
+        return [_deep_localize(i, hostname_map) for i in val]
+    elif isinstance(val, str):
+        if (val.startswith("{") and val.endswith("}")) or (
+            val.startswith("[") and val.endswith("]")
+        ):
+            try:
+                parsed = json.loads(val)
+                translated = _deep_localize(parsed, hostname_map)
+                return json.dumps(translated)
+            except (json.JSONDecodeError, TypeError):
+                pass
+    return val
+
+
+def _localize_hostnames(data: list, target_domain: str) -> list:
+    """Translate remote hostnames to the target domain.
+
+    Builds a hostname map from wagtailcore.site entries, then applies it
+    across the entire fixture data including JSON-encoded string fields.
+    """
+    hostname_map = {}
+    for entry in data:
+        if entry.get("model") == "wagtailcore.site":
+            fields = entry.get("fields", {})
+            old_h = fields.get("hostname", "").lower()
+            if (
+                not old_h
+                or old_h == target_domain
+                or old_h.endswith(f".{target_domain}")
+            ):
+                continue
+            try:
+                ipaddress.ip_address(old_h)
+                continue
+            except ValueError:
+                pass
+
+            parts = old_h.split(".")
+            if len(parts) > 2:
+                subdomain = ".".join(parts[:-2])
+                new_h = f"{subdomain}.{target_domain}"
+            else:
+                new_h = target_domain
+            hostname_map[old_h] = new_h
+            fields["hostname"] = new_h
+
+    if not hostname_map:
+        return data
+
+    for entry in data:
+        entry["fields"] = _deep_localize(entry.get("fields", {}), hostname_map)
+
+    return data
+
+
+def _pull_single_cluster(
+    cluster_name: str,
+    remote_host: str,
+    remote_dir: str,
+    localize: bool,
+    progress,
+    task,
+) -> None:
+    """Pull and load a single cluster from the remote server."""
+    clusters = get_clusters()
+    selected_apps = clusters[cluster_name]["apps"]
+    dump_filename = f"remote_{cluster_name}_pull.json"
+    local_dump_path = Path.cwd() / dump_filename
+
+    try:
+        remote_cmd = (
+            f"cd {remote_dir} && "
+            f"docker compose exec web python manage.py dumpdata "
+            f"{' '.join(selected_apps)} "
+            f"--natural-foreign --indent 2 > {dump_filename}"
+        )
+        progress.update(
+            task, description=f"Dumping {cluster_name.upper()} on remote..."
+        )
+        subprocess.run(
+            ["ssh", remote_host, remote_cmd],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        progress.update(
+            task, description=f"Downloading {cluster_name.upper()} dump..."
+        )
+        subprocess.run(
+            [
+                "scp",
+                f"{remote_host}:{remote_dir}/{dump_filename}",
+                str(local_dump_path),
+            ],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+        # Clean up remote dump file (failure is non-critical)
+        subprocess.run(
+            ["ssh", remote_host, f"rm -f {remote_dir}/{dump_filename}"],
+            capture_output=True,
+        )
+
+        if localize:
+            target_domain = read_env_value("DOMAIN") or "localhost"
+            progress.update(
+                task,
+                description=(
+                    f"Localizing {cluster_name.upper()} "
+                    f"hostnames to {target_domain}..."
+                ),
+            )
+            with open(local_dump_path) as f:
+                data = json.load(f)
+            data = _localize_hostnames(data, target_domain)
+            with open(local_dump_path, "w") as f:
+                json.dump(data, f, indent=2)
+
+        progress.update(
+            task, description=f"Loading {cluster_name.upper()} into database..."
+        )
+        docker_manage("loaddata", local_dump_path.name)
+    finally:
+        if local_dump_path.exists():
+            local_dump_path.unlink()
+
+
+@app.command(name="pull")
+def pull(
+    cluster: DataCluster = typer.Argument(
+        ...,
+        help="The data cluster to pull from the remote server",
+    ),
+    remote_host: str = typer.Argument(
+        ...,
+        help="SSH connection string (e.g., user@example.com)",
+    ),
+    remote_dir: str = typer.Argument(
+        ...,
+        help="Path to the project on the remote server",
+    ),
+    localize: bool = typer.Option(
+        True,
+        "--localize/--no-localize",
+        help="Whether to translate remote hostnames to localhost/subdomains.localhost",
+    ),
+) -> None:
+    """Pull data clusters from a remote server to the local environment.
+
+    DANGER: This will FLUSH your local database before loading.
+    A safety backup is created automatically before flushing.
+
+    Dependencies are resolved automatically. For example, pulling 'booking'
+    will pull 'cms' first since booking data depends on it.
+    """
+    try:
+        cluster_order = resolve_cluster_order(cluster.value)
+    except ValueError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    if len(cluster_order) > 1:
+        names = " → ".join(c.upper() for c in cluster_order)
+        console.print(f"[dim]Resolved pull order: {names}[/dim]")
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        transient=True,
+    ) as progress:
+        task = progress.add_task(description="Starting...", total=None)
+        try:
+            progress.update(task, description="Creating safety backup...")
+            docker_db(
+                "PGPASSWORD=$POSTGRES_PASSWORD pg_dump -h localhost"
+                " -U $POSTGRES_USER $POSTGRES_DB"
+                " > /db-backups/pre_pull_safety.sql"
+            )
+
+            progress.update(task, description="Flushing local database...")
+            docker_manage("flush", "--no-input")
+
+            for cluster_name in cluster_order:
+                _pull_single_cluster(
+                    cluster_name, remote_host, remote_dir, localize, progress, task
+                )
+
+            pulled = ", ".join(c.upper() for c in cluster_order)
+            console.print(
+                f"[green bold]✓ {pulled} data pulled"
+                " and loaded[/green bold]"
+            )
+        except subprocess.CalledProcessError as e:
+            stderr = e.stderr if e.stderr else str(e)
+            console.print(f"[red]Error:[/red] {stderr}")
+            raise typer.Exit(1)
+
+
+@app.command(name="backup")
+def backup() -> None:
+    """Create a database backup.
+
+    Saves a timestamped SQL dump to the db-backups volume.
+    """
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        transient=True,
+    ) as progress:
+        progress.add_task(description="Creating database backup...", total=None)
+        try:
+            docker_db(
+                "PGPASSWORD=$POSTGRES_PASSWORD pg_dump -h localhost"
+                " -U $POSTGRES_USER $POSTGRES_DB"
+                " > /db-backups/$(date +%F_%H-%M-%S).sql"
+            )
+            console.print("[green bold]✓ Database backup created[/green bold]")
+        except subprocess.CalledProcessError as e:
+            stderr = e.stderr if e.stderr else str(e)
+            console.print(f"[red]Error:[/red] {stderr}")
+            raise typer.Exit(1)
+
+
+@app.command(name="restore")
+def restore(
+    backup_file: str = typer.Argument(
+        ...,
+        help="Backup filename to restore (e.g., 2026-03-15_12-00-00.sql)",
+    ),
+) -> None:
+    """Restore the database from a backup file.
+
+    A safety backup of the current state is created automatically before restoring.
+    The restore runs in a single transaction and will roll back on error.
+    """
+    from rich.prompt import Confirm
+
+    if not Confirm.ask(
+        "This will replace the current database with "
+        f"[bold]{backup_file}[/bold]. Continue?",
+        default=False,
+    ):
+        raise typer.Exit(0)
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("[progress.description]{task.description}"),
+        transient=True,
+    ) as progress:
+        try:
+            progress.add_task(
+                description="Creating safety backup of current state...", total=None
+            )
+            docker_db(
+                "PGPASSWORD=$POSTGRES_PASSWORD pg_dump -h localhost"
+                " -U $POSTGRES_USER $POSTGRES_DB"
+                " > /db-backups/pre_restore_safety.sql"
+            )
+
+            progress.add_task(
+                description=f"Restoring from {backup_file}...", total=None
+            )
+            docker_db(
+                "PGPASSWORD=$POSTGRES_PASSWORD psql -h localhost"
+                " -U $POSTGRES_USER -d $POSTGRES_DB"
+                " -v ON_ERROR_STOP=1 --single-transaction"
+                ' -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
+                ' GRANT ALL ON SCHEMA public TO \\"$POSTGRES_USER\\";'
+                ' GRANT ALL ON SCHEMA public TO public;"'
+                f" -f /db-backups/{backup_file}"
+            )
+            console.print(
+                f"[green bold]✓ Database restored from {backup_file}[/green bold]"
+            )
+        except subprocess.CalledProcessError as e:
+            stderr = e.stderr if e.stderr else str(e)
+            console.print(f"[red]Error:[/red] {stderr}")
+            raise typer.Exit(1)