diff --git a/notes/bf-5kafx.md b/notes/bf-5kafx.md new file mode 100644 index 0000000..27d425b --- /dev/null +++ b/notes/bf-5kafx.md @@ -0,0 +1,132 @@ +# pdftract CLI Command Execution Documentation + +**Bead ID:** bf-5kafx +**Date:** 2026-07-05 +**Task:** Document command and execution results + +## Commands Executed + +### 1. Binary Location and Version +```bash +# Binary path +target/release/pdftract + +# Version info (from doctor output) +pdftract version: 0.1.0 (git: f95f38009fe7a58d1a35127eadd...) +Binary size: 17.8 MB +``` + +### 2. Help Command +```bash +pdftract --help +``` +**Exit Code:** 0 (success) +**Execution Time:** ~0.002 seconds +**Output Format:** Structured text with command listings and descriptions +**File Path:** `/home/coding/pdftract/target/release/pdftract` + +### 3. Diagnostic Listing +```bash +pdftract list-diagnostics +``` +**Exit Code:** 0 (success) +**Execution Time:** ~0.002 seconds +**Output Format:** Hierarchical diagnostic codes (100 codes) +- STRUCT_*: Structure-related diagnostics +- XREF_*: Cross-reference diagnostics +- STREAM_*: Stream diagnostics + +### 4. Environment Health Check +```bash +pdftract doctor +``` +**Exit Code:** 0 (success) +**Execution Time:** ~0.002 seconds +**Output Format:** Table format with status columns + +### 5. Extraction Commands + +#### Valid PDF (base_hello.pdf) +```bash +pdftract extract tests/document_model/fixtures/base_hello.pdf --json - +``` +**Exit Code:** 0 (success) +**Execution Time:** 0.002 seconds +**Output Format:** Valid JSON to stdout +**File Paths:** +- Input: `tests/document_model/fixtures/base_hello.pdf` +- Output: stdout + +#### Malformed PDF (js_in_openaction.pdf) +```bash +pdftract extract tests/document_model/fixtures/js_in_openaction.pdf --json - +``` +**Exit Code:** 0 (ANOMALY - should be non-zero on error) +**Error:** "No /Root reference in trailer" +**Note:** This is expected behavior for this intentionally malformed test fixture + +### 6. Validation Commands +```bash +pdftract validate +``` +**Exit Code:** 1 (on validation errors) +**Execution Time:** ~0.004-0.013 seconds +**Output Format:** JSON path + error message +``` +/ "schema_version" is a required property +/ "metadata" is a required property +``` + +### 7. Classify Command +```bash +pdftract classify +``` +**Exit Code:** 1 (when missing required features) +**Error:** Requires `--features profiles` +**Note:** Feature-gated command + +## Exit Code Summary + +| Exit Code | Meaning | Examples | +|-----------|---------|----------| +| 0 | Success | --help, list-diagnostics, doctor, successful extraction | +| 1 | Runtime Errors | Validation failures, missing features | +| 2 | Argument/File Errors | Invalid arguments, file not found, missing command | + +## Performance Metrics + +All commands executed in **excellent timing**: +- Help/diagnostics: ~0.002 seconds +- Doctor command: ~0.002 seconds +- Validation: ~0.004-0.013 seconds +- Extraction: ~0.002 seconds (valid PDFs) + +**All commands < 30 seconds requirement** ✅ + +## Output Formats Observed + +1. **Structured Text:** Help listings, diagnostic codes +2. **JSON Data:** Extraction output with schema_version 1.0 +3. **Error Messages:** Path-based validation errors +4. **Tabular Data:** Doctor command health checks + +## Warnings and Anomalies + +1. **Exit Code Inconsistency:** Extract failures return exit code 0 (should return non-zero) +2. **Missing Version Flag:** Neither `--version` nor `-V` work correctly +3. **Feature Gating:** Some commands require specific build features + +## File Paths Referenced + +- Binary: `/home/coding/pdftract/target/release/pdftract` +- Test fixtures: `/home/coding/pdftract/tests/document_model/fixtures/` +- Valid PDF: `base_hello.pdf` +- Malformed test PDF: `js_in_openaction.pdf` +- Expected outputs: `*.expected.json` files in fixtures directory + +## Environment Details + +- **System:** Linux 6.12.63 +- **Available RAM:** 59915 MiB +- **Binary location:** Also symlinked to `/home/coding/.local/bin/pdftract` +- **Cache status:** Directory does not exist (non-blocking)