opencode-llmstack 0.6.0__py3-none-any.whl

llmstack/commands/install.py

@@ -0,0 +1,365 @@
+"""``llmstack install`` -- regenerate ``opencode.json`` (and AGENTS.md copy).
+
+Renders the opencode config atomically (tmp file in target dir, validate,
+``mv``), copies AGENTS.md alongside it, and pins the default channel for
+``start`` to pick up. ``llama-swap.yaml`` is *not* generated here -- it's
+a runtime-only artifact owned by ``llmstack start`` (which knows the
+chosen channel and regenerates the yaml on each launch).
+
+This is also where the **channel** is decided -- everything downstream
+(``start``, ``status``, the activate hook) reads the persisted choice
+from ``.llmstack/default-channel`` and never re-derives it. Three
+channels exist:
+
+  * ``current``   -- local stack, canonical channel (default)
+  * ``next``      -- local stack, queued-upgrade channel
+  * ``external``  -- thin client; no daemons launched. Opt in via
+                    ``--external [URL]`` (URL defaults to the local
+                    router, ``http://127.0.0.1:10101``, so two
+                    projects on one host can share daemons without
+                    fighting for ports). ``LLMSTACK_REMOTE_URL`` in the
+                    environment is honoured as an alternative way in.
+
+``--print`` writes the opencode config to stdout instead of files.
+
+When this command seeds a fresh ``models.ini`` from the bundled template
+and the ``bedrock`` extra is installed (i.e. ``import boto3`` succeeds),
+any block fenced with ``; >>> AUTO-ENABLE-WHEN-BEDROCK-AVAILABLE >>>``
+markers in the seeded file is uncommented in place. The auto-enable
+runs only on the *initial* seed; subsequent ``install`` runs never
+mutate the user's models.ini.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from llmstack.generators import render_to
+from llmstack.generators.opencode import render as render_opencode
+from llmstack.generators.opencode import validate as validate_opencode
+from llmstack.paths import (
+    AGENTS_TEMPLATE,
+    DEFAULT_REMOTE_URL,
+    ChannelMark,
+    ensure_models_ini,
+    ensure_state_dirs,
+    env_remote_url,
+    write_marker,
+)
+
+_BEDROCK_BEGIN = "; >>> AUTO-ENABLE-WHEN-BEDROCK-AVAILABLE >>>"
+_BEDROCK_END   = "; <<< AUTO-ENABLE-WHEN-BEDROCK-AVAILABLE <<<"
+
+
+def _try_enable_bedrock_blocks(ini_path: Path) -> int:
+    """Activate any ``AUTO-ENABLE-WHEN-BEDROCK-AVAILABLE`` block in
+    ``ini_path`` when ``boto3`` is importable.
+
+    For each fenced block we drop the BEGIN / END marker lines and
+    strip a single leading ``"; "`` (or ``";\\t"``) from every line in
+    between -- so a doubly-commented line like ``; ; aws_profile = ...``
+    becomes a still-commented ``; aws_profile = ...`` in the active
+    config (preserving the "uncomment to use" semantics of literal
+    in-file comments). Returns the number of blocks rewritten; ``0``
+    when boto3 is missing, no markers exist, or every block is already
+    expanded.
+    """
+    try:
+        import boto3  # noqa: F401  -- presence check only
+    except ImportError:
+        return 0
+
+    text = ini_path.read_text()
+    if _BEDROCK_BEGIN not in text or _BEDROCK_END not in text:
+        return 0
+
+    out: list[str] = []
+    inside = False
+    blocks = 0
+    for line in text.splitlines(keepends=True):
+        bare = line.rstrip("\r\n").rstrip()
+        if bare == _BEDROCK_BEGIN:
+            inside = True
+            blocks += 1
+            continue
+        if bare == _BEDROCK_END:
+            inside = False
+            continue
+        if inside:
+            if line.startswith("; ") or line.startswith(";\t"):
+                out.append(line[2:])
+            elif bare == ";":
+                out.append(line[1:])
+            else:
+                out.append(line)
+        else:
+            out.append(line)
+
+    if blocks == 0:
+        return 0
+    ini_path.write_text("".join(out))
+    return blocks
+
+
+def _print_help() -> None:
+    print(
+        "usage: llmstack install [--print] [--current | --next] "
+        "[--external [URL]]"
+    )
+
+
+def _parse_args(args: list[str]) -> tuple[bool, str, str | None, bool]:
+    """Parse ``install``'s flags.
+
+    Returns ``(print_only, local_channel, external_url, want_external)``:
+
+      * ``local_channel`` is ``current`` or ``next`` -- ignored when
+        ``want_external`` is ``True``.
+      * ``external_url`` is the explicit URL given to ``--external <url>``,
+        if any. ``None`` when the flag was bare or absent.
+      * ``want_external`` is ``True`` iff the user passed ``--external``
+        (with or without a URL). The env-var fallback is layered in by
+        the caller, not here, so this stays a pure CLI parse.
+
+    ``--external`` accepts either ``--external <url>`` (separate arg) or
+    ``--external=<url>``. Mutually exclusive with ``--current`` /
+    ``--next`` -- mixing them raises ``SystemExit``.
+    """
+    print_only = False
+    local_channel = "current"
+    local_explicit = False
+    external_url: str | None = None
+    want_external = False
+
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg in ("--print", "-n"):
+            print_only = True
+        elif arg == "--next":
+            local_channel = "next"
+            local_explicit = True
+        elif arg == "--current":
+            local_channel = "current"
+            local_explicit = True
+        elif arg == "--external":
+            want_external = True
+            # Optional URL as next positional, but only if it looks like
+            # a URL (not the next flag).
+            if i + 1 < len(args) and not args[i + 1].startswith("-"):
+                external_url = args[i + 1]
+                i += 1
+        elif arg.startswith("--external="):
+            want_external = True
+            external_url = arg[len("--external="):]
+        elif arg in ("-h", "--help"):
+            _print_help()
+            raise SystemExit(0)
+        else:
+            print(
+                f"[!] unknown arg to install: {arg} "
+                "(try --print, --current, --next, --external, -h)"
+            )
+            raise SystemExit(2)
+        i += 1
+
+    if want_external and local_explicit:
+        print(
+            "[!] --external is mutually exclusive with --current / --next "
+            "(external installs don't run local daemons).",
+        )
+        raise SystemExit(2)
+
+    return print_only, local_channel, external_url, want_external
+
+
+def _resolve_external_url(flag_url: str | None) -> str:
+    """Pick the URL to bake into opencode.json + the channel marker.
+
+    Precedence: explicit ``--external <url>`` arg > ``$LLMSTACK_REMOTE_URL``
+    env var > :data:`DEFAULT_REMOTE_URL` (the local router). The default
+    is what makes the "two projects on one host" workflow zero-config:
+    ``llmstack install --external`` with nothing else set wires this
+    project as a thin client of localhost so it can ride alongside
+    whichever project actually owns the daemons.
+
+    The ``$LLMSTACK_REMOTE_URL`` rung is what the activate hook
+    populates when the user ``cd``-s into a project pinned to
+    ``external`` -- so re-running ``llmstack install`` from an active
+    shell inside an external project doesn't require the URL again.
+    """
+    if flag_url:
+        return flag_url.rstrip("/")
+    env = env_remote_url()
+    if env:
+        return env
+    return DEFAULT_REMOTE_URL
+
+
+def _fetch_remote_models_ini(url: str) -> str:
+    """Pull the live ``models.ini`` from a remote llmstack router.
+
+    External installs use the router as the source of truth for tier
+    inventory: the same file the router parsed at startup is what the
+    thin client renders ``opencode.json`` against, so tier names +
+    descriptions agree with what the router actually serves. The fetch
+    is also the canonical health check -- a 200 with parseable INI
+    content proves both that the router is reachable and that the
+    operator on the remote side has wired their config.
+
+    Raises ``SystemExit`` (with a user-facing message) on any failure
+    -- DNS, connection refused, non-2xx, empty body. The thin-client
+    install is meaningless without the file, so we refuse to write a
+    stale opencode.json from cached state. There is no client-side
+    cache: every ``install`` re-fetches.
+    """
+    fetch_url = f"{url.rstrip('/')}/models.ini"
+    req = urllib.request.Request(fetch_url, headers={"Accept": "text/plain"})
+    try:
+        with urllib.request.urlopen(req, timeout=15.0) as resp:
+            if resp.status != 200:
+                raise SystemExit(
+                    f"[!] {fetch_url} returned HTTP {resp.status} -- "
+                    "the remote router is up but doesn't have a "
+                    "models.ini. Run `llmstack install` on the router "
+                    "host to seed one, then retry here."
+                )
+            charset = resp.headers.get_content_charset() or "utf-8"
+            text = resp.read().decode(charset)
+    except urllib.error.HTTPError as e:
+        raise SystemExit(
+            f"[!] {fetch_url} returned HTTP {e.code} {e.reason}.\n"
+            "    is the remote running an llmstack version with "
+            "GET /models.ini? (added in v3.x)"
+        ) from e
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        raise SystemExit(
+            f"[!] failed to reach {fetch_url}: {e}\n"
+            "    check the URL, the network path, and that the remote "
+            "router is up."
+        ) from e
+
+    if not text.strip():
+        raise SystemExit(
+            f"[!] {fetch_url} returned an empty body -- nothing to "
+            "render opencode.json from."
+        )
+    return text
+
+
+def run(args: list[str]) -> int:
+    try:
+        print_only, local_channel, external_url_arg, want_external = _parse_args(args)
+    except SystemExit as e:
+        return int(e.code) if isinstance(e.code, int) else 0
+
+    # Env-var fallback: ``LLMSTACK_REMOTE_URL`` set without ``--external``
+    # still implies external mode. The activate hook re-exports this
+    # var from the channel marker when the user ``cd``-s into an
+    # external project, so re-running ``llmstack install`` from inside
+    # an active shell doesn't need the URL or the flag again.
+    if not want_external and env_remote_url() is not None:
+        want_external = True
+
+    if want_external:
+        remote = _resolve_external_url(external_url_arg)
+        channel: str = "external"
+    else:
+        remote = None
+        channel = local_channel
+
+    # Source of the INI is mode-dependent. Local mode reads (and
+    # seeds-if-missing) the per-project file. External mode pulls the
+    # router's live copy on every install -- the thin client never
+    # keeps a local models.ini, since that would just be a stale
+    # mirror of the router's truth.
+    ini_text: str | None = None
+    ini_source_label: str
+    if remote is not None:
+        # Flush so the "fetching" line lands before the network call;
+        # otherwise an error written to stderr from inside
+        # _fetch_remote_models_ini races ahead of buffered stdout and
+        # the user sees the failure message before the "what we're
+        # doing" message.
+        print(f"[*] fetching models.ini from {remote}/models.ini ...", flush=True)
+        ini_text = _fetch_remote_models_ini(remote)
+        print(f"[OK] {len(ini_text.splitlines())} lines from {remote}")
+        ini_source_label = f"{remote}/models.ini"
+    else:
+        ini_path, seeded = ensure_models_ini()
+        if seeded:
+            print(f"[*] no models.ini found -- seeded default at {ini_path}")
+            enabled = _try_enable_bedrock_blocks(ini_path)
+            if enabled:
+                print(
+                    f"[*] boto3 detected -- enabled {enabled} bedrock-backed "
+                    f"tier block(s) in {ini_path}"
+                )
+            print("    edit it to taste, then re-run `llmstack install`.")
+        ini_source_label = str(ini_path)
+
+    paths = ensure_state_dirs()
+
+    if print_only:
+        if remote is not None:
+            print(f"# external mode (channel: external, remote: {remote}); llama-swap.yaml not used.")
+            print()
+        print("----- opencode.json -----")
+        print(render_opencode(ini_text=ini_text, remote=remote))
+        return 0
+
+    print("[1/2] AGENTS.md")
+    if AGENTS_TEMPLATE.is_file():
+        shutil.copyfile(AGENTS_TEMPLATE, paths.agents_local)
+        os.chmod(paths.agents_local, 0o644)
+        print(f"[OK] copied AGENTS.md -> {paths.agents_local}")
+    else:
+        print(f"[!] AGENTS.md template not found at {AGENTS_TEMPLATE}; skipping copy")
+
+    print()
+    print("[2/2] opencode.json")
+    prev = os.environ.get("OPENCODE_INSTRUCTIONS")
+    os.environ["OPENCODE_INSTRUCTIONS"] = str(paths.agents_local)
+    try:
+        render_to(
+            paths.opencode_json,
+            render=lambda p: Path(p).write_text(
+                render_opencode(ini_text=ini_text, remote=remote)
+            ),
+            validate=validate_opencode,
+        )
+    finally:
+        if prev is None:
+            os.environ.pop("OPENCODE_INSTRUCTIONS", None)
+        else:
+            os.environ["OPENCODE_INSTRUCTIONS"] = prev
+    print(f"[OK] installed {paths.opencode_json}")
+
+    if remote is not None:
+        write_marker(paths.default_marker, ChannelMark("external", remote))
+        print(f"[OK] default channel: external (remote: {remote})")
+    else:
+        write_marker(paths.default_marker, ChannelMark(channel))
+        print(f"[OK] default channel: {channel}")
+
+    print()
+    print(f"[OK] opencode config generated from {ini_source_label}.")
+    print()
+    print(f"  config:       {paths.opencode_json}")
+    print(f"  instructions: {paths.agents_local}")
+    if remote is not None:
+        print(f"  remote:       {remote}")
+    else:
+        print(f"  channel:      {channel}")
+    print()
+    print("Next:")
+    if remote is not None:
+        print("  llmstack start     # re-fetch /models.ini + drop into the client subshell")
+    else:
+        print("  llmstack start     # generate llama-swap.yaml + bring up the stack")
+        print("  llmstack check     # snapshot configured GGUFs + drift check")
+    return 0

llmstack/commands/install_llama_swap.py

@@ -0,0 +1,36 @@
+"""``llmstack install-llama-swap`` -- (re-)download the llama-swap binary only.
+
+Exposes the previously-internal ``_install_llama_swap`` helper as a
+first-class subcommand. Useful for ``--force`` upgrades without touching
+the generated configs.
+"""
+
+from __future__ import annotations
+
+from llmstack.download.binary import install_llama_swap
+from llmstack.paths import is_remote, remote_url
+
+
+def _print_help() -> None:
+    print("usage: llmstack install-llama-swap [--force]")
+
+
+def run(args: list[str]) -> int:
+    force = False
+    for arg in args:
+        if arg in ("-f", "--force"):
+            force = True
+        elif arg in ("-h", "--help"):
+            _print_help()
+            return 0
+        else:
+            print(f"[!] unknown arg to install-llama-swap: {arg}")
+            return 2
+
+    if is_remote():
+        print(f"[!] this project is wired as a thin client of {remote_url()} (channel: external);")
+        print("    the binary lives on the remote. `llmstack install-llama-swap` is a local-only command.")
+        return 1
+
+    install_llama_swap(force=force)
+    return 0

llmstack/commands/reload.py

@@ -0,0 +1,59 @@
+"""``llmstack reload`` -- refresh env + prompt of the current shell.
+
+The activate hook normally re-evaluates env and ``PROMPT`` / ``PS1`` on
+every chpwd, so cd-ing into a project (or switching between projects)
+keeps things current. But mid-session events -- ``llmstack start --next``
+inside an already-active shell, the channel marker getting rewritten by
+another process, etc. -- don't trigger a chpwd, so the prompt would stay
+stale until the next directory change.
+
+Pipe this command's output through your shell's eval to apply the
+current channel's env + prompt in-place::
+
+    # zsh / bash
+    eval "$(llmstack reload)"
+
+    # powershell
+    Invoke-Expression (& llmstack reload | Out-String)
+
+We resolve the channel from ``.llmstack/active-channel`` (live, written
+by ``start``), falling back to ``.llmstack/default-channel`` (intent,
+written by ``install``), and finally to ``current``. All informational
+output goes to stderr so stdout stays eval-safe.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from llmstack.paths import read_marker, resolve
+from llmstack.shell_env import emit_shell_refresh
+
+
+def _print_help() -> None:
+    print('usage: eval "$(llmstack reload)"', file=sys.stderr)
+
+
+def run(args: list[str]) -> int:
+    for a in args:
+        if a in ("-h", "--help"):
+            _print_help()
+            return 0
+        print(f"[!] unknown arg to reload: {a}", file=sys.stderr)
+        return 2
+
+    paths = resolve()
+    if not paths.opencode_json.is_file():
+        # No project -- emit nothing on stdout (eval no-op) and a hint
+        # on stderr. We don't fail-hard because users may have their
+        # rc wired to call reload defensively.
+        print(
+            f"[!] no .llmstack/opencode.json under {paths.work_dir} -- nothing to reload.",
+            file=sys.stderr,
+        )
+        return 0
+
+    mark = read_marker(paths.active_marker) or read_marker(paths.default_marker)
+    channel = mark.channel if mark else "current"
+    emit_shell_refresh(channel)
+    return 0

