@portkey-ai/hoot 0.2.0

package/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to Hoot
+
+Thank you for your interest in contributing to Hoot! We welcome contributions from the community.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/yourusername/hoot.git
+   cd hoot
+   ```
+3. Install dependencies:
+   ```bash
+   npm install
+   ```
+4. Start the development environment:
+   ```bash
+   npm run dev:full
+   ```
+
+## Development Workflow
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+2. Make your changes
+3. Test your changes locally
+4. Commit your changes:
+   ```bash
+   git commit -m "feat: add your feature description"
+   ```
+5. Push to your fork:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+6. Open a Pull Request
+
+## Coding Standards
+
+- Use TypeScript for all new code
+- Follow the existing code style
+- Add comments for complex logic
+- Keep components small and focused
+- Use meaningful variable and function names
+
+## Testing
+
+Before submitting a PR:
+- Test all features manually
+- Ensure no TypeScript errors: `npm run build`
+- Check that both backend and frontend work together
+
+## Commit Message Format
+
+We follow conventional commits:
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation changes
+- `style:` - Code style changes (formatting, etc.)
+- `refactor:` - Code refactoring
+- `perf:` - Performance improvements
+- `test:` - Adding tests
+- `chore:` - Build process or auxiliary tool changes
+
+## Areas We Need Help
+
+- [ ] Resource testing UI
+- [ ] Prompt testing UI
+- [ ] Keyboard shortcuts
+- [ ] Browser extension for CORS bypass
+- [ ] Additional transports (stdio in Electron)
+- [ ] UI/UX improvements
+- [ ] Documentation improvements
+- [ ] Bug fixes
+
+## Questions?
+
+Feel free to open an issue for:
+- Bug reports
+- Feature requests
+- Questions about the codebase
+- Discussion about improvements
+
+Thank you for contributing! 🦉
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Hoot Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/PACKAGE_PREP_SUMMARY.md

@@ -0,0 +1,169 @@
+# 📦 Hoot - Open Source Release Preparation Complete
+
+## ✅ What's Been Done
+
+### 1. **Documentation Organization**
+- ✅ Created `docs/` directory
+- ✅ Moved 24+ documentation files from root to `docs/`
+- ✅ Removed redundant/outdated documentation files
+- ✅ Created comprehensive `docs/README.md` index
+- ✅ Cleaned up duplicate README files (removed HOOT_README.md, SCREECH_README.md)
+
+### 2. **Project Structure Cleanup**
+- ✅ Created `tests/` directory and moved test files
+- ✅ Created `examples/` directory for example files
+- ✅ Created `bin/` directory for CLI scripts
+- ✅ Organized root folder - now clean and professional
+
+### 3. **NPX Support**
+- ✅ Created `bin/hoot.js` - CLI entry point
+- ✅ Added `bin` field to package.json
+- ✅ Made script executable with proper shebang
+- ✅ Auto-starts both backend and frontend servers
+- ✅ Opens browser automatically
+
+### 4. **Package Configuration**
+- ✅ Updated package.json with:
+  - `bin` field for CLI support
+  - `start` script for easy launching
+  - `prepublishOnly` script for auto-build
+  - Repository, bugs, and homepage URLs
+  - Proper keywords and description
+  - Node.js version requirement (>=18.0.0)
+
+### 5. **Publishing Preparation**
+- ✅ Created `.npmignore` to exclude dev files
+- ✅ Created `CONTRIBUTING.md` for contributors
+- ✅ Created `LICENSE` file (MIT)
+- ✅ Created `PUBLISHING.md` with npm publishing guide
+- ✅ Updated README.md with npx instructions
+
+### 6. **Documentation Cleanup**
+Removed redundant/obsolete files:
+- ❌ HOOT_README.md (duplicate)
+- ❌ SCREECH_README.md (old branding)
+- ❌ CORS.md, CORS_PROXY.md (redundant)
+- ❌ DESIGN.md (superseded by DESIGN_HOOT.md)
+- ❌ STATUS.md, WORKING.md, SUCCESS.md (dev files)
+- ❌ Multiple implementation detail files
+- ❌ UI polish summary files
+
+## 🚀 How Users Will Use Hoot
+
+```bash
+# One command to rule them all!
+npx -y hoot
+```
+
+This will:
+1. Install Hoot (if not already installed)
+2. Start the backend server (port 3002)
+3. Start the frontend dev server (port 5173)
+4. Open the browser automatically
+5. User can start testing MCP servers immediately!
+
+## 📁 Final Project Structure
+
+```
+hoot/
+├── README.md              # Main documentation with npx instructions
+├── CONTRIBUTING.md        # Contribution guidelines
+├── LICENSE                # MIT license
+├── PUBLISHING.md          # npm publishing guide
+├── package.json           # Updated with bin field
+├── .npmignore             # Excludes dev files from npm
+│
+├── bin/
+│   └── hoot.js           # CLI entry point (executable)
+│
+├── src/                  # Source code (excluded from npm)
+│   ├── components/
+│   ├── lib/
+│   ├── stores/
+│   └── ...
+│
+├── dist/                 # Built assets (included in npm)
+│   ├── index.html
+│   └── assets/
+│
+├── docs/                 # Documentation (excluded from npm)
+│   ├── README.md         # Documentation index
+│   ├── ARCHITECTURE.md
+│   ├── AUTHENTICATION.md
+│   ├── BACKEND_ARCHITECTURE.md
+│   └── ... (9 more docs)
+│
+├── tests/                # Test files (excluded from npm)
+│   └── ... (4 test files)
+│
+├── examples/             # Examples (excluded from npm)
+│   └── mock-webpage.html
+│
+├── mcp-backend-server.js # Backend server (included in npm)
+└── proxy-server.js       # Optional proxy (included in npm)
+```
+
+## 📋 Next Steps for Publishing
+
+1. **Update Repository URLs** in `package.json`:
+   - Change `yourusername` to your actual GitHub username
+   
+2. **Build the Project**:
+   ```bash
+   npm run build
+   ```
+
+3. **Test Locally**:
+   ```bash
+   npm pack
+   npm install -g ./hoot-0.2.0.tgz
+   hoot
+   ```
+
+4. **Publish to npm**:
+   ```bash
+   npm login
+   npm publish
+   ```
+
+5. **Verify**:
+   ```bash
+   npx -y hoot
+   ```
+
+## 🎯 What's Ready
+
+- ✅ Clean, organized repository structure
+- ✅ Professional documentation
+- ✅ npx support configured
+- ✅ CLI entry point ready
+- ✅ Publishing workflow documented
+- ✅ Contributing guidelines in place
+- ✅ License file included
+- ✅ .npmignore excludes dev files
+
+## 📚 Documentation Available
+
+### Root Level:
+- `README.md` - Main README with quick start
+- `CONTRIBUTING.md` - How to contribute
+- `LICENSE` - MIT license
+- `PUBLISHING.md` - How to publish to npm
+
+### docs/ Directory:
+- Architecture and design docs
+- Authentication guides
+- Troubleshooting
+- Examples
+- Changelog
+- Roadmap
+
+## 🎉 Ready to Ship!
+
+The project is now ready for open-source release. Users can start using it with just:
+
+```bash
+npx -y hoot
+```
+
+No installation, no setup, no configuration needed!

package/PRE_PUBLISH_CHECKLIST.md

@@ -0,0 +1,162 @@
+# 🚀 Pre-Publish Checklist
+
+Before publishing Hoot to npm, complete these steps:
+
+## 1. Update Repository Information
+
+Edit `package.json` and replace `yourusername` with your actual GitHub username:
+
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_GITHUB_USERNAME/hoot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YOUR_GITHUB_USERNAME/hoot/issues"
+  },
+  "homepage": "https://github.com/YOUR_GITHUB_USERNAME/hoot#readme"
+}
+```
+
+## 2. Create GitHub Repository
+
+```bash
+# If not already a git repository
+git init
+
+# Add remote
+git remote add origin https://github.com/YOUR_GITHUB_USERNAME/hoot.git
+
+# Add all files
+git add .
+
+# Commit
+git commit -m "Initial commit - Hoot v0.2.0"
+
+# Push to GitHub
+git push -u origin main
+```
+
+## 3. Test Locally
+
+```bash
+# Test the start command
+npm start
+
+# Should start backend + frontend + open browser
+# Test adding a server and executing a tool
+# Press Ctrl+C when done
+```
+
+See `TEST_LOCALLY.md` for detailed testing instructions.
+
+## 4. Build for Production
+
+```bash
+npm run build
+```
+
+This creates optimized production assets in `dist/`.
+
+## 5. Test the Package
+
+```bash
+# Create a test package
+npm pack
+
+# Install globally from tarball
+npm install -g ./hoot-0.2.0.tgz
+
+# Test it
+hoot
+
+# Should work just like npm start
+
+# Clean up
+npm uninstall -g hoot
+rm hoot-0.2.0.tgz
+```
+
+## 6. Check Package Contents
+
+```bash
+# See what will be included in the npm package
+npm pack --dry-run
+```
+
+Should include:
+- `bin/`
+- `dist/`
+- `mcp-backend-server.js`
+- `package.json`
+- `README.md`
+- `LICENSE`
+
+Should NOT include:
+- `src/`
+- `docs/`
+- `tests/`
+- `examples/`
+- `node_modules/`
+
+## 7. Login to npm
+
+```bash
+npm login
+```
+
+Enter your npm credentials.
+
+## 8. Publish
+
+```bash
+npm publish
+```
+
+If you want to use a scoped package (recommended if "hoot" is taken):
+
+```bash
+# Update package.json name to "@yourusername/hoot"
+npm publish --access public
+```
+
+## 9. Verify Published Package
+
+```bash
+# Test with npx
+npx -y hoot
+
+# Or install globally
+npm install -g hoot
+hoot
+```
+
+## 10. Create GitHub Release
+
+```bash
+# Tag the version
+git tag v0.2.0
+
+# Push tag
+git push origin v0.2.0
+```
+
+Then create a release on GitHub with the changelog.
+
+## ✅ Done!
+
+Your package is now live on npm! Users can run:
+
+```bash
+npx -y hoot
+```
+
+---
+
+## Need Help?
+
+- See `PUBLISHING.md` for detailed publishing guide
+- See `TEST_LOCALLY.md` for testing instructions
+- Check `CONTRIBUTING.md` for development workflow
+

