docs: improve local CLI development instructions

- Update "Running the CLI locally" to use direct node execution
- Add warning about global socket installation conflicts
- Align root package.json Node.js requirement to >=25.8.0

Author: jdalton

CLAUDE.md

@@ -113,8 +113,10 @@ All shared standards (git, testing, code style, cross-platform, CI) defined in s
 
 ### Running the CLI locally
 - **Watch mode**: `pnpm dev` (auto-rebuilds on file changes)
-- **Build and run**: `pnpm build && pnpm exec socket`
-- **Run built version**: `pnpm exec socket <args>` (requires prior build)
+- **Build and run**: `pnpm build:cli && node packages/cli/dist/index.js`
+- **Run built version**: `node packages/cli/dist/index.js <args>` (requires prior build)
+
+**Note**: Avoid `pnpm exec socket` if you have a global `socket` installation, as it may conflict with the local package.
 
 ### Package Management
 - **Package Manager**: This project uses pnpm (v10.22+)

LICENSE

@@ -4,7 +4,6 @@
   "packageManager": "pnpm@10.31.0",
   "private": true,
   "engines": {
-    "node": ">=25.5.0",
     "pnpm": ">=10.22.0"
   },
   "scripts": {

logo-dark.png

@@ -129,7 +129,7 @@
     "zod": "catalog:"
   },
   "engines": {
-    "node": ">=25.8.0",
+    "node": ">=24.14.0",
     "pnpm": ">=10.22.0"
   },
   "repository": {

logo-light.png

@@ -23,12 +23,7 @@ const NODE_MEMORY_FLAGS = ['--max-old-space-size=8192']
 // Simple CLI helpers without registry dependencies.
 const isQuiet = () => process.argv.includes('--quiet')
 const isVerbose = () => process.argv.includes('--verbose')
-const log = {
-  info: msg => logger.info(msg),
-  step: msg => logger.step(msg),
-  success: msg => logger.success(msg),
-  error: msg => logger.error(msg),
-}
+
 const printHeader = title => {
   logger.log('')
   logger.log(title)
@@ -83,7 +78,7 @@ async function fixNodeGypStrings(dir, options = {}) {
         await fs.writeFile(filePath, fixed, 'utf8')
 
         if (!quiet && verbose) {
-          log.info(
+          logger.info(
             `Fixed node-gyp string in ${path.relative(packageRoot, filePath)}`,
           )
         }
@@ -106,7 +101,7 @@ async function main() {
   // Delegate to watch mode.
   if (watch) {
     if (!quiet) {
-      log.info('Starting watch mode...')
+      logger.info('Starting watch mode...')
     }
 
     // First download yoga WASM (only needed asset for CLI bundle).
@@ -164,28 +159,28 @@ async function main() {
     // Phase 1: Clean (if needed).
     if (shouldClean) {
       if (!quiet) {
-        log.step('Phase 1: Cleaning...')
+        logger.step('Phase 1: Cleaning...')
       }
       const result = await spawn('pnpm', ['run', 'clean:dist'], {
         shell: WIN32,
         stdio: 'inherit',
       })
       if (result.code !== 0) {
         if (!quiet) {
-          log.error(`Clean failed (exit code: ${result.code})`)
+          logger.error(`Clean failed (exit code: ${result.code})`)
           printError('Build failed')
         }
         process.exitCode = 1
         return
       }
       if (!quiet && verbose) {
-        log.success('Clean completed')
+        logger.success('Clean completed')
       }
     }
 
     // Phase 2: Generate packages and download assets in parallel.
     if (!quiet) {
-      log.step('Phase 2: Preparing build (parallel)...')
+      logger.step('Phase 2: Preparing build (parallel)...')
     }
 
     const parallelPrep = await Promise.all([
@@ -205,7 +200,7 @@ async function main() {
       // Check for null spawn result.
       if (!result) {
         if (!quiet) {
-          log.error(`${stepName} failed to start`)
+          logger.error(`${stepName} failed to start`)
           printError('Build failed')
         }
         process.exitCode = 1
@@ -214,21 +209,21 @@ async function main() {
 
       if (result.code !== 0) {
         if (!quiet) {
-          log.error(`${stepName} failed (exit code: ${result.code})`)
+          logger.error(`${stepName} failed (exit code: ${result.code})`)
           printError('Build failed')
         }
         process.exitCode = result.code ?? 1
         return
       }
 
       if (!quiet && verbose) {
-        log.success(`${stepName} completed`)
+        logger.success(`${stepName} completed`)
       }
     }
 
     // Phase 3: Build all variants.
     if (!quiet) {
-      log.step('Phase 3: Building variants...')
+      logger.step('Phase 3: Building variants...')
     }
 
     // Ensure dist directory exists before building variants.
@@ -245,28 +240,28 @@ async function main() {
 
     if (buildResult.code !== 0) {
       if (!quiet) {
-        log.error(`Build failed (exit code: ${buildResult.code})`)
+        logger.error(`Build failed (exit code: ${buildResult.code})`)
         printError('Build failed')
       }
       process.exitCode = 1
       return
     }
 
     if (!quiet && verbose) {
-      log.success('Build completed')
+      logger.success('Build completed')
     }
 
     // Phase 4: Post-processing (parallel).
     if (!quiet) {
-      log.step('Phase 4: Post-processing (parallel)...')
+      logger.step('Phase 4: Post-processing (parallel)...')
     }
 
     await Promise.all([
       // Copy CLI bundle to dist (required for dist/index.js to work).
       (async () => {
         copyFileSync('build/cli.js', 'dist/cli.js')
         if (!quiet && verbose) {
-          log.success('CLI bundle copied')
+          logger.success('CLI bundle copied')
         }
       })(),
 
@@ -277,25 +272,18 @@ async function main() {
           verbose,
         })
         if (!quiet && verbose) {
-          log.success('Build output post-processed')
+          logger.success('Build output post-processed')
         }
       })(),
 
-      // Copy files from repo root.
+      // Copy CHANGELOG.md from repo root (LICENSE and logos are already in cli package).
       (async () => {
-        const filesToCopy = [
-          'CHANGELOG.md',
-          'LICENSE',
-          'logo-dark.png',
-          'logo-light.png',
-        ]
-        await Promise.all(
-          filesToCopy.map(file =>
-            fs.cp(path.join(repoRoot, file), path.join(packageRoot, file)),
-          ),
+        await fs.cp(
+          path.join(repoRoot, 'CHANGELOG.md'),
+          path.join(packageRoot, 'CHANGELOG.md'),
         )
         if (!quiet && verbose) {
-          log.success('Files copied from repo root')
+          logger.success('CHANGELOG.md copied from repo root')
         }
       })(),
     ])