@devframes/plugin-git 0.0.1

package/dist/src-Bm_Zrtej.mjs

@@ -0,0 +1,756 @@
+import { fileURLToPath } from "node:url";
+import { defineDevframe } from "devframe/types";
+import { dirname, resolve } from "pathe";
+import { execFile } from "node:child_process";
+import process from "node:process";
+import { promisify } from "node:util";
+import { defineRpcFunction } from "devframe";
+//#region package.json
+var name = "@devframes/plugin-git";
+var version = "0.0.1";
+var description = "Git integration for devframe — a read-only repository dashboard (status, log, branches, diff) with a Next.js + shadcn/ui SPA over type-safe RPC.";
+var homepage = "https://github.com/devframes/devframe#readme";
+//#endregion
+//#region src/node/git.ts
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 1024 * 1024 * 64;
+/**
+* Run a git command in `cwd`. Rejects when git exits non-zero — callers that
+* tolerate failure (e.g. "no upstream configured") should use {@link tryGit}.
+*/
+async function runGit(cwd, args) {
+	const { stdout, stderr } = await execFileAsync("git", args, {
+		cwd,
+		maxBuffer: MAX_BUFFER,
+		windowsHide: true,
+		env: {
+			...process.env,
+			GIT_PAGER: "cat",
+			GIT_OPTIONAL_LOCKS: "0",
+			LC_ALL: "C"
+		}
+	});
+	return {
+		stdout,
+		stderr
+	};
+}
+/** Run a git command, returning trimmed stdout or `null` when it fails. */
+async function tryGit(cwd, args) {
+	try {
+		const { stdout } = await runGit(cwd, args);
+		return stdout.replace(/\n$/, "");
+	} catch {
+		return null;
+	}
+}
+/** Resolve the repository root for `cwd`, or `null` when `cwd` is outside a repo. */
+async function resolveRepoRoot(cwd) {
+	return tryGit(cwd, ["rev-parse", "--show-toplevel"]);
+}
+/** Split git output on a separator, dropping the trailing empty segment. */
+function splitClean(input, separator) {
+	return input.split(separator).filter((part) => part.length > 0);
+}
+/**
+* Extract a concise, single-line message from a failed `execFile` error.
+* git writes useful text (e.g. "nothing to commit") to stdout/stderr.
+*/
+function gitErrorMessage(error) {
+	const e = error;
+	return (e?.stderr || e?.stdout || e?.message || "git command failed").trim().split("\n")[0];
+}
+//#endregion
+//#region src/rpc/context.ts
+const configs = /* @__PURE__ */ new WeakMap();
+const contexts = /* @__PURE__ */ new WeakMap();
+/**
+* Record the working directory for a context. Called from the devframe
+* `setup` before any RPC handler runs, so {@link getGitContext} can honor a
+* `repoRoot` override instead of the raw `ctx.cwd`.
+*/
+function configureGit(ctx, config) {
+	configs.set(ctx, config);
+}
+/**
+* Per-`DevframeNodeContext` git state. Each RPC function file pulls its
+* working directory and (memoized) repo-root lookup from here instead of
+* re-resolving on every call.
+*/
+function getGitContext(ctx) {
+	let existing = contexts.get(ctx);
+	if (existing) return existing;
+	const config = configs.get(ctx);
+	const cwd = config?.cwd ?? ctx.cwd;
+	const write = config?.write ?? false;
+	let rootPromise;
+	existing = {
+		cwd,
+		write,
+		resolveRoot: () => {
+			rootPromise ??= resolveRepoRoot(cwd);
+			return rootPromise;
+		}
+	};
+	contexts.set(ctx, existing);
+	return existing;
+}
+//#endregion
+//#region src/rpc/functions/branches.ts
+const FORMAT$1 = [
+	"%(refname:short)",
+	"%(objectname:short)",
+	"%(HEAD)",
+	"%(upstream:short)",
+	"%(upstream:track)",
+	"%(contents:subject)"
+].join("");
+function parseTrack(track) {
+	if (track.includes("gone")) return {
+		ahead: 0,
+		behind: 0,
+		gone: true
+	};
+	const ahead = track.match(/ahead (\d+)/);
+	const behind = track.match(/behind (\d+)/);
+	return {
+		ahead: ahead ? Number(ahead[1]) : 0,
+		behind: behind ? Number(behind[1]) : 0,
+		gone: false
+	};
+}
+const branches = defineRpcFunction({
+	name: "git:branches",
+	type: "query",
+	snapshot: true,
+	jsonSerializable: true,
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: async () => {
+			if (!await git.resolveRoot()) return {
+				isRepo: false,
+				current: null,
+				branches: []
+			};
+			const raw = await tryGit(git.cwd, [
+				"for-each-ref",
+				`--format=${FORMAT$1}`,
+				"refs/heads"
+			]);
+			if (!raw) return {
+				isRepo: true,
+				current: null,
+				branches: []
+			};
+			let current = null;
+			const branches = splitClean(raw, "\n").map((line) => {
+				const [name, sha, head, upstream, track, subject] = line.split("");
+				const isCurrent = head === "*";
+				if (isCurrent) current = name;
+				return {
+					name,
+					current: isCurrent,
+					sha,
+					upstream: upstream || null,
+					subject: subject ?? "",
+					...parseTrack(track ?? "")
+				};
+			});
+			branches.sort((a, b) => Number(b.current) - Number(a.current));
+			return {
+				isRepo: true,
+				current,
+				branches
+			};
+		} };
+	}
+});
+//#endregion
+//#region src/rpc/functions/status.ts
+const EMPTY_STATUS = {
+	isRepo: false,
+	root: null,
+	branch: null,
+	detached: false,
+	head: null,
+	upstream: null,
+	ahead: 0,
+	behind: 0,
+	staged: [],
+	unstaged: [],
+	untracked: [],
+	clean: true,
+	canWrite: false
+};
+function mapCode(code) {
+	switch (code) {
+		case "M": return "modified";
+		case "A": return "added";
+		case "D": return "deleted";
+		case "R": return "renamed";
+		case "C": return "copied";
+		case "T": return "type-changed";
+		case "U": return "unmerged";
+		default: return "unknown";
+	}
+}
+/**
+* Parse `git status --porcelain=v2 --branch -z` into a structured snapshot.
+* Records are NUL-separated; rename/copy (type `2`) entries consume an extra
+* token for the original path.
+*/
+function parseStatus(root, raw) {
+	const tokens = raw.split("\0");
+	const status = {
+		...EMPTY_STATUS,
+		isRepo: true,
+		root,
+		staged: [],
+		unstaged: [],
+		untracked: []
+	};
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (!token) continue;
+		if (token.startsWith("# ")) {
+			const [, key, ...rest] = token.split(" ");
+			const value = rest.join(" ");
+			if (key === "branch.head") if (value === "(detached)") {
+				status.detached = true;
+				status.branch = null;
+			} else status.branch = value;
+			else if (key === "branch.oid" && value !== "(initial)") status.head = value.slice(0, 9);
+			else if (key === "branch.upstream") status.upstream = value;
+			else if (key === "branch.ab") {
+				const match = value.match(/\+(\d+)\s+-(\d+)/);
+				if (match) {
+					status.ahead = Number(match[1]);
+					status.behind = Number(match[2]);
+				}
+			}
+			continue;
+		}
+		if (token.startsWith("1 ") || token.startsWith("2 ")) {
+			const renamed = token.startsWith("2 ");
+			const fields = token.split(" ");
+			const xy = fields[1];
+			const x = xy[0];
+			const y = xy[1];
+			const path = fields.slice(renamed ? 9 : 8).join(" ");
+			const from = renamed ? tokens[++i] : void 0;
+			if (x !== ".") status.staged.push(from ? {
+				path,
+				from,
+				status: mapCode(x)
+			} : {
+				path,
+				status: mapCode(x)
+			});
+			if (y !== ".") status.unstaged.push({
+				path,
+				status: mapCode(y)
+			});
+			continue;
+		}
+		if (token.startsWith("u ")) {
+			const path = token.split(" ").slice(10).join(" ");
+			status.unstaged.push({
+				path,
+				status: "unmerged"
+			});
+			continue;
+		}
+		if (token.startsWith("? ")) status.untracked.push(token.slice(2));
+	}
+	status.clean = status.staged.length === 0 && status.unstaged.length === 0 && status.untracked.length === 0;
+	return status;
+}
+/**
+* Read the working-tree status for a git context. Shared by the `git:status`
+* query and the write actions (which return fresh status after mutating).
+*/
+async function readStatus(git) {
+	const root = await git.resolveRoot();
+	if (!root) return {
+		...EMPTY_STATUS,
+		canWrite: false
+	};
+	const { stdout } = await runGit(git.cwd, [
+		"status",
+		"--porcelain=v2",
+		"--branch",
+		"-z"
+	]);
+	const status = parseStatus(root, stdout);
+	status.canWrite = git.write;
+	return status;
+}
+const status = defineRpcFunction({
+	name: "git:status",
+	type: "query",
+	snapshot: true,
+	jsonSerializable: true,
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: () => readStatus(git) };
+	}
+});
+//#endregion
+//#region src/rpc/functions/commit.ts
+const commit = defineRpcFunction({
+	name: "git:commit",
+	type: "action",
+	jsonSerializable: true,
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: async (args) => {
+			const message = (args?.message ?? "").trim();
+			if (!await git.resolveRoot()) return {
+				ok: false,
+				hash: null,
+				message: "Not a git repository.",
+				status: await readStatus(git)
+			};
+			if (!message) return {
+				ok: false,
+				hash: null,
+				message: "Commit message is required.",
+				status: await readStatus(git)
+			};
+			try {
+				await runGit(git.cwd, [
+					"commit",
+					"-m",
+					message
+				]);
+				return {
+					ok: true,
+					hash: await tryGit(git.cwd, [
+						"rev-parse",
+						"--short",
+						"HEAD"
+					]),
+					message: "Committed.",
+					status: await readStatus(git)
+				};
+			} catch (error) {
+				return {
+					ok: false,
+					hash: null,
+					message: gitErrorMessage(error),
+					status: await readStatus(git)
+				};
+			}
+		} };
+	}
+});
+//#endregion
+//#region src/rpc/functions/diff.ts
+/** Hard cap on the returned patch text to keep payloads bounded. */
+const PATCH_CHAR_LIMIT$1 = 2e5;
+function parseNumstat$1(raw) {
+	return splitClean(raw, "\n").map((line) => {
+		const [add, del, ...rest] = line.split("	");
+		const binary = add === "-" || del === "-";
+		return {
+			path: rest.join("	"),
+			additions: binary ? 0 : Number(add),
+			deletions: binary ? 0 : Number(del),
+			binary
+		};
+	});
+}
+const diff = defineRpcFunction({
+	name: "git:diff",
+	type: "query",
+	snapshot: true,
+	jsonSerializable: true,
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: async (args = {}) => {
+			const { path, staged = false } = args;
+			if (!await git.resolveRoot()) return {
+				isRepo: false,
+				staged,
+				path: path ?? null,
+				files: [],
+				totalAdditions: 0,
+				totalDeletions: 0,
+				patch: null,
+				truncated: false
+			};
+			const base = staged ? ["diff", "--cached"] : ["diff"];
+			const scope = path ? ["--", path] : [];
+			const numstatRaw = await tryGit(git.cwd, [
+				...base,
+				"--numstat",
+				...scope
+			]);
+			const files = numstatRaw ? parseNumstat$1(numstatRaw) : [];
+			const totalAdditions = files.reduce((sum, f) => sum + f.additions, 0);
+			const totalDeletions = files.reduce((sum, f) => sum + f.deletions, 0);
+			let patch = null;
+			let truncated = false;
+			if (path) {
+				const { stdout } = await runGit(git.cwd, [...base, ...scope]);
+				if (stdout.length > PATCH_CHAR_LIMIT$1) {
+					patch = stdout.slice(0, PATCH_CHAR_LIMIT$1);
+					truncated = true;
+				} else patch = stdout;
+			}
+			return {
+				isRepo: true,
+				staged,
+				path: path ?? null,
+				files,
+				totalAdditions,
+				totalDeletions,
+				patch,
+				truncated
+			};
+		} };
+	}
+});
+//#endregion
+//#region src/rpc/functions/log.ts
+const FORMAT = [
+	"%H",
+	"%h",
+	"%P",
+	"%an",
+	"%ae",
+	"%aI",
+	"%D",
+	"%s",
+	"%b"
+].join("") + "";
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+function parseLog(raw) {
+	return splitClean(raw, "").map((record) => {
+		const [hash, shortHash, parents, author, email, isoDate, refs, subject, body] = record.replace(/^\n/, "").split("");
+		return {
+			hash,
+			shortHash,
+			author,
+			email,
+			date: Date.parse(isoDate),
+			subject,
+			body: (body ?? "").trim(),
+			refs: refs ? refs.split(", ").map((r) => r.trim()).filter(Boolean) : [],
+			parents: parents ? parents.split(" ").filter(Boolean) : []
+		};
+	});
+}
+const SNAPSHOT_LIMIT$1 = 200;
+const log = defineRpcFunction({
+	name: "git:log",
+	type: "query",
+	jsonSerializable: true,
+	dump: async (_ctx, handler) => {
+		const baked = {
+			...await handler({
+				limit: SNAPSHOT_LIMIT$1,
+				skip: 0
+			}),
+			hasMore: false
+		};
+		return {
+			records: [{
+				inputs: [],
+				output: baked
+			}],
+			fallback: baked
+		};
+	},
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: async (args = {}) => {
+			const limit = clamp(Math.trunc(args.limit ?? 30), 1, 200);
+			const skip = Math.max(0, Math.trunc(args.skip ?? 0));
+			const ref = args.ref?.trim() || void 0;
+			if (!await git.resolveRoot()) return {
+				isRepo: false,
+				commits: [],
+				limit,
+				skip,
+				hasMore: false
+			};
+			const command = [
+				"log",
+				"--topo-order",
+				`--max-count=${limit}`,
+				`--skip=${skip}`,
+				`--pretty=format:${FORMAT}`
+			];
+			if (ref) command.push(ref);
+			const raw = await tryGit(git.cwd, command);
+			const commits = raw ? parseLog(raw) : [];
+			return {
+				isRepo: true,
+				commits,
+				limit,
+				skip,
+				hasMore: commits.length === limit
+			};
+		} };
+	}
+});
+//#endregion
+//#region src/rpc/functions/show.ts
+/** Hard cap on the returned patch text to keep payloads bounded. */
+const PATCH_CHAR_LIMIT = 2e5;
+/** Matches the window `git:log` bakes, so any visible commit has a snapshot. */
+const SNAPSHOT_LIMIT = 200;
+const EMPTY_DETAIL = {
+	isRepo: false,
+	found: false,
+	hash: "",
+	shortHash: "",
+	author: "",
+	email: "",
+	date: 0,
+	committer: "",
+	committerEmail: "",
+	commitDate: 0,
+	subject: "",
+	body: "",
+	parents: [],
+	refs: [],
+	files: [],
+	totalAdditions: 0,
+	totalDeletions: 0,
+	patch: null,
+	truncated: false
+};
+const SHOW_FORMAT = [
+	"%H",
+	"%h",
+	"%P",
+	"%an",
+	"%ae",
+	"%aI",
+	"%cn",
+	"%ce",
+	"%cI",
+	"%D",
+	"%s",
+	"%b"
+].join("");
+function parseNumstat(raw) {
+	return splitClean(raw, "\n").map((line) => {
+		const [add, del, ...rest] = line.split("	");
+		const binary = add === "-" || del === "-";
+		return {
+			path: rest.join("	"),
+			additions: binary ? 0 : Number(add),
+			deletions: binary ? 0 : Number(del),
+			binary
+		};
+	});
+}
+async function readCommit(git, hash, includePatch) {
+	const meta = await tryGit(git.cwd, [
+		"show",
+		"-s",
+		`--format=${SHOW_FORMAT}`,
+		hash
+	]);
+	if (meta == null) return {
+		...EMPTY_DETAIL,
+		isRepo: true
+	};
+	const [fullHash, shortHash, parents, author, email, authorDate, committer, committerEmail, committerDate, refs, subject, body] = meta.split("");
+	const numstat = await tryGit(git.cwd, [
+		"diff-tree",
+		"--no-commit-id",
+		"--numstat",
+		"-r",
+		"--root",
+		hash
+	]);
+	const files = numstat ? parseNumstat(numstat) : [];
+	const totalAdditions = files.reduce((sum, f) => sum + f.additions, 0);
+	const totalDeletions = files.reduce((sum, f) => sum + f.deletions, 0);
+	let patch = null;
+	let truncated = false;
+	if (includePatch) {
+		const raw = await tryGit(git.cwd, [
+			"diff-tree",
+			"-p",
+			"--no-commit-id",
+			"-r",
+			"--root",
+			hash
+		]);
+		if (raw != null) if (raw.length > PATCH_CHAR_LIMIT) {
+			patch = raw.slice(0, PATCH_CHAR_LIMIT);
+			truncated = true;
+		} else patch = raw;
+	}
+	return {
+		isRepo: true,
+		found: true,
+		hash: fullHash,
+		shortHash,
+		author,
+		email,
+		date: Date.parse(authorDate),
+		committer,
+		committerEmail,
+		commitDate: Date.parse(committerDate),
+		subject,
+		body: (body ?? "").trim(),
+		parents: parents ? parents.split(" ").filter(Boolean) : [],
+		refs: refs ? refs.split(", ").map((r) => r.trim()).filter(Boolean) : [],
+		files,
+		totalAdditions,
+		totalDeletions,
+		patch,
+		truncated
+	};
+}
+const show = defineRpcFunction({
+	name: "git:show",
+	type: "query",
+	jsonSerializable: true,
+	dump: async (ctx, _handler) => {
+		const git = getGitContext(ctx);
+		if (!await git.resolveRoot()) return {
+			records: [],
+			fallback: EMPTY_DETAIL
+		};
+		const raw = await tryGit(git.cwd, [
+			"log",
+			"--topo-order",
+			`--max-count=${SNAPSHOT_LIMIT}`,
+			"--pretty=format:%H"
+		]);
+		const hashes = raw ? raw.split("\n").filter(Boolean) : [];
+		const records = [];
+		for (const hash of hashes) {
+			const output = await readCommit(git, hash, false);
+			records.push({
+				inputs: [{ hash }],
+				output
+			});
+		}
+		return {
+			records,
+			fallback: records[0]?.output ?? {
+				...EMPTY_DETAIL,
+				isRepo: true
+			}
+		};
+	},
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: async (args) => {
+			const hash = (args?.hash ?? "").trim();
+			const includePatch = args?.patch ?? true;
+			if (!await git.resolveRoot() || !hash) return EMPTY_DETAIL;
+			return readCommit(git, hash, includePatch);
+		} };
+	}
+});
+//#endregion
+//#region src/rpc/functions/stage.ts
+const stage = defineRpcFunction({
+	name: "git:stage",
+	type: "action",
+	jsonSerializable: true,
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: async (args) => {
+			const paths = args?.paths ?? [];
+			if (await git.resolveRoot() && paths.length > 0) await runGit(git.cwd, [
+				"add",
+				"--",
+				...paths
+			]);
+			return readStatus(git);
+		} };
+	}
+});
+//#endregion
+//#region src/rpc/functions/unstage.ts
+const unstage = defineRpcFunction({
+	name: "git:unstage",
+	type: "action",
+	jsonSerializable: true,
+	setup: (ctx) => {
+		const git = getGitContext(ctx);
+		return { handler: async (args) => {
+			const paths = args?.paths ?? [];
+			if (await git.resolveRoot() && paths.length > 0) await runGit(git.cwd, [
+				"restore",
+				"--staged",
+				"--",
+				...paths
+			]);
+			return readStatus(git);
+		} };
+	}
+});
+//#endregion
+//#region src/rpc/index.ts
+/** Read-only RPC — always registered. */
+const readFunctions = [
+	status,
+	log,
+	show,
+	branches,
+	diff
+];
+/** Mutating RPC — registered only when write actions are enabled. */
+const writeFunctions = [
+	stage,
+	unstage,
+	commit
+];
+//#endregion
+//#region src/index.ts
+const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+/**
+* Create the Git dashboard devframe. Mount it into any host via devframe's
+* adapters, or run it standalone with the bundled CLI (`devframe-git`).
+*
+* @experimental This plugin is experimental and may change without a major
+* version bump until it stabilizes.
+*/
+function createGitDevframe(options = {}) {
+	const distDir = options.distDir ?? resolve(PKG_ROOT, "dist/client");
+	return defineDevframe({
+		id: "git",
+		name: "Git",
+		version,
+		packageName: name,
+		homepage,
+		description,
+		icon: "ph:git-branch-duotone",
+		basePath: options.basePath,
+		cli: {
+			command: "devframe-git",
+			port: options.port ?? 9710,
+			distDir,
+			auth: false,
+			configure(cli) {
+				cli.option("--write", "Enable staging, unstaging, and committing from the UI");
+			}
+		},
+		spa: { loader: "none" },
+		setup(ctx, info) {
+			const write = options.write ?? info?.flags?.write === true;
+			configureGit(ctx, {
+				cwd: options.repoRoot ? resolve(options.repoRoot) : ctx.cwd,
+				write
+			});
+			for (const fn of readFunctions) ctx.rpc.register(fn);
+			if (write) for (const fn of writeFunctions) ctx.rpc.register(fn);
+		}
+	});
+}
+var src_default = createGitDevframe();
+//#endregion
+export { src_default as n, createGitDevframe as t };