@optique/git 0.9.0-dev.1

package/dist/index.js

@@ -0,0 +1,489 @@
+import { message, text } from "@optique/core/message";
+import { ensureNonEmptyString } from "@optique/core/nonempty";
+import * as git from "isomorphic-git";
+import { expandOid, listBranches, listRemotes, listTags, readObject, resolveRef } from "isomorphic-git";
+import process from "node:process";
+
+//#region src/index.ts
+const METAVAR_BRANCH = "BRANCH";
+const METAVAR_TAG = "TAG";
+const METAVAR_REMOTE = "REMOTE";
+let defaultFs = null;
+let fsLoading = null;
+async function getDefaultFs() {
+	if (defaultFs) return await defaultFs;
+	if (fsLoading) return await fsLoading;
+	fsLoading = (async () => {
+		const nodeFs = await import("node:fs/promises");
+		const { TextDecoder } = await import("node:util");
+		const decoder = new TextDecoder();
+		defaultFs = {
+			async readFile(path) {
+				const data = await nodeFs.readFile(path);
+				if (path.endsWith("/index") || path.endsWith(".idx")) return data;
+				return decoder.decode(data);
+			},
+			async writeFile(path, data) {
+				await nodeFs.writeFile(path, data);
+			},
+			async mkdir(path, options) {
+				await nodeFs.mkdir(path, options);
+			},
+			async rmdir(path, options) {
+				await nodeFs.rmdir(path, options);
+			},
+			async unlink(path) {
+				await nodeFs.unlink(path);
+			},
+			async readdir(path) {
+				const entries = await nodeFs.readdir(path, { withFileTypes: false });
+				return entries.filter((e) => typeof e === "string");
+			},
+			async lstat(path) {
+				return await nodeFs.lstat(path);
+			},
+			async stat(path) {
+				return await nodeFs.stat(path);
+			},
+			async readlink(path) {
+				return await nodeFs.readlink(path);
+			},
+			async symlink(target, path) {
+				await nodeFs.symlink(target, path, "file");
+			},
+			async chmod(path, mode) {
+				await nodeFs.chmod(path, mode);
+			},
+			async chown(path, uid, gid) {
+				await nodeFs.chown(path, uid, gid);
+			},
+			async rename(oldPath, newPath) {
+				await nodeFs.rename(oldPath, newPath);
+			},
+			async copyFile(srcPath, destPath) {
+				await nodeFs.copyFile(srcPath, destPath);
+			},
+			async exists(path) {
+				try {
+					await nodeFs.stat(path);
+					return true;
+				} catch {
+					return false;
+				}
+			}
+		};
+		return defaultFs;
+	})();
+	return fsLoading;
+}
+function createAsyncValueParser(options, metavar, parseFn, suggestFn) {
+	return {
+		$mode: "async",
+		metavar,
+		async parse(input) {
+			const fs = options?.fs ?? await getDefaultFs();
+			const dir = options?.dir ?? (typeof process !== "undefined" ? process.cwd() : ".");
+			ensureNonEmptyString(metavar);
+			return parseFn(fs, dir, input);
+		},
+		format(value) {
+			return value;
+		},
+		async *suggest(prefix) {
+			const fs = options?.fs ?? await getDefaultFs();
+			const dir = options?.dir ?? (typeof process !== "undefined" ? process.cwd() : ".");
+			if (suggestFn) yield* suggestFn(fs, dir, prefix);
+		}
+	};
+}
+/**
+* Creates a value parser that validates local branch names.
+*
+* This parser uses isomorphic-git to verify that the provided input
+* matches an existing branch in the repository.
+*
+* @param options Configuration options for the parser.
+* @returns A value parser that accepts existing branch names.
+* @since 0.9.0
+*
+* @example
+* ~~~~ typescript
+* import { gitBranch } from "@optique/git";
+* import { argument } from "@optique/core/primitives";
+*
+* const parser = argument(gitBranch());
+* ~~~~
+*/
+function gitBranch(options) {
+	const metavar = options?.metavar ?? METAVAR_BRANCH;
+	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+		try {
+			const branches = await git.listBranches({
+				fs,
+				dir
+			});
+			if (branches.includes(input)) return {
+				success: true,
+				value: input
+			};
+			return {
+				success: false,
+				error: message`Branch ${text(input)} does not exist. Available branches: ${branches.join(", ")}`
+			};
+		} catch {
+			return {
+				success: false,
+				error: message`Failed to list branches. Ensure ${text(dir)} is a valid git repository.`
+			};
+		}
+	}, async function* suggestBranch(fs, dir, prefix) {
+		try {
+			const branches = await git.listBranches({
+				fs,
+				dir
+			});
+			for (const branch of branches) if (branch.startsWith(prefix)) yield {
+				kind: "literal",
+				text: branch
+			};
+		} catch {}
+	});
+}
+/**
+* Creates a value parser that validates remote branch names.
+*
+* This parser uses isomorphic-git to verify that the provided input
+* matches an existing branch on the specified remote.
+*
+* @param remote The remote name to validate against.
+* @param options Configuration options for the parser.
+* @returns A value parser that accepts existing remote branch names.
+* @since 0.9.0
+*
+* @example
+* ~~~~ typescript
+* import { gitRemoteBranch } from "@optique/git";
+* import { option } from "@optique/core/primitives";
+*
+* const parser = option("-b", "--branch", gitRemoteBranch("origin"));
+* ~~~~
+*/
+function gitRemoteBranch(remote, options) {
+	const metavar = options?.metavar ?? METAVAR_BRANCH;
+	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+		try {
+			const branches = await git.listBranches({
+				fs,
+				dir,
+				remote
+			});
+			if (branches.includes(input)) return {
+				success: true,
+				value: input
+			};
+			return {
+				success: false,
+				error: message`Remote branch ${text(input)} does not exist on remote ${text(remote)}. Available branches: ${branches.join(", ")}`
+			};
+		} catch {
+			return {
+				success: false,
+				error: message`Failed to list remote branches. Ensure remote ${text(remote)} exists.`
+			};
+		}
+	}, async function* suggestRemoteBranch(fs, dir, prefix) {
+		try {
+			const branches = await git.listBranches({
+				fs,
+				dir,
+				remote
+			});
+			for (const branch of branches) if (branch.startsWith(prefix)) yield {
+				kind: "literal",
+				text: branch
+			};
+		} catch {}
+	});
+}
+/**
+* Creates a value parser that validates tag names.
+*
+* This parser uses isomorphic-git to verify that the provided input
+* matches an existing tag in the repository.
+*
+* @param options Configuration options for the parser.
+* @returns A value parser that accepts existing tag names.
+* @since 0.9.0
+*
+* @example
+* ~~~~ typescript
+* import { gitTag } from "@optique/git";
+* import { option } from "@optique/core/primitives";
+*
+* const parser = option("-t", "--tag", gitTag());
+* ~~~~
+*/
+function gitTag(options) {
+	const metavar = options?.metavar ?? METAVAR_TAG;
+	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+		try {
+			const tags = await git.listTags({
+				fs,
+				dir
+			});
+			if (tags.includes(input)) return {
+				success: true,
+				value: input
+			};
+			return {
+				success: false,
+				error: message`Tag ${text(input)} does not exist. Available tags: ${tags.join(", ")}`
+			};
+		} catch {
+			return {
+				success: false,
+				error: message`Failed to list tags. Ensure ${text(dir)} is a valid git repository.`
+			};
+		}
+	}, async function* suggestTag(fs, dir, prefix) {
+		try {
+			const tags = await git.listTags({
+				fs,
+				dir
+			});
+			for (const tag of tags) if (tag.startsWith(prefix)) yield {
+				kind: "literal",
+				text: tag
+			};
+		} catch {}
+	});
+}
+/**
+* Creates a value parser that validates remote names.
+*
+* This parser uses isomorphic-git to verify that the provided input
+* matches an existing remote in the repository.
+*
+* @param options Configuration options for the parser.
+* @returns A value parser that accepts existing remote names.
+* @since 0.9.0
+*
+* @example
+* ~~~~ typescript
+* import { gitRemote } from "@optique/git";
+* import { option } from "@optique/core/primitives";
+*
+* const parser = option("-r", "--remote", gitRemote());
+* ~~~~
+*/
+function gitRemote(options) {
+	const metavar = options?.metavar ?? METAVAR_REMOTE;
+	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+		try {
+			const remotes = await git.listRemotes({
+				fs,
+				dir
+			});
+			const remoteNames = [];
+			for (const r of remotes) if ("remote" in r && typeof r.remote === "string") remoteNames.push(r.remote);
+			if (remoteNames.includes(input)) return {
+				success: true,
+				value: input
+			};
+			return {
+				success: false,
+				error: message`Remote ${text(input)} does not exist. Available remotes: ${remoteNames.join(", ")}`
+			};
+		} catch {
+			return {
+				success: false,
+				error: message`Failed to list remotes. Ensure ${text(dir)} is a valid git repository.`
+			};
+		}
+	}, async function* suggestRemote(fs, dir, prefix) {
+		try {
+			const remotes = await git.listRemotes({
+				fs,
+				dir
+			});
+			for (const r of remotes) if ("remote" in r && typeof r.remote === "string" && r.remote.startsWith(prefix)) yield {
+				kind: "literal",
+				text: r.remote
+			};
+		} catch {}
+	});
+}
+/**
+* Creates a value parser that validates commit SHAs.
+*
+* This parser uses isomorphic-git to verify that the provided input
+* is a valid commit SHA (full or shortened) that exists in the repository.
+*
+* @param options Configuration options for the parser.
+* @returns A value parser that accepts valid commit SHAs.
+* @since 0.9.0
+*
+* @example
+* ~~~~ typescript
+* import { gitCommit } from "@optique/git";
+* import { option } from "@optique/core/primitives";
+*
+* const parser = option("-c", "--commit", gitCommit());
+* ~~~~
+*/
+function gitCommit(options) {
+	const metavar = options?.metavar ?? "COMMIT";
+	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+		try {
+			const oid = await git.expandOid({
+				fs,
+				dir,
+				oid: input
+			});
+			await git.readObject({
+				fs,
+				dir,
+				oid
+			});
+			return {
+				success: true,
+				value: oid
+			};
+		} catch {
+			return {
+				success: false,
+				error: message`Commit ${text(input)} does not exist. Provide a valid commit SHA.`
+			};
+		}
+	}, async function* suggestCommit(fs, dir, prefix) {
+		try {
+			const branches = await git.listBranches({
+				fs,
+				dir
+			});
+			const commits = [];
+			for (const branch of branches.slice(0, 10)) try {
+				const oid = await git.resolveRef({
+					fs,
+					dir,
+					ref: branch
+				});
+				if (oid.startsWith(prefix)) commits.push(oid);
+			} catch {}
+			for (const commit of [...new Set(commits)].slice(0, 10)) yield {
+				kind: "literal",
+				text: commit
+			};
+		} catch {}
+	});
+}
+/**
+* Creates a value parser that validates any git reference
+* (branches, tags, or commits).
+*
+* This parser uses isomorphic-git to verify that the provided input
+* resolves to a valid git reference (branch, tag, or commit SHA).
+*
+* @param options Configuration options for the parser.
+* @returns A value parser that accepts branches, tags, or commit SHAs.
+* @since 0.9.0
+*
+* @example
+* ~~~~ typescript
+* import { gitRef } from "@optique/git";
+* import { option } from "@optique/core/primitives";
+*
+* const parser = option("--ref", gitRef());
+* ~~~~
+*/
+function gitRef(options) {
+	const metavar = options?.metavar ?? "REF";
+	return createAsyncValueParser(options, metavar, async (fs, dir, input) => {
+		try {
+			const oid = await git.resolveRef({
+				fs,
+				dir,
+				ref: input
+			});
+			return {
+				success: true,
+				value: oid
+			};
+		} catch {
+			return {
+				success: false,
+				error: message`Reference ${text(input)} does not exist. Provide a valid branch, tag, or commit SHA.`
+			};
+		}
+	}, async function* suggestRef(fs, dir, prefix) {
+		try {
+			const branches = await git.listBranches({
+				fs,
+				dir
+			});
+			for (const branch of branches) if (branch.startsWith(prefix)) yield {
+				kind: "literal",
+				text: branch
+			};
+			const tags = await git.listTags({
+				fs,
+				dir
+			});
+			for (const tag of tags) if (tag.startsWith(prefix)) yield {
+				kind: "literal",
+				text: tag
+			};
+		} catch {}
+	});
+}
+/**
+* Creates a factory for git parsers with shared configuration.
+*
+* This function returns an object with methods for creating individual git
+* parsers that share the same configuration (filesystem and directory).
+*
+* @param options Shared configuration options for all parsers.
+* @returns An object with methods for creating individual git parsers.
+* @since 0.9.0
+*
+* @example
+* ~~~~ typescript
+* import { createGitParsers } from "@optique/git";
+*
+* const git = createGitParsers({ dir: "/path/to/repo" });
+*
+* const branchParser = git.branch();
+* const tagParser = git.tag();
+* ~~~~
+*/
+function createGitParsers(options) {
+	return {
+		branch: (parserOptions) => gitBranch({
+			...options,
+			...parserOptions
+		}),
+		remoteBranch: (remote, parserOptions) => gitRemoteBranch(remote, {
+			...options,
+			...parserOptions
+		}),
+		tag: (parserOptions) => gitTag({
+			...options,
+			...parserOptions
+		}),
+		remote: (parserOptions) => gitRemote({
+			...options,
+			...parserOptions
+		}),
+		commit: (parserOptions) => gitCommit({
+			...options,
+			...parserOptions
+		}),
+		ref: (parserOptions) => gitRef({
+			...options,
+			...parserOptions
+		})
+	};
+}
+
+//#endregion
+export { createGitParsers, expandOid, gitBranch, gitCommit, gitRef, gitRemote, gitRemoteBranch, gitTag, listBranches, listRemotes, listTags, readObject, resolveRef };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@optique/git",
+  "version": "0.9.0-dev.1",
+  "description": "Git value parsers for Optique",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "git",
+    "git-reference",
+    "branch",
+    "tag",
+    "commit"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/git/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "isomorphic-git": "^1.36.1",
+    "@optique/core": ""
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "tsdown && node --experimental-transform-types --test",
+    "test:bun": "tsdown && bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}