vastgrid-cli 0.0.0-stage → 0.2.0

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * `vastgrid [--save] [--port <n>] [--no-open] [<file or folder>…]` (docs/cli.md): starts DuckDB and the page that
+ * shows the files in 0.2's grid, on 127.0.0.1, and opens the page in the browser. Ctrl+C stops both, and the engine
+ * deletes its temporary folder.
+ */
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { serve } from "./server.js";
+const USAGE = `Usage: vastgrid [options] [<file or folder>…]
+
+Opens CSV, TSV, Parquet, JSON Lines and Excel files in a grid in the browser, read by DuckDB on this computer.
+A folder gives its files, two folders deep; the current folder when nothing is named.
+
+Options:
+  --save       Let the page save edited cells into CSV and TSV files (⌘S or Ctrl+S).
+  --port <n>   The port on 127.0.0.1; a free one by default.
+  --no-open    Print the address without opening the browser.
+  -h, --help   Show this help.
+
+VASTGRID_TOKEN sets the token in the address, instead of a random one.
+`;
+function fail(message, code) {
+    process.stderr.write(`vastgrid: ${message}\n`);
+    process.exit(code);
+}
+let parsed;
+function readArgs() {
+    return parseArgs({
+        allowPositionals: true,
+        options: {
+            save: { type: "boolean" },
+            port: { type: "string" },
+            "no-open": { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+}
+try {
+    parsed = readArgs();
+}
+catch (error) {
+    fail(`${error.message}\nRun vastgrid --help for the options.`, 2);
+}
+const { values, positionals } = parsed;
+if (values.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+}
+const port = values.port === undefined ? 0 : Number(values.port);
+if (!Number.isInteger(port) || port < 0 || port > 65535)
+    fail(`${values.port} is not a port.`, 2);
+/** Opens the address in the browser of the system; the address is printed either way. */
+function openBrowser(url) {
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+            : ["xdg-open", [url]];
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => process.stderr.write("vastgrid: Open the address in a browser.\n"));
+    child.unref();
+}
+const served = await serve({
+    paths: positionals.length > 0 ? positionals : ["."],
+    port,
+    token: process.env.VASTGRID_TOKEN || undefined,
+    save: values.save ?? false,
+    log: (message, error) => process.stderr.write(`vastgrid: ${message}: ${String(error ?? "")}\n`),
+}).catch((error) => fail(error instanceof Error ? error.message : String(error), 1));
+const count = (await served.files()).length;
+process.stdout.write(`vastgrid shows ${count === 1 ? "1 file" : `${count} files`}${values.save ? ", and saves edited cells," : ""} at\n` +
+    `  ${served.url}\nPress Ctrl+C to stop.\n`);
+if (!values["no-open"])
+    openBrowser(served.url);
+let stopping = false;
+function stop() {
+    // A second Ctrl+C does not wait.
+    if (stopping)
+        process.exit(130);
+    stopping = true;
+    void served.close().finally(() => process.exit(0));
+}
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+/** `vastgrid` (docs/cli.md): files in 0.2's grid in the browser, read by DuckDB on this computer. */
+export { type Served, type ServeOptions, serve } from "./server.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+/** `vastgrid` (docs/cli.md): files in 0.2's grid in the browser, read by DuckDB on this computer. */
+export { serve } from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,qGAAqG;AACrG,OAAO,EAAkC,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,30 @@
+export interface ServeOptions {
+    /** The files and folders to open: a folder gives its table files, up to two folders deep. */
+    paths: string[];
+    /** The port on 127.0.0.1; 0, the default, takes a free one. */
+    port?: number;
+    /** The token of the address: 16 or more letters, digits, `-` and `_`. A random one by default. */
+    token?: string;
+    /** Lets the page save written cells into the CSV and TSV files they came from (§7.5). Off by default. */
+    save?: boolean;
+    /** The folder that the page's names of files are relative to: the current one by default. */
+    cwd?: string;
+    /** Where the engine keeps its database and spilled data, in a folder of its own that it deletes when it stops. */
+    tempDirectory?: string;
+    /** The page: `dist/app.html` of the package by default. */
+    html?: () => Promise<string>;
+    /** Receives problems that no request caused. */
+    log?: (message: string, error?: unknown) => void;
+}
+export interface Served {
+    /** The address that opens the page, with the token. */
+    url: string;
+    port: number;
+    /** The files that the page lists, by the names that it opens them with. */
+    files(): Promise<string[]>;
+    /** Stops the server and the engine, which deletes its temporary folder. */
+    close(): Promise<void>;
+}
+/** Starts the engine and the server of the page, which shows the files of `paths`. */
+export declare function serve(options: ServeOptions): Promise<Served>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,YAAY;IAC3B,6FAA6F;IAC7F,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kGAAkG;IAClG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yGAAyG;IACzG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6FAA6F;IAC7F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kHAAkH;IAClH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7B,gDAAgD;IAChD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,MAAM;IACrB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3B,2EAA2E;IAC3E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA+DD,sFAAsF;AACtF,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAgHlE"}

package/dist/server.js

@@ -0,0 +1,191 @@
+/**
+ * The server of `vastgrid` (docs/cli.md): the page, the list of the files that it opens, and the DuckDB engine over
+ * HTTP (docs/spec.md §8.8), on 127.0.0.1 only. The address that the command prints holds a token, which the page
+ * keeps in a cookie: other sites in the browser, other people on the computer and names that point at 127.0.0.1
+ * (DNS rebinding) reach nothing.
+ */
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdirSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { createHttpHandler, DuckDBEngine, findTableFiles, tableFormatOf } from "vastgrid-duckdb";
+/** Files that the list of a folder holds at most. */
+const LIST_LIMIT = 1000;
+/**
+ * The page's script and styles are inside it, and it reaches nothing but this server; it is in no other site's
+ * frame.
+ */
+const PAGE_HEADERS = {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store",
+    "content-security-policy": "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; " +
+        "font-src data:; connect-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+    "x-content-type-options": "nosniff",
+    "referrer-policy": "no-referrer",
+};
+/** The page as the package builds it (`npm run build`), next to `src` and `dist`. */
+async function builtHtml() {
+    return readFile(new URL("../dist/app.html", import.meta.url), "utf8");
+}
+function text(response, status, body) {
+    response.writeHead(status, { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store" });
+    response.end(body);
+}
+function sameText(a, b) {
+    const given = Buffer.from(a ?? "");
+    const expected = Buffer.from(b);
+    return given.length === expected.length && timingSafeEqual(given, expected);
+}
+function cookieOf(request, name) {
+    for (const part of String(request.headers.cookie ?? "").split(";")) {
+        const at = part.indexOf("=");
+        if (at > 0 && part.slice(0, at).trim() === name)
+            return part.slice(at + 1).trim();
+    }
+    return null;
+}
+function isInside(folder, file) {
+    const relative = path.relative(folder, file);
+    return relative !== "" && !path.isAbsolute(relative) && relative.split(path.sep)[0] !== "..";
+}
+/** The files and folders of `paths`, or why one of them cannot be opened. */
+async function sortPaths(paths, cwd) {
+    const files = [];
+    const folders = [];
+    for (const named of paths) {
+        const full = path.resolve(cwd, named);
+        const found = await stat(full).catch(() => null);
+        if (!found)
+            throw new Error(`${named} does not exist.`);
+        if (found.isDirectory())
+            folders.push(full);
+        else if (tableFormatOf(full))
+            files.push(full);
+        else
+            throw new Error(`${named} is not a CSV, TSV, Parquet, JSON Lines or Excel file.`);
+    }
+    return { files: [...new Set(files)], folders: [...new Set(folders)] };
+}
+/** Starts the engine and the server of the page, which shows the files of `paths`. */
+export async function serve(options) {
+    const cwd = path.resolve(options.cwd ?? process.cwd());
+    const token = options.token ?? randomBytes(24).toString("base64url");
+    if (!/^[\w-]{16,}$/.test(token))
+        throw new Error("The token is 16 or more letters, digits, - and _.");
+    const { files, folders } = await sortPaths(options.paths, cwd);
+    const nameOf = (file) => (isInside(cwd, file) ? path.relative(cwd, file).split(path.sep).join("/") : file);
+    // Only the files named, and the table files of the folders named, open; DuckDB reads nothing outside their folders.
+    const opens = (file) => files.includes(file) || (tableFormatOf(file) !== null && folders.some((folder) => isInside(folder, file)));
+    const tempDirectory = options.tempDirectory ?? path.join(os.tmpdir(), "vastgrid-cli");
+    mkdirSync(tempDirectory, { recursive: true });
+    const engine = await DuckDBEngine.create({
+        allowedDirectories: [...new Set([...folders, ...files.map((file) => path.dirname(file))])],
+        resolve: (ref) => {
+            const file = path.resolve(cwd, ref);
+            if (!opens(file))
+                throw new Error(`vastgrid was not started with ${ref}.`);
+            return file;
+        },
+        tempDirectory,
+        saveFiles: options.save ?? false,
+        log: options.log,
+    });
+    const list = async () => {
+        const found = await findTableFiles(folders, LIST_LIMIT);
+        return [...new Set([...files, ...found])].map(nameOf);
+    };
+    const html = options.html ?? builtHtml;
+    const api = createHttpHandler(engine, { path: "/api" });
+    let hosts = new Set();
+    let cookie = "";
+    const route = async (request, response) => {
+        // A name of another site that points at this computer is not this server's.
+        if (!hosts.has(String(request.headers.host))) {
+            text(response, 403, "vastgrid answers at 127.0.0.1 and localhost only.\n");
+            return;
+        }
+        const url = new URL(request.url ?? "/", "http://localhost");
+        if (url.pathname === "/" && url.searchParams.has("token")) {
+            if (!sameText(url.searchParams.get("token"), token)) {
+                text(response, 401, "This is not the address that vastgrid printed.\n");
+                return;
+            }
+            // The page keeps the token, which leaves the address.
+            url.searchParams.delete("token");
+            response.writeHead(303, {
+                location: `/${url.search}`,
+                "set-cookie": `${cookie}=${token}; HttpOnly; SameSite=Strict; Path=/`,
+                "cache-control": "no-store",
+            });
+            response.end();
+            return;
+        }
+        if (!sameText(cookieOf(request, cookie), token)) {
+            text(response, 401, "Open the address that vastgrid printed when it started.\n");
+            return;
+        }
+        if (url.pathname === "/" && request.method === "GET") {
+            const page = await html().catch(() => null);
+            if (page === null)
+                text(response, 500, "The page is not built: run `npm run build`.\n");
+            else {
+                response.writeHead(200, PAGE_HEADERS);
+                response.end(page);
+            }
+        }
+        else if (url.pathname === "/files" && request.method === "GET") {
+            response.writeHead(200, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+            response.end(JSON.stringify({ files: await list(), save: options.save ?? false }));
+        }
+        else if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
+            await api(request, response);
+        }
+        else {
+            text(response, 404, "There is nothing at this path.\n");
+        }
+    };
+    const server = createServer((request, response) => {
+        route(request, response).catch((error) => {
+            options.log?.("A request failed", error);
+            if (response.headersSent)
+                response.destroy();
+            else
+                text(response, 500, "The request failed.\n");
+        });
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.port ?? 0, "127.0.0.1", resolve);
+        });
+    }
+    catch (error) {
+        await engine.dispose();
+        if (error.code === "EADDRINUSE")
+            throw new Error(`Port ${options.port} is in use.`);
+        throw error;
+    }
+    const { port } = server.address();
+    hosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`]);
+    // Cookies are not kept apart by port: each server of the computer has its own.
+    cookie = `vastgrid-${port}`;
+    let closed = null;
+    return {
+        url: `http://127.0.0.1:${port}/?token=${token}`,
+        port,
+        files: list,
+        close() {
+            closed ??= (async () => {
+                const stopped = new Promise((resolve) => server.close(() => resolve()));
+                // Streams of events stay open until they are closed.
+                server.closeAllConnections();
+                await stopped;
+                await engine.dispose();
+            })();
+            return closed;
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "vastgrid-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Open huge CSV, TSV, Parquet, JSON Lines and Excel files in a grid in the browser with one command, read by DuckDB on this computer: npx vastgrid-cli data.parquet",
+  "keywords": [
+    "csv",
+    "tsv",
+    "parquet",
+    "excel",
+    "xlsx",
+    "duckdb",
+    "viewer",
+    "cli",
+    "data grid"
+  ],
+  "license": "MIT",
+  "author": "yhay81",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yhay81/vastgrid.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://vastgrid.yhay81.com",
+  "bugs": "https://github.com/yhay81/vastgrid/issues",
+  "type": "module",
+  "sideEffects": false,
+  "bin": {
+    "vastgrid": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "vastgrid-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -b && node scripts/build-app.mjs"
+  },
+  "dependencies": {
+    "vastgrid-duckdb": "0.2.0"
+  },
+  "devDependencies": {
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "vastgrid": "0.2.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * `vastgrid [--save] [--port <n>] [--no-open] [<file or folder>…]` (docs/cli.md): starts DuckDB and the page that
+ * shows the files in 0.2's grid, on 127.0.0.1, and opens the page in the browser. Ctrl+C stops both, and the engine
+ * deletes its temporary folder.
+ */
+import { spawn } from "node:child_process";
+import { parseArgs } from "node:util";
+import { serve } from "./server.js";
+
+const USAGE = `Usage: vastgrid [options] [<file or folder>…]
+
+Opens CSV, TSV, Parquet, JSON Lines and Excel files in a grid in the browser, read by DuckDB on this computer.
+A folder gives its files, two folders deep; the current folder when nothing is named.
+
+Options:
+  --save       Let the page save edited cells into CSV and TSV files (⌘S or Ctrl+S).
+  --port <n>   The port on 127.0.0.1; a free one by default.
+  --no-open    Print the address without opening the browser.
+  -h, --help   Show this help.
+
+VASTGRID_TOKEN sets the token in the address, instead of a random one.
+`;
+
+function fail(message: string, code: number): never {
+  process.stderr.write(`vastgrid: ${message}\n`);
+  process.exit(code);
+}
+
+let parsed: ReturnType<typeof readArgs>;
+function readArgs() {
+  return parseArgs({
+    allowPositionals: true,
+    options: {
+      save: { type: "boolean" },
+      port: { type: "string" },
+      "no-open": { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  });
+}
+try {
+  parsed = readArgs();
+} catch (error) {
+  fail(`${(error as Error).message}\nRun vastgrid --help for the options.`, 2);
+}
+const { values, positionals } = parsed;
+if (values.help) {
+  process.stdout.write(USAGE);
+  process.exit(0);
+}
+const port = values.port === undefined ? 0 : Number(values.port);
+if (!Number.isInteger(port) || port < 0 || port > 65535) fail(`${values.port} is not a port.`, 2);
+
+/** Opens the address in the browser of the system; the address is printed either way. */
+function openBrowser(url: string) {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["rundll32", ["url.dll,FileProtocolHandler", url]]
+        : ["xdg-open", [url]];
+  const child = spawn(command, args, { stdio: "ignore", detached: true });
+  child.on("error", () => process.stderr.write("vastgrid: Open the address in a browser.\n"));
+  child.unref();
+}
+
+const served = await serve({
+  paths: positionals.length > 0 ? positionals : ["."],
+  port,
+  token: process.env.VASTGRID_TOKEN || undefined,
+  save: values.save ?? false,
+  log: (message, error) => process.stderr.write(`vastgrid: ${message}: ${String(error ?? "")}\n`),
+}).catch((error: unknown) => fail(error instanceof Error ? error.message : String(error), 1));
+
+const count = (await served.files()).length;
+process.stdout.write(
+  `vastgrid shows ${count === 1 ? "1 file" : `${count} files`}${values.save ? ", and saves edited cells," : ""} at\n` +
+    `  ${served.url}\nPress Ctrl+C to stop.\n`,
+);
+if (!values["no-open"]) openBrowser(served.url);
+
+let stopping = false;
+function stop() {
+  // A second Ctrl+C does not wait.
+  if (stopping) process.exit(130);
+  stopping = true;
+  void served.close().finally(() => process.exit(0));
+}
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);

package/src/index.ts

@@ -0,0 +1,2 @@
+/** `vastgrid` (docs/cli.md): files in 0.2's grid in the browser, read by DuckDB on this computer. */
+export { type Served, type ServeOptions, serve } from "./server.js";