@trebired/git-host 1.4.0 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `@trebired/git-host` will be documented here.
 
 This project follows semantic versioning once published.
 
+## 1.7.0
+
+- Added first-class host-managed source archives for branches, tags, commits, and forge releases through SHA-resolved `zipball` and `tarball` download routes backed by `git archive`.
+- Added streamed archive generation with deterministic commit-root folders, pluggable archive cache backends, filesystem cache support, TTL cleanup, structured archive error codes, and archive request/cache/generation audit logs.
+- Extended release and tag API/browser models with automatic source archive links that stay distinct from uploaded release assets.
+
+## 1.6.0
+
+- Made package styling optional instead of required for frontend integration by adding `unstyled` support across the shared repository UI provider and browser pages.
+- Added slot-based frontend skinning through `theme.classNames`, `theme.slots`, stable `data-slot` markers, and exported slot helpers so host apps can keep their own design system while reusing git-host structure.
+- Added render-state component overrides for loading, error, and empty states through `GitRepositoryUiProvider`.
+- Updated the README with explicit package structure plus app styling guidance and examples that do not depend on `@trebired/git-host/browser/styles.css`.
+
+## 1.5.0
+
+- Expanded the frontend ownership model across `@trebired/git-host/browser` and `@trebired/git-host/react` with a package-owned repository shell, route adapter system, diagnostics hooks, theme/token support, and shared UI provider state.
+- Added reusable React repository components and action primitives such as `GitRepositoryShell`, `GitRepositoryHeader`, `GitRepositoryTabs`, `GitCommitList`, `GitReleaseList`, `GitForkList`, `GitTreeView`, `GitBlobView`, `GitBranchSelector`, `GitTagSelector`, and repository action buttons.
+- Extended the browser entry to ship a broader first-class repository page surface including branches, tags, search, blame, compare, and richer release flows in addition to the existing overview/code/commits/releases/forks/activity pages.
+- Added query dedupe/caching plus frontend diagnostics hooks for fetch, action, render, empty-state, and navigation observation.
+- Updated the README with explicit frontend integration modes and thinner host-app examples.
+
 ## 1.4.0
 
 - Added a new forge layer through `createGitForge()` with host-owned storage adapters for releases, forks, stars, watching, and repository activity timelines.

package/README.md

@@ -104,9 +104,13 @@ const search = await gitHost.search("demo", {
 });
 const archive = await gitHost.readArchive("demo", {
   ref: "main",
-  format: "zip",
+  format: "tar.gz",
 });