llmstack/commands/restart.py

@@ -0,0 +1,12 @@
+"""``llmstack restart`` -- ``stop`` followed by ``start`` (passes flags through)."""
+
+from __future__ import annotations
+
+from llmstack.commands import start, stop
+
+
+def run(args: list[str]) -> int:
+    rc = stop.run([])
+    if rc not in (0, None):
+        return rc
+    return start.run(args)

llmstack/commands/setup.py

@@ -0,0 +1,146 @@
+"""``llmstack setup`` -- first-time walkthrough.
+
+Mirrors the shell ``cmd_setup``:
+
+  1. Kick off GGUF downloads in the background (skip with ``--skip-download``).
+  2. Wait for them to finish (skip with ``--skip-wait``).
+  3. Install the ``llama-swap`` binary.
+  4. Print the shell activation hook eval line + the auto-detected hook.
+  5. Verify ``opencode`` is on PATH.
+
+Does NOT run ``install`` or ``start`` -- those are separate steps once
+downloads finish.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+from llmstack._platform import IS_WINDOWS, shell_family
+from llmstack.commands.activate import write_hook
+from llmstack.download.binary import install_llama_swap
+from llmstack.download.ggufs import download_all, wait_for_downloads
+from llmstack.paths import is_remote, remote_url
+from llmstack.shell_env import _user_shell
+
+
+def _print_help() -> None:
+    print("usage: llmstack setup [--skip-download] [--skip-wait]")
+
+
+def run(args: list[str]) -> int:
+    skip_download = False
+    skip_wait = False
+    for arg in args:
+        if arg == "--skip-download":
+            skip_download = True
+        elif arg == "--skip-wait":
+            skip_wait = True
+        elif arg in ("-h", "--help"):
+            _print_help()
+            return 0
+        else:
+            print(f"[!] unknown arg to setup: {arg} (try --skip-download, --skip-wait, -h)")
+            return 2
+
+    if is_remote():
+        print(f"[!] external mode is in effect ({remote_url()}); setup is local-only.")
+        print("    in client mode you only need:")
+        print("      llmstack install --external      # generate .llmstack/opencode.json (points at remote)")
+        print("      llmstack start                   # verify remote + enter the client subshell")
+        return 1
+
+    if not skip_download:
+        print("[1/3] downloading required GGUFs...")
+        download_all()
+        print()
+    else:
+        print("[1/3] (skipped) downloads")
+        print()
+
+    if not skip_download and not skip_wait:
+        print("[2/3] waiting for downloads to finish...")
+        wait_for_downloads()
+        print()
+    else:
+        print("[2/3] (skipped) wait")
+        print()
+
+    _, shell_name = _user_shell()
+    family = shell_family(shell_name)
+
+    print("[3/3] installing llama-swap binary...")
+    install_llama_swap()
+    print()
+
+    print("[4/4] wiring shell activation hook...")
+    print()
+    if family in ("bash", "zsh"):
+        rc_hint = f"~/.{shell_name}rc"
+        hook_arg = shell_name
+    elif family == "powershell":
+        rc_hint = "$PROFILE"
+        hook_arg = "powershell"
+    else:
+        rc_hint = "your shell rc file"
+        hook_arg = None
+
+    eval_line: str | None = None
+    if hook_arg is not None:
+        path, _src = write_hook(hook_arg)
+        eval_line = f'eval "$(llmstack activate {hook_arg})"'
+        print(f"[OK] hook installed: {path}")
+        print()
+        print("To turn it on in this shell now (and persist across new shells, paste")
+        print(f"the same line into {rc_hint}):")
+        print()
+        print(f"    {eval_line}")
+
+    print()
+    print("[5/5] checking opencode...")
+    if shutil.which("opencode"):
+        path = shutil.which("opencode") or "opencode"
+        print(f"[OK] opencode found: {path}")
+        try:
+            ver = subprocess.run(
+                ["opencode", "--version"],
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                timeout=5,
+            ).stdout.strip()
+        except (OSError, subprocess.SubprocessError):
+            ver = "(unknown)"
+        print(f"     version: {ver or '(unknown)'}")
+    else:
+        print("[!] opencode not found in PATH.")
+        print()
+        print("Install it with:")
+        if IS_WINDOWS:
+            print("  irm https://opencode.ai/install.ps1 | iex")
+        else:
+            print("  curl -fsSL https://opencode.ai/install | sh")
+        print("  # or via npm:")
+        print("  npm install -g opencode-ai")
+        print()
+        print("After installing, run:")
+        print("  llmstack install     # generate configs for this project")
+        print("  llmstack start       # bring up the stack")
+        return 0
+
+    print()
+    print("[OK] setup complete.")
+    print()
+    print("Next steps:")
+    if eval_line is not None:
+        print(f"  1. Run (and paste into {rc_hint} for persistence): {eval_line}")
+    else:
+        print("  1. Source the generated hook in your shell rc (see above)")
+    print("  2. llmstack install     # generate .llmstack/ configs for this project")
+    print("  3. llmstack start       # bring up the stack")
+    print()
+    print("To check configured GGUFs + drift vs models.ini:")
+    print("  llmstack check")
+    return 0