Add manifest-driven extensions and CLI support

Introduce a manifest-driven external command layer and CLI integration. Adds a full extension implementation (src/extensions/*) with manifest schema, discovery, validation, and runtime contract (JSON stdin payload + env vars), plus CLI flags --list-plugins, --run-plugin and --plugin-dir and plumbing to collect selected archive entries for commands. Documentation added/updated (docs/EXTENSIONS.md, CORE_LIBRARY.md, SUPPORT_MATRIX.md, README and DEPENDENCIES updates) and a new pakfu_core umbrella target/header for non-UI code. Build/test infra enhanced: meson option to enable fuzzing, many fuzz/test targets added, and a GitHub workflow (/.github/workflows/hardening.yml) to run sanitizer+fuzzing CI.

Author: themuffinator

.github/workflows/hardening.yml

@@ -0,0 +1,57 @@
+name: parser-hardening
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  sanitize-and-fuzz:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      CC: clang
+      CXX: clang++
+      ASAN_OPTIONS: detect_leaks=0
+      UBSAN_OPTIONS: print_stacktrace=1
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+
+      - name: Install Meson + Ninja
+        run: python -m pip install --upgrade pip meson ninja
+
+      - name: Install Clang
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang lld
+
+      - name: Install Qt
+        uses: jurplel/install-qt-action@v4
+        with:
+          version: "6.10.1"
+          arch: "linux_gcc_64"
+          modules: qtmultimedia qtimageformats
+
+      - name: Configure Hardening Build
+        run: >
+          meson setup builddir
+          --backend ninja
+          --buildtype=debugoptimized
+          -Dvulkan_preview=disabled
+          -Dfuzzing=enabled
+          -Db_sanitize=address,undefined
+
+      - name: Build
+        run: meson compile -C builddir
+
+      - name: Run Sanitized Tests
+        run: meson test -C builddir --print-errorlogs

README.md

@@ -71,6 +71,8 @@ PakFu can also check for updates at runtime (GUI) and via CLI (`--check-updates`
 - Nested container mounting (open archives inside archives).
 - One-click `Extract Selected` and `Extract All` workflows for the active archive tab.
 - Batch conversion tool for selected assets with category tabs (images, video, archives, models, sound, maps, text, other).
+- Manifest-driven extension commands for archive-aware external tools in the GUI and CLI.
+- A reusable `pakfu_core` static library for non-UI archive, format, search, and extension code.
 - Image batch conversion supports output to all supported image formats (`png`, `jpg`, `jpeg`, `bmp`, `gif`, `tga`, `tif`, `tiff`, `pcx`, `wal`, `swl`, `mip`, `lmp`, `ftx`, `dds`) with format-aware settings (quality, compression, palette source, dithering, alpha threshold, embedded palette where applicable).
 - Modern platform-native open/save/folder dialogs with standard breadcrumbs/bookmarks and robust cross-platform behavior.
 - 3D preview renderer selection with Vulkan/OpenGL behavior and fallback.
@@ -82,6 +84,10 @@ PakFu can also check for updates at runtime (GUI) and via CLI (`--check-updates`
 
 ## Supported Formats
 
+For the fixture-backed support contract and current verification status, see
+[`docs/SUPPORT_MATRIX.md`](docs/SUPPORT_MATRIX.md). The tables below are the
+quick reference.
+
 ### Archive And Container Support
 | Type | Extensions | Open/List | Extract | Save/Rebuild |
 |---|---|---|---|---|
@@ -144,6 +150,19 @@ meson setup builddir --backend ninja
 meson compile -C builddir
 ```
 
+### Core Library Target
+```sh
+meson compile -C builddir pakfu_core
+meson test -C builddir core-api-smoke
+```
+
+### Parser Hardening Build
+For parser hardening smoke tests with libFuzzer + sanitizers:
+```sh
+CC=clang CXX=clang++ meson setup builddir-fuzz --backend ninja --buildtype=debugoptimized -Dvulkan_preview=disabled -Dfuzzing=enabled -Db_sanitize=address,undefined
+meson test -C builddir-fuzz --print-errorlogs
+```
+
 ### Run
 ```sh
 ./builddir/src/pakfu
@@ -169,13 +188,16 @@ Core actions:
 - `--save-as <archive>` : rebuild selected entries into a new archive.
 - `--convert <format>` : convert selected images to a supported image-writer output (`png`, `jpg`, `bmp`, `gif`, `tga`, `tiff`, `pcx`, `wal`, `swl`, `mip`, `lmp`, `ftx`, `dds`) or IDWAV audio to `wav`.
 - `--preview-export <entry>` : export the CLI preview rendition of one entry; images write an image file, text and binary entries write bytes.
+- `--list-plugins` : list discovered extension commands.
+- `--run-plugin <plugin[:command]>` : run one extension command against the loaded archive.
 - `--check-updates` : query GitHub Releases.
 - `--qa-practical` : run practical archive-ops smoke QA (selection/marquee/modifier checks).
 
 Archive selection and mounting:
-- `--entry <path>` : limit `--list`, `--extract`, `--save-as`, or `--convert` to an exact archive entry. Repeat for multiple entries.
-- `--prefix <dir>` : limit `--list`, `--extract`, `--save-as`, or `--convert` to entries under a directory prefix. Repeat for multiple prefixes.
+- `--entry <path>` : limit `--list`, `--extract`, `--save-as`, `--convert`, or `--run-plugin` to an exact archive entry. Repeat for multiple entries.
+- `--prefix <dir>` : limit `--list`, `--extract`, `--save-as`, `--convert`, or `--run-plugin` to entries under a directory prefix. Repeat for multiple prefixes.
 - `--mount <entry>` : mount a nested archive entry first, then run the requested action against the mounted archive.
+- `--plugin-dir <dir>` : add an extension search directory (repeat for more than one).
 
 Save-as options:
 - `--format <pak|sin|zip|pk3|pk4|pkz|wad|wad2>` : choose the output archive format. If omitted, PakFu infers it from `--save-as`.
@@ -205,6 +227,8 @@ Examples:
 ./builddir/src/pakfu --cli --convert png --prefix textures -o converted_textures path/to/archive.pk3
 ./builddir/src/pakfu --cli --preview-export gfx/conback.lmp -o previews path/to/pak0.pak
 ./builddir/src/pakfu --cli --mount nested/maps.pk3 --list path/to/archive.pk3
+./builddir/src/pakfu --cli --list-plugins
+./builddir/src/pakfu --cli --run-plugin example:inspect-cfg --entry scripts/autoexec.cfg path/to/archive.pk3
 ./builddir/src/pakfu --cli --check-updates
 ./builddir/src/pakfu --cli --qa-practical
 ./builddir/src/pakfu --cli --list-game-installs
@@ -235,6 +259,7 @@ Examples:
   - Double-click nested container files to mount and browse in-place.
   - Multiple nested layers are supported.
   - `File` menu and context menu actions support `Extract Selected`, `Extract All` (archive views), and `Convert Selected Assets...`.
+  - The `Extensions` menu discovers manifest-backed external tools and validates the current archive selection before launch.
 - Safety:
   - Pure PAK Protector is enabled by default for official archives (read-only protection with Save As workflow).
 
@@ -295,7 +320,9 @@ For full policy details, see `docs/RELEASES.md`.
 | `QT_MEDIA_BACKEND` | Override Qt multimedia backend selection. |
 
 ## Documentation
+- `docs/CORE_LIBRARY.md` : `pakfu_core` scope, umbrella header, and intended build contract.
 - `docs/DEPENDENCIES.md` : dependency baseline and optional libraries.
+- `docs/EXTENSIONS.md` : manifest schema, JSON payload contract, and CLI/GUI extension workflow.
 - `docs/QA_ARCHIVE_FILE_OPS.md` : practical QA checklist for selection, drag/drop, cut/copy/paste, and modifiers.
 - `docs/RELEASES.md` : versioning, release rules, and asset contract.
 - `docs/UI_BUTTON_ICONS.md` : UI action icon inventory.

docs/CORE_LIBRARY.md

@@ -0,0 +1,57 @@
+# PakFu Core Library
+
+PakFu now builds a non-UI static library target named `pakfu_core`.
+
+This is the first stable seam for archive, format, search, game-profile, and
+extension-contract code that does not depend on the desktop UI layer.
+
+## Scope
+
+`pakfu_core` includes:
+- archive loading and extraction
+- PAK/WAD/ZIP/resources backends
+- archive search indexing
+- image/model/cinematic/BSP parsing helpers
+- game profile and auto-detect helpers
+- manifest-driven extension command loading/execution
+
+`pakfu_core` does not include:
+- Qt Widgets or viewer windows
+- `PakTab`, `MainWindow`, or preview widgets
+- updater UI flow
+- platform shell integration
+
+## Umbrella header
+
+The stable umbrella header is:
+
+```text
+src/pakfu_core.h
+```
+
+It aggregates the primary non-UI APIs used by the app, tests, and helper tools.
+
+## Build target
+
+Build just the core layer:
+
+```sh
+meson compile -C builddir pakfu_core
+```
+
+Build the core API smoke test:
+
+```sh
+meson compile -C builddir core_api_smoke_test
+meson test -C builddir core-api-smoke
+```
+
+## Intended use
+
+This target is meant to:
+- reduce UI-to-backend coupling
+- give tests and helper binaries a stable link target
+- provide a clean place for future CLI and scripting integrations
+
+It is not yet installed as a packaged SDK, and its API is stable by repository
+contract rather than by external semantic-version promises.

docs/DEPENDENCIES.md

@@ -31,6 +31,7 @@
 
 ## Planned / Optional
 - Vulkan runtime + drivers (enables the Vulkan 3D preview renderer; OpenGL remains the fallback)
+- Clang/LLVM with libFuzzer support (parser fuzzing targets and sanitizer CI workflow)
 - OGG (if not handled by Qt Multimedia on a platform)
 - Third-party decoding libraries as needed, scoped to formats that Qt does not
   cover on all platforms

docs/EXTENSIONS.md

@@ -0,0 +1,168 @@
+# PakFu Extensions
+
+PakFu's first extension phase is a manifest-driven external command layer.
+Extensions are discovered from JSON manifests, and PakFu launches the declared
+command with a structured JSON payload on `stdin`.
+
+This phase is intentionally small:
+- manifest discovery
+- read-only archive context
+- selected-entry materialization to temporary files/directories
+- GUI launch from the `Extensions` menu
+- CLI launch with `--list-plugins` and `--run-plugin`
+
+There is no binary plugin ABI yet, and there is no write-back/import contract
+from extensions into archives in this phase.
+
+## Discovery
+
+PakFu searches these directories for manifests:
+- `<pakfu-dir>/plugins`
+- `./plugins` from the current working directory
+- the platform app-data `plugins` directory for PakFu
+
+CLI callers can add more search roots with:
+
+```text
+--plugin-dir <dir>
+```
+
+PakFu looks for either:
+- `plugin.json`
+- `*.pakfu-plugin.json`
+
+## Manifest schema
+
+Schema version: `1`
+
+Minimal example:
+
+```json
+{
+  "schema_version": 1,
+  "id": "example",
+  "name": "Example Tools",
+  "description": "Sample extension commands.",
+  "commands": [
+    {
+      "id": "inspect-cfg",
+      "name": "Inspect CFG",
+      "description": "Run an external checker on one selected CFG file.",
+      "command": ["python", "inspect_cfg.py"],
+      "working_directory": ".",
+      "requires_entries": true,
+      "allow_multiple": false,
+      "extensions": ["cfg"]
+    }
+  ]
+}
+```
+
+## Manifest fields
+
+Top-level fields:
+- `schema_version` : currently `1`
+- `id` : plugin identifier (`A-Z`, `a-z`, `0-9`, `_`, `.`, `-`)
+- `name` : display label
+- `description` : optional description
+- `commands` : array of command objects
+
+Command fields:
+- `id` : command identifier
+- `name` : display label
+- `description` : optional description
+- `command` : argv array; first item is the executable
+- `working_directory` : optional; relative paths resolve from the manifest directory
+- `requires_entries` : optional boolean, default `false`
+- `allow_multiple` : optional boolean, default `true`
+- `extensions` : optional list of allowed selected-file extensions without dots
+
+## Execution contract
+
+PakFu launches the external process with:
+- JSON payload on `stdin`
+- separate `stdout` and `stderr` capture
+- environment variables:
+  - `PAKFU_EXTENSION_SCHEMA`
+  - `PAKFU_EXTENSION_PLUGIN_ID`
+  - `PAKFU_EXTENSION_COMMAND_ID`
+
+Relative executable paths are resolved from the command's working directory.
+
+## JSON payload
+
+The payload schema id is:
+
+```text
+pakfu-extension/v1
+```
+
+Example payload:
+
+```json
+{
+  "schema": "pakfu-extension/v1",
+  "command": {
+    "plugin_id": "example",
+    "plugin_name": "Example Tools",
+    "command_id": "inspect-cfg",
+    "command_name": "Inspect CFG",
+    "description": "Run an external checker on one selected CFG file.",
+    "manifest_path": "/absolute/path/to/plugin.json"
+  },
+  "archive": {
+    "path": "/absolute/path/to/archive.pk3",
+    "readable_path": "/absolute/path/to/archive.pk3",
+    "format": "zip",
+    "mounted_entry": "",
+    "current_prefix": "scripts/",
+    "quakelive_encrypted_pk3": false,
+    "wad3": false,
+    "doom_wad": false
+  },
+  "entries": [
+    {
+      "archive_name": "scripts/autoexec.cfg",
+      "local_path": "/absolute/path/to/temp/scripts/autoexec.cfg",
+      "is_dir": false,
+      "size": 128,
+      "mtime_utc_secs": 1714156800
+    }
+  ]
+}
+```
+
+## GUI behavior
+
+Open an archive tab, select entries if the command requires them, then use:
+
+```text
+Extensions -> <command>
+```
+
+PakFu validates the current selection before launch. If a command is disabled in
+the menu, its tooltip explains why.
+
+## CLI behavior
+
+List discovered commands:
+
+```text
+pakfu --cli --list-plugins
+```
+
+Run a command against an archive:
+
+```text
+pakfu --cli --run-plugin example:inspect-cfg path/to/archive.pk3
+```
+
+Pass selected files with existing archive selectors:
+
+```text
+pakfu --cli --run-plugin example:inspect-cfg --entry scripts/autoexec.cfg path/to/archive.pk3
+pakfu --cli --run-plugin example:inspect-cfg --prefix scripts path/to/archive.pk3
+```
+
+In the CLI path for this phase, `--entry` and `--prefix` pass matching files as
+materialized temp files to the extension command.