@feng0531/dsh-vcs 0.3.23 → 0.3.35

package/git-history.mjs

@@ -0,0 +1,75 @@
+// Each line-porcelain record carries its own metadata; never interpret filename as an access path.
+export function parseBlame(text,maxLines=500){
+ if(typeof text!=='string'||Buffer.byteLength(text,'utf8')>2*1024*1024)throw new Error('Invalid blame output size');
+ if(!Number.isInteger(maxLines)||maxLines<1||maxLines>500)throw new Error('Invalid blame line limit');
+ if(!text)return [];
+ if(!text.endsWith('\n'))throw new Error('Truncated blame output');
+ const fields=text.slice(0,-1).split('\n'),rows=[];
+ for(let i=0;i<fields.length;){
+  const header=/^([a-f0-9]{40}|[a-f0-9]{64}) ([1-9][0-9]*) ([1-9][0-9]*)(?: ([1-9][0-9]*))?$/.exec(fields[i++]);
+  if(!header)throw new Error('Invalid blame header');
+  const originalLine=Number(header[2]),line=Number(header[3]);
+  if(!Number.isSafeInteger(originalLine)||!Number.isSafeInteger(line)||(rows.length&&line!==rows.at(-1).line+1))throw new Error('Invalid blame line sequence');
+  const metadata={};
+  while(i<fields.length&&!fields[i].startsWith('	')){
+   const item=fields[i++],space=item.indexOf(' '),key=space<0?item:item.slice(0,space),value=space<0?'':item.slice(space+1);
+   if(['author','author-time','author-tz','summary','filename'].includes(key)){
+    if(Object.hasOwn(metadata,key))throw new Error('Duplicate blame metadata');metadata[key]=value;
+   }
+  }
+  if(i===fields.length||!['author','author-time','author-tz','summary','filename'].every(k=>Object.hasOwn(metadata,k)))throw new Error('Incomplete blame record');
+  if(!/^-?[0-9]+$/.test(metadata['author-time'])||!Number.isSafeInteger(Number(metadata['author-time']))||! /^[+-][0-9]{4}$/.test(metadata['author-tz']))throw new Error('Invalid blame timestamp');
+  rows.push({commit:header[1],originalLine,line,author:metadata.author,authorTime:Number(metadata['author-time']),authorTimezone:metadata['author-tz'],summary:metadata.summary,text:fields[i++].slice(1)});
+  if(rows.length>maxLines)throw new Error('Blame line limit exceeded');
+ }
+ return rows;
+}
+// for-each-ref adds LF after each NUL-delimited record; ref names cannot contain LF.
+export const REFS_FORMAT='%(refname)%00%(objecttype)%00%(objectname)%00%(*objecttype)%00%(*objectname)%00';
+export function parseReferences(text){
+ if(typeof text!=='string'||Buffer.byteLength(text,'utf8')>2*1024*1024)throw Error('Invalid reference output size');
+ if(!text)return [];
+ if(!text.endsWith('\n'))throw Error('Truncated reference output');
+ const lines=text.slice(0,-1).split('\n');if(lines.length>1000)throw Error('Reference count exceeds limit');
+ const seen=new Set(),result=[];
+ for(const line of lines){
+  const fields=line.split('\0');if(fields.length!==6||fields[5]!=='')throw Error('Invalid reference framing');
+  const [name,type,id,peeledType,peeled]=fields;
+  const prefix=name.startsWith('refs/heads/')?'refs/heads/':name.startsWith('refs/tags/')?'refs/tags/':null;
+  if(!prefix||seen.has(name)||name.length>1024)throw Error('Invalid reference name');
+  const short=name.slice(prefix.length);
+  if(!short||short.endsWith('.')||short.includes('..')||short.includes('@{')||[...short].some(c=>c.charCodeAt(0)<=32||c.charCodeAt(0)===127||'~^:?*['.includes(c)||c===String.fromCharCode(92))||short.split('/').some(p=>!p||p.startsWith('.')||p.endsWith('.lock')))throw Error('Invalid reference name');
+  seen.add(name);
+  if(!oid(id)||!['commit','tag','tree','blob'].includes(type)||Boolean(peeledType)!==Boolean(peeled)||(peeled&&(!oid(peeled)||peeled.length!==id.length||!['commit','tag','tree','blob'].includes(peeledType))))throw Error('Invalid reference object');
+  if(type!=='tag'&&peeled)throw Error('Unexpected peeled object');
+  const commit=type==='commit'?id:type==='tag'&&peeledType==='commit'?peeled:null;
+  if(commit)result.push({name,shortName:short,kind:prefix==='refs/heads/'?'branch':'tag',commit});
+ }
+ return result;
+}
+
+// Format for: git log -z --format=<HISTORY_FORMAT>. NUL separates fields/records.
+export const HISTORY_FORMAT = '%H%x00%P%x00%an%x00%aI%x00%s';
+const oid = value => /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value);
+export function historyPage(rows,snapshot,offset,limit){
+ const hasMore=rows.length>limit;
+ const truncated=hasMore&&offset+limit>10000;
+ return {snapshot,commits:rows.slice(0,limit),nextOffset:hasMore&&!truncated?offset+limit:null,truncated};
+}
+export function parseHistory(text, maxRecords = 101) {
+  if(typeof text !== 'string' || Buffer.byteLength(text,'utf8') > 2*1024*1024) throw new Error('History output exceeds limit or is invalid');
+  if(!Number.isInteger(maxRecords)||maxRecords<1||maxRecords>101) throw new Error('Invalid history record limit');
+  if(!text) return [];
+  if(!text.endsWith('\0')) throw new Error('Truncated history output');
+  const fields=text.slice(0,-1).split('\0');
+  if(fields.length%5 || fields.length/5>maxRecords) throw new Error('Invalid history field count or record limit');
+  const result=[];
+  for(let i=0;i<fields.length;i+=5){
+    const [id,parentText,author,date,subject]=fields.slice(i,i+5);
+    const parents=parentText?parentText.split(' '):[];
+    if(!oid(id)||parents.some(p=>!oid(p)||p.length!==id.length)) throw new Error('Invalid history object id');
+    if(!/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:Z|[+-][0-9]{2}:[0-9]{2})$/.test(date)||!Number.isFinite(Date.parse(date))) throw new Error('Invalid history timestamp');
+    result.push({id,parents,author,date,subject});
+  }
+  return result;
+}

