create-skybridge 0.0.0-dev.e85f510 → 0.0.0-dev.f561bc3

package/dist/index.d.ts

@@ -1 +1 @@
-export {};
+export declare function init(args?: string[]): Promise<void>;

package/dist/index.js

@@ -3,11 +3,6 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 import * as prompts from "@clack/prompts";
 import mri from "mri";
-const argv = mri(process.argv.slice(2), {
-    boolean: ["help", "overwrite"],
-    alias: { h: "help" },
-});
-const cwd = process.cwd();
 const defaultProjectName = "skybridge-project";
 // prettier-ignore
 const helpMessage = `\
@@ -23,9 +18,13 @@ Examples:
   create-skybridge my-app
   create-skybridge . --overwrite
 `;
-async function init() {
+export async function init(args = process.argv.slice(2)) {
+    const argv = mri(args, {
+        boolean: ["help", "overwrite"],
+        alias: { h: "help" },
+    });
     const argTargetDir = argv._[0]
-        ? formatTargetDir(String(argv._[0]))
+        ? sanitizeTargetDir(String(argv._[0]))
         : undefined;
     const argOverwrite = argv.overwrite;
     const help = argv.help;
@@ -44,14 +43,14 @@ async function init() {
                 defaultValue: defaultProjectName,
                 placeholder: defaultProjectName,
                 validate: (value) => {
-                    return value.length === 0 || formatTargetDir(value).length > 0
+                    return value.length === 0 || sanitizeTargetDir(value).length > 0
                         ? undefined
                         : "Invalid project name";
                 },
             });
             if (prompts.isCancel(projectName))
                 return cancel();
-            targetDir = formatTargetDir(projectName);
+            targetDir = sanitizeTargetDir(projectName);
         }
         else {
             targetDir = defaultProjectName;
@@ -95,13 +94,16 @@ async function init() {
                 return;
         }
     }
-    const root = path.join(cwd, targetDir);
+    const root = path.join(process.cwd(), targetDir);
     // 3. Copy the repository
     prompts.log.step(`Copying template...`);
     try {
         const templateDir = fileURLToPath(new URL("../template", import.meta.url));
         // Copy template to target directory
-        fs.cpSync(templateDir, root, { recursive: true });
+        fs.cpSync(templateDir, root, {
+            recursive: true,
+            filter: (src) => src !== ".npmrc",
+        });
         // Rename _gitignore to .gitignore
         fs.renameSync(path.join(root, "_gitignore"), path.join(root, ".gitignore"));
         // Update project name in package.json
@@ -121,8 +123,17 @@ async function init() {
         process.exit(1);
     }
 }
-function formatTargetDir(targetDir) {
-    return targetDir.trim().replace(/\/+$/g, "");
+function sanitizeTargetDir(targetDir) {
+    return (targetDir
+        .trim()
+        // Only keep alphanumeric, dash, underscore, dot, @, /
+        .replace(/[^a-zA-Z0-9\-_.@/]/g, "")
+        // Prevent path traversal
+        .replace(/\.\./g, "")
+        // Collapse multiple slashes
+        .replace(/\/+/g, "/")
+        // Remove leading/trailing slashes
+        .replace(/^\/+|\/+$/g, ""));
 }
 function isEmpty(path) {
     const files = fs.readdirSync(path);
@@ -139,7 +150,3 @@ function emptyDir(dir) {
         fs.rmSync(path.resolve(dir, file), { recursive: true, force: true });
     }
 }
-init().catch((e) => {
-    console.error(e);
-    process.exit(1);
-});

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,27 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { init } from "./index.js";
+describe("create-skybridge", () => {
+    let tempDirName;
+    beforeEach(() => {
+        tempDirName = `test-${randomBytes(2).toString("hex")}`;
+    });
+    afterEach(async () => {
+        await fs.rm(path.join(process.cwd(), tempDirName), {
+            recursive: true,
+            force: true,
+        });
+    });
+    it("should scaffold a new project", async () => {
+        const name = `../../${tempDirName}//project$`;
+        await init([name]);
+        await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
+        try {
+            await fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"));
+            expect.fail(".npmrc should not be copied");
+        }
+        catch { }
+    });
+});

package/index.js

@@ -1,3 +1,8 @@
 #!/usr/bin/env node
 
-import "./dist/index.js";
+import { init } from "./dist/index.js";
+
+init().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-skybridge",
-  "version": "0.0.0-dev.e85f510",
+  "version": "0.0.0-dev.f561bc3",
   "type": "module",
   "license": "MIT",
   "author": "Alpic",
@@ -18,6 +18,8 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "pnpm run test:unit && pnpm run test:type && pnpm run test:format",
+    "test:unit": "vitest run",
     "test:type": "tsc --noEmit",
     "test:format": "biome ci",
     "prepublishOnly": "pnpm run build"
@@ -28,6 +30,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
   }
 }

