starskiff 0.0.0 → 0.4.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Wonhee Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,327 @@
+# starskiff
+
+> [!WARNING]
+> This project is under active development. APIs may change without notice until v1.0.
+
+Real Cosmos SDK nodes as ephemeral test instances — spawned as child processes, no Docker, no Kubernetes.
+
+starskiff is the lightweight skiff to [Starship](https://github.com/cosmology-tech/starship)'s heavy vessel: where Starship stands up multi-chain environments on Kubernetes, starskiff boots a single real chain node in seconds — for integration tests and CI. Not a mock; the actual Go binary.
+
+Inspired by [prool](https://github.com/wevm/prool) (test instances for Ethereum).
+
+## Features
+
+- Spawn real Cosmos SDK nodes as child processes
+- No Docker, no Kubernetes — just a Go binary
+- Genesis account injection with mnemonic recovery
+- Full lifecycle management (start/stop/restart)
+- Compatible with [@cosmjs/stargate](https://github.com/cosmos/cosmjs) and [@cosmjs/cosmwasm-stargate](https://github.com/cosmos/cosmjs) for testing
+- Extensible to any Cosmos SDK chain binary via `cosmosBase`
+
+## Instances
+
+| Instance           | Binary  | Modules                                         | Use case                     |
+| ------------------ | ------- | ----------------------------------------------- | ---------------------------- |
+| `Instance.simd()`  | `simd`  | bank, staking, gov, mint                        | Basic Cosmos SDK testing     |
+| `Instance.wasmd()` | `wasmd` | bank, staking, gov, mint, **IBC**, **CosmWasm** | Contract deploy/execute, IBC |
+
+## Install
+
+```bash
+pnpm add -D starskiff
+```
+
+### Prerequisites
+
+Install the binary for the instance you need. Requires [Go](https://go.dev/dl/) >= 1.25.
+
+**simd** (Cosmos SDK simapp):
+
+```bash
+git clone --depth 1 https://github.com/cosmos/cosmos-sdk.git /tmp/cosmos-sdk
+cd /tmp/cosmos-sdk/simapp && go build -o ~/go/bin/simd ./simd/
+```
+
+**wasmd** (CosmWasm — includes IBC):
+
+```bash
+git clone --depth 1 https://github.com/CosmWasm/wasmd.git /tmp/wasmd
+cd /tmp/wasmd && go build -o ~/go/bin/wasmd ./cmd/wasmd/
+```
+
+### Prebuilt binaries (CI)
+
+Prebuilt `linux/amd64` binaries are available in [GitHub Releases](https://github.com/2wheeh/starskiff/releases/tag/binaries/latest) for CI environments:
+
+```bash
+# Download and install (e.g. in GitHub Actions)
+gh release download "binaries/latest" --repo 2wheeh/starskiff --pattern "*.gz" --dir /tmp
+gunzip -c /tmp/simd-linux-amd64.gz > /usr/local/bin/simd
+gunzip -c /tmp/wasmd-linux-amd64.gz > /usr/local/bin/wasmd
+chmod +x /usr/local/bin/simd /usr/local/bin/wasmd
+```
+
+> For local development on macOS/Windows, build from source using the instructions above.
+
+## Usage
+
+### Basic (simd)
+
+```ts
+import { Instance } from 'starskiff';
+
+const instance = Instance.simd({
+  chainId: 'test-1',
+  denom: 'stake',
+  accounts: [
+    {
+      mnemonic: 'abandon abandon abandon ...',
+      coins: '1000000000stake',
+      name: 'alice',
+    },
+  ],
+});
+
+await instance.start();
+
+// Connect with cosmjs
+import { StargateClient } from '@cosmjs/stargate';
+const client = await StargateClient.connect(instance.rpcUrl);
+const balance = await client.getBalance(address, 'stake');
+
+await instance.stop();
+```
+
+### Test accounts
+
+Skip deriving your own dev mnemonic — `testAccounts` ships a handful of
+well-known, publicly-documented BIP39 mnemonics with addresses pre-derived
+for the `cosmos` bech32 prefix:
+
+```ts
+import { Instance, testAccounts } from 'starskiff';
+
+const [alice, bob] = testAccounts;
+
+const instance = Instance.simd({
+  chainId: 'test-1',
+  accounts: [{ mnemonic: alice.mnemonic, coins: '1000000000stake', name: alice.name }],
+});
+```
+
+These mnemonics are public — never fund them with real value. Addresses
+assume the `cosmos` prefix; chains configured with a different `prefix`
+(e.g. `osmo`, `xpla`) need addresses re-derived from the same mnemonic.
+
+### CosmWasm (wasmd)
+
+```ts
+import { Instance } from 'starskiff';
+import { SigningCosmWasmClient } from '@cosmjs/cosmwasm-stargate';
+import { GasPrice } from '@cosmjs/stargate';
+
+const instance = Instance.wasmd({
+  chainId: 'wasm-test-1',
+  accounts: [{ mnemonic: '...', coins: '1000000000stake', name: 'alice' }],
+});
+await instance.start();
+
+const client = await SigningCosmWasmClient.connectWithSigner(instance.rpcUrl, wallet, {
+  gasPrice: GasPrice.fromString('0stake'),
+});
+
+// Upload, instantiate, execute
+const { codeId } = await client.upload(address, wasmBytecode, 'auto');
+const { contractAddress } = await client.instantiate(address, codeId, initMsg, 'label', 'auto');
+const result = await client.execute(address, contractAddress, executeMsg, 'auto');
+```
+
+### vitest globalSetup (provide/inject)
+
+```ts
+// test/global-setup.ts
+import type { TestProject } from 'vitest/node';
+import { Instance } from 'starskiff';
+
+export default async function setup({ provide }: TestProject) {
+  const instance = Instance.wasmd({
+    chainId: 'test-1',
+    accounts: [{ mnemonic: '...', coins: '1000000000stake' }],
+  });
+  await instance.start();
+
+  provide('rpcUrl', instance.rpcUrl);
+
+  return () => instance.stop();
+}
+
+declare module 'vitest' {
+  export interface ProvidedContext {
+    rpcUrl: string;
+  }
+}
+```
+
+```ts
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    globalSetup: './test/global-setup.ts',
+  },
+});
+```
+
+```ts
+// test/bank.test.ts
+import { inject } from 'vitest';
+
+const rpcUrl = inject('rpcUrl');
+
+it('queries balance', async () => {
+  const client = await StargateClient.connect(rpcUrl);
+  const balance = await client.getBalance(address, 'stake');
+  // ...
+});
+```
+
+### Multi-chain
+
+Hand-assigning ports gets tedious (and error-prone) once you run more than one
+chain — use `findFreePorts()` instead:
+
+```ts
+import { findFreePorts, Instance } from 'starskiff';
+
+const [ports1, ports2] = await Promise.all([findFreePorts(), findFreePorts()]);
+
+const chain1 = Instance.wasmd({ chainId: 'wasm-1', ...ports1 });
+const chain2 = Instance.wasmd({ chainId: 'wasm-2', ...ports2 });
+
+await Promise.all([chain1.start(), chain2.start()]);
+```
+
+Each `findFreePorts()` call returns a `PortSet` of distinct, currently-free
+ports (`rpcPort`, `grpcPort`, `apiPort`, `p2pPort`, `grpcWebPort`,
+`pprofPort`). Pass `{ evm: true }` to also grab an `evmPort` for EVM-enabled
+chains (e.g. `xplad`, `evmd`). Note the TOCTOU caveat: a port is free at grab
+time, but nothing stops another process from binding it before the instance
+actually starts — rare, but possible under heavy concurrent test runs.
+
+### Custom chain binary
+
+```ts
+import { Instance, cosmosBase } from 'starskiff';
+
+// Any Cosmos SDK binary works — same init/genesis/start flow
+const gaiad = Instance.define(params => cosmosBase({ binary: 'gaiad', name: 'gaiad', ...params }));
+```
+
+## API
+
+### `Instance.simd(parameters?, options?)`
+
+Creates a simd (Cosmos SDK simapp) instance.
+
+### `Instance.wasmd(parameters?, options?)`
+
+Creates a wasmd (CosmWasm + IBC) instance. Same parameters as simd.
+
+### Parameters
+
+Shared by all instances (`CosmosChainParameters`):
+
+| Parameter          | Type              | Default           | Description        |
+| ------------------ | ----------------- | ----------------- | ------------------ |
+| `binary`           | `string`          | instance-specific | Path to binary     |
+| `chainId`          | `string`          | `"starskiff-1"`     | Chain ID           |
+| `denom`            | `string`          | `"stake"`         | Default denom      |
+| `accounts`         | `CosmosAccount[]` | `[]`              | Genesis accounts   |
+| `minimumGasPrices` | `string`          | `"0{denom}"`      | Minimum gas prices |
+| `rpcPort`          | `number`          | `26657`           | CometBFT RPC port  |
+| `grpcPort`         | `number`          | `9090`            | gRPC port          |
+| `apiPort`          | `number`          | `1317`            | REST API port      |
+| `p2pPort`          | `number`          | `26656`           | P2P port           |
+| `grpcWebPort`      | `number`          | `9091`            | gRPC-Web port      |
+| `pprofPort`        | `number`          | `6060`            | pprof port         |
+
+### Instance options (second argument)
+
+| Option          | Type     | Default | Description                        |
+| --------------- | -------- | ------- | ---------------------------------- |
+| `messageBuffer` | `number` | `20`    | Max messages to store in-memory    |
+| `timeout`       | `number` | `60000` | Start/stop timeout in milliseconds |
+
+```ts
+const instance = Instance.wasmd({ chainId: 'test-1' }, { timeout: 30_000 });
+```
+
+### Instance methods
+
+| Method                | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------- |
+| `start()`             | Start the instance. Returns a stop function.                           |
+| `stop()`              | Stop the instance and cleanup temp directory.                          |
+| `restart()`           | Stop then start.                                                       |
+| `on(event, handler)`  | Listen to events (`message`, `stdout`, `stderr`, `listening`, `exit`). |
+| `off(event, handler)` | Remove event listener.                                                 |
+
+### Instance properties
+
+| Property   | Type     | Description                                                             |
+| ---------- | -------- | ----------------------------------------------------------------------- |
+| `status`   | `string` | `idle` / `starting` / `started` / `stopping` / `stopped` / `restarting` |
+| `host`     | `string` | Host (default: `localhost`)                                             |
+| `port`     | `number` | RPC port                                                                |
+| `name`     | `string` | Instance name                                                           |
+| `messages` | `object` | `.get()` returns buffered messages, `.clear()` clears them              |
+
+### URL getters
+
+Cosmos instances (`simd`, `wasmd`, `xplad`, `evmd`, and anything built on
+`cosmosBase`) also expose ready-to-use endpoint URLs — no more manually
+templating `http://localhost:${instance.port}`:
+
+| Property  | Type     | Description                                              |
+| --------- | -------- | ---------------------------------------------------------|
+| `rpcUrl`  | `string` | `http://{host}:{port}` — CometBFT RPC endpoint            |
+| `grpcUrl` | `string` | `http://{host}:{grpcPort}` — gRPC endpoint                |
+| `apiUrl`  | `string` | `http://{host}:{apiPort}` — REST (Cosmos SDK API) endpoint |
+| `evmUrl`  | `string` | `http://{host}:{evmPort}` — EVM JSON-RPC endpoint (EVM instances only, e.g. `xplad`, `evmd`) |
+
+```ts
+const client = await StargateClient.connect(instance.rpcUrl);
+```
+
+## Testing strategies
+
+| Strategy                 | Isolation | Speed     | Use case                                    |
+| ------------------------ | --------- | --------- | ------------------------------------------- |
+| **Account isolation**    | Practical | Fast      | Most tests — each test uses unique accounts |
+| **Suite-level instance** | Full      | ~5s setup | Tests that modify chain-wide state          |
+| **Shared instance**      | None      | Fastest   | Read-only queries, smoke tests              |
+
+Recommended: fund multiple accounts in genesis, assign each test its own account(s).
+
+## Why not Starship?
+
+|              | Starship                   | starskiff              |
+| ------------ | -------------------------- | -------------------- |
+| Infra        | Kubernetes + Helm + Docker | None (child process) |
+| Startup      | 2-5 min                    | 3-5 sec              |
+| Dependencies | K8s cluster                | Go binary            |
+| State reset  | Helm redeploy (minutes)    | kill + restart (~3s) |
+| Best for     | Production simulation      | Dev/test             |
+
+## TODO
+
+- [ ] `cosmosEvmBase` — EVM JSON-RPC port support for EVM-enabled chains (e.g. xpla, evmos)
+- [ ] `starskiff.config.ts` — config-based chain + relayer declaration
+- [ ] `starskiff/vitest` — vitest plugin (automatic setup/teardown via `vitestPlugin(config)`)
+- [ ] `starskiff/playwright` — playwright plugin (`playwrightPlugin(config)`)
+- [ ] Automatic port allocation (avoid port conflicts in parallel tests)
+- [x] `findFreePorts()` utility for direct `Instance` users
+- [ ] `starskiff/setup-binaries` GitHub Action for CI binary setup
+
+## License
+
+MIT

package/dist/Instance.d.ts

@@ -0,0 +1,89 @@
+import { type Emitter } from 'mitt';
+import type { EventTypes } from './process.js';
+export { simd } from './instances/simd.js';
+export { wasmd } from './instances/wasmd.js';
+export { gaiad } from './instances/gaiad.js';
+export { xplad } from './instances/xplad.js';
+export { evmd } from './instances/evmd.js';
+export { hermes } from './instances/hermes.js';
+export type InstanceStatus = 'idle' | 'starting' | 'started' | 'stopping' | 'stopped' | 'restarting';
+/** A managed instance with lifecycle control and event emitting. */
+export type Instance = {
+    /** Host the instance is running on. */
+    host: string;
+    /** Name of the instance (e.g. "simd"). */
+    name: string;
+    /** RPC port the instance is listening on. */
+    port: number;
+    /** Current lifecycle status. */
+    status: InstanceStatus;
+    /** In-memory message buffer for debugging. */
+    messages: {
+        /** Clear all buffered messages. */
+        clear(): void;
+        /** Get all buffered messages. */
+        get(): string[];
+    };
+    /** Start the instance. Returns a stop function. */
+    start(): Promise<() => void>;
+    /** Stop the instance and clean up resources. */
+    stop(): Promise<void>;
+    /** Stop then start the instance. */
+    restart(): Promise<void>;
+    /** Subscribe to instance events (message, stdout, stderr, listening, exit). */
+    on: Emitter<EventTypes>['on'];
+    /** Unsubscribe from instance events. */
+    off: Emitter<EventTypes>['off'];
+};
+export type InstanceOptions = {
+    /** Number of messages to store in-memory. @default 20 */
+    messageBuffer?: number;
+    /** Timeout (in milliseconds) for starting and stopping. @default 60_000 */
+    timeout?: number;
+};
+export type InstanceStartOptions = {
+    port?: number | undefined;
+};
+export type InstanceStartContext = {
+    emitter: Emitter<EventTypes>;
+    setEndpoint?(endpoint: {
+        host?: string;
+        port?: number;
+    }): void;
+    status: InstanceStatus;
+};
+export type InstanceStopContext = {
+    emitter: Emitter<EventTypes>;
+    status: InstanceStatus;
+};
+type DefineFnResult = {
+    name: string;
+    host: string;
+    port: number;
+    start(options: InstanceStartOptions, context: InstanceStartContext): Promise<void>;
+    stop(context: InstanceStopContext): Promise<void>;
+};
+/**
+ * Creates an instance definition.
+ *
+ * Takes a factory function that returns the instance's name, host, port,
+ * and start/stop implementations. Returns a callable that creates
+ * managed instances with lifecycle control.
+ *
+ * @example
+ * ```ts
+ * const simd = Instance.define((params?: { chainId?: string }) => ({
+ *   name: 'simd',
+ *   host: 'localhost',
+ *   port: 26657,
+ *   async start(opts, ctx) { ... },
+ *   async stop(ctx) { ... },
+ * }))
+ *
+ * const instance = simd({ chainId: 'test-1' })
+ * instance.chainId // string — extra field preserved
+ * await instance.start()
+ * ```
+ */
+export declare function define<P = undefined, R extends DefineFnResult = DefineFnResult>(fn: (parameters: P) => R): (...args: P extends undefined ? [options?: InstanceOptions] : [parameters: P, options?: InstanceOptions]) => Omit<R, keyof DefineFnResult> & Instance;
+//# sourceMappingURL=Instance.d.ts.map

package/dist/Instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Instance.d.ts","sourceRoot":"","sources":["../src/Instance.ts"],"names":[],"mappings":"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"}

package/dist/Instance.js

@@ -0,0 +1,206 @@
+import mitt, {} from 'mitt';
+export { simd } from './instances/simd.js';
+export { wasmd } from './instances/wasmd.js';
+export { gaiad } from './instances/gaiad.js';
+export { xplad } from './instances/xplad.js';
+export { evmd } from './instances/evmd.js';
+export { hermes } from './instances/hermes.js';
+/**
+ * Creates an instance definition.
+ *
+ * Takes a factory function that returns the instance's name, host, port,
+ * and start/stop implementations. Returns a callable that creates
+ * managed instances with lifecycle control.
+ *
+ * @example
+ * ```ts
+ * const simd = Instance.define((params?: { chainId?: string }) => ({
+ *   name: 'simd',
+ *   host: 'localhost',
+ *   port: 26657,
+ *   async start(opts, ctx) { ... },
+ *   async stop(ctx) { ... },
+ * }))
+ *
+ * const instance = simd({ chainId: 'test-1' })
+ * instance.chainId // string — extra field preserved
+ * await instance.start()
+ * ```
+ */
+export function define(fn) {
+    return (...[parametersOrOptions, options_]) => {
+        const isInstanceOptions = (v) => v != null && typeof v === 'object' && ('messageBuffer' in v || 'timeout' in v);
+        // When P = undefined: (options?) → first arg is options
+        // When P is defined: (params, options?) → first arg is params, second is options
+        const parameters = (options_ !== undefined || !isInstanceOptions(parametersOrOptions)
+            ? parametersOrOptions
+            : undefined);
+        const options = options_ ?? (isInstanceOptions(parametersOrOptions) ? parametersOrOptions : {});
+        const raw = fn(parameters);
+        const { name, start, stop } = raw;
+        let host = raw.host;
+        let port = raw.port;
+        const { messageBuffer = 20, timeout = 60_000 } = options;
+        let startResolver = Promise.withResolvers();
+        let stopResolver = Promise.withResolvers();
+        let restartResolver = Promise.withResolvers();
+        const emitter = mitt();
+        let messages = [];
+        let status = 'idle';
+        let restarting = false;
+        const onMessage = (message) => {
+            messages.push(message);
+            if (messages.length > messageBuffer)
+                messages.shift();
+        };
+        const onListening = () => { status = 'started'; };
+        const onExit = () => { status = 'stopped'; };
+        const self = {
+            get host() { return host; },
+            name,
+            get port() { return port; },
+            get status() {
+                if (restarting)
+                    return 'restarting';
+                return status;
+            },
+            messages: {
+                clear() { messages = []; },
+                get() { return [...messages]; },
+            },
+            async start() {
+                if (status === 'starting')
+                    return startResolver.promise;
+                if (status !== 'idle' && status !== 'stopped')
+                    throw new Error(`Instance "${name}" is not in an idle or stopped state. Status: ${status}`);
+                let startTimer;
+                // Guards the in-flight start(...) call's .then/.catch below: once the
+                // timeout fires, status/resolvers have already been reset (and a
+                // retry may be in flight), so a late settle must not touch them.
+                let timedOut = false;
+                if (typeof timeout === 'number') {
+                    startTimer = setTimeout(() => {
+                        timedOut = true;
+                        status = 'idle';
+                        self.messages.clear();
+                        emitter.off('message', onMessage);
+                        emitter.off('listening', onListening);
+                        emitter.off('exit', onExit);
+                        startResolver.reject(new Error(`Instance "${name}" failed to start in time.`));
+                        startResolver = Promise.withResolvers();
+                        // Best-effort: the child may still be running post-timeout, so
+                        // ask the underlying stop to tear it down. Never let this throw —
+                        // the instance must remain retryable regardless of the outcome.
+                        try {
+                            void stop({ emitter, status: self.status }).catch(() => { });
+                        }
+                        catch {
+                            // ignore
+                        }
+                    }, timeout);
+                }
+                emitter.on('message', onMessage);
+                emitter.on('listening', onListening);
+                emitter.on('exit', onExit);
+                status = 'starting';
+                start({ port }, {
+                    emitter,
+                    setEndpoint(endpoint) {
+                        if (endpoint.host)
+                            host = endpoint.host;
+                        if (endpoint.port)
+                            port = endpoint.port;
+                    },
+                    status: self.status,
+                })
+                    .then(() => {
+                    if (startTimer)
+                        clearTimeout(startTimer);
+                    if (timedOut)
+                        return;
+                    status = 'started';
+                    stopResolver = Promise.withResolvers();
+                    startResolver.resolve(self.stop.bind(self));
+                })
+                    .catch((error) => {
+                    if (startTimer)
+                        clearTimeout(startTimer);
+                    if (timedOut)
+                        return;
+                    status = 'idle';
+                    self.messages.clear();
+                    emitter.off('message', onMessage);
+                    emitter.off('listening', onListening);
+                    emitter.off('exit', onExit);
+                    startResolver.reject(error);
+                    startResolver = Promise.withResolvers();
+                });
+                return startResolver.promise;
+            },
+            async stop() {
+                if (status === 'stopping')
+                    return stopResolver.promise;
+                if (status === 'starting')
+                    throw new Error(`Instance "${name}" is starting.`);
+                let stopTimer;
+                if (typeof timeout === 'number') {
+                    stopTimer = setTimeout(() => {
+                        stopResolver.reject(new Error(`Instance "${name}" failed to stop in time.`));
+                    }, timeout);
+                }
+                status = 'stopping';
+                stop({
+                    emitter,
+                    status: self.status,
+                })
+                    .then((...args) => {
+                    if (stopTimer)
+                        clearTimeout(stopTimer);
+                    status = 'stopped';
+                    self.messages.clear();
+                    emitter.off('message', onMessage);
+                    emitter.off('listening', onListening);
+                    emitter.off('exit', onExit);
+                    startResolver = Promise.withResolvers();
+                    stopResolver.resolve(...args);
+                })
+                    .catch((error) => {
+                    if (stopTimer)
+                        clearTimeout(stopTimer);
+                    status = 'started';
+                    stopResolver.reject(error);
+                    stopResolver = Promise.withResolvers();
+                });
+                return stopResolver.promise;
+            },
+            async restart() {
+                if (restarting)
+                    return restartResolver.promise;
+                restarting = true;
+                self.stop()
+                    .then(() => self.start())
+                    .then(() => {
+                    restarting = false;
+                    restartResolver.resolve();
+                    restartResolver = Promise.withResolvers();
+                })
+                    .catch((error) => {
+                    restarting = false;
+                    restartResolver.reject(error);
+                    restartResolver = Promise.withResolvers();
+                });
+                return restartResolver.promise;
+            },
+            on: emitter.on.bind(emitter),
+            off: emitter.off.bind(emitter),
+        };
+        const knownKeys = new Set(['name', 'host', 'port', 'start', 'stop']);
+        const extra = {};
+        for (const key of Object.keys(raw)) {
+            if (!knownKeys.has(key))
+                extra[key] = raw[key];
+        }
+        return Object.assign(self, extra);
+    };
+}
+//# sourceMappingURL=Instance.js.map

package/dist/Instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Instance.js","sourceRoot":"","sources":["../src/Instance.ts"],"names":[],"mappings":"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"}