@vsirotin/ts-stop 1.11.1 → 1.13.0

package/lib/esm/sfsm/FaMerger.js

@@ -0,0 +1,24 @@
+import { reduceFA } from './FaReducer';
+/**
+ * Merges multiple FA definitions into one compact multi-FA object.
+ *
+ * Each input is reduced first (same semantics as reduceFA). If an input is
+ * already compact, reduceFA returns it unchanged.
+ *
+ * On duplicate FA keys, the later input overwrites the previous one and a
+ * warning entry is emitted.
+ */
+export function mergeFAs(definitions) {
+    const merged = {};
+    const warnings = [];
+    for (let fileIndex = 0; fileIndex < definitions.length; fileIndex++) {
+        const reduced = reduceFA(definitions[fileIndex]);
+        for (const [faName, transitions] of Object.entries(reduced)) {
+            if (Object.prototype.hasOwnProperty.call(merged, faName)) {
+                warnings.push(`Duplicate FA key '${faName}' encountered at input #${fileIndex + 1}. Last definition wins.`);
+            }
+            merged[faName] = transitions;
+        }
+    }
+    return { merged, warnings };
+}

package/lib/esm/sfsm/index.js

@@ -2,5 +2,6 @@ export { ExternalWorldHub } from './ExternalWorldHub';
 export { FaResolver } from './FaResolver';
 export { Sfsm } from './Sfsm';
 export { reduceFA } from './FaReducer';
+export { mergeFAs } from './FaMerger';
 export { updateCompactFA, updateFullFA } from './FaUpdater';
 export { loadFAFromFile, loadFAFromURL } from './FaLoader';

package/lib/sfsm/FaMerger.d.ts

@@ -0,0 +1,16 @@
+import { FaDefinition } from './types';
+export interface MergeFaResult {
+    merged: FaDefinition;
+    warnings: string[];
+}
+/**
+ * Merges multiple FA definitions into one compact multi-FA object.
+ *
+ * Each input is reduced first (same semantics as reduceFA). If an input is
+ * already compact, reduceFA returns it unchanged.
+ *
+ * On duplicate FA keys, the later input overwrites the previous one and a
+ * warning entry is emitted.
+ */
+export declare function mergeFAs(definitions: FaDefinition[]): MergeFaResult;
+//# sourceMappingURL=FaMerger.d.ts.map

package/lib/sfsm/FaMerger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaMerger.d.ts","sourceRoot":"","sources":["../../src/sfsm/FaMerger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,MAAM,WAAW,aAAa;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,WAAW,EAAE,YAAY,EAAE,GAAG,aAAa,CAgBnE"}

package/lib/sfsm/FaMerger.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeFAs = mergeFAs;
+const FaReducer_1 = require("./FaReducer");
+/**
+ * Merges multiple FA definitions into one compact multi-FA object.
+ *
+ * Each input is reduced first (same semantics as reduceFA). If an input is
+ * already compact, reduceFA returns it unchanged.
+ *
+ * On duplicate FA keys, the later input overwrites the previous one and a
+ * warning entry is emitted.
+ */
+function mergeFAs(definitions) {
+    const merged = {};
+    const warnings = [];
+    for (let fileIndex = 0; fileIndex < definitions.length; fileIndex++) {
+        const reduced = (0, FaReducer_1.reduceFA)(definitions[fileIndex]);
+        for (const [faName, transitions] of Object.entries(reduced)) {
+            if (Object.prototype.hasOwnProperty.call(merged, faName)) {
+                warnings.push(`Duplicate FA key '${faName}' encountered at input #${fileIndex + 1}. Last definition wins.`);
+            }
+            merged[faName] = transitions;
+        }
+    }
+    return { merged, warnings };
+}
+//# sourceMappingURL=FaMerger.js.map

