nuxt-skill-hub 0.0.7 → 0.0.8

package/dist/module.d.mts

@@ -2,8 +2,8 @@ import * as _nuxt_schema from '@nuxt/schema';
 
 type SkillHubTarget = string;
 
-type SkillSourceKind = 'dist' | 'github' | 'generated';
-type SkillResolverKind = 'agentsField' | 'githubHeuristic' | 'metadataRouter';
+type SkillSourceKind = 'dist' | 'github' | 'wellKnown' | 'generated';
+type SkillResolverKind = 'agentsField' | 'githubHeuristic' | 'wellKnownV2' | 'metadataRouter';
 
 type SkillHubGenerationMode = 'prepare' | 'manual';
 interface ModuleOptions {

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-skill-hub",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "configKey": "skillHub",
   "compatibility": {
     "nuxt": ">=4.3.0"

package/dist/module.mjs

@@ -8,15 +8,16 @@ import matter from 'gray-matter';
 import { readPackageJSON, findWorkspaceDir, resolvePackageJSON, resolveLockfile } from 'pkg-types';
 import { transform } from 'automd';
 import { downloadTemplate } from 'giget';
-import { detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds, getAgentConfig } from 'unagent/env';
+import { getAgentConfig, detectInstalledAgents, expandPath, detectCurrentAgent, getAgentIds } from 'unagent/env';
 import { ofetch } from 'ofetch';
 import { createHash } from 'node:crypto';
+import { isIP } from 'node:net';
 import { hash } from 'ohash';
 import { glob } from 'tinyglobby';
 import { createConsola } from 'consola';
 import { colorize } from 'consola/utils';
 
-const version = "0.0.7";
+const version = "0.0.8";
 const packageJson = {
 	version: version};
 
@@ -146,6 +147,8 @@ function getSourceLabel(sourceKind) {
       return "Installed package skill";
     case "github":
       return "Resolved module skill";
+    case "wellKnown":
+      return "Docs-discovered skill";
     case "generated":
       return "Metadata-routed skill";
   }
@@ -206,8 +209,9 @@ function relativeModuleLink(entry, prefix) {
 function groupModuleEntries(entries) {
   const officialUpstream = entries.filter((entry) => entry.sourceKind === "dist");
   const githubResolved = entries.filter((entry) => entry.sourceKind === "github");
+  const wellKnownResolved = entries.filter((entry) => entry.sourceKind === "wellKnown");
   const metadataRouted = entries.filter((entry) => entry.sourceKind === "generated");
-  return { officialUpstream, githubResolved, metadataRouted };
+  return { officialUpstream, githubResolved, wellKnownResolved, metadataRouted };
 }
 function hasModuleGuidance(entries, skipped = []) {
   return entries.length > 0 || skipped.length > 0;
@@ -330,6 +334,7 @@ function createSkillMapSections(metadata, entries, skipped = [], includeModuleAu
   const moduleSections = [
     renderModuleGroup("Official upstream skills", grouped.officialUpstream, "./references/modules/"),
     renderModuleGroup("Resolved module skills", grouped.githubResolved, "./references/modules/"),
+    renderModuleGroup("Docs-discovered skills", grouped.wellKnownResolved, "./references/modules/"),
     renderModuleGroup("Metadata-routed skills", grouped.metadataRouted, "./references/modules/"),
     renderSkippedEntries(skipped)
   ].filter(Boolean);
@@ -494,24 +499,15 @@ function resolveSkillsDir(target, config) {
   }
   return void 0;
 }
-function normalizeTarget(target) {
-  return target.trim();
-}
-function getRawTargetConfig(target) {
-  return getAgentConfig(target);
-}
 function getSupportedTargets() {
-  return getAgentIds().filter((target) => {
-    const config = getRawTargetConfig(target);
-    return Boolean(resolveSkillsDir(target, config));
-  }).sort((a, b) => a.localeCompare(b));
+  return getAgentIds().filter((target) => Boolean(resolveSkillsDir(target, getAgentConfig(target)))).sort((a, b) => a.localeCompare(b));
 }
 function resolveAgentTargetConfig(target) {
-  const normalized = normalizeTarget(target);
+  const normalized = target.trim();
   if (!normalized) {
     return void 0;
   }
-  const config = getRawTargetConfig(normalized);
+  const config = getAgentConfig(normalized);
   const skillsDir = resolveSkillsDir(normalized, config);
   if (!config || !skillsDir) {
     return void 0;
@@ -523,11 +519,11 @@ function resolveAgentTargetConfig(target) {
   };
 }
 function validateTargets(targets) {
-  const uniqueTargets = Array.from(new Set(targets.map(normalizeTarget).filter(Boolean)));
+  const uniqueTargets = Array.from(new Set(targets.map((target) => target.trim()).filter(Boolean)));
   const valid = [];
   const invalid = [];
   for (const target of uniqueTargets) {
-    const config = getRawTargetConfig(target);
+    const config = getAgentConfig(target);
     if (!config) {
       invalid.push({
         target,
@@ -562,6 +558,24 @@ const MANAGED_HINT_START = "<!-- nuxt-skill-hub:start -->";
 const MANAGED_HINT_END = "<!-- nuxt-skill-hub:end -->";
 const SKILL_NAME_MAX_LENGTH = 64;
 const SKILL_NAME_PATTERN = /^[a-z0-9-]+$/;
+async function mapWithConcurrency(items, concurrency, mapper) {
+  if (!items.length) {
+    return [];
+  }
+  const results = [];
+  let nextIndex = 0;
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
+    while (true) {
+      const index = nextIndex++;
+      if (index >= items.length) {
+        return;
+      }
+      results[index] = await mapper(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
 async function pathExists(path) {
   try {
     await promises.access(path);
@@ -746,6 +760,22 @@ async function discoverInstalledPackageFromDirectory(directory) {
   }
   return readInstalledPackageMetadata(packageJsonPath);
 }
+async function collectInstalledModulePackages(modules, rootDir) {
+  const specifiers = Array.from(new Set(
+    (modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry))
+  ));
+  const resolved = await Promise.all(
+    specifiers.map((specifier) => discoverInstalledPackageFromSpecifier(specifier, rootDir))
+  );
+  const seenPackageRoots = /* @__PURE__ */ new Set();
+  const packages = [];
+  for (const pkg of resolved) {
+    if (!pkg || seenPackageRoots.has(pkg.packageRoot)) continue;
+    seenPackageRoots.add(pkg.packageRoot);
+    packages.push(pkg);
+  }
+  return packages;
+}
 async function readInstalledPackageMetadata(packageJsonPath, fallbackSpecifier) {
   const pkg = await readPackageJSON(packageJsonPath);
   return {
@@ -863,15 +893,15 @@ async function validateContribution(contribution) {
   };
 }
 async function validateResolvedContributions(contributions) {
+  const validations = await Promise.all(contributions.map(validateContribution));
   const valid = [];
   const issues = [];
-  for (const contribution of contributions) {
-    const validation = await validateContribution(contribution);
-    if (!validation.issues.length) {
-      valid.push(validation.contribution);
+  for (const validation of validations) {
+    if (validation.issues.length) {
+      issues.push(...validation.issues);
       continue;
     }
-    issues.push(...validation.issues);
+    valid.push(validation.contribution);
   }
   return {
     contributions: sortAndDedupeContributions(valid),
@@ -1040,7 +1070,7 @@ function formatConflictWarning(conflict) {
   return `Found ${conflict.skillNames.length} standalone skill(s) that may conflict with nuxt-skill-hub: ${conflict.skillNames.join(", ")} (global: ${conflict.globalDir}). Remove with: npx skills remove --global`;
 }
 
-const GITHUB_OVERRIDES = [
+const PACKAGE_OVERRIDES = [
   {
     packageName: "@nuxt/ui",
     repo: "nuxt/ui",
@@ -1054,10 +1084,15 @@ const GITHUB_OVERRIDES = [
     ref: "main",
     path: "skills/vueuse-functions",
     skillName: "vueuse-functions"
+  },
+  {
+    packageName: "docus",
+    repo: "nuxt-content/docus",
+    docsUrls: ["https://docus.dev/"]
   }
 ];
-function findGitHubOverride(packageName) {
-  return GITHUB_OVERRIDES.find((entry) => entry.packageName === packageName);
+function findPackageOverride(packageName) {
+  return PACKAGE_OVERRIDES.find((entry) => entry.packageName === packageName);
 }
 
 const GITHUB_API_BASE = "https://api.github.com";
@@ -1065,6 +1100,8 @@ const UNGH_API_BASE = "https://ungh.cc";
 const githubDirectoryCache = /* @__PURE__ */ new Map();
 const githubDefaultBranchCache = /* @__PURE__ */ new Map();
 const githubFileTextCache = /* @__PURE__ */ new Map();
+const urlTextCache = /* @__PURE__ */ new Map();
+const urlBytesCache = /* @__PURE__ */ new Map();
 function githubFetchOptions(timeoutMs) {
   return {
     timeout: timeoutMs,
@@ -1074,6 +1111,9 @@ function githubFetchOptions(timeoutMs) {
     }
   };
 }
+function fetchStatus(error) {
+  return typeof error === "object" && error && "status" in error ? Number(error.status) : void 0;
+}
 function encodeGitHubPath(path) {
   return path.split("/").filter(Boolean).map((segment) => encodeURIComponent(segment)).join("/");
 }
@@ -1180,16 +1220,378 @@ async function fetchGitHubFileText(repo, ref, filePath, timeoutMs) {
       );
       return { ok: true, data };
     } catch (error) {
-      const status = typeof error === "object" && error && "status" in error ? Number(error.status) : void 0;
       return {
         ok: false,
-        status,
+        status: fetchStatus(error),
+        error: error.message
+      };
+    }
+  });
+}
+async function fetchUrlText(url, timeoutMs) {
+  return await memoize(urlTextCache, url, async () => {
+    try {
+      const data = await ofetch(url, {
+        ...githubFetchOptions(timeoutMs),
+        responseType: "text"
+      });
+      return { ok: true, data };
+    } catch (error) {
+      return {
+        ok: false,
+        status: fetchStatus(error),
+        error: error.message
+      };
+    }
+  });
+}
+async function fetchUrlJson(url, timeoutMs) {
+  const text = await fetchUrlText(url, timeoutMs);
+  if (!text.ok) {
+    return {
+      ok: false,
+      status: text.status,
+      error: text.error
+    };
+  }
+  try {
+    return {
+      ok: true,
+      data: JSON.parse(text.data || "")
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error.message
+    };
+  }
+}
+async function fetchUrlBytes(url, timeoutMs) {
+  return await memoize(urlBytesCache, url, async () => {
+    try {
+      const data = await ofetch(url, {
+        ...githubFetchOptions(timeoutMs),
+        responseType: "arrayBuffer"
+      });
+      return {
+        ok: true,
+        data: new Uint8Array(data)
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        status: fetchStatus(error),
         error: error.message
       };
     }
   });
 }
 
+const WELL_KNOWN_DISCOVERY_V2_SCHEMA = "https://schemas.agentskills.io/discovery/0.2.0/schema.json";
+const WELL_KNOWN_DISCOVERY_V2_INDEX_PATH = "/.well-known/agent-skills/index.json";
+function makeSkip$1(packageName, skillName, reason) {
+  return {
+    packageName,
+    skillName,
+    reason,
+    sourceKind: "wellKnown"
+  };
+}
+function normalizeHttpUrl$1(url) {
+  const trimmed = url?.trim();
+  if (!trimmed) {
+    return void 0;
+  }
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? parsed.toString() : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function normalizeHostname(hostname) {
+  return hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+}
+function parseIpv4(hostname) {
+  const parts = hostname.split(".");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const octets = parts.map((part) => {
+    if (!/^\d+$/.test(part)) {
+      return Number.NaN;
+    }
+    return Number(part);
+  });
+  if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+    return null;
+  }
+  return octets;
+}
+function isPrivateIpv4(hostname) {
+  const octets = parseIpv4(normalizeHostname(hostname));
+  if (!octets) {
+    return false;
+  }
+  const [a, b] = octets;
+  return a === 0 || a === 10 || a === 127 || a === 169 && b === 254 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a >= 224 && a <= 239 || a >= 240;
+}
+function isPrivateIpv6(hostname) {
+  const normalized = normalizeHostname(hostname);
+  return normalized === "::" || normalized === "::1" || normalized.startsWith("fc") || normalized.startsWith("fd") || normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb");
+}
+function isUnsafeHostname(hostname) {
+  const normalized = normalizeHostname(hostname);
+  if (normalized === "localhost" || normalized.endsWith(".localhost")) {
+    return true;
+  }
+  const ipVersion = isIP(normalized);
+  if (ipVersion === 4) {
+    return isPrivateIpv4(normalized);
+  }
+  if (ipVersion === 6) {
+    return isPrivateIpv6(normalized);
+  }
+  return false;
+}
+function isPublicDiscoveryBase(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:" || parsed.hostname === "github.com" || parseGitHubRepo(url) || isUnsafeHostname(parsed.hostname)) {
+      return false;
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isSameOriginUrl(url, baseUrl) {
+  return new URL(url).origin === new URL(baseUrl).origin;
+}
+function resolveSameOriginUrl(rawUrl, baseUrl) {
+  const trimmed = rawUrl.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    const resolved = new URL(trimmed, baseUrl);
+    if (!isSameOriginUrl(resolved.toString(), baseUrl) || isUnsafeHostname(resolved.hostname)) {
+      return null;
+    }
+    return resolved.toString();
+  } catch {
+    return null;
+  }
+}
+function docsBaseCandidates(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
+  const candidates = [
+    ...override?.docsUrls || [],
+    packageInfo.homepage || ""
+  ];
+  return [...new Set(candidates.map(normalizeHttpUrl$1).filter((url) => Boolean(url)).filter(isPublicDiscoveryBase))];
+}
+function normalizeDigest(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return /^sha256:[a-f0-9]{64}$/.test(trimmed) ? trimmed : null;
+}
+function sha256(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+async function writeSkillFile(root, relativePath, bytes) {
+  const destination = join(root, relativePath);
+  await ensureDir(dirname(destination));
+  await promises.writeFile(destination, bytes);
+}
+function contributionFor(input) {
+  const sourceRepo = parseGitHubRepo(input.packageInfo.repository);
+  return normalizeContribution({
+    packageName: input.packageInfo.packageName,
+    version: input.packageInfo.version,
+    skillName: input.skillName,
+    description: input.description,
+    sourceKind: "wellKnown",
+    sourceRepo: sourceRepo || void 0,
+    sourcePath: input.indexUrl,
+    repoUrl: sourceRepo ? `https://github.com/${sourceRepo}` : void 0,
+    docsUrl: input.docsUrl,
+    official: true,
+    resolver: input.resolver,
+    forceIncludeScripts: true
+  }, input.targetDir, join(input.targetDir, ".."));
+}
+async function materializeV2Skill(input) {
+  const skillName = typeof input.entry.name === "string" ? input.entry.name.trim() : "";
+  if (!isValidSkillName(skillName)) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName || "entry", "well-known v2 skill name is invalid") };
+  }
+  const description = typeof input.entry.description === "string" ? input.entry.description.trim() : "";
+  if (!description) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a description") };
+  }
+  const type = typeof input.entry.type === "string" ? input.entry.type.trim() : "";
+  if (type === "archive") {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "archive artifacts are not supported yet") };
+  }
+  if (type !== "skill-md") {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, `unsupported well-known v2 skill type "${type || "unknown"}"`) };
+  }
+  if (typeof input.entry.url !== "string" || !input.entry.url.trim()) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a URL") };
+  }
+  const digest = normalizeDigest(input.entry.digest);
+  if (!digest) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill is missing a valid sha256 digest") };
+  }
+  const skillUrl = resolveSameOriginUrl(input.entry.url, input.indexUrl);
+  if (!skillUrl) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill URL must stay on the discovery origin") };
+  }
+  const response = await fetchUrlBytes(skillUrl, input.timeoutMs);
+  if (!response.ok || !response.data) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "failed to fetch well-known v2 skill artifact") };
+  }
+  if (sha256(response.data) !== digest) {
+    return { skipped: makeSkip$1(input.packageInfo.packageName, skillName, "well-known v2 skill digest mismatch") };
+  }
+  const origin = new URL(input.docsUrl).origin;
+  const targetDir = join(
+    input.cacheRoot,
+    "well-known",
+    "rfc",
+    sanitizeSegment(origin),
+    sanitizeSegment(input.packageInfo.packageName),
+    sanitizeSegment(input.packageInfo.version || "unknown"),
+    sanitizeSegment(skillName)
+  );
+  await emptyDir(targetDir);
+  await writeSkillFile(targetDir, "SKILL.md", response.data);
+  return {
+    contribution: contributionFor({
+      packageInfo: input.packageInfo,
+      targetDir,
+      skillName,
+      description,
+      docsUrl: input.docsUrl,
+      resolver: "wellKnownV2",
+      indexUrl: input.indexUrl
+    })
+  };
+}
+async function resolveV2Index(input) {
+  const skipped = [];
+  const contributions = [];
+  if (!Array.isArray(input.index.skills)) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known v2 index is missing a skills array")]
+    };
+  }
+  for (const rawEntry of input.index.skills) {
+    if (!rawEntry || typeof rawEntry !== "object") {
+      skipped.push(makeSkip$1(input.packageInfo.packageName, "entry", "well-known v2 skill entry must be an object"));
+      continue;
+    }
+    const materialized = await materializeV2Skill({
+      packageInfo: input.packageInfo,
+      entry: rawEntry,
+      indexUrl: input.indexUrl,
+      docsUrl: input.docsUrl,
+      cacheRoot: input.cacheRoot,
+      timeoutMs: input.timeoutMs
+    });
+    if (materialized?.contribution) {
+      contributions.push(materialized.contribution);
+    }
+    if (materialized?.skipped) {
+      skipped.push(materialized.skipped);
+    }
+  }
+  return { contributions, issues: [], skipped };
+}
+async function resolveIndex(input) {
+  const response = await fetchUrlJson(input.indexUrl, input.timeoutMs);
+  if (!response.ok) {
+    if (response.status === 404) {
+      return null;
+    }
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, `failed to fetch well-known index ${input.indexUrl}`)]
+    };
+  }
+  const index = response.data;
+  if (!index || typeof index !== "object") {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known index must be an object")]
+    };
+  }
+  if (index.$schema === WELL_KNOWN_DISCOVERY_V2_SCHEMA) {
+    return await resolveV2Index({
+      ...input,
+      index
+    });
+  }
+  if (typeof index.$schema === "string" && index.$schema) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, `unsupported well-known schema "${index.$schema}"`)]
+    };
+  }
+  return {
+    contributions: [],
+    issues: [],
+    skipped: [makeSkip$1(input.packageInfo.packageName, input.packageInfo.packageName, "well-known index is missing the v2 schema")]
+  };
+}
+async function resolveViaWellKnown(packageInfo, cacheRoot, timeoutMs) {
+  const bases = docsBaseCandidates(packageInfo);
+  const skipped = [];
+  const issues = [];
+  for (const docsUrl of bases) {
+    const indexUrl = new URL(WELL_KNOWN_DISCOVERY_V2_INDEX_PATH, docsUrl).toString();
+    const result = await resolveIndex({
+      packageInfo,
+      indexUrl,
+      docsUrl,
+      cacheRoot,
+      timeoutMs
+    });
+    if (!result) {
+      continue;
+    }
+    issues.push(...result.issues);
+    skipped.push(...result.skipped);
+    if (result.contributions.length) {
+      return {
+        contributions: result.contributions,
+        issues,
+        skipped
+      };
+    }
+  }
+  if (!bases.length) {
+    return {
+      contributions: [],
+      issues: [],
+      skipped: []
+    };
+  }
+  return {
+    contributions: [],
+    issues,
+    skipped
+  };
+}
+
 function makeSkip(packageName, skillName, reason, sourceKind) {
   return {
     packageName,
@@ -1231,8 +1633,14 @@ function normalizeHttpUrl(url) {
     return void 0;
   }
 }
+function resolveDocsUrl(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
+  const overrideDocsUrl = override?.docsUrls?.map(normalizeHttpUrl).find(Boolean);
+  return overrideDocsUrl || normalizeHttpUrl(packageInfo.homepage);
+}
 function resolveRepositoryUrl(packageInfo) {
-  const sourceRepo = parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
+  const override = findPackageOverride(packageInfo.packageName);
+  const sourceRepo = override?.repo || parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
   if (sourceRepo) {
     return {
       sourceRepo,
@@ -1304,18 +1712,9 @@ async function materializeCandidate(packageInfo, candidate, cacheRoot) {
     forceIncludeScripts: true
   }, targetDir, join(targetDir, ".."));
 }
-async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
-  const issues = [];
-  const skipped = [];
-  const override = findGitHubOverride(packageInfo.packageName);
+function createGitHubResolveContext(packageInfo) {
+  const override = findPackageOverride(packageInfo.packageName);
   const repo = override?.repo || parseGitHubRepo(packageInfo.repository) || parseGitHubRepo(packageInfo.homepage);
-  if (!repo) {
-    return {
-      contributions: [],
-      issues,
-      skipped: [makeSkip(packageInfo.packageName, override?.skillName || packageInfo.packageName, "No GitHub repository metadata found", "github")]
-    };
-  }
   const refs = dedupe([
     override?.ref || "",
     packageInfo.version ? `v${packageInfo.version}` : "",
@@ -1335,35 +1734,89 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
       ];
     })
   ]);
