fix(connect): suggest a serve command that matches how you ran connect

apps/server/src/cli/connect.ts

@@ -46,6 +46,7 @@ import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
 import * as ExternalLauncher from "../process/externalLauncher.ts";
 import { readPersistedServerRuntimeState } from "../serverRuntimeState.ts";
 import { projectLocationFlags, resolveCliAuthConfig } from "./config.ts";
+import { resolveCliCommand } from "./invocation.ts";
 import {
   bootServiceLayer,
   offerServiceDuringOnboarding,
@@ -526,10 +527,11 @@ const connectLinkCommand = Command.make("link", {
         yield* Console.log("T3 Connect\n");
         const linked = yield* linkEnvironmentForConnect(flags);
         if (linked) {
+          const serveCommand = yield* resolveCliCommand("serve");
           yield* Console.log(
             flags.publishOnly
               ? `✓ Authorized${connectedAs(linked.identity)}\n\nNext\n  Start T3 to publish agent activity (no managed tunnel).`
-              : `✓ Authorized${connectedAs(linked.identity)}\n\nNext\n  Start the server with \`t3 serve\` to make this machine reachable.`,
+              : `✓ Authorized${connectedAs(linked.identity)}\n\nNext\n  Start the server with \`${serveCommand}\` to make this machine reachable.`,
           );
         }
       }),
@@ -691,10 +693,15 @@ export const connectCommand = Command.make("connect", {
         // Connect itself already succeeded; a boot-service failure must not
         // fail the command, just tell the user what happened and move on.
         const background = yield* recoverServiceOnboardingOffer(offerServiceDuringOnboarding);
+        if (background) {
+          yield* Console.log(
+            "\n✓ Background service ready\n\nT3 Code will stay reachable after you log out.",
+          );
+          return;
+        }
+        const serveCommand = yield* resolveCliCommand("serve");
         yield* Console.log(
-          background
-            ? "\n✓ Background service ready\n\nT3 Code will stay reachable after you log out."
-            : "\nNext\n  Start the server with `t3 serve` to make this machine reachable.",
+          `\nNext\n  Start the server with \`${serveCommand}\` to make this machine reachable.`,
         );
       }),
     ),

apps/server/src/cli/invocation.test.ts

@@ -0,0 +1,74 @@
+import { assert, it } from "@effect/vitest";
+
+import { detectCliRunner, formatCliCommand, suggestedPackageSpec } from "./invocation.ts";
+
+it("detects package runners from their cache entry paths", () => {
+  assert.equal(detectCliRunner("/home/theo/.npm/_npx/abc123/node_modules/t3/dist/bin.mjs"), "npx");
+  assert.equal(
+    detectCliRunner(
+      "C:\\Users\\theo\\AppData\\Local\\npm-cache\\_npx\\abc\\node_modules\\t3\\dist\\bin.mjs",
+    ),
+    "npx",
+  );
+  assert.equal(
+    detectCliRunner("/home/theo/.cache/pnpm/dlx/abc/node_modules/t3/dist/bin.mjs"),
+    "pnpm dlx",
+  );
+  assert.equal(
+    detectCliRunner("/home/theo/.local/share/pnpm/.pnpm/dlx/abc/node_modules/t3/dist/bin.mjs"),
+    "pnpm dlx",
+  );
+  assert.equal(
+    detectCliRunner(
+      "C:\\Users\\theo\\AppData\\Local\\pnpm-cache\\dlx\\abc\\node_modules\\t3\\dist\\bin.mjs",
+    ),
+    "pnpm dlx",
+  );
+  assert.equal(detectCliRunner("/home/theo/.bun/install/cache/t3@0.0.31/dist/bin.mjs"), "bunx");
+  assert.equal(detectCliRunner("/tmp/bunx-1000-t3@latest/node_modules/t3/dist/bin.mjs"), "bunx");
+  assert.equal(
+    detectCliRunner(
+      "C:\\Users\\theo\\AppData\\Local\\Temp\\bunx-0-t3@latest\\node_modules\\t3\\dist\\bin.mjs",
+    ),
+    "bunx",
+  );
+});
+
+it("treats stable installs as direct invocations", () => {
+  assert.isNull(detectCliRunner("/usr/local/lib/node_modules/t3/dist/bin.mjs"));
+  assert.isNull(detectCliRunner("/home/theo/Code/work/t3code/apps/server/dist/bin.mjs"));
+  assert.isNull(detectCliRunner("/home/theo/.t3/runtime/0.0.31/node_modules/t3/dist/bin.mjs"));
+  assert.isNull(detectCliRunner(""));
+});
+
+it("re-suggests the nightly channel only for nightly builds", () => {
+  assert.equal(suggestedPackageSpec("0.0.31-nightly.20260729"), "t3@nightly");
+  assert.equal(suggestedPackageSpec("0.0.31"), "t3");
+});
+
+it("formats serve suggestions to match the launching command", () => {
+  assert.equal(
+    formatCliCommand({
+      subcommand: "serve",
+      entryPath: "/home/theo/.npm/_npx/abc/node_modules/t3/dist/bin.mjs",
+      version: "0.0.31-nightly.20260729",
+    }),
+    "npx t3@nightly serve",
+  );
+  assert.equal(
+    formatCliCommand({
+      subcommand: "serve",
+      entryPath: "/tmp/bunx-1000-t3@latest/node_modules/t3/dist/bin.mjs",
+      version: "0.0.31",
+    }),
+    "bunx t3 serve",
+  );
+  assert.equal(
+    formatCliCommand({
+      subcommand: "serve",
+      entryPath: "/usr/local/lib/node_modules/t3/dist/bin.mjs",
+      version: "0.0.31-nightly.20260729",
+    }),
+    "t3 serve",
+  );
+});

