@withtruing/companion 0.13.3 → 0.14.1

package/dist/whole-read-git.js

@@ -0,0 +1,340 @@
+import { createHash } from 'node:crypto';
+import { stat } from 'node:fs/promises';
+import crossSpawn from 'cross-spawn';
+const METADATA_LIMIT = 1 * 1024 * 1024;
+const TREE_LIMIT = 256 * 1024 * 1024;
+const BLOB_LIMIT = 256 * 1024 * 1024;
+const COMMAND_TIMEOUT_MS = 120_000;
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+export class WholeReadGitError extends Error {
+    code;
+    constructor(code) {
+        super(`Whole-read Git operation failed: ${code}.`);
+        this.code = code;
+        this.name = 'WholeReadGitError';
+    }
+}
+class ProcessFailure extends Error {
+    kind;
+    constructor(kind) {
+        super(kind);
+        this.kind = kind;
+    }
+}
+function runGit(repoPath, args, signal, outputLimit, input) {
+    if (signal.aborted)
+        return Promise.reject(new ProcessFailure('cancelled'));
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = crossSpawn('git', ['--no-replace-objects', ...args], {
+                cwd: repoPath,
+                env: {
+                    ...process.env,
+                    GIT_NO_REPLACE_OBJECTS: '1',
+                    GIT_NO_LAZY_FETCH: '1',
+                    GIT_OPTIONAL_LOCKS: '0',
+                    GIT_TERMINAL_PROMPT: '0',
+                },
+                stdio: ['pipe', 'pipe', 'pipe'],
+                windowsHide: true,
+            });
+        }
+        catch {
+            reject(new ProcessFailure('unavailable'));
+            return;
+        }
+        const chunks = [];
+        let byteCount = 0;
+        let settled = false;
+        let pendingFailure = null;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            if (error)
+                reject(error);
+            else
+                resolve({ bytes: Buffer.concat(chunks, byteCount) });
+        };
+        const stop = (kind) => {
+            if (pendingFailure || settled)
+                return;
+            pendingFailure = new ProcessFailure(kind);
+            child.kill('SIGKILL');
+        };
+        const abort = () => stop('cancelled');
+        signal.addEventListener('abort', abort, { once: true });
+        child.stdout?.on('data', (chunk) => {
+            byteCount += chunk.length;
+            if (byteCount > outputLimit)
+                stop('resource');
+            else
+                chunks.push(chunk);
+        });
+        // Diagnostics are intentionally drained but never retained or exposed.
+        child.stderr?.on('data', () => undefined);
+        child.stdin?.on('error', () => undefined);
+        child.on('error', (error) => {
+            finish(new ProcessFailure(error.code === 'ENOENT' ? 'unavailable' : 'resource'));
+        });
+        child.on('close', (code, closeSignal) => {
+            if (pendingFailure)
+                finish(pendingFailure);
+            else if (closeSignal !== null || code !== 0)
+                finish(new ProcessFailure('exit'));
+            else
+                finish();
+        });
+        const timer = setTimeout(() => stop('resource'), COMMAND_TIMEOUT_MS);
+        if (input === undefined)
+            child.stdin?.end();
+        else
+            child.stdin?.end(input);
+    });
+}
+function mapProcessFailure(error, fallback) {
+    if (error instanceof WholeReadGitError)
+        throw error;
+    if (error instanceof ProcessFailure) {
+        if (error.kind === 'cancelled')
+            throw new WholeReadGitError('cancelled');
+        if (error.kind === 'unavailable')
+            throw new WholeReadGitError('git_unavailable');
+        if (error.kind === 'resource')
+            throw new WholeReadGitError('resource_limit');
+    }
+    throw new WholeReadGitError(fallback);
+}
+function exactAsciiLine(bytes) {
+    if (bytes.length < 2 || bytes[bytes.length - 1] !== 0x0a || bytes.includes(0x0d))
+        return null;
+    const line = bytes.subarray(0, -1);
+    if (line.includes(0x0a) || line.some((byte) => byte > 0x7f))
+        return null;
+    return line.toString('ascii');
+}
+async function repositoryObjectFormat(repoPath, signal) {
+    if (signal.aborted)
+        throw new WholeReadGitError('cancelled');
+    try {
+        if (!(await stat(repoPath)).isDirectory())
+            throw new Error('not a directory');
+    }
+    catch {
+        throw new WholeReadGitError('repository_unavailable');
+    }
+    try {
+        const output = await runGit(repoPath, ['rev-parse', '--show-object-format'], signal, METADATA_LIMIT);
+        const format = exactAsciiLine(output.bytes);
+        if (format === 'sha1' || format === 'sha256')
+            return format;
+    }
+    catch (error) {
+        mapProcessFailure(error, 'repository_unavailable');
+    }
+    throw new WholeReadGitError('repository_unavailable');
+}
+function validObjectId(value, format) {
+    return (format === 'sha1' ? /^[0-9a-f]{40}$/ : /^[0-9a-f]{64}$/).test(value);
+}
+function validLocalBranch(branch) {
+    if (!branch || Buffer.byteLength(branch, 'utf8') > 1_024 || branch.startsWith('-')
+        || branch.startsWith('refs/') || branch === 'HEAD' || branch === '@'
+        || branch.startsWith('/') || branch.endsWith('/') || branch.endsWith('.')
+        || branch.includes('..') || branch.includes('//') || branch.includes('@{')
+        || /[\x00-\x20\x7f~^:?*\\[]/.test(branch))
+        return false;
+    return branch.split('/').every((part) => part && !part.startsWith('.') && !part.endsWith('.lock'));
+}
+/** Resolve one local branch without consulting remotes or the current checkout. */
+export async function resolveLocalBuildCommit(repoPath, branch, signal) {
+    if (signal.aborted)
+        throw new WholeReadGitError('cancelled');
+    if (!validLocalBranch(branch))
+        throw new WholeReadGitError('branch_unavailable');
+    const format = await repositoryObjectFormat(repoPath, signal);
+    try {
+        await runGit(repoPath, ['check-ref-format', '--branch', branch], signal, METADATA_LIMIT);
+    }
+    catch (error) {
+        mapProcessFailure(error, 'branch_unavailable');
+    }
+    let commit;
+    try {
+        const output = await runGit(repoPath, ['rev-parse', '--verify', `refs/heads/${branch}^{commit}`], signal, METADATA_LIMIT);
+        commit = exactAsciiLine(output.bytes) ?? '';
+    }
+    catch (error) {
+        mapProcessFailure(error, 'branch_unavailable');
+    }
+    if (!validObjectId(commit, format))
+        throw new WholeReadGitError('branch_unavailable');
+    try {
+        const output = await runGit(repoPath, ['cat-file', '-t', commit], signal, METADATA_LIMIT);
+        if (exactAsciiLine(output.bytes) !== 'commit')
+            throw new WholeReadGitError('snapshot_unavailable');
+    }
+    catch (error) {
+        mapProcessFailure(error, 'snapshot_unavailable');
+    }
+    return commit;
+}
+function escapedPath(bytes) {
+    let validText = null;
+    try {
+        validText = utf8Decoder.decode(bytes);
+    }
+    catch {
+        // Invalid bytes are shown individually below; base64 remains the identity.
+    }
+    if (validText !== null) {
+        let display = '';
+        for (const character of validText) {
+            const code = character.codePointAt(0);
+            if (character === '\\')
+                display += '\\\\';
+            else if (character === '\t')
+                display += '\\t';
+            else if (character === '\n')
+                display += '\\n';
+            else if (character === '\r')
+                display += '\\r';
+            else if (code < 0x20 || code === 0x7f)
+                display += `\\x${code.toString(16).padStart(2, '0')}`;
+            else
+                display += character;
+        }
+        return display;
+    }
+    let display = '';
+    for (const byte of bytes) {
+        if (byte === 0x5c)
+            display += '\\\\';
+        else if (byte === 0x09)
+            display += '\\t';
+        else if (byte === 0x0a)
+            display += '\\n';
+        else if (byte === 0x0d)
+            display += '\\r';
+        else if (byte >= 0x20 && byte <= 0x7e)
+            display += String.fromCharCode(byte);
+        else
+            display += `\\x${byte.toString(16).padStart(2, '0')}`;
+    }
+    return display;
+}
+function parseTree(bytes, format) {
+    if (bytes.length === 0)
+        return [];
+    if (bytes[bytes.length - 1] !== 0)
+        throw new WholeReadGitError('tree_invalid');
+    const entries = [];
+    const identities = new Set();
+    let offset = 0;
+    while (offset < bytes.length) {
+        const end = bytes.indexOf(0, offset);
+        if (end < 0)
+            throw new WholeReadGitError('tree_invalid');
+        const record = bytes.subarray(offset, end);
+        const tab = record.indexOf(0x09);
+        if (tab <= 0 || tab === record.length - 1)
+            throw new WholeReadGitError('tree_invalid');
+        const header = record.subarray(0, tab);
+        if (header.some((byte) => byte > 0x7f))
+            throw new WholeReadGitError('tree_invalid');
+        const match = /^(100644|100755|120000|160000) (blob|commit) ([0-9a-f]+)$/
+            .exec(header.toString('ascii'));
+        if (!match || !validObjectId(match[3], format))
+            throw new WholeReadGitError('tree_invalid');
+        const mode = match[1];
+        const objectType = match[2];
+        if ((mode === '160000') !== (objectType === 'commit'))
+            throw new WholeReadGitError('tree_invalid');
+        const path = record.subarray(tab + 1);
+        const pathBase64 = path.toString('base64');
+        if (identities.has(pathBase64))
+            throw new WholeReadGitError('tree_invalid');
+        identities.add(pathBase64);
+        entries.push({
+            pathBase64,
+            pathDisplay: escapedPath(path),
+            mode,
+            objectType,
+            blobId: match[3],
+        });
+        offset = end + 1;
+    }
+    return entries;
+}
+/** Enumerate only after the complete NUL-delimited tree output has been validated. */
+export async function* enumerateBuildTree(repoPath, commit, signal) {
+    const format = await repositoryObjectFormat(repoPath, signal);
+    if (!validObjectId(commit, format))
+        throw new WholeReadGitError('snapshot_unavailable');
+    try {
+        const type = await runGit(repoPath, ['cat-file', '-t', commit], signal, METADATA_LIMIT);
+        if (exactAsciiLine(type.bytes) !== 'commit')
+            throw new WholeReadGitError('snapshot_unavailable');
+    }
+    catch (error) {
+        mapProcessFailure(error, 'snapshot_unavailable');
+    }
+    let output;
+    try {
+        output = await runGit(repoPath, ['ls-tree', '-r', '-z', '--full-tree', commit], signal, TREE_LIMIT);
+    }
+    catch (error) {
+        mapProcessFailure(error, 'tree_invalid');
+    }
+    const entries = parseTree(output.bytes, format);
+    for (const entry of entries) {
+        if (signal.aborted)
+            throw new WholeReadGitError('cancelled');
+        yield entry;
+    }
+}
+function parseBlobResponse(response, expectedId, format) {
+    const headerEnd = response.indexOf(0x0a);
+    if (headerEnd < 0)
+        throw new WholeReadGitError('blob_invalid');
+    const header = response.subarray(0, headerEnd);
+    if (header.includes(0x0d) || header.some((byte) => byte > 0x7f)) {
+        throw new WholeReadGitError('blob_invalid');
+    }
+    const match = /^([0-9a-f]+) ([^ ]+) (0|[1-9][0-9]*)$/.exec(header.toString('ascii'));
+    if (!match || match[1] !== expectedId || match[2] !== 'blob'
+        || !validObjectId(match[1], format))
+        throw new WholeReadGitError('blob_invalid');
+    const size = Number(match[3]);
+    if (!Number.isSafeInteger(size) || size > BLOB_LIMIT)
+        throw new WholeReadGitError('resource_limit');
+    const bodyStart = headerEnd + 1;
+    const bodyEnd = bodyStart + size;
+    if (bodyEnd + 1 !== response.length || response[bodyEnd] !== 0x0a) {
+        throw new WholeReadGitError('blob_invalid');
+    }
+    const body = response.subarray(bodyStart, bodyEnd);
+    const actualId = createHash(format)
+        .update(Buffer.from(`blob ${size}\0`, 'ascii'))
+        .update(body)
+        .digest('hex');
+    if (actualId !== expectedId)
+        throw new WholeReadGitError('blob_hash_mismatch');
+    return Buffer.from(body);
+}
+/** Read and verify one canonical blob through Git's framed batch protocol. */
+export async function readBuildBlob(repoPath, blobId, signal) {
+    const format = await repositoryObjectFormat(repoPath, signal);
+    if (!validObjectId(blobId, format))
+        throw new WholeReadGitError('blob_invalid');
+    try {
+        const output = await runGit(repoPath, ['cat-file', '--batch'], signal, BLOB_LIMIT + METADATA_LIMIT, Buffer.from(`${blobId}\n`, 'ascii'));
+        return parseBlobResponse(output.bytes, blobId, format);
+    }
+    catch (error) {
+        mapProcessFailure(error, 'blob_invalid');
+    }
+}

package/dist/whole-read-pool.js

@@ -0,0 +1,80 @@
+const DEFAULT_PARALLEL_STEPS = 3;
+export function wholeReadParallelSteps(value = process.env.TRUING_PARALLEL_STEPS) {
+    if (typeof value !== 'string' && typeof value !== 'number')
+        return DEFAULT_PARALLEL_STEPS;
+    const parsed = typeof value === 'number' ? value : Number(value);
+    return Number.isInteger(parsed) && parsed >= 1 && parsed <= 8 ? parsed : DEFAULT_PARALLEL_STEPS;
+}
+export function createWholeReadAssignmentPool(dependencies) {
+    const concurrency = wholeReadParallelSteps(dependencies.concurrency);
+    const states = new Map();
+    let stopping = false;
+    const retire = (state) => {
+        if (state.revoked)
+            return;
+        state.revoked = true;
+        void Promise.resolve(dependencies.onRevoke?.(state.assignment)).catch((error) => {
+            dependencies.onError?.(error, state.assignment);
+        });
+    };
+    const start = (state) => {
+        dependencies.onStart?.(state.assignment);
+        let task;
+        task = dependencies.run(state.assignment)
+            .then((result) => {
+            if (result.status === 'build_concurrency_limit')
+                state.limitedPolls = 1;
+            else if (result.status === 'claimed')
+                state.limitedPolls = 0;
+        })
+            .catch((error) => { dependencies.onError?.(error, state.assignment); })
+            .finally(() => {
+            state.active.delete(task);
+            if (state.revoked && state.active.size === 0)
+                states.delete(dependencies.key(state.assignment));
+        });
+        state.active.add(task);
+    };
+    return {
+        poll(assignments) {
+            if (stopping || dependencies.shouldStop())
+                return 0;
+            const visible = new Set(assignments.map(dependencies.key));
+            for (const [key, state] of states)
+                if (!visible.has(key))
+                    retire(state);
+            if (!dependencies.mayClaim())
+                return 0;
+            let started = 0;
+            for (const assignment of assignments) {
+                if (stopping || dependencies.shouldStop() || !dependencies.mayClaim())
+                    break;
+                const key = dependencies.key(assignment);
+                let state = states.get(key);
+                if (!state || state.revoked) {
+                    state = { assignment, active: new Set(), revoked: false, limitedPolls: 0 };
+                    states.set(key, state);
+                }
+                else
+                    state.assignment = assignment;
+                if (state.limitedPolls > 0) {
+                    state.limitedPolls--;
+                    continue;
+                }
+                while (state.active.size < concurrency && !dependencies.shouldStop() && dependencies.mayClaim()) {
+                    start(state);
+                    started++;
+                }
+            }
+            return started;
+        },
+        inFlight(key) { return states.get(key)?.active.size ?? 0; },
+        async shutdown() {
+            stopping = true;
+            for (const state of states.values())
+                retire(state);
+            await Promise.allSettled([...states.values()].flatMap((state) => [...state.active]));
+            states.clear();
+        },
+    };
+}