Function parseQuickAddPackage

src/services/packageImportService.ts:125–198

(raw: string)

}

export function parseQuickAddPackage(raw: string): QuickAddPackage {
	let parsed: unknown;
	try {
		parsed = JSON.parse(raw);
	} catch (error) {
		throw new Error(
			`Package content is not valid JSON: ${(error as Error)?.message ?? error}`,
		);
	}

	if (!isQuickAddPackage(parsed)) {
		throw new Error("Content is not a valid QuickAdd package.");
	}

	if (parsed.schemaVersion > QUICKADD_PACKAGE_SCHEMA_VERSION) {
		throw new Error(
			`Package schema version ${parsed.schemaVersion} is newer than this plugin supports (${QUICKADD_PACKAGE_SCHEMA_VERSION}).`,
		);
	}

	// Reject duplicate asset paths at the untrusted-input boundary. The writer is
	// last-write-wins per destination while the review pane resolves the FIRST
	// match (decodeAssetPreview), so two assets at one path could show benign bytes
	// in review while malicious bytes land on disk — a silent review-gate desync.
	// Failing closed here keeps reviewed bytes identical to written bytes.
	const duplicateAssetPath = findDuplicateAssetPath(parsed.assets);
	if (duplicateAssetPath !== null) {
		throw new Error(
			`Package contains duplicate asset path "${duplicateAssetPath}". Each asset must have a unique path.`,
		);
	}

	// Reject internally-inconsistent choices at the untrusted-input boundary. The
	// same choice id can appear in MORE than one place in a package: as a flat
	// `pkg.choices` entry AND inline inside a Multi's `choices` array (or as a
	// NestedChoice/Conditional-branch embedded choice). The preview and the writer
	// each pick ONE of those copies and assume the others are identical:
	// buildPackagePreview's walk SKIPS an inline Multi child whose id is also an
	// entry (trusting the entry's walk to cover it), while applyPackageImport's
	// remapChoiceTree INSTALLS the inline copy and drops the standalone entry. A
	// crafted package can make those copies DIVERGE — a benign top-level entry that
	// the preview discloses, paired with a malicious inline child (e.g.
	// runOnStartup:true) that actually installs — suppressing the capability
	// disclosure and acknowledgement gate entirely. The structural validator
	// (isQuickAddPackage) never checks this. A legitimately-exported package always
	// clones every appearance of an id from one source choice, so all appearances
	// are identical; divergence implies tampering. Fail closed so the copy the user
	// reviews is provably the copy that installs.
	const divergentChoiceId = findDivergentChoiceId(parsed.choices);
	if (divergentChoiceId !== null) {
		throw new Error(
			`Package contains conflicting definitions for choice "${divergentChoiceId}". Each choice id must describe the same choice everywhere it appears.`,
		);
	}

	// Reject a parented choice whose declared parent does not actually carry it
	// inline. applyPackageImport installs a child SOLELY through its parent Multi's
	// inline `choices` (remapChoiceTree keeps only the children listed there) and,