silicon-cli 1.0.0__py3-none-any.whl

silicon_cli/registry.py

@@ -0,0 +1,145 @@
+"""~/.silicon/registry.json — the list of known silicon installations.
+
+Same file + schema as the original bash CLI, so installs carry over unchanged:
+    {"installations": [{"name", "path", "pid_file"}, ...]}
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from . import ui
+from .config import REGISTRY_DIR, REGISTRY_FILE
+
+
+@dataclass
+class Install:
+    index: int
+    name: str
+    path: str
+    pid_file: str
+
+
+def _load() -> dict:
+    if REGISTRY_FILE.exists():
+        try:
+            return json.loads(REGISTRY_FILE.read_text())
+        except Exception:
+            return {"installations": []}
+    return {"installations": []}
+
+
+def _save(reg: dict) -> None:
+    REGISTRY_DIR.mkdir(parents=True, exist_ok=True)
+    REGISTRY_FILE.write_text(json.dumps(reg, indent=2))
+
+
+def installs() -> list[Install]:
+    reg = _load()
+    out = []
+    for i, inst in enumerate(reg.get("installations", [])):
+        out.append(Install(i, inst["name"], inst["path"], inst.get("pid_file", "")))
+    return out
+
+
+def count() -> int:
+    return len(_load().get("installations", []))
+
+
+def register(name: str, path: str, pid_file: str | None = None) -> str:
+    """Add an installation. Returns 'added' or 'exists'."""
+    path = str(Path(path))
+    pid_file = pid_file or str(Path(path) / ".silicon.pid")
+    reg = _load()
+    for inst in reg.get("installations", []):
+        if inst.get("path") == path or inst.get("name") == name:
+            return "exists"
+    reg.setdefault("installations", []).append({"name": name, "path": path, "pid_file": pid_file})
+    _save(reg)
+    return "added"
+
+
+def name_taken(name: str) -> bool:
+    return any(i.name == name for i in installs())
+
+
+def find(search: str | None = None) -> Install | None:
+    """By name if given, else the install whose path contains the cwd."""
+    rows = installs()
+    if search:
+        for i in rows:
+            if i.name == search:
+                return i
+        return None
+    cwd = os.getcwd()
+    for i in rows:
+        if cwd == i.path or cwd.startswith(i.path.rstrip("/") + "/"):
+            return i
+    return None
+
+
+def is_multi_target(s: str) -> bool:
+    if s == "all":
+        return True
+    parts = s.split(",")
+    return all(p.strip().isdigit() for p in parts) and bool(parts)
+
+
+def resolve_targets(selector: str) -> list[str]:
+    """'all' | '1,2,4' (1-based indices) → list of install names."""
+    rows = installs()
+    if selector == "all":
+        return [i.name for i in rows]
+    out = []
+    for num in selector.split(","):
+        num = num.strip()
+        if not num.isdigit():
+            continue
+        idx = int(num) - 1
+        for i in rows:
+            if i.index == idx:
+                out.append(i.name)
+    return out
+
+
+def pick() -> Install:
+    """Interactive picker; auto-selects when there's exactly one."""
+    rows = installs()
+    if not rows:
+        ui.error("No silicon installations found. Run 'silicon install' first.")
+        sys.exit(1)
+    if len(rows) == 1:
+        return rows[0]
+
+    from .process import is_running
+    sys.stderr.write(f"\n{ui.BOLD}Select a silicon instance:{ui.RESET}\n\n")
+    for i in rows:
+        running = is_running(i.pid_file)
+        status = f"{ui.GREEN}● running{ui.RESET}" if running else f"{ui.DIM}○ stopped{ui.RESET}"
+        sys.stderr.write(f"  {ui.BOLD}{i.index + 1}){ui.RESET} {i.name:<20} {status}  {ui.DIM}{i.path}{ui.RESET}\n")
+    sys.stderr.write("\n")
+    choice = ui.ask("Choice", "1")
+    try:
+        target_idx = int(choice) - 1
+    except ValueError:
+        ui.error("Invalid choice")
+        sys.exit(1)
+    for i in rows:
+        if i.index == target_idx:
+            return i
+    ui.error("Invalid choice")
+    sys.exit(1)
+
+
+def resolve_one(target: str | None) -> Install:
+    """For single-target commands: by name, else cwd, else interactive pick."""
+    if target:
+        inst = find(target)
+        if not inst:
+            ui.error(f"Silicon '{target}' not found")
+            sys.exit(1)
+        return inst
+    return find() or pick()

