refactor: core CLI cleanup (dead code, dedup, testable units) + utils unit tests

[rin-st]

Tried to make some refactoring with claude and here is the result. Most of it are tests for utils. We didn't have them before but I think it's fine to have tests for utils so it would be more difficult to break them. On the other hand, utils are battle-tested and changes are rare, so tests could be redundant. What do you think?

Note 1: If we merge, I think we need to avoid combining those changes with next release (ui-tweaks, blockexplorer, yarn etc, I want to make it next version of sre-challenges)

Note 2: I also tried to refactor se-2 the same way, but the changes were so nitpicky, I think it's not even worth it to create PR there

---

Generated

TL;DR

Internal refactor of the core CLI only (src/ + templates/utils.js) — no changes to the generated app in templates/base/**. Removes dead code and hidden mutable state, deduplicates the template-copy and arg-parsing logic, splits mixed concerns into small testable units, and adds the first unit tests (28, via node:test, zero new deps).

Generated-app output verified byte-identical (including symlinks) to main for hardhat, none, and external-extension configs (non---dev runs). Behaviour is preserved for normal use; two intentional behaviour-only deltas are flagged below (create-project-directory nested-path handling, and the --dev-only .dev placeholder). +~500 / −~280 across ~23 files.

Out of scope: the solidityFramework → "general extensions" generalization (old // TODO) — that targets the extension system that is being deprecated, so the misleading TODO was removed rather than acted on.

---

Changes in detail

1. Tests (test: commit)

• Added a node:test suite (no new dependencies). yarn test runs src/**/*.test.ts via --experimental-strip-types.
• The CLI source uses extensionless, rollup-oriented imports, so a tiny resolve hook (src/test/ts-extension-resolver.mjs, registered by src/test/register.mjs) maps ./foo → ./foo.ts / ./foo/index.ts for the test run only.
• Coverage: external-extension URL parsing (getDataFromExternalExtensionArgument, getArgumentFromExternalExtensionOption), validateNpmName, and templates/utils.js (deepMerge, stringify, withDefaults, upperCaseFirstLetter).
• Converted type-only imports to import type on the tested dependency path (needed for type stripping; also general hygiene).
• ESLint: test/.mjs files are linted without type-aware rules (they're excluded from tsconfig).
• Note: running the tests requires Node ≥ 22.6 (type stripping), now declared via engines in package.json. CI's lts/* covers this. No CI step is wired for yarn test yet — can add separately if wanted.

2. Small fixes & cleanups

• prettier-format.ts — corrected the wrong copy-pasted error message and removed the unreachable result.failed check (execa rejects on failure).
• create-project-directory.ts — use fs.promises.mkdir(…, { recursive: true }) instead of spawning execa("mkdir", …); removed the same dead result.failed check. Intentional behaviour delta: also fixes Windows (where the mkdir builtin can't be spawned) and lets a nested project name (e.g. a/b/c with missing parents) succeed, where the old mkdir without -p errored.
• install-packages.ts — deduplicated the identical stdout/stderr buffer/chunk logic into one helper.
• merge-package-json.ts — dropped the dev-mode .dev write that only emitted a literal "TODO: …" placeholder (and the now-unused isDev param + call sites).
• Renamed src/declarations/merge-pacakges.d.ts → merge-packages.d.ts.
• Typed SolidityFrameworkChoices value as SolidityFramework | null instead of any.

3. copy-template-files.ts restructure

• copyOrLink is now passed as a parameter instead of a module-level mutable let reassigned at call time (removes hidden global state).
• A single getExternalExtensionPath() plus a SourcePaths object replaces the external-extension path computed (with the same dev ? … : … ternary) in three places.
• collectTemplateDescriptors() and collectArgsFileUrl() helpers replace the four near-identical descriptor-building blocks and three near-identical args-lookup blocks.

4. Arg-parsing split + global-args sync guard

• Extracted the pure parseCliArgs() into parse-cli-args.ts (now unit-tested). parseArgumentsIntoOptions is now a thin orchestrator over small steps: resolveExternalExtension, ensureCompatibleCreateEthVersion, validateProjectName, resolveSolidityFrameworkChoices. process.exit lives only in the version-compat gate, not in the parser.
• GLOBAL_ARGS_DEFAULTS is hand-copied between src/utils/consts.ts and templates/utils.js. The two copies remain — this is not deduplicated to a single source, since utils.js ships into user projects and can't import the TS const without a build step. The change only exports the templates/utils.js copy and adds a test that fails if the two definitions drift apart.

5. Stale TODO cleanup

• Removed the obsolete solidityFramework → general-extensions TODO (extensions are being deprecated).
• Replaced the prettier-format TODO with a rationale: we intentionally run the generated project's own yarn format (its config/plugins), so switching to the CLI's bundled prettier would be a regression.

---

Verification

yarn type-check, yarn lint, yarn test (28 passing), yarn build all green. Output parity confirmed by generating each config (non---dev) from this branch and from main and diffing a file+symlink manifest (sha per file, target per symlink).

Known issue (not fixed here)

The type check inside withDefaults (templates/utils.js) is effectively a no-op — the "expected" type is derived from the already-merged value, so a provided arg always matches itself. Left as-is to avoid changing template behaviour repo-wide; worth a follow-up.

Open question

No changeset included — changes are internal and behaviour-preserving for normal use (two intentional deltas noted above). Add one if the release flow expects it.

🤖 Generated with Claude Code