@facetlayer/docs-tool 0.1.0 → 0.2.0

package/dist/browseGlobalNpmInstall.d.ts

@@ -0,0 +1,15 @@
+export interface GlobalLibraryLocation {
+    libraryPath: string;
+    libraryName: string;
+}
+/**
+ * Get the global npm prefix directory.
+ * Returns null if it cannot be determined.
+ */
+export declare function getGlobalNpmPrefix(): Promise<string | null>;
+/**
+ * Find a library in the global npm installation directory.
+ * This is where `npm install -g` puts packages.
+ */
+export declare function findInGlobalNpmInstall(libraryName: string): Promise<GlobalLibraryLocation | null>;
+//# sourceMappingURL=browseGlobalNpmInstall.d.ts.map

package/dist/browseGlobalNpmInstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browseGlobalNpmInstall.d.ts","sourceRoot":"","sources":["../src/browseGlobalNpmInstall.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;CACrB;AAOD;;;GAGG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiBjE;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAoCvG"}

package/dist/browseNpmLibrary.d.ts

@@ -11,6 +11,10 @@ export interface NpmLibraryDocs {
     hasReadme: boolean;
     hasDocsFolder: boolean;
 }
+/**
+ * Check if a package exists at the given path with a package.json
+ */
+export declare function packageExistsAt(packagePath: string): boolean;
 /**
  * Find a library by name in node_modules directories.
  */

