@patchstack/connect 0.3.29 → 0.3.31

package/dist/index.d.cts

@@ -74,7 +74,7 @@ declare class PatchstackError extends Error {
 }
 
 type LockfileFilename = 'package-lock.json' | 'bun.lock' | 'bun.lockb' | 'yarn.lock' | 'pnpm-lock.yaml';
-type DetectionStrategy = 'npm-lockfile' | 'node-modules-walk' | 'pnpm-lockfile' | 'yarn-lockfile';
+type DetectionStrategy = 'npm-lockfile' | 'bun-lockfile' | 'node-modules-walk' | 'pnpm-lockfile' | 'yarn-lockfile';
 interface DetectedLockfile {
     ecosystem: 'npm';
     filePath: string;
@@ -87,10 +87,45 @@ declare function scanLockfile(cwd: string): Promise<Manifest>;
 interface WirePackage {
     name: string;
     version: string;
+    /**
+     * Where this exact name+version is installed, repo-relative and sorted.
+     *
+     * The same package can be installed more than once at different versions — a workspace pinning an old
+     * copy under `apps/api/node_modules`, a transitive dependency getting its own nested install. Without
+     * the locations, `lodash@4.17.11` and `lodash@4.17.21` arrive as two bare pairs and nothing can say
+     * WHICH one the app's own import resolves to. A consumer then has to treat every installed version as
+     * if the code used it: it warns on a copy nothing reaches, or pins a rule to a route running the safe
+     * one — a rule that never fires while reporting as protection.
+     *
+     * Node resolves an import by walking up from the importing file, so the map's import sites plus these
+     * paths together answer the question. Neither half answers it alone.
+     *
+     * OPT-IN. Absent unless the caller asks for locations (`scan --install-paths`), and absent even then
+     * when the scan source does not record them — see `installPathsComplete`, which is what separates
+     * "not installed there" from "we were not told".
+     *
+     * Off by default because it changes what leaves the machine. The package's standing promise is that
+     * `scan` sends names and versions and no paths of any kind; locations are a real widening of that, and
+     * an upload that widens it should be an explicit choice rather than a consequence of upgrading.
+     */
+    paths?: string[];
 }
 interface WirePayload {
     ecosystem: Manifest['ecosystem'];
     packages: WirePackage[];
+    /**
+     * Whether every entry's `paths` is the complete set of locations for it.
+     *
+     * False when locations were not requested at all, when the scan source cannot supply them (a yarn.lock
+     * is flat — hoisting is decided at install time and the file does not record it; a v1 npm lockfile
+     * describes the dependency graph, not the tree), or when only some entries had one. A consumer MUST NOT
+     * read a missing or short `paths` as "installed nowhere else" while this is false; absence is then "not
+     * recorded", which is not an answer.
+     *
+     * The default is therefore `false`, and that is the safe direction: the field withholds a negative
+     * rather than granting one.
+     */
+    installPathsComplete: boolean;
 }
 interface NormalizeStats {
     uniqueNames: number;
@@ -101,7 +136,14 @@ interface NormalizeResult {
     payload: WirePayload;
     stats: NormalizeStats;
 }
-declare function buildWirePayload(manifest: Manifest): NormalizeResult;
+interface WireOptions {
+    /**
+     * Include each package's install location. Off by default — see `WirePackage.paths`: it widens what
+     * `scan` transmits, so it is the caller's explicit choice, not a side effect of upgrading.
+     */
+    installPaths?: boolean;
+}
+declare function buildWirePayload(manifest: Manifest, options?: WireOptions): NormalizeResult;
 declare function compareVersions(a: string, b: string): number;
 
 declare const DEFAULT_ENDPOINT = "https://api.patchstack.com/monitor/pulse/manifest";
@@ -145,21 +187,40 @@ interface ResolveConfigOptions {
 }
 declare function resolveConfig(options: ResolveConfigOptions): Promise<Config>;
 declare function writeConfigFile(cwd: string, config: ConfigFile): Promise<string>;
+/**
+ * What happened to the credential file, so a caller can say only what is true.
+ *
+ * `ignored` is the OUTCOME of the ignore entry, verified by reading the file back — not the fact that a
+ * write was attempted. Telling somebody their credential is ignored when it is not is worse than telling
+ * them nothing: they stop looking, and a credential committed once is in the history whether or not the
+ * file is removed afterwards.
+ */
+interface SecretFileResult {
+    /** Absolute path of the credential file. */
+    path: string;
+    /** True only when `.gitignore` was read back and really covers it. */
+    ignored: boolean;
+    /** Why not, when it is not — for the caller to print instead of a false assurance. */
+    reason?: string;
+}
 /**
  * Merge a new siteUuid into the existing `.patchstackrc.json` (or create it).
  * Preserves any `endpoint` / `timeoutMs` / `apiKey` the user already wrote.
  */
 declare function persistSiteUuid(cwd: string, siteUuid: string): Promise<string>;
 /**
- * Persist the WP-format api_key issued at provision. Authenticates both the
- * Pulse endpoints and connector log reporting. Never embed it in the public
- * disclosure widget.
+ * Persist the WP-format api_key issued at provision. Authenticates both the Pulse endpoints and connector
+ * log reporting. Never embed it in the public disclosure widget.
  *
- * Drops any `pulseAuth` written by an earlier version. That field resolves
- * ahead of `apiKey`, so leaving a copy behind after the credential changes
- * would leave Pulse authenticating with the value the server just replaced.
+ * Written to the credential file, which setup adds to the project's ignore list — the public config is
+ * meant to be committed, so a credential in it is a credential in the repository.
+ *
+ * Any copy in the committed config is REMOVED at the same time. Leaving it would mean the value that just
+ * got moved is still in the file everyone commits, which is the state this split exists to end. `pulseAuth`
+ * goes with it: that field resolves ahead of `apiKey`, so a stale copy would keep authenticating with a
+ * credential the server has replaced.
  */
-declare function persistApiKey(cwd: string, apiKey: string): Promise<string>;
+declare function persistApiKey(cwd: string, apiKey: string): Promise<SecretFileResult>;
 /**
  * Persist a Pulse-specific credential.
  *
@@ -167,7 +228,7 @@ declare function persistApiKey(cwd: string, apiKey: string): Promise<string>;
  * credentials; they share one today, so `persistApiKey` covers both. Retained
  * for callers that separate them.
  */
-declare function persistPulseAuth(cwd: string, pulseAuth: string): Promise<string>;
+declare function persistPulseAuth(cwd: string, pulseAuth: string): Promise<SecretFileResult>;
 
 /**
  * A best-effort description of the stack a build was produced with, derived
@@ -251,6 +312,11 @@ declare function ensureSourceWidget(cwd: string, siteUuid: string): SourceWidget
 interface ScanAndReportOptions {
     cwd?: string;
     config?: Config;
+    /**
+     * Include each package's install location in the uploaded payload. Off by default: it widens what
+     * leaves the machine, so it is an explicit choice rather than something an upgrade turns on.
+     */
+    installPaths?: boolean;
 }
 interface ScanAndReportResult {
     manifest: Manifest;

package/dist/index.d.ts

@@ -74,7 +74,7 @@ declare class PatchstackError extends Error {
 }
 
 type LockfileFilename = 'package-lock.json' | 'bun.lock' | 'bun.lockb' | 'yarn.lock' | 'pnpm-lock.yaml';
-type DetectionStrategy = 'npm-lockfile' | 'node-modules-walk' | 'pnpm-lockfile' | 'yarn-lockfile';
+type DetectionStrategy = 'npm-lockfile' | 'bun-lockfile' | 'node-modules-walk' | 'pnpm-lockfile' | 'yarn-lockfile';
 interface DetectedLockfile {
     ecosystem: 'npm';
     filePath: string;
@@ -87,10 +87,45 @@ declare function scanLockfile(cwd: string): Promise<Manifest>;
 interface WirePackage {
     name: string;
     version: string;
+    /**
+     * Where this exact name+version is installed, repo-relative and sorted.
+     *
+     * The same package can be installed more than once at different versions — a workspace pinning an old
+     * copy under `apps/api/node_modules`, a transitive dependency getting its own nested install. Without
+     * the locations, `lodash@4.17.11` and `lodash@4.17.21` arrive as two bare pairs and nothing can say
+     * WHICH one the app's own import resolves to. A consumer then has to treat every installed version as
+     * if the code used it: it warns on a copy nothing reaches, or pins a rule to a route running the safe
+     * one — a rule that never fires while reporting as protection.
+     *
+     * Node resolves an import by walking up from the importing file, so the map's import sites plus these
+     * paths together answer the question. Neither half answers it alone.
+     *
+     * OPT-IN. Absent unless the caller asks for locations (`scan --install-paths`), and absent even then
+     * when the scan source does not record them — see `installPathsComplete`, which is what separates
+     * "not installed there" from "we were not told".
+     *
+     * Off by default because it changes what leaves the machine. The package's standing promise is that
+     * `scan` sends names and versions and no paths of any kind; locations are a real widening of that, and
+     * an upload that widens it should be an explicit choice rather than a consequence of upgrading.
+     */
+    paths?: string[];
 }
 interface WirePayload {
     ecosystem: Manifest['ecosystem'];
     packages: WirePackage[];
+    /**
+     * Whether every entry's `paths` is the complete set of locations for it.
+     *
+     * False when locations were not requested at all, when the scan source cannot supply them (a yarn.lock
+     * is flat — hoisting is decided at install time and the file does not record it; a v1 npm lockfile
+     * describes the dependency graph, not the tree), or when only some entries had one. A consumer MUST NOT
+     * read a missing or short `paths` as "installed nowhere else" while this is false; absence is then "not
+     * recorded", which is not an answer.
+     *
+     * The default is therefore `false`, and that is the safe direction: the field withholds a negative
+     * rather than granting one.
+     */
+    installPathsComplete: boolean;
 }
 interface NormalizeStats {
     uniqueNames: number;
@@ -101,7 +136,14 @@ interface NormalizeResult {
     payload: WirePayload;
     stats: NormalizeStats;
 }
-declare function buildWirePayload(manifest: Manifest): NormalizeResult;
+interface WireOptions {
+    /**
+     * Include each package's install location. Off by default — see `WirePackage.paths`: it widens what
+     * `scan` transmits, so it is the caller's explicit choice, not a side effect of upgrading.
+     */
+    installPaths?: boolean;
+}
+declare function buildWirePayload(manifest: Manifest, options?: WireOptions): NormalizeResult;
 declare function compareVersions(a: string, b: string): number;
 
 declare const DEFAULT_ENDPOINT = "https://api.patchstack.com/monitor/pulse/manifest";
@@ -145,21 +187,40 @@ interface ResolveConfigOptions {
 }
 declare function resolveConfig(options: ResolveConfigOptions): Promise<Config>;
 declare function writeConfigFile(cwd: string, config: ConfigFile): Promise<string>;
+/**
+ * What happened to the credential file, so a caller can say only what is true.
+ *
+ * `ignored` is the OUTCOME of the ignore entry, verified by reading the file back — not the fact that a
+ * write was attempted. Telling somebody their credential is ignored when it is not is worse than telling
+ * them nothing: they stop looking, and a credential committed once is in the history whether or not the
+ * file is removed afterwards.
+ */
+interface SecretFileResult {
+    /** Absolute path of the credential file. */
+    path: string;
+    /** True only when `.gitignore` was read back and really covers it. */
+    ignored: boolean;
+    /** Why not, when it is not — for the caller to print instead of a false assurance. */
+    reason?: string;
+}
 /**
  * Merge a new siteUuid into the existing `.patchstackrc.json` (or create it).
  * Preserves any `endpoint` / `timeoutMs` / `apiKey` the user already wrote.
  */
 declare function persistSiteUuid(cwd: string, siteUuid: string): Promise<string>;
 /**
- * Persist the WP-format api_key issued at provision. Authenticates both the
- * Pulse endpoints and connector log reporting. Never embed it in the public
- * disclosure widget.
+ * Persist the WP-format api_key issued at provision. Authenticates both the Pulse endpoints and connector
+ * log reporting. Never embed it in the public disclosure widget.
  *
- * Drops any `pulseAuth` written by an earlier version. That field resolves
- * ahead of `apiKey`, so leaving a copy behind after the credential changes
- * would leave Pulse authenticating with the value the server just replaced.
+ * Written to the credential file, which setup adds to the project's ignore list — the public config is
+ * meant to be committed, so a credential in it is a credential in the repository.
+ *
+ * Any copy in the committed config is REMOVED at the same time. Leaving it would mean the value that just
+ * got moved is still in the file everyone commits, which is the state this split exists to end. `pulseAuth`
+ * goes with it: that field resolves ahead of `apiKey`, so a stale copy would keep authenticating with a
+ * credential the server has replaced.
  */
-declare function persistApiKey(cwd: string, apiKey: string): Promise<string>;
+declare function persistApiKey(cwd: string, apiKey: string): Promise<SecretFileResult>;
 /**
  * Persist a Pulse-specific credential.
  *
@@ -167,7 +228,7 @@ declare function persistApiKey(cwd: string, apiKey: string): Promise<string>;
  * credentials; they share one today, so `persistApiKey` covers both. Retained
  * for callers that separate them.
  */
-declare function persistPulseAuth(cwd: string, pulseAuth: string): Promise<string>;
+declare function persistPulseAuth(cwd: string, pulseAuth: string): Promise<SecretFileResult>;
 
 /**
  * A best-effort description of the stack a build was produced with, derived
@@ -251,6 +312,11 @@ declare function ensureSourceWidget(cwd: string, siteUuid: string): SourceWidget
 interface ScanAndReportOptions {
     cwd?: string;
     config?: Config;
+    /**
+     * Include each package's install location in the uploaded payload. Off by default: it widens what
+     * leaves the machine, so it is an explicit choice rather than something an upgrade turns on.
+     */
+    installPaths?: boolean;
 }
 interface ScanAndReportResult {
     manifest: Manifest;