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

package/examples/05-fastly-capabilities/src/index.ts

@@ -0,0 +1,55 @@
+import { grip } from '@pulse-compute/grip'
+import { Pulse } from '@pulse-compute/pulse'
+
+interface User {
+  id: number
+  name: string
+}
+
+interface Session {
+  userId: number
+}
+
+const app = new Pulse({ auto: true })
+
+// Config, secret, and a named Fastly backend.
+app.get('/users/7', async (ctx) => {
+  const base = await ctx.config.get('API_BASE')
+  const token = await ctx.secret.get('API_TOKEN')
+  const user = await ctx
+    .fetch('https://api.example.com/users/7', {
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: 'application/json',
+        'x-api-base': base,
+      },
+    })
+    .json<User>()
+  return ctx.json({ user })
+})
+
+// Named Fastly KV storage.
+app.get('/session', async (ctx) => {
+  const current = await ctx.kv<Session>('sessions').get('session:123')
+  if (current === undefined) {
+    return ctx.json({ error: 'not_found' }, { status: 404 })
+  }
+  await ctx.kv<Session>('sessions').put('session:last', current)
+  return ctx.json({ session: current })
+})
+
+// Request-bound GRIP broadcast through the supported package root.
+app.post('/publish', async (ctx) => {
+  const acknowledgement = await grip.broadcast(ctx, {
+    channel: 'events:demo',
+    event: 'pulse.message',
+    id: 'message-1',
+    data: { message: 'hello from Pulse' },
+  })
+  return ctx.json(
+    { accepted: acknowledgement.accepted },
+    { status: 202 },
+  )
+})
+
+export default app

package/examples/05-fastly-capabilities/tests/pulse.harness.ts

@@ -0,0 +1,66 @@
+const config = { API_BASE: 'https://api.example.com' }
+const secrets = {
+  API_TOKEN: 'test-example-secret',
+  GRIP_TOKEN: 'test-grip-secret',
+}
+const grip = {
+  publishEndpoint: 'https://publisher.example.com/publish',
+  authentication: {
+    scheme: 'bearer',
+    secretRef: 'GRIP_TOKEN',
+  },
+}
+
+export default {
+  cases: [
+    {
+      name: 'configured-fetch',
+      request: { path: '/users/7' },
+      config,
+      secrets,
+      fetches: {
+        'https://api.example.com/users/7': {
+          value: { id: 7, name: 'Ada' },
+        },
+      },
+      expect: {
+        status: 200,
+        json: { user: { id: 7, name: 'Ada' } },
+      },
+    },
+    {
+      name: 'session-hit',
+      request: { path: '/session' },
+      kv: { sessions: { 'session:123': { userId: 123 } } },
+      expect: {
+        status: 200,
+        json: { session: { userId: 123 } },
+      },
+    },
+    {
+      name: 'session-miss',
+      request: { path: '/session' },
+      kv: { sessions: {} },
+      expect: {
+        status: 404,
+        json: { error: 'not_found' },
+      },
+    },
+    {
+      name: 'grip-broadcast',
+      request: { method: 'POST', path: '/publish' },
+      secrets,
+      grip,
+      fetches: {
+        'POST https://publisher.example.com/publish': {
+          status: 202,
+          value: { accepted: true, messageId: 'message-1' },
+        },
+      },
+      expect: {
+        status: 202,
+        json: { accepted: true },
+      },
+    },
+  ],
+}

package/examples/05-fastly-capabilities/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/07-opaque-proxy/.pulse/.gitignore

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

package/examples/07-opaque-proxy/.pulse/config.ts

@@ -0,0 +1,38 @@
+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: 'fastly',
+    target: 'native',
+    outDir: 'dist',
+    dev: {
+      fetches: {
+        'https://assets.example.com/archive.bin': {
+          opaque: true,
+          status: 206,
+          headers: [
+            ['content-type', 'application/octet-stream'],
+            ['x-part', 'one'],
+            ['x-part', 'two'],
+          ],
+          chunks: ['opaque-example'],
+        },
+      },
+    },
+    fastly: {
+      bindings: {
+        backends: {
+          'https://assets.example.com': 'assets_backend',
+        },
+        dynamicBackends: false,
+      },
+      build: { name: 'pulse-opaque-proxy-example' },
+    },
+  },
+}))

package/examples/07-opaque-proxy/README.md

