quiver-cli 0.6.0 → 0.8.0

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

@@ -1,175 +0,0 @@
-# Architecture Workflow
-
-## Concepts
-
-A **tool** is a backend action with no UI. It takes input and returns structured output. It can CRUD data and perform operations (checkout, submit, etc.).
-
-A **view** is a tool with a UI. It renders the tool output visually. The UI is a React app that can:
-- navigate multiple views (search → detail → confirmation)
-- manage its own state
-- call other tools to fetch data absent from the view output schema or trigger actions.
-
-## Step 1: Identify the UX Flows
-
-A **flow** is an end-to-end user journey that accomplishes one goal (e.g., "book a flight" = search → select → checkout).
-Extract flows from the SPEC's value proposition. **Stick to the spec**: don't invent flows or infer intermediate steps.
-
-**Example:**
-
-Input (SPEC):
-> Book flights by destination and dates, and cancel existing bookings by booking ID.
-
-✅ Good output:
-```
-Book flight:
-1. Search flights
-2. Select flight
-3. Checkout
-Cancel booking:
-1. Cancel booking
-```
-
-❌ Bad output:
-```
-Search flights:
-1. Search flights
-2. View results
-Book flight: ← wrong: split booking into separate flow
-1. Select flight
-2. Enter passenger details
-3. Checkout
-Cancel booking:
-1. List bookings ← wrong: invented step
-2. Cancel booking
-```
-
-**Do not proceed to Step 2 yet**: validate with user, adjust based on feedback.
-
-## Step 2: Does the flow need UI?
-
-Based on the UX flow:
-
-**YES if:**
-- Browsing/comparing multiple items
-- Visual data improves understanding (maps, charts, images)
-- Selections are easier in a visual layout
-
-**NO if:**
-- Inputs are naturally conversational (amounts, dates, descriptions)
-- Output is simple enough as text
-- No visual element would meaningfully improve the experience
-
-## Step 3: Design the API
-
-### Best Practices
-
-**Naming:** Both views and tools start with a verb: `search_flights`, `get_details`, `create_checkout`.
-
-**One view per flow/intent:** Different flows can have separate views
-❌ `search_flights` view + `view_flight` view (same flow → merge into one view)
-✅ `search_flights` view + `manage_bookings` view (different flows)
-
-**Don't duplicate:** View output is returned to the LLM for conversation. View can be re-invoked. Don't create a tool that duplicates what the view fetches.
-❌ `search_flights` view + `get_flights` tool (same data → view already fetches this)
-✅ unique `search_flights` view that can be re-invoked by LLM or user
-
-**View UI handles its own state:** Cart, selections, and form inputs live in the view - not as tools.
-❌ `add_to_cart` tool (cart is view state)
-❌ `select_seat` tool (selection is view state)
-❌ `update_quantity` tool (form input is view state)
-✅ Tools are for backend operations only: `create_checkout`, `submit_order`, `make_reservation`
-
-**Don't lazy-load:** Tool calls are expensive. Return all needed data upfront.
-❌ `search_flights` view + `get_flight_details` tool (lazy-loading details)
-✅ `search_flights` view returns full flight data including details
-
---- 
-
-For each identified flow:
-
-### If NEEDS UI → View + Optional Tool(s)
-
-**Example: Flight Booking**
-
-UX Flow:
-1. Search flights by dates, destination
-2. Browse results, select flight
-3. View flight details
-4. Click checkout → redirect to payment
-
-API:
-
-**View: search_flights**
-- Input: `{ dates, destination }`
-- Output: `{ flights }` → rendered as list
-- Views: search results, flight detail + passenger form
-- Calls `create_checkout` tool → redirects to payment
-
-**Tool: create_checkout**
-- Input: `{ flightId, passengers[] }`
-- Output: `{ checkoutUrl }` → view redirects to Stripe
-
-### If DOES NOT NEED UI → Tool(s) Only
-
-**Example: Manage Bookings**
-
-UX Flow:
-1. User: "Cancel my flight to Paris"
-2. LLM asks for email, fetches bookings, asks clarifying questions if needed
-3. LLM confirms and cancels
-
-API:
-
-**Tool: list_bookings**
-- Input: `{ email }`
-- Output: `{ booking[] }` → LLM says "You have two upcoming flights for Paris, which one do you want to cancel?"
-
-**Tool: cancel_booking**
-- Input: `{ bookingId }`
-- Output: `{ booking }` → LLM summarizes: "Your booking for Paris on Jan 1 has been canceled."
-
-## Step 4: Review
-
-Present the final architecture to the user, adjust based on feedback.
-
-## Step 5: Update SPEC.md
-
-Update SPEC.md with the UX flows and API design.
-
-**Example:**
-
-```markdown
-...
-
-## UX Flows
-
-Book a flight:
-1. Search flights by destination and dates
-2. Browse results, select flight
-3. Enter passenger details
-4. Checkout (redirect to Stripe)
-
-Cancel booking:
-1. Provide email
-2. Select booking to cancel
-
-## Tools and Views
-
-**View: search_flights**
-- **Input**: `{ destination, dates }`
-- **Output**: `{ flights[] }`
-- **Views**: results list, flight detail, passenger form
-- **Behavior**: manages passenger state locally, calls `create_checkout` tool
-
-**Tool: create_checkout**
-- **Input**: `{ flightId, passengers[] }`
-- **Output**: `{ checkoutUrl }`
-
-**Tool: list_bookings**
-- **Input**: `{ email }`
-- **Output**: `{ bookings[] }`
-
-**Tool: cancel_booking**
-- **Input**: `{ bookingId }`
-- **Output**: `{ success, booking }`
-```

