create-skybridge 0.0.0-dev.32f382f → 0.0.0-dev.3300e72

package/dist/index.js

@@ -7,7 +7,7 @@ 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 TEMPLATES = ["demo", "blank", "ecom"];
 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]
@@ -19,6 +19,7 @@ Arguments:
 
 Options:
   --blank        scaffold a minimal project without demo tools and views
+  --ecom         scaffold the ecommerce template (search products, render carousel)
   --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
@@ -60,7 +61,15 @@ const Spinner = {
 };
 export async function init(args = process.argv.slice(2)) {
     const argv = mri(args, {
-        boolean: ["help", "blank", "overwrite", "skip-skills", "start", "yes"],
+        boolean: [
+            "help",
+            "blank",
+            "ecom",
+            "overwrite",
+            "skip-skills",
+            "start",
+            "yes",
+        ],
         string: ["pm"],
         alias: { h: "help" },
     });
@@ -121,30 +130,43 @@ export async function init(args = process.argv.slice(2)) {
     if (argv.blank) {
         template = "blank";
     }
-    else if (yes) {
-        template = "demo";
+    if (argv.ecom) {
+        if (template) {
+            abort("Cannot specify both --blank and --ecom.");
+        }
+        template = "ecom";
     }
-    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();
+    if (!template) {
+        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",
+                    },
+                    {
+                        value: "ecom",
+                        label: "ecom",
+                        hint: "ecommerce template with product search tool and carousel view",
+                    },
+                ],
+                initialValue: "demo",
+            });
+            if (prompts.isCancel(choice)) {
+                return cancel();
+            }
+            template = choice;
         }
-        template = choice;
     }
     // 4. Copy template
     const root = path.resolve(targetDir);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-skybridge",
-  "version": "0.0.0-dev.32f382f",
+  "version": "0.0.0-dev.3300e72",
   "type": "module",
   "license": "MIT",
   "author": "Alpic",
@@ -24,7 +24,7 @@
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.9"
   },
   "scripts": {
     "build": "tsc",

package/templates/blank/package.json

@@ -13,13 +13,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "skybridge": "^0.0.0-dev.32f382f",
+    "skybridge": "^0.0.0-dev.3300e72",
     "vite": "^8.1.3"
   },
   "devDependencies": {
     "@skybridge/devtools": "^1.2.4",
     "@types/node": "^24.13.2",
-    "alpic": "^1.148.1",
+    "alpic": "^1.147.1",
     "tsx": "^4.23.0",
     "typescript": "^6.0.3"
   },

package/templates/demo/package.json

