yolo.rugo

# yolo.rugo — fast persistent matchlock VMs, one per directory.
#
# Usage:
#   yolo                        Attach (or create) the VM for $PWD; drop into bash.
#   yolo -- CMD ARGS...         Run CMD inside that VM (auto-create if needed).
#   yolo -n NAME [...]          Use a named VM instead of the per-CWD one.
#   yolo ls                     List all yolo-tracked VMs with live status.
#   yolo stop [-n NAME]         Stop the VM (state preserved on disk).
#   yolo rm   [-n NAME]         Stop + remove the VM and its name binding.
#   yolo logs [-n NAME]         Show the VM's log.
#   yolo id   [-n NAME]         Print the vm-id only (for scripting).
#   yolo status [-n NAME]       Print "<state> (<vm-id>)".
#   yolo prune                  Drop dead name bindings (VM gone).
#
# Env tweaks:
#   YOLO_IMAGE      (default: fedora:44)
#   YOLO_ALLOW      (default: *)               comma list of allowed hostnames
#   YOLO_WORKSPACE  (default: /work)           guest mount point for $PWD
#   YOLO_NAME       (default: cwd-<sha1>)      override the auto-derived name
#   YOLO_USER       (default: unset)           pass --user to matchlock

use "os"
use "str"
use "color"
use "crypto"
use "fmt"
use "filepath"
use "conv"
use "time"

# ---------------- Backends ----------------
# Each backend lives at `backends/<name>.rugo` and exposes a `make()` factory
# returning a handle (hash of constants + closure-valued methods). The
# contract is documented in backends/INTERFACE.md.
#
# Adding a new backend: drop a `backends/<name>.rugo` file, then add it to
# both the `require` line below and the BACKENDS registry.
require "backends" with matchlock, podman

# CLI parsing + help text and Yolofile parsing / front-matter validation
# both live in sibling modules to keep this file from sprawling further.
# They're pure (no state) — yolo.rugo's main block passes in the bits of
# context they need (BACKENDS, AI_AGENTS, VERSION) since Rugo modules can
# only see what they require, never the other direction.
require "cli"
require "yolofile"

BACKENDS = {
  "matchlock" => matchlock.make(),
  "podman"    => podman.make()
}
DEFAULT_BACKEND = "matchlock"

# ---------------- Embedded provisioners ----------------
# Each provisioner is a plain bash script that runs INSIDE the guest VM as
# root, piped through the backend's exec_provision channel. Drop additional
# ones at provisioners/provisioner-<name>.sh and embed them here.
embed "provisioners/provisioner-fedora-go.sh"      as prov_fedora_go
embed "provisioners/provisioner-fedora-rust.sh"    as prov_fedora_rust
embed "provisioners/provisioner-fedora-ruby.sh"    as prov_fedora_ruby
embed "provisioners/provisioner-fedora-android.sh" as prov_fedora_android

PROVISIONERS = {
  "fedora-go"      => prov_fedora_go,
  "fedora-rust"    => prov_fedora_rust,
  "fedora-ruby"    => prov_fedora_ruby,
  "fedora-android" => prov_fedora_android
}

# No hard default — when no provisioner is explicitly requested and no
# Yolofile exists, we sniff $PWD for language signals (see detect_provisioner).
# An empty result means "skip provisioning".
DEFAULT_PROVISIONER = ""

# ---------------- AI agent installers ----------------
# Layered on top of any language provisioner via the --ai-agent flag.
# Each is a plain bash script that runs as root in the guest.
embed "provisioners/ai-agents/copilot.sh"  as agent_copilot
embed "provisioners/ai-agents/opencode.sh" as agent_opencode

AI_AGENTS = {
  "copilot"  => agent_copilot,
  "opencode" => agent_opencode
}
DEFAULT_AI_AGENT = "opencode"

# ---------------- Embedded skills ----------------
# Agent skills shipped with yolo. `yolo install-skills` writes each into
# ~/.agents/skills/<name>/SKILL.md so AI coding agents can load them. Add new
# ones under skills/<name>/SKILL.md and embed them here.
embed "skills/yolo-user/SKILL.md"       as skill_yolo_user
embed "skills/yolofile-author/SKILL.md" as skill_yolofile_author
embed "skills/yolo-developer/SKILL.md"  as skill_yolo_developer

SKILLS = {
  "yolo-user"       => skill_yolo_user,
  "yolofile-author" => skill_yolofile_author,
  "yolo-developer"  => skill_yolo_developer
}

# ---------------- Config ----------------
# Bump this on every release tag (also bumped by hand on `main` after a
# release so `main` builds advertise a `-dev` suffix).
VERSION = "0.2.1"

def env_or(name, fallback)
  v = os.getenv(name)
  if v == ""
    return fallback
  end
  return v
end

IMAGE     = env_or("YOLO_IMAGE",     "")
# Setting YOLO_ALLOW enables matchlock's MITM proxy and restricts egress to the
# listed hosts. Leave empty (default) for plain NAT — the guest gets real
# Internet cert chains, so dnf/curl/go-install work out of the box. Once you
# set this you'll also need to trust matchlock's per-VM CA in the guest (or
# use --no-check-cert flags), since MITM rewrites every TLS cert chain.
ALLOW     = env_or("YOLO_ALLOW",     "")
WORKSPACE = env_or("YOLO_WORKSPACE", "/work")
# Resource defaults — bigger than matchlock's stock 1 CPU / 512 MB / 5 GB,
# because building Go dev tools (or anything similar) on the stock allocation
# runs out of disk and is painfully slow. Override per env var if needed.
CPUS      = env_or("YOLO_CPUS",      "2")
MEM_MB    = env_or("YOLO_MEM_MB",    "2048")
DISK_MB   = env_or("YOLO_DISK_MB",   "32768")
RUNTIME   = env_or("XDG_RUNTIME_DIR", "/tmp")
STATE_DIR = filepath.join(RUNTIME, "yolo")
USER_FLAG = env_or("YOLO_USER", "")
BACKEND_ENV = env_or("YOLO_BACKEND", "")

# Mutable per-invocation overrides for the VM-creation resource settings.
# Initialized to the env-var-or-default constants above. Yolofile front matter
# (parsed in main for vm-creating subcommands) and per-flag CLI overrides
# (e.g. `--disk-size`) replace these before the first backend `start()` call.
disk_mb = DISK_MB
mem_mb  = MEM_MB
cpus    = CPUS
image   = IMAGE

# Mutable backend selection. Empty means "let resolve_backend_name() fall back
# through the cascade". Set by --backend / YOLO_BACKEND / Yolofile front matter
# before any vm-creating subcommand runs. Sticky bindings (<name>.backend) take
# precedence over this in resolve_backend_name().
backend_sel = BACKEND_ENV

# GUI mode requested for this invocation. Honoured by backends where
# SUPPORTS_GUI is true; refused at the CLI layer otherwise.
gui_enabled = false

# Audio passthrough requested for this invocation. Honoured by backends
# where SUPPORTS_AUDIO is true; refused at the CLI layer otherwise.
audio_enabled = false

# Host directory mounted at WORKSPACE. Normal runs mount the invoking cwd;
# --ephemeral replaces this with a fresh temporary directory.
host_workspace = os.cwd()

# Optional explicit Yolofile source, set by --yolofile. May be a local path or
# an https:// URL; resolved once in main before provisioning/resource parsing.
yolofile_override = ""
yolofile_override_display = ""
yolofile_override_content = ""

# Ephemeral runs use generated state names and are removed when attach exits.
ephemeral_mode = false
ephemeral_workspace = ""

mkdir -p "#{STATE_DIR}"

