@punks/cli 0.1.16 → 1.0.0

package/dist/skills/frameworks/elysia/elysiajs/plugins/opentelemetry.md

@@ -0,0 +1,167 @@
+# OpenTelemetry Plugin - SKILLS.md
+
+## Installation
+```bash
+bun add @elysiajs/opentelemetry
+```
+
+## Basic Usage
+```typescript
+import { opentelemetry } from '@elysiajs/opentelemetry'
+import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
+
+new Elysia()
+  .use(opentelemetry({
+    spanProcessors: [
+      new BatchSpanProcessor(new OTLPTraceExporter())
+    ]
+  }))
+```
+
+Auto-collects spans from OpenTelemetry-compatible libraries. Parent/child spans applied automatically.
+
+## Config
+Extends OpenTelemetry SDK params:
+
+- `autoDetectResources` (true) - Auto-detect from env
+- `contextManager` (AsyncHooksContextManager) - Custom context
+- `textMapPropagator` (CompositePropagator) - W3C Trace + Baggage
+- `metricReader` - For MeterProvider
+- `views` - Histogram bucket config
+- `instrumentations` (getNodeAutoInstrumentations()) - Metapackage or individual
+- `resource` - Custom resource
+- `resourceDetectors` ([envDetector, processDetector, hostDetector]) - Auto-detect needs `autoDetectResources: true`
+- `sampler` - Custom sampler (default: sample all)
+- `serviceName` - Namespace identifier
+- `spanProcessors` - Array for tracer provider
+- `traceExporter` - Auto-setup OTLP/http/protobuf with BatchSpanProcessor if not set
+- `spanLimits` - Tracing params
+
+### Resource Detectors via Env
+```bash
+export OTEL_NODE_RESOURCE_DETECTORS="env,host"
+# Options: env, host, os, process, serviceinstance, all, none
+```
+
+## Export to Backends
+Example - Axiom:
+```typescript
+.use(opentelemetry({
+  spanProcessors: [
+    new BatchSpanProcessor(
+      new OTLPTraceExporter({
+        url: 'https://api.axiom.co/v1/traces',
+        headers: {
+          Authorization: `Bearer ${Bun.env.AXIOM_TOKEN}`,
+          'X-Axiom-Dataset': Bun.env.AXIOM_DATASET
+        }
+      })
+    )
+  ]
+}))
+```
+
+## OpenTelemetry SDK
+Use SDK normally - runs under Elysia's request span, auto-appears in trace.
+
+## Record Utility
+Equivalent to `startActiveSpan` - auto-closes + captures exceptions:
+```typescript
+import { record } from '@elysiajs/opentelemetry'
+
+.get('', () => {
+  return record('database.query', () => {
+    return db.query('SELECT * FROM users')
+  })
+})
+```
+
+Label for code shown in trace.
+
+## Function Naming
+Elysia reads function names as span names:
+```typescript
+// ⚠️ Anonymous span
+.derive(async ({ cookie: { session } }) => {
+  return { user: await getProfile(session) }
+})
+
+// ✅ Named span: "getProfile"
+.derive(async function getProfile({ cookie: { session } }) {
+  return { user: await getProfile(session) }
+})
+```
+
+## getCurrentSpan
+Get current span outside handler (via AsyncLocalStorage):
+```typescript
+import { getCurrentSpan } from '@elysiajs/opentelemetry'
+
+function utility() {
+  const span = getCurrentSpan()
+  span.setAttributes({ 'custom.attribute': 'value' })
+}
+```
+
+## setAttributes
+Sugar for `getCurrentSpan().setAttributes`:
+```typescript
+import { setAttributes } from '@elysiajs/opentelemetry'
+
+function utility() {
+  setAttributes({ 'custom.attribute': 'value' })
+}
+```
+
+## Instrumentations (Advanced)
+SDK must run before importing instrumented module.
+
+### Setup
+1. Separate file:
+```typescript
+// src/instrumentation.ts
+import { opentelemetry } from '@elysiajs/opentelemetry'
+import { PgInstrumentation } from '@opentelemetry/instrumentation-pg'
+
+export const instrumentation = opentelemetry({
+  instrumentations: [new PgInstrumentation()]
+})
+```
+
+2. Apply:
+```typescript
+// src/index.ts
+import { instrumentation } from './instrumentation'
+new Elysia().use(instrumentation).listen(3000)
+```
+
+3. Preload:
+```toml
+# bunfig.toml
+preload = ["./src/instrumentation.ts"]
+```
+
+### Production Deployment (Advanced)
+OpenTelemetry monkey-patches `node_modules`. Exclude instrumented libs from bundling:
+```bash
+bun build --compile --external pg --outfile server src/index.ts
+```
+
+Package.json:
+```json
+{
+  "dependencies": { "pg": "^8.15.6" },
+  "devDependencies": {
+    "@elysiajs/opentelemetry": "^1.2.0",
+    "@opentelemetry/instrumentation-pg": "^0.52.0"
+  }
+}
+```
+
+Production install:
+```bash
+bun install --production
+```
+
+Keeps `node_modules` with instrumented libs at runtime.

