extwee 2.2.6 → 2.3.0

package/src/CLI/isDirectory.js

@@ -0,0 +1,27 @@
+import { statSync } from 'node:fs';
+
+/*
+ * Check if a passed option is a valid directory.
+ * @function isDirectory
+ * @description Check if a directory exists.
+ * @param {string} path - Path to directory.
+ * @returns {boolean} True if directory exists, false if not.
+ */
+export const isDirectory = (path) => {
+  // set default.
+  let result = false;
+
+  try {
+    // Attempt t0 get stats.
+    const stats = statSync(path);
+
+    // Return if path is a directory.
+    result = stats.isDirectory();
+  } catch (e) {
+    // If there was an error, log it.
+    console.error(`Error: ${e}`);
+  }
+
+  // Return either the default (false) or the result (true).
+  return result;
+};

package/src/CLI/isFile.js

@@ -0,0 +1,28 @@
+// Import fs.
+import { statSync } from 'node:fs';
+
+/*
+ * Check if a passed option is a valid file.
+ * @function isFile
+ * @description Check if a file exists.
+ * @param {string} path - Path to file.
+ * @returns {boolean} True if file exists, false if not.
+ */
+export const isFile = (path) => {
+  // set default.
+  let result = false;
+
+  try {
+    // Attempt t0 get stats.
+    const stats = statSync(path);
+
+    // Return if path is a file.
+    result = stats.isFile();
+  } catch (e) {
+    // If there was an error, log it.
+    console.error(`Error: ${e}`);
+  }
+
+  // Return either the default (false) or the result (true).
+  return result;
+};

package/src/Config/parser.js

