Keep a refused report from failing the build it is hooked into (#204)

`setup` wires `scan` into postinstall, prebuild, or the Bun build chain. In that
position, a manifest Patchstack refused or could not receive ended the build, and
the usual reason is one the build cannot fix: the credential file is git-ignored,
so a clean checkout never has it.

When the package manager names the running script as an install or build
lifecycle event, a report that cannot be delivered is now printed in full on
stderr and `scan` exits 0. A direct `scan` still exits 1 for the same failure.
The no-credential line names both config files and the directory it checked,
and points at PATCHSTACK_API_KEY rather than at `login`, which cannot run in a
build.

Bun sets npm_lifecycle_event for `bun run` but not for install-time scripts, so
a postinstall scan under `bun install` still fails closed; the code comment and
README say so.

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: mariojgt

README.md

@@ -160,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:

src/build-hook.ts

@@ -0,0 +1,69 @@
+import { SECRET_CONFIG_FILENAME } from './config.js';
+import type { Config, PatchstackError } from './types.js';
+
+/**
+ * Lifecycle names under which `scan` is a hook on somebody else's install or build: the `postinstall`,
+ * `prebuild` and Bun `build` chain that `setup` wires, and the neighbours a project wires by hand.
+ */
+const INSTALL_AND_BUILD_EVENTS: ReadonlySet<string> = new Set([
+  'preinstall',
+  'install',
+  'postinstall',
+  'prepare',
+  'prebuild',
+  'build',
+  'postbuild',
+]);
+
+/**
+ * Whether this process is a lifecycle hook on an install or build.
+ *
+ * In that position the report is the connector's concern and the build is not: a manifest Patchstack
+ * cannot accept is said in full, and the build goes on. Run directly, the same failure exits non-zero.
+ *
+ * npm, pnpm, Yarn and `bun run` name the running script in `npm_lifecycle_event`; a direct invocation
+ * carries a different name (`npx`, or the bin's own name under Bun) or none at all. Bun does not set it
+ * for install-time scripts, so a `postinstall` hook under `bun install` is not recognised and fails
+ * closed. The variable is inherited by child processes, so a direct run from inside a build's process
+ * tree counts as a hook too — the error is still printed, so what that costs is an exit code, not silence.
+ */
+export function isInstallOrBuildHook(env: NodeJS.ProcessEnv = process.env): boolean {
+  const event = env.npm_lifecycle_event;
+
+  return typeof event === 'string' && INSTALL_AND_BUILD_EVENTS.has(event);
+}
+
+/**
+ * What a hooked `scan` prints when it could not deliver its report.
+ *
+ * The error's own message names the remedy for a developer machine. A build environment needs a different
+ * one: it never has the credential file, `login` refuses to run there, and the only fix is the platform's
+ * environment. Said for the credential cases only; a network or server failure has nothing to set.
+ *
+ * When no credential was found, the line names every source that was checked and where. Somebody who can
+ * see the file on their own machine reads "none is configured" as "the file was not read", and the log is
+ * the only place that can settle it.
+ */
+export function undeliveredReportLines(err: PatchstackError, config: Config, cwd: string): string[] {
+  const lines = [`patchstack: manifest not reported — ${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

@@ -55,8 +55,9 @@ import { runProtect, runVerify } from './protect/install/index.js';
 import { runMap } from './map-command.js';
 import { getStringFlag } from './flags.js';
 import { setupProtection, wireBuildScripts } from './setup.js';
+import { isInstallOrBuildHook, undeliveredReportLines } from './build-hook.js';
 import { detectStack, type StackDescriptor } from './stack.js';
-import { PatchstackError } from './types.js';
+import { PatchstackError, type StoreManifestResponse } from './types.js';
 import { buildWidgetTag, ensureSourceWidget, ensureWidgetInHtml } from './widget.js';
 
 const HELP = `@patchstack/connect — scan your lockfile and report packages to Patchstack.
@@ -69,7 +70,11 @@ Usage:
                                                      disclosure-widget <script> tag in the root
                                                      HTML shell (index.html, public/index.html,
                                                      or src/app.html) — 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.
@@ -428,7 +433,16 @@ async function runScan(
     console.log('No site UUID configured — provisioning a new Patchstack site from this manifest…');
   }
 
-  const response = await postManifest(config, payload);
+  // Hooked into an install or build, the report is this command's concern and the build is not: the
+  // failure is said in full on stderr and the build goes on. A direct `scan` still exits non-zero for it.
+  let response: StoreManifestResponse;
+  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;
+  }
 
   // The server always returns the UUID. If we didn't have one, persist it so
   // every subsequent scan targets the same site.

tests/bin-invocation.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest';
-import { execFileSync } from 'node:child_process';
-import { existsSync, mkdtempSync, rmSync, symlinkSync } from 'node:fs';
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+import { copyFileSync, existsSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
 import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
@@ -78,4 +81,100 @@ describe.skipIf(!built)('the packaged bin, invoked as npm invokes it', () => {
     }));
     expect(pkg['patchstack-connect']).toBe('./dist/cli.js');
   });
