@nachoggodino/cello 0.1.0

package/dist/cli/cli.js

@@ -0,0 +1,360 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { evaluate } from "../evaluator/evaluate.js";
+import { format as formatCello } from "../formatter/format.js";
+import { parse } from "../parser/parse.js";
+import { render } from "../renderer/render.js";
+import { serialize } from "../serializer/serialize.js";
+import { validate } from "../validator/validate.js";
+import { VERSION } from "../version.js";
+import { startServe } from "./serve.js";
+export function createCliDeps(overrides = {}) {
+    return {
+        cwd: overrides.cwd ?? process.cwd(),
+        readFileFn: overrides.readFileFn ?? readFile,
+        writeFileFn: overrides.writeFileFn ?? writeFile,
+        startServeFn: overrides.startServeFn ?? startServe,
+        stayOpenFn: overrides.stayOpenFn ?? (() => new Promise(() => undefined)),
+        stdoutWrite: overrides.stdoutWrite ?? ((text) => process.stdout.write(text)),
+        stderrWrite: overrides.stderrWrite ?? ((text) => process.stderr.write(text))
+    };
+}
+export async function runCli(argv, deps = createCliDeps()) {
+    const request = parseCliRequest(argv, deps.cwd);
+    if (request && "error" in request) {
+        deps.stderrWrite(`${request.error}\n`);
+        return 1;
+    }
+    if (!request) {
+        printUsage(deps.stdoutWrite);
+        return 1;
+    }
+    return runCliRequest(request, deps);
+}
+export async function runMain(argv, deps = createCliDeps(), exitFn = (code) => process.exit(code), runCliFn = runCli, stderrWrite = (text) => process.stderr.write(text)) {
+    try {
+        const code = await runCliFn(argv, deps);
+        exitFn(code);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.stack ?? err.message : String(err);
+        stderrWrite(`${message}\n`);
+        exitFn(1);
+    }
+}
+function printUsage(write) {
+    write([
+        "Usage:",
+        "  cello help [command]",
+        "  cello version",
+        "  cello parse <file.cel>",
+        "  cello evaluate <file.cel>",
+        "  cello format <file.cel> [--check] [-o out.cel]",
+        "  cello validate <file.cel>",
+        "  cello render <file.cel> [-o out.html] [--no-eval] [--format document|fragment]",
+        "  cello serialize <file.cel> [-o out.cel]",
+        "  cello serve <file.cel> [--port 4321] [--host 127.0.0.1] [--open] [--no-eval]"
+    ].join("\n"));
+    write("\n");
+}
+const HELP_TEXT = {
+    help: "Usage: cello help [command]\n\nPrint general help or details for one command.\n",
+    version: "Usage: cello --version\n\nPrint the cello CLI version.\n",
+    parse: "Usage: cello parse <file.cel>\n\nParse a workbook and print the AST as JSON.\n",
+    evaluate: "Usage: cello evaluate <file.cel>\n\nParse and evaluate formulas, then print the evaluated AST as JSON.\n",
+    format: "Usage: cello format <file.cel> [--check] [-o out.cel]\n\nPretty-print native Cello pipe tables. Writes in place by default, supports -o/--out for an alternate destination, and --check to report whether formatting changes are needed.\n",
+    validate: "Usage: cello validate <file.cel>\n\nParse and evaluate diagnostics. Prints JSON with valid and diagnostics fields. Exits 0 when valid, 1 when diagnostics exist.\n",
+    render: "Usage: cello render <file.cel> [-o out.html] [--no-eval] [--format document|fragment]\n\nRender a workbook to HTML. The default format is document. Use fragment for an embeddable chunk without html/head/body wrappers. Use --no-eval to leave formula cells unevaluated.\n",
+    serialize: "Usage: cello serialize <file.cel> [-o out.cel]\n\nParse and serialize a workbook back to .cel text.\n",
+    serve: "Usage: cello serve <file.cel> [--port 4321] [--host 127.0.0.1] [--open] [--no-eval]\n\nServe a live HTML preview. The server keeps the process warm for faster repeated renders. Use --open to open the URL in a browser.\n"
+};
+function parseCliRequest(argv, cwd) {
+    const [, , command, inputArg, ...rest] = argv;
+    if (command === "--version" || command === "-v" || command === "version") {
+        if (inputArg) {
+            return { error: `Unexpected argument for version: ${inputArg}` };
+        }
+        return { command: "version" };
+    }
+    if (command === "help" || command === "--help" || command === "-h") {
+        if (rest.length > 0) {
+            return { error: `Unexpected argument for help: ${rest[0]}` };
+        }
+        return { command: "help", topic: inputArg ?? "" };
+    }
+    if (inputArg === "--help" || inputArg === "-h") {
+        if (rest.length > 0) {
+            return { error: `Unexpected argument for help: ${rest[0]}` };
+        }
+        return { command: "help", topic: command ?? "" };
+    }
+    if (!command) {
+        return null;
+    }
+    if (!isCliCommand(command)) {
+        return { error: `Unknown command: ${command}` };
+    }
+    if (!inputArg) {
+        return { error: `Missing input file for ${command}.` };
+    }
+    if (inputArg.startsWith("-")) {
+        return { error: `Missing input file for ${command}; received option ${inputArg}.` };
+    }
+    const serveOptionError = validateServeOptionScope(command, rest);
+    if (serveOptionError) {
+        return serveOptionError;
+    }
+    const argumentError = validateArguments(command, rest);
+    if (argumentError) {
+        return argumentError;
+    }
+    const resolvedOutPath = resolveOutPath(cwd, rest);
+    if (typeof resolvedOutPath !== "string") {
+        return resolvedOutPath;
+    }
+    const resolvedRenderFormat = command === "render" ? resolveRenderFormat(rest) : undefined;
+    if (resolvedRenderFormat && "error" in resolvedRenderFormat) {
+        return resolvedRenderFormat;
+    }
+    const request = {
+        command,
+        inputPath: resolve(cwd, inputArg),
+        outPath: resolvedOutPath,
+        evaluate: !rest.includes("--no-eval")
+    };
+    if (command === "format") {
+        request.check = rest.includes("--check");
+    }
+    if (resolvedRenderFormat) {
+        request.renderFormat = resolvedRenderFormat.format;
+    }
+    if (command === "serve") {
+        const resolvedServeOptions = resolveServeOptions(rest);
+        if ("error" in resolvedServeOptions) {
+            return resolvedServeOptions;
+        }
+        request.host = resolvedServeOptions.host;
+        request.port = resolvedServeOptions.port;
+        request.open = resolvedServeOptions.open;
+    }
+    return request;
+}
+function isCliCommand(command) {
+    return (command === "parse" ||
+        command === "evaluate" ||
+        command === "format" ||
+        command === "validate" ||
+        command === "render" ||
+        command === "serialize" ||
+        command === "serve");
+}
+function validateServeOptionScope(command, rest) {
+    if (command !== "serve" && (rest.includes("--host") || rest.includes("--port") || rest.includes("--open"))) {
+        return { error: "--host, --port, and --open are only supported by serve." };
+    }
+    if (command !== "serve" && command !== "render" && rest.includes("--no-eval")) {
+        return { error: "--no-eval is only supported by render and serve." };
+    }
+    if (command !== "format" && rest.includes("--check")) {
+        return { error: "--check is only supported by format." };
+    }
+    return undefined;
+}
+function validateArguments(command, rest) {
+    const optionsWithValues = new Set(command === "serve" ? ["--host", "--port"] : ["--out", "-o", "--format"]);
+    const allowedOptions = new Set();
+    if (command === "render" || command === "serialize" || command === "format") {
+        allowedOptions.add("--out");
+        allowedOptions.add("-o");
+    }
+    if (command === "render" || command === "serve") {
+        allowedOptions.add("--no-eval");
+    }
+    if (command === "render") {
+        allowedOptions.add("--format");
+    }
+    if (command === "format") {
+        allowedOptions.add("--check");
+    }
+    if (command === "serve") {
+        allowedOptions.add("--host");
+        allowedOptions.add("--port");
+        allowedOptions.add("--open");
+    }
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        if (arg === undefined) {
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            return { error: `Unexpected argument: ${arg}` };
+        }
+        if (!allowedOptions.has(arg)) {
+            return { error: `Unsupported option for ${command}: ${arg}` };
+        }
+        if (optionsWithValues.has(arg)) {
+            index += 1;
+            continue;
+        }
+    }
+    return undefined;
+}
+function resolveServeOptions(rest) {
+    const hostValue = readOption(rest, "--host");
+    if (hostValue && "error" in hostValue) {
+        return hostValue;
+    }
+    const portValue = readOption(rest, "--port");
+    if (portValue && "error" in portValue) {
+        return portValue;
+    }
+    const host = hostValue?.value ?? "127.0.0.1";
+    const rawPort = portValue?.value;
+    const port = rawPort === undefined ? 4321 : Number(rawPort);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        return { error: "Invalid --port value." };
+    }
+    return { host, port, open: rest.includes("--open") };
+}
+function readOption(rest, name) {
+    const index = rest.findIndex((arg) => arg === name);
+    if (index < 0) {
+        return undefined;
+    }
+    const value = rest[index + 1];
+    if (!value || value.startsWith("-")) {
+        return { error: `Missing value after ${name}.` };
+    }
+    return { value };
+}
+function resolveOutPath(cwd, rest) {
+    const outIndex = rest.findIndex((arg) => arg === "--out" || arg === "-o");
+    if (outIndex < 0) {
+        return "";
+    }
+    const outArg = rest[outIndex + 1];
+    if (!outArg || outArg.startsWith("-")) {
+        return { error: "Missing output file after -o/--out." };
+    }
+    return resolve(cwd, outArg);
+}
+function resolveRenderFormat(rest) {
+    const raw = readOption(rest, "--format");
+    if (!raw) {
+        return undefined;
+    }
+    if ("error" in raw) {
+        return raw;
+    }
+    if (raw.value !== "document" && raw.value !== "fragment") {
+        return { error: "Invalid --format value. Expected document or fragment." };
+    }
+    return { format: raw.value };
+}
+async function runCliRequest(request, deps) {
+    if (request.command === "version") {
+        deps.stdoutWrite(`${VERSION}\n`);
+        return 0;
+    }
+    if (request.command === "help") {
+        return writeHelp(request.topic, deps.stdoutWrite, deps.stderrWrite);
+    }
+    if (request.command === "serve") {
+        const serveOptions = { evaluate: request.evaluate };
+        if (request.host !== undefined) {
+            serveOptions.host = request.host;
+        }
+        if (request.port !== undefined) {
+            serveOptions.port = request.port;
+        }
+        if (request.open !== undefined) {
+            serveOptions.open = request.open;
+        }
+        const handle = await deps.startServeFn(request.inputPath, serveOptions);
+        deps.stdoutWrite(`Serving ${request.inputPath}\n${formatTerminalLink(handle.url)}\n`);
+        return deps.stayOpenFn();
+    }
+    const text = await deps.readFileFn(request.inputPath, "utf8");
+    let ast;
+    const getAst = () => {
+        ast ??= parse(text);
+        return ast;
+    };
+    const handlers = {
+        parse: async () => writeStdoutJson(getAst(), deps.stdoutWrite),
+        evaluate: async () => writeStdoutJson(await evaluate(getAst()), deps.stdoutWrite),
+        format: async () => writeFormattedOutput(formatCello(text), text, request, deps),
+        validate: async () => writeValidationResult(await validate(text, { baseDir: dirname(request.inputPath) }), deps.stdoutWrite),
+        render: async () => writeCliOutput(await render(text, {
+            baseDir: dirname(request.inputPath),
+            evaluate: request.evaluate,
+            ...(request.renderFormat ? { format: request.renderFormat } : {})
+        }), request.outPath, deps, false),
+        serialize: async () => writeCliOutput(serialize(getAst()), request.outPath, deps, true)
+    };
+    return handlers[request.command]();
+}
+async function writeFormattedOutput(formatted, original, request, deps) {
+    const changed = formatted !== original;
+    if (request.check) {
+        deps.stdoutWrite(`${changed ? "Needs formatting" : "Already formatted"}: ${request.inputPath}\n`);
+        return changed ? 1 : 0;
+    }
+    const destination = request.outPath || request.inputPath;
+    if (!changed && destination === request.inputPath) {
+        deps.stdoutWrite(`Already formatted: ${request.inputPath}\n`);
+        return 0;
+    }
+    await deps.writeFileFn(destination, formatted, "utf8");
+    deps.stdoutWrite(`Wrote ${destination}\n`);
+    return 0;
+}
+function writeHelp(topic, stdoutWrite, stderrWrite) {
+    if (topic.length === 0) {
+        printUsage(stdoutWrite);
+        return 0;
+    }
+    const text = HELP_TEXT[topic];
+    if (!text) {
+        stderrWrite(`Unknown help topic: ${topic}\n`);
+        return 1;
+    }
+    stdoutWrite(text);
+    return 0;
+}
+function formatTerminalLink(url) {
+    return `\u001B]8;;${url}\u0007${url}\u001B]8;;\u0007`;
+}
+function writeValidationResult(value, stdoutWrite) {
+    writeStdoutJson(value, stdoutWrite);
+    return value.valid ? 0 : 1;
+}
+function writeStdoutJson(value, stdoutWrite) {
+    stdoutWrite(`${JSON.stringify(value, null, 2)}\n`);
+    return 0;
+}
+async function writeCliOutput(output, outPath, deps, appendTrailingNewline) {
+    if (outPath) {
+        await deps.writeFileFn(outPath, output, "utf8");
+        deps.stdoutWrite(`Wrote ${outPath}\n`);
+        return 0;
+    }
+    deps.stdoutWrite(appendTrailingNewline ? `${output}\n` : output);
+    return 0;
+}
+const isDirectExecution = process.argv[1] !== undefined && isDirectCliExecution(process.argv[1], import.meta.url);
+export function isDirectCliExecution(argvPath, moduleUrl) {
+    try {
+        return realpathSync(argvPath) === realpathSync(fileURLToPath(moduleUrl));
+    }
+    catch {
+        return pathToFileURL(argvPath).href === moduleUrl;
+    }
+}
+/* c8 ignore next 3 */
+if (isDirectExecution) {
+    void runMain(process.argv);
+}

