biller-cli 0.1.0__py3-none-any.whl

biller_cli/commands/init.py

@@ -0,0 +1,210 @@
+import os
+import shutil
+import typer
+import yaml
+import requests
+from pathlib import Path
+from rich.console import Console
+from rich.prompt import Prompt, Confirm
+
+# Import our custom utilities
+from biller_cli.utils.preflight import run_preflight, RuntimeMode
+from biller_cli.utils.secrets import write_env_file
+
+app = typer.Typer(help="Scaffold a new project.")
+console = Console()
+
+# Fallback registry URL (we will build the real FastAPI registry in Phase 2)
+REGISTRY_URL = os.getenv("BILLER_REGISTRY_URL", "https://biller-registry-production.up.railway.app")
+
+def _fetch_bous() -> list[dict]:
+    """Fetch available BOUs from the central registry."""
+    try:
+        resp = requests.get(f"{REGISTRY_URL}/api/v1/bous", timeout=5)
+        resp.raise_for_status()
+        return resp.json().get("bous", [])
+    except requests.RequestException:
+        console.print(f"[yellow]⚠ Cannot reach registry at {REGISTRY_URL}[/yellow]")
+        console.print("[dim]Using fallback local BOU list for offline development.[/dim]")
+        return [
+            {
+                "id": "nsdl",
+                "name": "NSDL Payments Bank",
+                "auth_header": "X-NSDL-Auth",
+                "environment": {
+                    "dev": "https://uat-bou.nsdlbank.com/bbps/callback",
+                    "prod": "https://bou.nsdlbank.com/bbps/callback"
+                }
+            },
+            {
+                "id": "fino",
+                "name": "Fino Payments Bank",
+                "auth_header": "X-Fino-Auth",
+                "environment": {
+                    "dev": "https://uat-bou.finopayments.com/bbps/callback",
+                    "prod": "https://bou.finopayments.com/bbps/callback"
+                }
+            }
+        ]
+
+def _select_bou(bous: list[dict], environment: str) -> dict:
+    """Show a numbered list of BOUs and let the developer pick one."""
+    console.print("\n[bold]Select your target BOU:[/bold]")
+    for i, bou in enumerate(bous, 1):
+        console.print(f"  {i}. {bou['name']}")
+
+    while True:
+        raw = Prompt.ask(">", default="1")
+        try:
+            idx = int(raw) - 1
+            if 0 <= idx < len(bous):
+                selected = bous[idx]
+                callback_url = selected["environment"].get(
+                    environment,
+                    selected["environment"].get("dev", "URL_NOT_FOUND")
+                )
+                console.print(
+                    f"\n[green]✓[/green] {selected['name']} selected\n"
+                    f"  Callback URL ({environment}): [dim]{callback_url}[/dim]\n"
+                )
+                return {**selected, "resolved_callback_url": callback_url}
+        except (ValueError, IndexError):
+            pass
+        console.print("[red]Invalid selection. Enter a valid number from the list.[/red]")
+
+@app.callback(invoke_without_command=True)
+def init_project(
+    output_dir: Path = typer.Option(Path("."), "--output", "-o", help="Directory to create the project in."),
+):
+    """Scaffold a new Biller Integrator project interactively."""
+    runtime = run_preflight()
+
+    console.rule("[bold blue]Biller Integrator Setup Wizard[/bold blue]")
+
+    if runtime == RuntimeMode.NATIVE:
+        console.print("[yellow]Notice: Docker not found. Project will be configured for native Maven mode.[/yellow]\n")
+
+    # 1. Base Prompts
+    biller_name = Prompt.ask("Biller Name (e.g., electricity-board)")
+    environment = Prompt.ask("Environment", choices=["dev", "staging", "prod"], default="dev")
+
+    # 1b. Runtime Selection
+    runtime_choice = Prompt.ask("Runtime mode", choices=["docker", "native"], default="native")
+
+    # 2. BOU Selection
+    console.print("\n[dim]Fetching available BOUs from registry...[/dim]")
+    bous = _fetch_bous()
+    if not bous:
+        console.print("[red]Error: No BOUs available. Cannot proceed.[/red]")
+        raise typer.Exit(1)
+    
+    selected_bou = _select_bou(bous, environment)
+
+    # 3. BBPS Specifics & Optional Secrets
+    biller_id = Prompt.ask(
+        "Biller ID [dim](Press Enter to set later — assigned by BBPS after registration)[/dim]",
+        default="PENDING",
+    )
+
+    console.print("\n[dim]Sensitive credentials (can be left blank for Day 0 setup):[/dim]")
+    bou_auth_token = Prompt.ask("BOU Auth Token [dim](Press Enter to skip)[/dim]", password=True, default="")
+    bbps_api_key = Prompt.ask("BBPS API Key [dim](Press Enter to skip)[/dim]", password=True, default="")
+
+    secrets = {
+        "bou_auth_token": bou_auth_token if bou_auth_token else "PENDING",
+        "bbps_api_key": bbps_api_key if bbps_api_key else "PENDING",
+        "bbps_cert_path": "CERT_PATH_PLACEHOLDER"  # Replaced after target_path is resolved
+    }
+
+    # 4. Overwrite Protection
+    target_path = output_dir / biller_name
+    if target_path.exists():
+        if not Confirm.ask(f"[yellow]Directory '{target_path}' already exists. Overwrite contents?[/yellow]", default=False):
+            console.print("Aborting.")
+            raise typer.Exit(0)
+    else:
+        target_path.mkdir(parents=True)
+    secrets["bbps_cert_path"] = str(target_path.absolute() / "certs" / "ousigner.p12")
+
+    # 5. Scaffolding Java Template
+    template_dir = Path(__file__).parent.parent / "templates"
+    if not template_dir.exists():
+         console.print(f"[red]Fatal: Template directory not found at {template_dir}[/red]")
+         raise typer.Exit(1)
+
+    console.print(f"\n[dim]Copying template to {target_path}...[/dim]")
+    shutil.copytree(template_dir, target_path, dirs_exist_ok=True)
+
+    # 6. Scaffold Certs Directory & Gitignore
+    certs_dir = target_path / "certs"
+    certs_dir.mkdir(exist_ok=True)
+    (certs_dir / ".gitignore").write_text("# Never commit certificates\n*.p12\n*.pfx\n")
+    console.print(f"[dim]Created isolated certs/ directory.[/dim]")
+
+    # 7. Generate docker-compose.yml dynamically
+    compose_content = f"""services:
+  biller-middleware:
+    build: .
+    env_file:
+      - .env.biller
+    environment:
+      - BILLER_NAME={biller_name}
+      - BILLER_ID={biller_id}
+      - BILLER_ENV={environment}
+      - BBPS_CERT_PATH=/app/certs/ousigner.p12
+    ports:
+      - "8080:8080"
+    volumes:
+      - ./certs:/app/certs:ro
+"""
+    (target_path / "docker-compose.yml").write_text(compose_content)
+
+    # 8. Generate basic Dockerfile for the User Layer
+    dockerfile_content = """FROM eclipse-temurin:17-jdk-alpine
+VOLUME /tmp
+COPY biller-user-layer/target/biller-user-layer-*.jar app.jar
+ENTRYPOINT ["java","-jar","/app.jar"]
+"""
+    (target_path / "Dockerfile").write_text(dockerfile_content)
+
+    # 9. Write biller.yaml config
+    biller_yaml_data = {
+        "version": "1",
+        "biller": {
+            "name": biller_name,
+            "id": biller_id,
+            "environment": environment,
+        },
+        "bou": {
+            "id": selected_bou["id"],
+            "name": selected_bou["name"],
+            "callback_url": selected_bou["resolved_callback_url"],
+            "auth_header": selected_bou["auth_header"],
+        },
+        "core": {"version": "1.0.1"},
+        "runtime": runtime_choice,
+    }
+    
+    yaml_path = target_path / "biller.yaml"
+    yaml_path.write_text(yaml.dump(biller_yaml_data, default_flow_style=False, sort_keys=False))
+
+    # 10. Manage Secrets
+    write_env_file(target_path, secrets)
+
+    # 11. Interpolate POM Pin
+    pom_path = target_path / "biller-user-layer" / "pom.xml"
+    if pom_path.exists():
+        pom_content = pom_path.read_text().replace("{{BILLER_CORE_VERSION}}", "1.0.1")
+        pom_path.write_text(pom_content)
+
+    # Wrap up UX
+    console.print(f"\n[bold green]✓ Project '{biller_name}' successfully scaffolded![/bold green]")
+    
+    if biller_id == "PENDING" or not bou_auth_token:
+        console.print("\n[yellow]Day 0 Notice:[/yellow] Your Biller ID and/or secrets are PENDING.")
+        console.print(f"When ready, drop your certificate into [bold]./{target_path}/certs/ousigner.p12[/bold]")
+        console.print("Then update your credentials via:")
+        console.print(f"  [bold]cd {target_path} && biller-cli config set biller.id YOUR_ID[/bold]\n")
+        
+    console.print(f"Detected Runtime: [bold]{runtime.value}[/bold]")
+    console.print(f"Next step: [bold]cd {target_path} && biller-cli up[/bold]")

