@doxbrix/doxloop 0.1.5 → 0.2.0

package/dist/job-events.js

@@ -0,0 +1,377 @@
+const EVENT_PREFIX = 'DOXLOOP_EVENT ';
+/**
+ * Every line the control center keeps for a job carries the local wall-clock
+ * time it arrived, so a reader can see which step took how long. Stage and
+ * outcome events already carry their own `at` and stay machine-readable.
+ */
+const JOB_LINE_STAMP = /^\d{2}:\d{2}:\d{2} /;
+export function formatJobLineStamp(at = new Date()) {
+    const pad = (value) => String(value).padStart(2, '0');
+    return `${pad(at.getHours())}:${pad(at.getMinutes())}:${pad(at.getSeconds())}`;
+}
+/** Prefix a log line with the time it arrived; event lines and already stamped lines pass through. */
+export function stampJobLine(line, at = new Date()) {
+    if (line.startsWith(EVENT_PREFIX) || JOB_LINE_STAMP.test(line))
+        return line;
+    return `${formatJobLineStamp(at)} ${line}`;
+}
+export function stripJobLineStamp(line) {
+    return line.replace(JOB_LINE_STAMP, '');
+}
+export function jobOutcomeLine(outcome, at = new Date().toISOString()) {
+    return `${EVENT_PREFIX}${JSON.stringify({ schemaVersion: 1, type: 'outcome', ...outcome, at })}`;
+}
+/** Report a job outcome to a control center that started this CLI; a terminal already saw the text. */
+export function emitJobOutcome(outcome) {
+    if (process.stdout.isTTY)
+        return;
+    process.stdout.write(`${jobOutcomeLine(outcome)}\n`);
+}
+export function parseJobOutcomeLine(line) {
+    if (!line.startsWith(EVENT_PREFIX))
+        return undefined;
+    try {
+        const parsed = JSON.parse(line.slice(EVENT_PREFIX.length));
+        const raw = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+        return raw?.schemaVersion === 1 && raw.type === 'outcome' ? parseJobOutcome(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function parseJobOutcome(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const outcome = raw;
+    if (outcome.kind !== 'sync' || typeof outcome.message !== 'string')
+        return undefined;
+    if (!['current', 'stale', 'proposal', 'skipped', 'failed', 'unknown'].includes(String(outcome.status)))
+        return undefined;
+    return {
+        kind: 'sync',
+        status: outcome.status,
+        message: outcome.message,
+        ...(typeof outcome.pages === 'number' && Number.isInteger(outcome.pages) && outcome.pages >= 0 ? { pages: outcome.pages } : {}),
+        ...(typeof outcome.proposalId === 'string' ? { proposalId: outcome.proposalId } : {}),
+    };
+}
+/** Serialize one stage event as the line the UI server reads from a CLI job. */
+export function workflowStageLine(id, label, status, progress, at = new Date().toISOString()) {
+    return `${EVENT_PREFIX}${JSON.stringify({ schemaVersion: 1, type: 'stage', id, label, status, ...(progress ? { progress } : {}), at })}`;
+}
+/**
+ * Report a workflow stage. A CLI run started by the control center streams
+ * machine-readable events; a person watching a terminal gets a plain line.
+ */
+export function emitWorkflowStage(id, label, status, progress) {
+    if (process.stdout.isTTY) {
+        if (status === 'pending')
+            return;
+        const mark = status === 'running' ? '…' : status === 'completed' ? '✓' : '✗';
+        process.stdout.write(`${mark} ${label}${formatStageProgress(progress)}\n`);
+        return;
+    }
+    process.stdout.write(`${workflowStageLine(id, label, status, progress)}\n`);
+}
+export function formatStageProgress(progress) {
+    if (!progress)
+        return '';
+    return progress.total !== undefined ? ` (${progress.done} of ${progress.total})` : ` (${progress.done})`;
+}
+export function applyWorkflowStageLine(stages, line) {
+    if (!line.startsWith(EVENT_PREFIX))
+        return;
+    let raw;
+    try {
+        const parsed = JSON.parse(line.slice(EVENT_PREFIX.length));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            return;
+        raw = parsed;
+    }
+    catch {
+        return;
+    }
+    if (raw.schemaVersion !== 1 || raw.type !== 'stage' || typeof raw.id !== 'string' || typeof raw.label !== 'string' || typeof raw.at !== 'string')
+        return;
+    if (!['pending', 'running', 'completed', 'failed'].includes(String(raw.status)))
+        return;
+    const status = raw.status;
+    const progress = parseStageProgress(raw.progress);
+    const existing = stages.find((stage) => stage.id === raw.id);
+    if (existing) {
+        // A stage announced up front never moves backwards once work started on it.
+        if (status === 'pending')
+            return;
+        existing.label = raw.label;
+        existing.status = status;
+        if (progress)
+            existing.progress = progress;
+        if (status === 'running')
+            existing.startedAt ??= raw.at;
+        else
+            existing.finishedAt = raw.at;
+    }
+    else {
+        stages.push({
+            id: raw.id,
+            label: raw.label,
+            status,
+            ...(progress ? { progress } : {}),
+            ...(status === 'running' ? { startedAt: raw.at } : status === 'pending' ? {} : { finishedAt: raw.at }),
+        });
+    }
+}
+export function finishWorkflowStages(stages, status, at = new Date().toISOString()) {
+    for (const stage of stages) {
+        if (stage.status !== 'running')
+            continue;
+        stage.status = status;
+        stage.finishedAt = at;
+    }
+}
+export function parseWorkflowStage(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const stage = raw;
+    if (typeof stage.id !== 'string' || typeof stage.label !== 'string' || !['pending', 'running', 'completed', 'failed'].includes(String(stage.status)))
+        return undefined;
+    const progress = parseStageProgress(stage.progress);
+    return {
+        id: stage.id,
+        label: stage.label,
+        status: stage.status,
+        ...(typeof stage.startedAt === 'string' ? { startedAt: stage.startedAt } : {}),
+        ...(typeof stage.finishedAt === 'string' ? { finishedAt: stage.finishedAt } : {}),
+        ...(progress ? { progress } : {}),
+    };
+}
+function parseStageProgress(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return undefined;
+    const progress = raw;
+    if (typeof progress.done !== 'number' || !Number.isInteger(progress.done) || progress.done < 0)
+        return undefined;
+    const total = progress.total;
+    if (total !== undefined && (typeof total !== 'number' || !Number.isInteger(total) || total < 0))
+        return undefined;
+    return { done: progress.done, ...(typeof total === 'number' ? { total } : {}) };
+}
+// ---------------------------------------------------------------------------
+// Job log hygiene: what the control center shows in "Live activity".
+const ANSI_ESCAPE = /\u001b\[[0-9;?]*[ -/]*[@-~]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)|\u001b[@-Z\\-_]/g;
+/** An optional `[task] ` prefix a parallel research session puts on its lines. */
+const SESSION_PREFIX = /^(\[[^\]\s]{1,40}\] )?/;
+/** A Rust `tracing` line from Codex's own internals: timestamp, level, module, message. */
+const CODEX_TRACE = /^\d{4}-\d{2}-\d{2}T[\d:.]+Z?\s+(ERROR|WARN|INFO|DEBUG|TRACE)\s+(codex[\w:]*)\s*:\s*(.*)$/;
+export function stripAnsi(value) {
+    return value.replace(ANSI_ESCAPE, '');
+}
+function compactLine(value, maximum) {
+    const single = value.replace(/\s+/g, ' ').trim();
+    return single.length > maximum ? `${single.slice(0, maximum - 1)}…` : single;
+}
+/** Condense one of Codex's internal tool-router errors, which Codex retries itself. */
+function codexTraceSummary(level, module, message) {
+    const text = message.replace(/^error=/, '');
+    if (module.includes('tools::router') || module.includes('tools')) {
+        if (/apply_patch verification failed/i.test(text))
+            return 'Codex edit retried (patch did not apply)';
+        const rejected = /^patch rejected:\s*(.*)$/i.exec(text);
+        if (rejected)
+            return `Codex edit rejected (${compactLine(rejected[1] ?? '', 120)})`;
+        const command = /^exec_command failed for `([^`]*)/i.exec(text);
+        if (command)
+            return `Codex command could not run (${compactLine((command[1] ?? '').replace(/^\/bin\/\w+ -lc /, ''), 100)})`;
+    }
+    if (level === 'DEBUG' || level === 'TRACE' || level === 'INFO')
+        return undefined;
+    return `Codex ${level === 'WARN' ? 'warning' : 'error'}: ${compactLine(text, 200)}`;
+}
+/**
+ * Clean one raw output line for the job log, or drop it: ANSI colour codes
+ * are stripped, Codex's "Reading additional input from stdin..." notice is
+ * dropped, and Codex's internal tracing lines are condensed to one readable
+ * sentence. Event lines pass through untouched.
+ */
+export function cleanJobOutputLine(line) {
+    if (line.startsWith(EVENT_PREFIX))
+        return line;
+    const stripped = stripAnsi(line).replace(/\s+$/, '');
+    if (!stripped.trim())
+        return undefined;
+    const prefix = SESSION_PREFIX.exec(stripped)?.[1] ?? '';
+    const body = stripped.slice(prefix.length);
+    if (/^Reading (?:additional )?(?:input|prompt) from stdin\.*$/i.test(body.trim()))
+        return undefined;
+    const trace = CODEX_TRACE.exec(body.trim());
+    if (trace) {
+        const summary = codexTraceSummary(trace[1], trace[2], trace[3] ?? '');
+        return summary ? `${prefix}${summary}` : undefined;
+    }
+    return stripped;
+}
+export function cleanJobOutputLines(lines) {
+    return lines.flatMap((line) => {
+        const cleaned = cleanJobOutputLine(line);
+        return cleaned === undefined ? [] : [cleaned];
+    });
+}
+const REPLY_TAG = /^<(doxloop-(?:plan-patch|plan|brief|review|triage))>(.*)$/;
+const SESSION_END = /^(?:Claude|Codex|Gemini) (?:finished|stopped|session started)\b/;
+/** A line a pretty-printed JSON document can contain on its own. */
+const JSON_LINE = /^\s*(?:[{}[\]],?|"(?:[^"\\]|\\.)*"\s*:.*|"(?:[^"\\]|\\.)*",?|-?\d[\d.eE+-]*,?|true,?|false,?|null,?|[{[].*)$/;
+/** Most lines a hidden block may hold before the filter gives up on it. */
+const MAX_HIDDEN_LINES = 50_000;
+function jsonDepthChange(line) {
+    let depth = 0;
+    let inString = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const character = line[index];
+        if (inString) {
+            if (character === '\\')
+                index += 1;
+            else if (character === '"')
+                inString = false;
+            continue;
+        }
+        if (character === '"')
+            inString = true;
+        else if (character === '{' || character === '[')
+            depth += 1;
+        else if (character === '}' || character === ']')
+            depth -= 1;
+    }
+    return depth;
+}
+function replySummary(block, complete) {
+    const body = block.lines.join('\n');
+    let parsed;
+    try {
+        const start = body.search(/[{[]/);
+        parsed = start >= 0 ? JSON.parse(body.slice(start)) : undefined;
+    }
+    catch {
+        parsed = undefined;
+    }
+    const record = parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    const count = (key) => Array.isArray(record?.[key]) ? record[key].length : undefined;
+    const hidden = `${block.lines.length} line${block.lines.length === 1 ? '' : 's'} in the full log`;
+    const incomplete = complete ? '' : ', incomplete';
+    if (block.tag === 'doxloop-plan') {
+        const pages = count('pages');
+        return pages !== undefined ? `Plan reply received: ${pages} page${pages === 1 ? '' : 's'}` : `Plan reply received (${hidden}${incomplete})`;
+    }
+    if (block.tag === 'doxloop-plan-patch') {
+        const pages = count('pages');
+        return `Plan changes received${pages !== undefined ? `: ${pages} page${pages === 1 ? '' : 's'}` : ` (${hidden}${incomplete})`}`;
+    }
+    if (block.tag === 'doxloop-brief')
+        return `Research brief received (${hidden}${incomplete})`;
+    if (block.tag === 'doxloop-review') {
+        const findings = count('findings');
+        const score = typeof record?.score === 'number' ? record.score : undefined;
+        return `Review reply received${score !== undefined ? `: ${score}/100` : ''}${findings !== undefined ? `, ${findings} finding${findings === 1 ? '' : 's'}` : ''}${score === undefined && findings === undefined ? ` (${hidden}${incomplete})` : ''}`;
+    }
+    if (block.tag === 'doxloop-triage')
+        return 'Request triage received';
+    return `Structured reply hidden (${hidden}${incomplete})`;
+}
+/**
+ * Keeps an agent's machine-readable replies out of the live activity view:
+ * a `<doxloop-plan>` block or a pretty-printed JSON document becomes one
+ * summary line ("Plan reply received: 62 pages") instead of hundreds of
+ * lines that push the useful ones out of the window. Parallel sessions are
+ * tracked by their `[task] ` prefix. The full job log keeps the raw reply.
+ */
+export class JobLogDisplayFilter {
+    blocks = new Map();
+    push(lines) {
+        return lines.flatMap((line) => this.line(line));
+    }
+    /** Summaries for blocks still open when the job ends. */
+    finish() {
+        const output = [];
+        for (const [key, block] of this.blocks)
+            output.push(`${key}${replySummary(block, false)}`);
+        this.blocks.clear();
+        return output;
+    }
+    line(raw) {
+        if (raw.startsWith(EVENT_PREFIX))
+            return [raw];
+        const stamp = /^\d{2}:\d{2}:\d{2} /.exec(raw)?.[0] ?? '';
+        const unstamped = raw.slice(stamp.length);
+        const prefix = SESSION_PREFIX.exec(unstamped)?.[1] ?? '';
+        const text = unstamped.slice(prefix.length);
+        const block = this.blocks.get(prefix);
+        if (block)
+            return this.continueBlock(block, prefix, stamp, text, raw);
+        const tag = REPLY_TAG.exec(text.trim());
+        if (tag) {
+            const opened = { kind: 'tag', tag: tag[1], lines: [], raw: [], depth: 0, strays: 0 };
+            const rest = tag[2] ?? '';
+            const close = rest.indexOf(`</${tag[1]}>`);
+            if (close >= 0) {
+                if (rest.slice(0, close).trim())
+                    opened.lines.push(rest.slice(0, close));
+                return [`${stamp}${prefix}${replySummary(opened, true)}`];
+            }
+            if (rest.trim())
+                opened.lines.push(rest);
+            this.blocks.set(prefix, opened);
+            return [];
+        }
+        const trimmed = text.trim();
+        if (trimmed === '{' || trimmed === '[' || /^```json\s*$/i.test(trimmed)) {
+            const fenced = trimmed.startsWith('```');
+            this.blocks.set(prefix, { kind: 'json', lines: fenced ? [] : [trimmed], raw: [raw], depth: fenced ? 0 : 1, strays: 0, ...(fenced ? { tag: 'fence' } : {}) });
+            return [];
+        }
+        return [raw];
+    }
+    continueBlock(block, prefix, stamp, text, raw) {
+        const trimmed = text.trim();
+        const close = block.kind === 'tag' ? `</${block.tag}>` : undefined;
+        if (close && trimmed.includes(close)) {
+            const before = trimmed.slice(0, trimmed.indexOf(close));
+            if (before.trim())
+                block.lines.push(before);
+            this.blocks.delete(prefix);
+            return [`${stamp}${prefix}${replySummary(block, true)}`];
+        }
+        if (block.tag === 'fence' && trimmed === '```') {
+            this.blocks.delete(prefix);
+            return [`${stamp}${prefix}${replySummary({ ...block, tag: undefined }, true)}`];
+        }
+        // A session that ended (or a truncated reply) must not swallow what follows.
+        if (SESSION_END.test(trimmed) || block.lines.length >= MAX_HIDDEN_LINES) {
+            this.blocks.delete(prefix);
+            return [`${stamp}${prefix}${replySummary(block.tag === 'fence' ? { ...block, tag: undefined } : block, false)}`, raw];
+        }
+        if (block.kind === 'json' && block.tag !== 'fence') {
+            if (!JSON_LINE.test(text)) {
+                block.strays += 1;
+                if (block.strays > 3) {
+                    this.blocks.delete(prefix);
+                    return [`${stamp}${prefix}${replySummary(block, false)}`, raw];
+                }
+                return [raw];
+            }
+            block.strays = 0;
+            block.lines.push(trimmed);
+            block.raw.push(raw);
+            block.depth += jsonDepthChange(trimmed);
+            if (block.depth <= 0) {
+                this.blocks.delete(prefix);
+                // A short object is readable as it stands.
+                if (block.lines.length <= 3)
+                    return block.raw;
+                return [`${stamp}${prefix}${replySummary(block, true)}`];
+            }
+            return [];
+        }
+        block.lines.push(trimmed);
+        return [];
+    }
+}
+//# sourceMappingURL=job-events.js.map

package/dist/keep-awake.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Keeps the computer from idle-sleeping while documentation jobs run: laptop
+ * sleep used to kill authoring batches mid-session. One helper process is
+ * held while any job needs it (reference-counted across concurrent jobs) and
+ * released when the last one ends or the server exits.
+ *
+ * macOS: `caffeinate -i -w <server pid>` (also exits on its own if the
+ * server dies). Linux: `systemd-inhibit --what=idle:sleep … sleep infinity`
+ * when systemd-inhibit is installed. Elsewhere, or with
+ * DOXLOOP_KEEP_AWAKE=0, nothing happens.
+ */
+import { type ChildProcess } from 'node:child_process';
+export interface KeepAwakeOptions {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    pid?: number;
+    spawn?: (command: string, args: string[], options: {
+        stdio: 'ignore';
+    }) => ChildProcess;
+    /** Whether a command is on PATH; replaced in tests. */
+    hasCommand?: (command: string) => boolean;
+    /** Register process-exit cleanup (off in tests). */
+    registerExitHook?: boolean;
+}
+export declare function keepAwakeCommand(options?: Pick<KeepAwakeOptions, 'platform' | 'env' | 'pid' | 'hasCommand'>): {
+    command: string;
+    args: string[];
+} | undefined;
+export declare class KeepAwake {
+    private readonly options;
+    private holders;
+    private child;
+    private exitHooked;
+    constructor(options?: KeepAwakeOptions);
+    /** Number of jobs currently holding the computer awake. */
+    get count(): number;
+    /** Whether a keep-awake helper process is running. */
+    get active(): boolean;
+    /**
+     * Hold the computer awake until the returned release function is called.
+     * Releasing twice is harmless; the helper stops when the last holder releases.
+     */
+    acquire(): () => void;
+    /** Stop the helper regardless of holders (process exit). */
+    stop(): void;
+    private start;
+}
+/** The UI server's shared keep-awake. */
+export declare const keepAwake: KeepAwake;
+//# sourceMappingURL=keep-awake.d.ts.map

package/dist/keep-awake.js

@@ -0,0 +1,123 @@
+/**
+ * Keeps the computer from idle-sleeping while documentation jobs run: laptop
+ * sleep used to kill authoring batches mid-session. One helper process is
+ * held while any job needs it (reference-counted across concurrent jobs) and
+ * released when the last one ends or the server exits.
+ *
+ * macOS: `caffeinate -i -w <server pid>` (also exits on its own if the
+ * server dies). Linux: `systemd-inhibit --what=idle:sleep … sleep infinity`
+ * when systemd-inhibit is installed. Elsewhere, or with
+ * DOXLOOP_KEEP_AWAKE=0, nothing happens.
+ */
+import { spawn as nodeSpawn } from 'node:child_process';
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+export function keepAwakeCommand(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.DOXLOOP_KEEP_AWAKE === '0' || env.DOXLOOP_KEEP_AWAKE === 'false')
+        return undefined;
+    const platform = options.platform ?? process.platform;
+    const hasCommand = options.hasCommand ?? ((command) => commandOnPath(command, env));
+    if (platform === 'darwin') {
+        return { command: 'caffeinate', args: ['-i', '-w', String(options.pid ?? process.pid)] };
+    }
+    if (platform === 'linux' && hasCommand('systemd-inhibit')) {
+        return {
+            command: 'systemd-inhibit',
+            args: ['--what=idle:sleep', '--who=Doxloop', '--why=Doxloop is generating documentation', '--mode=block', 'sleep', 'infinity'],
+        };
+    }
+    return undefined;
+}
+function commandOnPath(command, env) {
+    for (const directory of (env.PATH ?? '').split(delimiter)) {
+        if (!directory)
+            continue;
+        try {
+            accessSync(join(directory, command), constants.X_OK);
+            return true;
+        }
+        catch {
+            // Keep looking.
+        }
+    }
+    return false;
+}
+export class KeepAwake {
+    options;
+    holders = 0;
+    child;
+    exitHooked = false;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Number of jobs currently holding the computer awake. */
+    get count() {
+        return this.holders;
+    }
+    /** Whether a keep-awake helper process is running. */
+    get active() {
+        return this.child !== undefined;
+    }
+    /**
+     * Hold the computer awake until the returned release function is called.
+     * Releasing twice is harmless; the helper stops when the last holder releases.
+     */
+    acquire() {
+        this.holders += 1;
+        if (this.holders === 1)
+            this.start();
+        let released = false;
+        return () => {
+            if (released)
+                return;
+            released = true;
+            this.holders = Math.max(0, this.holders - 1);
+            if (this.holders === 0)
+                this.stop();
+        };
+    }
+    /** Stop the helper regardless of holders (process exit). */
+    stop() {
+        const child = this.child;
+        this.child = undefined;
+        if (child && child.exitCode === null && child.signalCode === null) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // Already gone.
+            }
+        }
+    }
+    start() {
+        const command = keepAwakeCommand(this.options);
+        if (!command)
+            return;
+        let child;
+        try {
+            child = (this.options.spawn ?? nodeSpawn)(command.command, command.args, { stdio: 'ignore' });
+        }
+        catch {
+            return;
+        }
+        this.child = child;
+        // A missing binary or a helper that exits early just means no keep-awake.
+        child.once('error', () => {
+            if (this.child === child)
+                this.child = undefined;
+        });
+        child.once('exit', () => {
+            if (this.child === child)
+                this.child = undefined;
+        });
+        child.unref?.();
+        if (!this.exitHooked && this.options.registerExitHook !== false) {
+            this.exitHooked = true;
+            process.once('exit', () => this.stop());
+        }
+    }
+}
+/** The UI server's shared keep-awake. */
+export const keepAwake = new KeepAwake();
+//# sourceMappingURL=keep-awake.js.map

package/dist/local-source-snapshot.d.ts

@@ -0,0 +1,20 @@
+import type { SourceBinding } from './types.js';
+export interface LocalSourceSnapshot {
+    /** The sources with every copied path replaced by its snapshot. */
+    sources: SourceBinding[];
+    copied: Array<{
+        name: string;
+        path: string;
+        files: number;
+    }>;
+}
+/**
+ * Copy each local source folder into a throwaway snapshot beside the managed
+ * remote snapshots, so an agent that cannot be denied write access to extra
+ * directories (Gemini) never touches the user's real checkout. Sources that
+ * are already managed snapshots, remote, inside the project, or missing are
+ * left as they are. A snapshot is keyed by content, so an unchanged source is
+ * reused rather than copied again.
+ */
+export declare function snapshotLocalSources(root: string, sources: SourceBinding[]): Promise<LocalSourceSnapshot>;
+//# sourceMappingURL=local-source-snapshot.d.ts.map

package/dist/local-source-snapshot.js

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto';
+import { cp, mkdir, mkdtemp, rename, rm } from 'node:fs/promises';
+import { dirname, join, relative, resolve, sep, isAbsolute } from 'node:path';
+import { pathExists } from './fs.js';
+import { sourceKind } from './project.js';
+import { localSourceManifest } from './sync.js';
+/**
+ * Copy each local source folder into a throwaway snapshot beside the managed
+ * remote snapshots, so an agent that cannot be denied write access to extra
+ * directories (Gemini) never touches the user's real checkout. Sources that
+ * are already managed snapshots, remote, inside the project, or missing are
+ * left as they are. A snapshot is keyed by content, so an unchanged source is
+ * reused rather than copied again.
+ */
+export async function snapshotLocalSources(root, sources) {
+    const projectRoot = resolve(root);
+    const projectId = createHash('sha256').update(projectRoot).digest('hex').slice(0, 12);
+    const copied = [];
+    const rewritten = [];
+    for (const source of sources) {
+        const sourcePath = resolve(projectRoot, source.path);
+        if (sourceKind(source) !== 'directory' ||
+            source.remote ||
+            sourcePath.split(sep).includes('.doxloop-sources') ||
+            !isOutside(projectRoot, sourcePath) ||
+            !(await pathExists(sourcePath))) {
+            rewritten.push(source);
+            continue;
+        }
+        const manifest = await localSourceManifest(sourcePath);
+        const destination = join(dirname(projectRoot), '.doxloop-sources', projectId, safeName(source.name), `local-${manifest.fingerprint.slice(0, 12)}`);
+        if (!(await pathExists(destination))) {
+            const parent = dirname(destination);
+            await mkdir(parent, { recursive: true });
+            const temporary = await mkdtemp(join(parent, '.copy-'));
+            try {
+                for (const file of Object.keys(manifest.files)) {
+                    const target = join(temporary, file);
+                    await mkdir(dirname(target), { recursive: true });
+                    await cp(join(sourcePath, file), target, { dereference: false, errorOnExist: false, force: true });
+                }
+                await rename(temporary, destination);
+            }
+            catch (error) {
+                await rm(temporary, { recursive: true, force: true });
+                throw error;
+            }
+        }
+        copied.push({ name: source.name, path: destination, files: Object.keys(manifest.files).length });
+        rewritten.push({ ...source, path: destination });
+    }
+    return { sources: rewritten, copied };
+}
+function isOutside(projectRoot, path) {
+    const rel = relative(projectRoot, path);
+    return rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+function safeName(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || 'source';
+}
+//# sourceMappingURL=local-source-snapshot.js.map

package/dist/mintlify-detect.d.ts

@@ -0,0 +1,3 @@
+/** Detection never treats Mintlify as a generator that can be adopted in place. */
+export declare function mintlifyMarker(root: string): Promise<string | undefined>;
+//# sourceMappingURL=mintlify-detect.d.ts.map

package/dist/mintlify-detect.js

@@ -0,0 +1,18 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Detection never treats Mintlify as a generator that can be adopted in place. */
+export async function mintlifyMarker(root) {
+    for (const name of ['docs.json', 'mint.json']) {
+        try {
+            const config = JSON.parse(await readFile(join(root, name), 'utf8'));
+            // Existing Doxbrix projects also have a legacy title + navigation-array format.
+            if (name === 'docs.json' && typeof config?.title === 'string' && Array.isArray(config.navigation))
+                continue;
+            if (config && config.navigation && !Array.isArray(config.spaces))
+                return name;
+        }
+        catch { /* Not a Mintlify configuration. */ }
+    }
+    return undefined;
+}
+//# sourceMappingURL=mintlify-detect.js.map