@pkgseer/cli 0.1.2 → 0.1.3

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-2wbvwsc9.js";
+} from "./shared/chunk-8dn0z2ja.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -202,7 +202,7 @@ var CliDocsListDocument = gql`
     packageName
     version
     pages {
-      slug
+      id
       title
       words
     }
@@ -465,6 +465,28 @@ var FetchPackageDocDocument = gql`
   }
 }
     `;
+var GetDocPageDocument = gql`
+    query GetDocPage($pageId: String!) {
+  getDocPage(pageId: $pageId) {
+    schemaVersion
+    page {
+      id
+      title
+      content
+      contentFormat
+      breadcrumbs
+      linkName
+      linkTargets
+      lastUpdatedAt
+      source {
+        url
+        label
+      }
+      baseUrl
+    }
+  }
+}
+    `;
 var SearchPackageDocsDocument = gql`
     query SearchPackageDocs($registry: Registry!, $packageName: String!, $keywords: [String!], $query: String, $includeSnippets: Boolean, $limit: Int, $version: String) {
   searchPackageDocs(
@@ -548,6 +570,7 @@ var PackageQualityDocumentString = print(PackageQualityDocument);
 var ComparePackagesDocumentString = print(ComparePackagesDocument);
 var ListPackageDocsDocumentString = print(ListPackageDocsDocument);
 var FetchPackageDocDocumentString = print(FetchPackageDocDocument);
+var GetDocPageDocumentString = print(GetDocPageDocument);
 var SearchPackageDocsDocumentString = print(SearchPackageDocsDocument);
 var SearchProjectDocsDocumentString = print(SearchProjectDocsDocument);
 function getSdk(client, withWrapper = defaultWrapper) {
@@ -603,6 +626,9 @@ function getSdk(client, withWrapper = defaultWrapper) {
     FetchPackageDoc(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(FetchPackageDocDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "FetchPackageDoc", "query", variables);
     },
+    GetDocPage(variables, requestHeaders) {
+      return withWrapper((wrappedRequestHeaders) => client.rawRequest(GetDocPageDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "GetDocPage", "query", variables);
+    },
     SearchPackageDocs(variables, requestHeaders) {
       return withWrapper((wrappedRequestHeaders) => client.rawRequest(SearchPackageDocsDocumentString, variables, { ...requestHeaders, ...wrappedRequestHeaders }), "SearchPackageDocs", "query", variables);
     },
@@ -1220,6 +1246,10 @@ class PkgseerServiceImpl {
     });
     return { data: result.data, errors: result.errors };
   }
+  async getDocPage(pageId) {
+    const result = await this.client.GetDocPage({ pageId });
+    return { data: result.data, errors: result.errors };
+  }
   async searchPackageDocs(registry, packageName, options) {
     const result = await this.client.SearchPackageDocs({
       registry,
@@ -1792,10 +1822,11 @@ function formatScore(score) {
 // src/commands/docs/get.ts
 function parsePackageRef(ref) {
   if (!ref.includes("/")) {
-    throw new Error(`Invalid format: "${ref}". Expected format:
-` + `  Full form: <registry>/<package>/<version>/<document>
-` + `  Short form: <package>/<document>
-` + `Examples: npm/express/4.18.2/readme or express/readme`);
+    return {
+      pageId: ref,
+      originalRef: ref,
+      isGlobalId: true
+    };
   }
   const parts = ref.split("/");
   if (parts.length < 2) {
@@ -1824,7 +1855,7 @@ function parsePackageRef(ref) {
   }
   return { packageName, pageId, originalRef: ref };
 }
-function formatDocPage(data, ref) {
+function formatDocPage(data, ref, verbose = false) {
   const lines = [];
   const page = data.page;
   if (!page) {
@@ -1832,6 +1863,49 @@ function formatDocPage(data, ref) {
   }
   lines.push(`[${ref}]`);
   lines.push("");
+  if (verbose) {
+    const metadata = [];
+    if (data.schemaVersion) {
+      metadata.push(`Schema Version: ${data.schemaVersion}`);
+    }
+    if (page.id) {
+      metadata.push(`Page ID: ${page.id}`);
+    }
+    if (page.contentFormat) {
+      metadata.push(`Format: ${page.contentFormat}`);
+    }
+    if (page.lastUpdatedAt) {
+      metadata.push(`Last Updated: ${page.lastUpdatedAt}`);
+    }
+    if (page.source) {
+      const sourceParts = [];
+      if (page.source.url) {
+        sourceParts.push(page.source.url);
+      }
+      if (page.source.label) {
+        sourceParts.push(`(${page.source.label})`);
+      }
+      if (sourceParts.length > 0) {
+        metadata.push(`Source: ${sourceParts.join(" ")}`);
+      }
+    }
+    if (page.baseUrl) {
+      metadata.push(`Base URL: ${page.baseUrl}`);
+    }
+    if (page.linkName) {
+      metadata.push(`Link Name: ${page.linkName}`);
+    }
+    if (page.linkTargets && page.linkTargets.length > 0) {
+      metadata.push(`Link Targets: ${page.linkTargets.join(", ")}`);
+    }
+    if (metadata.length > 0) {
+      lines.push("Metadata:");
+      for (const meta of metadata) {
+        lines.push(`  ${meta}`);
+      }
+      lines.push("");
+    }
+  }
   if (page.breadcrumbs && page.breadcrumbs.length > 0) {
     lines.push(page.breadcrumbs.join(" > "));
     lines.push("");
@@ -1861,13 +1935,66 @@ function extractErrorMessage(error) {
 }
 async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
   try {
+    if (ref.isGlobalId) {
+      const result2 = await pkgseerService.getDocPage(ref.pageId);
+      if (result2.errors && result2.errors.length > 0) {
+        const errorMsg = result2.errors.map((e) => {
+          if (typeof e === "object" && e !== null) {
+            const parts = [];
+            if ("message" in e) {
+              parts.push(String(e.message));
+            }
+            if ("extensions" in e && e.extensions) {
+              const ext = e.extensions;
+              if (typeof ext === "object" && "code" in ext) {
+                parts.push(`Code: ${ext.code}`);
+              }
+            }
+            return parts.length > 0 ? parts.join(" ") : JSON.stringify(e);
+          }
+          return String(e);
+        }).join("; ");
+        return { ref: ref.originalRef, result: null, error: errorMsg };
+      }
+      if (!result2.data.getDocPage) {
+        return {
+          ref: ref.originalRef,
+          result: null,
+          error: `Page not found: ${ref.pageId}`
+        };
+      }
+      return {
+        ref: ref.originalRef,
+        result: {
+          schemaVersion: result2.data.getDocPage?.schemaVersion ?? null,
+          page: result2.data.getDocPage?.page ?? null
+        }
+      };
+    }
     const registry = ref.registry ? toGraphQLRegistry(ref.registry) : defaultRegistry;
     const version2 = ref.version ?? defaultVersion;
+    if (!ref.packageName) {
+      return {
+        ref: ref.originalRef,
+        result: null,
+        error: `Package name required for reference: ${ref.originalRef}`
+      };
+    }
     const result = await pkgseerService.cliDocsGet(registry, ref.packageName, ref.pageId, version2);
     if (result.errors && result.errors.length > 0) {
       const errorMsg = result.errors.map((e) => {
-        if (typeof e === "object" && e !== null && "message" in e) {
-          return String(e.message);
+        if (typeof e === "object" && e !== null) {
+          const parts = [];
+          if ("message" in e) {
+            parts.push(String(e.message));
+          }
+          if ("extensions" in e && e.extensions) {
+            const ext = e.extensions;
+            if (typeof ext === "object" && "code" in ext) {
+              parts.push(`Code: ${ext.code}`);
+            }
+          }
+          return parts.length > 0 ? parts.join(" ") : JSON.stringify(e);
         }
         return String(e);
       }).join("; ");
@@ -1880,7 +2007,12 @@ async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
         error: `Page not found: ${ref.pageId} for ${ref.packageName}`
       };
     }
-    return { ref: ref.originalRef, result: result.data.fetchPackageDoc };
+    return {
+      ref: ref.originalRef,
+      result: result.data.fetchPackageDoc ? {
+        page: result.data.fetchPackageDoc.page ?? null
+      } : null
+    };
   } catch (error) {
     return {
       ref: ref.originalRef,
@@ -1891,7 +2023,7 @@ async function fetchPage(ref, defaultRegistry, defaultVersion, pkgseerService) {
 }
 async function docsGetAction(refs, options, deps) {
   if (refs.length === 0) {
-    outputError("At least one page reference required. Format: <package>/<slug>", options.json ?? false);
+    outputError("At least one page reference required. Format: <globally-unique-id> or <package>/<document>", options.json ?? false);
     return;
   }
   const { pkgseerService } = deps;
@@ -1929,17 +2061,24 @@ ${errorMessages}`, options.json ?? false);
       if (r.error) {
         return { ref: r.ref, error: r.error };
       }
