@capybara-hq/plugin-tools 0.1.0-rc.7 → 0.1.0-rc.8

package/dist/marketplace/cli.d.ts

@@ -16,7 +16,8 @@ export declare const MARKETPLACE_USAGE: string;
  * `--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 and displayName) and exits 1 only on `marketplace-invalid`.
+ * 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

@@ -22,7 +22,8 @@ export const MARKETPLACE_USAGE = "capybara-plugin marketplace --write|--check [-
  * `--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 and displayName) and exits 1 only on `marketplace-invalid`.
+ * 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) {

package/dist/marketplace/marketplace.d.ts

@@ -28,7 +28,7 @@ export interface SyncMarketplaceResult {
     /** `name@version` of the other entries of the tree's plugins (dropped with `write`). */
     removed: string[];
     /**
-     * `name@version` of listed entries whose `summary` / `displayName` differ from plugin.json
+     * `name@version` of listed entries whose `summary` / `displayName` / `icon` differ from plugin.json
      * (rewritten with `write`; source and integrity never change).
      */
     refreshed: string[];
@@ -37,25 +37,33 @@ export interface SyncMarketplaceResult {
      * `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 differ from plugin.json).
+     * `marketplace-display-stale` (a listed entry's summary / displayName / icon differ from plugin.json).
      */
     findings: 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?, homepage?, permissions, source: { npm: {
- * package, version, integrity } } }` (`summary` from the plugin.json `description`, a string being
- * `en`; `displayName` copied from plugin.json; `integrity` the pack's sha512, which the release
+ * 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`) are refreshed from the source plugin.json. Every other field
+ * 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

package/dist/marketplace/marketplace.js

@@ -36,39 +36,60 @@ 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);
-/** The display fields of a plugin's source plugin.json; undefined when it does not parse. */
-function displayOf(json) {
+/**
+ * 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` and `displayName` set to `d` (in place, `displayName` right after
- * `summary` when it is new, removed when plugin.json has none); undefined when they already equal.
+ * `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) &&
-        canonical(raw.displayName) === canonical(d.displayName)) {
+        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 (k === "displayName")
+        if (AFTER_SUMMARY.includes(k))
             continue;
         out[k] = k === "summary" ? d.summary : v;
-        if (k === "summary" && d.displayName !== undefined)
-            out.displayName = d.displayName;
+        if (k === "summary")
+            after(out);
     }
     if (!("summary" in raw)) {
         out.summary = d.summary;
-        if (d.displayName !== undefined)
-            out.displayName = d.displayName;
+        after(out);
     }
     return out;
 }
@@ -77,16 +98,18 @@ function refreshDisplay(raw, d) {
  * 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?, homepage?, permissions, source: { npm: {
- * package, version, integrity } } }` (`summary` from the plugin.json `description`, a string being
- * `en`; `displayName` copied from plugin.json; `integrity` the pack's sha512, which the release
+ * 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`) are refreshed from the source plugin.json. Every other field
+ * 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
@@ -150,7 +173,7 @@ export async function syncMarketplace(opts) {
             const kept = listed[0];
             /** Keeps the listed entry: drops the other versions, refreshes its display fields. */
             const keep = (raw) => {
-                const display = displayOf(source);
+                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;
@@ -188,6 +211,9 @@ export async function syncMarketplace(opts) {
                 version: npm.version,
                 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 },

package/dist/pack/pack.js

@@ -7,7 +7,7 @@ import { dirname, join, posix, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { promisify } from "node:util";
 import { gzip } from "node:zlib";
-import { AGENT_TEMPLATE_LIMITS, checkEntryImports, defineExtension, HOST_PROVIDED_PACKAGES, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, SDK_VERSION, staticManifestOf, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
+import { AGENT_TEMPLATE_LIMITS, checkEntryImports, defineExtension, HOST_PROVIDED_PACKAGES, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, SDK_VERSION, setupGuideFileProblem, staticManifestOf, unknownSetupGuidePlaceholders, validatePluginPackageJsonFor, } from "@capybara-hq/plugin-sdk";
 import { init as lexerInit, parse as lexerParse } from "es-module-lexer";
 import { build } from "esbuild";
 import { pack as tarPack } from "tar-stream";
@@ -167,6 +167,8 @@ const SHIPPED_ELSEWHERE = [
     "skills",
     "connectors",
     "agents",
+    // setup guide templates: the listed files are shipped by contentFiles
+    "guides",
     ".capybara-plugin",
     "README.md",
     "LICENSE",
@@ -357,6 +359,32 @@ async function contentFiles(dir, label, m) {
         }
         agentNames.set(t.template.name, rel);
     }
+    // Setup guides (spec 2026-11-08-plugin-setup-guides-design.md §2): the listed template files,
+    // text within the size limit, and only placeholders the place defines (the kernel leaves an
+    // unknown one visible; the toolchain refuses it so a typo never ships)
+    for (const g of m.setupGuides ?? []) {
+        const at = `${label}: setupGuides ${g.id}`;
+        const unknown = (text, where) => {
+            const names = unknownSetupGuidePlaceholders(text, g.place);
+            if (names.length > 0) {
+                throw new Error(`${at}: ${where} uses ${names.map((n) => `{{${n}}}`).join(", ")}, which place ${g.place} does not define`);
+            }
+        };
+        g.steps?.forEach((step, i) => {
+            unknown(step.en, `step ${i + 1}`);
+            if (step.zh !== undefined)
+                unknown(step.zh, `step ${i + 1} (zh)`);
+        });
+        for (const f of g.files ?? []) {
+            const rel = stripDot(f.path);
+            await addFile(rel, `setup guide ${g.id} file`);
+            const data = files.get(rel);
+            const problem = setupGuideFileProblem(f.path, new Uint8Array(data));
+            if (problem !== undefined)
+                throw new Error(`${at}: ${problem}`);
+            unknown(data.toString("utf8"), f.path);
+        }
+    }
     return {
         files,
         skills: m.skills?.length ?? scannedSkills,
@@ -505,6 +533,9 @@ export async function packPlugin(pluginDir, outDir) {
         throw new Error(`${label}: a plugin must contain an extension, a skill, a connector template or an agent template (src/index.ts, skills/<name>/SKILL.md, connectors/<id>.json or agents/<name>.md)`);
     }
     const ext = hasExtension ? await bundleExtension(dir, label, srcPkg.version) : undefined;
+    if (ext === undefined && source.setupGuides?.some((g) => g.place === "channel-connection")) {
+        throw new Error(`${label}: a channel-connection setup guide needs the plugin's extension to provide channel@1 (src/index.ts)`);
+    }
     const files = new Map([...(ext?.files ?? []), ...content.files]);
     const extra = await extraFiles(dir, srcPkg.files);
     for (const [path, data] of extra.files)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-tools",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
   "description": "Capybara plugin toolchain: the capybara-plugin CLI to pack, check and release Capybara plugins",
   "license": "Apache-2.0",
   "repository": {
@@ -51,12 +51,12 @@
     "esbuild": "0.28.2",
     "oxc-parser": "^0.154.0",
     "tar-stream": "3.2.2",
-    "@capybara-hq/plugin-sdk": "^0.1.0-rc.6",
-    "@capybara-hq/kernel": "^0.1.0-rc.9"
+    "@capybara-hq/kernel": "^0.1.0-rc.10",
+    "@capybara-hq/plugin-sdk": "^0.1.0-rc.7"
   },
   "devDependencies": {
     "zod": "^4.6.7",
-    "@capybara-hq/testing": "0.1.0-rc.9"
+    "@capybara-hq/testing": "0.1.0-rc.10"
   },
   "scripts": {
     "build": "tsc -b"