@extension.dev/mcp 5.3.1 → 5.4.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "extension-mcp",
       "source": "./",
       "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox.",
-      "version": "5.3.1",
+      "version": "5.4.0",
       "category": "development",
       "author": {
         "name": "Cezar Augusto"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "extension-mcp",
   "description": "MCP tools for browser extension development: scaffold from 60+ templates, run the dev server with HMR, inspect the live DOM and logs, and publish store-ready builds for Chrome, Edge, and Firefox. Ships /extension, /extension-add, /extension-debug, and /extension-publish commands.",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "author": {
     "name": "Cezar Augusto",
     "email": "boss@cezaraugusto.net",

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 5.4.0
+
+The DevX swarm's non-blocker friction clusters, cleared: waiting is
+narrated, ports tell the truth, artifacts say where they are, and error
+prose explains the extension instead of the engine.
+
+### Added
+
+- `extension_wait` narrates its budget. `timeoutMs` is a documented
+  argument (default 45000, clamped 1000 to 50000; the legacy `timeout`
+  spelling stays as a deprecated alias), every result carries `budgetMs`
+  and `elapsedMs`, and a timeout says what WAS observed plus a
+  call-again hint instead of an opaque failure. The status splits
+  `compiled` from `browserAttached`, and a `noBrowser` build-only
+  session returns immediately with `buildOnly: true` and a plain
+  statement that no browser will ever attach.
+- `extension_build` with `zip: true` returns `zipPath`, the absolute
+  path of the file the engine actually wrote (its name sanitizer strips
+  punctuation, so the filename rarely matches the project name), and
+  `zipSourcePath` for `zipSource: true`. When a zip cannot be located
+  after a successful build the result says so in `zipPathNote` instead
+  of omitting the field silently.
+
+### Fixed
+
+- `extension_dev` reports the actually-bound port. The engine's
+  ready.json carries the bound port from its first stamp, so dev reads
+  it after the health window and re-registers the session with the true
+  port; when the stamp has not landed yet, dev claims no port at all
+  and says `extension_wait` reports the bound one. dev and wait now
+  share one source of truth and cannot disagree about the same session.
+- `extension_build` warns when it writes over a live dev session's
+  dist: the dev browser may serve the production artifact until the
+  next recompile. The build is never blocked; the clobber is named.
+- `extension_inspect` classifies `.zip` files as archives and excludes
+  them from `shippableSize` and the 10MB store gate (the package is not
+  payload), with an `archiveNote` explaining the exclusion.
+- `extension_whoami` anchors its identity to the stored token that
+  `extension_login` minted: it does not follow the current working
+  directory, and the wording now says so.
+- `extension_open` explains a popup-less extension instead of relaying
+  the engine error: a manifest pre-check reports that nothing sets
+  `action.default_popup`, lists the surfaces the manifest DOES declare,
+  and points at the right next verb. Headless popup errors state the
+  exact headed path (`extension_dev` with `replace: true` and
+  `EXTENSION_HEADLESS=0`).
+- `extension_dev`'s `earlyOutput` drops V8 asm.js verdict lines (pure
+  noise); real errors are preserved.
+
 ## 5.3.1
 
 ### Added

package/dist/module.js

@@ -210,7 +210,7 @@ __webpack_require__.d(whoami_namespaceObject, {
     handler: ()=>whoami_handler,
     schema: ()=>whoami_schema
 });
-var package_namespaceObject = JSON.parse('{"rE":"5.3.1","El":{"OP":"^4.0.13"}}');
+var package_namespaceObject = JSON.parse('{"rE":"5.4.0","El":{"OP":"^4.0.13"}}');
 function scaffoldEnginePin(projectPath) {
     try {
         const pkg = JSON.parse(node_fs.readFileSync(node_path.join(projectPath, "package.json"), "utf8"));
@@ -623,6 +623,185 @@ function spawnExtensionCli(args, options) {
         }
     };
 }
+const sessions = new Map();
+function sessionKey(projectPath, browser) {
+    return `${node_path.resolve(projectPath)}::${browser}`;
+}
+function markerDir() {
+    return process.env.EXTENSION_MCP_SESSION_DIR || node_path.join(node_os.tmpdir(), "extension-dev-mcp-sessions");
+}
+function markerPath(projectPath, browser) {
+    const digest = node_crypto.createHash("sha1").update(sessionKey(projectPath, browser)).digest("hex").slice(0, 16);
+    return node_path.join(markerDir(), `${digest}.json`);
+}
+function removeSessionMarker(projectPath, browser) {
+    try {
+        node_fs.rmSync(markerPath(projectPath, browser), {
+            force: true
+        });
+    } catch  {}
+}
+function listSessionMarkers() {
+    let files;
+    try {
+        files = node_fs.readdirSync(markerDir());
+    } catch  {
+        return [];
+    }
+    const out = [];
+    for (const file of files)if (file.endsWith(".json")) try {
+        const parsed = JSON.parse(node_fs.readFileSync(node_path.join(markerDir(), file), "utf8"));
+        if ("string" == typeof parsed?.projectPath && "string" == typeof parsed?.browser) out.push(parsed);
+    } catch  {}
+    return out;
+}
+function registerSession(info) {
+    sessions.set(sessionKey(info.projectPath, info.browser), info);
+    try {
+        node_fs.mkdirSync(markerDir(), {
+            recursive: true
+        });
+        node_fs.writeFileSync(markerPath(info.projectPath, info.browser), JSON.stringify({
+            ...info,
+            projectPath: node_path.resolve(info.projectPath),
+            registeredAt: new Date().toISOString()
+        }));
+    } catch  {}
+}
+function getSession(projectPath, browser) {
+    return sessions.get(sessionKey(projectPath, browser));
+}
+function findSessionInfo(projectPath, browser) {
+    const inMemory = sessions.get(sessionKey(projectPath, browser));
+    if (inMemory) return inMemory;
+    const resolved = node_path.resolve(projectPath);
+    for (const marker of listSessionMarkers())if (node_path.resolve(marker.projectPath) === resolved && marker.browser === browser) return marker;
+}
+function removeSession(projectPath, browser) {
+    sessions.delete(sessionKey(projectPath, browser));
+}
+function listSessions() {
+    return Array.from(sessions.values());
+}
+function contractSightings(projectPath) {
+    const root = node_path.resolve(projectPath, "dist", "extension-js");
+    let dirs;
+    try {
+        dirs = node_fs.readdirSync(root);
+    } catch  {
+        return [];
+    }
+    const sightings = [];
+    for (const dir of dirs){
+        const readyPath = node_path.join(root, dir, "ready.json");
+        try {
+            const stat = node_fs.statSync(readyPath);
+            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+            if (contract?.status !== "ready") continue;
+            sightings.push({
+                browser: dir,
+                mtimeMs: stat.mtimeMs,
+                pid: "number" == typeof contract.pid ? contract.pid : void 0
+            });
+        } catch  {}
+    }
+    return sightings;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch  {
+        return false;
+    }
+}
+function knownSessionBrowsers(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const browsers = [];
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
+    for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
+    return Array.from(new Set(browsers));
+}
+function liveProjectSessions(projectPath) {
+    const resolved = node_path.resolve(projectPath);
+    const out = new Map();
+    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) {
+        if (pidAlive(session.pid)) out.set(session.browser, {
+            browser: session.browser,
+            pid: session.pid,
+            source: "registry"
+        });
+    }
+    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && pidAlive(sighting.pid)) {
+        if (!out.has(sighting.browser)) out.set(sighting.browser, {
+            browser: sighting.browser,
+            pid: sighting.pid,
+            source: "contract"
+        });
+    }
+    return [
+        ...out.values()
+    ];
+}
+function deadReadySession(projectPath) {
+    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && !pidAlive(sighting.pid)) return {
+        browser: sighting.browser,
+        pid: sighting.pid
+    };
+    return null;
+}
+function browserExitStamp(projectPath, browser, since) {
+    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+    try {
+        const stat = node_fs.statSync(readyPath);
+        if (stat.mtimeMs < since) return null;
+        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+        const exited = contract?.code === "browser_exited" || contract?.browserExitCode !== void 0 || contract?.browserExitedAt !== void 0;
+        if (contract?.status === "error" && exited) return {
+            code: contract.code,
+            browserExitCode: contract.browserExitCode ?? null,
+            browserExitedAt: contract.browserExitedAt
+        };
+    } catch  {}
+    return null;
+}
+function contractBoundPort(projectPath, browser, since) {
+    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
+    try {
+        const stat = node_fs.statSync(readyPath);
+        if (stat.mtimeMs < since) return null;
+        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
+        return "number" == typeof contract?.port && Number.isFinite(contract.port) ? contract.port : null;
+    } catch  {
+        return null;
+    }
+}
+function resolveSessionBrowser(projectPath, explicit, fallback = "chrome") {
+    if (explicit) return {
+        browser: explicit,
+        source: "explicit"
+    };
+    const resolved = node_path.resolve(projectPath);
+    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
+    if (mine.length > 0) return {
+        browser: mine[mine.length - 1].browser,
+        source: "session"
+    };
+    const sightings = contractSightings(projectPath).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+    const live = sightings.filter((s)=>void 0 === s.pid || pidAlive(s.pid));
+    if (live.length > 0) return {
+        browser: live[0].browser,
+        source: "contract"
+    };
+    if (sightings.length > 0) return {
+        browser: sightings[0].browser,
+        source: "stale"
+    };
+    return {
+        browser: fallback,
+        source: "fallback"
+    };
+}
 function readBuildSummary(projectPath, browser, since) {
     const file = node_path.resolve(projectPath, "dist", "extension-js", browser, "build-summary.json");
     try {
@@ -678,6 +857,46 @@ function builtEntrypoints(distDir) {
     });
     return out;
 }
