Skip to content
Back to search

deckprobe

ffprobe for documents — probe PDF, Microsoft Office, and Apple iWork files without opening them. Rust CLI + browser WASM SDK returning structured JSON with confidence, evidence, and measured I/O cost.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/deckflow--deckprobe/badge.svg)](/listings/deckflow--deckprobe)

HTML

<a href="/listings/deckflow--deckprobe"><img src="/api/listings/deckflow--deckprobe/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Install from source

Requires [Rust 1.88 or newer](https://www.rust-lang.org/tools/install) and Git. This builds the CLI on the user's machine and installs it in the Cargo user directory, so it normally does not require administrator privileges:

cargo install --git https://github.com/deckflow/deckprobe --locked deckprobe

Install a prebuilt release

The installers choose the matching CPU and platform archive and install into the Cargo user directory. Installing there does not require administrator privileges. Use an elevated shell only when deliberately installing into a system directory.

macOS (Apple Silicon or Intel)

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | sh

Linux (x86-64 or ARM64; GNU or musl)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | sh

Windows (x86-64, MSVC)

powershell -ExecutionPolicy ByPass -c "irm https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.ps1 | iex"

If the PowerShell installer updates the user `Path`, restart the shell before running `deckprobe`.

Every release contains platform archives, per-archive SHA-256 files, a consolidated checksum file, and GitHub build-provenance attestations. The shell installer verifies its embedded checksum when `sha256sum` is available. For a manual verification, download the matching archive and checksum from the same GitHub Release and use `shasum -a 256` on macOS, `sha256sum` on Linux, or `Get-FileHash -Algorithm SHA256` on Windows.

The checksum protects against accidental corruption and the provenance attestation records how the artifact was built. They are not the same as an OS code signature: this project does not currently publish macOS Developer ID notarization or Windows Authenticode signatures. macOS Gatekeeper or Windows SmartScreen may therefore ask for an explicit confirmation for a downloaded binary. A source-built binary is also not project-signed, but a locally built executable normally does not carry the quarantine marker attached to browser downloads.

The one-line installer commands are a convenience for trusted environments. For a controlled or offline installation, download the installer and archive from the GitHub Release, inspect them locally, verify the checksum and (where required) the build-provenance attestation, then run the installer.

At runtime DeckProbe does not need root or administrator access. It needs execute permission on the binary and read permission on the document being inspected; output is written to standard output. Hardened environments can still impose additional `noexec`, SELinux/AppArmor, or enterprise execution policies.

See the [installation guide](docs/INSTALLATION.md) for custom install locations, upgrades, and uninstallation.

Verify the installation and probe a file:

deckprobe --version
deckprobe --pretty report.pdf

The default `metadata` probe returns common metadata plus useful format-specific facts. For a focused query, name one or more targets:

deckprobe --pretty \
  -t format,slide_count \
  deck.pptx

Target options are repeatable and unambiguous short names are resolved after format detection:

deckprobe -l m -t title -t slide_count -p deck.pptx
deckprobe -t @summary,@security --view values deck.pptx

Optional zero-additional-path values and per-target confidence are explicit:

deckprobe -t slide_count -o orientation,aspect_ratio \
  -C slide_count=x deck.pptx

Probe one raw document from stdin by supplying the logical filename used for format routing:

cat report.pdf | deckprobe -n report.pdf -

Process multiple paths or named base64 payloads as JSONL. DeckProbe writes one compact schema-v2 result for each non-empty input line:

printf '%s\n' \

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "deckflow",
  3. "owner": {
  4. "name": "DeckFlow",
  5. "url": "https://github.com/deckflow"
  6. },
  7. "description": "DeckProbe document-inspection tooling",
  8. "plugins": [
  9. {
  10. "name": "deckprobe",
  11. "source": "./",
  12. "description": "Inspect PDF, Microsoft Office, and Apple iWork documents with bounded, deterministic probes.",
  13. "homepage": "https://github.com/deckflow/deckprobe",
  14. "repository": "https://github.com/deckflow/deckprobe",
  15. "license": "Apache-2.0",
  16. "keywords": ["pdf", "office", "iwork", "metadata", "document-inspection"]
  17. }
  18. ]
  19. }