package/lib/sfsm/FaMerger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaMerger.js","sourceRoot":"","sources":["../../src/sfsm/FaMerger.ts"],"names":[],"mappings":";;AAiBA,4BAgBC;AAhCD,2CAAuC;AAOvC;;;;;;;;GAQG;AACH,SAAgB,QAAQ,CAAC,WAA2B;IAChD,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,IAAI,SAAS,GAAG,CAAC,EAAE,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,CAAC;QAClE,MAAM,OAAO,GAAG,IAAA,oBAAQ,EAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC;QAEjD,KAAK,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1D,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC;gBACvD,QAAQ,CAAC,IAAI,CAAC,qBAAqB,MAAM,2BAA2B,SAAS,GAAG,CAAC,yBAAyB,CAAC,CAAC;YAChH,CAAC;YACD,MAAM,CAAC,MAAM,CAAC,GAAG,WAAW,CAAC;QACjC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC"}

package/lib/sfsm/index.d.ts

@@ -4,6 +4,7 @@ export { FaDefinition, FaNode, FaUpdate, Transition, SfsmOptions, LogEntry, Miss
 export { FaResolver, ResolvedFa } from './FaResolver';
 export { Sfsm } from './Sfsm';
 export { reduceFA } from './FaReducer';
+export { mergeFAs, MergeFaResult } from './FaMerger';
 export { updateCompactFA, updateFullFA } from './FaUpdater';
 export { loadFAFromFile, loadFAFromURL } from './FaLoader';
 //# sourceMappingURL=index.d.ts.map

package/lib/sfsm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sfsm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AACxI,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sfsm/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,MAAM,SAAS,CAAC;AACxI,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAC9B,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC"}

package/lib/sfsm/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadFAFromURL = exports.loadFAFromFile = exports.updateFullFA = exports.updateCompactFA = exports.reduceFA = exports.Sfsm = exports.FaResolver = exports.ExternalWorldHub = void 0;
+exports.loadFAFromURL = exports.loadFAFromFile = exports.updateFullFA = exports.updateCompactFA = exports.mergeFAs = exports.reduceFA = exports.Sfsm = exports.FaResolver = exports.ExternalWorldHub = void 0;
 var ExternalWorldHub_1 = require("./ExternalWorldHub");
 Object.defineProperty(exports, "ExternalWorldHub", { enumerable: true, get: function () { return ExternalWorldHub_1.ExternalWorldHub; } });
 var FaResolver_1 = require("./FaResolver");
@@ -9,6 +9,8 @@ var Sfsm_1 = require("./Sfsm");
 Object.defineProperty(exports, "Sfsm", { enumerable: true, get: function () { return Sfsm_1.Sfsm; } });
 var FaReducer_1 = require("./FaReducer");
 Object.defineProperty(exports, "reduceFA", { enumerable: true, get: function () { return FaReducer_1.reduceFA; } });
+var FaMerger_1 = require("./FaMerger");
+Object.defineProperty(exports, "mergeFAs", { enumerable: true, get: function () { return FaMerger_1.mergeFAs; } });
 var FaUpdater_1 = require("./FaUpdater");
 Object.defineProperty(exports, "updateCompactFA", { enumerable: true, get: function () { return FaUpdater_1.updateCompactFA; } });
 Object.defineProperty(exports, "updateFullFA", { enumerable: true, get: function () { return FaUpdater_1.updateFullFA; } });

package/lib/sfsm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sfsm/index.ts"],"names":[],"mappings":";;;AACA,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AAEzB,2CAAsD;AAA7C,wGAAA,UAAU,OAAA;AACnB,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA;AACjB,yCAA4D;AAAnD,4GAAA,eAAe,OAAA;AAAE,yGAAA,YAAY,OAAA;AACtC,uCAA2D;AAAlD,0GAAA,cAAc,OAAA;AAAE,yGAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sfsm/index.ts"],"names":[],"mappings":";;;AACA,uDAAsD;AAA7C,oHAAA,gBAAgB,OAAA;AAEzB,2CAAsD;AAA7C,wGAAA,UAAU,OAAA;AACnB,+BAA8B;AAArB,4FAAA,IAAI,OAAA;AACb,yCAAuC;AAA9B,qGAAA,QAAQ,OAAA;AACjB,uCAAqD;AAA5C,oGAAA,QAAQ,OAAA;AACjB,yCAA4D;AAAnD,4GAAA,eAAe,OAAA;AAAE,yGAAA,YAAY,OAAA;AACtC,uCAA2D;AAAlD,0GAAA,cAAc,OAAA;AAAE,yGAAA,aAAa,OAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vsirotin/ts-stop",
-  "version": "1.11.1",
+  "version": "1.13.0",
   "description": "State Oriented Programming library for TypeScript",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -20,10 +20,18 @@
   },
   "files": [
     "lib",
+    "scripts",
     "README.md",
     "LICENSE",
     "LICENSE-COMMERCIAL.md"
   ],
