gutterpress 0.0.0

package/dist/lib/build-runner.d.ts

@@ -0,0 +1,161 @@
+import { resolveConfig } from "./manifest";
+import { BuildError } from "./build-error";
+import { type Gates } from "./build-preflight";
+import { type PdfRenderer, type PdfRenderInput } from "./pagination";
+export type { PdfRenderer, PdfRenderInput };
+export type BuildFormat = "html" | "pdf" | "pdfx";
+export type PdfxFlavor = "x1a" | "x3";
+export { BuildError };
+export interface BuildRunnerOptions {
+    inputDir: string;
+    format: BuildFormat;
+    outDir?: string;
+    pdfFileOverride?: string | null;
+    title?: string;
+    pdfxFlavor?: PdfxFlavor;
+    iccPath?: string;
+    manifestPath?: string;
+    stripAnnotations?: boolean;
+    skipLint?: boolean;
+    skipPreValidate?: boolean;
+    skipPostValidate?: boolean;
+    /**
+     * Optional PDF renderer override. When provided, the build uses it instead of
+     * launching Chromium via puppeteer, and the Chromium preflight is skipped.
+     * The Electron desktop injects one backed by `webContents.printToPDF`.
+     */
+    pdfRenderer?: PdfRenderer;
+    /**
+     * Keep the pooled headless browser alive after the build returns. A one-shot
+     * CLI build leaves this false so the process can exit; a long-lived
+     * preview/watch server sets it true so the browser stays warm across rebuilds
+     * (every rebuild then skips the ~1–2s Chromium launch). The server owns
+     * `closeBrowser()` on shutdown.
+     */
+    keepBrowserAlive?: boolean;
+    rawArgs: Record<string, unknown>;
+}
+export interface BuildRunnerResult {
+    outDir: string;
+    /**
+     * The published `book.html`, or `null` for a one-file delivery (`--out x.pdf`,
+     * a desktop export) where only the PDF is delivered and everything else is
+     * discarded with the work dir. Returning a work-dir path here would hand the
+     * caller a filename that is already deleted by the time they see it.
+     */
+    htmlPath: string | null;
+    pdfPath: string | null;
+    /** As {@link htmlPath}: `null` when nothing but the artifact was published. */
+    fingerprintPath: string | null;
+}
+export interface SplitOutPath {
+    outDir?: string;
+    pdfFileOverride: string | null;
+}
+/**
+ * Split --out into outDir + optional pdfFileOverride.
+ *  - For pdf/pdfx, accept "*.pdf" forms (file path) and split into dirname + path.
+ *  - For html or any non-.pdf string, treat as a directory.
+ */
+export declare function splitOutPath(outArg: string | undefined, format: BuildFormat): SplitOutPath;
+/**
+ * Everything the build stages + output strategies need, resolved once up front:
+ * the requested format, absolute input/output dirs, the manifest dir (for
+ * plugin + ICC resolution), the merged config, and the lint/validate gates.
+ * Assembled by {@link resolveBuildContext}; consumed by {@link runQualityGates},
+ * {@link renderBook}, and the {@link OutputStrategy} implementations.
+ */
+/**
+ * Where a finished build is delivered. The build itself always writes to a
+ * scratch `workDir`; this says what happens to it afterwards.
+ *
+ * The distinction is structural, not a flag: `rm` appears in exactly one branch
+ * of {@link publishBuild}, the `project` one, whose path is always computed by
+ * `resolveOutputDir` from the manifest. A caller-supplied path is a different
+ * variant that reaches different code, so no `--out` value can be deleted —
+ * there is no code path that would do it.
+ */
+export type PublishTarget = 
+/** gutterpress's own `dist/<slug>/`. Replaced wholesale, so stale files vanish. */
+{
+    kind: "project";
+    dir: string;
+}
+/** `--out <dir>`: the user's directory. Files are added; nothing is removed. */
+ | {
+    kind: "directory";
+    dir: string;
+}
+/** `--out <file.pdf>` / the desktop's Save dialog: ONE file, nothing else. */
+ | {
+    kind: "file";
+    file: string;
+};
+export interface BuildContext {
+    opts: BuildRunnerOptions;
+    format: BuildFormat;
+    inputDir: string;
+    outDir: string;
+    manifestDir: string;
+    config: ReturnType<typeof resolveConfig>;
+    gates: Gates;
+    /**
+     * Where the build actually writes. A build assembles a COMPLETE output tree
+     * here and only then replaces `outDir` with it, so a build is atomic (a crash
+     * leaves the previous output untouched) and stale files cannot survive — the
+     * work dir starts empty, so whatever is not rebuilt simply is not there.
+     *
+     * It is a sibling of `outDir` rather than an OS temp dir so the final publish
+     * is a same-filesystem `rename`.
+     */
+    workDir: string;
+    /** What to do with `workDir` once the build succeeds. */
+    target: PublishTarget;
+}
+/**
+ * Stage 1 — load the manifest, merge CLI overrides into the resolved config,
+ * pick the output dir, and compute the lint/validate gates. Pure planning: no
+ * filesystem writes, no browser, no logging beyond computeGates' own
+ * flags-ignored notice. Everything downstream reads from the returned context.
+ */
+export declare function resolveBuildContext(opts: BuildRunnerOptions): Promise<BuildContext>;
+/**
+ * Stage 3 — load configured plugins, render the markdown chapters to
+ * `outDir/book.html`, and copy user asset directories. Returns the path to the
+ * rendered book.html both output strategies then paginate. This is the shared
+ * pre-format work; the per-format tails live in the strategies.
+ *
+ * ARCH finding #4: markdown-it-paged computes typed, line-numbered
+ * author-mistake warnings (`env.layoutWarnings`) that every real render path
+ * used to discard silently. `renderChaptersToFile`'s `onChapterWarnings`
+ * threads them back out here so a final artifact never omits a marker
+ * mistake without at least telling the author about it in the build log.
+ * Exported (not just for the pipeline) so this stage is unit-testable
+ * without driving the full `runBuild` pagination/PDF machinery.
+ */
+export declare function renderBook(ctx: BuildContext): Promise<string>;
+/**
+ * Resolve the effective ICC profile for a PDF/X build (extracted from the pdfx
+ * branch so it is unit-testable in isolation). Relative paths are tried against
+ * the manifest dir first, then cwd. As a convenience the unspecified default
+ * profile (`CGATS21_CRPC1.icc`, no explicit `--icc`) falls back to the embedded
+ * copy shipped in the binary. Throws BuildError(exitCode 2) if nothing resolves.
+ */
+export declare function resolveIccProfile(icc: string, manifestDir: string, explicitIccPath: string | undefined): Promise<string>;
+/**
+ * Orchestrate a build: resolve the context, mkdir the output, preflight tools
+ * (non-html), pre-warm the browser when this build will paginate in Chromium,
+ * run the quality gates, render the book, then hand off to the per-format output
+ * strategy for pagination + finalize. The heavy lifting lives in the named
+ * stages + strategies above (plus ./build-preflight, ./build-staging, and
+ * ./pagination); this reads as the pipeline it is.
+ *
+ * Everything from the prewarm decision onward runs inside a try/finally that
+ * closes the pooled browser (unless `keepBrowserAlive` is set) — finding #50:
+ * previously the close only happened on the success tail (inside
+ * `finalizeBuild`), so a prewarmed Chromium leaked whenever a quality gate,
+ * the render, or pagination itself threw. `closeBrowser()` is a no-op if
+ * nothing was launched (including the injected-renderer path, which never
+ * uses the pool), so it is safe to call unconditionally here.
+ */
+export declare function runBuild(opts: BuildRunnerOptions): Promise<BuildRunnerResult>;

