@goodfellow-cms/github 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/github
 
-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 GitHub, straight from the browser: sign-in with an access token, publishing as single commits, conflict checks and deploy status.
+
+```tsx
+import { github } from "@goodfellow-cms/github";
+
+export default defineConfig({ blocks, backend: github({ repo: "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,121 @@
+import { ConnectDomainOptions, DeployStatus, DnsRecord, FileChange, FileVersion, GitBackend, GitHost, GitUser, HistoryOptions, OwnerAccess, PagesDomains, SetupHost, SiteEditors, SiteUpdates, StorageLike, TokenLink, WriteOptions } from "@goodfellow-cms/core";
+//#region src/api.d.ts
+interface ApiOptions {
+  apiUrl: string;
+  token: string;
+  fetch: typeof fetch;
+}
+//#endregion
+//#region src/backend.d.ts
+interface GitHubBackendOptions {
+  api: ApiOptions;
+  repo: string;
+  branch: string;
+  user: GitUser;
+  onSignOut: () => void;
+  /** Where to create the owner token, which can change editors and GitHub Pages settings. */
+  ownerTokenLink: TokenLink;
+}
+/**
+ * The site's files on GitHub. Reads come from the commit `revision()` last
+ * returned; saves are single commits made with GraphQL's `createCommitOnBranch`,
+ * which fails if the branch has moved, so nothing is ever overwritten.
+ */
+export declare class GitHubBackend implements GitBackend {
+  readonly user: GitUser;
+  readonly pages: PagesDomains;
+  readonly editors: SiteEditors;
+  readonly ownerAccess: OwnerAccess;
+  readonly updates: SiteUpdates;
+  private readonly api;
+  private readonly repo;
+  private readonly branch;
+  private readonly onSignOut;
+  private pinned?;
+  private readonly trees;
+  private readonly blobs;
+  constructor(options: GitHubBackendOptions);
+  revision(): Promise<string>;
+  /** Path → blob id for every file at a commit. Commits never change, so this is cached. */
+  private tree;
+  private currentTree;
+  read(path: string): Promise<string | undefined>;
+  private readFrom;
+  readBytes(path: string): Promise<Uint8Array | undefined>;
+  list(dir: string): Promise<string[]>;
+  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 deployment GitHub Pages or Vercel created for a commit, and for
+   * GitHub Actions, the workflow run that builds it: a build that fails never
+   * creates a deployment. Before either exists, the site counts as building
+   * if it has ever been deployed.
+   */
+  deployStatus(revision: string): Promise<DeployStatus>;
+  /** The site's deploy workflow run for a commit, or `undefined` if there's none or the token can't see Actions. */
+  private workflowRun;
+  /** Which step of a failed run failed. */
+  private runProblem;
+  signOut(): void;
+}
+//#endregion
+//#region src/pages.d.ts
+/** The records GitHub Pages needs: its addresses for an apex domain, or an alias of the owner's github.io. */
+export declare function githubPagesRecords(repo: string, domain: string, { apex, www }: ConnectDomainOptions): DnsRecord[];
+//#endregion
+//#region src/setup.d.ts
+interface GitHubSetupOptions {
+  /** For GitHub Enterprise. Defaults to `https://api.github.com`. */
+  apiUrl?: string;
+  /** For GitHub Enterprise. Defaults to `https://github.com`. */
+  webUrl?: string;
+  /** For tests. */
+  fetch?: typeof fetch;
+}
+/**
+ * Links to GitHub's token pages with what creating a site needs: creating the
+ * repository (administration), writing its files and its build setup
+ * (contents and workflows), and turning on GitHub Pages (pages).
+ */
+export declare function githubSetupTokenLinks(webUrl?: string): {
+  fineGrained: string;
+  classic: string;
+};
+/** Signing in to GitHub to create a site's repository, with GitHub Pages if wanted. */
+export declare function githubSetup(options?: GitHubSetupOptions): SetupHost;
+//#endregion
+//#region src/index.d.ts
+export interface GitHubOptions {
+  /** The site's repository, as `owner/name`. */
+  repo: string;
+  /** The branch the live site is built from. Defaults to the repository's default branch. */
+  branch?: string;
+  /** For GitHub Enterprise. Defaults to `https://api.github.com`. */
+  apiUrl?: string;
+  /** For GitHub Enterprise. Defaults to `https://github.com`. */
+  webUrl?: string;
+  /** For tests. */
+  fetch?: typeof fetch;
+  /** For tests. */
+  storage?: {
+    local?: StorageLike;
+    session?: StorageLike;
+  };
+}
+/**
+ * Links to GitHub's token page with everything filled in except the
+ * repository, which GitHub doesn't let links choose.
+ */
+export declare function githubTokenLinks(repo: string, webUrl?: string): {
+  fineGrained: string;
+  classic: string;
+  owner: string;
+};
+/** Sign-in and storage for a site whose repository is on GitHub. */
+export declare function github(options: GitHubOptions): GitHost;
+//#endregion
+export type { GitHubSetupOptions };