@pulse-compute/cli 0.0.0 → 1.0.0-beta.1

package/examples/01-hello-json/README.md

@@ -0,0 +1,119 @@
+# Hello JSON
+
+The smallest canonical Pulse project: branch on the request path and return JSON or text.
+
+## Workflow
+
+```bash
+pulse doctor
+pulse inspect
+pulse test
+pulse dev
+pulse build
+```
+
+The documented test result below is executed by the documentation gate.
+
+<!-- pulse-doc-run {"project":"examples/01-hello-json","args":["test","--json"]} -->
+```bash
+pulse test --json
+```
+```json
+{
+  "status": "passed",
+  "provider": "node",
+  "summary": {
+    "total": 3,
+    "passed": 3,
+    "failed": 0
+  },
+  "cases": [
+    {
+      "name": "health",
+      "status": "passed",
+      "response": {
+        "status": 200
+      }
+    }
+  ]
+}
+```
+
+## Wasm size
+
+| Artifact | Default build | `--experimental-native-size` | Reduction |
+|---|---:|---:|---:|
+| `canonical-native.wasm` | 2.2 KiB (2,212 bytes) | 2.0 KiB (2,058 bytes) | 7.0% |
+
+The executable documentation gate rebuilds and measures both variants on
+`1.0.0-beta.1`. These are uncompressed on-disk sizes, not transfer sizes or
+platform limits.
+
+## Handler
+
+<!-- pulse-doc-source: examples/01-hello-json/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => ctx.json({ ok: true }))
+app.get('/hello', async (ctx) => ctx.json({ message: 'hello from Pulse' }))
+app.get('/*', async (ctx) => ctx.text('not found', { status: 404 }))
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/01-hello-json/.pulse/config.ts -->
+```ts
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((_scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'local',
+    strict: true,
+  },
+  local: {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist',
+    dev: { host: '127.0.0.1', port: 8787 },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+
+## Test harness
+
+<!-- pulse-doc-source: examples/01-hello-json/tests/pulse.harness.ts -->
+```ts
+export default {
+  cases: [
+    {
+      name: 'health',
+      request: { path: '/health' },
+      expect: { status: 200, json: { ok: true } },
+    },
+    {
+      name: 'hello',
+      request: { path: '/hello' },
+      expect: {
+        status: 200,
+        json: { message: 'hello from Pulse' },
+      },
+    },
+    {
+      name: 'missing',
+      request: { path: '/missing' },
+      expect: { status: 404, text: 'not found' },
+    },
+  ],
+}
+```
+<!-- /pulse-doc-source -->

package/examples/01-hello-json/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pulse-examples/01-hello-json",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "doctor": "pulse doctor",
+    "inspect": "pulse inspect",
+    "test": "pulse test",
+    "dev": "pulse dev",
+    "build": "pulse build"
+  },
+  "dependencies": {
+    "@pulse-compute/pulse": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@pulse-compute/cli": "1.0.0-beta.1",
+    "typescript": "5.9.3"
+  }
+}

package/examples/01-hello-json/src/index.ts

@@ -0,0 +1,9 @@
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => ctx.json({ ok: true }))
+app.get('/hello', async (ctx) => ctx.json({ message: 'hello from Pulse' }))
+app.get('/*', async (ctx) => ctx.text('not found', { status: 404 }))
+
+export default app

package/examples/01-hello-json/tests/pulse.harness.ts

@@ -0,0 +1,22 @@
+export default {
+  cases: [
+    {
+      name: 'health',
+      request: { path: '/health' },
+      expect: { status: 200, json: { ok: true } },
+    },
+    {
+      name: 'hello',
+      request: { path: '/hello' },
+      expect: {
+        status: 200,
+        json: { message: 'hello from Pulse' },
+      },
+    },
+    {
+      name: 'missing',
+      request: { path: '/missing' },
+      expect: { status: 404, text: 'not found' },
+    },
+  ],
+}

package/examples/01-hello-json/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true
+  },
+  "include": [
+    "src/**/*.ts",
+    ".pulse/**/*.ts",
+    "tests/**/*.ts"
+  ]
+}

package/examples/02-request-schema/.pulse/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!config.ts

package/examples/02-request-schema/.pulse/config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((_scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    schema: 'src/schemas.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'local',
+    strict: true,
+  },
+  local: {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist',
+    schemas: { contentTypePolicy: 'require-json', maxBytes: 1024 },
+  },
+}))

package/examples/02-request-schema/README.md

@@ -0,0 +1,145 @@
+# Request schema
+
+Compiles explicit TypeScript request and response schemas with the project. The
+same codecs are used by `test`, `dev`, Node builds, and Fastly builds.
+
+## Workflow
+
+```bash
+pulse doctor
+pulse inspect
+pulse test
+pulse dev
+pulse build
+```
+
+The documented test result below is executed by the documentation gate.
+
+<!-- pulse-doc-run {"project":"examples/02-request-schema","args":["test","--json"]} -->
+```bash
+pulse test --json
+```
+```json
+{
+  "status": "passed",
+  "provider": "node",
+  "summary": {
+    "total": 2,
+    "passed": 2,
+    "failed": 0
+  },
+  "cases": [
+    {
+      "name": "create-user",
+      "status": "passed",
+      "response": {
+        "status": 201
+      }
+    }
+  ]
+}
+```
+
+## Wasm size
+
+| Artifact | Default build | `--experimental-native-size` | Reduction |
+|---|---:|---:|---:|
+| `canonical-native.wasm` | 38.9 KiB (39,795 bytes) | 30.8 KiB (31,578 bytes) | 20.6% |
+
+The executable documentation gate rebuilds and measures both variants on
+`1.0.0-beta.1`. These are uncompressed on-disk sizes, not transfer sizes or
+platform limits.
+
+## Handler
+
+<!-- pulse-doc-source: examples/02-request-schema/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+import type { CreateUserInput, CreateUserOutput } from './schemas.js'
+
+const app = new Pulse({ auto: true })
+
+app.post('/users', async (ctx) => {
+  const first = await ctx.req.json<CreateUserInput>('app.CreateUserInput')
+  const second = await ctx.req.json<CreateUserInput>('app.CreateUserInput')
+  const output: CreateUserOutput = {
+    id: 7,
+    name: first.name,
+    active: first.active,
+    sameReference: first === second,
+  }
+  return ctx.json(output, { status: 201, schema: 'app.CreateUserOutput' })
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/02-request-schema/.pulse/config.ts -->
+```ts
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((_scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    schema: 'src/schemas.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'local',
+    strict: true,
+  },
+  local: {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist',
+    schemas: { contentTypePolicy: 'require-json', maxBytes: 1024 },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+
+## Test harness
+
+<!-- pulse-doc-source: examples/02-request-schema/tests/pulse.harness.ts -->
+```ts
+export default {
+  cases: [
+    {
+      name: 'create-user',
+      request: {
+        method: 'POST',
+        path: '/users',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: 'Ada', active: true }),
+      },
+      expect: {
+        status: 201,
+        json: {
+          id: 7,
+          name: 'Ada',
+          active: true,
+          sameReference: true,
+        },
+      },
+    },
+    {
+      name: 'invalid-user',
+      request: {
+        method: 'POST',
+        path: '/users',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: 12, active: true }),
+      },
+      expect: {
+        error: {
+          name: 'SchemaDecodeError',
+          code: 'PULSE_SCHEMA_DECODE',
+        },
+      },
+    },
+  ],
+}
+```
+<!-- /pulse-doc-source -->

package/examples/02-request-schema/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pulse-examples/02-request-schema",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "doctor": "pulse doctor",
+    "inspect": "pulse inspect",
+    "test": "pulse test",
+    "dev": "pulse dev",
+    "build": "pulse build"
+  },
+  "dependencies": {
+    "@pulse-compute/pulse": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@pulse-compute/cli": "1.0.0-beta.1",
+    "typescript": "5.9.3"
+  }
+}

