@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/documentation-plan.d.ts

@@ -0,0 +1,253 @@
+import { AgentSessionError } from './agent-failure.js';
+export { agentReplyFromStream, extractPlanOutput, readPlanOutput, type PlanReply } from './agent-reply.js';
+import { type ClaudeEffortLevel } from './author.js';
+import { DoxloopError } from './errors.js';
+import { type ReleaseTemplateInput } from './release-notes.js';
+import { type DocumentationDiscoveryInventory } from './source-discovery.js';
+export { discoveryGuidance } from './source-discovery.js';
+import { type RunAuthoringRecord } from './sync-runs.js';
+import type { AgentName, DocumentationPlan, DoxloopProject, DocumentationPlanExecution, DocumentationPlanFailure, DocumentationPlanMode, DocumentationPlanScope, SourceBinding } from './types.js';
+import { assignSectionSpaces } from './plan-navigation.js';
+export { assignSectionSpaces };
+export interface CreateDocumentationPlanInput {
+    mode: DocumentationPlanMode;
+    scope: DocumentationPlanScope;
+    /** Reviewer-requested minimum number of pages to write. */
+    targetPages?: number;
+    request?: string;
+    clarificationMode?: 'review' | 'defaults' | 'stop';
+    execution: DocumentationPlanExecution;
+    /** Start from a content-type template whose inputs Doxloop collects deterministically. */
+    template?: ReleaseTemplateInput;
+}
+export declare function createDocumentationPlan(root: string, input: CreateDocumentationPlanInput): Promise<DocumentationPlan>;
+/** Planner instructions for a content-type template, or nothing for a plain request. */
+export declare function templateInstructions(plan: Pick<DocumentationPlan, 'template'>): string;
+/** Writer instructions derived from the plan: required diagrams and the release inventory. */
+export declare function planWritingRequirements(plan: Pick<DocumentationPlan, 'pages' | 'template' | 'target'>): string;
+export declare function listDocumentationPlans(root: string): Promise<DocumentationPlan[]>;
+export declare function latestDocumentationPlan(root: string): Promise<DocumentationPlan | undefined>;
+export declare function listDocumentationPlanVersions(root: string, id: string): Promise<DocumentationPlan[]>;
+export declare function readDocumentationPlan(root: string, id: string): Promise<DocumentationPlan>;
+/**
+ * The authoring inputs a plan-first generation run starts with. Recorded beside
+ * each run; rebuilt here for runs that predate that record so they can still
+ * be resumed from their approved plan.
+ */
+export declare function planAuthoringRecord(root: string, plan: DocumentationPlan): Promise<Omit<RunAuthoringRecord, 'schemaVersion'>>;
+export declare function proposeDocumentationPlan(root: string, id: string): Promise<DocumentationPlan>;
+/** Validate and persist the structured result returned by any terminal agent. */
+export declare function applyDocumentationPlanProposal(root: string, id: string, raw: unknown, agent?: AgentName): Promise<DocumentationPlan>;
+export declare function beginDocumentationPlanRevision(root: string, id: string, clarificationAnswers?: Record<string, string>): Promise<DocumentationPlan>;
+export declare function reviseDocumentationPlan(root: string, id: string, feedback: string): Promise<DocumentationPlan>;
+export declare function documentationPlanClarificationFeedback(plan: DocumentationPlan, answers: Record<string, string>, useRecommendations?: boolean): string;
+export declare function editDocumentationPlan(root: string, id: string, raw: unknown): Promise<DocumentationPlan>;
+export declare function approveDocumentationPlan(root: string, id: string): Promise<DocumentationPlan>;
+/**
+ * Keep a plan whose configured sources changed after it was proposed. The
+ * reviewer has already read the structure, so re-running the planner for an
+ * unrelated code edit would throw that review away. Refreshing the evidence
+ * snapshot keeps every page as proposed and lets approval proceed; generation
+ * still inspects the current sources when it writes each page.
+ */
+export declare function resumeDocumentationPlan(root: string, id: string): Promise<DocumentationPlan>;
+export declare function cancelDocumentationPlan(root: string, id: string): Promise<DocumentationPlan>;
+/**
+ * Record that a planning or generation process ended without reporting a
+ * result. A process that is killed, crashes, or is stopped from the UI never
+ * reaches its own failure bookkeeping, and a plan left at "planning" offers
+ * the reviewer nothing to retry. Returns the failed plan, or undefined when
+ * the plan had already moved on.
+ */
+export declare function markDocumentationPlanInterrupted(root: string, id: string, stage: DocumentationPlanFailure['stage'], message: string): Promise<DocumentationPlan | undefined>;
+/** Restore only the durable state required to retry an interrupted UI stage. */
+/** Run settings to change; a key present with `undefined` clears that setting. */
+export interface ExecutionChange {
+    agent?: DocumentationPlanExecution['agent'] | undefined;
+    model?: string | undefined;
+    reasoning?: DocumentationPlanExecution['reasoning'] | undefined;
+    effort?: DocumentationPlanExecution['effort'] | undefined;
+}
+/**
+ * Point a plan at another assistant, model, or effort before it runs again
+ * (a retry after the pinned assistant signed out, or a switch in Settings).
+ * An approved plan stays approved: the run settings are not the content the
+ * reviewer approved, so the approval is re-stamped when it was still valid.
+ */
+export declare function updateDocumentationPlanExecution(root: string, id: string, change: ExecutionChange): Promise<DocumentationPlan>;
+export declare function retryDocumentationPlan(root: string, id: string, stage: 'propose' | 'revise' | 'generate'): Promise<DocumentationPlan>;
+export declare function generateApprovedDocumentationPlan(root: string, id: string): Promise<DocumentationPlan>;
+export declare function documentationSourceSnapshot(root: string): Promise<string>;
+export interface ProposalCheckpoint {
+    /** Fingerprint of everything the planner was asked; a different brief or source snapshot invalidates the checkpoint. */
+    key: string;
+    /** Which planning pass produced the reply: the first proposal, or the corrective pass after failed gates. */
+    pass: 'proposal' | 'revised';
+    raw: unknown;
+    /** Deterministic fixes Doxloop applied to read the reply, surfaced on the plan review. */
+    repairs?: string[];
+    savedAt: string;
+}
+/**
+ * Fingerprint of a planning request. Two attempts with the same fingerprint
+ * are asking the same question, so the agent's earlier reply can stand in for
+ * a new one.
+ */
+export declare function proposalCheckpointKey(current: DocumentationPlan, sourceSnapshot: string, feedback?: string): string;
+/**
+ * Keep the agent's reply the moment it arrives. A planning run that is later
+ * stopped by its time limit, a crash, or the user can then continue from
+ * this reply instead of paying for the same planning pass again.
+ */
+export declare function writeProposalCheckpoint(root: string, id: string, checkpoint: Omit<ProposalCheckpoint, 'savedAt'>): Promise<void>;
+export declare function readProposalCheckpoint(root: string, id: string, key: string): Promise<ProposalCheckpoint | undefined>;
+export declare function clearProposalCheckpoint(root: string, id: string): Promise<void>;
+/**
+ * The corrective pass costs as much as the first proposal because the agent
+ * returns the whole plan again, and in real runs it cost more: told to
+ * "re-audit the evidence" and "inspect the reachable application", the
+ * planner signed in and re-explored every screen it had already seen. The
+ * gate names specific pages and specific fields, so the pass is scoped to
+ * them, and the browser is only for a state the first pass never reached.
+ */
+export declare function gateRevisionInstructions(planningIssue: string, firstProposal: unknown, options?: {
+    briefed?: boolean;
+}): string;
+/**
+ * A revision used to return the whole plan again — for a 34-page plan that
+ * was 57 KB of JSON emitted token by token, five minutes of waiting to apply
+ * three answers. The reviser sends only what changed and Doxloop merges it.
+ */
+export declare function planRevisionPatchInstructions(): string;
+/**
+ * Drop the questions the reviewer has answered from a revised plan. The
+ * reviser is told to remove them, but a patch that omits "questions" keeps
+ * the base plan's list, and a plan that still carries an answered question
+ * would pause for input a second time.
+ */
+export declare function withoutAnsweredQuestions(raw: unknown, answers: Record<string, string>): unknown;
+/**
+ * Merge a corrective-pass patch into the proposal it corrects. Pages are
+ * matched by id: a patched page replaces its original, a new id is appended,
+ * and listed ids are removed. Other top-level lists are replaced only when
+ * the patch carries them. A patch that turns out to be a whole plan merges
+ * the same way, page by page.
+ */
+export declare function applyPlanPatch(base: unknown, patch: unknown): unknown;
+/**
+ * Accept a plan the planner could not finish to its own standard. The gate it
+ * missed becomes an advisory on the plan review, where the reviewer can edit
+ * pages, add a screenshot guide, or approve the plan as it is.
+ */
+export declare function ignoreDocumentationPlanError(root: string, id: string): Promise<DocumentationPlan>;
+export type PlanContinuationStrategy = 'resume' | 'ignore-errors';
+/**
+ * Continue a plan whose generation failed, from the proposal workspace that
+ * failure preserved. `resume` starts the agent again in that workspace with a
+ * brief of what already exists, so finished pages and verified screenshots are
+ * kept; `ignore-errors` accepts the existing output for review with every
+ * screenshot problem recorded instead of enforced. Neither starts over.
+ */
+export declare function continueDocumentationPlanGeneration(root: string, id: string, strategy: PlanContinuationStrategy): Promise<DocumentationPlan>;
+export declare const DEFAULT_PLANNING_TIMEOUT_MINUTES = 20;
+/**
+ * How long a planning agent may run before Doxloop stops it. The environment
+ * variable wins over the project budget so a CI job can tighten or relax it
+ * without editing the project.
+ */
+export declare function planningTimeoutMinutes(project: Pick<DoxloopProject, 'sync'>, env?: NodeJS.ProcessEnv): number;
+/**
+ * How long one planning pass may run for a batch. A limit the user set
+ * (environment or monitoring budget) is honoured and capped by the batch's
+ * minutes; otherwise the batch's own minutes apply, never less than the
+ * default, so a comprehensive plan is not cut off at a starter's deadline.
+ */
+export declare function planningTimeoutForBatch(project: Pick<DoxloopProject, 'sync'>, limits: {
+    maxMinutes: number;
+}, env?: NodeJS.ProcessEnv): number;
+/**
+ * Research sessions that all stopped on the agent's sign-in or account are
+ * not "missing briefs to retry": name the cause and the next step instead.
+ */
+export declare function researchBlockedError(error: unknown, blocker: AgentSessionError): DoxloopError;
+export declare function planningTimeoutMessage(minutes: number, agent: string): string;
+/**
+ * Planning is an inventory and grouping task over evidence Doxloop has
+ * already extracted; extra reasoning effort mostly buys slower turns. The
+ * run's effort still applies to authoring, where depth matters.
+ */
+export declare function planningEffort(effort: ClaudeEffortLevel): ClaudeEffortLevel;
+export declare function screenshotPlanningInstructions(briefed?: boolean): string;
+/**
+ * When an existing documentation site is configured, the plan is also an
+ * audit of it: the reviewer sees coverage, gaps, contradictions, and where
+ * every old page lands before any page is rewritten. Product sources decide
+ * facts; without them the plan may restructure but not invent.
+ */
+export declare function existingDocumentationPlanningInstructions(sources: SourceBinding[], discovery: DocumentationDiscoveryInventory, briefed?: boolean): string;
+export declare function existingDocumentationPlanShape(sources: SourceBinding[]): string;
+/**
+ * How the writer follows the approved audit of an existing documentation
+ * site: dispositions are scope, contradictions are corrections, and the old
+ * prose is evidence to rewrite from rather than text to paste.
+ */
+export declare function existingDocumentationWritingRequirements(plan: Pick<DocumentationPlan, 'existingDocumentation' | 'pages'>): string;
+/** Titles and URLs of crawled pages, keyed by docs-site source name and snapshot path. */
+export type ExistingPageDetails = Map<string, Map<string, {
+    title: string;
+    url: string;
+}>>;
+/**
+ * Add the title and URL of every existing page the plan names, from the
+ * snapshot manifest. The planner lists pages by path only, which keeps its
+ * reply shorter; the review still shows readers what each page was.
+ */
+export declare function fillExistingPageDetails(raw: unknown, details: ExistingPageDetails): unknown;
+/**
+ * The audit of an existing documentation site is what the reviewer approves
+ * before a rewrite, so a first proposal that skips it is not approvable.
+ */
+export declare function existingDocumentationPlanIssue(plan: Pick<DocumentationPlan, 'existingDocumentation'>, base: Pick<DocumentationPlan, 'mode' | 'status'>, sources: SourceBinding[]): string | undefined;
+/** Crawled pages the plan never placed are reported for the reviewer rather than sent back to the planner. */
+export declare function existingDocumentationAdvisory(plan: Pick<DocumentationPlan, 'existingDocumentation'>, sources: SourceBinding[], discovery: Pick<DocumentationDiscoveryInventory, 'sources'>): string | undefined;
+/**
+ * Fix what a corrective planning pass would only relabel. In required
+ * screenshot mode every screenshot-enabled page is required by definition,
+ * so a "recommended" label is a wording slip, not a planning decision, and
+ * a second full pass to change the word costs as much as the first proposal.
+ *
+ * The same goes for the other slips the required-screenshot gate catches: a
+ * guide whose visual purpose landed in the page's own rationale, a start path
+ * written without its leading slash, or a workflow the planner left out while
+ * spelling the same steps out in the capture sequence. Real runs paid a second
+ * planning pass — six to twenty minutes, with the browser exploration repeated
+ * — for each of these, so they are repaired here and reported on the log.
+ */
+/** The capture IDs the application research brief recorded, or undefined when there is no brief. */
+export declare function knownPlanningCaptureIds(root: string, planId: string): Promise<Set<string> | undefined>;
+/** Blank every visuals.captureIds entry that names no saved capture; returns how many were blanked. */
+export declare function dropUnknownCaptureIds(raw: unknown, known: ReadonlySet<string>): number;
+export declare function repairMechanicalPlanIssues(raw: unknown, execution: DocumentationPlanExecution): unknown;
+export declare function requiredScreenshotPlanIssue(plan: Pick<DocumentationPlan, 'pages'>, execution: DocumentationPlanExecution): string | undefined;
+/**
+ * Thin screenshot coverage, reported for human review rather than enforced. One
+ * guide covering several documented workflows usually means the planner only
+ * ever saw the application's entry screen — but an application parked on its
+ * first-run state genuinely has nothing else to show, and failing the plan for
+ * that would leave the reviewer with no way forward.
+ */
+/** A screenshot-enabled guide needs at least one useful image, without a per-type quota. */
+export declare const MINIMUM_GUIDE_CAPTURES = 1;
+/** Flag screenshot-enabled guides without a capture; one meaningful image is enough. */
+export declare function shallowCaptureAdvisory(plan: Pick<DocumentationPlan, 'pages'>, execution: DocumentationPlanExecution): string | undefined;
+export declare function screenshotCoverageAdvisory(plan: Pick<DocumentationPlan, 'pages'>, execution: DocumentationPlanExecution): string | undefined;
+export declare function contentSafePath(path: string): string;
+/**
+ * Doxbrix serves a page at its file name, so two planned pages called
+ * "troubleshooting" in different folders would publish as one. Later pages
+ * with a taken name get their folder in front of it ("embed/embed-troubleshooting").
+ */
+export declare function uniquePageFileNames(pages: Array<{
+    path: string;
+}>): void;
+//# sourceMappingURL=documentation-plan.d.ts.map