package/PUBLISHING.md

@@ -0,0 +1,174 @@
+# Publishing Hoot to npm
+
+This guide will help you publish Hoot to npm so users can run it with `npx -y hoot`.
+
+## Prerequisites
+
+1. **npm account**: Create one at https://www.npmjs.com/signup
+2. **npm CLI logged in**: Run `npm login` and enter your credentials
+3. **Package built**: Run `npm run build` to create the production build
+
+## Pre-publish Checklist
+
+- [ ] Update version in `package.json` (follow semver)
+- [ ] Update `CHANGELOG.md` with latest changes
+- [ ] Ensure all tests pass locally
+- [ ] Check that `npm run build` completes without errors
+- [ ] Update repository URL in `package.json` to your actual GitHub repo
+- [ ] Review `.npmignore` to ensure only necessary files are included
+
+## Publishing Steps
+
+### 1. Update Package Information
+
+Edit `package.json` and update these fields:
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_USERNAME/hoot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YOUR_USERNAME/hoot/issues"
+  },
+  "homepage": "https://github.com/YOUR_USERNAME/hoot#readme"
+}
+```
+
+### 2. Build for Production
+
+```bash
+npm run build
+```
+
+This will:
+- Compile TypeScript
+- Build the Vite frontend
+- Create optimized production assets in `dist/`
+
+### 3. Test the Package Locally
+
+Before publishing, test the package locally:
+
+```bash
+# Create a tarball
+npm pack
+
+# Test installation from tarball
+npm install -g ./hoot-0.2.0.tgz
+
+# Test running it
+hoot
+
+# Clean up
+npm uninstall -g hoot
+rm hoot-0.2.0.tgz
+```
+
+### 4. Publish to npm
+
+```bash
+# First time publishing
+npm publish
+
+# If the package name is already taken, use a scope
+npm publish --access public
+```
+
+### 5. Verify the Package
+
+After publishing:
+
+```bash
+# Test with npx
+npx -y hoot
+
+# Or install globally and run
+npm install -g hoot
+hoot
+```
+
+## Post-publish Steps
+
+1. **Create a GitHub Release**
+   - Tag the version: `git tag v0.2.0`
+   - Push the tag: `git push origin v0.2.0`
+   - Create release on GitHub with changelog
+
+2. **Update Documentation**
+   - Add installation instructions to README
+   - Update examples with the published package name
+
+3. **Announce**
+   - Share on social media
+   - Post in relevant communities
+   - Update any related documentation
+
+## Updating the Package
+
+When you need to publish a new version:
+
+```bash
+# Update version (choose one)
+npm version patch  # 0.2.0 -> 0.2.1
+npm version minor  # 0.2.0 -> 0.3.0
+npm version major  # 0.2.0 -> 1.0.0
+
+# This will automatically:
+# - Update package.json
+# - Create a git commit
+# - Create a git tag
+
+# Build and publish
+npm run build
+npm publish
+
+# Push to git
+git push origin main --tags
+```
+
+## Files Included in npm Package
+
+The following files are included (see `.npmignore`):
+- `bin/` - CLI scripts
+- `dist/` - Built frontend assets
+- `mcp-backend-server.js` - Backend server
+- `package.json` - Package metadata
+- `README.md` - Documentation
+- `LICENSE` - License file
+
+The following are excluded:
+- `src/` - Source TypeScript files
+- `docs/` - Documentation files
+- `tests/` - Test files
+- `examples/` - Example files
+- Development configuration files
+
+## Troubleshooting
+
+### Package name already taken
+Use an npm scope: Change package name to `@yourusername/hoot`
+
+### Permission denied
+Run `npm login` again to authenticate
+
+### Build fails
+Check that all dependencies are installed: `npm install`
+
+### Binary not working
+Ensure `bin/hoot.js` has execute permissions: `chmod +x bin/hoot.js`
+
+## Best Practices
+
+1. **Semantic Versioning**: Follow semver for version numbers
+2. **Changelog**: Keep CHANGELOG.md up to date
+3. **Testing**: Test locally before publishing
+4. **Git Tags**: Tag releases in git
+5. **Documentation**: Keep README.md accurate and helpful
+
+## Support
+
+- GitHub Issues: https://github.com/yourusername/hoot/issues
+- npm Package: https://www.npmjs.com/package/hoot
+- Documentation: See `docs/` folder
+