@muggleai/works 5.28.0-staging.251 → 5.28.0-staging.252

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "muggleai",
       "source": "./plugin",
       "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-      "version": "5.28.0-staging.251"
+      "version": "5.28.0-staging.252"
     }
   ]
 }

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.28.0-staging.251",
+  "version": "5.28.0-staging.252",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.codex-mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.28.0-staging.251",
+        "@muggleai/works@5.28.0-staging.252",
         "serve"
       ],
       "env": {

package/dist/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "muggle",
-  "version": "5.28.0-staging.251",
+  "version": "5.28.0-staging.252",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
   "author": {
     "name": "Muggle AI",

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.28.0-staging.251",
+  "version": "5.28.0-staging.252",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.28.0-staging.251",
+        "@muggleai/works@5.28.0-staging.252",
         "serve"
       ]
     }

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
   "release": "5.26.0",
-  "buildId": "run-251-1",
-  "commitSha": "1e6cfe30749385ff8e553c34e1f43494668d3cb2",
-  "buildTime": "2026-10-30T04:38:24Z",
+  "buildId": "run-252-1",
+  "commitSha": "b14f1bedf8857a826ae5719d26677793c866a161",
+  "buildTime": "2026-10-30T06:23:28Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@muggleai/works",
   "mcpName": "io.github.multiplex-ai/muggle",
-  "version": "5.28.0-staging.251",
+  "version": "5.28.0-staging.252",
   "description": "13 years of Microsoft hyperscale engineering, packaged as a harness for your AI coding agent.",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,7 @@
     "bin/muggle.js",
     ".claude-plugin/marketplace.json",
     "scripts/postinstall.mjs",
+    "scripts/post-install-guide",
     "scripts/claude-marketplace-sync.mjs",
     "scripts/electron-app-install-dir.mjs",
     "scripts/onboarding-backfill.mjs",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.28.0-staging.251",
+  "version": "5.28.0-staging.252",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.codex-mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.28.0-staging.251",
+        "@muggleai/works@5.28.0-staging.252",
         "serve"
       ],
       "env": {

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "muggle",
-  "version": "5.28.0-staging.251",
+  "version": "5.28.0-staging.252",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
   "author": {
     "name": "Muggle AI",

package/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Real-browser E2E acceptance for your coding agent: test the flows you changed and open the PR with screenshots. Built for flows other tools can't reach: managed test identities with live inboxes (magic links, email OTP and 2FA, verification mail, password resets), an encrypted secret store for login and test credentials, and a test graph that runs prerequisite flows first. Plain-English tests become replayable scripts on localhost or preview URLs.",
-  "version": "5.28.0-staging.251",
+  "version": "5.28.0-staging.252",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@muggleai/works@5.28.0-staging.251",
+        "@muggleai/works@5.28.0-staging.252",
         "serve"
       ]
     }

package/scripts/post-install-guide/constants.mjs

@@ -0,0 +1,41 @@
+/** Terminal device opened on POSIX systems to reach the user's console past npm's output capture. */
+export const POSIX_TERMINAL_DEVICE_PATH = "/dev/tty";
+
+/** Console output device opened on Windows to reach the user's console past npm's output capture. */
+export const WINDOWS_TERMINAL_DEVICE_PATH = "\\\\.\\CONOUT$";
+
+/** Documentation page the guide links to. */
+export const POST_INSTALL_DOCS_URL = "https://www.muggle-ai.com/muggleTestV0/docs/mcp/mcp-overview";
+
+/** Lines of the guide, in print order. Blank strings are spacing. */
+export const POST_INSTALL_GUIDE_LINES = [
+    "Muggle AI Works is installed. Here is how to use it.",
+    "",
+    "See the menu",
+    "  /m   (or /muggle:muggle)   Opens a menu of every command",
+    "",
+    "Import your existing tests first",
+    "  /mimport   (or /muggle:muggle-test-import)",
+    "  Example: /mimport import my Playwright tests from ./e2e",
+    "",
+    "Build something, with acceptance tests",
+    "  /mdo   (or /muggle:muggle-do)",
+    "  Example: /mdo Add a logout button to the header",
+    "  Writes the code and unit tests, checks it in a real browser, opens the PR with",
+    "  screenshots, then watches the PR for reviews and CI.",
+    "",
+    "Run a test, locally or remotely",
+    "  /mtest   (or /muggle:muggle-test)",
+    "  Example: /mtest check my changes on http://localhost:3000",
+    "  Example: /mtest check my changes on https://staging.example.com",
+    "",
+    "Get run guidance",
+    "  muggle help   Full how-to guide, in your terminal",
+    "",
+    "Manage preferences",
+    "  /mprefs   (or /muggle:muggle-preferences)",
+    "  Example: /mprefs show my settings",
+    "",
+    "In Codex, write $muggle:mdo for /mdo.",
+    `Docs: ${POST_INSTALL_DOCS_URL}`,
+];

package/scripts/post-install-guide/index.d.mts

