@sparkelf/dsh-plus 0.2.1-rc.2.4 → 0.2.2-alpha.2.1

package/lib/bin.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { r as runApply } from "./apply-e0aMC4B4.js";
+import { i as readPatchSet, r as runApply } from "./apply-08huHfLG.js";
 import { createRequire } from "node:module";
 import { execFileSync, spawn, spawnSync } from "node:child_process";
 import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
@@ -858,6 +858,11 @@ function requireStringArray(value, label) {
 	if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) throw new Error(label + " must be a string array");
 	return value;
 }
+/** Read one non-empty string field. */
+function requireString(value, label) {
+	if (typeof value !== "string" || value.trim() === "") throw new Error(label + " must be a non-empty string");
+	return value;
+}
 /** Resolve the DSH home, honouring the environment override the launcher itself reads. */
 function resolveHome(env = process.env) {
 	const configured = env.DSH_HOME;
@@ -910,18 +915,12 @@ function resolveDistributionDirectory(anchor) {
 	}
 	throw new Error("@sparkelf/dsh-plus resolved outside " + resolve(dirname(anchor)) + " (found " + resolved + "); run this command from the directory that installed it");
 }
-/** The reviewed bundle order and pins the installed distribution declares. */
 function readDistributionProfile(distributionDirectory) {
 	const manifest = requireRecord(JSON.parse(readFileSync(join(distributionDirectory, "package.json"), "utf8")), "Plus distribution manifest");
 	const plus = requireRecord(manifest.dshPlus, "dshPlus");
 	const profile = requireRecord(plus.profile, "dshPlus.profile");
-	const rawDependencies = requireRecord(profile.dependencies, "dshPlus.profile.dependencies");
+	const dependencies = requireDependencyMap(requireRecord(profile.dependencies, "dshPlus.profile.dependencies"), "dshPlus.profile.dependencies");
 	const rawAllowBuilds = requireRecord(profile.allowBuilds, "dshPlus.profile.allowBuilds");
-	const dependencies = {};
-	for (const [name, spec] of Object.entries(rawDependencies)) {
-		if (typeof spec !== "string" || spec === "") throw new Error("dshPlus.profile.dependencies." + name + " must be a non-empty string");
-		dependencies[name] = spec;
-	}
 	const allowBuilds = {};
 	for (const [name, allowed] of Object.entries(rawAllowBuilds)) {
 		if (typeof allowed !== "boolean") throw new Error("dshPlus.profile.allowBuilds." + name + " must be a boolean");
@@ -933,6 +932,16 @@ function readDistributionProfile(distributionDirectory) {
 		if (typeof spec !== "string" || spec === "") throw new Error("dshPlus.profile.overrides." + name + " must be a non-empty string");
 		overrides[name] = spec;
 	}
+	const editions = {};
+	const rawEditions = plus.editions === void 0 ? {} : requireRecord(plus.editions, "dshPlus.editions");
+	for (const [id, value] of Object.entries(rawEditions)) {
+		const edition = requireRecord(value, "dshPlus.editions." + id);
+		editions[id] = {
+			label: requireString(edition.label, "dshPlus.editions." + id + ".label"),
+			bundles: requireStringArray(edition.bundles, "dshPlus.editions." + id + ".bundles"),
+			packages: requireDependencyMap(requireRecord(edition.packages, "dshPlus.editions." + id + ".packages"), "dshPlus.editions." + id + ".packages")
+		};
+	}
 	const compatibility = requireRecord(plus.compatibility, "dshPlus.compatibility");
 	return {
 		name: String(manifest.name),
@@ -940,10 +949,20 @@ function readDistributionProfile(distributionDirectory) {
 		dependencies,
 		allowBuilds,
 		overrides,
+		editions,
 		dshRange: String(compatibility.dsh),
 		version: String(manifest.version)
 	};
 }
+/** Read one package-name-to-spec map, rejecting empty entries. */
+function requireDependencyMap(value, label) {
+	const dependencies = {};
+	for (const [name, spec] of Object.entries(value)) {
+		if (typeof spec !== "string" || spec === "") throw new Error(label + "." + name + " must be a non-empty string");
+		dependencies[name] = spec;
+	}
+	return dependencies;
+}
 /**
 * Give the profile its own installed tree, built from the distribution's declarations.
 *
@@ -993,7 +1012,8 @@ function installWithRegistryFallback(paths) {
 		], {
 			cwd: paths.profileDirectory,
 			stdio: "inherit",
-			shell: process.platform === "win32"
+			shell: process.platform === "win32",
+			timeout: 5 * 6e4
 		});
 		if (result.error !== void 0) throw result.error;
 		if (result.status === 0) return;
@@ -1153,12 +1173,35 @@ function resolvePaths(anchor, env = process.env) {
 *
 * @param paths - resolved standalone paths.
 * @param consumerDirectory - directory whose `node_modules` holds the installed packages.
+* @param edition - edition id whose package list to install, or undefined for the default.
 * @returns whether this call created the manifest.
 */
-function ensureProfile(paths, consumerDirectory) {
+function ensureProfile(paths, consumerDirectory, edition) {
 	const manifestPath = join(paths.profileDirectory, "package.json");
 	const distribution = readDistributionProfile(paths.distributionDirectory);
+	const composition = edition === void 0 ? void 0 : distribution.editions[edition];
+	if (edition !== void 0 && composition === void 0) {
+		const offered = Object.keys(distribution.editions);
+		throw new Error("unknown edition \"" + edition + "\"; this release offers " + (offered.length === 0 ? "(none)" : offered.join(", ")));
+	}
+	const editionPackages = composition?.packages ?? {};
+	const editionBundles = composition?.bundles ?? distribution.bundles;
 	if (existsSync(manifestPath)) {
+		if (composition !== void 0) {
+			const manifest = requireRecord(JSON.parse(readFileSync(manifestPath, "utf8")), "Plus profile manifest");
+			manifest.dependencies = {
+				...manifest.dependencies,
+				...editionPackages
+			};
+			manifest.dsh = {
+				...manifest.dsh,
+				profile: {
+					...manifest.dsh?.profile,
+					bundles: [...editionBundles]
+				}
+			};
+			writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+		}
 		writeProfileOverrides(paths.profileDirectory, distribution.overrides, distribution.allowBuilds, paths.omittedPackages);
 		installProfilePackages(paths, consumerDirectory);
 		return false;
@@ -1171,10 +1214,11 @@ function ensureProfile(paths, consumerDirectory) {
 		dependencies: {
 			"@sparkelf/dsh-plus": distribution.version,
 			"@deepseek-ai/dsh": distribution.dshRange,
-			...distribution.dependencies
+			...distribution.dependencies,
+			...editionPackages
 		},
 		dsh: { profile: {
-			bundles: distribution.bundles,
+			bundles: [...editionBundles],
 			patchReload: "live"
 		} }
 	};
@@ -1234,30 +1278,21 @@ function git(root, args, acceptFailure = false) {
 * @returns the labels of the patches that were applied.
 */
 function applyProfileNpmPatches(distributionDirectory, profileDirectory) {
-	const names = requireRecord(requireRecord(JSON.parse(readFileSync(join(distributionDirectory, "package.json"), "utf8")), "Plus distribution manifest").dshPlus, "dshPlus").patchPackages;
-	if (!Array.isArray(names)) throw new Error("dshPlus.patchPackages must be an array");
+	const patchSet = readPatchSet(distributionDirectory, requireRecord(JSON.parse(readFileSync(join(distributionDirectory, "package.json"), "utf8")), "Plus distribution manifest"));
 	const applied = [];
-	for (const value of names) {
-		if (typeof value !== "string" || value === "") throw new Error("dshPlus.patchPackages entries must be non-empty strings");
-		const patchPackage = resolveInstalledPackage(distributionDirectory, value);
-		const variants = requireRecord(patchPackage.manifest.dshPatch, value + " dshPatch").variants;
-		if (!Array.isArray(variants)) throw new Error(value + " dshPatch.variants must be an array");
-		for (const entry of variants) {
-			const variant = requireRecord(entry, value + " variant");
-			const target = requireRecord(variant.target, value + " variant target");
-			if (target.kind !== "npm") continue;
-			const targetName = String(target.name);
-			const patched = resolveInstalledPackage(profileDirectory, targetName);
-			const file = resolve(patchPackage.directory, String(variant.file));
-			if (git(patched.directory, [
-				"apply",
-				"--reverse",
-				"--check",
-				file
-			], true) !== void 0) continue;
-			git(patched.directory, ["apply", file]);
-			applied.push(value + " -> " + targetName);
-		}
+	for (const entry of [...patchSet.entries, ...patchSet.thirdPartyPatches]) {
+		if (entry.target.kind !== "npm") continue;
+		const targetName = entry.target.name;
+		const patched = resolveInstalledPackage(profileDirectory, targetName);
+		const file = resolve(distributionDirectory, entry.file);
+		if (git(patched.directory, [
+			"apply",
+			"--reverse",
+			"--check",
+			file
+		], true) !== void 0) continue;
+		git(patched.directory, ["apply", file]);
+		applied.push(entry.id + " -> " + targetName);
 	}
 	return applied;
 }
@@ -1268,7 +1303,18 @@ function resolveInstalledPackage(from, packageName) {
 	try {
 		manifestPath = requireFrom.resolve(packageName + "/package.json");
 	} catch {
-		throw new Error(packageName + " is not installed under " + from);
+		let directory;
+		try {
+			directory = dirname(requireFrom.resolve(packageName));
+		} catch {
+			throw new Error(packageName + " is not installed under " + from);
+		}
+		while (!existsSync(resolve(directory, "package.json"))) {
+			const parent = dirname(directory);
+			if (parent === directory) throw new Error(packageName + " has no resolvable package manifest under " + from);
+			directory = parent;
+		}
+		manifestPath = resolve(directory, "package.json");
 	}
 	const manifest = requireRecord(JSON.parse(readFileSync(manifestPath, "utf8")), packageName + " manifest");
 	return {
@@ -1298,6 +1344,7 @@ function parseStartOptions(argv) {
 	let host = "127.0.0.1";
 	let open = true;
 	let foreground = false;
+	let edition;
 	let capabilities;
 	for (let index = 0; index < argv.length; index += 1) {
 		const token = argv[index];
@@ -1323,6 +1370,13 @@ function parseStartOptions(argv) {
 			foreground = true;
 			continue;
 		}
+		if (token === "--edition") {
+			const value = argv[index + 1];
+			if (value === void 0 || value === "") throw new Error("--edition requires a value");
+			edition = value;
+			index += 1;
+			continue;
+		}
 		if (token === "--capabilities") {
 			const value = argv[index + 1];
 			if (value === void 0) throw new Error("--capabilities requires a comma-separated list, or an empty string for none");
@@ -1340,6 +1394,7 @@ function parseStartOptions(argv) {
 		host,
 		open,
 		foreground,
+		edition,
 		capabilities
 	};
 }
@@ -1425,6 +1480,40 @@ function runForeground(entry, profileName, port, host, open) {
 	if (!open) args.push("--no-open");
 	return spawnSync(process.execPath, args, { stdio: "inherit" }).status ?? 1;
 }
+/** Parse the install command's edition selection. */
+function parseInstallOptions(argv) {
+	let edition;
+	for (let index = 0; index < argv.length; index += 1) {
+		const token = argv[index];
+		if (token === "--edition") {
+			const value = argv[index + 1];
+			if (value === void 0 || value === "") throw new Error("--edition requires a value");
+			edition = value;
+			index += 1;
+			continue;
+		}
+		throw new Error("unknown option: " + String(token));
+	}
+	if (edition === void 0) throw new Error("install requires --edition personal or --edition team");
+	return { edition };
+}
+/**
+* Install one edition's package manifest into the profile.
+*
+* The profile's `package.json` is the install artifact; there is no separate standalone
+* package. A later `start` uses the same manifest, so changing the edition is a new
+* install rather than a second product.
+*
+* @param argv - arguments after `install`.
+* @returns the process exit code.
+*/
+function install(argv) {
+	const { edition } = parseInstallOptions(argv);
+	const paths = resolvePaths(declarationAnchor());
+	ensureProfile(paths, installationRoot(), edition);
+	console.log("Installed the " + edition + " edition into " + paths.profileDirectory);
+	return 0;
+}
 async function start(argv) {
 	const options = parseStartOptions(argv);
 	const anchor = installationAnchor();
@@ -1458,8 +1547,9 @@ async function start(argv) {
 		}
 		console.log("pnpm installed.");
 	}
-	const created = ensureProfile(paths, installationRoot());
+	const created = ensureProfile(paths, installationRoot(), options.edition);
 	console.log(created ? "Created the " + paths.profileName + " profile at " + paths.profileDirectory : "Using the existing " + paths.profileName + " profile");
+	if (options.edition !== void 0) console.log("Edition: " + options.edition);
 	for (const label of applyProfileNpmPatches(paths.distributionDirectory, paths.profileDirectory)) console.log("Applied the reviewed patch " + label);
 	const answers = created || !existsSync(join(paths.home, "capabilities.json")) ? options.capabilities === void 0 ? await interviewCapabilities(true) : selectCapabilities(options.capabilities) : void 0;
 	if (answers !== void 0) {
@@ -1809,6 +1899,7 @@ const USAGE = [
 	"Usage: dsh-plus <command> [options]",
 	"",
 	"Commands:",
+	"  install       install an edition package manifest into the profile",
 	"  start         start the server (first run creates the profile)",
 	"  stop          stop the server",
 	"  status        report whether the server is running",
@@ -1821,6 +1912,10 @@ const USAGE = [
 	"  --host <h>     interface to bind (default 127.0.0.1)",
 	"  --no-open      do not open a browser",
 	"  --foreground   run in this terminal instead of in the background",
+	"  --edition <id> install the named edition manifest (personal or team)",
+	"",
+	"install options:",
+	"  --edition <id>  package manifest to install (personal or team)",
 	"",
 	"capabilities options:",
 	"  --enable <ids>   enable the comma-separated capability ids",
@@ -1843,6 +1938,7 @@ async function runStandaloneCli(argv) {
 		console.log(USAGE);
 		return 0;
 	}
+	if (command === "install") return install(rest);
 	if (command === "start") return await start(rest);
 	if (command === "stop") return stop();
 	if (command === "status") return status();

package/lib/types/apply.d.ts

@@ -1,4 +1,4 @@
-/** Materialize the Plus distribution's independent patch packages without Desktop. */
+/** Materialize the Plus distribution's embedded patch set without Desktop. */
 /** One official workspace package available as a profile peer dependency. */
 export interface OfficialWorkspacePackage {
     name: string;

package/lib/types/apply.js

@@ -1,11 +1,12 @@
-/** Materialize the Plus distribution's independent patch packages without Desktop. */
+/** Materialize the Plus distribution's embedded patch set without Desktop. */
 import { spawnSync } from 'node:child_process';
 import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync, } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname, isAbsolute, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
 import { satisfies, valid, validRange } from 'semver';
 import { parseDocument } from 'yaml';
+import { readPatchSet } from "./patch-set.js";
 const FORMAT_VERSION = 1;
 function isSelectedNpmPatch(patch) {
     return patch.target.kind === 'npm';
@@ -50,7 +51,22 @@ function requireStringArray(value, label) {
 }
 function resolveInstalledPackage(distributionDirectory, packageName) {
     const requireFromDistribution = createRequire(resolve(distributionDirectory, 'package.json'));
-    const manifestPath = requireFromDistribution.resolve(packageName + '/package.json');
+    let manifestPath;
+    try {
+        manifestPath = requireFromDistribution.resolve(packageName + '/package.json');
+    }
+    catch {
+        // Some packages do not export `./package.json`; resolve the entry module instead and walk
+        // up to the directory that holds the manifest.
+        let directory = dirname(requireFromDistribution.resolve(packageName));
+        while (!existsSync(resolve(directory, 'package.json'))) {
+            const parent = dirname(directory);
+            if (parent === directory)
+                throw new Error(packageName + ' has no resolvable package manifest');
+            directory = parent;
+        }
+        manifestPath = resolve(directory, 'package.json');
+    }
     const manifest = readJsonObject(manifestPath, packageName + ' manifest');
     return {
         name: packageName,
@@ -59,48 +75,6 @@ function resolveInstalledPackage(distributionDirectory, packageName) {
         manifest,
     };
 }
-function resolvePatchFile(packageDirectory, declared) {
-    const absoluteFile = resolve(packageDirectory, declared);
-    const local = relative(packageDirectory, absoluteFile);
-    if (isAbsolute(local) || local === '..' || local.startsWith('../')) {
-        throw new Error('patch file must stay inside its patch package: ' + declared);
-    }
-    if (!existsSync(absoluteFile))
-        throw new Error('patch file does not exist: ' + absoluteFile);
-    return { relativeFile: local.replaceAll('\\', '/'), absoluteFile };
-}
-function parseVariant(value, index, patchPackage) {
-    const label = patchPackage.name + ' dshPatch.variants[' + String(index) + ']';
-    const variant = requireObject(value, label);
-    const target = requireObject(variant.target, label + '.target');
-    const kind = requireString(target.kind, label + '.target.kind');
-    const common = {
-        id: requireString(variant.id, label + '.id'),
-        dsh: requireRange(variant.dsh, label + '.dsh'),
-        file: requireString(variant.file, label + '.file'),
-        patchPackage,
-    };
-    if (kind === 'npm') {
-        return {
-            ...common,
-            target: {
-                kind,
-                name: requireString(target.name, label + '.target.name'),
-                range: requireRange(target.range, label + '.target.range'),
-            },
-        };
-    }
-    if (kind === 'dsh-source') {
-        return {
-            ...common,
-            target: {
-                kind,
-                baseRevision: requireString(target.baseRevision, label + '.target.baseRevision'),
-            },
-        };
-    }
-    throw new Error('unsupported patch target kind: ' + kind);
-}
 function git(root, args, acceptFailure = false) {
     const result = spawnSync('git', args, { cwd: root, encoding: 'utf8' });
     if (result.status === 0)
@@ -148,23 +122,6 @@ function requireSourceBase(root, baseRevision) {
     }
     return checkoutRevision;
 }
-function patchPackageVariants(distributionDirectory, names) {
-    const variants = [];
-    for (const name of names) {
-        const patchPackage = resolveInstalledPackage(distributionDirectory, name);
-        const declaration = requireObject(patchPackage.manifest.dshPatch, name + ' dshPatch');
-        if (declaration.formatVersion !== FORMAT_VERSION) {
-            throw new Error('unsupported dshPatch formatVersion in ' + name + ': ' + String(declaration.formatVersion));
-        }
-        if (!Array.isArray(declaration.variants) || declaration.variants.length === 0) {
-            throw new Error(name + ' dshPatch.variants must be a non-empty array');
-        }
-        for (const [index, value] of declaration.variants.entries()) {
-            variants.push(parseVariant(value, index, patchPackage));
-        }
-    }
-    return variants;
-}
 // 先验证official source，再物化Plus声明的profile依赖，避免source不匹配时改动用户profile。
 function prepareSelection(distributionDirectory, profileDirectory, dshRoot) {
     const distributionManifest = readJsonObject(resolve(distributionDirectory, 'package.json'), 'Plus distribution manifest');
@@ -192,31 +149,24 @@ function prepareSelection(distributionDirectory, profileDirectory, dshRoot) {
             throw new Error('dshPlus.profile.allowBuilds.' + name + ' must be a boolean');
         allowBuilds[name] = allowed;
     }
-    const patchPackageNames = requireStringArray(plus.patchPackages, 'dshPlus.patchPackages');
+    const patchSet = readPatchSet(distributionDirectory, distributionManifest);
     const dependencies = requireObject(distributionManifest.dependencies, 'Plus distribution dependencies');
     const dshManifest = readJsonObject(resolve(dshRoot, 'package.json'), 'DSH source manifest');
     const dshVersion = requireVersion(dshManifest.version, 'DSH source version');
     if (!satisfies(dshVersion, dshRange, { includePrerelease: true })) {
         throw new Error(distributionName + '@' + distributionVersion + ' requires DSH ' + dshRange + ', found ' + dshVersion);
     }
-    const checkoutRevision = requireSourceBase(dshRoot, baseRevision);
-    const groups = new Map();
-    for (const variant of patchPackageVariants(distributionDirectory, patchPackageNames)) {
-        const entries = groups.get(variant.id) ?? [];
-        entries.push(variant);
-        groups.set(variant.id, entries);
-    }
+    const checkoutRevision = requireSourceBase(dshRoot, patchSet.sourceBaseRevision);
+    const patchEntries = [...patchSet.entries, ...patchSet.thirdPartyPatches];
     const sourceStates = new Map();
-    const orderedGroups = [...groups].sort(([left], [right]) => left.localeCompare(right));
-    for (const [, variants] of orderedGroups) {
-        for (const variant of variants) {
-            if (variant.target.kind !== 'dsh-source'
-                || variant.target.baseRevision !== baseRevision
-                || !satisfies(dshVersion, variant.dsh, { includePrerelease: true }))
-                continue;
-            const file = resolvePatchFile(variant.patchPackage.directory, variant.file);
-            sourceStates.set(file.absoluteFile, sourcePatchState(dshRoot, file.absoluteFile));
+    for (const item of patchEntries) {
+        if (!satisfies(dshVersion, item.dsh, { includePrerelease: true })) {
+            throw new Error('patch ' + item.id + ' declares DSH ' + item.dsh + ', found ' + dshVersion);
         }
+        if (item.target.kind !== 'dsh-source')
+            continue;
+        const absoluteFile = resolve(distributionDirectory, item.file);
+        sourceStates.set(absoluteFile, sourcePatchState(dshRoot, absoluteFile));
     }
     const pendingSourceFiles = [...sourceStates].flatMap(([file, state]) => state === 'pending' ? [file] : []);
     preflightSourcePatches(dshRoot, pendingSourceFiles);
@@ -227,49 +177,38 @@ function prepareSelection(distributionDirectory, profileDirectory, dshRoot) {
         return { name, version: installed.version };
     });
     const runtimePackages = [
-        ...Object.keys(dependencies).filter(name => !patchPackageNames.includes(name)).sort().map((name) => {
+        ...Object.keys(dependencies).sort().map((name) => {
             const installed = resolveInstalledPackage(distributionDirectory, name);
             return { name, version: installed.version };
         }),
         ...profileDependencies,
     ].sort((left, right) => left.name.localeCompare(right.name));
     const selected = [];
-    // 每个patch id必须在当前DSH、official base与installed npm graph上唯一命中，不能fallback到第二variant。
-    for (const [id, variants] of orderedGroups) {
-        const candidates = variants.flatMap((variant) => {
-            if (!satisfies(dshVersion, variant.dsh, { includePrerelease: true }))
-                return [];
-            const file = resolvePatchFile(variant.patchPackage.directory, variant.file);
-            if (variant.target.kind === 'dsh-source') {
-                if (variant.target.baseRevision !== baseRevision)
-                    return [];
-                return [{
-                        id,
-                        patchPackage: { name: variant.patchPackage.name, version: variant.patchPackage.version },
-                        file: file.relativeFile,
-                        absoluteFile: file.absoluteFile,
-                        target: { kind: 'dsh-source', baseRevision },
-                        alreadyApplied: sourceStates.get(file.absoluteFile) === 'applied',
-                    }];
-            }
-            const targetDirectory = variant.target.name in profileDependencySpecs ? profileDirectory : distributionDirectory;
-            const targetVersion = resolveInstalledPackage(targetDirectory, variant.target.name).version;
-            if (!satisfies(targetVersion, variant.target.range, { includePrerelease: true }))
-                return [];
-            return [{
-                    id,
-                    patchPackage: { name: variant.patchPackage.name, version: variant.patchPackage.version },
-                    file: file.relativeFile,
-                    absoluteFile: file.absoluteFile,
-                    target: { kind: 'npm', name: variant.target.name, version: targetVersion },
-                }];
+    for (const item of patchEntries) {
+        const absoluteFile = resolve(distributionDirectory, item.file);
+        if (item.target.kind === 'dsh-source') {
+            selected.push({
+                id: item.id,
+                scope: item.scope,
+                file: item.file,
+                absoluteFile,
+                target: { kind: 'dsh-source', baseRevision: patchSet.sourceBaseRevision },
+                alreadyApplied: sourceStates.get(absoluteFile) === 'applied',
+            });
+            continue;
+        }
+        const targetDirectory = item.target.name in profileDependencySpecs ? profileDirectory : distributionDirectory;
+        const targetVersion = resolveInstalledPackage(targetDirectory, item.target.name).version;
+        if (!satisfies(targetVersion, item.target.range, { includePrerelease: true })) {
+            throw new Error('patch ' + item.id + ' targets ' + item.target.name + ' ' + item.target.range + ', found ' + targetVersion);
+        }
+        selected.push({
+            id: item.id,
+            scope: item.scope,
+            file: item.file,
+            absoluteFile,
+            target: { kind: 'npm', name: item.target.name, version: targetVersion },
         });
-        const [candidate] = candidates;
-        if (candidate === undefined)
-            throw new Error('no compatible patch variant for ' + id + ' on DSH ' + dshVersion);
-        if (candidates.length > 1)
-            throw new Error('multiple compatible patch variants for ' + id + ' on DSH ' + dshVersion);
-        selected.push(candidate);
     }
     const lockPatches = selected.map((patch) => {
         if ('alreadyApplied' in patch) {
@@ -299,7 +238,7 @@ function materializePatchFiles(profileDirectory, patches) {
     const root = resolve(profileDirectory, '.dsh-plus', 'patches');
     rmSync(root, { recursive: true, force: true });
     const stablePatches = patches.map((patch) => {
-        const destination = resolve(root, patch.patchPackage.name, patch.patchPackage.version, patch.file);
+        const destination = resolve(root, patch.scope, patch.id, basename(patch.file));
         mkdirSync(dirname(destination), { recursive: true });
         copyFileSync(patch.absoluteFile, destination);
         return { ...patch, absoluteFile: destination };
@@ -323,7 +262,7 @@ function materializePatchFiles(profileDirectory, patches) {
             continue;
         }
         // 成员或版本变化必须改变workspace路径，使pnpm重新应用新的组合payload。
-        const members = group.map(patch => encodeURIComponent(patch.id + '@' + patch.patchPackage.version)).join('+');
+        const members = group.map(patch => encodeURIComponent(patch.id)).join('+');
         const destination = resolve(root, 'combined', encodeURIComponent(key), members + '.patch');
         mkdirSync(dirname(destination), { recursive: true });
         const contents = group.map((patch) => {

package/lib/types/patch-set.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Read the Plus distribution's embedded patch set.
+ *
+ * The distribution owns one patch set for official DSH and, separately, the patches it
+ * carries for third-party packages. Both live inside the distribution package: the
+ * manifest declares entries, and each entry's payload is a file under `patches/`. A
+ * consumer resolves no independently published patch package.
+ *
+ * The two lists are governed differently. A Plus entry must target an official package
+ * that the profile republishes and overrides; a third-party entry must name its upstream
+ * and a retirement condition, and never becomes part of the official patch set.
+ */
+/** An npm package the distribution patches in place. */
+export interface NpmPatchTarget {
+    readonly kind: 'npm';
+    readonly name: string;
+    readonly range: string;
+}
+/** One official source path set, applied to the exact `dshPlus.sourceBase` revision. */
+export interface SourcePatchTarget {
+    readonly kind: 'dsh-source';
+    readonly baseRevision: string;
+    /** Official packages the patch modifies; each must be republished and overridden. */
+    readonly packages: readonly string[];
+    readonly paths: readonly string[];
+}
+/** Where one patch payload lands. */
+export type PatchTarget = NpmPatchTarget | SourcePatchTarget;
+/** Who owns the entry: the Plus official delta or a carried third-party patch. */
+export type PatchScope = 'plus' | 'third-party';
+/** One entry of the embedded patch set. */
+export interface PatchSetEntry {
+    /** Stable identity used by the lock and by retirement records. */
+    readonly id: string;
+    readonly scope: PatchScope;
+    /** DSH range the entry applies to. */
+    readonly dsh: string;
+    /** Payload path, relative to the distribution package. */
+    readonly file: string;
+    /** The behavior or upstream release that retires this entry. */
+    readonly retireWhen: string;
+    /** Third-party entries name the upstream they track. */
+    readonly upstreamUrl?: string;
+    readonly target: PatchTarget;
+}
+/** The distribution's complete embedded patch declaration. */
+export interface PatchSet {
+    readonly entries: readonly PatchSetEntry[];
+    readonly thirdPartyPatches: readonly PatchSetEntry[];
+    readonly sourceBaseRevision: string;
+}
+/**
+ * Read and validate the embedded patch set from an installed distribution.
+ * @param distributionDirectory - installed `@sparkelf/dsh-plus` directory.
+ * @param manifest - its parsed package manifest.
+ * @returns the ordered Plus entries, third-party entries, and the exact source base.
+ */
+export declare function readPatchSet(distributionDirectory: string, manifest: Record<string, unknown>): PatchSet;
+//# sourceMappingURL=patch-set.d.ts.map