@pipeshub-ai/mcp 2.3.1 → 2.3.3

package/src/cli/init-qm.ts

@@ -89,10 +89,147 @@ RUN npm install -g "@pipeshub-ai/mcp@${version}" \\
 # ----------------------------------------------------------------------------
 `;
 
+/**
+ * Strip JSONC comments without mangling `//` inside string values.
+ *
+ * The naive version eats the second slash of `"https://example.com"` and turns
+ * a valid config into a parse error, which is a maddening failure to debug in
+ * a file the operator did not know we read.
+ */
+export function stripJsonComments(src: string): string {
+  let out = "";
+  let inString = false;
+  let inLine = false;
+  let inBlock = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (inLine) {
+      if (c === "\n") { inLine = false; out += c; }
+      continue;
+    }
+    if (inBlock) {
+      if (c === "*" && next === "/") { inBlock = false; i++; }
+      continue;
+    }
+    if (inString) {
+      out += c;
+      if (c === "\\") { out += next ?? ""; i++; continue; }
+      if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') { inString = true; out += c; continue; }
+    if (c === "/" && next === "/") { inLine = true; i++; continue; }
+    if (c === "/" && next === "*") { inBlock = true; i++; continue; }
+    out += c;
+  }
+  return out;
+}
+
+/**
+ * Drop trailing commas before `}` or `]`. JSONC allows them and hand-edited
+ * configs collect them; `JSON.parse` does not. Without this a stray comma makes
+ * the config unreadable, which fails open and writes the Dockerfile we were
+ * trying not to write.
+ */
+export function dropTrailingCommas(src: string): string {
+  let out = "";
+  let inString = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (inString) {
+      out += c;
+      if (c === "\\") { out += src[i + 1] ?? ""; i++; continue; }
+      if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') { inString = true; out += c; continue; }
+    if (c === ",") {
+      let j = i + 1;
+      while (j < src.length && /\s/.test(src[j] as string)) j++;
+      if (src[j] === "}" || src[j] === "]") continue; // drop it
+    }
+    out += c;
+  }
+  return out;
+}
+
+export interface DeploymentShape {
+  target?: string | undefined;
+  backend?: string | undefined;
+}
+
+/**
+ * Read `target` and `sandbox.backend` from the operator's existing
+ * qm.config.jsonc. Returns null when there is no readable config — a fresh
+ * directory, or a file we cannot parse. Never throws: this only decides how
+ * much to scaffold, and a config we cannot read must not stop the scaffold.
+ */
+export async function readDeploymentShape(
+  dest: string,
+): Promise<DeploymentShape | null> {
+  try {
+    const raw = await readFile(join(dest, "qm.config.jsonc"), "utf8");
+    const cfg = JSON.parse(dropTrailingCommas(stripJsonComments(raw))) as {
+      target?: unknown;
+      sandbox?: { backend?: unknown };
+    };
+    const target = typeof cfg.target === "string" ? cfg.target : undefined;
+    const backend = typeof cfg.sandbox?.backend === "string"
+      ? cfg.sandbox.backend
+      : undefined;
+    if (!target && !backend) return null;
+    return { target, backend };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why a custom sandbox image cannot boot for this deployment, or null when it
+ * can. A reason rather than a boolean so the report can never describe a
+ * deployment as something it is not.
+ *
+ * `backend` is what decides where sandboxes run, not `target`: the CLI requires
+ * `"backend": "aws"` to have `target: "aws"` but not the reverse, so an AWS
+ * control plane running Sprites sandboxes is a supported and different thing
+ * from Lambda MicroVMs (`config.js:1106-1112`).
+ *
+ * This describes QM as it behaves today. If yc-software/qm#272 is fixed so
+ * Sprites boot a published image, the Sprites case here stops being true.
+ */
+export type ImageSkipReason = "sprites-ignores-image" | "aws-microvm" | null;
+
+export function imageSkipReason(shape: DeploymentShape | null): ImageSkipReason {
+  if (!shape) return null;
+  // Lambda MicroVMs have no install mechanism at all (qm#350).
+  if (shape.backend === "aws") return "aws-microvm";
+  // Sprites boot the stock base and ignore a published image (qm#272).
+  if (shape.backend === "sprites" || shape.target === "fly") {
+    return "sprites-ignores-image";
+  }
+  // An AWS target with no backend declared cannot run agents yet; skip rather
+  // than write a file whose fate depends on a choice not made.
+  if (shape.target === "aws") return "sprites-ignores-image";
+  return null;
+}
+
+/**
+ * Whether to scaffold a Dockerfile. Unknown shapes scaffold as before:
+ * guessing wrong in that direction removes a file someone needs.
+ */
+export function customImageBoots(shape: DeploymentShape | null): boolean {
+  return imageSkipReason(shape) === null;
+}
+
 export interface InitResult {
   written: string[];
   skipped: string[];
-  dockerfileAction: "created" | "appended" | "manual";
+  dockerfileAction: "created" | "appended" | "manual" | "skipped-unusable";
+  shape: DeploymentShape | null;
+  skipReason: ImageSkipReason;
+  /** A Dockerfile an earlier version already wrote, on a deploy that cannot use it. */
+  staleDockerfile: boolean;
   version: string;
   configFragment: string;
 }
@@ -112,6 +249,7 @@ export async function initQm(
 
   const version = await packageVersion(root);
   const dest = resolve(targetDir);
+  const shape = await readDeploymentShape(dest);
   const written: string[] = [];
   const skipped: string[] = [];
 
@@ -133,7 +271,17 @@ export async function initQm(
   // has no PipesHub block yet, and otherwise leave it entirely alone.
   const dockerfile = join(dest, "sandbox", "Dockerfile");
   let dockerfileAction: InitResult["dockerfileAction"];
-  if (!await exists(dockerfile)) {
+  const skipReason = imageSkipReason(shape);
+  // An earlier version wrote this unconditionally. Leaving it is not neutral:
+  // upcoming QM validation rejects it outright, so the operator needs telling.
+  // Not deleted here — it is their file and may carry their own build steps.
+  let staleDockerfile = false;
+  if (skipReason !== null) {
+    // Deliberately not written. The skill installs the CLI on first use, which
+    // is the path that actually runs on these deployments.
+    staleDockerfile = await exists(dockerfile);
+    dockerfileAction = "skipped-unusable";
+  } else if (!await exists(dockerfile)) {
     await copyFile(join(bundle, "sandbox", "Dockerfile"), dockerfile);
     // Restamp the pin so it matches the version actually installed.
     const body = await readFile(dockerfile, "utf8");
@@ -157,9 +305,8 @@ export async function initQm(
     }
   }
 
-  // Do not swallow this. The fragment carries the `sandbox.env` block the
-  // operator must merge in, so reporting a successful init without it leaves
-  // them with a scaffold that cannot reach PipesHub and no sign of why.
+  // Do not swallow this. The fragment is part of the bundle contract; a
+  // successful init that cannot read it means the package was assembled wrong.
   const fragmentPath = join(bundle, "qm.config.fragment.jsonc");
   let configFragment: string;
   try {
@@ -171,7 +318,16 @@ export async function initQm(
     );
   }
 
-  return { written, skipped, dockerfileAction, version, configFragment };
+  return {
+    written,
+    skipped,
+    dockerfileAction,
+    version,
+    configFragment,
+    shape,
+    skipReason,
+    staleDockerfile,
+  };
 }
 
 export function renderInitReport(dest: string, r: InitResult): string {
@@ -183,6 +339,37 @@ export function renderInitReport(dest: string, r: InitResult): string {
   for (const f of r.skipped) lines.push(`  kept    ${f}  (already existed — use --force to replace)`);
   lines.push("");
 
+  if (r.dockerfileAction === "skipped-unusable") {
+    if (r.skipReason === "aws-microvm") {
+      lines.push("No sandbox/Dockerfile was written: AWS Lambda MicroVM sandboxes");
+      lines.push("have no way to install a binary, so the file could never run.");
+    } else {
+      lines.push("No sandbox/Dockerfile was written: Fly Sprites boot the stock");
+      lines.push("image and ignore a published one, so the file would look like the");
+      lines.push("install path while never running.");
+    }
+    lines.push("The skill installs the CLI on first use instead — that is the line");
+    lines.push("that actually executes, and it needs nothing from you.");
+    lines.push("");
+  }
+
+  if (r.staleDockerfile) {
+    lines.push("ACTION NEEDED: sandbox/Dockerfile already exists here, written by an");
+    lines.push("earlier version. This deployment cannot use it, and upcoming QM");
+    lines.push("validation rejects it rather than ignoring it — `qm check` will fail");
+    lines.push("with an error naming that file. Delete it, or remove the PipesHub");
+    lines.push("install block if the rest of it is yours.");
+    lines.push("");
+  }
+
+  if (r.skipReason === "aws-microvm") {
+    lines.push("Heads up on AWS: with Lambda MicroVM sandboxes the CLI cannot be");
+    lines.push("installed at all (yc-software/qm#350). The tool's guidance, network");
+    lines.push("allowlist, and approval rules still apply, but the binary will be");
+    lines.push("missing. The sprites backend is what this bundle is tested against.");
+    lines.push("");
+  }
+
   if (r.dockerfileAction === "appended") {
     lines.push("Appended the install block to your existing sandbox/Dockerfile.");
   } else if (r.dockerfileAction === "manual") {
@@ -195,20 +382,22 @@ export function renderInitReport(dest: string, r: InitResult): string {
   lines.push("");
   lines.push("Two things left to do:");
   lines.push("");
-  lines.push("1. Set your PipesHub origin in qm.config.jsonc. It must be a PUBLIC");
-  lines.push("   HTTPS address — QM sandboxes do not run on your machine, so");
-  lines.push("   localhost and LAN addresses are unreachable from them:");
+  lines.push("1. Set `egress` in sandbox/tools/pipeshub/tool.json to your PipesHub");
+  lines.push("   hostname (no scheme, no path). It must be reachable over public HTTPS");
+  lines.push("   — QM sandboxes do not run on your machine, so localhost is unreachable.");
   lines.push("");
-  lines.push('     "sandbox": {');
-  lines.push('       "env": { "PIPESHUB_BASE_URL": "https://pipeshub.your-company.com" }');
-  lines.push("     }");
+  lines.push("2. Each person adds two personal keychain entries (service: pipeshub):");
+  lines.push("     PIPESHUB_TOKEN     → their PAT (never paste it into chat)");
+  lines.push("     PIPESHUB_BASE_URL  → public HTTPS origin, no /mcp path");
+  lines.push("   Do NOT put a token in sandbox.secretEnv (org-wide). Do NOT rely on");
+  lines.push("   sandbox.env for the URL — it does not reach the sandbox.");
   lines.push("");
-  lines.push("   Do NOT put anyone's token in sandbox.secretEnv — that is org-wide and");
-  lines.push("   would hand one person's credential to everybody. Each person adds");
-  lines.push("   their own to their own keychain (service: pipeshub, kind: env).");
+  lines.push("Then:  qm check && qm up");
   lines.push("");
-  lines.push("2. Set `egress` in sandbox/tools/pipeshub/tool.json to your hostname,");
-  lines.push("   then run:  qm check && qm sandbox publish && qm up");
+  if (r.dockerfileAction !== "skipped-unusable") {
+    lines.push("On Sprites, `qm sandbox publish` does not put pipeshub on PATH.");
+    lines.push("The skill installs the CLI on first use.");
+  }
   return lines.join("\n");
 }
 

package/src/cli/pipeshub.ts

@@ -244,13 +244,14 @@ async function run(argv: string[]): Promise<number> {
 
   if (origin === null) {
     // Report the missing credential too when both are absent. Otherwise a
-    // person whose actual problem is "I never added my token" is told about an
-    // admin-level setting, and goes looking in the wrong place.
+    // person whose actual problem is "I never added my token" is told about a
+    // missing URL, and goes looking in the wrong place.
     const alsoNoToken = token === null
       ? " Your PipesHub credential is also missing ($PIPESHUB_TOKEN is unset)."
       : "";
     throw new CliError(
-      "PIPESHUB_BASE_URL is not set — an admin sets it once for the deployment."
+      "PIPESHUB_BASE_URL is not set — it must reach the sandbox as an env var "
+        + "(keychain or org service credential, not sandbox.env)."
         + alsoNoToken
         + " Run 'pipeshub auth connect-help' for the steps.",
       EXIT.USAGE,

package/src/mcp-server/tools/pipeshubChat.ts

@@ -56,7 +56,7 @@ const args = {
       + "Only meaningful on the FIRST turn (when starting a new conversation).",
   ),
   modelKey: z.string().optional().describe(
-    "Model id to use (from `pipeshub_sources` `models[*].modelKey`). "
+    "Model id to use (from `pipeshub_sources` `llmModels[*].modelKey`). "
       + "Defaults to the org's default LLM.",
   ),
   modelName: z.string().optional(),