gitfred 0.1.0__tar.gz

gitfred-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.pem
+kubeconfig*
+*.kubeconfig
+
+# Node / frontend
+node_modules/
+frontend/dist/
+frontend/.vite/
+*.local
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+
+# Build artifacts
+dist/
+build/
+.gitfred/
+
+# Sample validation repos (each is its own GitHub repo, staged here)
+/samples/*
+!/samples/VALIDATION.md

gitfred-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: gitfred
+Version: 0.1.0
+Summary: GitFred CLI — deploy GitHub repositories as live web apps from your terminal.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.15
+Description-Content-Type: text/markdown
+
+# gitfred
+
+The GitFred CLI: deploy GitHub repositories as live web apps at `https://<slug>.gitfred.com` from your terminal — or from an AI coding agent.
+
+```bash
+uv tool install gitfred        # or: pipx install gitfred
+gitfred login                  # browser-approval sign-in
+gitfred app create --repo you/your-repo --publish
+gitfred deploy 42 --follow
+```
+
+Every command supports `--json` for machine-readable output and uses meaningful exit codes (`0` ok, `2` usage, `3` auth, `4` not found, `5` quota, `6` deploy failed, `7` timeout), so agents can drive it non-interactively with `GITFRED_TOKEN`.
+
+Docs: https://app.gitfred.com/docs/cli

gitfred-0.1.0/README.md

@@ -0,0 +1,14 @@
+# gitfred
+
+The GitFred CLI: deploy GitHub repositories as live web apps at `https://<slug>.gitfred.com` from your terminal — or from an AI coding agent.
+
+```bash
+uv tool install gitfred        # or: pipx install gitfred
+gitfred login                  # browser-approval sign-in
+gitfred app create --repo you/your-repo --publish
+gitfred deploy 42 --follow
+```
+
+Every command supports `--json` for machine-readable output and uses meaningful exit codes (`0` ok, `2` usage, `3` auth, `4` not found, `5` quota, `6` deploy failed, `7` timeout), so agents can drive it non-interactively with `GITFRED_TOKEN`.
+
+Docs: https://app.gitfred.com/docs/cli

gitfred-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "gitfred"
+version = "0.1.0"
+description = "GitFred CLI — deploy GitHub repositories as live web apps from your terminal."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "typer>=0.15",
+    "httpx>=0.27",
+    "rich>=13.0",
+]
+
+[project.scripts]
+gitfred = "gitfred_cli.main:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gitfred_cli"]
+
+[dependency-groups]
+dev = ["pytest>=8.3"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+ignore = ["E501", "B008"]

gitfred-0.1.0/src/gitfred_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

gitfred-0.1.0/src/gitfred_cli/client.py

@@ -0,0 +1,130 @@
+"""HTTP client for the GitFred /api/v1 contract, plus the SSE log iterator."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from . import __version__
+from .output import EXIT_AUTH, EXIT_ERROR, EXIT_NOT_FOUND, EXIT_QUOTA
+
+
+class ApiError(Exception):
+    def __init__(self, status: int, message: str, detail: Any = None):
+        super().__init__(message)
+        self.status = status
+        self.detail = detail
+
+    @property
+    def exit_code(self) -> int:
+        if self.status in (401, 403):
+            return EXIT_AUTH
+        if self.status == 404:
+            return EXIT_NOT_FOUND
+        if self.status == 429:
+            return EXIT_QUOTA
+        return EXIT_ERROR
+
+
+class Client:
+    """Thin wrapper around httpx bound to ``{api_url}/api/v1`` with bearer auth."""
+
+    def __init__(
+        self,
+        api_url: str,
+        token: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        headers = {"User-Agent": f"gitfred-cli/{__version__}"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self._http = httpx.Client(
+            base_url=api_url.rstrip("/") + "/api/v1",
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: Any = None,
+        params: dict | None = None,
+        expect_json: bool = True,
+    ) -> Any:
+        try:
+            res = self._http.request(method, path, json=body, params=params)
+        except httpx.HTTPError as exc:
+            raise ApiError(0, f"cannot reach the GitFred API: {exc}") from exc
+        if res.status_code >= 400:
+            raise self._error(res)
+        if not expect_json or res.status_code == 204 or not res.content:
+            return None
+        return res.json()
+
+    def get(self, path: str, **kw: Any) -> Any:
+        return self.request("GET", path, **kw)
+
+    def post(self, path: str, **kw: Any) -> Any:
+        return self.request("POST", path, **kw)
+
+    def put(self, path: str, **kw: Any) -> Any:
+        return self.request("PUT", path, **kw)
+
+    def patch(self, path: str, **kw: Any) -> Any:
+        return self.request("PATCH", path, **kw)
+
+    def delete(self, path: str, **kw: Any) -> Any:
+        return self.request("DELETE", path, **kw)
+
+    def status_of(self, method: str, path: str, *, body: Any = None) -> int:
+        """Like request() but returns the status code, never raising on 4xx.
+        Used by the device-auth poll loop where 202 is a normal answer."""
+        res = self._http.request(method, path, json=body)
+        if res.status_code >= 400:
+            raise self._error(res)
+        return res.status_code
+
+    def sse(self, path: str, params: dict | None = None) -> Iterator[tuple[str, dict]]:
+        """Yield ``(event, data)`` pairs from an SSE endpoint until it closes."""
+        with self._http.stream(
+            "GET", path, params=params, timeout=httpx.Timeout(30.0, read=90.0)
+        ) as res:
+            if res.status_code >= 400:
+                res.read()
+                raise self._error(res)
+            event = "message"
+            data_lines: list[str] = []
+            for line in res.iter_lines():
+                if line.startswith("event:"):
+                    event = line[6:].strip()
+                elif line.startswith("data:"):
+                    data_lines.append(line[5:].strip())
+                elif line == "" and data_lines:
+                    try:
+                        yield event, json.loads("\n".join(data_lines))
+                    except ValueError:
+                        pass
+                    event = "message"
+                    data_lines = []
+
+    @staticmethod
+    def _error(res: httpx.Response) -> ApiError:
+        message = f"{res.status_code} {res.reason_phrase}"
+        detail: Any = None
+        try:
+            payload = res.json()
+            detail = payload.get("detail", payload)
+            if isinstance(detail, str):
+                message = detail
+            elif isinstance(detail, dict) and "message" in detail:
+                message = str(detail["message"])
+        except ValueError:
+            pass
+        return ApiError(res.status_code, message, detail)

gitfred-0.1.0/src/gitfred_cli/commands/addon.py

@@ -0,0 +1,38 @@
+"""addon enable — turn on platform addons for an app."""
+
+from __future__ import annotations
+
+import typer
+
+from ..helpers import handle_errors, resolve_app
+from ..output import emit
+from ..state import get_state
+
+addon_app = typer.Typer(help="Manage application addons (postgres, valkey, volume, object-storage).")
+
+_KINDS = {
+    "postgres": "enable_postgres",
+    "valkey": "enable_valkey",
+    "volume": "enable_volume",
+    "object-storage": "enable_object_storage",
+    "object_storage": "enable_object_storage",
+}
+
+
+@addon_app.command("enable")
+@handle_errors
+def enable(
+    app_ref: str = typer.Argument(..., metavar="APP"),
+    kind: str = typer.Argument(..., help="postgres | valkey | volume | object-storage"),
+) -> None:
+    """Enable an addon (provisioned on the next deploy)."""
+    field = _KINDS.get(kind.lower())
+    if field is None:
+        raise typer.BadParameter(f"unknown addon {kind!r} (expected one of: {', '.join(sorted(set(_KINDS) - {'object_storage'}))})")
+    data = resolve_app(app_ref)
+    updated = get_state().client.patch(f"/applications/{data['id']}", body={field: True})
+    emit(
+        updated,
+        f"Enabled [bold]{kind}[/bold] on {updated['name']} — redeploy to provision: "
+        f"gitfred deploy {updated['id']}",
+    )

gitfred-0.1.0/src/gitfred_cli/commands/app.py

@@ -0,0 +1,149 @@
+"""app create / list / show / delete."""
+
+from __future__ import annotations
+
+import sys
+
+import typer
+from rich.table import Table
+
+from ..helpers import handle_errors, resolve_app, resolve_repository
+from ..output import EXIT_ERROR, console, emit, fail, json_mode
+from ..state import get_state
+
+app_app = typer.Typer(help="Manage applications.")
+
+ADDON_FLAGS = ("postgres", "valkey", "volume", "object_storage")
+
+
+def _parse_env(pairs: list[str]) -> dict[str, str]:
+    env: dict[str, str] = {}
+    for pair in pairs:
+        if "=" not in pair:
+            raise fail(f"--env expects KEY=VALUE, got {pair!r}", 2)
+        key, value = pair.split("=", 1)
+        env[key] = value
+    return env
+
+
+@app_app.command("create")
+@handle_errors
+def create(
+    repo: str = typer.Option(..., "--repo", help="owner/name or a connected repository id."),
+    name: str | None = typer.Option(None, "--name", help="Application name (default: repo name)."),
+    branch: str | None = typer.Option(None, "--branch"),
+    port: int | None = typer.Option(None, "--port"),
+    health_path: str | None = typer.Option(None, "--health-path"),
+    postgres: bool = typer.Option(False, "--postgres", help="Enable the PostgreSQL addon."),
+    valkey: bool = typer.Option(False, "--valkey", help="Enable the Valkey (Redis) addon."),
+    volume: bool = typer.Option(False, "--volume", help="Enable the persistent-volume addon."),
+    object_storage: bool = typer.Option(
+        False, "--object-storage", help="Enable the S3 object-storage addon."
+    ),
+    env: list[str] = typer.Option([], "--env", help="KEY=VALUE (repeatable)."),
+    auto_deploy: bool = typer.Option(False, "--auto-deploy", help="Republish on every push."),
+    no_detect: bool = typer.Option(
+        False, "--no-detect", help="Skip repo-type detection and its suggested defaults."
+    ),
+    publish: bool = typer.Option(False, "--publish", help="Trigger the first deploy immediately."),
+) -> None:
+    """Create an application from a repository (detection fills in sensible defaults)."""
+    client = get_state().client
+    repository = resolve_repository(repo)
+
+    detection = None
+    if not no_detect:
+        detection = client.post(
+            "/applications/detect",
+            body={"repository_id": repository["id"], "branch": branch},
+        )
+        if not detection["deployable"]:
+            raise fail(
+                f"{repository['full_name']} is not deployable: "
+                f"{detection.get('reason') or detection['label']}",
+                EXIT_ERROR,
+                detail=detection,
+            )
+        if not json_mode():
+            console.print(
+                f"Detected [bold]{detection['label']}[/bold]"
+                + (f" · {detection['note']}" if detection.get("note") else "")
+            )
+
+    suggestions = (detection or {}).get("suggestions", {})
+    body = {
+        "repository_id": repository["id"],
+        "name": name or repository["name"],
+        "branch": branch,
+        "port": port if port is not None else suggestions.get("port", 8080),
+        "health_path": health_path
+        if health_path is not None
+        else suggestions.get("health_path", "/"),
+        "release_command": suggestions.get("release_command"),
+        "auto_deploy": auto_deploy,
+        "enable_postgres": postgres or suggestions.get("enable_postgres", False),
+        "enable_valkey": valkey or suggestions.get("enable_valkey", False),
+        "enable_volume": volume,
+        "enable_object_storage": object_storage
+        or suggestions.get("enable_object_storage", False),
+        "env": _parse_env(env),
+    }
+    created = client.post("/applications", body=body)
+
+    deployment = None
+    if publish:
+        deployment = client.post(f"/applications/{created['id']}/publish")
+
+    emit(
+        {"application": created, "deployment": deployment, "detection": detection},
+        f"Created application [bold]{created['name']}[/bold] (id {created['id']})"
+        + (f"\nDeployment {deployment['id']} queued — follow with: gitfred logs {deployment['id']} --follow"
+           if deployment else
+           f"\nDeploy it with: gitfred deploy {created['id']}"),
+    )
+
+
+@app_app.command("list")
+@handle_errors
+def list_apps() -> None:
+    """List your applications."""
+    apps = get_state().client.get("/applications")
+    emit(apps)
+    if not json_mode():
+        table = Table(header_style="bold")
+        for col in ("id", "name", "status", "url", "last deployed"):
+            table.add_column(col)
+        for a in apps:
+            table.add_row(
+                str(a["id"]), a["name"], a["status"], a.get("url") or "-",
+                a.get("last_deployed_at") or "never",
+            )
+        console.print(table)
+
+
+@app_app.command("show")
+@handle_errors
+def show(app_ref: str = typer.Argument(..., metavar="APP", help="Application id, slug, or name.")) -> None:
+    """Show one application in full."""
+    data = resolve_app(app_ref)
+    emit(data)
+    if not json_mode():
+        console.print_json(data=data)
+
+
+@app_app.command("delete")
+@handle_errors
+def delete(
+    app_ref: str = typer.Argument(..., metavar="APP"),
+    yes: bool = typer.Option(False, "--yes", help="Skip the confirmation prompt."),
+) -> None:
+    """Delete an application and tear down everything it provisioned."""
+    data = resolve_app(app_ref)
+    if not yes:
+        if not sys.stdin.isatty():
+            raise fail("refusing to delete without --yes in non-interactive mode", 2)
+        typer.confirm(
+            f"Delete '{data['name']}' (id {data['id']}) and all its resources?", abort=True
+        )
+    get_state().client.delete(f"/applications/{data['id']}")
+    emit({"status": "deleted", "id": data["id"]}, f"Deleted application {data['id']}.")

gitfred-0.1.0/src/gitfred_cli/commands/auth.py

@@ -0,0 +1,91 @@
+"""login / logout / whoami."""
+
+from __future__ import annotations
+
+import socket
+import time
+import webbrowser
+
+import typer
+
+from ..client import ApiError, Client
+from ..config import load_config, save_config
+from ..helpers import handle_errors
+from ..output import EXIT_AUTH, EXIT_TIMEOUT, console, emit, fail, json_mode
+from ..state import get_state
+
+
+@handle_errors
+def login(
+    token: str | None = typer.Option(
+        None, "--token", help="Use an existing API token instead of the browser flow."
+    ),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Print the approval URL instead of opening a browser."
+    ),
+) -> None:
+    """Sign in to GitFred (opens your browser to approve this device)."""
+    state = get_state()
+    if token is None and not json_mode():
+        token = _device_flow(state.anon_client, open_browser=not no_browser)
+    elif token is None:
+        # --json implies non-interactive: a polling browser flow makes no sense there.
+        raise fail("in --json mode pass --token or set GITFRED_TOKEN", EXIT_AUTH)
+
+    me = Client(state.api_url, token).get("/auth/me")
+    config = load_config()
+    config["token"] = token
+    config["api_url"] = state.api_url
+    save_config(config)
+    emit(me, f"Signed in as [bold]@{me['login']}[/bold]")
+
+
+def _device_flow(client: Client, open_browser: bool) -> str:
+    started = client.post(
+        "/auth/device",
+        body={"client_name": "gitfred-cli", "client_host": socket.gethostname()},
+    )
+    url = started["verification_url"]
+    console.print(f"Approve this device in your browser:\n\n  [bold cyan]{url}[/bold cyan]\n")
+    if open_browser:
+        webbrowser.open(url)
+    deadline = time.monotonic() + started["expires_in"]
+    interval = started.get("interval", 2)
+    console.print("Waiting for approval…")
+    while time.monotonic() < deadline:
+        try:
+            result = client.post("/auth/device/poll", body={"device_code": started["device_code"]})
+        except ApiError as exc:
+            if exc.status == 403:
+                raise fail("authorization was denied in the browser", EXIT_AUTH) from exc
+            raise
+        if result is not None:
+            return result["token"]
+        time.sleep(interval)
+    raise fail("login timed out — run `gitfred login` again", EXIT_TIMEOUT)
+
+
+@handle_errors
+def logout() -> None:
+    """Sign out: revoke this device's token and remove it from the local config."""
+    config = load_config()
+    token = config.pop("token", None)
+    if token:
+        # Best-effort server-side revocation (the PAT can revoke itself).
+        try:
+            client = get_state().client
+            for t in client.get("/tokens"):
+                if token.startswith(t["token_prefix"]):
+                    client.delete(f"/tokens/{t['id']}")
+                    break
+        except ApiError:
+            pass
+    save_config(config)
+    emit({"status": "logged_out"}, "Signed out.")
+
+
+@handle_errors
+def whoami() -> None:
+    """Show the signed-in user."""
+    me = get_state().client.get("/auth/me")
+    emit(me, f"@{me['login']} ({me.get('name') or 'no name'}) · user id {me['id']}")

gitfred-0.1.0/src/gitfred_cli/commands/deploy.py

@@ -0,0 +1,142 @@
+"""deploy / logs / open — the publish-and-watch path."""
+
+from __future__ import annotations
+
+import time
+import webbrowser
+
+import typer
+
+from ..client import ApiError
+from ..helpers import handle_errors, resolve_app
+from ..output import (
+    EXIT_DEPLOY_FAILED,
+    EXIT_OK,
+    EXIT_TIMEOUT,
+    console,
+    emit,
+    fail,
+    json_mode,
+)
+from ..state import get_state
+
+_TERMINAL = {"succeeded", "failed", "canceled"}
+
+
+@handle_errors
+def deploy(
+    app_ref: str = typer.Argument(..., metavar="APP", help="Application id, slug, or name."),
+    follow: bool = typer.Option(
+        True, "--follow/--no-follow", help="Stream build/deploy logs until the deploy finishes."
+    ),
+    timeout: int = typer.Option(1800, "--timeout", help="Max seconds to wait with --follow."),
+) -> None:
+    """Publish an application (build + deploy the latest commit)."""
+    client = get_state().client
+    data = resolve_app(app_ref)
+    deployment = client.post(f"/applications/{data['id']}/publish")
+    if not follow:
+        emit(
+            deployment,
+            f"Deployment {deployment['id']} queued — follow with: "
+            f"gitfred logs {deployment['id']} --follow",
+        )
+        return
+    if not json_mode():
+        console.print(f"Deployment [bold]{deployment['id']}[/bold] queued, streaming logs…")
+    status = _follow_logs(deployment["id"], timeout)
+    final = client.get(f"/deployments/{deployment['id']}")
+    emit(final, None)
+    _finish(final, status)
+
+
+@handle_errors
+def logs(
+    deployment_id: int = typer.Argument(..., help="Deployment id."),
+    follow: bool = typer.Option(False, "--follow", help="Stream until the deploy finishes."),
+    after: int = typer.Option(0, "--after", help="Only lines with seq > AFTER."),
+    timeout: int = typer.Option(1800, "--timeout", help="Max seconds to wait with --follow."),
+) -> None:
+    """Print (or stream) the logs of a deployment."""
+    client = get_state().client
+    if not follow:
+        lines = client.get(f"/deployments/{deployment_id}/logs", params={"after": after})
+        emit(lines)
+        if not json_mode():
+            for entry in lines:
+                _print_line(entry)
+        return
+    status = _follow_logs(deployment_id, timeout, after=after)
+    final = client.get(f"/deployments/{deployment_id}")
+    emit(final, None)
+    _finish(final, status)
+
+
+@handle_errors
+def open_app(app_ref: str = typer.Argument(..., metavar="APP")) -> None:
+    """Open the application's live URL in your browser."""
+    data = resolve_app(app_ref)
+    url = data.get("url")
+    if not url:
+        raise fail("application has no URL yet — deploy it first", 4)
+    emit({"url": url}, f"Opening [bold cyan]{url}[/bold cyan]")
+    if not json_mode():
+        webbrowser.open(url)
+
+
+def _print_line(entry: dict) -> None:
+    stage = entry.get("stage", "")
+    line = entry.get("line", "")
+    if entry.get("stream") == "stderr":
+        console.print(f"[dim]{stage:>10}[/dim] [red]{line}[/red]", highlight=False)
+    else:
+        console.print(f"[dim]{stage:>10}[/dim] {line}", highlight=False)
+
+
+def _follow_logs(deployment_id: int, timeout: int, after: int = 0) -> str | None:
+    """Stream logs via SSE (falling back to polling) until terminal or timeout.
+
+    Returns the final status when the stream reported it, else None.
+    """
+    client = get_state().client
+    deadline = time.monotonic() + timeout
+    last_seq = after
+    while time.monotonic() < deadline:
+        try:
+            for event, data in client.sse(
+                f"/deployments/{deployment_id}/logs/stream", params={"after": last_seq}
+            ):
+                if event == "log":
+                    last_seq = max(last_seq, data.get("seq", last_seq))
+                    if not json_mode():
+                        _print_line(data)
+                elif event == "done":
+                    return data.get("status")
+                if time.monotonic() > deadline:
+                    raise fail("timed out waiting for the deployment", EXIT_TIMEOUT)
+            # Stream closed without a `done` event (proxy idle cut) — check and resume.
+        except ApiError:
+            # SSE unavailable (old proxy, flaky link) — fall back to one polling round.
+            time.sleep(2)
+            entries = client.get(
+                f"/deployments/{deployment_id}/logs", params={"after": last_seq}
+            )
+            for entry in entries:
+                last_seq = max(last_seq, entry["seq"])
+                if not json_mode():
+                    _print_line(entry)
+        status = client.get(f"/deployments/{deployment_id}")["status"]
+        if status in _TERMINAL:
+            return status
+    raise fail("timed out waiting for the deployment", EXIT_TIMEOUT)
+
+
+def _finish(final: dict, status: str | None) -> None:
+    status = status or final.get("status")
+    if status == "succeeded":
+        if not json_mode():
+            console.print(f"\n[green]✓ deployed[/green] {final.get('url') or ''}")
+        raise SystemExit(EXIT_OK)
+    if not json_mode():
+        console.print(f"\n[red]✗ deployment {status}[/red] {final.get('error') or ''}")
+    raise SystemExit(EXIT_DEPLOY_FAILED)