# ---------------- Logging ----------------
def log(msg)
  prefix = color.dim("[yolo]")
  puts "#{prefix} #{msg}"
end
def warn(msg)
  prefix = color.dim("[yolo]")
  puts "#{prefix} #{color.yellow(msg)}"
end
def err_(msg)
  prefix = color.dim("[yolo]")
  puts "#{prefix} #{color.red(msg)}"
end

# ---------------- Backend dispatch ----------------
# Every per-name state file has a sibling <name>.backend recording which
# backend owns it. read_backend(name) falls back to DEFAULT_BACKEND so
# pre-existing yolo state (no .backend file) keeps working as matchlock.
def backend_file(name)
  return filepath.join(STATE_DIR, "#{name}.backend")
end
def read_backend(name)
  path = backend_file(name)
  if !os.file_exists(path)
    return ""
  end
  return str.trim(os.read_file(path))
end
def write_backend(name, b)
  os.write_file(backend_file(name), b + "\n")
end
def remove_backend_file(name)
  path = backend_file(name)
  if os.file_exists(path)
    os.remove(path)
  end
end

# Selection cascade (highest wins):
#   1. <name>.backend if already recorded (sticky once a VM has been created)
#   2. --backend CLI flag                  (parsed.backend, mutable global)
#   3. YOLO_BACKEND env var
#   4. Yolofile front matter `backend:`    (applied to global `backend_sel`
#      from main, like cpus/mem_mb/etc.)
#   5. DEFAULT_BACKEND
def resolve_backend_name(name)
  existing = read_backend(name)
  if existing != ""
    if BACKENDS[existing] == nil
      err_("name '#{name}' was created with unknown backend '#{existing}' — install it or `yolo rm -n #{name}`")
      os.exit(1)
    end
    return existing
  end
  if backend_sel != ""
    if BACKENDS[backend_sel] == nil
      err_("unknown backend '#{backend_sel}' (known: #{known_backends()})")
      os.exit(2)
    end
    return backend_sel
  end
  return DEFAULT_BACKEND
end

def backend_for(name)
  return BACKENDS[resolve_backend_name(name)]
end

def known_backends
  names = []
  for n in BACKENDS
    names = append(names, n)
  end
  return str.join(names, ", ")
end

def vm_status(id, table)
  if id == "" || id == nil
    return ""
  end
  row = table[id]
  if row == nil
    return ""
  end
  return row[0]
end

# POSIX shell-quote: wrap in single quotes; escape internal `'` as `'\''`.
# Lossless under bash word-splitting — the original string round-trips.
def shell_quote(s)
  return "'" + str.replace(s, "'", "'\\''") + "'"
end

# Quote each element of an argv and join with spaces. The result is a bash
# command line that, when re-parsed by bash, yields the original argv.
def shell_join(args)
  parts = []
  for a in args
    parts = append(parts, shell_quote(a))
  end
  return str.join(parts, " ")
end

def safe_ephemeral_name
  seed = "#{os.cwd()}:#{os.pid()}:#{time.now()}"
  h = crypto.sha1(seed)
  return "tmp-" + str.slice(h, 0, 12)
end

def make_temp_workspace
  base = os.tmp_dir()
  seed = "#{os.pid()}-#{str.slice(crypto.sha1(os.cwd() + conv.to_s(time.now())), 0, 8)}"
  p = filepath.join(base, "yolo-ephemeral-#{seed}")
  made = try `bash -c "mkdir -p #{shell_quote(p)} && echo OK"` or ""
  if str.trim(made) != "OK"
    err_("failed to create ephemeral workspace at #{p}")
    os.exit(1)
  end
  return p
end

def cleanup_ephemeral(name)
  if ephemeral_mode != true
    return
  end
  log("cleaning up ephemeral VM #{color.bold(name)}")
  cmd_rm(name)
  if ephemeral_workspace != ""
    try `bash -c "rm -rf #{shell_quote(ephemeral_workspace)}"` or nil
  end
end

def release_and_exit(name, code)
  release_lock(name)
  cleanup_ephemeral(name)
  os.exit(code)
end

def read_yolofile_source(src)
  if src == ""
    return {display: "", content: "", err: ""}
  end
  if str.starts_with(src, "http://")
    return {display: src, content: "", err: "Yolofile URLs must use https://"}
  end
  if str.starts_with(src, "https://")
    cmd = "curl -fsSL --proto '=https' --tlsv1.2 " + shell_quote(src)
    body = try os.exec(cmd) or msg
        return {display: src, content: "", err: "failed to fetch #{src}: #{msg}"}
      end
    return {display: src, content: body, err: ""}
  end
  p = src
  if !str.starts_with(p, "/")
    p = filepath.join(os.cwd(), p)
  end
  if !yolofile.exists_at(p)
    return {display: p, content: "", err: "Yolofile not found: #{p}"}
  end
  return {display: p, content: os.read_file(p), err: ""}
end

def active_yolofile_exists
  if yolofile_override != ""
    return true
  end
  if ephemeral_mode == true
    return false
  end
  return yolofile.exists()
end

def active_yolofile_display
  if yolofile_override != ""
    return yolofile_override_display
  end
  return yolofile.path()
end

def parse_active_yolofile
  if yolofile_override != ""
    return yolofile.parse_content(yolofile_override_content)
  end
  return yolofile.read_and_parse()
end

# Start a fresh VM bound to $name. Returns the new vm-id.
def start_vm(name)
  be = backend_for(name)
  # Refuse incompatible combinations before touching state or logging.
  if gui_enabled && be.SUPPORTS_GUI == false
    err_("backend '#{be.NAME}' does not support GUI mode (use --backend podman)")
    os.exit(2)
  end
  if audio_enabled && be.SUPPORTS_AUDIO == false
    err_("backend '#{be.NAME}' does not support audio passthrough (use --backend podman)")
    os.exit(2)
  end
  # Per-name image pin (from `yolo import`) overrides the global default so
  # an imported VM boots from its custom OCI image instead of the backend
  # default. If neither is set, use the global `image` (which may itself
  # have been set from a Yolofile / env / default).
  img = read_image(name)
  if img == ""
    img = image
  end
  if img == ""
    img = be.DEFAULT_IMAGE
  end
  log("starting #{color.bold(img)} VM #{color.bold(name)} for #{host_workspace} [#{be.NAME}]")
  opts = {
    "name"      => name,
    "image"     => img,
    "cpus"      => cpus,
    "mem_mb"    => mem_mb,
    "disk_mb"   => disk_mb,
    "workspace" => WORKSPACE,
    "cwd"       => host_workspace,
    "user"      => USER_FLAG,
    "allow"     => ALLOW,
    "gui"       => gui_enabled,
    "audio"     => audio_enabled
  }
  id = be.start(opts)
  os.write_file(state_file(name), id)
  write_backend(name, be.NAME)
  record_cwd(name)
  # If an imported `.applied` file is waiting with the __IMPORTED__ sentinel,
  # rewrite its first line to the new vm-id so the markers stick to this VM
  # and provisioners skip re-running (their effects are already in the image).
  rebind_imported_applied(name, id)
  be.wait_ready(id)
  return id
end

def state_file(name)
  return filepath.join(STATE_DIR, "#{name}.vmid")
end

def applied_file(name)
  return filepath.join(STATE_DIR, "#{name}.applied")
end

def cwd_file(name)
  return filepath.join(STATE_DIR, "#{name}.cwd")
end

# Per-name image pin (set by `yolo import`). When present, start_vm uses this
# image ref instead of $YOLO_IMAGE / fedora:44 — this is how an imported VM's
# rootfs modifications survive: the rootfs is registered as a matchlock OCI
# image and pinned here.
def image_file(name)
  return filepath.join(STATE_DIR, "#{name}.image")
