@arraypress/extension-kit 0.0.0-stage → 1.0.0

package/src/build/duplication.js

@@ -0,0 +1,119 @@
+/**
+ * A guard against copied code: run jscpd over a repository with its
+ * `.jscpd.json` and fail on any clone, except the deliberate ones listed,
+ * each with its reason, in `.jscpd-allowlist.json`:
+ *
+ *     { "allow": [{ "files": ["test/a.js", "test/b.js"], "reason": "…" }] }
+ *
+ * A clone is allowed when both of its files are in one entry. jscpd is the
+ * caller's (a devDependency), passed in as its `runJscpd`, so this package
+ * needs none.
+ *
+ * @module build/duplication
+ */
+
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+/**
+ * One clone from jscpd's JSON report, reduced to where it is.
+ *
+ * @typedef {object} Clone
+ * @property {string} first First file, relative to the scan's folder.
+ * @property {string} second Second file (may equal `first`).
+ * @property {number} lines How many lines it spans.
+ * @property {string} where "a.js:10-20 ~ b.js:30-40", for messages.
+ */
+
+/**
+ * One deliberate exception.
+ *
+ * @typedef {object} AllowEntry
+ * @property {string[]} files Files whose clones of each other are allowed.
+ * @property {string} reason Why the copy stays.
+ */
+
+/**
+ * jscpd's `runJscpd` (from the `jscpd` package): spawns its binary.
+ *
+ * @typedef {(args: readonly string[], options: {cwd: string, encoding: 'utf8'}) => {status: number | null, stderr: string, error?: Error}} RunJscpd
+ */
+
+/**
+ * The clones jscpd's JSON report lists.
+ *
+ * @param {{duplicates?: {firstFile: {name: string, start: number, end: number}, secondFile: {name: string, start: number, end: number}, lines: number}[]}} report
+ *   The parsed `jscpd-report.json`.
+ * @returns {Clone[]} One entry per clone.
+ */
+export function clonesFromReport(report) {
+  return (report.duplicates ?? []).map(({ firstFile: a, secondFile: b, lines }) => ({
+    first: a.name,
+    second: b.name,
+    lines,
+    where: `${a.name}:${a.start}-${a.end} ~ ${b.name}:${b.start}-${b.end}`,
+  }));
+}
+
+/**
+ * The clones no allowlist entry covers.
+ *
+ * @param {readonly Clone[]} clones - What jscpd found.
+ * @param {readonly AllowEntry[]} allow - The deliberate exceptions.
+ * @returns {Clone[]} The clones to fail on.
+ * @example
+ * disallowedClones(clones, [{ files: ['a.js', 'b.js'], reason: 'fixtures' }]);
+ */
+export function disallowedClones(clones, allow) {
+  return clones.filter(({ first, second }) => !allow.some(({ files }) => files.includes(first) && files.includes(second)));
+}
+
+/**
+ * Read a JSON file, or `fallback` when it doesn't exist.
+ *
+ * @template T
+ * @param {string} file - The file.
+ * @param {T} fallback - What a missing file reads as.
+ * @returns {Promise<T>} The parsed JSON.
+ */
+async function readJson(file, fallback) {
+  try {
+    return JSON.parse(await readFile(file, 'utf8'));
+  } catch (error) {
+    if (/** @type {NodeJS.ErrnoException} */ (error).code === 'ENOENT') return fallback;
+    throw error;
+  }
+}
+
+/**
+ * Run jscpd in `cwd` (it reads `.jscpd.json` there) and report clones the
+ * allowlist doesn't cover.
+ *
+ * @param {object} options - How to run.
+ * @param {RunJscpd} options.runJscpd - From the `jscpd` package.
+ * @param {string} [options.cwd] - The repository. Default the current folder.
+ * @returns {Promise<Clone[]>} The disallowed clones; empty means clean.
+ * @throws {Error} When jscpd can't run.
+ */
+export async function findDisallowedClones({ runJscpd, cwd = process.cwd() }) {
+  const out = await mkdtemp(path.join(tmpdir(), 'jscpd-'));
+  try {
+    // Absolute paths, made relative to the repository below: jscpd otherwise names each file
+    // relative to the scanned folder it's in, so test/a.js and scripts/a.js would look the same.
+    const run = runJscpd(['--reporters', 'json', '--output', out, '--silent', '--exit-code', '0', '--absolute'], { cwd, encoding: 'utf8' });
+    if (run.error || run.status !== 0) throw run.error ?? new Error(`jscpd failed: ${run.stderr}`);
+    /** @type {Parameters<typeof clonesFromReport>[0]} */
+    const report = await readJson(path.join(out, 'jscpd-report.json'), {});
+    for (const { firstFile, secondFile } of report.duplicates ?? []) {
+      firstFile.name = path.relative(cwd, firstFile.name);
+      secondFile.name = path.relative(cwd, secondFile.name);
+    }
+    /** @type {{allow?: AllowEntry[]}} */
+    const allowlist = await readJson(path.join(cwd, '.jscpd-allowlist.json'), {});
+    const allow = allowlist.allow ?? [];
+    return disallowedClones(clonesFromReport(report), allow);
+  } finally {
+    await rm(out, { recursive: true, force: true });
+  }
+}

