@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/remote-source.js

@@ -0,0 +1,426 @@
+import { createHash } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { mkdir, mkdtemp, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, isAbsolute, join, posix, relative, resolve } from 'node:path';
+import { promisify } from 'node:util';
+import { unzipSync } from 'fflate';
+import { DoxloopError } from './errors.js';
+import { pathExists } from './fs.js';
+const MAX_ARCHIVE_BYTES = 100 * 1024 * 1024;
+const MAX_EXTRACTED_BYTES = 500 * 1024 * 1024;
+const execFileAsync = promisify(execFile);
+const gitCredentials = new Map();
+const GIT_CREDENTIALS_ENV = 'DOXLOOP_SESSION_GIT_CREDENTIALS';
+/** Validate a provider-neutral Git clone URL without embedding credentials. */
+export function parseGitRepository(value) {
+    const input = value.trim();
+    if (!input || /[\r\n\0]/.test(input))
+        throw new DoxloopError('Enter a Git repository URL.');
+    if (/^[^@\s]+@[^:\s]+:.+$/.test(input))
+        return input;
+    try {
+        const url = new URL(input);
+        if (!['https:', 'http:', 'ssh:', 'git:', 'file:'].includes(url.protocol) || url.password)
+            throw new Error('unsupported');
+        return input;
+    }
+    catch {
+        throw new DoxloopError('Enter a Git clone URL from GitHub, GitLab, Azure DevOps, or another Git service.');
+    }
+}
+/** Keep private-repository credentials in memory for this Doxloop UI session. */
+export function rememberRemoteCredential(repository, username, secret) {
+    const key = credentialKey(repository);
+    if (!secret) {
+        gitCredentials.delete(key);
+        return;
+    }
+    gitCredentials.set(key, { ...(username?.trim() ? { username: username.trim() } : {}), secret });
+}
+/**
+ * Forward UI-session credentials to Doxloop child processes without writing
+ * them to the project configuration or placing them on a command line.
+ */
+export function remoteCredentialEnvironment() {
+    if (gitCredentials.size === 0)
+        return {};
+    return { [GIT_CREDENTIALS_ENV]: JSON.stringify(Object.fromEntries(gitCredentials)) };
+}
+/** Accept GitHub web/clone URLs or owner/name and return the canonical slug. */
+export function parseGitHubRepository(value) {
+    const input = value.trim();
+    const slug = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(input)
+        ? input
+        : githubSlugFromUrl(input);
+    if (!slug || !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(slug)) {
+        throw new DoxloopError('Enter a GitHub repository URL, for example https://github.com/acme/product.');
+    }
+    return slug.replace(/\.git$/i, '');
+}
+function githubSlugFromUrl(value) {
+    const ssh = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/.exec(value);
+    if (ssh)
+        return `${ssh[1]}/${ssh[2]}`;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.hostname.toLowerCase() !== 'github.com' || url.username || url.password)
+            return;
+        const parts = url.pathname.replace(/^\/+|\/+$/g, '').split('/');
+        if (parts.length !== 2)
+            return;
+        return `${parts[0]}/${parts[1].replace(/\.git$/i, '')}`;
+    }
+    catch {
+        return;
+    }
+}
+export async function listRemoteBranches(remote) {
+    if (remote.provider === 'git')
+        return listGitBranches(remote);
+    const response = await githubRequest(remote, `/repos/${repositoryPath(remote)}/branches?per_page=100`);
+    const branches = (await response.json());
+    return branches.flatMap((branch) => {
+        const name = branch.name;
+        const head = branch.commit?.sha;
+        return name && head && /^[0-9a-f]{40}$/i.test(head) ? [{ name, head }] : [];
+    });
+}
+export async function remoteHead(remote) {
+    if (remote.provider === 'git')
+        return gitRemoteHead(remote);
+    const response = await githubRequest(remote, `/repos/${repositoryPath(remote)}/branches/${encodeURIComponent(remote.branch)}`);
+    const branch = (await response.json());
+    const sha = branch.commit?.sha;
+    if (!sha || !/^[0-9a-f]{40}$/i.test(sha)) {
+        throw new DoxloopError(`GitHub returned an invalid head for ${remote.repository}@${remote.branch}.`);
+    }
+    return sha;
+}
+/** List repository folders without checking out file contents. */
+export async function listRemoteDirectories(remote) {
+    if (remote.provider === 'github')
+        return listGitHubDirectories(remote);
+    const temporary = await mkdtemp(join(tmpdir(), 'doxloop-git-tree-'));
+    try {
+        await rm(temporary, { recursive: true, force: true });
+        await runGit(remote, [
+            'clone', '--depth', '1', '--single-branch', '--branch', remote.branch,
+            '--filter=blob:none', '--no-checkout', '--no-tags', '--quiet', remote.repository, temporary,
+        ]);
+        const output = await runGit(remote, ['-C', temporary, 'ls-tree', '-d', '-r', '--name-only', 'HEAD']);
+        return output.split(/\r?\n/).map((directory) => directory.trim()).filter(Boolean).slice(0, 5000);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+export async function remoteChangedFiles(remote, baseline, head) {
+    if (remote.provider === 'git')
+        return gitChangedFiles(remote, baseline, head);
+    const response = await githubRequest(remote, `/repos/${repositoryPath(remote)}/compare/${encodeURIComponent(baseline)}...${encodeURIComponent(head)}?per_page=100`);
+    const comparison = (await response.json());
+    return (comparison.files ?? []).flatMap((file) => {
+        if (!file.filename)
+            return [];
+        const status = file.status === 'added' ? 'A' : file.status === 'removed' ? 'D' : file.status === 'renamed' ? 'R100' : 'M';
+        if (status === 'R100' && file.previous_filename)
+            return [`${status}\t${file.previous_filename}\t${file.filename}`];
+        return [`${status}\t${file.filename}`];
+    });
+}
+/** Download a provider snapshot outside the documentation deployment boundary. */
+export async function materializeRemoteSource(root, source, requestedHead) {
+    const remote = source.remote;
+    if (remote.provider === 'git')
+        return materializeGitSource(root, source, requestedHead);
+    const head = requestedHead ?? await remoteHead(remote);
+    const projectId = createHash('sha256').update(resolve(root)).digest('hex').slice(0, 12);
+    const destination = join(dirname(resolve(root)), '.doxloop-sources', projectId, safeName(source.name), head);
+    let files = 0;
+    if (!(await pathExists(destination))) {
+        const parent = dirname(destination);
+        await mkdir(parent, { recursive: true });
+        const temporary = await mkdtemp(join(parent, '.download-'));
+        try {
+            const response = await githubRequest(remote, `/repos/${repositoryPath(remote)}/zipball/${encodeURIComponent(head)}`, 'application/vnd.github+json');
+            const archive = new Uint8Array(await response.arrayBuffer());
+            if (archive.byteLength > MAX_ARCHIVE_BYTES) {
+                throw new DoxloopError(`The source archive exceeds the ${MAX_ARCHIVE_BYTES / 1024 / 1024} MB safety limit.`);
+            }
+            const entries = unzipSync(archive);
+            let extracted = 0;
+            for (const [rawName, content] of Object.entries(entries)) {
+                const normalized = posix.normalize(rawName.replace(/\\/g, '/'));
+                const parts = normalized.split('/').filter(Boolean);
+                if (parts.length < 2 || normalized.startsWith('/') || parts.includes('..'))
+                    continue;
+                const archiveRelative = parts.slice(1).join('/');
+                if (!archiveRelative)
+                    continue;
+                const output = resolve(temporary, archiveRelative);
+                if (!output.startsWith(`${resolve(temporary)}/`))
+                    throw new DoxloopError('GitHub returned an unsafe archive path.');
+                if (normalized.endsWith('/')) {
+                    await mkdir(output, { recursive: true });
+                    continue;
+                }
+                extracted += content.byteLength;
+                if (extracted > MAX_EXTRACTED_BYTES) {
+                    throw new DoxloopError(`The expanded source exceeds the ${MAX_EXTRACTED_BYTES / 1024 / 1024} MB safety limit.`);
+                }
+                await mkdir(dirname(output), { recursive: true });
+                await writeFile(output, content);
+                files += 1;
+            }
+            await rename(temporary, destination);
+        }
+        catch (error) {
+            await rm(temporary, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    const scoped = remote.subdirectory
+        ? resolveRemoteSubdirectory(destination, remote.subdirectory)
+        : destination;
+    try {
+        if (!(await stat(scoped)).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        throw new DoxloopError(`The repository subdirectory does not exist on ${remote.branch}: ${remote.subdirectory}`);
+    }
+    return { path: scoped, head, files };
+}
+export function changedFilesInRemoteScope(files, subdirectory) {
+    if (!subdirectory)
+        return files;
+    const prefix = `${normalizeSubdirectory(subdirectory)}/`;
+    return files.flatMap((entry) => {
+        const columns = entry.split('\t');
+        const paths = columns.slice(1);
+        if (!paths.some((path) => path === prefix.slice(0, -1) || path.startsWith(prefix)))
+            return [];
+        return [columns.map((column, index) => index === 0 ? column : column.startsWith(prefix) ? column.slice(prefix.length) : column).join('\t')];
+    });
+}
+export function portableSourcePath(root, sourcePath) {
+    return relative(resolve(root), resolve(sourcePath)).split('\\').join('/');
+}
+function resolveRemoteSubdirectory(root, value) {
+    const normalized = normalizeSubdirectory(value);
+    const destination = resolve(root, normalized);
+    if (isAbsolute(normalized) || destination === resolve(root) || !destination.startsWith(`${resolve(root)}/`)) {
+        throw new DoxloopError('Repository subdirectory must be a safe relative directory.');
+    }
+    return destination;
+}
+function normalizeSubdirectory(value) {
+    return posix.normalize(value.trim().replace(/\\/g, '/')).replace(/^\.\//, '').replace(/\/$/, '');
+}
+async function listGitHubDirectories(remote) {
+    const head = await remoteHead(remote);
+    const response = await githubRequest(remote, `/repos/${repositoryPath(remote)}/git/trees/${encodeURIComponent(head)}?recursive=1`);
+    const tree = (await response.json());
+    return (tree.tree ?? []).flatMap((entry) => entry.type === 'tree' && entry.path ? [entry.path] : []).slice(0, 5000);
+}
+async function listGitBranches(remote) {
+    const output = await runGit(remote, ['ls-remote', '--heads', remote.repository]);
+    const branches = output.split(/\r?\n/).flatMap((line) => {
+        const match = /^([0-9a-f]{40,64})\s+refs\/heads\/(.+)$/i.exec(line.trim());
+        return match ? [{ name: match[2], head: match[1] }] : [];
+    });
+    const defaultBranch = await gitDefaultBranch(remote);
+    return branches.sort((a, b) => a.name === defaultBranch ? -1 : b.name === defaultBranch ? 1 : a.name.localeCompare(b.name));
+}
+async function gitDefaultBranch(remote) {
+    try {
+        const output = await runGit(remote, ['ls-remote', '--symref', remote.repository, 'HEAD']);
+        return /^ref:\s+refs\/heads\/(.+)\s+HEAD$/m.exec(output)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+async function gitRemoteHead(remote) {
+    const output = await runGit(remote, ['ls-remote', remote.repository, `refs/heads/${remote.branch}`]);
+    const match = /^([0-9a-f]{40,64})\s+refs\/heads\/.+$/im.exec(output);
+    if (!match)
+        throw new DoxloopError(`Branch "${remote.branch}" was not found in the repository.`);
+    return match[1];
+}
+async function gitChangedFiles(remote, baseline, head) {
+    const temporary = await mkdtemp(join(tmpdir(), 'doxloop-git-diff-'));
+    try {
+        await runGit(remote, ['clone', '--bare', '--filter=blob:none', '--quiet', remote.repository, temporary]);
+        const output = await runGit(remote, ['-C', temporary, 'diff', '--name-status', baseline, head]);
+        return output.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+    }
+    finally {
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+async function materializeGitSource(root, source, requestedHead) {
+    const remote = source.remote;
+    const head = requestedHead ?? await gitRemoteHead(remote);
+    const projectId = createHash('sha256').update(resolve(root)).digest('hex').slice(0, 12);
+    const destination = join(dirname(resolve(root)), '.doxloop-sources', projectId, safeName(source.name), head);
+    let files = 0;
+    if (!(await pathExists(destination))) {
+        const parent = dirname(destination);
+        await mkdir(parent, { recursive: true });
+        const temporary = await mkdtemp(join(parent, '.clone-'));
+        try {
+            await rm(temporary, { recursive: true, force: true });
+            await runGit(remote, [
+                'clone', '--depth', '1', '--single-branch', '--branch', remote.branch,
+                '--no-tags', '--quiet', remote.repository, temporary,
+            ]);
+            const actualHead = (await runGit(remote, ['-C', temporary, 'rev-parse', 'HEAD'])).trim();
+            if (actualHead !== head)
+                throw new DoxloopError('The repository changed while Doxloop was preparing it. Connect again to use the latest version.');
+            await rm(join(temporary, '.git'), { recursive: true, force: true });
+            const measured = await measureDirectory(temporary);
+            if (measured.bytes > MAX_EXTRACTED_BYTES) {
+                throw new DoxloopError(`The source exceeds the ${MAX_EXTRACTED_BYTES / 1024 / 1024} MB safety limit.`);
+            }
+            files = measured.files;
+            await rename(temporary, destination);
+        }
+        catch (error) {
+            await rm(temporary, { recursive: true, force: true });
+            throw error;
+        }
+    }
+    const scoped = remote.subdirectory ? resolveRemoteSubdirectory(destination, remote.subdirectory) : destination;
+    try {
+        if (!(await stat(scoped)).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        throw new DoxloopError(`The repository subdirectory does not exist on ${remote.branch}: ${remote.subdirectory}`);
+    }
+    return { path: scoped, head, files };
+}
+async function measureDirectory(root) {
+    let files = 0;
+    let bytes = 0;
+    for (const entry of await readdir(root, { withFileTypes: true })) {
+        const path = join(root, entry.name);
+        if (entry.isDirectory()) {
+            const child = await measureDirectory(path);
+            files += child.files;
+            bytes += child.bytes;
+        }
+        else if (entry.isFile()) {
+            files += 1;
+            bytes += (await stat(path)).size;
+        }
+    }
+    return { files, bytes };
+}
+async function runGit(remote, args) {
+    const credential = remoteCredential(remote.repository);
+    const askpassDirectory = credential ? await mkdtemp(join(tmpdir(), 'doxloop-askpass-')) : undefined;
+    try {
+        let askpass;
+        if (askpassDirectory) {
+            askpass = join(askpassDirectory, 'askpass.sh');
+            await writeFile(askpass, '#!/bin/sh\ncase "$1" in *sername*) printf "%s" "$DOXLOOP_GIT_USERNAME" ;; *) printf "%s" "$DOXLOOP_GIT_SECRET" ;; esac\n', { mode: 0o700 });
+        }
+        // An explicitly supplied UI credential must win over stale entries in the
+        // user's Git credential manager. Automatic mode still uses that manager.
+        const commandArgs = credential ? ['-c', 'credential.helper=', ...args] : args;
+        const result = await execFileAsync('git', commandArgs, {
+            maxBuffer: 20 * 1024 * 1024,
+            env: {
+                ...process.env,
+                GIT_TERMINAL_PROMPT: '0',
+                ...(askpass && credential ? {
+                    GIT_ASKPASS: askpass,
+                    DOXLOOP_GIT_USERNAME: credential.username ?? 'oauth2',
+                    DOXLOOP_GIT_SECRET: credential.secret,
+                } : {}),
+            },
+        });
+        return result.stdout;
+    }
+    catch (error) {
+        const detail = error && typeof error === 'object' && 'stderr' in error ? String(error.stderr).trim() : '';
+        throw new DoxloopError(gitErrorMessage(detail, remote.repository));
+    }
+    finally {
+        if (askpassDirectory)
+            await rm(askpassDirectory, { recursive: true, force: true });
+    }
+}
+function remoteCredential(repository) {
+    const key = credentialKey(repository);
+    const remembered = gitCredentials.get(key);
+    if (remembered)
+        return remembered;
+    const serialized = process.env[GIT_CREDENTIALS_ENV];
+    if (!serialized)
+        return undefined;
+    try {
+        const value = JSON.parse(serialized);
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            return undefined;
+        const candidate = value[key];
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate))
+            return undefined;
+        const secret = candidate.secret;
+        const username = candidate.username;
+        if (typeof secret !== 'string' || !secret || (username !== undefined && typeof username !== 'string'))
+            return undefined;
+        return { ...(typeof username === 'string' && username ? { username } : {}), secret };
+    }
+    catch {
+        return undefined;
+    }
+}
+function gitErrorMessage(detail, repository) {
+    if (/write access to repository not granted|requested url returned error:\s*403|forbidden/i.test(detail)) {
+        const github = /github\.com/i.test(repository);
+        return github
+            ? 'GitHub denied access to this repository. Make sure the access key includes this repository and has Contents set to Read-only (or use a classic token with the repo scope). If the repository belongs to an organization, the key may also need SSO approval.'
+            : 'The Git service denied access to this repository. Make sure this account can read the repository and the access key has repository read permission.';
+    }
+    if (/authentication failed|could not read Username|terminal prompts disabled|access denied|repository not found/i.test(detail)) {
+        return 'Doxloop could not sign in to this repository. Check your repository address and access details.';
+    }
+    if (/not found|does not appear to be a git repository/i.test(detail))
+        return 'Doxloop could not find a Git repository at this address.';
+    return detail ? `Git connection failed: ${detail.split(/\r?\n/).slice(-2).join(' ')}` : 'Git connection failed. Check the repository address and try again.';
+}
+function credentialKey(repository) {
+    return repository.trim().replace(/\/$/, '');
+}
+async function githubRequest(remote, path, accept = 'application/vnd.github+json') {
+    const base = (remote.apiBaseUrl ?? 'https://api.github.com').replace(/\/$/, '');
+    const tokenName = remote.tokenEnv ?? 'GITHUB_TOKEN';
+    const token = process.env[tokenName];
+    const response = await fetch(`${base}${path}`, {
+        redirect: 'follow',
+        headers: {
+            Accept: accept,
+            'User-Agent': 'doxloop-remote-source',
+            'X-GitHub-Api-Version': '2022-11-28',
+            ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        },
+    });
+    if (!response.ok) {
+        const hint = response.status === 401 || response.status === 403
+            ? ` Set ${tokenName} for a private repository or higher API limits.`
+            : '';
+        throw new DoxloopError(`GitHub API request failed for ${remote.repository} (${response.status} ${response.statusText}).${hint}`);
+    }
+    return response;
+}
+function repositoryPath(remote) {
+    return remote.repository.split('/').map(encodeURIComponent).join('/');
+}
+function safeName(value) {
+    return value.replace(/[^a-zA-Z0-9_-]/g, '-');
+}
+//# sourceMappingURL=remote-source.js.map

package/dist/review-diff.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Diff primitives for the local review center.
+ *
+ * Two kinds of diff are produced here. `unifiedRows` turns the stored proposal
+ * hunks back into a reviewable unified diff with surrounding context and
+ * word-level emphasis, and `alignBlocks`/`markHtmlWordDiff` line up the two
+ * rendered versions of a page so a reader can compare them side by side without
+ * reading Markdown at all.
+ */
+import type { SyncChangeHunk } from './types.js';
+export type SpanType = 'equal' | 'delete' | 'insert';
+export interface DiffSpan {
+    type: SpanType;
+    beforeStart: number;
+    beforeEnd: number;
+    afterStart: number;
+    afterEnd: number;
+}
+/** Longest-common-subsequence diff over pre-computed comparison keys. */
+export declare function diffKeys(before: readonly string[], after: readonly string[]): DiffSpan[];
+export type DiffRowType = 'context' | 'delete' | 'insert' | 'gap';
+export interface DiffRow {
+    type: DiffRowType;
+    /** 1-based line number in the current file, when the row exists there. */
+    oldNumber?: number;
+    /** 1-based line number in the proposed file, when the row exists there. */
+    newNumber?: number;
+    /** Escaped HTML — may contain `<mark>` spans for word-level emphasis. */
+    html: string;
+    /** Set on `gap` rows: how many unchanged lines were folded away. */
+    hidden?: number;
+    hunkId?: string;
+    hunkState?: 'pending' | 'accepted' | 'rejected';
+}
+export interface UnifiedDiff {
+    rows: DiffRow[];
+    added: number;
+    removed: number;
+}
+export interface UnifiedOptions {
+    context?: number;
+}
+/**
+ * Rebuild a reviewable unified diff from the proposal's stored hunks. The hunks
+ * only carry the changed lines, so the surrounding context comes from the
+ * snapshot of the file taken when the proposal was generated.
+ */
+export declare function unifiedRows(beforeText: string, hunks: readonly SyncChangeHunk[], options?: UnifiedOptions): UnifiedDiff;
+export interface WordDiff {
+    before: string;
+    after: string;
+}
+/** Word-level diff of two plain-text lines, returned as escaped HTML. */
+export declare function wordDiffText(before: string, after: string): WordDiff;
+/**
+ * Split rendered documentation HTML into its top-level blocks (one paragraph,
+ * heading, code block, callout, table … per entry) so two renderings can be
+ * lined up against each other.
+ */
+export declare function splitHtmlBlocks(html: string): string[];
+/** Visible text of an HTML fragment, used as the block comparison key. */
+export declare function htmlText(html: string): string;
+export type RenderedRowStatus = 'equal' | 'changed' | 'added' | 'removed';
+export interface RenderedRow {
+    status: RenderedRowStatus;
+    before?: string;
+    after?: string;
+}
+/**
+ * Align the blocks of two rendered pages. Adjacent removals and additions are
+ * paired into a single "changed" row so the reader sees one before/after
+ * comparison instead of two disconnected entries.
+ */
+export declare function alignBlocks(before: readonly string[], after: readonly string[]): RenderedRow[];
+/**
+ * Highlight the words that differ between two rendered blocks while leaving the
+ * surrounding markup — links, code spans, table cells — intact.
+ */
+export declare function markHtmlWordDiff(before: string, after: string): WordDiff;
+export declare function textLines(text: string): string[];
+export declare function escapeHtml(value: string): string;
+//# sourceMappingURL=review-diff.d.ts.map