@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/authoring-progress.d.ts

@@ -0,0 +1,95 @@
+import { type WorkflowStageProgress, type WorkflowStageStatus } from './job-events.js';
+import type { DocumentationPlan, DoxloopProject } from './types.js';
+/**
+ * Stage identifiers shared by the plan pipeline and the authoring run, so the
+ * pipeline can announce the stages up front and the run can advance them as
+ * the agent actually writes files.
+ */
+export declare const AUTHORING_STAGE: {
+    readonly authoring: "authoring-pages";
+    readonly navigation: "updating-navigation";
+    readonly evidence: "recording-evidence";
+    readonly screenshots: "capturing-screenshots";
+    readonly validating: "validating";
+};
+export type AuthoringActivityKind = 'page' | 'navigation' | 'evidence' | 'screenshot' | 'validation';
+export interface AuthoringActivity {
+    kind: AuthoringActivityKind;
+    /** Workspace-relative path when the activity is a file the agent wrote. */
+    path?: string;
+}
+export interface WorkspaceLayout {
+    /** Content directory relative to the workspace root, '' for the root itself. */
+    contentDir: string;
+    pageExtensions: readonly string[];
+    /** Workspace-relative navigation and theme files. */
+    navigationFiles: readonly string[];
+}
+export declare function portableWorkspacePath(path: string): string;
+/** Decide what a file the agent wrote says about the run's progress. */
+export declare function classifyWorkspaceFile(rawPath: string, layout: WorkspaceLayout): AuthoringActivity | undefined;
+/**
+ * Turn an agent tool call into an activity the file watcher cannot see: a
+ * screenshot request to the capture server, or a validation command. Every
+ * agent's log formatter reports calls in Claude's vocabulary (`Bash` with a
+ * `command`, `mcp__<server>__<tool>`); Gemini exposes MCP tools by their bare
+ * name, so a tool whose own name says "screenshot" counts as well.
+ */
+export declare function classifyAgentToolCall(tool: string, input: Record<string, unknown>, options?: {
+    captureServer?: string;
+}): AuthoringActivity | undefined;
+export declare function workspaceLayout(root: string, project: DoxloopProject): Promise<WorkspaceLayout>;
+/** Pages an approved plan asks the agent to write or rewrite. */
+export declare function plannedPageCount(plan: Pick<DocumentationPlan, 'pages'> | undefined): number | undefined;
+export interface AuthoringStageEmitter {
+    (id: string, label: string, status: WorkflowStageStatus, progress?: WorkflowStageProgress): void;
+}
+export interface AuthoringProgressOptions {
+    /** Number of pages the run is expected to write, shown as "N of M". */
+    plannedPages?: number | undefined;
+    /** Whether the run may capture application screenshots. */
+    screenshots: boolean;
+    /** Copy for the page stage; edits and generation read differently. */
+    pageLabel?: string;
+    emit?: AuthoringStageEmitter;
+}
+/**
+ * Advance the workflow stages from what the agent really does: a page write
+ * starts the authoring stage and counts towards the planned total, a
+ * navigation write starts the navigation stage, and so on. Every stage is
+ * announced as pending first so the reader sees the whole path at once.
+ */
+export declare class AuthoringProgressTracker {
+    private readonly stages;
+    private readonly pages;
+    private readonly emit;
+    private readonly plannedPages;
+    private finished;
+    constructor(options: AuthoringProgressOptions);
+    /** Announce every stage before the agent starts. */
+    begin(): void;
+    record(activity: AuthoringActivity): void;
+    /** The agent exited: Doxloop now validates what it left behind. */
+    validating(): void;
+    /**
+     * Settle the agent's stages after a successful run. Stages that never saw
+     * activity say so instead of pretending the work happened.
+     */
+    finish(): void;
+    pagesWritten(): number;
+    /**
+     * Pages a resumed run found finished and keeps. They count as done from
+     * the start, so the reviewer sees "35 of 35" instead of a run that seems
+     * to begin from nothing and then only ever reaches the pages it repaired.
+     */
+    retain(paths: readonly string[]): void;
+    private start;
+    private progressFor;
+}
+/**
+ * Watch the run workspace so progress is derived from files for every agent,
+ * including the ones whose output Doxloop does not parse. Resolves once the
+ * watcher is armed; the returned function stops it.
+ */
+export declare function watchWorkspaceActivity(workspace: string, layout: WorkspaceLayout, onActivity: (activity: AuthoringActivity) => void): Promise<() => Promise<void>>;
+//# sourceMappingURL=authoring-progress.d.ts.map

package/dist/authoring-progress.js