+function engineSanitize(input) {
+    return input.toLowerCase().replace(/[^a-z0-9 ]/gi, "").trim().replace(/\s+/g, "-");
+}
+function newestZip(dir, since, match) {
+    try {
+        const fresh = node_fs.readdirSync(dir).filter((name)=>name.endsWith(".zip") && (!match || match(name))).map((name)=>{
+            const full = node_path.join(dir, name);
+            return {
+                full,
+                mtimeMs: node_fs.statSync(full).mtimeMs
+            };
+        }).filter((entry)=>entry.mtimeMs >= since).sort((a, b)=>b.mtimeMs - a.mtimeMs);
+        return fresh[0]?.full ?? null;
+    } catch  {
+        return null;
+    }
+}
+function engineZipBase(distDir, projectPath) {
+    let manifest = {};
+    try {
+        manifest = JSON.parse(node_fs.readFileSync(node_path.join(distDir, "manifest.json"), "utf8"));
+    } catch  {}
+    const rawName = "string" != typeof manifest.name || /^__MSG_.+__$/.test(manifest.name) ? node_path.basename(node_path.resolve(projectPath)) : manifest.name;
+    const version = "string" == typeof manifest.version && manifest.version ? manifest.version : "0.0.0";
+    return `${engineSanitize(rawName)}-${version}`;
+}
+function locateDistZip(projectPath, browser, zipFilename, since) {
+    const distDir = node_path.resolve(projectPath, "dist", browser);
+    const base = zipFilename ? engineSanitize(zipFilename) : engineZipBase(distDir, projectPath);
+    const expected = node_path.join(distDir, `${base}.zip`);
+    if (node_fs.existsSync(expected)) return expected;
+    return newestZip(distDir, since);
+}
+function locateSourceZip(projectPath, browser, since) {
+    const distDir = node_path.resolve(projectPath, "dist", browser);
+    const distRoot = node_path.resolve(projectPath, "dist");
+    const expected = node_path.join(distRoot, `${engineZipBase(distDir, projectPath)}-source.zip`);
+    if (node_fs.existsSync(expected)) return expected;
+    return newestZip(distRoot, since, (name)=>name.endsWith("-source.zip"));
+}
 const build_schema = {
     name: "extension_build",
     description: "Build a browser extension for production. Outputs to dist/<browser>/. Optionally creates .zip for store submission.",
@@ -816,6 +1035,8 @@ async function build_handler(args) {
         duration: Date.now() - start,
         hint: "Fix the errors above, then build again. Run extension_manifest_validate for the full report. To build anyway (for example to inspect the broken output), pass skipValidation: true."
     });