end

def read_image(name)
  path = image_file(name)
  if !os.file_exists(path)
    return ""
  end
  return str.trim(os.read_file(path))
end

def write_image(name, tag)
  os.write_file(image_file(name), tag + "\n")
end

def remove_image(name)
  path = image_file(name)
  if os.file_exists(path)
    os.remove(path)
  end
end

# Sentinel used in <name>.applied right after import: the real vm-id is not
# known yet (the VM doesn't exist), so we store this and let start_vm rewrite
# line 1 once the VM is created. See rebind_imported_applied().
IMPORTED_SENTINEL = "__IMPORTED__"

# If <name>.applied was written by `yolo import` with the IMPORTED_SENTINEL as
# line 1, replace that line with the freshly-allocated vm-id so the existing
# applied_list()/is_applied() logic recognises the markers and skips re-running
# provisioners (their effects are already baked into the imported image).
def rebind_imported_applied(name, vm_id)
  path = applied_file(name)
  if !os.file_exists(path)
    return
  end
  content = os.read_file(path)
  lines = []
  for line in str.each_line(content)
    t = str.trim(line)
    if t != ""
      lines = append(lines, t)
    end
  end
  if len(lines) == 0
    return
  end
  if lines[0] != IMPORTED_SENTINEL
    return
  end
  body = vm_id
  i = 1
  while i < len(lines)
    body = body + "\n" + lines[i]
    i = i + 1
  end
  os.write_file(path, body + "\n")
  log("rebound imported provisioner markers to #{vm_id}")
end

def read_cwd(name)
  path = cwd_file(name)
  if !os.file_exists(path)
    return ""
  end
  return str.trim(os.read_file(path))
end

def record_cwd(name)
  os.write_file(cwd_file(name), host_workspace)
end

def read_state(name)
  path = state_file(name)
  if !os.file_exists(path)
    return ""
  end
  return str.trim(os.read_file(path))
end

# Read provisioners already applied to the *current* vm-id. If the marker is
# stale (vm-id mismatch, e.g. after auto-heal recreated the VM), returns [].
def applied_list(name, vm_id)
  path = applied_file(name)
  if !os.file_exists(path)
    return []
  end
  content = os.read_file(path)
  lines = []
  for line in str.each_line(content)
    trimmed = str.trim(line)
    if trimmed != ""
      lines = append(lines, trimmed)
    end
  end
  if len(lines) < 1
    return []
  end
  if lines[0] != vm_id
    return []
  end
  out = []
  i = 1
  while i < len(lines)
    out = append(out, lines[i])
    i = i + 1
  end
  return out
end

def is_applied(name, vm_id, prov_name)
  for p in applied_list(name, vm_id)
    if p == prov_name
      return true
    end
  end
  return false
end

def mark_applied(name, vm_id, prov_name)
  list = applied_list(name, vm_id)
  found = false
  for p in list
    if p == prov_name
      found = true
    end
  end
  if !found
    list = append(list, prov_name)
  end
  body = vm_id
  for p in list
    body = body + "\n" + p
  end
  os.write_file(applied_file(name), body + "\n")
end

# ---------------- Inter-process lock (per name) ----------------
# Prevents two concurrent `yolo`s on the same name from racing during VM
# creation / provisioning. We use atomic mkdir() as the lock primitive: it
# returns success only if it created the directory, failure if it existed.
# On stale locks (process died), the PID liveness check reclaims them.

def lock_dir(name)
  return filepath.join(STATE_DIR, "#{name}.lock")
end

def acquire_lock(name, label)
  ld = lock_dir(name)
  warned = false
  iter = 0
  while true
    made = try `bash -c "mkdir #{ld} 2>/dev/null && echo OK"` or ""
    if str.trim(made) == "OK"
      os.write_file(filepath.join(ld, "pid"), "#{os.pid()}")
      os.write_file(filepath.join(ld, "label"), label)
      return
    end
    # Lock is held; check if the holder is still alive.
    pid_file = filepath.join(ld, "pid")
    holder_pid = ""
    holder_label = "?"
    if os.file_exists(pid_file)
      holder_pid = str.trim(os.read_file(pid_file))
    end
    lf = filepath.join(ld, "label")
    if os.file_exists(lf)
      holder_label = str.trim(os.read_file(lf))
    end
    if holder_pid != ""
      raw = try `bash -c "/bin/kill -0 #{holder_pid} 2>/dev/null && echo y || echo n"` or "n"
      alive = str.trim(raw)
      if alive == "n"
        warn("removing stale lock for '#{name}' (pid #{holder_pid} dead)")
        try `bash -c "rm -rf #{ld}"` or nil
        warned = false
        iter = 0
        next
      end
    end
    if !warned
      log("waiting for another yolo (#{holder_label}, pid #{holder_pid})...")
      warned = true
    end
    sleep 0.5
    iter = iter + 1
  end
end

def release_lock(name)
  ld = lock_dir(name)
  try `bash -c "rm -rf #{ld}"` or nil
end

# Ensure a running VM bound to $name; auto-heal stopped/missing.
# Behavior depends on the backend's PERSISTS_ON_STOP capability:
#   - false (matchlock): anything not "running" => recreate from scratch.
#   - true  (podman):    a stopped/exited container is resumed via be.resume()
#                        which preserves in-container state; recreation only
#                        happens when the binding is missing entirely.
def ensure_vm(name)
  id = read_state(name)
  be = backend_for(name)
  table = be.list_table()
  status = vm_status(id, table)
  if status == "running"
    return id
  end
  if status != "" && be.PERSISTS_ON_STOP == true && id != ""
    log("resuming stopped #{id} for '#{name}'")
    be.resume(id)
    be.wait_ready(id)
    return id
  end
  if status == ""
    if id != ""
      warn("tracked VM #{id} is gone; recreating")
      os.remove(state_file(name))
    end
  else
    warn("VM #{id} is in state '#{status}'; recreating")
    be.remove(id)
    os.remove(state_file(name))
  end
  return start_vm(name)
end

# CLI arg parsing, --help, --version, and --disk-size value parsing all
# live in cli.rugo. See that module for the full flag table and the
# returned hash shape.

def default_name
  override = env_or("YOLO_NAME", "")
  if override != ""
    return override
  end
  h = crypto.sha1(os.cwd())
  return "cwd-" + str.slice(h, 0, 10)
end

# ---------------- Subcommands ----------------

# Collapse $HOME to ~ for display.
def display_path(p)
  if p == ""
    return color.dim("—")
  end
  home = os.getenv("HOME")
  if home != "" && str.starts_with(p, home)
    return "~" + str.slice(p, len(home), len(p))
  end
  return p
end

# Build a {backend_name => list_table} cache so multi-name commands (ls, du,
# prune) make at most one runtime call per backend even when names span
# different backends.
def collect_tables
  out = {}
  files = try filepath.glob(filepath.join(STATE_DIR, "*.vmid")) or []
  for f in files
    n = str.trim_suffix(filepath.base(f), ".vmid")
    bn = read_backend(n)
    if bn == ""
      bn = DEFAULT_BACKEND
    end
    if out[bn] == nil
      be = BACKENDS[bn]
      if be == nil
        out[bn] = {}
      else
        out[bn] = be.list_table()
      end
    end
  end
  return out
end

