alpine-fleet 0.1.0__py3-none-any.whl

alpine_fleet/__init__.py

@@ -0,0 +1,3 @@
+"""alpine-fleet: declaratively turn a disposable OCI micro VM into a hardened Alpine machine."""
+
+__version__ = "0.1.0"

alpine_fleet/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

alpine_fleet/answerfiles/oci-e2-micro.answerfile

@@ -0,0 +1,38 @@
+# Non-interactive answerfile for `setup-alpine -f <this-file>`
+# Tuned for OCI VM.Standard.E2.1.Micro (and similar small free-tier shapes).
+#
+# Usage (from the live Alpine environment after kexec):
+#   setup-alpine -f oci-e2-micro.answerfile
+#
+# NOTE: this uses DHCP rather than a static IP + manual netmask, since
+# OCI's VCN subnets hand out DHCP correctly and it sidesteps having to
+# guess/know the subnet's real netmask (setup-alpine's default guess
+# based on IP class is very often wrong for cloud VCNs).
+
+KEYMAPOPTS="us us"
+HOSTNAMEOPTS="-n alpine-worker"
+
+INTERFACESOPTS="auto lo
+iface lo inet loopback
+
+auto eth0
+iface eth0 inet dhcp
+"
+
+# 169.254.169.254 is OCI's metadata service, which proxies DNS correctly
+# inside the VCN. Adjust for other providers.
+DNSOPTS="-d '' 169.254.169.254"
+
+TIMEZONEOPTS="-z UTC"
+PROXYOPTS="none"
+APKREPOSOPTS="-1"
+SSHDOPTS="-c openssh"
+NTPOPTS="-c chrony"
+
+# sda is OCI's boot volume device name for these shapes. Verify with
+# `lsblk` in the live environment before trusting this blindly on a
+# different provider/shape.
+DISKOPTS="-m sys /dev/sda"
+
+LBUOPTS="none"
+APKCACHEOPTS="none"

alpine_fleet/cli.py

