@piagent/platform 1.3.1 → 1.4.1

package/scripts/traffic-snapshot.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+// Archives GitHub repository traffic before GitHub discards it.
+//
+// The traffic API only serves a rolling 14-day window. Anything older is gone
+// for good -- there is no endpoint that returns it and no way to reconstruct
+// it. So the counts are merged into CSV files that keep growing, and a run that
+// happens at least every 14 days loses nothing.
+//
+// Merge rule: a row is keyed by its day and the newest fetch wins. Today's
+// bucket is still filling while the run happens, so it is always partial; the
+// next run overwrites it with the settled value. Once a day leaves the window
+// it stops being returned at all, and the stored row is final.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const EXIT_USAGE = 2;
+const EXIT_FORBIDDEN = 3;
+
+const SERIES = [
+  { endpoint: "clones", file: "clones.csv", columns: ["date", "count", "uniques"] },
+  { endpoint: "views", file: "views.csv", columns: ["date", "count", "uniques"] }
+];
+// Referrers and paths are a 14-day rollup, not a daily series: the API gives no
+// per-day breakdown, so a row is only meaningful next to the day it was read.
+const ROLLUPS = [
+  { endpoint: "popular/referrers", file: "referrers.csv", key: "referrer", columns: ["snapshot_date", "referrer", "count", "uniques"] },
+  { endpoint: "popular/paths", file: "paths.csv", key: "path", columns: ["snapshot_date", "path", "title", "count", "uniques"] }
+];
+
+function fail(message, code = EXIT_USAGE) {
+  console.error(`FAIL: ${message}`);
+  process.exit(code);
+}
+
+export function parseArguments(argv) {
+  const options = { repository: "", out: "traffic", dryRun: false, today: "" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    switch (argument) {
+      case "--repository": case "--repo": {
+        options.repository = argv[index += 1] ?? "";
+        if (!/^[^/\s]+\/[^/\s]+$/.test(options.repository)) fail("--repository needs owner/name");
+        break;
+      }
+      case "--out": {
+        options.out = argv[index += 1] ?? "";
+        if (!options.out) fail("--out needs a directory");
+        break;
+      }
+      // The archive is written from a snapshot date, and a test cannot wait a
+      // day to prove the merge. Injecting it keeps the assertions exact.
+      case "--today": {
+        options.today = argv[index += 1] ?? "";
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(options.today)) fail("--today needs YYYY-MM-DD");
+        break;
+      }
+      case "--dry-run": options.dryRun = true; break;
+      case "-h": case "--help": options.help = true; break;
+      default: fail(`unknown argument: ${argument}`);
+    }
+  }
+  return options;
+}
+
+export function csvEscape(value) {
+  const text = String(value ?? "");
+  return /[",\n\r]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export function parseCsv(text) {
+  const rows = [];
+  let row = [], field = "", quoted = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (quoted) {
+      if (character === '"' && text[index + 1] === '"') { field += '"'; index += 1; }
+      else if (character === '"') quoted = false;
+      else field += character;
+      continue;
+    }
+    if (character === '"') quoted = true;
+    else if (character === ",") { row.push(field); field = ""; }
+    else if (character === "\n") { row.push(field); rows.push(row); row = []; field = ""; }
+    else if (character !== "\r") field += character;
+  }
+  if (field.length || row.length) { row.push(field); rows.push(row); }
+  return rows.filter((entry) => entry.some((cell) => cell !== ""));
+}
+
+function readTable(file, columns) {
+  if (!fs.existsSync(file)) return [];
+  const rows = parseCsv(fs.readFileSync(file, "utf8"));
+  const header = rows.shift();
+  if (!header || header.join(",") !== columns.join(",")) {
+    fail(`${file} has header [${header?.join(", ") ?? "none"}], expected [${columns.join(", ")}]`);
+  }
+  return rows.map((row) => Object.fromEntries(columns.map((column, index) => [column, row[index] ?? ""])));
+}
+
+function writeTable(file, columns, rows) {
+  const lines = [columns.join(",")];
+  for (const row of rows) lines.push(columns.map((column) => csvEscape(row[column])).join(","));
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${lines.join("\n")}\n`);
+}
+
+/**
+ * Existing rows plus fetched rows, keyed by `key`. The fetched value wins,
+ * because it is the newer reading of the same day. Rows outside the API window
+ * are untouched -- that is the whole point of the archive.
+ */
+export function mergeByKey(existing, fetched, key) {
+  const merged = new Map(existing.map((row) => [row[key], row]));
+  for (const row of fetched) merged.set(row[key], row);
+  return [...merged.values()].sort((a, b) => String(a[key]).localeCompare(String(b[key])));
+}
+
+/** Rollup rows for one snapshot date, replacing any earlier run on that date. */
+export function mergeRollup(existing, fetched, snapshotDate) {
+  const kept = existing.filter((row) => row.snapshot_date !== snapshotDate);
+  return [...kept, ...fetched].sort((a, b) =>
+    String(a.snapshot_date).localeCompare(String(b.snapshot_date))
+    || Number(b.count) - Number(a.count));
+}
+
+async function fetchTraffic(repository, endpoint, token) {
+  const url = `https://api.github.com/repos/${repository}/traffic/${endpoint}`;
+  const response = await fetch(url, {
+    headers: {
+      accept: "application/vnd.github+json",
+      authorization: `Bearer ${token}`,
+      "user-agent": "piagent-traffic-snapshot",
+      "x-github-api-version": "2022-11-28"
+    }
+  });
+  if (response.status === 403 || response.status === 404) {
+    // The distinction matters: this is the one failure an operator cannot debug
+    // from the status code, because the traffic API answers 403 for a token
+    // that is valid but lacks push access -- which the default workflow token
+    // may or may not have, depending on repository settings.
+    fail(`the token cannot read ${endpoint} for ${repository} (HTTP ${response.status}).\n`
+      + "  Repository traffic needs push access. If this ran in GitHub Actions with the\n"
+      + "  default GITHUB_TOKEN, create a fine-grained personal access token with the\n"
+      + "  'Administration: read' permission on this repository, store it as the\n"
+      + "  TRAFFIC_TOKEN secret, and re-run. Nothing was written.", EXIT_FORBIDDEN);
+  }
+  if (!response.ok) fail(`GET ${url} returned HTTP ${response.status}`);
+  return response.json();
+}
+
+export async function snapshot(options, token, fetcher = fetchTraffic) {
+  const today = options.today || new Date().toISOString().slice(0, 10);
+  const summary = { repository: options.repository, snapshotDate: today, files: {} };
+
+  // Read every existing file before fetching anything. A corrupt archive is a
+  // reason to stop, and stopping before the network call keeps the failure
+  // about the file rather than about whatever the API happened to answer.
+  const existing = new Map();
+  for (const target of [...SERIES, ...ROLLUPS]) {
+    existing.set(target.file, readTable(path.join(options.out, target.file), target.columns));
+  }
+
+  for (const series of SERIES) {
+    const payload = await fetcher(options.repository, series.endpoint, token);
+    const fetched = (payload[series.endpoint] ?? []).map((entry) => ({
+      date: String(entry.timestamp ?? "").slice(0, 10),
+      count: String(entry.count ?? 0),
+      uniques: String(entry.uniques ?? 0)
+    })).filter((row) => row.date);
+    const file = path.join(options.out, series.file);
+    const merged = mergeByKey(existing.get(series.file), fetched, "date");
+    if (!options.dryRun) writeTable(file, series.columns, merged);
+    summary.files[series.file] = { fetchedDays: fetched.length, totalDays: merged.length };
+  }
+
+  for (const rollup of ROLLUPS) {
+    const payload = await fetcher(options.repository, rollup.endpoint, token);
+    const fetched = (Array.isArray(payload) ? payload : []).map((entry) => ({
+      snapshot_date: today,
+      [rollup.key]: String(entry[rollup.key] ?? entry.referrer ?? entry.path ?? ""),
+      title: String(entry.title ?? ""),
+      count: String(entry.count ?? 0),
+      uniques: String(entry.uniques ?? 0)
+    }));
+    const file = path.join(options.out, rollup.file);
+    const merged = mergeRollup(existing.get(rollup.file), fetched, today);
+    if (!options.dryRun) writeTable(file, rollup.columns, merged);
+    summary.files[rollup.file] = { fetchedRows: fetched.length, totalRows: merged.length };
+  }
+
+  return summary;
+}
+
+const invokedDirectly = process.argv[1]
+  && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+
+if (invokedDirectly) {
+  const options = parseArguments(process.argv.slice(2));
+  if (options.help) {
+    console.log(`Usage:
+  node scripts/traffic-snapshot.mjs --repository <owner/name> [--out <dir>] [--dry-run]
+
+Archives GitHub traffic (clones, views, referrers, paths) into growing CSV files.
+The API only keeps 14 days, so run this at least fortnightly or the gap is
+permanent. Reads the token from TRAFFIC_TOKEN, else GITHUB_TOKEN.`);
+    process.exit(0);
+  }
+  if (!options.repository) fail("--repository is required");
+  const token = process.env.TRAFFIC_TOKEN || process.env.GITHUB_TOKEN;
+  if (!token) fail("set TRAFFIC_TOKEN or GITHUB_TOKEN");
+  const summary = await snapshot(options, token);
+  console.log(JSON.stringify(summary, null, 2));
+}

