pm-csv 2026.10.22 → 2026.10.24

package/dist/index.js

@@ -1,8 +1,11 @@
-import { readFileSync, writeFileSync, createReadStream } from "node:fs";
+import { readFileSync, writeFileSync, createReadStream, mkdirSync } from "node:fs";
 import { basename, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { certifyCompleteListResult, inspectCompleteListResult, runWorkspaceTransactionGc } from "@unbrained/pm-cli/sdk";
+import { importLineage, writeLineageBundle, LineageRefusal } from "./lineage.js";
+import { applyEditSession, exportEditSession, EditRefusal } from "./roundtrip.js";
+import { registerTableSchemaCommands } from "./table-schema.js";
 import { captureUpdateCompensation, compensateUpdate, inspectUpdate, UPDATE_COMPENSATION_VERSION } from "./atomic-update.js";
 // ---------------------------------------------------------------------------
 // Error contract
@@ -92,15 +95,18 @@ const SUPPORTED_ENCODINGS = ["utf-8", "utf8", "utf16le", "latin1"];
  *  - Escaped quotes ("" inside a quoted field → single ")
  *  - Custom delimiter
  *  - CRLF and LF line endings
+ *  - Explicit quoted empty records at EOF, without inventing a row after a final newline
  */
 function parseCSV(text, delimiter = ",") {
     const rows = [];
     let row = [];
     let field = "";
     let inQuotes = false;
+    let recordStarted = false;
     let i = 0;
     while (i < text.length) {
         const ch = text[i];
+        recordStarted = true;
         if (inQuotes) {
             if (ch === '"') {
                 // Peek ahead: "" means escaped quote
@@ -136,6 +142,7 @@ function parseCSV(text, delimiter = ",") {
             field = "";
             rows.push(row);
             row = [];
+            recordStarted = false;
             i += 2;
             continue;
         }
@@ -144,14 +151,15 @@ function parseCSV(text, delimiter = ",") {
             field = "";
             rows.push(row);
             row = [];
+            recordStarted = false;
             i++;
             continue;
         }
         field += ch;
         i++;
     }
-    // Flush last field / row
-    if (field !== "" || row.length > 0) {
+    // An explicit quoted empty field starts a record even though its value is empty.
+    if (recordStarted) {
         row.push(field);
         rows.push(row);
     }
@@ -207,6 +215,7 @@ class StreamingCSVParser {
     field = "";
     row = [];
     inQuotes = false;
+    recordStarted = false;
     pendingBoundaryChar = "";
     constructor(delimiter, onRow) {
         this.delimiter = delimiter;
@@ -218,6 +227,7 @@ class StreamingCSVParser {
         let i = 0;
         while (i < text.length) {
             const ch = text[i];
+            this.recordStarted = true;
             if (this.inQuotes) {
                 if (ch === '"') {
                     if (i + 1 === text.length) {
@@ -253,6 +263,7 @@ class StreamingCSVParser {
                 this.field = "";
                 this.onRow(this.row);
                 this.row = [];
+                this.recordStarted = false;
                 i += 2;
                 continue;
             }
@@ -265,6 +276,7 @@ class StreamingCSVParser {
                 this.field = "";
                 this.onRow(this.row);
                 this.row = [];
+                this.recordStarted = false;
                 i++;
                 continue;
             }
@@ -280,11 +292,12 @@ class StreamingCSVParser {
             this.field += this.pendingBoundaryChar;
         }
         this.pendingBoundaryChar = "";
-        if (this.field !== "" || this.row.length > 0) {
+        if (this.recordStarted) {
             this.row.push(this.field);
             this.onRow(this.row);
             this.field = "";
             this.row = [];
+            this.recordStarted = false;
         }
     }
 }
@@ -1165,6 +1178,17 @@ function importCSVInMemory(pmRoot, filePath, opts) {
     processImportRows(pmRoot, dataRows, resolvedHeaders.headers, opts, result);
     return result;
 }
+/** Import an already captured table through the existing mapping, upsert and mutation core.
+ * Callers own structural/strict validation; this entry never rereads a mutable input file.
+ */
+export function importParsedCSV(pmRoot, table, opts) {
+    const resolved = resolveImportHeaders(table[0], opts);
+    const result = createImportResult();
+    result.fieldMapWarnings = resolved.fieldMapWarnings;
+    result.autoMappings = resolved.autoMappings;
+    processImportRows(pmRoot, table.slice(1), resolved.headers, opts, result);
+    return result;
+}
 // ---------------------------------------------------------------------------
 // Atomic import (pm-cli >= 2026.7.19 commitWorkspaceTransaction)
 // ---------------------------------------------------------------------------
@@ -1220,7 +1244,8 @@ function atomicStepId(rowIndex, existingId) {
  * Recover the original plan's update targets and create roles from SDK journal
  * step identities. Mutable CSV key tags cannot retarget an interrupted update
  * or turn a previously planned create into an update. Incompatible identities
- * refuse replay before any mutation; the SDK validates the remaining journal.
+ * refuse replay before any mutation. Check the journal's schema and transaction
+ * identity before trusting its bindings; the SDK validates the remaining journal.
  * The public read-only inventory supplies the path, including after SDK layout
  * changes. Infinite retention and dry-run prevent recovery receipts being pruned.
  */
@@ -1234,13 +1259,17 @@ async function loadAtomicBindings(pmRoot, transactionId) {
     if (journal === null || typeof journal !== "object" || Array.isArray(journal)
         || !("stepIds" in journal) || !Array.isArray(journal.stepIds)
         || !journal.stepIds.every((id) => typeof id === "string")) {
-        throw new Error(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
+        throw new CommandError(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
+    }
+    if (!("schemaVersion" in journal) || journal.schemaVersion !== 1
+        || !("transactionId" in journal) || journal.transactionId !== transactionId) {
+        throw new CommandError(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV journal identity. Refusing before transaction coordination.`);
     }
     const pattern = new RegExp(String.raw `^csv-import-v${UPDATE_COMPENSATION_VERSION}-(?:create|update-(.+))-row-(\d+)$`);
     for (const id of journal.stepIds) {
         const match = pattern.exec(id);
         if (!match)
-            throw new Error(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
+            throw new CommandError(`Workspace transaction ${transactionId} journal does not match the supplied plan: incompatible CSV step identity.`);
         bindings.set(Number(match[2]), match[1]);
     }
     return bindings;
@@ -2323,8 +2352,9 @@ function prepareCsvExport(pmRoot, rawOptions) {
 }
 export default {
     name: "pm-csv",
-    version: "2026.10.22",
+    version: "2026.10.24",
     activate(api) {
+        registerTableSchemaCommands(api);
         // -----------------------------------------------------------------------
         // Schema: register an optional `csv_source` provenance field so imported
         // items can record where they came from (set via `pm csv import --source`).
@@ -2335,6 +2365,105 @@ export default {
         api.registerItemFields([
             { name: "csv_source", type: "string", optional: true },
         ]);
+        api.registerCommand({
+            name: "csv bundle",
+            description: "Import with portable cell lineage and a minimal rejected-row retry CSV (maximum 1000 rows).",
+            arguments: [{ name: "file", required: true, description: "UTF-8 CSV input" }],
+            flags: [
+                { long: "--output", value_name: "directory", description: "New private bundle directory" },
+                { long: "--columns", value_name: "fields", description: "Explicit permitted import and diagnostic fields, including title" },
+                { long: "--map", value_name: "mapping", description: "Source=target pairs, for example Summary=title" },
+            ],
+            async run(ctx) {
+                const output = ctx.options["output"];
+                const columns = ctx.options["columns"];
+                if (!output || !columns || !ctx.args[0])
+                    throw new LineageRefusal("csv_lineage_invalid", "Provide input.csv --output new-bundle --columns title,priority; only explicitly selected fields can be imported or exported.");
+                let table;
+                try {
+                    table = parseCSV(stripBOM(readFileSync(ctx.args[0], "utf8")));
+                    mkdirSync(output, { mode: 0o700 });
+                }
+                catch {
+                    throw new LineageRefusal("csv_bundle_io", "Provide readable UTF-8 input and a new writable output directory; existing bundles are preserved.");
+                }
+                let fieldMap;
+                try {
+                    const parsed = parseFieldMap(ctx.options["map"]);
+                    fieldMap = Object.fromEntries(Object.entries(parsed).map(([header, field]) => [
+                        table[0]?.find(source => source.trim().toLowerCase() === header) ?? header, field,
+                    ]));
+                }
+                catch {
+                    throw new LineageRefusal("csv_lineage_invalid", "Use --map Source=title,Rank=priority; map only permitted fields.");
+                }
+                const bundle = await importLineage(ctx.pm_root, table, {
+                    columns: columns.split(",").map(field => field.trim()),
+                    fieldMap,
+                    author: ctx.global["author"] ?? "pm-csv",
+                });
+                writeLineageBundle(output, bundle);
+                return bundle.receipt;
+            },
+        });
+        api.registerCommand({
+            name: "csv checkout",
+            description: "Export a conflict-aware CSV edit session and immutable baseline JSON (maximum 1000 items).",
+            flags: [
+                { long: "--output", value_name: "file", description: "New CSV filename; baseline uses <file>.session.json" },
+                { long: "--ids", value_name: "ids", description: "Comma-separated canonical item IDs (default: complete tracker)" },
+            ],
+            async run(ctx) {
+                const output = ctx.options["output"];
+                if (!output)
+                    throw new EditRefusal("csv_edit_invalid", "Provide --output items.csv; retain items.csv.session.json alongside the CSV.");
+                const selection = ctx.options["ids"];
+                const ids = selection ? selection.split(",").map(id => id.trim())
+                    : parseCSV(buildCsvExport(ctx.pm_root, { delimiter: ",", columns: ["id"] }).csvText).slice(1).map(row => row[0]);
+                const { session, table } = await exportEditSession(ctx.pm_root, ids);
+                // Exclusive creation prevents accidental replacement of an earlier edit session.
+                try {
+                    writeFileSync(`${output}.session.json`, JSON.stringify(session), { encoding: "utf8", flag: "wx", mode: 0o600 });
+                    writeFileSync(output, serializeCSV(table, ",") + "\n", { encoding: "utf8", flag: "wx", mode: 0o600 });
+                }
+                catch (error) {
+                    const refusal = new EditRefusal("csv_edit_invalid", "Use new writable checkout filenames. Existing files were preserved; an incomplete new baseline may remain if CSV creation failed.");
+                    refusal.cause = error;
+                    throw refusal;
+                }
+                return { exported: session.rows.length, session: session.digest };
+            },
+        });
+        api.registerCommand({
+            name: "csv apply",
+            description: "Apply an edited checkout as a three-way patch; conflicts refuse before application.",
+            arguments: [{ name: "file", required: true, description: "Edited checkout CSV" }],
+            flags: [
+                { long: "--session", value_name: "file", description: "Baseline JSON (default: <file>.session.json)" },
+                { long: "--dry-run", description: "Read-only conflict check and compact patch counts" },
+            ],
+            async run(ctx) {
+                const file = ctx.args[0];
+                if (!file)
+                    throw new EditRefusal("csv_edit_invalid", "Provide the edited CSV filename.");
+                const baseline = ctx.options["session"] ?? `${file}.session.json`;
+                let session;
+                let text;
+                try {
+                    session = JSON.parse(readFileSync(baseline, "utf8"));
+                    text = stripBOM(readFileSync(file, "utf8"));
+                }
+                catch (error) {
+                    const refusal = new EditRefusal("csv_session_invalid", "Provide a readable CSV and the unchanged checkout session JSON.");
+                    refusal.cause = error;
+                    throw refusal;
+                }
+                return { ...await applyEditSession(ctx.pm_root, session, parseCSV(text), {
+                        author: ctx.global["author"] ?? "pm-csv",
+                        dryRun: readBoolOption(ctx.options, "dry-run", "dryRun"),
+                    }) };
+            },
+        });
         // -----------------------------------------------------------------------
         // Command: pm csv import <file>
         // -----------------------------------------------------------------------
@@ -2598,7 +2727,7 @@ export default {
 // ---------------------------------------------------------------------------
 // Named exports — pure helpers exposed for unit testing (no side effects).
 // ---------------------------------------------------------------------------
-export { parseCSV, serializeCSV, serializeField, stripBOM, resolveDelimiter, parseFieldMap, resolveImportFieldMap, applyFieldMap, normalizeStatus, parseTags, stringifyTags, encodeKeyTagValue, decodeKeyTagValue, errorMessage, normalizeKeyValue, selectExportColumns, resolveEncoding, validateParsedCSV, validateCSV, strictValidationIssues, parseImportFilter, rowMatchesFilter, discoverCustomFields, EXPORT_COLUMNS, IMPORT_COLUMNS, StreamingCSVParser, streamCSVFile, levenshtein, suggestClosest, validateFieldMapTargets, checkMapSourcesPresent, };
+export { parseCSV, readBoolOption, serializeCSV, serializeField, stripBOM, resolveDelimiter, parseFieldMap, resolveImportFieldMap, applyFieldMap, normalizeStatus, parseTags, stringifyTags, encodeKeyTagValue, decodeKeyTagValue, errorMessage, normalizeKeyValue, selectExportColumns, resolveEncoding, validateParsedCSV, validateCSV, strictValidationIssues, parseImportFilter, rowMatchesFilter, discoverCustomFields, EXPORT_COLUMNS, IMPORT_COLUMNS, StreamingCSVParser, streamCSVFile, levenshtein, suggestClosest, validateFieldMapTargets, checkMapSourcesPresent, };
 // ---------------------------------------------------------------------------
 // Internal store helpers exposed for regression testing against oversized pm
 // roots. Unlike the pure helpers above, these READ or WRITE the given pm root
@@ -2615,4 +2744,7 @@ export { loadAppliedByTransaction, itemStatus, compensateCreate };
 // ONLY for those tests; production callers keep using the command paths.
 export { loadKeyIndex, buildCsvExport };
 export { importCSV };
+export { applyEditSession, exportEditSession, parseEditSession, editSessionHeader, EDIT_FIELDS, EditRefusal } from "./roundtrip.js";
+export { importLineage, writeLineageBundle, lineageDigest, LINEAGE_FIELDS, LineageRefusal } from "./lineage.js";
+export { describeTable, previewTable, parseTableSchema, importNegotiatedTable, TableSchemaRefusal } from "./table-schema.js";
 //# sourceMappingURL=index.js.map