quiver-cli 0.1.0

package/template/.agents/skills/apps/skybridge/references/fetch-and-render-data.md

@@ -0,0 +1,151 @@
+# Fetch and render data
+
+- Fetch structured data and render with custom UI → `view`
+- Fetch textual data or trigger actions → `tool`
+- Tool can be triggered by user interaction within a view UI
+
+## Project Structure
+
+```
+my-app/
+├── src/
+│   ├── server.ts         # McpServer with tool + view registration
+│   ├── helpers.ts        # Type-safe hooks via generateHelpers
+│   ├── index.css         # Global CSS, must be imported in every view
+│   └── views/            # React components (filename = view component name)
+│       └── search-flights.tsx
+└── package.json
+```
+
+**Naming convention**: View filename must match the `view.component` name using kebab-case.
+`search_flights` → register with `view.component: "search-flights"` → file `views/search-flights.tsx`
+
+## Server Handlers
+
+Output:
+- **`structuredContent`**: concise JSON the view uses and the model reads. Include only what the model should see.
+- **`content`** (optional): narration (Markdown or plaintext) shown to LLM
+- **`_meta`** (optional): large or sensitive data exclusively for the view. _meta never reaches the model.
+
+Annotations (set `true` when):
+- **`readOnlyHint`**: only reads data, no side effects
+- **`openWorldHint`**: publishes content or reaches outside user's account
+- **`destructiveHint`**: deletes or overwrites user data
+
+**Example**:
+
+- src/server.ts
+```typescript
+import { McpServer } from "skybridge/server";
+import { z } from "zod";
+
+const server = new McpServer(
+  { name: "my-app", version: "0.0.1" },
+  { capabilities: {} },
+)
+  .registerTool(
+    {
+      name: "search-flights",
+      description: "Search for flights",
+      inputSchema: { destination: z.string(), dates: z.string() },
+      annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
+      view: {
+        component: "search-flights",
+        description: "Flight results",
+      },
+    },
+    async ({ destination, dates }) => {
+      const flights = await fetchFlights(destination, dates);
+      const structuredContent = { flights: [] };
+      const _meta = { images: [] }
+      for (const { id, departureTime, price, airlineLogo } of flights) {
+        structuredContent.flights.push({ id, departureTime, price });
+        _meta.images.push(airlineLogo);
+      }
+      return {
+        structuredContent,
+        content: [{ type: "text", text: `Found ${flights.length} flights.` }],
+        _meta // mind the underscore prefix
+      };
+    }
+  )
+  .registerTool(
+    {
+      name: "book-flight",
+      description: "Book a flight",
+      inputSchema: { flightId: z.string() },
+      annotations: { readOnlyHint: false, openWorldHint: false, destructiveHint: false },
+    },
+    async ({ flightId }) => {
+      const confirmationId = await bookFlight(flightId);
+      return {
+        structuredContent: { confirmationId },
+        content: [{ type: "text", text: `Flight booked. Confirmation: ${confirmationId}` }],
+      };
+    }
+  );
+
+server.run();
+
+export type AppType = typeof server;
+```
+
+## UI Components
+
+- generate type-safe hooks with `generateHelpers`
+- `useToolInfo`: access view input/output
+- `useCallTool`: trigger tool from UI
+
+**Example**:
+
+- src/helpers.ts
+```typescript
+import { generateHelpers } from "skybridge/web";
+import type { AppType } from "./server.js";
+
+export const { useToolInfo, useCallTool } = generateHelpers<AppType>();
+```
+
+- src/views/search-flights.tsx
+```tsx
+import "@/index.css";
+import { useToolInfo, useCallTool } from "../helpers.js";
+
+export default function SearchFlights() {
+  const { input, output, isPending, responseMetadata } = useToolInfo<"search-flights">();
+  const {
+    callTool, // returns void, use `data` to get the actual output
+    data: bookFlightOutput,
+    isPending: isBooking,
+    isSuccess: isBooked,
+  } = useCallTool("book-flight");
+
+  if (isPending) {
+    return <div>Searching flights to {input?.destination}...</div>;
+  }
+
+  if (isBooked) {
+    return <div>Booked! Confirmation: {bookFlightOutput.structuredContent.confirmationId}</div>;
+  }
+
+  return (
+    <div>
+      <h2>Flights to {input.destination}</h2>
+      <ul>
+        {output.flights.map((flight, i) => (
+          <li key={i}>
+            <img src={responseMetadata.images[i]} />
+            {flight.departureTime} - ${flight.price}
+            <button
+              onClick={() => callTool({ flightId: flight.id })}
+              disabled={isBooking}
+            >
+              {isBooking ? "Booking..." : "Book"}
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```

package/template/.agents/skills/apps/skybridge/references/oauth.md

