@bendyline/docblocks-cli 2.6.1 → 2.7.0

package/dist/index.d.ts

@@ -3,11 +3,19 @@ import { ContentContainer } from '@bendyline/squisq/storage';
 import * as _bendyline_squisq_cli_api from '@bendyline/squisq-cli/api';
 import { FormatRegistry } from '@bendyline/squisq-cli/api';
 import { VideoQuality, VideoOrientation } from '@bendyline/squisq-video';
+import { WorkspaceOutputLimits, WorkspaceOutputResult } from '@bendyline/docblocks/workspace-settings';
 
 interface BuildOptions {
     input: string;
     output: string;
     theme?: string;
+    /**
+     * Skip `<input>/.docblocks/workspace.json`. Otherwise, when `theme` is
+     * unset, its `documents.defaultTheme` styles documents that name no theme.
+     */
+    ignoreWorkspaceSettings?: boolean;
+    /** Receives non-fatal warnings; defaults to stderr. */
+    onWarning?: (message: string) => void;
     /** Programmatic traversal budget; CLI callers use the safe default. */
     maxEntries?: number;
     /** Programmatic directory-depth budget; CLI callers use the safe default. */
@@ -140,6 +148,53 @@ interface ParseOptions {
 }
 declare function runParse(inputPath: string, options?: ParseOptions): Promise<string>;
 
+/**
+ * workspace command — maintain the outputs a workspace opts into through
+ * `<workspace root>/.docblocks/workspace.json`.
+ *
+ * `workspace refresh` runs the same filesystem-agnostic catalog refresh the
+ * editor shell runs (`@bendyline/docblocks/workspace-settings`) over a Node
+ * adapter, so CI and scripts produce byte-identical `index.html` /
+ * `catalog.json` outputs. Only enabled outputs are written, only files that
+ * carry the DocBlocks catalog marker are replaced, and unchanged bytes are
+ * never rewritten.
+ */
+
+interface WorkspaceRefreshOptions {
+    /** Workspace root; defaults to the current directory. */
+    readonly dir?: string;
+    /** Rewrite the catalog page even when its inputs digest is unchanged. */
+    readonly force?: boolean;
+    /** Compute every output and report what would change; write nothing. */
+    readonly dryRun?: boolean;
+    readonly signal?: AbortSignal;
+    /** Receives non-fatal warnings; defaults to stderr. */
+    readonly onWarning?: (message: string) => void;
+    /** Programmatic budget overrides for the catalog walk. */
+    readonly limits?: Partial<WorkspaceOutputLimits>;
+}
+interface WorkspaceRefreshResult {
+    /** Physical workspace root. */
+    readonly root: string;
+    /**
+     * `missing` when the workspace has no settings file, `disabled` when its
+     * settings enable no output, otherwise `refreshed`.
+     */
+    readonly status: 'missing' | 'disabled' | 'refreshed';
+    readonly documentCount: number;
+    readonly outputs: readonly WorkspaceOutputResult[];
+    readonly dryRun: boolean;
+}
+/**
+ * Regenerate the catalog outputs a workspace enables. Throws when the
+ * settings file is invalid or from a newer DocBlocks, when the walk exceeds
+ * its budget, and on storage failures. A blocked output (a hand-written file
+ * at the configured path) is reported in `outputs`, not thrown.
+ */
+declare function runWorkspaceRefresh(options?: WorkspaceRefreshOptions): Promise<WorkspaceRefreshResult>;
+/** One human-readable status line per output, as printed by the command. */
+declare function describeWorkspaceOutput(output: WorkspaceOutputResult): string;
+
 declare function getPackageVersion(): string;
 
-export { type BuildOptions, type BuildResult, type ConvertOptions, type ConvertResult, type ParseOptions, type VideoOptions, type VideoResult, type VideoRunDependencies, applyTransformToMarkdown, assertCliVideoRenderBudget, getPackageVersion, runBuild, runConvert, runParse, runVideo };
+export { type BuildOptions, type BuildResult, type ConvertOptions, type ConvertResult, type ParseOptions, type VideoOptions, type VideoResult, type VideoRunDependencies, type WorkspaceRefreshOptions, type WorkspaceRefreshResult, applyTransformToMarkdown, assertCliVideoRenderBudget, describeWorkspaceOutput, getPackageVersion, runBuild, runConvert, runParse, runVideo, runWorkspaceRefresh };