gutterpress 0.0.0

package/dist/lib/presets.d.ts

@@ -0,0 +1,45 @@
+import type { ResolvedConfig } from "../schema/manifest.types";
+export type VendorPreset = Omit<ResolvedConfig, "title" | "authors">;
+export declare const DTRPG_PRESET: VendorPreset;
+/**
+ * A neutral, vendor-agnostic default for authors who aren't targeting a
+ * specific print vendor (UX finding M48). Standard 6x9in trade-book trim size,
+ * no vendor total-area-coverage (TAC) cap, and no PDF/X forcing:
+ *
+ * - `page`: 6in x 9in (432 x 648pt) — the common generic trade paperback trim.
+ *   Authors targeting a different size still set `page.width`/`page.height`
+ *   directly; this is a starting point, not a lock-in.
+ * - `ink.maxTac: 400` — 400% is the physical ceiling for 4-color process ink
+ *   (100% each of C+M+Y+K), so `pdf.print.ink-coverage` effectively never
+ *   fires unless the author opts into a real vendor limit.
+ * - `validate.checks`: keeps the generic, vendor-agnostic PDF health checks
+ *   (`pdf.structure.qpdf` parses/traverses, `pdf.print.embedded-fonts` are
+ *   embedded) but does NOT force `pdf.print.pdfx-markers` /
+ *   `pdf.print.pdfx-metadata` — those assert PDF/X OutputIntent/DOCINFO
+ *   structure, which only applies to a PDF/X build (`--format pdfx`).
+ * - `validate.pdf.forbidTransparency: false` and `assets.allowAlpha: true` —
+ *   PDF/X forbids both; a plain PDF/HTML book has no such restriction.
+ * - `validate.assets.allowedColorSpaces` includes RGB (not just CMYK/Grayscale)
+ *   since a generic book isn't assumed to be prepping for CMYK print-only
+ *   distribution.
+ */
+export declare const BOOK_PRESET: VendorPreset;
+export declare const PRESETS: Record<string, VendorPreset>;
+export declare function warnOnce(id: string, message: string, sink?: (msg: string) => void): void;
+/** Test-only reset hook — clears all warn-once dedup state. */
+export declare function resetWarnOnce(): void;
+/**
+ * Resolve a manifest/CLI `preset` value to the {@link VendorPreset} it names
+ * (UX finding M48).
+ *
+ * - Unset (`undefined`): defaults to `dtrpg` for backward compatibility —
+ *   flipping the silent default to the new neutral `book` preset would change
+ *   output geometry (trim size, TAC cap, PDF/X forcing) for every existing
+ *   preset-less project. Emits a one-line warning instead so authors notice
+ *   and choose explicitly; a future major version may change the default.
+ * - Unknown (typo'd) value: throws a {@link UsageError} naming the known
+ *   presets, instead of silently falling back to `dtrpg` — the previous
+ *   behavior turned a typo'd `preset: a4` into 621x810pt DriveThruRPG
+ *   geometry with TAC 240 and PDF/X x1a with zero feedback.
+ */
+export declare function resolvePreset(presetName: string | undefined): VendorPreset;

package/dist/lib/printsafe.d.ts

@@ -0,0 +1,17 @@
+export declare const ruleRemoteUrls = "printsafe/no-remote-urls";
+export declare const ruleRiskyProps = "printsafe/no-risky-print-effects";
+export declare const rulePagedjsCrashSelectors = "printsafe/no-pagedjs-crash-selectors";
+export declare const ruleSyntax = "printsafe/syntax-error";
+export interface PrintSafeWarning {
+    rule: string;
+    severity: "error" | "warning";
+    message: string;
+    line: number;
+    column: number;
+}
+/**
+ * Run print-safety checks against a CSS string. Returns one warning per finding
+ * (errors for remote URLs / crash-prone selectors / syntax errors; warnings for
+ * risky print effects).
+ */
+export declare function checkCss(css: string, from?: string): PrintSafeWarning[];

