feat(cli): delegate commands to gnd by default

`graph <cmd>` now execs the matching `gnd <cmd>` (the Rust
`@graphprotocol/gnd` binary). Two exceptions stay on the oclif/TS path:
`local`, which has no gnd equivalent, and `dev`, which is a thin oclif
shim that spawns `gnd dev` so the command is discoverable from
`graph --help`. Set `GRAPH_CLI_IGNORE_GND=1` to force the TS
implementation everywhere; the test suite does this automatically.

Author: lutter

packages/cli/CLAUDE.md

@@ -6,6 +6,23 @@ CLI for building and deploying subgraphs to The Graph Network.
 
 Built on [oclif](https://oclif.io/) command framework. Entry point: `bin/run.js` -> `dist/commands/`.
 
+## gnd dispatch
+
+By default, `graph <cmd>` execs `gnd <cmd>` (the Rust `@graphprotocol/gnd`
+binary). Exceptions:
+
+- `graph local` always runs the TypeScript implementation — gnd has no
+  equivalent command.
+- `graph dev` is an oclif shim that spawns `gnd dev`, so the command is
+  discoverable from `graph --help` even when running in TS mode.
+
+Set `GRAPH_CLI_IGNORE_GND=1` to force every command through the oclif/TS
+implementation. The test suite sets this automatically via
+`tests/cli/globalSetup.ts`.
+
+The dispatch lives in `bin/run.js` and shares the spawn helper in
+`src/command-helpers/gnd.ts` with `src/commands/dev.ts`.
+
 ## Key Directories
 
 ```
@@ -34,7 +51,8 @@ src/
 | `add` | Add data source to manifest |
 | `remove` | Remove data source from manifest |
 | `auth` | Set deploy key |
-| `local` | Manage local Graph Node |
+| `local` | Manage local Graph Node (always TS — gnd has no equivalent) |
+| `dev` | Run graph-node in dev mode (delegates to `gnd dev`) |
 | `clean` | Remove build artifacts |
 
 ## Protocol System

packages/cli/bin/run.js

@@ -3,6 +3,7 @@ import process from 'node:process';
 import semver from 'semver';
 import { execute } from '@oclif/core';
 import { nodeVersion } from '../dist/version.js';
+import { runGnd } from '../dist/command-helpers/gnd.js';
 
 if (!semver.satisfies(process.version, nodeVersion)) {
   process.stderr.write(
@@ -11,4 +12,11 @@ if (!semver.satisfies(process.version, nodeVersion)) {
   process.exit(1);
 }
 
-await execute({ dir: import.meta.url });
+const args = process.argv.slice(2);
+const useGnd = !process.env.GRAPH_CLI_IGNORE_GND && args[0] !== 'local';
+
+if (useGnd) {
+  runGnd(args);
+} else {
+  await execute({ dir: import.meta.url });
+}

packages/cli/src/command-helpers/gnd.ts

@@ -0,0 +1,22 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import process from 'node:process';
+
+const require = createRequire(import.meta.url);
+
+export function runGnd(args: string[]): never {
+  const gndEntry = require.resolve('@graphprotocol/gnd/bin/gnd.js');
+  const child = spawn(process.execPath, [gndEntry, ...args], { stdio: 'inherit' });
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 1);
+    }
+  });
+  child.on('error', err => {
+    process.stderr.write(`Failed to launch gnd: ${err.message}\n`);
+    process.exit(1);
+  });
+  return new Promise<never>(() => {}) as never;
+}

packages/cli/src/commands/dev.ts

@@ -0,0 +1,15 @@
+import { Command } from '@oclif/core';
+import { runGnd } from '../command-helpers/gnd.js';
+
+export default class DevCommand extends Command {
+  static description =
+    'Run graph-node in dev mode. Delegates to `gnd dev`; run `graph dev --help` (without GRAPH_CLI_IGNORE_GND set) for the full list of supported flags.';
+
+  static strict = false;
+
+  static args = {};
+
+  async run() {
+    runGnd(['dev', ...this.argv]);
+  }
+}

packages/cli/tests/cli/globalSetup.ts

@@ -4,5 +4,6 @@ import { linkCli } from './link';
 
 export default async () => {
   process.env.GRAPH_CLI_TESTS = '1';
+  process.env.GRAPH_CLI_IGNORE_GND = '1';
   await linkCli();
 };