skybridge 0.0.0-dev.f76ccdc → 0.0.0-dev.f784c00

package/README.md

@@ -1,198 +1,152 @@
-<div align="center">
-
-# Skybridge
-
-**Skybridge is the TypeScript framework for building ChatGPT apps**
-
-[![By Alpic](https://img.shields.io/badge/Made%20by%20Alpic-f6ffed?logo=alpic)](https://alpic.ai)
-
-![NPM Downloads](https://img.shields.io/npm/dm/skybridge?color=e90060)
-![NPM Version](https://img.shields.io/npm/v/skybridge?color=e90060)
-![GitHub License](https://img.shields.io/github/license/alpic-ai/skybridge?color=e90060)
-
-</div>
-
-Skybridge comes with 2 packages:
-
-- `skybridge/server`: A drop-in replacement of the `@modelcontextprotocol/sdk` official `McpServer` class with extra features for widget development.
-- `skybridge/web`: A react library with hooks and components to build widgets on the underlying _OpenAI iFrame skybridge_ runtime.
-
-## Quick start
-
-To get started in less than a minute, you can [create a new repository](https://github.com/new?template_name=apps-sdk-template&template_owner=alpic-ai) using our [ChatGPT SDK template](https://github.com/alpic-ai/apps-sdk-template). This template includes a basic setup for both the server and the widgets.
-
-## Installation
-
+# Skybridge - the MCP Apps framework
+
+<p align="center">
+  <a href="https://docs.skybridge.tech">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/skybridge-readme-banner-dark.png" />
+      <img alt="Skybridge, the full-stack React framework for MCP apps and MCP servers" src="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/skybridge-readme-banner-light.png" width="100%" />
+    </picture>
+  </a>
+</p>
+
+<p align="center">
+  <strong>The full-stack React framework for MCP Apps and MCP Servers.</strong>
+</p>
+
+<p align="center">
+  <a href="https://docs.skybridge.tech">Documentation</a> ·
+  <a href="https://docs.skybridge.tech/quickstart/create-new-app">Quickstart</a> ·
+  <a href="https://github.com/alpic-ai/skybridge/tree/main/examples">Examples</a>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/skybridge"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/v/skybridge?color=77F5EE&amp;labelColor=161B22&amp;style=for-the-badge"><img alt="npm version" src="https://img.shields.io/npm/v/skybridge?color=E3FAF7&amp;labelColor=F6F8FA&amp;style=for-the-badge"></picture></a>
+  <a href="https://www.npmjs.com/package/skybridge"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/npm/dm/skybridge?color=D7FFC8&amp;labelColor=161B22&amp;style=for-the-badge"><img alt="npm downloads" src="https://img.shields.io/npm/dm/skybridge?color=E8FBD9&amp;labelColor=F6F8FA&amp;style=for-the-badge"></picture></a>
+  <a href="https://discord.com/invite/gNAazGueab"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/badge/Discord-community-77F5EE?style=for-the-badge&amp;logo=discord&amp;logoColor=77F5EE&amp;labelColor=161B22"><img alt="Discord community" src="https://img.shields.io/badge/Discord-community-E3FAF7?style=for-the-badge&amp;logo=discord&amp;logoColor=5865F2&amp;labelColor=F6F8FA"></picture></a>
+  <a href="https://github.com/alpic-ai/skybridge/blob/main/LICENSE"><picture><source media="(prefers-color-scheme: dark)" srcset="https://img.shields.io/github/license/alpic-ai/skybridge?color=D7FFC8&amp;labelColor=161B22&amp;style=for-the-badge"><img alt="License: MIT" src="https://img.shields.io/github/license/alpic-ai/skybridge?color=E8FBD9&amp;labelColor=F6F8FA&amp;style=for-the-badge"></picture></a>
+</p>
+
+## About Skybridge
+
+Skybridge helps developers build type-safe MCP apps for Claude, ChatGPT and other UI-enabled MCP clients, with a complete set of tooling designed for both humans and agents.
+
+Why? MCP apps extend the [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) with **rich, interactive UI views** rendered from MCP servers. Conversational apps need seamless interaction between the user, the UI, and the model. This means new UX patterns, developer tooling, and abstractions. 
+Plus, the raw SDKs are low-level: no hooks, type safety, HMR, etc.
+
+That's why we built *Skybridge*.
+
+Features include:
+
+- **Delightful dev environment**: Skybridge provides a dev server with a local emulator, hot module reload, and a permanent tunnel to connect your local app to Claude and ChatGPT.
+- **Write once, run everywhere**: the framework abstracts implementation differences between MCP clients, so your app runs seamlessly in Claude, ChatGPT, VSCode, and any other MCP apps compatible client.
+- **Agent-ready**: powerful skills, CLI, and programmatic dev tool APIs, everything your coding agent needs to build MCP apps end-to-end.
+- **Type-safe end-to-end**: tRPC-style inference from MCP server tool definition to React view for type safety from server to frontend.
+- **React-first**: Intuitive React Query-style hooks, with advanced state management. 
+- **Example library**: get started quickly with ChatGPT- and Claude-ready app examples for ecommerce, travel, SaaS, and more.
+
+They chose to build their MCP apps with Skybridge: 
+
+<p align="center">
+  <a href="https://www.datadoghq.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/datadog-dark.svg"><img src="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/datadog-light.svg" alt="Datadog" height="24"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://bitmovin.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/bitmovin-dark.svg"><img src="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/bitmovin-light.svg" alt="Bitmovin" height="22"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://www.evaneos.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/evaneos-dark.svg"><img src="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/evaneos-light.svg" alt="Evaneos" height="18"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://www.touchstream.media"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/touchstream-dark.svg"><img src="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/touchstream-light.svg" alt="Touchstream" height="24"></picture></a>
+  &nbsp;&nbsp;
+  <a href="https://www.cottages.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/cottages-dark.svg"><img src="https://raw.githubusercontent.com/alpic-ai/skybridge/main/docs/images/user-logos/cottages-light.svg" alt="Cottages.com" height="24"></picture></a>
+</p>
+
+## Get started
+
+**For agents**
+
+Install our [skill](https://docs.skybridge.tech/devtools/skills) for building MCP apps and ChatGPT apps:
 ```bash
-pnpm add skybridge
-```
-
-## Concepts
-
-### Widgets
-
-> A widget is a UI component that turns structured tool results into a human-friendly UI. Those are built using React components. They are rendered inside an iframe inline with the conversation on ChatGPT.
-
-Each widget in your app must have a unique name. The name is used to bridge the tool invocation result with the widget React component.
-
-For example, in order to register a new widget named `pokemon` on your ChatGPT app. You should have the following file structure and file contents:
-
-_Project structure_
-
-```
-server/
-└── src/
-    └── index.ts // Register the widget with McpServer.widget()
-web/
-└── src/
-    └── widgets/
-        └── pokemon.tsx // Use the same widget name as the file name
+npx skills add alpic-ai/skybridge -s skybridge
 ```
+Once installed, ask your agent "What skills do you have?" to confirm, then try:
 
-_server/src/index.ts_
+- _Create a new MCP app_
+- _Migrate my MCP server to the Skybridge framework_
+- _Add a new view to my MCP app_ 
 
-```ts
-import { McpServer } from "skybridge/server";
+**For humans**
 
-const server = new McpServer();
-
-server.widget(
-  "pokemon"
-  // Remaining arguments...
-);
+Bootstrap a new project with:
+```bash
+npm create skybridge@latest my-app
 ```
+For full install instructions, read our [**Quickstart guide**](https://docs.skybridge.tech/quickstart/create-new-app).
 
-_web/src/widgets/pokemon.tsx_
-
-```ts
-import { mountWidget } from "skybridge/web";
-
-const Pokemon: React.FunctionComponent = () => {
-  // Your React component code goes here...
-};
-
-mountWidget(<Pokemon />);
-```
+## Documentation
 
-## Packages
+The [Skybridge documentation](https://docs.skybridge.tech) covers the full lifecycle of building MCP Apps:
 
-### skybridge/server
+- [Fundamentals](https://docs.skybridge.tech/fundamentals): understand MCP Apps, ChatGPT Apps, and how Skybridge bridges both runtimes.
+- [Core concepts](https://docs.skybridge.tech/concepts): learn about server <> model <> UI data flows, LLM context sync, type safety, and instant local iteration with our devtools.
+- [Guides](https://docs.skybridge.tech/guides/fetching-data): build real app behavior with tools, views, state, and model communication.
+- [API Reference](https://docs.skybridge.tech/api-reference): browse our MCP server APIs, React hooks, CLI commands, and runtime compatibility.
 
-The `skybridge/server` package is a drop-in replacement of the `@modelcontextprotocol/sdk` official `McpServer` class with extra features for widget development. If you're already using the `@modelcontextprotocol/sdk`, you can simply replace your `McpServer` import with `skybridge/server` and you're good to go.
+## Deploy
 
-### skybridge/web
+Deploy Skybridge apps instantly on [Alpic](https://alpic.ai) for scalable hosting, MCP-specific analytics, permanent tunneling, app store compliance auditing and submission help. You can also self-host on any Node.js-compatible platform.
 
-The `skybridge/web` package is a react library with hooks and components to build widgets on the underlying _OpenAI iFrame skybridge_ runtime.
+See our [deployment guide](https://docs.skybridge.tech/quickstart/deploy) for the full production path.
 
-**Vite plugin**
+## Community & Contributing
 
-The `skybridge/web` package comes with a Vite plugin that allows you to build your widgets as regular Vite apps.
+We'd love your help improving Skybridge. Here are a few ways to get involved:
 
-```ts
-import { defineConfig } from "vite";
-import { skybridge } from "skybridge/web";
+- **Bugs**: If you run into a bug or unexpected behavior, open a [GitHub Issue](https://github.com/alpic-ai/skybridge/issues) with a clear reproduction.
+- **Questions and ideas**: Need help building with Skybridge or have ideas to improve the framework, docs, examples, or developer experience? [Open an issue](https://github.com/alpic-ai/skybridge/issues) or share them on our [Discord](https://discord.com/invite/gNAazGueab).
+- **Pull requests**: For code or documentation changes, read the [Contributing Guide](https://github.com/alpic-ai/skybridge/blob/main/CONTRIBUTING.md) before opening a PR.
 
-export default defineConfig({
-  plugins: [skybridge()],
-});
-```
+Skybridge is released under the [MIT License](https://github.com/alpic-ai/skybridge/blob/main/LICENSE).
 
-**Hooks**
+### Contributors
 
-The `skybridge/web` package comes with a set of hooks to help you build your widgets :
+Built and maintained with ❤️ by [Harijoe](https://github.com/harijoe), [Fred Barthelet](https://github.com/fredericbarthelet), and the [Alpic](https://alpic.ai) team.
 
-- `useOpenAiGlobal`: A generic hook to get any global data from the OpenAI iFrame skybridge runtime (in `window.openai`).
-- `useToolOutput`: A hook to get the initial tool `structuredContent` returned when rendering the widget for the first time. The data inside this hook is not updated when the tool is called again.
-- `useToolResponseMetadata`: A hook to get the initial tool `meta` returned when rendering the widget for the first time. The data inside this hook is not updated when the tool is called again.
-- `useCallTool`: A @tanstack/react-query inspired hook to send make additional tool calls inside a widget.
+<a href="https://github.com/alpic-ai/skybridge/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=alpic-ai/skybridge" alt="Skybridge contributors">
+</a>
 
-_useOpenAiGlobal_
+## Example templates
 
-```ts
-import { useOpenAiGlobal } from "skybridge/web";
+Explore all our example templates in the [Examples](https://docs.skybridge.tech/examples) section of the documentation.
 
-const theme = useOpenAiGlobal("theme");
-```
+### Basic
 
-_useToolOutput_
+| Preview | App | Description | Demo | Code |
+| --- | --- | --- | --- | --- |
+| <img src="docs/images/showcase-example.png" alt="Everything" width="160" /> | Everything | Comprehensive playground app showcasing all Skybridge hooks and features. | [Try Demo](https://everything.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/everything) |
 
-```ts
-import { useToolOutput } from "skybridge/web";
+### Use cases
 
-const toolOutput = useToolOutput();
-```
+| Preview | App | Description | Demo | Code |
+| --- | --- | --- | --- | --- |
+| <img src="docs/images/showcase-capitals.png" alt="Capitals Explorer" width="160" /> | Capitals Explorer | Interactive world map with geolocation, country information, and dynamic capital exploration. | [Try Demo](https://capitals.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/capitals) |
+| <img src="docs/images/showcase-flight-booking.png" alt="Flight Booking" width="160" /> | Flight Booking | Flight search carousel with route details, pricing comparison, and external booking. | [Try Demo](https://flight-booking.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/flight-booking) |
+| <img src="docs/images/showcase-ecommerce.png" alt="Ecommerce Carousel" width="160" /> | Ecommerce Carousel | Product carousel with persistent cart, localization, theme switching, and modal dialogs. | [Try Demo](https://ecommerce.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/ecom-carousel) |
+| <img src="docs/images/showcase-investigation-game.png" alt="Investigation Game" width="160" /> | Investigation Game | Multi-screen mystery game with fullscreen mode, dynamic story progression and context asynchronicity demonstration | [Try Demo](https://investigation-game.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/investigation-game) |
+| <img src="docs/images/showcase-productivity.png" alt="Productivity" width="160" /> | Productivity | Interactive analytics dashboard with charts, theme adaptation, localization, fullscreen mode, and bidirectional tool calls. | [Try Demo](https://productivity.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/productivity) |
+| <img src="docs/images/showcase-times-up.png" alt="Time's Up" width="160" /> | Time's Up | Word-guessing party game where the user gives hints and the AI tries to guess. | [Try Demo](https://times-up.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/times-up) |
+| <img src="docs/images/showcase-lumo.png" alt="Lumo Interactive AI Tutor" width="160" /> | Lumo — Interactive AI Tutor | Adaptive tutor with Mermaid diagrams, mind maps, quizzes, and fill-in-the-blank exercises. | [Try Demo](https://lumo-mcp-app-39519fdd.alpic.live/try) | [View code](https://github.com/connorads/lumo-mcp-app) |
 
-_useToolResponseMetadata_
+### Auth
 
-```ts
-import { useToolResponseMetadata } from "skybridge/web";
+| Preview | Provider | Description | Code |
+| --- | --- | --- | --- |
+| <img src="docs/images/showcase-clerk.png" alt="Auth Clerk" width="160" /> | Clerk | Full OAuth authentication with Clerk and personalized coffee shop search. | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/auth-clerk) |
+| <img src="docs/images/showcase-workos.png" alt="Auth WorkOS AuthKit" width="160" /> | WorkOS AuthKit | Full OAuth authentication with WorkOS AuthKit and personalized coffee shop search. | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/auth-workos) |
+| <img src="docs/images/showcase-stytch.png" alt="Auth Stytch" width="160" /> | Stytch | Full OAuth authentication with Stytch and personalized coffee shop search. | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/auth-stytch) |
+| <img src="docs/images/showcase-auth0.png" alt="Auth Auth0" width="160" /> | Auth0 | Full OAuth authentication with Auth0 and personalized coffee shop search. | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/auth-auth0) |
 
-const toolResponseMetadata = useToolResponseMetadata();
-```
+### UI and component libraries
 
-_useCallTool_ in synchronous mode
-
-```ts
-import { useCallTool } from "skybridge/web";
-
-export const TestTool: React.FunctionComponent = () => {
-  const { callTool, isPending } = useCallTool("myToolName");
-
-  return (
-    <div>
-      <button
-        disabled={isPending}
-        onClick={() => {
-          callTool({ input: "test input" }, {
-            onSuccess: (data) => {
-              alert("Tool returned: " + data);
-            },
-          });
-      >
-        Call Tool inside a widget
-      </button>
-    </div>
-  );
-};
-```
-
-_useCallTool_ in asynchronous mode
-
-```ts
-import { useCallTool } from "skybridge/web";
-
-export const TestTool: React.FunctionComponent = () => {
-  const { callToolAsync, isPending } = useCallTool("myToolName");
-
-  return (
-    <div>
-      <button
-        disabled={isPending}
-        onClick={async () => {
-          const data = await callToolAsync({ input: "test input" });
-          alert("Tool returned: " + data);
-        }}
-      >
-        Call Tool inside a widget
-      </button>
-    </div>
-  );
-};
-```
-
-## Migrate your existing MCP server to a ChatGPT app
-
-If you're already using the `@modelcontextprotocol/sdk` to build a MCP server, you can migrate to a ChatGPT app by following these steps:
-
-1. Replace your `McpServer` import from `@modelcontextprotocol/sdk` with the same import from `skybridge/server`
-2. Create a new vite project in a folder named `web` and install the `skybridge` package
-3. Replace the `vite.config.ts` file with the following:
-
-```ts
-import { defineConfig } from "vite";
-import { skybridge } from "skybridge/web";
-
-export default defineConfig({
-  plugins: [skybridge()],
-});
-```
+| Preview | App | Description | Demo | Code |
+| --- | --- | --- | --- | --- |
+| <img src="docs/images/showcase-manifest-ui.png" alt="Manifest UI" width="160" /> | Manifest UI | Agentic component library example for rich AI-powered experiences. | [Try Demo](https://manifest-ui.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/manifest-ui) |
+| <img src="docs/images/showcase-generative-ui.png" alt="Generative UI" width="160" /> | Generative UI | LLM-generated dynamic UIs with json-render and 36 pre-built shadcn/ui components. | [Try Demo](https://generative-ui.skybridge.tech/try) | [View code](https://github.com/alpic-ai/skybridge/tree/main/examples/generative-ui) |

package/bin/run.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { execute } from "@oclif/core";
+
+await execute({ dir: import.meta.url });

package/dist/cli/detect-port.d.ts

@@ -0,0 +1,18 @@
+export declare function resolvePort(flagPort?: number): Promise<{
+    port: number;
+    fallback: boolean;
+    envWarning?: undefined;
+} | {
+    port: number;
+    fallback: boolean;
+    envWarning: string;
+}>;
+/**
+ * Returns the given port if available, otherwise lets the OS
+ * pick a free port via `listen(0)`.
+ *
+ * @param host - Bind address for the check. Pass `"localhost"` for
+ *   services that bind to 127.0.0.1 (e.g. Vite HMR). Omit for
+ *   services that bind to all interfaces (e.g. the HTTP server).
+ */
+export declare function detectAvailablePort(startPort: number, host?: string): Promise<number>;

package/dist/cli/detect-port.js

@@ -0,0 +1,61 @@
+import net from "node:net";
+const DEFAULT_PORT = 3000;
+export async function resolvePort(flagPort) {
+    if (flagPort && flagPort > 1) {
+        return { port: flagPort, fallback: false };
+    }
+    const rawEnv = process.env.PORT;
+    if (rawEnv) {
+        const parsed = Number(rawEnv);
+        if (Number.isInteger(parsed) && parsed > 0) {
+            return { port: parsed, fallback: false };
+        }
+        return {
+            port: await detectAvailablePort(DEFAULT_PORT),
+            fallback: false,
+            envWarning: `Invalid PORT="${rawEnv}", ignoring and using default`,
+        };
+    }
+    const port = await detectAvailablePort(DEFAULT_PORT);
+    return { port, fallback: port !== DEFAULT_PORT };
+}
+/**
+ * Returns the given port if available, otherwise lets the OS
+ * pick a free port via `listen(0)`.
+ *
+ * @param host - Bind address for the check. Pass `"localhost"` for
+ *   services that bind to 127.0.0.1 (e.g. Vite HMR). Omit for
+ *   services that bind to all interfaces (e.g. the HTTP server).
+ */
+export async function detectAvailablePort(startPort, host) {
+    const available = await isPortAvailable(startPort, host);
+    if (available) {
+        return startPort;
+    }
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.once("error", reject);
+        server.once("listening", () => {
+            const addr = server.address();
+            if (addr && typeof addr === "object") {
+                const { port } = addr;
+                server.close(() => resolve(port));
+            }
+            else {
+                server.close(() => reject(new Error("Failed to detect available port")));
+            }
+        });
+        server.listen(0, host);
+    });
+}
+function isPortAvailable(port, host) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", () => resolve(false));
+        server.once("listening", () => {
+            server.close(() => resolve(true));
+        });
+        server.listen(port, host);
+    });
+}
+//# sourceMappingURL=detect-port.js.map

package/dist/cli/detect-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-port.js","sourceRoot":"","sources":["../../src/cli/detect-port.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,MAAM,YAAY,GAAG,IAAI,CAAC;AAE1B,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAiB;IACjD,IAAI,QAAQ,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAC7C,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;IAChC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9B,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;QAC3C,CAAC;QACD,OAAO;YACL,IAAI,EAAE,MAAM,mBAAmB,CAAC,YAAY,CAAC;YAC7C,QAAQ,EAAE,KAAK;YACf,UAAU,EAAE,iBAAiB,MAAM,+BAA+B;SACnE,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,mBAAmB,CAAC,YAAY,CAAC,CAAC;IACrD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,KAAK,YAAY,EAAE,CAAC;AACnD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAiB,EACjB,IAAa;IAEb,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACzD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAElC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;YAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC;YAC9B,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrC,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;gBACtB,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACpC,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAChB,MAAM,CAAC,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC,CACrD,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACzB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,IAAY,EAAE,IAAa;IAClD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAElC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;QAC3C,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,GAAG,EAAE;YAC5B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import net from \"node:net\";\n\nconst DEFAULT_PORT = 3000;\n\nexport async function resolvePort(flagPort?: number) {\n  if (flagPort && flagPort > 1) {\n    return { port: flagPort, fallback: false };\n  }\n\n  const rawEnv = process.env.PORT;\n  if (rawEnv) {\n    const parsed = Number(rawEnv);\n    if (Number.isInteger(parsed) && parsed > 0) {\n      return { port: parsed, fallback: false };\n    }\n    return {\n      port: await detectAvailablePort(DEFAULT_PORT),\n      fallback: false,\n      envWarning: `Invalid PORT=\"${rawEnv}\", ignoring and using default`,\n    };\n  }\n\n  const port = await detectAvailablePort(DEFAULT_PORT);\n  return { port, fallback: port !== DEFAULT_PORT };\n}\n\n/**\n * Returns the given port if available, otherwise lets the OS\n * pick a free port via `listen(0)`.\n *\n * @param host - Bind address for the check. Pass `\"localhost\"` for\n *   services that bind to 127.0.0.1 (e.g. Vite HMR). Omit for\n *   services that bind to all interfaces (e.g. the HTTP server).\n */\nexport async function detectAvailablePort(\n  startPort: number,\n  host?: string,\n): Promise<number> {\n  const available = await isPortAvailable(startPort, host);\n  if (available) {\n    return startPort;\n  }\n\n  return new Promise((resolve, reject) => {\n    const server = net.createServer();\n\n    server.once(\"error\", reject);\n    server.once(\"listening\", () => {\n      const addr = server.address();\n      if (addr && typeof addr === \"object\") {\n        const { port } = addr;\n        server.close(() => resolve(port));\n      } else {\n        server.close(() =>\n          reject(new Error(\"Failed to detect available port\")),\n        );\n      }\n    });\n\n    server.listen(0, host);\n  });\n}\n\nfunction isPortAvailable(port: number, host?: string): Promise<boolean> {\n  return new Promise((resolve) => {\n    const server = net.createServer();\n\n    server.once(\"error\", () => resolve(false));\n    server.once(\"listening\", () => {\n      server.close(() => resolve(true));\n    });\n\n    server.listen(port, host);\n  });\n}\n"]}

package/dist/cli/header.d.ts

@@ -0,0 +1,4 @@
+export declare const Header: ({ version, children, }: {
+    version: string;
+    children?: React.ReactNode;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/cli/header.js

@@ -0,0 +1,6 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+export const Header = ({ version, children, }) => {
+    return (_jsxs(Box, { marginBottom: 1, children: [_jsxs(Text, { color: "cyan", bold: true, children: ["\u26F0", "  ", "Skybridge"] }), _jsxs(Text, { color: "cyan", children: [" v", version] }), children] }));
+};
+//# sourceMappingURL=header.js.map

package/dist/cli/header.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"header.js","sourceRoot":"","sources":["../../src/cli/header.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,KAAK,CAAC;AAEhC,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,EACrB,OAAO,EACP,QAAQ,GAIT,EAAE,EAAE;IACH,OAAO,CACL,MAAC,GAAG,IAAC,YAAY,EAAE,CAAC,aAClB,MAAC,IAAI,IAAC,KAAK,EAAC,MAAM,EAAC,IAAI,6BACnB,IAAI,iBACD,EACP,MAAC,IAAI,IAAC,KAAK,EAAC,MAAM,mBAAI,OAAO,IAAQ,EACpC,QAAQ,IACL,CACP,CAAC;AACJ,CAAC,CAAC","sourcesContent":["import { Box, Text } from \"ink\";\n\nexport const Header = ({\n  version,\n  children,\n}: {\n  version: string;\n  children?: React.ReactNode;\n}) => {\n  return (\n    <Box marginBottom={1}>\n      <Text color=\"cyan\" bold>\n        ⛰{\"  \"}Skybridge\n      </Text>\n      <Text color=\"cyan\"> v{version}</Text>\n      {children}\n    </Box>\n  );\n};\n"]}

package/dist/cli/run-command.d.ts

@@ -0,0 +1,2 @@
+import { type SpawnOptions } from "node:child_process";
+export declare function runCommand(command: string, options?: SpawnOptions): Promise<void>;

package/dist/cli/run-command.js

@@ -0,0 +1,43 @@
+import { spawn } from "node:child_process";
+export function runCommand(command, options = {
+    stdio: ["ignore", "inherit", "inherit"],
+}) {
+    return new Promise((resolve, reject) => {
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        const proc = spawn(command, {
+            ...options,
+            shell: true,
+        });
+        if (proc.stdout) {
+            proc.stdout.on("data", (chunk) => {
+                stdoutChunks.push(chunk);
+            });
+        }
+        if (proc.stderr) {
+            proc.stderr.on("data", (chunk) => {
+                stderrChunks.push(chunk);
+            });
+        }
+        proc.on("close", (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                const stdoutOutput = Buffer.concat(stdoutChunks).toString();
+                const stderrOutput = Buffer.concat(stderrChunks).toString();
+                const allOutput = [stdoutOutput, stderrOutput]
+                    .filter((output) => output.trim())
+                    .join("\n");
+                const errorMessage = allOutput
+                    ? `Command failed with exit code ${code}\n${allOutput}`
+                    : `Command failed with exit code ${code}`;
+                reject(new Error(errorMessage));
+            }
+        });
+        proc.on("error", (error) => {
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=run-command.js.map

package/dist/cli/run-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-command.js","sourceRoot":"","sources":["../../src/cli/run-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAE9D,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,UAAwB;IACtB,KAAK,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,CAAC;CACxC;IAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,YAAY,GAAa,EAAE,CAAC;QAClC,MAAM,YAAY,GAAa,EAAE,CAAC;QAElC,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,EAAE;YAC1B,GAAG,OAAO;YACV,KAAK,EAAE,IAAI;SACZ,CAAC,CAAC;QAEH,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC/B,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC/B,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC,CAAC,CAAC;QACL,CAAC;QAED,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;YACxB,IAAI,IAAI,KAAK,CAAC,EAAE,CAAC;gBACf,OAAO,EAAE,CAAC;YACZ,CAAC;iBAAM,CAAC;gBACN,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAC5D,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,QAAQ,EAAE,CAAC;gBAC5D,MAAM,SAAS,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC;qBAC3C,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;qBACjC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACd,MAAM,YAAY,GAAG,SAAS;oBAC5B,CAAC,CAAC,iCAAiC,IAAI,KAAK,SAAS,EAAE;oBACvD,CAAC,CAAC,iCAAiC,IAAI,EAAE,CAAC;gBAC5C,MAAM,CAAC,IAAI,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;YAClC,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;YACzB,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC","sourcesContent":["import { type SpawnOptions, spawn } from \"node:child_process\";\n\nexport function runCommand(\n  command: string,\n  options: SpawnOptions = {\n    stdio: [\"ignore\", \"inherit\", \"inherit\"],\n  },\n): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const stdoutChunks: Buffer[] = [];\n    const stderrChunks: Buffer[] = [];\n\n    const proc = spawn(command, {\n      ...options,\n      shell: true,\n    });\n\n    if (proc.stdout) {\n      proc.stdout.on(\"data\", (chunk) => {\n        stdoutChunks.push(chunk);\n      });\n    }\n\n    if (proc.stderr) {\n      proc.stderr.on(\"data\", (chunk) => {\n        stderrChunks.push(chunk);\n      });\n    }\n\n    proc.on(\"close\", (code) => {\n      if (code === 0) {\n        resolve();\n      } else {\n        const stdoutOutput = Buffer.concat(stdoutChunks).toString();\n        const stderrOutput = Buffer.concat(stderrChunks).toString();\n        const allOutput = [stdoutOutput, stderrOutput]\n          .filter((output) => output.trim())\n          .join(\"\\n\");\n        const errorMessage = allOutput\n          ? `Command failed with exit code ${code}\\n${allOutput}`\n          : `Command failed with exit code ${code}`;\n        reject(new Error(errorMessage));\n      }\n    });\n\n    proc.on(\"error\", (error) => {\n      reject(error);\n    });\n  });\n}\n"]}

package/dist/cli/telemetry.d.ts

@@ -0,0 +1,7 @@
+import type { Hook } from "@oclif/core";
+export declare function isEnabled(): boolean;
+export declare function isDebugMode(): boolean;
+export declare function setEnabled(enabled: boolean): void;
+export declare function getMachineId(): string;
+declare const hook: Hook<"finally">;
+export default hook;

package/dist/cli/telemetry.js

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import ci from "ci-info";
+import { PostHog } from "posthog-node";
+const POSTHOG_API_KEY = "phc_rQdkCYr0DO4NcZBQXZnUwsHAbau9zuNwKIpil9FQP6v";
+const POSTHOG_HOST = "https://us.i.posthog.com";
+const ENV_TELEMETRY_DISABLED = "SKYBRIDGE_TELEMETRY_DISABLED";
+const ENV_TELEMETRY_DEBUG = "SKYBRIDGE_TELEMETRY_DEBUG";
+const ENV_DO_NOT_TRACK = "DO_NOT_TRACK";
+const GLOBAL_CONFIG_DIR = join(homedir(), ".skybridge");
+const GLOBAL_CONFIG_FILE = join(GLOBAL_CONFIG_DIR, "config.json");
+let posthogClient = null;
+function getPostHogClient() {
+    if (!posthogClient) {
+        posthogClient = new PostHog(POSTHOG_API_KEY, {
+            host: POSTHOG_HOST,
+            flushAt: 1,
+            flushInterval: 0,
+        });
+    }
+    return posthogClient;
+}
+function readJsonFile(filePath) {
+    try {
+        if (existsSync(filePath)) {
+            const content = readFileSync(filePath, "utf-8");
+            return JSON.parse(content);
+        }
+    }
+    catch {
+        // Ignore errors reading config
+    }
+    return null;
+}
+function writeJsonFile(filePath, data) {
+    try {
+        const dir = join(filePath, "..");
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(filePath, JSON.stringify(data, null, 2), "utf-8");
+    }
+    catch {
+        // Ignore errors writing config
+    }
+}
+function getGlobalConfig() {
+    const existing = readJsonFile(GLOBAL_CONFIG_FILE);
+    if (existing?.machineId && existing?.telemetry !== undefined) {
+        return existing;
+    }
+    const config = {
+        machineId: existing?.machineId || crypto.randomUUID(),
+        telemetry: {
+            enabled: existing?.telemetry?.enabled ?? true,
+        },
+    };
+    writeJsonFile(GLOBAL_CONFIG_FILE, config);
+    return config;
+}
+export function isEnabled() {
+    if (process.env[ENV_TELEMETRY_DISABLED] === "1" ||
+        process.env[ENV_TELEMETRY_DISABLED]?.toLowerCase() === "true") {
+        return false;
+    }
+    if (process.env[ENV_DO_NOT_TRACK] === "1" ||
+        process.env[ENV_DO_NOT_TRACK]?.toLowerCase() === "true") {
+        return false;
+    }
+    if (ci.isCI) {
+        return true;
+    }
+    const config = getGlobalConfig();
+    return config.telemetry.enabled;
+}
+export function isDebugMode() {
+    return (process.env[ENV_TELEMETRY_DEBUG] === "1" ||
+        process.env[ENV_TELEMETRY_DEBUG]?.toLowerCase() === "true");
+}
+export function setEnabled(enabled) {
+    const config = getGlobalConfig();
+    config.telemetry.enabled = enabled;
+    writeJsonFile(GLOBAL_CONFIG_FILE, config);
+}
+export function getMachineId() {
+    if (ci.isCI) {
+        return ci.name ?? "unknown-ci";
+    }
+    return getGlobalConfig().machineId;
+}
+const hook = async ({ id: command, config: { version }, error, }) => {
+    if (!isEnabled()) {
+        return;
+    }
+    const event = {
+        version,
+        machineId: getMachineId(),
+        sessionId: crypto.randomUUID(),
+        isCI: ci.isCI,
+        nodeVersion: process.version,
+        platform: process.platform,
+        outcome: error ? "failure" : "success",
+        error: error?.message,
+    };
+    if (isDebugMode()) {
+        console.error("[Telemetry Debug] Would send event:", JSON.stringify(event, null, 2));
+        return;
+    }
+    try {
+        const client = getPostHogClient();
+        client.capture({
+            distinctId: event.machineId,
+            event: command,
+            properties: event,
+        });
+    }
+    catch {
+        // Silently ignore telemetry errors - never block CLI operation
+    }
+};
+export default hook;
+//# sourceMappingURL=telemetry.js.map