feat(extensions): the extension manager facade

[scottlovegrove]

Slice 7 of 7, on top of slice 6. This completes the library half of phase 1.

Ties the slices together behind createExtensionManager, which is the only thing a host CLI needs to call.

Includes the version-range check behind an extension's requires field. A range the running CLI does not satisfy is a warning rather than a refusal: upgrading the CLI should not silently break an extension that still works.

Also records the subsystem in CODEBASE.md, including why nothing in the directory imports from the rest of the repo.

Next, in a separate PR: the td extension command group, the src/index.ts wiring, the command-token lookup change, --user scoping, doctor checks and SKILL_CONTENT.

Stack: #521 core · #522 discovery · #523 dispatch · #524 tools · #525 install · #526 upgrade · #527 manager

[doistbot]

This PR completes the library half of phase 1 by tying the extension slices together behind createExtensionManager, adding the fail-open requires version-range check, and documenting the subsystem in CODEBASE.md. Few things worth tightening:

• upgrade() passes selectors straight through without deduping after normalizeSelector, so aliased selectors (e.g. ['goals', 'td-goals']) can trigger two concurrent upgrades against the same directory — dedupe by normalized name first.
• The range parser splits comparators on whitespace, so a valid range like >= 4.0.0 misreads 4.0.0 as an exact-match comparator; parse operators with optional trailing whitespace and add a test for this form.
• find() discovers and describes every installed extension before picking one, making dispatch, remove, and targeted upgrade needlessly inspect all extensions; add a targeted lookup/describe path.

I also included a few optional follow-up notes in the details below.

Optional follow-up notes (7)

• src/lib/extensions/version-range.ts:73: An empty || alternative is treated as a satisfied clause (comparators.length === 0 returns true), so '>=9.0.0 ||' (or a leading/consecutive ||) makes the whole range pass and suppresses the warning even though the parseable part is unmet. Drop empty clauses before some, returning true only when no non-empty clause remains.
• src/lib/extensions/version-range.ts:72: A hyphen range like 4.0.0 - 5.0.0 is half-parsed rather than passed through: the split yields comparators {='4.0.0'}, undefined (for -), and {='5.0.0'}, so td 4.5.0 fails the range even though it sits inside it — producing exactly the spurious warning this module's header says false negatives should not cause, since an unparseable token makes the clause pass but parseable ones still enforce equality. Either reject clauses containing an unparseable comparator wholesale (treat the clause as satisfied), or explicitly document hyphen ranges as unsupported; the current middle ground silently misjudges them.
• src/lib/extensions/manager.ts:188: The EXTENSION_NOT_FOUND CliError is built twice in this file (here and in requireExtension above) with the same code, message, and hint. Extract one notFound(name) helper and call it from both paths so the user-facing message and hint cannot drift between the single-selector and batch paths.
• src/lib/extensions/version-range.test.ts:24: The caret test says it covers the 0.x special case, but it only exercises ^0.2.3 (the minor > 0 branch). The ^0.0.x branch in upperBound (return 0.0.${patch + 1}) is never hit, so a regression there would pass. Add satisfiesRange('0.0.3', '^0.0.3') as true and satisfiesRange('0.0.4', '^0.0.3') as false.
• src/lib/extensions/manager.test.ts:72: The test title promises the error points at the list command, but the assertion only checks code: 'EXTENSION_NOT_FOUND'. The hint (Run \td extension list`) is the user-visible behavior being named, and it can be dropped or mistyped without this test failing. Assert the message or hintscontainsextension list` too.
• src/lib/extensions/manager.test.ts:149: manager.upgrade has its own EXTENSION_NOT_FOUND branch for unknown selectors (it does not delegate to require), and nothing in this suite exercises it. A regression there would break the future td extension upgrade <name> error path with no failing test. Add a case asserting makeManager().upgrade(['ghost']) rejects with code: 'EXTENSION_NOT_FOUND' and a list-command hint.
• src/lib/extensions/manager.test.ts:46: Low-value test: this only asserts join(dataDir, 'extensions'), a constant. The isEmpty test below already verifies behaviorally that extensions are discovered from <dataDir>/extensions (it writes a fixture there and watches isEmpty() flip). I'd delete this test and let the behavioral one carry the contract.

_{Share Feedback • Review Logs}

[pawelgrimm]

@scottlovegrove Sorry, I ran out of time today. I'll get a review in tomorrow!

[doist-release-bot]

🎉 This PR is included in version 5.4.0-next.1 🎉

The release is available on:

• npm package (@next dist-tag)
• GitHub release

Your semantic-release bot 📦🚀