SPB Git

Repository Public

automation.md 13.8 KB

# Automation

ORIX Docs can be driven without its windows in three ways, all on the same engine (Packages/ORIXDocsKit/Sources/DocAutomation):

Surface Where For
Workflows the Workflows… command in the app, orixdocs workflow run Repeatable sequences of document operations, on one document or a batch
orixdocs the package's executable target Scripts, CI, the terminal
Shortcuts actions App Intents in the app Shortcuts, Spotlight, Siri

Everything runs on this Mac. No step, command or action opens a network connection, runs a script or starts another program.

# Workflows

A workflow is a name and an ordered list of steps. WorkflowRunner executes it on one input (run) or on many files with bounded concurrency (runBatch). Each execution produces a WorkflowRun record: start and end, the outcome, duration and detail of every step, the warnings of the converters (tagged with their step), the files written, the audit summary and, on failure, a structured error naming the step and the file.

  • Progress. A callback receives, per step, the index, the plain-language name and the fraction done; a batch also reports which file.
  • Cancellation is cooperative: the task's cancellation is checked before every step and before every new file of a batch. A step in progress finishes; nothing is left half-written (files are written atomically).
  • Failures in a batch do not stop the other files. Every input gets a record, in input order.
  • Existing files are never overwritten unless asked: the runner's policy is fail (default; used by the tool), rename (“name 2.pdf”; used by the app) or overwrite (--force, “Replace files that already exist”). A workflow can never replace its own input file.
  • History. Runs are appended to ~/Library/Application Support/ORIX Docs/Automation/history.json (newest first, the 200 most recent). ORIX_AUTOMATION_HOME moves that folder (tests, CI).
  • Saved workflows are JSON files in ~/Library/Application Support/ORIX Docs/Automation/Workflows/. The sheet's Add Workflow File… validates a file and copies it there.

# JSON format

json
{
  "name": "Thesis to PDF",
  "summary": "House style for theses.",
  "steps": [
    { "type": "import" },
    { "type": "applyTemplateStyles", "template": "thesis" },
    { "type": "setPageSetup", "paper": "a4", "margins": 72, "marginLeft": 90 },
    { "type": "acceptAllChanges" },
    { "type": "removeComments" },
    { "type": "tableOfContents", "maxLevel": 2 },
    { "type": "setCitationStyle", "style": "apa" },
    { "type": "insertBibliography" },
    { "type": "audit", "profile": "academic", "failOnErrors": true },
    { "type": "export", "format": "pdf", "fileName": "pdf/{name}.pdf", "pdf": { "outline": true, "tagged": true } },
    { "type": "writeAuditReport", "format": "json" }
  ]
}

name and steps are required; id (defaults to a slug of the name) and summary are optional. The file must be smaller than 1 MB.

# Step catalogue

type Keys What it does
import path (optional) Reads the document. Without path, takes the input of the run (a file of the batch, or the open document). Any readable format: orixdoc, docx, rtf, txt, md, html, pdf (text). Import warnings are recorded.
applyTheme theme Re-derives the built-in styles from a theme: ORIX, Classic, Modern, Academic, Editorial, Technical.
applyTemplateStyles template Replaces the style sheet with a template's (blank, business-letter, academic-paper, research-report, thesis, proposal, financial-report, legal-memorandum, meeting-minutes, resume, cover-letter, technical-manual, book-manuscript, project-report, invoice, newsletter). Paragraphs keep their style id, so a Heading 1 takes the template's Heading 1; styles the template does not define are carried over.
setPageSetup paper, orientation, margins, marginTop, marginBottom, marginLeft, marginRight Applies to every section. Paper: a4, letter, legal, a5, b5, tabloid, trade. Orientation: portrait or landscape. Margins in points (0–1000). Absent keys are left alone.
acceptAllChanges / rejectAllChanges — Resolves every tracked change. Skipped when there is none.
removeComments — Removes all comments and their anchors.
tableOfContents title, maxLevel (1–9, default 3) Inserts a table of contents after the title block when the document has headings and no contents; an existing one gets maxLevel (and title when given).
insertBibliography title Appends the bibliography when the document cites sources and has none. Cited keys without a reference are reported as a warning.
setCitationStyle style apa, chicago-author-date, mla, ieee, numeric, vancouver.
recalculateTables — Recalculates every table formula.
setMetadata title, author, subject, keywords, language Sets the given document properties.
audit profile (standard, academic, business, minimal), failOnErrors Runs the document auditor with the facts of a real pagination. With failOnErrors, a finding of severity error stops the workflow.
export format, fileName, pdf Writes the document into the output folder. format: orixdoc, docx, pdf, rtf, markdown, html, txt. fileName may contain {name} (the input name) and subfolders; default {name}.<ext>. pdf: outline, tagged, cropMarks, bleed, firstPage, lastPage. Export warnings are recorded.
writeAuditReport format (md by default, json, or any export format), fileName Writes the findings of the last audit step next to the output (default {name}-audit.<ext>). Skipped when no audit ran.

