podletjs/ROADMAP.md

JavaScript port of Podlet - Generate Podman Quadlet files from Docker run commands and compose files

# PodletJS Roadmap

## Current Status: ✅ Feature Complete (v1.0.0)

PodletJS successfully implements the core functionality of the original Podlet (Rust) with:
- **Docker run command parsing** (40+ flags supported)
- **Docker Compose file parsing** (multi-service with dependencies)
- **Quadlet file generation** (complete systemd integration)
- **Comprehensive testing** (200+ test cases)

**The tool is production-ready for 90%+ of real-world use cases.**

---

## Future Enhancements

#### 1. Pod Generation Support
**Status**: Not implemented  
**Effort**: Medium  
**Impact**: High for multi-container deployments

- [ ] `--pod` flag support for compose files
- [ ] Generate `.pod` Quadlet files automatically
- [ ] Pod-level port publishing (move ports from containers to pod)
- [ ] Container-to-pod linking

**Use Case**: Convert compose services into a single Podman pod instead of separate containers.

```yaml
# Input: compose with --pod flag
services:
  web:
    ports: ["8080:80"]
  api:
    ports: ["3000:3000"]

# Output: 
# - app.pod (with both ports)
# - app-web.container (linked to pod)
# - app-api.container (linked to pod)
```

---

#### 2. Build Context Handling
**Status**: Placeholder implementation  
**Effort**: Medium  
**Impact**: Medium for development workflows

- [ ] Parse `build` sections in compose files
- [ ] Generate `.build` Quadlet files
- [ ] Handle build context paths and Dockerfiles
- [ ] Build argument support
- [ ] Multi-stage build support

**Current Limitation**: Services with `build` get placeholder image names like `servicename.build`.

```yaml
# Currently limited support
services:
  app:
    build:
      context: ./app
      dockerfile: Dockerfile.prod
      args:
        NODE_ENV: production
```

---

#### 3. Podman Version Compatibility
**Status**: Not implemented  
**Effort**: Low-Medium  
**Impact**: Medium for older Podman versions

- [ ] Podman version detection/specification
- [ ] Feature downgrading for older versions
- [ ] Quadlet option compatibility matrix
- [ ] Validation warnings for unsupported features

**Use Case**: Ensure generated Quadlet files work with specific Podman versions (4.4, 4.5, 5.0, etc.).

---

#### 4. CLI Tool Interface
**Status**: Not implemented  
**Effort**: Low  
**Impact**: High for end-user experience

- [ ] Command-line interface (like original Podlet)
- [ ] File input/output options
- [ ] Batch processing support
- [ ] `--file`, `--unit-directory` flags
- [ ] Progress reporting for large compose files

**Use Case**: 
```bash
npx podlet-js docker run nginx:latest
npx podlet-js compose docker-compose.yml --output ./quadlets/
```

---

#### 5. Extended Compose Features
**Status**: Partial/Not implemented  
**Effort**: Medium-High  
**Impact**: Low-Medium (edge cases)

- [ ] **Configs** support (when Quadlet supports it)
- [ ] **Secrets** support (when Quadlet supports it)
- [ ] **Extension fields** (`x-*`)
- [ ] **Advanced networking** (custom drivers, IPAM)
- [ ] **Deploy** section (replicas, resources, placement)
- [ ] **Profiles** support

**Current Status**: These features are intentionally not supported as Quadlet/Podman doesn't have equivalents yet.

---

#### 6. Developer Experience Improvements
**Status**: Basic implementation  
**Effort**: Low  
**Impact**: Medium for developers

- [ ] **TypeScript definitions** for better IDE support
- [ ] **VS Code extension** for Quadlet syntax highlighting
- [ ] **JSON Schema** for compose validation
- [ ] **Plugin system** for custom transformations
- [ ] **Debug mode** with detailed transformation logs

---

#### 7. Advanced Output Options
**Status**: Basic implementation  
**Effort**: Low-Medium  
**Impact**: Medium for integration

- [ ] **YAML output** format (alternative to INI)
- [ ] **JSON output** for programmatic use
- [ ] **Kubernetes YAML** generation (like original Podlet)
- [ ] **Template system** for custom output formats
- [ ] **Diff mode** for comparing changes

---

### 🐛 Known Limitations & Fixes

#### Minor Issues
- [ ] Some docker run flags only added to `PodmanArgs` (not native Quadlet options)
- [ ] Build contexts generate placeholder images instead of proper build files
- [ ] Network aliases handling could be more sophisticated
- [ ] Volume mount option parsing could be more robust

#### Compatibility Gaps
- [ ] Some advanced Podman-specific flags not supported
- [ ] Compose interpolation (environment variable substitution)
- [ ] Compose `include` directive
- [ ] Docker Swarm specific features (by design - not applicable)

---

## Priority Ranking

### 🔥 High Priority (would significantly improve utility)
1. **CLI Tool Interface** - Makes it usable as a standalone tool
2. **Pod Generation Support** - Major feature gap from original Podlet
3. **Build Context Handling** - Important for development workflows

### 🌟 Medium Priority (nice to have)
1. **Podman Version Compatibility** - Important for enterprise use
2. **TypeScript Definitions** - Better developer experience
3. **Advanced Output Options** - Integration flexibility

### 🔮 Low Priority (future/edge cases)
1. **Extended Compose Features** - Waiting on Podman/Quadlet support
2. **Plugin System** - Over-engineering for current scope
3. **VS Code Extension** - Separate project territory

---

## Contributing

Send pull a requests if you're interested in implementing any of these features.