package/dist/lib/build-staging.d.ts

@@ -0,0 +1,64 @@
+/**
+ * HTML string-rewriting for the shippable artifact: turns the raw
+ * serialized-paginated DOM that pagination produces into the static desktop HTML
+ * (or the runtime-pagination fallback). Pure string/fs transforms — no browser.
+ *
+ * The former `stagePaginationInput` is GONE. It copied `book.html` plus every
+ * asset directory into a temp dir purely so relative URLs would resolve against
+ * some root, which cost a second full copy of every asset per build and made the
+ * staged tree a second place assets could go missing. `book.html` is now
+ * self-contained (CSS and fonts inlined by `lib/asset-inline.ts`), so the
+ * pagination pass serves `outDir` directly with in-memory overlays for the
+ * engine — see `createStaticFileServer`'s `overlays` in `./pagination.ts`.
+ */
+/**
+ * Remove the Paged.js pagination ENGINE from an already-paginated, serialized
+ * document so the browser renders the static pages as-is and never re-paginates.
+ * Strips (a) the polyfill `<script src>` and (b) the inline break-inside handler.
+ * Navigation toolbar scripts are NOT touched — they only scroll between pages
+ * that already exist, which is not DOM-pagination.
+ */
+export declare function stripPaginationRuntime(html: string): string;
+/**
+ * Rewrite the build's ephemeral pagination origin back to document-relative
+ * URLs.
+ *
+ * Paged.js absolutizes every non-`data:` CSS `url()` against the sheet's origin
+ * (`replaceUrls`, paged.polyfill.js), so the serialized document comes back
+ * pointing at `http://127.0.0.1:<port>/…` — a port that dies with the build.
+ * Left alone, a shipped `book.html` references a dead origin for every
+ * content-addressed image.
+ *
+ * The leading slash is stripped along with the origin ON PURPOSE: `book.html`
+ * sits at the artifact root, so `assets/x.png` is correct and `/assets/x.png`
+ * would break any deployment under a subpath (GitHub Pages project sites).
+ */
+export declare function stripPaginationOrigin(html: string): string;
+/**
+ * Inject the navigation-only toolbar scripts (page nav, zoom, view modes) into
+ * the static document head. These read the pre-rendered `.pagedjs_page`
+ * elements; they do not paginate.
+ */
+export declare function injectNavigationScripts(html: string): string;
+/**
+ * Turn a raw serialized paginated document into the shippable static desktop
+ * `book.html`: copy the navigation toolbar scripts, strip the pagination engine
+ * and the build's ephemeral origin, wire the nav scripts, and write the file.
+ * Shared by the HTML format and the PDF unification path.
+ */
+export declare function finalizeStaticBook(rawSerializedHtml: string, htmlFile: string, outDir: string): Promise<void>;
+/**
+ * Fallback for `--format html` when no headless browser is available: ship the
+ * Paged.js polyfill + nav scripts so the BROWSER paginates at load time (the
+ * pre-SSG behavior). Slower at runtime and not pre-paginated, but it works with
+ * no Chromium at build.
+ */
+export declare function shipRuntimePaginatedHtml(htmlFile: string, outDir: string): Promise<void>;
+/**
+ * Create a unique scratch directory under the OS temp dir. Now used ONLY for
+ * PDF/X intermediates (`raw.pdf`, Ghostscript work files) — never for staging
+ * assets. Must not be resolved against `process.cwd()`: `runBuild` is exported
+ * and called by the desktop host, so writing scratch dirs into the caller's
+ * directory is a hidden side effect. Callers remove it in a `finally`.
+ */
+export declare function createStageRoot(): Promise<string>;

