quiver-cli 0.8.0 → 1.0.0

package/template/.agents/skills/hono/SKILL.md

@@ -0,0 +1,579 @@
+---
+name: hono
+description: Use when building Hono web applications or when the user asks about Hono APIs, routing, middleware, JSX, validation, testing, or streaming. TRIGGER when code imports from 'hono' or 'hono/*', or user mentions Hono. Use `npx hono request` to test endpoints.
+---
+
+# Hono Skill
+
+Build Hono web applications. This skill provides inline API knowledge for AI. Use `npx hono request` to test endpoints. If the `hono-docs` MCP server is configured, prefer its tools for the latest documentation over the inline reference.
+
+## Hono CLI Usage
+
+### Request Testing
+
+Test endpoints without starting an HTTP server. Uses `app.request()` internally.
+
+```bash
+# GET request
+npx hono request [file] -P /path
+
+# POST request with JSON body
+npx hono request [file] -X POST -P /api/users -d '{"name": "test"}'
+```
+
+**Note:** Do not pass credentials directly in CLI arguments. Use environment variables for sensitive values. `hono request` does not support Cloudflare Workers bindings (KV, D1, R2, etc.). When bindings are required, use `workers-fetch` instead:
+
+```bash
+npx workers-fetch /path
+npx workers-fetch -X POST -H "Content-Type:application/json" -d '{"name":"test"}' /api/users
+```
+
+---
+
+## Hono API Reference
+
+### App Constructor
+
+```ts
+import { Hono } from 'hono'
+
+const app = new Hono()
+
+// With TypeScript generics
+type Env = {
+  Bindings: { DATABASE: D1Database; KV: KVNamespace }
+  Variables: { user: User }
+}
+const app = new Hono<Env>()
+```
+
+### Routing Methods
+
+```ts
+app.get('/path', handler)
+app.post('/path', handler)
+app.put('/path', handler)
+app.delete('/path', handler)
+app.patch('/path', handler)
+app.options('/path', handler)
+app.all('/path', handler) // all HTTP methods
+app.on('PURGE', '/path', handler) // custom method
+app.on(['PUT', 'DELETE'], '/path', handler) // multiple methods
+```
+
+### Routing Patterns
+
+```ts
+// Path parameters
+app.get('/user/:name', (c) => {
+  const name = c.req.param('name')
+  return c.json({ name })
+})
+
+// Multiple params
+app.get('/posts/:id/comments/:commentId', (c) => {
+  const { id, commentId } = c.req.param()
+})
+
+// Optional parameters
+app.get('/api/animal/:type?', (c) => c.text('Animal!'))
+
+// Wildcards
+app.get('/wild/*/card', (c) => c.text('Wildcard'))
+
+// Regexp constraints
+app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
+  const { date, title } = c.req.param()
+})
+
+// Chained routes
+app
+  .get('/endpoint', (c) => c.text('GET'))
+  .post((c) => c.text('POST'))
+  .delete((c) => c.text('DELETE'))
+```
+
+### Route Grouping
+
+```ts
+// Using route()
+const api = new Hono()
+api.get('/users', (c) => c.json([]))
+
+const app = new Hono()
+app.route('/api', api) // mounts at /api/users
+
+// Using basePath()
+const app = new Hono().basePath('/api')
+app.get('/users', (c) => c.json([])) // GET /api/users
+```
+
+### Error Handling
+
+```ts
+app.notFound((c) => c.json({ message: 'Not Found' }, 404))
+
+app.onError((err, c) => {
+  console.error(err)
+  return c.json({ message: 'Internal Server Error' }, 500)
+})
+```
+
+---
+
+## Context (c)
+
+### Response Methods
+
+```ts
+c.text('Hello') // text/plain
+c.json({ message: 'Hello' }) // application/json
+c.html('<h1>Hello</h1>') // text/html
+c.redirect('/new-path') // 302 redirect
+c.redirect('/new-path', 301) // 301 redirect
+c.body('raw body', 200, headers) // raw response
+c.notFound() // 404 response
+```
+
+### Headers & Status
+
+```ts
+c.status(201)
+c.header('X-Custom', 'value')
+c.header('Cache-Control', 'no-store')
+```
+
+### Variables (request-scoped data)
+
+```ts
+// In middleware
+c.set('user', { id: 1, name: 'Alice' })
+
+// In handler
+const user = c.get('user')
+// or
+const user = c.var.user
+```
+
+### Environment (Cloudflare Workers)
+
+```ts
+const value = await c.env.KV.get('key')
+const db = c.env.DATABASE
+c.executionCtx.waitUntil(promise)
+```
+
+### Renderer
+
+```ts
+app.use(async (c, next) => {
+  c.setRenderer((content) =>
+    c.html(
+      <html><body>{content}</body></html>
+    )
+  )
+  await next()
+})
+
+app.get('/', (c) => c.render(<h1>Hello</h1>))
+```
+
+---
+
+## HonoRequest (c.req)
+
+```ts
+c.req.param('id') // path parameter
+c.req.param() // all path params as object
+c.req.query('page') // query string parameter
+c.req.query() // all query params as object
+c.req.queries('tags') // multiple values: ?tags=A&tags=B → ['A', 'B']
+c.req.header('Authorization') // request header
+c.req.header() // all headers (keys are lowercase)
+
+// Body parsing
+await c.req.json() // parse JSON body
+await c.req.text() // parse text body
+await c.req.formData() // parse as FormData
+await c.req.parseBody() // parse multipart/form-data or urlencoded
+await c.req.arrayBuffer() // parse as ArrayBuffer
+await c.req.blob() // parse as Blob
+
+// Validated data (used with validator middleware)
+c.req.valid('json')
+c.req.valid('query')
+c.req.valid('form')
+c.req.valid('param')
+
+// Properties
+c.req.url // full URL string
+c.req.path // pathname
+c.req.method // HTTP method
+c.req.raw // underlying Request object
+```
+
+---
+
+## Middleware
+
+### Using Built-in Middleware
+
+```ts
+import { cors } from 'hono/cors'
+import { logger } from 'hono/logger'
+import { basicAuth } from 'hono/basic-auth'
+import { prettyJSON } from 'hono/pretty-json'
+import { secureHeaders } from 'hono/secure-headers'
+import { etag } from 'hono/etag'
+import { compress } from 'hono/compress'
+import { poweredBy } from 'hono/powered-by'
+import { timing } from 'hono/timing'
+import { cache } from 'hono/cache'
+import { bearerAuth } from 'hono/bearer-auth'
+import { jwt } from 'hono/jwt'
+import { csrf } from 'hono/csrf'
+import { ipRestriction } from 'hono/ip-restriction'
+import { bodyLimit } from 'hono/body-limit'
+import { requestId } from 'hono/request-id'
+import { methodOverride } from 'hono/method-override'
+import { trailingSlash, trimTrailingSlash } from 'hono/trailing-slash'
+
+// Registration
+app.use(logger()) // all routes
+app.use('/api/*', cors()) // specific path
+app.post('/api/*', basicAuth({ username: 'admin', password: 'secret' }))
+```
+
+### Custom Middleware
+
+```ts
+// Inline
+app.use(async (c, next) => {
+  const start = Date.now()
+  await next()
+  const elapsed = Date.now() - start
+  c.res.headers.set('X-Response-Time', `${elapsed}ms`)
+})
+
+// Reusable with createMiddleware
+import { createMiddleware } from 'hono/factory'
+
+const auth = createMiddleware(async (c, next) => {
+  const token = c.req.header('Authorization')
+  if (!token) return c.json({ error: 'Unauthorized' }, 401)
+  await next()
+})
+
+app.use('/api/*', auth)
+```
+
+### Middleware Execution Order
+
+Middleware executes in registration order. `await next()` calls the next middleware/handler, and code after `next()` runs on the way back:
+
+```
+Request → mw1 before → mw2 before → handler → mw2 after → mw1 after → Response
+```
+
+```ts
+app.use(async (c, next) => {
+  // before handler
+  await next()
+  // after handler
+})
+```
+
+---
+
+## Validation
+
+Validation targets: `json`, `form`, `query`, `header`, `param`, `cookie`.
+
+### Zod Validator
+
+```ts
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+const schema = z.object({
+  title: z.string().min(1),
+  body: z.string()
+})
+
+app.post('/posts', zValidator('json', schema), (c) => {
+  const data = c.req.valid('json') // fully typed
+  return c.json(data, 201)
+})
+```
+
+### Valibot / Standard Schema Validator
+
+```ts
+import { sValidator } from '@hono/standard-validator'
+import * as v from 'valibot'
+
+const schema = v.object({ name: v.string(), age: v.number() })
+
+app.post('/users', sValidator('json', schema), (c) => {
+  const data = c.req.valid('json')
+  return c.json(data, 201)
+})
+```
+
+---
+
+## JSX
+
+### Setup
+
+In `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "jsxImportSource": "hono/jsx"
+  }
+}
+```
+
+Or use pragma: `/** @jsxImportSource hono/jsx */`
+
+**Important:** Files using JSX must have a `.tsx` extension. Rename `.ts` to `.tsx` or the compiler will fail.
+
+### Components
+
+```tsx
+import type { PropsWithChildren } from 'hono/jsx'
+
+const Layout = (props: PropsWithChildren) => (
+  <html>
+    <head>
+      <title>My App</title>
+    </head>
+    <body>{props.children}</body>
+  </html>
+)
+
+const UserCard = ({ name }: { name: string }) => (
+  <div class="card">
+    <h2>{name}</h2>
+  </div>
+)
+
+app.get('/', (c) => {
+  return c.html(
+    <Layout>
+      <UserCard name="Alice" />
+    </Layout>
+  )
+})
+```
+
+### jsxRenderer Middleware
+
+Use `jsxRenderer` middleware for layouts. See `npx hono docs /docs/middleware/builtin/jsx-renderer` for details.
+
+### Async Components
+
+```tsx
+const UserList = async () => {
+  const users = await fetchUsers()
+  return (
+    <ul>
+      {users.map((u) => (
+        <li>{u.name}</li>
+      ))}
+    </ul>
+  )
+}
+```
+
+### Fragments
+
+```tsx
+const Items = () => (
+  <>
+    <li>Item 1</li>
+    <li>Item 2</li>
+  </>
+)
+```
+
+---
+
+## Streaming
+
+```ts
+import { stream, streamText, streamSSE } from 'hono/streaming'
+
+// Basic stream
+app.get('/stream', (c) => {
+  return stream(c, async (stream) => {
+    stream.onAbort(() => console.log('Aborted'))
+    await stream.write(new Uint8Array([0x48, 0x65]))
+    await stream.pipe(readableStream)
+  })
+})
+
+// Text stream
+app.get('/stream-text', (c) => {
+  return streamText(c, async (stream) => {
+    await stream.writeln('Hello')
+    await stream.sleep(1000)
+    await stream.write('World')
+  })
+})
+
+// Server-Sent Events
+app.get('/sse', (c) => {
+  return streamSSE(c, async (stream) => {
+    let id = 0
+    while (true) {
+      await stream.writeSSE({
+        data: JSON.stringify({ time: new Date().toISOString() }),
+        event: 'time-update',
+        id: String(id++)
+      })
+      await stream.sleep(1000)
+    }
+  })
+})
+```
+
+---
+
+## Testing with app.request()
+
+Test endpoints without starting an HTTP server:
+
+```ts
+// GET
+const res = await app.request('/posts')
+expect(res.status).toBe(200)
+expect(await res.json()).toEqual({ posts: [] })
+
+// POST with JSON
+const res = await app.request('/posts', {
+  method: 'POST',
+  body: JSON.stringify({ title: 'Hello' }),
+  headers: { 'Content-Type': 'application/json' }
+})
+
+// POST with FormData
+const formData = new FormData()
+formData.append('name', 'Alice')
+const res = await app.request('/users', { method: 'POST', body: formData })
+
+// With mock env (Cloudflare Workers bindings)
+const res = await app.request('/api/data', {}, { KV: mockKV, DATABASE: mockDB })
+
+// Using Request object
+const req = new Request('http://localhost/api', { method: 'DELETE' })
+const res = await app.request(req)
+```
+
+---
+
+## Hono Client (RPC)
+
+Type-safe API client using shared types between server and client.
+
+**IMPORTANT: Routes MUST be chained for type inference to work. Without chaining, the client cannot infer route types.**
+
+```ts
+// Server: routes MUST be chained to preserve types
+const route = app
+  .post('/posts', zValidator('json', schema), (c) => {
+    return c.json({ ok: true }, 201)
+  })
+  .get('/posts', (c) => {
+    return c.json({ posts: [] })
+  })
+export type AppType = typeof route
+
+// Client: use hc() with the exported type
+import { hc } from 'hono/client'
+import type { AppType } from './server'
+
+const client = hc<AppType>('http://localhost:8787/')
+const res = await client.posts.$post({ json: { title: 'Hello' } })
+const data = await res.json() // fully typed
+```
+
+Type utilities:
+
+```ts
+import type { InferRequestType, InferResponseType } from 'hono/client'
+
+type ReqType = InferRequestType<typeof client.posts.$post>
+type ResType = InferResponseType<typeof client.posts.$post, 200>
+```
+
+---
+
+## Helpers
+
+Helpers are utility functions imported from `hono/<helper-name>`:
+
+```ts
+import { getConnInfo } from 'hono/conninfo'
+import { getCookie, setCookie, deleteCookie } from 'hono/cookie'
+import { css, Style } from 'hono/css'
+import { createFactory } from 'hono/factory'
+import { html, raw } from 'hono/html'
+import { stream, streamText, streamSSE } from 'hono/streaming'
+import { testClient } from 'hono/testing'
+import { upgradeWebSocket } from 'hono/cloudflare-workers' // or other adapter
+```
+
+Available helpers: Accepts, Adapter, ConnInfo, Cookie, css, Dev, Factory, html, JWT, Proxy, Route, SSG, Streaming, Testing, WebSocket.
+
+For details, use `npx hono docs /docs/helpers/<helper-name>`.
+
+### Factory
+
+Use `createFactory` to define `Env` once and share it across app, middleware, and handlers:
+
+```ts
+import { createFactory } from 'hono/factory'
+
+const factory = createFactory<Env>()
+
+// Create app (Env type is inherited)
+const app = factory.createApp()
+
+// Create middleware (Env type is inherited, no need to pass generics)
+const mw = factory.createMiddleware(async (c, next) => {
+  await next()
+})
+
+// Create handlers separately (preserves type inference)
+const handlers = factory.createHandlers(logger(), (c) => c.json({ message: 'Hello' }))
+app.get('/api', ...handlers)
+```
+
+---
+
+## Best Practices
+
+- Write handlers inline in route definitions for proper type inference of path params.
+- Use `app.route()` to organize large apps by feature, not Rails-style controllers.
+- Use `createFactory()` to share Env type across app, middleware, and handlers.
+- Use `c.set()`/`c.get()` to pass data between middleware and handlers.
+- Chain validators for multiple request parts (param + query + json).
+- Export app type for RPC: `export type AppType = typeof routes`
+- Use `app.request()` for testing — no server startup needed.
+
+## Adapters
+
+Hono runs on multiple runtimes. The default export works for Cloudflare Workers, Deno, and Bun. For Node.js, use the Node adapter:
+
+```ts
+// Cloudflare Workers / Deno / Bun
+export default app
+
+// Node.js
+import { serve } from '@hono/node-server'
+serve(app)
+```