-console.log(tags.length, blame.lines[0]?.author_name, search.match_count, archive.file_name);
+const archiveLinks = gitHost.resolveArchiveLinks("demo", {
+  basePath: "/api/git",
+  ref: "main",
+});
+console.log(tags.length, blame.lines[0]?.author_name, search.match_count, archive.file_name, archiveLinks.zip.href);
 
 const inspectionTarget = await gitHost.resolveInspectionTarget("demo", {
   ref: "auto",
@@ -306,42 +310,365 @@ GET /api/git/repositories/demo/linguist?ref=HEAD
 GET /api/git/repositories/demo/blame?ref=HEAD&path=src/app.ts
 GET /api/git/repositories/demo/search?ref=HEAD&path=src&query=value
 GET /api/git/repositories/demo/archive?ref=HEAD&format=zip
+GET /api/git/repositories/demo/archive?ref=HEAD&format=tar.gz
+GET /api/git/repositories/demo/zipball/main
+GET /api/git/repositories/demo/tarball/v1
 GET /api/git/repositories/demo/blob?ref=HEAD&path=README.md
 GET /api/git/repositories/demo/diff?baseRef=main&headRef=feature%2Fx&path=src
 ```
 
-React companion:
+## Source Archives
+
+git-host now exposes GitHub-style source archive downloads for branches, tags, commit SHAs, and forge releases.
+
+- `zipball/:ref` streams a `zip` archive.
+- `tarball/:ref` streams a `tar.gz` archive.
+- `readArchive()` still returns a base64 payload for JSON-first consumers.
+- `resolveArchiveLinks()` builds typed download URLs for branches, tags, releases, and commit SHAs.
+
+Archives are always generated from Git objects with `git archive`, never from the checked-out working tree.
+
+- Branch and tag downloads resolve to the current target commit first, then use a SHA-based cache key.
+- Commit SHA downloads are the stable choice when you need predictable contents.
+- The extracted root directory is commit-based, so the inner folder stays stable for a fixed commit even if the request came from a branch or tag name.
+- The outer archive bytes are streamed and cached, but git-host does not promise byte-for-byte identical compression output forever unless you choose to enforce that at the cache/backend layer.
+
+### Releases, Tags, and Assets
+
+A forge release is metadata attached to a Git tag. Its automatic source archives are not uploaded assets.
+
+- `release.assets` remains your uploaded files.
+- `release.source_archives.zip` and `release.source_archives.tar_gz` point at the automatic downloads for the tagged source.
+- Tag list/detail responses also expose `source_archives`.
+- If a release points at a missing tag, the forge API returns `release_tag_not_found`.
+
+### Cache Behavior
+
+The built-in archive service prefers on-demand generation plus cache.
+
+- Cache keys include repository id, resolved commit SHA, archive format, and the configured archive cache key version.
+- Moving a tag or branch to a different commit produces a new cache key automatically.
+- The default cache backend is filesystem-backed under the system temp directory.
+- You can inject your own `archive.cache` backend, including future object-storage implementations.
+- Cached entries carry TTL metadata and the filesystem backend performs periodic expired-entry cleanup.
+
+### Security Notes
+
+- Public repositories can expose `zipball` and `tarball` routes without auth.
+- Private repositories should authorize before archive generation just like any other read route.
+- The API handlers authorize archive downloads before they resolve refs or touch the cache.
+- Cache backends can optionally mint redirect URLs for object storage, but the default filesystem backend streams directly from git-host.
+
+## Frontend Integration
+
+The package now supports three frontend integration modes.
+
+### 1. Full Browser Pages
+
+Use `@trebired/git-host/browser` when you want git-host to own the whole repository area:
+
+- repository shell
+- tabs and navigation behavior
+- stats, actions, and social controls
+- loading, error, retry, and empty states
+- code browsing, blame, compare, releases, forks, activity, branches, tags, and search pages
+
+Host apps mostly provide:
+
+- auth
+- API base URL
+- repository key
+- route adapter
+- theme tokens
+- optional policy and diagnostics hooks
+
+Default styling is optional.
+
+- If you want the package look, import `@trebired/git-host/browser/styles.css`.
+- If you want package-owned structure with your own design system, skip that stylesheet and pass theme slots/classes.
 
 ```ts
-import { createGitApiClient, GitApiClientProvider, useGitLinguist, useGitRepositorySummary } from "@trebired/git-host/react";
+import {
+  GitRepositoryOverviewPage,
+  createGitRepositoryRouteAdapter,
+} from "@trebired/git-host/browser";
 
-const gitClient = createGitApiClient({
-  baseUrl: "/api/git",
+const routeAdapter = createGitRepositoryRouteAdapter({
+  repositoryBasePath: "/workspaces",
 });
 
-function RepositorySummaryCard() {
-  const summary = useGitRepositorySummary("demo");
-  const linguist = useGitLinguist("demo", { ref: "main" });
+function RepositoryScreen() {
+  return (
+    <GitRepositoryOverviewPage
+      baseUrl="/api/git"
+      repositoryKey="demo"
+      routeAdapter={routeAdapter}
+      branding={{
+        getCloneUrl(repositoryKey) {
+          return `https://git.example.com/${repositoryKey}.git`;
+        },
+      }}
+      unstyled
+      theme={{
+        classNames: {
+          page: "repo-page",
+          header: "repo-header",
+          title: "repo-title",
+          tabs: "repo-tabs",
+          "tab-link": "repo-tab",
+          card: "repo-card",
+          button: "repo-button",
+        },
+        slots: {
+          page: {
+            attributes: {
+              "data-repository-surface": "git-host",
+            },
+          },
+        },
+        variables: {
+          "--git-browser-accent": "#0a7f5a",
+        },
+      }}
+    />
+  );
+}
+```
+
+### 2. Hybrid Shell + Package Sections
 
-  if (summary.loading) return "Loading...";
-  if (summary.error) return summary.error.message;
-  if (!summary.data) return "Missing repository";
+Use `@trebired/git-host/react` when your app owns the outer chrome but git-host should own the repository section UI patterns:
 
-  return `${summary.data.repository.current_branch} @ ${summary.data.repository.head_short} (${Object.keys(linguist.data?.languages.results || {}).length} languages)`;
+```ts
+import {
+  GitApiClientProvider,
+  GitCommitList,
+  GitRepositoryShell,
+  GitRepositoryUiProvider,
+  createGitApiClient,
+  createGitRepositoryRouteAdapter,
+  useGitCommits,
+  useGitOverview,
+} from "@trebired/git-host/react";
+
+const client = createGitApiClient({ baseUrl: "/api/git" });
+const routes = createGitRepositoryRouteAdapter({
+  repositoryBasePath: "/app/repos",
+});
+
+function RepositoryCommitsSection({ repositoryKey }: { repositoryKey: string }) {
+  const overview = useGitOverview(repositoryKey);
+  const commits = useGitCommits(repositoryKey, {
+    ref: overview.data?.repository.repository.current_branch,
+  });
+
+  return (
+    <GitRepositoryShell
+      page="commits"
+      repositoryKey={repositoryKey}
+      loading={overview.loading || commits.loading}
+      error={overview.error || commits.error}
+      social={overview.data?.social}
+      stats={[
+        { label: "Branch", value: overview.data?.repository.repository.current_branch || "-" },
+        { label: "Forks", value: String(overview.data?.fork_count || 0) },
+      ]}
+    >
+      <GitCommitList commits={commits.data || []} repositoryKey={repositoryKey} />
+    </GitRepositoryShell>
+  );
 }
 
 function App() {
   return (
-    <GitApiClientProvider client={gitClient}>
-      <RepositorySummaryCard />
+    <GitApiClientProvider client={client}>
+      <GitRepositoryUiProvider
+        routeAdapter={routes}
+        theme={{
+          unstyled: true,
+          classNames: {
+            page: "repo-surface",
+            header: "repo-shell-header",
+            card: "repo-panel",
+            button: "repo-action",
+          },
+        }}
+      >
+        <RepositoryCommitsSection repositoryKey="demo" />
+      </GitRepositoryUiProvider>
     </GitApiClientProvider>
   );
 }
 ```
 
-For long-running repository scans, the typed client also exposes a live Socket.IO linguist stream:
+### 3. Fully Custom Layout
+
+Use the typed client, hooks, diagnostics, route adapter, and low-level models when you want full control over the page structure:
+
+```ts
+import {
+  GitApiClientProvider,
+  createGitApiClient,
+  useGitOverview,
+  useGitSearch,
+} from "@trebired/git-host/react";
+
+const client = createGitApiClient({ baseUrl: "/api/git" });
+
+function CustomRepositorySearch({ repositoryKey }: { repositoryKey: string }) {
+  const overview = useGitOverview(repositoryKey);
+  const search = useGitSearch(repositoryKey, {
+    query: "value",
+    ref: overview.data?.repository.repository.current_branch,
+  });
+
+  if (search.loading) return "Searching...";
+  if (search.error) return search.error.message;
+  return JSON.stringify(search.data?.files || []);
+}
+```
+
+## Frontend Surface
+
+`@trebired/git-host/browser` ships package-owned repository pages for:
+
+- overview
+- code/tree/blob
+- commits
+- commit detail
+- releases
+- release detail
+- forks
+- activity
+- blame
+- diff/compare
+- branches
+- tags
+- search
+
+`@trebired/git-host/react` now ships reusable repository primitives such as:
+
+- `GitRepositoryUiProvider`
+- `GitRepositoryShell`
+- `GitRepositoryHeader`
+- `GitRepositoryTabs`
+- `GitRepositoryStats`
+- `GitRepositoryActionBar`
+- `GitRepositorySocialButtons`
+- `GitCommitList`
+- `GitReleaseList`
+- `GitForkList`
+- `GitBranchList`
+- `GitTagList`
+- `GitTreeView`
+- `GitBlobView`
+- `GitBlameView`
+- `GitDiffView`
+- `GitSearchResults`
+- `GitBranchSelector`
+- `GitTagSelector`
+- `GitEmptyState`
+- `GitErrorState`
+- `GitLoadingState`
+
+### Styling And Skinning
+
+The package is designed around three frontend ownership levels:
+
+- full package UI: import `@trebired/git-host/browser/styles.css` and use the browser pages directly
+- package structure + app styling: skip the stylesheet and pass `theme.unstyled`, `theme.classNames`, and `theme.slots`
+- package logic + app rendering: use the typed hooks, mutations, diagnostics, and route adapter with fully custom host rendering
+
+The package now treats styling as optional rather than required:
+
+- no browser page requires `@trebired/git-host/browser/styles.css` to function
+- structural components expose stable `data-slot` markers for host CSS targeting
+- `GitRepositoryUiProvider` accepts `theme.classNames` and `theme.slots` for slot-level class and attribute overrides
+- `GitBrowserProvider` and browser pages accept `unstyled` as a shortcut for `theme.unstyled: true`
+- render-state components can be replaced through `components.LoadingState`, `components.ErrorState`, and `components.EmptyState`
+
+```ts
+import {
+  GitRepositoryUiProvider,
+  GitRepositoryShell,
+  GitCommitList,
+} from "@trebired/git-host/react";
+
+<GitRepositoryUiProvider
+  theme={{
+    unstyled: true,
+    classNames: {
+      page: "nativeRepoPage",
+      header: "nativeRepoHeader",
+      card: "nativeCard",
+      list: "nativeList",
+      "list-item": "nativeListItem",
+      button: "nativeButton",
+    },
+    slots: {
+      page: {
+        attributes: {
+          "data-app-surface": "repository",
+        },
+      },
+    },
+  }}
+  components={{
+    EmptyState({ title, message }) {
+      return <section className="nativeEmpty">{title}: {message}</section>;
+    },
+  }}
+>
+  <GitRepositoryShell page="commits" repositoryKey="demo">
+    <GitCommitList commits={commits} repositoryKey="demo" />
+  </GitRepositoryShell>
+</GitRepositoryUiProvider>;
+```
+
+### Route Adapter
+
+Both `browser` and `react` use a package-owned route adapter:
+
+```ts
+import { createGitRepositoryRouteAdapter } from "@trebired/git-host/react";
+
+const routes = createGitRepositoryRouteAdapter({
+  repositoryBasePath: "/repos",
+});
+
+routes.overview("demo");
+routes.code("demo", "src/app.ts", "main");
+routes.commit("demo", "abc123");
+routes.release("demo", "release-1");
+routes.compare("demo", "main", "feature/x");
+```
+
+### Diagnostics Hooks
+
+Repository UIs are brittle, so the package also exposes lifecycle diagnostics through `GitRepositoryUiProvider`:
+
+- `onNavigate`
+- `onViewMount`
+- `onFetchStart`
+- `onFetchSuccess`
+- `onFetchError`
+- `onActionStart`
+- `onActionSuccess`
+- `onActionError`
+- `onEmptyState`
+- `onRenderStateChange`
+
+### Initial Data
+
+Browser pages and hybrid sections can take a stable `initialData` shape through `GitRepositoryFrontEndInitialData`, so host apps do not need to invent per-page bootstrap payloads.
+
+For long-running repository scans, the typed client still exposes a live Socket.IO linguist stream:
 
 ```ts
+const gitClient = createGitApiClient({
+  baseUrl: "/api/git",
+});
+
 const socket = gitClient.openLinguistSocket("demo", {
   ref: "main",
   onProgress(event) {
@@ -355,18 +682,18 @@ const socket = gitClient.openLinguistSocket("demo", {
 await socket.completed;
 ```
 
-The React entry is intentionally headless. It helps apps fetch and mutate Git data consistently, but it does not ship a bundled styled UI.
-
 ## Current API
 
-The first public slice is intentionally small:
+The package now exposes three main frontend/backend layers:
 
 - `createGitHost()`
+- `createGitForge()`
 - `resolveRepositoryPath()`
 - `runGit()`
 - `buildGitEnv()`
 - `RepositoryLockManager`
 - `createGitApiHandler()`
+- `createGitForgeApiHandler()`
 - `createGitApiSocketServer()`
 - `createGitHttpHandler()`
 - `generateSshKeyPair()`
@@ -375,6 +702,7 @@ The first public slice is intentionally small:
 - `fingerprintSshPublicKey()`
 - `createGitSshServer()`
 - `@trebired/git-host/react`
+- `@trebired/git-host/browser`
 
 And the main host instance methods:
 
@@ -415,12 +743,16 @@ And the main host instance methods:
 - `push()`
 - `withRepositoryLock()`
 
-The React entry currently exports:
+The React entry now exports:
 
 - `createGitApiClient()`
 - `GitApiClientProvider`
+- `GitRepositoryUiProvider`
+- `createGitRepositoryRouteAdapter()`
 - `openLinguistSocket()` through the typed client instance
 - `useGitRepositorySummary()`
+- `useGitOverview()`
+- `useGitSocialState()`
 - `useGitBranches()`
 - `useGitCommits()`
 - `useGitCommit()`
@@ -434,6 +766,48 @@ The React entry currently exports:
 - `useGitBlob()`
 - `useGitDiff()`
 - `useGitApiQuery()`
+- `GitRepositoryShell`
+- `GitRepositoryHeader`
+- `GitRepositoryTabs`
+- `GitRepositoryStats`
+- `GitRepositoryActionBar`
+- `GitRepositorySocialButtons`
+- `GitCommitList`
+- `GitReleaseList`
+- `GitForkList`
+- `GitBranchList`
+- `GitTagList`
+- `GitTreeView`
+- `GitBlobView`
+- `GitBlameView`
+- `GitDiffView`
+- `GitSearchResults`
+- `GitBranchSelector`
+- `GitTagSelector`
+- `GitStarButton`
+- `GitWatchButton`
+- `GitForkButton`
+- `GitSyncForkButton`
+- `GitCreateReleaseButton`
+- `GitDeleteReleaseButton`
+- `GitCopyCloneUrlButton`
+- `GitDownloadArchiveButton`
+
+The browser entry exports full-page repository surfaces such as:
+
+- `GitRepositoryOverviewPage`
+- `GitRepositoryCodePage`
+- `GitRepositoryCommitsPage`
+- `GitRepositoryCommitPage`
+- `GitRepositoryReleasesPage`
+- `GitRepositoryReleasePage`
+- `GitRepositoryForksPage`
+- `GitRepositoryActivityPage`
+- `GitRepositoryBranchesPage`
+- `GitRepositoryTagsPage`
+- `GitRepositorySearchPage`
+- `GitRepositoryBlamePage`
+- `GitRepositoryComparePage`
 
 ## Repository Model
 
@@ -441,7 +815,7 @@ This package does not own your app database.
 
 Your app resolves a repository id to an absolute repository path. The package then runs Git operations against that path. This keeps repository metadata, permissions, tokens, SSH keys, and UI decisions inside the host app where they belong.
 
-The current public API is worktree-first because that keeps the reusable boundary compact and predictable.
+The repository runtime is still worktree-first, but the frontend surface is intentionally much broader now so host apps can stay thin.
 
 Private remotes are still host-owned. The package now helps with the transport plumbing by supporting:
 
@@ -462,10 +836,11 @@ Most alternatives fall into one of three buckets:
 Use it when you want:
 
 - your app to keep owning users, permissions, tokens, SSH keys, repository records, and UI
+- your app to keep owning users, permissions, tokens, SSH keys, repository records, branding, auth, and top-level route mounting while git-host owns most repository UI
 - real Git behavior from the system `git` binary
 - clone, fetch, pull, and push over smart HTTP and SSH
 - a reusable Git runtime instead of spreading Git shell calls all over your platform code
-- optional headless React helpers over the JSON API without coupling the core package to a UI framework
+- full browser-ready repository pages or reusable React repository primitives without rebuilding the same repository shell in every host app
 
 Do not use it when you want:
 
@@ -515,7 +890,7 @@ The host platform should still own:
 - permission checks and route authorization policy
 - access token issuance, revocation, and storage
 - SSH key ownership, private key storage, and known-host persistence
-- merge requests, reviews, UI flows, and other product-specific features
+- top-level product chrome, auth flows, branding decisions, and any product-specific features outside the repository area
 
 That boundary is where the package simplifies a platform the most without turning into a forge product of its own.
 

package/dist/api/forge/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/api/forge/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAIjE,OAAO,KAAK,EAAE,+BAA+B,EAAoC,MAAM,gBAAgB,CAAC;AAUxG,OAAO,EAAE,qBAAqB,EAAyB,MAAM,YAAY,CAAC;AA0P1E,iBAAS,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,IAarC,KAAK,eAAe,EAAE,KAAK,cAAc,UAK7E;AAED,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,CAAC"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../src/api/forge/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAKjE,OAAO,KAAK,EAAE,+BAA+B,EAAiF,MAAM,gBAAgB,CAAC;AAWrJ,OAAO,EAAE,qBAAqB,EAAyB,MAAM,YAAY,CAAC;AA4V1E,iBAAS,wBAAwB,CAAC,OAAO,EAAE,+BAA+B,IAarC,KAAK,eAAe,EAAE,KAAK,cAAc,UAK7E;AAED,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/api/forge/handler.js

@@ -1,6 +1,8 @@
 import { logPackageInitialized } from "@trebired/logger-adapter";
 import { resolveLogger } from "../../logging.js";
+import { GitHostError } from "../../errors.js";
 import { text } from "../../utils/text.js";
+import { enrichRepositoryDataWithArchives, isArchiveDownloadAction, writeArchiveDownload } from "../handler/archive.js";
 import { runGitApiAction } from "../handler/action.js";
 import { applyAuthorizationHeaders, authorizationAllowed, serializeError, statusForError, writeJson, } from "../handler/response.js";
 import { parseGitForgeApiRoute } from "./route.js";
@@ -131,6 +133,57 @@ async function runForgeAction(options, route, repositoryId, actor, body) {
             }, route, repositoryId, new URLSearchParams());
     }
 }
+async function attachReleaseSourceArchives(options, repositoryId, repositoryKey, release) {
+    try {
+        await options.gitHost.resolveArchive(repositoryId, {
+            format: "zip",
+            ref: release.tag_name,
+        });
+    }
+    catch (error) {
+        if (error instanceof GitHostError && error.code === "archive_ref_not_found") {
+            throw new GitHostError("release_tag_not_found", `Release "${release.id}" points at missing tag "${release.tag_name}" in repository "${repositoryId}".`, {
+                releaseId: release.id,
+                repositoryId,
+                tag: release.tag_name,
+            });
+        }
+        throw error;
+    }
+    return {
+        ...release,
+        source_archives: options.gitHost.resolveArchiveLinks(repositoryKey, {
+            basePath: options.basePath,
+            ref: release.tag_name,
+        }),
+    };
+}
+async function enrichForgeDataWithArchives(options, route, repositoryId, data) {
+    if (route.resource === "repository") {
+        return await enrichRepositoryDataWithArchives(options, route, data);
+    }
+    if (route.action === "release" && data && typeof data === "object") {
+        return await attachReleaseSourceArchives(options, repositoryId, route.repositoryKey, data);
+    }
+    if (route.action === "releases" && Array.isArray(data)) {
+        return await Promise.all(data.map(async (release) => {
+            return await attachReleaseSourceArchives(options, repositoryId, route.repositoryKey, release);
+        }));
+    }
+    if (route.action === "releases" && data && typeof data === "object") {
+        return await attachReleaseSourceArchives(options, repositoryId, route.repositoryKey, data);
+    }
+    if (route.action === "overview" && data && typeof data === "object") {
+        const overview = data;
+        return {
+            ...overview,
+            latest_release: overview.latest_release
+                ? await attachReleaseSourceArchives(options, repositoryId, route.repositoryKey, overview.latest_release)
+                : null,
+        };
+    }
+    return data;
+}
 async function handleGitForgeApiRequest(req, res, options) {
     const logger = resolveLogger(options.logger, options.loggerAdapter);
     const verbose = options.verbose === true;
@@ -191,6 +244,16 @@ async function handleGitForgeApiRequest(req, res, options) {
         : undefined);
     applyAuthorizationHeaders(res, auth.headers);
     if (!auth.allowed) {
+        if (isArchiveDownloadAction(route.action)) {
+            logger.warn(logGroup, "archive download denied", {
+                action: route.action,
+                method,
+                pathname: url.pathname,
+                repositoryId,
+                repositoryKey,
+                status: auth.status || 403,
+            });
+        }
         writeJson(req, res, auth.status || 403, {
             ok: false,
             error: {
@@ -207,11 +270,27 @@ async function handleGitForgeApiRequest(req, res, options) {
         body._method = method;
     }
     try {
-        const data = route.resource === "repository" && route.action !== "overview" && route.action !== "social" && route.action !== "activity"
+        if (isArchiveDownloadAction(route.action)) {
+            logger.info(logGroup, "archive download authorized", {
+                action: route.action,
+                method,
+                pathname: url.pathname,
+                repositoryId,
+                repositoryKey,
+            });
+            await writeArchiveDownload(req, res, options.gitHost, {
+                ref: "refName" in route ? route.refName : "HEAD",
+                repositoryId,
+                routeAction: route.action,
+            });
+            return;
+        }
+        const rawData = route.resource === "repository" && route.action !== "overview" && route.action !== "social" && route.action !== "activity"
             ? await runGitApiAction({
                 gitHost: options.gitHost,
             }, route, repositoryId, url.searchParams)
             : await runForgeAction(options, route, repositoryId, actor, body);
+        const data = await enrichForgeDataWithArchives(options, route, repositoryId, rawData);
         if (verbose) {
             logger.info(logGroup, "forge api action completed", {
                 action: route.action,