package/src/build/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The kit's Node half, for an extension's build, package and maintenance
+ * scripts: never loaded by the extension itself.
+ *
+ * @module build
+ */
+export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
+export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
+export { TOOLBAR_COLORS, TOOLBAR_ICON_COLORS, TOOLBAR_ICON_SIZES, renderToolbarIcons, toolbarIconFile } from './toolbar-icons.js';
+export { RUNTIME_ENTRIES, STYLESHEET, vendorKit } from './vendor.js';
+export { ZIP_EXCLUDE, shipsFile, zipExtension } from './zip.js';

package/src/build/index.js

@@ -0,0 +1,12 @@
+/**
+ * The kit's Node half, for an extension's build, package and maintenance
+ * scripts: never loaded by the extension itself.
+ *
+ * @module build
+ */
+
+export { clonesFromReport, disallowedClones, findDisallowedClones } from './duplication.js';
+export { placeholderWarning, printReleaseChecks, repositoryReminder } from './release-checks.js';
+export { TOOLBAR_COLORS, TOOLBAR_ICON_COLORS, TOOLBAR_ICON_SIZES, renderToolbarIcons, toolbarIconFile } from './toolbar-icons.js';
+export { RUNTIME_ENTRIES, STYLESHEET, vendorKit } from './vendor.js';
+export { ZIP_EXCLUDE, shipsFile, zipExtension } from './zip.js';

package/src/build/release-checks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Package-time reminders about the About card's links (about/links.js): a
+ * loud warning while any is a placeholder, so a build with example.com links
+ * can't ship by accident, and a reminder that GitHub links need a public
+ * repository. Both only print: the zip is still fine for testing.
+ *
+ * @module build/release-checks
+ */
+/**
+ * The warning to print while any link is a placeholder.
+ *
+ * @param {Record<string, string>} links - The About links by name.
+ * @returns {string | null} The warning, naming each placeholder, or null when every link is real.
+ * @example
+ * placeholderWarning({ help: 'https://example.com/help' });
+ * // '!!!…\n!! WARNING: the About card still has placeholder links …\n!!   help: https://example.com/help\n…'
+ */
+export declare function placeholderWarning(links: Record<string, string>): string | null;
+/**
+ * The reminder to print when the links point into a repository: it has to be
+ * public before the store listing goes live.
+ *
+ * @param {Record<string, string>} links - The About links by name.
+ * @param {string} repository - The repository's address.
+ * @returns {string | null} The reminder, or null when no link is in the repository.
+ */
+export declare function repositoryReminder(links: Record<string, string>, repository: string): string | null;
+/**
+ * Print both, the warning on stderr: run last in `npm run package`, so it's
+ * the thing on screen.
+ *
+ * @param {Record<string, string>} links - The About links by name.
+ * @param {string} repository - The repository's address.
+ * @returns {void}
+ */
+export declare function printReleaseChecks(links: Record<string, string>, repository: string): void;

