npm package: @iyulab/oops
Description: Core SDK for Oops - Safe text file editing with automatic backup
Author: iyulab
Latest version: 0.1.3

# @iyulab/oops

Core SDK for Oops - Safe text file editing with automatic backup and simple undo.

## Installation

```bash
npm install @iyulab/oops
```

## Quick Start

```typescript
import { Oops } from '@iyulab/oops';

const oops = new Oops();

// Initialize workspace
await oops.initWorkspace();

// Start tracking a file
await oops.begin('/path/to/file.txt');

// Check for changes
const hasChanges = await oops.hasChanges('/path/to/file.txt');

// Get diff
const diff = await oops.diff('/path/to/file.txt');

// Apply changes
await oops.keep('/path/to/file.txt');

// Or undo changes
await oops.undo('/path/to/file.txt');
```

## Features

- 🔒 **Safe file editing** with automatic backup
- 📝 **Simple undo** functionality
- 🗂️ **Workspace management** with temporary or local storage
- 🔄 **Batch operations** for multiple files
- 📊 **File validation** and health checks
- ⚙️ **Configurable** safety options

## API Reference

### Core Methods

#### `initWorkspace()`
Initialize a new workspace for tracking files.

#### `begin(filePath: string)`
Start tracking a file by creating a backup.

#### `hasChanges(filePath: string): Promise<boolean>`
Check if a tracked file has changes.

#### `diff(filePath: string): Promise<DiffResult>`
Generate diff information for a tracked file.

#### `keep(filePath: string)`
Apply changes and stop tracking the file.

#### `undo(filePath: string)`
Revert file to backup and stop tracking.

#### `abort(filePath: string)`
Stop tracking without reverting changes.

### Batch Operations

#### `keepAll()`
Apply changes to all tracked files.

#### `undoAll()`
Revert all tracked files to their backups.

#### `abortAll()`
Stop tracking all files without reverting.

### Workspace Management

#### `getWorkspaceInfo(): Promise<WorkspaceInfo>`
Get information about the current workspace.

#### `isWorkspaceHealthy(): Promise<boolean>`
Check if the workspace is in a healthy state.

#### `cleanWorkspace()`
Clean up the workspace and all tracking data.

#### `getWorkspaceSize(): Promise<{files: number, sizeBytes: number}>`
Get workspace size information.

### Configuration

#### `getConfig(): OopsConfig`
Get current configuration.

#### `setConfig(key: string, value: any)`
Set configuration values (supports nested keys like 'safety.confirmKeep').

## Configuration Options

```typescript
interface OopsConfig {
  workspace: {
    useTemp: boolean;    // Use temporary directory
    path: string | null; // Custom workspace path
  };
  safety: {
    confirmKeep: boolean;   // Confirm before applying changes
    confirmUndo: boolean;   // Confirm before undoing
    autoBackup: boolean;    // Automatic backup creation
  };
  diff: {
    tool: string;    // External diff tool ('auto', 'code', 'vimdiff', etc.)
    context: number; // Number of context lines in diff
  };
}
```

## Static Factory Methods

#### `Oops.createTempWorkspace(): Promise<Oops>`
Create an instance with a temporary workspace.

#### `Oops.createLocalWorkspace(basePath: string): Promise<Oops>`
Create an instance with a local workspace.

## Error Handling

The SDK provides specific error types for better error handling:

- `FileNotFoundError`
- `FileAlreadyTrackedError` 
- `FileNotTrackedError`
- `WorkspaceNotInitializedError`
- `WorkspaceCorruptedError`
- `GitOperationError`

## TypeScript Support

This package is written in TypeScript and includes complete type definitions.

## License

MIT - see [LICENSE](./LICENSE) for details.

## Repository

[https://github.com/iyulab/oops](https://github.com/iyulab/oops)