package/scripts/typescript-loader.mjs

@@ -1,12 +1,53 @@
 import fs from "node:fs/promises";
 import { stripTypeScriptTypes } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Repository TypeScript must remain erasable: the integrity lock hashes the
+// source bytes and `strip` fails closed if a future change needs codegen.
+// pi-mcp-adapter@2.15.0 is the sole exception because its published OAuth
+// implementation contains parameter properties. Keep that transform isolated
+// to the exact installed adapter root and Node release reviewed below. A Node
+// or adapter upgrade must deliberately update these pins before OAuth loads.
+export const PINNED_EXTERNAL_TRANSFORM = Object.freeze({
+  nodeVersion: "24.11.1",
+  packageName: "pi-mcp-adapter",
+  packageVersion: "2.15.0"
+});
+
+async function pinnedTransformRoot(url) {
+  const configured = process.env.PIAGENT_PINNED_TS_TRANSFORM_ROOT;
+  if (!configured || process.versions.node !== PINNED_EXTERNAL_TRANSFORM.nodeVersion) return false;
+  // This asks one question: is the file being loaded inside the pinned adapter?
+  // A configured root that is absent, unreadable or not that adapter answers
+  // "no". It used to throw instead, and the throw escaped `load` on the first
+  // `.ts` file of any kind -- so a machine without pi-mcp-adapter installed
+  // could not start the gateway at all, for a reason that had nothing to do
+  // with the file it died on. Answering "no" falls back to `strip`, which is
+  // the stricter of the two modes: this can only refuse a transform, never
+  // grant one.
+  let root;
+  let metadata;
+  try {
+    root = await fs.realpath(configured);
+    metadata = JSON.parse(await fs.readFile(path.join(root, "package.json"), "utf8"));
+  } catch {
+    return false;
+  }
+  if (metadata?.name !== PINNED_EXTERNAL_TRANSFORM.packageName
+    || metadata?.version !== PINNED_EXTERNAL_TRANSFORM.packageVersion) return false;
+  const target = await fs.realpath(fileURLToPath(url));
+  const relative = path.relative(root, target);
+  return Boolean(relative) && !relative.startsWith("..") && !path.isAbsolute(relative);
+}
 
 export async function load(url, context, nextLoad) {
   if (!url.endsWith(".ts")) return nextLoad(url, context);
   const source = await fs.readFile(new URL(url), "utf8");
+  const mode = await pinnedTransformRoot(url) ? "transform" : "strip";
   return {
     format: "module",
     shortCircuit: true,
-    source: stripTypeScriptTypes(source, { mode: "strip", sourceUrl: url })
+    source: stripTypeScriptTypes(source, { mode, sourceUrl: url })
   };
 }

