git-er-done 0.1.11 → 0.1.13

package/README.md

@@ -147,6 +147,39 @@ if (mdFiles.edited) {
 }
 ```
 
+### Getting File Creation and Modification Dates
+
+Get git timestamps for when files were created and last modified:
+
+```js
+const { getFileDates, getFileModifiedTimeStamp, getFileCreatedTimeStamp } = require('git-er-done')
+
+// Get both dates efficiently (recommended)
+const dates = await getFileDates('src/index.js')
+console.log('Created:', dates.createdDate)
+console.log('Modified:', dates.modifiedDate)
+console.log('Created timestamp:', dates.created) // Unix timestamp in seconds
+console.log('Modified timestamp:', dates.modified) // Unix timestamp in seconds
+
+// Or get just modified date
+const modifiedTimestamp = await getFileModifiedTimeStamp('README.md')
+console.log('Last modified:', new Date(modifiedTimestamp * 1000))
+
+// Or get just created date
+const createdTimestamp = await getFileCreatedTimeStamp('README.md')
+console.log('First committed:', new Date(createdTimestamp * 1000))
+
+// Get dates for multiple files (pass an array)
+const files = ['README.md', 'package.json', 'src/index.js']
+const fileDates = await getFileDates(files)
+
+for (const [file, info] of Object.entries(fileDates)) {
+  if (!info.error) {
+    console.log(`${file}: last modified ${info.modifiedDate.toISOString()}`)
+  }
+}
+```
+
 ### Getting Detailed File Information
 
 The `fileMatch` function returns detailed information about matched files:
@@ -168,6 +201,70 @@ console.log('All edited test files:', testFiles.editedFiles)
 if (testFiles.edited) {
   console.log('Tests have been modified - run test suite')
 }
+```
+
+### Getting Git Root Directory
+
+```js
+const { getGitRoot } = require('git-er-done')
+
+const root = await getGitRoot()
+console.log('Git root:', root) // '/Users/you/your-repo'
+```
+
+### Getting File Contents at a Specific Commit
+
+Retrieve the contents of a file as it existed at a specific commit:
+
+```js
+const { getFileAtCommit } = require('git-er-done')
+
+// Get file contents from previous commit
+const previousVersion = await getFileAtCommit('src/index.js', 'HEAD~1')
+console.log('Previous version:', previousVersion)
+
+// Get file at specific SHA
+const oldVersion = await getFileAtCommit('package.json', 'abc123')
+
+// With cwd option for running in a different directory
+const contents = await getFileAtCommit('src/app.js', 'main', {
+  cwd: '/path/to/other/repo'
+})
+```
+
+### Getting Git Remotes
+
+```js
+const { getRemotes, getRemote } = require('git-er-done')
+
+// Get all remotes
+const remotes = await getRemotes()
+console.log('All remotes:', Object.keys(remotes)) // ['origin', 'upstream']
+console.log('Origin URL:', remotes.origin.url)
+
+// Get a specific remote
+const origin = await getRemote('origin')
+console.log('Origin:', origin)
+// { name: 'origin', url: 'git@github.com:user/repo.git', fetchUrl: '...', pushUrl: '...' }
+```
+
+### Subpath Exports
+
+Import only what you need for smaller bundles:
+
+```js
+// Individual imports
+const { getCommit } = require('git-er-done/get-commit')
+const { getAllCommits } = require('git-er-done/get-all-commits')
+const { getFirstCommit } = require('git-er-done/get-first-commit')
+const { getLastCommit } = require('git-er-done/get-last-commit')
+const { gitDetails } = require('git-er-done/get-details')
+const { getGitRoot } = require('git-er-done/get-root')
+const { getGitFiles } = require('git-er-done/get-files')
+const { getFileAtCommit } = require('git-er-done/get-file-at-commit')
+const { getFileDates, getFileModifiedTimeStamp, getFileCreatedTimeStamp } = require('git-er-done/get-file-dates')
+const { getRemotes, getRemote } = require('git-er-done/get-remotes')
+```
 
 ## Examples
 
@@ -178,6 +275,7 @@ Check out the [`examples`](./examples) directory for more use cases:
 - [`get-all-commits.js`](./examples/get-all-commits.js) - Retrieve and display all commits
 - [`get-git-files.js`](./examples/get-git-files.js) - Get list of all git-tracked files
 - [`get-specific-commit-info.js`](./examples/get-specific-commit-info.js) - Get detailed information about a specific commit
+- [`get-file-dates.js`](./examples/get-file-dates.js) - Get creation and modification dates for files
 
 ### File Change Detection
 - [`detect-file-changes.js`](./examples/detect-file-changes.js) - Detect specific file changes between commits
@@ -191,6 +289,7 @@ Check out the [`examples`](./examples) directory for more use cases:
 - [`check-config-changes.js`](./examples/check-config-changes.js) - Detect configuration file changes for CI/CD pipelines
 - [`code-review-helper.js`](./examples/code-review-helper.js) - Automated code review checklist and suggestions
 - [`monorepo-package-detection.js`](./examples/monorepo-package-detection.js) - Detect which packages changed in a monorepo
+- [`serverless-monorepo-detection.js`](./examples/serverless-monorepo-detection.js) - Detect changes in serverless projects within a monorepo
 - [`generate-release-notes.js`](./examples/generate-release-notes.js) - Auto-generate release notes from commits
 
 Run any example:
@@ -199,6 +298,7 @@ Run any example:
 node examples/get-git-data.js
 node examples/code-review-helper.js
 node examples/monorepo-package-detection.js