package/dist/lib/chromium.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns the path to a system Chrome/Chromium binary, or undefined if none found.
+ *
+ * Resolution order:
+ *   1. CHROMIUM_PATH / PUPPETEER_EXECUTABLE_PATH env vars
+ *   2. Hard-coded standard install paths (Chrome / Edge / Brave / Chromium
+ *      on Linux, macOS, Windows)
+ *   3. PATH probe via `which` / `where.exe` for common binary names
+ *      (catches Scoop, Chocolatey, Homebrew, portable installs, and any
+ *      Chromium variant the user added to PATH manually)
+ *
+ * Prefer requireChromiumExecutable() for build paths that cannot continue
+ * without it — it surfaces a multi-line install-instructions error.
+ */
+export declare function resolveChromiumExecutable(): Promise<string | undefined>;
+/**
+ * Like resolveChromiumExecutable() but throws with actionable install instructions
+ * when no Chrome/Chromium is found on the system.
+ */
+export declare function requireChromiumExecutable(): Promise<string>;

package/dist/lib/cli-args.d.ts

@@ -0,0 +1,45 @@
+import type { BuildFormat, PdfxFlavor } from "./build-runner.ts";
+export { EXIT_CODES } from "./build-error.ts";
+/** A recoverable "bad CLI usage" error carrying the process exit code. */
+export declare class UsageError extends Error {
+    exitCode: number;
+    constructor(message: string, exitCode?: number);
+}
+interface CliArgumentDefinition {
+    type?: "boolean" | "string" | "enum" | "positional";
+    alias?: string | readonly string[];
+}
+type CliArgumentDefinitions = Readonly<Record<string, CliArgumentDefinition>>;
+/**
+ * Reject option names citty would otherwise retain and silently ignore, and
+ * reject value-taking options whose value is absent.
+ *
+ * This scans raw argv rather than the parsed object so a positional name used
+ * as an option (for example, `build --input`) cannot masquerade as a declared
+ * flag. Citty parses in non-strict mode and turns a valueless string option
+ * into `""`; catching that from raw argv is the only way to distinguish an
+ * omitted option from a typo. A dash-prefixed token is still a legitimate
+ * string value unless it names an option declared by this command.
+ */
+export declare function rejectUnknownFlags(rawArgs: readonly string[], declared: CliArgumentDefinitions, commandName: string): void;
+/**
+ * Reject CLI positionals beyond the ones a command declares (UX finding M46).
+ *
+ * Citty's parser keeps every raw positional token in `args._` even after
+ * `type: "positional"` args have claimed their share — it shifts values off a
+ * COPY of `_` for each declared positional arg, but never trims the original
+ * array. So a command with one declared positional silently drops a second
+ * one instead of erroring, e.g. `gutterpress build a b` builds `a` and never
+ * mentions `b`. Call this near the top of a command's `run()`, passing
+ * `(args as { _: unknown[] })._` and how many positionals the command itself
+ * declares, to turn that into a named `UsageError` instead.
+ */
+export declare function rejectExtraPositionals(positionals: unknown[] | undefined, expectedCount: number, commandName: string): void;
+/** Parse `--format`, falling back to the caller-supplied default. */
+export declare function parseFormat(raw: unknown, opts: {
+    default: BuildFormat;
+}): BuildFormat;
+/** Parse `--pdfx-flavor`, which is only valid alongside `--format pdfx`. */
+export declare function parsePdfxFlavor(raw: unknown, format: BuildFormat): PdfxFlavor | undefined;
+/** Parse `--port`, defaulting to {@link NETWORK.DEFAULT_PORT} (0 = OS-assigned). */
+export declare function resolvePort(raw: unknown): number;

