@qpfai/pf-gate-cli 1.0.26 → 2.0.0-darwin-x64

package/README.md

@@ -1,36 +1,9 @@
-# @qpfai/pf-gate-cli
+# @qpfai/pf-gate-cli (darwin-x64)
 
-Global CLI launcher for PF Gate with first-run runtime bootstrap.
+Platform runtime payload for PF Gate CLI.
 
-## Install
+The bundled launcher at `vendor/<target-triple>/pf-gate/` runs PF Gate through Python:
 
-```bash
-npm i -g @qpfai/pf-gate-cli
-```
-
-## Use
-
-Open the PF Gate terminal UX:
-
-```bash
-pf gate
-```
-
-Run direct CLI commands:
-
-```bash
-pf --version
-pf gate --selftest
-```
-
-On first run, the launcher creates `~/.pf-gate/runtime/.venv` and installs PF Gate.
-
-## Maintainer release flow
-
-From repo root:
-
-```bash
-cd npm/pf-gate-cli
-npm run prepare:python
-npm publish --access public
-```
+- Uses `PF_GATE_PYTHON` when set, else probes `python3` then `python` (Windows also tries `py -3`).
+- Uses `PF_GATE_PIP_SPEC` when set, else installs `persons-field==1.0.0` if missing.
+- Starts `persons_field.terminal.launcher` with forwarded arguments.

package/package.json

