Skip to content

Folder-per-plugin column architecture + Zod schemas + parity check - #3

Merged
aaronjmars merged 1 commit into
mainfrom
refactor/plugin-architecture
Apr 30, 2026
Merged

aaronjmars merged 1 commit into
mainfrom
refactor/plugin-architecture

Conversation

@aaronjmars

Copy link
Copy Markdown
Collaborator

Summary

Each column type now lives in lib/columns/plugins/<id>/ with three files: plugin.ts (pure metadata + Zod schema), client.tsx (UI), server.ts (fetcher). Schemas are the single source of truth — the API route validates body.config against the plugin's schema and returns structured 400s on bad input.

A new plugins/manifest.ts is the canonical id list. Both registries (registry.ts for client UI, server-registry.ts for fetchers) are validated against it at module init, so registering on one side and forgetting the other throws loudly rather than 404'ing in production.

What landed

  • Folder-per-plugin — 16 plugins migrated; each owns its config, UI, fetcher, and cursor format end-to-end. The 160-line monolithic server-registry of inline cursor parsing is gone.
  • Zod schemas — defaultConfig is now schema.parse({}). The s(c.foo, fallback) runtime extraction pattern is gone.
  • Typed meta — each plugin declares a TMeta interface; renderers receive FeedItem<TMeta> directly (no typeof m.foo === "number" guards).
  • Capabilities — paginated, requiresEnv, rateLimitHint, refreshIntervalHintMs. Add-column dialog auto-renders a notes block when env vars or rate limits are declared.
  • Parity check — server-registry.ts validates the manifest at module init; mismatches throw immediately.
  • Categories — every plugin sets category (ai | social | news | video | blockchain | other) — wiring is in place for grouped UI when 30+ plugins justify it.
  • Template + docs — lib/columns/plugins/_template/ is a copyable starter; lib/columns/README.md walks through the contract; main README.md updated.

Test plan

  • npx tsc --noEmit clean
  • npx eslint . clean
  • npm run build succeeds (parity check passes at server init, all 4 routes generate)
  • Browser smoke test: create deck, add a Reddit + Grok Ask + YouTube column, refresh each, click Load more on Reddit
  • Verify Add-column dialog shows the new "Requires: XAI_API_KEY" / rate-limit notes
  • Verify a deliberately broken config (e.g. missing required field) returns a 400 with field-level error from the API route

🤖 Generated with Claude Code

Each column type now lives in `lib/columns/plugins/<id>/` with three files:
- `plugin.ts` — pure metadata (id, label, icon, Zod schema, capabilities)
- `client.tsx` — "use client" ConfigForm + ItemRenderer
- `server.ts` — "server-only" fetch function

The schema in plugin.ts is the single source of truth for the config
shape: API route validates body.config against it (structured 400 on bad
input), defaultConfig is `schema.parse({})`, and fetchers receive a fully
typed config. Each plugin also declares a TMeta interface so renderers
get `FeedItem<TMeta>` directly instead of `typeof m.foo === "number"`
guards.

Capabilities object replaces the lone `paginated` boolean — adds
`requiresEnv`, `rateLimitHint`, `refreshIntervalHintMs`. The Add column
dialog auto-renders a notes block when `requiresEnv` or `rateLimitHint`
is set.

A new `plugins/manifest.ts` is the canonical id list. Both registries
(`registry.ts` for client UI, `server-registry.ts` for fetchers) are
keyed by id and validated against the manifest at module init —
forgetting either half throws loudly rather than 404'ing at request time.

Includes a copyable `_template/` plugin and a `lib/columns/README.md`
walkthrough.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@aaronjmars
aaronjmars merged commit 068dcda into main Apr 30, 2026
1 check passed
@aaronjmars
aaronjmars deleted the refactor/plugin-architecture branch April 30, 2026 14:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant