feat(macos): explain the Local Network grant for .local URLs

[roodboi]

What changes

On macOS, Hack now prints one fixed hint line on stderr when a command opens or prints a browser URL or dev host ending in .local:

Hint: on macOS, browsers other than Safari need a one-time Local Network permission to open .local names (System Settings > Privacy & Security > Local Network). See docs/guides/macos-browser-network.md.

Where it appears:

• hack open (Compose and native-authored paths, with and without --json)
• hack branch open
• hack status / hack projects (human output, from the dev host column)
• hack doctor browser check (the --browser-url origin, or the default domain when no origin is given). Native doctor shows it only for a given --browser-url.

Rules (in src/lib/local-network-hint.ts):

• Shown only on darwin, only for hostnames ending in .local (case-insensitive, trailing root dot ignored).
• Shown at most once per command (one process-wide emitter).
• Always written to stderr. It never appears in a --json payload. Doctor JSON has no structured hints array, so nothing is added to the JSON data.
• The text is a fixed constant with no interpolated host names.
• Hack does not read, request or change the permission.

The product decision keeps hack.local as the default dev-host root. This change explains the one-time grant that browsers other than Safari need.

Docs

• docs/guides/macos-browser-network.md: new section explaining the name-based rule (Apple TN3179: .local is the mDNS namespace, so the grant applies even when Hack resolves to loopback), the Safari exemption, the new hint, and alternatives:
  • the OAuth alias (<project>.hack.gy, hack open --prefer alias)
  • a custom suffix under hack.gy: hack global dns activate --domain dev.hack.gy for native, or default_domain plus hack global install for the Docker stack
• Linked from docs/guides/init-project.md (default domain notes and the .local compatibility paragraph) and from the native DNS section of docs/guides/native-candidate.md.

Canonical agent guidance does not say that .local works in every browser, so it is unchanged. Plugins and render fingerprints are not regenerated. The CLI surface is unchanged, so docs/reference/cli.md is not regenerated.

Validation

• tests/local-network-hint.test.ts (new):
  • The hint appears for .local URLs and hosts on darwin.
  • It does not appear for .hack, .hack.gy, .hack.local.gy, localhost, IPs or unparsable input.
  • It is never shown on linux, win32 or freebsd.
  • It is shown once per emitter.
  • The text is closed.
  • A real CLI open --json run uses an isolated HOME and state, no daemon and no Docker. It checks that the stdout JSON is exactly {url} with no hint, and that the hint appears on stderr exactly once on darwin (zero times on other platforms). A non-.local host produces no hint.
• tests/integration-ownership.test.ts and tests/agent-plugin-generation.test.ts pass.
• Related suites pass: tests/doctor-*.test.ts, tests/native-ca-doctor-cli.test.ts, tests/project-name-command.test.ts, tests/open-host.test.ts, tests/cli-reference-docs.test.ts, and the projects and branch tests.
• bun run --cwd packages/cli typecheck: 0 errors.
• bun run --cwd packages/cli check: 0 errors. The 34 existing warnings are unchanged, and none are in the changed files.

The tests do not touch /etc/resolver, dnsmasq, the keychain, Docker, the real HOME, sudo or osascript.

Remaining gaps

• hack up prints no URL summary today, and hack ps prints no URLs (Compose or native), so neither shows the hint. This PR does not add a URL summary to up.
• hack status / hack projects show the hint only in human output. Their --json daemon payload is passed through unchanged, so no hint is added there.
• I have not observed the hint text in a real browser session. Chrome and Firefox behavior after the grant is taken from the product decision and TN3179, not from a test.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}