package/template/.agents/skills/apps/skybridge/references/copy-template.md

@@ -1,24 +0,0 @@
-# Start From Template
-
-Scaffold a project by setting up the Skybridge template starter. Skybridge is a TypeScript framework for building MCP servers with type-safe APIs and React views.
-
-## Workflow
-
-1. Ask: "Which package manager?" (npm / pnpm / yarn / bun / deno)
-
-2. Run (do not `rm` beforehand—create handles conflicts):
-```bash
-{pm} create skybridge@latest {target-dir}
-
-# deno
-deno init --npm skybridge {target-dir}
-```
-
-3. [Start the dev server](run-locally.md). Read logs to assess readiness/health; fix any errors (TypeScript, etc.) before proceeding.
-
-4. Start implementing your app using these core concepts:
-- Server handlers and view components → [fetch-and-render-data.md](fetch-and-render-data.md)
-- View state and LLM context → [state-and-context.md](state-and-context.md)
-- Display modes → [ui-guidelines.md](ui-guidelines.md)
-
-5. Delete unused views files and leftover code.

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

@@ -1,33 +0,0 @@
-# Content Security Policy
-
-Views run in sandboxed iframes with strict CSP. Whitelist external domains under the tool's `view.csp`:
-
-| Property | Purpose |
-|----------|---------|
-| `connectDomains` | Fetch/XHR requests to external APIs |
-| `resourceDomains` | Static assets (images, fonts, scripts, styles) |
-| `redirectDomains` | (optional) `openExternal` destinations without safe-link modal |
-| `frameDomains` | (optional) Iframe embeds — triggers stricter review |
-
-```typescript
-server.registerTool(
-  {
-    name: "search-flights",
-    description: "Search flights",
-    inputSchema: { ... },
-    view: {
-      component: "search-flights",
-      description: "Flight results",
-      csp: {
-        connectDomains: ["https://api.example.com"],
-        resourceDomains: ["https://cdn.example.com"],
-        frameDomains: ["https://maps.example.com"],
-        redirectDomains: ["https://checkout.example.com"],
-      },
-    },
-  },
-  async (input) => ({ ... })
-);
-```
-
-Skybridge auto-includes the server's domain. Only add external domains.

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

