@meldscience/meld/docs/PLAN-3.md

pipeable one-shot prompt scripting toolkit

# Phase 2 Plan: Enhancements

### 1. Use a Non-Blocking File I/O in PromptScript

- Change readFileSync to readFile (in process() and anywhere else it appears).
- Return an async promise for reading, ensuring consistent async usage.

### 2. Limit Synchronous Shell Calls

- In PromptScript.executeCommand(), replace execSync with exec or spawn with a callback/promise wrapper.
- This will prevent the entire process from blocking and allow more flexible error handling in async flow.

### 3. Consolidate Error Handling for Command Execution

- When a shell command fails, incorporate a more detailed message including stdout/stderr (not just the error message).
- Wrap the output in code fences to provide better readability of partial outputs.

### 4. Add a Temporary File Abstraction in Oneshotcat

- Instead of hardcoding '.temp-oneshot-expanded.md', create a helper (e.g., createTempFile(content): string) that:
  - Generates a unique filename (e.g., using a UUID).
  - Writes content to that file.
- This avoids collisions if multiple Oneshotcats run in parallel.

### 5. Add an In-Memory Prompt Mode in Oneshot

- Modify OneshotOptions to accept either a promptFile or a direct promptText.
- If promptText is provided, skip reading a file.
- This gives more flexibility and avoids creating a temp file if you already have the expanded text.

### 6. Refine Variation Prompt Formatting

- When merging variation prompts (v) into the user prompt, separate them more clearly (e.g., add a markdown separator or --- Variation: v ---) to avoid confusion.
- This helps identify which portion is the original user prompt and which is the variation.

### 7. Add Logging/Debug Option

- In each CLI script (ps.ts, oneshot.ts, oneshotcat.ts), add a --debug boolean.
	•	If set, log each major step to stdout (e.g., “Reading file X”, “Executing command Y”, “Sending request to model Z”).
- Helps with troubleshooting command failures and AI calls.

### 8. Enhance Configuration Loading

- In config.ts, allow specifying an alternate path for a config file via --config <path>.
- Merges it last (highest priority) on top of existing environment and .rc file data.
- Improves user control over environment- or project-specific configurations.

### 9. Add Basic Validation for Variation Prompts

- In Oneshot.process(), if a variation is empty or whitespace, skip it.
- Prevents sending empty or meaningless prompts to the AI provider.

### 10. Include files Field or .npmignore in package.json

- Ensure that only necessary files (src, bin, package.json, README) get published, excluding tests and temp files.
- Keeps package size smaller and avoids accidental publication of local test data or .temp files.

### 11. Add a .rc File for Custom Configuration

- Create a .rc file in the user's home directory (e.g., ~/.oneshotrc) to store custom configurations.
- This allows users to set defaults once and have them automatically applied to all CLI calls.
- Example: { "model": "claude-3-5-sonnet-20240620", "temperature": 0.5 }