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

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 #171 — ESLint 10 migration (introduced the workaround)
• #169 — ESLint 10 upgrade issue

eslint.config.mjs と cli/src/bin/bgagent.ts から始め、次に PR #171 と、shebang に関する eslint-plugin-license-header の動作を確認します。プラグインが許可されたプリアンブルをサポートしているか確認し、サポートしていない場合は upstream-fix、custom-rule、alternative-plugin の各オプションを比較します。完了の条件は、shebang を含むファイルで実行可能ヘッダーが維持され、その直後にライセンスヘッダーが引き続き適用され、空行が最大 1 行であることです。