@@ -1,24 +1,19 @@
 {
   "name": "@qpfai/pf-gate-cli",
-  "version": "1.0.26",
-  "description": "PF Gate terminal launcher with first-run runtime bootstrap.",
+  "version": "2.0.0-darwin-x64",
+  "description": "PF Gate runtime payload for darwin x64.",
   "license": "Apache-2.0",
   "type": "module",
-  "bin": {
-    "pf": "bin/pf.mjs",
-    "pf-gate": "bin/pf.mjs"
-  },
+  "os": [
+    "darwin"
+  ],
+  "cpu": [
+    "x64"
+  ],
   "files": [
-    "bin",
-    "lib",
-    "artifacts",
+    "vendor",
     "README.md"
   ],
-  "scripts": {
-    "prepare:python": "node scripts/prepare-python-wheel.mjs",
-    "prepack": "npm run prepare:python",
-    "test": "node --test tests/*.test.mjs"
-  },
   "engines": {
     "node": ">=18"
   },

package/vendor/x86_64-apple-darwin/pf-gate/pf-gate

@@ -0,0 +1,31 @@
+#!/usr/bin/env sh
+set -eu
+
+PYTHON_BIN="${PF_GATE_PYTHON:-}"
+if [ -z "$PYTHON_BIN" ]; then
+  if command -v python3 >/dev/null 2>&1; then
+    PYTHON_BIN="python3"
+  elif command -v python >/dev/null 2>&1; then
+    PYTHON_BIN="python"
+  else
+    echo "PF Gate runtime error: Python 3.13+ not found. Install Python or set PF_GATE_PYTHON." >&2
+    exit 1
+  fi
+fi
+
+PIP_SPEC="${PF_GATE_PIP_SPEC:-persons-field==1.0.0}"
+
+if ! "$PYTHON_BIN" -c "import persons_field" >/dev/null 2>&1; then
+  echo "PF Gate runtime: persons_field is missing; installing ${PIP_SPEC}..." >&2
+  if ! "$PYTHON_BIN" -m pip --version >/dev/null 2>&1; then
+    "$PYTHON_BIN" -m ensurepip --upgrade >/dev/null 2>&1 || true
+  fi
+  if ! "$PYTHON_BIN" -m pip install --upgrade --disable-pip-version-check "$PIP_SPEC"; then
+    if ! "$PYTHON_BIN" -m pip install --user --upgrade --disable-pip-version-check "$PIP_SPEC"; then
+      echo "PF Gate runtime error: failed to install ${PIP_SPEC}. Set PF_GATE_PYTHON and PF_GATE_PIP_SPEC, then retry." >&2
+      exit 1
+    fi
+  fi
+fi
+
+exec "$PYTHON_BIN" -m persons_field.terminal.launcher "$@"

package/artifacts/python-wheel.json

@@ -1,8 +0,0 @@
-{
-  "schemaVersion": 1,
-  "generatedAt": "2026-02-17T03:13:25.424Z",
-  "pythonPackage": "persons-field",
-  "pythonPackageVersion": "1.0.0",
-  "wheel": "persons_field-1.0.0-py3-none-any.whl",
-  "sha256": "0270434fae7427fdc6fc46be62a5cabe660b212bbb4b5c1fb894141a97c88303"
-}

package/bin/pf.mjs

@@ -1,10 +0,0 @@
-#!/usr/bin/env node
-
-import { runCli } from "../lib/main.mjs";
-
-runCli(process.argv.slice(2)).catch((error) => {
-  const message = error instanceof Error ? error.message : String(error);
-  console.error(`PF Gate launcher error: ${message}`);
-  process.exit(1);
-});
-

package/lib/main.mjs

@@ -1,786 +0,0 @@
-import { spawn, spawnSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import fs from "node:fs";
-import https from "node:https";
-import os from "node:os";
-import path from "node:path";
-import process from "node:process";
-import readline from "node:readline/promises";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const PACKAGE_ROOT = path.resolve(__dirname, "..");
-const ARTIFACT_MANIFEST_PATH = path.join(PACKAGE_ROOT, "artifacts", "python-wheel.json");
-const INSTALL_STATE_NAME = "install-state.json";
-const PYTHON_CANDIDATES = ["python3.13", "python3", "python"];
-const DEFAULT_NPM_REGISTRY = "https://registry.npmjs.org";
-const UPDATE_CHECK_TIMEOUT_MS = 6000;
-const UPDATE_INSTALL_MAX_RETRIES = 10;
-const UPDATE_INSTALL_RETRY_MS = 3000;
-
-function isWindows() {
-  return process.platform === "win32";
-}
-
-function runtimePythonPath(runtimeRoot) {
-  if (isWindows()) {
-    return path.join(runtimeRoot, ".venv", "Scripts", "python.exe");
-  }
-  return path.join(runtimeRoot, ".venv", "bin", "python");
-}
-
-function runtimeVenvPath(runtimeRoot) {
-  return path.join(runtimeRoot, ".venv");
-}
-
-function runtimeBinDir(runtimeRoot) {
-  if (isWindows()) {
-    return path.join(runtimeRoot, ".venv", "Scripts");
-  }
-  return path.join(runtimeRoot, ".venv", "bin");
-}
-
-function removeStaleRuntimeEntryPoints(runtimeRoot) {
-  const binDir = runtimeBinDir(runtimeRoot);
-  const candidates = isWindows()
-    ? ["pf.exe", "pf.cmd", "PF.exe", "PF.cmd", "pf-gate.exe", "pf-gate.cmd"]
-    : ["pf", "PF", "pf-gate"];
-  for (const name of candidates) {
-    try {
-      fs.rmSync(path.join(binDir, name), { force: true });
-    } catch (_error) {
-      // best-effort cleanup only.
-    }
-  }
-}
-
-function runtimePipArgs(runtimeRoot) {
-  return ["-m", "pip"];
-}
-
-function runtimeLauncherArgs(args) {
-  return ["-m", "persons_field.terminal.launcher", ...args];
-}
-
-export function shouldOpenUx(args) {
-  if (args.length === 0) {
-    return true;
-  }
-  if (args.length !== 1) {
-    return false;
-  }
-  const first = String(args[0] || "").trim().toLowerCase();
-  return first === "gate" || first === "ux" || first === "shell";
-}
-
-function loadPackageMetadata() {
-  const raw = fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf-8");
-  const payload = JSON.parse(raw);
-  return {
-    name: String(payload.name || "@pfgate/cli"),
-    version: String(payload.version || "0.0.0"),
-  };
-}
-
-function ensureDir(dirPath) {
-  fs.mkdirSync(dirPath, { recursive: true });
-}
-
-function runChecked(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    stdio: "inherit",
-    ...options,
-  });
-  if (result.error) {
-    throw result.error;
-  }
-  if ((result.status ?? 1) !== 0) {
-    throw new Error(`Command failed (${result.status}): ${command} ${args.join(" ")}`);
-  }
-}
-
-function runCheckedCapture(command, args, options = {}) {
-  const result = spawnSync(command, args, {
-    stdio: "pipe",
-    encoding: "utf-8",
-    ...options,
-  });
-  if (result.stdout) {
-    process.stdout.write(String(result.stdout));
-  }
-  if (result.stderr) {
-    process.stderr.write(String(result.stderr));
-  }
-  if (result.error) {
-    throw result.error;
-  }
-  if ((result.status ?? 1) !== 0) {
-    const combined = `${String(result.stdout || "")}\n${String(result.stderr || "")}`;
-    const error = new Error(
-      `Command failed (${result.status}): ${command} ${args.join(" ")}`
-    );
-    error.commandOutput = combined;
-    throw error;
-  }
-}
-
-function runCapture(command, args) {
-  const result = spawnSync(command, args, {
-    stdio: "pipe",
-    encoding: "utf-8",
-  });
-  if (result.error) {
-    return { ok: false, output: "" };
-  }
-  return {
-    ok: (result.status ?? 1) === 0,
-    output: String(result.stdout || "").trim(),
-  };
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function startSphereSpinner(message) {
-  if (process.stdout.isTTY) {
-    process.stdout.write(`${message}\n`);
-  }
-  return (doneMessage = `✓ ${message}`) => {
-    if (process.stdout.isTTY && doneMessage) {
-      process.stdout.write(`${doneMessage}\n`);
-    }
-  };
-}
-
-function spawnCapture(command, args, options = {}) {
-  return new Promise((resolve) => {
-    const child = spawn(command, args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      ...options,
-    });
-    let stdout = "";
-    let stderr = "";
-    if (child.stdout) {
-      child.stdout.on("data", (chunk) => {
-        stdout += String(chunk);
-      });
-    }
-    if (child.stderr) {
-      child.stderr.on("data", (chunk) => {
-        stderr += String(chunk);
-      });
-    }
-    child.on("error", (error) => {
-      resolve({ status: 1, error, stdout, stderr });
-    });
-    child.on("close", (code) => {
-      resolve({ status: code ?? 1, error: null, stdout, stderr });
-    });
-  });
-}
-
-async function runCommandWithSphereSpinner(command, args, message, options = {}) {
-  const { failureMessage, successMessage, ...spawnOptions } = options;
-  const stop = startSphereSpinner(message);
-  const result = await spawnCapture(command, args, spawnOptions);
-  if (result.error || (result.status ?? 1) !== 0) {
-    stop(failureMessage || `… ${message}`);
-    const error =
-      result.error ||
-      new Error(`Command failed (${result.status}): ${command} ${args.join(" ")}`);
-    error.commandOutput = `${String(result.stdout || "")}\n${String(result.stderr || "")}`;
-    throw error;
-  }
-  stop(successMessage || `✓ ${message}`);
-  return result;
-}
-
-function parseVersionTriplet(version) {
-  const text = String(version || "").trim();
-  const [core] = text.split("-");
-  const pieces = core.split(".");
-  const numbers = [];
-  for (let index = 0; index < 3; index += 1) {
-    const value = Number.parseInt(pieces[index] || "0", 10);
-    numbers.push(Number.isFinite(value) ? value : 0);
-  }
-  return numbers;
-}
-
-export function compareVersions(left, right) {
-  const lhs = parseVersionTriplet(left);
-  const rhs = parseVersionTriplet(right);
-  for (let index = 0; index < 3; index += 1) {
-    if (lhs[index] > rhs[index]) {
-      return 1;
-    }
-    if (lhs[index] < rhs[index]) {
-      return -1;
-    }
-  }
-  return 0;
-}
-
-function configuredNpmRegistry() {
-  const fromEnv = String(process.env.PF_GATE_NPM_REGISTRY || "").trim();
-  if (fromEnv) {
-    return fromEnv.replace(/\/+$/, "");
-  }
-  return DEFAULT_NPM_REGISTRY;
-}
-
-function debugUpdateEnabled() {
-  return String(process.env.PF_GATE_DEBUG_UPDATE_CHECK || "").trim() === "1";
-}
-
-function debugUpdate(message) {
-  if (debugUpdateEnabled()) {
-    console.log(`[PF Gate update-check] ${message}`);
-  }
-}
-
-function fetchJson(url, timeoutMs = UPDATE_CHECK_TIMEOUT_MS) {
-  return new Promise((resolve) => {
-    const request = https.get(
-      url,
-      {
-        headers: {
-          "User-Agent": "pf-gate-cli",
-          Accept: "application/json",
-        },
-      },
-      (response) => {
-        let body = "";
-        response.on("data", (chunk) => {
-          body += String(chunk);
-        });
-        response.on("end", () => {
-          if ((response.statusCode || 500) >= 400) {
-            resolve(null);
-            return;
-          }
-          try {
-            resolve(JSON.parse(body));
-          } catch (_error) {
-            resolve(null);
-          }
-        });
-      }
-    );
-    request.setTimeout(timeoutMs, () => {
-      request.destroy(new Error("timeout"));
-      resolve(null);
-    });
-    request.on("error", () => resolve(null));
-  });
-}
-
-export function latestFromDistTags(payload) {
-  if (!payload || typeof payload !== "object") {
-    return null;
-  }
-  const latest = String(payload.latest || "").trim();
-  if (!latest) {
-    return null;
-  }
-  return latest;
-}
-
-export function parseNpmViewVersion(raw) {
-  const text = String(raw || "").trim();
-  if (!text) {
-    return null;
-  }
-  try {
-    const parsed = JSON.parse(text);
-    if (typeof parsed === "string" && parsed.trim()) {
-      return parsed.trim();
-    }
-    if (Array.isArray(parsed) && parsed.length > 0) {
-      const first = String(parsed[0] || "").trim();
-      return first || null;
-    }
-  } catch (_error) {
-    // npm can return plain text; fall through.
-  }
-  const firstLine = text.split(/\r?\n/, 1)[0] || "";
-  const candidate = firstLine.replace(/^["']|["']$/g, "").trim();
-  return candidate || null;
-}
-
-function fetchLatestVersionFromNpmCli(packageName, registry) {
-  const probe = runCapture("npm", [
-    "view",
-    `${packageName}@latest`,
-    "version",
-    "--json",
-    "--registry",
-    registry,
-  ]);
-  if (!probe.ok) {
-    return null;
-  }
-  return parseNpmViewVersion(probe.output);
-}
-
-async function fetchLatestVersion(packageName, registry) {
-  const encoded = encodeURIComponent(packageName);
-  const url = `${registry}/-/package/${encoded}/dist-tags`;
-  debugUpdate(`fetch ${url}`);
-  const payload = await fetchJson(url);
-  const latest = latestFromDistTags(payload);
-  if (latest) {
-    debugUpdate(`dist-tags latest=${latest}`);
-    return latest;
-  }
-  debugUpdate("dist-tags unavailable; falling back to npm view");
-  const fallback = fetchLatestVersionFromNpmCli(packageName, registry);
-  if (fallback) {
-    debugUpdate(`npm view latest=${fallback}`);
-  }
-  return fallback;
-}
-
-function canPrompt() {
-  return Boolean(process.stdin.isTTY && process.stdout.isTTY);
-}
-
-async function promptYesNo(question, defaultYes = true, promptSuffix = null) {
-  if (!canPrompt()) {
-    return false;
-  }
-  let prompt = defaultYes ? `${question} [Y/n] ` : `${question} [y/N] `;
-  if (typeof promptSuffix === "string" && promptSuffix.trim()) {
-    prompt = `${question} ${promptSuffix.trim()} `;
-  }
-  const rl = readline.createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  try {
-    const answer = (await rl.question(prompt)).trim().toLowerCase();
-    if (!answer) {
-      return defaultYes;
-    }
-    return answer === "y" || answer === "yes";
-  } finally {
-    rl.close();
-  }
-}
-
-async function promptCliUpdate(metadata, latestVersion) {
-  if (!canPrompt()) {
-    return false;
-  }
-  console.clear();
-  console.log(
-    `Update available: ${metadata.name} ${metadata.version} -> ${latestVersion}`
-  );
-  return promptYesNo("Install update now?", false, "[Y/N]");
-}
-
-function npmGlobalBinDir() {
-  const prefix = runCapture("npm", ["prefix", "-g"]);
-  if (!prefix.ok) {
-    return null;
-  }
-  const root = String(prefix.output || "").trim();
-  if (!root) {
-    return null;
-  }
-  return path.join(root, "bin");
-}
-
-function maybeHealBinCollision(output) {
-  const text = String(output || "");
-  if (!text.includes("EEXIST")) {
-    return false;
-  }
-  const binDir = npmGlobalBinDir();
-  if (!binDir) {
-    return false;
-  }
-  let removed = false;
-  for (const name of ["PF", "pf", "pf-gate"]) {
-    const candidate = path.join(binDir, name);
-    try {
-      if (fs.existsSync(candidate)) {
-        fs.rmSync(candidate, { force: true });
-        removed = true;
-      }
-    } catch (_error) {
-      // keep going and try remaining bins
-    }
-  }
-  if (removed) {
-    console.log("PF Gate updater: removed stale global CLI bin links; retrying install...");
-  }
-  return removed;
-}
-
-function isEtargetPublishRace(output) {
-  const text = String(output || "").toLowerCase();
-  return text.includes("code etarget") || text.includes("notarget no matching version");
-}
-
-async function npmVersionExists(packageName, version, registry) {
-  const result = await spawnCapture(
-    "npm",
-    ["view", `${packageName}@${version}`, "version", "--json", "--registry", registry],
-    { encoding: "utf-8" }
-  );
-  if (result.error || (result.status ?? 1) !== 0) {
-    return false;
-  }
-  const parsed = parseNpmViewVersion(String(result.stdout || "").trim());
-  return parsed === String(version || "").trim();
-}
-
-async function installLatestCliPackage(packageName, targetVersion, registry) {
-  const args = ["i", "-g", `${packageName}@${targetVersion}`, "--registry", registry];
-  const runOnce = async () => {
-    const stop = startSphereSpinner("Installing PF Gate update...");
-    const result = await spawnCapture("npm", args, { encoding: "utf-8" });
-    if (!result.error && (result.status ?? 1) === 0) {
-      stop("✓ Installing PF Gate update...");
-    } else {
-      stop("✗ Installing PF Gate update...");
-    }
-    return result;
-  };
-
-  let attempts = 0;
-  let healedCollision = false;
-  let result = null;
-
-  while (attempts < UPDATE_INSTALL_MAX_RETRIES) {
-    attempts += 1;
-    const versionReady = await npmVersionExists(packageName, targetVersion, registry);
-    if (!versionReady) {
-      if (attempts < UPDATE_INSTALL_MAX_RETRIES) {
-        const delayMs = UPDATE_INSTALL_RETRY_MS * attempts;
-        const seconds = Math.ceil(delayMs / 1000);
-        const stopWait = startSphereSpinner(
-          `Waiting for ${packageName}@${targetVersion} to be available (${seconds}s)...`
-        );
-        await sleep(delayMs);
-        stopWait("✓ Retrying update install...");
-        continue;
-      }
-      break;
-    }
-
-    result = await runOnce();
-    if (!result.error && (result.status ?? 1) === 0) {
-      return true;
-    }
-
-    const combined = `${String(result.stdout || "")}\n${String(result.stderr || "")}`;
-    if (!healedCollision && maybeHealBinCollision(combined)) {
-      healedCollision = true;
-      continue;
-    }
-
-    if (attempts < UPDATE_INSTALL_MAX_RETRIES && isEtargetPublishRace(combined)) {
-      const delayMs = UPDATE_INSTALL_RETRY_MS * attempts;
-      const seconds = Math.ceil(delayMs / 1000);
-      const stopWait = startSphereSpinner(
-        `Waiting for npm registry propagation (${seconds}s)...`
-      );
-      await sleep(delayMs);
-      stopWait("✓ Retrying update install...");
-      continue;
-    }
-    break;
-  }
-
-  if (result && result.stdout) {
-    process.stdout.write(String(result.stdout));
-  }
-  if (result && result.stderr) {
-    process.stderr.write(String(result.stderr));
-  }
-  return false;
-}
-
-async function maybeOfferCliUpdate(metadata) {
-  if (String(process.env.PF_GATE_DISABLE_UPDATE_CHECK || "").trim() === "1") {
-    debugUpdate("disabled via PF_GATE_DISABLE_UPDATE_CHECK=1");
-    return false;
-  }
-  const registry = configuredNpmRegistry();
-  debugUpdate(`current=${metadata.version}, package=${metadata.name}, registry=${registry}`);
-  const stopCheck = startSphereSpinner("Checking for updates...");
-  const latestVersion = await fetchLatestVersion(metadata.name, registry);
-  stopCheck("✓ Checking for updates...");
-  if (!latestVersion) {
-    debugUpdate("unable to resolve latest version");
-    return false;
-  }
-  if (compareVersions(latestVersion, metadata.version) <= 0) {
-    debugUpdate(`up-to-date (latest=${latestVersion})`);
-    return false;
-  }
-  const wantsUpdate = await promptCliUpdate(metadata, latestVersion);
-  if (!wantsUpdate) {
-    console.log(`Continue with ${metadata.version}.`);
-    return false;
-  }
-  console.log(`Updating ${metadata.name}...`);
-  const installed = await installLatestCliPackage(metadata.name, latestVersion, registry);
-  if (!installed) {
-    console.log("Update failed. Continuing with current version.");
-    return false;
-  }
-  console.log("Update installed. Restart PF Gate to use the new version.");
-  return true;
-}
-
-function resolvePython() {
-  const envPython = (process.env.PF_GATE_PYTHON || "").trim();
-  const candidates = envPython ? [envPython, ...PYTHON_CANDIDATES] : PYTHON_CANDIDATES;
-  for (const candidate of candidates) {
-    const probe = runCapture(candidate, ["--version"]);
-    if (probe.ok) {
-      return candidate;
-    }
-  }
-  throw new Error(
-    "No Python runtime found. Install Python 3.13+ or set PF_GATE_PYTHON to an explicit executable."
-  );
-}
-
-function sha256File(filePath) {
-  const data = fs.readFileSync(filePath);
-  return createHash("sha256").update(data).digest("hex");
-}
-
-function parseManifest() {
-  if (!fs.existsSync(ARTIFACT_MANIFEST_PATH)) {
-    return null;
-  }
-  const raw = fs.readFileSync(ARTIFACT_MANIFEST_PATH, "utf-8");
-  const payload = JSON.parse(raw);
-  const wheelName = String(payload.wheel || "").trim();
-  if (!wheelName) {
-    return null;
-  }
-  const wheelPath = path.join(PACKAGE_ROOT, "artifacts", wheelName);
-  if (!fs.existsSync(wheelPath)) {
-    return null;
-  }
-  const expectedSha = String(payload.sha256 || "").trim().toLowerCase();
-  if (expectedSha) {
-    const actualSha = sha256File(wheelPath);
-    if (actualSha !== expectedSha) {
-      throw new Error(
-        `Wheel checksum mismatch for ${wheelName}. Expected ${expectedSha}, got ${actualSha}.`
-      );
-    }
-  }
-  return {
-    kind: "wheel",
-    wheelPath,
-    wheelName,
-    sha256: expectedSha || null,
-    packageVersion: String(payload.pythonPackageVersion || "").trim() || null,
-  };
-}
-
-function resolveInstallSource(cliVersion) {
-  const manifestSource = parseManifest();
-  if (manifestSource) {
-    return manifestSource;
-  }
-  const pipSpec = (process.env.PF_GATE_PIP_SPEC || `persons-field==${cliVersion}`).trim();
-  return {
-    kind: "pip",
-    pipSpec,
-  };
-}
-
-function installStatePath(runtimeRoot) {
-  return path.join(runtimeRoot, INSTALL_STATE_NAME);
-}
-
-function loadInstallState(runtimeRoot) {
-  const statePath = installStatePath(runtimeRoot);
-  if (!fs.existsSync(statePath)) {
-    return null;
-  }
-  try {
-    return JSON.parse(fs.readFileSync(statePath, "utf-8"));
-  } catch (_error) {
-    return null;
-  }
-}
-
-function writeInstallState(runtimeRoot, payload) {
-  fs.writeFileSync(
-    installStatePath(runtimeRoot),
-    JSON.stringify(payload, null, 2) + "\n",
-    "utf-8"
-  );
-}
-
-function desiredStateFingerprint(source, cliVersion) {
-  if (source.kind === "wheel") {
-    return `wheel:${source.wheelName}:${source.sha256 || "nosha"}:${cliVersion}`;
-  }
-  return `pip:${source.pipSpec}:${cliVersion}`;
-}
-
-function isRuntimeHealthy(runtimeRoot, source, cliVersion) {
-  const pythonPath = runtimePythonPath(runtimeRoot);
-  if (!fs.existsSync(pythonPath)) {
-    return false;
-  }
-  const state = loadInstallState(runtimeRoot);
-  const fingerprint = desiredStateFingerprint(source, cliVersion);
-  if (!state || String(state.fingerprint || "") !== fingerprint) {
-    return false;
-  }
-  const probe = runCapture(pythonPath, ["-c", "import persons_field"]);
-  return probe.ok;
-}
-
-async function ensureVirtualenv(runtimeRoot, bootstrapPython) {
-  const pythonPath = runtimePythonPath(runtimeRoot);
-  if (fs.existsSync(pythonPath)) {
-    return;
-  }
-  await runCommandWithSphereSpinner(
-    bootstrapPython,
-    ["-m", "venv", path.join(runtimeRoot, ".venv")],
-    "Creating runtime environment..."
-  );
-}
-
-async function recreateVirtualenv(runtimeRoot, bootstrapPython) {
-  const venvPath = runtimeVenvPath(runtimeRoot);
-  if (fs.existsSync(venvPath)) {
-    fs.rmSync(venvPath, { recursive: true, force: true });
-  }
-  await runCommandWithSphereSpinner(
-    bootstrapPython,
-    ["-m", "venv", venvPath],
-    "Recreating runtime environment..."
-  );
-}
-
-async function installRuntime(runtimeRoot, source, cliVersion) {
-  const pythonPath = runtimePythonPath(runtimeRoot);
-  const skipPipUpgrade = String(process.env.PF_GATE_SKIP_PIP_UPGRADE || "").trim() === "1";
-  removeStaleRuntimeEntryPoints(runtimeRoot);
-  if (!skipPipUpgrade) {
-    await runCommandWithSphereSpinner(
-      pythonPath,
-      [...runtimePipArgs(runtimeRoot), "install", "--upgrade", "pip"],
-      "Preparing runtime dependencies..."
-    );
-  }
-  if (source.kind === "wheel") {
-    await runCommandWithSphereSpinner(
-      pythonPath,
-      [
-        ...runtimePipArgs(runtimeRoot),
-        "install",
-        "--upgrade",
-        "--force-reinstall",
-        "--ignore-installed",
-        source.wheelPath,
-      ],
-      "Installing PF Gate runtime..."
-    );
-  } else {
-    await runCommandWithSphereSpinner(
-      pythonPath,
-      [
-        ...runtimePipArgs(runtimeRoot),
-        "install",
-        "--upgrade",
-        "--force-reinstall",
-        "--ignore-installed",
-        source.pipSpec,
-      ],
-      "Installing PF Gate runtime..."
-    );
-  }
-  await runCommandWithSphereSpinner(
-    pythonPath,
-    [
-      ...runtimePipArgs(runtimeRoot),
-      "install",
-      "--upgrade",
-      "--force-reinstall",
-      "--ignore-installed",
-      "prompt_toolkit>=3.0.39",
-    ],
-    "Installing terminal UX dependencies..."
-  );
-  const fingerprint = desiredStateFingerprint(source, cliVersion);
-  writeInstallState(runtimeRoot, {
-    installedAt: new Date().toISOString(),
-    cliVersion,
-    fingerprint,
-  });
-  console.log("✓ PF Gate runtime ready.");
-}
-
-function resolveRuntimeRoot() {
-  const appHome = (process.env.PF_GATE_HOME || "").trim() || path.join(os.homedir(), ".pf-gate");
-  return path.join(appHome, "runtime");
-}
-
-function dryRunEnabled() {
-  return String(process.env.PF_GATE_BOOTSTRAP_DRY_RUN || "").trim() === "1";
-}
-
-async function ensureRuntimeInstalled(cliVersion) {
-  const runtimeRoot = resolveRuntimeRoot();
-  ensureDir(runtimeRoot);
-  const source = resolveInstallSource(cliVersion);
-  if (!isRuntimeHealthy(runtimeRoot, source, cliVersion)) {
-    const bootstrapPython = resolvePython();
-    await ensureVirtualenv(runtimeRoot, bootstrapPython);
-    try {
-      await installRuntime(runtimeRoot, source, cliVersion);
-    } catch (error) {
-      console.log("PF Gate bootstrap: runtime install failed. Retrying with a clean environment...");
-      await recreateVirtualenv(runtimeRoot, bootstrapPython);
-      await installRuntime(runtimeRoot, source, cliVersion);
-    }
-  }
-  return runtimeRoot;
-}
-
-export async function runCli(args) {
-  const metadata = loadPackageMetadata();
-  if (dryRunEnabled()) {
-    const uiMode = shouldOpenUx(args) ? "ux" : "passthrough";
-    console.log(`PF Gate launcher dry-run (${uiMode})`);
-    console.log(`args: ${JSON.stringify(args)}`);
-    return;
-  }
-  const updated = await maybeOfferCliUpdate(metadata);
-  if (updated) {
-    process.exit(0);
-  }
-  const runtimeRoot = await ensureRuntimeInstalled(metadata.version);
-  const pythonPath = runtimePythonPath(runtimeRoot);
-  const resolvedArgs = args.length === 0 ? ["Gate"] : args;
-  const childEnv = {
-    ...process.env,
-    PF_GATE_CLI_VERSION: metadata.version,
-  };
-  const child = spawnSync(pythonPath, runtimeLauncherArgs(resolvedArgs), {
-    stdio: "inherit",
-    env: childEnv,
-  });
-  if (child.error) {
-    throw child.error;
-  }
-  process.exit(child.status ?? 1);
-}