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

package/docs/contributing/adding-core-provider.md

@@ -0,0 +1,315 @@
+<!-- pulse-doc-meta:start
+owner: docs-platform
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Add a provider toolchain
+
+> **Current boundary:** Provider selection is explicit, not discovered. A bare
+> host ID such as `node`, `fastly`, or `esp32` resolves to
+> `@pulse-compute/provider-<id>`, `none` remains internal, and a scoped package
+> name is loaded exactly from the project. The selected package must export the
+> versioned `./toolchain` contract.
+> No dependency scanning, package-keyword registration, or target fallback
+> occurs.
+
+A core provider realizes canonical compiler operations without changing the application handler API. It normally owns a capability descriptor, a local conformance runtime, binding normalization, and—when deployable—a target builder and toolchain boundary.
+
+This is separate from package-root lowering. A provider implements canonical
+capabilities and target realization; a Pulse-aware package may contribute a
+bounded first-party package effect. See [Pulse-aware package
+authoring](./pulse-aware-packages.md) before choosing either boundary.
+
+## Provider invariants
+
+Every provider must preserve:
+
+```json
+{
+  "providerSpecificUserland": false,
+  "providerSdkUserland": false,
+  "capabilityDiscoveryFromUserland": false
+}
+```
+
+Canonical source imports `@pulse-compute/runtime` and supported package facades. Provider SDK objects, request types, storage clients, and deployment resources do not enter handler scope.
+
+## Integration map
+
+| Concern | Current owner/location |
+|---|---|
+| Capability vocabulary and provider plan | `wasm/packages/contracts/src/provider/canonical-provider.js` |
+| Node descriptor/runtime | `packages/provider-node/src/runtime/canonical-api-runtime.js` |
+| Fastly descriptor | `packages/provider-fastly/src/provider-contract.js` |
+| Fastly local runtime | `packages/provider-fastly/src/runtime/canonical-api-runtime.js` |
+| Fastly target writer/toolchain | `packages/provider-fastly/src/build/` |
+| Deterministic package bootstrap | `wasm/packages/compiler/src/provider-toolchain.js` |
+| Versioned bootstrap contract | `wasm/packages/contracts/src/provider/toolchain.js` |
+| Provider driver and config normalization | Provider-owned `./toolchain` export |
+| Command execution | `wasm/packages/cli/src/project-execution.js` |
+| Public config reference | Provider-owned reference contribution, aggregated by `wasm/packages/cli/src/project-config-schema.js` |
+| Package policy | `release/pulse-release-manifest.json` |
+
+## 1. Define provider identity and scope
+
+Choose:
+
+- stable provider ID;
+- package owner and version;
+- runtime identity;
+- build target identity;
+- whether it supports local execution;
+- whether it emits a deployable target;
+- its exact canonical capabilities;
+- required resource bindings;
+- toolchain and external CLI dependencies.
+
+Do not claim a capability because a provider SDK happens to contain something similar. The provider must implement the canonical semantics and failure behavior.
+
+## 2. Build a canonical provider descriptor
+
+Descriptors are normalized by the shared provider contract. A conceptual descriptor looks like:
+
+```js
+const EXAMPLE_PROVIDER_DESCRIPTOR = createProviderDescriptor({
+  id: 'example',
+  providerVersion: '1.0.0-beta.2',
+  package: '@pulse-compute/provider-example',
+  runtime: 'pulse.canonical-example-runtime.v1',
+  buildTarget: 'example-edge',
+  deployable: true,
+  localExecution: true,
+  capabilities: [
+    'request.method',
+    'request.path',
+    'response.json',
+    'response.text',
+    'fetch',
+  ],
+  lowering: {
+    'request.method': 'example.request.method',
+    'request.path': 'example.request.path',
+    'response.json': 'example.response.json',
+    'response.text': 'example.response.text',
+    fetch: 'example.fetch.dispatch',
+  },
+})
+```
+
+The shared contract verifies that every declared capability has a lowering and that every compiled requirement is supported.
+
+When a package-owned operation requires an additional result capability—such as opaque pass-through—the descriptor must implement both the operation and result capability.
+
+## 3. Normalize bindings separately from source
+
+Canonical effects refer to logical resources: an origin URL, KV namespace, config store, secret store, or package resource. Provider configuration maps those to deployment bindings.
+
+A binding normalizer should:
+
+- accept only documented project fields;
+- produce deterministic normalized values;
+- reject duplicate, invalid, or missing mappings;
+- keep raw secret values out of the plan;
+- make dynamic-resource behavior explicit;
+- distinguish local fixture values from deployment resource names.
+
+Do not discover bindings by scanning provider-specific imports in handler source.
+
+## 4. Implement the local conformance runtime
+
+The local runtime executes canonical programs for `pulse test` and `pulse dev`. It should use shared host-runtime primitives where possible and implement each descriptor capability with normalized results.
+
+Required behavior includes:
+
+- bounded request-body access;
+- deterministic response construction;
+- effect dispatch and continuation resumption;
+- timeout and failure normalization;
+- config/secret/KV fixture isolation;
+- structured versus opaque body rules;
+- request completion and cleanup;
+- secret redaction.
+
+Local behavior should match canonical semantics, not emulate every incidental detail of a provider SDK.
+
+## 5. Implement target generation when deployable
+
+A deployable provider needs a target writer that consumes:
+
+- the canonical program;
+- provider lowering plan;
+- normalized bindings;
+- schema bundle and package effects;
+- project metadata;
+- output-safety options.
+
+It should emit a deterministic source package and validate the final artifact. For Wasm targets, verify at least the expected file, magic/version bytes, and compiler result metadata.
+
+Keep external toolchain discovery in a narrow adapter. Return stable diagnostics for unavailable binaries, version mismatch, timeout, compile failure, or invalid output.
+
+## 6. Export the formal toolchain
+
+The provider package exports `./toolchain`. Its module declares package
+identity and creates the provider-owned driver:
+
+```js
+module.exports = defineProviderToolchain({
+  version: 'pulse.provider-toolchain.v1',
+  id: 'example',
+  packageName: '@example/pulse-provider',
+  packageVersion: require('../package.json').version,
+  createDriver() {
+    return defineProviderDriver({
+      version: 'pulse.provider-driver.v1',
+      id: 'example',
+      descriptor: EXAMPLE_PROVIDER_DESCRIPTOR,
+      executable: true,
+      localExecution: true,
+      deployable: true,
+      normalizeConfig,
+      projectConfigDocument,
+      initTemplate,
+      targets,
+      execute: executeCanonicalProgram,
+      createLoweringPlan,
+      writeTarget,
+    })
+  },
+})
+```
+
+`createDriver()` receives no compiler service or caller option bag. Use the
+shared provider contract helpers for the exact planning input, target
+invocation, Native artifact, JavaScript package result, and provider target
+result shapes. A supported Native descriptor must include a valid
+`finalWasmPolicy`, and every command advertised by a target must have the
+required callable surface on the driver.
+
+`createLoweringPlan` consumes the versioned provider-plan projection rather
+than compiler metadata. `writeTarget` and `inspectRealization` consume the
+versioned target invocation rather than `{ compiled, metadata, plan, native,
+...options }`. Return normalized versioned data; do not return a compiler
+object, provider implementation, mutable manifest, or unaudited Wasm bytes.
+
+Keep concrete implementation, configuration normalization, reference fields,
+and target policy in the provider package. A project selects either a bare host
+ID or an exact scoped package name as its profile `host`; Pulse resolves only
+that package's `./toolchain` export. Adding a first-party bare host to the
+built-in support catalog still requires an architecture-reviewed release
+dependency, documentation, and acceptance change. A project-owned scoped
+provider does not.
+
+The selected toolchain executes as trusted build code in the Pulse process.
+Do not run Pulse commands against an untrusted project or dependency tree.
+
+## 7. Extend project configuration
+
+Update the public TypeScript types, config loader, normalization, and CLI override behavior. Decide whether the provider is selected by a string or a typed helper object.
+
+Document every field in the machine-readable project configuration catalog. The release gate compares that catalog with exported TypeScript interfaces, including optionality, so a field cannot be added only in code or only in prose.
+
+Cover:
+
+- defaults;
+- allowed values;
+- command-line precedence;
+- local versus deployment meaning;
+- secret and path safety;
+- related diagnostics.
+
+## 8. Extend CLI behavior and help
+
+For each command, decide and test:
+
+| Command | Provider question |
+|---|---|
+| `doctor` | What dependencies, bindings, and external tools are checked? |
+| `inspect` | What provider plan and readiness detail is emitted? |
+| `test` | Is local execution supported? |
+| `dev` | Can it serve locally and watch safely? |
+| `build` | What files are emitted, cleaned, and validated? |
+
+Update the declarative command specification when provider choices or option behavior change. Installed help and the generated CLI reference must remain in parity.
+
+## 9. Add public diagnostics
+
+Provider failures reaching the supported workflow need stable `PULSE_*` codes in the public diagnostic catalog. Typical classes include:
+
+- unsupported provider or command;
+- missing capability;
+- invalid binding map;
+- missing deployment resource mapping;
+- unavailable compiler or external CLI;
+- version mismatch;
+- target compile/serve timeout;
+- target compile/serve failure.
+
+Each public code needs summary, remediation, exit class, optional development HTTP mapping, and a generated exact-version documentation anchor.
+
+Internal proof diagnostics may remain `PULSEWASM_*`, but they must not leak as undocumented public links.
+
+## 10. Publish and classify the package
+
+When the provider is a published package:
+
+- add it to the synchronized release manifest and version set;
+- declare the support tier, audience, direct-install guidance, supported entry points, and stability in `release/pulse-release-manifest.json`;
+- ensure repository/homepage/bugs metadata is generated;
+- add a concise package README and a canonical package guide;
+- add required files to `package.json.files`;
+- verify packed relative and exact-version links;
+- test from packed tarballs without workspace links.
+
+An exported subpath is not automatically supported. List only entry points that carry an intentional compatibility promise.
+
+## 11. Test equivalence and isolation
+
+A provider is not complete after one successful request. Cover:
+
+```text
+request metadata and headers
+JSON/text/custom responses
+schema decode and encode
+single, grouped, and dependent fetch
+fetch timeout/network failure
+config and secret reads
+KV get/put
+opaque pass-through
+supported package-owned effects
+missing capability and binding failures
+continuation expiry/double-resume protection
+secret redaction
+local dev request behavior
+build output and output-path safety
+packed-package installation
+external target execution where available
+```
+
+Compare provider plans and observable canonical results with the Node conformance path where the capabilities overlap. Provider-specific target details may differ; application-visible semantics should not.
+
+## 12. Release checklist
+
+Before adding the provider to the public matrix:
+
+- The descriptor lists only implemented capabilities.
+- Every capability has local behavior and, when claimed, target behavior.
+- All required bindings fail early and clearly.
+- The driver is wired into all relevant commands.
+- Config types, normalization, generated reference, and examples agree.
+- Public diagnostics have resolvable anchors.
+- Handler source remains provider-neutral.
+- Packed-package and clean-machine tests pass.
+- External reality checks are separated from deterministic conformance tests.
+- The docs do not imply a public plugin API.
+
+## Related documentation
+
+- [Pulse-aware package authoring](./pulse-aware-packages.md)
+- [Contracts and providers](../concepts/contracts-and-providers.md)
+- [Fastly package guide](../packages/provider-fastly.md)
+- [Project configuration](../reference/project-config.md)
+- [Diagnostics](../reference/diagnostics.md)
+- [Release acceptance](../maintainers/release-acceptance.md)
+- [Package support policy](../packages/README.md)

