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

package/examples/12-mcp-proxy/README.md

@@ -0,0 +1,149 @@
+# MCP-shaped HTTP proxy
+
+Forwards one JSON-RPC-shaped HTTP request to an upstream endpoint and returns
+the upstream response without inspecting it. This is intentionally not a full
+MCP server: it has no SSE, sessions, discovery, tools catalog, authorization,
+or protocol lifecycle state.
+
+Pulse does not expose an opaque incoming-body handle. The request body crosses
+one bounded `ctx.req.text()` materialization seam before the outbound POST. The
+upstream response remains provider-owned and opaque.
+
+## 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/12-mcp-proxy","args":["test","--json"]} -->
+```bash
+pulse test --json
+```
+```json
+{
+  "status": "passed",
+  "provider": "node",
+  "summary": {
+    "total": 1,
+    "passed": 1,
+    "failed": 0
+  },
+  "cases": [
+    {
+      "name": "json-rpc-pass-through",
+      "status": "passed",
+      "response": {
+        "status": 200
+      }
+    }
+  ]
+}
+```
+
+## Wasm size
+
+| Artifact | Default build | `--experimental-native-size` | Reduction |
+|---|---:|---:|---:|
+| `canonical-native.wasm` | 2.5 KiB (2,589 bytes) | 2.4 KiB (2,418 bytes) | 6.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/12-mcp-proxy/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.post('/mcp', async (ctx) => {
+  const body = await ctx.req.text()
+  return ctx.fetch('https://mcp.example.test/rpc', {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+    },
+    body,
+  })
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/12-mcp-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: 'node',
+    target: 'native',
+    outDir: 'dist',
+    dev: {
+      fetches: {
+        'POST https://mcp.example.test/rpc': {
+          opaque: true,
+          status: 200,
+          headers: [['content-type', 'application/json']],
+          chunks: ['{"jsonrpc":"2.0","result":{},"id":1}'],
+        },
+      },
+    },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+## Test harness
+
+<!-- pulse-doc-source: examples/12-mcp-proxy/tests/pulse.harness.ts -->
+```ts
+export default {
+  cases: [
+    {
+      name: 'json-rpc-pass-through',
+      request: {
+        method: 'POST',
+        path: '/mcp',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          id: 1,
+        }),
+      },
+      fetches: {
+        'POST https://mcp.example.test/rpc': {
+          opaque: true,
+          status: 200,
+          headers: [['content-type', 'application/json']],
+          chunks: ['{"jsonrpc":"2.0","result":{},"id":1}'],
+        },
+      },
+      expect: {
+        status: 200,
+        bodyClass: 'opaque',
+      },
+    },
+  ],
+}
+```
+<!-- /pulse-doc-source -->

package/examples/12-mcp-proxy/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@pulse-examples/12-mcp-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"
+  },
+  "devDependencies": {
+    "@pulse-compute/cli": "1.0.0-beta.1",
+    "typescript": "5.9.3"
+  }
+}

package/examples/12-mcp-proxy/src/index.ts

@@ -0,0 +1,17 @@
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.post('/mcp', async (ctx) => {
+  const body = await ctx.req.text()
+  return ctx.fetch('https://mcp.example.test/rpc', {
+    method: 'POST',
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+    },
+    body,
+  })
+})
+
+export default app

package/examples/12-mcp-proxy/tests/pulse.harness.ts

@@ -0,0 +1,29 @@
+export default {
+  cases: [
+    {
+      name: 'json-rpc-pass-through',
+      request: {
+        method: 'POST',
+        path: '/mcp',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'tools/list',
+          id: 1,
+        }),
+      },
+      fetches: {
+        'POST https://mcp.example.test/rpc': {
+          opaque: true,
+          status: 200,
+          headers: [['content-type', 'application/json']],
+          chunks: ['{"jsonrpc":"2.0","result":{},"id":1}'],
+        },
+      },
+      expect: {
+        status: 200,
+        bodyClass: 'opaque',
+      },
+    },
+  ],
+}

package/examples/12-mcp-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/13-jwt-es256/.pulse/config.ts

