chore: initial commit

README.md

@@ -0,0 +1,122 @@
+# @stevanfreeborn/png2pdf
+
+Convert PNG images to PDF files from the command line.
+
+## Requirements
+
+- Node.js 20 or newer
+- npm
+
+## Install
+
+Run without installing:
+
+```powershell
+npx @stevanfreeborn/png2pdf .\image.png
+```
+
+Install globally:
+
+```powershell
+npm install --global @stevanfreeborn/png2pdf
+png2pdf --help
+```
+
+## Local development
+
+```powershell
+cd C:\Users\sfree\Repositories\png2pdf
+npm install
+npm run build
+```
+
+Run the local development build directly:
+
+```powershell
+npm run dev -- .\image.png
+```
+
+Or link the built CLI so `png2pdf` is available on your PATH:
+
+```powershell
+npm link
+png2pdf --help
+```
+
+## Usage
+
+```text
+png2pdf <input...> [options]
+```
+
+Inputs can be PNG files, directories, or glob patterns. PNG extensions are
+matched case-insensitively. Directory inputs are non-recursive unless
+`--recursive` is supplied.
+
+### Examples
+
+Create a PDF beside each PNG:
+
+```powershell
+png2pdf .\screenshots\login.png
+png2pdf .\screenshots
+```
+
+Write batch output to a directory:
+
+```powershell
+png2pdf ".\screenshots\**\*.png" --recursive --out-dir .\pdfs
+```
+
+Combine images into one multi-page PDF:
+
+```powershell
+png2pdf ".\screenshots\*.png" --merge --output .\album.pdf
+```
+
+Fit images onto A4 pages with a margin:
+
+```powershell
+png2pdf .\diagram.png --page-size a4 --margin 18
+```
+
+## Options
+
+| Option                | Description                                      |
+| --------------------- | ------------------------------------------------ |
+| `-d, --out-dir <dir>` | Write batch PDFs to this directory.              |
+| `-m, --merge`         | Combine all PNGs into one multi-page PDF.        |
+| `-o, --output <file>` | Output path for merged mode. Requires `--merge`. |
+| `-r, --recursive`     | Recurse into directory inputs.                   |
+| `--page-size <size>`  | `fit`, `a4`, or `letter`. Defaults to `fit`.     |
+| `--margin <points>`   | Page margin in PDF points. Defaults to `0`.      |
+| `--dpi <number>`      | DPI used to size `fit` pages. Defaults to `96`.  |
+| `-f, --force`         | Overwrite existing output files.                 |
+| `-q, --quiet`         | Suppress success and progress output.            |
+| `-V, --version`       | Print the version.                               |
+| `-h, --help`          | Print help.                                      |
+
+## Behavior
+
+- By default, every PNG becomes its own PDF beside the source file.
+- With `--merge`, all PNGs become pages in one PDF, in sorted path order.
+- `fit` pages use the image's physical dimensions at the selected DPI plus
+  margins.
+- `a4` and `letter` pages fit and center the image while preserving its aspect
+  ratio. Page orientation follows the image orientation.
+- Transparent PNGs keep their alpha channel.
+- Existing files are not overwritten unless `--force` is used.
+- In batch mode, failures are reported without stopping other conversions. The
+  command exits with code `1` if any conversion fails.
+- Batch output collisions, such as two inputs with the same basename and one
+  output directory, are rejected before conversion starts.
+
+## Development
+
+```powershell
+npm run typecheck
+npm run lint
+npm test
+npm run build
+npm run format:check
+```