@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/deploy.js

@@ -1,12 +1,21 @@
-import { readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { mkdtemp, rm, readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
 import { apiUrl, authenticatedRequest, authenticatedRequestOptional, } from './auth.js';
 import { DoxloopError } from './errors.js';
+import { pushDeploymentBundle } from './bundle-upload.js';
 import { listFiles, resolveContainedDirectory } from './fs.js';
+import { recordDeployment } from './history.js';
 import { deployGeneratedSite } from './artifact-deploy.js';
+import { packageStaticOutput, writeDryRunArchive } from './artifact-deploy.js';
+import { buildDoxbrixStaticSite } from './doxbrix-build.js';
 import { deploymentVisibility, updateDeploymentVisibility, } from './deployment-visibility.js';
-import { loadPages, loadProject, loadSiteConfig, relativePath, } from './project.js';
+import { loadPages, loadProject, loadSiteConfig, relativePath, ROOT_CONTENT_IGNORED_DIRECTORIES, } from './project.js';
 import { createStepList, formatDuration } from './progress.js';
 import { validateProject } from './validation.js';
+import { loadQualityConfig } from './quality-config.js';
+import { readVerificationMetadata } from './quality-claims.js';
+import { publishStaticTarget } from './deploy-targets/index.js';
 const MEDIA_EXTENSIONS = new Set([
     '.avif',
     '.bmp',
@@ -34,12 +43,29 @@ export async function deploy(options) {
     const project = await loadProject(options.root);
     const name = options.name?.trim() || project.title;
     const slug = options.slug?.trim() || slugify(project.title);
+    const target = options.target ?? project.deployment?.target ?? 'doxbrix';
+    if (target !== 'doxbrix') {
+        await publishStaticTarget(target, {
+            root: options.root,
+            name,
+            slug,
+            ...(options.dryRun === undefined ? {} : { dryRun: options.dryRun }),
+            ...(options.apiUrl ? { apiUrl: options.apiUrl } : {}),
+            ...(options.siteId ? { siteId: options.siteId } : {}),
+            ...(options.projectId ? { projectId: options.projectId } : {}),
+            ...(options.teamId ? { teamId: options.teamId } : {}),
+            ...(options.branch ? { branch: options.branch } : {}),
+            ...(options.basePath ? { basePath: options.basePath } : {}),
+        });
+        return;
+    }
     const visibility = deploymentVisibility(options.public);
     process.stdout.write(`Documentation project:\n  ${options.root}\nProduct sources excluded from deployment: ${project.sources.length}\n\n`);
     if (project.generator !== 'doxbrix') {
         return deployGeneratedSite({ ...options, name, slug });
     }
     const steps = createStepList();
+    const startedAt = new Date().toISOString();
     process.stdout.write(`Deploying "${name}" as ${visibility} → ${apiUrl(options.apiUrl)}\n\n`);
     try {
         const validating = steps.start('Validating documentation');
@@ -53,7 +79,20 @@ export async function deploy(options) {
         const bytes = Buffer.byteLength(JSON.stringify(bundle));
         building.done('Built bundle', `${count(bundle.pages.length, 'page')}${bundle.media.length > 0 ? `, ${count(bundle.media.length, 'media file')}` : ''}, ${formatBytes(bytes)}`);
         if (options.dryRun) {
-            process.stdout.write(`\nDeployment is valid.\nProject: ${name}\nSlug: ${slug}\nVisibility: ${visibility}\nPages: ${bundle.pages.length}\nMedia files: ${bundle.media.length}\nPayload: ${formatBytes(bytes)}\nNo data was uploaded.\n`);
+            const temporary = await mkdtemp(join(tmpdir(), 'doxloop-dry-run-'));
+            try {
+                const staticBuild = await buildDoxbrixStaticSite({
+                    root: options.root,
+                    outDir: join(temporary, 'build'),
+                    ...(process.env.DOXLOOP_SITE_URL ? { siteUrl: process.env.DOXLOOP_SITE_URL } : {}),
+                });
+                const packaged = await packageStaticOutput(staticBuild.outputDir);
+                const archivePath = await writeDryRunArchive(options.root, packaged.archive);
+                process.stdout.write(`\nDeployment is valid.\nProject: ${name}\nSlug: ${slug}\nVisibility: ${visibility}\nPages: ${bundle.pages.length}\nMedia files: ${bundle.media.length}\nPayload: ${formatBytes(bytes)}\nArchive: ${archivePath}\nNo data was uploaded.\n`);
+            }
+            finally {
+                await rm(temporary, { recursive: true, force: true });
+            }
             return;
         }
         const locating = steps.start('Locating project');
@@ -75,29 +114,59 @@ export async function deploy(options) {
             locating.done(`Created project "${target.name}" (${target.slug})`);
         }
         const publishing = steps.start('Publishing to Doxbrix');
-        const pushed = await authenticatedRequest(`/api/v1/projects/${encodeURIComponent(target.slug)}/bundle`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ ...bundle, publish: true }),
-        }, options.apiUrl);
+        const pushed = await pushDeploymentBundle(target.slug, bundle, 
+        // A deployment bundle is the complete documentation snapshot. Asking
+        // Doxbrix to replace the previous snapshot prevents pages and menu
+        // items removed locally from surviving on the published site.
+        { publish: true, replace: true }, options.apiUrl);
         const report = pushed.result;
-        publishing.done('Published', `${count(bundle.pages.length, 'page')} (${report.pagesCreated} created, ${report.pagesUpdated} updated), ${count(report.spaces, 'space')}${bundle.media.length > 0 ? `, ${count(bundle.media.length, 'media file')}` : ''} · ${formatDuration(publishing.durationMs)}`);
+        publishing.done('Published', `${count(bundle.pages.length, 'page')} (${report.pagesCreated} created, ${report.pagesUpdated} updated${report.pagesDeleted ? `, ${report.pagesDeleted} removed` : ''}), ${count(report.spaces, 'space')}${bundle.media.length > 0 ? `, ${count(bundle.media.length, 'media file')}` : ''} · ${formatDuration(publishing.durationMs)}`);
         for (const warning of report.warnings ?? []) {
             process.stdout.write(`warning: ${warning}\n`);
         }
-        process.stdout.write(`\n${apiUrl(options.apiUrl)}/editor?project=${encodeURIComponent(target.slug)}\n`);
+        // Doxbrix serves every project's rendered documentation on its own host and
+        // reports it as `hostedUrl`. Link readers there, not at the editor; the
+        // editor link is only a fallback for a Doxbrix that does not report one.
+        const siteUrl = target.hostedUrl
+            || `${apiUrl(options.apiUrl)}/editor?project=${encodeURIComponent(target.slug)}`;
+        process.stdout.write(`\n${siteUrl}\n`);
+        await recordDeployment(options.root, {
+            target: 'doxbrix',
+            status: 'succeeded',
+            startedAt,
+            name: target.name,
+            slug: target.slug,
+            visibility,
+            url: siteUrl,
+            pagesCount: bundle.pages.length,
+            mediaCount: bundle.media.length,
+            bytes,
+            pagesCreated: report.pagesCreated,
+            pagesUpdated: report.pagesUpdated,
+            ...(report.pagesDeleted === undefined ? {} : { pagesDeleted: report.pagesDeleted }),
+        });
     }
     catch (error) {
         steps.failActive();
+        await recordDeployment(options.root, {
+            target: 'doxbrix',
+            status: 'failed',
+            startedAt,
+            name,
+            slug,
+            visibility,
+            error: error instanceof Error ? error.message : String(error),
+        });
         throw error;
     }
 }
 export async function buildDeploymentBundle(root, contentDir) {
     const project = await loadProject(root);
+    const qualityConfig = await loadQualityConfig(root);
     if (contentDir !== project.contentDir) {
         throw new DoxloopError('Deployment content directory must match .doxloop/project.json.');
     }
-    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Deployment content directory');
+    const contentRoot = await resolveContainedDirectory(root, project.contentDir, 'Deployment content directory', { allowRoot: project.generator === 'doxbrix' });
     const pages = [];
     for (const path of await loadPages(root, project)) {
         pages.push({
@@ -106,14 +175,19 @@ export async function buildDeploymentBundle(root, contentDir) {
         });
     }
     const media = [];
-    for (const path of await listFiles(contentRoot, MEDIA_EXTENSIONS)) {
+    for (const path of await listFiles(contentRoot, MEDIA_EXTENSIONS, {
+        ...(contentRoot === resolve(root)
+            ? { ignoredDirectories: ROOT_CONTENT_IGNORED_DIRECTORIES }
+            : {}),
+    })) {
         media.push({
             path: relativePath(contentRoot, path),
             base64: (await readFile(path)).toString('base64'),
         });
     }
     const manifest = await loadSiteConfig(root, project);
-    return { manifest, basePath: contentDir, pages, media };
+    const verification = qualityConfig.readerVerification?.enabled ? await readVerificationMetadata(root) : undefined;
+    return { manifest, basePath: contentDir, pages, media, ...(verification ? { verification } : {}) };
 }
 function slugify(value) {
     const slug = value

package/dist/deterministic-capture.d.ts

@@ -0,0 +1,90 @@
+import type { DocumentationPlan, DocumentationPlanPage, DoxloopProject } from './types.js';
+/**
+ * Deterministic screenshot capture for navigation-only manifest steps.
+ *
+ * The LLM agent spends most of a run's wall time driving a browser through
+ * MCP: several tool calls and a model turn per image, stale element refs, and
+ * retries. A large share of planned captures need none of that — they are the
+ * entry screen of a guide or a step that simply opens a route. Doxloop takes
+ * those itself with Playwright before the agent starts, records them as
+ * verified manifest rows, and leaves only steps that need interaction to the
+ * agent. A guide the agent later skips therefore still ends with its entry
+ * screen instead of zero captures.
+ */
+export interface DeterministicCaptureInput {
+    workspace: string;
+    /** Uses project.application.{baseUrl, screenshots.viewport}, project.generator, project.contentDir. */
+    project: DoxloopProject;
+    plan: DocumentationPlan;
+    /** Restrict to these plan pages (a batch); default all screenshot-enabled pages. */
+    pages?: DocumentationPlanPage[];
+    /** Playwright storageState file from prepareCaptureAuth (recorded sign-in session), if any. */
+    storageStatePath?: string;
+    /**
+     * Saved sign-in credentials. When a capture lands on the sign-in page,
+     * Doxloop fills the form once for the browser session and retries, so
+     * navigation-only steps behind a login no longer all fall to the agent.
+     */
+    credentials?: {
+        username: string;
+        password: string;
+    };
+    /** The application's sign-in route (project.application.authentication.loginPath), default /login. */
+    loginPath?: string;
+    /** Test seam: replaces the real browser. */
+    capturePage?: (url: string) => Promise<CapturedPage>;
+    /** Test seam: replaces the real sign-in; resolves to whether the browser is now signed in. */
+    signIn?: (loginUrl: string, credentials: {
+        username: string;
+        password: string;
+    }) => Promise<boolean>;
+    log?: (line: string) => void;
+    /** Overall wall-clock cap; default 4 minutes. */
+    timeBudgetMs?: number;
+}
+export interface CapturedPage {
+    png: Buffer;
+    finalUrl: string;
+    status: number | undefined;
+    hasPasswordField: boolean;
+    title?: string;
+}
+export interface DeterministicCaptureResult {
+    captured: Array<{
+        page: string;
+        step: string;
+        file: string;
+    }>;
+    skipped: Array<{
+        page: string;
+        step: string;
+        reason: string;
+    }>;
+}
+/**
+ * Decide whether a manifest action only opens a screen.
+ *
+ * Returns the explicit app-relative path when the action names one, an empty
+ * object when it is a bare "open the app" instruction, and `undefined` when
+ * the step needs interaction (or does not start by navigating).
+ */
+export declare function isNavigationOnlyStep(action: string): {
+    path?: string;
+} | undefined;
+/**
+ * Resolve the route a step should be captured at, or `undefined` when the step
+ * is not navigation-only.
+ *
+ * The first step of a guide is the entry screen by construction, so it needs
+ * no explicit route: `visuals.startPath` stands in when the action carries
+ * none. Every later step qualifies only when its action names a route, since
+ * a bare "open the dialog" describes interaction, not navigation.
+ */
+export declare function resolveStepPath(page: DocumentationPlanPage, step: {
+    id: string;
+    action: string;
+    sequenceItem?: number;
+}, index: number): string | undefined;
+/** Capture every navigation-only planned step with a real browser (or the injected seam). */
+export declare function captureNavigableSteps(input: DeterministicCaptureInput): Promise<DeterministicCaptureResult>;
+//# sourceMappingURL=deterministic-capture.d.ts.map