@kuiralabs/midnight-dev

Development for the Midnight CLI packages: mn dev (compile, deploy and test a dApp as its files change, on dev wallets), mn test (prepare, run and scaffold a dApp's test suites from its dapp.test.json) and mn localnet (a local ledger-9 network in Docker).

Install

npm install @kuiralabs/midnight-cli-core @kuiralabs/midnight-dev @kuiralabs/midnight-connect @kuiralabs/midnight-engine-rc

Install with npm 11 or older (npm 12 no longer reads a package's shrinkwrap): the engine ships an npm-shrinkwrap.json that pins its SDK set, and npm 11 honours it. A program that runs the SDK installs the engine, @kuiralabs/midnight-engine-rc, for every network. How a program sets up its process for the SDK (the rejection guard, the heap, Ctrl-C, ending) is in core's README.

Entry points

| Import | What it holds | |---|---| | @kuiralabs/midnight-dev | The localnet compose path and the errors these commands throw (NoTestConfigError, LocalnetUnavailableError, PrepStepFailedError) | | @kuiralabs/midnight-dev/commands | test, dev and localnet as a registry entry (devCommands), its codes (devCodes) |

Every export and its signature is in api-report.md.

What you call

These are commands more than functions: mount them (below). getComposePath gives where a local network's compose file is written.

Codes

Each error carries a code, and classifyError(err, registry) gives its code and exit code by that code alone, never by its message. These are the codes this package owns; the rest come from core and the packages below it, each listed in its README.

| Code | Exit | What went wrong | What to do | |------|------|-----------------|------------| | NO_TEST_CONFIG | 1 | No dapp.test.json in the folder the test command ran in. | Ask the user to run it from the dApp's root, or create one with mn test create. |

Mounting its commands

The commands are definitions your program mounts in its own command line, with your state root, settings and notices (core's README explains each part). Its commands name codes the packages it builds on own, so the registry holds their entries too, as mn's does; a registry missing one is refused when it is built. Built on core's example, this one adds the dev commands, and connect's payer for mn dev's deploys:

import { homedir } from 'node:os';
import { join } from 'node:path';
import { classifyError, createHost, createPackageRegistry, parseArgs, runCommand, settingsFromEnvironment, UsageError } from '@kuiralabs/midnight-cli-core';
import { coreCommands } from '@kuiralabs/midnight-cli-core/commands';
import { chainCommands } from '@kuiralabs/midnight-chain/commands';
import { walletCommands } from '@kuiralabs/midnight-wallet/commands';
import { contractCommands } from '@kuiralabs/midnight-contract/commands';
import { connectCommands } from '@kuiralabs/midnight-connect/commands';
import { devCommands } from '@kuiralabs/midnight-dev/commands';
import { servePayer } from '@kuiralabs/midnight-connect';
import { createRcEngine } from '@kuiralabs/midnight-engine-rc';

const registry = createPackageRegistry([coreCommands, chainCommands, walletCommands, contractCommands, connectCommands, devCommands], []);
const host = createHost({
  paths: { stateRoot: join(homedir(), '.my-app'), home: homedir() },
  settings: () => settingsFromEnvironment(process.env),
  notice: (line) => console.error(line),
  engineLoader: async (_set, host) => createRcEngine(host),
});
const output = { result: (data) => console.log(JSON.stringify(data)), stdout: (text) => process.stdout.write(text), stderr: (text) => process.stderr.write(text) };

const args = parseArgs(process.argv.slice(2));
try {
  const definition = registry.find(args.command ?? '');
  if (definition === undefined) throw new UsageError(`Unknown command: ${args.command}`);
  const outcome = await runCommand(definition, args, { host, output, payer: servePayer });
  process.exitCode = outcome?.exitCode ?? 0;
} catch (err) {
  const { errorCode, exitCode } = classifyError(err, registry);
  console.error(`${errorCode}: ${err.message}`);
  process.exitCode = exitCode;
}

node my-cli.mjs test list in a dApp's folder lists its test suites; in a folder with no dapp.test.json it ends with NO_TEST_CONFIG and exit code 1. A test in mn runs the block above as it is written.