@@ -0,0 +1,150 @@
+"""alpine-fleet command line interface."""
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__, doctor, paths
+
+PKG = Path(__file__).resolve().parent
+SCRIPTS = PKG / "scripts"
+ANSWERFILE = PKG / "answerfiles" / "oci-e2-micro.answerfile"
+
+WARNING = """\
+WARNING: this replaces the target instance's operating system with Alpine Linux
+and erases its boot disk (/dev/sda). Use it only on disposable or recoverable
+instances. Root ends up key-only (no password): if you lose your private key,
+rebuild the instance."""
+
+EPILOG = WARNING + """
+
+commands:
+  doctor     check host tools (ssh, jq, oci, bash>=4) and print install commands
+  discover   show E2.1.Micro / A1.Flex headroom per availability domain
+  up         launch an E2.1.Micro if needed and convert it to Alpine
+  convert    convert an existing instance:  convert <user@ip> <instance-ocid>
+  down       terminate the instance recorded in the state file
+  cache      build the Oracle Linux 7 kexec cache (faster runs; needs podman/docker)
+
+Extra flags for discover/down/cache are passed to the underlying script
+(e.g. `alpine-fleet down --yes`, `alpine-fleet cache --force`)."""
+
+
+def _env() -> dict[str, str]:
+    env = dict(os.environ)
+    if not env.get("OCI_BIN"):
+        found = doctor.find_oci()
+        if found:
+            env["OCI_BIN"] = found
+    env.setdefault("ALPINE_FLEET_STATE_DIR", str(paths.state_dir()))
+    env.setdefault("KEXEC_CACHE", str(paths.kexec_cache()))
+    return env
+
+
+def _bash(script: str, extra: list[str]) -> int:
+    # Always via `bash`: wheels and copies can lose exec bits.
+    return subprocess.call(["bash", str(SCRIPTS / script), *extra], env=_env())
+
+
+def _confirm(expect: str | None, yes: bool) -> bool:
+    print(WARNING, file=sys.stderr)
+    if yes:
+        return True
+    if not sys.stdin.isatty():
+        print("Refusing to continue without --yes (stdin is not a terminal).", file=sys.stderr)
+        return False
+    if expect:
+        return input(f"\nType the target's address ({expect}) to continue: ").strip() == expect
+    return input("\nContinue? [y/N] ").strip().lower() == "y"
+
+
+def _orchestrate(args: argparse.Namespace, target: str | None = None, ocid: str | None = None) -> int:
+    missing = doctor.blocking()
+    if missing:
+        print("Missing requirements: " + ", ".join(missing) + "\nRun: alpine-fleet doctor", file=sys.stderr)
+        return 2
+    expect = target.split("@", 1)[-1] if target else None
+    if not _confirm(expect, args.yes):
+        print("Aborted.", file=sys.stderr)
+        return 1
+    state = paths.state_dir()
+    cmd = [sys.executable, str(SCRIPTS / "orchestrate.py"),
+           "--script-dir", str(SCRIPTS),
+           "--answerfile", args.answerfile,
+           "--state-file", str(state / "current-instance.json"),
+           "--serial-log", str(state / "serial.log"),
+           "--alpine-version", args.alpine_version,
+           "--ssh-pubkey", args.ssh_pubkey]
+    if args.console_key:
+        cmd += ["--key", args.console_key]
+    if args.debug:
+        cmd.append("--debug")
+    if getattr(args, "no_launch", False):
+        cmd.append("--no-launch")
+    if target:
+        cmd += [target, ocid]
+    return subprocess.call(cmd, env=_env())
+
+
+def _add_run_flags(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--yes", "-y", action="store_true", help="skip the destructive-action confirmation")
+    p.add_argument("--debug", "-v", action="store_true", help="echo the raw serial console and bootstrap output")
+    p.add_argument("--alpine-version", default="v3.24", help="Alpine release branch (default: %(default)s)")
+    p.add_argument("--ssh-pubkey", default=str(Path.home() / ".ssh" / "id_ed25519.pub"),
+                   help="public key installed for root (default: %(default)s)")
+    p.add_argument("--console-key", default=None, help="RSA key for the OCI serial console (default: ~/.ssh/oci-console-rsa)")
+    p.add_argument("--answerfile", default=str(ANSWERFILE), help="setup-alpine answerfile (default: the bundled OCI one)")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="alpine-fleet",
+        description="Turn a disposable OCI micro VM into a lightweight, hardened Alpine machine.",
+        epilog=EPILOG, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--version", action="version", version=f"alpine-fleet {__version__}")
+    sub = ap.add_subparsers(dest="cmd", metavar="<command>")
+
+    d = sub.add_parser("doctor", help="check host requirements")
+    d.add_argument("--fix", action="store_true", help="offer to run the install command")
+
+    sub.add_parser("discover", help="show free-tier capacity per availability domain", add_help=False)
+
+    up = sub.add_parser("up", help="launch (if needed) and convert to Alpine")
+    _add_run_flags(up)
+    up.add_argument("--no-launch", action="store_true", help="never launch; use the recorded instance")
+
+    cv = sub.add_parser("convert", help="convert an existing instance")
+    cv.add_argument("target", metavar="USER@IP", help="stock-OS login, e.g. opc@203.0.113.7")
+    cv.add_argument("instance_ocid", metavar="INSTANCE_OCID")
+    _add_run_flags(cv)
+
+    sub.add_parser("down", help="terminate the recorded instance", add_help=False)
+    sub.add_parser("cache", help="build the kexec cache", add_help=False)
+    return ap
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = build_parser()
+    args, extra = ap.parse_known_args(argv)
+    if args.cmd is None:
+        ap.print_help()
+        return 0
+    if args.cmd in ("doctor", "up", "convert") and extra:
+        ap.error("unrecognized arguments: " + " ".join(extra))
+
+    if args.cmd == "doctor":
+        return doctor.run(fix=args.fix)
+    if args.cmd == "discover":
+        return _bash("discover-capacity.sh", extra)
+    if args.cmd == "down":
+        return _bash("teardown-e2.sh", extra)
+    if args.cmd == "cache":
+        return _bash("prepare-kexec-cache.sh", extra)
+    if args.cmd == "up":
+        return _orchestrate(args)
+    if args.cmd == "convert":
+        return _orchestrate(args, args.target, args.instance_ocid)
+    return 1

alpine_fleet/doctor.py

@@ -0,0 +1,125 @@
+"""`alpine-fleet doctor`: report missing host tools and print (or run) the install command.
+
+pip cannot install system packages, so this never runs at install time and only
+runs a package-manager command after an explicit confirmation.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+# (tools that must exist, {package manager: package that provides them})
+SYSTEM_GROUPS = [
+    (["ssh", "scp", "ssh-keygen"], {
+        "pacman": "openssh", "apt": "openssh-client", "dnf": "openssh-clients",
+        "zypper": "openssh-clients", "apk": "openssh-client", "brew": "openssh"}),
+    (["jq"], {p: "jq" for p in ("pacman", "apt", "dnf", "zypper", "apk", "brew")}),
+]
+
+INSTALL = {
+    "pacman": ["pacman", "-S", "--needed"],
+    "apt": ["apt", "install"],
+    "dnf": ["dnf", "install"],
+    "zypper": ["zypper", "install"],
+    "apk": ["apk", "add"],
+    "brew": ["brew", "install"],
+}
+
+
+def detect_pm() -> str | None:
+    return next((pm for pm in INSTALL if shutil.which(pm)), None)
+
+
+def bash_major() -> int:
+    bash = shutil.which("bash")
+    if not bash:
+        return 0
+    try:
+        out = subprocess.check_output([bash, "-c", "echo ${BASH_VERSINFO[0]}"], text=True)
+        return int(out.strip())
+    except (subprocess.SubprocessError, ValueError, OSError):
+        return 0
+
+
+def find_oci() -> str | None:
+    if os.environ.get("OCI_BIN"):
+        return os.environ["OCI_BIN"]
+    beside_python = Path(sys.executable).parent / "oci"
+    return str(beside_python) if beside_python.exists() else shutil.which("oci")
+
+
+def oci_config_path() -> Path:
+    return Path(os.environ.get("OCI_CONFIG_FILE", "~/.oci/config")).expanduser()
+
+
+def check() -> tuple[list[tuple[str, str, str]], list[str]]:
+    """Return (rows, packages_to_install). Row = (status, label, hint); status is
+    ok / MISSING (blocks a run) / optional."""
+    rows: list[tuple[str, str, str]] = []
+    pm = detect_pm()
+    pkgs: list[str] = []
+
+    for tools, by_pm in SYSTEM_GROUPS:
+        missing = [t for t in tools if not shutil.which(t)]
+        label = "/".join(tools)
+        if not missing:
+            rows.append(("ok", label, ""))
+        else:
+            pkg = by_pm.get(pm or "")
+            rows.append(("MISSING", label, f"install package '{pkg}'" if pkg else "install with your package manager"))
+            if pkg and pkg not in pkgs:
+                pkgs.append(pkg)
+
+    major = bash_major()
+    if major >= 4:
+        rows.append(("ok", "bash >= 4", ""))
+    else:
+        hint = "macOS ships bash 3.2; run: brew install bash" if sys.platform == "darwin" else "install bash 4 or newer"
+        rows.append(("MISSING", "bash >= 4", hint))
+
+    if find_oci():
+        rows.append(("ok", "oci CLI", ""))
+    else:
+        rows.append(("MISSING", "oci CLI", "pipx install 'alpine-fleet[oci]'  (or: pip install oci-cli)"))
+
+    if oci_config_path().exists():
+        rows.append(("ok", "OCI config", str(oci_config_path())))
+    else:
+        rows.append(("MISSING", "OCI config", "run: oci setup config"))
+
+    if shutil.which("podman") or shutil.which("docker"):
+        rows.append(("ok", "podman/docker", ""))
+    else:
+        rows.append(("optional", "podman/docker", "only needed for `alpine-fleet cache` (faster runs)"))
+
+    return rows, pkgs
+
+
+def blocking() -> list[str]:
+    rows, _ = check()
+    return [label for status, label, _ in rows if status == "MISSING"]
+
+
+def run(fix: bool = False) -> int:
+    rows, pkgs = check()
+    for status, label, hint in rows:
+        mark = {"ok": "ok      ", "MISSING": "MISSING ", "optional": "optional"}[status]
+        print(f"  [{mark}] {label:<16} {hint}")
+
+    pm = detect_pm()
+    if pkgs and pm:
+        cmd = list(INSTALL[pm]) + pkgs
+        if pm != "brew" and os.geteuid() != 0:
+            cmd = ["sudo"] + cmd
+        print("\nInstall the missing system packages with:\n  " + " ".join(cmd))
+        if fix:
+            if input("Run it now? [y/N] ").strip().lower() == "y":
+                subprocess.call(cmd)
+                return 0 if not blocking() else 1
+    elif pkgs:
+        print("\nNo known package manager found; install: " + ", ".join(pkgs))
+
+    return 1 if blocking() else 0

alpine_fleet/paths.py

@@ -0,0 +1,21 @@
+"""User-level state/cache locations (the install directory is never written to)."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def _xdg(var: str, fallback: str) -> Path:
+    return Path(os.environ.get(var) or Path.home() / fallback)
+
+
+def state_dir() -> Path:
+    """Instance state file and serial transcripts (contain instance IDs and IPs)."""
+    override = os.environ.get("ALPINE_FLEET_STATE_DIR")
+    return Path(override) if override else _xdg("XDG_STATE_HOME", ".local/state") / "alpine-fleet"
+
+
+def kexec_cache() -> Path:
+    """Host-side cache of kexec binaries built for the target's stock OS."""
+    override = os.environ.get("KEXEC_CACHE")
+    return Path(override) if override else _xdg("XDG_CACHE_HOME", ".cache") / "alpine-fleet" / "kexec"

alpine_fleet/scripts/bootstrap.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+#
+# alpine-fleet bootstrap.sh
+#
+# Stages a kexec jump from a running cloud VM's current OS into Alpine
+# Linux's netboot installer with an embedded apkovl answerfile overlay.
+#
+set -euo pipefail
+
+TARGET="${1:?Usage: bootstrap.sh <user>@<ip> [alpine-version] [answerfile]}"
+ALPINE_VERSION="${2:-v3.24}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ANSWERFILE="${3:-$SCRIPT_DIR/../answerfiles/oci-e2-micro.answerfile}"
+ARCH="x86_64"
+
+[[ -f "$ANSWERFILE" ]] || { echo "FATAL: answerfile not found at $ANSWERFILE" >&2; exit 1; }
+ANSWERFILE_B64="$(base64 < "$ANSWERFILE" | tr -d '\n')"
+
+TARGET_USER="${TARGET%%@*}"
+if [[ "$TARGET_USER" == "root" ]]; then
+    echo "!! OCI's stock images (opc-based) reject root SSH logins outright." >&2
+    echo "!! Use the image's default user instead, e.g.: opc@${TARGET#*@}" >&2
+    exit 1
+fi
+
+MIRROR="https://dl-cdn.alpinelinux.org/alpine/${ALPINE_VERSION}/releases/${ARCH}/netboot"
+REPO="http://dl-cdn.alpinelinux.org/alpine/${ALPINE_VERSION}/main"
+
+echo "== alpine-fleet bootstrap =="
+echo "Target:     $TARGET"
+echo "Version:    $ALPINE_VERSION"
+echo "Answerfile: $ANSWERFILE"
+echo
+echo "!! Before continuing, make sure you have a serial/console connection"
+echo "!! open and confirmed working for this instance. This is your only"
+echo "!! visibility once the kexec jump happens — SSH will die instantly."
+read -r -p "Console confirmed and watching? [y/N] " confirm
+if [[ "$confirm" != "y" && "$confirm" != "Y" ]]; then
+    echo "Aborting. Set up console access first."
+    exit 1
+fi
+
+# ---- optional host-side kexec cache -------------------------------------------
+# `kexec` has to run on the TARGET'S CURRENT OS (e.g. Oracle Linux 7), not on
+# Alpine and not on this machine, so the cached binary must be built for that OS
+# (see scripts/prepare-kexec-cache.sh). Layout: cache/kexec/<os-id>-<major>/kexec,
+# e.g. cache/kexec/ol-7/kexec. A fully static binary in cache/kexec/static/kexec
+# works on any x86_64 Linux. Set NO_KEXEC_CACHE=1 to ignore the cache.
+KEXEC_CACHE="${KEXEC_CACHE:-${XDG_CACHE_HOME:-$HOME/.cache}/alpine-fleet/kexec}"
+USE_CACHED_KEXEC=0
+if [[ "${NO_KEXEC_CACHE:-0}" != "1" ]]; then
+    OS_ID="$(ssh -o BatchMode=yes "$TARGET" '. /etc/os-release && echo "${ID}-${VERSION_ID%%.*}"' 2>/dev/null || true)"
+    for cand in "$KEXEC_CACHE/${OS_ID:-unknown}/kexec" "$KEXEC_CACHE/static/kexec"; do
+        if [[ -x "$cand" ]]; then
+            if scp -q -o BatchMode=yes "$cand" "$TARGET:/tmp/kexec-cached"; then
+                USE_CACHED_KEXEC=1
+                echo "kexec cache: HIT ($cand) for target OS '${OS_ID:-unknown}'"
+                break
+            fi
+        fi
+    done
+    [[ $USE_CACHED_KEXEC == 1 ]] || echo "kexec cache: miss for target OS '${OS_ID:-unknown}' — will install kexec-tools on the target"
+fi
+
+SSH_OUT=$(mktemp)
+set +e
+ssh -o BatchMode=yes "$TARGET" bash -s <<REMOTE | tee "$SSH_OUT"
+set -euo pipefail
+
+cd /tmp
+# Start the two netboot downloads in the background NOW: they are network-bound,
+# while the package install below is CPU/disk-bound on a 1-vCPU box, so the two
+# overlap instead of running back to back. Waited on (and checked) further down.
+echo "[remote] fetching Alpine netboot kernel + initramfs (background)..."
+( wget -q "${MIRROR}/vmlinuz-lts" -O /tmp/vmlinuz-lts && echo "[remote] kernel downloaded (t+\${SECONDS}s)" ) &
+DL_KERNEL=\$!
+( wget -q "${MIRROR}/initramfs-lts" -O /tmp/initramfs-lts && echo "[remote] initramfs downloaded (t+\${SECONDS}s)" ) &
+DL_INITRD=\$!
+
+if [ -x /usr/sbin/kexec ] && /usr/sbin/kexec --version >/dev/null 2>&1; then
+    echo "[remote] kexec already present on the target — nothing to install"
+elif [ "$USE_CACHED_KEXEC" = 1 ] && sudo install -m 0755 /tmp/kexec-cached /usr/sbin/kexec && /usr/sbin/kexec --version >/dev/null 2>&1; then
+    echo "[remote] using host-cached kexec: \$(/usr/sbin/kexec --version 2>&1 | head -1) — package install skipped"
+else
+    echo "[remote] cached kexec unavailable or unusable — installing kexec-tools..."
+    sudo rm -f /usr/sbin/kexec   # drop a cached binary that failed its --version check
+    if command -v apt >/dev/null; then
+        sudo apt-get update -qq && sudo apt-get install -y -qq kexec-tools
+    elif command -v dnf >/dev/null; then
+        sudo dnf install -y kexec-tools
+    elif command -v yum >/dev/null; then
+        echo "[remote] busiest processes at start: \$(ps -eo comm --sort=-pcpu | sed 1d | head -4 | tr '\n' ' ') (t+\${SECONDS}s)"
+        sudo yum makecache -q
+        echo "[remote] yum metadata cached (t+\${SECONDS}s)"
+        sudo yum install -y kexec-tools
+    elif command -v apk >/dev/null; then
+        sudo apk add kexec-tools
+    else
+        echo "[remote] unknown package manager, install kexec-tools manually" >&2
+        exit 1
+    fi
+fi
+echo "[remote] kexec-tools ready (t+\${SECONDS}s)"
+
+echo "[remote] baking answerfile into an apkovl overlay..."
+rm -rf /tmp/overlay /tmp/overlay.cpio.gz
+mkdir -p /tmp/overlay/root
+echo "$ANSWERFILE_B64" | base64 -d > /tmp/overlay/root/answers
+chmod 600 /tmp/overlay/root/answers
+(cd /tmp/overlay && find . | cpio -H newc -o 2>/dev/null | gzip -9 > /tmp/overlay.cpio.gz)
+
+wait \$DL_KERNEL || { echo "[remote] kernel download failed" >&2; exit 1; }
+wait \$DL_INITRD || { echo "[remote] initramfs download failed" >&2; exit 1; }
+echo "[remote] netboot files downloaded (t+\${SECONDS}s)"
+cat /tmp/initramfs-lts /tmp/overlay.cpio.gz > /tmp/initramfs-bundled
+
+echo "[remote] staging kexec with bundled overlay..."
+sudo kexec -l /tmp/vmlinuz-lts --initrd=/tmp/initramfs-bundled \
+    --append="ip=dhcp alpine_repo=${REPO} modloop=${MIRROR}/modloop-lts console=tty0 console=ttyS0,115200"
+
+echo "[remote] KEXEC_STAGE_OK (t+\${SECONDS}s)"
+REMOTE
+SSH_EXIT=$?
+set -e
+
+if [[ $SSH_EXIT -ne 0 ]] || ! grep -q "KEXEC_STAGE_OK" "$SSH_OUT"; then
+    echo
+    echo "!! Staging FAILED (ssh exit=$SSH_EXIT). Nothing jumped." >&2
+    rm -f "$SSH_OUT"
+    exit 1
+fi
+rm -f "$SSH_OUT"
+
+echo
+echo "== Staging confirmed on remote host =="

alpine_fleet/scripts/console-connect.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+#
+# console-connect.sh — get (or create) an OCI serial console connection,
+# auto-discovering the target instance and managing a persistent RSA
+# key, then pull the connection-string out of the JSON response, patch
+# in the key + safety flags, and either print or exec the result.
+#
+# Usage:
+#   ./console-connect.sh [--instance-id <ocid>] [--key <path>] [--exec]
+#
+# --instance-id: optional. If omitted, this looks at every RUNNING
+#   instance in the compartment (via oci-common.sh). If exactly one is
+#   running, it's used automatically. If there's more than one, you'll
+#   get a list and have to re-run with --instance-id to disambiguate —
+#   this script will not guess which of several live boxes you meant.
+#
+# --key: optional, default ~/.ssh/oci-console-rsa. OCI's serial console
+#   requires an RSA key specifically — Ed25519 keys are rejected by the
+#   console proxy even though they work fine for normal instance SSH.
+#   If the key doesn't exist yet, it's generated (RSA 4096, no
+#   passphrase — needed since this runs non-interactively) and PERSISTED
+#   to disk, not thrown away after use: the console-connection resource
+#   in OCI is tied to the public key you registered when you created it,
+#   so reusing the same key on future runs lets this script find and
+#   reuse that existing connection instead of creating a new one every
+#   time (you're capped at 10 console connections per tenancy).
+#   Since there's no passphrase, treat this key file like any other
+#   unlocked credential — restrict its permissions (this script does,
+#   via `ssh-keygen`'s default 600) and don't copy it elsewhere.
+#
+# --exec: connect immediately instead of just printing the command.
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/oci-common.sh"
+
+INSTANCE_ID=""
+PRIVATE_KEY="$HOME/.ssh/oci-console-rsa"
+DO_EXEC=false
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --instance-id) INSTANCE_ID="$2"; shift 2 ;;
+        --key)         PRIVATE_KEY="$2"; shift 2 ;;
+        --exec)        DO_EXEC=true; shift ;;
+        *)
+            echo "Unknown argument: $1" >&2
+            echo "Usage: console-connect.sh [--instance-id <ocid>] [--key <path>] [--exec]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+command -v jq >/dev/null || {
+    echo "FATAL: jq is required here — the connection-string contains spaces" >&2
+    echo "and quoting that naive grep/sed would mangle. Install jq and retry." >&2
+    exit 1
+}
+
+OCI_BIN="$(oci_resolve_bin)"
+COMPARTMENT_ID="$(oci_resolve_compartment_id)"
+
+# ---- Instance auto-discovery ----
+if [ -z "$INSTANCE_ID" ]; then
+    echo "[console] no --instance-id given — looking for running instances..." >&2
+    RUNNING_JSON="$(oci_list_running_instances "$OCI_BIN" "$COMPARTMENT_ID")"
+    COUNT="$(echo "$RUNNING_JSON" | jq 'length')"
+    if [ "$COUNT" -eq 0 ]; then
+        echo "FATAL: no RUNNING instances found in this compartment." >&2
+        exit 1
+    elif [ "$COUNT" -eq 1 ]; then
+        INSTANCE_ID="$(echo "$RUNNING_JSON" | jq -r '.[0].id')"
+        NAME="$(echo "$RUNNING_JSON" | jq -r '.[0].name')"
+        echo "[console] found exactly one — using '$NAME' ($INSTANCE_ID)" >&2
+    else
+        echo "FATAL: $COUNT running instances found — ambiguous. Pick one:" >&2
+        echo "$RUNNING_JSON" | jq -r '.[] | "  \(.name)\t\(.shape)\t\(.id)"' >&2
+        echo "Re-run with: --instance-id <ocid>" >&2
+        exit 1
+    fi
+fi
+
+# ---- RSA key: reuse if present, generate+persist if not ----
+if [ -f "$PRIVATE_KEY" ]; then
+    KEY_TYPE="$(ssh-keygen -l -f "$PRIVATE_KEY" 2>/dev/null | grep -o '(RSA)' || true)"
+    if [ -z "$KEY_TYPE" ]; then
+        echo "FATAL: $PRIVATE_KEY exists but isn't an RSA key — OCI's serial" >&2
+        echo "console requires RSA specifically (Ed25519 is rejected). Pass a" >&2
+        echo "different --key path, or move this file aside and re-run to" >&2
+        echo "generate a fresh RSA key at the default path." >&2
+        exit 1
+    fi
+    echo "[console] reusing existing RSA key at $PRIVATE_KEY" >&2
+else
+    echo "[console] no key at $PRIVATE_KEY — generating a new RSA 4096 key..." >&2
+    mkdir -p "$(dirname "$PRIVATE_KEY")"
+    ssh-keygen -t rsa -b 4096 -N "" -f "$PRIVATE_KEY" -C "oci-console-connect" >&2
+fi
+PUB_KEY="${PRIVATE_KEY}.pub"
+
+# ---- Find or create the console connection ----
+echo "[console] checking for an existing active console connection..." >&2
+EXISTING_JSON="$("$OCI_BIN" compute instance-console-connection list \
+    --compartment-id "$COMPARTMENT_ID" \
+    --instance-id "$INSTANCE_ID" \
+    --output json)"
+
+CONN_ID="$(echo "$EXISTING_JSON" | jq -r '.data[] | select(."lifecycle-state"=="ACTIVE") | .id' | head -1)"
+
+if [ -z "$CONN_ID" ] || [ "$CONN_ID" = "null" ]; then
+    echo "[console] none found — creating one (this can take ~30-60s)..." >&2
+    CONN_JSON="$("$OCI_BIN" compute instance-console-connection create \
+        --instance-id "$INSTANCE_ID" \
+        --ssh-public-key-file "$PUB_KEY" \
+        --wait-for-state ACTIVE \
+        --output json)"
+else
+    echo "[console] reusing existing active connection $CONN_ID" >&2
+    CONN_JSON="$("$OCI_BIN" compute instance-console-connection get \
+        --instance-console-connection-id "$CONN_ID" \
+        --output json)"
+fi
+
+RAW_CONN_STR="$(echo "$CONN_JSON" | jq -r '.data."connection-string"')"
+if [ -z "$RAW_CONN_STR" ] || [ "$RAW_CONN_STR" = "null" ]; then
+    echo "FATAL: could not extract connection-string from the JSON response:" >&2
+    echo "$CONN_JSON" >&2
+    exit 1
+fi
+
+# Two nested ssh invocations — outer + ProxyCommand — both need: the
+# private key (OCI's string never embeds a key path; it assumes
+# ssh-agent or a default identity, which won't be true here),
+# ControlPath=none (the proxy's long OCID-as-username + hostname
+# routinely blows past the ~104-108 byte Unix socket path limit on the
+# default multiplexing ControlPath template), and disabled strict host
+# checking (the console's host key has nothing to do with the
+# instance's own).
+SAFE_FLAGS="-i ${PRIVATE_KEY} -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ControlPath=none"
+
+# Bash parameter-expansion global replace — avoids sed delimiter clashes
+# with slashes in $PRIVATE_KEY.
+PATCHED="${RAW_CONN_STR//ssh /ssh $SAFE_FLAGS }"
+
+echo "$PATCHED"
+
+if $DO_EXEC; then
+    echo "[console] connecting..." >&2
+    exec bash -c "$PATCHED"
+fi