premanmcp 0.7.0 → 0.8.0

package/bin/desktop.js

@@ -0,0 +1,214 @@
+/**
+ * `preman install-desktop` — download and install the PreMan desktop app.
+ *
+ * Version-less asset names are used on purpose: `/releases/latest/download/
+ * PreMan-mac-arm64.dmg` keeps working after every release, where a versioned URL
+ * would 404 the day the next build ships. The live tag is read from the GitHub
+ * API only to report what was installed.
+ *
+ * Arch detection is trivial here in a way it is not on the website: `uname -m`
+ * is authoritative, so there is no need for the WebGL guessing the download page
+ * has to do.
+ */
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { cliInvocation, makeArgs } from "./shared.js";
+
+export const DESKTOP_HELP = `
+Install-desktop options:
+  --arch <arm64|x64>    Override architecture detection
+  --dest <dir>          Install directory. Defaults to /Applications
+  --keep-dmg            Leave the downloaded disk image in place
+  --print-url           Print the resolved download URL and exit
+`;
+
+const RELEASES_BASE = "https://github.com/PreMan-Inc/PreMan-Desktop/releases";
+const RELEASE_API = "https://api.github.com/repos/PreMan-Inc/PreMan-Desktop/releases/latest";
+const APP_NAME = "PreMan.app";
+const DOWNLOAD_TIMEOUT_MS = 300_000;
+
+export function dmgUrl(arch) {
+  return `${RELEASES_BASE}/latest/download/PreMan-mac-${arch}.dmg`;
+}
+
+export function detectArch() {
+  const machine = os.machine ? os.machine() : os.arch();
+  if (machine === "arm64" || machine === "aarch64") return "arm64";
+  if (machine === "x86_64" || machine === "x64") return "x64";
+  // Rosetta reports x86_64 for the Node binary itself, so ask sysctl whether the
+  // hardware is actually Apple silicon before handing over an Intel build.
+  const probe = spawnSync("sysctl", ["-n", "hw.optional.arm64"], { encoding: "utf8" });
+  if (probe.status === 0 && probe.stdout.trim() === "1") return "arm64";
+  return "x64";
+}
+
+async function fetchLatestRelease() {
+  try {
+    const resp = await fetch(RELEASE_API, {
+      headers: { Accept: "application/vnd.github+json", "User-Agent": "premanmcp-cli" },
+    });
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The sha512 and size electron-builder published for this architecture's disk
+ * image, or null if the manifest could not be read.
+ *
+ * `latest-mac.yml` is the only integrity signal available without our own signing
+ * infrastructure. It keys entries by the *versioned* filename
+ * (`PreMan-0.3.79-arm64.dmg`), while we download the version-less alias, so the
+ * version has to be read out of the manifest to find the right entry. The alias
+ * is a copy of the same artifact, which the size check confirms before the digest
+ * is trusted.
+ */
+export function parseMacManifest(text, arch) {
+  const version = text.match(/^version:\s*(\S+)/m)?.[1];
+  if (!version) return null;
+  const wanted = `PreMan-${version}-${arch}.dmg`;
+  const lines = String(text).split("\n");
+  for (let i = 0; i < lines.length; i += 1) {
+    if (!lines[i].includes(wanted)) continue;
+    let sha512 = null;
+    let size = null;
+    for (let j = i + 1; j < Math.min(lines.length, i + 5); j += 1) {
+      if (/^\s*-\s*url:/.test(lines[j])) break;
+      sha512 ??= lines[j].match(/sha512:\s*([A-Za-z0-9+/=]+)/)?.[1] ?? null;
+      size ??= lines[j].match(/size:\s*(\d+)/)?.[1] ?? null;
+    }
+    if (sha512) return { version, sha512, size: size ? Number(size) : null, asset: wanted };
+  }
+  return null;
+}
+
+async function expectedDigest(arch) {
+  try {
+    const resp = await fetch(`${RELEASES_BASE}/latest/download/latest-mac.yml`, {
+      headers: { "User-Agent": "premanmcp-cli" },
+    });
+    if (!resp.ok) return null;
+    return parseMacManifest(await resp.text(), arch);
+  } catch {
+    return null;
+  }
+}
+
+async function download(url, destination) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), DOWNLOAD_TIMEOUT_MS);
+  try {
+    const resp = await fetch(url, { signal: controller.signal, redirect: "follow" });
+    if (!resp.ok) throw new Error(`download failed: ${resp.status} ${url}`);
+    const buffer = Buffer.from(await resp.arrayBuffer());
+    writeFileSync(destination, buffer);
+    return buffer.length;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function sha512Base64(filePath) {
+  return createHash("sha512").update(readFileSync(filePath)).digest("base64");
+}
+
+function run(command, commandArgs) {
+  const result = spawnSync(command, commandArgs, { encoding: "utf8" });
+  if (result.status !== 0) {
+    throw new Error(`${command} ${commandArgs.join(" ")} failed: ${result.stderr?.trim() || result.status}`);
+  }
+  return result.stdout || "";
+}
+
+function mountedVolume(hdiutilOutput) {
+  const match = hdiutilOutput.match(/(\/Volumes\/[^\n\t]+)/);
+  if (!match) throw new Error("could not find the mounted volume in hdiutil output");
+  return match[1].trim();
+}
+
+export async function installDesktopCommand(commandArgs = []) {
+  const args = makeArgs(commandArgs);
+
+  if (process.platform !== "darwin") {
+    process.stdout.write(
+      `The PreMan desktop app is macOS-only right now.\n` +
+        `Downloads for other platforms: ${RELEASES_BASE}/latest\n`
+    );
+    return { state: "unsupported", platform: process.platform };
+  }
+
+  const arch = args.value("--arch", "") || detectArch();
+  if (!["arm64", "x64"].includes(arch)) {
+    throw new Error(`unsupported --arch ${arch}; expected arm64 or x64`);
+  }
+  const url = dmgUrl(arch);
+
+  if (args.has("--print-url")) {
+    process.stdout.write(`${url}\n`);
+    return { state: "printed", url, arch };
+  }
+
+  const release = await fetchLatestRelease();
+  const version = String(release?.tag_name || "").replace(/^v/i, "") || "latest";
+  const destination = args.value("--dest", "/Applications");
+
+  process.stdout.write(`Downloading PreMan ${version} (${arch})…\n`);
+  const workDir = mkdtempSync(path.join(os.tmpdir(), "preman-desktop-"));
+  const dmgPath = path.join(workDir, `PreMan-mac-${arch}.dmg`);
+  let mounted = null;
+
+  try {
+    const bytes = await download(url, dmgPath);
+    process.stdout.write(`  ${(bytes / 1024 / 1024).toFixed(1)} MB\n`);
+
+    const expected = await expectedDigest(arch);
+    if (expected) {
+      if (expected.size && expected.size !== bytes) {
+        throw new Error(
+          `size mismatch: downloaded ${bytes} bytes but the release manifest ` +
+            `records ${expected.size} for ${expected.asset}. Nothing was installed.`
+        );
+      }
+      if (sha512Base64(dmgPath) !== expected.sha512) {
+        throw new Error(
+          "digest mismatch: the downloaded disk image does not match the checksum " +
+            "published with the release. Nothing was installed."
+        );
+      }
+      process.stdout.write(`  checksum verified against ${expected.asset}\n`);
+    } else {
+      process.stdout.write("  checksum unavailable for this release; skipping verification\n");
+    }
+
+    const attach = run("hdiutil", ["attach", dmgPath, "-nobrowse", "-quiet", "-readonly"]);
+    mounted = mountedVolume(attach || run("hdiutil", ["info"]));
+
+    const source = path.join(mounted, APP_NAME);
+    if (!existsSync(source)) {
+      throw new Error(`${APP_NAME} not found inside the disk image at ${mounted}`);
+    }
+    const target = path.join(destination, APP_NAME);
+    if (existsSync(target)) rmSync(target, { recursive: true, force: true });
+    run("cp", ["-R", source, target]);
+    chmodSync(target, 0o755);
+
+    process.stdout.write(
+      `\nInstalled ${target}\n\nNext: open PreMan and it will pair with this account.\n` +
+        `Then run \`${cliInvocation()} status\` to see endpoint health.\n`
+    );
+    return { state: "installed", version, arch, path: target };
+  } finally {
+    if (mounted) {
+      spawnSync("hdiutil", ["detach", mounted, "-quiet"], { encoding: "utf8" });
+    }
+    if (!args.has("--keep-dmg")) rmSync(workDir, { recursive: true, force: true });
+    else process.stdout.write(`Disk image kept at ${dmgPath}\n`);
+  }
+}

package/bin/detect.js

@@ -0,0 +1,378 @@
+/**
+ * Local target detection.
+ *
+ * At `git push` time the developer's own running app is the disposable
+ * environment, so PreMan can test it with writes allowed. Finding it must take
+ * zero configuration, which means guessing -- and a wrong guess is worse than no
+ * guess, because it would test some unrelated service listening on port 3000 and
+ * report the results as if they were this repo's.
+ *
+ * So detection is two separate steps: propose candidates from repo signals, then
+ * *prove* one is this app by intersecting its live routes with the inventory we
+ * scanned. Nothing is tested until a candidate is confirmed.
+ */
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+// Ordered by how much the signal actually tells us. An explicit port in .env beats
+// a framework default, which beats a guess.
+export const SOURCE_RANK = {
+  env_file: 100,
+  package_script: 80,
+  compose: 70,
+  procfile: 60,
+  framework_default: 40,
+};
+
+const ENV_FILES = [".env", ".env.local", ".env.development", ".env.dev"];
+const ENV_URL_KEYS = ["API_URL", "API_BASE_URL", "BASE_URL", "PREMAN_TARGET_URL", "APP_URL"];
+const ENV_PORT_KEYS = ["PORT", "API_PORT", "SERVER_PORT", "APP_PORT", "HTTP_PORT"];
+
+const FRAMEWORK_DEFAULTS = [
+  { file: "next.config.js", port: 3000, stack: "next" },
+  { file: "next.config.mjs", port: 3000, stack: "next" },
+  { file: "next.config.ts", port: 3000, stack: "next" },
+  { file: "nest-cli.json", port: 3000, stack: "nest" },
+  { file: "manage.py", port: 8000, stack: "django" },
+  { file: "Gemfile", port: 3000, stack: "rails" },
+  { file: "pom.xml", port: 8080, stack: "spring" },
+  { file: "build.gradle", port: 8080, stack: "spring" },
+  { file: "go.mod", port: 8080, stack: "go" },
+  { file: "pyproject.toml", port: 8000, stack: "python" },
+  { file: "requirements.txt", port: 8000, stack: "python" },
+];
+
+function readIfExists(filePath) {
+  try {
+    return existsSync(filePath) ? readFileSync(filePath, "utf8") : "";
+  } catch {
+    return "";
+  }
+}
+
+/** Minimal dotenv reader: KEY=value, ignoring comments, exports, and quotes. */
+export function parseEnvFile(text) {
+  const out = {};
+  for (const rawLine of String(text || "").split("\n")) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) continue;
+    const withoutExport = line.startsWith("export ") ? line.slice(7).trim() : line;
+    const eq = withoutExport.indexOf("=");
+    if (eq <= 0) continue;
+    const key = withoutExport.slice(0, eq).trim();
+    let value = withoutExport.slice(eq + 1).trim();
+    const quote = value[0];
+    if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length > 1) {
+      value = value.slice(1, -1);
+    } else {
+      const hash = value.indexOf(" #");
+      if (hash >= 0) value = value.slice(0, hash).trim();
+    }
+    if (key) out[key] = value;
+  }
+  return out;
+}
+
+function normalisePort(value) {
+  const port = Number.parseInt(String(value ?? "").trim(), 10);
+  return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+}
+
+function loopbackUrl(port) {
+  return `http://127.0.0.1:${port}`;
+}
+
+function isLoopback(url) {
+  try {
+    const { hostname } = new URL(url);
+    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "::1" || hostname === "0.0.0.0";
+  } catch {
+    return false;
+  }
+}
+
+function addCandidate(map, { url, port, source, detail }) {
+  if (!url && port) url = loopbackUrl(port);
+  if (!url) return;
+  // Only ever propose loopback. A detected staging or production URL must never
+  // be silently promoted into a write-enabled target.
+  if (!isLoopback(url)) return;
+  const key = url.replace(/\/+$/, "");
+  const rank = SOURCE_RANK[source] ?? 0;
+  const existing = map.get(key);
+  if (existing && existing.rank >= rank) {
+    if (!existing.signals.includes(detail)) existing.signals.push(detail);
+    return;
+  }
+  map.set(key, {
+    url: key,
+    source,
+    rank,
+    signals: existing ? [...existing.signals, detail] : [detail],
+  });
+}
+
+function fromEnvFiles(root, map) {
+  for (const name of ENV_FILES) {
+    const text = readIfExists(path.join(root, name));
+    if (!text) continue;
+    const env = parseEnvFile(text);
+    for (const key of ENV_URL_KEYS) {
+      if (env[key]) addCandidate(map, { url: env[key], source: "env_file", detail: `${name}:${key}` });
+    }
+    for (const key of ENV_PORT_KEYS) {
+      const port = normalisePort(env[key]);
+      if (port) addCandidate(map, { port, source: "env_file", detail: `${name}:${key}` });
+    }
+  }
+}
+
+function fromPackageScripts(root, map) {
+  const text = readIfExists(path.join(root, "package.json"));
+  if (!text) return;
+  let pkg;
+  try {
+    pkg = JSON.parse(text);
+  } catch {
+    return;
+  }
+  const scripts = pkg.scripts || {};
+  for (const name of ["dev", "start", "serve", "start:dev"]) {
+    const script = scripts[name];
+    if (typeof script !== "string") continue;
+    const flag = script.match(/(?:-p|--port|PORT)[= ](\d{2,5})/);
+    if (flag) {
+      const port = normalisePort(flag[1]);
+      if (port) addCandidate(map, { port, source: "package_script", detail: `package.json:scripts.${name}` });
+    }
+  }
+}
+
+function fromCompose(root, map) {
+  for (const name of ["docker-compose.yaml", "docker-compose.yml", "compose.yaml", "compose.yml"]) {
+    const text = readIfExists(path.join(root, name));
+    if (!text) continue;
+    // Published host ports only: "8080:8080", "127.0.0.1:8080:8080", "- 3000:3000".
+    for (const match of text.matchAll(/["'\s-]\s*(?:\d+\.\d+\.\d+\.\d+:)?(\d{2,5}):(\d{2,5})/g)) {
+      const port = normalisePort(match[1]);
+      if (port) addCandidate(map, { port, source: "compose", detail: `${name}:ports` });
+    }
+  }
+}
+
+function fromProcfile(root, map) {
+  const text = readIfExists(path.join(root, "Procfile"));
+  if (!text) return;
+  const match = text.match(/(?:-p|--port|\$?\{?PORT\}?[= ])[= ]?(\d{2,5})/);
+  const port = normalisePort(match?.[1]);
+  if (port) addCandidate(map, { port, source: "procfile", detail: "Procfile" });
+}
+
+function fromFrameworkDefaults(root, map) {
+  let entries = [];
+  try {
+    entries = readdirSync(root);
+  } catch {
+    return;
+  }
+  const present = new Set(entries);
+  for (const { file, port, stack } of FRAMEWORK_DEFAULTS) {
+    if (present.has(file)) {
+      addCandidate(map, { port, source: "framework_default", detail: `${file} (${stack} default)` });
+    }
+  }
+}
+
+/**
+ * Candidate local base URLs, most trustworthy first. Proposals only -- none of
+ * these is safe to test against until `confirmCandidate` proves it is this app.
+ */
+export function detectCandidates(root = process.cwd(), { extraPorts = [] } = {}) {
+  const map = new Map();
+  fromEnvFiles(root, map);
+  fromPackageScripts(root, map);
+  fromCompose(root, map);
+  fromProcfile(root, map);
+  fromFrameworkDefaults(root, map);
+  for (const port of extraPorts) {
+    const parsed = normalisePort(port);
+    if (parsed) addCandidate(map, { port: parsed, source: "env_file", detail: "--port" });
+  }
+
+  return [...map.values()].sort((a, b) => b.rank - a.rank || a.url.localeCompare(b.url));
+}
+
+const SPEC_PATHS = ["/openapi.json", "/swagger.json", "/v3/api-docs", "/openapi.yaml"];
+
+async function fetchJson(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(url, { signal: controller.signal, redirect: "manual" });
+    if (!resp.ok) return null;
+    const text = await resp.text();
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function probe(url, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const resp = await fetch(url, { signal: controller.signal, redirect: "manual" });
+    return { reachable: true, status: resp.status };
+  } catch {
+    return { reachable: false, status: 0 };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function normalisePathTemplate(value) {
+  return String(value || "")
+    .trim()
+    .replace(/\{[^}]*\}/g, "{}")
+    .replace(/:[A-Za-z_][A-Za-z0-9_]*/g, "{}")
+    .replace(/\/+$/, "")
+    .toLowerCase() || "/";
+}
+
+/** Route keys the live app advertises through its generated spec, if it has one. */
+async function liveSpecRoutes(baseUrl, timeoutMs) {
+  for (const specPath of SPEC_PATHS) {
+    const spec = await fetchJson(`${baseUrl}${specPath}`, timeoutMs);
+    const paths = spec && typeof spec === "object" ? spec.paths : null;
+    if (!paths || typeof paths !== "object") continue;
+    const keys = new Set();
+    for (const [rawPath, methods] of Object.entries(paths)) {
+      if (!methods || typeof methods !== "object") continue;
+      for (const method of Object.keys(methods)) {
+        keys.add(`${method.toUpperCase()} ${normalisePathTemplate(rawPath)}`);
+      }
+    }
+    if (keys.size) return { keys, via: specPath };
+  }
+  return null;
+}
+
+export const CONFIRM_MIN_OVERLAP = 0.5;
+export const CONFIRM_MIN_ROUTES = 2;
+
+/**
+ * Decide whether a reachable candidate really is the repo under test.
+ *
+ * With a live spec we require a real overlap with the scanned inventory. Without
+ * one we fall back to probing a couple of known routes and requiring that they
+ * do not 404 -- weaker, so it is reported as `weak` confidence and the caller
+ * decides whether that is enough.
+ */
+export async function confirmCandidate(candidate, inventory, { timeoutMs = 2000 } = {}) {
+  const baseUrl = candidate.url.replace(/\/+$/, "");
+  const root = await probe(`${baseUrl}/`, timeoutMs);
+  if (!root.reachable) {
+    return { ...candidate, confirmed: false, reason: "nothing listening" };
+  }
+
+  const expected = new Set(
+    (inventory || [])
+      .map((ep) => {
+        const method = String(ep.method || "GET").toUpperCase();
+        const template = normalisePathTemplate(ep.path_template || ep.path || "");
+        return template ? `${method} ${template}` : null;
+      })
+      .filter(Boolean)
+  );
+
+  if (expected.size === 0) {
+    return {
+      ...candidate,
+      confirmed: false,
+      reason: "no scanned inventory to match against",
+    };
+  }
+
+  const live = await liveSpecRoutes(baseUrl, timeoutMs);
+  if (live) {
+    let matched = 0;
+    for (const key of expected) if (live.keys.has(key)) matched += 1;
+    const overlap = matched / expected.size;
+    if (matched >= CONFIRM_MIN_ROUTES && overlap >= CONFIRM_MIN_OVERLAP) {
+      return {
+        ...candidate,
+        confirmed: true,
+        confidence: "spec",
+        matched,
+        expected: expected.size,
+        overlap: Number(overlap.toFixed(3)),
+        via: live.via,
+      };
+    }
+    return {
+      ...candidate,
+      confirmed: false,
+      reason: `live spec at ${live.via} matches ${matched}/${expected.size} scanned routes; ` +
+        "this is probably a different service",
+      matched,
+      expected: expected.size,
+    };
+  }
+
+  // No spec. Probe a few GET routes and require that the app recognises them.
+  const probes = (inventory || [])
+    .filter((ep) => String(ep.method || "GET").toUpperCase() === "GET")
+    .slice(0, 3);
+  let recognised = 0;
+  for (const ep of probes) {
+    const concrete = String(ep.path_template || ep.path || "/").replace(/\{[^}]*\}/g, "1");
+    const result = await probe(`${baseUrl}${concrete.startsWith("/") ? "" : "/"}${concrete}`, timeoutMs);
+    if (result.reachable && result.status !== 404) recognised += 1;
+  }
+  if (probes.length && recognised === probes.length) {
+    return {
+      ...candidate,
+      confirmed: true,
+      confidence: "weak",
+      matched: recognised,
+      expected: probes.length,
+      via: "route probe",
+    };
+  }
+  return {
+    ...candidate,
+    confirmed: false,
+    reason: probes.length
+      ? `${recognised}/${probes.length} probed routes recognised`
+      : "no GET route available to probe",
+  };
+}
+
+/** First candidate that proves itself, or a structured miss. */
+export async function resolveLocalTarget(
+  inventory,
+  { root = process.cwd(), extraPorts = [], timeoutMs = 2000 } = {}
+) {
+  const candidates = detectCandidates(root, { extraPorts });
+  if (!candidates.length) {
+    return { target: null, candidates: [], reason: "no local target signals in this repo" };
+  }
+  const attempts = [];
+  for (const candidate of candidates) {
+    const result = await confirmCandidate(candidate, inventory, { timeoutMs });
+    attempts.push(result);
+    if (result.confirmed) return { target: result, candidates: attempts };
+  }
+  return {
+    target: null,
+    candidates: attempts,
+    reason: attempts[0]?.reason || "no candidate could be confirmed",
+  };
+}