fix: resolve quality scan issues

Critical fixes:
- Add try-catch for JSON.parse in releases/github.ts (2 instances)
- Fix lastIndexOf('@') edge case in package-extensions.ts

External bundles fixes:
- Bundle debug, which, signal-exit, supports-color inline
- Eliminates hidden requires that would fail without node_modules

Workflow fixes:
- Replace process.exit() with throw in cover.mjs and filter.mjs
- Replace process.exit(1) with process.exitCode in main.mjs catch handler

GitHub Actions improvements:
- Add concurrency limits to CI workflow
- Document all workflow permissions with inline comments

Documentation fixes:
- Fix incorrect function names in README.md (readJsonFile → readJson)
- Fix non-existent constant in README.md (NODE_MODULES → PACKAGE, LATEST)
- Update CLAUDE.md directory structure, path aliases, build scripts, exports

Author: jdalton

.github/workflows/ci.yml

@@ -3,6 +3,10 @@ name: ⚡ CI
 # Dependencies:
 #   - SocketDev/socket-registry/.github/workflows/ci.yml
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   push:
     branches: [main]

.github/workflows/claude-auto-review.yml

@@ -9,9 +9,9 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
-  id-token: write
-  pull-requests: read
+  contents: read        # Read repository code for analysis
+  id-token: write       # Generate OIDC token for Anthropic API authentication
+  pull-requests: read   # Read PR metadata and diff for review
 
 jobs:
   auto-review:

.github/workflows/claude.yml

@@ -15,10 +15,10 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
-  id-token: write
-  issues: write
-  pull-requests: write
+  contents: read        # Read repository code for Claude analysis
+  id-token: write       # Generate OIDC token for Anthropic API authentication
+  issues: write         # Post Claude responses to issues
+  pull-requests: write  # Post Claude responses to PR comments
 
 jobs:
   claude:

.github/workflows/provenance.yml

@@ -16,8 +16,8 @@ on:
           - '1'
 
 permissions:
-  contents: write
-  id-token: write
+  contents: write   # Push git tags and create GitHub releases
+  id-token: write   # NPM trusted publishing via OIDC
 
 jobs:
   publish:

.github/workflows/socket-auto-pr.yml

@@ -19,8 +19,8 @@ on:
           - '1'
 
 permissions:
-  contents: write
-  pull-requests: write
+  contents: write       # Commit dependency updates to branches
+  pull-requests: write  # Create automated Socket.dev security PRs
 
 jobs:
   socket-auto-pr:

CLAUDE.md

@@ -112,8 +112,7 @@ src/
 ├── types.ts           # TypeScript type definitions
 ├── constants/         # Node.js, npm, package manager constants
 ├── env/              # Typed environment variable access
-├── lib/              # Core utility functions
-│   └── packages/     # Package management utilities
+├── packages/         # Package management utilities
 ├── external/         # Vendored external dependencies
 └── utils/            # Shared utilities
 
@@ -125,19 +124,19 @@ scripts/              # Build and development scripts
 test/                 # Test files
 ```
 
-**Path aliases**:
+**Path aliases** (defined in `.config/tsconfig.external-aliases.json`):
 ```
 #constants/* → src/constants/*
 #env/*       → src/env/*
-#lib/*       → src/lib/*
-#packages/*  → src/lib/packages/*
+#lib/*       → src/*
+#packages/*  → src/packages/*
 #types       → src/types
 #utils/*     → src/utils/*
 ```
 
 ### Commands
 - **Build**: `pnpm build` (production build)
-- **Watch**: `pnpm run build:watch` or `pnpm run dev` (development mode)
+- **Watch**: `pnpm run dev` (development mode)
 - **Test**: `pnpm test` (run tests)
 - **Type check**: `pnpm run check` (TypeScript type checking)
 - **Lint**: `pnpm run lint` (Biome linting)
@@ -149,26 +148,29 @@ test/                 # Test files
 
 #### Compilation
 - **Target**: TypeScript → CommonJS (ES2022)
-- **Builder**: esbuild via `scripts/build-js.mjs`
+- **Builder**: esbuild via `scripts/build/js.mjs`
 - **Type generation**: tsgo (TypeScript Native Preview)
 - **Output**: `dist/` directory
 
 #### Build Scripts
-All build scripts are Node.js modules (`.mjs`):
-- `build-js.mjs` - Main JavaScript compilation
-- `build-externals.mjs` - External dependency bundling
-- `fix-commonjs-exports.mjs` - Post-build CommonJS export fixes
-- `fix-default-imports.mjs` - Fix default import patterns
-- `generate-package-exports.mjs` - Auto-generate package.json exports
+All build scripts are Node.js modules (`.mjs`) in `scripts/`:
+- `build/js.mjs` - Main JavaScript compilation
+- `build/externals.mjs` - External dependency bundling
+- `fix/commonjs-exports.mjs` - Post-build CommonJS export fixes
+- `fix/external-imports.mjs` - Fix external import patterns
+- `fix/generate-package-exports.mjs` - Auto-generate package.json exports
 
 🚨 **FORBIDDEN**: Shell scripts (`.sh`) - Always use Node.js scripts
 
 #### Build Process
-1. Clean previous build: `pnpm run clean`
-2. Compile JavaScript: `pnpm run build:js`
-3. Generate types: `pnpm run build:types`
-4. Bundle externals: `pnpm run build:externals`
-5. Fix exports: `pnpm run fix:exports`
+The main build command (`pnpm build`) orchestrates via `scripts/build/main.mjs`:
+1. Clean previous build
+2. Build in parallel: source code, types, and externals
+3. Fix exports via `scripts/fix/main.mjs`
+
+Individual commands:
+- `pnpm run clean` - Clean build artifacts only
+- `pnpm build` - Full build (default)
 
 ### Code Style - Lib-Specific
 
@@ -250,8 +252,8 @@ Blank lines between groups, alphabetical within groups.
 All modules are exported via `package.json` exports field:
 - **Constants**: `./constants/<name>` → `dist/constants/<name>.js`
 - **Environment**: `./env/<name>` → `dist/env/<name>.js`
-- **Libraries**: `./<name>` → `dist/lib/<name>.js`
-- **Packages**: `./packages/<name>` → `dist/lib/packages/<name>.js`
+- **Libraries**: `./<name>` → `dist/<name>.js`
+- **Packages**: `./packages/<name>` → `dist/packages/<name>.js`
 - **Types**: `./types` → `dist/types.js`
 
 #### Adding New Exports
@@ -351,7 +353,7 @@ path: |
 3. `pnpm test` - Run tests (or `pnpm run cover` for coverage)
 
 #### Watch Mode
-Use `pnpm run build:watch` or `pnpm run dev` for development with automatic rebuilds.
+Use `pnpm run dev` for development with automatic rebuilds.
 
 #### Adding New Utilities
 1. Create utility in appropriate `src/` subdirectory

README.md

@@ -20,12 +20,12 @@ pnpm add @socketsecurity/lib
 ```typescript
 // Tree-shakeable exports
 import { Spinner } from '@socketsecurity/lib/spinner'