+      if (options.verbose) {
+        return {
+          ref: r.ref,
+          ...r.result
+        };
+      }
       const page = r.result?.page;
       return {
         ref: r.ref,
         title: page?.title,
-        content: page?.content
+        content: page?.content,
+        breadcrumbs: page?.breadcrumbs
       };
     });
     output(jsonResults, true);
   } else {
     if (successes.length > 0) {
-      const pages = successes.filter((r) => r.result !== null).map((r) => formatDocPage(r.result, r.ref));
+      const pages = successes.filter((r) => r.result !== null).map((r) => formatDocPage(r.result, r.ref, options.verbose));
       console.log(pages.join(`
 
 ---
@@ -1956,29 +2095,28 @@ var GET_DESCRIPTION = `Fetch one or more documentation pages.
 Retrieves the full content of documentation pages including
 title, breadcrumbs, content (markdown), and source URL.
 
-Use 'pkgseer docs list' first to discover available page IDs, or
-use the output format from 'pkgseer docs search --refs-only'.
+Use 'pkgseer docs list' first to discover available page IDs.
 
-Format: <registry>/<package>/<version>/<document> (full form)
+Format: <globally-unique-id> (preferred)
+        or <registry>/<package>/<version>/<document> (full form)
         or <package>/<document> (short form, requires --registry/--pkg-version)
 
 Examples:
-  # Full form (from search output)
+  # Globally unique ID (from list output)
+  pkgseer docs get 24293-shared-plugins-during-build-2
+
+  # Full form
   pkgseer docs get npm/express/4.18.2/readme
   pkgseer docs get hex/postgrex/1.15.0/readme
 
-  # Short form (backward compatibility)
+  # Short form
   pkgseer docs get express/readme --registry npm --pkg-version 4.18.2
   pkgseer docs get postgrex/readme --registry hex
 
   # Multiple pages
-  pkgseer docs get npm/express/4.18.2/readme npm/express/4.18.2/writing-middleware
-
-  # Pipe from search (full form works seamlessly)
-  pkgseer docs search log --package express --refs-only | \\
-    xargs pkgseer docs get`;
+  pkgseer docs get 24293-shared-plugins-during-build-2 npm/express/4.18.2/readme`;
 function registerDocsGetCommand(program) {
-  program.command("get <refs...>").summary("Fetch documentation page(s)").description(GET_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (refs, options) => {
+  program.command("get <refs...>").summary("Fetch documentation page(s)").description(GET_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").option("--verbose", "Include metadata (ID, format, source, links, etc.)").action(async (refs, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await docsGetAction(refs, options, deps);
@@ -1998,11 +2136,11 @@ function formatDocsList(docs) {
   lines.push(`Found ${docs.pages.length} pages:`);
   lines.push("");
   for (const page of docs.pages) {
-    if (!page)
+    if (!page || !page.id)
       continue;
     const words = page.words ? ` (${formatNumber(page.words)} words)` : "";
     lines.push(`  ${page.title}${words}`);
-    lines.push(`    ID: ${page.slug}`);
+    lines.push(`    ID: ${page.id}`);
     lines.push("");
   }
   lines.push("Use 'pkgseer docs get <package>/<page-id>' to fetch a page.");
@@ -2020,10 +2158,14 @@ async function docsListAction(packageName, options, deps) {
   }
   if (options.json) {
     const pages = result.data.listPackageDocs.pages?.filter((p) => p) ?? [];
-    const slim = pages.map((p) => ({
-      slug: p.slug,
-      title: p.title
-    }));
+    const slim = pages.map((p) => {
+      if (!p || !p.id)
+        return null;
+      return {
+        id: p.id,
+        title: p.title
+      };
+    }).filter((p) => p !== null);
     output(slim, true);
   } else {
     console.log(formatDocsList(result.data.listPackageDocs));
@@ -2031,7 +2173,7 @@ async function docsListAction(packageName, options, deps) {
 }
 var LIST_DESCRIPTION = `List available documentation pages for a package.
 
-Shows all documentation pages with titles, page IDs (slugs),
+Shows all documentation pages with titles, globally unique page IDs,
 word counts, and descriptions. Use the page ID with 'docs get'
 to fetch the full content of a specific page.
 
@@ -3723,26 +3865,23 @@ function createComparePackagesTool(pkgseerService) {
 // src/tools/fetch-package-doc.ts
 import { z as z4 } from "zod";
 var argsSchema2 = {
-  registry: schemas.registry,
-  package_name: schemas.packageName.describe("Name of the package to fetch documentation for"),
-  page_id: z4.string().max(500).describe("Documentation page identifier (from list_package_docs)"),
-  version: schemas.version
+  page_id: z4.string().max(500).describe("Globally unique documentation page identifier (from list_package_docs)")
 };
 function createFetchPackageDocTool(pkgseerService) {
   return {
     name: "fetch_package_doc",
-    description: "Fetches the full content of a specific documentation page. Returns page title, content (markdown/HTML), breadcrumbs, and source attribution. Use list_package_docs first to get available page IDs.",
+    description: "Fetches the full content of a specific documentation page using a globally unique page ID. Returns complete page metadata including title, content (markdown/HTML), content format, breadcrumbs, source attribution, link metadata, base URL, and last updated timestamp. Use list_package_docs first to get available page IDs.",
     schema: argsSchema2,
-    handler: async ({ registry, package_name, page_id, version: version2 }, _extra) => {
+    handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
-        const result = await pkgseerService.fetchPackageDoc(toGraphQLRegistry2(registry), package_name, page_id, version2);
+        const result = await pkgseerService.getDocPage(page_id);
         const graphqlError = handleGraphQLErrors(result.errors);
         if (graphqlError)
           return graphqlError;
-        if (!result.data.fetchPackageDoc) {
-          return errorResult(`Documentation page not found: ${page_id} for ${package_name} in ${registry}`);
+        if (!result.data.getDocPage) {
+          return errorResult(`Documentation page not found: ${page_id}`);
         }
-        return textResult(JSON.stringify(result.data.fetchPackageDoc, null, 2));
+        return textResult(JSON.stringify(result.data.getDocPage, null, 2));
       });
     }
   };
@@ -3756,7 +3895,7 @@ var argsSchema3 = {
 function createListPackageDocsTool(pkgseerService) {
   return {
     name: "list_package_docs",
-    description: "Lists documentation pages for a package version. Returns page titles, slugs, and metadata. Use this to discover available documentation before fetching specific pages.",
+    description: "Lists documentation pages for a package version. Returns page titles, globally unique IDs, and metadata. Use this to discover available documentation before fetching specific pages.",
     schema: argsSchema3,
     handler: async ({ registry, package_name, version: version2 }, _extra) => {
       return withErrorHandling("list package documentation", async () => {

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   version
-} from "./shared/chunk-2wbvwsc9.js";
+} from "./shared/chunk-8dn0z2ja.js";
 export {
   version
 };

package/dist/shared/{chunk-2wbvwsc9.js → chunk-8dn0z2ja.js}

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.1.2";
+var version = "0.1.3";
 
 export { version };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pkgseer/cli",
   "description": "CLI companion for PkgSeer - package intelligence for developers and AI assistants",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "files": [
     "dist",