package/scripts/uninstall-global.sh

@@ -80,6 +80,46 @@ run_cmd() {
   fi
 }
 
+# The helper can live under a non-default npm prefix: install falls back to a
+# user-writable root when the configured one is not writable, and --npm-prefix
+# picks one deliberately. A bare `npm uninstall -g` resolves against the
+# configured prefix instead, so it removes nothing and still reports success.
+# Derive the prefix from where this script actually runs, the same way
+# update-global.mjs does, and only add --prefix when it differs.
+installed_helper_prefix() {
+  local root="$ROOT"
+  [[ "$(basename "$root")" == "platform" ]] || return 0
+  local scope_root node_modules_root parent
+  scope_root="$(dirname "$root")"
+  [[ "$(basename "$scope_root")" == "@piagent" ]] || return 0
+  node_modules_root="$(dirname "$scope_root")"
+  [[ "$(basename "$node_modules_root")" == "node_modules" ]] || return 0
+  parent="$(dirname "$node_modules_root")"
+  # An npx run lives in a prunable cache that owns no bin on anyone's PATH;
+  # uninstalling from there would claim to remove an install nobody has.
+  case "$parent" in
+    */_npx/*|*/_npx) return 0 ;;
+  esac
+  if [[ "$(basename "$parent")" == "lib" ]]; then
+    dirname "$parent"
+  else
+    printf '%s' "$parent"
+  fi
+}
+
+# The prefix npm has to be pointed at, or empty when the helper already lives
+# under the configured one and the plain command is correct. Returns a single
+# value rather than an argument list: macOS still ships bash 3.2, where
+# expanding an empty array under `set -u` aborts the script.
+npm_prefix_override() {
+  local helper_prefix configured
+  helper_prefix="$(installed_helper_prefix)"
+  [[ -n "$helper_prefix" ]] || return 0
+  configured="$(npm prefix -g 2>/dev/null || true)"
+  [[ "$helper_prefix" != "$configured" ]] || return 0
+  printf '%s' "$helper_prefix"
+}
+
 # Reads the package sources Pi has registered, so removal targets what is
 # actually installed rather than what this version happens to install today. An
 # older release registered a different source shape, and it still has to come