-import { readJsonFile } from '@socketsecurity/lib/fs'
-import { NODE_MODULES } from '@socketsecurity/lib/constants/packages'
+import { readJson } from '@socketsecurity/lib/fs'
+import { PACKAGE, LATEST } from '@socketsecurity/lib/constants/packages'
 
 const spinner = Spinner({ text: 'Loading...' })
 spinner.start()
-const pkg = await readJsonFile('./package.json')
+const pkg = await readJson('./package.json')
 spinner.stop()
 ```
 

scripts/build-externals/esbuild-config.mjs

@@ -153,7 +153,7 @@ function createStubPlugin(stubMap = STUB_MAP) {
 }
 
 // Shared dependencies bundled in external-pack that should be marked external in other bundles.
-const EXTERNAL_PACK_DEPS = [
+const _EXTERNAL_PACK_DEPS = [
   'has-flag',
   'signal-exit',
   'supports-color',
@@ -178,8 +178,8 @@ export function getPackageSpecificOptions(packageName) {
     // Zod has localization files we don't need.
     opts.external = [...(opts.external || []), './locales/*']
   } else if (packageName === 'debug') {
-    // Mark shared deps as external - they're bundled in external-pack.
-    opts.external = [...(opts.external || []), ...EXTERNAL_PACK_DEPS]
+    // Bundle supports-color inline to avoid external dependency.
+    // This makes debug.js fully self-contained.
   } else if (packageName === 'external-pack') {
     // Inquirer packages have heavy dependencies we can exclude.
     opts.external = [...(opts.external || []), 'rxjs/operators']
@@ -189,14 +189,8 @@ export function getPackageSpecificOptions(packageName) {
       js: 'if (module.exports && module.exports.default && Object.keys(module.exports).length === 1) { module.exports = module.exports.default; }',
     }
   } else if (packageName === 'npm-pack') {
-    // Mark shared deps as external - they're bundled in external-pack.
-    // Also mark debug and which as external since they have their own bundles.
-    opts.external = [
-      ...(opts.external || []),
-      ...EXTERNAL_PACK_DEPS,
-      'debug',
-      'which',
-    ]
+    // Bundle all deps inline to make npm-pack.js fully self-contained.
+    // This avoids hidden requires to debug, which, signal-exit, supports-color.
   } else if (packageName === '@socketregistry/packageurl-js') {
     // packageurl-js imports from socket-lib, creating a circular dependency.
     // Mark socket-lib imports as external to avoid bundling issues.

scripts/test/cover.mjs

@@ -42,9 +42,7 @@ const buildResult = await spawn('node', ['scripts/build/main.mjs'], {
   },
 })
 if (buildResult.code !== 0) {
-  logger.error('Build with source maps failed')
-  process.exitCode = 1
-  process.exit(1)
+  throw new Error('Build with source maps failed')
 }
 
 // Run vitest with coverage enabled, capturing output

scripts/test/filter.mjs

@@ -20,8 +20,7 @@ const projectRoot = path.resolve(__dirname, '..')
 // Find all coverage JSON files
 const coverageDir = path.join(projectRoot, 'coverage')
 if (!fs.existsSync(coverageDir)) {
-  logger.error('Coverage directory not found:', coverageDir)
-  process.exit(1)
+  throw new Error(`Coverage directory not found: ${coverageDir}`)
 }
 
 const coverageFinalPath = path.join(coverageDir, 'coverage-final.json')