npm - @punks/cli - Versions diffs - 0.1.16 → 1.0.0 - Mend

@punks/cli 0.1.16 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (508) hide show

package/dist/skills/frameworks/elysia/elysiajs/plugins/html.md ADDED Viewed

@@ -0,0 +1,188 @@
+# HTML
+Allows you to use JSX and HTML with proper headers and support.
+## Installation
+```bash
+bun add @elysiajs/html
+```
+## Basic Usage
+```tsx twoslash
+import React from 'react'
+import { Elysia } from 'elysia'
+import { html, Html } from '@elysiajs/html'
+new Elysia()
+	.use(html())
+	.get(
+		'/html',
+		() => `
+            <html lang='en'>
+                <head>
+                    <title>Hello World</title>
+                </head>
+                <body>
+                    <h1>Hello World</h1>
+                </body>
+            </html>`
+	)
+	.get('/jsx', () => (
+		<html lang="en">
+			<head>
+				<title>Hello World</title>
+			</head>
+			<body>
+				<h1>Hello World</h1>
+			</body>
+		</html>
+	))
+	.listen(3000)
+```
+This plugin will automatically add `Content-Type: text/html; charset=utf8` header to the response, add `<!doctype html>`, and convert it into a Response object.
+## JSX
+Elysia can use JSX
+1. Replace your file that needs to use JSX to end with affix **"x"**:
+- .js -> .jsx
+- .ts -> .tsx
+2. Register the TypeScript type by append the following to **tsconfig.json**:
+```jsonc
+// tsconfig.json
+{
+	"compilerOptions": {
+		"jsx": "react",
+		"jsxFactory": "Html.createElement",
+		"jsxFragmentFactory": "Html.Fragment"
+	}
+}
+```
+3. Starts using JSX in your file
+```tsx twoslash
+import React from 'react'
+import { Elysia } from 'elysia'
+import { html, Html } from '@elysiajs/html'
+new Elysia()
+	.use(html())
+	.get('/', () => (
+		<html lang="en">
+			<head>
+				<title>Hello World</title>
+			</head>
+			<body>
+				<h1>Hello World</h1>
+			</body>
+		</html>
+	))
+	.listen(3000)
+```
+If the error `Cannot find name 'Html'. Did you mean 'html'?` occurs, this import must be added to the JSX template:
+```tsx
+import { Html } from '@elysiajs/html'
+```
+It is important that it is written in uppercase.
+## XSS
+Elysia HTML is based use of the Kita HTML plugin to detect possible XSS attacks in compile time.
+You can use a dedicated `safe` attribute to sanitize user value to prevent XSS vulnerability.
+```tsx
+import { Elysia, t } from 'elysia'
+import { html, Html } from '@elysiajs/html'
+new Elysia()
+	.use(html())
+	.post(
+		'/',
+		({ body }) => (
+			<html lang="en">
+				<head>
+					<title>Hello World</title>
+				</head>
+				<body>
+					<h1 safe>{body}</h1>
+				</body>
+			</html>
+		),
+		{
+			body: t.String()
+		}
+	)
+	.listen(3000)
+```
+However, when are building a large-scale app, it's best to have a type reminder to detect possible XSS vulnerabilities in your codebase.
+To add a type-safe reminder, please install:
+```sh
+bun add @kitajs/ts-html-plugin
+```
+Then appends the following **tsconfig.json**
+```jsonc
+// tsconfig.json
+{
+	"compilerOptions": {
+		"jsx": "react",
+		"jsxFactory": "Html.createElement",
+		"jsxFragmentFactory": "Html.Fragment",
+		"plugins": [{ "name": "@kitajs/ts-html-plugin" }]
+	}
+}
+```
+## Config
+Below is a config which is accepted by the plugin
+### contentType
+- Type: `string`
+- Default: `'text/html; charset=utf8'`
+The content-type of the response.
+### autoDetect
+- Type: `boolean`
+- Default: `true`
+Whether to automatically detect HTML content and set the content-type.
+### autoDoctype
+- Type: `boolean | 'full'`
+- Default: `true`
+Whether to automatically add `<!doctype html>` to a response starting with `<html>`, if not found.
+Use `full` to also automatically add doctypes on responses returned without this plugin
+```ts
+// without the plugin
+app.get('/', () => '<html></html>')
+// With the plugin
+app.get('/', ({ html }) => html('<html></html>'))
+```
+### isHtml
+- Type: `(value: string) => boolean`
+- Default: `isHtml` (exported function)
+The function is used to detect if a string is a html or not. Default implementation if length is greater than 7, starts with `<` and ends with `>`.
+Keep in mind there's no real way to validate HTML, so the default implementation is a best guess.