@@ -12,12 +12,12 @@
     "deploy": "alpic deploy"
   },
   "dependencies": {
-    "@alpic-ai/ui": "^1.148.1",
+    "@alpic-ai/ui": "^1.147.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "lucide-react": "^1.23.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
-    "skybridge": "^0.0.0-dev.32f382f",
+    "skybridge": "^0.0.0-dev.3300e72",
     "sonner": "^2.0.7",
     "tw-animate-css": "^1.4.0",
     "vite": "^8.1.3",
@@ -30,7 +30,7 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.3",
-    "alpic": "^1.148.1",
+    "alpic": "^1.147.1",
     "tailwindcss": "^4.3.2",
     "tsx": "^4.23.0",
     "typescript": "^6.0.3"

package/templates/ecom/.dockerignore

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

package/templates/ecom/.env.template

@@ -0,0 +1,2 @@
+# Copy to .env and fill in. Sourced by the server at startup.
+API_KEY=

package/templates/ecom/AGENTS.md

@@ -0,0 +1,2 @@
+This is an MCP ecommerce app built with Skybridge.
+ALWAYS use the `chatgpt-app-builder` skill when planning or updating the codebase: see its "ecommerce" reference.

package/templates/ecom/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.18.0-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.18.0-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/ecom/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/ecom/_gitignore

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

package/templates/ecom/alpic.json

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

package/templates/ecom/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.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/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.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.148.1_@opentelemetry+api@1.9.1_@opentelemetry+core@2.8.0_@opentelemetry+api@1.9_dc7708ba103efafb508db02d69c9f925/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/ecom/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/ecom/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

package/templates/ecom/node_modules/.bin/tsc

@@ -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/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsc" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsc" "$@"
+fi

package/templates/ecom/node_modules/.bin/tsserver

@@ -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/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/typescript@6.0.3/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../typescript/bin/tsserver" "$@"
+else
+  exec node  "$basedir/../typescript/bin/tsserver" "$@"
+fi

package/templates/ecom/node_modules/.bin/tsx

@@ -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/tsx@4.23.0/node_modules/tsx/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/tsx@4.23.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
+else
+  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/tsx@4.23.0/node_modules/tsx/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/tsx@4.23.0/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules:$NODE_PATH"
+fi
+if [ -x "$basedir/node" ]; then
+  exec "$basedir/node"  "$basedir/../tsx/dist/cli.mjs" "$@"
+else
+  exec node  "$basedir/../tsx/dist/cli.mjs" "$@"
+fi

package/templates/ecom/node_modules/.bin/vite

@@ -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/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.2/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.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/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.2/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.1.3_@types+node@24.13.2_esbuild@0.28.1_jiti@2.7.0_terser@5.44.1_tsx@4.23.0_yaml@2.8.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/../vite/bin/vite.js" "$@"
+else
+  exec node  "$basedir/../vite/bin/vite.js" "$@"
+fi

package/templates/ecom/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "skybridge-ecom",
+  "version": "0.0.1",
+  "private": true,
+  "description": "Skybridge MCP ecommerce template",
+  "type": "module",
+  "scripts": {
+    "dev": "skybridge dev",
+    "dev:tunnel": "skybridge dev --tunnel",
+    "build": "skybridge build",
+    "start": "skybridge start",
+    "deploy": "alpic deploy"
+  },
+  "dependencies": {
+    "skybridge": "workspace:*",
+    "vite": "^8.1.3",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@skybridge/devtools": "^1.2.4",
+    "@types/node": "^24.13.2",
+    "alpic": "^1.147.1",
+    "tsx": "^4.23.0",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=24.18.0"
+  }
+}

package/templates/ecom/src/config.ts

@@ -0,0 +1,10 @@
+// App-wide tuning knobs, shared by the server prompt and the tools.
+
+// @todo: minimum number of searches the model runs before rendering. Feeds the
+// prompts to enforce multi-call exploration; raise for deeper results.
+export const MIN_SEARCH_ITERATIONS = 2;
+
+// @todo: how many products the carousel curates toward. CAROUSEL_RANGE is
+// interpolated into the prompts so the model aims for the right amount.
+export const CAROUSEL_MAX_SIZE = 6;
+export const CAROUSEL_RANGE = `${Math.ceil(CAROUSEL_MAX_SIZE / 2)}-${CAROUSEL_MAX_SIZE}`;

package/templates/ecom/src/helpers.ts

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

package/templates/ecom/src/server.ts

@@ -0,0 +1,36 @@
+import { existsSync } from "node:fs";
+import { McpServer } from "skybridge/server";
+import { MIN_SEARCH_ITERATIONS } from "./config.js";
+import {
+  searchProductsDefinition,
+  searchProductsHandler,
+} from "./tools/search-products.js";
+
+// Load .env into process.env when present (native to Node, no dependency).
+if (existsSync(".env")) {
+  process.loadEnvFile();
+}
+
+const server = new McpServer(
+  {
+    // @todo: name and version your app.
+    name: "skybridge-ecom",
+    version: "0.0.1",
+  },
+  {
+    // @todo: adapt this server-wide prompt to your catalog.
+    instructions: `\
+Two phases:
+
+SEARCH: Call search-products ${MIN_SEARCH_ITERATIONS}+ times before presenting—never off one call. \
+Vary the keyword, apply filters from a prior response, or page deeper. \
+Stay silent while searching: emit NO text between calls. Speak only \
+once the carousel renders. Never call a category unavailable before searching.
+
+RENDER: not implemented yet`,
+  },
+).registerTool(searchProductsDefinition, searchProductsHandler);
+
+export default await server.run();
+
+export type AppType = typeof server;

