@uapkg/cli 1.4.0 → 1.5.0

package/dist/types/uapkg-package-manifest-schema/manifest/ManifestSchema.d.ts

@@ -0,0 +1,106 @@
+import { Dependency } from "./DependencySchema.js";
+import { z } from "zod";
+//#region src/manifest/ManifestSchema.d.ts
+/**
+ * Discriminated manifest schema — dispatches to `ProjectManifestSchema`
+ * or `PluginManifestSchema` based on the `kind` field.
+ */
+declare const ManifestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  name: z.core.$ZodBranded<z.ZodString, "PackageName", "out">;
+  version: z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">;
+  private: z.ZodOptional<z.ZodBoolean>;
+  publish: z.ZodOptional<z.ZodObject<{
+    registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    owner: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    asset: z.ZodOptional<z.ZodString>;
+    manifestPath: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  kind: z.ZodLiteral<"project">;
+  uapkgVersion: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">>;
+  overrides: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  postinstall: z.ZodOptional<z.ZodObject<{
+    modules: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>;
+  dev: z.ZodOptional<z.ZodObject<{
+    harness: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$strip>>;
+}, z.core.$loose>, z.ZodObject<{
+  name: z.core.$ZodBranded<z.ZodString, "PackageName", "out">;
+  version: z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">;
+  private: z.ZodOptional<z.ZodBoolean>;
+  publish: z.ZodOptional<z.ZodObject<{
+    registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    owner: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    asset: z.ZodOptional<z.ZodString>;
+    manifestPath: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  kind: z.ZodLiteral<"plugin">;
+  uapkgVersion: z.ZodOptional<z.ZodNever>;
+}, z.core.$loose>], "kind">;
+type Manifest = z.infer<typeof ManifestSchema>;
+//#endregion
+export { Manifest, ManifestSchema };

package/dist/types/uapkg-package-manifest-schema/manifest/PluginManifestSchema.d.ts

@@ -0,0 +1,52 @@
+import { Dependency } from "./DependencySchema.js";
+import { z } from "zod";
+//#region src/manifest/PluginManifestSchema.d.ts
+/**
+ * Plugin manifest — `uapkg.json` for a plugin package.
+ *
+ * Plugins MUST NOT have `overrides`.
+ */
+declare const PluginManifestSchema: z.ZodObject<{
+  name: z.core.$ZodBranded<z.ZodString, "PackageName", "out">;
+  version: z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">;
+  private: z.ZodOptional<z.ZodBoolean>;
+  publish: z.ZodOptional<z.ZodObject<{
+    registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    owner: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    asset: z.ZodOptional<z.ZodString>;
+    manifestPath: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  kind: z.ZodLiteral<"plugin">;
+  uapkgVersion: z.ZodOptional<z.ZodNever>;
+}, z.core.$loose>;
+type PluginManifest = z.infer<typeof PluginManifestSchema>;
+//#endregion
+export { PluginManifest, PluginManifestSchema };

package/dist/types/uapkg-package-manifest-schema/manifest/ProjectManifestSchema.d.ts

@@ -0,0 +1,80 @@
+import { Dependency } from "./DependencySchema.js";
+import { z } from "zod";
+//#region src/manifest/ProjectManifestSchema.d.ts
+/**
+ * Project-only postinstall overrides.
+ *
+ * - `modules` — explicit list of Unreal module names to pass to postinstall
+ *               scripts. Overrides the names discovered from the project's
+ *               `.uproject` `Modules[]`. Intended for harness / test projects
+ *               that want to limit which modules receive UAPKG-BEGIN/END
+ *               injection blocks.
+ */
+declare const ProjectPostinstallSchema: z.ZodObject<{
+  modules: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/**
+ * Project manifest — the root `uapkg.json` for a project.
+ *
+ * Projects MAY specify `overrides` to pin transitive dependency versions.
+ */
+declare const ProjectManifestSchema: z.ZodObject<{
+  name: z.core.$ZodBranded<z.ZodString, "PackageName", "out">;
+  version: z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">;
+  private: z.ZodOptional<z.ZodBoolean>;
+  publish: z.ZodOptional<z.ZodObject<{
+    registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+    owner: z.ZodOptional<z.ZodString>;
+    repository: z.ZodOptional<z.ZodString>;
+    asset: z.ZodOptional<z.ZodString>;
+    manifestPath: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  devDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  peerDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  kind: z.ZodLiteral<"project">;
+  uapkgVersion: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "PackageVersion", "out">>;
+  overrides: z.ZodOptional<z.ZodRecord<z.ZodString, 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">>;
+    path: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "InstallPath", "out">>;
+  }, z.core.$strip>]>, z.ZodTransform<Dependency, {
+    version: string & z.$brand<"VersionRange">;
+    registry?: (string & z.$brand<"RegistryName">) | undefined;
+    path?: (string & z.$brand<"InstallPath">) | undefined;
+  } | (string & z.$brand<"VersionRange">)>>>>;
+  postinstall: z.ZodOptional<z.ZodObject<{
+    modules: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>;
+  dev: z.ZodOptional<z.ZodObject<{
+    harness: z.ZodOptional<z.ZodUnknown>;
+  }, z.core.$strip>>;
+}, z.core.$loose>;
+type ProjectManifest = z.infer<typeof ProjectManifestSchema>;
+type ProjectPostinstall = z.infer<typeof ProjectPostinstallSchema>;
+//#endregion
+export { ProjectManifest, ProjectManifestSchema, ProjectPostinstall, ProjectPostinstallSchema };

package/dist/types/uapkg-package-manifest-schema/manifest/PublishSchema.d.ts

@@ -0,0 +1,15 @@
+import { z } from "zod";
+//#region src/manifest/PublishSchema.d.ts
+/**
+ * Optional publish configuration within `uapkg.json`.
+ */
+declare const PublishSchema: z.ZodObject<{
+  registry: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "RegistryName", "out">>;
+  owner: z.ZodOptional<z.ZodString>;
+  repository: z.ZodOptional<z.ZodString>;
+  asset: z.ZodOptional<z.ZodString>;
+  manifestPath: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Publish = z.infer<typeof PublishSchema>;
+//#endregion
+export { Publish, PublishSchema };

package/dist/types/uapkg-registry-core/contracts/RegistryCoreTypes.d.ts

@@ -0,0 +1,54 @@
+import { RegistryIdentifier, UnixTimestamp } from "../../uapkg-common-schema/index.js";
+//#region src/contracts/RegistryCoreTypes.d.ts
+interface RegistryDescriptor {
+  readonly type: 'git';
+  readonly url: string;
+  readonly ref: {
+    readonly type: 'branch' | 'tag' | 'rev';
+    readonly value: string;
+  };
+}
+type RegistryUpdateResult = 'Updated' | 'AlreadyFresh' | 'UpdatedRecently' | 'Failed';
+interface RegistryUpdateOptions {
+  /** Skip the TTL freshness check and force a sync. */
+  readonly bypassFreshnessCheck?: boolean;
+}
+interface RegistryAccessOptions {
+  /** Allow system Git and its configured credential helper to prompt. */
+  readonly interactive?: boolean;
+}
+interface RegistryMetadata {
+  readonly lastRegistrySyncAt: UnixTimestamp;
+  readonly registryIdentifier: RegistryIdentifier;
+}
+interface RegistryLockData {
+  readonly pid: number;
+  readonly startedAt: UnixTimestamp;
+  readonly heartbeat: UnixTimestamp;
+}
+interface SyncPolicyInput {
+  readonly lastSyncAt: UnixTimestamp | undefined;
+  readonly ttlSeconds: number;
+  readonly hasUpdatedWithinProcessLifetime: boolean;
+  readonly forced: boolean;
+}
+type SyncDecision = 'update' | 'skip';
+type RegistryInstantiationResult = 'Created' | 'AlreadyInstantiated' | 'Failed';
+interface RegistryCoreOptions {
+  /** Pass a `@uapkg/config` ConfigInstance to avoid re-reading config. */
+  readonly configInstance?: {
+    get(path?: string, options?: {
+      scope?: 'global' | 'local';
+    }): unknown;
+    getAll(): Record<string, unknown>;
+    getDefaultRegistry(): {
+      url: string;
+      ref: {
+        type: string;
+        value: string;
+      };
+    } | null;
+  };
+}
+//#endregion
+export { RegistryAccessOptions, RegistryCoreOptions, RegistryDescriptor, RegistryInstantiationResult, RegistryLockData, RegistryMetadata, RegistryUpdateOptions, RegistryUpdateResult, SyncDecision, SyncPolicyInput };

package/dist/types/uapkg-registry-core/core/RegistryCore.d.ts

@@ -0,0 +1,26 @@
+import { RegistryCoreOptions } from "../contracts/RegistryCoreTypes.js";
+import { Registry } from "../registry/Registry.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+//#region src/core/RegistryCore.d.ts
+/**
+ * Top-level entry point for the registry subsystem.
+ *
+ * Manages a process-level cache of `Registry` instances and resolves
+ * configured registry names into runtime `Registry` objects.
+ */
+declare class RegistryCore {
+  private static readonly registryPool;
+  private readonly registries;
+  private readonly config;
+  constructor(options?: RegistryCoreOptions);
+  /**
+   * Get or create a `Registry` for the given logical name.
+   *
+   * The name must exist as a key under `registries` in the resolved config.
+   */
+  getOrCreateRegistry(registryName: string): Result<Registry>;
+  /** Resolve a registry descriptor from config. */
+  private resolveDescriptor;
+}
+//#endregion
+export { RegistryCore };

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

@@ -0,0 +1,14 @@
+import { RegistryAccessOptions, RegistryCoreOptions, RegistryDescriptor, RegistryInstantiationResult, RegistryLockData, RegistryMetadata, RegistryUpdateOptions, RegistryUpdateResult, SyncDecision, SyncPolicyInput } from "./contracts/RegistryCoreTypes.js";
+import { ResolvedVersion, resolveVersion } from "./resolution/PackageResolver.js";
+import { Registry } from "./registry/Registry.js";
+import { RegistryCore } from "./core/RegistryCore.js";
+import { getRegistryCachePath, getRegistryLockPath, getRegistryMetadataPath, getRegistryPackagesPath, getRegistryRepoPath, getRegistryRoot } from "./paths/RegistryPaths.js";
+import { GitCommandRunner, GitInteractionMode, GitProcessSpawner, GitRunOptions, GitRunner } from "./registry/GitRunner.js";
+import { RegistryLock } from "./registry/RegistryLock.js";
+import { RegistryMetadataReader } from "./registry/RegistryMetadataReader.js";
+import { RegistryPackageReader } from "./registry/RegistryPackageReader.js";
+import { evaluateSyncPolicy } from "./registry/RegistrySyncPolicy.js";
+import { RegistryUpdater } from "./registry/RegistryUpdater.js";
+import { redactRegistryUrlSecrets, sanitizeRegistryUrlForDisplay } from "./registry/RegistryUrlSanitizer.js";
+import { SemverSelectionPolicy } from "./resolution/SemverSelectionPolicy.js";
+export { type GitCommandRunner, type GitInteractionMode, type GitProcessSpawner, type GitRunOptions, GitRunner, Registry, type RegistryAccessOptions, RegistryCore, type RegistryCoreOptions, type RegistryDescriptor, type RegistryInstantiationResult, RegistryLock, type RegistryLockData, type RegistryMetadata, RegistryMetadataReader, RegistryPackageReader, type RegistryUpdateOptions, type RegistryUpdateResult, RegistryUpdater, type ResolvedVersion, SemverSelectionPolicy, type SyncDecision, type SyncPolicyInput, evaluateSyncPolicy, getRegistryCachePath, getRegistryLockPath, getRegistryMetadataPath, getRegistryPackagesPath, getRegistryRepoPath, getRegistryRoot, redactRegistryUrlSecrets, resolveVersion, sanitizeRegistryUrlForDisplay };

package/dist/types/uapkg-registry-core/paths/RegistryPaths.d.ts

@@ -0,0 +1,15 @@
+//#region src/paths/RegistryPaths.d.ts
+/** Root of all registry caches in the profile selected by the CLI launcher. */
+declare function getRegistryRoot(): string;
+/** Cache root for a specific registry: `{profile-root}/registry/{shortId}` */
+declare function getRegistryCachePath(shortId: string): string;
+/** Path to the cloned registry repo. */
+declare function getRegistryRepoPath(shortId: string): string;
+/** Path reserved for future persistent package archive caching. */
+declare function getRegistryPackagesPath(shortId: string): string;
+/** Path to `registry.json` metadata file. */
+declare function getRegistryMetadataPath(shortId: string): string;
+/** Path to the lock file used during updates. */
+declare function getRegistryLockPath(shortId: string): string;
+//#endregion
+export { getRegistryCachePath, getRegistryLockPath, getRegistryMetadataPath, getRegistryPackagesPath, getRegistryRepoPath, getRegistryRoot };

package/dist/types/uapkg-registry-core/registry/GitRunner.d.ts

@@ -0,0 +1,31 @@
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { ChildProcess, SpawnOptions } from "node:child_process";
+//#region src/registry/GitRunner.d.ts
+type GitInteractionMode = 'non-interactive' | 'interactive';
+interface GitRunOptions {
+  readonly cwd?: string;
+  readonly interaction?: GitInteractionMode;
+  readonly timeoutMs?: number;
+}
+interface GitCommandRunner {
+  run(args: readonly string[], options?: GitRunOptions): Promise<Result<void>>;
+}
+type GitProcessSpawner = (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+/**
+ * Runs the configured system Git without ever handling Git credentials itself.
+ *
+ * Normal registry operations are deliberately non-interactive. An explicitly
+ * interactive access probe may hand stdin and stderr to Git so its configured
+ * credential helper or SSH agent can authenticate the user.
+ */
+declare class GitRunner implements GitCommandRunner {
+  private readonly gitBinary;
+  private readonly sensitiveValues;
+  private readonly spawnProcess;
+  constructor(gitBinary: string, sensitiveValues?: readonly string[], spawnProcess?: GitProcessSpawner);
+  run(args: readonly string[], options?: GitRunOptions): Promise<Result<void>>;
+  private failure;
+  private redact;
+}
+//#endregion
+export { GitCommandRunner, GitInteractionMode, GitProcessSpawner, GitRunOptions, GitRunner };

package/dist/types/uapkg-registry-core/registry/Registry.d.ts

@@ -0,0 +1,46 @@
+import { RegistryAccessOptions, RegistryDescriptor, RegistryUpdateOptions, RegistryUpdateResult } from "../contracts/RegistryCoreTypes.js";
+import { ResolvedVersion } from "../resolution/PackageResolver.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { PackageRegistryManifest } from "../../uapkg-registry-schema/index.js";
+import { RegistryIdentifier } from "../../uapkg-common-schema/index.js";
+//#region src/registry/Registry.d.ts
+/**
+ * Represents one configured local registry cache.
+ *
+ * Exposes registry-level operations: sync, read manifests, resolve versions.
+ */
+declare class Registry {
+  readonly id: RegistryIdentifier;
+  readonly descriptor: RegistryDescriptor;
+  readonly shortId: string;
+  private readonly aliases;
+  private hasUpdatedThisProcess;
+  private initPromise?;
+  private readonly metadataReader;
+  private readonly cacheValidator;
+  private readonly updater;
+  private readonly packageReader;
+  private ttlSeconds;
+  private constructor();
+  /** Factory — use this instead of `new`. */
+  static create(initialAlias: string, descriptor: RegistryDescriptor, id: RegistryIdentifier, shortId: string, gitBinary: string, ttlSeconds: number): Registry;
+  registerAlias(alias: string, ttlSeconds?: number): void;
+  /** Ensure the local cache is up-to-date. */
+  ensureUpToDate(options?: RegistryUpdateOptions & {
+    readonly logicalRegistryName?: string;
+  }): Promise<Result<RegistryUpdateResult>>;
+  /** Check whether system Git can read the configured remote without changing the cache. */
+  probeAccess(options?: RegistryAccessOptions): Promise<Result<void>>;
+  /** Read a package registry manifest from the local cache. */
+  getPackageManifest(packageName: string, logicalRegistryName?: string): Promise<Result<PackageRegistryManifest>>;
+  /** Resolve the best matching version for a package. */
+  resolvePackage(packageName: string, versionRange: string, registryName: string, current?: string): Promise<Result<ResolvedVersion>>;
+  private ensureReady;
+  private performUpdate;
+  private writeMetadata;
+  private toRegistryUnreachableDiagnostic;
+  private extractHttpStatus;
+  private resolveDiagnosticRegistryName;
+}
+//#endregion
+export { Registry };

package/dist/types/uapkg-registry-core/registry/RegistryCacheValidator.d.ts

@@ -0,0 +1,21 @@
+import { RegistryMetadataReader } from "./RegistryMetadataReader.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { RegistryIdentifier, UnixTimestamp } from "../../uapkg-common-schema/index.js";
+//#region src/registry/RegistryCacheValidator.d.ts
+interface RegistryCacheState {
+  readonly initialized: boolean;
+  readonly lastRegistrySyncAt?: UnixTimestamp;
+}
+/**
+ * Validates the relationship between a shortened cache directory, its cloned
+ * repository, and the full identity retained in registry.json.
+ */
+declare class RegistryCacheValidator {
+  private readonly shortId;
+  private readonly expectedIdentifier;
+  private readonly metadataReader;
+  constructor(shortId: string, expectedIdentifier: RegistryIdentifier, metadataReader: RegistryMetadataReader);
+  inspect(): Promise<Result<RegistryCacheState>>;
+}
+//#endregion
+export { RegistryCacheState, RegistryCacheValidator };

package/dist/types/uapkg-registry-core/registry/RegistryLock.d.ts

@@ -0,0 +1,27 @@
+import { Result } from "../../uapkg-diagnostics/index.js";
+//#region src/registry/RegistryLock.d.ts
+/**
+ * File-based lock for registry updates.
+ *
+ * - Acquire via exclusive create (`wx`).
+ * - Maintain heartbeat while owning.
+ * - Detect stale from heartbeat timeout.
+ * - Never delete another process's valid lock.
+ */
+declare class RegistryLock {
+  private readonly lockPath;
+  private heartbeatTimer;
+  constructor(lockPath: string);
+  /** Try to acquire the lock. Returns ok(true) if acquired. */
+  acquire(): Promise<Result<boolean>>;
+  /** Release the lock owned by this process. */
+  release(): Promise<Result<void>>;
+  private startHeartbeat;
+  private stopHeartbeat;
+  private updateHeartbeat;
+  private isStale;
+  private readLock;
+  private forceWrite;
+}
+//#endregion
+export { RegistryLock };

package/dist/types/uapkg-registry-core/registry/RegistryMetadataReader.d.ts

@@ -0,0 +1,18 @@
+import { RegistryMetadata } from "../contracts/RegistryCoreTypes.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+//#region src/registry/RegistryMetadataReader.d.ts
+/**
+ * Read and write `registry.json` metadata for a local registry cache.
+ */
+declare class RegistryMetadataReader {
+  private readonly shortId;
+  constructor(shortId: string);
+  /** Read registry.json from cache. */
+  read(): Promise<Result<RegistryMetadata>>;
+  /** Write updated registry.json to cache. */
+  write(metadata: RegistryMetadata): Promise<Result<void>>;
+  /** Check whether registry.json exists in cache. */
+  exists(): boolean;
+}
+//#endregion
+export { RegistryMetadataReader };

package/dist/types/uapkg-registry-core/registry/RegistryPackageReader.d.ts

@@ -0,0 +1,24 @@
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { PackageRegistryManifest } from "../../uapkg-registry-schema/index.js";
+//#region src/registry/RegistryPackageReader.d.ts
+/**
+ * Reads package manifests from the local cloned registry repo.
+ *
+ * Layout: `packages/{first-letter}/{package-name}.json` (unscoped) or
+ * `packages/@{scope}/{package-name}.json` (scoped).
+ */
+declare class RegistryPackageReader {
+  private readonly shortId;
+  constructor(shortId: string);
+  /** Read and validate a package registry manifest. */
+  readPackageManifest(packageName: string): Promise<Result<PackageRegistryManifest>>;
+  private resolveManifestPath;
+  /**
+   * Read the trusted context for registry-type-dependent package validation.
+   * Missing, invalid, and unsupported metadata all fail closed: registry type
+   * is required to select the correct package-record policy.
+   */
+  private readRegistryType;
+}
+//#endregion
+export { RegistryPackageReader };

package/dist/types/uapkg-registry-core/registry/RegistrySyncPolicy.d.ts

@@ -0,0 +1,14 @@
+import { SyncDecision, SyncPolicyInput } from "../contracts/RegistryCoreTypes.js";
+//#region src/registry/RegistrySyncPolicy.d.ts
+/**
+ * Determines whether a registry should be updated.
+ *
+ * Rules (evaluated in order):
+ *   1. If `forced`, always update.
+ *   2. If already updated within the current process lifetime, skip.
+ *   3. If last sync was within TTL window, skip.
+ *   4. Otherwise, update.
+ */
+declare function evaluateSyncPolicy(input: SyncPolicyInput): SyncDecision;
+//#endregion
+export { evaluateSyncPolicy };

package/dist/types/uapkg-registry-core/registry/RegistryUpdater.d.ts

@@ -0,0 +1,23 @@
+import { RegistryDescriptor } from "../contracts/RegistryCoreTypes.js";
+import { GitCommandRunner } from "./GitRunner.js";
+import { Result } from "../../uapkg-diagnostics/index.js";
+//#region src/registry/RegistryUpdater.d.ts
+/**
+ * Handles git clone and git fetch/pull for a single registry.
+ */
+declare class RegistryUpdater {
+  private readonly shortId;
+  private readonly descriptor;
+  private readonly runner;
+  constructor(shortId: string, descriptor: RegistryDescriptor, gitBinary: string, runner?: GitCommandRunner);
+  /** Clone or fetch the registry repo as needed. */
+  update(): Promise<Result<void>>;
+  /** Probe remote access without cloning or mutating the local registry cache. */
+  probeAccess(interactive?: boolean): Promise<Result<void>>;
+  private cloneRepo;
+  private fetchRepo;
+  private resolveRefSpec;
+  private runGit;
+}
+//#endregion
+export { RegistryUpdater };

package/dist/types/uapkg-registry-core/registry/RegistryUrlSanitizer.d.ts

@@ -0,0 +1,10 @@
+//#region src/registry/RegistryUrlSanitizer.d.ts
+/** Return a registry coordinate that is safe to include in diagnostics. */
+declare function sanitizeRegistryUrlForDisplay(registryUrl: string): string;
+/**
+ * Remove a registry URL and any HTTP credential/query/fragment material from
+ * arbitrary Git output before it enters a diagnostic.
+ */
+declare function redactRegistryUrlSecrets(value: string, registryUrl: string): string;
+//#endregion
+export { redactRegistryUrlSecrets, sanitizeRegistryUrlForDisplay };

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

@@ -0,0 +1,21 @@
+import { Result } from "../../uapkg-diagnostics/index.js";
+import { PackageRegistryManifest, RegistryVersion } from "../../uapkg-registry-schema/index.js";
+//#region src/resolution/PackageResolver.d.ts
+interface ResolvedVersion {
+  readonly version: string;
+  readonly entry: RegistryVersion;
+}
+/**
+ * Resolve the best version from a registry manifest that satisfies a range.
+ *
+ * Uses {@link SemverSelectionPolicy} so that:
+ *  - Stable ranges never auto-jump into prereleases.
+ *  - Users already on a prerelease escape to a satisfying stable version
+ *    as soon as one is published.
+ *
+ * @param current Optional currently-installed version, used to bias
+ *   escape-from-prerelease selection.
+ */
+declare function resolveVersion(manifest: PackageRegistryManifest, versionRange: string, registryName: string, current?: string): Result<ResolvedVersion>;
+//#endregion
+export { ResolvedVersion, resolveVersion };