package/dist/skills/frameworks/elysia/elysiajs/plugins/jwt.md ADDED Viewed

@@ -0,0 +1,197 @@
+# JWT Plugin
+This plugin adds support for using JWT in Elysia handlers.
+## Installation
+```bash
+bun add @elysiajs/jwt
+```
+## Basic Usage
+```typescript [cookie]
+import { Elysia } from 'elysia'
+import { jwt } from '@elysiajs/jwt'
+const app = new Elysia()
+    .use(
+        jwt({
+            name: 'jwt',
+            secret: 'Fischl von Luftschloss Narfidort'
+        })
+    )
+    .get('/sign/:name', async ({ jwt, params: { name }, cookie: { auth } }) => {
+    	const value = await jwt.sign({ name })
+        auth.set({
+            value,
+            httpOnly: true,
+            maxAge: 7 * 86400,
+            path: '/profile',
+        })
+        return `Sign in as ${value}`
+    })
+    .get('/profile', async ({ jwt, status, cookie: { auth } }) => {
+        const profile = await jwt.verify(auth.value)
+        if (!profile)
+            return status(401, 'Unauthorized')
+        return `Hello ${profile.name}`
+    })
+    .listen(3000)
+```
+## Config
+This plugin extends config from [jose](https://github.com/panva/jose).
+Below is a config that is accepted by the plugin.
+### name
+Name to register `jwt` function as.
+For example, `jwt` function will be registered with a custom name.
+```typescript
+new Elysia()
+    .use(
+        jwt({
+            name: 'myJWTNamespace',
+            secret: process.env.JWT_SECRETS!
+        })
+    )
+    .get('/sign/:name', ({ myJWTNamespace, params }) => {
+        return myJWTNamespace.sign(params)
+    })
+```
+Because some might need to use multiple `jwt` with different configs in a single server, explicitly registering the JWT function with a different name is needed.
+### secret
+The private key to sign JWT payload with.
+### schema
+Type strict validation for JWT payload.
+### alg
+@default `HS256`
+Signing Algorithm to sign JWT payload with.
+Possible properties for jose are:
+HS256
+HS384
+HS512
+PS256
+PS384
+PS512
+RS256
+RS384
+RS512
+ES256
+ES256K
+ES384
+ES512
+EdDSA
+### iss
+The issuer claim identifies the principal that issued the JWT as per [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.1)
+TLDR; is usually (the domain) name of the signer.
+### sub
+The subject claim identifies the principal that is the subject of the JWT.
+The claims in a JWT are normally statements about the subject as per [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.2)
+### aud
+The audience claim identifies the recipients that the JWT is intended for.
+Each principal intended to process the JWT MUST identify itself with a value in the audience claim as per [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.3)
+### jti
+JWT ID claim provides a unique identifier for the JWT as per [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.7)
+### nbf
+The "not before" claim identifies the time before which the JWT must not be accepted for processing as per [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.5)
+### exp
+The expiration time claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing as per [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.4)
+### iat
+The "issued at" claim identifies the time at which the JWT was issued.
+This claim can be used to determine the age of the JWT as per [RFC7519](https://www.rfc-editor.org/rfc/rfc7519#section-4.1.6)
+### b64
+This JWS Extension Header Parameter modifies the JWS Payload representation and the JWS Signing input computation as per [RFC7797](https://www.rfc-editor.org/rfc/rfc7797).
+### kid
+A hint indicating which key was used to secure the JWS.
+This parameter allows originators to explicitly signal a change of key to recipients as per [RFC7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.4)
+### x5t
+(X.509 certificate SHA-1 thumbprint) header parameter is a base64url-encoded SHA-1 digest of the DER encoding of the X.509 certificate [RFC5280](https://www.rfc-editor.org/rfc/rfc5280) corresponding to the key used to digitally sign the JWS as per [RFC7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.7)
+### x5c
+(X.509 certificate chain) header parameter contains the X.509 public key certificate or certificate chain [RFC5280](https://www.rfc-editor.org/rfc/rfc5280) corresponding to the key used to digitally sign the JWS as per [RFC7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.6)
+### x5u
+(X.509 URL) header parameter is a URI [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) that refers to a resource for the X.509 public key certificate or certificate chain [RFC5280] corresponding to the key used to digitally sign the JWS as per [RFC7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.5)
+### jwk
+The "jku" (JWK Set URL) Header Parameter is a URI [RFC3986] that refers to a resource for a set of JSON-encoded public keys, one of which corresponds to the key used to digitally sign the JWS.
+The keys MUST be encoded as a JWK Set [JWK] as per [RFC7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.2)
+### typ
+The `typ` (type) Header Parameter is used by JWS applications to declare the media type [IANA.MediaTypes] of this complete JWS.
+This is intended for use by the application when more than one kind of object could be present in an application data structure that can contain a JWS as per [RFC7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.9)
+### ctr
+Content-Type parameter is used by JWS applications to declare the media type [IANA.MediaTypes] of the secured content (the payload).
+This is intended for use by the application when more than one kind of object could be present in the JWS Payload as per [RFC7515](https://www.rfc-editor.org/rfc/rfc7515#section-4.1.9)
+## Handler
+Below are the value added to the handler.
+### jwt.sign
+A dynamic object of collection related to use with JWT registered by the JWT plugin.
+Type:
+```typescript
+sign: (payload: JWTPayloadSpec): Promise<string>
+```
+`JWTPayloadSpec` accepts the same value as [JWT config](#config)
+### jwt.verify
+Verify payload with the provided JWT config
+Type:
+```typescript
+verify(payload: string) => Promise<JWTPayloadSpec | false>
+```
+`JWTPayloadSpec` accepts the same value as [JWT config](#config)
+## Pattern
+Below you can find the common patterns to use the plugin.
+## Set JWT expiration date
+By default, the config is passed to `setCookie` and inherits its value.
+```typescript
+const app = new Elysia()
+    .use(
+        jwt({
+            name: 'jwt',
+            secret: 'kunikuzushi',
+            exp: '7d'
+        })
+    )
+    .get('/sign/:name', async ({ jwt, params }) => jwt.sign(params))
+```
+This will sign JWT with an expiration date of the next 7 days.

package/dist/skills/frameworks/elysia/elysiajs/plugins/openapi.md ADDED Viewed

@@ -0,0 +1,246 @@
+# OpenAPI Plugin
+## Installation
+```bash
+bun add @elysiajs/openapi
+```
+## Basic Usage
+```typescript
+import { openapi } from '@elysiajs/openapi'
+new Elysia()
+  .use(openapi())
+  .get('/', () => 'hello')
+```
+Docs at `/openapi`, spec at `/openapi/json`.
+## Detail Object
+Extends OpenAPI Operation Object:
+```typescript
+.get('/', () => 'hello', {
+  detail: {
+    title: 'Hello',
+    description: 'An example route',
+    summary: 'Short summary',
+    deprecated: false,
+    hide: true,  // Hide from docs
+    tags: ['App']
+  }
+})
+```
+### Documentation Config
+```typescript
+openapi({
+  documentation: {
+    info: {
+      title: 'API',
+      version: '1.0.0'
+    },
+    tags: [
+      { name: 'App', description: 'General' }
+    ],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: 'http', scheme: 'bearer' }
+      }
+    }
+  }
+})
+```
+### Standard Schema Mapping
+```typescript
+mapJsonSchema: {
+  zod: z.toJSONSchema,  // Zod 4
+  valibot: toJsonSchema,
+  effect: JSONSchema.make
+}
+```
+Zod 3: `zodToJsonSchema` from `zod-to-json-schema`
+## OpenAPI Type Gen
+Generate docs from types:
+```typescript
+import { fromTypes } from '@elysiajs/openapi'
+export const app = new Elysia()
+  .use(openapi({
+    references: fromTypes()
+  }))
+```
+### Production
+Recommended to generate `.d.ts` file for production when using OpenAPI Type Gen
+```typescript
+references: fromTypes(
+  process.env.NODE_ENV === 'production'
+    ? 'dist/index.d.ts'
+    : 'src/index.ts'
+)
+```
+### Options
+```typescript
+fromTypes('src/index.ts', {
+  projectRoot: path.join('..', import.meta.dir),
+  tsconfigPath: 'tsconfig.dts.json'
+})
+```
+### Caveat: Explicit Types
+Use `Prettify` helper to inline when type is not showing:
+```typescript
+type Prettify<T> = { [K in keyof T]: T[K] } & {}
+function getUser(): Prettify<User> { }
+```
+## Schema Description
+```typescript
+body: t.Object({
+  username: t.String(),
+  password: t.String({
+    minLength: 8,
+    description: 'Password (8+ chars)'
+  })
+}, {
+  description: 'Expected username and password'
+}),
+detail: {
+  summary: 'Sign in user',
+  tags: ['auth']
+}
+```
+## Response Headers
+```typescript
+import { withHeader } from '@elysiajs/openapi'
+response: withHeader(
+  t.Literal('Hi'),
+  { 'x-powered-by': t.Literal('Elysia') }
+)
+```
+Annotation only - doesn't enforce. Set headers manually.
+## Tags
+Define + assign:
+```typescript
+.use(openapi({
+  documentation: {
+    tags: [
+      { name: 'App', description: 'General' },
+      { name: 'Auth', description: 'Auth' }
+    ]
+  }
+}))
+.get('/', () => 'hello', {
+  detail: { tags: ['App'] }
+})
+```
+### Instance Tags
+```typescript
+new Elysia({ tags: ['user'] })
+  .get('/user', 'user')
+```
+## Reference Models
+Auto-generates schemas:
+```typescript
+.model({
+  User: t.Object({
+    id: t.Number(),
+    username: t.String()
+  })
+})
+.get('/user', () => ({ id: 1, username: 'x' }), {
+  response: { 200: 'User' },
+  detail: { tags: ['User'] }
+})
+```
+## Guard
+Apply to instance/group:
+```typescript
+.guard({
+  detail: {
+    description: 'Requires auth'
+  }
+})
+.get('/user', 'user')
+```
+## Security
+```typescript
+.use(openapi({
+  documentation: {
+    components: {
+      securitySchemes: {
+        bearerAuth: {
+          type: 'http',
+          scheme: 'bearer',
+          bearerFormat: 'JWT'
+        }
+      }
+    }
+  }
+}))
+new Elysia({
+  prefix: '/address',
+  detail: {
+    security: [{ bearerAuth: [] }]
+  }
+})
+```
+Secures all routes under prefix.
+## Config
+Below is a config which is accepted by the `openapi({})`
+### enabled
+@default true
+Enable/Disable the plugin
+### documentation
+OpenAPI documentation information
+@see https://spec.openapis.org/oas/v3.0.3.html
+### exclude
+Configuration to exclude paths or methods from documentation
+### exclude.methods
+List of methods to exclude from documentation
+### exclude.paths
+List of paths to exclude from documentation
+### exclude.staticFile
+@default true
+Exclude static file routes from documentation
+### exclude.tags
+List of tags to exclude from documentation
+### mapJsonSchema
+A custom mapping function from Standard schema to OpenAPI schema
+### path
+@default '/openapi'
+The endpoint to expose OpenAPI documentation frontend
+### provider
+@default 'scalar'
+OpenAPI documentation frontend between:
+- Scalar
+- SwaggerUI
+- null: disable frontend