@mutmutco/installer-launcher 1.2.5 → 1.3.0

package/README.md

@@ -21,6 +21,7 @@ launcher status [--json]                            read-only: launcher, payload
 launcher doctor                                     launcher report (no network), then the payload's doctor
 launcher autoupdate on|off|status                   hourly per-user schedule (hidden via wscript on Windows)
 launcher <verb> [args…]                             forwarded untouched when payload.json declares it
+launcher [-p …|--model …]                           no verb: starts the product's session; leading flags the launcher does not own pass through
 launcher --run <file> [args…]                       run a payload ESM file with the launcher's own runtime
 launcher --version                                  `<bin> <payload version> (launcher <version>)`
 ```

package/dist/launcher.js

@@ -677,9 +677,9 @@ async function installAcquisition(dir, candidate, version, acquisition, options)
 
 // src/index.ts
 import { spawn as spawn2, spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync8, readFileSync as readFileSync8, statSync, mkdtempSync as mkdtempSync2, unlinkSync as unlinkSync2, rmdirSync, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync6, writeFileSync as writeFileSync8 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync8, statSync as statSync2, mkdtempSync as mkdtempSync2, unlinkSync as unlinkSync2, rmdirSync, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync6, writeFileSync as writeFileSync8 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
-import { dirname as dirname4, join as join7, resolve as resolve2 } from "node:path";
+import { dirname as dirname4, join as join7, resolve as resolve3 } from "node:path";
 import { isSea } from "node:sea";
 import { fileURLToPath, pathToFileURL as pathToFileURL2 } from "node:url";
 
@@ -1744,7 +1744,7 @@ function firstLine(text) {
 
 // src/login-github.ts
 import { spawn, spawnSync as spawnSync3 } from "node:child_process";
-var realSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+var realSleep = (ms) => new Promise((resolve4) => setTimeout(resolve4, ms));
 function openBrowser(url) {
   if (process.env.LAUNCHER_NO_OPEN === "1") return;
   const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
@@ -1898,7 +1898,7 @@ async function loginGoogle(options) {
   const server = options.host.replace(/\/+$/, "");
   const timeoutMs = options.timeoutMs ?? 5 * 6e4;
   const listener = createServer();
-  await new Promise((resolve3) => listener.listen(0, "127.0.0.1", resolve3));
+  await new Promise((resolve4) => listener.listen(0, "127.0.0.1", resolve4));
   const port = listener.address().port;
   const redirectUri = `http://127.0.0.1:${port}/callback`;
   try {
@@ -1925,7 +1925,7 @@ async function loginGoogle(options) {
       code_challenge: challenge,
       code_challenge_method: "S256"
     }).toString();
