@james-pre/mc-admin 0.1.0

package/README.md

@@ -0,0 +1,15 @@
+# mc-admin
+
+Minecraft server administration CLI.
+
+## Install
+
+```sh
+npm install -g @james-pre/mc-admin
+```
+
+## Usage
+
+```sh
+mc-admin --help
+```

package/dist/buffers.d.ts

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

package/dist/buffers.js

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

package/dist/cli.d.ts

@@ -0,0 +1,6 @@
+import { Command } from 'commander';
+declare const cli: Command<[], {
+    config?: string | undefined;
+    world?: string | undefined;
+}, {}>;
+export default cli;

package/dist/cli.js

@@ -0,0 +1,110 @@
+import { Command, InvalidArgumentError, Option } from 'commander';
+import * as io from 'ioium/node';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { styleText } from 'node:util';
+import { _throw, pick } from 'utilium';
+import { bytes as formatBytes } from 'utilium/format';
+import $pkg from '../package.json' with { type: 'json' };
+import { config, configManager } from './config.js';
+import * as prune from './prune.js';
+const cli = new Command('mc-admin')
+    .version($pkg.version)
+    .description($pkg.description)
+    .option('-C, --config <file>', 'configuration file to use')
+    .option('-w, --world <path>', 'override the world path to use')
+    .hook('preAction', () => {
+    const opts = cli.opts();
+    if (opts.config)
+        configManager.loadFile(resolve(opts.config), {});
+    else
+        configManager.loadDefaults();
+    if (opts.world)
+        configManager.set('world_path', resolve(opts.world));
+});
+const cli_regions = cli.command('regions').alias('region');
+const secondsPattern = /^\d+(\.\d+)?$/, timeOnlyPattern = /^[\d.]+[smh]$/i;
+function seconds(val) {
+    if (secondsPattern.test(val))
+        return Number(val);
+    if (timeOnlyPattern.test(val))
+        val = 'T' + val;
+    try {
+        return Temporal.Duration.from('P' + val.toUpperCase()).total('seconds');
+    }
+    catch {
+        throw new InvalidArgumentError('expected seconds or a duration like 30s, 5m, 2h, or 1DT12H');
+    }
+}
+const excludeReasons = {
+    excluded: 'protected',
+    inhabited: 'inhabited',
+    unreadable: 'unparsed chunks',
+    conflict: 'destination conflict',
+};
+/** Kept regions are only worth reporting when the reason is something the user didn't ask for. */
+const surprising = ['unreadable', 'conflict'];
+cli_regions
+    .command('prune')
+    .description('Prune region files')
+    .option('-t, --threshold <duration>', 'keep regions with at least this much play time', seconds)
+    .addOption(new Option('--move [dir]', 'move pruned region files').conflicts('delete'))
+    .addOption(new Option('--delete', 'delete pruned region files').conflicts('move'))
+    .option('--atomic', 'Stop at the first failure, leaving the remaining regions untouched')
+    .option('-v, --verbose', 'Report every region that is kept, and why')
+    .option('--conflicting <mode>', `How to handle conflicts when moving regions (${prune.conflictModes.join(', ')})`, (val) => prune.conflictModes.includes(val)
+    ? val
+    : _throw(new InvalidArgumentError('Invalid conflict mode')), 'throw')
+    .action(async function (options) {
+    const threshold = BigInt(Math.round(options.threshold ?? config.prune_threshold) * 20); // seconds -> ticks
+    const world = resolve(config.world_path);
+    if (!existsSync(world))
+        io.exit(`invalid world directory: ${world}`);
+    const into = typeof options.move == 'string' ? resolve(options.move) : null;
+    const tx = new prune.Transaction(world)
+        .on('prepare_error', (err, file) => io.error(styleText('bold', file.path), io.errorText(err)))
+        .on('prepare_exclude', (reason, region) => {
+        if (!options.verbose && !surprising.includes(reason))
+            return;
+        const text = `${styleText('dim', region.dimension.id)} ${styleText('bold', region.name)} kept: ${excludeReasons[reason]}`;
+        if (surprising.includes(reason))
+            io.warn(text);
+        else
+            io.log(text);
+    })
+        .on('execute_error', (err, region) => {
+        io.error(styleText('dim', region.dimension.id), styleText('bold', region.name), styleText('gray', `(${region.kind})`), io.errorText(err));
+        process.exitCode = 1;
+    });
+    const pruneOpts = { threshold, exclude: config.protected_regions, into, ...pick(options, 'atomic', 'conflicting', 'delete') };
+    await tx.prepare(pruneOpts);
+    if (!tx.regions.length) {
+        io.log('Found no prunable region files.');
+        return;
+    }
+    io.setTableTargetWidth(process.stdout.columns);
+    io.table([
+        { name: 'Dimension', text: r => r.dimension.id },
+        { name: 'Region File', text: r => r.name },
+        { name: 'Chunks', text: r => r.chunks, padStart: true },
+        { name: 'Size', text: r => formatBytes(r.size), padStart: true },
+        { name: 'Max chunk time', text: r => (Number(r.inhabitedTicks) / 1200).toFixed(1) + ' min', padStart: true },
+    ], { formatHead: t => styleText('bold', t) }, tx.regions);
+    const ioRegions = styleText('blue', tx.regions.length.toString()), ioSize = styleText('blue', formatBytes(tx.pruneSize));
+    if (!options.delete && !options.move) {
+        io.log('Found', ioRegions, 'prunable regions, totaling', ioSize);
+        return;
+    }
+    io.log('About to', options.delete ? styleText('red', 'DELETE') : styleText('yellow', 'move'), ioRegions, 'regions, totaling', ioSize);
+    await io.assertYes();
+    const { pruned, freed } = await tx.execute(pruneOpts);
+    io.log(options.delete ? 'Deleted' : 'Moved', styleText('blue', pruned.length.toString()), 'regions, freeing', styleText('blue', formatBytes(freed)));
+});
+cli.command('console')
+    .alias('con')
+    .alias('rcon')
+    .alias('rc')
+    .action(function () {
+    //
+});
+export default cli;