+node examples/serverless-monorepo-detection.js
 ```
 
 ## Prior art

package/package.json

@@ -1,9 +1,59 @@
 {
   "name": "git-er-done",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Utility for dealing with modified, created, deleted files since a git commit",
   "main": "src/index.js",
   "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./get-commit": {
+      "types": "./types/git/commits/getCommit.d.ts",
+      "default": "./src/git/commits/getCommit.js"
+    },
+    "./get-all-commits": {
+      "types": "./types/git/commits/getAllCommits.d.ts",
+      "default": "./src/git/commits/getAllCommits.js"
+    },
+    "./get-first-commit": {
+      "types": "./types/git/commits/getFirstCommit.d.ts",
+      "default": "./src/git/commits/getFirstCommit.js"
+    },
+    "./get-last-commit": {
+      "types": "./types/git/commits/getLastCommit.d.ts",
+      "default": "./src/git/commits/getLastCommit.js"
+    },
+    "./get-details": {
+      "types": "./types/git/getDetails.d.ts",
+      "default": "./src/git/getDetails.js"
+    },
+    "./get-root": {
+      "types": "./types/git/getGitRoot.d.ts",
+      "default": "./src/git/getGitRoot.js"
+    },
+    "./get-files": {
+      "types": "./types/git/getGitFiles.d.ts",
+      "default": "./src/git/getGitFiles.js"
+    },
+    "./get-file-at-commit": {
+      "types": "./types/git/getFileAtCommit.d.ts",
+      "default": "./src/git/getFileAtCommit.js"
+    },
+    "./get-diff-formatted": {
+      "types": "./types/git/getDiffFormatted.d.ts",
+      "default": "./src/git/getDiffFormatted.js"
+    },
+    "./get-file-dates": {
+      "types": "./types/git/dates/getFileDates.d.ts",
+      "default": "./src/git/dates/getFileDates.js"
+    },
+    "./get-remotes": {
+      "types": "./types/git/remotes/getRemotes.d.ts",
+      "default": "./src/git/remotes/getRemotes.js"
+    }
+  },
   "scripts": {
     "test": "uvu . \\.test\\.js$",
     "check": "tsc --noEmit",
@@ -40,7 +90,11 @@
     "url": "https://github.com/DavidWells/components/tree/master/packages/util-git-info"
   },
   "devDependencies": {
+    "@davidwells/extract-deps": "^0.0.5",
+    "@davidwells/git-split-diffs": "^2.2.1",
     "@types/node": "^22.10.1",
+    "configorama": "^0.6.14",
+    "minimatch": "^10.0.1",
     "typescript": "^5.7.2",
     "uvu": "^0.5.6"
   }

package/src/git/dates/getFileDates.js

@@ -0,0 +1,204 @@
+const { executeCommand } = require('../utils/exec')
+const path = require('path')
+const { getGitRoot } = require('../getGitRoot')
+const { validateFilePath } = require('../utils/validateFilePath')
+
+/**
+ * @typedef {Object} FileDateInfo
+ * @property {number} created - Unix timestamp (seconds) of when the file was first committed
+ * @property {number} modified - Unix timestamp (seconds) of when the file was last modified
+ * @property {Date} createdDate - JavaScript Date object of creation time
+ * @property {Date} modifiedDate - JavaScript Date object of last modification
+ */
+
+/**
+ * @typedef {Object} FileDateError
+ * @property {string} error - Error message when file date retrieval fails
+ */
+
+/**
+ * Gets the last modification date of a file from git history
+ * @param {string} filePath - Path to the file (absolute or relative to git root)
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Promise<number>} Promise that resolves to Unix timestamp (seconds) of last modification
+ * @example
+ * const modifiedDate = await getFileModifiedTimeStamp('src/index.js')
+ * console.log('Last modified:', new Date(modifiedDate * 1000))
+ */
+async function getFileModifiedTimeStamp(filePath, options = {}) {
+  const cwd = options.cwd || process.cwd()
+
+  return new Promise((resolve, reject) => {
+    // Validate file path to prevent command injection
+    try {
+      validateFilePath(filePath)
+    } catch (err) {
+      return reject(err)
+    }
+
+    // Get most recent commit timestamp for the file
+    const command = `git log -1 --pretty=format:%at --follow -- "${filePath}"`
+
+    executeCommand(command, { dst: cwd }, (err, stdout) => {
+      if (err) {
+        return reject(new Error(`Failed to get modified date for ${filePath}: ${err.message}`))
+      }
+
+      const timestamp = stdout.trim()
+      if (!timestamp || timestamp === '') {
+        // File might not be committed yet
+        return reject(new Error(`No git history found for ${filePath}`))
+      }
+
+      const unixTimestamp = parseInt(timestamp, 10)
+      if (isNaN(unixTimestamp)) {
+        return reject(new Error(`Invalid timestamp received for ${filePath}`))
+      }
+
+      resolve(unixTimestamp)
+    })
+  })
+}
+
+/**
+ * Gets the creation date of a file from git history (first commit)
+ * @param {string} filePath - Path to the file (absolute or relative to git root)
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Promise<number>} Promise that resolves to Unix timestamp (seconds) of creation
+ * @example
+ * const createdDate = await getFileCreatedTimeStamp('src/index.js')
+ * console.log('Created:', new Date(createdDate * 1000))
+ */
+async function getFileCreatedTimeStamp(filePath, options = {}) {
+  const cwd = options.cwd || process.cwd()
+
+  return new Promise((resolve, reject) => {
+    // Validate file path to prevent command injection
+    try {
+      validateFilePath(filePath)
+    } catch (err) {
+      return reject(err)
+    }
+
+    // Get all commit timestamps following history, then take the last one (oldest)
+    const command = `git log --follow --pretty=format:%at -- "${filePath}"`
+
+    executeCommand(command, { dst: cwd }, (err, stdout) => {
+      if (err) {
+        return reject(new Error(`Failed to get created date for ${filePath}: ${err.message}`))
+      }
+
+      const timestamps = stdout.trim().split('\n').filter(Boolean)
+      if (timestamps.length === 0) {
+        return reject(new Error(`No git history found for ${filePath}`))
+      }
+
+      // Last timestamp in the log is the oldest (creation)
+      const createdTimestamp = timestamps[timestamps.length - 1]
+      const unixTimestamp = parseInt(createdTimestamp, 10)
+
+      if (isNaN(unixTimestamp)) {
+        return reject(new Error(`Invalid timestamp received for ${filePath}`))
+      }
+
+      resolve(unixTimestamp)
+    })
+  })
+}
+
+/**
+ * Gets dates for a single file (internal helper)
+ * @param {string} filePath - Path to the file
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory
+ * @returns {Promise<FileDateInfo>}
+ */
+async function getSingleFileDates(filePath, options = {}) {
+  const cwd = options.cwd || process.cwd()
+
+  return new Promise((resolve, reject) => {
+    // Validate file path to prevent command injection
+    try {
+      validateFilePath(filePath)
+    } catch (err) {
+      return reject(err)
+    }
+
+    // Get all commit timestamps following history
+    const command = `git log --follow --pretty=format:%at -- "${filePath}"`
+
+    executeCommand(command, { dst: cwd }, (err, stdout) => {
+      if (err) {
+        return reject(new Error(`Failed to get dates for ${filePath}: ${err.message}`))
+      }
+
+      const timestamps = stdout.trim().split('\n').filter(Boolean)
+      if (timestamps.length === 0) {
+        return reject(new Error(`No git history found for ${filePath}`))
+      }
+
+      // First timestamp is most recent (modified), last is oldest (created)
+      const modifiedTimestamp = parseInt(timestamps[0], 10)
+      const createdTimestamp = parseInt(timestamps[timestamps.length - 1], 10)
+
+      if (isNaN(modifiedTimestamp) || isNaN(createdTimestamp)) {
+        return reject(new Error(`Invalid timestamp received for ${filePath}`))
+      }
+
+      resolve({
+        created: createdTimestamp,
+        modified: modifiedTimestamp,
+        createdDate: new Date(createdTimestamp * 1000),
+        modifiedDate: new Date(modifiedTimestamp * 1000)
+      })
+    })
+  })
+}
+
+/**
+ * Gets both creation and modification dates for file(s) from git history
+ * @param {string | string[]} filePaths - Path or array of paths to file(s)
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Promise<FileDateInfo | Object<string, FileDateInfo | FileDateError>>} Single file returns FileDateInfo, multiple files returns object keyed by path
+ * @example
+ * // Single file
+ * const dates = await getFileDates('src/index.js')
+ * console.log('Created:', dates.createdDate)
+ * console.log('Modified:', dates.modifiedDate)
+ *
+ * // Multiple files
+ * const dates = await getFileDates(['src/index.js', 'README.md'])
+ * console.log('Index modified:', dates['src/index.js'].modifiedDate)
+ */
+async function getFileDates(filePaths, options = {}) {
+  // Single file path
+  if (typeof filePaths === 'string') {
+    return getSingleFileDates(filePaths, options)
+  }
+
+  // Multiple file paths
+  /** @type {Object<string, FileDateInfo | FileDateError>} */
+  const results = {}
+
+  await Promise.all(
+    filePaths.map(async (filePath) => {
+      try {
+        results[filePath] = await getSingleFileDates(filePath, options)
+      } catch (err) {
+        // Store error but don't fail entire operation
+        results[filePath] = { error: err.message }
+      }
+    })
+  )
+
+  return results
+}
+
+module.exports = {
+  getFileModifiedTimeStamp,
+  getFileCreatedTimeStamp,
+  getFileDates
+}

package/src/git/dates/getFileDates.test.js

@@ -0,0 +1,203 @@
+const path = require('path')
+const { test } = require('uvu')
+const assert = require('uvu/assert')
+
+const {
+  getFileModifiedTimeStamp,
+  getFileCreatedTimeStamp,
+  getFileDates
+} = require('./getFileDates')
+
+// Use style-guard package files for testing (they're unlikely to change)
+// Note: These paths are relative to the git root
+const STYLE_GUARD_INDEX = path.join(__dirname, '../../../../style-guard/index.js')
+const STYLE_GUARD_README = path.join(__dirname, '../../../../style-guard/README.md')
+const STYLE_GUARD_PACKAGE = path.join(__dirname, '../../../../style-guard/package.json')
+
+// Wrapper to add timing to tests
+const timedTest = (name, fn) => {
+  test(name, async (context) => {
+    const start = Date.now()
+    try {
+      await fn(context)
+    } finally {
+      const duration = Date.now() - start
+      console.log(`  ⏱️  ${name}: ${duration}ms`)
+    }
+  })
+}
+
+timedTest('getFileModifiedTimeStamp should return a unix timestamp', async () => {
+  const timestamp = await getFileModifiedTimeStamp(STYLE_GUARD_INDEX)
+  assert.ok(Number.isInteger(timestamp))
+  assert.ok(timestamp > 0)
+  // Should be a reasonable date (after 2020)
+  assert.ok(timestamp > 1577836800)
+})
+
+timedTest('getFileCreatedTimeStamp should return a unix timestamp', async () => {
+  const timestamp = await getFileCreatedTimeStamp(STYLE_GUARD_INDEX)
+  assert.ok(Number.isInteger(timestamp))
+  assert.ok(timestamp > 0)
+  // Should be a reasonable date (after 2020)
+  assert.ok(timestamp > 1577836800)
+})
+
+timedTest('getFileDates should return both created and modified dates', async () => {
+  const dates = await getFileDates(STYLE_GUARD_INDEX)
+  console.log('getFileDates', dates)
+
+  // Check specific timestamp values
+  assert.is(dates.created, 1609635897)
+  assert.is(dates.modified, 1610136724)
+
+  // Check specific Date object values
+  assert.is(dates.createdDate.toISOString(), '2021-01-03T01:04:57.000Z')
+  assert.is(dates.modifiedDate.toISOString(), '2021-01-08T20:12:04.000Z')
+
+  // Check timestamps exist and are valid
+  assert.ok(Number.isInteger(dates.created))
+  assert.ok(Number.isInteger(dates.modified))
+  assert.ok(dates.created > 0)
+  assert.ok(dates.modified > 0)
+
+  // Check Date objects exist and are valid
+  assert.ok(dates.createdDate instanceof Date)
+  assert.ok(dates.modifiedDate instanceof Date)
+
+  // Created date should be before or equal to modified date
+  assert.ok(dates.created <= dates.modified)
+
+  // Date objects should match timestamps
+  assert.is(dates.createdDate.getTime(), dates.created * 1000)
+  assert.is(dates.modifiedDate.getTime(), dates.modified * 1000)
+})
+
+timedTest('getFileDates should return dates for multiple files', async () => {
+  const files = [STYLE_GUARD_INDEX, STYLE_GUARD_README, STYLE_GUARD_PACKAGE]
+  const results = await getFileDates(files)
+
+  console.log('getFileDates (multiple)', results)
+
+  // Should have results for all files
+  assert.equal(Object.keys(results).sort(), files.sort())
+
+  // Each file should have valid date info
+  for (const file of files) {
+    const dates = results[file]
+
+    // Skip if there was an error
+    if (dates.error) {
+      continue
+    }
+
+    assert.ok(Number.isInteger(dates.created))
+    assert.ok(Number.isInteger(dates.modified))
+    assert.ok(dates.createdDate instanceof Date)
+    assert.ok(dates.modifiedDate instanceof Date)
+  }
+})
+
+timedTest('should reject invalid file paths - null bytes', async () => {
+  try {
+    await getFileModifiedTimeStamp('test\0.js')
+    assert.unreachable('Should have thrown an error')
+  } catch (err) {
+    assert.match(err.message, /null bytes/)
+  }
+})
+
+timedTest('should reject invalid file paths - command injection', async () => {
+  try {
+    await getFileModifiedTimeStamp('test.js; rm -rf /')
+    assert.unreachable('Should have thrown an error')
+  } catch (err) {
+    assert.match(err.message, /suspicious characters/)
+  }
+})
+
+timedTest('should reject invalid file paths - shell metacharacters', async () => {
+  const dangerousPaths = [
+    'test.js|cat /etc/passwd',
+    'test.js`whoami`',
+    'test.js$(whoami)',
+    'test.js&& echo hacked',
+  ]
+
+  for (const badPath of dangerousPaths) {
+    try {
+      await getFileModifiedTimeStamp(badPath)
+      assert.unreachable(`Should have thrown an error for: ${badPath}`)
+    } catch (err) {
+      assert.match(err.message, /suspicious characters/)
+    }
+  }
+})
+
+timedTest('should reject path traversal attempts', async () => {
+  try {
+    await getFileModifiedTimeStamp('../../etc/passwd')
+    assert.unreachable('Should have thrown an error')
+  } catch (err) {
+    assert.match(err.message, /suspicious characters|directory traversal/)
+  }
+})
+
+timedTest('should reject newlines in file paths', async () => {
+  try {
+    await getFileModifiedTimeStamp('test.js\nrm -rf /')
+    assert.unreachable('Should have thrown an error')
+  } catch (err) {
+    assert.match(err.message, /suspicious characters/)
+  }
+})
+
+timedTest('should reject empty or non-string file paths', async () => {
+  try {
+    await getFileModifiedTimeStamp('')
+    assert.unreachable('Should have thrown an error')
+  } catch (err) {
+    assert.match(err.message, /non-empty string/)
+  }
+
+  try {
+    await getFileModifiedTimeStamp(null)
+    assert.unreachable('Should have thrown an error')
+  } catch (err) {
+    assert.match(err.message, /non-empty string/)
+  }
+
+  try {
+    await getFileModifiedTimeStamp(undefined)
+    assert.unreachable('Should have thrown an error')
+  } catch (err) {
+    assert.match(err.message, /non-empty string/)
+  }
+})
+
+timedTest('should handle files with spaces in names', async () => {
+  // This should NOT be rejected - spaces are valid in file names
+  // Note: This test will fail if the file doesn't exist, but that's expected
+  // The important thing is that it doesn't fail due to path validation
+  try {
+    await getFileModifiedTimeStamp('test file.js')
+  } catch (err) {
+    // Should fail because file doesn't exist, not because of validation
+    assert.match(err.message, /No git history found|Failed to get/)
+  }
+})
+
+timedTest('should handle relative paths correctly', async () => {
+  // Relative paths should work - test with the same file
+  const timestamp = await getFileModifiedTimeStamp(STYLE_GUARD_INDEX)
+  assert.ok(Number.isInteger(timestamp))
+  assert.ok(timestamp > 0)
+})
+
+timedTest('created date should be less than or equal to modified date', async () => {
+  const dates = await getFileDates(STYLE_GUARD_INDEX)
+  assert.ok(dates.created <= dates.modified,
+    `Created date (${dates.created}) should be <= modified date (${dates.modified})`)
+})
+
+test.run()

package/src/git/getDiffFormatted.js

@@ -0,0 +1,142 @@
+const path = require('path')
+const { promisify } = require('util')
+const { exec } = require('child_process')
+const { getGitRoot } = require('./getGitRoot')
+const terminalSize = require('./utils/term-size')
+const execAsync = promisify(exec)
+
+/**
+ * Strip ANSI escape codes from a string
+ */
+function stripAnsi(str) {
+  return str.replace(/\x1b\[[0-9;]*m/g, '')
+}
+
+/**
+ * Calculate the longest line length in a diff
+ */
+function getLongestLineLength(diff) {
+  const lines = diff.split('\n')
+  let maxLength = 0
+
+  for (const line of lines) {
+    // Skip diff headers
+    if (line.startsWith('diff --git') ||
+        line.startsWith('index ') ||
+        line.startsWith('---') ||
+        line.startsWith('+++')) {
+      continue
+    }
+
+    let contentToMeasure = line
+
+    // For hunk headers (@@), extract the code context after the second @@
+    if (line.startsWith('@@')) {
+      const secondAtIndex = line.indexOf('@@', 2)
+      if (secondAtIndex !== -1) {
+        contentToMeasure = line.slice(secondAtIndex + 2)
+      }
+    } else {
+      // Get actual content (skip the leading space/+/-)
+      contentToMeasure = line.slice(1)
+    }
+
+    const cleanContent = stripAnsi(contentToMeasure)
+
+    if (cleanContent.length > maxLength) {
+      maxLength = cleanContent.length
+    }
+  }
+
+  return maxLength
+}
+
+/**
+ * Get formatted diff for a specific file
+ * @param {Object} options - Options for getting formatted diff
+ * @param {string} options.filePath - Relative path from git root
+ * @param {string} options.gitRootDir - Absolute path to git root directory
+ * @param {string} options.baseBranch - Base branch to compare against
+ * @param {boolean} options.shrinkToLongestLine - Auto-calculate width based on longest line
+ * @param {number} options.leftMargin - Number of spaces to add to the left of each line
+ * @param {number} options.width - Width of the diff output (ignored if shrinkToLongestLine is true)
+ * @param {boolean} options.hideHeader - Remove the file path header from the diff
+ */
+async function getFormattedDiff({
+  filePath,
+  gitRootDir,
+  baseBranch = 'master',
+  shrinkToLongestLine = false,
+  leftMargin = 0,
+  width = 140,
+  hideHeader = false
+}) {
+  try {
+    const { formatDiff } = await import('@davidwells/git-split-diffs')
+
+    if (!gitRootDir) {
+      gitRootDir = await getGitRoot()
+    }
+
+    // Get the diff for this specific file
+    const { stdout: diff } = await execAsync(`git diff ${baseBranch} --ignore-cr-at-eol -- "${filePath}"`, {
+      cwd: gitRootDir
+    })
+
+    if (!diff) {
+      return null
+    }
+
+    // Calculate width if shrinkToLongestLine is enabled
+    let diffWidth = width
+    if (shrinkToLongestLine) {
+      const longestLine = getLongestLineLength(diff)
+      diffWidth = longestLine + 25
+    }
+
+    // TODO cache this value
+    const terminalWidth = terminalSize()
+    let maxWidth = Math.min(terminalWidth.columns, diffWidth)
+
+    if (leftMargin > 0) {
+      maxWidth = maxWidth - leftMargin
+    }
+
+    // Format the diff with git-split-diffs
+    let formatted = await formatDiff(diff, {
+      // hyperlinkFileNames: false,
+      // hyperlinkLineNumbers: false,
+      // hideFileHeader: true,
+      // omitHunkHeaders: true,
+      trimLastEmptyLine: true,
+      width: maxWidth,
+      minLineWidth: 80,
+      wrapLines: false,
+      highlightLineChanges: true,
+      themeName: 'dark',
+      gitRootDir,
+    })
+
+    // Remove header if hideHeader is true
+    if (hideHeader) {
+      const lines = formatted.split('\n')
+      // Skip first 3 lines (separator, file path with ■■, separator)
+      formatted = lines.slice(3).join('\n')
+    }
+
+    // Add left margin if specified
+    if (leftMargin > 0) {
+      const margin = ' '.repeat(leftMargin)
+      return formatted.split('\n').map(line => margin + line).join('\n')
+    }
+
+    return formatted
+  } catch (err) {
+    console.error(`Error formatting diff for ${filePath}:`, err.message)
+    return null
+  }
+}
+
+module.exports = {
+  getFormattedDiff
+}

package/src/git/getFileAtCommit.js

@@ -0,0 +1,27 @@
+// Returns file contents at a specific git commit
+const { localGetFileAtSHA } = require('./localGetFileAtSHA')
+const { validateFilePath } = require('./utils/validateFilePath')
+
+/**
+ * Gets the contents of a file at a specific git commit
+ * @param {string} filePath - Path to the file (relative to git root)
+ * @param {string} sha - Git commit SHA or ref (e.g., 'HEAD', 'main', 'abc123')
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
+ * @returns {Promise<string|undefined>} File contents at that commit, or undefined if not found
+ * @example
+ * const contents = await getFileAtCommit('src/index.js', 'HEAD~1')
+ * console.log('Previous version:', contents)
+ *
+ * // With cwd option
+ * const contents = await getFileAtCommit('package.json', 'HEAD', { cwd: '/path/to/repo' })
+ */
+async function getFileAtCommit(filePath, sha, options = {}) {
+  validateFilePath(filePath)
+  if (!sha || typeof sha !== 'string') {
+    throw new Error('SHA must be a non-empty string')
+  }
+  return localGetFileAtSHA(filePath, null, sha, options)
+}
+
+module.exports = { getFileAtCommit }

package/src/git/localGetFileAtSHA.js

@@ -1,21 +1,32 @@
+// Gets file contents at a specific git SHA
 const { debug } = require('../debug')
 const { exec } = require('child_process')
 
 const d = debug('localGetFileAtSHA')
 
-const localGetFileAtSHA = (path, _repo, sha) => {
-  return new Promise(resolve => {
+/**
+ * Gets file contents at a specific git commit (internal)
+ * @param {string} path - File path relative to git root
+ * @param {string|null} _repo - Unused, kept for interface compatibility
+ * @param {string} sha - Git commit SHA or ref
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
+ * @returns {Promise<string|undefined>} File contents or undefined if not found
+ */
+const localGetFileAtSHA = (path, _repo, sha, options = {}) => {
+  const cwd = options.cwd || process.cwd()
+  /** @type {Promise<string|undefined>} */
+  const promise = new Promise(resolve => {
     const call = `git show ${sha}:'${path}'`
     d(call)
-    exec(call, (err, stdout, _stderr) => {
+    exec(call, { cwd }, (err, stdout, _stderr) => {
       if (err) {
-        // console.error(`Could not get the file ${path} from git at ${sha}`)
-        // console.error(err)
-        return resolve()
+        return resolve(undefined)
       }
       resolve(stdout)
     })
   })
+  return promise
 }
 
 module.exports.localGetFileAtSHA = localGetFileAtSHA

package/src/git/utils/differ.js

@@ -0,0 +1 @@
+// https://github.com/kpdecker/jsdiff/blob/master/test/patch/create.js

package/src/git/utils/gitignore.js

@@ -0,0 +1 @@
+// https://github.com/humanwhocodes/gitignore-to-minimatch

package/src/git/utils/term-size.js

@@ -0,0 +1,136 @@
+const process = require('process')
+const { execFileSync } = require('child_process')
+const fs = require('fs')
+const tty = require('tty')
+
+const defaultColumns = 80
+const defaultRows = 24
+
+/**
+ * @typedef {Object} TerminalSize
+ * @property {number} columns - Number of columns in the terminal
+ * @property {number} rows - Number of rows in the terminal
+ */
+
+/** @type {TerminalSize|undefined} */
+let sizeCache
+
+// @ts-ignore
+function exec(command, arguments_, { shell, env } = {}) {
+  return execFileSync(command, arguments_, {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'ignore'],
+    timeout: 500,
+    shell,
+    env,
+  }).trim()
+}
+
+function create(columns, rows) {
+  return {
+    columns: Number.parseInt(columns, 10),
+    rows: Number.parseInt(rows, 10),
+  }
+}
+
+function createIfNotDefault(maybeColumns, maybeRows) {
+  const { columns, rows } = create(maybeColumns, maybeRows)
+
+  if (Number.isNaN(columns) || Number.isNaN(rows)) {
+    return
+  }
+
+  if (columns === defaultColumns && rows === defaultRows) {
+    return
+  }
+
+  return { columns, rows }
+}
+
+function devTty() {
+  try {
+    // eslint-disable-next-line no-bitwise
+    // @ts-ignore - O_EVTONLY is macOS-specific
+    const flags = process.platform === 'darwin' ? fs.constants.O_EVTONLY | fs.constants.O_NONBLOCK : fs.constants.O_NONBLOCK
+    // eslint-disable-next-line new-cap
+    // @ts-ignore
+    const { columns, rows } = tty.WriteStream(fs.openSync('/dev/tty', flags))
+    return { columns, rows }
+  } catch {}
+}
+
+// On macOS, this only returns correct values when stdout is not redirected.
+function tput() {
+  try {
+    // `tput` requires the `TERM` environment variable to be set.
+    const columns = exec('tput', ['cols'], { env: { TERM: 'dumb', ...process.env } })
+    const rows = exec('tput', ['lines'], { env: { TERM: 'dumb', ...process.env } })
+
+    if (columns && rows) {
+      return createIfNotDefault(columns, rows)
+    }
+  } catch {}
+}
+
+// Only exists on Linux.
+function resize() {
+  // `resize` is preferred as it works even when all file descriptors are redirected
+  // https://linux.die.net/man/1/resize
+  try {
+    const size = exec('resize', ['-u']).match(/\d+/g)
+
+    if (size.length === 2) {
+      return createIfNotDefault(size[0], size[1])
+    }
+  } catch {}
+}
+
+function terminalSize() {
+  // Return cached size if available for performance.
+  if (sizeCache) {
+    return sizeCache
+  }
+
+  const { env, stdout, stderr } = process
+
+  if (stdout?.columns && stdout?.rows) {
+    sizeCache = create(stdout.columns, stdout.rows)
+    return sizeCache
+  }
+
+  if (stderr?.columns && stderr?.rows) {
+    sizeCache = create(stderr.columns, stderr.rows)
+    return sizeCache
+  }
+
+  // These values are static, so not the first choice.
+  if (env.COLUMNS && env.LINES) {
+    sizeCache = create(env.COLUMNS, env.LINES)
+    return sizeCache
+  }
+
+  const fallback = {
+    columns: defaultColumns,
+    rows: defaultRows,
+  }
+
+  if (process.platform === 'win32') {
+    // We include `tput` for Windows users using Git Bash.
+    sizeCache = tput() ?? fallback
+    return sizeCache
+  }
+
+  if (process.platform === 'darwin') {
+    sizeCache = devTty() ?? tput() ?? fallback
+    return sizeCache
+  }
+
+  sizeCache = devTty() ?? tput() ?? resize() ?? fallback
+  return sizeCache
+}
+
+if (require.main === module) {
+  console.log(terminalSize())
+}
+
+module.exports = terminalSize

package/src/git/utils/validateFilePath.js

@@ -0,0 +1,44 @@
+const path = require('path')
+
+/**
+ * Validates and sanitizes a file path to prevent command injection
+ * @param {string} filePath - The file path to validate
+ * @returns {string} The validated file path
+ * @throws {Error} If the file path contains suspicious characters
+ */
+function validateFilePath(filePath) {
+  if (!filePath || typeof filePath !== 'string') {
+    throw new Error('File path must be a non-empty string')
+  }
+
+  // Check for null bytes (common injection technique)
+  if (filePath.includes('\0')) {
+    throw new Error('File path contains null bytes')
+  }
+
+  // Check for command injection attempts
+  const dangerousPatterns = [
+    /[;&|`$(){}[\]<>]/,  // Shell metacharacters
+    /\n|\r/,              // Newlines
+    /\.\.\//,             // Path traversal attempts (relative)
+    /^\.\.\\/,            // Path traversal attempts (Windows)
+  ]
+
+  for (const pattern of dangerousPatterns) {
+    if (pattern.test(filePath)) {
+      throw new Error(`File path contains suspicious characters: ${filePath}`)
+    }
+  }
+
+  // Normalize the path to prevent traversal attacks
+  const normalized = path.normalize(filePath)
+
+  // Additional check after normalization for path traversal
+  if (normalized.includes('..')) {
+    throw new Error(`File path contains directory traversal: ${filePath}`)
+  }
+
+  return filePath
+}
+
+module.exports = { validateFilePath }

