@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/git/repo.js

@@ -0,0 +1,222 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** Repositories as a whole: creating and copying them, revisions, configuration, worktrees. */
+import { dirname, resolve } from 'node:path';
+import { ensureDir, exists } from '../kernel/fs.js';
+import { git, gitBytes, gitFailure, gitResult, nulFields } from './run.js';
+/**
+ * Whether `directory` is itself a repository: a checkout's top level or a
+ * bare repository. A subdirectory of a checkout is not.
+ *
+ * @param directory - The directory
+ */
+export async function isRepository(directory) {
+    if (!(await exists(directory)))
+        return false;
+    return (await gitResult(['rev-parse', '--git-dir'], { cwd: directory })).exitCode === 0;
+}
+/**
+ * Creates an empty repository, and the directory if needed.
+ *
+ * @param directory - Where
+ * @param options - See {@link InitOptions}
+ */
+export async function initRepository(directory, options = {}) {
+    await ensureDir(directory);
+    await git([
+        'init',
+        '--quiet',
+        ...(options.bare === true ? ['--bare'] : []),
+        `--object-format=${options.objectFormat ?? 'sha1'}`,
+        `--initial-branch=${options.branch ?? 'main'}`,
+    ], { cwd: directory });
+}
+/**
+ * Clones a local repository. With `shared`, the clone borrows the source's
+ * objects instead of copying them (`git clone --shared`), so it costs
+ * almost nothing but must not outlive the source.
+ *
+ * @param source - The repository to clone
+ * @param target - The new repository's directory; must not exist or be empty
+ * @param options - `shared`, and `bare` for a clone without a worktree
+ */
+export async function cloneRepository(source, target, options = {}) {
+    await ensureDir(dirname(target));
+    await git([
+        'clone',
+        '--quiet',
+        ...(options.shared === true ? ['--shared'] : []),
+        ...(options.bare === true ? ['--bare'] : []),
+        '--',
+        source,
+        target,
+    ], { cwd: dirname(target) });
+}
+/**
+ * Fetches one commit and what it needs from another repository, without tags.
+ * Point a ref at it afterwards ({@link updateRef}) or it may be collected.
+ *
+ * @param cwd - The receiving repository
+ * @param source - A path or URL of the repository holding `commit`
+ * @param commit - The full commit id
+ * @param options - `depth` limits history (1: the commit alone)
+ */
+export async function fetchCommit(cwd, source, commit, options = {}) {
+    await git([
+        'fetch',
+        '--quiet',
+        '--no-tags',
+        '--no-write-fetch-head',
+        ...(options.depth === undefined ? [] : [`--depth=${options.depth}`]),
+        '--',
+        source,
+        commit,
+    ], { cwd });
+}
+/**
+ * Resolves a revision to a full object id.
+ *
+ * @param cwd - The repository
+ * @param revision - Any revision (`HEAD`, a ref, an id, `rev:path`)
+ * @param type - Peel to this type (`HEAD` → its tree with `tree`); not for a `rev:path`
+ * @returns The id, or undefined when the revision does not resolve (an unborn
+ *   HEAD, a missing ref, a path absent at that revision)
+ */
+export async function resolveRevision(cwd, revision, type) {
+    const spec = type === undefined ? revision : `${revision}^{${type}}`;
+    const args = ['rev-parse', '--verify', '--quiet', '--end-of-options', spec];
+    const result = await gitResult(args, { cwd });
+    if (result.exitCode === 0)
+        return result.stdout.toString('utf8').trim();
+    if (result.exitCode === 1)
+        return undefined;
+    throw gitFailure(args, result, cwd);
+}
+/**
+ * The branch HEAD is on, or undefined when HEAD is detached.
+ *
+ * @param cwd - The repository
+ */
+export async function currentBranch(cwd) {
+    const args = ['symbolic-ref', '--quiet', '--short', 'HEAD'];
+    const result = await gitResult(args, { cwd });
+    if (result.exitCode === 0)
+        return result.stdout.toString('utf8').trim();
+    if (result.exitCode === 1)
+        return undefined;
+    throw gitFailure(args, result, cwd);
+}
+/**
+ * The best common ancestor of two commits, or undefined when they share none.
+ *
+ * @param cwd - The repository
+ * @param a - A commit
+ * @param b - A commit
+ */
+export async function mergeBase(cwd, a, b) {
+    const args = ['merge-base', a, b];
+    const result = await gitResult(args, { cwd });
+    if (result.exitCode === 0)
+        return result.stdout.toString('utf8').trim();
+    if (result.exitCode === 1)
+        return undefined;
+    throw gitFailure(args, result, cwd);
+}
+/**
+ * Whether `ancestor` is `descendant` or one of its ancestors.
+ *
+ * @param cwd - The repository
+ * @param ancestor - A commit
+ * @param descendant - A commit
+ */
+export async function isAncestor(cwd, ancestor, descendant) {
+    const args = ['merge-base', '--is-ancestor', ancestor, descendant];
+    const result = await gitResult(args, { cwd });
+    if (result.exitCode === 0 || result.exitCode === 1)
+        return result.exitCode === 0;
+    throw gitFailure(args, result, cwd);
+}
+/**
+ * The repository's object format, which fixes the length of its ids.
+ *
+ * @param cwd - The repository
+ */
+export async function objectFormat(cwd) {
+    const format = (await git(['rev-parse', '--show-object-format'], { cwd })).trim();
+    return format === 'sha256' ? 'sha256' : 'sha1';
+}
+/**
+ * The absolute path of the repository's git directory, or with `common` of
+ * the directory a linked worktree shares with its main checkout.
+ *
+ * @param cwd - The repository
+ * @param options - `common`
+ */
+export async function gitDir(cwd, options = {}) {
+    const which = options.common === true ? '--git-common-dir' : '--git-dir';
+    // Git answers with forward slashes on every platform.
+    return resolve((await git(['rev-parse', '--path-format=absolute', which], { cwd })).trim());
+}
+/**
+ * Reads a setting from the repository's own configuration file.
+ *
+ * @param cwd - The repository
+ * @param key - The key (`merge.fireforge.driver`)
+ * @returns Its value, or undefined when unset
+ */
+export async function getConfig(cwd, key) {
+    const args = ['config', '--local', '--get', key];
+    const result = await gitResult(args, { cwd });
+    if (result.exitCode === 0)
+        return result.stdout.toString('utf8').replace(/\n$/, '');
+    if (result.exitCode === 1)
+        return undefined;
+    throw gitFailure(args, result, cwd);
+}
+/**
+ * Writes or removes a setting in the repository's own configuration file.
+ *
+ * @param cwd - The repository
+ * @param key - The key
+ * @param value - The value, or undefined to remove every value of the key
+ */
+export async function setConfig(cwd, key, value) {
+    if (value !== undefined) {
+        await git(['config', '--local', key, value], { cwd });
+        return;
+    }
+    const args = ['config', '--local', '--unset-all', key];
+    const result = await gitResult(args, { cwd });
+    // 5: the key was not set, which is the state asked for.
+    if (result.exitCode !== 0 && result.exitCode !== 5)
+        throw gitFailure(args, result, cwd);
+}
+/**
+ * The repository's worktrees, the main one first.
+ *
+ * @param cwd - The repository or any of its worktrees
+ */
+export async function listWorktrees(cwd) {
+    const fields = nulFields(await gitBytes(['worktree', 'list', '--porcelain', '-z'], { cwd }));
+    const worktrees = [];
+    let current;
+    for (const field of fields) {
+        const [key = '', value = ''] = field.split(/ (.*)/s);
+        if (key === 'worktree') {
+            current = { path: resolve(value), bare: false, locked: false, prunable: false };
+            worktrees.push(current);
+        }
+        else if (current === undefined)
+            continue;
+        else if (key === 'HEAD')
+            current.head = value;
+        else if (key === 'branch')
+            current.branch = value;
+        else if (key === 'bare')
+            current.bare = true;
+        else if (key === 'locked')
+            current.locked = true;
+        else if (key === 'prunable')
+            current.prunable = true;
+    }
+    return worktrees;
+}

