@patchstack/connect 0.3.31 → 0.3.33

package/AGENT-INSTALL.md

@@ -144,18 +144,112 @@ would have stopped while it is still in dry-run. Two separate paths, with differ
   token; the `apiKey` itself is not sent to the log endpoint. Disable with `PATCHSTACK_TELEMETRY=off`, or
   `reportFirewallLog: false` in `createProtection`.
 - **Every rule that matched** goes to `monitor/pulse/detections/<your site uuid>` — including matches that
-  blocked, which are reported on both paths. This is **off unless you pass `reportDetections: true`** to
-  `createProtection`; the scaffolded guard does not pass it. It also requires a provisioned site UUID, a
-  resolvable credential, and is disabled by `PATCHSTACK_TELEMETRY=off`. It exists because a rule carrying
-  `dry-run` blocks nothing, so without it nothing distinguishes a rule that is protecting from one that is
-  quietly wrong.
-
-What a detection report contains, per matched rule: the rule id, the request path **with any query string
-removed**, the parameter names that rule reads (from the rule's own definition), which phase matched,
-whether it was enforced, the identifier of the rule bundle in use, the revision of the rule itself when the
-bundle carried one, and a timestamp. Each batch also
-carries a count of reports dropped when traffic outran the flush, so a partial sample is not read as a
-complete one.
+  blocked, which are reported on both paths. It exists because a rule carrying `dry-run` blocks nothing, so
+  without it nothing distinguishes a rule that is protecting from one that is quietly wrong.
+
+  **This is on by default for a site enrolled with Patchstack that is running Patchstack-delivered rules**,
+  and off otherwise. Specifically, it requires all of: a provisioned site UUID, rules that came from
+  Patchstack rather than from a local bundle, and a resolvable credential. A local install, or a guard
+  running its own `rules`, sends nothing.
+
+  Switch it off with **`PATCHSTACK_REPORT_DETECTIONS=0`**, or `reportDetections: false` in
+  `createProtection`, or `PATCHSTACK_TELEMETRY=off` which covers all telemetry. `reportDetections` is an
+  opt-out only — passing `true` cannot switch reporting on for a site that is not enrolled.
+
+  `protection.detectionReporting` names the current state locally, so a guard that is not reporting says
+  which reason applies: `on`, `disabled-by-config`, `disabled-by-telemetry-opt-out`, `not-enrolled`,
+  `no-managed-rules`, or `unavailable-no-credential`.
+
+  **How the state reaches Patchstack, and what that costs on the network.** The state travels as a header
+  on the rules request the guard already makes — no extra request for it. Two of the six never travel:
+  `not-enrolled` makes no site-addressed request at all, and `unavailable-no-credential` cannot produce an
+  authenticated one, and the header is withheld from unauthenticated requests. Those two are local
+  diagnostics only.
+
+  There is one case that does add a request. The header is set before the rules request finishes, so a
+  guard booting with no cached rules declares `no-managed-rules` and then receives managed rules on that
+  same response. When that happens it sends **one immediate POST to the detections endpoint containing the
+  corrected state and no detections at all** — an empty `detections` array plus `reporting_state`. It is
+  sent once per process, only when the state changed, and never when the guard already had cached rules.
+  Without it, a guard with rule refreshing switched off would leave Patchstack holding the pre-resolution
+  answer for the life of the process.
+
+What a detection report contains, per matched rule — on every phase, whatever fired it: the rule id, the revision of the rule when the
+bundle carried one, the identifier of the rule bundle in use, which phase matched,
+whether it was enforced, the request path **with the query string's values removed**,
+that query's parameter names, the method, and a timestamp. Each batch also carries a count of reports dropped when traffic outran the flush,
+so a partial sample is not read as a complete one.
+
+Two fields depend on the phase, because one kind of detection has a client and the other does not. A
+**request or response** detection also carries the user agent,
+and the client address together with where that address came from.
+An **egress** detection — a rule that fired on a call your application made outbound — carries neither:
+the call was your application's own, so there is no visitor to attribute it to, and those fields read
+`null` and `unavailable` rather than being guessed at. "What values a report can contain" below says the
+same thing about captured evidence.
+
+Every field is bounded in size, and an event that had to be shortened says so.
+`truncated` lists **which fields were shortened**.
+`parameters_total` records **how many parameters the rule reads**, when a rule reads more than the event
+names.
+`query_keys_total` records **how many query parameters the request carried**, counted as DISTINCT names,
+when it carried more than the event lists — a parameter repeated three times is one name to look up. The
+names themselves are the ones the guard addresses a parameter by, so `?first+name=x` is reported as
+`first name`. Both appear only when something really was shortened, so their absence is not a claim of its own —
+and a shortened route or rule id is marked rather than passed off as complete, because a reader must not
+use one as a key believing it names the whole thing.
+
+Delivery is retried, up to four attempts per batch, with exponential backoff and jitter, honouring a
+`Retry-After` header when the endpoint sets one. Only failures worth retrying are retried — unreachable,
+rate-limited, or a server error; a batch that was refused on its merits is not sent again. Every attempt
+of one batch carries the same `Idempotency-Key` header, and a different batch carries a different one, so
+a redelivery is identifiable as the same batch rather than a new one — an acknowledgement can be lost
+after the server has already taken a batch. One request is in flight at a time, so a slow endpoint slows
+the queue rather than opening more sockets; each attempt is abandoned after 10 seconds, so a request that
+never settles cannot hold that slot; and a batch that exhausts its attempts is dropped and counted rather
+than retried forever. Stopping a guard makes one last attempt at whatever is outstanding and counts
+anything it could not send. `stop()` returns a promise that settles once the reporters have finished or
+been given up on, so a shutdown handler can `await protection.stop()` instead of racing the last batch
+against process exit. Each reporter has its own budget, and when it runs out that reporter is ended: its
+requests are aborted, it starts nothing further, and it discards what it was holding. An abort is a
+request to stop, not a guarantee — a transport that ignores it is detached rather than completed, so
+"resolved" means the reporter is finished with it, and a runtime that kills the process still wins
+regardless. Every detection event ends up delivered, refused or dropped and is reported in the health
+counts; block-log records have no counters, so one lost to a failed send or an expired shutdown is
+reported nowhere.
+
+The client address is reported with its **provenance**, because an address is only as trustworthy as
+whatever supplied it. `client_ip_source` is one of `runtime` (the address the transport observed),
+`trusted-proxy` (read from a forwarded header, through peers you declared via `trustedProxy`), or
+`unavailable`. When it is `unavailable` the `client_ip` field is **omitted entirely** rather than sent
+empty, so a missing address cannot read as a failed lookup of a real one. A forwarded header is never
+trusted implicitly: with no `trustedProxy` policy the address is whatever the transport observed, and in a
+runtime that exposes no transport peer there is no address to report at all.
+
+### Behaviour change: how the client address is determined
+
+The guard resolves the client address itself, once per request, and shares that one answer with rule
+matching, block logging and detection reports — so those cannot disagree about who a request came from.
+Two consequences if you are upgrading:
+
+- **Express and Node: forwarded headers are no longer read implicitly.** Earlier versions took the
+  address from `X-Forwarded-For`, `CF-Connecting-IP` or `X-Real-IP` (the Node guard), or from `req.ip`
+  (the Express guard, where it reflects Express's own `trust proxy` setting). Neither source can be
+  verified by the guard, and any client can send those headers, so both guards now read the transport
+  peer. **If your app runs behind a proxy or load balancer, addresses will now show as the proxy's**
+  until you declare your proxies with `trustedProxy` (below) — which affects attribution in reports and
+  any rule matching on `server.ip` or `REMOTE_ADDR`.
+- **Fetch runtimes report no address at all.** A WHATWG `Request` exposes no transport peer, so a Fetch
+  guard (Workers, Deno, Bun, edge) has nothing to observe, and no forwarded header is accepted in its
+  place under any `trustedProxy` policy: `client_ip_source` is `unavailable` and no address is sent.
+  Earlier versions reported the forwarded header here, so an address-scoped rule that appeared to work on
+  such a runtime was matching a client-supplied value.
+
+`trustedProxy` is the only way to make a forwarded header count. It takes the proxies you actually run —
+`{ peers: ['10.0.0.0/8'] }`, or `{ hops: 1 }` to trust that many hops in from the peer, plus optional
+`header` and `isTrusted` — and the chain is then read from your application inward, stopping at the first
+hop you have not declared. There are no built-in provider presets: a header a provider sets is
+indistinguishable from one a client sent unless you say which peers may set it.
 
 The parameter names are **identifiers, and they name the request region they refer to** — `post.title`,
 `get.redirect_to`, `cookie.session`, `server.HTTP_AUTHORIZATION`. So a rule that inspects a cookie or an
@@ -163,16 +257,79 @@ The parameter names are **identifiers, and they name the request region they ref
 definition, not from your traffic, so they describe what is being screened rather than what any request
 contained.
 
-What it does not contain: **no values of any kind.** Not the value that matched, not the request body,
-and not the value of any header, cookie or query-string parameter — including those of the parameters
-named above. Reports are batched, capped in memory, and dropped rather than retried if Patchstack cannot
+### What values a report can contain
+
+**A request or response detection** carries the request's method and path,
+the query string's parameter **names**,
+the user agent, the client address with its provenance, and a timestamp.
+
+**An egress detection** — a rule that fired on a request your application made outbound — carries the
+outbound method and path, the query's parameter names, and a timestamp. It carries **no user agent and no
+client address**: the call was your application's own, so there is no visitor to attribute it to, and
+those fields read `null` and `unavailable` rather than being guessed at.
+
+Beyond that baseline, either can include the **values of the parameters a rule names** — and nothing
+else. Counting that a
+rule fired is not enough to act on it: whoever triages a detection still has to decide whether the request
+was really an attack, and for that they need to see what the rule saw.
+
+**A rule earns each permission by naming what it reads.** What may be captured is derived from the rule
+itself, never configured per site:
+
+- a rule naming a parameter (`post.title`, `cookie.session`, `server.HTTP_AUTHORIZATION`) permits **that
+  parameter's value**, because the rule was written to inspect it;
+- a prefix (`post.field_*`) permits the values of keys that match, and no others;
+- a rule reading `raw` or `all` — the whole request — permits **nothing at all**, so the broadest rules
+  grant the narrowest capture;
+- **response** values are never captured: the phase that reads them exists to redact secrets, and
+  capturing them would collect the very values that redaction stops leaving;
+- **raw request bytes** need an explicit, reviewed opt-in on the individual rule, and are then limited to
+  a short prefix of the body.
+
+**Everything is bounded, and the bounds report themselves.**
+At most 10 values per detection, at most 512 characters each, and at most 5 values from any one prefix. A value shortened to fit is marked; values a bound
+left out are counted; a value refused because it was not a plain string, number or boolean is counted
+separately; and a read that failed is counted as a failure rather than as absence — so a short list is
+never mistaken for a complete one.
+
+**A `capture.plan` identifies the permissions, not the rule.** Each report carries a `capture.plan` reference derived
+from the permissions themselves — which parameters, which prefixes, which bounds — so what a given report
+was permitted to include can be established after the fact, without the rule in front of you. It
+identifies the PERMISSIONS, not the rule: two different rules that read the same parameters share one
+reference, and the rule document is identified by `rule_id` with `rule_revision`.
+
+**Capture is the union of everything the rule reads, not only the condition that matched.** The engine
+reports which rule fired, not which of its conditions did, so a rule reading `post.title` and
+`cookie.session` permits both values whichever one triggered the detection. A rule scoped to one parameter
+captures one; a broad rule captures what it is broad about.
+
+**One header value always travels, whatever the rule names: the User-Agent** — on a request or response
+detection, where there is a client to attribute. It is part of the baseline above, because attribution is
+what this channel is for and a detection without it cannot be told from another client's. It is the only
+exception to the rule-scoped policy, and the only header value sent without a rule naming it.
+
+**What a report never contains:** the value of any parameter the matched rule does not name — the
+User-Agent above excepted; any response body, header or status value;
+the request body, other than the reviewed raw prefix above;
+and anything at all from a rule that reads the whole request without that opt-in.
+
+**One qualification on the query string.** The exclusion above is about baseline URL metadata: `route` and
+`query_keys` describe a URL without disclosing what was in it. It is not a promise about captured
+evidence. A rule that names `egress.url` reads the outbound URL, so its capture carries that URL as the
+rule read it — query values included. That is the rule-scoped policy working as described, not an
+exception to it: the rule named the parameter, so the parameter's value travels. The value recorded is the request as the
+engine resolved it — URL- and entity-decoded — and not the result of a rule's own further mutations.
+
+Reports are batched, capped in memory, retried a bounded number of times, and dropped if Patchstack cannot
 be reached — a reporting failure never delays or fails a request.
 
-The endpoint needs a credential, so `reportDetections: true` with none resolved starts nothing: the guard
-warns once at boot and `protection.detectionReporting` reads `unavailable-no-credential` instead of `on`.
+The endpoint needs a credential, so an enrolled site with none resolved starts nothing: the guard warns
+once at boot and `protection.detectionReporting` reads `unavailable-no-credential` instead of `on`.
 When reporting is on, `protection.detectionHealth()` returns local counts — detections attempted,
 acknowledged, refused or unreachable, dropped for queue pressure — and the time of the last
-acknowledgement. Those counts stay in your process; nothing extra is sent to report them.
+acknowledgement. Counts for the state POST described above are kept separately under `capability`, since it
+carries no detections and would otherwise read as one. Those counts stay in your process; nothing extra is
+sent to report them.
 
 `protection.stop()` stops everything the guard has running in the background — the rule-refresh loop, the
 block-log reporter, the detection reporter — and flushes what is buffered. `protection.stopRefresh()` is

package/README.md

@@ -2,8 +2,6 @@
 
 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.
 
-For how this repo fits with the wider Patchstack ecosystem (`saas`, `hub`, `patchstack-website`, `patchstack-connect`), see [`patchstack/saas` → `docs/ecosystem.md`](https://github.com/patchstack/saas/blob/main/docs/ecosystem.md).
-
 ## Agent-assisted setup
 
 Copy this request into a coding assistant, or run the same command yourself:
@@ -89,6 +87,7 @@ patchstack-connect demo-guide node-serialize       Read-only, state-aware instru
                                                    local demo, including the next exact command,
                                                    expected proof, and cleanup.
 patchstack-connect help                            Print help
+patchstack-connect --version                       Print the installed version
 
 Options (for scan, setup, and status):
   --site-uuid <uuid>      Override the configured site UUID
@@ -161,6 +160,12 @@ PATCHSTACK_ENVIRONMENT=sandbox npx @patchstack/connect setup
 
 The generated `prebuild` scan deliberately carries no hard-coded environment. A production builder with no override reports `production`; a preview/sandbox builder must receive `PATCHSTACK_ENVIRONMENT=sandbox` from its host. Runtime protection itself is not environment-specific: `PATCHSTACK_ENVIRONMENT` labels manifests only. Use `PATCHSTACK_MODE=dry-run` when protection should observe rather than block.
 
+### `scan` as a build hook
+
+`setup` wires `scan` into `postinstall`, `prebuild`, or the Bun `build` chain. Run from one of those, a report Patchstack cannot accept — no credential in the build environment, a rejected credential, a site that no longer exists, an outage — is printed on stderr and `scan` exits 0, so the install or build it is attached to carries on. Patchstack keeps the last manifest it accepted for the site until a scan that can report. Run directly (`npx @patchstack/connect scan`), the same failure exits 1.
+
+A deploy never has `.patchstackrc.local.json`, so the usual cause is a missing `PATCHSTACK_API_KEY` in the platform's environment (see *Configuration*). The hook is recognised through `npm_lifecycle_event`, which npm, pnpm, Yarn and `bun run` set to the running script's name. `bun install` does not set it, so a `postinstall` scan under Bun still fails the install when it cannot report.
+
 ## Production virtual-patch demo
 
 The `node-serialize` scenario demonstrates dependency detection and a live, version-scoped virtual patch against a throwaway Express application. Connect/provision the project first, deliberately add the known-vulnerable package, then run:

package/dist/{chunk-LLKP5EJS.js → chunk-3G2I6QL6.js}

@@ -84,4 +84,4 @@ export {
   pulseAuthHeader,
   pulseFetch
 };
-//# sourceMappingURL=chunk-LLKP5EJS.js.map
+//# sourceMappingURL=chunk-3G2I6QL6.js.map

package/dist/chunk-3G2I6QL6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/pulse-token.ts"],"mappings":"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","names":[]}

package/dist/cli.js

@@ -2,6 +2,7 @@
 
 // src/cli.ts
 import { readFileSync as readFileSync14, writeFileSync as writeFileSync10 } from "fs";
+import { createRequire as createRequire2 } from "module";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -2083,38 +2084,83 @@ var PROD_MARKER_GLOBAL = "__PATCHSTACK_PROD__";
 var REGION_OPEN = "{/* #region patchstack (managed by patchstack-connect \u2014 do not edit) */}";
 var REGION_CLOSE = "{/* #endregion patchstack */}";
 var REGION_RE = /[ \t]*\{\/\* #region patchstack[\s\S]*?#endregion patchstack \*\/\}\n?/g;
+function findJsxShellAnchor(source, tagName) {
+  const candidates = new RegExp(`^([ \\t]*)<${tagName}(?=[\\s/>])`, "gm");
+  let candidate;
+  while ((candidate = candidates.exec(source)) !== null) {
+    let quote = null;
+    let escaped = false;
+    let braces = 0;
+    let blockComment = false;
+    let lineComment = false;
+    for (let index = candidates.lastIndex; index < source.length; index += 1) {
+      const char = source[index];
+      const next = source[index + 1];
+      if (lineComment) {
+        if (char === "\n") lineComment = false;
+        continue;
+      }
+      if (blockComment) {
+        if (char === "*" && next === "/") {
+          blockComment = false;
+          index += 1;
+        }
+        continue;
+      }
+      if (quote !== null) {
+        if (escaped) {
+          escaped = false;
+        } else if (char === "\\") {
+          escaped = true;
+        } else if (char === quote) {
+          quote = null;
+        }
+        continue;
+      }
+      if (char === "'" || char === '"' || char === "`") {
+        quote = char;
+      } else if (braces > 0 && char === "/" && next === "*") {
+        blockComment = true;
+        index += 1;
+      } else if (braces > 0 && char === "/" && next === "/") {
+        lineComment = true;
+        index += 1;
+      } else if (char === "{") {
+        braces += 1;
+      } else if (char === "}") {
+        if (braces === 0) break;
+        braces -= 1;
+      } else if (char === ">" && braces === 0) {
+        const openingTag = source.slice(candidate.index, index + 1);
+        if (/\/\s*>$/.test(openingTag)) break;
+        return { end: index + 1, indent: candidate[1] ?? "" };
+      }
+    }
+  }
+  return null;
+}
 function ensureMarkerInJsxShell(source, framework) {
   if (!hasJsxShell(framework)) {
     return { source, action: "unsupported" };
   }
   const stripped = source.replace(REGION_RE, "");
   if (stripped.includes(PROD_MARKER_GLOBAL)) {
-    return { source, action: "manual" };
+    return { source: stripped, action: "manual" };
   }
   const block = (indent) => [REGION_OPEN, ...buildSourceMarkerSnippet(framework).split("\n"), REGION_CLOSE].map((line) => `${indent}${line}`).join("\n");
-  const widget = stripped.match(/^([ \t]*).*patchstack-widget.*$/m);
-  if (widget?.index !== void 0) {
-    const indent = widget[1] ?? "";
+  for (const tagName of ["head", "body"]) {
+    const anchor = findJsxShellAnchor(stripped, tagName);
+    if (anchor === null) continue;
+    const indent = `${anchor.indent}  `;
+    const remainder = stripped.slice(anchor.end);
+    const separator = remainder.startsWith("\n") || remainder.startsWith("\r") ? "" : "\n";
     return {
-      source: `${stripped.slice(0, widget.index)}${block(indent)}
-${stripped.slice(widget.index)}`,
+      source: `${stripped.slice(0, anchor.end)}
+${block(indent)}${separator}${remainder}`,
       action: "added"
     };
   }
-  for (const anchor of [/^([ \t]*)<head>[ \t]*$/m, /^([ \t]*)<body>[ \t]*$/m]) {
-    const match = stripped.match(anchor);
-    if (match?.index === void 0) {
-      continue;
-    }
-    const end = match.index + match[0].length;
-    const indent = `${match[1] ?? ""}  `;
-    return {
-      source: `${stripped.slice(0, end)}
-${block(indent)}${stripped.slice(end)}`,
-      action: "added"
-    };
-  }
-  return { source, action: "no-anchor" };
+  return { source: stripped, action: "no-anchor" };
 }
 function ensureSourceMarker(cwd, shell, framework) {
   if (shell === null) {
@@ -2123,7 +2169,7 @@ function ensureSourceMarker(cwd, shell, framework) {
   const file = path7.resolve(cwd, shell);
   const before = readFileSync(file, "utf8");
   const result = ensureMarkerInJsxShell(before, framework);
-  if (result.source !== before && result.action === "added") {
+  if (result.source !== before) {
     writeFileSync(file, result.source);
   }
   return { ...result, shell };
@@ -4912,12 +4958,16 @@ var FS_PACKAGES = ["fs-extra", "graceful-fs", "memfs"];
 var isFsPackage = (pkg) => /^node:fs(\/promises)?$/.test(pkg) || FS_PACKAGES.includes(pkg);
 var EXEC_PACKAGES = ["execa", "cross-spawn", "shelljs", "zx"];
 var isExecPackage = (pkg) => pkg === "node:child_process" || EXEC_PACKAGES.includes(pkg);
+var DESERIALIZE_CALLS = /^unserialize$/;
+var DESERIALIZE_PACKAGES = ["node-serialize"];
+var isDeserializePackage = (pkg) => DESERIALIZE_PACKAGES.includes(pkg);
 function recognizedSinkKinds(pkg) {
   const kinds = [];
   if (isDbPackage(pkg)) kinds.push("db");
   if (isFsPackage(pkg)) kinds.push("fs");
   if (isExecPackage(pkg)) kinds.push("exec");
   if (isHttpPackage(pkg)) kinds.push("http");
+  if (isDeserializePackage(pkg)) kinds.push("eval");
   return kinds;
 }
 function collectLocalSinks(sf, ts, bindings, ctx) {
@@ -5031,6 +5081,9 @@ function directSinks(node, ts, bindings, ctx) {
           if (EXEC_CALLS.test(method) && b.pkg && isExecPackage(b.pkg)) {
             push({ kind: "exec", package: b.pkg, op: method, attribution: "import", ...spanOf(n) });
           }
+          if (DESERIALIZE_CALLS.test(method) && b.pkg && isDeserializePackage(b.pkg)) {
+            push({ kind: "eval", provider: b.root, package: b.pkg, op: method, attribution: "import", ...spanOf(n) });
+          }
           if (HTTP_MEMBER_METHODS.has(method)) {
             if (b.pkg && isHttpPackage(b.pkg)) {
               push({ kind: "http", provider: b.root, package: b.pkg, op: method, attribution: "import", ...spanOf(n) });
@@ -5058,6 +5111,9 @@ function directSinks(node, ts, bindings, ctx) {
           push({ kind: "exec", package: pkg, op: name, attribution: "import", ...spanOf(n) });
         }
         if (name === "eval" && trueGlobal) push({ kind: "eval", op: "eval", attribution: "global", ...spanOf(n) });
+        if (DESERIALIZE_CALLS.test(name) && pkg && isDeserializePackage(pkg)) {
+          push({ kind: "eval", package: pkg, op: name, attribution: "import", ...spanOf(n) });
+        }
       }
     }
     if (ts.isNewExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === "Function" && !bindings.locals.has("Function") && !isShadowedByEnclosingBinding(n, "Function", ts)) {
@@ -5134,6 +5190,7 @@ var CANDIDATE_FAMILIES = {
 };
 function argumentRoleOf(sinkKind, method, index, total = 0) {
   if (sinkKind === "eval" && method === "Function") return index === total - 1 ? "code" : "args";
+  if (sinkKind === "eval" && method === "unserialize") return index === 0 ? "code" : "unknown";
   const table = method ? ARGUMENT_ROLES[sinkKind]?.[method] : void 0;
   return table?.[index] ?? "unknown";
 }
@@ -6673,6 +6730,41 @@ function wireBuildScripts(cwd, packageManager) {
   };
 }
 
+// src/build-hook.ts
+var INSTALL_AND_BUILD_EVENTS = /* @__PURE__ */ new Set([
+  "preinstall",
+  "install",
+  "postinstall",
+  "prepare",
+  "prebuild",
+  "build",
+  "postbuild"
+]);
+function isInstallOrBuildHook(env = process.env) {
+  const event = env.npm_lifecycle_event;
+  return typeof event === "string" && INSTALL_AND_BUILD_EVENTS.has(event);
+}
+function undeliveredReportLines(err, config, cwd) {
+  const lines = [`patchstack: manifest not reported \u2014 ${err.message}`];
+  if (err.code === "UNAUTHORIZED") {
+    const hasCredential = typeof config.pulseAuth === "string" && config.pulseAuth.length > 0;
+    if (hasCredential) {
+      lines.push(
+        "patchstack: the credential this environment holds was rejected. If `login` rotated it, set the new value as PATCHSTACK_API_KEY here."
+      );
+    } else {
+      lines.push(
+        `patchstack: PATCHSTACK_API_KEY is not set, and neither ${SECRET_CONFIG_FILENAME} nor .patchstackrc.json in ${cwd} holds a credential.`,
+        `patchstack: ${SECRET_CONFIG_FILENAME} is git-ignored, so a clean checkout never has it. Set PATCHSTACK_API_KEY in the platform's environment so builds can report.`
+      );
+    }
+  }
+  lines.push(
+    "patchstack: continuing the build. Patchstack keeps the last manifest it accepted for this site until a scan that can report."
+  );
+  return lines;
+}
+
 // src/cli.ts
 var HELP = `@patchstack/connect \u2014 scan your lockfile and report packages to Patchstack.
 
@@ -6684,7 +6776,11 @@ Usage:
                                                      disclosure-widget <script> tag in the root
                                                      HTML shell (index.html, public/index.html,
                                                      or src/app.html) \u2014 opt out with
-                                                     "widget": false in .patchstackrc.json
+                                                     "widget": false in .patchstackrc.json.
+                                                     Run as a postinstall/prebuild/build hook, a
+                                                     report Patchstack cannot accept is printed
+                                                     and exits 0 so the build goes on; run
+                                                     directly, the same failure exits 1
   patchstack-connect setup  [options]                Finish the bounded project setup: run scan,
                                                      manage the widget, install + verify runtime
                                                      protection, and wire dependency/build scans.
@@ -6751,6 +6847,10 @@ Usage:
                                                      the old one must be updated. Not usable in CI
   patchstack-connect help                            Print this message
 
+Global:
+  --version               Print the installed version of this package and exit
+  --help                  Print this help and exit
+
 Options (for scan, setup, status, and uninstall):
   --site-uuid <uuid>      Override the configured site UUID
   --endpoint <url>        Override the API endpoint
@@ -6980,7 +7080,14 @@ async function runScan(args, options = {}) {
   if (provisioning) {
     console.log("No site UUID configured \u2014 provisioning a new Patchstack site from this manifest\u2026");
   }
-  const response = await postManifest(config, payload);
+  let response;
+  try {
+    response = await postManifest(config, payload);
+  } catch (err) {
+    if (!(err instanceof PatchstackError) || !isInstallOrBuildHook()) throw err;
+    for (const line of undeliveredReportLines(err, config, process.cwd())) console.error(line);
+    return 0;
+  }
   if (provisioning && response.uuid !== void 0 && response.uuid.length > 0) {
     const target = await persistSiteUuid(process.cwd(), response.uuid);
     console.log(`Provisioned site ${response.uuid}. Saved UUID to ${target}.`);
@@ -7445,8 +7552,21 @@ async function runMarkBuild(args) {
   );
   return 0;
 }
+function packageVersion() {
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const manifest = require2("../package.json");
+    return typeof manifest.version === "string" && manifest.version.length > 0 ? manifest.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 async function main() {
   const args = parseArgs(process.argv);
+  if (args.flags.has("version") || args.command === "version") {
+    console.log(packageVersion());
+    return 0;
+  }
   if (args.flags.has("help") || args.command === "help" || args.command === null) {
     console.log(HELP);
     return 0;