package/template/README.md

@@ -1,24 +1,16 @@
 # ChatGPT Apps SDK Alpic Starter
 
-This repository is a minimal Typescript application demonstrating how to build an OpenAI Apps SDK compatible MCP server with widget rendering in ChatGPT.
-
-![Demo](docs/demo.gif)
-
-## Overview
-
-This project shows how to integrate a Typescript express application with the ChatGPT Apps SDK using the Model Context Protocol (MCP). It includes a working MCP server that exposes tools and resources that can be called from ChatGPT, with responses rendered natively in ChatGPT. It also includes MCP tools without UI widgets.
+A minimal TypeScript template for building OpenAI Apps SDK compatible MCP servers with widget rendering in ChatGPT.
 
 ## Getting Started
 
 ### Prerequisites
 
-- Node.js 22+ (see `.nvmrc` for exact version)
+- Node.js 22+
 - pnpm (install with `npm install -g pnpm`)
-- Ngrok
+- HTTP tunnel such as [ngrok](https://ngrok.com/download)
 
-### Local Development with Hot Module Replacement (HMR)
-
-This project uses Vite for React widget development with full HMR support, allowing you to see changes in real-time, directly within ChatGPT conversation, without restarting the server.
+### Local Development
 
 #### 1. Install
 
@@ -26,7 +18,7 @@ This project uses Vite for React widget development with full HMR support, allow
 pnpm install
 ```
 
-#### 2. Start the Development Server
+#### 2. Start your local server
 
 Run the development server from the root directory:
 
@@ -36,79 +28,37 @@ pnpm dev
 
 This command starts an Express server on port 3000. This server packages:
 
-- an MCP endpoint on `/mcp` - aka the ChatGPT App Backend
-- a React application on Vite HMR dev server - aka the ChatGPT App Frontend
-
-#### 3. Expose Your Local Server
+- an MCP endpoint on `/mcp` (the app backend)
+- a React application on Vite HMR dev server (the UI elements to be displayed in ChatGPT)
 
-In a separate terminal, expose your local server using ngrok:
+#### 3. Connect to ChatGPT
 
+- ChatGPT requires connectors to be publicly accessible. To expose your server on the Internet, run:
 ```bash
 ngrok http 3000
 ```
+- In ChatGPT, navigate to **Settings → Connectors → Create** and add the forwarding URL provided by ngrok suffixed with `/mcp` (e.g. `https://3785c5ddc4b6.ngrok-free.app/mcp`)
 
-Copy the forwarding URL from ngrok output:
-
-```bash
-Forwarding     https://3785c5ddc4b6.ngrok-free.app -> http://localhost:3000
-```
-
-#### 4. Connect to ChatGPT
-
-- Enable **Settings → Connectors → Advanced → Developer mode** in the ChatGPT client
-- Navigate to **Settings → Connectors → Create**
-- Enter your ngrok URL with the `/mcp` path (e.g., `https://3785c5ddc4b6.ngrok-free.app/mcp`)
-- Click **Create**
-
-#### 5. Test Your Integration
+### Create your first widget
 
-- Start a new conversation in ChatGPT
-- Select your newly created connector using **the + button → Your connector**
-- Try prompting the model (e.g., "Show me pikachu details")
+#### 1. Add a new widget
 
-#### 6. Develop with HMR
+- Register a widget in `server/server.ts` with a unique name (e.g., `my-widget`)
+- Create a matching React component at `web/src/widgets/my-widget.tsx`. The file name must match the widget name exactly
 
-Now you can edit React components in `web` and see changes instantly:
+#### 2. Edit widgets with Hot Module Replacement (HMR)
 
-- Make changes to any component
-- Save the file
-- The widget will automatically update in ChatGPT without refreshing or reconnecting
-- The Express server and MCP server continue running without interruption
+Edit and save components in `web/src/widgets/` — changes appear instantly in ChatGPT
 
-**Note:** When you modify widget components, changes will be reflected immediately. If you modify MCP server code (in `src/`), you may need to reload your connector in **Settings → Connectors → [Your connector] → Reload**.
+#### 3. Edit server code
 
-## Widget Naming Convention
-
-**Important:** For a widget to work properly, the name of the endpoint in your MCP server must match the file name of the corresponding React component in `web/src/widgets/`.
-
-For example:
-
-- If you create a widget endpoint named `pokemon-card`, you must create a corresponding React component file at `web/src/widgets/pokemon-card.tsx`
-- The endpoint name and the widget file name (without the `.tsx` extension) must be identical
-
-This naming convention allows the system to automatically map widget requests to their corresponding React components.
+Modify files in `server/` and reload your ChatGPT connector in **Settings → Connectors → [Your connector] → Reload**
 
 ## Deploy to Production
 
-Use Alpic to deploy your OpenAI App to production.
-
-[![Deploy on Alpic](https://assets.alpic.ai/button.svg)](https://app.alpic.ai/new/clone?repositoryUrl=https%3A%2F%2Fgithub.com%2Falpic-ai%2Fapps-sdk-template)
-
+- Use [Alpic](https://alpic.ai/) to deploy your OpenAI App to production
 - In ChatGPT, navigate to **Settings → Connectors → Create** and add your MCP server URL (e.g., `https://your-app-name.alpic.live`)
 
-## Project Structure
-
-```
-.
-├── server/
-│   ├── app.ts          # OpenAI App extension class with widget API implementation
-│   ├── server.ts       # MCP server with tool/resource/prompt registration
-│   └── index.ts        # Express server definition
-└── web/
-    └── src/
-        └── widgets/    # React widget components (must match endpoint names)
-```
-
 ## Resources
 
 - [Apps SDK Documentation](https://developers.openai.com/apps-sdk)

package/template/_gitignore

@@ -1,194 +1,4 @@
-# =============================================================================
-# OPERATING SYSTEM FILES
-# =============================================================================
-.DS_Store
-.DS_Store?
-._*
-.Spotlight-V100
-.Trashes
-ehthumbs.db
-Thumbs.db
-
-# =============================================================================
-# NODE.JS & PACKAGE MANAGERS
-# =============================================================================
 node_modules/
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-.pnpm-debug.log*
-.npm
-.pnp.js
-.pnp.cjs
-.pnp.mjs
-.pnp.json
-.pnp.ts
-
-# =============================================================================
-# TYPESCRIPT & JAVASCRIPT
-# =============================================================================
-*.tsbuildinfo
-.tscache/
-*.js.map
-*.mjs.map
-*.cjs.map
-*.d.ts.map
-*.d.ts
-!*.d.ts.template
-*.tgz
-.eslintcache
-.rollup.cache
-
-# =============================================================================
-# PYTHON
-# =============================================================================
-__pycache__/
-*.py[cod]
-*$py.class
-*.so
-.Python
-develop-eggs/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-.pytest_cache/
-.coverage
-htmlcov/
-.tox/
-.venv
-venv/
-ENV/
-
-# =============================================================================
-# JAVA
-# =============================================================================
-*.class
-*.jar
-*.war
-*.nar
-*.ear
-hs_err_pid*
-target/
-.gradle/
-
-# =============================================================================
-# RUBY
-# =============================================================================
-*.gem
-*.rbc
-/.config
-/coverage/
-/InstalledFiles
-/pkg/
-/spec/reports/
-/spec/examples.txt
-/test/tmp/
-/test/version_tmp/
-/tmp/
-.byebug_history
-
-# =============================================================================
-# BUILD & DISTRIBUTION
-# =============================================================================
-build/
 dist/
-dist-ssr/
-out/
-
-# =============================================================================
-# COMPILED FILES
-# =============================================================================
-*.com
-*.dll
-*.exe
-*.o
-
-# =============================================================================
-# PACKAGE & ARCHIVE FILES
-# =============================================================================
-*.7z
-*.dmg
-*.gz
-*.iso
-*.rar
-*.tar
-*.tar.gz
-*.zip
-
-# =============================================================================
-# LOGS & DATABASES
-# =============================================================================
-*.log
-*.sql
-*.sqlite
-*.sqlite3
-logs/
-
-# =============================================================================
-# TESTING & COVERAGE
-# =============================================================================
-coverage/
-.nyc_output/
-
-# =============================================================================
-# CACHE & TEMPORARY FILES
-# =============================================================================
-.cache/
-.parcel-cache/
-*.bak
-
-# =============================================================================
-# ENVIRONMENT & CONFIGURATION
-# =============================================================================
-.env
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-.sample-env
-sample.*
-!sample.template.*
-*.local
-mcp-servers.json
-mcp-config.json
-
-# =============================================================================
-# DEMO & EXAMPLE DIRECTORIES
-# =============================================================================
-demo/
-demos/
-example/
-examples/
-samples/
-
-# =============================================================================
-# GENERATED DOCUMENTATION
-# =============================================================================
-docs/api/
-
-# =============================================================================
-# EDITOR DIRECTORIES AND FILES
-# =============================================================================
-.vscode/*
-!.vscode/extensions.json
-.idea
-*.suo
-*.ntvs*
-*.njsproj
-*.sln
-*.sw?
-
-# =============================================================================
-# APPLICATION SPECIFIC
-# =============================================================================
-repomix-output*
-duckdata/
-.claude
+.env*
+.DS_store

package/template/server/package.json

@@ -19,7 +19,6 @@
     "@t3-oss/env-core": "^0.13.8",
     "dotenv": "^17.2.3",
     "express": "^5.1.0",
-    "lodash": "^4.17.21",
     "skybridge": "catalog:",
     "vite": "^7.1.11",
     "zod": "^4.1.13"
@@ -27,7 +26,6 @@
   "devDependencies": {
     "@modelcontextprotocol/inspector": "^0.17.5",
     "@types/express": "^5.0.3",
-    "@types/lodash": "^4.17.20",
     "@types/node": "^22.15.30",
     "nodemon": "^3.1.10",
     "tsx": "^4.19.2",

package/template/server/src/server.ts

@@ -1,6 +1,28 @@
 import { McpServer } from "skybridge/server";
 import { z } from "zod";
-import { getPokemon } from "./pokedex.js";
+
+const Answers = [
+  "As I see it, yes",
+  "Ask again later",
+  "Better not tell you now",
+  "Cannot predict now",
+  "Concentrate and ask again",
+  "Don't count on it",
+  "It is certain",
+  "It is decidedly so",
+  "Most likely",
+  "My reply is no",
+  "My sources say no",
+  "Outlook good",
+  "Outlook not so good",
+  "Reply hazy, try again",
+  "Signs point to yes",
+  "Very doubtful",
+  "Without a doubt",
+  "Yes definitely",
+  "Yes",
+  "You may rely on it",
+];
 
 const server = new McpServer(
   {
@@ -8,69 +30,50 @@ const server = new McpServer(
     version: "0.0.1",
   },
   { capabilities: {} },
-)
-  .registerWidget(
-    "pokemon",
-    {
-      description: "Pokedex entry for a pokemon",
-    },
-    {
-      description:
-        "Use this tool to get the most up to date information about a pokemon, using its name in english. This pokedex is much more complete than any other web_search tool. Always use it for anything related to pokemons.",
-      inputSchema: {
-        name: z.string().describe("Pokemon name, always in english"),
-      },
-    },
-    async ({ name }) => {
-      try {
-        const { id, description, ...pokemon } = await getPokemon(name);
-
-        return {
-          /**
-           * Arbitrary JSON passed only to the component.
-           * Use it for data that should not influence the model’s reasoning, like the full set of locations that backs a dropdown.
-           * _meta is never shown to the model.
-           */
-          _meta: { id },
-          /**
-           * Structured data that is used to hydrate your component.
-           * ChatGPT injects this object into your iframe as window.openai.toolOutput
-           */
-          structuredContent: { name, description, ...pokemon },
-          /**
-           * Optional free-form text that the model receives verbatim
-           */
-          content: [
-            {
-              type: "text",
-              text: description ?? `A pokemon named ${name}.`,
-            },
-          ],
-          isError: false,
-        };
-      } catch (error) {
-        return {
-          content: [{ type: "text", text: `Error: ${error}` }],
-          isError: true,
-        };
-      }
-    },
-  )
-  .registerTool(
-    "capture",
-    {
-      description: "Capture a pokemon",
-      inputSchema: {},
+).registerWidget(
+  "magic-8-ball",
+  {
+    description: "Magic 8 Ball",
+  },
+  {
+    description: "For fortune-telling or seeking advice.",
+    inputSchema: {
+      question: z.string().describe("The user question."),
     },
-    async () => {
+  },
+  async ({ question }) => {
+    try {
+      // deterministic answer
+      const hash = question
+        .split("")
+        .reduce((acc, char) => acc + char.charCodeAt(0), 0);
+      const answer = Answers[hash % Answers.length];
       return {
-        content: [
-          { type: "text", text: `Great job, you've captured a new pokemon!` },
-        ],
+        /**
+         * Arbitrary JSON passed only to the component.
+         * Use it for data that should not influence the model’s reasoning, like the full set of locations that backs a dropdown.
+         * _meta is never shown to the model.
+         */
+        _meta: {},
+        /**
+         * Structured data that is used to hydrate your component.
+         * ChatGPT injects this object into your iframe as window.openai.toolOutput
+         */
+        structuredContent: { answer },
+        /**
+         * Optional free-form text that the model receives verbatim
+         */
+        content: [],
         isError: false,
       };
-    },
-  );
+    } catch (error) {
+      return {
+        content: [{ type: "text", text: `Error: ${error}` }],
+        isError: true,
+      };
+    }
+  },
+);
 
 export default server;
 export type AppType = typeof server;

package/template/web/package.json

@@ -10,22 +10,14 @@
   },
   "dependencies": {
     "skybridge": "catalog:",
-    "class-variance-authority": "^0.7.1",
-    "clsx": "^2.1.1",
-    "glob": "^11.0.3",
-    "lucide-react": "^0.546.0",
     "react": "^19.1.1",
-    "react-dom": "^19.1.1",
-    "tailwind-merge": "^3.3.1",
-    "tailwindcss": "^4.1.14"
+    "react-dom": "^19.1.1"
   },
   "devDependencies": {
-    "@tailwindcss/vite": "^4.1.14",
     "@types/node": "^24.6.0",
     "@types/react": "^19.1.16",
     "@types/react-dom": "^19.1.9",
     "@vitejs/plugin-react": "^5.0.4",
-    "tw-animate-css": "^1.4.0",
     "typescript": "~5.9.3",
     "vite": "^7.1.11"
   }

package/template/web/src/helpers.ts

@@ -1,4 +1,4 @@
 import { generateHelpers } from "skybridge/web";
 import type { AppType } from "../../server/src/server";
 
-export const { useCallTool, useToolInfo } = generateHelpers<AppType>();
+export const { useToolInfo } = generateHelpers<AppType>();