@appstrate/core 2.0.0 → 2.1.1

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "@appstrate/core",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "type": "module",
-  "files": ["src"],
+  "files": [
+    "src"
+  ],
   "exports": {
     "./logger": "./src/logger.ts",
     "./rate-limit": "./src/rate-limit.ts",
@@ -17,7 +19,10 @@
     "./semver": "./src/semver.ts",
     "./registry-deps": "./src/registry-deps.ts",
     "./update-check": "./src/update-check.ts",
-    "./publish-manifest": "./src/publish-manifest.ts"
+    "./publish-manifest": "./src/publish-manifest.ts",
+    "./dist-tags": "./src/dist-tags.ts",
+    "./version-policy": "./src/version-policy.ts",
+    "./download": "./src/download.ts"
   },
   "dependencies": {
     "fflate": "^0.8.0",

package/src/dist-tags.ts

@@ -0,0 +1,12 @@
+/** Regex for valid dist-tag names: lowercase alphanumeric, dots, hyphens, underscores. */
+export const DIST_TAG_REGEX = /^[a-z][a-z0-9._-]*$/;
+
+/** Check whether `tag` is a valid dist-tag name. */
+export function isValidDistTag(tag: string): boolean {
+  return DIST_TAG_REGEX.test(tag);
+}
+
+/** Check whether `tag` is a protected tag that cannot be manually set or removed. */
+export function isProtectedTag(tag: string): boolean {
+  return tag === "latest";
+}

package/src/download.ts

@@ -0,0 +1,54 @@
+import { computeIntegrity } from "./integrity.ts";
+
+// ─────────────────────────────────────────────
+// Integrity verification
+// ─────────────────────────────────────────────
+
+export interface IntegrityCheckResult {
+  valid: boolean;
+  computed: string;
+}
+
+/** Verify artifact integrity by computing SHA256 hash and comparing to expected value. */
+export function verifyArtifactIntegrity(
+  data: Uint8Array,
+  expectedIntegrity: string,
+): IntegrityCheckResult {
+  const computed = computeIntegrity(data);
+  return { valid: computed === expectedIntegrity, computed };
+}
+
+// ─────────────────────────────────────────────
+// Download filename
+// ─────────────────────────────────────────────
+
+/** Build a consistent download filename: scope-name-version.zip */
+export function buildDownloadFilename(scope: string, name: string, version: string): string {
+  const cleanScope = scope.replace(/^@/, "");
+  return `${cleanScope}-${name}-${version}.zip`;
+}
+
+// ─────────────────────────────────────────────
+// Download response headers
+// ─────────────────────────────────────────────
+
+export interface DownloadHeadersInput {
+  integrity: string;
+  yanked: boolean;
+  scope: string;
+  name: string;
+  version: string;
+}
+
+/** Build standard download response headers (Content-Type, Content-Disposition, X-Integrity, X-Yanked). */
+export function buildDownloadHeaders(meta: DownloadHeadersInput): Record<string, string> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/zip",
+    "X-Integrity": meta.integrity,
+    "Content-Disposition": `attachment; filename="${buildDownloadFilename(meta.scope, meta.name, meta.version)}"`,
+  };
+  if (meta.yanked) {
+    headers["X-Yanked"] = "true";
+  }
+  return headers;
+}

package/src/semver.ts

@@ -34,6 +34,11 @@ export function isPrerelease(v: string): boolean {
   return semver.prerelease(v) !== null;
 }
 
