@uapkg/cli 1.4.0 → 1.5.0

package/dist/types/uapkg-registry-core/resolution/SemverSelectionPolicy.d.ts

@@ -0,0 +1,36 @@
+import { PackageVersion, VersionRange } from "../../uapkg-common-schema/index.js";
+//#region src/resolution/SemverSelectionPolicy.d.ts
+/**
+ * npm-style version selection policy.
+ *
+ * Rules (matching npm's resolver behavior via `semver`):
+ *
+ *  1. A range that does not explicitly include a prerelease tag
+ *     (e.g. `^1.0.0`) will never auto-select a prerelease version.
+ *  2. A range with an explicit prerelease tag (e.g. `^1.0.0-0`,
+ *     `>=1.0.0-beta.1`) opts-in to prereleases via `includePrerelease`.
+ *  3. If the current installed version is a prerelease and a stable
+ *     version satisfies the range, the stable version wins — users
+ *     should escape the prerelease channel as soon as possible.
+ *  4. All other ties are broken by `semver.rcompare` (highest wins).
+ *
+ * This class is pure: no IO, no shared state.
+ */
+declare class SemverSelectionPolicy {
+  /**
+   * Select the best matching version.
+   *
+   * @param candidates All versions available in the registry manifest.
+   * @param range The semver range from the dependency declaration.
+   * @param current The version already installed/locked, if any. Used to
+   *   bias escape-from-prerelease (rule #3).
+   * @returns The best matching version, or `null` if nothing satisfies.
+   */
+  selectBest(candidates: readonly PackageVersion[], range: VersionRange, current?: PackageVersion): PackageVersion | null;
+  /** Does the range string itself mention a prerelease tag? */
+  private rangeExplicitlyOptsInToPrerelease;
+  /** Is the given version string a prerelease? */
+  private isPrerelease;
+}
+//#endregion
+export { SemverSelectionPolicy };

package/dist/types/uapkg-registry-schema/index.d.ts

@@ -0,0 +1,9 @@
+import { getRegistryPackagePath, getRegistryPackagePathSegments } from "./paths/RegistryPackagePath.js";
+import { Integrity, IntegritySchema } from "./schemas/IntegritySchema.js";
+import { RegistryDependency, RegistryDependencyDeclaration, RegistryDependencyDeclarationSchema, RegistryDependencyLongSchema, RegistryDependencySchema, RegistryDependencyShortSchema, normalizeRegistryDependencyDeclaration, normalizeRegistryDependencyRecord, toRegistryDependencyDeclaration, toRegistryDependencyRecordDeclaration } from "./schemas/RegistryDependencySchema.js";
+import { RegistryMeta, RegistryMetaSchema, RegistryType, RegistryTypeSchema } from "./schemas/RegistryMetaSchema.js";
+import { PackageRegistryManifest, PackageRegistryManifestSchema, createPackageRegistryManifestSchema } from "./schemas/PackageRegistryManifestSchema.js";
+import { PackageSource, PackageSourceSchema } from "./schemas/PackageSourceSchema.js";
+import { RegistryAsset, RegistryAssetSchema } from "./schemas/RegistryAssetSchema.js";
+import { RegistryVersion, RegistryVersionSchema, ReleaseFiles, ReleaseFilesSchema, VersionMeta, VersionMetaSchema } from "./schemas/RegistryVersionSchema.js";
+export { type Integrity, IntegritySchema, type PackageRegistryManifest, PackageRegistryManifestSchema, type PackageSource, PackageSourceSchema, type RegistryAsset, RegistryAssetSchema, type RegistryDependency, type RegistryDependencyDeclaration, RegistryDependencyDeclarationSchema, RegistryDependencyLongSchema, RegistryDependencySchema, RegistryDependencyShortSchema, type RegistryMeta, RegistryMetaSchema, type RegistryType, RegistryTypeSchema, type RegistryVersion, RegistryVersionSchema, type ReleaseFiles, ReleaseFilesSchema, type VersionMeta, VersionMetaSchema, createPackageRegistryManifestSchema, getRegistryPackagePath, getRegistryPackagePathSegments, normalizeRegistryDependencyDeclaration, normalizeRegistryDependencyRecord, toRegistryDependencyDeclaration, toRegistryDependencyRecordDeclaration };