package/src/build/release-checks.js

@@ -0,0 +1,61 @@
+/**
+ * Package-time reminders about the About card's links (about/links.js): a
+ * loud warning while any is a placeholder, so a build with example.com links
+ * can't ship by accident, and a reminder that GitHub links need a public
+ * repository. Both only print: the zip is still fine for testing.
+ *
+ * @module build/release-checks
+ */
+
+import { isPlaceholder } from '../about/links.js';
+
+/**
+ * The warning to print while any link is a placeholder.
+ *
+ * @param {Record<string, string>} links - The About links by name.
+ * @returns {string | null} The warning, naming each placeholder, or null when every link is real.
+ * @example
+ * placeholderWarning({ help: 'https://example.com/help' });
+ * // '!!!…\n!! WARNING: the About card still has placeholder links …\n!!   help: https://example.com/help\n…'
+ */
+export function placeholderWarning(links) {
+  const left = Object.entries(links).filter(([, url]) => isPlaceholder(url));
+  if (!left.length) return null;
+  const bar = '!'.repeat(78);
+  return [
+    bar,
+    '!! WARNING: the About card still has placeholder links (about-links.js):',
+    ...left.map(([name, url]) => `!!   ${name}: ${url}`),
+    '!! Don’t submit this zip to the Chrome Web Store. Set the real URLs and rerun `npm run package`.',
+    bar,
+  ].join('\n');
+}
+
+/**
+ * The reminder to print when the links point into a repository: it has to be
+ * public before the store listing goes live.
+ *
+ * @param {Record<string, string>} links - The About links by name.
+ * @param {string} repository - The repository's address.
+ * @returns {string | null} The reminder, or null when no link is in the repository.
+ */
+export function repositoryReminder(links, repository) {
+  return Object.values(links).some((url) => url.startsWith(repository))
+    ? `Reminder: the About links point at ${repository}. Make the repository public before submitting to the Chrome Web Store.`
+    : null;
+}
+
+/**
+ * Print both, the warning on stderr: run last in `npm run package`, so it's
+ * the thing on screen.
+ *
+ * @param {Record<string, string>} links - The About links by name.
+ * @param {string} repository - The repository's address.
+ * @returns {void}
+ */
+export function printReleaseChecks(links, repository) {
+  const warning = placeholderWarning(links);
+  if (warning) console.warn(`\n${warning}\n`);
+  const reminder = repositoryReminder(links, repository);
+  if (reminder) console.log(`\n${reminder}\n`);
+}

