@devframes/service-git 0.9.4 → 0.9.5

package/dist/index.d.mts

@@ -56,6 +56,8 @@ interface LogArgs {
   skip?: number;
   /** Optional ref/branch to read history from (default: current HEAD). */
   ref?: string;
+  /** Restrict history to commits that touched these repo-relative path(s). */
+  paths?: string[];
 }
 interface Branch {
   name: string;
@@ -73,6 +75,47 @@ interface GitBranches {
   current: string | null;
   branches: Branch[];
 }
+interface Tag {
+  name: string;
+  /** Short SHA of the commit the tag ultimately points to. */
+  sha: string;
+  /**
+   * Tag creation date as epoch milliseconds — the tag's own date for
+   * annotated tags, the target commit's date for lightweight tags. `0` when
+   * the date can't be parsed.
+   */
+  date: number;
+  /** Tag message subject (annotated) or target commit subject (lightweight). */
+  subject: string;
+  /** `true` for annotated tags, which carry their own message and date. */
+  annotated: boolean;
+}
+interface GitTags {
+  isRepo: boolean;
+  /** Tags, newest creation date first. */
+  tags: Tag[];
+}
+interface ReadFileArgs {
+  /** Repo-relative path to the file. */
+  path: string;
+  /** Commit-ish to read the file from (default: current HEAD). */
+  ref?: string;
+}
+interface GitFile {
+  /** `false` when the working directory is not inside a git repository. */
+  isRepo: boolean;
+  /** `false` when no blob exists at `path` for `ref`. */
+  found: boolean;
+  /** The resolved ref the file was read from. */
+  ref: string;
+  path: string;
+  /** File text, or `null` when not found or binary. */
+  content: string | null;
+  /** `true` when the blob is binary (its `content` is omitted). */
+  binary: boolean;
+  /** `true` when `content` was clipped to the internal char limit. */
+  truncated: boolean;
+}
 interface DiffFile {
   path: string;
   additions: number;
@@ -165,8 +208,10 @@ interface GitServiceApi {
   status: () => Promise<GitStatus>;
   log: (args?: LogArgs) => Promise<GitLog>;
   show: (args: ShowArgs) => Promise<CommitDetail>;
+  readFile: (args: ReadFileArgs) => Promise<GitFile>;
   diff: (args?: DiffArgs) => Promise<GitDiff>;
   branches: () => Promise<GitBranches>;
+  tags: () => Promise<GitTags>;
   stage: (args: StageArgs) => Promise<GitStatus>;
   unstage: (args: UnstageArgs) => Promise<GitStatus>;
   commit: (args: CommitArgs) => Promise<CommitResult>;
@@ -187,8 +232,10 @@ declare module 'devframe' {
     'devframes:service:git:status': () => Promise<GitStatus>;
     'devframes:service:git:log': (args?: LogArgs) => Promise<GitLog>;
     'devframes:service:git:show': (args: ShowArgs) => Promise<CommitDetail>;
+    'devframes:service:git:readFile': (args: ReadFileArgs) => Promise<GitFile>;
     'devframes:service:git:diff': (args?: DiffArgs) => Promise<GitDiff>;
     'devframes:service:git:branches': () => Promise<GitBranches>;
+    'devframes:service:git:tags': () => Promise<GitTags>;
     'devframes:service:git:stage': (args: StageArgs) => Promise<GitStatus>;
     'devframes:service:git:unstage': (args: UnstageArgs) => Promise<GitStatus>;
     'devframes:service:git:commit': (args: CommitArgs) => Promise<CommitResult>;
@@ -211,4 +258,4 @@ declare module 'devframe' {
  */
 declare function createGitService(options?: GitServiceOptions): DevframeServiceDefinition<GitServiceApi, GitServiceOptions>;
 //#endregion
-export { Branch, Commit, CommitArgs, CommitDetail, CommitFile, CommitResult, DiffArgs, DiffFile, FileStatusCode, GIT_SERVICE_PACKAGE, GIT_SERVICE_SCOPE, GitBranches, GitDiff, GitLog, GitServiceApi, GitServiceOptions, GitStatus, LogArgs, ShowArgs, StageArgs, StatusFileEntry, UnstageArgs, createGitService, createGitService as default };
+export { Branch, Commit, CommitArgs, CommitDetail, CommitFile, CommitResult, DiffArgs, DiffFile, FileStatusCode, GIT_SERVICE_PACKAGE, GIT_SERVICE_SCOPE, GitBranches, GitDiff, GitFile, GitLog, GitServiceApi, GitServiceOptions, GitStatus, GitTags, LogArgs, ReadFileArgs, ShowArgs, StageArgs, StatusFileEntry, Tag, UnstageArgs, createGitService, createGitService as default };

package/dist/index.mjs

@@ -4,7 +4,7 @@ import { execFile } from "node:child_process";
 import process from "node:process";
 import { promisify } from "node:util";
 //#region package.json
-var version = "0.9.4";
+var version = "0.9.5";
 //#endregion
 //#region src/git.ts
 const execFileAsync = promisify(execFile);
@@ -66,6 +66,8 @@ function gitErrorMessage(error) {
 //#region src/operations.ts
 /** Hard cap on returned patch text to keep payloads bounded. */
 const PATCH_CHAR_LIMIT = 2e5;
+/** Hard cap on returned raw file content to keep payloads bounded. */
+const FILE_CHAR_LIMIT = 5e5;
 const EMPTY_STATUS = {
 	isRepo: false,
 	root: null,
@@ -203,6 +205,14 @@ const BRANCH_FORMAT = [
 	"%(upstream:track)",
 	"%(contents:subject)"
 ].join("");
+const TAG_FORMAT = [
+	"%(refname:short)",
+	"%(objecttype)",
+	"%(objectname:short)",
+	"%(*objectname:short)",
+	"%(creatordate:iso-strict)",
+	"%(contents:subject)"
+].join("");
 function parseTrack(track) {
 	if (track.includes("gone")) return {
 		ahead: 0,
@@ -299,15 +309,22 @@ function parseCommitNumstat(raw, status) {
 		};
 	});
 }
-function clipPatch(raw) {
-	return raw.length > PATCH_CHAR_LIMIT ? {
-		patch: raw.slice(0, PATCH_CHAR_LIMIT),
+function clipText(raw, limit) {
+	return raw.length > limit ? {
+		text: raw.slice(0, limit),
 		truncated: true
 	} : {
-		patch: raw,
+		text: raw,
 		truncated: false
 	};
 }
+function clipPatch(raw) {
+	const { text, truncated } = clipText(raw, PATCH_CHAR_LIMIT);
+	return {
+		patch: text,
+		truncated
+	};
+}
 /**
 * Build the git node API bound to a single working directory, with the repo
 * root resolved once (memoized). This is the surface returned to in-process
@@ -431,6 +448,8 @@ function createGitOps(cwd) {
 				};
 				command.push("--end-of-options", ref);
 			}
+			const paths = (args.paths ?? []).map((p) => p.trim()).filter(Boolean);
+			if (paths.length > 0) command.push("--", ...paths);
 			const raw = await tryGit(cwd, command);
 			const commits = raw ? parseLog(raw) : [];
 			return {
@@ -447,6 +466,44 @@ function createGitOps(cwd) {
 			if (!await resolveRoot() || !hash) return { ...EMPTY_DETAIL };
 			return readCommit(hash, includePatch);
 		},
+		async readFile(args) {
+			const path = (args?.path ?? "").trim();
+			const ref = args?.ref?.trim() || "HEAD";
+			const root = await resolveRoot();
+			const base = {
+				isRepo: !!root,
+				found: false,
+				ref,
+				path,
+				content: null,
+				binary: false,
+				truncated: false
+			};
+			if (!root || !path) return base;
+			if (!isSafeRevision(ref)) return base;
+			let raw;
+			try {
+				({stdout: raw} = await runGit(cwd, [
+					"show",
+					"--end-of-options",
+					`${ref}:${path}`
+				]));
+			} catch {
+				return base;
+			}
+			if (raw.includes("\0")) return {
+				...base,
+				found: true,
+				binary: true
+			};
+			const { text: content, truncated } = clipText(raw, FILE_CHAR_LIMIT);
+			return {
+				...base,
+				found: true,
+				content,
+				truncated
+			};
+		},
 		async diff(args = {}) {
 			const { path, staged = false } = args;
 			if (!await resolveRoot()) return {
@@ -521,6 +578,38 @@ function createGitOps(cwd) {
 				branches
 			};
 		},
+		async tags() {
+			if (!await resolveRoot()) return {
+				isRepo: false,
+				tags: []
+			};
+			const raw = await tryGit(cwd, [
+				"for-each-ref",
+				`--format=${TAG_FORMAT}`,
+				"refs/tags"
+			]);
+			if (!raw) return {
+				isRepo: true,
+				tags: []
+			};
+			const tags = splitClean(raw, "\n").map((line) => {
+				const [name, objectType, objectSha, targetSha, isoDate, subject] = line.split("");
+				const annotated = objectType === "tag";
+				const parsed = Date.parse(isoDate);
+				return {
+					name,
+					sha: targetSha || objectSha,
+					date: Number.isNaN(parsed) ? 0 : parsed,
+					subject: subject ?? "",
+					annotated
+				};
+			});
+			tags.sort((a, b) => b.date - a.date);
+			return {
+				isRepo: true,
+				tags
+			};
+		},
 		async stage(args) {
 			const paths = args?.paths ?? [];
 			if (await resolveRoot() && paths.length > 0) await runGit(cwd, [
@@ -640,6 +729,15 @@ const commitDetailSchema = s.object({
 	patch: s.nullable(s.string()),
 	truncated: s.boolean()
 });
+const gitFileSchema = s.object({
+	isRepo: s.boolean(),
+	found: s.boolean(),
+	ref: s.string(),
+	path: s.string(),
+	content: s.nullable(s.string()),
+	binary: s.boolean(),
+	truncated: s.boolean()
+});
 const gitDiffSchema = s.object({
 	isRepo: s.boolean(),
 	staged: s.boolean(),
@@ -689,12 +787,13 @@ function createGitService(options) {
 				args: [s.object({
 					limit: s.optional(s.number()),
 					skip: s.optional(s.number()),
-					ref: s.optional(s.string())
+					ref: s.optional(s.string()),
+					paths: s.optional(s.array(s.string()))
 				})],
 				returns: gitLogSchema,
 				agent: {
 					title: "Git log",
-					description: "Commit history of the inspected repository, newest first. Paginate with limit (1-200, default 30) and skip; pass ref to read another branch. Safe to call freely."
+					description: "Commit history of the inspected repository, newest first. Paginate with limit (1-200, default 30) and skip; pass ref to read another branch, or paths to list only commits that touched those files/directories. Safe to call freely."
 				},
 				handler: (args = {}) => ops.log(args)
 			}));
@@ -713,6 +812,21 @@ function createGitService(options) {
 				},
 				handler: (args) => ops.show(args)
 			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "readFile",
+				type: "query",
+				jsonSerializable: true,
+				args: [s.object({
+					path: s.string(),
+					ref: s.optional(s.string())
+				})],
+				returns: gitFileSchema,
+				agent: {
+					title: "Git read file",
+					description: "Read the contents of a single file at a commit-ish (default HEAD) — the raw text of a versioned file without checking it out. found is false when no such file exists at the ref; binary blobs return with content omitted. Safe to call freely."
+				},
+				handler: (args) => ops.readFile(args)
+			}));
 			ctx.rpc.register(defineRpcFunction({
 				name: "diff",
 				type: "query",
@@ -738,6 +852,16 @@ function createGitService(options) {
 				},
 				handler: () => ops.branches()
 			}));
+			ctx.rpc.register(defineRpcFunction({
+				name: "tags",
+				type: "query",
+				jsonSerializable: true,
+				agent: {
+					title: "Git tags",
+					description: "List tags (newest first) with the target commit SHA, creation date, and message subject; annotated tags are flagged. Safe to call freely."
+				},
+				handler: () => ops.tags()
+			}));
 			ctx.rpc.register(defineRpcFunction({
 				name: "stage",
 				type: "action",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@devframes/service-git",
   "type": "module",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "description": "Devframe wire service exposing read/write git operations (status, log, show, diff, branches, stage, unstage, commit) over RPC.",
   "author": "Anthony Fu <anthonyfu117@hotmail.com>",
   "license": "MIT",
@@ -28,13 +28,13 @@
     "dist"
   ],
   "peerDependencies": {
-    "devframe": "0.9.4"
+    "devframe": "0.9.5"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "tsdown": "^0.22.14",
     "vitest": "^4.1.10",
-    "devframe": "0.9.4"
+    "devframe": "0.9.5"
   },
   "scripts": {
     "build": "tsdown",