create-skybridge 0.0.0-dev.2 → 0.0.0-dev.2009590

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,389 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as prompts from "@clack/prompts";
+import spawn from "cross-spawn";
+import mri from "mri";
+const OUTPUT_TAIL_LINES = 10;
+const DEFAULT_PROJECT_NAME = "skybridge-project";
+const PACKAGE_MANAGERS = ["bun", "deno", "npm", "pnpm", "yarn"];
+const TEMPLATES = ["demo", "blank"];
+const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf-8"));
+const version = pkg.version;
+const HELP_MESSAGE = `Usage: skybridge create [path] [options]
+
+⛰ Skybridge v${version} - the fullstack framework for building MCP Apps
+
+Arguments:
+  path           Where the project will be created. Prompted when omitted.
+
+Options:
+  --blank        scaffold a minimal project without demo tools and views
+  --overwrite    remove existing files if target directory is not empty
+  --pm <choice>  package manager to use (choices: ${PACKAGE_MANAGERS.join(", ")}. default to npm when none is provided or infered)
+  --skip-skills  skip installing coding agent skills
+  --start        start dev server
+  --yes          skip prompts and use default values for unprovided options
+  --help         display this help message
+
+Non-interactive usage:
+  Mandatory: path argument and --yes option
+  Example: skybridge create my-app --yes`;
+const isTTY = process.stdout.isTTY;
+const _spinner = prompts.spinner();
+const Spinner = {
+    start(msg) {
+        if (!isTTY) {
+            prompts.log.info(msg);
+        }
+        else {
+            _spinner.clear();
+            _spinner.start(msg);
+        }
+    },
+    stop(msg) {
+        if (!isTTY) {
+            prompts.log.success(msg);
+        }
+        else {
+            _spinner.stop(msg);
+        }
+    },
+    error(msg) {
+        if (!isTTY) {
+            prompts.log.error(msg);
+        }
+        else {
+            _spinner.error(msg);
+        }
+    },
+};
+export async function init(args = process.argv.slice(2)) {
+    const argv = mri(args, {
+        boolean: ["help", "blank", "overwrite", "skip-skills", "start", "yes"],
+        string: ["pm"],
+        alias: { h: "help" },
+    });
+    if (argv.help) {
+        console.log(HELP_MESSAGE);
+        return;
+    }
+    const { yes } = argv;
+    let targetDir = argv._[0] ? sanitizeTargetDir(String(argv._[0])) : undefined;
+    if (yes && !targetDir) {
+        abort("The target directory is required in non-interactive mode.", "Example: skybridge create my-app --yes");
+    }
+    let pm = parsePackageManager(argv.pm || "");
+    if (argv.pm && !pm) {
+        abort(`Invalid --pm value "${argv.pm}". Expected one of: ${PACKAGE_MANAGERS.join(", ")}.`);
+    }
+    console.log(); // cosmetic line break
+    prompts.intro(`\x1b[1;36m⛰  Welcome to Skybridge v${version} \x1b[22m- the fullstack framework for building MCP Apps\x1b[0m`);
+    // 1. Target directory
+    if (!targetDir) {
+        const choice = await prompts.text({
+            message: "Project directory:",
+            placeholder: DEFAULT_PROJECT_NAME,
+            defaultValue: DEFAULT_PROJECT_NAME,
+            validate: (value) => !value || sanitizeTargetDir(value).length > 0
+                ? undefined
+                : "Invalid project name",
+        });
+        if (prompts.isCancel(choice)) {
+            return cancel();
+        }
+        targetDir = sanitizeTargetDir(choice);
+    }
+    // 2. Existing-directory handling
+    if (fs.existsSync(targetDir) && !isEmpty(targetDir)) {
+        if (argv.overwrite) {
+            emptyDir(targetDir);
+        }
+        else if (yes) {
+            prompts.log.error(`Target directory "${targetDir}" is not empty. Use --overwrite to remove existing files.`);
+            process.exit(1);
+        }
+        else {
+            const ok = await prompts.confirm({
+                message: `Target directory "${targetDir}" is not empty. Remove existing files?`,
+                initialValue: true,
+            });
+            if (prompts.isCancel(ok) || !ok) {
+                return cancel();
+            }
+            Spinner.start(`Cleaning up ${targetDir}`);
+            emptyDir(targetDir);
+            Spinner.stop(`Cleaned up ${targetDir}`);
+        }
+    }
+    // 3. Template
+    let template;
+    if (argv.blank) {
+        template = "blank";
+    }
+    else if (yes) {
+        template = "demo";
+    }
+    else {
+        const choice = await prompts.select({
+            message: "Choose a template:",
+            options: [
+                {
+                    value: "demo",
+                    label: "demo",
+                    hint: "starter code with tools and UI",
+                },
+                {
+                    value: "blank",
+                    label: "blank",
+                    hint: "minimal boilerplate without tools",
+                },
+            ],
+            initialValue: "demo",
+        });
+        if (prompts.isCancel(choice)) {
+            return cancel();
+        }
+        template = choice;
+    }
+    // 4. Copy template
+    const root = path.resolve(targetDir);
+    Spinner.start(`Copying ${template} template`);
+    try {
+        const templateDir = fileURLToPath(new URL(`../templates/${template}`, import.meta.url));
+        fs.cpSync(templateDir, root, {
+            recursive: true,
+            filter: (src) => [".npmrc"].every((file) => !src.endsWith(file)),
+        });
+        const gitignoreSource = path.join(root, "_gitignore");
+        if (fs.existsSync(gitignoreSource)) {
+            fs.renameSync(gitignoreSource, path.join(root, ".gitignore"));
+        }
+        Spinner.stop(`Copied ${template} template`);
+    }
+    catch (error) {
+        Spinner.error("Failed to copy template");
+        abort(String(error));
+    }
+    // 5. Set package.json name to the project dir basename
+    try {
+        const pkgPath = path.join(root, "package.json");
+        const projectPkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        projectPkg.name = path.basename(root);
+        fs.writeFileSync(pkgPath, `${JSON.stringify(projectPkg, null, 2)}\n`);
+    }
+    catch (error) {
+        abort("Failed to update project name in package.json.", String(error));
+    }
+    // Async spawn wrapper so a spinner can keep animating during the subprocess
+    // (cross-spawn.sync would block the event loop). Captures stdout/stderr to
+    // `output` when stdio is "pipe", trimmed to the last OUTPUT_TAIL_LINES lines
+    // — install errors land at the tail, so we keep that and prefix with an
+    // ellipsis when content gets dropped.
+    function spawnAsync(command, args) {
+        return new Promise((resolve) => {
+            let raw = "";
+            const child = spawn(command, args, {
+                stdio: ["ignore", "pipe", "pipe"],
+                cwd: root,
+            });
+            child.stdout?.on("data", (chunk) => {
+                raw += chunk.toString();
+            });
+            child.stderr?.on("data", (chunk) => {
+                raw += chunk.toString();
+            });
+            const done = (status) => {
+                const tail = [];
+                for (const part of raw.split("\n").reverse()) {
+                    const line = part.trim();
+                    if (!line) {
+                        continue;
+                    }
+                    if (tail.length >= OUTPUT_TAIL_LINES) {
+                        tail.push(`… (truncated, showing last ${OUTPUT_TAIL_LINES} lines)`);
+                        break;
+                    }
+                    tail.push(line);
+                }
+                resolve({ status, output: tail.reverse().join("\n") });
+            };
+            child.on("close", done);
+            child.on("error", () => done(1));
+        });
+    }
+    // 6. Skills install (single Y/n prompt)
+    let installSkills;
+    if (argv["skip-skills"]) {
+        installSkills = false;
+    }
+    else if (yes) {
+        installSkills = true;
+    }
+    else {
+        const choice = await prompts.confirm({
+            message: "Install coding agent skills? (recommended)",
+            initialValue: true,
+        });
+        if (prompts.isCancel(choice)) {
+            return cancel();
+        }
+        installSkills = choice;
+    }
+    if (installSkills) {
+        Spinner.start("Installing coding agent skills");
+        const { status, output } = await spawnAsync("npx", [
+            "--yes",
+            "skills",
+            "add",
+            "alpic-ai/skybridge",
+            "--skill",
+            "chatgpt-app-builder",
+            "--agent",
+            "universal",
+            "claude-code",
+            "--copy", // something the symlink fails for some reason
+            "--yes",
+        ]);
+        // skills cli always returns 0 so we look for the success message
+        if (status === 0 && output.includes("Done!")) {
+            Spinner.stop(`Installed coding agent skills`);
+        }
+        else {
+            Spinner.error(`Failed to install coding agent skills:
+\x1b[2m${output}\x1b[0m`);
+            prompts.log.error("Try manually: `npx skills add alpic-ai/skybridge`.");
+        }
+    }
+    // 7. Package manager — autodetect, prompt only if detection fails (interactive)
+    if (!pm) {
+        pm = detectPackageManager() || "npm";
+    }
+    if (!yes) {
+        const choice = await prompts.select({
+            message: "Choose a package manager:",
+            options: PACKAGE_MANAGERS.map((value) => ({ value })),
+            initialValue: pm,
+        });
+        if (prompts.isCancel(choice)) {
+            return cancel();
+        }
+        pm = choice;
+    }
+    // 8. Always install dependencies
+    Spinner.start(`Installing dependencies with ${pm}`);
+    const { status, output } = await spawnAsync(pm, ["install"]);
+    if (status === 0) {
+        Spinner.stop(`Installed dependencies with ${pm}`);
+    }
+    else {
+        Spinner.error(`Dependency installation failed:
+\x1b[2m${output}\x1b[0m`);
+        abort(`Try manually: cd ${targetDir} && ${pm} install`);
+    }
+    // 9. Start dev server?
+    let start = false;
+    if (argv.start) {
+        start = true;
+    }
+    else if (!yes) {
+        const choice = await prompts.confirm({
+            message: "Start dev server now?",
+            initialValue: true,
+        });
+        if (prompts.isCancel(choice)) {
+            return cancel();
+        }
+        start = choice;
+    }
+    if (start) {
+        prompts.outro(`Starting dev server in ${targetDir}…`);
+        const devResult = spawn.sync(pm, scriptArgs(pm, "dev"), {
+            stdio: "inherit",
+            cwd: root,
+        });
+        process.exit(devResult.status ?? 0);
+    }
+    prompts.log.success("All set! Next steps:");
+    prompts.log.info(`Start:
+cd ${targetDir}
+${scriptCommand(pm, "dev")}`);
+    prompts.log.info(`Deploy:
+${scriptCommand(pm, "deploy")}`);
+    prompts.outro(`🛟  Need help?
+   Chat: https://discord.alpic.ai
+   Docs: https://docs.skybridge.tech`);
+}
+function cancel() {
+    prompts.cancel("Operation cancelled");
+    process.exit(0);
+}
+function abort(...lines) {
+    for (const line of lines) {
+        prompts.log.error(line);
+    }
+    prompts.outro("Aborted");
+    process.exit(1);
+}
+function parsePackageManager(value) {
+    switch (value) {
+        case "bun":
+            return "bun";
+        case "deno":
+            return "deno";
+        case "npm":
+            return "npm";
+        case "pnpm":
+            return "pnpm";
+        case "yarn":
+            return "yarn";
+        default:
+            return undefined;
+    }
+}
+function detectPackageManager() {
+    const userAgent = process.env.npm_config_user_agent;
+    if (!userAgent) {
+        return undefined;
+    }
+    const name = userAgent.split(" ")[0]?.split("/")[0];
+    return parsePackageManager(name);
+}
+function scriptArgs(pm, script) {
+    switch (pm) {
+        case "yarn":
+        case "pnpm":
+        case "bun":
+            return [script];
+        case "deno":
+            return ["task", script];
+        case "npm":
+            return ["run", script];
+    }
+}
+function scriptCommand(pm, script) {
+    return [pm, ...scriptArgs(pm, script)].join(" ");
+}
+function sanitizeTargetDir(targetDir) {
+    return targetDir.trim().replace(/\/+$/g, "");
+}
+// 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 entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (isSkippedEntry(entry)) {
+            continue;
+        }
+        fs.rmSync(path.join(dir, entry.name), { recursive: true, force: true });
+    }
+}

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,28 +1,36 @@
 {
   "name": "create-skybridge",
-  "version": "0.0.0-dev.2",
+  "version": "0.0.0-dev.2009590",
   "type": "module",
   "license": "MIT",
   "author": "Alpic",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alpic-ai/skybridge.git"
+  },
   "bin": {
     "create-skybridge": "index.js"
   },
   "files": [
     "index.js",
-    "dist"
+    "dist",
+    "templates"
   ],
   "dependencies": {
-    "@clack/prompts": "^0.11.0",
+    "@clack/prompts": "^1.1.0",
+    "cross-spawn": "^7.0.6",
     "mri": "^1.2.0"
   },
   "devDependencies": {
-    "@types/node": "^25.0.3",
-    "picocolors": "^1.1.1",
-    "typescript": "^5.9.3"
+    "@types/cross-spawn": "^6.0.6",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "tsc",
-    "test:type": "tsc --noEmit",
+    "test": "pnpm run test:unit && pnpm run test:format",
+    "test:unit": "vitest run",
+    "format": "biome check --write --error-on-warnings",
     "test:format": "biome ci"
   }
 }

