pdt-cli 0.1.0__py3-none-any.whl

pdt/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pdt-cli")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

pdt/cli.py

@@ -0,0 +1,177 @@
+"""pdt — set up, run, and deploy scheduled jobs.
+
+Commands:
+  init [DIR]             create a project here, or in DIR
+  examples               list the example apps bundled with pdt
+  new <app> --from EXAMPLE   add an app to the project
+  list                   show every app with its schedule and provider
+  validate               check config files and required env vars
+  run <app>              run an app locally
+  deploy <app> [--yes] [--profile NAME]   deploy an app to its configured platform
+  destroy <app> [--yes] [--profile NAME]  tear down everything deploy created for an app
+  login <app> [--profile NAME]            sign in again to the app's cloud provider
+  az <args...>           run the Azure CLI that pdt installs
+  gcloud <args...>       run the Google Cloud CLI that pdt installs
+
+Every command except `init`, `examples`, `az`, and `gcloud` needs a project.
+pdt finds it by walking up from the working directory to the nearest pdt.yml.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from pdt import __version__, config, deploy, scaffold
+from pdt.config import ConfigError
+from pdt.utils.send_email import email_problems, prepare_email_auth
+
+CLOUD_CLIS = {"az": "deploy_azure.py", "gcloud": "deploy_google_cloud.py"}
+
+
+def cmd_init(args) -> int:
+    return scaffold.init(args.directory, args.yes)
+
+
+def cmd_examples(_args) -> int:
+    return scaffold.list_examples()
+
+
+def cmd_new(args) -> int:
+    return scaffold.new_app(args.app, args.source)
+
+
+def cmd_list(_args) -> int:
+    apps = config.find_apps()
+    if not apps:
+        print("This project has no apps yet.")
+        print("Run `pdt examples` to see what you can start from,")
+        print("then `pdt new my-report --from <example>`.")
+        return 0
+    for name in apps:
+        try:
+            app = config.merged_app(name)
+            schedule = app["schedule"] or "-"
+            provider = app["platform"].get("provider", "-")
+            print(f"{name}  schedule={schedule}  provider={provider}")
+        except ConfigError as e:
+            print(f"{name}  config error: {e}")
+    return 0
+
+
+def cmd_validate(_args) -> int:
+    problems = config.validate()
+    original_env = os.environ.copy()
+    try:
+        for name in config.find_apps():
+            os.environ.clear()
+            os.environ.update(original_env)
+            try:
+                app = config.merged_app(name)
+            except ConfigError:
+                continue
+            config.load_env(app["dir"])
+            for problem in config.check_env(app["env"]):
+                problems.append(f"{name}: {problem}")
+            if config.uses_email(app):
+                for problem in email_problems(app["config"]):
+                    problems.append(f"{name}: {problem}")
+    finally:
+        os.environ.clear()
+        os.environ.update(original_env)
+    if problems:
+        for problem in problems:
+            print(f"error: {problem}")
+        print(f"{len(problems)} problem(s) found.")
+        return 1
+    print("Configuration is valid.")
+    return 0
+
+
+def cmd_run(args) -> int:
+    try:
+        app = config.merged_app(args.app)
+    except ConfigError as e:
+        print(f"error: {e}")
+        return 1
+    if config.uses_email(app):
+        env_files = config.load_env(app["dir"])
+        problems = email_problems(app["config"], check_oauth=False)
+        if problems:
+            for problem in problems:
+                print(f"error: {args.app}: {problem}")
+            return 1
+        prepare_email_auth(env_files[0] if env_files else app["dir"] / ".env")
+    proc = subprocess.run(["uv", "run", "--script", "run.py"], cwd=app["dir"])
+    return proc.returncode
+
+
+def cmd_deploy(args) -> int:
+    return deploy.deploy(args.app, assume_yes=args.yes, profile=args.profile)
+
+
+def cmd_login(args) -> int:
+    return deploy.login(args.app, profile=args.profile)
+
+
+def cmd_destroy(args) -> int:
+    return deploy.destroy(args.app, assume_yes=args.yes, profile=args.profile)
+
+
+def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] in CLOUD_CLIS:
+        # Before argparse, so the cloud CLI parses its own flags.
+        script = Path(__file__).with_name(CLOUD_CLIS[sys.argv[1]])
+        return subprocess.run(
+            ["uv", "run", "--script", str(script), *sys.argv[1:]]).returncode
+    parser = argparse.ArgumentParser(
+        prog="pdt", description=__doc__,
+        formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("init", help="create a project here, or in DIR")
+    p.add_argument("directory", nargs="?")
+    p.add_argument("--yes", action="store_true", help="accept the defaults, ask nothing")
+    p.set_defaults(func=cmd_init)
+    sub.add_parser("examples", help="list the bundled example apps").set_defaults(
+        func=cmd_examples)
+    p = sub.add_parser("new", help="add an app to the project")
+    p.add_argument("app")
+    p.add_argument("--from", dest="source",
+                   help="which example to copy; run `pdt examples` to see them")
+    p.set_defaults(func=cmd_new)
+    sub.add_parser("list", help="show every app").set_defaults(func=cmd_list)
+    sub.add_parser("validate", help="check config and env").set_defaults(func=cmd_validate)
+    p = sub.add_parser("run", help="run an app locally")
+    p.add_argument("app")
+    p.set_defaults(func=cmd_run)
+    p = sub.add_parser("deploy", help="deploy an app")
+    p.add_argument("app")
+    p.add_argument("--yes", action="store_true", help="skip the confirmation prompt")
+    p.add_argument("--profile", help="AWS profile name (AWS only)")
+    p.set_defaults(func=cmd_deploy)
+    p = sub.add_parser("login", help="sign in again to an app's cloud provider")
+    p.add_argument("app")
+    p.add_argument("--profile", help="AWS profile name (AWS only)")
+    p.set_defaults(func=cmd_login)
+    p = sub.add_parser("destroy", help="tear down an app's deployed resources")
+    p.add_argument("app")
+    p.add_argument("--yes", action="store_true", help="skip the confirmation prompt")
+    p.add_argument("--profile", help="AWS profile name (AWS only)")
+    p.set_defaults(func=cmd_destroy)
+    args = parser.parse_args()
+    try:
+        return args.func(args)
+    except ConfigError as e:
+        print(f"error: {e}")
+        return 1
+    except KeyboardInterrupt:
+        print()
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pdt/config.py

@@ -0,0 +1,394 @@
+"""Load, merge, and validate pdt configuration.
+
+A project is a directory holding pdt.yml. An app is a directory inside it
+that contains run.py. Commands find the project by walking up from the
+working directory, so pdt works the same whether it was installed from
+PyPI or run from a clone of this repository.
+
+Merge order for one app, least to most specific:
+  1. `platform:` defaults in the project pdt.yml
+  2. the app's entry under `apps:` in pdt.yml
+  3. the app's own config.yml
+  4. PDT_<APP>_<KEY> environment variables (config keys only)
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import date, timedelta
+from pathlib import Path
+
+import yaml
+from dotenv import load_dotenv
+
+PROJECT_FILE = "pdt.yml"
+APP_FILE = "config.yml"
+
+PROVIDERS = ("google-cloud", "azure", "aws", "snowflake", "windows")
+AWS_RUNTIMES = ("lambda", "fargate")
+AZURE_RUNTIMES = ("functions", "container_apps")
+SCHEDULE_SHORTHAND = {
+    "hourly": "0 * * * *",
+    "daily": "0 0 * * *",
+    "weekly": "0 0 * * 0",
+    "monthly": "0 0 1 * *",
+    "yearly": "0 0 1 1 *",
+}
+APP_KEYS = {"name", "schedule", "timezone", "platform", "config", "env"}
+PLATFORM_KEYS = {
+    "provider", "region", "project",
+    "account", "runtime",
+    "subscription", "resource_group",
+}
+ENV_KEYS = {"required", "one_of", "optional"}
+CRON_FIELDS = (
+    ("minute", 0, 59),
+    ("hour", 0, 23),
+    ("day-of-month", 1, 31),
+    ("month", 1, 12),
+    ("day-of-week", 0, 7),
+)
+
+
+class ConfigError(Exception):
+    pass
+
+
+def load_yaml(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    try:
+        data = yaml.safe_load(path.read_text())
+    except yaml.YAMLError as e:
+        raise ConfigError(f"{path}: not valid yaml: {e}")
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: expected a mapping at the top level")
+    return data
+
+
+def find_project(start: Path | None = None) -> Path:
+    override = os.environ.get("PDT_PROJECT", "").strip()
+    if override != "":
+        folder = Path(override).expanduser().resolve()
+        if not (folder / PROJECT_FILE).is_file():
+            raise ConfigError(f"PDT_PROJECT is {folder}, which has no {PROJECT_FILE}")
+        return folder
+    folder = (start or Path.cwd()).resolve()
+    while True:
+        if (folder / PROJECT_FILE).is_file():
+            return folder
+        if folder.parent == folder:
+            raise ConfigError(
+                f"this is not a pdt project: no {PROJECT_FILE} here or in any "
+                "parent folder. Run `pdt init` to set one up.")
+        folder = folder.parent
+
+
+def find_apps() -> list[str]:
+    names = []
+    for child in sorted(find_project().iterdir()):
+        if child.name.startswith(".") or not child.is_dir():
+            continue
+        if (child / "run.py").is_file():
+            names.append(child.name)
+    return names
+
+
+def uses_email(app: dict) -> bool:
+    return "pdt.utils.send_email" in (app["dir"] / "run.py").read_text()
+
+
+def root_app_entry(root_cfg: dict, name: str) -> dict:
+    for entry in root_cfg.get("apps") or []:
+        if isinstance(entry, dict) and entry.get("name") == name:
+            return entry
+    return {}
+
+
+def env_overrides(name: str) -> dict:
+    prefix = "PDT_" + name.upper().replace("-", "_") + "_"
+    out = {}
+    for key, val in os.environ.items():
+        if key.startswith(prefix):
+            out[key[len(prefix):].lower()] = val
+    return out
+
+
+def merged_app(name: str) -> dict:
+    app_dir = find_project() / name
+    if not (app_dir / "run.py").is_file():
+        raise ConfigError(f"no app named {name!r} (no {name}/run.py)")
+    root_cfg = load_yaml(find_project() / PROJECT_FILE)
+    entry = root_app_entry(root_cfg, name)
+    own = load_yaml(app_dir / APP_FILE)
+    return {
+        "name": name,
+        "dir": app_dir,
+        "schedule": own.get("schedule", entry.get("schedule")),
+        "timezone": own.get("timezone", entry.get("timezone", "Etc/UTC")),
+        "platform": {
+            **(root_cfg.get("platform") or {}),
+            **(entry.get("platform") or {}),
+            **(own.get("platform") or {}),
+        },
+        "config": {
+            **(entry.get("config") or {}),
+            **(own.get("config") or {}),
+            **env_overrides(name),
+        },
+        "env": own.get("env", entry.get("env")) or {},
+    }
+
+
+def save_platform_key(app: dict, key: str, value: str) -> Path:
+    # Edit the text rather than rewrite the yaml, so the user's comments survive.
+    project_file = find_project() / PROJECT_FILE
+    root_cfg = load_yaml(project_file)
+    if (root_cfg.get("platform") or {}).get("provider") == app["platform"].get("provider"):
+        path = project_file
+    else:
+        path = app["dir"] / APP_FILE
+    lines = path.read_text().splitlines() if path.is_file() else []
+    start = next((i for i, line in enumerate(lines) if line.strip() == "platform:"), None)
+    if start is None:
+        lines += ["platform:", f'  {key}: "{value}"']
+    else:
+        end = start + 1
+        while end < len(lines) and (lines[end].startswith((" ", "\t")) or lines[end].strip() == ""):
+            end += 1
+        block = range(start + 1, end)
+        existing = next((i for i in block if lines[i].strip().startswith(f"{key}:")), None)
+        if existing is not None:
+            lines[existing] = f'{_indent(lines[existing])}{key}: "{value}"'
+        else:
+            first = next((i for i in block
+                          if lines[i].strip() and not lines[i].strip().startswith("#")), None)
+            indent = _indent(lines[first]) if first is not None else "  "
+            lines.insert((first if first is not None else start) + 1, f'{indent}{key}: "{value}"')
+    path.write_text("\n".join(lines) + "\n")
+    return path
+
+
+def _indent(line: str) -> str:
+    return line[:len(line) - len(line.lstrip())]
+
+
+def aws_account_problem(account: str) -> str:
+    # Deploy reads the account from the credentials and writes it back, so
+    # validate only judges a value the user already set.
+    account = account.strip()
+    if account == "" or (len(account) == 12 and account.isdigit()):
+        return ""
+    return "That is not an AWS account ID. It is 12 digits, for example 123456789012."
+
+
+def cron_expression(schedule) -> str:
+    if not isinstance(schedule, str) or schedule.strip() == "":
+        raise ConfigError("schedule is missing")
+    text = schedule.strip()
+    if text.lstrip("@") in SCHEDULE_SHORTHAND:
+        return SCHEDULE_SHORTHAND[text.lstrip("@")]
+    fields = text.split()
+    if len(fields) != 5:
+        raise ConfigError(
+            f"schedule {schedule!r} is not a shorthand "
+            f"({', '.join(SCHEDULE_SHORTHAND)}) or a 5-field cron expression")
+    for field, (label, lo, hi) in zip(fields, CRON_FIELDS):
+        _cron_values(field, lo, hi, label)
+    return text
+
+
+def _cron_values(field: str, lo: int, hi: int, label: str) -> set[int]:
+    values = set()
+    for part in field.split(","):
+        if part == "":
+            raise ConfigError(f"cron {label} field {field!r} contains an empty value")
+        span, separator, step_text = part.partition("/")
+        if separator and (step_text == "" or "/" in step_text):
+            raise ConfigError(f"cron {label} field {field!r} has an invalid step")
+        try:
+            step = int(step_text) if separator else 1
+        except ValueError:
+            raise ConfigError(f"cron {label} field {field!r} has a non-numeric step")
+        if step < 1:
+            raise ConfigError(f"cron {label} field {field!r} has a step below 1")
+        if span == "*":
+            start, end = lo, hi
+        elif "-" in span:
+            numbers = span.split("-")
+            if len(numbers) != 2:
+                raise ConfigError(f"cron {label} field {field!r} has an invalid range")
+            try:
+                start, end = (int(number) for number in numbers)
+            except ValueError:
+                raise ConfigError(f"cron {label} field {field!r} has a non-numeric range")
+        else:
+            try:
+                start = int(span)
+            except ValueError:
+                raise ConfigError(f"cron {label} field {field!r} is not numeric")
+            end = hi if separator else start
+        if start < lo or end > hi or start > end:
+            raise ConfigError(
+                f"cron {label} field {field!r} must be between {lo} and {hi}")
+        values.update(range(start, end + 1, step))
+    return values
+
+
+def runs_per_month(cron: str) -> float:
+    cron = cron_expression(cron)
+    minute, hour, dom, month, dow = cron.split()
+    per_day = (len(_cron_values(minute, 0, 59, "minute"))
+               * len(_cron_values(hour, 0, 23, "hour")))
+    months = _cron_values(month, 1, 12, "month")
+    doms = _cron_values(dom, 1, 31, "day-of-month")
+    dows = {d % 7 for d in _cron_values(dow, 0, 7, "day-of-week")}
+    days = 0
+    for offset in range(365):  # a representative non-leap year
+        day = date(2025, 1, 1) + timedelta(days=offset)
+        if day.month not in months:
+            continue
+        dom_hit = day.day in doms
+        dow_hit = (day.weekday() + 1) % 7 in dows
+        # cron rule: dom and dow are OR'd only when both are restricted
+        if dom == "*" or dow == "*":
+            hit = dom_hit and dow_hit
+        else:
+            hit = dom_hit or dow_hit
+        if hit:
+            days += 1
+    return per_day * days / 12
+
+
+def find_env_files(start: Path) -> list[Path]:
+    folder = start.resolve()
+    files = []
+    while True:
+        candidate = folder / ".env"
+        if candidate.is_file():
+            files.append(candidate)
+        at_root = (folder / PROJECT_FILE).is_file() or (folder / ".git").exists()
+        if at_root or folder.parent == folder:
+            break
+        folder = folder.parent
+    return files
+
+
+def load_env(start: Path) -> list[Path]:
+    # Closest .env wins; parents only fill keys still empty.
+    # Existing process env wins (override=False).
+    files = find_env_files(start)
+    for path in files:
+        load_dotenv(path, override=False)
+    load_env_json()
+    return files
+
+
+def load_env_json() -> None:
+    # In the cloud, deploy mounts all app secrets as one json blob.
+    raw = os.environ.get("PDT_ENV_JSON", "").strip()
+    if raw == "":
+        return
+    try:
+        blob = json.loads(raw)
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"PDT_ENV_JSON is not valid json: {e}")
+    for key, val in blob.items():
+        os.environ.setdefault(key, str(val))
+
+
+def check_env(env_spec: dict) -> list[str]:
+    problems = []
+    for name in env_spec.get("required") or []:
+        if os.environ.get(name, "").strip() == "":
+            problems.append(f"missing required env var {name}")
+    groups = env_spec.get("one_of") or []
+    if groups:
+        satisfied = False
+        for group in groups:
+            complete = True
+            for name in group:
+                if os.environ.get(name, "").strip() == "":
+                    complete = False
+            if complete:
+                satisfied = True
+        if not satisfied:
+            choices = " or ".join(" + ".join(group) for group in groups)
+            problems.append(f"set one of: {choices}")
+    return problems
+
+
+def validate() -> list[str]:
+    problems = []
+    try:
+        root_cfg = load_yaml(find_project() / PROJECT_FILE)
+    except ConfigError as e:
+        return [str(e)]
+    for key in root_cfg:
+        if key not in {"platform", "apps"}:
+            problems.append(f"{PROJECT_FILE}: unknown key {key!r}")
+    apps = find_apps()
+    for entry in root_cfg.get("apps") or []:
+        if not isinstance(entry, dict) or "name" not in entry:
+            problems.append(f"{PROJECT_FILE}: every apps entry needs a name")
+            continue
+        if entry["name"] not in apps:
+            problems.append(f"{PROJECT_FILE}: app {entry['name']!r} has no directory with a run.py")
+        for key in entry:
+            if key not in APP_KEYS:
+                problems.append(f"{PROJECT_FILE}: app {entry['name']}: unknown key {key!r}")
+    for name in apps:
+        problems.extend(validate_app(name))
+    return problems
+
+
+def validate_app(name: str) -> list[str]:
+    problems = []
+    where = f"{name}/config.yml"
+    try:
+        own = load_yaml(find_project() / name / APP_FILE)
+    except ConfigError as e:
+        return [str(e)]
+    for key in own:
+        if key == "apps":
+            problems.append(f"{where}: the apps list is only allowed in pdt.yml")
+        elif key not in APP_KEYS:
+            problems.append(f"{where}: unknown key {key!r}")
+    own_name = own.get("name")
+    if own_name is not None and own_name != name:
+        problems.append(f"{where}: name {own_name!r} does not match directory {name!r}")
+    try:
+        app = merged_app(name)
+    except ConfigError as e:
+        return problems + [str(e)]
+    for key in app["platform"]:
+        if key not in PLATFORM_KEYS:
+            problems.append(f"{name}: platform: unknown key {key!r}")
+    provider = app["platform"].get("provider")
+    if provider not in PROVIDERS:
+        problems.append(
+            f"{name}: platform.provider must be one of: {', '.join(PROVIDERS)}. "
+            f"Set it under platform: in {PROJECT_FILE}, or in {name}/{APP_FILE}.")
+    if provider == "aws":
+        problem = aws_account_problem(str(app["platform"].get("account") or ""))
+        if problem != "":
+            problems.append(f"{name}: platform.account: {problem}")
+        runtime = app["platform"].get("runtime", "lambda")
+        if runtime not in AWS_RUNTIMES:
+            problems.append(f"{name}: platform.runtime must be one of: {', '.join(AWS_RUNTIMES)}")
+    if provider == "azure":
+        runtime = app["platform"].get("runtime", "functions")
+        if runtime not in AZURE_RUNTIMES:
+            problems.append(f"{name}: platform.runtime must be one of: {', '.join(AZURE_RUNTIMES)}")
+    if app["schedule"] is not None:
+        try:
+            cron_expression(app["schedule"])
+        except ConfigError as e:
+            problems.append(f"{name}: {e}")
+    for key in app["env"]:
+        if key not in ENV_KEYS:
+            problems.append(f"{name}: env: unknown key {key!r}")
+    return problems

