extwee 2.2.5 → 2.3.0

package/build/extwee.web.min.js.LICENSE.txt

@@ -0,0 +1 @@
+/*! https://mths.be/he v1.2.0 by @mathias | MIT license */

package/extwee.config.json

@@ -0,0 +1,6 @@
+{
+    "mode": "decompile",
+    "input": "index.html",
+    "output": "index.twee",
+    "story-format": "harlowe"
+}

package/extwee.config.md

@@ -0,0 +1,67 @@
+# Extwee Config File Options
+
+The configuration file supports some, but not all, possible actions using command-line arguments.
+
+## Defining `mode`
+
+The most important option is `mode`. This **MUST BE** either `compile` or `decompile`.
+
+```json
+{
+    "mode": "decompile"
+}
+```
+
+## Defining `input` and `output`
+
+To process files, the `input` and `output` properties **MUST BE** defined using either an absolute or relative path.
+
+```json
+{
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html"
+}
+```
+
+## Defining `story-format`
+
+If using the `"mode": "compile"` option, the `story-format` property **MUST BE** defined. This should be the name of a directory in the relative `./story-formats` directory.
+
+For example, if using Harlowe, the path would be `./story-formats/harlowe` and the key-value pair would be `"story-format": "harlowe"`.
+
+```json
+{
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html",
+    "story-format": "harlowe"
+}
+```
+
+### Defining optional `story-format-version`
+
+The Story Format Archive retrieves story formats based on its version in a sub-directory structure:
+
+```file
+story-formats/
+├── harlowe/
+│   ├── 2.3.0/
+│       └── format.js
+│   ├── 2.4.0/
+│       └── format.js
+```
+
+This can be specified, such as `3.2.0`, or the default `latest`, can be used.
+
+```json
+{
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html",
+    "story-format": "harlowe",
+    "story-format-version": "3.2.0"
+}
+```
+
+If only the story format name is specified, and it can be found in the local `story-formats` directory, it will search for a corresponding `format.js` file.

package/index.js

@@ -8,6 +8,7 @@ import { parse as parseTWS } from './src/TWS/parse.js';
 import { compile as compileTwine1HTML } from './src/Twine1HTML/compile.js';
 import { compile as compileTwine2HTML } from './src/Twine2HTML/compile.js';
 import { compile as compileTwine2ArchiveHTML } from './src/Twine2ArchiveHTML/compile.js';
+import { compile as compileStoryFormat } from './src/StoryFormat/compile.js';
 import { generate as generateIFID } from './src/IFID/generate.js';
 import { Story } from './src/Story.js';
 import Passage from './src/Passage.js';
