refactor(website): SMI-1376 extract shared Skill types, utils, and ca…

[hytonylee]

Summary

Extracts five helpers duplicated across skills/index.astro and skills/[id].astro into shared, typed modules, and converts both pages from is:inline script blocks to bundler-visible <script> tags. This is the foundation ticket for the broader skills-directory refactor — subsequent tickets in the series depend on these types and utilities existing.

Ticket

SMI-1376

Changes

• src/types/skills.ts — wire-format Skill (snake_case API response shape), AlsoInstalled, SearchState discriminated union, re-exports QualityTier
• src/lib/skills-utils.ts — TRUST_BADGE_CLASSES, escapeHtml, formatNumber; re-exports getQualityTier and TIER_THRESHOLDS from the existing quality-tiers.ts canonical source
• src/data/categories.ts — CategoryMeta, SkillItem, and CATEGORIES array lifted out of [id].astro frontmatter
• src/env.d.ts — adds _rateLimitInterval and hideRateLimitToast to the global Window interface (required for TypeScript to accept the rate-limit countdown logic)
• skills/index.astro — removes is:inline + define:vars, switches to bundled <script> with imports; SSR value (FEATURED_SKILL_IDS) passed via data attribute on a hidden config element
• skills/[id].astro — same conversion; skillId and CATEGORIES/CategoryMeta/SkillItem definitions replaced with imports; removes now-resolved SMI-4907 migration comment

Checklist

Code Quality

• TypeScript compiles without errors (npm run typecheck)
• Linting passes (npm run lint)
• Tests added/updated and passing (npm test) — no behavioural logic changed; utilities are re-exports or thin wrappers with no branching to unit-test
• No console.log statements in production code

Security

• No hardcoded secrets or credentials
• Input validation added for user-provided data — escapeHtml was already the sanitisation boundary; no new user input surface added
• Security checklist reviewed (if applicable)

Mock Data Review (SMI-763)

• No mock data in production code paths
• Mock data isolated in test fixtures (tests/fixtures/)
• Environment flag (SKILLSMITH_USE_MOCK) controls mock vs real data
• Real service integrations work correctly when mock mode disabled

Documentation

• JSDoc added for new public functions — file-level JSDoc on all three new modules
• README/CLAUDE.md updated if needed — no new patterns introduced
• ADR created for significant architectural decisions — refactor only, no architectural decision

Testing

• Unit tests — no new logic to unit-test; utilities delegate to existing tested functions (getQualityTier, formatNumber)
• Integration tests — n/a
• Manual testing — verify the three routes below in a local npm run dev session inside packages/website:

Route	What to check
/skills	Search returns cards with trust badges, tier dots, org-match badge; featured skills load on initial state
/skills/development (any category slug)	Category landing page renders h1, description, top-skills grid, JSON-LD in page source
/skills/<any-real-skill-id>	Skill detail renders name, author, trust badge, star count, tags, install commands

E2E Tests (Required for MCP/Install changes)

• n/a — website-only change, no MCP or install path affected

Screenshots (if applicable)

N/A — refactor only, no visual changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
website	Error		Jun 5, 2026 12:13am

[github-actions]

E2E Test Results

Phase	Status
CLI E2E	❌ failure
MCP E2E	❌ skipped

[github-actions]

Website Preview

Deploy failed. No preview URL was captured.

View logs for details.

[wrsmith108]

Thanks for this, @hytonylee — closing it after a detailed look during the June repo triage, with a clear path to redo it cleanly. Your original commit is preserved on the branch (restored to 5ccd14b7); nothing here is lost.

Why we're closing rather than merging

I rebased the branch onto main to clear the staleness, which surfaced two things:

1. Conflict with the trust-tier fix (SMI-5217 / fix(website): reconcile trust-tier rendering to 5-tier ApiTrustTier (SMI-5217) #1401). main reworked skills/index.astro + skills/[id].astro to the canonical 5-tier public set (official | verified | curated | community | unverified) via the shared constants/trust-tier-badges.ts. This PR carried the legacy 4-tier vocabulary (experimental/unknown, missing official) in the extracted types/skills.ts + skills-utils.ts, so merging as-is would have reintroduced the bug SMI-5217 just fixed.

2. The core extraction isn't viable yet (architectural). The goal — extract shared Skill types + utils for the pages to import — can't work while the pages render via Astro is:inline + define:vars scripts, which cannot use ESM imports. After resolving the conflict in favour of main's working 5-tier code, types/skills.ts and skills-utils.ts ended up with no consumers (orphaned dead code, no tests). Separately, the [id].astro change had replaced the ~340-line client detail-script with a 2-line stub, which would have broken the detail page.

Path forward (tracked on #1376)

The extraction is the right idea — it's just blocked on migrating those inline scripts to bundled <script> blocks first (tracked as SMI-4907). Once that lands, the shared types/skills.ts + skills-utils.ts can be imported by the pages as intended.

One piece is independently good and worth keeping when #1376 is redone: extracting the inline 78-line CATEGORIES array out of [id].astro into data/categories.ts (frontmatter can import that fine — it's only the is:inline client scripts that can't).

Leaving #1376 open to redo cleanly after SMI-4907. Thanks again — the instinct to de-duplicate these pages is correct, just sequenced after the script migration.

[github-actions]

E2E Test Results

Phase	Status
CLI E2E	❌ failure
MCP E2E	❌ skipped