create-skybridge 0.0.0-dev.ecf87cf → 0.0.0-dev.eea25a3

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,20 +1,14 @@
-import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 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 TEMPLATE_REPO = "https://github.com/alpic-ai/apps-sdk-template";
 const defaultProjectName = "skybridge-project";
 // prettier-ignore
 const helpMessage = `\
 Usage: create-skybridge [OPTION]... [DIRECTORY]
 
-Create a new Skybridge project by cloning the starter template.
+Create a new Skybridge project by copying the starter template.
 
 Options:
   -h, --help              show this help message
@@ -24,23 +18,13 @@ Examples:
   create-skybridge my-app
   create-skybridge . --overwrite
 `;
-function run([command, ...args], options) {
-    if (!command) {
-        throw new Error("Command is required");
-    }
-    const { status, error } = spawnSync(command, args, options);
-    if (status != null && status > 0) {
-        process.exit(status);
-    }
-    if (error) {
-        console.error(`\n${command} ${args.join(" ")} error!`);
-        console.error(error);
-        process.exit(1);
-    }
-}
-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;
@@ -59,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;
@@ -110,30 +94,43 @@ async function init() {
                 return;
         }
     }
-    const root = path.join(cwd, targetDir);
-    // 3. Clone the repository
-    prompts.log.step(`Cloning template from ${TEMPLATE_REPO}...`);
+    const root = path.join(process.cwd(), targetDir);
+    // 3. Copy the repository
+    prompts.log.step(`Copying template...`);
     try {
-        // Clone directly to target directory
-        run(["git", "clone", "--depth", "1", TEMPLATE_REPO, root], {
-            stdio: "inherit",
-        });
-        // Remove .git directory to start fresh
-        const gitDir = path.join(root, ".git");
-        if (fs.existsSync(gitDir)) {
-            fs.rmSync(gitDir, { recursive: true, force: true });
+        const templateDir = fileURLToPath(new URL("../template", import.meta.url));
+        // Copy template to target directory
+        fs.cpSync(templateDir, root, { recursive: true });
+        // Rename _gitignore to .gitignore
+        fs.renameSync(path.join(root, "_gitignore"), path.join(root, ".gitignore"));
+        // Update project name in package.json
+        const name = path.basename(root);
+        for (const dir of ["", "server", "web"]) {
+            const pkgPath = path.join(root, dir, "package.json");
+            const pkg = fs.readFileSync(pkgPath, "utf-8");
+            const fixed = pkg.replace(/apps-sdk-template/g, name);
+            fs.writeFileSync(pkgPath, fixed);
         }
         prompts.log.success(`Project created in ${root}`);
         prompts.outro(`Done! Next steps:\n\n  cd ${targetDir}\n  pnpm install\n  pnpm dev`);
     }
     catch (error) {
-        prompts.log.error("Failed to clone repository");
+        prompts.log.error("Failed to copy repository");
         console.error(error);
         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);
@@ -150,7 +147,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,22 @@
+import { randomBytes } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { afterEach, beforeEach, describe, 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"));
+    });
+});

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.ecf87cf",
+  "version": "0.0.0-dev.eea25a3",
   "type": "module",
   "license": "MIT",
   "author": "Alpic",
@@ -13,10 +13,13 @@
   },
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "template"
   ],
   "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"
@@ -27,6 +30,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
   }
 }

package/template/.cursor/mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "local": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}

package/template/.nvmrc

@@ -0,0 +1 @@
+lts/jod

package/template/.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "Debug MCP Server",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/dist/index.js",
+      "console": "integratedTerminal",
+      "sourceMaps": true,
+      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
+      "preLaunchTask": "npm: build",
+      "stopOnEntry": false
+    }
+  ]
+}

package/template/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "editor.formatOnSave": true
+}

package/template/.vscode/tasks.json

@@ -0,0 +1,14 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "type": "shell",
+      "command": "npm",
+      "args": ["build"],
+      "group": "build",
+      "label": "npm: build",
+      "detail": "npm build",
+      "problemMatcher": ["$tsc"]
+    }
+  ]
+}

package/template/README.md

@@ -0,0 +1,116 @@
+# 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.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 22+ (see `.nvmrc` for exact version)
+- pnpm (install with `npm install -g pnpm`)
+- Ngrok
+
+### 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.
+
+#### 1. Install
+
+```bash
+pnpm install
+```
+
+#### 2. Start the Development Server
+
+Run the development server from the root directory:
+
+```bash
+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
+
+In a separate terminal, expose your local server using ngrok:
+
+```bash
+ngrok http 3000
+```
+
+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
+
+- 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")
+
+#### 6. Develop with HMR
+
+Now you can edit React components in `web` and see changes instantly:
+
+- 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
+
+**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**.
+
+## 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.
+
+## 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)
+
+- 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)
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Alpic Documentation](https://docs.alpic.ai/)

package/template/_gitignore

@@ -0,0 +1,194 @@
+# =============================================================================
+# 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

package/template/alpic.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://assets.alpic.ai/alpic.json",
+  "buildOutputDir": "server/dist"
+}

package/template/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "apps-sdk-template",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Alpic MCP Server Template",
+  "type": "module",
+  "packageManager": "pnpm@10.18.3",
+  "scripts": {
+    "dev": "pnpm --filter @apps-sdk-template/server dev",
+    "build": "pnpm web:build && rm -rf server/dist && pnpm --filter=@apps-sdk-template/server --prod deploy server/dist && cp -r web/dist server/dist/assets && pnpm --filter=@apps-sdk-template/server build",
+    "start": "pnpm server:start",
+    "inspector": "pnpm --filter @apps-sdk-template/server inspector",
+    "server:build": "pnpm --filter @apps-sdk-template/server build",
+    "server:start": "pnpm --filter @apps-sdk-template/server start",
+    "web:build": "pnpm --filter @apps-sdk-template/web build",
+    "web:preview": "pnpm --filter @apps-sdk-template/web preview"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.4"
+  }
+}