@starship-ci/client: The Official NPM Client Package for Starship Deployment Management

The @starship-ci/client package is the official Node.js/TypeScript SDK that provides a high-level programmatic façade for deploying, managing, and verifying Starship multi-chain environments through Helm and Kubernetes orchestration.

The @starship-ci/client package serves as the canonical NPM client package for Starship, published under the hyperweb-io/starship repository. It abstracts the complexity of Helm chart operations and Kubernetes resource management into a unified JavaScript/TypeScript interface, enabling developers to programmatically script complete blockchain devnet lifecycles from initialization to teardown.

Core Responsibilities of the Starship NPM Client

Helm Repository and Chart Management

The client handles all Helm interactions required to install Starship. In packages/packages/client/src/client.ts, the setupHelm() method executes helm repo add and helm repo update to register the Starship chart repository (source). The deploy() method then constructs and runs the helm install command, injecting chain-specific scripts from your starship.yaml configuration to create the release (source).

Kubernetes Connectivity and Pod Lifecycle Monitoring

Before any deployment, checkConnection() validates that kubectl can reach the cluster by running kubectl get nodes, aborting immediately on failure (source). During runtime, waitForPods() and checkPodStatus() poll pod states and track restart counts, failing fast if containers enter crash loops (source). When teardown is required, deleteHelm() executes helm delete to remove the release cleanly (source).

Port Forwarding and Service Verification

The client automatically bridges local ports to deployed services through startPortForward(), which walks the loaded configuration and invokes kubectl port-forward for chains, relayers, explorers, and registries (source). After deployment, verify() delegates to the verifier modules in packages/packages/client/src/verifiers/ to execute HTTP-based health checks defined in @starship-ci/types, confirming all components are operational (source).

Installing and Configuring @starship-ci/client

Install the package from the NPM registry:

npm install @starship-ci/client

Initialize the client with your deployment parameters:

import { StarshipClient } from '@starship-ci/client';

const client = new StarshipClient({
  name: 'my-demo',                     // Helm release name
  config: 'starship.yaml',             // Path to Starship config file
  repo: 'starship',
  repoUrl: 'https://hyperweb-io.github.io/starship/',
  chart: 'devnet',
  version: '1.8.0',
  namespace: 'starship-ns',            // optional K8s namespace
});

The constructor merges these values with sensible defaults defined in defaultStarshipContext (source).

Deploying and Managing Starship Clusters

Starting a Full Deployment

Load your configuration and execute the complete orchestration sequence:

client.loadConfig();      // parses YAML into `client.config`
await client.start();     // checks K8s → setupHelm → deploy → waitForPods → startPortForward

The start() method in packages/packages/client/src/client.ts coordinates the entire lifecycle from dependency validation through port forwarding (source).

Verifying Service Health

Confirm that all deployed services are responding correctly:

await client.verify();    // runs verifiers from @starship-ci/types

Tearing Down Environments

Clean up all Kubernetes resources and Helm releases programmatically:

await client.stop();      // stops port-forwards → records status → helm delete → waits for termination

Low-Level API Access

For granular control over specific lifecycle stages, bypass the high-level orchestration:

client.setup();           // only adds Helm repo & updates it
client.deploy();          // installs chart without waiting for pods

Dependency Validation

Before executing any cluster operations, checkDependencies() validates that required external tools are installed. This method reads the dependencies array from packages/packages/client/src/deps.ts—which specifies kubectl, docker, and helm—and aborts with installation instructions if any binary is missing (source).

Summary

• The @starship-ci/client package provides the official Node.js SDK for managing Starship deployments via NPM.
• It abstracts Helm chart operations, Kubernetes pod monitoring, and port forwarding into a unified TypeScript interface.
• Key methods include start() for full deployment orchestration, verify() for health checks, and stop() for resource cleanup.
• The client validates dependencies and cluster connectivity before executing any operations to ensure reliable automation.
• Source code is located in packages/packages/client/src/ within the hyperweb-io/starship repository.

Frequently Asked Questions

What is the difference between start() and deploy() in the Starship client?

The start() method is a high-level orchestrator that executes the complete lifecycle: checking Kubernetes connectivity, setting up Helm, deploying the chart, waiting for pods to be ready, and starting port forwards. In contrast, deploy() only constructs and executes the helm install command without waiting for pod readiness or setting up port forwarding, providing lower-level control for custom workflows.

How does the client handle Kubernetes dependency checks?

Before any operation, checkDependencies() validates that kubectl, docker, and helm binaries are installed by referencing the dependencies array defined in src/deps.ts. If any tool is missing, the client prints installation hints and aborts to prevent runtime failures during cluster operations.

Can I use the client in CI/CD pipelines?

Yes. The package is designed for automated environments, allowing you to programmatically spin up multi-chain devnets in GitHub Actions, GitLab CI, or other pipelines. The start() and stop() methods provide deterministic deployment and cleanup, while verify() ensures services are healthy before proceeding to test steps.

Where are the health check verifiers implemented?

Service verification logic resides in packages/packages/client/src/verifiers/, where individual modules implement HTTP-based health checks for specific components like chains, relayers, and explorers. The verify() method in client.ts delegates to these verifiers and formats the results according to the type definitions in @starship-ci/types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}