@plantnet/planttaxomatcher 0.1.0

package/dist/index.js

@@ -0,0 +1,1305 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { promises as fs4 } from "fs";
+import { parse as parsePath } from "path";
+import { confirm, password } from "@inquirer/prompts";
+import { Command } from "commander";
+import kleur2 from "kleur";
+
+// ../shared/src/schemas/identifiers.ts
+import { z } from "zod";
+var identifierNamespaceSchema = z.enum([
+  "wcvp:taxonID",
+  "wcvp:acceptedNameUsageID",
+  "ipni:lsid",
+  "gbif:taxonKey",
+  "powo:url"
+]);
+var taxonIdentifierSchema = z.object({
+  namespace: identifierNamespaceSchema,
+  value: z.string().min(1)
+});
+
+// ../shared/src/schemas/grading.ts
+import { z as z2 } from "zod";
+var matchStatusSchema = z2.enum(["matched", "ambiguous", "no_match", "error", "skipped"]);
+var evidenceTypeSchema = z2.enum([
+  "local_exact",
+  "local_canonical_unique",
+  "external_validated",
+  "local_fuzzy",
+  "external_fuzzy",
+  "team_history",
+  "llm"
+]);
+var gradeSchema = z2.enum(["A", "B", "C"]);
+var reviewStatusSchema = z2.enum(["not_required", "pending", "accepted", "rejected", "overridden"]);
+var identificationQualifierSchema = z2.enum([
+  "none",
+  "cf",
+  "aff",
+  "sensu_lato",
+  "sensu_stricto",
+  "aggregate",
+  "complex",
+  "sp",
+  "spp",
+  "indet",
+  "cultivar",
+  "hybrid_formula",
+  "informal"
+]);
+var scoreBreakdownSchema = z2.object({
+  canonicalSimilarity: z2.number().min(0).max(1).optional(),
+  authorSimilarity: z2.number().min(0).max(1).optional(),
+  rankCompatibility: z2.number().min(0).max(1).optional(),
+  familyCompatibility: z2.number().min(0).max(1).optional(),
+  providerAgreement: z2.number().min(0).max(1).optional()
+});
+
+// ../shared/src/schemas/job.ts
+import { z as z3 } from "zod";
+var jobStatusSchema = z3.enum([
+  "queued",
+  "parsing",
+  "matching",
+  "paused",
+  "cancelled",
+  "completed",
+  "failed"
+]);
+var authorModeSchema = z3.enum(["ignore", "prefer", "strict"]);
+var reviewModeSchema = z3.enum(["off", "recommended", "strict"]);
+var jobConfigSchema = z3.object({
+  nameColumn: z3.string().min(1),
+  idColumn: z3.string().nullable().optional(),
+  familyColumn: z3.string().nullable().optional(),
+  genusColumn: z3.string().nullable().optional(),
+  rankColumn: z3.string().nullable().optional(),
+  authorColumn: z3.string().nullable().optional(),
+  sourceReferentialColumn: z3.string().nullable().optional(),
+  sourceIdColumn: z3.string().nullable().optional(),
+  authorMode: authorModeSchema.default("prefer"),
+  matchAuthors: z3.boolean().default(true),
+  parallelism: z3.number().int().min(1).max(10).default(4),
+  allowFuzzy: z3.boolean().default(true),
+  allowLlm: z3.boolean().default(false),
+  llmCostCapCents: z3.number().int().min(0).default(500),
+  reviewMode: reviewModeSchema.default("recommended"),
+  exportConfirmedOnly: z3.boolean().default(false),
+  /**
+   * Keep the identified accepted name at species level: when an input
+   * resolves to an infraspecific accepted taxon (Variety / Subspecies /
+   * Form / …), collapse it up to its parent Species. Default true; set false
+   * to keep the exact infraspecific accepted taxon.
+   */
+  speciesLevelAcceptedOnly: z3.boolean().default(true),
+  /**
+   * Which WCVP snapshot to match against. When omitted, the API picks the
+   * most-recently-imported snapshot at submit time. The job stores the
+   * resolved version on `jobs.referential_version` so re-runs are
+   * reproducible even if a newer snapshot lands later.
+   */
+  referentialVersion: z3.string().min(1).optional()
+});
+var wcvpSnapshotSummarySchema = z3.object({
+  version: z3.string(),
+  recordCount: z3.number().int().nonnegative(),
+  importedAt: z3.string().datetime(),
+  isLatest: z3.boolean()
+});
+var idTypeDetectionSchema = z3.object({
+  sampleSize: z3.number().int().nonnegative(),
+  counts: z3.record(z3.string(), z3.number().int().nonnegative()),
+  dominant: z3.string().nullable(),
+  dominantConfidence: z3.number().min(0).max(1),
+  minorityExamples: z3.array(
+    z3.object({
+      rowIndex: z3.number().int().nonnegative(),
+      value: z3.string(),
+      type: z3.string()
+    })
+  )
+});
+var publicAccessSchema = z3.enum(["none", "read", "review"]);
+var jobSummarySchema = z3.object({
+  id: z3.string().ulid(),
+  teamId: z3.string().uuid(),
+  userId: z3.string().uuid(),
+  /** Optional user-supplied label. URL still uses `id`; null when unset. */
+  name: z3.string().nullable(),
+  /** Display name of the user who submitted the job (from their token's
+   * user). Null when unavailable (e.g. mutation responses). */
+  submittedBy: z3.string().nullable(),
+  status: jobStatusSchema,
+  /** 'none' = private. 'read'/'review' = anyone with the link, no sign-in. */
+  publicAccess: publicAccessSchema,
+  referentialVersion: z3.string(),
+  idColumn: z3.string().nullable(),
+  idTypeDetection: idTypeDetectionSchema.nullable(),
+  totalRows: z3.number().int().nonnegative(),
+  uniqueQueries: z3.number().int().nonnegative(),
+  processedRows: z3.number().int().nonnegative(),
+  matchedRows: z3.number().int().nonnegative(),
+  ambiguousRows: z3.number().int().nonnegative(),
+  errorRows: z3.number().int().nonnegative(),
+  needsReviewRows: z3.number().int().nonnegative(),
+  llmCostCents: z3.number().int().nonnegative(),
+  llmCostCapCents: z3.number().int().nonnegative(),
+  createdAt: z3.string().datetime(),
+  startedAt: z3.string().datetime().nullable(),
+  completedAt: z3.string().datetime().nullable(),
+  expiresAt: z3.string().datetime()
+});
+var jobPublicAccessUpdateSchema = z3.object({
+  publicAccess: publicAccessSchema
+});
+var progressEventSchema = z3.object({
+  type: z3.enum(["progress", "status", "error", "completed"]),
+  jobId: z3.string().ulid(),
+  timestamp: z3.string().datetime(),
+  processedRows: z3.number().int().nonnegative().optional(),
+  totalRows: z3.number().int().nonnegative().optional(),
+  status: jobStatusSchema.optional(),
+  message: z3.string().optional()
+});
+var taxonIdentifierRefSchema = z3.object({
+  namespace: z3.string(),
+  value: z3.string()
+});
+var jobRowSummarySchema = z3.object({
+  id: z3.string().uuid(),
+  rowIndex: z3.number().int().nonnegative(),
+  inputName: z3.string().nullable(),
+  inputId: z3.string().nullable(),
+  inputFamily: z3.string().nullable(),
+  matchStatus: matchStatusSchema.nullable(),
+  grade: gradeSchema.nullable(),
+  evidenceType: z3.string().nullable(),
+  reviewStatus: reviewStatusSchema,
+  matchQueryId: z3.string().uuid().nullable(),
+  confidence: z3.number().nullable(),
+  layer: z3.string().nullable(),
+  flags: z3.array(z3.string()).nullable(),
+  candidateAcceptedName: z3.string().nullable(),
+  /** Authorship of the accepted taxon (distinct from `candidateAuthorship`
+   * which carries the matched-row author when the match resolves via a synonym). */
+  candidateAcceptedAuthorship: z3.string().nullable(),
+  candidateAcceptedIdentifiers: z3.array(taxonIdentifierRefSchema).nullable(),
+  candidateScientificName: z3.string().nullable(),
+  candidateAuthorship: z3.string().nullable(),
+  candidateFamily: z3.string().nullable(),
+  candidateReason: z3.string().nullable(),
+  candidateTargetUrl: z3.string().nullable()
+});
+var gradeCountsSchema = z3.object({
+  A: z3.number().int().nonnegative(),
+  B: z3.number().int().nonnegative(),
+  C: z3.number().int().nonnegative(),
+  ungraded: z3.number().int().nonnegative()
+});
+var statusCountsSchema = z3.object({
+  matched: z3.number().int().nonnegative(),
+  ambiguous: z3.number().int().nonnegative(),
+  no_match: z3.number().int().nonnegative(),
+  error: z3.number().int().nonnegative(),
+  skipped: z3.number().int().nonnegative(),
+  /** Rows whose match query exists but hasn't been processed yet (mid-run).
+   * Distinct from `skipped` (no query — empty/guarded input). Not part of the
+   * outcome funnel; the SPA can show it as in-progress. */
+  pending: z3.number().int().nonnegative()
+});
+var jobRowsPageSchema = z3.object({
+  rows: z3.array(jobRowSummarySchema),
+  /** Row count matching the CURRENT filter (not the whole job) — drives
+   * pagination so page count adapts to active grade/status/search/conf filters. */
+  total: z3.number().int().nonnegative(),
+  offset: z3.number().int().nonnegative(),
+  limit: z3.number().int().positive(),
+  /** Per-grade row counts for the whole job, independent of the current
+   * filter. Used by the SPA to show "B (12)" next to each grade chip. */
+  gradeCounts: gradeCountsSchema,
+  /** Per-status row counts (matched / ambiguous / no_match / error /
+   * skipped), same scope + purpose as `gradeCounts`. */
+  statusCounts: statusCountsSchema
+});
+var wcvpSearchHitSchema = z3.object({
+  taxonId: z3.string(),
+  scientificName: z3.string(),
+  canonicalName: z3.string(),
+  authorship: z3.string().nullable(),
+  rank: z3.string().nullable(),
+  taxonomicStatus: z3.string().nullable(),
+  family: z3.string().nullable(),
+  acceptedTaxonId: z3.string().nullable(),
+  acceptedName: z3.string().nullable(),
+  similarity: z3.number()
+});
+var wcvpSearchResponseSchema = z3.array(wcvpSearchHitSchema);
+var jobDiffRowSchema = z3.object({
+  rowId: z3.string().uuid(),
+  rowIndex: z3.number().int().nonnegative(),
+  inputName: z3.string().nullable(),
+  inputFamily: z3.string().nullable(),
+  matchedName: z3.string().nullable(),
+  matchedAuthorship: z3.string().nullable(),
+  matchedTaxonomicStatus: z3.string().nullable(),
+  acceptedName: z3.string().nullable(),
+  acceptedAuthorship: z3.string().nullable(),
+  acceptedFamily: z3.string().nullable(),
+  isSynonym: z3.boolean(),
+  familyChanged: z3.boolean(),
+  grade: gradeSchema.nullable(),
+  reviewStatus: reviewStatusSchema,
+  targetUrl: z3.string().nullable()
+});
+var jobDiffPageSchema = z3.object({
+  rows: z3.array(jobDiffRowSchema),
+  total: z3.number().int().nonnegative()
+});
+var reviewActionSchema = z3.enum(["accept", "reject"]);
+var reviewRequestSchema = z3.object({
+  action: reviewActionSchema,
+  candidateId: z3.string().uuid()
+});
+var bulkReviewRequestSchema = z3.object({
+  action: reviewActionSchema,
+  filter: z3.object({
+    grade: gradeSchema.optional(),
+    matchStatus: matchStatusSchema.optional(),
+    family: z3.string().optional()
+  }).default({}),
+  dryRun: z3.boolean().default(false)
+});
+var bulkReviewResponseSchema = z3.object({
+  action: reviewActionSchema,
+  matchedQueries: z3.number().int().nonnegative(),
+  dryRun: z3.boolean(),
+  appliedAt: z3.string().datetime().nullable()
+});
+var reviewResponseSchema = z3.object({
+  matchQueryId: z3.string().uuid(),
+  action: reviewActionSchema,
+  candidateId: z3.string().uuid(),
+  reviewStatus: reviewStatusSchema,
+  reviewEventId: z3.string().uuid()
+});
+var matchAttemptSummarySchema = z3.object({
+  id: z3.string().uuid(),
+  layer: z3.string(),
+  provider: z3.string(),
+  status: z3.string(),
+  durationMs: z3.number().int().nonnegative(),
+  // JSONB fields accept any shape. Note: `z.unknown()` infers as optional,
+  // so consumers should guard for `undefined` even though we always send
+  // them as part of the response.
+  query: z3.unknown(),
+  rawResponseSummary: z3.unknown().nullable(),
+  createdAt: z3.string().datetime()
+});
+var matchCandidateSummarySchema = z3.object({
+  id: z3.string().uuid(),
+  attemptId: z3.string().uuid(),
+  source: z3.string(),
+  sourceId: z3.string().nullable(),
+  scientificName: z3.string(),
+  canonicalName: z3.string(),
+  authorship: z3.string().nullable(),
+  rank: z3.string().nullable(),
+  taxonomicStatus: z3.string().nullable(),
+  acceptedName: z3.string().nullable(),
+  acceptedAuthorship: z3.string().nullable(),
+  acceptedIdentifiers: z3.array(taxonIdentifierRefSchema).nullable(),
+  identifiers: z3.array(taxonIdentifierRefSchema),
+  family: z3.string().nullable(),
+  confidence: z3.number().nullable(),
+  grade: gradeSchema.nullable(),
+  reason: z3.string().nullable(),
+  flags: z3.array(z3.string()).nullable(),
+  state: z3.enum(["proposed", "accepted", "rejected", "overridden"]),
+  targetUrl: z3.string().nullable()
+});
+var matchQueryDetailSchema = z3.object({
+  id: z3.string().uuid(),
+  jobId: z3.string().ulid(),
+  normalizedInput: z3.string(),
+  parsed: z3.unknown(),
+  matchStatus: matchStatusSchema.nullable(),
+  evidenceType: z3.string().nullable(),
+  grade: gradeSchema.nullable(),
+  confidence: z3.number().nullable(),
+  flags: z3.array(z3.string()).nullable(),
+  reviewStatus: reviewStatusSchema,
+  selectedCandidateId: z3.string().uuid().nullable()
+});
+var queryCandidatesResponseSchema = z3.object({
+  query: matchQueryDetailSchema,
+  candidates: z3.array(matchCandidateSummarySchema),
+  attempts: z3.array(matchAttemptSummarySchema)
+});
+var reviewChatMessageSchema = z3.object({
+  role: z3.enum(["user", "assistant"]),
+  content: z3.string().min(1).max(4e3)
+});
+var reviewChatBodySchema = z3.object({
+  messages: z3.array(reviewChatMessageSchema).min(1).max(40)
+});
+var reviewChatResponseSchema = z3.object({
+  reply: z3.string(),
+  model: z3.string()
+});
+var replayableLayerSchema = z3.enum(["L1", "L2", "L3", "L4", "L5", "L6", "L7"]);
+var replayLayerBodySchema = z3.object({ layer: replayableLayerSchema });
+var replayCandidateSchema = z3.object({
+  scientificName: z3.string(),
+  canonicalName: z3.string(),
+  authorship: z3.string().nullable(),
+  rank: z3.string().nullable(),
+  taxonomicStatus: z3.string().nullable(),
+  acceptedName: z3.string().nullable(),
+  acceptedAuthorship: z3.string().nullable(),
+  family: z3.string().nullable(),
+  /** WCVP taxon id of the matched row (null for unresolved external proposals). */
+  taxonId: z3.string().nullable(),
+  /** WCVP taxon id of the resolved accepted taxon (null when unresolved). */
+  acceptedTaxonId: z3.string().nullable(),
+  confidence: z3.number().nullable(),
+  reason: z3.string().nullable(),
+  flags: z3.array(z3.string()),
+  targetUrl: z3.string().nullable(),
+  /** Provider that proposed this candidate (e.g. tnrs, gbif, openrouter,
+   * wcvp-local). */
+  provider: z3.string().nullable()
+});
+var replayAttemptSchema = z3.object({
+  provider: z3.string(),
+  status: z3.string(),
+  durationMs: z3.number().int().nonnegative(),
+  summary: z3.unknown().nullable()
+});
+var replayLayerResultSchema = z3.object({
+  layer: replayableLayerSchema,
+  kind: z3.enum(["unique", "ambiguous", "miss"]),
+  reason: z3.string().nullable(),
+  /** Human-facing note when the layer couldn't run as-is (e.g. LLM not
+   * configured, no external providers enabled). */
+  note: z3.string().nullable(),
+  providers: z3.array(z3.string()),
+  durationMs: z3.number().int().nonnegative(),
+  /** What was actually submitted to the layer (post gnparser). */
+  query: z3.object({
+    canonical: z3.string(),
+    authorship: z3.string().nullable(),
+    inputId: z3.string().nullable()
+  }),
+  candidates: z3.array(replayCandidateSchema),
+  attempts: z3.array(replayAttemptSchema)
+});
+
+// ../shared/src/schemas/auth.ts
+import { z as z4 } from "zod";
+var tokenScopeSchema = z4.enum([
+  "submit:job",
+  "read:job",
+  "cancel:job",
+  "review:job",
+  "override:match",
+  "download:job",
+  "admin:tokens",
+  "admin:jobs",
+  "admin:teams"
+]);
+var ALL_TOKEN_SCOPES = tokenScopeSchema.options;
+var tokenStringSchema = z4.string().regex(/^ptm_[a-zA-Z0-9]{12}_[a-zA-Z0-9]{32}$/, "Malformed token");
+var meSchema = z4.object({
+  userId: z4.string().uuid(),
+  teamId: z4.string().uuid(),
+  displayName: z4.string(),
+  scopes: z4.array(tokenScopeSchema),
+  tokenLabel: z4.string().nullable()
+});
+var tokenCreateBodySchema = z4.object({
+  label: z4.string().min(1).max(120),
+  scopes: z4.array(tokenScopeSchema).min(1),
+  expiresAt: z4.string().datetime().optional()
+});
+var tokenSummarySchema = z4.object({
+  id: z4.string().uuid(),
+  tokenIdPrefix: z4.string(),
+  label: z4.string(),
+  displayName: z4.string(),
+  scopes: z4.array(tokenScopeSchema),
+  createdAt: z4.string().datetime(),
+  lastUsedAt: z4.string().datetime().nullable(),
+  expiresAt: z4.string().datetime().nullable()
+});
+var tokenCreatedSchema = tokenSummarySchema.extend({
+  tokenString: tokenStringSchema
+});
+var teamSummarySchema = z4.object({
+  id: z4.string().uuid(),
+  name: z4.string(),
+  createdAt: z4.string().datetime()
+});
+var teamCreateBodySchema = z4.object({
+  name: z4.string().min(1).max(120),
+  initialUserDisplayName: z4.string().min(1).max(120).default("Admin"),
+  initialToken: z4.object({
+    label: z4.string().min(1).max(120),
+    scopes: z4.array(tokenScopeSchema).min(1)
+  }).optional()
+});
+var teamCreatedSchema = teamSummarySchema.extend({
+  initialUser: z4.object({
+    id: z4.string().uuid(),
+    displayName: z4.string()
+  }),
+  initialToken: tokenCreatedSchema.nullable()
+});
+var setupStatusSchema = z4.object({
+  needsSetup: z4.boolean()
+});
+var setupBodySchema = z4.object({
+  teamName: z4.string().min(1).max(120),
+  displayName: z4.string().min(1).max(120).default("Admin")
+});
+var setupResultSchema = z4.object({
+  team: teamSummarySchema,
+  user: z4.object({ id: z4.string().uuid(), displayName: z4.string() }),
+  tokenString: tokenStringSchema,
+  scopes: z4.array(tokenScopeSchema)
+});
+var teamLlmSettingsSchema = z4.object({
+  keyConfigured: z4.boolean(),
+  keyHint: z4.string().nullable(),
+  lightModel: z4.string(),
+  heavyModel: z4.string()
+});
+var teamLlmUpdateSchema = z4.object({
+  openrouterApiKey: z4.string().max(400).nullable().optional(),
+  lightModel: z4.string().min(1).max(200).optional(),
+  heavyModel: z4.string().min(1).max(200).optional()
+});
+var wcvpImportStatusSchema = z4.enum([
+  "queued",
+  "downloading",
+  "importing",
+  "completed",
+  "failed",
+  "cancelled"
+]);
+var wcvpImportRunSchema = z4.object({
+  id: z4.string().uuid(),
+  version: z4.string(),
+  sourceUrl: z4.string(),
+  status: wcvpImportStatusSchema,
+  forceOverwrite: z4.boolean(),
+  bytesDownloaded: z4.number().int().nonnegative(),
+  totalBytes: z4.number().int().nonnegative().nullable(),
+  insertedCount: z4.number().int().nonnegative(),
+  recordCount: z4.number().int().nonnegative().nullable(),
+  message: z4.string().nullable(),
+  createdAt: z4.string().datetime(),
+  startedAt: z4.string().datetime().nullable(),
+  completedAt: z4.string().datetime().nullable()
+});
+var wcvpImportCreateBodySchema = z4.object({
+  version: z4.string().min(1).max(120),
+  /** Defaults to the Kew SFTP URL when omitted, so the admin doesn't have
+   * to remember it for routine v13/v14 imports. */
+  url: z4.string().url().optional(),
+  force: z4.boolean().optional()
+});
+var adminHealthErrorSchema = z4.object({
+  id: z4.string().uuid(),
+  action: z4.string(),
+  entityType: z4.string(),
+  entityId: z4.string().nullable(),
+  timestamp: z4.string().datetime(),
+  metadata: z4.unknown().nullable()
+});
+var adminHealthSchema = z4.object({
+  queueDepth: z4.object({
+    waiting: z4.number().int().nonnegative(),
+    active: z4.number().int().nonnegative(),
+    delayed: z4.number().int().nonnegative(),
+    completed: z4.number().int().nonnegative(),
+    failed: z4.number().int().nonnegative(),
+    paused: z4.number().int().nonnegative()
+  }),
+  workerCount: z4.number().int().nonnegative(),
+  lastErrors: z4.array(adminHealthErrorSchema),
+  rateLimitBudget: z4.object({
+    max: z4.number().int().nonnegative(),
+    timeWindowSeconds: z4.number().int().nonnegative()
+  }),
+  snapshotVersion: z4.string().nullable(),
+  snapshotImportedAt: z4.string().datetime().nullable(),
+  /**
+   * Number of cached accepted-name mappings (L0.5 match-history rows) for the
+   * caller's team — the size of the team accepted-name cache.
+   */
+  teamHistorySize: z4.number().int().nonnegative(),
+  /**
+   * Overall (all-teams) tally of which cascade layer produced the winning
+   * candidate, across every matched query. `layer` is the raw attempt layer
+   * (`L1`…`L7`, `L0.5`, `OVERRIDE`); `count` is the number of matched queries
+   * that layer resolved. Descending by count.
+   */
+  layerUsage: z4.array(
+    z4.object({
+      layer: z4.string(),
+      count: z4.number().int().nonnegative()
+    })
+  ),
+  /**
+   * Per external provider (GBIF / TNRS / GNverifier / Pl@ntNet / OpenRouter)
+   * call stats across all teams, from `match_attempts`. Local/in-process
+   * providers (wcvp-local / gnparser / team-history / cascade) are excluded.
+   * Lets the health page surface each external source's usage, hit/miss/error
+   * breakdown, latency, and recency — so a misbehaving provider is visible.
+   */
+  externalProviders: z4.array(
+    z4.object({
+      provider: z4.string(),
+      total: z4.number().int().nonnegative(),
+      hits: z4.number().int().nonnegative(),
+      misses: z4.number().int().nonnegative(),
+      errors: z4.number().int().nonnegative(),
+      avgDurationMs: z4.number().int().nonnegative(),
+      lastUsedAt: z4.string().datetime().nullable()
+    })
+  )
+});
+
+// ../shared/src/normalize.ts
+var NULL_SENTINELS = /* @__PURE__ */ new Set(["", "na", "n/a", "null", "-", "\u2014", "unknown", "undet", "undet."]);
+var QUALIFIER_PATTERNS = [
+  { pattern: /\bcf\.?\b/i, qualifier: "cf" },
+  { pattern: /\baff\.?\b/i, qualifier: "aff" },
+  { pattern: /\bs\.\s*l\.?\b/i, qualifier: "sensu_lato" },
+  { pattern: /\bs\.\s*str\.?\b/i, qualifier: "sensu_stricto" },
+  { pattern: /\bs\.\s*s\.?\b/i, qualifier: "sensu_stricto" },
+  { pattern: /\bagg\.?\b/i, qualifier: "aggregate" },
+  { pattern: /\bcomplex\b/i, qualifier: "complex" },
+  { pattern: /\bspp\.?\b/i, qualifier: "spp" },
+  { pattern: /\bsp\.?(?=\s|$)/i, qualifier: "sp" },
+  { pattern: /\bindet\.?\b/i, qualifier: "indet" }
+];
+var CULTIVAR_PATTERN = /'[^']+'|"[^"]+"/;
+var HYBRID_FORMULA = /\w+\s+[×x]\s+[A-ZÀ-Ý]/;
+function normalizeInput(raw) {
+  const original = (raw ?? "").toString();
+  const warnings = [];
+  let s = original.normalize("NFC").trim();
+  if (/\s{2,}/.test(s)) warnings.push("multiple_spaces");
+  s = s.replace(/\s+/g, " ");
+  if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
+    s = s.slice(1, -1).trim();
+  }
+  if (NULL_SENTINELS.has(s.toLowerCase())) {
+    return {
+      raw: original,
+      normalized: null,
+      qualifier: "none",
+      isCultivar: false,
+      isHybridFormula: false,
+      isVernacularSuspected: false,
+      warnings
+    };
+  }
+  if (s.endsWith(".") || /[,;]$/.test(s)) warnings.push("trailing_punctuation");
+  if (s.includes("?")) warnings.push("question_mark");
+  s = s.replace(/(?<=\w)\s+[xX]\s+(?=\w)/g, " \xD7 ");
+  let qualifier = "none";
+  for (const { pattern, qualifier: q } of QUALIFIER_PATTERNS) {
+    if (pattern.test(s)) {
+      qualifier = q;
+      break;
+    }
+  }
+  const isCultivar = CULTIVAR_PATTERN.test(s);
+  if (isCultivar) qualifier = "cultivar";
+  const isHybridFormula = HYBRID_FORMULA.test(s);
+  if (isHybridFormula && qualifier === "none") qualifier = "hybrid_formula";
+  const isVernacularSuspected = detectVernacular(s);
+  return {
+    raw: original,
+    normalized: s,
+    qualifier,
+    isCultivar,
+    isHybridFormula,
+    isVernacularSuspected,
+    warnings
+  };
+}
+var VERNACULAR_KEYWORDS = /\b(tree|flower|grass|weed|herb|fern|moss|leaf|lily|rose|oak)\b/i;
+function detectVernacular(s) {
+  if (!s) return false;
+  if (VERNACULAR_KEYWORDS.test(s)) return true;
+  const firstChar = s[0];
+  if (!firstChar) return false;
+  if (firstChar !== firstChar.toUpperCase()) return true;
+  return false;
+}
+
+// ../shared/src/id-type.ts
+var IPNI_LSID_URN_RE = /^urn:lsid:ipni\.org:names:\d+-\d+$/i;
+var IPNI_LSID_BARE_RE = /^\d+-\d+$/;
+var WFO_RE = /^wfo-\d{10}$/i;
+var INTEGER_RE = /^\d{4,}$/;
+var COL_RE = /^[A-Z0-9]{5,6}$/;
+var URN_RE = /^urn:/i;
+var URL_RE = /^https?:\/\//i;
+function detectIdType(value) {
+  const v = value.trim();
+  if (!v) return "unknown";
+  if (IPNI_LSID_URN_RE.test(v)) return "ipni-lsid-urn";
+  if (IPNI_LSID_BARE_RE.test(v)) return "ipni-lsid";
+  if (WFO_RE.test(v)) return "wfo-name-id";
+  if (URN_RE.test(v)) return "urn";
+  if (URL_RE.test(v)) return "url";
+  if (INTEGER_RE.test(v)) return "gbif-taxon-key";
+  if (COL_RE.test(v)) return "col-name-id";
+  if (v.length <= 3) return "short-string";
+  return "unknown";
+}
+function detectIdTypeDistribution(samples, opts) {
+  const counts = {
+    "ipni-lsid": 0,
+    "ipni-lsid-urn": 0,
+    "wcvp-taxon-id": 0,
+    "gbif-taxon-key": 0,
+    "wfo-name-id": 0,
+    "col-name-id": 0,
+    urn: 0,
+    url: 0,
+    "short-string": 0,
+    unknown: 0
+  };
+  const typed = [];
+  for (const s of samples) {
+    const t = detectIdType(s.value);
+    counts[t]++;
+    typed.push({ rowIndex: s.rowIndex, value: s.value, type: t });
+  }
+  let dominant = null;
+  let max = 0;
+  for (const [t, n] of Object.entries(counts)) {
+    if (n > max) {
+      max = n;
+      dominant = t;
+    }
+  }
+  const sampleSize = samples.length;
+  const dominantConfidence = sampleSize > 0 && dominant ? counts[dominant] / sampleSize : 0;
+  const minorityExamples = typed.filter((t) => t.type !== dominant).slice(0, opts?.minorityExamples ?? 5);
+  return { sampleSize, counts, dominant, dominantConfidence, minorityExamples };
+}
+
+// ../shared/src/column-map.ts
+import { z as z5 } from "zod";
+var columnMappingSchema = z5.object({
+  nameColumn: z5.string().nullable(),
+  idColumn: z5.string().nullable(),
+  familyColumn: z5.string().nullable(),
+  genusColumn: z5.string().nullable(),
+  rankColumn: z5.string().nullable(),
+  authorColumn: z5.string().nullable()
+});
+var detectColumnsBodySchema = z5.object({
+  headers: z5.array(z5.string().min(1)).min(1).max(200)
+});
+var detectColumnsResponseSchema = z5.object({
+  mapping: columnMappingSchema,
+  usedLlm: z5.boolean()
+});
+
+// src/api-client.ts
+import { promises as fs } from "fs";
+import { basename } from "path";
+import { FormData, fetch, request } from "undici";
+var ApiError = class extends Error {
+  constructor(message, status, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+  }
+  status;
+  body;
+};
+async function call(creds, path, init) {
+  const url = new URL(path, creds.server).toString();
+  const hasBody = init?.body !== void 0;
+  const res = await request(url, {
+    method: init?.method ?? "GET",
+    headers: {
+      authorization: `Bearer ${creds.token}`,
+      ...hasBody ? { "content-type": "application/json" } : {}
+    },
+    ...hasBody ? { body: JSON.stringify(init.body) } : {}
+  });
+  const text = await res.body.text();
+  const parsed = text ? safeJson(text) : null;
+  if (res.statusCode >= 400) {
+    throw new ApiError(`HTTP ${res.statusCode}`, res.statusCode, parsed ?? text);
+  }
+  return parsed;
+}
+function safeJson(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+}
+var apiClient = {
+  me: (c) => call(c, "/v1/me"),
+  listJobs: (c) => call(c, "/v1/jobs"),
+  getJob: (c, id) => call(c, `/v1/jobs/${id}`),
+  downloadColumns: (c, id) => call(c, `/v1/jobs/${id}/download/columns`),
+  pauseJob: (c, id) => call(c, `/v1/jobs/${id}/pause`, { method: "POST" }),
+  resumeJob: (c, id) => call(c, `/v1/jobs/${id}/resume`, { method: "POST" }),
+  cancelJob: (c, id) => call(c, `/v1/jobs/${id}/cancel`, { method: "POST" }),
+  async submitJob(creds, filePath, config, name) {
+    const buf = await fs.readFile(filePath);
+    const fd = new FormData();
+    const lower = filePath.toLowerCase();
+    const mime = lower.endsWith(".json") ? "application/json" : "text/csv";
+    fd.set("file", new Blob([buf], { type: mime }), basename(filePath));
+    fd.set("config", JSON.stringify(config));
+    if (name && name.trim()) fd.set("name", name.trim());
+    const url = new URL("/v1/jobs", creds.server).toString();
+    const res = await fetch(url, {
+      method: "POST",
+      body: fd,
+      headers: { authorization: `Bearer ${creds.token}` }
+    });
+    const text = await res.text();
+    const parsed = text ? safeJson(text) : null;
+    if (!res.ok) throw new ApiError(`HTTP ${res.status}`, res.status, parsed ?? text);
+    return parsed;
+  },
+  async downloadJob(creds, id, opts) {
+    const params = new URLSearchParams({ format: opts.format });
+    if (opts.confirmedOnly) params.set("confirmedOnly", "true");
+    if (opts.bundle) params.set("bundle", "true");
+    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();
+    const res = await fetch(url, { headers: { authorization: `Bearer ${creds.token}` } });
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new ApiError(`HTTP ${res.status}`, res.status, text);
+    }
+    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 filename = m?.[1] ?? `planttaxomatcher_${id}.${ext}`;
+    const buf = Buffer.from(await res.arrayBuffer());
+    return { filename, body: buf };
+  },
+  async *streamJob(creds, id) {
+    const url = new URL(`/v1/jobs/${id}/stream`, creds.server).toString();
+    const res = await fetch(url, { headers: { authorization: `Bearer ${creds.token}` } });
+    if (!res.ok || !res.body) {
+      const text = await res.text().catch(() => "");
+      throw new ApiError(`HTTP ${res.status}`, res.status, text);
+    }
+    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 {
+        }
+      }
+    }
+  }
+};
+
+// src/config.ts
+import { promises as fs2 } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var CONFIG_DIR = join(homedir(), ".config", "planttaxomatcher");
+var CONFIG_FILE = join(CONFIG_DIR, "credentials");
+async function readCredentials() {
+  try {
+    const raw = await fs2.readFile(CONFIG_FILE, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+async function writeCredentials(creds) {
+  await fs2.mkdir(CONFIG_DIR, { recursive: true, mode: 448 });
+  await fs2.writeFile(CONFIG_FILE, JSON.stringify(creds, null, 2), { mode: 384 });
+}
+async function clearCredentials() {
+  try {
+    await fs2.unlink(CONFIG_FILE);
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+  }
+}
+async function requireCredentials() {
+  const creds = await readCredentials();
+  if (!creds) {
+    throw new Error("Not logged in. Run: planttaxomatcher login --token <t> --server <url>");
+  }
+  return creds;
+}
+
+// src/dry-run.ts
+import { promises as fs3 } from "fs";
+import { Readable } from "stream";
+import { parse as parseCsvStream } from "csv-parse";
+import kleur from "kleur";
+async function readSample(file, sampleLimit) {
+  const lower = file.toLowerCase();
+  if (lower.endsWith(".json")) {
+    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 = [];
+    for (const v of arr) {
+      if (out2.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);
+      }
+    }
+    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();
+  }
+  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] : ",";
+}
+async function buildDryRunReport(file, opts) {
+  const sampleLimit = opts.sampleLimit ?? 1e3;
+  const previewRows = opts.previewRows ?? 10;
+  const rows = await readSample(file, sampleLimit);
+  if (rows.length === 0) {
+    return {
+      rowsRead: 0,
+      nullNameCount: 0,
+      qualifierFlagCount: 0,
+      sampleRows: [],
+      idTypeDetection: null
+    };
+  }
+  if (!(opts.nameColumn in rows[0])) {
+    throw new Error(`name column "${opts.nameColumn}" not present in file header`);
+  }
+  let nullNameCount = 0;
+  let qualifierFlagCount = 0;
+  const sampleRows = [];
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i];
+    const input = row[opts.nameColumn] ?? null;
+    const parsed = normalizeInput(input);
+    if (!parsed.normalized) nullNameCount++;
+    const flags = [];
+    if (parsed.qualifier && parsed.qualifier !== "none") flags.push(`qualifier:${parsed.qualifier}`);
+    if (parsed.isCultivar) flags.push("cultivar");
+    if (parsed.isHybridFormula) flags.push("hybrid-formula");
+    if (parsed.isVernacularSuspected) flags.push("vernacular?");
+    if (flags.length > 0) qualifierFlagCount++;
+    if (sampleRows.length < previewRows) {
+      sampleRows.push({
+        rowIndex: i,
+        input,
+        normalized: parsed.normalized,
+        flags
+      });
+    }
+  }
+  let idTypeDetection = null;
+  if (opts.idColumn && rows.length > 0 && opts.idColumn in rows[0]) {
+    const samples = rows.map((r, i) => ({ rowIndex: i, value: r[opts.idColumn] ?? "" })).filter((s) => s.value.trim().length > 0);
+    if (samples.length > 0) {
+      idTypeDetection = detectIdTypeDistribution(samples, { minorityExamples: 5 });
+    }
+  }
+  return {
+    rowsRead: rows.length,
+    nullNameCount,
+    qualifierFlagCount,
+    sampleRows,
+    idTypeDetection
+  };
+}
+function printDryRunReport(report) {
+  console.log();
+  console.log(kleur.bold("Dry-run preview"));
+  console.log(
+    `  Read ${kleur.cyan(report.rowsRead)} rows \xB7 ${kleur.yellow(report.nullNameCount)} with no usable name \xB7 ${kleur.yellow(report.qualifierFlagCount)} with qualifier flags`
+  );
+  if (report.idTypeDetection) {
+    const d = report.idTypeDetection;
+    const pct = Math.round(d.dominantConfidence * 100);
+    console.log(
+      `  ID-column detection: ${kleur.green(d.dominant ?? "\u2014")} (${pct}% of ${d.sampleSize} sampled)`
+    );
+    if (d.minorityExamples.length > 0) {
+      console.log(`  Minority examples:`);
+      for (const m of d.minorityExamples) {
+        console.log(
+          `    row ${m.rowIndex + 1}: ${kleur.gray(m.value)} \u2192 ${kleur.dim(m.type)}`
+        );
+      }
+    }
+  }
+  console.log();
+  console.log(kleur.bold("First rows after normalization:"));
+  console.log(
+    `  ${"#".padStart(4)}  ${"input".padEnd(36)}  ${"normalized".padEnd(36)}  flags`
+  );
+  for (const r of report.sampleRows) {
+    const idx = String(r.rowIndex + 1).padStart(4);
+    const inp = trunc(r.input ?? "\u2205", 36).padEnd(36);
+    const norm = trunc(r.normalized ?? "\u2205", 36).padEnd(36);
+    console.log(`  ${idx}  ${inp}  ${norm}  ${r.flags.join(" ") || ""}`);
+  }
+  console.log();
+}
+function trunc(s, n) {
+  if (s.length <= n) return s;
+  return s.slice(0, n - 1) + "\u2026";
+}
+
+// src/index.ts
+var program = new Command();
+program.name("planttaxomatcher").description("PlantTaxoMatcher CLI").version("0.1.0");
+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."
+).option(
+  "--token-stdin",
+  "Read the token from stdin instead of argv (e.g. `cat token.txt | planttaxomatcher login --token-stdin`).",
+  false
+).option("--server <url>", "API server base URL", "http://localhost:4000").option(
+  "--insecure",
+  "Allow sending the token over cleartext http to a non-loopback server (NOT recommended).",
+  false
+).action(
+  async (opts) => {
+    assertServerTransport(opts.server, !!opts.insecure);
+    const token = await resolveLoginToken(opts);
+    if (!tokenStringSchema.safeParse(token).success) {
+      throw new Error("malformed token \u2014 expected ptm_<12 chars>_<32 chars>");
+    }
+    await writeCredentials({ token, server: opts.server });
+    console.log(kleur2.green("\u2713"), `Logged in to ${opts.server}`);
+  }
+);
+program.command("logout").description("Clear saved credentials").action(async () => {
+  await clearCredentials();
+  console.log(kleur2.green("\u2713"), "Logged out");
+});
+program.command("whoami").description("Show current user").action(async () => {
+  const creds = await requireCredentials();
+  const me = await apiClient.me(creds);
+  console.log(`${me.displayName}  team=${me.teamId}  scopes=${me.scopes.join(",")}`);
+});
+program.command("list").description("List recent jobs").action(async () => {
+  const creds = await requireCredentials();
+  const jobs = await apiClient.listJobs(creds);
+  if (jobs.length === 0) {
+    console.log(kleur2.gray("No jobs."));
+    return;
+  }
+  for (const j of jobs) {
+    console.log(
+      `${j.id}  ${j.status.padEnd(10)}  ${String(j.matchedRows).padStart(6)}/${String(j.totalRows).padStart(6)} matched`
+    );
+  }
+});
+program.command("status <jobId>").description("Show job status snapshot").action(async (jobId) => {
+  const creds = await requireCredentials();
+  const job = await apiClient.getJob(creds, jobId);
+  console.log(JSON.stringify(job, null, 2));
+});
+program.command("submit <files...>").description(
+  'Submit one or more CSV/JSON files for matching. Accepts shell-expanded paths or quoted glob patterns (e.g. "data/*.csv"). Each file becomes its own job; the file name (without extension) is used as the job name.'
+).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(
+  "--keep-infraspecific",
+  "Keep infraspecific accepted taxa (varieties, subspecies, forms) instead of collapsing them up to the species",
+  false
+).option("--allow-llm", "Allow Layer 7 LLM cascade (breaks ties between competing matches)", false).option("--llm-cap-cents <cents>", "Max LLM spend in cents", "500").option("--referential <version>", "WCVP snapshot version to match against (default: latest)").option("--no-watch", "Do not stream progress after submit").option(
+  "--dry-run",
+  "Preview locally (normalize first rows + detect ID type) and confirm before uploading",
+  false
+).option(
+  "--dry-run-rows <n>",
+  "Number of rows to show in the dry-run preview table (default 10)",
+  "10"
+).action(async (files, opts) => {
+  const creds = await requireCredentials();
+  const inputs = await expandInputs(files);
+  if (inputs.length === 0) throw new Error("no input files");
+  if (opts.name && inputs.length > 1) {
+    console.log(
+      kleur2.yellow("!"),
+      "--name ignored for multi-file submit; using each file name as the job name"
+    );
+  }
+  if (inputs.length > 1) {
+    console.log(kleur2.cyan("\u2192"), `${inputs.length} files matched:`);
+    for (const f of inputs) console.log(kleur2.gray(`    ${f}`));
+  }
+  if (opts.dryRun) {
+    const idColumn = opts.idColumn ? String(opts.idColumn) : null;
+    const previewRows = Number(opts.dryRunRows ?? 10);
+    for (const file of inputs) {
+      if (inputs.length > 1) console.log(kleur2.bold(`
+${file}`));
+      const report = await buildDryRunReport(file, {
+        nameColumn: String(opts.nameColumn),
+        idColumn,
+        previewRows: Number.isFinite(previewRows) ? previewRows : 10,
+        sampleLimit: 1e3
+      });
+      printDryRunReport(report);
+    }
+    const proceed = await confirm({
+      message: inputs.length > 1 ? `Proceed with upload of ${inputs.length} files?` : "Proceed with upload?",
+      default: true
+    });
+    if (!proceed) {
+      console.log(kleur2.gray("Aborted."));
+      return;
+    }
+  }
+  const config = {
+    nameColumn: String(opts.nameColumn),
+    idColumn: opts.idColumn ? String(opts.idColumn) : null,
+    familyColumn: opts.familyColumn ? String(opts.familyColumn) : null,
+    genusColumn: opts.genusColumn ? String(opts.genusColumn) : null,
+    rankColumn: opts.rankColumn ? String(opts.rankColumn) : null,
+    authorColumn: opts.authorColumn ? String(opts.authorColumn) : null,
+    authorMode: String(opts.authorMode ?? "prefer"),
+    matchAuthors: true,
+    parallelism: Number(opts.parallel ?? 4),
+    allowFuzzy: true,
+    allowLlm: !!opts.allowLlm,
+    llmCostCapCents: Number(opts.llmCapCents ?? 500),
+    reviewMode: String(opts.reviewMode ?? "recommended"),
+    // UI/CLI opt-in inverts the config flag: by default we collapse an
+    // infraspecific accepted taxon up to its species.
+    speciesLevelAcceptedOnly: !opts.keepInfraspecific,
+    exportConfirmedOnly: false,
+    forceReviewFamilies: [],
+    ...opts.referential ? { referentialVersion: String(opts.referential) } : {}
+  };
+  const submitted = [];
+  for (const file of inputs) {
+    const jobName = inputs.length === 1 && opts.name ? String(opts.name) : parsePath(file).name;
+    console.log(kleur2.cyan("\u2192"), `Uploading ${file} \u2026`);
+    const job = await apiClient.submitJob(creds, file, config, jobName || null);
+    console.log(kleur2.green("\u2713"), `Job created: ${job.id}  ${kleur2.gray(jobName)}`);
+    console.log(`  rows=${job.totalRows}  uniqueQueries=${job.uniqueQueries}`);
+    submitted.push({ id: job.id, file });
+  }
+  if (opts.watch === false) return;
+  for (const s of submitted) {
+    if (submitted.length > 1) console.log(kleur2.bold(`
+[${s.file}] ${s.id}`));
+    await streamJob(creds, s.id);
+  }
+});
+program.command("watch <jobId>").description("Stream NDJSON progress for a job").action(async (jobId) => {
+  const creds = await requireCredentials();
+  await streamJob(creds, jobId);
+});
+program.command("pause <jobId>").description("Pause a running job (worker stops between match queries)").action(async (jobId) => {
+  const creds = await requireCredentials();
+  const job = await apiClient.pauseJob(creds, jobId);
+  console.log(kleur2.green("\u2713"), `paused: ${job.id} (status=${job.status})`);
+});
+program.command("resume <jobId>").description("Resume a paused job (re-enqueues the match stage)").action(async (jobId) => {
+  const creds = await requireCredentials();
+  const job = await apiClient.resumeJob(creds, jobId);
+  console.log(kleur2.green("\u2713"), `resumed: ${job.id} (status=${job.status})`);
+});
+program.command("cancel <jobId>").description("Cancel a job. Already-matched rows are kept; pending queries stop.").action(async (jobId) => {
+  const creds = await requireCredentials();
+  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(
+  "--columns <list>",
+  "comma-separated result/upload column keys to KEEP (default: all). See --list-columns"
+).option(
+  "--wcvp-extra <list>",
+  "comma-separated extra WCVP fields to append as wcvp_<key> columns (e.g. ipni_id,powo_id). See --list-columns"
+).option("--list-columns", "print the columns available for this job and exit", false).option("--output <path>", "write to this path; default is the server-provided filename in CWD").action(async (jobId, opts) => {
+  const creds = await requireCredentials();
+  if (opts.listColumns) {
+    const cat = await apiClient.downloadColumns(creds, jobId);
+    console.log(kleur2.bold("Result columns (--columns):"));
+    for (const r of cat.result) console.log(`  ${r.key}  ${kleur2.gray(`(${r.group})`)}`);
+    if (cat.original.length > 0) {
+      console.log(kleur2.bold("\nYour upload columns (--columns):"));
+      for (const k of cat.original) console.log(`  ${k}`);
+    }
+    console.log(kleur2.bold("\nWCVP extra fields (--wcvp-extra):"));
+    for (const f of cat.wcvpExtra) console.log(`  ${f.key}  ${kleur2.gray(`(${f.group})`)}`);
+    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)})`);
+  }
+  const confirmedOnly = !!opts.confirmedOnly;
+  const bundle = !!opts.bundle;
+  const { filename, body } = await apiClient.downloadJob(creds, jobId, {
+    format,
+    confirmedOnly,
+    bundle,
+    ...opts.columns ? { columns: String(opts.columns) } : {},
+    ...opts.wcvpExtra ? { wcvpExtra: String(opts.wcvpExtra) } : {}
+  });
+  const outPath = opts.output ?? filename;
+  const { writeFile } = await import("fs/promises");
+  await writeFile(outPath, body);
+  console.log(kleur2.green("\u2713"), `wrote ${body.length} bytes to ${outPath}`);
+});
+program.parseAsync(process.argv).catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(kleur2.red("error:"), msg);
+  process.exit(1);
+});
+function assertServerTransport(server, insecure) {
+  let u;
+  try {
+    u = new URL(server);
+  } catch {
+    throw new Error(`invalid --server URL: ${server}`);
+  }
+  if (u.protocol === "https:") return;
+  if (u.protocol !== "http:") {
+    throw new Error(`--server must use http or https (got ${u.protocol})`);
+  }
+  const host = u.hostname;
+  const isLoopback = host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]" || host.endsWith(".localhost");
+  if (!isLoopback && !insecure) {
+    throw new Error(
+      `refusing to send a token in cleartext to ${u.host}. Use an https URL, or pass --insecure to override (NOT recommended).`
+    );
+  }
+}
+async function readStdinLine() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+async function resolveLoginToken(opts) {
+  if (opts.tokenStdin) {
+    const t = await readStdinLine();
+    if (!t) throw new Error("--token-stdin was set but stdin was empty");
+    return t;
+  }
+  if (opts.token) return opts.token.trim();
+  const env = process.env.PLANTTAXOMATCHER_TOKEN;
+  if (env && env.trim()) return env.trim();
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      "no token provided. Pass --token-stdin, set PLANTTAXOMATCHER_TOKEN, or run interactively."
+    );
+  }
+  const entered = await password({ message: "Personal token (ptm_...)", mask: true });
+  return entered.trim();
+}
+var GLOB_MAGIC = /[*?[\]{}!()]/;
+async function expandInputs(patterns) {
+  const out = /* @__PURE__ */ new Set();
+  for (const p of patterns) {
+    if (GLOB_MAGIC.test(p)) {
+      let matched = false;
+      for await (const m of fs4.glob(p)) {
+        out.add(m);
+        matched = true;
+      }
+      if (!matched) throw new Error(`no files matched: ${p}`);
+    } else {
+      await fs4.access(p).catch(() => {
+        throw new Error(`file not found: ${p}`);
+      });
+      out.add(p);
+    }
+  }
+  return [...out].sort();
+}
+async function streamJob(creds, jobId) {
+  console.log(kleur2.cyan("\u2192"), `Streaming progress for ${jobId} \u2026`);
+  for await (const evt of apiClient.streamJob(creds, jobId)) {
+    const t = String(evt.type ?? "");
+    if (t === "heartbeat") continue;
+    if (t === "status") {
+      console.log(kleur2.gray("\u2022"), evt.status);
+    } else if (t === "progress") {
+      const p = evt.processedQueries ?? evt.processedRows ?? 0;
+      const total = evt.totalQueries ?? evt.totalRows ?? 0;
+      process.stdout.write(`\r  progress: ${p}/${total}        `);
+    } else if (t === "completed") {
+      process.stdout.write("\n");
+      console.log(kleur2.green("\u2713"), "completed");
+      return;
+    } else if (t === "error") {
+      process.stdout.write("\n");
+      console.error(kleur2.red("error:"), evt.message);
+      return;
+    }
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "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"
+  }
+}