silicon_cli/stemcell.py

@@ -0,0 +1,226 @@
+"""Create / hydrate a silicon from the silicon-stemcell base.
+
+`silicon new <dir>` downloads the stemcell, copies in any files the target is
+missing (never clobbering env.py / silicon.json / .glass.json), seeds config +
+env keys, prompts for tokens + brain/worker providers, installs requirements,
+and registers the instance — same flow as the original bash CLI.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+from . import registry, ui
+from .config import STEMCELL_GIT_URL, STEMCELL_ZIP_URL, python_run_cmd
+
+SKIP_NAMES = {".git", "__pycache__", ".DS_Store"}
+PRESERVE_ROOT = {"env.py", "silicon.json", ".glass.json"}
+ALLOWED_PROVIDERS = {"claude", "codex", "chatgpt"}
+
+
+def download_stemcell(target: str) -> None:
+    shutil.rmtree(target, ignore_errors=True)
+    os.makedirs(target, exist_ok=True)
+    if shutil.which("git"):
+        subprocess.run(["git", "clone", "--depth", "1", STEMCELL_GIT_URL, target],
+                       stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
+        shutil.rmtree(Path(target) / ".git", ignore_errors=True)
+        return
+    # Fallback: download the zip
+    dl = shutil.which("curl") or shutil.which("wget")
+    if not dl:
+        ui.error("Need git, curl, or wget to download Silicon.")
+        sys.exit(1)
+    tmp_zip = tempfile.mktemp(suffix=".zip", prefix="silicon-")
+    if "curl" in dl:
+        subprocess.run([dl, "-fsSL", STEMCELL_ZIP_URL, "-o", tmp_zip], check=True)
+    else:
+        subprocess.run([dl, "-q", STEMCELL_ZIP_URL, "-O", tmp_zip], check=True)
+    subprocess.run(["unzip", "-q", tmp_zip, "-d", target], check=True)
+    os.unlink(tmp_zip)
+    extracted = [p for p in Path(target).iterdir() if p.is_dir() and p.name.startswith("silicon-")]
+    if extracted:
+        inner = extracted[0]
+        for item in inner.iterdir():
+            shutil.move(str(item), str(Path(target) / item.name))
+        shutil.rmtree(inner, ignore_errors=True)
+
+
+def _env_value(env_path: Path, key: str) -> str:
+    if not env_path.exists():
+        return ""
+    m = re.search(rf'^{key}\s*=\s*["\'](.*)["\']\s*$', env_path.read_text(), re.M)
+    return m.group(1) if m else ""
+
+
+def _env_upsert(env_path: Path, key: str, value: str) -> None:
+    text = env_path.read_text() if env_path.exists() else ""
+    pattern = rf'^{key}\s*=\s*["\'].*["\']\s*$'
+    replacement = f'{key} = "{value}"'
+    if re.search(pattern, text, re.M):
+        text = re.sub(pattern, replacement, text, flags=re.M)
+    else:
+        text = (text.rstrip() + "\n" if text.strip() else "") + replacement + "\n"
+    env_path.write_text(text.rstrip() + "\n")
+
+
+def _provider_list(value, default):
+    if not isinstance(value, list):
+        return default
+    out = []
+    for item in value:
+        if isinstance(item, str) and item in ALLOWED_PROVIDERS:
+            v = "codex" if item == "chatgpt" else item
+            if v not in out:
+                out.append(v)
+    return out or default
+
+
+def _choose_provider_order(worker_type: str, default_choice: str = "claude") -> list[str]:
+    choice = ui.ask(f"Which provider should {worker_type} workers use – claude or codex?", default_choice)
+    if choice == "codex":
+        return ["codex", "claude"] if ui.confirm(f"Keep claude as fallback for {worker_type} workers?") else ["codex"]
+    return ["claude", "codex"] if ui.confirm(f"Keep codex as fallback for {worker_type} workers?") else ["claude"]
+
+
+def hydrate(target: str) -> None:
+    abs_target = str(Path(target).resolve())
+    os.makedirs(abs_target, exist_ok=True)
+    dst = Path(abs_target)
+
+    tmp_src = tempfile.mkdtemp(prefix="silicon-src-")
+    try:
+        ui.info("Downloading Silicon stemcell...")
+        download_stemcell(tmp_src)
+        src = Path(tmp_src)
+
+        # Instance name: silicon.json address/name, else folder name
+        name = ""
+        sj = dst / "silicon.json"
+        if sj.exists():
+            try:
+                data = json.loads(sj.read_text())
+                name = (data.get("address") or data.get("name") or "").strip()
+            except Exception:
+                pass
+        if not name:
+            name = dst.name
+
+        ui.info(f"Hydrating {abs_target}...")
+        for path in src.rglob("*"):
+            rel = path.relative_to(src)
+            if any(part in SKIP_NAMES for part in rel.parts):
+                continue
+            tgt = dst / rel
+            if path.is_dir():
+                tgt.mkdir(parents=True, exist_ok=True)
+                continue
+            if len(rel.parts) == 1 and rel.parts[0] in PRESERVE_ROOT and tgt.exists():
+                continue
+            if tgt.exists():
+                continue
+            tgt.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(path, tgt)
+
+        # Seed silicon.json
+        silicon = {}
+        if sj.exists():
+            try:
+                silicon = json.loads(sj.read_text())
+            except json.JSONDecodeError:
+                silicon = {}
+        silicon.setdefault("name", "Silicon")
+        silicon.setdefault("run", "python main.py")
+        silicon.setdefault("brain", "claude")
+        silicon.setdefault("workers", {"browser": ["claude"], "terminal": ["claude"], "writer": ["claude"]})
+        if not silicon.get("address"):  # the stemcell ships an empty address — fill it
+            silicon["address"] = name
+        silicon.pop("version", None)
+        sj.write_text(json.dumps(silicon, indent=4) + "\n")
+
+        # Seed env.py required keys
+        env_path = dst / "env.py"
+        for key, default in {"TELEGRAM_BOT_TOKEN": "", "OPENAI_API_KEY": "", "GEMINI_API_KEY": "", "BROWSER_PROFILE": name}.items():
+            if not _env_value(env_path, key):
+                _env_upsert(env_path, key, default)
+
+        # Run the stemcell's snapshot hook (for safe future updates), best-effort
+        updater = src / "scripts" / "silicon_update.py"
+        if updater.exists():
+            subprocess.run([python_run_cmd(), str(updater), "snapshot", "--source", str(src), "--target", abs_target],
+                           stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+
+        # Interactive setup
+        if ui.interactive():
+            _interactive_setup(dst, env_path, sj, name)
+
+        # Install dependencies
+        req = dst / "requirements.txt"
+        if req.exists():
+            ui.info("Installing Python dependencies...")
+            r = subprocess.run([python_run_cmd(), "-m", "pip", "install", "-r", str(req), "--quiet"])
+            if r.returncode != 0:
+                subprocess.run([python_run_cmd(), "-m", "pip", "install", "-r", str(req), "--quiet", "--user"])
+
+        registry.register(name, abs_target)
+        ui.success(f"Hydrated '{name}' at {abs_target}")
+        ui.info(f"Run 'silicon start {name}' when you're ready.")
+    finally:
+        shutil.rmtree(tmp_src, ignore_errors=True)
+
+
+def _interactive_setup(dst: Path, env_path: Path, sj: Path, name: str) -> None:
+    if not _env_value(env_path, "TELEGRAM_BOT_TOKEN"):
+        ui.info("You need a Telegram bot token to use Silicon.")
+        sys.stderr.write(f"{ui.DIM}  1. Open Telegram and search for @BotFather{ui.RESET}\n")
+        sys.stderr.write(f"{ui.DIM}  2. Send /newbot and follow the prompts{ui.RESET}\n")
+        sys.stderr.write(f"{ui.DIM}  3. Copy the token BotFather gives you{ui.RESET}\n")
+        token = ui.read_secret("Telegram bot token")
+        if not token:
+            ui.error("Telegram bot token is required.")
+            sys.exit(1)
+        _env_upsert(env_path, "TELEGRAM_BOT_TOKEN", token)
+
+    if not _env_value(env_path, "OPENAI_API_KEY"):
+        ui.info("OpenAI API key (for incoming voice transcription via Whisper). Enter to skip.")
+        v = ui.read_secret("OpenAI API key (optional)")
+        if v:
+            _env_upsert(env_path, "OPENAI_API_KEY", v)
+
+    if not _env_value(env_path, "GEMINI_API_KEY"):
+        ui.info("Gemini API key (for outgoing text-to-speech). Enter to skip.")
+        v = ui.read_secret("Gemini API key (optional)")
+        if v:
+            _env_upsert(env_path, "GEMINI_API_KEY", v)
+
+    # Brain / worker providers — only ask when both claude + codex are present
+    brain = "claude"
+    workers = {"browser": ["claude"], "terminal": ["claude"], "writer": ["claude"]}
+    have_claude = bool(shutil.which("claude"))
+    have_codex = bool(shutil.which("codex"))
+    if have_claude and have_codex:
+        ui.info("Detected both claude and codex.")
+        brain = "codex" if ui.ask("Which brain should Silicon use – claude or codex?", "claude") == "codex" else "claude"
+        # Each worker defaults to the chosen brain (matches the current stemcell CLI).
+        workers = {
+            "browser": _choose_provider_order("browser", brain),
+            "terminal": _choose_provider_order("terminal", brain),
+            "writer": _choose_provider_order("writer", brain),
+        }
+    elif have_codex:
+        brain = "codex"
+        workers = {"browser": ["codex"], "terminal": ["codex"], "writer": ["codex"]}
+
+    try:
+        silicon = json.loads(sj.read_text())
+    except Exception:
+        silicon = {}
+    silicon["brain"] = brain
+    silicon["workers"] = {k: _provider_list(v, ["claude"]) for k, v in workers.items()}
+    sj.write_text(json.dumps(silicon, indent=4) + "\n")

silicon_cli/sync.py

@@ -0,0 +1,216 @@
+"""Glass sync — pull a silicon from a Glass server and run backups (push).
+
+Faithful port of the bash `pull`/`push`. HTTP via stdlib urllib. Backups shell
+out to the `glass` CLI (auto-installed if missing), same as the original.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+from pathlib import Path
+
+from . import registry, stemcell, ui
+from .config import GLASS_CLI_REPO, GLASS_SERVER_URL
+
+
+def _has_glass() -> bool:
+    return bool(shutil.which("glass"))
+
+
+def ensure_glass_cli() -> None:
+    if _has_glass():
+        return
+    ui.info("glass CLI not found. Installing it...")
+    install_glass_cli()
+    if not _has_glass():
+        ui.error("glass CLI installation failed")
+        sys.exit(1)
+
+
+def install_glass_cli() -> None:
+    glass_dir = Path.home() / ".glass"
+    bin_dir = Path.home() / ".local" / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+    archive = f"https://codeload.github.com/{GLASS_CLI_REPO}/tar.gz/refs/heads/main"
+    tmp = tempfile.mkdtemp(prefix="glass-install-")
+    try:
+        ui.info("Installing glass CLI...")
+        tarball = Path(tmp) / "glass.tar.gz"
+        urllib.request.urlretrieve(archive, tarball)
+        with tarfile.open(tarball) as tf:
+            tf.extractall(tmp)
+        src = next((p for p in Path(tmp).iterdir() if p.is_dir() and p.name.startswith("glass-")), None)
+        if not src or not (src / "glass").exists():
+            ui.warn("Could not auto-install glass CLI. Downloaded archive was invalid.")
+            return
+        shutil.rmtree(glass_dir, ignore_errors=True)
+        glass_dir.mkdir(parents=True, exist_ok=True)
+        for item in src.iterdir():
+            if item.name in {".git", "__pycache__"}:
+                continue
+            dest = glass_dir / item.name
+            if item.is_dir():
+                shutil.copytree(item, dest, dirs_exist_ok=True)
+            else:
+                shutil.copy2(item, dest)
+        os.chmod(glass_dir / "glass", 0o755)
+        wrapper = bin_dir / "glass"
+        if wrapper.exists() or wrapper.is_symlink():
+            wrapper.unlink()
+        wrapper.symlink_to(glass_dir / "glass")
+        ui.success("glass CLI installed") if _has_glass() else ui.warn("glass installed but not on PATH (add ~/.local/bin).")
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+def _post_json(url: str, payload: dict) -> tuple[int, dict]:
+    data = json.dumps(payload).encode()
+    req = urllib.request.Request(url, data=data, headers={"Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(req) as resp:
+            return resp.status, json.loads(resp.read().decode() or "{}")
+    except urllib.error.HTTPError as e:
+        try:
+            return e.code, json.loads(e.read().decode() or "{}")
+        except Exception:
+            return e.code, {}
+    except Exception as e:
+        return 0, {"error": str(e)}
+
+
+def pull(username: str | None) -> None:
+    if not username:
+        ui.error("Usage: silicon pull <silicon-username>")
+        sys.exit(1)
+    ensure_glass_cli()
+
+    target = Path.cwd() / username
+    if target.exists():
+        ui.error(f"Target folder already exists: {target}")
+        sys.exit(1)
+
+    connector_code = ui.read_secret("Connector code")
+    target.mkdir(parents=True)
+    fingerprint = hashlib.sha256(f"{socket.gethostname()}::{target.resolve()}".encode()).hexdigest()
+
+    code, claim = _post_json(f"{GLASS_SERVER_URL}/sync/api/pull/claim/", {
+        "username": username, "connector_code": connector_code,
+        "folder_label": username, "folder_fingerprint": fingerprint,
+    })
+    if not (200 <= code < 300):
+        shutil.rmtree(target, ignore_errors=True)
+        ui.error(claim.get("error", "Pull claim failed."))
+        sys.exit(1)
+
+    if claim.get("has_snapshot"):
+        archive = tempfile.mktemp(suffix=".tar.gz", prefix="silicon-pull-")
+        req = urllib.request.Request(
+            f"{GLASS_SERVER_URL}/sync/api/silicons/{username}/latest.tar.gz",
+            headers={"X-Source-Token": claim["source_token"]},
+        )
+        with urllib.request.urlopen(req) as resp, open(archive, "wb") as f:
+            shutil.copyfileobj(resp, f)
+        with tarfile.open(archive) as tf:
+            tf.extractall(target)
+        os.unlink(archive)
+
+    (target / ".glass.json").write_text(json.dumps({
+        "server_url": GLASS_SERVER_URL, "silicon_username": username,
+        "source_token": claim["source_token"], "api_key": claim["api_key"],
+        "folder_fingerprint": fingerprint, "last_tree_hash": claim.get("latest_tree_hash", ""),
+    }, indent=2) + "\n")
+
+    sj = target / "silicon.json"
+    silicon = {}
+    if sj.exists():
+        try:
+            silicon = json.loads(sj.read_text())
+        except json.JSONDecodeError:
+            silicon = {}
+    silicon.setdefault("name", "Silicon")
+    silicon.setdefault("run", "python main.py")
+    silicon.setdefault("brain", "claude")
+    silicon.setdefault("workers", {"browser": ["claude"], "terminal": ["claude"], "writer": ["claude"]})
+    silicon.pop("version", None)
+    silicon["address"] = username
+    silicon["glass"] = {"server_url": GLASS_SERVER_URL, "silicon_username": username,
+                        "api_key": claim["api_key"], "source_token": claim["source_token"]}
+    sj.write_text(json.dumps(silicon, indent=4) + "\n")
+    stemcell._env_upsert(target / "env.py", "GLASS_API_KEY", claim["api_key"])
+
+    registry.register(username, str(target))
+    ui.success(f"Pulled '{username}' into {target}")
+    ui.info("Registered as a silicon instance.")
+
+    # Empty-repo detection → offer to populate
+    bare = {".glass.json", "silicon.json", "env.py"}
+    real = [f for f in target.iterdir()
+            if not (f.name.startswith(".") and f.name != ".glass.json")
+            and f.name != "__pycache__" and f.name not in bare]
+    if not real and ui.interactive():
+        ui.warn("This looks like an empty repository (only silicon.json and env.py).")
+        if ui.confirm("Do you want to populate it with Silicon?"):
+            stemcell.hydrate(str(target))
+
+    if ui.interactive() and ui.confirm("Do you want to enable backups for this silicon?"):
+        ensure_glass_cli()
+        ui.info("Running initial backup...")
+        if subprocess.run(["glass", "push", "now"], cwd=str(target)).returncode == 0:
+            ui.success("Backup complete.")
+            _start_backup_loop(str(target), username)
+        else:
+            ui.warn(f"Initial backup failed. Retry with: silicon push {username} now")
+
+
+def _start_backup_loop(path: str, name: str) -> None:
+    ui.info("Starting hourly backup loop in background...")
+    log = open(Path(path) / ".glass-push.log", "a")
+    proc = subprocess.Popen(["glass", "push"], cwd=path, stdout=log, stderr=subprocess.STDOUT,
+                            start_new_session=True)
+    (Path(path) / ".glass-push.pid").write_text(str(proc.pid))
+    ui.success(f"Hourly backups running (PID {proc.pid}). Logs: {path}/.glass-push.log")
+    ui.info(f"Use 'silicon push {name} now' for a manual backup anytime.")
+
+
+def push(target: str | None, subcmd: str | None) -> None:
+    inst = registry.resolve_one(target)
+    if not (Path(inst.path) / ".glass.json").exists():
+        ui.error(f"'{inst.name}' is not connected to Glass. No .glass.json found.")
+        sys.exit(1)
+    ensure_glass_cli()
+    pid_file = Path(inst.path) / ".glass-push.pid"
+
+    if subcmd == "now":
+        ui.info(f"Pushing '{inst.name}' to Glass...")
+        ok = subprocess.run(["glass", "push", "now"], cwd=inst.path).returncode == 0
+        ui.success("Backup complete.") if ok else ui.error("Push failed.")
+    elif subcmd == "stop":
+        try:
+            pid = int(pid_file.read_text().strip())
+            os.kill(pid, 15)
+            pid_file.unlink(missing_ok=True)
+            ui.success(f"Stopped backup loop for '{inst.name}'.")
+            return
+        except Exception:
+            ui.warn(f"No backup loop running for '{inst.name}'.")
+            pid_file.unlink(missing_ok=True)
+    else:
+        if pid_file.exists():
+            try:
+                pid = int(pid_file.read_text().strip())
+                os.kill(pid, 0)
+                ui.warn(f"Backup loop already running for '{inst.name}' (PID {pid})")
+                return
+            except Exception:
+                pass
+        ui.info(f"Starting hourly backup loop for '{inst.name}'...")
+        subprocess.run(["glass", "push", "now"], cwd=inst.path)
+        _start_backup_loop(inst.path, inst.name)

silicon_cli/ui.py

@@ -0,0 +1,61 @@
+"""Terminal UI helpers — colors, status glyphs, prompts. Mirrors the bash CLI."""
+from __future__ import annotations
+
+import sys
+
+RED = "\033[0;31m"; GREEN = "\033[0;32m"; YELLOW = "\033[1;33m"
+BLUE = "\033[0;34m"; CYAN = "\033[0;36m"; BOLD = "\033[1m"
+DIM = "\033[2m"; RESET = "\033[0m"
+
+
+def _p(msg: str) -> None:
+    sys.stdout.write(msg + "\n")
+    sys.stdout.flush()
+
+
+def error(msg: str) -> None: _p(f"{RED}✗{RESET} {msg}")
+def info(msg: str) -> None: _p(f"{BLUE}→{RESET} {msg}")
+def success(msg: str) -> None: _p(f"{GREEN}✓{RESET} {msg}")
+def warn(msg: str) -> None: _p(f"{YELLOW}⚠{RESET} {msg}")
+
+
+def interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def confirm(question: str, default_yes: bool = True) -> bool:
+    if not interactive():
+        return default_yes
+    suffix = "[Y/n]" if default_yes else "[y/N]"
+    try:
+        ans = input(f"{BOLD}? {question} {suffix}{RESET} ").strip().lower()
+    except EOFError:
+        return default_yes
+    if not ans:
+        return default_yes
+    return ans[0] != "n" if default_yes else ans[0] == "y"
+
+
+def ask(question: str, default: str = "") -> str:
+    if not interactive():  # non-TTY: don't block on input(), take the default
+        return default
+    label = f"{BOLD}? {question}" + (f" [{default}]" if default else "") + f":{RESET} "
+    try:
+        ans = input(label).strip()
+    except EOFError:
+        ans = ""
+    return ans or default
+
+
+def read_secret(prompt: str) -> str:
+    """Masked input (echoes * per char) on a TTY; falls back to getpass."""
+    import getpass
+    if not interactive():
+        return ""
+    try:
+        sys.stderr.write(f"{BOLD}? {prompt}:{RESET} ")
+        sys.stderr.flush()
+        # getpass reads without echo; we accept that over fragile raw-tty masking.
+        return getpass.getpass("")
+    except Exception:
+        return ""