peek

Imported from radityprtama/peek (AGENTS.md). Install upstream with npx skills add radityprtama/peek. Copyright stays with the author.

Agent guide for Peek

Peek is a zero-config Node.js CLI that runs one project's dev server and shares its verified port through one temporary Cloudflare Quick Tunnel. It is one npm package, @radityprtama/peek, with peek as the executable. Read the architecture, design spec, and decisions before changing startup or security behavior.

Directory map

Non-negotiable invariants

1. peek remains zero-config for a normal project with a dev script.
2. Peek must not require a Peek account.
3. Peek must not require a manually installed cloudflared binary.
4. Dev server and tunnel must always be cleaned up together.
5. Never expose a port other than the selected, verified server port.
6. Never collect source code or environment variables; add no telemetry.
7. Keep tunnel providers behind src/tunnel/types.ts.
8. Normal CI must not depend on an external Cloudflare tunnel.
9. Keep runtime dependencies minimal and explain any new one.
10. Preserve Node.js 22+ compatibility without requiring Bun.

Do not casually change the Cloudflare version or SHA-256 digests, disable checksum checks, add shell execution, accept arbitrary public URLs, weaken port ownership/readiness checks, or detach children from lifecycle cleanup. Do not add accounts, relay infrastructure, configuration requirements, or other roadmap ideas as part of unrelated fixes.

Coding and verification

Use strict TypeScript, small modules, explicit types, and argv arrays. Keep network and process boundaries injectable. Explain why in comments; avoid comments that restate code. When working with a dependency API, check current documentation with Context7 before relying on remembered behavior.

pnpm install
pnpm dev
pnpm test
pnpm lint
pnpm typecheck
pnpm build
pnpm pack:check

Add a focused unit or integration test for behavior that can expose the wrong port, lose a child process, accept a malformed URL, or execute an unverified binary. No CI test should require the public Cloudflare network. Run the full local gate before a release: lint, typecheck, test, build, and packed CLI smoke test. See development for manual tunnel testing.

Release process

Update CHANGELOG.md and package version together. Verify every pinned Cloudflare asset digest against the official release if changing the binary version. Run the local gate and inspect npm pack --dry-run. The tag release workflow checks the tag matches package version and publishes with npm provenance. npm requires an existing package before trusted publishing can be configured: the owner must first publish a minimal bootstrap prerelease from an isolated directory, then authorize direct npm publish for the exact GitHub repository and release.yml before tagging v0.1.0. See docs/DEVELOPMENT.md. Never place an npm token in this repository.