+
+  /**
+   * A report the server refuses must not fail the build `scan` is hooked into, and must fail a direct run.
+   *
+   * Driven through the real bin against a local server that refuses everything, because the decision sits
+   * between the network failure and the process exit code, and only the process can show both.
+   */
+  describe('a report the server refuses', () => {
+    async function refusingServer(): Promise<{ endpoint: string; close: () => Promise<void> }> {
+      const server = createServer((_req, res) => {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end('{"error":"unauthorized"}');
+      });
+      await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve));
+      const { port } = server.address() as AddressInfo;
+
+      return {
+        endpoint: `http://127.0.0.1:${port}/monitor/pulse/manifest`,
+        close: () => new Promise<void>((resolve) => server.close(() => resolve())),
+      };
+    }
+
+    // An existing site with no credential anywhere: the state a deploy is in when the credential file
+    // stayed behind on the developer's machine.
+    function projectWithSite(): string {
+      const dir = mkdtempSync(path.join(tmpdir(), 'ps-bin-hook-'));
+      writeFileSync(
+        path.join(dir, 'package.json'),
+        JSON.stringify({ name: 'example-app', version: '1.0.0', dependencies: { axios: '^1.6.0', lodash: '^4.17.21' } }),
+      );
+      copyFileSync(path.join(root, 'tests', 'fixtures', 'package-lock-v3.json'), path.join(dir, 'package-lock.json'));
+      writeFileSync(path.join(dir, '.patchstackrc.json'), JSON.stringify({ siteUuid: '11111111-1111-4111-8111-111111111111' }));
+
+      return dir;
+    }
+
+    // The environment is built from scratch rather than inherited: the parent may itself be running under
+    // a package manager, and the lifecycle name it exported is the very thing under test. Asynchronous
+    // because the refusing server lives on this thread's event loop, and a blocking spawn would starve it.
+    async function runScan(
+      cwd: string,
+      endpoint: string,
+      lifecycleEvent?: string,
+    ): Promise<{ status: number; stderr: string }> {
+      const env: NodeJS.ProcessEnv = {
+        PATH: process.env.PATH,
+        HOME: process.env.HOME,
+        PATCHSTACK_ENDPOINT: endpoint,
+        PATCHSTACK_TIMEOUT_MS: '5000',
+      };
+      if (lifecycleEvent !== undefined) env.npm_lifecycle_event = lifecycleEvent;
+
+      try {
+        const { stderr } = await promisify(execFile)('node', [bin, 'scan'], { cwd, env, encoding: 'utf8' });
+
+        return { status: 0, stderr };
+      } catch (err) {
+        const failed = err as { code?: unknown; stderr?: unknown };
+
+        return {
+          status: typeof failed.code === 'number' ? failed.code : -1,
+          stderr: typeof failed.stderr === 'string' ? failed.stderr : '',
+        };
+      }
+    }
+
+    it('exits 0 from a build hook and says what was not reported', async () => {
+      const server = await refusingServer();
+      const dir = projectWithSite();
+      try {
+        const result = await runScan(dir, server.endpoint, 'build');
+
+        expect(result.status).toBe(0);
+        expect(result.stderr).toContain('manifest not reported');
+        expect(result.stderr).toContain('PATCHSTACK_API_KEY');
+      } finally {
+        await server.close();
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it('exits 1 for the same refusal when run directly', async () => {
+      const server = await refusingServer();
+      const dir = projectWithSite();
+      try {
+        const result = await runScan(dir, server.endpoint);
+
+        expect(result.status).toBe(1);
+        expect(result.stderr).toContain('Error (UNAUTHORIZED)');
+        expect(result.stderr).not.toContain('continuing the build');
+      } finally {
+        await server.close();
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+  });
 });

tests/build-hook.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, it } from 'vitest';
+import { isInstallOrBuildHook, undeliveredReportLines } from '../src/build-hook.js';
+import { PatchstackError, type Config } from '../src/types.js';
+
+/**
+ * A hooked `scan` must not fail the build it is attached to, and must say why the report did not land.
+ *
+ * The hook is recognised by the lifecycle name the package manager exports, so these pin which names
+ * count: the ones `setup` wires and their neighbours, and none of the names a person or an assistant
+ * produces by running the command directly. The messages are pinned because the error's own remedy —
+ * run `login` — is the wrong one in a build environment, and that text is what the build log shows.
+ */
+describe('isInstallOrBuildHook', () => {
+  it('recognises the install and build lifecycle names', () => {
+    for (const event of ['preinstall', 'install', 'postinstall', 'prepare', 'prebuild', 'build', 'postbuild']) {
+      expect(isInstallOrBuildHook({ npm_lifecycle_event: event })).toBe(true);
+    }
+  });
+
+  it('does not recognise a direct invocation', () => {
+    // `npx` names its event `npx`, `bun <bin>` names it after the bin, a project script after itself, and a
+    // bare `node` sets nothing.
+    for (const event of ['npx', 'patchstack-connect', 'scan', 'dev', 'start', 'test', '']) {
+      expect(isInstallOrBuildHook({ npm_lifecycle_event: event })).toBe(false);
+    }
+    expect(isInstallOrBuildHook({})).toBe(false);
+  });
+});
+
+describe('undeliveredReportLines', () => {
+  const config = (over: Partial<Config> = {}): Config => ({
+    siteUuid: '11111111-1111-4111-8111-111111111111',
+    apiKey: null,
+    pulseAuth: null,
+    endpoint: 'https://api.test/monitor/pulse/manifest',
+    timeoutMs: 5_000,
+    environment: 'production',
+    widget: true,
+    ...over,
+  });
+
+  it('points a build environment with no credential at the env var, not at login', () => {
+    const said = undeliveredReportLines(new PatchstackError('none configured', 'UNAUTHORIZED'), config(), '/srv/app').join('\n');
+
+    expect(said).toContain('none configured');
+    expect(said).toContain('PATCHSTACK_API_KEY');
+    expect(said).toContain('continuing the build');
+  });
+
+  it('names every source it checked, and where, when no credential was found', () => {
+    // The question a build log has to settle is whether the file was read at all. Naming both files and
+    // the directory is what turns "none is configured" into an answer.
+    const said = undeliveredReportLines(new PatchstackError('none configured', 'UNAUTHORIZED'), config(), '/srv/app').join('\n');
+
+    expect(said).toContain('.patchstackrc.local.json');
+    expect(said).toContain('.patchstackrc.json');
+    expect(said).toContain('/srv/app');
+    expect(said).toContain('git-ignored');
+  });
+
+  it('says a held credential was rejected rather than missing', () => {
+    const held = config({ apiKey: 'a-secret', pulseAuth: 'a-secret' });
+    const said = undeliveredReportLines(new PatchstackError('rejected', 'UNAUTHORIZED'), held, '/srv/app').join('\n');
+
+    expect(said).toContain('rejected');
+    expect(said).toContain('PATCHSTACK_API_KEY');
+    expect(said).not.toContain('never has');
+    expect(said).not.toContain('/srv/app');
+  });
+
+  it('adds no credential advice to a failure that is not about credentials', () => {
+    // The control: a network failure with credential advice attached would send someone to set a variable
+    // that changes nothing.
+    for (const code of ['NETWORK_ERROR', 'NETWORK_TIMEOUT', 'SERVER_ERROR', 'SITE_NOT_FOUND', 'VALIDATION_ERROR'] as const) {
+      const lines = undeliveredReportLines(new PatchstackError(`failed: ${code}`, code), config(), '/srv/app');
+
+      expect(lines).toHaveLength(2);
+      expect(lines[0]).toContain(`failed: ${code}`);
+      expect(lines.join('\n')).not.toContain('PATCHSTACK_API_KEY');
+      expect(lines[1]).toContain('continuing the build');
+    }
+  });
+
+  it('never prints the credential itself', () => {
+    const held = config({ apiKey: 'the-secret-value-0001', pulseAuth: 'the-secret-value-0001' });
+    const said = undeliveredReportLines(new PatchstackError('rejected', 'UNAUTHORIZED'), held, '/srv/app').join('\n');
+
+    expect(said).not.toContain('the-secret-value-0001');
+  });
+});