package/src/build/toolbar-icons.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Toolbar glyphs: render an extension's monochrome toolbar icon in Chrome's
+ * own toolbar-icon colours, light and dark, at 16, 32 and 48px, for
+ * toolbar/theme.js to switch between.
+ *
+ * A folder holds the sources: `glyph.svg` (16×16 viewBox, drawn in
+ * `currentColor`) and, optionally, `glyph-16.svg`, the same mark hand-fitted
+ * to whole pixels for the 16px file (a 1.5px stroke smears at 1x). Out come
+ * `light-16.png`, `dark-16.png`, … beside them. The caller passes its own
+ * Playwright, so this package needs none.
+ *
+ * @module build/toolbar-icons
+ */
+/**
+ * Chrome's toolbar button icon colour, default theme, Chrome 157 (157.0.8103.39):
+ *
+ *   chrome/browser/ui/color/material_chrome_color_mixer.cc:531-532
+ *     kColorToolbarButtonIcon = kColorToolbarButtonIconDefault = kColorSysOnSurfaceSecondary
+ *   ui/color/sys_color_mixer.cc:219-220 (the baseline palette, no user colour)
+ *     kColorSysOnSurfaceSecondary = dark ? kColorRefNeutral80 : kColorRefNeutral30
+ *   ui/color/ref_color_mixer.cc:150, 155 (default; the :107/:112 values sit behind
+ *   kChromeDarkNeutrals26, off by default in ui/base/ui_base_features.cc:529)
+ *     kColorRefNeutral30 = #474747, kColorRefNeutral80 = #C7C7C7
+ *
+ * Apple's Passwords extension uses #35363A, which is the pre-2023 *dark toolbar*
+ * colour (chrome_color_mixer.cc:805, kColorToolbar dark); the old light icon was
+ * kGoogleGrey700 #5F6368 (chrome_color_mixer.cc:826-827). Both are darker or bluer
+ * than the Refresh icons beside them, so we use Chrome's current values.
+ */
+export declare const TOOLBAR_ICON_COLORS: Readonly<{
+    light: "#474747";
+    dark: "#C7C7C7";
+}>;
+/**
+ * The toolbar behind them, for previews: kColorToolbar = kColorSysBase
+ * (material_chrome_color_mixer.cc:527) = dark ? kColorRefNeutral25 : kColorRefNeutral100
+ * (sys_color_mixer.cc:246) = #3C3C3C / #FFFFFF (ref_color_mixer.cc:149, 164).
+ */
+export declare const TOOLBAR_COLORS: Readonly<{
+    light: "#FFFFFF";
+    dark: "#3C3C3C";
+}>;
+/** 16 and 32 are what Chrome draws at 1x and 2x; 48 covers 3x. */
+export declare const TOOLBAR_ICON_SIZES: readonly number[];
+/**
+ * The file name of one rendered icon.
+ *
+ * @param {'light' | 'dark'} scheme - Which scheme's colour.
+ * @param {number} size - Pixels.
+ * @returns {string} For example `light-16.png`.
+ */
+export declare function toolbarIconFile(scheme: 'light' | 'dark', size: number): string;
+export type BrowserLauncher = {
+    launch: () => Promise<{
+        newPage(options: {
+            viewport: {
+                width: number;
+                height: number;
+            };
+            deviceScaleFactor: number;
+        }): Promise<{
+            setContent(html: string): Promise<void>;
+            screenshot(options: {
+                omitBackground: boolean;
+            }): Promise<Uint8Array>;
+            close(): Promise<void>;
+        }>;
+        close(): Promise<void>;
+    }>;
+};
+/**
+ * The parts of a Playwright `BrowserType` (`chromium`) this uses.
+ *
+ * @typedef {object} BrowserLauncher
+ * @property {() => Promise<{newPage(options: {viewport: {width: number, height: number}, deviceScaleFactor: number}): Promise<{
+ *   setContent(html: string): Promise<void>,
+ *   screenshot(options: {omitBackground: boolean}): Promise<Uint8Array>,
+ *   close(): Promise<void>}>, close(): Promise<void>}>} launch
+ */
+/**
+ * Render every scheme and size from `dir`'s sources into `dir`.
+ *
+ * @param {object} options - What to render with and where.
+ * @param {BrowserLauncher} options.chromium - Playwright's `chromium`.
+ * @param {string} options.dir - The folder with `glyph.svg` (and maybe `glyph-16.svg`).
+ * @param {readonly number[]} [options.sizes] - Default {@link TOOLBAR_ICON_SIZES}.
+ * @returns {Promise<string[]>} The files written.
+ * @example
+ * import { chromium } from 'playwright';
+ * await renderToolbarIcons({ chromium, dir: 'extension/icons/toolbar' });
+ */
+export declare function renderToolbarIcons({ chromium, dir, sizes }: {
+    chromium: BrowserLauncher;
+    dir: string;
+    sizes?: readonly number[];
+}): Promise<string[]>;

