@matter/cli-tool 0.11.0-alpha.0-20241013-d38e934bb

package/src/commands/ls.ts

@@ -0,0 +1,232 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { bin } from "#globals.js";
+import { Location } from "#location.js";
+import colors from "ansi-colors";
+import { stdout } from "process";
+import yargs from "yargs";
+
+bin.ls = async function (...rawArgs: unknown[]) {
+    const args = await yargs(rawArgs.map(arg => `${arg}`))
+        .usage("Show available objects (objects in the current path by default)")
+        .option("l", { type: "boolean", description: "use a long listing format" })
+        .exitProcess(false)
+        .parse();
+
+    const locations = Array<DisplayLocation>();
+    for (const str of args._) {
+        const input = `${str}`;
+        locations.push(DisplayLocation(await this.location.at(input), input));
+    }
+
+    const files = Array<DisplayLocation>();
+    const dirs = Array<DisplayLocation>();
+
+    if (locations.length) {
+        for (const location of locations) {
+            if (location.kind === "directory") {
+                dirs.push(location);
+            } else {
+                files.push(location);
+            }
+        }
+    } else {
+        for (const basename of await this.location.paths) {
+            files.push(DisplayLocation(await this.location.at(basename)));
+        }
+    }
+
+    let displayedSomething = false;
+
+    if (files.length) {
+        display(files, "");
+        displayedSomething = true;
+    }
+
+    for (const dir of dirs) {
+        if (displayedSomething) {
+            stdout.write("\n");
+        }
+        let linePrefix;
+        if (displayedSomething || dirs.length > 1) {
+            stdout.write(`${dir.displayName ?? dir.basename}:\n`);
+            linePrefix = "  ";
+        } else {
+            linePrefix = "";
+        }
+        display(
+            (await Promise.all((await dir.paths).map(path => dir.at(path)))).map(location => DisplayLocation(location)),
+            linePrefix,
+        );
+    }
+
+    function display(files: DisplayLocation[], linePrefix: string) {
+        if (args.l) {
+            displayList(files, linePrefix);
+        } else {
+            const { grid, colWidth } = gridFor(files, linePrefix);
+            displayGrid(grid, colWidth, linePrefix);
+        }
+    }
+
+    function displayList(files: DisplayLocation[], linePrefix: string) {
+        for (const location of files) {
+            const { name, length } = formatName(location);
+
+            let charsAvailable = stdout.columns ?? 80;
+
+            const { name: longName, tag } = location;
+
+            stdout.write(linePrefix);
+            stdout.write(name);
+            stdout.write(" ");
+            stdout.write(colors.dim(tag));
+            charsAvailable -= length + tag.length + linePrefix.length + 1;
+
+            let { id, summary } = location;
+
+            if (id !== undefined) {
+                id = `#${id}`;
+                stdout.write(colors.dim(id));
+                charsAvailable -= id.length + 1;
+            }
+
+            if (longName) {
+                stdout.write(' "');
+                stdout.write(colors.cyan(longName));
+                stdout.write('"');
+                charsAvailable -= longName.length + 3;
+            }
+
+            if (summary !== undefined && charsAvailable > 10) {
+                stdout.write(" ");
+                charsAvailable -= 1;
+
+                summary = summary.split("\n")[0].trim();
+                if (summary.length > charsAvailable) {
+                    summary = summary.slice(0, charsAvailable - 1) + "…";
+                }
+
+                stdout.write(summary);
+            }
+            stdout.write("\n");
+        }
+    }
+
+    function gridFor(files: DisplayLocation[], linePrefix: string) {
+        const columns = (stdout.columns ?? 80) - linePrefix.length;
+
+        // Maximum width of columns + 1 for special char and +2 for between columns
+        const maxWidth = maxWidthOf(files) + 3;
+
+        let colCount = Math.floor(columns / maxWidth);
+        if (colCount === 0) {
+            colCount = 1;
+        }
+
+        const rowCount = Math.ceil(files.length / colCount);
+
+        const grid = Array<DisplayLocation[]>();
+
+        for (let i = 0; i < files.length; i++) {
+            const colNum = Math.floor(i / rowCount);
+            const rowNum = i - colNum * rowCount;
+            (grid[rowNum] ??= [])[colNum] = files[i];
+        }
+
+        const colWidth = Math.floor(columns / colCount);
+
+        return { grid, colWidth };
+    }
+
+    function displayGrid(grid: Array<DisplayLocation[]>, colWidth: number, linePrefix: string) {
+        for (const row of grid) {
+            stdout.write(linePrefix);
+            for (const location of row) {
+                const { name, length } = formatName(location);
+                stdout.write(name);
+                stdout.write("".padStart(colWidth - length));
+            }
+            stdout.write("\n");
+        }
+    }
+
+    function formatName(location: DisplayLocation) {
+        const name = location.displayName ?? location.basename;
+        const length = name.length;
+
+        if (location.kind === "directory") {
+            return { name: `${colors.blue(name)}/`, length: length + 1 };
+        }
+
+        if (location.kind === "command") {
+            return { name: `${colors.green(name)}*`, length: length + 1 };
+        }
+
+        return { name, length };
+    }
+
+    function maxWidthOf(locations: DisplayLocation[]) {
+        return Math.max(...locations.map(file => (file.displayName ?? file.basename).length));
+    }
+};
+
+export interface DisplayLocation extends Location {
+    displayName: string;
+}
+
+function DisplayLocation(location: Location, displayName?: string): DisplayLocation {
+    return {
+        get kind() {
+            return location.kind;
+        },
+
+        get basename() {
+            return location.basename;
+        },
+
+        get name() {
+            return location.name;
+        },
+
+        get id() {
+            return location.id;
+        },
+
+        get path() {
+            return location.path;
+        },
+
+        get paths() {
+            return location.paths;
+        },
+
+        get tag() {
+            return location.tag;
+        },
+
+        get summary() {
+            return location.summary;
+        },
+
+        get definition() {
+            return location.definition;
+        },
+
+        get displayName() {
+            return displayName ?? location.basename;
+        },
+
+        get at() {
+            return location.at;
+        },
+
+        get maybeAt() {
+            return location.maybeAt;
+        },
+    };
+}