@@ -0,0 +1,269 @@
+import { extname, relative } from 'node:path';
+import chokidar from 'chokidar';
+import { EVIDENCE_MAP_FILE } from './evidence.js';
+import { loadGeneratorAdapter } from './generators.js';
+import { emitWorkflowStage } from './job-events.js';
+import { relativePath, siteConfigPath } from './project.js';
+import { SCREENSHOT_MANIFEST_FILE } from './screenshot-workflow.js';
+/**
+ * Stage identifiers shared by the plan pipeline and the authoring run, so the
+ * pipeline can announce the stages up front and the run can advance them as
+ * the agent actually writes files.
+ */
+export const AUTHORING_STAGE = {
+    authoring: 'authoring-pages',
+    navigation: 'updating-navigation',
+    evidence: 'recording-evidence',
+    screenshots: 'capturing-screenshots',
+    validating: 'validating',
+};
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.avif']);
+const IGNORED_SEGMENTS = new Set(['.git', 'node_modules', '.doxloop-sources']);
+const CAPTURE_OUTPUT_PREFIX = '.doxloop/capture-output/';
+export function portableWorkspacePath(path) {
+    return path.replaceAll('\\', '/').replace(/^\.\//, '').replace(/^\/+/, '');
+}
+/** Decide what a file the agent wrote says about the run's progress. */
+export function classifyWorkspaceFile(rawPath, layout) {
+    const path = portableWorkspacePath(rawPath);
+    if (!path || path.split('/').some((segment) => IGNORED_SEGMENTS.has(segment)))
+        return undefined;
+    if (path === portableWorkspacePath(EVIDENCE_MAP_FILE))
+        return { kind: 'evidence', path };
+    if (path === portableWorkspacePath(SCREENSHOT_MANIFEST_FILE))
+        return { kind: 'screenshot' };
+    if (path.startsWith(CAPTURE_OUTPUT_PREFIX))
+        return { kind: 'screenshot', path };
+    if (path.startsWith('.doxloop/'))
+        return undefined;
+    const extension = extname(path).toLowerCase();
+    if (IMAGE_EXTENSIONS.has(extension))
+        return { kind: 'screenshot', path };
+    const navigation = new Set(layout.navigationFiles.map(portableWorkspacePath));
+    if (navigation.has(path))
+        return { kind: 'navigation', path };
+    const content = portableWorkspacePath(layout.contentDir).replace(/\/+$/, '');
+    const insideContent = !content || path === content || path.startsWith(`${content}/`);
+    if (insideContent && layout.pageExtensions.some((candidate) => candidate.toLowerCase() === extension)) {
+        return { kind: 'page', path };
+    }
+    return undefined;
+}
+/**
+ * Turn an agent tool call into an activity the file watcher cannot see: a
+ * screenshot request to the capture server, or a validation command. Every
+ * agent's log formatter reports calls in Claude's vocabulary (`Bash` with a
+ * `command`, `mcp__<server>__<tool>`); Gemini exposes MCP tools by their bare
+ * name, so a tool whose own name says "screenshot" counts as well.
+ */
+export function classifyAgentToolCall(tool, input, options = {}) {
+    const capturePrefix = options.captureServer ? `mcp__${options.captureServer}__` : undefined;
+    if (capturePrefix && tool.startsWith(capturePrefix)) {
+        return /screenshot|snapshot|capture/i.test(tool.slice(capturePrefix.length)) ? { kind: 'screenshot' } : undefined;
+    }
+    if (!tool.startsWith('mcp__') && /screenshot/i.test(tool))
+        return { kind: 'screenshot' };
+    if (tool === 'Bash') {
+        const command = typeof input.command === 'string' ? input.command : '';
+        if (/\bdoxloop\s+(test|quality)\b/.test(command))
+            return { kind: 'validation' };
+    }
+    return undefined;
+}
+export async function workspaceLayout(root, project) {
+    if (project.generator === 'doxbrix') {
+        let navigationFiles = ['docs.json'];
+        try {
+            navigationFiles = [portableWorkspacePath(relativePath(root, await siteConfigPath(root, project)))];
+        }
+        catch {
+            // A workspace without a site configuration yet still has pages to count.
+        }
+        return { contentDir: project.contentDir, pageExtensions: ['.md', '.mdx'], navigationFiles };
+    }
+    try {
+        const adapter = await loadGeneratorAdapter(root, project);
+        return {
+            contentDir: project.contentDir,
+            pageExtensions: adapter.project.pageExtensions,
+            navigationFiles: adapter.planning?.navigationFiles ?? [],
+        };
+    }
+    catch {
+        return { contentDir: project.contentDir, pageExtensions: ['.md', '.mdx'], navigationFiles: [] };
+    }
+}
+/** Pages an approved plan asks the agent to write or rewrite. */
+export function plannedPageCount(plan) {
+    if (!plan)
+        return undefined;
+    const count = plan.pages.filter((page) => page.action === 'create' || page.action === 'update').length;
+    return count > 0 ? count : undefined;
+}
+/**
+ * Advance the workflow stages from what the agent really does: a page write
+ * starts the authoring stage and counts towards the planned total, a
+ * navigation write starts the navigation stage, and so on. Every stage is
+ * announced as pending first so the reader sees the whole path at once.
+ */
+export class AuthoringProgressTracker {
+    stages;
+    pages = new Set();
+    emit;
+    plannedPages;
+    finished = false;
+    constructor(options) {
+        this.emit = options.emit ?? emitWorkflowStage;
+        this.plannedPages = options.plannedPages;
+        const pageLabel = options.pageLabel ?? 'Authoring approved pages';
+        this.stages = [
+            { id: AUTHORING_STAGE.authoring, label: pageLabel, idleLabel: 'No pages were written', status: 'pending' },
+            { id: AUTHORING_STAGE.navigation, label: 'Updating navigation and theme', idleLabel: 'Navigation and theme unchanged', status: 'pending' },
+            { id: AUTHORING_STAGE.evidence, label: 'Recording page evidence', idleLabel: 'Page evidence unchanged', status: 'pending' },
+            ...(options.screenshots
+                ? [{ id: AUTHORING_STAGE.screenshots, label: 'Capturing application screenshots', idleLabel: 'No application screenshots captured', status: 'pending' }]
+                : []),
+            { id: AUTHORING_STAGE.validating, label: 'Validating generated documentation', idleLabel: 'Validating generated documentation', status: 'pending' },
+        ];
+    }
+    /** Announce every stage before the agent starts. */
+    begin() {
+        for (const stage of this.stages)
+            this.emit(stage.id, stage.label, 'pending', this.progressFor(stage.id));
+    }
+    record(activity) {
+        if (this.finished)
+            return;
+        switch (activity.kind) {
+            case 'page': {
+                if (!activity.path || this.pages.has(activity.path))
+                    return;
+                this.pages.add(activity.path);
+                this.start(AUTHORING_STAGE.authoring, true);
+                return;
+            }
+            case 'navigation':
+                this.start(AUTHORING_STAGE.navigation);
+                return;
+            case 'evidence':
+                this.start(AUTHORING_STAGE.evidence);
+                return;
+            case 'screenshot':
+                this.start(AUTHORING_STAGE.screenshots);
+                return;
+            case 'validation':
+                this.start(AUTHORING_STAGE.validating);
+                return;
+            default:
+                return;
+        }
+    }
+    /** The agent exited: Doxloop now validates what it left behind. */
+    validating() {
+        this.start(AUTHORING_STAGE.validating);
+    }
+    /**
+     * Settle the agent's stages after a successful run. Stages that never saw
+     * activity say so instead of pretending the work happened.
+     */
+    finish() {
+        if (this.finished)
+            return;
+        this.finished = true;
+        for (const stage of this.stages) {
+            if (stage.id === AUTHORING_STAGE.validating)
+                continue;
+            if (stage.status === 'running') {
+                stage.status = 'completed';
+                this.emit(stage.id, stage.label, 'completed', this.progressFor(stage.id));
+            }
+            else if (stage.status === 'pending') {
+                stage.status = 'completed';
+                this.emit(stage.id, stage.idleLabel, 'completed', this.progressFor(stage.id));
+            }
+        }
+    }
+    pagesWritten() {
+        return this.pages.size;
+    }
+    /**
+     * Pages a resumed run found finished and keeps. They count as done from
+     * the start, so the reviewer sees "35 of 35" instead of a run that seems
+     * to begin from nothing and then only ever reaches the pages it repaired.
+     */
+    retain(paths) {
+        if (this.finished)
+            return;
+        let added = false;
+        for (const raw of paths) {
+            const path = portableWorkspacePath(raw);
+            if (!path || this.pages.has(path))
+                continue;
+            this.pages.add(path);
+            added = true;
+        }
+        if (added)
+            this.start(AUTHORING_STAGE.authoring, true);
+    }
+    start(id, reemit = false) {
+        const stage = this.stages.find((candidate) => candidate.id === id);
+        if (!stage)
+            return;
+        if (stage.status === 'running' && !reemit)
+            return;
+        if (stage.status !== 'running' && stage.status !== 'pending')
+            return;
+        stage.status = 'running';
+        this.emit(stage.id, stage.label, 'running', this.progressFor(stage.id));
+    }
+    progressFor(id) {
+        if (id !== AUTHORING_STAGE.authoring)
+            return undefined;
+        if (this.pages.size === 0 && this.plannedPages === undefined)
+            return undefined;
+        // Starter pages the run replaces and pages a fix session rewrites are
+        // files too; the count never reads "36 of 32".
+        const done = this.plannedPages !== undefined ? Math.min(this.pages.size, this.plannedPages) : this.pages.size;
+        return { done, ...(this.plannedPages !== undefined ? { total: this.plannedPages } : {}) };
+    }
+}
+/**
+ * Watch the run workspace so progress is derived from files for every agent,
+ * including the ones whose output Doxloop does not parse. Resolves once the
+ * watcher is armed; the returned function stops it.
+ */
+export async function watchWorkspaceActivity(workspace, layout, onActivity) {
+    const watcher = chokidar.watch(workspace, {
+        ignoreInitial: true,
+        persistent: true,
+        ignored: (path) => {
+            const rel = portableWorkspacePath(relative(workspace, path));
+            return rel.split('/').some((segment) => IGNORED_SEGMENTS.has(segment));
+        },
+    });
+    const report = (path) => {
+        const activity = classifyWorkspaceFile(relative(workspace, path), layout);
+        if (activity)
+            onActivity(activity);
+    };
+    watcher.on('add', report);
+    watcher.on('change', report);
+    watcher.on('error', () => undefined);
+    await new Promise((resolveReady) => {
+        const timer = setTimeout(resolveReady, 5_000);
+        timer.unref?.();
+        watcher.once('ready', () => {
+            clearTimeout(timer);
+            resolveReady();
+        });
+    });
+    return async () => {
+        try {
+            await watcher.close();
+        }
+        catch {
+            // A watcher that already stopped has nothing left to release.
+        }
+    };
+}
+//# sourceMappingURL=authoring-progress.js.map

package/dist/autosync.d.ts

@@ -0,0 +1,56 @@
+import { runAuthor } from './author.js';
+import { type PromptIo } from './prompts.js';
+import { installSchedule, removeSchedule, scheduleState } from './schedule.js';
+import { type CreateSyncRunOptions } from './sync-runs.js';
+import type { DoxloopProject, SyncConfig, SyncMode, SyncRunTrigger, SyncTrigger } from './types.js';
+export declare function replaySyncSetupCommand(sync: SyncConfig): string;
+export declare function parseTriggerList(raw: string): SyncTrigger[];
+export declare function parseSyncMode(raw: string): SyncMode;
+/** Use provider APIs whenever a remote source is configured. */
+export declare function computeConfiguredDrift(root: string, project: DoxloopProject): Promise<import("./types.js").DriftResult>;
+/** The native scheduler, replaceable in tests so no real job is registered. */
+export interface SyncScheduler {
+    install: typeof installSchedule;
+    remove: typeof removeSchedule;
+    state: typeof scheduleState;
+}
+/**
+ * Apply a sync configuration: persist it, then make the local machine match it.
+ * Installing and removing are the same operation with different inputs, so a
+ * project can move between trigger sets without leaving orphaned jobs behind.
+ * Local folders are checked in place: a Git checkout by its HEAD commit and
+ * working tree, any other folder by the content it held at the last sync.
+ * Nothing is fetched, pulled, or written in the source, so a local folder
+ * needs no remote to be scheduled.
+ */
+export declare function applySyncConfig(root: string, project: DoxloopProject, sync: SyncConfig, scheduler?: SyncScheduler): Promise<string[]>;
+export declare function runSyncSetupWizard(options: {
+    root: string;
+    project: DoxloopProject;
+    io: PromptIo;
+}): Promise<SyncConfig | undefined>;
+/**
+ * Prove the automation can actually run before anyone depends on it. An expired
+ * agent sign-in is the most common silent failure for unattended runs, so it is
+ * checked here rather than discovered at 09:00 three weeks later.
+ */
+export declare function formatSyncStatus(root: string, project: DoxloopProject): Promise<string>;
+/**
+ * One full maintenance cycle. Detection always runs; authoring runs only when
+ * the mode allows it, the configured branch is checked out, and the run budget
+ * has not been spent.
+ */
+interface RunSyncOptions {
+    root: string;
+    project: DoxloopProject;
+    quiet?: boolean;
+    trigger?: SyncRunTrigger;
+    /** Test seam; production callers always use the real author runner. */
+    author?: typeof runAuthor;
+    /** Manual authoring request and controls supplied by the workspace UI. */
+    authoring?: CreateSyncRunOptions['authoring'];
+}
+export declare function runSyncNow(options: RunSyncOptions): Promise<number>;
+export declare function disableSync(root: string, project: DoxloopProject): Promise<string[]>;
+export {};
+//# sourceMappingURL=autosync.d.ts.map