def cmd_ls
  tables = collect_tables()
  printf_hdr()
  seen = {}
  files = try filepath.glob(filepath.join(STATE_DIR, "*.vmid")) or []
  for f in files
    n = str.trim_suffix(filepath.base(f), ".vmid")
    seen[n] = true
    id = str.trim(os.read_file(f))
    bn = read_backend(n)
    if bn == ""
      bn = DEFAULT_BACKEND
    end
    table = tables[bn]
    if table == nil
      table = {}
    end
    row = table[id]
    if row == nil
      st = "gone"
      im = "—"
    else
      st = row[0]
      im = row[1]
    end
    cwd = read_cwd(n)
    print_row(n, id, st, im, display_path(cwd))
  end
  # Imported-but-not-yet-started names: have <name>.image but no <name>.vmid.
  img_files = try filepath.glob(filepath.join(STATE_DIR, "*.image")) or []
  for f in img_files
    n = str.trim_suffix(filepath.base(f), ".image")
    if seen[n] == true
      # already printed (running/stopped/gone)
    else
      tag = str.trim(os.read_file(f))
      cwd = read_cwd(n)
      print_row(n, "—", "imported", tag, display_path(cwd))
    end
  end
end

def printf_hdr
  fmt.printf("%-25s  %-20s  %-12s  %-18s  %s\n", "NAME", "VM-ID", "STATUS", "IMAGE", "CWD")
end

def print_row(name, id, st, im, cwd_disp)
  if st == "running"
    st_c = color.green(fmt.sprintf("%-12s", st))
  elsif st == "gone"
    st_c = color.red(fmt.sprintf("%-12s", st))
  elsif st == "imported"
    st_c = color.yellow(fmt.sprintf("%-12s", st))
  else
    st_c = color.dim(fmt.sprintf("%-12s", st))
  end
  fmt.printf("%-25s  %-20s  %s  %-18s  %s\n", name, id, st_c, im, cwd_disp)
end

def cmd_stop(name)
  id = read_state(name)
  if id == ""
    warn("no VM tracked for '#{name}'")
    return
  end
  be = backend_for(name)
  be.stop(id)
  log("stopped #{id} (#{name})")
end

def cmd_rm(name)
  id = read_state(name)
  pinned_image = read_image(name)
  if id == "" && pinned_image == ""
    warn("no VM tracked for '#{name}'")
    return
  end
  be = backend_for(name)
  if id != ""
    be.remove(id)
    os.remove(state_file(name))
  end
  ap = applied_file(name)
  if os.file_exists(ap)
    os.remove(ap)
  end
  cf = cwd_file(name)
  if os.file_exists(cf)
    os.remove(cf)
  end
  remove_image(name)
  # If the pinned image was created by `yolo import`, drop it from the
  # backend's image store too — but only when no other yolo name still pins
  # the same tag. We restrict this to yolo-import/* to avoid removing
  # user-supplied images.
  if pinned_image != "" && str.starts_with(pinned_image, "yolo-import/")
    if !image_pinned_elsewhere(pinned_image)
      be.image_remove(pinned_image)
      log("removed imported image #{pinned_image}")
    end
  end
  remove_backend_file(name)
  # Best-effort: drop any stale lock dir for this name.
  ld = lock_dir(name)
  try `bash -c "rm -rf #{ld}"` or nil
  if id != ""
    log("removed #{id} (#{name})")
  else
    log("removed imported binding (#{name})")
  end
end

# Scan all *.image state files to see if any name pins `tag`. Used to decide
# whether `image_remove` is safe in cmd_rm (we call this AFTER removing the
# binding for the name being deleted, so a `true` result means another
# binding still references it).
def image_pinned_elsewhere(tag)
  files = try filepath.glob(filepath.join(STATE_DIR, "*.image")) or []
  for f in files
    other = str.trim(os.read_file(f))
    if other == tag
      return true
    end
  end
  return false
end

def cmd_logs(name, extra)
  id = read_state(name)
  if id == ""
    err_("no VM tracked for '#{name}'")
    os.exit(1)
  end
  be = backend_for(name)
  be.logs(id, extra)
end

def cmd_id(name)
  id = read_state(name)
  if id != ""
    puts id
  end
end

def cmd_status(name)
  id = read_state(name)
  pinned = read_image(name)
  if id == ""
    if pinned != ""
      puts "imported (no vm yet) image: #{pinned}"
    else
      puts "untracked"
    end
    return
  end
  be = backend_for(name)
  table = be.list_table()
  st = vm_status(id, table)
  if st == ""
    st = "gone"
  end
  applied = applied_list(name, id)
  suffix = ""
  if pinned != ""
    suffix = " image: #{pinned}"
  end
  if len(applied) == 0
    puts "#{st} (#{id}) applied: -#{suffix}"
  else
    csv = str.join(applied, ",")
    puts "#{st} (#{id}) applied: #{csv}#{suffix}"
  end
end

def cmd_prune
  files = try filepath.glob(filepath.join(STATE_DIR, "*.vmid")) or []
  tables = collect_tables()
  for f in files
    id = str.trim(os.read_file(f))
    n = str.trim_suffix(filepath.base(f), ".vmid")
    bn = read_backend(n)
    if bn == ""
      bn = DEFAULT_BACKEND
    end
    table = tables[bn]
    if table == nil
      table = {}
    end
    if vm_status(id, table) == ""
      log("pruning #{n} → #{id} (gone)")
      os.remove(f)
      ap = applied_file(n)
      if os.file_exists(ap)
        os.remove(ap)
      end
      cf = cwd_file(n)
      if os.file_exists(cf)
        os.remove(cf)
      end
      remove_backend_file(n)
    end
  end
end

# Format a byte count as a human-readable string.
def human_bytes(n)
  if n < 1024
    return fmt.sprintf("%d B", n)
  end
  k = n / 1024.0
  if k < 1024.0
    return fmt.sprintf("%.1f KiB", k)
  end
  m = k / 1024.0
  if m < 1024.0
    return fmt.sprintf("%.1f MiB", m)
  end
  g = m / 1024.0
  return fmt.sprintf("%.2f GiB", g)
end

def cmd_du
  tables = collect_tables()
  fmt.printf("%-25s  %-20s  %-10s  %-12s  %s\n", "NAME", "VM-ID", "STATUS", "USED", "ALLOCATED")
  files = try filepath.glob(filepath.join(STATE_DIR, "*.vmid")) or []
  total_real = 0
  total_app = 0
  for f in files
    n = str.trim_suffix(filepath.base(f), ".vmid")
    id = str.trim(os.read_file(f))
    bn = read_backend(n)
    if bn == ""
      bn = DEFAULT_BACKEND
    end
    be = BACKENDS[bn]
    real_b = -1
    app_b  = -1
    if be != nil
      real_b = be.disk_real(id)
      app_b  = be.disk_apparent(id)
    end
    if real_b < 0
      real_str = color.dim(fmt.sprintf("%-12s", "—"))
    else
      total_real = total_real + real_b
      real_str = fmt.sprintf("%-12s", human_bytes(real_b))
    end
    if app_b < 0
      app_str = color.dim("—")
    else
      total_app = total_app + app_b
      app_str = human_bytes(app_b)
    end
    table = tables[bn]
    if table == nil
      table = {}
    end
    st = vm_status(id, table)
    if st == ""
      st = "gone"
    end
    if st == "running"
      st_c = color.green(fmt.sprintf("%-10s", st))
    elsif st == "gone"
      st_c = color.red(fmt.sprintf("%-10s", st))
    else
      st_c = color.dim(fmt.sprintf("%-10s", st))
    end
    n_pad = fmt.sprintf("%-25s", n)
    id_pad = fmt.sprintf("%-20s", id)
    puts "#{n_pad}  #{id_pad}  #{st_c}  #{real_str}  #{app_str}"
  end
  # Total row: pad the whole prefix to the USED column, then write both
  # totals without further format-string padding (ANSI codes throw it off).
  prefix = fmt.sprintf("%-61s", "TOTAL")
  real_total_s = color.bold(fmt.sprintf("%-12s", human_bytes(total_real)))
  app_total_s  = color.bold(human_bytes(total_app))
  puts "#{prefix}#{real_total_s}  #{app_total_s}"