package/dist/lib/project-scaffold.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Which embedded starter template to scaffold from. Each id maps to a directory
+ * under `assets/templates/<id>/` (a `manifest.yaml` + a `chapter-01.md`), baked
+ * into the binary via `embedded-assets.ts`. `"book"` is the default; the others
+ * give non-technical authors a head start for common formats (#29).
+ */
+export type ProjectTemplateId = "book" | "ttrpg" | "zine" | "technical";
+/**
+ * How (or whether) to put the new project under local version history.
+ *
+ * - `"local-git"` — default. Initialise a local Git repo with one initial
+ *   "snapshot" commit, using a **Node-native, pure-JS** implementation
+ *   (`isomorphic-git`) per CLAUDE.md §7. No remote, no credentials. Maps to a
+ *   `local-git-folder` ProjectSource.
+ * - `"none"` — the escape hatch. Leave the project a plain `local-folder` (no
+ *   `.git`). Selected automatically if version-history init fails, or
+ *   explicitly by an author who does not want it.
+ */
+export type ProjectVersionHistoryMode = "local-git" | "none";
+/**
+ * Inputs the wizard / CLI collect from the author. Writer-friendly: the only
+ * required field is a human project name; everything else is derived or
+ * defaulted.
+ */
+export interface CreateProjectOptions {
+    /** Human-friendly project name (e.g. "My First Book"). Required. */
+    name: string;
+    /** Author display name. Becomes manifest `authors: [author]`. Optional. */
+    author?: string;
+    /** Absolute path to the PARENT directory chosen in the folder picker. */
+    parentDir: string;
+    /** Folder name under `parentDir`. Defaults to a slug of `name`. */
+    folderName?: string;
+    /** Which embedded template to scaffold from. Defaults to `"book"`. */
+    template?: ProjectTemplateId;
+    /**
+     * Absolute path to a CUSTOM template directory to scaffold from (#29). When
+     * set, the whole directory is copied (minus its metadata sidecar) instead of a
+     * built-in template, and `template` is ignored. Used by the wizard when the
+     * author picks a saved/imported template.
+     */
+    templateDir?: string;
+    /** Version-history mode for the new project. Defaults to `"local-git"`. */
+    versionHistory?: ProjectVersionHistoryMode;
+}
+/** The result of a successful scaffold. */
+export interface CreateProjectResult {
+    /** Absolute path of the created project directory. */
+    projectDir: string;
+    /** Absolute path of the generated manifest. */
+    manifestPath: string;
+    /**
+     * Absolute path of the sample chapter the desktop should open first, so the
+     * author immediately sees a rendered document (issue acceptance criterion).
+     */
+    openFile: string;
+    /**
+     * What actually happened with version history. May differ from the requested
+     * mode: if `"local-git"` was requested but init failed (escape hatch fired),
+     * this is `"none"` and `versionHistoryError` explains why.
+     */
+    versionHistory: ProjectVersionHistoryMode;
+    /** Present only when `"local-git"` was requested but downgraded to `"none"`. */
+    versionHistoryError?: string;
+}
+/**
+ * Discriminated failure reasons so the wizard can show a writer-friendly
+ * message and the CLI can choose an exit code. Scaffolding is fail-fast and
+ * NEVER deletes or overwrites anything that already exists.
+ */
+export type CreateProjectErrorCode = "parent-not-writable" | "target-exists" | "invalid-name" | "scaffold-io";
+export interface CreateProjectError extends Error {
+    code: CreateProjectErrorCode;
+}
+/**
+ * Slugify a human name into a safe folder / filename stem: lowercased,
+ * non-alphanumerics collapsed to single hyphens, trimmed. Returns `""` for
+ * input that contains no usable characters (caller treats that as invalid).
+ */
+export declare function slugifyProjectName(name: string): string;
+/**
+ * Escape a string for use as a double-quoted YAML scalar. We emit values inside
+ * `"..."`, so only `\` and `"` need escaping. Keeps the generated manifest
+ * human-readable while staying valid for any author name/title.
+ */
+export declare function escapeYamlScalar(value: string): string;
+/**
+ * Scaffold a new gutterpress project. Resolves with a {@link CreateProjectResult};
+ * throws a {@link CreateProjectError} on any precondition failure.
+ */
+export declare function scaffoldProject(options: CreateProjectOptions): Promise<CreateProjectResult>;
+/** Options for adopting an EXISTING folder as a gutterpress project (in place). */
+export interface AdoptFolderOptions {
+    /** Absolute path of the existing folder to set up as a book. */
+    dir: string;
+    /** Book title. Defaults to a prettified version of the folder name. */
+    title?: string;
+    /** Author display name. Optional. */
+    author?: string;
+    /** Template whose starter theme/chapter is used. Defaults to `"book"`. */
+    template?: ProjectTemplateId;
+    /** Version-history mode. Defaults to `"local-git"`. */
+    versionHistory?: ProjectVersionHistoryMode;
+}
+/**
+ * Adopt an EXISTING folder as a gutterpress project, in place (no new subfolder).
+ * Writes a `manifest.yaml` (using the folder's existing top-level `.md` files as
+ * `source.files`, or scaffolding a `chapter-01.md` when there are none), copies
+ * a starter `styles/book.css`, ensures `dist/` is gitignored (see
+ * `ensureGitignoreHasDist`), and optionally initialises local version history.
+ *
+ * NON-DESTRUCTIVE (global never-overwrite rule): refuses if the folder is
+ * already a project, and never overwrites an existing `manifest.yaml`,
+ * `styles/book.css`, `.gitignore`, or any markdown file.
+ */
+export declare function adoptFolder(options: AdoptFolderOptions): Promise<CreateProjectResult>;

package/dist/lib/project-source.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The classified source of an opened project.
+ *
+ * `managed-github` is defined for #15/#16 (OAuth-backed GitHub projects) but is
+ * never produced by {@link detectProjectSource} in this release.
+ */
+export type ProjectSource = {
+    type: "local-folder";
+    path: string;
+} | {
+    type: "local-git-folder";
+    path: string;
+    /**
+     * Root of the Git repository that holds this project's history. For a
+     * project that IS the repository root this equals `path`. For a book
+     * folder that lives INSIDE a larger repository (a multi-book monorepo)
+     * this is the enclosing repository root — the project USES that repo's
+     * history, scoped to its own subfolder, rather than being told to move.
+     */
+    repoRoot: string;
+    /**
+     * Project directory relative to `repoRoot`, in canonical forward-slash
+     * form (`"books/field-guide"`). Empty string when the project is the
+     * repository root itself. Records WHERE the opened folder sits inside
+     * the repo — it does not scope anything: history/snapshot/restore/sync
+     * operate on the whole repo at `repoRoot` ("a project is its git repo"),
+     * never on just this subfolder.
+     */
+    subPath: string;
+    hasRemote: boolean;
+    remoteUrl?: string;
+    branch?: string;
+} | {
+    type: "managed-github";
+    owner: string;
+    repo: string;
+    branch: string;
+    rootPath?: string;
+};
+/**
+ * What the UI may offer for a given source. Derived purely from the source
+ * type; no I/O.
+ *
+ * NOTE (audit D5): today the desktop only reads `canSnapshot` (it gates the
+ * StatusBar "Version history" affordance). The other flags —
+ * `canEnableVersionHistory`, `canViewHistory`, `canRestoreSnapshot`, `canRead`,
+ * `canWriteLocal`, `authManagedByApp` — are computed and part of the DTO but
+ * not yet wired to UI gating; they are staging for the version-history feature
+ * (#13). Don't assume a button is driven by one of these until you find its
+ * reader.
+ *
+ * Deliberately NO `canSync` here: syncability is a credential-aware question
+ * only `diagnoseProjectRemote().canSync` (remote-auth/diagnose.ts) can answer.
+ * This interface used to carry a second, weaker `canSync` (= hasRemote, any
+ * protocol, no credential check), and the two same-named-but-different gates
+ * were a recurring source of contradictory sync behavior. Remote PRESENCE, for
+ * display purposes, lives on the classification itself (`source.hasRemote`).
+ */
+export interface ProjectCapabilities {
+    canRead: boolean;
+    canWriteLocal: boolean;
+    canEnableVersionHistory: boolean;
+    canSnapshot: boolean;
+    canViewHistory: boolean;
+    canRestoreSnapshot: boolean;
+    authManagedByApp: boolean;
+}
+/**
+ * The remote a project syncs against: `origin` when one exists, else the first
+ * remote. Pure pick over a `listRemotes` result — see {@link syncRemoteFor}
+ * for the I/O helper detection and the sync transport share.
+ */
+export declare function pickSyncRemote<T extends {
+    remote: string;
+    url?: string;
+}>(remotes: T[]): T | undefined;
+/**
+ * THE one answer to "which remote does this repo sync against, and what's its
+ * URL" — shared by detection (`detectProjectSource`) and the sync transport
+ * (`resolveTransport`), so the two layers can never disagree about whether a
+ * remote exists (each divergence shipped as a repo the engine could sync that
+ * the UI called local-only, or vice versa).
+ *
+ * `listRemotes` scans `[remote "…"]` sections case-SENSITIVELY, but git itself
+ * (and isomorphic-git's own fetch/push, via config `get`) treats section names
+ * case-INSENSITIVELY — so a hand-edited `[Remote "origin"]` IS syncable by the
+ * engine while being invisible to `listRemotes`. The `getConfig` fallback
+ * covers exactly that: it uses the same case-insensitive, last-value-wins
+ * lookup the engine's transport uses. Never throws.
+ */
+export declare function syncRemoteFor(dir: string): Promise<{
+    remote: string;
+    url: string;
+} | undefined>;
+/**
+ * Walk PARENT directories of `folderPath` looking for a `.git` directory
+ * (the folder's own `.git` is the `local-git-folder` case, not this).
+ * Returns the nearest enclosing repo root, or `undefined` when none exists.
+ *
+ * Stops at the user's home directory — a repo AT or ABOVE `~` is OS/system
+ * tooling (e.g. a dotfiles repo), not the author's project, and must never
+ * become the `repoRoot` for a bare folder the author opens under home (that
+ * would scope snapshot/restore/sync to the entire home directory). The home
+ * check runs BEFORE the `.git` probe on each ancestor so home itself is never
+ * treated as an enclosing repo, even if it happens to have a `.git` dir.
+ * Pure `node:fs` stats — no git involvement — so the walk costs one `stat`
+ * per ancestor.
+ */
+export declare function findEnclosingRepoDir(folderPath: string): Promise<string | undefined>;
+/** Project dir relative to the repo root, canonical forward-slash form. */
+export declare function repoSubPath(repoRoot: string, folderPath: string): string;
+/**
+ * Classify a folder by inspecting it for a `.git` directory and, if present,
+ * reading `.git/config` (for a remote) and `.git/HEAD` (for the branch).
+ *
+ * A folder WITHOUT its own `.git` that sits inside an enclosing repository
+ * (a book subfolder of a multi-book monorepo) classifies as
+ * `local-git-folder` too: it USES the enclosing repo's history, scoped to
+ * `subPath`. Only a folder with no repo anywhere above it is `local-folder`.
+ *
+ * Pure Node-fs logic; never throws — any read error degrades gracefully (a
+ * `.git` dir that can't be parsed still classifies as `local-git-folder` with
+ * `hasRemote: false`). Never returns `managed-github`.
+ */
+export declare function detectProjectSource(folderPath: string): Promise<ProjectSource>;
+/**
+ * Map a {@link ProjectSource} to the actions the UI may offer. Pure; no I/O.
+ *
+ * - `local-folder`: read/write only; version history can be ENABLED (a later
+ *   `git init`, #13/#25) but no snapshot/history/restore until then.
+ * - `local-git-folder`: version history already on, so snapshot/history/restore
+ *   are available — including book subfolders of a larger repo (`subPath`
+ *   non-empty), which share the enclosing repo's whole-repo history (`subPath`
+ *   is where the folder sits, not a scope).
+ * - `managed-github`: full app-managed read/write/version history.
+ *
+ * Syncability is deliberately NOT answered here — see the interface doc
+ * comment: `diagnoseProjectRemote().canSync` is the one sync gate.
+ */
+export declare function capabilitiesFor(source: ProjectSource): ProjectCapabilities;

package/dist/lib/project-templates.d.ts

@@ -0,0 +1,49 @@
+/** The built-in templates shipped as embedded assets. */
+export declare const BUILT_IN_TEMPLATE_IDS: readonly ["book", "ttrpg", "zine", "technical"];
+/** Author-friendly metadata for one template (built-in or custom). */
+export interface TemplateInfo {
+    /** Stable id. For built-ins, the {@link ProjectTemplateId}; for custom, a slug. */
+    id: string;
+    /** Display name shown in the wizard. */
+    label: string;
+    /** One-line description shown under the label. */
+    description: string;
+    /** `"builtin"` (embedded) or `"custom"` (user-saved / imported). */
+    kind: "builtin" | "custom";
+    /** For custom templates: absolute directory the files live in. */
+    dir?: string;
+}
+/** List the built-in templates (metadata only — no fs access). */
+export declare function listBuiltInTemplates(): Promise<TemplateInfo[]>;
+export interface SaveProjectAsTemplateOptions {
+    /** Absolute path of the project to capture. */
+    projectDir: string;
+    /** Author-supplied template name. */
+    name: string;
+    /** Absolute directory custom templates are stored under. */
+    templatesRoot: string;
+}
+/**
+ * Capture an existing project as a reusable custom template. Copies the whole
+ * project tree (minus build/VCS dirs) into `<templatesRoot>/<slug(name)>/`, then
+ * re-tokenises the project's title back to `{{TITLE}}` in the manifest so the
+ * saved template scaffolds cleanly for the next book. Refuses to overwrite an
+ * existing template directory (never deletes user data).
+ */
+export declare function saveProjectAsTemplate(options: SaveProjectAsTemplateOptions): Promise<TemplateInfo>;
+/**
+ * List custom templates saved under `templatesRoot`. Returns `[]` when the root
+ * doesn't exist. Each subdirectory is a template; its label comes from the
+ * metadata sidecar (falling back to a prettified id).
+ */
+export declare function listCustomTemplates(templatesRoot: string): Promise<TemplateInfo[]>;
+/**
+ * Import a template from an arbitrary folder by copying it under `templatesRoot`.
+ * Thin wrapper around the same copy logic as save-as-template, used by the
+ * wizard's "Import template…" action. Refuses to overwrite an existing id.
+ */
+export declare function importTemplateFromFolder(options: {
+    sourceDir: string;
+    name?: string;
+    templatesRoot: string;
+}): Promise<TemplateInfo>;

package/dist/lib/publish/butler.d.ts

@@ -0,0 +1,10 @@
+import type { PublishDeps } from "./types.ts";
+/** broth channel for the running platform; null when unsupported. */
+export declare function butlerBrothChannel(platform?: NodeJS.Platform, arch?: string): string | null;
+export declare function butlerDownloadUrl(channel: string): string;
+/**
+ * Resolve a runnable butler command, downloading it into the tool cache when
+ * necessary. Returns the command to spawn (an absolute path, or plain
+ * "butler" when found on the PATH).
+ */
+export declare function ensureButler(deps: PublishDeps): Promise<string>;

package/dist/lib/publish/command-runner.d.ts

@@ -0,0 +1,18 @@
+import type { CommandRunner } from "./types.ts";
+/**
+ * Default idle budget (audit B2 / review): applied BY THE RUNNER whenever
+ * `timeoutMs` is omitted, so no call site (a provider upload, a
+ * `commandExists` probe) can silently regain hang-forever behavior by
+ * forgetting to pass it. `timeoutMs: 0` is the explicit opt-out. Idle, not
+ * total — the timer re-arms on every output chunk, so only total silence
+ * kills the child. 5 minutes tolerates upload CLIs that quiet their progress
+ * stream when piped (butler/swa run with stdio piped, not a TTY).
+ */
+export declare const PUBLISH_IDLE_TIMEOUT_MS = 300000;
+export declare const defaultCommandRunner: CommandRunner;
+/**
+ * True when `cmd` resolves to an executable on the PATH. `env` (typically
+ * {@link PublishDeps.env}) is forwarded to the probe so a host-injected PATH
+ * influences resolution the same way it will influence the eventual spawn.
+ */
+export declare function commandExists(cmd: string, runCommand?: CommandRunner, env?: Record<string, string | undefined>): Promise<boolean>;

package/dist/lib/publish/connect.d.ts

@@ -0,0 +1,23 @@
+import { type PublishDeps } from "./types.ts";
+export interface ConnectPublishProviderOptions {
+    projectDir: string;
+    providerId: string;
+    /** The pasted API key. NEVER log this. */
+    token: string;
+    /**
+     * Optional account label for a NAMED credential — lets a user keep several
+     * credentials for one provider (e.g. two itch.io accounts). Stored under the
+     * compound `<host>#<account>` key; empty means the default (bare-host) entry.
+     */
+    account?: string;
+    manifestPath?: string;
+}
+/**
+ * Verify `token` with the platform, then store it. Throws a friendly,
+ * token-free error when the provider needs no key, the paste is empty, or
+ * the platform rejects it — leaving the store untouched in every case.
+ */
+export declare function connectPublishProvider(options: ConnectPublishProviderOptions, deps: PublishDeps): Promise<{
+    connected: true;
+    providerId: string;
+}>;

package/dist/lib/publish/manifest-publish.d.ts

@@ -0,0 +1,9 @@
+/** All `publish.*` sections, as plain JSON keyed by provider id (absent → {}). */
+export declare function readPublishSettings(projectDir: string): Promise<Record<string, Record<string, unknown>>>;
+/**
+ * Merge `values` into `publish.<providerId>`. A value of `undefined`, `null`
+ * or `""` deletes that key; emptied sections (and an emptied `publish:` map)
+ * are removed rather than left dangling. Returns the updated settings straight
+ * from the in-memory document — no re-read.
+ */
+export declare function setPublishProviderConfig(projectDir: string, providerId: string, values: Record<string, unknown>): Promise<Record<string, Record<string, unknown>>>;

package/dist/lib/publish/providers/azure-swa.d.ts

@@ -0,0 +1,3 @@
+import { type PublishProvider } from "../types.ts";
+export declare const AZURE_SWA_HOST = "azure-swa";
+export declare const azureSwaProvider: PublishProvider;

package/dist/lib/publish/providers/drivethrurpg.d.ts

@@ -0,0 +1,10 @@
+/**
+ * DriveThruRPG publish provider (#35) — GUIDED.
+ *
+ * DriveThruRPG has no publisher upload API (its public API is read-only,
+ * customer-side). Publishing stages a validated upload package and opens the
+ * publisher hub with a checklist. If DTRPG ever ships a publisher API this
+ * provider upgrades to kind "api" without changing the author surface.
+ */
+import type { PublishProvider } from "../types.ts";
+export declare const drivethrurpgProvider: PublishProvider;

package/dist/lib/publish/providers/guided.d.ts

@@ -0,0 +1,3 @@
+import type { PublishRequest } from "../types.ts";
+/** Copy the artifact + a LISTING.md metadata sheet into the staging dir. */
+export declare function stageGuidedPackage(req: PublishRequest, providerId: string, listingLines: string[]): Promise<string>;

package/dist/lib/publish/providers/itch.d.ts

@@ -0,0 +1,5 @@
+import { type PublishProvider } from "../types.ts";
+export declare const ITCH_HOST = "itch.io";
+/** `user/game` → the public project page URL. */
+export declare function itchProjectUrl(target: string): string;
+export declare const itchProvider: PublishProvider;

package/dist/lib/publish/providers/kdp.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Amazon KDP publish provider (#35) — GUIDED.
+ *
+ * Amazon has no KDP API and has stated no plans to release one; scripting the
+ * KDP web UI violates its ToS. Publishing stages a KDP-ready package
+ * (interior PDF + listing sheet) and opens the KDP bookshelf with a checklist.
+ */
+import type { PublishProvider } from "../types.ts";
+export declare const kdpProvider: PublishProvider;

package/dist/lib/publish/providers/shopify.d.ts

@@ -0,0 +1,5 @@
+import { type PublishProvider } from "../types.ts";
+export declare const SHOPIFY_HOST = "shopify";
+/** `gid://shopify/Product/123` → `123` (for admin deep links). */
+export declare function shopifyLegacyId(gid: string): string;
+export declare const shopifyProvider: PublishProvider;

package/dist/lib/publish/registry.d.ts

@@ -0,0 +1,5 @@
+import type { PublishProvider, PublishProviderInfo } from "./types.ts";
+/** All providers' static descriptions, in display order. */
+export declare function listPublishProviders(): PublishProviderInfo[];
+/** Look up a provider by id; throws a friendly error listing valid ids. */
+export declare function publishProviderFor(id: string): PublishProvider;

package/dist/lib/publish/run-publish.d.ts

@@ -0,0 +1,30 @@
+import type { PreflightIssue, PublishDeps, PublishOutcome, PublishRequest } from "./types.ts";
+export interface RunPublishOptions {
+    projectDir: string;
+    providerId: string;
+    manifestPath?: string;
+    /**
+     * Explicit artifact path (a PDF file, or the HTML export directory).
+     * Default: the manifest's resolved output location.
+     */
+    artifactPath?: string;
+    /** Stop after preflight — report issues without contacting the platform. */
+    dryRun?: boolean;
+}
+export interface RunPublishResult {
+    ok: boolean;
+    providerId: string;
+    issues: PreflightIssue[];
+    /** Present when the upload ran (not on dry runs / preflight failures). */
+    outcome?: PublishOutcome;
+    /** Friendly failure summary when `ok` is false. */
+    error?: string;
+}
+/**
+ * Resolve the {@link PublishRequest} for a provider from the project's
+ * manifest — shared by `runPublish` and by hosts that call individual
+ * provider methods (authenticate, listProducts) outside a full publish.
+ */
+export declare function resolvePublishRequest(options: Pick<RunPublishOptions, "projectDir" | "providerId" | "manifestPath" | "artifactPath">, deps: PublishDeps): Promise<PublishRequest>;
+/** Preflight → authenticate → upload, with structured results throughout. */
+export declare function runPublish(options: RunPublishOptions, deps: PublishDeps): Promise<RunPublishResult>;

package/dist/lib/publish/selections.d.ts

@@ -0,0 +1,25 @@
+/** Both levels' explicit selections for a provider (for the UI). */
+export interface PublishAccountSelection {
+    project?: string;
+    global?: string;
+}
+export declare class PublishSelectionsStore {
+    readonly filePath: string;
+    private queue;
+    constructor(filePath?: string);
+    private read;
+    private write;
+    private enqueue;
+    /**
+     * The effective default account for a provider: the project selection wins
+     * over the global one; `undefined` when neither is set (→ the default
+     * bare-host credential).
+     */
+    resolve(providerId: string, projectDir?: string): Promise<string | undefined>;
+    /** Both explicit selections for a provider — for a UI that shows each level. */
+    levels(providerId: string, projectDir?: string): Promise<PublishAccountSelection>;
+    /** Set (or clear, with an empty account) the global default for a provider. */
+    setGlobal(providerId: string, account: string | null): Promise<void>;
+    /** Set (or clear) the default for one provider within one project. */
+    setProject(projectDir: string, providerId: string, account: string | null): Promise<void>;
+}