create-skybridge 0.0.0-dev.1b451bd → 0.0.0-dev.1d67840

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alpic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,13 +1,10 @@
 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 { downloadTemplate } from "giget";
 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 = `\
@@ -17,31 +14,32 @@ Create a new Skybridge project by copying the starter template.
 
 Options:
   -h, --help              show this help message
+  --repo <uri>            use a git repository instead of the built-in template
   --overwrite             remove existing files in target directory
+  --immediate             install dependencies and start development server
+
+Repository URI formats:
+  github:user/repo
+  gitlab:user/repo/subdirectory
+  bitbucket:user/repo#branch
 
 Examples:
   create-skybridge my-app
-  create-skybridge . --overwrite
+  create-skybridge my-app --repo github:alpic-ai/skybridge/examples/ecom-carousel
+  create-skybridge . --overwrite --immediate
 `;
-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", "immediate"],
+        string: ["repo"],
+        alias: { h: "help" },
+    });
     const argTargetDir = argv._[0]
-        ? formatTargetDir(String(argv._[0]))
+        ? sanitizeTargetDir(String(argv._[0]))
         : undefined;
+    const argRepo = argv.repo;
     const argOverwrite = argv.overwrite;
+    const argImmediate = argv.immediate;
     const help = argv.help;
     if (help) {
         console.log(helpMessage);
@@ -58,14 +56,15 @@ 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))
+            if (prompts.isCancel(projectName)) {
                 return cancel();
-            targetDir = formatTargetDir(projectName);
+            }
+            targetDir = sanitizeTargetDir(projectName);
         }
         else {
             targetDir = defaultProjectName;
@@ -92,8 +91,9 @@ async function init() {
                         },
                     ],
                 });
-                if (prompts.isCancel(res))
+                if (prompts.isCancel(res)) {
                     return cancel();
+                }
                 overwrite = res;
             }
             else {
@@ -105,51 +105,179 @@ async function init() {
                 emptyDir(targetDir);
                 break;
             case "no":
-                cancel();
-                return;
+                prompts.log.error("Target directory is not empty.");
+                process.exit(1);
         }
     }
-    const root = path.join(cwd, targetDir);
-    // 3. Copy the repository
-    prompts.log.step(`Copying template...`);
+    const root = path.join(process.cwd(), targetDir);
+    // 3. Download from repo or copy template
     try {
-        const templateDir = new URL("../template", import.meta.url).pathname;
-        // Copy directly to target directory
-        run(["cp", "-r", `${templateDir}/.`, root], {
-            stdio: "inherit",
-        });
-        // Set up .gitignore
-        run(["mv", path.join(root, "_gitignore"), path.join(root, ".gitignore")], {
-            stdio: "inherit",
-        });
-        prompts.log.success(`Project created in ${root}`);
-        prompts.outro(`Done! Next steps:\n\n  cd ${targetDir}\n  pnpm install\n  pnpm dev`);
+        if (argRepo) {
+            prompts.log.step(`Downloading ${argRepo}...`);
+            await downloadTemplate(argRepo, { dir: root });
+            prompts.log.success(`Project created in ${root}`);
+        }
+        else {
+            prompts.log.step(`Copying template...`);
+            const templateDir = fileURLToPath(new URL("../template", import.meta.url));
+            // Copy template to target directory
+            fs.cpSync(templateDir, root, {
+                recursive: true,
+                filter: (src) => [".npmrc"].every((file) => !src.endsWith(file)),
+            });
+            // Rename _gitignore to .gitignore
+            fs.renameSync(path.join(root, "_gitignore"), path.join(root, ".gitignore"));
+            prompts.log.success(`Project created in ${root}`);
+        }
+    }
+    catch (error) {
+        prompts.log.error("Failed to create project from template");
+        console.error(error);
+        process.exit(1);
+    }
+    // Update project name in package.json
+    const pkgPath = path.join(root, "package.json");
+    if (!fs.existsSync(pkgPath)) {
+        prompts.log.error("No package.json found in project");
+        process.exit(1);
+    }
+    try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        pkg.name = path.basename(root);
+        fs.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
     }
     catch (error) {
-        prompts.log.error("Failed to copy repository");
+        prompts.log.error("Failed to update project name in package.json");
+        console.error(error);
+        process.exit(1);
+    }
+    const userAgent = process.env.npm_config_user_agent;
+    const pkgManager = userAgent?.split(" ")[0]?.split("/")[0] || "npm";
+    // 4. Ask about skills installation
+    if (interactive) {
+        const skillsResult = await prompts.confirm({
+            message: "Install the coding agents skills? (recommended)",
+            initialValue: true,
+        });
+        if (prompts.isCancel(skillsResult)) {
+            return cancel();
+        }
+        if (skillsResult) {
+            run([
+                ...getPkgExecCmd(pkgManager, "skills"),
+                "add",
+                "alpic-ai/skybridge",
+                "-s",
+                "chatgpt-app-builder",
+            ], {
+                stdio: "inherit",
+                cwd: targetDir,
+            });
+        }
+    }
+    // 5. Ask about immediate installation
+    let immediate = argImmediate;
+    if (immediate === undefined) {
+        if (interactive) {
+            const immediateResult = await prompts.confirm({
+                message: `Install with ${pkgManager} and start now?`,
+            });
+            if (prompts.isCancel(immediateResult)) {
+                return cancel();
+            }
+            immediate = immediateResult;
+        }
+        else {
+            immediate = false;
+        }
+    }
+    const installCmd = [pkgManager, "install"];
+    const runCmd = [pkgManager];
+    switch (pkgManager) {
+        case "yarn":
+        case "pnpm":
+        case "bun":
+            break;
+        case "deno":
+            runCmd.push("task");
+            break;
+        default:
+            runCmd.push("run");
+    }
+    runCmd.push("dev");
+    if (!immediate) {
+        prompts.outro(`Done! Next steps:
+  cd ${targetDir}
+  ${installCmd.join(" ")}
+  ${runCmd.join(" ")}
+`);
+        return;
+    }
+    prompts.log.step(`Installing dependencies with ${pkgManager}...`);
+    run(installCmd, {
+        stdio: "inherit",
+        cwd: root,
+    });
+    prompts.log.step("Starting dev server...");
+    run(runCmd, {
+        stdio: "inherit",
+        cwd: root,
+    });
+}
+function run([command, ...args], options) {
+    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);
     }
 }