@@ -174,7 +214,13 @@ if [[ "$WITH_HOST" == true ]]; then
   echo
   if command -v npm >/dev/null 2>&1; then
     echo "Uninstalling Pi host:"
-    run_cmd npm uninstall -g "$PI_HOST_PACKAGE"
+    HOST_PREFIX="$(npm_prefix_override)"
+    if [[ -n "$HOST_PREFIX" ]]; then
+      echo "  (prefix $HOST_PREFIX, where this helper is installed)"
+      run_cmd npm uninstall -g --prefix "$HOST_PREFIX" "$PI_HOST_PACKAGE"
+    else
+      run_cmd npm uninstall -g "$PI_HOST_PACKAGE"
+    fi
   else
     echo "WARN: npm is not on PATH; cannot uninstall $PI_HOST_PACKAGE." >&2
   fi
@@ -231,7 +277,12 @@ echo
 if [[ "$APPLY" == true ]]; then
   echo "Uninstall complete."
   echo "The npm-global helper is separate and stays until you remove it:"
-  echo "  npm uninstall -g $PLATFORM_PACKAGE"
+  HELPER_PREFIX="$(npm_prefix_override)"
+  if [[ -n "$HELPER_PREFIX" ]]; then
+    echo "  npm uninstall -g --prefix $HELPER_PREFIX $PLATFORM_PACKAGE"
+  else
+    echo "  npm uninstall -g $PLATFORM_PACKAGE"
+  fi
 else
   echo "Dry run only. Nothing was removed. Re-run with --apply to perform it."
 fi

package/scripts/update-global.mjs

@@ -213,8 +213,21 @@ function binForPrefix(prefix) {
   return process.platform === "win32" ? prefix : path.join(prefix, "bin");
 }
 
+// The npx cache is a `node_modules` tree like any other, so the documented
+// bootstrap -- `npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update`
+// -- ran the helper from `~/.npm/_npx/<hash>/node_modules/@piagent/platform` and
+// this function happily reported that hash directory as the prefix to install
+// into. Host and helper then landed in a cache npm is free to prune, with a `bin`
+// that is on nobody's PATH: the command reported success and the machine had
+// nothing installed. A cache is never an install target, so it is refused here
+// and the caller falls back to a real global prefix.
+function isNpxCacheRoot(root) {
+  return root.split(path.sep).some((segment) => segment === "_npx" || segment === "_cacache");
+}
+
 function npmPrefixForInstalledHelper(root) {
   if (path.basename(root) !== "platform") return undefined;
+  if (isNpxCacheRoot(root)) return undefined;
   const scopeRoot = path.dirname(root);
   if (path.basename(scopeRoot) !== "@piagent") return undefined;
   const nodeModulesRoot = path.dirname(scopeRoot);
@@ -444,10 +457,29 @@ function main() {
     console.log(`  npm:     using explicit global prefix ${npmTarget.prefix}`);
   }
 
+  // The host version above was read before this prepend, so it described whatever
+  // `pi` the caller's PATH happened to resolve. Once the prefix moves -- a default
+  // global root that is not writable, an explicit `--npm-prefix`, or a helper
+  // already installed elsewhere -- every step below uses a different `pi`, and
+  // "(already current)" could be describing a binary this run never touches. The
+  // decision belongs to the `pi` that will actually be used, so it is taken again
+  // here rather than trusted from before the move.
+  let effectiveHost = currentHost;
+  let effectiveHostNeedsChange = hostNeedsChange;
+  if (npmTarget.bin) {
+    const activeHost = installedHostVersion();
+    if (activeHost !== currentHost) {
+      effectiveHost = activeHost;
+      effectiveHostNeedsChange = options.host && (options.force || activeHost !== targetHost);
+      console.log(`  host:    the active prefix resolves pi ${activeHost ?? "not installed"}, not ${currentHost ?? "not installed"};`
+        + ` using ${effectiveHost ?? "not installed"} -> ${targetHost}${effectiveHostNeedsChange ? "" : " (already current)"}`);
+    }
+  }
+
   // Host first: piagent-install refuses to run against a host that does not match
   // the version its package.json pins, so a helper installed ahead of the host
   // would fail on its very next step.
-  if (hostNeedsChange) {
+  if (effectiveHostNeedsChange) {
     const args = npmInstallArgs(`${HOST_PACKAGE}@${targetHost}`, npmTarget);
     describeStep(options.dryRun, "npm", args);
     if (!options.dryRun && !run("npm", args).ok) fail(`could not install ${HOST_PACKAGE}@${targetHost}`);