srclawyer 0.4.0 → 0.4.1

package/README.md

@@ -8,16 +8,58 @@ Static analysis engine that derives privacy policy documentation directly from s
 
 ## Usage
 
+No install needed for a first try — `npx` fetches and runs the latest version on demand:
+
+```bash
+npx srclawyer init     # one-time: jurisdiction, markets, industry
+npx srclawyer scan     # analyze the codebase and write PRIVACY_POLICY.md
+```
+
+For a persistent `srclawyer` command instead of typing `npx` every time:
+
 ```bash
+npm install -g srclawyer
+srclawyer init
+srclawyer scan                  # analyze the codebase and write PRIVACY_POLICY.md
+srclawyer scan --json           # findings as JSON (still writes the policy file)
+srclawyer scan --out docs/privacy.md
+```
+
+If `srclawyer` isn't found right after a global install, see [Troubleshooting: command not found](#troubleshooting-command-not-found) below.
+
+## Development
+
+Working on SrcLawyer itself (not just using it):
+
+```bash
+git clone https://github.com/SrcLawyer/srclawyer.git
+cd srclawyer
 npm install
 npm run build
-node dist/cli.js init            # one-time: jurisdiction, markets, industry
-node dist/cli.js scan            # analyze the codebase and write PRIVACY_POLICY.md
-node dist/cli.js scan --json     # findings as JSON (still writes the policy file)
-node dist/cli.js scan --out docs/privacy.md
+node dist/cli.js scan
 ```
 
