@qpfai/pf-gate-cli 1.0.0

package/README.md

@@ -0,0 +1,36 @@
+# @qpfai/pf-gate-cli
+
+Global CLI launcher for PF Gate with first-run runtime bootstrap.
+
+## Install
+
+```bash
+npm i -g @qpfai/pf-gate-cli
+```
+
+## Use
+
+Open the Codex-style 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
+```

package/artifacts/python-wheel.json

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-02-16T18:51:30.931Z",
+  "pythonPackage": "persons-field",
+  "pythonPackageVersion": "1.0.0",
+  "wheel": "persons_field-1.0.0-py3-none-any.whl",
+  "sha256": "f16ad52f913ea806e8d40a4f49c3a92f50f2708ecce67e7ceaf37b492ed0d793"
+}

package/bin/pf.mjs

@@ -0,0 +1,10 @@
+#!/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

@@ -0,0 +1,274 @@
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+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"];
+
+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 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 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 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;
+}
+
+function ensureVirtualenv(runtimeRoot, bootstrapPython) {
+  const pythonPath = runtimePythonPath(runtimeRoot);
+  if (fs.existsSync(pythonPath)) {
+    return;
+  }
+  console.log("PF Gate bootstrap: creating runtime virtual environment...");
+  runChecked(bootstrapPython, ["-m", "venv", path.join(runtimeRoot, ".venv")]);
+}
+
+function installRuntime(runtimeRoot, source, cliVersion) {
+  const pythonPath = runtimePythonPath(runtimeRoot);
+  const skipPipUpgrade = String(process.env.PF_GATE_SKIP_PIP_UPGRADE || "").trim() === "1";
+  if (!skipPipUpgrade) {
+    console.log("PF Gate bootstrap: updating pip...");
+    runChecked(pythonPath, [...runtimePipArgs(runtimeRoot), "install", "--upgrade", "pip"]);
+  }
+  console.log("PF Gate bootstrap: installing PF Gate runtime...");
+  if (source.kind === "wheel") {
+    runChecked(pythonPath, [
+      ...runtimePipArgs(runtimeRoot),
+      "install",
+      "--upgrade",
+      source.wheelPath,
+    ]);
+  } else {
+    runChecked(pythonPath, [
+      ...runtimePipArgs(runtimeRoot),
+      "install",
+      "--upgrade",
+      source.pipSpec,
+    ]);
+  }
+  const fingerprint = desiredStateFingerprint(source, cliVersion);
+  writeInstallState(runtimeRoot, {
+    installedAt: new Date().toISOString(),
+    cliVersion,
+    fingerprint,
+  });
+  console.log("PF Gate bootstrap: 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";
+}
+
+function ensureRuntimeInstalled(cliVersion) {
+  const runtimeRoot = resolveRuntimeRoot();
+  ensureDir(runtimeRoot);
+  const source = resolveInstallSource(cliVersion);
+  if (!isRuntimeHealthy(runtimeRoot, source, cliVersion)) {
+    const bootstrapPython = resolvePython();
+    ensureVirtualenv(runtimeRoot, bootstrapPython);
+    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 runtimeRoot = ensureRuntimeInstalled(metadata.version);
+  const pythonPath = runtimePythonPath(runtimeRoot);
+  const resolvedArgs = args.length === 0 ? ["Gate"] : args;
+  const child = spawnSync(pythonPath, runtimeLauncherArgs(resolvedArgs), {
+    stdio: "inherit",
+  });
+  if (child.error) {
+    throw child.error;
+  }
+  process.exit(child.status ?? 1);
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@qpfai/pf-gate-cli",
+  "version": "1.0.0",
+  "description": "PF Gate terminal launcher with first-run runtime bootstrap.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "PF": "bin/pf.mjs",
+    "pf-gate": "bin/pf.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "artifacts",
+    "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"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}