package/src/build/toolbar-icons.js

@@ -0,0 +1,101 @@
+/**
+ * Toolbar glyphs: render an extension's monochrome toolbar icon in Chrome's
+ * own toolbar-icon colours, light and dark, at 16, 32 and 48px, for
+ * toolbar/theme.js to switch between.
+ *
+ * A folder holds the sources: `glyph.svg` (16×16 viewBox, drawn in
+ * `currentColor`) and, optionally, `glyph-16.svg`, the same mark hand-fitted
+ * to whole pixels for the 16px file (a 1.5px stroke smears at 1x). Out come
+ * `light-16.png`, `dark-16.png`, … beside them. The caller passes its own
+ * Playwright, so this package needs none.
+ *
+ * @module build/toolbar-icons
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * Chrome's toolbar button icon colour, default theme, Chrome 157 (157.0.8103.39):
+ *
+ *   chrome/browser/ui/color/material_chrome_color_mixer.cc:531-532
+ *     kColorToolbarButtonIcon = kColorToolbarButtonIconDefault = kColorSysOnSurfaceSecondary
+ *   ui/color/sys_color_mixer.cc:219-220 (the baseline palette, no user colour)
+ *     kColorSysOnSurfaceSecondary = dark ? kColorRefNeutral80 : kColorRefNeutral30
+ *   ui/color/ref_color_mixer.cc:150, 155 (default; the :107/:112 values sit behind
+ *   kChromeDarkNeutrals26, off by default in ui/base/ui_base_features.cc:529)
+ *     kColorRefNeutral30 = #474747, kColorRefNeutral80 = #C7C7C7
+ *
+ * Apple's Passwords extension uses #35363A, which is the pre-2023 *dark toolbar*
+ * colour (chrome_color_mixer.cc:805, kColorToolbar dark); the old light icon was
+ * kGoogleGrey700 #5F6368 (chrome_color_mixer.cc:826-827). Both are darker or bluer
+ * than the Refresh icons beside them, so we use Chrome's current values.
+ */
+export const TOOLBAR_ICON_COLORS = Object.freeze({ light: '#474747', dark: '#C7C7C7' });
+
+/**
+ * The toolbar behind them, for previews: kColorToolbar = kColorSysBase
+ * (material_chrome_color_mixer.cc:527) = dark ? kColorRefNeutral25 : kColorRefNeutral100
+ * (sys_color_mixer.cc:246) = #3C3C3C / #FFFFFF (ref_color_mixer.cc:149, 164).
+ */
+export const TOOLBAR_COLORS = Object.freeze({ light: '#FFFFFF', dark: '#3C3C3C' });
+
+/** 16 and 32 are what Chrome draws at 1x and 2x; 48 covers 3x. */
+export const TOOLBAR_ICON_SIZES = Object.freeze([16, 32, 48]);
+
+/**
+ * The file name of one rendered icon.
+ *
+ * @param {'light' | 'dark'} scheme - Which scheme's colour.
+ * @param {number} size - Pixels.
+ * @returns {string} For example `light-16.png`.
+ */
+export function toolbarIconFile(scheme, size) {
+  return `${scheme}-${size}.png`;
+}
+
+/**
+ * The parts of a Playwright `BrowserType` (`chromium`) this uses.
+ *
+ * @typedef {object} BrowserLauncher
+ * @property {() => Promise<{newPage(options: {viewport: {width: number, height: number}, deviceScaleFactor: number}): Promise<{
+ *   setContent(html: string): Promise<void>,
+ *   screenshot(options: {omitBackground: boolean}): Promise<Uint8Array>,
+ *   close(): Promise<void>}>, close(): Promise<void>}>} launch
+ */
+
+/**
+ * Render every scheme and size from `dir`'s sources into `dir`.
+ *
+ * @param {object} options - What to render with and where.
+ * @param {BrowserLauncher} options.chromium - Playwright's `chromium`.
+ * @param {string} options.dir - The folder with `glyph.svg` (and maybe `glyph-16.svg`).
+ * @param {readonly number[]} [options.sizes] - Default {@link TOOLBAR_ICON_SIZES}.
+ * @returns {Promise<string[]>} The files written.
+ * @example
+ * import { chromium } from 'playwright';
+ * await renderToolbarIcons({ chromium, dir: 'extension/icons/toolbar' });
+ */
+export async function renderToolbarIcons({ chromium, dir, sizes = TOOLBAR_ICON_SIZES }) {
+  const master = await readFile(path.join(dir, 'glyph.svg'), 'utf8');
+  const small = await readFile(path.join(dir, 'glyph-16.svg'), 'utf8').catch(() => master);
+  const browser = await chromium.launch();
+  /** @type {string[]} */
+  const written = [];
+  try {
+    for (const [scheme, color] of /** @type {['light' | 'dark', string][]} */ (Object.entries(TOOLBAR_ICON_COLORS))) {
+      for (const size of sizes) {
+        const page = await browser.newPage({ viewport: { width: size, height: size }, deviceScaleFactor: 1 });
+        const svg = size === 16 ? small : master;
+        await page.setContent(`<style>*{margin:0}svg{display:block;width:${size}px;height:${size}px;color:${color}}</style>${svg}`);
+        const file = path.join(dir, toolbarIconFile(scheme, size));
+        await writeFile(file, await page.screenshot({ omitBackground: true }));
+        written.push(file);
+        await page.close();
+      }
+    }
+  } finally {
+    await browser.close();
+  }
+  return written;
+}

