diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..a3ef7da --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,181 @@ +name: Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please fill out the information below to help us resolve the issue. + + - type: textarea + id: description + attributes: + label: Describe the bug + description: A clear description of what the bug is + placeholder: When I do X, Y happens instead of Z + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to reproduce + description: Detailed steps to reproduce the behavior + placeholder: | + 1. Create a container with... + 2. Execute code... + 3. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What you expected to happen + placeholder: I expected the code to execute successfully + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What actually happened (include error messages if any) + placeholder: Got error "Cannot find module 'fs'" + validations: + required: true + + - type: dropdown + id: component + attributes: + label: Which component is affected? + description: Select all that apply + multiple: true + options: + - Runtime / Code execution + - Virtual File System (VFS) + - Node.js API shims (fs, path, http, etc.) + - npm package installation + - Vite dev server + - Next.js dev server + - Service Worker + - Web Worker / Sandbox + - TypeScript transformation + - Hot Module Replacement (HMR) + - Documentation + - Other + validations: + required: true + + - type: input + id: almostnode-version + attributes: + label: almostnode version + description: Run `npm list almostnode` or check package.json + placeholder: "0.2.11" + validations: + required: true + + - type: input + id: node-version + attributes: + label: Node.js version + description: Run `node --version` + placeholder: "v20.10.0" + validations: + required: true + + - type: dropdown + id: browser + attributes: + label: Browser + options: + - Chrome + - Firefox + - Safari + - Edge + - Other + validations: + required: true + + - type: input + id: browser-version + attributes: + label: Browser version + placeholder: "Chrome 120.0.0" + + - type: dropdown + id: os + attributes: + label: Operating System + options: + - macOS + - Windows + - Linux + - Other + validations: + required: true + + - type: dropdown + id: mode + attributes: + label: Execution mode + options: + - Same-origin (dangerouslyAllowSameOrigin) + - Cross-origin sandbox + - Web Worker + - Main thread + - Not applicable + validations: + required: true + + - type: textarea + id: code + attributes: + label: Minimal reproduction code + description: Provide the smallest code snippet that reproduces the issue + render: typescript + placeholder: | + import { createRuntime } from 'almostnode'; + import { VirtualFS } from 'almostnode'; + + const vfs = new VirtualFS(); + const runtime = await createRuntime(vfs); + const result = await runtime.execute(` + const fs = require('fs'); + // Bug happens here + `); + + - type: textarea + id: logs + attributes: + label: Console output / Error logs + description: Include relevant console output or error messages + render: shell + placeholder: | + Error: Cannot find module 'fs' + at Runtime.require (runtime.ts:123) + + - type: textarea + id: additional + attributes: + label: Additional context + description: Any other context, screenshots, or information that might help + placeholder: | + - This started happening after upgrading to version X + - Works fine in Chrome but fails in Safari + - Screenshot: [attach image] + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission checklist + options: + - label: I have searched existing issues to avoid duplicates + required: true + - label: I have tested with the latest version of almostnode + required: true + - label: I have included a minimal reproduction + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..22fdf13 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: Question or Discussion + url: https://github.com/macaly/almostnode/discussions + about: Ask questions or discuss ideas with the community + - name: Documentation + url: https://github.com/macaly/almostnode#readme + about: Check the documentation for usage guides and examples + - name: Macaly Support + url: https://macaly.com + about: Visit Macaly.com for more information diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..635d0e5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,131 @@ +name: Feature Request +description: Suggest a new feature or enhancement +title: "[Feature]: " +labels: ["enhancement", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! Please provide as much detail as possible to help us understand your request. + + - type: textarea + id: problem + attributes: + label: Problem statement + description: What problem does this feature solve? What's the use case? + placeholder: | + I'm trying to build a code playground where users can... + Currently, I have to manually... + This is frustrating because... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed solution + description: How would you like this feature to work? + placeholder: | + I would like to be able to... + The API could look like... + This would allow me to... + validations: + required: true + + - type: dropdown + id: feature-area + attributes: + label: Which area does this feature relate to? + description: Select all that apply + multiple: true + options: + - Runtime / Code execution + - Virtual File System (VFS) + - Node.js API shims + - npm package installation + - Vite integration + - Next.js integration + - Service Worker + - Web Worker / Sandbox + - TypeScript support + - Hot Module Replacement (HMR) + - Security / Isolation + - Performance + - Developer Experience (DX) + - Documentation + - Examples + - Other + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: What other solutions or workarounds have you considered? + placeholder: | + I tried using... + I could work around this by... + Other tools like X do this by... + + - type: textarea + id: examples + attributes: + label: Examples from other tools + description: Are there similar features in other tools that inspired this request? + placeholder: | + WebContainers has a feature where... + StackBlitz allows you to... + CodeSandbox shows... + + - type: dropdown + id: priority + attributes: + label: How important is this feature to you? + options: + - Critical - Blocking my work + - High - Would significantly improve my workflow + - Medium - Nice to have + - Low - Minor improvement + validations: + required: true + + - type: textarea + id: api-design + attributes: + label: API design (if applicable) + description: If this is an API change, show how you'd like it to work + render: typescript + placeholder: | + // Proposed API + const container = createContainer({ + newOption: true + }); + + - type: textarea + id: additional + attributes: + label: Additional context + description: Any other context, mockups, or examples + placeholder: | + Here's a mockup of how it could look... + This would be especially useful for... + Related to issue #123 + + - type: checkboxes + id: contribution + attributes: + label: Contribution + options: + - label: I'm willing to submit a PR to implement this feature + required: false + + - type: checkboxes + id: checklist + attributes: + label: Pre-submission checklist + options: + - label: I have searched existing issues to avoid duplicates + required: true + - label: This feature aligns with almostnode's goal of bringing Node.js to the browser + required: true diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..74bff16 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,45 @@ +# Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a professional setting + +## Enforcement Responsibilities + +Project maintainers are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. + +Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at support@macaly.com. All complaints will be reviewed and investigated promptly and fairly. + +All project team members are obligated to respect the privacy and security of the reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..e739011 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,285 @@ +# Contributing to almostnode + +Thanks for your interest in contributing to almostnode! This guide will help you get started. + +## Code of Conduct + +Be respectful, constructive, and collaborative. We're building a tool that brings Node.js to the browser - let's make it great together. + +## Ways to Contribute + +- **Report bugs** - Found something broken? Let us know +- **Suggest features** - Have ideas for improvements? We'd love to hear them +- **Fix issues** - Check our [issue tracker](https://github.com/macaly/almostnode/issues) +- **Improve docs** - Documentation improvements are always welcome +- **Add tests** - Help us improve test coverage +- **Add Node.js API shims** - Help us support more Node.js modules + +## Getting Started + +### Prerequisites + +- **Node.js 20+** - Required for development +- **npm** - Package manager +- **Modern browser** - Chrome, Firefox, Safari, or Edge + +### Development Setup + +1. **Fork and clone the repository** + +```bash +git clone https://github.com/YOUR_USERNAME/almostnode.git +cd almostnode +``` + +2. **Install dependencies** + +```bash +npm install +``` + +3. **Start development server** + +```bash +npm run dev +``` + +4. **Open examples** + +Navigate to `http://localhost:5173/examples/` to see demos + +### Project Structure + +``` +almostnode/ +├── src/ +│ ├── runtime.ts # Core runtime +│ ├── virtual-fs.ts # Virtual filesystem +│ ├── create-runtime.ts # Runtime factory +│ ├── index.ts # Main exports +│ ├── shims/ # Node.js API shims (fs, path, http, etc.) +│ ├── frameworks/ # Framework integrations (flat structure) +│ │ ├── vite-dev-server.ts +│ │ ├── next-dev-server.ts +│ │ └── ... +│ ├── npm/ # npm package manager +│ ├── worker/ # Web Worker support +│ ├── types/ # TypeScript types +│ └── utils/ # Utility functions +├── tests/ # Unit tests +├── e2e/ # End-to-end tests +└── examples/ # Demo applications +``` + +## Development Workflow + +### 1. Create a feature branch + +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/issue-description +``` + +### 2. Make your changes + +- Write clear, focused commits +- Follow existing code style +- Add tests for new features +- Update documentation if needed + +### 3. Run tests + +```bash +# Unit tests +npm test + +# Run tests once (no watch mode) +npm run test:run + +# E2E tests (requires Playwright) +npm run test:e2e + +# Type checking +npm run type-check +``` + +### 4. Build the project + +```bash +# Build library for distribution +npm run build + +# Or build with types +npm run build:publish +``` + +### 5. Test with examples + +```bash +npm run dev +# Open http://localhost:5173/examples/ +``` + +### 6. Commit your changes + +```bash +git add . +git commit -m "Add support for X" +# or +git commit -m "Fix issue with Y" +``` + +Write clear, descriptive commit messages that explain what changed and why. + +### 7. Push and create a Pull Request + +```bash +git push origin feature/your-feature-name +``` + +Then open a PR on GitHub with: +- Clear description of what changed and why +- Reference any related issues (`Fixes #123`) +- Screenshots/videos for UI changes + +## Common Tasks + +### Core Principle: Fix the Platform, Not the Package + +**The most important rule when contributing:** When a package doesn't work, the fix goes into the generic shims (fs, path, http, etc.), not into package-specific adapters. + +Never write library-specific shim code. If a package fails because it needs `fs.readFileSync`, add or improve `fs.readFileSync` in `src/shims/fs.ts`. Don't create a special adapter for that package. + +This keeps almostnode maintainable and ensures fixes benefit all packages, not just one. + +### Adding a New Node.js API Shim + +1. **Create or update the shim file** in `src/shims/` + +```typescript +// src/shims/my-module.ts +export function myFunction() { + // Implementation that works in the browser +} +``` + +2. **Register in runtime** (`src/runtime.ts`) + +```typescript +this.builtinModules.set('my-module', () => require('./shims/my-module')); +``` + +3. **Add tests** in `tests/` + +```typescript +// tests/my-module.test.ts +import { describe, it, expect } from 'vitest'; +import { createRuntime } from '../src'; +import { VirtualFS } from '../src/virtual-fs'; + +describe('my-module', () => { + it('should work', async () => { + const vfs = new VirtualFS(); + const runtime = await createRuntime(vfs); + const result = await runtime.execute(` + const mod = require('my-module'); + module.exports = mod.myFunction(); + `); + expect(result.exports).toBe(expected); + }); +}); +``` + +4. **Export from index.ts** if it's a public API + +```typescript +export * as myModule from './shims/my-module'; +``` + +### Fixing a Bug + +1. **Reproduce the issue** - Verify you can reproduce it +2. **Write a failing test** - Add a test that fails with the bug +3. **Fix the bug** - Make the test pass +4. **Verify** - Run all tests to ensure no regressions + +## Testing Guidelines + +### Unit Tests + +- Use Vitest for unit tests +- Test individual functions and modules +- Mock external dependencies +- Aim for high coverage + +```bash +npm test +``` + +### E2E Tests + +- Use Playwright for end-to-end tests +- Test real browser scenarios +- Test framework integrations (Vite, Next.js) + +```bash +npm run test:e2e +``` + +## Pull Request Guidelines + +### Before Submitting + +- [ ] Code builds without errors (`npm run build`) +- [ ] All tests pass (`npm run test:run`) +- [ ] Type checking passes (`npm run type-check`) +- [ ] Documentation is updated if needed +- [ ] PR description explains what and why + +### PR Title Format + +Write clear, descriptive titles: +``` +Add support for worker_threads module +Fix path resolution issue in virtual filesystem +Improve sandbox setup documentation +``` + +### Review Process + +1. Maintainers will review your PR +2. Address any feedback or requested changes +3. Once approved, a maintainer will merge + +## Security Considerations + +### Running Untrusted Code + +**Always use cross-origin sandbox** for untrusted code: + +```typescript +const runtime = await createRuntime(vfs, { + sandbox: 'https://your-sandbox.vercel.app', +}); +``` + +**Never use** `dangerouslyAllowSameOrigin` with untrusted code. + +### Reporting Security Issues + +If you discover a security vulnerability, please email security@macaly.com instead of opening a public issue. + +## Getting Help + +- **GitHub Issues** - [Report bugs or request features](https://github.com/macaly/almostnode/issues) +- **Discussions** - [Ask questions or share ideas](https://github.com/macaly/almostnode/discussions) +- **Email** - support@macaly.com + +## License + +By contributing to almostnode, you agree that your contributions will be licensed under the MIT License. + +--- + +Thank you for contributing to almostnode! 🚀 diff --git a/README.md b/README.md index cb8237e..988abdc 100644 --- a/README.md +++ b/README.md @@ -885,13 +885,21 @@ Open `http://localhost:5173/examples/next-demo.html` to see the Next.js demo. ## Contributing -Contributions are welcome! Please: +We welcome contributions! Whether you're fixing bugs, adding Node.js API shims, improving documentation, or building new features, your help is appreciated. -1. Fork the repository -2. Create a feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request +Check out our **[Contributing Guide](CONTRIBUTING.md)** to get started. + +Before contributing: +1. Read the [Contributing Guide](CONTRIBUTING.md) +2. Check existing [issues](https://github.com/macaly/almostnode/issues) and [discussions](https://github.com/macaly/almostnode/discussions) +3. Follow the code style and conventions +4. Add tests for new features +5. Update documentation as needed + +**Quick links:** +- [Report a bug](https://github.com/macaly/almostnode/issues/new?template=bug_report.yml) +- [Request a feature](https://github.com/macaly/almostnode/issues/new?template=feature_request.yml) +- [View discussions](https://github.com/macaly/almostnode/discussions) ---