Support in-place edits to .prj component databases

Encodes the mdb half of the project: now that ewd writes a JSON for
.prj files, ewe accepts the (edited) JSON back and patches the
original .prj in-place.

Mechanism (per plans/jet-in-place-edit.md):

  - Diff the edited JSON's text/memo cell values against what mdb-reader
    reads from the original .prj.
  - For each change where the new value has the same byte length and
    the old value appears exactly once in the raw file, overwrite the
    bytes at that offset. Encoding is latin1 for Jet 3, UTF-16LE for
    Jet 4 (detected from the version byte at offset 0x14).
  - Anything that violates those constraints (length change, missing,
    ambiguous, non-text column) is skipped with a reason. The result
    summary lists `N applied, M skipped` and `--verbose` enumerates
    each skipped change.

Out of scope for this commit (documented in the plan file):

  - Row reflow / different-length text edits.
  - Numeric / date / OLE column edits.
  - Empty <-> non-empty changes.
  - Targeted (table, row, column) lookups when a value is ambiguous;
    today that's just skipped.

Verified end-to-end on a real Stocked.prj: changed a vendor part
number `WM10134CT-ND` -> `WMTESTING-ND` in the JSON, ran ewe, decoded
the patched .prj, and the new value reads back. 72 tests pass across
5 files; CI runs check / typecheck / test on Ubuntu and Windows.

ewe now recognizes `.json` inputs as the mdb edit path and routes the
existing `.xml` inputs through the compressed-xml encoder unchanged.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: cinderblock

README.md

@@ -55,12 +55,28 @@ Dates become ISO 8601 strings; binary blob fields (`ole` columns) become
 `{ "_bytes": "base64", "value": "..." }` envelopes so the data survives a
 JSON round-trip.
 
-**Encode (write-back) is not implemented yet.** Writing a valid Jet 3
-file from scratch would mean reimplementing Access's page/B-tree storage
-engine, which is a multi-month undertaking. The planned path is in-place
-edits only: read an existing `.prj`, change cell values that fit in the
-existing page layout, write back. That's tractable; a full Jet writer
-is not.
+**Encode is in-place-edit only.** Writing a valid Jet 3 file from
+scratch would mean reimplementing Access's page/B-tree storage engine,
+which is out of scope. Instead `ewe` patches an existing `.prj`:
+
+1. You decode with `ewd` to produce `<file>.prj.json`.
+2. You edit the JSON in your text editor (or with a script).
+3. You run `ewe edited.json` and `ewe` diffs the edited JSON against
+   the original `.prj`, then byte-patches each changed cell.
+
+Today's limits (each enforced by the encoder, with a clear "skipped"
+report when violated):
+
+- Only `text` and `memo` columns. Numeric / date / OLE edits are skipped.
+- New value must have the same byte length as the old value. Length
+  changes would require row reflow / free-space accounting (planned).
+- Old value must appear exactly once in the file. If it's ambiguous
+  (collides with another row) or missing, the change is skipped.
+
+These constraints cover the typical vendor / price / MPN editing
+workflow because those values are usually unique and you usually
+substitute one same-length identifier for another. The skipped list
+tells you exactly when they don't.
 
 ## Format detection
 
@@ -99,6 +115,8 @@ Options:
 
 ## Encode
 
