@patchstack/connect 0.1.0 → 0.2.4

package/README.md

@@ -6,23 +6,51 @@ Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.co
 
 Copy and paste this prompt into any AI coding assistant (Cursor, v0, Bolt, Lovable, Claude Code, etc.):
 
-> Add `@patchstack/connect` to this project as a dev dependency. Run `npx @patchstack/connect init <SITE_UUID>` once to save the site UUID, then add `"prebuild": "patchstack-connect scan"` to `package.json` `scripts` so dependencies are reported to Patchstack on every build. Replace `<SITE_UUID>` with the UUID from the Patchstack dashboard.
+> Add `@patchstack/connect` to this project as a dev dependency, then add `"prebuild": "patchstack-connect scan"` to `package.json` `scripts`. The first time the script runs, Patchstack provisions a site automatically from the lockfile and saves the new site UUID to `.patchstackrc.json` — no dashboard signup or manual UUID required. Commit `.patchstackrc.json` so every developer / CI run targets the same site.
 
-## Quick start
+## Quick start (zero configuration)
 
 ```bash
 npm install --save-dev @patchstack/connect
-npx @patchstack/connect init <your-site-uuid>
 npx @patchstack/connect scan
 ```
 
-Get your site UUID from the Patchstack dashboard: create a new site with type **Application**, then copy the UUID shown on the site's settings page.
+That's it. The first `scan`:
+
+1. Reads your `package-lock.json`.
+2. POSTs the package list to Patchstack with **no** UUID.
+3. Patchstack provisions a fresh site and returns its UUID.
+4. The connector writes the UUID to `.patchstackrc.json` so the next `scan` targets the same site.
+
+Then wire it into builds:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "prebuild": "patchstack-connect scan"
+  }
+}
+```
+
+## Quick start (existing site)
+
+If you already created an "Application" site in the Patchstack dashboard, pre-seed the UUID:
+
+```bash
+npm install --save-dev @patchstack/connect
+npx @patchstack/connect init <your-site-uuid>
+npx @patchstack/connect scan
+```
 
 ## CLI
 
 ```
-patchstack-connect init <site-uuid>                Save the site UUID to .patchstackrc.json
-patchstack-connect scan   [options]                Scan the lockfile and POST to Patchstack
+patchstack-connect scan   [options]                Scan the lockfile and POST to Patchstack.
+                                                   If no UUID is configured the server provisions
+                                                   one and the connector persists it.
+patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json with
+                                                   an existing site UUID
 patchstack-connect status [options]                Show current configuration
 patchstack-connect help                            Print help
 
@@ -43,7 +71,7 @@ Precedence (highest wins):
 Environment variables:
 
 - `PATCHSTACK_SITE_UUID` — the site UUID from your Patchstack dashboard
-- `PATCHSTACK_ENDPOINT` — override the API endpoint (default `https://app.patchstack.com/monitor/pulse/manifest`)
+- `PATCHSTACK_ENDPOINT` — override the API endpoint (default `http://api.patchstack.com/monitor/pulse/manifest`)
 - `PATCHSTACK_TIMEOUT_MS` — request timeout in milliseconds (default `30000`)
 
 `.patchstackrc.json` example:
@@ -84,10 +112,14 @@ That's the entire payload. No source code, no environment variables, no file pat
 
 ## Supported lockfiles
 
-- ✅ `package-lock.json` (npm v6 / v2 / v3)
+- ✅ `package-lock.json` (npm v6 / v2 / v3) — parsed directly
+- ✅ `bun.lockb` (binary) — package list resolved by walking `node_modules/`
+- ✅ `bun.lock` (text) — same fallback; direct parsing coming
 - ❌ `yarn.lock` — coming soon
 - ❌ `pnpm-lock.yaml` — coming soon
 
+If both a Bun lockfile and `node_modules/` are present, the connector walks `node_modules/` to enumerate the installed packages. Run `bun install` (or `npm install`) before scanning so the directory is populated.
+
 ## Development
 
 ```bash
@@ -97,6 +129,34 @@ npm test
 npm run build
 ```
 
