pivotkit-cli 0.0.0-stage → 0.1.0

package/src/errors.js

@@ -0,0 +1,66 @@
+/*
+ * The CLI's errors and how each ends: a CliError has a kind (what went wrong, for scripts) and is
+ * exit code 2; a view's findings are exit code 1 (cli.js). No message holds the content of a file:
+ * a path is named by its base name, and text from a file or a view is cleaned before it is printed.
+ */
+
+import { basename } from "node:path";
+import { PivotkitError } from "pivotkit-core";
+import { cleanText } from "pivotkit-core/import";
+
+/** @typedef {"usage" | "io" | "limit" | "template" | "internal"} ErrorKind */
+
+export class CliError extends Error {
+    /**
+     * @param {ErrorKind} kind
+     * @param {string} code  a stable name, e.g. NOT_FOUND, OUTSIDE_ALLOWED_DIR, UNKNOWN_OPTION
+     * @param {string} message
+     */
+    constructor(kind, code, message) {
+        super(message);
+        this.name = "CliError";
+        this.kind = kind;
+        this.code = code;
+    }
+}
+
+/** The most characters of a name or message from outside that the CLI prints. */
+export const PRINT_LENGTH = 200;
+
+/** Text from a file, a view or the data, safe to print: no control or direction characters, capped. */
+export function printable(text) {
+    const clean = cleanText(String(text ?? ""));
+    return clean.length > PRINT_LENGTH ? `${clean.slice(0, PRINT_LENGTH - 1)}…` : clean;
+}
+
+/** A path as messages name it: its base name only. */
+export const shortName = (path) => printable(path === "-" ? "stdin" : basename(String(path)));
+
+/**
+ * Any error as a CliError: pivotkit-core's by their code, Node's file errors by theirs (with the
+ * file's base name, never its content), anything else as internal.
+ * @param {unknown} error
+ * @param {string} [path]  the file it is about
+ * @returns {CliError}
+ */
+export function asCliError(error, path) {
+    if (error instanceof CliError) {
+        return error;
+    }
+    const name = path ? shortName(path) : "";
+    if (error instanceof PivotkitError) {
+        const code = /** @type {string} */ (error.code);
+        // a reader over a limit throws LIMIT_EXCEEDED; pivotkit-xlsx 0.1.0 threw INVALID_FILE with reason
+        // LIMIT and details.limit, and a host may still have it installed next to this CLI
+        const overLimit = code === "LIMIT_EXCEEDED" || (code === "INVALID_FILE" && (error.details?.reason === "LIMIT" || typeof error.details?.limit === "string"));
+        const kind = overLimit ? "limit" : code === "INVALID_TEMPLATE" ? "template" : code === "INVALID_FILE" ? "io" : code === "INVALID_OPTION" ? "usage" : "internal";
+        const reason = typeof error.details?.reason === "string" ? error.details.reason : code;
+        return new CliError(kind, reason, printable(name && !error.message.includes(name) ? `${name}: ${error.message}` : error.message));
+    }
+    const e = /** @type {NodeJS.ErrnoException} */ (error);
+    const fileErrors = { ENOENT: "not found", EACCES: "not allowed to read or write", EPERM: "not allowed to read or write", EISDIR: "is a directory", ENOTDIR: "a part of the path is not a directory", ELOOP: "is a symbolic link", EEXIST: "exists", ENOSPC: "no space left on the disk", EROFS: "the file system is read-only" };
+    if (e && typeof e.code === "string" && Object.hasOwn(fileErrors, e.code)) {
+        return new CliError("io", e.code, `${name || "file"}: ${fileErrors[e.code]}`);
+    }
+    return new CliError("internal", "INTERNAL", printable(e && e.message ? e.message : String(error)));
+}

package/src/help.js