@@ -0,0 +1,115 @@
+# OAuth Authentication
+
+Enable user authentication so tools can access user-specific data.
+
+## How it works
+
+1. MCP server exposes OAuth discovery endpoints
+2. Host reads them, walks the user through OAuth, refreshes tokens
+3. Host calls `/mcp` with `Authorization: Bearer <token>`
+4. `requireBearerAuth` middleware verifies the token and rejects with HTTP 401 if invalid — tool handlers never run unauthenticated
+5. Tool handlers read user identity from `extra.authInfo`
+
+## 1. Discovery endpoints
+
+Mount OAuth metadata so MCP clients can discover the authorization server:
+
+```typescript
+// src/server.ts
+import { mcpAuthMetadataRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { McpServer } from "skybridge/server";
+
+const server = new McpServer(
+  { name: "my-app", version: "0.0.1" },
+  { capabilities: {} },
+).use(
+  mcpAuthMetadataRouter({
+    oauthMetadata: {
+      issuer: "https://your-oauth-provider.com",
+      authorization_endpoint: "https://your-oauth-provider.com/oauth2/authorize",
+      token_endpoint: "https://your-oauth-provider.com/oauth2/token",
+      response_types_supported: ["code"],
+      grant_types_supported: ["authorization_code", "refresh_token"],
+      code_challenge_methods_supported: ["S256"],
+    },
+    // SERVER_URL: this server's public URL (localhost:3000, Alpic tunnel, or prod)
+    resourceServerUrl: new URL(process.env.SERVER_URL),
+  }),
+);
+```
+
+This serves `/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`.
+
+## 2. Write a token verifier
+
+`requireBearerAuth` takes a `verifier` with `verifyAccessToken(token): Promise<AuthInfo>`. Verify the provider's JWT against its JWKS:
+
+⚠️ Fetch your provider's docs for the exact JWKS URL and issuer.
+
+```typescript
+// src/auth.ts
+import { InvalidTokenError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import * as jose from "jose";
+
+const jwks = jose.createRemoteJWKSet(
+  new URL("https://your-oauth-provider.com/oauth2/jwks"),
+);
+
+export async function verifyAccessToken(token: string): Promise<AuthInfo> {
+  const { payload } = await jose.jwtVerify(token, jwks, {
+    issuer: "https://your-oauth-provider.com",
+  });
+
+  if (!payload.sub || typeof payload.sub !== "string") {
+    throw new InvalidTokenError("missing sub claim");
+  }
+
+  return {
+    token,
+    clientId: (payload.client_id ?? payload.azp ?? "") as string,
+    scopes: typeof payload.scope === "string" ? payload.scope.split(" ") : [],
+    expiresAt: payload.exp,
+    extra: { sub: payload.sub },
+  };
+}
+```
+
+## 3. Enforce auth on /mcp
+
+```typescript
+// src/server.ts (continued)
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { verifyAccessToken } from "./auth.js";
+
+server.use(
+  "/mcp",
+  requireBearerAuth({
+    verifier: { verifyAccessToken },
+    requiredScopes: ["openid", "email", "profile"], // optional
+  }),
+);
+```
+
+Unauthenticated requests get HTTP 401 before any tool handler runs.
+
+## 4. Read auth in handlers
+
+```typescript
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+
+server.registerTool(
+  {
+    name: "get-orders",
+    description: "Get user orders",
+  },
+  async (_input, extra) => {
+    const auth = extra.authInfo as AuthInfo;
+    const orders = await fetchOrders(auth.extra?.sub as string);
+    return {
+      structuredContent: { orders },
+      content: [{ type: "text", text: `Found ${orders.length} orders` }],
+    };
+  },
+);
+```

package/template/.agents/skills/apps/skybridge/references/open-external-links.md

