**New Sandbox Service:**
- Separate microservice for secure npm package execution
- Uses isolated-vm for V8-level isolation
- 128MB memory limit, 10s timeout
- Package caching for performance
- Express API with /execute, /health, /cache/clear endpoints
**Why Microservice:**
- VM2 doesn't work with Next.js Turbopack (requires runtime file access)
- isolated-vm doesn't work in Vercel serverless (native bindings)
- Microservice allows full Node environment with proper sandboxing
- Industry standard approach (Replit, CodeSandbox, RunKit)
**Deployment:**
- Dockerfile with isolated-vm build dependencies
- Railway.json configuration
- Health checks and auto-restart policies
- CORS configuration for Next.js integration
**Next Steps:**
1. Deploy to Railway:
cd services/sandbox-executor
railway init
railway up
2. Set SANDBOX_EXECUTOR_URL in Next.js env
3. Update API routes to call sandbox service
This provides secure, production-ready package execution outside Vercel's constraints.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**VM2 Removal:**
- Remove VM2 dependency from package-executor
- Rewrite executor to use direct package execution with require()
- Add TODO comment for future sandboxing implementation
**Why this change:**
- VM2 requires runtime filesystem access to bridge.js which doesn't work with Next.js Turbopack bundling
- Even marking as serverExternalPackages fails because VM2 uses hardcoded file paths
- Direct execution allows builds to complete while we find Next.js-compatible sandboxing solution
**Next Steps:**
- Implement proper sandboxing with isolated-vm or similar Next.js-compatible solution
- Add security measures for package execution
- Consider moving package execution to separate microservice
This unblocks CI/CD while maintaining playground functionality.
🤖 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>
**Syntax Highlighting:**
- Add react-syntax-highlighter with Solarized Light theme
- Proper language detection from markdown code blocks
- Beautiful syntax highlighting for all code examples
- Improved inline code styling with subtle borders
**Enhanced Readability:**
- Larger base typography with prose-lg
- Better contrast for text colors (zinc-700/zinc-300)
- Improved heading spacing and hierarchy
- Enhanced table styling with hover effects and better spacing
- Table headers with uppercase, bold styling
- Table cells with generous padding (px-6 py-4/py-3)
- Row hover effects for better interaction
- Better blockquote styling with blue accents
- Improved list spacing with leading-relaxed
- Enhanced image borders and shadows
**Table Improvements:**
- Professional header styling with background colors
- Better cell padding and spacing
- Hover effects on rows
- Improved borders and shadows
- Responsive overflow handling
All code blocks now have beautiful Solarized Light syntax highlighting, and the overall typography is more readable and professional.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
**Enhanced Markdown Rendering:**
- Use prose-slate for better default typography
- Add proper heading hierarchy with bottom borders on h1/h2
- Improve code block styling with better backgrounds and shadows
- Style inline code with pink/red accent colors like npm
- Better table styling with proper borders and rounded corners
- Improve link colors (blue) with hover effects
- Add better spacing throughout (margins, padding, line-height)
- Enhance blockquote styling with background colors
- Better list spacing with space-y-2
- Add proper light/dark mode support with zinc color palette
**Component Updates:**
- Custom pre component with better background and border
- Custom table wrapper with overflow handling
- Improved link component with external link detection
- Better inline code styling
The README now renders beautifully like npm.com instead of looking plain.
🤖 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>
- Rename [slug] to [...slug] for catch-all routing
- Update tool detail page to join slug segments (e.g., ['@tpmjs', 'text-transformer'] -> '@tpmjs/text-transformer')
- Remove encodeURIComponent from tool search links
- URLs now display as /tool/@tpmjs/text-transformer instead of /tool/%40tpmjs%2Ftext-transformer
This makes URLs cleaner and more readable while maintaining full compatibility with scoped npm package names.
🤖 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>
- Create new /publish page with step-by-step instructions
- Show all 3 metadata tiers (Minimal, Basic, Rich) with examples
- Include quality score explanation and real-world examples
- Add category reference and tips for success
- Update homepage with Publish navigation link
- Add Publish Your Tool promotional section to homepage
🤖 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>
- Comprehensive debugging journey from timeout to working endpoints
- Details on Turborepo monorepo build order for Vercel
- Prisma cold start optimization strategies
- Progressive debugging approach with code examples
- Performance metrics before/after optimization
- All examples reference tpmjs.com as production domain
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Change build filter from @tpmjs/web to @tpmjs/web...
- The ... suffix tells pnpm to build all dependencies first
- This fixes 'Module not found' errors for @tpmjs/env, @tpmjs/types, @tpmjs/ui
- Ensures workspace packages are built before web app tries to import them
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove --webpack flag (incompatible with Turbo)
- Remove functions config (not working as expected)
- Use direct pnpm build command
🤖 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 explicit functions configuration to vercel.json
- Set maxDuration to 60 seconds for all API routes
- This ensures Vercel properly detects and deploys API routes as serverless functions
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
The redirect was being applied to ALL routes including API routes,
causing them to return "Redirecting..." instead of executing.
Use negative lookahead regex `/((?!api).*)` to exclude /api/* paths
from the www → non-www redirect.
This ensures:
- API routes execute normally without redirection
- Page routes still redirect from www.tpmjs.com to tpmjs.com
- Follows Option 2 from the investigation plan
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Root cause: The redirect rule in /vercel.json was intercepting ALL requests
(including /api/*) before they reached the Next.js app, causing API routes
to timeout without generating any logs.
Changes:
- Move www → non-www redirect to apps/web/next.config.ts async redirects()
- Remove redirects array from root vercel.json
- Keep cron job configuration in root vercel.json
Why this fixes the issue:
- Next.js handles redirects AFTER route resolution (pages vs API routes)
- API routes execute before redirect logic is applied
- Redirects still work for pages as expected
- More idiomatic for Next.js applications
Testing:
- API routes should now respond: /api/health, /api/tools
- www.tpmjs.com should still redirect to tpmjs.com
- All existing functionality preserved
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add vercel.json to apps/web with Turborepo build command
- Configure build to use turbo build --filter=@tpmjs/web
- Ensures Vercel properly detects and builds Next.js app in monorepo structure
- Fixes API routes timing out due to incorrect project root detection
This resolves the issue where Vercel wasn't detecting the Next.js app
inside apps/web/, causing API routes to never be built as serverless functions.
Note: You must also set Root Directory to "apps/web" in Vercel dashboard:
Project Settings > General > Root Directory
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add @tpmjs/db, @tpmjs/types, @tpmjs/env to transpilePackages
- Fixes API routes timing out on Vercel due to untranspiled TypeScript imports
- Ensures all workspace dependencies are properly bundled for serverless functions
Without transpilation, Vercel couldn't properly bundle the @tpmjs/db package,
causing API route handlers to hang when trying to import Prisma client.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add redirect rule in vercel.json to redirect www.tpmjs.com → tpmjs.com
- Use permanent (301) redirect for SEO benefits
- Preserves all paths and query parameters with /:path* pattern
- Ensures canonical URL is always non-www
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace DitherHeadline (canvas-based) with simple h1 heading
- Replace AnimatedCounter components with static text
- Remove parallax scroll effect
- Remove glitch bar animations
- Removes CPU-intensive canvas dithering that was blocking page interaction
Fixes issue where homepage froze and prevented link clicks until tab closed.
Users can now interact with the page immediately on load.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add "Discover AI Tools" section with CTA buttons to tool search
- Add three feature cards highlighting search, metrics, and AI integration
- Add "Tools" link to header navigation for easy access
- Simplify header nav by removing unused Pro/Teams/Pricing buttons
Features:
- Browse/Search tools CTAs prominently displayed
- Feature cards explain key benefits (Smart Search, Quality Metrics, AI Ready)
- Direct navigation to tool search from homepage
- Responsive grid layout for feature cards
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add category dropdown filter with dynamic options from fetched tools
- Add clickable tag badges for filtering by tags (up to 10 most common)
- Implement client-side tag filtering with multi-select support
- Add "Clear Filters" button when filters are active
- Extract unique categories and tags from API responses
- Update UI with visual feedback for selected tags (default vs outline)
Features:
- Category filter integrates with API /api/tools?category param
- Tag filtering happens client-side for instant feedback
- Tags highlight when selected for better UX
- Filters persist across tab changes
🤖 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 pathNot: ['^~/'] exception to not-to-unresolvable rule
- This allows ~/env and other app-relative path aliases used in Next.js apps
- TypeScript compiler and Next.js resolve these correctly at build time
The ~ path alias is configured in apps/web/tsconfig.json and resolves to
apps/web/src. While dependency-cruiser can't resolve it during static
analysis, the actual build tools handle it correctly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add path.resolve for __dirname in ESM context to dependency-cruiser config
- Configure alias in enhancedResolveOptions to map ~ to apps/web/src
- Restore correct ~/env imports in sync routes (was incorrectly @tpmjs/env)
This fixes two issues:
1. dependency-cruiser can now properly resolve the ~ TypeScript path alias
2. Sync routes import from the correct local env file, not the package
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add "build" to type-check dependsOn in turbo.json
- Ensures packages run their own build before type-checking
- Fixes @tpmjs/db type-check failing due to missing Prisma client
- Maintains existing "^build" dependency on workspace dependencies
This ensures Prisma client generation (via db package build script)
completes before TypeScript type-checking runs, preventing CI failures.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add build script that runs 'prisma generate'
- Ensures Prisma client is generated during CI build phase
- Fixes type-check failures caused by missing PrismaClient type
This resolves CI errors:
- error TS2305: Module '"@prisma/client"' has no exported member 'PrismaClient'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Replace mock data with real API fetching using useEffect
- Add loading and error states
- Update field names to match API schema (npmPackageName, npmVersion, etc.)
- Display quality score with progress bar
- Show downloads per month instead of generic usage metric
- Add Official badge for official tools
- Support search and filtering via API query parameters
The page now fetches tools from the database through the /api/tools endpoint
and displays real NPM registry data synced by the workers.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Release @tpmjs/createblogpost v0.2.0 with initial features:
- Creates structured blog posts with frontmatter and metadata
- Supports both Markdown and MDX output formats
- Automatic slug generation, word count, and reading time calculation
- Rich TPMJS metadata for NPM registry discovery
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add test tool package to verify sync system can discover and process tools:
Package Features:
- Creates structured blog posts with frontmatter and metadata
- Supports both Markdown and MDX output formats
- Automatic slug generation from title
- Word count and reading time calculation
- SEO-friendly metadata generation
TPMJS Integration:
- Rich-tier tpmjs field with all optional metadata
- Tagged with 'tpmjs-tool' keyword for NPM discovery
- Complete parameter and return type documentation
- AI agent guidance for optimal LLM usage
- Pricing, authentication, and framework metadata
Implementation:
- Full TypeScript implementation with exported types
- Proper tsconfig and tsup build configuration
- Comprehensive README with usage examples
- Changeset for publishing workflow
- Added packages/tools/* to pnpm workspace
This package serves as an end-to-end test of the sync workers to verify:
1. NPM keyword search discovers the package
2. Changes feed picks up updates
3. tpmjs field validation works correctly
4. Rich-tier metadata is properly extracted
5. Quality score calculation functions
🤖 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>
Add 5 new slash commands for database management:
- /db-check - Check database connection and show table row counts
- /db-migrate - Create and apply Prisma migrations (production)
- /db-push - Push schema changes without migrations (development)
- /db-studio - Open Prisma Studio visual database browser
- /db-seed - Run seed script to initialize database
These commands make it easy to test database connectivity, run migrations,
view data in Prisma Studio, and seed the database with initial data.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add detailed section covering:
- Testing individual packages with --filter flag
- Testing all packages via Turborepo
- Building packages (individual and all)
- Database commands for Prisma (generate, push, migrate, studio, seed)
- Development server commands
- Pre-commit hooks (Lefthook) explanation
- Turborepo caching behavior and invalidation
- Common workflows (after pulling, creating packages, testing)
- Troubleshooting guide for common issues
This documents how to test, build, and develop in this monorepo,
including all CLI commands used during development.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Implement changes feed client for real-time package discovery
- Implement keyword search with auto-pagination support
- Implement package metadata fetcher with tpmjs field extraction
- Implement download statistics client for quality scoring
- Implement rate limiter with configurable concurrency and delays
- Implement retry logic with exponential backoff for 429 errors
All API responses validated with Zod schemas for type safety.
Rate limiter defaults: max 10 concurrent, 100ms minimum delay.
Handles scoped packages (@scope/name) correctly.
Graceful 404 handling returns null instead of throwing.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add @tpmjs/db package with Prisma ORM setup
- Define Tool model with NPM metadata and TPMJS fields
- Define SyncCheckpoint model for tracking sync worker progress
- Define SyncLog model for audit trail of sync operations
- Add Prisma client singleton with dev logging
- Add seed script for initializing sync checkpoints
- Include comprehensive README with setup instructions
Package includes:
- Complete Prisma schema matching NPM_MIRROR.md spec
- Three models: Tool, SyncCheckpoint, SyncLog
- Indexes for performance on key fields
- TypeScript support via @tpmjs/tsconfig
- Scripts for db:migrate, db:push, db:studio, db:seed
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove ProblemSection, VisionSection, EcosystemStats, and DeveloperStories
- Keep only Header, HeroSection, and Footer
- Cleaner, more focused landing page experience
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