-During development, run directly from source with `npm run dev -- scan`.
+Or run directly from source without building first: `npm run dev -- scan`.
+
+## Troubleshooting: command not found
+
+After `npm install -g srclawyer`, the install prints `added N packages` but the `srclawyer` command isn't recognized. This almost always means the command *was* installed — npm's own global bin directory just isn't on your shell's `PATH`, or your shell doesn't know about it yet.
+
+**The most common cause: conda.** If you have Anaconda/Miniconda installed with `auto_activate_base` enabled (the default), conda prepends its own directories to `PATH` every time a new shell starts — this can land ahead of, or instead of, the directory npm actually installed into. Symptoms: `srclawyer` works in some terminals/tabs but not others, or never works despite the install reporting success.
+
+Steps, in order of how likely each is to fix it:
+
+1. **Open a brand-new terminal window or tab.** `PATH` is set when a shell starts; a terminal that was already open won't pick up a global install that happened after it launched.
+2. **If a new terminal doesn't help, check where npm actually put it versus what's on your `PATH`:**
+   ```bash
+   npm config get prefix      # where npm installs global packages
+   echo $PATH                 # does the above, plus "/bin", appear in here?
+   ```
+   If `npm config get prefix`'s `bin` subdirectory (or, on Windows, the prefix itself) isn't listed in `$PATH` at all, that's the root cause — your shell's startup files (`.zshrc`, `.bashrc`, `.bash_profile`) need a line adding it, e.g. `export PATH="$(npm config get prefix)/bin:$PATH"`.
+3. **If conda specifically is the culprit** (its paths appear in `$PATH` ahead of npm's prefix, or npm's prefix is missing because conda's own Node/npm shadowed the one you expected to use): either run `conda deactivate` before using `srclawyer`, or turn off automatic activation so it stops happening on every new shell: `conda config --set auto_activate_base false`.
+4. **If `srclawyer` still isn't found after fixing `PATH`**, your shell may have cached the old (missing) command location. Clear that cache: `hash -r` (bash) or `rehash` (zsh), then try again without opening a new terminal.
+
+If none of this resolves it, `npx srclawyer scan` (see [Usage](#usage) above) sidesteps `PATH` entirely, since `npx` always invokes the binary directly rather than relying on it being a recognized shell command.
 
 ## What `scan` does today
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "srclawyer",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Static analysis engine that derives privacy policy documentation directly from source code",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -20,11 +20,13 @@
     "./package.json": "./package.json"
   },
   "files": [
-    "dist"
+    "dist",
+    "postinstall.cjs"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "prepare": "npm run build",
+    "postinstall": "node postinstall.cjs",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
     "test:corpus": "tsx scripts/scoreCorpus.ts",

package/postinstall.cjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Advisory-only PATH check, run via the "postinstall" lifecycle hook. Plain, dependency-free
+ * CommonJS (not compiled from src/) on purpose: postinstall fires BEFORE "prepare" in npm's
+ * lifecycle order, so dist/ doesn't exist yet during this repo's own `npm install` -- a compiled
+ * script referencing dist/ would break every contributor's first install. A real, pre-built
+ * tarball install (the actual target of this check) always has this file on disk already.
+ *
+ * IMPORTANT, confirmed empirically: npm (v7+) does NOT share stdio with lifecycle scripts by
+ * default -- normal process.stdout/stderr writes from here are silently swallowed for a plain
+ * `npm install -g`, visible only with the rarely-used --foreground-scripts flag. Exiting non-zero
+ * to force visibility was tried and rejected -- it doesn't just print an ugly error, it makes npm
+ * abort the install entirely (the package's files never get placed), which is worse than saying
+ * nothing. Writing directly to the controlling terminal device (bypassing the suppressed stdio) is
+ * the standard real-world workaround for this exact npm behavior, so that's what this does, with a
+ * plain stderr write as the fallback for when there's no TTY to open (CI, non-interactive installs)
+ * -- at that point this is genuinely best-effort, not guaranteed.
+ *
+ * Never fails the install over this: worst case is silence, never a non-zero exit or a thrown
+ * error reaching npm's own install process.
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+function pathImplFor(platform) {
+  return platform === "win32" ? path.win32 : path.posix;
+}
+
+function globalBinDir(prefix, platform) {
+  if (!prefix) return null;
+  return platform === "win32" ? prefix : pathImplFor(platform).join(prefix, "bin");
+}
+
+function normalize(p, platform) {
+  let resolved = pathImplFor(platform).resolve(p).replace(/[\\/]+$/, "");
+  if (platform === "win32" || platform === "darwin") resolved = resolved.toLowerCase();
+  return resolved;
+}
+
+/** Pure, testable: is `dir` present among `pathEnv`'s entries, resolved and normalized? */
+function isDirOnPath(dir, pathEnv, platform) {
+  if (!dir) return true; // can't determine the target dir -- don't false-positive a warning
+  const target = normalize(dir, platform);
+  const delimiter = platform === "win32" ? ";" : ":";
+  const entries = (pathEnv || "").split(delimiter).filter(Boolean);
+  return entries.some((entry) => normalize(entry, platform) === target);
+}
+
+function printWarning(message) {
+  // npm doesn't share stdio with lifecycle scripts by default -- a plain stderr write here is
+  // silently swallowed for a normal `npm install -g`. Writing straight to the controlling terminal
+  // bypasses that. Falls back to stderr (visible with --foreground-scripts, or if something else
+  // in the chain does share stdio) when there's no TTY to open -- CI, piped/non-interactive installs.
+  try {
+    const ttyPath = process.platform === "win32" ? "\\\\.\\CON" : "/dev/tty";
+    const fd = fs.openSync(ttyPath, "w");
+    try {
+      fs.writeSync(fd, message);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    try {
+      process.stderr.write(message);
+    } catch {
+      // Truly nothing we can do -- advisory only, never throw from here.
+    }
+  }
+}
+
+function main() {
+  try {
+    if (process.env.npm_config_global !== "true") return; // local/dependency install, or npx -- not our concern
+
+    const bin = globalBinDir(process.env.npm_config_prefix, process.platform);
+    if (isDirOnPath(bin, process.env.PATH, process.platform)) return;
+
+    printWarning(
+      [
+        "",
+        '⚠ srclawyer installed, but the "srclawyer" command isn’t on your PATH yet.',
+        "  This is often caused by tools like conda (auto_activate_base) rearranging PATH ahead of",
+        "  npm's global bin directory. Try opening a new terminal window first.",
+        "  If that doesn't fix it, see the Troubleshooting section in the README:",
+        "  https://github.com/SrcLawyer/srclawyer#troubleshooting-command-not-found",
+        "",
+      ].join("\n")
+    );
+  } catch {
+    // Advisory only -- never let this check itself break an install.
+  }
+}
+
+main();
+
+module.exports = { isDirOnPath, globalBinDir, normalize };