@@ -12,8 +12,11 @@ export function parser(obj) {
     // Extracted results.
     let results = {
         StoryFormat: null,
-        StoryTitle: null,
-        StoryVersion: null
+        Input: null,
+        Output: null,
+        Mode: null,
+        Twine1Project: false,
+        StoryFormatVersion: null
     };
     
     // Does the object contain 'StoryFormat'?
@@ -21,14 +24,33 @@ export function parser(obj) {
         results.StoryFormat = obj['story-format'];
     }
 
-    // Does the object contain 'StoryTitle'?
-    if (Object.hasOwnProperty.call(obj, 'story-title')) {
-        results.StoryTitle = obj['story-title'];
+    // Does the object contain 'StoryFormatVersion'?
+    if (Object.hasOwnProperty.call(obj, 'story-format-version')) {
+        results.StoryFormatVersion = obj['story-format-version'];
+    } else {
+        results.StoryFormatVersion = "latest";
     }
 
-    // Does the object contain 'StoryVersion'?
-    if (Object.hasOwnProperty.call(obj, 'story-version')) {
-        results.StoryVersion = obj['story-version'];
+    // Does the object contain 'mode'?
+    if (Object.hasOwnProperty.call(obj, 'mode')) {
+        results.Mode = obj['mode'];
+    }
+
+    // Does the object contain 'input'?
+    if (Object.hasOwnProperty.call(obj, 'input')) {
+        results.Input = obj['input'];
+    }
+
+    // Does the object contain 'output'?
+    if (Object.hasOwnProperty.call(obj, 'output')) {
+        results.Output = obj['output'];
+    }
+
+    // Does the object contain 'twine1-project'?
+    if (Object.hasOwnProperty.call(obj, 'twine1-project')) {
+        results.Twine1Project = obj['twine1-project'];
+    } else {
+        results.Twine1Project = false;
     }
 
     // Return the extracted results.

package/src/Passage.js

@@ -190,8 +190,23 @@ export default class Passage {
       content += ` ${JSON.stringify(this.metadata)}`;
     }
 
-    // Add newline, text, and two newlines.
-    content += `\n${this.text}\n\n`;
+    // Split the text into lines.
+    const lines = this.text.split('\n');
+
+    // For each line, check if it begins with a double-colon.
+    for (let i = 0; i < lines.length; i++) {
+      // Check if the line begins with a double-colon.
+      if (lines[i].startsWith('::')) {
+        // Escape the double-colon.
+        lines[i] = `\\${lines[i]}`;
+      }
+    }
+
+    // Rejoin the lines.
+    const output = lines.join('\n');
+
+    // Add newline and text.
+    content += `\n${output}\n\n`;
 
     // Return string.
     return content;

package/src/Story.js

@@ -2,10 +2,12 @@ import Passage from './Passage.js';
 import { generate as generateIFID } from './IFID/generate.js';
 import { encode } from 'html-entities';
 
+// Set the creator name.
+// This is used to identify the program that created the story.
 const creatorName = 'extwee';
 
 // Set the creator version.
-const creatorVersion = '2.2.6';
+const creatorVersion = '2.3.0';
 
 /**
  * Story class.
@@ -22,6 +24,8 @@ const creatorVersion = '2.2.6';
  * @property {string} creatorVersion - Version used to create Story.
  * @property {object} metadata - Metadata of Story.
  * @property {object} tagColors - Tag Colors
+ * @property {string} storyJavaScript - Story JavaScript
+ * @property {string} storyStylesheet - Story Stylesheet
  * @method {number} addPassage - Add a passage to the story and returns the new length of the passages array.
  * @method {number} removePassageByName - Remove a passage from the story by name and returns the new length of the passages array.
  * @method {Array} getPassagesByTag - Find passages by tag.
@@ -107,6 +111,18 @@ class Story {
    */
   #_tagColors = {};
 
+  /**
+   * Story JavaScript
+   * @private
+   */
+  #_storyJavaScript = '';
+
+  /**
+   * Story Stylesheet
+   * @private
+   */
+  #_storyStylesheet = '';
+
   /**
    * Creates a story.
    * @param {string} name - Name of the story.
@@ -322,6 +338,45 @@ class Story {
     }
   }
 
+  /**
+   * Story stylesheet data can be set as a passage, property value, or both.
+   * @returns {string} storyStylesheet
+   */
+  get storyStylesheet () {
+    return this.#_storyStylesheet;
+  }
+
+  /**
+   * @param {string} s - Replacement story stylesheet
+   */
+  set storyStylesheet (s) {
+    if (typeof s === 'string') {
+      this.#_storyStylesheet = s;
+    } else {
+      throw new Error('Story stylesheet must be a string!');
+    }
+  }
+
+  /** 
+   * Get story JavaScript.
+   * @returns {string} storyJavaScript
+   */
+  get storyJavaScript () {
+    return this.#_storyJavaScript;
+  }
+
+  /**
+   * Set story JavaScript.
+   * @param {string} s - Replacement story JavaScript
+   */
+  set storyJavaScript (s) {
+    if (typeof s === 'string') {
+      this.#_storyJavaScript = s;
+    } else {
+      throw new Error('Story JavaScript must be a string!');
+    }
+  }
+
   /**
    * Add a passage to the story.
    * Passing `StoryData` will override story metadata and `StoryTitle` will override story name.
@@ -484,6 +539,8 @@ class Story {
       creator: this.creator,
       creatorVersion: this.creatorVersion,
       zoom: this.zoom,
+      style: this.storyStylesheet,
+      script: this.storyJavaScript,
       passages: []
     };
 
@@ -595,6 +652,16 @@ class Story {
     // Add two newlines.
     outputContents += '\n\n';
 
+    // Write out the story stylesheet, if any.
+    if (this.#_storyStylesheet.length > 0) {
+      outputContents += ':: StoryStylesheet [stylesheet]\n' + this.#_storyStylesheet + '\n\n';
+    }
+
+    // Write out the story JavaScript, if any.
+    if (this.#_storyJavaScript.length > 0) {
+      outputContents += ':: StoryJavaScript [script]\n' + this.#_storyJavaScript + '\n\n';
+    }
+
     // For each passage, append it to the output.
     this.passages.forEach((passage) => {
       outputContents += passage.toTwee();
@@ -620,6 +687,10 @@ class Story {
    * - `format`: (string) Optional. The format of the story.
    * - `format-version`: (string) Optional. The version of the format of the story.
    * 
+   * Because story stylesheet data can be represented as a passage, property value, or both, all approaches are encoded.
+   * 
+   * Because story JavaScript can be represented as a passage, property value, or both, all approaches are encoded.
+   * 
    * @method toTwine2HTML
    * @returns {string} Twine 2 HTML string
    */
@@ -728,6 +799,9 @@ class Story {
     // Add the default attributes.
     storyData += ' options hidden>\n';
 
+    // We may have passages with tags of 'stylesheet', story stylesheet data, both, or none.
+
+    // Step 1: Add all passages with tag of 'stylesheet' to the stylesheet element.
     // Filter out passages with tag of 'stylesheet'.
     const stylesheetPassages = passages.filter((passage) => passage.tags.includes('stylesheet'));
 
@@ -749,6 +823,16 @@ class Story {
       storyData += '</style>\n';
     }
 
+    // Step 2: Check if the internal stylesheet data is empty.
+    // If it is not empty, add it to the stylesheet element.
+    if (this.#_storyStylesheet.length > 0) {
+      // Add the internal stylesheet.
+      storyData += `\t<style role="stylesheet" id="twine-user-stylesheet" type="text/twine-css">${this.#_storyStylesheet}</style>\n`;
+    }
+
+    // We may have passages with tags of 'script', story JavaScript data, both, or none.
+
+    // Step 1: Add all passages with tag of 'script' to the script element.
     // Filter out passages with tag of 'script'.
     const scriptPassages = passages.filter((passage) => passage.tags.includes('script'));
 
@@ -770,6 +854,13 @@ class Story {
       storyData += '</script>\n';
     }
 
+    // Step 2: Check if the internal JavaScript data is empty.
+    // If it is not empty, add it to the script element.
+    if (this.#_storyJavaScript.length > 0) {
+      // Add the internal JavaScript.
+      storyData += `\t<script role="script" id="twine-user-script" type="text/twine-javascript">${this.#_storyJavaScript}</script>\n`;
+    }
+
     // Reset the PID counter.
     PIDcounter = 1;
 

package/src/extwee.js

@@ -1,206 +1,31 @@
-#!/usr/bin/env node
+#! /usr/bin/env node
 
 /**
  * @file CLI for Extwee
  * @author Dan Cox
  */
 
-// Import functions we need.
-import {
-  parseTwine2HTML,
-  parseTwee,
-  parseStoryFormat,
-  parseTwine1HTML,
-  compileTwine2HTML,
-  compileTwine1HTML
-} from '../index.js';
+import { CommandLineProcessing } from "./CLI/CommandLineProcessing.js";
+import { ConfigFilePresent, ConfigFileProcessing } from "./CLI/ProcessConfig.js";
 
-// Import fs.
-import { readFileSync, writeFileSync, statSync } from 'node:fs';
-
-// Import Commander.
-import { Command, InvalidArgumentError } from 'commander';
-
-// Create a new Command.
-const program = new Command();
-
-/*
- * Check if a passed option is a valid file.
- * @function isFile
- * @description Check if a file exists.
- * @param {string} path - Path to file.
- * @returns {boolean} True if file exists, false if not.
- */
-const isFile = (path) => {
-  // set default.
-  let result = false;
-
-  try {
-    // Attempt tp get stats.
-    const stats = statSync(path);
-
-    // Return if path is a file.
-    result = stats.isFile();
-  } catch (e) {
-    // There was an error, so return false.
-    result = false;
-  }
-
-  // Return either the default (false) or the result (true).
-  return result;
-};
-
-program
-  .name('extwee')
-  .description('CLI for Extwee')
-  .option('-v, --version', '2.2.4')
-  .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(process.argv);
-
-// Create object of passed arguments parsed by Commander.
-const options = program.opts();
-
-/*
- * Prepare some (soon to be) global variables.
+/**
+ * As a command-line tool, Extwee can be invoked multiple ways.
+ * (1) Via NPX with command-line arguments. (process.argv.length > 2)
+ * (2) Via NPX in the presence of a `extwee.config.json` file.
  */
-// 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());
-
-  // Exit the process.
-  process.exit();
-}
-
-// 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.
-  process.exit();
+// Check if the command line arguments are present.
+if(process.argv.length > 2) {
+    // Process the command line arguments.
+    CommandLineProcessing(process.argv);
+    // Exit the process.
+    process.exit(0);
 }
 
-// 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.
-  process.exit();
-}
-
-// 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());
-
-  // Exit the process.
-  process.exit();
-}
+// Check if the config file exists.
+if(ConfigFilePresent()) {
+    // Process the config file.
+    ConfigFileProcessing();
+    // Exit the process.
+    process.exit(0);
+}

package/test/Config/Config.test.js

@@ -14,9 +14,10 @@ describe('src/Config/reader.js', () => {
         it('should return the parsed JSON contents of the file', () => {
             const contents = ConfigReader('test/Config/files/valid.json');
             expect(contents).toEqual({
-                "story-format": 'Harlowe',
-                "story-title": "My Story",
-                "story-version": "2.0.1"
+                "story-format": 'harlowe',
+                "mode": "decompile",
+                "input": "index.html",
+                "output": "index.twee"
             });
         });
     });
@@ -27,20 +28,49 @@ describe('src/Config/reader.js', () => {
             expect(() => ConfigParser('{')).toThrow();
         });
 
-        it('should extract the StoryFormat, StoryTitle, and StoryVersion from the JSON object', () => {
+        it('should extract the StoryFormat and StoryFormatVersion from the JSON object', () => {
             const jsonObject = ConfigReader('test/Config/files/valid.json');
             const contents = ConfigParser(jsonObject);
-            expect(contents.StoryFormat).toEqual('Harlowe');
-            expect(contents.StoryTitle).toEqual('My Story');
-            expect(contents.StoryVersion).toEqual('2.0.1');
+            expect(contents.StoryFormat).toEqual('harlowe');
+            expect(contents.StoryFormatVersion).toEqual('latest');
+            expect(contents.Input).toEqual('index.html');
+            expect(contents.Output).toEqual('index.twee');
+            expect(contents.Mode).toEqual('decompile');
+            expect(contents.Twine1Project).toEqual(false);
         });
 
-        it('should not extract the StoryFormat, StoryTitle, and StoryVersion if they do not exist in the JSON object', () => {
+        it('should not extract options if they do not exist in the JSON object', () => {
             const jsonObject = ConfigReader('test/Config/files/empty.json');
             const contents = ConfigParser(jsonObject);
             expect(contents.StoryFormat).toBeNull();
-            expect(contents.StoryTitle).toBeNull();
-            expect(contents.StoryVersion).toBeNull();
+            expect(contents.StoryFormatVersion).toBe('latest');
+            expect(contents.Input).toBeNull();
+            expect(contents.Output).toBeNull();
+            expect(contents.Mode).toBeNull();
+            expect(contents.Twine1Project).toBe(false);
+        });
+
+        it('should set StoryFormatVersion to "latest" if it is not present in the JSON object', () => {
+            const jsonObject = ConfigReader('test/Config/files/valid.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.StoryFormatVersion).toEqual('latest');
+        });
+
+        it('should set Twine1Project to false if it is not present in the JSON object', () => {
+            const jsonObject = ConfigReader('test/Config/files/valid.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.Twine1Project).toEqual(false);
+        });
+
+        it('Should read story-format, story-format-version, and twine1-project if present', () => {
+            const jsonObject = ConfigReader('test/Config/files/full.json');
+            const contents = ConfigParser(jsonObject);
+            expect(contents.StoryFormat).toEqual('harlowe');
+            expect(contents.StoryFormatVersion).toEqual('3.2.0');
+            expect(contents.Input).toEqual('index.twee');
+            expect(contents.Output).toEqual('index.html');
+            expect(contents.Mode).toEqual('compile');
+            expect(contents.Twine1Project).toEqual(false);
         });
     });
 });

package/test/Config/files/full.json

@@ -0,0 +1,8 @@
+{
+    "story-format": "harlowe",
+    "mode": "compile",
+    "input": "index.twee",
+    "output": "index.html",
+    "story-format-version": "3.2.0",
+    "twine1-project": false
+}

package/test/Config/files/valid.json

@@ -1,5 +1,6 @@
 {
-    "story-format": "Harlowe",
-    "story-title": "My Story",
-    "story-version": "2.0.1"
+    "story-format": "harlowe",
+    "mode": "decompile",
+    "input": "index.html",
+    "output": "index.twee"
 }

package/test/Config/isDirectory.test.js

@@ -0,0 +1,44 @@
+import { isDirectory } from '../../src/CLI/isDirectory';
+import { statSync } from 'node:fs';
+
+jest.mock('node:fs');
+
+describe('isDirectory', () => {
+    afterEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it('should return true if the path is a directory', () => {
+        const mockStats = { isDirectory: jest.fn(() => true) };
+        statSync.mockReturnValue(mockStats);
+
+        const result = isDirectory('/valid/directory/path');
+        expect(statSync).toHaveBeenCalledWith('/valid/directory/path');
+        expect(mockStats.isDirectory).toHaveBeenCalled();
+        expect(result).toBe(true);
+    });
+
+    it('should return false if the path is not a directory', () => {
+        const mockStats = { isDirectory: jest.fn(() => false) };
+        statSync.mockReturnValue(mockStats);
+
+        const result = isDirectory('/valid/file/path');
+        expect(statSync).toHaveBeenCalledWith('/valid/file/path');
+        expect(mockStats.isDirectory).toHaveBeenCalled();
+        expect(result).toBe(false);
+    });
+
+    it('should return false and log an error if statSync throws an error', () => {
+        const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+        statSync.mockImplementation(() => {
+            throw new Error('Test error');
+        });
+
+        const result = isDirectory('/invalid/path');
+        expect(statSync).toHaveBeenCalledWith('/invalid/path');
+        expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('Error: Test error'));
+        expect(result).toBe(false);
+
+        consoleErrorSpy.mockRestore();
+    });
+});