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

package/examples/09-router-lowering/README.md

@@ -0,0 +1,287 @@
+# Router lowering
+
+Uses the static `Router` authoring surface to define terminal middleware, route
+fallthrough, error handling, mounts, parameters, wildcards, and method-specific
+routes. Pulse lowers the flat Router execution graph into the same canonical
+native plan used by single-handler applications.
+
+## Workflow
+
+```bash
+pulse doctor
+pulse inspect
+pulse test
+pulse dev
+pulse compile
+pulse build
+```
+
+The inspect result exposes Router execution entries and route/middleware
+ownership for effects and continuations. `return next()` terminates the current
+handler and advances dispatch; it never resumes.
+
+<!-- pulse-doc-run {"project":"examples/09-router-lowering","args":["inspect","--json"]} -->
+```bash
+pulse inspect --json
+```
+```json
+{
+  "status": "ok",
+  "provider": {
+    "id": "node"
+  },
+  "compiler": {
+    "authoring": {
+      "kind": "router"
+    },
+    "routing": {
+      "version": "pulse.router-authoring.v2",
+      "routes": [
+        {
+          "method": "GET",
+          "path": "/api/health"
+        }
+      ]
+    },
+    "effectCount": 1,
+    "continuationCount": 1
+  }
+}
+```
+
+The documented test result below is also executed by the documentation gate.
+
+<!-- pulse-doc-run {"project":"examples/09-router-lowering","args":["test","--json"]} -->
+```bash
+pulse test --json
+```
+```json
+{
+  "status": "passed",
+  "provider": "node",
+  "summary": {
+    "total": 9,
+    "passed": 9,
+    "failed": 0
+  },
+  "cases": [
+    {
+      "name": "mounted-health",
+      "status": "passed",
+      "response": {
+        "status": 200
+      }
+    }
+  ]
+}
+```
+
+## Wasm size
+
+| Artifact | Default build | `--experimental-native-size` | Reduction |
+|---|---:|---:|---:|
+| `canonical-native.wasm` | 6.1 KiB (6,271 bytes) | 5.4 KiB (5,496 bytes) | 12.4% |
+
+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.
+
+## Router application
+
+<!-- pulse-doc-source: examples/09-router-lowering/src/index.ts -->
+```ts
+import { Router } from '@pulse-compute/runtime'
+
+interface User {
+  id: number
+  name: string
+}
+
+const users = new Router()
+const api = new Router()
+const app = new Router()
+
+app.use(async (ctx, next) => {
+  if (ctx.req.header('x-pulse-deny') === '1') {
+    return ctx.json(
+      { error: 'denied by middleware' },
+      { status: 401 },
+    )
+  }
+  return next()
+})
+
+api.use(async (ctx, next) => {
+  if (ctx.req.header('x-api-state') === 'closed') {
+    return ctx.text('api closed', { status: 503 })
+  }
+  return next()
+})
+
+users.get('/:id', async (ctx) => {
+  const id = ctx.param('id')
+  const user = await ctx
+    .fetch('https://users.example.test/users/' + id)
+    .json<User>()
+  return ctx.json({ route: 'user', id, user })
+})
+
+api.get('/health', async (ctx, next) => {
+  if (ctx.req.header('x-health-handler') === 'fallback') {
+    return next()
+  }
+  return ctx.json({ ok: true, handler: 'primary' })
+})
+api.get('/health', async (ctx) => ctx.json({ ok: true, handler: 'fallback' }))
+api.head('/health', async (ctx) => ctx.text('', {
+  status: 204,
+  headers: [['x-pulse-route', 'health']],
+}))
+api.post('/users', async (ctx) => ctx.json(
+  { route: 'create', method: ctx.req.method },
+  { status: 201 },
+))
+api.get('/files/*', async (ctx) => ctx.text(ctx.req.path))
+api.get('/failure', async (ctx, next) => next('documented-failure'))
+
+api.mount('/users', users)
+app.mount('/api', api)
+
+app.error(async (error, ctx, next) => {
+  if (error === 'documented-failure') {
+    return ctx.json({ error: 'handled' }, { status: 418 })
+  }
+  return next(error)
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/09-router-lowering/.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: {
+        'https://users.example.test/users/7': {
+          value: { id: 7, name: 'Ada' },
+        },
+      },
+    },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+
+## Test harness
+
+<!-- pulse-doc-source: examples/09-router-lowering/tests/pulse.harness.ts -->
+```ts
+export default {
+  cases: [
+    {
+      name: 'mounted-health',
+      request: { method: 'GET', path: '/api/health' },
+      expect: {
+        status: 200,
+        json: { ok: true, handler: 'primary' },
+      },
+    },
+    {
+      name: 'middleware-short-circuit',
+      request: {
+        method: 'GET',
+        path: '/api/health',
+        headers: { 'x-pulse-deny': '1' },
+      },
+      expect: {
+        status: 401,
+        json: { error: 'denied by middleware' },
+      },
+    },
+    {
+      name: 'scoped-middleware-short-circuit',
+      request: {
+        method: 'GET',
+        path: '/api/health',
+        headers: { 'x-api-state': 'closed' },
+      },
+      expect: { status: 503, text: 'api closed' },
+    },
+    {
+      name: 'route-fallthrough',
+      request: {
+        method: 'GET',
+        path: '/api/health',
+        headers: { 'x-health-handler': 'fallback' },
+      },
+      expect: {
+        status: 200,
+        json: { ok: true, handler: 'fallback' },
+      },
+    },
+    {
+      name: 'error-middleware',
+      request: { method: 'GET', path: '/api/failure' },
+      expect: { status: 418, json: { error: 'handled' } },
+    },
+    {
+      name: 'parameter-and-fetch',
+      request: { method: 'GET', path: '/api/users/7' },
+      fetches: {
+        'https://users.example.test/users/7': {
+          value: { id: 7, name: 'Ada' },
+        },
+      },
+      expect: {
+        status: 200,
+        json: {
+          route: 'user',
+          id: '7',
+          user: { id: 7, name: 'Ada' },
+        },
+      },
+    },
+    {
+      name: 'method-specific-post',
+      request: { method: 'POST', path: '/api/users' },
+      expect: {
+        status: 201,
+        json: { route: 'create', method: 'POST' },
+      },
+    },
+    {
+      name: 'trailing-wildcard',
+      request: {
+        method: 'GET',
+        path: '/api/files/guides/start',
+      },
+      expect: {
+        status: 200,
+        text: '/api/files/guides/start',
+      },
+    },
+    {
+      name: 'default-not-found',
+      request: { method: 'GET', path: '/missing' },
+      expect: { status: 404, text: 'Not Found' },
+    },
+  ],
+}
+```
+<!-- /pulse-doc-source -->

package/examples/09-router-lowering/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@pulse-examples/09-router-lowering",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "doctor": "pulse doctor",
+    "inspect": "pulse inspect",
+    "test": "pulse test",
+    "dev": "pulse dev",
+    "compile": "pulse compile",
+    "build": "pulse build"
+  },
+  "dependencies": {
+    "@pulse-compute/runtime": "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/09-router-lowering/src/index.ts

@@ -0,0 +1,65 @@
+import { Router } from '@pulse-compute/runtime'
+
+interface User {
+  id: number
+  name: string
+}
+
+const users = new Router()
+const api = new Router()
+const app = new Router()
+
+app.use(async (ctx, next) => {
+  if (ctx.req.header('x-pulse-deny') === '1') {
+    return ctx.json(
+      { error: 'denied by middleware' },
+      { status: 401 },
+    )
+  }
+  return next()
+})
+
+api.use(async (ctx, next) => {
+  if (ctx.req.header('x-api-state') === 'closed') {
+    return ctx.text('api closed', { status: 503 })
+  }
+  return next()
+})
+
+users.get('/:id', async (ctx) => {
+  const id = ctx.param('id')
+  const user = await ctx
+    .fetch('https://users.example.test/users/' + id)
+    .json<User>()
+  return ctx.json({ route: 'user', id, user })
+})
+
+api.get('/health', async (ctx, next) => {
+  if (ctx.req.header('x-health-handler') === 'fallback') {
+    return next()
+  }
+  return ctx.json({ ok: true, handler: 'primary' })
+})
+api.get('/health', async (ctx) => ctx.json({ ok: true, handler: 'fallback' }))
+api.head('/health', async (ctx) => ctx.text('', {
+  status: 204,
+  headers: [['x-pulse-route', 'health']],
+}))
+api.post('/users', async (ctx) => ctx.json(
+  { route: 'create', method: ctx.req.method },
+  { status: 201 },
+))
+api.get('/files/*', async (ctx) => ctx.text(ctx.req.path))
+api.get('/failure', async (ctx, next) => next('documented-failure'))
+
+api.mount('/users', users)
+app.mount('/api', api)
+
+app.error(async (error, ctx, next) => {
+  if (error === 'documented-failure') {
+    return ctx.json({ error: 'handled' }, { status: 418 })
+  }
+  return next(error)
+})
+
+export default app

package/examples/09-router-lowering/tests/pulse.harness.ts

@@ -0,0 +1,91 @@
+export default {
+  cases: [
+    {
+      name: 'mounted-health',
+      request: { method: 'GET', path: '/api/health' },
+      expect: {
+        status: 200,
+        json: { ok: true, handler: 'primary' },
+      },
+    },
+    {
+      name: 'middleware-short-circuit',
+      request: {
+        method: 'GET',
+        path: '/api/health',
+        headers: { 'x-pulse-deny': '1' },
+      },
+      expect: {
+        status: 401,
+        json: { error: 'denied by middleware' },
+      },
+    },
+    {
+      name: 'scoped-middleware-short-circuit',
+      request: {
+        method: 'GET',
+        path: '/api/health',
+        headers: { 'x-api-state': 'closed' },
+      },
+      expect: { status: 503, text: 'api closed' },
+    },
+    {
+      name: 'route-fallthrough',
+      request: {
+        method: 'GET',
+        path: '/api/health',
+        headers: { 'x-health-handler': 'fallback' },
+      },
+      expect: {
+        status: 200,
+        json: { ok: true, handler: 'fallback' },
+      },
+    },
+    {
+      name: 'error-middleware',
+      request: { method: 'GET', path: '/api/failure' },
+      expect: { status: 418, json: { error: 'handled' } },
+    },
+    {
+      name: 'parameter-and-fetch',
+      request: { method: 'GET', path: '/api/users/7' },
+      fetches: {
+        'https://users.example.test/users/7': {
+          value: { id: 7, name: 'Ada' },
+        },
+      },
+      expect: {
+        status: 200,
+        json: {
+          route: 'user',
+          id: '7',
+          user: { id: 7, name: 'Ada' },
+        },
+      },
+    },
+    {
+      name: 'method-specific-post',
+      request: { method: 'POST', path: '/api/users' },
+      expect: {
+        status: 201,
+        json: { route: 'create', method: 'POST' },
+      },
+    },
+    {
+      name: 'trailing-wildcard',
+      request: {
+        method: 'GET',
+        path: '/api/files/guides/start',
+      },
+      expect: {
+        status: 200,
+        text: '/api/files/guides/start',
+      },
+    },
+    {
+      name: 'default-not-found',
+      request: { method: 'GET', path: '/missing' },
+      expect: { status: 404, text: 'Not Found' },
+    },
+  ],
+}

package/examples/09-router-lowering/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/10-entities-tools/.pulse/.gitignore

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

package/examples/10-entities-tools/.pulse/config.ts

@@ -0,0 +1,23 @@
+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: 'node-javascript',
+    strict: true,
+  },
+  'node-javascript': {
+    host: 'node',
+    target: 'javascript',
+    outDir: 'dist-node-javascript',
+    dev: { networkFetch: false },
+  },
+  'node-native': {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist-node-native',
+    dev: { networkFetch: false },
+  },
+}))

package/examples/10-entities-tools/README.md

@@ -0,0 +1,165 @@
+# Entities tools facade
+
+This experimental example declares two schema-bound operations with
+`@pulse-compute/entities`, exposes them through the first-party JSON-RPC
+adapter, and projects their emitted static catalog into a dependency-free tools
+facade. The facade invokes the governed request boundary; it does not call
+application handlers directly.
+
+The application contributes:
+
+- `system.status`, which accepts no input and completes with `null`;
+- `customer.lookup`, which validates named input and output and performs one
+  governed `ctx.fetch` effect.
+
+## Candidate workflow
+
+```bash
+pulse inspect
+node ../../wasm/scripts/run-wasm-tests.cjs --task entities-orchestration-demo --no-report
+```
+
+`pulse inspect` reports the static entity catalog, declared schemas, handler
+effects, and target evidence. The focused orchestration gate builds and consumes
+the catalog, invokes both operations through the Node JavaScript request
+boundary, validates the governed fetch, and compiles/inspects the package-owned
+Native artifact.
+
+The ordinary JavaScript `test`/`dev` application loader currently requests the
+unexported physical package entry, and ordinary Native builds do not yet adopt
+the Entities intrinsic. I11 records those product-integration blockers instead
+of widening package exports or compiler/provider authority. A JavaScript build
+can still emit the source package, catalog, and inspection artifacts; no command
+may fall back to another target.
+
+## Wasm size
+
+The default `node-javascript` profile emits **no application Wasm artifact**.
+The ordinary `node-native` build currently fails closed at the unadopted
+Entities intrinsic. The focused gate's package-owned Native artifact exercises
+a different boundary and is not comparable to an emitted application guest.
+Consequently, `--experimental-native-size` has no application artifact to
+optimize for this example.
+
+## Entity application
+
+<!-- pulse-doc-source: examples/10-entities-tools/src/index.ts -->
+```ts
+import { EntityRouter, jsonRpc } from '@pulse-compute/entities'
+import { lookupCustomer, systemStatus } from './handlers.js'
+
+const rpc = new EntityRouter({
+  adapter: jsonRpc({ namedParamsOnly: true, acceptEmptyObjectForNoInput: true }),
+})
+
+rpc.on('system.status', {
+  input: null,
+  output: null,
+  metadata: {
+    title: 'Check system status',
+    description: 'Checks that the governed entity request boundary is available.',
+    mcp: { readOnlyHint: true },
+  },
+}, systemStatus)
+
+rpc.on('customer.lookup', {
+  input: 'tools.CustomerLookupInput',
+  output: 'tools.CustomerLookupOutput',
+  metadata: {
+    title: 'Look up customer',
+    description: 'Looks up one customer through the configured directory backend.',
+    mcp: { readOnlyHint: true },
+  },
+}, lookupCustomer)
+
+export default async function handler(ctx: unknown) {
+  return rpc.handle(ctx as never)
+}
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/10-entities-tools/.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: 'node-javascript',
+    strict: true,
+  },
+  'node-javascript': {
+    host: 'node',
+    target: 'javascript',
+    outDir: 'dist-node-javascript',
+    dev: { networkFetch: false },
+  },
+  'node-native': {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist-node-native',
+    dev: { networkFetch: false },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+## Test harness
+
+<!-- pulse-doc-source: examples/10-entities-tools/tests/pulse.harness.ts -->
+```ts
+export default { cases: [
+  {
+    name: 'system-status',
+    request: {
+      method: 'POST',
+      path: '/',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ jsonrpc: '2.0', method: 'system.status', id: 'status-doc' }),
+    },
+    expect: {
+      status: 200,
+      json: { jsonrpc: '2.0', result: null, id: 'status-doc' },
+    },
+  },
+  {
+    name: 'customer-lookup',
+    request: {
+      method: 'POST',
+      path: '/',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        method: 'customer.lookup',
+        params: { email: 'ada@example.test' },
+        id: 'lookup-doc',
+      }),
+    },
+    fetches: {
+      'https://directory.example.test/customers/ada@example.test': { value: 'Ada Lovelace' },
+    },
+    expect: {
+      status: 200,
+      json: {
+        jsonrpc: '2.0',
+        result: { email: 'ada@example.test', displayName: 'Ada Lovelace' },
+        id: 'lookup-doc',
+      },
+    },
+  },
+] }
+```
+<!-- /pulse-doc-source -->
+
+## Facade boundary
+
+`tools-facade.cjs` is an orchestration example, not a complete MCP server. It
+does not add listeners, SSE, sessions, tasks, resources, prompts, sampling,
+authorization, transport negotiation, or protocol lifecycle state to Pulse
+runtime core. A future MCP or tools facade remains an adapter outside the
+entity engine, just as a future Worker/event adapter would bind a different
+request or event protocol without changing entity handler semantics.

package/examples/10-entities-tools/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@pulse-examples/10-entities-tools",
+  "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/entities": "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"
+  }
+}