@plantnet/planttaxomatcher 0.1.0 → 0.1.2

package/dist/index.js

@@ -101,7 +101,16 @@ var jobConfigSchema = z3.object({
    * resolved version on `jobs.referential_version` so re-runs are
    * reproducible even if a newer snapshot lands later.
    */
-  referentialVersion: z3.string().min(1).optional()
+  referentialVersion: z3.string().min(1).optional(),
+  /**
+   * Row filter: keep only rows whose `filterColumn` value equals
+   * `filterValue` (trimmed, case-insensitive); all other rows are skipped at
+   * ingest (no match query created). Both must be set for the filter to
+   * apply. Lets a user match a subset of a mixed file (e.g. only
+   * `kingdom = Plantae`).
+   */
+  filterColumn: z3.string().nullable().optional(),
+  filterValue: z3.string().nullable().optional()
 });
 var wcvpSnapshotSummarySchema = z3.object({
   version: z3.string(),
@@ -785,6 +794,7 @@ var apiClient = {
     const params = new URLSearchParams({ format: opts.format });
     if (opts.confirmedOnly) params.set("confirmedOnly", "true");
     if (opts.bundle) params.set("bundle", "true");
+    if (opts.delimiter) params.set("delimiter", opts.delimiter);
     if (opts.columns) params.set("columns", opts.columns);
     if (opts.wcvpExtra) params.set("wcvpExtra", opts.wcvpExtra);
     const url = new URL(`/v1/jobs/${id}/download?${params}`, creds.server).toString();
@@ -795,7 +805,7 @@ var apiClient = {
     }
     const disp = res.headers.get("content-disposition") ?? "";
     const m = /filename="?([^"]+)"?/.exec(disp);
-    const ext = opts.bundle ? "zip" : opts.format === "csv" ? "csv" : opts.format === "json" ? "json" : "ndjson";
+    const ext = opts.bundle ? "zip" : opts.format === "csv" ? "csv" : opts.format === "json" ? "json" : opts.format === "xlsx" ? "xlsx" : "ndjson";
     const filename = m?.[1] ?? `planttaxomatcher_${id}.${ext}`;
     const buf = Buffer.from(await res.arrayBuffer());
     return { filename, body: buf };
@@ -810,20 +820,25 @@ var apiClient = {
     const reader = res.body.getReader();
     const decoder = new TextDecoder("utf-8");
     let buf = "";
-    for (; ; ) {
-      const { done, value } = await reader.read();
-      if (done) break;
-      buf += decoder.decode(value, { stream: true });
-      let nl;
-      while ((nl = buf.indexOf("\n")) >= 0) {
-        const line = buf.slice(0, nl).trim();
-        buf = buf.slice(nl + 1);
-        if (!line) continue;
-        try {
-          yield JSON.parse(line);
-        } catch {
+    try {
+      for (; ; ) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, nl).trim();
+          buf = buf.slice(nl + 1);
+          if (!line) continue;
+          try {
+            yield JSON.parse(line);
+          } catch {
+          }
         }
       }
+    } finally {
+      await reader.cancel().catch(() => {
+      });
     }
   }
 };
@@ -863,9 +878,8 @@ async function requireCredentials() {
 }
 
 // src/dry-run.ts