package/dist/lib/desktop.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Output filename constants for the build pipeline.
+ *
+ * Historically this file also emitted "desktop chrome" (toolbar + folder
+ * picker + GH clone modal) into the build output so the directory was a
+ * self-hostable site. That chrome was removed 2026-05-18 when the desktop
+ * was extracted into packages/desktop (Electron + SvelteKit). The CLI build
+ * now produces a "naked" book.html with Paged.js polyfill and the
+ * pagedjs-interface/bridge scripts injected — no toolbar.
+ *
+ * Power users who want a hosted UI launch the desktop app or write their
+ * own iframe wrapper around book.html.
+ */
+export declare const BOOK_HTML_FILENAME = "book.html";

package/dist/lib/diagnostics.d.ts

@@ -0,0 +1,64 @@
+/**
+ * System diagnostics — surfaces tool availability + versions for the
+  * desktop's Help/About dialog and the `gutterpress doctor` CLI command.
+ *
+ * Reuses `resolveChromiumExecutable`, `findTool`, and `isToolAvailable` for
+ * tool detection. Install-hint copy lives in `./install-hints.ts` — the
+ * single source of truth also consumed by build-runner.ts's preflight and
+ * chromium.ts's `requireChromiumExecutable` — not duplicated here. Probes
+ * are run in parallel; total wall time is dominated by the slowest
+ * `--version` invocation (~50-200ms per tool that's present, ~5ms per tool
+ * that's missing).
+ */
+export interface ToolStatus {
+    /**
+     * Stable machine id for this tool, independent of the human-readable
+     * `name`/`bin` display strings (e.g. "chromium", "gs", "qpdf"). Consumers
+     * that need to single out a specific tool (the desktop's doctor route
+     * excludes the bundled-Chromium entry from the "external tools" list) MUST
+     * match on this field, not on `bin`/`name` — those are presentation text
+     * and can be reworded without notice (UX L10).
+     */
+    id: string;
+    name: string;
+    /** The canonical CLI/binary name being probed (gs, qpdf, etc). */
+    bin: string;
+    /** True if the binary is resolvable on PATH or via fixed-path scan. */
+    found: boolean;
+    /** Absolute path on disk if found. */
+    path?: string;
+    /** First line of `<bin> --version` output if found and the call succeeded. */
+    version?: string;
+    /**
+     * What features depend on this tool.
+     * "required" — the feature breaks without it
+     * "optional" — the feature degrades / skips gracefully
+     */
+    usedBy: Array<{
+        feature: string;
+        severity: "required" | "optional";
+    }>;
+    /** Multi-line, per-platform install hint. Always present. */
+    installHint: string;
+}
+export interface SystemDiagnostics {
+    /** Gutterpress lib version */
+    libVersion: string;
+    platform: {
+        os: string;
+        arch: string;
+        release: string;
+        node: string;
+    };
+    tools: ToolStatus[];
+    /** Existing CLI config/credential directory; reporting it never relocates data. */
+    configDir: string;
+    /** Path to the docs page with deeper info. */
+    docsUrl: string;
+}
+/**
+ * Probe every external tool the lib could spawn and return a structured
+ * report. Safe to call repeatedly; the slowest path is ~200ms when every
+ * tool is present (one `--version` per tool, in parallel).
+ */
+export declare function getSystemDiagnostics(): Promise<SystemDiagnostics>;