-    const code = await new Promise((resolve3, reject) => {
+    const code = await new Promise((resolve4, reject) => {
       const timer = setTimeout(() => reject(new Error("sign-in timed out \u2014 run login again.")), timeoutMs);
       listener.on("request", (req, res) => {
         const url = new URL(req.url ?? "/", redirectUri);
@@ -1943,7 +1943,7 @@ async function loginGoogle(options) {
         }
         res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page("Signed in.", "You can close this tab and go back to the terminal."));
         clearTimeout(timer);
-        resolve3(received);
+        resolve4(received);
       });
       const print = options.print ?? ((line) => process.stderr.write(`${line}
 `));
@@ -2041,9 +2041,9 @@ async function ensureFreshToken(config, dir, fetchImpl = fetch) {
 
 // src/refresh.ts
 import { execFile } from "node:child_process";
-import { chmodSync, existsSync as existsSync7, lstatSync, readdirSync, readFileSync as readFileSync7, renameSync as renameSync4, rmSync as rmSync5, writeFileSync as writeFileSync7 } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync as existsSync7, lstatSync, readdirSync, readFileSync as readFileSync7, realpathSync as realpathSync3, renameSync as renameSync4, rmSync as rmSync5, statSync, writeFileSync as writeFileSync7 } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname as dirname3, join as join6 } from "node:path";
+import { basename, dirname as dirname3, join as join6, resolve as resolve2 } from "node:path";
 var LAUNCHER_RECORD_FILE = "launcher.json";
 var RECORD_TIMEOUT_MS = 1e4;
 function platformKey(platform, arch) {
@@ -2102,15 +2102,54 @@ function recordedPath(productDir) {
 function installedPath(target, productDir, platform) {
   return platform === "win32" ? join6(productDir, "bin", `${target.bin}.exe`) : join6(homedir(), ".local", "bin", target.bin);
 }
+function onPath(bin, platform, env) {
+  const win = platform === "win32";
+  const read = (name) => env[name] ?? env[Object.keys(env).find((key) => key.toLowerCase() === name.toLowerCase()) ?? ""];
+  const exts = win ? ["", ...(read("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  const found = [];
+  for (const dir of (read("PATH") ?? "").split(win ? ";" : ":").filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = join6(dir.replace(/^"|"$/gu, ""), `${bin}${ext}`);
+      try {
+        if (!statSync(candidate).isFile()) continue;
+        if (!win) accessSync(candidate, constants.X_OK);
+        found.push(candidate);
+      } catch {
+      }
+    }
+  }
+  return found;
+}
+function findPathShadow(bin, file, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const same = (a, b) => {
+    const real = (path) => {
+      try {
+        return realpathSync3(path);
+      } catch {
+        return resolve2(path);
+      }
+    };
+    const [x, y] = [real(a), real(b)];
+    return platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+  };
+  const hits = onPath(bin, platform, options.env ?? process.env);
+  const other = hits.find((hit) => !same(hit, file));
+  if (!other) return null;
+  if (hits.findIndex((hit) => same(hit, file)) === 0) {
+    return { state: "shadowing", other, line: `Warning: ${file} shadows another ${bin} on PATH: ${other}.` };
+  }
+  return { state: "shadowed", other, line: `Warning: ${file} is shadowed by another ${bin} earlier on PATH: ${other}.` };
+}
 function parseLauncherVersion(stdout, bin) {
   const text = String(stdout).trim();
   if (!text.startsWith(`${bin} `)) return null;
   return text.match(/launcher (\d+\.\d+\.\d+[^\s)]*)/u)?.[1] ?? null;
 }
 function runVersion(path, bin) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     execFile(path, ["--version"], { timeout: 3e4, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
-      resolve3(error ? null : parseLauncherVersion(stdout, bin));
+      resolve4(error ? null : parseLauncherVersion(stdout, bin));
     });
   });
 }
@@ -2142,7 +2181,8 @@ async function refreshLauncher(target, options = {}) {
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
-  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail, durationMs: Date.now() - started });
+  const shadow = findPathShadow(target.bin, file, { platform, ...options.env ? { env: options.env } : {} });
+  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail: [detail, shadow?.line].filter(Boolean).join(" "), durationMs: Date.now() - started });
   const record = await fetchRecord(target, options);
   if (record === "bad-signature") return arm("fail", from, "The launcher record failed its signature check.");
   const entry2 = record?.files.find((candidate) => candidate.path === key);
@@ -2196,7 +2236,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.2.5" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.3.0" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);
@@ -2246,7 +2286,13 @@ function parseArgv(argv2) {
       parsed.run = { file: argv2[i + 1], args: argv2.slice(i + 2) };
       return parsed;
     }
-    i = skip(i);
+    const next = flag(i);
+    if (next < 0) {
+      parsed.unknownFlag ??= argv2[i];
+      parsed.forward = argv2.slice(i);
+      return parsed;
+    }
+    i = next;
   }
   parsed.command = argv2[i];
   if (parsed.command === void 0) return parsed;
