Fix/sdk screenshot gate parity (#2164)

* fix(sdk): grade docs/screenshot.png exactly, like the registry gate * docs(wiki): document plugin MCP tools and the exact screenshot gate * test(sdk): cover the preflight screenshot probe
2026-10-18 21:16:47 +00:00 · 2026-08-31 14:32:53 +02:00
parent e615011e73
commit 54b0e4eed4
9 changed files with 339 additions and 89 deletions
@@ -9,7 +9,7 @@
 import { describe, it, expect } from 'vitest';
 import { runOffline } from '../src/cli/checks/index.js';
 import { blocking, type CheckContext, type CheckReport } from '../src/cli/checks/types.js';
-import { proseLength, missingSections, placeholders, images, undocumentedPermissions } from '../src/cli/checks/readme.js';
+import { proseLength, missingSections, placeholders, undocumentedPermissions } from '../src/cli/checks/readme.js';

 /** A manifest that passes everything, so each test can break exactly one thing. */
 const GOOD_MANIFEST = {
@@ -188,19 +188,20 @@ describe('README checks', () => {
  });

  /**
-   * The old check regexed for an image LINK and passed if it found one — so the scaffold's
-   * `![screenshot](./docs/screenshot.png)`, pointing at a file that was never created, satisfied
-   * it. Resolve the path instead.
+   * The registry's check-readme.mjs fetches EXACTLY docs/screenshot.png at the pinned commit —
+   * README image links are irrelevant to this gate. (A previous version of this check scanned
+   * them instead, which passed a README whose only images had other names and failed it in CI,
+   * after the release was immutable.)
   */
-  it('fails a screenshot link whose file does not exist', () => {
+  it('fails when docs/screenshot.png does not exist, whatever the README links', () => {
    const r = runOffline(ctx({ exists: (rel) => rel === 'server/index.js' }));
    expect(failed(r, 'docs.screenshot')).toBe(true);
    expect(r.errors.find((e) => e.id === 'docs.screenshot')?.next).toBe('trek-plugin shot');
  });

-  it('fails a README with no image at all', () => {
+  it('passes on docs/screenshot.png alone — README image links are not what CI checks', () => {
    const r = runOffline(ctx({ readme: GOOD_README.replace('![screenshot](./docs/screenshot.png)', '') }));
-    expect(failed(r, 'docs.screenshot')).toBe(true);
+    expect(failed(r, 'docs.screenshot')).toBe(false);
  });
 });

@@ -259,11 +260,6 @@ describe('README helpers mirror the registry exactly', () => {
    expect(performance.now() - started).toBeLessThan(1000);
  });

-  it('ignores data: URIs when looking for a screenshot, like the registry does', () => {
-    expect(images('![a](data:image/png;base64,xxx)')).toEqual([]);
-    expect(images('<img src="shot.png">')).toEqual(['shot.png']);
-  });
-
  it('matches a permission anywhere in the README, case-insensitively', () => {
    expect(undocumentedPermissions('we use `DB:OWN` for caching', ['db:own'])).toEqual([]);
    expect(undocumentedPermissions('nothing here', ['db:own'])).toEqual(['db:own']);
@@ -0,0 +1,184 @@
+/**
+ * The network checks talk to GitHub only through the global `fetch`, so they run here against a
+ * stubbed fetch and no network. These tests pin the README-at-commit gate — in particular its
+ * screenshot half: the registry's check-readme.mjs fetches EXACTLY `docs/screenshot.png` at the
+ * pinned commit (that precise path is what the store card loads), and preflight must grade the
+ * same path the same way. The offline twin of this gate lives in checks.test.ts.
+ */
+import { describe, it, expect, afterEach, vi } from 'vitest';
+import { NETWORK_CHECKS } from '../src/cli/checks/network.js';
+import { makeContext } from '../src/cli/checks/context.js';
+import type { RegistryEntry } from '../src/cli/checks/types.js';
+
+const readmeAtCommit = NETWORK_CHECKS.find((c) => c.id === 'network.readme-at-commit');
+if (!readmeAtCommit) throw new Error('network.readme-at-commit is not registered');
+
+/** Passes every registry README rule: four sections, no placeholders, ≥400 chars of prose,
+ *  and the manifest's one permission (`db:own`) named. */
+const GOOD_README = `# Flight Tracker
+
+![screenshot](./docs/screenshot.png)
+
+## What it does
+
+This plugin shows your next flight on the trip dashboard, so you never have to dig through your
+inbox for a boarding pass again. It reads the trip you are looking at, finds the next reservation
+of type flight, and renders it as a widget with the gate, the terminal and a countdown. There is
+nothing to configure and nothing to sign up for, and it works offline once the trip has synced.
+
+## Screenshots
+
+The image above shows the widget on a trip dashboard.
+
+## Permissions
+
+| Permission | Why |
+|---|---|
+| \`db:own\` | Stores the cached flight lookup so the widget renders instantly. |
+
+## Setup
+
+Install it and enable it. There is nothing to configure.
+`;
+
+const SHA = 'a'.repeat(40);
+
+const ENTRY: RegistryEntry = {
+  id: 'flight-tracker',
+  name: 'Flight Tracker',
+  author: 'You',
+  description: 'Live flight status on the dashboard.',
+  repo: 'you/trek-plugin-flight-tracker',
+  type: 'widget',
+  versions: [
+    {
+      version: '1.0.0',
+      gitTag: 'v1.0.0',
+      commitSha: SHA,
+      downloadUrl: 'https://github.com/you/trek-plugin-flight-tracker/releases/download/v1.0.0/plugin.zip',
+      sha256: '0'.repeat(64),
+      trek: '>=4.0.0 <5.0.0',
+      size: 1234,
+      apiVersion: 1,
+      nativeModules: false,
+      publishedAt: '2026-01-01T00:00:00.000Z',
+    },
+  ],
+};
+
+const MANIFEST_AT_COMMIT = JSON.stringify({ id: 'flight-tracker', permissions: ['db:own'] });
+
+type Route = { ok: boolean; status: number; contentType?: string; body?: string } | 'throw';
+
+/** Serve each URL by suffix; anything unrouted is a test bug, not a silent 404. */
+function stubFetch(routes: Record<string, Route>): ReturnType<typeof vi.fn> {
+  const fn = vi.fn(async (url: unknown, init?: { headers?: Record<string, string> }) => {
+    void init;
+    const key = Object.keys(routes).find((k) => String(url).endsWith(k));
+    if (!key) throw new Error(`unexpected fetch in test: ${String(url)}`);
+    const r = routes[key];
+    if (r === 'throw') throw new Error('network down');
+    return {
+      ok: r.ok,
+      status: r.status,
+      headers: { get: (name: string) => (name.toLowerCase() === 'content-type' ? (r.contentType ?? null) : null) },
+      text: async () => r.body ?? '',
+    };
+  });
+  vi.stubGlobal('fetch', fn);
+  return fn;
+}
+
+const ctx = () => makeContext({ entry: ENTRY });
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('network.readme-at-commit — the README graded at the pinned commit', () => {
+  it('passes a good README whose docs/screenshot.png serves an image at the commit', async () => {
+    const fetchFn = stubFetch({
+      '/README.md': { ok: true, status: 200, body: GOOD_README },
+      '/docs/screenshot.png': { ok: true, status: 200, contentType: 'image/png' },
+      '/trek-plugin.json': { ok: true, status: 200, body: MANIFEST_AT_COMMIT },
+    });
+
+    const r = await readmeAtCommit.run(ctx());
+    expect(r.status).toBe('pass');
+
+    // The screenshot probe mirrors the registry gate byte-for-byte: the exact path at the
+    // pinned commit, first 2 KB only.
+    const shot = fetchFn.mock.calls.find(([u]) => String(u).endsWith('/docs/screenshot.png'));
+    expect(shot?.[0]).toBe(`https://raw.githubusercontent.com/${ENTRY.repo}/${SHA}/docs/screenshot.png`);
+    expect(shot?.[1]?.headers?.Range).toBe('bytes=0-2047');
+  });
+
+  it('fails naming docs/screenshot.png when the file 404s at the commit — README links to other images do not count', async () => {
+    stubFetch({
+      '/README.md': { ok: true, status: 200, body: GOOD_README },
+      '/docs/screenshot.png': { ok: false, status: 404, contentType: 'text/plain' },
+      '/trek-plugin.json': { ok: true, status: 200, body: MANIFEST_AT_COMMIT },
+    });
+
+    const r = await readmeAtCommit.run(ctx());
+    expect(r.status).toBe('fail');
+    expect(r.fix).toMatch(/docs\/screenshot\.png does not resolve to an image/);
+    expect(r.fix).toMatch(/404/);
+    expect(r.fix).toMatch(/trek-plugin shot/);
+  });
+
+  it('fails when the file resolves but is not an image (200 with no content-type)', async () => {
+    stubFetch({
+      '/README.md': { ok: true, status: 200, body: GOOD_README },
+      '/docs/screenshot.png': { ok: true, status: 200 },
+      '/trek-plugin.json': { ok: true, status: 200, body: MANIFEST_AT_COMMIT },
+    });
+
+    const r = await readmeAtCommit.run(ctx());
+    expect(r.status).toBe('fail');
+    expect(r.fix).toMatch(/no content-type/);
+  });
+
+  it('fails calling the screenshot unreachable when the fetch itself throws', async () => {
+    stubFetch({
+      '/README.md': { ok: true, status: 200, body: GOOD_README },
+      '/docs/screenshot.png': 'throw',
+      '/trek-plugin.json': { ok: true, status: 200, body: MANIFEST_AT_COMMIT },
+    });
+
+    const r = await readmeAtCommit.run(ctx());
+    expect(r.status).toBe('fail');
+    expect(r.fix).toMatch(/docs\/screenshot\.png is unreachable/);
+  });
+
+  it('fails on a README missing at the commit — the tree is not what the registry grades', async () => {
+    stubFetch({
+      '/README.md': { ok: false, status: 404 },
+    });
+
+    const r = await readmeAtCommit.run(ctx());
+    expect(r.status).toBe('fail');
+    expect(r.detail).toMatch(/README\.md not found/);
+  });
+
+  it('reports the README problems and the permission parity together, like the registry does', async () => {
+    stubFetch({
+      '/README.md': { ok: true, status: 200, body: '# Stub\n\nDescribe what it does. {{TAGLINE}}\n' },
+      '/docs/screenshot.png': { ok: true, status: 200, contentType: 'image/png' },
+      '/trek-plugin.json': { ok: true, status: 200, body: MANIFEST_AT_COMMIT },
+    });
+
+    const r = await readmeAtCommit.run(ctx());
+    expect(r.status).toBe('fail');
+    expect(r.fix).toMatch(/missing required section/);
+    expect(r.fix).toMatch(/template placeholder/);
+    expect(r.fix).toMatch(/chars of prose/);
+    expect(r.fix).toMatch(/permissions not explained in the README: db:own/);
+  });
+
+  it('skips without an entry — nothing to grade against', async () => {
+    stubFetch({});
+    const r = await readmeAtCommit.run(makeContext({}));
+    expect(r.status).toBe('skip');
+  });
+});