@tochii/vscode-file-recovery/README.md

Recover files and full project structures in bulk from VS Code's local history

# @tochii/vscode-file-recovery

Recover files and full project structures in bulk from VS Code's local history programmatically.

**Note:** this package is not a CLI. Go to [CLI version](#cli-version) to use the CLI.

## Table of Contents
- [@tochii/vscode-file-recovery](#tochiivscode-file-recovery)
  - [Table of Contents](#table-of-contents)
  - [Installation](#installation)
      - [CLI version](#cli-version)
  - [Usage](#usage)
    - [Parameters](#parameters)
  - [Options](#options)
  - [Output](#output)
  - [Notes](#notes)
  - [Troubleshooting](#troubleshooting)
      - [If any files fail due to permission issues, try the following:](#if-any-files-fail-due-to-permission-issues-try-the-following)


## Installation
```bash
npm install @tochii/vscode-file-recovery
```

#### CLI version
```bash
npx @tochii/cli generate vscode-file-recovery
```

or install the CLI locally and then run it:
```bash
npm i -D @tochii/cli
```
```bash
tochi generate vscode-file-recovery
```

## Usage
```ts
import vscodeFileRecovery from '@tochii/vscode-file-recovery';

await vscodeFileRecovery('search-term-or-path', {
    clean: true,
    range: ['2024-01-01', '2024-12-31'],
    outDir: './recovered',
    verbose: 'info'
});
```

### Parameters
- `search` (string): Required. A search string to match recovered file paths. Can be a partial path or keyword.
- `options` (VsCodeFileRecoveryOptions): Optional. Recovery configuration.
- `loggerOptions` (LoggerOptions): Optional. Custom logger configuration (see [@tochii/logger](https://www.npmjs.com/package/@tochii/logger)).

## Options

| Option            | Type                                                      | Default                                    | Description                                           |
| ----------------- | --------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------- |
| `clean`           | `boolean`                                                 | `false`                                    | Whether to clean the output directory before recovery |
| `dateFormat`      | `string`                                                  | `"yyyy LLL dd, hh:mm a"`                   | Format for output timestamps using Luxon              |
| `range`           | `[TimeRangeValue, TimeRangeValue]`                        | `[null, null]`                             | Limit recovery to file versions within a date range   |
| `skip`            | `string[]`                                                | `["node_modules", "vscode-file-recovery"]` | Skip paths containing any of these values             |
| `outDir`          | `string`                                                  | `<rootDir>/vscode-file-recovery`           | Output directory path                                 |
| `rootDir`         | `string`                                                  | `current working dir`                      | Project root directory                                |
| `outDirName`      | `string`                                                  | `"vscode-file-recovery"`                   | Name of the output folder                             |
| `localHistoryDir` | `string`                                                  | `<AppData>/Code/User/History`              | Path to VS Code’s local history                       |
| `verbose`         | `fatal`, `error`, `warn`, `info`, `debug`, `trace`, `off` | `trace`                                    | Logging level                                         |

## Output
- Recovered files are copied to the configured output directory.
- A `metadata.json` file with recovery context is generated.
- Log files are created to track:
  - Successfully copied files
  - Skipped files
  - Invalid files

## Notes
- The most recent entry for each matched file is recovered unless a date range is specified.
- You must have appropriate read and write permissions for the local history and output directories.

## Troubleshooting
#### If any files fail due to permission issues, try the following:
  - Run as administrator
  - Ensure files are not open in other programs
  - Confirm write access to the VS Code local history folder
  - Wait briefly and try again (folder locks can be temporary)