package/src/commands/rm.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InvalidArgumentError } from "#errors.js";
+import { bin } from "#globals.js";
+import { Location } from "#location.js";
+
+bin.rm = async function (...paths: unknown[]) {
+    const toDelete = Array<Location>();
+
+    for (const path of paths) {
+        const location = await this.location.at(`${path}`);
+        if (!location.parent) {
+            throw new InvalidArgumentError(`Invalid argument: Can't delete ${location.path}`);
+        }
+        toDelete.push(location);
+    }
+
+    for (const location of toDelete) {
+        delete (location.parent!.definition as Record<string, unknown>)[location.basename];
+    }
+};

package/src/commands/set.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InvalidArgumentError, TooManyArgsError } from "#errors.js";
+import { bin } from "#globals.js";
+import { Environment, VariableService } from "@matter/general";
+
+bin.set = function (keyOrAssignment: unknown, value: unknown) {
+    switch (arguments.length) {
+        case 0:
+            return Environment.default.vars.vars;
+
+        case 1:
+            const assignment = `${keyOrAssignment}`;
+            const equalPos = assignment.indexOf("=");
+            if (equalPos === -1) {
+                throw new InvalidArgumentError(`Invalid argument: parameter must be of the form key=value`);
+            }
+            Environment.default.vars.set(assignment.slice(0, equalPos), assignment.slice(equalPos + 1));
+            break;
+
+        case 2:
+            Environment.default.vars.set(`${keyOrAssignment}`, value as VariableService.Value);
+            break;
+
+        default:
+            throw new TooManyArgsError("set");
+    }
+};