package/docs/contributing/adding-first-party-lowerer.md

@@ -0,0 +1,327 @@
+<!-- pulse-doc-meta:start
+owner: docs-platform
+status: active
+last-reviewed: 2026-07-25
+review-by: 2027-01-25
+pulse-doc-meta:end -->
+
+# Add a first-party package-owned lowerer
+
+Start with [Pulse-aware package authoring](./pulse-aware-packages.md) to decide
+whether the package needs Native lowering at all. Ordinary target-compatible
+JavaScript packages do not require a compiler builder.
+
+> **Scope and trust boundary:** Pulse `1.0.0-beta.2` executes package-owned compiler builders only when their manifest declares `compiler.trust: 'first-party'` and the package is part of the synchronized release set. This is a core-repository contributor workflow, **not an external plugin** interface or a supported third-party plugin API. An external package cannot self-register arbitrary compiler code.
+
+A package-owned lowerer lets one release package define a narrow TypeScript facade and keep its domain-specific static validation outside compiler core. GRIP is the clearest current example; assets is the second implementation proving that the generic loader is not GRIP-specific.
+
+## What belongs where
+
+| Concern | Owner |
+|---|---|
+| Ergonomic lowerable TypeScript symbols | Feature package root, such as `packages/grip/src/index.ts` |
+| Package identity and facade-to-sidecar declaration | Feature package manifest |
+| Domain payload versions and diagnostic vocabulary | Shared contracts package |
+| AST validation and canonical effect construction | Feature package compiler builder |
+| Manifest discovery and trusted builder loading | `@pulse-compute/wasm-library-kit` |
+| Whole-project orchestration and merge with canonical effects | `@pulse-compute/wasm-compiler` |
+| Capability realization | Node/Fastly provider packages |
+| Product workflow, diagnostics, docs, release validation | `@pulse-compute/cli` and root release scripts |
+
+The central compiler may invoke and combine package plans, but it must not absorb package-specific symbol names, payload rules, or provider behavior.
+
+## End-to-end data flow
+
+```text
+application import
+  → package facade symbol
+  → package manifest discovery
+  → first-party compiler builder
+  → package contract validation
+  → canonical package effect
+  → shared provider plan
+  → Node/Fastly realization
+```
+
+## 1. Choose stable identity
+
+Define before implementation:
+
+- a contract ID, such as `pulse.grip`;
+- an npm package owner;
+- one canonical package-root import;
+- a small static symbol set;
+- canonical effect kinds and result classes;
+- the providers that can realize each operation;
+- unsupported or reserved forms and their diagnostics.
+
+Identity must have one owner. Do not duplicate contract IDs, package names, or facade symbol lists in compiler core.
+
+For a new package named `@pulse-compute/example`, a typical layout is:
+
+```text
+packages/example/
+  src/index.ts
+  pulsewasm.manifest.cjs
+  pulsewasm.compiler.cjs
+  as/index.as.ts
+  package.json
+  README.md
+  test/
+```
+
+## 2. Create a real package-root API
+
+The package root must be the application import for both JavaScript execution
+and supported Native lowering. JavaScript targets execute the real package
+implementation. The compiler recognizes a deliberately narrower set of
+package-root calls for Native targets and reports unsupported forms as
+eligibility diagnostics.
+
+Design rules:
+
+- keep the public lowerable symbol set narrow;
+- prefer literal or statically bounded arguments;
+- use the package root as `lowerableSubpath` and `facade.import`;
+- do not import a provider SDK;
+- route request-bound work through the explicit Pulse context;
+- keep pure framing or result-adoption helpers free of ambient authority;
+- keep compatibility subpaths, when they already exist, out of new authoring
+  guidance.
+
+Export the package root from `package.json` and include its built
+JavaScript/types in the packed files.
+
+## 3. Declare the package manifest
+
+The package root advertises the manifest in `package.json`:
+
+```json
+{
+  "pulsewasm": {
+    "manifest": "./pulsewasm.manifest.cjs"
+  }
+}
+```
+
+The manifest uses `pulsewasm.lowerable-library-manifest.v2` and must include:
+
+```js
+const pulseWasmManifest = Object.freeze({
+  version: 'pulsewasm.lowerable-library-manifest.v2',
+  kind: 'pulsewasm.lowerable-library-manifest',
+  contractId: 'pulse.example',
+  npmPackage: '@pulse-compute/example',
+  lowerableSubpath: '@pulse-compute/example',
+  facade: Object.freeze({
+    namespace: 'example',
+    import: '@pulse-compute/example',
+    symbols: Object.freeze(['emit']),
+  }),
+  compiler: Object.freeze({
+    version: 'pulsewasm.lowerable-compiler-builder.v1',
+    entry: './pulsewasm.compiler.cjs',
+    export: 'buildExampleLoweringPlan',
+    artifact: 'example-lowering-plan.json',
+    builderOwner: '@pulse-compute/example',
+    trust: 'first-party',
+  }),
+  modes: Object.freeze({
+    typescript: Object.freeze({ entry: './dist/index.js' }),
+    jsEngine: Object.freeze({ entry: './dist/index.js' }),
+    wasm: Object.freeze({
+      mode: 'wasm-sidecar',
+      sidecar: './as/index.as.ts',
+      lowerings: Object.freeze([
+        Object.freeze({
+          tsSymbol: 'example.emit',
+          asSymbol: 'pulse_example_emit',
+          callShape: 'literal-topic-message',
+          hostCapabilities: Object.freeze(['example']),
+        }),
+      ]),
+      hostCapabilities: Object.freeze(['example']),
+    }),
+  }),
+})
+
+module.exports = pulseWasmManifest
+```
+
+The manifest validator requires the facade, TypeScript/JS entries, sidecar, lowering list, builder protocol, entry, export, owner, and trust declaration. `compiler.builderOwner` must match `npmPackage`.
+
+Do not weaken the `first-party` check to make a local experiment load. A public plugin mechanism would require separate trust, discovery, sandboxing, version negotiation, and compatibility design.
+
+## 4. Define contract-owned schemas and diagnostics
+
+Add the operation and plan vocabulary under `wasm/packages/contracts/src/<feature>/`. Contracts should define:
+
+- contract and artifact version constants;
+- valid operation names and capabilities;
+- payload and result shapes;
+- static status vocabulary;
+- internal compiler diagnostics for invalid facade forms;
+- normalization helpers used by builder and providers.
+
+Contracts must not contain package discovery, AST traversal, provider execution, or application runtime code.
+
+Export the new contract through the contracts package’s declared subpaths and verify package exports.
+
+## 5. Implement the package compiler builder
+
+The manifest export, such as `buildExampleLoweringPlan`, receives the source, discovered manifest, library contracts, TypeScript parser, and builder ownership metadata from the generic loader.
+
+The builder should:
+
+1. collect only imports from its exact `lowerableSubpath`;
+2. classify namespace, default, and named imports intentionally;
+3. match supported call placements;
+4. validate literals and object options with contract-owned rules;
+5. emit source-located diagnostics for unsupported forms;
+6. construct canonical package effects;
+7. return a versioned package plan and summary;
+8. avoid provider-specific lowering names or runtime calls.
+
+A canonical package effect needs enough information for the shared provider contract:
+
+```js
+{
+  version: 'pulse.canonical-package-effect.v1',
+  contractId: 'pulse.example',
+  package: '@pulse-compute/example',
+  import: '@pulse-compute/example',
+  kind: 'example.emit',
+  providerKind: 'example',
+  operation: 'emit',
+  capability: 'example.emit',
+  result: 'ack',
+  resource: { kind: 'literal', value: 'updates' },
+  payload: { topic: 'updates', message: 'ready' },
+  loc: { file: 'src/index.ts', line: 4, column: 3 },
+}
+```
+
+Keep domain rules in the builder. The generic loader is intentionally free of strings such as `grip.hold` or `assets.lookup`.
+
+## 6. Add the sidecar contract when compiled Wasm needs one
+
+The manifest’s sidecar source exports stable symbols and delegates to stable host imports. It is an ABI boundary, not the place to reimplement the package compiler.
+
+For each manifest lowering:
+
+- export the declared `asSymbol`;
+- keep arguments/results deterministic and versioned;
+- map to named host capabilities;
+- add compile/link tests;
+- prove packed-package discovery, not only monorepo source resolution.
+
+A sidecar can be a readiness/ABI surface even when provider execution is implemented elsewhere. Document that status explicitly.
+
+## 7. Verify generic discovery
+
+The reachable module graph selects participating package contracts and tracks
+package-root symbols through supported imports and re-exports. The compiler
+then recognizes operations in each reachable project module. The generic
+library kit resolves the selected first-party manifest from the synchronized
+workspace or exact installed package and invokes its declared builder.
+
+This is not entry-source substring discovery. An installed dependency is not
+participating merely because it has a manifest, and a package cannot
+self-register compiler code. The detailed owner and pipeline map lives in the
+[package lowerer contract reference](./package-lowerer-contract.md).
+
+Add tests proving:
+
+- the manifest validates;
+- the package exports its lowerable facade, manifest, and compiler-builder subpaths as intended;
+- `package.json.files` includes the manifest, builder, sidecar, and built facade;
+- discovery works from an isolated `node_modules`-style packed package;
+- a reachable import or supported project re-export selects the package contract;
+- an installed but unreachable lowerable package is not selected;
+- the generic loader resolves the manifest-declared builder export;
+- compiler core does not hard-code the new package import or symbol names.
+
+Do not rely only on workspace symlinks.
+
+## 8. Add provider realization
+
+A package effect is not usable until each advertised provider maps its capabilities. For every supported provider:
+
+- add capabilities to its descriptor;
+- add stable lowering names;
+- normalize required bindings;
+- implement local conformance behavior;
+- implement target/build behavior where applicable;
+- fail with a public diagnostic when required bindings are absent;
+- preserve `providerSpecificUserland: false` and `providerSdkUserland: false`.
+
+A provider that cannot implement the capability should reject it during provider-plan creation, not at an arbitrary later request branch.
+
+## 9. Add public diagnostics and documentation
+
+Internal `PULSEWASM_*` builder diagnostics are useful for proof lanes but are not automatically public CLI codes. Any failure that can reach application authors through the supported workflow needs an entry in the public diagnostic catalog with title, summary, remediation, exit class, HTTP mapping where applicable, and a generated anchor.
+
+Update:
+
+- the feature package README;
+- [Package support policy](../packages/README.md) when the package is published or its supported entries change;
+- a package guide under `docs/packages/`;
+- concept or tutorial pages that introduce the capability;
+- project configuration reference when new bindings are public;
+- the environment reference only for genuine process-level inputs.
+
+Public examples must use canonical handlers and the normal `pulse` workflow.
+
+## 10. Required verification
+
+At minimum, cover:
+
+```text
+positive static lowering
+negative dynamic/literal validation
+manifest schema validation
+builder owner/trust validation
+normal-JavaScript facade failure
+canonical effect shape
+provider capability plan
+Node local conformance when supported
+Fastly local and compiled target behavior when supported
+packed package discovery
+package export and tarball contents
+documentation links and source-bound snippets
+```
+
+Run the repository’s focused tests first, then the release gates:
+
+```bash
+pnpm docs:check
+pnpm wasm:test:unit
+pnpm wasm:test:native
+pnpm wasm:test:providers
+npm run release:seal
+```
+
+Exact script names may evolve; the authoritative profiles are described in [Testing](../maintainers/testing.md).
+
+## Review checklist
+
+A lowerer is ready for the synchronized release only when all answers are yes:
+
+- Does the feature package own its facade, manifest, and builder?
+- Does a shared contract own payload/version semantics?
+- Is the builder explicitly first-party and owner-matched?
+- Does compiler core remain free of feature-specific AST rules?
+- Are all advertised providers capable and bound?
+- Does ordinary JavaScript execution use the real package implementation?
+- Does packed dependency discovery work without workspace paths?
+- Are public failures catalogued and documented?
+- Is the Beta boundary narrower than or equal to what tests prove?
+
+## Related documentation
+
+- [Pulse-aware package authoring](./pulse-aware-packages.md)
+- [Compilation and lowering](../concepts/compilation-and-lowering.md)
+- [Contracts and providers](../concepts/contracts-and-providers.md)
+- [GRIP package guide](../packages/grip.md)
+- [Assets package guide](../packages/assets.md)
+- [Implementation packages](../packages/implementation-packages.md)