apps/server/src/cli/invocation.ts

@@ -0,0 +1,75 @@
+import * as Effect from "effect/Effect";
+
+import { HostProcessArguments } from "@t3tools/shared/hostProcess";
+
+import packageJson from "../../package.json" with { type: "json" };
+
+export type CliRunner = "npx" | "pnpm dlx" | "bunx";
+
+/**
+ * How the CLI was launched, judged by where its entry script lives. Each
+ * package runner executes out of a distinctive cache/temp layout:
+ *
+ *   npx      ~/.npm/_npx/<hash>/node_modules/...
+ *   pnpm dlx ~/.cache/pnpm/dlx/..., $PNPM_HOME/.pnpm/dlx/...,
+ *            or %LOCALAPPDATA%/pnpm-cache/dlx/... on Windows
+ *   bunx     ~/.bun/install/cache/... or $TMPDIR/bunx-<uid>-<spec>/...
+ *
+ * Global installs and repo checkouts match none of these and return null.
+ * Detection is best-effort; callers must fail closed to a plain `t3` command.
+ */
+export function detectCliRunner(entryPath: string): CliRunner | null {
+  const path = entryPath.replaceAll("\\", "/");
+  if (path.includes("/_npx/")) {
+    return "npx";
+  }
+  if (
+    path.includes("/pnpm/dlx/") ||
+    path.includes("/.pnpm/dlx/") ||
+    path.includes("/pnpm-cache/dlx/")
+  ) {
+    return "pnpm dlx";
+  }
+  if (path.includes("/.bun/install/cache/") || path.includes("/bunx-")) {
+    return "bunx";
+  }
+  return null;
+}
+
+/**
+ * The `t3` package spec to suggest. The literal spec the user typed (e.g.
+ * `t3@nightly`) is resolved away before our process starts, so re-derive it
+ * from the running version: nightly builds re-suggest the nightly channel,
+ * anything else suggests the bare package.
+ */
+export function suggestedPackageSpec(version: string): string {
+  return version.includes("-nightly.") ? "t3@nightly" : "t3";
+}
+
+/**
+ * Render a `t3 <subcommand>` suggestion that matches how this process was
+ * launched, so copy/pasting it actually works: `npx t3 connect` suggests
+ * `npx t3 serve`, a global install suggests `t3 serve`, and a nightly build
+ * keeps the `@nightly` tag.
+ */
+export function formatCliCommand(input: {
+  readonly subcommand: string;
+  readonly entryPath: string;
+  readonly version: string;
+}): string {
+  const runner = detectCliRunner(input.entryPath);
+  if (runner === null) {
+    return `t3 ${input.subcommand}`;
+  }
+  return `${runner} ${suggestedPackageSpec(input.version)} ${input.subcommand}`;
+}
+
+/** `formatCliCommand` against this process's real entry path and version. */
+export const resolveCliCommand = (subcommand: string) =>
+  Effect.map(HostProcessArguments, (processArguments) =>
+    formatCliCommand({
+      subcommand,
+      entryPath: processArguments[1] ?? "",
+      version: packageJson.version,
+    }),
+  );