package/src/build/vendor.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Copy the kit's browser half (the runtime modules and the stylesheet) into
+ * an extension folder. A packaged extension can't load files from outside
+ * itself, so an extension without a bundler loads the kit from a copy; the
+ * copy is made from the installed package on `npm install` and is never
+ * committed, so it can't drift from the version in package.json.
+ *
+ * An extension with a bundler imports the package instead and copies only
+ * the stylesheet ({@link STYLESHEET}).
+ *
+ * @module build/vendor
+ */
+/** What a vendored copy holds, relative to `src/`: everything an extension page or worker may load. */
+export declare const RUNTIME_ENTRIES: readonly string[];
+/** The kit's stylesheet, an absolute path in the installed package. */
+export declare const STYLESHEET: string;
+/**
+ * Replace `dest` with a fresh copy of the runtime modules and stylesheet.
+ *
+ * @param {string} dest - The folder to fill, e.g. `extension/vendor/extension-kit`. Removed first.
+ * @returns {Promise<string[]>} The entries copied, relative to `dest`.
+ * @example
+ * await vendorKit('extension/vendor/extension-kit');
+ * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …
+ */
+export declare function vendorKit(dest: string): Promise<string[]>;

package/src/build/vendor.js

@@ -0,0 +1,43 @@
+/**
+ * Copy the kit's browser half (the runtime modules and the stylesheet) into
+ * an extension folder. A packaged extension can't load files from outside
+ * itself, so an extension without a bundler loads the kit from a copy; the
+ * copy is made from the installed package on `npm install` and is never
+ * committed, so it can't drift from the version in package.json.
+ *
+ * An extension with a bundler imports the package instead and copies only
+ * the stylesheet ({@link STYLESHEET}).
+ *
+ * @module build/vendor
+ */
+
+import { cp, mkdir, rm } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+/** The package's `src/` folder. */
+const SOURCE = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+/** What a vendored copy holds, relative to `src/`: everything an extension page or worker may load. */
+export const RUNTIME_ENTRIES = Object.freeze(['index.js', 'index.d.ts', 'about', 'commands', 'dom', 'settings', 'styles', 'toolbar']);
+
+/** The kit's stylesheet, an absolute path in the installed package. */
+export const STYLESHEET = path.join(SOURCE, 'styles', 'chrome-ui.css');
+
+/**
+ * Replace `dest` with a fresh copy of the runtime modules and stylesheet.
+ *
+ * @param {string} dest - The folder to fill, e.g. `extension/vendor/extension-kit`. Removed first.
+ * @returns {Promise<string[]>} The entries copied, relative to `dest`.
+ * @example
+ * await vendorKit('extension/vendor/extension-kit');
+ * // extension/vendor/extension-kit/index.js, …/styles/chrome-ui.css, …
+ */
+export async function vendorKit(dest) {
+  await rm(dest, { recursive: true, force: true });
+  await mkdir(dest, { recursive: true });
+  for (const entry of RUNTIME_ENTRIES) {
+    await cp(path.join(SOURCE, entry), path.join(dest, entry), { recursive: true });
+  }
+  return [...RUNTIME_ENTRIES];
+}

