From deea09ee1062a77be388ad140ce4095ee4bd2aa0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 4 Sep 2026 09:52:54 +0000
Subject: [PATCH] feat: honour the Actor's original start command when run as
 ENTRYPOINT

Running as the image CMD has two problems: the Actor's real start command is
lost (the entrypoint is guessed from package.json/conventional paths), and an
ENTRYPOINT defined in the Actor's own Dockerfile silently swallows our CMD, so
the Actor runs with no debugger and no error.

As ENTRYPOINT, Docker appends the image's own CMD to our arguments. Everything
after --brk is now treated as that start command and resolved into a Node.js
launch spec, keeping the original node flags and script arguments:

  node [flags] <script> [args]      -> that script, flags and args preserved
  npm|pnpm|yarn [run] <script>      -> the package.json script, parsed again
  sh -c "<command>"                 -> the inner command, parsed again
  <path>                            -> that file (the explicit-path form)

Chained scripts are resolved from the last segment back, so
`npm run build && node dist/main.js` debugs the Actor, not the build step.
With no command passed, the previous auto-detection still applies, so the
existing CMD forms keep working unchanged. When a command is passed but no
Node.js entrypoint can be derived from it, the debugger fails fast with the
reason instead of starting the Actor undebuggable.

Adds a node:test suite for the resolver (no new dependencies) and runs it,
plus a syntax check of the new module, in the release workflow.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UTxccb4QARxDG34guZbeFG
---
 .github/workflows/publish.yml |   5 +
 README.md                     |  52 ++++++--
 bin/cli.mjs                   |  54 ++++-----
 lib/resolve_launch.mjs        | 218 ++++++++++++++++++++++++++++++++++
 package.json                  |   3 +
 test/resolve_launch.test.mjs  | 144 ++++++++++++++++++++++
 6 files changed, 436 insertions(+), 40 deletions(-)
 create mode 100644 lib/resolve_launch.mjs
 create mode 100644 test/resolve_launch.test.mjs

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index d88f02b..05986ab 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -36,6 +36,11 @@ jobs:
         run: |
           node --check bin/cli.mjs
           node --check lib/debug_server.mjs
+          node --check lib/inline_sourcemaps.mjs
+          node --check lib/resolve_launch.mjs
+
+      - name: Unit tests
+        run: npm test
 
       - name: Verify tag matches package.json version
         run: |
diff --git a/README.md b/README.md
index 5a9f72f..1ce7b4b 100644
--- a/README.md
+++ b/README.md
@@ -6,13 +6,16 @@ container URL** — so you open one link in your own browser and debug. No wstun
 no rebuild of your source, and **no browser in the Actor**.
 
 ```dockerfile
-# Get the package
-RUN npm install actor-debugger
+# Get the package (globally, so the Actor's own node_modules and lockfile are untouched)
+RUN npm install --global actor-debugger
 
-# pause on the first line until a debugger attaches (for short-lived Actors):
-CMD ["npx", "actor-debugger", "--brk"]
+# Recommended: wrap the image's existing CMD. Docker appends it to the ENTRYPOINT, so your real
+# start command is used as-is, and an ENTRYPOINT in your own Dockerfile can't swallow it.
+# `--brk` pauses on the first line until a debugger attaches (for short-lived Actors).
+ENTRYPOINT ["actor-debugger", "--brk"]
 
-# or point at a specific entry:
+# Or replace the CMD instead - the entrypoint is then auto-detected, or given explicitly:
+CMD ["npx", "actor-debugger", "--brk"]
 CMD ["npx", "actor-debugger", "dist/main.js"]
 ```
 
@@ -36,10 +39,10 @@ chii's build is the same frontend, ready to serve.
 
 ## Activation
 
