pm-csv 2026.6.2 → 2026.6.4

package/dist/index.js

@@ -25,7 +25,10 @@ class CommandError extends Error {
         this.exitCode = exitCode;
     }
 }
-// Columns accepted on import (order independent — driven by header row)
+// Columns accepted on import (order independent — driven by header row).
+// The relational/planning fields (parent, assignee, sprint, release,
+// blocked_by) all map to real `pm create`/`pm update` flags verified against
+// the installed CLI (--parent, --assignee, --sprint, --release, --blocked-by).
 const IMPORT_COLUMNS = [
     "title",
     "type",
@@ -34,6 +37,11 @@ const IMPORT_COLUMNS = [
     "tags",
     "deadline",
     "body",
+    "parent",
+    "assignee",
+    "sprint",
+    "release",
+    "blocked_by",
 ];
 // Columns written on export (fixed order)
 const EXPORT_COLUMNS = [
@@ -45,9 +53,26 @@ const EXPORT_COLUMNS = [
     "tags",
     "deadline",
     "body",
+    "parent",
+    "assignee",
+    "sprint",
+    "release",
+    "blocked_by",
+    "csv_source",
     "created_at",
     "updated_at",
 ];
+/** Recognized status values for the `csv validate` report. */
+const KNOWN_STATUSES = new Set([
+    "open", "todo", "new",
+    "in_progress", "wip", "in progress", "doing",
+    "blocked", "on_hold", "on hold",
+    "closed", "done", "complete", "completed",
+    "canceled", "cancelled",
+    "draft",
+]);
+/** Supported file encodings for `--encoding` on import. */
+const SUPPORTED_ENCODINGS = ["utf-8", "utf8", "utf16le", "latin1"];
 // ---------------------------------------------------------------------------
 // CSV parser — no external dependencies
 // ---------------------------------------------------------------------------
@@ -123,6 +148,14 @@ function parseCSV(text, delimiter = ",") {
     }
     return rows;
 }
+/**
+ * Strip a leading UTF-8 BOM (U+FEFF) if present. Files exported by Excel and
+ * many Windows tools start with a BOM; without removing it the first header
+ * name silently becomes "title" and the required-column check fails.
+ */
+function stripBOM(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
 /**
  * Serialize a single field value for CSV output.
  * Wraps in double-quotes when the value contains the delimiter, quotes, or newlines.
@@ -140,10 +173,14 @@ function serializeField(value, delimiter) {
 /**
  * Serialize a full array of rows into a CSV string.
  */
-function serializeCSV(rows, delimiter) {
+function serializeCSV(rows, delimiterOrOpts) {
+    const opts = typeof delimiterOrOpts === "string"
+        ? { delimiter: delimiterOrOpts }
+        : delimiterOrOpts;
+    const eol = opts.eol ?? "\n";
     return rows
-        .map((row) => row.map((f) => serializeField(f, delimiter)).join(delimiter))
-        .join("\n");
+        .map((row) => row.map((f) => serializeField(f, opts.delimiter)).join(opts.delimiter))
+        .join(eol);
 }
 // ---------------------------------------------------------------------------
 // Helpers
@@ -160,6 +197,91 @@ function readBoolOption(options, ...keys) {
     }
     return false;
 }
+/**
+ * Resolve a user-supplied delimiter, accepting friendly aliases so TSV is easy:
+ *   --delimiter tab   --delimiter "\t"   --delimiter ";"
+ * A literal backslash-t is interpreted as a tab.
+ */
+function resolveDelimiter(raw) {
+    if (raw === undefined || raw === "")
+        return ",";
+    const lower = raw.toLowerCase();
+    if (lower === "tab" || lower === "\\t" || lower === "tsv")
+        return "\t";
+    if (lower === "comma")
+        return ",";
+    if (lower === "semicolon")
+        return ";";
+    if (lower === "pipe")
+        return "|";
+    return raw;
+}
+/**
+ * Provenance tag prefix used for idempotent upsert. When the importer is told
+ * to key on a column, the created item is tagged `csv-key:<value>` so a later
+ * re-import can find and update the same item instead of duplicating it.
+ */
+const KEY_TAG_PREFIX = "csv-key:";
+// Provenance tag prefix written when `--source <label>` is given. The CLI's
+// registerItemFields registers the `csv_source` schema field but (as of
+// pm 2026.5.31) does not expose a `pm create --csv_source` setter, so we
+// persist the label as a queryable tag. Stripped from exports like csv-key.
+const SOURCE_TAG_PREFIX = "csv-source:";
+const PM_LIST_MAX_BUFFER = 16 * 1024 * 1024;
+/**
+ * Normalize a dedup key value for stable matching. pm lower-cases tags on
+ * storage, so a `csv-key:` tag written from "Fix Bug" comes back as
+ * "fix bug"; we therefore fold the key to lower-case on BOTH write and lookup
+ * so re-imports match (and thus update) instead of duplicating.
+ */
+function normalizeKeyValue(value) {
+    return value.trim().toLowerCase();
+}
+function encodeKeyTagValue(value) {
+    return encodeURIComponent(value);
+}
+function decodeKeyTagValue(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Parse a `--map csvHeader=field` spec (repeatable / comma-joined) into a
+ * lookup from a normalized CSV header name to the canonical pm field name.
+ * Example: `--map "Summary=title,Owner=tags"`.
+ */
+function parseFieldMap(spec) {
+    const map = {};
+    if (spec === undefined)
+        return map;
+    const parts = (Array.isArray(spec) ? spec : [spec]).flatMap((s) => s.split(","));
+    for (const part of parts) {
+        const trimmed = part.trim();
+        if (!trimmed)
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq < 0) {
+            throw new CommandError(`Invalid --map entry "${trimmed}"; expected csvHeader=field`, EXIT_CODE.USAGE);
+        }
+        const from = trimmed.slice(0, eq).trim().toLowerCase();
+        const to = trimmed.slice(eq + 1).trim().toLowerCase();
+        if (!from || !to) {
+            throw new CommandError(`Invalid --map entry "${trimmed}"; expected csvHeader=field`, EXIT_CODE.USAGE);
+        }
+        map[from] = to;
+    }
+    return map;
+}
+/**
+ * Apply a field map to a list of header names, producing the effective
+ * (canonical) header used for column lookup.
+ */
+function applyFieldMap(headers, fieldMap) {
+    return headers.map((h) => fieldMap[h] ?? h);
+}
 /**
  * Map an arbitrary status string (from the CSV) to a valid SDK status.
  * Falls back to "open".
@@ -204,12 +326,27 @@ function stringifyTags(tags) {
         return "";
     return tags.join(",");
 }
+/**
+ * Validate and normalize a user-supplied `--encoding` value to a Node-supported
+ * BufferEncoding. Accepts utf-8/utf8, utf16le, latin1. Throws USAGE otherwise.
+ */
+function resolveEncoding(raw) {
+    if (raw === undefined || raw === "")
+        return "utf-8";
+    const lower = raw.trim().toLowerCase();
+    if (SUPPORTED_ENCODINGS.includes(lower)) {
+        return lower;
+    }
+    throw new CommandError(`Unknown --encoding '${raw}'. Supported: ${SUPPORTED_ENCODINGS.join(", ")}`, EXIT_CODE.USAGE);
+}
 /**
  * Read rows from a CSV file, returning header and data rows separately.
- * Skips fully-empty rows.
+ * Skips fully-empty rows. Decodes with the given encoding (default utf-8).
  */
-function readCSVFile(filePath, delimiter) {
-    const text = readFileSync(filePath, "utf-8");
+function readCSVFile(filePath, delimiter, encoding = "utf-8") {
+    // Node's BufferEncoding spells utf-8 as "utf8"; normalize.
+    const bufEnc = encoding === "utf-8" ? "utf8" : encoding;
+    const text = stripBOM(readFileSync(filePath, bufEnc));
     const rows = parseCSV(text, delimiter).filter((r) => r.some((f) => f.trim() !== ""));
     if (rows.length === 0) {
         return { headers: [], dataRows: [] };
@@ -218,20 +355,432 @@ function readCSVFile(filePath, delimiter) {
     const dataRows = rows.slice(1);
     return { headers, dataRows };
 }
+/**
+ * Build the canonical field accessor for a header row + data row.
+ */
+function rowFields(headers, row) {
+    const col = (name) => headers.indexOf(name);
+    const get = (name) => {
+        const idx = col(name);
+        return idx >= 0 ? (row[idx] ?? "").trim() : "";
+    };
+    const rawStatus = get("status");
+    const rawPriority = get("priority");
+    const priority = rawPriority ? parseInt(rawPriority, 10) : undefined;
+    return {
+        get,
+        parsed: {
+            title: get("title"),
+            status: rawStatus ? normalizeStatus(rawStatus) : "open",
+            priority: priority !== undefined && !isNaN(priority) ? priority : undefined,
+            tags: parseTags(get("tags")),
+            type: get("type") || undefined,
+            // pm has no milestone/due_date fields; map deadline (accept legacy header).
+            deadline: get("deadline") || get("due_date") || undefined,
+            body: get("body") || undefined,
+            parent: get("parent") || undefined,
+            assignee: get("assignee") || undefined,
+            sprint: get("sprint") || undefined,
+            release: get("release") || undefined,
+            // Accept both blocked_by and a friendlier blocked-by header.
+            blocked_by: get("blocked_by") || get("blocked-by") || undefined,
+        },
+    };
+}
+/**
+ * Parse the `--status`/`--type`/`--priority` import filter flags into a
+ * normalized {@link ImportRowFilter}. Mirrors export filter semantics:
+ *   - status is normalized through {@link normalizeStatus} so the same alias
+ *     vocabulary as a CSV `status` cell applies (e.g. `--status done` matches
+ *     rows whose status normalizes to `closed`).
+ *   - priority must be an integer; a non-integer is a USAGE error.
+ *   - type is matched case-insensitively (lower-cased here and at compare time).
+ * Returns `undefined` when no filter flag is set (the common no-filter path).
+ */
+function parseImportFilter(statusRaw, typeRaw, priorityRaw) {
+    const status = statusRaw && statusRaw.trim() ? normalizeStatus(statusRaw) : undefined;
+    const type = typeRaw && typeRaw.trim() ? typeRaw.trim().toLowerCase() : undefined;
+    let priority;
+    if (priorityRaw !== undefined && priorityRaw.trim() !== "") {
+        const n = Number(priorityRaw.trim());
+        if (!Number.isInteger(n)) {
+            throw new CommandError(`Invalid --priority filter '${priorityRaw}'; expected an integer.`, EXIT_CODE.USAGE);
+        }
+        priority = n;
+    }
+    if (status === undefined && type === undefined && priority === undefined) {
+        return undefined;
+    }
+    return { status, type, priority };
+}
+/**
+ * Pure predicate: does a parsed row satisfy every set filter criterion?
+ * Unset criteria are wildcards. Exposed for unit testing.
+ */
+function rowMatchesFilter(row, filter) {
+    if (!filter)
+        return true;
+    if (filter.status !== undefined && row.status !== filter.status)
+        return false;
+    if (filter.type !== undefined && (row.type ?? "").toLowerCase() !== filter.type)
+        return false;
+    if (filter.priority !== undefined && row.priority !== filter.priority)
+        return false;
+    return true;
+}
+/**
+ * List existing items once and build a lookup from csv-key provenance value to
+ * item id, for idempotent upsert.
+ */
+function loadKeyIndex(pmRoot) {
+    const index = new Map();
+    const result = spawnSync("pm", ["--path", pmRoot, "list-all", "--json"], { encoding: "utf-8", maxBuffer: PM_LIST_MAX_BUFFER });
+    if (result.error)
+        throw new CommandError(`pm list-all failed: ${result.error.message}`);
+    if (result.status !== 0) {
+        throw new CommandError(result.stderr?.trim() || "pm list-all failed");
+    }
+    let items = [];
+    try {
+        items = JSON.parse(result.stdout).items ?? [];
+    }
+    catch {
+        return index;
+    }
+    for (const item of items) {
+        for (const tag of item.tags ?? []) {
+            if (tag.startsWith(KEY_TAG_PREFIX)) {
+                index.set(normalizeKeyValue(decodeKeyTagValue(tag.slice(KEY_TAG_PREFIX.length))), item.id);
+            }
+        }
+    }
+    return index;
+}
+function importCSV(pmRoot, filePath, opts) {
+    const { headers: rawHeaders, dataRows } = readCSVFile(filePath, opts.delimiter, opts.encoding ?? "utf-8");
+    const result = { imported: 0, updated: 0, skipped: 0, filtered: 0, errors: [], previews: [] };
+    if (rawHeaders.length === 0)
+        return result;
+    const headers = applyFieldMap(rawHeaders, opts.fieldMap);
+    if (!headers.includes("title")) {
+        throw new CommandError(`CSV is missing required 'title' column (after --map). Found: ${headers.join(", ")}`, EXIT_CODE.USAGE);
+    }
+    if (opts.keyField && !headers.includes(opts.keyField)) {
+        throw new CommandError(`--key column '${opts.keyField}' not found in CSV. Found: ${headers.join(", ")}`, EXIT_CODE.USAGE);
+    }
+    // Pre-load the dedup index only when upserting (one extra pm call, not per-row).
+    const keyIndex = opts.keyField && !opts.dryRun ? loadKeyIndex(pmRoot) : new Map();
+    for (let rowIndex = 0; rowIndex < dataRows.length; rowIndex++) {
+        const row = dataRows[rowIndex];
+        const lineNo = rowIndex + 2; // 1-based + header row
+        const { get, parsed } = rowFields(headers, row);
+        if (!parsed.title) {
+            const msg = `Row ${lineNo}: skipping — 'title' is empty`;
+            console.error(msg);
+            result.skipped++;
+            continue;
+        }
+        // Row-level filter (mirrors export filter semantics): skip non-matching
+        // rows BEFORE any create/update so they never become pm items.
+        if (!rowMatchesFilter(parsed, opts.filter)) {
+            result.skipped++;
+            result.filtered++;
+            continue;
+        }
+        const keyValue = opts.keyField ? get(opts.keyField) : "";
+        const existingId = keyValue ? keyIndex.get(normalizeKeyValue(keyValue)) : undefined;
+        if (opts.dryRun) {
+            result.previews.push({
+                action: existingId ? "update" : "create",
+                ...parsed,
+                ...(opts.keyField ? { key: keyValue } : {}),
+                ...(opts.source ? { csv_source: opts.source } : {}),
+            });
+            if (existingId)
+                result.updated++;
+            else
+                result.imported++;
+            continue;
+        }
+        try {
+            if (existingId) {
+                upsertUpdate(pmRoot, existingId, parsed, opts.source);
+                result.updated++;
+            }
+            else {
+                const newId = upsertCreate(pmRoot, parsed, opts.keyField ? keyValue : undefined, opts.source);
+                if (opts.keyField && keyValue && newId)
+                    keyIndex.set(normalizeKeyValue(keyValue), newId);
+                result.imported++;
+            }
+        }
+        catch (err) {
+            const msg = `Row ${lineNo}: ${existingId ? "update" : "create"} failed — ${err instanceof Error ? err.message : String(err)}`;
+            console.error(msg);
+            result.errors.push(msg);
+            result.skipped++;
+        }
+    }
+    return result;
+}
+/**
+ * Append the relational/planning field flags shared by create and update.
+ * Flag names verified against the installed `pm create`/`pm update` contracts:
+ * --parent, --assignee, --sprint, --release, --blocked-by.
+ */
+function appendRelationalArgs(args, p) {
+    if (p.parent)
+        args.push("--parent", p.parent);
+    if (p.assignee)
+        args.push("--assignee", p.assignee);
+    if (p.sprint)
+        args.push("--sprint", p.sprint);
+    if (p.release)
+        args.push("--release", p.release);
+    if (p.blocked_by)
+        args.push("--blocked-by", p.blocked_by);
+}
+/** Create a new item, optionally carrying a csv-key provenance tag. Returns the new id. */
+function upsertCreate(pmRoot, p, keyValue, source) {
+    const tags = [...p.tags];
+    // Encode the lower-cased key so the stored tag matches the lookup index
+    // regardless of pm's tag case-folding (see normalizeKeyValue).
+    if (keyValue)
+        tags.push(`${KEY_TAG_PREFIX}${encodeKeyTagValue(normalizeKeyValue(keyValue))}`);
+    // Provenance for the schema-registered csv_source field, persisted as a tag
+    // since the CLI exposes no scalar setter for extension-registered fields.
+    if (source)
+        tags.push(`${SOURCE_TAG_PREFIX}${encodeKeyTagValue(source)}`);
+    const args = ["--path", pmRoot, "create", "--title", p.title, "--status", p.status, "--json"];
+    if (p.body)
+        args.push("--body", p.body);
+    if (p.priority !== undefined)
+        args.push("--priority", String(p.priority));
+    if (p.type)
+        args.push("--type", p.type);
+    if (p.deadline)
+        args.push("--deadline", p.deadline);
+    appendRelationalArgs(args, p);
+    if (tags.length > 0)
+        args.push("--tags", tags.join(","));
+    const r = spawnSync("pm", args, { encoding: "utf-8" });
+    if (r.status !== 0)
+        throw new Error(r.stderr?.trim() || "pm create failed");
+    try {
+        const parsed = JSON.parse(r.stdout);
+        return parsed.id ?? parsed.item?.id ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+/** Update an existing item in place (status via update; close handled separately). */
+function upsertUpdate(pmRoot, id, p, source) {
+    const args = ["--path", pmRoot, "update", id, "--title", p.title];
+    if (p.body !== undefined)
+        args.push("--body", p.body);
+    if (p.priority !== undefined)
+        args.push("--priority", String(p.priority));
+    if (p.type)
+        args.push("--type", p.type);
+    if (p.deadline)
+        args.push("--deadline", p.deadline);
+    appendRelationalArgs(args, p);
+    // Preserve the csv-key tag (additive) and refresh the user tags.
+    const addTags = [...p.tags];
+    if (source)
+        addTags.push(`${SOURCE_TAG_PREFIX}${encodeKeyTagValue(source)}`);
+    if (addTags.length > 0)
+        args.push("--add-tags", addTags.join(","));
+    // `update` cannot set a closed status; only set non-closed statuses here.
+    if (p.status !== "closed" && p.status !== "canceled")
+        args.push("--status", p.status);
+    const r = spawnSync("pm", args, { encoding: "utf-8" });
+    if (r.status !== 0)
+        throw new Error(r.stderr?.trim() || "pm update failed");
+    // Apply terminal statuses through the dedicated close command.
+    if (p.status === "closed" || p.status === "canceled") {
+        const reason = p.status === "canceled" ? "canceled" : "completed";
+        const cr = spawnSync("pm", ["--path", pmRoot, "close", id, "--reason", reason], { encoding: "utf-8" });
+        if (cr.status !== 0)
+            throw new Error(cr.stderr?.trim() || "pm close failed");
+    }
+}
+/**
+ * Parse a CSV and report data-quality issues without writing anything.
+ * Pure function over file contents — exposed for unit testing via the
+ * lower-level {@link validateParsedCSV} helper below.
+ */
+function validateCSV(filePath, opts) {
+    const { headers: rawHeaders, dataRows } = readCSVFile(filePath, opts.delimiter, opts.encoding ?? "utf-8");
+    return validateParsedCSV(rawHeaders, dataRows, opts.fieldMap);
+}
+/**
+ * Core validation logic over already-parsed headers + rows. Pure and
+ * side-effect-free so it can be unit tested directly.
+ */
+function validateParsedCSV(rawHeaders, dataRows, fieldMap) {
+    const mappedColumns = applyFieldMap(rawHeaders, fieldMap);
+    const hasTitleColumn = mappedColumns.includes("title");
+    const issues = [];
+    let rowsMissingTitle = 0;
+    let rowsWithUnknownStatus = 0;
+    let rowsWithNonIntegerPriority = 0;
+    const titleIdx = mappedColumns.indexOf("title");
+    const statusIdx = mappedColumns.indexOf("status");
+    const priorityIdx = mappedColumns.indexOf("priority");
+    for (const row of dataRows) {
+        if (hasTitleColumn) {
+            const title = (row[titleIdx] ?? "").trim();
+            if (!title)
+                rowsMissingTitle++;
+        }
+        if (statusIdx >= 0) {
+            const status = (row[statusIdx] ?? "").trim().toLowerCase();
+            if (status && !KNOWN_STATUSES.has(status))
+                rowsWithUnknownStatus++;
+        }
+        if (priorityIdx >= 0) {
+            const priority = (row[priorityIdx] ?? "").trim();
+            if (priority && !/^-?\d+$/.test(priority))
+                rowsWithNonIntegerPriority++;
+        }
+    }
+    if (rawHeaders.length === 0) {
+        issues.push("CSV is empty (no header row).");
+    }
+    if (!hasTitleColumn) {
+        issues.push(`Missing required 'title' column (after --map). Detected: ${mappedColumns.join(", ") || "(none)"}`);
+    }
+    if (rowsMissingTitle > 0) {
+        issues.push(`${rowsMissingTitle} row(s) have an empty title and would be skipped.`);
+    }
+    if (rowsWithUnknownStatus > 0) {
+        issues.push(`${rowsWithUnknownStatus} row(s) have an unrecognized status (would fall back to 'open').`);
+    }
+    if (rowsWithNonIntegerPriority > 0) {
+        issues.push(`${rowsWithNonIntegerPriority} row(s) have a non-integer priority (would be ignored).`);
+    }
+    // Only a missing title column (or empty file) is a structural problem.
+    const ok = hasTitleColumn && rawHeaders.length > 0;
+    return {
+        ok,
+        rowCount: dataRows.length,
+        detectedColumns: rawHeaders,
+        mappedColumns,
+        hasTitleColumn,
+        rowsMissingTitle,
+        rowsWithUnknownStatus,
+        rowsWithNonIntegerPriority,
+        issues,
+    };
+}
+/**
+ * Discover custom item fields registered in the workspace runtime schema and
+ * return those that are NOT already covered by the built-in export columns
+ * (or the provenance `csv_source` column).
+ *
+ * This is the standalone-extension-safe equivalent of the SDK's
+ * `resolveRuntimeFieldRegistry(settings.schema)`: a standalone-installed
+ * extension only loads its own `dist/`, so `@unbrained/pm-cli` is not
+ * resolvable at runtime and the SDK function cannot be imported. We instead
+ * read the very same inputs that function consumes — the workspace
+ * `settings.json` `schema.fields` plus the file it points at
+ * (`schema.files.fields`, default `schema/fields.json`) — and merge them by
+ * field key. The shape matches the SDK `RuntimeFieldDefinition` type.
+ *
+ * Never throws: any read/parse problem yields an empty list so export still
+ * works on hosts without a runtime field schema.
+ */
+function discoverCustomFields(pmRoot) {
+    const builtin = new Set(EXPORT_COLUMNS);
+    const byKey = new Map();
+    const collect = (fields) => {
+        if (!Array.isArray(fields))
+            return;
+        for (const raw of fields) {
+            if (!raw || typeof raw !== "object")
+                continue;
+            const def = raw;
+            const key = typeof def.key === "string" ? def.key.trim() : "";
+            if (!key || builtin.has(key))
+                continue;
+            const metadataKey = (typeof def.metadata_key === "string" && def.metadata_key.trim()) ||
+                (typeof def.front_matter_key === "string" && def.front_matter_key.trim()) ||
+                key;
+            if (!byKey.has(key))
+                byKey.set(key, { key, metadataKey });
+        }
+    };
+    let settings = {};
+    try {
+        settings = JSON.parse(readFileSync(resolve(pmRoot, "settings.json"), "utf-8"));
+    }
+    catch {
+        return [];
+    }
+    const schema = (settings["schema"] ?? {});
+    // Inline fields declared directly in settings.json.
+    collect(schema["fields"]);
+    // File-backed fields (schema.files.fields, default schema/fields.json) — the
+    // path the CLI scaffolds and the SDK loader reads.
+    const files = (schema["files"] ?? {});
+    const fieldsPath = typeof files["fields"] === "string" && files["fields"].trim()
+        ? files["fields"]
+        : "schema/fields.json";
+    try {
+        const fileJson = JSON.parse(readFileSync(resolve(pmRoot, fieldsPath), "utf-8"));
+        collect(fileJson?.fields);
+    }
+    catch {
+        // No file / unreadable / unparsable — inline fields (if any) still apply.
+    }
+    return [...byKey.values()];
+}
 // Parse a `--columns id,title,status` spec into a validated, ordered subset of
 // the export columns. Unknown column names throw a USAGE error; an empty/absent
-// spec falls back to the full default column set.
-function selectExportColumns(spec) {
+// spec falls back to the full default column set. `extraValid` lets discovered
+// custom-field keys be selected explicitly via --columns alongside --all-fields.
+function selectExportColumns(spec, extraValid = []) {
     if (!spec || !spec.trim())
-        return EXPORT_COLUMNS;
+        return [...EXPORT_COLUMNS];
     const requested = spec.split(",").map((s) => s.trim()).filter(Boolean);
-    const valid = new Set(EXPORT_COLUMNS);
+    const valid = new Set([...EXPORT_COLUMNS, ...extraValid]);
     const unknown = requested.filter((c) => !valid.has(c));
     if (unknown.length > 0) {
-        throw new CommandError(`Unknown export column(s): ${unknown.join(", ")}. Valid: ${EXPORT_COLUMNS.join(", ")}`, EXIT_CODE.USAGE);
+        const validList = [...EXPORT_COLUMNS, ...extraValid].join(", ");
+        throw new CommandError(`Unknown export column(s): ${unknown.join(", ")}. Valid: ${validList}`, EXIT_CODE.USAGE);
     }
     return requested;
 }
+/**
+ * Resolve the effective export column list (and the column→property remap for
+ * custom fields) shared by `csv export` and the `csv-export` exporter.
+ *
+ * - With no `--columns` and no discovery, returns the default built-in set.
+ * - With `discover` set, appends every discovered custom field key not already
+ *   present (default column set otherwise unchanged — strictly additive).
+ * - With `--columns`, the explicit, ordered selection wins; discovered custom
+ *   field keys become selectable names too.
+ */
+function resolveExportColumns(pmRoot, columnsSpec, discover) {
+    const discovered = discover ? discoverCustomFields(pmRoot) : [];
+    const columnSource = {};
+    for (const f of discovered) {
+        if (f.key !== f.metadataKey)
+            columnSource[f.key] = f.metadataKey;
+    }
+    if (columnsSpec && columnsSpec.trim()) {
+        const columns = selectExportColumns(columnsSpec, discovered.map((f) => f.key));
+        return { columns, columnSource };
+    }
+    const columns = [...EXPORT_COLUMNS];
+    for (const f of discovered) {
+        if (!columns.includes(f.key))
+            columns.push(f.key);
+    }
+    return { columns, columnSource };
+}
 function buildCsvExport(pmRoot, opts) {
     const result = spawnSync("pm", ["--path", pmRoot, "list-all", "--json", "--include-body"], { encoding: "utf-8" });
     if (result.status !== 0) {
@@ -242,133 +791,205 @@ function buildCsvExport(pmRoot, opts) {
         items = items.filter((i) => i.status === opts.statusFilter);
     if (opts.typeFilter)
         items = items.filter((i) => i.type === opts.typeFilter);
-    const headerRow = opts.columns.map(String);
+    // Surface provenance: derive csv_source from the internal csv-source: tag.
+    for (const item of items) {
+        const sourceTag = (item.tags ?? []).find((t) => t.startsWith(SOURCE_TAG_PREFIX));
+        if (sourceTag)
+            item.csv_source = decodeKeyTagValue(sourceTag.slice(SOURCE_TAG_PREFIX.length));
+    }
     const dataRows = items.map((item) => opts.columns.map((col) => {
-        const val = item[col];
+        const prop = opts.columnSource?.[col] ?? col;
+        const val = item[prop];
         if (val === undefined || val === null)
             return "";
-        if (Array.isArray(val))
-            return stringifyTags(val);
+        if (Array.isArray(val)) {
+            // Strip internal provenance tags (csv-key / csv-source) so a round-trip
+            // export stays clean.
+            const visible = val.filter((t) => typeof t === "string" &&
+                !t.startsWith(KEY_TAG_PREFIX) &&
+                !t.startsWith(SOURCE_TAG_PREFIX));
+            return stringifyTags(visible);
+        }
         return String(val);
     }));
-    return { csvText: serializeCSV([headerRow, ...dataRows], opts.delimiter), count: items.length };
+    const allRows = opts.noHeader ? dataRows : [opts.columns.map(String), ...dataRows];
+    // --excel implies CRLF (and a UTF-8 BOM prefix, added below).
+    const eol = opts.crlf || opts.excel ? "\r\n" : "\n";
+    let csvText = serializeCSV(allRows, { delimiter: opts.delimiter, eol });
+    if (opts.excel)
+        csvText = "" + csvText;
+    return {
+        csvText,
+        count: items.length,
+    };
 }
 export default defineExtension({
     name: "pm-csv",
-    version: "2026.6.2",
+    version: "2026.6.4",
     activate(api) {
+        // -----------------------------------------------------------------------
+        // Schema: register an optional `csv_source` provenance field so imported
+        // items can record where they came from (set via `pm csv import --source`).
+        // Guarded: only call when the running SDK exposes registerItemFields, so
+        // older hosts that lack the schema capability degrade to a no-op (and the
+        // manifest still declares "schema" because we genuinely implement it).
+        //
+        // NOTE: pm 2026.5.31 accepts the field into the schema registry but exposes
+        // no `pm create --csv_source` setter for extension-registered scalar fields,
+        // so the importer persists the provenance label as a `csv-source:` tag
+        // (stripped from exports and surfaced back via the csv_source export column).
+        // -----------------------------------------------------------------------
+        if (typeof api.registerItemFields === "function") {
+            try {
+                api.registerItemFields([
+                    { name: "csv_source", type: "string", optional: true },
+                ]);
+            }
+            catch (err) {
+                // Never let a schema-registration hiccup break command registration.
+                console.error(`pm-csv: csv_source field not registered — ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
         // -----------------------------------------------------------------------
         // Command: pm csv import <file>
         // -----------------------------------------------------------------------
         api.registerCommand({
             name: "csv import",
-            description: "Import pm items from a CSV file. " +
-                "Expected columns: title, type, status, priority, tags, milestone, due_date, body. " +
-                "Only 'title' is required; all other columns are optional.",
+            description: "Import pm items from a CSV file with full RFC-4180 parsing (quoted fields, " +
+                "embedded newlines, escaped quotes, BOM, CRLF). Expected columns: title, type, " +
+                "status, priority, tags, deadline, body, parent, assignee, sprint, release, " +
+                "blocked_by. Only 'title' is required. Use --map to remap arbitrary headers, " +
+                "--key for idempotent re-import (upsert), --encoding for non-UTF-8 files, " +
+                "--source to record import provenance in the csv_source field, and " +
+                "--status/--type/--priority to import only matching rows (others are skipped).",
             intent: "import items from a CSV file into pm",
             examples: [
                 "pm csv import tasks.csv",
                 "pm csv import backlog.csv --delimiter ';'",
+                "pm csv import data.tsv --delimiter tab",
+                "pm csv import jira.csv --map 'Summary=title,Owner=tags'",
+                "pm csv import items.csv --key title   # idempotent re-import (no duplicates)",
+                "pm csv import legacy.csv --encoding latin1",
+                "pm csv import sprint12.csv --source 'jira-export-2026-06'",
+                "pm csv import tasks.csv --status open          # import only open rows",
+                "pm csv import tasks.csv --type Feature --priority 1",
                 "pm csv import items.csv --dry-run",
             ],
             flags: [
-                { long: "--delimiter", value_name: "char", description: "CSV field delimiter (default: ,)" },
+                { long: "--delimiter", value_name: "char", description: "Field delimiter, or alias tab|comma|semicolon|pipe (default: ,)" },
+                { long: "--map", value_name: "col=field", description: "Remap a CSV header to a pm field (repeatable, comma-joined). e.g. --map 'Summary=title'" },
+                { long: "--key", value_name: "field", description: "Dedup key column: re-import updates the matching item instead of creating a duplicate" },
+                { long: "--encoding", value_name: "enc", description: "Source file encoding: utf-8 (default) | utf16le | latin1" },
+                { long: "--source", value_name: "label", description: "Record an import-provenance label in the csv_source field of created/updated items" },
+                { long: "--status", value_name: "filter", description: "Import only rows whose (normalized) status matches: open | in_progress | blocked | closed | canceled | draft" },
+                { long: "--type", value_name: "type", description: "Import only rows whose type matches (case-insensitive)" },
+                { long: "--priority", value_name: "n", description: "Import only rows whose integer priority equals this value" },
                 { long: "--dry-run", description: "Preview without writing" },
             ],
             async run(ctx) {
                 const filePath = ctx.args[0];
                 if (!filePath) {
-                    throw new CommandError("Usage: pm csv import <file> [--delimiter <char>] [--dry-run]", EXIT_CODE.USAGE);
+                    throw new CommandError("Usage: pm csv import <file> [--delimiter <char>] [--map col=field] [--key field] [--encoding enc] [--source label] [--status s] [--type t] [--priority n] [--dry-run]", EXIT_CODE.USAGE);
                 }
-                const delimiter = ctx.options["delimiter"] ?? ",";
+                const delimiter = resolveDelimiter(ctx.options["delimiter"]);
                 const dryRun = readBoolOption(ctx.options, "dry-run", "dryRun");
+                const fieldMap = parseFieldMap(ctx.options["map"]);
+                const keyField = (ctx.options["key"] ?? "").trim().toLowerCase() || undefined;
+                const encoding = resolveEncoding(ctx.options["encoding"]);
+                const source = (ctx.options["source"] ?? "").trim() || undefined;
+                const filter = parseImportFilter(ctx.options["status"], ctx.options["type"], ctx.options["priority"]);
                 const absolutePath = resolve(filePath);
                 console.error(`Reading CSV from: ${absolutePath}`);
-                let headers;
-                let dataRows;
+                let res;
                 try {
-                    ({ headers, dataRows } = readCSVFile(absolutePath, delimiter));
+                    res = importCSV(ctx.pm_root, absolutePath, { delimiter, dryRun, fieldMap, keyField, encoding, source, filter });
                 }
                 catch (err) {
+                    if (err instanceof CommandError)
+                        throw err;
                     const msg = err instanceof Error ? err.message : String(err);
                     const exitCode = /ENOENT|no such file/i.test(msg) ? EXIT_CODE.NOT_FOUND : EXIT_CODE.GENERIC_FAILURE;
-                    throw new CommandError(`Failed to read file: ${msg}`, exitCode);
+                    throw new CommandError(`Failed to import: ${msg}`, exitCode);
                 }
-                if (headers.length === 0) {
-                    console.error("CSV file is empty or has no headers.");
-                    return { imported: 0, skipped: 0 };
+                const filterNote = res.filtered > 0 ? ` (${res.filtered} filtered out)` : "";
+                if (dryRun) {
+                    console.error(`[dry-run] Would create ${res.imported}, update ${res.updated}, skip ${res.skipped}${filterNote}.`);
+                    return {
+                        dryRun: true,
+                        wouldCreate: res.imported,
+                        wouldUpdate: res.updated,
+                        wouldSkip: res.skipped,
+                        filtered: res.filtered,
+                        previews: res.previews,
+                    };
                 }
-                // Validate that at minimum 'title' is present
-                if (!headers.includes("title")) {
-                    throw new CommandError(`CSV is missing required 'title' column. Found: ${headers.join(", ")}`);
+                console.error(`Imported ${res.imported}, updated ${res.updated}, skipped ${res.skipped}${filterNote}.`);
+                return { imported: res.imported, updated: res.updated, skipped: res.skipped, filtered: res.filtered, errors: res.errors };
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Command: pm csv validate <file>
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "csv validate",
+            description: "Validate a CSV without importing it. Reports row count, detected/mapped " +
+                "columns, rows missing a title, rows with unrecognized status, rows with a " +
+                "non-integer priority, and whether the required 'title' column is present " +
+                "(after --map). Exits non-zero on structural problems (missing title column). " +
+                "Honors --delimiter, --map, --encoding; supports --json.",
+            intent: "validate a CSV file without importing",
+            examples: [
+                "pm csv validate tasks.csv",
+                "pm csv validate jira.csv --map 'Summary=title'",
+                "pm csv validate data.tsv --delimiter tab --json",
+            ],
+            flags: [
+                { long: "--delimiter", value_name: "char", description: "Field delimiter, or alias tab|comma|semicolon|pipe (default: ,)" },
+                { long: "--map", value_name: "col=field", description: "Remap a CSV header to a pm field (repeatable, comma-joined) before validating" },
+                { long: "--encoding", value_name: "enc", description: "Source file encoding: utf-8 (default) | utf16le | latin1" },
+                { long: "--json", description: "Emit the report as JSON" },
+            ],
+            async run(ctx) {
+                const filePath = ctx.args[0];
+                if (!filePath) {
+                    throw new CommandError("Usage: pm csv validate <file> [--delimiter <char>] [--map col=field] [--encoding enc] [--json]", EXIT_CODE.USAGE);
                 }
-                // Index columns
-                const col = (name) => headers.indexOf(name);
-                let imported = 0;
-                let skipped = 0;
-                const previews = [];
-                for (let rowIndex = 0; rowIndex < dataRows.length; rowIndex++) {
-                    const row = dataRows[rowIndex];
-                    const get = (name) => {
-                        const idx = col(name);
-                        return idx >= 0 ? (row[idx] ?? "").trim() : "";
-                    };
-                    const title = get("title");
-                    if (!title) {
-                        console.error(`Row ${rowIndex + 2}: skipping — 'title' is empty`);
-                        skipped++;
-                        continue;
-                    }
-                    const rawStatus = get("status");
-                    const status = rawStatus ? normalizeStatus(rawStatus) : "open";
-                    const rawPriority = get("priority");
-                    const priority = rawPriority ? parseInt(rawPriority, 10) : undefined;
-                    const tags = parseTags(get("tags"));
-                    const type = get("type") || undefined;
-                    // pm has no milestone/due_date fields on `create`; the deadline column
-                    // (accept legacy "due_date" header too) maps to `--deadline`.
-                    const deadline = get("deadline") || get("due_date") || undefined;
-                    const body = get("body") || undefined;
-                    if (dryRun) {
-                        previews.push({ title, type, status, priority, tags, deadline, body });
-                        imported++;
-                        continue;
-                    }
-                    try {
-                        const spawnArgs = [
-                            "--path", ctx.pm_root,
-                            "create",
-                            "--title", title,
-                            "--status", status,
-                        ];
-                        if (body)
-                            spawnArgs.push("--body", body);
-                        if (priority !== undefined && !isNaN(priority))
-                            spawnArgs.push("--priority", String(priority));
-                        if (type)
-                            spawnArgs.push("--type", type);
-                        if (deadline)
-                            spawnArgs.push("--deadline", deadline);
-                        if (tags.length > 0)
-                            spawnArgs.push("--tags", tags.join(","));
-                        const result = spawnSync("pm", spawnArgs, { encoding: "utf-8" });
-                        if (result.status !== 0) {
-                            throw new Error(result.stderr || "pm create failed");
-                        }
-                        imported++;
-                    }
-                    catch (err) {
-                        const msg = err instanceof Error ? err.message : String(err);
-                        console.error(`Row ${rowIndex + 2}: create failed — ${msg}`);
-                        skipped++;
-                    }
+                const delimiter = resolveDelimiter(ctx.options["delimiter"]);
+                const fieldMap = parseFieldMap(ctx.options["map"]);
+                const encoding = resolveEncoding(ctx.options["encoding"]);
+                const asJson = readBoolOption(ctx.options, "json");
+                const absolutePath = resolve(filePath);
+                let report;
+                try {
+                    report = validateCSV(absolutePath, { delimiter, fieldMap, encoding });
                 }
-                if (dryRun) {
-                    console.error(`[dry-run] Would import ${imported} item(s), skip ${skipped} item(s).`);
-                    return { dryRun: true, wouldImport: imported, wouldSkip: skipped, previews };
+                catch (err) {
+                    if (err instanceof CommandError)
+                        throw err;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    const exitCode = /ENOENT|no such file/i.test(msg) ? EXIT_CODE.NOT_FOUND : EXIT_CODE.GENERIC_FAILURE;
+                    throw new CommandError(`Failed to validate: ${msg}`, exitCode);
                 }
-                console.error(`Imported ${imported} item(s), skipped ${skipped} item(s).`);
-                return { imported, skipped };
+                // Human-readable summary on stderr (so --json stdout stays clean).
+                console.error(`Rows: ${report.rowCount}`);
+                console.error(`Detected columns: ${report.detectedColumns.join(", ") || "(none)"}`);
+                console.error(`Mapped columns:   ${report.mappedColumns.join(", ") || "(none)"}`);
+                console.error(`Has 'title' column: ${report.hasTitleColumn ? "yes" : "no"}`);
+                console.error(`Rows missing title: ${report.rowsMissingTitle}`);
+                console.error(`Rows w/ unknown status: ${report.rowsWithUnknownStatus}`);
+                console.error(`Rows w/ non-integer priority: ${report.rowsWithNonIntegerPriority}`);
+                for (const issue of report.issues)
+                    console.error(`  - ${issue}`);
+                console.error(report.ok ? "Validation OK." : "Validation FAILED (structural problems).");
+                // Structural problems (no title column / empty) → non-zero exit.
+                if (!report.ok) {
+                    if (asJson) {
+                        // Surface the structured report even on failure before throwing.
+                        console.error(JSON.stringify(report, null, 2));
+                    }
+                    throw new CommandError("CSV is missing the required 'title' column (after --map).", EXIT_CODE.USAGE);
+                }
+                return report;
             },
         });
         // -----------------------------------------------------------------------
@@ -385,24 +1006,39 @@ export default defineExtension({
                 "pm csv export --output backlog.csv --delimiter ';'",
                 "pm csv export --status open --output todos.csv",
                 "pm csv export --type Feature --output features.csv",
+                "pm csv export --all-fields --output full.csv   # include custom workspace fields",
+                "pm csv export --excel --output for-excel.csv",
             ],
             flags: [
                 { long: "--output", value_name: "file", description: "Output file path (default: print to stdout)" },
-                { long: "--delimiter", value_name: "char", description: "CSV field delimiter (default: ,)" },
+                { long: "--delimiter", value_name: "char", description: "Field delimiter, or alias tab|comma|semicolon|pipe (default: ,)" },
                 { long: "--status", value_name: "filter", description: "Filter by status: open | in_progress | blocked | closed | canceled | draft" },
                 { long: "--type", value_name: "type", description: "Filter by item type" },
-                { long: "--columns", value_name: "list", description: `Comma-separated columns to export, in order (default: all). Valid: ${EXPORT_COLUMNS.join(", ")}` },
+                { long: "--columns", value_name: "list", description: `Comma-separated columns to export, in order (default: all). Valid: ${EXPORT_COLUMNS.join(", ")} (plus any discovered custom fields)` },
+                { long: "--all-fields", description: "Discover custom item fields registered in the workspace schema and append them as columns" },
+                { long: "--discover-fields", description: "Alias for --all-fields" },
+                { long: "--no-header", description: "Omit the CSV header row" },
+                { long: "--crlf", description: "Use CRLF line endings (RFC-4180 / Excel)" },
+                { long: "--excel", description: "Excel-friendly output: CRLF line endings + a UTF-8 BOM prefix" },
             ],
             async run(ctx) {
-                const delimiter = ctx.options["delimiter"] ?? ",";
+                const delimiter = resolveDelimiter(ctx.options["delimiter"]);
                 const outputPath = ctx.options["output"];
-                const columns = selectExportColumns(ctx.options["columns"]);
+                const discover = readBoolOption(ctx.options, "all-fields", "allFields", "discover-fields", "discoverFields");
+                const { columns, columnSource } = resolveExportColumns(ctx.pm_root, ctx.options["columns"], discover);
+                const noHeader = readBoolOption(ctx.options, "no-header", "noHeader");
+                const crlf = readBoolOption(ctx.options, "crlf");
+                const excel = readBoolOption(ctx.options, "excel");
                 console.error("Fetching pm items…");
                 const { csvText, count } = buildCsvExport(ctx.pm_root, {
                     statusFilter: ctx.options["status"],
                     typeFilter: ctx.options["type"],
                     delimiter,
                     columns,
+                    columnSource,
+                    noHeader,
+                    crlf,
+                    excel,
                 });
                 if (count === 0) {
                     console.error("No items found.");
@@ -424,14 +1060,22 @@ export default defineExtension({
         // Mirrors the importer so CSV is a first-class import/export pair.
         // -----------------------------------------------------------------------
         api.registerExporter("csv-export", async (ctx) => {
-            const delimiter = ctx.options["delimiter"] ?? ",";
+            const delimiter = resolveDelimiter(ctx.options["delimiter"]);
             const outputPath = ctx.options["output"];
-            const columns = selectExportColumns(ctx.options["columns"]);
+            const discover = readBoolOption(ctx.options, "all-fields", "allFields", "discover-fields", "discoverFields");
+            const { columns, columnSource } = resolveExportColumns(ctx.pm_root, ctx.options["columns"], discover);
+            const noHeader = readBoolOption(ctx.options, "no-header", "noHeader");
+            const crlf = readBoolOption(ctx.options, "crlf");
+            const excel = readBoolOption(ctx.options, "excel");
             const { csvText, count } = buildCsvExport(ctx.pm_root, {
                 statusFilter: ctx.options["status"],
                 typeFilter: ctx.options["type"],
                 delimiter,
                 columns,
+                columnSource,
+                noHeader,
+                crlf,
+                excel,
             });
             if (outputPath) {
                 const absolutePath = resolve(outputPath);
@@ -451,76 +1095,30 @@ export default defineExtension({
                 console.error("csv-import: no 'file' provided in options — skipping.");
                 return;
             }
-            const delimiter = ctx.options["delimiter"] ?? ",";
+            const delimiter = resolveDelimiter(ctx.options["delimiter"]);
+            const fieldMap = parseFieldMap(ctx.options["map"]);
+            const keyField = (ctx.options["key"] ?? "").trim().toLowerCase() || undefined;
+            const encoding = resolveEncoding(ctx.options["encoding"]);
+            const source = (ctx.options["source"] ?? "").trim() || undefined;
+            const filter = parseImportFilter(ctx.options["status"], ctx.options["type"], ctx.options["priority"]);
             const absolutePath = resolve(filePath);
             console.error(`csv-import: reading ${absolutePath}`);
-            let headers;
-            let dataRows;
+            let res;
             try {
-                ({ headers, dataRows } = readCSVFile(absolutePath, delimiter));
+                res = importCSV(ctx.pm_root, absolutePath, { delimiter, dryRun: false, fieldMap, keyField, encoding, source, filter });
             }
             catch (err) {
                 const msg = err instanceof Error ? err.message : String(err);
-                console.error(`csv-import: failed to read file — ${msg}`);
+                console.error(`csv-import: failed — ${msg}`);
                 return;
             }
-            if (!headers.includes("title")) {
-                console.error("csv-import: CSV is missing required 'title' column — skipping.");
-                return;
-            }
-            const col = (name) => headers.indexOf(name);
-            let imported = 0;
-            let skipped = 0;
-            for (let rowIndex = 0; rowIndex < dataRows.length; rowIndex++) {
-                const row = dataRows[rowIndex];
-                const get = (name) => {
-                    const idx = col(name);
-                    return idx >= 0 ? (row[idx] ?? "").trim() : "";
-                };
-                const title = get("title");
-                if (!title) {
-                    skipped++;
-                    continue;
-                }
-                const rawStatus = get("status");
-                const status = rawStatus ? normalizeStatus(rawStatus) : "open";
-                const rawPriority = get("priority");
-                const priority = rawPriority ? parseInt(rawPriority, 10) : undefined;
-                const tags = parseTags(get("tags"));
-                const type = get("type") || undefined;
-                const deadline = get("deadline") || get("due_date") || undefined;
-                const body = get("body") || undefined;
-                try {
-                    const spawnArgs = [
-                        "--path", ctx.pm_root,
-                        "create",
-                        "--title", title,
-                        "--status", status,
-                    ];
-                    if (body)
-                        spawnArgs.push("--body", body);
-                    if (priority !== undefined && !isNaN(priority))
-                        spawnArgs.push("--priority", String(priority));
-                    if (type)
-                        spawnArgs.push("--type", type);
-                    if (deadline)
-                        spawnArgs.push("--deadline", deadline);
-                    if (tags.length > 0)
-                        spawnArgs.push("--tags", tags.join(","));
-                    const result = spawnSync("pm", spawnArgs, { encoding: "utf-8" });
-                    if (result.status !== 0) {
-                        throw new Error(result.stderr || "pm create failed");
-                    }
-                    imported++;
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    console.error(`csv-import: row ${rowIndex + 2} create failed — ${msg}`);
-                    skipped++;
-                }
-            }
-            console.error(`csv-import: done — imported ${imported}, skipped ${skipped}.`);
+            const filterNote = res.filtered > 0 ? ` (${res.filtered} filtered out)` : "";
+            console.error(`csv-import: done — imported ${res.imported}, updated ${res.updated}, skipped ${res.skipped}${filterNote}.`);
         });
     },
 });
+// ---------------------------------------------------------------------------
+// Named exports — pure helpers exposed for unit testing (no side effects).
+// ---------------------------------------------------------------------------
+export { parseCSV, serializeCSV, serializeField, stripBOM, resolveDelimiter, parseFieldMap, applyFieldMap, normalizeStatus, parseTags, stringifyTags, encodeKeyTagValue, decodeKeyTagValue, normalizeKeyValue, selectExportColumns, resolveEncoding, validateParsedCSV, parseImportFilter, rowMatchesFilter, discoverCustomFields, EXPORT_COLUMNS, IMPORT_COLUMNS, };
 //# sourceMappingURL=index.js.map