story-format-parser 0.0.0-stage → 1.0.2

package/.vscode/launch.json

@@ -0,0 +1,14 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "node",
+      "request": "launch",
+      "name": "Debug parseStory.js",
+      "program": "${workspaceFolder}/parseStory.js",
+      "skipFiles": [
+        "/**"
+      ]
+    }
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "files.associations": {
+    "*.story": "markdown"
+  }
+}

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# .STORY Format Parser & Serializer
+
+A lightweight JavaScript parser and serializer for the custom `.STORY` plain text file format. Built with zero dependencies and cross-environment compatibility for **Node.js** and **Browser** environments.
+
+---
+
+## Format Overview
+
+A `.STORY` document structures narrative data into days containing optional headers and body interactions.
+
+```story
+day: 1
+title: The Awakening
+weather: Rain
+---
+# First scene
+ALICE: Hello world! Time is 10:30 AM
+* Thunder rumbles in the distance.
+===
+day: 2
+title: Shadows
+mood: Tense
+---
+bob: What was that noise?
+* Steps echo down the hall.
+```
+
+---
+
+## Features
+
+- **Zero Dependencies:** Standard, vanilla JavaScript.
+- **Universal Export:** Works seamlessly across Node.js (`require`) and Browser (`<script>` tag) runtimes.
+- **Non-Throwing Parser:** Returns detailed `warnings` with line numbers for malformed lines instead of throwing syntax runtime errors.
+- **Full Serialization:** Losslessly converts structured story objects back into standard `.STORY` formatted text.
+
+---
+
+## Syntax Rules
+
+1. **Day Separator (`===`):** Separates days within a story file.
+2. **Header-Body Separator (`---`):** Divides header metadata from dialogue/narration lines within each day block.
+3. **Headers (`key: value`):** Reserved keys (`day`, `title`, `scene`, `mood`) map directly onto the day object. Custom/unknown keys are captured in `extra`.
+4. **Dialogue (`speaker: text`):** Dialogue lines are converted to lower-cased speaker identifiers (`speaker`) with body text (`text`).
+5. **Narration (`* text`):** Lines beginning with an asterisk are parsed as `type: "narration"`.
+6. **Comments (`# comment`):** Lines starting with `#` are ignored during parsing.
+
+---
+
+## Installation & Setup
+
+Clone the repository to your local machine:
+
+```bash
+git clone https://github.com/keane3029-lab/.story-format.git
+cd .story-format
+```
+
+---
+
+## Usage
+
+### Node.js
+
+```javascript
+const { parseStory, serializeStory } = require('./parseStory.js');
+
+const storyText = `
+day: 1
+title: Prologue
+---
+* The adventure begins.
+ALICE: Are you ready?
+`;
+
+// Parse text to object structure
+const { days, warnings } = parseStory(storyText);
+console.log(days);
+
+// Serialize object structure back to .STORY format
+const rawText = serializeStory(days);
+console.log(rawText);
+```
+
+### Browser
+
+```html
+<script src="parseStory.js"></script>
+<script>
+  const input = "day: 1\n---\nalice: Ready when you are.";
+  const { days, warnings } = parseStory(input);
+  console.log(days);
+</script>
+```
+
+---
+
+## Running Tests
+
+Run the built-in self-test script in Node.js:
+
+```bash
+npm test
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/open-storyfiles.py

@@ -0,0 +1,179 @@
+import os
+import re
+import json
+
+def parse_story(text: str) -> dict:
+    """
+    Parses raw .STORY format string into a structured dictionary.
+    Returns a dict containing 'days' list and 'warnings' list.
+    """
+    days = []
+    warnings = []
+
+    if not isinstance(text, str):
+        warnings.append({"line": 0, "message": "Input must be a string."})
+        return {"days": days, "warnings": warnings}
+
+    # Split by day delimiter '===' on its own line
+    raw_days = re.split(r'^===\s*$', text, flags=re.MULTILINE)
+
+    for day_text in raw_days:
+        lines = day_text.splitlines()
+        day_obj = {
+            "day": None,
+            "title": None,
+            "scene": None,
+            "mood": None,
+            "extra": {},
+            "entries": []
+        }
+
+        in_header = True
+
+        for line_idx, line in enumerate(lines):
+            line_num = line_idx + 1
+            trimmed = line.strip()
+
+            # Ignore empty lines and comments
+            if not trimmed or trimmed.startswith("#"):
+                continue
+
+            # Check for header/body separator '---'
+            if in_header and re.match(r'^---\s*$', trimmed):
+                in_header = False
+                continue
+
+            if in_header:
+                if ":" not in line:
+                    warnings.append({
+                        "line": line_num,
+                        "message": f'Invalid header syntax: missing colon in line "{trimmed}"'
+                    })
+                    continue
+
+                key, value = line.split(":", 1)
+                key = key.strip().lower()
+                value = value.strip()
+
+                if key in ["day", "title", "scene", "mood"]:
+                    if key == "day":
+                        try:
+                            day_obj["day"] = int(value)
+                        except ValueError:
+                            day_obj["day"] = value
+                    else:
+                        day_obj[key] = value
+                else:
+                    day_obj["extra"][key] = value
+            else:
+                # Body parsing (dialogue vs narration)
+                if trimmed.startswith("*"):
+                    narration_text = trimmed[1:].strip()
+                    day_obj["entries"].append({
+                        "type": "narration",
+                        "speaker": None,
+                        "text": narration_text
+                    })
+                else:
+                    if ":" not in line:
+                        warnings.append({
+                            "line": line_num,
+                            "message": f'Invalid dialogue syntax: missing speaker colon in line "{trimmed}"'
+                        })
+                        # Fallback as narration
+                        day_obj["entries"].append({
+                            "type": "narration",
+                            "speaker": None,
+                            "text": trimmed
+                        })
+                        continue
+
+                    speaker, entry_text = line.split(":", 1)
+                    speaker = speaker.strip().lower()
+                    entry_text = entry_text.strip()
+
+                    day_obj["entries"].append({
+                        "type": "dialogue",
+                        "speaker": speaker,
+                        "text": entry_text
+                    })
+
+        if day_obj["day"] is not None or len(day_obj["entries"]) > 0 or len(day_obj["extra"]) > 0:
+            days.append(day_obj)
+
+    return {"days": days, "warnings": warnings}
+
+
+def load_story_file(file_path: str) -> dict:
+    """
+    Opens and parses a .STORY file from disk.
+    """
+    if not os.path.exists(file_path):
+        raise FileNotFoundError(f"Story file not found at path: {file_path}")
+
+    with open(file_path, "r", encoding="utf-8") as f:
+        content = f.read()
+
+    return parse_story(content)
+
+
+def serialize_story(days: list) -> str:
+    """
+    Serializes a list of day dictionaries back into .STORY formatted plain text.
+    """
+    if not isinstance(days, list):
+        return ""
+
+    day_blocks = []
+    for day_obj in days:
+        header_lines = []
+
+        if day_obj.get("day") is not None:
+            header_lines.append(f"day: {day_obj['day']}")
+        if day_obj.get("title"):
+            header_lines.append(f"title: {day_obj['title']}")
+        if day_obj.get("scene"):
+            header_lines.append(f"scene: {day_obj['scene']}")
+        if day_obj.get("mood"):
+            header_lines.append(f"mood: {day_obj['mood']}")
+
+        extra = day_obj.get("extra", {})
+        if isinstance(extra, dict):
+            for k, v in extra.items():
+                header_lines.append(f"{k}: {v}")
+
+        body_lines = []
+        for entry in day_obj.get("entries", []):
+            if entry.get("type") == "narration" or not entry.get("speaker"):
+                body_lines.append(f"* {entry.get('text', '')}")
+            else:
+                body_lines.append(f"{entry.get('speaker', '')}: {entry.get('text', '')}")
+
+        full_block = "\n".join(header_lines) + "\n---\n" + "\n".join(body_lines)
+        day_blocks.append(full_block)
+
+    return "\n===\n".join(day_blocks)
+
+
+# Quick runner test when executed directly
+if __name__ == "__main__":
+    sample_file = "sample.story"
+    
+    if os.path.exists(sample_file):
+        print(f"=== READING {sample_file} ===")
+        result = load_story_file(sample_file)
+        print("Parsed JSON Output:")
+        print(json.dumps(result["days"], indent=2))
+        print("\nWarnings:", result["warnings"])
+    else:
+        print(f"File {sample_file} not found. Running inline test.")
+        sample_data = """day: 1
+title: The Python Awakening
+scene: Code Room
+---
+# Python parser test
+python_bot: Hello from Python land!
+* The script executes flawlessly.
+"""
+        result = parse_story(sample_data)
+        print(json.dumps(result["days"], indent=2))

package/package.json

@@ -1,6 +1,17 @@
-{
-  "name": "story-format-parser",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "story-format-parser",
+  "version": "1.0.2",
+  "description": "Parser and serializer for the .STORY plain text file format.",
+  "main": "parseStory.js",
+  "scripts": {
+    "test": "node parseStory.js"
+  },
+  "keywords": [
+    "story",
+    "parser",
+    "interactive-fiction",
+    "text-format"
+  ],
+  "author": "",
+  "license": "MIT"
+}

package/parseStory.js

@@ -0,0 +1,146 @@
+/**
+ * .STORY Format Parser, Serializer, and File Reader
+ * Zero-dependency universal library (Node.js & Browser)
+ */
+
+function parseStory(text) {
+  const days = [];
+  const warnings = [];
+
+  if (typeof text !== "string") {
+    warnings.push({ line: 0, message: "Input must be a string." });
+    return { days, warnings };
+  }
+
+  const rawDays = text.split(/^===\s*$/m);
+
+  rawDays.forEach((dayText, dayIdx) => {
+    const lines = dayText.split(/\r?\n/);
+    const dayObj = {
+      day: null,
+      title: null,
+      scene: null,
+      mood: null,
+      extra: {},
+      entries: []
+    };
+
+    let inHeader = true;
+
+    lines.forEach((line, lineIdx) => {
+      const lineNum = lineIdx + 1;
+      const trimmed = line.trim();
+
+      // Ignore empty lines and comments
+      if (!trimmed || trimmed.startsWith("#")) {
+        return;
+      }
+
+      // Check header/body separator
+      if (inHeader && /^---\s*$/.test(trimmed)) {
+        inHeader = false;
+        return;
+      }
+
+      if (inHeader) {
+        const colonIndex = line.indexOf(":");
+        if (colonIndex === -1) {
+          warnings.push({
+            line: lineNum,
+            message: `Invalid header syntax: missing colon in line "${trimmed}"`
+          });
+          return;
+        }
+
+        const key = line.slice(0, colonIndex).trim().toLowerCase();
+        const value = line.slice(colonIndex + 1).trim();
+
+        if (["day", "title", "scene", "mood"].includes(key)) {
+          if (key === "day") {
+            const parsedDay = parseInt(value, 10);
+            dayObj.day = isNaN(parsedDay) ? value : parsedDay;
+          } else {
+            dayObj[key] = value;
+          }
+        } else {
+          dayObj.extra[key] = value;
+        }
+      } else {
+        // Parsing body (dialogue and narration)
+        if (trimmed.startsWith("*")) {
+          // Narration
+          const narrationText = trimmed.slice(1).trim();
+          dayObj.entries.push({
+            type: "narration",
+            speaker: null,
+            text: narrationText
+          });
+        } else {
+          // Dialogue
+          const colonIndex = line.indexOf(":");
+          if (colonIndex === -1) {
+            warnings.push({
+              line: lineNum,
+              message: `Invalid dialogue syntax: missing speaker colon in line "${trimmed}"`
+            });
+            // Fallback as unformatted narration
+            dayObj.entries.push({
+              type: "narration",
+              speaker: null,
+              text: trimmed
+            });
+            return;
+          }
+
+          const speaker = line.slice(0, colonIndex).trim().toLowerCase();
+          const text = line.slice(colonIndex + 1).trim();
+
+          dayObj.entries.push({
+            type: "dialogue",
+            speaker,
+            text
+          });
+        }
+      }
+    });
+
+    if (dayObj.day !== null || dayObj.entries.length > 0 || Object.keys(dayObj.extra).length > 0) {
+      days.push(dayObj);
+    }
+  });
+
+  return { days, warnings };
+}
+
+function serializeStory(days) {
+  if (!Array.isArray(days)) return "";
+
+  return days.map(dayObj => {
+    const headerLines = [];
+
+    if (dayObj.day !== null && dayObj.day !== undefined) headerLines.push(`day: ${dayObj.day}`);
+    if (dayObj.title) headerLines.push(`title: ${dayObj.title}`);
+    if (dayObj.scene) headerLines.push(`scene: ${dayObj.scene}`);
+    if (dayObj.mood) headerLines.push(`mood: ${dayObj.mood}`);
+
+    if (dayObj.extra && typeof dayObj.extra === "object") {
+      Object.entries(dayObj.extra).forEach(([k, v]) => {
+        headerLines.push(`\({k}:\){v}`);
+      });
+    }
+
+    const bodyLines = (dayObj.entries || []).map(entry => {
+      if (entry.type === "narration" || !entry.speaker) {
+        return `* ${entry.text}`;
+      }
+      return `\({entry.speaker}:\){entry.text}`;
+    });
+
+    return [...headerLines, "---", ...bodyLines].join("\n");
+  }).join("\n===\n");
+}
+
+/**
+ * Reads and parses a .STORY file asynchronously in Node.js.
+ * @param {string} filePath - Path to the .STORY file.
+ * @returns {Promise<{ days: Array 

package/sample.story

@@ -0,0 +1,3 @@
+day: 1
+title: The Awakening
+weather: Rain