[Brooooooklyn]

Closes #871.

A tool with its own loader built on the oxc-node binding (Vite+'s vpx watch) can now run the oxnode watch watcher.

 your CLI                                        the app (your loader)
 runWatch(argv, options)  ── node <loaderArgs> <node options> <entry> ──▶  installSignalAck()
   @oxc-node/cli/watch                                                     watchSink(), withFlush()
                          ◀── IPC { "watch:import": [url] } ──────────────   @oxc-node/core/watch-report
                          ◀── "I" on the OXNODE_SIGNAL_ACK socket ─────────   @oxc-node/core/signal-ack

Watcher side: @oxc-node/cli/watch

runWatch(argv, { loaderArgs, ignoreDirs, name }). All options are optional, and with none oxnode watch behaves and prints exactly as before (the default --help text is byte-for-byte the same).

Option	Default
loaderArgs	["--enable-source-maps", "--import", <@oxc-node/core/register>], resolved only when not given
ignoreDirs	the folder of @oxc-node/core/register when loaderArgs is not given, else none (real paths count too)
name	"oxnode watch", used in errors, usage and --help; its first word tags log lines ([vpx])

• dist/watch.js is a second rolldown entry. It reaches only a shared chunk that imports node: modules: no clipanion, no binding, and it starts nothing on import. A test walks the chunks to keep it that way.
• WatchCommand (clipanion) moved into src/index.ts, so src/watch has no clipanion import.
• Hand-written types in packages/cli/watch.d.ts. ./dist/* stays importable.

App side: @oxc-node/core/signal-ack, @oxc-node/core/watch-report

• installSignalAck() is unchanged.
• flush, withFlush and createRelay now take the binding's takeWatchDependencies as an argument (take), so the entry loads no binding of its own. register.mjs and esm.mjs pass theirs.
• Both entries have import and default, so a CommonJS --require preload can load them.
• Added to package.json and to the build-time rewrite in reexport-oxc-runtime.mjs.

Docs

README, "Embedding the watcher": both sides, with code, plus the protocol for a loader that does not use these entries (start args and env, the IPC message, the "oxc-node": true key, the ack byte).

Tests

• watch-embed.spec.ts (new):
  • runs runWatch through @oxc-node/cli/watch with a custom registerHooks loader built from the new core entries;
  • restarts on a dependency edit and on a tsconfig.json edit (the second one only works through take), under [vpx], with the loader folder skipped;
  • errors and --help under the tool's name;
  • bundle guard; importing starts nothing; the entries load no binding and work with require().
• watch-args.spec.ts, watch-units.spec.ts: names in the errors, help text and log tag.
• Full suite passes in normal and OXC_TRANSFORM_ALL mode. Checked by hand on Node 22.18, 24.12 and 24.22.

Open questions for the maintainers

1. Under a name other than oxnode watch, the hints that point to oxnode --watch (for --test, and the help footer) are left out, not rewritten. Should there be a nodeWatch option for a tool's own text?
2. Is the log tag taken from the first word of name enough, or should there be a label option?
3. Should the protocol in the README (env names such as OXNODE_SIGNAL_ACK, the "oxc-node" key, the ack byte) be called stable under semver?
4. The help body still says "Run with oxc-node", which is true for a loader built on the binding. Is that wording fine for vpx?

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-20T14:59:09.669111Z	500326b	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 500326bdeb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".