package/src/index.js

@@ -4,12 +4,32 @@ const { getFirstCommit } = require('./git/commits/getFirstCommit')
 const { getLastCommit } = require('./git/commits/getLastCommit')
 const { getAllCommits } = require('./git/commits/getAllCommits')
 const { getGitFiles } = require('./git/getGitFiles')
+const { getGitRoot } = require('./git/getGitRoot')
+const { getRemotes, getRemote } = require('./git/remotes/getRemotes')
+const { getFileAtCommit } = require('./git/getFileAtCommit')
+const {
+  getFileModifiedTimeStamp,
+  getFileCreatedTimeStamp,
+  getFileDates
+} = require('./git/dates/getFileDates')
 
 module.exports = {
+  // Get Git Details
+  gitDetails,
+  getGitRoot,
+  // Get Commits
   getCommit,
+  getAllCommits,
   getFirstCommit,
   getLastCommit,
-  getAllCommits,
-  gitDetails,
-  getGitFiles
+  // Get Git Files
+  getGitFiles,
+  getFileAtCommit,
+  // Get Git File time details
+  getFileModifiedTimeStamp,
+  getFileCreatedTimeStamp,
+  getFileDates,
+  // Get Git Remotes
+  getRemotes,
+  getRemote,
 }

package/src/types.js