package/src/build/zip.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Zip an extension folder for the Chrome Web Store: the folder's contents
+ * with `manifest.json` at the zip's root, less source-only files.
+ *
+ * @module build/zip
+ */
+/**
+ * `zip -x` patterns left out by default (a `*` crosses folders): SVG sources
+ * of rendered icons, type declarations that only editors read, and Finder's
+ * `.DS_Store` files.
+ */
+export declare const ZIP_EXCLUDE: readonly string[];
+/**
+ * Whether a file under an extension folder ships, by the same rules as
+ * {@link ZIP_EXCLUDE}: for tests that compare the zip with the folder.
+ *
+ * @param {string} file - Path relative to the extension folder, forward slashes.
+ * @returns {boolean} False for `icons/**.svg`, `*.d.ts` and `.DS_Store`.
+ */
+export declare function shipsFile(file: string): boolean;
+/**
+ * Zip everything under `from` into `to`, paths relative to `from`. An older
+ * zip at `to` is replaced. Needs the `zip` command (macOS and Linux have it).
+ *
+ * @param {string} from - The extension folder.
+ * @param {string} to - The zip to write; its folder is made if missing.
+ * @param {readonly string[]} [exclude] - `zip -x` patterns. Default {@link ZIP_EXCLUDE}.
+ * @returns {Promise<string>} `to`.
+ * @throws {Error} When `zip` fails.
+ */
+export declare function zipExtension(from: string, to: string, exclude?: readonly string[]): Promise<string>;

package/src/build/zip.js

@@ -0,0 +1,47 @@
+/**
+ * Zip an extension folder for the Chrome Web Store: the folder's contents
+ * with `manifest.json` at the zip's root, less source-only files.
+ *
+ * @module build/zip
+ */
+
+import { execFileSync } from 'node:child_process';
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+/**
+ * `zip -x` patterns left out by default (a `*` crosses folders): SVG sources
+ * of rendered icons, type declarations that only editors read, and Finder's
+ * `.DS_Store` files.
+ */
+export const ZIP_EXCLUDE = Object.freeze(['icons/*.svg', '*.d.ts', '*.DS_Store']);
+
+/**
+ * Whether a file under an extension folder ships, by the same rules as
+ * {@link ZIP_EXCLUDE}: for tests that compare the zip with the folder.
+ *
+ * @param {string} file - Path relative to the extension folder, forward slashes.
+ * @returns {boolean} False for `icons/**.svg`, `*.d.ts` and `.DS_Store`.
+ */
+export function shipsFile(file) {
+  return !/^icons\/.*\.svg$/.test(file) && !file.endsWith('.d.ts') && path.posix.basename(file) !== '.DS_Store';
+}
+
+/**
+ * Zip everything under `from` into `to`, paths relative to `from`. An older
+ * zip at `to` is replaced. Needs the `zip` command (macOS and Linux have it).
+ *
+ * @param {string} from - The extension folder.
+ * @param {string} to - The zip to write; its folder is made if missing.
+ * @param {readonly string[]} [exclude] - `zip -x` patterns. Default {@link ZIP_EXCLUDE}.
+ * @returns {Promise<string>} `to`.
+ * @throws {Error} When `zip` fails.
+ */
+export async function zipExtension(from, to, exclude = ZIP_EXCLUDE) {
+  await mkdir(path.dirname(to), { recursive: true });
+  await rm(to, { force: true });
+  // -X leaves out macOS extended attributes (the store rejects __MACOSX
+  // entries); -D leaves out folder entries, so the zip lists files only.
+  execFileSync('zip', ['-r', '-X', '-D', '-q', to, '.', '-x', ...exclude], { cwd: from, stdio: 'inherit' });
+  return to;
+}