end

def cmd_attach(name, passthrough, prov_name, no_prov, agent_name)
  acquire_lock(name, "setup")
  id = ensure_vm(name)
  be = backend_for(name)

  if !no_prov
    # Resolve once. marker is content-hashed so source edits trigger a re-run.
    resolved = resolve_provisioner(prov_name)
    pname = resolved.name
    if pname == ""
      if ephemeral_mode == true
        log("ephemeral run has no provisioner — skipping (use --provisioner NAME or --yolofile PATH|URL)")
      else
        log("no provisioner detected for #{os.cwd()} — skipping (use --provisioner NAME or add a Yolofile)")
      end
    elsif resolved.src == ""
      err_("unknown provisioner '#{prov_name}'")
      release_and_exit(name, 1)
    elsif !is_applied(name, id, resolved.marker)
      if ephemeral_mode == true
        try apply_provisioner(name, id, prov_name) or err
          err_(err)
          release_and_exit(name, 1)
        end
      else
        apply_provisioner(name, id, prov_name)
      end
      mark_applied(name, id, resolved.marker)
    end
  end

  # Optional: layer an AI agent on top. Tracked separately, also content-hashed.
  if agent_name != ""
    agent_src = AI_AGENTS[agent_name]
    if agent_src == nil
      err_("unknown ai-agent '#{agent_name}'")
      release_and_exit(name, 1)
    end
    agent_short = str.slice(crypto.sha256(agent_src), 0, 12)
    agent_marker = "ai-agent:#{agent_name}:#{agent_short}"
    if !is_applied(name, id, agent_marker)
      if ephemeral_mode == true
        try apply_agent(id, agent_name, name) or err
          err_(err)
          release_and_exit(name, 1)
        end
      else
        apply_agent(id, agent_name, name)
      end
      mark_applied(name, id, agent_marker)
    end
  end

  # Release the lock BEFORE attaching: the interactive shell may run forever,
  # and we want other terminals to be able to attach concurrently to the
  # already-set-up VM.
  release_lock(name)

  # Only request a PTY (`-t`) when stdin is itself a terminal — same convention
  # docker / podman use. Without this, `yolo -- cmd` from a script, CI job, or
  # SSH session without `-t` fails with `matchlock: -it requires a TTY`.
  # Probe the controlling TTY via </dev/tty rather than the spawned shell's
  # own stdin: rugo's captured backtick gives the child a non-TTY stdin
  # (it's a captured-output shell), so `[ -t 0 ]` always reads false even
  # from an interactive terminal. /dev/tty opens the controlling terminal
  # directly if there is one, and fails (caught by `try`) when there isn't
  # (CI, scripted, SSH without a TTY).
  tty_check = try `bash -c "[ -t 0 ] && printf t" </dev/tty 2>/dev/null` or ""
  it_flag = "-i"
  if str.trim(tty_check) == "t"
    it_flag = "-it"
  end

  if ephemeral_mode == true
    exec_ok = true
    exec_err = ""
    if len(passthrough) == 0
      try be.exec_shell(id, WORKSPACE, it_flag) or err
        exec_ok = false
        exec_err = err
      end
    else
      argv = shell_join(passthrough)
      try be.exec_argv(id, WORKSPACE, it_flag, argv) or err
        exec_ok = false
        exec_err = err
      end
    end
    cleanup_ephemeral(name)
    if exec_ok != true
      if exec_err != ""
        err_(exec_err)
      end
      os.exit(1)
    end
  else
    if len(passthrough) == 0
      be.exec_shell(id, WORKSPACE, it_flag)
    else
      argv = shell_join(passthrough)
      be.exec_argv(id, WORKSPACE, it_flag, argv)
    end
  end
end

# List all embedded provisioners. Marks the one that would be auto-selected.
# Install the embedded agent skills into ~/.agents/skills/<name>/SKILL.md.
# Pure local operation — no VM, backend, or Yolofile involved. Existing
# files are overwritten so re-running updates them to the shipped version.
def cmd_install_skills
  home = os.getenv("HOME")
  if home == ""
    err_("cannot install skills: HOME is not set")
    os.exit(1)
  end
  base = filepath.join(filepath.join(home, ".agents"), "skills")
  log("installing skills into #{color.bold(base)}")
  count = 0
  for name in SKILLS
    dir = filepath.join(base, name)
    made = try `bash -c "mkdir -p #{shell_quote(dir)} && echo OK"` or ""
    if str.trim(made) != "OK"
      err_("failed to create #{dir}")
      os.exit(1)
    end
    dest = filepath.join(dir, "SKILL.md")
    action = "installed"
    if os.file_exists(dest)
      action = "updated "
    end
    os.write_file(dest, SKILLS[name])
    log("  #{action} #{color.bold(name)}")
    count = count + 1
  end
  suffix = ""
  if count != 1
    suffix = "s"
  end
  log("done — #{count} skill#{suffix} in #{base}")
end

def cmd_provisioners
  auto = ""
  default_label = ""
  if active_yolofile_exists()
    yp = active_yolofile_display()
    default_label = "Yolofile (#{yp})"
  else
    if ephemeral_mode == true
      auto = ""
    else
      auto = detect_provisioner()
    end
    cwd = os.cwd()
    if auto == ""
      default_label = "(none — no Yolofile, no language signals in #{cwd})"
    else
      default_label = "#{auto}  [auto-detected from #{cwd}]"
    end
  end
  puts "Available provisioners (default: #{default_label}):"
  for n in PROVISIONERS
    marker = "  "
    if !active_yolofile_exists() && n == auto
      marker = color.green("* ")
    end
    puts "#{marker}#{n}"
  end
  if active_yolofile_exists()
    star = color.green("* ")
    yp = active_yolofile_display()
    puts "#{star}yolofile  (#{yp})"
  end
  puts ""
  puts "AI agents (opt in with --ai-agent [NAME], default: #{DEFAULT_AI_AGENT}):"
  for n in AI_AGENTS
    marker = "  "
    if n == DEFAULT_AI_AGENT
      marker = color.green("* ")
    end
    puts "#{marker}#{n}"
  end
end

# ---------------- Yolofile (local provisioner) ----------------
# If a file named Yolofile exists in $PWD, yolo uses it as the provisioner
# instead of the embedded default. The marker key includes a sha256 of the
# bash body (excluding any leading front matter) so editing the script
# triggers a re-provision on the next attach. Editing only the front matter
# does NOT re-provision — see docs/05-yolofile.md for the full contract.
#
# Parsing + front matter validation live in yolofile.rugo; this file only
# orchestrates (where to read it, when to apply overrides, and how to feed
# the bash body to the backend). The yolofile module exposes:
#   - yolofile.path()           absolute path to ./Yolofile
#   - yolofile.exists()         bool
#   - yolofile.read_and_parse() {fm:, body:, err:}
#   - yolofile.parse_content(s) same shape, from a literal string
#   - yolofile.validate(fm, backends, ai_agents, default_ai_agent)
#                               typed overrides hash (image/cpus/mem_mb/...)

