@tsdoctor/bundle 0.1.0

package/BundleFetch.js

@@ -0,0 +1,348 @@
+import { readBundle } from "./Bundle.js";
+import { discoverBundle } from "./BundleDiscovery.js";
+import { Effect, FileSystem, Option, Path, Schema } from "effect";
+import { GitHubRelease, Repo, RepoRef } from "@effected/github";
+import { NpmRegistry, PackageTarball, PublishedVersion } from "@effected/npm";
+import { Cache } from "@effected/store";
+import { AppDirs } from "@effected/xdg";
+
+//#region src/BundleFetch.ts
+/**
+* Raised when a remote bundle cannot be fetched into the local cache.
+*
+* @remarks
+* Fetch-plane failures speak in remote terms (`ref` names the coordinate the
+* caller asked for, never a temp directory). Post-fetch READ failures — a
+* fetched artifact whose layer files are malformed — surface as the same
+* typed errors local reads produce (`BundleLayerError`,
+* `BundleManifestError`), so a consumer handles one vocabulary for both.
+*
+* @public
+*/
+var BundleFetchError = class extends Schema.TaggedError()("BundleFetchError", {
+	/** Which fetcher failed. */
+	source: Schema.Literals(["npm", "github"]),
+	/** What went wrong, structurally. */
+	reason: Schema.Literals([
+		"invalidRef",
+		"versionNotFound",
+		"releaseNotFound",
+		"assetNotFound",
+		"assetAmbiguous",
+		"download",
+		"notABundle",
+		"cache"
+	]),
+	/** The remote coordinate: `name@version` or `owner/repo@tag#asset`. */
+	ref: Schema.String,
+	/** Human context for the failure. */
+	detail: Schema.optionalKey(Schema.String),
+	/** The underlying failure, when one exists, preserved structurally. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		const detailPart = this.detail !== void 0 ? `: ${this.detail}` : "";
+		return `Bundle fetch failed (${this.reason}) for ${this.source} ${this.ref}${detailPart}`;
+	}
+};
+/** The default asset suffix for the GitHub release bundle variant. */
+const META_TGZ_SUFFIX = ".npm.meta.tgz";
+/** Cache-record schema: which layer files a cached bundle dir holds. */
+const CachedBundleRecord = Schema.Struct({ files: Schema.Array(Schema.String) });
+/**
+* One path segment safe to join into the cache tree: no separators, no
+* traversal, no whitespace. Mirrors the registry's cache-key discipline —
+* lenient about npm's historical malformations, strict enough that a
+* coordinate can never escape its cache directory.
+*/
+const SAFE_SEGMENT = /^(?!\.{1,2}$)[^/\\\s]+$/;
+const utf8Encode = (text) => new TextEncoder().encode(text);
+const utf8Decode = (bytes) => new TextDecoder().decode(bytes);
+/** Validate that every cache-path segment is traversal-safe. */
+function validateSegments(source, ref, segments) {
+	for (const segment of segments) if (!SAFE_SEGMENT.test(segment)) return Effect.fail(new BundleFetchError({
+		source,
+		reason: "invalidRef",
+		ref,
+		detail: `unsafe path segment "${segment}"`
+	}));
+	return Effect.void;
+}
+/** The durable cache directory for one remote bundle coordinate. */
+function bundleCacheDir(segments) {
+	return Effect.gen(function* () {
+		const appDirs = yield* AppDirs;
+		const path = yield* Path.Path;
+		const cacheRoot = yield* appDirs.ensureCache.pipe(Effect.orDie);
+		return path.join(cacheRoot, "bundles", ...segments);
+	});
+}
+/**
+* The cache-hit probe: a metadata record exists AND every file it lists is
+* still on disk. Any inconsistency — missing record, undecodable record,
+* missing file, cache-read failure — reads as a miss, so a damaged cache
+* self-heals by refetching.
+*/
+function cachedBundle(key, dir) {
+	return Effect.gen(function* () {
+		const cache = yield* Cache;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const entry = yield* cache.get(key).pipe(Effect.orElseSucceed(() => Option.none()));
+		if (Option.isNone(entry)) return Option.none();
+		const record = yield* Schema.decodeUnknownEffect(CachedBundleRecord)(yield* Effect.try(() => JSON.parse(utf8Decode(entry.value.value))).pipe(Effect.orElseSucceed(() => null))).pipe(Effect.option);
+		if (Option.isNone(record)) return Option.none();
+		for (const file of record.value.files) if (!(yield* fs.exists(path.join(dir, file)).pipe(Effect.orElseSucceed(() => false)))) return Option.none();
+		return yield* Effect.flatMap(discoverBundle(dir), readBundle).pipe(Effect.option);
+	});
+}
+/**
+* Persist a fetched bundle's layer files from the (scoped, about-to-vanish)
+* extraction directory into the durable cache dir, and record them in the
+* metadata cache. The returned Bundle's descriptor points into the CACHE
+* directory, which outlives the extraction scope.
+*/
+function persistAndRead(source, ref, key, extractedDir, cacheDir) {
+	return Effect.gen(function* () {
+		const cache = yield* Cache;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const discovered = yield* discoverBundle(extractedDir).pipe(Effect.mapError((cause) => new BundleFetchError({
+			source,
+			reason: "notABundle",
+			ref,
+			detail: "the fetched artifact does not contain a readable bundle (no *.api.json model)",
+			cause
+		})));
+		const layerPaths = [
+			discovered.modelPath,
+			...discovered.packageJsonPath !== void 0 ? [discovered.packageJsonPath] : [],
+			...discovered.tsconfigPath !== void 0 ? [discovered.tsconfigPath] : [],
+			...discovered.manifestPath !== void 0 ? [discovered.manifestPath] : []
+		];
+		const failCache = (cause) => new BundleFetchError({
+			source,
+			reason: "cache",
+			ref,
+			cause
+		});
+		yield* fs.remove(cacheDir, { recursive: true }).pipe(Effect.ignore);
+		yield* fs.makeDirectory(cacheDir, { recursive: true }).pipe(Effect.mapError(failCache));
+		const files = [];
+		for (const layerPath of layerPaths) {
+			const fileName = path.basename(layerPath);
+			yield* fs.copyFile(layerPath, path.join(cacheDir, fileName)).pipe(Effect.mapError(failCache));
+			files.push(fileName);
+		}
+		yield* cache.set({
+			key,
+			value: utf8Encode(JSON.stringify({ files })),
+			contentType: "application/json"
+		}).pipe(Effect.mapError(failCache));
+		return yield* Effect.flatMap(discoverBundle(cacheDir), readBundle).pipe(Effect.catchTag("BundleDiscoveryError", (cause) => Effect.fail(failCache(cause))));
+	});
+}
+/**
+* Fetch one published npm package version as a bundle, through the durable
+* XDG cache.
+*
+* @remarks
+* Works against any npm-protocol-family registry via `target` (the
+* `type: "npm"` semantics of the manifest's registries block). The tarball is
+* downloaded, integrity-verified and extracted by `@effected/npm`'s
+* `PackageTarball`, its bundle layer files are copied into
+* `<xdg-cache>/tsdoctor/bundles/npm/<name>/<version>/`, and the returned
+* {@link Bundle}'s descriptor points at that durable directory. A published
+* npm version is immutable, so a cache hit skips the network entirely;
+* `refresh: true` forces a refetch.
+*
+* Provide the `NpmRegistry`, `PackageTarball`, `Cache` and `AppDirs`
+* services (plus `FileSystem`/`Path`) at the application boundary.
+*
+* @public
+*/
+function fetchNpmBundle(options) {
+	const ref = `${options.name}@${options.version}`;
+	return Effect.gen(function* () {
+		const segments = [
+			"npm",
+			...options.name.split("/"),
+			options.version
+		];
+		yield* validateSegments("npm", ref, segments.slice(1));
+		const cacheDir = yield* bundleCacheDir(segments);
+		const key = `bundle:v1:npm:${ref}`;
+		if (options.refresh !== true) {
+			const hit = yield* cachedBundle(key, cacheDir);
+			if (Option.isSome(hit)) return hit.value;
+		}
+		const registry = yield* NpmRegistry;
+		const tarball = yield* PackageTarball;
+		const published = yield* registry.version(options.name, options.version, options.target).pipe(Effect.mapError((cause) => new BundleFetchError({
+			source: "npm",
+			reason: "download",
+			ref,
+			cause
+		})));
+		if (Option.isNone(published)) return yield* Effect.fail(new BundleFetchError({
+			source: "npm",
+			reason: "versionNotFound",
+			ref,
+			detail: "the registry reports no such published version (exact versions and dist-tags only; ranges are not resolved here)"
+		}));
+		return yield* Effect.gen(function* () {
+			const extractedDir = yield* tarball.extract(published.value).pipe(Effect.mapError((cause) => new BundleFetchError({
+				source: "npm",
+				reason: cause.reason === "notFound" ? "versionNotFound" : "download",
+				ref,
+				cause
+			})));
+			return yield* persistAndRead("npm", ref, key, extractedDir, cacheDir);
+		}).pipe(Effect.scoped);
+	});
+}
+/**
+* Locate the bundle root inside an extracted release archive. npm-style
+* archives unpack to `package/`; the real `*.npm.meta.tgz` release variant
+* unpacks to `meta/` (verified against vitest-agent's published assets); a
+* hand-rolled archive may put its files at the root. The first candidate
+* containing a `*.api.json` wins: `package/`, the archive root, then each
+* top-level subdirectory.
+*/
+function locateBundleRoot(extractedPackageDir) {
+	return Effect.gen(function* () {
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const archiveRoot = path.dirname(extractedPackageDir);
+		const candidates = [
+			extractedPackageDir,
+			archiveRoot,
+			...(yield* fs.readDirectory(archiveRoot).pipe(Effect.orElseSucceed(() => []))).filter((entry) => entry !== path.basename(extractedPackageDir)).map((entry) => path.join(archiveRoot, entry))
+		];
+		for (const candidate of candidates) if ((yield* fs.readDirectory(candidate).pipe(Effect.orElseSucceed(() => []))).some((name) => name.endsWith(".api.json"))) return Option.some(candidate);
+		return Option.none();
+	});
+}
+/** Pick the release asset: an exact name, or the single `*.npm.meta.tgz`. */
+function pickAsset(ref, assets, wanted) {
+	if (wanted !== void 0) {
+		const found = assets.find((asset) => asset.name === wanted);
+		return found !== void 0 ? Effect.succeed(found) : Effect.fail(new BundleFetchError({
+			source: "github",
+			reason: "assetNotFound",
+			ref,
+			detail: `no asset named "${wanted}" (available: ${assets.map((asset) => asset.name).join(", ") || "none"})`
+		}));
+	}
+	const candidates = assets.filter((asset) => asset.name.endsWith(META_TGZ_SUFFIX));
+	if (candidates.length === 1) return Effect.succeed(candidates[0]);
+	if (candidates.length === 0) return Effect.fail(new BundleFetchError({
+		source: "github",
+		reason: "assetNotFound",
+		ref,
+		detail: `no *${META_TGZ_SUFFIX} asset on the release; pass an explicit asset name`
+	}));
+	return Effect.fail(new BundleFetchError({
+		source: "github",
+		reason: "assetAmbiguous",
+		ref,
+		detail: `multiple *${META_TGZ_SUFFIX} assets (${candidates.map((asset) => asset.name).join(", ")}); pass an explicit asset name`
+	}));
+}
+/**
+* Fetch a bundle attached to a GitHub release as a `*.npm.meta.tgz`-style
+* asset, through the durable XDG cache.
+*
+* @remarks
+* The release is looked up by tag via `@effected/github`'s `GitHubRelease`
+* (the `Repo` context is provided internally from `owner`/`repo`), the chosen
+* asset is downloaded and extracted through the same verified
+* `PackageTarball` path the npm fetcher uses (no integrity is available for
+* release assets, so the download is unverified — the extractor logs this),
+* and the layer files land in
+* `<xdg-cache>/tsdoctor/bundles/github/<owner>/<repo>/<tag>/<asset>/`.
+*
+* A tarball with an npm-style `package/` root and one with its files at the
+* archive root are both accepted. Git tags CAN move; the cache treats them as
+* immutable and `refresh: true` is the escape hatch. Private-repo assets are
+* not supported yet: the asset's browser download URL is fetched directly,
+* which works for public releases only.
+*
+* @public
+*/
+function fetchGitHubReleaseBundle(options) {
+	const ref = `${options.owner}/${options.repo}@${options.tag}${options.asset !== void 0 ? `#${options.asset}` : ""}`;
+	return Effect.gen(function* () {
+		yield* validateSegments("github", ref, [
+			options.owner,
+			options.repo,
+			options.tag,
+			...options.asset !== void 0 ? [options.asset] : []
+		]);
+		const cacheCoordinate = (assetName) => ({
+			segments: [
+				"github",
+				options.owner,
+				options.repo,
+				options.tag,
+				assetName
+			],
+			key: `bundle:v1:github:${options.owner}/${options.repo}@${options.tag}#${assetName}`
+		});
+		if (options.asset !== void 0 && options.refresh !== true) {
+			const coordinate = cacheCoordinate(options.asset);
+			const earlyHit = yield* cachedBundle(coordinate.key, yield* bundleCacheDir(coordinate.segments));
+			if (Option.isSome(earlyHit)) return earlyHit.value;
+		}
+		const releases = yield* GitHubRelease;
+		const repoRef = RepoRef.make({
+			owner: options.owner,
+			repo: options.repo
+		});
+		const withRepo = (effect) => Effect.provideService(effect, Repo, repoRef);
+		const failDownload = (cause) => new BundleFetchError({
+			source: "github",
+			reason: "download",
+			ref,
+			cause
+		});
+		const release = yield* withRepo(releases.getByTagOption(options.tag)).pipe(Effect.mapError(failDownload));
+		if (Option.isNone(release)) return yield* Effect.fail(new BundleFetchError({
+			source: "github",
+			reason: "releaseNotFound",
+			ref,
+			detail: "no release with that tag"
+		}));
+		const assets = yield* withRepo(releases.listAssets(release.value.id)).pipe(Effect.mapError(failDownload));
+		const asset = yield* pickAsset(ref, assets, options.asset);
+		const { segments, key } = cacheCoordinate(asset.name);
+		const cacheDir = yield* bundleCacheDir(segments);
+		if (options.refresh !== true && options.asset === void 0) {
+			const hit = yield* cachedBundle(key, cacheDir);
+			if (Option.isSome(hit)) return hit.value;
+		}
+		const tarball = yield* PackageTarball;
+		return yield* Effect.gen(function* () {
+			const bundleRoot = yield* locateBundleRoot(yield* tarball.extract(PublishedVersion.make({
+				name: asset.name,
+				version: options.tag,
+				tarball: asset.url
+			})).pipe(Effect.mapError((cause) => new BundleFetchError({
+				source: "github",
+				reason: cause.reason === "notFound" ? "assetNotFound" : "download",
+				ref,
+				cause
+			}))));
+			if (Option.isNone(bundleRoot)) return yield* Effect.fail(new BundleFetchError({
+				source: "github",
+				reason: "notABundle",
+				ref,
+				detail: "the release asset contains no *.api.json model at its root, in package/, or in any top-level directory"
+			}));
+			return yield* persistAndRead("github", ref, key, bundleRoot.value, cacheDir);
+		}).pipe(Effect.scoped);
+	});
+}
+
+//#endregion
+export { BundleFetchError, fetchGitHubReleaseBundle, fetchNpmBundle };

package/BundleHash.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+
+//#region src/BundleHash.ts
+/**
+* Serialize a JSON-shaped value canonically: object keys sorted recursively,
+* `undefined`-valued keys dropped, arrays in declared order, no whitespace.
+*
+* @remarks
+* The normalization half of the change-detection discipline: two values that
+* differ only in key order or optional-key presence-as-`undefined` serialize
+* identically, so their hashes match. Non-JSON leaves (functions, symbols)
+* serialize as `null`, matching `JSON.stringify` semantics inside arrays.
+*
+* @public
+*/
+function canonicalJson(value) {
+	if (value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string") return JSON.stringify(value);
+	if (Array.isArray(value)) return `[${value.map((item) => canonicalJson(item === void 0 ? null : item)).join(",")}]`;
+	if (typeof value === "object") {
+		const record = value;
+		return `{${Object.keys(record).filter((key) => record[key] !== void 0).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(",")}}`;
+	}
+	return "null";
+}
+/**
+* Normalize text for hashing: CRLF/CR line endings become LF and trailing
+* whitespace at the end of the content is trimmed.
+*
+* @remarks
+* The same file checked out with different line-ending settings must hash
+* identically — coarse layer-hash comparison otherwise reports every file
+* changed on the first cross-platform build.
+*
+* @public
+*/
+function normalizeText(text) {
+	return text.replace(/\r\n?/g, "\n").trimEnd();
+}
+/**
+* The lowercase hex SHA-256 of a string, UTF-8 encoded.
+*
+* @public
+*/
+function sha256Hex(text) {
+	return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/**
+* Hash text content: {@link normalizeText} then {@link sha256Hex}.
+*
+* @public
+*/
+function hashText(text) {
+	return sha256Hex(normalizeText(text));
+}
+/**
+* Hash a JSON-shaped value: {@link canonicalJson} then {@link sha256Hex}.
+*
+* @public
+*/
+function hashJsonValue(value) {
+	return sha256Hex(canonicalJson(value));
+}
+/**
+* Hash one bundle layer file's raw text — the COARSE half of change
+* detection (all layer hashes match → skip resolution entirely).
+*
+* @remarks
+* Total: text that parses as JSON hashes canonically (key order and
+* formatting churn do not read as change); text that does not parse falls
+* back to {@link hashText}, so a broken file still gets a stable hash
+* rather than an error — hashing is bookkeeping, not validation.
+*
+* @public
+*/
+function hashLayerText(text) {
+	try {
+		return hashJsonValue(JSON.parse(text));
+	} catch {
+		return hashText(text);
+	}
+}
+/**
+* Fingerprint every present field of a {@link ResolvedBundle} — the FINE
+* half of change detection, hashing each field's `{ value, source }` pair.
+*
+* @remarks
+* The source participates deliberately: an override flip (a field moving
+* from `inferred` to an authored tier without changing value) is a
+* semantically meaningful change and must read as one. Absent fields carry
+* no fingerprint — their appearance or disappearance is itself the diff.
+* The consuming store maps each key to its invalidation scope (version →
+* version-embedding surfaces, tsconfig → all code blocks, …).
+*
+* @public
+*/
+function fingerprintResolvedBundle(resolved) {
+	const fingerprints = {};
+	const fields = { ...resolved };
+	for (const key of Object.keys(fields).sort()) {
+		const field = fields[key];
+		if (field !== void 0) fingerprints[key] = hashJsonValue(field);
+	}
+	return fingerprints;
+}
+
+//#endregion
+export { canonicalJson, fingerprintResolvedBundle, hashJsonValue, hashLayerText, hashText, normalizeText, sha256Hex };

package/BundleManifest.js

@@ -0,0 +1,183 @@
+import { Effect, Schema } from "effect";
+
+//#region src/BundleManifest.ts
+/**
+* The registry protocol families this reader knows how to do more than link
+* to. `"npm"` means an npm-compatible registry — install commands and tarball
+* fetching work against any instance of it — and `"jsr"` the jsr protocol.
+*
+* @remarks
+* The manifest's `type` field is deliberately NOT constrained to these
+* values: unknown future types must degrade to link-only rendering, not
+* reject the manifest. Use {@link isKnownRegistryType} to branch.
+*
+* @public
+*/
+const KNOWN_REGISTRY_TYPES = ["npm", "jsr"];
+/**
+* Whether a registry `type` value is a protocol family this reader
+* recognizes. `false` means the registry entry should degrade to link-only
+* rendering — it is never a validation failure.
+*
+* @public
+*/
+function isKnownRegistryType(type) {
+	return KNOWN_REGISTRY_TYPES.includes(type);
+}
+/**
+* One registry the documented package is published to.
+*
+* @remarks
+* `type` is the PROTOCOL FAMILY (`"npm"` covers every npm-compatible
+* registry), `name` the human instance label, `url` the package's page on
+* that instance. Unknown `type` values decode successfully and degrade to
+* link-only rendering (see {@link isKnownRegistryType}).
+*
+* @public
+*/
+const RegistryRef = Schema.Struct({
+	/** The protocol family, e.g. `"npm"` or `"jsr"`. Unknown values are accepted. */
+	type: Schema.String,
+	/** The human instance label, e.g. `"npm"` or `"Savvy Web Registry"`. */
+	name: Schema.String,
+	/** The package's URL on that registry instance. */
+	url: Schema.String
+});
+/**
+* One Open Graph image declared by the manifest.
+*
+* @remarks
+* Exactly ONE of `path` (a bundle-relative asset the consuming platform
+* publishes and resolves to a URL) or `url` (an absolute external URL used
+* verbatim) must be present — the schema enforces the XOR. `type` is a MIME
+* type, inferred from the file extension by the resolver when omitted; `alt`
+* has a documented inference chain (tagline → description →
+* `"<name> API documentation"`).
+*
+* @public
+*/
+const OpenGraphImage = Schema.Struct({
+	/** Bundle-relative asset path. Mutually exclusive with `url`. */
+	path: Schema.optionalKey(Schema.String),
+	/** Absolute external URL, used verbatim. Mutually exclusive with `path`. */
+	url: Schema.optionalKey(Schema.String),
+	/** MIME type; inferred from the extension when omitted. */
+	type: Schema.optionalKey(Schema.String),
+	/** Pixel width; 1200×630 (1.91:1) is the cross-platform safe default. */
+	width: Schema.optionalKey(Schema.Int),
+	/** Pixel height. */
+	height: Schema.optionalKey(Schema.Int),
+	/** Alt text; inferred (tagline → description → fallback) when omitted. */
+	alt: Schema.optionalKey(Schema.String)
+}).check(Schema.makeFilter((image) => image.path === void 0 !== (image.url === void 0) ? void 0 : "exactly one of \"path\" or \"url\" must be present", { title: "openGraph image source" }));
+/**
+* The manifest's Open Graph block: the asset-ish pieces only — most OG tags
+* are page-level and derive at render time in the consuming platform.
+*
+* @remarks
+* Multiple images follow OG array semantics: the first declared wins, extras
+* are alternates (e.g. a portrait 1000×1500 variant).
+*
+* @public
+*/
+const OpenGraphConfig = Schema.Struct({
+	/** Declared images, first-wins per OG array semantics. */
+	images: Schema.optionalKey(Schema.Array(OpenGraphImage)),
+	/** Embed accent color (e.g. Discord), a CSS color string. */
+	themeColor: Schema.optionalKey(Schema.String)
+});
+/**
+* A pointer to the bundle's SBOM, computed by the bundler at publish and
+* served as a downloadable static asset.
+*
+* @public
+*/
+const SbomRef = Schema.Struct({
+	/** Bundle-relative path to the SBOM file. */
+	path: Schema.String,
+	/** SBOM format label, e.g. `"spdx-json"`. Unknown values are accepted. */
+	format: Schema.optionalKey(Schema.String)
+});
+/**
+* The inherited project tier, flattened into the emitted manifest by the
+* bundler (a fetched bundle has no parent directory to walk). Kept nested —
+* structurally distinguishable from the leaf fields — because provenance is
+* load-bearing for override detection.
+*
+* @public
+*/
+const ProjectIdentity = Schema.Struct({
+	/** The project display name, e.g. `"Effected"` over leaf `@effected/store`. */
+	name: Schema.optionalKey(Schema.String),
+	/** The project tagline. */
+	tagline: Schema.optionalKey(Schema.String)
+});
+/**
+* The versioned `tsdoctor.json` sidecar manifest — bundle layer 3.
+*
+* @remarks
+* `spec` is the only required field; every other field enriches. Unknown
+* top-level fields are ignored on decode (additive fields are minor spec
+* revisions) and unknown enum-ish values (registry `type`, sbom `format`)
+* degrade gracefully instead of rejecting — an old reader must be able to
+* consume a new bundle.
+*
+* @public
+*/
+const BundleManifest = Schema.Struct({
+	/** The integer spec version. This reader understands spec 1. */
+	spec: Schema.Literal(1),
+	/** Human display name (the npm name is dry; this one is SEO-friendly). */
+	name: Schema.optionalKey(Schema.String),
+	/** Short tagline. */
+	tagline: Schema.optionalKey(Schema.String),
+	/** Long description; overrides the package.json description when present. */
+	description: Schema.optionalKey(Schema.String),
+	/** The inherited project tier, flattened in at emit time. */
+	project: Schema.optionalKey(ProjectIdentity),
+	/** Open Graph assets. */
+	openGraph: Schema.optionalKey(OpenGraphConfig),
+	/** SBOM pointer. */
+	sbom: Schema.optionalKey(SbomRef),
+	/** Registries the package is published to. */
+	registries: Schema.optionalKey(Schema.Array(RegistryRef))
+});
+/**
+* Raised when a present `tsdoctor.json` cannot be parsed or does not satisfy
+* the {@link (BundleManifest:variable)} schema.
+*
+* @remarks
+* Absence of the manifest is NEVER this error — layers enrich, never gate,
+* so a missing sidecar is the normal case and reads as `Option.none()`.
+*
+* @public
+*/
+var BundleManifestError = class extends Schema.TaggedError()("BundleManifestError", {
+	/** The manifest file path, when the failure is tied to a file on disk. */
+	path: Schema.optionalKey(Schema.String),
+	/** The underlying failure (JSON syntax or schema decode), preserved structurally. */
+	cause: Schema.Defect()
+}) {
+	get message() {
+		return `Invalid tsdoctor.json manifest${this.path !== void 0 ? ` at ${this.path}` : ""}`;
+	}
+};
+/**
+* Decode an unknown value into a {@link (BundleManifest:type)}.
+*
+* @remarks
+* The typed boundary for manifest input that has already been parsed from
+* JSON (plugin options, fetched payloads). File-based reading lives in
+* `readBundle`, which routes through this after parsing.
+*
+* @public
+*/
+function decodeBundleManifest(input, path) {
+	return Schema.decodeUnknownEffect(BundleManifest)(input).pipe(Effect.mapError((cause) => new BundleManifestError({
+		...path !== void 0 ? { path } : {},
+		cause
+	})));
+}
+
+//#endregion
+export { BundleManifest, BundleManifestError, KNOWN_REGISTRY_TYPES, OpenGraphConfig, OpenGraphImage, ProjectIdentity, RegistryRef, SbomRef, decodeBundleManifest, isKnownRegistryType };