wildash-cli 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# WiLDash CLI
+
+Run analyses, check progress, and export results from the terminal.
+
+## Install
+
+```bash
+npm install -g wildash-cli
+```
+
+Or run without installing:
+
+```bash
+npx wildash-cli --help
+```
+
+## Quick Start
+
+```bash
+wildash login
+wildash run --log ./sample.csv --location ./locations.csv --wait
+wildash summary --latest
+wildash export --latest --target overview --out ./exports/
+```
+
+## Commands
+
+```
+wildash login           Sign in and store credentials
+wildash whoami          Show current account
+wildash logout          Remove local credentials
+wildash run             Upload files and start analysis
+wildash list            List recent analyses
+wildash status          Show analysis progress
+wildash cancel          Stop a running analysis
+wildash summary         Show analysis summary
+wildash export          Download results as ZIP
+```
+
+## Common Flags
+
+- `--latest` use your most recent analysis
+- `--json` print JSON instead of text
+- `--api-url` use a different WiLDash server
+
+## Environment Variables
+
+- `WILDASH_API_URL` sets the default server
+- `WILDASH_PASSWORD` lets `wildash login` run without a password prompt
+
+## Requirements
+
+- Node.js >= 18

package/bin/wildash.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/index.js");

package/dist/index.js

@@ -0,0 +1,850 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_commander = require("commander");
+
+// src/lib/errors.ts
+var CLIError = class extends Error {
+  hint;
+  exitCode;
+  constructor(message, opts) {
+    super(message);
+    this.name = "CLIError";
+    this.hint = opts?.hint;
+    this.exitCode = opts?.exitCode ?? 1;
+  }
+};
+
+// src/lib/output.ts
+function emit(opts) {
+  if (opts.jsonMode) {
+    console.log(
+      JSON.stringify(
+        { ok: true, command: opts.command, data: opts.data },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  for (const line of opts.lines ?? []) {
+    console.log(line);
+  }
+}
+function emitError(opts) {
+  const exitCode = opts.exitCode ?? 1;
+  if (opts.jsonMode) {
+    process.stderr.write(
+      JSON.stringify(
+        {
+          ok: false,
+          command: opts.command,
+          error: { message: opts.message, hint: opts.hint ?? null, exit_code: exitCode }
+        },
+        null,
+        2
+      ) + "\n"
+    );
+    return;
+  }
+  process.stderr.write(`Error: ${opts.message}
+`);
+  if (opts.hint) {
+    process.stderr.write(`Hint: ${opts.hint}
+`);
+  }
+}
+
+// src/commands/login.ts
+var import_prompts = require("@inquirer/prompts");
+
+// src/lib/operations.ts
+var import_node_fs3 = __toESM(require("fs"));
+var import_node_os2 = __toESM(require("os"));
+var import_node_path3 = __toESM(require("path"));
+
+// src/lib/client.ts
+var import_node_fs2 = __toESM(require("fs"));
+var import_node_path2 = __toESM(require("path"));
+var import_node_stream = require("stream");
+
+// src/lib/constants.ts
+var DEFAULT_API_URL = "http://127.0.0.1:8000/api";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var UPLOAD_TIMEOUT_MS = 30 * 6e4;
+var EXPORT_TARGET_ALIASES = {
+  overview: "overview",
+  map: "flow_map",
+  flow_map: "flow_map",
+  network: "flow_network",
+  flow_network: "flow_network",
+  temporal: "temporal",
+  all: "all"
+};
+var TERMINAL_SESSION_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "paused"
+]);
+
+// src/lib/state.ts
+var import_node_fs = __toESM(require("fs"));
+var import_node_path = __toESM(require("path"));
+var import_node_os = __toESM(require("os"));
+function configDir() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".config", "wildash");
+}
+function authStorePath() {
+  return import_node_path.default.join(configDir(), "auth.json");
+}
+function legacyAuthStorePath() {
+  return import_node_path.default.join(import_node_os.default.homedir(), ".wildash", "credentials.json");
+}
+function readJsonFile(filePath) {
+  try {
+    return import_node_fs.default.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function loadAuthState() {
+  for (const filePath of [authStorePath(), legacyAuthStorePath()]) {
+    const raw = readJsonFile(filePath);
+    if (!raw) continue;
+    try {
+      const data = JSON.parse(raw);
+      if (typeof data === "object" && data !== null && !Array.isArray(data)) return data;
+    } catch {
+      throw new CLIError(`State file contains invalid JSON: ${filePath}`, {
+        hint: `Fix or remove ${filePath} and retry.`
+      });
+    }
+  }
+  return {};
+}
+function saveAuthState(payload) {
+  const filePath = authStorePath();
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(filePath), { recursive: true });
+  import_node_fs.default.writeFileSync(
+    filePath,
+    JSON.stringify(payload, null, 2) + "\n",
+    "utf-8"
+  );
+}
+function unlinkIfExists(filePath) {
+  try {
+    import_node_fs.default.unlinkSync(filePath);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+}
+function clearAuthState() {
+  unlinkIfExists(authStorePath());
+  unlinkIfExists(legacyAuthStorePath());
+}
+
+// src/lib/client.ts
+function normalizeApiRoot(value) {
+  let text = (value ?? "").trim() || process.env.WILDASH_API_URL || DEFAULT_API_URL;
+  text = text.replace(/\/+$/, "");
+  if (text.endsWith("/api/v2")) return text;
+  if (text.endsWith("/api")) return `${text}/v2`;
+  if (text.endsWith("/v2")) return text;
+  return `${text}/api/v2`;
+}
+function extractErrorDetail(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    const obj = body;
+    const detail = String(obj.detail ?? obj.error ?? "").trim();
+    if (detail) return detail;
+    const nonField = obj.non_field_errors;
+    if (Array.isArray(nonField) && nonField.length) return String(nonField[0]).trim();
+  }
+  if (Array.isArray(body) && body.length) return String(body[0]).trim();
+  return "Request failed.";
+}
+var MIME_TYPES = {
+  ".csv": "text/csv",
+  ".json": "application/json",
+  ".txt": "text/plain",
+  ".log": "text/plain",
+  ".zip": "application/zip"
+};
+var APIClient = class {
+  authState;
+  apiRoot;
+  constructor(apiRoot) {
+    this.authState = loadAuthState();
+    this.apiRoot = normalizeApiRoot(apiRoot || this.authState.api_root);
+  }
+  url(p) {
+    return `${this.apiRoot}/${p.replace(/^\/+/, "")}`;
+  }
+  getAccessToken() {
+    const token = this.authState.access?.trim();
+    if (token) return token;
+    throw new CLIError("Not logged in.", { hint: "Run 'wildash login'.", exitCode: 2 });
+  }
+  async refreshAccessToken() {
+    const refresh = this.authState.refresh?.trim();
+    if (!refresh) {
+      throw new CLIError("Session expired.", { hint: "Run 'wildash login'.", exitCode: 2 });
+    }
+    const res = await fetch(this.url("auth/refresh/"), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refresh }),
+      signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS)
+    });
+    if (res.status !== 200) {
+      clearAuthState();
+      this.authState = {};
+      throw new CLIError("Session expired.", { hint: "Run 'wildash login'.", exitCode: 2 });
+    }
+    const payload = await res.json();
+    const access = String(payload.access ?? "").trim();
+    if (!access) {
+      clearAuthState();
+      this.authState = {};
+      throw new CLIError("Session refresh failed.", { hint: "Run 'wildash login'.", exitCode: 2 });
+    }
+    this.authState.access = access;
+    this.authState.api_root = this.apiRoot;
+    saveAuthState(this.authState);
+  }
+  async request(method, urlPath, opts) {
+    const auth = opts?.auth ?? true;
+    const allowRefresh = opts?.allowRefresh ?? true;
+    const timeout = opts?.timeout ?? DEFAULT_TIMEOUT_MS;
+    const headers = {};
+    if (auth) headers["Authorization"] = `Bearer ${this.getAccessToken()}`;
+    let body;
+    if (opts?.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(opts.json);
+    }
+    const doFetch = () => fetch(this.url(urlPath), { method, headers, body, signal: AbortSignal.timeout(timeout) });
+    let res = await doFetch();
+    if (res.status === 401 && auth && allowRefresh) {
+      await this.refreshAccessToken();
+      headers["Authorization"] = `Bearer ${this.getAccessToken()}`;
+      res = await doFetch();
+    }
+    return res;
+  }
+  async requestJson(method, urlPath, opts) {
+    const res = await this.request(method, urlPath, opts);
+    if (res.status >= 400) await this.raiseForError(res);
+    const text = await res.text();
+    if (!text) return {};
+    try {
+      return JSON.parse(text);
+    } catch (e) {
+      throw new CLIError(`Invalid JSON response from server: ${e}`);
+    }
+  }
+  async raiseForError(res) {
+    const text = await res.text().catch(() => "");
+    let body;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new CLIError(`${res.status} ${res.statusText}: ${text || "Request failed."}`);
+    }
+    let hint;
+    let exitCode = 1;
+    if (body && typeof body === "object" && !Array.isArray(body)) {
+      const obj = body;
+      if (String(obj.error_code ?? "").toUpperCase() === "LEGAL_CONSENT_REQUIRED") {
+        const url = String(obj.legal_url ?? "").trim();
+        hint = url ? `You need to accept the latest terms before continuing. Open ${url} and accept them, then try again.` : "You need to accept the latest terms in WiLDash before continuing.";
+        exitCode = 3;
+      }
+    }
+    throw new CLIError(`${res.status} ${res.statusText}: ${extractErrorDetail(body)}`, { hint, exitCode });
+  }
+  async uploadToPresignedUrl(url, filePath) {
+    const ext = import_node_path2.default.extname(filePath).toLowerCase();
+    const contentType = MIME_TYPES[ext] ?? "application/octet-stream";
+    const stat = import_node_fs2.default.statSync(filePath);
+    const body = import_node_stream.Readable.toWeb(import_node_fs2.default.createReadStream(filePath));
+    const res = await fetch(url, {
+      method: "PUT",
+      headers: { "Content-Type": contentType, "Content-Length": String(stat.size) },
+      body,
+      // @ts-expect-error -- Node fetch requires duplex for streaming bodies
+      duplex: "half",
+      signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS)
+    });
+    if (res.status < 200 || res.status >= 300) {
+      const detail = (await res.text()).trim();
+      throw new CLIError(detail || `Upload failed (${res.status}).`);
+    }
+  }
+};
+
+// src/lib/operations.ts
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function expandHome(p) {
+  if (p === "~") return import_node_os2.default.homedir();
+  return p.startsWith("~/") ? import_node_path3.default.join(import_node_os2.default.homedir(), p.slice(2)) : p;
+}
+function ensureFile(filePath, label) {
+  const resolved = import_node_path3.default.resolve(expandHome(filePath));
+  if (!import_node_fs3.default.existsSync(resolved) || !import_node_fs3.default.statSync(resolved).isFile()) {
+    throw new CLIError(`${label} file not found: ${resolved}`);
+  }
+  return resolved;
+}
+async function login(opts) {
+  if (!opts.email?.trim()) throw new CLIError("Email is required.");
+  if (!opts.password) throw new CLIError("Password is required.");
+  const client = new APIClient(normalizeApiRoot(opts.apiRoot));
+  const payload = await client.requestJson("POST", "auth/sign-in/", {
+    auth: false,
+    allowRefresh: false,
+    json: { email: opts.email.trim(), password: opts.password }
+  });
+  const access = payload.tokens?.access?.trim();
+  const refresh = payload.tokens?.refresh?.trim();
+  if (!access || !refresh) {
+    throw new CLIError("Login succeeded but tokens are missing from the response.");
+  }
+  const authState = { api_root: client.apiRoot, access, refresh, user: payload.user ?? {} };
+  saveAuthState(authState);
+  return { api_root: client.apiRoot, user: authState.user };
+}
+async function whoami(opts) {
+  return new APIClient(opts.apiRoot).requestJson("GET", "auth/me/");
+}
+async function createSession(opts) {
+  const name = opts.name?.trim();
+  if (!name) throw new CLIError("Session name is required.");
+  const body = { name };
+  if (opts.description) body.description = opts.description;
+  return new APIClient(opts.apiRoot).requestJson("POST", "sessions/", { json: body });
+}
+async function listSessions(opts) {
+  const payload = await new APIClient(opts.apiRoot).requestJson("GET", "sessions/");
+  let rows = Array.isArray(payload) ? payload : payload.results ?? [];
+  const wantedStatus = opts.status?.trim().toLowerCase();
+  if (wantedStatus) {
+    rows = rows.filter((r) => String(r.status ?? "").toLowerCase() === wantedStatus);
+  }
+  const limit = Number.isFinite(opts.limit) ? Math.max(1, opts.limit) : 20;
+  const sliced = rows.slice(0, limit);
+  return { count: sliced.length, sessions: sliced };
+}
+async function resolveLatestSessionId(apiRoot) {
+  const { sessions } = await listSessions({ apiRoot, limit: 1 });
+  if (!sessions.length) {
+    throw new CLIError("No analyses found.", {
+      hint: "Run 'wildash run --log <file>' to start your first analysis."
+    });
+  }
+  return String(sessions[0].id);
+}
+async function resolveSessionId(opts) {
+  if (opts.sessionId?.trim()) return opts.sessionId.trim();
+  if (opts.latest) return resolveLatestSessionId(opts.apiRoot);
+  throw new CLIError("Analysis ID is required.", {
+    hint: "Run 'wildash list' to choose one, or use --latest."
+  });
+}
+async function getSessionStatus(opts) {
+  return new APIClient(opts.apiRoot).requestJson(
+    "GET",
+    `sessions/${opts.sessionId}/status/`
+  );
+}
+function statusFingerprint(p) {
+  const stages = (p.stages ?? []).map((s) => `${s.code}:${s.status}:${s.progress ?? 0}`).join("|");
+  return `${p.status}:${p.progress ?? 0}:${stages}`;
+}
+async function waitForSession(opts) {
+  let lastFp = "";
+  const pollMs = Math.max(500, (Number.isFinite(opts.pollSeconds) ? opts.pollSeconds : 4) * 1e3);
+  while (true) {
+    const payload = await getSessionStatus({ apiRoot: opts.apiRoot, sessionId: opts.sessionId });
+    const fp = statusFingerprint(payload);
+    if (fp !== lastFp) opts.onUpdate?.(payload);
+    lastFp = fp;
+    if (TERMINAL_SESSION_STATUSES.has((payload.status ?? "").toLowerCase())) return payload;
+    await sleep(pollMs);
+  }
+}
+async function cancelSession(opts) {
+  const body = opts.reason ? { reason: opts.reason.trim() } : {};
+  return new APIClient(opts.apiRoot).requestJson("POST", `sessions/${opts.sessionId}/stop/`, { json: body });
+}
+async function runSession(opts) {
+  const client = new APIClient(opts.apiRoot);
+  const logFile = ensureFile(opts.logPath, "Log");
+  const locationFile = opts.locationPath ? ensureFile(opts.locationPath, "Location") : void 0;
+  const sessionName = opts.name?.trim() || import_node_path3.default.basename(logFile);
+  const sessionDescription = opts.description?.trim() || `CLI run created at ${(/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z")}`;
+  const session = await createSession({
+    apiRoot: opts.apiRoot,
+    name: sessionName,
+    description: sessionDescription
+  });
+  const sessionId = session.id;
+  if (!sessionId) throw new CLIError("Failed to create session: missing session ID in response.");
+  const files = [{ kind: "log", filename: import_node_path3.default.basename(logFile) }];
+  if (locationFile) files.push({ kind: "location", filename: import_node_path3.default.basename(locationFile) });
+  let presign;
+  try {
+    presign = await client.requestJson("POST", `sessions/${sessionId}/uploads-presign/`, {
+      json: { files }
+    });
+  } catch (e) {
+    if (e instanceof CLIError && /Upload service is (unavailable|not configured)/.test(e.message)) {
+      throw new CLIError(e.message, {
+        hint: "This WiLDash server is not ready for uploads yet. Use the preview stack or ask for uploads to be enabled, then try 'wildash run' again.",
+        exitCode: e.exitCode
+      });
+    }
+    throw e;
+  }
+  const uploads = presign.uploads ?? [];
+  const uploadMap = new Map(uploads.map((u) => [u.kind, u]));
+  const logUpload = uploadMap.get("log");
+  if (!logUpload?.url) throw new CLIError("Upload target missing for log file.");
+  await client.uploadToPresignedUrl(logUpload.url, logFile);
+  const completePayload = {
+    log_key: logUpload.key ?? "",
+    log_name: import_node_path3.default.basename(logFile)
+  };
+  if (locationFile) {
+    const locUpload = uploadMap.get("location");
+    if (!locUpload?.url) throw new CLIError("Upload target missing for location file.");
+    await client.uploadToPresignedUrl(locUpload.url, locationFile);
+    completePayload.location_key = locUpload.key ?? "";
+    completePayload.location_name = import_node_path3.default.basename(locationFile);
+  }
+  await client.requestJson("POST", `sessions/${sessionId}/uploads-complete/`, { json: completePayload });
+  await client.requestJson("POST", `sessions/${sessionId}/run/`, { json: {} });
+  const status = opts.wait ? await waitForSession({ apiRoot: opts.apiRoot, sessionId, pollSeconds: opts.pollSeconds, onUpdate: opts.onUpdate }) : await getSessionStatus({ apiRoot: opts.apiRoot, sessionId });
+  return { session_id: sessionId, name: sessionName, description: sessionDescription, wait: !!opts.wait, status };
+}
+async function getSummary(opts) {
+  const client = new APIClient(opts.apiRoot);
+  const res = await client.request("GET", `analytics/${opts.sessionId}/summary/`);
+  if (res.status >= 400) {
+    if (res.status === 404) {
+      let detail;
+      try {
+        const body = await res.json();
+        detail = body.detail ?? body.error;
+      } catch {
+      }
+      throw new CLIError(detail || "Summary not found.", {
+        hint: `Check the analysis ID, or run 'wildash status ${opts.sessionId} --watch' and wait for completion.`
+      });
+    }
+    await client.raiseForError(res);
+  }
+  const text = await res.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new CLIError(`Invalid JSON response from summary endpoint: ${e}`);
+  }
+}
+function resolveExportTarget(target) {
+  const backend = EXPORT_TARGET_ALIASES[target.toLowerCase()];
+  if (!backend) {
+    throw new CLIError(`Unsupported export target: ${target}`, {
+      hint: "Supported targets: overview, map, network, temporal, all"
+    });
+  }
+  const display = backend === "flow_map" ? "map" : backend === "flow_network" ? "network" : backend;
+  return { display, backend };
+}
+function filenameFromDisposition(disposition) {
+  for (const part of disposition.split(";")) {
+    const seg = part.trim();
+    if (seg.toLowerCase().startsWith("filename=")) {
+      return seg.split("=")[1]?.trim().replace(/"/g, "") ?? "";
+    }
+  }
+  return "";
+}
+async function downloadExport(opts) {
+  const { display, backend } = resolveExportTarget(opts.target);
+  const client = new APIClient(opts.apiRoot);
+  const res = await client.request("POST", `results/${opts.sessionId}/export/`, { json: { target: backend } });
+  if (res.status >= 400) await client.raiseForError(res);
+  const buffer = Buffer.from(await res.arrayBuffer());
+  const outRaw = opts.out.trim();
+  if (!outRaw) throw new CLIError("Output path is required.");
+  const resolved = import_node_path3.default.resolve(expandHome(outRaw));
+  const isDir = outRaw.endsWith("/") || outRaw.endsWith(import_node_path3.default.sep) || import_node_fs3.default.existsSync(resolved) && import_node_fs3.default.statSync(resolved).isDirectory();
+  const outPath = isDir ? import_node_path3.default.join(resolved, filenameFromDisposition(res.headers.get("Content-Disposition") ?? "") || `analytics-${opts.sessionId}-${backend}.zip`) : resolved;
+  import_node_fs3.default.mkdirSync(import_node_path3.default.dirname(outPath), { recursive: true });
+  import_node_fs3.default.writeFileSync(outPath, buffer);
+  return { session_id: opts.sessionId, target: display, backend_target: backend, output: import_node_path3.default.resolve(outPath), bytes: buffer.byteLength };
+}
+function clearCredentials() {
+  clearAuthState();
+  return { logged_out: true };
+}
+
+// src/commands/login.ts
+function registerLogin(program2) {
+  program2.command("login").description("Sign in to WiLDash and store local credentials.").option("--email <email>", "Email address.").option("--password <password>", "Password.").option("--api-url <url>", "Use a different WiLDash server.").action(async (opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const email = opts.email?.trim() || await (0, import_prompts.input)({ message: "Email:" });
+    const password = opts.password || process.env.WILDASH_PASSWORD || await (0, import_prompts.password)({ message: "Password:" });
+    const result = await login({ apiRoot: opts.apiUrl, email, password });
+    emit({
+      jsonMode,
+      command: "login",
+      data: result,
+      lines: [`Signed In: ${result.user.email ?? ""}`, `Server: ${result.api_root}`]
+    });
+  });
+}
+
+// src/commands/logout.ts
+function registerLogout(program2) {
+  program2.command("logout").description("Remove local credentials.").action(() => {
+    const jsonMode = program2.opts().json ?? false;
+    const result = clearCredentials();
+    emit({
+      jsonMode,
+      command: "logout",
+      data: result,
+      lines: ["Logout: success"]
+    });
+  });
+}
+
+// src/commands/whoami.ts
+function registerWhoami(program2) {
+  program2.command("whoami").description("Show the currently signed-in account.").option("--api-url <url>", "Use a different WiLDash server.").action(async (opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const result = await whoami({ apiRoot: opts.apiUrl });
+    emit({
+      jsonMode,
+      command: "whoami",
+      data: result,
+      lines: [
+        `Email: ${result.email ?? ""}`,
+        `Organization: ${result.organization_name ?? ""}`,
+        `Username: ${result.username ?? ""}`,
+        `User ID: ${result.id ?? ""}`
+      ]
+    });
+  });
+}
+
+// src/commands/run.ts
+function registerRun(program2) {
+  program2.command("run").description("Create a session, upload files, and start analysis.").requiredOption("--log <path>", "Path to the Wi-Fi log file.").option("--location <path>", "Optional locations CSV file.").option("--name <name>", "Name for the analysis.").option("--description <text>", "Short note for this analysis.").option("--wait", "Stay until the analysis finishes.", false).option("--poll <seconds>", "Seconds between checks while waiting.", "4").option("--api-url <url>", "Use a different WiLDash server.").action(async (opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const onUpdate = opts.wait ? (payload) => {
+      if (!jsonMode) {
+        process.stderr.write(`Status: ${payload.status ?? ""} (${payload.progress ?? 0}%)
+`);
+      }
+    } : void 0;
+    const result = await runSession({
+      apiRoot: opts.apiUrl,
+      logPath: opts.log,
+      locationPath: opts.location,
+      name: opts.name,
+      description: opts.description,
+      wait: opts.wait,
+      pollSeconds: parseFloat(opts.poll),
+      onUpdate
+    });
+    const { status } = result;
+    const finalStatus = (status.status ?? "").toLowerCase();
+    if (opts.wait && finalStatus !== "completed") {
+      throw new CLIError(`Analysis ended with status '${finalStatus}'.`, {
+        hint: status.last_error?.trim() || void 0
+      });
+    }
+    const lines = [
+      `Analysis ID: ${result.session_id}`,
+      `Name: ${result.name}`,
+      `Status: ${status.status ?? ""}`,
+      `Progress: ${status.progress ?? 0}%`
+    ];
+    lines.push(opts.wait ? "Finished: yes" : `Next: wildash status ${result.session_id} --watch`);
+    emit({ jsonMode, command: "run", data: result, lines });
+  });
+}
+
+// src/commands/list.ts
+function formatListLines(rows) {
+  if (!rows.length) return ["No analyses found."];
+  const headers = ["ID", "STATUS", "PROGRESS", "UPDATED", "NAME"];
+  const table = rows.map((item) => [
+    String(item.id ?? ""),
+    String(item.status ?? ""),
+    `${Number(item.progress ?? 0)}%`,
+    String(item.updated_at ?? ""),
+    String(item.name ?? "").replace(/\t/g, " ")
+  ]);
+  const widths = headers.map((h) => h.length);
+  for (const row of table) {
+    for (let i = 0; i < row.length; i++) {
+      widths[i] = Math.max(widths[i], row[i].length);
+    }
+  }
+  const render = (row) => row.map((val, i) => val.padEnd(widths[i])).join("  ");
+  return [
+    render(headers),
+    render(widths.map((w) => "-".repeat(w))),
+    ...table.map(render)
+  ];
+}
+function registerList(program2) {
+  program2.command("list").description("List recent analysis sessions.").option("--status <status>", "Only show analyses with this status.").option("--limit <n>", "Maximum number of analyses to show.", "20").option("--api-url <url>", "Use a different WiLDash server.").action(async (opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const result = await listSessions({
+      apiRoot: opts.apiUrl,
+      status: opts.status,
+      limit: parseInt(opts.limit, 10)
+    });
+    emit({
+      jsonMode,
+      command: "list",
+      data: result,
+      lines: formatListLines(result.sessions)
+    });
+  });
+}
+
+// src/commands/status.ts
+function statusLines(payload) {
+  const lines = [
+    `Analysis ID: ${payload.id ?? ""}`,
+    `Name: ${payload.name ?? ""}`,
+    `Status: ${payload.status ?? ""}`,
+    `Progress: ${payload.progress ?? 0}%`
+  ];
+  if (payload.total_records != null) {
+    lines.push(`Total Records: ${payload.total_records}`);
+  }
+  if (payload.total_flows != null) {
+    lines.push(`Total Flows: ${payload.total_flows}`);
+  }
+  const lastError = (payload.last_error ?? "").trim();
+  if (lastError) lines.push(`Last Error: ${lastError}`);
+  const stages = Array.isArray(payload.stages) ? payload.stages : [];
+  for (const stage of stages) {
+    if (typeof stage === "object" && stage !== null) {
+      lines.push(
+        `Stage ${stage.code ?? ""}: ${stage.status ?? ""} (${stage.progress ?? 0}%)`
+      );
+    }
+  }
+  return lines;
+}
+function registerStatus(program2) {
+  program2.command("status [analysis-id]").description("Show progress for an analysis.").option("--latest", "Use your most recent analysis.", false).option("--watch", "Keep checking until the analysis finishes.", false).option("--poll <seconds>", "Seconds between checks while watching.", "4").option("--api-url <url>", "Use a different WiLDash server.").action(async (sessionIdArg, opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const resolvedId = await resolveSessionId({
+      apiRoot: opts.apiUrl,
+      sessionId: sessionIdArg,
+      latest: opts.latest
+    });
+    let result;
+    if (opts.watch) {
+      result = await waitForSession({
+        apiRoot: opts.apiUrl,
+        sessionId: resolvedId,
+        pollSeconds: parseFloat(opts.poll),
+        onUpdate: (payload) => {
+          if (!jsonMode) {
+            process.stderr.write(
+              `Status: ${payload.status ?? ""} (${payload.progress ?? 0}%)
+`
+            );
+          }
+        }
+      });
+    } else {
+      result = await getSessionStatus({
+        apiRoot: opts.apiUrl,
+        sessionId: resolvedId
+      });
+    }
+    const lines = statusLines(result);
+    if (!opts.watch && !TERMINAL_SESSION_STATUSES.has((result.status ?? "").trim().toLowerCase())) {
+      lines.push(`Next: wildash status ${resolvedId} --watch`);
+    }
+    emit({
+      jsonMode,
+      command: "status",
+      data: result,
+      lines
+    });
+  });
+}
+
+// src/commands/cancel.ts
+function registerCancel(program2) {
+  program2.command("cancel [analysis-id]").description("Stop a running analysis.").option("--latest", "Use your most recent analysis.", false).option("--reason <text>", "Optional reason.").option("--api-url <url>", "Use a different WiLDash server.").action(async (sessionIdArg, opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const resolvedId = await resolveSessionId({
+      apiRoot: opts.apiUrl,
+      sessionId: sessionIdArg,
+      latest: opts.latest
+    });
+    const result = await cancelSession({
+      apiRoot: opts.apiUrl,
+      sessionId: resolvedId,
+      reason: opts.reason
+    });
+    emit({
+      jsonMode,
+      command: "cancel",
+      data: result,
+      lines: [
+        `Analysis ID: ${result.id ?? resolvedId}`,
+        `Status: ${result.status ?? ""}`,
+        "Cancellation: requested"
+      ]
+    });
+  });
+}
+
+// src/commands/summary.ts
+function summaryLines(payload, session) {
+  const lines = [];
+  if (session) {
+    lines.push(`Analysis ID: ${session.id ?? ""}`, `Name: ${session.name ?? ""}`);
+  }
+  lines.push(
+    `Total Unique Users: ${payload.total_unique_users ?? 0}`,
+    `Total Movements: ${payload.total_movements ?? 0}`,
+    `Date Range: ${payload.date_range_start ?? ""} -> ${payload.date_range_end ?? ""}`
+  );
+  const preview = (payload.top_locations ?? []).slice(0, 3).map((loc) => `${loc.building ?? ""} (${loc.visit_count ?? 0})`);
+  if (preview.length) lines.push(`Top Locations: ${preview.join(", ")}`);
+  if (payload.ai_insights?.trim()) lines.push(`AI Insights: ${payload.ai_insights.trim()}`);
+  return lines;
+}
+function registerSummary(program2) {
+  program2.command("summary [analysis-id]").description("Show the summary for an analysis.").option("--latest", "Use your most recent analysis.", false).option("--api-url <url>", "Use a different WiLDash server.").action(async (sessionIdArg, opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const resolvedId = await resolveSessionId({
+      apiRoot: opts.apiUrl,
+      sessionId: sessionIdArg,
+      latest: opts.latest
+    });
+    const session = await getSessionStatus({ apiRoot: opts.apiUrl, sessionId: resolvedId });
+    const summary = await getSummary({ apiRoot: opts.apiUrl, sessionId: resolvedId });
+    emit({
+      jsonMode,
+      command: "summary",
+      data: { session, summary },
+      lines: summaryLines(summary, session)
+    });
+  });
+}
+
+// src/commands/export.ts
+function registerExport(program2) {
+  program2.command("export [analysis-id]").description("Download a results bundle as a ZIP file.").option("--latest", "Use your most recent analysis.", false).requiredOption(
+    "--target <target>",
+    "Which results bundle to download (overview, map, network, temporal, all)."
+  ).requiredOption(
+    "--out <path>",
+    "ZIP file or folder path. End with / to save into a folder."
+  ).option("--api-url <url>", "Use a different WiLDash server.").action(async (sessionIdArg, opts) => {
+    const jsonMode = program2.opts().json ?? false;
+    const resolvedId = await resolveSessionId({
+      apiRoot: opts.apiUrl,
+      sessionId: sessionIdArg,
+      latest: opts.latest
+    });
+    const result = await downloadExport({
+      apiRoot: opts.apiUrl,
+      sessionId: resolvedId,
+      target: opts.target,
+      out: opts.out
+    });
+    emit({
+      jsonMode,
+      command: "export",
+      data: result,
+      lines: [
+        `Analysis ID: ${result.session_id}`,
+        `Target: ${result.target}`,
+        `Saved To: ${result.output}`,
+        `Size: ${result.bytes} bytes`
+      ]
+    });
+  });
+}
+
+// src/index.ts
+var program = new import_commander.Command();
+program.name("wildash").version("0.1.0").description("Run WiLDash analyses from the terminal.\n\nTypical flow: login, run, status, summary, export.").option("--json", "Print JSON instead of text.", false).helpOption("-h, --help").exitOverride().configureOutput({
+  writeOut: (str) => process.stdout.write(str),
+  writeErr: (str) => {
+    if (!process.argv.includes("--json")) process.stderr.write(str);
+  }
+});
+registerLogin(program);
+registerLogout(program);
+registerWhoami(program);
+registerRun(program);
+registerList(program);
+registerStatus(program);
+registerCancel(program);
+registerSummary(program);
+registerExport(program);
+function isJsonRequested() {
+  return program.opts().json || process.argv.includes("--json");
+}
+async function main() {
+  try {
+    await program.parseAsync(process.argv);
+  } catch (err) {
+    const jsonMode = isJsonRequested();
+    const command = `wildash ${program.args[0] ?? ""}`.trim();
+    if (err instanceof import_commander.CommanderError && err.exitCode === 0) process.exit(0);
+    if (err instanceof CLIError) {
+      emitError({ jsonMode, command, message: err.message, hint: err.hint, exitCode: err.exitCode });
+      process.exit(err.exitCode);
+    }
+    if (err instanceof Error) {
+      emitError({ jsonMode, command, message: err.message });
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+main();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "wildash-cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for WiLDash",
+  "license": "Proprietary",
+  "homepage": "https://wildash.space",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/QingrongY/WilDash_webapp.git",
+    "directory": "packages/wildash-cli"
+  },
+  "bin": {
+    "wildash": "./bin/wildash.js",
+    "wildash-cli": "./bin/wildash.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "lint": "eslint src/",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "commander": "^13.0.0",
+    "@inquirer/prompts": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}