@@ -24,6 +25,7 @@ export {
     compileTwine1HTML,
     compileTwine2HTML,
     compileTwine2ArchiveHTML,
+    compileStoryFormat,
     generateIFID,
     Story,
     Passage,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "extwee",
-  "version": "2.2.5",
+  "version": "2.3.0",
   "description": "A story compiler tool using Twine-compatible formats",
   "author": "Dan Cox",
   "main": "index.js",
@@ -12,9 +12,8 @@
     "lint": "eslint ./src/**/*.js --fix",
     "lint:test": "eslint ./test/**/*.test.js --fix",
     "build:web": "webpack",
-    "build:bin": "esbuild ./src/extwee.js --bundle --platform=node --target=node12 --outfile=out.js",
     "gen-types": "npx -p typescript tsc src/**/*.js --declaration --allowJs --emitDeclarationOnly --outDir types",
-    "all": "npm run lint && npm run lint:test && npm run test && npm run gen-types"
+    "all": "npm run lint && npm run lint:test && npm run test && npm run build:web && npm run gen-types"
   },
   "keywords": [
     "twine",
@@ -24,34 +23,36 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "commander": "^13.1.0",
+    "commander": "^14.0.0",
     "graphemer": "^1.4.0",
-    "html-entities": "^2.5.2",
+    "html-entities": "^2.6.0",
     "node-html-parser": "^7.0.1",
     "pickleparser": "^0.2.1",
-    "semver": "^7.7.1",
-    "uuid": "^11.0.5"
+    "semver": "^7.7.2",
+    "shelljs": "^0.10.0",
+    "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@babel/cli": "^7.26.4",
-    "@babel/core": "^7.26.8",
-    "@babel/preset-env": "^7.26.8",
-    "@eslint/js": "^9.20.0",
+    "@babel/cli": "^7.27.2",
+    "@babel/core": "^7.27.1",
+    "@babel/preset-env": "^7.27.2",
+    "@eslint/js": "^9.29.0",
+    "@inquirer/prompts": "^7.5.2",
+    "@types/semver": "^7.7.0",
     "@types/uuid": "^10.0.0",
-    "babel-loader": "^9.2.1",
+    "babel-loader": "^10.0.0",
     "clean-jsdoc-theme": "^4.3.0",
-    "core-js": "^3.40.0",
-    "esbuild": "^0.25.0",
-    "eslint": "^9.20.0",
-    "eslint-plugin-jest": "^28.11.0",
-    "eslint-plugin-jsdoc": "^50.6.3",
-    "globals": "^15.14.0",
-    "jest": "^29.7.0",
+    "core-js": "^3.43.0",
+    "eslint": "^9.29.0",
+    "eslint-plugin-jest": "^28.14.0",
+    "eslint-plugin-jsdoc": "^51.0.1",
+    "globals": "^16.2.0",
+    "jest": "^30.0.0",
+    "jest-environment-jsdom": "^30.0.0",
     "regenerator-runtime": "^0.14.1",
-    "shelljs": "^0.8.5",
-    "typescript": "^5.7.3",
-    "typescript-eslint": "^8.23.0",
-    "webpack": "^5.97.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.34.0",
+    "webpack": "^5.99.9",
     "webpack-cli": "^6.0.1"
   },
   "repository": {

package/src/CLI/CommandLineProcessing.js

@@ -0,0 +1,196 @@
+// Import functions we need.
+import {
+    parseTwine2HTML,
+    parseTwee,
+    parseStoryFormat,
+    parseTwine1HTML,
+    compileTwine2HTML,
+    compileTwine1HTML
+  } from '../../index.js';
+  
+// Import fs.
+import { readFileSync, writeFileSync } from 'node:fs';
+  
+// Import Commander.
+import { Command, InvalidArgumentError } from 'commander';
+  
+// Import package.json.
+import Package from '../../package.json' with { type: 'json' };
+
+// Import isFile function.
+import { isFile } from './isFile.js';
+
+/**
+ * Process command line arguments.
+ * @function CommandLineProcessing
+ * @description This function processes the command line arguments passed to the Extwee CLI.
+ * @module CLI/commandLineProcessing
+ * @param {Array} argv - The command line arguments passed to the CLI.
+ */
+export function CommandLineProcessing(argv) {
+  // This is the main function for processing the command line arguments.
+  // It uses the Commander library to parse the arguments and then calls the appropriate functions.
+  // The function is called when the script is run from the command line.
+
+
+  // Create a new Command.
+  const program = new Command();
+
+  program
+    .name('extwee')
+    .description('CLI for Extwee')
+    .option('-v, --version', 'Show version number', () => {
+      // Show the version number.
+      console.log(`Extwee v${Package.version}`);
+      // Exit the process.
+      process.exit(0);
+    })
+    .option('-c, --compile', 'Compile input into output')
+    .option('-d, --decompile', 'De-compile input into output')
+    .option('--twine1', 'Enable Twine 1 processing')
+    .option('--name <storyFormatName>', 'Name of the Twine 1 story format (needed for `code.js` inclusion)')
+    .option('--codejs <codeJSFile>', 'Twine 1 code.js file for use with Twine 1 HTML', (value) => {
+      // Does the input file exist?
+      if (isFile(value) === false) {
+        // We cannot do anything without valid input.
+        throw new InvalidArgumentError(`Twine 1 code.js ${value} does not exist.`);
+      }
+
+      return value;
+    })
+    .option('--engine <engineFile>', 'Twine 1 engine.js file for use with Twine 1 HTML', (value) => {
+      // Does the input file exist?
+      if (isFile(value) === false) {
+        // We cannot do anything without valid input.
+        throw new InvalidArgumentError(`Twine 1 engine.js ${value} does not exist.`);
+      }
+
+      return value;
+    })
+    .option('--header <headerFile>', 'Twine 1 header.html file for use with Twine 1 HTML', (value) => {
+      // Does the input file exist?
+      if (isFile(value) === false) {
+        // We cannot do anything without valid input.
+        throw new InvalidArgumentError(`Twine 1 header.html ${value} does not exist.`);
+      }
+
+      return value;
+    })
+    .option('-s <storyformat>, --storyformat <storyformat>', 'Path to story format file for Twine 2', (value) => {
+      // Does the input file exist?
+      if (isFile(value) === false) {
+        // We cannot do anything without valid input.
+        throw new InvalidArgumentError(`Story format ${value} does not exist.`);
+      }
+
+      return value;
+    })
+    .option('-i <inputFile>, --input <inputFile>', 'Path to input file', (value) => {
+      // Does the input file exist?
+      if (isFile(value) === false) {
+        // We cannot do anything without valid input.
+        throw new InvalidArgumentError(`Input file ${value} does not exist.`);
+      }
+
+      return value;
+    })
+    .option('-o <outputFile>, --output <outputFile>', 'Path to output file');
+
+  // Parse the passed arguments.
+  program.parse(argv);
+
+  // Create object of passed arguments parsed by Commander.
+  const options = program.opts();
+
+  /*
+  * Prepare some (soon to be) global variables.
+  */
+  // Check if Twine 1 is enabled.
+  const isTwine1Mode = (options.twine1 === true);
+
+  // Check if Twine 2 is enabled.
+  const isTwine2Mode = (isTwine1Mode === false);
+
+  // Check if de-compile mode is enabled.
+  const isDecompileMode = (options.decompile === true);
+
+  // Check if compile mode is enabled.
+  const isCompileMode = (options.compile === true);
+
+  // De-compile Twine 2 HTML into Twee 3 branch.
+  // If -d is passed, -i and -o are required.
+  if (isTwine2Mode === true && isDecompileMode === true) {
+    // Read the input HTML file.
+    const inputHTML = readFileSync(options.i, 'utf-8');
+
+    // Parse the input HTML file into Story object.
+    const storyObject = parseTwine2HTML(inputHTML);
+
+    // Write the output file from Story as Twee 3.
+    writeFileSync(options.o, storyObject.toTwee());
+
+    return;
+  }
+
+  // Compile Twee 3 into Twine 2 HTML branch.
+  // If -c is passed, -i, -o, and -s are required.
+  if (isTwine2Mode === true && isCompileMode === true) {
+    // Read the input file.
+    const inputTwee = readFileSync(options.i, 'utf-8');
+
+    // Parse the input file.
+    const story = parseTwee(inputTwee);
+
+    // Read the story format file.
+    const inputStoryFormat = readFileSync(options.s, 'utf-8');
+
+    // Parse the story format file.
+    const parsedStoryFormat = parseStoryFormat(inputStoryFormat);
+
+    // Compile the story.
+    const Twine2HTML = compileTwine2HTML(story, parsedStoryFormat);
+
+    // Write the output file.
+    writeFileSync(options.o, Twine2HTML);
+
+    // Exit the process.
+    return;
+  }
+
+  // Compile Twee 3 into Twine 1 HTML branch.
+  // Twine 1 compilation is complicated, so we have to check for all the required options.
+  // * options.engine (from Twine 1 itself)
+  // * options.header (from Twine 1 story format)
+  // * options.name (from Twine 1 story format)
+  // * options.codejs (from Twine 1 story format)
+  if (isTwine1Mode === true && isCompileMode === true) {
+    // Read the input file.
+    const inputTwee = readFileSync(options.i, 'utf-8');
+
+    // Parse the input file.
+    const story = parseTwee(inputTwee);
+
+    // Does the engine file exist?
+    const Twine1HTML = compileTwine1HTML(story, options.engine, options.header, options.name, options.codejs);
+
+    // Write the output file.
+    writeFileSync(options.o, Twine1HTML);
+
+    // Exit the process.
+    return;
+  }
+
+  // De-compile Twine 1 HTML into Twee 3 branch.
+  if (isTwine1Mode === true && isDecompileMode === true) {
+    // Read the input HTML file.
+    const inputHTML = readFileSync(options.i, 'utf-8');
+
+    // Parse the input HTML file into Story object.
+    const storyObject = parseTwine1HTML(inputHTML);
+
+    // Write the output file from Story as Twee 3.
+    writeFileSync(options.o, storyObject.toTwee());
+
+    return;
+  }
+}

package/src/CLI/ProcessConfig/loadStoryFormat.js

@@ -0,0 +1,102 @@
+import { isDirectory } from "../isDirectory.js";
+import { isFile } from "../isFile.js";
+import { readDirectories } from "./readDirectories.js";
+import { readFileSync } from "node:fs";
+
+/**
+ * Load the story format from the story-formats directory.
+ * @function loadStoryFormat
+ * @description This function loads the story format from the story-formats directory.
+ * It checks if the story-formats directory exists, if the named story format exists,
+ * if the version directory exists, and if the format.js file exists.
+ * If any of these checks fail, the function will exit the process with an error message.
+ * If all checks pass, the function will return the contents of the format.js file.
+ * @param {string} storyFormatName - The name of the story format.
+ * @param {string} storyFormatVersion - The version of the story format.
+ * @returns {string} - The contents of the format.js file.
+ * @throws {Error} - If the story-formats directory does not exist, if the named story format does not exist,
+ * if the version directory does not exist, or if the format.js file does not exist.
+ * @example
+ * // Load the story format from the story-formats directory.
+ * const storyFormat = loadStoryFormat('Harlowe', '3.2.0');
+ * console.log(storyFormat);
+ * // Output: The contents of the format.js file.
+ */
+export function loadStoryFormat(storyFormatName, storyFormatVersion) {
+    // If the story-formats directory does not exist, throw error.
+    if (isDirectory('story-formats') === false) {
+        throw new Error(`Error: story-formats directory does not exist. Consider running 'npx sfa-get' to download the latest story formats.`);
+    }
+
+    // Does the named story format exist in the story-formats directory?
+    const isStoryFormatDir = isDirectory(`story-formats/${storyFormatName}`);
+    
+    // If the story format directory does not exist, throw error.
+    if (isStoryFormatDir === false) {
+        throw new Error(`Error: story format ${storyFormatName} does not exist in the story-formats directory.`);
+    }
+
+    let filepath = `story-formats/${storyFormatName}/format.js`;
+
+    // If the story format version is 'latest', check if the format.js file exists.
+    // If the format.js file does not exist, check if there are version directories.
+    // If there are version directories, get the latest version and set the filepath to that version directory and format.js file.
+    // If the format.js file exists, return its contents.
+
+    // Check if storyFormatVersion is "latest"
+    if (storyFormatVersion === 'latest' && isFile(filepath) === false) {
+        // Read the directories in the story format directory.
+        // The directories are expected to be version directories.
+        let directories = readDirectories(`story-formats/${storyFormatName}`);
+
+        console.log("!!! directories", directories);
+
+        // Check if there are any version directories.
+        if (directories.length === 0) {
+            // If there are no version directories, throw error.
+            throw new Error(`Error: story format ${storyFormatName} does not have any version directories.`);
+        }
+            
+        // Sort the directories in descending order.
+        directories.sort((a, b) => {
+            return b.localeCompare(a, undefined, { numeric: true });
+        });
+
+        // Get the latest version directory.
+        // The latest version is the last directory in the sorted list.
+        const latestVersion = directories[0];
+        
+        // Set the filepath to the latest version directory.
+        filepath = `story-formats/${storyFormatName}/${latestVersion}/format.js`;
+
+        // Is there a 'format.js' file in the version directory?
+        let isFormatFile = isFile(filepath);
+
+        // If the format.js file does not exist, exit the process.
+        if (isFormatFile === false) {
+            throw new Error(`Error: story format ${storyFormatName} version ${storyFormatVersion} does not have a format.js file.`);
+        }
+    }
+
+    // If the story format version is not 'latest', check if version directories exists.
+    if(storyFormatVersion !== 'latest') {
+        // Does the named story format have a version directory?
+        const isVersionDir = isDirectory(`story-formats/${storyFormatName}/${storyFormatVersion}`);
+        
+        // If the version directory does not exist, throw error.
+        if (isVersionDir === false) {
+            throw new Error(`Error: story format ${storyFormatName} version ${storyFormatVersion} does not exist in the story-formats directory.`);
+        }
+
+        // Set an initial path based on the version.
+        filepath = `story-formats/${storyFormatName}/${storyFormatVersion}/format.js`;
+        
+        // If the format.js file does not exist, throw error.
+        if (isFile(filepath) === false) {
+            throw new Error(`Error: story format ${storyFormatName} version ${storyFormatVersion} does not have a format.js file.`);
+        }
+    }
+
+    // If the format.js file exists, read and return its contents.
+    return readFileSync(filepath, 'utf-8');
+}

package/src/CLI/ProcessConfig/readDirectories.js

@@ -0,0 +1,46 @@
+import { readdirSync } from 'node:fs';
+import { isDirectory } from '../isDirectory.js';
+
+/**
+ * Read the contents of a directory and returns all directories.
+ * @function readDirectories
+ * @description This function reads the contents of a directory and returns a list of directories.
+ * @param {string} directory - The path to the directory to read.
+ * @returns {Array<string>} - An array of directories in the directory.
+ * @throws {Error} - If the directory does not exist or if there is an error reading the directory.
+ */
+export function readDirectories(directory) {
+
+    // Create default response.
+    let results = [];
+
+    // Check if the directory exists.
+    const isDir = isDirectory(directory);
+    // If the directory does not exist, return an empty array
+    //  and log an error message.
+    if (isDir == false) {
+        console.error(`Error: Directory ${directory} does not exist.`);
+    }
+
+    // Read the directory and return the list of files.
+    try {
+        results = readdirSync(directory);
+    } catch (error) {
+        console.error(`Error reading directory ${directory}:`, error);
+        results = [];
+    }
+
+    // Check if results is an array.
+    // This should not happen, but for some reason it can.
+    if (!Array.isArray(results)) {
+        results = [];
+    }
+
+    // Filter the list to only include directories.
+    const directoriesOnly = results.filter((item) => {
+        return isDirectory(`${directory}/${item}`);
+    });
+
+    // Return the list of directories.
+    return directoriesOnly;
+}