Support all .ms10..ms19 files + content-based format detection

The decoder was hardcoded to two extensions (.ewprj, .ms14) with the
matching headers baked into decode.ts. Replace that with a content-driven
approach: the file's magic bytes determine the format, so any compressed
EW file decodes regardless of filename.

- New `src/formats.ts` is the single source of truth: a `FORMATS` table
  with one entry per container variant (key, label, header, extension
  pattern), plus helpers (`detectFormatByHeader`, `formatForExtension`,
  `formatByKey`, `knownFormatsList`).
- `decode.ts` now reads the longest known header up front, identifies
  the format from the bytes, and rewinds the file position if the actual
  match is shorter than the read.
- `encode.ts`: `encode()` takes an options object with an optional
  `format` override; `headerFor` is kept as a thin wrapper for tests.
  `ewe` exposes the override as `--format <key>` (e.g. for renamed files
  or unconventional extensions).
- Coverage: Multisim 10 through 19 are recognized by extension; .ms13
  and .ms14 are content-verified, the rest are extrapolated. Out-of-range
  versions still work via `--format multisim`.

Verified end-to-end: decoded a real DanceDongle.ms13 (Multisim 13
schema 66) and round-tripped it byte-identical. 43 tests pass across
3 files, biome+tsc clean.

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

Author: cinderblock

README.md

@@ -2,15 +2,36 @@
 
 Two CLIs:
 
-- **`ewd`** — decode an EWB project (`.ewprj`, `.ms14`) into its underlying XML.
-- **`ewe`** — encode XML back into a `.ewprj`/`.ms14` the original software can re-open.
+- **`ewd`** — decode an EWB project into its underlying XML.
+- **`ewe`** — encode XML back into a compressed EWB file the original software can re-open.
 
-The container is a small header (`CompressedElectronicsWorkbenchXML` or
-`MSMCompressedElectronicsWorkbenchXML`), then a 64-bit little-endian total
-decompressed length, then a sequence of `(decompressed_length: u32, compressed_length: u32, pkware_implode_block)` sections. Compression is
+## Supported formats
+
+| Key        | Extension(s)          | Header                                  |
+| ---------- | --------------------- | --------------------------------------- |
+| `ewprj`    | `.ewprj`              | `CompressedElectronicsWorkbenchXML`     |
+| `multisim` | `.ms10` … `.ms19`     | `MSMCompressedElectronicsWorkbenchXML`  |
+
+`ewd` identifies the format by reading the magic bytes at the start of the
+file, so the filename extension can be anything (renamed files, no extension,
+`.dat`, etc. all decode correctly).
+
+`ewe` infers the format from the **output** filename's extension; pass
+`--format <key>` to override for non-standard extensions. Out-of-range
+Multisim versions (e.g. `.ms9` or future `.ms20+`) need an explicit
+`--format multisim`.
+
+The container is a small header, then a 64-bit little-endian total
+decompressed length, then a sequence of `(decompressed_length: u32,
+compressed_length: u32, pkware_implode_block)` sections. Compression is
 PKWare DCL Implode (ASCII literal mode, large dictionary). Multisim chunks
 big files into 900 000-decompressed-byte sections; `ewe` mirrors that.
 
+> Note: the `*.prj` / `*.usr` / `*.ldb` files that ship as part of NI's
+> "Electronics Workbench Database" are Microsoft Access (Jet) databases,
+> not the compressed-XML container described here. They aren't handled by
+> `ewd` / `ewe`.
+
 ## Install
 
 Requires [bun](https://bun.sh) (≥ 1.0).
@@ -39,16 +60,19 @@ Options:
 bun run ewe --verbose ./samples/Temp.ewprj.xml
 # or with explicit output:
 bun run ewe --output ./out.ewprj ./samples/Temp.ewprj.xml
+# or force a format on a non-standard extension:
+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 (`.ewprj` vs `.ms14`).
+path. Format is inferred from the output extension (see the table above).
 
 Options:
 
 - `-v`, `--verbose` — log per-section 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
 
 ### Compression ratio caveat
@@ -67,9 +91,10 @@ produces byte-identical XML, and the resulting files are accepted by
 bun test
 ```
 
-Covers unit tests for the encoder's filename helpers and round-trip
-integration tests (tiny `.ewprj`, tiny `.ms14`, multi-block payload that
-spans more than one PKWare section, and an empty payload).
+Covers the format registry (extension matching, header detection),
+encoder filename helpers, and round-trip integration tests (tiny
+`.ewprj`, tiny `.ms14`, multi-block payload that spans more than one
+PKWare section, and an empty payload).
 
 ## Development
 

src/decode.ts

@@ -2,6 +2,7 @@ import { promises as fs } from 'node:fs';
 import { Readable } from 'node:stream';
 import { explode, stream } from 'node-pkware';
 import type winston from 'winston';
+import { detectFormatByHeader, knownFormatsList, MAX_HEADER_LENGTH } from './formats';
 import { UnexpectedValue } from './util/UnexpectedValue';
 
 const { streamToBuffer, through } = stream;
@@ -22,18 +23,6 @@ async function decodeBlock(block: Buffer, expectedLength: number): Promise<Buffe
 export async function decode(filename: string, logger: winston.Logger, outFile = `${filename}.xml`): Promise<void> {
   if (!filename) throw new Error('No filename provided');
 
-  let expectedHeader: Buffer;
-
-  if (filename.endsWith('.ewprj')) {
-    logger.silly(`Opening EWPRJ: ${filename}`);
-    expectedHeader = Buffer.from('CompressedElectronicsWorkbenchXML');
-  } else if (filename.endsWith('.ms14')) {
-    logger.silly(`Opening MultiSIM: ${filename}`);
-    expectedHeader = Buffer.from('MSMCompressedElectronicsWorkbenchXML');
-  } else {
-    throw new Error(`I don't know how to parse: ${filename}`);
-  }
-
   const file = await fs.open(filename, 'r');
   let pos = 0;
 