+## 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:
+
+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:
+
+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.
+
+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.
+
 ## License
 
 MIT

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
-import path2 from "path";
+import path3 from "path";
 
 // src/types.ts
 var PatchstackError = class extends Error {
@@ -102,20 +102,150 @@ function isDirectV2(pkgPath) {
   return nmCount === 1;
 }
 
+// src/parsers/node_modules.ts
+import { lstat, readFile as readFile2, readdir, stat } from "fs/promises";
+import path2 from "path";
+async function walkNodeModules(cwd) {
+  const root = path2.join(cwd, "node_modules");
+  try {
+    const info = await stat(root);
+    if (!info.isDirectory()) {
+      throw new PatchstackError(
+        `${root} exists but is not a directory.`,
+        "LOCKFILE_NOT_FOUND"
+      );
+    }
+  } catch (cause) {
+    if (cause instanceof PatchstackError) {
+      throw cause;
+    }
+    throw new PatchstackError(
+      `node_modules/ not found at ${cwd}. Install dependencies first (e.g. \`bun install\` or \`npm install\`).`,
+      "LOCKFILE_NOT_FOUND",
+      cause
+    );
+  }
+  const entries = [];
+  await walk(root, entries, 0);
+  return entries;
+}
+async function walk(dir, acc, depth) {
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name.startsWith(".")) {
+      continue;
+    }
+    const fullPath = path2.join(dir, name);
+    if (!await isPlainDirectory(fullPath)) {
+      continue;
+    }
+    if (name.startsWith("@")) {
+      let subNames;
+      try {
+        subNames = await readdir(fullPath);
+      } catch {
+        continue;
+      }
+      for (const sub of subNames) {
+        if (sub.startsWith(".")) {
+          continue;
+        }
+        const scopedDir = path2.join(fullPath, sub);
+        if (!await isPlainDirectory(scopedDir)) {
+          continue;
+        }
+        await readPackage(scopedDir, depth, acc);
+        await walkNested(scopedDir, acc, depth);
+      }
+      continue;
+    }
+    await readPackage(fullPath, depth, acc);
+    await walkNested(fullPath, acc, depth);
+  }
+}
+async function readPackage(pkgDir, depth, acc) {
+  let raw;
+  try {
+    raw = await readFile2(path2.join(pkgDir, "package.json"), "utf8");
+  } catch {
+    return;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return;
+  }
+  if (typeof parsed.name !== "string" || parsed.name.length === 0) {
+    return;
+  }
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    return;
+  }
+  acc.push({
+    name: parsed.name,
+    version: parsed.version,
+    direct: depth === 0
+  });
+}
+async function walkNested(pkgDir, acc, depth) {
+  const nested = path2.join(pkgDir, "node_modules");
+  if (!await isPlainDirectory(nested)) {
+    return;
+  }
+  await walk(nested, acc, depth + 1);
+}
+async function isPlainDirectory(dir) {
+  try {
+    const info = await lstat(dir);
+    return info.isDirectory() && !info.isSymbolicLink();
+  } catch {
+    return false;
+  }
+}
+
 // src/parsers/index.ts
 async function detectLockfile(cwd) {
-  const npmLock = path2.join(cwd, "package-lock.json");
+  const npmLock = path3.join(cwd, "package-lock.json");
   if (await exists(npmLock)) {
-    return { ecosystem: "npm", filePath: npmLock, filename: "package-lock.json" };
-  }
-  const yarnLock = path2.join(cwd, "yarn.lock");
+    return {
+      ecosystem: "npm",
+      filePath: npmLock,
+      filename: "package-lock.json",
+      strategy: "npm-lockfile"
+    };
+  }
+  const bunLock = path3.join(cwd, "bun.lock");
+  if (await exists(bunLock)) {
+    return {
+      ecosystem: "npm",
+      filePath: bunLock,
+      filename: "bun.lock",
+      strategy: "node-modules-walk"
+    };
+  }
+  const bunLockB = path3.join(cwd, "bun.lockb");
+  if (await exists(bunLockB)) {
+    return {
+      ecosystem: "npm",
+      filePath: bunLockB,
+      filename: "bun.lockb",
+      strategy: "node-modules-walk"
+    };
+  }
+  const yarnLock = path3.join(cwd, "yarn.lock");
   if (await exists(yarnLock)) {
     throw new PatchstackError(
       "yarn.lock detected but not yet supported. Run `npm install` to generate a package-lock.json, or open an issue at github.com/patchstack/connect.",
       "LOCKFILE_UNSUPPORTED"
     );
   }