# Best-effort: pick a built-in provisioner based on files in $PWD.
# Returns the provisioner name (key into PROVISIONERS) or "" if no signal.
def detect_provisioner
  cwd = os.cwd()
  # Go
  if os.file_exists(filepath.join(cwd, "go.mod")) || os.file_exists(filepath.join(cwd, "go.sum"))
    return "fedora-go"
  end
  go_files = try filepath.glob(filepath.join(cwd, "*.go")) or []
  if len(go_files) > 0
    return "fedora-go"
  end
  # Rust
  if os.file_exists(filepath.join(cwd, "Cargo.toml")) || os.file_exists(filepath.join(cwd, "rust-toolchain.toml")) || os.file_exists(filepath.join(cwd, "rust-toolchain"))
    return "fedora-rust"
  end
  # Ruby
  if os.file_exists(filepath.join(cwd, "Gemfile")) || os.file_exists(filepath.join(cwd, ".ruby-version"))
    return "fedora-ruby"
  end
  gemspecs = try filepath.glob(filepath.join(cwd, "*.gemspec")) or []
  if len(gemspecs) > 0
    return "fedora-ruby"
  end
  # Android / Kotlin
  for f in ["build.gradle.kts", "settings.gradle.kts", "build.gradle", "settings.gradle"]
    if os.file_exists(filepath.join(cwd, f))
      return "fedora-android"
    end
  end
  for sub in ["app/build.gradle.kts", "app/build.gradle"]
    if os.file_exists(filepath.join(cwd, sub))
      return "fedora-android"
    end
  end
  return ""
end

# Resolve a provisioner name to its bash source. Returns "" if none should run.
#   - explicit name   → look it up in PROVISIONERS (error if unknown)
#   - "" (default)    → Yolofile if present
#                     → else auto-detect from $PWD
#                     → else "" (skip provisioning)
#
# The returned `marker` is what we store in .applied and check against. It
# includes a short content hash so edits to the source (Yolofile or rebuilt
# embedded provisioner) invalidate the marker and trigger re-provisioning.
def resolve_provisioner(prov_name)
  pname = prov_name
  if pname == ""
    if active_yolofile_exists()
      pname = "__yolofile__"
    elsif ephemeral_mode == true
      pname = ""
    else
      pname = detect_provisioner()
    end
  end
  if pname == ""
    return {name: "", display: "", marker: "", src: ""}
  end

  src = ""
  display = pname
  if pname == "__yolofile__"
    parsed = parse_active_yolofile()
    if parsed.err != ""
      err_("Yolofile: #{parsed.err}")
      os.exit(2)
    end
    src = parsed.body
    display = "Yolofile"
    if yolofile_override != ""
      display = "Yolofile (#{yolofile_override_display})"
    end
  else
    src = PROVISIONERS[pname]
    if src == nil
      src = ""
    end
  end

  if src == ""
    return {name: pname, display: display, marker: "", src: ""}
  end

  # Content-hashed marker so edits trigger a re-run.
  short = str.slice(crypto.sha256(src), 0, 12)
  marker = ""
  if pname == "__yolofile__"
    marker = "yolofile:#{short}"
  else
    marker = "#{pname}:#{short}"
  end
  return {name: pname, display: display, marker: marker, src: src}
end

# Internal: apply the given provisioner. The provisioner is plain bash that
# runs as root inside the VM via `matchlock exec -i -- bash`. yolo's job
# here is just to pick the right source, stream it in, and log status.
# Returns the marker string (so the caller can persist it).
def apply_provisioner(name, vm_id, prov_name)
  resolved = resolve_provisioner(prov_name)
  src     = resolved.src
  display = resolved.display
  marker  = resolved.marker
  if src == ""
    err_("unknown provisioner '#{prov_name}'")
    puts "available:"
    for n in PROVISIONERS
      puts "  #{n}"
    end
    if active_yolofile_exists()
      puts "  yolofile (#{active_yolofile_display()})"
    end
    os.exit(1)
  end

  be = backend_for(name)
  log("applying #{color.bold(display)} to #{color.bold(vm_id)}")
  be.exec_provision(vm_id, src, WORKSPACE)
  return marker
end

# Install an AI agent inside the guest. Same shape as apply_provisioner but
# uses the AI_AGENTS registry. Returns the marker name ("ai-agent:NAME").
# `name` is the yolo binding (used to resolve the backend).
def apply_agent(vm_id, agent_name, name)
  src = AI_AGENTS[agent_name]
  if src == nil || src == ""
    err_("unknown ai-agent '#{agent_name}'")
    puts "available:"
    for n in AI_AGENTS
      puts "  #{n}"
    end
    os.exit(1)
  end
  be = backend_for(name)
  log("installing ai-agent #{color.bold(agent_name)} into #{color.bold(vm_id)}")
  be.exec_provision(vm_id, src, WORKSPACE)
  return "ai-agent:#{agent_name}"
end

# Explicit `yolo provision` — always re-runs.
def cmd_provision(name, prov_name)
  acquire_lock(name, "provision")
  id = ensure_vm(name)
  applied_marker = apply_provisioner(name, id, prov_name)
  mark_applied(name, id, applied_marker)
  release_lock(name)
  log("provisioner finished (marker: #{applied_marker})")
end

# ---------------- Export / Import ----------------
# Move a yolo VM between hosts in a single compressed file.
#
# Strategy: package the VM's merged rootfs as a custom OCI image (docker-save
# tarball, ingested by `matchlock image import`) plus yolo's per-name state
# (applied provisioner markers, cwd) plus metadata. The destination host
# re-registers the image and pins it for the target name; the next `yolo`
# creates a fresh VM from that image, preserving all in-guest changes
# (installed packages, files outside the mounted workspace, etc.).
#
# Limitations:
# - Live RAM/CPU state is not preserved (matchlock has no checkpoint/restore).
# - Files under the mounted workspace (/work) are host-side; not part of rootfs.
# - Pseudo filesystems (/proc, /sys, /dev, /run) and tmpfs are excluded.

EXPORT_SCHEMA_VERSION = 1
EXPORT_PLACEHOLDER_TAG = "yolo-export:placeholder"

def valid_name(s)
  if s == "" || len(s) > 128
    return false
  end
  i = 0
  while i < len(s)
    c = str.slice(s, i, i + 1)
    ok = false
    # [A-Za-z0-9._:-]
    if c >= "A" && c <= "Z"
      ok = true
    elsif c >= "a" && c <= "z"
      ok = true
    elsif c >= "0" && c <= "9"
      ok = true
    elsif c == "." || c == "_" || c == "-" || c == ":"
      ok = true
    end
    if !ok
      return false
    end
    i = i + 1
  end
  return true
end

def json_escape(s)
  out = ""
  i = 0
  while i < len(s)
    c = str.slice(s, i, i + 1)
    if c == "\\"
      out = out + "\\\\"
    elsif c == "\""
      out = out + "\\\""
    elsif c == "\n"
      out = out + "\\n"
    elsif c == "\r"
      out = out + "\\r"
    elsif c == "\t"
      out = out + "\\t"
    else
      out = out + c
    end
    i = i + 1
  end
  return out
end

