feat: file-based development with convention-driven tool and widget discovery (#116)

* feat(weather-app): enhance weather app with file-based development and new tools

- Introduced a new configuration file (mcp.config.ts) for the weather app, enabling file-based development.
- Added new tools for fetching current weather, forecasts, and alerts, with colocated UI components.
- Implemented a daily weather briefing workflow that combines current conditions, forecasts, and alerts.
- Updated README to reflect new features and usage instructions.
- Enhanced the app's structure by removing the old server/index.ts and integrating generated server files.
- Updated package.json to include @mcp-apps-kit/codegen as a dependency for code generation.

This commit significantly improves the development experience and functionality of the weather app.

* feat(codegen): integrate jiti for TypeScript support and enhance hot reload capabilities

- Replaced dynamic import with jiti in config and serve files to support native TypeScript loading without tsx.
- Added jiti as a dependency in the codegen package for improved module handling.
- Implemented hot reload functionality in the app, allowing tool definitions to be updated at runtime without server restarts.
- Enhanced server instance to support replacing the MCP server with new tool definitions, preserving active connections.
- Updated package.json in the weather app to streamline development commands and improve build processes.

These changes significantly enhance the development experience and runtime flexibility of the application.

* feat(codegen): refactor logging and enhance global config validation

- Replaced the default logger implementation with a utility function for improved logging consistency across the codebase.
- Introduced a new function, `validateGlobalConfigFields`, to centralize and streamline validation of global configuration fields, enhancing maintainability and readability.
- Updated the `validateConfig` function to utilize the new validation logic, reducing code duplication.
- Adjusted error messages in tests to reflect the updated validation structure for clearer feedback.

These changes improve the overall structure and reliability of configuration handling in the codegen package.

* feat(weather-app): enhance weather app with UI widget support and refactor tool definitions

- Added support for UI widgets by introducing a new `uiWidgets` directory in the configuration.
- Updated the weather app's package.json and pnpm-lock.yaml to include the new `@mcp-apps-kit/ui-react-builder` dependency.
- Refactored tool definitions in the weather app to remove colocated UI components, streamlining the tool structure.
- Enhanced the code generation process to discover and bind UI widgets to tools, improving the integration of UI components.
- Updated the Vite configuration to support the new UI widget structure and ensure proper build outputs.

These changes significantly improve the modularity and flexibility of the weather app, allowing for better UI integration and development practices.

* feat(weather-app): update dependencies and refactor UI components

- Updated pnpm-lock.yaml to include lightningcss@1.30.2 and other dependencies.
- Added @tailwindcss/postcss and autoprefixer to the weather app's package.json.
- Refactored UI components in the weather app, enhancing styling and structure.
- Removed obsolete files such as index.html, App.tsx, and styles.css to streamline the project.

These changes improve the overall performance and maintainability of the weather app, ensuring a more modern and responsive UI.

* feat(weather-app): add server icon and update TypeScript configuration

- Introduced a server icon in the mcp.config.ts file, enhancing the visual representation in MCP client UIs.
- Updated the TypeScript configuration to include additional directories for better project structure and organization.

These changes improve the overall user experience and maintainability of the weather app.

* feat(codegen): enhance multi-version configuration support and validation

- Introduced support for multi-version configurations in the code generation process, allowing for version-specific tools, workflows, and UI resources.
- Added new validation functions to ensure proper structure and integrity of versioned configurations, including checks for version keys and directory structures.
- Updated the `loadConfig` and `runCodegen` functions to handle both single-version and multi-version configurations seamlessly.
- Enhanced the watcher functionality to support versioned directories, improving the development experience for multi-version applications.
- Refactored existing code to accommodate the new versioning features, ensuring maintainability and clarity.

These changes significantly improve the flexibility and usability of the code generation tool, enabling developers to manage multiple API versions more effectively.

* feat(weather-app): refactor UI components and enhance styling for weather widgets

- Refactored CSS styles for the weather app to utilize CSS custom properties for improved theming and maintainability.
- Updated widget components to align with new styling conventions, enhancing the visual consistency across the app.
- Introduced responsive design adjustments for better usability on smaller screens.
- Enhanced the structure of weather-related components, including daily briefings, current weather, forecasts, and alerts, to improve readability and organization.

These changes significantly improve the user experience and maintainability of the weather app, ensuring a more modern and responsive UI.

* feat(codegen): add middleware and handler support in code generation

- Introduced new configuration options for middleware and handlers in the code generation process, allowing for better organization and modularity.
- Updated the manifest generation to include middleware and handler imports, exports, and type definitions.
- Enhanced the discovery and analysis of middleware and handler files, ensuring proper validation and integration into the application.
- Modified the server setup to register middleware and handlers dynamically, improving the flexibility of the application architecture.

These changes significantly enhance the capabilities of the code generation tool, enabling developers to manage middleware and event handlers more effectively within their applications.

* refactor(weather-app): update tool definitions to camelCase and enhance UI integration

- Refactored tool definitions for current weather, forecast, and alerts to use camelCase naming conventions, improving consistency and readability.
- Updated integration points in UI components to align with the new tool names, ensuring seamless data handling and display.
- Enhanced the daily briefing workflow to utilize the new tool structure, improving the overall architecture and maintainability of the weather app.

These changes significantly improve the clarity and usability of the weather app's tools and UI components, fostering a more modern development approach.

* feat(weather-app): enhance data validation and TypeScript configuration

- Improved data validation in weather widgets by adding comprehensive checks for required fields, ensuring robust error handling and data integrity.
- Updated TypeScript configuration to include additional directories for middleware and handlers, enhancing project organization and modularity.
- Enhanced error handling in the code generation process to provide clearer feedback when loading manifests and configuration files.

These changes significantly improve the reliability and maintainability of the weather app, fostering a more resilient development environment.

* refactor(weather-app): update tool naming conventions and improve project structure

- Refactored tool names to camelCase for consistency across the weather app, enhancing readability and alignment with modern JavaScript practices.
- Updated the project structure in the README to reflect the new naming conventions and clarify the organization of tools and workflows.
- Removed unnecessary imports from widget files to streamline the codebase.

These changes improve the clarity and maintainability of the weather app, fostering a more organized development environment.

* feat(weather-app): implement file-based widget discovery and enhance metadata handling

- Updated the weather app to support file-based discovery of UI widgets, allowing for automatic inference of HTML paths from widget filenames.
- Refactored widget metadata definitions to utilize a new `WidgetMetadata` type, improving clarity and consistency across widget implementations.
- Modified the Vite configuration to accommodate the new `widgetsDir` option, enabling a more flexible approach to widget management.
- Enhanced error handling and validation in the code generation process to ensure robust integration of UI components.

These changes significantly improve the modularity and usability of the weather app, fostering a more organized development environment.

* chore(weather-app): update README and example files for clarity and consistency

- Enhanced the README.md with a new introduction, features overview, and improved quick start instructions for better user guidance.
- Updated example files to reflect naming conventions and improve clarity, including renaming `SearchResults.tsx` to `search-results.tsx`.
- Refined CSS styles for better readability and organization, ensuring consistent formatting across stylesheets.
- Improved TypeScript type handling in widget files to enhance type safety and maintainability.

These changes aim to improve the overall documentation and example clarity, fostering a better development experience.

* fix(weather-app): use pnpm exec for codegen CLI commands

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore(codegen): update build script to set executable permissions for CLI files

- Modified the build script in package.json to include setting executable permissions for dist/cli.js and dist/serve.js.
- Added __generated__/ directory to .prettierignore to exclude generated files from formatting.

These changes enhance the build process and ensure proper execution of generated CLI files.

* chore(codegen): add postbuild script for offline pnpm installation

- Introduced a postbuild script in package.json to handle offline pnpm installation, ensuring dependencies are installed correctly when a pnpm workspace is detected.
- This enhancement improves the build process by providing a fallback mechanism for dependency management.

* fix: address major PR review comments

- Use pathToFileURL for Windows compatibility in app.ts
- Add proper port validation (1-65535, integer-only) in serve.ts
- Guard against multiple next() calls in composeMiddleware
- Fix flaky test ordering by using find() instead of array index
- Update Node engine to >=20 for CLI tooling
- Fix hot-reload UI state: extract UIs pre-start, clear removed UIs
- Allow null in validateProtocol/validateServerRoute for versioned configs

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: address additional PR review feedback

- Update config.ts TODO to recommend Zod v4 for validation deduplication
- Fix watcher race condition with queue-based regeneration approach
- Add chokidar for cross-platform file watching (Linux support)
- Add type safety for middleware sorting with type guards and constants

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: implement shared Zod schemas for config validation

- Create shared config-schemas.ts with Zod v4 validation schemas
- Export schemas from @mcp-apps-kit/core for use by codegen
- Update config.ts to use shared schemas instead of duplicated logic
- Update config-validation.ts to use shared schemas
- Add custom error messages to enum schemas for consistent formatting
- Update tests to match new error message format

This eliminates code duplication between packages and ensures
consistent validation rules across the codebase.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat(watcher): add support for optional uiWidgets directory in file watching

- Enhanced the watcher functionality to include an optional uiWidgets directory for monitoring changes.
- Updated the setupWatcher and createStandaloneWatcher functions to add uiWidgets to the list of directories to watch if configured.

This improvement allows for greater flexibility in project structure and enhances the file watching capabilities of the codegen package.

* feat(codegen): enhance security with config path validation and recursion limits

- Introduced validation for config file paths to ensure they are within the project root and have allowed extensions, enhancing security against path traversal attacks.
- Implemented maximum recursion depth checks in directory scanning to prevent stack overflow and excessive resource usage.
- Updated file discovery functions to include path validation and recursion limits, ensuring safer file handling during code generation.
- Added comprehensive validation for tools during hot reload to prevent issues with undefined or improperly structured tool definitions.

These improvements bolster the security and reliability of the code generation process.

* feat(codegen): enhance plugin configuration validation and improve middleware processing

- Introduced a new `validatePluginsConfig` function to validate plugin arrays using a shared Zod schema, ensuring consistent error handling and validation across configurations.
- Updated existing validation functions to utilize the new plugin validation logic, simplifying the code and improving maintainability.
- Refactored middleware processing in the `generateManifest` function to analyze files in parallel, enhancing performance for large codebases.
- Added utility functions for sorting and retrieving middleware, improving code clarity and reusability.

These changes enhance the robustness of configuration validation and optimize middleware handling in the code generation process.

* feat(codegen): enhance file analysis with improved error logging and validation

- Updated the `analyzeFile` function to include an optional logger parameter for better error handling during file parsing.
- Enhanced error logging to capture and report syntax errors, aiding in debugging and improving developer experience.
- Added validation checks for tool definitions in the `validateToolsForHotReload` function, ensuring that tools have necessary properties like description and input schema.
- Introduced tests for logging parse failures and validating tool definitions, ensuring robustness in the code generation process.

These changes improve the reliability of file analysis and enhance the overall developer experience by providing clearer error messages.

* feat(codegen): improve configuration validation and enhance file analysis concurrency

- Updated the `validateConfig` function to utilize a shared Zod schema for validating optional directories, improving error handling and consistency.
- Introduced a new `withConcurrencyLimit` function to manage concurrent file analysis operations, preventing excessive memory usage in large codebases.
- Enhanced error messages for tool, workflow, UI, and middleware name collisions during manifest generation, providing actionable suggestions for resolution.
- Updated tests to reflect changes in error messages and validation logic, ensuring robustness in configuration handling.

These enhancements improve the reliability and performance of the code generation process while providing clearer guidance for developers.

* feat(codegen): enhance server code generation with improved path handling

- Refactored the `generateServerCode` and `generateVersionedServerCode` functions to accept additional parameters for output directory and project root, improving path resolution for configuration files.
- Updated the `writeServer` and `writeVersionedServer` functions to accommodate the new parameters, ensuring correct file generation.
- Removed redundant module cache clearing logic from `serve.ts`, streamlining the hot reload process.

These changes enhance the flexibility and reliability of server code generation, providing better path management for configuration files.

* feat(codegen): add sourceType option for module support in file analysis

- Updated the `analyzeFile` function to include a `sourceType` option set to "module", enhancing support for ES module syntax in file analysis.
- This change improves compatibility with modern JavaScript and TypeScript files, ensuring accurate parsing and analysis of module-based code.

These enhancements contribute to a more robust code generation process by accommodating various module formats.

---------

Co-authored-by: Gabe <gpavanello@thefork.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -51,3 +51,9 @@ specs/
 .claude
 .vercel/
 .cursor/
+.ralph/
+.devcontainer/
+.pnpm-store/
+.agent/
+ralph.yml
+PROMPT.md

.prettierignore

@@ -4,6 +4,7 @@ node_modules/
 # Build outputs
 dist/
 build/
+__generated__/
 
 # Lock files
 package-lock.json