+  "bin": {
+    "reduce-fa": "./scripts/reduce-fa.js",
+    "merge-fas": "./scripts/merge-fas.js",
+    "merge-fas-from-dir": "./scripts/merge-fas-from-dir.js",
+    "update-full-fa": "./scripts/update-fa.js",
+    "update-compact-fa": "./scripts/update-fa.js"
+  },
   "scripts": {
     "build": "npm run build:cjs && npm run build:esm",
     "build:cjs": "tsc",
@@ -34,6 +42,8 @@
     "publish:local": "./scripts/publish-local.sh",
     "pack": "npm run build && npm pack",
     "reduce-fa": "node scripts/reduce-fa.js",
+    "merge-fas": "node scripts/merge-fas.js",
+    "merge-fas-from-dir": "node scripts/merge-fas-from-dir.js",
     "update-full-fa": "node scripts/update-fa.js --format=full",
     "update-compact-fa": "node scripts/update-fa.js --format=compact"
   },

package/scripts/merge-fas-from-dir.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * merge-fas-from-dir.js — CLI tool to recursively merge all FA JSON files from a directory.
+ *
+ * Usage:
+ *   node scripts/merge-fas-from-dir.js --input-dir=<path/to/dir> --result=<path/to/result.json>
+ *
+ * Behavior:
+ * - Recursively finds all .json files in the input directory (including subdirectories).
+ * - Sorts files alphabetically by full path for consistent merge order.
+ * - Each input file is reduced with reduceFA semantics.
+ * - Already compact files are used unchanged.
+ * - Duplicate FA keys are overwritten by the latest file and reported as warnings.
+ * - Output is a single merged compact FA definition.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { mergeFAs } = require('../lib/sfsm');
+
+const args = process.argv.slice(2);
+const options = {};
+
+for (const arg of args) {
+    const match = arg.match(/^--([^=]+)=(.+)$/);
+    if (match) {
+        options[match[1]] = match[2];
+    }
+}
+
+if (!options['input-dir']) {
+    console.error('Error: --input-dir=<path> is required.');
+    console.error('Usage: node scripts/merge-fas-from-dir.js --input-dir=<path/to/dir> --result=<path/to/result.json>');
+    process.exit(1);
+}
+
+if (!options.result) {
+    console.error('Error: --result=<path> is required.');
+    console.error('Usage: node scripts/merge-fas-from-dir.js --input-dir=<path/to/dir> --result=<path/to/result.json>');
+    process.exit(1);
+}
+
+const inputDir = path.resolve(process.cwd(), options['input-dir']);
+const resultFile = path.resolve(process.cwd(), options.result);
+
+// Verify input directory exists
+if (!fs.existsSync(inputDir) || !fs.statSync(inputDir).isDirectory()) {
+    console.error(`Error: Input directory not found or not a directory: ${inputDir}`);
+    process.exit(1);
+}
+
+/**
+ * Recursively find all .json files in a directory.
+ */
+function findJsonFiles(dir, baseDir = dir) {
+    const files = [];
+    const entries = fs.readdirSync(dir);
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry);
+        const stat = fs.statSync(fullPath);
+
+        if (stat.isDirectory()) {
+            files.push(...findJsonFiles(fullPath, baseDir));
+        } else if (entry.endsWith('.json')) {
+            files.push(fullPath);
+        }
+    }
+
+    return files;
+}
+
+/**
+ * Check if a definition is in compact format.
+ */
+function isCompactDefinition(definition) {
+    const entries = Object.entries(definition);
+    return entries.length > 0 && entries.every(([, value]) => Array.isArray(value));
+}
+
+// Find all JSON files
+const jsonFiles = findJsonFiles(inputDir).sort();
+
+if (jsonFiles.length === 0) {
+    console.error(`Error: No JSON files found in input directory: ${inputDir}`);
+    process.exit(1);
+}
+
+console.log(`Found ${jsonFiles.length} JSON file(s) in ${inputDir}`);
+
+const definitions = [];
+
+for (let i = 0; i < jsonFiles.length; i++) {
+    const file = jsonFiles[i];
+    const relPath = path.relative(inputDir, file);
+    let definition;
+
+    try {
+        definition = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch (err) {
+        console.error(`Error: Failed to parse JSON from ${file}: ${err.message}`);
+        process.exit(1);
+    }
+
+    if (isCompactDefinition(definition)) {
+        console.log(`Info: Input #${i + 1} is already compact and will be used as-is: ${relPath}`);
+    } else {
+        console.log(`Info: Input #${i + 1} is extended and will be reduced: ${relPath}`);
+    }
+
+    definitions.push(definition);
+}
+
+const { merged, warnings } = mergeFAs(definitions);
+
+for (const warning of warnings) {
+    console.warn(`Warning: ${warning}`);
+}
+
+const json = JSON.stringify(merged, null, 4).replace(
+    /\[\s*\n\s*"([^"]+)",\s*\n\s*"([^"]+)",\s*\n\s*"([^"]+)"(?:,\s*\n\s*"([^"]+)")?\s*\n\s*\]/g,
+    (_, a, b, c, d) => d ? `["${a}", "${b}", "${c}", "${d}"]` : `["${a}", "${b}", "${c}"]`
+);
+
+fs.mkdirSync(path.dirname(resultFile), { recursive: true });
+fs.writeFileSync(resultFile, `${json}\n`, 'utf-8');
+console.log(`Merged compact FA written to: ${resultFile}`);