@@ -0,0 +1,116 @@
+/*
+ * The help texts and the shell completions, both made from the command table (commands.js).
+ */
+
+import { COMMANDS, GLOBAL_OPTIONS, SHELLS, optionsOf } from "./commands.js";
+
+/** One option as the help writes it: "-o, --output <file>". */
+function optionLine(name, spec) {
+    const flag = `${spec.short ? `-${spec.short}, ` : "    "}--${name}${spec.type === "string" ? ` <${spec.value ?? "value"}>` : ""}`;
+    const choices = spec.choices ? ` (${spec.choices.join(", ")})` : "";
+    const env = spec.env ? ` [env ${spec.env}]` : "";
+    return { flag, text: `${spec.text}${choices}${env}` };
+}
+
+/** Lines of two columns, the first padded. */
+const columns = (rows) => {
+    const width = Math.min(32, Math.max(...rows.map((r) => r.flag.length)));
+    return rows.map((r) => `  ${r.flag.padEnd(width)}  ${r.text}`).join("\n");
+};
+
+/** The help of pivotkit, or of one command. */
+export function helpText(command) {
+    if (!command || !Object.hasOwn(COMMANDS, command)) {
+        const list = Object.entries(COMMANDS).map(([name, c]) => ({ flag: name, text: c.text }));
+        return `pivotkit - run pivotkit views without a browser\n\nUsage: pivotkit <command> [options]\n\nCommands:\n${columns(list)}\n\nOptions:\n${columns([...Object.entries(GLOBAL_OPTIONS).map(([n, s]) => optionLine(n, s)), { flag: "    --version", text: "Show the versions of pivotkit-cli, pivotkit-report and pivotkit-core." }])}\n\nExit codes: 0 done, 1 findings (errors in the view, or warnings with --strict), 2 usage, file, limit or template errors.\nRun "pivotkit help <command>" for a command's options. Documentation: https://pivotkit.eize.dev/reference/cli/\n`;
+    }
+    const c = COMMANDS[command];
+    const args = c.args.length ? `\n\nArguments:\n${columns(c.args.map((a) => ({ flag: a.optional ? `[${a.name}]` : `<${a.name}>`, text: a.text })))}` : "";
+    const own = Object.entries(c.options).map(([n, s]) => optionLine(n, s));
+    const global = Object.entries(GLOBAL_OPTIONS).map(([n, s]) => optionLine(n, s));
+    const examples = c.examples?.length ? `\n\nExamples:\n${c.examples.map((e) => `  ${e}`).join("\n")}` : "";
+    return `${c.text}\n\nUsage: ${c.usage}${args}${own.length ? `\n\nOptions:\n${columns(own)}` : ""}\n\nCommon options:\n${columns(global)}${examples}\n`;
+}
+
+/** Every command's long options, with whether each takes a value and how a shell completes it. */
+function table() {
+    return Object.keys(COMMANDS).map((name) => ({
+        name,
+        args: COMMANDS[name].args,
+        options: Object.entries(optionsOf(name)).map(([option, spec]) => ({ name: option, short: spec.short, value: spec.type === "string", choices: spec.choices ?? null, complete: spec.complete ?? null }))
+    }));
+}
+
+/** Quotes a word for a POSIX shell script. */
+const sh = (word) => `'${String(word).replace(/'/g, "'\\''")}'`;
+
+/**
+ * The completion script of a shell.
+ * @param {"bash" | "zsh" | "fish" | "powershell"} shell
+ */
+export function completionScript(shell) {
+    const commands = table();
+    const names = commands.map((c) => c.name).join(" ");
+    if (shell === "bash" || shell === "zsh") {
+        const cases = commands
+            .map((c) => {
+                const opts = c.options.flatMap((o) => [`--${o.name}`, ...(o.short ? [`-${o.short}`] : [])]).join(" ");
+                const values = c.options
+                    .filter((o) => o.value)
+                    .map((o) => {
+                        const flags = [`--${o.name}`, ...(o.short ? [`-${o.short}`] : [])].join("|");
+                        const reply = o.choices ? `COMPREPLY=( $(compgen -W ${sh(o.choices.join(" "))} -- "$cur") )` : o.complete === "dir" ? 'COMPREPLY=( $(compgen -d -- "$cur") )' : o.complete === "file" ? 'COMPREPLY=( $(compgen -f -- "$cur") )' : "COMPREPLY=()";
+                        return `        ${flags}) ${reply}; return 0 ;;`;
+                    })
+                    .join("\n");
+                const arg = c.args[0]?.complete === "shell" ? `compgen -W ${sh(SHELLS.join(" "))} -- "$cur"` : c.args[0]?.complete === "command" ? `compgen -W ${sh(names)} -- "$cur"` : 'compgen -f -- "$cur"';
+                return `    ${c.name})\n      case "$prev" in\n${values || "        *) ;;"}\n      esac\n      if [[ "$cur" == -* ]]; then COMPREPLY=( $(compgen -W ${sh(opts)} -- "$cur") ); else COMPREPLY=( $(${arg}) ); fi ;;`;
+            })
+            .join("\n");
+        const body = `_pivotkit() {\n  local cur prev cmd\n  cur="\${COMP_WORDS[COMP_CWORD]}"\n  prev="\${COMP_WORDS[COMP_CWORD-1]}"\n  cmd="\${COMP_WORDS[1]}"\n  if [[ $COMP_CWORD -eq 1 ]]; then\n    COMPREPLY=( $(compgen -W ${sh(`${names} --help --version`)} -- "$cur") )\n    return 0\n  fi\n  case "$cmd" in\n${cases}\n  esac\n}\n`;
+        return shell === "bash"
+            ? `# pivotkit completion for bash: eval "$(pivotkit completion bash)"\n${body}complete -o default -F _pivotkit pivotkit\n`
+            : `#compdef pivotkit\n# pivotkit completion for zsh: eval "$(pivotkit completion zsh)" (uses bash completion)\nautoload -U +X bashcompinit && bashcompinit\n${body}complete -o default -F _pivotkit pivotkit\n`;
+    }
+    if (shell === "fish") {
+        const lines = ["# pivotkit completion for fish: pivotkit completion fish | source", "complete -c pivotkit -f"];
+        for (const c of commands) {
+            lines.push(`complete -c pivotkit -n __fish_use_subcommand -a ${sh(c.name)} -d ${sh(COMMANDS[c.name].text)}`);
+            for (const o of c.options) {
+                const values = o.choices ? ` -x -a ${sh(o.choices.join(" "))}` : o.complete === "file" ? " -r -F" : o.complete === "dir" ? ` -x -a "(__fish_complete_directories)"` : o.value ? " -x" : "";
+                lines.push(`complete -c pivotkit -n ${sh(`__fish_seen_subcommand_from ${c.name}`)} -l ${o.name}${o.short ? ` -s ${o.short}` : ""}${values}`);
+            }
+            if (c.args[0]?.complete === "shell") lines.push(`complete -c pivotkit -n ${sh("__fish_seen_subcommand_from completion")} -a ${sh(SHELLS.join(" "))}`);
+            if (c.args[0]?.complete === "file") lines.push(`complete -c pivotkit -n ${sh(`__fish_seen_subcommand_from ${c.name}`)} -F`);
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    // PowerShell: Register-ArgumentCompleter -Native
+    const ps = (word) => `'${String(word).replace(/'/g, "''")}'`;
+    const map = commands
+        .map((c) => `    ${ps(c.name)} = @{ options = @(${c.options.flatMap((o) => [`--${o.name}`, ...(o.short ? [`-${o.short}`] : [])]).map(ps).join(", ")}); choices = @{ ${c.options.filter((o) => o.choices).map((o) => `${ps(`--${o.name}`)} = @(${o.choices.map(ps).join(", ")})`).join("; ")} } }`)
+        .join("\n");
+    return `# pivotkit completion for PowerShell: pivotkit completion powershell | Out-String | Invoke-Expression
+$pivotkitCommands = @{
+${map}
+}
+Register-ArgumentCompleter -Native -CommandName pivotkit -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+    $words = @($commandAst.CommandElements | ForEach-Object { $_.ToString() })
+    if ($words.Count -le 1 -or ($words.Count -eq 2 -and $wordToComplete)) {
+        $candidates = @(${commands.map((c) => ps(c.name)).join(", ")}, '--help', '--version')
+    } else {
+        $entry = $pivotkitCommands[$words[1]]
+        if (-not $entry) { return }
+        $previous = if ($wordToComplete) { $words[-2] } else { $words[-1] }
+        if ($entry.choices.ContainsKey($previous)) { $candidates = $entry.choices[$previous] }
+        elseif ($words[1] -eq 'completion') { $candidates = @(${SHELLS.map(ps).join(", ")}) }
+        elseif ($wordToComplete -like '-*') { $candidates = $entry.options }
+        else { return }
+    }
+    $candidates | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+}
+`;
+}

package/src/safe-files.js

@@ -0,0 +1,190 @@
+/*
+ * Reading and writing files the same safe way, with or without allowed directories:
+ *
+ * - `--allow-dir` is a hard limit: every file read or written must lie inside one of the directories
+ *   after its real path is resolved (symbolic links and ".." followed), checked on the path and again
+ *   on the opened file (its device and inode against the real path's). Without it the CLI reads and
+ *   writes with the user's own rights, as any command-line tool does.
+ * - A file is opened once, without following a symbolic link at its end where the system can
+ *   (O_NOFOLLOW) and without waiting for a writer (O_NONBLOCK, so a FIFO cannot hang the CLI), then
+ *   checked on the handle: a regular file only, and its size against the limit before a byte is read.
+ * - A file is written to a new temporary file next to it (exclusive create), then renamed over the
+ *   target: no half-written output, and a symbolic link, a directory or another non-regular file at
+ *   the target is refused, never replaced.
+ *
+ * Not a sandbox against another process of the same user that changes the directories while the CLI
+ * runs: the checks narrow that window, they do not close it. A hard link inside an allowed directory
+ * to a file outside it is that file's name inside: no path check can tell it apart. A temporary file
+ * of a run that is killed between its creation and the rename stays behind (".<name>.<pid>-<random>.tmp").
+ * The MCP server of step 3 reuses this module.
+ */
+
+import { constants } from "node:fs";
+import { lstat, open, realpath, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join, relative, resolve, isAbsolute, sep } from "node:path";
+import { CliError, shortName } from "./errors.js";
+
+const READ_FLAGS = constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0);
+
+/** True when `real` is `dir` or lies inside it (both real paths). */
+export function isInside(real, dir) {
+    const rel = relative(dir, real);
+    // "..foo" is a name inside the directory; only ".." as the first part leaves it
+    return rel === "" || (!isAbsolute(rel) && rel.split(sep)[0] !== "..");
+}
+
+/**
+ * The allowed directories as real paths; each must exist and be a directory.
+ * @param {string[]} dirs
+ * @param {string} cwd
+ * @returns {Promise<string[]>}
+ */
+export async function allowedDirs(dirs, cwd) {
+    const out = [];
+    for (const dir of dirs) {
+        let real;
+        try {
+            real = await realpath(resolve(cwd, dir));
+        } catch {
+            throw new CliError("usage", "ALLOW_DIR_NOT_FOUND", `--allow-dir ${shortName(dir)}: not found`);
+        }
+        if (!(await stat(real)).isDirectory()) {
+            throw new CliError("usage", "ALLOW_DIR_NOT_DIRECTORY", `--allow-dir ${shortName(dir)}: not a directory`);
+        }
+        out.push(real);
+    }
+    return out;
+}
+
+/** Refuses a real path outside the allowed directories (none given: every path is allowed). */
+function checkAllowed(real, allow, path) {
+    if (allow.length > 0 && !allow.some((dir) => isInside(real, dir))) {
+        // the directories by their base names, as every path in a message
+        throw new CliError("io", "OUTSIDE_ALLOWED_DIR", `${shortName(path)}: outside the allowed directories (--allow-dir ${allow.map(shortName).join(", ")})`);
+    }
+}
+
+/**
+ * Reads a regular file of at most `maxBytes` bytes.
+ * @param {string} path
+ * @param {{ cwd: string, allow: string[], maxBytes: number, limit?: string }} options  `limit`: the limit's name for the message
+ * @returns {Promise<Uint8Array>}
+ */
+export async function readSafe(path, { cwd, allow, maxBytes, limit = "fileBytes" }) {
+    const full = resolve(cwd, path);
+    let real;
+    try {
+        real = await realpath(full);
+    } catch (e) {
+        throw e?.code === "ENOENT" ? new CliError("io", "NOT_FOUND", `${shortName(path)}: not found`) : e;
+    }
+    checkAllowed(real, allow, path);
+    const handle = await open(real, READ_FLAGS);
+    try {
+        const info = await handle.stat();
+        if (!info.isFile()) {
+            throw new CliError("io", "NOT_REGULAR_FILE", `${shortName(path)}: not a regular file`);
+        }
+        const now = await stat(real);
+        if (now.dev !== info.dev || now.ino !== info.ino) {
+            throw new CliError("io", "CHANGED", `${shortName(path)}: changed while it was opened`);
+        }
+        if (info.size > maxBytes) {
+            throw tooLarge(path, info.size, maxBytes, limit);
+        }
+        // the size the file had at the check, plus one byte: a file that has more by then grew (or, as
+        // a file of /proc, says it has none): over the limit it is refused as too large, else as changed,
+        // never cut
+        const buffer = new Uint8Array(Math.min(maxBytes + 1, info.size + 1));
+        let length = 0;
+        for (;;) {
+            const { bytesRead } = await handle.read(buffer, length, buffer.length - length, null);
+            if (bytesRead === 0) {
+                break;
+            }
+            length += bytesRead;
+            if (length > maxBytes) {
+                throw tooLarge(path, length, maxBytes, limit);
+            }
+            if (length > info.size) {
+                throw new CliError("io", "CHANGED", `${shortName(path)}: changed while it was read (it has more than the ${info.size.toLocaleString("en-US")} bytes it had)`);
+            }
+        }
+        return buffer.subarray(0, length);
+    } finally {
+        await handle.close();
+    }
+}
+
+/** A file over its limit, named by its base name. */
+const tooLarge = (path, size, max, limit) => new CliError("limit", "LIMIT_EXCEEDED", `${shortName(path)}: ${size.toLocaleString("en-US")} bytes exceed the limit of ${max.toLocaleString("en-US")} (limits.${limit})`);
+
+/**
+ * Reads stdin up to `maxBytes` bytes.
+ * @param {AsyncIterable<Uint8Array>} stdin
+ * @param {number} maxBytes
+ * @param {string} [limit]
+ */
+export async function readStdin(stdin, maxBytes, limit = "fileBytes") {
+    const chunks = [];
+    let length = 0;
+    for await (const chunk of stdin) {
+        length += chunk.length;
+        if (length > maxBytes) {
+            throw tooLarge("-", length, maxBytes, limit);
+        }
+        chunks.push(chunk);
+    }
+    const out = new Uint8Array(length);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.length;
+    }
+    return out;
+}
+
+/**
+ * Writes `bytes` to `path`: into a new temporary file in the target's directory, then renamed over it.
+ * @param {string} path
+ * @param {Uint8Array} bytes
+ * @param {{ cwd: string, allow: string[] }} options
+ * @returns {Promise<string>}  the real path written
+ */
+export async function writeSafe(path, bytes, { cwd, allow }) {
+    const full = resolve(cwd, path);
+    let dir;
+    try {
+        dir = await realpath(dirname(full));
+    } catch {
+        throw new CliError("io", "NOT_FOUND", `${shortName(path)}: its directory is not found`);
+    }
+    const target = join(dir, basename(full));
+    checkAllowed(target, allow, path);
+    const existing = await lstat(target).catch((e) => (e.code === "ENOENT" ? null : Promise.reject(e)));
+    if (existing && !existing.isFile()) {
+        const what = existing.isSymbolicLink() ? "a symbolic link" : existing.isDirectory() ? "a directory" : "a device or another special file";
+        throw new CliError("io", existing.isSymbolicLink() || existing.isDirectory() ? "NOT_REGULAR_FILE" : "SPECIAL_FILE", `${shortName(path)}: exists and is ${what}; not replaced`);
+    }
+    // the temporary name stays within a file name's 255 bytes, however long the target's name is: 50
+    // characters of at most 4 bytes each, then about 25 for the process, a random part and ".tmp"
+    const stem = Array.from(basename(full)).slice(0, 50).join("");
+    const temp = join(dir, `.${stem}.${process.pid}-${Math.random().toString(36).slice(2, 10)}.tmp`);
+    const handle = await open(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), existing ? existing.mode & 0o777 : 0o644);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    } catch (e) {
+        await handle.close();
+        await unlink(temp).catch(() => undefined);
+        throw e;
+    }
+    await handle.close();
+    try {
+        await rename(temp, target);
+    } catch (e) {
+        await unlink(temp).catch(() => undefined);
+        throw e;
+    }
+    return target;
+}

