refactor(scripts): reorganize and standardize script infrastructure

- Reorganize scripts into focused categories: npm/, validation/, maintenance/, ci/
- Migrate from console to logger (@socketsecurity/lib) for consistent output
- Standardize error handling with descriptive messages and proper exit codes
- Extract validation boilerplate into shared validation-runner utility
- Convert Promise.all to Promise.allSettled for better error handling
- Add type annotations to improve type coverage
- Correct root path resolution in validation scripts
- Remove unused scripts and utilities (get-local-package-aliases, etc.)
- Add @fileoverview headers to all script files
- Standardize logger method usage across all scripts

Author: jdalton

.config/vitest.config.mts

@@ -171,7 +171,7 @@ export default defineConfig({
       reportsDirectory: 'coverage',
       reporter: ['text', 'json', 'html', 'lcov', 'clover'],
       // ONLY include registry/src production code (not types.ts)
-      include: ['registry/src/index.{ts,mts,cts}'],
+      include: ['registry/src/**/*.{ts,mts,cts}'],
       // Exclude everything else (must include vitest defaults)
       exclude: [
         // Vitest defaults
@@ -193,16 +193,16 @@ export default defineConfig({
         'registry/plugins/**',
         'registry/dist/**',
       ],
-      // Set to false to ONLY report files in include list that are executed
-      all: false,
+      // Set to true to report ALL files in include list, even if not executed
+      all: true,
       clean: true,
       skipFull: false,
       ignoreClassMethods: ['constructor'],
       thresholds: {
-        lines: 1,
-        functions: 80,
-        branches: 80,
-        statements: 1,
+        lines: 98,
+        functions: 100,
+        branches: 100,
+        statements: 98,
       },
     },
   },

perf/npm/json-stable-stringify.perf.mts

@@ -7,13 +7,13 @@ import { getDefaultLogger } from '@socketsecurity/lib/logger'
 import fastJsonStableStringify from 'fast-json-stable-stringify'
 import { Bench } from 'tinybench'
 
-import constants from '../../scripts/constants.mjs'
+import { PERF_NPM_FIXTURES_PATH } from '../../scripts/constants/paths.mjs'
 
 const logger = getDefaultLogger()
 
 void (async () => {
   const sampleData2MbJson = require(
-    path.join(constants.perfNpmFixturesPath, 'sample_data_2mb.json'),
+    path.join(PERF_NPM_FIXTURES_PATH, 'sample_data_2mb.json'),
   )
   const sampleData6MbJson = {
     a: sampleData2MbJson,

registry/.config/esbuild.config.mjs

@@ -7,7 +7,7 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import fg from 'fast-glob'
 
-import { getLocalPackageAliases } from '../scripts/utils/get-local-package-aliases.mjs'
+import { envAsBoolean } from '@socketsecurity/lib/env/helpers'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.join(__dirname, '..')
@@ -22,38 +22,6 @@ const entryPoints = fg.sync('**/*.{ts,mts,cts}', {
   ignore: ['**/*.d.ts', '**/types/**'],
 })
 
-/**
- * Plugin to handle local package aliases when bundle: false
- * esbuild's built-in alias only works with bundle: true, so we need a custom plugin
- */
-function createAliasPlugin() {
-  const aliases = getLocalPackageAliases(rootPath)
-
-  // Only create plugin if we have local aliases
-  if (Object.keys(aliases).length === 0) {
-    return null
-  }
-
-  return {
-    name: 'local-package-aliases',
-    setup(build) {
-      // Intercept imports for aliased packages
-      for (const [packageName, aliasPath] of Object.entries(aliases)) {
-        build.onResolve({ filter: new RegExp(`^${packageName}$`) }, () => {
-          // Return the path to the local package dist
-          return { path: aliasPath, external: true }
-        })
-
-        // Handle subpath imports like '@socketsecurity/lib/spinner'
-        build.onResolve({ filter: new RegExp(`^${packageName}/`) }, args => {
-          const subpath = args.path.slice(packageName.length + 1)
-          return { path: path.join(aliasPath, subpath), external: true }
-        })
-      }
-    },
-  }
-}
-
 // Build configuration for CommonJS output
 export const buildConfig = {
   entryPoints,
@@ -64,7 +32,8 @@ export const buildConfig = {
   format: 'cjs',
   platform: 'node',
   target: 'node18',
-  sourcemap: true,
+  // Enable source maps for coverage (set COVERAGE=true env var)
+  sourcemap: envAsBoolean(process.env.COVERAGE),
   // Disable minification for better Node ESM interop
   // Node ESM requires clear exports: module.exports = { foo, bar }
   minify: false,
@@ -73,9 +42,6 @@ export const buildConfig = {
   metafile: true,
   logLevel: 'info',
 
-  // Use plugin for local package aliases (built-in alias requires bundle: true)
-  plugins: [createAliasPlugin()].filter(Boolean),
-
   // Note: Cannot use "external" with bundle: false
   // esbuild automatically treats all imports as external when not bundling
 

registry/scripts/build-js.mjs

@@ -9,13 +9,16 @@ import { fileURLToPath } from 'node:url'
 import { build, context } from 'esbuild'
 import fg from 'fast-glob'
 
-import { printError, printSuccess } from '../../scripts/utils/cli-helpers.mjs'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
 import {
   analyzeMetafile,
   buildConfig,
   watchConfig,
 } from '../.config/esbuild.config.mjs'
 
+const logger = getDefaultLogger()
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.join(__dirname, '..')
 const srcPath = path.join(rootPath, 'src')
@@ -112,7 +115,7 @@ async function buildJS() {
     return 0
   } catch (error) {
     if (!isQuiet) {
-      printError('JavaScript build failed')
+      logger.error('JavaScript build failed')
       console.error(error)
     }
     return 1
@@ -140,11 +143,11 @@ async function watchJS() {
             build.onEnd(result => {
               if (result.errors.length > 0) {
                 if (!isQuiet) {
-                  printError('Rebuild failed')
+                  logger.error('Rebuild failed')
                 }
               } else {
                 if (!isQuiet) {
-                  printSuccess('Rebuild succeeded')
+                  logger.success('Rebuild succeeded')
 
                   if (result?.metafile && isVerbose) {
                     const analysis = analyzeMetafile(result.metafile)
@@ -173,7 +176,7 @@ async function watchJS() {
     await new Promise(() => {})
   } catch (error) {
     if (!isQuiet) {
-      printError('Watch mode failed')
+      logger.error('Watch mode failed')
       console.error(error)
     }
     return 1

registry/scripts/build.mjs

@@ -7,23 +7,22 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { build, context } from 'esbuild'
-import colors from 'yoctocolors-cjs'
 import fg from 'fast-glob'
+
+import { isQuiet } from '@socketsecurity/lib/argv/flags'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { printFooter, printHeader } from '@socketsecurity/lib/stdio/header'
+
 import {
   analyzeMetafile,
   buildConfig,
   watchConfig,
 } from '../.config/esbuild.config.mjs'
-import { isQuiet } from '../../scripts/utils/flags.mjs'
-import {
-  logger,
-  printCompletedHeader,
-  printFooter,
-  printHeader,
-} from '../../scripts/utils/helpers.mjs'
 import { parseArgs } from '../../scripts/utils/parse-args.mjs'
 import { runSequence } from '../../scripts/utils/run-command.mjs'
 
+const logger = getDefaultLogger()
+
 const rootPath = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
   '..',
@@ -432,7 +431,7 @@ async function main() {
       }
 
       if (!quiet) {
-        printCompletedHeader('Build Cleaned')
+        logger.success('Build Cleaned')
       }
 
       // Run source and types builds in parallel.
@@ -463,9 +462,9 @@ async function main() {
     // Print final status and footer.
     if (!quiet) {
       if (exitCode === 0) {
-        console.log(colors.green('✓ Build completed successfully!'))
+        logger.success('Build completed successfully!')
       } else {
-        console.error(colors.red('✗ Build failed'))
+        logger.fail('Build failed')
       }
       printFooter()
     }

registry/scripts/post-build-transform.mjs

@@ -8,6 +8,10 @@ import { readFileSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
+const logger = getDefaultLogger()
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.join(__dirname, '..')
 const indexPath = path.join(rootPath, 'dist', 'index.js')
@@ -41,8 +45,8 @@ try {
   // Write back the transformed content
   writeFileSync(indexPath, transformedContent, 'utf8')
 
-  console.log('✓ Transformed exports for Node ESM interop')
+  logger.success('Transformed exports for Node ESM interop')
 } catch (error) {
-  console.error('Post-build transform failed:', error.message)
+  logger.error(`Post-build transform failed: ${error.message}`)
   process.exit(1)
 }

registry/scripts/utils/get-local-package-aliases.mjs

@@ -7,8 +7,12 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import colors from 'yoctocolors-cjs'
+import { getDefaultLogger } from '@socketsecurity/lib/logger'
+
 import { runCommand } from './utils/run-command.mjs'
 
+const logger = getDefaultLogger()
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.resolve(__dirname, '..')
 const registryPath = path.join(rootPath, 'registry')
@@ -20,7 +24,6 @@ const isQuiet = args.includes('--quiet') || args.includes('--silent')
 async function main() {
   // Build the @socketsecurity/registry package.
   // This is required before running tests that import from it.
-
   // Pass all arguments through to the registry build script.
   const buildArgs = ['run', 'build']
   if (args.length > 0) {
@@ -33,7 +36,7 @@ async function main() {
 
   if (exitCode !== 0) {
     if (!isQuiet) {
-      console.error(colors.red('✗ Failed to build @socketsecurity/registry'))
+      logger.error(colors.red('✗ Failed to build @socketsecurity/registry'))
     }
     process.exitCode = exitCode
     return
@@ -43,6 +46,6 @@ async function main() {
 }
 
 main().catch(error => {
-  console.error(colors.red('✗ Build failed:'), error)
+  logger.error(colors.red('✗ Build failed:'), error)
   process.exitCode = 1
 })