Add direct excel->file store conversion

Author: m-houston

Makefile

@@ -26,6 +26,10 @@ clean:: # Clean-up project resources (main) @Operations
 config:: _install-dependencies version # Configure development environment (main) @Configuration
 	(cd docs && make install)
 
+internal-config:
+	npm run parse --workspace=@supplier-config/excel-parser -- \
+		"$(PWD)/specifications.xlsx" --output-dir "$(PWD)/artifacts/config-store" --pretty
+
 # ==============================================================================
 
 ${VERBOSE}.SILENT: \

packages/excel-parser/README.md

@@ -29,16 +29,25 @@ npm run parse -- config.xlsx -o output.json
 # Parse with pretty formatting and save to file
 npm run parse -- config.xlsx --pretty --output output.json
 
+# Parse and write a file-store-compatible directory of JSON files
+npm run parse -- config.xlsx --output-dir ./config-store
+
+# Pretty-print each JSON file in the generated config store
+npm run parse -- config.xlsx --output-dir ./config-store --pretty
+
 # Show help
 npm run parse -- --help
 ```
 
 **Options:**
 
 - `-o, --output <file>` - Write output to a file instead of stdout
+- `-d, --output-dir <directory>` - Write one JSON file per record into a directory compatible with `@supplier-config/file-store`
 - `-p, --pretty` - Pretty-print the JSON output
 - `-h, --help` - Show help message
 
+`--output` and `--output-dir` are mutually exclusive.
+
 **Output format:**
 
 The JSON output contains the following top-level keys:
@@ -50,6 +59,21 @@ The JSON output contains the following top-level keys:
 - `allocations` - Record of SupplierAllocation objects keyed by ID
 - `supplierPacks` - Record of SupplierPack objects keyed by ID
 
+#### Parse Excel to a file-store directory
+
+When `--output-dir` is used, the parser writes one JSON file per record using the directory names expected by the file-store package:
+
+- `volume-group/`
+- `letter-variant/`
+- `pack-specification/`
+- `supplier/`
+- `supplier-allocation/`
+- `supplier-pack/`
+
+Each file is written as a file-store-safe filename derived from the record id. Lowercase letters, digits, and hyphens are kept readable where possible, while characters that could cause path or casing issues are percent-encoded. `@supplier-config/file-store` decodes that filename back to the original id when loading records.
+
+To keep the generated store in sync with the Excel source, the writer recreates those managed entity directories on each run before writing the latest records. Unrelated files in the output root are left untouched.
+
 #### Generate Template
 
 Generate a template Excel file with the correct sheet structure and column headers:
@@ -86,7 +110,10 @@ The template includes the following sheets with proper column headers:
 #### Parsing an Excel file
 
 ```typescript
-import { parseExcelFile } from "@nhs-notify/excel-parser";
+import {
+  parseExcelFile,
+  writeParseResultToConfigStore,
+} from "@supplier-config/excel-parser";
 
 const result = parseExcelFile("./specifications.xlsx");
 
@@ -96,12 +123,16 @@ console.log(result.volumeGroups);    // Record<string, VolumeGroup>
 console.log(result.suppliers);       // Record<string, Supplier>
 console.log(result.allocations);     // Record<string, SupplierAllocation>
 console.log(result.supplierPacks);   // Record<string, SupplierPack>
+
+await writeParseResultToConfigStore(result, "./config-store", {
+  pretty: true,
+});
 ```
 
 ### Generating a template Excel file
 
 ```typescript
-import { generateTemplateExcel } from "@nhs-notify/excel-parser";
+import { generateTemplateExcel } from "@supplier-config/excel-parser";
 
 // Generate a new template (fails if file exists)
 generateTemplateExcel("./specifications.template.xlsx");