package/templates/blank/.dockerignore

@@ -0,0 +1,4 @@
+node_modules
+.git
+dist
+.env*

package/templates/blank/AGENTS.md

@@ -0,0 +1 @@
+This is a ChatGPT/MCP app built with Skybridge. ALWAYS use the `chatgpt-app-builder` skill when planning or updating the codebase.

package/templates/blank/Dockerfile

@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1
+
+# Dockerfile for a Skybridge MCP server.
+#
+# Detects npm, yarn, or pnpm from the lockfile in your project.
+# (For bun or deno, adapt the install/build/prune commands below.)
+
+# Build stage: install deps, compile the app, then prune dev deps.
+FROM node:24-slim AS build
+WORKDIR /app
+
+COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./
+RUN --mount=type=cache,target=/root/.npm \
+    --mount=type=cache,target=/usr/local/share/.cache/yarn \
+    --mount=type=cache,target=/root/.local/share/pnpm/store \
+    if [ -f package-lock.json ]; then \
+      npm ci; \
+    elif [ -f yarn.lock ]; then \
+      corepack enable yarn && yarn install --frozen-lockfile; \
+    elif [ -f pnpm-lock.yaml ]; then \
+      corepack enable pnpm && pnpm install --frozen-lockfile; \
+    else \
+      echo "No lockfile found." && exit 1; \
+    fi
+
+ENV NODE_ENV=production
+
+COPY . .
+RUN if [ -f package-lock.json ]; then \
+      npm run build && npm prune --omit=dev; \
+    elif [ -f yarn.lock ]; then \
+      corepack enable yarn && yarn build && yarn install --frozen-lockfile --production=true; \
+    elif [ -f pnpm-lock.yaml ]; then \
+      corepack enable pnpm && pnpm build && pnpm prune --prod; \
+    fi
+
+# Runtime stage: copy built artifacts and prod deps, run as non-root.
+FROM node:24-slim AS runtime
+WORKDIR /app
+ENV NODE_ENV=production
+
+USER node
+
+COPY --from=build --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+COPY --from=build --chown=node:node /app/package.json ./package.json
+
+EXPOSE 3000
+
+# Run the built server directly rather than via `npm start` / `skybridge start`.
+# Each wrapper adds a process layer that can swallow SIGTERM, which makes
+# graceful shutdowns time out on platforms like Cloud Run, Fly, and k8s.
+CMD ["node", "dist/__entry.js"]