+    const clobberedSessions = liveProjectSessions(args.projectPath).filter((session)=>session.browser === browser);
+    const warnings = clobberedSessions.map((session)=>`A live dev session (pid ${session.pid}) is running on this project for ${browser}, and this build wrote over its dist/${browser} output. The dev browser may now serve the production artifact instead of the dev build until the next recompile. Run extension_stop, or let dev recompile on the next source change, to resolve it.`);
     const cliArgs = [
         "build",
         args.projectPath,
@@ -858,6 +1079,9 @@ async function build_handler(args) {
                 manifestWarnings: preflight.warnings
             } : {},
             ...buildWarnings,
+            ...warnings.length ? {
+                warnings
+            } : {},
             duration,
             output: lastLines(out, 12),
             hint: "The bundler exited 0 but did not emit these files. Check that the manifest paths match what the build produces, and that nothing references a file outside the source tree."
@@ -884,7 +1108,26 @@ async function build_handler(args) {
                     productionDivergence: divergence
                 } : {};
             })(),
+            ...warnings.length ? {
+                warnings
+            } : {},
             zip: args.zip ?? false,
+            ...args.zip ? (()=>{
+                const zipPath = locateDistZip(args.projectPath, browser, args.zipFilename, start);
+                return zipPath ? {
+                    zipPath
+                } : {
+                    zipPathNote: `zip: true was requested and the build succeeded, but no .zip file could be located in dist/${browser}. The engine may not have packaged it; check the build output below.`
+                };
+            })() : {},
+            ...args.zipSource ? (()=>{
+                const zipSourcePath = locateSourceZip(args.projectPath, browser, start);
+                return zipSourcePath ? {
+                    zipSourcePath
+                } : {
+                    zipSourcePathNote: "zipSource: true was requested and the build succeeded, but no *-source.zip file could be located in dist/. The engine may not have packaged it; check the build output below."
+                };
+            })() : {},
             duration,
             output: lastLines(out, 12)
         });
@@ -894,172 +1137,13 @@ async function build_handler(args) {
         success: false,
         browser,
         error: message.slice(0, 1200),
+        ...warnings.length ? {
+            warnings
+        } : {},
         duration,
         hint: "Check that the project has a valid src/manifest.json and its dependencies are installed (extension_dev auto-installs; build does not)."
     });
 }
