# Documentize.Flatten

Flattens PDF form fields into static page content.

This project is one of the standalone-publishable plugins under `Plugins/`. It has no
`ProjectReference` to other projects in the repo — every file it needs is linked directly into
its `.csproj` — so it builds and publishes independently of the rest of the solution.

## Requirements

- .NET 10 SDK to build; the .NET 10 runtime is enough to run a published build.
- An Aspose Documentize license file, `documentize.lic`, placed next to the published binary (the plugin runs unlicensed/evaluation mode if it is absent).

### OS packages

This plugin renders/edits documents through Aspose. On Linux, .NET's System.Drawing/GDI+
compatibility layer (`libgdiplus`) and a font configuration (`fontconfig` + at least one font
family) are required for correct text measurement and rendering.

#### Windows
No extra OS packages are normally required — GDI+ and fonts are part of Windows. If the
document uses fonts not installed system-wide, install them normally (Settings > Fonts) so
Aspose can find them.

#### Linux (primary platform)
```bash
sudo apt-get update
sudo apt-get install -y libgdiplus fontconfig fonts-liberation fonts-dejavu-core
# Recommended for documents authored with Microsoft-compatible fonts:
sudo apt-get install -y ttf-mscorefonts-installer
fc-cache -f
```

## Build

```bash
dotnet build Documentize.Flatten.csproj -c Release
```

## Publish a standalone build

```bash
# Linux (framework-dependent, needs the .NET 10 runtime installed on the target machine)
dotnet publish Documentize.Flatten.csproj -c Release -r linux-x64 --self-contained false -o ./publish/linux

# Windows
dotnet publish Documentize.Flatten.csproj -c Release -r win-x64 --self-contained false -o ./publish/win

# Fully self-contained (no .NET runtime required on the target machine, larger output)
dotnet publish Documentize.Flatten.csproj -c Release -r linux-x64 --self-contained true -o ./publish/linux-standalone
```

## Run

### From the terminal (Linux) / cmd or PowerShell (Windows)

Using `dotnet run` from source:
```bash
dotnet run --project Documentize.Flatten.csproj -- --skip-fields value --flatten-only-fields value
```

Using a published build:
```bash
# Linux
./publish/linux/Documentize.Flatten --skip-fields value --flatten-only-fields value

# Windows (cmd.exe or PowerShell)
.\publish\win\Documentize.Flatten.exe --skip-fields value --flatten-only-fields value
```

Show all available options:
```bash
./publish/linux/Documentize.Flatten --help
```

### CLI options

| Flag | Type | Default | Description |
|---|---|---|---|
| `--skip-fields` | csv list | *(empty list)* | Comma-separated field names to leave un-flattened. |
| `--flatten-only-fields` | csv list | *(empty list)* | Comma-separated field names to flatten exclusively. |

Every plugin also accepts `--task-id <guid>` (alias `--id`) to set the task id used for the
input/output working directories; if omitted, a new GUID is generated.

### Alternative input: base64 task JSON

For compatibility with the Plugin Manager (and as a drop-in alternative to flags), the plugin
also accepts a single base64-encoded JSON argument instead of `--flags`. The JSON uses the same
PascalCase property names as the options above, plus an `"ID"` field for the task id:

```json
{ "ID": "b1e6a4b0-0000-0000-0000-000000000000", "SkipFields": [], "FlattenOnlyFields": [] }
```

```bash
python3 -c "import base64,json; print(base64.b64encode(json.dumps({ \"ID\": \"b1e6a4b0-0000-0000-0000-000000000000\", \"SkipFields\": [], \"FlattenOnlyFields\": [] }).encode()).decode())"
./publish/linux/Documentize.Flatten <base64-string-from-above>
```

### Manager hot-process mode

`--pool` puts the plugin into the Plugin Manager's stdin/stdout worker-pool protocol
(`READY` / `{taskId} {base64}` per line / `DONE:{taskId}` or `FAIL:{taskId}:{msg}`).
This mode is only used by `Documentize.Plugin.Manager` — not intended for direct/manual use.

## Exit codes

| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | The task ran but failed (see stderr for the exception) |
| 2 | Usage/argument error (missing required option, invalid value, `--help`) |