package/dist/skills/frameworks/elysia/elysiajs/plugins/server-timing.md

@@ -0,0 +1,71 @@
+# Server Timing Plugin
+This plugin adds support for auditing performance bottlenecks with Server Timing API
+
+## Installation
+```bash
+bun add @elysiajs/server-timing
+```
+
+## Basic Usage
+```typescript twoslash
+import { Elysia } from 'elysia'
+import { serverTiming } from '@elysiajs/server-timing'
+
+new Elysia()
+    .use(serverTiming())
+    .get('/', () => 'hello')
+    .listen(3000)
+```
+
+Server Timing then will append header 'Server-Timing' with log duration, function name, and detail for each life-cycle function.
+
+To inspect, open browser developer tools > Network > [Request made through Elysia server] > Timing.
+
+Now you can effortlessly audit the performance bottleneck of your server.
+
+## Config
+Below is a config which is accepted by the plugin
+
+### enabled
+@default `NODE_ENV !== 'production'`
+
+Determine whether or not Server Timing should be enabled
+
+### allow
+@default `undefined`
+
+A condition whether server timing should be log
+
+### trace
+@default `undefined`
+
+Allow Server Timing to log specified life-cycle events:
+
+Trace accepts objects of the following:
+- request: capture duration from request
+- parse: capture duration from parse
+- transform: capture duration from transform
+- beforeHandle: capture duration from beforeHandle
+- handle: capture duration from the handle
+- afterHandle: capture duration from afterHandle
+- total: capture total duration from start to finish
+
+## Pattern
+Below you can find the common patterns to use the plugin.
+
+## Allow Condition
+You may disable Server Timing on specific routes via `allow` property
+
+```ts twoslash
+import { Elysia } from 'elysia'
+import { serverTiming } from '@elysiajs/server-timing'
+
+new Elysia()
+    .use(
+        serverTiming({
+            allow: ({ request }) => {
+                return new URL(request.url).pathname !== '/no-trace'
+            }
+        })
+    )
+```

package/dist/skills/frameworks/elysia/elysiajs/plugins/static.md

@@ -0,0 +1,84 @@
+# Static Plugin
+This plugin can serve static files/folders for Elysia Server
+
+## Installation
+```bash
+bun add @elysiajs/static
+```
+
+## Basic Usage
+```typescript twoslash
+import { Elysia } from 'elysia'
+import { staticPlugin } from '@elysiajs/static'
+
+new Elysia()
+    .use(staticPlugin())
+    .listen(3000)
+```
+
+By default, the static plugin default folder is `public`, and registered with `/public` prefix.
+
+Suppose your project structure is:
+```
+| - src
+  | - index.ts
+| - public
+  | - takodachi.png
+  | - nested
+    | - takodachi.png
+```
+
+The available path will become:
+- /public/takodachi.png
+- /public/nested/takodachi.png
+
+## Config
+Below is a config which is accepted by the plugin
+
+### assets
+@default `"public"`
+
+Path to the folder to expose as static
+
+### prefix
+@default `"/public"`
+
+Path prefix to register public files
+
+### ignorePatterns
+@default `[]`
+
+List of files to ignore from serving as static files
+
+### staticLimit
+@default `1024`
+
+By default, the static plugin will register paths to the Router with a static name, if the limits are exceeded, paths will be lazily added to the Router to reduce memory usage.
+Tradeoff memory with performance.
+
+### alwaysStatic
+@default `false`
+
+If set to true, static files path will be registered to Router skipping the `staticLimits`.
+
+### headers
+@default `{}`
+
+Set response headers of files
+
+### indexHTML
+@default `false`
+
+If set to true, the `index.html` file from the static directory will be served for any request that is matching neither a route nor any existing static file.
+
+## Pattern
+Below you can find the common patterns to use the plugin.
+
+## Single file
+Suppose you want to return just a single file, you can use `file` instead of using the static plugin
+```typescript
+import { Elysia, file } from 'elysia'
+
+new Elysia()
+    .get('/file', file('public/takodachi.png'))
+```

