@vee3/upload 0.1.1 → 0.2.1

package/package.json

@@ -1,24 +1,31 @@
-{
-  "name": "@vee3/upload",
-  "version": "0.1.1",
-  "description": "Upload local files to Vee3.",
-  "homepage": "https://vee3.io",
-  "type": "module",
-  "bin": {
-    "vee3-upload": "./src/index.js"
-  },
-  "files": ["src"],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/vee3io/Vee3.git",
-    "directory": "packages/upload"
-  },
-  "keywords": ["vee3", "upload", "cli", "mcp"],
-  "license": "MIT"
-}
+{
+  "name": "@vee3/upload",
+  "version": "0.2.1",
+  "description": "Upload local files to Vee3.",
+  "homepage": "https://vee3.io",
+  "type": "module",
+  "bin": {
+    "vee3-upload": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vee3io/Vee3.git",
+    "directory": "packages/upload"
+  },
+  "keywords": [
+    "vee3",
+    "upload",
+    "cli",
+    "mcp"
+  ],
+  "license": "MIT"
+}

package/src/api.js

@@ -1,34 +1,43 @@
-export const DEFAULT_API_BASE_URL = "https://api.vee3.io";
-
-async function formatApiError(response) {
-  const responseText = await response.text();
-  try {
-    const payload = JSON.parse(responseText);
-    if (payload && typeof payload.error === "object") {
-      const requestId = payload.error.request_id ? ` (request_id=${payload.error.request_id})` : "";
-      return `${payload.error.code}: ${payload.error.message}${requestId}`;
-    }
-  } catch {
-    // Fall through to raw response text.
-  }
-  return responseText || `HTTP ${response.status}`;
-}
-
-export async function resolveUpload({ apiBaseUrl, uploadCode, contentType }) {
-  const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}/v1/agent-uploads/resolve`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify({
-      upload_code: uploadCode,
-      content_type: contentType
-    })
-  });
-
-  if (!response.ok) {
-    throw new Error(await formatApiError(response));
-  }
-
-  return await response.json();
-}
+import { UploadError, describeNetworkError } from "./errors.js";
+
+export const DEFAULT_API_BASE_URL = "https://api.vee3.io";
+
+async function formatApiError(response) {
+  const responseText = await response.text();
+  try {
+    const payload = JSON.parse(responseText);
+    if (payload && typeof payload.error === "object") {
+      const requestId = payload.error.request_id ? ` (request_id=${payload.error.request_id})` : "";
+      return `${payload.error.code}: ${payload.error.message}${requestId}`;
+    }
+  } catch {
+    // Fall through to raw response text.
+  }
+  return responseText || `HTTP ${response.status}`;
+}
+
+export async function resolveUpload({ apiBaseUrl, uploadCode, contentType }) {
+  const requestUrl = `${apiBaseUrl.replace(/\/$/, "")}/v1/agent-uploads/resolve`;
+
+  let response;
+  try {
+    response = await fetch(requestUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        upload_code: uploadCode,
+        content_type: contentType
+      })
+    });
+  } catch (error) {
+    throw new UploadError(describeNetworkError(error, `the Vee3 API at ${apiBaseUrl}`));
+  }
+
+  if (!response.ok) {
+    throw new UploadError(await formatApiError(response));
+  }
+
+  return await response.json();
+}

package/src/errors.js

@@ -0,0 +1,51 @@
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+export class UploadError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UploadError";
+  }
+}
+
+const TLS_VERIFICATION_CODES = new Set([
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "CERT_HAS_EXPIRED",
+  "ERR_TLS_CERT_ALTNAME_INVALID"
+]);
+
+/**
+ * Turns a low-level fetch failure into a message a user can act on. Node's
+ * fetch throws a generic "fetch failed" TypeError and hides the real reason in
+ * error.cause, so we surface the underlying code here.
+ */
+export function describeNetworkError(error, targetDescription) {
+  const cause = error?.cause ?? error;
+  const code = cause?.code;
+
+  if (code === "ECONNREFUSED") {
+    return `Could not connect to ${targetDescription}. Make sure it is running and the address is correct.`;
+  }
+  if (code === "ENOTFOUND") {
+    return `Could not find ${targetDescription}. Check the address and your network connection.`;
+  }
+  if (code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT") {
+    return `Connection to ${targetDescription} timed out.`;
+  }
+  if (code && TLS_VERIFICATION_CODES.has(code)) {
+    return (
+      `Could not verify the TLS certificate for ${targetDescription}. ` +
+      "This usually means a proxy or antivirus is inspecting HTTPS traffic. " +
+      "Use Node 22.15 or newer, or set NODE_EXTRA_CA_CERTS to your root certificate."
+    );
+  }
+
+  const detail = cause?.message ?? error?.message ?? String(error);
+  return `Request to ${targetDescription} failed: ${detail}`;
+}

package/src/format.js

@@ -0,0 +1,17 @@
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB"];
+
+export function formatBytes(byteCount) {
+  if (!Number.isFinite(byteCount) || byteCount <= 0) {
+    return "0 B";
+  }
+
+  let unitIndex = 0;
+  let value = byteCount;
+  while (value >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+
+  const decimals = unitIndex === 0 ? 0 : 1;
+  return `${value.toFixed(decimals)} ${BYTE_UNITS[unitIndex]}`;
+}

package/src/index.js

@@ -1,96 +1,121 @@
-#!/usr/bin/env node
-
-import { stat } from "node:fs/promises";
-import { DEFAULT_API_BASE_URL, resolveUpload } from "./api.js";
-import { detectContentType } from "./detectContentType.js";
-import { uploadFileToSignedUrl } from "./uploadFile.js";
-
-function printUsage() {
-  console.error(
-    "Usage: vee3-upload <upload_code> <file_path> [--api-base-url https://api.vee3.io] [--json]"
-  );
-}
-
-function parseArguments(argumentsList) {
-  const positionalArguments = [];
-  let apiBaseUrl = DEFAULT_API_BASE_URL;
-  let outputJson = false;
-
-  for (let index = 0; index < argumentsList.length; index += 1) {
-    const argument = argumentsList[index];
-    if (argument === "--api-base-url") {
-      const nextArgument = argumentsList[index + 1];
-      if (!nextArgument) {
-        throw new Error("--api-base-url requires a value");
-      }
-      apiBaseUrl = nextArgument;
-      index += 1;
-      continue;
-    }
-    if (argument === "--json") {
-      outputJson = true;
-      continue;
-    }
-    positionalArguments.push(argument);
-  }
-
-  if (positionalArguments.length !== 2) {
-    throw new Error("Expected upload_code and file_path");
-  }
-
-  return {
-    uploadCode: positionalArguments[0],
-    filePath: positionalArguments[1],
-    apiBaseUrl,
-    outputJson
-  };
-}
-
-async function main() {
-  const { uploadCode, filePath, apiBaseUrl, outputJson } = parseArguments(
-    process.argv.slice(2)
-  );
-  const fileStat = await stat(filePath);
-  if (!fileStat.isFile()) {
-    throw new Error(`File path is not a file: ${filePath}`);
-  }
-
-  const contentType = await detectContentType(filePath);
-  const resolvedUpload = await resolveUpload({
-    apiBaseUrl,
-    uploadCode,
-    contentType
-  });
-
-  if (fileStat.size > resolvedUpload.max_bytes) {
-    throw new Error(
-      `File is too large: ${fileStat.size} bytes exceeds ${resolvedUpload.max_bytes} bytes`
-    );
-  }
-
-  await uploadFileToSignedUrl({
-    uploadUrl: resolvedUpload.upload_url,
-    filePath,
-    fileSizeBytes: fileStat.size,
-    requiredHeaders: resolvedUpload.required_headers
-  });
-
-  if (outputJson) {
-    console.log(
-      JSON.stringify({
-        upload_id: resolvedUpload.upload_id,
-        content_type: contentType,
-        size_bytes: fileStat.size
-      })
-    );
-    return;
-  }
-
-  console.log(resolvedUpload.upload_id);
-}
-
-main().catch((error) => {
-  printUsage();
-  console.error(error instanceof Error ? error.message : String(error));
-  process.exit(1);
-});
+#!/usr/bin/env node
+
+import { stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { DEFAULT_API_BASE_URL, resolveUpload } from "./api.js";
+import { detectContentType } from "./detectContentType.js";
+import { UploadError, UsageError } from "./errors.js";
+import { formatBytes } from "./format.js";
+import { ensureSystemCertificateTrust } from "./systemCertificates.js";
+import { uploadFileToSignedUrl } from "./uploadFile.js";
+
+ensureSystemCertificateTrust();
+
+function printUsage() {
+  console.error("Usage: vee3-upload <upload_code> <file_path>");
+}
+
+function parseArguments(argumentsList) {
+  const positionalArguments = [];
+  let apiBaseUrl = DEFAULT_API_BASE_URL;
+  let outputJson = false;
+
+  for (let index = 0; index < argumentsList.length; index += 1) {
+    const argument = argumentsList[index];
+    if (argument === "--api-base-url") {
+      const nextArgument = argumentsList[index + 1];
+      if (!nextArgument) {
+        throw new UsageError("--api-base-url requires a value");
+      }
+      apiBaseUrl = nextArgument;
+      index += 1;
+      continue;
+    }
+    if (argument === "--json") {
+      outputJson = true;
+      continue;
+    }
+    positionalArguments.push(argument);
+  }
+
+  if (positionalArguments.length !== 2) {
+    throw new UsageError("Expected upload_code and file_path");
+  }
+
+  return {
+    uploadCode: positionalArguments[0],
+    filePath: positionalArguments[1],
+    apiBaseUrl,
+    outputJson
+  };
+}
+
+async function readFileStat(filePath) {
+  try {
+    return await stat(filePath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new UploadError(`File not found: ${filePath}`);
+    }
+    throw new UploadError(`Could not read file: ${filePath} (${error.message})`);
+  }
+}
+
+async function main() {
+  const { uploadCode, filePath, apiBaseUrl, outputJson } = parseArguments(
+    process.argv.slice(2)
+  );
+
+  const fileStat = await readFileStat(filePath);
+  if (!fileStat.isFile()) {
+    throw new UploadError(`Not a file: ${filePath}`);
+  }
+
+  const contentType = await detectContentType(filePath);
+
+  console.error("Resolving upload code...");
+  const resolvedUpload = await resolveUpload({
+    apiBaseUrl,
+    uploadCode,
+    contentType
+  });
+
+  if (fileStat.size > resolvedUpload.max_bytes) {
+    throw new UploadError(
+      `File is too large: ${formatBytes(fileStat.size)} exceeds the ${formatBytes(
+        resolvedUpload.max_bytes
+      )} limit.`
+    );
+  }
+
+  console.error(`Uploading ${basename(filePath)} (${formatBytes(fileStat.size)})...`);
+  await uploadFileToSignedUrl({
+    uploadUrl: resolvedUpload.upload_url,
+    filePath,
+    fileSizeBytes: fileStat.size,
+    requiredHeaders: resolvedUpload.required_headers
+  });
+
+  if (outputJson) {
+    console.log(
+      JSON.stringify({
+        upload_id: resolvedUpload.upload_id,
+        content_type: contentType,
+        size_bytes: fileStat.size
+      })
+    );
+    return;
+  }
+
+  console.log(resolvedUpload.upload_id);
+}
+
+main().catch((error) => {
+  if (error instanceof UsageError) {
+    printUsage();
+    console.error(error.message);
+  } else {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
+  process.exit(1);
+});

package/src/progress.js

@@ -0,0 +1,59 @@
+import { formatBytes } from "./format.js";
+
+const TTY_RENDER_INTERVAL_MS = 150;
+const NON_TTY_MILESTONE_STEP = 20;
+
+/**
+ * Reports upload progress to stderr so that stdout stays clean for the
+ * upload_id. In an interactive terminal it redraws a single line; in
+ * non-interactive contexts (such as agent logs) it prints discrete milestone
+ * lines to avoid carriage-return spam.
+ */
+export function createUploadProgressReporter(totalBytes) {
+  const isInteractive = Boolean(process.stderr.isTTY);
+  let lastRenderTime = 0;
+  let lastMilestone = 0;
+
+  function computePercent(uploadedBytes) {
+    if (totalBytes <= 0) {
+      return 100;
+    }
+    return Math.min(100, Math.floor((uploadedBytes / totalBytes) * 100));
+  }
+
+  function report(uploadedBytes) {
+    const percent = computePercent(uploadedBytes);
+
+    if (isInteractive) {
+      const now = Date.now();
+      const isComplete = uploadedBytes >= totalBytes;
+      if (!isComplete && now - lastRenderTime < TTY_RENDER_INTERVAL_MS) {
+        return;
+      }
+      lastRenderTime = now;
+      process.stderr.write(
+        `\rUploading ${percent}% (${formatBytes(uploadedBytes)} / ${formatBytes(totalBytes)})`
+      );
+      return;
+    }
+
+    const milestone = Math.floor(percent / NON_TTY_MILESTONE_STEP) * NON_TTY_MILESTONE_STEP;
+    if (milestone <= lastMilestone || milestone >= 100) {
+      return;
+    }
+    lastMilestone = milestone;
+    process.stderr.write(
+      `Uploading ${milestone}% (${formatBytes(uploadedBytes)} / ${formatBytes(totalBytes)})\n`
+    );
+  }
+
+  function finish() {
+    if (isInteractive) {
+      process.stderr.write(`\rUploaded ${formatBytes(totalBytes)} (100%)\n`);
+      return;
+    }
+    process.stderr.write(`Uploaded ${formatBytes(totalBytes)} (100%)\n`);
+  }
+
+  return { report, finish };
+}

package/src/systemCertificates.js

@@ -0,0 +1,61 @@
+import { spawnSync } from "node:child_process";
+
+const SYSTEM_CA_FLAG = "--use-system-ca";
+const REEXEC_GUARD_VARIABLE = "VEE3_UPLOAD_SYSTEM_CA_REEXEC";
+
+function systemCaFlagAlreadyActive() {
+  if (process.execArgv.includes(SYSTEM_CA_FLAG)) {
+    return true;
+  }
+  const nodeOptions = process.env.NODE_OPTIONS ?? "";
+  return nodeOptions.includes(SYSTEM_CA_FLAG);
+}
+
+function systemCaFlagSupported() {
+  try {
+    return process.allowedNodeEnvironmentFlags.has(SYSTEM_CA_FLAG);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Networks that perform TLS inspection (corporate proxies, some antivirus
+ * products) present certificates signed by a private root CA that Node does not
+ * trust by default, so HTTPS requests fail with UNABLE_TO_VERIFY_LEAF_SIGNATURE.
+ * Re-executing with --use-system-ca makes Node trust the same roots the
+ * operating system already trusts, which is what browsers and OS HTTP clients
+ * use. On older Node versions without the flag we fall back to whatever
+ * NODE_EXTRA_CA_CERTS provides.
+ */
+export function ensureSystemCertificateTrust() {
+  if (process.env[REEXEC_GUARD_VARIABLE] === "1") {
+    return;
+  }
+  if (systemCaFlagAlreadyActive()) {
+    return;
+  }
+  if (!systemCaFlagSupported()) {
+    return;
+  }
+
+  const entryScript = process.argv[1];
+  if (!entryScript) {
+    return;
+  }
+
+  const result = spawnSync(
+    process.execPath,
+    [SYSTEM_CA_FLAG, entryScript, ...process.argv.slice(2)],
+    {
+      stdio: "inherit",
+      env: { ...process.env, [REEXEC_GUARD_VARIABLE]: "1" }
+    }
+  );
+
+  if (result.error) {
+    return;
+  }
+
+  process.exit(result.status ?? 0);
+}

package/src/uploadFile.js

@@ -1,25 +1,52 @@
-import { createReadStream } from "node:fs";
-
-export async function uploadFileToSignedUrl({
-  uploadUrl,
-  filePath,
-  fileSizeBytes,
-  requiredHeaders
-}) {
-  const headers = {
-    ...requiredHeaders,
-    "Content-Length": String(fileSizeBytes)
-  };
-
-  const response = await fetch(uploadUrl, {
-    method: "PUT",
-    headers,
-    body: createReadStream(filePath),
-    duplex: "half"
-  });
-
-  if (!response.ok) {
-    const responseText = await response.text();
-    throw new Error(responseText || `Upload failed with HTTP ${response.status}`);
-  }
-}
+import { createReadStream } from "node:fs";
+import { Transform } from "node:stream";
+import { UploadError, describeNetworkError } from "./errors.js";
+import { createUploadProgressReporter } from "./progress.js";
+
+export async function uploadFileToSignedUrl({
+  uploadUrl,
+  filePath,
+  fileSizeBytes,
+  requiredHeaders
+}) {
+  const progressReporter = createUploadProgressReporter(fileSizeBytes);
+  let uploadedBytes = 0;
+
+  const progressStream = new Transform({
+    transform(chunk, _encoding, callback) {
+      uploadedBytes += chunk.length;
+      progressReporter.report(uploadedBytes);
+      callback(null, chunk);
+    }
+  });
+
+  const fileStream = createReadStream(filePath);
+  fileStream.on("error", (error) => {
+    progressStream.destroy(error);
+  });
+  fileStream.pipe(progressStream);
+
+  const headers = {
+    ...requiredHeaders,
+    "Content-Length": String(fileSizeBytes)
+  };
+
+  let response;
+  try {
+    response = await fetch(uploadUrl, {
+      method: "PUT",
+      headers,
+      body: progressStream,
+      duplex: "half"
+    });
+  } catch (error) {
+    throw new UploadError(describeNetworkError(error, "Vee3 storage"));
+  }
+
+  if (!response.ok) {
+    const responseText = (await response.text()).trim();
+    throw new UploadError(responseText || `Upload failed with HTTP ${response.status}`);
+  }
+
+  progressReporter.finish();
+}