package/dist/common/buffers.d.ts

@@ -0,0 +1,8 @@
+/** A view of the same bytes, without copying them. */
+export declare function toBytes(data: BufferSource): Uint8Array<ArrayBuffer>;
+export type CompressionFormat = 'gzip' | 'deflate' | 'deflate-raw';
+export declare function decompress(data: BufferSource, format: CompressionFormat): Promise<Uint8Array<ArrayBuffer>>;
+/** Split text into lines, holding a partial line until the rest of it arrives. */
+export declare function lines(): TransformStream<string, string>;
+/** Split a byte stream into lines of text. */
+export declare function toLines(source: ReadableStream<BufferSource>): ReadableStream<string>;

package/dist/common/buffers.js

@@ -0,0 +1,47 @@
+/** A view of the same bytes, without copying them. */
+export function toBytes(data) {
+    return ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
+}
+export async function decompress(data, format) {
+    const input = new ReadableStream({
+        start(controller) {
+            controller.enqueue(toBytes(data));
+            controller.close();
+        },
+    });
+    const reader = input.pipeThrough(new DecompressionStream(format)).getReader();
+    const parts = [];
+    let length = 0;
+    for (let next = await reader.read(); !next.done; next = await reader.read()) {
+        parts.push(next.value);
+        length += next.value.byteLength;
+    }
+    const result = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.byteLength;
+    }
+    return result;
+}
+/** Split text into lines, holding a partial line until the rest of it arrives. */
+export function lines() {
+    let partial = '';
+    return new TransformStream({
+        transform(chunk, controller) {
+            partial += chunk;
+            const parts = partial.split(/\r?\n/);
+            partial = parts.pop();
+            for (const part of parts)
+                controller.enqueue(part);
+        },
+        flush(controller) {
+            if (partial)
+                controller.enqueue(partial);
+        },
+    });
+}
+/** Split a byte stream into lines of text. */
+export function toLines(source) {
+    return source.pipeThrough(new TextDecoderStream()).pipeThrough(lines());
+}

