yini-cli 1.1.0-beta → 1.2.0-beta

package/README.md

@@ -1,63 +1,142 @@
 # YINI-CLI
-**Command-line tool for working with YINI configuration files. Validate, inspect, and convert to JSON with pretty output.**
+> **Readable configuration without indentation pitfalls or JSON verbosity.**  
 
-*YINI aims to be a human-friendly config format: like INI, but with type-safe values, nested sections, comments, minimal syntax noise, and optional strict mode.*
+**The official terminal / command-line (CLI) tool for validating, inspecting, and converting YINI configuration files to JSON or JavaScript.**
+
+*YINI is an INI-inspired and human-readable text format for representing structured information. It is designed to be clear, predictable, and easy for humans to read and write. It supports nesting, comments, and a formally defined syntax. It is suitable for configuration files, application settings, and general data-storage use cases.*
 
 [![npm version](https://img.shields.io/npm/v/yini-cli.svg)](https://www.npmjs.com/package/yini-cli) [![All Test Suites](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-all-tests.yml) [![Regression Tests](https://github.com/YINI-lang/yini-cli/actions/workflows/run-regression-tests.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-regression-tests.yml) [![CLI Test CI](https://github.com/YINI-lang/yini-cli/actions/workflows/run-cli-test.yml/badge.svg)](https://github.com/YINI-lang/yini-cli/actions/workflows/run-cli-test.yml)
 
----
+This tool is designed for teams and developers working with human-edited configuration files who require explicit structure without indentation-based semantics.
 
-## 🙋‍♀️ Why YINI?
-- **YINI is an alternative** to other great config formats like INI, JSON, YAML, XML, and TOML — designed for clarity, simplicity, and straightforward section nesting.
-- **Started as a personal project and a research challenge:** Provides structure similar to INI, with features inspired by JSON and YAML.
-- **Built for clarity:**
-    * Uses concise syntax designed for clarity, especially in nested sections.
-    * Supports commonly used configuration structures.
-- *Developed to meet practical needs, driven by curiosity and a desire **for configuration clarity, simplicity, minimalism, and flexibility**.
+---
 
-⭐ **Enjoying yini-cli?** If you like this project, [star it on GitHub](https://github.com/YINI-lang/yini-cli) — it helps a lot, thank you!
+## Example of YINI code
+> A basic YINI configuration example, showing a section, nested section, comments:  
+![YINI Config Example](./samples/basic.yini.png)
+Source: [basic.yini](./samples/basic.yini)
 
----
+## Quick Start
 
-## Requirements
+### Requirements
 YINI CLI requires Node.js **v20 or later**.  
 
-(It has also been tested with Node.js v13+, but v20+ is recommended for best compatibility.)
+### Installation
+
+1. **Install it globally from npm — (requires Node.js)**  
+    Open your terminal and run:
+    ```
+    npm install -g yini-cli
+    ```
+
+2. **Verify installation**  
+    Run this in your terminal:
+    ```bash
+    yini --version
+    ```
+    This should print the installed version (e.g., 1.0.0).
+
+    Then you may try:
+    ```bash
+    yini --help
+    ```
+    Should show you the CLI help for YINI.
+
+3. **Test functionality**  
+    Create a simple test file, for example: `config.yini`:
+    ```yini
+    ^ App
+      name = "My App Title"
+      version = "1.2.3"
+      pageSize = 25
+      darkTheme = off
+    ```
+
+    Then run:
+    ```bash
+    yini parse config.yini
+    ```
+
+    Expected result, your CLI should output a parsed version of the config and output something similar to:
+    ```json
+    {
+        "App": {
+            "name": "My App Title",
+            "version": "1.2.3",
+            "pageSize": 25,
+            "darkTheme": false
+        }
+    }    
+    ```
+
+### Typical use cases
+
+- Validating configuration files during development or CI.
+- Inspecting and debugging structured configuration.
+- Converting YINI files to JSON for tooling and automation.
 
 ---
 
-## 💡 What is YINI?
-- **INI-inspired** — with added support for typing, comments, and nested sections.
-- **Uses minimal syntax** — yet aims to keep maximum clarity.
-- Section nesting **without requiring indentation or dot-delimited keys**.
-- **Supports strict and lenient modes**, and all major data types.
-- Designed for compatibility with both **manual editing** and **automation**.
-- 👉 See [how YINI differs from JSON, YAML, INI, and TOML](https://github.com/YINI-lang/yini-parser-typescript/tree/main/examples/compare-formats.md).
-- Want the full syntax reference? See the [YINI Specification](https://github.com/YINI-lang/YINI-spec).
+## Example 2
+> A real-world YINI configuration example, showing sections, nesting, comments, and multiple data types:  
+![YINI Config Example](./samples/config.yini.png)
+Source: [config.yini](./samples/config.yini)
 
 ---
 
-## Quick Into to YINI Format
+## 🙋‍♀️ Why YINI?
+- **Indentation-independent structure:** YINI is indentation-independent — whitespace never alters structural meaning.
+- **Explicit nesting & refactoring safety:** It uses clear header markers (`^`, `^^`, `^^^`) to define hierarchy (like in Markdown), without long dotted keys.
+- **Multiple data types:** Supports boolean literals (`true` / `false`, `Yes` / `No`, etc), numbers, arrays (lists), and JS-style objects natively, with explicit string syntax.
+- **Comments support:** YINI supports multiple comment styles (`#`, `//`, `/* ... */`, and `;`) allowing one to document config directly in the file.
+- **Predictable parsing rules:** Well-defined rules with optional strict and lenient modes, for different use-requirements.
 
-YINI code looks like this:
-```yini
-    // This is a comment in YINI
-    // YINI is a simple, human-readable configuration file format.
+---
 
-    // Note: In YINI, spaces and tabs don't change meaning - indentation is just
-    // for readability.
+## Usage
 
-    /*  This is a block comment
+### Quick Examples
 
-        In YINI, section headers use repeated characters "^" at the start to
-        show their level: (Section header names are case-sensitive.)
+```bash
+yini parse config.yini
+```
+→ Parse and print formatted JSON (default).
 
-        ^ SectionLevel1
-        ^^ SectionLevel2
-        ^^^ SectionLevel3
-    */
+```bash
+yini parse config.yini --compact
+```
+→ Output compact JSON (no whitespace).
+
+```bash
+yini parse config.yini --js
+```
+→ Output as JavaScript-style object.
+
+```bash
+yini parse config.yini -o out.json
+```
+→ Write formatted JSON to a file.
+
+```bash
+yini validate --strict config.yini
+```
+→ Validate using strict mode.
 
-    ^ App                      // Definition of section (group) "App" 
+For help with a specific command:
+
+```bash
+yini parse --help
+```
+
+---
+
+## Quick Look at YINI
+
+Here's a small example showing YINI structure and comments:
+```yini
+    // This is a comment in YINI
+
+    ^ App                      // Defines section (group) "App" 
       name     = 'My Title'    // Keys and values are written as key = value
       items    = 25
       darkMode = true          // "ON" and "YES" works too
@@ -66,6 +145,8 @@ YINI code looks like this:
         ^^ Special
            primaryColor = #336699   // Hex number format
            isCaching    = false     // "OFF" and "NO" works too
+    
+    # This is a comment too.
 ```
 
 **The above YINI converted to a JS object:**
@@ -100,107 +181,70 @@ YINI code looks like this:
 
 That's it!
 
-- ▶️ Link to [examples/](https://github.com/YINI-lang/yini-parser-typescript/tree/main/examples) files.
+- ▶️ See more on [YINI Homepage](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_cli&utm_content=readme_middle).
 - ▶️ Link to [Demo Apps](https://github.com/YINI-lang/yini-demo-apps/tree/main) with complete basic usage.
 
 ---
 
-## Bigger Intro into YINI Config Format
-**YINI** is a simple and readable configuration format. Sections are defined with `^ SectionName`, and values are assigned using `key = value`. The format supports common data types (same as those found in JSON), including strings, numbers, booleans, nulls, and lists. 
+## 📤 Output Modes for `yini parse`
 
-To learn more, see the [Getting Started: Intro to YINI Config Format](https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Intro-to-YINI-Config-Format.md) tutorial.
+The `parse` command supports multiple output formats:
 
----
+| Command Example                         | Output Format       | Description |
+|------------------------------------------|----------------------|------------|
+| `yini parse config.yini`                | Pretty JSON (default) | Formatted JSON with indentation (4 spaces). |
+| `yini parse config.yini --json`         | Pretty JSON          | Explicit pretty JSON output. |
+| `yini parse config.yini --compact`      | Compact JSON         | Minified JSON (no whitespace). |
+| `yini parse config.yini --js`           | JavaScript object    | JavaScript-style object (unquoted keys, single quotes). |
+| `yini parse config.yini -o out.json`    | File output          | Writes formatted JSON to file (default format). |
 
-## Usage
+>💡 `--js` and `--compact` are mutually exclusive.  
+>💡 Tip: You can combine --output with any style flag to control both formatting and destination.
 
-### Installation
+---
 
-1. **Install it globally from npm — (requires Node.js)**  
-    Open your terminal and run:
-    ```
-    npm install -g yini-cli
-    ```
+## 📁 Output File Handling
 
-2. **Verify installation**  
-    Run this in your terminal:
-    ```bash
-    yini --version
-    ```
-    Should print the version (e.g., 1.0.0).
+When using `-o, --output <file>`, YINI CLI applies safe write rules:
 
-    Then you may try:
-    ```bash
-    yini --help
-    ```
-    Should show you the CLI help for YINI.
+| Scenario | Result |
+|----------|--------|
+| File does not exist | File is written |
+| File exists and is **older** than the input YINI file | File is overwritten |
+| File exists and is **newer** than the input YINI file | Command fails |
+| `--overwrite` is used | File is always overwritten |
+| `--no-overwrite` is used | Command fails if file exists |
 
-3. **Test functionality**  
-    Create a simple test file, for example: `config.yini`:
-    ```yini
-    ^ App
-      name = "My App Title"
-      version = "1.2.3"
-      pageSize = 25
-      darkTheme = off
-    ```
+This prevents accidental overwriting of newer generated files.
 
-    Then run:
-    ```bash
-    yini parse config.yini
-    ```
-
-    Expected result, your CLI should output a parsed version of the config and output something similar to:
-    ```js
-    {
-        App: {
-            name: 'My App Title',
-            version: '1.2.3',
-            pageSize: 25,
-            darkTheme: false
-        }
-    }    
-    ```
+Use:
+`--overwrite` to force replacement.
 
 ---
 
-## 📤 Output Modes for `yini parse`
-
-The `parse` command supports multiple output styles:
-
-| Command Example                                    | Output Style         | Description                                                                  |
-|----------------------------------------------------|----------------------|------------------------------------------------------------------------------|
-| `yini parse config.yini`                           | JS-style object       | Uses Node’s `util.inspect` — human-readable, shows types, nesting, etc.     |
-| `yini parse config.yini --pretty`                  | Pretty JSON           | Formatted and indented with `JSON.stringify(obj, null, 4)`.                  |
-| `yini parse config.yini --json`                    | Compact JSON          | Compact and machine-friendly `JSON.stringify(obj)`.                          |
-| `yini parse config.yini --output out.txt`          | File (JS-style)       | Default style, written to specified file.                                    |
-| `yini parse config.yini --pretty --output out.json`| File (Pretty JSON)    | Formatted JSON written to file.                                              |
+## 🛠 Roadmap
+Areas of planned and possible future expansion:
 
->💡 Tip: You can combine --output with any style flag to control both formatting and destination.
+1. **Improve existing commands** — Continued functionality improvements, better diagnostics, and expanded QA for `parse` and `validate` and their options.
+2. Command `convert`: Batch convert YINI files to JSON or JavaScript.
+3. Command `format`: Pretty-print or normalize a `.yini` file.
+4. Command `lint`: Stricter stylistic checks (like `validate`, but opinionated).
+5. Command `diff`: Compare two YINI files and show structural/config differences.
+6. Import JSON or XML into YINI format.
 
 ---
 
 ## Links
-- ➡️ [Getting Started: Intro to YINI Config Format](https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Intro-to-YINI-Config-Format.md)  
-  *Beginner-friendly walkthrough and basic usage examples.*
-
 - ➡️ [YINI Parser on npm](https://www.npmjs.com/package/yini-parser)  
   *Install and view package details.*
 
-- ➡️ [Read the YINI Specification](https://github.com/YINI-lang/YINI-spec/blob/release/YINI-Specification.md#table-of-contents)  
-  *Full formal spec for the YINI format, including syntax and features.*
-
-- ➡️ [YINI Parser on GitHub](https://github.com/YINI-lang/yini-parser-typescript)  
-  *TypeScript source code, issue tracker, and contributing guide.*
+- ➡️ [YINI Project](https://github.com/YINI-lang)  
+  *YINI home on GitHub.*
 
-- ➡️ [YINI vs Other Formats](https://github.com/YINI-lang/YINI-spec/tree/release#-summary-difference-with-other-formats)  
-  *How does YINI differ: comparison with INI, YAML, and JSON.*
-  
-- ➡️ [Why YINI? (Project Rationale)](https://github.com/YINI-lang/YINI-spec/blob/release/RATIONALE.md)  
-  *Learn about the motivations and design decisions behind YINI.*
+---
 
-- ➡️ [YINI Project](https://github.com/YINI-lang)  
-  *YINI home.*
+## Contribution & Involvement
+Contributions, issues, and feedback are welcome. Even small improvements or suggestions are appreciated.
 
 ---
 
@@ -211,4 +255,7 @@ In this project on GitHub, the `libs` directory contains third party software an
 
 ---
 
-~ **YINI ≡** • [https://yini-lang.org](https://yini-lang.org)
+**^YINI ≡**  
+> YINI — Clear, Structured Configuration Files.  
+
+[yini-lang.org](https://yini-lang.org/?utm_source=github&utm_medium=referral&utm_campaign=yini_cli&utm_content=readme_footer) · [YINI on GitHub](https://github.com/YINI-lang)  

package/dist/cli/helpAll.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function enableHelpAll(program: Command): void;

package/dist/cli/helpAll.js

@@ -0,0 +1,23 @@
+export function enableHelpAll(program) {
+    const originalFormatHelp = program.createHelp().formatHelp;
+    program.configureHelp({
+        formatHelp: (cmd, helper) => {
+            // Call the original formatter (not the overridden one)
+            let output = originalFormatHelp.call(helper, cmd, helper);
+            // Only expand the top-level help
+            if (cmd !== program)
+                return output;
+            for (const sub of program.commands) {
+                output += '\n\n';
+                output +=
+                    '--------------------------------------------------------\n';
+                output += `* Command: ${sub.name()}\n`;
+                output +=
+                    '--------------------------------------------------------\n';
+                output += originalFormatHelp.call(helper, sub, helper);
+                // output += '--------------------------------------------------------\n'
+            }
+            return output;
+        },
+    });
+}

package/dist/commands/infoCommand.d.ts

@@ -0,0 +1,4 @@
+/**
+ * NOTE: Keep contributors in acknowledged in README or --credits.
+ */
+export declare const printInfo: () => void;

package/dist/commands/infoCommand.js

@@ -0,0 +1,44 @@
+import { createRequire } from 'module';
+import { removeSuffix, toColRow } from '../utils/string.js';
+// import pkg from '../../package.json' with { type: 'json' } // NOTE: Must use { type: 'json' } when in ESM mode.
+const require = createRequire(import.meta.url);
+const pkg = require('../../package.json');
+/*
+    YINI CLI — Environment Information
+    ──────────────────────────────────
+
+    CLI Version:     1.1.1-beta
+    Parser Version:  1.3.2-beta
+
+if verbose(
+    Node.js:           v20.18.0
+    Platform:          win32 x64
+    Working Directory: D:\Sources\YINI-lang-WORK\yini-cli
+)
+
+    Author:          Marko K. Seppänen
+    License:         Apache-2.0
+
+    Repository:      https://github.com/YINI-lang/yini-cli
+    Homepage:        https://yini-lang.org
+
+    ---
+
+*/
+/**
+ * NOTE: Keep contributors in acknowledged in README or --credits.
+ */
+export const printInfo = () => {
+    const size = 16;
+    console.log();
+    console.log('YINI CLI — Environment Information');
+    console.log('==================================');
+    console.log();
+    console.log(toColRow(size, 'CLI Version:', pkg.version));
+    console.log(toColRow(size, 'Parser Version:', pkg.dependencies['yini-parser'].replace('^', '')));
+    console.log(toColRow(size, 'Author:', pkg.author));
+    console.log(toColRow(size, 'License:', pkg.license));
+    console.log();
+    console.log(toColRow(size, 'Repository:', 'https://github.com/YINI-lang/yini-cli'));
+    console.log(toColRow(size, 'Homepage:', removeSuffix(pkg.homepage, '/')));
+};

package/dist/commands/parseCommand.d.ts

@@ -1,7 +1,14 @@
 import { IGlobalOptions } from '../types.js';
+/**
+ * @deprecated pretty Deprecated since 2026 Feb! Use `json` instead.
+ */
 export interface IParseCommandOptions extends IGlobalOptions {
     pretty?: boolean;
     json?: boolean;
+    compact?: boolean;
+    js?: boolean;
     output?: string;
+    bestEffort?: boolean;
+    overwrite?: boolean;
 }
 export declare const parseFile: (file: string, commandOptions: IParseCommandOptions) => void;

package/dist/commands/parseCommand.js

@@ -1,72 +1,131 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import util from 'util';
 import YINI from 'yini-parser';
-import { debugPrint, printObject, toPrettyJSON } from '../utils/print.js';
+import { debugPrint, printObject, toPrettyJS, toPrettyJSON, } from '../utils/print.js';
 // -------------------------------------------------------------------------
+/*
+    TODO / SHOULD-DO:
+
+    yini parse <file> [options]
+
+    Options
+    -------
+
+    Parsing mode:
+    --strict
+    --lenient                   (default)
+
+    Output format:
+    --to <json|json-compact>    (default, --to json)
+    --json                      (alias for --to json, default)
+    --compact              (alias for --to json-compact)
+
+    Output handling:
+    -o, --output <file>         (default) No overwrite if dest is more recent than source file (override with --overwrite)
+    --overwrite
+    --no-overwrite
+
+    Execution control:
+    --fail-fast
+    --best-effort = ignore-errors within a file, attempt recovery and still emit outp
+                --No for parse, --keep-going = continue to the next file when one fails
+    --max-errors <n>
+    --verbose
+    --checks                    (default)
+    --no-checks
+
+    Policy control (advanced):
+    --duplicates-policy <error|warn|allow>
+    --reserved-policy   <error|warn|allow>
+ */
 export const parseFile = (file, commandOptions) => {
     const outputFile = commandOptions.output || '';
-    const isStrictMode = !!commandOptions.strict;
-    let outputStyle = 'JS-style';
+    // const isStrictMode = !!commandOptions.strict
+    const outputStyle = resolveOutputStyle(commandOptions);
     debugPrint('file = ' + file);
     debugPrint('output = ' + commandOptions.output);
     debugPrint('commandOptions:');
     printObject(commandOptions);
-    if (commandOptions.pretty) {
-        outputStyle = 'Pretty-JSON';
+    doParseFile(file, commandOptions, outputStyle, outputFile);
+};
+const resolveOutputStyle = (options) => {
+    if (options.js && options.compact) {
+        throw new Error('--js and --compact cannot be combined.');
     }
-    else if (commandOptions.json) {
-        outputStyle = 'JSON-compact';
+    if (options.compact)
+        return 'JSON-compact';
+    if (options.js)
+        return 'JS-style';
+    if (options.pretty) {
+        console.warn('Warning: --pretty is deprecated. Use --json instead.');
     }
-    else {
-        outputStyle = 'JS-style';
+    return 'Pretty-JSON';
+};
+const renderOutput = (parsed, style) => {
+    switch (style) {
+        case 'JS-style':
+            return toPrettyJS(parsed);
+        case 'JSON-compact':
+            return JSON.stringify(parsed);
+        case 'Pretty-JSON':
+        default:
+            return toPrettyJSON(parsed);
     }
-    doParseFile(file, commandOptions, outputStyle, outputFile);
 };
 const doParseFile = (file, commandOptions, outputStyle, outputFile = '') => {
     // let strictMode = !!commandOptions.strict
-    let preferredFailLevel = 'auto';
+    let preferredFailLevel = commandOptions.bestEffort
+        ? 'ignore-errors'
+        : 'auto';
     let includeMetaData = false;
     debugPrint('File = ' + file);
     debugPrint('outputStyle = ' + outputStyle);
     const parseOptions = {
         strictMode: commandOptions.strict ?? false,
-        // failLevel: 'errors',
         failLevel: preferredFailLevel,
-        // failLevel: 'ignore-errors',
         includeMetadata: includeMetaData,
     };
-    // If --force then override fail-level.
-    if (commandOptions.force) {
+    // If --best-effort then override fail-level.
+    if (commandOptions.bestEffort) {
         parseOptions.failLevel = 'ignore-errors';
     }
     try {
         const parsed = YINI.parseFile(file, parseOptions);
-        let output = '';
-        switch (outputStyle) {
-            case 'Pretty-JSON':
-                output = toPrettyJSON(parsed);
-                break;
-            case 'Console.log':
-                output = '<todo>';
-                break;
-            case 'JSON-compact':
-                output = JSON.stringify(parsed);
-                break;
-            default:
-                output = util.inspect(parsed, { depth: null, colors: false });
-        }
+        const output = renderOutput(parsed, outputStyle);
         if (outputFile) {
+            const resolved = path.resolve(outputFile);
+            enforceWritePolicy(file, resolved, commandOptions.overwrite);
             // Write JSON output to file instead of stdout.
-            fs.writeFileSync(path.resolve(outputFile), output, 'utf-8');
-            console.log(`Output written to file: "${outputFile}"`);
+            fs.writeFileSync(resolved, output, 'utf-8');
+            if (commandOptions.verbose) {
+                console.log(`Output written to file: "${outputFile}"`);
+            }
         }
         else {
             console.log(output);
         }
     }
     catch (err) {
-        console.error(`Error: ${err.message}`);
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${message}`);
         process.exit(1);
     }
 };
+const enforceWritePolicy = (srcPath, destPath, overwrite) => {
+    if (!fs.existsSync(destPath)) {
+        return; // File does not exist, OK to write.
+    }
+    const srcStat = fs.statSync(srcPath);
+    const destStat = fs.statSync(destPath);
+    const destIsNewer = destStat.mtimeMs >= srcStat.mtimeMs;
+    if (overwrite === true) {
+        return; // Explicit overwrite, OK.
+    }
+    if (overwrite === false) {
+        throw new Error(`File "${destPath}" already exists. Overwriting disabled (--no-overwrite).`);
+    }
+    // Default policy (overwrite undefined).
+    if (destIsNewer) {
+        throw new Error(`Destination file "${destPath}" is newer than source. Use --overwrite to force.`);
+    }
+};

package/dist/commands/validateCommand.d.ts

@@ -1,6 +1,5 @@
 import { IGlobalOptions } from '../types.js';
 export interface IValidateCommandOptions extends IGlobalOptions {
-    report?: boolean;
-    details?: boolean;
+    stats?: boolean;
 }
 export declare const validateFile: (file: string, commandOptions?: IValidateCommandOptions) => never;