imprimatur 0.1.0

data/Cargo.toml

@@ -0,0 +1,44 @@
+[workspace]
+members = ["ext/imprimatur_native/cli", "ext/imprimatur_native/core", "ext/imprimatur_native/ffi"]
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+rust-version = "1.99"
+authors = ["Abdelkader Boudih <oss@seuros.com>"]
+license = "BSD-3-Clause"
+repository = "https://github.com/seuros/imprimatur"
+
+[workspace.dependencies]
+imprimatur = { path = "ext/imprimatur_native/core", version = "0.1.0" }
+magnus = { version = "0.9.2", default-features = false }
+# For rb_thread_call_without_gvl2, which magnus does not wrap; magnus's own
+# rb-sys, features and all.
+rb-sys = { version = "0.9.130", default-features = false, features = ["stable-api"] }
+regex = "1.13.1"
+serde_json = "1.0.154"
+tempfile = "3"
+usage-parser = { package = "usage-lib", version = "7.0.1" }
+usage-rs = "7.0.1"
+
+[workspace.lints.rust]
+unsafe_code = "deny"
+unused_must_use = "warn"
+
+[workspace.lints.clippy]
+all = { level = "warn", priority = -1 }
+pedantic = { level = "warn", priority = -1 }
+nursery = { level = "warn", priority = -1 }
+expect_used = "deny"
+needless_borrow = "deny"
+redundant_clone = "deny"
+redundant_closure = "deny"
+redundant_closure_for_method_calls = "deny"
+trivially_copy_pass_by_ref = "deny"
+uninlined_format_args = "deny"
+unwrap_used = "deny"
+
+[profile.release]
+codegen-units = 1
+lto = true
+strip = true

data/LICENSE.txt

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Abdelkader Boudih
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.md

