cffs-image-tool 1.0.0

package/dist/lib/operations.js

@@ -0,0 +1,161 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { SECTOR_SIZE, FLAG_USED, DATA_START } from './constants.js';
+import { parseName, formatName } from './filename.js';
+import { writeSector } from './image.js';
+import { readDirectory, writeDirectory, findFile, findFreeSlot, calcNextSector, calcSectorCount, } from './directory.js';
+/**
+ * Add a host file to the image. Optionally rename with targetName (8.3 format).
+ */
+export function addFile(buf, hostPath, targetName) {
+    const data = readFileSync(hostPath);
+    if (data.length > 0xFFFF) {
+        throw new Error(`File too large: ${data.length} bytes (max 65535)`);
+    }
+    const nameInput = targetName ?? basename(hostPath);
+    const { name, ext } = parseName(nameInput);
+    const entries = readDirectory(buf);
+    // If file with same name exists, clear old entry (overwrite behavior matches BIOS FsSaveFile)
+    const existing = findFile(entries, name, ext);
+    if (existing) {
+        existing.flags = 0;
+    }
+    const slotIndex = findFreeSlot(entries);
+    if (slotIndex === -1) {
+        throw new Error('Directory is full (16 entries maximum)');
+    }
+    // Recalculate next sector after potentially clearing old entry
+    const startSector = calcNextSector(entries);
+    // Check that the file data fits in the image
+    const sectorCount = calcSectorCount(data.length);
+    const endByte = (startSector + sectorCount) * SECTOR_SIZE;
+    if (endByte > buf.length) {
+        throw new Error(`Not enough space in image: need sector ${startSector + sectorCount - 1}, image has ${buf.length / SECTOR_SIZE} sectors`);
+    }
+    // Write file data to sectors
+    for (let i = 0; i < sectorCount; i++) {
+        const chunk = Buffer.alloc(SECTOR_SIZE);
+        const srcOffset = i * SECTOR_SIZE;
+        const remaining = Math.min(SECTOR_SIZE, data.length - srcOffset);
+        if (remaining > 0) {
+            data.copy(chunk, 0, srcOffset, srcOffset + remaining);
+        }
+        writeSector(buf, startSector + i, chunk);
+    }
+    // Update directory entry
+    entries[slotIndex] = {
+        name,
+        ext,
+        flags: FLAG_USED,
+        startSector,
+        fileSize: data.length,
+        index: slotIndex,
+    };
+    writeDirectory(buf, entries);
+}
+/**
+ * Remove a file by name (clears flags only, no compaction — matches BIOS FsDeleteFile).
+ */
+export function removeFile(buf, nameInput) {
+    const { name, ext } = parseName(nameInput);
+    const entries = readDirectory(buf);
+    const entry = findFile(entries, name, ext);
+    if (!entry) {
+        throw new Error(`File not found: ${nameInput}`);
+    }
+    entry.flags = 0;
+    writeDirectory(buf, entries);
+}
+/**
+ * List all in-use directory entries.
+ */
+export function listFiles(buf) {
+    return readDirectory(buf).filter((e) => (e.flags & FLAG_USED) !== 0);
+}
+/**
+ * Extract a file from the image to the host filesystem.
+ */
+export function extractFile(buf, nameInput, outputPath) {
+    const { name, ext } = parseName(nameInput);
+    const entries = readDirectory(buf);
+    const entry = findFile(entries, name, ext);
+    if (!entry) {
+        throw new Error(`File not found: ${nameInput}`);
+    }
+    const sectorCount = calcSectorCount(entry.fileSize);
+    const output = Buffer.alloc(entry.fileSize);
+    for (let i = 0; i < sectorCount; i++) {
+        const offset = (entry.startSector + i) * SECTOR_SIZE;
+        const srcSlice = buf.subarray(offset, offset + SECTOR_SIZE);
+        const dstOffset = i * SECTOR_SIZE;
+        const remaining = Math.min(SECTOR_SIZE, entry.fileSize - dstOffset);
+        srcSlice.copy(output, dstOffset, 0, remaining);
+    }
+    const outPath = outputPath ?? formatName(entry);
+    writeFileSync(outPath, output);
+}
+/**
+ * Defragment the image: sort used entries by startSector, rewrite contiguously from LBA 1.
+ */
+export function defragment(buf) {
+    const entries = readDirectory(buf);
+    const usedEntries = entries
+        .filter((e) => (e.flags & FLAG_USED) !== 0)
+        .sort((a, b) => a.startSector - b.startSector);
+    let currentSector = DATA_START;
+    for (const entry of usedEntries) {
+        const sectorCount = calcSectorCount(entry.fileSize);
+        // Only move if not already in the right spot
+        if (entry.startSector !== currentSector) {
+            // Read file data from current location
+            const fileData = Buffer.alloc(sectorCount * SECTOR_SIZE);
+            for (let i = 0; i < sectorCount; i++) {
+                const srcOffset = (entry.startSector + i) * SECTOR_SIZE;
+                buf.copy(fileData, i * SECTOR_SIZE, srcOffset, srcOffset + SECTOR_SIZE);
+            }
+            // Write to new location
+            for (let i = 0; i < sectorCount; i++) {
+                const chunk = fileData.subarray(i * SECTOR_SIZE, (i + 1) * SECTOR_SIZE);
+                writeSector(buf, currentSector + i, chunk);
+            }
+            entry.startSector = currentSector;
+        }
+        currentSector += sectorCount;
+    }
+    // Zero out any sectors after the last used file (reclaim space)
+    const totalSectors = buf.length / SECTOR_SIZE;
+    for (let s = currentSector; s < totalSectors; s++) {
+        buf.fill(0, s * SECTOR_SIZE, (s + 1) * SECTOR_SIZE);
+    }
+    // Write updated directory
+    writeDirectory(buf, entries);
+}
+/**
+ * Clear all directory entries (zero the directory sector).
+ */
+export function clearImage(buf) {
+    const sector = Buffer.alloc(SECTOR_SIZE);
+    writeSector(buf, 0, sector);
+}
+/**
+ * Return image stats.
+ */
+export function imageInfo(buf) {
+    const entries = readDirectory(buf);
+    const usedEntries = entries.filter((e) => (e.flags & FLAG_USED) !== 0);
+    const nextFreeSector = calcNextSector(entries);
+    const totalSectors = buf.length / SECTOR_SIZE;
+    let usedDataSectors = 0;
+    for (const e of usedEntries) {
+        usedDataSectors += calcSectorCount(e.fileSize);
+    }
+    return {
+        totalSectors,
+        usedEntries: usedEntries.length,
+        freeEntries: entries.length - usedEntries.length,
+        nextFreeSector,
+        usedDataSectors,
+        freeDataSectors: totalSectors - 1 - usedDataSectors, // -1 for directory sector
+    };
+}
+//# sourceMappingURL=operations.js.map

