sunpeak 0.20.62 → 0.20.64

package/README.md

@@ -20,6 +20,8 @@ Server-agnostic MCP testing framework and full-stack MCP App framework.
 
 MCP Apps are cross-platform, meaning sunpeak is a ChatGPT App framework, Claude Connector framework, and more.
 
+ChatGPT apps are now submitted and published as plugins. The app remains an MCP-backed app, so sunpeak's architecture and runtime do not change. The plugin is the package used for local installation, review, and public distribution.
+
 ```bash
 npx sunpeak new
 ```
@@ -149,4 +151,5 @@ Toggle between hosts, themes, display modes, and device types from the sidebar.
 - [MCP Overview](https://sunpeak.ai/docs/mcp-apps/mcp/overview) · [Tools](https://sunpeak.ai/docs/mcp-apps/mcp/tools) · [Resources](https://sunpeak.ai/docs/mcp-apps/mcp/resources)
 - [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps)
 - [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
+- [Build ChatGPT Plugins](https://learn.chatgpt.com/docs/build-plugins) · [Submit ChatGPT Plugins](https://learn.chatgpt.com/docs/submit-plugins)
 - [Troubleshooting](https://sunpeak.ai/docs/app-framework/guides/troubleshooting)

package/bin/commands/inspect.mjs

@@ -1032,6 +1032,12 @@ function appendInspectorRequestToken(resourceUrl, requestToken) {
   }
 }
 
+function isInspectorRequestTokenValid(req, requestToken) {
+  if (!requestToken) return true;
+  const url = new URL(req.url, 'http://localhost');
+  return url.searchParams.get('__sunpeak_token') === requestToken;
+}
+
 function addInspectorRequestTokenToSimulations(simulations, requestToken) {
   if (!requestToken || !simulations || typeof simulations !== 'object') return simulations;
   return Object.fromEntries(
@@ -2073,12 +2079,7 @@ function sunpeakInspectEndpointsPlugin(getClient, setClient, pluginOpts = {}) {
   }
 
   function requireInspectorRequestToken(req, res) {
-    if (!pluginOpts.requestToken) return true;
-    const fetchSiteHeader = req.headers['sec-fetch-site'];
-    const fetchSite = Array.isArray(fetchSiteHeader) ? fetchSiteHeader[0] : fetchSiteHeader;
-    if (fetchSite !== 'cross-site') return true;
-    const url = new URL(req.url, 'http://localhost');
-    if (url.searchParams.get('__sunpeak_token') === pluginOpts.requestToken) return true;
+    if (isInspectorRequestTokenValid(req, pluginOpts.requestToken)) return true;
     res.writeHead(403, { 'Content-Type': 'text/plain' });
     res.end('Forbidden: missing or invalid inspector request token');
     return false;
@@ -3090,6 +3091,7 @@ export const _securityTestExports = {
   formatSharedAppContextForModel,
   addInspectorRequestTokenToSimulations,
   appendInspectorRequestToken,
+  isInspectorRequestTokenValid,
   normalizeApiKey,
   normalizeModelChatMessages,
   normalizeModelAppContext,

package/bin/lib/live/chatgpt-page.mjs

@@ -11,7 +11,7 @@ import { HostPage } from './host-page.mjs';
 /**
  * All ChatGPT DOM selectors in one place for easy maintenance.
  *
- * Last verified: 2026-03-24 via live Playwright inspection.
+ * Updated: 2026-07-10 for the documented ChatGPT Plugins flow.
  */
 const SELECTORS = {
   // Chat interface
@@ -23,8 +23,9 @@ const SELECTORS = {
   loggedInIndicator: '[data-testid="accounts-profile-button"]',
   loginPage: 'button:has-text("Log in")',
 
-  // Settings navigation
-  appsTab: '[role="tab"]:has-text("Apps")',
+  // Plugin directory navigation
+  createdByYou:
+    'button:has-text("Created by you"), [role="tab"]:has-text("Created by you"), a:has-text("Created by you")',
   refreshButton: 'button:has-text("Refresh")',
   reconnectButton: 'button:has-text("Reconnect")',
 
@@ -40,40 +41,51 @@ const SELECTORS = {
 
 const URLS = {
   base: 'https://chatgpt.com',
-  settings: 'https://chatgpt.com/#settings/Connectors',
+  plugins: 'https://chatgpt.com/plugins',
 };
 
+const PLUGIN_SETUP_HINT =
+  'Enable Developer mode from the bottom-left user menu under Settings > Security and login > Developer mode, then add the app from Plugins > +.';
+
 export { SELECTORS as CHATGPT_SELECTORS, URLS as CHATGPT_URLS };
 
 export class ChatGPTPage extends HostPage {
-  get hostId() { return 'chatgpt'; }
-  get hostName() { return 'ChatGPT'; }
-  get selectors() { return SELECTORS; }
-  get urls() { return URLS; }
+  get hostId() {
+    return 'chatgpt';
+  }
+  get hostName() {
+    return 'ChatGPT';
+  }
+  get selectors() {
+    return SELECTORS;
+  }
+  get urls() {
+    return URLS;
+  }
 
   /**
-   * Refresh the MCP server connection in ChatGPT settings.
-   * Navigates to Settings > Apps, clicks the app entry, clicks Refresh,
+   * Refresh the MCP server connection from the ChatGPT Plugins directory.
+   * Opens Plugins, finds the developer-mode app, clicks Refresh,
    * and waits for the success/error toast.
    */
   async refreshMcpServer({ tunnelUrl, appName } = {}) {
-    await this.page.goto(URLS.settings, { waitUntil: 'domcontentloaded' });
+    await this.page.goto(URLS.plugins, { waitUntil: 'domcontentloaded' });
     await this.page.waitForTimeout(3_000);
 
     const found = await this._findAndClickRefresh(appName);
 
     if (!found) {
-      const appsTab = this.page.locator(SELECTORS.appsTab);
-      const hasAppsTab = await appsTab.isVisible().catch(() => false);
-      if (hasAppsTab) {
-        await appsTab.click();
+      const createdByYou = this.page.locator(SELECTORS.createdByYou).first();
+      const hasCreatedByYou = await createdByYou.isVisible().catch(() => false);
+      if (hasCreatedByYou) {
+        await createdByYou.click();
         await this.page.waitForTimeout(2_000);
         const retryFound = await this._findAndClickRefresh(appName);
         if (!retryFound) {
-          await this._screenshotAndThrow('refresh-mcp-settings', tunnelUrl);
+          await this._screenshotAndThrow('refresh-mcp-plugin', tunnelUrl, PLUGIN_SETUP_HINT);
         }
       } else {
-        await this._screenshotAndThrow('no-apps-tab', tunnelUrl);
+        await this._screenshotAndThrow('developer-plugin-not-found', tunnelUrl, PLUGIN_SETUP_HINT);
       }
     }
 
@@ -82,7 +94,7 @@ export class ChatGPTPage extends HostPage {
     if (hasError) {
       throw new Error(
         `MCP server refresh failed in ChatGPT:\n${errorText.trim()}\n\n` +
-        `Make sure your MCP dev server is running (pnpm dev) and your tunnel is active.`
+          `Make sure your MCP dev server is running (pnpm dev) and your tunnel is active.`
       );
     }
 
@@ -107,13 +119,18 @@ export class ChatGPTPage extends HostPage {
     }
 
     // Wait for the outer sandbox iframe
-    await this.page.locator(SELECTORS.mcpAppOuterIframe).first().waitFor({ state: 'attached', timeout: 30_000 });
+    await this.page
+      .locator(SELECTORS.mcpAppOuterIframe)
+      .first()
+      .waitFor({ state: 'attached', timeout: 30_000 });
 
     // Wait for the inner frame to appear inside the sandboxed outer iframe.
     // waitForFunction can't cross the sandbox boundary, so use Playwright's frameLocator instead.
     const outerFrame = this.page.frameLocator(SELECTORS.mcpAppOuterIframe).first();
     await outerFrame
-      .locator(`iframe[name="${SELECTORS.mcpAppInnerFrameName}"], iframe#${SELECTORS.mcpAppInnerFrameName}`)
+      .locator(
+        `iframe[name="${SELECTORS.mcpAppInnerFrameName}"], iframe#${SELECTORS.mcpAppInnerFrameName}`
+      )
       .waitFor({ state: 'attached', timeout: 15_000 });
 
     const appFrame = this.getAppIframe();
@@ -182,13 +199,11 @@ export class ChatGPTPage extends HostPage {
       return false;
     };
 
-    if (await tryClickRefresh()) return true;
-
     if (appName) {
       const strategies = [
         () => this.page.getByText(appName, { exact: true }).first(),
-        () => this.page.locator(`text=${appName}`).first(),
-        () => this.page.locator(`a:has-text("${appName}"), [role="button"]:has-text("${appName}")`).first(),
+        () => this.page.getByRole('link', { name: appName, exact: true }).first(),
+        () => this.page.getByRole('button', { name: appName, exact: true }).first(),
       ];
 
       for (const getLocator of strategies) {
@@ -205,6 +220,6 @@ export class ChatGPTPage extends HostPage {
       }
     }
 
-    return false;
+    return appName ? false : tryClickRefresh();
   }
 }

package/bin/lib/live/global-setup.mjs

@@ -3,7 +3,7 @@
  *
  * Runs exactly once before all workers. Two responsibilities:
  *  1. Authenticate — launch a browser, verify login, wait for user if needed.
- *  2. Refresh MCP server — navigate to host settings and click Refresh so
+ *  2. Refresh MCP server: open the host's app management UI and click Refresh so
  *     all workers start with pre-loaded resources.
  *
  * Auth approach:
@@ -150,7 +150,7 @@ export default async function globalSetup() {
     // Refresh MCP server in the SAME browser session.
     // This is critical — Cloudflare's cf_clearance cookie is HttpOnly and
     // won't be in the saved storageState. By refreshing here, the cookie
-    // is still valid for navigating to settings.
+    // is still valid for navigating to the plugin directory.
     //
     // This MUST succeed — if the MCP server isn't reachable or the refresh
     // fails, tests will fail with confusing iframe/timeout errors.

package/bin/lib/live/host-page.mjs

@@ -23,8 +23,7 @@
 /**
  * @typedef {Object} HostUrls
  * @property {string} base - Host base URL (e.g., 'https://chatgpt.com')
- * @property {string} settings - MCP settings URL
- * @property {string} loginTestId - Test ID for login detection (if using getByTestId)
+ * @property {string} [plugins] - Host plugin or app management URL
  */
 
 export class HostPage {
@@ -80,7 +79,8 @@ export class HostPage {
     if (warnings.length > 0) {
       console.warn(
         `\n⚠️  ${this.hostName} DOM may have changed — update selectors in ${this.hostId}-page.mjs:\n` +
-        warnings.join('\n') + '\n'
+          warnings.join('\n') +
+          '\n'
       );
     }
 
@@ -135,14 +135,14 @@ export class HostPage {
     // Not logged in. Wait for the user to authenticate in this browser window.
     console.log(
       `\n` +
-      `╔══════════════════════════════════════════════════════════════╗\n` +
-      `║  Not logged into ${this.hostName.padEnd(42)}║\n` +
-      `║                                                            ║\n` +
-      `║  Please log in at: ${this.urls.base.padEnd(39)}║\n` +
-      `║  in the browser window that just opened.                   ║\n` +
-      `║                                                            ║\n` +
-      `║  Waiting up to 3 minutes...                                ║\n` +
-      `╚══════════════════════════════════════════════════════════════╝\n`
+        `╔══════════════════════════════════════════════════════════════╗\n` +
+        `║  Not logged into ${this.hostName.padEnd(42)}║\n` +
+        `║                                                            ║\n` +
+        `║  Please log in at: ${this.urls.base.padEnd(39)}║\n` +
+        `║  in the browser window that just opened.                   ║\n` +
+        `║                                                            ║\n` +
+        `║  Waiting up to 3 minutes...                                ║\n` +
+        `╚══════════════════════════════════════════════════════════════╝\n`
     );
 
     // Poll for login — the user may need to pass Cloudflare + enter credentials
@@ -160,14 +160,14 @@ export class HostPage {
 
     throw new Error(
       `Login to ${this.hostName} timed out after 3 minutes.\n` +
-      `Please log in at ${this.urls.base} in the browser window and try again.\n` +
-      'If the session expired, delete the .auth/ directory and try again.'
+        `Please log in at ${this.urls.base} in the browser window and try again.\n` +
+        'If the session expired, delete the .auth/ directory and try again.'
     );
   }
 
   /**
-   * Refresh the MCP server connection in host settings.
-   * Subclasses must implement this — each host has different settings UI.
+   * Refresh the MCP server connection in the host's app management UI.
+   * Subclasses must implement this because each host has a different flow.
    *
    * @param {Object} [options]
    * @param {string} [options.tunnelUrl] - Tunnel URL for error messages
@@ -228,9 +228,10 @@ export class HostPage {
    * Capture a debug screenshot and throw with helpful message.
    * @param {string} context - Context label for the screenshot filename
    * @param {string} [tunnelUrl] - Tunnel URL for the error message
+   * @param {string} [setupHint] - Host-specific setup steps
    * @protected
    */
-  async _screenshotAndThrow(context, tunnelUrl) {
+  async _screenshotAndThrow(context, tunnelUrl, setupHint) {
     const screenshotPath = `/tmp/sunpeak-live-debug-${this.hostId}-${context}.png`;
     try {
       await this.page.screenshot({ path: screenshotPath, fullPage: true });
@@ -241,29 +242,34 @@ export class HostPage {
 
     try {
       const buttons = await this.page.locator('button').allTextContents();
-      console.error('Visible buttons on page:', buttons.filter(t => t.trim()).join(', '));
+      console.error('Visible buttons on page:', buttons.filter((t) => t.trim()).join(', '));
     } catch {
       // Best effort
     }
 
     throw new Error(
-      `Could not find Refresh/Reconnect button in ${this.hostName} settings.\n` +
-      `Make sure your MCP server is added in ${this.hostName} settings` +
-      (tunnelUrl ? ` with URL: ${tunnelUrl}/mcp` : '') +
-      `\n\nDebug screenshot: ${screenshotPath}`
+      `Could not find Refresh/Reconnect in ${this.hostName} app management.\n` +
+        `Make sure your MCP server is added to ${this.hostName}` +
+        (tunnelUrl ? ` with URL: ${tunnelUrl}/mcp` : '') +
+        (setupHint ? `\n${setupHint}` : '') +
+        `\n\nDebug screenshot: ${screenshotPath}`
     );
   }
 
   /**
    * Wait for a toast/alert banner and check for errors.
-   * Many hosts show success/error toasts after settings actions.
+   * Many hosts show success/error toasts after app management actions.
    * @param {Object} [options]
    * @param {string} [options.alertSelector='[role="alert"]'] - Selector for toast elements
    * @param {number} [options.timeout=30000] - Max time to wait
    * @param {number} [options.minTextLength=5] - Minimum text length to consider as a real toast
    * @protected
    */
-  async _waitForToast({ alertSelector = '[role="alert"]', timeout = 30_000, minTextLength = 5 } = {}) {
+  async _waitForToast({
+    alertSelector = '[role="alert"]',
+    timeout = 30_000,
+    minTextLength = 5,
+  } = {}) {
     try {
       await this.page.waitForFunction(
         ({ selector, minLen }) => {
@@ -275,7 +281,7 @@ export class HostPage {
           return false;
         },
         { selector: alertSelector, minLen: minTextLength },
-        { timeout },
+        { timeout }
       );
     } catch {
       console.warn('No toast detected — assuming success.');

package/bin/lib/test/test-fixtures.mjs

@@ -67,6 +67,14 @@ async function fetchJson(page, path) {
   return response.json();
 }
 
+async function getInspectorRequestToken(page) {
+  const baseURL = page.context()._options?.baseURL || '';
+  const response = await page.request.get(`${baseURL}/@id/__x00__virtual:sunpeak-inspect-entry`);
+  if (!response.ok()) return null;
+  const source = await response.text();
+  return source.match(/[?&]__sunpeak_token=([^"'&\\]+)/)?.[1] ?? null;
+}
+
 /**
  * Read the tool result from the inspector's <script id="__tool-result"> element.
  */
@@ -199,9 +207,10 @@ const test = base.extend({
 
       async readResource(uri) {
         const baseURL = page.context()._options?.baseURL || '';
-        const response = await page.request.get(
-          `${baseURL}/__sunpeak/read-resource?uri=${encodeURIComponent(uri)}`
-        );
+        const params = new URLSearchParams({ uri });
+        const requestToken = await getInspectorRequestToken(page);
+        if (requestToken) params.set('__sunpeak_token', requestToken);
+        const response = await page.request.get(`${baseURL}/__sunpeak/read-resource?${params}`);
         if (!response.ok()) {
           throw new Error(
             `readResource(${uri}) returned ${response.status()}: ${await response.text()}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sunpeak",
-  "version": "0.20.62",
+  "version": "0.20.64",
   "description": "App framework, testing framework, and inspector for MCP Apps.",
   "type": "module",
   "main": "./dist/index.cjs",

package/template/README.md

@@ -76,7 +76,11 @@ pnpm dev
 ngrok http 8000
 ```
 
-You can then connect to the tunnel forwarding URL at the `/mcp` path from ChatGPT **in developer mode** to see your UI in action: `User > Settings > Apps > Create`
+If Developer mode is not already enabled, click your user menu in the bottom-left corner and select `Settings > Security and login > Developer mode`.
+
+Then return to the ChatGPT homepage and click `Plugins` in the sidebar. Open your app if it is already there, or select the `+` button and connect the tunnel forwarding URL at the `/mcp` path.
+
+ChatGPT creates a developer-mode app backed by your MCP server. It appears under `Plugins`, but its MCP App UI and runtime do not change.
 
 Once your app is connected, send the name of the app and a tool, like `/sunpeak show review`, to ChatGPT.
 
@@ -86,8 +90,9 @@ Run automated tests against real ChatGPT with `pnpm test:live`. This opens your
 
 **One-time setup:**
 
-1. Log into [chatgpt.com](https://chatgpt.com) in your browser (Chrome, Arc, Brave, or Edge)
-2. Add your MCP server in ChatGPT settings: `Settings > Apps > Create` with your tunnel URL at `/mcp`
+1. If Developer mode is not already enabled, click your user menu in the bottom-left corner and select `Settings > Security and login > Developer mode`
+2. Return to the ChatGPT homepage and click `Plugins` in the sidebar
+3. Open your app if it is already there, or select `+` and add your tunnel URL at `/mcp`
 
 **Run live tests:**
 
@@ -133,6 +138,8 @@ pnpm start -- --json-logs              # Structured JSON logging for production
 
 The server includes a `/health` endpoint for load balancer probes and monitoring. See the [Deployment Guide](https://sunpeak.ai/docs/app-framework/guides/deployment) for production operations details (reverse proxy, process management, Docker).
 
+ChatGPT apps are submitted and published as plugins. Deploy this MCP server first, then create a `With MCP` submission in the [OpenAI Platform plugin portal](https://platform.openai.com/plugins). Submit the MCP server URL directly, not an existing ChatGPT app ID. See the [sunpeak publishing guide](https://sunpeak.ai/docs/app-framework/guides/deployment#publish-to-chatgpt) and OpenAI's [plugin submission guide](https://learn.chatgpt.com/docs/submit-plugins).
+
 ## Add a new UI (Resource)
 
 To add a new UI ([MCP Resource](https://sunpeak.ai/docs/mcp-apps/mcp/resources)), create a new directory under `src/resources/` with the following files:
@@ -162,7 +169,7 @@ If your app doesn't render in ChatGPT or Claude:
 
 1. **Check your tunnel** is running and pointing to the correct port
 2. **Restart `pnpm dev`** to clear stale connections
-3. **Refresh or re-add the MCP server** in the host's settings (Settings > MCP Servers)
+3. **Refresh or re-add the MCP server** from the host's app or plugin management page
 4. **Hard refresh** the host page (`Cmd+Shift+R` / `Ctrl+Shift+R`)
 5. **Open a new chat** in the host (cached iframes persist per-conversation)
 
@@ -175,3 +182,4 @@ Full guide: [sunpeak.ai/docs/app-framework/guides/troubleshooting](https://sunpe
 - [MCP Overview](https://sunpeak.ai/docs/mcp-apps/mcp/overview) · [Tools](https://sunpeak.ai/docs/mcp-apps/mcp/tools) · [Resources](https://sunpeak.ai/docs/mcp-apps/mcp/resources)
 - [MCP Apps SDK](https://github.com/modelcontextprotocol/ext-apps)
 - [ChatGPT Apps SDK Design Guidelines](https://developers.openai.com/apps-sdk/concepts/design-guidelines)
+- [Build ChatGPT Plugins](https://learn.chatgpt.com/docs/build-plugins) · [Submit ChatGPT Plugins](https://learn.chatgpt.com/docs/submit-plugins)

package/template/dist/albums/albums.json

@@ -12,5 +12,5 @@
     }
   },
   "name": "albums",
-  "uri": "ui://albums-mr9dz635"
+  "uri": "ui://albums-mrf9zhts"
 }

package/template/dist/carousel/carousel.json

@@ -12,5 +12,5 @@
     }
   },
   "name": "carousel",
-  "uri": "ui://carousel-mr9dz635"
+  "uri": "ui://carousel-mrf9zhts"
 }

package/template/dist/map/map.json

@@ -18,5 +18,5 @@
     }
   },
   "name": "map",
-  "uri": "ui://map-mr9dz635"
+  "uri": "ui://map-mrf9zhts"
 }

package/template/dist/review/review.json

@@ -12,5 +12,5 @@
     }
   },
   "name": "review",
-  "uri": "ui://review-mr9dz635"
+  "uri": "ui://review-mrf9zhts"
 }