@@ -0,0 +1,71 @@
+# Open external links
+
+- "Open in App" button URL → `useSetOpenInAppUrl`
+- External redirect → `useOpenExternal`
+
+## "Open in App" button
+
+Top right corner in fullscreen mode. Set programmatically. If the origin matches the view server URL, ChatGPT navigates to the full href (any path). If the origin differs, ChatGPT falls back to the view server URL.
+
+**Example**:
+```tsx
+import { useSetOpenInAppUrl } from "skybridge/web";
+import { useEffect } from "react";
+
+function ProductDetail({ productId }: { productId: string }) {
+  const setOpenInAppUrl = useSetOpenInAppUrl();
+
+  useEffect(() => {
+    setOpenInAppUrl(`https://example.com/products/${productId}`).catch(console.error);
+  }, [productId]);
+
+  return <div>{/* Product details */}</div>;
+}
+```
+
+## External redirect
+
+**Example**:
+```tsx
+import { useOpenExternal } from "skybridge/web";
+
+function ExternalLink() {
+  const openExternal = useOpenExternal();
+
+  return (
+    <button onClick={() => openExternal("https://example.com")}>
+      Visit Website
+    </button>
+  );
+}
+```
+
+
+You can control return-path behavior with an optional second argument (ChatGPT only):
+
+```tsx
+openExternal("https://example.com", { redirectUrl: false });
+```
+
+Use `redirectUrl: false` to skip automatic `?redirectUrl=...` appending.
+
+Shows confirmation dialog unless domain is whitelisted:
+
+```typescript
+// src/server.ts
+server.registerTool(
+  {
+    name: "search-flights",
+    description: "Search for flights",
+    inputSchema: { destination: z.string(), dates: z.string() },
+    view: {
+      component: "search-flights",
+      description: "Flight results",
+      csp: {
+        redirectDomains: ["https://airline.example.com"],
+      },
+    },
+  },
+  async ({ destination, dates }) => { /* ... */ }
+);
+```

package/template/.agents/skills/apps/skybridge/references/prompt-llm.md

@@ -0,0 +1,20 @@
+# Prompt model
+
+Trigger an LLM completion from user interaction with `useSendFollowUpMessage`.
+
+**Example:**
+```tsx
+import { useSendFollowUpMessage } from "skybridge/web";
+
+export function FindBestFlightButton() {
+  const sendMessage = useSendFollowUpMessage();
+
+  return (
+    <button onClick={() => sendMessage({
+      prompt: "Find the best flight option, based on user preferences and agenda."
+    })}>
+      Find Best Flight
+    </button>
+  );
+}
+```

package/template/.agents/skills/apps/skybridge/references/publish.md

@@ -0,0 +1,19 @@
+# Publish to Directories
+
+## 1. Audit Annotations
+
+**Common cause of rejection.** Ensure all tools and views have correct annotations. See [fetch-and-render-data.md](fetch-and-render-data.md).
+
+## 2. Audit CSP
+
+Ensure all external domains are declared in the tool's `view.csp`. See [csp.md](csp.md).
+
+## 3. Submit
+
+### ChatGPT
+Guide user to submit the app at [platform.openai.com](https://platform.openai.com) → Apps.
+
+OpenAI verifies app ownership via `/.well-known/openai-apps-challenge`. Guide user to Alpic **Distribution** tab → **OpenAI Apps Verification Token** → paste the token from OpenAI.
+
+### Claude
+Guide user to submit the app on the [Anthropic Connectors Directory FAQ](https://support.claude.com/en/articles/11596036-anthropic-connectors-directory-faq).

package/template/.agents/skills/apps/skybridge/references/run-locally.md

@@ -0,0 +1,51 @@
+# Running Locally Workflow
+
+## 1. Start Dev Server
+
+Install dependencies and start the dev server in the background:
+
+```bash
+{pm} install && {pm} run dev
+```
+
+For Deno projects, use `deno task dev` instead.
+
+When started, output the local MCP server and devtools URL.
+
+Hot reload enabled (nodemon for server, HMR for views).
+
+## 2. Connect to AI Assistants (Optional)
+
+Ask user if they want to test in ChatGPT/Claude or just use local devtools.
+
+If yes, expose the local server via Alpic tunnel:
+
+```bash
+alpic tunnel --port 3000
+```
+
+Extract the forwarding URL from Alpic tunnel output (e.g., `https://cool-marmot-fondue-420.alpic.dev`).
+
+### Connect to ChatGPT
+Provide the user with these instructions to create the app in ChatGPT:
+1. Go to [Apps Settings](https://chatgpt.com/apps#settings/Connectors) → Create App
+2. Enter a name and description for the app
+3. Paste this URL: `{tunnel-url}/mcp`
+4. Set the appropriate Authentication scheme. In doubt, pick "No Authentication"
+5. Click Create
+6. Test by typing `@{app-name}` in a ChatGPT chat
+
+**Troubleshooting:**
+- 'Create App' button missing: ask user to enable Developer mode in Settings → Apps → Advanced Settings
+- 'Create App' button not working: confirm they have ChatGPT Plus, Pro, Business, or Enterprise/Edu plan
+
+
+### Connect to Claude
+Provide the user with these instructions to create the app in Claude:
+1. Go to [Connector Settings](https://claude.ai/settings/connectors) → Add Custom Connector
+2. Enter a name and URL: `{tunnel-url}/mcp`
+3. Click Create
+4. In Claude chat, click the `+` button and select `@{app-name}`
+
+**Troubleshooting:**
+- 'Add Custom Connector' button missing: confirm they have a Claude paid plan

package/template/.agents/skills/apps/skybridge/references/state-and-context.md

@@ -0,0 +1,151 @@
+# Manage View State and LLM Context
+
+- View state (`useViewState`/`createStore`) persists and is visible to LLM as structured data.
+- `data-llm` gives LLM context for referential language ("this one").
+- React `useState` is ephemeral and invisible to LLM.
+
+**Decision guide:**
+| Need | Use |
+|------|-----|
+| Persist data, single component | `useViewState` |
+| Persist data, shared across components, complex mutations | `createStore` |
+| Help LLM understand "this one" | `data-llm` |
+| Ephemeral UI only (hover, animation) | `useState` |
+
+## useViewState
+
+Single component, simple access patterns.
+
+```tsx
+function SeatPicker({ seats }) {
+  const [{ selectedSeat }, setState] = useViewState({ selectedSeat: null });
+
+  return (
+    <div className="seat-grid">
+      {seats.map(seat => (
+        <button
+          key={seat.id}
+          onClick={() => setState((prev) => ({ ...prev, selectedSeat: seat.id }))}
+          className={selectedSeat === seat.id ? "selected" : ""}
+        >
+          {seat.id}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+**Why useViewState:** Single component reads `selectedSeat` to highlight button. View or LLM reads when booking.
+
+## createStore
+
+Shared across components, complex mutations. `createStore` is a thin wrapper around Zustand.
+
+```tsx
+import { createStore } from "skybridge/web";
+
+const useCartStore = createStore<CartState>((set) => ({
+  cart: [],
+  add: (item) => set((s) => ({ cart: [...s.cart, item] })),
+  remove: (id) => set((s) => ({ cart: s.cart.filter(i => i.id !== id) })),
+}));
+
+// ProductCard.tsx
+function ProductCard({ product }) {
+  const add = useCartStore((s) => s.add);
+  return <button onClick={() => add(product)}>Add to Cart</button>;
+}
+
+// CartSummary.tsx
+function CartSummary() {
+  const cart = useCartStore((s) => s.cart);
+  return <span>{cart.length} items</span>;
+}
+```
+
+**Why createStore:** Cart accessed by multiple components. View or LLM reads items at checkout.
+
+## data-llm
+
+Tell the LLM what user is viewing/doing. One-way—view doesn't read it back. These are annotations—don't put complex objects here.
+
+```tsx
+function ProductDetail({ product }) {
+  return (
+    <div data-llm={`Viewing: ${product.name}, $${product.price}, ${product.inStock ? "in stock" : "out of stock"}`}>
+      <h1>{product.name}</h1>
+      <p>${product.price}</p>
+    </div>
+  );
+}
+```
+
+**Why data-llm:** When user asks "Is this one good?" or "Add this to cart", LLM knows what "this" refers to.
+
+## Common mistakes
+
+```tsx
+// DON'T: useState is not persisted, LLM can't see it
+const [selected, setSelected] = useState(null);
+
+// DO: useViewState persists and LLM sees it
+const [{ selected }, setState] = useViewState({ selected: null });
+```
+
+```tsx
+// DON'T: Complex object in data-llm
+<div data-llm={JSON.stringify(cart)}>
+
+// DO: Human-readable summary
+<div data-llm={`Cart: ${cart.length} items, $${total}`}>
+```
+
+## Combined example
+
+Todo list. User checks off tasks, asks "what should I prioritize?"
+
+```tsx
+function TaskList() {
+  // PERSIST: All tasks with completed status
+  const [{ tasks }, setState] = useViewState({
+    tasks: [
+      { id: 1, title: "Buy groceries", completed: false },
+      { id: 2, title: "Call mom", completed: true },
+    ]
+  });
+
+  // EPHEMERAL: Task user is viewing — reset on reopen
+  const [viewing, setViewing] = useState(null);
+
+  return (
+    // CONTEXT: What user is looking at — LLM answers "how should I handle this task?"
+    <div data-llm={viewing
+      ? `Viewing: "${viewing.title}"`
+      : `${tasks.filter(t => !t.completed).length} tasks remaining`
+    }>
+      {tasks.map(t => (
+        <Task
+          key={t.id}
+          task={t}
+          onView={() => setViewing(t)}
+          onToggle={() => setState((prev) => ({
+            ...prev,
+            tasks: prev.tasks.map(task =>
+              task.id === t.id ? { ...task, completed: !task.completed } : task
+            )
+          }))}
+        />
+      ))}
+    </div>
+  );
+}
+```
+
+**Why each?**
+
+| What | API | Why |
+|------|-----|-----|
+| `tasks` | `useViewState` | Persists. Tasks and progress survive reopen. |
+| `viewing` | `useState` | Ephemeral. Current focus resets on reopen. |
+| `"Viewing: Buy groceries"` | `data-llm` | LLM context. Understands "this task" in conversation. |