package/scripts/merge-fas.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * merge-fas.js — CLI tool to reduce and merge multiple FA JSON files.
+ *
+ * Usage:
+ *   npm run merge-fas -- --result=<path/to/result.json> <file1[,file2,...]> [file3 ...]
+ *
+ * Behavior:
+ * - Each input file is reduced with reduceFA semantics.
+ * - Already compact files are used unchanged.
+ * - Duplicate FA keys are overwritten by the latest file and reported as warnings.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { mergeFAs } = require('../lib/sfsm');
+
+const args = process.argv.slice(2);
+const options = {};
+const rawFiles = [];
+
+for (const arg of args) {
+    const match = arg.match(/^--([^=]+)=(.+)$/);
+    if (match) {
+        options[match[1]] = match[2];
+    } else {
+        rawFiles.push(arg);
+    }
+}
+
+if (!options.result) {
+    console.error('Error: --result=<path> is required.');
+    console.error('Usage: npm run merge-fas -- --result=<path/to/result.json> <file1[,file2,...]> [file3 ...]');
+    process.exit(1);
+}
+
+const inputFiles = rawFiles
+    .flatMap((chunk) => chunk.split(','))
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+if (inputFiles.length === 0) {
+    console.error('Error: At least one input file is required.');
+    console.error('Usage: npm run merge-fas -- --result=<path/to/result.json> <file1[,file2,...]> [file3 ...]');
+    process.exit(1);
+}
+
+const resolvedInputFiles = inputFiles.map((f) => path.resolve(process.cwd(), f));
+const resultFile = path.resolve(process.cwd(), options.result);
+
+for (const file of resolvedInputFiles) {
+    if (!fs.existsSync(file)) {
+        console.error(`Error: Input file not found: ${file}`);
+        process.exit(1);
+    }
+}
+
+function isCompactDefinition(definition) {
+    const entries = Object.entries(definition);
+    return entries.length > 0 && entries.every(([, value]) => Array.isArray(value));
+}
+
+const definitions = [];
+
+for (let i = 0; i < resolvedInputFiles.length; i++) {
+    const file = resolvedInputFiles[i];
+    let definition;
+    try {
+        definition = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch (err) {
+        console.error(`Error: Failed to parse JSON from ${file}: ${err.message}`);
+        process.exit(1);
+    }
+
+    if (isCompactDefinition(definition)) {
+        console.log(`Info: Input #${i + 1} is already compact and will be used as-is: ${file}`);
+    } else {
+        console.log(`Info: Input #${i + 1} is extended and will be reduced: ${file}`);
+    }
+
+    definitions.push(definition);
+}
+
+const { merged, warnings } = mergeFAs(definitions);
+
+for (const warning of warnings) {
+    console.warn(`Warning: ${warning}`);
+}
+
+const json = JSON.stringify(merged, null, 4).replace(
+    /\[\s*\n\s*"([^"]+)",\s*\n\s*"([^"]+)",\s*\n\s*"([^"]+)"(?:,\s*\n\s*"([^"]+)")?\s*\n\s*\]/g,
+    (_, a, b, c, d) => d ? `["${a}", "${b}", "${c}", "${d}"]` : `["${a}", "${b}", "${c}"]`
+);
+
+fs.mkdirSync(path.dirname(resultFile), { recursive: true });
+fs.writeFileSync(resultFile, `${json}\n`, 'utf-8');
+console.log(`Merged compact FA written to: ${resultFile}`);