@@ -0,0 +1,150 @@
+# Opaque binary proxy
+
+Returns an origin response directly. The binary or streaming body stays
+host-owned and is never decoded or copied into user scope.
+
+## 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/07-opaque-proxy","args":["test","--json"]} -->
+```bash
+pulse test --json
+```
+```json
+{
+  "status": "passed",
+  "provider": "fastly",
+  "summary": {
+    "total": 1,
+    "passed": 1,
+    "failed": 0
+  },
+  "cases": [
+    {
+      "name": "pass-through",
+      "status": "passed",
+      "response": {
+        "status": 206
+      }
+    }
+  ]
+}
+```
+
+Fastly builds produce a verified `.pulse-docs-build/bin/main.wasm`. Configured
+tests execute through the local-conformance runtime; compiled-target execution
+remains in the explicit reality profile.
+
+## Wasm size
+
+| Artifact | Default build | `--experimental-native-size` | Reduction |
+|---|---:|---:|---:|
+| `canonical-native.wasm` | 2.1 KiB (2,200 bytes) | 2.1 KiB (2,101 bytes) | 4.5% |
+| `bin/main.wasm` | 28.9 KiB (29,602 bytes) | 25.3 KiB (25,953 bytes) | 12.3% |
+
+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/07-opaque-proxy/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/archive', async (ctx) => {
+  return ctx.fetch('https://assets.example.com/archive.bin')
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/07-opaque-proxy/.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: 'fastly',
+    target: 'native',
+    outDir: 'dist',
+    dev: {
+      fetches: {
+        'https://assets.example.com/archive.bin': {
+          opaque: true,
+          status: 206,
+          headers: [
+            ['content-type', 'application/octet-stream'],
+            ['x-part', 'one'],
+            ['x-part', 'two'],
+          ],
+          chunks: ['opaque-example'],
+        },
+      },
+    },
+    fastly: {
+      bindings: {
+        backends: {
+          'https://assets.example.com': 'assets_backend',
+        },
+        dynamicBackends: false,
+      },
+      build: { name: 'pulse-opaque-proxy-example' },
+    },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+
+## Test harness
+
+<!-- pulse-doc-source: examples/07-opaque-proxy/tests/pulse.harness.ts -->
+```ts
+export default {
+  cases: [
+    {
+      name: 'pass-through',
+      request: { path: '/archive' },
+      fetches: {
+        'https://assets.example.com/archive.bin': {
+          opaque: true,
+          status: 206,
+          headers: [
+            ['content-type', 'application/octet-stream'],
+            ['x-part', 'one'],
+            ['x-part', 'two'],
+          ],
+          chunks: ['opaque-example'],
+        },
+      },
+      expect: {
+        status: 206,
+        bodyClass: 'opaque',
+        headers: { 'x-part': ['one', 'two'] },
+      },
+    },
+  ],
+}
+```
+<!-- /pulse-doc-source -->

package/examples/07-opaque-proxy/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pulse-examples/07-opaque-proxy",
+  "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",
+    "@pulse-compute/provider-fastly": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@pulse-compute/cli": "1.0.0-beta.1",
+    "typescript": "5.9.3"
+  }
+}

package/examples/07-opaque-proxy/src/index.ts

@@ -0,0 +1,9 @@
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/archive', async (ctx) => {
+  return ctx.fetch('https://assets.example.com/archive.bin')
+})
+
+export default app

package/examples/07-opaque-proxy/tests/pulse.harness.ts

@@ -0,0 +1,25 @@
+export default {
+  cases: [
+    {
+      name: 'pass-through',
+      request: { path: '/archive' },
+      fetches: {
+        'https://assets.example.com/archive.bin': {
+          opaque: true,
+          status: 206,
+          headers: [
+            ['content-type', 'application/octet-stream'],
+            ['x-part', 'one'],
+            ['x-part', 'two'],
+          ],
+          chunks: ['opaque-example'],
+        },
+      },
+      expect: {
+        status: 206,
+        bodyClass: 'opaque',
+        headers: { 'x-part': ['one', 'two'] },
+      },
+    },
+  ],
+}

package/examples/07-opaque-proxy/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/09-router-lowering/.pulse/.gitignore

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

package/examples/09-router-lowering/.pulse/config.ts

@@ -0,0 +1,22 @@
+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/7': {
+          value: { id: 7, name: 'Ada' },
+        },
+      },
+    },
+  },
+}))