@piagent/platform 1.0.2 → 1.1.1

package/scripts/check-published-site.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+
+// Checks that the published documentation site serves the released version from
+// every address it resolves to.
+//
+// Opening the site in a browser is not this check. A domain with several A
+// records answers from whichever one the resolver picked that second, so one
+// address can be dead for a week while every manual look happens to land on a
+// healthy one. This resolves the name, then asks each address directly with the
+// right Host header and SNI, and reports them separately. A partial outage has
+// to read as a failure, not as an average.
+//
+// A redirect from a pinned address back to the same host is reported rather
+// than followed: that is the shape of a loop, and following it would only
+// re-resolve the name and hide which address caused it.
+
+import dns from "node:dns/promises";
+import https from "node:https";
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REQUEST_TIMEOUT_MS = 15_000;
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+
+function fail(message) {
+  process.stderr.write(`FAIL: ${message}\n`);
+  process.exit(1);
+}
+
+function parseArguments(values) {
+  const options = { hosts: [], expect: null, allowUnverified: false };
+  for (let index = 0; index < values.length; index += 1) {
+    const option = values[index];
+    if (option === "-h" || option === "--help") {
+      process.stdout.write("Usage: node scripts/check-published-site.mjs [--host <name>]... [--expect <text>] [--allow-unverified]\n");
+      process.stdout.write("Verify every resolved address of the docs site serves the released version.\n");
+      process.stdout.write("Defaults to piagent.io.vn and www.piagent.io.vn, expecting the root package version.\n");
+      process.stdout.write("--allow-unverified downgrades addresses this machine cannot route to from a failure to a note.\n");
+      process.exit(0);
+    }
+    if (option === "--allow-unverified") {
+      options.allowUnverified = true;
+      continue;
+    }
+    const value = values[index + 1];
+    if (option === "--host") {
+      if (!value || value.startsWith("--")) fail("--host requires a value");
+      if (!/^[a-z0-9.-]{1,253}$/i.test(value)) fail(`--host value ${JSON.stringify(value)} is not a hostname`);
+      options.hosts.push(value);
+      index += 1;
+      continue;
+    }
+    if (option === "--expect") {
+      if (!value || value.startsWith("--")) fail("--expect requires a value");
+      if (options.expect !== null) fail("duplicate option --expect");
+      options.expect = value;
+      index += 1;
+      continue;
+    }
+    fail(`unknown option ${option}`);
+  }
+  if (options.hosts.length === 0) options.hosts = ["piagent.io.vn", "www.piagent.io.vn"];
+  if (options.expect === null) {
+    const manifest = JSON.parse(fs.readFileSync(path.join(repositoryRoot, "package.json"), "utf8"));
+    options.expect = manifest.version;
+  }
+  return options;
+}
+
+async function resolveAddresses(host) {
+  const addresses = [];
+  for (const [family, resolver] of [[4, dns.resolve4], [6, dns.resolve6]]) {
+    try {
+      for (const address of await resolver(host)) addresses.push({ address, family });
+    } catch (error) {
+      if (error?.code !== "ENODATA" && error?.code !== "ENOTFOUND") throw error;
+    }
+  }
+  return addresses;
+}
+
+// `port` and `tlsOptions` exist so the body-cap path can be driven against a
+// local server in a test. Nothing on the command line reaches them, and the
+// defaults are what every real run uses: port 443 and Node's own trust store.
+export function request(host, { address, family, port = 443 }, tlsOptions = {}) {
+  return new Promise((resolve) => {
+    // Every path out of here has to settle exactly once. Capping the body
+    // destroys the response, and a destroyed response emits neither `end` nor
+    // `error` — it goes straight to `aborted` and `close`. Without a `close`
+    // handler the promise stays pending forever, and the request timeout cannot
+    // rescue it because the socket is already gone. That is a hung release gate,
+    // not a failed one.
+    let settled = false;
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    const call = https.request(
+      {
+        ...tlsOptions,
+        host: address,
+        family,
+        servername: host,
+        port,
+        path: "/",
+        method: "GET",
+        headers: { Host: host, "User-Agent": "piagent-site-check" },
+        timeout: REQUEST_TIMEOUT_MS
+      },
+      (response) => {
+        let body = "";
+        let bytes = 0;
+        let truncated = false;
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          bytes += Buffer.byteLength(chunk, "utf8");
+          if (bytes > MAX_BODY_BYTES) {
+            truncated = true;
+            response.destroy();
+            return;
+          }
+          body += chunk;
+        });
+        response.on("end", () =>
+          settle({ status: response.statusCode, location: response.headers.location, body, truncated })
+        );
+        response.on("error", (error) => settle({ error: error.message, code: error.code }));
+        response.on("close", () =>
+          settle({ status: response.statusCode, location: response.headers.location, body, truncated })
+        );
+      }
+    );
+    call.on("timeout", () => {
+      call.destroy();
+      settle({ error: `no response within ${REQUEST_TIMEOUT_MS}ms` });
+    });
+    call.on("error", (error) => settle({ error: error.message, code: error.code }));
+    call.end();
+  });
+}
+
+// A redirect is only acceptable when it leaves this host for another name we are
+// also checking. Pointing back at itself is the loop; pointing off the domain
+// means the released page is not what this address serves.
+export function judge(host, hosts, expect, result, family) {
+  // A machine with no route to the address family cannot say anything about the
+  // address. Calling that a site failure would be a false positive, and a gate
+  // that cries wolf gets ignored, so it is reported as unverified instead.
+  if (result.code === "ENETUNREACH" || result.code === "EHOSTUNREACH") {
+    return { unverified: `no route from this machine to IPv${family}: ${result.error}` };
+  }
+  if (result.error) return `unreachable: ${result.error}`;
+  if (result.status >= 300 && result.status < 400) {
+    let target;
+    try {
+      target = new URL(result.location ?? "", `https://${host}/`);
+    } catch {
+      return `HTTP ${result.status} with an unreadable Location header`;
+    }
+    if (target.hostname === host) return `HTTP ${result.status} redirecting to itself at ${target.href}`;
+    if (!hosts.includes(target.hostname)) return `HTTP ${result.status} redirecting off the site to ${target.href}`;
+    return null;
+  }
+  if (result.status !== 200) return `HTTP ${result.status}`;
+  if (result.body.includes(expect)) return null;
+  // Not finding the version in a body that was cut short is not the same claim
+  // as not finding it in the page.
+  if (result.truncated) {
+    return `HTTP 200 but the response exceeded ${MAX_BODY_BYTES} bytes and the part read does not mention ${expect}`;
+  }
+  return `HTTP 200 but the page does not mention ${expect}`;
+}
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  const failures = [];
+  const unverified = [];
+  let checked = 0;
+
+  for (const host of options.hosts) {
+    let addresses;
+    try {
+      addresses = await resolveAddresses(host);
+    } catch (error) {
+      fail(`${host} did not resolve: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (addresses.length === 0) fail(`${host} resolved to no addresses`);
+    for (const entry of addresses) {
+      const verdict = judge(host, options.hosts, options.expect, await request(host, entry), entry.family);
+      checked += 1;
+      if (verdict?.unverified) {
+        unverified.push(`${host} at ${entry.address}: ${verdict.unverified}`);
+        process.stdout.write(`  ????  ${host} ${entry.address} — ${verdict.unverified}\n`);
+      } else if (verdict) {
+        failures.push(`${host} at ${entry.address}: ${verdict}`);
+        process.stdout.write(`  FAIL  ${host} ${entry.address} — ${verdict}\n`);
+      } else {
+        process.stdout.write(`  ok    ${host} ${entry.address}\n`);
+      }
+    }
+  }
+
+  const summary = summarize({ checked, failures, unverified, expect: options.expect, allowUnverified: options.allowUnverified });
+  process.stdout.write(summary.out);
+  process.stderr.write(summary.err);
+  process.exit(summary.code);
+}
+
+// An address nobody checked is not an address that passed. Reporting it as
+// unverified and then exiting 0 makes the gate say "verified every address"
+// about a run that did not, so an unchecked address ends the run unless the
+// operator accepts the gap deliberately.
+export function summarize({ checked, failures, unverified, expect, allowUnverified }) {
+  let out = "";
+  for (const entry of unverified) out += `UNVERIFIED: ${entry}\n`;
+
+  if (failures.length > 0) {
+    let err = `FAIL: ${failures.length} of ${checked} addresses do not serve ${expect}\n`;
+    for (const failure of failures) err += `  ${failure}\n`;
+    err += "Each address is a real path users take. Fix the DNS records or the deployment behind them.\n";
+    return { code: 1, out, err };
+  }
+
+  if (unverified.length > 0 && !allowUnverified) {
+    let err = `FAIL: ${unverified.length} of ${checked} addresses could not be checked from this machine\n`;
+    for (const entry of unverified) err += `  ${entry}\n`;
+    err += "Run the check from a machine with a route to them, or pass --allow-unverified to accept the gap.\n";
+    return { code: 1, out, err };
+  }
+
+  const verified = checked - unverified.length;
+  const note = unverified.length > 0 ? ` (${unverified.length} accepted as not reachable from this machine)` : "";
+  out += `PASS: ${verified} of ${checked} addresses serve ${expect}${note}\n`;
+  return { code: 0, out, err: "" };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/scripts/configure-mcp.sh

@@ -211,6 +211,22 @@ const servers = {
   }
 };
 
+// Writing a server definition does not make it usable. What each one still
+// needs from the operator is stated here so it can be printed at the moment the
+// definition is written, rather than living only in a description string that
+// shows up under --list.
+const prerequisites = {
+  context7: ["optional: export CONTEXT7_API_KEY for a higher documentation quota"],
+  "chrome-devtools": ["a local Chrome installation"],
+  github: [
+    "Docker running",
+    "export GITHUB_PERSONAL_ACCESS_TOKEN with the scopes you intend to use"
+  ],
+  playwright: ["browsers installed on first use (npx playwright install)"],
+  figma: ["Figma OAuth, completed from the Pi MCP panel on first use"],
+  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
+};
+
 const presets = {
   minimal: [],
   docs: ["context7"],
@@ -227,7 +243,10 @@ const presets = {
 if (listOnly) {
   console.log(JSON.stringify({
     presets,
-    servers: Object.fromEntries(Object.entries(servers).map(([name, value]) => [name, value.description]))
+    servers: Object.fromEntries(Object.entries(servers).map(([name, value]) => [
+      name,
+      { description: value.description, requires: prerequisites[name] ?? [] }
+    ]))
   }, null, 2));
   process.exit(0);
 }
@@ -290,6 +309,19 @@ const report = {
   serverCount: Object.keys(current.mcpServers).length
 };
 
+// stdout stays machine-readable; the operator note goes to stderr.
+function reportPrerequisites() {
+  const lines = [];
+  for (const name of presets[presetName]) {
+    for (const item of prerequisites[name] ?? []) lines.push(`  ${name}: ${item}`);
+  }
+  if (lines.length === 0) return;
+  console.error("");
+  console.error("Server definitions are written. Each still needs this before it can connect:");
+  for (const line of lines) console.error(line);
+  console.error("Servers connect lazily, so nothing above is checked until the first call.");
+}
+
 if (dryRun) {
   console.log(JSON.stringify(report, null, 2));
   console.log(output);
@@ -297,5 +329,6 @@ if (dryRun) {
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, output);
   console.log(JSON.stringify(report, null, 2));
+  reportPrerequisites();
 }
 NODE

package/scripts/init-project.sh

@@ -238,6 +238,20 @@ NODE
     fi
   fi
 
+  # Running from an installed package rather than a checkout. The name and
+  # version on disk are exactly what a teammate resolves from the registry, so
+  # they are a portable source; the install path is not, and project settings
+  # are meant to be committed.
+  if [[ "$PLATFORM_ROOT" == */node_modules/* ]]; then
+    local installed_name installed_version
+    installed_name="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).name ?? "");' "$PLATFORM_ROOT/package.json")"
+    installed_version="$(node -e 'const fs=require("node:fs"); process.stdout.write(JSON.parse(fs.readFileSync(process.argv[1], "utf8")).version ?? "");' "$PLATFORM_ROOT/package.json")"
+    if [[ -n "$installed_name" && "$installed_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+([+-][0-9A-Za-z.-]+)?$ ]]; then
+      printf 'npm:%s@%s\n' "$installed_name" "$installed_version"
+      return
+    fi
+  fi
+
   echo "WARN: No exact package source provided." >&2
   echo "WARN: .pi/settings.json will use local platform path; do not commit it for team use." >&2
   printf '%s\n' "$PLATFORM_ROOT"
@@ -365,5 +379,10 @@ echo "  cd \"$PROJECT_PATH\""
 echo "  pi"
 echo "  /login              # first time only"
 echo "  /onboard-project    # first project-read after model selection"
+echo "  /mcp                # MCP servers come from the global install, not from this project"
 echo "  /context-index      # inspect compact project context index"
 echo "  /memory-policy      # inspect project memory policy when needed"
+echo
+echo "Note: .mcp.json and .pi/mcp.json are written empty on purpose. They exist so this"
+echo "project can add its own servers later; the shared baseline lives in the global"
+echo "config written by piagent-setup. An empty file here does not mean MCP is missing."

package/scripts/install-global.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 usage() {
   cat <<'USAGE'
 Usage:
-  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp] [--mcp-preset <preset>] [--with-subagents] [--subagents-preset <preset>] [--with-web-access] [--with-herdr] [--model-scope <preset>]
+  scripts/install-global.sh [--stable|--dev|--local|--channel <stable|dev|local>] [--version <tag>] [--resolve-tag] [--package-source <source>] [--dry-run] [--with-mcp|--no-mcp] [--mcp-preset <preset>] [--with-subagents] [--subagents-preset <preset>] [--with-web-access] [--with-herdr] [--model-scope <preset>]
 
 Purpose:
   Install the piagent Pi package into the current user's global Pi settings.
@@ -15,7 +15,7 @@ Package source examples:
   # Installs the stable tag after resolving it to a commit SHA.
 
   # Pin a specific release:
-  scripts/install-global.sh --version v1.0.2 --resolve-tag
+  scripts/install-global.sh --version v1.1.1 --resolve-tag
 
   # Preview the planned install/update without changing user config:
   scripts/install-global.sh --stable --dry-run
@@ -35,7 +35,10 @@ Notes:
   - OAuth is intentionally not automated. Run `pi` then `/login`.
   - Model scope is configured with Pi's native `enabledModels` so users choose via `/model`, Ctrl+L, `/scoped-models`, and Ctrl+P.
   - Herdr integration is optional and modifies user-level Herdr/Pi config.
-  - MCP preset defaults to core: Context7 docs, Chrome DevTools, GitHub.
+  - MCP is installed by default with the core preset: Context7 docs, Chrome DevTools, GitHub.
+    Skip it with --no-mcp. Writing the config does not start or authenticate anything:
+    the GitHub server additionally needs Docker running and GITHUB_PERSONAL_ACCESS_TOKEN
+    exported, and Chrome DevTools needs a local Chrome.
   - Subagents preset defaults to safe: compact tool description, bounded concurrency/depth.
   - Web access is optional. Install it only when you want the builtin `researcher` subagent to browse/fetch web sources inside Pi.
 USAGE
@@ -50,8 +53,9 @@ DEFAULT_REPO_REMOTE_URL="https://github.com/Vt-mmm/piagent.git"
 PACKAGE_SOURCE="${PIAGENT_PACKAGE_SOURCE:-}"
 PACKAGE_VERSION="${PIAGENT_PACKAGE_VERSION:-}"
 RELEASE_CHANNEL="${PIAGENT_RELEASE_CHANNEL:-}"
-WITH_MCP=false
+WITH_MCP=true
 MCP_PRESET="core"
+MCP_PRESET_EXPLICIT=false
 WITH_SUBAGENTS=false
 SUBAGENTS_PRESET="safe"
 SUBAGENTS_MODEL_SCOPE="none"
@@ -123,7 +127,7 @@ detect_runtime_surface() {
       printf 'native-windows/%s (not release-gated; terminal helpers require Bash semantics)' "$arch_name"
       ;;
     *)
-      printf '%s/%s (outside v1.0.2 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.1.1 release matrix)' "$os_name" "$arch_name"
       ;;
   esac
 }
@@ -131,7 +135,7 @@ detect_runtime_surface() {
 warn_runtime_surface_if_needed() {
   local surface="$1"
   case "$surface" in
-    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.0.2 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.1 release matrix"*)
       echo "WARN: runtime surface is $surface." >&2
       echo "WARN: For team rollout, run piagent-doctor plus the project smoke/verify suite on this machine before relying on it." >&2
       ;;
@@ -275,9 +279,14 @@ while [[ $# -gt 0 ]]; do
       WITH_MCP=true
       shift
       ;;
+    --no-mcp)
+      WITH_MCP=false
+      shift
+      ;;
     --mcp-preset)
       require_value "$1" "${2:-}"
       MCP_PRESET="$2"
+      MCP_PRESET_EXPLICIT=true
       shift 2
       ;;
     --with-subagents)
@@ -328,6 +337,13 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+# A preset chosen alongside --no-mcp used to be accepted and then quietly
+# dropped, which reads as "the preset was applied".
+if [[ "$WITH_MCP" == false && "$MCP_PRESET_EXPLICIT" == true ]]; then
+  echo "FAIL: --mcp-preset has no effect with --no-mcp. Drop one of them." >&2
+  exit 2
+fi
+
 require_node_version
 CURRENT_RUNTIME_SURFACE="$(detect_runtime_surface)"
 warn_runtime_surface_if_needed "$CURRENT_RUNTIME_SURFACE"
@@ -438,7 +454,7 @@ if ! command -v pi >/dev/null 2>&1; then
   else
   echo "FAIL: pi is not on PATH." >&2
   echo "Install Pi first, then rerun this script." >&2
-    echo "Expected command on npm-based installs: npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.81.1" >&2
+    echo "Expected command on npm-based installs: npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0" >&2
   exit 1
   fi
 else
@@ -527,6 +543,8 @@ echo "  pi"
 echo "  /login"
 echo "  /model          # or Ctrl+L: select provider/model from Pi selector"
 echo "  /scoped-models  # optional: edit Ctrl+P model cycle scope"
-echo "  /mcp            # inspect MCP servers; authenticate Figma/GitHub only when needed"
+if [[ "$WITH_MCP" == true ]]; then
+  echo "  /mcp            # inspect MCP servers; authenticate Figma/GitHub only when needed"
+fi
 echo "  /subagents-doctor"
 echo "  /task Implement <task>  # parent may auto-delegate scout/planner/reviewer"

package/scripts/setup.sh

@@ -378,8 +378,13 @@ echo
 if [[ "$DO_GLOBAL" == true ]]; then
   ensure_pi_cli
   install_args=("$PLATFORM_ROOT/scripts/install-global.sh" "--package-source" "$PACKAGE_SOURCE")
+  # The opt-out has to be passed explicitly. The installer defaults MCP on, so
+  # saying nothing here would install it against the operator's choice; the
+  # flags below can stay one-sided only because the installer defaults them off.
   if [[ "$WITH_MCP" == true ]]; then
     install_args+=("--with-mcp" "--mcp-preset" "$MCP_PRESET")
+  else
+    install_args+=("--no-mcp")
   fi
   if [[ "$WITH_SUBAGENTS" == true ]]; then
     install_args+=("--with-subagents" "--subagents-preset" "$SUBAGENTS_PRESET" "--subagents-model-scope" "$SUBAGENTS_MODEL_SCOPE")

package/scripts/team-doctor.sh

@@ -137,7 +137,7 @@ function runtimeMatrixStatus() {
     surface: `${platform}/${arch}`,
     status: "outside-release-matrix",
     teamRolloutReady: false,
-    note: "This runtime is outside the documented v1.0.2 support matrix."
+    note: "This runtime is outside the documented v1.1.1 support matrix."
   };
 }
 

package/scripts/uninstall-global.sh

@@ -155,8 +155,11 @@ else
     fi
     # The MCP baseline and subagent config are shared files that the operator
     # may have edited after install, so they are reported rather than reset.
+    # Install writes the shared global scope; the Pi-global file is the override
+    # scope and is listed too, because an operator who used it will look there.
     echo "Left in place, review by hand if no longer wanted:"
-    echo "  $PI_AGENT_DIR/mcp.json"
+    echo "  ${XDG_CONFIG_HOME:-"${HOME}/.config"}/mcp/mcp.json   # written by install"
+    echo "  $PI_AGENT_DIR/mcp.json                               # Pi-global override scope, only if you created it"
     echo "  $PI_AGENT_DIR/extensions/subagent/config.json"
   fi
 fi