-  const pnpmLock = path2.join(cwd, "pnpm-lock.yaml");
+  const pnpmLock = path3.join(cwd, "pnpm-lock.yaml");
   if (await exists(pnpmLock)) {
     throw new PatchstackError(
       "pnpm-lock.yaml detected but not yet supported. Open an issue at github.com/patchstack/connect to request support.",
@@ -123,15 +253,23 @@ async function detectLockfile(cwd) {
     );
   }
   throw new PatchstackError(
-    `No lockfile found in ${cwd}. Expected one of: package-lock.json, yarn.lock, pnpm-lock.yaml.`,
+    `No lockfile found in ${cwd}. Expected one of: package-lock.json, bun.lock, bun.lockb, yarn.lock, pnpm-lock.yaml.`,
     "LOCKFILE_NOT_FOUND"
   );
 }
 async function scanLockfile(cwd) {
   const detected = await detectLockfile(cwd);
-  const packages = await parseNpmLockfile(detected.filePath);
+  const packages = await runStrategy(detected, cwd);
   return { ecosystem: detected.ecosystem, packages };
 }
+async function runStrategy(detected, cwd) {
+  switch (detected.strategy) {
+    case "npm-lockfile":
+      return parseNpmLockfile(detected.filePath);
+    case "node-modules-walk":
+      return walkNodeModules(cwd);
+  }
+}
 async function exists(filePath) {
   try {
     await access(filePath);
@@ -244,11 +382,11 @@ function compareSegments(a, b) {
 }
 
 // src/client.ts
-var DEFAULT_ENDPOINT = "https://app.patchstack.com/monitor/pulse/manifest";
+var DEFAULT_ENDPOINT = "http://api.patchstack.com/monitor/pulse/manifest";
 var DEFAULT_TIMEOUT_MS = 3e4;
 function buildEndpointUrl(base, siteUuid) {
   const trimmed = base.replace(/\/$/, "");
-  return `${trimmed}/${encodeURIComponent(siteUuid)}`;
+  return siteUuid !== void 0 && siteUuid !== null && siteUuid.length > 0 ? `${trimmed}/${encodeURIComponent(siteUuid)}` : trimmed;
 }
 async function postManifest(config, payload) {
   const url = buildEndpointUrl(config.endpoint, config.siteUuid);
@@ -317,8 +455,8 @@ function isTimeoutError(cause) {
 }
 
 // src/config.ts
-import { readFile as readFile2, writeFile } from "fs/promises";
-import path3 from "path";
+import { readFile as readFile3, writeFile } from "fs/promises";
+import path4 from "path";
 var CONFIG_FILENAME = ".patchstackrc.json";
 async function resolveConfig(options) {
   const fromFile = await readConfigFile(options.cwd);
@@ -326,31 +464,39 @@ async function resolveConfig(options) {
   const siteUuid = options.cliSiteUuid ?? fromEnv.siteUuid ?? fromFile.siteUuid ?? null;
   const endpoint = options.cliEndpoint ?? fromEnv.endpoint ?? fromFile.endpoint ?? DEFAULT_ENDPOINT;
   const timeoutMs = fromEnv.timeoutMs ?? fromFile.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  if (siteUuid === null || siteUuid.length === 0) {
+  if (siteUuid !== null && siteUuid.length > 0 && !isUuid(siteUuid)) {
     throw new PatchstackError(
-      "No site UUID configured. Run `patchstack-connect init <site-uuid>` or set PATCHSTACK_SITE_UUID.",
-      "CONFIG_MISSING"
+      `Site UUID "${siteUuid}" does not look like a valid UUID.`,
+      "CONFIG_INVALID"
     );
   }
-  if (!isUuid(siteUuid)) {
+  if (options.requireSiteUuid && (siteUuid === null || siteUuid.length === 0)) {
     throw new PatchstackError(
-      `Site UUID "${siteUuid}" does not look like a valid UUID.`,
-      "CONFIG_INVALID"
+      "No site UUID configured. Run `patchstack-connect scan` to provision one, or set PATCHSTACK_SITE_UUID.",
+      "CONFIG_MISSING"
     );
   }
-  return { siteUuid, endpoint, timeoutMs };
+  return {
+    siteUuid: siteUuid === null || siteUuid.length === 0 ? null : siteUuid,
+    endpoint,
+    timeoutMs
+  };
 }
 async function writeConfigFile(cwd, config) {
-  const target = path3.join(cwd, CONFIG_FILENAME);
+  const target = path4.join(cwd, CONFIG_FILENAME);
   const content = JSON.stringify(config, null, 2) + "\n";
   await writeFile(target, content, "utf8");
   return target;
 }
+async function persistSiteUuid(cwd, siteUuid) {
+  const existing = await readConfigFile(cwd);
+  return writeConfigFile(cwd, { ...existing, siteUuid });
+}
 async function readConfigFile(cwd) {
-  const target = path3.join(cwd, CONFIG_FILENAME);
+  const target = path4.join(cwd, CONFIG_FILENAME);
   let raw;
   try {
-    raw = await readFile2(target, "utf8");
+    raw = await readFile3(target, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return {};
@@ -398,8 +544,11 @@ function isUuid(value) {
 var HELP = `@patchstack/connect \u2014 scan your lockfile and report packages to Patchstack.
 
 Usage:
-  patchstack-connect init <site-uuid>                Save the site UUID to .patchstackrc.json
-  patchstack-connect scan   [options]                Scan lockfile and POST to Patchstack
+  patchstack-connect scan   [options]                Scan lockfile and POST to Patchstack.
+                                                     If no UUID is configured, the server
+                                                     provisions one and we persist it.
+  patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json
+                                                     with an existing site UUID
   patchstack-connect status [options]                Show current configuration
   patchstack-connect help                            Print this message
 
@@ -410,15 +559,15 @@ Options (for scan and status):
 
 Environment:
   PATCHSTACK_SITE_UUID    Site UUID
-  PATCHSTACK_ENDPOINT     API endpoint (default: https://app.patchstack.com/monitor/pulse/manifest)
+  PATCHSTACK_ENDPOINT     API endpoint (default: http://api.patchstack.com/monitor/pulse/manifest)
   PATCHSTACK_TIMEOUT_MS   Request timeout in ms (default: 30000)
 
 Precedence: CLI flag > environment variable > .patchstackrc.json.
 
 Examples:
-  npx @patchstack/connect init 550e8400-e29b-41d4-a716-446655440000
   npx @patchstack/connect scan
   npx @patchstack/connect scan --dry-run
+  npx @patchstack/connect init 550e8400-e29b-41d4-a716-446655440000
   npx @patchstack/connect scan --site-uuid 550e8400-...-446655440000
 `;
 var VALUE_FLAGS = /* @__PURE__ */ new Set(["site-uuid", "endpoint"]);
@@ -493,7 +642,12 @@ async function runScan(args) {
   }
   if (dryRun) {
     console.log("");
-    console.log("--dry-run: not posting to Patchstack. Payload preview:");
+    if (config.siteUuid === null) {
+      console.log("--dry-run: no site UUID configured. A real run would provision one.");
+    } else {
+      console.log(`--dry-run: not posting to Patchstack (site UUID ${config.siteUuid}).`);
+    }
+    console.log("Payload preview:");
     const preview = JSON.stringify(payload, null, 2).split("\n");
     console.log(preview.slice(0, Math.min(preview.length, 30)).join("\n"));
     if (preview.length > 30) {
@@ -501,7 +655,15 @@ async function runScan(args) {
     }
     return 0;
   }
+  const provisioning = config.siteUuid === null;
+  if (provisioning) {
+    console.log("No site UUID configured \u2014 provisioning a new Patchstack site from this manifest\u2026");
+  }
   const response = await postManifest(config, payload);
+  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}.`);
+  }
   if (response.stored) {
     console.log(`Stored manifest #${response.manifest_id} (checksum ${response.checksum}).`);
   } else if (response.reason === "duplicate") {
@@ -512,23 +674,15 @@ async function runScan(args) {
   return 0;
 }
 async function runStatus(args) {
-  try {
-    const config = await resolveConfig({
-      cwd: process.cwd(),
-      cliSiteUuid: getStringFlag(args.flags, "site-uuid"),
-      cliEndpoint: getStringFlag(args.flags, "endpoint")
-    });
-    console.log(`Site UUID:  ${config.siteUuid}`);
-    console.log(`Endpoint:   ${config.endpoint}`);
-    console.log(`Timeout:    ${config.timeoutMs}ms`);
-    return 0;
-  } catch (err) {
-    if (err instanceof PatchstackError && err.code === "CONFIG_MISSING") {
-      console.log("Not configured. Run `patchstack-connect init <site-uuid>` to get started.");
-      return 0;
-    }
-    throw err;
-  }
+  const config = await resolveConfig({
+    cwd: process.cwd(),
+    cliSiteUuid: getStringFlag(args.flags, "site-uuid"),
+    cliEndpoint: getStringFlag(args.flags, "endpoint")
+  });
+  console.log(`Site UUID:  ${config.siteUuid ?? "(none yet \u2014 the next `scan` will provision one)"}`);
+  console.log(`Endpoint:   ${config.endpoint}`);
+  console.log(`Timeout:    ${config.timeoutMs}ms`);
+  return 0;
 }
 async function main() {
   const args = parseArgs(process.argv);