loki-mode 7.71.0 → 7.73.0

package/autonomy/loki

@@ -115,6 +115,16 @@ if [ -f "$_LOKI_SCRIPT_DIR/quickstart.sh" ]; then
     source "$_LOKI_SCRIPT_DIR/quickstart.sh"
 fi
 
+# Shared PRINT-ONLY pull-request advisory (provides print_pr_advice and its
+# origin/compare-URL helpers). Single source of truth sourced by BOTH this CLI
+# (cmd_deploy CI/CD path) and autonomy/run.sh (create_session_pr) so the two
+# surfaces print byte-identical, correct git push + PR commands and cannot drift.
+# Self-guarded against double-source. Existence-guarded matching the pattern above.
+if [ -f "$_LOKI_SCRIPT_DIR/lib/git-pr-advisory.sh" ]; then
+    # shellcheck source=autonomy/lib/git-pr-advisory.sh
+    source "$_LOKI_SCRIPT_DIR/lib/git-pr-advisory.sh"
+fi
+
 # Resolve the script's real path (handles symlinks)
 resolve_script_path() {
     local script="$1"
@@ -725,7 +735,7 @@ show_help() {
     echo "  version          Show version"
     echo "  help             Show this help ('loki help aliases' for old names)"
     echo ""
-    echo "More commands (grill, spec, cleanup, init, watch, demo, web, api,"
+    echo "More commands (grill, spec, deploy, cleanup, init, watch, demo, web, api,"
     echo "logs, github, import, council, proof, audit, compliance, agent, template,"
     echo "magic, docs, wiki, ci, test, bench, secrets, telemetry, crash, worktree,"
     echo "failover, monitor, remote, ...) are dispatchable and documented via"
@@ -5207,42 +5217,14 @@ cmd_web_status() {
     echo "Purple Lab is not running."
 }
 
-# Open the running app preview (the app Loki built and started locally).
-# Surfaces the existing app-runner state; does not start or change the app.
-cmd_preview() {
-    local open_browser=true
-    case "${1:-}" in
-        --help|-h|help)
-            echo -e "${BOLD}Loki Mode -- open the running app preview${NC}"
-            echo ""
-            echo "Usage: loki preview [--no-open]"
-            echo "       loki open      (alias)"
-            echo ""
-            echo "Prints the URL of the app Loki built and started locally, then"
-            echo "opens it in your browser. The app runner starts the app after the"
-            echo "first successful build iteration. This serves a real local build"
-            echo "from localhost on your machine; it is not hosted."
-            echo ""
-            echo "Options:"
-            echo "  --no-open    Print the URL and status only; do not open a browser"
-            echo "  --help, -h   Show this help and exit"
-            return 0
-            ;;
-        --no-open)
-            open_browser=false
-            ;;
-    esac
-
-    local state_file="${LOKI_DIR}/app-runner/state.json"
-    if [ ! -f "$state_file" ]; then
-        echo "No app running. The app runner starts after the first successful build iteration."
-        echo "Run 'loki status' to check the current run."
-        return 0
-    fi
-
-    # Parse url/status/port. Prefer python3 (used throughout); fall back to grep.
-    # Pass the path as argv (not inline interpolation) so a path with quotes
-    # cannot break the script, and parse all three fields in one invocation.
+# Read app-runner state.json and echo url, status, port (one per line, in that
+# order). Shared by the plain preview browser path and the --public tunnel path
+# so there is no parse drift between them. Path is passed as argv (not inline
+# interpolation) so a path with quotes cannot break the script. Always exits 0;
+# callers re-split with sed -n '1p/2p/3p'. Logic is byte-identical to the
+# original inline parse in cmd_preview (do not "clean up" -- behavior-neutral).
+_read_app_state() {
+    local state_file="$1"
     local url status port parsed
     if command -v python3 &> /dev/null; then
         parsed=$(python3 -c "import json,sys
@@ -5261,6 +5243,404 @@ except Exception:
         status=$(grep -oE '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$state_file" 2>/dev/null | head -1 | sed 's/.*"status"[[:space:]]*:[[:space:]]*"//;s/"$//')
         port=$(grep -oE '"port"[[:space:]]*:[[:space:]]*[0-9]+' "$state_file" 2>/dev/null | head -1 | grep -oE '[0-9]+$')
     fi
+    printf '%s\n%s\n%s\n' "$url" "$status" "$port"
+}
+
+# Pure extractor: pull the first cloudflared quick-tunnel URL out of a log file.
+# Reads a FILE (not a live process) so it is unit-testable. Echoes the URL or
+# nothing. Always returns 0 -- a no-match must not abort the caller under
+# `set -o pipefail` (grep exits 1 on no match, so the pipeline is `|| true`d).
+_extract_tunnel_url_cloudflared() {
+    local logfile="${1:-}"
+    [ -f "$logfile" ] || return 0
+    grep -oE 'https://[a-z0-9-]+\.trycloudflare\.com' "$logfile" 2>/dev/null | head -1 || true
+}
+
+# Pure extractor: pull the public_url out of an ngrok 4040 API JSON dump.
+# Reads a FILE so it is unit-testable. Prefers the https tunnel. Uses python3
+# json (path passed as argv -- no shell interpolation into the heredoc), with a
+# grep fallback if python3 is absent or the parse fails. Echoes URL or nothing;
+# always returns 0.
+_extract_tunnel_url_ngrok() {
+    local json_file="${1:-}"
+    [ -f "$json_file" ] || return 0
+    local out=""
+    if command -v python3 >/dev/null 2>&1; then
+        out=$(python3 - "$json_file" <<'PYEXTRACT' 2>/dev/null || true
+import json, sys
+try:
+    with open(sys.argv[1]) as fh:
+        data = json.load(fh)
+except Exception:
+    sys.exit(0)
+tunnels = data.get("tunnels", []) if isinstance(data, dict) else []
+urls = [t.get("public_url", "") for t in tunnels if isinstance(t, dict) and t.get("public_url")]
+https = [u for u in urls if u.startswith("https://")]
+chosen = https[0] if https else (urls[0] if urls else "")
+if chosen:
+    print(chosen)
+PYEXTRACT
+)
+    fi
+    if [ -z "$out" ]; then
+        # Grep fallback: take https public_url values first, else any public_url.
+        out=$(grep -oE '"public_url"[[:space:]]*:[[:space:]]*"https://[^"]*"' "$json_file" 2>/dev/null | head -1 | grep -oE 'https://[^"]*' || true)
+        if [ -z "$out" ]; then
+            out=$(grep -oE '"public_url"[[:space:]]*:[[:space:]]*"[^"]*"' "$json_file" 2>/dev/null | head -1 | sed 's/.*"public_url"[[:space:]]*:[[:space:]]*"//;s/"$//' || true)
+        fi
+    fi
+    printf '%s' "$out"
+}
+
+# Teardown for a launched tunnel: TERM, brief grace, then KILL, then remove the
+# log. All steps are `|| true` so the EXIT/INT/TERM trap is set -e safe and never
+# leaves an orphaned public tunnel. Args: tunnel_pid [logfile].
+_preview_public_teardown() {
+    local tunnel_pid="${1:-}"
+    local logfile="${2:-}"
+    if [ -n "$tunnel_pid" ]; then
+        kill -TERM "$tunnel_pid" 2>/dev/null || true
+        sleep 1
+        kill -KILL "$tunnel_pid" 2>/dev/null || true
+    fi
+    if [ -n "$logfile" ]; then
+        rm -f "$logfile" 2>/dev/null || true
+    fi
+}
+
+# Expose the already-running local app over a PUBLIC URL by wrapping the user's
+# OWN tunnel CLI (cloudflared or ngrok). Consent-gated, default-OFF. Loki never
+# proxies traffic and never bundles a binary. Args: provider yes no_host_rewrite.
+# Returns non-zero on any precondition failure or declined/refused consent
+# (except an interactive decline, which is a clean exit 0).
+_preview_public() {
+    local provider="${1:-}"
+    local assume_yes="${2:-false}"
+    local no_host_rewrite="${3:-false}"
+
+    local state_file="${LOKI_DIR}/app-runner/state.json"
+
+    # Precondition 1: state.json must exist.
+    if [ ! -f "$state_file" ]; then
+        echo "No app running. Nothing to expose." >&2
+        echo "Start a build (loki start) or check status (loki status) first." >&2
+        return 1
+    fi
+
+    # Read url/status/port via the shared helper (same parse as plain preview).
+    local _state url status port
+    _state=$(_read_app_state "$state_file")
+    url=$(printf '%s\n' "$_state" | sed -n '1p')
+    status=$(printf '%s\n' "$_state" | sed -n '2p')
+    port=$(printf '%s\n' "$_state" | sed -n '3p')
+
+    # Precondition 2: status must be running.
+    if [ "$status" != "running" ]; then
+        echo "App is not running (status: ${status:-unknown}). Refusing to expose." >&2
+        echo "The app runner starts the app after a successful build iteration." >&2
+        return 1
+    fi
+
+    # Precondition 3: resolve URL/port (fallback mirrors the plain path).
+    if [ -z "$url" ]; then
+        url="http://localhost:${port:-3000}"
+    fi
+    local probe_port="${port:-3000}"
+
+    # Precondition 4: PORT must actually be reachable. Never tunnel a dead port.
+    # Reuses the curl-readiness poll pattern (autonomy/loki:4979).
+    local retries=0
+    local port_ready=false
+    while [ $retries -lt 6 ]; do
+        if curl -s "http://localhost:${probe_port}" > /dev/null 2>&1; then
+            port_ready=true
+            break
+        fi
+        sleep 0.5
+        retries=$((retries + 1))
+    done
+    if [ "$port_ready" != true ]; then
+        echo "Port ${probe_port} is not responding. Refusing to expose a dead port." >&2
+        echo "Confirm the app is up locally (loki preview) before sharing it." >&2
+        return 1
+    fi
+
+    # Consent (default-OFF). Print the full warning every time (even with --yes).
+    echo "WARNING: This makes the app running on THIS machine reachable by ANYONE who has"
+    echo "the URL, over the public internet, using YOUR tunnel account."
+    echo "- The app may have NO authentication. Anyone with the link can use it."
+    echo "- Traffic flows through your own cloudflared/ngrok account, not through Loki."
+    echo "- This stays up until you stop it. Stop it when you are done."
+    echo ""
+
+    if [ "$assume_yes" = true ]; then
+        : # --yes: warning printed above; skip the prompt.
+    elif [ -t 0 ]; then
+        # Interactive TTY. Default-N: only ^[Yy] proceeds. (Deliberately NOT the
+        # default-Y idiom at :1894 -- public exposure is unsafe by default.)
+        local confirm=""
+        echo -e "Expose this app publicly? [y/N] \c"
+        read -r confirm || true
+        if [[ ! "$confirm" =~ ^[Yy] ]]; then
+            echo "Aborted. App was not exposed."
+            return 0
+        fi
+    else
+        # Non-TTY without --yes: never silently expose.
+        echo "Refusing to expose a public tunnel non-interactively without --yes." >&2
+        return 1
+    fi
+
+    # === SEAM (Agent B): provider detection + tunnel launch + URL extraction ===
+
+    # Provider detection (SS5). command -v based so a PATH stub works in tests.
+    # If $provider was requested, require exactly that one; else prefer
+    # cloudflared (no account needed for quick tunnels) then ngrok.
+    local chosen_provider=""
+    if [ -n "$provider" ]; then
+        # Allowlist: only cloudflared/ngrok are supported. Without this guard an
+        # arbitrary on-PATH binary name (e.g. --provider ls) would set
+        # chosen_provider and fall through to the ngrok launch branch below.
+        case "$provider" in
+            cloudflared|ngrok) ;;
+            *)
+                echo -e "${RED}Unsupported tunnel provider: ${provider}${NC}" >&2
+                echo "Supported providers: cloudflared, ngrok" >&2
+                return 1
+                ;;
+        esac
+        if command -v "$provider" >/dev/null 2>&1; then
+            chosen_provider="$provider"
+        fi
+    else
+        if command -v cloudflared >/dev/null 2>&1; then
+            chosen_provider="cloudflared"
+        elif command -v ngrok >/dev/null 2>&1; then
+            chosen_provider="ngrok"
+        fi
+    fi
+
+    if [ -z "$chosen_provider" ]; then
+        # Honest install hint (mirrors the gh-missing block). Never pretend
+        # success, never download a binary. Loki wraps YOUR OWN client.
+        if [ -n "$provider" ]; then
+            echo -e "${RED}Requested tunnel provider not found: ${provider}${NC}" >&2
+        else
+            echo -e "${RED}No tunnel CLI found (cloudflared or ngrok)${NC}" >&2
+        fi
+        echo "" >&2
+        echo "Loki wraps YOUR OWN tunnel client. It never downloads or bundles one." >&2
+        echo "Install one of the following, then re-run:" >&2
+        echo "" >&2
+        echo "  cloudflared (no account needed for quick tunnels):" >&2
+        echo "    brew install cloudflared                        # macOS" >&2
+        echo "    https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/  # all platforms" >&2
+        echo "" >&2
+        echo "  ngrok (needs a free authtoken):" >&2
+        echo "    brew install ngrok                              # macOS" >&2
+        echo "    https://ngrok.com/download                      # all platforms" >&2
+        return 1
+    fi
+
+    # State dir, parallel to app-runner/.
+    mkdir -p "${LOKI_DIR}/preview" 2>/dev/null || true
+    local log_file="${LOKI_DIR}/preview/${chosen_provider}.log"
+
+    # Build the launch command (SS7/SS8). Host-header rewrite is default-ON to
+    # fix the #1 dev-server "Invalid Host header" failure; --no-host-rewrite
+    # opts out.
+    local -a tunnel_cmd=()
+    if [ "$chosen_provider" = "cloudflared" ]; then
+        tunnel_cmd=(cloudflared tunnel --url "http://localhost:${probe_port}")
+        if [ "$no_host_rewrite" != true ]; then
+            tunnel_cmd+=(--http-host-header localhost)
+        fi
+    else
+        # ngrok
+        tunnel_cmd=(ngrok http "${probe_port}")
+        if [ "$no_host_rewrite" != true ]; then
+            tunnel_cmd+=(--host-header=rewrite)
+        fi
+    fi
+
+    echo ""
+    echo "Starting ${chosen_provider} tunnel for http://localhost:${probe_port} ..."
+
+    # Launch redirected to a log, in the background; capture its pid.
+    "${tunnel_cmd[@]}" > "$log_file" 2>&1 &
+    local tunnel_pid=$!
+
+    # Install teardown immediately so no exit path leaves an orphaned tunnel.
+    trap '_preview_public_teardown "$tunnel_pid" "$log_file"' EXIT INT TERM
+
+    # Poll for the public URL. cloudflared writes it to its log; ngrok exposes
+    # it via the local 4040 API. Bounded loop (~20 x sleep 0.5 = ~10s). Also
+    # detect early tunnel-process death so we fail honestly instead of hanging.
+    local public_url=""
+    local tries=0
+    while [ $tries -lt 20 ]; do
+        # Early death detection: if the tunnel process is gone, report and bail.
+        if ! kill -0 "$tunnel_pid" 2>/dev/null; then
+            echo -e "${RED}${chosen_provider} exited; see ${log_file}${NC}" >&2
+            # Surface the tail of the log for context.
+            tail -n 10 "$log_file" 2>/dev/null >&2 || true
+            if [ "$chosen_provider" = "ngrok" ]; then
+                echo "If this is an auth error, add your token: ngrok config add-authtoken <token>" >&2
+            fi
+            # The EXIT trap fires at SHELL exit, not function return, so reap the
+            # process now and clear the trap. Keep the log for inspection (the
+            # message points at it), so omit the log arg to teardown.
+            _preview_public_teardown "$tunnel_pid"
+            trap - EXIT INT TERM
+            return 1
+        fi
+
+        if [ "$chosen_provider" = "cloudflared" ]; then
+            public_url=$(_extract_tunnel_url_cloudflared "$log_file")
+        else
+            local api_json="${LOKI_DIR}/preview/ngrok-api.json"
+            if curl -s "http://127.0.0.1:4040/api/tunnels" -o "$api_json" 2>/dev/null; then
+                public_url=$(_extract_tunnel_url_ngrok "$api_json")
+            fi
+            rm -f "$api_json" 2>/dev/null || true
+        fi
+
+        if [ -n "$public_url" ]; then
+            break
+        fi
+        sleep 0.5
+        tries=$((tries + 1))
+    done
+
+    if [ -z "$public_url" ]; then
+        echo -e "${RED}Timed out waiting for a public URL from ${chosen_provider}.${NC}" >&2
+        tail -n 10 "$log_file" 2>/dev/null >&2 || true
+        if [ "$chosen_provider" = "ngrok" ]; then
+            echo "ngrok may be missing an authtoken: ngrok config add-authtoken <token>" >&2
+        fi
+        # Reap now (the EXIT trap fires only at shell exit, not function return,
+        # which would orphan the tunnel back in cmd_preview/main). Keep the log
+        # for inspection, so omit the log arg.
+        _preview_public_teardown "$tunnel_pid"
+        trap - EXIT INT TERM
+        return 1
+    fi
+
+    # URL captured. Print it clearly and re-print the live warning.
+    echo ""
+    echo -e "${GREEN}Public preview URL:${NC} ${public_url}"
+    echo ""
+    echo "WARNING: This URL is live and reachable by ANYONE who has it, over the"
+    echo "public internet, through YOUR ${chosen_provider} account. The app may have no"
+    echo "authentication. This stays up until you stop it."
+    echo ""
+    echo "Press Ctrl+C to stop sharing."
+
+    # Foreground-block on the tunnel. Ctrl+C delivers INT -> trap -> teardown.
+    # `wait` returns 130 on signal; guard so set -e does not abort the clean exit.
+    wait "$tunnel_pid" 2>/dev/null || true
+
+    # Idempotent final teardown (the INT trap may already have run) + remove the
+    # log on this success/Ctrl+C path. Clear the trap so it does not re-fire at
+    # shell exit with out-of-scope locals.
+    _preview_public_teardown "$tunnel_pid" "$log_file"
+    trap - EXIT INT TERM
+
+    echo ""
+    echo "Tunnel stopped."
+    return 0
+}
+
+# Open the running app preview (the app Loki built and started locally).
+# Surfaces the existing app-runner state; does not start or change the app.
+cmd_preview() {
+    local open_browser=true
+    local public=false
+    local provider=""
+    local assume_yes=false
+    local no_host_rewrite=false
+
+    # Parse options. Loop so flag combos like `--public --yes` work; preserve
+    # the existing leniency on unknown args (no hard error -> no behavior drift).
+    while [ $# -gt 0 ]; do
+        case "${1:-}" in
+            --help|-h|help)
+                echo -e "${BOLD}Loki Mode -- open the running app preview${NC}"
+                echo ""
+                echo "Usage: loki preview [--no-open]"
+                echo "       loki preview --public [--provider cloudflared|ngrok] [--yes] [--no-host-rewrite]"
+                echo "       loki open      (alias)"
+                echo ""
+                echo "Prints the URL of the app Loki built and started locally, then"
+                echo "opens it in your browser. The app runner starts the app after the"
+                echo "first successful build iteration. This serves a real local build"
+                echo "from localhost on your machine; it is not hosted."
+                echo ""
+                echo "Options:"
+                echo "  --no-open          Print the URL and status only; do not open a browser"
+                echo "  --public           Expose the running app over a PUBLIC URL via your own"
+                echo "                     tunnel CLI (cloudflared or ngrok). Consent-gated,"
+                echo "                     default-OFF. Loki never proxies traffic or bundles a"
+                echo "                     binary; it wraps YOUR OWN tunnel client."
+                echo "  --provider NAME    Tunnel provider for --public: cloudflared or ngrok"
+                echo "                     (default: auto-detect, cloudflared first)"
+                echo "  --yes              Skip the --public consent prompt (warning is still"
+                echo "                     printed). Required to use --public non-interactively"
+                echo "  --no-host-rewrite  Do not rewrite the Host header on the tunnel"
+                echo "  --help, -h         Show this help and exit"
+                echo ""
+                echo "WARNING (--public): exposes THIS machine's app to ANYONE with the URL,"
+                echo "over the public internet, through your own tunnel account. The app may"
+                echo "have no authentication. It stays up until you stop it."
+                return 0
+                ;;
+            --no-open)
+                open_browser=false
+                ;;
+            --public)
+                public=true
+                ;;
+            --provider)
+                provider="${2:-}"
+                # Guard the value-consuming shift: if --provider is the LAST arg
+                # (no value), an unguarded shift here plus the loop's trailing
+                # shift would underflow and abort under set -e. Only consume a
+                # value when one is actually present.
+                [ $# -ge 2 ] && shift
+                ;;
+            --yes)
+                assume_yes=true
+                ;;
+            --no-host-rewrite)
+                no_host_rewrite=true
+                ;;
+        esac
+        shift
+    done
+
+    # --public branches into the tunnel path BEFORE the browser-open logic.
+    # Capture the exit code (set -e safe: a bare non-zero return on the call
+    # line would trip set -e before `return` runs).
+    if [ "$public" = true ]; then
+        local rc=0
+        _preview_public "$provider" "$assume_yes" "$no_host_rewrite" || rc=$?
+        return $rc
+    fi
+
+    local state_file="${LOKI_DIR}/app-runner/state.json"
+    if [ ! -f "$state_file" ]; then
+        echo "No app running. The app runner starts after the first successful build iteration."
+        echo "Run 'loki status' to check the current run."
+        return 0
+    fi
+
+    # Parse url/status/port via the shared helper, then re-split (same logic the
+    # inline parse used; behavior-neutral for the plain preview path).
+    local url status port _state
+    _state=$(_read_app_state "$state_file")
+    url=$(printf '%s\n' "$_state" | sed -n '1p')
+    status=$(printf '%s\n' "$_state" | sed -n '2p')
+    port=$(printf '%s\n' "$_state" | sed -n '3p')
 
     if [ "$status" != "running" ]; then
         echo "App is not running (status: ${status:-unknown})."