@@ -0,0 +1,314 @@
+# imprimatur
+
+*Imprimatur*: "let it be printed", the stamp a censor put on a book before it
+could go to press. This one stamps spreadsheets, PDFs and Word documents. No heresy reaches the printer: an invalid sheet name, a NaN or
+a 40,000-character cell is refused at the door, not discovered by Excel's
+"We found a problem with some content".
+
+- **A Ruby DSL over a native core.** The core is also published on its own,
+  as `imprimatur` on crates.io; the gem wraps it.
+- **No third-party format stack.** The XML writer and the zip container are
+  written here, from ECMA-376 and the zip specification; only deflate
+  (`miniz_oxide`) and CRC-32 (`crc32fast`) come from crates.
+- **Deterministic.** The same document always gives the same bytes.
+- **Native only.** CRuby 4.0+. No pure Ruby fallback, no JRuby, no TruffleRuby.
+
+```ruby
+require "imprimatur"
+
+Imprimatur.xlsx("budget.xlsx") do |book|
+  book.sheet("Budget") do |sheet|
+    sheet.row "Line item", "Promised", "Delivered"
+    sheet.row "High-speed rail", 1_000_000_000, 0
+    sheet.row "Bridge to nowhere", 398_000_000, 398_000_000
+    sheet.row "Total", Imprimatur.formula("SUM(B2:B3)"), Imprimatur.formula("SUM(C2:C3)")
+  end
+end
+```
+
+## Installation
+
+```ruby
+gem "imprimatur"
+```
+
+Precompiled gems ship for Linux (x86_64 and aarch64, glibc 2.34+ and musl),
+macOS 13+ (arm64, x86_64) and FreeBSD 15.1 (amd64): nothing to compile.
+Anywhere else, the source gem compiles the extension on install, with the
+toolchain from [rustup.rs](https://rustup.rs) (1.99+).
+
+## Workbooks
+
+```ruby
+bytes = Imprimatur.xlsx do |book|       # no path: returns the .xlsx bytes
+  sheet = book.sheet("Sales")
+  sheet.row "Region", "Q1", "On target"
+  sheet.row "North", 12.5, true
+  sheet << ["South", nil, false]         # nil leaves a cell empty
+  sheet.write(9, 2, "C10")               # zero-based row and column
+  sheet.next_row                         # => 10
+end
+
+send_data bytes, filename: "sales.xlsx", type: :xlsx
+```
+
+| Ruby value | Cell |
+|---|---|
+| `String` | text, up to 32,767 characters |
+| `Integer` | number, up to 2\*\*53 (beyond, Excel would store a different number: `RangeError`) |
+| `Float` | number; NaN and infinity are refused |
+| `BigDecimal`, `Rational` | number, as its `to_f`: Excel keeps every number as a double |
+| `true`, `false` | boolean |
+| `Imprimatur.formula("SUM(A1:A3)")` | formula, computed when the workbook opens |
+| `Date`, `Time`, `DateTime` | date; its wall-clock fields, no time zone (1900-01-01 to 9999-12-31) |
+| `ActiveSupport::TimeWithZone` | as `Time`, the wall clock of its zone |
+| `nil` | nothing |
+
+Dates without a number format of their own show as `yyyy-mm-dd`, or
+`yyyy-mm-dd hh:mm:ss` with a time of day.
+
+Anything else raises `TypeError`. Excel's own limits raise `Imprimatur::Error`:
+sheet names (31 characters, no `[ ] : * ? / \`, unique ignoring case, not
+`History`), 1,048,576 rows, 16,384 columns. A rejected row writes nothing.
+
+## Styles
+
+```ruby
+header = Imprimatur.style(bold: true, color: "#FFFFFF", fill: "#1F4E79", align: :center, border: :thin)
+money  = Imprimatur.style(number_format: "#,##0.00")
+
+Imprimatur.xlsx("report.xlsx") do |book|
+  book.sheet("Report") do |sheet|
+    sheet.column_widths 24, 14                 # characters; nil skips a column
+    sheet.row "Line item", "Amount", style: header
+    sheet.row "Consulting", nil
+    sheet.write(1, 1, 98_000, style: money)
+  end
+end
+```
+
+`Imprimatur.style` takes `number_format:`, `bold:`, `italic:`, `underline:`,
+`color:` and `fill:` (`"#RRGGBB"`), `font:` (`"Arial"`; Calibri by default),
+`size:` (points, in steps of 0.5; 11 by default), `align:` (`:left`,
+`:center`, `:right`), `valign:` (`:top`, `:center`, `:bottom`), `direction:`
+(`:ltr`, `:rtl`), `wrap:` and `border:` (`:thin`, `:medium`, `:thick`). A
+style is checked once, when it is built, and every cell using it shares one
+entry in the workbook.
+
+`style:` also takes an Array, one style (or `nil`) per column from A; the
+columns past its end are left unstyled:
+
+```ruby
+sheet.row "", "", "", "Notes", style: [yellow] * 3
+```
+
+## Validation and comments
+
+```ruby
+yes_no = Imprimatur.validation(list: %w[Yes No])     # built once, shared
+
+book.sheet("Items") do |sheet|
+  sheet.row "Name", "Unit", "Supplier", "Raw material"
+  sheet.comment "A1", "Required. Up to 100 characters.", author: "Instructions"
+  sheet.validate "A2:A1000", formula: "LEN(A2)<=100", alert: :warning, prompt: "Up to 100 characters"
+  sheet.validate "B2:B1000", list: %w[g kg m l ea]
+  sheet.validate "C2:C1000", list: "Suppliers!$A$2:$A$500",
+                             error_title: "Unknown supplier", error: "Pick one from the list."
+  sheet.validate "D2:D1000", yes_no
+end
+```
+
+`list:` is the drop-down's values, or a range holding them (another sheet's
+too). Values typed into the rule stay under Excel's 255 characters, commas
+between them included, and cannot contain a comma; longer lists belong in a
+range. `formula:` accepts a value when it is true, its references relative to
+the range's top-left cell. `alert:` decides what an invalid value meets:
+`:stop` (refused, the default), `:warning`, `:information`, or `:off` (accepted;
+a list still offers its drop-down). `prompt:` and `prompt_title:` show while a
+cell is selected, `error:` and `error_title:` in the alert. Ranges are A1 text;
+one overlapping a range already validated is refused, since Excel applies a
+single rule per cell.
+
+A comment is an Excel note: hidden until the pointer rests on its cell, or
+shown all the time with `visible: true`. The cell need not hold a value.
+
+## Right to left
+
+```ruby
+rtl = Imprimatur.style(direction: :rtl)
+
+book.sheet("مبيعات") do |sheet|                        # Arabic
+  sheet.right_to_left!                                 # column A on the right
+  sheet.row "المنطقة", "الشمال", style: rtl
+end
+
+book.sheet("מכירות") do |sheet|                        # Hebrew
+  sheet.right_to_left!
+  sheet.row "אזור", "צפון", style: rtl
+end
+```
+
+Text in any right-to-left language needs nothing special: Hebrew, Yiddish,
+Arabic, Persian, Urdu, Pashto, Sindhi, Kurdish (Sorani), Uyghur, Syriac,
+Dhivehi (Thaana), N'Ko, Adlam and the rest. `right_to_left!` lays the sheet
+out the way Excel does for them, and `direction: :rtl` fixes a cell's reading
+order instead of letting Excel infer it from its first letter.
+
+Not yet: merged cells, frozen panes, streaming for very large sheets.
+
+## Documents: PDF and DOCX
+
+One document, two formats:
+
+```ruby
+doc = Imprimatur::Document.new(page_size: :a4, page_numbers: true)
+doc.heading "Quarterly report"
+doc.heading "Sales", level: 2
+doc.paragraph do |p|
+  p.text "Revenue was "
+  p.text "up 12%", bold: true, color: "#1F7A1F"
+  p.text " this quarter."
+end
+doc.paragraph "Figures are unaudited.", italic: true, align: :center
+doc.table [["Region", "Q1"], ["North", 12_500.5]], header: true
+doc.page_break
+doc.paragraph "Appendix."
+
+doc.save_pdf("report.pdf")
+doc.save_docx("report.docx")
+
+Imprimatur.pdf("memo.pdf") { it.paragraph "Or in one go." }    # Imprimatur.docx alike
+```
+
+- Headings 1 to 3 (real Word heading styles in DOCX), paragraphs of runs
+  (bold, italic, underline, color), alignment, `\n` line breaks and tabs.
+- Tables: equal columns, borders, a shaded header row that repeats on every
+  page; cells are converted with `to_s`.
+- Page breaks, A4 or Letter, `1 / N` page numbers.
+- `direction: :rtl` makes a right-to-left paragraph (right aligned, and
+  `w:bidi` in DOCX).
+
+**PDF text is Latin only for now.** PDFs use the standard Helvetica fonts,
+which carry Windows-1252: English and Western European text, curly quotes,
+dashes, the euro sign. Anything else (Arabic, Hebrew, Greek, CJK, emoji) raises
+`Imprimatur::Error` naming the character, never a `?`. DOCX carries any
+script. Embedded TrueType fonts, and with them every script and proper RTL in
+PDF, are the next step.
+
+## Reading: documents as Markdown
+
+The other direction: a PDF, XLSX or DOCX printed as Markdown, for search
+indexes and language models.
+
+```ruby
+Imprimatur.markdown("audit.pdf")              # a path
+Imprimatur.markdown(upload.download)          # bytes: the format is in the content
+Imprimatur.markdown(File.open("sales.xlsx"))  # an IO
+
+begin
+  Imprimatur.markdown(scan)
+rescue Imprimatur::NoTextLayer
+  # scanned pages: images, which need OCR
+end
+```
+
+- **PDF**: the text layer, placed glyph by glyph (fonts, encodings and
+  ToUnicode maps, forms, rotated pages), in reading order (right-to-left
+  lines too: Hebrew, Arabic, Persian, Urdu, Syriac, Dhivehi, N'Ko, Adlam,
+  their vowel marks kept on their letters), with headings by font size, hyphenated line breaks rejoined,
+  presentation forms (`fi`, Arabic contextual forms) as plain letters, and
+  running headers and footers left out. Pages after the first start with
+  `<!-- page N -->`. Encrypted PDFs open when the user password is empty, as
+  it is for documents that only restrict printing or copying (RC4, AES-128,
+  AES-256).
+- **XLSX**: each sheet as a table under its name, values as Excel shows them
+  (dates as dates, percentages, 15 significant digits), formulas without a
+  cached result as `=FORMULA`, then the sheet's comments.
+- **DOCX**: headings (from styles and outline levels), bulleted and numbered
+  lists, bold, italic, links, tables, text boxes; deleted text and field
+  codes left out.
+
+Escaping is minimal: only what would break a table (`|`, line breaks). The
+text is meant to be searched and read, and `snake\_case` would be noise.
+
+Documents are untrusted input, so reads are bounded: `max_bytes:` (512 MiB),
+`max_inflated:` (1 GiB of decompressed data, zip bombs included) and
+`timeout:` (60 seconds), plus a nesting limit; past one,
+`Imprimatur::LimitExceeded`. Reading runs without the GVL: other threads and
+fibers keep running, and `Timeout` or `Thread#raise` cancels it.
+`Imprimatur::PasswordRequired` and `Imprimatur::UnsupportedDocument` (legacy
+`.xls` and `.doc`, `.xlsb`, presentations) are the other errors to expect.
+
+### Structure and images
+
+Markdown is one rendering of what a read finds. `Imprimatur.content` gives
+the structure itself, the same as `imprimatur --json md` prints: a PDF's
+pages of headings and paragraphs with their position, a workbook's typed
+cells and comments, a Word document's blocks with their bold, italic and
+linked stretches.
+
+```ruby
+sheet = Imprimatur.content("sales.xlsx")[:sheets].first
+sheet[:rows][1][:cells]
+# => [{cell: "A2", type: "text", value: "North"},
+#     {cell: "B2", type: "number", value: 12.5, text: "12.5"}]
+
+Imprimatur.content("audit.pdf")[:pages].first[:blocks].first
+# => {type: "heading", level: 1, text: "Audit report",
+#     bounds: {left: 72.0, top: 61.4, right: 290.1, bottom: 85.0}}
+```
+
+`Imprimatur.images` hands over every image as a file: a PDF's JPEG and JPEG
+2000 as stored, fax scans as TIFF, raw pixels as PNG (soft masks as alpha),
+with the page and place each is drawn at; a Word or Excel document's media,
+with the sheet that shows each. A scanned PDF gives its pages, ready for
+OCR.
+
+```ruby
+Imprimatur.images("scan.pdf") do |image|
+  File.binwrite("page-#{image.page}.#{image.format}", image.data)
+end
+```
+
+## Command line
+
+The same reader as a static binary, for scripts and agents that would
+otherwise reach for Python to read a PDF:
+
+```sh
+cargo install imprimatur-cli
+imprimatur md audit.pdf sales.xlsx         # Markdown on stdout
+imprimatur --json md sales.xlsx            # the structure: typed cells, blocks, positions
+imprimatur grep -i 'gots' certs/*.pdf      # matches by page, cell or section
+imprimatur images -o figures/ report.pdf   # every image, as a file
+```
+
+See [`ext/imprimatur_native/cli`](ext/imprimatur_native/cli/README.md).
+
+## Core library
+
+The core works without Ruby too; see
+[`ext/imprimatur_native/core`](ext/imprimatur_native/core/README.md).
+
+## Development
+
+```sh
+bundle install
+rake test:all        # cargo test, then the Ruby suite on the compiled extension
+rake lint            # dictator, cargo fmt --check, clippy
+rake gems:native     # the precompiled gem for this machine, in pkg/
+```
+
+Releases come from release-please: merging its release PR tags `vX.Y.Z`,
+bumps the gem and the crates together, and the release workflow attaches the
+source gem and every platform gem to the GitHub release. Publishing is local:
+
+```sh
+rake gems:pull_all   # the release's gems into pkg/, every platform checked
+rake gems:push_all   # to rubygems.org, skipping platforms already published
+```
+
+## License
+
+BSD 3-Clause. The PDF font metrics in `pdf/metrics.rs` are derived from Adobe's Core 14
+AFM files, under the notice reproduced in that file.

data/ext/imprimatur_native/cli/Cargo.toml

@@ -0,0 +1,30 @@
+[package]
+name = "imprimatur-cli"
+version = "0.1.0"
+description = "Read PDF, XLSX and DOCX documents as Markdown, from the command line."
+keywords = ["pdf", "xlsx", "docx", "markdown", "cli"]
+categories = ["command-line-utilities", "text-processing"]
+readme = "README.md"
+edition.workspace = true
+rust-version.workspace = true
+authors.workspace = true
+license.workspace = true
+repository.workspace = true
+
+[[bin]]
+name = "imprimatur"
+path = "src/main.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+imprimatur = { workspace = true, features = ["json"] }
+regex.workspace = true
+serde_json.workspace = true
+usage-rs = { workspace = true, features = ["completions"] }
+
+[dev-dependencies]
+tempfile.workspace = true
+usage-parser.workspace = true
+usage-rs = { workspace = true, features = ["completions", "test"] }

data/ext/imprimatur_native/cli/src/app.rs

@@ -0,0 +1,183 @@
+//! What every command shares: the output mode, reading a document, writing
+//! to standard output, and the exit status each kind of failure maps to.
+
+use std::borrow::Cow;
+use std::collections::HashSet;
+use std::fs;
+use std::io::{self, Read, StdoutLock, Write};
+use std::path::{Path, PathBuf};
+use std::process::ExitCode;
+
+use imprimatur::read::{Content, Limits};
+
+/// The context handed to commands.
+#[derive(Debug, Clone, Copy)]
+pub struct App {
+    /// One JSON object per document instead of text.
+    pub json: bool,
+}
+
+/// How a document failed, as scripts branch on it: exit status and the
+/// name `--json` reports.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Failure {
+    Damaged,
+    NoTextLayer,
+    PasswordRequired,
+    Unsupported,
+    LimitExceeded,
+}
+
+impl Failure {
+    pub const fn of(error: &imprimatur::Error) -> Self {
+        match error {
+            imprimatur::Error::NoTextLayer => Self::NoTextLayer,
+            imprimatur::Error::PasswordRequired => Self::PasswordRequired,
+            imprimatur::Error::UnsupportedDocument(_) => Self::Unsupported,
+            imprimatur::Error::LimitExceeded(_) | imprimatur::Error::Cancelled => {
+                Self::LimitExceeded
+            }
+            _ => Self::Damaged,
+        }
+    }
+
+    /// The exit status, as `imprimatur --help` lists them.
+    pub const fn code(self) -> u8 {
+        match self {
+            Self::Damaged => 1,
+            Self::NoTextLayer => 3,
+            Self::PasswordRequired => 4,
+            Self::Unsupported => 5,
+            Self::LimitExceeded => 6,
+        }
+    }
+
+    pub const fn name(self) -> &'static str {
+        match self {
+            Self::Damaged => "damaged",
+            Self::NoTextLayer => "no_text_layer",
+            Self::PasswordRequired => "password_required",
+            Self::Unsupported => "unsupported",
+            Self::LimitExceeded => "limit_exceeded",
+        }
+    }
+}
+
+/// The exit status of a run: success, or the first failure met.
+#[derive(Debug, Default, Clone, Copy)]
+pub struct Status(Option<Failure>);
+
+impl Status {
+    pub fn record(&mut self, failure: Failure) {
+        self.0.get_or_insert(failure);
+    }
+
+    pub fn exit_code(self) -> ExitCode {
+        self.0.map_or(ExitCode::SUCCESS, |failure| ExitCode::from(failure.code()))
+    }
+}
+
+/// The document's bytes: the file, or standard input for `-`.
+pub fn read(file: &Path) -> imprimatur::Result<Vec<u8>> {
+    if file.as_os_str() == "-" {
+        let mut document = Vec::new();
+        io::stdin().lock().read_to_end(&mut document)?;
+        return Ok(document);
+    }
+    Ok(fs::read(file)?)
+}
+
+/// A document's content: the file read, then the document.
+pub fn content(file: &Path, limits: &Limits) -> imprimatur::Result<Content> {
+    read(file).and_then(|document| imprimatur::read::content(&document, limits))
+}
+
+/// What a document's outputs are named after: its file's stem, `stdin`
+/// for `-`.
+pub fn stem(file: &Path) -> Cow<'_, str> {
+    if file.as_os_str() == "-" {
+        return "stdin".into();
+    }
+    file.file_stem().map_or_else(|| "document".into(), |stem| stem.to_string_lossy())
+}
+
+/// `DIRECTORY/BASE.EXTENSION`, or `BASE-2`, `BASE-3`... when this run
+/// already wrote that path.
+pub fn unique_path(
+    directory: &Path,
+    base: &str,
+    extension: &str,
+    written: &mut HashSet<PathBuf>,
+) -> PathBuf {
+    let mut target = directory.join(format!("{base}.{extension}"));
+    let mut number = 2;
+    while !written.insert(target.clone()) {
+        target = directory.join(format!("{base}-{number}.{extension}"));
+        number += 1;
+    }
+    target
+}
+
+/// Creates the directory outputs go to, or reports why it cannot be and
+/// gives the exit status.
+pub fn create_dir(directory: &Path) -> Result<(), ExitCode> {
+    fs::create_dir_all(directory).map_err(|error| {
+        eprintln!("imprimatur: {}: {error}", directory.display());
+        ExitCode::from(Failure::Damaged.code())
+    })
+}
+
+/// Standard output. A closed pipe (`| head`) is not an error: writes after
+/// it report `false`, and the command stops quietly.
+pub struct Out {
+    stdout: StdoutLock<'static>,
+}
+
+impl Out {
+    pub fn new() -> Self {
+        Self { stdout: io::stdout().lock() }
+    }
+
+    /// Whether the text could be written.
+    pub fn write(&mut self, text: &str) -> bool {
+        self.stdout.write_all(text.as_bytes()).is_ok()
+    }
+
+    /// One JSON value on a line.
+    pub fn json(&mut self, value: &serde_json::Value) -> bool {
+        let mut line = value.to_string();
+        line.push('\n');
+        self.write(&line)
+    }
+}
+
+impl Drop for Out {
+    fn drop(&mut self) {
+        let _ = self.stdout.flush(); // Nothing left to tell a closed pipe.
+    }
+}
+
+impl App {
+    /// Reports a document that failed: on standard error, or as a JSON line
+    /// with `--json`. Returns the failure, and whether output still works.
+    pub fn report_failure(
+        self,
+        out: &mut Out,
+        file: &Path,
+        error: &imprimatur::Error,
+    ) -> (Failure, bool) {
+        let failure = Failure::of(error);
+        let open = if self.json {
+            out.json(&serde_json::json!({
+                "file": file.to_string_lossy(),
+                "ok": false,
+                "error": failure.name(),
+                "message": error.to_string(),
+            }))
+        } else {
+            eprintln!("imprimatur: {}: {error}", file.display());
+            true
+        };
+        (failure, open)
+    }
+}

data/ext/imprimatur_native/cli/src/cli/completion.rs

@@ -0,0 +1,26 @@
+use std::process::ExitCode;
+
+use usage_rs::complete::Shell;
+use usage_rs::{Args, Run};
+
+/// Print a shell completion script
+#[derive(Args, Debug)]
+pub struct Completion {
+    /// Shell to generate for
+    #[usage(arg, choices("bash", "zsh", "fish", "elvish", "nu", "powershell"))]
+    pub shell: String,
+}
+
+impl Run for Completion {
+    type Output = ExitCode;
+
+    fn run(self) -> ExitCode {
+        // The choices above are the names Shell::from_name knows.
+        let Some(shell) = Shell::from_name(&self.shell) else {
+            eprintln!("imprimatur: unsupported shell: {}", self.shell);
+            return ExitCode::from(2);
+        };
+        print!("{}", super::Imprimatur::completion_script(shell));
+        ExitCode::SUCCESS
+    }
+}