package/src/domain.ts

@@ -0,0 +1,221 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { BadCommandError, IncompleteError, NotACommandError, NotADirectoryError, NotFoundError } from "#errors.js";
+import { InternalError, MaybePromise } from "#general";
+import { bin, globals as defaultGlobals } from "#globals.js";
+import { Location } from "#location.js";
+import { parseInput } from "#parser.js";
+import { Directory } from "#stat.js";
+import { createContext, runInContext, RunningCodeOptions } from "vm";
+
+export interface Domain {
+    location: Location;
+    execute(input: string): Promise<unknown>;
+}
+
+/**
+ * Maintains state and executes commands.
+ */
+export function Domain(): Domain {
+    const hiddenGlobals = Object.keys(globalThis);
+
+    const globals: Record<string, unknown> = Object.defineProperties(
+        {},
+        {
+            ...Object.getOwnPropertyDescriptors(globalThis),
+            ...Object.getOwnPropertyDescriptors(defaultGlobals),
+            bin: { value: { ...bin }, enumerable: true, writable: false, configurable: false },
+        },
+    );
+
+    globals.global = globals.globalThis = globals;
+
+    const domain: Domain = {
+        location: Location(
+            "",
+            globals,
+            Directory({
+                paths() {
+                    const result = new Set(Object.keys(globals));
+                    for (const name of hiddenGlobals) {
+                        result.delete(name);
+                    }
+                    return [...result];
+                },
+
+                definitionAt(path: string) {
+                    // Crypto has specialized constraints on its "this"
+                    if (path === "crypto") {
+                        return globalThis.crypto;
+                    }
+                    return globals[path];
+                },
+            }),
+            undefined,
+        ),
+
+        async execute(inputStr: string) {
+            const input = parseInput(inputStr);
+
+            switch (input.kind) {
+                case "empty":
+                    return;
+
+                case "incomplete":
+                    throw new IncompleteError(input.error);
+
+                case "command":
+                    break;
+
+                case "statement":
+                    return await evaluate(input.js);
+
+                default:
+                    throw new InternalError(`Unknown internal command type ${(input as any).kind}`);
+            }
+
+            const { name, args } = input;
+
+            let location;
+            try {
+                location = await this.location.at(name);
+            } catch (e) {
+                if ((e instanceof NotFoundError || e instanceof NotADirectoryError) && name.indexOf("/") === -1) {
+                    // "path" search
+                    try {
+                        location = await this.location.at(Location.join("/bin", name));
+                    } catch (e2) {
+                        if (e instanceof NotFoundError || e instanceof NotADirectoryError) {
+                            // Throw original error
+                            throw e;
+                        }
+                        throw e2;
+                    }
+                } else {
+                    throw e;
+                }
+            }
+
+            const fn = location?.definition;
+
+            if (location === undefined || fn === undefined) {
+                throw new NotACommandError(name);
+            }
+
+            if (typeof fn !== "function") {
+                if (args.length) {
+                    // If there are arguments it must be a call; otherwise it's just inspection
+                    throw new BadCommandError(name);
+                }
+                return fn;
+            }
+
+            const argvals = args.map(arg => {
+                return evaluate(arg.js, {
+                    lineOffset: arg.line - 1,
+                    columnOffset: arg.column,
+                });
+            });
+
+            let scope = location.parent?.definition ?? globals;
+            if (scope === globals.bin) {
+                scope = this;
+            }
+
+            return fn.apply(scope, argvals);
+        },
+    };
+
+    const context = createContext(
+        new Proxy(
+            {},
+            {
+                get(_target, key, _receiver) {
+                    if (!(typeof key === "string")) {
+                        return;
+                    }
+                    const value = domain.location.maybeAt(key);
+
+                    if (MaybePromise.is(value)) {
+                        return value.then(value => {
+                            if (value === undefined) {
+                                return globals[key];
+                            }
+                            return value.definition;
+                        });
+                    }
+
+                    if (value === undefined) {
+                        return globals[key];
+                    }
+
+                    return value.definition;
+                },
+
+                set(target, key, newValue, _receiver) {
+                    const { definition } = domain.location;
+                    if (definition === undefined || definition === null) {
+                        // Shouldn't happen
+                        return false;
+                    }
+                    target = definition;
+                    (target as any)[key] = newValue;
+                    return true;
+                },
+
+                has(_target, key) {
+                    const { definition } = domain.location;
+                    if (definition === undefined || definition === null || typeof definition !== "object") {
+                        // Shouldn't happen
+                        return false;
+                    }
+                    return key in definition;
+                },
+
+                defineProperty(_target, property, attributes) {
+                    Object.defineProperty(domain.location.definition, property, attributes);
+                    return true;
+                },
+
+                deleteProperty(_target, property) {
+                    const { definition } = domain.location;
+                    if (definition === undefined || definition === null) {
+                        // Shouldn't happen
+                        return false;
+                    }
+                    Reflect.deleteProperty(definition, property);
+                    return true;
+                },
+
+                ownKeys(_target) {
+                    return [
+                        ...new Set([...Reflect.ownKeys(globals), ...Reflect.ownKeys(domain.location.definition as {})]),
+                    ];
+                },
+
+                getOwnPropertyDescriptor(_target, p) {
+                    const descriptor = Reflect.getOwnPropertyDescriptor(domain.location.definition as {}, p);
+                    if (descriptor) {
+                        return descriptor;
+                    }
+                    return Reflect.getOwnPropertyDescriptor(globals, p);
+                },
+            },
+        ),
+    );
+
+    return domain;
+
+    function evaluate(js: string, options: RunningCodeOptions = {}) {
+        return runInContext(js, context, {
+            breakOnSigint: true,
+            filename: "matter-cli-eval",
+            displayErrors: false,
+            ...options,
+        });
+    }
+}

