@uapkg/cli 1.4.0 → 1.5.0

package/dist/types/uapkg-diagnostics/publishing/PublishingDiagnostics.d.ts

@@ -0,0 +1,77 @@
+import { DiagnosticBase } from "../base/Diagnostic.js";
+//#region src/publishing/PublishingDiagnostics.d.ts
+/**
+ * Safe, user-facing context for a failed publish request. The fixed set of
+ * kinds prevents arbitrary control-plane details from leaking into output.
+ */
+type PublishDiagnosticFact = {
+  readonly kind: 'package';
+  readonly value: string;
+} | {
+  readonly kind: 'version';
+  readonly value: string;
+} | {
+  readonly kind: 'registry';
+  readonly value: string;
+} | {
+  readonly kind: 'credential-kind';
+  readonly value: string;
+} | {
+  readonly kind: 'requested-owner';
+  readonly value: string;
+} | {
+  readonly kind: 'token-owner';
+  readonly value: string;
+} | {
+  readonly kind: 'allowed-owner';
+  readonly value: string;
+} | {
+  readonly kind: 'actual-access-mode';
+  readonly value: string;
+} | {
+  readonly kind: 'required-access-mode';
+  readonly value: string;
+} | {
+  readonly kind: 'repository';
+  readonly value: string;
+} | {
+  readonly kind: 'requested-repository';
+  readonly value: string;
+} | {
+  readonly kind: 'trusted-repository';
+  readonly value: string;
+} | {
+  readonly kind: 'request-id';
+  readonly value: string;
+} | {
+  readonly kind: 'retry-after';
+  readonly value: string;
+} | {
+  readonly kind: 'missing-capability';
+  readonly value: string;
+};
+/** A CLI command or account page that can help resolve a publish failure. */
+type PublishDiagnosticResource = {
+  readonly kind: 'command';
+  readonly command: string;
+  readonly label?: string;
+} | {
+  readonly kind: 'url';
+  readonly url: string;
+  readonly label?: string;
+};
+interface PublishRequestFailedDiagnosticData {
+  /** Stable control-plane error code, when a response was received. */
+  readonly serverCode?: string;
+  /** HTTP response status, when a response was received. */
+  readonly status?: number;
+  /** Validated facts that are safe to show to the user. */
+  readonly facts: readonly PublishDiagnosticFact[];
+  /** Commands and account pages that can help the user recover. */
+  readonly resources: readonly PublishDiagnosticResource[];
+}
+type PublishRequestFailedDiagnostic = DiagnosticBase<'PUBLISH_REQUEST_FAILED', PublishRequestFailedDiagnosticData>;
+type PublishingDiagnostic = PublishRequestFailedDiagnostic;
+declare function createPublishRequestFailedDiagnostic(message: string, data: PublishRequestFailedDiagnosticData, hint?: string): PublishRequestFailedDiagnostic;
+//#endregion
+export { PublishDiagnosticFact, PublishDiagnosticResource, PublishRequestFailedDiagnostic, PublishRequestFailedDiagnosticData, PublishingDiagnostic, createPublishRequestFailedDiagnostic };

package/dist/types/uapkg-diagnostics/registry/RegistryDiagnostics.d.ts