+### Compressed-XML (greenfield encode from `.xml`)
+
 ```bash
 bun run ewe --verbose ./samples/Temp.ewprj.xml
 # or with explicit output:
@@ -110,16 +128,34 @@ bun run ewe --format multisim --output ./out.dat ./samples/Design1.ms14.xml
 By default, strips a trailing `.xml` from each input to derive the output
 path. Format is inferred from the output extension (see the table above).
 
-Options:
+### MDB in-place edits from `.json`
 
-- `-v`, `--verbose` — log per-section progress
+```bash
+# Decode first to produce the editable JSON.
+bun run ewd ./samples/Stocked.prj
+# Edit ./samples/Stocked.prj.json in your editor / script.
+# Then re-encode: ewe diffs vs the original and writes a patched copy.
+bun run ewe --verbose ./samples/Stocked.prj.json
+# -> samples/Stocked.prj.patched.prj
+```
+
+`ewe` recognizes `.json` inputs and routes them through the in-place
+edit path. The original `.prj` location is taken from the JSON's
+`source` field (or `--source <path>` to override). The patched copy
+goes to `<source>.patched.prj` (or `--output <path>` to override).
+
+Each `--verbose` run prints `N applied, M skipped` and lists every
+skipped change with its reason. Skipped changes leave the file
+untouched at that cell.
+
+### Options
+
+- `-v`, `--verbose` — log progress
 - `-c`, `--concurrent` — encode multiple files in parallel
 - `-o`, `--output <path>` — explicit output path (single-input only)
-- `-f`, `--format <key>` — force a format (`ewprj` or `multisim`)
-- positional args — XML files to encode
-
-Trying to encode an `mdb` target fails with a clear error until
-in-place-edit support lands.
+- `-s`, `--source <path>` — for MDB JSON inputs: override the source `.prj`
+- `-f`, `--format <key>` — for compressed-XML: force a format (`ewprj` or `multisim`)
+- positional args — XML or JSON files to encode
 
 ### Compression ratio caveat
 

src/encodeMdb.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from 'bun:test';
+import { applyChange, detectJetVersion, textEncodingForJet } from './encodeMdb';
+
+function jetHeader(versionByte: number): Buffer {
+  const buf = Buffer.alloc(64);
+  buf[0] = 0x00;
+  buf[1] = 0x01;
+  buf[2] = 0x00;
+  buf[3] = 0x00;
+  buf.write('Standard Jet DB', 4, 'latin1');
+  buf[0x14] = versionByte;
+  return buf;
+}
+
+describe('detectJetVersion', () => {
+  test('returns 3 for version byte 0x00', () => {
+    expect(detectJetVersion(jetHeader(0x00))).toBe(3);
+  });
+
+  test('returns 4 for version byte 0x01', () => {
+    expect(detectJetVersion(jetHeader(0x01))).toBe(4);
+  });
+
+  test('throws on an unrecognized version byte', () => {
+    expect(() => detectJetVersion(jetHeader(0x09))).toThrow(/Unknown Jet version/);
+  });
+});
+
+describe('textEncodingForJet', () => {
+  test('Jet 3 uses latin1', () => {
+    expect(textEncodingForJet(3)).toBe('latin1');
+  });
+
+  test('Jet 4 uses utf16le', () => {
+    expect(textEncodingForJet(4)).toBe('utf16le');
+  });
+});
+
+describe('applyChange', () => {
+  const change = (oldValue: string, newValue: string) => ({
+    table: 'T',
+    rowIndex: 0,
+    column: 'C',
+    oldValue,
+    newValue,
+  });
+
+  test('patches a unique same-length value in latin1', () => {
+    const buf = Buffer.from('prefix WM10134CT-ND suffix unique data', 'latin1');
+    const r = applyChange(buf, change('WM10134CT-ND', 'WMTESTING-ND'), 'latin1');
+    expect(r).toEqual({ ok: true, offset: 7 });
+    expect(buf.toString('latin1')).toBe('prefix WMTESTING-ND suffix unique data');
+  });
+
+  test('refuses when the byte length differs', () => {
+    const buf = Buffer.from('hello world', 'latin1');
+    const r = applyChange(buf, change('hello', 'hellos'), 'latin1');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/byte length differs/);
+    expect(buf.toString('latin1')).toBe('hello world'); // unchanged
+  });
+
+  test('refuses when the old value is missing', () => {
+    const buf = Buffer.from('hello world', 'latin1');
+    const r = applyChange(buf, change('absent', 'newval'), 'latin1');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/not present/);
+  });
+
+  test('refuses when the old value is ambiguous', () => {
+    const buf = Buffer.from('foo bar foo baz', 'latin1');
+    const r = applyChange(buf, change('foo', 'qux'), 'latin1');
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toMatch(/2 times/);
+    expect(buf.toString('latin1')).toBe('foo bar foo baz'); // unchanged
+  });
+
+  test('works with utf16le (Jet 4) encoding', () => {
+    const buf = Buffer.concat([
+      Buffer.from('prefix', 'latin1'),
+      Buffer.from('OldVal', 'utf16le'),
+      Buffer.from('suffix uniq', 'latin1'),
+    ]);
+    const r = applyChange(buf, change('OldVal', 'NewVal'), 'utf16le');
+    expect(r.ok).toBe(true);
+    if (r.ok) {
+      const patched = buf.subarray(r.offset, r.offset + 12).toString('utf16le');
+      expect(patched).toBe('NewVal');
+    }
+  });
+
+  test('only patches one occurrence (mutates buffer in place)', () => {
+    const original = Buffer.from('aaa unique12 bbb', 'latin1');
+    const buf = Buffer.from(original);
+    const r = applyChange(buf, change('unique12', 'changed!'), 'latin1');
+    expect(r.ok).toBe(true);
+    expect(buf.toString('latin1')).toBe('aaa changed! bbb');
+    expect(original.toString('latin1')).toBe('aaa unique12 bbb'); // original Buffer untouched
+  });
+});

src/encodeMdb.ts

@@ -0,0 +1,190 @@
+/**
+ * In-place edit support for NI EW component databases (Jet 3 / Jet 4).
+ *
+ * Reads an edited JSON (produced by `ewd`) alongside the original `.prj`,
+ * diffs cell values, and applies same-length byte patches to the original's
+ * raw bytes. The result is a modified copy of the original `.prj` that
+ * `mdb-reader` (and presumably Multisim) accept.
+ *
+ * Constraints for the first cut (per `plans/jet-in-place-edit.md`):
+ *
+ *   - Only `text` and `memo` columns are eligible. Numeric / date / OLE
+ *     edits are skipped silently — that's a planned future expansion.
+ *   - New value must have the same byte length as the old value (no
+ *     row reflow). Length-changing edits are skipped.
+ *   - Old value must appear exactly once in the raw file bytes. If it's
+ *     missing (already changed?) or ambiguous (repeats), the change is
+ *     skipped with a reason.
+ *
+ * Anything skipped is reported so the caller can decide what to do. The
+ * "applied" + "skipped" breakdown is the primary return value.
+ */
+
+import { promises as fs } from 'node:fs';
+import MDBReader from 'mdb-reader';
+import type winston from 'winston';
+import { type MdbJson, normalizeValue } from './decodeMdb';
+
+export interface CellChange {
+  table: string;
+  rowIndex: number;
+  column: string;
+  oldValue: string;
+  newValue: string;
+}
+
+export interface SkippedChange {
+  change: CellChange;
+  reason: string;
+}
+
+export interface PatchResult {
+  applied: CellChange[];
+  skipped: SkippedChange[];
+  outFile: string;
+}
+
+type JetVersion = 3 | 4;
+type JetTextEncoding = 'latin1' | 'utf16le';
+
+export function detectJetVersion(buffer: Buffer): JetVersion {
+  const v = buffer[0x14];
+  if (v === 0x00) return 3;
+  if (v === 0x01) return 4;
+  throw new Error(`Unknown Jet version byte at offset 0x14: 0x${v?.toString(16) ?? '??'}`);
+}
+
+export function textEncodingForJet(version: JetVersion): JetTextEncoding {
+  return version === 3 ? 'latin1' : 'utf16le';
+}
+
+function isEditableTextType(type: string): boolean {
+  return type === 'text' || type === 'memo';
+}
+
+/** Compute the cell-level diff between an edited JSON and the original DB bytes. */
+export function diffMdbAgainstOriginal(edited: MdbJson, originalBuffer: Buffer): CellChange[] {
+  const db = new MDBReader(originalBuffer);
+  const originalTables = new Set(db.getTableNames());
+  const changes: CellChange[] = [];
+
+  for (const [tableName, tableJson] of Object.entries(edited.tables)) {
+    if (!originalTables.has(tableName)) continue;
+
+    const editableColumns = new Set(tableJson.columns.filter(c => isEditableTextType(c.type)).map(c => c.name));
+    if (editableColumns.size === 0) continue;
+
+    const origRows = db.getTable(tableName).getData() as Record<string, unknown>[];
+
+    for (let i = 0; i < tableJson.rows.length; i++) {
+      const editedRow = tableJson.rows[i];
+      const origRow = origRows[i];
+      if (!origRow) continue;
+
+      for (const col of editableColumns) {
+        const newVal = editedRow[col];
+        const oldNormalized = normalizeValue(origRow[col]);
+        if (newVal === oldNormalized) continue;
+        if (typeof newVal !== 'string' || typeof oldNormalized !== 'string') continue;
+        if (newVal === '' || oldNormalized === '') continue; // empty<->non-empty needs row reflow
+        changes.push({
+          table: tableName,
+          rowIndex: i,
+          column: col,
+          oldValue: oldNormalized,
+          newValue: newVal,
+        });
+      }
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Apply a single change to `buffer` in place. Returns the offset that was
+ * patched on success, or a reason string on failure. The buffer is mutated.
+ */
+export function applyChange(
+  buffer: Buffer,
+  change: CellChange,
+  encoding: JetTextEncoding,
+): { ok: true; offset: number } | { ok: false; reason: string } {
+  const oldBytes = Buffer.from(change.oldValue, encoding);
+  const newBytes = Buffer.from(change.newValue, encoding);
+
+  if (oldBytes.length !== newBytes.length) {
+    return { ok: false, reason: `byte length differs (${oldBytes.length} -> ${newBytes.length})` };
+  }
+
+  const offsets: number[] = [];
+  let from = 0;
+  for (;;) {
+    const i = buffer.indexOf(oldBytes, from);
+    if (i === -1) break;
+    offsets.push(i);
+    from = i + 1;
+  }
+
+  if (offsets.length === 0) return { ok: false, reason: 'old value not present in raw bytes' };
+  if (offsets.length > 1) return { ok: false, reason: `old value appears ${offsets.length} times (ambiguous)` };
+
+  newBytes.copy(buffer, offsets[0]);
+  return { ok: true, offset: offsets[0] };
+}
+
+export interface EncodeMdbOptions {
+  /** Source `.prj` to use as the template. Defaults to the JSON's `source` field. */
+  source?: string;
+  /** Output path for the patched file. Defaults to `<source>.patched.prj`. */
+  outFile?: string;
+}
+
+export async function encodeMdb(
+  editedJsonPath: string,
+  logger: winston.Logger,
+  options: EncodeMdbOptions = {},
+): Promise<PatchResult> {
+  const editedJson = JSON.parse(await fs.readFile(editedJsonPath, 'utf8')) as MdbJson;
+
+  if (editedJson.format !== 'mdb') {
+    throw new Error(`Expected an mdb JSON document, got format=${String(editedJson.format)}`);
+  }
+
+  const sourcePath = options.source ?? editedJson.source;
+  if (!sourcePath) {
+    throw new Error('No --source given and the JSON has no "source" field; cannot locate the template .prj.');
+  }
+
+  const outFile = options.outFile ?? `${sourcePath}.patched.prj`;
+
+  logger.verbose(`Loading template ${sourcePath}`);
+  const originalReadOnly = await fs.readFile(sourcePath);
+  const jetVersion = detectJetVersion(originalReadOnly);
+  const encoding = textEncodingForJet(jetVersion);
+  logger.silly(`Jet version ${jetVersion}, text encoding ${encoding}`);
+
+  const changes = diffMdbAgainstOriginal(editedJson, originalReadOnly);
+  logger.verbose(`Diff: ${changes.length} candidate cell change${changes.length === 1 ? '' : 's'}`);
+
+  const buffer = Buffer.from(originalReadOnly); // independent mutable copy
+  const result: PatchResult = { applied: [], skipped: [], outFile };
+
+  for (const change of changes) {
+    const r = applyChange(buffer, change, encoding);
+    if (r.ok) {
+      logger.silly(`patched ${change.table}[${change.rowIndex}].${change.column} @ ${r.offset}`);
+      result.applied.push(change);
+    } else {
+      logger.silly(`skipped ${change.table}[${change.rowIndex}].${change.column}: ${r.reason}`);
+      result.skipped.push({ change, reason: r.reason });
+    }
+  }
+
+  await fs.writeFile(outFile, buffer);
+  logger.verbose(
+    `Wrote ${outFile}: ${result.applied.length} applied, ${result.skipped.length} skipped, ${changes.length} total candidates`,
+  );
+
+  return result;
+}