legal-markdown-js 2.8.1 → 2.9.0

package/README.md

@@ -41,6 +41,9 @@ After installation, you'll have access to these commands:
 
 - **`legal-md`** - Standard command-line interface with options and flags
 - **`legal-md-ui`** - Interactive CLI with guided prompts and smart defaults
+- **`legal-md-setup`** - Configuration setup script for easy environment setup
+- **`legal-md-playground`** - Local playground server for testing and
+  exploration
 - **`legal2md`** - Alias for `legal-md` (for compatibility)
 
 ## 🚀 Try it Online
@@ -49,8 +52,42 @@ After installation, you'll have access to these commands:
 Markdown JS directly in your browser with live examples and real-time
 processing.
 
+### Local Playground
+
+You can also run the playground locally for offline use or testing:
+
+```bash
+# Start local playground server (when installed globally)
+legal-md-playground
+
+# Or with custom port
+legal-md-playground --port=3000
+
+# Or if installed locally in a project
+npm run web:serve
+```
+
+The playground provides the same interactive experience as the online version,
+including real-time processing, syntax highlighting, and example templates.
+
 ## Quick Start
 
+### Initial Setup (Optional)
+
+For the best experience, especially if you're new to Legal Markdown JS, run the
+setup script to configure your environment:
+
+```bash
+# Configure paths and directories (when installed globally)
+legal-md-setup
+
+# Or if installed locally in a project
+npm run setup-config
+```
+
+This creates a personalized configuration file that the tool will automatically
+find and use.
+
 ### Command Line Usage
 
 #### Standard CLI
@@ -250,9 +287,33 @@ npm run test:coverage
 Legal Markdown JS supports environment-based configuration for customizing file
 paths and directories.
 
-### Environment Variables
+### Quick Setup (Recommended)
+
+For easy configuration setup, especially for non-technical users:
+
+```bash
+# Run the setup script (when installed globally)
+legal-md-setup
+
+# Or if installed locally in a project
+npm run setup-config
+```
+
+This script will:
+
+- Create a configuration directory at `~/.config/legal-markdown-js/`
+- Copy the configuration template with helpful comments
+- Provide clear instructions on how to customize your paths
+- Show you exactly where to edit your settings
+
+### Manual Configuration
+
+If you prefer manual setup, create a `.env` file in one of these locations (in
+order of precedence):
 