@@ -0,0 +1,71 @@
+import { DiagnosticBase } from "../base/Diagnostic.js";
+//#region src/registry/RegistryDiagnostics.d.ts
+/** A network-level error when communicating with a registry. */
+type NetworkErrorDiagnostic = DiagnosticBase<'NETWORK_ERROR', {
+  readonly url: string;
+  readonly reason: string;
+}>;
+/** A git operation failed. */
+type GitErrorDiagnostic = DiagnosticBase<'GIT_ERROR', {
+  readonly command: string;
+  readonly stderr: string;
+  readonly exitCode: number;
+}>;
+/** A registry document did not pass schema validation. */
+type SchemaInvalidDiagnostic = DiagnosticBase<'SCHEMA_INVALID', {
+  readonly filePath: string;
+  readonly issues: readonly string[];
+}>;
+/** A referenced registry name is not found in configuration. */
+type RegistryNotFoundDiagnostic = DiagnosticBase<'REGISTRY_NOT_FOUND', {
+  readonly registryName: string;
+}>;
+/** Failed to acquire the registry update lock. */
+type LockAcquisitionFailedDiagnostic = DiagnosticBase<'LOCK_ACQUISITION_FAILED', {
+  readonly lockPath: string;
+  readonly ownerPid: number;
+}>;
+/** Registry cache could not be read. */
+type CacheReadErrorDiagnostic = DiagnosticBase<'CACHE_READ_ERROR', {
+  readonly cachePath: string;
+  readonly reason: string;
+}>;
+/** Registry cache state is internally inconsistent or malformed. */
+type CacheCorruptDiagnostic = DiagnosticBase<'CACHE_CORRUPT', {
+  readonly cachePath: string;
+  readonly reason: string;
+}>;
+/** A shortened cache path belongs to a different full registry identifier. */
+type CacheIdentifierCollisionDiagnostic = DiagnosticBase<'CACHE_IDENTIFIER_COLLISION', {
+  readonly cachePath: string;
+  readonly expectedIdentifier: string;
+  readonly actualIdentifier: string;
+}>;
+/** Registry could not be reached, optionally with cached state available. */
+type RegistryUnreachableDiagnostic = DiagnosticBase<'REGISTRY_UNREACHABLE', {
+  readonly registryName: string;
+  readonly url: string;
+  readonly httpStatus?: number;
+  readonly cause: string;
+  readonly initialized: boolean;
+}>;
+/** Union of all registry diagnostics. */
+type RegistryDiagnostic = NetworkErrorDiagnostic | GitErrorDiagnostic | SchemaInvalidDiagnostic | RegistryNotFoundDiagnostic | LockAcquisitionFailedDiagnostic | CacheReadErrorDiagnostic | CacheCorruptDiagnostic | CacheIdentifierCollisionDiagnostic | RegistryUnreachableDiagnostic;
+declare function createNetworkErrorDiagnostic(url: string, reason: string): NetworkErrorDiagnostic;
+declare function createGitErrorDiagnostic(command: string, stderr: string, exitCode: number): GitErrorDiagnostic;
+declare function createSchemaInvalidDiagnostic(filePath: string, issues: readonly string[]): SchemaInvalidDiagnostic;
+declare function createRegistryNotFoundDiagnostic(registryName: string): RegistryNotFoundDiagnostic;
+declare function createLockAcquisitionFailedDiagnostic(lockPath: string, ownerPid: number): LockAcquisitionFailedDiagnostic;
+declare function createCacheReadErrorDiagnostic(cachePath: string, reason: string): CacheReadErrorDiagnostic;
+declare function createCacheCorruptDiagnostic(cachePath: string, reason: string): CacheCorruptDiagnostic;
+declare function createCacheIdentifierCollisionDiagnostic(cachePath: string, expectedIdentifier: string, actualIdentifier: string): CacheIdentifierCollisionDiagnostic;
+declare function createRegistryUnreachableDiagnostic(input: {
+  readonly registryName: string;
+  readonly url: string;
+  readonly cause: string;
+  readonly initialized: boolean;
+  readonly httpStatus?: number;
+  readonly level?: 'error' | 'warning';
+}): RegistryUnreachableDiagnostic;
+//#endregion
+export { CacheCorruptDiagnostic, CacheIdentifierCollisionDiagnostic, CacheReadErrorDiagnostic, GitErrorDiagnostic, LockAcquisitionFailedDiagnostic, NetworkErrorDiagnostic, RegistryDiagnostic, RegistryNotFoundDiagnostic, RegistryUnreachableDiagnostic, SchemaInvalidDiagnostic, createCacheCorruptDiagnostic, createCacheIdentifierCollisionDiagnostic, createCacheReadErrorDiagnostic, createGitErrorDiagnostic, createLockAcquisitionFailedDiagnostic, createNetworkErrorDiagnostic, createRegistryNotFoundDiagnostic, createRegistryUnreachableDiagnostic, createSchemaInvalidDiagnostic };

package/dist/types/uapkg-diagnostics/registryTools/RegistryToolsDiagnostics.d.ts

