- Add standardized ApiResponse interface with consistent structure
- Implement proper request validation with detailed error messages
- Add response metadata (version, timestamp, requestId, processingTime)
- Include proper HTTP status codes and error handling
- Add validation for pagination parameters (limit: 1-1000, offset: >=0)
- Add health status enum validation
- Include response headers (X-Request-ID, X-Processing-Time, Cache-Control)
- Improve error logging with structured context
- Add count field to pagination response
- Follow REST API industry standards and best practices
- Increase max limit from 50 to 1000 for bulk tool fetching
- Exclude large fields (npmReadme, npmAuthor, npmMaintainers) from API response
- Reduces payload size while maintaining all necessary tool metadata
- Executor now updates TPM.js database directly when loading tools
- Update /api/tools/update-schema to use packageName+exportName lookup
- Remove schema update logic from HLLM proxy (no longer needed)
- Add /api/tools/update-schema endpoint to TPM.js to update tool parameters
- When a tool is executed, fetch its schema from the executor
- Update TPM.js database with the discovered schema (async, non-blocking)
- This ensures /api/tools returns correct inputSchema for all tools
Launch checklist implementation:
- Add Privacy Policy page (/privacy) with GDPR compliance
- Add Terms of Service page (/terms)
- Add custom 404 and error pages with helpful navigation
- Add FAQ page (/faq) covering common questions
- Add SEO meta tags with OpenGraph/Twitter cards
- Add JSON-LD structured data (Organization, WebSite, SoftwareApplication)
- Add sitemap.ts and robots.ts for search engines
- Add security headers (HSTS, CSP, X-Frame-Options) in vercel.json
- Add security.txt at /.well-known/security.txt
- Add API rate limiting (100 req/min default, 20 req/min strict)
- Add empty states in tool search for better UX
- Update AppHeader with FAQ link
- Update AppFooter with Privacy/Terms links
- Update biome.json to allow dangerouslySetInnerHTML for JSON-LD in page files
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove direct DB updates from playground
- Add /api/tools/report-health endpoint with all health logic
- Playground now reports results to web app API
- All env var / validation error detection is in one place
- Health status updates based on execution success and error type
- Fix type errors with proper null checks
When a tool is marked as BROKEN but executes successfully in the
playground, update its health status to HEALTHY. This ensures
stale health check data doesn't persist when tools are working.
Also fixes noImplicitAnyLet lint error by refactoring to const.
The search endpoint was missing importHealth, executionHealth,
healthCheckError, and lastHealthCheck fields in the response. This caused
the playground (which uses search-registry tool) to not receive health
data for displaying broken tool badges.
Added all four health fields to the tool mapping in the search response.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Create ToolHealthBadge component in @tpmjs/ui for broken tool indicator
- Create ToolHealthBanner component in @tpmjs/ui for detailed health warnings
- Integrate both components into playground ToolsSidebar:
- Badge shows in tool cards in left sidebar
- Banner shows in tool detail modal
- Update search-registry to include health fields in API responses
- Add package.json exports for new health components
These components provide consistent UI for displaying broken tool status
across the application (tool search, tool detail pages, playground).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add non-blocking health check calls to both sync endpoints:
- /api/sync/changes: Triggers health checks after tool upsert from changes feed
- /api/sync/keyword: Triggers health checks after tool upsert from keyword search
Health checks run asynchronously with 'sync' trigger source, ensuring:
- New/updated tools are validated immediately after sync
- Sync operations don't wait for health check completion
- Errors are logged but don't fail the sync
This completes Phase 2 of the health check system implementation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive health monitoring for TPMJS tools that tracks both
import and execution health via Railway executor service.
## Database Schema
- Add HealthStatus enum (UNKNOWN, HEALTHY, BROKEN)
- Add HealthCheckType enum (IMPORT, EXECUTION, FULL)
- Add health fields to Tool model:
- importHealth: tracks if tool can be loaded
- executionHealth: tracks if tool can execute
- lastHealthCheck: timestamp of last check
- healthCheckError: stores error message
- Add HealthCheck audit table for full history
## Core Service
Create health-check-service.ts with 5 functions:
1. checkImportHealth() - Tests tool loading via /load-and-describe
2. checkExecutionHealth() - Tests execution via /execute-tool
3. generateTestParameters() - Creates minimal test params by type
4. performHealthCheck() - Full check with database updates
5. performBatchHealthCheck() - Processes tools in batches
Features:
- 30-second timeout per check
- Skips execution if import fails
- Batch processing (5 concurrent, 1s delays)
- Full audit trail in HealthCheck table
## API Endpoints
/api/sync/health-check (POST):
- Daily cron job at 2am UTC
- Checks all tools in database
- Requires CRON_SECRET auth
- Logs results to SyncLog table
- Max duration: 5 minutes
/api/tools/broken (GET):
- Lists all tools with broken health status
- Filters by importHealth='BROKEN' OR executionHealth='BROKEN'
- Includes package metadata
- Orders by lastHealthCheck DESC
## Configuration
- Add RAILWAY_EXECUTOR_URL to env.ts
- Add daily cron job to vercel.json
- Use db:push for schema changes (existing production data)
Next: Manual trigger endpoint + health filtering + UI components
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implement proper BM25 scoring algorithm in /api/tools/search
- Term frequency with saturation (k1 = 1.5)
- Length normalization (b = 0.75)
- Inverse document frequency (IDF)
- Accept recent messages via 'messages' query param for better context
- Update search-registry tool to:
- Use /api/tools/search endpoint (not /api/tools)
- Pass last 3 user messages for contextual search
- Include recentMessages in tool input schema
- Update chat API to extract and pass last 3 user messages to search
BM25 formula: Σ IDF(qi) * (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * |D| / avgdl))
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implements a complete dynamic tool loading system that allows the playground to discover and load tools from the TPMJS registry at runtime.
**Architecture:**
- Search tool package (@tpmjs/search-registry) - Searches registry for tools
- Search API endpoint (/api/tools/search) - Text-based search with scoring
- Pre-flight tool loading - Automatically searches and loads tools on every message
- Railway executor service (Deno) - Loads tools from esm.sh via HTTP imports
- Dynamic tool loader - Calls Railway to load and execute tools remotely
**Key Components:**
1. Railway Executor (apps/railway-executor/)
- Deno-based service that natively supports HTTP imports
- Endpoints: /load-and-describe, /execute-tool, /cache/stats, /cache/clear
- Deploys to Railway with deno run --allow-net --allow-env server.ts
2. Search Tool Package (packages/tools/search-registry/)
- AI SDK v6 tool for searching TPMJS registry
- Uses jsonSchema + inputSchema pattern
- Searches /api/tools/search endpoint
3. Search API (apps/web/src/app/api/tools/search/)
- Text-based search with composite scoring
- Scores: text relevance + quality boost + download boost
- Returns tool metadata with importUrl for dynamic loading
4. Dynamic Tool Loader (apps/playground/src/lib/dynamic-tool-loader.ts)
- Calls Railway service to load tools from esm.sh
- Creates tool wrappers that execute remotely
- Process-level module cache + per-conversation tracking
5. Pre-flight Loading (apps/playground/src/app/api/chat/route.ts)
- Automatically searches for tools on every user message
- Loads top 5 matching tools before agent processes request
- Merges with static tools for seamless experience
**Technical Decisions:**
- Deno over Node.js: Native HTTP import support without flags
- Remote execution: Tools run in Railway sandbox, not Vercel
- Pre-flight loading: Better UX than two-turn search pattern
- Text search: BM25 had dependency issues, simple scoring works well
**Environment Variables:**
- RAILWAY_SERVICE_URL: https://endearing-commitment-production.up.railway.app🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
BREAKING CHANGE: Complete refactoring from single-tool to multi-tool package support
Database Schema:
- Split Tool model into Package (1) and Tool (many) with one-to-many relationship
- Package stores npm metadata and package-level tpmjs fields (category, env, frameworks, tier)
- Tool stores individual tool exports with tool-level metadata (exportName, description, parameters, returns, aiAgent)
- Unique constraint on (packageId, exportName) to prevent duplicate tools
- Cascade deletes when packages are removed
Type System:
- Updated tpmjs field schema to support tools array
- Each tool has exportName, description, parameters, returns, aiAgent
- Package-level fields: category, env, frameworks shared across all tools
- Backward compatible with legacy single-tool format (auto-migrates to exportName: "default")
API Updates:
- Updated all /api/tools routes to query Tool model with Package relations
- Updated /api/tools/[slug] to accept package/export path segments
- Updated tool-executor-agent to use actual exportName instead of hardcoded "default"
- Updated metrics sync to calculate quality scores per Tool
Frontend Updates:
- Updated tool search page to display exportName as primary heading
- Updated tool detail pages to show package name as secondary info
- Removed tag-based filtering (tags moved to package level)
Manual Tool Registry:
- Added manual-tools.ts with 23 curated tools from major providers
- Created sync-manual-tools.ts script to sync manual tools to database
- Added MANUAL_TOOLS.md documentation for manual tool system
- Added GitHub workflow for automated daily sync
- Includes tools from: Vercel, Exa, Firecrawl, AWS Bedrock, Perplexity, Tavily, Superagent, Valyu
Playground Updates:
- Updated tool loader to load multiple tools per package
- Added sanitizeToolName for OpenAI API compatibility
Sync System Updates:
- Updated changes feed sync to handle multi-tool packages
- Updated keyword sync to upsert multiple tools per package
- Added orphaned tool deletion when tools removed from package.json
Migration Strategy:
- Database uses same Neon instance for dev and prod
- Schema updated via prisma db push (no migration files yet)
- All data repopulates from npm via sync system
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
API Changes:
- Track author name along with package name and reason
- Extract author from pkg.author (string or object with name field)
- Default to "unknown" if author info not available
Workflow Changes:
- Display author in format: "package-name (by author) - reason"
Example Discord output:
📋 Skipped Packages
tpmjs-threejs-tool (by john-doe) - invalid tpmjs field
@scope/package-1 (by jane-smith) - missing tpmjs field
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
API Changes:
- Track skip reason along with package name
- Changed skippedPackages from string[] to Array<{name, reason}>
- Reasons: "package not found", "missing tpmjs field", "invalid tpmjs field"
Workflow Changes:
- Format skipped packages as "package-name - reason"
- Display one package per line in Discord notification
Example Discord output:
📋 Skipped Packages
@scope/package-1 - missing tpmjs field
package-2 - invalid tpmjs field
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
API Changes:
- Track skipped package names in keyword sync endpoint
- Include skippedPackages array in API response
Workflow Changes:
- Extract skipped package names from sync response
- Display skipped packages in Discord notification as comma-separated list
- Only show "📋 Skipped Packages" field when packages are skipped
- Dynamic field construction using jq
Example Discord output:
📋 Skipped Packages
package-name-1, package-name-2, package-name-3
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
API Changes:
- Return errorMessages array in sync response (first 5 errors)
Workflow Changes:
- Display error messages in GitHub Actions logs with formatting
- Include error details in Discord notifications (first 3 errors)
- Shows errors in both console output and Discord embed
Example output:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚠️ SYNC ERRORS (4 total):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
• Failed to process pkg1: Invalid tpmjs field
• Failed to process pkg2: Network timeout
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Convert static import of executeToolWithAgent to dynamic import inside the
POST handler. This prevents the AI SDK (and its tiktoken dependency) from
being loaded at build time, which was causing WASM loading errors.
**Why this fix works:**
- Next.js 16 + Turbopack tries to analyze routes at build time
- tiktoken requires tiktoken_bg.wasm which can't load during static analysis
- Dynamic imports defer loading until runtime, avoiding build-time WASM issues
**Changes:**
- Remove: `import { executeToolWithAgent } from '@/lib/ai-agent/tool-executor-agent'`
- Add: `const { executeToolWithAgent } = await import('@/lib/ai-agent/tool-executor-agent')`
inside the stream start() handler
Build now completes successfully. Route is properly marked as dynamic (ƒ).
Resolves: "Error: Missing tiktoken_bg.wasm" during Next.js build
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add `export const dynamic = 'force-dynamic'` to `/api/tools/execute/[...slug]`
to prevent Next.js from attempting static generation at build time.
The AI SDK (used via executeToolWithAgent) requires tiktoken_bg.wasm which
cannot be loaded during static generation. Marking as dynamic ensures the
route is only executed at runtime.
Note: This partially addresses the build error but further investigation needed
for complete resolution of tiktoken WASM loading in Next.js 16 + Turbopack.
Relates to: "Error: Missing tiktoken_bg.wasm"
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**API Route Restructuring:**
- Move execute endpoint from /api/tools/[...slug]/execute to /api/tools/execute/[...slug]
- Move simulations endpoint from /api/tools/[...slug]/simulations to /api/tools/simulations/[...slug]
- Fix Next.js App Router constraint: catch-all segments must be terminal
- Update ToolPlayground component to use new endpoint paths
**Package Executor Export Fix:**
- Remove .js extensions from exports in @tpmjs/package-executor
- Change from './types.js' to './types' for proper TypeScript resolution
- Change from './executor.js' to './executor' for proper TypeScript resolution
- Fixes "Export executePackage doesn't exist in target module" build error
**Next.js Configuration:**
- Add vm2 and @tpmjs/package-executor to serverExternalPackages
- Prevents bundling VM2 which requires filesystem access to internal files
**Code Quality:**
- Add biome-ignore for excessive complexity in SSE stream handling
- Add biome-ignore for decorative loading spinner SVGs (2 instances)
Note: VM2 sandboxing still has compatibility issues with Next.js Turbopack.
This may need to be replaced with a different sandboxing approach or disabled.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Rename API route from [slug] to [...slug] for catch-all routing
- Update API handler to join slug segments for scoped packages
- Remove encodeURIComponent from frontend API call
This fixes the 404 error when accessing tool pages with scoped package names.
The sync workers will need to run to populate README data for existing tools.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Database Schema:**
- Add npmReadme, npmKeywords, npmAuthor, npmMaintainers fields to Tool model
**NPM Client:**
- Add fetchLatestPackageWithMetadata() function to fetch README and top-level metadata
- Export new PackageVersionWithReadme type
**Sync Workers:**
- Update keyword and changes sync to fetch and store README content
- Store author, maintainers, and keywords from package.json
**UI Components:**
- Create Markdown component using react-markdown with GitHub Flavored Markdown
- Add rehype-sanitize for security and remark-gfm for tables/strikethrough support
**Tool Detail Page:**
- Convert from createElement to JSX for better maintainability
- Display README in a dedicated card with proper markdown rendering
- Show NPM keywords, author, and maintainers in sidebar
- Add ThemeToggle to header
- Improve layout with better spacing and organization
This brings the tool detail pages much closer to NPM's package pages,
providing users with comprehensive information about each tool including
the full README documentation.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Next.js error: "You cannot use different slug names for the same dynamic path ('id' !== 'slug')"
Removed /api/tools/[id]/route.ts to resolve conflict with /api/tools/[slug]/route.ts
The [slug] route already handles fetching tools by package name
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Prevents lefthook from failing in CI/Vercel environments
- Only installs git hooks when in actual git repository
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add --webpack flag to build command to use Webpack instead of Turbopack
- Add maxDuration export to health route
- This should ensure API routes are properly detected and deployed as serverless functions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add /api/tools/[slug] endpoint to fetch individual tool by package name
- Create dynamic /tool/[slug] detail pages with complete tool information
- Display installation commands, usage examples, parameters, and stats
- Add breadcrumb navigation and links between search and detail pages
- Update tool search page to link to detail pages
- Show AI agent integration info, frameworks, tags, and quality scores
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add complete sync worker system for NPM package discovery and metrics:
**Sync Workers:**
- Changes Feed Sync (/api/sync/changes) - Polls NPM changes every 2 min
- Keyword Search Sync (/api/sync/keyword) - Searches tpmjs-tool keyword every 15 min
- Metrics Sync (/api/sync/metrics) - Updates downloads & quality scores hourly
**Features:**
- Secure CRON_SECRET authentication for all sync endpoints
- Comprehensive error handling with sync logs and checkpoints
- Smart package validation and filtering (skip invalid tpmjs fields)
- Automatic tool upsert with discovery method tracking
- Quality score calculation based on tier, downloads, and GitHub stars
- 5-minute timeout support for long-running sync operations
**Dependencies:**
- Add @tpmjs/npm-client to web app for NPM API integration
- Use barrel exports from npm-client package (no subpath imports)
- Add CRON_SECRET env variable validation
- Add ~/src path alias to tsconfig
**Infrastructure:**
- Configure Vercel Cron jobs in vercel.json for automated syncing
- Add publishedAt field to PackageVersion schema
- Fix Prisma JSON field handling (use undefined instead of null)
- Proper null checks for fetchLatestPackageVersion return values
**Type Safety:**
- Cast TpmjsField union type to access optional rich-tier properties
- Handle searchByKeyword array return type correctly
- Fix fetchDownloadStats to return number directly
All API routes follow Next.js 16 conventions with proper type checking.
Type-check and full build successful.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add 4 REST API endpoints for the TPMJS tool registry:
**GET /api/tools**
- Search and list tools with filtering, sorting, pagination
- Query params: q (search), category, official, limit, offset
- Returns tools with pagination metadata
- Sorts by quality score and download count
**GET /api/tools/[id]**
- Get tool details by ID (cuid) or package name
- Supports both lookup methods with OR query
- Returns full tool metadata
**POST /api/tools/validate**
- Validate tpmjs field schema
- Determines tier (minimal vs rich)
- Returns validation errors with detailed messages
- Uses @tpmjs/types validateTpmjsField function
**GET /api/stats**
- Aggregate statistics about the registry
- Total tools, official tools, category breakdown
- Recent tools (last 7 days), total downloads
- Efficient parallel queries with Promise.all
All endpoints include proper error handling, TypeScript types,
and follow Next.js 16 App Router conventions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