package/dist/src/git/run.js

@@ -0,0 +1,242 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The one way FireForge runs git.
+ *
+ * Every call is hermetic: the operator's global and system configuration,
+ * repository-selecting variables (`GIT_DIR`, `GIT_INDEX_FILE`, …) and outer
+ * `git -c` settings are dropped, and the settings below are pinned, so
+ * output and object ids are the same on every host. Repository-local
+ * configuration still applies.
+ *
+ * `cwd` is always the repository itself: its top-level directory, or a bare
+ * repository's directory. Git does not search parent directories, so a
+ * directory that is not a repository fails rather than silently addressing
+ * an enclosing one (an engine inside a project checkout, say). Pathspecs are
+ * literal. Optional index refreshes are off, so reading a repository never
+ * writes its index.
+ */
+import { isUtf8 } from 'node:buffer';
+import { dirname, join, resolve } from 'node:path';
+import { ExitCode, FireForgeError } from '../kernel/errors.js';
+import { exists, makeTempDir, remove } from '../kernel/fs.js';
+import { runBytes } from '../kernel/process/index.js';
+import { tailLines } from '../kernel/text.js';
+/**
+ * The empty file, as git spells it on every platform. Git for Windows maps
+ * this name itself and refuses the native device path.
+ */
+export const GIT_NULL = '/dev/null';
+const PINNED_CONFIG = [
+    ['core.fsmonitor', 'false'],
+    ['core.hooksPath', GIT_NULL],
+    ['core.attributesFile', GIT_NULL],
+    ['core.excludesFile', GIT_NULL],
+    ['core.autocrlf', 'false'],
+    ['core.safecrlf', 'false'],
+    ['core.quotePath', 'true'],
+    ['diff.noprefix', 'false'],
+    ['diff.mnemonicPrefix', 'false'],
+    ['diff.renames', 'false'],
+    ['diff.algorithm', 'myers'],
+    ['diff.indentHeuristic', 'true'],
+    ['diff.context', '3'],
+    ['diff.interHunkContext', '0'],
+    ['diff.suppressBlankEmpty', 'false'],
+    ['merge.conflictStyle', 'merge'],
+    ['color.ui', 'false'],
+    ['commit.gpgsign', 'false'],
+    ['tag.gpgsign', 'false'],
+    // No background `gc --auto` detaching from a FireForge command.
+    ['gc.auto', '0'],
+    ['maintenance.auto', 'false'],
+];
+/** Inherited `GIT_*` variables that select a transport or trace output, never a repository. */
+const KEPT_GIT_VARIABLE = /^GIT_(?:EXEC_PATH|SSH|SSH_COMMAND|SSH_VARIANT|SSL_\w+|PROXY_\w+|ASKPASS|TRACE\w*|CURL_VERBOSE)$/;
+function environment(options) {
+    const env = {};
+    for (const key of Object.keys(process.env)) {
+        if (key.startsWith('GIT_') && !KEPT_GIT_VARIABLE.test(key))
+            env[key] = undefined;
+    }
+    Object.assign(env, {
+        GIT_CONFIG_GLOBAL: GIT_NULL,
+        GIT_CONFIG_NOSYSTEM: '1',
+        GIT_ATTR_NOSYSTEM: '1',
+        GIT_TERMINAL_PROMPT: '0',
+        GIT_OPTIONAL_LOCKS: '0',
+        GIT_NO_REPLACE_OBJECTS: '1',
+        GIT_LITERAL_PATHSPECS: '1',
+        GIT_CEILING_DIRECTORIES: dirname(resolve(options.cwd)),
+        // Messages are parsed (`git apply`'s rejects), so they must not be translated.
+        LC_ALL: 'C',
+        GIT_CONFIG_COUNT: String(PINNED_CONFIG.length),
+    });
+    for (const [index, [key, value]] of PINNED_CONFIG.entries()) {
+        env[`GIT_CONFIG_KEY_${index}`] = key;
+        env[`GIT_CONFIG_VALUE_${index}`] = value;
+    }
+    if (options.index !== undefined)
+        env['GIT_INDEX_FILE'] = options.index;
+    return { ...env, ...options.env };
+}
+function notARepository(cwd, cause) {
+    return new FireForgeError('git-not-a-repository', `${cwd} is not a git repository.`, {
+        exitCode: ExitCode.GIT_ERROR,
+        cause,
+    });
+}
+/**
+ * The error for a failed git call: `git-not-a-repository`, `git-index-locked`
+ * or `git-failed`, with git's stderr in the message and the cause.
+ *
+ * @param args - The arguments after `git`
+ * @param result - How the call ended
+ * @param cwd - The repository
+ */
+export function gitFailure(args, result, cwd) {
+    const stderr = result.stderr.trim();
+    const cause = new Error(stderr);
+    if (/not a git repository/i.test(stderr))
+        return notARepository(cwd, cause);
+    const lock = /Unable to create '([^']*index\.lock)'/.exec(stderr)?.[1];
+    if (lock !== undefined) {
+        return new FireForgeError('git-index-locked', `The git index of ${cwd} is locked.`, {
+            exitCode: ExitCode.GIT_ERROR,
+            hint: `Another git process is using it. If none is running, remove ${lock}.`,
+            cause,
+        });
+    }
+    const command = `git ${args.join(' ')}`;
+    const tail = tailLines(stderr, 10);
+    return new FireForgeError('git-failed', `${command.length > 200 ? `${command.slice(0, 200)}…` : command} failed (exit ${result.exitCode})` +
+        (tail.length === 0 ? '.' : `:\n${tail.map((line) => `  ${line}`).join('\n')}`), { exitCode: ExitCode.GIT_ERROR, cause });
+}
+/**
+ * Runs git and returns how it ended, whatever the exit code. For commands
+ * whose exit code is an answer (`check-ignore`, `merge-base --is-ancestor`).
+ *
+ * @param args - The arguments after `git`
+ * @param options - See {@link GitOptions}
+ */
+export async function gitResult(args, options) {
+    const config = Object.entries(options.config ?? {}).flatMap(([key, value]) => [
+        '-c',
+        `${key}=${value}`,
+    ]);
+    try {
+        return await runBytes('git', ['--no-pager', ...config, ...args], {
+            cwd: options.cwd,
+            env: environment(options),
+            ...(options.input !== undefined && { input: options.input }),
+        });
+    }
+    catch (error) {
+        // A missing working directory fails the spawn the way a missing program does.
+        if (!(await exists(options.cwd)))
+            throw notARepository(options.cwd, error);
+        throw error;
+    }
+}
+/**
+ * Runs git and returns stdout as bytes; a non-zero exit throws.
+ *
+ * @param args - The arguments after `git`
+ * @param options - See {@link GitOptions}
+ */
+export async function gitBytes(args, options) {
+    const result = await gitResult(args, options);
+    if (result.exitCode !== 0)
+        throw gitFailure(args, result, options.cwd);
+    return result.stdout;
+}
+/**
+ * Runs git and returns stdout as text; a non-zero exit throws.
+ *
+ * @param args - The arguments after `git`
+ * @param options - See {@link GitOptions}
+ */
+export async function git(args, options) {
+    return (await gitBytes(args, options)).toString('utf8');
+}
+/**
+ * Splits NUL-terminated `-z` output into paths. Git paths are bytes; one
+ * that is not UTF-8 is refused rather than silently renamed.
+ *
+ * @param output - The output
+ */
+export function nulFields(output) {
+    if (!isUtf8(output)) {
+        throw new FireForgeError('git-path-encoding', 'git reported a path that is not valid UTF-8.', {
+            exitCode: ExitCode.GIT_ERROR,
+            hint: 'Rename the file to a UTF-8 name.',
+        });
+    }
+    const fields = output.toString('utf8').split('\0');
+    if (fields.at(-1) === '')
+        fields.pop();
+    return fields;
+}
+/**
+ * Groups paths so each group's arguments stay well under the smallest
+ * historical argument-length limit (256 KiB), with room for the environment.
+ *
+ * @param paths - The paths
+ * @param budget - Bytes per group
+ */
+export function chunkPaths(paths, budget = 96_000) {
+    const chunks = [];
+    let current = [];
+    let used = 0;
+    for (const path of paths) {
+        const cost = Buffer.byteLength(path) + 1;
+        if (current.length > 0 && used + cost > budget) {
+            chunks.push(current);
+            current = [];
+            used = 0;
+        }
+        current.push(path);
+        used += cost;
+    }
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/**
+ * Runs a `-z` listing command over `paths` in argument-sized chunks (once,
+ * unscoped, when `paths` is undefined) and returns the union of its output.
+ *
+ * @param args - The command, without `--` and paths
+ * @param paths - Pathspecs, or undefined for the whole repository
+ * @param options - See {@link GitOptions}
+ */
+export async function listPaths(args, paths, options) {
+    if (paths === undefined)
+        return nulFields(await gitBytes(args, options));
+    const found = new Set();
+    for (const chunk of chunkPaths(paths)) {
+        for (const path of nulFields(await gitBytes([...args, '--', ...chunk], options)))
+            found.add(path);
+    }
+    return [...found];
+}
+/**
+ * Runs `task` with a scratch index, so nothing in the repository's own index
+ * moves: dry runs, snapshots and tree construction work here. The index
+ * starts as `seed` (a tree-ish) or empty, and is deleted afterwards.
+ *
+ * @param cwd - The repository
+ * @param seed - Tree-ish to start from, or undefined for an empty index
+ * @param task - Receives the index file's path, for {@link GitOptions.index}
+ */
+export async function withPrivateIndex(cwd, seed, task) {
+    const directory = await makeTempDir('fireforge-index-');
+    const index = join(directory, 'index');
+    try {
+        if (seed !== undefined)
+            await git(['read-tree', seed], { cwd, index });
+        return await task(index);
+    }
+    finally {
+        await remove(directory);
+    }
+}

package/dist/src/git/status.js

@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: EUPL-1.2
+/** The working tree: its status, which files git tracks or ignores, and putting paths back. */
+import { chunkPaths, git, gitBytes, gitFailure, gitResult, listPaths, nulFields } from './run.js';
+/**
+ * The working tree's changes against HEAD, rename detection off, untracked
+ * files listed one by one rather than as directories.
+ *
+ * @param cwd - The repository
+ * @param options - `paths` limits the report; `untracked: false` leaves untracked files out
+ */
+export async function status(cwd, options = {}) {
+    const args = [
+        'status',
+        '--porcelain=v1',
+        '-z',
+        '--no-renames',
+        `--untracked-files=${options.untracked === false ? 'no' : 'all'}`,
+    ];
+    const records = await listPaths(args, options.paths, { cwd });
+    const entries = new Map();
+    for (const record of records) {
+        if (record.length < 4)
+            continue;
+        const entry = { path: record.slice(3), index: record.charAt(0), worktree: record.charAt(1) };
+        entries.set(entry.path, entry);
+    }
+    return [...entries.values()];
+}
+const FILE_SET_ARGS = {
+    tracked: ['--cached'],
+    untracked: ['--others', '--exclude-standard'],
+    ignored: ['--others', '--ignored', '--exclude-standard'],
+};
+/**
+ * Lists files under `paths` (or the whole repository): tracked in the index,
+ * untracked and not ignored, or untracked and ignored.
+ *
+ * @param cwd - The repository
+ * @param options - `which` (default `tracked`) and `paths`
+ */
+export async function listFiles(cwd, options = {}) {
+    const args = ['ls-files', '-z', ...FILE_SET_ARGS[options.which ?? 'tracked']];
+    return (await listPaths(args, options.paths, { cwd })).sort();
+}
+/**
+ * Whether git tracks exactly this file (a directory is not tracked).
+ *
+ * @param cwd - The repository
+ * @param path - Repository-relative path
+ */
+export async function isTracked(cwd, path) {
+    return nulFields(await gitBytes(['ls-files', '-z', '--cached', '--', path], { cwd })).includes(path);
+}
+/**
+ * The paths among `paths` that git's ignore rules match. A tracked file is
+ * never ignored.
+ *
+ * @param cwd - The repository
+ * @param paths - Repository-relative paths
+ */
+export async function checkIgnore(cwd, paths) {
+    if (paths.length === 0)
+        return new Set();
+    const args = ['check-ignore', '-z', '--stdin'];
+    const result = await gitResult(args, {
+        cwd,
+        input: paths.map((path) => `${path}\0`).join(''),
+        // check-ignore reads paths, not pathspecs, and refuses pathspec magic.
+        env: { GIT_LITERAL_PATHSPECS: undefined },
+    });
+    // 1: none of them is ignored.
+    if (result.exitCode !== 0 && result.exitCode !== 1)
+        throw gitFailure(args, result, cwd);
+    return new Set(nulFields(result.stdout));
+}
+/**
+ * Git attributes of each path: `set`, `unset`, `unspecified` or the value.
+ *
+ * @param cwd - The repository
+ * @param paths - Repository-relative paths
+ * @param names - Attribute names (`text`, `eol`, `filter`, `merge`)
+ */
+export async function checkAttributes(cwd, paths, names) {
+    const attributes = new Map();
+    if (paths.length === 0 || names.length === 0)
+        return attributes;
+    const fields = nulFields(await gitBytes(['check-attr', '-z', '--stdin', ...names], {
+        cwd,
+        input: paths.map((path) => `${path}\0`).join(''),
+    }));
+    for (let index = 0; index + 2 < fields.length; index += 3) {
+        const path = fields[index] ?? '';
+        const row = attributes.get(path) ?? {};
+        row[fields[index + 1] ?? ''] = fields[index + 2] ?? '';
+        attributes.set(path, row);
+    }
+    return attributes;
+}
+/**
+ * Puts paths (files or directories) back as they are in `source`, in the
+ * index and the working tree. A tracked path that `source` lacks is removed
+ * from both. Untracked files are left alone; {@link cleanPaths} removes them.
+ *
+ * @param cwd - The repository
+ * @param paths - Repository-relative paths
+ * @param options - `source` (default `HEAD`)
+ */
+export async function restorePaths(cwd, paths, options = {}) {
+    if (paths.length === 0)
+        return;
+    const source = options.source ?? 'HEAD';
+    // `restore` refuses a pathspec that matches nothing, so name what exists.
+    const known = new Set([
+        ...(await listPaths(['ls-tree', '-r', '-z', '--name-only', '--full-tree', source], paths, {
+            cwd,
+        })),
+        ...(await listPaths(['ls-files', '-z', '--cached'], paths, { cwd })),
+    ]);
+    if (known.size === 0)
+        return;
+    await git([
+        'restore',
+        `--source=${source}`,
+        '--staged',
+        '--worktree',
+        '--pathspec-from-file=-',
+        '--pathspec-file-nul',
+    ], { cwd, input: [...known].map((path) => `${path}\0`).join('') });
+}
+/**
+ * Deletes untracked files and directories under `paths` (or everywhere).
+ *
+ * @param cwd - The repository
+ * @param options - `paths`; `ignored` deletes ignored files too
+ */
+export async function cleanPaths(cwd, options = {}) {
+    const args = ['clean', '-f', '-d', '-q', ...(options.ignored === true ? ['-x'] : [])];
+    if (options.paths === undefined) {
+        await git(args, { cwd });
+        return;
+    }
+    for (const chunk of chunkPaths(options.paths))
+        await git([...args, '--', ...chunk], { cwd });
+}
+/**
+ * Moves the current branch (or detached HEAD) to `commit` and makes the
+ * index match it. `hard` also makes the working tree's tracked files match;
+ * otherwise the working tree is untouched.
+ *
+ * @param cwd - The repository
+ * @param commit - Default `HEAD`
+ * @param mode - Default `hard`
+ */
+export async function reset(cwd, commit = 'HEAD', mode = 'hard') {
+    await git(['reset', '--quiet', `--${mode}`, commit, '--'], { cwd });
+}