npm package: @genzai/logging
Description: Logging middleware for code generation
Latest version: 0.1.1

# @genzai/logging

Logging middleware for code generation with progress tracking and file operation visibility.

## Installation

```bash
npm install @genzai/logging @genzai/core
# or
pnpm add @genzai/logging @genzai/core
# or
yarn add @genzai/logging @genzai/core
```

## Overview

`@genzai/logging` provides middleware for logging file operations during code generation. It tracks which files are being written, how long operations take, and provides visibility into the generation process.

## Features

- 📝 **Operation Logging**: Log file and folder operations
- ⏱️ **Performance Tracking**: Measure operation duration
- 🔌 **Easy Integration**: Drop-in middleware for `@genzai/core`
- 🎯 **Simple API**: Just add to middleware pipeline

## Quick Start

```typescript
import { write } from "@genzai/core";
import { loggingMiddleware } from "@genzai/logging";

await write(plan, "./output", [], {
  middlewares: [loggingMiddleware],
});
```

Output:
```
Writing: /path/to/output/index.ts
Completed: /path/to/output/index.ts (12ms)
Writing: /path/to/output/config.json
Completed: /path/to/output/config.json (5ms)
```

## API Reference

### `loggingMiddleware`

Middleware that logs file operations and their duration.

```typescript
import { loggingMiddleware } from "@genzai/logging";
import { write } from "@genzai/core";

await write(nodes, "./output", [], {
  middlewares: [loggingMiddleware],
});
```

## Usage Examples

### Basic Usage

```typescript
import { file, folder, write } from "@genzai/core";
import { loggingMiddleware } from "@genzai/logging";

const generator = folder(
  "my-project",
  file("README.md", () => "# My Project"),
  file("index.ts", () => "export const main = () => {};")
);

const plan = await generator({});

await write(plan, "./output", [], {
  middlewares: [loggingMiddleware],
});
```

### With Multiple Middleware

```typescript
import { write } from "@genzai/core";
import { loggingMiddleware } from "@genzai/logging";
import { slotMiddleware } from "@genzai/slots";
import { mergeStrategyMiddleware } from "@genzai/merge-strategy";

await write(plan, "./output", [], {
  middlewares: [
    loggingMiddleware,        // Log at the start
    mergeStrategyMiddleware,
    slotMiddleware,
  ],
});
```

This will log operations as they happen, giving you visibility into the entire pipeline.

## How It Works

1. **Before Write**: Logs the file path and starts a timer
2. **Proceed**: Calls `next()` to continue the middleware chain
3. **After Write**: Logs completion with duration

The middleware wraps the entire operation, so it includes time spent in all downstream middleware and the actual write operation.

## Output Format

```
Writing: <absolute-path>
Completed: <absolute-path> (<duration>ms)
```

Example:
```
Writing: /Users/john/project/src/index.ts
Completed: /Users/john/project/src/index.ts (15ms)
Writing: /Users/john/project/src/lib.ts
Completed: /Users/john/project/src/lib.ts (8ms)
```

## Future Enhancements

The current implementation provides basic logging. Future versions may include:

- 🌳 **Tree View**: Hierarchical display of folder structure
- 📊 **Progress Bar**: Visual progress indication
- 📈 **Statistics**: Total files written, total time, etc.
- 🎨 **Colored Output**: Enhanced terminal formatting
- 🔇 **Log Levels**: Configurable verbosity
- 📁 **Folder Operations**: Explicit folder creation logging

See the TODO in the source code for more planned features.

## Best Practices

1. **Place Early**: Put logging middleware early in the chain to capture full duration
2. **Development**: Great for development to see what's being generated
3. **Debugging**: Helps identify slow operations or issues in the pipeline
4. **CI/CD**: Useful in build pipelines to track generation steps

## Middleware Order

The order of middleware affects what gets logged. Consider:

```typescript
// This logs the full operation time including all middleware
middlewares: [
  loggingMiddleware,
  slowMiddleware,        // Time included in log
]

// This only logs the write operation time
middlewares: [
  slowMiddleware,
  loggingMiddleware,     // Doesn't include slowMiddleware time
]
```

## Related Packages

- `@genzai/core` - Core generation framework (required)
- `@genzai/slots` - Slot-based content preservation
- `@genzai/merge-strategy` - File conflict resolution
- `@genzai/prettier` - Code formatting middleware

## License

MIT