package/dist/common/chunk.d.ts

@@ -0,0 +1,41 @@
+import type { Tag } from './nbt.js';
+export declare enum Compression {
+    GZip = 1,
+    ZLib = 2,
+    None = 3,
+    LZ4 = 4,
+    Custom = 127
+}
+/** Set on a chunk's compression byte when its payload lives in a `c.<x>.<z>.mcc` file instead. */
+export declare const externalFlag = 128;
+/** Where a chunk sits in the file, from the header alone. */
+export interface Entry {
+    /** The chunk's index in the header, `x + z * 32`. */
+    index: number;
+    /** Chunk coordinates within the region, 0 to 31. */
+    x: number;
+    z: number;
+    /** Byte offset of the chunk's record. */
+    offset: number;
+    /** Length of the chunk's allocation, in sectors. */
+    sectors: number;
+    /** When the chunk was last written, in epoch seconds; 0 if it never was. */
+    timestamp: number;
+}
+export interface Raw extends Entry {
+    compression: Compression;
+    /** The payload is in a `c.<x>.<z>.mcc` file next to the region, and `data` is empty. */
+    external: boolean;
+    /** The still-compressed NBT payload. */
+    data: Uint8Array<ArrayBuffer>;
+}
+export interface Parsed extends Raw {
+    tag: Tag;
+}
+/**
+ * Decompress a chunk's NBT payload.
+ *
+ * @throws When the chunk is external, or compressed with a scheme this can't undo — LZ4 and the
+ * `Custom` escape hatch, both of which only a modded server writes.
+ */
+export declare function payload(chunk: Raw): Promise<Uint8Array<ArrayBuffer>>;

package/dist/common/chunk.js

@@ -0,0 +1,31 @@
+import { decompress } from './buffers.js';
+export var Compression;
+(function (Compression) {
+    Compression[Compression["GZip"] = 1] = "GZip";
+    Compression[Compression["ZLib"] = 2] = "ZLib";
+    Compression[Compression["None"] = 3] = "None";
+    Compression[Compression["LZ4"] = 4] = "LZ4";
+    Compression[Compression["Custom"] = 127] = "Custom";
+})(Compression || (Compression = {}));
+/** Set on a chunk's compression byte when its payload lives in a `c.<x>.<z>.mcc` file instead. */
+export const externalFlag = 0x80;
+const formats = {
+    [Compression.GZip]: 'gzip',
+    [Compression.ZLib]: 'deflate',
+};
+/**
+ * Decompress a chunk's NBT payload.
+ *
+ * @throws When the chunk is external, or compressed with a scheme this can't undo — LZ4 and the
+ * `Custom` escape hatch, both of which only a modded server writes.
+ */
+export async function payload(chunk) {
+    if (chunk.external)
+        throw new Error(`chunk ${chunk.x},${chunk.z} is stored externally`);
+    if (chunk.compression === Compression.None)
+        return chunk.data;
+    const format = formats[chunk.compression];
+    if (!format)
+        throw new Error(`chunk ${chunk.x},${chunk.z} uses unsupported compression (${Compression[chunk.compression] ?? chunk.compression})`);
+    return await decompress(chunk.data, format);
+}

package/dist/common/index.d.ts

@@ -0,0 +1,7 @@
+export * as chunk from './chunk.js';
+export * as log from './log.js';
+export * as nbt from './nbt.js';
+export * as rcon from './rcon.js';
+export { Region } from './region.js';
+export * as region from './region.js';
+export * as snbt from './snbt.js';

package/dist/common/index.js

@@ -0,0 +1,7 @@
+export * as chunk from './chunk.js';
+export * as log from './log.js';
+export * as nbt from './nbt.js';
+export * as rcon from './rcon.js';
+export { Region } from './region.js';
+export * as region from './region.js';
+export * as snbt from './snbt.js';

package/dist/common/level.d.ts