@@ -0,0 +1,130 @@
+import { DiagnosticBase } from "../base/Diagnostic.js";
+//#region src/registryTools/RegistryToolsDiagnostics.d.ts
+/** Package name does not match its on-disk manifest path. */
+type RegistryToolsPathMismatchDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_PATH_MISMATCH', {
+  readonly packageName: string;
+  readonly expectedPath: string;
+  readonly actualPath: string;
+}>;
+/** Existing package manifest declares a different `packageSource` than the request. */
+type RegistryToolsPackageSourceMismatchDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_PACKAGE_SOURCE_MISMATCH', {
+  readonly packageName: string;
+  readonly existing: {
+    readonly type: string;
+    readonly url: string;
+  };
+  readonly requested: {
+    readonly type: string;
+    readonly url: string;
+  };
+}>;
+/** A version already exists and `overwriteExistingVersion` was not set. */
+type RegistryToolsVersionExistsDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_VERSION_EXISTS', {
+  readonly packageName: string;
+  readonly version: string;
+}>;
+/** Requested version was not found on the package. */
+type RegistryToolsVersionNotFoundDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_VERSION_NOT_FOUND', {
+  readonly packageName: string;
+  readonly version: string;
+}>;
+/** Package manifest is missing and was not allowed to be created. */
+type RegistryToolsPackageMissingDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_PACKAGE_MISSING', {
+  readonly packageName: string;
+  readonly manifestPath: string;
+}>;
+/** Versions in a manifest are not sorted newest-first by SemVer. */
+type RegistryToolsVersionsUnsortedDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_VERSIONS_UNSORTED', {
+  readonly packageName: string;
+  readonly actual: readonly string[];
+  readonly expected: readonly string[];
+}>;
+/** External-registry dependency is forbidden by policy. */
+type RegistryToolsExternalRegistryDeniedDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_EXTERNAL_REGISTRY_DENIED', {
+  readonly packageName: string;
+  readonly version: string;
+  readonly dependency: string;
+  readonly registryName: string;
+  readonly bucket: 'dependencies' | 'devDependencies' | 'peerDependencies';
+}>;
+/** External-registry dependency uses a registry name not in the allow-list. */
+type RegistryToolsExternalRegistryNotAllowedDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_EXTERNAL_REGISTRY_NOT_ALLOWED', {
+  readonly packageName: string;
+  readonly version: string;
+  readonly dependency: string;
+  readonly registryName: string;
+  readonly allowList: readonly string[];
+  readonly bucket: 'dependencies' | 'devDependencies' | 'peerDependencies';
+}>;
+/** A required (non-external) dependency is not present in this registry. */
+type RegistryToolsDependencyNotInRegistryDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_DEPENDENCY_NOT_IN_REGISTRY', {
+  readonly packageName: string;
+  readonly version: string;
+  readonly dependency: string;
+}>;
+/** A dependency version range cannot be satisfied by any version in the registry. */
+type RegistryToolsDependencyRangeUnreachableDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_DEPENDENCY_RANGE_UNREACHABLE', {
+  readonly packageName: string;
+  readonly version: string;
+  readonly dependency: string;
+  readonly range: string;
+  readonly availableVersions: readonly string[];
+}>;
+/** A removal was attempted but disallowed by policy. */
+type RegistryToolsRemovalDeniedDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_REMOVAL_DENIED', {
+  readonly kind: 'version' | 'package';
+  readonly packageName: string;
+  readonly version?: string;
+  readonly policy: string;
+}>;
+/** A computed integrity does not match an expected integrity. */
+type RegistryToolsIntegrityMismatchDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_INTEGRITY_MISMATCH', {
+  readonly filePath: string;
+  readonly expectedHash: string;
+  readonly actualHash: string;
+  readonly expectedSize: number;
+  readonly actualSize: number;
+}>;
+/** A release file name does not match an accepted pattern. */
+type RegistryToolsReleaseFileNameInvalidDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_RELEASE_FILE_NAME_INVALID', {
+  readonly packageName: string;
+  readonly version: string;
+  readonly fileName: string;
+  readonly accepted: readonly string[];
+}>;
+/** Generic violation surfaced by the official-registry policy validator. */
+type RegistryToolsOfficialPolicyViolationDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_OFFICIAL_POLICY_VIOLATION', {
+  readonly rule: string;
+  readonly detail: string;
+  readonly path?: string;
+}>;
+/** An unrecognized top-level or nested key was found in a registry manifest. */
+type RegistryToolsUnknownKeyDiagnostic = DiagnosticBase<'REGISTRY_TOOLS_UNKNOWN_KEY', {
+  readonly path: string;
+  readonly key: string;
+}>;
+/** Union of all registry-tools diagnostics. */
+type RegistryToolsDiagnostic = RegistryToolsPathMismatchDiagnostic | RegistryToolsPackageSourceMismatchDiagnostic | RegistryToolsVersionExistsDiagnostic | RegistryToolsVersionNotFoundDiagnostic | RegistryToolsPackageMissingDiagnostic | RegistryToolsVersionsUnsortedDiagnostic | RegistryToolsExternalRegistryDeniedDiagnostic | RegistryToolsExternalRegistryNotAllowedDiagnostic | RegistryToolsDependencyNotInRegistryDiagnostic | RegistryToolsDependencyRangeUnreachableDiagnostic | RegistryToolsRemovalDeniedDiagnostic | RegistryToolsIntegrityMismatchDiagnostic | RegistryToolsReleaseFileNameInvalidDiagnostic | RegistryToolsOfficialPolicyViolationDiagnostic | RegistryToolsUnknownKeyDiagnostic;
+declare function createRegistryToolsPathMismatchDiagnostic(packageName: string, expectedPath: string, actualPath: string): RegistryToolsPathMismatchDiagnostic;
+declare function createRegistryToolsPackageSourceMismatchDiagnostic(packageName: string, existing: {
+  readonly type: string;
+  readonly url: string;
+}, requested: {
+  readonly type: string;
+  readonly url: string;
+}): RegistryToolsPackageSourceMismatchDiagnostic;
+declare function createRegistryToolsVersionExistsDiagnostic(packageName: string, version: string): RegistryToolsVersionExistsDiagnostic;
+declare function createRegistryToolsVersionNotFoundDiagnostic(packageName: string, version: string): RegistryToolsVersionNotFoundDiagnostic;
+declare function createRegistryToolsPackageMissingDiagnostic(packageName: string, manifestPath: string): RegistryToolsPackageMissingDiagnostic;
+declare function createRegistryToolsVersionsUnsortedDiagnostic(packageName: string, actual: readonly string[], expected: readonly string[]): RegistryToolsVersionsUnsortedDiagnostic;
+declare function createRegistryToolsExternalRegistryDeniedDiagnostic(args: Omit<RegistryToolsExternalRegistryDeniedDiagnostic['data'], never>): RegistryToolsExternalRegistryDeniedDiagnostic;
+declare function createRegistryToolsExternalRegistryNotAllowedDiagnostic(args: Omit<RegistryToolsExternalRegistryNotAllowedDiagnostic['data'], never>): RegistryToolsExternalRegistryNotAllowedDiagnostic;
+declare function createRegistryToolsDependencyNotInRegistryDiagnostic(packageName: string, version: string, dependency: string): RegistryToolsDependencyNotInRegistryDiagnostic;
+declare function createRegistryToolsDependencyRangeUnreachableDiagnostic(packageName: string, version: string, dependency: string, range: string, availableVersions: readonly string[]): RegistryToolsDependencyRangeUnreachableDiagnostic;
+declare function createRegistryToolsRemovalDeniedDiagnostic(kind: 'version' | 'package', packageName: string, policy: string, version?: string): RegistryToolsRemovalDeniedDiagnostic;
+declare function createRegistryToolsIntegrityMismatchDiagnostic(filePath: string, expectedHash: string, actualHash: string, expectedSize: number, actualSize: number): RegistryToolsIntegrityMismatchDiagnostic;
+declare function createRegistryToolsReleaseFileNameInvalidDiagnostic(packageName: string, version: string, fileName: string, accepted: readonly string[]): RegistryToolsReleaseFileNameInvalidDiagnostic;
+declare function createRegistryToolsOfficialPolicyViolationDiagnostic(rule: string, detail: string, path?: string): RegistryToolsOfficialPolicyViolationDiagnostic;
+declare function createRegistryToolsUnknownKeyDiagnostic(path: string, key: string, level?: 'warning' | 'error'): RegistryToolsUnknownKeyDiagnostic;
+//#endregion
+export { RegistryToolsDependencyNotInRegistryDiagnostic, RegistryToolsDependencyRangeUnreachableDiagnostic, RegistryToolsDiagnostic, RegistryToolsExternalRegistryDeniedDiagnostic, RegistryToolsExternalRegistryNotAllowedDiagnostic, RegistryToolsIntegrityMismatchDiagnostic, RegistryToolsOfficialPolicyViolationDiagnostic, RegistryToolsPackageMissingDiagnostic, RegistryToolsPackageSourceMismatchDiagnostic, RegistryToolsPathMismatchDiagnostic, RegistryToolsReleaseFileNameInvalidDiagnostic, RegistryToolsRemovalDeniedDiagnostic, RegistryToolsUnknownKeyDiagnostic, RegistryToolsVersionExistsDiagnostic, RegistryToolsVersionNotFoundDiagnostic, RegistryToolsVersionsUnsortedDiagnostic, createRegistryToolsDependencyNotInRegistryDiagnostic, createRegistryToolsDependencyRangeUnreachableDiagnostic, createRegistryToolsExternalRegistryDeniedDiagnostic, createRegistryToolsExternalRegistryNotAllowedDiagnostic, createRegistryToolsIntegrityMismatchDiagnostic, createRegistryToolsOfficialPolicyViolationDiagnostic, createRegistryToolsPackageMissingDiagnostic, createRegistryToolsPackageSourceMismatchDiagnostic, createRegistryToolsPathMismatchDiagnostic, createRegistryToolsReleaseFileNameInvalidDiagnostic, createRegistryToolsRemovalDeniedDiagnostic, createRegistryToolsUnknownKeyDiagnostic, createRegistryToolsVersionExistsDiagnostic, createRegistryToolsVersionNotFoundDiagnostic, createRegistryToolsVersionsUnsortedDiagnostic };