-Create a `.env` file in your project root to customize default paths:
+1. **Current working directory**: `./.env`
+2. **Your home directory**: `~/.env`
+3. **Config directory**: `~/.config/legal-markdown-js/.env`
 
 ```bash
 # Copy the example configuration

package/dist/cli/interactive/utils/format-helpers.js

@@ -29,7 +29,7 @@ function formatConfigSummary(config) {
     const { inputFile, outputFilename, outputFormats, processingOptions, cssFile } = config;
     let summary = chalk_1.default.bold.cyan('\n📋 Configuration Summary:\n\n');
     // Input file
-    summary += `📁 ${chalk_1.default.bold('Input file:')} ${inputFile}\n`;
+    summary += `📄 ${chalk_1.default.bold('Input file:')} ${inputFile}\n`;
     // Output filename
     summary += `📝 ${chalk_1.default.bold('Output filename:')} ${outputFilename}\n`;
     // Output formats

package/dist/constants/paths.d.ts

@@ -4,6 +4,11 @@
  * This module provides centralized access to path constants loaded from
  * environment variables via dotenv. It ensures consistent path usage
  * across the application and provides sensible defaults.
+ *
+ * The .env file is discovered from multiple locations in order of precedence:
+ * 1. Current working directory
+ * 2. User's home directory
+ * 3. User's config directory (~/.config/legal-markdown-js/)
  */
 /**
  * Path constants loaded from environment variables

package/dist/constants/paths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/constants/paths.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAQH;;GAEG;AACH,eAAO,MAAM,KAAK;IAChB;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC"}
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/constants/paths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH;;GAEG;AACH,eAAO,MAAM,KAAK;IAChB;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;OAGG;;CAEK,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,cAAc;;;;;CAKjB,CAAC"}

package/dist/constants/paths.js

@@ -5,6 +5,11 @@
  * This module provides centralized access to path constants loaded from
  * environment variables via dotenv. It ensures consistent path usage
  * across the application and provides sensible defaults.
+ *
+ * The .env file is discovered from multiple locations in order of precedence:
+ * 1. Current working directory
+ * 2. User's home directory
+ * 3. User's config directory (~/.config/legal-markdown-js/)
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -41,10 +46,14 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RESOLVED_PATHS = exports.PATHS = void 0;
-const dotenv_1 = require("dotenv");
 const path = __importStar(require("path"));
-// Load environment variables from .env file
-(0, dotenv_1.config)({ debug: false });
+const env_discovery_1 = require("../utils/env-discovery");
+// Discover and load environment variables from .env file
+const loadedEnvPath = (0, env_discovery_1.discoverAndLoadEnv)();
+// Optional: Log which .env file was loaded for debugging
+if (process.env.NODE_ENV !== 'test' && process.env.NODE_ENV !== 'ci' && loadedEnvPath) {
+    console.log(`Loaded environment configuration from: ${loadedEnvPath}`);
+}
 /**
  * Path constants loaded from environment variables
  */

package/dist/constants/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/constants/paths.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,mCAAgC;AAChC,2CAA6B;AAE7B,4CAA4C;AAC5C,IAAA,eAAM,EAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;AAEzB;;GAEG;AACU,QAAA,KAAK,GAAG;IACnB;;;OAGG;IACH,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,mBAAmB;IAExE;;;OAGG;IACH,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,YAAY;IAEjE;;;OAGG;IACH,iBAAiB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,OAAO;IAE1E;;;OAGG;IACH,kBAAkB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,QAAQ;CACrE,CAAC;AAEX;;GAEG;AACU,QAAA,cAAc,GAAG;IAC5B,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,UAAU,CAAC;IACzD,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,UAAU,CAAC;IACzD,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,iBAAiB,CAAC;IACvE,kBAAkB,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,kBAAkB,CAAC;CACjE,CAAC"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/constants/paths.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAEH,2CAA6B;AAC7B,0DAA4D;AAE5D,yDAAyD;AACzD,MAAM,aAAa,GAAG,IAAA,kCAAkB,GAAE,CAAC;AAE3C,yDAAyD;AACzD,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,IAAI,IAAI,aAAa,EAAE,CAAC;IACtF,OAAO,CAAC,GAAG,CAAC,0CAA0C,aAAa,EAAE,CAAC,CAAC;AACzE,CAAC;AAED;;GAEG;AACU,QAAA,KAAK,GAAG;IACnB;;;OAGG;IACH,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,mBAAmB;IAExE;;;OAGG;IACH,UAAU,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,YAAY;IAEjE;;;OAGG;IACH,iBAAiB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,OAAO;IAE1E;;;OAGG;IACH,kBAAkB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,QAAQ;CACrE,CAAC;AAEX;;GAEG;AACU,QAAA,cAAc,GAAG;IAC5B,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,UAAU,CAAC;IACzD,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,UAAU,CAAC;IACzD,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,iBAAiB,CAAC;IACvE,kBAAkB,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,aAAK,CAAC,kBAAkB,CAAC;CACjE,CAAC"}

package/dist/utils/env-discovery.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment File Discovery Utility
+ *
+ * This module provides functionality to discover .env files in multiple
+ * locations to improve user experience, especially for non-developer users.
+ * It searches for .env files in the following order:
+ * 1. Current working directory
+ * 2. User's home directory
+ * 3. User's config directory (~/.config/legal-markdown-js/)
+ */
+/**
+ * Discovers and loads .env file from multiple possible locations
+ *
+ * @returns The path of the loaded .env file or null if none found
+ */
+export declare function discoverAndLoadEnv(): string | null;
+/**
+ * Gets all potential .env file locations for informational purposes
+ *
+ * @returns Array of potential .env file paths
+ */
+export declare function getEnvSearchPaths(): string[];
+/**
+ * Creates the config directory if it doesn't exist
+ *
+ * @returns The path to the config directory
+ */
+export declare function ensureConfigDirectory(): string;
+/**
+ * Creates a sample .env file in the user's config directory
+ *
+ * @returns The path where the sample was created or null if failed
+ */
+export declare function createSampleEnvFile(): string | null;
+//# sourceMappingURL=env-discovery.d.ts.map

package/dist/utils/env-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-discovery.d.ts","sourceRoot":"","sources":["../../src/utils/env-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqBH;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CAiBlD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CAa9C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAgCnD"}

package/dist/utils/env-discovery.js

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Environment File Discovery Utility
+ *
+ * This module provides functionality to discover .env files in multiple
+ * locations to improve user experience, especially for non-developer users.
+ * It searches for .env files in the following order:
+ * 1. Current working directory
+ * 2. User's home directory
+ * 3. User's config directory (~/.config/legal-markdown-js/)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discoverAndLoadEnv = discoverAndLoadEnv;
+exports.getEnvSearchPaths = getEnvSearchPaths;
+exports.ensureConfigDirectory = ensureConfigDirectory;
+exports.createSampleEnvFile = createSampleEnvFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+const dotenv_1 = require("dotenv");
+/**
+ * Potential locations for .env files in order of precedence
+ */
+const ENV_SEARCH_PATHS = [
+    // 1. Current working directory (highest precedence)
+    () => path.join(process.cwd(), '.env'),
+    // 2. User's home directory
+    () => path.join(os.homedir(), '.env'),
+    // 3. User's config directory
+    () => path.join(os.homedir(), '.config', 'legal-markdown-js', '.env'),
+];
+/**
+ * Discovers and loads .env file from multiple possible locations
+ *
+ * @returns The path of the loaded .env file or null if none found
+ */
+function discoverAndLoadEnv() {
+    for (const getPath of ENV_SEARCH_PATHS) {
+        const envPath = getPath();
+        try {
+            if (fs.existsSync(envPath) && fs.statSync(envPath).isFile()) {
+                // Load the .env file
+                (0, dotenv_1.config)({ path: envPath, debug: false });
+                return envPath;
+            }
+        }
+        catch (error) {
+            // Continue to next location if this one fails
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Gets all potential .env file locations for informational purposes
+ *
+ * @returns Array of potential .env file paths
+ */
+function getEnvSearchPaths() {
+    return ENV_SEARCH_PATHS.map(getPath => getPath());
+}
+/**
+ * Creates the config directory if it doesn't exist
+ *
+ * @returns The path to the config directory
+ */
+function ensureConfigDirectory() {
+    const configDir = path.join(os.homedir(), '.config', 'legal-markdown-js');
+    try {
+        if (!fs.existsSync(configDir)) {
+            fs.mkdirSync(configDir, { recursive: true });
+        }
+    }
+    catch (error) {
+        // If we can't create the directory, that's okay
+        // The user can still use other locations
+    }
+    return configDir;
+}
+/**
+ * Creates a sample .env file in the user's config directory
+ *
+ * @returns The path where the sample was created or null if failed
+ */
+function createSampleEnvFile() {
+    try {
+        const configDir = ensureConfigDirectory();
+        const samplePath = path.join(configDir, '.env');
+        // Don't overwrite existing file
+        if (fs.existsSync(samplePath)) {
+            return samplePath;
+        }
+        const sampleContent = `# Legal Markdown - User Configuration
+# This file was automatically created in your config directory
+# Customize these paths according to your needs
+
+# Directory containing image assets (logos, diagrams, etc.)
+IMAGES_DIR=src/assets/images
+
+# Directory containing CSS stylesheets  
+STYLES_DIR=src/styles
+
+# Default directory for input documents
+DEFAULT_INPUT_DIR=input
+
+# Default directory for output documents
+DEFAULT_OUTPUT_DIR=output
+`;
+        fs.writeFileSync(samplePath, sampleContent, 'utf8');
+        return samplePath;
+    }
+    catch (error) {
+        return null;
+    }
+}
+//# sourceMappingURL=env-discovery.js.map

package/dist/utils/env-discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-discovery.js","sourceRoot":"","sources":["../../src/utils/env-discovery.ts"],"names":[],"mappings":";AAAA;;;;;;;;;GASG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0BH,gDAiBC;AAOD,8CAEC;AAOD,sDAaC;AAOD,kDAgCC;AA7GD,uCAAyB;AACzB,2CAA6B;AAC7B,uCAAyB;AACzB,mCAAgC;AAEhC;;GAEG;AACH,MAAM,gBAAgB,GAAG;IACvB,oDAAoD;IACpD,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC;IAEtC,2BAA2B;IAC3B,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,MAAM,CAAC;IAErC,6BAA6B;IAC7B,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,CAAC;CACtE,CAAC;AAEF;;;;GAIG;AACH,SAAgB,kBAAkB;IAChC,KAAK,MAAM,OAAO,IAAI,gBAAgB,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC;QAE1B,IAAI,CAAC;YACH,IAAI,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC5D,qBAAqB;gBACrB,IAAA,eAAM,EAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBACxC,OAAO,OAAO,CAAC;YACjB,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,8CAA8C;YAC9C,SAAS;QACX,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAgB,iBAAiB;IAC/B,OAAO,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;GAIG;AACH,SAAgB,qBAAqB;IACnC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,mBAAmB,CAAC,CAAC;IAE1E,IAAI,CAAC;QACH,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAC9B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,gDAAgD;QAChD,yCAAyC;IAC3C,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB;IACjC,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,qBAAqB,EAAE,CAAC;QAC1C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QAEhD,gCAAgC;QAChC,IAAI,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC9B,OAAO,UAAU,CAAC;QACpB,CAAC;QAED,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;CAezB,CAAC;QAEE,EAAE,CAAC,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QACpD,OAAO,UAAU,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "legal-markdown-js",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Node.js implementation of LegalMarkdown for processing legal documents with markdown and YAML - Complete feature parity with Ruby version",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -44,7 +44,8 @@
     "validate": "npm run typecheck && npm run lint && npm run test",
     "web": "node scripts/web-serve.js",
     "web:serve": "node scripts/web-serve.js",
-    "build:packages": "node scripts/build-packages.js"
+    "build:packages": "node scripts/build-packages.js",
+    "setup-config": "node scripts/setup-config.js"
   },
   "keywords": [
     "legal",
@@ -121,9 +122,11 @@
   "bin": {
     "legal-md": "./dist/cli/index.js",
     "legal2md": "./dist/cli/index.js",
-    "legal-md-ui": "./dist/cli/interactive/index.js"
+    "legal-md-ui": "./dist/cli/interactive/index.js",
+    "legal-md-setup": "./scripts/setup-config.js",
+    "legal-md-playground": "./scripts/web-serve.js"
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": ["dist", "scripts", "README.md", "LICENSE"],
   "engines": {
     "node": ">=18.0.0"
   },