Real card views (Clarity) + upvotes (giscus/Discussions)

[soyalejolopez]

What

Replaces the fabricated view/upvote counters on the resource cards with real data.

Views -> Microsoft Clarity

• build-stats.js pulls the Clarity Data Export API (URL dimension), accumulated daily and overlap-safe into traffic-data/clarity-views.json.
• GitHub traffic stays as a migration fallback so the 7 already-real cards never regress.
• Adds hash routing (index.html#<slug>) so Clarity attributes views per resource; deep-links + back/forward work.

Upvotes -> GitHub Discussions + giscus

• Detail modal mounts a live giscus embed (category "Resource Votes", specific term = slug), theme-synced to the dark toggle, re-mounted per open.
• Cards show a baked upvote count (GraphQL THUMBS_UP) only when a discussion exists; giscus lazily creates each thread on first reaction.
• Legacy hash-based fake generator and the Issues-based path fully removed.

Verified

• Headless smoke test: 0 app console errors; exactly 7 real view pills (powerclaw 1.2k, purview 656, ...); votes hidden until threads exist; deep-link #powerclaw-agent opens the modal; giscus resolves (repo-id/category-id) and reports lazy-create.

Required before all-card views light up

• Add repo secret CLARITY_API_TOKEN (Settings -> Secrets and variables -> Actions).
• Clarity coverage is forward-looking: it accumulates from deploy as visitors hit #slug URLs. Verify a few days in that Clarity records the URL fragment; if not, pivot to Clarity custom tags.

Co-authored-by: Copilot App

[gemini-code-assist]

Code Review

This pull request replaces the custom upvote system with a Giscus-based GitHub Discussions integration, updates the gallery routing to use URL hashes instead of query parameters, and introduces build scripts (build-stats.js and create-vote-discussions.js) to fetch and compile resource views and upvotes. Feedback on the new scripts highlights critical issues: collectDiscussions needs to return null instead of an empty array on failure to prevent wiping out existing upvote counts, the main loop should fall back to existing stats when upvote data is unavailable, and subtractClarityTotals should default previous uniques to zero to avoid omitting unique view counts for new resources.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If GITHUB_TOKEN is not set or if the GitHub API call fails, collectDiscussions currently returns an empty array []. This causes upvoteTotals to be empty, which subsequently overwrites and wipes out all existing upvote counts in resource-stats.json during the build. Returning null instead of [] allows the script to distinguish between a failed/skipped fetch and a successful fetch with zero discussions, enabling a fallback to the existing upvote counts.

async function collectDiscussions() {
  if (!githubToken) {
    console.log('GITHUB_TOKEN or GH_TOKEN is not set; skipping discussion upvotes.');
    return null;
  }

  const query = `query($owner:String!,$name:String!,$after:String) {
    repository(owner:$owner,name:$name) {
      discussions(first:100,after:$after) {
        pageInfo { hasNextPage endCursor }
        nodes {
          number
          url
          title
          category { name }
          reactionGroups { content reactors { totalCount } }
        } 
      }
    }
  }`;
  const discussions = [];
  let after = null;
  try {
    do {
      const data = await githubGraphql(query, { owner: 'microsoft', name: 'FastTrack', after });
      const connection = data?.repository?.discussions;
      if (!connection) throw new Error('GitHub did not return the discussions connection');
      discussions.push(...connection.nodes.filter(
        discussion => discussion?.category?.name === 'Resource Votes'
      ));
      after = connection.pageInfo.hasNextPage ? connection.pageInfo.endCursor : null;
    } while (after);
  } catch (error) {
    console.warn(`Warning: could not collect GitHub Discussions: ${error.message}`);
    return null;
  }
  return discussions;
}

[gemini-code-assist]

To prevent wiping out existing upvote counts when the GitHub Discussions fetch is skipped or fails, we should load the existing resource-stats.json and fall back to its upvote and discussion values if upvoteTotals is null.

const clarityState = readOptionalJson(clarityStatePath, { lastRun: '', days: {} });
if (!clarityState.days || typeof clarityState.days !== 'object') clarityState.days = {};

const clarityChanged = await updateClarityState(clarityState, knownSlugs);
const clarityViews = collectClarityViews(clarityState, knownSlugs);
const fallbackViews = collectFallbackViews();
const discussions = await collectDiscussions();
const upvoteTotals = discussions !== null ? mapDiscussions(discussions, knownSlugs, discussionConfig.map ?? {}) : null;
const existingStats = readOptionalJson(join(repositoryRoot, 'resource-stats.json'), { resources: {} });
const resources = {};
let viewCount = 0;
let upvoteCount = 0;

for (const resource of catalog.resources) {
  const stats = {};
  const clarity = clarityViews.get(resource.slug);
  let fallback;
  try {
    fallback = fallbackViews.get(new URL(resource.url).pathname);
  } catch {
    console.warn(`Warning: could not parse URL for ${resource.slug}.`);
  }

  // Clarity is authoritative once it has a nonzero cumulative total; legacy GitHub
  // path traffic only prevents existing resources from losing views during migration.
  const views = clarity?.views > 0 ? clarity : fallback;
  if (views) {
    Object.assign(stats, views);
    viewCount += 1;
  }

  const upvotes = upvoteTotals !== null
    ? upvoteTotals.get(resource.slug)
    : (existingStats.resources?.[resource.slug]?.upvotes !== undefined ? {
        upvotes: existingStats.resources[resource.slug].upvotes,
        discussion: existingStats.resources[resource.slug].discussion
      } : undefined);
  if (upvotes) {
    Object.assign(stats, upvotes);
    upvoteCount += 1;
  }

  if (Object.keys(stats).length > 0) resources[resource.slug] = stats;
}

[gemini-code-assist]

In subtractClarityTotals, if a resource is new or only has data in the larger window (meaning previous is undefined), the unique views count (entry.uniques) is completely omitted because of the strict previous?.uniques !== undefined check. Defaulting the previous uniques to 0 ensures that the unique count is correctly calculated and preserved.

    if (metrics.uniques !== undefined) {
      const uniques = metrics.uniques - (previous?.uniques ?? 0);
      if (uniques >= 0) entry.uniques = Math.round(uniques);
    }