@@ -47,4 +47,12 @@
  * @property {function(): Promise<number>} linesOfCode - Async function that returns total lines of code changed
  */
 
+/**
+ * @typedef {Object} FileDateInfo
+ * @property {number} created - Unix timestamp (seconds) of when the file was first committed
+ * @property {number} modified - Unix timestamp (seconds) of when the file was last modified
+ * @property {Date} createdDate - JavaScript Date object of creation time
+ * @property {Date} modifiedDate - JavaScript Date object of last modification
+ */
+
 module.exports = {}

package/types/git/dates/getFileDates.d.ts

@@ -0,0 +1,82 @@
+export type FileDateInfo = {
+    /**
+     * - Unix timestamp (seconds) of when the file was first committed
+     */
+    created: number;
+    /**
+     * - Unix timestamp (seconds) of when the file was last modified
+     */
+    modified: number;
+    /**
+     * - JavaScript Date object of creation time
+     */
+    createdDate: Date;
+    /**
+     * - JavaScript Date object of last modification
+     */
+    modifiedDate: Date;
+};
+export type FileDateError = {
+    /**
+     * - Error message when file date retrieval fails
+     */
+    error: string;
+};
+/**
+ * @typedef {Object} FileDateInfo
+ * @property {number} created - Unix timestamp (seconds) of when the file was first committed
+ * @property {number} modified - Unix timestamp (seconds) of when the file was last modified
+ * @property {Date} createdDate - JavaScript Date object of creation time
+ * @property {Date} modifiedDate - JavaScript Date object of last modification
+ */
+/**
+ * @typedef {Object} FileDateError
+ * @property {string} error - Error message when file date retrieval fails
+ */
+/**
+ * Gets the last modification date of a file from git history
+ * @param {string} filePath - Path to the file (absolute or relative to git root)
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Promise<number>} Promise that resolves to Unix timestamp (seconds) of last modification
+ * @example
+ * const modifiedDate = await getFileModifiedTimeStamp('src/index.js')
+ * console.log('Last modified:', new Date(modifiedDate * 1000))
+ */
+export function getFileModifiedTimeStamp(filePath: string, options?: {
+    cwd?: string;
+}): Promise<number>;
+/**
+ * Gets the creation date of a file from git history (first commit)
+ * @param {string} filePath - Path to the file (absolute or relative to git root)
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Promise<number>} Promise that resolves to Unix timestamp (seconds) of creation
+ * @example
+ * const createdDate = await getFileCreatedTimeStamp('src/index.js')
+ * console.log('Created:', new Date(createdDate * 1000))
+ */
+export function getFileCreatedTimeStamp(filePath: string, options?: {
+    cwd?: string;
+}): Promise<number>;
+/**
+ * Gets both creation and modification dates for file(s) from git history
+ * @param {string | string[]} filePaths - Path or array of paths to file(s)
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Current working directory (defaults to process.cwd())
+ * @returns {Promise<FileDateInfo | Object<string, FileDateInfo | FileDateError>>} Single file returns FileDateInfo, multiple files returns object keyed by path
+ * @example
+ * // Single file
+ * const dates = await getFileDates('src/index.js')
+ * console.log('Created:', dates.createdDate)
+ * console.log('Modified:', dates.modifiedDate)
+ *
+ * // Multiple files
+ * const dates = await getFileDates(['src/index.js', 'README.md'])
+ * console.log('Index modified:', dates['src/index.js'].modifiedDate)
+ */
+export function getFileDates(filePaths: string | string[], options?: {
+    cwd?: string;
+}): Promise<FileDateInfo | {
+    [x: string]: FileDateInfo | FileDateError;
+}>;

