@hexclave/cli 1.0.61 → 1.0.63

package/src/lib/dashboard-release.ts

@@ -166,7 +166,7 @@ async function sha256File(path: string): Promise<string> {
   return hash.digest("hex");
 }
 
-async function downloadDashboardRelease(manifest: DashboardManifest): Promise<void> {
+async function downloadDashboardRelease(manifest: DashboardManifest, onProgress?: (message: string) => void): Promise<void> {
   const cacheRoot = dashboardCacheRoot();
   mkdirSync(cacheRoot, { recursive: true });
   // Unique temp names so parallel runs don't collide; publish is an atomic rename.
@@ -175,6 +175,7 @@ async function downloadDashboardRelease(manifest: DashboardManifest): Promise<vo
   const tmpDir = join(cacheRoot, `.extract-${manifest.version}-${suffix}`);
   const targetDir = dashboardVersionDir(manifest.version);
   try {
+    onProgress?.(`Downloading Hexclave dashboard ${manifest.version}`);
     const response = await fetch(manifest.url, { redirect: "follow", signal: AbortSignal.timeout(DASHBOARD_DOWNLOAD_TIMEOUT_MS) });
     // The manifest URL passed isAllowedDownloadUrl, but redirects can land on a
     // different host/scheme; re-check the final URL before streaming the archive.
@@ -186,6 +187,7 @@ async function downloadDashboardRelease(manifest: DashboardManifest): Promise<vo
     }
     await pipeline(Readable.fromWeb(response.body as Parameters<typeof Readable.fromWeb>[0]), createWriteStream(tmpZip));
 
+    onProgress?.(`Verifying Hexclave dashboard ${manifest.version}`);
     const digest = await sha256File(tmpZip);
     if (digest !== manifest.sha256) {
       throw new CliError(`Dashboard ${manifest.version} failed its integrity check (expected ${manifest.sha256}, got ${digest}).`);
@@ -193,6 +195,7 @@ async function downloadDashboardRelease(manifest: DashboardManifest): Promise<vo
 
     rmSync(tmpDir, { recursive: true, force: true });
     mkdirSync(tmpDir, { recursive: true });
+    onProgress?.(`Extracting Hexclave dashboard ${manifest.version}`);
     await extractZip(tmpZip, { dir: tmpDir });
     if (!existsSync(join(tmpDir, DASHBOARD_SERVER_RELATIVE_PATH))) {
       throw new CliError(`Dashboard ${manifest.version} archive is missing its server entrypoint.`);
@@ -225,7 +228,10 @@ async function downloadDashboardRelease(manifest: DashboardManifest): Promise<vo
 
 // Resolve the build to launch: on-disk override → manifest version (downloaded if
 // not cached) → newest cached (offline). Throws only when nothing is usable.
-export async function resolveDashboardRuntime(opts: { manifest?: DashboardManifest | null } = {}): Promise<ResolvedDashboard> {
+export async function resolveDashboardRuntime(opts: {
+  manifest?: DashboardManifest | null,
+  onProgress?: (message: string) => void,
+} = {}): Promise<ResolvedDashboard> {
   const override = dashboardDirOverride();
   if (override != null) {
     if (!existsSync(join(override, DASHBOARD_SERVER_RELATIVE_PATH))) {
@@ -240,7 +246,7 @@ export async function resolveDashboardRuntime(opts: { manifest?: DashboardManife
       return { root: dashboardVersionDir(manifest.version), version: manifest.version };
     }
     try {
-      await downloadDashboardRelease(manifest);
+      await downloadDashboardRelease(manifest, opts.onProgress);
       return { root: dashboardVersionDir(manifest.version), version: manifest.version };
     } catch (error) {
       const cached = latestCachedDashboardVersion();

package/src/lib/ignore-rules.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { isIgnoredByRules, parseIgnoreFile, parseIgnorePattern } from "./ignore-rules.js";
+
+const check = (content: string, relativePath: string, isDirectory = false) =>
+  isIgnoredByRules(parseIgnoreFile(content), relativePath, isDirectory);
+
+describe("parseIgnorePattern", () => {
+  it("skips comments and blank lines", () => {
+    expect(parseIgnorePattern("# a comment")).toBeUndefined();
+    expect(parseIgnorePattern("")).toBeUndefined();
+    expect(parseIgnorePattern("   ")).toBeUndefined();
+  });
+});
+
+describe("isIgnoredByRules", () => {
+  it("matches basenames at any depth for slash-less patterns", () => {
+    expect(check("*.log", "error.log")).toBe(true);
+    expect(check("*.log", "deep/nested/error.log")).toBe(true);
+    expect(check("*.log", "error.log.txt")).toBe(false);
+    expect(check("dist", "dist", true)).toBe(true);
+    expect(check("dist", "packages/a/dist", true)).toBe(true);
+  });
+
+  it("anchors patterns that contain a slash", () => {
+    expect(check("build/output.js", "build/output.js")).toBe(true);
+    expect(check("build/output.js", "nested/build/output.js")).toBe(false);
+    expect(check("/top.txt", "top.txt")).toBe(true);
+    expect(check("/top.txt", "nested/top.txt")).toBe(false);
+  });
+
+  it("handles directory-only patterns", () => {
+    expect(check("cache/", "cache", true)).toBe(true);
+    expect(check("cache/", "cache", false)).toBe(false);
+  });
+
+  it("handles negation with last-match-wins", () => {
+    const content = "*.env\n!example.env";
+    expect(check(content, "secret.env")).toBe(true);
+    expect(check(content, "example.env")).toBe(false);
+    // Reversed order: the ignore comes later, so it wins.
+    expect(check("!example.env\n*.env", "example.env")).toBe(true);
+  });
+
+  it("handles ** wildcards", () => {
+    expect(check("docs/**", "docs/a.md")).toBe(true);
+    expect(check("docs/**", "docs/deep/b.md")).toBe(true);
+    expect(check("docs/**", "docs", true)).toBe(false);
+    expect(check("**/temp", "temp", true)).toBe(true);
+    expect(check("**/temp", "a/b/temp", true)).toBe(true);
+    expect(check("a/**/z.txt", "a/z.txt")).toBe(true);
+    expect(check("a/**/z.txt", "a/b/c/z.txt")).toBe(true);
+  });
+
+  it("handles ? wildcards without crossing directories", () => {
+    expect(check("file?.txt", "file1.txt")).toBe(true);
+    expect(check("file?.txt", "file12.txt")).toBe(false);
+    expect(check("a?c", "a/c")).toBe(false);
+  });
+
+  it("does not match partial segments", () => {
+    expect(check("foo", "foobar")).toBe(false);
+    expect(check("foo", "bar/foo")).toBe(true);
+  });
+
+  it("handles character classes", () => {
+    expect(check("file[0-9].txt", "file1.txt")).toBe(true);
+    expect(check("file[0-9].txt", "fileA.txt")).toBe(false);
+    expect(check("file[!0-9].txt", "fileA.txt")).toBe(true);
+    expect(check("file[!0-9].txt", "file1.txt")).toBe(false);
+    expect(check("[ab]c", "ac")).toBe(true);
+    expect(check("[ab]c", "cc")).toBe(false);
+    // Unterminated bracket is a literal.
+    expect(check("foo[bar", "foo[bar")).toBe(true);
+  });
+
+  it("handles backslash escapes", () => {
+    expect(check("\\#not-a-comment", "#not-a-comment")).toBe(true);
+    expect(check("\\!not-negated", "!not-negated")).toBe(true);
+    expect(check("star\\*lit", "star*lit")).toBe(true);
+    expect(check("star\\*lit", "starXlit")).toBe(false);
+    // Escaped trailing space is preserved.
+    expect(check("ends-with-space\\ ", "ends-with-space ")).toBe(true);
+  });
+});

package/src/lib/ignore-rules.ts

@@ -0,0 +1,133 @@
+// A small .gitignore/.vercelignore matcher for `hexclave deploy`'s source
+// packaging. Implements the commonly-used gitignore syntax: comments, blank
+// lines, negation (!), directory-only patterns (trailing /), anchoring
+// (patterns containing a slash are relative to the ignore file's directory),
+// the *, ?, ** wildcards, backslash escapes (\#, \!, \ ), and character
+// classes ([abc], [a-z], [!a-z]). Matching what users' .gitignore files
+// actually mean matters here: a pattern we under-match would make the CLI
+// upload files the user believes are ignored.
+
+export type IgnoreRule = {
+  negated: boolean,
+  dirOnly: boolean,
+  regex: RegExp,
+};
+
+function escapeRegExpChar(char: string): string {
+  return /[.*+?^${}()|[\]\\]/.test(char) ? `\\${char}` : char;
+}
+
+// Converts one glob segment ("*.log", "foo?", "[a-z]bc", ...) to a regex
+// fragment that never crosses a "/" boundary.
+function globSegmentToRegex(segment: string): string {
+  let result = "";
+  for (let i = 0; i < segment.length; i++) {
+    const char = segment[i];
+    if (char === "\\" && i + 1 < segment.length) {
+      // Backslash escape: the next character is literal (gitignore uses this
+      // for \#, \!, and trailing "\ ").
+      result += escapeRegExpChar(segment[i + 1]);
+      i++;
+    } else if (char === "*") {
+      result += "[^/]*";
+    } else if (char === "?") {
+      result += "[^/]";
+    } else if (char === "[") {
+      // Character class: find the closing bracket (a ']' directly after the
+      // opening '[' or '[!' is literal, per fnmatch). An unterminated '[' is
+      // treated as a literal bracket.
+      let j = i + 1;
+      let negatedClass = false;
+      if (segment[j] === "!" || segment[j] === "^") {
+        negatedClass = true;
+        j++;
+      }
+      let classEnd = segment[j] === "]" ? segment.indexOf("]", j + 1) : segment.indexOf("]", j);
+      if (classEnd === -1) {
+        result += escapeRegExpChar(char);
+      } else {
+        const inner = segment.slice(j, classEnd);
+        // Keep '-' ranges; escape everything regex-special except '-'.
+        const safeInner = [...inner].map((c) => (c === "-" ? "-" : escapeRegExpChar(c))).join("");
+        result += `[${negatedClass ? "^" : ""}${safeInner}]`;
+        i = classEnd;
+      }
+    } else {
+      result += escapeRegExpChar(char);
+    }
+  }
+  return result;
+}
+
+export function parseIgnorePattern(line: string): IgnoreRule | undefined {
+  let pattern = line.replace(/\r$/, "");
+  // Trailing spaces are ignored unless backslash-escaped (git semantics); the
+  // lookbehind keeps an escaped "\ " so the escape handling below can turn it
+  // into a literal space.
+  pattern = pattern.replace(/(?<!\\) +$/, "");
+  if (pattern === "" || pattern.startsWith("#")) {
+    return undefined;
+  }
+  let negated = false;
+  if (pattern.startsWith("!")) {
+    negated = true;
+    pattern = pattern.slice(1);
+  }
+  let dirOnly = false;
+  if (pattern.endsWith("/")) {
+    dirOnly = true;
+    pattern = pattern.slice(0, -1);
+  }
+  if (pattern === "") {
+    return undefined;
+  }
+  // A pattern containing a slash (after stripping the trailing one) is
+  // anchored to the ignore file's directory; otherwise it matches at any depth.
+  const anchored = pattern.includes("/");
+  if (pattern.startsWith("/")) {
+    pattern = pattern.slice(1);
+  }
+
+  const segments = pattern.split("/");
+  const regexParts: string[] = [];
+  for (let i = 0; i < segments.length; i++) {
+    const segment = segments[i];
+    if (segment === "**") {
+      // "**" as a full segment matches zero or more path segments.
+      regexParts.push(i === segments.length - 1 ? ".*" : "(?:[^/]+/)*");
+    } else {
+      regexParts.push(globSegmentToRegex(segment) + (i === segments.length - 1 ? "" : "/"));
+    }
+  }
+  const body = regexParts.join("");
+  const prefix = anchored ? "" : "(?:[^/]+/)*";
+  return {
+    negated,
+    dirOnly,
+    regex: new RegExp(`^${prefix}${body}$`),
+  };
+}
+
+export function parseIgnoreFile(content: string): IgnoreRule[] {
+  return content
+    .split("\n")
+    .map(parseIgnorePattern)
+    .filter((rule): rule is IgnoreRule => rule !== undefined);
+}
+
+/**
+ * Evaluates the rules against a path relative to the directory the rules are
+ * anchored at (POSIX separators, no leading "/"). Last matching rule wins,
+ * like git. Note that like git, a negation can't rescue a file inside an
+ * ignored directory — the walker prunes ignored directories entirely.
+ */
+export function isIgnoredByRules(rules: IgnoreRule[], relativePath: string, isDirectory: boolean): boolean {
+  let ignored = false;
+  for (const rule of rules) {
+    if (rule.dirOnly && !isDirectory) continue;
+    if (rule.regex.test(relativePath)) {
+      ignored = !rule.negated;
+    }
+  }
+  return ignored;
+}

package/src/lib/progress.test.ts

@@ -0,0 +1,73 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { startProgress, withProgress } from "./progress.js";
+
+function createStream(isTTY: boolean) {
+  const chunks: string[] = [];
+  return {
+    chunks,
+    stream: {
+      isTTY,
+      write(chunk: string) {
+        chunks.push(chunk);
+      },
+    },
+  };
+}
+
+describe("startProgress", () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("renders and clears an animated line in interactive terminals", () => {
+    vi.useFakeTimers();
+    const { chunks, stream } = createStream(true);
+    const progress = startProgress("Loading config", { stream });
+
+    vi.advanceTimersByTime(80);
+    progress.update("Pushing config");
+    progress.stop();
+
+    expect(chunks.join("")).toContain("⠋ Loading config");
+    expect(chunks.join("")).toContain("⠙ Loading config");
+    expect(chunks.join("")).toContain("Pushing config");
+    expect(chunks.at(-1)).toBe("\r\x1b[2K");
+  });
+
+  it("writes durable phase lines when stderr is redirected", () => {
+    const { chunks, stream } = createStream(false);
+    const progress = startProgress("Loading config", { prefix: "[Hexclave] ", stream });
+
+    progress.update("Pushing config");
+    progress.stop("Config pushed");
+
+    expect(chunks).toEqual([
+      "[Hexclave] Loading config...\n",
+      "[Hexclave] Pushing config...\n",
+      "[Hexclave] Config pushed\n",
+    ]);
+  });
+
+  it("stops idempotently", () => {
+    const { chunks, stream } = createStream(false);
+    const progress = startProgress("Working", { stream });
+
+    progress.stop("Done");
+    progress.stop("Done again");
+
+    expect(chunks).toEqual(["Working...\n", "Done\n"]);
+  });
+});
+
+describe("withProgress", () => {
+  it("clears progress when the operation rejects", async () => {
+    const { chunks, stream } = createStream(true);
+    const error = new Error("nope");
+
+    await expect(withProgress("Working", async () => {
+      throw error;
+    }, { stream })).rejects.toBe(error);
+
+    expect(chunks.at(-1)).toBe("\r\x1b[2K");
+  });
+});

package/src/lib/progress.ts

@@ -0,0 +1,82 @@
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const SPINNER_INTERVAL_MS = 80;
+
+type ProgressStream = {
+  isTTY?: boolean,
+  write: (chunk: string) => unknown,
+};
+
+export type Progress = {
+  update: (message: string) => void,
+  stop: (finalMessage?: string) => void,
+};
+
+type ProgressOptions = {
+  prefix?: string,
+  stream?: ProgressStream,
+};
+
+/**
+ * Reports long-running CLI work without contaminating stdout. Interactive
+ * terminals get a single animated line, while redirected output gets durable
+ * lines that remain useful in CI logs.
+ */
+export function startProgress(initialMessage: string, options: ProgressOptions = {}): Progress {
+  const stream = options.stream ?? process.stderr;
+  const prefix = options.prefix ?? "";
+  let message = initialMessage;
+  let stopped = false;
+
+  if (!stream.isTTY) {
+    stream.write(`${prefix}${message}...\n`);
+    return {
+      update(nextMessage) {
+        if (stopped || nextMessage === message) return;
+        message = nextMessage;
+        stream.write(`${prefix}${message}...\n`);
+      },
+      stop(finalMessage) {
+        if (stopped) return;
+        stopped = true;
+        if (finalMessage != null) {
+          stream.write(`${prefix}${finalMessage}\n`);
+        }
+      },
+    };
+  }
+
+  let frameIndex = 0;
+  const render = () => {
+    stream.write(`\r\x1b[2K${prefix}${SPINNER_FRAMES[frameIndex]} ${message}`);
+    frameIndex = (frameIndex + 1) % SPINNER_FRAMES.length;
+  };
+  render();
+  const timer = setInterval(render, SPINNER_INTERVAL_MS);
+  timer.unref();
+
+  return {
+    update(nextMessage) {
+      if (stopped || nextMessage === message) return;
+      message = nextMessage;
+      render();
+    },
+    stop(finalMessage) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      stream.write("\r\x1b[2K");
+      if (finalMessage != null) {
+        stream.write(`${prefix}${finalMessage}\n`);
+      }
+    },
+  };
+}
+
+export async function withProgress<T>(message: string, operation: () => Promise<T>, options?: ProgressOptions): Promise<T> {
+  const progress = startProgress(message, options);
+  try {
+    return await operation();
+  } finally {
+    progress.stop();
+  }
+}

package/src/lib/source-packaging.test.ts

@@ -0,0 +1,129 @@
+import { parseTar } from "@hexclave/shared/dist/utils/tar";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { gunzipSync } from "node:zlib";
+import { afterEach, describe, expect, it } from "vitest";
+import { packageSourceDirectory } from "./source-packaging.js";
+
+const tempDirs: string[] = [];
+const makeTempDir = () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "hexclave-package-test-"));
+  tempDirs.push(dir);
+  return dir;
+};
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+const write = (root: string, relativePath: string, content: string) => {
+  const absolute = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(absolute), { recursive: true });
+  fs.writeFileSync(absolute, content);
+};
+
+const packagedPaths = (root: string) => {
+  const packaged = packageSourceDirectory(root);
+  const entries = parseTar(gunzipSync(packaged.tarballGzipped), { maxEntries: 10_000, maxTotalBytes: 100 * 1024 * 1024 });
+  return entries.map((entry) => entry.path);
+};
+
+describe("packageSourceDirectory", () => {
+  it("packages files with deterministic ordering and roundtrips content", () => {
+    const root = makeTempDir();
+    write(root, "package.json", `{"name":"x"}`);
+    write(root, "src/index.ts", "export {}\n");
+    write(root, "src/a.ts", "// a\n");
+
+    const packaged = packageSourceDirectory(root);
+    const entries = parseTar(gunzipSync(packaged.tarballGzipped), { maxEntries: 100, maxTotalBytes: 1024 * 1024 });
+    expect(entries.map((entry) => entry.path)).toEqual(["package.json", "src/a.ts", "src/index.ts"]);
+    expect(new TextDecoder().decode(entries[0].data)).toBe(`{"name":"x"}`);
+    expect(packaged.fileCount).toBe(3);
+
+    // Byte-identical when repackaged (fixed mtimes, sorted entries).
+    expect(Buffer.compare(packageSourceDirectory(root).tarballGzipped, packaged.tarballGzipped)).toBe(0);
+  });
+
+  it("always drops node_modules and .git, even without ignore files", () => {
+    const root = makeTempDir();
+    write(root, "index.js", "");
+    write(root, "node_modules/pkg/index.js", "");
+    write(root, ".git/HEAD", "");
+    write(root, "nested/node_modules/pkg/index.js", "");
+    expect(packagedPaths(root)).toEqual(["index.js"]);
+  });
+
+  it("respects .gitignore and .vercelignore including negation", () => {
+    const root = makeTempDir();
+    write(root, ".gitignore", "*.log\ndist/\n!keep.log\n");
+    write(root, ".vercelignore", "*.md\n");
+    write(root, "app.js", "");
+    write(root, "error.log", "");
+    write(root, "keep.log", "");
+    write(root, "README.md", "");
+    write(root, "dist/out.js", "");
+    expect(packagedPaths(root)).toEqual([".gitignore", ".vercelignore", "app.js", "keep.log"]);
+  });
+
+  it("applies nested .gitignore files relative to their directory", () => {
+    const root = makeTempDir();
+    write(root, "sub/.gitignore", "local-only.txt\n");
+    write(root, "sub/local-only.txt", "");
+    write(root, "sub/kept.txt", "");
+    write(root, "local-only.txt", "");
+    expect(packagedPaths(root)).toEqual(["local-only.txt", "sub/.gitignore", "sub/kept.txt"]);
+  });
+
+  it("inherits ignore files above a monorepo service root", () => {
+    const root = makeTempDir();
+    write(root, ".gitignore", "*.log\npackages/api/generated/\n");
+    write(root, ".vercelignore", "packages/api/private.txt\n");
+    write(root, "packages/api/index.ts", "");
+    write(root, "packages/api/error.log", "");
+    write(root, "packages/api/generated/client.ts", "");
+    write(root, "packages/api/private.txt", "");
+
+    const packaged = packageSourceDirectory(path.join(root, "packages/api"), root);
+    const entries = parseTar(gunzipSync(packaged.tarballGzipped), { maxEntries: 100, maxTotalBytes: 1024 * 1024 });
+    expect(entries.map((entry) => entry.path)).toEqual(["index.ts"]);
+  });
+
+  it("allows a nested ignore file to override an inherited file rule", () => {
+    const root = makeTempDir();
+    write(root, ".gitignore", "*.log\n");
+    write(root, "packages/api/.gitignore", "!keep.log\n");
+    write(root, "packages/api/drop.log", "");
+    write(root, "packages/api/keep.log", "");
+
+    const packaged = packageSourceDirectory(path.join(root, "packages/api"), root);
+    const entries = parseTar(gunzipSync(packaged.tarballGzipped), { maxEntries: 100, maxTotalBytes: 1024 * 1024 });
+    expect(entries.map((entry) => entry.path)).toEqual([".gitignore", "keep.log"]);
+  });
+
+  it("rejects a source directory outside the ignore/config root", () => {
+    const configRoot = makeTempDir();
+    const sourceRoot = makeTempDir();
+    write(sourceRoot, "index.ts", "");
+    expect(() => packageSourceDirectory(sourceRoot, configRoot)).toThrow("must be inside the config directory");
+  });
+
+  it("skips symlinks", () => {
+    const root = makeTempDir();
+    write(root, "real.txt", "hi");
+    fs.symlinkSync(path.join(root, "real.txt"), path.join(root, "link.txt"));
+    expect(packagedPaths(root)).toEqual(["real.txt"]);
+  });
+
+  it("errors on a missing directory", () => {
+    expect(() => packageSourceDirectory(path.join(makeTempDir(), "nope"))).toThrow("Source directory not found");
+  });
+
+  it("errors when everything is ignored", () => {
+    const root = makeTempDir();
+    write(root, "node_modules/pkg/index.js", "");
+    expect(() => packageSourceDirectory(root)).toThrow("No files to deploy");
+  });
+});