@pogo-vcs/pogo 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+zlib/libpng license
+
+Copyright (c) 2025 Frank Mayer
+
+This software is provided 'as-is', without any express or implied warranty.
+In no event will the authors be held liable for any damages arising from the
+use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+    1. The origin of this software must not be misrepresented; you must not
+    claim that you wrote the original software. If you use this software in a
+    product, an acknowledgment in the product documentation would be
+    appreciated but is not required.
+
+    2. Altered source versions must be plainly marked as such, and must not
+    be misrepresented as being the original software.
+
+    3. This notice may not be removed or altered from any source
+    distribution.

package/README.md

@@ -0,0 +1,143 @@
+<div align="center">
+<h1 align="center">
+<img src="/brand/logo.svg" width="150" alt="P" />
+<br>
+Pogo
+</h1>
+<p align="center">
+<strong>A centralized version control system that is simple and easy to use.</strong>
+</p>
+<p align="center">
+<a href="https://github.com/pogo-vcs/pogo/releases"><img src="https://img.shields.io/github/v/release/pogo-vcs/pogo" alt="Latest release" /></a>
+<a href="https://github.com/pogo-vcs/pogo/actions/workflows/test.yaml"><img src="https://img.shields.io/github/actions/workflow/status/pogo-vcs/pogo/test.yaml" alt="GitHub Workflow Status" /></a>
+<a href="https://github.com/pogo-vcs/pogo/blob/main/LICENSE"><img src="https://img.shields.io/github/license/pogo-vcs/pogo" alt="License" /></a>
+</p>
+</div>
+
+Pogo is a centralized version control system designed to be straightforward and efficient. It features an easy-to-use CLI client, a simple web UI, and robust support for both text and binary files. Pogo treats conflicts as first-class citizens, allowing them to be pushed to the remote to be resolved later.
+
+## ✨ Goals
+
+- **🏠 Centralized Server:** A single source of truth for all your data.
+- **💻 Easy CLI Client:** No need for a complex GUI.
+- **🌐 Simple Web UI:** For easy viewing of your repositories.
+- **🔄 Cross-Platform Consistency:** Works the same on all major operating systems.
+- **📄 Text & Binary File Support:** Handles all file types with ease.
+- **💥 First-Class Conflicts:** Push conflicts to the remote and resolve them later.
+- **🌳 No Named Branches:** Create branches by adding multiple children to a change and merge them by creating a new change with multiple parents. Changes are automaticall named.
+- **🔖 Bookmarks:** Tag versions with bookmarks, like `main` for the current version or `v1.0.0` for a specific version. `main` is treated like a default branch in Git.
+- **📦 Go Module Support:** Import a Pogo repository as a Go module, no additional configuration or software required.
+
+## 🚀 Installation
+
+### NPM
+
+```sh
+npm install -g @pogo-vcs/pogo
+```
+
+### Homebrew
+
+```sh
+brew install --cask pogo-vcs/tap/pogo
+```
+
+### Scoop
+
+```sh
+scoop bucket add pogo-vcs https://github.com/pogo-vcs/scoop-bucket.git
+scoop install pogo
+```
+
+### Docker (server)
+
+```sh
+docker pull ghcr.io/pogo-vcs/pogo:alpine
+```
+
+### From Source
+
+To build Pogo from source, run the following commands:
+
+```sh
+git clone https://github.com/pogo-vcs/pogo.git
+cd pogo
+just build
+```
+
+This will create a `pogo` binary in the current directory. You can move this binary to a directory in your `PATH` to make it accessible from anywhere.
+
+Required software for building:
+
+- [go](https://go.dev/)
+- [just](https://github.com/casey/just)
+- [protoc](https://protobuf.dev/) (for gRPC)
+- [sqlc](https://sqlc.dev/)
+- [pnpm](https://pnpm.io/) (for Tailwind CSS)
+- [templ](https://templ.guide/)
+
+## 🕹️ Usage
+
+The intended workflow for Pogo is simple and efficient:
+
+1.  **describe your changes:** Before you start working, use the `pogo describe` command to write a detailed description of the changes you are about to make and why. This helps you to think about the changes and to communicate them to others.
+2.  **Make your changes:** Make the changes to your files as you normally would.
+3.  **Iterate on the description:** As you work, you can iterate on the description to reflect the changes you are making. Maybe your implementation plan changed and you need your description to reflect that.
+4.  **Push your changes:** Regularly push your changes to the server using the `pogo push` command. A daemon process that pushes automatically will be added later. You constantly overwrite the current change until you are satisfied with it.
+5.  **Create a new change:** When you are done with your changes, create a new one using the `pogo new` command. You can optionally add one or more parent changes to the command. By default, your current change is used as the parent.
+6.  **Maintain a "main" bookmark:** Use bookmarks to tag important changes. You can set a bookmark with `pogo bookmark set main` to set the current change as the main one, or `pogo bookmark set main <change>` to set a specific change as main. "main" ist just a string, you can use any format for version bookmarks you want. But "main" is a special value, treated like a default branch in Git.
+
+## 📋 Commands
+
+| Command         | Subcommand | Aliases            | Description                                                                                 |
+| --------------- | ---------- | ------------------ | ------------------------------------------------------------------------------------------- |
+| `pogo`          |            |                    | The root command for the Pogo CLI.                                                          |
+| `pogo bookmark` |            | `b`                | Manage bookmarks.                                                                           |
+|                 | `set`      | `s`                | Set a bookmark to a specific change. If no change is specified, the current change is used. |
+|                 | `list`     | `l`                | List all bookmarks.                                                                         |
+| `pogo commit`   |            |                    | Combines `describe`, `push`, and `new` into a single command.                               |
+| `pogo describe` |            | `desc`, `rephrase` | Set the description for the current change.                                                 |
+| `pogo edit`     |            | `checkout`         | Sets the specified revision as the working-copy revision.                                   |
+| `pogo gc`       |            |                    | Run garbage collection on the server.                                                       |
+| `pogo info`     |            |                    | Display the current working copy status.                                                    |
+| `pogo init`     |            |                    | Initialize a new repository.                                                                |
+| `pogo log`      |            |                    | Show the change history.                                                                    |
+| `pogo new`      |            |                    | Create a new change based on one or more parent changes.                                    |
+| `pogo push`     |            |                    | Push a change to the repository.                                                            |
+| `pogo rm`       |            |                    | Remove a change from the repository.                                                        |
+| `pogo serve`    |            |                    | Start the Pogo server.                                                                      |
+| `pogo whoami`   |            |                    | Show the personal access token being used for the current repository.                       |
+
+## 🏗️ Architecture
+
+Pogo uses a PostgreSQL server to store all metadata about repositories, changes, and files. The actual file contents are stored in an object store on the file system. This separation of metadata and content allows for efficient storage and retrieval of data.
+
+## 🗑️ Garbage Collection
+
+Pogo includes an automatic garbage collection system that removes unreachable data to prevent unbounded storage growth. The GC system cleans up both database records and filesystem objects that are no longer referenced by any repository.
+
+### How to Use
+
+- **Manual GC:** Run `pogo gc` from any repository to trigger garbage collection on the server. This requires authentication.
+- **Automatic GC:** When running `pogo serve`, garbage collection automatically runs daily at 3:00 AM server time.
+
+### Adaptive Implementation
+
+The garbage collection system uses an adaptive strategy based on the total number of files in the database:
+
+- **Small-scale (< 10 million files):** Uses an in-memory hash map strategy for fast O(1) lookups.
+- **Large-scale (≥ 10 million files):** Uses a batch processing strategy that scales to billions of files with constant memory usage.
+
+The threshold can be configured via the `GC_MEMORY_THRESHOLD` environment variable.
+
+## 📜 License
+
+This project is published under the [Zlib license](LICENSE).
+
+In short:
+
+- You can use Pogo for any purpose, for free, including commercial use, forever.
+- You can create and distribute modified versions of Pogo, but you must not misrepresent the software's origin, you must clearly mark your changes, and you must retain the original license notice.
+- I don't take any responsibility for any damages or losses that may occur as a result of using Pogo. If you encounter any issues, please report them to me.
+
+If you make any modifications to Pogo, I would appreciate it if you shared them with me. I'm always interested in learning from others and improving my own work.

package/install.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// This file was generated by GoReleaser. DO NOT EDIT.
+
+const { install } = require("./lib.js");
+install();

package/lib.js

@@ -0,0 +1,215 @@
+// This file was generated by GoReleaser. DO NOT EDIT.
+const { archives } = require("./package.json");
+const fs = require("fs");
+const crypto = require("crypto");
+const path = require("path");
+const JSZip = require("jszip");
+const tar = require("tar");
+const axios = require("axios");
+const { spawnSync } = require("child_process");
+
+const getArchive = () => {
+	let target = `${process.platform}-${process.arch}`;
+	const archive = archives[target];
+	if (!archive) {
+		throw new Error(`No archive available for ${target}`);
+	}
+	return archive;
+};
+
+const binDir = path.join(__dirname, "bin");
+
+async function extractTar(tarPath, binaries, dir, wrappedIn) {
+	try {
+		const filesToExtract = wrappedIn
+			? binaries.map((bin) =>
+				path.join(wrappedIn, bin).replace(/\\/g, "/"),
+			)
+			: binaries;
+
+		await tar.x({
+			file: tarPath,
+			cwd: dir,
+			filter: (path) => filesToExtract.includes(path),
+		});
+
+		// If wrapped, move files from wrapped directory to bin directory
+		if (wrappedIn) {
+			const wrappedDir = path.join(dir, wrappedIn);
+			for (const binary of binaries) {
+				const srcPath = path.join(wrappedDir, binary);
+				const destPath = path.join(dir, binary);
+				if (fs.existsSync(srcPath)) {
+					fs.renameSync(srcPath, destPath);
+				}
+			}
+			// Clean up empty wrapped directory
+			try {
+				fs.rmSync(wrappedDir, { recursive: true, force: true });
+			} catch (err) {
+				// Ignore cleanup errors
+			}
+		}
+
+		console.log(`Successfully extracted ${binaries} to "${dir}"`);
+	} catch (err) {
+		throw new Error(`Extraction failed: ${err.message}`);
+	}
+}
+
+async function extractZip(zipPath, binaries, dir, wrappedIn) {
+	try {
+		const zipData = fs.readFileSync(zipPath);
+		const zip = await JSZip.loadAsync(zipData);
+
+		for (const binary of binaries) {
+			const binaryPath = wrappedIn
+				? path.join(wrappedIn, binary).replace(/\\/g, "/")
+				: binary;
+
+			if (!zip.files[binaryPath]) {
+				throw new Error(
+					`Error: ${binaryPath} does not exist in ${zipPath}`,
+				);
+			}
+
+			const content = await zip.files[binaryPath].async("nodebuffer");
+			if (!fs.existsSync(dir)) {
+				fs.mkdirSync(dir, { recursive: true });
+			}
+			const file = path.join(dir, binary);
+			fs.writeFileSync(file, content);
+			fs.chmodSync(file, "755");
+			console.log(`Successfully extracted "${binary}" to "${dir}"`);
+		}
+	} catch (err) {
+		throw new Error(`Extraction failed: ${err.message}`);
+	}
+}
+
+const run = async (bin) => {
+	await install();
+	if (process.platform === "win32") {
+		bin += ".exe";
+	}
+	const [, , ...args] = process.argv;
+	let result = spawnSync(path.join(binDir, bin), args, {
+		cwd: process.cwd(),
+		stdio: "inherit",
+	});
+	if (result.error) {
+		console.error(result.error);
+	}
+	return result.status;
+};
+
+const install = async () => {
+	try {
+		let archive = getArchive();
+		if (await exists(archive)) {
+			return;
+		}
+		let tmp = fs.mkdtempSync("archive-");
+		let archivePath = path.join(tmp, archive.name);
+		await download(archive.url, archivePath);
+		verify(archivePath, archive.checksum);
+
+		if (!fs.existsSync(binDir)) {
+			fs.mkdirSync(binDir);
+		}
+		switch (archive.format) {
+			case "binary":
+				const bin = path.join(binDir, archive.bins[0]);
+				fs.copyFileSync(archivePath, bin);
+				fs.chmodSync(bin, 0o755);
+				return;
+			case "zip":
+				return extractZip(
+					archivePath,
+					archive.bins,
+					binDir,
+					archive.wrappedIn,
+				);
+			case "tar":
+			case "tar.gz":
+			case "tgz":
+				return extractTar(
+					archivePath,
+					archive.bins,
+					binDir,
+					archive.wrappedIn,
+				);
+			case "tar.zst":
+			case "tzst":
+			case "tar.xz":
+			case "txz":
+			default:
+				throw new Error(`unsupported format: ${archive.format}`);
+		}
+	} catch (err) {
+		throw new Error(`Installation failed: ${err.message}`);
+	}
+};
+
+const verify = (filename, checksum) => {
+	if (checksum.algorithm == "" || checksum.digest == "") {
+		console.warn("Warning: No checksum provided for verification");
+		return;
+	}
+	let digest = crypto
+		.createHash(checksum.algorithm)
+		.update(fs.readFileSync(filename))
+		.digest("hex");
+	if (digest != checksum.digest) {
+		throw new Error(
+			`${filename}: ${checksum.algorithm} does not match, expected ${checksum.digest}, got ${digest}`,
+		);
+	}
+};
+
+const download = async (url, filename) => {
+	try {
+		console.log(`Downloading ${url} to ${filename}...`);
+		const dir = path.dirname(filename);
+		if (!fs.existsSync(dir)) {
+			fs.mkdirSync(dir, { recursive: true });
+		}
+
+		const response = await axios({
+			method: "GET",
+			url: url,
+			responseType: "stream",
+			timeout: 300000, // 5min
+		});
+
+		const writer = fs.createWriteStream(filename);
+		response.data.pipe(writer);
+
+		return new Promise((resolve, reject) => {
+			writer.on("finish", () => {
+				console.log(`Download complete: ${filename}`);
+				resolve(dir);
+			});
+
+			writer.on("error", (err) => {
+				console.error(`Error writing file: ${err.message}`);
+				reject(err);
+			});
+		});
+	} catch (err) {
+		throw new Error(`Download failed: ${err.message}`);
+	}
+};
+
+function exists(archive) {
+	if (!fs.existsSync(binDir)) {
+		return false;
+	}
+	return archive.bins.every((bin) => fs.existsSync(path.join(binDir, bin)));
+}
+
+module.exports = {
+	install,
+	run,
+	getArchive,
+};

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@pogo-vcs/pogo",
+  "version": "0.0.1",
+  "description": "A centralized version control system that is simple and easy to use.",
+  "scripts": {
+    "postinstall": "node install.js",
+    "run": "node run-pogo.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pogo-vcs/pogo"
+  },
+  "keywords": [
+    "cli",
+    "golang",
+    "version control",
+    "vcs",
+    "scm",
+    "centralized",
+    "git"
+  ],
+  "author": "Frank Mayer",
+  "license": "Zlib",
+  "bugs": {
+    "url": "https://github.com/pogo-vcs/pogo/issues"
+  },
+  "homepage": "https://github.com/pogo-vcs/pogo",
+  "bin": {
+    "pogo": "run-pogo.js"
+  },
+  "dependencies": {
+    "axios": "^1.8.2",
+    "jszip": "^3.10.1",
+    "tar": "^7.4.3"
+  },
+  "archives": {
+    "win32-arm64": {
+      "name": "pogo_Windows_arm64.zip",
+      "url": "https://github.com/pogo-vcs/pogo/releases/download/v0.0.1/pogo_Windows_arm64.zip",
+      "bins": [
+        "pogo.exe"
+      ],
+      "format": "zip",
+      "checksum": {
+        "algorithm": "sha256",
+        "digest": "66e8ba9843321967d5b1bfa0bee94c726edac1694d2eda1316b3d7f4f8dab130"
+      }
+    },
+    "win32-x64": {
+      "name": "pogo_Windows_x86_64.zip",
+      "url": "https://github.com/pogo-vcs/pogo/releases/download/v0.0.1/pogo_Windows_x86_64.zip",
+      "bins": [
+        "pogo.exe"
+      ],
+      "format": "zip",
+      "checksum": {
+        "algorithm": "sha256",
+        "digest": "b018dc7c68c4daf26b3e96aad408d9f5bb59921bc2d0f02f942e1bb0460deaf4"
+      }
+    }
+  }
+}

package/run-pogo.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// This file was generated by GoReleaser. DO NOT EDIT.
+
+const { run } = require("./lib.js");
+run("pogo");