@capybara-hq/plugin-tools 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/marketplace/cli.d.ts

@@ -1,20 +1,23 @@
 export declare const MARKETPLACE_USAGE: string;
 /**
  * `capybara-plugin marketplace`: writes (`--write`) or checks (`--check`) the repository's
- * marketplace manifest against reproducible packs of its public plugins ({@link syncMarketplace}).
+ * marketplace manifest, one entry per public plugin at its current version, against reproducible
+ * packs of its public plugins ({@link syncMarketplace}).
  *
  * - `--root <dir>`: the repository (default: the current directory);
  * - `--file <path>`: the manifest, relative to the root (default `.capybara-plugin/marketplace.json`);
  * - `--plugins <glob>`: the plugin directories, relative to the root (default `plugins/*`, or the
  *   root itself when it is a plugin).
  *
- * - `--base <rev>` (with `--check`, on pull requests): the entries the file had at `<rev>` must be
- *   unchanged and first, in order (`marketplace-append-only`), and the entries added since must
- *   match the tree's packs (`marketplace-integrity`).
+ * - `--base <rev>` (with `--check`, on pull requests): an entry's version may only increase over the
+ *   versions `<rev>` lists (`marketplace-version-decrease`), a version `<rev>` lists keeps its
+ *   integrity, and the entries added since must match the tree's packs (`marketplace-integrity`).
  *
- * `--check` exits 1 on any finding (`marketplace-missing`, `marketplace-integrity`,
- * `marketplace-append-only`, `marketplace-invalid`); `--write` appends the missing entries and
- * exits 1 only on `marketplace-invalid`.
+ * `--check` exits 1 on any finding that is not a warning (`marketplace-missing`,
+ * `marketplace-display-stale`, `marketplace-integrity`, `marketplace-version-decrease`,
+ * `marketplace-invalid`); `--write` writes each plugin's entry (replacing its other versions,
+ * refreshing a listed entry's summary, displayName and icon) and exits 1 only on
+ * `marketplace-invalid`.
  * Relative paths resolve against `cwd`. Returns the exit code.
  */
 export declare function marketplaceCommand(args: string[], cwd: string): Promise<number>;

package/dist/marketplace/cli.js

@@ -1,25 +1,29 @@
 import { resolve } from "node:path";
 import { parseArgs } from "node:util";
 import { formatFinding } from "../check/report.js";
+import { errorsOf } from "../check/source.js";
 import { MARKETPLACE_FILE, syncMarketplace } from "./marketplace.js";
 export const MARKETPLACE_USAGE = "capybara-plugin marketplace --write|--check [--base <rev>] [--root <dir>] [--file <path>]\n" +
     "                            [--plugins <glob>]";
 /**
  * `capybara-plugin marketplace`: writes (`--write`) or checks (`--check`) the repository's
- * marketplace manifest against reproducible packs of its public plugins ({@link syncMarketplace}).
+ * marketplace manifest, one entry per public plugin at its current version, against reproducible
+ * packs of its public plugins ({@link syncMarketplace}).
  *
  * - `--root <dir>`: the repository (default: the current directory);
  * - `--file <path>`: the manifest, relative to the root (default `.capybara-plugin/marketplace.json`);
  * - `--plugins <glob>`: the plugin directories, relative to the root (default `plugins/*`, or the
  *   root itself when it is a plugin).
  *
- * - `--base <rev>` (with `--check`, on pull requests): the entries the file had at `<rev>` must be
- *   unchanged and first, in order (`marketplace-append-only`), and the entries added since must
- *   match the tree's packs (`marketplace-integrity`).
+ * - `--base <rev>` (with `--check`, on pull requests): an entry's version may only increase over the
+ *   versions `<rev>` lists (`marketplace-version-decrease`), a version `<rev>` lists keeps its
+ *   integrity, and the entries added since must match the tree's packs (`marketplace-integrity`).
  *
- * `--check` exits 1 on any finding (`marketplace-missing`, `marketplace-integrity`,
- * `marketplace-append-only`, `marketplace-invalid`); `--write` appends the missing entries and
- * exits 1 only on `marketplace-invalid`.
+ * `--check` exits 1 on any finding that is not a warning (`marketplace-missing`,
+ * `marketplace-display-stale`, `marketplace-integrity`, `marketplace-version-decrease`,
+ * `marketplace-invalid`); `--write` writes each plugin's entry (replacing its other versions,
+ * refreshing a listed entry's summary, displayName and icon) and exits 1 only on
+ * `marketplace-invalid`.
  * Relative paths resolve against `cwd`. Returns the exit code.
  */
 export async function marketplaceCommand(args, cwd) {
@@ -59,14 +63,20 @@ export async function marketplaceCommand(args, cwd) {
         });
         for (const f of r.findings)
             console.error(formatFinding(f, root));