package/scripts/publish-local.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+set -e
+
+echo "📦 Publishing ts-stop locally..."
+
+# Build
+npm run build
+
+# Copy to ts-stop node_modules so the test suite can import @vsirotin/ts-stop
+echo "📋 Installing to ts-stop node_modules..."
+rm -rf node_modules/@vsirotin/ts-stop
+mkdir -p node_modules/@vsirotin/ts-stop
+cp -r lib package.json README.md LICENSE node_modules/@vsirotin/ts-stop/
+
+echo "✅ Local publishing completed!"

package/scripts/reduce-fa.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * reduce-fa.js — CLI tool to convert an extended FA JSON file to compact format.
+ *
+ * Usage:
+ *   npm run reduce-fa -- <path/to/extended-fa.json>
+ *
+ * Output:
+ *   Writes the compact definition to <input>-compact.json in the same directory.
+ *
+ * Requires the library to be built first: npm run build
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { reduceFA } = require('../lib/sfsm');
+
+const inputArg = process.argv[2];
+
+if (!inputArg) {
+    console.error('Error: No input file specified.');
+    console.error('Usage: npm run reduce-fa -- <path/to/extended-fa.json>');
+    process.exit(1);
+}
+
+const inputFile = path.resolve(process.cwd(), inputArg);
+
+if (!fs.existsSync(inputFile)) {
+    console.error(`Error: File not found: ${inputFile}`);
+    process.exit(1);
+}
+
+let definition;
+try {
+    definition = JSON.parse(fs.readFileSync(inputFile, 'utf-8'));
+} catch (err) {
+    console.error(`Error: Failed to parse JSON from ${inputFile}: ${err.message}`);
+    process.exit(1);
+}
+
+const compact = reduceFA(definition);
+
+const ext = path.extname(inputFile);
+const base = path.basename(inputFile, ext);
+const dir = path.dirname(inputFile);
+const outputFile = path.join(dir, `${base}-compact${ext}`);
+
+// Serialize with transitions inline: ["state", "signal", "newState", "cmd?"]
+const json = JSON.stringify(compact, null, 4).replace(
+    /\[\s*\n\s*"([^"]+)",\s*\n\s*"([^"]+)",\s*\n\s*"([^"]+)"(?:,\s*\n\s*"([^"]+)")?\s*\n\s*\]/g,
+    (_, a, b, c, d) => d ? `["${a}", "${b}", "${c}", "${d}"]` : `["${a}", "${b}", "${c}"]`
+);
+fs.writeFileSync(outputFile, json, 'utf-8');
+console.log(`Reduced FA written to: ${outputFile}`);

