diff --git a/src/cli/build.ts b/src/cli/build.ts
new file mode 100644
index 0000000..2202d6b
--- /dev/null
+++ b/src/cli/build.ts
@@ -0,0 +1,74 @@
+import {
+ build as viteBuild,
+ preview as vitePreview,
+ createLogger,
+ type InlineConfig,
+ type PreviewServer,
+} from "vite";
+import { writeFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import type { DataExplorerConfig } from "./types.js";
+
+/**
+ * Build the data-explorer static site using Vite's API
+ */
+export async function build(
+ config: DataExplorerConfig,
+ packageRoot: string
+): Promise
{
+ const configPath = join(packageRoot, ".data-explorer-config.json");
+
+ writeFileSync(configPath, JSON.stringify(config, null, 2));
+
+ try {
+ process.env["DATA_EXPLORER_CONFIG_PATH"] = configPath;
+
+ const viteConfig: InlineConfig = {
+ root: packageRoot,
+ configFile: join(packageRoot, "vite.config.ts"),
+ build: {
+ outDir: config.outputPath,
+ emptyOutDir: true,
+ },
+ logLevel: "info",
+ customLogger: createLogger("info", { prefix: "[data-explorer]" }),
+ };
+
+ await viteBuild(viteConfig);
+
+ console.log("");
+ console.log("Build completed successfully!");
+ console.log(`Output: ${config.outputPath}`);
+ } finally {
+ if (existsSync(configPath)) {
+ rmSync(configPath);
+ }
+ delete process.env["DATA_EXPLORER_CONFIG_PATH"];
+ }
+}
+
+/**
+ * Preview the built site using Vite's preview server
+ */
+export async function preview(
+ outputPath: string,
+ port: number = 3000
+): Promise {
+ const viteConfig: InlineConfig = {
+ preview: {
+ port,
+ open: true,
+ },
+ build: {
+ outDir: outputPath,
+ },
+ };
+
+ const server = await vitePreview(viteConfig);
+
+ console.log("");
+ console.log(`Preview server running at:`);
+ server.printUrls();
+
+ return server;
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
new file mode 100644
index 0000000..c3699e6
--- /dev/null
+++ b/src/cli/index.ts
@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, statSync } from "node:fs";
+import { build, preview } from "./build.js";
+import { DEFAULT_CONFIG, type DataExplorerConfig } from "./types.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const HELP_TEXT = `
+data-explorer - Static site generator for Malloy data models and notebooks
+
+Usage:
+ data-explorer build [options]
+ data-explorer preview [options]
+
+Commands:
+ build Build the static site from Malloy files
+ preview Start a preview server for built site
+
+Build Options:
+ -o, --output Output directory for the built site (default: ./dist)
+ -t, --title Site title (default: "Data Explorer")
+ -d, --description <desc> Home page description
+ -b, --base-path <path> Base public path for deployment (default: "/")
+
+Preview Options:
+ -p, --port <port> Port for preview server (default: 3000)
+
+General Options:
+ -h, --help Show this help message
+ -v, --version Show version number
+
+Examples:
+ data-explorer build ./models
+ data-explorer build ./models -o ./dist -t "My Data Site"
+ data-explorer preview ./dist -p 8080
+`;
+
+function showHelp(): void {
+ console.log(HELP_TEXT);
+ process.exit(0);
+}
+
+function showVersion(): void {
+ console.log("data-explorer v0.0.1");
+ process.exit(0);
+}
+
+function validatePath(inputPath: string, mustBeDir: boolean = true): string {
+ const resolved = resolve(inputPath);
+ if (!existsSync(resolved)) {
+ console.error(`Error: Path does not exist: ${resolved}`);
+ process.exit(1);
+ }
+ if (mustBeDir && !statSync(resolved).isDirectory()) {
+ console.error(`Error: Path is not a directory: ${resolved}`);
+ process.exit(1);
+ }
+ return resolved;
+}
+
+async function main(): Promise<void> {
+ const { values, positionals } = parseArgs({
+ allowPositionals: true,
+ options: {
+ output: { type: "string", short: "o" },
+ title: { type: "string", short: "t" },
+ description: { type: "string", short: "d" },
+ "base-path": { type: "string", short: "b" },
+ port: { type: "string", short: "p" },
+ help: { type: "boolean", short: "h" },
+ version: { type: "boolean", short: "v" },
+ },
+ });
+
+ if (values.help) {
+ showHelp();
+ }
+
+ if (values.version) {
+ showVersion();
+ }
+
+ const command = positionals[0];
+
+ if (!command) {
+ console.error(
+ "Error: No command specified. Use --help for usage information."
+ );
+ process.exit(1);
+ }
+
+ // __dirname is dist-cli/, so go up one level to get project root
+ const packageRoot = resolve(__dirname, "..");
+
+ if (command === "build") {
+ const inputPath = positionals[1];
+ if (!inputPath) {
+ console.error("Error: No input path specified for build command.");
+ console.error("Usage: data-explorer build <input-path> [options]");
+ process.exit(1);
+ }
+
+ const config: DataExplorerConfig = {
+ inputPath: validatePath(inputPath),
+ outputPath: values.output ? resolve(values.output) : resolve("./dist"),
+ title: values.title ?? DEFAULT_CONFIG.title,
+ description: values.description ?? DEFAULT_CONFIG.description,
+ basePath: values["base-path"] ?? DEFAULT_CONFIG.basePath,
+ };
+
+ console.log("Building data-explorer site...");
+ console.log(` Input: ${config.inputPath}`);
+ console.log(` Output: ${config.outputPath}`);
+ console.log(` Title: ${config.title}`);
+ console.log(` Description: ${config.description}`);
+ console.log(` Base Path: ${config.basePath}`);
+ console.log("");
+
+ await build(config, packageRoot);
+ } else if (command === "preview") {
+ const distPath = positionals[1];
+ if (!distPath) {
+ console.error("Error: No dist path specified for preview command.");
+ console.error("Usage: data-explorer preview <dist-path> [options]");
+ process.exit(1);
+ }
+
+ const outputPath = validatePath(distPath);
+ const port = values.port ? parseInt(values.port, 10) : 3000;
+
+ console.log(`Starting preview server for: ${outputPath}`);
+ console.log(`Port: ${port}`);
+
+ await preview(outputPath, port);
+
+ // Keep the server running
+ await new Promise(() => {});
+ } else {
+ console.error(
+ `Error: Unknown command "${command}". Use --help for usage information.`
+ );
+ process.exit(1);
+ }
+}
+
+main().catch((error: unknown) => {
+ console.error("Error:", error);
+ process.exit(1);
+});
diff --git a/src/cli/types.ts b/src/cli/types.ts
new file mode 100644
index 0000000..c7229d7
--- /dev/null
+++ b/src/cli/types.ts
@@ -0,0 +1,21 @@
+/**
+ * Configuration for the data-explorer build
+ */
+export interface DataExplorerConfig {
+ /** Path to the directory containing Malloy files (.malloy, .malloynb) */
+ inputPath: string;
+ /** Path to output the built website */
+ outputPath: string;
+ /** Title for the site (shown in browser tab and home page) */
+ title: string;
+ /** Description shown on the home page */
+ description: string;
+ /** Base public path for deployment (e.g., "/my-repo/" for GitHub Pages) */
+ basePath: string;
+}
+
+export const DEFAULT_CONFIG: Omit<DataExplorerConfig, "inputPath" | "outputPath"> = {
+ title: "Data Explorer",
+ description: "Explore and analyze your Malloy models and notebooks",
+ basePath: "/",
+};
diff --git a/src/index.tsx b/src/index.tsx
index 91a3283..beb90cc 100644
--- a/src/index.tsx
+++ b/src/index.tsx
@@ -1,6 +1,10 @@
import { createRoot } from "react-dom/client";
import App from "./App";
import { StrictMode } from "react";
+import { getSiteConfig } from "./site-config";
+
+// Set document title from config
+document.title = getSiteConfig().title;
const rootElement = document.getElementById("root");
if (null === rootElement) {
diff --git a/src/site-config.ts b/src/site-config.ts
new file mode 100644
index 0000000..83acdd0
--- /dev/null
+++ b/src/site-config.ts
@@ -0,0 +1,15 @@
+/**
+ * Site configuration injected at build time via Vite's define option
+ */
+export interface SiteConfig {
+ title: string;
+ description: string;
+}
+
+declare global {
+ const __DATA_EXPLORER_CONFIG__: SiteConfig;
+}
+
+export function getSiteConfig(): SiteConfig {
+ return __DATA_EXPLORER_CONFIG__;
+}
diff --git a/tests/cli/cli.test.ts b/tests/cli/cli.test.ts
new file mode 100644
index 0000000..9d22eee
--- /dev/null
+++ b/tests/cli/cli.test.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execSync } from "node:child_process";
+import { existsSync, rmSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+const PROJECT_ROOT = resolve(__dirname, "../..");
+const CLI_PATH = join(PROJECT_ROOT, "dist-cli/index.js");
+const EXAMPLE_ECOMMERCE = join(PROJECT_ROOT, "examples/ecommerce");
+
+// Build CLI before tests
+beforeAll(() => {
+ console.log("Building CLI...");
+ execSync("npm run build:cli", { cwd: PROJECT_ROOT, stdio: "inherit" });
+}, 30000);
+
+describe("CLI smoke tests", () => {
+ describe("--help flag", () => {
+ it("should display help text", () => {
+ const output = execSync(`node ${CLI_PATH} --help`, {
+ encoding: "utf-8",
+ });
+
+ expect(output).toContain("data-explorer");
+ expect(output).toContain("build");
+ expect(output).toContain("preview");
+ expect(output).toContain("--output");
+ expect(output).toContain("--title");
+ expect(output).toContain("--description");
+ expect(output).toContain("--port");
+ });
+ });
+
+ describe("--version flag", () => {
+ it("should display version", () => {
+ const output = execSync(`node ${CLI_PATH} --version`, {
+ encoding: "utf-8",
+ });
+
+ expect(output).toContain("data-explorer");
+ expect(output).toMatch(/v?\d+\.\d+\.\d+/);
+ });
+ });
+
+ describe("build command validation", () => {
+ it("should error when no input path provided", () => {
+ expect(() => {
+ execSync(`node ${CLI_PATH} build`, {
+ encoding: "utf-8",
+ stdio: "pipe",
+ });
+ }).toThrow();
+ });
+
+ it("should error when input path does not exist", () => {
+ expect(() => {
+ execSync(`node ${CLI_PATH} build /nonexistent/path`, {
+ encoding: "utf-8",
+ stdio: "pipe",
+ });
+ }).toThrow();
+ });
+
+ it("should error when unknown command is given", () => {
+ expect(() => {
+ execSync(`node ${CLI_PATH} unknowncommand`, {
+ encoding: "utf-8",
+ stdio: "pipe",
+ });
+ }).toThrow();
+ });
+ });
+
+ describe("build command execution", () => {
+ const testOutputDir = join(PROJECT_ROOT, "test-output-cli");
+
+ afterAll(() => {
+ if (existsSync(testOutputDir)) {
+ rmSync(testOutputDir, { recursive: true, force: true });
+ }
+ });
+
+ it("should build example site successfully", () => {
+ if (existsSync(testOutputDir)) {
+ rmSync(testOutputDir, { recursive: true, force: true });
+ }
+
+ const output = execSync(
+ `node ${CLI_PATH} build ${EXAMPLE_ECOMMERCE} -o ${testOutputDir} -t "Test Site" -d "Test description"`,
+ {
+ encoding: "utf-8",
+ cwd: PROJECT_ROOT,
+ timeout: 120000,
+ }
+ );
+
+ expect(output).toContain("Build completed successfully");
+ expect(existsSync(testOutputDir)).toBe(true);
+ expect(existsSync(join(testOutputDir, "index.html"))).toBe(true);
+ expect(existsSync(join(testOutputDir, "assets"))).toBe(true);
+ }, 120000);
+
+ it("should produce valid HTML structure", () => {
+ const indexHtml = readFileSync(
+ join(testOutputDir, "index.html"),
+ "utf-8"
+ );
+
+ expect(indexHtml.toLowerCase()).toContain("<!doctype html>");
+ expect(indexHtml).toContain('<div id="root">');
+ });
+ });
+});
diff --git a/tsconfig.cli.json b/tsconfig.cli.json
new file mode 100644
index 0000000..98262c8
--- /dev/null
+++ b/tsconfig.cli.json
@@ -0,0 +1,22 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.cli.tsbuildinfo",
+ "target": "ES2022",
+ "lib": ["ES2023"],
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "outDir": "./dist-cli",
+ "rootDir": "./src/cli",
+ "skipLibCheck": true,
+ "esModuleInterop": true,
+ "isolatedModules": true,
+ "incremental": true,
+ "declaration": true,
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "noFallthroughCasesInSwitch": true,
+ "forceConsistentCasingInFileNames": true
+ },
+ "include": ["src/cli/**/*.ts"]
+}
diff --git a/tsconfig.json b/tsconfig.json
index 9a66b8a..78bdc79 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -8,6 +8,7 @@
"files": [],
"references": [
{ "path": "./tsconfig.app.json" },
- { "path": "./tsconfig.node.json" }
+ { "path": "./tsconfig.node.json" },
+ { "path": "./tsconfig.cli.json" }
]
}
diff --git a/vite.config.ts b/vite.config.ts
index bf25cdd..4c6c10f 100644
--- a/vite.config.ts
+++ b/vite.config.ts
@@ -2,14 +2,61 @@
import { defineConfig, type UserConfig } from "vite";
import react from "@vitejs/plugin-react";
import svgr from "vite-plugin-svgr";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+interface DataExplorerConfig {
+ inputPath: string;
+ outputPath: string;
+ title: string;
+ description: string;
+ basePath: string;
+}
+
+// Load config from file if it exists (when running via CLI)
+function loadConfig(): DataExplorerConfig | null {
+ const configPath =
+ process.env["DATA_EXPLORER_CONFIG_PATH"] ??
+ join(process.cwd(), ".data-explorer-config.json");
+
+ if (existsSync(configPath)) {
+ const content = readFileSync(configPath, "utf-8");
+ return JSON.parse(content) as DataExplorerConfig;
+ }
+ return null;
+}
+
+const cliConfig = loadConfig();
+
+// Default values for development (uses examples/sample-data)
+const siteConfig = {
+ title: cliConfig?.title ?? "Data Explorer",
+ description:
+ cliConfig?.description ??
+ "Explore and analyze your Malloy models and notebooks",
+ basePath: cliConfig?.basePath ?? process.env["BASE_PUBLIC_PATH"] ?? "/",
+ modelsPath:
+ cliConfig?.inputPath ?? resolve(process.cwd(), "examples/sample-data"),
+};
// https://vite.dev/config/
const config: UserConfig = defineConfig({
// NOTE: THIS PATH MUST END WITH A TRAILING SLASH
- base: process.env["BASE_PUBLIC_PATH"] ?? "/",
+ base: siteConfig.basePath.endsWith("/")
+ ? siteConfig.basePath
+ : siteConfig.basePath + "/",
plugins: [react(), svgr()],
define: {
"process.env": {},
+ __DATA_EXPLORER_CONFIG__: JSON.stringify({
+ title: siteConfig.title,
+ description: siteConfig.description,
+ }),
+ },
+ resolve: {
+ alias: {
+ "/models": siteConfig.modelsPath,
+ },
},
optimizeDeps: {
esbuildOptions: {
diff --git a/vitest.cli.config.ts b/vitest.cli.config.ts
new file mode 100644
index 0000000..7e1eb69
--- /dev/null
+++ b/vitest.cli.config.ts
@@ -0,0 +1,8 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+ test: {
+ include: ["tests/cli/**/*.test.ts"],
+ testTimeout: 60000, // CLI tests may take longer due to build process
+ },
+});