{"_id":"@aditya-borkar/localport","name":"@aditya-borkar/localport","dist-tags":{"latest":"0.0.0-development"},"versions":{"0.0.0-development":{"bin":{"localport":"src/cli.ts"},"dependencies":{"commander":"^14.0.3","consola":"^3.4.2","ora":"^9.3.0"},"devDependencies":{"@biomejs/biome":"^2.4.3","@sebbo2002/semantic-release-jsr":"^3.2.0","@semantic-release/changelog":"^6.0.3","@semantic-release/commit-analyzer":"^13.0.1","@semantic-release/git":"^10.0.1","@semantic-release/github":"^12.0.6","@semantic-release/npm":"^13.1.4","@semantic-release/release-notes-generator":"^14.1.0","@types/bun":"^1.3.9","husky":"^9.1.7","semantic-release":"^25.0.3"},"engines":{"bun":">=1.0.0","node":">=22.0.0"},"exports":{".":{"import":"./src/index.ts","types":"./src/index.ts"}},"module":"src/index.ts","name":"@aditya-borkar/localport","peerDependencies":{"typescript":"^5.9.3"},"scripts":{"dev":"bun src/cli.ts","lint":"biome check --fix","prepare":"husky","test":"bun test","typecheck":"tsc --noEmit"},"sideEffects":false,"type":"module","version":"0.0.0-development","gitHead":"2b643c2832dc77ec6a57f01c3c0915ed6b978574","_id":"@aditya-borkar/localport@0.0.0-development","description":"CLI tool for managing local DNS and HTTP services with custom `.local` domains. Localport sets up dnsmasq for DNS resolution and Caddy for serving local content, perfect for development environments and local testing.","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-NkCKNRoPO4uxbwlVUeNJbfPE31GzWjULaJQ87g016LzdfaXKPu57ZhPktODeGphKEY4vkn8rwQpbDb15A8Vw0w==","shasum":"7d013191b89b32d4dc27a086e08eba8eb6dcd4f8","tarball":"https://registry.npmjs.org/@aditya-borkar/localport/-/localport-0.0.0-development.tgz","fileCount":5,"unpackedSize":12098,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCVwJ9ef5PK+ELumyyivhs4opDhbW5D2Ry+C/pglvVB6AIhAPpeOTNZCXNrPQ+dCyKy4zCDgqM67WmKUe4IjA2Bdwgq"}]},"_npmUser":{"name":"adityaborkar","email":"aditya.borkar.programs+npm@gmail.com"},"directories":{},"maintainers":[{"name":"adityaborkar","email":"aditya.borkar.programs+npm@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/localport_0.0.0-development_1771603296784_0.6907436535592328"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-20T16:01:36.647Z","0.0.0-development":"2026-02-20T16:01:36.929Z","modified":"2026-02-20T16:01:37.251Z"},"maintainers":[{"name":"adityaborkar","email":"aditya.borkar.programs+npm@gmail.com"}],"description":"CLI tool for managing local DNS and HTTP services with custom `.local` domains. Localport sets up dnsmasq for DNS resolution and Caddy for serving local content, perfect for development environments and local testing.","readme":"# localport\n\nCLI tool for managing local DNS and HTTP services with custom `.local` domains. Localport sets up dnsmasq for DNS resolution and Caddy for serving local content, perfect for development environments and local testing.\n\n## Features\n\n- **Custom `.local` Domains**: Map any `.local` domain to `127.0.0.1` for local development\n- **Automatic Dependency Installation**: Installs dnsmasq and Caddy based on your platform\n- **Service Management**: Start, stop, and check status of services with a single command\n- **Health Checks**: Verifies DNS and HTTP services are running correctly\n- **Cross-Platform**: Supports macOS (Darwin) and major Linux distributions (Arch, CentOS, Debian, Fedora, Manjaro, RHEL, Ubuntu)\n- **XDG-Compliant**: Uses standard directories for configuration and state management\n- **Lock File Protection**: Prevents concurrent operations for safe service management\n\n## Installation\n\n### Prerequisites\n\n- **Bun**: Runtime environment (>= 1.0.0)\n- **Node.js**: Peer dependency (>= 22.0.0) for type definitions\n- **System Requirements**:\n  - Root/sudo access for installing dnsmasq and Caddy\n  - Network access for fetching dependencies\n\n### Install from NPM\n\n```bash\nbun install -g localport\n```\n\n### Install from Source\n\n```bash\ngit clone <repository-url>\ncd localport\nbun install\nbun link\n```\n\n## Supported Platforms\n\n| Platform | Support Status |\n|----------|----------------|\n| macOS (Darwin) | ✅ |\n| Arch Linux | ✅ |\n| Manjaro | ✅ |\n| Ubuntu | ✅ |\n| Debian | ✅ |\n| Fedora | ✅ |\n| RHEL | ✅ |\n| CentOS | ✅ |\n\n## Usage\n\n### Start Services\n\nStart dnsmasq (DNS) and Caddy (HTTP) in detached mode:\n\n```bash\nlocalport start\n```\n\nStart in foreground mode (useful for debugging):\n\n```bash\nlocalport start --no-detached\n```\n\n**Default Ports:**\n\n- DNS (dnsmasq): `127.0.0.1:5353`\n- HTTP (Caddy): `127.0.0.1:8443`\n\n### Stop Services\n\nStop all running services:\n\n```bash\nlocalport stop\n```\n\n### Check Status\n\nView service status and health:\n\n```bash\nlocalport status\n```\n\nOutput example:\n\n```\ndnsmasq  ✓ running (PID: 12345, Port: 5353) - healthy\ncaddy    ✓ running (PID: 12346, Port: 8443) - healthy\n```\n\n## Exit Codes\n\nThe CLI uses the following exit codes:\n\n| Code | Meaning |\n|------|---------|\n| 0 | Success |\n| 1 | Error |\n| 2 | Usage (invalid command or arguments) |\n\nWhen an error occurs, the CLI will exit with code `1` and print an error message to stderr.\n\n## How It Works\n\n1. **DNS Resolution (dnsmasq)**:\n   - Runs on `127.0.0.1:5353`\n   - Resolves all `.local` domains to `127.0.0.1`\n   - Caches queries for performance\n   - Uses upstream DNS servers (1.1.1.1, 8.8.8.8)\n\n2. **HTTP Server (Caddy)**:\n   - Runs on `127.0.0.1:8443`\n   - Responds with status message on default endpoint\n   - Can be configured for custom domain routing\n\n3. **File Organization**:\n   - Config: `$XDG_CONFIG_HOME/localport/` (default: `~/.config/localport/`)\n   - State: `$XDG_STATE_HOME/localport/` (default: `~/.local/state/localport/`)\n   - Logs: `$XDG_STATE_HOME/localport/logs/`\n\n## Configuration\n\nAfter starting localport, configure your system DNS to use the local DNS server:\n\n### macOS\n\n```bash\nsudo networksetup -setdnsservers Wi-Fi 127.0.0.1 5353\n```\n\n### Linux (NetworkManager)\n\n```bash\nnmcli connection modify <connection-name> ipv4.dns \"127.0.0.1 5353\"\n```\n\n### Testing DNS Resolution\n\n```bash\ndig @127.0.0.1 -p 5353 test.local +short\n```\n\nExpected output: `127.0.0.1`\n\n## Development\n\n### Available Scripts\n\n```bash\n# Install dependencies\nbun install\n\n# Run CLI in development mode\nbun run dev\n\n# Run TypeScript type checking\nbun run typecheck\n\n# Run linter\nbun run lint\n\n# Run tests\nbun test\n```\n\n### Project Structure\n\n```\nlocalport/\n├── src/\n│   ├── cli.ts           # CLI entry point and command definitions\n│   ├── constants.ts     # Platform-specific constants and configs\n│   ├── utils.ts         # Utility functions and helpers\n│   ├── index.ts         # Main exports (for library usage)\n│   └── sdk/\n│       ├── start.ts     # Service start logic\n│       ├── stop.ts      # Service stop logic\n│       └── status.ts   # Service status checking\n├── package.json\n├── tsconfig.json\n└── AGENTS.md            # Agent development guidelines\n```\n\n## API\n\n### Programmatic Usage\n\nYou can also use localport as a library in your TypeScript/JavaScript projects:\n\n```typescript\nimport { start, stop, status } from \"localport\"\n\n// Start services\nawait start(true, false)\n\n// Check status\nconst serviceStatus = await status(true)\n\n// Stop services\nawait stop(true)\n```\n\n## Troubleshooting\n\n### Services Won't Start\n\n1. Check if ports are already in use:\n\n   ```bash\n   lsof -i :5353  # dnsmasq\n   lsof -i :8443  # caddy\n   ```\n\n2. View logs:\n\n   ```bash\n   tail -f ~/.local/state/localport/logs/dnsmasq.log\n   tail -f ~/.local/state/localport/logs/caddy.log\n   ```\n\n### DNS Not Resolving\n\n1. Verify dnsmasq is running: `localport status`\n2. Check DNS configuration: `dig @127.0.0.1 -p 5353 test.local`\n3. Ensure system DNS is pointing to `127.0.0.1:5353`\n\n### Permission Errors\n\nEnsure you have sudo/root access for installing system dependencies (dnsmasq and Caddy).\n\n## License\n\n[Your License Here]\n\n## Contributing\n\nContributions are welcome! Please read [AGENTS.md](./AGENTS.md) for development guidelines before submitting pull requests.\n\n## Support\n\nFor issues, questions, or feature requests, please open an issue on the [GitHub repository](<repository-url>).\n","readmeFilename":"README.md","_rev":"1-3ccd5714bd8fa734d1ddd5c3118fddce"}