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

package/docs/packages/pulse.md

@@ -0,0 +1,159 @@
+# `@pulse-compute/pulse`
+
+`@pulse-compute/pulse` is the conventional application-authoring package for a
+Pulse project. It owns the project-aware `Pulse` application root, deferred
+configuration factory, and static schema declarations while reusing the
+provider-neutral runtime contract.
+
+## Install
+
+```bash
+npm install @pulse-compute/pulse@1.0.0-beta.1
+```
+
+The package exposes two supported entry points:
+
+- `@pulse-compute/pulse` for `Pulse`, `defineConfig`, and runtime-owned
+  authoring types;
+- `@pulse-compute/pulse/schema` for `schema`, `response`, and
+  `defineSchemaRegistry`.
+
+## Application root
+
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => {
+  return ctx.json({ ok: true })
+})
+
+export default app
+```
+
+`Pulse` extends the same live `Router` implementation exposed by
+`@pulse-compute/runtime`; it does not introduce a second routing or execution
+system. Compiler analysis normalizes the application into the canonical Router
+IR before target selection and provider realization.
+
+`Pulse` also owns root-only static event registration:
+
+```ts
+app.on('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const reading = ctx.event.payload
+  await ctx.config.get('MODE')
+  void reading
+})
+
+app.on('system.tick', { schema: null }, async (ctx) => {
+  void ctx.event.type
+})
+```
+
+Event types and schema IDs are literal compiler inputs, every type has one
+owner, and non-null schemas must resolve through the project registry. Event
+handlers receive a non-HTTP context and complete with `void`. The compiler
+places HTTP and event handlers in separate planes of one application-entry
+table. Eligible event handlers can lower through the conditional
+provider-neutral Native event ABI. Node has a bounded invocation-scoped
+reference ingress and outbound-acceptance adapter for direct JavaScript/Native
+parity, but no public event bus, deployment listener, delivery guarantee, or
+other provider target support is implied.
+
+The complete authoring, frame, queue, target, diagnostic, and no-call boundary
+is documented in [Static events and outbound emission](../guides/events.md).
+
+The statically analyzable root forms are:
+
+```ts
+new Pulse({ auto: true })
+new Pulse(configFactory)
+```
+
+Aliases, subclasses, factories returning `Pulse`, mounted `Pulse` instances, and
+re-exported application roots remain outside the initial single-entry grammar.
+Use `Router` for mounted and child applications.
+
+## Project configuration
+
+Canonical configuration is one synchronous deferred factory:
+
+```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,
+    reporting: 'info',
+  },
+  local: {
+    host: 'node',
+    target: 'native',
+    apiBase: scope.config('API_BASE'),
+    token: scope.secret('API_TOKEN'),
+  },
+}))
+```
+
+The scope produces symbolic configuration and secret references only. It does
+not expose selected-profile state, resolved values, commands, or ambient
+environment authority.
+
+## Schema declarations
+
+```ts
+import {
+  defineSchemaRegistry,
+  response,
+  schema,
+} from '@pulse-compute/pulse/schema'
+
+interface User {
+  id: number
+  name: string
+}
+
+export default defineSchemaRegistry({
+  schemas: {
+    'app.User': schema<User>(),
+  },
+  responses: {
+    'app.UserResponse': response(200, 'app.User'),
+  },
+})
+```
+
+Schema calls are static declarations consumed by the compiler. They do not add
+runtime reflection or generic JSON parsing to the guest module.
+
+## Async-shaped handlers and execution state
+
+Conventional projects require async-shaped handlers. Native lowering erases the
+wrapper and lowers only recognized Pulse effects; it does not add Promise or
+Asyncify runtimes.
+
+See [Managed handler TypeScript and
+JavaScript](../reference/handler-authoring.md) for the canonical static source
+rules and JavaScript-only boundary, and the [compatibility
+matrix](../reference/compatibility-matrix.md) for four-mode support.
+
+`ctx.state` is an execution-scoped string map. HTTP executions share it across
+the forward Router cursor, mounted routers, error recovery, and Native
+continuation resumption; event executions share it across their continuation
+resumption. It is reset between HTTP requests and event invocations and does
+not expose enumeration, object values, or persistence.
+
+## Ownership boundary
+
+This package owns application ergonomics and declarations. It does not own
+Handler IR, effects, continuations, Native lowering, provider lifecycle, or
+provider-specific bootstraps. Fastly and other host realization remains in the
+corresponding provider package.
+
+For the lower-level static Router and complete context contract, see
+[`@pulse-compute/runtime`](./runtime.md). For project orchestration, see
+[`@pulse-compute/cli`](./cli.md).

package/docs/packages/runtime.md

@@ -0,0 +1,256 @@
+# `@pulse-compute/runtime`
+
+`@pulse-compute/runtime` is the canonical, provider-neutral TypeScript authoring surface for Pulse applications. Install it in every canonical project and import handler types or the static `Router` marker from the package root.
+
+## Install
+
+```bash
+npm install @pulse-compute/runtime@1.0.0-beta.1
+```
+
+A project created by `pulse init` depends on the public
+`@pulse-compute/pulse` conventional application package, which re-exports these
+runtime types for convenience. Public package availability remains
+release-manifest-owned.
+
+Conventional `.pulse` projects require async-shaped managed handlers and report `PULSE_HANDLER_ASYNC_REQUIRED` for synchronous forms. The compiler erases the wrapper and lowers trusted awaited Pulse effects through the Promise-free effect/continuation machinery.
+
+## Minimal handler
+
+<!-- pulse-doc-source: examples/01-hello-json/src/index.ts -->
+```ts
+import { Pulse } from '@pulse-compute/pulse'
+
+const app = new Pulse({ auto: true })
+
+app.get('/health', async (ctx) => ctx.json({ ok: true }))
+app.get('/hello', async (ctx) => ctx.json({ message: 'hello from Pulse' }))
+app.get('/*', async (ctx) => ctx.text('not found', { status: 404 }))
+
+export default app
+```
+<!-- /pulse-doc-source -->
+
+The source-bound example is the conventional authoring shape. Managed handlers are async-shaped, while `ctx` remains the handler's only authority.
+
+## Public contract
+
+The package exports:
+
+- `PulseRequest` for method, URL, path, headers, bounded text, and bounded JSON reads;
+- `PulseFetchInit` and `PulseFetchResponse` for canonical outbound fetches;
+- structured and opaque response types;
+- `PulseExecutionContext`, shared by HTTP and event handlers, with state, logging,
+  fetch, config, secret, KV, keyed parallel, and one-way event emission;
+- `PulseContext` with the shared authority plus HTTP request and response construction;
+- `PulseEvent`, `PulseEventContext`, and `PulseEventHandler` for exact type,
+  immutable schema payload, non-HTTP authority, and void completion;
+- `PulseResult`, `Handler`, `PulseRouteContext`, `RouteHandler`, `RouterMiddleware`, `RouterErrorHandler`, and `RouterNext`;
+- `Router`, the compile-time marker for static route topology;
+- `RUNTIME_API_VERSION`, currently `pulse.runtime-authoring.v4`, and `ROUTER_API_VERSION`, currently `pulse.router-authoring.v2`.
+
+The complete type-by-type reference is in [Canonical API](../../API.md).
+
+
+## Static Router applications
+
+```ts
+import { Router } from '@pulse-compute/runtime'
+
+const app = new Router()
+app.use(async (ctx, next) => {
+  if (!ctx.req.header('authorization')) return ctx.text('Unauthorized', { status: 401 })
+  return next()
+})
+app.get('/health', async (ctx) => ctx.json({ ok: true }))
+app.get('/users/:id', async (ctx) => ctx.json({ id: ctx.param('id') }))
+export default app
+```
+
+The compiler extracts and flattens static routes, middleware, mounts, and error entries before normal canonical lowering. `return next()` and `return next(error)` are terminal control transfers; the current handler never resumes. The marker does not dispatch through a JavaScript runtime. See [Static Router authoring](../guides/routing.md).
+
+## Request access
+
+```ts
+const method = ctx.req.method
+const path = ctx.req.path
+const requestId = ctx.req.header('x-request-id')
+const text = await ctx.req.text()
+const input = await ctx.req.json<{ name: string }>('app.CreateUserInput')
+```
+
+Schema-backed JSON reads use an exact ID declared by the selected `.pulse/config.ts` profile:
+
+```ts
+const input = await ctx.req.json<CreateUserInput>('app.CreateUserInput')
+```
+
+See [Explicit JSON schemas](../guides/json-schemas.md).
+
+
+## Async and execution state
+
+Native targets treat `async` and trusted `await` as authoring notation. The compiler erases the async wrapper, lowers awaited Pulse effects into the existing continuation state machine, warns when `await` wraps a proven synchronous `ctx` value, and rejects arbitrary library awaits for native selection. No Promise runtime or Asyncify transform is linked.
+
+The exact accepted source shapes, `ctx.parallel` record restrictions, and
+JavaScript-only forms live in [Managed handler TypeScript and
+JavaScript](../reference/handler-authoring.md). The tested four-mode claims live
+in the [compatibility matrix](../reference/compatibility-matrix.md).
+
+`ctx.state` is a synchronous execution-local string map:
+
+```ts
+ctx.state.set('request-id', 'r1')
+const requestId = ctx.state.get('request-id') // string | undefined
+```
+
+For HTTP, state is visible across forward middleware, mounted Routers, error
+recovery, and effect continuation resume. Event handlers use the same state
+surface across continuation resume. State is isolated between HTTP requests and
+between event invocations.
+
+With project `pulse.strict: true` (the default), schema-less request JSON is rejected. Explicit `pulse.strict: false` enables the byte-bounded `host-generic-json` capability for reachable schema-less calls; the native plan and manifest report that dynamic-host choice. Schema-bound JSON remains specialized in either mode.
+
+## Event context and Native ingress
+
+Static event handlers receive `PulseEventContext<Payload>`:
+
+```ts
+app.on('device.reading', { schema: 'events.DeviceReading' }, async (ctx) => {
+  const reading = ctx.event.payload
+  const mode = await ctx.config.get('MODE')
+  ctx.state.set('last-mode', mode)
+  void reading
+})
+```
+
+`ctx.event.type` is the exact registered event type. The payload is validated
+against the registration schema and detached before entry; a `schema: null`
+registration receives `null`. Event contexts expose shared execution authority
+but no request, route, response, middleware, or Router-transfer surface, and
+handlers complete with `void`.
+
+Eligible event handlers lower to the provider-neutral Native plan and execute
+through the conditional `pulse.native-event-abi.v1` entry. Event-only and mixed
+artifacts are supported; HTTP-only Native bytes remain unchanged. Node wraps
+this entry with an invocation-scoped bounded FIFO reference adapter for direct
+JavaScript/Native parity. That adapter is provider-maintainer infrastructure,
+not a public listener, deployment transport, or process-global bus.
+
+## Outbound events
+
+HTTP and event handlers can create a one-way, schema-bound effect:
+
+```ts
+await ctx.emit('device.led.set', {
+  schema: 'events.DeviceLedSet',
+  payload: { enabled: true },
+})
+
+await ctx.emit('system.tick', { schema: null })
+```
+
+The call must be awaited directly or through an awaited `ctx.parallel` group.
+Event type and schema IDs must be literal at compilation; non-null schemas must
+resolve in the project registry and require a payload, while `schema: null`
+forbids one. JavaScript and Native execution validate and detach the same frame
+before host acceptance and return `undefined`. Native suspends and resumes
+through the ordinary effect/continuation protocol. The Node reference adapter
+records exact accepted frames independently from its FIFO ingress queue, so it
+never performs automatic loopback. It does not deliver a receipt, persistence,
+retry, or public provider transport.
+
+`ctx.emit` is not a call operation. The runtime exposes no request/reply
+correlation, automatic local dispatch, `ctx.call`, or reserved call capability.
+See [Static events and outbound emission](../guides/events.md) for the frame,
+queue, target, and Native-extension details.
+
+## Logging
+
+`ctx.log` exposes four synchronous string methods:
+
+```ts
+ctx.log.error('failed to publish event')
+ctx.log.warn('retrying origin request')
+ctx.log.info('user created')
+ctx.log.debug('decoded request body')
+```
+
+The active profile’s flat `reporting` setting resolves `off`, `error`, `warn`,
+`info`, or `debug`; the default is `info`. Native lowering removes calls below
+the resolved threshold and writes enabled messages through the synchronous
+`pulse_log(level, ptr, len)` host ABI. JavaScript targets use the same threshold
+and provider-owned destination at runtime.
+
+Logging is not a Pulse effect and cannot suspend a handler. Sink failures are
+request-contained, and known request secrets are redacted before managed output.
+Messages are strings only; structured logging and application-significant side
+effects inside message expressions are outside the Beta contract.
+
+## Responses
+
+```ts
+return ctx.json({ ok: true }, { status: 201 })
+return ctx.text('not found', { status: 404 })
+return ctx.response({ status: 204 })
+```
+
+A schema-backed JSON response names its compiled schema:
+
+```ts
+return ctx.json(output, { schema: 'app.CreateUserOutput' })
+```
+
+## Host capabilities
+
+Canonical host work is requested through `ctx`:
+
+```ts
+const upstream = await ctx.fetch('https://api.example.test/items').json('app.ItemList')
+const mode = await ctx.config.get('MODE')
+const token = await ctx.secret.get('API_TOKEN')
+const session = await ctx.kv<{ userId: number }>('sessions').get('current')
+```
+
+Those calls are compiled into explicit effects and validated against the selected provider. See [Compilation and lowering](../concepts/compilation-and-lowering.md).
+
+## Structured and opaque fetch results
+
+A response can be inspected as bounded structured data:
+
+```ts
+const item = await ctx.fetch('https://api.example.test/item').json<{ id: number }>('app.Item')
+return ctx.json(item)
+```
+
+Or returned directly as an opaque pass-through response:
+
+```ts
+return ctx.fetch('https://assets.example.test/archive.bin')
+```
+
+Opaque bodies are returnable but not inspectable or iterable. See [Structured and opaque bodies](../concepts/bodies.md).
+
+## Deliberate exclusions
+
+The runtime contract does not expose:
+
+- arbitrary Promise construction or general Promise semantics under native lowering;
+- ambient `process.env`, global fetch, timers, or randomness;
+- provider SDK objects or provider-specific namespaces;
+- arbitrary binary body inspection;
+- userland stream transforms or background tasks;
+- raw sockets.
+
+The compiler rejects unsupported forms rather than treating them as
+provider-dependent behavior. See the
+[Beta scope](../preview-scope.md).
+
+## Package and installed references
+
+The npm tarball includes:
+
+- `docs/API.md` — the canonical API reference;
+- `docs/preview-scope.md` — the supported and excluded Beta surface.
+
+For workflow and project configuration, use [`@pulse-compute/cli`](./cli.md).

package/docs/preview-scope.md

@@ -0,0 +1,142 @@
+# Beta scope
+
+Pulse `1.0.0-beta.1` is a Beta of one provider-neutral application contract
+with explicit Native and JavaScript execution targets. The intended 1.0
+surface is present, but deliberate corrections may still occur before the
+stable `1.0.0` release.
+
+The Beta is intentionally strict: Pulse builds the target selected by the
+active `.pulse/config.ts` profile, and unsupported source stops at the exact
+lowering boundary with a stable diagnostic. Pulse never silently switches
+targets.
+
+## Supported application behavior
+
+- Async-shaped provider-neutral TypeScript handlers; trusted Pulse awaits lower
+  into explicit effects and continuations without a Promise runtime.
+- Static Router v2 with terminal middleware, route fallthrough, error
+  middleware, GET/HEAD/POST routes, exact paths, named parameters, trailing
+  wildcards, and acyclic mounts.
+- Basic branching and structured object, array, and scalar manipulation.
+- Request method, URL, path, headers, text, and JSON access.
+- Bounded, memoized structured body decoding.
+- Explicit TypeScript JSON schema declarations and literal schema IDs.
+- GET, HEAD, and POST fetch effects.
+- Independent Native effect grouping, dependent continuation chains, and
+  explicit cross-target `ctx.parallel({ ... })` keyed groups.
+- HTTP status and headers as ordinary response data.
+- JSON, text, custom, and direct pass-through responses.
+- Exact-name config and secret reads.
+- Named KV `get` and `put`.
+- Opaque host-owned binary and stream pass-through.
+- Stateless package-root GRIP request classification, response subscription and
+  handoff framing, and configured request-bound broadcast.
+- Synchronous string logging through `ctx.log.error`, `warn`, `info`, and
+  `debug`, with flat profile reporting thresholds and provider-owned output.
+- Root-only static `Pulse.on` declarations, immutable schema-validated event
+  contexts, and one-way `ctx.emit` acceptance through the bounded Node
+  JavaScript/Native reference adapter.
+- Provider-neutral portable Wasm and configured Native Node or Fastly builds.
+- Direct JavaScript execution and deterministic source packaging for Node and
+  Fastly.
+
+## Execution contract
+
+The Beta has two target classes and four explicitly selected
+execution modes over one application model:
+
+```text
+source
+├─ Node / Native        → canonical analysis → Pulse-owned Wasm → Node realization
+├─ Node / JavaScript    → graph-backed loader → live packages → Node lifecycle
+├─ Fastly / Native      → canonical analysis → direct-host-ABI bin/main.wasm
+└─ Fastly / JavaScript  → deterministic source package → Fastly JS runtime candidate
+```
+
+Native source that crosses the supported lowering boundary fails visibly with a
+stable diagnostic. JavaScript core Router execution, request/response lifecycle,
+eligibility inspection, effects, package realizations, source packaging, schema
+enforcement, target integrity, and bounded GRIP realization are implemented.
+Native/JavaScript conformance covers Router context, body handling, fetch
+projections, configuration, secrets, KV, schema codecs, GRIP framing, logging,
+and target identity. All declared Node and Fastly full-target-support gates are
+satisfied for the implemented four-mode contract.
+
+Fastly JavaScript candidate evidence compiles the deterministic source package
+with the exact pinned downstream toolchain and records a structurally deployable
+runtime artifact. The final release candidate must additionally pass the
+mandatory external Fastly CLI-managed reality lane. Neither result authorizes a
+service deployment or activation.
+
+There is no automatic fallback. An operator must select the target through
+project configuration or an explicitly permitted CLI target selection. A
+successful provider-neutral compile does not silently change a
+JavaScript-selected project into a Native one.
+
+## Deliberately unsupported
+
+- Automatic fallback from Native lowering to JavaScript execution.
+- Declaring general target availability without satisfying every declared
+  full-target-support gate.
+- Arbitrary Promise construction, arbitrary library awaits under Native
+  selection, JSPI, or Asyncify semantics. Managed `async` wrappers and trusted
+  Pulse awaits are supported notation, not a Promise runtime.
+- Ambient `fetch`, environment variables, filesystem, process, sockets, or
+  timers.
+- Provider SDK objects or `ctx.fastly` / `ctx.cloudflare` namespaces.
+- Capability enumeration or runtime provider introspection.
+- Automatic discovery of arbitrary TypeScript types.
+- Dynamic schema IDs.
+- Arbitrary binary body inspection or mutation.
+- Userland chunk iteration, transform streams, or manual backpressure.
+- Background tasks and work that outlives the request.
+- Raw TCP or UDP sockets.
+- Dynamic GRIP channel, framing-option, or message shapes under Native
+  selection.
+- Onion-style post-`next()` middleware, assigning or awaiting `next()`, Router
+  `throw` transfer, realtime hooks, channels, timeout scopes, `ctx.resolve`, or
+  `ctx.resolved`.
+- Third-party provider or lowerer self-registration.
+- A public event listener, production event transport, delivery/retry
+  guarantee, automatic loopback or reentrancy, generic bus, `ctx.call`, or
+  request/reply event routing.
+- Fastly, browser, or ESP32 event ingress/emit realization. Fastly fails closed
+  with exact eligibility diagnostics; browser and ESP32 remain unclaimed.
+
+## Compatibility authority
+
+The single source-form, provider-binding, artifact, and deployment-boundary
+table is [Provider and target compatibility](./reference/compatibility-matrix.md).
+It uses one public target order—Node JavaScript, Fastly JavaScript, Node Native,
+and Fastly Native—and links every row to a focused proof or canonical contract.
+
+The exact portable language subset and the JavaScript-only Native eligibility
+boundaries are defined in
+[Managed handler TypeScript and JavaScript](./reference/handler-authoring.md).
+
+## Body model
+
+If a body is inspected as text or JSON, Pulse treats it as a bounded immutable
+value. If a body is passed through as binary or a stream, it remains an opaque
+host-owned capability handle.
+
+```text
+inspect it → bounded structured value
+pass it through → opaque handle
+```
+
+## Compatibility and release signals
+
+- Documented behavior is intentional and evidence-backed.
+- Unsupported behavior fails explicitly.
+- No execution target silently falls back.
+- Public surfaces may still change deliberately before stable `1.0.0`.
+- Implementation and historical subpaths do not gain accidental compatibility
+  guarantees.
+- Package names, release artifacts, and published versions are immutable once
+  released.
+
+The intended npm dist-tag for the Beta is `beta`. It becomes
+active only through the atomic documentation-release transaction and an
+explicitly authorized publication. The workflow never assigns `latest`
+implicitly.

package/docs/reference/README.md

@@ -0,0 +1,33 @@
+<!-- pulse-doc-meta:start
+owner: docs-platform
+status: active
+last-reviewed: 2026-08-01
+review-by: 2027-02-01
+pulse-doc-meta:end -->
+
+# Reference
+
+Use this section for exact application, command, configuration, compatibility,
+and diagnostic contracts.
+
+- [API reference](../../API.md) — a context-at-a-glance map plus the exact
+  Router, request, header, route parameter, state, response, and capability
+  surfaces.
+- [Provider and target compatibility](./compatibility-matrix.md) — supported
+  behavior across Node and Fastly Native and JavaScript targets.
+- [Managed handler TypeScript and JavaScript](./handler-authoring.md) — the
+  accepted authoring language and Native eligibility boundary.
+- [CLI reference](./cli.md) — commands, flags, and machine-readable command
+  specification.
+- [Project configuration](./project-config.md) — profiles, providers, targets,
+  bindings, and schemas.
+- [Diagnostics and remediation](./diagnostics.md) — stable public diagnostic
+  codes and corrective actions.
+- [Environment variables](./environment.md) — supported tooling inputs and
+  contributor-only controls.
+- [Shell completion](./shell-completion.md) — Bash, Zsh, and Fish integration.
+
+Repository governance, release operations, publication, deployment, and
+evidence procedures are intentionally separated from the application
+reference. Maintainers can enter that narrower surface through the
+[maintainer documentation](../maintainers/).