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

package/examples/10-entities-tools/src/handlers.ts

@@ -0,0 +1,15 @@
+type CustomerLookupInput = Readonly<{
+  email: string
+}>
+
+export async function systemStatus(_ctx: unknown, _input: undefined) {
+  return undefined
+}
+
+export async function lookupCustomer(ctx: any, input: CustomerLookupInput) {
+  const displayName = await ctx.fetch(
+    `https://directory.example.test/customers/${input.email}`,
+  ).text()
+  return { email: input.email, displayName }
+}
+

package/examples/10-entities-tools/src/index.ts

@@ -0,0 +1,31 @@
+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)
+}
+

package/examples/10-entities-tools/src/schemas.ts

@@ -0,0 +1,18 @@
+import { defineSchemaRegistry, schema } from '@pulse-compute/pulse/schema'
+
+export interface CustomerLookupInput {
+  email: string
+}
+
+export interface CustomerLookupOutput {
+  email: string
+  displayName: string
+}
+
+export default defineSchemaRegistry({
+  schemas: {
+    'tools.CustomerLookupInput': schema<CustomerLookupInput>(),
+    'tools.CustomerLookupOutput': schema<CustomerLookupOutput>(),
+  },
+})
+

package/examples/10-entities-tools/tests/pulse.harness.ts

@@ -0,0 +1,40 @@
+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',
+      },
+    },
+  },
+] }

package/examples/10-entities-tools/tools-facade.cjs