-  const tryResolveForRef = async (ref, allowTreeLookup) => {
-    const packageJson = await fetchGitHubFileText(repo, ref, "package.json", timeoutMs);
-    if (packageJson.ok && packageJson.data) {
-      try {
-        const parsed = JSON.parse(packageJson.data);
-        const remoteSkills = parseAgentSkillDeclarations(parsed, packageInfo.packageName, "github");
-        issues.push(...remoteSkills.issues);
-        for (const skill of remoteSkills.skills) {
-          const resolved = await materializeCandidate(packageInfo, {
-            skillName: skill.name,
-            sourcePath: skill.path,
-            sourceKind: "github",
-            sourceRepo: repo,
-            sourceRef: ref,
-            official: true,
-            resolver: "agentsField"
-          }, cacheRoot);
-          if (resolved) {
-            return [resolved];
-          }
-        }
-      } catch {
-        issues.push(createValidationIssue(packageInfo.packageName, packageInfo.packageName, "Failed to parse remote package.json", "github"));
+  return {
+    issues: [],
+    skipped: [],
+    override,
+    repo: repo || void 0,
+    refs,
+    pathCandidates
+  };
+}
+async function resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs) {
+  if (!context.repo) {
+    return null;
+  }
+  const packageJson = await fetchGitHubFileText(context.repo, ref, "package.json", timeoutMs);
+  if (!packageJson.ok || !packageJson.data) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(packageJson.data);
+    const remoteSkills = parseAgentSkillDeclarations(parsed, packageInfo.packageName, "github");
+    context.issues.push(...remoteSkills.issues);
+    for (const skill of remoteSkills.skills) {
+      const resolved = await materializeCandidate(packageInfo, {
+        skillName: skill.name,
+        sourcePath: skill.path,
+        sourceKind: "github",
+        sourceRepo: context.repo,
+        sourceRef: ref,
+        official: true,
+        resolver: "agentsField"
+      }, cacheRoot);
+      if (resolved) {
+        return [resolved];
       }
     }
-    if (!allowTreeLookup) {
-      return null;
+  } catch {
+    context.issues.push(createValidationIssue(packageInfo.packageName, packageInfo.packageName, "Failed to parse remote package.json", "github"));
+  }
+  return null;
+}
+async function resolveViaGitHubAgents(packageInfo, cacheRoot, timeoutMs) {
+  const context = createGitHubResolveContext(packageInfo);
+  if (!context.repo) {
+    return {
+      contributions: [],
+      issues: context.issues,
+      skipped: []
+    };
+  }
+  for (const ref of context.refs) {
+    const resolved = await resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
+    }
+  }
+  const fallbackRefs = dedupe([
+    await fetchGitHubDefaultBranch(context.repo, timeoutMs) || "",
+    "main",
+    "master"
+  ]);
+  for (const ref of fallbackRefs) {
+    const resolved = await resolveAgentSkillsForRef(packageInfo, context, ref, cacheRoot, timeoutMs);
+    if (resolved?.length) {
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
     }
-    const skillsDirs = await listGitHubDirectory(repo, ref, "skills", timeoutMs);
+  }
+  return {
+    contributions: [],
+    issues: context.issues,
+    skipped: context.skipped
+  };
+}
+async function resolveViaGitHubHeuristics(packageInfo, cacheRoot, timeoutMs) {
+  const context = createGitHubResolveContext(packageInfo);
+  if (!context.repo) {
+    return {
+      contributions: [],
+      issues: context.issues,
+      skipped: [makeSkip(packageInfo.packageName, context.override?.skillName || packageInfo.packageName, "No GitHub repository metadata found", "github")]
+    };
+  }
+  const tryResolveForRef = async (ref, allowTreeLookup) => {
+    const skillsDirs = await listGitHubDirectory(context.repo, ref, "skills", timeoutMs) ;
     if (skillsDirs.length) {
       const contributions = [];
       for (const skillName of skillsDirs) {
@@ -1371,7 +1824,7 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
           skillName,
           sourcePath: `skills/${skillName}`,
           sourceKind: "github",
-          sourceRepo: repo,
+          sourceRepo: context.repo,
           sourceRef: ref,
           official: true,
           resolver: "githubHeuristic"
@@ -1384,13 +1837,13 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
         return contributions;
       }
     }
-    for (const path of pathCandidates) {
-      const candidateSkillName = override?.path && path === override.path ? override.skillName || path.split("/").pop() || packageInfo.packageName : path.split("/").pop() || packageInfo.packageName;
+    for (const path of context.pathCandidates) {
+      const candidateSkillName = context.override?.path && path === context.override.path ? context.override.skillName || path.split("/").pop() || packageInfo.packageName : path.split("/").pop() || packageInfo.packageName;
       const resolved = await materializeCandidate(packageInfo, {
         skillName: candidateSkillName,
         sourcePath: path,
         sourceKind: "github",
-        sourceRepo: repo,
+        sourceRepo: context.repo,
         sourceRef: ref,
         official: true,
         resolver: "githubHeuristic"
@@ -1401,39 +1854,33 @@ async function resolveViaGitHub(packageInfo, cacheRoot, timeoutMs) {
     }
     return null;
   };
-  for (const ref of refs) {
-    const resolved = await tryResolveForRef(ref, false);
-    if (resolved?.length) {
-      return { contributions: resolved, issues, skipped };
-    }
-  }
   const fallbackRefs = dedupe([
-    await fetchGitHubDefaultBranch(repo, timeoutMs) || "",
+    await fetchGitHubDefaultBranch(context.repo, timeoutMs) || "",
     "main",
     "master"
   ]);
   for (const ref of fallbackRefs) {
-    const resolved = await tryResolveForRef(ref, true);
+    const resolved = await tryResolveForRef(ref);
     if (resolved?.length) {
-      return { contributions: resolved, issues, skipped };
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
     }
   }
-  for (const ref of refs) {
-    const resolved = await tryResolveForRef(ref, true);
+  for (const ref of context.refs) {
+    const resolved = await tryResolveForRef(ref);
     if (resolved?.length) {
-      return { contributions: resolved, issues, skipped };
+      return { contributions: resolved, issues: context.issues, skipped: context.skipped };
     }
   }
-  skipped.push(makeSkip(packageInfo.packageName, override?.skillName || packageInfo.packageName, "No GitHub skill found using configured refs and path heuristics", "github"));
+  context.skipped.push(makeSkip(packageInfo.packageName, context.override?.skillName || packageInfo.packageName, "No GitHub skill found using configured refs and path heuristics", "github"));
   return {
     contributions: [],
-    issues,
-    skipped
+    issues: context.issues,
+    skipped: context.skipped
   };
 }
 async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
   const { repoUrl, sourceRepo } = resolveRepositoryUrl(packageInfo);
-  const docsUrl = normalizeHttpUrl(packageInfo.homepage);
+  const docsUrl = resolveDocsUrl(packageInfo);
   if (!repoUrl && !docsUrl) {
     return {
       contributions: [],
@@ -1505,26 +1952,46 @@ async function resolveViaMetadataRouter(packageInfo, cacheRoot) {
   };
 }
 async function resolveRemoteContributionsForPackage(packageInfo, options) {
-  const githubResult = options.enableGithubLookup ? await resolveViaGitHub(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+  const githubAgentsResult = options.enableGithubLookup ? await resolveViaGitHubAgents(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
     contributions: [],
     issues: [],
     skipped: []
   };
-  if (githubResult.contributions.length) {
-    return githubResult;
+  if (githubAgentsResult.contributions.length) {
+    return githubAgentsResult;
+  }
+  const wellKnownResult = await resolveViaWellKnown(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs);
+  if (wellKnownResult.contributions.length) {
+    return {
+      contributions: wellKnownResult.contributions,
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues],
+      skipped: wellKnownResult.skipped
+    };
+  }
+  const githubHeuristicResult = options.enableGithubLookup ? await resolveViaGitHubHeuristics(packageInfo, options.cacheRoot, options.githubLookupTimeoutMs) : {
+    contributions: [],
+    issues: [],
+    skipped: []
+  };
+  if (githubHeuristicResult.contributions.length) {
+    return {
+      contributions: githubHeuristicResult.contributions,
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues],
+      skipped: wellKnownResult.skipped
+    };
   }
   const generatedResult = await resolveViaMetadataRouter(packageInfo, options.cacheRoot);
   if (generatedResult.contributions.length) {
     return {
       contributions: generatedResult.contributions,
-      issues: [...githubResult.issues, ...generatedResult.issues],
-      skipped: generatedResult.skipped
+      issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues, ...generatedResult.issues],
+      skipped: [...wellKnownResult.skipped, ...generatedResult.skipped]
     };
   }
   return {
     contributions: [],
-    issues: [...githubResult.issues, ...generatedResult.issues],
-    skipped: [...githubResult.skipped, ...generatedResult.skipped]
+    issues: [...githubAgentsResult.issues, ...wellKnownResult.issues, ...githubHeuristicResult.issues, ...generatedResult.issues],
+    skipped: [...wellKnownResult.skipped, ...githubHeuristicResult.skipped, ...generatedResult.skipped]
   };
 }
 
@@ -1582,6 +2049,7 @@ async function hashFileIfExists(path) {
   }
 }
 
+const HASH_READ_CONCURRENCY = 16;
 async function resolveManualContribution(rootDir, contribution) {
   const sourceDir = isAbsolute(contribution.sourceDir) ? contribution.sourceDir : resolve(rootDir, contribution.sourceDir);
   return normalizeContribution(contribution, sourceDir, sourceDir);
@@ -1633,8 +2101,6 @@ async function hashDirectoryTreeIfExists(rootPath) {
   if (!rootStat.isDirectory()) {
     return null;
   }
-  const hash = createHash("sha256");
-  hash.update("dir:.\n");
   const entries = await glob("**/*", {
     cwd: rootPath,
     dot: true,
@@ -1643,30 +2109,20 @@ async function hashDirectoryTreeIfExists(rootPath) {
     onlyFiles: false
   });
   entries.sort((a, b) => a.localeCompare(b));
-  for (const entry of entries) {
+  const chunkGroups = await mapWithConcurrency(entries, HASH_READ_CONCURRENCY, async (entry) => {
     const currentPath = join(rootPath, entry);
     const stat = await promises.lstat(currentPath);
-    const relativePath = relative(rootPath, currentPath).replaceAll("\\", "/");
-    if (stat.isSymbolicLink()) {
-      hash.update(`symlink:${relativePath}:`);
-      hash.update(await promises.readlink(currentPath));
-      hash.update("\n");
-      continue;
-    }
-    if (stat.isDirectory()) {
-      hash.update(`dir:${relativePath}
-`);
-      continue;
-    }
-    if (stat.isFile()) {
-      hash.update(`file:${relativePath}:`);
-      hash.update(await promises.readFile(currentPath));
-      hash.update("\n");
-      continue;
-    }
-    hash.update(`other:${relativePath}:${stat.mode}
-`);
-  }
+    const rel = relative(rootPath, currentPath).replaceAll("\\", "/");
+    if (stat.isSymbolicLink()) return [`symlink:${rel}:`, await promises.readlink(currentPath), "\n"];
+    if (stat.isDirectory()) return [`dir:${rel}
+`];
+    if (stat.isFile()) return [`file:${rel}:`, await promises.readFile(currentPath), "\n"];
+    return [`other:${rel}:${stat.mode}
+`];
+  });
+  const hash = createHash("sha256");
+  hash.update("dir:.\n");
+  for (const chunks of chunkGroups) for (const chunk of chunks) hash.update(chunk);
   return hash.digest("hex");
 }
 
@@ -1727,24 +2183,6 @@ function getPersistentCacheRoot(exportRoot) {
 function getCachedGeneratedSkillRoot(cacheRoot, skillName) {
   return join(cacheRoot, "generated", skillName);
 }
-async function mapWithConcurrency(items, concurrency, mapper) {
-  if (!items.length) {
-    return [];
-  }
-  const results = [];
-  let nextIndex = 0;
-  const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-    while (true) {
-      const index = nextIndex++;
-      if (index >= items.length) {
-        return;
-      }
-      results[index] = await mapper(items[index], index);
-    }
-  });
-  await Promise.all(workers);
-  return results;
-}
 function mergeSkipped(entries, keyFn) {
   const byKey = /* @__PURE__ */ new Map();
   for (const entry of entries) {
@@ -1781,17 +2219,13 @@ async function collectInstalledPackages(nuxt) {
       discoveries.push(discovered);
     }
   };
-  const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
-  const seenSpecifiers = Array.from(new Set(moduleSpecifiers));
-  for (const specifier of seenSpecifiers) {
-    addInstalledPackage(await discoverInstalledPackageFromSpecifier(specifier, nuxt.options.rootDir));
-  }
+  const modulePackages = await collectInstalledModulePackages(nuxt.options.modules, nuxt.options.rootDir);
+  for (const pkg of modulePackages) addInstalledPackage(pkg);
   const layerDirectories = Array.from(new Set(
     nuxt.options._layers.map((layer) => resolve(layer.cwd || layer.config.rootDir || "")).filter((layerDir) => layerDir && layerDir !== resolve(nuxt.options.rootDir))
   ));
-  for (const layerDirectory of layerDirectories) {
-    addInstalledPackage(await discoverInstalledPackageFromDirectory(layerDirectory));
-  }
+  const layerPackages = await Promise.all(layerDirectories.map((dir) => discoverInstalledPackageFromDirectory(dir)));
+  for (const pkg of layerPackages) addInstalledPackage(pkg);
   const localPackageSkills = await discoverLocalPackageSkills(nuxt.options.rootDir);
   if (localPackageSkills) {
     discoveries.push(localPackageSkills);
@@ -1971,23 +2405,14 @@ async function generateSkillTree(input) {
 function isCancelled(value) {
   return value === null || typeof value === "symbol";
 }
-const AI_AGENT_TARGET_MAP = {
-  codex: "codex",
-  claude: "claude-code",
-  gemini: "gemini-code-assist",
-  replit: "replit-agent"
-};
-function resolveAIGuidanceTarget(currentTarget, detectedAgent) {
-  if (currentTarget) {
-    return currentTarget;
-  }
-  if (!detectedAgent) {
-    return void 0;
-  }
-  return AI_AGENT_TARGET_MAP[detectedAgent];
-}
 function buildAIGuidance(currentTarget, detectedAgent) {
-  const target = resolveAIGuidanceTarget(currentTarget, detectedAgent);
+  const agentTargetMap = {
+    codex: "codex",
+    claude: "claude-code",
+    gemini: "gemini-code-assist",
+    replit: "replit-agent"
+  };
+  const target = currentTarget || (detectedAgent ? agentTargetMap[detectedAgent] : void 0);
   const sourceLabel = detectedAgent ? ` (${detectedAgent})` : "";
   const snippetLines = [
     "export default defineNuxtConfig({",
@@ -2068,15 +2493,7 @@ Let's configure AI agent skills for your Nuxt project.`
       }
     }
   }
-  const moduleSpecifiers = (nuxt.options.modules || []).map((entry) => extractModuleSpecifier(entry)).filter((entry) => Boolean(entry));
-  const uniqueSpecifiers = Array.from(new Set(moduleSpecifiers));
-  const installedModulePackages = [];
-  for (const specifier of uniqueSpecifiers) {
-    const pkg = await discoverInstalledPackageFromSpecifier(specifier, rootDir);
-    if (!pkg || pkg.packageName === "nuxt-skill-hub")
-      continue;
-    installedModulePackages.push(pkg.packageName);
-  }
+  const installedModulePackages = (await collectInstalledModulePackages(nuxt.options.modules, rootDir)).map((pkg) => pkg.packageName).filter((name) => name !== "nuxt-skill-hub");
   if (installedModulePackages.length) {
     consola.info(`Detected ${installedModulePackages.length} installed module package(s):`);
     for (const packageName of installedModulePackages) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-skill-hub",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Teach your AI agent the Nuxt way with best practices and module guidance.",
   "repository": {
     "type": "git",
@@ -61,11 +61,13 @@
     "dev:build": "nuxt-module-build build --stub --watch",
     "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare",
     "release": "bumpp --push --no-push-all",
+    "release:check-version": "node ./scripts/check-npm-version.mjs",
     "lint": "eslint .",
-    "test": "pnpm run dev:prepare && vitest run && pnpm run test:pack",
+    "test": "pnpm run dev:prepare && pnpm run docs:prepare && vitest run && pnpm run test:pack",
     "test:pack": "node ./scripts/check-packlist.mjs",
     "test:watch": "vitest watch",
     "test:types": "pnpm run dev:prepare && vue-tsc --noEmit",
+    "docs:prepare": "pnpm --dir docs exec nuxt prepare",
     "docs:typecheck": "pnpm --dir docs typecheck",
     "typecheck": "pnpm run test:types && pnpm run docs:typecheck"
   }