@@ -0,0 +1,21 @@
+/** The directory each vanilla dimension uses, relative to the level root. */
+export declare const vanillaDimensions: {
+    readonly 'minecraft:overworld': "";
+    readonly 'minecraft:the_nether': "DIM-1";
+    readonly 'minecraft:the_end': "DIM1";
+};
+export declare const vanillaIds: Map<string, string>;
+/** The subdirectories a dimension splits its region files across, all on the same grid. */
+export declare const regionKinds: readonly ["region", "entities", "poi"];
+export type RegionKind = (typeof regionKinds)[number];
+/** A region file's coordinates and location on disk. */
+export interface RegionFile {
+    kind: RegionKind;
+    /** Region coordinates. */
+    x: number;
+    z: number;
+    name: string;
+    path: string;
+}
+/** A id (e.g. for dimensions) with its namespace made explicit, so ids from different sources compare equal. */
+export declare function normalizeId(id: string): string;

package/dist/common/level.js

@@ -0,0 +1,16 @@
+/** The directory each vanilla dimension uses, relative to the level root. */
+export const vanillaDimensions = {
+    'minecraft:overworld': '',
+    'minecraft:the_nether': 'DIM-1',
+    'minecraft:the_end': 'DIM1',
+};
+export const vanillaIds = new Map(Object.entries(vanillaDimensions)
+    .filter(([, dir]) => dir)
+    .map(([id, dir]) => [dir, id]));
+/** The subdirectories a dimension splits its region files across, all on the same grid. */
+export const regionKinds = ['region', 'entities', 'poi'];
+/** A id (e.g. for dimensions) with its namespace made explicit, so ids from different sources compare equal. */
+export function normalizeId(id) {
+    const lower = id.toLowerCase();
+    return lower.includes(':') ? lower : `minecraft:${lower}`;
+}

package/dist/common/log.d.ts

@@ -0,0 +1,13 @@
+export declare const logLevels: readonly ["TRACE", "DEBUG", "INFO", "WARN", "ERROR", "FATAL"];
+export type LogLevel = (typeof logLevels)[number];
+/** A server log line, `[09:46:08] [Server thread/INFO]: message`. */
+export interface LogLine {
+    /** The time of day the line was logged, as `HH:MM:SS`. */
+    timestamp: string;
+    /** The thread that logged the line. */
+    thread: string;
+    level: LogLevel;
+    message: string;
+}
+/** Parse a server log line, or null when it isn't one. */
+export declare function parse(line: string): LogLine | null;

package/dist/common/log.js

@@ -0,0 +1,10 @@
+export const logLevels = ['TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL'];
+const linePattern = new RegExp(String.raw `^\[(\d{2}:\d{2}:\d{2})\] \[([^\]]*)\/(${logLevels.join('|')})\]:\s*(.*)$`);
+/** Parse a server log line, or null when it isn't one. */
+export function parse(line) {
+    const match = linePattern.exec(line);
+    if (!match)
+        return null;
+    const [, timestamp, thread, level, message] = match;
+    return { timestamp, thread, level: level, message };
+}

package/dist/common/nbt.d.ts