package/scripts/update-fa.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * update-fa.js — CLI tool to apply an FA update file to a source FA JSON file.
+ *
+ * Invoked via npm scripts:
+ *   npm run update-full-fa    -- --source=<path> --update=<path> [--result=<path>]
+ *   npm run update-compact-fa -- --source=<path> --update=<path> [--result=<path>]
+ *
+ * If --result is omitted, the output file is named <source-basename>-updated.json.
+ *
+ * Requires the library to be built first: npm run build
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { updateFullFA, updateCompactFA } = require('../lib/sfsm');
+
+// ---------------------------------------------------------------------------
+// Parse args
+// ---------------------------------------------------------------------------
+
+const args = {};
+for (const arg of process.argv.slice(2)) {
+    const match = arg.match(/^--([^=]+)=(.+)$/);
+    if (match) args[match[1]] = match[2];
+}
+
+const format = args['format'];
+if (!format || !['full', 'compact'].includes(format)) {
+    console.error('Error: --format=full|compact is required (set by the npm script).');
+    process.exit(1);
+}
+
+if (!args['source']) {
+    console.error('Error: --source=<path> is required.');
+    console.error(`Usage: npm run update-${format}-fa -- --source=<path> --update=<path> [--result=<path>]`);
+    process.exit(1);
+}
+
+if (!args['update']) {
+    console.error('Error: --update=<path> is required.');
+    console.error(`Usage: npm run update-${format}-fa -- --source=<path> --update=<path> [--result=<path>]`);
+    process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Resolve paths
+// ---------------------------------------------------------------------------
+
+const sourceFile = path.resolve(process.cwd(), args['source']);
+const updateFile = path.resolve(process.cwd(), args['update']);
+
+let resultFile;
+if (args['result']) {
+    resultFile = path.resolve(process.cwd(), args['result']);
+} else {
+    const ext  = path.extname(sourceFile);
+    const base = path.basename(sourceFile, ext);
+    const dir  = path.dirname(sourceFile);
+    resultFile = path.join(dir, `${base}-updated${ext}`);
+}
+
+// ---------------------------------------------------------------------------
+// Load & validate
+// ---------------------------------------------------------------------------
+
+if (!fs.existsSync(sourceFile)) {
+    console.error(`Error: Source file not found: ${sourceFile}`);
+    process.exit(1);
+}
+
+if (!fs.existsSync(updateFile)) {
+    console.error(`Error: Update file not found: ${updateFile}`);
+    process.exit(1);
+}
+
+let source, update;
+try {
+    source = JSON.parse(fs.readFileSync(sourceFile, 'utf-8'));
+} catch (err) {
+    console.error(`Error: Failed to parse source JSON: ${err.message}`);
+    process.exit(1);
+}
+
+try {
+    update = JSON.parse(fs.readFileSync(updateFile, 'utf-8'));
+} catch (err) {
+    console.error(`Error: Failed to parse update JSON: ${err.message}`);
+    process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Apply update
+// ---------------------------------------------------------------------------
+
+let result;
+try {
+    result = format === 'full'
+        ? updateFullFA(source, update)
+        : updateCompactFA(source, update);
+} catch (err) {
+    console.error(`Error: Update failed: ${err.message}`);
+    process.exit(1);
+}
+
+fs.writeFileSync(resultFile, JSON.stringify(result, null, 4), 'utf-8');
+console.log(`Updated FA written to: ${resultFile}`);