Print claim URL after provisioning, expose in status

[ejntaylor]

Summary

Implements the connector-side half of the claim flow agreed in ADR-0004.

• After a successful provisioning scan, the connector prints a claim URL so the user can attach the new site to their Patchstack account.
• npx @patchstack/connect status re-displays the claim URL whenever a UUID is configured.
• The URL is constructed from the API endpoint's origin plus /claim?site=<uuid> — works for production, staging, ngrok and local mock servers without code changes.

Why

ADR-0004 (revised in saas#508) decides:

The site UUID is the credential for claiming. There is no separate claim token in the MVP. The connector prints a claim URL after every successful provisioning scan; the URL is constructed from the API endpoint's origin plus /claim?site=<uuid>.

This PR is the connector half of that decision. The matching SaaS work — adding the GET /claim?site=<uuid> page and the authenticated POST /claim route — lands separately on the SaaS side. Until that ships, clicking the URL will 404; the connector printing it does no harm and makes the connector ready as soon as the SaaS endpoint goes live.

What's in it

• src/client.ts — new buildClaimUrl(endpoint, siteUuid) helper alongside buildEndpointUrl. Uses new URL(endpoint).origin to extract the host part, so changing the API path doesn't break the claim URL.
• src/cli.ts — runScan prints the URL after the manifest-stored message, only on the provisioning path (first scan of a fresh project). runStatus shows a Claim URL: line whenever a UUID is configured.
• src/index.ts — exports buildClaimUrl for programmatic consumers.
• tests/client.test.ts — 6 new tests cover origin extraction, ngrok-style hosts, trailing slashes, scheme preservation (http vs https), URL encoding of the UUID, and dropping deep paths from the endpoint. Suite is 51 green.
• README.md — adds the claim step to the "Quick start (zero configuration)" walkthrough.

What's deliberately not in it

• No state added to .patchstackrc.json. The claim URL is reconstructible from siteUuid + endpoint and is never persisted. ADR-0004 explicitly avoids storing claim state in source control.
• No detection of already-claimed sites. The ADR's "Watch" note flags this as a v2 improvement (server returns claimed: true, connector suppresses the link). For MVP the URL is informational; the /claim page tells a user "already claimed" if they reach it after the site is taken.
• No SaaS-side changes. Mario or whoever owns the SaaS claim route will add GET/POST /claim separately. The connector PR is independent and harmless until then.

Output sample

Found 5 unique package versions across 4 package names in npm lockfile.
1 package(s) appear at multiple versions:
  lodash
No site UUID configured — provisioning a new Patchstack site from this manifest…
Provisioned site 973e041c-b607-413d-b8e3-556f81d848db. Saved UUID to /path/.patchstackrc.json.
Stored manifest #14 (checksum c5cf5c1b2279).

Claim this site to view vulnerability reports in your Patchstack dashboard:
  https://app.patchstack.com/claim?site=973e041c-b607-413d-b8e3-556f81d848db

Test plan

• npx vitest run — 51/51 passing
• npx tsc --noEmit — clean
• End-to-end smoke test against a local mock server returning the exact response shape from the SaaS — claim URL prints correctly in both scan and status
• Once the SaaS /claim route lands, click the URL from a real provisioning scan and confirm the round-trip

🤖 Generated with Claude Code