package/types/git/getDiffFormatted.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Get formatted diff for a specific file
+ * @param {Object} options - Options for getting formatted diff
+ * @param {string} options.filePath - Relative path from git root
+ * @param {string} options.gitRootDir - Absolute path to git root directory
+ * @param {string} options.baseBranch - Base branch to compare against
+ * @param {boolean} options.shrinkToLongestLine - Auto-calculate width based on longest line
+ * @param {number} options.leftMargin - Number of spaces to add to the left of each line
+ * @param {number} options.width - Width of the diff output (ignored if shrinkToLongestLine is true)
+ * @param {boolean} options.hideHeader - Remove the file path header from the diff
+ */
+export function getFormattedDiff({ filePath, gitRootDir, baseBranch, shrinkToLongestLine, leftMargin, width, hideHeader }: {
+    filePath: string;
+    gitRootDir: string;
+    baseBranch: string;
+    shrinkToLongestLine: boolean;
+    leftMargin: number;
+    width: number;
+    hideHeader: boolean;
+}): Promise<any>;

package/types/git/getFileAtCommit.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Gets the contents of a file at a specific git commit
+ * @param {string} filePath - Path to the file (relative to git root)
+ * @param {string} sha - Git commit SHA or ref (e.g., 'HEAD', 'main', 'abc123')
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
+ * @returns {Promise<string|undefined>} File contents at that commit, or undefined if not found
+ * @example
+ * const contents = await getFileAtCommit('src/index.js', 'HEAD~1')
+ * console.log('Previous version:', contents)
+ *
+ * // With cwd option
+ * const contents = await getFileAtCommit('package.json', 'HEAD', { cwd: '/path/to/repo' })
+ */
+export function getFileAtCommit(filePath: string, sha: string, options?: {
+    cwd?: string;
+}): Promise<string | undefined>;

