@theholocron/git-utils 1.9.2 → 1.10.0

package/dist/index.d.mts

@@ -0,0 +1,89 @@
+//#region src/managed-block.d.ts
+export interface ManagedBlockOptions {
+  /** The line that opens the block, e.g. `# managed by my-tool — skills`. Matched as text, so it must be distinctive. */
+  start: string;
+  /** The line that closes the block. */
+  end: string;
+  /** What goes between the markers, one entry per line. No blank lines, and no line breaks inside an entry. */
+  lines: readonly string[];
+}
+/**
+ * Inserts or replaces a block of lines delimited by marker lines, leaving
+ * everything outside it untouched.
+ *
+ * - Block present (`start` … `end`): replaced in place.
+ * - No block: appended, separated from existing content by a blank line, with a
+ *   single trailing newline.
+ * - `start` present but `end` missing (hand-edited or truncated): the block is
+ *   taken to run to the next blank line, or to the end of the file — so the
+ *   content after it is kept, not lost. An `end` marker only closes the block
+ *   when it comes before that blank line; one further down is left alone.
+ *
+ * Line endings follow the existing text (`\r\n` when it mostly uses them), so
+ * a CRLF file stays CRLF. That is also why `lines` can't contain blank lines: a
+ * blank line is how an unterminated block is told apart from the next section.
+ *
+ * Idempotent: calling it again with the same options returns the same text.
+ * There are no default markers; callers choose them, and must keep them stable
+ * so existing blocks are still found.
+ *
+ * @throws {TypeError} when an entry in `lines` is blank or contains a line break.
+ */
+export declare function upsertManagedBlock(content: string, { start, end, lines }: ManagedBlockOptions): string;
+/**
+ * {@link upsertManagedBlock} applied to a file (a missing file counts as empty,
+ * and is created). Writes only when the content changes, and atomically (a
+ * temp file renamed into place; a symlinked path is updated through the link).
+ * Resolves to `true` when it wrote.
+ *
+ * Calls for the same path within one process run one after another, each
+ * reading the file as the previous left it. Separate processes aren't
+ * coordinated. Any read error other than "no such file" rejects, rather than
+ * being mistaken for an empty file and overwritten.
+ */
+export declare function updateGitignore(path: string, options: ManagedBlockOptions): Promise<boolean>;
+//#endregion
+//#region src/remote.d.ts
+export interface GitRemote {
+  host: string;
+  /** Everything before the repo name: `owner`, or `group/subgroup` on hosts with nested groups. */
+  owner: string;
+  repo: string;
+  /** `owner/repo`. */
+  slug: string;
+}
+/**
+ * Parses a git remote URL — any host, any of the common shapes:
+ *
+ * - `https://github.com/owner/repo(.git)(/)`, with optional credentials or port
+ * - `git@github.com:owner/repo(.git)` (scp-style SSH)
+ * - `ssh://git@github.com(:22)/owner/repo(.git)`
+ * - `git://github.com/owner/repo.git`
+ *
+ * A bracketed IPv6 host is returned without its brackets. The whole input must
+ * be one remote: trailing text after the URL (apart from a `?query` or
+ * `#fragment`) makes it `undefined`.
+ *
+ * `undefined` for anything else (a local path, an empty string, a URL with
+ * fewer than two path segments).
+ */
+export declare function parseGitRemoteUrl(url: string): GitRemote | undefined;
+/**
+ * Runs `git <args>` in `options.cwd` and resolves its stdout; rejects when git
+ * exits non-zero. Injectable so callers' tests don't need a real repository.
+ */
+export type GitExec = (args: string[], options: {
+  cwd: string;
+}) => Promise<string>;
+export interface ReadGitRemoteOptions {
+  exec?: GitExec;
+  /** Remote name. Default `"origin"`. */
+  remote?: string;
+}
+/**
+ * The parsed URL of a repository's remote (`git remote get-url <remote>`), or
+ * `undefined` when `cwd` isn't a repository, has no such remote, git isn't
+ * installed, or the URL isn't one {@link parseGitRemoteUrl} understands.
+ */
+export declare function readGitRemote(cwd: string, options?: ReadGitRemoteOptions): Promise<GitRemote | undefined>;
+//#endregion

