forje-cloud 0.1.0__py3-none-any.whl

forje_cloud/__init__.py

@@ -0,0 +1,8 @@
+"""Idempotent server provisioning.
+
+Sets up Docker Swarm, a reverse proxy, and a Cloudflare tunnel on a Linux
+machine, and leaves anything that is already correct untouched.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Matheus Rodrigues Trindade"

forje_cloud/cli.py

@@ -0,0 +1,508 @@
+"""Command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from . import __version__, docgen, ui
+from .core import Config, Context, HashLog, Plan, Runner, Status
+from .steps import default_pipeline
+from .wizard import run_wizard
+
+DEFAULT_LOG = "/var/log/forje-cloud/runs.jsonl"
+DEFAULT_DOC = "INFRASTRUCTURE.md"
+
+
+def _config_from_args(args: argparse.Namespace) -> Config:
+    """Build a configuration from flags and the environment.
+
+    Flags win over environment variables. Anything still unset is either
+    collected by the wizard or left at its default.
+    """
+    cfg = Config()
+
+    for field, value in (
+        ("project", args.project),
+        ("hostname", args.hostname),
+        ("deploy_user", args.deploy_user),
+        ("edge_network", args.network),
+        ("domain", args.domain),
+    ):
+        if value:
+            setattr(cfg, field, value)
+
+    cfg.cf_api_token = args.cf_token or os.environ.get("CF_API_TOKEN", "")
+    cfg.cf_account_id = os.environ.get("CF_ACCOUNT_ID", "")
+    cfg.cf_zone_id = os.environ.get("CF_ZONE_ID", "")
+    cfg.tunnel_name = cfg.tunnel_name or cfg.project
+
+    cfg.r2_access_key = os.environ.get("R2_ACCESS_KEY_ID", "")
+    cfg.r2_secret_key = os.environ.get("R2_SECRET_ACCESS_KEY", "")
+    cfg.r2_account_id = os.environ.get("R2_ACCOUNT_ID", "")
+    cfg.r2_bucket = os.environ.get("R2_BUCKET", "")
+    cfg.backup_enabled = bool(cfg.r2_bucket and cfg.r2_access_key)
+
+    cfg.telegram_token = os.environ.get("TELEGRAM_TOKEN", "")
+    cfg.telegram_chat_id = os.environ.get("TELEGRAM_CHAT_ID", "")
+    cfg.llm_api_key = os.environ.get("LLM_API_KEY", "")
+    cfg.llm_provider = os.environ.get("LLM_PROVIDER", "claude")
+    cfg.monitoring_enabled = bool(cfg.telegram_token and cfg.llm_api_key)
+
+    cfg.close_ssh = args.close_ssh
+    return cfg
+
+
+def _context(cfg: Config, log_path: str) -> Context:
+    return Context(
+        cfg=cfg,
+        runner=Runner(assume_root=(os.geteuid() == 0)),
+        log=HashLog(log_path),
+    )
+
+
+def _write_doc(cfg: Config, results: list, path: str) -> None:
+    document = docgen.generate(cfg, results)
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(document, encoding="utf-8")
+    ui.note(f"Infrastructure documented: {destination}")
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    """Collect configuration interactively, then provision."""
+    cfg = _config_from_args(args)
+
+    completed = run_wizard(cfg)
+    if completed is None:
+        ui.warn("Cancelled. Nothing was changed.")
+        return 1
+
+    ctx = _context(completed, args.log)
+
+    ui.section("Applying")
+    if ctx.runner.needs_sudo_password():
+        ui.hint("Some steps need administrator rights.")
+        ctx.runner.prompt_sudo()
+        print()
+
+    plan = Plan(default_pipeline(), ctx)
+    plan.run(
+        yes=True,
+        on_result=lambda r: ui.result_line(r.step, r.status.value, r.detail, r.error),
+    )
+
+    counts = plan.summary()
+    ui.summary_box(
+        [
+            ("Configured", str(counts["applied"])),
+            ("Already present", str(counts["skipped"])),
+            ("Needs attention", str(counts["drifted"])),
+            ("Failed", str(counts["failed"] + counts["rolled_back"])),
+        ]
+    )
+
+    _write_doc(completed, plan.results, args.doc)
+    ui.note(f"Audit log: {ctx.log.path}")
+
+    if completed.domain:
+        print()
+        ui.note(f"Your server is reachable at https://{completed.domain}")
+        ui.hint(f"Any subdomain of {completed.domain} works, with HTTPS, immediately.")
+
+    ctx.clear_secrets()
+    print()
+    return 1 if counts["failed"] + counts["rolled_back"] else 0
+
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Report what this machine already has, changing nothing."""
+    cfg = _config_from_args(args)
+    ctx = _context(cfg, args.log)
+
+    ui.banner("Current state", "Nothing is changed by this command.")
+
+    for step in default_pipeline():
+        try:
+            verdict = step.check(ctx)
+        except Exception as exc:  # noqa: BLE001
+            ui.result_line(step.name, "failed", f"could not check: {exc}")
+            continue
+
+        if verdict.ok:
+            ui.result_line(step.name, "skipped", verdict.detail)
+        elif verdict.drift:
+            ui.result_line(step.name, "drifted", verdict.detail)
+        else:
+            ui.result_line(step.name, "failed", verdict.detail)
+
+    ctx.clear_secrets()
+    print()
+    return 0
+
+
+def cmd_plan(args: argparse.Namespace) -> int:
+    """Report what a run would do, changing nothing."""
+    cfg = _config_from_args(args)
+    ctx = _context(cfg, args.log)
+
+    ui.banner("Plan", "A preview. Nothing is changed by this command.")
+
+    plan = Plan(default_pipeline(), ctx)
+    plan.run(
+        dry_run=True,
+        on_result=lambda r: ui.result_line(r.step, r.status.value, r.detail),
+    )
+
+    counts = plan.summary()
+    ui.summary_box(
+        [
+            ("Already present", str(counts["skipped"])),
+            ("Would configure", str(counts["failed"])),
+            ("Needs attention", str(counts["drifted"])),
+        ]
+    )
+
+    ctx.clear_secrets()
+    return 0
+
+
+def cmd_apply(args: argparse.Namespace) -> int:
+    """Provision without prompting, using flags and the environment."""
+    cfg = _config_from_args(args)
+    ctx = _context(cfg, args.log)
+
+    ui.banner("Applying", "Only what is missing will be configured.")
+
+    if ctx.runner.needs_sudo_password():
+        ctx.runner.prompt_sudo()
+        print()
+
+    plan = Plan(default_pipeline(), ctx)
+    plan.run(
+        yes=args.yes,
+        on_result=lambda r: ui.result_line(r.step, r.status.value, r.detail, r.error),
+    )
+
+    counts = plan.summary()
+    ui.summary_box(
+        [
+            ("Configured", str(counts["applied"])),
+            ("Already present", str(counts["skipped"])),
+            ("Needs attention", str(counts["drifted"])),
+            ("Failed", str(counts["failed"] + counts["rolled_back"])),
+        ]
+    )
+
+    _write_doc(cfg, plan.results, args.doc)
+    ui.note(f"Audit log: {ctx.log.path}")
+
+    ctx.clear_secrets()
+    print()
+    return 1 if counts["failed"] + counts["rolled_back"] else 0
+
+
+def _restore_client(args: argparse.Namespace) -> "RestoreClient":
+    """Build a restore client, prompting for anything not supplied."""
+    from .restore import RestoreClient
+
+    account = os.environ.get("R2_ACCOUNT_ID", "") or ui.ask(
+        "R2 account ID",
+        "The Cloudflare account holding the backups.",
+    )
+    bucket = args.bucket or os.environ.get("R2_BUCKET", "") or ui.ask(
+        "Bucket",
+        "The bucket the backups were written to.",
+    )
+    access = os.environ.get("R2_ACCESS_KEY_ID", "") or ui.ask(
+        "R2 access key ID", "From R2 > Manage API Tokens.", secret=True
+    )
+    secret = os.environ.get("R2_SECRET_ACCESS_KEY", "") or ui.ask(
+        "R2 secret access key", "Shown once, when the token was created.", secret=True
+    )
+
+    return RestoreClient(
+        Runner(assume_root=(os.geteuid() == 0)),
+        bucket=bucket,
+        endpoint=f"https://{account}.r2.cloudflarestorage.com",
+        access_key=access,
+        secret_key=secret,
+    )
+
+
+def cmd_restore(args: argparse.Namespace) -> int:
+    """Restore volumes, databases and images from a backup."""
+    from .restore import RestoreError
+
+    ui.banner("Restore", "Choose a backup, then choose what to bring back.")
+
+    client = _restore_client(args)
+
+    ui.section("Available backups")
+    backups = client.list_backups()
+    if not backups:
+        ui.error("No backups found in that bucket.")
+        return 1
+
+    for index, backup in enumerate(backups, start=1):
+        marker = "*" if index == 1 else " "
+        print(
+            ui.paint(
+                f"   {marker} {index:>2}) {backup.stamp}  {backup.summary()}", "dim"
+            )
+        )
+
+    print()
+    ui.hint("The most recent is selected by default.")
+    answer = input(ui.paint("   > [1] ", "cyan")).strip()
+    try:
+        backup = backups[int(answer) - 1 if answer else 0]
+    except (ValueError, IndexError):
+        ui.error("Not a valid choice.")
+        return 1
+
+    if not backup.manifest:
+        ui.error(f"Backup {backup.stamp} has no manifest and cannot be read.")
+        return 1
+
+    ui.section(f"Restoring from {backup.stamp}")
+    ui.note(f"Taken on {backup.host} — {backup.summary()}")
+
+    workdir = "/tmp/forje-restore"
+    client._runner.run(f"mkdir -p {workdir}", check=False)
+
+    restored: list[str] = []
+    failed: list[str] = []
+
+    # Images first: services cannot start without them.
+    if backup.images:
+        chosen = ui.multiselect(
+            "Images",
+            "Locally built images. Without these, services have nothing to run.",
+            [(item["image"], item["image"]) for item in backup.images],
+        )
+        for item in backup.images:
+            if item["image"] not in chosen:
+                continue
+            try:
+                ui.result_line("image", "applied", client.restore_image(backup, item, workdir))
+                restored.append(str(item["image"]))
+            except Exception as exc:  # noqa: BLE001
+                ui.result_line("image", "failed", str(item["image"]), str(exc))
+                failed.append(str(item["image"]))
+
+    if backup.volumes:
+        chosen = ui.multiselect(
+            "Volumes",
+            "Application data. Existing contents are replaced, not merged.",
+            [
+                (
+                    item["volume"],
+                    f"{item['volume']:<28} {int(item.get('bytes', 0)) / 1048576:>8.1f} MB",
+                )
+                for item in backup.volumes
+            ],
+        )
+        for item in backup.volumes:
+            if item["volume"] not in chosen:
+                continue
+            try:
+                ui.result_line("volume", "applied", client.restore_volume(backup, item, workdir))
+                restored.append(str(item["volume"]))
+            except Exception as exc:  # noqa: BLE001
+                ui.result_line("volume", "failed", str(item["volume"]), str(exc))
+                failed.append(str(item["volume"]))
+
+    if backup.databases:
+        ui.section("Databases")
+        ui.hint("A database is loaded into a running container of the same engine.")
+        ui.hint("Start the database service first, then select it here.")
+
+        chosen = ui.multiselect(
+            "Databases",
+            "Dumps taken with each engine's own tool.",
+            [
+                (item["container"], f"{item['container']:<28} {item['engine']}")
+                for item in backup.databases
+            ],
+            default_all=False,
+        )
+        for item in backup.databases:
+            if item["container"] not in chosen:
+                continue
+            target = ui.ask(
+                f"Container for {item['container']}",
+                f"The running {item['engine']} container to load this dump into.",
+                default=str(item["container"]),
+            )
+            try:
+                ui.result_line(
+                    "database",
+                    "applied",
+                    client.restore_database(backup, item, workdir, target),
+                )
+                restored.append(str(item["container"]))
+            except (RestoreError, Exception) as exc:  # noqa: BLE001
+                ui.result_line("database", "failed", str(item["container"]), str(exc))
+                failed.append(str(item["container"]))
+
+    compose_path = client.fetch_compose(backup, os.getcwd())
+    if compose_path:
+        print()
+        ui.note(f"Recovery compose written: {compose_path}")
+        ui.hint("It describes every workload running when the backup was taken.")
+        ui.hint(f"Deploy it with: docker stack deploy -c {os.path.basename(compose_path)} <name>")
+
+    ui.summary_box(
+        [("Restored", str(len(restored))), ("Failed", str(len(failed)))]
+    )
+
+    client._runner.run(f"rm -rf {workdir}", check=False)
+    return 1 if failed else 0
+
+
+def cmd_compose(args: argparse.Namespace) -> int:
+    """Reconstruct a Compose file covering every workload on this machine."""
+    from .steps.backup import COMPOSE_SCRIPT
+
+    runner = Runner(assume_root=(os.geteuid() == 0))
+
+    script = "/tmp/forje-compose.sh"
+    Path(script).write_text(COMPOSE_SCRIPT, encoding="utf-8")
+
+    result = runner.run(f"sh {script}", sudo=True, check=False, timeout=300)
+    if not result.ok:
+        ui.error("Could not read the running services.")
+        return 1
+
+    destination = Path(args.out)
+    destination.write_text(result.out + "\n", encoding="utf-8")
+    runner.run(f"rm -f {script}", check=False)
+
+    services = result.out.count("\n    image: ")
+    ui.result_line("compose", "applied", f"{services} services written to {destination}")
+    ui.hint("Servers accumulate stacks deployed from files nobody kept.")
+    ui.hint("This one is read back out of Swarm, so it matches what is running.")
+    return 0
+
+
+def cmd_verify(args: argparse.Namespace) -> int:
+    """Check the audit log for tampering."""
+    log = HashLog(args.log)
+    intact, message = log.verify()
+    count = sum(1 for _ in log.entries())
+
+    if intact:
+        ui.result_line("audit log", "applied", f"{message}; {count} entries")
+        return 0
+
+    ui.result_line("audit log", "failed", message)
+    return 1
+
+
+def cmd_docs(args: argparse.Namespace) -> int:
+    """Regenerate the infrastructure document from the current state."""
+    cfg = _config_from_args(args)
+    ctx = _context(cfg, args.log)
+
+    results = []
+    plan = Plan(default_pipeline(), ctx)
+    results = plan.run(dry_run=True)
+
+    _write_doc(cfg, results, args.doc)
+    ctx.clear_secrets()
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="forje-cloud",
+        description="Set up a server: containers, HTTPS, backups and alerts.",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"forje-cloud {__version__}"
+    )
+
+    shared = argparse.ArgumentParser(add_help=False)
+    shared.add_argument("--project", help="short name used to label resources")
+    shared.add_argument("--hostname", help="name for this machine")
+    shared.add_argument("--deploy-user", help="non-root account that owns deployments")
+    shared.add_argument("--network", help="shared overlay network name")
+    shared.add_argument("--domain", help="domain to publish, already on Cloudflare")
+    shared.add_argument("--cf-token", help="Cloudflare API token (or CF_API_TOKEN)")
+    shared.add_argument(
+        "--close-ssh",
+        action="store_true",
+        help="close port 22 once the tunnel is confirmed working",
+    )
+    shared.add_argument("--log", default=DEFAULT_LOG, help="audit log path")
+    shared.add_argument("--doc", default=DEFAULT_DOC, help="generated document path")
+
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    setup = commands.add_parser(
+        "setup", parents=[shared], help="guided setup (recommended)"
+    )
+    setup.set_defaults(func=cmd_setup)
+
+    status = commands.add_parser(
+        "status", parents=[shared], help="show what this machine already has"
+    )
+    status.set_defaults(func=cmd_status)
+
+    plan = commands.add_parser(
+        "plan", parents=[shared], help="preview a run without changing anything"
+    )
+    plan.set_defaults(func=cmd_plan)
+
+    apply_cmd = commands.add_parser(
+        "apply", parents=[shared], help="provision without prompting"
+    )
+    apply_cmd.add_argument(
+        "--yes", action="store_true", help="authorize destructive steps"
+    )
+    apply_cmd.set_defaults(func=cmd_apply)
+
+    verify = commands.add_parser(
+        "verify", parents=[shared], help="check the audit log for tampering"
+    )
+    verify.set_defaults(func=cmd_verify)
+
+    docs = commands.add_parser(
+        "docs", parents=[shared], help="regenerate the infrastructure document"
+    )
+    docs.set_defaults(func=cmd_docs)
+
+    restore = commands.add_parser(
+        "restore", parents=[shared], help="restore volumes, databases and images"
+    )
+    restore.add_argument("--bucket", help="R2 bucket holding the backups")
+    restore.set_defaults(func=cmd_restore)
+
+    compose = commands.add_parser(
+        "compose",
+        parents=[shared],
+        help="reconstruct a Compose file for every workload running here",
+    )
+    compose.add_argument(
+        "--out", default="recovery-compose.yml", help="where to write the file"
+    )
+    compose.set_defaults(func=cmd_compose)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print()
+        ui.warn("Interrupted. Nothing further was changed.")
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

forje_cloud/core/__init__.py

@@ -0,0 +1,22 @@
+"""Execution core: the step contract, the runner, and the audit log."""
+
+from .context import Config, Context, Plan
+from .hashlog import HashLog, LogEntry
+from .runner import Result, Runner
+from .step import BaseStep, CheckResult, Status, Step, StepResult, run_step
+
+__all__ = [
+    "BaseStep",
+    "CheckResult",
+    "Config",
+    "Context",
+    "HashLog",
+    "LogEntry",
+    "Plan",
+    "Result",
+    "Runner",
+    "Status",
+    "Step",
+    "StepResult",
+    "run_step",
+]