feat: SourceAdapter pattern + SourceRegistry (#1)

[bradygaster]

Summary

Implements Issue #1: Architecture Refactor — SourceAdapter Pattern + SourceRegistry

Changes

Refactored the discovery layer from monolithic \content.ts/\community.ts\ into a pluggable adapter pattern inspired by Squad SDK's SkillSource pattern:

New Files

• src/discovery/adapters/types.ts - SourceAdapter interface, AdapterValidation, RegistryResult
• src/discovery/adapters/helpers.ts - Shared helpers: generateCanonicalId(), truncate(), isAspireRelated(), isExcluded()
• src/discovery/adapters/rss.ts - RSSSourceAdapter (extracted from content.ts)
• src/discovery/adapters/github.ts - GitHubSourceAdapter (extracted from community.ts)
• src/discovery/adapters/registry.ts - SourceRegistry with parallel execution via Promise.allSettled()
• src/discovery/adapters/index.ts - Module exports + createDefaultRegistry() factory

Modified Files

• src/index.ts - Uses SourceRegistry instead of direct discoverContent()/discoverCommunity() calls
• src/discovery/content.ts - Now a backward-compat facade redirecting to RSSSourceAdapter
• src/discovery/community.ts - Now a backward-compat facade redirecting to GitHubSourceAdapter

Architecture

• SourceAdapter interface:
  ame, \displayName, \channel, \�alidate(), \discover(state)\
• SourceRegistry: Parallel execution with graceful degradation (failed adapters logged, others continue)
• Validation first: Each adapter validates before discovery
• Promise.allSettled(): Per-adapter isolation (not Promise.all + try/catch)
• No new dependencies: Zero npm packages added

Testing

✅ TypeScript builds with zero errors (strict mode)
✅ Application runs successfully
✅ Same output: 9 report files generated in AspireContentEngine/
✅ 127 unique items discovered (RSS + GitHub)
✅ Graceful degradation: GitHub warning logged when GITHUB_TOKEN not set

Extensibility

New discovery sources can be added by:

1. Implementing SourceAdapter interface
2. Calling registry.register(new YourAdapter())
3. No changes needed to orchestrator (src/index.ts)

Closes #1

[bradygaster]

✅ LGTM from Stringer — SDK Pattern Compliance Review

I wrote the architectural design for this refactor (stringer-issue1-sdk-design.md). This implementation is a faithful execution of that design.

Checklist — All Passing

Design Spec	Status	Evidence
SourceAdapter interface (name, displayName, channel, validate, discover)	✅	types.ts:14-20 — exact match
AdapterValidation (valid, reason?, warnings?)	✅	types.ts:8-12 — exact match
RegistryResult (results, errors, skipped, timing)	✅	types.ts:22-27 — exact match
SourceRegistry (register, list, validateAll, discoverAll)	✅	registry.ts — all 4 methods
Promise.allSettled() not Promise.all()	✅	registry.ts:35 + registry.ts:83 — both paths
Explicit registration, not filesystem auto-discovery	✅	index.ts:16-21 — createDefaultRegistry() with explicit register() calls
Error isolation (log + continue)	✅	Double-layer: registry catches + adapter-internal catches
Adapters own their constants	✅	RSS_FEEDS in rss.ts, GITHUB_QUERIES in github.ts — no shared config coupling
Scope boundary: discovery only	✅	All files under src/discovery/adapters/ — dedupe/classify/analyze untouched

Minor Deviation — Acceptable

My design spec included an AdapterError class mirroring Squad SDK ErrorFactory.wrap(). The implementation uses plain Error objects instead. This is the right call — the registry already provides error isolation via RegistryResult.errors. Custom error class is over-engineering at this stage.

Architecture Notes

• Shared helpers correctly factored — adapter-agnostic utilities
• createDefaultRegistry() factory replaces hardcoded calls, exactly as designed
• Future adapters just implement SourceAdapter + register() — zero changes to existing code

Verdict: APPROVE. Ship it. 🚢

[FatiiFuad]

Project Plan fi Requirements
Maal gochuu barbaadde app keessatti ifteessi (features, UI, backend, mobile/web)
Examples: login system, dashboard, payment, notifications, settings
2. Repo fi Folder Structure
Repo kee “Kufankas-app” jira ✔️
Folder structure qopheessi:
/mobile → Flutter files (Android + iOS)
/web → React files
/backend → Node.js / API files
/assets → images, icons, fonts
3. Development Environment
PC ykn laptop irratti install godhi:
Flutter (mobile)
Node.js + React (web)
VS Code (code editor)
Git (version control)
4. Mobile App Development (Flutter)
Main file: main.dart
Screens: Home, Login, Dashboard, Profile
Widgets: Buttons, Forms, Lists
State management: Provider, Riverpod ykn Bloc
Testing locally: flutter run
5. Web App Development (React)
Main file: App.js
Components: Header, Footer, Sidebar, Pages
Routing: React Router
State management: Redux / Context API
Testing locally: npm start
6. Backend Development
Server + API endpoints
Example: Node.js + Express
Features: authentication, database CRUD, notifications
Database: Firebase, MongoDB, MySQL
7. Integrate Frontend & Backend
Mobile & web apps connect API
Test data flow (login, submit forms, fetch data)
8. Testing
Mobile: Emulator / Real device
Web: Browser testing
Test all features (login, dashboard, notifications)
9. Build & Deployment
Mobile:
Android: flutter build apk
iOS: flutter build ios
Web:
npm run build → host on Netlify / Vercel / Firebase
10. Maintenance & Updates
Bug fixes
Feature updates
Version control with Git

[FatiiFuad]

https://github.com/fatifuad/Kufankas-app