-        if (r.findings.length > 0) {
-            console.error(`\n${r.findings.length} marketplace finding(s)`);
+        const errors = errorsOf(r.findings);
+        if (errors.length > 0) {
+            console.error(`\n${errors.length} marketplace finding(s)`);
             return 1;
         }
         if (values.write) {
             for (const e of r.added)
                 console.log(`added ${e.name}@${e.version}`);
-            console.log(r.added.length === 0 ? "marketplace is up to date" : `wrote ${file}`);
+            for (const k of r.removed)
+                console.log(`removed ${k}`);
+            for (const k of r.refreshed)
+                console.log(`refreshed ${k}`);
+            const changed = r.added.length + r.removed.length + r.refreshed.length > 0;
+            console.log(changed ? `wrote ${file}` : "marketplace is up to date");
         }
         else {
             console.log("marketplace is up to date");

package/dist/marketplace/marketplace.d.ts

@@ -9,44 +9,66 @@ export interface SyncMarketplaceOptions {
     file: string;
     /** Plugin directories relative to `root` (`*` within one segment); default as `discoverPlugins`. */
     plugins?: string;
-    /** Append the missing entries to `file` (`--write`); otherwise only report them (`--check`). */
+    /** Write the plugins' entries into `file` (`--write`); otherwise only report them (`--check`). */
     write: boolean;
     /**
      * A git revision (`--check --base <rev>`, pull requests): the entries the file had there are
-     * published and must still be there, unchanged and in the same order (only appending is
-     * allowed; `marketplace-append-only`), and every entry added since must match the tree's pack
-     * (`marketplace-integrity`). A file the base does not have constrains nothing.
+     * published. An entry of a version the base lists must keep its source and integrity
+     * (`marketplace-integrity`); an entry of a version the base does not list must be newer than
+     * every version the base lists for that plugin (`marketplace-version-decrease`) and, when it is
+     * the tree's version, match the tree's pack (`marketplace-integrity`). A file the base does not
+     * have constrains nothing.
      */
     base?: string;
 }
 /** The result of {@link syncMarketplace}. */
 export interface SyncMarketplaceResult {
-    /** Entries for `(name, version)` pairs the file does not list yet (appended with `write`). */
+    /** New entries: plugins not listed at their current version (written with `write`). */
     added: MarketplaceEntry[];
+    /** `name@version` of the other entries of the tree's plugins (dropped with `write`). */
+    removed: string[];
     /**
-     * `marketplace-invalid` (the file does not parse, or would not after appending),
-     * `marketplace-integrity` (with a base: an entry added since names another package or integrity
-     * than the tree's pack), `marketplace-append-only` (with a base: a published entry changed, moved
-     * or went away) and, without `write`, `marketplace-missing` (one per added entry).
+     * `name@version` of listed entries whose `summary` / `displayName` / `icon` differ from plugin.json
+     * (rewritten with `write`; source and integrity never change).
+     */
+    refreshed: string[];
+    /**
+     * `marketplace-invalid` (the file does not parse, or would not after writing),
+     * `marketplace-integrity` and `marketplace-version-decrease` (with a base, see
+     * {@link SyncMarketplaceOptions.base}) and, without `write`, `marketplace-missing` (one per
+     * plugin whose current version is not listed, or not as its only entry) and
+     * `marketplace-display-stale` (a listed entry's summary / displayName / icon differ from plugin.json).
      */
     findings: Finding[];
 }
 /**
- * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing every
- * published version of its public plugins (package ecosystem spec §5.2; one entry per
- * `(name, version)`, Decision 7 of phase A3b). Each public plugin (not `"private": true`) is packed
- * reproducibly with {@link packPlugin}; when the file has no entry for its name and version, an
- * entry `{ name, version, summary, homepage?, permissions, source: { npm: { package, version,
- * integrity } } }` is added (`integrity` the pack's sha512, which the release then publishes
- * byte for byte; `permissions` display only). A version already listed is not packed or compared:
- * once published, its bytes are the release gate's business (`release --marketplace`), so a later
- * source or toolchain change at the same version is not a finding. With `base`, published entries
- * must be unchanged and first in order, and entries added since must match the tree's packs.
- * Entries of versions no longer in the tree are kept, so a pinned commit lists what it pins and
- * older versions stay importable. The file is written formatted as Biome formats it
- * ({@link formatMarketplaceJson}).
- * With `write`, the new entries are appended in plugin order (nothing is written when there is any
- * other finding).
+ * The repository path of a plugin's icon: the plugin.json `icon` (relative to the plugin's
+ * directory `dir`) as `./<path from the root>` (an entry's `icon`, read at the marketplace's
+ * commit, so it follows every release without naming a tag).
+ */
+export declare function repoIconPath(root: string, dir: string, icon: string): string;
+/**
+ * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing one entry
+ * per public plugin, its current version (plugin component management spec §13.2, replacing the
+ * one-entry-per-version rule of the package ecosystem spec §5.2). Each public plugin (not
+ * `"private": true`) not listed at its version is packed reproducibly with {@link packPlugin} and
+ * gets an entry `{ name, version, summary, displayName?, icon?, homepage?, permissions, source: {
+ * npm: { package, version, integrity } } }` (`summary` from the plugin.json `description`, a string
+ * being `en`; `displayName` copied from plugin.json; `icon` the plugin.json `icon` as a path in the
+ * repository, `./<plugin dir>/<icon>`, which a git marketplace reads at its refreshed commit;
+ * `integrity` the pack's sha512, which the release
+ * then publishes byte for byte; `permissions` display only). The new entry takes the place of the
+ * plugin's first entry (a version that moved), the plugin's other entries are dropped (also those
+ * of a file written in the older one-entry-per-version form), and a plugin not listed yet is
+ * appended. Entries of plugins not in the tree are kept. A version already listed is not packed or
+ * compared: once published, its bytes are the release gate's business (`release --marketplace`),
+ * so a later source or toolchain change at the same version is not a finding; only its display
+ * fields (`summary`, `displayName`, `icon`) are refreshed from the source plugin.json. Every other field
+ * of a kept entry stays as written, among them `deprecated`, which the maintainer sets by hand on
+ * a published version's entry (not in plugin.json: that would change the packed bytes); a new
+ * version's entry has none, and no rule compares it with the base. With `base`, see
+ * {@link SyncMarketplaceOptions.base}. The file is written formatted as Biome formats it
+ * ({@link formatMarketplaceJson}); nothing is written when there is any other finding.
  */
 export declare function syncMarketplace(opts: SyncMarketplaceOptions): Promise<SyncMarketplaceResult>;
 /**

package/dist/marketplace/marketplace.js

@@ -4,16 +4,22 @@ import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, relative } from "node:path";
 import { isSensitivePermissionKey, PACKAGES_MAX_BYTES_DEFAULT, permissionKeys, permissionSetOfPackage, readExtensionPackage, WARNINGS_KEY_PREFIX, } from "@capybara-hq/kernel";
-import { MARKETPLACE_LIMITS, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
+import { MARKETPLACE_LIMITS, PLUGIN_MANIFEST_FILE, parseMarketplaceManifest, parsePluginManifest, pluginDescription, SDK_VERSION, } from "@capybara-hq/plugin-sdk";
 import { discoverPlugins } from "../discover.js";
 import { integrityOf } from "../integrity.js";
 import { packPlugin } from "../pack/pack.js";
+import { compareSemver, parseSemver } from "../release/semver.js";
 export { MARKETPLACE_FILE } from "./file.js";
 const isObj = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-/** The marketplace summary of a plugin: its plugin.json description, cut to the summary limit. */
-function summaryOf(description) {
+/** The marketplace summary text: a description cut to the summary limit. */
+function cut(text) {
     const max = MARKETPLACE_LIMITS.summaryChars;
-    return description.length <= max ? description : `${description.slice(0, max - 1)}…`;
+    return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
+}
+/** The marketplace summary of a plugin: its plugin.json description (`{ en, zh? }`), each cut. */
+function summaryOf(description) {
+    const d = pluginDescription(description);
+    return { en: cut(d.en), ...(d.zh !== undefined && { zh: cut(d.zh) }) };
 }
 /** The permission summary of a packed plugin, as the kernel computes it at import (display only). */
 async function permissionsOf(bytes, hasExtension) {
@@ -31,28 +37,92 @@ async function permissionsOf(bytes, hasExtension) {
 /** An entry's version: `version`, else its npm source's. */
 const versionOf = (e) => e.version ?? ("npm" in e.source ? e.source.npm.version : undefined);
 /**
- * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing every
- * published version of its public plugins (package ecosystem spec §5.2; one entry per
- * `(name, version)`, Decision 7 of phase A3b). Each public plugin (not `"private": true`) is packed
- * reproducibly with {@link packPlugin}; when the file has no entry for its name and version, an
- * entry `{ name, version, summary, homepage?, permissions, source: { npm: { package, version,
- * integrity } } }` is added (`integrity` the pack's sha512, which the release then publishes
- * byte for byte; `permissions` display only). A version already listed is not packed or compared:
- * once published, its bytes are the release gate's business (`release --marketplace`), so a later
- * source or toolchain change at the same version is not a finding. With `base`, published entries
- * must be unchanged and first in order, and entries added since must match the tree's packs.
- * Entries of versions no longer in the tree are kept, so a pinned commit lists what it pins and
- * older versions stay importable. The file is written formatted as Biome formats it
- * ({@link formatMarketplaceJson}).
- * With `write`, the new entries are appended in plugin order (nothing is written when there is any
- * other finding).
+ * The repository path of a plugin's icon: the plugin.json `icon` (relative to the plugin's
+ * directory `dir`) as `./<path from the root>` (an entry's `icon`, read at the marketplace's
+ * commit, so it follows every release without naming a tag).
+ */
+export function repoIconPath(root, dir, icon) {
+    const rel = relative(root, dir).split("\\").join("/");
+    const file = icon.replace(/^\.\//, "");
+    return `./${rel === "" ? file : `${rel}/${file}`}`;
+}
+/**
+ * The display fields of a plugin's source plugin.json (`dir` its directory under `root`); undefined
+ * when it does not parse.
+ */
+function displayOf(json, root, dir) {
+    const m = parsePluginManifest(json);
+    if ("errors" in m)
+        return undefined;
+    return {
+        summary: summaryOf(m.description),
+        ...(m.displayName !== undefined && { displayName: m.displayName }),
+        ...(m.icon !== undefined && { icon: repoIconPath(root, dir, m.icon) }),
+    };
+}
+/** The display fields after `summary`, in this order. */
+const AFTER_SUMMARY = ["displayName", "icon"];
+/**
+ * `raw` with its `summary`, `displayName` and `icon` set to `d` (in place; a new `displayName` /
+ * `icon` right after `summary`, removed when plugin.json has none); undefined when they already
+ * equal.
+ */
+function refreshDisplay(raw, d) {
+    if (!isObj(raw))
+        return undefined;
+    if (canonical(raw.summary) === canonical(d.summary) &&
+        AFTER_SUMMARY.every((k) => canonical(raw[k]) === canonical(d[k]))) {
+        return undefined;
+    }
+    const after = (out) => {
+        for (const k of AFTER_SUMMARY)
+            if (d[k] !== undefined)
+                out[k] = d[k];
+    };
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (AFTER_SUMMARY.includes(k))
+            continue;
+        out[k] = k === "summary" ? d.summary : v;
+        if (k === "summary")
+            after(out);
+    }
+    if (!("summary" in raw)) {
+        out.summary = d.summary;
+        after(out);
+    }
+    return out;
+}
+/**
+ * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing one entry
+ * per public plugin, its current version (plugin component management spec §13.2, replacing the
+ * one-entry-per-version rule of the package ecosystem spec §5.2). Each public plugin (not
+ * `"private": true`) not listed at its version is packed reproducibly with {@link packPlugin} and
+ * gets an entry `{ name, version, summary, displayName?, icon?, homepage?, permissions, source: {
+ * npm: { package, version, integrity } } }` (`summary` from the plugin.json `description`, a string
+ * being `en`; `displayName` copied from plugin.json; `icon` the plugin.json `icon` as a path in the
+ * repository, `./<plugin dir>/<icon>`, which a git marketplace reads at its refreshed commit;
+ * `integrity` the pack's sha512, which the release
+ * then publishes byte for byte; `permissions` display only). The new entry takes the place of the
+ * plugin's first entry (a version that moved), the plugin's other entries are dropped (also those
+ * of a file written in the older one-entry-per-version form), and a plugin not listed yet is
+ * appended. Entries of plugins not in the tree are kept. A version already listed is not packed or
+ * compared: once published, its bytes are the release gate's business (`release --marketplace`),
+ * so a later source or toolchain change at the same version is not a finding; only its display
+ * fields (`summary`, `displayName`, `icon`) are refreshed from the source plugin.json. Every other field
+ * of a kept entry stays as written, among them `deprecated`, which the maintainer sets by hand on
+ * a published version's entry (not in plugin.json: that would change the packed bytes); a new
+ * version's entry has none, and no rule compares it with the base. With `base`, see
+ * {@link SyncMarketplaceOptions.base}. The file is written formatted as Biome formats it
+ * ({@link formatMarketplaceJson}); nothing is written when there is any other finding.
  */
 export async function syncMarketplace(opts) {
     const findings = [];
     const at = (rule, message) => findings.push({ file: opts.file, line: 1, rule, message });
+    const none = () => ({ added: [], removed: [], refreshed: [], findings });
     if (!existsSync(opts.file)) {
         at("marketplace-invalid", `${opts.file} does not exist: create it with schemaVersion, name, owner and "plugins": []`);
-        return { added: [], findings };
+        return none();
     }
     let raw;
     try {
@@ -60,22 +130,23 @@ export async function syncMarketplace(opts) {
     }
     catch (e) {
         at("marketplace-invalid", `not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
-        return { added: [], findings };
+        return none();
     }
     const parsed = parseMarketplaceManifest(raw);
     if ("errors" in parsed) {
         at("marketplace-invalid", parsed.errors.join("; "));
-        return { added: [], findings };
+        return none();
     }
+    // The parser keeps the order, so parsed.plugins[i] is rawEntries[i].
     const rawEntries = isObj(raw) && Array.isArray(raw.plugins) ? raw.plugins : [];
-    /** `name@version` of the entries added since `opts.base` (all of them without a base). */
-    let addedSinceBase;
+    /** `name@version` of the entries the base lists (undefined without a base). */
+    let baseKeys;
     if (opts.base !== undefined) {
         const baseEntries = entriesAt(opts.root, opts.file, opts.base);
-        findings.push(...appendOnly(baseEntries, rawEntries, opts.file));
-        addedSinceBase = new Set(rawEntries.slice(baseEntries.length).map((e) => keyOfRaw(e)));
+        findings.push(...publishedRules(baseEntries, rawEntries, opts.file));
+        baseKeys = new Set(baseEntries.map(keyOfRaw));
     }
-    const added = [];
+    const updates = [];
     const out = await mkdtemp(join(tmpdir(), "capybara-marketplace-"));
     try {
         for (const dir of discoverPlugins(opts.root, opts.plugins)) {
@@ -87,15 +158,33 @@ export async function syncMarketplace(opts) {
             if (pkg.private === true)
                 continue;
             const source = JSON.parse(await readFile(manifestFile, "utf8"));
+            // (the display fields of a listed entry are refreshed from this source plugin.json)
             const name = String(source.name);
             const version = String(pkg.version);
-            const listed = parsed.plugins.filter((e) => e.name === name && versionOf(e) === version);
+            const mine = parsed.plugins.flatMap((e, i) => (e.name === name ? [{ e, i }] : []));
+            const listed = mine.filter(({ e }) => versionOf(e) === version);
+            const dropped = mine
+                .filter(({ e }) => versionOf(e) !== version)
+                .map(({ e }) => `${name}@${versionOf(e) ?? "(no version)"}`);
             // A version already listed is published (or about to be): its bytes are the release gate's
             // business, so a later source or toolchain change at the same version is not a finding here.
             // Only an entry added since the base is compared with the tree's pack.
-            const toCompare = listed.filter((e) => addedSinceBase?.has(`${e.name}@${versionOf(e)}`));
-            if (listed.length > 0 && toCompare.length === 0)
+            const toCompare = listed.filter(({ e }) => baseKeys !== undefined && !baseKeys.has(keyOf(e)));
+            const kept = listed[0];
+            /** Keeps the listed entry: drops the other versions, refreshes its display fields. */
+            const keep = (raw) => {
+                const display = displayOf(source, opts.root, dir);
+                const fresh = display === undefined ? undefined : refreshDisplay(raw, display);
+                if (dropped.length > 0 || fresh !== undefined) {
+                    const entry = fresh ?? raw;
+                    updates.push({ name, version, entry, isNew: false, dropped, refreshed: !!fresh });
+                }
+            };
+            if (kept !== undefined && toCompare.length === 0) {
+                keep(rawEntries[kept.i]);
                 continue;
+            }
+            // Packed: the plugin is not listed at its version, or its entry is new since the base.
             const r = await packPlugin(dir, out);
             const bytes = new Uint8Array(await readFile(r.file));
             const npm = {
@@ -103,7 +192,7 @@ export async function syncMarketplace(opts) {
                 version: r.manifest.version,
                 integrity: integrityOf(bytes),
             };
-            for (const e of toCompare) {
+            for (const { e } of toCompare) {
                 const src = "npm" in e.source ? e.source.npm : undefined;
                 if (src?.package !== npm.package || src.integrity !== npm.integrity) {
                     const was = src === undefined
@@ -113,39 +202,79 @@ export async function syncMarketplace(opts) {
                         `with integrity ${npm.integrity}: run capybara-plugin marketplace --write`);
                 }
             }
-            if (listed.length > 0)
+            if (kept !== undefined) {
+                keep(rawEntries[kept.i]);
                 continue;
-            added.push({
+            }
+            const entry = {
                 name: r.manifest.name,
                 version: npm.version,
-                summary: { en: summaryOf(r.manifest.description) },
+                summary: summaryOf(r.manifest.description),
+                ...(r.manifest.displayName !== undefined && { displayName: r.manifest.displayName }),
+                ...(r.manifest.icon !== undefined && {
+                    icon: repoIconPath(opts.root, dir, r.manifest.icon),
+                }),
                 ...(r.manifest.homepage !== undefined && { homepage: r.manifest.homepage }),
                 permissions: await permissionsOf(bytes, r.manifest.extension !== undefined),
                 source: { npm },
-            });
+            };
+            updates.push({ name, version, entry, isNew: true, dropped, refreshed: false });
         }
     }
     finally {
         await rm(out, { recursive: true, force: true });
     }
+    const added = updates.filter((u) => u.isNew).map((u) => u.entry);
+    const removed = updates.flatMap((u) => u.dropped);
+    const refreshed = updates.filter((u) => u.refreshed).map((u) => `${u.name}@${u.version}`);
     if (!opts.write) {
-        for (const e of added) {
-            at("marketplace-missing", `${e.name}@${e.version} is not listed: run capybara-plugin marketplace --write`);
+        for (const u of updates) {
+            if (u.refreshed) {
+                at("marketplace-display-stale", `${u.name}@${u.version} has a summary or displayName other than its plugin.json's: ` +
+                    "run capybara-plugin marketplace --write");
+            }
+            if (!u.isNew && u.dropped.length === 0)
+                continue;
+            const also = u.dropped.map((d) => d.slice(u.name.length + 1)).join(", ");
+            at("marketplace-missing", u.isNew
+                ? `${u.name}@${u.version} is not listed${also === "" ? "" : ` (the marketplace lists ${also})`}: ` +
+                    "one entry per plugin, its current version; run capybara-plugin marketplace --write"
+                : `${u.name}@${u.version} is not the plugin's only entry (also ${also}): ` +
+                    "one entry per plugin, its current version; run capybara-plugin marketplace --write");
         }
-        return { added, findings };
+        return { added, removed, refreshed, findings };
     }
-    if (findings.length > 0 || added.length === 0)
-        return { added, findings };
+    if (findings.length > 0 || updates.length === 0)
+        return { added, removed, refreshed, findings };
+    const byName = new Map(updates.map((u) => [u.name, u]));
+    const placed = new Set();
+    const plugins = [];
+    for (const e of rawEntries) {
+        const name = isObj(e) ? String(e.name) : "";
+        const u = byName.get(name);
+        if (u === undefined) {
+            plugins.push(e);
+        }
+        else if (!placed.has(name)) {
+            placed.add(name);
+            plugins.push(u.entry);
+        }
+    }
+    for (const u of updates)
+        if (!placed.has(u.name))
+            plugins.push(u.entry);
     const next = isObj(raw) ? { ...raw } : {};
-    next.plugins = [...(Array.isArray(next.plugins) ? next.plugins : []), ...added];
+    next.plugins = plugins;
     const check = parseMarketplaceManifest(next);
     if ("errors" in check) {
         at("marketplace-invalid", `the new entries do not parse: ${check.errors.join("; ")}`);
-        return { added, findings };
+        return { added, removed, refreshed, findings };
     }
     await writeFile(opts.file, formatMarketplaceJson(next));
-    return { added, findings };
+    return { added, removed, refreshed, findings };
 }
+/** `name@version` of a parsed entry (`?` without a version). */
+const keyOf = (e) => `${e.name}@${versionOf(e) ?? "?"}`;
 /** `name@version` of a raw entry (`?` for what is missing). */
 function keyOfRaw(e) {
     if (!isObj(e))
@@ -153,7 +282,7 @@ function keyOfRaw(e) {
     const npm = isObj(e.source) && isObj(e.source.npm) ? e.source.npm : {};
     return `${String(e.name ?? "?")}@${String(e.version ?? npm.version ?? "?")}`;
 }
-/** JSON with object keys sorted (deep equality of entries regardless of key order). */
+/** JSON with object keys sorted (deep equality regardless of key order). */
 function canonical(v) {
     if (Array.isArray(v))
         return `[${v.map(canonical).join(",")}]`;
@@ -184,25 +313,68 @@ function entriesAt(root, file, base) {
     const raw = JSON.parse(text);
     return isObj(raw) && Array.isArray(raw.plugins) ? raw.plugins : [];
 }
+/** A raw entry's version when it is a plain semver (else undefined: not ordered). */
+function semverOfRaw(e) {
+    const v = keyOfRaw(e).split("@").pop();
+    return v !== undefined && parseSemver(v) !== undefined ? v : undefined;
+}
 /**
- * `marketplace-append-only`: the base's entries are published, so the current list must start with
- * exactly them, in the same order (an entry is never edited, removed or moved; new ones go last).
+ * The rules on the entries published at the base: `marketplace-integrity`, a version the base
+ * lists keeps its source (package and integrity); `marketplace-version-decrease`, a version the
+ * base does not list must be newer than every version the base lists for that plugin, and a
+ * plugin's newest listed version may not be older than the newest the base lists. Display
+ * fields (summary, displayName, permissions, homepage) may change, entries may move, and a
+ * plugin's older versions may go (one entry per plugin).
  */
-function appendOnly(base, current, file) {
+function publishedRules(base, current, file) {
     const out = [];
-    base.forEach((b, i) => {
-        const c = current[i];
-        if (c !== undefined && canonical(c) === canonical(b))
-            return;
-        const key = keyOfRaw(b);
-        const moved = current.some((x) => canonical(x) === canonical(b));
-        out.push({
-            file,
-            line: 1,
-            rule: "marketplace-append-only",
-            message: `${key} is published at the base and ${moved ? "moved" : c !== undefined && keyOfRaw(c) === key ? "was edited" : "went away"}: published entries never change and new ones are appended at the end`,
-        });
-    });
+    const finding = (rule, message) => out.push({ file, line: 1, rule, message });
+    const baseByKey = new Map(base.map((b) => [keyOfRaw(b), b]));
+    const newest = new Map();
+    for (const b of base) {
+        const v = semverOfRaw(b);
+        const name = isObj(b) ? String(b.name) : "?";
+        const top = newest.get(name);
+        if (v !== undefined && (top === undefined || compareSemver(v, top) > 0))
+            newest.set(name, v);
+    }
+    /** `name@version` of the entries reported as `marketplace-version-decrease`. */
+    const decreased = new Set();
+    for (const c of current) {
+        const key = keyOfRaw(c);
+        const b = baseByKey.get(key);
+        const src = (e) => (isObj(e) ? e.source : undefined);
+        if (b !== undefined) {
+            if (canonical(src(c)) !== canonical(src(b))) {
+                finding("marketplace-integrity", `${key} is published at the base with the source ${canonical(src(b))}, now ` +
+                    `${canonical(src(c))}: a published version keeps its integrity (bump the version instead)`);
+            }
+            continue;
+        }
+        const v = semverOfRaw(c);
+        const top = newest.get(isObj(c) ? String(c.name) : "?");
+        if (v !== undefined && top !== undefined && compareSemver(v, top) < 0)
+            decreased.add(key);
+    }
+    // A plugin's newest listed version may not fall below the newest the base lists, also when it
+    // moves back to an older version the base lists too (a base in the older form).
+    const newestNow = new Map();
+    for (const c of current) {
+        const v = semverOfRaw(c);
+        const name = isObj(c) ? String(c.name) : "?";
+        const top = newestNow.get(name);
+        if (v !== undefined && (top === undefined || compareSemver(v, top) > 0))
+            newestNow.set(name, v);
+    }
+    for (const [name, v] of newestNow) {
+        const top = newest.get(name);
+        if (top !== undefined && compareSemver(v, top) < 0)
+            decreased.add(`${name}@${v}`);
+    }
+    for (const key of decreased) {
+        const name = key.slice(0, key.lastIndexOf("@"));
+        finding("marketplace-version-decrease", `${key} is older than ${newest.get(name)}, which the base lists: an entry's version may only increase`);
+    }
     return out;
 }
 const INDENT = "  ";

package/dist/pack/cli.d.ts

@@ -1,19 +1,12 @@
-export declare const PACK_USAGE: string;
+export declare const PACK_USAGE = "capybara-plugin pack [<dir>...] [--all <root>] [--out <dir>]";
 /**
  * `capybara-plugin pack`: packs plugin directories into plugin tgz files.
  *
  * - `<dir>...`: the plugin directories to pack;
  * - `--all <root>`: also every plugin of the repository at `<root>` (`<root>/plugins/*`, or `<root>`
  *   itself when it is a plugin);
- * - `--bootstrap <manifest>`: the bootstrap directory an image bakes: every entry of the bootstrap
- *   manifest as `<name>-<version>.tgz`, checked against its pins (workspace entries' `path` is
- *   relative to `--root`, default the current directory; npm entries are downloaded from
- *   `--registry`, default `CAPYBARA_PACKAGES__NPM_REGISTRY` (the kernel's `packages.npmRegistry`)
- *   or else the public npm registry, and must match their pinned sha512; `--npm-token`, default
- *   `CAPYBARA_PACKAGES__NPM_TOKEN` (the kernel's `packages.npmToken`), is sent as a Bearer token to
- *   the registry origin only);
- * - `--out <dir>`: output directory, default `artifacts/plugins` (`artifacts/bootstrap` with
- *   `--bootstrap`) under the current directory. The last `--out` wins.
+ * - `--out <dir>`: output directory, default `artifacts/plugins` under the current directory. The
+ *   last `--out` wins.
  *
  * Relative paths resolve against `cwd` (the current directory). Returns the exit code.
  */