package/template/.agents/skills/integrations/langfuse/SKILL.md

@@ -23,20 +23,24 @@ This skill helps you use Langfuse effectively across all common workflows: instr
 Follow these principles for ALL Langfuse work:
 
 1. **Documentation First**: NEVER implement based on memory. Always fetch current docs before writing code (Langfuse updates frequently) See the section below on how to access documentation.
-2. **CLI for Data Access**: Use `langfuse-cli` when querying/modifying Langfuse data. See the section below on how to use the CLI. 
+2. **CLI for Data Access**: Use `langfuse-cli` when querying/modifying Langfuse data. See the section below on how to use the CLI.
 3. **Best Practices by Use Case**: Check the relevant reference file below for use-case-specific guidelines before implementing
-4. **Use latest Langfuse versions**: Unless the user specified otherwise or there's a good reason, always use the latest version of Langfuse SDKs/APIs.
+4. **Use latest Langfuse versions**: Unless the user specified otherwise or there's a good reason, always use the latest version of Langfuse SDKs/APIs. Even if you're only creating a plan for another agent to execute, be explicit about the exact version to use.
+5. **If you guide the user through UI** and are unsure about a label or location, inspect the user’s screenshots or ask to see the relevant screen. Do not assume UI labels have the exact same names as API, SDK, or CLI fields.
 
 
 ## Use case specific references
 
 - instrumenting an existing function/application: references/instrumentation.md
 - migrating prompts from a codebase into Langfuse: references/prompt-migration.md