@@ -0,0 +1,158 @@
+'use strict';
+
+const TOOLS_FACADE_VERSION = 'pulse.entities-tools-facade-demo.v1';
+const TOOLS_CATALOG_VERSION = 'pulse.entities-tools-catalog-demo.v1';
+
+const TOOLS_FACADE_POLICY = Object.freeze({
+  completeMcpServer: false,
+  discovery: 'static-entity-catalog',
+  invocation: 'json-rpc-2.0-request-boundary',
+  governedExecution: 'pulse-entity-handler',
+  excluded: Object.freeze([
+    'sse',
+    'sessions',
+    'tasks',
+    'resources',
+    'prompts',
+    'sampling',
+    'authorization',
+    'transport-negotiation',
+    'runtime-core-protocol-state'
+  ])
+});
+
+class ToolsFacadeInvocationError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'ToolsFacadeInvocationError';
+    this.code = code;
+  }
+}
+
+function staticMetadata(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : Object.freeze({});
+}
+
+function projectTool(entity) {
+  const metadata = staticMetadata(entity.metadata);
+  const hints = staticMetadata(metadata.mcp);
+  return Object.freeze({
+    name: entity.name,
+    title: typeof metadata.title === 'string' ? metadata.title : entity.name,
+    description: typeof metadata.description === 'string' ? metadata.description : '',
+    inputSchemaId: entity.inputSchema,
+    outputSchemaId: entity.outputSchema,
+    annotations: Object.freeze({ readOnlyHint: hints.readOnlyHint === true })
+  });
+}
+
+function readTools(catalog) {
+  if (!catalog || catalog.version !== 'pulse.entities-catalog.v1') {
+    throw new TypeError('Tools facade requires a pulse.entities-catalog.v1 artifact.');
+  }
+  if (!Array.isArray(catalog.routers) || catalog.routers.length !== 1) {
+    throw new TypeError('Tools facade demonstration requires exactly one static entity router.');
+  }
+  const router = catalog.routers[0];
+  if (!router || router.adapter !== 'json-rpc' || !Array.isArray(router.entities)) {
+    throw new TypeError('Tools facade demonstration requires one JSON-RPC entity router.');
+  }
+  const tools = router.entities.map(projectTool);
+  if (new Set(tools.map((tool) => tool.name)).size !== tools.length) {
+    throw new TypeError('Tools facade catalog contains duplicate tool names.');
+  }
+  return Object.freeze(tools);
+}
+
+function requestId(value) {
+  if (value === null || typeof value === 'string' || Number.isFinite(value)) return value;
+  throw new TypeError('Tools facade request ID must be a string, finite number, or null.');
+}
+
+function createToolsFacade({ catalog, invoke }) {
+  if (typeof invoke !== 'function') {
+    throw new TypeError(
+      'Tools facade requires an injected request-boundary invoker.'
+    );
+  }
+  const tools = readTools(catalog);
+  const toolsByName = new Map(tools.map((tool) => [tool.name, tool]));
+
+  return Object.freeze({
+    version: TOOLS_FACADE_VERSION,
+    policy: TOOLS_FACADE_POLICY,
+    listTools() {
+      return Object.freeze({ version: TOOLS_CATALOG_VERSION, tools });
+    },
+    async callTool(name, input, options = {}) {
+      const tool = toolsByName.get(name);
+      if (!tool) throw new RangeError(`Unknown catalog tool ${String(name)}.`);
+      if (
+        tool.inputSchemaId !== null
+        && (input === null || typeof input !== 'object' || Array.isArray(input))
+      ) {
+        throw new TypeError(`Tool ${name} requires a named object input.`);
+      }
+      if (tool.inputSchemaId === null && input !== undefined) {
+        throw new TypeError(`Tool ${name} does not accept input.`);
+      }
+      const envelope = {
+        jsonrpc: '2.0',
+        method: name,
+        ...(tool.inputSchemaId === null ? {} : { params: input }),
+        id: requestId(options.id === undefined ? `tools:${name}` : options.id)
+      };
+      const response = await invoke(Object.freeze({
+        method: 'POST',
+        headers: Object.freeze([Object.freeze(['content-type', 'application/json'])]),
+        body: JSON.stringify(envelope)
+      }));
+      const status = Number(response && response.status);
+      const body = response && typeof response.body === 'string' ? response.body : '';
+      if (status !== 200 || body.length === 0) {
+        throw new ToolsFacadeInvocationError(
+          'PULSE_TOOLS_BOUNDARY_RESPONSE_INVALID',
+          'Tool request boundary returned an invalid response.'
+        );
+      }
+      let payload;
+      try { payload = JSON.parse(body); }
+      catch (_) {
+        throw new ToolsFacadeInvocationError(
+          'PULSE_TOOLS_BOUNDARY_JSON_INVALID',
+          'Tool request boundary returned invalid JSON.'
+        );
+      }
+      if (
+        !payload
+        || payload.jsonrpc !== '2.0'
+        || JSON.stringify(payload.id) !== JSON.stringify(envelope.id)
+      ) {
+        throw new ToolsFacadeInvocationError(
+          'PULSE_TOOLS_BOUNDARY_ENVELOPE_INVALID',
+          'Tool request boundary returned an invalid JSON-RPC envelope.'
+        );
+      }
+      if (payload.error) {
+        throw new ToolsFacadeInvocationError(
+          'PULSE_TOOLS_CALL_FAILED',
+          typeof payload.error.message === 'string' ? payload.error.message : 'Tool call failed.'
+        );
+      }
+      if (!Object.prototype.hasOwnProperty.call(payload, 'result')) {
+        throw new ToolsFacadeInvocationError(
+          'PULSE_TOOLS_BOUNDARY_RESULT_MISSING',
+          'Tool request boundary omitted the result.'
+        );
+      }
+      return payload.result;
+    }
+  });
+}
+
+module.exports = Object.freeze({
+  TOOLS_FACADE_POLICY,
+  TOOLS_FACADE_VERSION,
+  ToolsFacadeInvocationError,
+  createToolsFacade
+});

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

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

package/examples/11-events/.pulse/.gitignore

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

package/examples/11-events/.pulse/config.ts

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

package/examples/11-events/README.md

