@pkgseer/cli 0.1.3 → 0.1.4

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   version
-} from "./shared/chunk-8dn0z2ja.js";
+} from "./shared/chunk-z505vakm.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -71,12 +71,13 @@ var CliPackageQualityDocument = gql`
 }
     `;
 var CliPackageDepsDocument = gql`
-    query CliPackageDeps($registry: Registry!, $name: String!, $version: String, $includeTransitive: Boolean) {
+    query CliPackageDeps($registry: Registry!, $name: String!, $version: String, $includeTransitive: Boolean, $maxDepth: Int) {
   packageDependencies(
     registry: $registry
     name: $name
     version: $version
     includeTransitive: $includeTransitive
+    maxDepth: $maxDepth
   ) {
     package {
       name
@@ -488,12 +489,12 @@ var GetDocPageDocument = gql`
 }
     `;
 var SearchPackageDocsDocument = gql`
-    query SearchPackageDocs($registry: Registry!, $packageName: String!, $keywords: [String!], $query: String, $includeSnippets: Boolean, $limit: Int, $version: String) {
+    query SearchPackageDocs($registry: Registry!, $packageName: String!, $keywords: [String!], $matchMode: MatchMode, $includeSnippets: Boolean, $limit: Int, $version: String) {
   searchPackageDocs(
     registry: $registry
     packageName: $packageName
     keywords: $keywords
-    query: $query
+    matchMode: $matchMode
     includeSnippets: $includeSnippets
     limit: $limit
     version: $version
@@ -502,7 +503,6 @@ var SearchPackageDocsDocument = gql`
     registry
     packageName
     version
-    query
     entries {
       id
       title
@@ -523,17 +523,16 @@ var SearchPackageDocsDocument = gql`
 }
     `;
 var SearchProjectDocsDocument = gql`
-    query SearchProjectDocs($project: String!, $keywords: [String!], $query: String, $includeSnippets: Boolean, $limit: Int) {
+    query SearchProjectDocs($project: String!, $keywords: [String!], $matchMode: MatchMode, $includeSnippets: Boolean, $limit: Int) {
   searchProjectDocs(
     project: $project
     keywords: $keywords
-    query: $query
+    matchMode: $matchMode
     includeSnippets: $includeSnippets
     limit: $limit
   ) {
     schemaVersion
     project
-    query
     entries {
       id
       title
@@ -1255,7 +1254,7 @@ class PkgseerServiceImpl {
       registry,
       packageName,
       keywords: options?.keywords,
-      query: options?.query,
+      matchMode: options?.matchMode,
       includeSnippets: options?.includeSnippets,
       limit: options?.limit,
       version: options?.version
@@ -1266,7 +1265,7 @@ class PkgseerServiceImpl {
     const result = await this.client.SearchProjectDocs({
       project,
       keywords: options?.keywords,
-      query: options?.query,
+      matchMode: options?.matchMode,
       includeSnippets: options?.includeSnippets,
       limit: options?.limit
     });
@@ -1292,12 +1291,13 @@ class PkgseerServiceImpl {
     });
     return { data: result.data, errors: result.errors };
   }
-  async cliPackageDeps(registry, name, version2, includeTransitive) {
+  async cliPackageDeps(registry, name, version2, includeTransitive, maxDepth) {
     const result = await this.client.CliPackageDeps({
       registry,
       name,
       version: version2,
-      includeTransitive
+      includeTransitive,
+      maxDepth
     });
     return { data: result.data, errors: result.errors };
   }
@@ -1724,10 +1724,26 @@ function outputError(message, json) {
   process.exit(1);
 }
 function handleErrors(errors, json) {
-  if (errors && errors.length > 0) {
-    const message = errors.map((e) => e.message).join(", ");
-    outputError(message, json);
-  }
+  if (!errors || errors.length === 0)
+    return;
+  const combined = errors.map((e) => e.message).filter(Boolean).join(", ");
+  const lower = combined.toLowerCase();
+  const isTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
+  const isNotFound = lower.includes("not found") || lower.includes("does not exist") || lower.includes("unknown");
+  const isAuth = lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("token") || lower.includes("authentication") || lower.includes("permission");
+  const isRateLimit = lower.includes("rate limit") || lower.includes("too many requests");
+  let hint = "";
+  if (isTimeout) {
+    hint = " Hint: lower the limit or narrow the scope, then retry.";
+  } else if (isNotFound) {
+    hint = " Hint: verify the name/registry and that the resource exists.";
+  } else if (isAuth) {
+    hint = " Hint: check login or token validity (pkgseer auth-status).";
+  } else if (isRateLimit) {
+    hint = " Hint: wait and retry, or reduce request frequency.";
+  }
+  const message = `${combined}${hint}`;
+  outputError(message, json);
 }
 function formatNumber(num) {
   if (num == null)
@@ -1805,6 +1821,19 @@ async function withCliErrorHandling(json, fn) {
       return;
     }
     const message = error instanceof Error ? error.message : "Unknown error";
+    const lower = message.toLowerCase();
+    if (lower.includes("-32001") || lower.includes("timeout")) {
+      outputError(`${message}. Hint: lower the limit or narrow the scope, then retry.`, json);
+      return;
+    }
+    if (lower.includes("unauthorized") || lower.includes("forbidden") || lower.includes("token") || lower.includes("authentication") || lower.includes("permission")) {
+      outputError(`${message}. Hint: check login or token validity.`, json);
+      return;
+    }
+    if (lower.includes("rate limit") || lower.includes("too many requests")) {
+      outputError(`${message}. Hint: wait and retry.`, json);
+      return;
+    }
     const colonMatch = message.match(/^([^:]+):/);
     const shortMessage = colonMatch?.[1] ?? message;
     outputError(shortMessage, json);
@@ -1855,7 +1884,7 @@ function parsePackageRef(ref) {
   }
   return { packageName, pageId, originalRef: ref };
 }
-function formatDocPage(data, ref, verbose = false) {
+function formatDocPage(data, ref, verbose = false, previewLines) {
   const lines = [];
   const page = data.page;
   if (!page) {
@@ -1913,9 +1942,22 @@ function formatDocPage(data, ref, verbose = false) {
   lines.push(`# ${page.title}`);
   lines.push("");
   if (page.content) {
-    lines.push(page.content);
+    const previewLimit = previewLines ?? 20;
+    if (previewLimit === 0) {
+      lines.push(page.content);
+    } else {
+      const contentLines = page.content.split(`
+`);
+      const preview = contentLines.slice(0, previewLimit).join(`
+`);
+      lines.push(preview);
+      if (contentLines.length > previewLimit) {
+        lines.push("");
+        lines.push("(Preview truncated; use --preview-lines 0 for full content.)");
+      }
+    }
   } else {
-    lines.push("(No content available)");
+    lines.push("(No content available. Verify the page ID or try another version.)");
   }
   return lines.join(`
 `);
@@ -2028,6 +2070,8 @@ async function docsGetAction(refs, options, deps) {
   }
   const { pkgseerService } = deps;
   const defaultRegistry = toGraphQLRegistry(options.registry);
+  const previewLines = options.previewLines != null ? Number.parseInt(options.previewLines, 10) : 20;
+  const resolvedPreview = Number.isNaN(previewLines) ? 20 : previewLines;
   const parsedRefs = [];
   for (const ref of refs) {
     try {
@@ -2078,7 +2122,7 @@ ${errorMessages}`, options.json ?? false);
     output(jsonResults, true);
   } else {
     if (successes.length > 0) {
-      const pages = successes.filter((r) => r.result !== null).map((r) => formatDocPage(r.result, r.ref, options.verbose));
+      const pages = successes.filter((r) => r.result !== null).map((r) => formatDocPage(r.result, r.ref, options.verbose, resolvedPreview));
       console.log(pages.join(`
 
 ---
@@ -2116,7 +2160,7 @@ Examples:
   # Multiple pages
   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").option("--verbose", "Include metadata (ID, format, source, links, etc.)").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.)").option("--preview-lines <n>", "Lines of content to show (0 for full content; default 20)").action(async (refs, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await docsGetAction(refs, options, deps);
@@ -2190,6 +2234,22 @@ function registerDocsListCommand(program) {
   });
 }
 // src/commands/docs/search.ts
+function summarizeSearchResults(results) {
+  const entries = results.entries ?? [];
+  const count = entries.length;
+  const totalMatches = entries.reduce((acc, e) => acc + (e?.matchCount ?? 0), 0);
+  const lines = [];
+  lines.push(`Results: ${count} page${count === 1 ? "" : "s"} | matches: ${totalMatches}`);
+  lines.push("");
+  for (const entry of entries.filter((e) => !!e)) {
+    lines.push(`- ${entry.title ?? entry.slug ?? "untitled"} (${entry.matchCount ?? 0} matches)`);
+  }
+  if (count === 0) {
+    lines.push("No matches. Try broader terms or fewer constraints.");
+  }
+  return lines.join(`
+`);
+}
 function buildDocRef(entry, searchResult) {
   if (!entry?.slug)
     return "";
@@ -2299,7 +2359,7 @@ function formatEntry(entry, searchResult, useColors) {
 function formatSearchResults(results, useColors) {
   const entries = results.entries ?? [];
   if (entries.length === 0) {
-    return "No matching documentation found.";
+    return "No matching documentation found. Try broader terms or fewer constraints.";
   }
   const formatted = entries.filter((e) => e != null).map((entry) => formatEntry(entry, results, useColors));
   return formatted.join(`
@@ -2343,25 +2403,24 @@ function slimSearchResults(results) {
 }
 async function docsSearchAction(queryArg, options, deps) {
   const { pkgseerService, config } = deps;
-  const searchQuery = queryArg || options.query;
-  const keywords = options.keywords;
-  if (!searchQuery && (!keywords || keywords.length === 0)) {
-    outputError("Search query required. Provide a query as argument or use --query/--keywords", options.json ?? false);
+  const providedTerms = Array.isArray(queryArg) ? queryArg : queryArg ? [queryArg] : [];
+  const terms = providedTerms.concat(options.terms ?? []);
+  if (!terms.length) {
+    outputError("Search terms required. Provide terms as argument or with --terms", options.json ?? false);
     return;
   }
   const contextBefore = options.context ? Number.parseInt(options.context, 10) : options.before ? Number.parseInt(options.before, 10) : 2;
   const contextAfter = options.context ? Number.parseInt(options.context, 10) : options.after ? Number.parseInt(options.after, 10) : 2;
   const maxMatches = options.maxMatches ? Number.parseInt(options.maxMatches, 10) : 5;
   const limit = options.limit ? Number.parseInt(options.limit, 10) : 25;
-  const matchMode = options.mode?.toUpperCase() || undefined;
+  const matchMode = options.match_mode?.toUpperCase() || options.mode?.toUpperCase() || undefined;
   const useColors = shouldUseColors(options.noColor);
   const project = options.project ?? config.project;
   const packageName = options.package;
   if (packageName) {
     const registry = toGraphQLRegistry(options.registry ?? "npm");
     const result = await pkgseerService.cliDocsSearch(registry, packageName, {
-      query: searchQuery,
-      keywords,
+      keywords: terms,
       matchMode,
       limit,
       version: options.pkgVersion,
@@ -2379,8 +2438,7 @@ async function docsSearchAction(queryArg, options, deps) {
   }
   if (project) {
     const result = await pkgseerService.cliProjectDocsSearch(project, {
-      query: searchQuery,
-      keywords,
+      keywords: terms,
       matchMode,
       limit,
       contextLinesBefore: contextBefore,
@@ -2401,12 +2459,15 @@ async function docsSearchAction(queryArg, options, deps) {
 ` + "  - Use --package <name> to search a specific package", options.json ?? false);
 }
 function outputResults(results, options, useColors) {
-  if (options.json) {
+  const format = options.json ? "json" : options.format ?? "human";
+  if (format === "json") {
     output(slimSearchResults(results), true);
   } else if (options.refsOnly) {
     console.log(formatRefsOnly(results));
   } else if (options.count) {
     console.log(formatCount(results));
+  } else if (format === "summary") {
+    console.log(summarizeSearchResults(results));
   } else {
     console.log(formatSearchResults(results, useColors));
   }
@@ -2426,11 +2487,11 @@ Examples:
   pkgseer docs search "error handling" --package express
   pkgseer docs search log --package express -C 3
 
-  # Multiple keywords (OR by default)
-  pkgseer docs search -k "middleware,routing" --package express
+  # Multiple terms (OR by default)
+  pkgseer docs search -t "middleware,routing" --package express
 
   # Strict matching (AND mode)
-  pkgseer docs search -k "error,middleware" --mode and --package express
+  pkgseer docs search -t "error,middleware" --match-mode all --package express
 
   # Output for piping
   pkgseer docs search log --package express --refs-only | \\
@@ -2439,14 +2500,14 @@ Examples:
   # Count matches
   pkgseer docs search error --package express --count`;
 function addSearchOptions(cmd) {
-  return cmd.option("-p, --package <name>", "Search specific package (overrides project)").option("-r, --registry <registry>", "Package registry (with --package)", "npm").option("-v, --pkg-version <version>", "Package version (with --package)").option("--project <name>", "Project name (overrides config)").option("-q, --query <query>", "Search query (alternative to argument)").option("-k, --keywords <words>", "Comma-separated keywords", (val) => val.split(",").map((s) => s.trim())).option("-l, --limit <n>", "Max results (default: 25)").option("-A, --after <n>", "Lines of context after match (default: 2)").option("-B, --before <n>", "Lines of context before match (default: 2)").option("-C, --context <n>", "Lines of context before and after match").option("--max-matches <n>", "Max matches per page (default: 5)").option("--mode <mode>", "Match mode: or (default), and").option("--refs-only", "Output only page references (for piping)").option("--count", "Output only match counts per page").option("--no-color", "Disable colored output").option("--json", "Output as JSON");
+  return cmd.option("-p, --package <name>", "Search specific package (overrides project)").option("-r, --registry <registry>", "Package registry (with --package)", "npm").option("-v, --pkg-version <version>", "Package version (with --package)").option("--project <name>", "Project name (overrides config)").option("-t, --terms <words>", "Comma-separated search terms", (val) => val.split(",").map((s) => s.trim())).option("-l, --limit <n>", "Max results (default: 25)").option("-A, --after <n>", "Lines of context after match (default: 2)").option("-B, --before <n>", "Lines of context before match (default: 2)").option("-C, --context <n>", "Lines of context before and after match").option("--max-matches <n>", "Max matches per page (default: 5)").option("--match-mode <mode>", "How to combine terms: any/or (default) or all/and").option("--refs-only", "Output only page references (for piping)").option("--count", "Output only match counts per page").option("--format <format>", "Output format: human|summary|json", "human").option("--no-color", "Disable colored output").option("--json", "Output as JSON");
 }
 function registerDocsSearchCommand(program) {
-  const cmd = program.command("search [query]").summary("Search documentation").description(SEARCH_DESCRIPTION);
-  addSearchOptions(cmd).action(async (query, options) => {
+  const cmd = program.command("search [terms...]").summary("Search documentation").description(SEARCH_DESCRIPTION);
+  addSearchOptions(cmd).action(async (terms, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
-      await docsSearchAction(query, options, deps);
+      await docsSearchAction(terms, options, deps);
     });
   });
 }
@@ -3811,9 +3872,28 @@ var schemas = {
   packageName: z2.string().max(255).describe("Name of the package"),
   version: z2.string().max(100).optional().describe("Specific version (defaults to latest)")
 };
+function buildHintedMessage(operation, message) {
+  const lower = message.toLowerCase();
+  const isTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
+  if (isTimeout) {
+    return `Failed to ${operation}: ${message}. ` + "Hint: try lowering the limit or narrowing the scope, then retry.";
+  }
+  return `Failed to ${operation}: ${message}`;
+}
 function handleGraphQLErrors(errors) {
   if (errors && errors.length > 0) {
-    return errorResult(`Error: ${errors.map((e) => e.message).join(", ")}`);
+    const messages = errors.map((e) => e.message).filter(Boolean);
+    const combined = messages.join(", ");
+    const lower = combined.toLowerCase();
+    const hasNotFound = lower.includes("not found") || lower.includes("does not exist");
+    const hasTimeout = lower.includes("-32001") || lower.includes("timeout") || lower.includes("timed out");
+    if (hasNotFound) {
+      return errorResult(`Error: ${combined}. Hint: verify the name/registry and that the resource exists.`);
+    }
+    if (hasTimeout) {
+      return errorResult(`Error: ${combined}. Hint: try lowering the limit or narrowing the scope, then retry.`);
+    }
+    return errorResult(`Error: ${combined}`);
   }
   return null;
 }
@@ -3822,7 +3902,7 @@ async function withErrorHandling(operation, fn) {
     return await fn();
   } catch (error2) {
     const message = error2 instanceof Error ? error2.message : "Unknown error";
-    return errorResult(`Failed to ${operation}: ${message}`);
+    return errorResult(buildHintedMessage(operation, message));
   }
 }
 function notFoundError(packageName, registry) {
@@ -3841,7 +3921,7 @@ var argsSchema = {
 function createComparePackagesTool(pkgseerService) {
   return {
     name: "compare_packages",
-    description: "Compares multiple packages across metadata, quality, and security dimensions",
+    description: 'Compares 2-10 packages across metadata, quality, and security. Example: [{"registry":"npm","name":"react","version":"18.2.0"},{"registry":"pypi","name":"requests"}].',
     schema: argsSchema,
     handler: async ({ packages }, _extra) => {
       return withErrorHandling("compare packages", async () => {
@@ -3870,7 +3950,7 @@ var argsSchema2 = {
 function createFetchPackageDocTool(pkgseerService) {
   return {
     name: "fetch_package_doc",
-    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.",
+    description: "Fetches the full content of a documentation page by globally unique page ID (from list_package_docs). Returns full metadata (title, content, format, breadcrumbs, source, base URL, last updated).",
     schema: argsSchema2,
     handler: async ({ page_id }, _extra) => {
       return withErrorHandling("fetch documentation page", async () => {
@@ -3920,10 +4000,82 @@ var argsSchema4 = {
   include_transitive: z5.boolean().optional().describe("Whether to include transitive dependency DAG"),
   max_depth: z5.number().int().min(1).max(10).optional().describe("Maximum depth for transitive traversal (1-10)")
 };
+function decodeDag(rawDag) {
+  if (!rawDag || typeof rawDag !== "object")
+    return;
+  const dag = rawDag;
+  const nodesSource = dag.n ?? dag.nodes;
+  const nodesRaw = nodesSource && typeof nodesSource === "object" && !Array.isArray(nodesSource) ? nodesSource : undefined;
+  const edgesSource = dag.e ?? dag.edges;
+  const edgesRaw = Array.isArray(edgesSource) ? edgesSource : undefined;
+  const nodes = nodesRaw ? Object.entries(nodesRaw).map(([id, value]) => {
+    const {
+      n: nameField,
+      v: versionField,
+      l: labelField,
+      ...rest
+    } = value ?? {};
+    return {
+      id,
+      name: nameField ?? rest.name,
+      version: versionField ?? rest.version,
+      label: labelField ?? rest.label,
+      ...rest
+    };
+  }) : [];
+  const edges = edgesRaw?.map((edge) => {
+    if (Array.isArray(edge) && edge.length >= 2) {
+      return { from: String(edge[0]), to: String(edge[1]) };
+    }
+    const edgeObj = edge ?? {};
+    return {
+      from: String(edgeObj.f ?? edgeObj.from ?? edgeObj.source ?? edgeObj.s ?? ""),
+      to: String(edgeObj.t ?? edgeObj.to ?? edgeObj.target ?? edgeObj.d ?? "")
+    };
+  }) ?? [];
+  return {
+    version: dag.v ?? dag.version,
+    nodes,
+    edges
+  };
+}
+function buildEdgeDepths(decodedDag, rootId) {
+  if (!decodedDag)
+    return;
+  const root = rootId ?? decodedDag.nodes[0]?.id;
+  if (!root)
+    return;
+  const depthMap = new Map([[root, 0]]);
+  const adjacency = new Map;
+  for (const edge of decodedDag.edges) {
+    if (!edge.from || !edge.to)
+      continue;
+    const list = adjacency.get(edge.from) ?? [];
+    list.push(edge.to);
+    adjacency.set(edge.from, list);
+  }
+  const queue = [root];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    const currentDepth = depthMap.get(current) ?? 0;
+    for (const next of adjacency.get(current) ?? []) {
+      if (!depthMap.has(next)) {
+        depthMap.set(next, currentDepth + 1);
+        queue.push(next);
+      }
+    }
+  }
+  return decodedDag.edges.map((edge) => ({
+    from: edge.from,
+    to: edge.to,
+    depthFrom: depthMap.get(edge.from),
+    depthTo: depthMap.get(edge.to)
+  }));
+}
 function createPackageDependenciesTool(pkgseerService) {
   return {
     name: "package_dependencies",
-    description: "Retrieves direct and transitive dependencies for a package version",
+    description: "Retrieves direct and transitive dependencies for a package version. Options: include_transitive (bool) and max_depth (1-10). Transitive output includes a DAG (`n/e/v` keys) decoded into readable nodes/edges with depth and counts; raw DAG is preserved alongside decoded form.",
     schema: argsSchema4,
     handler: async ({ registry, package_name, version: version2, include_transitive, max_depth }, _extra) => {
       return withErrorHandling("fetch package dependencies", async () => {
@@ -3934,7 +4086,29 @@ function createPackageDependenciesTool(pkgseerService) {
         if (!result.data.packageDependencies) {
           return notFoundError(package_name, registry);
         }
-        return textResult(JSON.stringify(result.data.packageDependencies, null, 2));
+        const deps = result.data.packageDependencies.dependencies;
+        const decodedDag = decodeDag(deps?.transitive?.dag);
+        const transitiveDag = deps?.transitive?.dag;
+        const edgesWithDepth = buildEdgeDepths(decodedDag, typeof transitiveDag?.root === "string" ? transitiveDag.root : undefined);
+        const output2 = {
+          summary: deps?.summary,
+          package: result.data.packageDependencies.package,
+          direct: deps?.direct,
+          transitive: deps?.transitive ? {
+            totalEdges: deps.transitive.totalEdges,
+            uniquePackagesCount: deps.transitive.uniquePackagesCount,
+            uniqueDependencies: deps.transitive.uniqueDependencies,
+            conflicts: deps.transitive.conflicts,
+            circularDependencies: deps.transitive.circularDependencies,
+            dag: {
+              decoded: decodedDag,
+              edgesWithDepth,
+              raw: deps.transitive.dag
+            }
+          } : undefined,
+          raw: result.data.packageDependencies
+        };
+        return textResult(JSON.stringify(output2, null, 2));
       });
     }
   };
@@ -4018,8 +4192,8 @@ import { z as z6 } from "zod";
 var argsSchema8 = {
   registry: schemas.registry,
   package_name: schemas.packageName.describe("Name of the package to search documentation for"),
-  keywords: z6.array(z6.string()).optional().describe("Keywords to search for; combined into a single query"),
-  query: z6.string().max(500).optional().describe("Freeform search query (alternative to keywords)"),
+  terms: z6.array(z6.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
+  match_mode: z6.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
   include_snippets: z6.boolean().optional().describe("Include content excerpts around matches"),
   limit: z6.number().int().min(1).max(100).optional().describe("Maximum number of results to return"),
   version: schemas.version
@@ -4027,25 +4201,28 @@ var argsSchema8 = {
 function createSearchPackageDocsTool(pkgseerService) {
   return {
     name: "search_package_docs",
-    description: "Searches package documentation with keyword or freeform query support. Returns ranked results with relevance scores. Use include_snippets=true to get content excerpts showing match context.",
+    description: "Searches package documentation using search terms and match modes (any/all). Returns ranked results with match context. Defaults to include_snippets=true.",
     schema: argsSchema8,
     handler: async ({
       registry,
       package_name,
-      keywords,
-      query,
+      terms,
+      match_mode,
       include_snippets,
       limit,
       version: version2
     }, _extra) => {
       return withErrorHandling("search package documentation", async () => {
-        if (!keywords?.length && !query) {
-          return errorResult("Either keywords or query must be provided for search");
+        const normalizedTerms = terms?.map((term) => term.trim()).filter((term) => term.length > 0) ?? [];
+        if (normalizedTerms.length === 0) {
+          return errorResult("Search terms are required to run documentation search.");
         }
+        const matchMode = match_mode === "all" || match_mode === "and" ? "AND" : match_mode === "any" || match_mode === "or" ? "OR" : undefined;
+        const includeSnippets = include_snippets ?? true;
         const result = await pkgseerService.searchPackageDocs(toGraphQLRegistry2(registry), package_name, {
-          keywords,
-          query,
-          includeSnippets: include_snippets,
+          keywords: normalizedTerms,
+          matchMode,
+          includeSnippets,
           limit,
           version: version2
         });
@@ -4055,6 +4232,9 @@ function createSearchPackageDocsTool(pkgseerService) {
         if (!result.data.searchPackageDocs) {
           return errorResult(`No documentation found for ${package_name} in ${registry}`);
         }
+        if ((result.data.searchPackageDocs.entries ?? []).length === 0 && normalizedTerms.length > 0) {
+          return errorResult(`No documentation matched: ${normalizedTerms.join(", ")}. ` + "Try fewer or broader terms, or reduce match constraints.");
+        }
         return textResult(JSON.stringify(result.data.searchPackageDocs, null, 2));
       });
     }
@@ -4064,8 +4244,8 @@ function createSearchPackageDocsTool(pkgseerService) {
 import { z as z7 } from "zod";
 var argsSchema9 = {
   project: z7.string().optional().describe("Project name to search. Optional if configured in pkgseer.yml; only needed to search a different project."),
-  keywords: z7.array(z7.string()).optional().describe("Keywords to search for; combined into a single query"),
-  query: z7.string().max(500).optional().describe("Freeform search query (alternative to keywords)"),
+  terms: z7.array(z7.string()).optional().describe("Search terms to match. Provide a few key words or phrases that should appear in results."),
+  match_mode: z7.enum(["any", "or", "all", "and"]).optional().describe('How to combine terms: "any" (OR) or "all" (AND).'),
   include_snippets: z7.boolean().optional().describe("Include content excerpts around matches"),
   limit: z7.number().int().min(1).max(100).optional().describe("Maximum number of results to return")
 };
@@ -4073,21 +4253,24 @@ function createSearchProjectDocsTool(deps) {
   const { pkgseerService, config } = deps;
   return {
     name: "search_project_docs",
-    description: "Searches documentation across all dependencies in a PkgSeer project. Returns ranked results from multiple packages. Uses project from pkgseer.yml config by default.",
+    description: "Searches documentation across all dependencies in a PkgSeer project using search terms and match modes (any/all). Returns ranked results from multiple packages. Uses project from pkgseer.yml config by default.",
     schema: argsSchema9,
-    handler: async ({ project, keywords, query, include_snippets, limit }, _extra) => {
+    handler: async ({ project, terms, match_mode, include_snippets, limit }, _extra) => {
       return withErrorHandling("search project documentation", async () => {
         const resolvedProject = project ?? config.project;
         if (!resolvedProject) {
           return errorResult("No project provided and none configured in pkgseer.yml. " + "Either pass project parameter or add project to your config.");
         }
-        if (!keywords?.length && !query) {
-          return errorResult("Either keywords or query must be provided for search");
+        const normalizedTerms = terms?.map((term) => term.trim()).filter((term) => term.length > 0) ?? [];
+        if (normalizedTerms.length === 0) {
+          return errorResult("Search terms are required to run documentation search.");
         }
+        const matchMode = match_mode === "all" || match_mode === "and" ? "AND" : match_mode === "any" || match_mode === "or" ? "OR" : undefined;
+        const includeSnippets = include_snippets ?? true;
         const result = await pkgseerService.searchProjectDocs(resolvedProject, {
-          keywords,
-          query,
-          includeSnippets: include_snippets,
+          keywords: normalizedTerms,
+          matchMode,
+          includeSnippets,
           limit
         });
         const graphqlError = handleGraphQLErrors(result.errors);
@@ -4096,6 +4279,9 @@ function createSearchProjectDocsTool(deps) {
         if (!result.data.searchProjectDocs) {
           return errorResult(`Project not found: ${resolvedProject}`);
         }
+        if ((result.data.searchProjectDocs.entries ?? []).length === 0 && normalizedTerms.length > 0) {
+          return errorResult(`No documentation matched: ${normalizedTerms.join(", ")}. ` + "Try fewer or broader terms, or reduce match constraints.");
+        }
         return textResult(JSON.stringify(result.data.searchProjectDocs, null, 2));
       });
     }
@@ -4313,7 +4499,7 @@ function registerPkgCompareCommand(program) {
   });
 }
 // src/commands/pkg/deps.ts
-function formatPackageDependencies(data) {
+function formatPackageDependencies(data, transitiveRequested) {
   const lines = [];
   const pkg = data.package;
   const deps = data.dependencies;
@@ -4341,32 +4527,52 @@ function formatPackageDependencies(data) {
   } else {
     lines.push("No direct dependencies.");
   }
+  if (!transitiveRequested) {
+    lines.push("");
+    lines.push("Tip: use --transitive for full dependency graph traversal.");
+  }
   return lines.join(`
 `);
 }
 async function pkgDepsAction(packageName, options, deps) {
   const { pkgseerService } = deps;
   const registry = toGraphQLRegistry(options.registry);
-  const result = await pkgseerService.cliPackageDeps(registry, packageName, options.pkgVersion, options.transitive);
+  const transitiveRequested = options.transitive ?? false;
+  const result = await pkgseerService.cliPackageDeps(registry, packageName, options.pkgVersion, options.transitive, options.maxDepth ? Number.parseInt(options.maxDepth, 10) : undefined);
   handleErrors(result.errors, options.json ?? false);
   if (!result.data.packageDependencies) {
     outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
     return;
   }
-  if (options.json) {
+  const format = options.json ? "json" : options.format ?? "human";
+  if (format === "json") {
     const data = result.data.packageDependencies;
-    const slim = {
+    output({
       package: `${data.package?.name}@${data.package?.version}`,
       directCount: data.dependencies?.summary?.directCount ?? 0,
-      dependencies: data.dependencies?.direct?.filter((d) => d).map((d) => ({
+      uniquePackagesCount: data.dependencies?.summary?.uniquePackagesCount ?? 0,
+      transitiveIncluded: options.transitive ?? false,
+      dependencies: data.dependencies?.direct?.filter((d) => Boolean(d)).map((d) => ({
         name: d.name,
         version: d.versionConstraint,
         type: d.type
       }))
-    };
-    output(slim, true);
+    }, true);
+  } else if (format === "summary") {
+    const data = result.data.packageDependencies;
+    const deps2 = data.dependencies;
+    const directCount = deps2?.summary?.directCount ?? 0;
+    const uniquePackagesCount = deps2?.summary?.uniquePackagesCount ?? 0;
+    const lines = [
+      `Package: ${data.package?.name ?? ""}@${data.package?.version ?? ""}`,
+      `Direct deps: ${directCount}`,
+      `Unique packages: ${uniquePackagesCount || "N/A"}`,
+      transitiveRequested ? "Transitive: included" : "Transitive: not included (use --transitive)"
+    ];
+    console.log(lines.join(`
+`));
   } else {
-    console.log(formatPackageDependencies(result.data.packageDependencies));
+    console.log(formatPackageDependencies(result.data.packageDependencies, transitiveRequested));
   }
 }
 var DEPS_DESCRIPTION = `Get package dependencies.
@@ -4379,7 +4585,7 @@ Examples:
   pkgseer pkg deps lodash --transitive
   pkgseer pkg deps requests --registry pypi --json`;
 function registerPkgDepsCommand(program) {
-  program.command("deps <package>").summary("Get package dependencies").description(DEPS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("-t, --transitive", "Include transitive dependencies").option("--json", "Output as JSON").action(async (packageName, options) => {
+  program.command("deps <package>").summary("Get package dependencies").description(DEPS_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("-t, --transitive", "Include transitive dependencies").option("--max-depth <n>", "Maximum transitive depth (1-10, defaults to server)").option("--format <format>", "Output format: human|summary|json", "human").option("--json", "Output as JSON").action(async (packageName, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await pkgDepsAction(packageName, options, deps);
@@ -4480,18 +4686,15 @@ function formatPackageQuality(data) {
   if (!quality) {
     return "No quality data available.";
   }
-  lines.push(`\uD83D\uDCCA Quality Score: ${formatScore(quality.overallScore)} (Grade: ${quality.grade})`);
-  lines.push("");
-  if (quality.categories && quality.categories.length > 0) {
-    lines.push("Category Breakdown:");
-    for (const category of quality.categories) {
-      if (category) {
-        const name = (category.category || "Unknown").padEnd(20);
-        lines.push(`  ${name} ${formatScore(category.score)}`);
-      }
+  const topCategories = (quality.categories ?? []).filter((c) => Boolean(c)).sort((a, b) => (b?.score ?? 0) - (a?.score ?? 0)).slice(0, 3);
+  lines.push(`\uD83D\uDCCA Quality: Grade ${quality.grade ?? "N/A"} (${formatScore(quality.overallScore)})`);
+  if (topCategories.length > 0) {
+    lines.push("Top drivers:");
+    for (const category of topCategories) {
+      lines.push(`  - ${(category.category ?? "Unknown").toLowerCase()}: ${formatScore(category.score)}`);
     }
-    lines.push("");
   }
+  lines.push("Tip: use --json for full category breakdown.");
   return lines.join(`
 `);
 }
@@ -4504,7 +4707,8 @@ async function pkgQualityAction(packageName, options, deps) {
     outputError(`Package not found: ${packageName} in ${options.registry}`, options.json ?? false);
     return;
   }
-  if (options.json) {
+  const format = options.json ? "json" : options.format ?? "human";
+  if (format === "json") {
     const quality = result.data.packageQuality.quality;
     const slim = {
       package: `${result.data.packageQuality.package?.name}@${result.data.packageQuality.package?.version}`,
@@ -4533,7 +4737,7 @@ Examples:
   pkgseer pkg quality express -v 4.18.0
   pkgseer pkg quality requests --registry pypi --json`;
 function registerPkgQualityCommand(program) {
-  program.command("quality <package>").summary("Get package quality score").description(QUALITY_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--json", "Output as JSON").action(async (packageName, options) => {
+  program.command("quality <package>").summary("Get package quality score").description(QUALITY_DESCRIPTION).option("-r, --registry <registry>", "Package registry", "npm").option("-v, --pkg-version <version>", "Package version").option("--format <format>", "Output format: human|summary|json", "human").option("--json", "Output as JSON").action(async (packageName, options) => {
     await withCliErrorHandling(options.json ?? false, async () => {
       const deps = await createContainer();
       await pkgQualityAction(packageName, options, deps);

package/dist/index.js

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

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

@@ -1,4 +1,4 @@
 // package.json
-var version = "0.1.3";
+var version = "0.1.4";
 
 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.3",
+  "version": "0.1.4",
   "type": "module",
   "files": [
     "dist",