pdt/deploy.py

@@ -0,0 +1,106 @@
+"""Provider-neutral deploy entry points.
+
+Validates the app, then dispatches to one script per provider
+(pdt/deploy_<provider>.py) with `uv run --script`, so each provider
+installs its own SDK packages. Every provider script accepts
+`deploy|destroy|login <app> [--yes] [--profile NAME]`.
+
+PDT_PROJECT reaches the provider script through the environment, so the
+child agrees with the parent about which project it is working on.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+from pdt import config
+from pdt.config import ConfigError
+from pdt.utils.send_email import email_problems, prepare_email_auth
+
+PROVIDERS = {
+    "google-cloud": "deploy_google_cloud.py",
+    "aws": "deploy_aws.py",
+    "azure": "deploy_azure.py",
+    "windows": "deploy_windows.py",
+}
+
+
+def _load(app_name: str):
+    app = config.merged_app(app_name)
+    provider = app["platform"].get("provider")
+    if provider not in PROVIDERS:
+        raise ConfigError(
+            f"provider {provider!r} is not supported yet "
+            f"(supported: {', '.join(PROVIDERS)})")
+    return app, provider
+
+
+def dispatch(provider: str, command: str, app_name: str, assume_yes: bool,
+             profile: str | None = None) -> int:
+    script = Path(__file__).with_name(PROVIDERS[provider])
+    args = ["uv", "run", "--script", str(script), command, app_name]
+    if assume_yes:
+        args.append("--yes")
+    if profile:
+        args += ["--profile", profile]
+    env = dict(os.environ, PDT_PROJECT=str(config.find_project()))
+    return subprocess.run(args, check=False, env=env).returncode
+
+
+def deploy(app_name: str, assume_yes: bool = False, profile: str | None = None) -> int:
+    try:
+        app, provider = _load(app_name)
+    except ConfigError as e:
+        print(f"error: {e}")
+        return 1
+    problems = config.validate_app(app_name)
+    env_files = config.load_env(app["dir"])
+    for problem in config.check_env(app["env"]):
+        problems.append(f"env: {problem}")
+    if app["schedule"] is None:
+        problems.append("schedule is required to deploy")
+    if config.uses_email(app):
+        problems.extend(email_problems(app["config"], check_oauth=False))
+    if problems:
+        for problem in problems:
+            print(f"error: {app_name}: {problem}")
+        return 1
+    if config.uses_email(app):
+        env_file = env_files[0] if env_files else app["dir"] / ".env"
+        prepare_email_auth(env_file)
+    return dispatch(provider, "deploy", app_name, assume_yes, profile)
+
+
+def login(app_name: str, profile: str | None = None) -> int:
+    try:
+        app, provider = _load(app_name)
+    except ConfigError as e:
+        print(f"error: {e}")
+        return 1
+    config.load_env(app["dir"])
+    return dispatch(provider, "login", app_name, False, profile)
+
+
+def destroy(app_name: str, assume_yes: bool = False, profile: str | None = None) -> int:
+    try:
+        app, provider = _load(app_name)
+    except ConfigError as e:
+        print(f"error: {e}")
+        return 1
+    config.load_env(app["dir"])
+    return dispatch(provider, "destroy", app_name, assume_yes, profile)
+
+
+def confirm(actions: list[str], assume_yes: bool,
+            cost_lines: list[str] | None = None) -> bool:
+    print("Plan:")
+    for action in actions:
+        print(f"  {action}")
+    for line in cost_lines or []:
+        print(line)
+    if assume_yes:
+        return True
+    answer = input("Proceed? [y/N] ").strip().lower()
+    return answer in ("y", "yes")