refactor(tool): unify the cli entrypoint (#275)

Brooooooklyn · web-flow · commit 2f39b246d15f · 2025-10-29T20:17:24.000+08:00
I'm preparing to add more tools to `@voidzero-dev/vite-plus-tools`. Before adding more commands and tools, I want to unify the CLI entry point first.
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -48,7 +48,7 @@ jobs:
       - uses: oxc-project/setup-node@fdbf0dfd334c4e6d56ceeb77d91c76339c2a0885 # v1.0.4
 
       - name: Set binding version
-        run: pnpm exec replace-file-content packages/cli/binding/Cargo.toml 'version = "0.0.0"' 'version = "0.0.0-${{ github.sha }}"'
+        run: pnpm exec tool replace-file-content packages/cli/binding/Cargo.toml 'version = "0.0.0"' 'version = "0.0.0-${{ github.sha }}"'
 
       - name: Build
         if: ${{ matrix.settings.target == 'x86_64-unknown-linux-gnu' }}
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -27,7 +27,7 @@
   },
   "scripts": {
     "build": "oxnode ./build.ts",
-    "snap-test": "snap-test"
+    "snap-test": "tool snap-test"
   },
   "files": [
     "bin",
diff --git a/packages/global/package.json b/packages/global/package.json
@@ -19,7 +19,7 @@
   ],
   "scripts": {
     "build": "rolldown -c rolldown.config.ts",
-    "snap-test": "snap-test"
+    "snap-test": "tool snap-test"
   },
   "dependencies": {
     "@voidzero-dev/vite-plus": "workspace:*",
diff --git a/packages/tools/package.json b/packages/tools/package.json
@@ -3,14 +3,13 @@
   "private": true,
   "type": "module",
   "bin": {
-    "json-edit": "./src/json-edit.ts",
-    "snap-test": "./src/snap-test.ts",
-    "replace-file-content": "./src/replace-file-content.ts"
+    "tool": "./src/bin.js",
+    "json-edit": "./src/json-edit.ts"
   },
   "devDependencies": {
     "minimatch": "catalog:"
   },
   "scripts": {
-    "snap-test": "snap-test"
+    "snap-test": "tool snap-test"
   }
 }
diff --git a/packages/tools/snap-tests/replace-file-content/snap.txt b/packages/tools/snap-tests/replace-file-content/snap.txt
@@ -14,7 +14,7 @@ crossterm = { workspace = true }
 napi = { workspace = true }
 napi-derive = { workspace = true }
 
-> replace-file-content foo/example.toml 'version = "0.0.0"' 'version = "1.0.0"' && cat foo/example.toml # should edit toml file
+> tool replace-file-content foo/example.toml 'version = "0.0.0"' 'version = "1.0.0"' && cat foo/example.toml # should edit toml file
 [package]
 name = "foo"
 version = "1.0.0"
diff --git a/packages/tools/snap-tests/replace-file-content/steps.json b/packages/tools/snap-tests/replace-file-content/steps.json
@@ -3,6 +3,6 @@
   },
   "commands": [
     "cat foo/example.toml # should show original toml file",
-    "replace-file-content foo/example.toml 'version = \"0.0.0\"' 'version = \"1.0.0\"' && cat foo/example.toml # should edit toml file"
+    "tool replace-file-content foo/example.toml 'version = \"0.0.0\"' 'version = \"1.0.0\"' && cat foo/example.toml # should edit toml file"
   ]
 }
diff --git a/packages/tools/src/__tests__/utils.spec.ts b/packages/tools/src/__tests__/utils.spec.ts
@@ -2,7 +2,7 @@ import { tmpdir } from 'node:os';
 
 import { describe, expect, test } from '@voidzero-dev/vite-plus/test';
 