package/image-preview.mjs

@@ -0,0 +1,86 @@
+import {inflate} from 'node:zlib';
+import {promisify} from 'node:util';
+const inflateAsync=promisify(inflate);
+// Structural gate only. Pixel decoding must still succeed before display.
+export function inspectPng(buffer){
+ if(!Buffer.isBuffer(buffer)||buffer.length>2*1024*1024)throw new Error('Image byte limit exceeded or invalid input');
+ if(buffer.length<8||!buffer.subarray(0,8).equals(Buffer.from([137,80,78,71,13,10,26,10])))throw new Error('Only PNG is supported');
+ let offset=8,width,height,depth,color,paletteSize=0,seenTransparency=false,seenPalette=false,seenData=false,endedData=false,ended=false,chunks=0;
+ while(offset<buffer.length){
+  if(++chunks>4096||buffer.length-offset<12)throw new Error('Invalid PNG chunk bounds');
+  const length=buffer.readUInt32BE(offset),end=offset+12+length;
+  if(end>buffer.length)throw new Error('Truncated PNG chunk');
+  const type=buffer.toString('ascii',offset+4,offset+8);
+  if(!buffer.subarray(offset+4,offset+8).every(b=>(b>=65&&b<=90)||(b>=97&&b<=122)))throw new Error('Invalid PNG chunk type');
+  if(buffer[offset+6]&32)throw new Error('Invalid PNG reserved chunk bit');
+  let crc=0xffffffff;
+  for(const byte of buffer.subarray(offset+4,end-4)){crc^=byte;for(let bit=0;bit<8;bit++)crc=(crc>>>1)^((crc&1)?0xedb88320:0);}
+  if(((crc^0xffffffff)>>>0)!==buffer.readUInt32BE(end-4))throw new Error('Invalid PNG CRC');
+  if(chunks===1&&type!=='IHDR')throw new Error('PNG header must be first');
+  if(type==='IHDR'){
+   if(chunks!==1||length!==13)throw new Error('Invalid PNG header');
+   width=buffer.readUInt32BE(offset+8);height=buffer.readUInt32BE(offset+12);
+   if(!width||!height||width>8192||height>8192||width*height>16000000)throw new Error('Image dimensions exceed limit');
+   depth=buffer[offset+16];color=buffer[offset+17];
+   if(!({0:[1,2,4,8,16],2:[8,16],3:[1,2,4,8],4:[8,16],6:[8,16]}[color]?.includes(depth))||buffer[offset+18]!==0||buffer[offset+19]!==0||buffer[offset+20]>1)throw new Error('Invalid PNG encoding');
+  }else if(type==='PLTE'){
+   if(seenPalette||seenTransparency||seenData||color===0||color===4||!length||length%3||length>768||(color===3&&length/3>2**depth))throw new Error('Invalid PNG palette');
+   seenPalette=true;paletteSize=length/3;
+  }else if(type==='tRNS'){
+   if(seenTransparency||seenData||![0,2,3].includes(color)||(color===0&&length!==2)||(color===2&&length!==6)||(color===3&&(!seenPalette||!length||length>paletteSize)))throw new Error('Invalid PNG transparency');
+   if(color!==3)for(let i=0;i<length;i+=2)if(buffer.readUInt16BE(offset+8+i)>=2**depth)throw new Error('Invalid PNG transparent sample');
+   seenTransparency=true;
+  }else if(type==='IDAT'){
+   if(color===3&&!seenPalette)throw new Error('Missing PNG palette');
+   if(endedData)throw new Error('Noncontiguous PNG data');seenData=true;
+  }else{
+   if(seenData)endedData=true;
+   if(type==='IEND'){if(length||!seenData||end!==buffer.length)throw new Error('Invalid PNG end');ended=true;}
+   else if(['iCCP','zTXt','iTXt'].includes(type))throw new Error('Compressed or international PNG metadata is unsupported');
+   else if(['acTL','fcTL','fdAT'].includes(type))throw new Error('Animated PNG is unsupported');
+   else if(type[0]===type[0].toUpperCase()&&type!=='PLTE')throw new Error('Unknown critical PNG chunk');
+  }
+  offset=end;
+ }
+ if(!ended)throw new Error('Missing PNG end');
+ return {mime:'image/png',width,height,bytes:buffer.length};
+}
+
+// Stripping color metadata makes this unsuitable for color-critical review.
+export async function preparePng(buffer,options){
+ const metadata=await validatePng(buffer,options),parts=[buffer.subarray(0,8)];
+ for(let offset=8;offset<buffer.length;){
+  const length=buffer.readUInt32BE(offset),end=offset+length+12,type=buffer.toString("ascii",offset+4,offset+8);
+  if(["IHDR","PLTE","tRNS","IDAT","IEND"].includes(type))parts.push(buffer.subarray(offset,end));
+  offset=end;
+ }
+ options?.signal?.throwIfAborted();
+ const data=Buffer.concat(parts);
+ return {...metadata,bytes:data.length,originalBytes:metadata.bytes,data,metadataStripped:data.length!==buffer.length};
+}
+
+// Fail fast instead of retaining an unbounded queue of image buffers.
+let activeValidations=0;
+export async function validatePng(buffer,{signal}={}){
+ signal?.throwIfAborted();
+ if(activeValidations>=2)throw Object.assign(new Error('Image validation busy; retry shortly'),{code:'IMAGE_BUSY'});
+ activeValidations++;
+ try{return await validatePngStream(buffer,{signal});}finally{activeValidations--;}
+}
+async function validatePngStream(buffer,{signal}){
+ signal?.throwIfAborted();
+ const metadata=inspectPng(buffer);
+ const depth=buffer[24],color=buffer[25];
+ if(buffer[28]!==0)throw new Error('Interlaced PNG is unsupported');
+ const channels={0:1,2:3,3:1,4:2,6:4}[color],stride=Math.ceil(metadata.width*channels*depth/8)+1;
+ const expected=stride*metadata.height;
+ if(expected>64*1024*1024)throw new Error('PNG decoded byte limit exceeded');
+ const parts=[];
+ for(let offset=8;offset<buffer.length;){const length=buffer.readUInt32BE(offset);if(buffer.toString('ascii',offset+4,offset+8)==='IDAT')parts.push(buffer.subarray(offset+8,offset+8+length));offset+=length+12;}
+ const compressed=Buffer.concat(parts);
+ const result=await inflateAsync(compressed,{maxOutputLength:expected,info:true,signal});
+ signal?.throwIfAborted();
+ if(result.engine.bytesWritten!==compressed.length||result.buffer.length!==expected)throw new Error('Invalid PNG decoded length');
+ for(let row=0;row<metadata.height;row++)if(result.buffer[row*stride]>4)throw new Error('Invalid PNG row filter');
+ return metadata;
+}

