feat: add daemon mode and --json output (#448)

* feat: add daemon mode and --json output for agent-friendly usage

- Add --daemon flag to offckb node to run the devnet in the background
- Add global --json flag for structured JSON log output
- Write daemon PID and logs to devnet data folder
- Add tests for logger JSON mode and node daemon spawning
- Update README with daemon and --json usage

Fixes #446

Co-Authored-By: Claude <noreply@anthropic.com>

* feat: add node stop command

Add offckb node stop to terminate the devnet daemon started by
offckb node --daemon. It reads the PID file, sends SIGTERM, waits
for graceful shutdown, falls back to SIGKILL if needed, and removes
the PID file.

Also add tests and update README to mention node stop instead of
manual kill.

Co-Authored-By: Claude <noreply@anthropic.com>

* ci: fix formatting, windows test paths, and add changeset

- Run prettier so lint job's git diff --exit-code passes

- Use path.join in node-command tests so Windows path assertions pass

- Add changeset for daemon mode, --json output, and node stop command

Co-Authored-By: Claude <noreply@anthropic.com>

* chore: change changeset level from minor to patch

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(node): harden daemon lifecycle per test team review

- Reject duplicate daemon starts when PID file points to a live process.
- Verify target process identity before stopNode sends signals.
- Harden CLI entry resolution with OFFCKB_CLI_PATH fallback and file validation.
- Fix stopNode race condition between existsSync/readFileSync by reading once.
- Always clean up PID file even when signal delivery fails.
- Handle spawn sync exceptions, missing child.pid, and log dir creation failures.
- Use taskkill on Windows to terminate the daemon process tree.
- Distinguish EPERM vs ESRCH and surface clear error messages.

Co-Authored-By: Claude <noreply@anthropic.com>

* test(node): make daemon lifecycle tests platform-aware for Windows CI

- Assert the resolved script path so Windows backslash normalization passes.
- Mock WMIC output with the CommandLine= prefix required by the parser.
- Normalize process.platform to linux in stop tests for deterministic
  POSIX signal assertions; the Windows taskkill path is covered by the
  daemon spawn tests and integration tests.

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: humble-little-bear

.changeset/brave-falcons-dance.md

@@ -0,0 +1,10 @@
+---
+"@offckb/cli": patch
+---
+
+Add daemon mode and structured JSON output for agent-friendly usage, plus a `node stop` command to terminate the daemon.
+
+- `offckb node --daemon` starts the CKB devnet as a detached background process and writes the PID and logs to the devnet data folder.
+- `offckb --json <command>` emits structured JSON log output for programmatic consumption.
+- `offckb node stop` reads the daemon PID file and gracefully shuts down the daemon, falling back to force-kill if necessary. It now verifies the target process identity, handles stale PID files, and cleans up on error paths.
+- Hardened daemon lifecycle: duplicate daemon starts are rejected, CLI entry resolution supports packaged/npx environments via `OFFCKB_CLI_PATH`, and log/PID directory creation failures are handled gracefully.

README.md

@@ -70,6 +70,7 @@ Options:
 
 Commands:
   node [CKB-Version]                            Use the CKB to start devnet
+  node stop                                     Stop the running CKB devnet daemon
   create [options] [project-name]               Create a new CKB Smart Contract project in JavaScript.
   deploy [options]                              Deploy contracts to different networks, only supports devnet and testnet
   debug [options]                               Quickly debug transaction with tx-hash
@@ -118,6 +119,40 @@ offckb node --binary-path /path/to/your/ckb/binary
 
 When using `--binary-path`, it will ignore the specified version and network, and only work for devnet.
 
+**Run in Daemon Mode**
+
+Start the devnet in the background so your terminal stays free:
+
+```sh
+offckb node --daemon
+```
+
+The daemon writes its logs and PID to the devnet data folder, for example:
+
+- Logs: `~/Library/Application Support/offckb-nodejs/devnet/data/logs/daemon.log`
+- PID file: `~/Library/Application Support/offckb-nodejs/devnet/data/logs/daemon.pid`
+
+Stop the daemon later with:
+
+```sh
+offckb node stop
+```
+
+**Agent-Friendly JSON Output**
+
+For programmatic consumption or agent integration, add `--json` to any command to emit structured JSON logs:
+
+```sh
+offckb node --json
+offckb node --daemon --json
+```
+
+Each log line is a single JSON object:
+
+```json
+{"level":"info","message":"Launching CKB devnet Node...","timestamp":"2026-07-07T07:10:00.000Z"}
+```
+
 **RPC & Proxy RPC**
 
 When the Devnet starts:

src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { startNode } from './cmd/node';
+import { startNode, stopNode } from './cmd/node';
 import { accounts } from './cmd/accounts';
 import { clean } from './cmd/clean';
 import { setUTF8EncodingForWindows } from './util/encoding';
@@ -28,18 +28,32 @@ setUTF8EncodingForWindows();
 const program = new Command();
 program.name('offckb').description(description).version(version).enablePositionalOptions();
 
-program
+program.option('--json', 'Output logs in JSON format for agent/programmatic consumption');
+program.hook('preAction', (thisCommand) => {
+  const opts = thisCommand.opts();
+  if (opts.json) {
+    logger.setJsonMode(true);
+  }
+});
+
+const nodeCommand = program
   .command('node [CKB-Version]')
   .description('Use the CKB to start devnet')
   .option('--network <network>', 'Specify the network to deploy to', 'devnet')
   .option(
     '-b, --binary-path <binaryPath>',
     'Specify the CKB binary path to use, only for devnet, when set, will ignore version and network',
   )
-  .action(async (version: string, options: { network: Network; binaryPath?: string }) => {
-    return startNode({ version, network: options.network, binaryPath: options.binaryPath });
+  .option('--daemon', 'Run the node in the background as a daemon (devnet only)')
+  .action(async (version: string, options: { network: Network; binaryPath?: string; daemon?: boolean }) => {
+    return startNode({ version, network: options.network, binaryPath: options.binaryPath, daemon: options.daemon });
   });
 
+nodeCommand
+  .command('stop')
+  .description('Stop the running CKB devnet daemon')
+  .action(async () => stopNode());
+
 program
   .command('create [project-name]')
   .description('Create a new CKB Smart Contract project in JavaScript.')