-import { isPassThroughEnv, replaceUnstableOutput } from '../utils.ts';
+import { isPassThroughEnv, replaceUnstableOutput } from '../utils';
 
 describe('replaceUnstableOutput()', () => {
   test('replace unstable semver version', () => {
diff --git a/packages/tools/src/bin.js b/packages/tools/src/bin.js
@@ -0,0 +1,4 @@
+import '@oxc-node/core/register';
+
+// defer the import to avoid the register hook is not being called
+await import('./index.ts');
diff --git a/packages/tools/src/index.ts b/packages/tools/src/index.ts
@@ -0,0 +1,17 @@
+import { replaceFileContent } from './replace-file-content';
+import { snapTest } from './snap-test';
+
+const subcommand = process.argv[2];
+
+switch (subcommand) {
+  case 'snap-test':
+    await snapTest();
+    break;
+  case 'replace-file-content':
+    replaceFileContent();
+    break;
+  default:
+    console.error(`Unknown subcommand: ${subcommand}`);
+    console.error('Available subcommands: snap-test, replace-file-content');
+    process.exit(1);
+}
diff --git a/packages/tools/src/json-edit.ts b/packages/tools/src/json-edit.ts
@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 
 import { readFileSync, writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
 
-const filename = process.argv[2];
-const script = process.argv[3];
+const { positionals } = parseArgs({
+  allowPositionals: true,
+});
+
+const filename = positionals[0];
+const script = positionals[1];
 
 if (!filename || !script) {
   console.error('Usage: json-edit <filename> <script>');
diff --git a/packages/tools/src/replace-file-content.ts b/packages/tools/src/replace-file-content.ts
@@ -1,19 +1,25 @@
-#!/usr/bin/env node
-
 import { readFileSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
+import { parseArgs } from 'node:util';
 
-const filename = process.argv[2];
-const searchValue = process.argv[3];
-const newValue = process.argv[4];
+export function replaceFileContent() {
+  const { positionals } = parseArgs({
+    allowPositionals: true,
+    args: process.argv.slice(3),
+  });
 
-if (!filename || !searchValue || !newValue) {
-  console.error('Usage: replace-file-content <filename> <searchValue> <newValue>');
-  console.error('Example: replace-file-content example.toml \'version = "0.0.0"\' \'version = "0.0.1"\'');
-  process.exit(1);
-}
+  const filename = positionals[0];
+  const searchValue = positionals[1];
+  const newValue = positionals[2];
 
-const filepath = path.resolve(filename);
-const content = readFileSync(filepath, 'utf-8');
-const newContent = content.replace(searchValue, newValue);
-writeFileSync(filepath, newContent, 'utf-8');
+  if (!filename || !searchValue || !newValue) {
+    console.error('Usage: tool replace-file-content <filename> <searchValue> <newValue>');
+    console.error('Example: tool replace-file-content example.toml \'version = "0.0.0"\' \'version = "0.0.1"\'');
+    process.exit(1);
+  }
+
+  const filepath = path.resolve(filename);
+  const content = readFileSync(filepath, 'utf-8');
+  const newContent = content.replace(searchValue, newValue);
+  writeFileSync(filepath, newContent, 'utf-8');
+}
diff --git a/packages/tools/src/snap-test.ts b/packages/tools/src/snap-test.ts
@@ -1,12 +1,12 @@
-#!/usr/bin/env node
-
 import cp from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs';
 import fsPromises from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { debuglog, promisify } from 'node:util';
+import { debuglog, parseArgs, promisify } from 'node:util';
+
+import { isPassThroughEnv, replaceUnstableOutput } from './utils';
 
 const debug = debuglog('vite-plus/snap-test');
 const cpExec = promisify(cp.exec);
@@ -16,37 +16,42 @@ const exec = async (command: string, options: cp.ExecOptionsWithStringEncoding)
     process.platform === 'win32' ? { ...options, shell: 'pwsh.exe' } : options,
   );
 
-import { isPassThroughEnv, replaceUnstableOutput } from './utils.ts';
+export async function snapTest() {
+  const { positionals } = parseArgs({
+    allowPositionals: true,
+    args: process.argv.slice(3),
+  });
 
-// Create a unique temporary directory for testing
-// On macOS, `tmpdir()` is a symlink. Resolve it so that we can replace the resolved cwd in outputs.
-const tempTmpDir = `${fs.realpathSync(tmpdir())}/vite-plus-test-${randomUUID()}`;
-fs.mkdirSync(tempTmpDir, { recursive: true });
+  const filter = positionals[0] ?? ''; // Optional filter to run specific test cases
 
-// Make dependencies available in the test cases
-fs.symlinkSync(
-  path.resolve('node_modules'),
-  path.join(tempTmpDir, 'node_modules'),
-  process.platform === 'win32' ? 'junction' : 'dir',
-);
+  // Create a unique temporary directory for testing
+  // On macOS, `tmpdir()` is a symlink. Resolve it so that we can replace the resolved cwd in outputs.
+  const tempTmpDir = `${fs.realpathSync(tmpdir())}/vite-plus-test-${randomUUID()}`;
+  fs.mkdirSync(tempTmpDir, { recursive: true });
 
-// Clean up the temporary directory on exit
-process.on('exit', () => fs.rmSync(tempTmpDir, { recursive: true, force: true }));
+  // Make dependencies available in the test cases
+  fs.symlinkSync(
+    path.resolve('node_modules'),
+    path.join(tempTmpDir, 'node_modules'),
+    process.platform === 'win32' ? 'junction' : 'dir',
+  );
 
-const casesDir = path.resolve('snap-tests');
+  // Clean up the temporary directory on exit
+  process.on('exit', () => fs.rmSync(tempTmpDir, { recursive: true, force: true }));
 
-const filter = process.argv[2] ?? ''; // Optional filter to run specific test cases
+  const casesDir = path.resolve('snap-tests');
 
-const tasks: Promise<void>[] = [];
-for (const caseName of fs.readdirSync(casesDir)) {
-  if (caseName.startsWith('.')) continue; // Skip hidden files like .DS_Store
-  if (caseName.includes(filter)) {
-    tasks.push(runTestCase(caseName));
+  const tasks: Promise<void>[] = [];
+  for (const caseName of fs.readdirSync(casesDir)) {
+    if (caseName.startsWith('.')) continue; // Skip hidden files like .DS_Store
+    if (caseName.includes(filter)) {
+      tasks.push(runTestCase(caseName, tempTmpDir, casesDir));
+    }
   }
-}
 
-if (tasks.length > 0) {
-  await Promise.all(tasks);
+  if (tasks.length > 0) {
+    await Promise.all(tasks);
+  }
 }
 
 interface Steps {
@@ -55,7 +60,7 @@ interface Steps {
   commands: string[];
 }
 
-async function runTestCase(name: string) {
+async function runTestCase(name: string, tempTmpDir: string, casesDir: string) {
   const steps: Steps = JSON.parse(await fsPromises.readFile(`${casesDir}/${name}/steps.json`, 'utf-8'));
   if (steps.ignoredPlatforms !== undefined && steps.ignoredPlatforms.includes(process.platform)) {
     console.log('%s skipped on platform %s', name, process.platform);
@@ -67,7 +72,7 @@ async function runTestCase(name: string) {
   await fsPromises.cp(`${casesDir}/${name}`, caseTmpDir, { recursive: true, errorOnExist: true });
 
   const passThroughEnvs = Object.fromEntries(Object.entries(process.env).filter(([key]) => isPassThroughEnv(key)));
-  const env = {
+  const env: Record<string, string> = {
     ...passThroughEnvs,
     // Indicate CLI is running in test mode, so that it prints more detailed outputs.
     VITE_PLUS_CLI_TEST: '1',
@@ -104,7 +109,7 @@ async function runTestCase(name: string) {
       if (stderr) {
         newSnap.push(replaceUnstableOutput(stderr, caseTmpDir));
       }
-    } catch (error) {
+    } catch (error: any) {
       // add error exit code to the command
       newSnap.push(`[${error.code}]> ${command}`);
       if (error.stdout) {
diff --git a/packages/tools/tsconfig.json b/packages/tools/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "composite": true,
+    "outDir": "./dist",
+    "noEmit": false,
+    "allowImportingTsExtensions": false,
+    "rootDir": "./src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist", "./snap-tests/**"]
+}
diff --git a/tsconfig.json b/tsconfig.json
@@ -25,6 +25,9 @@
     },
     {
       "path": "./packages/multiplexer"
+    },
+    {
+      "path": "./packages/tools"
     }
   ]
 }

Original file line number	Diff line number	Diff line change
`@@ -3,6 +3,6 @@`
`3`	`3`	`},`
`4`	`4`	`"commands": [`
`5`	`5`	`"cat foo/example.toml # should show original toml file",`
`6`		`- "replace-file-content foo/example.toml 'version = \"0.0.0\"' 'version = \"1.0.0\"' && cat foo/example.toml # should edit toml file"`
	`6`	`+ "tool replace-file-content foo/example.toml 'version = \"0.0.0\"' 'version = \"1.0.0\"' && cat foo/example.toml # should edit toml file"`
`7`	`7`	`]`
`8`	`8`	`}`