def cmd_export(name, out_path)
  acquire_lock(name, "export")
  id = read_state(name)
  if id == ""
    err_("no VM tracked for '#{name}' — start it first with `yolo -n #{name}`")
    release_lock(name)
    os.exit(1)
  end

  be = backend_for(name)
  if !be.SUPPORTS_EXPORT
    err_("backend '#{be.NAME}' does not support export/import")
    release_lock(name)
    os.exit(2)
  end

  # We need the VM running for the in-guest tar streaming. Auto-heal if
  # needed: this may recreate the VM from its (pinned) image, which is the
  # right thing — an export of a stopped/missing VM would otherwise have
  # nothing to capture.
  table = be.list_table()
  st = vm_status(id, table)
  if st != "running"
    warn("VM '#{name}' (#{id}) is '#{st}'; recreating to export")
    id = ensure_vm(name)
  end

  # Resolve output path.
  out = out_path
  if out == ""
    raw = try `bash -c "date -u +%Y%m%d-%H%M%S"` or ""
    ts = str.trim(raw)
    out = filepath.join(os.cwd(), "yolo-export-#{name}-#{ts}.tar.gz")
  end

  # Source image (per-name pin or env default) — recorded in metadata only.
  src_image = read_image(name)
  if src_image == ""
    src_image = IMAGE
  end

  applied = applied_list(name, id)
  cwd_disp = read_cwd(name)
  hostname_raw = try `bash -c "hostname 2>/dev/null || echo unknown"` or "unknown"
  hostname = str.trim(hostname_raw)
  ts_raw = try `bash -c "date -u +%Y-%m-%dT%H:%M:%SZ"` or ""
  ts_iso = str.trim(ts_raw)

  # Yolofile from the recorded cwd (if it still exists and is readable).
  yolofile_src = ""
  if cwd_disp != ""
    cand = filepath.join(cwd_disp, "Yolofile")
    if os.file_exists(cand)
      yolofile_src = cand
    end
  end

  # Build metadata.json
  applied_json = "[]"
  if len(applied) > 0
    parts = []
    for p in applied
      parts = append(parts, "\"" + json_escape(p) + "\"")
    end
    applied_json = "[" + str.join(parts, ",") + "]"
  end

  yolofile_flag = "false"
  if yolofile_src != ""
    yolofile_flag = "true"
  end

  meta = "{\n" +
    "  \"schema_version\": \"#{EXPORT_SCHEMA_VERSION}\",\n" +
    "  \"yolo_export\": true,\n" +
    "  \"exported_at\": \"#{json_escape(ts_iso)}\",\n" +
    "  \"source_host\": \"#{json_escape(hostname)}\",\n" +
    "  \"name\": \"#{json_escape(name)}\",\n" +
    "  \"backend\": \"#{json_escape(be.NAME)}\",\n" +
    "  \"src_vm_id\": \"#{json_escape(id)}\",\n" +
    "  \"src_image\": \"#{json_escape(src_image)}\",\n" +
    "  \"cwd\": \"#{json_escape(cwd_disp)}\",\n" +
    "  \"workspace\": \"#{json_escape(WORKSPACE)}\",\n" +
    "  \"cpus\": \"#{json_escape(cpus)}\",\n" +
    "  \"mem_mb\": \"#{json_escape(mem_mb)}\",\n" +
    "  \"disk_mb\": \"#{json_escape(disk_mb)}\",\n" +
    "  \"has_yolofile\": #{yolofile_flag},\n" +
    "  \"applied\": #{applied_json}\n" +
    "}\n"

  meta_tmp = "/tmp/yolo-export-meta-#{os.pid()}.json"
  os.write_file(meta_tmp, meta)

  ap_path = applied_file(name)
  cwd_path = cwd_file(name)
  log("exporting #{color.bold(name)} (#{id}) → #{color.bold(out)}")
  rc = be.export_archive({
    "vm_id"        => id,
    "name"         => name,
    "out"          => out,
    "meta_tmp"     => meta_tmp,
    "ap_path"      => ap_path,
    "cwd_path"     => cwd_path,
    "yolofile_src" => yolofile_src,
    "placeholder"  => EXPORT_PLACEHOLDER_TAG
  })
  if rc == ""
    try os.remove(meta_tmp) or nil
    release_lock(name)
    os.exit(1)
  end
  puts rc
  try os.remove(meta_tmp) or nil
  release_lock(name)
end

def cmd_import(in_path, name_override, force)
  if in_path == ""
    err_("usage: yolo import FILE [-n NAME] [--force]")
    os.exit(1)
  end
  if !os.file_exists(in_path)
    err_("archive not found: #{in_path}")
    os.exit(1)
  end

  # Resolve archive to an absolute path so the bash script's `cd` doesn't
  # break a relative reference.
  abs_raw = try `bash -c "readlink -f #{in_path}"` or ""
  abs = str.trim(abs_raw)
  if abs == ""
    abs = in_path
  end

  # Extract to a fresh tempdir, hardened against path traversal. We use the
  # matchlock backend's helper for now — the archive format is matchlock's
  # (docker-save tarball), so this is correct. A future podman backend
  # would either reuse the same on-disk format or add format detection.
  work_raw = try `bash -c "mktemp -d -t yolo-import-XXXXXX"` or ""
  work = str.trim(work_raw)
  if work == ""
    err_("could not create tempdir for import")
    os.exit(1)
  end

  be = BACKENDS["matchlock"]
  if be == nil
    err_("matchlock backend not registered — cannot import")
    os.exit(1)
  end

  rc = be.import_unpack({
    "work" => work,
    "abs"  => abs
  })
  if rc == ""
    try `bash -c "rm -rf #{work}"` or nil
    os.exit(1)
  end

  # Parse metadata (cheap line-based extraction — we only need a few fields,
  # and we don't trust the values for anything except display + name default).
  meta_path = filepath.join(work, "metadata.json")
  meta_raw  = os.read_file(meta_path)
  meta_name = json_string_field(meta_raw, "name")
  meta_cwd  = json_string_field(meta_raw, "cwd")
  meta_src  = json_string_field(meta_raw, "src_image")
  meta_host = json_string_field(meta_raw, "source_host")
  meta_ts   = json_string_field(meta_raw, "exported_at")
  meta_schema = json_string_field(meta_raw, "schema_version")
  meta_backend = json_string_field(meta_raw, "backend")
  if meta_schema != "1"
    err_("unsupported export schema_version '#{meta_schema}' (expected 1)")
    try `bash -c "rm -rf #{work}"` or nil
    os.exit(1)
  end
  # Backend field was added later; missing means matchlock. Reject archives
  # that originated on a different backend than what's available locally.
  if meta_backend != "" && meta_backend != "matchlock"
    err_("archive was exported from backend '#{meta_backend}' — import is matchlock-only")
    try `bash -c "rm -rf #{work}"` or nil
    os.exit(1)
  end

  target = name_override
  if target == ""
    target = meta_name
  end
  if !valid_name(target)
    err_("invalid target name '#{target}' (allowed: [A-Za-z0-9._:-]+, max 128 chars)")
    try `bash -c "rm -rf #{work}"` or nil
    os.exit(1)
  end

  # Refuse to clobber an existing binding unless --force.
  existing_vmid = read_state(target)
  existing_img  = read_image(target)
  if existing_vmid != "" || existing_img != ""
    if !force
      err_("name '#{target}' already bound (vm=#{existing_vmid}, image=#{existing_img}). Use --force to replace, or pass -n to choose a different name.")
      try `bash -c "rm -rf #{work}"` or nil
      os.exit(1)
    end
    log("--force: removing existing binding for '#{target}'")
    cmd_rm(target)
  end

  # Destination-local unique tag derived from archive content. Using a content
  # hash means re-importing the same file is idempotent; importing different
  # archives under the same name still produces distinct tags.
  hash_raw = try `bash -c "sha256sum #{abs} | awk '{print $1}' | cut -c1-12"` or ""
  short = str.trim(hash_raw)
  if short == ""
    short = "unknown"
  end
  tag = "yolo-import/#{target}:#{short}"

  acquire_lock(target, "import")

  # Re-tag image.tar's manifest + repositories to the destination tag, then
  # hand it to the matchlock image store.
  rc = be.import_retag({
    "work"        => work,
    "placeholder" => EXPORT_PLACEHOLDER_TAG,
    "tag"         => tag
  })
  if rc == ""
    try `bash -c "rm -rf #{work}"` or nil
    release_lock(target)
    os.exit(1)
  end
  puts rc

  # Pin the image for this name and stash the cwd + backend for display.
  write_image(target, tag)
  write_backend(target, "matchlock")
  if meta_cwd != ""
    os.write_file(cwd_file(target), meta_cwd)
  end

  # Carry over applied provisioner markers under the IMPORTED_SENTINEL.
  # start_vm() rewrites line 1 to the real vm-id on first attach (see
  # rebind_imported_applied), so provisioners skip re-running on import.
  state_dir = filepath.join(work, "state")
  src_applied = filepath.join(state_dir, "#{meta_name}.applied")
  if meta_name != "" && os.file_exists(src_applied)
    raw = os.read_file(src_applied)
    markers = []
    line_idx = 0
    for line in str.each_line(raw)
      t = str.trim(line)
      # line 0 was the original vm-id; skip it. Keep all subsequent markers.
      if line_idx > 0 && t != ""
        markers = append(markers, t)
      end
      line_idx = line_idx + 1
    end
    body = IMPORTED_SENTINEL
    for m in markers
      body = body + "\n" + m
    end
    os.write_file(applied_file(target), body + "\n")
  end

  try `bash -c "rm -rf #{work}"` or nil
  release_lock(target)

  src_info = ""
  if meta_host != "" && meta_ts != ""
    src_info = " (from #{meta_host} at #{meta_ts})"
  end
  log("imported '#{target}'#{src_info}")
  log("  base image:   #{tag}")
  if meta_src != ""
    log("  src image:    #{meta_src}")
  end
  if meta_cwd != ""
    log("  src cwd:      #{meta_cwd}")
  end
  puts ""
  puts "Run `yolo -n #{target}` from your project directory to boot a VM from this image."