README.md · README · 586 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. # DeckProbe
  3. **`ffprobe` for documents, built for agents.**
  4. Ask for the facts you need. Get structured JSON with confidence, evidence, and measured I/O cost.
  5. [![CI](https://github.com/deckflow/deckprobe/actions/workflows/ci.yml/badge.svg)](https://github.com/deckflow/deckprobe/actions/workflows/ci.yml)
  6. [![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-2f80ed.svg)](LICENSE)
  7. [![Rust 1.88+](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org/)
  8. [Install](docs/INSTALLATION.md) · [Quickstart](#quickstart) · [Runtime role](#where-deckprobe-fits) · [Agent skill](#use-from-a-coding-agent) · [MCP server](#mcp-server) · [npm package](#javascript-package) · [Execution modes](#execution-modes) · [Examples](#common-recipes) · [Formats](#supported-formats) · [CLI reference](docs/CLI-REFERENCE.md)
  9. </div>
  10. DeckProbe is the probing engine of the DeckFlow Runtime. It performs low-cost
  11. preflight inspection and returns structured evidence that callers can use before
  12. more expensive parsing, OCR, rendering, uploading, or model ingestion.
  13. Available as a target-driven Rust engine, native CLI, and browser SDK, DeckProbe
  14. inspects untrusted PDF, Microsoft Office, and modern Apple iWork documents
  15. without rendering them or starting a desktop office suite. Instead of eagerly
  16. unpacking everything, it chooses the cheapest probe path that can satisfy the
  17. targets and confidence you requested.
  18. ```console
  19. $ deckprobe --pretty -t slide_count deck.pptx
  20. {
  21. "driver": { "id": "powerpoint", "profile": "pptx" },
  22. "results": {
  23. "<target>": {
  24. "status": "resolved",
  25. "value": 31,
  26. "confidence": "high",
  27. "path": "<selected-path>"
  28. }
  29. },
  30. ...
  31. }
  32. ```
  33. User-facing examples use short target names; reports retain stable canonical
  34. keys for machine consumers.
  35. ## Where DeckProbe fits
  36. DeckFlow is the Document Runtime for Agents. Its product model has three engine
  37. responsibilities:
  38. | Engine | Responsibility |
  39. |---|---|
  40. | Probe / DeckProbe | Inspect and expose bounded preflight signals for routing decisions. |
  41. | Parse / DeckParse | Make document content and structure operable as persistent state. |
  42. | Render / DeckRender | Produce visual representations for humans, AI, and software. |
  43. DeckProbe can run independently. In a larger Runtime workflow, its report helps
  44. the calling agent or application decide whether to parse, render, reject, or use
  45. another path. DeckProbe provides the evidence for that decision; it does not
  46. automatically choose or execute downstream actions.
  47. DeckProbe is not a general-purpose parser, renderer, OCR engine, editor, or
  48. complete security product.
  49. ## Why DeckProbe
  50. | Need | What DeckProbe does |
  51. |---|---|
  52. | Fast, focused inspection | Runs only the paths needed for targets such as page count or slide count. |
  53. | Agent-friendly automation | Emits deterministic schema-v2 JSON for success, partial results, and errors, with stable codes and target-level evidence. |
  54. | Predictable work | Enforces physical-read, decompression, archive-entry, and wall-clock budgets. |
  55. | Broad PDF compatibility | Uses normal parsing first, then bounded safe xref normalization/reconstruction for common damaged-but-readable PDFs. |
  56. | Modern and Legacy Office | Reads OOXML plus `.doc`, `.xls`, and `.ppt` metadata and core statistics through the same target vocabulary. |
  57. | Modern Apple iWork | Validates and inspects `.key`, `.numbers`, and `.pages` ZIP/IWA packages through bounded Snappy and Protobuf paths. |
  58. | Format safety | Routes by filename extension, then verifies the container and required internal main part before reporting values. |
  59. The native CLI needs no Python, JVM, Microsoft Office installation, or external
  60. PDF library at runtime. The browser SDK runs the same engine locally through
  61. WebAssembly and does not upload document bytes.
  62. ## Quickstart
  63. ### Install from source
  64. Requires [Rust 1.88 or newer](https://www.rust-lang.org/tools/install) and Git.
  65. This builds the CLI on the user's machine and installs it in the Cargo user
  66. directory, so it normally does not require administrator privileges:
  67. ```sh
  68. cargo install --git https://github.com/deckflow/deckprobe --locked deckprobe
  69. ```
  70. ### Install a prebuilt release
  71. The installers choose the matching CPU and platform archive and install into
  72. the Cargo user directory. Installing there does not require administrator
  73. privileges. Use an elevated shell only when deliberately installing into a
  74. system directory.
  75. #### macOS (Apple Silicon or Intel)
  76. ```sh
  77. curl --proto '=https' --tlsv1.2 -LsSf \
  78. https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | sh
  79. ```
  80. #### Linux (x86-64 or ARM64; GNU or musl)
  81. ```sh
  82. curl --proto '=https' --tlsv1.2 -LsSf https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 110 on GitHub
  83. ```
  84. #### Windows (x86-64, MSVC)
  85. ```powershell
  86. powershell -ExecutionPolicy ByPass -c "irm https://github.com/deckflow/deckprobe/releases/latest/download/deckprobe-installer.ps1 | iex"
  87. ```
  88. If the PowerShell installer updates the user `Path`, restart the shell before
  89. running `deckprobe`.
  90. Every release contains platform archives, per-archive SHA-256 files, a
  91. consolidated checksum file, and GitHub build-provenance attestations. The shell
  92. installer verifies its embedded checksum when `sha256sum` is available. For a
  93. manual verification, download the matching archive and checksum from the same
  94. GitHub Release and use `shasum -a 256` on macOS, `sha256sum` on Linux, or
  95. `Get-FileHash -Algorithm SHA256` on Windows.
  96. The checksum protects against accidental corruption and the provenance
  97. attestation records how the artifact was built. They are not the same as an OS
  98. code signature: this project does not currently publish macOS Developer ID
  99. notarization or Windows Authenticode signatures. macOS Gatekeeper or Windows
  100. SmartScreen may therefore ask for an explicit confirmation for a downloaded
  101. binary. A source-built binary is also not project-signed, but a locally built
  102. executable normally does not carry the quarantine marker attached to browser
  103. downloads.
  104. The one-line installer commands are a convenience for trusted environments.
  105. For a controlled or offline installation, download the installer and archive
  106. from the GitHub Release, inspect them locally, verify the checksum and (where
  107. required) the build-provenance attestation, then run the installer.
  108. At runtime DeckProbe does not need root or administrator access. It needs
  109. execute permission on the binary and read permission on the document being
  110. inspected; output is written to standard output. Hardened environments can
  111. still impose additional `noexec`, SELinux/AppArmor, or enterprise execution
  112. policies.
  113. See the [installation guide](docs/INSTALLATION.md) for custom install locations, upgrades, and uninstallation.
  114. Verify the installation and probe a file:
  115. ```sh
  116. deckprobe --version
  117. deckprobe --pretty report.pdf
  118. ```
  119. The default `metadata` probe returns common metadata plus useful format-specific facts. For a focused query, name one or more targets:
  120. ```sh
  121. deckprobe --pretty \
  122. -t format,slide_count \
  123. deck.pptx
  124. ```
  125. Target options are repeatable and unambiguous short names are resolved after
  126. format detection:
  127. ```sh
  128. deckprobe -l m -t title -t slide_count -p deck.pptx
  129. deckprobe -t @summary,@security --view values deck.pptx
  130. ```
  131. Optional zero-additional-path values and per-target confidence are explicit:
  132. ```sh
  133. deckprobe -t slide_count -o orientation,aspect_ratio \
  134. -C slide_count=x deck.pptx
  135. ```
  136. Probe one raw document from stdin by supplying the logical filename used for
  137. format routing:
  138. ```sh
  139. cat report.pdf | deckprobe -n report.pdf -
  140. ```
  141. Process multiple paths or named base64 payloads as JSONL. DeckProbe writes one
  142. compact schema-v2 result for each non-empty input line:
  143. ```sh
  144. printf '%s\n' \
  145. '{"id":"report","path":"report.pdf"}' \
  146. '{"id":"deck","path":"deck.pptx"}' | deckprobe --jsonl -t @summary
  147. ```
  148. When a valid JSONL record fails, the error envelope echoes its optional `id`
  149. and original `path` under `input`.
  150. ## Use from a coding agent
  151. DeckProbe ships an [Agent Skill](https://agentskills.io) that teaches an agent the
  152. target vocabulary, the report contract, and the exit-status handling, so it stops
  153. guessing flags and stops falling back to unzipping documents by hand.
  154. If you already have the CLI, install the skill for whichever agents this project
  155. uses:
  156. ```sh
  157. deckprobe install --skills # every agent present in this project
  158. deckprobe install --skills --agent claude -g # ~/.claude/skills/deckprobe/
  159. deckprobe install --skills --dry-run --pretty # preview first
  160. ```
  161. If you do not, install it straight from this repository:
  162. ```sh
  163. npx skills add deckflow/deckprobe
  164. ```
  165. Claude Code users can instead take it as a plugin:
  166. ```
  167. /plugin marketplace add deckflow/deckprobe
  168. /plugin install deckprobe@deckflow
  169. ```
  170. All three deliver the same bytes from [`skills/deckprobe/`](skills/deckprobe/).
  171. Note that `npx skills add` and the plugin install the instructions only — the
  172. skill's first step checks for the CLI and falls back to `npx -y @deckflow/deckprobe`
  173. when it is missing. See
  174. [Installing agent assets](docs/CLI-REFERENCE.md#installing-agent-assets) for the
  175. agent/directory table and the overwrite policy.
  176. ## MCP server
  177. An agent with no shell — Claude Desktop, an IDE chat pane, a hosted agent —
  178. reaches DeckProbe through
  179. [deckprobe-mcp-server](https://github.com/deckflow/deckprobe-mcp-server), which
  180. serves this engine over [MCP](https://modelcontextprotocol.io) as four typed
  181. tools: `probe`, `probe_batch`, `list_formats`, and `list_targets`.
  182. ```sh
  183. claude mcp add deckprobe -- npx -y @deckflow/deckprobe-mcp
  184. ```
  185. ```jsonc
  186. // Claude Desktop, Cursor, VS Code, Zed — any client reading mcpServers
  187. { "deckprobe": { "command": "npx", "args": ["-y", "@deckflow/deckprobe-mcp"] } }
  188. ```
  189. It spawns the same native binary this repository ships, returns schema-v2
  190. reports unmodified, and validates tool arguments before the engine runs. It is
  191. listed in the MCP Registry as `io.github.deckflow/deckprobe`.
  192. The skill and the MCP server teach the same vocabulary. Use the skill when the
  193. agent has a shell and you want the CLI's complete surface; use the MCP server
  194. when it does not.
  195. ## JavaScript package
  196. The independently published `@deckflow/deckprobe` package ships the `deckprobe`
  197. command for Node and runs the same target-driven Rust engine in WebAssembly for
  198. browsers and Node APIs.
  199. ### Install from npm
  200. ```sh
  201. npm install @deckflow/deckprobe
  202. ```
  203. That installs the `deckprobe` command as well. It is the same native binary the
  204. standalone installers ship, delivered through a per-platform optional
  205. dependency, so every flag, help page, report, and exit code is identical:
  206. ```sh
  207. npx @deckflow/deckprobe --help
  208. npx @deckflow/deckprobe -t slide_count deck.pptx
  209. ```
  210. Under Node the package also exposes `probeFile()`, which reads a file and
  211. returns the same report the CLI writes for it. Note that it holds the whole
  212. file in memory, while the CLI reads only the paths a probe needs — prefer the
  213. command, or `--jsonl` for batches, on large inputs.
  214. ```ts
  215. import { probeFile } from "@deckflow/deckprobe";
  216. const report = await probeFile("deck.pptx", { targets: ["@summary"] });
  217. ```
  218. ### Browser SDK
  219. In the browser it accepts `File`, `Blob`, `ArrayBuffer`, and `Uint8Array`
  220. inputs; document bytes do not leave the browser.
  221. | Need | Import | Use it when |
  222. |---|---|---|
  223. | Main-thread probe and discovery | `@deckflow/deckprobe` | A small, interaction-adjacent probe can use the UI thread. |
  224. | Off-main-thread probe | `@deckflow/deckprobe/worker` | A user-provided or deep probe must not block rendering. |
  225. | TypeScript types | `@deckflow/deckprobe` | Type `ProbeResult`, `ProbeCallOptions`, or the discovery responses. |
  226. `probe()` initializes WASM lazily. Call `initDeckProbe()` during application
  227. startup or idle time when the first user interaction should use the warm path.
  228. ```ts
  229. import { initDeckProbe, probe } from "@deckflow/deckprobe";
  230. await initDeckProbe();
  231. const report = await probe(file, {
  232. targets: ["@summary", "@security"],
  233. level: "metadata",
  234. });
  235. ```
  236. | Input | Filename handling |
  237. |---|---|
  238. | `File` | Uses `File.name` automatically. |
  239. | `Blob`, `ArrayBuffer`, `Uint8Array` | Pass `name` with a filename extension so DeckProbe can route the format. |
  240. For example, probe fetched bytes with an explicit logical filename:
  241. ```ts
  242. const bytes = await fetch("/documents/quarterly-deck").then((response) =>
  243. response.arrayBuffer(),
  244. );
  245. const report = await probe(bytes, {
  246. name: "quarterly-deck.pptx",
  247. targets: ["powerpoint.slide_count"],
  248. });
  249. ```
  250. Use the Worker entry point for user-provided files, deep probes, or any flow
  251. where parsing must not block the UI thread. Reuse one worker for a batch and
  252. terminate it when the owning screen or job ends:
  253. ```ts
  254. import { createDeckProbeWorker } from "@deckflow/deckprobe/worker";
  255. const worker = createDeckProbeWorker();
  256. try {
  257. const report = await worker.probe(file, {
  258. targets: ["@summary"],
  259. level: "deep",
  260. });
  261. } finally {
  262. worker.terminate();
  263. }
  264. ```
  265. The Worker entry is a module worker resolved relative to the installed package;
  266. verify that the application's bundler preserves module-worker URLs. Calling
  267. `terminate()` cancels pending probes, so create a new worker for a later batch.
  268. `formats()`, `targets(format)`, `schema()`, and `version()` are available from
  269. the main entry point for discovery and integration tooling. See the
  270. [package guide](packages/deckprobe-js/README.md) for the complete API.
  271. ### Bundler setup
  272. The package resolves its WebAssembly binary relative to its own JavaScript
  273. wrapper, so a bundler that relocates the wrapper without the binary breaks
  274. initialization. **Vite's dev server does this in every version** and reports
  275. either `HTTP status code is not ok` or `expected magic word 00 61 73 6d`,
  276. while `vite build` works — exclude the package from dependency
  277. pre-bundling:
  278. ```ts
  279. // vite.config.ts
  280. export default defineConfig({
  281. optimizeDeps: { exclude: ["@deckflow/deckprobe"] },
  282. });
  283. ```
  284. Main-thread-only applications can instead pass the binary URL to
  285. `initDeckProbe()` via the `@deckflow/deckprobe/wasm` export. See the package
  286. guide's [bundler notes](packages/deckprobe-js/README.md#bundlers) for both
  287. fixes, the per-version error messages, and the CDN, sub-path, and CSP cases.
  288. ## Execution modes
  289. DeckProbe deliberately exposes different execution modes instead of treating
  290. every workload as a new process. Choose the mode that matches the lifetime of
  291. your application:
  292. | Mode | Best for | Lifecycle and trade-off |
  293. |---|---|---|
  294. | Native CLI, single-shot | Shell commands, CI steps, one-off automation | Starts a new process per input; simplest invocation and full end-to-end CLI cost. |
  295. | Native CLI, persistent JSONL | Servers, queues, and high-volume local batches | One `deckprobe --jsonl` process stays alive and processes one JSON record per line; avoids startup cost while keeping every document probe independent. |
  296. | Browser SDK, main thread | Short, interaction-adjacent browser checks | Lowest browser transport overhead, but a deep probe can occupy the UI thread. |
  297. | Browser SDK, module Worker | Upload screens, large files, and deep browser inspection | Keeps the UI responsive; includes byte-copy, message, and response-transfer cost. |
  298. The browser paths run the same planner and bounded engine work as native
  299. execution. In practical terms: use JSONL when a native service processes a
  300. queue; use the main-thread SDK only when the expected probe is small enough to
  301. fit the UI budget; and use the Worker SDK as the default for user files and
  302. deep analysis.
  303. ## Common recipes
  304. Probe only low-cost identity targets:
  305. ```sh
  306. deckprobe -l h -t @header suspicious.docx
  307. ```
  308. Require an exact slide count. The planner selects `presentation.xml` instead of the cheaper saved statistic:
  309. ```sh
  310. deckprobe -c x \
  311. -t slide_count \
  312. deck.pptx
  313. ```
  314. Preview the selected paths without executing non-header probes:
  315. ```sh
  316. deckprobe -P -t @default deck.pptx
  317. ```
  318. Bound work on an untrusted archive and fail if a requested target cannot be resolved:
  319. ```sh
  320. deckprobe -s \
  321. -b 8388608 \
  322. -x 16777216 \
  323. -e 5000 \
  324. -T 1000 \
  325. -t format,has_macros \
  326. upload.docm
  327. ```
  328. Discover capabilities from the CLI itself:
  329. ```sh
  330. deckprobe --pretty formats
  331. deckprobe --pretty targets --format pdf
  332. deckprobe --pretty targets --format docx
  333. deckprobe --pretty targets --format xlsx
  334. deckprobe --pretty targets --format pptx
  335. deckprobe --pretty targets --format key
  336. deckprobe --pretty targets --format numbers
  337. deckprobe --pretty targets --format pages
  338. ```
  339. Target presets are composable:
  340. | Preset | Meaning |
  341. |---|---|
  342. | `@header` | Low-cost identity targets. |
  343. | `@default` | Driver defaults for the selected probe level. |
  344. | `@summary` | Identity, common metadata, and primary structure. |
  345. | `@security` | Encryption, macros, signatures, external relationships, and active content. |
  346. | `@structure` | Format-owned counts, names, dimensions, and structure. |
  347. | `@assets` | Images, media, previews, fonts, and embedded-object summaries. |
  348. | `@quality` | Integrity, repair, extension, and conformance signals. |
  349. | `@format` | Format-owned targets available at the selected level. |
  350. | `@all` | Every target available at the selected level. |
  351. The summary preset excludes statistics that currently require a full-file
  352. path; request those explicitly or through `@structure`.
  353. ## Supported formats
  354. | Driver | Profiles | Current inspection depth |
  355. |---|---|---|
  356. | PDF | `.pdf` | Header and Info metadata, page/object counts, xref type, signatures, links, attachments, JavaScript, forms, annotations, and XMP presence. |
  357. | Word | `.docx`, `.docm`, `.dotx`, `.dotm` | OPC metadata, saved statistics, opt-in medium-confidence deep text estimates, exact paragraph/table structure, security signals, comments, and image assets. |
  358. | Excel | `.xlsx`, `.xlsm`, `.xltx`, `.xltm`, `.xlsb` | OPC metadata, worksheets/names/visibility, shared strings, tables, charts, pivots, security signals, and image assets; XLSB identity only. |
  359. | PowerPoint | `.pptx`, `.pptm`, `.ppsx`, `.ppsm`, `.potx`, `.potm` | OPC metadata, slides/hidden slides, masters/layouts/notes, slide size, security signals, charts, comments, images, and media. |
  360. | Legacy Office | `.doc`, `.dot`, `.xls`, `.xlt`, `.ppt`, `.pps`, `.pot` | Validated CFB main streams, SummaryInformation metadata, macros, embedded-object signals, and core Word/Excel/PowerPoint statistics. |
  361. | Keynote | `.key` | Modern IWA identity/integrity plus slide canvas, orientation, hidden/notes/build/transition slide counts, and referenced table models. |
  362. | Numbers | `.numbers` | Modern IWA identity/integrity, exact ordered sheets, referenced table dimensions, hidden/filtered dimensions, and persisted formula definitions. |
  363. | Pages | `.pages` | Modern IWA identity/integrity, sections, page geometry, change tracking, body-text structural counts, cached pagination, and referenced table models. |
  364. The shared deep IWA path also exposes total archive-object counts, raw numeric
  365. message-type counts, and stable semantic object-class counts. The filename
  366. extension selects the driver path, after which DeckProbe verifies the container
  367. signature and format-specific root objects. Apple iWork support is intentionally
  368. limited to the modern ZIP/IWA generation; legacy XML packages containing
  369. `index.apxl` or `index.xml` return structured `UNSUPPORTED_FORMAT` JSON. A
  370. suffix/content mismatch returns `MALFORMED_INPUT`. Target discovery includes
  371. `applicable` and `supported_levels`, and scenario selectors only include targets
  372. backed by the selected driver's executable paths.
  373. ## How probing works
  374. ```text
  375. requested targets + confidence + budget
  376. │
  377. extension dispatcher
  378. │
  379. container + type validation
  380. │
  381. lowest-cost valid probe plan
  382. ┌───────┼────────┬───────────┬────────────┐
  383. PDF Word Excel PowerPoint Apple iWork
  384. \ | / │
  385. shared OOXML paths ZIP/IWA/Snappy/Proto
  386. │
  387. values + evidence + actual cost
  388. ```
  389. Each driver owns its targets, format options, candidate paths, and parsing logic. Word, Excel, and PowerPoint share bounded ZIP/OPC/XML paths. Keynote, Numbers, and Pages share a bounded ZIP/plist/Snappy/IWA/Protobuf layer while retaining separate profile validation and targets.
  390. ### JSON contract
  391. Schema version 2 uses one JSON envelope on standard output. Top-level `status` is `ok`, `partial`, or `error`; errors include a stable code, message, and exit code. The tracked [JSON Schema](docs/deckprobe-report.schema.json) is suitable for generated clients and Agent tool contracts. Every requested target has an explicit status such as `resolved`, `estimated`, `planned`, `unknown`, `unsupported`, `budget_exceeded`, or `failed`. Resolved evidence includes:
  392. - `value` and its target-defined type;
  393. - `confidence` and numeric `confidence_score`;
  394. - the executed `path` and evidence `source`;
  395. - deterministic physical-byte, expanded-byte, and random-read counters for the whole probe.
  396. `confidence` records how strong the evidence for a value is — `exact` when it was read from the
  397. authoritative structure, `high` when it came from a statistic the authoring application saved,
  398. `medium` when it was inferred from a proxy. The paired `confidence_score` is a **fixed constant per
  399. label** (`0.4`, `0.7`, `0.95`, `1.0`), not a calibrated probability: `0.95` does not mean the value
  400. is right 95% of the time. Likewise `partial` only means some requested target was unresolved — the
  401. other results are still valid, and it is not a verdict on the document's health. See
  402. [Reading confidence and partial results](docs/CLI-REFERENCE.md#reading-confidence-and-partial-results).
  403. Wall-clock `elapsed_ms` is omitted by default so identical inputs and options produce byte-identical JSON. Add `--telemetry` when timing is needed.
  404. Use `--strict` when unresolved targets should make the command exit non-zero.
  405. Use `--view values` when a compact target-to-value map is preferable to the
  406. complete evidence envelope. `deckprobe schema` prints the exact bundled
  407. contract, and `deckprobe completion SHELL` generates completions from the live
  408. command model.
  409. ## CLI reference
  410. Start with the built-in help or the complete [CLI reference](docs/CLI-REFERENCE.md):
  411. ```sh
  412. deckprobe --help
  413. deckprobe targets --help
  414. ```
  415. To generate the man page from the same CLI definition:
  416. ```sh
  417. deckprobe generate man > deckprobe.1
  418. man ./deckprobe.1
  419. ```
  420. ## Current limitations
  421. DeckProbe intentionally does not render files, run OCR, execute macros,
  422. follow external links, or send documents to a remote service.
  423. - PDF metadata currently reads the Info dictionary; XMP merging is not implemented.
  424. - PDF metadata/deep paths use a bounded full in-memory parser after the header path; safe xref recovery does not attempt damaged encrypted PDFs.
  425. - Legacy Office focuses on metadata and core counts rather than complete fidelity for every historical binary record variant.
  426. - `.xlsb` deep workbook parsing is not implemented.
  427. - Legacy XML iWork documents are recognized and rejected; only modern IWA packages are supported.
  428. - Pages exposes persisted page geometry, body-text structure, and cached pagination; rendered text-layout reconstruction is not implemented.
  429. - Network-backed range sources, persistent cache, and plugin loading are not implemented,
  430. and are **not planned** for now. Both remote reads and a persistent cache would add
  431. protocol, authentication, invalidation, privacy, and failure-handling surface, and no
  432. measured workload has yet shown that fetching or rereading remote documents is a
  433. material cost next to the local-file and byte-input paths. A proposal would need a
  434. representative corpus with sizes, repeat-probe frequency, bytes transferred, and
  435. latency before the work is scheduled.
  436. ## Development
  437. ```sh
  438. cargo build -p deckprobe
  439. cargo test --workspace
  440. cargo check -p deckprobe-wasm --target wasm32-unknown-unknown
  441. (cd packages/deckprobe-js && npm ci && npm run build && npx playwright install chromium && npm test)
  442. ```
  443. Every release is validated by the maintainers' quality gate—format and lint
  444. checks, workspace tests, the Browser SDK contract tests, and a
  445. correctness-and-performance comparison against the previous release—before it
  446. is published to this repository.
  447. Contributions are welcome—read [CONTRIBUTING.md](CONTRIBUTING.md). Treat every input document as untrusted and report vulnerabilities privately as described in [SECURITY.md](SECURITY.md).
  448. ## License
  449. DeckProbe is available under the [Apache License 2.0](LICENSE).
  450. See [NOTICE](NOTICE) for copyright attribution. Third-party components retain
  451. their own licenses.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.