@meldscience/meld/docs/PLAN.md

pipeable one-shot prompt scripting toolkit

# Handoff Note - Current Progress and Next Steps

Dear next assistant,

We have successfully implemented and thoroughly tested the core functionality of this project, and we've made significant progress on the CLI implementation. The current state is stable with 25 passing tests across all components. Here's what you need to know:

1. Current Status:
   - All core classes (Meld, Oneshot, Oneshotcat) are implemented and tested
   - Supporting infrastructure (errors.ts, config.ts, providers) is complete
   - Test coverage is comprehensive with mocked file systems and AI providers
   - Everything in Phase 1 is complete and stable
   - CLI implementation has begun with `meld` command (formerly `ps`)
   - CLI tests are properly isolated in tests/cli directory

2. Next Priority - Continue CLI Implementation:
   - We've renamed `ps` to `meld` for better clarity and to avoid Unix command conflicts
   - The `meld` command is implemented and tested
   - Next step is implementing `oneshot` CLI
   - Then move on to `oneshotcat` CLI
   - Keep following the pattern of isolated CLI tests in tests/cli directory

3. Critical Cautions:
   - The current test suite is passing and stable - preserve this stability
   - Run ALL tests (npm test) after EVERY change to ensure no regressions
   - Implement changes slowly and methodically
   - Do not modify any existing core classes while implementing the CLI
   - If you need to modify core classes, discuss with the user first
   - Keep CLI code separate from core logic
   - Write tests before implementing each CLI component

4. Testing Strategy:
   - Use child_process.spawn for CLI tests
   - Mock file system and AI calls consistently
   - Verify both success and error cases
   - Ensure proper exit codes and error messages
   - Test error handling thoroughly
   - Test with real file system operations in CLI tests
   - Always clean up test files in afterEach hooks

5. Recent Learnings:
   - Use imported fs functions instead of require('fs') for proper mocking
   - Be careful with command naming to avoid conflicts with system commands
   - Add clear success/error output in CLI commands
   - Use consistent error formatting across all commands

Remember: Stability and reliability are our top priorities. When in doubt:
1. Write the test first
2. Implement the minimal change needed
3. Run ALL tests to verify no regressions
4. Commit only when everything passes
5. Take small, verifiable steps

---

# Implementation Plan for `meld` `oneshot` `oneshotcat`

## Phase 1: Core Implementation ✓

The following core components have been implemented and tested:

### Core Classes ✓
- ✓ Meld (src/meld.ts)
  - Handles command extraction and execution
  - Manages file I/O and error handling
  - Supports dry-run mode
  - All tests passing

- ✓ Oneshot (src/oneshot.ts)
  - Manages AI provider interactions
  - Handles variations and iterations
  - Supports system prompts
  - All tests passing

- ✓ Oneshotcat (src/oneshotcat.ts)
  - Combines Meld and Oneshot
  - Handles temporary file management
  - Provider selection based on model
  - All tests passing

### Supporting Infrastructure ✓
- ✓ Error Handling (src/errors.ts)
  - Centralized error definitions
  - Consistent error codes
  - Tests verify error behavior

- ✓ Configuration (src/config.ts)
  - Environment variables
  - RC file support
  - Option merging
  - Tests verify priority order

- ✓ AI Providers (src/providers/*)
  - Anthropic implementation
  - OpenAI implementation
  - Error handling
  - Tests with mocked responses

## Phase 2: CLI Implementation (In Progress)

### 1. bin/meld.ts ✓
- ✓ Purpose: Provide the CLI interface for meld (formerly ps)
- ✓ Implementation:
    1. Uses commander to define CLI command: meld <input.meld.md> [options]
    2. Creates new Meld(options)
    3. Calls .process() and handles output
    4. Provides clear success/error messages
- ✓ Tests: Using child_process.spawn to verify:
    - Basic command processing
    - Custom output paths
    - Overwrite protection
    - Dry-run mode

### 2. bin/oneshot.ts ❌
- Purpose: Provide the CLI interface for oneshot
- Implementation Steps:
    1. Use commander to parse [model] [promptFile] [options]
    2. Use loadConfig() to gather tokens
    3. Decide on the provider (OpenAIProvider vs. AnthropicProvider)
    4. Instantiate Oneshot and call .process()
    5. Print or write output to file
- Test: Similar approach: spawn a real CLI process, mock AI calls

### 3. bin/oneshotcat.ts ❌
- Purpose: Single-step "prompt expand + AI call" CLI
- Implementation Steps:
    1. Use commander to parse [model] [input.meld.md] [options]
    2. Create Oneshotcat({...})
    3. Call .process()
    4. Print or save to file
- Test: Provide a sample .meld.md that includes @cmd[...] calls and confirm final AI response flow

## Phase 3: Distribution & Documentation ❌

### 1. Package Preparation ❌
- Purpose: Prepare for npm distribution
- Tasks:
    1. Verify bin entries in package.json
    2. Ensure build scripts work correctly
    3. Test global installation

### 2. Documentation ❌
- Purpose: Ensure easy adoption
- Tasks:
    1. Update README.md with final CLI usage
    2. Add example commands and outputs
    3. Document configuration options

### Important Notes for Phase 2
1. Current test suite is passing (25 tests)
2. Core functionality is solid and well-tested
3. CLI implementation should not modify existing core classes
4. CLI tests are properly isolated in tests/cli directory
5. Each CLI command should have comprehensive error handling