@@ -2302,12 +2348,19 @@ async function run(rawOptions = {}) {
   const dir = resolveProductDir(config.product, rawOptions.dir ?? parsed.flags.dir);
   const ui = screensFor(faceProduct(config), config.binName, render, rawOptions);
   if ((parsed.command === "install" || parsed.command === "update") && !parsed.flags.version) recordSelf(dir);
+  const leadingForeign = parsed.forward !== void 0 && parsed.unknownFlag === parsed.forward[0] && !parsed.flags.help && !parsed.flags.version;
+  if (leadingForeign && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, parsed.forward, ui, () => void 0);
+  }
   if (parsed.unknownFlag) return ui.refuse(`Unknown option: ${parsed.unknownFlag}.`, `${ui.bin} --help`, 2);
   if (parsed.flags.version) {
     print(renderVersion(ui.bin, readState(dir)?.version ?? "not installed", LAUNCHER_VERSION));
     return 0;
   }
   const command2 = parsed.command;
+  if (!parsed.flags.help && command2 === void 0 && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, [], ui, () => void 0);
+  }
   if (parsed.flags.help || command2 === void 0) {
     ui.show(usage(config, dir, render));
     return parsed.flags.help ? 0 : 2;
@@ -2397,7 +2450,7 @@ async function runFile(file, args, printErr) {
     printErr("launcher --run needs a file to run.");
     return 1;
   }
-  const abs = resolve2(process.cwd(), file);
+  const abs = resolve3(process.cwd(), file);
   if (!existsSync8(abs)) {
     printErr(`cannot run ${file}: no such file.`);
     return 1;
@@ -2753,7 +2806,7 @@ function payloadFileAsCommand(entry2, payload) {
   if (NEVER_A_PROGRAM.test(first)) return first;
   if (process.platform === "win32") return null;
   try {
-    return (statSync(candidate).mode & 73) === 0 ? first : null;
+    return (statSync2(candidate).mode & 73) === 0 ? first : null;
   } catch {
     return null;
   }
@@ -2828,7 +2881,7 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
   let progressError;
   const redact = (text) => secrets.reduce((safe, value) => safe.replaceAll(value, "[redacted]"), text);
   try {
-    const result = await new Promise((resolve3) => {
+    const result = await new Promise((resolve4) => {
       const child = spawn2(shell ? [command2, ...args].map(quoteForShell).join(" ") : command2, shell ? [] : args, {
         cwd,
         shell,
@@ -2885,8 +2938,8 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
         channel.setEncoding("utf8");
         channel.on("data", receive);
       }
-      child.on("error", (error) => resolve3({ ok: false, error: error.message }));
-      child.on("close", (code) => resolve3({
+      child.on("error", (error) => resolve4({ ok: false, error: error.message }));
+      child.on("close", (code) => resolve4({
         ok: code === 0,
         ...code !== null ? { code } : {},
         ...code !== 0 ? { error: `exit code ${code}` } : {}
@@ -2911,16 +2964,19 @@ function armState(arm) {
   if (arm.verdict === "skip") return "kept";
   return arm.from === arm.to ? "current" : "updated";
 }
+function entryFor(dir) {
+  const acquired = readState(dir)?.acquired;
+  return { acquired, target: acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir) };
+}
 function doForward(config, dir, options, command2, rest, ui, unlock) {
-  if (existsSync8(command2)) {
+  if (command2 !== void 0 && existsSync8(command2)) {
     return ui.refuse(`${command2} is a file, not a command.`, `${ui.bin} --run ${command2}`, 2);
   }
-  const acquired = readState(dir)?.acquired;
-  const target = acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir);
+  const { acquired, target } = entryFor(dir);
   const verbs = readPayloadVerbs(dir);
-  const declared = verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
+  const declared = command2 === void 0 || verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
   if (!target || !declared) return ui.refuse(`Unknown command: ${command2}.`, `${ui.bin} --help`, 2);
-  const forwarded = [...resolveEntry(target), command2, ...rest];
+  const forwarded = [...resolveEntry(target), ...command2 === void 0 ? [] : [command2], ...rest];
   const cwd = payloadDir(dir);
   const inherited = payloadEnv(dir);
   const env = acquired ? runtimeEnvironment(acquired.node, inherited ?? process.env) : inherited;
@@ -3019,6 +3075,8 @@ async function doStatus(config, dir, options, ui, print, json) {
 function doDoctor(config, dir, options, ui) {
   const local = localFacts(config, dir, options);
   const verdict = verdictFor(ui, local, false, `${ui.bin} status`);
+  const shadowFile = options.shadow?.file ?? (isSea() ? process.execPath : void 0);
+  const shadow = shadowFile ? findPathShadow(config.binName, shadowFile, options.shadow ?? {}) : null;
   ui.show(renderReport(ui.product, {
     rows: [
       { surface: "launcher", state: LAUNCHER_VERSION, mark: "ok" },
@@ -3027,7 +3085,7 @@ function doDoctor(config, dir, options, ui) {
       autoUpdateRow(local.schedule)
     ],
     // Paths belong in the receipt, never a row.
-    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`] }
+    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`, ...shadow ? [shadow.line] : []] }
   }, ui.render));
   const own = verdict.state === "fail" ? 1 : 0;
   const acquired = readState(dir)?.acquired;

package/dist/launcher.sea.cjs

@@ -1777,7 +1777,7 @@ function firstLine(text) {
 
 // src/login-github.ts
 var import_node_child_process3 = require("node:child_process");
-var realSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
+var realSleep = (ms) => new Promise((resolve4) => setTimeout(resolve4, ms));
 function openBrowser(url) {
   if (process.env.LAUNCHER_NO_OPEN === "1") return;
   const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
@@ -1931,7 +1931,7 @@ async function loginGoogle(options) {
   const server = options.host.replace(/\/+$/, "");
   const timeoutMs = options.timeoutMs ?? 5 * 6e4;
   const listener = (0, import_node_http.createServer)();
-  await new Promise((resolve3) => listener.listen(0, "127.0.0.1", resolve3));
+  await new Promise((resolve4) => listener.listen(0, "127.0.0.1", resolve4));
   const port = listener.address().port;
   const redirectUri = `http://127.0.0.1:${port}/callback`;
   try {
@@ -1958,7 +1958,7 @@ async function loginGoogle(options) {
       code_challenge: challenge,
       code_challenge_method: "S256"
     }).toString();
-    const code = await new Promise((resolve3, reject) => {
+    const code = await new Promise((resolve4, reject) => {
       const timer = setTimeout(() => reject(new Error("sign-in timed out \u2014 run login again.")), timeoutMs);
       listener.on("request", (req, res) => {
         const url = new URL(req.url ?? "/", redirectUri);
@@ -1976,7 +1976,7 @@ async function loginGoogle(options) {
         }
         res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(page("Signed in.", "You can close this tab and go back to the terminal."));
         clearTimeout(timer);
-        resolve3(received);
+        resolve4(received);
       });
       const print = options.print ?? ((line) => process.stderr.write(`${line}
 `));
@@ -2135,15 +2135,54 @@ function recordedPath(productDir) {
 function installedPath(target, productDir, platform) {
   return platform === "win32" ? (0, import_node_path6.join)(productDir, "bin", `${target.bin}.exe`) : (0, import_node_path6.join)((0, import_node_os4.homedir)(), ".local", "bin", target.bin);
 }
+function onPath(bin, platform, env) {
+  const win = platform === "win32";
+  const read = (name) => env[name] ?? env[Object.keys(env).find((key) => key.toLowerCase() === name.toLowerCase()) ?? ""];
+  const exts = win ? ["", ...(read("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  const found = [];
+  for (const dir of (read("PATH") ?? "").split(win ? ";" : ":").filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = (0, import_node_path6.join)(dir.replace(/^"|"$/gu, ""), `${bin}${ext}`);
+      try {
+        if (!(0, import_node_fs11.statSync)(candidate).isFile()) continue;
+        if (!win) (0, import_node_fs11.accessSync)(candidate, import_node_fs11.constants.X_OK);
+        found.push(candidate);
+      } catch {
+      }
+    }
+  }
+  return found;
+}
+function findPathShadow(bin, file, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const same = (a, b) => {
+    const real = (path) => {
+      try {
+        return (0, import_node_fs11.realpathSync)(path);
+      } catch {
+        return (0, import_node_path6.resolve)(path);
+      }
+    };
+    const [x, y] = [real(a), real(b)];
+    return platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+  };
+  const hits = onPath(bin, platform, options.env ?? process.env);
+  const other = hits.find((hit) => !same(hit, file));
+  if (!other) return null;
+  if (hits.findIndex((hit) => same(hit, file)) === 0) {
+    return { state: "shadowing", other, line: `Warning: ${file} shadows another ${bin} on PATH: ${other}.` };
+  }
+  return { state: "shadowed", other, line: `Warning: ${file} is shadowed by another ${bin} earlier on PATH: ${other}.` };
+}
 function parseLauncherVersion(stdout, bin) {
   const text = String(stdout).trim();
   if (!text.startsWith(`${bin} `)) return null;
   return text.match(/launcher (\d+\.\d+\.\d+[^\s)]*)/u)?.[1] ?? null;
 }
 function runVersion(path, bin) {
-  return new Promise((resolve3) => {
+  return new Promise((resolve4) => {
     (0, import_node_child_process4.execFile)(path, ["--version"], { timeout: 3e4, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
-      resolve3(error ? null : parseLauncherVersion(stdout, bin));
+      resolve4(error ? null : parseLauncherVersion(stdout, bin));
     });
   });
 }
@@ -2175,7 +2214,8 @@ async function refreshLauncher(target, options = {}) {
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
-  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail, durationMs: Date.now() - started });
+  const shadow = findPathShadow(target.bin, file, { platform, ...options.env ? { env: options.env } : {} });
+  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail: [detail, shadow?.line].filter(Boolean).join(" "), durationMs: Date.now() - started });
   const record = await fetchRecord(target, options);
   if (record === "bad-signature") return arm("fail", from, "The launcher record failed its signature check.");
   const entry2 = record?.files.find((candidate) => candidate.path === key);
@@ -2229,7 +2269,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.2.5" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.3.0" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);
@@ -2279,7 +2319,13 @@ function parseArgv(argv2) {
       parsed.run = { file: argv2[i + 1], args: argv2.slice(i + 2) };
       return parsed;
     }
-    i = skip(i);
+    const next = flag(i);
+    if (next < 0) {
+      parsed.unknownFlag ??= argv2[i];
+      parsed.forward = argv2.slice(i);
+      return parsed;
+    }
+    i = next;
   }
   parsed.command = argv2[i];
   if (parsed.command === void 0) return parsed;
@@ -2335,12 +2381,19 @@ async function run(rawOptions = {}) {
   const dir = resolveProductDir(config.product, rawOptions.dir ?? parsed.flags.dir);
   const ui = screensFor(faceProduct(config), config.binName, render, rawOptions);
   if ((parsed.command === "install" || parsed.command === "update") && !parsed.flags.version) recordSelf(dir);
+  const leadingForeign = parsed.forward !== void 0 && parsed.unknownFlag === parsed.forward[0] && !parsed.flags.help && !parsed.flags.version;
+  if (leadingForeign && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, parsed.forward, ui, () => void 0);
+  }
   if (parsed.unknownFlag) return ui.refuse(`Unknown option: ${parsed.unknownFlag}.`, `${ui.bin} --help`, 2);
   if (parsed.flags.version) {
     print(renderVersion(ui.bin, readState(dir)?.version ?? "not installed", LAUNCHER_VERSION));
     return 0;
   }
   const command2 = parsed.command;
+  if (!parsed.flags.help && command2 === void 0 && entryFor(dir).target) {
+    return doForward(config, dir, rawOptions, void 0, [], ui, () => void 0);
+  }
   if (parsed.flags.help || command2 === void 0) {
     ui.show(usage(config, dir, render));
     return parsed.flags.help ? 0 : 2;
@@ -2861,7 +2914,7 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
   let progressError;
   const redact = (text) => secrets.reduce((safe, value) => safe.replaceAll(value, "[redacted]"), text);
   try {
-    const result = await new Promise((resolve3) => {
+    const result = await new Promise((resolve4) => {
       const child = (0, import_node_child_process5.spawn)(shell ? [command2, ...args].map(quoteForShell).join(" ") : command2, shell ? [] : args, {
         cwd,
         shell,
@@ -2918,8 +2971,8 @@ async function runInstallEntry(entry2, cwd, env, installer, tokens = null) {
         channel.setEncoding("utf8");
         channel.on("data", receive);
       }
-      child.on("error", (error) => resolve3({ ok: false, error: error.message }));
-      child.on("close", (code) => resolve3({
+      child.on("error", (error) => resolve4({ ok: false, error: error.message }));
+      child.on("close", (code) => resolve4({
         ok: code === 0,
         ...code !== null ? { code } : {},
         ...code !== 0 ? { error: `exit code ${code}` } : {}
@@ -2944,16 +2997,19 @@ function armState(arm) {
   if (arm.verdict === "skip") return "kept";
   return arm.from === arm.to ? "current" : "updated";
 }
+function entryFor(dir) {
+  const acquired = readState(dir)?.acquired;
+  return { acquired, target: acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir) };
+}
 function doForward(config, dir, options, command2, rest, ui, unlock) {
-  if ((0, import_node_fs12.existsSync)(command2)) {
+  if (command2 !== void 0 && (0, import_node_fs12.existsSync)(command2)) {
     return ui.refuse(`${command2} is a file, not a command.`, `${ui.bin} --run ${command2}`, 2);
   }
-  const acquired = readState(dir)?.acquired;
-  const target = acquired ? [acquired.node, acquired.entry] : readPayloadRun(dir);
+  const { acquired, target } = entryFor(dir);
   const verbs = readPayloadVerbs(dir);
-  const declared = verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
+  const declared = command2 === void 0 || verbs === "*" || Array.isArray(verbs) && verbs.includes(command2);
   if (!target || !declared) return ui.refuse(`Unknown command: ${command2}.`, `${ui.bin} --help`, 2);
-  const forwarded = [...resolveEntry(target), command2, ...rest];
+  const forwarded = [...resolveEntry(target), ...command2 === void 0 ? [] : [command2], ...rest];
   const cwd = payloadDir(dir);
   const inherited = payloadEnv(dir);
   const env = acquired ? runtimeEnvironment(acquired.node, inherited ?? process.env) : inherited;
@@ -3052,6 +3108,8 @@ async function doStatus(config, dir, options, ui, print, json) {
 function doDoctor(config, dir, options, ui) {
   const local = localFacts(config, dir, options);
   const verdict = verdictFor(ui, local, false, `${ui.bin} status`);
+  const shadowFile = options.shadow?.file ?? ((0, import_node_sea2.isSea)() ? process.execPath : void 0);
+  const shadow = shadowFile ? findPathShadow(config.binName, shadowFile, options.shadow ?? {}) : null;
   ui.show(renderReport(ui.product, {
     rows: [
       { surface: "launcher", state: LAUNCHER_VERSION, mark: "ok" },
@@ -3060,7 +3118,7 @@ function doDoctor(config, dir, options, ui) {
       autoUpdateRow(local.schedule)
     ],
     // Paths belong in the receipt, never a row.
-    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`] }
+    verdict: { ...verdict, facts: [`Folder: ${dir}`, `Release host: ${config.host}`, ...shadow ? [shadow.line] : []] }
   }, ui.render));
   const own = verdict.state === "fail" ? 1 : 0;
   const acquired = readState(dir)?.acquired;

package/dist/refresh.js

@@ -1,8 +1,8 @@
 // src/refresh.ts
 import { execFile } from "node:child_process";
-import { chmodSync, existsSync as existsSync2, lstatSync, readdirSync, readFileSync as readFileSync2, renameSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync as existsSync2, lstatSync, readdirSync, readFileSync as readFileSync2, realpathSync as realpathSync2, renameSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
-import { basename, dirname as dirname2, join as join3 } from "node:path";
+import { basename, dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
 
 // src/acquisition.ts
 import { createHash as createHash2, randomUUID } from "node:crypto";
@@ -235,15 +235,54 @@ function recordedPath(productDir) {
 function installedPath(target, productDir, platform) {
   return platform === "win32" ? join3(productDir, "bin", `${target.bin}.exe`) : join3(homedir(), ".local", "bin", target.bin);
 }
+function onPath(bin, platform, env) {
+  const win = platform === "win32";
+  const read = (name) => env[name] ?? env[Object.keys(env).find((key) => key.toLowerCase() === name.toLowerCase()) ?? ""];
+  const exts = win ? ["", ...(read("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)] : [""];
+  const found = [];
+  for (const dir of (read("PATH") ?? "").split(win ? ";" : ":").filter(Boolean)) {
+    for (const ext of exts) {
+      const candidate = join3(dir.replace(/^"|"$/gu, ""), `${bin}${ext}`);
+      try {
+        if (!statSync(candidate).isFile()) continue;
+        if (!win) accessSync(candidate, constants.X_OK);
+        found.push(candidate);
+      } catch {
+      }
+    }
+  }
+  return found;
+}
+function findPathShadow(bin, file, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const same = (a, b) => {
+    const real = (path) => {
+      try {
+        return realpathSync2(path);
+      } catch {
+        return resolve2(path);
+      }
+    };
+    const [x, y] = [real(a), real(b)];
+    return platform === "win32" ? x.toLowerCase() === y.toLowerCase() : x === y;
+  };
+  const hits = onPath(bin, platform, options.env ?? process.env);
+  const other = hits.find((hit) => !same(hit, file));
+  if (!other) return null;
+  if (hits.findIndex((hit) => same(hit, file)) === 0) {
+    return { state: "shadowing", other, line: `Warning: ${file} shadows another ${bin} on PATH: ${other}.` };
+  }
+  return { state: "shadowed", other, line: `Warning: ${file} is shadowed by another ${bin} earlier on PATH: ${other}.` };
+}
 function parseLauncherVersion(stdout, bin) {
   const text = String(stdout).trim();
   if (!text.startsWith(`${bin} `)) return null;
   return text.match(/launcher (\d+\.\d+\.\d+[^\s)]*)/u)?.[1] ?? null;
 }
 function runVersion(path, bin) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     execFile(path, ["--version"], { timeout: 3e4, windowsHide: true, encoding: "utf8" }, (error, stdout) => {
-      resolve2(error ? null : parseLauncherVersion(stdout, bin));
+      resolve3(error ? null : parseLauncherVersion(stdout, bin));
     });
   });
 }
@@ -275,7 +314,8 @@ async function refreshLauncher(target, options = {}) {
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
-  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail, durationMs: Date.now() - started });
+  const shadow = findPathShadow(target.bin, file, { platform, ...options.env ? { env: options.env } : {} });
+  const arm = (verdict, to, detail) => ({ surface: "launcher", from, to, verdict, detail: [detail, shadow?.line].filter(Boolean).join(" "), durationMs: Date.now() - started });
   const record = await fetchRecord(target, options);
   if (record === "bad-signature") return arm("fail", from, "The launcher record failed its signature check.");
   const entry = record?.files.find((candidate) => candidate.path === key);
@@ -330,6 +370,7 @@ async function refreshLauncher(target, options = {}) {
 export {
   LAUNCHER_RECORD_FILE,
   compareVersions,
+  findPathShadow,
   parseLauncherVersion,
   readLauncherRecord,
   refreshLauncher

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/installer-launcher",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "Single-executable (SEA) launcher: sign-in, gated payload fetch, self-update. One copy ships per product.",
   "type": "module",
   "license": "UNLICENSED",