-const sessions = new Map();
-function sessionKey(projectPath, browser) {
-    return `${node_path.resolve(projectPath)}::${browser}`;
-}
-function markerDir() {
-    return process.env.EXTENSION_MCP_SESSION_DIR || node_path.join(node_os.tmpdir(), "extension-dev-mcp-sessions");
-}
-function markerPath(projectPath, browser) {
-    const digest = node_crypto.createHash("sha1").update(sessionKey(projectPath, browser)).digest("hex").slice(0, 16);
-    return node_path.join(markerDir(), `${digest}.json`);
-}
-function removeSessionMarker(projectPath, browser) {
-    try {
-        node_fs.rmSync(markerPath(projectPath, browser), {
-            force: true
-        });
-    } catch  {}
-}
-function listSessionMarkers() {
-    let files;
-    try {
-        files = node_fs.readdirSync(markerDir());
-    } catch  {
-        return [];
-    }
-    const out = [];
-    for (const file of files)if (file.endsWith(".json")) try {
-        const parsed = JSON.parse(node_fs.readFileSync(node_path.join(markerDir(), file), "utf8"));
-        if ("string" == typeof parsed?.projectPath && "string" == typeof parsed?.browser) out.push(parsed);
-    } catch  {}
-    return out;
-}
-function registerSession(info) {
-    sessions.set(sessionKey(info.projectPath, info.browser), info);
-    try {
-        node_fs.mkdirSync(markerDir(), {
-            recursive: true
-        });
-        node_fs.writeFileSync(markerPath(info.projectPath, info.browser), JSON.stringify({
-            ...info,
-            projectPath: node_path.resolve(info.projectPath),
-            registeredAt: new Date().toISOString()
-        }));
-    } catch  {}
-}
-function getSession(projectPath, browser) {
-    return sessions.get(sessionKey(projectPath, browser));
-}
-function removeSession(projectPath, browser) {
-    sessions.delete(sessionKey(projectPath, browser));
-}
-function listSessions() {
-    return Array.from(sessions.values());
-}
-function contractSightings(projectPath) {
-    const root = node_path.resolve(projectPath, "dist", "extension-js");
-    let dirs;
-    try {
-        dirs = node_fs.readdirSync(root);
-    } catch  {
-        return [];
-    }
-    const sightings = [];
-    for (const dir of dirs){
-        const readyPath = node_path.join(root, dir, "ready.json");
-        try {
-            const stat = node_fs.statSync(readyPath);
-            const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-            if (contract?.status !== "ready") continue;
-            sightings.push({
-                browser: dir,
-                mtimeMs: stat.mtimeMs,
-                pid: "number" == typeof contract.pid ? contract.pid : void 0
-            });
-        } catch  {}
-    }
-    return sightings;
-}
-function pidAlive(pid) {
-    try {
-        process.kill(pid, 0);
-        return true;
-    } catch  {
-        return false;
-    }
-}
-function knownSessionBrowsers(projectPath) {
-    const resolved = node_path.resolve(projectPath);
-    const browsers = [];
-    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) browsers.push(session.browser);
-    for (const sighting of contractSightings(projectPath))if (void 0 === sighting.pid || pidAlive(sighting.pid)) browsers.push(sighting.browser);
-    return Array.from(new Set(browsers));
-}
-function liveProjectSessions(projectPath) {
-    const resolved = node_path.resolve(projectPath);
-    const out = new Map();
-    for (const session of listSessions())if (node_path.resolve(session.projectPath) === resolved) {
-        if (pidAlive(session.pid)) out.set(session.browser, {
-            browser: session.browser,
-            pid: session.pid,
-            source: "registry"
-        });
-    }
-    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && pidAlive(sighting.pid)) {
-        if (!out.has(sighting.browser)) out.set(sighting.browser, {
-            browser: sighting.browser,
-            pid: sighting.pid,
-            source: "contract"
-        });
-    }
-    return [
-        ...out.values()
-    ];
-}
-function deadReadySession(projectPath) {
-    for (const sighting of contractSightings(projectPath))if (void 0 !== sighting.pid && !pidAlive(sighting.pid)) return {
-        browser: sighting.browser,
-        pid: sighting.pid
-    };
-    return null;
-}
-function browserExitStamp(projectPath, browser, since) {
-    const readyPath = node_path.resolve(projectPath, "dist", "extension-js", browser, "ready.json");
-    try {
-        const stat = node_fs.statSync(readyPath);
-        if (stat.mtimeMs < since) return null;
-        const contract = JSON.parse(node_fs.readFileSync(readyPath, "utf8"));
-        const exited = contract?.code === "browser_exited" || contract?.browserExitCode !== void 0 || contract?.browserExitedAt !== void 0;
-        if (contract?.status === "error" && exited) return {
-            code: contract.code,
-            browserExitCode: contract.browserExitCode ?? null,
-            browserExitedAt: contract.browserExitedAt
-        };
-    } catch  {}
-    return null;
-}
-function resolveSessionBrowser(projectPath, explicit, fallback = "chrome") {
-    if (explicit) return {
-        browser: explicit,
-        source: "explicit"
-    };
-    const resolved = node_path.resolve(projectPath);
-    const mine = listSessions().filter((s)=>node_path.resolve(s.projectPath) === resolved);
-    if (mine.length > 0) return {
-        browser: mine[mine.length - 1].browser,
-        source: "session"
-    };
-    const sightings = contractSightings(projectPath).sort((a, b)=>b.mtimeMs - a.mtimeMs);
-    const live = sightings.filter((s)=>void 0 === s.pid || pidAlive(s.pid));
-    if (live.length > 0) return {
-        browser: live[0].browser,
-        source: "contract"
-    };
-    if (sightings.length > 0) return {
-        browser: sightings[0].browser,
-        source: "stale"
-    };
-    return {
-        browser: fallback,
-        source: "fallback"
-    };
-}
 const stop_schema = {
     name: "extension_stop",
     description: "Stop a running dev, start, or preview session: terminates the dev server and the browser it launched. Counterpart to extension_dev/extension_start. Call it when you are done verifying so sessions do not accumulate.",
@@ -1380,7 +1464,8 @@ async function dev_handler(args) {
         browser,
         port: args.port,
         projectPath: args.projectPath,
-        command: "dev"
+        command: "dev",
+        noBrowser: Boolean(args.noBrowser)
     });
     child.on("exit", ()=>removeSession(args.projectPath, browser));
     await new Promise((resolve)=>setTimeout(resolve, 3000));
@@ -1437,11 +1522,30 @@ async function dev_handler(args) {
         allowEval: Boolean(args.allowEval),
         unlocked: allowControl ? args.allowEval ? `${controlVerbs}, eval` : controlVerbs : "none (read-only: logs, source_inspect, wait, doctor)"
     };
+    const boundPort = contractBoundPort(args.projectPath, browser, spawnedAt);
+    if (null !== boundPort && boundPort !== args.port) registerSession({
+        pid,
+        browser,
+        port: boundPort,
+        projectPath: args.projectPath,
+        command: "dev",
+        noBrowser: Boolean(args.noBrowser)
+    });
+    const portReport = null !== boundPort ? {
+        port: boundPort,
+        ...void 0 !== args.port && args.port !== boundPort ? {
+            requestedPort: args.port,
+            portNote: `Requested port ${args.port} was not available; the dev server bound ${boundPort} (read from the engine's ready.json contract, the same source extension_wait reports).`
+        } : {}
+    } : {
+        requestedPort: args.port ?? 8080,
+        portNote: "The engine has not stamped its ready.json contract yet, so the bound port is not known at response time (a taken port makes the server bind the next free one). extension_wait reports the bound port from that contract once it lands; requestedPort above is only what was asked for."
+    };
     return JSON.stringify({
         ok: true,
         pid,
         browser,
-        port: args.port ?? 8080,
+        ...portReport,
         projectPath: args.projectPath,
         status: "started",
         ...replaced.length > 0 ? {
@@ -1451,7 +1555,7 @@ async function dev_handler(args) {
             } : {}
         } : {},
         capabilities,
-        hint: "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser.",
+        hint: args.noBrowser ? "Build-only session (noBrowser: true): no browser will launch, so no runtime will ever attach. extension_wait returns as soon as the first compile lands (compiled: true, browserAttached: false) instead of waiting out its budget; do not wait for a browser. The control verbs (storage/reload/open/dom_inspect/eval) need a live browser and will not work against this session. When you are done, call extension_stop to shut down the dev server." : "Use extension_wait to check when the extension is fully loaded, then extension_source_inspect to inspect the live state. " + (allowControl ? `Control channel is ON: extension_${controlVerbs.split(", ").join("/extension_")}${args.allowEval ? "/extension_eval" : ""} will work against this session.` : "Control channel is OFF: extension_storage/reload/open/dom_inspect need allowControl: true, and extension_eval needs allowEval: true (which also implies allowControl). To unlock them, call extension_dev again with the flag you need plus replace: true (it stops this session first); a plain second call is refused so the session does not fork.") + " When you are done, call extension_stop to shut down the dev server and browser.",
         earlyOutput: denoiseEarlyOutput(earlyOutput).slice(0, 500),
         logPath
     });