package/dist/lib/embedded-assets.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Embedded preview assets (favicon, manifest schema, paged.js polyfill,
+ * iframe interface + cross-origin bridge).
+ *
+ * `with { type: "file" }` imports are the canonical embedding mechanism for
+ * assets that must be accessible in all three runtime contexts:
+ *
+ *  - bun build --compile (standalone binary):
+ *      Bun embeds the file at a bunfs path and the import returns that absolute
+ *      bunfs path as a string. All modules are merged into one root file in
+ *      bunfs, so new URL("../assets/...", import.meta.url) does NOT work here
+ *      because import.meta.url points to the bundle root, not the source file.
+ *      with { type: "file" } correctly gives the embedded absolute path.
+ *
+ *  - bun run src/cli.ts (development):
+ *      The import returns the real absolute disk path to the asset file.
+ *
+ *  - Node.js via dist/ (Electron in-process):
+ *      bun build --target node copies assets alongside the output JS with
+ *      hashed filenames and rewrites imports to relative strings like
+ *      "./favicon-abc123.ico". We resolve these relative to __libdir so
+ *      readFile always gets an absolute path regardless of CWD.
+ *
+ * On first use we copy everything into a per-process temp directory and return
+ * that path, letting call sites use plain readFile/cp without caring about
+ * the source format.
+ */
+export declare function getAssetsDir(): Promise<string>;
+export declare function getAssetPath(relPath: string): Promise<string>;

