@effectstream/orchestrator 0.100.14 → 0.100.16

package/README.md

@@ -0,0 +1,123 @@
+# @effectstream/orchestrator
+
+A multi-chain local development environment for EffectStream. One CLI
+starts every dependency a template needs — Postgres / PgLite, Hardhat,
+contracts, Bitcoin Core, Midnight node + indexer + proof server,
+Cardano-side services, Avail node + light client, NEAR sandbox,
+Celestia, plus the EffectStream sync + runtime + batcher — in the right
+order, with health checks.
+
+- One CLI that starts every dependency a template needs: DB, chains, sync, runtime, batcher.
+- Dependency-graph aware: runs in parallel where it can, sequential where it must.
+- Disable any chain with `DISABLE_EVM=true`, `DISABLE_BITCOIN=true`, ...
+- Used by every template in this repo and by the E2E runner.
+
+## Install
+
+```bash
+bun add @effectstream/orchestrator
+# or
+npm install @effectstream/orchestrator
+```
+
+## Standalone usage
+
+The orchestrator is mostly invoked as a CLI from a template's repo
+root:
+
+```bash
+# Start every process defined in orchestrator.config.ts (or .json)
+bun packages/build-tools/orchestrator/src/cli.ts start
+
+# Show what's running and the health of each
+bun packages/build-tools/orchestrator/src/cli.ts status
+
+# Stop everything
+bun packages/build-tools/orchestrator/src/cli.ts stop
+```
+
+Each process is declared in an `OrchestratorConfig` object: its command,
+working directory, environment, the ports/endpoints to watch for
+readiness, and which other processes it depends on. Then the
+orchestrator builds the dependency graph and runs them in parallel where
+possible.
+
+```typescript
+import type { OrchestratorConfig } from "@effectstream/orchestrator/config";
+
+export const config: OrchestratorConfig = {
+  processes: [
+    {
+      name: "pglite",
+      command: ["bun", "run", "@effectstream/db/start-pglite"],
+      readiness: { tcp: { port: 5432 } },
+    },
+    {
+      name: "hardhat",
+      command: ["bun", "run", "hardhat", "node"],
+      readiness: { http: { url: "http://127.0.0.1:8545" } },
+    },
+    {
+      name: "deploy-contracts",
+      command: ["bun", "scripts/deploy.ts"],
+      dependsOn: ["hardhat"],
+    },
+    // …
+  ],
+};
+```
+
+Common chain launchers ship as subpath scripts you can compose: `./launch-pglite`,
+`./launch-evm`, `./launch-bitcoin`, `./launch-cardano`, `./launch-midnight`,
+`./launch-avail`, `./launch-near`. Each wraps a pinned binary from a
+package under `packages/binaries/` (e.g. `@effectstream/npm-midnight-node`,
+`@effectstream/bitcoin-core`, `@effectstream/near-sandbox`) with sensible
+defaults.
+
+> **Tip:** Disable chains you don't need with env vars: `DISABLE_EVM=true`,
+> `DISABLE_BITCOIN=true`, `DISABLE_MIDNIGHT=true`, etc. Same flags work for
+> the orchestrator and `e2e/runner.ts`.
+
+## CLI reference
+
+```
+orchestrator start   [config]    Start processes (daemonised, exposes HTTP API)
+orchestrator status              Show process status
+orchestrator restart <name>      Restart a named process
+orchestrator stop    [name]      Stop a named process, or all
+orchestrator list    [config]    List processes without starting
+orchestrator silence <name...>   Suppress terminal output for named processes
+orchestrator unsilence <name...> Resume terminal output
+orchestrator logs   [name...]    Follow background daemon log files
+
+Global flags:
+  --port <n>        Orchestrator API port (default: 4747)
+```
+
+## Inside EffectStream
+
+Every template under
+[`templates/`](https://github.com/effectstream/effectstream/tree/main/templates)
+defines an `orchestrator.config.ts` (or `.json`) and starts dev with one
+command. The E2E runner at
+[`e2e/runner.ts`](https://github.com/effectstream/effectstream/blob/main/e2e/runner.ts)
+is the same machinery, serialised across nine chain suites.
+
+## Key subpath exports
+
+- `@effectstream/orchestrator/config` — `OrchestratorConfig`, `ProcessConfig` types.
+- `@effectstream/orchestrator/resolve-package` — resolve a package's bin to an absolute path (used by launcher scripts).
+- `@effectstream/orchestrator/launch-pglite`, `./launch-evm`, `./launch-bitcoin`, `./launch-cardano`, `./launch-midnight`, `./launch-avail`, `./launch-near` — opinionated launcher scripts for each chain.
+- `@effectstream/orchestrator/wait-tcp`, `./wait-http` — readiness-check helpers.
+
+## Examples
+
+- Templates: every directory under [`templates/`](https://github.com/effectstream/effectstream/tree/main/templates) ships a working orchestrator config.
+- E2E: [`e2e/`](https://github.com/effectstream/effectstream/tree/main/e2e) drives the orchestrator under the hood.
+
+Runnable: [`test/examples.test.ts`](./test/examples.test.ts).
+
+## Links
+
+- Docs: https://effectstream.github.io/docs/packages/tools/orchestrator
+- Source: https://github.com/effectstream/effectstream/tree/main/packages/build-tools/orchestrator

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effectstream/orchestrator",
-  "version": "0.100.14",
+  "version": "0.100.16",
   "license": "MIT",
   "homepage": "https://effectstream.github.io/docs/",
   "repository": {
@@ -20,6 +20,7 @@
     "./launch-cardano": "./scripts/launch-cardano.ts",
     "./launch-midnight": "./scripts/launch-midnight.ts",
     "./launch-avail": "./scripts/launch-avail.ts",
+    "./launch-celestia": "./scripts/launch-celestia.ts",
     "./launch-near": "./scripts/launch-near.ts",
     "./wait-tcp": "./scripts/wait-tcp.ts",
     "./wait-http": "./scripts/wait-http.ts"
@@ -31,7 +32,7 @@
     "start": "bun src/cli.ts start"
   },
   "dependencies": {
-    "@effectstream/db": "0.100.14"
+    "@effectstream/db": "0.100.16"
   },
   "description": "Multi-chain local development environment for EffectStream"
 }

package/scripts/launch-celestia.ts

@@ -0,0 +1,67 @@
+import type { ProcessConfig } from "../src/config.ts";
+import { resolvePackageDir, type ResolveLocation } from "./resolve-package.ts";
+
+export const CelestiaNames = {
+  CLEAN:       "celestia-clean",
+  DEVNET:      "celestia-devnet",
+  BRIDGE_WAIT: "celestia-bridge-wait",
+  FUND:        "celestia-fund-bridge",
+} as const;
+
+const REQUIRED_SCRIPTS = {
+  "celestia-bridge:start": "Start the Celestia consensus node + bridge",
+  "celestia-bridge:wait":  "Wait for the Celestia bridge RPC to be ready",
+  "celestia-fund:bridge":  "Fund the bridge node wallet with tokens",
+} as const;
+
+export function launchCelestia(
+  packageName: string,
+  location: ResolveLocation,
+  opts?: { ports?: number[]; home?: string },
+): ProcessConfig[] {
+  const cwd   = resolvePackageDir("launchCelestia", packageName, location, REQUIRED_SCRIPTS);
+  const ports = opts?.ports ?? [26657, 26658];
+  const home  = opts?.home  ?? "/tmp/celestia-home";
+
+  const cleanScript =
+    `await import('fs').then(fs => { try { fs.rmSync('${home}', { recursive: true, force: true }); } catch {} }); console.log('Celestia home cleaned');`;
+
+  return [
+    {
+      name: CelestiaNames.CLEAN,
+      description: "Remove stale Celestia devnet data",
+      args: ["-e", cleanScript],
+      waitToExit: true,
+    },
+    {
+      name: CelestiaNames.DEVNET,
+      description: `Celestia consensus node + bridge (${packageName} celestia-bridge:start)`,
+      cwd,
+      stopProcessAtPort: ports,
+      args: ["run", "celestia-bridge:start"],
+      env: { CELESTIA_HOME: home, CELESTIA_FORCE_NO_BBR: "1" },
+      waitToExit: false,
+      critical: true,
+      silent: true,
+      dependsOn: [CelestiaNames.CLEAN],
+    },
+    {
+      name: CelestiaNames.BRIDGE_WAIT,
+      description: `Wait for Celestia bridge RPC (${packageName} celestia-bridge:wait)`,
+      cwd,
+      args: ["run", "celestia-bridge:wait"],
+      waitToExit: true,
+      dependsOn: [CelestiaNames.DEVNET],
+    },
+    {
+      name: CelestiaNames.FUND,
+      description: `Fund the Celestia bridge wallet (${packageName} celestia-fund:bridge)`,
+      cwd,
+      args: ["run", "celestia-fund:bridge"],
+      env: { CELESTIA_HOME: home },
+      waitToExit: true,
+      critical: true,
+      dependsOn: [CelestiaNames.BRIDGE_WAIT],
+    },
+  ];
+}

package/test/examples.test.ts

@@ -0,0 +1,32 @@
+// Examples for the README — verify the public surface resolves.
+
+import { test, expect } from "bun:test";
+import type { OrchestratorConfig, ProcessConfig } from "../src/config.ts";
+
+test("README: OrchestratorConfig + ProcessConfig types compose into a valid object", () => {
+  const config: OrchestratorConfig = {
+    processes: [
+      {
+        name: "pglite",
+        command: ["bun", "run", "@effectstream/db/start-pglite"],
+        readiness: { tcp: { port: 5432 } },
+      },
+      {
+        name: "hardhat",
+        command: ["bun", "run", "hardhat", "node"],
+        readiness: { http: { url: "http://127.0.0.1:8545" } },
+      },
+      {
+        name: "deploy-contracts",
+        command: ["bun", "scripts/deploy.ts"],
+        dependsOn: ["hardhat"],
+      },
+    ],
+  };
+
+  expect(config.processes.length).toBe(3);
+  expect(config.processes[0].name).toBe("pglite");
+
+  const proc: ProcessConfig = config.processes[1];
+  expect(proc.name).toBe("hardhat");
+});