package/dist/types/uapkg-registry-schema/paths/RegistryPackagePath.d.ts

@@ -0,0 +1,15 @@
+//#region src/paths/RegistryPackagePath.d.ts
+/**
+ * Canonical repository-relative path of a package's registry manifest.
+ *
+ * - unscoped: `packages/{first-letter}/{package-name}.json`
+ * - scoped:   `packages/@{scope}/{package-name}.json`
+ *
+ * Segments are returned for path-separator-agnostic joining; use
+ * {@link getRegistryPackagePath} for the canonical `/`-joined form.
+ */
+declare function getRegistryPackagePathSegments(packageName: string): readonly string[];
+/** Canonical `/`-separated repository-relative registry manifest path. */
+declare function getRegistryPackagePath(packageName: string): string;
+//#endregion
+export { getRegistryPackagePath, getRegistryPackagePathSegments };

package/dist/types/uapkg-registry-schema/schemas/IntegritySchema.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+//#region src/schemas/IntegritySchema.d.ts
+/**
+ * Integrity block for a release asset.
+ */
+declare const IntegritySchema: z.ZodObject<{
+  hash: z.core.$ZodBranded<z.ZodString, "AssetHash", "out">;
+  size: z.ZodNumber;
+}, z.core.$strict>;
+type Integrity = z.infer<typeof IntegritySchema>;
+//#endregion
+export { Integrity, IntegritySchema };

package/dist/types/uapkg-registry-schema/schemas/PackageRegistryManifestSchema.d.ts

@@ -0,0 +1,108 @@
+import { RegistryDependency } from "./RegistryDependencySchema.js";
+import { RegistryType } from "./RegistryMetaSchema.js";
+import { z } from "zod";
+//#region src/schemas/PackageRegistryManifestSchema.d.ts
+/**
+ * The top-level package registry manifest — one per package in the registry repo.
+ *
+ * File layout: `packages/{first-letter}/{package-name}.json` for unscoped
+ * names and `packages/@{scope}/{package-name}.json` for scoped names.
+ * Unknown optional members are tolerated rather than rejected so newer
+ * records do not break older clients.
+ */
+declare const PackageRegistryManifestSchema: z.ZodObject<{
+  name: z.core.$ZodBranded<z.ZodString, "PackageName", "out">;
+  packageSource: z.ZodObject<{
+    type: z.ZodLiteral<"git">;
+    url: z.ZodURL;
+  }, z.core.$strict>;
+  versions: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">, z.ZodObject<{
+    gitTree: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "GitTree", "out">>;
+    private: z.ZodDefault<z.ZodBoolean>;
+    meta: z.ZodOptional<z.ZodObject<{
+      publishedAt: z.core.$ZodBranded<z.ZodNumber, "UnixTimestamp", "out">;
+    }, z.core.$strip>>;
+    releaseFiles: z.ZodObject<{
+      package: z.ZodObject<{
+        url: z.ZodURL;
+        integrity: z.ZodObject<{
+          hash: z.core.$ZodBranded<z.ZodString, "AssetHash", "out">;
+          size: z.ZodNumber;
+        }, z.core.$strict>;
+      }, z.core.$strict>;
+    }, z.core.$strip>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+      version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+      registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+      version: string & z.$brand<"VersionRange">;
+      registry?: (string & z.$brand<"RegistryName">) | undefined;
+    } | (string & z.$brand<"VersionRange">)>>>>;
+    devDependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+      version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+      registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+      version: string & z.$brand<"VersionRange">;
+      registry?: (string & z.$brand<"RegistryName">) | undefined;
+    } | (string & z.$brand<"VersionRange">)>>>>;
+    peerDependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+      version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+      registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+      version: string & z.$brand<"VersionRange">;
+      registry?: (string & z.$brand<"RegistryName">) | undefined;
+    } | (string & z.$brand<"VersionRange">)>>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Add the trusted registry-type policy to the structural package schema.
+ * Public registry versions must identify their source Git tree; private
+ * registry versions may omit it.
+ */
+declare function createPackageRegistryManifestSchema(registryType: RegistryType): z.ZodObject<{
+  name: z.core.$ZodBranded<z.ZodString, "PackageName", "out">;
+  packageSource: z.ZodObject<{
+    type: z.ZodLiteral<"git">;
+    url: z.ZodURL;
+  }, z.core.$strict>;
+  versions: z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">, z.ZodObject<{
+    gitTree: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "GitTree", "out">>;
+    private: z.ZodDefault<z.ZodBoolean>;
+    meta: z.ZodOptional<z.ZodObject<{
+      publishedAt: z.core.$ZodBranded<z.ZodNumber, "UnixTimestamp", "out">;
+    }, z.core.$strip>>;
+    releaseFiles: z.ZodObject<{
+      package: z.ZodObject<{
+        url: z.ZodURL;
+        integrity: z.ZodObject<{
+          hash: z.core.$ZodBranded<z.ZodString, "AssetHash", "out">;
+          size: z.ZodNumber;
+        }, z.core.$strict>;
+      }, z.core.$strict>;
+    }, z.core.$strip>;
+    dependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+      version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+      registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+      version: string & z.$brand<"VersionRange">;
+      registry?: (string & z.$brand<"RegistryName">) | undefined;
+    } | (string & z.$brand<"VersionRange">)>>>>;
+    devDependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+      version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+      registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+      version: string & z.$brand<"VersionRange">;
+      registry?: (string & z.$brand<"RegistryName">) | undefined;
+    } | (string & z.$brand<"VersionRange">)>>>>;
+    peerDependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+      version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+      registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+      version: string & z.$brand<"VersionRange">;
+      registry?: (string & z.$brand<"RegistryName">) | undefined;
+    } | (string & z.$brand<"VersionRange">)>>>>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+type PackageRegistryManifest = z.infer<typeof PackageRegistryManifestSchema>;
+//#endregion
+export { PackageRegistryManifest, PackageRegistryManifestSchema, createPackageRegistryManifestSchema };