biller_cli/commands/up.py

@@ -0,0 +1,138 @@
+import os
+import time
+import subprocess
+import yaml
+import psutil
+import typer
+import requests
+from pathlib import Path
+from rich.console import Console
+
+from biller_cli.utils.preflight import run_preflight, RuntimeMode
+
+app = typer.Typer(help="Start the Biller middleware stack.")
+console = Console()
+
+PID_FILE_NAME = ".biller/biller.pid"
+LOG_FILE_NAME = ".biller/biller.log"
+
+def _wait_for_health(timeout: int = 90):
+    """Polls the Spring Boot actuator endpoint to ensure the service is up."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        try:
+            r = requests.get("http://localhost:8111/health", timeout=2)
+            if r.status_code == 200:
+                console.print("[green]✓ Biller stack is running and healthy.[/green]")
+                console.print("Health check: [bold]curl http://localhost:8111/health[/bold]")
+                return
+        except requests.RequestException:
+            pass
+        time.sleep(2)
+    
+    console.print("[yellow]⚠ Stack may still be starting, or health check timed out.[/yellow]")
+    console.print("Check manually: [bold]curl http://localhost:8111/health[/bold]")
+
+def _up_docker(project_dir: Path, detach: bool):
+    """Orchestrates the Docker Compose stack."""
+    compose_file = project_dir / "docker-compose.yml"
+    if not compose_file.exists():
+        console.print("[red]Fatal: docker-compose.yml not found.[/red]")
+        raise typer.Exit(1)
+
+    cmd = ["docker", "compose", "-f", str(compose_file), "up", "--build"]
+    if detach:
+        cmd.append("-d")
+
+    console.print("[blue]🚀 Starting Biller stack (Docker Mode)...[/blue]")
+    result = subprocess.run(cmd)
+
+    if result.returncode != 0:
+        console.print("[red]Docker Compose failed to start.[/red]")
+        console.print("Run without detach mode for full logs: [bold]biller-cli up --no-detach[/bold]")
+        raise typer.Exit(result.returncode)
+
+    if detach:
+        _wait_for_health(timeout=30)
+
+def _up_native(project_dir: Path, detach: bool):
+    """Starts the application natively via Maven with PID management."""
+    biller_dir = project_dir / ".biller"
+    biller_dir.mkdir(exist_ok=True)
+    
+    pid_file = project_dir / PID_FILE_NAME
+    log_file = project_dir / LOG_FILE_NAME
+
+    # Guard against duplicate starts
+    if pid_file.exists():
+        try:
+            existing_pid = int(pid_file.read_text().strip())
+            if psutil.pid_exists(existing_pid):
+                console.print(f"[yellow]Stack is already running (PID {existing_pid}).[/yellow]")
+                console.print("Run [bold]biller-cli down[/bold] first to restart.")
+                raise typer.Exit(0)
+            else:
+                pid_file.unlink() # Stale PID, clean it up
+        except ValueError:
+            pid_file.unlink()
+
+    # Load secrets into process environment
+    env = os.environ.copy()
+    env_file = project_dir / ".env.biller"
+    if env_file.exists():
+        for line in env_file.read_text().splitlines():
+            if "=" in line and not line.startswith("#"):
+                k, v = line.split("=", 1)
+                env[k.strip()] = v.strip()
+
+    cmd = ["mvn", "spring-boot:run"]
+    console.print("[blue]🚀 Starting Biller stack (Native Maven Mode)...[/blue]")
+    console.print("[dim]Note: First run compiles the project and takes ~30 seconds.[/dim]")
+
+    if detach:
+        with open(log_file, "w") as lf:
+            process = subprocess.Popen(
+                cmd,
+                cwd=str(project_dir / "biller-user-layer"),
+                env=env,
+                stdout=lf,
+                stderr=lf,
+            )
+        pid_file.write_text(str(process.pid))
+        console.print(f"[dim]Process running in background (PID {process.pid}). Logs stored in {log_file}[/dim]")
+        _wait_for_health(timeout=90)
+    else:
+        try:
+            subprocess.run(cmd, cwd=str(project_dir / "biller-user-layer"), env=env)
+        except KeyboardInterrupt:
+            console.print("\n[yellow]Shutting down native process...[/yellow]")
+
+@app.callback(invoke_without_command=True)
+def up(
+    project_dir: Path = typer.Option(Path("."), "--dir", "-d", help="Project directory"),
+    detach: bool = typer.Option(True, "--detach/--no-detach", help="Run in background"),
+    runtime_override: str = typer.Option(None, "--runtime", help="Force 'docker' or 'native'"),
+):
+    """Start the Biller middleware stack (Auto-detects Docker vs Native)."""
+    run_preflight(require_runtime=True)
+
+    biller_yaml_path = project_dir / "biller.yaml"
+    if not biller_yaml_path.exists():
+        console.print(f"[red]No biller.yaml found in {project_dir}. Run 'biller-cli init' first.[/red]")
+        raise typer.Exit(1)
+
+    try:
+        config = yaml.safe_load(biller_yaml_path.read_text())
+    except Exception as e:
+        console.print(f"[red]Failed to parse biller.yaml: {e}[/red]")
+        raise typer.Exit(1)
+
+    effective_runtime = runtime_override or config.get("runtime", "docker")
+
+    if effective_runtime == "docker":
+        _up_docker(project_dir, detach)
+    elif effective_runtime == "native":
+        _up_native(project_dir, detach)
+    else:
+        console.print(f"[red]Unknown runtime '{effective_runtime}' in biller.yaml. Use 'docker' or 'native'.[/red]")
+        raise typer.Exit(1)

biller_cli/commands/upgrade.py

@@ -0,0 +1,271 @@
+"""
+biller-cli upgrade
+
+Fetches migration rules from the registry, applies automatable ones,
+runs a sandbox compile-check, then updates the version pin in
+biller.yaml and pom.xml.
+
+SCOPE OF SANDBOX:
+  Runs `mvn clean package -pl biller-user-layer --also-make`.
+  This is a COMPILE-ONLY gate. It does NOT prove the app boots,
+  that the DB schema is compatible, or that the cert path resolves.
+  A green sandbox means the code compiles against the new biller-core.
+  Boot correctness must be verified by running biller-cli up after upgrade.
+"""
+
+import subprocess
+import sys
+import shutil
+import typer
+import requests
+import yaml
+from pathlib import Path
+from rich.console import Console
+from packaging.version import Version
+
+from biller_cli.utils.version_pin import get_version_pin, set_version_pin
+
+app = typer.Typer(help="Upgrade biller-core to a newer version.")
+console = Console()
+
+REGISTRY_URL_DEFAULT = "https://biller-registry-production.up.railway.app"
+
+
+def _get_registry_url(project_dir: Path) -> str:
+    """Read BILLER_REGISTRY_URL from environment, then .env.biller, fallback to default."""
+    # Environment variable takes highest priority
+    import os
+    env_var = os.environ.get("BILLER_REGISTRY_URL")
+    if env_var:
+        return env_var
+    # Then .env.biller file
+    env_file = project_dir / ".env.biller"
+    if env_file.exists():
+        for line in env_file.read_text().splitlines():
+            if line.startswith("BILLER_REGISTRY_URL="):
+                return line.split("=", 1)[1].strip()
+    return REGISTRY_URL_DEFAULT
+
+
+def _fetch_migration_path(registry_url: str, from_version: str, to_version: str) -> dict:
+    """Fetch ordered migration rules from the registry."""
+    url = f"{registry_url}/api/v1/manifest/migration-path"
+    try:
+        resp = requests.get(url, params={"from_version": from_version, "to_version": to_version}, timeout=10)
+    except requests.ConnectionError:
+        console.print(f"[red]Cannot reach registry at {registry_url}.[/red]")
+        console.print("Check your network or set BILLER_REGISTRY_URL in .env.biller.")
+        raise typer.Exit(1)
+
+    if resp.status_code == 400:
+        console.print(f"[red]{resp.json().get('detail', 'Bad request')}[/red]")
+        raise typer.Exit(1)
+    if resp.status_code == 404:
+        console.print(f"[red]Version not found in registry: {resp.json().get('detail')}[/red]")
+        raise typer.Exit(1)
+    if resp.status_code != 200:
+        console.print(f"[red]Registry error {resp.status_code}: {resp.text}[/red]")
+        raise typer.Exit(1)
+
+    return resp.json()
+
+
+def _fetch_latest_version(registry_url: str) -> str:
+    """Fetch the latest published biller-core version from the registry."""
+    try:
+        resp = requests.get(f"{registry_url}/api/v1/manifest/latest", timeout=10)
+        resp.raise_for_status()
+        return resp.json()["version"]
+    except Exception as e:
+        console.print(f"[red]Failed to fetch latest version from registry: {e}[/red]")
+        raise typer.Exit(1)
+
+
+def _apply_config_rename_rule(project_dir: Path, rule: dict) -> None:
+    """Apply a config_rename migration rule to biller.yaml."""
+    old_key = rule.get("old_key")
+    new_key = rule.get("new_key")
+    if not old_key or not new_key:
+        return
+
+    bp = project_dir / "biller.yaml"
+    cfg = yaml.safe_load(bp.read_text())
+
+    # Support dot-notation keys like "core.timeout"
+    def get_nested(d, keys):
+        for k in keys:
+            if not isinstance(d, dict) or k not in d:
+                return None, False
+            d = d[k]
+        return d, True
+
+    def set_nested(d, keys, value):
+        for k in keys[:-1]:
+            d = d.setdefault(k, {})
+        d[keys[-1]] = value
+
+    def del_nested(d, keys):
+        for k in keys[:-1]:
+            if k not in d:
+                return
+            d = d[k]
+        d.pop(keys[-1], None)
+
+    old_parts = old_key.split(".")
+    new_parts = new_key.split(".")
+
+    value, found = get_nested(cfg, old_parts)
+    if found:
+        set_nested(cfg, new_parts, value)
+        del_nested(cfg, old_parts)
+        bp.write_text(yaml.dump(cfg, default_flow_style=False, sort_keys=False))
+        console.print(f"  [green]✓[/green] Renamed config key [bold]{old_key}[/bold] → [bold]{new_key}[/bold]")
+    else:
+        console.print(f"  [yellow]⚠[/yellow] Config key [bold]{old_key}[/bold] not found — skipping rename")
+
+
+def _run_sandbox_build(project_dir: Path, target_version: str) -> bool:
+    """
+    Create a Git worktree sandbox, pin the new version, and attempt compilation.
+    Returns True if build passes, False if it fails.
+    Always cleans up the worktree regardless of outcome.
+
+    COMPILE-ONLY: Does not test boot, DB connectivity, or cert resolution.
+    """
+    worktree_path = project_dir / ".biller" / f"sandbox-{target_version}"
+
+    # Require a git repo for worktree support
+    git_dir = project_dir / ".git"
+    if not git_dir.exists():
+        console.print("[yellow]⚠ Not a git repository — skipping sandbox build.[/yellow]")
+        console.print("[dim]Sandbox compile-check requires git. Proceeding without it.[/dim]")
+        return True
+
+    # Check Maven is available
+    if not shutil.which("mvn"):
+        console.print("[yellow]⚠ Maven (mvn) not found on PATH — skipping sandbox build.[/yellow]")
+        return True
+
+    try:
+        console.print(f"[dim]Creating sandbox worktree at {worktree_path}...[/dim]")
+        result = subprocess.run(
+            ["git", "worktree", "add", str(worktree_path), "HEAD"],
+            cwd=str(project_dir),
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            console.print(f"[yellow]⚠ Could not create sandbox worktree: {result.stderr.strip()}[/yellow]")
+            console.print("[dim]Proceeding without sandbox.[/dim]")
+            return True
+
+        # Pin the target version in the sandbox copy (not in the live project)
+        set_version_pin(worktree_path, target_version)
+
+        console.print("[dim]Running sandbox compile check (mvn clean package)...[/dim]")
+        console.print("[dim]Sandbox scope: compile-only. Boot correctness verified after upgrade.[/dim]")
+
+        build_result = subprocess.run(
+            ["mvn", "clean", "package", "-pl", "biller-user-layer", "--also-make", "-q"],
+            cwd=str(worktree_path),
+        )
+
+        if build_result.returncode != 0:
+            console.print("[red]✗ Sandbox build FAILED. Version pin NOT updated.[/red]")
+            console.print("Fix the compilation errors before upgrading.")
+            return False
+
+        console.print("[green]✓ Sandbox compile check passed.[/green]")
+        return True
+
+    finally:
+        # Always clean up worktree — success or failure
+        subprocess.run(
+            ["git", "worktree", "remove", "--force", str(worktree_path)],
+            cwd=str(project_dir),
+            capture_output=True,
+        )
+
+
+@app.callback(invoke_without_command=True)
+def upgrade(
+    project_dir: Path = typer.Option(Path("."), "--dir", "-d", help="Project directory"),
+    to: str = typer.Option(None, "--to", help="Target version (default: latest from registry)"),
+    skip_sandbox: bool = typer.Option(False, "--skip-sandbox", help="Skip the sandbox compile check"),
+):
+    """Upgrade biller-core to a newer version."""
+    registry_url = _get_registry_url(project_dir)
+
+    # Resolve current version
+    try:
+        current_version = get_version_pin(project_dir)
+    except (FileNotFoundError, KeyError) as e:
+        console.print(f"[red]{e}[/red]")
+        console.print("Run [bold]biller-cli init[/bold] first.")
+        raise typer.Exit(1)
+
+    # Resolve target version
+    target_version = to or _fetch_latest_version(registry_url)
+
+    # Guard: already on target
+    if Version(target_version) <= Version(current_version):
+        console.print(f"Already on [bold]{current_version}[/bold]. Nothing to upgrade.")
+        if Version(target_version) < Version(current_version):
+            console.print("To downgrade, use [bold]biller-cli downgrade[/bold].")
+        raise typer.Exit(0)
+
+    console.print(f"\nUpgrading biller-core: [bold]{current_version}[/bold] → [bold]{target_version}[/bold]")
+    console.print(f"Registry: {registry_url}\n")
+
+    # Fetch migration path
+    migration = _fetch_migration_path(registry_url, current_version, target_version)
+    rules = migration.get("rules", [])
+    path = migration.get("path", [])
+
+    if path:
+        console.print(f"Migration path: {' → '.join([current_version] + path)}")
+    else:
+        console.print("No intermediate versions — direct upgrade.")
+
+    if migration.get("has_breaking_changes"):
+        console.print("\n[red bold]⚠ Breaking changes detected in this upgrade path.[/red bold]")
+        typer.confirm("Continue?", abort=True)
+
+    # Apply automatable rules
+    auto_rules = [r for r in rules if r.get("type") == "config_rename"]
+    manual_rules = [r for r in rules if r.get("type") == "manual"]
+
+    if auto_rules:
+        console.print(f"\nApplying {len(auto_rules)} automated migration rule(s):")
+        for rule in auto_rules:
+            _apply_config_rename_rule(project_dir, rule)
+
+    if manual_rules:
+        console.print(f"\n[yellow bold]⚠ {len(manual_rules)} manual step(s) required:[/yellow bold]")
+        for rule in manual_rules:
+            console.print(f"  → {rule.get('description', 'See docs')}")
+            if rule.get("docs_url"):
+                console.print(f"    Docs: {rule['docs_url']}")
+        console.print("[yellow]These must be completed manually before running biller-cli up.[/yellow]")
+
+    # Sandbox compile check
+    if not skip_sandbox:
+        passed = _run_sandbox_build(project_dir, target_version)
+        if not passed:
+            raise typer.Exit(1)
+    else:
+        console.print("[yellow]⚠ Sandbox skipped.[/yellow]")
+
+    # All gates passed — update the live version pin
+    try:
+        set_version_pin(project_dir, target_version)
+    except (FileNotFoundError, RuntimeError) as e:
+        console.print(f"[red]Failed to update version pin: {e}[/red]")
+        raise typer.Exit(1)
+
+    console.print(f"\n[green bold]✓ Upgrade complete.[/green bold]")
+    console.print(f"biller-core pinned to [bold]{target_version}[/bold] in biller.yaml and pom.xml.")
+    console.print("\nNext: run [bold]biller-cli down && biller-cli up[/bold] to apply.")
+
+    if manual_rules:
+        console.print("[yellow]Reminder: complete the manual steps above before starting the stack.[/yellow]")

biller_cli/main.py

@@ -0,0 +1,34 @@
+import typer
+from rich.console import Console
+
+# Import commands
+from biller_cli.commands import init, up, down, upgrade, downgrade
+
+app = typer.Typer(
+    name="biller-cli",
+    help="Manage your Biller Integrator lifecycle: from scaffold to production.",
+    add_completion=False,
+)
+console = Console()
+
+# Register subcommands
+app.add_typer(init.app, name="init")
+app.add_typer(up.app, name="up")
+app.add_typer(down.app, name="down")
+app.add_typer(upgrade.app, name="upgrade")
+app.add_typer(downgrade.app, name="downgrade")
+
+@app.callback(invoke_without_command=True)
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(None, "--version", "-v", is_eager=True, help="Print version and exit."),
+):
+    if version:
+        console.print("biller-cli v0.1.0")
+        raise typer.Exit()
+        
+    if ctx.invoked_subcommand is None:
+        console.print(ctx.get_help())
+
+if __name__ == "__main__":
+    app()