webmcp-gauge 0.1.0

package/core/cohort.test.mjs

@@ -0,0 +1,370 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  normalizeTargets,
+  capturedUrlsFrom,
+  remainingTargets,
+  robotsAllows,
+  toRecord,
+  toPublishable,
+  summarize,
+  attributeTools,
+  localDateStamp,
+  HARNESS_UA_SUFFIX,
+} from './cohort.mjs';
+
+/**
+ * The capture's whole claim is the date it was taken on, and this machine runs at
+ * UTC+5:30 — a run started at 00:30 local would be filed under yesterday if the
+ * stamp came from toISOString().
+ */
+test('the date stamp is local, not UTC', () => {
+  // 2026-09-02T00:30 in a +05:30 zone is 2026-09-01T19:00Z. The stamp must follow
+  // the operator's calendar, whatever the machine's offset happens to be.
+  const local = new Date(2026, 8, 2, 0, 30, 0);
+  assert.equal(localDateStamp(local), '2026-09-02');
+  assert.equal(localDateStamp(new Date(2026, 0, 5, 23, 59)), '2026-01-05', 'months and days are zero-padded');
+});
+
+test('a bare hostname becomes an https URL, and the project name defaults to the host', () => {
+  const [row] = normalizeTargets(['example.netlify.app']);
+  assert.equal(row.url, 'https://example.netlify.app/');
+  assert.equal(row.project, 'example.netlify.app');
+  assert.equal(row.repo, null);
+});
+
+test('the same page under two spellings is one capture, not two visits', () => {
+  const rows = normalizeTargets([
+    'https://a.example/demo/',
+    'https://a.example/demo',
+    'https://a.example/demo#tools',
+  ]);
+  assert.equal(rows.length, 1);
+  assert.deepEqual(rows[0].aliases, ['https://a.example/demo', 'https://a.example/demo']);
+});
+
+test('a query string is part of identity, because a variant is a different page', () => {
+  const rows = normalizeTargets(['https://a.example/t?variant=clean', 'https://a.example/t?variant=degraded']);
+  assert.equal(rows.length, 2);
+});
+
+test('an entry with no url, or a non-http scheme, is refused rather than skipped', () => {
+  assert.throws(() => normalizeTargets([{ project: 'x' }]), /has no url/);
+  assert.throws(() => normalizeTargets(['ftp://a.example/x']), /not http/);
+  assert.throws(() => normalizeTargets('not an array'), TypeError);
+});
+
+test('missing or empty robots.txt is permission, which is what the standard says', () => {
+  assert.equal(robotsAllows('', '/demo'), true);
+  assert.equal(robotsAllows(null, '/demo'), true);
+});
+
+test('a wildcard Disallow blocks, and an empty Disallow allows everything', () => {
+  assert.equal(robotsAllows('User-agent: *\nDisallow: /', '/demo'), false);
+  assert.equal(robotsAllows('User-agent: *\nDisallow:', '/demo'), true);
+});
+
+test('the longest matching rule wins, so a nested Allow beats a broad Disallow', () => {
+  const robots = 'User-agent: *\nDisallow: /private\nAllow: /private/public';
+  assert.equal(robotsAllows(robots, '/private/secret'), false);
+  assert.equal(robotsAllows(robots, '/private/public/page'), true);
+});
+
+test('a rule naming us specifically overrides the wildcard group entirely', () => {
+  const robots = 'User-agent: *\nDisallow: /\n\nUser-agent: webmcp-gauge\nDisallow: /admin';
+  assert.equal(robotsAllows(robots, '/demo'), true, 'our own group replaces the wildcard one');
+  assert.equal(robotsAllows(robots, '/admin/x'), false);
+});
+
+test('wildcards and end-anchors in patterns are honoured', () => {
+  assert.equal(robotsAllows('User-agent: *\nDisallow: /*.pdf$', '/files/a.pdf'), false);
+  assert.equal(robotsAllows('User-agent: *\nDisallow: /*.pdf$', '/files/a.pdf.html'), true);
+});
+
+test('comments and blank lines do not become rules', () => {
+  const robots = '# nothing to see\n\nUser-agent: *\n# Disallow: /\nAllow: /\n';
+  assert.equal(robotsAllows(robots, '/demo'), true);
+});
+
+const manifest = {
+  present: true,
+  settled: true,
+  inNavigator: false,
+  tools: [
+    {
+      name: 'sum_by_category',
+      description: 'Totals spending per category and optionally highlights one.',
+      inputSchema: { type: 'object', properties: { highlight: { type: 'string' } }, required: ['highlight'] },
+      inputSchemaWire: 'string',
+      annotations: { readOnlyHint: true },
+    },
+  ],
+};
+
+test('the local record keeps the manifest verbatim, because the text is the measured object', () => {
+  const record = toRecord({
+    target: { project: 'airlock', url: 'https://airlock.example/', repo: null, aliases: [] },
+    capturedAt: '2026-09-04T00:00:00.000Z',
+    status: 200,
+    finalUrl: 'https://airlock.example/',
+    title: 'Airlock',
+    manifest,
+  });
+
+  assert.equal(record.webmcp.tools[0].description, manifest.tools[0].description);
+  assert.equal(record.liveness.reachable, true);
+  assert.equal(record.liveness.redirected, false);
+  assert.equal(record.webmcp.toolCount, 1);
+  assert.equal(record.webmcp.registered, true);
+});
+
+/**
+ * The defect this guards against was found by the 2026-09-01 dry run, not by
+ * reasoning: document.modelContext exists on every page in a WebMCP-enabled
+ * browser, so "present" was true for example.com and for a 404 page.
+ */
+test('a page where only the browser API exists has not adopted WebMCP', () => {
+  const record = toRecord({
+    target: { project: 'example.com', url: 'https://example.com/', repo: null, aliases: [] },
+    capturedAt: 'now',
+    status: 200,
+    finalUrl: 'https://example.com/',
+    manifest: { present: true, settled: false, tools: [] },
+  });
+
+  assert.equal(record.webmcp.apiPresent, true, 'the browser fact is still recorded');
+  assert.equal(record.webmcp.registered, false, 'but it is not adoption');
+  assert.equal(record.webmcp.toolCount, 0);
+});
+
+test('a redirect is recorded as one, and a 4xx page registers nothing whatever its error document does', () => {
+  const target = { project: 'x', url: 'https://x.example/', repo: null, aliases: [] };
+  const moved = toRecord({ target, capturedAt: 'now', status: 200, finalUrl: 'https://y.example/' });
+  assert.equal(moved.liveness.redirected, true);
+
+  const gone = toRecord({ target, capturedAt: 'now', status: 404, finalUrl: 'https://x.example/', manifest });
+  assert.equal(gone.liveness.reachable, false);
+  assert.equal(gone.webmcp.registered, false);
+  assert.equal(gone.webmcp.toolCount, 0, 'a 404 page\u2019s tools are not the project\u2019s tools');
+  assert.deepEqual(gone.webmcp.tools, []);
+});
+
+test('the published row carries tool names and shapes but never a description', () => {
+  const record = toRecord({
+    target: { project: 'airlock', url: 'https://airlock.example/', repo: 'https://github.com/x/y', aliases: [] },
+    capturedAt: '2026-09-04T00:00:00.000Z',
+    status: 200,
+    finalUrl: 'https://airlock.example/',
+    title: 'Airlock',
+    manifest,
+  });
+  const published = toPublishable(record);
+
+  const serialized = JSON.stringify(published);
+  assert.ok(!serialized.includes('Totals spending'), 'a description must not leave this machine');
+  assert.equal(published.tools[0].name, 'sum_by_category');
+  assert.equal(published.tools[0].descriptionLength, manifest.tools[0].description.length);
+  assert.equal(published.tools[0].propertyCount, 1);
+  assert.equal(published.tools[0].requiredCount, 1);
+  assert.equal(published.tools[0].hasAnnotations, true);
+  assert.equal(published.usesWebmcp, true);
+  assert.equal(published.title, undefined, 'a page title is prose too, and is not published');
+});
+
+test('the census counts adoption, not browser support', () => {
+  const at = '2026-09-04T00:00:00.000Z';
+  const mk = (project, status, tools) =>
+    toRecord({
+      target: { project, url: `https://${project}.example/`, repo: null, aliases: [] },
+      capturedAt: at,
+      status,
+      finalUrl: `https://${project}.example/`,
+      // present: true everywhere, because that is what a WebMCP-enabled browser
+      // actually reports — the census must not be fooled by it.
+      manifest: { present: true, tools },
+    });
+
+  const summary = summarize([
+    mk('live-with-tools', 200, [{ name: 'a' }, { name: 'b' }]),
+    mk('live-registered-nothing', 200, []),
+    mk('dead-with-an-error-page', 404, [{ name: 'ghost' }]),
+  ]);
+
+  assert.equal(summary.projects, 3);
+  assert.equal(summary.reachable, 2);
+  assert.equal(summary.dead, 1);
+  assert.equal(summary.usingWebmcp, 1, 'one project registered a tool');
+  assert.equal(summary.reachableWithoutTools, 1);
+  assert.equal(summary.totalTools, 2);
+  assert.equal(summary.maxToolCount, 2);
+});
+
+/**
+ * The union decision, taken 2026-09-02 before the capture. A cross-origin embed
+ * with allow="tools" puts a tool in the browser's view and in nobody's
+ * getTools(), so "what this builder shipped" and "what an agent can call here"
+ * stop being the same number. Both are captured; neither is allowed to stand in
+ * for the other.
+ */
+const embedInputs = () => ({
+  target: { project: 'host', url: 'https://host.example/', repo: null, aliases: [] },
+  capturedAt: 'now',
+  status: 200,
+  finalUrl: 'https://host.example/',
+  manifest: { present: true, tools: [{ name: 'own_one', description: 'x' }] },
+  browserTools: [
+    { name: 'own_one', frameId: 'F1' },
+    {
+      name: 'embedded_pay',
+      frameId: 'F2',
+      stackTrace: { callFrames: [{ url: 'https://widget.example/w.js' }] },
+    },
+  ],
+  frames: [
+    { id: 'F1', origin: 'https://host.example' },
+    { id: 'F2', origin: 'https://widget.example' },
+  ],
+});
+
+const embedRecord = () => toRecord(embedInputs());
+
+test('a third party\u2019s tool is agent-visible but never credited to the page', () => {
+  const record = embedRecord();
+
+  assert.equal(record.webmcp.toolCount, 1, 'the page shipped one tool');
+  assert.equal(record.webmcp.agentToolCount, 2, 'an agent can call two');
+  assert.equal(record.webmcp.thirdPartyToolCount, 1);
+  assert.deepEqual(record.webmcp.divergence.onlyInBrowser, ['embedded_pay']);
+  assert.deepEqual(record.webmcp.divergence.onlyInPage, []);
+
+  const attributed = record.webmcp.attribution.find((t) => t.name === 'embedded_pay');
+  assert.equal(attributed.origin, 'https://widget.example');
+  assert.equal(attributed.sameOrigin, false);
+});
+
+test('the published row carries the counts but not a third party\u2019s identity', () => {
+  const published = toPublishable(embedRecord());
+
+  assert.equal(published.toolCount, 1);
+  assert.equal(published.agentVisibleToolCount, 2);
+  assert.equal(published.thirdPartyToolCount, 1);
+  assert.equal(published.viewsDiverge, true);
+  assert.ok(
+    !JSON.stringify(published).includes('widget.example'),
+    "a fourth party's origin must not appear in somebody else's published row"
+  );
+});
+
+test('a tool whose origin cannot be established is unattributed, not assumed to be the page\u2019s', () => {
+  const attributed = attributeTools([{ name: 'mystery', frameId: 'gone' }], [], 'https://host.example');
+  assert.equal(attributed[0].origin, null);
+  assert.equal(attributed[0].sameOrigin, null, 'null, not true');
+});
+
+test('no browser view means null throughout, never zero or an empty list', () => {
+  const record = toRecord({
+    target: { project: 'x', url: 'https://x.example/', repo: null, aliases: [] },
+    capturedAt: 'now',
+    status: 200,
+    finalUrl: 'https://x.example/',
+    manifest: { present: true, tools: [{ name: 'a' }] },
+    browserTools: null,
+  });
+
+  assert.equal(record.webmcp.agentTools, null);
+  assert.equal(record.webmcp.agentToolCount, null);
+  assert.equal(record.webmcp.divergence, null);
+  assert.equal(record.webmcp.thirdPartyToolCount, null);
+
+  const summary = summarize([record]);
+  assert.equal(summary.pagesWithAgentView, 0);
+  assert.equal(summary.totalAgentVisibleTools, null, 'a cohort with no browser view reports null, not 0');
+  assert.equal(summary.pagesWhereViewsDiverge, null);
+});
+
+test('the census reports agent-side totals separately from adoption', () => {
+  const summary = summarize([embedRecord()]);
+
+  assert.equal(summary.usingWebmcp, 1);
+  assert.equal(summary.totalTools, 1, 'adoption counts what the builder shipped');
+  assert.equal(summary.totalAgentVisibleTools, 2, 'reality counts what an agent can call');
+  assert.equal(summary.pagesWithThirdPartyTools, 1);
+  assert.equal(summary.pagesWhereViewsDiverge, 1);
+});
+
+/**
+ * Item 23 (2026-09-05): the agent view can be taken at the browser endpoint,
+ * and then the record has to say so — with the OOPIF session count attached,
+ * because a watch no out-of-process iframe ever attached to has measured
+ * auto-attach rather than the browser's view. From `agentToolCount` alone the
+ * two findings are identical; they are not the same claim.
+ */
+test('the record keeps how the agent view was taken, and defaults to null when unsaid', () => {
+  const watched = toRecord({
+    ...embedInputs(),
+    browserView: { endpoint: 'browser', oopiFrames: 1, attachedSessions: 3, toolSessions: 2 },
+  });
+  assert.deepEqual(watched.webmcp.browserView, {
+    endpoint: 'browser',
+    oopiFrames: 1,
+    attachedSessions: 3,
+    toolSessions: 2,
+  });
+
+  const unsaid = embedRecord();
+  assert.equal(unsaid.webmcp.browserView, null, 'older callers must not gain a made-up view description');
+});
+
+/**
+ * The resume rules, from the night of 2026-09-25/26 when a browser death and a
+ * machine sleep each stopped a full-corpus run and the URL subtraction ran
+ * twice by hand. A capture that cannot be repeated must be resumable in one
+ * command, and the subtraction must be exactly the file's canonical URLs
+ * against the fixture's canonical targets — no near-miss spellings.
+ */
+test('resume: captured urls parse out of an append-only snapshot, torn lines and all', () => {
+  const text = [
+    JSON.stringify({ project: 'a', url: 'https://a.example/' }),
+    '{"project":"torn",',
+    JSON.stringify({ project: 'b', url: 'https://b.example/' }),
+    '',
+  ].join('\n');
+
+  const captured = capturedUrlsFrom(text);
+  assert.equal(captured.size, 2, 'a torn final line must not poison the rest of the file');
+  assert.ok(captured.has('https://a.example/'));
+  assert.ok(captured.has('https://b.example/'));
+
+  assert.deepEqual([...capturedUrlsFrom('')], [], 'an empty file resumes everything');
+  assert.deepEqual([...capturedUrlsFrom(null)], [], 'a missing file resumes everything');
+});
+
+test('resume: remaining targets subtract exactly what the file already holds', () => {
+  const targets = normalizeTargets([
+    { url: 'https://a.example/' },
+    { url: 'https://b.example/#frag' },
+    { url: 'https://c.example/' },
+  ]);
+  const captured = capturedUrlsFrom(
+    `${JSON.stringify({ url: 'https://a.example/' })}\n${JSON.stringify({ url: 'https://b.example/' })}`
+  );
+
+  const remaining = remainingTargets(targets, captured);
+  assert.deepEqual(remaining.map((t) => t.url), ['https://c.example/']);
+
+  assert.throws(() => remainingTargets(targets, new Map()), TypeError, 'a Set is the contract');
+  assert.equal(remainingTargets([], new Set()).length, 0);
+});
+
+test('an empty cohort summarizes to zeroes rather than throwing', () => {
+  const summary = summarize([]);
+  assert.equal(summary.projects, 0);
+  assert.equal(summary.medianToolCount, null);
+  assert.equal(summary.maxToolCount, null);
+});
+
+test('the user agent identifies the harness and offers a contact, per the publishing policy', () => {
+  assert.match(HARNESS_UA_SUFFIX, /webmcp-gauge/);
+  assert.match(HARNESS_UA_SUFFIX, /github\.com/);
+});

