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

package/docs/reference/project-config.md

@@ -0,0 +1,554 @@
+# Project configuration reference
+
+<!-- Generated by wasm/scripts/sync-reference-docs.cjs. Edit the source catalog, not this file. -->
+
+## Conventional `.pulse/config.ts`
+
+Conventional projects use one deferred, synchronous `defineConfig` factory from `@pulse-compute/pulse`. Every top-level key except `pulse` is a flat profile. The scope exposes symbolic `config` and `secret` references; it never resolves ambient values while the project plan is built.
+
+```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',
+    apiBase: scope.config('API_BASE'),
+    apiToken: scope.secret('API_TOKEN'),
+  },
+}))
+```
+
+Project pointers are workspace-relative. Profile selection is explicit and deterministic:
+
+1. `--profile`
+2. `PULSE_PROFILE`
+3. `pulse.defaultProfile`
+
+Project commands accept one optional positional directory and otherwise start from the current directory. Discovery searches upward only for `.pulse/config.ts`. Public entry, config-file, workspace, provider, and target overrides are not supported.
+
+1. Discovery starts at the positional directory or the current working directory and searches upward for .pulse/config.ts.
+2. Profile precedence is --profile, PULSE_PROFILE, then pulse.defaultProfile.
+3. A selected-profile crypto declaration replaces pulse.crypto completely; array and object forms never merge.
+4. Command-line output, host, port, and watch values override the corresponding active-profile field for that command. Entry, provider, and target remain project-configured.
+5. Dedicated harness case inputs replace development inputs for that case; they do not configure deployment resources.
+6. Provider deployment bindings come from the configured provider object; handler source never receives provider SDK objects.
+
+## Project and provider selection
+
+Select the canonical entry, provider, and build output.
+
+### `entry`
+
+Project-relative TypeScript handler entry.
+
+- **Type:** string
+- **Required/default:** Optional; default `./src/index.ts`.
+- **Allowed values or constraints:** —
+- **Scope:** all project commands
+- **Precedence:** `pulse.entry` in `.pulse/config.ts`.
+- **Security and safety:** Must resolve to an existing file.
+- **Related diagnostics:** [`PULSE_ENTRY_NOT_FOUND`](diagnostics.md#pulse-entry-not-found)
+
+### `provider`
+
+Selects provider validation, local conformance, and build realization through the provider package toolchain contract.
+
+- **Type:** 'node' | 'fastly' | 'none' | scoped package name | provider configuration
+- **Required/default:** Optional; default `node`.
+- **Allowed values or constraints:** `node`, `fastly`, `none`, another bare host id, or an exact scoped package name
+- **Scope:** compile/build/dev/test
+- **Precedence:** Bare host ids resolve to `@pulse-compute/provider-<id>`; scoped package names are loaded exactly from the project.
+- **Security and safety:** Package loading is explicit and limited to the selected package `./toolchain` export; there is no scanning or fallback discovery.
+- **Related diagnostics:** [`PULSE_PROVIDER_PACKAGE_NOT_FOUND`](diagnostics.md#pulse-provider-package-not-found), [`PULSE_PROVIDER_TOOLCHAIN_LOAD_FAILED`](diagnostics.md#pulse-provider-toolchain-load-failed), [`PULSE_PROVIDER_TOOLCHAIN_INVALID`](diagnostics.md#pulse-provider-toolchain-invalid), [`PULSE_PROVIDER_UNSUPPORTED`](diagnostics.md#pulse-provider-unsupported), [`PULSE_PROVIDER_COMPILE_ONLY`](diagnostics.md#pulse-provider-compile-only), [`PULSE_TEST_PROVIDER_REQUIRED`](diagnostics.md#pulse-test-provider-required), [`PULSE_DEV_PROVIDER_UNSUPPORTED`](diagnostics.md#pulse-dev-provider-unsupported)
+
+### `outDir`
+
+Project-relative artifact output directory.
+
+- **Type:** string
+- **Required/default:** Optional; default `./dist`.
+- **Allowed values or constraints:** —
+- **Scope:** compile/build
+- **Precedence:** `--out` overrides this field for the current command.
+- **Security and safety:** Must remain a real child of the project root; absolute, parent-traversal, and symbolic-link traversal outside the project root is rejected.
+- **Related diagnostics:** [`PULSE_BUILD_OUT_UNSAFE`](diagnostics.md#pulse-build-out-unsafe)
+
+### `reporting`
+
+Resolved synchronous logging threshold after the flat profile override is applied.
+
+- **Type:** 'off' | 'error' | 'warn' | 'info' | 'debug'
+- **Required/default:** Optional; default `info`.
+- **Allowed values or constraints:** `off`, `error`, `warn`, `info`, `debug`
+- **Scope:** compile/build/dev/test
+- **Precedence:** Selected-profile `reporting`, then `pulse.reporting`, then `info`.
+- **Security and safety:** Known request-owned secret values are redacted before provider emission.
+- **Related diagnostics:** `PULSE_REPORTING_LEVEL_UNSUPPORTED` (family fallback; reference root)
+
+## Cryptographic requirements
+
+Declare exact algorithms for the global or selected profile and resolve one target realization without fallback. This surface is part of the synchronized 1.0.0-beta.1 package set.
+
+### `pulse.crypto`
+
+Declares the complete global algorithm set. Array entries are canonical algorithm names; object entries may pin one exact known realization.
+
+- **Type:** readonly ('HS256' | 'ES256')[] | { readonly HS256?: { readonly realization?: PulseCryptoRealization }; readonly ES256?: { readonly realization?: PulseCryptoRealization } }
+- **Required/default:** Optional; default implicit no-crypto declaration.
+- **Allowed values or constraints:** `HS256`, `ES256`; exact pins `runtime-builtin`, `guest-source:pulse-hmac-as`, and `guest-linked:pulse-es256-rustcrypto-p256`
+- **Scope:** global crypto requirement default
+- **Precedence:** Used only when the selected profile omits `crypto`.
+- **Security and safety:** Keys and verification bytes are not configuration values. Target selection is deterministic and never probes or falls back.
+- **Related diagnostics:** `PULSE_CRYPTO_CONFIG_SHAPE_INVALID` (family fallback; reference root), `PULSE_CRYPTO_ALGORITHM_DUPLICATE` (family fallback; reference root), `PULSE_CRYPTO_ALGORITHM_UNKNOWN` (family fallback; reference root), `PULSE_CRYPTO_REALIZATION_UNKNOWN` (family fallback; reference root)
+
+### `<profile>.crypto`
+
+Replaces the complete global crypto declaration for the selected profile. Arrays and objects never merge with `pulse.crypto`.
+
+- **Type:** readonly ('HS256' | 'ES256')[] | { readonly HS256?: { readonly realization?: PulseCryptoRealization }; readonly ES256?: { readonly realization?: PulseCryptoRealization } }
+- **Required/default:** Optional; default inherit `pulse.crypto` when absent.
+- **Allowed values or constraints:** `[]` and `{}` explicitly select no crypto; otherwise `HS256` and/or `ES256`
+- **Scope:** selected profile
+- **Precedence:** Selected-profile declaration replaces `pulse.crypto`; absence inherits it.
+- **Security and safety:** Every declared algorithm must resolve for the selected target before lowering. A failed exact realization cannot select another backend.
+- **Related diagnostics:** `PULSE_CRYPTO_CONFIG_REQUIRED` (family fallback; reference root), `PULSE_CRYPTO_REALIZATION_PIN_INVALID` (family fallback; reference root), `PULSE_CRYPTO_REALIZATION_UNAVAILABLE` (family fallback; reference root)
+
+## JSON schema policy
+
+Configure bounded schema-body policy. Conventional projects declare registry identity only through pulse.schema.
+
+### `schemas`
+
+Sets schema body limits and content-type policy. Schema identities come from the module selected by pulse.schema.
+
+- **Type:** PulseSchemaConfig
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** compile/dev/test/build
+- **Precedence:** Configuration value.
+- **Security and safety:** Structured bodies are bounded before decoding.
+- **Related diagnostics:** [`PULSE_SCHEMA_COMPILE_FAILED`](diagnostics.md#pulse-schema-compile-failed)
+
+### `schemas.contentTypePolicy`
+
+Controls whether a JSON content type is mandatory.
+
+- **Type:** 'accept-json-or-missing' | 'require-json'
+- **Required/default:** Optional; default `accept-json-or-missing`.
+- **Allowed values or constraints:** `accept-json-or-missing`, `require-json`
+- **Scope:** request and fetched-body schema decode
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** `PULSE_SCHEMA_CONTENT_TYPE_POLICY_INVALID` (family fallback; reference root), [`PULSE_SCHEMA_DECODE`](diagnostics.md#pulse-schema-decode)
+
+### `schemas.maxBytes`
+
+Maximum buffered bytes accepted by schema decoding.
+
+- **Type:** positive safe integer
+- **Required/default:** Optional; default `65_536`.
+- **Allowed values or constraints:** —
+- **Scope:** structured schema decode
+- **Precedence:** Configuration value.
+- **Security and safety:** Raise deliberately; this is a memory and request-amplification boundary.
+- **Related diagnostics:** `PULSE_SCHEMA_BODY_LIMIT_INVALID` (family fallback; reference root), [`PULSE_BODY_TOO_LARGE`](diagnostics.md#pulse-body-too-large)
+
+## Local development
+
+Configure the foreground local server and local-only provider inputs.
+
+### `dev`
+
+Development listener and local fixture inputs.
+
+- **Type:** object
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** pulse dev and local conformance
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `dev.host`
+
+Listener host.
+
+- **Type:** string
+- **Required/default:** Optional; default `127.0.0.1`.
+- **Allowed values or constraints:** —
+- **Scope:** pulse dev
+- **Precedence:** `--host` overrides this field.
+- **Security and safety:** Binding a non-loopback address exposes the local development server.
+- **Related diagnostics:** `PULSE_DEV_HOST_INVALID` (family fallback; reference root)
+
+### `dev.port`
+
+Listener port.
+
+- **Type:** integer
+- **Required/default:** Optional; default `8787`.
+- **Allowed values or constraints:** `0`–`65535`; `0` requests an ephemeral port
+- **Scope:** pulse dev
+- **Precedence:** `--port` overrides this field.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** `PULSE_DEV_PORT_INVALID` (family fallback; reference root)
+
+### `dev.watch`
+
+Watches the entry and schema dependency graph.
+
+- **Type:** boolean
+- **Required/default:** Optional; default `true`.
+- **Allowed values or constraints:** —
+- **Scope:** pulse dev
+- **Precedence:** `--watch` or `--no-watch` overrides this field.
+- **Security and safety:** Configuration-file changes still require a restart.
+- **Related diagnostics:** None specific.
+
+### `dev.maxBodyBytes`
+
+Maximum request body accepted by the local development server.
+
+- **Type:** positive safe integer
+- **Required/default:** Optional; default `65_536`.
+- **Allowed values or constraints:** —
+- **Scope:** incoming local requests
+- **Precedence:** Configuration value.
+- **Security and safety:** Raise deliberately; this is a memory and request-amplification boundary.
+- **Related diagnostics:** `PULSE_DEV_BODY_LIMIT_INVALID` (family fallback; reference root), [`PULSE_REQUEST_BODY_TOO_LARGE`](diagnostics.md#pulse-request-body-too-large)
+
+### `dev.networkFetch`
+
+Allows unmatched local fetches to use the network.
+
+- **Type:** boolean
+- **Required/default:** Optional; default selected provider default.
+- **Allowed values or constraints:** —
+- **Scope:** local fetch realization
+- **Precedence:** This explicit field overrides the selected provider local default.
+- **Security and safety:** Keep disabled for deterministic or untrusted test inputs.
+- **Related diagnostics:** [`PULSE_FETCH_IMPLEMENTATION_UNAVAILABLE`](diagnostics.md#pulse-fetch-implementation-unavailable), [`PULSE_FETCH_NETWORK`](diagnostics.md#pulse-fetch-network)
+
+### `dev.config`
+
+Local configuration-store values.
+
+- **Type:** Readonly<Record<string, string>>
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** local config capability
+- **Precedence:** Configuration value.
+- **Security and safety:** Development input only; it does not configure deployed provider stores.
+- **Related diagnostics:** None specific.
+
+### `dev.secrets`
+
+Local secret-store values.
+
+- **Type:** Readonly<Record<string, string>>
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** local secret capability
+- **Precedence:** Configuration value.
+- **Security and safety:** Raw values are omitted from project JSON, diagnostics, and runtime error details; do not commit real production secrets.
+- **Related diagnostics:** None specific.
+
+### `dev.kv`
+
+Local KV stores keyed by configured logical store name.
+
+- **Type:** Readonly<Record<string, Readonly<Record<string, unknown>>>>
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** local KV capability
+- **Precedence:** Configuration value.
+- **Security and safety:** Development input only; it is not deployed.
+- **Related diagnostics:** None specific.
+
+### `dev.fetches`
+
+Deterministic fetch fixtures resolved before optional live network fetch.
+
+- **Type:** Readonly<Record<string, unknown>>
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** local fetch capability
+- **Precedence:** Configuration value.
+- **Security and safety:** Prefer fixtures for deterministic tests and offline development.
+- **Related diagnostics:** None specific.
+
+## Fastly provider options
+
+Options passed to fastly(...) from @pulse-compute/provider-fastly.
+
+### `fastly.configStore`
+
+Fastly Config Store resource name.
+
+- **Type:** string
+- **Required/default:** Optional; default `pulse_config`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly config capability
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `fastly.secretStore`
+
+Fastly Secret Store resource name.
+
+- **Type:** string
+- **Required/default:** Optional; default `pulse_secrets`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly secret capability
+- **Precedence:** Configuration value.
+- **Security and safety:** The name is build metadata; secret values are never embedded by this option.
+- **Related diagnostics:** None specific.
+
+### `fastly.kv`
+
+Maps logical ctx.kv names to Fastly KV Store resource names.
+
+- **Type:** Readonly<Record<string, string>>
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly KV capability
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** [`PULSE_FASTLY_KV_BINDINGS_INVALID`](diagnostics.md#pulse-fastly-kv-bindings-invalid)
+
+### `fastly.backends`
+
+Maps static absolute origin URLs to named Fastly backends.
+
+- **Type:** Readonly<Record<string, string>>
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly fetch capability
+- **Precedence:** Configuration value.
+- **Security and safety:** Prefer explicit backends over dynamic origin authority.
+- **Related diagnostics:** [`PULSE_FASTLY_BACKEND_BINDINGS_INVALID`](diagnostics.md#pulse-fastly-backend-bindings-invalid), [`PULSE_FASTLY_BACKEND_REQUIRED`](diagnostics.md#pulse-fastly-backend-required)
+
+### `fastly.dynamicBackends`
+
+Allows undeclared outbound origins to use dynamic backends.
+
+- **Type:** boolean
+- **Required/default:** Optional; default `false`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly fetch capability
+- **Precedence:** Configuration value.
+- **Security and safety:** Opt in deliberately because it broadens outbound authority.
+- **Related diagnostics:** [`PULSE_FASTLY_BACKEND_REQUIRED`](diagnostics.md#pulse-fastly-backend-required)
+
+### `fastly.grip`
+
+Provider-owned bindings used by package-owned GRIP compatibility and canonical broadcast effects.
+
+- **Type:** object
+- **Required/default:** Optional; default omitted.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly GRIP capability
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `fastly.grip.fanoutBackend`
+
+Named Fastly Fanout backend.
+
+- **Type:** string
+- **Required/default:** Optional; default omitted.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP hold
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** [`PULSE_FASTLY_GRIP_FANOUT_BACKEND_REQUIRED`](diagnostics.md#pulse-fastly-grip-fanout-backend-required)
+
+### `fastly.grip.publishEndpoint`
+
+Provider-owned absolute publish/control endpoint; distinct from public gateway and ingress URLs.
+
+- **Type:** string
+- **Required/default:** Optional; default omitted.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP broadcast
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** [`PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED`](diagnostics.md#pulse-fastly-grip-publish-binding-required)
+
+### `fastly.grip.publishUrl`
+
+Absolute publish endpoint URL.
+
+- **Type:** string
+- **Required/default:** Optional; default omitted.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP publish
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** [`PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED`](diagnostics.md#pulse-fastly-grip-publish-binding-required)
+
+### `fastly.grip.publishBackend`
+
+Named backend for the provider publish endpoint.
+
+- **Type:** string
+- **Required/default:** Optional; default omitted.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP broadcast/publish
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** [`PULSE_FASTLY_GRIP_PUBLISH_BINDING_REQUIRED`](diagnostics.md#pulse-fastly-grip-publish-binding-required)
+
+### `fastly.grip.authentication`
+
+Authentication metadata containing references only; no credential value is accepted here.
+
+- **Type:** object
+- **Required/default:** Optional; default omitted.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP broadcast authentication
+- **Precedence:** Configuration value.
+- **Security and safety:** Store the value in Fastly Secret Store and configure only secretRef.
+- **Related diagnostics:** None specific.
+
+### `fastly.grip.authentication.scheme`
+
+Provider authentication scheme.
+
+- **Type:** 'bearer'
+- **Required/default:** Optional; default `bearer`.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP broadcast authentication
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** `PULSE_FASTLY_NATIVE_GRIP_AUTH_SCHEME_UNSUPPORTED` (family fallback; reference root)
+
+### `fastly.grip.authentication.secretRef`
+
+Named Fastly Secret Store key used for the bearer token.
+
+- **Type:** string
+- **Required/default:** Optional; default omitted.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP broadcast authentication
+- **Precedence:** Configuration value.
+- **Security and safety:** The secret value is resolved only at request execution and is redacted from traces.
+- **Related diagnostics:** `PULSE_FASTLY_NATIVE_GRIP_SECRET_REFERENCE_MISSING` (family fallback; reference root)
+
+### `fastly.grip.directHold`
+
+Enables the direct host-owned hold response realization.
+
+- **Type:** boolean
+- **Required/default:** Optional; default `true`.
+- **Allowed values or constraints:** —
+- **Scope:** GRIP hold
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `fastly.name`
+
+Generated Fastly package name.
+
+- **Type:** string
+- **Required/default:** Optional; default `pulse-app`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly package metadata
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `fastly.description`
+
+Generated Fastly package description.
+
+- **Type:** string
+- **Required/default:** Optional; default `Pulse application`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly package metadata
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `fastly.authors`
+
+Generated Fastly package authors.
+
+- **Type:** readonly string[]
+- **Required/default:** Optional; default `[]`.
+- **Allowed values or constraints:** —
+- **Scope:** Fastly package metadata
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `fastly.local`
+
+Local-only behavior; it does not alter the deployed target.
+
+- **Type:** object
+- **Required/default:** Optional; default `{}`.
+- **Allowed values or constraints:** —
+- **Scope:** local Fastly conformance
+- **Precedence:** Configuration value.
+- **Security and safety:** No special handling.
+- **Related diagnostics:** None specific.
+
+### `fastly.local.networkFetch`
+
+Allows unmatched local Fastly fetches to use the network.
+
+- **Type:** boolean
+- **Required/default:** Optional; default `false`.
+- **Allowed values or constraints:** —
+- **Scope:** local Fastly fetch realization
+- **Precedence:** `dev.networkFetch` overrides this value when explicitly set.
+- **Security and safety:** Keep disabled for deterministic tests and offline development.
+- **Related diagnostics:** None specific.
+
+## Fastly profile example
+
+```ts
+local: {
+  host: 'fastly',
+  target: 'native',
+  fastly: {
+    bindings: {
+      configStore: 'pulse_config',
+      secretStore: 'pulse_secrets',
+      kv: { sessions: 'sessions' },
+      backends: { 'https://api.example.com': 'api_backend' },
+      dynamicBackends: false,
+      grip: {
+        fanoutBackend: 'fanout',
+        publishUrl: 'https://publisher.example.com/publish',
+        publishBackend: 'publisher',
+        directHold: true,
+      },
+    },
+    build: { name: 'pulse-app', authors: ['Team'] },
+    local: { networkFetch: false },
+  },
+}
+```
+
+Deployment resource names configure provider bindings; local `dev.config`, `dev.secrets`, `dev.kv`, and `dev.fetches` values never create or populate deployed resources.
+
+## Safety invariants
+
+- Output directories must remain real descendants of the project root.
+- Structured request and schema bodies are bounded before decoding.
+- Live local network fetch is explicit for Fastly and can be disabled for Node.
+- Raw secret values are redacted from public JSON, diagnostics, and runtime error detail.
+- Provider SDK objects and provider-specific namespaces never enter canonical handler scope.
+- `none` is compile-only; it cannot execute `pulse dev` or `pulse test`.