@yawlabs/npmjs-mcp 0.11.15 → 0.12.1

package/dist/index.js

@@ -31347,12 +31347,23 @@ function translateError(res, context) {
         ...res,
         error: `Rate limited${opPart}. Retried automatically and still failed \u2014 wait longer and retry, or contact npm support if this persists. Raw: ${res.error}`
       };
+    case 409:
+      return {
+        ...res,
+        error: `Version conflict${pkgPart}${opPart}. The package metadata changed between read and write (a concurrent publish, deprecate, or registry _rev bump). Re-run the operation \u2014 it re-fetches the current _rev each call. Raw: ${res.error}`
+      };
     case 0:
       return {
         ...res,
         error: `Network error${opPart}. Could not reach the registry. Raw: ${res.error}`
       };
     default:
+      if (res.status >= 500) {
+        return {
+          ...res,
+          error: `Registry server error${pkgPart}${opPart} (HTTP ${res.status}). Retried automatically and still failed \u2014 the registry is likely having a transient outage. Wait and retry; check https://status.npmjs.org if it persists. Raw: ${res.error}`
+        };
+      }
       return res;
   }
 }
@@ -31383,7 +31394,7 @@ var accessTools = [
       if (authErr) return authErr;
       const res = await registryGetAuth(`/-/package/${encPkg(input.name)}/collaborators`);
       if (!res.ok) return translateError(res, { pkg: input.name, op: "collaborators" });
-      const collaborators = Object.entries(res.data).map(([username, permissions]) => ({
+      const collaborators = Object.entries(res.data ?? {}).map(([username, permissions]) => ({
         username,
         permissions
       }));
@@ -31418,7 +31429,13 @@ var accessTools = [
         registryGetAuth(`/-/package/${encPkg(input.name)}/access`),
         registryGetAuth(`/-/package/${encPkg(input.name)}/collaborators`)
       ]);
-      if (!accessRes.ok && !collabRes.ok) return translateError(collabRes, { pkg: input.name, op: "package_access" });
+      if (!accessRes.ok && !collabRes.ok) {
+        return {
+          ok: false,
+          status: accessRes.status,
+          error: `Both package_access requests failed. access endpoint: HTTP ${accessRes.status}${accessRes.error ? ` (${accessRes.error})` : ""}; collaborators endpoint: HTTP ${collabRes.status}${collabRes.error ? ` (${collabRes.error})` : ""}.`
+        };
+      }
       const result = {
         package: input.name,
         isScoped: input.name.startsWith("@")
@@ -31431,7 +31448,7 @@ var accessTools = [
         result.access = accessRes.data;
       }
       if (collabRes.ok) {
-        result.collaborators = Object.entries(collabRes.data).map(([username, permissions]) => ({
+        result.collaborators = Object.entries(collabRes.data ?? {}).map(([username, permissions]) => ({
           username,
           permissions
         }));
@@ -31457,6 +31474,10 @@ var analysisTools = [
       packages: external_exports.array(external_exports.string()).min(2).max(5).describe("Package names to compare")
     }),
     handler: async (input) => {
+      for (const pkg of input.packages) {
+        const nameErr = validatePackageName(pkg);
+        if (nameErr) return { ok: false, status: 400, error: nameErr };
+      }
       const partials = await Promise.all(
         input.packages.map(async (name) => {
           const [pkgRes, dlRes] = await Promise.all([
@@ -31499,10 +31520,15 @@ var analysisTools = [
           latest,
           license: pkg.license ?? latestVersion?.license,
           maintainers: pkg.maintainers?.map((m) => m.name),
-          weeklyDownloads: dlRes.ok ? dlRes.data.downloads : null,
+          // Guard on data presence, not just .ok: a 2xx with an empty body yields
+          // ok:true with no data (api.ts), and dlRes.data!.downloads would throw
+          // and crash the whole compare. Degrade to null instead.
+          weeklyDownloads: dlRes.ok && dlRes.data ? dlRes.data.downloads : null,
+          // versionCount includes ALL published versions (stable + pre-releases).
           versionCount: versionKeys.length,
           created: pkg.time.created,
           lastPublish: latest ? pkg.time[latest] : void 0,
+          // `deprecated` is false when not deprecated, or the message string when deprecated.
           deprecated: latestVersion?.deprecated ?? false,
           hasReadme: !!(pkg.readme && pkg.readme.length > 0),
           repository: pkg.repository,
@@ -31565,12 +31591,15 @@ var analysisTools = [
         }
         avgDaysBetweenReleases = Math.round(gaps.reduce((a, b) => a + b, 0) / gaps.length);
       }
+      const STALE_DAYS = 365;
+      const ACTIVE_DAYS = 90;
       const hasLicense = !!(pkg.license ?? latestVersion?.license);
       const hasReadme = !!(pkg.readme && pkg.readme.length > 0);
       const hasRepo = !!pkg.repository;
       const hasHomepage = !!pkg.homepage;
       const isDeprecated = !!latestVersion?.deprecated;
-      const isStale = daysSinceLastPublish !== null && daysSinceLastPublish > 365;
+      const deprecatedMessage = latestVersion?.deprecated ?? false;
+      const isStale = daysSinceLastPublish !== null && daysSinceLastPublish > STALE_DAYS;
       return {
         ok: true,
         status: 200,
@@ -31578,9 +31607,12 @@ var analysisTools = [
           name: pkg.name,
           latest,
           signals: {
-            weeklyDownloads: dlWeekRes.ok ? dlWeekRes.data.downloads : null,
-            monthlyDownloads: dlMonthRes.ok ? dlMonthRes.data.downloads : null,
+            // Guard on data presence, not just .ok: an empty-body 2xx yields
+            // ok:true with no data (api.ts); degrade to null rather than throw.
+            weeklyDownloads: dlWeekRes.ok && dlWeekRes.data ? dlWeekRes.data.downloads : null,
+            monthlyDownloads: dlMonthRes.ok && dlMonthRes.data ? dlMonthRes.data.downloads : null,
             maintainerCount: pkg.maintainers?.length ?? 0,
+            // versionCount includes ALL published versions (stable + pre-releases).
             versionCount: versionKeys.length,
             daysSinceLastPublish,
             avgDaysBetweenReleases,
@@ -31590,7 +31622,8 @@ var analysisTools = [
             hasReadme,
             hasRepo,
             hasHomepage,
-            isDeprecated,
+            // `isDeprecated` is false when not deprecated, or the message string when deprecated.
+            isDeprecated: deprecatedMessage,
             isStale
           },
           // Holistic single-string verdict layered priority-first: a deprecated
@@ -31600,7 +31633,7 @@ var analysisTools = [
           // on the audit endpoint or a packument with no `latest` to audit) --
           // better to flag the unknown than confidently report ACTIVE on
           // unverified data. Then staleness, recency, and the catch-all.
-          assessment: isDeprecated ? "DEPRECATED" : vulnerabilityCount !== null && vulnerabilityCount > 0 ? "VULNERABLE" : !auditReliable ? "AUDIT_UNKNOWN" : isStale ? "STALE" : daysSinceLastPublish !== null && daysSinceLastPublish < 90 ? "ACTIVE" : "MAINTENANCE"
+          assessment: isDeprecated ? "DEPRECATED" : vulnerabilityCount !== null && vulnerabilityCount > 0 ? "VULNERABLE" : !auditReliable ? "AUDIT_UNKNOWN" : isStale ? "STALE" : daysSinceLastPublish !== null && daysSinceLastPublish < ACTIVE_DAYS ? "ACTIVE" : "MAINTENANCE"
         }
       };
     }
@@ -31674,6 +31707,7 @@ var analysisTools = [
         status: 200,
         data: {
           name: pkg.name,
+          // totalVersions includes ALL published versions (stable + pre-releases).
           totalVersions: Object.keys(pkg.versions).length,
           analyzed: releases.length,
           created: pkg.time.created,
@@ -31781,6 +31815,10 @@ var authTools = [
           tokens: data.objects.map((t) => ({
             key: t.key,
             readonly: t.readonly,
+            // Surface token class + automation flag so callers can tell automation
+            // tokens (which bypass 2FA) from granular/legacy ones. Undefined drops out of JSON.
+            type: t.type,
+            automation: t.automation,
             cidrWhitelist: t.cidr_whitelist,
             created: t.created,
             updated: t.updated
@@ -31813,12 +31851,20 @@ var authTools = [
           error: `Token failed /-/whoami check. Token is invalid, expired, or revoked. Create a new one at https://www.npmjs.com/settings/~/tokens. Raw: ${whoami.error}`
         };
       }
-      const tfaData = profile.ok ? profile.data?.tfa : null;
-      const tfa = tfaData ? {
-        enabled: !tfaData.pending,
-        mode: tfaData.mode,
-        ...tfaData.pending ? { pending: true } : {}
-      } : { enabled: false };
+      let tfa;
+      if (!profile.ok) {
+        tfa = {
+          unknown: true,
+          warning: `2FA status unknown: profile lookup failed (HTTP ${profile.status}). Token is valid (whoami passed) but write-readiness could not be fully assessed. Raw: ${profile.error}`
+        };
+      } else {
+        const tfaData = profile.data?.tfa;
+        tfa = tfaData ? {
+          enabled: !tfaData.pending,
+          mode: tfaData.mode,
+          ...tfaData.pending ? { pending: true } : {}
+        } : { enabled: false };
+      }
       return {
         ok: true,
         status: 200,
@@ -31917,7 +31963,7 @@ var dependencyTools = [
     inputSchema: external_exports.object({
       name: external_exports.string().describe("Package name"),
       version: external_exports.string().optional().describe("Semver version or dist-tag (default: 'latest')"),
-      depth: external_exports.number().min(1).max(5).optional().describe("Max tree depth (default 3, max 5)")
+      depth: external_exports.number().min(1).max(5).optional().describe("Max tree depth where the root counts as level 1 (default 3 = root + 2 transitive levels, max 5)")
     }),
     handler: async (input) => {
       const maxDepth = input.depth ?? 3;
@@ -31933,7 +31979,18 @@ var dependencyTools = [
         resolved.add(hintKey);
         let pending = packumentCache.get(name);
         if (!pending) {
-          pending = runLimited(() => registryGetAbbreviated(`/${encPkg(name)}`)).then((res) => {
+          let encodedName;
+          try {
+            encodedName = encPkg(name);
+          } catch {
+            warnings.push(`Invalid package name "${name}": skipped`);
+            if (!failedPackages.has(name)) {
+              failedPackages.add(name);
+              tree[hintKey] = { version: versionHint2, dependencies: {}, failed: true };
+            }
+            return;
+          }
+          pending = runLimited(() => registryGetAbbreviated(`/${encodedName}`)).then((res) => {
             if (!res.ok) {
               warnings.push(`Failed to fetch ${name}: ${res.error}`);
               return null;
@@ -32071,7 +32128,7 @@ var downloadTools = [
     },
     inputSchema: external_exports.object({
       name: external_exports.string().describe("Package name"),
-      period: external_exports.string().optional().describe("Period: 'last-day', 'last-week', 'last-month', 'last-year', or 'YYYY-MM-DD:YYYY-MM-DD'")
+      period: external_exports.string().optional().describe("Period: 'last-day', 'last-week', 'last-month', 'last-year', or 'YYYY-MM-DD:YYYY-MM-DD' (default: 'last-week')")
     }),
     handler: async (input) => {
       const period = input.period ?? "last-week";
@@ -32091,7 +32148,7 @@ var downloadTools = [
     },
     inputSchema: external_exports.object({
       name: external_exports.string().describe("Package name"),
-      period: external_exports.string().optional().describe("Period: 'last-week', 'last-month', 'last-year', or 'YYYY-MM-DD:YYYY-MM-DD'")
+      period: external_exports.string().optional().describe("Period: 'last-week', 'last-month', 'last-year', or 'YYYY-MM-DD:YYYY-MM-DD' (default: 'last-month')")
     }),
     handler: async (input) => {
       const period = input.period ?? "last-month";
@@ -32115,6 +32172,10 @@ var downloadTools = [
     }),
     handler: async (input) => {
       const period = input.period ?? "last-week";
+      for (const pkg of input.packages) {
+        const nameErr = validatePackageName(pkg);
+        if (nameErr) return { ok: false, status: 400, error: nameErr };
+      }
       const scoped = input.packages.filter((p) => p.startsWith("@"));
       if (scoped.length > 0) {
         return {
@@ -32243,7 +32304,17 @@ var hookTools = [
       const authErr = requireAuth();
       if (authErr) return authErr;
       const qs = new URLSearchParams();
-      if (input.package) qs.set("package", input.package);
+      if (input.package) {
+        const pkgErr = validatePackageName(input.package);
+        if (pkgErr) {
+          return {
+            ok: false,
+            status: 400,
+            error: `Invalid package filter '${input.package}': ${pkgErr}`
+          };
+        }
+        qs.set("package", input.package);
+      }
       if (input.limit !== void 0) qs.set("limit", String(input.limit));
       if (input.offset !== void 0) qs.set("offset", String(input.offset));
       const q = qs.toString();
@@ -32736,7 +32807,7 @@ var packageTools = [
 var provenanceTools = [
   {
     name: "npm_provenance",
-    description: "Get Sigstore provenance attestations for a specific package version. Shows SLSA provenance (which CI built it, from which repo/commit) and publish attestations. Essential for supply chain security verification.",
+    description: "Retrieve Sigstore attestations for a specific package version. Shows SLSA provenance (which CI built it, from which repo/commit) and publish attestations. NOTE: this tool RETRIEVES attestations from the registry -- it does NOT perform cryptographic signature, certificate-chain, or Rekor transparency-log verification. Use a dedicated Sigstore client to cryptographically verify the bundles.",
     annotations: {
       title: "Package provenance",
       readOnlyHint: true,
@@ -32749,11 +32820,14 @@ var provenanceTools = [
       version: external_exports.string().describe("Exact semver version (e.g. '1.0.0')")
     }),
     handler: async (input) => {
+      if (!input.version || !input.version.trim()) {
+        return { ok: false, status: 400, error: "version is required and must not be empty" };
+      }
       const res = await registryGet(
         `/-/npm/v1/attestations/${encPkg(input.name)}@${encodeURIComponent(input.version)}`
       );
       if (!res.ok) return translateError(res, { pkg: input.name, op: `provenance ${input.version}` });
-      const attestations = (res.data.attestations ?? []).map((a) => ({
+      const attestations = (res.data?.attestations ?? []).map((a) => ({
         predicateType: a.predicateType,
         bundle: a.bundle
       }));
@@ -32764,8 +32838,10 @@ var provenanceTools = [
           package: input.name,
           version: input.version,
           attestationCount: attestations.length,
-          hasProvenance: attestations.some((a) => a.predicateType.includes("slsa.dev/provenance")),
-          hasPublishAttestation: attestations.some((a) => a.predicateType.includes("npmjs.com/attestation")),
+          hasProvenance: attestations.some((a) => a.predicateType.startsWith("https://slsa.dev/provenance")),
+          hasPublishAttestation: attestations.some(
+            (a) => a.predicateType.startsWith("https://npmjs.com/attestation")
+          ),
           attestations
         }
       };
@@ -32801,7 +32877,7 @@ var registryTools = [
       title: "Recent registry changes",
       readOnlyHint: true,
       destructiveHint: false,
-      idempotentHint: true,
+      idempotentHint: false,
       openWorldHint: true
     },
     inputSchema: external_exports.object({
@@ -32814,7 +32890,7 @@ var registryTools = [
         replicateGet(`/_changes?limit=${limit}&descending=true`)
       ]);
       if (!changesRes.ok) return translateError(changesRes, { op: "recent_changes" });
-      const changes = changesRes.data.results.map((r) => ({
+      const changes = (changesRes.data?.results ?? []).map((r) => ({
         package: r.id,
         rev: r.changes[0]?.rev
       }));
@@ -32822,7 +32898,11 @@ var registryTools = [
         ok: true,
         status: 200,
         data: {
-          totalPackages: dbRes.ok ? dbRes.data.doc_count : null,
+          // `registryPackageCount` is the registry-wide doc-count from
+          // replicate.npmjs.com (the entire npm registry, ~3M) -- NOT the
+          // count of returned changes. `changes.length` is the per-call
+          // result size.
+          registryPackageCount: dbRes.data?.doc_count ?? null,
           changes
         }
       };
@@ -32855,7 +32935,7 @@ var registryTools = [
             tool: "mcp_tool: npm_deprecate",
             requiresNpmToken: true,
             messageFormat: {
-              preferred: "Renamed to @scope/pkg \u2014 install that instead",
+              preferred: "Renamed to @scope/pkg -- install that instead",
               avoid: "Renamed to @scope/pkg. Install that instead.",
               note: "Period-capital form has triggered 422 on at least one scoped package; use em-dash."
             }
@@ -32921,6 +33001,13 @@ var searchTools = [
       maintenance: external_exports.number().min(0).max(1).optional().describe("Weight for maintenance score (0-1)")
     }),
     handler: async (input) => {
+      if (input.query.trim() === "") {
+        return {
+          ok: false,
+          status: 400,
+          error: "Query cannot be empty. Provide a search term or qualifier (e.g. 'mcp', 'keywords:react')."
+        };
+      }
       const params = new URLSearchParams({ text: input.query });
       if (input.size !== void 0) params.set("size", String(input.size));
       if (input.from !== void 0) params.set("from", String(input.from));
@@ -32929,7 +33016,8 @@ var searchTools = [
       if (input.maintenance !== void 0) params.set("maintenance", String(input.maintenance));
       const res = await registryGet(`/-/v1/search?${params}`);
       if (!res.ok) return translateError(res, { op: `search "${input.query}"` });
-      const results = res.data.objects.map((obj) => ({
+      const objects = res.data?.objects ?? [];
+      const results = objects.map((obj) => ({
         name: obj.package.name,
         version: obj.package.version,
         description: obj.package.description,
@@ -32940,7 +33028,7 @@ var searchTools = [
         links: obj.package.links,
         score: obj.score.detail
       }));
-      return { ok: true, status: 200, data: { total: res.data.total, results } };
+      return { ok: true, status: 200, data: { total: res.data?.total ?? objects.length, results } };
     }
   }
 ];
@@ -33007,9 +33095,15 @@ var securityTools = [
       dependencies: external_exports.record(external_exports.string(), external_exports.string()).describe('Dependencies to audit as { "package": "version" }, e.g. { "express": "4.17.1" }')
     }),
     handler: async (input) => {
+      const nameErr = validatePackageName(input.name);
+      if (nameErr) return { ok: false, status: 400, error: nameErr };
+      const version3 = input.version ?? "1.0.0";
+      if (!version3.trim()) {
+        return { ok: false, status: 400, error: "version must not be empty" };
+      }
       const body = {
         name: input.name,
-        version: input.version ?? "1.0.0",
+        version: version3,
         requires: input.dependencies,
         dependencies: Object.fromEntries(
           Object.entries(input.dependencies).map(([pkg, ver]) => [pkg, { version: ver }])
@@ -33065,12 +33159,20 @@ var trustTools = [
         if (c.type === "github") {
           result.repository = c.claims?.repository;
           const workflowRef = c.claims?.workflow_ref;
-          result.workflowFile = workflowRef?.file;
+          if (typeof workflowRef === "string") {
+            result.workflowFile = workflowRef;
+          } else if (workflowRef && typeof workflowRef === "object") {
+            result.workflowFile = workflowRef.file;
+          }
           result.environment = c.claims?.environment;
         } else if (c.type === "gitlab") {
           result.project = c.claims?.project_path;
           const configRef = c.claims?.ci_config_ref_uri;
-          result.configFile = configRef?.file;
+          if (typeof configRef === "string") {
+            result.configFile = configRef;
+          } else if (configRef && typeof configRef === "object") {
+            result.configFile = configRef.file;
+          }
           result.environment = c.claims?.environment;
         } else if (c.type === "circleci") {
           result.project = c.claims?.project_id;
@@ -33124,7 +33226,10 @@ var workflowTools = [
       }
       result.authenticated = true;
       result.username = whoamiRes.data.username;
-      const profileRes = await registryGetAuth("/-/npm/v1/user");
+      const [profileRes, tokensRes] = await Promise.all([
+        registryGetAuth("/-/npm/v1/user"),
+        registryGetAuth("/-/npm/v1/tokens")
+      ]);
       if (profileRes.ok && profileRes.data) {
         const tfa = profileRes.data.tfa;
         if (tfa && !tfa.pending) {
@@ -33132,8 +33237,9 @@ var workflowTools = [
         } else {
           result.twoFactorAuth = "disabled";
         }
+      } else {
+        result.twoFactorAuth = "fetch-failed";
       }
-      const tokensRes = await registryGetAuth("/-/npm/v1/tokens");
       if (tokensRes.ok && tokensRes.data) {
         const tokens = tokensRes.data.objects;
         const hasReadWrite = tokens.some((t) => !t.readonly);
@@ -33144,6 +33250,10 @@ var workflowTools = [
         result.canPublishHeadless = true;
         result.tokenType = "any (2FA disabled)";
         result.recommendation = "2FA is disabled \u2014 any valid token can publish. Consider enabling 2FA for security.";
+      } else if (result.twoFactorAuth === "fetch-failed") {
+        result.canPublishHeadless = null;
+        result.tokenType = "unknown (profile fetch failed)";
+        result.recommendation = "Could not determine 2FA status -- token may lack read permission on /-/npm/v1/user. Verify the token has at least read access and re-run npm_check_auth.";
       } else {
         result.tokenType = "unknown (tokens are redacted in API)";
         result.canPublishHeadless = null;
@@ -33224,7 +33334,10 @@ var workflowTools = [
           });
         }
         if (username) {
-          const profileRes = await registryGetAuth("/-/npm/v1/user");
+          const [profileRes, tokensRes] = await Promise.all([
+            registryGetAuth("/-/npm/v1/user"),
+            registryGetAuth("/-/npm/v1/tokens")
+          ]);
           if (profileRes.ok && profileRes.data) {
             const tfa = profileRes.data.tfa;
             if (tfa && !tfa.pending) {
@@ -33247,8 +33360,13 @@ var workflowTools = [
                 detail: "2FA is disabled. Any valid token can publish, but 2FA is strongly recommended for security."
               });
             }
+          } else {
+            checks.push({
+              check: "2FA status",
+              status: "warn",
+              detail: "Could not determine 2FA status -- token may lack read permission on /-/npm/v1/user. Verify the token has at least read access and re-run npm_publish_preflight."
+            });
           }
-          const tokensRes = await registryGetAuth("/-/npm/v1/tokens");
           if (tokensRes.ok && tokensRes.data) {
             const tokens = tokensRes.data.objects;
             const totalTokens = tokensRes.data.total;
@@ -33395,15 +33513,8 @@ function parseTeamTarget(target) {
   return { scope, team };
 }
 function highestVersion(versions) {
-  const parsed = [];
-  for (const v of versions) {
-    if (v.includes("-")) continue;
-    const m = v.match(/^(\d+)\.(\d+)\.(\d+)/);
-    if (m) parsed.push([Number(m[1]), Number(m[2]), Number(m[3]), v]);
-  }
-  if (parsed.length === 0) return null;
-  parsed.sort((a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2]);
-  return parsed[parsed.length - 1][3];
+  const stable = versions.filter((v) => !v.includes("-"));
+  return maxSatisfying(stable, "*");
 }
 var writeTools = [
   // ───────────────────────────────────────────────────────
@@ -33421,7 +33532,7 @@ var writeTools = [
     },
     inputSchema: external_exports.object({
       name: external_exports.string().describe("Package name (e.g. '@yawlabs/spend')"),
-      message: external_exports.string().describe("Deprecation message. Empty string to clear deprecation (use npm_undeprecate instead)."),
+      message: external_exports.string().describe("Deprecation message. Use npm_undeprecate to clear."),
       versionRange: external_exports.string().optional().describe(
         "Semver range. Omit to deprecate ALL versions. Example: '<1.0.0' or '0.3.x'. Standard semver applies \u2014 bare integers are x-ranges (e.g. '0' means '0.x.x', not exact version 0). For a single version use '=1.2.3'."
       )
@@ -33431,46 +33542,50 @@ var writeTools = [
       if (authErr) return authErr;
       const problem = validateDeprecationMessage(input.message);
       if (problem) return { ok: false, status: 400, error: problem };
-      const pRes = await fetchPackument(input.name);
-      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "deprecate (fetch)" });
-      const packument = pRes.data;
-      const allVersions = Object.keys(packument.versions || {});
       const range = input.versionRange ?? "*";
-      const affected = versionsSatisfying(allVersions, range);
-      if (affected.length === 0) {
-        return {
-          ok: false,
-          status: 400,
-          error: `No versions match range '${range}' for ${input.name}. Published versions: ${allVersions.join(", ") || "(none)"}.`
-        };
-      }
-      for (const v of affected) {
-        packument.versions[v].deprecated = input.message;
-      }
-      if (!packument._rev) {
+      for (let attempt = 0; attempt <= 1; attempt++) {
+        const pRes = await fetchPackument(input.name);
+        if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "deprecate (fetch)" });
+        const packument = pRes.data;
+        const allVersions = Object.keys(packument.versions || {});
+        const affected = versionsSatisfying(allVersions, range);
+        if (affected.length === 0) {
+          return {
+            ok: false,
+            status: 400,
+            error: `No versions match range '${range}' for ${input.name}. Published versions: ${allVersions.join(", ") || "(none)"}.`
+          };
+        }
+        if (!packument._rev) {
+          return {
+            ok: false,
+            status: 500,
+            error: `Packument for ${input.name} missing _rev -- cannot deprecate. Try again; this is usually transient.`
+          };
+        }
+        for (const v of affected) {
+          packument.versions[v].deprecated = input.message;
+        }
+        delete packument._revisions;
+        delete packument._attachments;
+        const putRes = await registryPutAuth(
+          `/${encPkg(input.name)}/-rev/${encodeURIComponent(packument._rev)}`,
+          packument
+        );
+        if (putRes.status === 409 && attempt === 0) continue;
+        if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "deprecate (write)" });
         return {
-          ok: false,
-          status: 500,
-          error: `Packument for ${input.name} missing _rev -- cannot deprecate. Try again; this is usually transient.`
+          ok: true,
+          status: 200,
+          data: {
+            package: input.name,
+            affectedVersions: affected,
+            totalAffected: affected.length,
+            message: input.message
+          }
         };
       }
-      delete packument._revisions;
-      delete packument._attachments;
-      const putRes = await registryPutAuth(
-        `/${encPkg(input.name)}/-rev/${encodeURIComponent(packument._rev)}`,
-        packument
-      );
-      if (!putRes.ok) return translateError(putRes, { pkg: input.name, op: "deprecate (write)" });
-      return {
-        ok: true,
-        status: 200,
-        data: {
-          package: input.name,
-          affectedVersions: affected,
-          totalAffected: affected.length,
-          message: input.message
-        }
-      };
+      return { ok: false, status: 409, error: "Conflict after OCC retry -- try again." };
     }
   },
   // ───────────────────────────────────────────────────────
@@ -33585,15 +33700,16 @@ var writeTools = [
         return {
           ok: false,
           status: 500,
-          error: `Packument for ${input.name} missing _rev \u2014 cannot unpublish. Try again; this is usually transient.`
+          error: `Packument for ${input.name} missing _rev -- cannot unpublish. Try again; this is usually transient.`
         };
       }
       const tarballUrl = versionData.dist?.tarball;
-      const latestBefore = packument["dist-tags"]?.latest;
+      const distTags = packument["dist-tags"] || {};
+      const latestBefore = distTags.latest;
       delete packument.versions[input.version];
-      for (const tag of Object.keys(packument["dist-tags"] || {})) {
-        if (packument["dist-tags"][tag] === input.version) {
-          delete packument["dist-tags"][tag];
+      for (const tag of Object.keys(distTags)) {
+        if (distTags[tag] === input.version) {
+          delete distTags[tag];
         }
       }
       if (latestBefore === input.version) {
@@ -33617,10 +33733,17 @@ var writeTools = [
         const freshRev = freshRes.ok ? freshRes.data._rev : void 0;
         if (freshRev) {
           try {
-            const pathname = new URL(tarballUrl).pathname;
-            const delRes = await registryDeleteAuth(`${pathname}/-rev/${encodeURIComponent(freshRev)}`);
-            tarballDeleted = delRes.ok;
-            if (!delRes.ok) tarballError = delRes.error;
+            const tarballParsed = new URL(tarballUrl);
+            const registryOrigin = new URL(
+              (process.env.NPM_REGISTRY || "https://registry.npmjs.org").replace(/\/+$/, "")
+            ).origin;
+            if (tarballParsed.origin !== registryOrigin) {
+              tarballError = `tarball origin ${tarballParsed.origin} does not match registry origin ${registryOrigin} -- tarball DELETE skipped`;
+            } else {
+              const delRes = await registryDeleteAuth(`${tarballParsed.pathname}/-rev/${encodeURIComponent(freshRev)}`);
+              tarballDeleted = delRes.ok;
+              if (!delRes.ok) tarballError = delRes.error;
+            }
           } catch (err) {
             tarballError = err instanceof Error ? err.message : String(err);
           }
@@ -33677,7 +33800,7 @@ var writeTools = [
         return {
           ok: false,
           status: 500,
-          error: `Packument for ${input.name} missing _rev \u2014 cannot unpublish.`
+          error: `Packument for ${input.name} missing _rev -- cannot unpublish.`
         };
       }
       const delRes = await registryDeleteAuth(`/${encPkg(input.name)}/-rev/${encodeURIComponent(rev)}`);
@@ -33712,6 +33835,16 @@ var writeTools = [
       if (authErr) return authErr;
       const tagErr = validateTag(input.tag);
       if (tagErr) return { ok: false, status: 400, error: tagErr };
+      const pRes = await fetchPackument(input.name);
+      if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: `dist-tag set ${input.tag} (fetch)` });
+      const packument = pRes.data;
+      if (!packument.versions?.[input.version]) {
+        return {
+          ok: false,
+          status: 404,
+          error: `Version ${input.version} not found for ${input.name}. Published versions: ${Object.keys(packument.versions || {}).join(", ")}.`
+        };
+      }
       const putRes = await registryPutAuth(
         `/-/package/${encPkg(input.name)}/dist-tags/${encTag(input.tag)}`,
         input.version
@@ -33817,7 +33950,7 @@ var writeTools = [
         return {
           ok: false,
           status: 500,
-          error: `Packument for ${input.name} missing _rev \u2014 cannot update owners.`
+          error: `Packument for ${input.name} missing _rev -- cannot update owners.`
         };
       }
       const maintainers = [...owners, userRecord];
@@ -33864,14 +33997,14 @@ var writeTools = [
       if (!pRes.ok) return translateError(pRes, { pkg: input.name, op: "owner_remove (fetch)" });
       const packument = pRes.data;
       const before = packument.maintainers || [];
-      if (!before.some((m) => m.name === input.username)) {
+      if (!before.some((m) => m.name.toLowerCase() === input.username.toLowerCase())) {
         return {
           ok: false,
           status: 404,
           error: `${input.username} is not a maintainer of ${input.name}. Current maintainers: ${before.map((m) => m.name).join(", ") || "(none)"}.`
         };
       }
-      const after = before.filter((m) => m.name !== input.username);
+      const after = before.filter((m) => m.name.toLowerCase() !== input.username.toLowerCase());
       if (after.length === 0) {
         return {
           ok: false,
@@ -33883,7 +34016,7 @@ var writeTools = [
         return {
           ok: false,
           status: 500,
-          error: `Packument for ${input.name} missing _rev \u2014 cannot update owners.`
+          error: `Packument for ${input.name} missing _rev -- cannot update owners.`
         };
       }
       const putRes = await registryPutAuth(`/${encPkg(input.name)}/-rev/${encodeURIComponent(packument._rev)}`, {
@@ -33908,7 +34041,7 @@ var writeTools = [
   // ───────────────────────────────────────────────────────
   {
     name: "npm_access_set",
-    description: "Set package access level: 'public', 'private', or 'restricted'. Unscoped packages are always public. Private access requires a paid npm account.",
+    description: "Set package access level: 'public' or 'restricted' (private). 'private' is accepted as an alias for 'restricted' for ergonomics -- both map to the registry wire value 'restricted'. Unscoped packages are always public. Restricted access requires a paid npm account.",
     annotations: {
       title: "Set package access level",
       readOnlyHint: false,
@@ -33918,17 +34051,18 @@ var writeTools = [
     },
     inputSchema: external_exports.object({
       name: external_exports.string().describe("Package name"),
-      access: external_exports.enum(["public", "private", "restricted"]).describe("Access level")
+      access: external_exports.enum(["public", "private", "restricted"]).describe("Access level ('private' maps to 'restricted' on the wire)")
     }),
     handler: async (input) => {
       const authErr = requireAuth();
       if (authErr) return authErr;
-      const res = await registryPostAuth(`/-/package/${encPkg(input.name)}/access`, { access: input.access });
+      const wireAccess = input.access === "private" ? "restricted" : input.access;
+      const res = await registryPostAuth(`/-/package/${encPkg(input.name)}/access`, { access: wireAccess });
       if (!res.ok) return translateError(res, { pkg: input.name, op: `access_set ${input.access}` });
       return {
         ok: true,
         status: 200,
-        data: { package: input.name, access: input.access }
+        data: { package: input.name, access: wireAccess }
       };
     }
   },
@@ -33984,12 +34118,16 @@ var writeTools = [
     },
     inputSchema: external_exports.object({
       team: external_exports.string().describe("Team in the form '@scope:team' (e.g. '@yawlabs:devs')"),
-      package: external_exports.string().describe("Package name"),
+      package: external_exports.string().describe(
+        "Package name. Field is named 'package' to match the npm CLI (diverges from 'name' used elsewhere in this server)."
+      ),
       permissions: external_exports.enum(["read-only", "read-write"]).describe("Permission level")
     }),
     handler: async (input) => {
       const authErr = requireAuth();
       if (authErr) return authErr;
+      const pkgErr = validatePackageName(input.package);
+      if (pkgErr) return { ok: false, status: 400, error: pkgErr };
       const parsed = parseTeamTarget(input.team);
       if ("error" in parsed) {
         return { ok: false, status: 400, error: parsed.error };
@@ -34022,11 +34160,15 @@ var writeTools = [
     },
     inputSchema: external_exports.object({
       team: external_exports.string().describe("Team in the form '@scope:team'"),
-      package: external_exports.string().describe("Package name")
+      package: external_exports.string().describe(
+        "Package name. Field is named 'package' to match the npm CLI (diverges from 'name' used elsewhere in this server)."
+      )
     }),
     handler: async (input) => {
       const authErr = requireAuth();
       if (authErr) return authErr;
+      const pkgErr = validatePackageName(input.package);
+      if (pkgErr) return { ok: false, status: 400, error: pkgErr };
       const parsed = parseTeamTarget(input.team);
       if ("error" in parsed) {
         return { ok: false, status: 400, error: parsed.error };
@@ -34081,7 +34223,7 @@ var writeTools = [
   // ───────────────────────────────────────────────────────
   {
     name: "npm_team_delete",
-    description: "Delete a team. Team is passed as '@scope:team'. Revokes all package permissions that team held. Requires confirm: true \u2014 this removes the team and all its package grants in one call.",
+    description: "Delete a team. Team is passed as '@scope:team'. Revokes all package permissions that team held, and team memberships are also removed. Requires confirm: true \u2014 this removes the team and all its package grants in one call. List the team's current grants with npm_team_packages first if you need to preserve them.",
     annotations: {
       title: "Delete team",
       readOnlyHint: false,
@@ -34197,22 +34339,30 @@ var writeTools = [
     inputSchema: external_exports.object({
       org: external_exports.string().describe("Organization name (with or without leading @)"),
       user: external_exports.string().describe("npm username"),
-      role: external_exports.enum(["developer", "admin", "owner"]).optional().describe("Role to assign")
+      role: external_exports.enum(["developer", "admin", "owner"]).optional().describe("Role to assign"),
+      confirm: external_exports.literal(true).describe("Must be literally true. Guards against accidental org membership changes.")
     }),
     handler: async (input) => {
       const authErr = requireAuth();
       if (authErr) return authErr;
+      if (input.confirm !== true) {
+        return {
+          ok: false,
+          status: 400,
+          error: "org_member_set requires confirm: true. This adds or changes a user's org role."
+        };
+      }
       const orgErr = validateScope(input.org);
       if (orgErr) return { ok: false, status: 400, error: orgErr };
       const userErr = validateUsername(input.user);
       if (userErr) return { ok: false, status: 400, error: userErr };
-      const org = input.org.replace(/^@/, "");
-      const user = input.user.replace(/^@/, "");
-      const body = { user };
+      const userBare = input.user.replace(/^@/, "");
+      const orgBare = input.org.replace(/^@/, "");
+      const body = { user: userBare };
       if (input.role) body.role = input.role;
-      const res = await registryPutAuth(`/-/org/${encScope(org)}/user`, body);
-      if (!res.ok) return translateError(res, { op: `org_member_set ${org}/${user}` });
-      const data = { org, user };
+      const res = await registryPutAuth(`/-/org/${encScope(input.org)}/user`, body);
+      if (!res.ok) return translateError(res, { op: `org_member_set ${orgBare}/${userBare}` });
+      const data = { org: orgBare, user: userBare };
       if (input.role) data.role = input.role;
       return { ok: true, status: 200, data };
     }
@@ -34249,11 +34399,11 @@ var writeTools = [
       if (orgErr) return { ok: false, status: 400, error: orgErr };
       const userErr = validateUsername(input.user);
       if (userErr) return { ok: false, status: 400, error: userErr };
-      const org = input.org.replace(/^@/, "");
-      const user = input.user.replace(/^@/, "");
-      const res = await registryDeleteAuth(`/-/org/${encScope(org)}/user`, { user });
-      if (!res.ok) return translateError(res, { op: `org_member_remove ${org}/${user}` });
-      return { ok: true, status: 200, data: { org, removedUser: user } };
+      const orgBare = input.org.replace(/^@/, "");
+      const userBare = input.user.replace(/^@/, "");
+      const res = await registryDeleteAuth(`/-/org/${encScope(input.org)}/user`, { user: userBare });
+      if (!res.ok) return translateError(res, { op: `org_member_remove ${orgBare}/${userBare}` });
+      return { ok: true, status: 200, data: { org: orgBare, removedUser: userBare } };
     }
   },
   // ───────────────────────────────────────────────────────
@@ -34285,6 +34435,13 @@ var writeTools = [
           error: "token_revoke requires confirm: true. Revoking the token in NPM_TOKEN will break the next call."
         };
       }
+      if (!input.tokenKey || !/^[0-9a-f-]{8,}$/i.test(input.tokenKey)) {
+        return {
+          ok: false,
+          status: 400,
+          error: `Invalid token key '${input.tokenKey}'. Expected a UUID (hex characters and dashes, at least 8 characters). Use npm_tokens to list valid keys.`
+        };
+      }
       const res = await registryDeleteAuth(`/-/npm/v1/tokens/token/${encodeURIComponent(input.tokenKey)}`);
       if (!res.ok) return translateError(res, { op: "token_revoke" });
       return { ok: true, status: 200, data: { tokenKey: input.tokenKey, revoked: true } };
@@ -34293,7 +34450,7 @@ var writeTools = [
 ];
 
 // src/index.ts
-var version2 = true ? "0.11.15" : (await null).createRequire(import.meta.url)("../package.json").version;
+var version2 = true ? "0.12.1" : (await null).createRequire(import.meta.url)("../package.json").version;
 var subcommand = process.argv[2];
 if (subcommand === "version" || subcommand === "--version" || subcommand === "-v" || subcommand === "-V") {
   console.log(version2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/npmjs-mcp",
-  "version": "0.11.15",
+  "version": "0.12.1",
   "mcpName": "io.github.YawLabs/npmjs-mcp",
   "description": "npm registry MCP server — package intelligence, security audits, and dependency analysis for AI assistants",
   "license": "MIT",