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

package/README.md

@@ -1,3 +1,73 @@
 # @pulse-compute/cli
 
-This is an inert namespace-bootstrap package. It contains no executable code.
+<!-- pulse-package-status:start -->
+> **Support tier:** Canonical application surface<br>
+> **Audience:** Pulse application authors, CI workflows, and tooling integrations.<br>
+> **Install directly:** Yes. Install the package globally or as a project development dependency.<br>
+> **Supported entry points:** `pulse binary`, `@pulse-compute/cli`, `@pulse-compute/cli/workflow`, `@pulse-compute/cli/project-config`, `@pulse-compute/cli/project-execution`, `@pulse-compute/cli/project-config-schema`, `@pulse-compute/cli/diagnostics`, `@pulse-compute/cli/project-config.schema.json`, `@pulse-compute/cli/cli-spec.json`, `@pulse-compute/cli/release-manifest.json`, `@pulse-compute/cli/documentation-versions.json`, `@pulse-compute/cli/documentation-site.json`<br>
+> **Stability:** Supported Beta workflow and project-configuration contract.<br>
+> **npm:** [`@pulse-compute/cli`](https://www.npmjs.com/package/@pulse-compute/cli)<br>
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.2/packages/cli/)
+>
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.2` package policy.
+<!-- pulse-package-status:end -->
+
+The public CLI and conventional `@pulse-compute/pulse` application root are
+both part of the synchronized `1.0.0-beta.2` release set. Validate the generated
+workflow from the repository or the exact packed acceptance set:
+
+```bash
+pnpm pulse -- init ./my-app
+cd ./my-app
+npm install
+pulse doctor
+pulse test
+pulse inspect
+pulse dev
+pulse build
+```
+
+`pulse init` writes exact catalog package versions and does not invoke a package manager. Project commands discover one authoritative `.pulse/config.ts` workspace, select a flat profile, compile the same canonical handler contract, and realize Node, Fastly, or compile-only `none`.
+
+## Supported programmatic entries
+
+- package root for `defineConfig`, public types, diagnostics, and workflow integration;
+- `workflow` for command parsing/execution;
+- `project-config` for discovery and normalization;
+- `project-execution` for canonical command orchestration;
+- `diagnostics` for stable public descriptors and mappings.
+
+Repository fixture/profile/task flags are not part of installed help or the public contract.
+
+## JavaScript support and eligibility
+
+Profiles may select `target: 'javascript'` with either the Node or Fastly
+provider. Both targets execute the live Router/context and package
+implementations, and both satisfy their declared full-target-support gates.
+
+`pulse inspect` and `pulse doctor` expose general target availability separately
+from deterministic project eligibility and loader observations. `pulse test`
+and `pulse dev` execute only when the reachable application, capabilities,
+provider requirements, and packages are eligible. Fastly identifies this local
+mode as provider emulation; it is not Node-provider fallback.
+
+`pulse compile` remains provider-neutral while recording the configured
+JavaScript target and static eligibility evidence in `pulse-compile.json`.
+`pulse build` emits a deterministic Node or Fastly source package. Fastly output
+also carries exact downstream compiler pins and deployment-candidate metadata;
+the release gate compiles that closure to a runtime Wasm without deploying or
+publishing it. Pending or blocked projects never switch to Native execution:
+`automaticFallback` is always false.
+
+## Included documentation
+
+- [Documentation index](./docs/README.md)
+- [Package guide](./docs/packages/cli.md)
+- [CLI reference](./docs/reference/cli.md)
+- [Project configuration](./docs/reference/project-config.md)
+- [Diagnostics](./docs/reference/diagnostics.md)
+- [Environment variables](./docs/reference/environment.md)
+- [Canonical API](./API.md)
+- [Runnable examples](./examples/README.md)
+
+These references and examples ship in the npm tarball and are checked after packing.

package/bin/pulse.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+'use strict';
+
+const { runPulseWorkflowCli } = require('../src/workflow.js');
+
+runPulseWorkflowCli(process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdout: process.stdout,
+  stderr: process.stderr
+}).then((result) => {
+  process.exitCode = result.status || 0;
+}).catch((error) => {
+  process.stderr.write(`${error && error.stack ? error.stack : String(error)}\n`);
+  process.exitCode = 1;
+});

package/bin/pulsewasm-extract.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('node:path');
+const { runCli } = require('@pulse-compute/wasm-compiler/cli');
+const { getDefaultArtifactsDir } = require('@pulse-compute/wasm-build-support/artifacts-dir');
+const compilerRoot = path.resolve(require.resolve('@pulse-compute/wasm-compiler'), '..', '..');
+const providerProofs = require(path.join(compilerRoot, 'bin', 'provider-proof-composition.js'));
+
+runCli(process.argv.slice(2), {
+  cwd: process.cwd(),
+  stdout: process.stdout,
+  stderr: process.stderr,
+  defaultOutDir: getDefaultArtifactsDir(process.cwd()),
+  providerProofs,
+  exitOnComplete: true
+}).then(() => {
+  process.exit(process.exitCode || 0);
+}).catch((error) => {
+  process.stderr.write(`${error && error.stack ? error.stack : String(error)}\n`);
+  process.exit(1);
+});

package/cli-spec.json

@@ -0,0 +1,575 @@
+{
+  "schemaVersion": "pulse.cli-command-spec.v5",
+  "cliVersion": "1.0.0-beta.2",
+  "completionShells": [
+    "bash",
+    "zsh",
+    "fish"
+  ],
+  "metaInvocations": [
+    {
+      "syntax": "pulse --help | pulse -h | pulse help",
+      "description": "Print public help."
+    },
+    {
+      "syntax": "pulse --version | pulse -v | pulse version",
+      "description": "Print the installed CLI package version."
+    },
+    {
+      "syntax": "pulse completion <bash|zsh|fish>",
+      "description": "Print a shell completion script generated from the public command specification."
+    }
+  ],
+  "globalOptions": [
+    {
+      "id": "help",
+      "key": "help",
+      "flags": [
+        {
+          "name": "--help"
+        },
+        {
+          "name": "-h"
+        }
+      ],
+      "kind": "boolean",
+      "description": "Print public CLI help and exit."
+    },
+    {
+      "id": "json",
+      "key": "json",
+      "flags": [
+        {
+          "name": "--json"
+        }
+      ],
+      "kind": "boolean",
+      "description": "Emit machine-readable JSON. pulse dev emits one JSON event per line."
+    },
+    {
+      "id": "dry-run",
+      "key": "dryRun",
+      "flags": [
+        {
+          "name": "--dry-run"
+        },
+        {
+          "name": "--plan"
+        }
+      ],
+      "kind": "boolean",
+      "description": "Resolve and report the command plan without executing it."
+    }
+  ],
+  "commands": [
+    {
+      "name": "init",
+      "summary": "Create a conventional .pulse workspace with an async Pulse application and dedicated test harness.",
+      "usage": [
+        "pulse init [directory] [--name <package-name>] [--force]"
+      ],
+      "positionals": [
+        {
+          "name": "directory",
+          "key": "target",
+          "description": "Target directory. Defaults to the current directory."
+        }
+      ],
+      "options": [
+        {
+          "id": "force",
+          "key": "force",
+          "flags": [
+            {
+              "name": "--force"
+            }
+          ],
+          "kind": "boolean",
+          "description": "Allow generated files to replace entries in a non-empty target directory."
+        },
+        {
+          "id": "name",
+          "key": "name",
+          "flags": [
+            {
+              "name": "--name"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<package-name>",
+          "description": "Set the generated npm package name."
+        }
+      ],
+      "examples": [
+        "pulse init ./my-pulse-app",
+        "pulse init ./edge-app --name @example/edge-app"
+      ],
+      "diagnostics": [
+        "PULSE_INIT_NOT_EMPTY",
+        "PULSE_INIT_FILE_EXISTS",
+        "PULSE_PROVIDER_UNSUPPORTED"
+      ],
+      "outputs": [
+        "Human output lists generated files and next steps.",
+        "With --json, emits one initialization result object."
+      ],
+      "sideEffects": [
+        "Creates .pulse/config.ts, an async Pulse application, a dedicated test harness, package scripts, and documentation.",
+        "Does not install dependencies or run npm, pnpm, or any network operation."
+      ],
+      "exit": "0 on success; 2 for invalid usage, provider selection, or unsafe overwrite conditions."
+    },
+    {
+      "name": "doctor",
+      "summary": "Audit project shape, compilation, schemas, provider bindings, output safety, and required tools.",
+      "usage": [
+        "pulse doctor [directory] [--profile <name>] [--strict]"
+      ],
+      "positionals": [
+        {
+          "name": "directory",
+          "key": "directory",
+          "description": "Project discovery start. Defaults to the current directory."
+        }
+      ],
+      "options": [
+        {
+          "id": "strict",
+          "key": "strict",
+          "flags": [
+            {
+              "name": "--strict"
+            }
+          ],
+          "kind": "boolean",
+          "description": "Treat doctor warnings as failed checks."
+        },
+        {
+          "id": "profile",
+          "key": "profile",
+          "flags": [
+            {
+              "name": "--profile"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<profile>",
+          "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile."
+        }
+      ],
+      "examples": [
+        "pulse doctor ./my-pulse-app",
+        "pulse doctor ./edge-app --strict --json"
+      ],
+      "diagnostics": [
+        "PULSE_CONFIG_NOT_FOUND",
+        "PULSE_PROJECT_COMPILE_FAILED",
+        "PULSE_NODE_VERSION_UNSUPPORTED",
+        "PULSE_CANONICAL_NATIVE_COMPILE_FAILED"
+      ],
+      "outputs": [
+        "Human output prints every check.",
+        "With --json, emits one completed audit object including failed and warning checks."
+      ],
+      "sideEffects": [
+        "Reads and compiles the project.",
+        "Does not write the build output."
+      ],
+      "exit": "0 when the audit passes; 1 when a completed audit contains failed checks; 2–5 only when the audit command itself cannot be completed."
+    },
+    {
+      "name": "inspect",
+      "summary": "Report canonical compiler, schema, effect, continuation, capability, provider, and build-mode details.",
+      "usage": [
+        "pulse inspect [directory] [--profile <name>]",
+        "pulse inspect --artifact <file.json>"
+      ],
+      "positionals": [
+        {
+          "name": "directory",
+          "key": "directory",
+          "description": "Project discovery start. Defaults to the current directory."
+        }
+      ],
+      "options": [
+        {
+          "id": "profile",
+          "key": "profile",
+          "flags": [
+            {
+              "name": "--profile"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<profile>",
+          "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile."
+        },
+        {
+          "id": "artifact",
+          "key": "artifact",
+          "flags": [
+            {
+              "name": "--artifact"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<file.json>",
+          "description": "Inspect an existing JSON build or compiler artifact instead of a project."
+        }
+      ],
+      "examples": [
+        "pulse inspect ./my-pulse-app --json",
+        "pulse inspect --artifact ./dist/pulse-build.json"
+      ],
+      "diagnostics": [
+        "PULSE_CONFIG_NOT_FOUND",
+        "PULSE_PROJECT_COMPILE_FAILED",
+        "PULSE_CANONICAL_COMPILE_FAILED"
+      ],
+      "outputs": [
+        "Human output prints a compact project/compiler summary.",
+        "With --json, emits one inspection or artifact object."
+      ],
+      "sideEffects": [
+        "Compiles and validates the project in memory.",
+        "Does not write the build output."
+      ],
+      "exit": "0 on success; 2–5 according to the emitted stable diagnostic."
+    },
+    {
+      "name": "test",
+      "summary": "Run configured cases through the selected provider local-conformance runtime.",
+      "usage": [
+        "pulse test [directory] [--profile <name>] [--case <name>]"
+      ],
+      "positionals": [
+        {
+          "name": "directory",
+          "key": "directory",
+          "description": "Project discovery start. Defaults to the current directory."
+        }
+      ],
+      "options": [
+        {
+          "id": "profile",
+          "key": "profile",
+          "flags": [
+            {
+              "name": "--profile"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<profile>",
+          "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile."
+        },
+        {
+          "id": "case",
+          "key": "caseName",
+          "flags": [
+            {
+              "name": "--case"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<name>",
+          "description": "Run one named project test case."
+        }
+      ],
+      "examples": [
+        "pulse test ./my-pulse-app",
+        "pulse test ./my-pulse-app --case smoke --json"
+      ],
+      "diagnostics": [
+        "PULSE_TEST_PROVIDER_REQUIRED",
+        "PULSE_PROVIDER_CAPABILITY_MISSING",
+        "PULSE_SCHEMA_DECODE"
+      ],
+      "outputs": [
+        "Human output uses TAP-like case lines and a summary.",
+        "With --json, emits one test-run object; expected stable errors remain inside their case results."
+      ],
+      "sideEffects": [
+        "Compiles the project and executes configured deterministic or live fixtures.",
+        "Does not write the build output."
+      ],
+      "exit": "0 when all selected cases pass; 1 when the completed test run has failed cases; 2–5 when setup, compilation, runtime, or toolchain execution fails before a normal result."
+    },
+    {
+      "name": "dev",
+      "summary": "Start the foreground local server with the selected provider conformance runtime.",
+      "usage": [
+        "pulse dev [directory] [--profile <name>] [--host <host>] [--port <port>] [--watch|--no-watch] [--once]"
+      ],
+      "positionals": [
+        {
+          "name": "directory",
+          "key": "directory",
+          "description": "Project discovery start. Defaults to the current directory."
+        }
+      ],
+      "options": [
+        {
+          "id": "once",
+          "key": "once",
+          "flags": [
+            {
+              "name": "--once"
+            }
+          ],
+          "kind": "boolean",
+          "description": "Close the development server after the first completed request."
+        },
+        {
+          "id": "watch",
+          "key": "watch",
+          "flags": [
+            {
+              "name": "--watch",
+              "value": true
+            },
+            {
+              "name": "--no-watch",
+              "value": false
+            }
+          ],
+          "kind": "boolean-value",
+          "description": "Enable or disable entry and schema dependency watching. Watching is enabled by default."
+        },
+        {
+          "id": "profile",
+          "key": "profile",
+          "flags": [
+            {
+              "name": "--profile"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<profile>",
+          "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile."
+        },
+        {
+          "id": "host",
+          "key": "host",
+          "flags": [
+            {
+              "name": "--host"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<host>",
+          "description": "Override the development listen host."
+        },
+        {
+          "id": "port",
+          "key": "port",
+          "flags": [
+            {
+              "name": "--port"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<port>",
+          "description": "Override the development listen port. Use 0 to request an ephemeral port."
+        }
+      ],
+      "examples": [
+        "pulse dev ./my-pulse-app",
+        "pulse dev ./my-pulse-app --port 0 --once --json"
+      ],
+      "diagnostics": [
+        "PULSE_DEV_PROVIDER_UNSUPPORTED",
+        "PULSE_REQUEST_BODY_TOO_LARGE",
+        "PULSE_FETCH_NETWORK"
+      ],
+      "outputs": [
+        "Human output reports the ready URL and reload or error messages.",
+        "With --json, stdout is newline-delimited JSON events: compiled, ready, reloaded, request, compile-error, and request-error. It is not one enclosing JSON document."
+      ],
+      "sideEffects": [
+        "Binds a foreground HTTP listener.",
+        "Watches the entry and schema dependency graph by default.",
+        "Configuration-file changes require restarting the command."
+      ],
+      "exit": "0 after a normal server close; 2–5 when setup, compilation, provider, runtime, or toolchain initialization fails."
+    },
+    {
+      "name": "compile",
+      "summary": "Compile the canonical project into provider-neutral Pulse-owned WebAssembly.",
+      "usage": [
+        "pulse compile [directory] [--profile <name>] [--out <dir>] [--clean|--no-clean] [--experimental-native-size]"
+      ],
+      "positionals": [
+        {
+          "name": "directory",
+          "key": "directory",
+          "description": "Project discovery start. Defaults to the current directory."
+        }
+      ],
+      "options": [
+        {
+          "id": "clean",
+          "key": "clean",
+          "flags": [
+            {
+              "name": "--clean",
+              "value": true
+            },
+            {
+              "name": "--no-clean",
+              "value": false
+            }
+          ],
+          "kind": "boolean-value",
+          "description": "Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default."
+        },
+        {
+          "id": "experimental-native-size",
+          "key": "experimentalNativeSize",
+          "flags": [
+            {
+              "name": "--experimental-native-size"
+            }
+          ],
+          "kind": "boolean",
+          "description": "Experimentally optimize Native Wasm for size. JavaScript build targets reject this flag."
+        },
+        {
+          "id": "profile",
+          "key": "profile",
+          "flags": [
+            {
+              "name": "--profile"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<profile>",
+          "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile."
+        },
+        {
+          "id": "out",
+          "key": "outDir",
+          "flags": [
+            {
+              "name": "--out"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<dir>",
+          "description": "Override the project-relative artifact output directory."
+        }
+      ],
+      "examples": [
+        "pulse compile ./my-pulse-app",
+        "pulse compile ./edge-app --out ./dist --json",
+        "pulse compile ./edge-app --experimental-native-size"
+      ],
+      "diagnostics": [
+        "PULSE_BUILD_OUT_UNSAFE",
+        "PULSE_CANONICAL_NATIVE_PLAN_FAILED",
+        "PULSE_CANONICAL_NATIVE_COMPILE_FAILED"
+      ],
+      "outputs": [
+        "Writes pulse-compile.json, the canonical program, native plan, generated AssemblyScript, compact Wasm, WAT, and native manifest.",
+        "The output is provider-neutral and does not package a deployment provider runtime.",
+        "Experimental size builds record the exact non-default Native compiler optimization settings.",
+        "With --json, emits one compile result object containing exact artifact paths and native metadata."
+      ],
+      "sideEffects": [
+        "Cleans the output directory by default.",
+        "Invokes the lockfile-pinned AssemblyScript compiler.",
+        "Refuses absolute, parent-traversal, and symbolic-link traversal outside the project root."
+      ],
+      "exit": "0 on success; 2–5 according to the emitted stable diagnostic."
+    },
+    {
+      "name": "build",
+      "summary": "Compile the canonical project and realize the deployment provider selected by the active project profile.",
+      "usage": [
+        "pulse build [directory] [--profile <name>] [--out <dir>] [--clean|--no-clean] [--experimental-native-size]"
+      ],
+      "positionals": [
+        {
+          "name": "directory",
+          "key": "directory",
+          "description": "Project discovery start. Defaults to the current directory."
+        }
+      ],
+      "options": [
+        {
+          "id": "clean",
+          "key": "clean",
+          "flags": [
+            {
+              "name": "--clean",
+              "value": true
+            },
+            {
+              "name": "--no-clean",
+              "value": false
+            }
+          ],
+          "kind": "boolean-value",
+          "description": "Remove or preserve the selected output directory before writing artifacts. Cleaning is enabled by default."
+        },
+        {
+          "id": "experimental-native-size",
+          "key": "experimentalNativeSize",
+          "flags": [
+            {
+              "name": "--experimental-native-size"
+            }
+          ],
+          "kind": "boolean",
+          "description": "Experimentally optimize Native Wasm for size. JavaScript build targets reject this flag."
+        },
+        {
+          "id": "profile",
+          "key": "profile",
+          "flags": [
+            {
+              "name": "--profile"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<profile>",
+          "description": "Select a project profile. Precedence: --profile, PULSE_PROFILE, pulse.defaultProfile."
+        },
+        {
+          "id": "out",
+          "key": "outDir",
+          "flags": [
+            {
+              "name": "--out"
+            }
+          ],
+          "kind": "value",
+          "valueName": "<dir>",
+          "description": "Override the project-relative artifact output directory."
+        }
+      ],
+      "examples": [
+        "pulse build ./my-pulse-app",
+        "pulse build ./edge-app --out ./dist --json",
+        "pulse build ./edge-app --experimental-native-size"
+      ],
+      "diagnostics": [
+        "PULSE_BUILD_OUT_UNSAFE",
+        "PULSE_BUILD_PROVIDER_REQUIRED",
+        "PULSE_EXPERIMENTAL_NATIVE_SIZE_UNSUPPORTED",
+        "PULSE_CANONICAL_NATIVE_COMPILE_FAILED"
+      ],
+      "outputs": [
+        "Writes pulse-build.json, the provider-neutral native module, and the configured provider realization.",
+        "Fastly builds write generated AssemblyScript and direct-host-ABI native Wasm at bin/main.wasm; no JavaScript runtime image is packaged.",
+        "Experimental size builds record the exact non-default Native compiler optimization settings in portable, provider, and build metadata.",
+        "With --json, emits one build result object containing exact portable and provider artifact paths."
+      ],
+      "sideEffects": [
+        "Cleans the output directory by default.",
+        "Invokes the native compiler and configured provider realization.",
+        "Refuses absolute, parent-traversal, and symbolic-link traversal outside the project root."
+      ],
+      "exit": "0 on success; 2–5 according to the emitted stable diagnostic."
+    }
+  ]
+}