+/** Auto-bump the patch segment of `currentVersion`. Returns null if invalid semver. */
+export function bumpPatch(currentVersion: string): string | null {
+  return semver.inc(currentVersion, "patch");
+}
+
 /** Returns true if `remote` is a strictly newer version than `installed`.
  *  Returns false if either is null/undefined or invalid. */
 export function hasNewerVersion(
@@ -71,3 +76,51 @@ export function resolveLatestVersion(
 
   return versions.at(-1)?.version ?? null;
 }
+
+export interface CatalogVersion {
+  id: number;
+  version: string;
+  yanked: boolean;
+}
+
+/**
+ * Resolve a version query against a catalog of versions and dist-tags.
+ * 3-step resolution: exact match → dist-tag → semver range.
+ *
+ * - Exact match includes yanked versions (like npm/crates.io: exact pins always resolve).
+ * - Dist-tag lookup excludes yanked versions.
+ * - Semver range excludes yanked versions.
+ *
+ * Returns the version id, or null if no match.
+ */
+export function resolveVersionFromCatalog(
+  query: string,
+  versions: CatalogVersion[],
+  distTags: DistTagEntry[],
+): number | null {
+  // 1. Exact match — includes yanked
+  if (isValidVersion(query)) {
+    const exact = versions.find((v) => v.version === query);
+    if (exact) return exact.id;
+    return null;
+  }
+
+  // 2. Dist-tag — excludes yanked
+  const tagEntry = distTags.find((t) => t.tag === query);
+  if (tagEntry) {
+    const tagged = versions.find((v) => v.id === tagEntry.versionId && !v.yanked);
+    if (tagged) return tagged.id;
+  }
+
+  // 3. Semver range — excludes yanked
+  if (isValidRange(query)) {
+    const nonYanked = versions.filter((v) => !v.yanked);
+    const versionStrings = nonYanked.map((v) => v.version).filter(isValidVersion);
+    const best = matchVersion(versionStrings, query);
+    if (!best) return null;
+    const match = nonYanked.find((v) => v.version === best);
+    return match?.id ?? null;
+  }
+
+  return null;
+}

package/src/version-policy.ts

@@ -0,0 +1,66 @@
+import { isValidVersion, versionGt, compareVersionsDesc, isPrerelease } from "./semver.ts";
+
+export type ForwardVersionError = "VERSION_EXISTS" | "VERSION_NOT_HIGHER";
+
+export interface ForwardVersionResult {
+  ok: boolean;
+  error?: ForwardVersionError;
+  highest?: string;
+}
+
+/**
+ * Validate that `newVersion` is strictly higher than all existing versions.
+ * Callers must pass ALL versions (including yanked) to prevent re-publishing.
+ * Rejects duplicates and versions not higher than the current maximum.
+ */
+export function validateForwardVersion(
+  newVersion: string,
+  existingVersions: string[],
+): ForwardVersionResult {
+  if (existingVersions.includes(newVersion)) {
+    return { ok: false, error: "VERSION_EXISTS" };
+  }
+
+  const validVersions = existingVersions.filter(isValidVersion);
+  if (validVersions.length === 0) {
+    return { ok: true };
+  }
+
+  const highest = validVersions.sort(compareVersionsDesc)[0]!;
+  if (!versionGt(newVersion, highest)) {
+    return { ok: false, error: "VERSION_NOT_HIGHER", highest };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Find the best candidate for dist-tag reassignment after a yank:
+ * highest non-yanked, non-prerelease version.
+ */
+export function findBestStableVersion(
+  candidates: Array<{ id: number; version: string }>,
+): { id: number; version: string } | null {
+  const stable = candidates.filter((v) => !isPrerelease(v.version));
+  if (stable.length === 0) return null;
+
+  const sorted = stable.sort((a, b) => compareVersionsDesc(a.version, b.version));
+  return sorted[0]!;
+}
+
+/**
+ * Determine whether a newly published version should replace the "latest" dist-tag.
+ * Prereleases never update "latest". A stable version updates "latest" only if
+ * there is no current latest or the new version is >= the current one.
+ */
+export function shouldUpdateLatestTag(
+  newVersion: string,
+  currentLatestVersion: string | null,
+): boolean {
+  if (isPrerelease(newVersion)) return false;
+  if (!currentLatestVersion) return true;
+  return !versionGt(currentLatestVersion, newVersion);
+}
+
+// Re-export bumpPatch from semver.ts for backward compatibility
+export { bumpPatch } from "./semver.ts";