package/src/errors.ts

@@ -0,0 +1,54 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError } from "#general";
+
+export class CliError extends MatterError {
+    // Error class won't be the same across vm contexts so make detection easier
+    isCliError = true;
+}
+
+export class NotFoundError extends CliError {
+    constructor(what: unknown) {
+        super(`Not found: ${what}`);
+    }
+}
+
+export class NotADirectoryError extends CliError {
+    constructor(what: unknown) {
+        super(`Not a directory: ${what}`);
+    }
+}
+
+export class BadCommandError extends CliError {
+    constructor(what: unknown) {
+        super(`Bad command: ${what}`);
+    }
+}
+
+export class NotACommandError extends CliError {
+    constructor(what: unknown) {
+        super(`Not a command: ${what}`);
+    }
+}
+
+export class TooManyArgsError extends CliError {
+    constructor(what: string) {
+        super(`Too many arguments: ${what}`);
+    }
+}
+
+export class InvalidArgumentError extends CliError {}
+
+/**
+ * Thrown when statement appears incomplete and REPL should wait for more input.
+ */
+export class IncompleteError extends Error {
+    constructor(cause: Error) {
+        super(cause.message, { cause });
+        this.cause = cause;
+    }
+}

package/src/globals.ts

@@ -0,0 +1,29 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Domain } from "#domain.js";
+import * as general from "#general";
+import * as model from "#model";
+import { Matter as matter } from "#model";
+import * as node from "#node";
+import * as protocol from "#protocol";
+import * as tools from "#tools";
+import * as types from "#types";
+
+export type GlobalCommand = (this: Domain, ...args: unknown[]) => unknown;
+
+export const bin: Record<string, GlobalCommand> = {};
+
+export const globals: Record<string, unknown> = {
+    general,
+    tools,
+    protocol,
+    node,
+    types,
+    matter,
+    model,
+    bin,
+};