package/dist/browseNpmLibrary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browseNpmLibrary.d.ts","sourceRoot":"","sources":["../src/browseNpmLibrary.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;CACxB;AAuGD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAiCvG;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CASjD;AA6GD;;GAEG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAiC3H;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CA+BvF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQ/H"}
+{"version":3,"file":"browseNpmLibrary.d.ts","sourceRoot":"","sources":["../src/browseNpmLibrary.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAG5C,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAE5D;AAsGD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAiCvG;AAED;;GAEG;AACH,wBAAgB,wBAAwB,IAAI,MAAM,CASjD;AA6GD;;GAEG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CA0C3H;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CA+BvF;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAQ/H"}

package/dist/cli.js

@@ -4,12 +4,12 @@
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 import { readFileSync as readFileSync3 } from "fs";
-import { join as join4, dirname as dirname2 } from "path";
+import { join as join5, dirname as dirname2 } from "path";
 import { fileURLToPath } from "url";
 
 // src/index.ts
 import { readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
-import { join as join3, basename, relative } from "path";
+import { join as join4, basename, relative } from "path";
 
 // src/browseLocalLibrary.ts
 import { resolve, join } from "path";
@@ -34,24 +34,83 @@ function browseLocalLibrary(targetPath) {
 }
 
 // src/browseNpmLibrary.ts
-import { readFileSync, readdirSync, existsSync as existsSync2, mkdirSync, writeFileSync } from "fs";
-import { join as join2, dirname } from "path";
+import { readFileSync, readdirSync, existsSync as existsSync3, mkdirSync, writeFileSync } from "fs";
+import { join as join3, dirname } from "path";
 import { homedir } from "os";
+import { runShellCommand as runShellCommand2 } from "@facetlayer/subprocess-wrapper";
+
+// src/browseGlobalNpmInstall.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
 import { runShellCommand } from "@facetlayer/subprocess-wrapper";
+var cachedGlobalPrefix = void 0;
+async function getGlobalNpmPrefix() {
+  var _a;
+  if (cachedGlobalPrefix !== void 0) {
+    return cachedGlobalPrefix;
+  }
+  try {
+    const result = await runShellCommand("npm", ["prefix", "-g"]);
+    if (result.failed() || !result.stdout) {
+      cachedGlobalPrefix = null;
+      return null;
+    }
+    cachedGlobalPrefix = ((_a = result.stdout[0]) == null ? void 0 : _a.trim()) || null;
+    return cachedGlobalPrefix;
+  } catch {
+    cachedGlobalPrefix = null;
+    return null;
+  }
+}
+async function findInGlobalNpmInstall(libraryName) {
+  const globalPrefix = await getGlobalNpmPrefix();
+  if (!globalPrefix) {
+    return null;
+  }
+  const globalNodeModules = join2(globalPrefix, "lib", "node_modules");
+  if (!existsSync2(globalNodeModules)) {
+    return null;
+  }
+  if (libraryName.startsWith("@")) {
+    const [scope, pkgName] = libraryName.split("/");
+    if (pkgName) {
+      const fullPath2 = join2(globalNodeModules, scope, pkgName);
+      if (packageExistsAt(fullPath2)) {
+        return {
+          libraryPath: fullPath2,
+          libraryName
+        };
+      }
+    }
+    return null;
+  }
+  const fullPath = join2(globalNodeModules, libraryName);
+  if (packageExistsAt(fullPath)) {
+    return {
+      libraryPath: fullPath,
+      libraryName
+    };
+  }
+  return null;
+}
+
+// src/browseNpmLibrary.ts
+function packageExistsAt(packagePath) {
+  return existsSync3(packagePath) && existsSync3(join3(packagePath, "package.json"));
+}
 function findExactMatch(nodeModulesPath, libraryName) {
   if (libraryName.startsWith("@")) {
     const [scope, pkgName] = libraryName.split("/");
-    const scopePath = join2(nodeModulesPath, scope);
-    if (pkgName && existsSync2(scopePath)) {
-      const fullPath2 = join2(scopePath, pkgName);
-      if (existsSync2(fullPath2) && existsSync2(join2(fullPath2, "package.json"))) {
+    if (pkgName) {
+      const fullPath2 = join3(nodeModulesPath, scope, pkgName);
+      if (packageExistsAt(fullPath2)) {
         return fullPath2;
       }
     }
     return null;
   }
-  const fullPath = join2(nodeModulesPath, libraryName);
-  if (existsSync2(fullPath) && existsSync2(join2(fullPath, "package.json"))) {
+  const fullPath = join3(nodeModulesPath, libraryName);
+  if (packageExistsAt(fullPath)) {
     return fullPath;
   }
   return null;
@@ -59,21 +118,21 @@ function findExactMatch(nodeModulesPath, libraryName) {
 function findPartialMatches(nodeModulesPath, partialName) {
   const matches = [];
   const lowerPartial = partialName.toLowerCase();
-  if (!existsSync2(nodeModulesPath)) {
+  if (!existsSync3(nodeModulesPath)) {
     return matches;
   }
   const entries = readdirSync(nodeModulesPath, { withFileTypes: true });
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     if (entry.name.startsWith("@")) {
-      const scopePath = join2(nodeModulesPath, entry.name);
+      const scopePath = join3(nodeModulesPath, entry.name);
       const scopedEntries = readdirSync(scopePath, { withFileTypes: true });
       for (const scopedEntry of scopedEntries) {
         if (!scopedEntry.isDirectory()) continue;
         const fullName = `${entry.name}/${scopedEntry.name}`;
         if (fullName.toLowerCase().includes(lowerPartial)) {
-          const fullPath = join2(scopePath, scopedEntry.name);
-          if (existsSync2(join2(fullPath, "package.json"))) {
+          const fullPath = join3(scopePath, scopedEntry.name);
+          if (existsSync3(join3(fullPath, "package.json"))) {
             matches.push({
               libraryPath: fullPath,
               libraryName: fullName,
@@ -84,8 +143,8 @@ function findPartialMatches(nodeModulesPath, partialName) {
       }
     } else {
       if (entry.name.toLowerCase().includes(lowerPartial)) {
-        const fullPath = join2(nodeModulesPath, entry.name);
-        if (existsSync2(join2(fullPath, "package.json"))) {
+        const fullPath = join3(nodeModulesPath, entry.name);
+        if (existsSync3(join3(fullPath, "package.json"))) {
           matches.push({
             libraryPath: fullPath,
             libraryName: entry.name,
@@ -101,8 +160,8 @@ function getNodeModulesPaths(startDir) {
   const paths = [];
   let currentDir = startDir;
   while (true) {
-    const nodeModulesPath = join2(currentDir, "node_modules");
-    if (existsSync2(nodeModulesPath)) {
+    const nodeModulesPath = join3(currentDir, "node_modules");
+    if (existsSync3(nodeModulesPath)) {
       paths.push(nodeModulesPath);
     }
     const parentDir = dirname(currentDir);
@@ -143,16 +202,16 @@ function findLibraryInNodeModules(libraryName, startDir) {
   return null;
 }
 function getInstallationDirectory() {
-  const stateDir = join2(homedir(), ".cache", "docs-tool");
-  const installDir = join2(stateDir, "installed-packages");
-  if (!existsSync2(installDir)) {
+  const stateDir = join3(homedir(), ".cache", "docs-tool");
+  const installDir = join3(stateDir, "installed-packages");
+  if (!existsSync3(installDir)) {
     mkdirSync(installDir, { recursive: true });
   }
   return installDir;
 }
 function ensureInstallDirInitialized(installDir) {
-  const packageJsonPath = join2(installDir, "package.json");
-  if (!existsSync2(packageJsonPath)) {
+  const packageJsonPath = join3(installDir, "package.json");
+  if (!existsSync3(packageJsonPath)) {
     const packageJson2 = {
       name: "docs-tool-installed-packages",
       version: "1.0.0",
@@ -163,8 +222,8 @@ function ensureInstallDirInitialized(installDir) {
   }
 }
 function findInInstallDir(installDir, libraryName) {
-  const nodeModulesPath = join2(installDir, "node_modules");
-  if (!existsSync2(nodeModulesPath)) {
+  const nodeModulesPath = join3(installDir, "node_modules");
+  if (!existsSync3(nodeModulesPath)) {
     return null;
   }
   const exactPath = findExactMatch(nodeModulesPath, libraryName);
@@ -184,7 +243,7 @@ function findInInstallDir(installDir, libraryName) {
 async function getLatestVersion(libraryName) {
   var _a;
   try {
-    const result = await runShellCommand("npm", ["view", libraryName, "version"]);
+    const result = await runShellCommand2("npm", ["view", libraryName, "version"]);
     if (result.failed() || !result.stdout) {
       return null;
     }
@@ -195,7 +254,7 @@ async function getLatestVersion(libraryName) {
 }
 function getInstalledVersion(libraryPath) {
   try {
-    const packageJsonPath = join2(libraryPath, "package.json");
+    const packageJsonPath = join3(libraryPath, "package.json");
     const packageJson2 = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
     return packageJson2.version || null;
   } catch {
@@ -205,7 +264,7 @@ function getInstalledVersion(libraryPath) {
 async function installLibrary(installDir, libraryName) {
   ensureInstallDirInitialized(installDir);
   console.log(`Installing ${libraryName}...`);
-  const result = await runShellCommand("npm", ["install", libraryName, "--ignore-scripts"], {
+  const result = await runShellCommand2("npm", ["install", libraryName, "--ignore-scripts"], {
     cwd: installDir
   });
   if (result.failed()) {
@@ -215,7 +274,7 @@ async function installLibrary(installDir, libraryName) {
 }
 async function updateLibrary(installDir, libraryName) {
   console.log(`Updating ${libraryName} to latest version...`);
-  const result = await runShellCommand("npm", ["update", libraryName, "--ignore-scripts"], {
+  const result = await runShellCommand2("npm", ["update", libraryName, "--ignore-scripts"], {
     cwd: installDir
   });
   if (result.failed()) {
@@ -229,6 +288,13 @@ async function findLibrary(libraryName, options) {
   if (localResult) {
     return localResult;
   }
+  const globalResult = await findInGlobalNpmInstall(libraryName);
+  if (globalResult) {
+    return {
+      ...globalResult,
+      matchType: "exact"
+    };
+  }
   if (options == null ? void 0 : options.skipInstall) {
     return null;
   }
@@ -250,10 +316,10 @@ async function findLibrary(libraryName, options) {
 function getLibraryDocs(libraryPath, libraryName) {
   const dirs = [];
   const files = [];
-  const readmePath = join2(libraryPath, "README.md");
-  const docsPath = join2(libraryPath, "docs");
-  const hasReadme = existsSync2(readmePath);
-  const hasDocsFolder = existsSync2(docsPath);
+  const readmePath = join3(libraryPath, "README.md");
+  const docsPath = join3(libraryPath, "docs");
+  const hasReadme = existsSync3(readmePath);
+  const hasDocsFolder = existsSync3(docsPath);
   if (hasReadme) {
     files.push(readmePath);
   }
@@ -314,7 +380,7 @@ var DocFilesHelper = class {
         const files = readdirSync2(dir);
         for (const file of files) {
           if (!file.endsWith(".md")) continue;
-          this.fileMap.set(file, join3(dir, file));
+          this.fileMap.set(file, join4(dir, file));
         }
       }
     }
@@ -472,7 +538,7 @@ function parseTarget(target) {
 var __filename = fileURLToPath(import.meta.url);
 var __dirname = dirname2(__filename);
 var packageJson = JSON.parse(
-  readFileSync3(join4(__dirname, "../package.json"), "utf-8")
+  readFileSync3(join5(__dirname, "../package.json"), "utf-8")
 );
 async function main() {
   await yargs(hideBin(process.argv)).command(

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/index.ts
 import { readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
-import { join as join3, basename, relative } from "path";
+import { join as join4, basename, relative } from "path";
 
 // src/browseLocalLibrary.ts
 import { resolve, join } from "path";
@@ -25,24 +25,83 @@ function browseLocalLibrary(targetPath) {
 }
 
 // src/browseNpmLibrary.ts
-import { readFileSync, readdirSync, existsSync as existsSync2, mkdirSync, writeFileSync } from "fs";
-import { join as join2, dirname } from "path";
+import { readFileSync, readdirSync, existsSync as existsSync3, mkdirSync, writeFileSync } from "fs";
+import { join as join3, dirname } from "path";
 import { homedir } from "os";
+import { runShellCommand as runShellCommand2 } from "@facetlayer/subprocess-wrapper";
+
+// src/browseGlobalNpmInstall.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
 import { runShellCommand } from "@facetlayer/subprocess-wrapper";
+var cachedGlobalPrefix = void 0;
+async function getGlobalNpmPrefix() {
+  var _a;
+  if (cachedGlobalPrefix !== void 0) {
+    return cachedGlobalPrefix;
+  }
+  try {
+    const result = await runShellCommand("npm", ["prefix", "-g"]);
+    if (result.failed() || !result.stdout) {
+      cachedGlobalPrefix = null;
+      return null;
+    }
+    cachedGlobalPrefix = ((_a = result.stdout[0]) == null ? void 0 : _a.trim()) || null;
+    return cachedGlobalPrefix;
+  } catch {
+    cachedGlobalPrefix = null;
+    return null;
+  }
+}
+async function findInGlobalNpmInstall(libraryName) {
+  const globalPrefix = await getGlobalNpmPrefix();
+  if (!globalPrefix) {
+    return null;
+  }
+  const globalNodeModules = join2(globalPrefix, "lib", "node_modules");
+  if (!existsSync2(globalNodeModules)) {
+    return null;
+  }
+  if (libraryName.startsWith("@")) {
+    const [scope, pkgName] = libraryName.split("/");
+    if (pkgName) {
+      const fullPath2 = join2(globalNodeModules, scope, pkgName);
+      if (packageExistsAt(fullPath2)) {
+        return {
+          libraryPath: fullPath2,
+          libraryName
+        };
+      }
+    }
+    return null;
+  }
+  const fullPath = join2(globalNodeModules, libraryName);
+  if (packageExistsAt(fullPath)) {
+    return {
+      libraryPath: fullPath,
+      libraryName
+    };
+  }
+  return null;
+}
+
+// src/browseNpmLibrary.ts
+function packageExistsAt(packagePath) {
+  return existsSync3(packagePath) && existsSync3(join3(packagePath, "package.json"));
+}
 function findExactMatch(nodeModulesPath, libraryName) {
   if (libraryName.startsWith("@")) {
     const [scope, pkgName] = libraryName.split("/");
-    const scopePath = join2(nodeModulesPath, scope);
-    if (pkgName && existsSync2(scopePath)) {
-      const fullPath2 = join2(scopePath, pkgName);
-      if (existsSync2(fullPath2) && existsSync2(join2(fullPath2, "package.json"))) {
+    if (pkgName) {
+      const fullPath2 = join3(nodeModulesPath, scope, pkgName);
+      if (packageExistsAt(fullPath2)) {
         return fullPath2;
       }
     }
     return null;
   }
-  const fullPath = join2(nodeModulesPath, libraryName);
-  if (existsSync2(fullPath) && existsSync2(join2(fullPath, "package.json"))) {
+  const fullPath = join3(nodeModulesPath, libraryName);
+  if (packageExistsAt(fullPath)) {
     return fullPath;
   }
   return null;
@@ -50,21 +109,21 @@ function findExactMatch(nodeModulesPath, libraryName) {
 function findPartialMatches(nodeModulesPath, partialName) {
   const matches = [];
   const lowerPartial = partialName.toLowerCase();
-  if (!existsSync2(nodeModulesPath)) {
+  if (!existsSync3(nodeModulesPath)) {
     return matches;
   }
   const entries = readdirSync(nodeModulesPath, { withFileTypes: true });
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     if (entry.name.startsWith("@")) {
-      const scopePath = join2(nodeModulesPath, entry.name);
+      const scopePath = join3(nodeModulesPath, entry.name);
       const scopedEntries = readdirSync(scopePath, { withFileTypes: true });
       for (const scopedEntry of scopedEntries) {
         if (!scopedEntry.isDirectory()) continue;
         const fullName = `${entry.name}/${scopedEntry.name}`;
         if (fullName.toLowerCase().includes(lowerPartial)) {
-          const fullPath = join2(scopePath, scopedEntry.name);
-          if (existsSync2(join2(fullPath, "package.json"))) {
+          const fullPath = join3(scopePath, scopedEntry.name);
+          if (existsSync3(join3(fullPath, "package.json"))) {
             matches.push({
               libraryPath: fullPath,
               libraryName: fullName,
@@ -75,8 +134,8 @@ function findPartialMatches(nodeModulesPath, partialName) {
       }
     } else {
       if (entry.name.toLowerCase().includes(lowerPartial)) {
-        const fullPath = join2(nodeModulesPath, entry.name);
-        if (existsSync2(join2(fullPath, "package.json"))) {
+        const fullPath = join3(nodeModulesPath, entry.name);
+        if (existsSync3(join3(fullPath, "package.json"))) {
           matches.push({
             libraryPath: fullPath,
             libraryName: entry.name,
@@ -92,8 +151,8 @@ function getNodeModulesPaths(startDir) {
   const paths = [];
   let currentDir = startDir;
   while (true) {
-    const nodeModulesPath = join2(currentDir, "node_modules");
-    if (existsSync2(nodeModulesPath)) {
+    const nodeModulesPath = join3(currentDir, "node_modules");
+    if (existsSync3(nodeModulesPath)) {
       paths.push(nodeModulesPath);
     }
     const parentDir = dirname(currentDir);
@@ -134,16 +193,16 @@ function findLibraryInNodeModules(libraryName, startDir) {
   return null;
 }
 function getInstallationDirectory() {
-  const stateDir = join2(homedir(), ".cache", "docs-tool");
-  const installDir = join2(stateDir, "installed-packages");
-  if (!existsSync2(installDir)) {
+  const stateDir = join3(homedir(), ".cache", "docs-tool");
+  const installDir = join3(stateDir, "installed-packages");
+  if (!existsSync3(installDir)) {
     mkdirSync(installDir, { recursive: true });
   }
   return installDir;
 }
 function ensureInstallDirInitialized(installDir) {
-  const packageJsonPath = join2(installDir, "package.json");
-  if (!existsSync2(packageJsonPath)) {
+  const packageJsonPath = join3(installDir, "package.json");
+  if (!existsSync3(packageJsonPath)) {
     const packageJson = {
       name: "docs-tool-installed-packages",
       version: "1.0.0",
@@ -154,8 +213,8 @@ function ensureInstallDirInitialized(installDir) {
   }
 }
 function findInInstallDir(installDir, libraryName) {
-  const nodeModulesPath = join2(installDir, "node_modules");
-  if (!existsSync2(nodeModulesPath)) {
+  const nodeModulesPath = join3(installDir, "node_modules");
+  if (!existsSync3(nodeModulesPath)) {
     return null;
   }
   const exactPath = findExactMatch(nodeModulesPath, libraryName);
@@ -175,7 +234,7 @@ function findInInstallDir(installDir, libraryName) {
 async function getLatestVersion(libraryName) {
   var _a;
   try {
-    const result = await runShellCommand("npm", ["view", libraryName, "version"]);
+    const result = await runShellCommand2("npm", ["view", libraryName, "version"]);
     if (result.failed() || !result.stdout) {
       return null;
     }
@@ -186,7 +245,7 @@ async function getLatestVersion(libraryName) {
 }
 function getInstalledVersion(libraryPath) {
   try {
-    const packageJsonPath = join2(libraryPath, "package.json");
+    const packageJsonPath = join3(libraryPath, "package.json");
     const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
     return packageJson.version || null;
   } catch {
@@ -196,7 +255,7 @@ function getInstalledVersion(libraryPath) {
 async function installLibrary(installDir, libraryName) {
   ensureInstallDirInitialized(installDir);
   console.log(`Installing ${libraryName}...`);
-  const result = await runShellCommand("npm", ["install", libraryName, "--ignore-scripts"], {
+  const result = await runShellCommand2("npm", ["install", libraryName, "--ignore-scripts"], {
     cwd: installDir
   });
   if (result.failed()) {
@@ -206,7 +265,7 @@ async function installLibrary(installDir, libraryName) {
 }
 async function updateLibrary(installDir, libraryName) {
   console.log(`Updating ${libraryName} to latest version...`);
-  const result = await runShellCommand("npm", ["update", libraryName, "--ignore-scripts"], {
+  const result = await runShellCommand2("npm", ["update", libraryName, "--ignore-scripts"], {
     cwd: installDir
   });
   if (result.failed()) {
@@ -220,6 +279,13 @@ async function findLibrary(libraryName, options) {
   if (localResult) {
     return localResult;
   }
+  const globalResult = await findInGlobalNpmInstall(libraryName);
+  if (globalResult) {
+    return {
+      ...globalResult,
+      matchType: "exact"
+    };
+  }
   if (options == null ? void 0 : options.skipInstall) {
     return null;
   }
@@ -241,10 +307,10 @@ async function findLibrary(libraryName, options) {
 function getLibraryDocs(libraryPath, libraryName) {
   const dirs = [];
   const files = [];
-  const readmePath = join2(libraryPath, "README.md");
-  const docsPath = join2(libraryPath, "docs");
-  const hasReadme = existsSync2(readmePath);
-  const hasDocsFolder = existsSync2(docsPath);
+  const readmePath = join3(libraryPath, "README.md");
+  const docsPath = join3(libraryPath, "docs");
+  const hasReadme = existsSync3(readmePath);
+  const hasDocsFolder = existsSync3(docsPath);
   if (hasReadme) {
     files.push(readmePath);
   }
@@ -305,7 +371,7 @@ var DocFilesHelper = class {
         const files = readdirSync2(dir);
         for (const file of files) {
           if (!file.endsWith(".md")) continue;
-          this.fileMap.set(file, join3(dir, file));
+          this.fileMap.set(file, join4(dir, file));
         }
       }
     }

package/docs/ClaudeMdSetup.md

@@ -0,0 +1,27 @@
+# CLAUDE.md Setup
+
+Add the following to your project's `CLAUDE.md` file to enable AI assistants to use the `docs` tool for looking up NPM library documentation.
+
+## Recommended Section
+
+```markdown
+### docs
+
+Generic CLI tool to fetch documentation for a target NPM library. This will
+search local node_modules first and will search NPM if necessary.
+
+Syntax:
+
+    docs list <library-name>          # List the documentation files for <library-name>
+    docs show <library-name> <file>   # Show a documentation file
+
+Example:
+
+    docs list yargs
+    docs show yargs README.md
+```
+
+## Notes
+
+- The `docs` tool must be installed globally (`npm install -g @facetlayer/docs-tool`)
+- Place this section under a heading like `## Helpful development tools` or similar

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@facetlayer/docs-tool",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Library and CLI tool for browsing docs in NPM packages",
   "type": "module",
   "main": "dist/index.js",
@@ -12,7 +12,8 @@
     "build": "node build.mts build",
     "prepublishOnly": "node build.mts validate && node build.mts build",
     "typecheck": "tsc -p .",
-    "test": "vitest run --testTimeout=30000"
+    "test": "vitest run --testTimeout=30000",
+    "local:install": "npm run build && npm i -g ."
   },
   "keywords": [
     "doc",

package/src/browseGlobalNpmInstall.ts

@@ -0,0 +1,79 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { runShellCommand } from '@facetlayer/subprocess-wrapper';
+import { packageExistsAt } from './browseNpmLibrary.ts';
+
+export interface GlobalLibraryLocation {
+  libraryPath: string;
+  libraryName: string;
+}
+
+/**
+ * Cached global npm prefix to avoid repeated shell calls
+ */
+let cachedGlobalPrefix: string | null | undefined = undefined;
+
+/**
+ * Get the global npm prefix directory.
+ * Returns null if it cannot be determined.
+ */
+export async function getGlobalNpmPrefix(): Promise<string | null> {
+  if (cachedGlobalPrefix !== undefined) {
+    return cachedGlobalPrefix;
+  }
+
+  try {
+    const result = await runShellCommand('npm', ['prefix', '-g']);
+    if (result.failed() || !result.stdout) {
+      cachedGlobalPrefix = null;
+      return null;
+    }
+    cachedGlobalPrefix = result.stdout[0]?.trim() || null;
+    return cachedGlobalPrefix;
+  } catch {
+    cachedGlobalPrefix = null;
+    return null;
+  }
+}
+
+/**
+ * Find a library in the global npm installation directory.
+ * This is where `npm install -g` puts packages.
+ */
+export async function findInGlobalNpmInstall(libraryName: string): Promise<GlobalLibraryLocation | null> {
+  const globalPrefix = await getGlobalNpmPrefix();
+  if (!globalPrefix) {
+    return null;
+  }
+
+  const globalNodeModules = join(globalPrefix, 'lib', 'node_modules');
+  if (!existsSync(globalNodeModules)) {
+    return null;
+  }
+
+  // Handle scoped packages like @scope/package
+  if (libraryName.startsWith('@')) {
+    const [scope, pkgName] = libraryName.split('/');
+    if (pkgName) {
+      const fullPath = join(globalNodeModules, scope, pkgName);
+      if (packageExistsAt(fullPath)) {
+        return {
+          libraryPath: fullPath,
+          libraryName: libraryName,
+        };
+      }
+    }
+    return null;
+  }
+
+  // Regular package
+  const fullPath = join(globalNodeModules, libraryName);
+  if (packageExistsAt(fullPath)) {
+    return {
+      libraryPath: fullPath,
+      libraryName: libraryName,
+    };
+  }
+
+  return null;
+}

package/src/browseNpmLibrary.ts

@@ -3,6 +3,7 @@ import { join, dirname } from 'path';
 import { homedir } from 'os';
 import { runShellCommand } from '@facetlayer/subprocess-wrapper';
 import { DocFilesHelper } from './index.ts';
+import { findInGlobalNpmInstall } from './browseGlobalNpmInstall.ts';
 
 export interface LibraryLocation {
   libraryPath: string;
@@ -18,6 +19,13 @@ export interface NpmLibraryDocs {
   hasDocsFolder: boolean;
 }
 
+/**
+ * Check if a package exists at the given path with a package.json
+ */
+export function packageExistsAt(packagePath: string): boolean {
+  return existsSync(packagePath) && existsSync(join(packagePath, 'package.json'));
+}
+
 /**
  * Check if a directory contains a package that matches the given name exactly
  */
@@ -25,10 +33,9 @@ function findExactMatch(nodeModulesPath: string, libraryName: string): string |
   // Handle scoped packages like @scope/package
   if (libraryName.startsWith('@')) {
     const [scope, pkgName] = libraryName.split('/');
-    const scopePath = join(nodeModulesPath, scope);
-    if (pkgName && existsSync(scopePath)) {
-      const fullPath = join(scopePath, pkgName);
-      if (existsSync(fullPath) && existsSync(join(fullPath, 'package.json'))) {
+    if (pkgName) {
+      const fullPath = join(nodeModulesPath, scope, pkgName);
+      if (packageExistsAt(fullPath)) {
         return fullPath;
       }
     }
@@ -37,7 +44,7 @@ function findExactMatch(nodeModulesPath: string, libraryName: string): string |
 
   // Regular package
   const fullPath = join(nodeModulesPath, libraryName);
-  if (existsSync(fullPath) && existsSync(join(fullPath, 'package.json'))) {
+  if (packageExistsAt(fullPath)) {
     return fullPath;
   }
   return null;
@@ -288,11 +295,20 @@ export async function findLibrary(libraryName: string, options?: { skipInstall?:
     return localResult;
   }
 
+  // Second, check global npm installation (where `npm install -g` puts packages)
+  const globalResult = await findInGlobalNpmInstall(libraryName);
+  if (globalResult) {
+    return {
+      ...globalResult,
+      matchType: 'exact',
+    };
+  }
+
   if (options?.skipInstall) {
     return null;
   }
 
-  // Check our installation directory
+  // Third, check our installation directory
   const installDir = getInstallationDirectory();
   let installedResult = findInInstallDir(installDir, libraryName);