package/dist/cli/serve.d.ts

@@ -0,0 +1,15 @@
+import { type FSWatcher } from "node:fs";
+import { type Server } from "node:http";
+export interface ServeOptions {
+    host?: string;
+    port?: number;
+    open?: boolean;
+    evaluate?: boolean;
+}
+export interface ServeHandle {
+    url: string;
+    server: Server;
+    watcher: FSWatcher;
+    close: () => Promise<void>;
+}
+export declare function startServe(filePath: string, options?: ServeOptions): Promise<ServeHandle>;

package/dist/cli/serve.js

@@ -0,0 +1,226 @@
+import { watch } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { basename, dirname, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { render } from "../renderer/render.js";
+const LIVE_VERSION_PATH = "/__cello/version";
+export async function startServe(filePath, options = {}) {
+    const inputPath = resolve(filePath);
+    const host = options.host ?? "127.0.0.1";
+    const port = options.port ?? 4321;
+    const servedPath = `/${encodeURIComponent(basename(inputPath))}`;
+    const renderer = createCachedRenderer(inputPath, options.evaluate !== false);
+    await renderer.refresh();
+    const server = createServer((request, response) => {
+        void handleRequest(request, response, renderer, servedPath);
+    });
+    const watcher = watch(inputPath, () => {
+        renderer.markDirty();
+    });
+    try {
+        await listen(server, port, host);
+        const address = server.address();
+        const boundPort = typeof address === "object" && address ? address.port : port;
+        const url = `http://${host}:${boundPort}${servedPath}`;
+        if (options.open) {
+            openBrowser(url);
+        }
+        return {
+            url,
+            server,
+            watcher,
+            close: async () => {
+                watcher.close();
+                await closeServer(server);
+            }
+        };
+    }
+    catch (err) {
+        if (server.listening) {
+            await closeServer(server);
+        }
+        throw err;
+    }
+    finally {
+        if (!server.listening) {
+            watcher.close();
+        }
+    }
+}
+function createCachedRenderer(inputPath, evaluateFormulas) {
+    let dirty = true;
+    let cached = "";
+    let version = 0;
+    let lastMtimeMs;
+    return {
+        markDirty: () => {
+            markDirty();
+        },
+        refresh: async () => {
+            await detectFileChange();
+            if (!dirty) {
+                return cached;
+            }
+            const text = await readFile(inputPath, "utf8");
+            cached = await render(text, {
+                baseDir: dirname(inputPath),
+                evaluate: evaluateFormulas,
+                title: inputPath
+            });
+            cached = injectLiveReload(cached);
+            lastMtimeMs = (await stat(inputPath)).mtimeMs;
+            dirty = false;
+            return cached;
+        },
+        version: async () => {
+            await detectFileChange();
+            return version;
+        }
+    };
+    function markDirty() {
+        if (!dirty) {
+            version += 1;
+        }
+        dirty = true;
+    }
+    async function detectFileChange() {
+        const currentMtimeMs = (await stat(inputPath)).mtimeMs;
+        if (lastMtimeMs !== undefined && currentMtimeMs !== lastMtimeMs) {
+            markDirty();
+        }
+    }
+}
+async function handleRequest(request, response, renderer, servedPath) {
+    const pathname = getPathname(request.url ?? "/");
+    if (request.method !== "GET" || !isKnownRoute(pathname, servedPath)) {
+        response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+        response.end("Not found\n");
+        return;
+    }
+    if (pathname === LIVE_VERSION_PATH) {
+        response.writeHead(200, {
+            "content-type": "application/json; charset=utf-8",
+            "cache-control": "no-store"
+        });
+        response.end(`${JSON.stringify({ version: await renderer.version() })}\n`);
+        return;
+    }
+    try {
+        const html = await renderer.refresh();
+        response.writeHead(200, {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store"
+        });
+        response.end(html);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        response.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+        response.end(`${message}\n`);
+    }
+}
+function getPathname(url) {
+    try {
+        return new URL(url, "http://localhost").pathname;
+    }
+    catch {
+        return "/";
+    }
+}
+function isKnownRoute(pathname, servedPath) {
+    return pathname === "/" || pathname === servedPath || pathname === LIVE_VERSION_PATH;
+}
+function injectLiveReload(html) {
+    const script = `<script>
+    (() => {
+      let currentVersion;
+      async function checkForCelloChanges() {
+        try {
+          const response = await fetch("${LIVE_VERSION_PATH}", { cache: "no-store" });
+          const data = await response.json();
+          if (currentVersion === undefined) {
+            currentVersion = data.version;
+            return;
+          }
+          if (data.version !== currentVersion) {
+            window.location.reload();
+          }
+        } catch {
+          // Keep the last rendered workbook visible if the dev server is stopped.
+        }
+      }
+      window.setInterval(checkForCelloChanges, 500);
+      void checkForCelloChanges();
+    })();
+  </script>`;
+    return html.replace("</body>", `${script}\n</body>`);
+}
+function listen(server, port, host) {
+    return new Promise((resolveListen, rejectListen) => {
+        const onError = (err) => {
+            server.off("listening", onListening);
+            rejectListen(err);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolveListen();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, host);
+    });
+}
+function closeServer(server) {
+    return new Promise((resolveClose, rejectClose) => {
+        server.close((err) => {
+            if (err) {
+                rejectClose(err);
+                return;
+            }
+            resolveClose();
+        });
+    });
+}
+function openBrowser(url) {
+    const commands = getOpenBrowserCommands(url);
+    let index = 0;
+    const tryOpen = () => {
+        const next = commands[index];
+        if (!next) {
+            return;
+        }
+        index += 1;
+        const child = spawn(next.command, next.args, {
+            detached: true,
+            stdio: "ignore"
+        });
+        child.once("error", tryOpen);
+        child.once("exit", (code) => {
+            if (code && code !== 0) {
+                tryOpen();
+            }
+        });
+        child.unref();
+    };
+    tryOpen();
+}
+function getOpenBrowserCommands(url) {
+    if (process.platform === "win32") {
+        return [{ command: "cmd.exe", args: ["/c", "start", "", url] }];
+    }
+    if (process.platform === "darwin") {
+        return [{ command: "open", args: [url] }];
+    }
+    if (isWsl()) {
+        return [
+            { command: "cmd.exe", args: ["/c", "start", "", url] },
+            { command: "wslview", args: [url] },
+            { command: "xdg-open", args: [url] }
+        ];
+    }
+    return [{ command: "xdg-open", args: [url] }];
+}
+function isWsl() {
+    return Boolean(process.env.WSL_DISTRO_NAME || process.env.WSL_INTEROP);
+}

package/dist/evaluator/evaluate.d.ts

@@ -0,0 +1,2 @@
+import type { EvaluateOptions, WorkbookAst } from "../shared/types.js";
+export declare function evaluate(ast: WorkbookAst, options?: EvaluateOptions): Promise<WorkbookAst>;