create-skybridge 0.0.0-dev.cf133c0 → 0.0.0-dev.cf29341

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 the catalog",
+    "openai/toolInvocation/invoked": "Searched the catalog",
+  },
+
+  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()],
+});

package/dist/index.test.d.ts

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

package/dist/index.test.js

@@ -1,33 +0,0 @@
-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/template/AGENTS.md

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

package/template/README.md

@@ -1,97 +0,0 @@
-# Skybridge Starter
-
-A minimal TypeScript template for building MCP and ChatGPT Apps with the [Skybridge](https://docs.skybridge.tech/home) framework.
-
-## Getting Started
-
-### Prerequisites
-
-- Node.js 24+
-- HTTP tunnel such as [ngrok](https://ngrok.com/download) if you want to test with remote MCP hosts like ChatGPT or Claude.ai.
-
-### Local Development
-
-#### 1. Install
-
-```bash
-npm install
-# or
-yarn install
-# or
-pnpm install
-# or
-bun install
-```
-
-#### 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:
-- Your MCP server at `http://localhost:3000/mcp`.
-- Skybridge DevTools UI at `http://localhost:3000/`.
-
-#### 3. Project structure
-
-```
-├── server/
-│   └── src/
-│       └── index.ts      # Server entry point
-├── web/
-│   ├── src/
-│   │   ├── widgets/      # React components (one per widget)
-│   │   ├── helpers.ts    # Shared utilities
-│   │   └── index.css     # Global styles
-│   └── vite.config.ts
-├── alpic.json            # Deployment config
-├── nodemon.json          # Dev server config
-└── package.json
-```
-
-### Create your first widget
-
-#### 1. Add a new widget
-
-- Register a widget in `server/src/server.ts` with a unique name (e.g., `my-widget`) using [`registerWidget`](https://docs.skybridge.tech/api-reference/register-widget)
-- Create a matching React component at `web/src/widgets/my-widget.tsx`. **The file name must match the widget name exactly**.
-
-#### 2. Edit widgets with Hot Module Replacement (HMR)
-
-Edit and save components in `web/src/widgets/` — changes will appear instantly inside your App.
-
-#### 3. Edit server code
-
-Modify files in `server/` and refresh the connection with your testing MCP Client to see the changes.
-
-### Testing your App
-
-You can test your App locally by using our DevTools UI on `localhost:3000` while running the `pnpm dev` command.
-
-To test your app with other MCP Clients like ChatGPT, Claude or VSCode, see [Testing Your App](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 in minutes is [Alpic](https://alpic.ai/).
-1. Create an account on [Alpic platform](https://app.alpic.ai/). 
-2. Connect your GitHub repository to automatically deploy at each commit. 
-3. Use your remote App URL to connect it to MCP Clients, or use the Alpic Playground to easily test your App.
-
-## 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/template/node_modules/.bin/alpic

@@ -1,21 +0,0 @@
-#!/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.95.0_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.3/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.95.0_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.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/alpic@1.95.0_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.3/node_modules/alpic/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/alpic@1.95.0_@opentelemetry+api@1.9.0_arktype@2.1.27_rxjs@7.8.2_typescript@5.9.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/../alpic/bin/run.js" "$@"
-else
-  exec node  "$basedir/../alpic/bin/run.js" "$@"
-fi

package/template/node_modules/.bin/sb

@@ -1,21 +0,0 @@
-#!/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/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules:/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/template/node_modules/.bin/skybridge

@@ -1,21 +0,0 @@
-#!/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/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/node_modules"
-else
-  export NODE_PATH="/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules/skybridge/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/skybridge@0.35.5_@modelcontextprotocol+sdk@1.27.1_zod@4.3.6__@skybridge+devtools@0.35.5_2bc251bdf070edcf23d16b641b0b7ce8/node_modules:/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/template/node_modules/.bin/vite

@@ -1,21 +0,0 @@
-#!/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.0.0_@types+node@25.2.3_esbuild@0.27.2_jiti@2.6.1_terser@5.44.1_tsx@4.21.0_yaml@2.8.2/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.0.0_@types+node@25.2.3_esbuild@0.27.2_jiti@2.6.1_terser@5.44.1_tsx@4.21.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.0.0_@types+node@25.2.3_esbuild@0.27.2_jiti@2.6.1_terser@5.44.1_tsx@4.21.0_yaml@2.8.2/node_modules/vite/node_modules:/home/runner/work/skybridge/skybridge/node_modules/.pnpm/vite@8.0.0_@types+node@25.2.3_esbuild@0.27.2_jiti@2.6.1_terser@5.44.1_tsx@4.21.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/template/package.json

@@ -1,33 +0,0 @@
-{
-  "name": "apps-sdk-template",
-  "version": "0.0.1",
-  "private": true,
-  "description": "Alpic MCP Server Template",
-  "type": "module",
-  "scripts": {
-    "dev": "skybridge dev",
-    "build": "skybridge build",
-    "start": "skybridge start",
-    "deploy": "alpic deploy"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
-    "skybridge": ">=0.35.5 <1.0.0",
-    "vite": "^8.0.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@skybridge/devtools": ">=0.35.5 <1.0.0",
-    "@types/react": "^19.2.14",
-    "@types/react-dom": "^19.2.3",
-    "@vitejs/plugin-react": "^6.0.1",
-    "alpic": "^1.95.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
-  },
-  "engines": {
-    "node": ">=24.14.0"
-  }
-}

package/template/server/src/index.ts

@@ -1,62 +0,0 @@
-import { McpServer } from "skybridge/server";
-import { z } from "zod";
-
-const Answers = [
-  "As I see it, yes",
-  "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",
-  "Signs point to yes",
-  "Very doubtful",
-  "Without a doubt",
-  "Yes definitely",
-  "Yes",
-  "You may rely on it",
-];
-
-const server = new McpServer(
-  {
-    name: "alpic-openai-app",
-    version: "0.0.1",
-  },
-  { capabilities: {} },
-).registerWidget(
-  "magic-8-ball",
-  {
-    description: "Magic 8 Ball",
-  },
-  {
-    description: "For fortune-telling or seeking advice.",
-    inputSchema: {
-      question: z.string().describe("The user question."),
-    },
-  },
-  async ({ question }) => {
-    try {
-      // deterministic answer
-      const hash = question
-        .split("")
-        .reduce((acc, char) => acc + char.charCodeAt(0), 0);
-      const answer = Answers[hash % Answers.length];
-      return {
-        structuredContent: { answer },
-        content: [],
-        isError: false,
-      };
-    } catch (error) {
-      return {
-        content: [{ type: "text", text: `Error: ${error}` }],
-        isError: true,
-      };
-    }
-  },
-);
-
-server.run();
-
-export type AppType = typeof server;

package/template/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "skybridge/tsconfig",
-
-  "compilerOptions": {
-    "outDir": "dist"
-  },
-
-  "include": ["server/src", "web/src"]
-}

package/template/web/src/helpers.ts

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