package/dist/index.mjs

@@ -0,0 +1,165 @@
+import { randomBytes } from "node:crypto";
+import { chmod, readFile, realpath, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+//#region src/managed-block.ts
+/** A blank (or whitespace-only) line: the boundary of a block whose end marker went missing. */
+const BLANK_LINE = /\r?\n[ \t]*\r?\n/;
+/** `\r\n` when it is the text's majority line ending, else `\n`. */
+function detectEol(text) {
+	const crlf = text.match(/\r\n/g)?.length ?? 0;
+	return crlf > (text.match(/\n/g)?.length ?? 0) - crlf ? "\r\n" : "\n";
+}
+/**
+* Inserts or replaces a block of lines delimited by marker lines, leaving
+* everything outside it untouched.
+*
+* - Block present (`start` … `end`): replaced in place.
+* - No block: appended, separated from existing content by a blank line, with a
+*   single trailing newline.
+* - `start` present but `end` missing (hand-edited or truncated): the block is
+*   taken to run to the next blank line, or to the end of the file — so the
+*   content after it is kept, not lost. An `end` marker only closes the block
+*   when it comes before that blank line; one further down is left alone.
+*
+* Line endings follow the existing text (`\r\n` when it mostly uses them), so
+* a CRLF file stays CRLF. That is also why `lines` can't contain blank lines: a
+* blank line is how an unterminated block is told apart from the next section.
+*
+* Idempotent: calling it again with the same options returns the same text.
+* There are no default markers; callers choose them, and must keep them stable
+* so existing blocks are still found.
+*
+* @throws {TypeError} when an entry in `lines` is blank or contains a line break.
+*/
+function upsertManagedBlock(content, { start, end, lines }) {
+	for (const line of lines) if (line.trim() === "" || /[\r\n]/.test(line)) throw new TypeError(`Managed block lines must be non-blank single lines, got ${JSON.stringify(line)}`);
+	const eol = detectEol(content);
+	const block = [
+		start,
+		...lines,
+		end
+	].join(eol);
+	const startAt = content.indexOf(start);
+	if (startAt === -1) {
+		const base = content.trimEnd();
+		return (base ? `${base}${eol}${eol}` : "") + `${block}${eol}`;
+	}
+	const boundary = BLANK_LINE.exec(content.slice(startAt));
+	const boundaryAt = boundary ? startAt + boundary.index : -1;
+	const endAt = content.indexOf(end, startAt);
+	if (endAt !== -1 && (boundaryAt === -1 || endAt < boundaryAt)) return content.slice(0, startAt) + block + content.slice(endAt + end.length);
+	return content.slice(0, startAt) + block + (boundaryAt === -1 ? eol : content.slice(boundaryAt));
+}
+/** Updates in flight, per file: a second call for the same path waits for the first. */
+const queues = /* @__PURE__ */ new Map();
+function serialized(key, task) {
+	const result = (queues.get(key) ?? Promise.resolve()).then(task, task);
+	const tail = result.catch(() => void 0);
+	queues.set(key, tail);
+	tail.then(() => {
+		if (queues.get(key) === tail) queues.delete(key);
+	});
+	return result;
+}
+async function readIfExists(path) {
+	try {
+		return await readFile(path, "utf8");
+	} catch (err) {
+		if (err.code === "ENOENT") return "";
+		throw err;
+	}
+}
+/** Writes `path` by renaming a finished temp file over it, so a failure never leaves it truncated. */
+async function writeAtomic(path, text) {
+	const mode = await stat(path).then((s) => s.mode & 511, () => void 0);
+	const tmp = join(dirname(path), `.${randomBytes(6).toString("hex")}.tmp`);
+	try {
+		await writeFile(tmp, text, "utf8");
+		if (mode !== void 0) await chmod(tmp, mode);
+		await rename(tmp, path);
+	} catch (err) {
+		await unlink(tmp).catch(() => void 0);
+		throw err;
+	}
+}
+/**
+* {@link upsertManagedBlock} applied to a file (a missing file counts as empty,
+* and is created). Writes only when the content changes, and atomically (a
+* temp file renamed into place; a symlinked path is updated through the link).
+* Resolves to `true` when it wrote.
+*
+* Calls for the same path within one process run one after another, each
+* reading the file as the previous left it. Separate processes aren't
+* coordinated. Any read error other than "no such file" rejects, rather than
+* being mistaken for an empty file and overwritten.
+*/
+async function updateGitignore(path, options) {
+	const target = await realpath(path).catch(() => path);
+	return serialized(target, async () => {
+		const existing = await readIfExists(target);
+		const updated = upsertManagedBlock(existing, options);
+		if (updated === existing) return false;
+		await writeAtomic(target, updated);
+		return true;
+	});
+}
+//#endregion
+//#region src/remote.ts
+/**
+* Parses a git remote URL — any host, any of the common shapes:
+*
+* - `https://github.com/owner/repo(.git)(/)`, with optional credentials or port
+* - `git@github.com:owner/repo(.git)` (scp-style SSH)
+* - `ssh://git@github.com(:22)/owner/repo(.git)`
+* - `git://github.com/owner/repo.git`
+*
+* A bracketed IPv6 host is returned without its brackets. The whole input must
+* be one remote: trailing text after the URL (apart from a `?query` or
+* `#fragment`) makes it `undefined`.
+*
+* `undefined` for anything else (a local path, an empty string, a URL with
+* fewer than two path segments).
+*/
+function parseGitRemoteUrl(url) {
+	const input = url.trim();
+	const withScheme = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/\s]*@)?(\[[0-9a-f:.]+\]|[^:/\s]+)(?::\d+)?\/([^\s?#]+)(?:[?#]\S*)?$/i.exec(input);
+	const scp = withScheme ? null : /^(?:[^@/\s]+@)?(\[[0-9a-f:.]+\]|[^:/\s]{2,}):(?!\/\/)([^\s]+)$/i.exec(input);
+	const match = withScheme ?? scp;
+	if (!match) return void 0;
+	const host = match[1].replace(/^\[|\]$/g, "");
+	const segments = match[2].split("/").filter(Boolean);
+	const last = segments.pop().replace(/\.git$/, "");
+	if (last) segments.push(last);
+	if (segments.length < 2) return void 0;
+	const repo = segments[segments.length - 1];
+	const owner = segments.slice(0, -1).join("/");
+	return {
+		host,
+		owner,
+		repo,
+		slug: `${owner}/${repo}`
+	};
+}
+const defaultExec = async (args, { cwd }) => {
+	const [{ execFile }, { promisify }] = await Promise.all([import("node:child_process"), import("node:util")]);
+	return (await promisify(execFile)("git", args, { cwd })).stdout;
+};
+/**
+* The parsed URL of a repository's remote (`git remote get-url <remote>`), or
+* `undefined` when `cwd` isn't a repository, has no such remote, git isn't
+* installed, or the URL isn't one {@link parseGitRemoteUrl} understands.
+*/
+async function readGitRemote(cwd, options = {}) {
+	const exec = options.exec ?? defaultExec;
+	try {
+		return parseGitRemoteUrl(await exec([
+			"remote",
+			"get-url",
+			options.remote ?? "origin"
+		], { cwd }));
+	} catch {
+		return;
+	}
+}
+//#endregion
+export { parseGitRemoteUrl, readGitRemote, updateGitignore, upsertManagedBlock };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/git-utils",
-  "version": "1.9.2",
+  "version": "1.10.0",
   "description": "Parse git remote URLs, read a repo's remote, and maintain managed blocks in .gitignore.",
   "keywords": [
     "git",