@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/demo.js

@@ -0,0 +1,122 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DoxloopError } from './errors.js';
+import { approveDocumentationPlan, applyDocumentationPlanProposal, createDocumentationPlan } from './documentation-plan.js';
+import { writeEvidenceMap } from './evidence.js';
+import { scaffoldProject } from './project.js';
+import { persistReviewReport } from './review-report.js';
+import { recordSyncState } from './sync.js';
+import { validateProject } from './validation.js';
+/** Build a deterministic showcase in an isolated temporary directory. */
+export async function createDemoWorkspace() {
+    const parent = await mkdtemp(join(tmpdir(), 'doxloop-demo-'));
+    const product = join(parent, 'product');
+    const root = join(parent, 'pulse-api-docs');
+    await mkdir(product, { recursive: true });
+    const specification = join(product, 'openapi.json');
+    await writeFile(specification, `${JSON.stringify(DEMO_OPENAPI, null, 2)}\n`, 'utf8');
+    await scaffoldProject({
+        directory: root,
+        title: 'Pulse API',
+        sources: [{ name: 'pulse-api', path: '../product/openapi.json', kind: 'openapi', scope: { routePrefix: 'reference', navigationGroup: 'API reference' } }],
+    });
+    for (const [path, content] of Object.entries(DEMO_PAGES)) {
+        await mkdir(join(root, path, '..'), { recursive: true });
+        await writeFile(join(root, path), content, 'utf8');
+    }
+    await writeFile(join(root, 'docs.json'), `${JSON.stringify(DEMO_NAVIGATION, null, 2)}\n`, 'utf8');
+    const created = await createDocumentationPlan(root, {
+        mode: 'create',
+        scope: 'standard',
+        request: 'Create complete onboarding and API reference documentation for Pulse API.',
+        execution: { agent: 'codex', model: 'demo-bundled', reasoning: 'low', screenshots: false },
+    });
+    const pageDefinitions = Object.keys(DEMO_PAGES).map((path, index) => {
+        const id = path.replace(/\.mdx$/, '').replaceAll('/', '-');
+        const title = DEMO_TITLES[path];
+        return {
+            id,
+            title,
+            path: path.replace(/\.mdx$/, ''),
+            type: index < 2 ? 'getting-started' : path.startsWith('reference/') ? 'reference' : path.includes('troubleshooting') ? 'troubleshooting' : 'how-to',
+            priority: 'must-have',
+            action: index < 2 ? 'update' : 'create',
+            purpose: `Help developers ${DEMO_PURPOSES[path]}.`,
+            rationale: 'The bundled OpenAPI contract directly supports this reader task.',
+            evidence: [`pulse-api: ${DEMO_EVIDENCE[path]}`],
+            evidenceDetails: [{ source: 'pulse-api', path: 'openapi.json', kind: 'openapi', label: DEMO_EVIDENCE[path] }],
+        };
+    });
+    const ready = await applyDocumentationPlanProposal(root, created.id, {
+        productProfile: 'Event ingestion and webhook delivery API',
+        summary: 'Take a developer from authentication through event ingestion, webhook handling, and error recovery.',
+        audiences: ['Application developers', 'Platform engineers'],
+        outcomes: ['Send a first event', 'Verify webhooks', 'Recover from API errors'],
+        terminology: { project: 'Pulse API workspace' },
+        exclusions: ['Dashboard administration and internal operations'],
+        instructions: 'Use runnable curl examples and explain observable success states.',
+        experienceLevel: 'beginner',
+        preferredExamples: ['curl', 'TypeScript'],
+        estimatedEffort: 'medium',
+        estimatedPages: pageDefinitions.length,
+        capabilities: pageDefinitions.map((page) => ({ id: `capability-${page.id}`, title: page.title, kind: page.type, evidence: page.evidenceDetails, pageIds: [page.id], disposition: 'planned' })),
+        navigation: { top: ['Documentation'], sections: [{ id: 'getting-started', title: 'Get started', pageIds: pageDefinitions.slice(0, 2).map((page) => page.id) }, { id: 'guides', title: 'Guides', pageIds: pageDefinitions.slice(2, 5).map((page) => page.id) }, { id: 'reference', title: 'Reference', pageIds: pageDefinitions.slice(5).map((page) => page.id) }] },
+        pages: pageDefinitions,
+        questions: [],
+    }, 'codex');
+    const approved = await approveDocumentationPlan(root, ready.id);
+    const generated = { ...approved, status: 'generated', updatedAt: new Date().toISOString() };
+    await writeFile(join(root, '.doxloop', 'plans', generated.id, 'plan.json'), `${JSON.stringify(generated, null, 2)}\n`, 'utf8');
+    await writeFile(join(root, '.doxloop', 'documentation-plan.json'), `${JSON.stringify(generated, null, 2)}\n`, 'utf8');
+    await writeEvidenceMap(root, { schemaVersion: 1, pages: Object.fromEntries(Object.keys(DEMO_PAGES).map((path) => [path, { sources: [{ source: 'pulse-api', operations: [DEMO_EVIDENCE[path]] }], confidence: 'verified', verifiedOn: { 'pulse-api': new Date().toISOString() } }])) });
+    await recordSyncState(root, [{ name: 'pulse-api', path: '../product/openapi.json', kind: 'openapi' }]);
+    const review = await persistReviewReport(root, '<doxloop-review>{"score":96,"hardGates":"pass","summary":"The bundled documentation is complete, navigable, evidence-backed, and ready to preview.","findings":[]}</doxloop-review>', { agent: 'codex', model: 'demo-bundled', reasoning: 'low' });
+    const validation = await validateProject(root);
+    if (validation.errors > 0) {
+        await rm(parent, { recursive: true, force: true });
+        throw new DoxloopError(`The bundled demo failed its own validation with ${validation.errors} errors.`);
+    }
+    return { parent, root, plan: generated, review, validation, cleanup: () => rm(parent, { recursive: true, force: true }) };
+}
+const DEMO_OPENAPI = {
+    openapi: '3.1.0',
+    info: { title: 'Pulse API', version: '1.0.0', description: 'Ingest product events and deliver signed webhooks.' },
+    servers: [{ url: 'https://api.pulse.example/v1' }],
+    components: { securitySchemes: { bearerAuth: { type: 'http', scheme: 'bearer' } }, schemas: { Event: { type: 'object', required: ['type', 'data'], properties: { type: { type: 'string' }, data: { type: 'object' } } } } },
+    security: [{ bearerAuth: [] }],
+    paths: {
+        '/events': { post: { operationId: 'createEvent', summary: 'Send an event', responses: { '202': { description: 'Accepted' }, '400': { description: 'Invalid event' }, '401': { description: 'Unauthorized' } } } },
+        '/webhooks': { get: { operationId: 'listWebhooks', summary: 'List webhook endpoints', responses: { '200': { description: 'Webhook endpoints' } } }, post: { operationId: 'createWebhook', summary: 'Create a webhook endpoint', responses: { '201': { description: 'Created' } } } },
+    },
+};
+const DEMO_TITLES = {
+    'index.mdx': 'Pulse API overview', 'quickstart.mdx': 'Quickstart', 'guides/authentication.mdx': 'Authentication', 'guides/send-events.mdx': 'Send events', 'guides/webhooks.mdx': 'Receive webhooks', 'reference/events.mdx': 'Events API', 'troubleshooting.mdx': 'Troubleshooting',
+};
+const DEMO_PURPOSES = {
+    'index.mdx': 'understand the API and choose a workflow', 'quickstart.mdx': 'send a first successful event', 'guides/authentication.mdx': 'authenticate requests safely', 'guides/send-events.mdx': 'construct and submit event payloads', 'guides/webhooks.mdx': 'configure and verify webhook delivery', 'reference/events.mdx': 'look up request and response behavior', 'troubleshooting.mdx': 'diagnose common request failures',
+};
+const DEMO_EVIDENCE = {
+    'index.mdx': 'POST /events', 'quickstart.mdx': 'POST /events', 'guides/authentication.mdx': 'bearerAuth', 'guides/send-events.mdx': 'POST /events', 'guides/webhooks.mdx': 'POST /webhooks', 'reference/events.mdx': 'POST /events', 'troubleshooting.mdx': 'POST /events 400/401',
+};
+function page(title, description, body) {
+    return `---\ntitle: ${JSON.stringify(title)}\ndescription: ${JSON.stringify(description)}\n---\n\n# ${title}\n\n${body.trim()}\n`;
+}
+const DEMO_PAGES = {
+    'index.mdx': page('Pulse API overview', 'Understand what Pulse API does and choose the right integration workflow.', 'Pulse API accepts product events and delivers them to signed webhook endpoints.\n\n- Start with the [quickstart](/quickstart).\n- Learn how [authentication](/guides/authentication) works.\n- Use the [Events API reference](/reference/events) while integrating.'),
+    'quickstart.mdx': page('Quickstart', 'Authenticate and send your first accepted event in a few minutes.', '## Send an event\n\n```bash\ncurl -X POST https://api.pulse.example/v1/events \\\n  -H "Authorization: Bearer $PULSE_API_TOKEN" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"type":"user.created","data":{"id":"usr_123"}}\'\n```\n\nA successful request returns HTTP `202 Accepted`. Continue with [webhooks](/guides/webhooks).'),
+    'guides/authentication.mdx': page('Authentication', 'Send API credentials safely with every Pulse API request.', 'Pulse API uses bearer authentication. Store the token in a secret manager and send it in the `Authorization` header.\n\n```http\nAuthorization: Bearer YOUR_TOKEN\n```\n\nNever place a token in a URL, source file, or client-side application.'),
+    'guides/send-events.mdx': page('Send events', 'Create valid event payloads and recognize an accepted request.', 'Send JSON to `POST /events` with a string `type` and an object `data`. The API returns `202` after accepting the event for processing.\n\nUse stable event names such as `user.created` so consumers can route them predictably.'),
+    'guides/webhooks.mdx': page('Receive webhooks', 'Create an endpoint and prepare an application to receive event deliveries.', 'Create a destination with `POST /webhooks`, then expose an HTTPS handler that returns a successful response promptly. List configured destinations with `GET /webhooks`.\n\nTest the complete path with a non-production event before enabling a live integration.'),
+    'reference/events.mdx': page('Events API', 'Look up the request contract and response behavior for event ingestion.', '## `POST /events`\n\nRequires bearer authentication and a JSON body containing `type` and `data`.\n\n| Status | Meaning |\n| --- | --- |\n| `202` | Event accepted |\n| `400` | Payload is invalid |\n| `401` | Authentication failed |'),
+    'troubleshooting.mdx': page('Troubleshooting', 'Resolve authentication and payload errors when sending Pulse API events.', '## `401 Unauthorized`\n\nConfirm that the token is present, active, and sent as a bearer token.\n\n## `400 Bad Request`\n\nConfirm that the body is JSON and includes both `type` and `data`. Compare the request with the [quickstart](/quickstart).'),
+};
+const DEMO_NAVIGATION = {
+    version: 1, name: 'Pulse API', description: 'Evidence-backed example documentation generated by Doxloop.',
+    spaces: [{ name: 'Documentation', slug: 'docs', icon: 'book', nav: [
+                { type: 'group', label: 'Get started', icon: 'rocket', items: [{ type: 'page', file: 'index', title: 'Overview' }, { type: 'page', file: 'quickstart', title: 'Quickstart' }] },
+                { type: 'group', label: 'Guides', icon: 'book', items: [{ type: 'page', file: 'guides/authentication', title: 'Authentication' }, { type: 'page', file: 'guides/send-events', title: 'Send events' }, { type: 'page', file: 'guides/webhooks', title: 'Receive webhooks' }] },
+                { type: 'group', label: 'Reference', icon: 'api', items: [{ type: 'page', file: 'reference/events', title: 'Events API' }, { type: 'page', file: 'troubleshooting', title: 'Troubleshooting' }] },
+            ] }], theme: { primaryColor: '#0f766e', mode: 'system', font: 'Inter', headingFont: 'Inter', codeFont: 'ui-monospace' },
+};
+//# sourceMappingURL=demo.js.map