@@ -1463,7 +1567,10 @@ function denoiseEarlyOutput(raw) {
         /^npm warn config/i,
         /V8: .*Invalid asm\.js/i,
         /^\(node:\d+\) V8:/i,
-        /Use `node --trace-warnings/i
+        /Use `node --trace-warnings/i,
+        /Invalid asm\.js:/i,
+        /Linking failure in asm\.js/i,
+        /Successfully compiled asm\.js/i
     ];
     return raw.split("\n").filter((line)=>!NOISE.some((re)=>re.test(line.trim()))).join("\n").replace(/\n{2,}/g, "\n").trimStart();
 }
@@ -2307,6 +2414,9 @@ function walkDir(dir, base = "") {
                 else if ([
                     ".map"
                 ].includes(ext)) type = "sourcemap";
+                else if ([
+                    ".zip"
+                ].includes(ext)) type = "archive";
                 entries.push({
                     path: rel,
                     size: stat.size,
@@ -2347,7 +2457,8 @@ async function inspect_handler(args) {
     }
     const sourcemapSize = byType.sourcemap?.size ?? 0;
     const buildType = sourcemapSize > 0 ? "development" : "production";
-    const shippableSize = totalSize - sourcemapSize;
+    const archiveSize = byType.archive?.size ?? 0;
+    const shippableSize = totalSize - sourcemapSize - archiveSize;
     const sizeByPath = new Map(files.map((f)=>[
             f.path,
             f.size
@@ -2377,7 +2488,7 @@ async function inspect_handler(args) {
     });
     const PROMO_RE = /(screenshot|promo|marquee|tile|banner|preview)[-_.]?\d*\.(png|jpe?g|webp|gif)$/i;
     const sizeWarnings = [];
-    for (const f of files)if ("sourcemap" !== f.type) {
+    for (const f of files)if ("sourcemap" !== f.type && "archive" !== f.type) {
         if (PROMO_RE.test(f.path)) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) looks like a store-listing promo image shipped inside the extension package, move it out of the bundled sources so it does not inflate the store zip.`);
         else if ("image" === f.type && !f.path.includes("icon") && f.size > 51200 && shippableSize > 0 && f.size / shippableSize > 0.25) sizeWarnings.push(`${f.path} (${formatBytes(f.size)}) is ${Math.round(f.size / shippableSize * 100)}% of the shipped bundle, unusually large for a shipped asset.`);
     }
@@ -2397,6 +2508,9 @@ async function inspect_handler(args) {
         ..."development" === buildType ? {
             note: `This dist contains ${formatBytes(sourcemapSize)} of sourcemaps and looks like a dev build; run extension_build for production sizes. shippableSize excludes sourcemaps.`
         } : {},
+        ...archiveSize > 0 ? {
+            archiveNote: `This dist contains ${formatBytes(archiveSize)} of .zip archive(s) (store packaging output, written into dist by zip builds). shippableSize excludes them so the packaged copy does not double-count the files it contains.`
+        } : {},
         manifest: {
             name: manifest.name,
             version: manifest.version,
@@ -2429,7 +2543,7 @@ async function inspect_handler(args) {
             has128Icon: "string" == typeof manifest.icons?.["128"],
             noSourceMaps: !files.some((f)=>"sourcemap" === f.type),
             noPromoAssets: !files.some((f)=>PROMO_RE.test(f.path)),
-            under10MB: totalSize < 10485760
+            under10MB: totalSize - archiveSize < 10485760
         }
     };
     return JSON.stringify(result);
@@ -3909,6 +4023,57 @@ function surfaceDocument(projectPath, browser, surface) {
     }
     return null;
 }
+const SURFACE_MANIFEST_KEYS = {
+    popup: "action.default_popup",
+    options: "options_ui.page (or options_page)",
+    sidebar: "side_panel.default_path (or sidebar_action.default_panel)",
+    newtab: "chrome_url_overrides.newtab",
+    history: "chrome_url_overrides.history",
+    bookmarks: "chrome_url_overrides.bookmarks"
+};
+function declaredSurfaces(projectPath, browser) {
+    const candidates = [
+        node_path.join(projectPath, "dist", browser, "manifest.json"),
+        node_path.join(projectPath, "dist", "manifest.json"),
+        node_path.join(projectPath, "src", "manifest.json"),
+        node_path.join(projectPath, "manifest.json")
+    ];
+    const readable = candidates.some((file)=>{
+        try {
+            JSON.parse(node_fs.readFileSync(file, "utf8"));
+            return true;
+        } catch  {
+            return false;
+        }
+    });
+    if (!readable) return null;
+    return Object.keys(SURFACE_MANIFEST_KEYS).filter((s)=>null !== surfaceDocument(projectPath, browser, s));
+}
+function missingSurfaceError(projectPath, browser, surface, consequence) {
+    const declared = declaredSurfaces(projectPath, browser);
+    if (null === declared) return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoSurfaceDocument",
+            message: `No readable manifest was found for this project (checked dist/${browser}, dist, src, and the project root), so the ${surface} document cannot be resolved.`
+        },
+        hint: "Check projectPath, or build the project first (extension_build)."
+    });
+    const key = SURFACE_MANIFEST_KEYS[surface] ?? surface;
+    const others = declared.filter((s)=>s !== surface);
+    const nextVerb = "popup" === surface ? 'To exercise the toolbar button of a popup-less extension, call extension_open with surface: "action", which replays chrome.action.onClicked. To give the extension a popup, set action.default_popup in the manifest and rebuild.' : `To add one, set ${key} in the manifest and rebuild.`;
+    return JSON.stringify({
+        ok: false,
+        error: {
+            name: "NoSurfaceDocument",
+            message: `This extension declares no ${surface}: nothing in its manifest sets ${key}, ${consequence}. That is how the extension is built, not a failure of the session or the tooling.`
+        },
+        ...others.length ? {
+            declaredSurfaces: others
+        } : {},
+        hint: (others.length ? `Surfaces this extension does declare: ${others.join(", ")}; extension_open can target those. ` : "The manifest declares no other UI surface documents either. ") + nextVerb
+    });
+}
 const POPUP_MIN = 25;
 const POPUP_MAX_WIDTH = 800;
 const POPUP_MAX_HEIGHT = 600;
@@ -3967,14 +4132,7 @@ async function applyPopupBounds(projectPath, browser, targetId) {
 }
 async function openSurfaceAsTab(projectPath, browser, surface) {
     const doc = surfaceDocument(projectPath, browser, surface);
-    if (!doc) return JSON.stringify({
-        ok: false,
-        error: {
-            name: "NoSurfaceDocument",
-            message: `The manifest declares no document for surface "${surface}", so there is no page to render as a tab.`
-        },
-        hint: "Check the manifest: popup needs action.default_popup, options needs options_ui.page or options_page, sidebar needs side_panel.default_path."
-    });
+    if (!doc) return missingSurfaceError(projectPath, browser, surface, "so there is no page to render as a tab");
     const id = await resolveExtensionId(projectPath, browser);
     if (!id) return JSON.stringify({
         ok: false,
@@ -4087,6 +4245,10 @@ async function open_handler(args) {
             hint: declared.length ? `Declared commands are: ${declared.join(", ")}. Check for a typo, or add "${args.name}" to the manifest.` : "This manifest declares no commands at all. Add a `commands` block, rebuild, then retry."
         });
     }
+    if ("popup" === args.surface) {
+        const declared = declaredSurfaces(args.projectPath, browser);
+        if (declared && !declared.includes("popup")) return missingSurfaceError(args.projectPath, browser, "popup", "so there is no popup to open");
+    }
     const cli = [
         "open",
         args.surface,
@@ -4110,12 +4272,12 @@ async function open_handler(args) {
                 try {
                     const parsedFallback = JSON.parse(fallback);
                     if (parsedFallback?.ok) {
-                        parsedFallback.note = "The dev browser is headless (EXTENSION_HEADLESS), which has no window to attach a popup/sidebar to, so the surface was rendered as a tab instead. Pass asTab: false and relaunch headed for a real popup window.";
+                        parsedFallback.note = "The dev browser is headless (EXTENSION_HEADLESS=1), and a real popup/sidebar window can only open in a headed session, so the surface was rendered as a tab instead. For the real window, start a headed session: extension_dev with replace: true, with EXTENSION_HEADLESS=0 (or unset) in the environment, then open the surface again without asTab.";
                         return JSON.stringify(parsedFallback);
                     }
                 } catch  {}
             }
-            if (!parsed.hint) parsed.hint = /user gesture/i.test(msg) ? "This surface can only open from a real user gesture, which headless automation cannot produce. Retry with asTab: true to render the surface document in a tab instead." : "The dev browser is running headless (EXTENSION_HEADLESS), which has no visible window to attach a popup/sidebar to. Retry with asTab: true to render the surface document in a tab, or relaunch a headed dev session for a real popup window.";
+            if (!parsed.hint) parsed.hint = /user gesture/i.test(msg) ? "This surface can only open from a real user gesture, which headless automation cannot produce. Retry with asTab: true to render the surface document in a tab instead." : "The dev browser is running headless (EXTENSION_HEADLESS=1), and a popup/sidebar window needs a headed session. Retry with asTab: true to render the surface document in a tab, or start a headed session for the real window: extension_dev with replace: true, with EXTENSION_HEADLESS=0 (or unset) in the environment.";
             return JSON.stringify(parsed);
         }
     } catch  {}
@@ -5227,6 +5389,8 @@ async function doctor_handler(args) {
     }
 }
 const SAFE_CEILING_MS = 50000;
+const DEFAULT_TIMEOUT_MS = 45000;
+const MIN_TIMEOUT_MS = 1000;
 function wait_isAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -5237,7 +5401,7 @@ function wait_isAlive(pid) {
 }
 const wait_schema = {
     name: "extension_wait",
-    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status. A single call is bounded to ~50s to stay under the MCP client request timeout; if it returns status:'timeout', call it again to keep waiting (polling resumes on the same contract).",
+    description: "Wait for a running dev or start session to be ready. Polls the ready.json contract file and returns structured status with two separate facts: compiled (the compiler finished) and browserAttached (the extension's runtime connected from a live browser). Every result reports budgetMs (this call's wait budget) and elapsedMs; on status:'timeout' call again to keep waiting (polling resumes on the same contract). In a noBrowser (build-only) session it returns as soon as the compile lands instead of waiting for a browser that will never attach. Ports in the result come from the ready contract, so they always match what the dev server actually bound.",
     inputSchema: {
         type: "object",
         properties: {
@@ -5249,10 +5413,14 @@ const wait_schema = {
                 type: "string",
                 description: "Browser to check readiness for. Defaults to the active dev session's browser for this project."
             },
+            timeoutMs: {
+                type: "number",
+                default: DEFAULT_TIMEOUT_MS,
+                description: `Wait budget in milliseconds for this call. Default ${DEFAULT_TIMEOUT_MS}; clamped to ${MIN_TIMEOUT_MS}-${SAFE_CEILING_MS} (the ceiling keeps one call under the MCP client's 60s request timeout). On timeout the result reports elapsedMs plus what was observed (compiled, browserAttached); call again to keep waiting, polling resumes on the same contract.`
+            },
             timeout: {
                 type: "number",
-                default: 45000,
-                description: "Requested wait in milliseconds. Clamped to ~50s per call so it never exceeds the MCP client request timeout; call again to keep waiting for slower builds."
+                description: "Deprecated alias of timeoutMs, kept for callers that already pass it. timeoutMs wins when both are given."
             }
         },
         required: [
@@ -5262,26 +5430,47 @@ const wait_schema = {
 };
 async function wait_handler(args) {
     const { browser } = resolveSessionBrowser(args.projectPath, args.browser, "chrome");
-    const requested = args.timeout ?? 45000;
-    const timeout = Math.min(Math.max(requested, 1000), SAFE_CEILING_MS);
+    const requested = args.timeoutMs ?? args.timeout ?? DEFAULT_TIMEOUT_MS;
+    const budgetMs = Math.min(Math.max(requested, MIN_TIMEOUT_MS), SAFE_CEILING_MS);
     const clamped = requested > SAFE_CEILING_MS;
     const readyPath = node_path.resolve(args.projectPath, "dist", "extension-js", browser, "ready.json");
+    const buildOnly = findSessionInfo(args.projectPath, browser)?.noBrowser === true;
     const start = Date.now();
     const pollInterval = 1000;
     let sawCompiledButUnattached = false;
-    while(Date.now() - start < timeout){
+    let lastContractStatus = null;
+    while(Date.now() - start < budgetMs){
         try {
             const raw = node_fs.readFileSync(readyPath, "utf8");
             const contract = JSON.parse(raw);
+            lastContractStatus = contract.status;
             if ("ready" === contract.status) {
                 if ("number" == typeof contract.pid && !wait_isAlive(contract.pid)) return JSON.stringify({
                     status: "stale",
                     message: `ready.json reports ready but its dev-server pid ${contract.pid} is dead, the session exited. Restart with extension_dev; extension_doctor will confirm.`,
                     browser: contract.browser,
                     pid: contract.pid,
-                    waitDuration: Date.now() - start
+                    budgetMs,
+                    elapsedMs: Date.now() - start
                 });
                 const attached = "attached" === contract.runtime || "string" == typeof contract.executorAttachedAt;
+                if (!attached && buildOnly) return JSON.stringify({
+                    status: "ready",
+                    buildOnly: true,
+                    compiled: true,
+                    browserAttached: false,
+                    message: "Build-only session (noBrowser): the extension compiled and the dev server is live, but no browser was launched, so browserAttached will never become true. Do not call extension_wait again to wait for a browser. The control verbs (storage/reload/open/dom_inspect/eval) need a live browser and will not work against this session.",
+                    command: contract.command,
+                    browser: contract.browser,
+                    port: contract.port,
+                    pid: contract.pid,
+                    distPath: contract.distPath,
+                    manifestPath: contract.manifestPath,
+                    compiledAt: contract.compiledAt,
+                    startedAt: contract.startedAt,
+                    budgetMs,
+                    elapsedMs: Date.now() - start
+                });
                 if (!attached) {
                     await new Promise((r)=>setTimeout(r, pollInterval));
                     sawCompiledButUnattached = true;
@@ -5290,6 +5479,8 @@ async function wait_handler(args) {
                 const runtimeErrors = recentErrorLogs(args.projectPath, browser, 3);
                 return JSON.stringify({
                     status: "ready",
+                    compiled: true,
+                    browserAttached: true,
                     command: contract.command,
                     browser: contract.browser,
                     port: contract.port,
@@ -5298,7 +5489,8 @@ async function wait_handler(args) {
                     manifestPath: contract.manifestPath,
                     compiledAt: contract.compiledAt,
                     startedAt: contract.startedAt,
-                    waitDuration: Date.now() - start,
+                    budgetMs,
+                    elapsedMs: Date.now() - start,
                     ...runtimeErrors.length ? {
                         runtimeErrors,
                         warning: `Compiled and attached, but the extension is throwing at runtime (${runtimeErrors.length} recent error event${1 === runtimeErrors.length ? "" : "s"} above). Check extension_logs (level: error) or extension_doctor before trusting this session.`
@@ -5311,23 +5503,30 @@ async function wait_handler(args) {
                 errors: contract.errors,
                 code: contract.code,
                 browser: contract.browser,
-                waitDuration: Date.now() - start
+                budgetMs,
+                elapsedMs: Date.now() - start
             });
         } catch  {}
         await new Promise((resolve)=>setTimeout(resolve, pollInterval));
     }
     if (sawCompiledButUnattached) return JSON.stringify({
         status: "compiled-not-attached",
-        message: `The extension compiled, but the runtime executor never attached within ${timeout}ms. The build is fine; the browser side is not connected, so extension_eval/storage/reload/open will fail with "no executor connected".`,
+        compiled: true,
+        browserAttached: false,
+        message: `The extension compiled, but the runtime executor never attached within this call's ${budgetMs}ms budget. The build is fine; the browser side is not connected, so extension_eval/storage/reload/open will fail with "no executor connected".`,
         readyPath,
-        waitDuration: Date.now() - start,
+        budgetMs,
+        elapsedMs: Date.now() - start,
         hint: "This is usually transient: call extension_wait again. If it persists, stop and restart the session with extension_dev (a restart reliably reattaches); extension_doctor reports the executor leg."
     });
     return JSON.stringify({
         status: "timeout",
-        message: `Extension not ready after ${timeout}ms this call`,
+        compiled: false,
+        browserAttached: false,
+        message: "starting" === lastContractStatus ? `Not ready after ${budgetMs}ms this call: the dev server stamped its contract (status: starting) but the first compile has not landed yet.` : `Not ready after ${budgetMs}ms this call: no ready contract was observed at ${readyPath}, so neither the compile nor a browser attach has been seen.`,
         readyPath,
-        waitDuration: Date.now() - start,
+        budgetMs,
+        elapsedMs: Date.now() - start,
         clamped: clamped ? `requested ${requested}ms was clamped to ${SAFE_CEILING_MS}ms to stay under the MCP client request timeout` : void 0,
         hint: "Still building, call extension_wait again to keep waiting (it resumes polling the same contract). If it never readies, check the dev process with extension_doctor."
     });
@@ -5936,7 +6135,7 @@ async function login_handler(args) {
 }
 const whoami_schema = {
     name: "extension_whoami",
-    description: "Report the locally stored extension.dev login (workspace/project and token expiry) without revealing the token. Returns logged-out status when no credentials are stored.",
+    description: "Report the identity carried by the locally stored extension.dev token that extension_login minted (workspace/project scoped), plus its expiry, without revealing the token. The identity comes from that stored token alone; it does not change with the current working directory or whichever project folder you are in. Returns logged-out status when no credentials are stored.",
     inputSchema: {
         type: "object",
         properties: {}
@@ -5961,7 +6160,7 @@ async function whoami_handler() {
         expiresAt: creds.expiresAt ? new Date(1000 * creds.expiresAt).toISOString() : null,
         expiresInSeconds: creds.expiresAt ? creds.expiresAt - now : null,
         expired,
-        message: expired ? "Stored token has expired. Run extension_login to refresh it." : `Logged in to ${creds.workspaceSlug}/${creds.projectSlug}.`
+        message: expired ? "The stored token has expired. Run extension_login to refresh it." : `Logged in as ${creds.workspaceSlug}/${creds.projectSlug}, per the token extension_login stored on this machine. That token is what scopes the identity: it does not follow the current working directory or project folder.`
     });
 }
 const logout_schema = {

package/dist/src/lib/process-manager.d.ts

@@ -3,5 +3,6 @@ export declare function removeSessionMarker(projectPath: string, browser: string
 export declare function listSessionMarkers(): ProcessInfo[];
 export declare function registerSession(info: ProcessInfo): void;
 export declare function getSession(projectPath: string, browser: string): ProcessInfo | undefined;
+export declare function findSessionInfo(projectPath: string, browser: string): ProcessInfo | undefined;
 export declare function removeSession(projectPath: string, browser: string): void;
 export declare function listSessions(): ProcessInfo[];

package/dist/src/lib/session-browser.d.ts

@@ -19,4 +19,5 @@ export interface BrowserExitStamp {
     browserExitedAt?: string;
 }
 export declare function browserExitStamp(projectPath: string, browser: string, since: number): BrowserExitStamp | null;
+export declare function contractBoundPort(projectPath: string, browser: string, since: number): number | null;
 export declare function resolveSessionBrowser(projectPath: string, explicit: string | undefined, fallback?: string): ResolvedBrowser;

package/dist/src/lib/types.d.ts

@@ -43,7 +43,7 @@ export interface TemplatesMetaV2 {
     templates: TemplateMeta[];
 }
 export interface ReadyContract {
-    status: "ready" | "error" | "stopped";
+    status: "starting" | "ready" | "error" | "stopped";
     message?: string;
     errors?: string[];
     code?: string;
@@ -56,9 +56,13 @@ export interface ReadyContract {
     distPath?: string;
     manifestPath?: string;
     port?: number | null;
+    host?: string;
+    cdpPort?: number;
     pid?: number;
     ts?: string;
     compiledAt?: string | null;
+    executorAttachedAt?: string;
+    runtime?: string;
 }
 export interface ProcessInfo {
     pid: number;
@@ -66,5 +70,6 @@ export interface ProcessInfo {
     port?: number;
     projectPath: string;
     command: "dev" | "start" | "preview";
+    noBrowser?: boolean;
 }
 export type BrowserType = "chrome" | "edge" | "firefox" | "chromium-based" | "gecko-based";

package/dist/src/tools/wait.d.ts

@@ -12,11 +12,15 @@ export declare const schema: {
                 type: string;
                 description: string;
             };
-            timeout: {
+            timeoutMs: {
                 type: string;
                 default: number;
                 description: string;
             };
+            timeout: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };
@@ -24,5 +28,6 @@ export declare const schema: {
 export declare function handler(args: {
     projectPath: string;
     browser?: string;
+    timeoutMs?: number;
     timeout?: number;
 }): Promise<string>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@extension.dev/mcp",
   "type": "module",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "description": "MCP server that lets AI agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex) build, run, inspect, and publish browser extensions. 32 tools for scaffolding, live DOM inspection, log streaming, and store-ready builds across Chrome, Edge, Firefox, Safari, and every Chromium- or Gecko-based browser (Brave, Opera, Vivaldi, Yandex, Waterfox, LibreWolf). Powered by extension.dev and Extension.js.",
   "mcpName": "io.github.extensiondev/mcp",
   "license": "MIT",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://extension.dev",
-  "version": "5.3.1",
+  "version": "5.4.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@extension.dev/mcp",
-      "version": "5.3.1",
+      "version": "5.4.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"