@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/sync-runs.d.ts

@@ -0,0 +1,192 @@
+import { runAuthor, type ClaudeEffortLevel, type ReasoningLevel, type ScreenshotIntent } from './author.js';
+import type { ValidationIssue, AgentName, DocumentationPlan, DoxloopProject, DriftResult, SourceChange, SyncRun, SyncRunTrigger, SyncState } from './types.js';
+export declare const SYNC_RUNS_DIRECTORY: string;
+export interface CreateSyncRunOptions {
+    id?: string;
+    root: string;
+    project: DoxloopProject;
+    drift: DriftResult;
+    sourceChanges: SourceChange[];
+    /** Isolated evidence paths used only inside the proposal workspace. */
+    authoringSources?: DoxloopProject['sources'];
+    trigger?: SyncRunTrigger;
+    author?: typeof runAuthor;
+    /** Baseline to place in the proposal and apply only after approval. */
+    nextSyncState?: SyncState;
+    /** Approved plan that originated this proposal, when generation is plan-first. */
+    plan?: DocumentationPlan;
+    /** Existing proposal whose isolated workspace seeds a targeted revision. */
+    revisionOf?: string;
+    revisionRequest?: {
+        instruction: string;
+        changeIds: string[];
+        hunkIds?: string[];
+    };
+    editRequest?: SyncRun['editRequest'];
+    /** User-selected authoring controls for a manual workspace update. */
+    authoring?: {
+        mode?: 'create' | 'update';
+        /** The user-facing instruction saved in history when the agent prompt is generated internally. */
+        historyRequest?: string;
+        request?: string;
+        agent?: AgentName;
+        model?: string;
+        reasoning?: ReasoningLevel;
+        effort?: ClaudeEffortLevel;
+        screenshots?: ScreenshotIntent;
+    };
+}
+export interface AcceptSelection {
+    changeId: string;
+    hunkIds?: string[];
+}
+export interface AcceptOptions {
+    /**
+     * Apply changes flagged `changedDuringRun` even though they replace an
+     * edit made in the project while the agent ran.
+     */
+    confirmChangedDuringRun?: boolean;
+}
+export interface ReviseSyncRunInput {
+    instruction: string;
+    changeIds: string[];
+    hunkIds?: string[];
+    author?: typeof runAuthor;
+    trigger?: SyncRunTrigger;
+}
+/** Generate and validate a proposal without changing the real documentation. */
+export declare function createSyncRun(options: CreateSyncRunOptions): Promise<SyncRun>;
+/** The inputs a proposal's agent run was started with, persisted beside the run. */
+export interface RunAuthoringRecord {
+    schemaVersion: 1;
+    mode: 'create' | 'update';
+    trigger: SyncRunTrigger;
+    screenshots: ScreenshotIntent;
+    request?: string;
+    historyRequest?: string;
+    agent?: AgentName;
+    model?: string;
+    reasoning?: ReasoningLevel;
+    effort?: ClaudeEffortLevel;
+    timeoutMinutes?: number;
+    changeSummary?: string;
+    authoringSources?: DoxloopProject['sources'];
+    nextSyncState?: SyncState;
+    editRequest?: SyncRun['editRequest'];
+}
+/**
+ * Doxloop's deterministic repairs over a finished workspace: navigation and
+ * frontmatter, links to pages that exist, embeds of images that do not, and
+ * the generated starter pages the plan superseded. No agent session.
+ */
+export declare function repairWorkspaceBeforeReview(workspace: string, project: DoxloopProject, plan: DocumentationPlan, issues: ValidationIssue[]): Promise<string[]>;
+export interface RecoverSyncRunOptions {
+    /**
+     * Accept the preserved output even though its screenshots do not satisfy
+     * the run's requirement. Each problem is recorded on the affected step and
+     * on the proposal so the reviewer can see exactly what was skipped.
+     */
+    ignoreScreenshotProblems?: boolean;
+    /**
+     * Repair a finished proposal that validation errors keep from being
+     * applied: run Doxloop's deterministic post-pass over its workspace
+     * (navigation placement, broken links turned into plain text, evidence
+     * entries) and collect the proposal again. No agent session is started.
+     */
+    repair?: boolean;
+}
+/**
+ * Re-run the post-agent finalization pipeline on a failed run's preserved
+ * workspace and promote it to review. This recovers completed agent work when
+ * the failure happened after authoring — for example a screenshot-manifest
+ * validation defect — without paying for another full agent run.
+ */
+export declare function recoverSyncRun(root: string, id: string, options?: RecoverSyncRunOptions): Promise<SyncRun>;
+export interface ResumeSyncRunOptions {
+    author?: typeof runAuthor;
+    /**
+     * Instructions to continue with when the run predates the recorded
+     * authoring inputs. A plan-first run can rebuild them from its approved plan.
+     */
+    fallbackAuthoring?: Omit<RunAuthoringRecord, 'schemaVersion'>;
+}
+/**
+ * Continue a failed or interrupted run's agent inside its preserved workspace.
+ *
+ * The agent is started with the same instructions as before plus a brief of
+ * what already exists — verified screenshots, finished guides, the reason the
+ * run stopped — so it completes only the unfinished part instead of writing
+ * every page and capturing every image again. The run keeps its id, so the
+ * plan that started it and its review history stay attached.
+ */
+export declare function resumeSyncRun(root: string, id: string, options?: ResumeSyncRunOptions): Promise<SyncRun>;
+export declare function listSyncRuns(root: string): Promise<SyncRun[]>;
+export declare function readSyncRun(root: string, id: string): Promise<SyncRun>;
+export declare function rejectSyncRun(root: string, id: string): Promise<SyncRun>;
+export declare function rejectSyncChanges(root: string, id: string, selections?: AcceptSelection[], reason?: string): Promise<SyncRun>;
+export declare function reviseSyncRun(root: string, id: string, input: ReviseSyncRunInput): Promise<SyncRun>;
+export declare function readSyncRunChangeContent(root: string, id: string, changeId: string): Promise<{
+    content: string;
+    path: string;
+    fingerprint: string;
+    evidenceDisposition: 'preserved' | 'needs-review';
+}>;
+export declare function editSyncRunChange(root: string, id: string, changeId: string, content: string, evidenceDisposition: 'preserved' | 'needs-review', fingerprint?: string): Promise<SyncRun>;
+export declare function undoSyncRun(root: string, id: string): Promise<SyncRun>;
+export declare function archiveSyncRun(root: string, id: string): Promise<SyncRun>;
+export declare function pruneSyncRuns(root: string, now?: Date): Promise<string[]>;
+export declare function acceptSyncChanges(root: string, id: string, selections: AcceptSelection[], options?: AcceptOptions): Promise<SyncRun>;
+/** Project-relative paths of the proposal's changes that still have hunks neither accepted nor rejected. */
+export declare function pendingProposalPaths(changes: Array<{
+    path: string;
+    hunks: Array<{
+        acceptedAt?: string;
+        rejectedAt?: string;
+    }>;
+}>): Set<string>;
+/**
+ * Whether a validation error is one the not-yet-accepted part of the same
+ * proposal takes care of: an error on a file the proposal still replaces,
+ * or a page missing from a navigation the proposal still updates. Such an
+ * error is real for the workspace as it stands and gone once the reviewer
+ * accepts the rest, so it must not block accepting one file at a time.
+ */
+export declare function resolvedByPendingChanges(issue: {
+    code: string;
+    file?: string;
+    message?: string;
+}, pending: Set<string>): boolean;
+export declare function formatSyncRunHistory(runs: SyncRun[]): string;
+export declare function pendingRunCount(runs: SyncRun[]): number;
+export declare function runWorkspace(root: string, id: string): string;
+export declare function runBeforeRoot(root: string, id: string): string;
+/**
+ * Where a file moved since the run started: only in the agent's workspace,
+ * only in the project, or in both. Hashes are enough — the live content is
+ * the "before" side either way, and a file the agent never touched is not a
+ * proposal change no matter what happened to it in the project.
+ */
+export declare function compareWithBaseline(baselineHash: string | undefined, live: Buffer | undefined, proposed: Buffer | undefined): 'agent-only' | 'project-only' | 'both';
+export interface RevisionScope {
+    selectedPaths: Set<string>;
+    supportingPaths: Set<string>;
+    /** Related assets may be newly created below these page-slug prefixes. */
+    supportingPrefixes?: Set<string>;
+    /** Page-shaped files never qualify as related assets. */
+    pageExtensions?: Set<string>;
+    wholeProposal: boolean;
+    hunkRanges: Map<string, Array<{
+        start: number;
+        end: number;
+    }>>;
+}
+export declare function assertRevisionStayedInScope(workspace: string, baseline: Map<string, Buffer>, scope: RevisionScope, edit?: boolean): Promise<void>;
+/**
+ * A run left at "generating" by a process that is gone (cancelled, killed, or
+ * the UI server restarted) is marked failed so Review offers Resume instead
+ * of showing it as still being written. Only runs created after `since`
+ * are touched, so an older interrupted run keeps whatever it recorded.
+ */
+export declare function markInterruptedSyncRuns(root: string, since: string, message: string): Promise<string[]>;
+export declare function createRunId(): string;
+//# sourceMappingURL=sync-runs.d.ts.map