package/dist/types/uapkg-diagnostics/resolver/ResolverDiagnostics.d.ts

@@ -0,0 +1,38 @@
+import { DiagnosticBase } from "../base/Diagnostic.js";
+//#region src/resolver/ResolverDiagnostics.d.ts
+/** Two or more registries resolve the same package name to different versions (single-version kind). */
+type VersionConflictDiagnostic = DiagnosticBase<'VERSION_CONFLICT', {
+  readonly packageName: string;
+  readonly versions: readonly string[];
+  readonly registry: string;
+}>;
+/** A dependency cycle was detected. */
+type CircularDepDiagnostic = DiagnosticBase<'CIRCULAR_DEP', {
+  readonly path: readonly string[];
+}>;
+/** Requested package could not be found in any configured registry. */
+type PackageNotFoundDiagnostic = DiagnosticBase<'PACKAGE_NOT_FOUND', {
+  readonly packageName: string;
+  readonly registry: string;
+}>;
+/** No published version satisfies the requested range. */
+type VersionNotFoundDiagnostic = DiagnosticBase<'VERSION_NOT_FOUND', {
+  readonly packageName: string;
+  readonly versionRange: string;
+  readonly registry: string;
+  readonly availableVersions: readonly string[];
+}>;
+/** Same package name required from two different registries. */
+type RegistryNameCollisionDiagnostic = DiagnosticBase<'REGISTRY_NAME_COLLISION', {
+  readonly packageName: string;
+  readonly registries: readonly string[];
+}>;
+/** Union of all resolver diagnostics. */
+type ResolverDiagnostic = VersionConflictDiagnostic | CircularDepDiagnostic | PackageNotFoundDiagnostic | VersionNotFoundDiagnostic | RegistryNameCollisionDiagnostic;
+declare function createVersionConflictDiagnostic(packageName: string, versions: readonly string[], registry: string): VersionConflictDiagnostic;
+declare function createCircularDepDiagnostic(path: readonly string[]): CircularDepDiagnostic;
+declare function createPackageNotFoundDiagnostic(packageName: string, registry: string): PackageNotFoundDiagnostic;
+declare function createVersionNotFoundDiagnostic(packageName: string, versionRange: string, registry: string, availableVersions: readonly string[]): VersionNotFoundDiagnostic;
+declare function createRegistryNameCollisionDiagnostic(packageName: string, registries: readonly string[]): RegistryNameCollisionDiagnostic;
+//#endregion
+export { CircularDepDiagnostic, PackageNotFoundDiagnostic, RegistryNameCollisionDiagnostic, ResolverDiagnostic, VersionConflictDiagnostic, VersionNotFoundDiagnostic, createCircularDepDiagnostic, createPackageNotFoundDiagnostic, createRegistryNameCollisionDiagnostic, createVersionConflictDiagnostic, createVersionNotFoundDiagnostic };

