fix(eslint): support license headers in shebang files without disabling the rule

[scottschreckengaust]

Summary

The eslint-plugin-license-header rule reports "Superfluous new lines before license header" on files that start with a shebang (#!/usr/bin/env node) followed by the license comment. The current workaround disables the rule entirely for src/bin/**/*.ts — this hides the problem instead of fixing it.

Problem

cli/src/bin/bgagent.ts starts with:

#!/usr/bin/env node

/**
 *  MIT No Attribution
 *  ...
 */

The license-header plugin expects the license comment at line 1. The shebang line + blank line before it triggers "superfluous new lines." The --fix option can't resolve this because removing the shebang would break the executable.

Current workaround (PR #171)

// eslint.config.mjs
{
  files: ['src/bin/**/*.ts'],
  rules: { 'license-header/header': 'off' },
}

This means shebang files have NO license header enforcement — a file could lose its header and ESLint wouldn't catch it.

Desired behavior

The license-header rule should:

1. Recognize shebangs as valid preamble before the license header
2. Still enforce that the license header appears immediately after the shebang (with at most one blank line separator)

Options

1. Upstream fix: File an issue/PR on eslint-plugin-license-header to support shebang-aware header detection
2. Custom rule: Write a project-local rule that handles shebangs (more maintenance)
3. Different plugin: Evaluate alternatives (e.g., eslint-plugin-header) that may already handle shebangs
4. Plugin configuration: Check if eslint-plugin-license-header has an option for allowed preamble patterns (shebangs, @ts-check, etc.)

Related

• PR feat(tooling): upgrade ESLint 9 → 10 with flat config migration #171 — ESLint 10 migration (introduced the workaround)
• feat(tooling): upgrade ESLint 9 → 10 with flat config migration #169 — ESLint 10 upgrade issue