package/types/git/localGetFileAtSHA.d.ts

@@ -1 +1,12 @@
-export function localGetFileAtSHA(path: any, _repo: any, sha: any): Promise<any>;
+/**
+ * Gets file contents at a specific git commit (internal)
+ * @param {string} path - File path relative to git root
+ * @param {string|null} _repo - Unused, kept for interface compatibility
+ * @param {string} sha - Git commit SHA or ref
+ * @param {Object} [options] - Options
+ * @param {string} [options.cwd] - Working directory (defaults to process.cwd())
+ * @returns {Promise<string|undefined>} File contents or undefined if not found
+ */
+export function localGetFileAtSHA(path: string, _repo: string | null, sha: string, options?: {
+    cwd?: string;
+}): Promise<string | undefined>;

package/types/git/utils/term-size.d.ts

@@ -0,0 +1,15 @@
+export = terminalSize;
+declare function terminalSize(): TerminalSize;
+declare namespace terminalSize {
+    export { TerminalSize };
+}
+type TerminalSize = {
+    /**
+     * - Number of columns in the terminal
+     */
+    columns: number;
+    /**
+     * - Number of rows in the terminal
+     */
+    rows: number;
+};

package/types/git/utils/validateFilePath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Validates and sanitizes a file path to prevent command injection
+ * @param {string} filePath - The file path to validate
+ * @returns {string} The validated file path
+ * @throws {Error} If the file path contains suspicious characters
+ */
+export function validateFilePath(filePath: string): string;

