fix(bggrep): accept a leading (?i) flag group and explain the others

[lloydsk]

What

Agents write PCRE habits into pattern, and JavaScript's RegExp has no unscoped inline flag syntax — flags are the second argument — so (?i)error is a syntax error. That cost a real tool call in practice: a search with (?i)\(fail\)|error:|… came back as Invalid regular expression: Invalid group and had to be worked around by hand. The tool also offered no way to request case-insensitivity at all, which is why its default pattern hand-writes both Error: and error:.

Change

• A leading (?i), (?m) or (?s) group is translated into the equivalent JS flags, so (?i)error searches case-insensitively.
• Only the leading position is translated. PCRE scopes a mid-pattern (?i) to the rest of the pattern, so stripping it there would silently widen the match instead of honoring it. Those still fail — now with an explanation.
• Flags are threaded through all three compile sites — worker, sync fallback, up-front validation — so they cannot disagree. The worker receives them via workerData; matchLinesWithBudget's trailing workerSource parameter became opts: { workerSource?, flags? }.
• Messages and details.pattern echo the pattern as the caller wrote it, flags included, while matching uses the translated source.

Not attempted

General PCRE compatibility. \K, atomic groups, possessive quantifiers and conditionals have no faithful JS translation, so accepting them would quietly change what a search means.

Follow-up from review (third commit)

Two gaps and one inaccuracy, all found by review:

• The hint over-suppressed. inlineFlagHint returned "" whenever the raw pattern started with a flag group — so (?is)a(?m)b (a leading group we honour plus a second group that is the real cause) produced a bare engine error with no explanation. That is the only case the hint exists for. It is now keyed on the pattern after the leading group is stripped, which keeps every earlier assertion while restoring the hint for (?is)a(?m)b and (?i)(?i)b — both now pinned by tests.
• The sync fallback's flags parameter had no test. Only the worker is reachable from the tool in this suite (worker_threads exists on Node and Bun), so a regression dropping the argument at either fallback call site would have shipped silently — precisely the bug class this branch fixes. The parity test now asserts both paths honour i, and that the flagless calls miss.
• The wording was wrong. Node 24 and Bun 1.3.6 do support scoped modifier groups ((?i:…), ES2025), which scope exactly as PCRE does — so "JS RegExp has no inline flags" was false. Every surface now says "no unscoped inline flags" and notes that a scoped group is native anywhere. That change also required updating two assertions that matched the old phrasing.

Verification

• tsc --noEmit clean.
• 227 tests pass: case-insensitive matching via (?i), the mid-pattern explanation, the translation table, the fallback/worker flag parity, and details.pattern.
• A live pi session, running the exact call that failed in the wild:

bggrep(pattern: "(?i)mixed_case_line")
   → 1 match for /(?i)mixed_case_line/ in 4 lines
     L2: MIXED_case_LINE

bggrep(pattern: "line(?i)more")
   → bggrep: invalid pattern "line(?i)more": Invalid regular expression:
     /line(?i)more/: Invalid group — JavaScript regexes have no unscoped inline flags …

Docs

The README bggrep row and the skills/run-bg Grep row state the accepted form, that a scoped group is native, and that no unscoped inline-flag syntax exists.

[github-actions]

CI report

Check	Result
tsc --noEmit	success
tests	success
npm pack --dry-run	success (7 files in tarball)

Ref: 5692bfabb042708db3386fa7f84471b7a08b0136