package/dist/types/uapkg-registry-schema/schemas/PackageSourceSchema.d.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+//#region src/schemas/PackageSourceSchema.d.ts
+/**
+ * Describes where the package source lives.
+ */
+declare const PackageSourceSchema: z.ZodObject<{
+  type: z.ZodLiteral<"git">;
+  url: z.ZodURL;
+}, z.core.$strict>;
+type PackageSource = z.infer<typeof PackageSourceSchema>;
+//#endregion
+export { PackageSource, PackageSourceSchema };

package/dist/types/uapkg-registry-schema/schemas/RegistryAssetSchema.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+//#region src/schemas/RegistryAssetSchema.d.ts
+/**
+ * A downloadable release asset with integrity metadata.
+ */
+declare const RegistryAssetSchema: z.ZodObject<{
+  url: z.ZodURL;
+  integrity: z.ZodObject<{
+    hash: z.core.$ZodBranded<z.ZodString, "AssetHash", "out">;
+    size: z.ZodNumber;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type RegistryAsset = z.infer<typeof RegistryAssetSchema>;
+//#endregion
+export { RegistryAsset, RegistryAssetSchema };

package/dist/types/uapkg-registry-schema/schemas/RegistryDependencySchema.d.ts

@@ -0,0 +1,36 @@
+import { RegistryNameSchema, VersionRangeSchema } from "../../uapkg-common-schema/index.js";
+import { z } from "zod";
+//#region src/schemas/RegistryDependencySchema.d.ts
+/**
+ * A dependency entry stored inside a registry version.
+ *
+ * Both `version` (range) and `registry` (logical name) are required
+ * so that multi-registry resolution can work.
+ */
+declare const RegistryDependencyLongSchema: z.ZodObject<{
+  version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+  registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+}, z.core.$strict>;
+declare const RegistryDependencyShortSchema: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+declare const RegistryDependencyDeclarationSchema: z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+  version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+  registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+}, z.core.$strict>]>;
+interface RegistryDependency {
+  readonly version: z.infer<typeof VersionRangeSchema>;
+  readonly registry?: z.infer<typeof RegistryNameSchema>;
+}
+type RegistryDependencyDeclaration = z.infer<typeof RegistryDependencyDeclarationSchema>;
+declare const RegistryDependencySchema: z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+  version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+  registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+}, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+  version: string & z.$brand<"VersionRange">;
+  registry?: (string & z.$brand<"RegistryName">) | undefined;
+} | (string & z.$brand<"VersionRange">)>>;
+declare function normalizeRegistryDependencyDeclaration(input: RegistryDependencyDeclaration | RegistryDependency): RegistryDependency;
+declare function toRegistryDependencyDeclaration(input: RegistryDependency): RegistryDependencyDeclaration;
+declare function normalizeRegistryDependencyRecord(input?: Record<string, RegistryDependencyDeclaration | RegistryDependency>): Record<string, RegistryDependency> | undefined;
+declare function toRegistryDependencyRecordDeclaration(input?: Record<string, RegistryDependency>): Record<string, RegistryDependencyDeclaration> | undefined;
+//#endregion
+export { RegistryDependency, RegistryDependencyDeclaration, RegistryDependencyDeclarationSchema, RegistryDependencyLongSchema, RegistryDependencySchema, RegistryDependencyShortSchema, normalizeRegistryDependencyDeclaration, normalizeRegistryDependencyRecord, toRegistryDependencyDeclaration, toRegistryDependencyRecordDeclaration };

