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

package/docs/guides/grip.md

@@ -0,0 +1,94 @@
+# GRIP and Fanout
+
+Pulse treats GRIP as stateless HTTP framing around an external connection owner. Fanout, Pushpin, or another GRIP gateway maintains connections and fan-out state. Pulse handles ordinary requests and responses.
+
+The JavaScript target permits ordinary runtime values:
+
+```ts
+import { Router } from '@pulse-compute/runtime'
+import { grip } from '@pulse-compute/grip'
+
+const app = new Router()
+
+app.get('/events/:topic', async (ctx) => {
+  const channel = `topic:${ctx.param('topic')}`
+
+  if (grip.isWebSocket(ctx.req)) {
+    return grip.handoff({ channel })
+  }
+
+  return grip.subscribe(
+    new Response(null, { status: 200 }),
+    { channel, mode: 'stream', timeoutMs: 30_000 },
+  )
+})
+
+app.post('/events/:topic', async (ctx) => {
+  const data = await ctx.req.json()
+  await grip.broadcast(ctx, {
+    channel: `topic:${ctx.param('topic')}`,
+    event: 'pulse.message',
+    data,
+  })
+  return ctx.json({ accepted: true }, { status: 202 })
+})
+
+export default app
+```
+
+`isWebSocket`, `subscribe`, and `handoff` are pure request/response helpers. `broadcast` is the only provider effect, so it participates in normal request cancellation, secret redaction, direct `await`, and keyed `ctx.parallel({ ... })` behavior.
+
+The Native target recognizes the same root with supported static framing options
+and broadcast messages:
+
+```ts
+import { grip } from '@pulse-compute/grip'
+
+export async function handler(ctx) {
+  if (grip.isWebSocket(ctx.req)) {
+    return grip.handoff({ channel: 'topic:news', body: 'handoff' })
+  }
+
+  await grip.broadcast(ctx, {
+    channel: 'topic:news',
+    event: 'pulse.message',
+    data: { available: true },
+  })
+
+  return grip.subscribe(new Response(null, { status: 202 }), {
+    channels: ['topic:news', 'topic:audit'],
+    mode: 'stream',
+    timeoutMs: 30_000,
+  })
+}
+```
+
+Dynamic Native channel, option, or message shapes fail at the unsupported
+expression. Pulse does not retry another lowering or switch targets.
+
+Provider broadcast configuration is distinct from the public gateway URL and
+the application's ingress route. It supplies an explicit publish/control
+endpoint and, on Fastly, its named backend:
+
+```ts
+fastly({
+  backends: {
+    'https://publisher.example': 'grip_publisher',
+  },
+  grip: {
+    publishEndpoint: 'https://publisher.example/publish',
+    publishBackend: 'grip_publisher',
+    authentication: {
+      scheme: 'bearer',
+      secretRef: 'GRIP_PUBLISH_TOKEN',
+    },
+  },
+})
+```
+
+Only the secret reference enters project configuration; the provider resolves
+the value inside the shared redaction boundary. There is no ambient endpoint,
+credential, connection state, or automatic fallback. Cross-target conformance
+covers framing, cancellation, bounds, acknowledgements, redaction, and
+deterministic Node/Fastly provider artifacts. GRIP is included in the generally
+available Node JavaScript target in the Beta.

package/docs/guides/json-schemas.md