-import { promises as fs3 } from "fs";
-import { Readable } from "stream";
-import { parse as parseCsvStream } from "csv-parse";
+import { promises as fs3, createReadStream } from "fs";
+import Papa from "papaparse";
 import kleur from "kleur";
 async function readSample(file, sampleLimit) {
   const lower = file.toLowerCase();
@@ -873,54 +887,47 @@ async function readSample(file, sampleLimit) {
     const text = await fs3.readFile(file, "utf8");
     const arr = JSON.parse(text);
     if (!Array.isArray(arr)) throw new Error("JSON file must be an array of row objects");
-    const out2 = [];
+    const out = [];
     for (const v of arr) {
-      if (out2.length >= sampleLimit) break;
+      if (out.length >= sampleLimit) break;
       if (v && typeof v === "object") {
         const row = {};
         for (const [k, val] of Object.entries(v)) row[k] = val == null ? "" : String(val);
-        out2.push(row);
+        out.push(row);
       }
     }
-    return out2;
-  }
-  const head = Buffer.alloc(4096);
-  const fh = await fs3.open(file, "r");
-  let bytesRead = 0;
-  try {
-    bytesRead = (await fh.read(head, 0, 4096, 0)).bytesRead;
-  } finally {
-    await fh.close();
+    return out;
   }
-  const delimiter = detectDelimiter(head.subarray(0, bytesRead));
-  const buf = await fs3.readFile(file);
-  const parser = Readable.from(buf).pipe(
-    parseCsvStream({
-      columns: true,
-      skip_empty_lines: true,
-      trim: true,
-      delimiter,
-      relax_quotes: true,
-      relax_column_count: true
-    })
-  );
-  const out = [];
-  for await (const row of parser) {
-    out.push(row);
-    if (out.length >= sampleLimit) break;
-  }
-  return out;
-}
-function detectDelimiter(buf) {
-  const head = buf.toString("utf8").split("\n", 5).join("\n");
-  const counts = {
-    ",": (head.match(/,/g) ?? []).length,
-    ";": (head.match(/;/g) ?? []).length,
-    "	": (head.match(/\t/g) ?? []).length,
-    "|": (head.match(/\|/g) ?? []).length
-  };
-  const winner = Object.entries(counts).sort((a, b) => b[1] - a[1])[0];
-  return winner && winner[1] > 0 ? winner[0] : ",";
+  return await new Promise((resolve, reject) => {
+    const out = [];
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      resolve(out);
+    };
+    const stream = createReadStream(file);
+    const parseStream = Papa.parse(Papa.NODE_STREAM_INPUT, {
+      header: true,
+      skipEmptyLines: "greedy",
+      delimitersToGuess: [",", ";", "	", "|"],
+      transformHeader: (h) => h.trim(),
+      transform: (v) => typeof v === "string" ? v.trim() : v
+    });
+    stream.on("error", reject);
+    parseStream.on("error", reject);
+    parseStream.on("data", (row) => {
+      const o = {};
+      for (const [k, val] of Object.entries(row)) o[k] = val == null ? "" : String(val);
+      out.push(o);
+      if (out.length >= sampleLimit) {
+        stream.destroy();
+        finish();
+      }
+    });
+    parseStream.on("end", finish);
+    stream.pipe(parseStream);
+  });
 }
 async function buildDryRunReport(file, opts) {
   const sampleLimit = opts.sampleLimit ?? 1e3;
@@ -1017,7 +1024,7 @@ function trunc(s, n) {
 
 // src/index.ts
 var program = new Command();
-program.name("planttaxomatcher").description("PlantTaxoMatcher CLI").version("0.1.0");
+program.name("planttaxomatcher").description("PlantTaxoMatcher CLI").version("0.1.1");
 program.command("login").description("Save a personal token + server URL").option(
   "--token <token>",
   "Personal token (ptm_...). Avoid on shared hosts: it is visible in shell history and the process list. Prefer --token-stdin or the PLANTTAXOMATCHER_TOKEN env var."
@@ -1072,7 +1079,7 @@ program.command("submit <files...>").description(
 ).option(
   "--name <label>",
   "Job name override (single file only; ignored when multiple files match \u2014 the file name is used)"
-).requiredOption("--name-column <name>", "Column holding the scientific name").option("--id-column <name>", "Column holding a known ID").option("--family-column <name>", "Column holding family").option("--genus-column <name>", "Column holding genus").option("--rank-column <name>", "Column holding rank").option("--author-column <name>", "Column holding authorship").option("--author-mode <mode>", "ignore|prefer|strict", "prefer").option("--parallel <n>", "Per-job parallelism", "4").option("--review-mode <mode>", "off|recommended|strict", "recommended").option(
+).requiredOption("--name-column <name>", "Column holding the scientific name").option("--id-column <name>", "Column holding a known ID").option("--family-column <name>", "Column holding family").option("--genus-column <name>", "Column holding genus").option("--rank-column <name>", "Column holding rank").option("--author-column <name>", "Column holding authorship").option("--filter-column <name>", "Only process rows where this column matches --filter-value; others are skipped").option("--filter-value <value>", "Value the --filter-column must equal (trimmed, case-insensitive)").option("--author-mode <mode>", "ignore|prefer|strict", "prefer").option("--parallel <n>", "Per-job parallelism", "4").option("--review-mode <mode>", "off|recommended|strict", "recommended").option(
   "--keep-infraspecific",
   "Keep infraspecific accepted taxa (varieties, subspecies, forms) instead of collapsing them up to the species",
   false
@@ -1128,6 +1135,8 @@ ${file}`));
     genusColumn: opts.genusColumn ? String(opts.genusColumn) : null,
     rankColumn: opts.rankColumn ? String(opts.rankColumn) : null,
     authorColumn: opts.authorColumn ? String(opts.authorColumn) : null,
+    filterColumn: opts.filterColumn ? String(opts.filterColumn) : null,
+    filterValue: opts.filterValue != null ? String(opts.filterValue) : null,
     authorMode: String(opts.authorMode ?? "prefer"),
     matchAuthors: true,
     parallelism: Number(opts.parallel ?? 4),
@@ -1177,7 +1186,7 @@ program.command("cancel <jobId>").description("Cancel a job. Already-matched row
   const job = await apiClient.cancelJob(creds, jobId);
   console.log(kleur2.green("\u2713"), `cancelled: ${job.id} (status=${job.status})`);
 });
-program.command("download <jobId>").description("Download a job export (CSV, JSON, or NDJSON; optionally bundled with NOTICE.md)").option("--format <fmt>", "csv | json | ndjson", "csv").option("--confirmed-only", "only matched rows that are accepted / not pending", false).option("--bundle", "wrap in a ZIP with NOTICE.md citing the WCVP snapshot + providers", false).option(
+program.command("download <jobId>").description("Download a job export (CSV, JSON, or NDJSON; optionally bundled with NOTICE.md)").option("--format <fmt>", "csv | xlsx | json | ndjson", "csv").option("--confirmed-only", "only matched rows that are accepted / not pending", false).option("--delimiter <sep>", "CSV separator: comma | semicolon | tab | pipe (csv format only)", "comma").option("--bundle", "wrap in a ZIP with NOTICE.md citing the WCVP snapshot + providers", false).option(
   "--columns <list>",
   "comma-separated result/upload column keys to KEEP (default: all). See --list-columns"
 ).option(
@@ -1198,15 +1207,20 @@ program.command("download <jobId>").description("Download a job export (CSV, JSO
     return;
   }
   const format = opts.format ?? "csv";
-  if (format !== "csv" && format !== "json" && format !== "ndjson") {
-    throw new Error(`--format must be csv, json or ndjson (got ${String(format)})`);
+  if (format !== "csv" && format !== "json" && format !== "ndjson" && format !== "xlsx") {
+    throw new Error(`--format must be csv, xlsx, json or ndjson (got ${String(format)})`);
   }
   const confirmedOnly = !!opts.confirmedOnly;
   const bundle = !!opts.bundle;
+  const delimiter = String(opts.delimiter ?? "comma");
+  if (!["comma", "semicolon", "tab", "pipe"].includes(delimiter)) {
+    throw new Error(`--delimiter must be comma, semicolon, tab or pipe (got ${delimiter})`);
+  }
   const { filename, body } = await apiClient.downloadJob(creds, jobId, {
     format,
     confirmedOnly,
     bundle,
+    ...format === "csv" && delimiter !== "comma" ? { delimiter } : {},
     ...opts.columns ? { columns: String(opts.columns) } : {},
     ...opts.wcvpExtra ? { wcvpExtra: String(opts.wcvpExtra) } : {}
   });
@@ -1287,7 +1301,16 @@ async function streamJob(creds, jobId) {
     const t = String(evt.type ?? "");
     if (t === "heartbeat") continue;
     if (t === "status") {
-      console.log(kleur2.gray("\u2022"), evt.status);
+      const status = String(evt.status ?? "");
+      console.log(kleur2.gray("\u2022"), status);
+      if (status === "completed") {
+        console.log(kleur2.green("\u2713"), "completed");
+        return;
+      }
+      if (status === "failed" || status === "cancelled") {
+        console.error(kleur2.red(status));
+        return;
+      }
     } else if (t === "progress") {
       const p = evt.processedQueries ?? evt.processedRows ?? 0;
       const total = evt.totalQueries ?? evt.totalRows ?? 0;

package/package.json

@@ -1,42 +1,44 @@
 {
-  "name": "@plantnet/planttaxomatcher",
-  "version": "0.1.0",
-  "description": "PlantTaxoMatcher CLI — reconcile plant names against WCVP via the PlantTaxoMatcher API.",
-  "type": "module",
-  "engines": {
-    "node": ">=24"
-  },
-  "bin": {
-    "planttaxomatcher": "./dist/index.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@inquirer/prompts": "^8.5.0",
-    "commander": "^14.0.0",
-    "csv-parse": "^6.0.0",
-    "kleur": "^4.1.5",
-    "ora": "^9.0.0",
-    "undici": "^8.0.0",
-    "zod": "^4.0.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.12.4",
-    "tsup": "^8.5.1",
-    "tsx": "^4.20.0",
-    "typescript": "^6.0.0",
-    "vitest": "^4.1.7",
-    "@planttaxomatcher/shared": "0.0.0"
-  },
-  "scripts": {
-    "dev": "tsx src/index.ts",
-    "build": "tsup",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run --passWithNoTests",
-    "lint": "echo \"no lint yet\" && exit 0"
-  }
-}
+    "name": "@plantnet/planttaxomatcher",
+    "version": "0.1.2",
+    "description": "PlantTaxoMatcher CLI — reconcile plant names against WCVP via the PlantTaxoMatcher API.",
+    "type": "module",
+    "engines": {
+        "node": ">=24"
+    },
+    "bin": {
+        "planttaxomatcher": "./dist/index.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "dev": "tsx src/index.ts",
+        "build": "tsup",
+        "typecheck": "tsc -p tsconfig.json --noEmit",
+        "test": "vitest run --passWithNoTests",
+        "lint": "echo \"no lint yet\" && exit 0",
+        "prepublishOnly": "pnpm run build"
+    },
+    "dependencies": {
+        "@inquirer/prompts": "^8.5.0",
+        "commander": "^14.0.0",
+        "kleur": "^4.1.5",
+        "ora": "^9.0.0",
+        "papaparse": "^5.5.3",
+        "undici": "^8.0.0",
+        "zod": "^4.0.0"
+    },
+    "devDependencies": {
+        "@planttaxomatcher/shared": "workspace:*",
+        "@types/node": "^24.12.4",
+        "@types/papaparse": "^5.5.2",
+        "tsup": "^8.5.1",
+        "tsx": "^4.20.0",
+        "typescript": "^6.0.0",
+        "vitest": "^4.1.7"
+    }
+}