package/types/cli.d.ts

@@ -0,0 +1,27 @@
+export type Io = {
+    stdin: AsyncIterable<Uint8Array> & {
+        isTTY?: boolean;
+    };
+    stdout: {
+        write(chunk: string | Uint8Array): unknown;
+        isTTY?: boolean;
+    };
+    stderr: {
+        write(chunk: string | Uint8Array): unknown;
+    };
+    env: Record<string, string | undefined>;
+    cwd: string;
+};
+/** The versions of this package and the two it renders with. */
+export declare function versions(): {
+    "pivotkit-cli": any;
+    "pivotkit-report": any;
+    "pivotkit-core": any;
+};
+/**
+ * Runs one command. Never throws: every error ends in its exit code and message.
+ * @param {string[]} argv  the arguments after "pivotkit"
+ * @param {Io} io
+ * @returns {Promise<number>}  the exit code
+ */
+export declare function main(argv: string[], io: Io): Promise<number>;

package/types/commands.d.ts

@@ -0,0 +1,80 @@
+export type OptionSpec = {
+    type: "string" | "boolean";
+    /**
+     * one letter
+     */
+    short?: string;
+    /**
+     * may be given more than once
+     */
+    multiple?: boolean;
+    /**
+     * the value's name in the help ("file", "dir")
+     */
+    value?: string;
+    /**
+     * the values it takes (checked, and offered by the completions)
+     */
+    choices?: string[];
+    /**
+     * what a shell completes for its value
+     */
+    complete?: "file" | "dir";
+    /**
+     * the environment variable that gives its default
+     */
+    env?: string;
+    /**
+     * render: the output formats it acts in (given with another, a warning)
+     */
+    formats?: string[];
+    /**
+     * one line of help
+     */
+    text: string;
+};
+/**
+ * @typedef {object} OptionSpec
+ * @property {"string" | "boolean"} type
+ * @property {string} [short]  one letter
+ * @property {boolean} [multiple]  may be given more than once
+ * @property {string} [value]  the value's name in the help ("file", "dir")
+ * @property {string[]} [choices]  the values it takes (checked, and offered by the completions)
+ * @property {"file" | "dir"} [complete]  what a shell completes for its value
+ * @property {string} [env]  the environment variable that gives its default
+ * @property {string[]} [formats]  render: the output formats it acts in (given with another, a warning)
+ * @property {string} text  one line of help
+ */
+/** @type {Readonly<Record<string, OptionSpec>>} Options every command takes. */
+export declare const GLOBAL_OPTIONS: Readonly<Record<string, OptionSpec>>;
+export type CommandSpec = {
+    usage: string;
+    text: string;
+    args: Array<{
+        name: string;
+        text: string;
+        optional?: boolean;
+        complete?: "file" | "shell" | "command";
+    }>;
+    /**
+     * besides GLOBAL_OPTIONS
+     */
+    options: Readonly<Record<string, OptionSpec>>;
+    examples?: string[];
+};
+/**
+ * @typedef {object} CommandSpec
+ * @property {string} usage
+ * @property {string} text
+ * @property {Array<{ name: string, text: string, optional?: boolean, complete?: "file" | "shell" | "command" }>} args
+ * @property {Readonly<Record<string, OptionSpec>>} options  besides GLOBAL_OPTIONS
+ * @property {string[]} [examples]
+ */
+/** @type {Readonly<Record<string, CommandSpec>>} */
+export declare const COMMANDS: Readonly<Record<string, CommandSpec>>;
+/** The shells completion() writes for. */
+export declare const SHELLS: readonly string[];
+/** The options of a command: its own and the global ones. */
+export declare const optionsOf: (command: any) => {
+    [x: string]: OptionSpec;
+};