package/dist/types/uapkg-diagnostics/safety/SafetyDiagnostics.d.ts

@@ -0,0 +1,33 @@
+import { DiagnosticBase } from "../base/Diagnostic.js";
+//#region src/safety/SafetyDiagnostics.d.ts
+/**
+ * A target install directory exists but has no `uapkg.json` inside.
+ * The installer refuses to overwrite because the directory's identity is
+ * unknown. Use `--force` to override.
+ */
+type SafetyTargetExistsNoManifestDiagnostic = DiagnosticBase<'SAFETY_TARGET_EXISTS_NO_MANIFEST', {
+  readonly packageName: string;
+  readonly path: string;
+}>;
+/**
+ * A plugin-kind manifest declared a custom install `path` for one of its
+ * dependencies. Only project-kind manifests may override paths; plugins fall
+ * back to the default install location and this warning is emitted.
+ */
+type SafetyPathNotProjectManifestDiagnostic = DiagnosticBase<'SAFETY_PATH_NOT_PROJECT_MANIFEST', {
+  readonly pluginName: string;
+  readonly dependencyName: string;
+  readonly requestedPath: string;
+  readonly fallbackPath: string;
+}>;
+/** Informational: a safety check was bypassed because --force was passed. */
+type SafetyOverriddenByForceDiagnostic = DiagnosticBase<'SAFETY_OVERRIDDEN_BY_FORCE', {
+  readonly packageName: string;
+  readonly policy: string;
+}>;
+type SafetyDiagnostic = SafetyTargetExistsNoManifestDiagnostic | SafetyPathNotProjectManifestDiagnostic | SafetyOverriddenByForceDiagnostic;
+declare function createSafetyTargetExistsNoManifestDiagnostic(packageName: string, path: string): SafetyTargetExistsNoManifestDiagnostic;
+declare function createSafetyPathNotProjectManifestDiagnostic(pluginName: string, dependencyName: string, requestedPath: string, fallbackPath: string): SafetyPathNotProjectManifestDiagnostic;
+declare function createSafetyOverriddenByForceDiagnostic(packageName: string, policy: string): SafetyOverriddenByForceDiagnostic;
+//#endregion
+export { SafetyDiagnostic, SafetyOverriddenByForceDiagnostic, SafetyPathNotProjectManifestDiagnostic, SafetyTargetExistsNoManifestDiagnostic, createSafetyOverriddenByForceDiagnostic, createSafetyPathNotProjectManifestDiagnostic, createSafetyTargetExistsNoManifestDiagnostic };

