Shadow Checkpoint Manager

A tool for managing shadow Git checkpoints that track file modifications in a separate repository from the main project repository.

Requirements

Core Functionality

Implement a checkpoint management system that creates and manages snapshots in a shadow Git repository:

1. Shadow Repository Initialization: Initialize a shadow Git repository at a specified path (e.g., ~/.checkpoints/<project_hash>/) that is separate from any existing project repository.

2. Automatic Checkpointing: Before any file modification operation, automatically create a checkpoint by committing the current state of specified files to the shadow repository. Each checkpoint should include:

   • A timestamp
   • A description of the operation being performed
   • Metadata about which files will be modified

3. Checkpoint Listing: List all available checkpoints in chronological order, showing:

   • Checkpoint ID (commit hash)
   • Timestamp
   • Description
   • Files affected

4. File Restoration: Restore specific files from a checkpoint to their state at that point in time, without affecting the main project repository.

5. Checkpoint Browsing: Retrieve and display the state of files at any checkpoint without restoring them.

Test Cases

• Given an initialized shadow repository and a file config.json, when creating a checkpoint before modifying the file, then the shadow repository should contain a commit with the file's current state and appropriate metadata @test

• Given multiple checkpoints exist, when listing checkpoints, then all checkpoints should be returned in chronological order with their metadata (timestamp, description, files affected) @test

• Given a checkpoint ID and a file path, when restoring that file from the checkpoint, then the file should be restored to its exact state at that checkpoint without affecting the shadow repository or any other files @test

• Given a checkpoint ID, when browsing the checkpoint, then the contents of all files at that checkpoint should be retrievable without modifying the current working directory @test

Implementation

@generates

API

/**
 * Initializes a shadow Git repository at the specified path.
 *
 * @param {string} shadowRepoPath - Path where the shadow repository should be created
 * @returns {Promise<void>}
 */
async function initShadowRepo(shadowRepoPath) {
  // IMPLEMENTATION HERE
}

/**
 * Creates a checkpoint by committing the current state of files to the shadow repository.
 *
 * @param {string} shadowRepoPath - Path to the shadow repository
 * @param {string[]} filePaths - Array of file paths to include in the checkpoint
 * @param {Object} metadata - Checkpoint metadata
 * @param {string} metadata.description - Description of the operation
 * @returns {Promise<string>} The checkpoint ID (commit hash)
 */
async function createCheckpoint(shadowRepoPath, filePaths, metadata) {
  // IMPLEMENTATION HERE
}

/**
 * Lists all checkpoints in the shadow repository.
 *
 * @param {string} shadowRepoPath - Path to the shadow repository
 * @returns {Promise<Array<Object>>} Array of checkpoint objects with id, timestamp, description, and files
 */
async function listCheckpoints(shadowRepoPath) {
  // IMPLEMENTATION HERE
}

/**
 * Restores a specific file from a checkpoint to its state at that time.
 *
 * @param {string} shadowRepoPath - Path to the shadow repository
 * @param {string} checkpointId - Checkpoint ID (commit hash) to restore from
 * @param {string} filePath - Path to the file to restore
 * @param {string} targetPath - Where to restore the file
 * @returns {Promise<void>}
 */
async function restoreFile(shadowRepoPath, checkpointId, filePath, targetPath) {
  // IMPLEMENTATION HERE
}

/**
 * Retrieves the contents of files at a specific checkpoint without restoring them.
 *
 * @param {string} shadowRepoPath - Path to the shadow repository
 * @param {string} checkpointId - Checkpoint ID (commit hash) to browse
 * @returns {Promise<Map<string, string>>} Map of file paths to their contents at that checkpoint
 */
async function browseCheckpoint(shadowRepoPath, checkpointId) {
  // IMPLEMENTATION HERE
}

module.exports = {
  initShadowRepo,
  createCheckpoint,
  listCheckpoints,
  restoreFile,
  browseCheckpoint
};

Dependencies { .dependencies }

simple-git { .dependency }

Git integration for Node.js applications - provides programmatic Git operations.

fs-extra { .dependency }

File system operations with additional utility methods beyond Node.js built-in fs module.