package/types/errors.d.ts

@@ -0,0 +1,26 @@
+export type ErrorKind = "usage" | "io" | "limit" | "template" | "internal";
+/** @typedef {"usage" | "io" | "limit" | "template" | "internal"} ErrorKind */
+export declare class CliError extends Error {
+    kind: ErrorKind;
+    code: string;
+    /**
+     * @param {ErrorKind} kind
+     * @param {string} code  a stable name, e.g. NOT_FOUND, OUTSIDE_ALLOWED_DIR, UNKNOWN_OPTION
+     * @param {string} message
+     */
+    constructor(kind: ErrorKind, code: string, message: string);
+}
+/** The most characters of a name or message from outside that the CLI prints. */
+export declare const PRINT_LENGTH = 200;
+/** Text from a file, a view or the data, safe to print: no control or direction characters, capped. */
+export declare function printable(text: any): string;
+/** A path as messages name it: its base name only. */
+export declare const shortName: (path: any) => string;
+/**
+ * Any error as a CliError: pivotkit-core's by their code, Node's file errors by theirs (with the
+ * file's base name, never its content), anything else as internal.
+ * @param {unknown} error
+ * @param {string} [path]  the file it is about
+ * @returns {CliError}
+ */
+export declare function asCliError(error: unknown, path?: string): CliError;

