@json-to-office/jto-ops 1.2.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Wiseair srl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @json-to-office/jto-ops
+
+Host-side operations layer for [json-to-office](https://github.com/Wiseair-srl/json-to-office): the format adapters that validate and generate documents, the LibreOffice rasterizer behind the docx `visual` component, and the per-platform LibreOffice font stagers.
+
+Extracted from [`@json-to-office/jto-cli`](https://www.npmjs.com/package/@json-to-office/jto-cli) so a host without a terminal — the MCP server, a serverless function, a job runner — can do the work without installing ink, react, commander or chalk. The CLI re-exports everything here, so nothing changes for its consumers.
+
+```ts
+import {
+  createAdapter,
+  createLibreOfficePptxRasterizer,
+  getFontStager,
+} from '@json-to-office/jto-ops';
+
+const adapter = createAdapter('docx');
+const result = await adapter.generate(document, { output: 'out.docx' });
+```
+
+## Diagnostics
+
+This package writes to no stream of its own — a host may own stdout as a protocol channel. Warnings and traces go to a sink you scope around the call:
+
+```ts
+import {
+  runWithDiagnosticSink,
+  stderrDiagnosticSink,
+} from '@json-to-office/jto-ops';
+
+await runWithDiagnosticSink(stderrDiagnosticSink, () =>
+  adapter.generate(document, options)
+);
+```
+
+With no sink installed the messages are dropped. The CLI installs an Ink-backed sink per task; `stderrDiagnosticSink` is the plain-text fallback for hosts with no UI.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,412 @@
+import { FontRuntimeOpts, GenerationWarning, PptxBatchRasterizer, PptxRasterizer, ResolvedFont } from '@json-to-office/shared';
+
+type FormatName = 'docx' | 'pptx';
+interface GeneratorOptions {
+    theme?: string | any;
+    themePath?: string;
+    customThemes?: Record<string, any>;
+    validation?: {
+        strict?: boolean;
+        allowUnknownFields?: boolean;
+    };
+    fonts?: FontRuntimeOpts;
+    deterministic?: boolean;
+    generatedAt?: string | Date;
+    /**
+     * Directory that relative asset paths in the document resolve against —
+     * normally the input document's own directory (#142).
+     */
+    baseDir?: string;
+    /**
+     * Backend that turns the compiled document into bytes.
+     *
+     * Format-specific and validated by the core's renderer registry, which is
+     * why this is a bare string here: naming the id union would make this
+     * package import both cores statically, and they are loaded on demand.
+     * Undefined means the format's default (`docxjs` / `pptxgenjs`).
+     */
+    renderer?: string;
+    /**
+     * Optional sink for structured generation warnings (FONT_UNRESOLVED and
+     * friends). Mirrors core-docx's `JsonGenerationOptions.warnings`, and is the
+     * only delivery mechanism that works off the CLI: `emitGenerationWarnings`
+     * routes through an AsyncLocalStorage sink that is a no-op on the server.
+     *
+     * Adapters PUSH into it; they never replace it. Warnings therefore
+     * ACCUMULATE across repeated `generateBuffer` calls on one
+     * `GeneratorResult` — allocate one array per logical request.
+     */
+    warnings?: GenerationWarning[];
+}
+interface GeneratorResult {
+    generateBuffer: (document: any) => Promise<Buffer>;
+    /**
+     * Post-expansion standard JSON tree without any rendering work — no fonts,
+     * no layout, no visual rasterization. Present when the underlying generator
+     * supports it (plugin-aware DOCX generation does).
+     */
+    getStandardDefinition?: (config: any) => Promise<any>;
+    hasPlugins: boolean;
+    pluginNames: string[];
+    /**
+     * Identity of the theme this generator forces on every document, or
+     * undefined when nothing was requested and each document's own `props.theme`
+     * decides. Reported by the CLI so the summary names what actually rendered.
+     */
+    themeLabel?: string;
+}
+interface FormatAdapter {
+    name: FormatName;
+    extension: string;
+    label: string;
+    defaultPort: number;
+    generateBuffer(json: unknown, options: GeneratorOptions): Promise<Buffer>;
+    createGenerator(plugins: any[], options: GeneratorOptions): Promise<GeneratorResult>;
+    parseJson(input: string | object): unknown;
+    validateDocument(doc: unknown): {
+        valid: boolean;
+        errors?: any[];
+    };
+    generateSchema(options?: any): any;
+    getBuiltinThemes(): Record<string, any>;
+    resolveTheme(options: GeneratorOptions): Promise<any>;
+    loadCustomThemes(options: GeneratorOptions): Promise<Record<string, any> | undefined>;
+    /**
+     * Renderer ids this format registers, defaults first.
+     *
+     * Async because the core that owns the registry is imported on demand — the
+     * list is read from it rather than repeated here, so the two cannot drift.
+     */
+    rendererIds(): Promise<readonly string[]>;
+    /** Cumulative visual pre-pass dedupe counters (DOCX only) (#156). */
+    getVisualPrepassStats?(): Promise<any>;
+    /** Reset per-format cache observability counters (DOCX only). */
+    resetCacheStats?(): Promise<void>;
+}
+declare class DocxFormatAdapter implements FormatAdapter {
+    name: FormatName;
+    extension: string;
+    label: string;
+    defaultPort: number;
+    rendererIds(): Promise<readonly string[]>;
+    generateBuffer(json: unknown, options: GeneratorOptions): Promise<Buffer>;
+    createGenerator(plugins: any[], options: GeneratorOptions): Promise<GeneratorResult>;
+    parseJson(input: string | object): unknown;
+    validateDocument(doc: unknown): {
+        valid: boolean;
+        errors?: any[];
+    };
+    generateSchema(_options?: any): any;
+    getBuiltinThemes(): Record<string, any>;
+    resolveTheme(options: GeneratorOptions): Promise<any>;
+    /**
+     * Resolve `theme`/`themePath` once for a whole run: `themePath` is read a
+     * single time and feeds both the requested theme and the custom-theme
+     * registry, so a bad path warns once instead of once per consumer.
+     */
+    private resolveThemes;
+    loadCustomThemes(options: GeneratorOptions): Promise<Record<string, any> | undefined>;
+    getVisualPrepassStats(): Promise<any>;
+    resetCacheStats(): Promise<void>;
+}
+declare class PptxFormatAdapter implements FormatAdapter {
+    name: FormatName;
+    extension: string;
+    label: string;
+    defaultPort: number;
+    rendererIds(): Promise<readonly string[]>;
+    generateBuffer(json: unknown, options: GeneratorOptions): Promise<Buffer>;
+    createGenerator(plugins: any[], options: GeneratorOptions): Promise<GeneratorResult>;
+    parseJson(input: string | object): unknown;
+    validateDocument(doc: unknown): {
+        valid: boolean;
+        errors?: any[];
+    };
+    generateSchema(_options?: any): any;
+    getBuiltinThemes(): Record<string, any>;
+    resolveTheme(options: GeneratorOptions): Promise<any>;
+    /**
+     * Resolve `theme`/`themePath` once for a whole run: `themePath` is read a
+     * single time and feeds both the requested theme and the custom-theme
+     * registry, so a bad path warns once instead of once per consumer.
+     */
+    private resolveThemes;
+    loadCustomThemes(options: GeneratorOptions): Promise<Record<string, any> | undefined>;
+}
+declare function createAdapter(format: FormatName): FormatAdapter;
+
+/**
+ * PPTX rasterizer — the concrete service backing docx `visual` components.
+ *
+ * Pipeline: presentation JSON → (core-pptx) .pptx → (LibreOffice) PDF →
+ * (poppler/pdftoppm) PNG. Returns a base64 data URI plus the natural pixel
+ * dimensions. Results are content-addressed and cached on disk so repeated
+ * builds of an unchanged visual skip the (multi-second) LibreOffice run.
+ *
+ * Single and batch rasterization share one engine (#153). A batch keeps one
+ * .pptx per slide and converts them all in a single `soffice` launch — the
+ * launch is the dominant cost, and per-file conversion keeps slides fully
+ * independent: each has its own PDF and PNG (no page↔slide index mapping),
+ * its own dpi, and a cache key identical to the single-slide path, so both
+ * paths share the same disk cache.
+ *
+ * A request may carry `fonts`: base64 font faces that are staged for the
+ * soffice launches (via the shared FontStager pipeline) so the slide renders
+ * with the document's real families instead of whatever the host happens to
+ * have installed. Those fonts are part of the disk-cache key — the same
+ * slide is genuinely different pixels with and without them, and the cache
+ * is shared process-wide across callers.
+ *
+ * Every engine run works against a wall-clock deadline (one batch-scaled
+ * soffice window plus one pdftoppm window) so a wedged conversion fails the
+ * remaining slides quickly instead of holding the caller — and its
+ * concurrency slot — for minutes.
+ *
+ * This is injected via `services.pptx.render` / `services.pptx.renderBatch`;
+ * the published engine packages never depend on these binaries.
+ */
+
+/**
+ * Process-wide rasterizer disk-cache counters (#156).
+ */
+interface RasterizerCacheStats {
+    /** Slides served from the content-addressed PNG disk cache. */
+    diskHits: number;
+    /** Unique slides that missed the disk cache and needed the engine. */
+    diskMisses: number;
+    /** diskHits / (diskHits + diskMisses), 0 when no lookups. */
+    hitRate: number;
+    /** Requests resolved by batch-internal dedupe (duplicate slides). */
+    dedupedRequests: number;
+    /** Slides successfully rendered by the engine (LibreOffice + pdftoppm). */
+    rendered: number;
+    /** Slides that failed at any engine stage. */
+    failed: number;
+    /** PNG files currently in the disk cache directories. */
+    entries: number;
+    /** Total bytes of those PNG files. */
+    bytes: number;
+}
+/**
+ * Get rasterizer cache statistics: process-lifetime counters plus a live
+ * scan of the disk cache directories (default dir included, so entries from
+ * previous processes are visible too).
+ */
+declare function getRasterizerCacheStats(): Promise<RasterizerCacheStats>;
+/**
+ * Delete every cached PNG in the known cache directories (default dir
+ * included) and reset the counters. Backs "Clear all caches" (#156) — the
+ * disk cache used to survive it.
+ */
+declare function clearRasterizerCache(): Promise<void>;
+/**
+ * Build a LibreOffice-backed pptx rasterizer.
+ *
+ * @param options.cacheDir - directory for the content-addressed PNG cache
+ *   (default: <tmp>/jto-visual-cache). Pass `null` to disable caching.
+ */
+declare function createLibreOfficePptxRasterizer(options?: {
+    cacheDir?: string | null;
+}): PptxRasterizer;
+/**
+ * Build a LibreOffice-backed BATCH pptx rasterizer (#153): many independent
+ * single-slide presentations, one soffice launch, per-slide results. Shares
+ * the content-addressed disk cache with the single-slide rasterizer — the
+ * per-slide cache key is identical on both paths.
+ */
+declare function createLibreOfficePptxBatchRasterizer(options?: {
+    cacheDir?: string | null;
+}): PptxBatchRasterizer;
+
+/**
+ * Make resolved fonts visible to the LibreOffice child process for the
+ * duration of one PDF conversion, then clean up.
+ *
+ * Linux/macOS:  fontconfig + FONTCONFIG_FILE env var.
+ * Windows:      GDI session registration via koffi (AddFontResourceW).
+ *
+ * The caller calls `stage(fonts, tempDir)` before spawning soffice, merges
+ * `envOverrides` into the child process env, waits for conversion, then
+ * awaits `cleanup()` regardless of success or failure.
+ *
+ * Two consumers today: the playground's LibreOffice PDF-preview converter
+ * (`@json-to-office/jto`) and the pptx rasterizer that backs docx `visual`
+ * components (`../pptx-rasterizer.ts`).
+ */
+
+interface FontStageHandle {
+    /** Merged into the child process env. Empty object if nothing to stage. */
+    envOverrides: Record<string, string>;
+    /** Always call in a finally block. Safe to call multiple times (idempotent). */
+    cleanup(): Promise<void>;
+}
+interface FontStageOptions {
+    /**
+     * UserInstallation profile directories the soffice launch(es) will use.
+     * The macOS stager seeds its OnStartApp Python macro into EACH of them —
+     * a launch with an unseeded profile registers no fonts and silently falls
+     * back to system faces. Absent → `<tempDir>/user-profile`, the
+     * LibreOfficeConverterService convention.
+     */
+    profileDirs?: string[];
+}
+interface FontStager {
+    stage(fonts: ResolvedFont[], tempDir: string, options?: FontStageOptions): Promise<FontStageHandle>;
+}
+
+declare class NoopFontStager implements FontStager {
+    stage(_fonts?: unknown, _tempDir?: string, _options?: FontStageOptions): Promise<FontStageHandle>;
+}
+
+/**
+ * Linux + macOS: use fontconfig to expose staged TTFs to LibreOffice.
+ *
+ * Writes each resolved font to `<tempDir>/fonts/` and a minimal
+ * fontconfig.xml that includes that dir plus the system font config.
+ * LibreOffice honors the per-invocation FONTCONFIG_FILE env var.
+ *
+ * The caller removes the whole tempDir in its own finally block; `cleanup()`
+ * only has to undo the read-only freeze stage() puts on the fonts dir so
+ * that recursive rm can actually unlink.
+ */
+
+declare class FontconfigStager implements FontStager {
+    stage(fonts: ResolvedFont[], tempDir: string, _options?: FontStageOptions): Promise<FontStageHandle>;
+    private pickSystemIncludes;
+}
+
+/**
+ * Windows: register staged TTFs with GDI via AddFontResourceW so the soffice
+ * child process finds them at startup. Forces LibreOffice onto the GDI
+ * backend via SAL_DISABLE_SKIA=1 — Skia/DirectWrite doesn't reliably pick
+ * up GDI-registered fonts on recent LO builds.
+ *
+ * Scope, precisely: `AddFontResourceW` adds to the **session** font table, not
+ * a private per-process one. That is deliberate and unavoidable here — the
+ * private variant (`AddFontResourceExW` with `FR_PRIVATE`) is visible only to
+ * the registering process, and the process that has to see these fonts is the
+ * `soffice` CHILD. Node stays alive for the full conversion so the fonts
+ * persist until cleanup, and GDI releases them on process exit if Node
+ * crashes, so nothing leaks past the process.
+ *
+ * KNOWN LIMITATION — concurrent conversions on one Windows host share that
+ * session table. Two conversions staging different bytes under the same
+ * synthesized family (say two documents that each embed their own "Inter")
+ * register two faces claiming one name, and which one GDI hands to soffice is
+ * then order-dependent. Staged FILES never collide — each carries a
+ * pid-plus-counter suffix — so this is a resolution ambiguity, not corruption.
+ *
+ * Not fixed here because the only correct fix is a host-wide lease held from
+ * stage() through cleanup(), which serializes every Windows conversion; that
+ * is a real throughput cost for a risk the deployed images do not carry (both
+ * production containers are Linux/fontconfig, where staging is per-process via
+ * FONTCONFIG_FILE and cannot collide). It bites a Windows host running
+ * concurrent conversions — worth a lease if that becomes a supported topology.
+ */
+
+declare class WindowsFontStager implements FontStager {
+    stage(fonts: ResolvedFont[], tempDir: string, _options?: FontStageOptions): Promise<FontStageHandle>;
+}
+
+/**
+ * macOS: make staged fonts visible to the soffice child process by
+ * registering them *inside* soffice via a Python macro bound to the
+ * `OnStartApp` event.
+ *
+ * Why this works on macOS 26. Apple tightened `CTFontManagerScopeSession`
+ * and `kCTFontManagerScopePersistent` to require signed+notarized callers
+ * (unsigned Node processes get `paramErr -50`), and `Process` scope only
+ * registers fonts for the calling process — so the Node server can't
+ * register fonts the soffice child sees. But Process scope DOES work from
+ * inside soffice. LibreOffice for macOS bundles Python 3.12 with `ctypes`,
+ * and UNO lets us bind a Python macro to application-start events. We seed
+ * a per-invocation UserInstallation profile with:
+ *
+ *   - `user/Scripts/python/JtoFontRegister.py`  — a ~20-line macro that
+ *     reads `JTO_FONT_PATHS` from the process env and calls
+ *     `CTFontManagerRegisterFontsForURL(url, kScopeProcess, NULL)` via
+ *     ctypes for each path (Process = 1 in Core Text's scope enum).
+ *   - `user/registrymodifications.xcu` — binds the macro to `OnStartApp`
+ *     and sets `MacroSecurityLevel=0` for this ephemeral profile only.
+ *
+ * SECURITY INVARIANT — macro execution scope. The seeded profile disables
+ * soffice's macro-security prompt (`MacroSecurityLevel=0`) so our
+ * OnStartApp macro runs without a dialog. This profile MUST ONLY be used
+ * to open files this server just generated (i.e., well-formed outputs
+ * from `@json-to-office/core-*`). Piping user-supplied .docx/.pptx/.odt
+ * through a soffice invocation that uses this stager would execute any
+ * embedded VBA/Basic macros silently — an RCE primitive. If a future
+ * code path ever converts user-supplied documents (e.g. "PDF-ify my
+ * upload"), it must build a separate converter that does NOT share this
+ * profile, or call soffice with `--safe-mode` / a default profile.
+ *
+ * The pptx rasterizer (`./pptx-rasterizer.ts`) is the second consumer and
+ * upholds the same invariant: it only ever opens .pptx files this process
+ * just built from `@json-to-office/core-pptx` out of the request's own
+ * presentation JSON — never a user-supplied binary document.
+ *
+ * PROFILE DIRS. The macro is only reachable from the UserInstallation
+ * profile it was seeded into, so `options.profileDirs` must list EVERY
+ * profile the caller will launch soffice with. The converter uses exactly
+ * one (`<tempDir>/user-profile`, the default here); the rasterizer uses a
+ * batch profile plus one per isolated retry, and a launch against an
+ * unseeded profile registers nothing and silently falls back.
+ *
+ * Flow: the converter spawns
+ *   `soffice --headless -env:UserInstallation=file://<tempDir>/user-profile ...`
+ * with env `{ JTO_FONT_PATHS: "<ttf1>:<ttf2>:..." }`. LO boots, reads our
+ * seeded profile, fires `OnStartApp`, runs our macro, registers each
+ * staged TTF at Process scope in its own process. Font enumeration then
+ * resolves the synthetic family names (`Inter Bold`, `Source Code Pro
+ * Medium`, …) against those Process-scope registrations. The PDF export
+ * ships the correct glyphs.
+ *
+ * Elegant side-effects:
+ *   - Nothing outside the converter's `tempDir` is touched. The user's
+ *     real `~/Library/Fonts` and `~/Library/Application Support/LibreOffice`
+ *     stay untouched.
+ *   - Cleanup is the converter's `fs.rm(tempDir, …)` — no orphan sweep
+ *     needed. If Node crashes mid-conversion, the per-invocation tempDir
+ *     is reaped by macOS tmpreaper (or the OS's next boot cleanup).
+ *   - No DYLD injection, no notarized helper, no filesystem-scan races.
+ *
+ * Failure mode: if LibreOffice can't run the macro for any reason
+ * (macro-security policy applied at bootstrap before our XCU loads,
+ * Python not present in a minimal LO build, …) the soffice process still
+ * runs and produces a PDF — just with system-fallback fonts, exactly the
+ * pre-fix behavior. Non-catastrophic. Diagnose via stderr: the macro
+ * writes failures to stderr via `print(..., file=sys.stderr)`.
+ */
+
+declare class MacOSCoreTextStager implements FontStager {
+    stage(fonts: ResolvedFont[], tempDir: string, options?: FontStageOptions): Promise<FontStageHandle>;
+}
+
+/**
+ * Factory entry point for the font staging pipeline shared by every
+ * LibreOffice launch in the toolchain: the playground's PDF preview
+ * converter (`@json-to-office/jto`) and the pptx rasterizer that backs docx
+ * `visual` components (`../pptx-rasterizer.ts`).
+ */
+
+declare function getFontStager(platform?: NodeJS.Platform): FontStager;
+
+type DiagnosticTone = 'default' | 'info' | 'success' | 'warning' | 'error' | 'muted';
+type DiagnosticSink = (text: string, tone?: DiagnosticTone) => void;
+/**
+ * Scope a sink to one operation. The CLI installs an Ink-backed one per
+ * task; the MCP server installs one that collects into its response.
+ */
+declare function runWithDiagnosticSink<T>(sink: DiagnosticSink, callback: () => T): T;
+/**
+ * This package writes to no stream of its own — a host may own stdout as a
+ * protocol channel — so with no sink installed the message is dropped.
+ */
+declare function emitDiagnostic(text: string, tone?: DiagnosticTone): void;
+/**
+ * Plain-text sink for hosts with no UI of their own. stderr, not stdout,
+ * so it stays safe to install alongside a stdout protocol stream.
+ */
+declare const stderrDiagnosticSink: DiagnosticSink;
+
+export { type DiagnosticSink, type DiagnosticTone, DocxFormatAdapter, type FontStageHandle, type FontStageOptions, type FontStager, FontconfigStager, type FormatAdapter, type FormatName, type GeneratorOptions, type GeneratorResult, MacOSCoreTextStager, NoopFontStager, PptxFormatAdapter, type RasterizerCacheStats, WindowsFontStager, clearRasterizerCache, createAdapter, createLibreOfficePptxBatchRasterizer, createLibreOfficePptxRasterizer, emitDiagnostic, getFontStager, getRasterizerCacheStats, runWithDiagnosticSink, stderrDiagnosticSink };