A step that has nothing to do (no tracked changes, no citations…) is recorded as skipped, not failed.

# Built-in workflows

Id Steps
docx-to-styled-pdf import, apply the ORIX theme, contents, audit, export PDF
markdown-to-pdf import, styles of the Research Report template, A4 with 72 pt margins, contents, bibliography, export PDF
clean-review-copy import, accept all changes, remove comments, recalculate tables, export {name}-clean.docx
audit-only import, audit, write the report as Markdown and as JSON

# Security

  • No script execution. The step types above are the whole vocabulary. A workflow file with any other type (shell, runScript, …) is rejected when it is loaded, before any input is read. The engine contains no process spawning, no AppleScript and no network code; a test (OnDeviceOnlyTests.noNetworkCodeInAutomationOrIntelligence) scans the sources for those APIs.
  • Path confinement. Output names are relative to the output folder. A name that is absolute, starts with ~, or contains .., . or empty components is rejected at load time (pathEscapesOutputFolder). At run time the destination is resolved again, symbolic links included, and refused if it lands outside the folder; {name} is sanitised so an input name cannot carry a path.
  • Reading. import with a path reads that file and nothing else; Markdown and HTML may load images only from the folder of the source file, and never from the network (DocumentConverter).
  • Hostile input. Importers treat files as untrusted (size limits, defensive ZIP reader); a damaged file fails its own run only.
  • Values are validated before anything runs: unknown theme, template, paper, citation style, audit profile or export format, and out-of-range margins or levels.

# Command-line tool

orixdocs is the executable target of the package (swift build --product orixdocs). It needs no window server beyond what Core Text and Core Graphics use.

text
orixdocs convert <input> <output> [--theme <name>] [--paper <size>] [--accept-changes] [--force]
orixdocs audit <input> [--profile standard|academic|business|minimal] [--json] [--fail-on-error]
orixdocs stats <input> [--json]
orixdocs compare <original> <revised> [--report <out.md>] [--merged <out.orixdoc>] [--force]
orixdocs workflow run <workflow.json|builtin-name> <inputs…> --out <dir> [--jobs <n>] [--force] [--quiet]
orixdocs workflow list [--json]
orixdocs formats
orixdocs --version
orixdocs <command> --help

Results (paths written, reports, JSON) go to standard output; errors, warnings and progress go to standard error, prefixed with orixdocs: for errors.

Exit code Meaning
0 Success
1 The operation failed: unreadable or damaged input, conversion or I/O error, invalid workflow file
2 Bad command line: unknown command or option, missing argument, unknown theme, paper, profile or format
3 An output file already exists and --force was not given (nothing was written)
4 A batch finished, but at least one input failed
5 audit --fail-on-error found at least one finding of severity error
130 Interrupted (Ctrl-C): the step in progress finished, the remaining files were not processed

Examples:

sh
orixdocs convert report.docx report.pdf --theme Academic --paper a4
orixdocs convert draft.docx clean.docx --accept-changes
orixdocs audit thesis.orixdoc --profile academic --json > findings.json
orixdocs audit thesis.orixdoc --fail-on-error || echo "errors remain"
orixdocs stats chapter.md --json
orixdocs compare v1.docx v2.docx --report changes.md --merged merged.orixdoc
orixdocs workflow run docx-to-styled-pdf inbox/*.docx --out published --jobs 8
orixdocs workflow run house-style.json chapter-*.md --out build --force

workflow run prints one output path per line and, on standard error, one line per finished file and a final summary (3 succeeded, 1 failed, 0 cancelled in 0.41 s). --jobs defaults to the number of cores, at most 8.

# Shortcuts actions

Four App Intents (App/Sources/Automation/DocumentIntents.swift), listed by ORIXDocsShortcuts:

Action Input Output
Convert Document a file, a format, “Accept Tracked Changes” the converted file
Export as PDF a file a PDF
Audit Document a file, a profile, Text or JSON the findings as text
Document Statistics a file, Text or JSON the statistics as text

They take the file's bytes (IntentFile), call the same engine as the tool off the main actor, and return a value; openAppWhenRun is false and they create no document or window themselves.

Status: the actions compile and their engine paths are the tested ones, but they have not been run from the Shortcuts app (that cannot be scripted from a terminal session). One point must be settled first in the application delegate, which this work does not own: when macOS launches the app in the background to run an action, applicationDidFinishLaunching activates the app and the untitled-document path shows the template chooser. Launches made for an intent must skip both.

# AppleScript: deferred

Not shipped in this version, deliberately.

  • The standard suite needs a scripting definition (.sdef), NSAppleScriptEnabled and OSAScriptingDefinition in the Info.plist, and a model exposed through key-value coding. NSDocument would give open, close, save, print and count documents almost for free, but save … as only reaches the types the document class can write, which is the native format alone (other formats go through export). The one command people script a word processor for — “export this document as PDF” — would need a custom command, and text of document a text suite over a value-type model.
  • A dictionary that advertises the standard suite and then fails on save as PDF or returns nothing for text is the half-working dictionary this project does not ship.
  • The same needs are covered today: batch conversion and auditing by orixdocs, user-facing automation by the Shortcuts actions (which AppleScript and Automator can call through shortcuts run).

If it is added later, the minimal honest scope is: standard suite on document (name, path, modified; open, close, save in the native format, print) plus one custom export command with a format parameter, implemented on DocumentConverter, with tests that drive it through osascript.

# Measured timings

Machine: Mac Studio, Apple M5 Max (18 cores), macOS 27.0; orixdocs built with -c release. Batch: 76 DOCX files (the 19 documents of the import corpus × 4 copies, 656 KB in total; short documents of one to three pages), workflow docx-to-styled-pdf (import, theme, contents, audit with pagination, tagged PDF with outline).

--jobs Wall time Per document
1 0.96 s 12.6 ms
4 0.44 s 5.8 ms
8 0.65 s 8.6 ms

One run each, measured on 2026-11-21 with time, while the machine was busy with other builds and tests (load average 28 on 18 cores): the figures are indicative, and the slower result at 8 jobs than at 4 is within that noise. All 76 files succeeded in every run. The corpus documents are small; process start-up and font loading are a visible share of these times, so they say little about long documents.

In the app, the same workflow on the open Research Report template (5 pages) took 0.4 s, and on the Thesis template (14 pages) 0.4 s, in a debug build.

# Known limits

  • PDF outline. Written by the publisher with CGPDFContextSetOutline (an earlier PDFKit-based pass did not persist on macOS 27.0 and was replaced); Tests/DocLayoutTests/PDFTests.swift (outlineMirrorsTheHeadings) checks it. The automation tests themselves do not assert on the outline.
  • Two inputs with the same base name in one batch write to the same output name: with fail the second one is refused, with overwrite the last one wins.
  • Workflows have no conditions or loops, by design.
  • The history keeps paths and step details, not document content.
Files main
Menu

Theme