package/templates/ecom/src/tools/search-products.ts

@@ -0,0 +1,185 @@
+import { z } from "zod";
+import {
+  CAROUSEL_MAX_SIZE,
+  CAROUSEL_RANGE,
+  MIN_SEARCH_ITERATIONS,
+} from "../config.js";
+
+// The `search-products` tool: keyword + filters in, matching products out as
+// structured output for the model. It has NO view — include only what the model
+// needs to curate (ids + properties), never presentational data (images, media);
+// render-carousel handles that. Everything this tool needs lives in this file.
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+
+const inputSchema = {
+  // @todo: tune this guidance to your catalog's vocabulary. The model reads
+  // it to turn conversational input into a good keyword.
+  keyword: z.string().describe(
+    `\
+Short noun phrases extracted from conversational input. Never pass full sentences. \
+ALWAYS use the singular form, not the plural. \
+Include color, material, and style descriptors for accuracy. \
+For vague gift or occasion queries without a clear product type, use broad category terms. \
+Preserve the existing keyword across filter refinements; only replace when the user makes a completely different request.`,
+  ),
+
+  // @todo: set the sort options your backend supports (or remove).
+  sort: z.enum(["price-asc", "price-desc"]).optional().describe("Sort order."),
+
+  // @todo: declare the filters your catalog supports. Add one param per
+  // facet (category, color, size...), each optional so the model only sends
+  // what the user asked for. `priceRange` below is just an example, remove it.
+  priceRange: z
+    .string()
+    .optional()
+    .describe(
+      "Price range in dollars. Format: 'min-max' e.g. '0-500', '1000-2000'.",
+    ),
+};
+
+type SearchInput = z.infer<z.ZodObject<typeof inputSchema>>;
+
+// ---------------------------------------------------------------------------
+// Output — model-facing grounding, returned in structuredContent.
+// ---------------------------------------------------------------------------
+
+// The property names the model curates on (grounding only, no presentational data).
+// @todo: replace with your catalog's property names.
+const propertyName = z.enum(["name", "price", "description"]);
+
+const outputSchema = {
+  products: z
+    .array(
+      z.object({
+        id: z.string().describe("Stable product ID; pass to render-carousel."),
+        properties: z
+          .array(
+            z.object({
+              name: propertyName.describe("Which property this is."),
+              value: z.array(z.string()).describe("The property's value(s)."),
+            }),
+          )
+          .describe("Product properties to curate on."),
+      }),
+    )
+    .describe("Matching products, sorted."),
+  pages: z
+    .object({
+      current: z.number(),
+      total: z.number(),
+    })
+    .optional()
+    .describe("Pagination: current page and total page count."),
+  totalHits: z
+    .number()
+    .optional()
+    .describe("Total matching products across all pages."),
+};
+
+type SearchResults = z.infer<z.ZodObject<typeof outputSchema>>;
+
+// ---------------------------------------------------------------------------
+// Data access
+// ---------------------------------------------------------------------------
+
+function search(input: SearchInput): SearchResults {
+  // @todo: plug in your product API / DB. Query it with the input params and map
+  // each result into `products` below. `pages` and `totalHits` are optional.
+  return {
+    products: [], // { id: string; properties: { name: PropertyName; value: string[] }[] }[]
+    pages: { current: 1, total: 1 },
+    totalHits: 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Narration — framing + next-step instructions for the model. The products
+// themselves ride in structuredContent; this text carries NO result data.
+// @todo: customize the NEXT STEPS guidance below for your flow (keep searching
+// vs. curate and render). Remind the model to ground claims in the structured
+// results and never invent attributes.
+// ---------------------------------------------------------------------------
+
+function narrate({ products }: SearchResults): string {
+  const size = products.length;
+
+  if (size === 0) {
+    return `\
+No products found.
+
+NEXT STEP: Broaden the keyword or relax filters, then search again.`;
+  }
+
+  if (size < CAROUSEL_MAX_SIZE) {
+    return `\
+Only a few results.
+
+NEXT STEPS:
+1. If the client asked for a specific product by name, these are fine: curate and call render-carousel with the selected IDs.
+2. Otherwise, search again with broader terms before rendering.`;
+  }
+
+  return `\
+Enough results to present.
+
+NEXT STEPS:
+1. Curate the best matches for the client's intent from the structured results.
+2. Write your recommendation mentioning the selected products.
+3. Call render-carousel with the selected IDs.`;
+}
+
+// ---------------------------------------------------------------------------
+// Tool (registered from server.ts to keep the typed tool chain intact)
+// ---------------------------------------------------------------------------
+
+export const searchProductsDefinition = {
+  name: "search-products" as const,
+
+  // @todo: describe YOUR catalog and how the agent should search and curate
+  // it. This is the model's main guide: be specific about your categories,
+  // the multi-call search loop, and when to render vs. keep searching.
+  description: `\
+Search the product catalog. Handles any query: specific products, broad categories, gifts, occasions, or open discovery.
+Never assume a category is unavailable: always search before responding.
+
+The response is data only: a list of matching products (name, ID, price, description, and any product-specific attributes) plus pagination and the available filters. The raw results are for your eyes only: the client never sees them.
+
+NEVER describe or characterize the raw results to the client: do not mention how many there are, what categories they fall into, or that they look off-topic. While searching, stay silent: do not narrate what you are doing, announce searches, or report progress between tool calls. Speak only once the carousel is rendered.
+
+Act on the response as follows:
+
+- FIRST SEARCH: use the keyword only (plus sort if needed). Read the available filters in the response; these are the only valid filter options for follow-ups.
+- REFINEMENT: if the user's intent matches an available filter, apply it. If it doesn't match any filter, start a new keyword search.
+- ITERATE: a single search is never enough. Run several searches (${MIN_SEARCH_ITERATIONS} minimum) before rendering: vary the keyword, apply a filter, or page deeper, and compare results across them. Quality comes from this multi-call exploration; one call then render gives shallow results.
+- CURATION: read results and pick the best matches for the client's intent, grounding your choice in each product's description. If zero results, broaden the keyword or relax filters and search again: do NOT call render-carousel. If fewer than 3 results and the user didn't ask for a specific product, search again with broader terms. Only after exploring across several searches, call render-carousel with the selected IDs.
+- PRESENT: Once you have ${CAROUSEL_RANGE} distinct, relevant products, call render-carousel with their IDs. Recommend ONLY AFTER the carousel displays, in carousel order.
+
+The sweet spot is ${CAROUSEL_RANGE} products.
+`,
+  annotations: {
+    readOnlyHint: true,
+    openWorldHint: false,
+    destructiveHint: false,
+  },
+
+  // @todo: customize the status messages shown in ChatGPT while the tool runs.
+  _meta: {
+    "openai/toolInvocation/invoking": "Searching",
+    "openai/toolInvocation/invoked": "Done searching",
+  },
+
+  inputSchema,
+  outputSchema,
+};
+
+export function searchProductsHandler(input: SearchInput) {
+  const results = search(input);
+  return {
+    structuredContent: results,
+    content: [{ type: "text" as const, text: narrate(results) }],
+    isError: false,
+  };
+}

package/templates/ecom/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "skybridge/tsconfig",
+
+  "include": ["src", ".skybridge/**/*.d.ts"]
+}

package/templates/ecom/vite.config.ts

@@ -0,0 +1,6 @@
+import { skybridge } from "skybridge/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [skybridge()],
+});