-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);
-    return files.length === 0 || (files.length === 1 && files[0] === ".git");
+// Skip user's SPEC.md and IDE/agent preferences (.idea, .claude, etc.)
+function isSkippedEntry(entry) {
+    return ((entry.name.startsWith(".") && entry.isDirectory()) ||
+        entry.name === "SPEC.md");
+}
+function isEmpty(dirPath) {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    return entries.every(isSkippedEntry);
 }
 function emptyDir(dir) {
     if (!fs.existsSync(dir)) {
         return;
     }
-    for (const file of fs.readdirSync(dir)) {
-        if (file === ".git") {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (isSkippedEntry(entry)) {
             continue;
         }
-        fs.rmSync(path.resolve(dir, file), { recursive: true, force: true });
+        fs.rmSync(path.join(dir, entry.name), { recursive: true, force: true });
+    }
+}
+function getPkgExecCmd(pkgManager, cmd) {
+    switch (pkgManager) {
+        case "yarn":
+            return ["yarn", "dlx", cmd];
+        case "pnpm":
+            return ["pnpm", "dlx", cmd];
+        case "bun":
+            return ["bunx", cmd];
+        case "deno":
+            return ["deno", "run", "-A", `npm:${cmd}`];
+        default:
+            return ["npx", cmd];
     }
 }
-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,33 @@
+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 copy the template", async () => {
+        const name = `../../${tempDirName}//project$`;
+        await init([name]);
+        await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
+        expect(fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"))).rejects.toThrowError();
+    });
+    it("should download template from repo", async () => {
+        const name = `../../${tempDirName}//project$`;
+        await init([
+            name,
+            "--repo",
+            "github:alpic-ai/skybridge/examples/ecom-carousel",
+        ]);
+        await fs.access(path.join(process.cwd(), tempDirName, "project", ".gitignore"));
+        expect(fs.access(path.join(process.cwd(), tempDirName, "project", ".npmrc"))).rejects.toThrowError();
+    });
+});

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.1b451bd",
+  "version": "0.0.0-dev.1d67840",
   "type": "module",
   "license": "MIT",
   "author": "Alpic",
@@ -16,18 +16,20 @@
     "dist",
     "template"
   ],
-  "scripts": {
-    "build": "tsc",
-    "test:type": "tsc --noEmit",
-    "test:format": "biome ci",
-    "prepublishOnly": "pnpm run build"
-  },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
+    "giget": "^2.0.0",
     "mri": "^1.2.0"
   },
   "devDependencies": {
-    "@types/node": "^25.0.3",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "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"
   }
-}
+}

package/template/AGENTS.md

@@ -0,0 +1 @@
+Before writing code, first explore the project structure, then invoke the chatgpt-app-builder skill for documentation.

package/template/README.md

@@ -1,114 +1,75 @@
-# ChatGPT Apps SDK Alpic Starter
+# Skybridge 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 ChatGPT and MCP Apps with widget rendering.
 
 ## Getting Started
 
 ### Prerequisites
 
-- Node.js 22+ (see `.nvmrc` for exact version)
-- pnpm (install with `npm install -g pnpm`)
-- Ngrok
+- Node.js 24+
+- 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
 
 ```bash
+npm install
+# or
+yarn install
+# or
 pnpm install
+# or
+bun install
 ```
 
-#### 2. Start the Development Server
+#### 2. Start your local server
 
 Run the development server from the root directory:
 
 ```bash
+npm run dev
+# or
+yarn dev
+# or
 pnpm dev
+# or
+bun 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 the host)
 
-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 the host
 
-**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)