package/templates/blank/README.md

@@ -0,0 +1,92 @@
+# Skybridge Boilerplate
+
+A minimal TypeScript boilerplate for building MCP and ChatGPT Apps with the [Skybridge](https://docs.skybridge.tech) framework.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 24+
+
+### Local Development
+
+#### 1. Install
+
+```bash
+npm install
+# or
+pnpm install
+# or
+bun install
+# or
+deno install
+# or
+yarn install
+```
+
+#### 2. Start your local server
+
+Run the development server from the root directory:
+
+```bash
+npm run dev
+# or
+pnpm dev
+# or
+bun dev
+# or
+deno task dev
+# or
+yarn dev
+```
+
+This command starts:
+- Your MCP server at `http://localhost:3000/mcp`.
+- Skybridge DevTools UI at `http://localhost:3000`.
+
+#### 3. Project structure
+
+```
+├── src/
+│   ├── server.ts         # Server entry point
+│   └── helpers.ts        # Shared utilities
+├── vite.config.ts
+├── alpic.json            # Deployment config
+└── package.json
+```
+
+### Create your first view
+
+#### 1. Add a new view
+
+- Register a tool in `src/server.ts` with a unique name (e.g., `my-view`) using [`registerTool`](https://docs.skybridge.tech/api-reference/register-tool) and a `view` config.
+- Create a matching React component at `src/views/my-view.tsx`. **The file name must match the view name exactly**.
+
+#### 2. Edit views with Hot Module Replacement (HMR)
+
+Edit and save components in `src/views/` — changes will appear instantly inside your App.
+
+#### 3. Edit server code
+
+Modify files in `src/` and refresh the tool list with your MCP Client to see the changes.
+
+### Testing your App
+
+You can test your app locally by using our DevTools UI on `http://localhost:3000` while running the `dev` command.
+
+To connect your app with web clients like ChatGPT or Claude, expose your server on the internet by adding the `--tunnel` flag.
+By enabling the tunnel, you'll also be able to access a playground to chat with your app and a real LLM. Learn more by reading the [test guide](https://docs.skybridge.tech/quickstart/test-your-app).
+
+
+## Deploy to Production
+
+Skybridge is infrastructure vendor agnostic, and your app can be deployed on any cloud platform supporting MCP.
+
+The simplest way to deploy your app is by running the `deploy` command, which will push your MCP server to the [Alpic](https://alpic.ai/) cloud for free.
+
+## Resources
+- [Skybridge Documentation](https://docs.skybridge.tech/)
+- [Apps SDK Documentation](https://developers.openai.com/apps-sdk)
+- [MCP Apps Documentation](https://github.com/modelcontextprotocol/ext-apps/tree/main)
+- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
+- [Alpic Documentation](https://docs.alpic.ai/)

package/templates/blank/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+dist/
+.env*
+.DS_store
+*.tsbuildinfo
+.skybridge/
+.vercel/

package/templates/blank/alpic.json

@@ -0,0 +1,3 @@
+{
+  "$schema": "https://assets.alpic.ai/alpic.json"
+}

package/templates/blank/node_modules/.bin/alpic

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.136.3_@opentelemetry+api@1.9.1_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.136.3_@opentelemetry+api@1.9.1_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.136.3_@opentelemetry+api@1.9.1_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.136.3_@opentelemetry+api@1.9.1_arktype@2.1.27_rxjs@7.8.2_typescript@6.0.2/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../alpic/bin/run.js" "$@"
+else
+  exec node  "$basedir/../alpic/bin/run.js" "$@"
+fi

package/templates/blank/node_modules/.bin/sb

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../skybridge/bin/run.js" "$@"
+else
+  exec node  "$basedir/../skybridge/bin/run.js" "$@"
+fi

package/templates/blank/node_modules/.bin/skybridge

@@ -0,0 +1,21 @@
+#!/bin/sh
+basedir=$(dirname "$(echo "$0" | sed -e 's,\\,/,g')")
+
+case `uname` in
+    *CYGWIN*|*MINGW*|*MSYS*)
+        if command -v cygpath > /dev/null 2>&1; then
+            basedir=`cygpath -w "$basedir"`
+        fi
+    ;;
+esac
+
+if [ -z "$NODE_PATH" ]; then
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../skybridge/bin/run.js" "$@"
+else
+  exec node  "$basedir/../skybridge/bin/run.js" "$@"
+fi