package/dist/types/uapkg-diagnostics/spec/SpecDiagnostics.d.ts

@@ -0,0 +1,23 @@
+import { DiagnosticBase } from "../base/Diagnostic.js";
+//#region src/spec/SpecDiagnostics.d.ts
+/** The raw CLI specifier could not be parsed into `(@org/)?name(@range)?`. */
+type InvalidPackageSpecDiagnostic = DiagnosticBase<'INVALID_PACKAGE_SPEC', {
+  readonly input: string;
+  readonly reason: string;
+}>;
+/** Organization portion of a package spec was not a valid OrgName. */
+type InvalidOrgNameDiagnostic = DiagnosticBase<'INVALID_ORG_NAME', {
+  readonly input: string;
+  readonly org: string;
+}>;
+/** Version range portion of a package spec was not a valid semver range. */
+type InvalidVersionRangeDiagnostic = DiagnosticBase<'INVALID_VERSION_RANGE', {
+  readonly input: string;
+  readonly range: string;
+}>;
+type SpecParseDiagnostic = InvalidPackageSpecDiagnostic | InvalidOrgNameDiagnostic | InvalidVersionRangeDiagnostic;
+declare function createInvalidPackageSpecDiagnostic(input: string, reason: string): InvalidPackageSpecDiagnostic;
+declare function createInvalidOrgNameDiagnostic(input: string, org: string): InvalidOrgNameDiagnostic;
+declare function createInvalidVersionRangeDiagnostic(input: string, range: string): InvalidVersionRangeDiagnostic;
+//#endregion
+export { InvalidOrgNameDiagnostic, InvalidPackageSpecDiagnostic, InvalidVersionRangeDiagnostic, SpecParseDiagnostic, createInvalidOrgNameDiagnostic, createInvalidPackageSpecDiagnostic, createInvalidVersionRangeDiagnostic };

package/dist/types/uapkg-diagnostics/types.d.ts