package/dist/lib/operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../src/lib/operations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EACL,aAAa,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EACrD,cAAc,EAAE,eAAe,GAChC,MAAM,gBAAgB,CAAC;AAExB;;GAEG;AACH,MAAM,UAAU,OAAO,CAAC,GAAW,EAAE,QAAgB,EAAE,UAAmB;IACxE,MAAM,IAAI,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAEpC,IAAI,IAAI,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,CAAC,MAAM,oBAAoB,CAAC,CAAC;IACtE,CAAC;IAED,MAAM,SAAS,GAAG,UAAU,IAAI,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAE3C,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IAEnC,8FAA8F;IAC9F,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAC9C,IAAI,QAAQ,EAAE,CAAC;QACb,QAAQ,CAAC,KAAK,GAAG,CAAC,CAAC;IACrB,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,SAAS,KAAK,CAAC,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;IAC5D,CAAC;IAED,+DAA+D;IAC/D,MAAM,WAAW,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAE5C,6CAA6C;IAC7C,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,CAAC,WAAW,GAAG,WAAW,CAAC,GAAG,WAAW,CAAC;IAC1D,IAAI,OAAO,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,0CAA0C,WAAW,GAAG,WAAW,GAAG,CAAC,eAAe,GAAG,CAAC,MAAM,GAAG,WAAW,UAAU,CAAC,CAAC;IAC5I,CAAC;IAED,6BAA6B;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QACxC,MAAM,SAAS,GAAG,CAAC,GAAG,WAAW,CAAC;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;QACjE,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC,CAAC;QACxD,CAAC;QACD,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,yBAAyB;IACzB,OAAO,CAAC,SAAS,CAAC,GAAG;QACnB,IAAI;QACJ,GAAG;QACH,KAAK,EAAE,SAAS;QAChB,WAAW;QACX,QAAQ,EAAE,IAAI,CAAC,MAAM;QACrB,KAAK,EAAE,SAAS;KACjB,CAAC;IAEF,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,SAAiB;IACvD,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAE3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,mBAAmB,SAAS,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC;IAChB,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,OAAO,aAAa,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,SAAiB,EAAE,UAAmB;IAC7E,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;IAE3C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CAAC,mBAAmB,SAAS,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACpD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAE5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC;QACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAAC,CAAC;QAC5D,MAAM,SAAS,GAAG,CAAC,GAAG,WAAW,CAAC;QAClC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;QACpE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC;IAChD,aAAa,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AACjC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,WAAW,GAAG,OAAO;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;SAC1C,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC;IAEjD,IAAI,aAAa,GAAG,UAAU,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;QAChC,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAEpD,6CAA6C;QAC7C,IAAI,KAAK,CAAC,WAAW,KAAK,aAAa,EAAE,CAAC;YACxC,uCAAuC;YACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,GAAG,WAAW,CAAC,CAAC;YACzD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,MAAM,SAAS,GAAG,CAAC,KAAK,CAAC,WAAW,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC;gBACxD,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,GAAG,WAAW,EAAE,SAAS,EAAE,SAAS,GAAG,WAAW,CAAC,CAAC;YAC1E,CAAC;YAED,wBAAwB;YACxB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,GAAG,WAAW,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;gBACxE,WAAW,CAAC,GAAG,EAAE,aAAa,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YAC7C,CAAC;YAED,KAAK,CAAC,WAAW,GAAG,aAAa,CAAC;QACpC,CAAC;QAED,aAAa,IAAI,WAAW,CAAC;IAC/B,CAAC;IAED,gEAAgE;IAChE,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;IAC9C,KAAK,IAAI,CAAC,GAAG,aAAa,EAAE,CAAC,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;QAClD,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC;IACtD,CAAC;IAED,0BAA0B;IAC1B,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACzC,WAAW,CAAC,GAAG,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,GAAW;IAQnC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;IACvE,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,GAAG,CAAC,MAAM,GAAG,WAAW,CAAC;IAE9C,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE,CAAC;QAC5B,eAAe,IAAI,eAAe,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;IACjD,CAAC;IAED,OAAO;QACL,YAAY;QACZ,WAAW,EAAE,WAAW,CAAC,MAAM;QAC/B,WAAW,EAAE,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM;QAChD,cAAc;QACd,eAAe;QACf,eAAe,EAAE,YAAY,GAAG,CAAC,GAAG,eAAe,EAAE,0BAA0B;KAChF,CAAC;AACJ,CAAC"}

