feat: add new node command to fuels CLI (#2376)

* feat: add new `node` command to `fuels` CLI

* add command to readme

---------

Co-authored-by: Sérgio Torres <[email protected]>
Co-authored-by: Chad Nehemiah <[email protected]>

Author: 3 people

Diff for: .changeset/quiet-lobsters-design.md

@@ -0,0 +1,5 @@
+---
+"fuels": patch
+---
+
+feat: add new `node` command to `fuels` CLI

Diff for: README.md

@@ -66,6 +66,7 @@ Options:
 
 Commands:
   init [options]     Create a sample `fuel.config.ts` file
+  node [options]     Start a Fuel node
   dev [options]      Start a Fuel node and run build + deploy on every file change
   build [options]    Build Sway programs and generate Typescript for them
   deploy [options]   Deploy contracts to the Fuel network

Diff for: apps/docs/src/guide/fuels-cli/commands.md

@@ -131,6 +131,14 @@ The `fuels dev` command does three things:
 
 > _In `dev` mode, every time you update a contract on your Forc `workspace`, we re-generate type definitions and factory classes for it, following your pre-configured [`output`](./config-file.md#output) directory. If it's part of another build system running in dev mode (i.e. `next dev`), you can expect it to re-build / auto-reload as well._
 
+## `fuels node`
+
+```console-vue
+npx fuels@{{fuels}} node
+```
+
+The `fuels node` command starts a short-lived `fuel-core` node ([docs](./config-file.md#autostartfuelcore)).
+
 ## `fuels typegen`
 
 Manually generates type definitions and factory classes from ABI JSON files.

Diff for: packages/fuels/src/cli.test.ts

@@ -34,11 +34,13 @@ describe('cli.js', () => {
 
     const init = cmd(Commands.init);
     const dev = cmd(Commands.dev);
+    const node = cmd(Commands.node);
     const build = cmd(Commands.build);
     const deploy = cmd(Commands.deploy);
 
     expect(init).toBeTruthy();
     expect(dev).toBeTruthy();
+    expect(node).toBeTruthy();
     expect(build).toBeTruthy();
     expect(deploy).toBeTruthy();
 
@@ -47,6 +49,7 @@ describe('cli.js', () => {
 
     expect(init?.opts()).toEqual({ path });
     expect(dev?.opts()).toEqual({ path });
+    expect(node?.opts()).toEqual({ path });
     expect(build?.opts()).toEqual({ path });
     expect(deploy?.opts()).toEqual({ path });
   });

Diff for: packages/fuels/src/cli.ts

@@ -7,6 +7,7 @@ import { build } from './cli/commands/build';
 import { deploy } from './cli/commands/deploy';
 import { dev } from './cli/commands/dev';
 import { init } from './cli/commands/init';
+import { node } from './cli/commands/node';
 import { withBinaryPaths } from './cli/commands/withBinaryPaths';
 import { withConfig } from './cli/commands/withConfig';
 import { withProgram } from './cli/commands/withProgram';
@@ -66,6 +67,11 @@ export const configureCli = () => {
     .addOption(pathOption)
     .action(withConfig(command, Commands.dev, dev));
 
+  (command = program.command(Commands.node))
+    .description('Start a Fuel node')
+    .addOption(pathOption)
+    .action(withConfig(command, Commands.node, node));
+
   (command = program.command(Commands.build))
     .description('Build Sway programs and generate Typescript for them')
     .addOption(pathOption)

Diff for: packages/fuels/src/cli/commands/node/index.test.ts

@@ -0,0 +1,85 @@
+import type { FSWatcher } from 'chokidar';
+
+import { fuelsConfig } from '../../../../test/fixtures/fuels.config';
+import { mockStartFuelCore } from '../../../../test/utils/mockAutoStartFuelCore';
+import { mockLogger } from '../../../../test/utils/mockLogger';
+import * as loadConfigMod from '../../config/loadConfig';
+import type { FuelsConfig } from '../../types';
+import * as withConfigMod from '../withConfig';
+
+import { closeAllFileHandlers, configFileChanged, getConfigFilepathsToWatch } from '.';
+
+/**
+ * @group node
+ */
+describe('node', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function mockAll() {
+    const { autoStartFuelCore, fuelCore, killChildProcess } = mockStartFuelCore();
+
+    const onFailure = vi.fn();
+
+    const withConfigErrorHandler = vi
+      .spyOn(withConfigMod, 'withConfigErrorHandler')
+      .mockReturnValue(Promise.resolve());
+
+    const loadConfig = vi
+      .spyOn(loadConfigMod, 'loadConfig')
+      .mockReturnValue(Promise.resolve(fuelsConfig));
+
+    return {
+      autoStartFuelCore,
+      fuelCore,
+      killChildProcess,
+      loadConfig,
+      onFailure,
+      withConfigErrorHandler,
+    };
+  }
+
+  test('should call `close` on all file handlers', () => {
+    const close = vi.fn();
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const handlers: any = [{ close }, { close }, { close }];
+
+    closeAllFileHandlers(handlers);
+
+    expect(close).toHaveBeenCalledTimes(3);
+  });
+
+  test('should restart everything when config file changes', async () => {
+    const { log } = mockLogger();
+    const { autoStartFuelCore, fuelCore, killChildProcess, loadConfig, withConfigErrorHandler } =
+      mockAll();
+
+    const config = structuredClone(fuelsConfig);
+    const close = vi.fn();
+    const watchHandlers = [{ close }, { close }] as unknown as FSWatcher[];
+
+    await configFileChanged({ config, fuelCore, watchHandlers })('event', 'some/path');
+
+    // configFileChanged() internals
+    expect(log).toHaveBeenCalledTimes(1);
+    expect(close).toHaveBeenCalledTimes(2);
+    expect(killChildProcess).toHaveBeenCalledTimes(1);
+    expect(loadConfig).toHaveBeenCalledTimes(1);
+
+    // node() internals
+    expect(autoStartFuelCore).toHaveBeenCalledTimes(1);
+    expect(withConfigErrorHandler).toHaveBeenCalledTimes(0); // never error
+  });
+
+  test('should collect only non-null config paths', () => {
+    const config: FuelsConfig = structuredClone(fuelsConfig);
+
+    config.snapshotDir = undefined;
+    expect(getConfigFilepathsToWatch(config)).toHaveLength(1);
+
+    config.snapshotDir = '/some/path/to/chainConfig.json';
+    expect(getConfigFilepathsToWatch(config)).toHaveLength(2);
+  });
+});

Diff for: packages/fuels/src/cli/commands/node/index.ts

@@ -0,0 +1,58 @@
+import { watch, type FSWatcher } from 'chokidar';
+
+import { loadConfig } from '../../config/loadConfig';
+import type { FuelsConfig } from '../../types';
+import { error, log } from '../../utils/logger';
+import type { FuelCoreNode } from '../dev/autoStartFuelCore';
+import { autoStartFuelCore } from '../dev/autoStartFuelCore';
+import { withConfigErrorHandler } from '../withConfig';
+
+export type NodeState = {
+  config: FuelsConfig;
+  watchHandlers: FSWatcher[];
+  fuelCore?: FuelCoreNode;
+};
+
+export const getConfigFilepathsToWatch = (config: FuelsConfig) => {
+  const configFilePathsToWatch: string[] = [config.configPath];
+  if (config.snapshotDir) {
+    configFilePathsToWatch.push(config.snapshotDir);
+  }
+  return configFilePathsToWatch;
+};
+
+export const closeAllFileHandlers = (handlers: FSWatcher[]) => {
+  handlers.forEach((h) => h.close());
+};
+
+export const configFileChanged = (state: NodeState) => async (_event: string, path: string) => {
+  log(`\nFile changed: ${path}`);
+
+  closeAllFileHandlers(state.watchHandlers);
+  state.fuelCore?.killChildProcess();
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-use-before-define
+    await node(await loadConfig(state.config.basePath));
+  } catch (err: unknown) {
+    await withConfigErrorHandler(<Error>err, state.config);
+  }
+};
+
+export const node = async (config: FuelsConfig) => {
+  const fuelCore = await autoStartFuelCore(config);
+
+  const configFilePaths = getConfigFilepathsToWatch(config);
+
+  try {
+    const watchHandlers: FSWatcher[] = [];
+    const options = { persistent: true, ignoreInitial: true, ignored: '**/out/**' };
+    const state = { config, watchHandlers, fuelCore };
+
+    // watch: fuels.config.ts and snapshotDir
+    watchHandlers.push(watch(configFilePaths, options).on('all', configFileChanged(state)));
+  } catch (err: unknown) {
+    error(err);
+    throw err;
+  }
+};

Diff for: packages/fuels/src/cli/types.ts

@@ -6,6 +6,7 @@ export enum Commands {
   dev = 'dev',
   init = 'init',
   versions = 'versions',
+  node = 'node',
 }
 
 export type CommandEvent =
@@ -28,6 +29,10 @@ export type CommandEvent =
   | {
       type: Commands.versions;
       data: unknown;
+    }
+  | {
+      type: Commands.node;
+      data: unknown;
     };
 
 export type DeployedContract = {