@heyclaude/mcp 0.2.0 → 0.3.0

package/src/submissions.js

@@ -1,8 +1,4 @@
 export const SUBMISSION_SITE_URL = "https://heyclau.de/submit";
-export const GITHUB_NEW_ISSUE_URL =
-  "https://github.com/JSONbored/awesome-claude/issues/new";
-
-const defaultLabels = ["content-submission", "needs-review"];
 
 function normalizeText(value) {
   return String(value || "").trim();
@@ -78,28 +74,31 @@ function isHttpsUrl(value) {
   }
 }
 
+const TRACKING_QUERY_KEYS = new Set([
+  "aff",
+  "affiliate",
+  "affiliate_id",
+  "campaign",
+  "coupon",
+  "irclickid",
+  "partner",
+  "referral",
+  "referral_code",
+  "via",
+]);
+
+function isTrackingQueryKey(key) {
+  const normalized = key.trim().toLowerCase();
+  return normalized.startsWith("utm_") || TRACKING_QUERY_KEYS.has(normalized);
+}
+
 function isLikelyAffiliateUrl(value) {
   const trimmed = normalizeText(value);
   if (!trimmed) return false;
   try {
     const url = new URL(trimmed);
-    const affiliateParams = new Set([
-      "aff",
-      "affiliate",
-      "affiliate_id",
-      "campaign",
-      "coupon",
-      "irclickid",
-      "partner",
-      "referral",
-      "referral_code",
-      "via",
-    ]);
     for (const key of url.searchParams.keys()) {
-      const normalized = key.trim().toLowerCase();
-      if (normalized.startsWith("utm_") || affiliateParams.has(normalized)) {
-        return true;
-      }
+      if (isTrackingQueryKey(key)) return true;
     }
   } catch {
     return false;
@@ -166,6 +165,32 @@ function compactWhitespace(value) {
   return output.trim();
 }
 
+function splitList(value) {
+  const items = [];
+  let current = "";
+  for (const char of String(value || "")) {
+    if (char === "\n" || char === ",") {
+      const next = current.trim();
+      if (next) items.push(next);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  const next = current.trim();
+  if (next) items.push(next);
+  return items;
+}
+
+function isIsoDate(value) {
+  const text = normalizeText(value);
+  if (text.length !== 10) return false;
+  return [...text].every((char, index) => {
+    if (index === 4 || index === 7) return char === "-";
+    return char >= "0" && char <= "9";
+  });
+}
+
 function tagsToText(value) {
   return Array.isArray(value)
     ? value.map(normalizeText).filter(Boolean).join(", ")
@@ -217,14 +242,6 @@ function modelFor(spec, category) {
   return spec?.categories?.[category] || null;
 }
 
-function templateFor(spec, category) {
-  return spec?.issueTemplates?.[category] || null;
-}
-
-function labelsFor(spec, category) {
-  return templateFor(spec, category)?.labels || defaultLabels;
-}
-
 function requiredFields(model) {
   return (model?.fields || [])
     .filter((field) => field.required)
@@ -235,6 +252,23 @@ function fieldLabels(model) {
   return new Map((model?.fields || []).map((field) => [field.id, field.label]));
 }
 
+function fieldOptions(model, fieldId) {
+  const field = (model?.fields || []).find((item) => item.id === fieldId);
+  return new Set((field?.options || []).map(normalizeLower).filter(Boolean));
+}
+
+function validateSelectOptions(model, normalized, errors) {
+  for (const field of model?.fields || []) {
+    if (!Array.isArray(field.options) || !field.options.length) continue;
+    const value = normalizeLower(normalized[field.id]);
+    if (!value) continue;
+    const validValues = new Set(field.options.map(normalizeLower));
+    if (!validValues.has(value)) {
+      errors.push(`Invalid ${field.id}: ${value}`);
+    }
+  }
+}
+
 function selectedCategory(spec, category) {
   const normalized = normalizeLower(category);
   return categoryKeys(spec).includes(normalized) ? normalized : "";
@@ -300,12 +334,21 @@ function validateAgainstSpec(spec, fields = {}) {
   if (normalized.brand_domain && !isCanonicalDomain(normalized.brand_domain)) {
     errors.push("brand_domain must be a canonical domain such as asana.com.");
   }
+
+  validateSelectOptions(model, normalized, errors);
+
   if (
     category === "skills" &&
     !normalizeText(normalized.install_command) &&
-    !normalizeText(normalized.download_url)
+    !normalizeText(normalized.download_url) &&
+    !normalizeText(normalized.github_url) &&
+    !normalizeText(normalized.docs_url) &&
+    !normalizeText(normalized.full_copyable_content) &&
+    !normalizeText(normalized.retrieval_sources)
   ) {
-    errors.push("Skills submissions require install_command or download_url.");
+    errors.push(
+      "Skills submissions require install_command, source URL, retrieval_sources, or full_copyable_content.",
+    );
   }
   if (category === "collections" && !normalizeText(normalized.items)) {
     errors.push("Collections submissions require items.");
@@ -313,6 +356,32 @@ function validateAgainstSpec(spec, fields = {}) {
   if (category === "guides" && !normalizeText(normalized.guide_content)) {
     errors.push("Guide submissions require guide_content.");
   }
+  if (category === "skills") {
+    const skillType = normalizeLower(normalized.skill_type);
+    const skillLevel = normalizeLower(normalized.skill_level);
+    const verifiedAt = normalizeText(normalized.verified_at);
+    const retrievalSources = normalizeText(normalized.retrieval_sources);
+    if (verifiedAt && !isIsoDate(verifiedAt)) {
+      errors.push("verified_at must use YYYY-MM-DD format.");
+    }
+    if (skillType === "capability-pack") {
+      if (!verifiedAt)
+        errors.push("capability-pack skills require verified_at.");
+      if (!retrievalSources) {
+        errors.push("capability-pack skills require retrieval_sources.");
+      }
+      if (skillLevel && skillLevel !== "expert") {
+        errors.push("capability-pack skills must use skill_level=expert.");
+      }
+    }
+    if (retrievalSources) {
+      for (const url of splitList(retrievalSources)) {
+        if (!isHttpsUrl(url)) {
+          errors.push(`retrieval_sources must use https URLs: ${url}`);
+        }
+      }
+    }
+  }
   if (!normalized.github_url && !normalized.docs_url) {
     warnings.push("No github_url/docs_url provided.");
   }
@@ -331,7 +400,7 @@ function validateAgainstSpec(spec, fields = {}) {
   };
 }
 
-export function buildIssueDraftFromSpec(spec, fields = {}) {
+export function buildPrDraftFromSpec(spec, fields = {}) {
   const validation = validateAgainstSpec(spec, fields);
   const category = validation.category;
   const model = modelFor(spec, category);
@@ -362,9 +431,8 @@ export function buildIssueDraftFromSpec(spec, fields = {}) {
   const label = modelLabel.endsWith("s") ? modelLabel.slice(0, -1) : modelLabel;
 
   return {
-    title: `Submit ${label}: ${validation.normalized.name || "New directory entry"}`,
+    title: `Add ${label}: ${validation.normalized.name || "New directory entry"}`,
     body,
-    labels: labelsFor(spec, category),
   };
 }
 
@@ -377,26 +445,16 @@ export function buildSubmissionUrlsFromSpec(spec, args = {}) {
   const fields = normalizeSubmissionFields(args.fields || {});
   const validation = validateAgainstSpec(spec, fields);
   const category = validation.category || fields.category || "";
-  const issueDraft = buildIssueDraftFromSpec(spec, fields);
-  const template = templateFor(spec, category)?.template || "submit-entry.md";
-
+  const prDraft = buildPrDraftFromSpec(spec, fields);
   const submitUrl = new URL(SUBMISSION_SITE_URL);
-  const issueUrl = new URL(GITHUB_NEW_ISSUE_URL);
-  issueUrl.searchParams.set("template", template);
 
   for (const [key, value] of Object.entries(fields)) {
     if (key === "source_url" && (fields.github_url || fields.docs_url))
       continue;
     setParam(submitUrl.searchParams, key, value);
-    if (key !== "source_url") setParam(issueUrl.searchParams, key, value);
   }
   if (category) {
     submitUrl.searchParams.set("category", category);
-    issueUrl.searchParams.set("category", category);
-  }
-  if (fields.name) {
-    issueUrl.searchParams.set("title", issueDraft.title);
-    issueUrl.searchParams.set("name", fields.name);
   }
 
   return {
@@ -405,17 +463,17 @@ export function buildSubmissionUrlsFromSpec(spec, args = {}) {
     category,
     slug: fields.slug || "",
     submitUrl: submitUrl.toString(),
-    githubIssueUrl: issueUrl.toString(),
-    issueDraft: args.includeIssueBody
-      ? issueDraft
-      : { title: issueDraft.title, labels: issueDraft.labels },
+    reviewUrl: submitUrl.toString(),
+    prDraft: args.includePrBody ? prDraft : { title: prDraft.title },
     validation: {
       errors: validation.errors,
       warnings: validation.warnings,
       missingRequiredFields: validation.missingRequiredFields || [],
     },
     reviewModel:
-      "Issue-first: maintainers review accepted submissions before an import PR is opened.",
+      "PR-first: source-backed submissions are opened as single-entry PRs. Content-only PRs may be merged automatically after content validation, Superagent, and private maintainer-agent review pass.",
+    artifactPolicy:
+      "Community ZIP/MCPB artifacts are review material only and are not published as HeyClaude-hosted downloads.",
   };
 }
 
@@ -437,16 +495,14 @@ export function getSubmissionSchemaFromSpec(spec, args = {}) {
     categories: categoryKeys(spec),
     category: category || "",
     schema: category ? spec.categories[category] : spec.categories,
-    issueTemplate: category
-      ? spec.issueTemplates?.[category]
-      : spec.issueTemplates,
+    prIntake: spec.prIntake || null,
   };
 }
 
 export function validateSubmissionDraftFromSpec(spec, args = {}) {
   const validation = validateAgainstSpec(spec, args.fields || {});
-  const issueDraft = validation.category
-    ? buildIssueDraftFromSpec(spec, validation.normalized)
+  const prDraft = validation.category
+    ? buildPrDraftFromSpec(spec, validation.normalized)
     : null;
 
   return {
@@ -459,16 +515,21 @@ export function validateSubmissionDraftFromSpec(spec, args = {}) {
     missingRequiredFields: validation.missingRequiredFields || [],
     errors: validation.errors,
     warnings: validation.warnings,
-    issuePreview: issueDraft
-      ? { title: issueDraft.title, labels: issueDraft.labels }
+    prPreview: prDraft
+      ? {
+          title: prDraft.title,
+        }
       : null,
     nextSteps: validation.valid
       ? [
           "Check for duplicate registry entries.",
-          "Open the generated HeyClaude submit URL or GitHub issue URL.",
-          "Maintainers review accepted submissions before an import PR is opened.",
+          "Open the generated HeyClaude submit URL and continue with GitHub.",
+          "Source-backed, non-artifact submissions are reviewed through the private PR gate.",
+          "Eligible content PRs may be merged automatically after validation, Superagent, and private maintainer-agent review pass.",
         ]
-      : ["Fix validation errors before opening a public submission issue."],
+      : ["Fix validation errors before opening a public submission PR."],
+    artifactPolicy:
+      "Do not request HeyClaude /downloads hosting for community-submitted ZIP/MCPB artifacts.",
   };
 }
 
@@ -539,6 +600,10 @@ function exampleValueForField(fieldId, category, label) {
       return "Claude Code, Codex, Cursor";
     case "prerequisites":
       return "- Node.js 20+\n- Claude-compatible MCP client";
+    case "safety_notes":
+      return "- Runs user-configured code with local workspace permissions";
+    case "privacy_notes":
+      return "- Reads local project files and may send selected context to the configured API";
     case "troubleshooting_section":
       return "If setup fails, verify the install command and source URL first.";
     case "installation_order":
@@ -576,6 +641,7 @@ function exampleForCategory(spec, category) {
     "install_command",
     "usage_snippet",
     "download_url",
+    "full_copyable_content",
     "guide_content",
     "items",
   ]) {
@@ -585,13 +651,14 @@ function exampleForCategory(spec, category) {
   return {
     category,
     label: model?.label || category,
-    template: model?.template || templateFor(spec, category)?.template || "",
+    template: model?.template || "",
     requiredFields: requiredFields(model),
     minimalFields,
     completeFields: fields,
     notes: [
       "Use canonical source URLs and avoid affiliate/referral links.",
-      "The generated issue draft is a maintainer-reviewed submission, not automatic publication.",
+      "The generated PR draft can become a reviewable submission after gates pass, but it is not automatic publication.",
+      "Community package archives are quarantine/review material, not public HeyClaude-hosted downloads.",
     ],
   };
 }
@@ -613,19 +680,19 @@ export function getSubmissionExamplesFromSpec(spec, args = {}) {
     ok: true,
     categories: categories.map((key) => exampleForCategory(spec, key)),
     reviewModel:
-      "Examples are draft helpers only; maintainers review accepted submissions before import.",
+      "Examples are draft helpers only; maintainers review generated PRs before merge.",
   };
 }
 
 export function prepareSubmissionDraftFromSpec(spec, args = {}) {
   const fields = normalizeSubmissionFields(args.fields || {});
   const validation = validateAgainstSpec(spec, fields);
-  const issueDraft = validation.category
-    ? buildIssueDraftFromSpec(spec, validation.normalized)
+  const prDraft = validation.category
+    ? buildPrDraftFromSpec(spec, validation.normalized)
     : null;
   const urls = buildSubmissionUrlsFromSpec(spec, {
     fields: validation.normalized,
-    includeIssueBody: true,
+    includePrBody: true,
   });
 
   return {
@@ -638,17 +705,21 @@ export function prepareSubmissionDraftFromSpec(spec, args = {}) {
     missingRequiredFields: validation.missingRequiredFields || [],
     errors: validation.errors,
     warnings: validation.warnings,
-    issueDraft,
+    prDraft: prDraft ? { ...prDraft } : null,
     submitUrl: urls.submitUrl,
-    githubIssueUrl: urls.githubIssueUrl,
+    reviewUrl: urls.reviewUrl,
     reviewChecklist: [
-      "Confirm category fit and required fields before opening the issue.",
+      "Confirm category fit and required fields before opening the PR.",
       "Check for existing registry entries with the same source, slug, or title.",
       "Verify source URLs, install commands, and copied content before maintainer approval.",
+      "Add safety_notes/privacy_notes when a submission runs code, handles credentials, reads local data, writes externally, or uses background workers.",
+      "Use source-backed or copyable-content submissions; do not request public /downloads hosting for community ZIPs.",
       "Disclose paid, sponsored, affiliate, or commercial content separately from free community submissions.",
     ],
     submissionPolicy:
-      "This tool prepares a review issue only. HeyClaude does not auto-publish MCP-submitted content.",
+      "This tool prepares a PR-first submission draft only. Eligible content-only PRs may be merged automatically after content validation, Superagent, and private maintainer-agent review pass; platform, workflow, package, and generated-artifact changes are never auto-merged by this path.",
+    artifactPolicy:
+      "Community ZIP/MCPB artifacts are quarantine/review material only. Maintainer-built packages are the only HeyClaude-hosted downloads.",
   };
 }
 
@@ -659,10 +730,17 @@ export function reviewSubmissionDraftFromSpec(spec, args = {}, entries = []) {
     slug: validation.normalized.slug,
     title: validation.normalized.title || validation.normalized.name,
     name: validation.normalized.name,
-    sourceUrl:
-      validation.normalized.github_url ||
-      validation.normalized.docs_url ||
+    // Forward every candidate URL the submission carries rather than picking a
+    // single winner via `||` — see `collectSubmissionCandidateUrls`. A
+    // submission with both `github_url` and `docs_url` was previously dropping
+    // the second candidate from duplicate detection.
+    sourceUrls: [
+      validation.normalized.github_url,
+      validation.normalized.docs_url,
       validation.normalized.source_url,
+      validation.normalized.download_url,
+      validation.normalized.website_url,
+    ].filter(Boolean),
     brandDomain: validation.normalized.brand_domain,
     limit: args.duplicateLimit || 5,
   };
@@ -670,7 +748,7 @@ export function reviewSubmissionDraftFromSpec(spec, args = {}, entries = []) {
   const recommendedAction = validation.valid
     ? duplicates.count > 0
       ? "review_possible_duplicate"
-      : "open_review_issue"
+      : "open_review_pr"
     : "fix_required_fields";
 
   return {
@@ -687,28 +765,118 @@ export function reviewSubmissionDraftFromSpec(spec, args = {}, entries = []) {
       "Schema-valid is not publish-valid; maintainer review is still required.",
       "Check category fit against the actual artifact, not only the submitter's selected category.",
       "Verify source availability, install commands, and any credential/payment-sensitive behavior.",
+      "Keep packages source-backed unless maintainers explicitly rebuild and verify a first-party artifact.",
       "Reject or request edits for affiliate/referral links, unsupported claims, or unclear paid/sponsored positioning.",
     ],
     nextSteps: validation.valid
       ? [
-          "Open or update the canonical GitHub submission issue.",
-          "Apply maintainer review labels only after source and duplicate checks.",
+          "Open or update the canonical single-entry GitHub submission PR.",
+          "Let the private gate apply review labels after source, duplicate, and safety checks.",
         ]
-      : ["Fix required fields and validation errors before opening an issue."],
+      : ["Fix required fields and validation errors before opening a PR."],
+    artifactPolicy:
+      "Community-submitted ZIP/MCPB packages must not be treated as trusted public downloads.",
   };
 }
 
-function entrySourceUrls(entry) {
-  return [
+// Normalize a URL for duplicate-detection matching. Lowercases scheme + host,
+// strips `www.`, drops `#hash`, drops `utm_*` and known affiliate/tracking
+// query params (so links shared with marketing parameters still match the
+// canonical form), and strips a trailing `/` on non-root paths. Returns "" for
+// unparseable input — unparseable URLs simply don't match anything, which is
+// safe (the slug/title/brand_domain matches still run).
+function normalizeSubmissionUrlForMatch(value) {
+  const trimmed = normalizeText(value);
+  if (!trimmed) return "";
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return "";
+  }
+  url.protocol = url.protocol.toLowerCase();
+  url.hostname = url.hostname.toLowerCase().replace(/^www\./, "");
+  url.hash = "";
+  const droppedKeys = [];
+  for (const key of url.searchParams.keys()) {
+    if (isTrackingQueryKey(key)) droppedKeys.push(key);
+  }
+  for (const key of droppedKeys) url.searchParams.delete(key);
+  // Normalize the pathname before serializing so a trailing `/` is stripped on
+  // non-root paths regardless of any query string. Checking the serialized
+  // string's `endsWith("/")` misses cases like
+  // `https://example.com/foo/?ref=x`, where the slash sits before the query and
+  // is never the last character — leaving it would break the match against the
+  // canonical `https://example.com/foo?ref=x`.
+  if (url.pathname !== "/" && url.pathname.endsWith("/")) {
+    url.pathname = url.pathname.slice(0, -1);
+  }
+  return url.toString();
+}
+
+// Every external-publisher URL field the indexed entry may carry. Includes
+// `downloadUrl`, `websiteUrl`, `githubUrl`, and `trustSignals.sourceUrls` —
+// each is a real entry field today and a duplicate that lives only on one of
+// them must still match a submitter's URL. Internal `url`/`canonicalUrl`/
+// `llmsUrl`/`apiUrl` stay in the list because a submitter who pastes the
+// HeyClaude canonical URL of an existing entry is still describing the same
+// resource and should be flagged as a duplicate.
+function collectEntrySourceUrls(entry) {
+  const candidates = [
     entry.documentationUrl,
     entry.repoUrl,
+    entry.githubUrl,
+    entry.websiteUrl,
+    entry.downloadUrl,
     entry.url,
     entry.canonicalUrl,
     entry.llmsUrl,
     entry.apiUrl,
-  ]
-    .map(normalizeText)
-    .filter(Boolean);
+  ];
+  const trustSourceUrls = entry?.trustSignals?.sourceUrls;
+  if (Array.isArray(trustSourceUrls)) {
+    for (const value of trustSourceUrls) candidates.push(value);
+  }
+  const normalized = new Set();
+  for (const candidate of candidates) {
+    const value = normalizeSubmissionUrlForMatch(candidate);
+    if (value) normalized.add(value);
+  }
+  return normalized;
+}
+
+// Collect every URL the caller has offered as a duplicate-search candidate.
+// Accepts the legacy scalar `sourceUrl`, the new `sourceUrls` array, and the
+// fielded `githubUrl`/`docsUrl`/`downloadUrl`/`websiteUrl` keys so callers
+// don't have to `||`-chain a single winner and silently drop the rest.
+function collectSubmissionCandidateUrls(args = {}) {
+  const candidates = [
+    args.sourceUrl,
+    args.githubUrl,
+    args.docsUrl,
+    args.downloadUrl,
+    args.websiteUrl,
+  ];
+  if (Array.isArray(args.sourceUrls)) {
+    for (const value of args.sourceUrls) candidates.push(value);
+  }
+  const normalized = new Set();
+  for (const candidate of candidates) {
+    const value = normalizeSubmissionUrlForMatch(candidate);
+    if (value) normalized.add(value);
+  }
+  return normalized;
+}
+
+// First URL that appears in both Sets, or "" if none. Returning the matched
+// URL (rather than just a boolean) lets callers surface which URL hit if they
+// ever want to extend the `reasons` payload — today the predicate path is
+// boolean-only, but the value is free.
+function findOverlappingSourceUrl(entryUrls, candidateUrls) {
+  for (const value of candidateUrls) {
+    if (entryUrls.has(value)) return value;
+  }
+  return "";
 }
 
 export function searchDuplicateEntries(entries = [], args = {}) {
@@ -717,7 +885,7 @@ export function searchDuplicateEntries(entries = [], args = {}) {
   const slug = normalizeLower(args.slug);
   const title = normalizeLower(args.title || args.name);
   const brandDomain = normalizeDomain(args.brandDomain);
-  const sourceUrl = normalizeText(args.sourceUrl);
+  const candidateUrls = collectSubmissionCandidateUrls(args);
 
   const matches = [];
   for (const entry of entries) {
@@ -728,7 +896,10 @@ export function searchDuplicateEntries(entries = [], args = {}) {
     if (brandDomain && normalizeDomain(entry.brandDomain) === brandDomain) {
       reasons.push("brand_domain");
     }
-    if (sourceUrl && entrySourceUrls(entry).includes(sourceUrl)) {
+    if (
+      candidateUrls.size > 0 &&
+      findOverlappingSourceUrl(collectEntrySourceUrls(entry), candidateUrls)
+    ) {
       reasons.push("source_url");
     }
 
@@ -779,7 +950,7 @@ export function getCategorySubmissionGuidanceFromSpec(spec, args = {}) {
         category: key,
         label: model?.label || key,
         description: model?.description || "",
-        template: model?.template || templateFor(spec, key)?.template || "",
+        template: model?.template || "",
         requiredFields: requiredFields(model),
         optionalFields: (model?.fields || [])
           .filter((field) => !field.required)