formatferry 0.1.1

package/README.md

@@ -0,0 +1,230 @@
+# FormatFerry CLI
+
+Convert HTML, DOCX, PDF, XLSX, and CSV to clean Markdown from the command line.
+
+```bash
+npm install -g formatferry
+```
+
+Requires Node.js 18+.
+
+## Quick Start
+
+```bash
+# Pipe HTML from stdin
+echo '<h1>Hello</h1><p>World</p>' | formatferry
+
+# Convert a file
+formatferry -i document.html -o output.md
+
+# Convert a Word document
+formatferry -i report.docx -o report.md
+
+# Convert a PDF
+formatferry -i paper.pdf -o paper.md
+
+# Convert a spreadsheet
+formatferry -i data.xlsx -o data.md
+```
+
+## Commands
+
+### Convert (default)
+
+The default command converts input to Markdown.
+
+```
+formatferry [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-i, --input <path>` | Input file path (.html, .htm, .docx, .pdf, .xlsx, .csv) |
+| `-o, --output <path>` | Output file path (defaults to stdout) |
+| `-f, --format <format>` | Markdown format (default: `github`) |
+| `--url <url>` | Fetch and convert a web article (requires API key) |
+| `--batch <glob>` | Batch convert files matching a glob pattern (Premium) |
+| `--output-dir <dir>` | Output directory for batch mode |
+
+#### Input Modes
+
+1. **stdin** — pipe HTML content directly:
+   ```bash
+   cat page.html | formatferry
+   pbpaste | formatferry          # macOS clipboard
+   ```
+
+2. **File** — use `--input` for local files:
+   ```bash
+   formatferry -i report.docx
+   formatferry -i data.xlsx -f commonmark
+   ```
+
+3. **URL** — fetch and extract a web article (requires API key):
+   ```bash
+   formatferry --url https://example.com/article
+   ```
+
+#### Supported Formats
+
+| Format | Flag Value | Description |
+|--------|-----------|-------------|
+| GitHub Flavored Markdown | `github` | Default. Tables, task lists, strikethrough |
+| CommonMark | `commonmark` | Strict CommonMark spec |
+| Slack | `slack` | Slack mrkdwn syntax |
+| Discord | `discord` | Discord Markdown |
+| Reddit | `reddit` | Reddit Markdown |
+| Confluence | `confluence` | Confluence wiki markup |
+| R Markdown | `rmarkdown` | R Markdown with YAML front matter |
+| Custom | `custom` | Base Markdown with no format-specific rules |
+
+#### Supported File Types
+
+| Extension | Type | Notes |
+|-----------|------|-------|
+| `.html`, `.htm` | HTML | Rich text, web pages, Google Docs exports |
+| `.docx` | Word | Microsoft Word documents (via Mammoth.js) |
+| `.pdf` | PDF | Text extraction (via PDF.js) |
+| `.xlsx` | Excel | Spreadsheets with multi-sheet support (via SheetJS) |
+| `.csv` | CSV | Comma-separated data files |
+
+### Auth
+
+Manage license keys and API keys.
+
+```
+formatferry auth [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--license-key <key>` | Activate a license key |
+| `--api-key <key>` | Activate an API key |
+| `--status` | Show current license/plan status |
+| `--logout` | Remove stored credentials |
+
+#### License Key
+
+```bash
+# Activate a license key
+formatferry auth --license-key FF-PREM-XXXX-XXXX
+
+# Check status
+formatferry auth --status
+
+# Remove credentials
+formatferry auth --logout
+```
+
+#### API Key
+
+API keys enable URL extraction and are available through subscription plans.
+
+```bash
+# Activate an API key
+formatferry auth --api-key ff_your_api_key_here
+
+# Check plan and quota
+formatferry auth --status
+```
+
+#### Plans
+
+| Plan | Features | Batch | URL Extraction |
+|------|----------|-------|----------------|
+| Free | Basic conversion | No | No |
+| Pro | Atlassian parsing, token optimization, batch | Yes | Yes |
+| Credits | Pay-per-use URL extraction | No | Yes |
+| Agent Starter | All Pro features + rate limit | Yes | Yes |
+| Agent Pro | All Pro features + higher rate limit | Yes | Yes |
+| Agent Scale | All Pro features + highest rate limit | Yes | Yes |
+
+### Batch Convert (Premium)
+
+Convert multiple files at once using glob patterns.
+
+```bash
+# Convert all HTML files in a directory
+formatferry --batch "docs/*.html"
+
+# Convert to a specific output directory
+formatferry --batch "**/*.html" --output-dir converted/
+
+# Convert with a specific format
+formatferry --batch "*.docx" -f commonmark --output-dir output/
+```
+
+Batch mode requires a Premium license or a Pro/Agent API key. Output files are written with `.md` extension alongside the source files, or to `--output-dir` if specified.
+
+The batch summary reports success/failure counts:
+```
+Batch complete: 5 succeeded, 1 failed, 6 total
+```
+
+Files that fail conversion (e.g., unsupported types in a broad glob) are logged to stderr and skipped — remaining files continue processing.
+
+## Configuration
+
+Credentials are stored in a platform-specific config file:
+
+| Platform | Path |
+|----------|------|
+| macOS/Linux | `~/.config/formatferry/config.json` |
+| Windows | `%APPDATA%\formatferry\config.json` |
+
+The config file is created with `0600` permissions (owner read/write only) on POSIX systems.
+
+### Entitlement Caching
+
+License keys are validated against the FormatFerry license server on each CLI invocation with a 2-second timeout. If the server is unreachable:
+
+- **Cache < 7 days old**: Cached entitlements are used
+- **Cache > 7 days old**: Falls back to free tier with a warning
+
+Revoked keys are automatically removed from the config.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error (invalid input, missing file, auth failure, unsupported format) |
+
+All errors are written to stderr. Conversion output goes to stdout (unless `--output` is specified).
+
+## Examples
+
+```bash
+# Convert clipboard HTML to Markdown (macOS)
+pbpaste | formatferry | pbcopy
+
+# Convert a Google Docs export
+formatferry -i "My Document.html" -o document.md
+
+# Convert all Word docs in a project
+formatferry --batch "reports/**/*.docx" --output-dir markdown/
+
+# Extract and convert a web article
+formatferry --url https://blog.example.com/post -o article.md
+
+# Use CommonMark format for strict compatibility
+formatferry -i page.html -f commonmark
+
+# Pipe through other tools
+curl -s https://example.com | formatferry -f reddit
+```
+
+## Development
+
+```bash
+# Install dependencies (from repo root)
+npm install
+
+# Run tests
+npm test --workspace=packages/cli
+
+# Build
+npm run build --workspace=packages/cli
+```
+
+See [PUBLISHING.md](./PUBLISHING.md) for npm publish instructions.