package/dist/types/uapkg-registry-schema/schemas/RegistryMetaSchema.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+//#region src/schemas/RegistryMetaSchema.d.ts
+/** Immutable control-plane classification of a UAPKG registry. */
+declare const RegistryTypeSchema: z.ZodEnum<{
+  private: "private";
+  public: "public";
+}>;
+/**
+ * Canonical `.uapkg/registry.meta.json` contract.
+ *
+ * The v1 core retains registry selection, display name, and package-policy
+ * context. Unknown members remain tolerated and preserved, including richer
+ * existing v1 files, while an unknown `schemaVersion` still fails closed.
+ */
+declare const RegistryMetaSchema: z.ZodObject<{
+  schemaVersion: z.ZodLiteral<1>;
+  registry: z.ZodObject<{
+    id: z.ZodUUID;
+    name: z.core.$ZodBranded<z.ZodString, "RegistryName", "out">;
+    registryType: z.ZodEnum<{
+      private: "private";
+      public: "public";
+    }>;
+  }, z.core.$loose>;
+}, z.core.$loose>;
+type RegistryMeta = z.infer<typeof RegistryMetaSchema>;
+type RegistryType = z.infer<typeof RegistryTypeSchema>;
+//#endregion
+export { RegistryMeta, RegistryMetaSchema, RegistryType, RegistryTypeSchema };

package/dist/types/uapkg-registry-schema/schemas/RegistryVersionSchema.d.ts

@@ -0,0 +1,71 @@
+import { RegistryDependency } from "./RegistryDependencySchema.js";
+import { z } from "zod";
+//#region src/schemas/RegistryVersionSchema.d.ts
+/**
+ * Release files attached to a version.
+ */
+declare const ReleaseFilesSchema: z.ZodObject<{
+  package: z.ZodObject<{
+    url: z.ZodURL;
+    integrity: z.ZodObject<{
+      hash: z.core.$ZodBranded<z.ZodString, "AssetHash", "out">;
+      size: z.ZodNumber;
+    }, z.core.$strict>;
+  }, z.core.$strict>;
+}, z.core.$strip>;
+/**
+ * Metadata about a published version.
+ */
+declare const VersionMetaSchema: z.ZodObject<{
+  publishedAt: z.core.$ZodBranded<z.ZodNumber, "UnixTimestamp", "out">;
+}, z.core.$strip>;
+/**
+ * A single version entry within a package registry manifest.
+ *
+ * Unknown optional members are tolerated (and ignored) rather than rejected:
+ * install-time verification compares the mandatory core plus the optional
+ * keys understood on both sides, so a newer record must not break an older
+ * client. The mandatory core itself stays strictly validated.
+ */
+declare const RegistryVersionSchema: z.ZodObject<{
+  gitTree: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "GitTree", "out">>;
+  private: z.ZodDefault<z.ZodBoolean>;
+  meta: z.ZodOptional<z.ZodObject<{
+    publishedAt: z.core.$ZodBranded<z.ZodNumber, "UnixTimestamp", "out">;
+  }, z.core.$strip>>;
+  releaseFiles: z.ZodObject<{
+    package: z.ZodObject<{
+      url: z.ZodURL;
+      integrity: z.ZodObject<{
+        hash: z.core.$ZodBranded<z.ZodString, "AssetHash", "out">;
+        size: z.ZodNumber;
+      }, z.core.$strict>;
+    }, z.core.$strict>;
+  }, z.core.$strip>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+    version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+    registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+  }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+    version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+    registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+  }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.core.$ZodBranded<z.ZodString, "PackageName", "out">, z.ZodPipe<z.ZodUnion<readonly [z.core.$ZodBranded<z.ZodString, "VersionRange", "out">, z.ZodObject<{
+    version: z.core.$ZodBranded<z.ZodString, "VersionRange", "out">;
+    registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+  }, z.core.$strict>]>, z.ZodTransform<RegistryDependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+}, z.core.$strip>;
+type RegistryVersion = z.infer<typeof RegistryVersionSchema>;
+type ReleaseFiles = z.infer<typeof ReleaseFilesSchema>;
+type VersionMeta = z.infer<typeof VersionMetaSchema>;
+//#endregion
+export { RegistryVersion, RegistryVersionSchema, ReleaseFiles, ReleaseFilesSchema, VersionMeta, VersionMetaSchema };