@@ -0,0 +1,194 @@
+# Static events
+
+This mixed Node project keeps HTTP and event entries in separate planes. Two
+schema-bound `Pulse.on` registrations accept canonical event frames and use the
+one-way `ctx.emit` effect. The harness proves exact outbound acceptance; it
+does not claim delivery or invoke a matching local handler.
+
+## Workflow
+
+```bash
+pulse doctor
+pulse inspect
+pulse test
+pulse dev
+pulse build
+```
+
+`pulse test` executes both HTTP and event cases on the selected Node target.
+`pulse dev` serves only the HTTP portion; Pulse does not expose a public event
+listener or injection command.
+
+The documented result below is executed by the documentation gate.
+
+<!-- pulse-doc-run {"project":"examples/11-events","args":["test","--json"],"timeoutMs":240000} -->
+```bash
+pulse test --json
+```
+```json
+{
+  "status": "passed",
+  "provider": "node",
+  "summary": {
+    "total": 3,
+    "passed": 3,
+    "failed": 0
+  },
+  "cases": [
+    {
+      "name": "http health remains separate",
+      "status": "passed",
+      "response": {
+        "status": 200
+      }
+    },
+    {
+      "name": "schema event emits an accepted frame",
+      "status": "passed",
+      "kind": "event",
+      "emittedFrameCount": 1
+    }
+  ]
+}
+```
+
+## Wasm size
+
+| Artifact | Default build | `--experimental-native-size` | Reduction |
+|---|---:|---:|---:|
+| `canonical-native.wasm` | 38.4 KiB (39,358 bytes) | 30.6 KiB (31,313 bytes) | 20.4% |
+
+The executable documentation gate rebuilds and measures both variants on
+`1.0.0-beta.2`. These are uncompressed on-disk sizes, not transfer sizes or
+platform limits.
+
+## Application
+
+<!-- pulse-doc-source: examples/11-events/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+type DeviceReading = Readonly<{
+  deviceId: string
+  temperatureC: number
+}>
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => ctx.text('ok'))
+
+app.on<DeviceReading>('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const reading = ctx.event.payload
+  ctx.log.info('device reading accepted')
+  await ctx.emit('device.reading.accepted', {
+    schema: 'events.DeviceReadingAccepted',
+    payload: { deviceId: reading.deviceId, accepted: true },
+  })
+})
+
+app.on('system.tick', { schema: null }, async (ctx) => {
+  ctx.log.info('system tick accepted')
+  await ctx.emit('system.heartbeat', { schema: null })
+})
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+## Schemas
+
+<!-- pulse-doc-source: examples/11-events/src/schemas.ts -->
+```ts
+import { defineSchemaRegistry, schema } from '@pulse-compute/pulse/schema'
+
+export interface DeviceReading {
+  deviceId: string
+  temperatureC: number
+}
+
+export interface DeviceReadingAccepted {
+  deviceId: string
+  accepted: boolean
+}
+
+export default defineSchemaRegistry({
+  schemas: {
+    'events.DeviceReading': schema<DeviceReading>(),
+    'events.DeviceReadingAccepted': schema<DeviceReadingAccepted>(),
+  },
+})
+```
+<!-- /pulse-doc-source -->
+
+## Project config
+
+<!-- pulse-doc-source: examples/11-events/.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-native',
+    strict: true,
+  },
+  'node-native': {
+    host: 'node',
+    target: 'native',
+    outDir: 'dist-node-native',
+    dev: { host: '127.0.0.1', port: 8787, networkFetch: false },
+  },
+  'node-javascript': {
+    host: 'node',
+    target: 'javascript',
+    outDir: 'dist-node-javascript',
+    dev: { host: '127.0.0.1', port: 8787, networkFetch: false },
+  },
+}))
+```
+<!-- /pulse-doc-source -->
+
+## Test harness
+
+<!-- pulse-doc-source: examples/11-events/tests/pulse.harness.ts -->
+```ts
+export default { cases: [
+  {
+    name: 'http health remains separate',
+    request: { method: 'GET', path: '/health' },
+    expect: { status: 200, text: 'ok' },
+  },
+  {
+    name: 'schema event emits an accepted frame',
+    kind: 'event',
+    event: {
+      type: 'device.reading',
+      schema: 'events.DeviceReading',
+      payload: { deviceId: 'sensor-7', temperatureC: 21 },
+    },
+    expect: {
+      status: 'completed',
+      emitted: [{
+        type: 'device.reading.accepted',
+        schema: 'events.DeviceReadingAccepted',
+        payload: { deviceId: 'sensor-7', accepted: true },
+      }],
+    },
+  },
+  {
+    name: 'no-payload event emits a no-payload frame',
+    kind: 'event',
+    event: { type: 'system.tick', schema: null },
+    expect: {
+      status: 'completed',
+      emitted: [{ type: 'system.heartbeat', schema: null }],
+    },
+  },
+] }
+```
+<!-- /pulse-doc-source -->
+
+See [Static events and outbound emission](../../docs/guides/events.md) for the
+frame, queue, target, diagnostic, and Native-extension contracts.

package/examples/11-events/package.json

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

package/examples/11-events/src/index.ts

@@ -0,0 +1,27 @@
+import { Pulse } from '@pulse-compute/pulse'
+
+type DeviceReading = Readonly<{
+  deviceId: string
+  temperatureC: number
+}>
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => ctx.text('ok'))
+
+app.on<DeviceReading>('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const reading = ctx.event.payload
+  ctx.log.info('device reading accepted')
+  await ctx.emit('device.reading.accepted', {
+    schema: 'events.DeviceReadingAccepted',
+    payload: { deviceId: reading.deviceId, accepted: true },
+  })
+})
+
+app.on('system.tick', { schema: null }, async (ctx) => {
+  ctx.log.info('system tick accepted')
+  await ctx.emit('system.heartbeat', { schema: null })
+})
+
+export default app
+

package/examples/11-events/src/schemas.ts

@@ -0,0 +1,19 @@
+import { defineSchemaRegistry, schema } from '@pulse-compute/pulse/schema'
+
+export interface DeviceReading {
+  deviceId: string
+  temperatureC: number
+}
+
+export interface DeviceReadingAccepted {
+  deviceId: string
+  accepted: boolean
+}
+
+export default defineSchemaRegistry({
+  schemas: {
+    'events.DeviceReading': schema<DeviceReading>(),
+    'events.DeviceReadingAccepted': schema<DeviceReadingAccepted>(),
+  },
+})
+

package/examples/11-events/tests/pulse.harness.ts

@@ -0,0 +1,34 @@
+export default { cases: [
+  {
+    name: 'http health remains separate',
+    request: { method: 'GET', path: '/health' },
+    expect: { status: 200, text: 'ok' },
+  },
+  {
+    name: 'schema event emits an accepted frame',
+    kind: 'event',
+    event: {
+      type: 'device.reading',
+      schema: 'events.DeviceReading',
+      payload: { deviceId: 'sensor-7', temperatureC: 21 },
+    },
+    expect: {
+      status: 'completed',
+      emitted: [{
+        type: 'device.reading.accepted',
+        schema: 'events.DeviceReadingAccepted',
+        payload: { deviceId: 'sensor-7', accepted: true },
+      }],
+    },
+  },
+  {
+    name: 'no-payload event emits a no-payload frame',
+    kind: 'event',
+    event: { type: 'system.tick', schema: null },
+    expect: {
+      status: 'completed',
+      emitted: [{ type: 'system.heartbeat', schema: null }],
+    },
+  },
+] }
+

package/examples/11-events/tsconfig.json

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

package/examples/12-mcp-proxy/.pulse/.gitignore

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

package/examples/12-mcp-proxy/.pulse/config.ts

@@ -0,0 +1,25 @@
+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}'],
+        },
+      },
+    },
+  },
+}))