@trebired/git-host 1.3.0 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `@trebired/git-host` will be documented here.
 
 This project follows semantic versioning once published.
 
+## 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.
+- Added `createGitForgeApiHandler()` plus new repository routes for overview, social state, releases, forks, fork sync, and activity while keeping the existing read-only JSON API stable.
+- Extended the typed React client and hooks with forge reads and mutations, including optimistic star and watch helpers.
+- Added `@trebired/git-host/browser` with reusable SSR-safe repository pages and bundled browser styles for overview, code, commits, releases, forks, and activity views.
+- Added an in-memory forge storage adapter for tests, prototypes, and local embedding.
+
 ## 1.3.0
 
 - Added a first-class repository inspection layer with `resolveInspectionTarget()`, `readTree()`, `readDirectory()`, `readFile()`, and `readRepositoryAnalysis()`.

package/README.md

@@ -1,19 +1,19 @@
 # @trebired/git-host
 
-Embeddable Git host for Node.js and Bun apps with real Git CLI execution, smart HTTP and SSH transports, repository inspection APIs, and optional React helpers.
+Embeddable Git forge for Node.js and Bun apps with real Git CLI execution, smart HTTP and SSH transports, repository inspection APIs, forge features such as releases and forks, and optional React/browser companions.
 
-`@trebired/git-host` gives your app real Git repository operations and real Git transports without making you adopt a full forge product. It runs the real Git CLI, helps you resolve repository paths safely, serializes mutations per repository, and exposes a reusable API for repository initialization, summary reads, content inspection, branch operations, working-tree changes, remote sync helpers, JSON API handlers, and smart HTTP and SSH hosting.
+`@trebired/git-host` gives your app real Git repository operations, forge-style repository metadata, and real Git transports without forcing you into a monolithic hosted product. It runs the real Git CLI, helps you resolve repository paths safely, serializes mutations per repository, and exposes reusable APIs for repository initialization, summary reads, content inspection, branch operations, working-tree changes, releases, forks, stars, watching, activity feeds, JSON API handlers, browser-ready pages, and smart HTTP and SSH hosting.
 
 It is aimed at platforms and products that already own users, permissions, tokens, repository records, and UI, but want to stop hand-rolling the Git layer underneath all of that.
 
-The package keeps auth, permission, and persistence decisions host-owned while giving you reusable Git behavior and transport adapters.
+The package keeps auth, permission, and persistence decisions host-owned while giving you reusable Git behavior, forge adapters, and browser integration.
 
-It also exposes an optional React companion at `@trebired/git-host/react` for typed API clients, providers, and headless data hooks on top of the JSON API.
+It also exposes an optional React companion at `@trebired/git-host/react` for typed API clients, providers, and headless data hooks, plus an optional browser UI entry at `@trebired/git-host/browser` for full repository pages.
 
 In plain terms:
 
-- it is a Git hosting layer you embed into your app
-- it is not a full Git forge like GitLab, Gitea, or Forgejo
+- it is a Git hosting and lightweight forge layer you embed into your app
+- it is not a full hosted SaaS product with built-in accounts, billing, or platform ownership
 - it is not a reimplementation of Git
 - it uses the real `git` binary for the hard parts
 
@@ -35,6 +35,12 @@ Optional React companion:
 npm install react
 ```
 
+Optional browser pages:
+
+```sh
+npm install react
+```
+
 ```ts
 import { createGitHost, resolveRepositoryPath } from "@trebired/git-host";
 import { createLog } from "@trebired/logger";
@@ -304,38 +310,316 @@ 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:
+## 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) {
@@ -349,18 +633,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()`
@@ -369,6 +653,7 @@ The first public slice is intentionally small:
 - `fingerprintSshPublicKey()`
 - `createGitSshServer()`
 - `@trebired/git-host/react`
+- `@trebired/git-host/browser`
 
 And the main host instance methods:
 
@@ -409,12 +694,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()`
@@ -428,6 +717,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
 
@@ -435,7 +766,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:
 
@@ -456,10 +787,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:
 
@@ -509,7 +841,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

@@ -0,0 +1,6 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { CreateGitForgeApiHandlerOptions } from "../../types.js";
+import { parseGitForgeApiRoute } from "./route.js";
+declare function createGitForgeApiHandler(options: CreateGitForgeApiHandlerOptions): (req: IncomingMessage, res: ServerResponse) => void;
+export { createGitForgeApiHandler, parseGitForgeApiRoute };
+//# sourceMappingURL=handler.d.ts.map

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

@@ -0,0 +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"}