yini-cli 1.0.3-beta → 1.1.1-beta

package/README.md

@@ -1,54 +1,130 @@
 # YINI-CLI
-**Command-line tool for working with YINI configuration files. Validate, inspect, and convert to JSON with pretty output.**
+**Command-line tool for validating, inspecting, and converting YINI configuration files to JSON.**
 
-*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.*
+*YINI is an INI-inspired configuration format designed for clarity and predictability. It supports nesting, comments, and a formally defined syntax, so configuration files stay easy to read and reason about as they grow.*
 
-[![npm version](https://img.shields.io/npm/v/yini-parser.svg)](https://www.npmjs.com/package/yini-parser) [![All Tests](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)
+[![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 useful if you work with human-edited configuration files and want predictable structure without indentation-based rules.
 
 ---
 
-## 🙋‍♀️ 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**.
+## Quick Start
+
+### 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
+    ```
+    Should print the 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:
+    ```js
+    {
+        App: {
+            name: 'My App Title',
+            version: '1.2.3',
+            pageSize: 25,
+            darkTheme: false
+        }
+    }    
+    ```
+
+⭐ If this was useful, [star it on GitHub](https://github.com/YINI-lang/yini-cli) — it helps a lot, thank you!
 
 ---
 
-## 💡 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).
+### Typical use cases
+
+- Validating configuration files during development or CI.
+- Inspecting and debugging structured configuration.
+- Converting YINI files to JSON for tooling and automation.
 
 ---
 
-## Quick Into to YINI Format
+## 🙋‍♀️ Why YINI?
+- **Indentation-independent structure:** The YINI config format is indentation-independent, meaning any space or tab never changes meaning.
+- **Explicit nesting:** 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.
+## Usage of command `yini`
 
-    // Note: In YINI, spaces and tabs don't change meaning - indentation is just
-    // for readability.
+```bash
+Usage: yini [options] [command]
 
-    /*  This is a block comment
+CLI for parsing and validating YINI config files.
 
-        In YINI, section headers use repeated characters "^" at the start to
-        show their level: (Section header names are case-sensitive.)
+Options:
+  -v, --version              Output the version number.
+  -i, --info                 Show extended information (details, links, etc.).
+  -s, --strict               Enable strict parsing mode.
+  -f, --force                Continue parsing even if errors occur.
+  -q, --quiet                Reduce output (show only errors).
+  --silent                   Suppress all output (even errors, exit code only).
+  -h, --help                 Display help for command.
 
-        ^ SectionLevel1
-        ^^ SectionLevel2
-        ^^^ SectionLevel3
-    */
+Commands:
+  parse [options] <file>     Parse a YINI file (*.yini) and print the result.
+  validate [options] <file>  Checks if the file can be parsed as valid YINI.
+  info                       Deprecated: Use `yini --info` or `yini -i` instead.
+  help [command]             Display help for command.
+
+Examples:
+  $ yini parse config.yini
+  $ yini validate --strict config.yini
+  $ yini parse config.yini --pretty --output out.json
+
+For help with a specific command, use -h or --help. For example:
+  $ yini validate --help
+```
+
+---
+
+## Quick Look at YINI
+
+Here's a small example showing YINI structure and comments:
+```yini
+    // This is a comment in YINI
 
-    ^ App                      // Definition of section (group) "App" 
+    ^ 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
@@ -57,6 +133,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:**
@@ -96,65 +174,6 @@ That's it!
 
 ---
 
-## 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. 
-
-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.
-
----
-
-## Usage
-
-### 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
-    ```
-    Should print the 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:
-    ```js
-    {
-        App: {
-            name: 'My App Title',
-            version: '1.2.3',
-            pageSize: 25,
-            darkTheme: false
-        }
-    }    
-    ```
-
----
-
 ## 📤 Output Modes for `yini parse`
 
 The `parse` command supports multiple output styles:
@@ -171,27 +190,29 @@ The `parse` command supports multiple output styles:
 
 ---
 
-## 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.*
+## 🛠 Roadmap
+Areas of planned and possible future expansion:
+
+1. **Improve existing commands** — Continued functionality improvements, better diagnostics, and expanded QA for `parse` and `validate` and their options.
+2. Command `format`: Pretty-print or normalize a `.yini` file.
+3. Command `lint`: Stricter stylistic checks (like `validate`, but opinionated).
+4. Command `diff`: Compare two YINI files and show structural/config differences.
+5. Command `convert`: Convert a `JSON` or `XML` file into YINI format.
+
+---
 
+## Links
 - ➡️ [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
+Interested in contributing or trying ideas?
+Issues, feedback, and experiments are welcome — even small ones.
 
 ---
 
@@ -202,4 +223,9 @@ In this project on GitHub, the `libs` directory contains third party software an
 
 ---
 
-~ **YINI ≡** • [https://yini-lang.org](https://yini-lang.org)
+If you found this useful, a GitHub star helps the project a lot ⭐
+
+**^YINI ≡**  
+> YINI — Clear, Structured Configuration Files.  
+
+[yini-lang.org](https://yini-lang.org) · [YINI on GitHub](https://github.com/YINI-lang)  

package/dist/commands/parseCommand.d.ts

@@ -0,0 +1,7 @@
+import { IGlobalOptions } from '../types.js';
+export interface IParseCommandOptions extends IGlobalOptions {
+    pretty?: boolean;
+    json?: boolean;
+    output?: string;
+}
+export declare const parseFile: (file: string, commandOptions: IParseCommandOptions) => void;

package/dist/commands/{parse.js → parseCommand.js}

@@ -3,44 +3,45 @@ import path from 'node:path';
 import util from 'util';
 import YINI from 'yini-parser';
 import { debugPrint, printObject, toPrettyJSON } from '../utils/print.js';
-export const parseFile = (file, options) => {
-    const outputFile = options.output || '';
-    const isStrictMode = !!options.strict;
+// -------------------------------------------------------------------------
+export const parseFile = (file, commandOptions) => {
+    const outputFile = commandOptions.output || '';
+    const isStrictMode = !!commandOptions.strict;
     let outputStyle = 'JS-style';
     debugPrint('file = ' + file);
-    debugPrint('output = ' + options.output);
-    debugPrint('options:');
-    printObject(options);
-    if (options.pretty) {
+    debugPrint('output = ' + commandOptions.output);
+    debugPrint('commandOptions:');
+    printObject(commandOptions);
+    if (commandOptions.pretty) {
         outputStyle = 'Pretty-JSON';
     }
-    else if (options.log) {
-        outputStyle = 'Console.log';
-    }
-    else if (options.json) {
+    else if (commandOptions.json) {
         outputStyle = 'JSON-compact';
     }
     else {
         outputStyle = 'JS-style';
     }
-    doParseFile(file, outputStyle, isStrictMode, outputFile);
+    doParseFile(file, commandOptions, outputStyle, outputFile);
 };
-const doParseFile = (file, outputStyle, isStrictMode = false, outputFile = '') => {
-    // let strictMode = !!options.strict
-    let bailSensitivity = 'auto';
+const doParseFile = (file, commandOptions, outputStyle, outputFile = '') => {
+    // let strictMode = !!commandOptions.strict
+    let preferredFailLevel = '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) {
+        parseOptions.failLevel = 'ignore-errors';
+    }
     try {
-        // const raw = fs.readFileSync(file, 'utf-8')
-        // const parsed = YINI.parseFile(
-        //const parsed = YINI.parseFile(file)
-        const parsed = YINI.parseFile(file, isStrictMode, bailSensitivity, includeMetaData);
-        // const parsed = YINI.parse(raw)
-        // const output = options.pretty
-        //     ? // ? JSON.stringify(parsed, null, 2)
-        //       toPrettyJSON(parsed)
-        //     : JSON.stringify(parsed)
+        const parsed = YINI.parseFile(file, parseOptions);
         let output = '';
         switch (outputStyle) {
             case 'Pretty-JSON':

package/dist/commands/validateCommand.d.ts

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

package/dist/commands/validateCommand.js

@@ -0,0 +1,217 @@
+import assert from 'node:assert';
+import { exit } from 'node:process';
+import YINI from 'yini-parser';
+const IS_DEBUG = false; // For local debugging purposes, etc.
+// -------------------------------------------------------------------------
+export const validateFile = (file, commandOptions = {}) => {
+    let parsedResult = undefined;
+    let isCatchedError = true;
+    const parseOptions = {
+        strictMode: commandOptions.strict ?? false,
+        // failLevel: 'errors',
+        failLevel: commandOptions.force ? 'ignore-errors' : 'errors',
+        // failLevel: 'ignore-errors',
+        includeMetadata: true,
+        includeDiagnostics: true,
+        silent: true,
+    };
+    try {
+        parsedResult = YINI.parseFile(file, parseOptions);
+        isCatchedError = false;
+    }
+    catch (err) {
+        isCatchedError = true;
+    }
+    let metadata = null;
+    let errors = 0;
+    let warnings = 0;
+    let notices = 0;
+    let infos = 0;
+    if (!isCatchedError && parsedResult?.meta) {
+        metadata = parsedResult?.meta;
+        assert(metadata); // Make sure there is metadata!
+        // printObject(metadata, true)
+        assert(metadata.diagnostics);
+        const diag = metadata.diagnostics;
+        errors = diag.errors.errorCount;
+        warnings = diag.warnings.warningCount;
+        notices = diag.notices.noticeCount;
+        infos = diag.infos.infoCount;
+    }
+    IS_DEBUG && console.log();
+    IS_DEBUG && console.log('isCatchedError = ' + isCatchedError);
+    IS_DEBUG && console.log('TEMP OUTPUT');
+    IS_DEBUG && console.log('isCatchedError = ' + isCatchedError);
+    IS_DEBUG && console.log('  errors = ' + errors);
+    IS_DEBUG && console.log('warnings = ' + warnings);
+    IS_DEBUG && console.log(' notices = ' + notices);
+    IS_DEBUG && console.log('   infor = ' + infos);
+    IS_DEBUG && console.log('metadata = ' + metadata);
+    IS_DEBUG &&
+        console.log('includeMetadata = ' +
+            metadata?.diagnostics?.effectiveOptions.includeMetadata);
+    IS_DEBUG && console.log('commandOptions.report = ' + commandOptions?.report);
+    IS_DEBUG && console.log();
+    if (!commandOptions.silent && !isCatchedError) {
+        if (commandOptions.report) {
+            if (!metadata) {
+                console.error('Internal Error: No meta data found');
+            }
+            assert(metadata); // Make sure there is metadata!
+            console.log();
+            console.log(formatToReport(file, metadata).trim());
+        }
+        if (commandOptions.details) {
+            if (!metadata) {
+                console.error('Internal Error: No meta data found');
+            }
+            assert(metadata); // Make sure there is metadata!
+            console.log();
+            printDetailsOnAllIssue(file, metadata);
+        }
+    }
+    //state returned:
+    // - passed (no errors/warnings),
+    // - finished (with warnings, no errors) / or - passed with warnings
+    // - failed (errors),
+    if (isCatchedError) {
+        errors = 1;
+    }
+    // console.log()
+    if (errors) {
+        // red ✖
+        console.error(formatToStatus('Failed', errors, warnings, notices, infos));
+        exit(1);
+    }
+    else if (warnings) {
+        // yellow ⚠️
+        console.warn(formatToStatus('Passed-with-Warnings', errors, warnings, notices, infos));
+        exit(0);
+    }
+    else {
+        // green ✔
+        console.log(formatToStatus('Passed', errors, warnings, notices, infos));
+        exit(0);
+    }
+};
+const formatToStatus = (statusType, errors, warnings, notices, infos) => {
+    const totalMsgs = errors + warnings + notices + infos;
+    let str = ``;
+    switch (statusType) {
+        case 'Passed':
+            str = '✔  Validation passed';
+            break;
+        case 'Passed-with-Warnings':
+            str = '⚠️ Validation finished';
+            break;
+        case 'Failed':
+            str = '✖  Validation failed';
+            break;
+    }
+    str += ` (${errors} errors, ${warnings} warnings, ${totalMsgs} total messages)`;
+    return str;
+};
+// --- Format to a Report --------------------------------------------------------
+//@todo format parsed.meta to report as
+/*
+    - Produce a summary-level validation report.
+    - Output is structured and concise (e.g. JSON or table-like).
+    - Focus on counts, pass/fail, severity summary.
+
+    Example:
+    Validation report for config.yini:
+    Errors:   3
+    Warnings: 1
+    Notices:  0
+    Result: INVALID
+*/
+const formatToReport = (fileWithPath, metadata) => {
+    // console.log('formatToReport(..)')
+    // printObject(metadata)
+    // console.log()
+    assert(metadata.diagnostics);
+    const diag = metadata.diagnostics;
+    const issuesCount = diag.errors.errorCount +
+        diag.warnings.warningCount +
+        diag.notices.noticeCount +
+        diag.infos.infoCount;
+    const str = `Validation Report
+=================
+
+File      "${fileWithPath}"
+Issues:   ${issuesCount}
+
+Summary
+-------
+Mode:     ${metadata.mode}
+Strict:   ${metadata.mode === 'strict'}
+
+Errors:   ${diag.errors.errorCount}
+Warnings: ${diag.warnings.warningCount}
+Notices:  ${diag.notices.noticeCount}
+Infos:    ${diag.infos.infoCount}
+
+Stats
+-----
+Line Count:    ${metadata.source.lineCount}
+Section Count: ${metadata.structure.sectionCount}
+Member Count:  ${metadata.structure.memberCount}
+Nesting Depth: ${metadata.structure.maxDepth}
+
+Has @YINI:     ${metadata.source.hasYiniMarker}
+Has /END:      ${metadata.source.hasDocumentTerminator}
+Byte Size:     ${metadata.source.sourceType === 'inline' ? 'n/a' : metadata.source.byteSize + ' bytes'}
+`;
+    return str;
+};
+// -------------------------------------------------------------------------
+// --- Format to a Details --------------------------------------------------------
+//@todo format parsed.meta to details as
+/*
+    - Show full detailed validation messages.
+    - Output includes line numbers, columns, error codes, and descriptive text.
+    - Useful for debugging YINI files.
+
+    Example:
+    Error at line 5, column 9: Unexpected '/END' — expected <EOF>
+    Warning at line 10, column 3: Section level skipped (0 → 2)
+    Notice at line 1: Unused @yini directive
+*/
+const printDetailsOnAllIssue = (fileWithPath, metadata) => {
+    // console.log('printDetails(..)')
+    // printObject(metadata)
+    // console.log(toPrettyJSON(metadata))
+    // console.log()
+    assert(metadata.diagnostics);
+    const diag = metadata.diagnostics;
+    console.log('Details');
+    console.log('-------');
+    console.log();
+    const errors = diag.errors.payload;
+    printIssues('Error  ', 'E', errors);
+    const warnings = diag.warnings.payload;
+    printIssues('Warning', 'W', warnings);
+    const notices = diag.notices.payload;
+    printIssues('Notice ', 'N', notices);
+    const infos = diag.infos.payload;
+    printIssues('Info   ', 'I', infos);
+    return;
+};
+// -------------------------------------------------------------------------
+const printIssues = (typeLabel, prefix, issues) => {
+    const leftPadding = '        ';
+    issues.forEach((iss, i) => {
+        const id = '#' + prefix + '-0' + (i + 1);
+        // const id: string = '' + prefix + '-0' + (i+1) + ':'
+        let str = `${typeLabel} [${id}]:\n`;
+        str +=
+            leftPadding +
+                `At line ${iss.line}, column ${iss.column}: ${iss.message}`;
+        if (iss.advice)
+            str += '\n' + leftPadding + iss.advice;
+        if (iss.hint)
+            str += '\n' + leftPadding + iss.hint;
+        console.log(str);
+        console.log();
+    });
+};

package/dist/descriptions.js

@@ -2,5 +2,5 @@ export const descriptions = {
     yini: 'CLI for parsing and validating YINI config files.',
     'For-command-parse': 'Parse a YINI file (*.yini) and print the result.',
     'For-command-validate': 'Checks if the file can be parsed as valid YINI.',
-    'For-command-info': 'Show extended information (details, links, etc.).',
+    'For-command-info': 'Deprecated: Use `yini --info` or `yini -i` instead.',
 };

package/dist/globalOptions/helpOption.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Text to be displayed BEFORE the built-in help text block.
+ */
+export declare const getHelpTextBefore: () => string;
+/**
+ * Text to be displayed AFTER the built-in help text block.
+ */
+export declare const getHelpTextAfter: () => string;

package/dist/globalOptions/helpOption.js

@@ -0,0 +1,52 @@
+/*
+ * The main (global) option help.
+ */
+import { getPackageName, getPackageVersion } from '../utils/yiniCliHelpers.js';
+/**
+ * Text to be displayed BEFORE the built-in help text block.
+ */
+export const getHelpTextBefore = () => {
+    return `${getPackageName()} ${getPackageVersion()}
+YINI CLI (Yet another INI)
+
+Parse and validate YINI configuration files.
+A config format, inspired by INI, with type-safe values, nested
+sections, comments, minimal syntax noise, and optional strict mode.
+
+Designed for clarity and consistency. :)\n`;
+};
+/**
+ * Text to be displayed AFTER the built-in help text block.
+ */
+export const getHelpTextAfter = () => {
+    return `
+Examples:
+  $ yini parse config.yini
+  $ yini validate --strict config.yini
+  $ yini parse config.yini --pretty --output out.json
+
+For help with a specific command, use -h or --help. For example:
+  $ yini validate --help
+
+Sample "config.yini":
+    ^ App
+    title = 'My App'
+    items = 10
+    debug = ON
+
+    ^ Server
+    host = 'localhost'
+    port = 8080
+    useTLS = OFF
+
+        // Sub-section of Server.
+        ^^ Login
+        username = 'user'
+        password = 'secret'
+
+More info:
+https://github.com/YINI-lang/yini-cli
+
+Into to YINI Config:
+https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Intro-to-YINI-Config-Format.md`;
+};

package/dist/{commands/info.js → globalOptions/infoOption.js}

@@ -1,8 +1,9 @@
 import { createRequire } from 'module';
+// 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');
 export const printInfo = () => {
-    console.log(`** YINI CLI **`);
+    console.log(`*** YINI CLI ***`);
     console.log(`yini-cli:    ${pkg.version}`);
     console.log(`yini-parser: ${pkg.dependencies['yini-parser'].replace('^', '')}`);
     console.log(`Author:      ${pkg.author}`);

package/dist/index.js

@@ -1,187 +1,158 @@
 #!/usr/bin/env node
-// (!) NOTE: Leave above shebang as first line!
-// import pkg from '../package.json'
+//
+// (!) IMPORTANT: Leave the top shebang as the very first line! (otherwise command will break)
+//
 import { createRequire } from 'module';
 import { Command } from 'commander';
-import { printInfo } from './commands/info.js';
-import { parseFile } from './commands/parse.js';
-import { validateFile } from './commands/validate.js';
+import { parseFile } from './commands/parseCommand.js';
+import { validateFile, } from './commands/validateCommand.js';
 import { isDebug, isDev } from './config/env.js';
 import { descriptions as descr } from './descriptions.js';
+import { getHelpTextAfter, getHelpTextBefore, } from './globalOptions/helpOption.js';
+import { printInfo } from './globalOptions/infoOption.js';
 import { debugPrint, toPrettyJSON } from './utils/print.js';
+import { getPackageVersion } from './utils/yiniCliHelpers.js';
 const require = createRequire(import.meta.url);
-const pkg = require('../package.json');
-const program = new Command();
-/*
-
-Idea/suggestion
-yini [parse] [--strict] [--pretty] [--output]
-
-Current suggestion:
-* yini parse config.yini
-    JS-style object using printObject()
-    to stdout
-* yini parse config.yini --pretty
-    Pretty JSON	using JSON.stringify(obj, null, 4)
-    to stdout
-* yini parse config.yini --output out.txt
-    JS-style object
-    to out.txt
-* yini parse config.yini --pretty --output out.json
-    Pretty JSON
-    to out.json
-
-New suggestion:
-Current suggestion:
-* yini parse config.yini
-    JS-style object using printObject(obj) (using using util.inspect)
-    to stdout
-* yini parse config.yini --pretty
-    Pretty JSON	using JSON.stringify(obj, null, 4) (formatted, readable)
-    to stdout
-* yini parse config.yini --log
-    Intended for quick output using console.log (nested object may get compacted/abbreviate)
-    to stdout
-* yini parse config.yini --json
-    Stringigies JSON using using JSON.stringify(obj) (compact, machine-parseable)
-    to stdout
-* yini parse config.yini --output out.txt
-    JS-style object
-    to out.txt
-* yini parse config.yini --pretty --output out.json
-    Pretty JSON
-    to out.json
-
-*/
-// Display help for command
-program
+// const pkg = require('../package.json')
+// --- Helper functions --------------------------------------------------------
+function appendGlobalOptionsTo(cmd) {
+    const help = program.createHelp();
+    const globals = help.visibleOptions(program);
+    if (!globals.length)
+        return;
+    const lines = globals
+        // .map(
+        //     (opt) =>
+        //         `  ${help.optionTerm(opt)}  ${help.optionDescription(opt)}`,
+        // )
+        // .join('\n')
+        .map((option) => {
+        const optName = option.name();
+        if (optName === 'version' ||
+            optName === 'info' ||
+            optName === 'help') {
+            debugPrint('Skip patching option.name() = ' +
+                option.name() +
+                ' into per-command help');
+        }
+        else {
+            return `  ${help.optionTerm(option)}  ${help.optionDescription(option)}`;
+        }
+    })
+        .join('\n')
+        .trim();
+    cmd.addHelpText('after', `\nGlobal options:\n  ${lines}`);
+    // cmd.addHelpText('after', `  ${lines}`)
+}
+// -------------------------------------------------------------------------
+const program = new Command()
     .name('yini')
     .description(descr.yini)
     // Below will replace all auto-registered items (especially the descriptions starting with a capital and ending with a period).
-    .version(pkg.version, '-v, --version', 'Output the version number.')
+    .version(getPackageVersion(), '-v, --version', 'Output the version number.')
     .helpOption('-h, --help', 'Display help for command.')
     .helpCommand('help [command]', 'Display help for command.');
-program.addHelpText('before', `YINI CLI (Yet another INI)
-
-For parsing and validating YINI configuration files.
-A config format, inspired by INI, with type-safe values, nested
-sections, comments, minimal syntax noise, and optional strict mode.
-
-Designed for clarity and consistency. :)\n`);
-program.addHelpText('after', `
-Examples:
-  $ yini parse config.yini
-  $ yini validate config.yini --strict
-  $ yini parse config.yini --pretty --output out.json
-
-Example of "config.yini":
-    ^ App
-    title = 'My App'
-    items = 10
-    debug = ON
-
-    ^ Server
-    host = 'localhost'
-    port = 8080
-    useTLS = OFF
-
-        // Sub-section of Server.
-        ^^ Login
-        username = 'user'
-        password = 'secret'
-
-More info:
-https://github.com/YINI-lang/yini-cli
-
-Into to YINI Config:
-https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Intro-to-YINI-Config-Format.md`);
-//program.command('help [command]').description('Display help for command')
+program.addHelpText('before', getHelpTextBefore());
+program.addHelpText('after', getHelpTextAfter());
 /**
- *
- * Maybe later, to as default command: parse <parse>
+ * The (main/global) option: "--info, --strict, --quite, --silent"
+ */
+// Suggestions for future: --verbose, --debug, --no-color, --color, --timing, --stdin
+program
+    .option('-i, --info', 'Show extended information (details, links, etc.).')
+    .option('-s, --strict', 'Enable strict parsing mode.')
+    .option('-f, --force', 'Continue parsing even if errors occur.')
+    .option('-q, --quiet', 'Reduce output (show only errors).')
+    .option('--silent', 'Suppress all output (even errors, exit code only).')
+    .action((options) => {
+    debugPrint('Run global options');
+    if (isDebug()) {
+        console.log('Global options:');
+        console.log(toPrettyJSON(options));
+    }
+    printInfo();
+});
+/**
+ * The (main/global) option: "--info"
  */
 // program
-//     .argument('<file>', 'File to parse')
-//     .option('--strict', 'Parse YINI in strict-mode')
-//     .option('--pretty', 'Pretty-print output as JSON')
-//     // .option('--log', 'Use console.log output format (compact, quick view)')
-//     .option('--json', 'Compact JSON output using JSON.stringify')
-//     .option('--output <file>', 'Write output to a specified file')
-//     .action((file, options) => {
-//         if (file) {
-//             parseFile(file, options)
-//         } else {
-//             program.help()
+//     .option('-s, --strict', 'Enable parsing in strict-mode.')
+//     .action((options) => {
+//         debugPrint('Run (global) option "strict"')
+//         if (isDebug()) {
+//             console.log('options:')
+//             console.log(toPrettyJSON(options))
 //         }
+//         printInfo()
 //     })
-// Explicit "parse" command
-program
+/**
+ * The command: "parse <file>"
+ */
+const parseCmd = program
     .command('parse <file>')
     .description(descr['For-command-parse'])
-    .option('--strict', 'Parse YINI in strict-mode.')
     .option('--pretty', 'Pretty-print output as JSON.')
-    // .option('--log', 'Use console.log output format (compact, quick view)')
     .option('--json', 'Compact JSON output using JSON.stringify.')
     .option('--output <file>', 'Write output to a specified file.')
     .action((file, options) => {
+    const globals = program.opts(); // Global options.
+    const mergedOptions = { ...globals, ...options }; // Merge global options with per-command options.
     debugPrint('Run command "parse"');
     debugPrint('isDebug(): ' + isDebug());
     debugPrint('isDev()  : ' + isDev());
     debugPrint(`<file> = ${file}`);
     if (isDebug()) {
-        console.log('options:');
-        console.log(toPrettyJSON(options));
+        console.log('mergedOptions:');
+        console.log(toPrettyJSON(mergedOptions));
     }
     if (file) {
-        parseFile(file, options);
+        parseFile(file, mergedOptions);
     }
     else {
         program.help();
     }
 });
+appendGlobalOptionsTo(parseCmd);
 /**
- * To handle command validate, e.g.:
- *      yini validate config.yini
- *      yini validate config.yini --strict
- *      yini validate config.yini --details
- *      yini validate config.yini --silent
- *
- * If details:
- * Details:
- * - YINI version: 1.0.0-beta.6
- * - Mode: strict
- * - Keys: 42
- * - Sections: 6
- * - Nesting depth: 3
- * - Has @yini: true
+ * The command: "validate <file>"
  */
-program
+const validateCmd = program
     .command('validate <file>')
     .description(descr['For-command-validate'])
-    .option('--strict', 'Enable parsing in strict-mode')
-    .option('--details', 'Print detailed meta-data info (e.g., key count, nesting, etc.).')
-    .option('--silent', 'Suppress output')
+    .option('--report', 'Print detailed meta-data info (e.g., key count, nesting, etc.).')
+    .option('--details', 'Print detailed validation info (e.g., line locations, error codes, descriptive text, etc.).')
+    // .option('--silent', 'Suppress output')
     .action((file, options) => {
-    //@todo add debugPrint
+    const globals = program.opts(); // Global options.
+    const mergedOptions = { ...globals, ...options }; // Merge global options with per-command options.
+    debugPrint('Run command "parse"');
+    debugPrint('isDebug(): ' + isDebug());
+    debugPrint('isDev()  : ' + isDev());
+    debugPrint(`<file> = ${file}`);
+    if (isDebug()) {
+        console.log('mergedOptions:');
+        console.log(toPrettyJSON(mergedOptions));
+    }
     if (file) {
-        validateFile(file, options);
+        validateFile(file, mergedOptions);
     }
     else {
         program.help();
     }
 });
-// Command info
+appendGlobalOptionsTo(validateCmd);
+// About to get deleted, moved to main option --info
+//@todo Delete
 program
     .command('info')
-    // .command('')
     .description(descr['For-command-info'])
-    // .option('info')
     .action((options) => {
     debugPrint('Run command "info"');
     if (isDebug()) {
         console.log('options:');
         console.log(toPrettyJSON(options));
     }
+    console.warn('Deprecated: Use `yini --info` or `yini -i` instead of `yini info`.');
     printInfo();
 });
 // NOTE: Converting YINI files to other formats than json and js.

package/dist/types.d.ts

@@ -1,8 +1,6 @@
-export interface ICLIParseOptions {
+export interface IGlobalOptions {
     strict?: boolean;
-    pretty?: boolean;
-    log?: boolean;
-    json?: boolean;
-    output?: string;
+    force?: boolean;
+    quiet?: boolean;
+    silent?: boolean;
 }
-export type TBailSensitivity = 'auto' | 0 | 1 | 2;

package/dist/types.js

@@ -1 +1,5 @@
+// //export type TBailSensitivity = 'auto' | 0 | 1 | 2
+// export type TPreferredFailLevel = 'auto' | 0 | 1 | 2 // Preferred bail sensitivity level.
+// export type TBailSensitivityLevel = 0 | 1 | 2 // Bail sensitivity level.
 export {};
+// -------------------------------------------------------------------------

package/dist/utils/print.d.ts

@@ -2,14 +2,13 @@ export declare const debugPrint: (str?: any) => void;
 export declare const devPrint: (str?: any) => void;
 export declare const toJSON: (obj: any) => string;
 export declare const toPrettyJSON: (obj: any) => string;
-/**
- * Pretty-prints a JavaScript object as formatted JSON to the console.
+/** Pretty-prints a JavaScript object as formatted JSON to the console.
  * Strict JSON, all keys are enclosed in ", etc.
  */
-export declare const printJSON: (obj: any) => void;
+export declare const printJSON: (obj: any, isForce?: boolean) => void;
 /**
  * Print a full JavaScript object in a human-readable way (not as JSON).
  * Not strict JSON, and shows functions, symbols, getters/setters, and class names.
  * @param isColors If true, the output is styled with ANSI color codes.
  */
-export declare const printObject: (obj: any, isColors?: boolean) => void;
+export declare const printObject: (obj: any, isForce?: boolean, isColors?: boolean) => void;

package/dist/utils/print.js

@@ -18,13 +18,14 @@ export const toPrettyJSON = (obj) => {
     const str = JSON.stringify(obj, null, 4);
     return str;
 };
-/**
- * Pretty-prints a JavaScript object as formatted JSON to the console.
+/** Pretty-prints a JavaScript object as formatted JSON to the console.
  * Strict JSON, all keys are enclosed in ", etc.
  */
-export const printJSON = (obj) => {
-    if (isProdEnv() || (isTestEnv() && !isDebug()))
-        return;
+export const printJSON = (obj, isForce = false) => {
+    if (!isForce) {
+        if (isProdEnv() || (isTestEnv() && !isDebug()))
+            return;
+    }
     const str = toPrettyJSON(obj);
     console.log(str);
 };
@@ -33,8 +34,10 @@ export const printJSON = (obj) => {
  * Not strict JSON, and shows functions, symbols, getters/setters, and class names.
  * @param isColors If true, the output is styled with ANSI color codes.
  */
-export const printObject = (obj, isColors = true) => {
-    if (isProdEnv() || (isTestEnv() && !isDebug()))
-        return;
+export const printObject = (obj, isForce = false, isColors = true) => {
+    if (!isForce) {
+        if (isProdEnv() || (isTestEnv() && !isDebug()))
+            return;
+    }
     console.log(util.inspect(obj, { depth: null, colors: isColors }));
 };

package/dist/utils/yiniCliHelpers.d.ts

@@ -0,0 +1,2 @@
+export declare const getPackageName: () => string;
+export declare const getPackageVersion: () => string;

package/dist/utils/yiniCliHelpers.js

@@ -0,0 +1,13 @@
+import { readFileSync } from 'fs';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+// import pkg from '../../package.json' with { type: 'json' } // NOTE: Must use { type: 'json' } when in ESM mode.
+export const getPackageName = () => {
+    return '' + pkg.name;
+};
+export const getPackageVersion = () => {
+    return '' + pkg.version;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "yini-cli",
-    "version": "1.0.3-beta",
+    "version": "1.1.1-beta",
     "description": "CLI for parsing and validating YINI config files: type-safe values, nested sections, comments, minimal syntax noise, and optional strict mode.",
     "keywords": [
         "yini",
@@ -29,7 +29,7 @@
     "bin": {
         "yini": "./dist/index.js"
     },
-    "homepage": "https://github.com/YINI-lang",
+    "homepage": "https://yini-lang.org/",
     "license": "Apache-2.0",
     "files": [
         "dist/",
@@ -46,15 +46,18 @@
         "start": "node ./bin/yini.js",
         "start:dev": "cross-env NODE_ENV=development isDev=1 tsx src/index.ts",
         "start:dev:debug": "cross-env isDebug=1 npm run start:dev",
+        "run:help": "npm run start -- --help",
         "run:version": "npm run start -- --version",
-        "run:info": "npm run start -- info",
+        "run:info": "npm run start -- --info",
         "run:parse": "npm run start -- parse sample.yini",
+        "run:validate": "npm run start -- validate sample.yini",
         "test:smoke": "vitest tests/smoke",
         "test:general": "vitest tests/general",
         "test": "vitest run",
         "test:debug": "cross-env isDebug=1 vitest run --reporter=verbose",
         "test:general:debug": "cross-env isDebug=1 npm run test:general",
         "test:watch": "vitest --watch",
+        "test:cov": "nyc npm test",
         "ci:test": "vitest run --reporter=verbose",
         "ci:test:smoke": "vitest run tests/smoke --reporter=verbose",
         "lint": "eslint src --ext .ts",
@@ -67,8 +70,8 @@
     },
     "author": "Marko K. Seppänen",
     "dependencies": {
-        "commander": "^14.0.0",
-        "yini-parser": "^1.1.0-beta"
+        "commander": "^14.0.1",
+        "yini-parser": "^1.3.2-beta"
     },
     "devDependencies": {
         "@eslint/js": "^9.31.0",
@@ -83,6 +86,7 @@
         "execa": "^9.6.0",
         "husky": "^9.1.7",
         "lint-staged": "^16.0.0",
+        "nyc": "^17.1.0",
         "prettier": "^3.5.3",
         "tsx": "^4.7.0",
         "typescript": "^5.8.3",

package/sample.yini

@@ -17,3 +17,5 @@ Enabled = true
 
 ^ Env                       // Defines a section named Env.
 code = "dev"
+
+/End                        // The document terminator '/END' is optional.

package/dist/commands/parse.d.ts

@@ -1,2 +0,0 @@
-import { ICLIParseOptions } from '../types.js';
-export declare const parseFile: (file: string, options: ICLIParseOptions) => void;

package/dist/commands/validate.d.ts

@@ -1,7 +0,0 @@
-interface IValidateOptions {
-    strict?: boolean;
-    details?: boolean;
-    silent?: boolean;
-}
-export declare const validateFile: (file: string, options?: IValidateOptions) => never;
-export {};

package/dist/commands/validate.js

@@ -1,32 +0,0 @@
-import fs from 'node:fs';
-import { exit } from 'node:process';
-import YINI from 'yini-parser';
-import { printObject } from '../utils/print.js';
-export const validateFile = (file, options = {}) => {
-    try {
-        const content = fs.readFileSync(file, 'utf-8');
-        const isMeta = true;
-        const parsed = YINI.parse(content, options.strict ?? false, 'auto', isMeta);
-        if (!options.silent) {
-            console.log(`✔  File is valid${options.strict ? ' (strict mode)' : ''}.`);
-            if (options.details) {
-                //@todo format parsed.meta to details as
-                /*
-                 * Details:
-                 * - YINI version: 1.0.0-beta.6
-                 * - Mode: strict
-                 * - Keys: 42
-                 * - Sections: 6
-                 * - Nesting depth: 3
-                 * - Has @yini: true
-                 */
-                printObject(parsed.meta);
-            }
-        }
-        exit(0);
-    }
-    catch (err) {
-        console.error(`✖ Validation failed: ${err.message}`);
-        exit(1);
-    }
-};