package/dist/skills/frameworks/elysia/elysiajs/references/bun-fullstack-dev-server.md

@@ -0,0 +1,129 @@
+# Fullstack Dev Server
+
+## What It Is
+Bun 1.3 Fullstack Dev Server with HMR. React without bundler (no Vite/Webpack).
+
+Example: [elysia-fullstack-example](https://github.com/saltyaom/elysia-fullstack-example)
+
+## Setup
+1. Install + use Elysia Static:
+```typescript
+import { Elysia } from 'elysia'
+import { staticPlugin } from '@elysiajs/static'
+
+new Elysia()
+  .use(await staticPlugin())  // await required for HMR hooks
+  .listen(3000)
+```
+
+2. Create `public/index.html` + `public/index.tsx`:
+```html
+<!-- public/index.html -->
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <title>Elysia React App</title>
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./index.tsx"></script>
+  </body>
+</html>
+```
+
+```tsx
+// public/index.tsx
+import { useState } from 'react'
+import { createRoot } from 'react-dom/client'
+
+function App() {
+  const [count, setCount] = useState(0)
+  const increase = () => setCount((c) => c + 1)
+  
+  return (
+    <main>
+      <h2>{count}</h2>
+      <button onClick={increase}>Increase</button>
+    </main>
+  )
+}
+
+const root = createRoot(document.getElementById('root')!)
+root.render(<App />)
+```
+
+3. Enable JSX in `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  }
+}
+```
+
+4. Navigate to `http://localhost:3000/public`.
+
+Frontend + backend in single project. No bundler. Works with HMR, Tailwind, Tanstack Query, Eden Treaty, path alias.
+
+## Custom Prefix
+```typescript
+.use(await staticPlugin({ prefix: '/' }))
+```
+
+Serves at `/` instead of `/public`.
+
+## Tailwind CSS
+1. Install:
+```bash
+bun add tailwindcss@4
+bun add -d bun-plugin-tailwind
+```
+
+2. Create `bunfig.toml`:
+```toml
+[serve.static]
+plugins = ["bun-plugin-tailwind"]
+```
+
+3. Create `public/global.css`:
+```css
+@tailwind base;
+```
+
+4. Add to HTML or TS:
+```html
+<link rel="stylesheet" href="tailwindcss">
+```
+Or:
+```tsx
+import './global.css'
+```
+
+## Path Alias
+1. Add to `tsconfig.json`:
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@public/*": ["public/*"]
+    }
+  }
+}
+```
+
+2. Use:
+```tsx
+import '@public/global.css'
+```
+
+Works out of box.
+
+## Production Build
+```bash
+bun build --compile --target bun --outfile server src/index.ts
+```
+
+Creates single executable `server`. Include `public` folder when running.

package/dist/skills/frameworks/elysia/elysiajs/references/cookie.md

@@ -0,0 +1,187 @@
+# Cookie
+
+## What It Is
+Reactive mutable signal for cookie interaction. Auto-encodes/decodes objects.
+
+## Basic Usage
+No get/set - direct value access:
+```typescript
+import { Elysia } from 'elysia'
+
+new Elysia()
+  .get('/', ({ cookie: { name } }) => {
+    // Get
+    name.value
+    
+    // Set
+    name.value = "New Value"
+  })
+```
+
+Auto-encodes/decodes objects. Just works.
+
+## Reactivity
+Signal-like approach. Single source of truth. Auto-sets headers, syncs values.
+
+Cookie jar = Proxy object. Extract value always `Cookie<unknown>`, never `undefined`. Access via `.value`.
+
+Iterate over cookie jar → only existing cookies.
+
+## Cookie Attributes
+
+### Direct Property Assignment
+```typescript
+.get('/', ({ cookie: { name } }) => {
+  // Get
+  name.domain
+  
+  // Set
+  name.domain = 'millennium.sh'
+  name.httpOnly = true
+})
+```
+
+### set - Reset All Properties
+```typescript
+.get('/', ({ cookie: { name } }) => {
+  name.set({
+    domain: 'millennium.sh',
+    httpOnly: true
+  })
+})
+```
+
+Overwrites all properties.
+
+### add - Update Specific Properties
+Like `set` but only overwrites defined properties.
+
+## Remove Cookie
+```typescript
+.get('/', ({ cookie, cookie: { name } }) => {
+  name.remove()
+  // or
+  delete cookie.name
+})
+```
+
+## Cookie Schema
+Strict validation + type inference with `t.Cookie`:
+```typescript
+import { Elysia, t } from 'elysia'
+
+new Elysia()
+  .get('/', ({ cookie: { name } }) => {
+    name.value = {
+      id: 617,
+      name: 'Summoning 101'
+    }
+  }, {
+    cookie: t.Cookie({
+      name: t.Object({
+        id: t.Numeric(),
+        name: t.String()
+      })
+    })
+  })
+```
+
+### Nullable Cookie
+```typescript
+cookie: t.Cookie({
+  name: t.Optional(
+    t.Object({
+      id: t.Numeric(),
+      name: t.String()
+    })
+  )
+})
+```
+
+## Cookie Signature
+Cryptographic hash for verification. Prevents malicious modification.
+
+```typescript
+new Elysia()
+  .get('/', ({ cookie: { profile } }) => {
+    profile.value = { id: 617, name: 'Summoning 101' }
+  }, {
+    cookie: t.Cookie({
+      profile: t.Object({
+        id: t.Numeric(),
+        name: t.String()
+      })
+    }, {
+      secrets: 'Fischl von Luftschloss Narfidort',
+      sign: ['profile']
+    })
+  })
+```
+
+Auto-signs/unsigns.
+
+### Global Config
+```typescript
+new Elysia({
+  cookie: {
+    secrets: 'Fischl von Luftschloss Narfidort',
+    sign: ['profile']
+  }
+})
+```
+
+## Cookie Rotation
+Auto-handles secret rotation. Old signature verification + new signature signing.
+
+```typescript
+new Elysia({
+  cookie: {
+    secrets: ['Vengeance will be mine', 'Fischl von Luftschloss Narfidort']
+  }
+})
+```
+
+Array = key rotation (retire old, replace with new).
+
+## Config
+
+### secrets
+Secret key for signing/unsigning. Array = key rotation.
+
+### domain
+Domain Set-Cookie attribute. Default: none (current domain only).
+
+### encode
+Function to encode value. Default: `encodeURIComponent`.
+
+### expires
+Date for Expires attribute. Default: none (non-persistent, deleted on browser exit).
+
+If both `expires` and `maxAge` set, `maxAge` takes precedence (spec-compliant clients).
+
+### httpOnly (false)
+HttpOnly attribute. If true, JS can't access via `document.cookie`.
+
+### maxAge (undefined)
+Seconds for Max-Age attribute. Rounded down to integer.
+
+If both `expires` and `maxAge` set, `maxAge` takes precedence (spec-compliant clients).
+
+### path
+Path attribute. Default: handler path.
+
+### priority
+Priority attribute: `low` | `medium` | `high`. Not fully standardized.
+
+### sameSite
+SameSite attribute:
+- `true` = Strict
+- `false` = not set
+- `'lax'` = Lax
+- `'none'` = None (explicit cross-site)
+- `'strict'` = Strict
+
+Not fully standardized.
+
+### secure
+Secure attribute. If true, only HTTPS. Clients won't send over HTTP.