end

# Tiny JSON string-field extractor. We're parsing trusted-shape metadata that
# we wrote ourselves with json_escape(), so this is good enough — we don't
# want to take a JSON parser dep for one file.
def json_string_field(src, key)
  needle = "\"" + key + "\""
  idx = str.index(src, needle)
  if idx < 0
    return ""
  end
  rest = str.slice(src, idx + len(needle), len(src))
  # Find the colon, then the opening quote.
  colon = str.index(rest, ":")
  if colon < 0
    return ""
  end
  after = str.slice(rest, colon + 1, len(rest))
  q = str.index(after, "\"")
  if q < 0
    return ""
  end
  body = str.slice(after, q + 1, len(after))
  # Find the closing quote, honouring \" escapes.
  out = ""
  i = 0
  while i < len(body)
    c = str.slice(body, i, i + 1)
    if c == "\\" && i + 1 < len(body)
      n = str.slice(body, i + 1, i + 2)
      if n == "\""
        out = out + "\""
      elsif n == "\\"
        out = out + "\\"
      elsif n == "n"
        out = out + "\n"
      elsif n == "r"
        out = out + "\r"
      elsif n == "t"
        out = out + "\t"
      else
        out = out + n
      end
      i = i + 2
    elsif c == "\""
      return out
    else
      out = out + c
      i = i + 1
    end
  end
  return out
end

# ---------------- Main ----------------
parsed = cli.parse_args(os.args(), AI_AGENTS, DEFAULT_AI_AGENT, VERSION)
sub = parsed.sub

# `install-skills` is a pure local operation (writes embedded SKILL.md files
# to ~/.agents/skills). Handle it before any VM/state/Yolofile machinery so a
# broken Yolofile or missing backend can never block it.
if sub == "install-skills"
  cmd_install_skills()
  os.exit(0)
end

if parsed.ephemeral && sub != ""
  err_("--ephemeral only works with attach/run mode, not subcommand '#{sub}'")
  os.exit(2)
end
if parsed.yolofile_path != ""
  ysrc = read_yolofile_source(parsed.yolofile_path)
  if ysrc.err != ""
    err_(ysrc.err)
    os.exit(2)
  end
  yolofile_override = parsed.yolofile_path
  yolofile_override_display = ysrc.display
  yolofile_override_content = ysrc.content
end
if parsed.ephemeral
  ephemeral_mode = true
end

# Yolofile front matter: applied only for subcommands that may create or
# recreate a VM. This is deliberate — a malformed Yolofile must not block
# `yolo rm`, `yolo stop`, `yolo logs`, etc., which need to operate on
# already-existing VM state regardless of the (possibly broken) file.
applies_resources = (sub == "" || sub == "provision" || sub == "export")
if applies_resources && active_yolofile_exists()
  yf_parsed = parse_active_yolofile()
  if yf_parsed.err != ""
    err_("Yolofile: #{yf_parsed.err}")
    os.exit(2)
  end
  fm_resolved = yolofile.validate(yf_parsed.fm, BACKENDS, AI_AGENTS, DEFAULT_AI_AGENT)
  if fm_resolved.image != ""
    image = fm_resolved.image
  end
  if fm_resolved.cpus != ""
    cpus = fm_resolved.cpus
  end
  if fm_resolved.mem_mb != ""
    mem_mb = fm_resolved.mem_mb
  end
  if fm_resolved.disk_mb != ""
    disk_mb = fm_resolved.disk_mb
  end
  if fm_resolved.backend != ""
    backend_sel = fm_resolved.backend
  end
  if fm_resolved.gui_set
    gui_enabled = fm_resolved.gui
  end
  if fm_resolved.audio_set
    audio_enabled = fm_resolved.audio
  end
  # CLI --ai-agent / --no-ai-agent wins; otherwise honour Yolofile front matter.
  if !parsed.agent_set && fm_resolved.agent_set
    parsed.agent = fm_resolved.agent
  end
end

# CLI flag overrides run last so they win over both env vars and Yolofile.
if parsed.disk_mb != ""
  disk_mb = parsed.disk_mb
end
if parsed.backend != ""
  backend_sel = parsed.backend
end
if parsed.gui_set
  gui_enabled = parsed.gui
end
if parsed.audio_set
  audio_enabled = parsed.audio
end

# Validate backend_sel early (only for vm-creating subcommands) so an unknown
# name fails fast with a friendly message instead of erroring deep inside
# resolve_backend_name().
if backend_sel != "" && BACKENDS[backend_sel] == nil
  err_("unknown backend '#{backend_sel}' (known: #{known_backends()})")
  os.exit(2)
end

name = parsed.name
if parsed.ephemeral
  if name != ""
    err_("--ephemeral uses an auto-generated throwaway name; do not combine it with -n/--name")
    os.exit(2)
  end
  name = safe_ephemeral_name()
  ephemeral_workspace = make_temp_workspace()
  host_workspace = ephemeral_workspace
elsif name == ""
  name = default_name()
end
if sub == "ls"
  cmd_ls()
elsif sub == "du"
  cmd_du()
elsif sub == "stop"
  cmd_stop(name)
elsif sub == "rm"
  cmd_rm(name)
elsif sub == "logs"
  cmd_logs(name, parsed.rest)
elsif sub == "id"
  cmd_id(name)
elsif sub == "status"
  cmd_status(name)
elsif sub == "provision"
  cmd_provision(name, parsed.prov)
elsif sub == "provisioners"
  cmd_provisioners()
elsif sub == "prune"
  cmd_prune()
elsif sub == "export"
  cmd_export(name, parsed.out_path)
elsif sub == "import"
  # First positional arg after `import` is the archive path.
  in_path = ""
  if len(parsed.rest) > 0
    in_path = parsed.rest[0]
  end
  cmd_import(in_path, parsed.name, parsed.force)
else
  cmd_attach(name, parsed.passthrough, parsed.prov, parsed.no_prov, parsed.agent)
end