{"_id":"@404labs/portguard","name":"@404labs/portguard","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@404labs/portguard","version":"0.1.0","description":"Stable per-project localhost port assignment for AI-built apps. Prevents 3000/3001 drift, checks occupancy, and ships as an agent skill plus CLI.","bin":{"portguard":"bin/cli.js","pgport":"bin/cli.js"},"main":"./lib/registry.js","scripts":{"test":"node --test test/*.test.js","assign":"node bin/cli.js assign"},"keywords":["localhost","port","dev-server","developer-tools","ai-coding","stable-port","codex-cli","claude-code","antigravity","kimi-cli","agent-skill","nextjs","vite"],"license":"MIT","engines":{"node":">=18"},"repository":{"type":"git","url":"git+https://github.com/SpectreMercury/404labs.git","directory":"portguard"},"bugs":{"url":"https://github.com/SpectreMercury/404labs/issues"},"homepage":"https://github.com/SpectreMercury/404labs/tree/master/portguard#readme","_id":"@404labs/portguard@0.1.0","gitHead":"05cdf18546846ff6c15cd51c3718d74232f3ac0b","_nodeVersion":"22.13.0","_npmVersion":"11.3.0","dist":{"integrity":"sha512-yr7VmVjwdKqRCEfnYyE84q5ZGJBkMOQ7poFF454PKE/N47t4B+YXkWUB22Ns179SyaOaWi0vZry0RojOe1RKpA==","shasum":"ad8cb698f4c724165c36bc4fc5f764cac508d482","tarball":"https://registry.npmjs.org/@404labs/portguard/-/portguard-0.1.0.tgz","fileCount":9,"unpackedSize":34105,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBLjH3kxZ6EL2HU6u+IqBRx574pgdoHatUBSbtcr1xpoAiAA56sj3f2WSrPMy96yA7JGn2ttYpYlRU2YDihm6KvqOA=="}]},"_npmUser":{"name":"error404_timeispassmeby","email":"FrancisLee920217@gmail.com"},"directories":{},"maintainers":[{"name":"error404_timeispassmeby","email":"FrancisLee920217@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/portguard_0.1.0_1783242507768_0.3453185235123546"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-05T09:08:27.674Z","0.1.0":"2026-07-05T09:08:27.949Z","modified":"2026-07-05T09:08:28.116Z"},"maintainers":[{"name":"error404_timeispassmeby","email":"FrancisLee920217@gmail.com"}],"description":"Stable per-project localhost port assignment for AI-built apps. Prevents 3000/3001 drift, checks occupancy, and ships as an agent skill plus CLI.","homepage":"https://github.com/SpectreMercury/404labs/tree/master/portguard#readme","keywords":["localhost","port","dev-server","developer-tools","ai-coding","stable-port","codex-cli","claude-code","antigravity","kimi-cli","agent-skill","nextjs","vite"],"repository":{"type":"git","url":"git+https://github.com/SpectreMercury/404labs.git","directory":"portguard"},"bugs":{"url":"https://github.com/SpectreMercury/404labs/issues"},"license":"MIT","readme":"# portguard\n\n> Stable localhost ports for AI-built apps. Assign one durable port per\n> project, skip the crowded `3000`/`3001` defaults, check occupancy, and stop\n> framework auto-fallback from scrambling local accounts and password-manager\n> entries.\n\nAI coding agents often start every web app on `localhost:3000`, then drift to\n`3001`, `3002`, or a random framework fallback when something is already\nrunning. That makes browser profiles, OAuth callbacks, cookies, and password\nmanagers point at the wrong project. `portguard` gives each project a stable\nlocal URL and stores the assignment in a shared registry.\n\n---\n\n## What it does\n\n`portguard` keeps a local registry at\n`~/.404labs/portguard/registry.json`:\n\n1. **Assigns once per project** - uses the git root when present, otherwise\n   the current directory.\n2. **Avoids common defaults** - skips `3000` and `3001` by default.\n3. **Checks occupancy** - newly assigned ports must be bindable on\n   `127.0.0.1`.\n4. **Prevents silent reuse** - a port that belonged to one project is not\n   given to another project just because the first server is stopped.\n5. **Refuses silent drift** - an occupied existing assignment is reported;\n   the URL changes only when you explicitly run `--reassign`.\n\n---\n\n## Install\n\n### As an agent skill\n\n**Recommended - global install via the\n[Vercel Labs `skills` CLI](https://github.com/vercel-labs/skills)**\n(supports 55+ agent CLIs and keeps this behavior available in every repo):\n\n```bash\nnpx skills add SpectreMercury/404labs --skill portguard -g\n```\n\nInstall to the current detected agent instead:\n\n```bash\nnpx skills add SpectreMercury/404labs --skill portguard\n```\n\nInstall to all detected/supported agents:\n\n```bash\nnpx skills add SpectreMercury/404labs --skill portguard --all\n```\n\n### As a CLI\n\nInstall globally so all projects and agents share one command and one\nregistry:\n\n```bash\nnpm i -g @404labs/portguard\n```\n\nOr use it through `npx`:\n\n```bash\nnpx @404labs/portguard assign --json\n```\n\n### Built-in agent installer\n\nThe package can also copy the skill into common local agent folders:\n\n```bash\nnpx @404labs/portguard install                      # auto-detect\nnpx @404labs/portguard install --target all         # install for all 4 supported\nnpx @404labs/portguard install --target claude,codex\nnpx @404labs/portguard install --list-targets\n```\n\n| Built-in target | CLI | Path |\n|---|---|---|\n| `claude` | Claude Code | `~/.claude/skills/portguard/` |\n| `codex` | OpenAI Codex CLI | `~/.agents/skills/portguard/` |\n| `antigravity` | Google Antigravity | `~/.gemini/antigravity/skills/portguard/` |\n| `kimi` | Moonshot Kimi CLI | `~/.kimi/skills/portguard/` |\n\nRestart your CLI after installing the skill so its index refreshes.\n\n---\n\n## Usage\n\nAssign or read the current project's stable port:\n\n```bash\nportguard assign\n```\n\nMachine-readable output:\n\n```bash\nportguard assign --json\n```\n\nPrint only the port for scripts:\n\n```bash\nPORT=$(portguard assign --print) npm run dev\n```\n\nCheck whether a port is currently occupied:\n\n```bash\nportguard check 3124\n```\n\nList active assignments:\n\n```bash\nportguard list\n```\n\nRetire the current project's assignment without making the port reusable:\n\n```bash\nportguard release\n```\n\nReassign only when you intentionally accept a new local URL:\n\n```bash\nportguard assign --reassign\n```\n\nFail if the assigned port is occupied:\n\n```bash\nportguard assign --strict\n```\n\n---\n\n## Example output\n\n```text\nportguard assignment\n\n  project:  /Users/me/work/acme-dashboard\n  name:     acme-dashboard\n  port:     3104\n  url:      http://localhost:3104\n  source:   new\n  status:   free\n  registry: /Users/me/.404labs/portguard/registry.json\n\nUse: PORT=3104 npm run dev\n```\n\nIf the assigned port is occupied, `portguard` does not silently switch to a\nnew URL:\n\n```text\nstatus: occupied\n\nThe assigned port is occupied. If that is this project already running, keep\nusing it. If it is a different process, stop the conflict or run\n`portguard assign --reassign` intentionally.\n```\n\n---\n\n## Wire it into common frameworks\n\nNext.js:\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"next dev -p 3104\"\n  }\n}\n```\n\nVite:\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"vite --host 127.0.0.1 --port 3104 --strictPort\"\n  }\n}\n```\n\nAstro:\n\n```json\n{\n  \"scripts\": {\n    \"dev\": \"astro dev --host 127.0.0.1 --port 3104\"\n  }\n}\n```\n\nMore examples are in [references/frameworks.md](references/frameworks.md).\n\n---\n\n## Configuration\n\nFlags:\n\n```text\n--project <path>      Project path. Default: current working directory.\n--name <name>         Display name stored in the registry.\n--range <start-end>   Search range. Default: 3100-3999.\n--reserved <ports>    Comma list to skip. Default: 3000,3001.\n--host <host>         Bind-check host. Default: 127.0.0.1.\n--registry <path>     Registry file. Default: ~/.404labs/portguard/registry.json.\n--json                Machine-readable output.\n--print               Print only the assigned port.\n--strict              Exit 1 if the existing assigned port is occupied.\n--reassign            Explicitly move to a new never-used free port.\n--no-git-root         Key the exact path instead of the git root.\n```\n\nEnvironment:\n\n```bash\nPORTGUARD_REGISTRY=/custom/registry.json portguard list\nPORTGUARD_RANGE=4100-4999 portguard assign\nPORTGUARD_RESERVED=3000,3001,5173 portguard assign\n```\n\n---\n\n## Exit codes\n\n| Code | Meaning |\n|---|---|\n| `0` | Command succeeded; `check` found the port free |\n| `1` | Occupied port, no available port, no assignment to release, or partial install failure |\n| `2` | Usage/configuration error |\n\n---\n\n## License\n\nMIT - see [LICENSE](LICENSE).\n","readmeFilename":"README.md","_rev":"1-cce18d33dbc14af6f5019fb05b4eb423"}