package/dist/types/uapkg-registry-tools/aggregator/RegistryToolsAggregator.d.ts

@@ -0,0 +1,45 @@
+import { Diagnostic, DiagnosticLevel } from "../../uapkg-diagnostics/index.js";
+//#region src/aggregator/RegistryToolsAggregator.d.ts
+/**
+ * Process-wide aggregator for all diagnostics emitted by `@uapkg/registry-tools`.
+ *
+ * Goals:
+ *  - Single source of truth for CI consumers that want one consolidated list of
+ *    warnings and errors across an entire run.
+ *  - Plan-then-apply flows do not double-report: diagnostics with
+ *    `emitPolicy: 'once'` are deduplicated by their stable `emitFingerprint`.
+ *
+ * This is a true singleton — instantiating multiple `RegistryTools` objects in
+ * the same process all push into the same aggregator.
+ */
+declare class RegistryToolsAggregator {
+  private static instance;
+  private readonly items;
+  private readonly seenFingerprints;
+  /** Get (or lazily create) the process-wide singleton aggregator. */
+  static getInstance(): RegistryToolsAggregator;
+  /** Replace the singleton — primarily intended for tests. */
+  static resetForTests(): void;
+  /**
+   * Add a diagnostic to the aggregator.
+   *
+   * If the diagnostic uses `emitPolicy: 'once'` and a matching fingerprint has
+   * already been recorded, the call is a no-op and the method returns `false`.
+   */
+  add(diagnostic: Diagnostic): boolean;
+  /** Add many diagnostics. */
+  addMany(diagnostics: readonly Diagnostic[]): void;
+  /** All diagnostics collected so far, in insertion order. */
+  all(): readonly Diagnostic[];
+  /** Diagnostics filtered by level. */
+  byLevel(level: DiagnosticLevel): readonly Diagnostic[];
+  errors(): readonly Diagnostic[];
+  warnings(): readonly Diagnostic[];
+  hasErrors(): boolean;
+  /** Wipe collected diagnostics. */
+  clear(): void;
+}
+/** Convenience accessor for the process-wide singleton. */
+declare function getRegistryToolsAggregator(): RegistryToolsAggregator;
+//#endregion
+export { RegistryToolsAggregator, getRegistryToolsAggregator };

package/dist/types/uapkg-registry-tools/contracts/RegistryToolsTypes.d.ts