@@ -1,33 +0,0 @@
-# Deploy
-
-Deploy to Alpic using Alpic CLI.
-
-## Parameters
-
-- {path-to-project} is the path to the project directory. It is relative to the current working directory.
-- When executing a command requiring `{path-to-project}`, check that you provided the correct path to the project.
-
-## Steps
-
-1. **Make sure the user is logged in to Alpic**
-
-Execute `npx alpic@latest login` to login to Alpic.
-
-2. **Deploy to Alpic**
-
-If it's a first time deployment (absence of `.alpic/` folder in the project directory), **ask the user for the project name**.
-Then, execute `npx alpic@latest deploy --yes --project-name {project-name} {path-to-project}`.
-
-3. **Subsequent deployments**
-
-For subsequent deployments (presence of `.alpic/` folder in the project directory), execute `npx alpic@latest deploy --yes {path-to-project}`.
-
-4. **Setup GitHub integration**
-
-If it's a new project, ask the user first if they want to setup git.
-If yes:
-
-- **Push to GitHub** — Commit and push code
-- **Link to Alpic project** - Use `npx alpic@latest git connect --yes {path-to-project}`
-
-Full docs: [docs.alpic.ai/quickstart](https://docs.alpic.ai/quickstart)

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

@@ -1,84 +0,0 @@
-# Discovery Workflow
-
-**Goal: Idea maturation, not speed.**
-
-**Proceed in phases.** Even if the user provides details, complete each phase through conversation. Do not infer or assume but discuss and validate with user. Proceed one phase at a time—do not write SPEC.md nor proceed to implementation until all phases are validated.
-
----
-
-## Phase 1: Value Proposition
-
-1. **Problem + User**: What problem? For whom?
-2. **Pain**: How solved today? What's painful?
-3. **Core actions**: 1-3 focused actions (not a full app port)
-
----
-
-## Phase 2: Why LLM?
-
-1. **Conversational win**: Where does "just say it" beat clicking?
-2. **LLM adds**: What does the LLM contribute? (intent, generation, reasoning)
-3. **What LLM lacks**: Your data? APIs? Ability to take real actions?
-
-**Fail patterns** (stop if any match):
-- Long-form or static content better suited for a website
-- Complex multi-step workflows that exceed display modes
-- Dashboards (use tables, lists, or short paragraphs instead)
-- Full app ports instead of focused atomic actions
-- No clear answer to "why inside an AI assistant vs standalone?"
-
-→ If fails: explain gap, suggest different interface or narrower scope.
-
----
-
-## Phase 3: UI Overview
-
-Describe the user journey through core actions:
-
-1. **First view**: What does the user see when they start?
-2. **Key interactions**: What happens at each core action?
-3. **End state**: How does the experience conclude?
-
----
-
-## Phase 4: Product Context
-
-Gather: existing products, APIs/data, auth method, constraints.
-
----
-
-## Phase 5: Create SPEC.md
-
-**Only after phases 1-4 are discussed and validated with the user.** Do not write SPEC.md from the initial query alone.
-
-Assemble from phases. Target: cwd if empty, else `{app-name}/`.
-
-### Example
-
-```markdown
-# Pizza Ordering App
-
-## Value Proposition
-Order pizza through conversation. Target: PizzaCo customers wanting quick orders. Pain: navigating menus is slower than describing what you want.
-
-**Core actions**: Browse menu, customize order, track delivery.
-
-## Why LLM?
-**Conversational win**: "My usual but with mushrooms" = one sentence vs. multiple screens.
-**LLM adds**: Intent from natural descriptions, handles modifications.
-**What LLM lacks**: Real menu and pricing data, order placement.
-
-## UI Overview
-**First view**: Popular pizzas with quick "reorder last" option.
-**Browsing**: Menu with categories, filters, and customization options.
-**Checkout**: Order summary, confirm, and place order.
-**Tracking**: Live delivery status with ETA and map.
-
-## Product Context
-- **Existing products**: Mobile app, website
-- **API**: REST at api.pizzaco.com (OAuth2, 100 req/min)
-- **Auth**: PizzaCo account (OAuth2)
-- **Constraints**: Payment via existing account only
-```
-
-After SPEC.md is created, confirm with user before proceeding to implementation.

package/template/.agents/skills/apps/skybridge/references/download-file.md

@@ -1,77 +0,0 @@
-# Download file
-
-Save content to the user's filesystem → `useDownload`
-
-Views run in sandboxed iframes where `<a download>` and `URL.createObjectURL` are blocked. `useDownload` asks the host to perform the save; the host shows a confirmation dialog first.
-
-> MCP Apps only. On ChatGPT (Apps SDK), use `useFiles` to work with attachments instead.
-
-## Inline text (CSV, JSON, markdown)
-
-```tsx
-import { useDownload } from "skybridge/web";
-
-function ExportButton({ rows }: { rows: Row[] }) {
-  const { download } = useDownload();
-
-  const handleClick = async () => {
-    const csv = rows.map((r) => `${r.id},${r.name}`).join("\n");
-    const { isError } = await download({
-      contents: [
-        {
-          type: "resource",
-          resource: {
-            uri: "file:///orders.csv", // filename hint
-            mimeType: "text/csv",
-            text: csv,
-          },
-        },
-      ],
-    });
-    if (isError) {
-      // user cancelled or host denied — soft fail, not an exception
-    }
-  };
-
-  return <button onClick={handleClick}>Export CSV</button>;
-}
-```
-
-## Inline binary
-
-```tsx
-await download({
-  contents: [
-    {
-      type: "resource",
-      resource: {
-        uri: "file:///chart.png",
-        mimeType: "image/png",
-        blob: base64EncodedPng,
-      },
-    },
-  ],
-});
-```
-
-## Resource link (host fetches)
-
-```tsx
-await download({
-  contents: [
-    {
-      type: "resource_link",
-      uri: "https://api.example.com/reports/q4.pdf",
-      name: "Q4 Report",
-      mimeType: "application/pdf",
-    },
-  ],
-});
-```
-
-## Notes
-
-- Must be user-initiated (button/menu click). Calls from mount effects will be rejected.
-- The `uri` is a filename hint; the host derives the suggested save name from the last path segment.
-- `isError: true` is a soft signal (user cancelled / host denied). Transport errors throw.
-- For binary content above a few hundred KB, prefer `resource_link` over inline base64.

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

@@ -1,151 +0,0 @@
-# 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

@@ -1,115 +0,0 @@
-# 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` }],
-    };
-  },
-);
-```