premanmcp 0.13.0 → 0.15.1

package/bin/integrations.js

@@ -14,8 +14,11 @@
  * hand, and no third-party credential ever touches the terminal.
  */
 
+import { describeCheckout, explainNoCheckout, resolveCheckout } from "./repo.js";
 import {
+  DEFAULT_BACKEND,
   assertOk,
+  backendUrl,
   callBackendJson,
   cliInvocation,
   frontendUrl,
@@ -58,10 +61,41 @@ export function connected(message) {
   process.stdout.write(`${MARK.ok()} ${message}\n`);
 }
 
+const OPENING_FRAMES = ["\u280b", "\u2819", "\u2839", "\u2838", "\u283c", "\u2834", "\u2826", "\u2827", "\u2807", "\u280f"];
+
+function showOpeningDesktop() {
+  const label = "Opening PreMan\u2026";
+  if (!process.stdout.isTTY) {
+    process.stdout.write(`${label}\n`);
+    return () => {};
+  }
+
+  let frame = 0;
+  const render = () => {
+    process.stdout.write(`\r\u001b[2K${OPENING_FRAMES[frame % OPENING_FRAMES.length]} ${label}`);
+    frame += 1;
+  };
+  render();
+  const timer = setInterval(render, 80);
+  if (typeof timer.unref === "function") timer.unref();
+
+  let stopped = false;
+  return () => {
+    if (stopped) return;
+    stopped = true;
+    clearInterval(timer);
+    process.stdout.write("\r\u001b[2K");
+  };
+}
+
+const INSTALLATIONS_URL = "https://github.com/settings/installations";
+
 function present(url, what) {
   process.stdout.write(`\n  ${url}\n\n`);
-  if (openUrl(url)) process.stdout.write(`Opened ${what} in your browser.\n`);
-  else process.stdout.write(`Open the link above to ${what}.\n`);
+  // A tab appearing is its own confirmation; saying so as well spends a line
+  // on what the customer is already looking at. It earns its place only when
+  // no tab opened and the link is the way through.
+  if (!openUrl(url)) process.stdout.write(`Open the link above to ${what}.\n`);
 }
 
 /**
@@ -265,9 +299,7 @@ export async function githubCommand(args) {
     {
       timeoutMs: Number(process.env.PREMAN_GITHUB_POLL_MS) || GITHUB_POLL_TIMEOUT_MS,
       hintAfterMs: 20000,
-      hint:
-        "Still nothing from GitHub. Picking at least one repository and confirming\n" +
-        "is what sends you back here.",
+      hint: "Still nothing from GitHub — confirm a repository to come back here.",
     }
   );
 
@@ -291,15 +323,12 @@ function githubHandOff(args, refresh) {
   if (installed) {
     return (
       `The App is installed, but no repositories are shared with it.\n` +
-      `  - Add some: https://github.com/settings/installations\n` +
-      `  - Then re-run '${cliInvocation()} github'.\n`
+      `  Add some at ${INSTALLATIONS_URL}, then re-run '${cliInvocation()} github'.\n`
     );
   }
   return (
-    `Nothing from GitHub yet — no need to wait here.\n` +
-    `  - Finish the install in the browser; it records itself when you confirm.\n` +
-    `  - Check it: ${frontendUrl(args)}  or  https://github.com/settings/installations\n` +
-    `  - Then re-run '${cliInvocation()} github'.\n`
+    `Nothing from GitHub yet. Finish the install in the browser — it records itself.\n` +
+    `  Then re-run '${cliInvocation()} github'.\n`
   );
 }
 
@@ -337,14 +366,25 @@ export async function slackCommand(args) {
 // The guided run
 // ---------------------------------------------------------------------------
 
-/** "yes" | "no" | "back" -- back only offered once there is somewhere to go. */
-async function askStep(question, { assumeYes, canGoBack }) {
-  if (assumeYes) return "yes";
-  const hint = canGoBack ? "[Y/n/b]" : "[Y/n]";
+/**
+ * "yes" | "no" | "back" -- back only offered once there is somewhere to go.
+ *
+ * `--yes` takes each step's own default rather than answering yes to all of
+ * them. One step needs that today and it is the expensive one: the desktop app
+ * defaults to no because it downloads a hundred-odd megabytes and writes to
+ * /Applications, and `onboard --yes` used to do exactly that, unattended, to
+ * someone who only meant "stop asking me questions". They have
+ * `preman install-desktop` when they want it.
+ */
+async function askStep(question, { assumeYes, canGoBack, defaultYes = true }) {
+  const fallback = defaultYes ? "yes" : "no";
+  if (assumeYes) return fallback;
+  const shown = defaultYes ? "Y/n" : "y/N";
+  const hint = canGoBack ? `[${shown}/b]` : `[${shown}]`;
   const answer = (await promptText(`${question} ${hint}: `)).trim().toLowerCase();
   if (canGoBack && (answer === "b" || answer === "back")) return "back";
-  if (answer === "" || answer === "y" || answer === "yes") return "yes";
-  return "no";
+  if (answer === "") return fallback;
+  return answer === "y" || answer === "yes" ? "yes" : "no";
 }
 
 /**
@@ -354,50 +394,238 @@ async function askStep(question, { assumeYes, canGoBack }) {
  * finish Slack today should still leave with AWS streaming, so a step that
  * throws is reported and the run continues rather than unwinding the ones that
  * already worked.
+ *
+ * The order is the argument. Setup used to open with a hundred-megabyte
+ * download and close with the repository, so the first thing PreMan did was ask
+ * for disk space and the last was ask about the code — and someone who quit
+ * halfway had a desktop app pointed at an empty account. Endpoints come first
+ * now because they are the only step that shows what PreMan is for, and every
+ * ask after it can name what it just found. The app goes last because it is the
+ * one thing here nobody needs.
+ *
+ * The steps themselves live in connect/guide.js, which is also what
+ * `preman connect --guide` runs. Two walks that asked the same questions in
+ * different words with different defaults was the thing worth deleting.
  */
 export async function onboardCommand(
   commandArgs,
-  { makeArgs, authenticateTerminal, installDesktop, openDesktopSignedIn }
+  { makeArgs, authenticateTerminal, installDesktop, openDesktopSignedIn, installPushHook }
 ) {
   const args = makeArgs(commandArgs);
   const assumeYes = args.has("--yes");
 
+  // Imported at call time, not at the top: guide.js imports this module for MARK
+  // and the three integration commands, so a static edge back would close the
+  // cycle. By the time anyone runs onboard, this module is fully evaluated.
+  const { desktopPrecheck, desktopQuestion, desktopSkipped, discoverEndpoints, runDesktopInstall } =
+    await import("./connect/guide.js");
+  const { resolveAgentToDrive } = await import("./connect/agents.js");
+
   process.stdout.write("PreMan setup\n\n");
 
+  // Which PreMan this is talking to is invisible until the very last line,
+  // and a stored login from a local run silently redirects the whole walk:
+  // the account is created in a database nobody else can see, and the GitHub
+  // App redirects to the real callback, so the install never arrives and the
+  // wait looks like GitHub being slow. Production says nothing, because there
+  // is nothing to warn about; anything else is worth one line up front.
+  const target = backendUrl(args);
+  if (target !== DEFAULT_BACKEND) {
+    process.stdout.write(`${MARK.skip()} Using ${target}, not ${DEFAULT_BACKEND}.\n\n`);
+  }
+
   const creds = await authenticateTerminal(args);
   connected(`Signed in as ${creds.user_email || "your account"}.`);
 
+  // Asked once, here, because the repository step and the notice that stands in
+  // for it both need the answer and it costs a round trip. It is reported later,
+  // in the repository's own slot in the walk, so everything about this checkout
+  // is said in one place rather than before PreMan has looked at the code.
+  const checkout = await resolveCheckout(args, resolveApiKey(args));
+
   const steps = [
     {
-      name: "PreMan app",
-      question: "Install the PreMan app and open it signed in?",
+      // No question. Everything below is a decision about code PreMan has not
+      // read yet, and asking permission to look was how people ended up with an
+      // account, an app and nothing in either. It skips a repo that is already
+      // mapped, prints a brief when no agent can be driven, and never throws.
+      name: "Endpoints",
+      run: async () => {
+        // `interactive: false` on purpose. Getting started does not ask which
+        // coding agent you use -- that question belongs to `preman connect`,
+        // and putting a three-way picker in front of someone ninety seconds
+        // into their first run is how this walk got long in the first place.
+        // An unambiguous machine still gets its agent driven; anything less
+        // clear prints the brief and moves on.
+        const agent = await resolveAgentToDrive({
+          agent: args.value("--agent", ""),
+          interactive: false,
+        });
+        const counts = await discoverEndpoints(args, agent, args.value("--name", "preman"), {
+          handOffBrief: false,
+        });
+        return { state: counts.registered ? "done" : "skipped", counts };
+      },
+    },
+  ];
+
+  // Asking "Connect GitHub?" hands someone a chore with no visible end; asking
+  // "Connect acme/api?" is the entire decision, and this is the repository they
+  // ran the command in. It sits after discovery so it can say what is at stake
+  // in this repo rather than in the abstract, and because this is the step that
+  // decides whether a fix from this code can ever open a pull request — leaving
+  // it for later is leaving them to find the gap in a fix that produced nothing.
+  if (checkout?.supported && !checkout.match) {
+    steps.push({
+      name: "This repository",
+      question: (previous) => {
+        const found = previous.get("Endpoints")?.counts?.registered || 0;
+        if (!found) return `Connect ${checkout.slug} so fixes here can open pull requests?`;
+        return `Connect ${checkout.slug} so PreMan can open pull requests for the ${found} endpoint${found === 1 ? "" : "s"} it just mapped?`;
+      },
       run: async () => {
-        const installed = await installDesktop([...commandArgs]);
-        if (installed?.state === "unsupported") {
-          // Not a failure: the download link has already been printed, and the
-          // account this step exists to create is finished either way.
-          process.stdout.write("Sign in there with the account you just used.\n");
+        await githubCommand(args);
+        // Finishing the App install is not the same as this repository being
+        // connected: the install shares whichever repositories the customer
+        // picked, which may not include this one. Re-asking is the difference
+        // between "GitHub is connected" and the claim actually made above.
+        const after = await resolveCheckout(args, resolveApiKey(args), {
+          slug: checkout.slug,
+        });
+        if (after?.match) {
+          process.stdout.write(describeCheckout(after));
           return;
         }
-        process.stdout.write("Opening PreMan\u2026\n");
-        const opened = await openDesktopSignedIn(creds);
-        if (opened.state === "opened-signed-in") {
-          process.stdout.write("Opened PreMan, signed in as this account.\n");
-        } else if (opened.state === "not-installed") {
+        process.stdout.write(
+          `${checkout.slug} is still not shared. Add it at ${INSTALLATIONS_URL}.\n`
+        );
+      },
+    });
+  } else {
+    // Already connected, or there is no repository here to connect. Neither is a
+    // question, but both are the fact that decides whether a fix from this code
+    // can ever open a pull request, so the walk says it out loud in the slot
+    // where the question would have been. It used to say nothing at all when
+    // there was no checkout, which left people to discover the gap much later,
+    // from a fix task that finished and produced no pull request.
+    const already = describeCheckout(checkout);
+    steps.push({
+      name: "This repository",
+      run: () => {
+        if (already) {
+          process.stdout.write(already);
+          return { state: checkout?.match ? "done" : "skipped" };
+        }
+        process.stdout.write(`${MARK.skip()} ${explainNoCheckout()}\n`);
+        process.stdout.write(
+          `  Run '${cliInvocation()} github' from your API repo to connect it.\n`
+        );
+        return { state: "skipped" };
+      },
+    });
+  }
+
+  steps.push({
+    name: "Push checks",
+    question: "Check your endpoints on every git push in this repo?",
+    run: async () => {
+      let result;
+      try {
+        result = installPushHook(args);
+      } catch (err) {
+        // Onboarding from a home directory or a plain folder is ordinary, and
+        // it costs the customer nothing: the account is already done, and the
+        // hook is one command away inside the repo they meant.
+        if (/not inside a git repository/i.test(err.message)) {
           process.stdout.write(
-            "PreMan is not in /Applications yet \u2014 open it once installed and sign in.\n"
+            "Not a git repository, so there is nothing to hook here.\n" +
+              `Run '${cliInvocation()} hook install' inside your API repo.\n`
           );
-        } else {
-          // Either the session could not be handed over or this app is too old to
-          // take it up. Say so rather than let the customer wonder why they are
-          // looking at a login screen.
-          process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
+          return;
         }
-      },
+        throw err;
+      }
+
+      // A hook we refused to write is not a failure of setup, but saying
+      // nothing would leave the customer believing their pushes are checked.
+      if (result.action === "conflict" || result.action === "unproven") {
+        process.stdout.write(`Not installed: ${result.detail}\n  ${result.path}\n`);
+        return;
+      }
+
+      // One line, like every other step. The pinned invocation and the skip
+      // variable are real information and both are a `hook status` away;
+      // spelling them out here buried the one fact that changes a decision.
+      connected(`Pre-push hook ${result.action} — every push is checked, never blocked.`);
+      if (result.detail) process.stdout.write(`  ${result.detail}\n`);
     },
-    // GitHub, AWS and Slack are deliberately not here. Starting out is an account
-    // and the app; each integration is its own command for whenever it is wanted.
-  ];
+  });
+
+  // Last, defaulted to no, and only where there is something to install. The
+  // guards run out here rather than inside the step so a Linux user is not
+  // asked a macOS question and someone who already has the app is not asked to
+  // download it again — both of which happened when the check came after.
+  const desktop = desktopPrecheck(args);
+  if (desktop?.state === "installed") {
+    steps.push({
+      name: "Desktop app",
+      run: () => {
+        process.stdout.write(`${MARK.ok()} PreMan desktop app already installed.\n`);
+      },
+    });
+  } else if (!desktop) {
+    steps.push({
+      name: "Desktop app",
+      question: desktopQuestion(args),
+      // `--desktop` is how an unattended run opts in, since `--yes` gives every
+      // step its own default and this step's default is no.
+      defaultYes: args.has("--desktop"),
+      onSkip: desktopSkipped,
+      run: () =>
+        runDesktopInstall(args, {
+          // Onboarding installs *and* hands the fresh session over, so the app
+          // opens already signed in rather than on a login screen for the
+          // account created ninety seconds ago.
+          install: async () => {
+            let stopOpening = null;
+            try {
+              const installed = await installDesktop([...commandArgs], {
+                onInstalled: () => {
+                  stopOpening ??= showOpeningDesktop();
+                },
+              });
+              if (installed?.state === "unsupported") {
+                // Not a failure: the download link has already been printed, and
+                // the account this step exists to create is finished either way.
+                process.stdout.write("Sign in there with the account you just used.\n");
+                return installed;
+              }
+              stopOpening ??= showOpeningDesktop();
+              // The same --dest the install honoured, or the launch would look
+              // for the app somewhere it was never copied to.
+              const destination = args.value("--dest", "/Applications");
+              const opened = await openDesktopSignedIn(creds, { destination });
+              stopOpening();
+              if (opened.state === "opened-signed-in") {
+                process.stdout.write("Opened PreMan, signed in as this account.\n");
+              } else if (opened.state === "not-installed") {
+                process.stdout.write(
+                  `PreMan is not in ${destination} yet \u2014 open it once installed and sign in.\n`
+                );
+              } else {
+                // Either the session could not be handed over or this app is too
+                // old to take it up. Say so rather than let the customer wonder
+                // why they are looking at a login screen.
+                process.stdout.write("Opened PreMan \u2014 sign in with the account you just used.\n");
+              }
+              return installed;
+            } finally {
+              stopOpening?.();
+            }
+          },
+        }),
+    });
+  }
 
   // Outcome per step rather than three lists, so revisiting a step replaces its
   // result instead of recording it twice.
@@ -411,23 +639,39 @@ export async function onboardCommand(
     const step = steps[i];
     process.stdout.write(`\n── ${step.name} ──\n`);
 
-    const choice = await askStep(step.question, { assumeYes, canGoBack: i > 0 });
-    if (choice === "back") {
-      // Drop the result we are about to redo, or the summary would report the
-      // stale outcome of a step the customer chose to revisit.
-      outcome.delete(steps[i - 1].name);
-      i -= 1;
-      continue;
-    }
-    if (choice === "no") {
-      outcome.set(step.name, { state: "skipped" });
-      i += 1;
-      continue;
+    if (step.question) {
+      // "back" goes to the last step that asked something, not simply to the
+      // previous one: landing on a step with no question would re-run it and
+      // return straight here, which is not what typing b asked for.
+      const earlier = steps.slice(0, i).reduce((last, s, idx) => (s.question ? idx : last), -1);
+      // Late-bound so a question can name what an earlier step found. "Connect
+      // this repo?" is a different question once PreMan can say what is in it.
+      const question = typeof step.question === "function" ? step.question(outcome) : step.question;
+      const choice = await askStep(question, {
+        assumeYes,
+        canGoBack: earlier >= 0,
+        defaultYes: step.defaultYes ?? true,
+      });
+      if (choice === "back") {
+        // Drop the result we are about to redo, or the summary would report the
+        // stale outcome of a step the customer chose to revisit.
+        outcome.delete(steps[earlier].name);
+        i = earlier;
+        continue;
+      }
+      if (choice === "no") {
+        step.onSkip?.();
+        outcome.set(step.name, { state: "skipped" });
+        i += 1;
+        continue;
+      }
     }
 
     try {
-      await step.run();
-      outcome.set(step.name, { state: "done" });
+      // A step that caught its own failure and already explained it says so, and
+      // is not summarised as done; anything else that returns is taken as done.
+      const reported = await step.run();
+      outcome.set(step.name, { state: "done", ...(reported || {}) });
     } catch (err) {
       // Report and carry on: a failed Slack install must not cost the customer
       // the AWS connection they just finished.
@@ -451,13 +695,18 @@ export async function onboardCommand(
 
 export const INTEGRATIONS_HELP = `
 Setup options:
-  preman onboard              Create or sign in to an account, then install the
-                              PreMan app and open it signed in
+  preman onboard              Sign in, map this repo's endpoints, connect it for
+                              pull requests, and check the endpoints you touch on
+                              every git push. Offers the desktop app at the end
   preman aws                  Connect an AWS account and stream a log group
   preman github               Install the PreMan GitHub App
   preman slack                Add PreMan to a Slack workspace
 
-  --yes                       Accept every step without prompting (onboard)
+  --yes                       Take each step's default without prompting. The
+                              desktop app defaults to no, so --yes never
+                              downloads it (onboard)
+  --desktop                   Install the desktop app without asking (onboard)
+  --no-desktop                Do not offer the desktop app at all (onboard)
   b at any onboard prompt     Go back to the previous step
   --account <id>              AWS account id, skips the prompt
   --region <region>           AWS region for log groups. Defaults to us-east-1

package/bin/link.js

@@ -0,0 +1,207 @@
+/**
+ * The clickable PreMan line a push leaves behind.
+ *
+ * A terminal hyperlink is an OSC 8 escape wrapping a label, so the whole
+ * decision about *where a click lands* has to be made here, before anything is
+ * printed. There is no callback: the hook writes bytes and exits, and seconds
+ * later the terminal hands whatever URL it was given to the OS. That is why
+ * this module chooses a scheme rather than opening anything — an https link
+ * reaches the browser and a `preman://` link reaches the desktop app, and the
+ * only chance to pick between them is at print time.
+ *
+ * Deliberately not `openPlayground()` from desktop.js, which answers the same
+ * "desktop or web" question by spawning `open -a PreMan`. Stealing focus during
+ * a `git push` is exactly the behaviour that gets a tool uninstalled.
+ */
+
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import { desktopAppInstalled, installedAppPath } from "./desktop.js";
+import { DEFAULT_FRONTEND, frontendUrl } from "./shared.js";
+
+const DIM = "\u001b[2m";
+const RESET = "\u001b[0m";
+
+/**
+ * The brand palette, spelled once per colour depth.
+ *
+ * Basic ANSI green is whatever the reader's theme decided green means, which on
+ * a solarized or gruvbox scheme is not our green at all. The 24-bit values are
+ * the dashboard's own (`rgba(180, 215, 94)` for a pass, `rgba(227, 111, 102)`
+ * for a failure); the 256-colour indices are the nearest cube entries, 149 being
+ * rgb(175,215,95) and 167 rgb(215,95,95).
+ */
+export const PASS = { rgb: [180, 215, 94], x256: 149, basic: 32 };
+export const FAIL = { rgb: [227, 111, 102], x256: 167, basic: 31 };
+
+/**
+ * The strongest colour escape this stream will actually render.
+ *
+ * `getColorDepth()` is Node's own answer and already reads COLORTERM, TERM and
+ * FORCE_COLOR, so there is nothing to sniff by hand. It only exists on a real
+ * tty.WriteStream, and a truecolor sequence sent somewhere that cannot decode it
+ * prints as literal text -- hence the conservative default for anything else.
+ */
+export function paintTone(tone, stream) {
+  const depth = typeof stream.getColorDepth === "function" ? stream.getColorDepth() : 4;
+  if (depth >= 24) return `\u001b[38;2;${tone.rgb.join(";")}m`;
+  if (depth >= 8) return `\u001b[38;5;${tone.x256}m`;
+  return `\u001b[${tone.basic}m`;
+}
+
+/** The dashboard view a push link points at. */
+export const RUN_ROUTE = "/observability/endpoints";
+
+/**
+ * The first desktop build that reads `route` out of a `preman://open` URL.
+ *
+ * The contract PreMan-Desktop is expected to honour from this version on:
+ *
+ *     preman://open?source=push&route=%2Fobservability%2Fendpoints%3Fbatch%3D<uuid>
+ *
+ * `route` is one URL-encoded value holding a path and its query, to be navigated
+ * to after the window is raised.
+ *
+ * Older builds treat any `preman://open?…` as "bring the window forward" and
+ * ignore the query, so without this gate a link would raise a window on some
+ * unrelated view and look broken. Falling back to https costs a browser tab and
+ * always works, which is why an unreadable bundle resolves the same way.
+ */
+export const MIN_ROUTE_VERSION = "0.4.0";
+
+/** Numeric compare of dotted versions. Negative when `a` is older than `b`. */
+export function compareVersions(a, b) {
+  const parse = (value) => String(value || "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+  const left = parse(a);
+  const right = parse(b);
+  for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+    const diff = (left[i] || 0) - (right[i] || 0);
+    if (diff !== 0) return diff;
+  }
+  return 0;
+}
+
+/** CFBundleShortVersionString of the installed app, or "". */
+export function installedDesktopVersion(destination = "/Applications") {
+  try {
+    const plist = path.join(installedAppPath(destination), "Contents", "Info.plist");
+    const match = /<key>CFBundleShortVersionString<\/key>\s*<string>([^<]+)<\/string>/.exec(
+      readFileSync(plist, "utf8")
+    );
+    return match ? match[1].trim() : "";
+  } catch {
+    // Not installed, or a bundle we cannot read. Either way: not routable.
+    return "";
+  }
+}
+
+export function desktopSupportsRouting(destination = "/Applications") {
+  const version = installedDesktopVersion(destination);
+  return Boolean(version) && compareVersions(version, MIN_ROUTE_VERSION) >= 0;
+}
+
+/**
+ * Which surface a click should reach, and the URL that gets it there.
+ *
+ * `webUrl` is returned alongside `href` in every branch because it is always
+ * printed as the plain-text fallback -- macOS Terminal.app does not support OSC
+ * 8, and a `preman://` string is useless to anyone reading a captured log.
+ *
+ * A non-default frontend always resolves to the browser. A local Vite dev
+ * server is a browser thing, and the desktop app ships its own bundled UI, so
+ * handing it a localhost route would open the wrong build.
+ */
+export function resolveRunSurface(args, { batchId = "", destination = "/Applications" } = {}) {
+  const base = frontendUrl(args);
+  const route = batchId ? `${RUN_ROUTE}?batch=${encodeURIComponent(batchId)}` : RUN_ROUTE;
+  const webUrl = `${base}${route}`;
+
+  if (base !== DEFAULT_FRONTEND) return { href: webUrl, webUrl, surface: "web-local" };
+  if (desktopAppInstalled(destination) && desktopSupportsRouting(destination)) {
+    return {
+      href: `preman://open?source=push&route=${encodeURIComponent(route)}`,
+      webUrl,
+      surface: "desktop",
+    };
+  }
+  return { href: webUrl, webUrl, surface: "web" };
+}
+
+/** Wrap `label` so supporting terminals make it clickable. */
+export function terminalHyperlink(url, label) {
+  return `\u001b]8;;${url}\u001b\\${label}\u001b]8;;\u001b\\`;
+}
+
+/**
+ * A clickable headline over its own plain-text URL.
+ *
+ * Escapes are dropped entirely when stdout is not a TTY: hook output is
+ * routinely piped, captured by a GUI git client, or read back in CI, and a
+ * literal `\u001b]8;;` in a log file is worse than a plain URL. `NO_COLOR`
+ * suppresses only the colour, per the convention -- the hyperlink is not
+ * decoration.
+ *
+ * A `tone` of null dims the label instead of tinting it. The palette carries a
+ * verdict, so spending it on a line that merely points somewhere would make
+ * "here is your dashboard" look like "your push passed".
+ */
+function renderLinkBlock({ href, webUrl, label, tone = null, stream }) {
+  const rich = Boolean(stream.isTTY);
+  const coloured = rich && !process.env.NO_COLOR;
+
+  const tinted = coloured
+    ? `${tone ? paintTone(tone, stream) : DIM}${label}${RESET}`
+    : label;
+  const headline = rich ? terminalHyperlink(href, tinted) : label;
+  const fallback = coloured ? `${DIM}  ${webUrl}${RESET}` : `  ${webUrl}`;
+
+  return `${headline}\n${fallback}`;
+}
+
+/**
+ * The two-line block printed after a push, or "" when there is nothing to link
+ * to.
+ */
+export function formatPushLink({
+  batchId = "",
+  state = "passed",
+  args,
+  stream = process.stdout,
+  destination = "/Applications",
+} = {}) {
+  if (!batchId) return "";
+
+  const { href, webUrl } = resolveRunSurface(args, { batchId, destination });
+  const failed = state === "failed";
+  const label = `\u25c6 PreMan \u00b7 check #${String(batchId).slice(0, 6)} ${
+    failed ? "found problems" : "passed"
+  } \u2014 view results`;
+
+  return renderLinkBlock({
+    href,
+    webUrl,
+    label,
+    tone: failed ? FAIL : PASS,
+    stream,
+  });
+}
+
+/**
+ * The same block for a run that does not exist: no batch, no verdict, just the
+ * endpoints view.
+ *
+ * This is what a push prints when there was nothing to verify. A skip that ends
+ * in prose leaves the reader with a state they cannot see and no way to look --
+ * and the reason is nearly always something the dashboard shows plainly, like an
+ * inventory that is still being discovered.
+ */
+export function formatDashboardLink({
+  args,
+  label = "\u25c6 PreMan \u00b7 view endpoints",
+  stream = process.stdout,
+  destination = "/Applications",
+} = {}) {
+  const { href, webUrl } = resolveRunSurface(args, { destination });
+  return renderLinkBlock({ href, webUrl, label, stream });
+}