create-workframe 0.1.8 → 0.1.10

package/README.md

@@ -3,7 +3,7 @@
 Published on npm as **create-workframe**.
 
 ```bash
-npx create-workframe@0.1.8 MyProject
+npx create-workframe@0.1.9 MyProject
 ```
 
 Scaffolds an isolated Workframe + Hermes project on Windows, macOS, and Linux.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-workframe",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Scaffold a Workframe + Hermes workspace with guided onboarding",
   "type": "module",
   "bin": {

package/scripts/apply-update-workframe.sh

@@ -43,6 +43,60 @@ _wf_sync_tree() {
   cp -a "${src}/." "${dest}/"
 }
 
+_wf_sync_from_pack_dir() {
+  local pkg="$1"
+  if [[ -d "$pkg/workframe-api" ]]; then
+    echo "Syncing workframe-api -> $API_DIR"
+    _wf_sync_tree "$pkg/workframe-api" "$API_DIR"
+  fi
+  if [[ -d "$pkg/workframe-supervisor" ]]; then
+    echo "Syncing workframe-supervisor -> $SUP_DIR"
+    _wf_sync_tree "$pkg/workframe-supervisor" "$SUP_DIR"
+  fi
+  if [[ -d "$pkg/workframe-ui/public" ]]; then
+    echo "Syncing workframe-ui/public -> $UI_DIR"
+    _wf_sync_tree "$pkg/workframe-ui/public" "$UI_DIR"
+  fi
+  for script in apply-update-hermes.sh apply-update-workframe.sh restart-gateway-hermes.sh compose-docker-host.sh update-hermes.sh; do
+    if [[ -f "$pkg/scripts/$script" ]]; then
+      cp -a "$pkg/scripts/$script" "$SCRIPTS_DIR/$script"
+      chmod +x "$SCRIPTS_DIR/$script" 2>/dev/null || true
+    fi
+  done
+}
+
+_wf_apply_npm_tarball() {
+  local tarball="$1"
+  local ver="${2:-latest}"
+  if ! _wf_npm_integrity_ok "$tarball" "$NPM_PACKAGE" "$ver"; then
+    echo "integrity mismatch for ${NPM_PACKAGE}@${ver}" >&2
+    exit 1
+  fi
+  echo "integrity ok: ${NPM_PACKAGE}@${ver}"
+  local extract_dir
+  extract_dir="$(mktemp -d)"
+  tar -xf "$tarball" -C "$extract_dir"
+  _wf_sync_from_pack_dir "$extract_dir/package"
+  rm -rf "$extract_dir"
+}
+
+_wf_record_package_version() {
+  local ver="$1"
+  [[ -n "$ver" ]] || return 0
+  mkdir -p "$API_DIR/data"
+  printf '%s\n' "$ver" > "$API_DIR/data/package-version"
+  if [[ -f "$PROJECT_ROOT/workframe-manifest.json" ]] && command -v python3 >/dev/null 2>&1; then
+    python3 -c 'import json, sys
+from pathlib import Path
+p = Path(sys.argv[1])
+ver = sys.argv[2]
+data = json.loads(p.read_text(encoding="utf-8"))
+data["package_version"] = ver
+data["generator"] = f"create-workframe@{ver}"
+p.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")' "$PROJECT_ROOT/workframe-manifest.json" "$ver"
+  fi
+}
+
 _wf_install_paths() {
   local root="$1"
   if [[ -d "$root/services/workframe-api" ]]; then
@@ -88,8 +142,12 @@ echo "Preserves: Agents/, Files/, .env, workframe-api/data, gateway/Hermes profi
 
 TARGET_VERSION="${WORKFRAME_UPDATE_VERSION:-}"
 NPM_PACKAGE="${WORKFRAME_NPM_PACKAGE:-create-workframe}"
+PREFETCH_TARBALL="${WORKFRAME_UPDATE_TARBALL:-}"
 
-if [[ "${WORKFRAME_UPDATE_SKIP_NPM:-1}" == "1" ]] && [[ "${WORKFRAME_UPDATE_ALLOW_NPM:-}" != "1" ]]; then
+if [[ -n "$PREFETCH_TARBALL" && -f "$PREFETCH_TARBALL" ]]; then
+  echo "Applying API-prefetched tarball: $PREFETCH_TARBALL"
+  _wf_apply_npm_tarball "$PREFETCH_TARBALL" "${TARGET_VERSION:-latest}"
+elif [[ "${WORKFRAME_UPDATE_SKIP_NPM:-1}" == "1" ]] && [[ "${WORKFRAME_UPDATE_ALLOW_NPM:-}" != "1" ]]; then
   echo "Skipping npm template sync (WORKFRAME_UPDATE_SKIP_NPM=1; set WORKFRAME_UPDATE_ALLOW_NPM=1 to fetch)"
 elif command -v npm >/dev/null 2>&1; then
   if [[ "${WORKFRAME_UPDATE_ALLOW_NPM:-}" == "1" ]] && [[ -z "$TARGET_VERSION" ]]; then
@@ -99,36 +157,16 @@ elif command -v npm >/dev/null 2>&1; then
   TMP="$(mktemp -d)"
   trap 'rm -rf "$TMP"' EXIT
   echo "Fetching ${NPM_PACKAGE}@${TARGET_VERSION:-latest} from npm..."
-  (cd "$TMP" && npm pack "${NPM_PACKAGE}@${TARGET_VERSION:-latest}" --silent)
+  if ! (cd "$TMP" && npm pack "${NPM_PACKAGE}@${TARGET_VERSION:-latest}" --silent); then
+    echo "npm pack failed (supervisor control-net has no registry access — use API prefetch)" >&2
+    exit 1
+  fi
   TARBALL="$(ls -1 "$TMP"/${NPM_PACKAGE}-*.tgz 2>/dev/null | head -n1 || true)"
   if [[ -n "$TARBALL" ]]; then
-    if ! _wf_npm_integrity_ok "$TARBALL" "$NPM_PACKAGE" "${TARGET_VERSION:-latest}"; then
-      echo "integrity mismatch for ${NPM_PACKAGE}@${TARGET_VERSION:-latest}" >&2
-      exit 1
-    fi
-    echo "integrity ok: ${NPM_PACKAGE}@${TARGET_VERSION:-latest}"
-    tar -xf "$TARBALL" -C "$TMP"
-    PKG="$TMP/package"
-    if [[ -d "$PKG/workframe-api" ]]; then
-      echo "Syncing workframe-api -> $API_DIR"
-      _wf_sync_tree "$PKG/workframe-api" "$API_DIR"
-    fi
-    if [[ -d "$PKG/workframe-supervisor" ]]; then
-      echo "Syncing workframe-supervisor -> $SUP_DIR"
-      _wf_sync_tree "$PKG/workframe-supervisor" "$SUP_DIR"
-    fi
-    if [[ -d "$PKG/workframe-ui/public" ]]; then
-      echo "Syncing workframe-ui/public -> $UI_DIR"
-      _wf_sync_tree "$PKG/workframe-ui/public" "$UI_DIR"
-    fi
-    for script in apply-update-hermes.sh apply-update-workframe.sh restart-gateway-hermes.sh compose-docker-host.sh update-hermes.sh; do
-      if [[ -f "$PKG/scripts/$script" ]]; then
-        cp -a "$PKG/scripts/$script" "$SCRIPTS_DIR/$script"
-        chmod +x "$SCRIPTS_DIR/$script" 2>/dev/null || true
-      fi
-    done
+    _wf_apply_npm_tarball "$TARBALL" "${TARGET_VERSION:-latest}"
   else
-    echo "npm pack produced no tarball — skipping template sync"
+    echo "npm pack produced no tarball — skipping template sync" >&2
+    exit 1
   fi
 else
   echo "Skipping npm template sync (npm missing or WORKFRAME_UPDATE_SKIP_NPM=1)"
@@ -136,7 +174,16 @@ fi
 
 echo "Rebuilding workframe-api and workframe-supervisor..."
 workframe_compose build workframe-api workframe-supervisor
-workframe_compose up -d --build --no-deps workframe-api workframe-supervisor
+if [[ "${WORKFRAME_UPDATE_FROM_SUPERVISOR:-}" == "1" ]]; then
+  # ponytail: supervisor cannot recreate itself inside the stack.apply request — defer after handler returns
+  workframe_compose up -d --build --no-deps workframe-api
+  (
+    sleep 3
+    workframe_compose up -d --no-deps workframe-supervisor
+  ) >/tmp/workframe-supervisor-restart.log 2>&1 &
+else
+  workframe_compose up -d --build --no-deps workframe-api workframe-supervisor
+fi
 
 if workframe_compose config --services 2>/dev/null | grep -qx workframe-ui; then
   workframe_compose up -d --no-deps workframe-ui || workframe_compose restart workframe-ui || true
@@ -144,4 +191,6 @@ elif workframe_compose config --services 2>/dev/null | grep -qx workframe; then
   workframe_compose up -d --no-deps workframe || workframe_compose restart workframe || true
 fi
 
+_wf_record_package_version "${TARGET_VERSION:-}"
+
 echo "=== Workframe update complete ==="

package/scripts/compose-docker-host.sh

@@ -6,12 +6,18 @@ workframe_compose_prepare() {
   compose_cd=""
   compose_files=()
 
-  # Host-bindings overlay: docker.sock apply from supervisor uses WORKFRAME_HOST_* paths.
+  # Host-bindings overlay: absolute WORKFRAME_HOST_* paths for docker.sock on the real host.
+  # Skip inside supervisor when only the /compose bind mount is visible — host paths become
+  # /compose/D:/... and break build contexts.
   if [[ -n "${WORKFRAME_HOST_COMPOSE_DIR:-}" && -n "${WORKFRAME_COMPOSE_DIR:-}" \
         && -f "${WORKFRAME_COMPOSE_DIR}/docker-compose.yml" \
         && -f "${WORKFRAME_COMPOSE_DIR}/docker-compose.host-bindings.yml" ]]; then
     compose_cd="${WORKFRAME_COMPOSE_DIR}"
-    compose_files=(-f docker-compose.yml -f docker-compose.host-bindings.yml)
+    if [[ -d "${WORKFRAME_HOST_COMPOSE_DIR}" ]]; then
+      compose_files=(-f docker-compose.yml -f docker-compose.host-bindings.yml)
+    else
+      compose_files=(-f docker-compose.yml)
+    fi
     return 0
   fi
 

package/workframe-api/.dockerignore

@@ -0,0 +1,4 @@
+data/
+__pycache__/
+*.pyc
+.pytest_cache/

package/workframe-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workframe/workframe-api",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "private": true,
   "type": "module",
   "scripts": {

package/workframe-api/server.py

@@ -551,44 +551,11 @@ def _admin_write_allowed(handler: BaseHTTPRequestHandler) -> bool:
 
 
 def _apply_stack_update(target: str) -> dict[str, Any]:
-    workframe_version = ""
-    if target in {"workframe", "all"}:
-        try:
-            workframe_version = str(
-                stack_updates.updates_available().get("workframe", {}).get("latest") or ""
-            ).strip()
-        except Exception:  # noqa: BLE001
-            workframe_version = ""
-    try:
-        return stack_updates.apply_update(target)
-    except ValueError as exc:
-        err = str(exc)
-        if not _supervisor_ready():
-            raise
-        if err not in ("docker_unavailable", "admin_updates_disabled"):
-            raise
-        body: dict[str, Any] = {"target": target}
-        if workframe_version:
-            body["workframe_version"] = workframe_version
-        status, data = _supervisor_request("POST", "/v1/stack.apply", body, timeout=900.0)
-        if status >= 300 or not isinstance(data, dict) or not data.get("ok"):
-            raise ValueError(str((data or {}).get("error") or "supervisor_apply_failed"))
-        return data
+    return stack_updates.apply_update(target)
 
 
 def _restart_stack_gateway() -> dict[str, Any]:
-    try:
-        return stack_updates.restart_gateway()
-    except ValueError as exc:
-        # ponytail: SECURE_MODE API has no docker.sock; supervisor owns gateway restart
-        if str(exc) not in ("docker_unavailable", "admin_updates_disabled") or not _supervisor_ready():
-            raise
-        status, data = _supervisor_request(
-            "POST", "/v1/stack.apply", {"target": "gateway-restart"}, timeout=300.0,
-        )
-        if status >= 300 or not isinstance(data, dict) or not data.get("ok"):
-            raise ValueError(str((data or {}).get("error") or "supervisor_restart_failed"))
-        return data
+    return stack_updates.restart_gateway()
 
 
 def _cors_origin_for(headers=None) -> str:

package/workframe-api/updates.py

@@ -53,6 +53,55 @@ def _npm_latest_version() -> str:
     return str(data.get("version") or "").strip()
 
 
+def _supervisor_tarball_path(package: str, version: str) -> str:
+    """Path on the compose bind mount — supervisor reads /compose even when API lacks that mount."""
+    for raw in (os.environ.get("WORKFRAME_COMPOSE_DIR", ""), "/compose"):
+        root = str(raw or "").strip().rstrip("/")
+        if root and root != ".":
+            return f"{root}/workframe-api/data/.update-staging/{package}-{version}.tgz"
+    data_dir = Path(os.environ.get("WORKFRAME_API_DATA_DIR", "/app/data"))
+    return str(data_dir / ".update-staging" / f"{package}-{version}.tgz")
+
+
+def prefetch_workframe_npm_tarball(version: str) -> str:
+    """Download create-workframe pack to API data dir; return supervisor-visible path."""
+    import base64
+    import hashlib
+
+    ver = str(version or "").strip()
+    if not ver:
+        raise ValueError("workframe_version_required")
+    pkg = NPM_PACKAGE
+    try:
+        meta = _http_json(
+            f"https://registry.npmjs.org/{urllib.parse.quote(pkg)}/{urllib.parse.quote(ver)}",
+            timeout=60.0,
+        )
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError) as exc:
+        raise ValueError(f"npm_fetch_failed:{exc}") from exc
+    dist = meta.get("dist") if isinstance(meta.get("dist"), dict) else {}
+    url = str(dist.get("tarball") or "").strip()
+    integrity = str(dist.get("integrity") or "").strip()
+    if not url:
+        raise ValueError("npm_tarball_url_missing")
+    data_dir = Path(os.environ.get("WORKFRAME_API_DATA_DIR", "/app/data"))
+    staging = data_dir / ".update-staging"
+    staging.mkdir(parents=True, exist_ok=True)
+    dest = staging / f"{pkg}-{ver}.tgz"
+    req = urllib.request.Request(url, headers={"User-Agent": "workframe-api"})
+    try:
+        with urllib.request.urlopen(req, timeout=300.0) as resp:
+            body = resp.read()
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        raise ValueError(f"npm_download_failed:{exc}") from exc
+    if integrity.startswith("sha512-"):
+        actual = "sha512-" + base64.b64encode(hashlib.sha512(body).digest()).decode()
+        if actual != integrity:
+            raise ValueError("npm_integrity_mismatch")
+    dest.write_bytes(body)
+    return _supervisor_tarball_path(pkg, ver)
+
+
 def _docker_hub_digest(repo: str, tag: str) -> str:
     url = f"https://hub.docker.com/v2/repositories/{repo}/tags/{urllib.parse.quote(tag)}"
     data = _http_json(url)
@@ -113,8 +162,11 @@ def _container_image_digest(name: str) -> tuple[str, str]:
 
 def _read_installed_workframe_version(project_root: Path) -> dict[str, str]:
     out = {"api": API_VERSION, "package": "", "manifest_generator": ""}
+    pin = Path(os.environ.get("WORKFRAME_API_DATA_DIR", "/app/data")) / "package-version"
+    if pin.is_file():
+        out["package"] = pin.read_text(encoding="utf-8").strip()
     manifest = project_root / "workframe-manifest.json"
-    if manifest.is_file():
+    if not out["package"] and manifest.is_file():
         try:
             data = json.loads(manifest.read_text(encoding="utf-8"))
             out["package"] = str(data.get("package_version") or "")
@@ -404,36 +456,64 @@ def updates_available(*, desktop_version: str = "", hermes_agent_version: str =
     }
 
 
-def _apply_env_for_target(target: str) -> dict[str, str]:
-    env = os.environ.copy()
-    env.setdefault("WORKFRAME_COMPOSE_DIR", str(_compose_dir()))
-    env.setdefault("WORKFRAME_PROJECT_ROOT", str(_project_root()))
-    if target in {"workframe", "all"}:
-        latest = ""
+def _supervisor_stack_apply(body: dict[str, Any], *, timeout: float = 900.0) -> dict[str, Any]:
+    if not _supervisor_configured():
+        raise ValueError("supervisor_not_configured")
+    base = str(os.environ.get("WORKFRAME_SUPERVISOR_URL", "")).rstrip("/")
+    token = str(os.environ.get("WORKFRAME_SUPERVISOR_TOKEN", "")).strip()
+    payload = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        f"{base}/v1/stack.apply",
+        data=payload,
+        method="POST",
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": "workframe-api",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            data = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as exc:
+        detail = exc.read().decode("utf-8", errors="replace")
         try:
-            latest = str(updates_available().get("workframe", {}).get("latest") or "").strip()
-        except Exception:  # noqa: BLE001
-            latest = ""
-        if latest:
-            env["WORKFRAME_UPDATE_ALLOW_NPM"] = "1"
-            env["WORKFRAME_UPDATE_VERSION"] = latest
-    return env
+            parsed = json.loads(detail)
+            if isinstance(parsed, dict) and parsed.get("error"):
+                raise ValueError(str(parsed["error"])) from exc
+        except json.JSONDecodeError:
+            pass
+        raise ValueError(f"supervisor_apply_failed:{exc.code}") from exc
+    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError, OSError) as exc:
+        raise ValueError(f"supervisor_apply_failed:{exc}") from exc
+    if not isinstance(data, dict) or not data.get("ok"):
+        raise ValueError(str(data.get("error") or "supervisor_apply_failed"))
+    return data
 
 
-def apply_update(target: str) -> dict[str, Any]:
-    if not _admin_stack_updates_enabled():
-        raise ValueError("admin_updates_disabled")
-    target = str(target or "all").strip().lower()
-    if target not in {"hermes", "workframe", "all"}:
-        raise ValueError("invalid_update_target")
-    _, apply_ready, apply_reason = _update_apply_channel()
-    if not apply_ready:
-        if not Path(DOCKER_SOCK).exists():
-            raise ValueError("docker_unavailable")
-        raise ValueError(str(apply_reason or "docker_apply_unavailable"))
-    if not Path(DOCKER_SOCK).exists():
-        raise ValueError("docker_unavailable")
+def _workframe_update_target_version() -> str:
+    try:
+        return str(updates_available().get("workframe", {}).get("latest") or "").strip()
+    except Exception:  # noqa: BLE001
+        return ""
+
+
+def _visible_tarball_path(package: str, version: str, *, channel: str) -> str:
+    if channel == "supervisor":
+        return _supervisor_tarball_path(package, version)
+    return str(Path(os.environ.get("WORKFRAME_API_DATA_DIR", "/app/data")) / ".update-staging" / f"{package}-{version}.tgz")
 
+
+def _prepare_workframe_update(channel: str) -> tuple[str, str]:
+    version = _workframe_update_target_version()
+    if not version:
+        raise ValueError("workframe_update_version_unavailable")
+    prefetch_workframe_npm_tarball(version)
+    return version, _visible_tarball_path(NPM_PACKAGE, version, channel=channel)
+
+
+def _run_apply_scripts(target: str, env: dict[str, str]) -> dict[str, Any]:
     scripts: list[str] = []
     if target in {"hermes", "all"}:
         script = _script_path("apply-update-hermes.sh")
@@ -446,8 +526,6 @@ def apply_update(target: str) -> dict[str, Any]:
             raise ValueError("update_script_missing:workframe")
         scripts.append(str(script))
 
-    env = _apply_env_for_target(target)
-
     logs: list[str] = []
     for script in scripts:
         proc = subprocess.run(
@@ -461,18 +539,53 @@ def apply_update(target: str) -> dict[str, Any]:
         logs.append(f"=== {script} (exit {proc.returncode}) ===\n{proc.stdout}\n{proc.stderr}")
         if proc.returncode != 0:
             raise ValueError(f"update_failed:{Path(script).name}")
-
     return {"ok": True, "target": target, "log": "\n".join(logs)[-12000:]}
 
 
+def apply_update(target: str) -> dict[str, Any]:
+    if not _admin_stack_updates_enabled():
+        raise ValueError("admin_updates_disabled")
+    target = str(target or "all").strip().lower()
+    if target not in {"hermes", "workframe", "all"}:
+        raise ValueError("invalid_update_target")
+    channel, apply_ready, apply_reason = _update_apply_channel()
+    if not apply_ready:
+        raise ValueError(str(apply_reason or "docker_apply_unavailable"))
+
+    workframe_version = ""
+    workframe_tarball = ""
+    if target in {"workframe", "all"}:
+        workframe_version, workframe_tarball = _prepare_workframe_update(channel)
+
+    if channel == "supervisor":
+        body: dict[str, Any] = {"target": target}
+        if workframe_version:
+            body["workframe_version"] = workframe_version
+        if workframe_tarball:
+            body["workframe_tarball"] = workframe_tarball
+        return _supervisor_stack_apply(body)
+
+    if not Path(DOCKER_SOCK).exists():
+        raise ValueError("docker_unavailable")
+
+    env = os.environ.copy()
+    env.setdefault("WORKFRAME_COMPOSE_DIR", str(_compose_dir()))
+    env.setdefault("WORKFRAME_PROJECT_ROOT", str(_project_root()))
+    if workframe_version:
+        env["WORKFRAME_UPDATE_VERSION"] = workframe_version
+    if workframe_tarball:
+        env["WORKFRAME_UPDATE_TARBALL"] = workframe_tarball
+    return _run_apply_scripts(target, env)
+
+
 def restart_gateway() -> dict[str, Any]:
     if not _admin_stack_updates_enabled():
         raise ValueError("admin_updates_disabled")
-    _, apply_ready, apply_reason = _update_apply_channel()
+    channel, apply_ready, apply_reason = _update_apply_channel()
     if not apply_ready:
-        if not Path(DOCKER_SOCK).exists():
-            raise ValueError("docker_unavailable")
         raise ValueError(str(apply_reason or "docker_apply_unavailable"))
+    if channel == "supervisor":
+        return _supervisor_stack_apply({"target": "gateway-restart"}, timeout=300.0)
     if not Path(DOCKER_SOCK).exists():
         raise ValueError("docker_unavailable")
     script = _script_path("restart-gateway-hermes.sh")

package/workframe-supervisor/Dockerfile

@@ -5,7 +5,7 @@ FROM python:3-alpine
 RUN apk add --no-cache docker-cli docker-cli-compose bash nodejs npm
 
 WORKDIR /app
-COPY server.py profile_secret_policy.py .
+COPY server.py profile_secret_policy.py ./
 
 EXPOSE 8090
 CMD ["python3", "server.py"]

package/workframe-supervisor/server.py

@@ -60,7 +60,7 @@ def _exec_targets_runtime_profile_secrets(cmd: list[str], acting_profile: str =
     return exec_blocked_for_profile(cmd, acting_profile)
 
 
-def _stack_apply(target: str, *, workframe_version: str = "") -> dict[str, Any]:
+def _stack_apply(target: str, *, workframe_version: str = "", workframe_tarball: str = "") -> dict[str, Any]:
     target = str(target or "all").strip().lower()
     if target == "gateway-restart":
         script = SCRIPTS_DIR / "restart-gateway-hermes.sh"
@@ -92,7 +92,13 @@ def _stack_apply(target: str, *, workframe_version: str = "") -> dict[str, Any]:
         scripts.append(p)
     env = os.environ.copy()
     version = str(workframe_version or "").strip()
-    if version and target in {"workframe", "all"}:
+    tarball = str(workframe_tarball or "").strip()
+    env["WORKFRAME_UPDATE_FROM_SUPERVISOR"] = "1"
+    if tarball and target in {"workframe", "all"}:
+        env["WORKFRAME_UPDATE_TARBALL"] = tarball
+        if version:
+            env["WORKFRAME_UPDATE_VERSION"] = version
+    elif version and target in {"workframe", "all"}:
         env["WORKFRAME_UPDATE_ALLOW_NPM"] = "1"
         env["WORKFRAME_UPDATE_VERSION"] = version
     logs: list[str] = []
@@ -780,8 +786,16 @@ class Handler(BaseHTTPRequestHandler):
             if path == "/v1/stack.apply":
                 target = str(body.get("target") or "all").strip().lower()
                 workframe_version = str(body.get("workframe_version") or "").strip()
+                workframe_tarball = str(body.get("workframe_tarball") or "").strip()
                 try:
-                    return self._json(200, _stack_apply(target, workframe_version=workframe_version))
+                    return self._json(
+                        200,
+                        _stack_apply(
+                            target,
+                            workframe_version=workframe_version,
+                            workframe_tarball=workframe_tarball,
+                        ),
+                    )
                 except ValueError as exc:
                     return self._json(400, {"ok": False, "error": str(exc)})
                 except Exception as exc:  # noqa: BLE001