@@ -0,0 +1,85 @@
+export declare enum TagType {
+    End = 0,
+    Byte = 1,
+    Short = 2,
+    Int = 3,
+    Long = 4,
+    Float = 5,
+    Double = 6,
+    ByteArray = 7,
+    String = 8,
+    List = 9,
+    Compound = 10,
+    IntArray = 11,
+    LongArray = 12
+}
+/** A compound's children, keyed by tag name. */
+export type Compound = Map<string, Tag>;
+/** The value carried by a tag of each type. */
+export interface TagValues {
+    [TagType.End]: never;
+    [TagType.Byte]: number;
+    [TagType.Short]: number;
+    [TagType.Int]: number;
+    [TagType.Long]: bigint;
+    [TagType.Float]: number;
+    [TagType.Double]: number;
+    [TagType.ByteArray]: Int8Array;
+    [TagType.String]: string;
+    [TagType.List]: Tag[];
+    [TagType.Compound]: Compound;
+    [TagType.IntArray]: Int32Array;
+    [TagType.LongArray]: BigInt64Array;
+}
+export interface TagOf<T extends TagType> {
+    type: T;
+    value: TagValues[T];
+}
+export interface ListTag extends TagOf<TagType.List> {
+    /** The type shared by every item. `End` when the list is empty. */
+    of: TagType;
+}
+/** Every type that can appear as a value. `End` only ever terminates a compound. */
+export type ValueType = Exclude<TagType, TagType.End | TagType.List>;
+export type Tag = {
+    [T in ValueType]: TagOf<T>;
+}[ValueType] | ListTag;
+/** A root tag together with its name, which is usually empty. */
+export interface Named {
+    name: string;
+    tag: Tag;
+}
+/**
+ * Walks an NBT payload one tag at a time.
+ * @internal
+ */
+export declare class Reader {
+    protected readonly view: DataView;
+    protected readonly bytes: Uint8Array;
+    offset: number;
+    constructor(data: BufferSource);
+    protected int8(): number;
+    protected uint8(): number;
+    protected int16(): number;
+    protected int32(): number;
+    protected int64(): bigint;
+    protected float32(): number;
+    protected float64(): number;
+    /** A length-prefixed name or string value. */
+    string(): string;
+    /** The type byte introducing the next tag. */
+    type(): TagType;
+    /** The body of a tag whose type byte has already been read. */
+    tag(type: TagType): Tag;
+}
+/** Parse an uncompressed NBT payload. */
+export declare function parse(data: BufferSource): Named;
+/**
+ * Parse an NBT file, decompressing it first when it needs it.
+ */
+export declare function parseCompressed(data: BufferSource): Promise<Named>;
+/**
+ * Follow a path of compound keys and list indices, giving up rather than throwing when any step
+ * is missing or the wrong type.
+ */
+export declare function get(tag: Tag | null, ...path: (string | number)[]): Tag | null;

package/dist/common/nbt.js