package/dist/deploy-credentials.d.ts

@@ -0,0 +1,7 @@
+import type { DeployTargetId } from './deploy-targets/types.js';
+type CredentialTarget = Extract<DeployTargetId, 'netlify' | 'vercel'>;
+export declare function saveDeployCredential(target: CredentialTarget, token: string): Promise<void>;
+export declare function deployCredential(target: CredentialTarget): Promise<string>;
+export declare function deployCredentialState(): Promise<Record<CredentialTarget, boolean>>;
+export {};
+//# sourceMappingURL=deploy-credentials.d.ts.map

package/dist/deploy-credentials.js

@@ -0,0 +1,76 @@
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { DoxloopError } from './errors.js';
+import { pathExists } from './fs.js';
+import { promisify } from 'node:util';
+const execute = promisify(execFile);
+const KEYCHAIN_SERVICE = 'com.doxloop.deploy';
+export async function saveDeployCredential(target, token) {
+    const value = token.trim();
+    if (value.length < 8)
+        throw new DoxloopError(`${targetLabel(target)} token is too short.`);
+    if (process.platform === 'darwin') {
+        try {
+            await execute('security', ['add-generic-password', '-a', target, '-s', KEYCHAIN_SERVICE, '-w', value, '-U']);
+            return;
+        }
+        catch (error) {
+            throw new DoxloopError(`Could not save the ${targetLabel(target)} token in macOS Keychain: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    const path = credentialPath();
+    const current = await readCredentials();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, `${JSON.stringify({ ...current, [target]: value }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    if (process.platform !== 'win32')
+        await chmod(path, 0o600);
+}
+export async function deployCredential(target) {
+    const environment = target === 'netlify'
+        ? process.env.DOXLOOP_NETLIFY_TOKEN ?? process.env.NETLIFY_AUTH_TOKEN
+        : process.env.DOXLOOP_VERCEL_TOKEN ?? process.env.VERCEL_TOKEN;
+    const token = environment ?? await storedCredential(target);
+    if (!token) {
+        throw new DoxloopError(`No ${targetLabel(target)} token is configured. Set ${target === 'netlify' ? 'DOXLOOP_NETLIFY_TOKEN' : 'DOXLOOP_VERCEL_TOKEN'} or save one from the Deploy page.`);
+    }
+    return token;
+}
+export async function deployCredentialState() {
+    const [netlify, vercel] = await Promise.all([storedCredential('netlify'), storedCredential('vercel')]);
+    return {
+        netlify: Boolean(process.env.DOXLOOP_NETLIFY_TOKEN ?? process.env.NETLIFY_AUTH_TOKEN ?? netlify),
+        vercel: Boolean(process.env.DOXLOOP_VERCEL_TOKEN ?? process.env.VERCEL_TOKEN ?? vercel),
+    };
+}
+async function storedCredential(target) {
+    if (process.platform === 'darwin') {
+        try {
+            const result = await execute('security', ['find-generic-password', '-a', target, '-s', KEYCHAIN_SERVICE, '-w']);
+            return result.stdout.trim() || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return (await readCredentials())[target];
+}
+async function readCredentials() {
+    const path = credentialPath();
+    if (!(await pathExists(path)))
+        return {};
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        throw new DoxloopError(`Cannot read deployment credentials at ${path}.`);
+    }
+}
+function credentialPath() {
+    return process.env.DOXLOOP_CONFIG_HOME
+        ? join(process.env.DOXLOOP_CONFIG_HOME, 'deploy-targets.json')
+        : join(homedir(), '.config', 'doxloop', 'deploy-targets.json');
+}
+function targetLabel(target) { return target === 'netlify' ? 'Netlify' : 'Vercel'; }
+//# sourceMappingURL=deploy-credentials.js.map

package/dist/deploy-targets/github-pages.d.ts

@@ -0,0 +1,3 @@
+import type { DeployTarget } from './types.js';
+export declare const githubPagesTarget: DeployTarget;
+//# sourceMappingURL=github-pages.d.ts.map

package/dist/deploy-targets/github-pages.js

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process';
+import { cp, mkdtemp, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { DoxloopError } from '../errors.js';
+const execute = promisify(execFile);
+export const githubPagesTarget = {
+    id: 'github-pages',
+    label: 'GitHub Pages',
+    async configure(options) {
+        const branch = options.branch?.trim() || 'gh-pages';
+        if (!(branch === 'gh-pages' || /^doxloop-pages\/[A-Za-z0-9][A-Za-z0-9._-]*$/.test(branch)) || branch.includes('..')) {
+            throw new DoxloopError('Use gh-pages or doxloop-pages/<site> as a deployment-only branch. Source branches cannot be deployment targets.');
+        }
+        await git(options.root, ['rev-parse', '--is-inside-work-tree']);
+        await git(options.root, ['check-ref-format', '--branch', branch]);
+        const current = (await git(options.root, ['branch', '--show-current'])).trim();
+        if (current === branch)
+            throw new DoxloopError('The deployment branch is checked out. Switch to your documentation source branch before publishing.');
+        const remote = (await git(options.root, ['remote', 'get-url', 'origin'])).trim();
+        const withBase = { ...options, branch, ...(options.basePath ? {} : inferredBasePath(remote)) };
+        const siteUrl = githubPagesUrl(remote, withBase.basePath);
+        return { ...withBase, ...(siteUrl ? { siteUrl } : {}) };
+    },
+    async publish(bundle, rawOptions) {
+        const options = await this.configure(rawOptions);
+        const remote = (await git(options.root, ['remote', 'get-url', 'origin'])).trim();
+        const parent = await mkdtemp(join(tmpdir(), 'doxloop-pages-'));
+        const checkout = join(parent, 'site');
+        try {
+            await git(parent, ['clone', '--no-checkout', options.root, checkout]);
+            await git(checkout, ['remote', 'set-url', 'origin', remote]);
+            const ref = `refs/heads/${options.branch}`;
+            const advertised = (await git(checkout, ['ls-remote', '--heads', 'origin', ref])).trim().split(/\s+/)[0] || '';
+            if (advertised) {
+                await git(checkout, ['fetch', '--no-tags', 'origin', ref]);
+                const fetched = (await git(checkout, ['rev-parse', 'FETCH_HEAD'])).trim();
+                if (fetched !== advertised)
+                    throw new DoxloopError('The deployment branch changed during preparation. Retry publishing.');
+                const marker = await git(checkout, ['show', `${fetched}:.doxloop-deployment.json`]).catch(() => '');
+                if (marker.trim() !== '{"schemaVersion":1,"owner":"doxloop-static-deploy"}')
+                    throw new DoxloopError('The remote branch is not owned by Doxloop static deployments. Choose a new doxloop-pages/<site> branch to preserve its existing content.');
+                await git(checkout, ['checkout', '--detach', fetched]);
+            }
+            else {
+                await git(checkout, ['checkout', '--orphan', `doxloop-publish-${Date.now()}`]);
+            }
+            for (const entry of await readdir(checkout)) {
+                if (entry !== '.git')
+                    await rm(join(checkout, entry), { recursive: true, force: true });
+            }
+            for (const entry of await readdir(bundle.outputDir)) {
+                await cp(join(bundle.outputDir, entry), join(checkout, entry), { recursive: true });
+            }
+            await writeFile(join(checkout, '.nojekyll'), '', 'utf8');
+            await writeFile(join(checkout, '.doxloop-deployment.json'), '{"schemaVersion":1,"owner":"doxloop-static-deploy"}\n', 'utf8');
+            await git(checkout, ['add', '--all']);
+            await git(checkout, ['-c', 'user.name=Doxloop', '-c', 'user.email=doxloop@local', 'commit', '--allow-empty', '-m', 'docs: publish static site']);
+            const commit = (await git(checkout, ['rev-parse', 'HEAD'])).trim();
+            // Existing deployments retain their history. An explicit lease rejects concurrent updates.
+            await git(checkout, ['push', `--force-with-lease=${ref}:${advertised}`, 'origin', `HEAD:${ref}`]);
+            const url = githubPagesUrl(remote, options.basePath);
+            return {
+                id: commit,
+                ...(url ? { url } : {}),
+                detail: `Pushed ${bundle.files} files to ${options.branch}`,
+            };
+        }
+        finally {
+            await rm(parent, { recursive: true, force: true });
+        }
+    },
+};
+async function git(cwd, args) {
+    try {
+        return (await execute('git', args, { cwd, maxBuffer: 4_000_000 })).stdout;
+    }
+    catch (error) {
+        throw new DoxloopError(`GitHub Pages publish failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function repository(remote) {
+    const match = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?$/.exec(remote);
+    return match ? { owner: match[1], name: match[2] } : undefined;
+}
+function inferredBasePath(remote) {
+    const repo = repository(remote);
+    if (!repo || repo.name.toLowerCase() === `${repo.owner.toLowerCase()}.github.io`)
+        return {};
+    return { basePath: `/${repo.name}` };
+}
+function githubPagesUrl(remote, basePath) {
+    const repo = repository(remote);
+    if (!repo)
+        return undefined;
+    const path = basePath?.replace(/^\/+|\/+$/g, '');
+    return `https://${repo.owner.toLowerCase()}.github.io/${path ? `${path}/` : ''}`;
+}
+//# sourceMappingURL=github-pages.js.map

package/dist/deploy-targets/index.d.ts

@@ -0,0 +1,8 @@
+import type { DeployTarget, DeployTargetId, DeployTargetOptions, DeployTargetResult } from './types.js';
+export type { DeployBundle, DeployTarget, DeployTargetId, DeployTargetOptions, DeployTargetResult } from './types.js';
+export declare const STATIC_DEPLOY_TARGETS: readonly DeployTarget[];
+export declare function deployTarget(id: DeployTargetId): DeployTarget;
+export declare function publishStaticTarget(id: Extract<DeployTargetId, 'github-pages' | 'netlify' | 'vercel'>, options: DeployTargetOptions & {
+    dryRun?: boolean;
+}): Promise<DeployTargetResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/deploy-targets/index.js

@@ -0,0 +1,78 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { packageStaticOutput, containedOutput, runLocalBuild, writeDryRunArchive } from '../artifact-deploy.js';
+import { buildDoxbrixStaticSite } from '../doxbrix-build.js';
+import { DoxloopError } from '../errors.js';
+import { loadGeneratorAdapter } from '../generators.js';
+import { recordDeployment } from '../history.js';
+import { loadProject } from '../project.js';
+import { validateProject } from '../validation.js';
+import { githubPagesTarget } from './github-pages.js';
+import { netlifyTarget } from './netlify.js';
+import { vercelTarget } from './vercel.js';
+export const STATIC_DEPLOY_TARGETS = [githubPagesTarget, netlifyTarget, vercelTarget];
+export function deployTarget(id) {
+    const target = STATIC_DEPLOY_TARGETS.find((candidate) => candidate.id === id);
+    if (!target)
+        throw new DoxloopError(`Unsupported static deploy target: ${id}`);
+    return target;
+}
+export async function publishStaticTarget(id, options) {
+    const startedAt = new Date().toISOString();
+    const target = deployTarget(id);
+    let configured;
+    try {
+        const validation = await validateProject(options.root);
+        if (validation.errors > 0)
+            throw new DoxloopError(`Deployment stopped because documentation has ${validation.errors} validation error${validation.errors === 1 ? '' : 's'}. Run \`doxloop test\`.`);
+        configured = await target.configure(options);
+        const project = await loadProject(options.root);
+        const temporary = await mkdtemp(join(tmpdir(), 'doxloop-deploy-'));
+        try {
+            let outputDir;
+            if (project.generator === 'doxbrix') {
+                outputDir = join(temporary, 'site');
+                await buildDoxbrixStaticSite({
+                    root: options.root,
+                    outDir: outputDir,
+                    ...(configured.basePath ? { basePath: configured.basePath } : {}),
+                    ...(configured.siteUrl ? { siteUrl: configured.siteUrl } : {}),
+                });
+            }
+            else {
+                const adapter = await loadGeneratorAdapter(options.root, project);
+                await runLocalBuild(adapter.id, adapter.build.command, options.root, configured.siteUrl ?? 'https://example.com');
+                outputDir = containedOutput(options.root, adapter.build.outputDir);
+            }
+            const packaged = await packageStaticOutput(outputDir);
+            const bundle = { outputDir, archive: packaged.archive, files: packaged.files, bytes: packaged.archive.byteLength, sha256: packaged.sha256 };
+            if (options.dryRun) {
+                const archivePath = await writeDryRunArchive(options.root, bundle.archive);
+                process.stdout.write(`Deployment is valid.\nTarget: ${target.label}\nFiles: ${bundle.files}\nArchive: ${archivePath}\nSHA-256: ${bundle.sha256}\nNo data was uploaded.\n`);
+                return { detail: archivePath };
+            }
+            const result = await target.publish(bundle, configured);
+            await recordDeployment(options.root, {
+                target: id,
+                status: 'succeeded',
+                startedAt,
+                name: options.name,
+                slug: options.slug,
+                ...(result.url ? { url: result.url } : {}),
+                pagesCount: validation.pages.length,
+                bytes: bundle.bytes,
+            });
+            process.stdout.write(`${target.label} deployment succeeded.${result.detail ? ` ${result.detail}.` : ''}${result.url ? `\n${result.url}` : ''}\n`);
+            return result;
+        }
+        finally {
+            await rm(temporary, { recursive: true, force: true });
+        }
+    }
+    catch (error) {
+        await recordDeployment(options.root, { target: id, status: 'failed', startedAt, name: options.name, slug: options.slug, error: error instanceof Error ? error.message : String(error) });
+        throw error;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/deploy-targets/netlify.d.ts

@@ -0,0 +1,3 @@
+import type { DeployTarget } from './types.js';
+export declare const netlifyTarget: DeployTarget;
+//# sourceMappingURL=netlify.d.ts.map

package/dist/deploy-targets/netlify.js

@@ -0,0 +1,49 @@
+import { deployCredential } from '../deploy-credentials.js';
+import { DoxloopError } from '../errors.js';
+export const netlifyTarget = {
+    id: 'netlify',
+    label: 'Netlify',
+    async configure(options) {
+        if (!options.siteId?.trim())
+            throw new DoxloopError('Netlify requires a site ID.');
+        return { ...options, siteId: options.siteId.trim(), apiUrl: apiOrigin(options.apiUrl, 'https://api.netlify.com') };
+    },
+    async publish(bundle, rawOptions) {
+        const options = await this.configure(rawOptions);
+        const token = await deployCredential('netlify');
+        const response = await fetch(`${options.apiUrl}/api/v1/sites/${encodeURIComponent(options.siteId)}/deploys`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/zip' },
+            body: bundle.archive,
+            redirect: 'error',
+        });
+        if (!response.ok)
+            throw await providerError('Netlify', response);
+        const result = await response.json();
+        return { ...(result.id ? { id: result.id } : {}), ...(result.deploy_ssl_url ?? result.ssl_url ?? result.url ? { url: result.deploy_ssl_url ?? result.ssl_url ?? result.url } : {}), detail: result.state ? `Deploy ${result.state}` : 'Deploy uploaded' };
+    },
+};
+function apiOrigin(value, fallback) {
+    const raw = value?.trim() || fallback;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new DoxloopError(`Invalid Netlify API URL: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '::1'].includes(url.hostname)))
+        throw new DoxloopError('Netlify API URL must use HTTPS.');
+    if (url.username || url.password || url.search || url.hash)
+        throw new DoxloopError('Netlify API URL cannot contain credentials, query, or fragment.');
+    return url.toString().replace(/\/+$/, '');
+}
+async function providerError(provider, response) {
+    let detail = `${response.status} ${response.statusText}`.trim();
+    try {
+        detail = (await response.text()).trim().slice(0, 1_000) || detail;
+    }
+    catch { }
+    return new DoxloopError(`${provider} deployment failed: ${detail}`);
+}
+//# sourceMappingURL=netlify.js.map

package/dist/deploy-targets/types.d.ts

@@ -0,0 +1,32 @@
+export type DeployTargetId = 'doxbrix' | 'export' | 'github-pages' | 'netlify' | 'vercel';
+export interface DeployBundle {
+    outputDir: string;
+    archive: Uint8Array;
+    files: number;
+    bytes: number;
+    sha256: string;
+}
+export interface DeployTargetOptions {
+    root: string;
+    name: string;
+    slug: string;
+    apiUrl?: string;
+    siteId?: string;
+    projectId?: string;
+    teamId?: string;
+    branch?: string;
+    basePath?: string;
+    siteUrl?: string;
+}
+export interface DeployTargetResult {
+    url?: string;
+    id?: string;
+    detail?: string;
+}
+export interface DeployTarget {
+    id: DeployTargetId;
+    label: string;
+    configure(options: DeployTargetOptions): Promise<DeployTargetOptions>;
+    publish(bundle: DeployBundle, options: DeployTargetOptions): Promise<DeployTargetResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/deploy-targets/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/deploy-targets/vercel.d.ts

@@ -0,0 +1,3 @@
+import type { DeployTarget } from './types.js';
+export declare const vercelTarget: DeployTarget;
+//# sourceMappingURL=vercel.d.ts.map

package/dist/deploy-targets/vercel.js

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { lstat, readdir, readFile } from 'node:fs/promises';
+import { relative, resolve, sep } from 'node:path';
+import { deployCredential } from '../deploy-credentials.js';
+import { DoxloopError } from '../errors.js';
+export const vercelTarget = {
+    id: 'vercel',
+    label: 'Vercel',
+    async configure(options) {
+        if (!options.projectId?.trim())
+            throw new DoxloopError('Vercel requires a project ID or project name.');
+        return { ...options, projectId: options.projectId.trim(), apiUrl: apiOrigin(options.apiUrl) };
+    },
+    async publish(bundle, rawOptions) {
+        const options = await this.configure(rawOptions);
+        const token = await deployCredential('vercel');
+        const files = await deploymentFiles(bundle.outputDir);
+        const query = options.teamId ? `?teamId=${encodeURIComponent(options.teamId)}` : '';
+        for (const file of files) {
+            const upload = await fetch(`${options.apiUrl}/v2/files${query}`, {
+                method: 'POST',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': 'application/octet-stream',
+                    'Content-Length': String(file.data.byteLength),
+                    'x-vercel-digest': file.sha,
+                },
+                body: file.data,
+                redirect: 'error',
+            });
+            if (!upload.ok)
+                throw await providerError(upload);
+        }
+        const response = await fetch(`${options.apiUrl}/v13/deployments${query}`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                name: options.projectId,
+                project: options.projectId,
+                target: 'production',
+                files: files.map(({ file, sha, size }) => ({ file, sha, size })),
+                projectSettings: { framework: null },
+            }),
+            redirect: 'error',
+        });
+        if (!response.ok)
+            throw await providerError(response);
+        const result = await response.json();
+        const hostname = result.alias?.[0] ?? result.url;
+        return { ...(result.id ? { id: result.id } : {}), ...(hostname ? { url: `https://${hostname.replace(/^https?:\/\//, '')}` } : {}), detail: result.readyState ? `Deploy ${result.readyState.toLowerCase()}` : 'Deploy created' };
+    },
+};
+async function deploymentFiles(root) {
+    const files = [];
+    const visit = async (directory) => {
+        for (const entry of await readdir(directory, { withFileTypes: true })) {
+            const absolute = resolve(directory, entry.name);
+            const stat = await lstat(absolute);
+            if (stat.isSymbolicLink())
+                throw new DoxloopError('Vercel deployment output cannot contain symbolic links.');
+            if (stat.isDirectory())
+                await visit(absolute);
+            else if (stat.isFile()) {
+                const data = new Uint8Array(await readFile(absolute));
+                files.push({ file: relative(root, absolute).split(sep).join('/'), data, sha: createHash('sha1').update(data).digest('hex'), size: data.byteLength });
+            }
+        }
+    };
+    await visit(root);
+    return files;
+}
+function apiOrigin(value) {
+    const raw = value?.trim() || 'https://api.vercel.com';
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new DoxloopError(`Invalid Vercel API URL: ${raw}`);
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['localhost', '127.0.0.1', '::1'].includes(url.hostname)))
+        throw new DoxloopError('Vercel API URL must use HTTPS.');
+    if (url.username || url.password || url.search || url.hash)
+        throw new DoxloopError('Vercel API URL cannot contain credentials, query, or fragment.');
+    return url.toString().replace(/\/+$/, '');
+}
+async function providerError(response) {
+    let detail = `${response.status} ${response.statusText}`.trim();
+    try {
+        detail = (await response.text()).trim().slice(0, 1_000) || detail;
+    }
+    catch { }
+    return new DoxloopError(`Vercel deployment failed: ${detail}`);
+}
+//# sourceMappingURL=vercel.js.map

package/dist/deploy.d.ts

@@ -1,3 +1,5 @@
+import type { ReaderVerificationMetadata } from './types.js';
+import type { DeploymentTargetSetting } from './types.js';
 interface DeploymentBundle {
     manifest: unknown;
     basePath: string;
@@ -9,14 +11,21 @@ interface DeploymentBundle {
         path: string;
         base64: string;
     }>;
+    verification?: ReaderVerificationMetadata;
 }
 export declare function deploy(options: {
     root: string;
+    target?: DeploymentTargetSetting;
     name?: string;
     slug?: string;
     dryRun?: boolean;
     public?: boolean;
     apiUrl?: string;
+    siteId?: string;
+    projectId?: string;
+    teamId?: string;
+    branch?: string;
+    basePath?: string;
 }): Promise<void>;
 export declare function buildDeploymentBundle(root: string, contentDir: string): Promise<DeploymentBundle>;
 export {};