package/types/index.d.ts

@@ -1,7 +1,14 @@
+import { gitDetails } from "./git/getDetails";
+import { getGitRoot } from "./git/getGitRoot";
 import { getCommit } from "./git/commits/getCommit";
+import { getAllCommits } from "./git/commits/getAllCommits";
 import { getFirstCommit } from "./git/commits/getFirstCommit";
 import { getLastCommit } from "./git/commits/getLastCommit";
-import { getAllCommits } from "./git/commits/getAllCommits";
-import { gitDetails } from "./git/getDetails";
 import { getGitFiles } from "./git/getGitFiles";
-export { getCommit, getFirstCommit, getLastCommit, getAllCommits, gitDetails, getGitFiles };
+import { getFileAtCommit } from "./git/getFileAtCommit";
+import { getFileModifiedTimeStamp } from "./git/dates/getFileDates";
+import { getFileCreatedTimeStamp } from "./git/dates/getFileDates";
+import { getFileDates } from "./git/dates/getFileDates";
+import { getRemotes } from "./git/remotes/getRemotes";
+import { getRemote } from "./git/remotes/getRemotes";
+export { gitDetails, getGitRoot, getCommit, getAllCommits, getFirstCommit, getLastCommit, getGitFiles, getFileAtCommit, getFileModifiedTimeStamp, getFileCreatedTimeStamp, getFileDates, getRemotes, getRemote };

package/types/types.d.ts

@@ -126,3 +126,21 @@ export type GitDetails = {
      */
     linesOfCode: () => Promise<number>;
 };
+export type FileDateInfo = {
+    /**
+     * - Unix timestamp (seconds) of when the file was first committed
+     */
+    created: number;
+    /**
+     * - Unix timestamp (seconds) of when the file was last modified
+     */
+    modified: number;
+    /**
+     * - JavaScript Date object of creation time
+     */
+    createdDate: Date;
+    /**
+     * - JavaScript Date object of last modification
+     */
+    modifiedDate: Date;
+};