package/types/help.d.ts

@@ -0,0 +1,7 @@
+/** The help of pivotkit, or of one command. */
+export declare function helpText(command: any): string;
+/**
+ * The completion script of a shell.
+ * @param {"bash" | "zsh" | "fish" | "powershell"} shell
+ */
+export declare function completionScript(shell: "bash" | "zsh" | "fish" | "powershell"): string;

package/types/safe-files.d.ts

@@ -0,0 +1,39 @@
+/** True when `real` is `dir` or lies inside it (both real paths). */
+export declare function isInside(real: any, dir: any): boolean;
+/**
+ * The allowed directories as real paths; each must exist and be a directory.
+ * @param {string[]} dirs
+ * @param {string} cwd
+ * @returns {Promise<string[]>}
+ */
+export declare function allowedDirs(dirs: string[], cwd: string): Promise<string[]>;
+/**
+ * Reads a regular file of at most `maxBytes` bytes.
+ * @param {string} path
+ * @param {{ cwd: string, allow: string[], maxBytes: number, limit?: string }} options  `limit`: the limit's name for the message
+ * @returns {Promise<Uint8Array>}
+ */
+export declare function readSafe(path: string, { cwd, allow, maxBytes, limit }: {
+    cwd: string;
+    allow: string[];
+    maxBytes: number;
+    limit?: string;
+}): Promise<Uint8Array>;
+/**
+ * Reads stdin up to `maxBytes` bytes.
+ * @param {AsyncIterable<Uint8Array>} stdin
+ * @param {number} maxBytes
+ * @param {string} [limit]
+ */
+export declare function readStdin(stdin: AsyncIterable<Uint8Array>, maxBytes: number, limit?: string): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Writes `bytes` to `path`: into a new temporary file in the target's directory, then renamed over it.
+ * @param {string} path
+ * @param {Uint8Array} bytes
+ * @param {{ cwd: string, allow: string[] }} options
+ * @returns {Promise<string>}  the real path written
+ */
+export declare function writeSafe(path: string, bytes: Uint8Array, { cwd, allow }: {
+    cwd: string;
+    allow: string[];
+}): Promise<string>;