@@ -0,0 +1,37 @@
+import { ConfigDiagnostic } from "./config/ConfigDiagnostics.js";
+import { ControlPlaneDiagnostic } from "./controlPlane/ControlPlaneDiagnostics.js";
+import { GeneralDiagnostic } from "./general/GeneralDiagnostics.js";
+import { InstallerDiagnostic } from "./installer/InstallerDiagnostics.js";
+import { ManifestDiagnostic } from "./manifest/ManifestDiagnostics.js";
+import { PackDiagnostic } from "./pack/PackDiagnostics.js";
+import { PostinstallDiagnostic } from "./postinstall/PostinstallDiagnostics.js";
+import { PublishingDiagnostic } from "./publishing/PublishingDiagnostics.js";
+import { RegistryDiagnostic } from "./registry/RegistryDiagnostics.js";
+import { RegistryToolsDiagnostic } from "./registryTools/RegistryToolsDiagnostics.js";
+import { ResolverDiagnostic } from "./resolver/ResolverDiagnostics.js";
+import { SafetyDiagnostic } from "./safety/SafetyDiagnostics.js";
+import { SpecParseDiagnostic } from "./spec/SpecDiagnostics.js";
+//#region src/types.d.ts
+/**
+ * The unified Diagnostic type — a discriminated union of every known
+ * diagnostic, keyed on `code`.
+ *
+ * To add a new diagnostic:
+ *   1. Create its type in the appropriate family file.
+ *   2. Add it to that family's union.
+ *   3. It is automatically part of `Diagnostic` through this re-export.
+ */
+type Diagnostic = ResolverDiagnostic | ControlPlaneDiagnostic | ConfigDiagnostic | RegistryDiagnostic | RegistryToolsDiagnostic | ManifestDiagnostic | PackDiagnostic | GeneralDiagnostic | InstallerDiagnostic | PostinstallDiagnostic | PublishingDiagnostic | SafetyDiagnostic | SpecParseDiagnostic;
+/**
+ * Extract a specific diagnostic by code.
+ *
+ * @example
+ * type VC = DiagnosticByCode<'VERSION_CONFLICT'>;
+ */
+type DiagnosticByCode<C extends Diagnostic['code']> = Extract<Diagnostic, {
+  code: C;
+}>;
+/** All known diagnostic codes. */
+type DiagnosticCode = Diagnostic['code'];
+//#endregion
+export { Diagnostic, DiagnosticByCode, DiagnosticCode };

package/dist/types/uapkg-diagnostics-format/contracts/FormatterTypes.d.ts

@@ -0,0 +1,23 @@
+import { Diagnostic, DiagnosticCode } from "../../uapkg-diagnostics/index.js";
+//#region src/contracts/FormatterTypes.d.ts
+/**
+ * A function that converts a single diagnostic into a human-readable string.
+ */
+type DiagnosticFormatterFn = (diagnostic: Diagnostic) => string;
+/**
+ * A lookup of formatter functions keyed by diagnostic code.
+ */
+type FormatterMap = Partial<Record<DiagnosticCode, DiagnosticFormatterFn>>;
+/**
+ * Contract for a formatter registry that maps diagnostic codes to formatters.
+ */
+interface IFormatterRegistry {
+  /** Register a formatter for a specific code. */
+  register(code: DiagnosticCode, formatter: DiagnosticFormatterFn): void;
+  /** Format a single diagnostic. */
+  format(diagnostic: Diagnostic): string;
+  /** Format an array of diagnostics, one per line. */
+  formatAll(diagnostics: readonly Diagnostic[]): string;
+}
+//#endregion
+export { DiagnosticFormatterFn, FormatterMap, IFormatterRegistry };

package/dist/types/uapkg-diagnostics-format/defaults/defaultFormatters.d.ts