@@ -0,0 +1,179 @@
+import { decodeUTF8 } from 'utilium';
+import { decompress, toBytes } from './buffers.js';
+export var TagType;
+(function (TagType) {
+    TagType[TagType["End"] = 0] = "End";
+    TagType[TagType["Byte"] = 1] = "Byte";
+    TagType[TagType["Short"] = 2] = "Short";
+    TagType[TagType["Int"] = 3] = "Int";
+    TagType[TagType["Long"] = 4] = "Long";
+    TagType[TagType["Float"] = 5] = "Float";
+    TagType[TagType["Double"] = 6] = "Double";
+    TagType[TagType["ByteArray"] = 7] = "ByteArray";
+    TagType[TagType["String"] = 8] = "String";
+    TagType[TagType["List"] = 9] = "List";
+    TagType[TagType["Compound"] = 10] = "Compound";
+    TagType[TagType["IntArray"] = 11] = "IntArray";
+    TagType[TagType["LongArray"] = 12] = "LongArray";
+})(TagType || (TagType = {}));
+/**
+ * Walks an NBT payload one tag at a time.
+ * @internal
+ */
+export class Reader {
+    view;
+    bytes;
+    offset = 0;
+    constructor(data) {
+        this.bytes = toBytes(data);
+        this.view = new DataView(this.bytes.buffer, this.bytes.byteOffset, this.bytes.byteLength);
+    }
+    int8() {
+        return this.view.getInt8(this.offset++);
+    }
+    uint8() {
+        return this.view.getUint8(this.offset++);
+    }
+    int16() {
+        const value = this.view.getInt16(this.offset);
+        this.offset += 2;
+        return value;
+    }
+    int32() {
+        const value = this.view.getInt32(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    int64() {
+        const value = this.view.getBigInt64(this.offset);
+        this.offset += 8;
+        return value;
+    }
+    float32() {
+        const value = this.view.getFloat32(this.offset);
+        this.offset += 4;
+        return value;
+    }
+    float64() {
+        const value = this.view.getFloat64(this.offset);
+        this.offset += 8;
+        return value;
+    }
+    /** A length-prefixed name or string value. */
+    string() {
+        const length = this.view.getUint16(this.offset);
+        this.offset += 2;
+        if (this.offset + length > this.bytes.byteLength)
+            throw new RangeError(`string runs past the end of the payload at ${this.offset}`);
+        const value = decodeUTF8(this.bytes.subarray(this.offset, this.offset + length));
+        this.offset += length;
+        return value;
+    }
+    /** The type byte introducing the next tag. */
+    type() {
+        const type = this.uint8();
+        if (!(type in TagType))
+            throw new TypeError(`bad tag ${type} at ${this.offset - 1}`);
+        return type;
+    }
+    /** The body of a tag whose type byte has already been read. */
+    tag(type) {
+        switch (type) {
+            case TagType.Byte:
+                return { type, value: this.int8() };
+            case TagType.Short:
+                return { type, value: this.int16() };
+            case TagType.Int:
+                return { type, value: this.int32() };
+            case TagType.Long:
+                return { type, value: this.int64() };
+            case TagType.Float:
+                return { type, value: this.float32() };
+            case TagType.Double:
+                return { type, value: this.float64() };
+            case TagType.ByteArray: {
+                const length = this.int32();
+                if (this.offset + length > this.bytes.byteLength)
+                    throw new RangeError(`byte array runs past the end of the payload`);
+                const value = new Int8Array(this.bytes.slice(this.offset, this.offset + length).buffer);
+                this.offset += length;
+                return { type, value };
+            }
+            case TagType.String:
+                return { type, value: this.string() };
+            case TagType.List: {
+                const of = this.type();
+                const length = this.int32();
+                const value = [];
+                if (of !== TagType.End)
+                    for (let i = 0; i < length; i++)
+                        value.push(this.tag(of));
+                return { type, of, value };
+            }
+            case TagType.Compound: {
+                const value = new Map();
+                for (let child = this.type(); child !== TagType.End; child = this.type()) {
+                    const name = this.string();
+                    value.set(name, this.tag(child));
+                }
+                return { type, value };
+            }
+            case TagType.IntArray: {
+                const length = this.int32();
+                const value = new Int32Array(length);
+                for (let i = 0; i < length; i++)
+                    value[i] = this.int32();
+                return { type, value };
+            }
+            case TagType.LongArray: {
+                const length = this.int32();
+                const value = new BigInt64Array(length);
+                for (let i = 0; i < length; i++)
+                    value[i] = this.int64();
+                return { type, value };
+            }
+            default:
+                throw new TypeError(`${TagType[type]} is not a value at ${this.offset - 1}`);
+        }
+    }
+}
+/** Parse an uncompressed NBT payload. */
+export function parse(data) {
+    const reader = new Reader(data);
+    const type = reader.type();
+    if (type === TagType.End)
+        throw new TypeError('payload is empty');
+    return { name: reader.string(), tag: reader.tag(type) };
+}
+/**
+ * Parse an NBT file, decompressing it first when it needs it.
+ */
+export async function parseCompressed(data) {
+    const bytes = toBytes(data);
+    if (bytes[0] === 0x1f && bytes[1] === 0x8b)
+        return parse(await decompress(bytes, 'gzip'));
+    if (bytes[0] === 0x78)
+        return parse(await decompress(bytes, 'deflate'));
+    return parse(bytes);
+}
+/**
+ * Follow a path of compound keys and list indices, giving up rather than throwing when any step
+ * is missing or the wrong type.
+ */
+export function get(tag, ...path) {
+    let current = tag;
+    for (const key of path) {
+        if (!current)
+            return null;
+        if (typeof key === 'number') {
+            if (current.type !== TagType.List)
+                return null;
+            current = current.value[key];
+            continue;
+        }
+        if (current.type !== TagType.Compound)
+            return null;
+        current = current.value.get(key) ?? null;
+    }
+    return current;
+}