package/dist/lib/exec.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Join `dir` onto the front of `existingPath` using `sep` (defaults to the
+ * current platform's `node:path` delimiter — `:` on POSIX, `;` on Windows).
+ * A pure function so the delimiter behavior is unit-testable without
+ * needing to actually run on every OS — see exec.test.ts.
+ */
+export declare function buildEnhancedPath(dir: string, existingPath: string, sep?: string): string;
+/** Gutterpress's own node_modules/.bin so locally installed tools are found. */
+export declare const localBin: string;
+/**
+ * PATH with `localBin` prepended, correctly delimiter-joined. Single source
+ * of truth for every spawn in the lib — `run` and `execCapture` below use
+ * it, and tool-probe.ts's `isToolAvailable`/`findTool` get it for free by
+ * calling `execCapture` instead of keeping their own copy (previously a
+ * literal `:` here corrupted PATH on Windows while tool-probe.ts's copy of
+ * the same logic used `delimiter` correctly — see docs/reviews
+ * 2026-07-10-architecture-critical-review.md, finding #3).
+ */
+export declare const enhancedPath: string;
+/**
+ * Spawn a child process, inherit stdio, reject on non-zero exit.
+ */
+export declare function run(cmd: string, args: string[], opts?: {
+    cwd?: string;
+}): Promise<void>;
+/**
+ * After the child's 'exit', stdio data can still be in flight — buffered in
+ * the pipes, or written by a grandchild that inherited them (the SWA CLI
+ * spawns StaticSitesClient). Settling on 'exit' truncates that output, so we
+ * settle on 'close' (stdio flushed) — but a detached grandchild can hold the
+ * pipes open forever, so 'exit' arms this grace and we settle with whatever
+ * has arrived when it expires. The grace is an IDLE window, re-armed on every
+ * post-exit chunk: a grandchild actively streaming (StaticSitesClient still
+ * printing the deployment URL) is never cut mid-stream, while a silent
+ * daemon holding the pipe still settles one grace-width after exit.
+ */
+export declare const EXIT_FLUSH_GRACE_MS = 2000;
+export interface SpawnCaptureOptions {
+    cwd?: string;
+    /** Full child environment — callers compose it (no ambient default here). */
+    env?: NodeJS.ProcessEnv;
+    /** Kill budget in ms. 0/undefined = no timer. */
+    timeoutMs?: number;
+    /** "total" (default): one-shot deadline. "idle": re-armed on every chunk,
+     * so only complete output silence kills the child. */
+    timeoutMode?: "total" | "idle";
+    /** Raw chunk tap, called per stream as data arrives. */
+    onChunk?: (stream: "stdout" | "stderr", text: string) => void;
+    /** Keep only the trailing N chars of each captured stream (unbounded when
+     * unset) — bounds memory for hours-long progress streams. */
+    captureLimit?: number;
+    /** Override {@link EXIT_FLUSH_GRACE_MS} (tests). */
+    exitGraceMs?: number;
+}
+/**
+ * The lib's single "spawn, buffer stdout/stderr, settle" core. Resolves with
+ * the exit code/signal for ANY exit (callers decide whether non-zero is an
+ * error); rejects only on spawn error or timeout kill. Every timer is cleared
+ * on settle and `unref()`d so a pending call can never keep the process alive
+ * on its own. `execCapture` below and publish's `defaultCommandRunner` are
+ * thin adapters over this — do not grow parallel spawn loops elsewhere
+ * (previously four copies existed with different bug profiles — see
+ * docs/reviews 2026-07-10-architecture-critical-review.md, finding #16).
+ */
+export declare function spawnCapture(cmd: string, args: string[], opts?: SpawnCaptureOptions): Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Spawn and capture stdout/stderr. Rejects on non-zero exit, on spawn
+ * error, or — when `timeoutMs` is given — if the child hasn't exited in
+ * time (it is then SIGKILLed). A thin adapter over {@link spawnCapture};
+ * build-fingerprint.ts, diagnostics.ts, and tool-probe.ts all call this
+ * instead of keeping their own copies.
+ */
+export declare function execCapture(cmd: string, args: string[], opts?: {
+    timeoutMs?: number;
+    cwd?: string;
+}): Promise<{
+    stdout: string;
+    stderr: string;
+}>;

package/dist/lib/fetch-timeout.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared network deadline + author-friendly error mapping for the CLI's
+ * direct `fetch` call sites (GitHub auth/API, the butler download). ONE copy
+ * of the policy, so a fix here reaches every site (the old per-site clones
+ * let the dropped-timeout bug below survive in two of three copies):
+ *
+ *  - The deadline is a TOTAL budget (`AbortSignal.timeout` keeps ticking
+ *    through any body read done inside `run`), COMPOSED with the caller's
+ *    cancellation signal via `AbortSignal.any` — the old
+ *    `signal ?? AbortSignal.timeout(...)` pattern silently DROPPED the
+ *    timeout whenever a caller passed a signal.
+ *  - A caller abort ("AbortError") is rethrown untouched, so cancellation
+ *    keeps its site-specific handling.
+ *  - A fired deadline ("TimeoutError") maps to `timeoutMessage`.
+ *  - Every other failure (DNS, TLS, socket reset) maps to `offlineMessage`,
+ *    with the underlying error attached as `cause`.
+ *
+ * (The isomorphic-git transport has its own idle/total timer design —
+ * remote-auth/git-http.ts — because that client accepts no AbortSignal.)
+ */
+/** An operation error that already has its final classification and message. */
+export declare class FetchPassthroughError extends Error {
+}
+/** An author-friendly HTTP status error that should not be remapped. */
+export declare class FriendlyHttpError extends FetchPassthroughError {
+}
+/** A timeout, DNS, TLS, or socket failure that an optional download may skip. */
+export declare class FetchUnavailableError extends Error {
+}
+export interface FetchTimeoutOptions {
+    /** TOTAL deadline in ms, covering everything `run` does with the signal. */
+    timeoutMs: number;
+    /** Optional caller cancellation, composed with the deadline. */
+    signal?: AbortSignal;
+    /** Message when the deadline fires. Defaults to the offline mapping. */
+    timeoutMessage?: string;
+    /** Message for network-level failures (string, or built from the cause). */
+    offlineMessage: string | ((cause: unknown) => string);
+}
+/** Run one fetch-shaped operation under the policy described in the header. */
+export declare function withFetchTimeout<T>(options: FetchTimeoutOptions, run: (signal: AbortSignal) => Promise<T>): Promise<T>;

package/dist/lib/ghostscript.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Resolve the Ghostscript command on every supported platform.
+ *
+ * Resolution order is explicit override, platform-specific PATH names, then
+ * conventional versioned Windows installer directories. The optional
+ * arguments make the Windows branch testable on non-Windows CI; production
+ * callers always use the current platform and environment.
+ */
+export declare function resolveGhostscript(targetPlatform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/**
+ * Strip all annotations from a PDF using qpdf.
+ *
+ * Chromium embeds internal link annotations (from HTML `id` attributes)
+ * that are not permitted in PDF/X output. Removing them before Ghostscript
+ * prevents the "Annotation not TrapNet or PrinterMark" warning and keeps
+ * the output in strict PDF/X compliance.
+ */
+export declare function stripAnnotations(pdfPath: string, stagingDir: string): Promise<void>;
+type PdfxFlavor = "x1a" | "x3";
+/**
+ * Generate the PostScript definition file for PDF/X output intent + GCR.
+ */
+export declare function makePdfxDefPs(params: {
+    iccPath: string;
+    pdfx: PdfxFlavor;
+    title: string;
+    maxTac?: number;
+}): string;
+/**
+ * Stamp the Creator metadata field on an existing PDF.
+ *
+ * Uses pdf-lib (pure JS, MIT) rather than Ghostscript, so the plain-PDF build
+ * path needs no system tool at all — gs is now required only for PDF/X CMYK
+ * conversion (ADR 0002). `updateMetadata: false` keeps pdf-lib from rewriting
+ * the ModDate/Producer so the only change is the /Creator field.
+ */
+export declare function stampCreator(pdfPath: string): Promise<void>;
+/**
+ * Convert an RGB PDF to CMYK PDF/X using Ghostscript.
+ */
+export declare function convertToPdfxCmyk(inputPdf: string, outPdf: string, config: {
+    iccPath: string;
+    pdfx: PdfxFlavor;
+    title?: string;
+    maxTac?: number;
+    stagingDir: string;
+}): Promise<void>;
+export {};

package/dist/lib/host-policy.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Host-timer POLICY (pure) extracted from the source-provider abstraction.
+ *
+ * These helpers are the testable core of the desktop host's automatic-snapshot
+ * and automatic-sync timers: they turn a persisted, possibly-partial user
+ * settings object into a concrete debounce/cadence delay (ms) — or `null` when
+ * the feature is switched off. The timers themselves live in the Electron main
+ * process (CLAUDE.md §8); this module owns ONLY the clamping/default policy so
+ * both the CLI and the desktop resolve delays identically.
+ *
+ * Nothing here touches Git, the filesystem, or `isomorphic-git` — it is the
+ * host-facing cadence policy, deliberately separate from `source-provider.ts`'s
+ * SourceProvider operations.
+ */
+/** User-facing auto-snapshot policy (mirrors the desktop's settings group). */
+export interface AutoSnapshotPolicy {
+    /** Master switch — automatic snapshots default ON. */
+    autoSnapshot: boolean;
+    /** Minutes of quiet after the last edit before a snapshot fires. */
+    autoSnapshotMinutes: number;
+}
+/** Cadence bounds: never below 5 minutes (commit-per-keystroke guard), never
+ * above a day (a longer value means the user effectively wants it off). */
+export declare const AUTO_SNAPSHOT_MIN_MINUTES = 5;
+export declare const AUTO_SNAPSHOT_MAX_MINUTES: number;
+export declare const AUTO_SNAPSHOT_DEFAULT_MINUTES = 10;
+/** User-facing auto-sync policy (mirrors the desktop's settings group). */
+export interface AutoSyncPolicy {
+    /** Master switch — automatic sync defaults ON when a remote is configured. */
+    autoSync: boolean;
+    /** Periodic safety cadence in minutes (clamped, like the snapshot cadence). */
+    autoSyncMinutes: number;
+}
+/**
+ * Cadence bounds for the periodic safety sync. The floor (1 min) is lower than
+ * the snapshot floor because a network round-trip is cheaper than a full tree
+ * walk, and the transparent-sync plan targets ~2 min as the default cadence.
+ * The ceiling matches the snapshot ceiling (one day = effectively paused).
+ */
+export declare const AUTO_SYNC_MIN_MINUTES = 1;
+export declare const AUTO_SYNC_MAX_MINUTES: number;
+export declare const AUTO_SYNC_DEFAULT_MINUTES = 2;
+/**
+ * Resolve the debounce delay (ms) for the host's auto-snapshot timer, or
+ * `null` when automatic snapshots are disabled. Pure — the testable core of
+ * the trigger policy (the timer itself lives in the Electron main process).
+ *
+ * Defensive about persisted settings: a missing policy means "defaults"
+ * (enabled, 10 min); a non-finite/absurd minutes value falls back to the
+ * default and is then clamped into [5, 1440].
+ */
+export declare function autoSnapshotDelayMs(policy: Partial<AutoSnapshotPolicy> | undefined): number | null;
+/**
+ * Resolve the periodic-safety-sync interval (ms) for the host's auto-sync
+ * orchestrator, or `null` when auto-sync is disabled. Pure — the testable core
+ * of the trigger policy (the timer and the actual `syncProject` call live in
+ * the Electron main process, per CLAUDE.md §8).
+ *
+ * Modelled exactly on `autoSnapshotDelayMs`: a missing or partial policy means
+ * "defaults" (enabled, 2 min); a non-finite/absurd minutes value falls back to
+ * the default and is then clamped into [AUTO_SYNC_MIN_MINUTES,
+ * AUTO_SYNC_MAX_MINUTES].
+ *
+ * Note: the host orchestrator ALSO debounces on file-change triggers; this
+ * cadence governs only the periodic safety timer (§4.2 "Periodic safety").
+ */
+export declare function autoSyncDelayMs(policy: Partial<AutoSyncPolicy> | undefined): number | null;
+/**
+ * True when a changed path is internal Git state (any `.git` segment). The
+ * host's project watcher and auto-snapshot triggers must IGNORE these: the
+ * automatic snapshot itself writes under `.git`, and treating that as a
+ * content change would re-trigger preview reloads / re-arm the timer forever.
+ * Accepts absolute paths, relative paths, or bare basenames.
+ */
+export declare function isGitInternalPath(p: string): boolean;