@@ -0,0 +1,233 @@
+# Explicit JSON schemas
+
+Schemas are static project declarations, not runtime reflection. The compiler does not execute the registry module. Pulse extracts the default export,
+compiles deterministic JavaScript and Native codecs, and binds literal schema
+IDs at every structured JSON boundary.
+
+## Declare the registry
+
+<!-- pulse-doc-source: examples/02-request-schema/src/schemas.ts -->
+```ts
+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>(),
+  },
+})
+```
+<!-- /pulse-doc-source -->
+
+The string keys are the contract. TypeScript type names help authoring, but they
+are not discovered automatically and do not become runtime schema IDs.
+
+The schema subset is intentionally portable:
+
+- an object root with required property signatures;
+- `string`, `boolean`, and finite JSON `number`;
+- `Int32` and `Uint32` marker types imported with `import type`;
+- nested object types and arrays;
+- string-literal enums such as `'admin' | 'member'`;
+- one supported type unioned with `null`.
+
+Optional fields, `undefined`, recursive or generic types, interface inheritance,
+arbitrary unions, computed registry keys, runtime registry code, and public
+`json-as` decorators or imports are not supported. Relative type-only imports
+and re-exports can organize the type graph inside the project.
+
+## Add semantic response cases
+
+A response case gives one stable ID both a status and an already registered
+schema:
+
+```ts
+import {
+  defineSchemaRegistry,
+  response,
+  schema,
+} from '@pulse-compute/pulse/schema'
+import type { ApiError, CreateUserInput, User } from './models.js'
+
+export default defineSchemaRegistry({
+  schemas: {
+    'app.CreateUserInput': schema<CreateUserInput>(),
+    'app.User': schema<User>(),
+    'app.ApiError': schema<ApiError>(),
+  },
+  responses: {
+    'user.created': response(201, 'app.User'),
+    'user.failure': response(400, 'app.ApiError'),
+  },
+})
+```
+
+The response status and schema ID must be static literals. A response case
+cannot refer to an undeclared schema.
+
+## Point project configuration at the registry
+
+<!-- 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 -->
+
+`pulse.schema` owns the registry module. Do not also declare schema identity
+under a provider profile. Provider profiles own decode policy through
+`schemas.contentTypePolicy` and `schemas.maxBytes`:
+
+- `schemas.contentTypePolicy: 'accept-json-or-missing'` accepts JSON content
+  types and absent content types; it is the default;
+- `schemas.contentTypePolicy: 'require-json'` requires a JSON content type for
+  request and fetched-body schema decode;
+- `schemas.maxBytes` bounds structured schema decode and defaults to `65_536`
+  bytes;
+- `dev.maxBodyBytes` separately bounds incoming requests in the local
+  development server and also defaults to `65_536` bytes.
+
+Raise either byte limit deliberately. They are memory and request-amplification
+boundaries, not convenience settings.
+
+## Bind every JSON boundary
+
+<!-- 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 -->
+
+The four schema-boundary forms are:
+
+| Boundary | Authoring form | Operation |
+|---|---|---|
+| Incoming request | `await ctx.req.json<T>('app.Input')` | Decode |
+| Fetched response | `await ctx.fetch(url).json<T>('app.Output')` | Decode |
+| Outbound fetch body | `ctx.fetch(url, { json: value, schema: 'app.Input' })` | Encode |
+| Application response | `ctx.json(value, { schema: 'app.Output' })` | Encode |
+
+A registered response case is shorthand for response status plus schema:
+
+```ts
+return ctx.json(user, 'user.created')
+```
+
+IDs must be string literals. An outbound `schema` property is valid only with
+the semantic `json` property; a raw string `body` and `json` are mutually
+exclusive.
+
+## Understand strict mode
+
+`pulse.strict` defaults to `true`. When the project declares schemas, strict
+mode requires a schema ID for request JSON, fetched-response JSON, outbound
+fetch JSON, and application JSON responses. A response may use either a literal
+`schema` descriptor or a registered response-case ID.
+
+Setting `pulse.strict: false` allows schema-less generic JSON at reachable
+request and fetch-response reads and at JSON encode boundaries. It does not
+make an unknown ID valid: supplying an ID always requests that exact compiled
+codec. Pulse does not try schemas in sequence, infer a codec from the value, or
+fall back to generic JSON when an ID is missing from the registry.
+
+Generic JSON remains bounded and appears as an explicit host-generic JSON
+capability in Native inspection. It is a deliberate compatibility choice, not
+automatic JavaScript fallback.
+
+## Know the value semantics
+
+Schema decoding and encoding are semantic boundaries, not thin calls to a
+provider JSON object:
+
+- input values are validated, normalized, deeply immutable, and owned by the
+  request after decode;
+- repeated request reads of the same schema reuse the request-local decoded
+  value;
+- unknown input fields are removed recursively;
+- every declared field is required;
+- response and fetch encoding emits declared fields only, in declaration order;
+- numeric values must be finite JSON numbers;
+- JavaScript and Native use the same registry contract and semantic trace.
+
+The provider never exposes an SDK request or response object to the handler.
+Opaque bodies are not eligible for schema decode; see
+[Structured and opaque bodies](../concepts/bodies.md).
+
+## Inspect and diagnose the contract
+
+The CLI compiles the registry and direct codecs with the handler. `doctor`,
+`inspect`, `test`, `dev`, and `build` consume the same project output.
+
+```bash
+pulse inspect examples/02-request-schema --json
+```
+
+Check `schemas.authority`, `schemas.ids`, `schemas.responseCases`, and
+`schemas.codecRealization`, then review the compiler’s schema references and
+provider requirements. The packaged Native build carries the generated schema
+registry and codecs; it does not execute TypeScript or a JavaScript schema
+library at request time.
+
+Dynamic IDs, missing declarations, duplicate IDs, unsupported field shapes,
+invalid values, content-type violations, and oversized bodies fail explicitly.
+Common diagnostics include:
+
+- [`PULSE_SCHEMA_DECODE`](../reference/diagnostics.md#pulse-schema-decode);
+- [`PULSE_SCHEMA_ENCODE`](../reference/diagnostics.md#pulse-schema-encode);
+- [`PULSE_RESPONSE_ENCODE`](../reference/diagnostics.md#pulse-response-encode);
+- [`PULSE_BODY_TOO_LARGE`](../reference/diagnostics.md#pulse-body-too-large);
+- `PULSE_SCHEMA_REQUIRED`;
+- `PULSE_CANONICAL_SCHEMA_MISSING`;
+- `PULSE_RESPONSE_CASE_MISSING`.
+
+## Related documentation
+
+- [Structured and opaque bodies](../concepts/bodies.md)
+- [Project configuration](../reference/project-config.md)
+- [Managed handler TypeScript and JavaScript](../reference/handler-authoring.md)
+- [Provider and target compatibility](../reference/compatibility-matrix.md)
+- [Canonical API](../../API.md)

package/docs/guides/migrating-from-express.md

@@ -0,0 +1,192 @@
+# Migrate an Express service
+
+Pulse uses a familiar application, route, middleware, and error-handler shape,
+but it is not an Express-compatible runtime or a drop-in replacement. Express
+owns a live JavaScript server and mutable request/response objects. Pulse owns a
+static application description whose managed handlers compile to the selected
+JavaScript or Native target.
+
+Start from the similarity, then make each boundary explicit.
+
+## Map the mental model
+
+| Express concept | Pulse equivalent | Important difference |
+|---|---|---|
+| `express()` | `new Pulse({ auto: true })` | The default export is compiled; it is not a live dispatcher. |
+| `req.method`, `req.url`, `req.path` | `ctx.req.method`, `ctx.req.url`, `ctx.req.path` | Request metadata is read-only. |
+| `req.get('name')` | `ctx.req.header('name')` | Headers are normalized by the Pulse request contract. |
+| `req.params.id` | `ctx.param('id')` | Parameters exist only inside a matching static route. |
+| `res.locals` | `ctx.state.get()` / `ctx.state.set()` | State is request-local string storage, not an arbitrary object. |
+| `res.status(201).json(value)` | `return ctx.json(value, { status: 201 })` | Response builders return the terminal result; they do not mutate `res`. |
+| `res.status(204).end()` | `return ctx.response({ status: 204 })` | Every reachable handler branch returns a Pulse result or transfers control. |
+| `next()` | `return next()` | The transfer is terminal; the current handler never resumes. |
+| `next(error)` | `return next(error)` | Error transfer is explicit; authored `throw` is not Router control flow. |
+| Four-argument error middleware | `app.error(async (error, ctx, next) => …)` | Pulse error handlers use the canonical context and terminal transfer. |
+| Body-parser middleware | `await ctx.req.text()` or `await ctx.req.json('schema.id')` | Reads are explicit, bounded, and optionally schema-bound. |
+| `app.listen()` | `pulse dev` / `pulse build` plus a provider | The CLI and selected provider own execution and deployment lifecycle. |
+
+## Translate one route
+
+This Express example is illustrative; Express is not a Pulse dependency:
+
+```ts
+import express from 'express'
+
+const app = express()
+app.use(express.json())
+app.post('/users/:id', async (req, res, next) => {
+  try {
+    const user = await saveUser(req.params.id, req.body)
+    res.status(201).json(user)
+  } catch (error) {
+    next(error)
+  }
+})
+app.listen(3000)
+```
+
+The Pulse shape moves host work onto `ctx`, makes body decoding explicit, and
+returns the response:
+
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+import type { CreateUserInput, User } from './schemas.js'
+
+const app = new Pulse({ auto: true })
+
+app.post('/users/:id', async (ctx, next) => {
+  const id = ctx.param('id')
+  if (!id) return next('missing-user-id')
+
+  const input = await ctx.req.json<CreateUserInput>('app.CreateUserInput')
+  const user = await ctx.fetch('https://users.example.test/users/' + id, {
+    method: 'POST',
+    json: input,
+    schema: 'app.CreateUserInput',
+  }).json<User>('app.User')
+
+  return ctx.json(user, 'user.created')
+})
+
+app.error(async (error, ctx, next) => {
+  if (error === 'missing-user-id') {
+    return ctx.json({
+      code: 'missing-user-id',
+      message: 'The route did not produce a user ID.',
+    }, {
+      status: 400,
+      schema: 'app.ApiError',
+    })
+  }
+  return next(error)
+})
+
+export default app
+```
+
+The snippet assumes the named schemas and `user.created` response case are
+declared in the project schema registry. See
+[Explicit JSON schemas](./json-schemas.md).
+
+## Rewrite middleware as terminal control flow
+
+Express middleware can perform work after `await next()` in frameworks with an
+onion model, or depend on the eventual mutable response. Pulse middleware is a
+flat, compiler-owned cursor:
+
+```ts
+app.use('/api', async (ctx, next) => {
+  const token = ctx.req.header('authorization')
+  if (!token) return ctx.json({ error: 'unauthorized' }, { status: 401 })
+
+  ctx.state.set('principal', token)
+  return next()
+})
+```
+
+`return next()` permanently finishes this middleware. Do not assign its result,
+await it, or place cleanup and response mutation after it. Request state remains
+visible to later middleware, routes, error recovery, and resumed Pulse effects,
+but it is isolated between requests.
+
+Use `return next(error)` for a deliberate error-lane transfer. An unhandled
+normal lane ends as `404 Not Found`; an unhandled error lane ends as
+`500 Internal Server Error`.
+
+## Reduce routing to the static topology
+
+The Beta Router supports:
+
+- `use`, `get`, `head`, `post`, `put`, `patch`, `delete`, `mount`, and `error`;
+- exact paths, named `:parameters`, and a trailing `*` wildcard;
+- statically declared, acyclic mounted routers;
+- first-match order and explicit route fallthrough.
+
+It does not support `options`, `trace`, `connect`, regular-expression routes,
+runtime route registration, Express Router plugins, or hidden server lifecycle
+hooks. Keep an unsupported endpoint on its existing service or redesign it
+before moving that endpoint into Pulse; selecting a JavaScript target does not
+widen the Pulse Router API.
+
+## Replace ambient server capabilities
+
+Express code often reaches capabilities through Node globals, process state,
+SDK clients, or objects attached by middleware. Managed Pulse handlers use
+request-owned operations instead:
+
+| Existing dependency | Pulse boundary |
+|---|---|
+| Ambient `fetch` or HTTP client | `ctx.fetch()` |
+| `process.env` | `ctx.config.get()` or `ctx.secret.get()` |
+| Request-scoped SDK/client attachment | Explicit `ctx` effect or a supported package-root operation |
+| Logging package bound to the process | `ctx.log` |
+| Body-parser buffer or stream | Bounded `ctx.req.text()` / `ctx.req.json()` |
+| Streaming proxy response | Direct opaque response pass-through |
+
+Provider SDK objects, sockets, filesystem access, timers, background work, and
+userland body streams are outside the managed handler contract.
+
+## Decide what code can move unchanged
+
+Pure TypeScript or JavaScript expressions can move unchanged when they stay
+within the [managed handler language](../reference/handler-authoring.md).
+Imported project helpers also have to use compiler-supported static call shapes
+to remain Native-eligible. An ordinary library may work on an explicitly
+selected JavaScript target when that provider runtime supports the package.
+
+Express middleware packages cannot be mounted directly: they expect Express
+`req`, `res`, `next`, server lifecycle, or ambient Node behavior. Rewrite the
+needed policy against `ctx`, and verify its source form in the
+[compatibility matrix](../reference/compatibility-matrix.md). A JavaScript-only
+library or arbitrary library `await` makes the project ineligible for Native;
+Pulse never changes targets or falls back automatically.
+
+## Migrate in bounded slices
+
+1. Inventory routes, methods, middleware order, error paths, body parsing, and
+   ambient host dependencies.
+2. Move one supported `GET`, `HEAD`, `POST`, `PUT`, `PATCH`, or `DELETE` route to a statically declared
+   `Pulse` application.
+3. Replace response mutation with returned `ctx.json`, `ctx.text`, or
+   `ctx.response` results.
+4. Replace body-parser assumptions with bounded text or schema-bound JSON reads.
+5. Rewrite middleware around terminal `return next()` and explicit
+   `return next(error)`.
+6. Move network, config, secret, KV, logging, and supported package work onto
+   explicit `ctx` operations.
+7. Run `pulse doctor`, `pulse test`, and `pulse inspect` for the configured
+   provider/target before `pulse build`.
+
+Choose the target deliberately. JavaScript is useful for compatible ordinary
+packages; Native requires the bounded TypeScript/JavaScript subset. Neither
+lane is an Express runtime.
+
+## Continue with
+
+- [Static Router authoring](./routing.md)
+- [Explicit JSON schemas](./json-schemas.md)
+- [Structured and opaque bodies](../concepts/bodies.md)
+- [Managed handler TypeScript and JavaScript](../reference/handler-authoring.md)
+- [Provider and target compatibility](../reference/compatibility-matrix.md)
+- [Project lifecycle](./project-lifecycle.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/guides/project-lifecycle.md

@@ -0,0 +1,143 @@
+# Project lifecycle
+
+The normal Pulse application loop is:
+
+```text
+pulse init
+  → pulse doctor
+  → pulse test
+  → pulse dev
+  → pulse build
+```
+
+Each command resolves the same project root, `.pulse/config.ts`, selected
+profile, handler graph, schemas, provider bindings, target, and output
+directory. Provider and target selection come from configuration; no command
+silently changes them.
+
+## 1. Initialize
+
+```bash
+pulse init ./my-app
+cd ./my-app
+npm install
+```
+
+`pulse init` writes a conventional application, project configuration, test
+harness, package manifest, and TypeScript configuration. It pins the
+synchronized Pulse package versions but does not run a package manager or make
+an installation network request.
+
+## 2. Diagnose the configured project
+
+```bash
+pulse doctor
+```
+
+`doctor` validates project discovery, configuration, entry and schema
+resolution, output containment, provider support, required bindings, and
+external tool readiness. Run it after changing profiles, targets, bindings, or
+toolchains and before producing a candidate artifact.
+
+Use JSON when a script or issue report needs stable diagnostics:
+
+```bash
+pulse doctor --json
+```
+
+## 3. Execute the test harness
+
+```bash
+pulse test
+```
+
+`test` runs the cases in the configured `tests/pulse.harness.ts` through the
+selected provider's local conformance runtime. It proves the canonical program,
+fixtures, provider mapping, and expected results. It does not prove a remote
+origin, deployed resource, or provider service.
+
+Event cases use `kind: 'event'`, a canonical frame, and an ordered exact
+`expect.emitted` list. They are available only when the selected provider and
+target expose the bounded event test adapter.
+
+## 4. Run the development lifecycle
+
+```bash
+pulse dev
+```
+
+`dev` is a foreground process. It watches the reachable handler and schema
+graph, recompiles on change, serves through the selected provider's local
+runtime, and shuts down on normal process signals. Development values and
+fixtures remain local inputs; they do not provision deployment resources.
+
+For a mixed HTTP/event project, `dev` serves only HTTP requests. It does not
+open an event listener or injection endpoint; use the harness for bounded event
+execution.
+
+## 5. Build the selected target
+
+```bash
+pulse build
+```
+
+`build` realizes the exact provider and target in the active profile:
+
+- Node Native emits Pulse-owned Wasm and the Node host-contract metadata.
+- Node JavaScript emits a deterministic executable CommonJS source package.
+- Fastly Native emits compact direct-host-ABI `bin/main.wasm`.
+- Fastly JavaScript emits a deterministic source/deployment closure and
+  downstream runtime candidate.
+
+A successful build produces a candidate artifact. It does not publish a
+package, deploy documentation, create provider resources, deploy a service, or
+activate traffic.
+
+Continue with the separate [Node build and execution
+guide](./deploying-node.md) or [Fastly deployment-candidate
+guide](./deploying-fastly.md).
+
+## Inspect when you need the plan
+
+`pulse inspect` is an observability command, not a required lifecycle stage:
+
+```bash
+pulse inspect --json
+```
+
+Use it to examine target support, project eligibility, the reachable graph,
+effects, continuations, schemas, package-owned lowering, provider requirements,
+bindings, and Native plan identity.
+
+## Compile when you need the provider-neutral boundary
+
+`pulse compile` is the advanced provider-neutral Native command:
+
+```bash
+pulse compile
+```
+
+It emits the portable `pulse_host` Wasm contract and its canonical Native plan.
+It does not realize the configured provider. A JavaScript-selected project may
+still use `compile` when its source is Native-eligible, but that separate
+artifact does not change the selected JavaScript target.
+
+Use `build` for the normal application artifact. `compile` is not a prerequisite;
+run it only when you specifically need the portable Native boundary, inspection
+evidence, or a host integration input.
+
+## Failure path
+
+When a lifecycle command fails:
+
+1. rerun `pulse doctor --json`;
+2. use `pulse inspect --json` to compare project requirements with target and
+   provider decisions;
+3. resolve the first source-located or binding-specific diagnostic;
+4. rerun the failed lifecycle step.
+
+See [Managed handler TypeScript and JavaScript](../reference/handler-authoring.md),
+[Provider and target compatibility](../reference/compatibility-matrix.md),
+[Static events and outbound emission](./events.md),
+[Troubleshooting](./troubleshooting.md), and [Diagnostics and
+remediation](../reference/diagnostics.md).