@@ -0,0 +1,8 @@
+import { FormatterMap } from "../contracts/FormatterTypes.js";
+//#region src/defaults/defaultFormatters.d.ts
+/**
+ * Merged map of all built-in formatters across families.
+ */
+declare const defaultFormatters: FormatterMap;
+//#endregion
+export { defaultFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/PlainTextFormatter.d.ts

@@ -0,0 +1,11 @@
+import { Diagnostic } from "../../uapkg-diagnostics/index.js";
+//#region src/formatters/PlainTextFormatter.d.ts
+/**
+ * Default plain-text formatter for any diagnostic.
+ *
+ * Format: `[LEVEL CODE]: message`
+ * If a hint is present: `  → hint`
+ */
+declare function formatPlainText(diagnostic: Diagnostic): string;
+//#endregion
+export { formatPlainText };

package/dist/types/uapkg-diagnostics-format/formatters/config/configFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/config/configFormatters.d.ts
+declare const configFormatters: FormatterMap;
+//#endregion
+export { configFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/installer/installerFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/installer/installerFormatters.d.ts
+declare const installerFormatters: FormatterMap;
+//#endregion
+export { installerFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/manifest/manifestFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/manifest/manifestFormatters.d.ts
+declare const manifestFormatters: FormatterMap;
+//#endregion
+export { manifestFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/pack/packFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/pack/packFormatters.d.ts
+declare const packFormatters: FormatterMap;
+//#endregion
+export { packFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/postinstall/postinstallFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/postinstall/postinstallFormatters.d.ts
+declare const postinstallFormatters: FormatterMap;
+//#endregion
+export { postinstallFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/publishing/publishingFormatters.d.ts

@@ -0,0 +1,13 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+import { Diagnostic, PublishDiagnosticFact, PublishDiagnosticResource } from "../../../uapkg-diagnostics/index.js";
+//#region src/formatters/publishing/publishingFormatters.d.ts
+declare const publishFactLabels: Record<PublishDiagnosticFact['kind'], string>;
+declare function publishResourceLabel(resource: PublishDiagnosticResource): string;
+/**
+ * Render a publish submission failure in problem → context → fix → resource
+ * order. Values have already been validated by the publish error mapper.
+ */
+declare function formatPublishRequestFailed(diagnostic: Diagnostic): string;
+declare const publishingFormatters: FormatterMap;
+//#endregion
+export { formatPublishRequestFailed, publishFactLabels, publishResourceLabel, publishingFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/registry/registryFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/registry/registryFormatters.d.ts
+declare const registryFormatters: FormatterMap;
+//#endregion
+export { registryFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/registryTools/registryToolsFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/registryTools/registryToolsFormatters.d.ts
+declare const registryToolsFormatters: FormatterMap;
+//#endregion
+export { registryToolsFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/resolver/resolverFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/resolver/resolverFormatters.d.ts
+declare const resolverFormatters: FormatterMap;
+//#endregion
+export { resolverFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/safety/safetyFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/safety/safetyFormatters.d.ts
+declare const safetyFormatters: FormatterMap;
+//#endregion
+export { safetyFormatters };

package/dist/types/uapkg-diagnostics-format/formatters/spec/specFormatters.d.ts

@@ -0,0 +1,5 @@
+import { FormatterMap } from "../../contracts/FormatterTypes.js";
+//#region src/formatters/spec/specFormatters.d.ts
+declare const specFormatters: FormatterMap;
+//#endregion
+export { specFormatters };

package/dist/types/uapkg-diagnostics-format/index.d.ts

@@ -0,0 +1,15 @@
+import { DiagnosticFormatterFn, FormatterMap, IFormatterRegistry } from "./contracts/FormatterTypes.js";
+import { defaultFormatters } from "./defaults/defaultFormatters.js";
+import { formatPlainText } from "./formatters/PlainTextFormatter.js";
+import { installerFormatters } from "./formatters/installer/installerFormatters.js";
+import { manifestFormatters } from "./formatters/manifest/manifestFormatters.js";
+import { postinstallFormatters } from "./formatters/postinstall/postinstallFormatters.js";
+import { formatPublishRequestFailed, publishingFormatters } from "./formatters/publishing/publishingFormatters.js";
+import { registryFormatters } from "./formatters/registry/registryFormatters.js";
+import { registryToolsFormatters } from "./formatters/registryTools/registryToolsFormatters.js";
+import { resolverFormatters } from "./formatters/resolver/resolverFormatters.js";
+import { safetyFormatters } from "./formatters/safety/safetyFormatters.js";
+import { specFormatters } from "./formatters/spec/specFormatters.js";
+import { FormatterRegistry, createFormatterRegistry } from "./registry/FormatterRegistry.js";
+import { bulletList, indent } from "./utils/indent.js";
+export { type DiagnosticFormatterFn, type FormatterMap, FormatterRegistry, type IFormatterRegistry, bulletList, createFormatterRegistry, defaultFormatters, formatPlainText, formatPublishRequestFailed, indent, installerFormatters, manifestFormatters, postinstallFormatters, publishingFormatters, registryFormatters, registryToolsFormatters, resolverFormatters, safetyFormatters, specFormatters };

package/dist/types/uapkg-diagnostics-format/ink/components/configInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/configInkComponents.d.ts
+declare const configInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { configInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/installerInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/installerInkComponents.d.ts
+declare const installerInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { installerInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/manifestInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/manifestInkComponents.d.ts
+declare const manifestInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { manifestInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/packInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/packInkComponents.d.ts
+declare const packInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { packInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/postinstallInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/postinstallInkComponents.d.ts
+declare const postinstallInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { postinstallInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/publishingInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/publishingInkComponents.d.ts
+declare const publishingInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { publishingInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/registryInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/registryInkComponents.d.ts
+declare const registryInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { registryInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/resolverInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/resolverInkComponents.d.ts
+declare const resolverInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { resolverInkComponents };

package/dist/types/uapkg-diagnostics-format/ink/components/safetyInkComponents.d.ts

@@ -0,0 +1,5 @@
+import { DiagnosticInkComponentMap } from "../contracts/InkTypes.js";
+//#region src/ink/components/safetyInkComponents.d.ts
+declare const safetyInkComponents: DiagnosticInkComponentMap;
+//#endregion
+export { safetyInkComponents };