+- creating a prompt or changing any part of an existing prompt, including small edits and debugging/tuning: references/prompt-engineering.md
 - capturing user feedback (thumbs, ratings, implicit signals) as scores on traces: references/user-feedback.md
 - further tips on using the Langfuse CLI: references/cli.md
-- upgrading or migrating Langfuse SDKs to the latest version: references/sdk-upgrade.md
+- upgrading legacy trace-level or dataset-item evaluators to observation-level or experiment evaluators: references/trace-evaluator-upgrade.md. Use the [evaluator migration guide](https://langfuse.com/faq/all/llm-as-a-judge-migration) as the primary reference.
+- preparing an application and Langfuse project for the v4 platform migration: references/v4-project-migration.md
 - judge calibration (LLM-as-a-Judge reliability, simple accuracy checks, advanced split-based validation, confusion matrices, and metric ingestion): references/judge-calibration.md
 - systematic error analysis — reading traces, building failure taxonomy, deciding what to fix: references/error-analysis.md
+- setting up CI/CD experiment gates with `langfuse/experiment-action`: references/ci-cd.md
 - submitting feedback about this skill: references/skill-feedback.md
 
 
@@ -66,8 +70,8 @@ export LANGFUSE_PUBLIC_KEY=pk-lf-...
 export LANGFUSE_SECRET_KEY=sk-lf-...
 export LANGFUSE_BASE_URL=https://cloud.langfuse.com # example for EU cloud. For US cloud it's us.cloud.langfuse.com, and can also be a self-hosted URL. The server must always be specified in order to access Langfuse.
 ```
-
-If not set, ask the user to set them in their shell or a `.env` file (do not ask them to paste keys into chat for security reasons). Keys are found in Langfuse UI → Settings → API Keys.
+If `LANGFUSE_BASE_URL` is used instead of `LANGFUSE_HOST`, run `export LANGFUSE_HOST="$LANGFUSE_BASE_URL"`.
+If not set, ask the user to set them in their shell or a `.env` file. Keys are found in the Langfuse project under Settings -> API Keys; the user should create a project API key pair there. If they do not have a Langfuse account yet, share that they can create one for free at `https://langfuse.com/cloud`. Do not ask them to paste keys into chat for security reasons.
 
 ### Detailed CLI Reference
 
@@ -120,7 +124,7 @@ Returns a JSON response with:
   - `title`: page title
   - `source.content`: array of relevant text excerpts from the page
 
-Search is a great fallback if you cannot find the relevant pages or need more context. Especially useful when debugging issues as all GitHub Issues and Discussions are also indexed. Responses can be large — extract only the relevant portions.
+Search is a great fallback if you cannot find the relevant pages or need more context. Especially useful when debugging issues as all GitHub Issues and Discussions are also indexed. Responses can be large — extract only the relevant portions. Note that changelog posts may also surface here: use them only to confirm a feature exists, never to implement from — their examples may be outdated, so always implement from the docs and API/SDK reference.
 
 ### Documentation Workflow
 

package/template/.agents/skills/integrations/langfuse/references/ci-cd.md

@@ -0,0 +1,41 @@
+---
+name: langfuse-ci-cd
+description: Set up or extend agent regression checks / gating in GitHub Actions CI/CD using `langfuse/experiment-action`.
+metadata:
+  required_access:
+    - CODEBASE
+    - LANGFUSE_PROJECT_INTERFACE
+    - LANGFUSE_PROJECT_SCRIPT
+    - GITHUB
+---
+
+# Langfuse CI/CD
+
+## Checklist
+
+- [ ] Follow the [CI/CD docs page](https://langfuse.com/docs/evaluation/experiments/experiments-ci-cd) and the [langfuse/experiment-action README](https://github.com/langfuse/experiment-action)
+- [ ] Inspect whether the local repository is a GitHub repo. If not, `langfuse/experiment-action` is not applicable. Follow the guide for other [CI/CD systems](https://langfuse.com/docs/evaluation/experiments/experiments-ci-cd#other-cicd-systems) instead
+- [ ] Ask the user which [evaluators and run evaluators](https://langfuse.com/docs/evaluation/experiments/experiments-via-sdk#evaluators) they want to set up
+- [ ] Ask the user if and when yes which regression thresholds they want to set
+- [ ] Confirm dataset existence and shape of the dataset items before writing code with the Langfuse CLI (see `references/cli.md`)
+  - `langfuse-cli api datasets list`
+  - `langfuse-cli api dataset-items list --dataset-name <dataset name> --limit 5`
+- [ ] Propose the user to verify the check by actually running the new CI check (e.g. by creating a pull request)
+- [ ] If the evaluator task uses a third-party dependency, add the necessary CI steps to install them
+
+### GitHub specific checklist
+- [ ] Ask the user how they want the [workflow to be triggered](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows)
+- [ ] If available, use the `gh` CLI to check secret existence / set secrets for:
+      - Langfuse credentials
+      - Credentials required by the evaluator task (e.g. OpenAI or Anthropic API keys)
+
+## Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| `gh` is missing or not authenticated | Install the GitHub CLI if needed, then run `gh auth status` and `gh auth login` before using `gh secret` or `gh workflow` commands. |
+| Local Langfuse environment variables are not set | Set `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, and `LANGFUSE_HOST` locally before using `langfuse-cli`; do not ask the user to paste secret values into chat. |
+| Workflow secrets or action inputs are wrong | Verify `LANGFUSE_PUBLIC_KEY`, `LANGFUSE_SECRET_KEY`, `langfuse_base_url`, and provider secrets exist in the target repo/environment and are passed to the action step. |
+| Forked PR cannot access secrets | GitHub restricts secret access for forked PRs. Document the limitation or choose a trusted trigger such as internal PR, trusted-branch `push`, or `workflow_dispatch`. |
+| No default/base branch exists | Create an initial empty commit on the intended default branch before trying to verify a PR-triggered workflow. |
+| Script fails reading dataset fields | Re-inspect the dataset items with the Langfuse CLI, check `input`, `expected_output`, and metadata, and extract fields from object-shaped outputs explicitly. |

package/template/.agents/skills/integrations/langfuse/references/cli.md

@@ -1,3 +1,11 @@
+---
+name: langfuse-cli
+description: Langfuse CLI usage reference — install, resource/action discovery, credentials, and common usage tips for `langfuse-cli`. Use for further tips on using the Langfuse CLI.
+metadata:
+  required_access:
+    - LANGFUSE_PROJECT_INTERFACE
+---
+
 # Langfuse CLI Reference
 
 Documentation: https://langfuse.com/docs/api-and-data-platform/features/cli