@@ -78,15 +67,20 @@ export async function decode(filename: string, logger: winston.Logger, outFile =
     const outputFile = await fs.open(outFile, 'w');
 
     try {
-      const header = await read(expectedHeader.length);
-
-      logger.silly('Read header successfully');
-
-      if (!header.equals(expectedHeader)) {
-        throw new UnexpectedValue('File header does not match', expectedHeader, header);
+      const headerBuffer = await read(MAX_HEADER_LENGTH);
+      const format = detectFormatByHeader(headerBuffer);
+
+      if (!format) {
+        throw new UnexpectedValue(
+          `File header doesn't match any known EW format. Supported: ${knownFormatsList()}`,
+          `one of ${knownFormatsList()}`,
+          headerBuffer.toString('ascii'),
+        );
       }
 
-      logger.silly('Header matches as expected');
+      // Rewind past any bytes we read beyond the actual header length.
+      pos -= MAX_HEADER_LENGTH - format.header.length;
+      logger.silly(`Detected format: ${format.label}`);
 
       const finalLength = await readNumber(8);
 

src/encode.test.ts

@@ -1,35 +1,50 @@
 import { describe, expect, test } from 'bun:test';
 import { headerFor, inferOutFile } from './encode';
 
+const EWPRJ_HEADER = 'CompressedElectronicsWorkbenchXML';
+const MULTISIM_HEADER = 'MSMCompressedElectronicsWorkbenchXML';
+
 describe('headerFor', () => {
-  test('returns the .ewprj header for .ewprj filenames', () => {
-    expect(headerFor('foo.ewprj').toString('ascii')).toBe('CompressedElectronicsWorkbenchXML');
+  test('returns the EWPRJ header for .ewprj filenames', () => {
+    expect(headerFor('foo.ewprj').toString('ascii')).toBe(EWPRJ_HEADER);
   });
 
-  test('returns the .ms14 header for .ms14 filenames', () => {
-    expect(headerFor('foo.ms14').toString('ascii')).toBe('MSMCompressedElectronicsWorkbenchXML');
+  test.each([
+    'foo.ms10',
+    'foo.ms11',
+    'foo.ms12',
+    'foo.ms13',
+    'foo.ms14',
+    'foo.ms19',
+  ])('returns the Multisim header for %s', name => {
+    expect(headerFor(name).toString('ascii')).toBe(MULTISIM_HEADER);
   });
 
   test('throws on unknown extensions', () => {
-    expect(() => headerFor('foo.txt')).toThrow(/don't know what header/);
+    expect(() => headerFor('foo.txt')).toThrow(/Cannot infer format/);
     expect(() => headerFor('foo')).toThrow();
     expect(() => headerFor('foo.ewprj.bak')).toThrow();
   });
 
   test('matches the extension at the end, not anywhere', () => {
-    // these all end in .ewprj or .ms14
     expect(() => headerFor('something.ewprj')).not.toThrow();
     expect(() => headerFor('dir/sub.ms14')).not.toThrow();
-    // but these do not
     expect(() => headerFor('.ewprj.xml')).toThrow();
     expect(() => headerFor('.ms14.something')).toThrow();
   });
+
+  test('does not match Multisim versions outside the verified range', () => {
+    // .ms9 and .ms20+ aren't in the conservative pattern; user can pass --format multisim
+    expect(() => headerFor('foo.ms9')).toThrow();
+    expect(() => headerFor('foo.ms20')).toThrow();
+  });
 });
 
 describe('inferOutFile', () => {
   test('strips a trailing .xml', () => {
     expect(inferOutFile('foo.ewprj.xml')).toBe('foo.ewprj');
     expect(inferOutFile('bar.ms14.xml')).toBe('bar.ms14');
+    expect(inferOutFile('baz.ms10.xml')).toBe('baz.ms10');
   });
 
   test('handles paths with directories', () => {

src/encode.ts

@@ -2,6 +2,7 @@ import { promises as fs } from 'node:fs';
 import { Readable } from 'node:stream';
 import { constants, implode, stream } from 'node-pkware';
 import type winston from 'winston';
+import { type EwbFormat, formatForExtension, knownFormatsList } from './formats';
 
 const { COMPRESSION_ASCII, DICTIONARY_SIZE_LARGE } = constants;
 const { streamToBuffer, through } = stream;
@@ -25,33 +26,51 @@ function compressBlock(block: Buffer): Promise<Buffer> {
   });
 }
 
-export function headerFor(targetFilename: string): Buffer {
-  if (targetFilename.endsWith('.ewprj')) {
-    return Buffer.from('CompressedElectronicsWorkbenchXML');
-  }
-  if (targetFilename.endsWith('.ms14')) {
-    return Buffer.from('MSMCompressedElectronicsWorkbenchXML');
+/**
+ * Resolve the target format. Prefers an explicit `format` override; falls back
+ * to inferring from the output filename's extension.
+ */
+export function resolveFormat(targetFilename: string, override?: EwbFormat): EwbFormat {
+  if (override) return override;
+  const inferred = formatForExtension(targetFilename);
+  if (!inferred) {
+    throw new Error(
+      `Cannot infer format for "${targetFilename}". Pass an explicit format. Known: ${knownFormatsList()}.`,
+    );
   }
-  throw new Error(`I don't know what header to use for: ${targetFilename}`);
+  return inferred;
+}
+
+/** Backward-compatible helper: returns the magic header bytes for a target filename. */
+export function headerFor(targetFilename: string): Buffer {
+  return Buffer.from(resolveFormat(targetFilename).header, 'ascii');
 }
 
 export function inferOutFile(inFile: string): string {
   if (inFile.endsWith('.xml')) return inFile.slice(0, -'.xml'.length);
   throw new Error(`Cannot infer output filename from ${inFile}, pass --output`);
 }
 
-export async function encode(
-  inFile: string,
-  logger: winston.Logger,
-  outFile = inferOutFile(inFile),
-  blockSize = DEFAULT_BLOCK_SIZE,
-): Promise<void> {
+export interface EncodeOptions {
+  /** Output filename. Defaults to stripping a trailing `.xml` from `inFile`. */
+  outFile?: string;
+  /** Decompressed bytes per section. Defaults to `DEFAULT_BLOCK_SIZE`. */
+  blockSize?: number;
+  /** Force a specific output format. Overrides extension-based inference. */
+  format?: EwbFormat;
+}
+
+export async function encode(inFile: string, logger: winston.Logger, options: EncodeOptions = {}): Promise<void> {
   if (!inFile) throw new Error('No input filename provided');
+
+  const outFile = options.outFile ?? inferOutFile(inFile);
+  const blockSize = options.blockSize ?? DEFAULT_BLOCK_SIZE;
   if (blockSize <= 0) throw new RangeError('blockSize must be > 0');
 
-  const header = headerFor(outFile);
+  const format = resolveFormat(outFile, options.format);
+  const header = Buffer.from(format.header, 'ascii');
 
-  logger.verbose(`Encoding ${inFile} -> ${outFile}`);
+  logger.verbose(`Encoding ${inFile} -> ${outFile} as ${format.label}`);
 
   const xml = await fs.readFile(inFile);
   const totalLength = xml.length;

src/ewe.ts

@@ -1,16 +1,19 @@
 import commandLineArgs from 'command-line-args';
 import winston from 'winston';
 import { encode } from './encode';
+import { FORMATS, formatByKey, knownFormatsList } from './formats';
 
 export async function main() {
-  const { files, output, verbose, concurrent } = commandLineArgs([
+  const { files, output, format, verbose, concurrent } = commandLineArgs([
     { name: 'verbose', alias: 'v', type: Boolean },
     { name: 'concurrent', alias: 'c', type: Boolean },
     { name: 'output', alias: 'o', type: String },
+    { name: 'format', alias: 'f', type: String },
     { name: 'files', type: String, multiple: true, defaultOption: true },
   ]) as {
     files: string[];
     output?: string;
+    format?: string;
     verbose: boolean;
     concurrent: boolean;
   };
@@ -37,12 +40,26 @@ export async function main() {
     return;
   }
 
+  let resolvedFormat: ReturnType<typeof formatByKey>;
+  if (format) {
+    resolvedFormat = formatByKey(format);
+    if (!resolvedFormat) {
+      logger.error(
+        `Unknown --format "${format}". Known: ${FORMATS.map(f => f.key).join(', ')} (${knownFormatsList()})`,
+      );
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  const options = { outFile: output, format: resolvedFormat };
+
   if (concurrent) {
-    await Promise.all(files.map(f => encode(f, logger, output)));
+    await Promise.all(files.map(f => encode(f, logger, options)));
   } else {
     for (const f of files) {
       logger.info(`Next file: ${f}`);
-      await encode(f, logger, output);
+      await encode(f, logger, options);
     }
   }
 }