@archpublicwebsite/eslint-config

Reusable ESLint flat config and git-hook toolkit for Archipelago projects.

What this package includes

This package ships a ready-to-use flat config plus setup scripts for local project automation:

• createArchipelagoConfig() for building an ESLint flat config
• Git hook scripts for pre-commit and commit-message enforcement
• Setup automation that bootstraps the consumer project
• VS Code settings updates for the recommended linting workflow

Features

• Flat config based on @antfu/eslint-config
• Vue, TypeScript, Tailwind, and Nuxt-friendly defaults
• Git hooks for consistent formatting and commit validation
• Prettier remains available for editor guidance, but the global format/prettier bridge is disabled to avoid flat-config parser conflicts
• Automatic project setup on install
• Works with the Archipelago repo style rules

Requirements

Consumer projects should have these tools available when using the full setup:

pnpm add -D eslint prettier lint-staged turbo

Installation

pnpm add -D @archpublicwebsite/eslint-config

Usage

Create or update the root eslint.config.mjs:

import { createArchipelagoConfig } from '@archpublicwebsite/eslint-config'

export default createArchipelagoConfig()

Override rules when your project needs to diverge from the shared defaults:

import { createArchipelagoConfig } from '@archpublicwebsite/eslint-config'

export default createArchipelagoConfig({
  name: 'project/overrides',
  rules: {
    'no-console': 'off',
    'vue/max-attributes-per-line': 'off',
  },
})

What the setup does

On install or when you run the setup script manually, the package prepares the consumer project with:

• .hooks/pre-commit
• .hooks/prepare-commit-msg
• .hooks/commit-msg
• .hooks/post-commit
• safe-reinstall.sh (supports --check-only for pre-commit safety checks)
• scan-global.sh (global IOC scanner)
• eslint.config.mjs when one does not already exist
• .prettierrc plugin entry for prettier-plugin-tailwindcss
• .vscode/settings.json with ESLint flat-config settings
• .vscode/extensions.json with recommended extensions
• git config core.hooksPath .hooks when the project is a Git repository

VS Code integration

The setup merges ESLint-related settings into .vscode/settings.json:

{
  "eslint.useFlatConfig": true,
  "eslint.validate": [
    "javascript", "javascriptreact",
    "typescript", "typescriptreact",
    "vue", "json", "jsonc", "markdown"
  ],
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "never"
  },
  "editor.formatOnSave": true
}

Existing settings are preserved. Only the ESLint-related keys are added or updated.

Public API

The package exports:

• createArchipelagoConfig
• setup scripts under tools/

AI Implementation Guide

If you are extending or regenerating this package, keep the workflow explicit:

1. Update eslint.config.mjs when shared lint rules change.
2. Update tools/setup/install.mjs when install-time bootstrap behavior changes.
3. Update tools/git-hooks/ when hook behavior changes.
4. Keep the package export map aligned with the public API.
5. Document any new consumer dependency that the setup expects.

AI-friendly implementation notes

• Use createArchipelagoConfig() in the consumer project, not the internal setup scripts.
• Keep root scripts in sync with the hook and lint expectations.
• 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:

node node_modules/@archpublicwebsite/eslint-config/tools/setup/install.mjs

Hook wrappers reference

Root .hooks scripts should delegate to the installed package path:

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/pre-commit.mjs

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/prepare-commit-msg.mjs "$@"

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/commit-msg.mjs "$1"

#!/usr/bin/env bash
set -euo pipefail
cd "$(git rev-parse --show-toplevel)"
node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/post-commit.mjs

Publish

cd packages/eslint-config
pnpm version patch
npm publish --access public

Before publish, run:

npm pack --dry-run

Make sure the tarball contains only the intended public files: eslint.config.mjs, tools/, and README.md.

Required root scripts

{
  "scripts": {
    "lint": "pnpm lint:fix",
    "lint:check": "turbo run lint",
    "lint:fix": "((pnpm format || true) && turbo run lint --continue=always -- --fix) || true",
    "precommit": "node node_modules/@archpublicwebsite/eslint-config/tools/git-hooks/pre-commit.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"
  },
  "lint-staged": {
    "*.{js,ts,tsx,vue}": ["eslint --fix"]
  }
}

Pre-commit now runs in this order:

1. node tools/security/scan.mjs
2. bash ./safe-reinstall.sh --check-only (if present)
3. bash ./scan-global.sh (if present)
4. pnpm lint-staged

If you need to skip the global machine scan in CI or emergency situations, set:

SKIP_GLOBAL_SCAN=1

Verification

After making config changes, validate the package by checking the installed consumer workflow or by running the setup script in a test project.

License

MIT