@@ -0,0 +1,116 @@
+import { Diagnostic } from "../../uapkg-diagnostics/index.js";
+import { Integrity, PackageRegistryManifest, PackageSource, RegistryVersion } from "../../uapkg-registry-schema/index.js";
+import { PackageName, PackageVersion } from "../../uapkg-common-schema/index.js";
+//#region src/contracts/RegistryToolsTypes.d.ts
+type ExternalRegistryPolicyMode = 'deny' | 'allow-listed' | 'allow-any';
+type RemovalsPolicyMode = 'deny' | 'allow-version-remove' | 'allow-package-remove';
+type UnknownKeysPolicyMode = 'ignore' | 'warn' | 'error';
+interface RegistryToolsPolicy {
+  readonly externalRegistries?: ExternalRegistryPolicyMode;
+  readonly allowedExternalRegistryNames?: readonly string[];
+  readonly removals?: RemovalsPolicyMode;
+  readonly unknownKeys?: UnknownKeysPolicyMode;
+  readonly requireExistingDependencies?: boolean;
+  readonly requireReachableDependencyRanges?: boolean;
+  readonly requireSortedVersions?: boolean;
+}
+/** Fully resolved policy with defaults applied. */
+type ResolvedRegistryToolsPolicy = Required<RegistryToolsPolicy>;
+interface RegistryToolsOptions {
+  /** Root directory of the registry repo (NOT a package directory). */
+  readonly cwd: string;
+  readonly policy?: RegistryToolsPolicy;
+}
+interface PackageSummary {
+  readonly name: PackageName;
+  readonly manifestPath: string;
+  readonly versionCount: number;
+}
+interface WriteManifestResult {
+  readonly manifestPath: string;
+  readonly bytesWritten: number;
+}
+interface WriteResult {
+  readonly path: string;
+  readonly bytesWritten: number;
+}
+interface RegistryVersionValidationReport {
+  readonly packageName: PackageName;
+  readonly version: PackageVersion;
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface PackageValidationReport {
+  readonly packageName: PackageName;
+  readonly manifestPath: string;
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface RegistryValidationReport {
+  readonly packageReports: readonly PackageValidationReport[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface RegistryLintReport {
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface ChangedManifestValidation {
+  readonly perFile: readonly {
+    readonly path: string;
+    readonly diagnostics: readonly Diagnostic[];
+  }[];
+}
+interface DependencyValidationReport {
+  readonly packageName: PackageName;
+  readonly version: PackageVersion;
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface ExternalRegistryPolicyReport {
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface ReleaseFileNameReport {
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface OfficialPackagePolicyReport {
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface AddPackageVersionRequest {
+  readonly packageName: PackageName;
+  readonly version: PackageVersion;
+  readonly packageSource: PackageSource;
+  readonly registryVersion: RegistryVersion;
+  readonly createPackageManifestIfMissing?: boolean;
+  readonly overwriteExistingVersion?: boolean;
+}
+interface RemovePackageVersionRequest {
+  readonly packageName: PackageName;
+  readonly version: PackageVersion;
+}
+interface RemovePackageRequest {
+  readonly packageName: PackageName;
+}
+type RegistryMutationOperation = {
+  readonly kind: 'create-manifest';
+  readonly path: string;
+} | {
+  readonly kind: 'update-manifest';
+  readonly path: string;
+} | {
+  readonly kind: 'delete-manifest';
+  readonly path: string;
+};
+interface RegistryMutationPlan {
+  readonly operations: readonly RegistryMutationOperation[];
+  readonly nextManifest?: PackageRegistryManifest;
+  readonly diagnostics: readonly Diagnostic[];
+}
+interface RegistryMutationSummary {
+  readonly operations: readonly RegistryMutationOperation[];
+  readonly diagnostics: readonly Diagnostic[];
+}
+type IntegrityAlgorithm = 'sha256' | 'sha512';
+interface IntegrityVerificationResult {
+  readonly ok: boolean;
+  readonly actual: Integrity;
+  readonly expected: Integrity;
+}
+declare const REGISTRY_TOOLS_PACKAGES_DIR = "packages";
+//#endregion
+export { AddPackageVersionRequest, ChangedManifestValidation, DependencyValidationReport, ExternalRegistryPolicyMode, ExternalRegistryPolicyReport, IntegrityAlgorithm, IntegrityVerificationResult, OfficialPackagePolicyReport, PackageSummary, PackageValidationReport, REGISTRY_TOOLS_PACKAGES_DIR, RegistryLintReport, RegistryMutationOperation, RegistryMutationPlan, RegistryMutationSummary, RegistryToolsOptions, RegistryToolsPolicy, RegistryValidationReport, RegistryVersionValidationReport, ReleaseFileNameReport, RemovalsPolicyMode, RemovePackageRequest, RemovePackageVersionRequest, ResolvedRegistryToolsPolicy, UnknownKeysPolicyMode, WriteManifestResult, WriteResult };

package/dist/types/uapkg-registry-tools/index.d.ts

@@ -0,0 +1,18 @@
+import { RegistryToolsAggregator, getRegistryToolsAggregator } from "./aggregator/RegistryToolsAggregator.js";
+import { AddPackageVersionRequest, ChangedManifestValidation, DependencyValidationReport, ExternalRegistryPolicyMode, ExternalRegistryPolicyReport, IntegrityAlgorithm, IntegrityVerificationResult, OfficialPackagePolicyReport, PackageSummary, PackageValidationReport, RegistryLintReport, RegistryMutationOperation, RegistryMutationPlan, RegistryMutationSummary, RegistryToolsOptions, RegistryToolsPolicy, RegistryValidationReport, RegistryVersionValidationReport, ReleaseFileNameReport, RemovalsPolicyMode, RemovePackageRequest, RemovePackageVersionRequest, ResolvedRegistryToolsPolicy, UnknownKeysPolicyMode, WriteManifestResult, WriteResult } from "./contracts/RegistryToolsTypes.js";
+import { IntegrityCalculator } from "./io/IntegrityCalculator.js";
+import { RegistryRepoPaths } from "./paths/RegistryRepoPaths.js";
+import { ManifestStore } from "./io/ManifestStore.js";
+import { PackageLister } from "./listing/PackageLister.js";
+import { DependencyReachabilityValidator } from "./validation/DependencyReachabilityValidator.js";
+import { ExternalRegistryPolicyValidator } from "./validation/ExternalRegistryPolicyValidator.js";
+import { AddPackageVersionPlanner } from "./mutation/AddPackageVersionPlanner.js";
+import { RemovePackagePlanner } from "./mutation/RemovePackagePlanner.js";
+import { RemovePackageVersionPlanner } from "./mutation/RemovePackageVersionPlanner.js";
+import { sortVersionsNewestFirst } from "./mutation/VersionSorter.js";
+import { OfficialRegistryPolicyRequest, OfficialRegistryPolicyValidator } from "./validation/OfficialRegistryPolicyValidator.js";
+import { RegistryTools } from "./tools/RegistryTools.js";
+import { ManifestValidator } from "./validation/ManifestValidator.js";
+import { RegistryValidator } from "./validation/RegistryValidator.js";
+import { ReleaseFileNameValidator } from "./validation/ReleaseFileNameValidator.js";
+export { AddPackageVersionPlanner, type AddPackageVersionRequest, type ChangedManifestValidation, DependencyReachabilityValidator, type DependencyValidationReport, type ExternalRegistryPolicyMode, type ExternalRegistryPolicyReport, ExternalRegistryPolicyValidator, type IntegrityAlgorithm, IntegrityCalculator, type IntegrityVerificationResult, ManifestStore, ManifestValidator, type OfficialPackagePolicyReport, type OfficialRegistryPolicyRequest, OfficialRegistryPolicyValidator, PackageLister, type PackageSummary, type PackageValidationReport, type RegistryLintReport, type RegistryMutationOperation, type RegistryMutationPlan, type RegistryMutationSummary, RegistryRepoPaths, RegistryTools, RegistryToolsAggregator, type RegistryToolsOptions, type RegistryToolsPolicy, type RegistryValidationReport, RegistryValidator, type RegistryVersionValidationReport, type ReleaseFileNameReport, ReleaseFileNameValidator, type RemovalsPolicyMode, RemovePackagePlanner, type RemovePackageRequest, RemovePackageVersionPlanner, type RemovePackageVersionRequest, type ResolvedRegistryToolsPolicy, type UnknownKeysPolicyMode, type WriteManifestResult, type WriteResult, getRegistryToolsAggregator, sortVersionsNewestFirst };

package/dist/types/uapkg-registry-tools/io/IntegrityCalculator.d.ts

@@ -0,0 +1,20 @@
+import { RegistryToolsAggregator } from "../aggregator/RegistryToolsAggregator.js";
+import { IntegrityAlgorithm, IntegrityVerificationResult } from "../contracts/RegistryToolsTypes.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { Integrity } from "../../uapkg-registry-schema/index.js";
+//#region src/io/IntegrityCalculator.d.ts
+/**
+ * Computes and verifies file integrity locally — never reaches the network.
+ */
+declare class IntegrityCalculator {
+  private readonly aggregator;
+  constructor(aggregator: RegistryToolsAggregator);
+  /** Stream-hash a local file and return a validated `Integrity` record. */
+  compute(filePath: string, algorithm?: IntegrityAlgorithm): Promise<Result<Integrity>>;
+  /** Recompute a file's integrity and compare it to an expected value. */
+  verify(filePath: string, expected: Integrity): Promise<Result<IntegrityVerificationResult>>;
+  /** Hash a file by streaming. */
+  private streamHash;
+}
+//#endregion
+export { IntegrityCalculator };

package/dist/types/uapkg-registry-tools/io/ManifestStore.d.ts

@@ -0,0 +1,41 @@
+import { RegistryToolsAggregator } from "../aggregator/RegistryToolsAggregator.js";
+import { WriteManifestResult } from "../contracts/RegistryToolsTypes.js";
+import { RegistryRepoPaths } from "../paths/RegistryRepoPaths.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { PackageRegistryManifest } from "../../uapkg-registry-schema/index.js";
+import { PackageName } from "../../uapkg-common-schema/index.js";
+//#region src/io/ManifestStore.d.ts
+/**
+ * Reads, validates, and writes registry-package manifests on disk.
+ *
+ * Responsibilities:
+ *  - Resolve manifest paths for a given package name.
+ *  - Decode JSON safely.
+ *  - Validate against `PackageRegistryManifestSchema`.
+ *  - Write deterministic, sorted, pretty-printed JSON.
+ */
+declare class ManifestStore {
+  private readonly paths;
+  private readonly aggregator;
+  constructor(paths: RegistryRepoPaths, aggregator: RegistryToolsAggregator);
+  /** Resolve the manifest path for a package. Pure path computation. */
+  resolveManifestPath(packageName: PackageName): string;
+  /** True if the manifest file exists on disk. */
+  exists(packageName: PackageName): boolean;
+  /** Read and validate a package manifest. Emits a missing-package diagnostic when absent. */
+  read(packageName: PackageName): Promise<Result<PackageRegistryManifest>>;
+  /** Read and validate a manifest file at an arbitrary path. */
+  readFromPath(filePath: string): Promise<Result<PackageRegistryManifest>>;
+  /**
+   * Write a package manifest deterministically.
+   *
+   * Versions are pre-sorted newest-first by SemVer. The on-disk JSON uses
+   * stable key ordering and a trailing newline so version control shows
+   * minimal diffs.
+   */
+  write(manifest: PackageRegistryManifest): Promise<Result<WriteManifestResult>>;
+  /** Sort versions newest-first by SemVer; preserves all other fields. */
+  normalize(manifest: PackageRegistryManifest): PackageRegistryManifest;
+}
+//#endregion
+export { ManifestStore };

package/dist/types/uapkg-registry-tools/listing/PackageLister.d.ts

@@ -0,0 +1,22 @@
+import { RegistryToolsAggregator } from "../aggregator/RegistryToolsAggregator.js";
+import { PackageSummary } from "../contracts/RegistryToolsTypes.js";
+import { RegistryRepoPaths } from "../paths/RegistryRepoPaths.js";
+import { ManifestStore } from "../io/ManifestStore.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { PackageName } from "../../uapkg-common-schema/index.js";
+//#region src/listing/PackageLister.d.ts
+/**
+ * Lists packages in the registry repo by walking `packages/{first-letter}/*.json`.
+ */
+declare class PackageLister {
+  private readonly paths;
+  private readonly store;
+  private readonly aggregator;
+  constructor(paths: RegistryRepoPaths, store: ManifestStore, aggregator: RegistryToolsAggregator);
+  /** All package names in the registry repo, sorted alphabetically. */
+  listPackageNames(): Promise<Result<PackageName[]>>;
+  /** Summaries (manifest path + version count) for every package. */
+  listSummaries(): Promise<Result<PackageSummary[]>>;
+}
+//#endregion
+export { PackageLister };