feat: add script to generate Hexagate import CSVs from deployment files

[mirooon]

Which Linear task belongs to this PR?

https://linear.app/lifi-linear/issue/EXSC-38/hexagate-emergencypause-testing

Why did I implement it this way?

Problem
We need a consistent set of contract addresses (diamond, Safe, timelock, peripheries) registered in Hexagate with the right tags for monitoring and policy. Doing that by hand is slow, easy to get wrong, and drifts from what we actually deploy.

Hexagate supports CSV import: each row is chainId, address, and tags, and the platform attaches those tags on import. That fits our workflow better than one-off manual entry if the CSV matches our canonical deployment sources.

Separately, we’ve seen Hexagate struggle with large CSVs (failed or flaky import/conversion). So a single “everything on one chain” export is not reliable.

Solution
Added script/tasks/generateHexagateImportCsv.ts, which builds Hexagate-ready CSVs

Checklist before requesting a review

• I have performed a self-review of my code
• This pull request is as small as possible and only tackles one problem
• I have added tests that cover the functionality / test the bug
• For new facets: I have checked all points from this list: https://www.notion.so/lifi/New-Facet-Contract-Checklist-157f0ff14ac78095a2b8f999d655622e
• I have updated any required documentation

Checklist for reviewer (DO NOT DEPLOY and contracts BEFORE CHECKING THIS!!!)

• I have checked that any arbitrary calls to external contracts are validated and or restricted
• I have checked that any privileged calls (i.e. storage modifications) are validated and or restricted
• I have ensured that any new contracts have had AT A MINIMUM 1 preliminary audit conducted on by <company/auditor>

[coderabbitai]

Walkthrough

Introduces a new TypeScript/Bun script that generates Hexagate address-import CSV files by parsing network configuration and per-network deployment artifacts. The script accepts CLI arguments for target networks and optional category filters, loads deployment data with error tolerance, deduplicates addresses by (chainId, address) while accumulating tags, and outputs sorted CSV files with deterministic ordering.

Changes

Cohort / File(s)	Summary
New Script script/tasks/generateHexagateImportCsv.ts	New Bun/TypeScript script for generating Hexagate CSV imports with CLI argument parsing, network/deployment data loading, category-based filtering, address deduplication with tag accumulation, and multi-file CSV output with configurable row limits.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Stable verify contracts #1547: Modifies network configuration and deployment JSON structures that the new script reads and parses.

Suggested labels

AuditNotRequired

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add script to generate Hexagate import CSVs from deployment files' directly and accurately describes the main change—adding a new script to generate Hexagate CSV imports.
Description check	✅ Passed	The description covers the required sections: Linear task link, problem/solution rationale, and self-review checklist. However, it omits the 'Why did I implement it this way?' section header despite providing relevant content, and the reviewer checklist items remain unchecked.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch add-hexagate-generate-import-csv-script

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

🧹 Nitpick comments (2)

script/tasks/generateHexagateImportCsv.ts (2)

49-51: Use consola and citty per project conventions.

Per coding guidelines, task scripts must use citty for CLI argument parsing and consola for logging. The current implementation uses manual argv parsing and console.* calls.

 import { mkdir, readFile, writeFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { defineCommand, runMain } from 'citty'
+import consola from 'consola'

This would also require refactoring parseArgs to use citty's argument definition pattern and replacing all console.log/console.warn/console.error calls with consola.log/consola.warn/consola.error. As per coding guidelines: "CLI: use citty; logging via consola."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@script/tasks/generateHexagateImportCsv.ts` around lines 49 - 51, Replace
manual argv parsing and console.* usage with the project's citty + consola
conventions: refactor the parseArgs function to use citty's argument
definition/parse API (declare required options, types and defaults) and return
the parsed options, and replace all console.log/console.warn/console.error calls
in this file with consola.log/consola.warn/consola.error respectively; ensure
imports are updated to import citty and consola and remove manual argv handling
so generateHexagateImportCsv.ts uses citty for CLI parsing and consola for all
logging.

---

360-363: Consider adding explicit error typing.

The error handling wrapper correctly catches and logs errors before exiting. For better error messages, consider typing the error parameter.

♻️ Suggested improvement

-main().catch((e) => {
-  console.error(e)
+main().catch((e: unknown) => {
+  consola.error(e instanceof Error ? e.message : String(e))
   process.exit(1)
 })

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@script/tasks/generateHexagateImportCsv.ts` around lines 360 - 363, The catch
handler for main currently logs an untyped error parameter (e) and exits; change
it to accept an explicitly typed error (use unknown) and normalize/log safely by
checking instanceof Error (to print error.message and error.stack) or converting
with String/inspect before calling console.error, then call process.exit(1);
update the catch callback attached to main() to perform this typed and safe
logging so error details are clearer.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@script/tasks/generateHexagateImportCsv.ts`:
- Around line 49-51: Replace manual argv parsing and console.* usage with the
project's citty + consola conventions: refactor the parseArgs function to use
citty's argument definition/parse API (declare required options, types and
defaults) and return the parsed options, and replace all
console.log/console.warn/console.error calls in this file with
consola.log/consola.warn/consola.error respectively; ensure imports are updated
to import citty and consola and remove manual argv handling so
generateHexagateImportCsv.ts uses citty for CLI parsing and consola for all
logging.
- Around line 360-363: The catch handler for main currently logs an untyped
error parameter (e) and exits; change it to accept an explicitly typed error
(use unknown) and normalize/log safely by checking instanceof Error (to print
error.message and error.stack) or converting with String/inspect before calling
console.error, then call process.exit(1); update the catch callback attached to
main() to perform this typed and safe logging so error details are clearer.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: dc37b701-dde5-4653-a3d0-395683f28dbb

📥 Commits

Reviewing files that changed from the base of the PR and between abba53f and 0457f70.

📒 Files selected for processing (1)

• script/tasks/generateHexagateImportCsv.ts