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

scripts/build.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
 })

scripts/check.mjs

@@ -13,17 +13,12 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
+import { printFooter, printHeader } from '@socketsecurity/lib/stdio/header'
 
-const logger = getDefaultLogger()
-
-import {
-  printError,
-  printFooter,
-  printHeader,
-  printSuccess,
-} from './utils/cli-helpers.mjs'
 import { runCommand, runParallel } from './utils/run-command.mjs'
 
+const logger = getDefaultLogger()
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.resolve(__dirname, '..')
 const registryDistPath = path.join(rootPath, 'registry', 'dist', 'index.js')
@@ -37,7 +32,7 @@ async function main() {
     if (!existsSync(registryDistPath)) {
       const buildExitCode = await runCommand('pnpm', ['run', 'build'])
       if (buildExitCode !== 0) {
-        printError('Build failed')
+        logger.error('Build failed')
         process.exitCode = buildExitCode
         return
       }
@@ -66,14 +61,49 @@ async function main() {
         },
       },
       {
-        args: ['scripts/validate-no-link-deps.mjs'],
+        args: ['scripts/validation/no-link-deps.mjs'],
+        command: 'node',
+        options: {
+          ...(process.platform === 'win32' && { shell: true }),
+        },
+      },
+      {
+        args: ['scripts/validation/bundle-deps.mjs'],
+        command: 'node',
+        options: {
+          ...(process.platform === 'win32' && { shell: true }),
+        },
+      },
+      {
+        args: ['scripts/validation/esbuild-minify.mjs'],
+        command: 'node',
+        options: {
+          ...(process.platform === 'win32' && { shell: true }),
+        },
+      },
+      {
+        args: ['scripts/validation/no-cdn-refs.mjs'],
+        command: 'node',
+        options: {
+          ...(process.platform === 'win32' && { shell: true }),
+        },
+      },
+      {
+        args: ['scripts/validation/markdown-filenames.mjs'],
+        command: 'node',
+        options: {
+          ...(process.platform === 'win32' && { shell: true }),
+        },
+      },
+      {
+        args: ['scripts/validation/file-size.mjs'],
         command: 'node',
         options: {
           ...(process.platform === 'win32' && { shell: true }),
         },
       },
       {
-        args: ['scripts/validate-bundle-deps.mjs'],
+        args: ['scripts/validation/file-count.mjs'],
         command: 'node',
         options: {
           ...(process.platform === 'win32' && { shell: true }),
@@ -85,16 +115,19 @@ async function main() {
     const failed = exitCodes.some(code => code !== 0)
 
     if (failed) {
-      printError('Some checks failed')
+      logger.error('Some checks failed')
       process.exitCode = 1
     } else {
-      printSuccess('All checks passed')
+      logger.success('All checks passed')
       printFooter()
     }
   } catch (error) {
-    printError(`Check failed: ${error.message}`)
+    logger.error(`Check failed: ${error.message}`)
     process.exitCode = 1
   }
 }
 
-main().catch(e => logger.error(e))
+main().catch(e => {
+  logger.error(e)
+  process.exitCode = 1
+})

scripts/generate-actions-allow-list.mjs …ripts/ci/generate-actions-allow-list.mjsscripts/generate-actions-allow-list.mjs renamed to scripts/ci/generate-actions-allow-list.mjs scripts/generate-actions-allow-list.mjs renamed to scripts/ci/generate-actions-allow-list.mjs

@@ -10,7 +10,7 @@ const logger = getDefaultLogger()
 import {
   ROOT_DOT_GITHUB_ACTIONS_PATH,
   ROOT_DOT_GITHUB_WORKFLOWS_PATH,
-} from './constants/paths.mjs'
+} from '../constants/paths.mjs'
 
 /**
  * Extract action dependencies from a workflow or action file.

…ripts/inline-action-versions-as-shas.mjs …ts/ci/inline-action-versions-as-shas.mjsscripts/inline-action-versions-as-shas.mjs renamed to scripts/ci/inline-action-versions-as-shas.mjs scripts/inline-action-versions-as-shas.mjs renamed to scripts/ci/inline-action-versions-as-shas.mjs

@@ -7,7 +7,7 @@ import path from 'node:path'
 import { resolveRefToSha } from '@socketsecurity/lib/github'
 import { getDefaultLogger } from '@socketsecurity/lib/logger'
 
-import { ROOT_PATH } from './constants/paths.mjs'
+import { ROOT_PATH } from '../constants/paths.mjs'
 
 const logger = getDefaultLogger()
 

scripts/show-actions-tree.mjs scripts/ci/show-actions-tree.mjsscripts/show-actions-tree.mjs renamed to scripts/ci/show-actions-tree.mjs

@@ -10,7 +10,7 @@ const logger = getDefaultLogger()
 import {
   ROOT_DOT_GITHUB_ACTIONS_PATH,
   ROOT_DOT_GITHUB_WORKFLOWS_PATH,
-} from './constants/paths.mjs'
+} from '../constants/paths.mjs'
 
 /**
  * Extract structured dependency information from a workflow or action file.

scripts/claude.mjs

@@ -7,4 +7,4 @@
  */
 
 // Simply import and run the modular version.
-import './claude/index.mjs'
+import './claude/cli.mjs'

scripts/claude/index.mjs scripts/claude/cli.mjsscripts/claude/index.mjs renamed to scripts/claude/cli.mjs

@@ -19,12 +19,19 @@ async function runAudit(claudeCmd, options = {}) {
   log.step('Gathering project information')
 
   // Run various checks.
-  const [npmAudit, depCheck, licenseCheck] = await Promise.all([
+  const results = await Promise.allSettled([
     runCommandWithOutput('npm', ['audit', '--json']),
     runCommandWithOutput('pnpm', ['licenses', 'list', '--json']),
     fs.readFile(path.join(rootPath, 'package.json'), 'utf8'),
   ])
 
+  const npmAudit =
+    results[0].status === 'fulfilled' ? results[0].value : { stdout: '' }
+  const depCheck =
+    results[1].status === 'fulfilled' ? results[1].value : { stdout: '' }
+  const licenseCheck =
+    results[2].status === 'fulfilled' ? results[2].value : '{}'
+
   const packageJson = JSON.parse(licenseCheck)
 
   const prompt = `Perform a comprehensive audit of the project:

scripts/claude/commands/audit.mjs

@@ -9,6 +9,8 @@ import { fileURLToPath } from 'node:url'
 
 import colors from 'yoctocolors-cjs'
 
+import { LOG_SYMBOLS } from '@socketsecurity/lib/logger'
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const rootPath = path.join(__dirname, '..', '..')
 const parentPath = path.join(rootPath, '..')
@@ -91,7 +93,7 @@ const log = {
   info: msg => console.log(msg),
   progress: msg => {
     process.stdout.write('\r\x1b[K')
-    process.stdout.write(`  ∴ ${msg}`)
+    process.stdout.write(`  ${LOG_SYMBOLS.reason} ${msg}`)
   },
   step: msg => console.log(`\n${msg}`),
   substep: msg => console.log(`  ${msg}`),

scripts/claude/config.mjs

@@ -38,7 +38,8 @@ async function executeParallel(tasks, workers = 3) {
     }
   }
 
-  return Promise.all(results)
+  const settled = await Promise.allSettled(results)
+  return settled.map(r => (r.status === 'fulfilled' ? r.value : undefined))
 }
 
 /**