From 365e8a2605b4d492d2b12e436868bfe44ca5746b Mon Sep 17 00:00:00 2001 From: Mario Tarosso Date: Mon, 21 Sep 2026 09:07:04 +0100 Subject: [PATCH] Tidy the Connect README MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Four fixes, one of which is the reason the README misleads readers about what this package is. **Say what the "Report a vulnerability" button is, before using the phrase.** The button was named in the install prompt and the quick start, then not defined until "The disclosure widget" nearly 300 lines later. Read top-down — which is how an assistant reads it — the phrase lands next to a package about vulnerability monitoring and reads as either a way to report vulnerable dependencies to Patchstack, or as this package's own security-contact channel. It is neither: it is a button Connect renders on the reader's site for their visitors. The new opening says so at first use. **Describe the whole package.** The opening line covered dependency scanning only, and named `package-lock.json` when five lockfile formats are supported. The runtime guard, the disclosure widget and the attack-surface map all ship in `dist/` and were documented further down, so the summary a reader forms from the first paragraph was narrower than the package. It now lists the four things Connect does and links to each, and says `map` is never run for you. **Correct the release process.** It described bumping `package.json`, committing it, and a tag that must match or the workflow fails. None of that is how this releases: the tag is the source of truth, `Publish` writes the version into `package.json` in CI, and `Release` computes the bump. The section now matches `RELEASING.md` and `publish.yml` and points at the former for the rest. The one-time npm trusted-publishing setup moves to `RELEASING.md`, where a maintainer would look for it. **Fix the development loop order.** It listed `npm test` before `npm run build`. Several tests only run once `dist/` exists and skip without it, so that order reads exactly like passing while testing less. Also moves the local-endpoint manifest recipe to `CONTRIBUTING.md`; it is contributor-only and shipped to every consumer in the tarball. The install prompt is untouched, so all three copies still agree. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 17 +++++++++++++++ README.md | 55 +++++++++++++++---------------------------------- RELEASING.md | 16 ++++++++++++++ 3 files changed, 50 insertions(+), 38 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2e482a..c13cfe4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,23 @@ Build before testing, in that order. `dist/` is not committed, and several tests they skip in a plain checkout and are required in CI. Run in the other order and those tests skip, which reads exactly like passing. +### Posting a manifest at a local endpoint + +To post the current lockfile manifest to a Patchstack API endpoint you are running locally, and provision +a new site against it: + +```bash +bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest +``` + +The response should include the new site UUID. To re-test an existing site, pass that UUID explicitly: + +```bash +bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest --site-uuid YOUR_REAL_UUID +``` + +Use `--dry-run` to preview the payload without posting. + ## Before you open a pull request - `npm run typecheck`, `npm run build`, `npm test` all clean — in that order, for the reason above. diff --git a/README.md b/README.md index 9b4ecbc..8db7bbc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,13 @@ # @patchstack/connect -Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.com) for continuous vulnerability monitoring. Scans your `package-lock.json` and reports installed packages so Patchstack can match them against its vulnerability database and notify you when something needs patching. +Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.com). Connect does four things: + +- **Dependency inventory** — reads your lockfile and reports the installed package names and versions, so Patchstack can match them against its vulnerability database and tell you when something needs patching. See *[What gets sent](#what-gets-sent)*. +- **Runtime guard** — an in-process guard, wired into your server, that virtually patches known vulnerabilities in those dependencies rather than waiting for you to upgrade. See *[Verifying the guard at runtime](#verifying-the-guard-at-runtime-opt-in)*. +- **Disclosure widget** — a floating button labelled **"Report a vulnerability"** that Connect adds to *your* site, so visitors who spot a security problem have somewhere to send it. This is a channel for reports about your site; it is not how you report a bug in this package. See *[The disclosure widget](#the-disclosure-widget)*. +- **Attack-surface map** — a description of your server's entry points and the sinks they can reach, built by reading your source locally. See *[`map`](#cli)*. + +`setup` installs the first three in one command. `map` is never run for you — see the [CLI](#cli) section for what each command does and what it touches. ## Agent-assisted setup @@ -383,55 +390,27 @@ Every scanned source is validated against `package.json`: if the chosen lockfile ## Development ```bash -npm install +npm ci npm run typecheck +npm run build # before the tests: several only run once dist/ exists, and skip silently without it npm test -npm run build -``` - -### Manifest endpoint testing - -To post the current lockfile manifest to a local Patchstack API endpoint and provision a new site: - -```bash -bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest ``` -The response should include the new site UUID. To re-test an existing site, pass that UUID explicitly: - -```bash -bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest --site-uuid YOUR_REAL_UUID -``` - -Use `--dry-run` to preview the payload without posting. +`CONTRIBUTING.md` covers the rest — the Node versions this needs, the packaging checks, and what to run before opening a pull request. Changing onboarding, the install prompt or the setup guide? Read `MAINTAINING.md` first. ## Release process Pull requests run typecheck, tests, build, package verification, and a production dependency audit in GitHub Actions. -Publishing runs when a GitHub Release is published. The release tag must match the package version in `package.json` with a leading `v`. For example, `package.json` version `0.2.0` must be released with tag `v0.2.0`; otherwise the workflow fails before publishing. - -To publish a release: +Releases are cut by the `Release` workflow, which works out the next version, tags it, and hands off to `Publish`: -1. Bump the package version, for example `npm version 0.2.0 --no-git-tag-version`. -2. Commit `package.json` and `package-lock.json`. -3. Merge the version bump to `main`. -4. Create and publish a GitHub Release tagged `v0.2.0`. -5. The `Publish` workflow verifies the package, then runs `npm publish --provenance --access public`. - -Before the first release, configure npm trusted publishing for this package: +```bash +gh workflow run Release -f bump=patch # or: minor, major +``` -1. Merge `.github/workflows/publish.yml` to `main`. -2. Open the `@patchstack/connect` package settings on npmjs.com. -3. In **Trusted publishing**, choose **GitHub Actions**. -4. Configure: - - Organization/user: `patchstack` - - Repository: `connect` - - Workflow filename: `publish.yml` - - Environment name: `npm` -5. In GitHub repository settings, create an `npm` environment. Optional but recommended: require reviewer approval for that environment. +The git tag is the source of truth for the published version. `Publish` reads the version out of the tag, writes it into `package.json` in CI, then builds and publishes to npm with provenance — so you do **not** bump `package.json` before releasing. After publishing it opens a pull request bringing the committed manifest up to the version that just went out; merge that. -Do not add an npm publish token to GitHub secrets for this workflow. Trusted publishing uses GitHub OIDC short-lived credentials. After the first trusted publish succeeds, npm recommends setting package publishing access to require two-factor authentication and disallow tokens. +`RELEASING.md` has the details: how to pick the bump (a compatibility break on a `0.x` version needs at least a minor), the manual fallback, and the npm trusted-publishing configuration. ## License diff --git a/RELEASING.md b/RELEASING.md index 3b019e7..2e810c3 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -102,6 +102,22 @@ who has already installed it: Delete this section once both have shipped. +## npm trusted publishing + +This is configured already; it is recorded here so the settings can be checked or rebuilt. + +1. `.github/workflows/publish.yml` is on `main`. +2. In the `@patchstack/connect` package settings on npmjs.com, **Trusted publishing** is set to + **GitHub Actions** with organization `patchstack`, repository `connect`, workflow filename + `publish.yml`, environment name `npm`. +3. An `npm` environment exists in the GitHub repository settings. Requiring reviewer approval on it is + optional and recommended. + +There is deliberately **no npm publish token** in GitHub secrets for this workflow — trusted publishing +uses short-lived GitHub OIDC credentials instead. npm's own recommendation, once a trusted publish has +succeeded, is to set the package's publishing access to require two-factor authentication and disallow +tokens. + ## Notes - Tags must be `vX.Y.Z` (the leading `v` is stripped to get the npm version).