@goodfellow-cms/gitlab 0.0.0-stage → 0.2.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/goodfellow-cms/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://goodfellow-cms.github.io/goodfellow-cms/) for everything else.
+
+More in the docs: [Hosts and business sites](https://goodfellow-cms.github.io/goodfellow-cms/docs/hosts).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,138 @@
+import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, PagesDomains, SetupHost, SiteEditors, SiteUpdates, 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;
+  readonly pages: PagesDomains;
+  readonly editors: SiteEditors;
+  readonly updates: SiteUpdates;
+  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;
+  }>;
+  history(path: string, { page, perPage }?: HistoryOptions): Promise<FileVersion[]>;
+  readAt(path: string, revision: string): Promise<string | undefined>;
+  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>;
+  /** Why a commit's pipeline failed: the failed job's reason, and its log for which command failed and why. */
+  private jobProblem;
+  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/pages.d.ts
+/**
+ * The records GitLab Pages needs: its address for an apex domain, or an alias
+ * of the namespace's gitlab.io otherwise, and a TXT record per domain that
+ * proves it's the owner's, with the codes GitLab gave.
+ */
+export declare function gitlabPagesRecords(project: string, domain: string, options: ConnectDomainOptions, codes: Record<string, string>): DnsRecord[];
+//#endregion
+//#region src/setup.d.ts
+interface GitLabSetupOptions {
+  /** For self-managed GitLab. Defaults to `https://gitlab.com`. */
+  url?: string;
+  /**
+   * The Application ID of an OAuth application for the setup page (not
+   * confidential, scope `api`, redirect URI the page's address). Enables
+   * "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;
+}
+/** Signing in to GitLab to create a site's project, with GitLab Pages if wanted. */
+export declare function gitlabSetup(options?: GitLabSetupOptions): SetupHost;
+//#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
+export type { GitLabSetupOptions };