@goodfellow-cms/gitlab 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Goodfellow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @goodfellow-cms/gitlab
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Edit a Goodfellow site stored on GitLab, straight from the browser: sign-in with an access token, publishing as single commits, conflict checks and deploy status.
+
+```tsx
+import { gitlab } from "@goodfellow-cms/gitlab";
+
+export default defineConfig({ blocks, backend: gitlab({ project: "your-name/your-site" }) });
+```
+
+[Goodfellow](https://github.com/chartung17/goodfellow-cms) is a website builder for people who aren't developers, with no server or database: pages are files in your own GitHub or GitLab repository, edited in a visual editor built on [Puck](https://puckeditor.com). To start a new site, run `npm create goodfellow@latest my-site`. See the [documentation](https://chartung17.github.io/goodfellow-cms/) for everything else.
+
+More in the docs: [Hosts and business sites](https://chartung17.github.io/goodfellow-cms/docs/hosts).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,99 @@
+import { DeployStatus, FileChange, GitBackend, GitHost, GitUser, StorageLike, WriteOptions } from "@goodfellow-cms/core";
+//#region src/api.d.ts
+interface ApiOptions {
+  /** The API root, such as `https://gitlab.com/api/v4`. */
+  apiUrl: string;
+  /** Returns a current access token, refreshing it if needed. */
+  token: (options?: {
+    refresh?: boolean;
+  }) => Promise<string>;
+  /** Whether the token can be refreshed after a 401. */
+  canRefresh: boolean;
+  fetch: typeof fetch;
+}
+//#endregion
+//#region src/backend.d.ts
+interface GitLabBackendOptions {
+  api: ApiOptions;
+  project: string;
+  branch: string;
+  user: GitUser;
+  onSignOut: () => void;
+}
+/**
+ * The site's files on GitLab. Reads come from the commit `revision()` last
+ * returned. Saves are single commits; each changed file carries the commit it
+ * was last changed in, so GitLab refuses to overwrite anyone else's edits.
+ */
+export declare class GitLabBackend implements GitBackend {
+  readonly user: GitUser;
+  private readonly api;
+  private readonly project;
+  private readonly branch;
+  private readonly onSignOut;
+  private pinned?;
+  private readonly trees;
+  private readonly blobs;
+  constructor(options: GitLabBackendOptions);
+  private repo;
+  revision(): Promise<string>;
+  /** Every file in one folder at a commit, page by page. */
+  private listFolder;
+  /** Path → blob id for the editable files at a commit. Commits never change, so this is cached. */
+  private tree;
+  private currentTree;
+  read(path: string): Promise<string | undefined>;
+  readBytes(path: string): Promise<Uint8Array | undefined>;
+  list(dir: string): Promise<string[]>;
+  private lastCommitFor;
+  write(changes: FileChange[], { message, expectedRevision }: WriteOptions): Promise<{
+    revision: string;
+  }>;
+  changedPaths(from: string, to: string): Promise<string[]>;
+  /**
+   * Reads the commit's pipeline and external statuses (GitLab Pages jobs, or
+   * Vercel). Before any exist, the site counts as building if it has pipelines.
+   */
+  deployStatus(revision: string): Promise<DeployStatus>;
+  signOut(): void;
+}
+//#endregion
+//#region src/oauth.d.ts
+/** The admin panel's address, with a trailing slash so it always matches the redirect URI registered with GitLab. */
+export declare function redirectUri(href: string): string;
+//#endregion
+//#region src/index.d.ts
+/** The page's address and how to change it. Replaceable in tests. */
+export interface BrowserLocation {
+  href(): string;
+  /** Navigates away, for example to GitLab's sign-in page. */
+  assign(url: string): void;
+  /** Changes the address without reloading, for example to remove `?code=…` after signing in. */
+  replace(url: string): void;
+}
+export interface GitLabOptions {
+  /** The site's project path, such as `group/site` or `group/subgroup/site`. */
+  project: string;
+  /** The branch the live site is built from. Defaults to the project's default branch. */
+  branch?: string;
+  /** For self-managed GitLab. Defaults to `https://gitlab.com`. */
+  url?: string;
+  /**
+   * The Application ID of an OAuth application registered for the site (not
+   * confidential, scope `api`, redirect URI `https://your-site/admin/`). Enables
+   * one-click "Sign in with GitLab". Without it, people sign in with a token.
+   */
+  clientId?: string;
+  /** For tests. */
+  fetch?: typeof fetch;
+  /** For tests. */
+  storage?: {
+    local?: StorageLike;
+    session?: StorageLike;
+  };
+  /** For tests. */
+  location?: BrowserLocation;
+}
+/** Sign-in and storage for a site whose repository is on GitLab. */
+export declare function gitlab(options: GitLabOptions): GitHost;
+//#endregion

package/dist/index.js

@@ -0,0 +1,381 @@
+import { ConflictError, EDITABLE_FOLDERS, GitApiError, SignInError, credentialStorage, encodeBase64Bytes } from "@goodfellow-cms/core";
+//#region src/api.ts
+/** Calls the GitLab API. A 401 refreshes the token once; after that it means the sign-in has expired. */
+async function gitlabRequest(api, path, init = {}) {
+	const send = async (refresh) => api.fetch(`${api.apiUrl}${path}`, {
+		method: init.method ?? "GET",
+		headers: {
+			authorization: `Bearer ${await api.token({ refresh })}`,
+			...init.body !== void 0 && { "content-type": "application/json" }
+		},
+		body: init.body === void 0 ? void 0 : JSON.stringify(init.body),
+		cache: "no-store"
+	});
+	let response = await send(false);
+	if (response.status === 401 && api.canRefresh) response = await send(true);
+	if (response.status === 401) throw new SignInError("invalid", "GitLab didn't accept the sign-in. It may have expired.");
+	if (!response.ok && !init.allow?.includes(response.status)) {
+		const body = await response.json().catch(() => ({}));
+		const message = typeof body.message === "string" ? body.message : JSON.stringify(body.message ?? body.error ?? "");
+		throw new GitApiError(response.status, `GitLab answered ${response.status}: ${message || response.statusText}`);
+	}
+	return response;
+}
+async function gitlabJson(api, path, init) {
+	return await (await gitlabRequest(api, path, init)).json();
+}
+//#endregion
+//#region src/backend.ts
+const PAGE_SIZE = 100;
+/**
+* The site's files on GitLab. Reads come from the commit `revision()` last
+* returned. Saves are single commits; each changed file carries the commit it
+* was last changed in, so GitLab refuses to overwrite anyone else's edits.
+*/
+var GitLabBackend = class {
+	user;
+	api;
+	project;
+	branch;
+	onSignOut;
+	pinned;
+	trees = /* @__PURE__ */ new Map();
+	blobs = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.api = options.api;
+		this.project = encodeURIComponent(options.project);
+		this.branch = options.branch;
+		this.user = options.user;
+		this.onSignOut = options.onSignOut;
+	}
+	repo(path) {
+		return `/projects/${this.project}/repository${path}`;
+	}
+	async revision() {
+		const branch = await gitlabJson(this.api, this.repo(`/branches/${encodeURIComponent(this.branch)}`));
+		this.pinned = branch.commit.id;
+		return this.pinned;
+	}
+	/** Every file in one folder at a commit, page by page. */
+	async listFolder(sha, dir) {
+		const files = [];
+		for (let page = 1;; page++) {
+			const query = new URLSearchParams({
+				ref: sha,
+				path: dir,
+				recursive: "true",
+				per_page: String(PAGE_SIZE),
+				page: String(page)
+			});
+			const response = await gitlabRequest(this.api, this.repo(`/tree?${query}`), { allow: [404] });
+			if (response.status === 404) return files;
+			const entries = await response.json();
+			for (const entry of entries) if (entry.type === "blob") files.push([entry.path, entry.id]);
+			if (entries.length < PAGE_SIZE) return files;
+		}
+	}
+	/** Path → blob id for the editable files at a commit. Commits never change, so this is cached. */
+	tree(sha) {
+		let tree = this.trees.get(sha);
+		if (!tree) {
+			tree = Promise.all(EDITABLE_FOLDERS.map((folder) => this.listFolder(sha, folder))).then((folders) => new Map(folders.flat()));
+			tree.catch(() => this.trees.delete(sha));
+			this.trees.set(sha, tree);
+		}
+		return tree;
+	}
+	async currentTree() {
+		return this.tree(this.pinned ?? await this.revision());
+	}
+	async read(path) {
+		const sha = (await this.currentTree()).get(path);
+		if (!sha) return void 0;
+		let blob = this.blobs.get(sha);
+		if (!blob) {
+			blob = gitlabRequest(this.api, this.repo(`/blobs/${sha}/raw`)).then((response) => response.text());
+			blob.catch(() => this.blobs.delete(sha));
+			this.blobs.set(sha, blob);
+		}
+		return blob;
+	}
+	async readBytes(path) {
+		const sha = (await this.currentTree()).get(path);
+		if (!sha) return void 0;
+		const response = await gitlabRequest(this.api, this.repo(`/blobs/${sha}/raw`));
+		return new Uint8Array(await response.arrayBuffer());
+	}
+	async list(dir) {
+		const prefix = `${dir}/`;
+		return [...(await this.currentTree()).keys()].filter((path) => path.startsWith(prefix)).sort();
+	}
+	async lastCommitFor(path, ref) {
+		return (await gitlabJson(this.api, this.repo(`/files/${encodeURIComponent(path)}?ref=${ref}`))).last_commit_id;
+	}
+	async write(changes, { message, expectedRevision }) {
+		if (await this.revision() !== expectedRevision) throw new ConflictError();
+		const existing = await this.tree(expectedRevision);
+		const toApply = (await Promise.all(changes.map(async (change) => {
+			const exists = existing.has(change.path);
+			if ("delete" in change) return exists ? {
+				action: "delete",
+				file_path: change.path,
+				last_commit_id: await this.lastCommitFor(change.path, expectedRevision)
+			} : void 0;
+			const content = "bytes" in change ? {
+				content: encodeBase64Bytes(change.bytes),
+				encoding: "base64"
+			} : { content: change.content };
+			return exists ? {
+				action: "update",
+				file_path: change.path,
+				...content,
+				last_commit_id: await this.lastCommitFor(change.path, expectedRevision)
+			} : {
+				action: "create",
+				file_path: change.path,
+				...content
+			};
+		}))).filter((action) => action !== void 0);
+		if (toApply.length === 0) return { revision: expectedRevision };
+		try {
+			const commit = await gitlabJson(this.api, this.repo("/commits"), {
+				method: "POST",
+				body: {
+					branch: this.branch,
+					commit_message: message,
+					actions: toApply
+				}
+			});
+			this.pinned = commit.id;
+			return { revision: commit.id };
+		} catch (error) {
+			if (!(error instanceof GitApiError)) throw error;
+			if (error.status === 403) throw new SignInError("cant-publish", "This GitLab account can't publish to the site.");
+			if (error.status === 400 && /already exists|changed since/i.test(error.message) || await this.revision() !== expectedRevision) throw new ConflictError();
+			throw error;
+		}
+	}
+	async changedPaths(from, to) {
+		const comparison = await gitlabJson(this.api, this.repo(`/compare?${new URLSearchParams({
+			from,
+			to,
+			straight: "true"
+		})}`));
+		return [...new Set((comparison.diffs ?? []).flatMap((diff) => [diff.old_path, diff.new_path]))];
+	}
+	/**
+	* Reads the commit's pipeline and external statuses (GitLab Pages jobs, or
+	* Vercel). Before any exist, the site counts as building if it has pipelines.
+	*/
+	async deployStatus(revision) {
+		try {
+			const statuses = await gitlabJson(this.api, this.repo(`/commits/${revision}/statuses`));
+			if (statuses.length === 0) return { state: (await gitlabJson(this.api, `/projects/${this.project}/pipelines?per_page=1`)).length > 0 ? "building" : "unknown" };
+			const failed = statuses.find((status) => status.status === "failed" || status.status === "canceled");
+			if (failed) return {
+				state: "failed",
+				detailsUrl: failed.target_url ?? void 0
+			};
+			if (statuses.every((status) => status.status === "success" || status.status === "skipped")) return {
+				state: "live",
+				detailsUrl: statuses[0]?.target_url ?? void 0
+			};
+			return {
+				state: "building",
+				detailsUrl: statuses[0]?.target_url ?? void 0
+			};
+		} catch (error) {
+			if (error instanceof GitApiError) return { state: "unknown" };
+			throw error;
+		}
+	}
+	signOut() {
+		this.onSignOut();
+	}
+};
+//#endregion
+//#region src/oauth.ts
+/** OAuth 2.0 with PKCE: lets the browser sign in to GitLab without any server or client secret. */
+function base64Url(bytes) {
+	let binary = "";
+	for (const byte of bytes) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function randomString(bytes = 32) {
+	return base64Url(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+async function codeChallenge(verifier) {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+	return base64Url(new Uint8Array(digest));
+}
+function toTokens(response, verifier, now = Date.now()) {
+	return {
+		type: "oauth",
+		access: response.access_token,
+		refresh: response.refresh_token,
+		expiresAt: now + (response.expires_in ?? 7200) * 1e3,
+		verifier
+	};
+}
+/** The admin panel's address, with a trailing slash so it always matches the redirect URI registered with GitLab. */
+function redirectUri(href) {
+	const url = new URL(href);
+	return `${url.origin}${url.pathname.replace(/\/?$/, "/")}`;
+}
+//#endregion
+//#region src/index.ts
+const MIN_ACCESS_LEVEL_TO_PUBLISH = 30;
+function browserLocation() {
+	return {
+		href: () => window.location.href,
+		assign: (url) => window.location.assign(url),
+		replace: (url) => window.history.replaceState(window.history.state, "", url)
+	};
+}
+/** Sign-in and storage for a site whose repository is on GitLab. */
+function gitlab(options) {
+	const webUrl = (options.url ?? "https://gitlab.com").replace(/\/$/, "");
+	const apiUrl = `${webUrl}/api/v4`;
+	const fetcher = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+	const storage = credentialStorage(`goodfellow:gitlab:${webUrl}:${options.project}`, options.storage);
+	const pending = credentialStorage(`goodfellow:gitlab:pending:${options.project}`, options.storage);
+	const location = () => options.location ?? browserLocation();
+	async function requestTokens(params) {
+		const response = await fetcher(`${webUrl}/oauth/token`, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams(params)
+		});
+		if (!response.ok) throw new SignInError("invalid", `GitLab didn't accept the sign-in (${response.status}).`);
+		return await response.json();
+	}
+	async function connect(initial, remember) {
+		let credentials = initial;
+		const token = async ({ refresh } = {}) => {
+			if (credentials.type === "token") return credentials.token;
+			if (refresh || credentials.expiresAt - 6e4 < Date.now()) {
+				const { verifier } = credentials;
+				credentials = toTokens(await requestTokens({
+					client_id: options.clientId ?? "",
+					refresh_token: credentials.refresh,
+					grant_type: "refresh_token",
+					redirect_uri: redirectUri(location().href()),
+					code_verifier: verifier
+				}), verifier);
+				storage.save(JSON.stringify(credentials), remember);
+			}
+			return credentials.access;
+		};
+		const api = {
+			apiUrl,
+			token,
+			canRefresh: credentials.type === "oauth",
+			fetch: fetcher
+		};
+		const user = await gitlabJson(api, "/user");
+		let project;
+		try {
+			project = await gitlabJson(api, `/projects/${encodeURIComponent(options.project)}`);
+		} catch (error) {
+			if (error instanceof GitApiError && (error.status === 404 || error.status === 403)) throw new SignInError("no-access", `The GitLab account ${user.username} can't see ${options.project}.`);
+			throw error;
+		}
+		if (Math.max(project.permissions?.project_access?.access_level ?? 0, project.permissions?.group_access?.access_level ?? 0) < MIN_ACCESS_LEVEL_TO_PUBLISH) throw new SignInError("cant-publish", `The GitLab account ${user.username} can see ${options.project} but can't publish to it.`);
+		storage.save(JSON.stringify(credentials), remember);
+		return new GitLabBackend({
+			api,
+			project: options.project,
+			branch: options.branch ?? project.default_branch,
+			user: {
+				login: user.username,
+				name: user.name,
+				avatarUrl: user.avatar_url
+			},
+			onSignOut: () => storage.clear()
+		});
+	}
+	/** Finishes a redirect sign-in if the page has just come back from GitLab. */
+	async function completeRedirect() {
+		const url = new URL(location().href());
+		const code = url.searchParams.get("code");
+		const returnedState = url.searchParams.get("state");
+		const error = url.searchParams.get("error");
+		if (!code && !error) return null;
+		const saved = pending.load();
+		if (!saved) return null;
+		pending.clear();
+		const redirect = JSON.parse(saved);
+		for (const key of [
+			"code",
+			"state",
+			"error",
+			"error_description"
+		]) url.searchParams.delete(key);
+		url.hash = redirect.hash;
+		location().replace(url.toString());
+		if (error || !code || returnedState !== redirect.state) throw new SignInError("redirect-failed", "Signing in with GitLab was cancelled or didn't finish.");
+		return connect(toTokens(await requestTokens({
+			client_id: options.clientId ?? "",
+			code,
+			grant_type: "authorization_code",
+			redirect_uri: redirectUri(url.toString()),
+			code_verifier: redirect.verifier
+		}), redirect.verifier), redirect.remember);
+	}
+	return {
+		name: "GitLab",
+		canRedirect: Boolean(options.clientId),
+		tokenLinks: [{
+			url: `${webUrl}/-/user_settings/personal_access_tokens?${new URLSearchParams({
+				name: "Goodfellow admin",
+				scopes: "api"
+			})}`,
+			label: "signIn.token.create"
+		}],
+		async restore() {
+			const redirected = await completeRedirect();
+			if (redirected) return redirected;
+			const saved = storage.load();
+			if (!saved) return null;
+			try {
+				return await connect(JSON.parse(saved), storage.remembered());
+			} catch (error) {
+				if (error instanceof SignInError) storage.clear();
+				throw error;
+			}
+		},
+		async signInWithToken(token, remember) {
+			const trimmed = token.trim();
+			if (!trimmed) throw new SignInError("invalid", "Paste a token to sign in.");
+			return connect({
+				type: "token",
+				token: trimmed
+			}, remember);
+		},
+		async startRedirect(remember) {
+			if (!options.clientId) throw new Error("gitlab({ clientId }) is needed to sign in with GitLab.");
+			const verifier = randomString(48);
+			const state = randomString(16);
+			const here = new URL(location().href());
+			const redirect = {
+				state,
+				verifier,
+				remember,
+				hash: here.hash
+			};
+			pending.save(JSON.stringify(redirect), false);
+			const query = new URLSearchParams({
+				client_id: options.clientId,
+				redirect_uri: redirectUri(here.toString()),
+				response_type: "code",
+				state,
+				scope: "api",
+				code_challenge: await codeChallenge(verifier),
+				code_challenge_method: "S256"
+			});
+			location().assign(`${webUrl}/oauth/authorize?${query}`);
+		}
+	};
+}
+//#endregion
+export { GitLabBackend, gitlab, redirectUri };

package/dist/testing.d.ts

@@ -0,0 +1,34 @@
+import { FileChange } from "@goodfellow-cms/core";
+import { FakeRepo } from "@goodfellow-cms/core/testing";
+//#region src/testing.d.ts
+export interface FakeGitLabUser {
+  username: string;
+  name?: string;
+  /** GitLab access level: 30 is Developer, 40 Maintainer. Defaults to 40. */
+  accessLevel?: number;
+}
+export interface FakeGitLabOptions {
+  project: string;
+  url?: string;
+  files?: Record<string, string>;
+  /** Personal access tokens and their users. */
+  tokens?: Record<string, FakeGitLabUser>;
+  /** The OAuth application's ID, and the user who signs in through it. */
+  oauth?: {
+    clientId: string;
+    user: FakeGitLabUser;
+    expiresIn?: number;
+  };
+  /** Simulates a GitLab Pages pipeline that succeeds after being checked this many times. Off by default. */
+  deployAfterChecks?: number;
+}
+export declare function fakeGitLab(options: FakeGitLabOptions): {
+  repo: FakeRepo;
+  requests: Request[];
+  commit: (changes: FileChange[], message: string) => string;
+  authorize: (authorizeUrl: string) => string;
+  handle: (request: Request) => Promise<Response>;
+  fetch: typeof fetch;
+};
+export type FakeGitLab = ReturnType<typeof fakeGitLab>;
+//#endregion

package/dist/testing.js

@@ -0,0 +1,200 @@
+import { decodeBase64 } from "@goodfellow-cms/core";
+import { FakeRepo, fakeFileBytes } from "@goodfellow-cms/core/testing";
+//#region src/testing.ts
+/**
+* A fake of the parts of GitLab's API that `@goodfellow-cms/gitlab` uses, backed by
+* an in-memory repository, including OAuth with PKCE. For tests only.
+*/
+function json(body, status = 200) {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { "content-type": "application/json" }
+	});
+}
+async function sha256Base64Url(text) {
+	const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text)));
+	let binary = "";
+	for (const byte of digest) binary += String.fromCharCode(byte);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fakeGitLab(options) {
+	const webUrl = options.url ?? "https://gitlab.com";
+	const repo = new FakeRepo(options.files);
+	const tokens = new Map(Object.entries(options.tokens ?? { "test-token": {
+		username: "editor",
+		name: "Test Editor"
+	} }));
+	const codes = /* @__PURE__ */ new Map();
+	const refreshTokens = /* @__PURE__ */ new Map();
+	const pipelines = /* @__PURE__ */ new Map();
+	const requests = [];
+	let counter = 0;
+	function commit(changes, message) {
+		const sha = repo.commit(changes, message);
+		if (options.deployAfterChecks !== void 0) pipelines.set(sha, { checks: 0 });
+		return sha;
+	}
+	function issueTokens(user) {
+		counter += 1;
+		const access = `oauth-access-${counter}`;
+		const refresh = `oauth-refresh-${counter}`;
+		tokens.set(access, user);
+		refreshTokens.set(refresh, user);
+		return {
+			access_token: access,
+			refresh_token: refresh,
+			expires_in: options.oauth?.expiresIn ?? 7200,
+			token_type: "Bearer"
+		};
+	}
+	/**
+	* What GitLab's sign-in page does once the person approves: returns the
+	* address the browser is sent back to, with a one-time code.
+	*/
+	function authorize(authorizeUrl) {
+		const params = new URL(authorizeUrl).searchParams;
+		if (params.get("client_id") !== options.oauth?.clientId) throw new Error("Unknown OAuth application");
+		if (params.get("code_challenge_method") !== "S256") throw new Error("PKCE with S256 is required");
+		counter += 1;
+		const code = `code-${counter}`;
+		codes.set(code, {
+			challenge: params.get("code_challenge") ?? "",
+			redirectUri: params.get("redirect_uri") ?? ""
+		});
+		const back = new URL(params.get("redirect_uri") ?? "");
+		back.searchParams.set("code", code);
+		back.searchParams.set("state", params.get("state") ?? "");
+		return back.toString();
+	}
+	async function handle(request) {
+		requests.push(request.clone());
+		const url = new URL(request.url);
+		if (url.pathname === "/oauth/token" && request.method === "POST") {
+			const body = new URLSearchParams(await request.text());
+			if (body.get("client_id") !== options.oauth?.clientId || !options.oauth) return json({ error: "invalid_client" }, 401);
+			if (body.get("grant_type") === "authorization_code") {
+				const issued = codes.get(body.get("code") ?? "");
+				codes.delete(body.get("code") ?? "");
+				if (!issued || issued.redirectUri !== body.get("redirect_uri")) return json({ error: "invalid_grant" }, 400);
+				if (await sha256Base64Url(body.get("code_verifier") ?? "") !== issued.challenge) return json({
+					error: "invalid_grant",
+					error_description: "PKCE verification failed"
+				}, 400);
+				return json(issueTokens(options.oauth.user));
+			}
+			if (body.get("grant_type") === "refresh_token") {
+				const user = refreshTokens.get(body.get("refresh_token") ?? "");
+				refreshTokens.delete(body.get("refresh_token") ?? "");
+				return user ? json(issueTokens(user)) : json({ error: "invalid_grant" }, 400);
+			}
+			return json({ error: "unsupported_grant_type" }, 400);
+		}
+		if (!url.pathname.startsWith("/api/v4/")) return json({ message: "404 Not Found" }, 404);
+		const user = tokens.get(request.headers.get("authorization")?.replace(/^Bearer /, "") ?? "");
+		if (!user) return json({ message: "401 Unauthorized" }, 401);
+		const path = url.pathname.slice(7);
+		if (path === "/user") return json({
+			username: user.username,
+			name: user.name,
+			avatar_url: `https://avatars.example/${user.username}`
+		});
+		const projectMatch = path.match(/^\/projects\/([^/]+)(\/.*)?$/);
+		if (!projectMatch || decodeURIComponent(projectMatch[1] ?? "") !== options.project) return json({ message: "404 Project Not Found" }, 404);
+		const rest = projectMatch[2] ?? "";
+		const accessLevel = user.accessLevel ?? 40;
+		if (rest === "") return json({
+			default_branch: repo.defaultBranch,
+			permissions: {
+				project_access: { access_level: accessLevel },
+				group_access: null
+			}
+		});
+		const branch = rest.match(/^\/repository\/branches\/(.+)$/);
+		if (branch) {
+			const sha = repo.branches.get(decodeURIComponent(branch[1] ?? ""));
+			return sha ? json({ commit: { id: sha } }) : json({ message: "404 Branch Not Found" }, 404);
+		}
+		if (rest === "/repository/tree") {
+			const ref = url.searchParams.get("ref") ?? repo.defaultBranch;
+			const dir = url.searchParams.get("path") ?? "";
+			const perPage = Number(url.searchParams.get("per_page") ?? 20);
+			const page = Number(url.searchParams.get("page") ?? 1);
+			const entries = [...repo.files(ref)].filter(([file]) => file.startsWith(`${dir}/`)).map(([file, content]) => ({
+				id: repo.blobSha(content),
+				type: "blob",
+				path: file,
+				name: file.split("/").at(-1)
+			}));
+			if (entries.length === 0) return json({ message: "404 Tree Not Found" }, 404);
+			return json(entries.slice((page - 1) * perPage, page * perPage));
+		}
+		const blob = rest.match(/^\/repository\/blobs\/([0-9a-f]{40})\/raw$/);
+		if (blob) {
+			const content = repo.blobs.get(blob[1] ?? "");
+			return content === void 0 ? json({ message: "404 Blob Not Found" }, 404) : new Response(fakeFileBytes(content));
+		}
+		const file = rest.match(/^\/repository\/files\/([^/]+)$/);
+		if (file) {
+			const filePath = decodeURIComponent(file[1] ?? "");
+			const ref = url.searchParams.get("ref") ?? repo.defaultBranch;
+			const lastCommit = repo.files(ref).has(filePath) ? repo.lastCommitFor(filePath, ref) : void 0;
+			return lastCommit ? json({
+				file_path: filePath,
+				last_commit_id: lastCommit
+			}) : json({ message: "404 File Not Found" }, 404);
+		}
+		if (rest === "/repository/commits" && request.method === "POST") {
+			if (accessLevel < 30) return json({ message: "403 Forbidden" }, 403);
+			const body = await request.json();
+			const files = repo.files(body.branch);
+			for (const action of body.actions) {
+				if (action.action === "create" && files.has(action.file_path)) return json({ message: "A file with this name already exists" }, 400);
+				if ((action.action === "update" || action.action === "delete") && !files.has(action.file_path)) return json({ message: "A file with this name doesn't exist" }, 400);
+				if (action.last_commit_id && repo.lastCommitFor(action.file_path, body.branch) !== action.last_commit_id) return json({ message: "You are attempting to update a file that has changed since you started editing it." }, 400);
+			}
+			return json({
+				id: commit(body.actions.map((action) => action.action === "delete" ? {
+					path: action.file_path,
+					delete: true
+				} : action.encoding === "base64" ? {
+					path: action.file_path,
+					bytes: decodeBase64(action.content ?? "")
+				} : {
+					path: action.file_path,
+					content: action.content ?? ""
+				}), body.commit_message),
+				message: body.commit_message
+			}, 201);
+		}
+		if (rest === "/repository/compare") return json({ diffs: repo.changedPaths(url.searchParams.get("from") ?? "", url.searchParams.get("to") ?? "").map((changedPath) => ({
+			old_path: changedPath,
+			new_path: changedPath
+		})) });
+		const statuses = rest.match(/^\/repository\/commits\/([0-9a-f]{40})\/statuses$/);
+		if (statuses) {
+			const pipeline = pipelines.get(statuses[1] ?? "");
+			if (!pipeline) return json([]);
+			pipeline.checks += 1;
+			return json([{
+				name: "pages",
+				status: pipeline.checks > (options.deployAfterChecks ?? 0) ? "success" : "running",
+				target_url: `${webUrl}/${options.project}/-/jobs/1`
+			}]);
+		}
+		if (rest === "/pipelines") return json([...pipelines.keys()].map((sha, index) => ({
+			id: index + 1,
+			sha
+		})));
+		return json({ message: "404 Not Found" }, 404);
+	}
+	return {
+		repo,
+		requests,
+		commit,
+		authorize,
+		handle,
+		fetch: ((input, init) => handle(new Request(input, init)))
+	};
+}
+//#endregion
+export { fakeGitLab };

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@goodfellow-cms/gitlab",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Edit a Goodfellow site stored on GitLab, straight from the browser.",
+  "keywords": [
+    "goodfellow",
+    "cms",
+    "website-builder",
+    "puck",
+    "gitlab",
+    "git-based-cms"
+  ],
+  "homepage": "https://chartung17.github.io/goodfellow-cms/docs/hosts",
+  "bugs": "https://github.com/chartung17/goodfellow-cms/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chartung17/goodfellow-cms.git",
+    "directory": "packages/gitlab"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@goodfellow-cms/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@puckeditor/core": "0.23.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
 }