@neuralnomads/codenomadcloud

@neuralnomads/codenomadcloud ships the CodeNomad Cloud client surfaces plus the embedded Server Connector SDK used by CodeNomad Server integrations. This package also includes the supported codenomadcloud CLI.

Server Connector quick start

import { serverConnector } from "@neuralnomads/codenomadcloud";

const prepared = await serverConnector.connectServerTokenAndBuildConfig({
  cloudBaseUrl: process.env.CODENOMAD_CLOUD_URL!,
  // Optional when CODENOMAD_SERVER_TOKEN is set in the environment.
  serverToken: process.env.CODENOMAD_SERVER_TOKEN,
  connectorVersion: "codenomad-server/0.1.0",
  capabilities: {
    remoteAccessEnabled: true,
    webhookListenerEnabled: false,
  },
});

const connector = await serverConnector.createEmbeddedServerConnector({
  config: prepared.config,
  primaryTarget: { type: "loopback", port: 8080 },
  presenceHeartbeat: { enabled: true, intervalMs: 20_000 },
});

connector.on("connect", (event) => {
  console.info("server connector online", {
    serverId: prepared.config.serverId,
    wasReconnect: event.wasReconnect,
  });
});

connector.on("reconnect_attempt", (event) => {
  console.warn("server connector reconnecting", { attempt: event.attempt, delayMs: event.delayMs });
});

connector.on("error", (error) => {
  console.error("server connector runtime error", error);
});

connector.start();
await connector.waitForReady();

What the SDK gives you

• Server Token creation/connect/reconnect, rotation-compatible config, and slug helpers
• high-level server-token-to-config bootstrap for embedded server startup
• lifecycle-managed embedded connector with reconnect-aware capability advertisement
• server-centric session creation helpers for both serverId and connect-hostname targeting
• re-exported target, policy, and handler types for loopback, LAN, and in-process integrations

Compatibility note: existing lower-level enrollment artifact and setup-token helpers remain available for advanced or automation flows, but dashboard-issued Server Tokens should use serverToken. If serverToken is omitted, server-token helpers read CODENOMAD_SERVER_TOKEN from the runtime environment.

CLI quick start

The shipped codenomadcloud CLI supports three user-facing commands:

codenomadcloud webhook --to http://localhost:3000/webhooks --relay wss://relay.example.com --token "$CODENOMADCLOUD_TOKEN"
codenomadcloud serve --server-token "$CODENOMAD_SERVER_TOKEN" --cloud https://cloud.example.com --target http://127.0.0.1:8080
codenomadcloud access --session-token "$CODENOMADCLOUD_SESSION_TOKEN" --relay wss://relay.example.com --port 8080

• webhook forwards CodeNomad Cloud webhook delivery events to one local HTTP endpoint.
• serve connects or reconnects with a dashboard-issued Server Token, starts the embedded Server Connector, advertises Remote Access capability, and publishes one primary service target.
• access joins an authorized Remote Access session using a short-lived session token and exposes it on a local loopback port.

Legacy command names from earlier transitional tooling are not part of the supported CLI surface.

Local npm registry publish and install

The public consumer package is @neuralnomads/codenomadcloud. Internal workspace packages such as @codenomadcloud/shared and @codenomadcloud/remote-connector-protocol remain monorepo implementation details and are internalized under the package dist/node_modules/ tree; they are not separately published public consumer packages.

For public/consumer packaging, @neuralnomads/codenomadcloud is the only direct install unit. The package manifest does not require public npm resolution of @codenomadcloud/shared or @codenomadcloud/remote-connector-protocol; the build copies those internal runtime packages into dist/node_modules/ so direct pack, verification, local-registry, and public npm release flows do not require separate internal package publishes.

Public package support surface and obfuscation

The published package keeps consumer/support surfaces readable:

• package metadata and this README
• dist/index.js and generated .d.ts declarations
• codenomadcloud CLI command names, flags, usage, and help text
• documented SDK error names, fields, event names, and diagnostics

After TypeScript emit, the package build selectively minifies private dist/remote_connector/* runtime implementation files and removes their JavaScript source maps before packing. The generated dist/obfuscation-boundary.json records which emitted files were treated as readable or obfuscated.

Run the package verification harness from the repository root with:

pnpm sdk:verify:client-package

The verifier builds the internal workspace packages and public client package, confirms the internal runtime packages are present under dist/node_modules/, packs only @neuralnomads/codenomadcloud, checks package contents and dependency metadata, confirms no supported pack path exposes workspace:* runtime dependencies or path traversal entries, installs the client tarball into a clean temporary project as the only direct dependency, imports the SDK entrypoint, exercises CLI help for webhook, serve, and access, and validates the obfuscation boundary.

Publish to a local registry

Start a local npm-compatible registry such as Verdaccio, then publish from the repo root:

CODENOMADCLOUD_LOCAL_REGISTRY_URL=http://127.0.0.1:4873 pnpm publish:local-registry

Optional dry run:

CODENOMADCLOUD_LOCAL_REGISTRY_URL=http://127.0.0.1:4873 pnpm publish:local-registry -- --dry-run

Install from another project

In the consuming project, point npm to the local registry and install only the SDK package:

npm config set @neuralnomads:registry http://127.0.0.1:4873
npm install @neuralnomads/[email protected]

The installed tarball includes the internal runtime packages under dist/node_modules/, so no separate internal package install or publish is required.

Integration guide

See ../../docs/features/local_client/INTEGRATION_GUIDE.md for the full CodeNomad Server integration flow, target examples, and validation notes.