@tailglow/cli 0.9.5 → 0.9.15

package/src/flags.js

@@ -61,9 +61,12 @@ export function buildParserOptions(commands) {
 
   for (const command of commands) {
     const fields = [...command.path_params, ...command.query_params, ...command.body_fields];
+
     for (const field of fields) {
       const flag = toFlagName(field.name);
+
       if (options[flag]) continue;
+
       options[flag] = { type: field.type === "boolean" ? "boolean" : "string" };
     }
   }
@@ -86,6 +89,7 @@ export function normalizeSwitches(flags) {
     if (type !== "boolean") continue;
 
     const raw = flags[flag];
+
     if (raw === undefined || typeof raw === "boolean") continue;
     if (raw === "true" || raw === "false") {
       flags[flag] = raw === "true";
@@ -159,6 +163,7 @@ export function describeFlagSyntax(flag, type) {
  */
 export function isIntegerText(raw) {
   const trimmed = raw.trim();
+
   return /^[+-]?\d+$/.test(trimmed) && Number.isSafeInteger(Number(trimmed));
 }
 
@@ -176,6 +181,7 @@ export function isIntegerText(raw) {
 function parseStructuredValue(raw, type, named = "") {
   /** @type {unknown} */
   let value;
+
   try {
     value = JSON.parse(raw);
   } catch {
@@ -185,6 +191,7 @@ function parseStructuredValue(raw, type, named = "") {
   if (type.startsWith("object[]") && !Array.isArray(value)) {
     throw new Error(`${named}expected a JSON array for a ${type} value`);
   }
+
   if (!type.startsWith("object[]") && Array.isArray(value)) {
     throw new Error(`${named}expected a JSON object for a ${type} value`);
   }
@@ -214,6 +221,7 @@ export function coerceValue(raw, type, flag = "") {
     // A flag written bare parses as `true`. On a boolean field that IS the value; anywhere else the
     // value was left off, and sending `true` would make the API reject a request that reads as fine.
     if (type.includes("boolean")) return raw;
+
     throw new Error(`${named}expected a ${type} value after the flag, received none`);
   }
 
@@ -223,25 +231,30 @@ export function coerceValue(raw, type, flag = "") {
 
   if (type.includes("integer")) {
     if (!isIntegerText(raw)) throw new Error(`${named}expected a whole number, received "${raw}"`);
+
     return Number(raw);
   }
 
   if (type.includes("number")) {
     const value = Number(raw);
+
     if (raw.trim() === "" || !Number.isFinite(value)) {
       throw new Error(`${named}expected a number, received "${raw}"`);
     }
+
     return value;
   }
 
   if (type.includes("boolean")) {
     if (raw === "true") return true;
     if (raw === "false") return false;
+
     throw new Error(`${named}expected true or false, received "${raw}"`);
   }
 
   if (type.endsWith("[]")) {
     if (raw.trimStart().startsWith("[")) return parseStructuredValue(raw, "object[]");
+
     return raw
       .split(",")
       .map((entry) => entry.trim())
@@ -282,12 +295,14 @@ export function buildRequestParts(command, flags, { consumed_path_fields = new S
     if (RESERVED_FLAGS.has(flag) || consumed_flags.has(flag)) continue;
 
     const query_field = query_by_flag.get(flag);
+
     if (query_field) {
       query[query_field.name] = coerceValue(/** @type {string} */ (raw), query_field.type, flag);
       continue;
     }
 
     const body_field = body_by_flag.get(flag);
+
     if (body_field) {
       body[body_field.name] = coerceValue(/** @type {string} */ (raw), body_field.type, flag);
       continue;

package/src/help.js

@@ -107,6 +107,7 @@ function listResources(commands) {
 /** @param {(typeof GLOBAL_FLAGS)[number]} entry */
 function renderGlobalFlag(entry) {
   const left = entry.argument ? `${entry.flag} ${entry.argument}` : entry.flag;
+
   return {
     left,
     description: entry.env ? `${entry.description} (${entry.env})` : entry.description
@@ -276,6 +277,7 @@ export function renderRootHelp() {
 /** @param {string} resource */
 export function renderResourceHelp(resource) {
   const commands = CLI_COMMANDS.filter((command) => command.resource === resource);
+
   if (commands.length === 0) return null;
 
   const width = Math.max(...commands.map((command) => command.command.length));
@@ -327,10 +329,12 @@ function renderFields({ fields, title }) {
  */
 function renderNestedFields(fields, depth) {
   const indent = "  ".repeat(depth + 1);
+
   return fields.flatMap((field) => {
     const required = field.required ? " (required)" : "";
     const allowed = field.allowed_values.length > 0 ? ` [${field.allowed_values.join(", ")}]` : "";
     const description = field.description ? `  ${field.description}` : "";
+
     return [
       `${indent}${field.name} <${field.type}>${required}${allowed}${description}`,
       ...renderNestedFields(field.fields ?? [], depth + 1)

package/src/import-command.js

@@ -61,10 +61,13 @@ export function describeImportForMachines() {
 /** @param {unknown} error @param {Record<string, unknown>} flags */
 function safeError(error, flags) {
   let message = error instanceof Error ? error.message : "Import failed.";
+
   for (const name of ["api-key", "ingest-url"]) {
     const value = flags[name];
+
     if (typeof value === "string" && value) message = message.split(value).join("[redacted]");
   }
+
   message = message.replace(/https?:\/\/[^\s"'<>]+/gi, "[redacted URL]");
   return sanitizeText(message).slice(0, 1200);
 }
@@ -74,6 +77,7 @@ function parseWorkers(value) {
   if (value === undefined || value === "auto") return "auto";
   if (typeof value === "string" && /^\d{1,2}$/.test(value) && Number(value) <= IMPORT_MAX_WORKERS)
     return Number(value);
+
   throw new Error(`--workers takes auto or a whole number from 0 to ${IMPORT_MAX_WORKERS}.`);
 }
 
@@ -85,11 +89,13 @@ function checkAbort(signal) {
 /** @param {string} address @param {boolean} [is_ingest] */
 function safeUrl(address, is_ingest = false) {
   let url;
+
   try {
     url = new URL(address);
   } catch {
     throw new Error("Invalid destination address.");
   }
+
   if (
     url.username ||
     url.password ||
@@ -100,8 +106,10 @@ function safeUrl(address, is_ingest = false) {
       "Use an HTTPS address, or HTTP on localhost, without URL credentials or fragments."
     );
   }
+
   if (is_ingest && !url.searchParams.get("key"))
     throw new Error("The ingest address must contain its key.");
+
   return url;
 }
 
@@ -113,9 +121,12 @@ function safeUrl(address, is_ingest = false) {
 function requestSignal(parent, milliseconds) {
   const controller = new AbortController();
   const abort = () => controller.abort();
+
   if (parent.aborted) abort();
   else parent.addEventListener("abort", abort, { once: true });
+
   const timer = setTimeout(abort, milliseconds);
+
   return {
     signal: controller.signal,
     dispose() {
@@ -128,18 +139,25 @@ function requestSignal(parent, milliseconds) {
 /** @param {Response} response */
 async function smallJson(response) {
   if (!response.body) throw new Error("Missing response.");
+
   const reader = response.body.getReader();
   const decoder = new TextDecoder("utf-8", { fatal: true });
   let text = "";
   let bytes = 0;
+
   try {
     for (;;) {
       const { value, done } = await reader.read();
+
       if (done) break;
+
       bytes += value.byteLength;
+
       if (bytes > 64 * 1024) throw new Error("Oversized response.");
+
       text += decoder.decode(value, { stream: true });
     }
+
     return JSON.parse(text + decoder.decode());
   } finally {
     // Stream cleanup must not hold up the result or cancellation of the command.
@@ -154,6 +172,7 @@ async function smallJson(response) {
  */
 async function getJson(url, options, signal, request) {
   const linked = requestSignal(signal, 8000);
+
   try {
     const response = await request(url, {
       ...options,
@@ -163,10 +182,12 @@ async function getJson(url, options, signal, request) {
       cache: "no-store",
       credentials: "omit"
     });
+
     if (!response.ok) {
       void response.body?.cancel().catch(() => {});
       throw new Error("Refused response.");
     }
+
     return await smallJson(response);
   } catch {
     checkAbort(signal);
@@ -190,26 +211,35 @@ async function resolveDestination(flags, signal, request, read_config) {
     typeof flags["project-id"] === "string"
       ? flags["project-id"]
       : resolveSetting("project", { flags, config });
+
   if (flags.project && flags["project-id"] && flags.project !== flags["project-id"]) {
     throw new Error("--project and --project-id must name the same project.");
   }
+
   if (!project_id || project_id === "." || project_id === "..")
     throw new Error("Upload requires --project (or a configured project).");
+
   let url;
+
   if (typeof flags["ingest-url"] === "string") {
     if (flags["source-id"] || flags["ingest-key-id"])
       throw new Error("Choose --ingest-url or explicit --source-id/--ingest-key-id, not both.");
+
     url = safeUrl(flags["ingest-url"], true);
   } else {
     const source_id = flags["source-id"];
     const ingest_key_id = flags["ingest-key-id"];
+
     if (typeof source_id !== "string" || typeof ingest_key_id !== "string") {
       throw new Error("Upload requires --ingest-url, or both --source-id and --ingest-key-id.");
     }
+
     if ([source_id, ingest_key_id].some((id) => id === "." || id === ".."))
       throw new Error("Destination IDs cannot be dot segments.");
+
     const api_url = safeUrl(resolveApiUrl({ flags, config }));
     let credential;
+
     try {
       credential = resolveCredential({ flags, config });
     } catch {
@@ -217,6 +247,7 @@ async function resolveDestination(flags, signal, request, read_config) {
         "Sign in to the configured API or supply an API key to resolve this ingest key."
       );
     }
+
     const team_id = resolveSetting("team", { flags, config }) ?? credential.login?.team_id ?? null;
     const path =
       "/v1/projects/" +
@@ -236,6 +267,7 @@ async function resolveDestination(flags, signal, request, read_config) {
     );
 
     const key = payload?.data;
+
     if (
       key?.id !== ingest_key_id ||
       key.source_id !== source_id ||
@@ -246,13 +278,16 @@ async function resolveDestination(flags, signal, request, read_config) {
         "The selected ingest key is unavailable, inactive, or belongs to another source."
       );
     }
+
     url = safeUrl(key.url, true);
+
     if (LOCAL_HOSTS.has(api_url.hostname) && !LOCAL_HOSTS.has(url.hostname)) {
       throw new Error(
         "A local API returned a remote ingest address. Pass an explicit --ingest-url for the intended destination."
       );
     }
   }
+
   url.searchParams.set("collection", String(flags.collection));
   return { url, project_id };
 }
@@ -266,10 +301,13 @@ function renderHumanReport(report) {
         ? "Full validation complete."
         : "Sample or discovery only; upload validation is still required."
     ];
+
     lines.push(
       "File size: " + report.total_bytes + " bytes; scanned " + report.bytes_read + " bytes."
     );
+
     const xml = /** @type {any} */ (report.xml);
+
     if (xml?.record_paths?.length)
       lines.push(
         "XML record paths: " +
@@ -277,9 +315,11 @@ function renderHumanReport(report) {
             .map((/** @type {{ path: string }} */ entry) => sanitizeText(entry.path))
             .join(", ")
       );
+
     const fields = /** @type {import("./import.generated.js").FieldProfile[]} */ (
       report.fields ?? []
     );
+
     if (fields.length) {
       lines.push("Fields:");
       for (const field of fields.slice(0, 20))
@@ -293,20 +333,26 @@ function renderHumanReport(report) {
             ", missing " +
             field.missing
         );
+
       if (fields.length > 20) lines.push("  More fields are available with --json.");
     }
+
     const candidates = /** @type {import("./import.generated.js").TimestampCandidate[]} */ (
       report.timestamp_candidates ?? []
     );
+
     if (candidates.length)
       lines.push(
         "Timestamp candidates: " + candidates.map((entry) => sanitizeText(entry.path)).join(", ")
       );
+
     for (const warning of /** @type {string[]} */ (report.warnings ?? []))
       lines.push(sanitizeText(warning));
     return lines.join("\n");
   }
+
   const affected = /** @type {any} */ (report.affected_batch);
+
   return [
     report.status === "complete"
       ? "Import complete."
@@ -369,14 +415,19 @@ export async function runImportCommand(argv, context = {}) {
   const signal = controller.signal;
   const abort = () => controller.abort();
   const external_signal = context.signal;
+
   if (external_signal?.aborted) abort();
   else external_signal?.addEventListener("abort", abort, { once: true });
+
   process.on("SIGINT", abort);
+
   const stderr = context.stderr ?? process.stderr;
   const request = context.request ?? fetch;
   let result;
+
   try {
     let positionals;
+
     try {
       ({ values: flags, positionals } = parseArgs({
         args: argv,
@@ -387,8 +438,10 @@ export async function runImportCommand(argv, context = {}) {
     } catch {
       throw new Error("Invalid import options. Run tglow import --help.");
     }
+
     for (const [name, value] of Object.entries(flags)) {
       const option = IMPORT_PARSER_OPTIONS[name];
+
       if (!option) throw new Error("Unknown import option. Run tglow import --help.");
       if (option.type === "boolean") {
         if (value === "true" || value === "false") flags[name] = value === "true";
@@ -398,18 +451,23 @@ export async function runImportCommand(argv, context = {}) {
         throw new Error("--" + name + " requires a value.");
       }
     }
+
     if (flags.help || positionals.length === 1) {
       return {
         output: shouldEmitJson(flags) ? JSON.stringify(describeImportForMachines(), null, 2) : HELP,
         code: 0
       };
     }
+
     if (positionals[0] !== "import") throw new Error("Expected the import command.");
+
     const words = positionals.slice(1);
+
     if (words[0] === "scan" || words[0] === "validate") {
       action = words[0];
       words.shift();
     }
+
     if (words.length !== 1)
       throw new Error("Specify exactly one input file. Run tglow import --help.");
     if (action !== "scan" && flags.full !== undefined)
@@ -418,7 +476,9 @@ export async function runImportCommand(argv, context = {}) {
       throw new Error("--validate-first only applies to uploading.");
     if (!FORMATS.includes(String(flags.format ?? "auto")))
       throw new Error("Unsupported --format. Use auto, xml, jsonl, json, csv, or tsv.");
+
     const workers = parseWorkers(flags.workers);
+
     if (
       action !== "import" &&
       ["ingest-url", "collection", "source-id", "ingest-key-id"].some(
@@ -427,13 +487,17 @@ export async function runImportCommand(argv, context = {}) {
     ) {
       throw new Error("Destination options apply only to uploading, not scan or validate.");
     }
+
     if (action === "import" && (typeof flags.collection !== "string" || !flags.collection.trim()))
       throw new Error("Upload requires an explicit --collection.");
+
     checkAbort(signal);
+
     let last_progress = 0;
     /** @param {import("./import.generated.js").ImportProgress} progress */
     const onprogress = ({ bytes_read, total_bytes, rows }) => {
       if (Date.now() - last_progress < 1000) return;
+
       last_progress = Date.now();
       stderr.write("Reading: " + bytes_read + "/" + total_bytes + " bytes, " + rows + " rows.\n");
     };
@@ -443,6 +507,7 @@ export async function runImportCommand(argv, context = {}) {
     /** @param {import("./import.generated.js").ImportWorkerStatus} status */
     const onworkers = (status) => {
       let line;
+
       if (status.fallback)
         line = `XML workers stopped (${status.fallback}); continuing sequentially.`;
       else if (status.actual)
@@ -450,10 +515,12 @@ export async function runImportCommand(argv, context = {}) {
       else if (status.requested || (workers !== "auto" && workers > 0))
         line = `XML workers: none, reading sequentially (${status.reason}).`;
       else return;
+
       stderr.write(sanitizeText(line) + "\n");
     };
 
     outcome = "file_error";
+
     if (action === "import" && flags["validate-first"] === true) {
       stderr.write("Making a private snapshot for a full check before upload.\n");
       input = await snapshotImportFile(words[0], {
@@ -461,8 +528,11 @@ export async function runImportCommand(argv, context = {}) {
         temporary_root: context.temporary_root
       });
     } else input = await openImportFile(words[0], { signal });
+
     const source = input.source;
+
     outcome = "validation_failed";
+
     const detection = await detectImport(source, {
       format: /** @type {any} */ (flags.format ?? "auto"),
       signal
@@ -482,9 +552,11 @@ export async function runImportCommand(argv, context = {}) {
       ...options,
       is_full: action === "validate" || flags.full === true || flags["validate-first"] === true
     });
+
     if (action !== "import") {
       if (action === "validate" && (!report.is_complete || report.is_sampled))
         throw new Error("Validation did not cover the complete selected input.");
+
       return {
         output: shouldEmitJson(flags)
           ? JSON.stringify({ action, ...report }, null, 2)
@@ -492,10 +564,13 @@ export async function runImportCommand(argv, context = {}) {
         code: 0
       };
     }
+
     if (flags["validate-first"] === true && (!report.is_complete || report.is_sampled))
       throw new Error("The full file check did not finish.");
+
     total_rows = report.is_complete && !report.is_sampled ? report.row_count : null;
     outcome = "destination_failed";
+
     const destination = await resolveDestination(
       flags,
       signal,
@@ -504,8 +579,10 @@ export async function runImportCommand(argv, context = {}) {
     );
 
     const readiness = await getJson(destination.url, {}, signal, request);
+
     if (readiness?.status !== "ready" || readiness.project_id !== destination.project_id)
       throw new Error("The ingest endpoint is not ready for the expected project.");
+
     outcome = "validation_failed";
     for await (const batch of createImportBatches(readImportRows(source, options))) {
       checkAbort(signal);
@@ -516,8 +593,11 @@ export async function runImportCommand(argv, context = {}) {
         last_row: batch.rows[batch.rows.length - 1].index,
         status: "uncertain"
       };
+
       outcome = "uncertain_delivery";
+
       const linked = requestSignal(signal, 30_000);
+
       try {
         const response = await request(destination.url, {
           method: "POST",
@@ -527,10 +607,12 @@ export async function runImportCommand(argv, context = {}) {
           redirect: "error",
           credentials: "omit"
         });
+
         if (response.status !== 202) {
           affected_batch.status = IMPORT_REJECTED_STATUSES.includes(response.status)
             ? "rejected"
             : "uncertain";
+
           outcome = affected_batch.status === "rejected" ? "rejected" : "uncertain_delivery";
           affected_batch.http_status = response.status;
           void response.body?.cancel().catch(() => {});
@@ -538,9 +620,11 @@ export async function runImportCommand(argv, context = {}) {
             "The server did not acknowledge the batch. Upload stopped without retrying."
           );
         }
+
         accepted_count += batch.rows.length;
         affected_batch = null;
         void response.body?.cancel().catch(() => {});
+
         if (Date.now() - last_progress >= 1000 || accepted_count === total_rows) {
           last_progress = Date.now();
           stderr.write(
@@ -553,22 +637,27 @@ export async function runImportCommand(argv, context = {}) {
       } catch {
         if (affected_batch?.status === "rejected")
           throw new Error("The server rejected the batch. Upload stopped without retrying.");
+
         throw new Error(
           "No acknowledgement from the server. The affected batch may have arrived; upload stopped without retrying."
         );
       } finally {
         linked.dispose();
       }
+
       outcome = "validation_failed";
     }
+
     checkAbort(signal);
     await input.assertUnchanged();
+
     if (!accepted_count)
       throw new Error(
         "This selection has no data rows. Check the XML record path or file contents."
       );
     if (total_rows !== null && accepted_count !== total_rows)
       throw new Error("The imported row count differed from the full file check.");
+
     total_rows = accepted_count;
     result = {
       action,
@@ -592,18 +681,22 @@ export async function runImportCommand(argv, context = {}) {
           error = source_error;
       }
     }
+
+    let failure_outcome = outcome;
+
+    if (
+      error &&
+      typeof error === "object" &&
+      "code" in error &&
+      error.code === "IMPORT_SOURCE_CHANGED"
+    )
+      failure_outcome = "file_changed";
+    else if (signal.aborted && !affected_batch) failure_outcome = "cancelled";
+
     result = {
       action,
       status: signal.aborted ? "cancelled" : "failed",
-      outcome:
-        error &&
-        typeof error === "object" &&
-        "code" in error &&
-        error.code === "IMPORT_SOURCE_CHANGED"
-          ? "file_changed"
-          : signal.aborted && !affected_batch
-            ? "cancelled"
-            : outcome,
+      outcome: failure_outcome,
       ...(error &&
       typeof error === "object" &&
       "index" in error &&
@@ -622,15 +715,23 @@ export async function runImportCommand(argv, context = {}) {
       } catch {
         const cleanup_error =
           "Could not close the input or remove its private temporary snapshot. Check the tailglow-import directory in your temporary folder.";
+
         result = { ...result, cleanup_error };
         stderr.write("Warning: " + cleanup_error + "\n");
       }
     }
+
     external_signal?.removeEventListener("abort", abort);
     process.removeListener("SIGINT", abort);
   }
+
+  let exit_code = 1;
+
+  if (result.status === "complete") exit_code = 0;
+  else if (signal.aborted) exit_code = 130;
+
   return {
     output: shouldEmitJson(flags) ? JSON.stringify(result, null, 2) : renderHumanReport(result),
-    code: result.status === "complete" ? 0 : signal.aborted ? 130 : 1
+    code: exit_code
   };
 }