package/core/gallery.mjs

@@ -0,0 +1,145 @@
+/**
+ * Turning a gallery page into a targets file: the parts that can be decided
+ * without a browser, and therefore tested before the one day they have to work.
+ *
+ * The gallery was still unpublished when this was written (2026-09-01: the page
+ * says "The hackathon managers haven't published this gallery yet"), so the DOM
+ * selectors cannot be verified yet and live in the runner behind a cascade. What
+ * *can* be settled now is the reasoning applied to whatever links come back:
+ * which link is the demo, which is the repo, and which are neither.
+ *
+ * Getting that wrong on the day is expensive in a specific way — a project whose
+ * GitHub URL is mistaken for its demo produces a "no tools registered" row, which
+ * is indistinguishable in the census from a project that genuinely shipped none.
+ */
+
+/** Hosts whose links are never the thing we want to measure. */
+const REPO_HOSTS = new Set(['github.com', 'gitlab.com', 'bitbucket.org', 'codeberg.org']);
+const VIDEO_HOSTS = new Set(['youtube.com', 'youtu.be', 'vimeo.com', 'loom.com']);
+const SOCIAL_HOSTS = new Set([
+  'twitter.com',
+  'x.com',
+  'linkedin.com',
+  'facebook.com',
+  'instagram.com',
+  'discord.com',
+  'discord.gg',
+  'reddit.com',
+  't.me',
+]);
+/** Package and doc hosts that appear on submissions but host no page to measure. */
+const ARTEFACT_HOSTS = new Set([
+  'npmjs.com',
+  'pypi.org',
+  'crates.io',
+  'chromewebstore.google.com',
+  'chrome.google.com',
+  'addons.mozilla.org',
+  'docs.google.com',
+  'drive.google.com',
+  'notion.so',
+  'devpost.com',
+  // Devpost's own chrome and asset hosts. Measured on a real project page
+  // (2026-09-01): its footer and sponsor rail offer devpost.team and a
+  // cloudfront asset URL, both of which classify as "demo" unless named here,
+  // and one of them would then be captured as somebody's submission.
+  'devpost.team',
+  'cloudfront.net',
+  'amazonaws.com',
+  'devpost-file-uploads.s3.amazonaws.com',
+]);
+
+const hostOf = (url) => {
+  try {
+    return new URL(url).host.replace(/^www\./, '').toLowerCase();
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * What kind of link this is. Deliberately coarse: the only decision downstream is
+ * "is this a page a browser can be pointed at to read a WebMCP manifest".
+ */
+export const classifyLink = (url) => {
+  const host = hostOf(url);
+  if (!host) return 'unusable';
+
+  const base = host.split('.').slice(-2).join('.');
+  if (REPO_HOSTS.has(base)) return 'repo';
+  if (VIDEO_HOSTS.has(base)) return 'video';
+  if (SOCIAL_HOSTS.has(base)) return 'social';
+  if (ARTEFACT_HOSTS.has(base) || ARTEFACT_HOSTS.has(host)) return 'artefact';
+  return 'demo';
+};
+
+/**
+ * One project's links reduced to one row for the snapshot, or a refusal.
+ *
+ * Ordering rule, stated because it decides the dataset: the **first** demo-class
+ * link wins. Devpost renders submission links in the order the entrant chose, and
+ * an entrant who lists their live site first meant it. Ties are not broken by
+ * cleverness — guessing which of two candidate URLs is "more live" would be an
+ * invented preference, and the runner records every candidate so a human can
+ * override one row rather than distrust all of them.
+ */
+export const pickTarget = ({ title, devpostUrl, links = [] }) => {
+  const classified = links
+    .map((link) => (typeof link === 'string' ? { url: link } : link))
+    .filter((link) => link && typeof link.url === 'string' && link.url.trim() !== '')
+    .map((link) => ({ url: link.url.trim(), label: link.label ?? null, kind: classifyLink(link.url.trim()) }));
+
+  const demos = classified.filter((l) => l.kind === 'demo');
+  const repos = classified.filter((l) => l.kind === 'repo');
+
+  return {
+    project: title?.trim() || hostOf(devpostUrl) || 'untitled',
+    devpostUrl: devpostUrl ?? null,
+    url: demos[0]?.url ?? null,
+    repo: repos[0]?.url ?? null,
+    otherDemoCandidates: demos.slice(1).map((l) => l.url),
+    rejected: classified.filter((l) => l.kind !== 'demo' && l.kind !== 'repo'),
+    // A submission with no page to visit is not an error and not a target: it is a
+    // row in the census that says so, and the reason has to survive to the report.
+    skipReason: demos.length === 0 ? 'no demo-class link on the submission' : null,
+  };
+};
+
+/**
+ * Devpost paginates its galleries with ?page=N, 1-indexed. Kept here so the page
+ * walk is a pure function of the base URL and can be tested without fetching.
+ */
+export const galleryPageUrl = (base, page) => {
+  const url = new URL(base);
+  if (page > 1) url.searchParams.set('page', String(page));
+  else url.searchParams.delete('page');
+  return url.href;
+};
+
+/**
+ * The harvest as it will be handed to `cohort-snapshot.mjs`, plus the audit trail
+ * of what was dropped. Both halves are written to disk: a targets file that is
+ * only the measurable rows, and a manifest of every decision made to get there.
+ */
+export const toHarvest = (picks, { source, harvestedAt }) => {
+  const usable = picks.filter((p) => !p.skipReason && p.url);
+  const skipped = picks.filter((p) => p.skipReason || !p.url);
+
+  return {
+    schema: 'webmcp-gauge/gallery-harvest/1',
+    source,
+    harvestedAt,
+    counts: {
+      projects: picks.length,
+      usable: usable.length,
+      skipped: skipped.length,
+      ambiguous: usable.filter((p) => p.otherDemoCandidates.length > 0).length,
+      withRepo: usable.filter((p) => p.repo).length,
+    },
+    targets: usable.map((p) => ({ project: p.project, url: p.url, repo: p.repo })),
+    skipped: skipped.map((p) => ({ project: p.project, devpostUrl: p.devpostUrl, reason: p.skipReason ?? 'no url' })),
+    ambiguous: usable
+      .filter((p) => p.otherDemoCandidates.length > 0)
+      .map((p) => ({ project: p.project, chosen: p.url, alsoOffered: p.otherDemoCandidates })),
+  };
+};

package/core/gallery.test.mjs

@@ -0,0 +1,128 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { classifyLink, pickTarget, galleryPageUrl, toHarvest } from './gallery.mjs';
+
+test('a repo host is a repo, however it is spelled', () => {
+  assert.equal(classifyLink('https://github.com/user/project'), 'repo');
+  assert.equal(classifyLink('https://www.github.com/user/project'), 'repo');
+  assert.equal(classifyLink('https://gitlab.com/user/project'), 'repo');
+});
+
+test('videos, socials and package pages are not pages to measure', () => {
+  assert.equal(classifyLink('https://youtu.be/abc123'), 'video');
+  assert.equal(classifyLink('https://www.youtube.com/watch?v=abc'), 'video');
+  assert.equal(classifyLink('https://x.com/someone/status/1'), 'social');
+  assert.equal(classifyLink('https://www.npmjs.com/package/thing'), 'artefact');
+  assert.equal(classifyLink('https://devpost.com/software/thing'), 'artefact');
+});
+
+/**
+ * Measured on a real project page (2026-09-01), where Devpost's own footer and
+ * sponsor rail offered these alongside the entrant's links. Left unnamed, each
+ * one classifies as a demo, and the first-wins rule would then record a sponsor's
+ * marketing site as somebody's submission.
+ */
+test("Devpost's own chrome and asset hosts are not somebody's submission", () => {
+  assert.equal(classifyLink('https://devpost.team/'), 'artefact');
+  assert.equal(classifyLink('https://d112y698adiu2z.cloudfront.net/photos/x.png'), 'artefact');
+  assert.equal(classifyLink('https://devpost-file-uploads.s3.amazonaws.com/x.pdf'), 'artefact');
+});
+
+test('anything else is a demo candidate, including subdomains of free hosting', () => {
+  assert.equal(classifyLink('https://my-app.netlify.app'), 'demo');
+  assert.equal(classifyLink('https://project.vercel.app/demo'), 'demo');
+  assert.equal(classifyLink('https://user.github.io/project'), 'demo', 'pages hosting is a live page, not a repo');
+});
+
+test('a malformed link is unusable rather than a demo', () => {
+  assert.equal(classifyLink('not a url'), 'unusable');
+  assert.equal(classifyLink(''), 'unusable');
+});
+
+test('the first demo link wins, and the repo is captured beside it', () => {
+  const pick = pickTarget({
+    title: '  Airlock  ',
+    devpostUrl: 'https://devpost.com/software/airlock',
+    links: [
+      'https://github.com/user/airlock',
+      'https://airlock-app.netlify.app',
+      'https://backup.example/airlock',
+      'https://youtu.be/demo',
+    ],
+  });
+
+  assert.equal(pick.project, 'Airlock');
+  assert.equal(pick.url, 'https://airlock-app.netlify.app');
+  assert.equal(pick.repo, 'https://github.com/user/airlock');
+  assert.deepEqual(pick.otherDemoCandidates, ['https://backup.example/airlock']);
+  assert.equal(pick.skipReason, null);
+});
+
+test('a submission with only a repo and a video is skipped with the reason recorded', () => {
+  const pick = pickTarget({
+    title: 'CLI thing',
+    devpostUrl: 'https://devpost.com/software/cli-thing',
+    links: ['https://github.com/user/cli', 'https://youtu.be/x'],
+  });
+
+  assert.equal(pick.url, null);
+  assert.equal(pick.repo, 'https://github.com/user/cli');
+  assert.match(pick.skipReason, /no demo-class link/);
+});
+
+test('a project with no links at all is skipped rather than throwing', () => {
+  const pick = pickTarget({ title: 'Empty', devpostUrl: 'https://devpost.com/software/empty' });
+  assert.equal(pick.url, null);
+  assert.ok(pick.skipReason);
+});
+
+test('an untitled submission falls back to a name rather than an empty string', () => {
+  const pick = pickTarget({ title: '   ', devpostUrl: 'https://devpost.com/software/x', links: [] });
+  assert.equal(pick.project, 'devpost.com');
+});
+
+test('labelled links are accepted in object form as well as bare strings', () => {
+  const pick = pickTarget({
+    title: 'Mixed',
+    devpostUrl: null,
+    links: [{ url: 'https://demo.example', label: 'Try it out' }, 'https://github.com/a/b'],
+  });
+  assert.equal(pick.url, 'https://demo.example');
+  assert.equal(pick.repo, 'https://github.com/a/b');
+});
+
+test('page 1 carries no page parameter, and later pages do', () => {
+  const base = 'https://webmcp.devpost.com/project-gallery';
+  assert.equal(galleryPageUrl(base, 1), `${base}`);
+  assert.equal(galleryPageUrl(base, 3), `${base}?page=3`);
+});
+
+test('an existing query string on the gallery URL survives pagination', () => {
+  const base = 'https://webmcp.devpost.com/project-gallery?sort=recent';
+  assert.equal(galleryPageUrl(base, 2), 'https://webmcp.devpost.com/project-gallery?sort=recent&page=2');
+});
+
+test('the harvest separates what can be measured from what was dropped, and counts both', () => {
+  const picks = [
+    pickTarget({ title: 'A', devpostUrl: 'd/a', links: ['https://a.example', 'https://github.com/a/a'] }),
+    pickTarget({ title: 'B', devpostUrl: 'd/b', links: ['https://b.example', 'https://b2.example'] }),
+    pickTarget({ title: 'C', devpostUrl: 'd/c', links: ['https://github.com/c/c'] }),
+  ];
+  const harvest = toHarvest(picks, { source: 'https://webmcp.devpost.com/project-gallery', harvestedAt: 'now' });
+
+  assert.equal(harvest.counts.projects, 3);
+  assert.equal(harvest.counts.usable, 2);
+  assert.equal(harvest.counts.skipped, 1);
+  assert.equal(harvest.counts.ambiguous, 1, 'B offered two demo links');
+  assert.equal(harvest.counts.withRepo, 1);
+  assert.deepEqual(harvest.targets[0], { project: 'A', url: 'https://a.example', repo: 'https://github.com/a/a' });
+  assert.equal(harvest.skipped[0].project, 'C');
+  assert.deepEqual(harvest.ambiguous[0].alsoOffered, ['https://b2.example']);
+});
+
+test('an empty gallery harvests to an empty target list rather than a crash', () => {
+  const harvest = toHarvest([], { source: 'x', harvestedAt: 'now' });
+  assert.equal(harvest.counts.projects, 0);
+  assert.deepEqual(harvest.targets, []);
+});