@@ -0,0 +1,19 @@
+import { defineConfig } from '@pulse-compute/pulse'
+
+export default defineConfig((_scope) => ({
+  pulse: {
+    entry: 'src/index.ts',
+    tests: 'tests/pulse.harness.ts',
+    defaultProfile: 'node-native',
+    strict: true,
+  },
+  'node-native': {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist-node-native',
+    crypto: {
+      ES256: { realization: 'guest-linked:pulse-es256-rustcrypto-p256' },
+    },
+    dev: { host: '127.0.0.1', port: 8787, networkFetch: false },
+  },
+}))

package/examples/13-jwt-es256/README.md

@@ -0,0 +1,195 @@
+# ES256 bearer verification
+
+This Node example verifies one bearer JWT with an inline public P-256 JWK.
+The Native profile links the released RustCrypto verifier explicitly and does
+not probe for a fallback realization.
+
+The deterministic harness covers a valid token, a one-byte signature mutation,
+and a token whose declared algorithm is outside the allowlist. The fixture
+contains only a public verification key; no private signing material is part of
+the application or build output.
+
+## Workflow
+
+```bash
+pulse doctor
+pulse inspect
+pulse test
+pulse dev
+pulse build
+```
+
+The documented result below is executed against the exact linked Native
+artifact by the documentation gate.
+
+<!-- pulse-doc-run {"project":"examples/13-jwt-es256","args":["test","--json"],"timeoutMs":240000} -->
+```bash
+pulse test --json
+```
+```json
+{
+  "status": "passed",
+  "provider": "node",
+  "summary": {
+    "total": 3,
+    "passed": 3,
+    "failed": 0
+  },
+  "cases": [
+    {
+      "name": "valid ES256 bearer",
+      "status": "passed",
+      "response": {
+        "status": 200
+      }
+    },
+    {
+      "name": "wrong ES256 signature",
+      "status": "passed",
+      "expectedError": {
+        "code": "PULSE_JWT_SIGNATURE_INVALID"
+      }
+    },
+    {
+      "name": "disallowed algorithm",
+      "status": "passed",
+      "expectedError": {
+        "code": "PULSE_JWT_ALGORITHM_NOT_ALLOWED"
+      }
+    }
+  ]
+}
+```
+
+## Wasm size
+
+| Artifact | Default build | `--experimental-native-size` | Reduction |
+|---|---:|---:|---:|
+| Application input | 2.7 KiB (2,759 bytes) | 2.5 KiB (2,577 bytes) | 6.6% |
+| ES256 guest input | 20.5 KiB (21,009 bytes) | 20.5 KiB (21,009 bytes) | 0.0% |
+| Final linked `canonical-native.wasm` | 23.1 KiB (23,647 bytes) | 22.9 KiB (23,461 bytes) | 0.8% |
+
+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. The first two rows are the exact primary and guest inputs
+recorded by `guest-link-report.json`; the last row is the validated output of
+the deterministic static link. Linked output is not the arithmetic sum of its
+inputs because the linker composes and deduplicates the modules.
+
+## Application
+
+<!-- pulse-doc-source: examples/13-jwt-es256/src/index.ts -->
+```ts
+import { jwt } from '@pulse-compute/jwt'
+
+export default async function handler(ctx) {
+  const verified = await jwt.verify(ctx, jwt.bearer(ctx.req), {
+    algorithms: ['ES256'],
+    key: {
+      type: 'jwk',
+      key: {
+        kty: 'EC',
+        crv: 'P-256',
+        x: 'YP7UuiVanTHJYet0xjVtaMBJuJI7Yfps5mliLmDyn7Y',
+        y: 'eQP-EAi4vJmkGunpVii8ZPLxsgwtfp9Rd6PClNRGIpk',
+        alg: 'ES256',
+        use: 'sig',
+        key_ops: ['verify'],
+        kid: 'g3-key',
+      },
+    },
+  })
+  return ctx.text(verified.claims.sub + ':' + verified.protectedHeader.alg)
+}
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/13-jwt-es256/.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: 'node-native',
+    strict: true,
+  },
+  'node-native': {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist-node-native',
+    crypto: {
+      ES256: { realization: 'guest-linked:pulse-es256-rustcrypto-p256' },
+    },
+    dev: { host: '127.0.0.1', port: 8787, networkFetch: false },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+## Test harness
+
+<!-- pulse-doc-source: examples/13-jwt-es256/tests/pulse.harness.ts -->
+```ts
+const valid =
+  'eyJ0eXAiOiJKV1QiLCJraWQiOiJnMy1rZXkiLCJhbGciOiJFUzI1NiJ9.' +
+  'eyJzdWIiOiJnMy1zZW5zaXRpdmUtc3ViamVjdCIsImlhdCI6MTk5OTk5OTk5MCwi' +
+  'ZXhwIjoyMDAwMDAwMDYwLCJyb2xlcyI6WyJtZW1iZXIiXX0.' +
+  'LgxFHy8spsAvPR5FgmnHS1MnVWEr7rAOVtS-PMSrwnabWfD3tEmOam2km7ZCLiX2' +
+  'l2a_0ycVMIy6VMk95_ZOkQ'
+
+const wrongSignature =
+  'eyJ0eXAiOiJKV1QiLCJraWQiOiJnMy1rZXkiLCJhbGciOiJFUzI1NiJ9.' +
+  'eyJzdWIiOiJnMy1zZW5zaXRpdmUtc3ViamVjdCIsImlhdCI6MTk5OTk5OTk5MCwi' +
+  'ZXhwIjoyMDAwMDAwMDYwLCJyb2xlcyI6WyJtZW1iZXIiXX0.' +
+  'rgxFHy8spsAvPR5FgmnHS1MnVWEr7rAOVtS-PMSrwnabWfD3tEmOam2km7ZCLiX2' +
+  'l2a_0ycVMIy6VMk95_ZOkQ'
+
+const disallowedAlgorithm =
+  'eyJ0eXAiOiJKV1QiLCJraWQiOiJnMy1rZXkiLCJhbGciOiJIUzI1NiJ9.' +
+  'eyJzdWIiOiJnMy1zZW5zaXRpdmUtc3ViamVjdCIsImlhdCI6MTk5OTk5OTk5MCwi' +
+  'ZXhwIjoyMDAwMDAwMDYwLCJyb2xlcyI6WyJtZW1iZXIiXX0.' +
+  'LgxFHy8spsAvPR5FgmnHS1MnVWEr7rAOVtS-PMSrwnabWfD3tEmOam2km7ZCLiX2' +
+  'l2a_0ycVMIy6VMk95_ZOkQ'
+
+function authorization(token: string) {
+  return { authorization: `Bearer ${token}` }
+}
+
+export default { cases: [
+  {
+    name: 'valid ES256 bearer',
+    request: { method: 'GET', path: '/verify', headers: authorization(valid) },
+    expect: { status: 200, text: 'g3-sensitive-subject:ES256' },
+  },
+  {
+    name: 'wrong ES256 signature',
+    request: {
+      method: 'GET',
+      path: '/verify',
+      headers: authorization(wrongSignature),
+    },
+    expect: {
+      error: { name: 'JwtError', code: 'PULSE_JWT_SIGNATURE_INVALID' },
+    },
+  },
+  {
+    name: 'disallowed algorithm',
+    request: {
+      method: 'GET',
+      path: '/verify',
+      headers: authorization(disallowedAlgorithm),
+    },
+    expect: {
+      error: { name: 'JwtError', code: 'PULSE_JWT_ALGORITHM_NOT_ALLOWED' },
+    },
+  },
+] }
+```
+<!-- /pulse-doc-source -->
+
+See [JWT](../../docs/packages/jwt.md) for the full verification policy and
+supported key sources.

package/examples/13-jwt-es256/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pulse-examples/13-jwt-es256",
+  "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/jwt": "1.0.0-beta.1",
+    "@pulse-compute/pulse": "1.0.0-beta.1"
+  },
+  "devDependencies": {
+    "@pulse-compute/cli": "1.0.0-beta.1",
+    "typescript": "5.9.3"
+  }
+}

package/examples/13-jwt-es256/src/index.ts

@@ -0,0 +1,21 @@
+import { jwt } from '@pulse-compute/jwt'
+
+export default async function handler(ctx) {
+  const verified = await jwt.verify(ctx, jwt.bearer(ctx.req), {
+    algorithms: ['ES256'],
+    key: {
+      type: 'jwk',
+      key: {
+        kty: 'EC',
+        crv: 'P-256',
+        x: 'YP7UuiVanTHJYet0xjVtaMBJuJI7Yfps5mliLmDyn7Y',
+        y: 'eQP-EAi4vJmkGunpVii8ZPLxsgwtfp9Rd6PClNRGIpk',
+        alg: 'ES256',
+        use: 'sig',
+        key_ops: ['verify'],
+        kid: 'g3-key',
+      },
+    },
+  })
+  return ctx.text(verified.claims.sub + ':' + verified.protectedHeader.alg)
+}

package/examples/13-jwt-es256/tests/pulse.harness.ts

@@ -0,0 +1,54 @@
+const valid =
+  'eyJ0eXAiOiJKV1QiLCJraWQiOiJnMy1rZXkiLCJhbGciOiJFUzI1NiJ9.' +
+  'eyJzdWIiOiJnMy1zZW5zaXRpdmUtc3ViamVjdCIsImlhdCI6MTk5OTk5OTk5MCwi' +
+  'ZXhwIjoyMDAwMDAwMDYwLCJyb2xlcyI6WyJtZW1iZXIiXX0.' +
+  'LgxFHy8spsAvPR5FgmnHS1MnVWEr7rAOVtS-PMSrwnabWfD3tEmOam2km7ZCLiX2' +
+  'l2a_0ycVMIy6VMk95_ZOkQ'
+
+const wrongSignature =
+  'eyJ0eXAiOiJKV1QiLCJraWQiOiJnMy1rZXkiLCJhbGciOiJFUzI1NiJ9.' +
+  'eyJzdWIiOiJnMy1zZW5zaXRpdmUtc3ViamVjdCIsImlhdCI6MTk5OTk5OTk5MCwi' +
+  'ZXhwIjoyMDAwMDAwMDYwLCJyb2xlcyI6WyJtZW1iZXIiXX0.' +
+  'rgxFHy8spsAvPR5FgmnHS1MnVWEr7rAOVtS-PMSrwnabWfD3tEmOam2km7ZCLiX2' +
+  'l2a_0ycVMIy6VMk95_ZOkQ'
+
+const disallowedAlgorithm =
+  'eyJ0eXAiOiJKV1QiLCJraWQiOiJnMy1rZXkiLCJhbGciOiJIUzI1NiJ9.' +
+  'eyJzdWIiOiJnMy1zZW5zaXRpdmUtc3ViamVjdCIsImlhdCI6MTk5OTk5OTk5MCwi' +
+  'ZXhwIjoyMDAwMDAwMDYwLCJyb2xlcyI6WyJtZW1iZXIiXX0.' +
+  'LgxFHy8spsAvPR5FgmnHS1MnVWEr7rAOVtS-PMSrwnabWfD3tEmOam2km7ZCLiX2' +
+  'l2a_0ycVMIy6VMk95_ZOkQ'
+
+function authorization(token: string) {
+  return { authorization: `Bearer ${token}` }
+}
+
+export default { cases: [
+  {
+    name: 'valid ES256 bearer',
+    request: { method: 'GET', path: '/verify', headers: authorization(valid) },
+    expect: { status: 200, text: 'g3-sensitive-subject:ES256' },
+  },
+  {
+    name: 'wrong ES256 signature',
+    request: {
+      method: 'GET',
+      path: '/verify',
+      headers: authorization(wrongSignature),
+    },
+    expect: {
+      error: { name: 'JwtError', code: 'PULSE_JWT_SIGNATURE_INVALID' },
+    },
+  },
+  {
+    name: 'disallowed algorithm',
+    request: {
+      method: 'GET',
+      path: '/verify',
+      headers: authorization(disallowedAlgorithm),
+    },
+    expect: {
+      error: { name: 'JwtError', code: 'PULSE_JWT_ALGORITHM_NOT_ALLOWED' },
+    },
+  },
+] }

package/examples/13-jwt-es256/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/README.md

@@ -0,0 +1,36 @@
+# Pulse canonical examples
+
+These are complete canonical projects using the conventional
+`.pulse/config.ts` workspace, dedicated deterministic test harnesses,
+async-shaped managed handlers, and the same `pulse` commands as a user
+application. Examples 01, 02, 03, 05, 07, 11, and 12 use the project-level
+`@pulse-compute/pulse` application root. Example 09 retains
+`@pulse-compute/runtime` and `Router` as the explicit low-level authoring path.
+Example 10 uses `@pulse-compute/entities` with an external tools facade.
+
+For every example except 10, enter the example directory and run:
+
+```bash
+pulse doctor
+pulse inspect
+pulse test
+pulse dev
+pulse build
+```
+
+From this source checkout, the equivalent root command is:
+
+```bash
+pnpm pulse -- doctor examples/01-hello-json
+```
+
+See [`../docs/examples.md`](../docs/examples.md) for the capability index.
+
+Example 10 documents its focused entity workflow. Its gate executes
+catalog discovery, governed JavaScript calls, and Native artifact compilation
+without claiming that the ordinary project lifecycle integration is complete.
+Example 11 runs mixed HTTP and event cases on Node JavaScript or Node Native.
+Its development server remains HTTP-only; event input is available through the
+bounded test/reference adapter rather than a public listener.
+Example 12 is only an HTTP/JSON-RPC proxy shape: it does not claim MCP protocol
+ownership, discovery, SSE, or session behavior.

package/package.json

@@ -1,15 +1,75 @@
 {
   "name": "@pulse-compute/cli",
-  "version": "0.0.0",
-  "description": "Inert namespace bootstrap for Pulse.",
+  "version": "1.0.0-beta.1",
   "license": "Apache-2.0",
+  "description": "Pulse project CLI, configuration loader, and end-to-end workflow driver.",
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./workflow": "./src/workflow.js",
+    "./project-config": "./src/project-config.js",
+    "./project-execution": "./src/project-execution.js",
+    "./diagnostics": "./src/diagnostics.js",
+    "./project-config-schema": {
+      "types": "./src/project-config-schema.d.ts",
+      "require": "./src/project-config-schema.js",
+      "default": "./src/project-config-schema.js"
+    },
+    "./project-config.schema.json": "./project-config.schema.json",
+    "./cli-spec.json": "./cli-spec.json",
+    "./release-manifest.json": "./release-manifest.json",
+    "./documentation-versions.json": "./documentation-versions.json",
+    "./documentation-site.json": "./documentation-site.json"
+  },
+  "dependencies": {
+    "@pulse-compute/wasm-build-support": "1.0.0-beta.1",
+    "@pulse-compute/wasm-compiler": "1.0.0-beta.1",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.1",
+    "@pulse-compute/wasm-host-runtime": "1.0.0-beta.1",
+    "@pulse-compute/wasm-schema-json": "1.0.0-beta.1",
+    "typescript": "5.9.3"
+  },
+  "bin": {
+    "pulsewasm-extract": "./bin/pulsewasm-extract.js",
+    "pulsewasm": "./bin/pulsewasm-extract.js",
+    "pulse": "./bin/pulse.js"
+  },
+  "types": "./src/index.d.ts",
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
+    "bin",
+    "src",
     "README.md",
+    "docs",
+    "examples",
+    "API.md",
+    "completions",
+    "cli-spec.json",
+    "project-config.schema.json",
+    "release-manifest.json",
+    "documentation-versions.json",
+    "documentation-site.json",
+    "CHANGELOG.md",
     "LICENSE",
     "NOTICE"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "bootstrap"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulse-compute/pulse.git",
+    "directory": "wasm/packages/cli"
+  },
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.1/packages/cli/",
+  "bugs": {
+    "url": "https://github.com/pulse-compute/pulse/issues"
   }
-}
+}