@@ -0,0 +1,17 @@
+export declare const POSIX_TERMINAL_DEVICE_PATH: string;
+export declare const WINDOWS_TERMINAL_DEVICE_PATH: string;
+export declare const POST_INSTALL_DOCS_URL: string;
+export declare const POST_INSTALL_GUIDE_LINES: readonly string[];
+
+export declare function buildPostInstallGuide(): string;
+
+export declare function writeToTerminalDevice(devicePath: string, text: string): void;
+
+export declare function showPostInstallGuide(params: {
+    guide: string;
+    isStdoutTerminal: boolean;
+    env: NodeJS.ProcessEnv;
+    platformName: string;
+    writeToStdout: (text: string) => void;
+    writeToDevice?: (devicePath: string, text: string) => void;
+}): { wroteToStdout: boolean; wroteToTerminalDevice: boolean };

package/scripts/post-install-guide/index.mjs

@@ -0,0 +1,77 @@
+import { closeSync, openSync, writeSync } from "node:fs";
+
+import {
+    POSIX_TERMINAL_DEVICE_PATH,
+    POST_INSTALL_GUIDE_LINES,
+    WINDOWS_TERMINAL_DEVICE_PATH,
+} from "./constants.mjs";
+
+export {
+    POSIX_TERMINAL_DEVICE_PATH,
+    POST_INSTALL_DOCS_URL,
+    POST_INSTALL_GUIDE_LINES,
+    WINDOWS_TERMINAL_DEVICE_PATH,
+} from "./constants.mjs";
+
+/**
+ * Build the getting-started guide shown after install.
+ * @returns {string} The guide as plain text.
+ */
+export function buildPostInstallGuide() {
+    return POST_INSTALL_GUIDE_LINES.join("\n");
+}
+
+/**
+ * Write text straight to the user's console device, bypassing stdout.
+ * @param {string} devicePath - Console device to open.
+ * @param {string} text - Text to write.
+ * @throws When the device cannot be opened, as in a headless environment.
+ */
+export function writeToTerminalDevice(devicePath, text) {
+    const fileDescriptor = openSync(devicePath, "w");
+    try {
+        writeSync(fileDescriptor, text);
+    } finally {
+        closeSync(fileDescriptor);
+    }
+}
+
+/**
+ * Show the guide to whoever ran the install.
+ *
+ * npm captures a lifecycle script's stdout during a global install and discards it on
+ * success, so a plain `console.log` is never seen. When stdout is not a terminal the guide
+ * is also written to the console device directly. CI and headless runs have no console to
+ * reach, so that write is skipped there and its failure is swallowed.
+ * @param {object} params - Output wiring.
+ * @param {string} params.guide - Text to show.
+ * @param {boolean} params.isStdoutTerminal - Whether stdout is an interactive terminal.
+ * @param {NodeJS.ProcessEnv} params.env - Process environment.
+ * @param {string} params.platformName - Value of `os.platform()`.
+ * @param {(text: string) => void} params.writeToStdout - Writes the guide to stdout and the install log.
+ * @param {(devicePath: string, text: string) => void} [params.writeToDevice] - Writes to a console device.
+ * @returns {{ wroteToStdout: boolean, wroteToTerminalDevice: boolean }} Which outputs received the guide.
+ */
+export function showPostInstallGuide({
+    guide,
+    isStdoutTerminal,
+    env,
+    platformName,
+    writeToStdout,
+    writeToDevice = writeToTerminalDevice,
+}) {
+    writeToStdout(guide);
+
+    if (isStdoutTerminal || env.CI) {
+        return { wroteToStdout: true, wroteToTerminalDevice: false };
+    }
+
+    const devicePath = platformName === "win32" ? WINDOWS_TERMINAL_DEVICE_PATH : POSIX_TERMINAL_DEVICE_PATH;
+
+    try {
+        writeToDevice(devicePath, `\n${guide}\n\n`);
+        return { wroteToStdout: true, wroteToTerminalDevice: true };
+    } catch {
+        return { wroteToStdout: true, wroteToTerminalDevice: false };
+    }
+}

package/scripts/postinstall.mjs

@@ -38,6 +38,7 @@ import {
     resolveIntegrityPolicy,
     verifyReleaseSignature,
 } from "./release-integrity/index.mjs";
+import { buildPostInstallGuide, showPostInstallGuide } from "./post-install-guide/index.mjs";
 
 const require = createRequire(import.meta.url);
 const INSTALL_METADATA_FILE_NAME = ".install-metadata.json";
@@ -1056,4 +1057,17 @@ applyWatchServicePreference();
 upsertCursorMcpConfig();
 downloadElectronApp()
     .catch(logError)
-    .finally(() => process.exit(0));
+    .finally(() => {
+        try {
+            showPostInstallGuide({
+                guide: buildPostInstallGuide(),
+                isStdoutTerminal: Boolean(process.stdout.isTTY),
+                env: process.env,
+                platformName: platform(),
+                writeToStdout: log,
+            });
+        } catch (error) {
+            logError(`Failed to show the post-install guide: ${error.message}`);
+        }
+        process.exit(0);
+    });