extwee 2.3.4 → 2.3.5

package/src/CLI/CommandLineProcessing.js

@@ -12,7 +12,7 @@ import {
 import { readFileSync, writeFileSync } from 'node:fs';
   
 // Import Commander.
-import { Command, InvalidArgumentError } from 'commander';
+import { Command } from 'commander';
   
 // Import package.json.
 import Package from '../../package.json' with { type: 'json' };
@@ -20,177 +20,172 @@ import Package from '../../package.json' with { type: 'json' };
 // Import isFile function.
 import { isFile } from './isFile.js';
 
+
+
 /**
  * Process command line arguments.
- * @function CommandLineProcessing
+ * @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);
-    })
+    .description('CLI for Extwee - A tool for compiling and decompiling Twine stories')
+    .version(Package.version, '-v, --version', 'Show version number')
     .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.`);
-      }
+    .option('--codejs <codeJSFile>', 'Twine 1 code.js file for use with Twine 1 HTML')
+    .option('--engine <engineFile>', 'Twine 1 engine.js file for use with Twine 1 HTML')
+    .option('--header <headerFile>', 'Twine 1 header.html file for use with Twine 1 HTML')
+    .option('-s <storyformat>, --storyformat <storyformat>', 'Path to story format file for Twine 2')
+    .option('-i <inputFile>, --input <inputFile>', 'Path to input file')
+    .option('-o <outputFile>, --output <outputFile>', 'Path to output file')
+    .addHelpText('after', `
+Examples:
+  Compile Twee to Twine 2 HTML:
+    extwee -c -i story.twee -o story.html -s format.js
+
+  Compile Twee to Twine 1 HTML:
+    extwee --twine1 -c -i story.twee -o story.html --name "Sugarcane" --engine engine.js --header header.html --codejs code.js
+
+  Decompile Twine 2 HTML to Twee:
+    extwee -d -i story.html -o story.twee
+
+  Decompile Twine 1 HTML to Twee:
+    extwee --twine1 -d -i story.html -o story.twee
+`);
+
+  // Parse the passed arguments with improved error handling
+  try {
+    program.parse(argv);
+    
+    // Get parsed options
+    const options = program.opts();
+    
+    // Validate and execute based on options
+    handleCommand(options);
+  } catch (error) {
+    if (error.code === 'commander.invalidArgument') {
+      console.error(`❌ ${error.message}`);
+    } else {
+      console.error(`❌ Error: ${error.message}`);
+    }
+    process.exit(1);
+  }
+}
 
-      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.`);
+/**
+ * Handle the parsed command with improved validation and error messages
+ * @param {object} options - Parsed command options
+ */
+function handleCommand(options) {
+  try {
+    // Commander uses the first option name as the property, so -i becomes 'i' and --input becomes 'input'
+    const inputFile = options.input || options.i;
+    const outputFile = options.output || options.o;
+    const storyFormatFile = options.storyformat || options.s;
+    
+    // Validate required options
+    if (!inputFile) {
+      throw new Error('Input file (-i, --input) is required');
+    }
+    if (!outputFile) {
+      throw new Error('Output file (-o, --output) is required');
+    }
+    
+    if (!options.compile && !options.decompile) {
+      throw new Error('Either --compile (-c) or --decompile (-d) must be specified');
+    }
+    
+    if (options.compile && options.decompile) {
+      throw new Error('Cannot specify both --compile and --decompile');
+    }
+
+    // Validate input file exists
+    if (!isFile(inputFile)) {
+      throw new Error(`Input file '${inputFile}' does not exist`);
+    }
+
+    const isTwine1Mode = options.twine1 === true;
+    const isDecompileMode = options.decompile === true;
+    const isCompileMode = options.compile === true;
+
+    if (isDecompileMode) {
+      // Decompile HTML to Twee
+      console.log(`🔄 Decompiling ${isTwine1Mode ? 'Twine 1' : 'Twine 2'} HTML to Twee...`);
+      
+      const inputHTML = readFileSync(inputFile, 'utf-8');
+      let storyObject;
+      
+      if (isTwine1Mode) {
+        storyObject = parseTwine1HTML(inputHTML);
+      } else {
+        storyObject = parseTwine2HTML(inputHTML);
       }
-
-      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.`);
+      
+      writeFileSync(outputFile, storyObject.toTwee());
+      console.log(`✅ Successfully decompiled '${inputFile}' to '${outputFile}'`);
+      
+    } else if (isCompileMode) {
+      // Compile Twee to HTML
+      console.log(`🔄 Compiling Twee to ${isTwine1Mode ? 'Twine 1' : 'Twine 2'} HTML...`);
+      
+      const inputTwee = readFileSync(inputFile, 'utf-8');
+      const story = parseTwee(inputTwee);
+      
+      if (isTwine1Mode) {
+        // Validate Twine 1 required options and files
+        const requiredOptions = [
+          { opt: 'engine', desc: 'engine.js file' },
+          { opt: 'header', desc: 'header.html file' },
+          { opt: 'name', desc: 'story format name' },
+          { opt: 'codejs', desc: 'code.js file' }
+        ];
+        
+        const missingOptions = requiredOptions.filter(({ opt }) => !options[opt]);
+        if (missingOptions.length > 0) {
+          throw new Error(`Twine 1 compilation requires the following options: ${missingOptions.map(({ opt }) => `--${opt}`).join(', ')}`);
+        }
+        
+        // Validate required files exist
+        const requiredFiles = ['engine', 'header', 'codejs'];
+        for (const fileOpt of requiredFiles) {
+          if (!isFile(options[fileOpt])) {
+            throw new Error(`Twine 1 ${fileOpt} file '${options[fileOpt]}' does not exist`);
+          }
+        }
+        
+        const Twine1HTML = compileTwine1HTML(story, options.engine, options.header, options.name, options.codejs);
+        writeFileSync(outputFile, Twine1HTML);
+      } else {
+        // Validate Twine 2 required options
+        if (!storyFormatFile) {
+          throw new Error('Twine 2 compilation requires --storyformat option');
+        }
+        
+        if (!isFile(storyFormatFile)) {
+          throw new Error(`Story format file '${storyFormatFile}' does not exist`);
+        }
+        
+        const inputStoryFormat = readFileSync(storyFormatFile, 'utf-8');
+        const parsedStoryFormat = parseStoryFormat(inputStoryFormat);
+        const Twine2HTML = compileTwine2HTML(story, parsedStoryFormat);
+        writeFileSync(outputFile, Twine2HTML);
       }
-
-      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;
+      
+      console.log(`✅ Successfully compiled '${inputFile}' to '${outputFile}'`);
+    }
+  } catch (error) {
+    console.error(`❌ Operation failed: ${error.message}`);
+    process.exit(1);
   }
+}
 
-  // 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/Passage.js

@@ -1,4 +1,5 @@
 import { encode } from 'html-entities';
+import { escapeTweeMetacharacters } from './Twee/parse.js';
 
 /**
   * Passage class.
@@ -175,13 +176,14 @@ export default class Passage {
     // Start empty string.
     let content = '';
 
-    // Write the name.
-    content += `:: ${this.name}`;
+    // Write the name with proper escaping for metacharacters.
+    content += `:: ${escapeTweeMetacharacters(this.name)}`;
 
     // Test if it has any tags.
     if (this.tags.length > 0) {
-      // Write output of tags.
-      content += ` [${this.tags.join(' ')}]`;
+      // Write output of tags with proper escaping.
+      const escapedTags = this.tags.map(tag => escapeTweeMetacharacters(tag));
+      content += ` [${escapedTags.join(' ')}]`;
     }
 
     // Check if any properties exist.

package/src/Story.js

@@ -7,7 +7,7 @@ import { encode } from 'html-entities';
 const creatorName = 'extwee';
 
 // Set the creator version.
-const creatorVersion = '2.3.4';
+const creatorVersion = '2.3.5';
 
 /**
  * Story class.

package/src/Twee/parse.js

@@ -1,6 +1,108 @@
 import Passage from '../Passage.js';
 import { Story } from '../Story.js';
 
+/**
+ * Unescapes Twee 3 metacharacters according to the specification.
+ *
+ * From the Twee 3 specification:
+ * - Encoding: To avoid ambiguity, non-escape backslashes must also be escaped via
+ * the same mechanism (i.e. `foo\bar` must become `foo\\bar`).
+ * - Decoding: To make decoding more robust, any escaped character within a chunk of
+ * encoded text must yield the character minus the backslash (i.e. `\q` must yield `q`).
+ * @function unescapeTweeMetacharacters
+ * @param {string} text - Text to unescape
+ * @returns {string} Unescaped text
+ */
+function unescapeTweeMetacharacters(text) {
+  if (typeof text !== 'string') {
+    return text;
+  }
+  
+  // Replace any escaped character with the character minus the backslash
+  // This implements the robust decoding rule from the specification
+  return text.replace(/\\(.)/g, '$1');
+}
+
+/**
+ * Escapes Twee 3 metacharacters according to the specification.
+ * This is used when writing Twee files to ensure special characters are properly escaped.
+ * @function escapeTweeMetacharacters
+ * @param {string} text - Text to escape
+ * @returns {string} Escaped text
+ */
+function escapeTweeMetacharacters(text) {
+  if (typeof text !== 'string') {
+    return text;
+  }
+  
+  // First escape backslashes, then escape the metacharacters
+  return text
+    .replace(/\\/g, '\\\\')  // Escape backslashes first
+    .replace(/\[/g, '\\[')   // Escape opening square brackets
+    .replace(/\]/g, '\\]')   // Escape closing square brackets
+    .replace(/\{/g, '\\{')   // Escape opening curly braces
+    .replace(/\}/g, '\\}');  // Escape closing curly braces
+}
+
+/**
+ * Finds the last unescaped occurrence of a character in a string.
+ * @param {string} str - String to search in
+ * @param {string} char - Character to find
+ * @returns {number} Position of last unescaped occurrence, or -1 if not found
+ */
+function findLastUnescaped(str, char) {
+  for (let i = str.length - 1; i >= 0; i--) {
+    if (str[i] === char) {
+      // Count consecutive backslashes before this character
+      let backslashCount = 0;
+      for (let j = i - 1; j >= 0 && str[j] === '\\'; j--) {
+        backslashCount++;
+      }
+      // If even number of backslashes (including 0), the character is not escaped
+      if (backslashCount % 2 === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+
+/**
+ * Parses metadata from a header string, respecting escaped characters.
+ * @param {string} header - Header string to parse
+ * @returns {object | null} Object with {metadata, remainingHeader} or null if no metadata
+ */
+function parseMetadataFromHeader(header) {
+  const openingPos = findLastUnescaped(header, '{');
+  const closingPos = findLastUnescaped(header, '}');
+  
+  if (openingPos !== -1 && closingPos !== -1 && closingPos > openingPos) {
+    const metadata = header.slice(openingPos, closingPos + 1);
+    const remainingHeader = header.substring(0, openingPos) + header.substring(closingPos + 1);
+    return { metadata, remainingHeader };
+  }
+  
+  return null;
+}
+
+/**
+ * Parses tags from a header string, respecting escaped characters.
+ * @param {string} header - Header string to parse
+ * @returns {object | null} Object with {tags, remainingHeader} or null if no tags
+ */
+function parseTagsFromHeader(header) {
+  const openingPos = findLastUnescaped(header, '[');
+  const closingPos = findLastUnescaped(header, ']');
+  
+  if (openingPos !== -1 && closingPos !== -1 && closingPos > openingPos) {
+    const tags = header.slice(openingPos, closingPos + 1);
+    const remainingHeader = header.substring(0, openingPos) + header.substring(closingPos + 1);
+    return { tags, remainingHeader };
+  }
+  
+  return null;
+}
+
 /**
  * Parses Twee 3 text into a Story object.
  * @see {@link https://github.com/iftechfoundation/twine-specs/blob/master/twee-3-specification.md Twee 3 Specification}
@@ -51,16 +153,11 @@ function parse (fileContents) {
     // (And trim any remaining whitespace.)
     text = passage.substring(header.length + 1, passage.length).trim();
 
-    // Test for metadata
-    const openingCurlyBracketPosition = header.lastIndexOf('{');
-    const closingCurlyBracketPosition = header.lastIndexOf('}');
-
-    if (openingCurlyBracketPosition !== -1 && closingCurlyBracketPosition !== -1) {
-      // Save the text metadata
-      metadata = header.slice(openingCurlyBracketPosition, closingCurlyBracketPosition + 1);
-
-      // Remove the metadata from the header
-      header = header.substring(0, openingCurlyBracketPosition) + header.substring(closingCurlyBracketPosition + 1);
+    // Parse metadata using escape-aware logic
+    const metadataMatch = parseMetadataFromHeader(header);
+    if (metadataMatch) {
+      metadata = metadataMatch.metadata;
+      header = metadataMatch.remainingHeader;
     }
 
     // There was passage metadata
@@ -77,15 +174,11 @@ function parse (fileContents) {
       metadata = {};
     }
 
-    // Test for tags
-    const openingSquareBracketPosition = header.lastIndexOf('[');
-    const closingSquareBracketPosition = header.lastIndexOf(']');
-
-    if (openingSquareBracketPosition !== -1 && closingSquareBracketPosition !== -1) {
-      tags = header.slice(openingSquareBracketPosition, closingSquareBracketPosition + 1);
-
-      // Remove the tags from the header
-      header = header.substring(0, openingSquareBracketPosition) + header.substring(closingSquareBracketPosition + 1);
+    // Parse tags using escape-aware logic
+    const tagsMatch = parseTagsFromHeader(header);
+    if (tagsMatch) {
+      tags = tagsMatch.tags;
+      header = tagsMatch.remainingHeader;
     }
 
     // Parse tags
@@ -138,12 +231,15 @@ function parse (fileContents) {
 
     // Check if there is a name left
     if (header.length > 0) {
-      name = header;
+      name = unescapeTweeMetacharacters(header);
     } else {
       // No name left. Something went wrong. Blame user.
       throw new Error('Malformed passage header!');
     }
 
+    // Unescape tag names according to Twee 3 specification
+    tags = tags.map(tag => unescapeTweeMetacharacters(tag));
+
     // addPassage() method does all the work.
     story.addPassage(new Passage(name, text, tags, metadata, pid));
 
@@ -155,4 +251,4 @@ function parse (fileContents) {
   return story;
 }
 
-export { parse };
+export { parse, escapeTweeMetacharacters, unescapeTweeMetacharacters };

package/test/Objects/Passage.test.js

@@ -219,7 +219,7 @@ describe('Passage', () => {
 
     it('Should escape meta-characters safely in Twee header', function () {
       const p = new Passage('Where do tags begin? [well', '', ['hmm']);
-      expect(p.toTwee().includes('Where do tags begin? [well [hmm]')).toBe(true);
+      expect(p.toTwee().includes('Where do tags begin? \\[well [hmm]')).toBe(true);
     });
 
     it('Should produce valid HTML attributes', function () {