package/index.mjs

@@ -24,7 +24,7 @@ const rediscover = () => Object.assign(new Error('Repository authorization is mi
 
 function validatePayload(endpoint, payload) {
   if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw invalid('An object payload is required.');
-  const fields = endpoint === 'vcs/repositories' ? ['sessionId', 'subdirectory'] : ['sessionId', 'repositoryId', 'mode', ...(endpoint === 'vcs/compare' ? ['id'] : [])];
+  const fields = endpoint==='vcs/references'?['sessionId','repositoryId'] : endpoint==='vcs/commit-image'?['sessionId','repositoryId','commit','parentIndex','id','side'] : endpoint==='vcs/tree'?['sessionId','repositoryId','commit'] : endpoint==='vcs/file-history'?['sessionId','repositoryId','commit','parentIndex','id','offset','limit'] : ['vcs/revision-changes','vcs/revision-compare'].includes(endpoint) ? ['sessionId','repositoryId','base','target',...(endpoint==='vcs/revision-compare'?['id']:[])] : ['vcs/commit-compare','vcs/blame'].includes(endpoint) ? ['sessionId','repositoryId','commit','parentIndex','id'] : endpoint === 'vcs/commit' ? ['sessionId','repositoryId','commit','parentIndex'] : endpoint === 'vcs/history' ? ['sessionId','repositoryId','snapshot','offset','limit'] : endpoint === 'vcs/repositories' ? ['sessionId', 'subdirectory'] : ['sessionId', 'repositoryId', 'mode', ...(endpoint === 'vcs/compare' ? ['id'] : [])];
   if (Object.keys(payload).some(key => !fields.includes(key))) throw invalid('Only Session-addressed repository requests are supported; unknown payload field.');
   if (endpoint === 'vcs/repositories') {
     if (payload.subdirectory !== undefined) {
@@ -33,6 +33,21 @@ function validatePayload(endpoint, payload) {
     }
   } else {
     if (typeof payload.repositoryId !== 'string' || !payload.repositoryId || payload.repositoryId.length > 1024) throw invalid('A discovered repositoryId is required.');
+    if(endpoint==='vcs/commit-image'&&payload.side!==undefined&&!['left','right'].includes(payload.side))throw invalid('Invalid image side.');
+    if(['vcs/revision-changes','vcs/revision-compare'].includes(endpoint)){
+      for(const oid of [payload.base,payload.target])if(typeof oid!=='string'||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(oid))throw invalid('Invalid revision commit id.');
+      if(endpoint==='vcs/revision-compare'&&(typeof payload.id!=='string'||!/^[a-f0-9]{64}$/.test(payload.id)))throw invalid('Invalid revision change id.');
+    }
+    if(['vcs/commit-compare','vcs/file-history','vcs/blame','vcs/commit-image'].includes(endpoint)&&(typeof payload.id!=='string'||!/^[a-f0-9]{64}$/.test(payload.id)))throw invalid('Invalid historical change id.');
+    if(['vcs/commit','vcs/commit-compare','vcs/file-history','vcs/blame','vcs/tree','vcs/commit-image'].includes(endpoint)){
+      if(typeof payload.commit!=='string'||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(payload.commit))throw invalid('Invalid commit id.');
+      if(payload.parentIndex!==undefined&&(!Number.isInteger(payload.parentIndex)||payload.parentIndex<0||payload.parentIndex>100))throw invalid('Invalid parent index.');
+    }
+    if(['vcs/history','vcs/file-history'].includes(endpoint)){
+      if(payload.offset===null||payload.limit===null)throw invalid('Invalid history pagination.');
+      if(payload.snapshot!==undefined&&(typeof payload.snapshot!=='string'||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(payload.snapshot)))throw invalid('Invalid history snapshot.');
+      if(!Number.isInteger(payload.offset??0)||(payload.offset??0)<0||(payload.offset??0)>10000||!Number.isInteger(payload.limit??50)||(payload.limit??50)<1||(payload.limit??50)>100)throw invalid('Invalid history pagination.');
+    }
     if (!['all', 'unstaged', 'staged'].includes(payload.mode ?? 'all')) throw invalid('Unsupported comparison mode.');
     if (endpoint === 'vcs/compare' && (typeof payload.id !== 'string' || !payload.id || payload.id.length > 32768)) throw invalid('A change id is required.');
   }
@@ -40,7 +55,7 @@ function validatePayload(endpoint, payload) {
 
 /** Limit active adapter operations and retain only bounded, short-lived discovery grants. */
 export function createHandler(ctx, api = adapter, maxActive = 4, { now = Date.now, ttlMs = 5 * 60_000, maxSessions = 32, maxRepositories = 512 } = {}) {
-  let active = 0;
+  let active = 0, activeImages = 0;
   const sessions = new Map();
   function current(sessionId, cwd) {
     for (const [id, entry] of sessions) if (entry.expiresAt <= now()) sessions.delete(id);
@@ -54,9 +69,10 @@ export function createHandler(ctx, api = adapter, maxActive = 4, { now = Date.no
     if (current(sessionId, latest) !== entry || latest !== cwd) throw rediscover();
   }
   return async (endpoint, payload, signal) => {
-    if (!['vcs/repositories', 'vcs/status', 'vcs/compare'].includes(endpoint)) return failure('vcs/not-found', 'Unknown VCS endpoint.');
+    if (!['vcs/repositories', 'vcs/status', 'vcs/compare', 'vcs/history', 'vcs/commit', 'vcs/commit-compare', 'vcs/revision-changes', 'vcs/revision-compare', 'vcs/file-history', 'vcs/blame', 'vcs/tree', 'vcs/commit-image', 'vcs/references'].includes(endpoint)) return failure('vcs/not-found', 'Unknown VCS endpoint.');
     if (active >= maxActive) return failure('vcs/busy', 'Too many VCS requests. Please retry.');
     active++;
+    let imageSlot=false;
     try {
       signal?.throwIfAborted();
       validatePayload(endpoint, payload);
@@ -99,7 +115,32 @@ export function createHandler(ctx, api = adapter, maxActive = 4, { now = Date.no
       if (repository.type === 'svn' && mode !== 'all') throw invalid('SVN supports only all mode.');
       // Both adapter operations revalidate the canonical root; comparison also validates
       // the change ID against fresh status, so do not duplicate a full status scan here.
-      const value = endpoint === 'vcs/status'
+      if(['vcs/history','vcs/commit','vcs/commit-compare','vcs/revision-changes','vcs/revision-compare','vcs/file-history','vcs/blame','vcs/tree','vcs/commit-image','vcs/references'].includes(endpoint)&&repository.type!=='git')throw invalid('History currently supports Git only.');
+      if(endpoint==='vcs/commit-image'){
+        if(activeImages>=2)return failure('vcs/busy','Too many image requests. Please retry.');
+        activeImages++;imageSlot=true;
+      }
+      const value = endpoint === 'vcs/references'
+        ? await api.listReferences({...repository},{signal})
+        : endpoint === 'vcs/commit-image'
+        ? await api.getCommitImage({...repository},{commit:payload.commit,parentIndex:payload.parentIndex??0,id:payload.id,side:payload.side??'right',signal})
+        : endpoint === 'vcs/tree'
+        ? await api.getHistoricalTree({...repository},{commit:payload.commit,signal})
+        : endpoint === 'vcs/blame'
+        ? await api.getFileBlame({...repository},{commit:payload.commit,parentIndex:payload.parentIndex??0,id:payload.id,signal})
+        : endpoint === 'vcs/file-history'
+        ? await api.listFileHistory({...repository},{commit:payload.commit,parentIndex:payload.parentIndex??0,id:payload.id,offset:payload.offset??0,limit:payload.limit??50,signal})
+        : endpoint === 'vcs/revision-changes'
+        ? await api.getRevisionChanges({...repository},{base:payload.base,target:payload.target,signal})
+        : endpoint === 'vcs/revision-compare'
+        ? await api.getRevisionComparison({...repository},{base:payload.base,target:payload.target,id:payload.id,signal})
+        : endpoint === 'vcs/commit-compare'
+        ? await api.getCommitComparison({...repository},{commit:payload.commit,parentIndex:payload.parentIndex??0,id:payload.id,signal})
+        : endpoint === 'vcs/commit'
+        ? await api.getCommitDetails({...repository},{commit:payload.commit,parentIndex:payload.parentIndex??0,signal})
+        : endpoint === 'vcs/history'
+        ? await api.listHistory({...repository},{snapshot:payload.snapshot,offset:payload.offset??0,limit:payload.limit??50,signal})
+        : endpoint === 'vcs/status'
         ? { cwd, repository: { ...repository }, changes: await api.listChanges({ ...repository }, mode), mode }
         : await api.getComparison({ ...repository }, { mode, id: payload.id });
       await assertCurrent(payload.sessionId, cwd, entry, signal);
@@ -108,7 +149,7 @@ export function createHandler(ctx, api = adapter, maxActive = 4, { now = Date.no
     } catch (error) {
       if (signal?.aborted || error?.name === 'AbortError') return failure('vcs/cancelled', 'The request was cancelled.');
       return failure(typeof error?.code === 'string' && error.code.startsWith('vcs/') ? error.code : 'vcs/operation-failed', error instanceof Error ? error.message : String(error));
-    } finally { active--; }
+    } finally { active--; if(imageSlot)activeImages--; }
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feng0531/dsh-vcs",
-  "version": "0.3.23",
+  "version": "0.3.35",
   "private": false,
   "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
   "type": "module",
@@ -14,6 +14,8 @@
   "files": [
     "index.mjs",
     "vcs.mjs",
+    "git-history.mjs",
+    "image-preview.mjs",
     "dist",
     "locale",
     "icon.svg",

package/vcs.mjs

@@ -1,4 +1,6 @@
+import {preparePng} from './image-preview.mjs';
 import { spawn } from 'node:child_process';
+import {parseHistory,HISTORY_FORMAT,historyPage,parseBlame,parseReferences,REFS_FORMAT} from './git-history.mjs';
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
@@ -14,7 +16,7 @@ function run(command, args, cwd, max = MAX_OUTPUT, { signal, timeoutMs = TIMEOUT
     if (signal?.aborted) { reject(Object.assign(new Error('Discovery cancelled'), { code: 'ABORT_ERR' })); return; }
     // Inherited Git overrides must not redirect reads to a different repository.
     const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
-    Object.assign(env, { GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', LC_ALL: process.platform === 'linux' ? 'C.UTF-8' : 'en_US.UTF-8' });
+    Object.assign(env, { GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1', GIT_ALLOW_PROTOCOL: '', LC_ALL: process.platform === 'linux' ? 'C.UTF-8' : 'en_US.UTF-8' });
     const child = spawn(command, args, { cwd, shell: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'], env });
     const out = [], err = []; let size = 0, error, done = false;
     const stop = e => { error ??= e; child.kill(); };
@@ -211,12 +213,151 @@ export async function discoverRepositories(cwd, { signal, maxDepth = 6, maxDirec
   return result;
 }
 
-async function checkedRepo(repo) {
+async function checkedRepo(repo, signal) {
+  signal?.throwIfAborted();
   if (!repo || !['git', 'svn'].includes(repo.type) || typeof repo.root !== 'string') throw new Error('Invalid repository');
-  const found = await repositoryAt(repo.root, repo.type);
+  const found = await repositoryAt(repo.root, repo.type, () => ({signal}));
+  signal?.throwIfAborted();
   if (!found || found.type !== repo.type || path.resolve(found.root) !== path.resolve(repo.root)) throw new Error('Repository root changed or is invalid');
   return found;
 }
+export async function listHistory(repo, {snapshot,offset=0,limit=50,signal} = {}) {
+  if(!Number.isInteger(offset)||offset<0||offset>10000||!Number.isInteger(limit)||limit<1||limit>100) throw new Error('Invalid history pagination');
+  if(snapshot!==undefined && (typeof snapshot!=='string'||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(snapshot))) throw new Error('Invalid history snapshot');
+  if(signal?.aborted) throw Object.assign(new Error('History cancelled'),{code:'ABORT_ERR'});
+  repo=await checkedRepo(repo,signal);
+  if(repo.type!=='git') throw new Error('History currently supports Git only');
+  if(!snapshot){
+    try{snapshot=(await git(repo.root,['rev-parse','--verify','HEAD^{commit}'],MAX_TEXT,{signal})).toString('utf8').trim();}
+    catch(e){
+      if(e.code!=='VCS_COMMAND')throw e;
+      // Distinguish an unborn symbolic HEAD from corruption or other command failures.
+      const ref=(await git(repo.root,['symbolic-ref','-q','HEAD'],MAX_TEXT,{signal})).toString('utf8').trim();
+      try{await git(repo.root,['show-ref','--verify','--quiet',ref],MAX_TEXT,{signal});}
+      catch(missing){if(missing.code==='VCS_COMMAND'&&missing.exitCode===1)return {snapshot:null,commits:[],nextOffset:null};throw missing;}
+      throw e;
+    }
+  }
+  const text=await git(repo.root,['log','-z','--no-show-signature','--encoding=UTF-8','--topo-order','--max-count='+String(limit+1),'--skip='+String(offset),'--format='+HISTORY_FORMAT,snapshot,'--'],MAX_TEXT,{signal});
+  const rows=parseHistory(text.toString('utf8'),limit+1);
+  return historyPage(rows,snapshot,offset,limit);
+}
+export async function listReferences(repo,{signal}={}){
+ signal?.throwIfAborted();repo=await checkedRepo(repo,signal);
+ if(repo.type!=='git')throw new Error('References support Git only');
+ const raw=await git(repo.root,['for-each-ref','--sort=refname','--count=1001','--format='+REFS_FORMAT,'refs/heads/','refs/tags/'],MAX_TEXT,{signal});
+ return {references:parseReferences(raw.toString('utf8'))};
+}
+
+export async function getCommitDetails(repo,options={}) {
+  return commitDetails(repo,options,true);
+}
+async function commitDetails(repo,{commit,parentIndex=0,signal}={},includeMessage=false) {
+  if(typeof commit!=='string'||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit))throw new Error('Invalid commit id');
+  if(!Number.isInteger(parentIndex)||parentIndex<0)throw new Error('Invalid parent index');
+  signal?.throwIfAborted();
+  repo=await checkedRepo(repo,signal);
+  if(repo.type!=='git')throw new Error('Commit details support Git only');
+  const raw=await git(repo.root,['log','-z','--no-show-signature','--encoding=UTF-8','--max-count=1','--format='+HISTORY_FORMAT,commit,'--'],MAX_TEXT,{signal});
+  const metadata=parseHistory(raw.toString('utf8'),1)[0];
+  if(!metadata||metadata.id!==commit)throw new Error('Commit object required');
+  if(parentIndex>=Math.max(1,metadata.parents.length))throw new Error('Invalid parent index');
+  const parent=metadata.parents[parentIndex]??null;
+  const args=['diff-tree','--no-commit-id','--name-status','-z','-r','--no-ext-diff','--no-textconv','--find-renames',...(parent?[parent,commit]:['--root',commit]),'--'];
+  const changes=parseCommitChanges((await git(repo.root,args,MAX_TEXT,{signal})).toString('utf8'),commit+':'+(parent||'root'));
+  if(!includeMessage)return {...metadata,parent,parentIndex,changes};
+  let message='',messageTruncated=false;
+  try{message=(await git(repo.root,['log','--no-show-signature','--encoding=UTF-8','--max-count=1','--format=%B',commit,'--'],MAX_TEXT,{signal})).toString('utf8');}
+  catch(error){if(error.code!=='TOO_LARGE')throw error;messageTruncated=true;}
+  signal?.throwIfAborted();
+  return {...metadata,message,messageTruncated,parent,parentIndex,changes};
+}
+function parseCommitChanges(text,scope){
+  const fields=text.split(String.fromCharCode(0));
+  if(fields.pop()!=='')throw new Error('Truncated commit changes');
+  const changes=[];
+  for(let i=0;i<fields.length;){
+    const code=fields[i++];
+    if(!/^(?:[AMDT]|[RC][0-9]{1,3})$/.test(code))throw new Error('Invalid commit change status');
+    const first=fields[i++],renamed=/^[RC]/.test(code),file=renamed?fields[i++]:first;
+    if(!first||!file)throw new Error('Truncated commit path');
+    const entry={path:file,...(renamed?{oldPath:first}:{}),status:statuses[code[0]]||'modified'};
+    changes.push({...entry,id:identity(entry,scope)});
+    if(changes.length>10000)throw new Error('Commit exceeds file count limit');
+  }
+  return changes;
+}
+export async function getHistoricalTree(repo,{commit,signal}={}){
+ if(typeof commit!=='string'||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit))throw new Error('Invalid commit id');
+ repo=await checkedRepo(repo,signal);if(repo.type!=='git')throw new Error('Historical tree supports Git only');
+ const type=(await git(repo.root,['cat-file','-t',commit],MAX_TEXT,{signal})).toString('utf8').trim();if(type!=='commit')throw new Error('Commit object required');
+ const text=(await git(repo.root,['ls-tree','-r','-t','-z','--full-tree',commit],MAX_TEXT,{signal})).toString('utf8');
+ const fields=text.split(String.fromCharCode(0));if(fields.pop()!=='')throw new Error('Truncated historical tree');
+ if(fields.length>10000)throw new Error('Historical tree exceeds entry limit');
+ const entries=fields.map(record=>{
+  const tab=record.indexOf('\t'),head=record.slice(0,tab),file=record.slice(tab+1);
+  const match=/^(040000|100644|100755|120000|160000) (tree|blob|commit) ([a-f0-9]{40}|[a-f0-9]{64})$/.exec(head);
+  if(tab<0||!file||!match)throw new Error('Invalid historical tree entry');
+  const [,mode,type,oid]=match;
+  if(type!==(mode==='040000'?'tree':mode==='160000'?'commit':'blob'))throw new Error('Invalid historical tree type');
+  return {path:file,mode,type,oid};
+ });
+ return {commit,entries};
+}
+export async function getCommitImage(repo,{commit,parentIndex=0,id,side='right',signal}={}){
+ if(!['left','right'].includes(side))throw new Error('Invalid image side');
+ if(typeof id!=='string'||!/^[a-f0-9]{64}$/.test(id))throw new Error('Invalid historical change id');
+ const details=await commitDetails(repo,{commit,parentIndex,signal}),entry=details.changes.find(e=>e.id===id);
+ if(!entry)throw new Error('Change is not part of selected commit');
+ const revision=side==='left'?details.parent:commit,file=side==='left'?(entry.oldPath||entry.path):entry.path;
+ if(!revision||(side==='left'&&entry.status==='added')||(side==='right'&&entry.status==='deleted'))return {commit:revision,path:file,absent:true};
+ const listing=(await git(repo.root,['--literal-pathspecs','ls-tree','-z',revision,'--',file],MAX_TEXT,{signal})).toString('utf8');
+ const record=listing.split(String.fromCharCode(0)).find(row=>row.slice(row.indexOf('\t')+1)===file);
+ if(!record)throw new Error('Historical path missing');
+ const [mode,type,oid]=record.slice(0,record.indexOf('\t')).split(' ');
+ if(type!=='blob'||!['100644','100755'].includes(mode))throw new Error('Image preview requires a regular file');
+ const raw=await git(repo.root,['cat-file','blob',oid],MAX_TEXT,{signal});
+ const {data,...metadata}=await preparePng(raw,{signal});
+ return {commit:revision,path:file,oid,...metadata,base64:data.toString('base64')};
+}
+export async function getFileBlame(repo,{commit,parentIndex=0,id,signal}={}){
+ if(typeof id!=='string'||!/^[a-f0-9]{64}$/.test(id))throw new Error('Invalid historical change id');
+ const details=await commitDetails(repo,{commit,parentIndex,signal});
+ const entry=details.changes.find(row=>row.id===id);if(!entry)throw new Error('Change is not part of selected commit');
+ const result={commit,path:entry.path,lines:[],truncated:false};
+ if(entry.status==='deleted')return {...result,notice:'File is deleted at this commit; blame unavailable.'};
+ const blob=await historicalBlob(repo.root,commit,entry.path,signal);
+ if(blob.notice||blob.binary||blob.encoding!=='UTF-8')return {...result,notice:blob.notice||'Blame supports UTF-8 regular text only.'};
+ if(!blob.text)return result;
+ const count=blob.text.split('\n').length-(blob.text.endsWith('\n')?1:0),limit=Math.min(count,500);
+ let ignored;
+ try{ignored=(await git(repo.root,['config','--null','--get-all','blame.ignoreRevsFile'],MAX_TEXT,{signal})).toString('utf8');}catch(e){if(e.code!=='VCS_COMMAND'||e.exitCode!==1)throw e;}
+ if(ignored?.split(String.fromCharCode(0)).some(value=>value.length>0))return {...result,notice:'Blame unavailable while blame.ignoreRevsFile is configured; external revision files are not read.'};
+ const output=await git(repo.root,['--literal-pathspecs','blame','--ignore-revs-file=','--line-porcelain','--no-textconv','--encoding=UTF-8','-L','1,'+limit,commit,'--',entry.path],MAX_TEXT,{signal});
+ return {...result,lines:parseBlame(output.toString('utf8'),limit),truncated:count>limit};
+}
+export async function listFileHistory(repo,{commit,parentIndex=0,id,offset=0,limit=50,signal}={}){
+  if(!Number.isInteger(offset)||offset<0||offset>10000||!Number.isInteger(limit)||limit<1||limit>100)throw new Error('Invalid history pagination');
+  if(typeof id!=='string'||!/^[a-f0-9]{64}$/.test(id))throw new Error('Invalid historical change id');
+  const details=await commitDetails(repo,{commit,parentIndex,signal});
+  const entry=details.changes.find(row=>row.id===id);
+  if(!entry)throw new Error('Change is not part of selected commit');
+  const text=await git(repo.root,['--literal-pathspecs','log','-z','--no-show-signature','--encoding=UTF-8','--topo-order','--max-count='+String(limit+1),'--skip='+String(offset),'--format='+HISTORY_FORMAT,commit,'--',entry.path],MAX_TEXT,{signal});
+  return {...historyPage(parseHistory(text.toString('utf8'),limit+1),commit,offset,limit),path:entry.path,followsRenames:false};
+}
+export async function getRevisionChanges(repo,{base,target,signal}={}){
+  for(const oid of [base,target])if(typeof oid!=='string'||!/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(oid))throw new Error('Invalid revision commit id');
+  signal?.throwIfAborted();repo=await checkedRepo(repo,signal);
+  if(repo.type!=='git')throw new Error('Revision comparison supports Git only');
+  for(const oid of new Set([base,target])){
+    const type=(await git(repo.root,['cat-file','-t',oid],MAX_TEXT,{signal})).toString('utf8').trim();
+    if(type!=='commit')throw new Error('Commit object required');
+  }
+  const args=['diff-tree','--no-commit-id','--name-status','-z','-r','--no-ext-diff','--no-textconv','--find-renames',base,target,'--'];
+  const scope=JSON.stringify(['revision',repo.root,base,target]);
+  const changes=parseCommitChanges((await git(repo.root,args,MAX_TEXT,{signal})).toString('utf8'),scope);
+  return {base,target,changes};
+}
 function modeFor(repo, mode) {
   if (!['all', 'staged', 'unstaged'].includes(mode)) throw new Error('Invalid comparison mode');
   if (repo.type === 'svn' && mode !== 'all') throw new Error('SVN supports only all mode');
@@ -281,6 +422,36 @@ async function working(root, relative, svnLink = false) {
   try { const info = await handle.stat(); if (!info.isFile()) throw new Error('Not a regular file'); const buffer = Buffer.alloc(MAX_TEXT + 1); const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0); await confined(root, relative); return decode(buffer.subarray(0, bytesRead)); } finally { await handle.close(); }
 }
 async function gitBlob(root, revision, file) { return content(() => git(root, ['show', '--no-ext-diff', '--no-textconv', revision + ':' + file], MAX_TEXT)); }
+async function historicalBlob(root,revision,file,signal){
+  const listing=(await git(root,['ls-tree','-z',revision,'--',file],MAX_TEXT,{signal})).toString('utf8');
+  const records=listing.split(String.fromCharCode(0)).filter(Boolean);
+  const record=records.find(row=>row.slice(row.indexOf('	')+1)===file);
+  if(!record)throw new Error('Historical path missing');
+  const [mode,type,oid]=record.slice(0,record.indexOf('	')).split(' ');
+  if(mode==='160000')return {text:oid,notice:'Submodule commit reference; repository contents are not loaded.'};
+  if(type!=='blob'||!['100644','100755','120000'].includes(mode))return {text:'',notice:'Unsupported historical object type.'};
+  const result=await content(()=>git(root,['cat-file','blob',oid],MAX_TEXT,{signal}));
+  if(mode==='120000')result.notice=[result.notice,'Symbolic link target text; not followed.'].filter(Boolean).join(' ');
+  return result;
+}
+export async function getCommitComparison(repo,{commit,parentIndex=0,id,signal}={}){
+  if(typeof id!=='string'||!/^[a-f0-9]{64}$/.test(id))throw new Error('Invalid historical change id');
+  const details=await commitDetails(repo,{commit,parentIndex,signal});
+  const entry=details.changes.find(row=>row.id===id);
+  if(!entry)throw new Error('Historical change is not part of selected commit and parent');
+  const left=details.parent&&entry.status!=='added'?await historicalBlob(repo.root,details.parent,entry.oldPath||entry.path,signal):{text:''};
+  const right=entry.status!=='deleted'?await historicalBlob(repo.root,commit,entry.path,signal):{text:''};
+  return {...entry,left:{...left,label:details.parent||'Empty tree'},right:{...right,label:commit},binary:!!(left.binary||right.binary),notice:[left.notice,right.notice].filter(Boolean).join(' ')};
+}
+export async function getRevisionComparison(repo,{base,target,id,signal}={}){
+  if(typeof id!=='string'||!/^[a-f0-9]{64}$/.test(id))throw new Error('Invalid revision change id');
+  const details=await getRevisionChanges(repo,{base,target,signal});
+  const entry=details.changes.find(row=>row.id===id);
+  if(!entry)throw new Error('Change is not part of selected revision pair');
+  const left=entry.status!=='added'?await historicalBlob(repo.root,base,entry.oldPath||entry.path,signal):{text:''};
+  const right=entry.status!=='deleted'?await historicalBlob(repo.root,target,entry.path,signal):{text:''};
+  return {...entry,base,target,left:{...left,label:base},right:{...right,label:target},binary:!!(left.binary||right.binary),notice:[left.notice,right.notice].filter(Boolean).join(' ')};
+}
 async function properties(root, file, base) {
   const result = parseXML(await svn(root, ['proplist', '--xml', '--verbose', ...(base ? ['--revision', 'BASE'] : []), '--', file + '@']));
   const props = Object.create(null);