-Running the Actor through `npx actor-debugger` **is** the switch — debugging is on whenever the
-`CMD` line above is in place. To turn it off, revert the `CMD` to the Actor's normal entrypoint
-(e.g. `CMD ["npm", "start"]`) and rebuild. Pass `--brk` to pause on the first line until a
-debugger attaches — useful for Actors that would otherwise finish before you connect.
+Running the Actor through `actor-debugger` **is** the switch — debugging is on whenever the
+`ENTRYPOINT` (or `CMD`) line above is in place. To turn it off, drop that line and rebuild. Pass
+`--brk` to pause on the first line until a debugger attaches — useful for Actors that would
+otherwise finish before you connect.
 
 ## Connect
 
@@ -76,10 +79,33 @@ your `src/` into the final stage to fix it.
 
 ## Entrypoint detection order
 
-1. An explicit path argument, if given.
-2. The file in `package.json` `scripts.start` (e.g. `node dist/main.js` → `dist/main.js`).
-3. `package.json` `main`.
-4. Conventional paths: `dist/main.js`, `dist/index.js`, `build/main.js`, `src/main.js`, `main.js`, `index.js`.
+Anything after `--brk` is treated as the Actor's start command. As `ENTRYPOINT`, that is the image's
+own `CMD`, appended by Docker — so the Actor starts the way it normally does, with its Node flags and
+arguments intact, instead of being guessed at.
+
+Understood start commands:
+
+| Passed-through command | Resolves to |
+| --- | --- |
+| `node [flags] <script> [args]` | that script, keeping flags (incl. `-r x`/`--import x`) and args |
+| `npm start`, `npm run <s>`, `pnpm …`, `yarn …` | the matching `package.json` script, parsed again |
+| `sh -c "<command>"` | the inner command, parsed again |
+| `dist/main.js` | that file directly (the explicit-path form) |
+
+Chained scripts are handled by trying the segments from the last back, so `npm run build && node
+dist/main.js` debugs `dist/main.js` rather than the build step.
+
+With **no** command passed (the plain `CMD ["npx", "actor-debugger"]` form), the entrypoint is
+auto-detected instead:
+
+1. The file in `package.json` `scripts.start` (e.g. `node dist/main.js` → `dist/main.js`).
+2. `package.json` `main`.
+3. Conventional paths: `dist/main.js`, `dist/index.js`, `build/main.js`, `src/main.js`, `main.js`, `index.js`.
+
+If a command is passed but no Node.js entrypoint can be derived from it (e.g. a `tsx`/`ts-node`
+launcher), the debugger **fails fast** with the reason rather than starting the Actor without a
+debugger attached — a run you asked to debug should not silently run undebuggable. Pass the
+entrypoint explicitly in that case: `ENTRYPOINT ["actor-debugger", "--brk", "dist/main.js"]`.
 
 ## Security
 
diff --git a/bin/cli.mjs b/bin/cli.mjs
index 4141fb4..befc6f1 100644
--- a/bin/cli.mjs
+++ b/bin/cli.mjs
@@ -3,12 +3,17 @@
  * actor-debugger - launch an Apify Node/TS Actor under the Node inspector, reachable over the
  * run's container URL, with a one-line Dockerfile change:
  *
+ *   ENTRYPOINT ["actor-debugger", "--brk"]           # recommended: keeps the image's own CMD
  *   CMD ["npx", "actor-debugger"]                    # auto-detect the Actor's entrypoint
  *   CMD ["npx", "actor-debugger", "dist/x.js"]       # explicit entrypoint
  *   CMD ["npx", "actor-debugger", "--brk"]           # pause on the first line until attached
  *
- * Running through this command is what enables debugging - revert the CMD to the normal
- * entrypoint to turn it off.
+ * As ENTRYPOINT, Docker appends the image's original CMD to our arguments, so the Actor's real
+ * start command (`npm start`, `node dist/main.js`, ...) is honoured instead of guessed, and an
+ * ENTRYPOINT cannot be silently swallowed by one already defined in the Actor's Dockerfile.
+ *
+ * Running through this command is what enables debugging - revert the ENTRYPOINT/CMD to the
+ * normal entrypoint to turn it off.
  */
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
@@ -18,9 +23,12 @@ import path from 'node:path';
 
 import { startDebugServer } from '../lib/debug_server.mjs';
 import { inlineSourceMaps } from '../lib/inline_sourcemaps.mjs';
