@deepseek-ai/dsh-plugin-market-index 0.0.0-stage → 0.2.1-alpha.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,34 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/util/plugin-market-index/README.md
+/:
+  en: be1a45173d5c1ce7
+  zh: a9a5a976e40e4a8a
+/dsh-plugin-market-index:
+  en: 78d8cc75e40d4e48
+  zh: 9db1a93fb07d4ded
+/dsh-plugin-market-index/summary:
+  en: f68c94d63c1ec0e5
+  zh: 52db4114eef7454d
+/dsh-plugin-market-index/table-of-contents:
+  en: cd2a60a905c978d6
+  zh: cc71d387d0cbd442
+/dsh-plugin-market-index/use-this-package:
+  en: 8eac2625e2e366a8
+  zh: 652131f240e929e0
+/dsh-plugin-market-index/api:
+  en: e0e4444616427bf2
+  zh: 3960a7602bb17705
+/dsh-plugin-market-index/model-experience:
+  en: c060b1659cf43243
+  zh: 4a2313822283291e
+/dsh-plugin-market-index/model-experience/kv-cache-effect:
+  en: a7a5484352ac021c
+  zh: fe00da8797e85e06
+/dsh-plugin-market-index/known-limitations-and-deferred-work:
+  en: acfbb04ae4682367
+  zh: 48af36f974976528
+/dsh-plugin-market-index/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+---
+description: "Plugin market index format 1 validation and install arguments for DSH readers and index generators."
+kind: "package-library"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-plugin-market-index
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Validator without runtime dependencies for format 1 of the plugin market index, the single JSON file that lists installable DSH bundles with their display metadata. [The format Agent Note](../../../.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.md) defines the document; this package is its executable rule set. DSH's [`dsh-plugin-market`](../../boot/plugin-market/README.md) reads indexes with it, and index generators validate their output with it before publishing.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [API](#api)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+It is a library, not a service or plugin: no `ctx`, no registrations, no state, no I/O.
+
+Parse the fetched document as JSON, then pass the value and the URL it was read from to `parseMarketIndex`. The first violated rule throws `MarketIndexError` with the JSON path of the offending value. A successful result drops members the format does not define, fills absent `metadata` groups, `keywords`, `labels`, `sortKeys`, and `engines` with empty values, orders each plugin's `versions` by descending SemVer precedence, and replaces each relative `icon` reference with its absolute URL.
+
+Install one version with `marketInstallTarget(name, version)`: it returns the exact pnpm spec, `name@version` for npm and a commit-pinned `git+https` URL with an optional `path:` parameter for Git, and the registry to ask first when the version names one.
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import { MarketIndexError, marketInstallTarget, parseMarketIndex } from '@deepseek-ai/dsh-plugin-market-index'
+```
+
+| Export | Role |
+|---|---|
+| `parseMarketIndex(value, indexUrl)` | Validated `MarketIndex`; throws `MarketIndexError` for the first violated rule. |
+| `marketInstallTarget(name, version)` | `{ spec, registry? }` that installs that exact version. |
+| `MarketIndexError` | Validation failure carrying `path` and `reason`. |
+| `MAX_INLINE_ICON_BYTES` | Largest decoded payload of an inline `data:` icon, 32 KiB. |
+| `MarketIndex`, `MarketPlugin`, `MarketVersion`, `MarketEngines`, `MarketSource`, `MarketRepository`, `MarketIndexMetadata`, `MarketPluginMetadata`, `MarketDeclaration`, `MarketSortKeyDeclaration`, `MarketInstallTarget` | Validated record types. |
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through `dsh-plugin-market`, whose `plugin_market` tool returns validated plugins to the model.
+
+#### KV Cache effect
+
+None of its own. The tool result that carries plugins owns its request's cache behavior.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **Generator obligations are unchecked** — the validator cannot verify that `name`, `version`, `publishTimestamp`, `engines.dsh`, or display fields match the package they describe, or that the package declares a bundle.
+- **No size bound** — the caller bounds the document before parsing it.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,74 @@
+---
+description: "供 DSH 读取器和索引生成器使用的插件市场索引格式 1 校验与安装参数。"
+kind: "package-library"
+---
+
+# dsh-plugin-market-index
+
+[English](README.md) | 中文
+
+## 概述
+
+插件市场索引格式 1 的校验器，没有运行时依赖。插件市场索引是一份 JSON 文件，列出可安装的 DSH 组合包（bundle）及其展示元数据。[格式 Agent Note](../../../.agents/notes/implemented/feature/2026-10-02-plugin-market-index-format.zh.md) 定义该文档；本包是其可执行的规则集。DSH 的 [`dsh-plugin-market`](../../boot/plugin-market/README.zh.md) 用它读取索引，索引生成器在发布前用它校验输出。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [API](#api)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+本包是库，不是服务或插件：没有 `ctx`、没有注册、没有状态，也没有 I/O。
+
+先把获取到的文档解析为 JSON，再把该值和读取它的 URL 传给 `parseMarketIndex`。遇到第一条被违反的规则时，它抛出 `MarketIndexError`，并附带违规值的 JSON 路径。成功的结果会丢弃格式未定义的成员，用空值填充缺失的 `metadata` 分组、`keywords`、`labels`、`sortKeys` 和 `engines`，按 SemVer 优先级降序排列每个插件的 `versions`，并把每个相对 `icon` 引用替换为其绝对 URL。
+
+使用 `marketInstallTarget(name, version)` 安装一个版本：它返回精确的 pnpm spec（npm 为 `name@version`，Git 为固定到提交、可带 `path:` 参数的 `git+https` URL），该版本指定了 registry 时还返回首先询问的 registry。
+
+-----
+
+<a id="api"></a>
+## API
+
+```ts
+import { MarketIndexError, marketInstallTarget, parseMarketIndex } from '@deepseek-ai/dsh-plugin-market-index'
+```
+
+| 导出 | 作用 |
+|---|---|
+| `parseMarketIndex(value, indexUrl)` | 经过校验的 `MarketIndex`；遇到第一条被违反的规则时抛出 `MarketIndexError`。 |
+| `marketInstallTarget(name, version)` | 安装该精确版本的 `{ spec, registry? }`。 |
+| `MarketIndexError` | 携带 `path` 和 `reason` 的校验失败。 |
+| `MAX_INLINE_ICON_BYTES` | 内联 `data:` 图标解码后载荷的最大字节数，即 32 KiB。 |
+| `MarketIndex`, `MarketPlugin`, `MarketVersion`, `MarketEngines`, `MarketSource`, `MarketRepository`, `MarketIndexMetadata`, `MarketPluginMetadata`, `MarketDeclaration`, `MarketSortKeyDeclaration`, `MarketInstallTarget` | 经过校验的记录类型。 |
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接存在：通过 `dsh-plugin-market`，其 `plugin_market` 工具把经过校验的插件返回给模型。
+
+#### KV Cache 影响
+
+本包自身没有。携带插件的工具结果决定其请求的缓存行为。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **不检查生成器义务**——校验器无法验证 `name`、`version`、`publishTimestamp`、`engines.dsh` 或展示字段是否与其描述的包一致，也无法验证该包是否声明了组合包。
+- **没有大小上限**——调用方在解析前限制文档大小。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>

package/lib/index.js

@@ -0,0 +1,320 @@
+import semver from "semver";
+//#region lib/types/index.js
+/**
+* Plugin market index format 1: JSON validation, relative icon resolution, and install arguments.
+* The format is defined by the plugin market index format Agent Note; readers and generators share this validator.
+* @module @deepseek-ai/dsh-plugin-market-index
+*/
+/** An index that violates format 1; `path` is the JSON path of the offending value, such as `$.plugins[0].versions[1].version`. */
+var MarketIndexError = class extends Error {
+	path;
+	reason;
+	/**
+	* @param path - JSON path of the offending value.
+	* @param reason - the violated rule.
+	*/
+	constructor(path, reason) {
+		super(`${path} ${reason}`);
+		this.path = path;
+		this.reason = reason;
+		this.name = "MarketIndexError";
+	}
+};
+const LANGUAGE_ID = /^[a-z]{2,8}(?:-[a-z0-9]{1,8})*$/u;
+const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/u;
+const PACKAGE_NAME_MAX_LENGTH = 214;
+/** The SemVer 2.0.0 grammar for one exact version. */
+const NUMERIC = "(?:0|[1-9]\\d*)";
+const PRERELEASE_PART = `(?:${NUMERIC}|\\d*[a-zA-Z-][0-9a-zA-Z-]*)`;
+const SEMVER = new RegExp(`^${NUMERIC}\\.${NUMERIC}\\.${NUMERIC}(?:-${PRERELEASE_PART}(?:\\.${PRERELEASE_PART})*)?(?:\\+[0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*)?$`, "u");
+const COMMIT = /^[0-9a-f]{40}$/u;
+const PATH_SEGMENT = /^[A-Za-z0-9._@+-]+$/u;
+const DATA_ICON = /^data:(?:image\/svg\+xml|image\/png|image\/jpeg|image\/webp);base64,([A-Za-z0-9+/]*={0,2})$/u;
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u;
+/** Largest decoded payload of an inline `data:` icon, in bytes. */
+const MAX_INLINE_ICON_BYTES = 32 * 1024;
+const MAX_PUBLISH_TIMESTAMP = 1e11;
+function fail(path, reason) {
+	throw new MarketIndexError(path, reason);
+}
+function objectAt(value, path) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) fail(path, "must be an object");
+	return value;
+}
+function stringAt(value, path) {
+	if (typeof value !== "string" || value.trim() === "") fail(path, "must be a string with a non-whitespace character");
+	return value;
+}
+function optional(object, key, path, read) {
+	return Object.hasOwn(object, key) ? read(object[key], `${path}.${key}`) : void 0;
+}
+function localizedText(value, path) {
+	if (typeof value === "string") return stringAt(value, path);
+	const object = objectAt(value, path);
+	const text = {};
+	for (const [language, member] of Object.entries(object)) {
+		if (!LANGUAGE_ID.test(language)) fail(`${path}.${language}`, "must be keyed by a lowercase language id");
+		own(text, language, stringAt(member, `${path}.${language}`));
+	}
+	if (!Object.hasOwn(text, "en")) fail(path, "must contain en");
+	return text;
+}
+/** Define an own enumerable member, so an id such as `__proto__` stays an ordinary key. */
+function own(record, key, value) {
+	Object.defineProperty(record, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
+function declarations(value, path, read) {
+	const result = {};
+	for (const [id, member] of Object.entries(objectAt(value, path))) {
+		if (id === "") fail(path, "must not declare an empty id");
+		own(result, id, read(objectAt(member, `${path}.${id}`), `${path}.${id}`));
+	}
+	return result;
+}
+function declaration(object, path) {
+	return { title: localizedText(object.title, `${path}.title`) };
+}
+function sortKeyDeclaration(object, path) {
+	if (object.order !== "asc" && object.order !== "desc") fail(`${path}.order`, "must be \"asc\" or \"desc\"");
+	return {
+		title: localizedText(object.title, `${path}.title`),
+		order: object.order
+	};
+}
+function indexMetadata(value, path) {
+	const object = value === void 0 ? {} : objectAt(value, path);
+	return {
+		categories: optional(object, "categories", path, (member, at) => declarations(member, at, declaration)) ?? {},
+		labels: optional(object, "labels", path, (member, at) => declarations(member, at, declaration)) ?? {},
+		sortKeys: optional(object, "sortKeys", path, (member, at) => declarations(member, at, sortKeyDeclaration)) ?? {}
+	};
+}
+function declaredId(value, path, declared) {
+	const id = stringAt(value, path);
+	if (!Object.hasOwn(declared, id)) fail(path, `references undeclared id ${JSON.stringify(id)}`);
+	return id;
+}
+function pluginMetadata(value, path, index) {
+	const object = value === void 0 ? {} : objectAt(value, path);
+	const category = optional(object, "category", path, (member, at) => declaredId(member, at, index.categories));
+	const keywords = optional(object, "keywords", path, (member, at) => {
+		if (!Array.isArray(member)) fail(at, "must be an array");
+		return member.map((keyword, position) => {
+			if (typeof keyword !== "string") fail(`${at}[${String(position)}]`, "must be a string");
+			return keyword;
+		});
+	}) ?? [];
+	const labels = optional(object, "labels", path, (member, at) => {
+		if (!Array.isArray(member)) fail(at, "must be an array");
+		const ids = member.map((label, position) => declaredId(label, `${at}[${String(position)}]`, index.labels));
+		if (new Set(ids).size !== ids.length) fail(at, "must not repeat a label");
+		return ids;
+	}) ?? [];
+	const sortKeys = optional(object, "sortKeys", path, (member, at) => {
+		const values = {};
+		for (const [id, sortValue] of Object.entries(objectAt(member, at))) {
+			declaredId(id, `${at}.${id}`, index.sortKeys);
+			if (typeof sortValue !== "number" || !Number.isFinite(sortValue)) fail(`${at}.${id}`, "must be a finite number");
+			own(values, id, sortValue);
+		}
+		return values;
+	}) ?? {};
+	return {
+		...category === void 0 ? {} : { category },
+		keywords,
+		labels,
+		sortKeys
+	};
+}
+function httpUrl(value, path, protocols) {
+	const text = stringAt(value, path);
+	let url;
+	try {
+		url = new URL(text);
+	} catch {
+		fail(path, "must be an absolute URL");
+	}
+	if (!protocols.includes(url.protocol)) fail(path, `must use ${protocols.join(" or ")}`);
+	if (url.username !== "" || url.password !== "") fail(path, "must not contain credentials");
+	if (url.href.includes("?") || url.href.includes("#")) fail(path, "must not contain a query or fragment");
+	return url;
+}
+/** An absolute http(s) URL; npm `homepage` values often carry a `#readme` fragment, so fragments and queries are kept. */
+function homepageUrl(value, path) {
+	const text = stringAt(value, path);
+	if (!URL.canParse(text)) fail(path, "must be an absolute URL");
+	const url = new URL(text);
+	if (url.protocol !== "https:" && url.protocol !== "http:") fail(path, "must use https: or http:");
+	return url.href;
+}
+function gitUrl(value, path) {
+	const url = httpUrl(value, path, ["https:"]);
+	if (url.href !== value) fail(path, "must be a canonical URL");
+	if (!/^(?:\/[^/]+){2,}$/u.test(url.pathname)) fail(path, "must name a repository with at least two path segments");
+	if (/\.(?:tgz|tar\.gz)$/iu.test(url.pathname)) fail(path, "must name a repository, not a tarball");
+	return url.href;
+}
+function packagePath(value, path) {
+	const text = stringAt(value, path);
+	if (text.split("/").some((segment) => segment === "." || segment === ".." || !PATH_SEGMENT.test(segment))) fail(path, "must be a relative directory of letters, digits, and ._@+- segments without . or ..");
+	return text;
+}
+function repository(value, path) {
+	const object = objectAt(value, path);
+	const url = httpUrl(object.url, `${path}.url`, ["https:", "http:"]).href;
+	const directory = optional(object, "directory", path, packagePath);
+	return {
+		url,
+		...directory === void 0 ? {} : { directory }
+	};
+}
+function source(value, path) {
+	const object = objectAt(value, path);
+	switch (object.type) {
+		case "npm": {
+			const registry = optional(object, "registry", path, (member, at) => httpUrl(member, at, ["https:", "http:"]).href);
+			return {
+				type: "npm",
+				...registry === void 0 ? {} : { registry }
+			};
+		}
+		case "git": {
+			const commit = stringAt(object.commit, `${path}.commit`);
+			if (!COMMIT.test(commit)) fail(`${path}.commit`, "must be a lowercase 40-hex-digit commit SHA");
+			const packageDir = optional(object, "path", path, packagePath);
+			return {
+				type: "git",
+				url: gitUrl(object.url, `${path}.url`),
+				commit,
+				...packageDir === void 0 ? {} : { path: packageDir }
+			};
+		}
+		default: return fail(`${path}.type`, "must be \"npm\" or \"git\"");
+	}
+}
+function engines(value, path) {
+	const dsh = optional(objectAt(value, path), "dsh", path, (member, at) => {
+		const range = stringAt(member, at);
+		if (range.startsWith("workspace:")) fail(at, "must not be a workspace: range");
+		if (semver.validRange(range) === null) fail(at, "must be a SemVer range");
+		return range;
+	});
+	return dsh === void 0 ? {} : { dsh };
+}
+function icon(value, path, indexUrl) {
+	const text = stringAt(value, path);
+	if (text.startsWith("data:")) {
+		const payload = DATA_ICON.exec(text)?.[1];
+		if (payload === void 0 || payload === "" || !BASE64.test(payload)) fail(path, "must be a base64 SVG, PNG, JPEG, or WebP data URL");
+		if (payload.length / 4 * 3 - (payload.endsWith("==") ? 2 : payload.endsWith("=") ? 1 : 0) > 32768) fail(path, `must not exceed ${String(MAX_INLINE_ICON_BYTES / 1024)} KiB of decoded bytes`);
+		return text;
+	}
+	let resolved;
+	try {
+		resolved = new URL(text, indexUrl);
+	} catch {
+		fail(path, "must be a URL reference");
+	}
+	if (resolved.protocol !== "https:" && (resolved.origin === "null" || resolved.origin !== indexUrl.origin)) fail(path, "must resolve to https or the index origin");
+	return resolved.href;
+}
+function marketVersion(value, path) {
+	const object = objectAt(value, path);
+	const version = stringAt(object.version, `${path}.version`);
+	if (!SEMVER.test(version)) fail(`${path}.version`, "must be an exact SemVer version");
+	const publishTimestamp = object.publishTimestamp;
+	if (typeof publishTimestamp !== "number" || !Number.isInteger(publishTimestamp) || publishTimestamp < 0 || publishTimestamp >= MAX_PUBLISH_TIMESTAMP) fail(`${path}.publishTimestamp`, "must be an integer number of Unix seconds in [0, 10^11)");
+	return {
+		version,
+		publishTimestamp,
+		source: source(object.source, `${path}.source`),
+		engines: optional(object, "engines", path, engines) ?? {}
+	};
+}
+function versions(value, path) {
+	if (!Array.isArray(value) || value.length === 0) fail(path, "must be a non-empty array");
+	const seen = /* @__PURE__ */ new Set();
+	return value.map((member, position) => {
+		const at = `${path}[${String(position)}]`;
+		const entry = marketVersion(member, at);
+		if (seen.has(entry.version)) fail(`${at}.version`, `duplicates ${entry.version}`);
+		seen.add(entry.version);
+		return entry;
+	}).sort((left, right) => semver.rcompare(left.version, right.version));
+}
+function plugin(value, path, index, indexUrl) {
+	const object = objectAt(value, path);
+	const name = stringAt(object.name, `${path}.name`);
+	if (name.length > PACKAGE_NAME_MAX_LENGTH || !PACKAGE_NAME.test(name)) fail(`${path}.name`, "must be a valid npm package name");
+	const title = optional(object, "title", path, localizedText);
+	const description = optional(object, "description", path, localizedText);
+	const iconUrl = optional(object, "icon", path, (member, at) => icon(member, at, indexUrl));
+	const author = optional(object, "author", path, stringAt);
+	const homepage = optional(object, "homepage", path, homepageUrl);
+	const repo = optional(object, "repository", path, repository);
+	return {
+		name,
+		...title === void 0 ? {} : { title },
+		...description === void 0 ? {} : { description },
+		...iconUrl === void 0 ? {} : { icon: iconUrl },
+		...author === void 0 ? {} : { author },
+		...homepage === void 0 ? {} : { homepage },
+		...repo === void 0 ? {} : { repository: repo },
+		metadata: pluginMetadata(object.metadata, `${path}.metadata`, index),
+		versions: versions(object.versions, `${path}.versions`)
+	};
+}
+/**
+* Validate a parsed format-1 index. Members the format does not define are ignored and dropped.
+* @param value - the parsed JSON document.
+* @param indexUrl - absolute URL the index was read from; relative icon references resolve against it.
+* @returns the validated index with absent metadata groups and lists filled with empty values, and each plugin's
+*   versions in descending SemVer precedence.
+* @throws {MarketIndexError} for the first violated rule.
+*/
+function parseMarketIndex(value, indexUrl) {
+	if (!URL.canParse(indexUrl)) fail("$", `index URL ${JSON.stringify(indexUrl)} must be an absolute URL`);
+	const base = new URL(indexUrl);
+	const object = objectAt(value, "$");
+	if (object.format !== 1) fail("$.format", "must be 1");
+	const metadata = indexMetadata(object.metadata, "$.metadata");
+	if (!Array.isArray(object.plugins)) fail("$.plugins", "must be an array");
+	const names = /* @__PURE__ */ new Set();
+	const plugins = object.plugins.map((entry, position) => {
+		const parsed = plugin(entry, `$.plugins[${String(position)}]`, metadata, base);
+		if (names.has(parsed.name)) fail(`$.plugins[${String(position)}].name`, `duplicates ${parsed.name}`);
+		names.add(parsed.name);
+		return parsed;
+	});
+	const title = localizedText(object.title, "$.title");
+	const description = optional(object, "description", "$", localizedText);
+	return {
+		format: 1,
+		title,
+		...description === void 0 ? {} : { description },
+		metadata,
+		plugins
+	};
+}
+/**
+* Build the arguments that install one exact version: `name@version` for npm, and a `git+https` URL pinned to the
+* commit, with pnpm's `path:` parameter for a package directory, for Git.
+* @param name - the plugin's package name.
+* @param version - a validated version of that plugin.
+* @returns the install spec and the registry to ask first, when the version names one.
+*/
+function marketInstallTarget(name, version) {
+	const { source: from } = version;
+	if (from.type === "npm") return {
+		spec: `${name}@${version.version}`,
+		...from.registry === void 0 ? {} : { registry: from.registry }
+	};
+	return { spec: `git+${from.url.endsWith(".git") ? from.url : `${from.url}.git`}#${from.commit}${from.path === void 0 ? "" : `&path:/${from.path}`}` };
+}
+//#endregion
+export { MAX_INLINE_ICON_BYTES, MarketIndexError, marketInstallTarget, parseMarketIndex };

package/lib/types/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Plugin market index format 1: JSON validation, relative icon resolution, and install arguments.
+ * The format is defined by the plugin market index format Agent Note; readers and generators share this validator.
+ * @module @deepseek-ai/dsh-plugin-market-index
+ */
+import type { MarketIndex, MarketInstallTarget, MarketVersion } from './types.ts';
+export type * from './types.ts';
+/** An index that violates format 1; `path` is the JSON path of the offending value, such as `$.plugins[0].versions[1].version`. */
+export declare class MarketIndexError extends Error {
+    readonly path: string;
+    readonly reason: string;
+    /**
+     * @param path - JSON path of the offending value.
+     * @param reason - the violated rule.
+     */
+    constructor(path: string, reason: string);
+}
+/** Largest decoded payload of an inline `data:` icon, in bytes. */
+export declare const MAX_INLINE_ICON_BYTES: number;
+/**
+ * Validate a parsed format-1 index. Members the format does not define are ignored and dropped.
+ * @param value - the parsed JSON document.
+ * @param indexUrl - absolute URL the index was read from; relative icon references resolve against it.
+ * @returns the validated index with absent metadata groups and lists filled with empty values, and each plugin's
+ *   versions in descending SemVer precedence.
+ * @throws {MarketIndexError} for the first violated rule.
+ */
+export declare function parseMarketIndex(value: unknown, indexUrl: string): MarketIndex;
+/**
+ * Build the arguments that install one exact version: `name@version` for npm, and a `git+https` URL pinned to the
+ * commit, with pnpm's `path:` parameter for a package directory, for Git.
+ * @param name - the plugin's package name.
+ * @param version - a validated version of that plugin.
+ * @returns the install spec and the registry to ask first, when the version names one.
+ */
+export declare function marketInstallTarget(name: string, version: Pick<MarketVersion, 'version' | 'source'>): MarketInstallTarget;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Validated plugin market index records.
+ * @module @deepseek-ai/dsh-plugin-market-index/types
+ */
+import type { LocalizedText } from '@deepseek-ai/dsh-package-manifest';
+/** A market-declared category or label: an opaque id's display title. */
+export interface MarketDeclaration {
+    readonly title: LocalizedText;
+}
+/** A market-declared sort key: its display title and initial direction. */
+export interface MarketSortKeyDeclaration {
+    readonly title: LocalizedText;
+    readonly order: 'asc' | 'desc';
+}
+/** Market-defined declarations; absent groups are empty records. */
+export interface MarketIndexMetadata {
+    readonly categories: Readonly<Record<string, MarketDeclaration>>;
+    readonly labels: Readonly<Record<string, MarketDeclaration>>;
+    readonly sortKeys: Readonly<Record<string, MarketSortKeyDeclaration>>;
+}
+/** Market-defined values of one plugin; category, label, and sort-key ids require index declarations. */
+export interface MarketPluginMetadata {
+    readonly category?: string;
+    /** Free-form strings, conventionally from package keywords; absent input becomes an empty array. */
+    readonly keywords: readonly string[];
+    readonly labels: readonly string[];
+    readonly sortKeys: Readonly<Record<string, number>>;
+}
+/** Where a plugin's source code is published; display only, never an install source. */
+export interface MarketRepository {
+    /** Absolute http(s) URL of the repository's web page, without credentials, query, or fragment. */
+    readonly url: string;
+    /** Relative POSIX directory of the package inside the repository; absent means the repository root. */
+    readonly directory?: string;
+}
+/** Where one exact version is installed from. */
+export type MarketSource = {
+    readonly type: 'npm';
+    /** http(s) registry URL; absent means the installing client's configured registry. */
+    readonly registry?: string;
+} | {
+    readonly type: 'git';
+    /** Canonical https repository URL without credentials, query, or fragment. */
+    readonly url: string;
+    /** Lowercase 40-hex-digit commit SHA. */
+    readonly commit: string;
+    /** Relative POSIX package directory; absent means the repository root. */
+    readonly path?: string;
+};
+/** Runtime requirements of one version. */
+export interface MarketEngines {
+    /** SemVer range of DSH versions the version runs on; absent means any DSH version. */
+    readonly dsh?: string;
+}
+/** One installable version of a plugin. */
+export interface MarketVersion {
+    /** Exact SemVer version, unique within its plugin. */
+    readonly version: string;
+    /** Publish time of `version` in Unix seconds. */
+    readonly publishTimestamp: number;
+    readonly source: MarketSource;
+    readonly engines: MarketEngines;
+}
+/** One installable bundle and its listed versions. */
+export interface MarketPlugin {
+    /** npm package name, unique within its index. */
+    readonly name: string;
+    readonly title?: LocalizedText;
+    readonly description?: LocalizedText;
+    /** Base64 `data:` URL or absolute URL; a relative index reference is already resolved against the index URL. */
+    readonly icon?: string;
+    readonly author?: string;
+    /** Absolute http(s) URL of a page about the plugin. */
+    readonly homepage?: string;
+    /** Web page of the plugin's source repository and its package directory; display only. */
+    readonly repository?: MarketRepository;
+    readonly metadata: MarketPluginMetadata;
+    /** Non-empty, in descending SemVer precedence. */
+    readonly versions: readonly MarketVersion[];
+}
+/** One validated format-1 index; members the format does not define are dropped. */
+export interface MarketIndex {
+    readonly format: 1;
+    readonly title: LocalizedText;
+    readonly description?: LocalizedText;
+    readonly metadata: MarketIndexMetadata;
+    /** Plugins in the index's default order. */
+    readonly plugins: readonly MarketPlugin[];
+}
+/** The arguments that install one exact version. */
+export interface MarketInstallTarget {
+    /** Install spec accepted by `pnpm add`. */
+    readonly spec: string;
+    /** Registry to ask first; absent means the installing client's configured registry. */
+    readonly registry?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@deepseek-ai/dsh-plugin-market-index",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Plugin market index format 1: JSON validation, relative icon resolution, and pinned install arguments",
+  "version": "0.2.1-alpha.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/plugin-market-index"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/dsh-package-manifest": "0.2.1-alpha.4",
+    "semver": "^7.8.5"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.5-alpha.2",
+    "@types/semver": "^7.8.0"
+  }
 }