package/examples/02-request-schema/src/index.ts

@@ -0,0 +1,18 @@
+import { Pulse } from '@pulse-compute/pulse'
+import type { CreateUserInput, CreateUserOutput } from './schemas.js'
+
+const app = new Pulse({ auto: true })
+
+app.post('/users', async (ctx) => {
+  const first = await ctx.req.json<CreateUserInput>('app.CreateUserInput')
+  const second = await ctx.req.json<CreateUserInput>('app.CreateUserInput')
+  const output: CreateUserOutput = {
+    id: 7,
+    name: first.name,
+    active: first.active,
+    sameReference: first === second,
+  }
+  return ctx.json(output, { status: 201, schema: 'app.CreateUserOutput' })
+})
+
+export default app

package/examples/02-request-schema/src/schemas.ts

@@ -0,0 +1,20 @@
+import { defineSchemaRegistry, schema } from '@pulse-compute/pulse/schema'
+
+export interface CreateUserInput {
+  name: string
+  active: boolean
+}
+
+export interface CreateUserOutput {
+  id: number
+  name: string
+  active: boolean
+  sameReference: boolean
+}
+
+export default defineSchemaRegistry({
+  schemas: {
+    'app.CreateUserInput': schema<CreateUserInput>(),
+    'app.CreateUserOutput': schema<CreateUserOutput>(),
+  },
+})

package/examples/02-request-schema/tests/pulse.harness.ts

@@ -0,0 +1,37 @@
+export default {
+  cases: [
+    {
+      name: 'create-user',
+      request: {
+        method: 'POST',
+        path: '/users',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: 'Ada', active: true }),
+      },
+      expect: {
+        status: 201,
+        json: {
+          id: 7,
+          name: 'Ada',
+          active: true,
+          sameReference: true,
+        },
+      },
+    },
+    {
+      name: 'invalid-user',
+      request: {
+        method: 'POST',
+        path: '/users',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ name: 12, active: true }),
+      },
+      expect: {
+        error: {
+          name: 'SchemaDecodeError',
+          code: 'PULSE_SCHEMA_DECODE',
+        },
+      },
+    },
+  ],
+}

package/examples/02-request-schema/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true
+  },
+  "include": [
+    "src/**/*.ts",
+    ".pulse/**/*.ts",
+    "tests/**/*.ts"
+  ]
+}

package/examples/03-fetch-composition/.pulse/.gitignore

@@ -0,0 +1,3 @@
+*
+!.gitignore
+!config.ts

package/examples/03-fetch-composition/.pulse/config.ts

@@ -0,0 +1,31 @@
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((_scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'local',
+    strict: true,
+  },
+  local: {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist',
+    dev: {
+      fetches: {
+        'https://users.example.test/users/123': {
+          value: { id: 123, name: 'Ada' },
+          delayMs: 15,
+        },
+        'https://stats.example.test/users/123': {
+          value: { score: 42 },
+          delayMs: 5,
+        },
+        'https://flags.example.test/users/123': {
+          value: { enabled: true },
+          delayMs: 1,
+        },
+      },
+    },
+  },
+}))