+import { resolveLaunch } from '../lib/resolve_launch.mjs';
 
 const INSPECTOR_PORT = 9229;
 const TAG = '[actor-debugger]';
+/** Our own flag; everything else on the command line belongs to the Actor. */
+const BRK_FLAG = '--brk';
 
 /** Locate chii's prebuilt Chrome DevTools frontend (chrome-devtools-frontend npm ships unbuilt source). */
 function findFrontendDir() {
@@ -39,24 +47,6 @@ function findFrontendDir() {
     return null;
 }
 
-function resolveEntry(argEntry) {
-    if (argEntry) return path.resolve(argEntry);
-    const candidates = [];
-    try {
-        const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
-        const startMatch = pkg.scripts?.start && /node\s+(?:--\S+\s+)*(\S+)/.exec(pkg.scripts.start);
-        if (startMatch) candidates.push(startMatch[1]);
-        if (pkg.main) candidates.push(pkg.main);
-    } catch {
-        // no/invalid package.json - fall through to conventional paths
-    }
-    candidates.push('dist/main.js', 'dist/index.js', 'build/main.js', 'src/main.js', 'main.js', 'index.js');
-    for (const candidate of candidates) {
-        if (candidate && fs.existsSync(candidate)) return path.resolve(candidate);
-    }
-    return null;
-}
-
 function fetchInspectorUuid(retries = 40) {
     return new Promise((resolve) => {
         const attempt = (left) => {
@@ -108,13 +98,20 @@ async function announce(webServerUrl, hasFrontend) {
 }
 
 const args = process.argv.slice(2);
-const brk = args.includes('--brk');
-const entry = resolveEntry(args.find((a) => !a.startsWith('--')));
-if (!entry) {
-    console.error(`${TAG} could not find an Actor entrypoint. Pass one explicitly:`);
-    console.error(`${TAG}   CMD ["npx", "actor-debugger", "dist/main.js"]`);
+const brk = args.includes(BRK_FLAG);
+// Everything except our own flag is either an explicit entrypoint or - when we run as the image
+// ENTRYPOINT - the Actor's original CMD, appended by Docker.
+const command = args.filter((arg) => arg !== BRK_FLAG);
+
+const launch = resolveLaunch({ command });
+if (!launch.entry) {
+    console.error(`${TAG} ${launch.reason}.`);
+    console.error(`${TAG} pass the Actor's entrypoint explicitly, e.g.:`);
+    console.error(`${TAG}   ENTRYPOINT ["actor-debugger", "--brk", "dist/main.js"]`);
     process.exit(1);
 }
+const { entry, nodeFlags, scriptArgs, source } = launch;
+console.error(`${TAG} starting the Actor from ${source}.`);
 
 // A remote DevTools frontend cannot fetch file:// URLs, so external .map files (and the .ts
 // sources they reference) are unreachable to it. Inline them into the compiled files up front.
@@ -130,9 +127,12 @@ if (maps.inlined > 0) {
 }
 
 const inspectFlag = brk ? '--inspect-brk' : '--inspect';
-const nodeArgs = ['--enable-source-maps', `${inspectFlag}=127.0.0.1:${INSPECTOR_PORT}`];
+const nodeArgs = ['--enable-source-maps', `${inspectFlag}=127.0.0.1:${INSPECTOR_PORT}`, ...nodeFlags];
 
-const child = spawn(process.execPath, [...nodeArgs, entry], { stdio: 'inherit', env: process.env });
+const child = spawn(process.execPath, [...nodeArgs, entry, ...scriptArgs], {
+    stdio: 'inherit',
+    env: process.env,
+});
 
 let server;
 const { ACTOR_WEB_SERVER_PORT: port, ACTOR_WEB_SERVER_URL: url } = process.env;
diff --git a/lib/resolve_launch.mjs b/lib/resolve_launch.mjs
new file mode 100644
index 0000000..44dc239
--- /dev/null
+++ b/lib/resolve_launch.mjs
@@ -0,0 +1,218 @@
+/**
+ * Turns the Actor's start command into a Node.js launch spec (entrypoint + node flags + script args).
+ *
+ * This exists because `actor-debugger` can run as the image ENTRYPOINT, in which case Docker appends
+ * the image's original CMD to our arguments - so the Actor's real start command arrives as argv and
+ * we can honour it instead of guessing. It still supports being run as the CMD itself, with either an
+ * explicit entrypoint path or nothing at all (then the entrypoint is auto-detected).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** How many layers of indirection to follow (`npm start` -> `sh -c "..."` -> `node x.js`). */
+const MAX_DEPTH = 4;
+
+const NODE_BINARIES = new Set(['node', 'nodejs']);
+const PACKAGE_MANAGERS = new Set(['npm', 'pnpm', 'yarn']);
+const SHELLS = new Set(['sh', 'bash', 'dash', 'ash', 'zsh']);
+
+/** Subcommands that precede the script name (`npm run start`); `npm start` names the script directly. */
+const RUN_SUBCOMMANDS = new Set(['run', 'run-script']);
+
+/**
+ * Node flags whose value is a separate argument, so the token after them is NOT the script path
+ * (e.g. `node -r ts-node/register src/main.ts`).
+ */
+const NODE_FLAGS_WITH_SEPARATE_VALUE = new Set([
+    '-r',
+    '--require',
+    '--import',
+    '--loader',
+    '--experimental-loader',
+    '-C',
+    '--conditions',
+    '--max-old-space-size',
+    '--max-semi-space-size',
+    '--inspect-port',
+    '--title',
+]);
+
+/** Entrypoints to try when there is no start command to learn from. */
+const FALLBACK_ENTRIES = ['dist/main.js', 'dist/index.js', 'build/main.js', 'src/main.js', 'main.js', 'index.js'];
+
+/** Operators that chain commands; the Actor is started by one of the segments, usually the last. */
+const CHAIN_OPERATORS = new Set(['&&', '||', ';', '|']);
+
+/**
+ * Splits a command string into tokens, honouring single and double quotes so that
+ * `sh -c "node dist/main.js"` keeps the inner command in one token.
+ */
+export function tokenizeCommand(commandString) {
+    const tokens = [];
+    let current = '';
+    let quote = null;
+    let hasContent = false;
+
+    for (const char of commandString) {
+        if (quote) {
+            if (char === quote) quote = null;
+            else current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            hasContent = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (hasContent || current) tokens.push(current);
+            current = '';
+            hasContent = false;
+            continue;
+        }
+        current += char;
+    }
+    if (hasContent || current) tokens.push(current);
+    return tokens;
+}
+
+/** Splits a token list on shell chaining operators, e.g. `npm run build && node dist/main.js`. */
+function splitChain(command) {
+    const segments = [[]];
+    for (const token of command) {
+        if (CHAIN_OPERATORS.has(token)) segments.push([]);
+        else segments[segments.length - 1].push(token);
+    }
+    return segments.filter((segment) => segment.length > 0);
+}
+
+/** Separates a `node`-invocation tail into flags, the script path and the script's own arguments. */
+function splitNodeInvocation(args) {
+    const flags = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (!arg.startsWith('-')) return { flags, target: arg, scriptArgs: args.slice(index + 1) };
+        flags.push(arg);
+        // `-r ts-node/register` - the value is a separate token and must not be read as the script.
+        if (NODE_FLAGS_WITH_SEPARATE_VALUE.has(arg) && args[index + 1] !== undefined) {
+            flags.push(args[index + 1]);
+            index++;
+        }
+    }
+    return { flags, target: undefined, scriptArgs: [] };
+}
+
+/** Reads the script name out of a package-manager invocation (`npm start`, `pnpm run dev`, ...). */
+function packageManagerScript(args) {
+    const positional = args.filter((arg) => !arg.startsWith('-') && arg !== '--');
+    if (positional.length === 0) return undefined;
+    if (RUN_SUBCOMMANDS.has(positional[0])) return positional[1];
+    return positional[0];
+}
+
+function readPackageJson(cwd) {
+    try {
+        return JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8'));
+    } catch {
+        return undefined;
+    }
+}
+
+function existingFile(cwd, candidate) {
+    const absolute = path.resolve(cwd, candidate);
+    return fs.existsSync(absolute) && fs.statSync(absolute).isFile() ? absolute : undefined;
+}
+
+/** Looks for a conventional entrypoint when no usable start command is available. */
+function autoDetectEntry(cwd) {
+    const pkg = readPackageJson(cwd);
+    const candidates = [];
+    const startScript = pkg?.scripts?.start;
+    if (startScript) {
+        const startMatch = /node\s+(?:--\S+\s+)*(\S+)/.exec(startScript);
+        if (startMatch) candidates.push(startMatch[1]);
+    }
+    if (pkg?.main) candidates.push(pkg.main);
+    candidates.push(...FALLBACK_ENTRIES);
+
+    for (const candidate of candidates) {
+        const absolute = existingFile(cwd, candidate);
+        if (absolute) return absolute;
+    }
+    return undefined;
+}
+
+const autoDetect = (cwd) => {
+    const entry = autoDetectEntry(cwd);
+    return entry
+        ? { entry, nodeFlags: [], scriptArgs: [], source: 'auto-detected entrypoint' }
+        : {
+              entry: null,
+              reason: 'could not find an Actor entrypoint, and no start command was passed through to learn from',
+          };
+};
+
+/**
+ * Resolves how to start the Actor under the inspector.
+ *
+ * @param {object} options
+ * @param {string[]} options.command The Actor's start command (image CMD passed through by Docker),
+ *   or a single explicit entrypoint path, or empty to auto-detect.
+ * @param {string} [options.cwd] Directory the command would run in.
+ * @returns {{entry: string, nodeFlags: string[], scriptArgs: string[], source: string}
+ *   | {entry: null, reason: string}}
+ */
+export function resolveLaunch({ command = [], cwd = process.cwd(), depth = 0 } = {}) {
+    if (command.length === 0) return autoDetect(cwd);
+    if (depth > MAX_DEPTH) {
+        return { entry: null, reason: `start command "${command.join(' ')}" has too many layers of indirection` };
+    }
+
+    // `npm run build && node dist/main.js` - try the segments from the last one back, so the segment
+    // that actually starts the Actor wins over preceding build steps.
+    const segments = splitChain(command);
+    if (segments.length > 1) {
+        for (const segment of segments.reverse()) {
+            const resolved = resolveLaunch({ command: segment, cwd, depth: depth + 1 });
+            if (resolved.entry) return resolved;
+        }
+        return { entry: null, reason: `no Node.js entrypoint found in "${command.join(' ')}"` };
+    }
+
+    const [binary, ...args] = segments[0] ?? command;
+    const name = path.basename(binary);
+    const printable = command.join(' ');
+
+    // `node [flags] <script> [args]`
+    if (NODE_BINARIES.has(name)) {
+        const { flags, target, scriptArgs } = splitNodeInvocation(args);
+        if (!target) return { entry: null, reason: `no script found in "${printable}"` };
+        const entry = existingFile(cwd, target);
+        return entry
+            ? { entry, nodeFlags: flags, scriptArgs, source: `"${printable}"` }
+            : { entry: null, reason: `script "${target}" from "${printable}" does not exist in the image` };
+    }
+
+    // `npm start`, `pnpm run dev`, `yarn start`, ... - follow the script from package.json.
+    if (PACKAGE_MANAGERS.has(name)) {
+        const script = packageManagerScript(args);
+        if (!script) return { entry: null, reason: `could not tell which script "${printable}" runs` };
+        const scriptCommand = readPackageJson(cwd)?.scripts?.[script];
+        if (!scriptCommand) return { entry: null, reason: `package.json has no "${script}" script` };
+        return resolveLaunch({ command: tokenizeCommand(scriptCommand), cwd, depth: depth + 1 });
+    }
+
+    // `sh -c "node dist/main.js"`
+    if (SHELLS.has(name)) {
+        const flagIndex = args.indexOf('-c');
+        const inner = flagIndex === -1 ? undefined : args[flagIndex + 1];
+        if (!inner) return { entry: null, reason: `could not read the command out of "${printable}"` };
+        return resolveLaunch({ command: tokenizeCommand(inner), cwd, depth: depth + 1 });
+    }
+
+    // A bare path to a script - the documented `actor-debugger dist/main.js` form.
+    const entry = existingFile(cwd, binary);
+    if (entry) return { entry, nodeFlags: [], scriptArgs: args, source: `"${printable}"` };
+
+    return { entry: null, reason: `unrecognized start command "${printable}"` };
+}
diff --git a/package.json b/package.json
index 4f573ff..bb10882 100644
--- a/package.json
+++ b/package.json
@@ -6,6 +6,9 @@
     "bin": {
         "actor-debugger": "bin/cli.mjs"
     },
+    "scripts": {
+        "test": "node --test test/*.test.mjs"
+    },
     "files": [
         "bin",
         "lib",
diff --git a/test/resolve_launch.test.mjs b/test/resolve_launch.test.mjs
new file mode 100644
index 0000000..1a37d5b
--- /dev/null
+++ b/test/resolve_launch.test.mjs
@@ -0,0 +1,144 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { after, before, describe, it } from 'node:test';
+
+import { resolveLaunch, tokenizeCommand } from '../lib/resolve_launch.mjs';
+
+/** A throwaway Actor directory, so the resolver is exercised against a real filesystem. */
+let cwd;
+
+const write = (relativePath, content) => {
+    const absolute = path.join(cwd, relativePath);
+    fs.mkdirSync(path.dirname(absolute), { recursive: true });
+    fs.writeFileSync(absolute, content);
+};
+
+const writePackageJson = (pkg) => write('package.json', JSON.stringify(pkg));
+
+before(() => {
+    cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'actor-debugger-test-'));
+    write('dist/main.js', 'console.log(1);');
+    write('src/main.ts', 'console.log(1);');
+});
+
+after(() => fs.rmSync(cwd, { recursive: true, force: true }));
+
+describe('tokenizeCommand', () => {
+    it('splits on whitespace', () => {
+        assert.deepEqual(tokenizeCommand('node dist/main.js'), ['node', 'dist/main.js']);
+    });
+
+    it('keeps quoted sections together', () => {
+        assert.deepEqual(tokenizeCommand(`sh -c "node dist/main.js --flag"`), [
+            'sh',
+            '-c',
+            'node dist/main.js --flag',
+        ]);
+    });
+
+    it('preserves an empty quoted argument', () => {
+        assert.deepEqual(tokenizeCommand(`node dist/main.js ""`), ['node', 'dist/main.js', '']);
+    });
+});
+
+describe('resolveLaunch with a passed-through start command', () => {
+    it('honours `node <script>`', () => {
+        const launch = resolveLaunch({ command: ['node', 'dist/main.js'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+        assert.deepEqual(launch.nodeFlags, []);
+        assert.deepEqual(launch.scriptArgs, []);
+    });
+
+    it('keeps the original node flags and script arguments', () => {
+        const launch = resolveLaunch({
+            command: ['node', '--experimental-vm-modules', 'dist/main.js', '--verbose', 'input.json'],
+            cwd,
+        });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+        assert.deepEqual(launch.nodeFlags, ['--experimental-vm-modules']);
+        assert.deepEqual(launch.scriptArgs, ['--verbose', 'input.json']);
+    });
+
+    it('does not mistake a flag value for the script', () => {
+        const launch = resolveLaunch({ command: ['node', '-r', 'ts-node/register', 'dist/main.js'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+        assert.deepEqual(launch.nodeFlags, ['-r', 'ts-node/register']);
+    });
+
+    it('resolves an absolute node binary path', () => {
+        const launch = resolveLaunch({ command: ['/usr/local/bin/node', 'dist/main.js'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+    });
+
+    it('follows `npm start` through package.json', () => {
+        writePackageJson({ scripts: { start: 'node dist/main.js' } });
+        const launch = resolveLaunch({ command: ['npm', 'start'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+    });
+
+    it('follows `pnpm run <script>` and `yarn start`', () => {
+        writePackageJson({ scripts: { start: 'node dist/main.js', serve: 'node dist/main.js --serve' } });
+        assert.equal(resolveLaunch({ command: ['pnpm', 'run', 'serve'], cwd }).entry, path.join(cwd, 'dist/main.js'));
+        assert.deepEqual(resolveLaunch({ command: ['pnpm', 'run', 'serve'], cwd }).scriptArgs, ['--serve']);
+        assert.equal(resolveLaunch({ command: ['yarn', 'start'], cwd }).entry, path.join(cwd, 'dist/main.js'));
+    });
+
+    it('skips preceding build steps in a chained script', () => {
+        writePackageJson({ scripts: { start: 'npm run build && node dist/main.js', build: 'tsc' } });
+        const launch = resolveLaunch({ command: ['npm', 'start'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+    });
+
+    it('picks the node segment even when it is not last in the chain', () => {
+        writePackageJson({ scripts: { start: 'node dist/main.js && echo done' } });
+        const launch = resolveLaunch({ command: ['npm', 'start'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+    });
+
+    it('unwraps `sh -c`', () => {
+        const launch = resolveLaunch({ command: ['sh', '-c', 'node dist/main.js'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+    });
+
+    it('accepts a bare script path (the documented CMD form)', () => {
+        const launch = resolveLaunch({ command: ['dist/main.js'], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+    });
+});
+
+describe('resolveLaunch fallbacks and failures', () => {
+    it('auto-detects when no command is passed', () => {
+        writePackageJson({ main: 'dist/main.js' });
+        const launch = resolveLaunch({ command: [], cwd });
+        assert.equal(launch.entry, path.join(cwd, 'dist/main.js'));
+        assert.equal(launch.source, 'auto-detected entrypoint');
+    });
+
+    it('reports a missing script instead of guessing', () => {
+        const launch = resolveLaunch({ command: ['node', 'dist/nope.js'], cwd });
+        assert.equal(launch.entry, null);
+        assert.match(launch.reason, /does not exist/);
+    });
+
+    it('reports a missing package.json script', () => {
+        writePackageJson({ scripts: {} });
+        const launch = resolveLaunch({ command: ['npm', 'start'], cwd });
+        assert.equal(launch.entry, null);
+        assert.match(launch.reason, /no "start" script/);
+    });
+
+    it('reports an unrecognized launcher rather than running the wrong thing', () => {
+        const launch = resolveLaunch({ command: ['tsx', 'src/main.ts'], cwd });
+        assert.equal(launch.entry, null);
+        assert.match(launch.reason, /unrecognized start command/);
+    });
+
+    it('stops on self-referential scripts', () => {
+        writePackageJson({ scripts: { start: 'npm start' } });
+        const launch = resolveLaunch({ command: ['npm', 'start'], cwd });
+        assert.equal(launch.entry, null);
+        assert.match(launch.reason, /indirection/);
+    });
+});