filegoblin

A simple, privacy-first toolkit for converting office documents to PDF and merging PDFs.

What is filegoblin?

filegoblin helps you handle everyday document tasks without relying on online converters or complex software installations. It runs entirely on your local machine - no cloud services, no data upload, no privacy concerns.

Phase 1 Status (Current):

• ✅ CLI structure is complete and usable
• ✅ convert command accepts input/output files and flags
• ✅ merge command exists but is not yet implemented
• ⚠️ No real document conversion happens in Phase 1
• The noop renderer logs conversion requests but doesn't transform files

Phase 1 is about infrastructure, not features. The goal is a clean, well-tested CLI that's ready for real conversion logic in Phase 2.

Installation

From source

Requirements:

• Go 1.20 or later

# Clone the repository
git clone https://github.com/hey-granth/filegoblin.git
cd filegoblin

# Build the binary
make build

# Or build directly with go
go build -o filegoblin ./cmd/filegoblin

Usage

Basic Commands

Run without arguments to see help:

./filegoblin

Convert Command (Phase 1: noop only)

Convert a document to PDF:

./filegoblin convert --input document.docx --output document.pdf

Short flags:

./filegoblin convert -i slides.pptx -o slides.pdf

Specify format explicitly:

./filegoblin convert -i report.docx -o report.pdf --format pdf

Note: In Phase 1, this only logs the conversion request. No actual file transformation occurs.

Merge Command (Not Yet Implemented)

The merge command is planned for a future phase:

./filegoblin merge --inputs file1.pdf file2.pdf --output combined.pdf

Currently returns: "not yet implemented in Phase 1"

Development

Running Tests

make test

Or directly:

go test ./...

Linting

make lint

This runs:

• gofmt to check code formatting
• go vet to catch common mistakes

Building

make build

Cleaning

make clean

Architecture (for contributors)

filegoblin/
├── cmd/                    # CLI commands (Cobra)
│   ├── root.go            # Root command and context wiring
│   ├── convert.go         # Convert command implementation
│   └── merge.go           # Merge command (stub)
├── internal/
│   ├── conversion/        # Conversion abstraction layer
│   │   ├── renderer.go    # Renderer interface and Request type
│   │   ├── factory.go     # Factory for creating renderers
│   │   ├── noop.go        # No-op renderer (Phase 1)
│   │   └── conversion_test.go  # Tests
│   └── logx/              # Logging package
│       ├── logx.go        # Logger implementation
│       └── logx_test.go   # Tests
└── cmd/filegoblin/
    └── main.go            # Application entry point

Key Design Decisions

1. Interface-based architecture: The Renderer interface allows swapping conversion backends without changing CLI code.

2. Context everywhere: All operations accept a context.Context for future cancellation/timeout support.

3. No external dependencies for conversion: Phase 1 deliberately avoids LibreOffice, cloud APIs, or platform-specific automation.

4. Comments for beginners: Code is heavily commented to help new Go developers understand patterns and idioms.

Phase 1 Limitations

This is Phase 1 infrastructure. Here's what's explicitly NOT included:

• ❌ Real document conversion (DOCX → PDF, PPTX → PDF, etc.)
• ❌ PDF merging
• ❌ LibreOffice integration
• ❌ Cloud/external conversion services
• ❌ GUI or web interface

These will be addressed in future phases once the foundation is solid.

Contributing

Contributions are welcome! When contributing:

1. Follow existing code style (run make lint)
2. Add tests for new functionality
3. Comment your code heavily (assume readers are new to Go)
4. Keep functions small and focused
5. Avoid adding external dependencies without discussion

License

MIT License - see LICENSE file for details.

Philosophy

filegoblin is built around three principles:

1. Privacy: All processing happens locally. Your documents never leave your machine.
2. Simplicity: Clean CLI, clear errors, no surprises.
3. Clarity: Code is written to be learned from, not just used.

Phase 1 is deliberately minimal - we build a solid foundation before adding features.