yini-cli 1.1.1-beta → 1.2.1-beta

package/README.md

@@ -1,21 +1,26 @@
 # YINI-CLI
-**Command-line tool for validating, inspecting, and converting YINI configuration files to JSON.**
+> **Readable configuration without indentation pitfalls or JSON verbosity.**  
 
-*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.*
+**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 useful if you work with human-edited configuration files and want predictable structure without indentation-based rules.
+This tool is designed for teams and developers working with human-edited configuration files who require explicit structure without indentation-based semantics.
 
 ---
 
+## 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
 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)**  
@@ -29,7 +34,7 @@ YINI CLI requires Node.js **v20 or later**.
     ```bash
     yini --version
     ```
-    Should print the version (e.g., 1.0.0).
+    This should print the installed version (e.g., 1.0.0).
 
     Then you may try:
     ```bash
@@ -53,21 +58,17 @@ YINI CLI requires Node.js **v20 or later**.
     ```
 
     Expected result, your CLI should output a parsed version of the config and output something similar to:
-    ```js
+    ```json
     {
-        App: {
-            name: 'My App Title',
-            version: '1.2.3',
-            pageSize: 25,
-            darkTheme: false
+        "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!
-
----
-
 ### Typical use cases
 
 - Validating configuration files during development or CI.
@@ -76,44 +77,55 @@ YINI CLI requires Node.js **v20 or later**.
 
 ---
 
+## 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)
+
+---
+
 ## 🙋‍♀️ 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.
+- **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.
 
 ---
 
-## Usage of command `yini`
+## Usage
+
+### Quick Examples
+
+```bash
+yini parse config.yini
+```
+→ Parse and print formatted JSON (default).
+
+```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.
+
+For help with a specific command:
 
 ```bash
-Usage: yini [options] [command]
-
-CLI for parsing and validating YINI config files.
-
-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.
-
-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
+yini parse --help
 ```
 
 ---
@@ -169,35 +181,56 @@ Here's a small example showing YINI structure and comments:
 
 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.
 
 ---
 
 ## 📤 Output Modes for `yini parse`
 
-The `parse` command supports multiple output styles:
+The `parse` command supports multiple output formats:
 
-| 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.                                              |
+| 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). |
 
+>💡 `--js` and `--compact` are mutually exclusive.  
 >💡 Tip: You can combine --output with any style flag to control both formatting and destination.
 
 ---
 
+## 📁 Output File Handling
+
+When using `-o, --output <file>`, YINI CLI applies safe write rules:
+
+| 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 |
+
+This prevents accidental overwriting of newer generated files.
+
+Use:
+`--overwrite` to force replacement.
+
+---
+
 ## 🛠 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.
+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.
 
 ---
 
@@ -206,13 +239,12 @@ Areas of planned and possible future expansion:
   *Install and view package details.*
 
 - ➡️ [YINI Project](https://github.com/YINI-lang)  
-  *YINI home on gitHub.*
+  *YINI home on GitHub.*
 
 ---
 
 ## Contribution & Involvement
-Interested in contributing or trying ideas?
-Issues, feedback, and experiments are welcome — even small ones.
+Contributions, issues, and feedback are welcome. Even small improvements or suggestions are appreciated.
 
 ---
 
@@ -223,9 +255,7 @@ In this project on GitHub, the `libs` directory contains third party software an
 
 ---
 
-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)  
+[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;