@james-pre/mc-admin 0.1.0

package/dist/log.js

@@ -0,0 +1,137 @@
+import { existsSync, watch } from 'node:fs';
+import { open, stat } from 'node:fs/promises';
+import { basename, dirname } from 'node:path';
+import { toLines } from './common/buffers.js';
+import { parse } from './common/log.js';
+import { styleText } from 'node:util';
+export * from './common/log.js';
+const blockSize = 64 * 1024;
+/** The offset the last `count` lines of a file begin at. */
+async function backfillOffset(handle, size, count) {
+    if (count <= 0)
+        return size;
+    const block = new Uint8Array(blockSize);
+    let end = size, found = 0;
+    while (end > 0) {
+        const start = Math.max(0, end - block.length);
+        const { bytesRead } = await handle.read(block, 0, end - start, start);
+        for (let i = bytesRead - 1; i >= 0; i--) {
+            // The newline ending the final line doesn't start one.
+            if (block[i] !== 0x0a || start + i === size - 1)
+                continue;
+            if (++found === count)
+                return start + i + 1;
+        }
+        end = start;
+    }
+    return 0;
+}
+/** Follow a file, emitting bytes as they are appended, across rotation and truncation. */
+export function follow(path, options = {}) {
+    const { backfill = 0, interval = 2000, signal, onError } = options;
+    const block = new Uint8Array(blockSize);
+    let handle = null, inode = null, position = 0, stopped = false, watcher = null, wake = Promise.withResolvers();
+    let catchUp = existsSync(path);
+    function notify() {
+        wake.resolve();
+        wake = Promise.withResolvers();
+    }
+    function attachWatcher() {
+        if (watcher || stopped)
+            return;
+        try {
+            watcher = watch(dirname(path), (_event, name) => {
+                if (!name || name === basename(path))
+                    notify();
+            });
+            watcher.on('error', () => { });
+        }
+        catch {
+            // No directory yet; the poll finds the file once it appears.
+        }
+    }
+    const timer = setInterval(notify, interval).unref();
+    function stop() {
+        stopped = true;
+        watcher?.close();
+        watcher = null;
+        clearInterval(timer);
+        void handle?.close().catch(() => { });
+        handle = null;
+        notify();
+    }
+    signal?.addEventListener('abort', stop, { once: true });
+    /** Open the file, reopening it when it has been rotated or truncated. */
+    async function reopen() {
+        const stats = await stat(path).catch(() => null);
+        if (!stats)
+            return;
+        if (handle && stats.ino === inode && stats.size >= position)
+            return;
+        await handle?.close().catch(() => { });
+        handle = await open(path, 'r');
+        attachWatcher();
+        const opened = await handle.stat();
+        inode = opened.ino;
+        position = catchUp ? await backfillOffset(handle, opened.size, backfill) : 0;
+        catchUp = false;
+    }
+    attachWatcher();
+    return new ReadableStream({
+        async pull(controller) {
+            while (!stopped) {
+                try {
+                    await reopen();
+                    if (handle) {
+                        const { bytesRead } = await handle.read(block, 0, block.length, position);
+                        if (bytesRead > 0) {
+                            position += bytesRead;
+                            controller.enqueue(block.slice(0, bytesRead));
+                            return;
+                        }
+                    }
+                }
+                catch (error) {
+                    if (!onError)
+                        throw error;
+                    onError(error);
+                }
+                await wake.promise;
+            }
+            controller.close();
+        },
+        cancel: stop,
+    });
+}
+/** Follow a file, emitting each line appended to it. */
+export function tail(path, options) {
+    return toLines(follow(path, options));
+}
+export const levelColors = {
+    TRACE: 'gray',
+    DEBUG: 'magenta',
+    INFO: 'cyan',
+    WARN: 'yellowBright',
+    ERROR: 'red',
+    FATAL: 'redBright',
+};
+// Command feedback broadcast, `[Rcon: ...]`.
+const feedbackPattern = /^\[\w+:\s.*\]$/;
+// Chat, e.g. `<Notch> hi`. The trailing `>` and space keep this from matching `<--[HERE]`.
+const chatPattern = /^(<\w+>)(\s.*)$/;
+function formatMessage(message) {
+    if (feedbackPattern.test(message))
+        return styleText(['italic', 'dim'], message);
+    const chat = chatPattern.exec(message);
+    if (chat)
+        return styleText('bold', chat[1]) + chat[2];
+    return message;
+}
+export function format(line) {
+    const parsed = typeof line == 'object' && line !== null ? line : parse(line);
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    if (!parsed)
+        return String(line);
+    const { timestamp, thread, level, message } = parsed;
+    return [styleText('gray', `[${timestamp}]`), styleText(levelColors[level], `[${thread}/${level}]:`), formatMessage(message)].join(' ');
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import * as io from 'ioium/node';
+import cli from './cli.js';
+try {
+    await cli.parseAsync();
+}
+catch (e) {
+    io.exit(e);
+}

package/dist/nbt.d.ts

@@ -0,0 +1 @@
+export * from './common/nbt.js';

package/dist/nbt.js

@@ -0,0 +1 @@
+export * from './common/nbt.js';

package/dist/prune.d.ts

@@ -0,0 +1,85 @@
+import { Dimension, type RegionFile } from './level.js';
+import { EventEmitter } from 'node:events';
+export type ExcludeReason = 'excluded' | 'unreadable' | 'inhabited' | 'conflict';
+export interface MoveInfo {
+    src: string;
+    dest: string;
+    /** The destination already holds an identical file, so the source is dropped rather than moved. */
+    duplicate: boolean;
+    /** The destination holds a different file that this one replaces. */
+    overwrite: boolean;
+}
+export interface Region extends RegionFile {
+    dimension: Dimension;
+    /** The size of the region's files in bytes */
+    size: number;
+    /** How many chunks the region stores. */
+    chunks: number;
+    /** How many chunks that could not be parsed. */
+    unreadable: number;
+    /** The longest players have spent in any one chunk. */
+    inhabitedTicks: bigint;
+    keep?: ExcludeReason | null;
+    moves: MoveInfo[];
+    deletes: string[];
+    error?: Error;
+}
+export interface ExecuteOptions {
+    /** How many regions operate on at once. */
+    concurrency?: number;
+    /** Whether the first failure stops the transaction, leaving the remaining regions untouched. */
+    atomic?: boolean;
+}
+export declare const conflictModes: readonly ["throw", "exclude", "overwrite", "preserve"];
+export type ConflictMode = (typeof conflictModes)[number];
+export interface PrepareOptions extends ExecuteOptions {
+    /** Keep regions where players have spent at least this long in a chunk, in ticks. */
+    threshold: bigint;
+    /** Region coordinates to keep regardless of other constraints, as `<x>,<z>`, keyed by dimension id. */
+    exclude?: Readonly<Record<string, readonly string[]>>;
+    /** Delete the files instead of moving them. */
+    delete?: boolean;
+    /**
+     * Where moved files go.
+     * Relative paths are to the region directory, absolute paths will mirror the world directory layout
+     * @default 'old'
+     */
+    into?: string | null;
+    /**
+     * How to handle conflicts when moving regions
+     * - throw: emit an error for the given region, stopping the transaction when `atomic` is also set
+     * - exclude: the region will not be pruned
+     * - overwrite: the old region will be overwritten with the new one
+     * - preserve: the old region will be kept and the new one will be deleted (you probably do not want this)
+     * @default 'throw'
+     */
+    conflicting?: ConflictMode;
+}
+export interface Result {
+    pruned: Region[];
+    /** Bytes of region data removed. */
+    freed: number;
+    failed: {
+        region: Region;
+        error: Error;
+    }[];
+    /** Regions left untouched because an earlier failure stopped an atomic transaction. */
+    skipped: Region[];
+}
+export declare class Transaction extends EventEmitter<{
+    prepare_error: [error: Error, file: RegionFile];
+    prepare_exclude: [reason: ExcludeReason, region: Region];
+    execute_error: [error: Error, region: Region];
+}> {
+    #private;
+    readonly path: string;
+    readonly regions: Region[];
+    /** *All* of the regions, including excluded ones. */
+    readonly allRegions: Region[];
+    constructor(path: string);
+    get pruneSize(): number;
+    get isEmpty(): boolean;
+    get isPrepared(): boolean;
+    prepare(options: PrepareOptions): Promise<void>;
+    execute(options?: ExecuteOptions): Promise<Result>;
+}

package/dist/prune.js

@@ -0,0 +1,201 @@
+import * as fs from 'node:fs';
+import { dirname, isAbsolute, join, relative } from 'node:path';
+import { get, TagType } from './common/nbt.js';
+import { Dimension, isLevel, Level, normalizeId } from './level.js';
+import { Region as RegionData } from './region.js';
+import { concurrent, exists, filesIdentical, moveFile } from './utils.js';
+import { EventEmitter } from 'node:events';
+export const conflictModes = ['throw', 'exclude', 'overwrite', 'preserve'];
+export class Transaction extends EventEmitter {
+    path;
+    regions = [];
+    /** *All* of the regions, including excluded ones. */
+    allRegions = [];
+    constructor(path) {
+        super({ captureRejections: true });
+        this.path = path;
+    }
+    get pruneSize() {
+        return this.regions.reduce((sum, r) => sum + r.size, 0);
+    }
+    get isEmpty() {
+        return !this.regions.length;
+    }
+    #started = false;
+    #prepared = false;
+    get isPrepared() {
+        return this.#prepared;
+    }
+    async prepare(options) {
+        if (this.#started)
+            throw new Error('Transaction already prepared');
+        this.#started = true;
+        const isForLevel = await isLevel(this.path);
+        const dimensions = isForLevel
+            ? await new Level(this.path).dimensions()
+            : (await exists(join(this.path, 'region')))
+                ? [Dimension.at(this.path)]
+                : [];
+        if (!dimensions.length)
+            throw new Error('Transaction path does not match any dimensions');
+        const into = options.into ?? 'old';
+        for (const dimension of dimensions) {
+            const excluded = new Set(options.exclude?.[normalizeId(dimension.id)]);
+            await concurrent(await dimension.regionFiles(), options.concurrency ?? 4, async (file) => {
+                try {
+                    const region = new RegionData(await fs.promises.readFile(file.path), file);
+                    const stored = Array.from(region.entries()).length;
+                    let readable = 0, inhabitedTicks = 0n;
+                    for await (const chunk of region.chunks()) {
+                        readable++;
+                        const tag = get(chunk.tag, 'InhabitedTime');
+                        if (tag?.type === TagType.Long && tag.value > inhabitedTicks)
+                            inhabitedTicks = tag.value;
+                    }
+                    const unreadable = stored - readable;
+                    let keep = excluded.has(`${region.file.x},${region.file.z}`)
+                        ? 'excluded'
+                        : unreadable
+                            ? 'unreadable'
+                            : inhabitedTicks >= options.threshold
+                                ? 'inhabited'
+                                : null;
+                    const files = await dimension.regionFilesAt(region.file.x, region.file.z);
+                    const txRegion = {
+                        ...region.file,
+                        dimension,
+                        size: 0,
+                        chunks: stored,
+                        unreadable,
+                        inhabitedTicks,
+                        keep,
+                        moves: [],
+                        deletes: [],
+                    };
+                    this.allRegions.push(txRegion);
+                    if (keep) {
+                        this.emit('prepare_exclude', keep, txRegion);
+                        return;
+                    }
+                    await Promise.all(files.map(async (file) => {
+                        await fs.promises.access(dirname(file.path), fs.constants.W_OK | fs.constants.X_OK);
+                        const { size } = await fs.promises.stat(file.path);
+                        if (options.delete) {
+                            txRegion.deletes.push(file.path);
+                            txRegion.size += size;
+                        }
+                        else {
+                            const dest = isAbsolute(into)
+                                ? join(into, isForLevel ? relative(dimension.level, dimension.path) : '', file.kind, file.name)
+                                : join(dimension.path, file.kind, into, file.name);
+                            try {
+                                if (await filesIdentical(file.path, dest)) {
+                                    txRegion.moves.push({ src: file.path, dest, duplicate: true, overwrite: false });
+                                    txRegion.size += size;
+                                    return;
+                                }
+                                switch (options.conflicting) {
+                                    case 'exclude':
+                                        keep = 'conflict';
+                                        break;
+                                    case 'preserve':
+                                        txRegion.deletes.push(file.path);
+                                        txRegion.size += size;
+                                        break;
+                                    case 'overwrite':
+                                        txRegion.moves.push({ src: file.path, dest, duplicate: false, overwrite: true });
+                                        txRegion.size += size;
+                                        break;
+                                    case 'throw':
+                                    default:
+                                        throw new Error(`destination exists and differs: ${dest}`);
+                                }
+                            }
+                            catch (e) {
+                                if (e.code !== 'ENOENT')
+                                    throw e;
+                                txRegion.size += size;
+                                txRegion.moves.push({ src: file.path, dest, duplicate: false, overwrite: false });
+                            }
+                        }
+                    }));
+                    if (keep) {
+                        Object.assign(txRegion, { keep, size: 0, moves: [], deletes: [] });
+                        this.emit('prepare_exclude', keep, txRegion);
+                        return;
+                    }
+                    this.regions.push(txRegion);
+                }
+                catch (e) {
+                    if (options.atomic)
+                        throw e;
+                    this.emit('prepare_error', e, file);
+                }
+            });
+        }
+        const order = new Map(dimensions.map((dimension, index) => [dimension, index]));
+        const compare = (a, b) => order.get(a.dimension) - order.get(b.dimension) || a.x - b.x || a.z - b.z;
+        this.regions.sort(compare);
+        this.allRegions.sort(compare);
+        this.#prepared = true;
+    }
+    /**
+     * Apply one region's plan with rollback on failure
+     */
+    async #executeRegion(region) {
+        const moved = [];
+        try {
+            for (const move of region.moves) {
+                if (move.duplicate)
+                    continue;
+                await moveFile(move.src, move.dest, move.overwrite);
+                moved.push(move);
+            }
+        }
+        catch (error) {
+            for (const move of moved.reverse())
+                await moveFile(move.dest, move.src, true).catch(() => { });
+            throw error;
+        }
+        for (const move of region.moves)
+            if (move.duplicate)
+                await fs.promises.rm(move.src);
+        for (const path of region.deletes)
+            await fs.promises.rm(path);
+    }
+    async execute(options = {}) {
+        if (!this.#prepared)
+            throw new Error('Transaction is not prepared');
+        const result = { pruned: [], freed: 0, failed: [], skipped: [] };
+        let stopped = false;
+        const errors = await concurrent(this.regions, options.concurrency ?? 4, async (region) => {
+            if (stopped)
+                return 'skipped';
+            try {
+                await this.#executeRegion(region);
+                return null;
+            }
+            catch (error) {
+                if (options.atomic)
+                    stopped = true;
+                return error;
+            }
+        });
+        for (const [index, error] of errors.entries()) {
+            const region = this.regions[index];
+            if (error === 'skipped') {
+                result.skipped.push(region);
+            }
+            else if (error) {
+                region.error = error;
+                this.emit('execute_error', error, region);
+                result.failed.push({ region, error });
+            }
+            else {
+                result.pruned.push(region);
+                result.freed += region.size;
+            }
+        }
+        return result;
+    }
+}

package/dist/rcon.d.ts

@@ -0,0 +1,12 @@
+export * from './common/rcon.js';
+import { type Socket, type TcpSocketConnectOpts } from 'node:net';
+import { Connection, type ConnectionOptions } from './common/rcon.js';
+export interface ConnectOptions extends ConnectionOptions, TcpSocketConnectOpts {
+}
+/**
+ * Connect to an RCON server.
+ * You will need to authenticate before sending any commands!
+ */
+export declare function connect(options: ConnectOptions): Promise<Connection & {
+    socket: Socket;
+}>;

package/dist/rcon.js

@@ -0,0 +1,19 @@
+export * from './common/rcon.js';
+import { connect as connectSocket } from 'node:net';
+import { Connection } from './common/rcon.js';
+import { Duplex } from 'node:stream';
+/**
+ * Connect to an RCON server.
+ * You will need to authenticate before sending any commands!
+ */
+export async function connect(options) {
+    const socket = connectSocket(options);
+    socket.setNoDelay(true);
+    const opened = Promise.withResolvers();
+    socket.once('error', opened.reject);
+    socket.once('connect', opened.resolve);
+    await opened.promise;
+    socket.removeAllListeners('error');
+    const connection = new Connection(Duplex.toWeb(socket), options);
+    return Object.assign(connection, { socket });
+}

package/dist/region.d.ts

@@ -0,0 +1 @@
+export * from './common/region.js';

package/dist/region.js

@@ -0,0 +1 @@
+export * from './common/region.js';

package/dist/snbt.d.ts

@@ -0,0 +1,14 @@
+export * from './common/snbt.js';
+import { type InspectColor } from 'node:util';
+import { type Tag } from './common/nbt.js';
+export declare const colors: Record<'name' | 'string' | 'number' | 'suffix', InspectColor>;
+/**
+ * A string is always enclosed by double or single quotes.
+ * If the string does not contain any quote marks, double quotes are used.
+ * If the string contains a double quote then single quotes are used, and vice versa.
+ * If the string contains both then the opposite of the first instance of either in the string is used
+ * (e.g. if a " appears before a ' then the string will be enclosed in single quotes)
+ * @see https://minecraft.wiki/w/NBT_format#Conversion_to_SNBT
+ */
+export declare function escapeString(value: string): string;
+export declare function format(tag: Tag): string;

package/dist/snbt.js

@@ -0,0 +1,63 @@
+export * from './common/snbt.js';
+import { styleText } from 'node:util';
+import { TagType } from './common/nbt.js';
+import { arrayMarkers, tagSuffixes, escapes } from './common/snbt.js';
+export const colors = {
+    name: 'cyan',
+    string: 'green',
+    number: 'yellow',
+    suffix: 'red',
+};
+/** `escapes` read backwards: the letter to write for each character that needs one. */
+const escaped = new Map(Object.entries(escapes)
+    .filter(([letter]) => letter != 's')
+    .map(([letter, char]) => [char, letter]));
+/**
+ * A string is always enclosed by double or single quotes.
+ * If the string does not contain any quote marks, double quotes are used.
+ * If the string contains a double quote then single quotes are used, and vice versa.
+ * If the string contains both then the opposite of the first instance of either in the string is used
+ * (e.g. if a " appears before a ' then the string will be enclosed in single quotes)
+ * @see https://minecraft.wiki/w/NBT_format#Conversion_to_SNBT
+ */
+export function escapeString(value) {
+    const double = value.indexOf('"'), single = value.indexOf("'");
+    const quote = double == -1 ? '"' : single == -1 ? "'" : double < single ? "'" : '"';
+    let out = quote;
+    for (const char of value) {
+        if (char == '\\' || char == quote) {
+            out += '\\' + char;
+            continue;
+        }
+        const escape = escaped.get(char);
+        if (escape) {
+            out += '\\' + escape;
+            continue;
+        }
+        const code = char.codePointAt(0);
+        out += code < 0x20 || (code >= 0x7f && code <= 0x9f) ? '\\u' + code.toString(16).padStart(4, '0') : char;
+    }
+    return out + quote;
+}
+const isArrayTag = (tag) => tag.type in arrayMarkers;
+function num(value, suffix) {
+    const decimal = suffix === 'f' || suffix === 'd';
+    const text = decimal && Number.isInteger(value) ? Number(value).toFixed(1) : String(value);
+    return styleText(colors.number, text) + (suffix ? styleText(colors.suffix, suffix) : '');
+}
+export function format(tag) {
+    if (tag.type == TagType.String)
+        return styleText(colors.string, escapeString(tag.value));
+    if (tag.type == TagType.Compound) {
+        const entries = Array.from(tag.value).map(([key, child]) => `${styleText(colors.name, key)}:${format(child)}`);
+        return `{${entries.join(',')}}`;
+    }
+    if (tag.type == TagType.List)
+        return `[${tag.value.map(v => format(v)).join(',')}]`;
+    if (isArrayTag(tag)) {
+        const [marker, suffix] = arrayMarkers[tag.type];
+        const items = [...tag.value].map(item => num(item, suffix));
+        return `[${styleText(colors.suffix, marker)};${items.join(',')}]`;
+    }
+    return num(tag.value, tagSuffixes[tag.type] ?? '');
+}