@@ -5288,6 +5668,396 @@ except Exception:
     fi
 }
 
+# =============================================================================
+# loki deploy -- ADVISORY / PRINT-ONLY deploy command (FEAT-DEPLOY).
+#
+# WHY ITS OWN COMMAND (not a preview flag): `loki preview` is "show me the local
+# app I already built and started" and is GATED on a running app (state.json
+# status=running, a live reachable port). `loki deploy` is conceptually distinct:
+# it is a STATIC, FILESYSTEM-ONLY advisory about the project's type and the user's
+# installed cloud CLI / CI-CD pipeline. It must work with nothing running and no
+# build started, so it has NO running-app precondition. Folding it into preview
+# would force preview's running-app gate onto a feature that must not have one.
+#
+# HARD INVARIANT (DEPLOY-PLAN LOCK 5 + BRANCH-LIFECYCLE LOCK B4): PRINT-ONLY.
+# cmd_deploy NEVER runs a cloud CLI (vercel/netlify/flyctl/wrangler) -- not even
+# `--version` -- and NEVER runs `git push` or `gh pr create`. Tool detection is
+# `command -v` ONLY. Loki advises; the human runs the printed command. This keeps
+# the README promise ("Does not deploy -- human runs deploy commands") literally
+# true. Only the clipboard tools (pbcopy/wl-copy/...) and `command -v` may run.
+#
+# This whole block is contiguous (helpers + cmd_deploy) so a test can extract it
+# by name anchor, mirroring tests/test-preview-public.sh.
+# =============================================================================
+
+# _deploy_detect_type <dir>
+# Echoes the PRIMARY project-type label (one of: nextjs, static, docker, node,
+# python) or empty if none detected. Read-only file/dir existence + grep on
+# package.json. Always returns 0 (caller treats empty as "no project"). First
+# match wins for the primary label; cmd_deploy still offers multiple provider
+# options per type. set -e safe: every grep is `|| true`-guarded.
+_deploy_detect_type() {
+    local dir="${1:-.}"
+    local pkg="$dir/package.json"
+
+    # 1. Next.js -- source signal ("next" dep or a next.config.*), NOT the build
+    #    artifact (.next/standalone), since the build may not have run yet.
+    if [ -f "$pkg" ] && grep -q '"next"' "$pkg" 2>/dev/null; then
+        printf '%s' "nextjs"; return 0
+    fi
+    if [ -f "$dir/next.config.js" ] || [ -f "$dir/next.config.mjs" ] || [ -f "$dir/next.config.ts" ]; then
+        printf '%s' "nextjs"; return 0
+    fi
+
+    # 2. Static / SPA -- a built dist/ or build/ dir containing index.html, OR a
+    #    Vite / CRA source signal in package.json.
+    if { [ -d "$dir/dist" ] && [ -f "$dir/dist/index.html" ]; } || \
+       { [ -d "$dir/build" ] && [ -f "$dir/build/index.html" ]; }; then
+        printf '%s' "static"; return 0
+    fi
+    if [ -f "$pkg" ] && { grep -q '"vite"' "$pkg" 2>/dev/null || grep -q '"react-scripts"' "$pkg" 2>/dev/null; }; then
+        printf '%s' "static"; return 0
+    fi
+
+    # 3. Dockerfile / containerized server.
+    if [ -f "$dir/Dockerfile" ]; then
+        printf '%s' "docker"; return 0
+    fi
+
+    # 4. Generic Node server -- package.json with a start (or dev) script.
+    if [ -f "$pkg" ] && { grep -q '"start"' "$pkg" 2>/dev/null || grep -q '"dev"' "$pkg" 2>/dev/null; }; then
+        printf '%s' "node"; return 0
+    fi
+
+    # 5. Python.
+    if [ -f "$dir/requirements.txt" ] || [ -f "$dir/pyproject.toml" ]; then
+        printf '%s' "python"; return 0
+    fi
+
+    printf '%s' ""
+    return 0
+}
+
+# _deploy_options_for_type <type>
+# Pure, DIR-BLIND helper: echoes the ordered candidate rows for a project type,
+# one per line, as `provider|cli|command|docs`. Idiomatic provider first per
+# DEPLOY-PLAN LOCK 2. Lists the FULL ordered candidate set for the type
+# UNCONDITIONALLY (no dir awareness, no CLI-installed filtering -- cmd_deploy does
+# the `command -v` filtering). The command strings are the EXACT canonical forms
+# from DEPLOY-PLAN LOCK 3 (a wrong flag is worse than no feature; do not
+# paraphrase). Project-dependent dirs stay as `<...>` placeholders the user fills.
+# Note: the Fly CLI binary is `flyctl` but the canonical deploy verb is
+# `fly deploy` -- "fly" not "flyctl" here is CORRECT, intentional, not a typo.
+_deploy_options_for_type() {
+    local type="${1:-}"
+    case "$type" in
+        nextjs)
+            printf '%s\n' "Vercel|vercel|vercel --prod|https://vercel.com/docs/cli"
+            printf '%s\n' "Netlify|netlify|netlify deploy --prod|https://docs.netlify.com/cli/get-started/"
+            # fly not flyctl - correct: binary is flyctl, deploy verb is `fly deploy`.
+            printf '%s\n' "Fly.io|flyctl|fly deploy|https://fly.io/docs/flyctl/install/"
+            ;;
+        static)
+            printf '%s\n' "Netlify|netlify|netlify deploy --prod --dir=<build-output>|https://docs.netlify.com/cli/get-started/"
+            printf '%s\n' "Cloudflare Pages|wrangler|wrangler pages deploy <build-output>|https://developers.cloudflare.com/workers/wrangler/install-and-update/"
+            printf '%s\n' "Vercel|vercel|vercel --prod|https://vercel.com/docs/cli"
+            ;;
+        docker)
+            # fly not flyctl - correct (see note above).
+            printf '%s\n' "Fly.io|flyctl|fly deploy|https://fly.io/docs/flyctl/install/"
+            printf '%s\n' "Cloudflare|wrangler|wrangler deploy|https://developers.cloudflare.com/workers/wrangler/install-and-update/"
+            ;;
+        node)
+            # fly not flyctl - correct (see note above).
+            printf '%s\n' "Fly.io|flyctl|fly deploy|https://fly.io/docs/flyctl/install/"
+            printf '%s\n' "Vercel|vercel|vercel --prod|https://vercel.com/docs/cli"
+            ;;
+        python)
+            # fly not flyctl - correct (see note above).
+            printf '%s\n' "Fly.io|flyctl|fly deploy|https://fly.io/docs/flyctl/install/"
+            ;;
+    esac
+    return 0
+}
+
+# _deploy_detect_cicd <dir>
+# Returns 0 + echoes the detected CI/CD system name(s) (space-separated) if ANY
+# pipeline config exists (BRANCH-LIFECYCLE LOCK B1); returns 1 + echoes nothing
+# if none. Read-only file existence only. The `[ -e "$f" ]` guard inside the glob
+# loop makes the no-match literal-glob case set -e safe (an unmatched glob expands
+# to the literal pattern, which `[ -e ]` then rejects without aborting).
+_deploy_detect_cicd() {
+    local dir="${1:-.}"
+    local found=""
+    local systems=""
+
+    # GitHub Actions: any .yml or .yaml under .github/workflows/.
+    local f
+    for f in "$dir"/.github/workflows/*.yml "$dir"/.github/workflows/*.yaml; do
+        if [ -e "$f" ]; then found=1; systems="${systems} GitHub-Actions"; break; fi
+    done
+
+    [ -f "$dir/.gitlab-ci.yml" ] && { found=1; systems="${systems} GitLab-CI"; }
+    [ -f "$dir/Jenkinsfile" ] && { found=1; systems="${systems} Jenkins"; }
+    [ -f "$dir/.circleci/config.yml" ] && { found=1; systems="${systems} CircleCI"; }
+    [ -f "$dir/azure-pipelines.yml" ] && { found=1; systems="${systems} Azure-Pipelines"; }
+    [ -f "$dir/bitbucket-pipelines.yml" ] && { found=1; systems="${systems} Bitbucket-Pipelines"; }
+
+    if [ -n "$found" ]; then
+        # Trim the leading space and echo the names.
+        printf '%s' "${systems# }"
+        return 0
+    fi
+    printf '%s' ""
+    return 1
+}
+
+# _deploy_copy_clipboard <cmd>
+# Best-effort clipboard copy of a SINGLE command (DEPLOY-PLAN LOCK 4). TTY-gated,
+# command-v guarded, ALWAYS returns 0 and never fatal. Echoes a confirmation note
+# only if a copy tool actually ran. These clipboard tools ARE allowed to run; only
+# the four cloud CLIs are forbidden.
+_deploy_copy_clipboard() {
+    local cmd="${1:-}"
+    [ -n "$cmd" ] || return 0
+    [ -t 1 ] || return 0
+    local copied=""
+    if command -v pbcopy >/dev/null 2>&1; then
+        printf '%s' "$cmd" | pbcopy >/dev/null 2>&1 && copied="1" || true
+    elif command -v wl-copy >/dev/null 2>&1; then
+        printf '%s' "$cmd" | wl-copy >/dev/null 2>&1 && copied="1" || true
+    elif command -v xclip >/dev/null 2>&1; then
+        printf '%s' "$cmd" | xclip -selection clipboard >/dev/null 2>&1 && copied="1" || true
+    elif command -v xsel >/dev/null 2>&1; then
+        printf '%s' "$cmd" | xsel --clipboard --input >/dev/null 2>&1 && copied="1" || true
+    elif command -v clip >/dev/null 2>&1; then
+        printf '%s' "$cmd" | clip >/dev/null 2>&1 && copied="1" || true
+    fi
+    if [ -n "$copied" ]; then
+        printf '%s\n' "  (copied to clipboard: ${cmd})"
+    fi
+    return 0
+}
+
+# _deploy_print_install_hint <type>
+# Honest install hints (brew + official URL) for the candidate providers of a
+# type. NEVER fabricates success, NEVER downloads a binary. Mirrors the
+# tunnel-missing / gh-missing block. Caller redirects to stderr.
+_deploy_print_install_hint() {
+    local type="${1:-}"
+    echo "No deploy CLI found for this ${type} project."
+    echo "Loki never accesses your cloud account or runs deploy for you -- you run"
+    echo "the printed command. Install one of the following, then re-run 'loki deploy':"
+    echo ""
+    local options provider cli command docs
+    options="$(_deploy_options_for_type "$type")"
+    while IFS='|' read -r provider cli command docs; do
+        [ -n "$provider" ] || continue
+        case "$cli" in
+            vercel)   echo "  Vercel:      brew install vercel       |  ${docs}" ;;
+            netlify)  echo "  Netlify:     brew install netlify-cli  |  ${docs}" ;;
+            flyctl)   echo "  Fly.io:      brew install flyctl       |  ${docs}" ;;
+            wrangler) echo "  Cloudflare:  npm i -g wrangler         |  ${docs}" ;;
+            *)        echo "  ${provider}:  ${docs}" ;;
+        esac
+    done <<EOF
+$options
+EOF
+    return 0
+}
+
+# _deploy_print_cloud_options <dir> <type> <do_clip> <hint_on_none>
+# Prints every installed (project-type x CLI) option block, idiomatic first.
+# Best-effort copies the FIRST installed command when do_clip=true. Returns 0 if
+# at least one CLI was printed. If NONE installed: when hint_on_none=true, prints
+# the honest install hint (to stderr) and returns 1; when false (pipeline path,
+# where cloud is secondary), prints nothing and returns 1 silently.
+_deploy_print_cloud_options() {
+    local dir="${1:-.}"
+    local type="${2:-}"
+    local do_clip="${3:-true}"
+    local hint_on_none="${4:-true}"
+
+    local options=""
+    options="$(_deploy_options_for_type "$type")"
+
+    local printed=false
+    local first_cmd=""
+    local provider cli command docs
+    while IFS='|' read -r provider cli command docs; do
+        [ -n "$cli" ] || continue
+        if command -v "$cli" >/dev/null 2>&1; then
+            if [ "$printed" != true ]; then
+                echo -e "${BOLD}Detected ${type} project. Deploy options (run one yourself):${NC}"
+                echo ""
+                printed=true
+            fi
+            echo "  ${provider}:"
+            echo "    ${command}"
+            echo "    docs: ${docs}"
+            echo ""
+            if [ -z "$first_cmd" ]; then
+                first_cmd="$command"
+            fi
+        fi
+    done <<EOF
+$options
+EOF
+
+    if [ "$printed" = true ]; then
+        echo "Loki does not deploy for you. Review, then run the command yourself."
+        if [ "$do_clip" = true ] && [ -n "$first_cmd" ]; then
+            _deploy_copy_clipboard "$first_cmd"
+        fi
+        return 0
+    fi
+
+    # No installed CLI for this type.
+    if [ "$hint_on_none" = true ]; then
+        _deploy_print_install_hint "$type" >&2
+        return 1
+    fi
+    return 1
+}
+
+# cmd_deploy [--dir <path>] [--no-clip] [--help]
+# Advisory orchestration: detect project type + CI/CD pipeline + installed cloud
+# CLIs, then PRINT the canonical deploy command(s). PRINT-ONLY (see block header).
+# Placed LAST in the contiguous deploy block (all helpers above it) so the SDET
+# can extract from the first helper def to the close of cmd_deploy and capture the
+# whole self-contained unit (mirrors test-preview-public.sh, where cmd_preview is
+# the terminal function).
+cmd_deploy() {
+    local dir="${TARGET_DIR:-.}"
+    local do_clip=true
+
+    # Arg parse (mirror cmd_preview: lenient on unknown args -> no behavior drift).
+    while [ $# -gt 0 ]; do
+        case "${1:-}" in
+            --help|-h|help)
+                echo -e "${BOLD}Loki Mode -- advisory deploy command (print-only)${NC}"
+                echo ""
+                echo "Usage: loki deploy [--dir <path>] [--no-clip]"
+                echo ""
+                echo "Detects your project type and your installed cloud CLI (and any"
+                echo "CI/CD pipeline), then PRINTS the exact deploy command for YOU to run."
+                echo "It is advisory only: it NEVER deploys, NEVER runs a cloud CLI (not"
+                echo "even --version), and NEVER runs 'git push'. Loki does not access your"
+                echo "cloud account. You run the printed command. Detection is read-only."
+                echo ""
+                echo "If a CI/CD pipeline (GitHub Actions, GitLab CI, Jenkins, CircleCI,"
+                echo "Azure Pipelines, Bitbucket) is detected, the primary advice is the"
+                echo "git push + pull-request path, because your pipeline deploys on merge."
+                echo ""
+                echo "Options:"
+                echo "  --dir <path>   Project directory to scan (default: current dir)"
+                echo "  --no-clip      Do not copy the idiomatic command to the clipboard"
+                echo "  --help, -h     Show this help and exit"
+                return 0
+                ;;
+            --dir)
+                dir="${2:-.}"
+                # Guard the value-consuming shift: if --dir is the LAST arg (no
+                # value), an unguarded shift plus the loop's trailing shift would
+                # underflow and abort under set -e. Consume a value only if present.
+                [ $# -ge 2 ] && shift
+                ;;
+            --no-clip)
+                do_clip=false
+                ;;
+        esac
+        shift
+    done
+
+    # Resolve to '.' if the chosen dir does not exist (honest, no crash).
+    [ -d "$dir" ] || dir="."
+
+    # Detect CI/CD pipeline FIRST (BRANCH-LIFECYCLE LOCK B3 precedence).
+    local cicd=""
+    cicd="$(_deploy_detect_cicd "$dir" || true)"
+    local has_pipeline=false
+    [ -n "$cicd" ] && has_pipeline=true
+
+    # Detect project type (filesystem-only; LOCK 6 -- not gated on a running app).
+    local type=""
+    type="$(_deploy_detect_type "$dir")"
+
+    # ---- Pipeline path (LOCK B3): git push + PR advised FIRST, cloud secondary.
+    if [ "$has_pipeline" = true ]; then
+        echo -e "${BOLD}CI/CD pipeline detected (${cicd})${NC}"
+        echo "Your pipeline deploys on push/merge, so the primary deploy path is"
+        echo "commit + push + pull request:"
+        echo ""
+
+        # Derive base/head for the PR advice. set -e safe: every git call is
+        # 2>/dev/null with a fallback so a non-zero git never aborts the shell.
+        local head="" base=""
+        head="$(git -C "$dir" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")"
+        [ -n "$head" ] || head="HEAD"
+        case "$head" in
+            loki/*)
+                # On a loki branch: prefer the persisted base, else origin default.
+                if [ -s "$dir/.loki/state/base-branch.txt" ]; then
+                    base="$(head -n1 "$dir/.loki/state/base-branch.txt" 2>/dev/null || echo "")"
+                fi
+                ;;
+        esac
+        if [ -z "$base" ]; then
+            # Best-effort: origin's default branch (e.g. origin/main -> main).
+            local origin_head=""
+            origin_head="$(git -C "$dir" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo "")"
+            if [ -n "$origin_head" ]; then
+                base="${origin_head##*/}"
+            fi
+        fi
+
+        if [ -n "$base" ] && declare -F print_pr_advice >/dev/null 2>&1; then
+            print_pr_advice "$base" "$head" "$dir"
+        elif declare -F print_pr_advice >/dev/null 2>&1; then
+            echo "  Could not determine the PR base branch automatically."
+            echo "  Set your PR base manually when opening the pull request for: ${head}"
+            print_pr_advice "manually-set-base" "$head" "$dir"
+        else
+            echo "  git push -u origin ${head}"
+            echo "  Open a pull request for ${head} (set the base branch manually)."
+        fi
+        echo ""
+
+        # Cloud CLI options are SECONDARY when a pipeline exists. Print them if a
+        # project type + installed CLI match, but never fail the command on their
+        # absence (the git/PR advice above is the real deliverable here).
+        if [ -n "$type" ]; then
+            # Pass do_clip=false here: in the pipeline path the git push line is
+            # the PRIMARY advice (LOCK B3) and print_pr_advice already copied it to
+            # the clipboard, so the secondary cloud command must NOT overwrite it.
+            local printed_any=false
+            _deploy_print_cloud_options "$dir" "$type" "false" "false" && printed_any=true || true
+            if [ "$printed_any" != true ]; then
+                : # No installed cloud CLI; the pipeline path already advised. Fine.
+            fi
+        fi
+        return 0
+    fi
+
+    # ---- No-pipeline path: cloud-CLI advisory exactly per DEPLOY-PLAN.md.
+    # Honest failure: no project type detected.
+    if [ -z "$type" ]; then
+        {
+            echo "No deployable project detected in: ${dir}"
+            echo "Looked for: package.json (Next.js/Vite/CRA/Node), Dockerfile,"
+            echo "dist/ or build/ with index.html, requirements.txt, pyproject.toml."
+            echo "Run 'loki deploy --dir <path>' to point at your project directory."
+        } >&2
+        return 1
+    fi
+
+    # Print cloud options; clipboard the idiomatic one. Returns non-zero (with an
+    # honest install hint) when NO matching CLI is installed.
+    local rc=0
+    _deploy_print_cloud_options "$dir" "$type" "$do_clip" "true" || rc=$?
+    return $rc
+}
+
 # Import GitHub issues
 cmd_import() {
     # v7.6.2 B-13 fix: --help must print help, not start an import.
@@ -14596,6 +15366,9 @@ main() {
         preview)
             cmd_preview "$@"
             ;;
+        deploy)
+            cmd_deploy "$@"
+            ;;
         open)
             # CLI consolidation (Phase A): 'open' is a deprecated alias of 'preview'.
             _deprecated_alias open preview "$@"