package/dist/lib/types.d.ts

@@ -0,0 +1,8 @@
+export interface DirEntry {
+    name: string;
+    ext: string;
+    flags: number;
+    startSector: number;
+    fileSize: number;
+    index: number;
+}

package/dist/lib/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "cffs-image-tool",
+  "version": "1.0.0",
+  "description": "CompactFlash Filesystem Image Tool for A.C. Wright 6502 Project",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "cffs": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "start": "node dist/cli.js"
+  },
+  "keywords": ["6502", "compactflash", "filesystem"],
+  "author": "A.C. Wright",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acwright/cffs.git"
+  },
+  "homepage": "https://github.com/acwright/cffs",
+  "dependencies": {
+    "commander": "^14.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { openImage, saveImage, createImage } from './lib/image.js';
+import { formatName } from './lib/filename.js';
+import { calcSectorCount } from './lib/directory.js';
+import {
+  addFile, removeFile, listFiles, extractFile,
+  defragment, clearImage, imageInfo,
+} from './lib/operations.js';
+
+const program = new Command();
+
+program
+  .name('cffs')
+  .description('CompactFlash Filesystem Image Tool for A.C. Wright 6502 Project')
+  .version('1.0.0');
+
+/**
+ * Parse a size string like "32M", "512K", "1G", or a plain number (bytes).
+ */
+function parseSize(value: string): number {
+  const match = value.match(/^(\d+)\s*([KMGkmg])?[Bb]?$/);
+  if (!match) {
+    throw new Error(`Invalid size format: "${value}". Use e.g. 32M, 512K, or bytes.`);
+  }
+  const num = parseInt(match[1], 10);
+  const unit = (match[2] ?? '').toUpperCase();
+  switch (unit) {
+    case 'K': return num * 1024;
+    case 'M': return num * 1024 * 1024;
+    case 'G': return num * 1024 * 1024 * 1024;
+    default: return num;
+  }
+}
+
+// ── create ──────────────────────────────────────────────────────────────────
+program
+  .command('create')
+  .description('Create a blank CompactFlash image')
+  .argument('<image>', 'Path to image file to create')
+  .option('-s, --size <size>', 'Image size (e.g. 32M, 512K)', '32M')
+  .action((image: string, opts: { size: string }) => {
+    const totalBytes = parseSize(opts.size);
+    if (totalBytes % 512 !== 0) {
+      console.error('Error: size must be a multiple of 512 bytes');
+      process.exit(1);
+    }
+    const totalSectors = totalBytes / 512;
+    const buf = createImage(totalSectors);
+    saveImage(image, buf);
+    console.log(`Created ${image} (${totalBytes.toLocaleString()} bytes, ${totalSectors.toLocaleString()} sectors)`);
+  });
+
+// ── list ────────────────────────────────────────────────────────────────────
+program
+  .command('list')
+  .description('List files in the image')
+  .argument('<image>', 'Path to image file')
+  .action((image: string) => {
+    const buf = openImage(image);
+    const files = listFiles(buf);
+
+    if (files.length === 0) {
+      console.log('No files in image.');
+      return;
+    }
+
+    console.log('Name          Size     Start  Sectors');
+    console.log('────────────  ───────  ─────  ───────');
+    for (const f of files) {
+      const display = formatName(f).padEnd(12);
+      const size = f.fileSize.toString().padStart(7);
+      const start = f.startSector.toString().padStart(5);
+      const sectors = calcSectorCount(f.fileSize).toString().padStart(7);
+      console.log(`${display}  ${size}  ${start}  ${sectors}`);
+    }
+  });
+
+// ── add ─────────────────────────────────────────────────────────────────────
+program
+  .command('add')
+  .description('Add a host file to the image')
+  .argument('<image>', 'Path to image file')
+  .argument('<file>', 'Host file to add')
+  .option('-n, --name <name>', 'Target 8.3 filename (default: source filename)')
+  .action((image: string, file: string, opts: { name?: string }) => {
+    const buf = openImage(image);
+    addFile(buf, file, opts.name);
+    saveImage(image, buf);
+    console.log(`Added ${opts.name ?? file} to ${image}`);
+  });
+
+// ── remove ──────────────────────────────────────────────────────────────────
+program
+  .command('remove')
+  .description('Delete a file entry from the image')
+  .argument('<image>', 'Path to image file')
+  .argument('<name>', 'Filename to remove (8.3 format)')
+  .action((image: string, name: string) => {
+    const buf = openImage(image);
+    removeFile(buf, name);
+    saveImage(image, buf);
+    console.log(`Removed ${name} from ${image}`);
+  });
+
+// ── extract ─────────────────────────────────────────────────────────────────
+program
+  .command('extract')
+  .description('Extract a file from the image to the host filesystem')
+  .argument('<image>', 'Path to image file')
+  .argument('<name>', 'Filename to extract (8.3 format)')
+  .argument('[output]', 'Output path (default: original filename)')
+  .action((image: string, name: string, output?: string) => {
+    const buf = openImage(image);
+    extractFile(buf, name, output);
+    console.log(`Extracted ${name} from ${image}`);
+  });
+
+// ── defrag ──────────────────────────────────────────────────────────────────
+program
+  .command('defrag')
+  .description('Defragment the image (compact files)')
+  .argument('<image>', 'Path to image file')
+  .action((image: string) => {
+    const buf = openImage(image);
+    defragment(buf);
+    saveImage(image, buf);
+    console.log(`Defragmented ${image}`);
+  });
+
+// ── clear ───────────────────────────────────────────────────────────────────
+program
+  .command('clear')
+  .description('Clear all directory entries')
+  .argument('<image>', 'Path to image file')
+  .option('-y, --yes', 'Skip confirmation prompt')
+  .action(async (image: string, opts: { yes?: boolean }) => {
+    if (!opts.yes) {
+      const rl = createInterface({ input: stdin, output: stdout });
+      const answer = await rl.question(`Clear all entries in ${image}? [y/N] `);
+      rl.close();
+      if (answer.toLowerCase() !== 'y') {
+        console.log('Aborted.');
+        return;
+      }
+    }
+    const buf = openImage(image);
+    clearImage(buf);
+    saveImage(image, buf);
+    console.log(`Cleared all directory entries in ${image}`);
+  });
+
+// ── info ────────────────────────────────────────────────────────────────────
+program
+  .command('info')
+  .description('Display image statistics')
+  .argument('<image>', 'Path to image file')
+  .action((image: string) => {
+    const buf = openImage(image);
+    const info = imageInfo(buf);
+    console.log(`Image size:       ${(info.totalSectors * 512).toLocaleString()} bytes (${info.totalSectors.toLocaleString()} sectors)`);
+    console.log(`Directory:        ${info.usedEntries}/16 entries used, ${info.freeEntries} free`);
+    console.log(`Data sectors:     ${info.usedDataSectors} used, ${info.freeDataSectors.toLocaleString()} free`);
+    console.log(`Next free sector: ${info.nextFreeSector}`);
+  });
+
+program.parse();

package/src/lib/constants.ts

@@ -0,0 +1,19 @@
+export const SECTOR_SIZE = 512;
+export const DIR_LBA = 0;
+export const DATA_START = 1;
+export const MAX_FILES = 16;
+export const ENTRY_SIZE = 32;
+
+// Field offsets within a directory entry
+export const NAME_OFFSET = 0;
+export const NAME_LENGTH = 8;
+export const EXT_OFFSET = 8;
+export const EXT_LENGTH = 3;
+export const FLAGS_OFFSET = 11;
+export const START_OFFSET = 12;
+export const FSIZE_OFFSET = 14;
+export const RESERVED_OFFSET = 16;
+export const RESERVED_LENGTH = 16;
+
+// Flags
+export const FLAG_USED = 0x01;

package/src/lib/directory.ts

@@ -0,0 +1,104 @@
+import {
+  SECTOR_SIZE, DIR_LBA, MAX_FILES, ENTRY_SIZE,
+  NAME_OFFSET, NAME_LENGTH, EXT_OFFSET, EXT_LENGTH,
+  FLAGS_OFFSET, START_OFFSET, FSIZE_OFFSET, FLAG_USED,
+  DATA_START,
+} from './constants.js';
+import { DirEntry } from './types.js';
+import { readSector, writeSector } from './image.js';
+
+/**
+ * Parse all 16 directory entries from LBA 0.
+ */
+export function readDirectory(buf: Buffer): DirEntry[] {
+  const sector = readSector(buf, DIR_LBA);
+  const entries: DirEntry[] = [];
+
+  for (let i = 0; i < MAX_FILES; i++) {
+    const off = i * ENTRY_SIZE;
+    const name = sector.subarray(off + NAME_OFFSET, off + NAME_OFFSET + NAME_LENGTH).toString('ascii');
+    const ext = sector.subarray(off + EXT_OFFSET, off + EXT_OFFSET + EXT_LENGTH).toString('ascii');
+    const flags = sector[off + FLAGS_OFFSET];
+    const startSector = sector.readUInt16LE(off + START_OFFSET);
+    const fileSize = sector.readUInt16LE(off + FSIZE_OFFSET);
+
+    entries.push({ name, ext, flags, startSector, fileSize, index: i });
+  }
+
+  return entries;
+}
+
+/**
+ * Serialize directory entries back to LBA 0.
+ */
+export function writeDirectory(buf: Buffer, entries: DirEntry[]): void {
+  const sector = Buffer.alloc(SECTOR_SIZE);
+
+  for (const entry of entries) {
+    const off = entry.index * ENTRY_SIZE;
+    // Write name (8 bytes, space-padded)
+    sector.write(entry.name.padEnd(NAME_LENGTH, ' '), off + NAME_OFFSET, NAME_LENGTH, 'ascii');
+    // Write extension (3 bytes, space-padded)
+    sector.write(entry.ext.padEnd(EXT_LENGTH, ' '), off + EXT_OFFSET, EXT_LENGTH, 'ascii');
+    // Flags
+    sector[off + FLAGS_OFFSET] = entry.flags;
+    // Start sector (u16 LE)
+    sector.writeUInt16LE(entry.startSector, off + START_OFFSET);
+    // File size (u16 LE)
+    sector.writeUInt16LE(entry.fileSize, off + FSIZE_OFFSET);
+    // Reserved bytes stay zeroed
+  }
+
+  writeSector(buf, DIR_LBA, sector);
+}
+
+/**
+ * Find a used directory entry by name and extension (space-padded, uppercase).
+ */
+export function findFile(entries: DirEntry[], name: string, ext: string): DirEntry | undefined {
+  return entries.find(
+    (e) => (e.flags & FLAG_USED) !== 0 && e.name === name && e.ext === ext
+  );
+}
+
+/**
+ * Find the first free (unused) directory slot index, or -1 if full.
+ */
+export function findFreeSlot(entries: DirEntry[]): number {
+  const entry = entries.find((e) => (e.flags & FLAG_USED) === 0);
+  return entry ? entry.index : -1;
+}
+
+/**
+ * Calculate the next free sector after all allocated files.
+ * Replicates BIOS FsCalcNextSec logic:
+ *   sectors = highByte >> 1; if (highByte & 1 || lowByte != 0) sectors++
+ */
+export function calcSectorCount(fileSize: number): number {
+  const lowByte = fileSize & 0xFF;
+  const highByte = (fileSize >> 8) & 0xFF;
+  let sectors = highByte >> 1;
+  if ((highByte & 1) !== 0 || lowByte !== 0) {
+    sectors++;
+  }
+  return sectors;
+}
+
+/**
+ * Calculate the next free sector for allocation.
+ * Returns max(startSector + sectorCount) across all used entries, minimum DATA_START.
+ */
+export function calcNextSector(entries: DirEntry[]): number {
+  let next = DATA_START;
+
+  for (const e of entries) {
+    if ((e.flags & FLAG_USED) === 0) continue;
+    const sectorCount = calcSectorCount(e.fileSize);
+    const end = e.startSector + sectorCount;
+    if (end > next) {
+      next = end;
+    }
+  }
+
+  return next;
+}

package/src/lib/filename.ts

@@ -0,0 +1,55 @@
+import { DirEntry } from './types.js';
+
+/**
+ * Parse user input into 8.3 filename components.
+ * Splits on first dot, uppercases, space-pads to 8+3.
+ */
+export function parseName(input: string): { name: string; ext: string } {
+  const dotIndex = input.indexOf('.');
+  let rawName: string;
+  let rawExt: string;
+
+  if (dotIndex === -1) {
+    rawName = input;
+    rawExt = '';
+  } else {
+    rawName = input.substring(0, dotIndex);
+    rawExt = input.substring(dotIndex + 1);
+  }
+
+  rawName = rawName.toUpperCase();
+  rawExt = rawExt.toUpperCase();
+
+  if (rawName.length === 0 || rawName.length > 8) {
+    throw new Error(`Invalid filename: name part must be 1-8 characters, got "${rawName}"`);
+  }
+  if (rawExt.length > 3) {
+    throw new Error(`Invalid filename: extension must be 0-3 characters, got "${rawExt}"`);
+  }
+
+  // Validate ASCII printable (no spaces or special control chars in input)
+  const validChars = /^[A-Z0-9!#$%&'()\-@^_`{}~]+$/;
+  if (!validChars.test(rawName)) {
+    throw new Error(`Invalid filename: name contains invalid characters "${rawName}"`);
+  }
+  if (rawExt.length > 0 && !validChars.test(rawExt)) {
+    throw new Error(`Invalid filename: extension contains invalid characters "${rawExt}"`);
+  }
+
+  const name = rawName.padEnd(8, ' ');
+  const ext = rawExt.padEnd(3, ' ');
+
+  return { name, ext };
+}
+
+/**
+ * Format a directory entry's name for display as NAME.EXT (trimmed).
+ */
+export function formatName(entry: DirEntry): string {
+  const name = entry.name.trimEnd();
+  const ext = entry.ext.trimEnd();
+  if (ext.length === 0) {
+    return name;
+  }
+  return `${name}.${ext}`;
+}

package/src/lib/image.ts

@@ -0,0 +1,50 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { SECTOR_SIZE } from './constants.js';
+
+/**
+ * Read an entire image file into a Buffer.
+ */
+export function openImage(path: string): Buffer {
+  return readFileSync(path);
+}
+
+/**
+ * Write a Buffer to disk as an image file.
+ */
+export function saveImage(path: string, buf: Buffer): void {
+  writeFileSync(path, buf);
+}
+
+/**
+ * Create a new zeroed image buffer with the given number of sectors.
+ */
+export function createImage(totalSectors: number): Buffer {
+  return Buffer.alloc(totalSectors * SECTOR_SIZE);
+}
+
+/**
+ * Read a single sector (512 bytes) from the image buffer at the given LBA.
+ */
+export function readSector(buf: Buffer, lba: number): Buffer {
+  const offset = lba * SECTOR_SIZE;
+  if (offset + SECTOR_SIZE > buf.length) {
+    throw new Error(`Sector ${lba} is out of bounds (image size: ${buf.length} bytes)`);
+  }
+  return Buffer.from(buf.subarray(offset, offset + SECTOR_SIZE));
+}
+
+/**
+ * Write 512 bytes of data to the image buffer at the given LBA.
+ */
+export function writeSector(buf: Buffer, lba: number, data: Buffer): void {
+  const offset = lba * SECTOR_SIZE;
+  if (offset + SECTOR_SIZE > buf.length) {
+    throw new Error(`Sector ${lba} is out of bounds (image size: ${buf.length} bytes)`);
+  }
+  if (data.length > SECTOR_SIZE) {
+    throw new Error(`Data exceeds sector size (${data.length} > ${SECTOR_SIZE})`);
+  }
+  // Zero the sector first, then copy data (handles data shorter than 512)
+  buf.fill(0, offset, offset + SECTOR_SIZE);
+  data.copy(buf, offset);
+}