package/src/commands/shortcuts.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The keyboard shortcuts an options page lists: only the ones that are set,
+ * in the extension's own order (Chrome's `commands.getAll()` order is the
+ * manifest's object order, which isn't the menu's). Users set and change them
+ * on chrome://extensions/shortcuts, which the page links to.
+ *
+ * @module commands/shortcuts
+ */
+export type ShortcutEntry = {
+    /**
+     * The command's name in the manifest.
+     */
+    id: string;
+    /**
+     * What the page calls it.
+     */
+    title: string;
+};
+/**
+ * @typedef {object} ShortcutEntry
+ * @property {string} id The command's name in the manifest.
+ * @property {string} title What the page calls it.
+ */
+/**
+ * The shortcuts that are set, in `entries`' order.
+ *
+ * @param {readonly ShortcutEntry[]} entries - The commands to list, in order.
+ * @param {readonly {name?: string, shortcut?: string}[]} commands - `chrome.commands.getAll()`.
+ * @returns {(ShortcutEntry & {shortcut: string})[]} Each entry with its shortcut; unset ones left out.
+ * @example
+ * setShortcuts([{ id: 'reset', title: 'Reset' }], await chrome.commands.getAll());
+ * // [{ id: 'reset', title: 'Reset', shortcut: '⌥⇧0' }]
+ */
+export declare function setShortcuts(entries: readonly ShortcutEntry[], commands: readonly {
+    name?: string;
+    shortcut?: string;
+}[]): (ShortcutEntry & {
+    shortcut: string;
+})[];

package/src/commands/shortcuts.js

@@ -0,0 +1,31 @@
+/**
+ * The keyboard shortcuts an options page lists: only the ones that are set,
+ * in the extension's own order (Chrome's `commands.getAll()` order is the
+ * manifest's object order, which isn't the menu's). Users set and change them
+ * on chrome://extensions/shortcuts, which the page links to.
+ *
+ * @module commands/shortcuts
+ */
+
+/**
+ * @typedef {object} ShortcutEntry
+ * @property {string} id The command's name in the manifest.
+ * @property {string} title What the page calls it.
+ */
+
+/**
+ * The shortcuts that are set, in `entries`' order.
+ *
+ * @param {readonly ShortcutEntry[]} entries - The commands to list, in order.
+ * @param {readonly {name?: string, shortcut?: string}[]} commands - `chrome.commands.getAll()`.
+ * @returns {(ShortcutEntry & {shortcut: string})[]} Each entry with its shortcut; unset ones left out.
+ * @example
+ * setShortcuts([{ id: 'reset', title: 'Reset' }], await chrome.commands.getAll());
+ * // [{ id: 'reset', title: 'Reset', shortcut: '⌥⇧0' }]
+ */
+export function setShortcuts(entries, commands) {
+  return entries.flatMap((entry) => {
+    const shortcut = commands.find((command) => command.name === entry.id)?.shortcut;
+    return shortcut ? [{ ...entry, shortcut }] : [];
+  });
+}