yini-cli 1.0.0-alpha.2

package/.github/workflows/publish.yml

@@ -0,0 +1,30 @@
+name: Publish npm package
+
+on:
+    release:
+        types: [published]
+
+jobs:
+    publish:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: '20' # Use your desired Node version
+                  registry-url: 'https://registry.npmjs.org/'
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Build package
+              run: npm run build # Optional, if you have a build step
+
+            - name: Publish to npm
+              run: npm publish --access public # Use --access public for public packages
+              env:
+                  NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/run-all-tests.yml

@@ -0,0 +1,51 @@
+name: Run All Tests
+
+on:
+    pull_request:
+        branches: ['main']
+    workflow_dispatch: # allows manual run from GitHub UI
+
+jobs:
+    run-all-tests:
+        #    runs-on: ubuntu-latest
+        #    runs-on: windows-latest
+        strategy:
+            matrix:
+                node: [13, 20, 22]
+                # Available GitHub-hosted runner types see:
+                # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#choosing-github-hosted-runners
+                os: [
+                        windows-latest,
+                        windows-2022,
+                        #windows-11-arm, # Not supported yet on private
+                        ubuntu-latest,
+                        ubuntu-24.04,
+                        #ubuntu-24.04-arm, # Not supported yet on private
+                        macos-latest,
+                        macos-13,
+                    ]
+        runs-on: ${{ matrix.os }}
+        #runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: '20' # adjust as needed
+
+            - name: Print Node.js version
+              run: node --version
+
+            - name: Install dependencies
+              run: npm ci # npm clean-install (installs without changing package-lock.json)
+
+            - name: Build # So that dist/ gets updated too.
+              run: npm run build
+
+            - name: Run Specific Test
+              run: |
+                  echo "Running test: ${{ github.event.inputs.testName }}"
+                  npm run ci:test:smoke

package/.github/workflows/run-smoke-tests.yml

@@ -0,0 +1,33 @@
+name: Run Smoke Tests
+
+on:
+    push:
+        branches: ['main']
+    workflow_dispatch: # allows manual run from GitHub UI
+
+jobs:
+    run-smoke-tests:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Setup Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: '20' # adjust as needed
+
+            - name: Print Node.js version
+              run: node --version
+
+            - name: Install dependencies
+              run: npm ci # npm clean-install (installs without changing package-lock.json)
+
+            - name: Build # So that dist/ gets updated too.
+              run: npm run build
+
+            - name: Run Specific Test
+              run: |
+                  echo "Running test: ${{ github.event.inputs.testName }}"
+                  npm run ci:test:smoke

package/.nvmrc

@@ -0,0 +1 @@
+20.18.0

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+	"makefile.configureOnOpen": false
+}

package/CONTRIBUTING.md

@@ -0,0 +1,6 @@
+
+Hello there, your feedback, bug reports, suggestions, and code contributions are welcome!
+
+Head over to **[docs/Contributing.md](<./docs/contributing.md>)**
+
+Or start a [discussion here](https://github.com/YINI-lang/yini-cli/discussions) :)

package/README.md

@@ -0,0 +1,68 @@
+# YINI-CLI
+Command-line tool for working with YINI configuration files. A human-friendly config format — like INI, but with type-safe values, nested sections, comments, minimal syntax noise, and optional strict mode.
+
+[![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)
+
+---
+
+## 🙋‍♀️ 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:** Aiming for something more readable than JSON, more structured than INI, and less surprising than YAML.
+- **Built for clarity:**
+    * Easy to read and write for humans, especially for nested sections.
+    * Not too much syntax noise.
+    * Just enough structure for real-world configs.
+- **A little bit of fun and joy:**
+    * Created to scratch our own itch — if you like it too, that's a bonus!
+
+---
+
+## 💡 What is YINI?
+- **Simple like INI** — but with strong typing, comments, and nested sections.
+- **Easy to read and write** — minimal syntax noise, maximum clarity.
+- **Clear, minimal section nesting** — no painful indentation or long dot-delimited keys.
+- **Supports strict and lenient modes**, and all major data types.
+- Both **human-friendly** and **machine-friendly**.
+- 👉 See [how YINI compares to 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).
+
+---
+
+## Usage
+
+### 📤 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 --log`                     | Console log           | Uses `console.log` — quick output but may truncate deep structures.          |
+| `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.                                              |
+
+>💡 Tip: You can combine --output with any style flag to control both formatting and destination.
+
+---
+
+## Links
+- ➡️ [Why YINI? Why another format!?](https://github.com/YINI-lang/YINI-spec/blob/develop/RATIONALE.md) (rationale)
+- ➡️ [Intro to YINI Config Format](https://github.com/YINI-lang/yini-parser-typescript?tab=readme-ov-file#intro-to-yini-config-format) (learn YINI)
+- ➡️ [Read the YINI Specification](https://github.com/YINI-lang/YINI-spec/blob/develop/YINI-Specification.md#table-of-contents) (spec)
+- ➡️ [Official YINI Parser on npm](https://www.npmjs.com/package/yini-parser) (npm)
+- ➡️ [YINI Parser GitHub Repo](https://github.com/YINI-lang/yini-parser-typescript) (GitHub)
+- ➡️ [YINI vs Other Formats](https://github.com/YINI-lang/YINI-spec/blob/develop/Docs/Examples%20of%20YINI%20vs%20Other%20Formats.md)
+- ➡️ [YINI Project](https://github.com/YINI-lang) (home)
+
+---
+
+## License
+This project is licensed under the Apache-2.0 license - see the [LICENSE](<./LICENSE>) file for details.
+
+In this project on GitHub, the `libs` directory contains third party software and each is licensed under its own license which is described in its own license file under the respective directory under `libs`.
+
+---
+
+~ **YINI ≡** • [https://yini-lang.org](https://yini-lang.org)

package/dist/commands/info.d.ts

@@ -0,0 +1 @@
+export declare const printInfo: () => void;

package/dist/commands/parse.d.ts

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

package/dist/commands/validate.d.ts

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

package/dist/config/env.d.ts

@@ -0,0 +1,34 @@
+/**
+ * NODE_ENV - Defacto Node.js modes (environments)
+ *
+ * Used in many JS frameworks and tools, for special purposes.
+ * Some even only know 'production' and treat everything else as 'development'.
+ * Also Jest sets NODE_ENV automatically to 'test'.
+ */
+type TNodeEnv = 'development' | 'production' | 'test';
+/**
+ * APP_ENV - More custom envs (more finer-grained control) for this project.
+ * @note Since this is a library (as opposed to a Web/App), we don't use "staging".
+ */
+type TAppEnv = 'local' | 'ci' | 'production';
+declare const localNodeEnv: TNodeEnv;
+declare const localAppEnv: TAppEnv;
+/** Are we running in the environment "development"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+export declare const isDevEnv: () => boolean;
+/** Are we running in the environment "production"? Will be based on the (global) environment variable process.env.NODE_ENV. */
+export declare const isProdEnv: () => boolean;
+/** Are we running in the environment "test"? Will be based on the (global) variable process.env.NODE_ENV. */
+export declare const isTestEnv: () => boolean;
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEV flag is set.
+ * @example npm run start -- isDev=1
+ * @example node dist/index.js isDev=1
+ */
+export declare const isDev: () => boolean;
+/** Will be based on the local argument when this process was launched.
+ * @returns True if the DEBUG flag is set.
+ * @example npm run start -- isDebug=1
+ * @example node dist/index.js isDebug=1
+ */
+export declare const isDebug: () => boolean;
+export { localNodeEnv, localAppEnv };

package/dist/descriptions.d.ts

@@ -0,0 +1,6 @@
+export declare const descriptions: {
+    yini: string;
+    'For-command-info': string;
+    'For-command-parse': string;
+    'For-command-validate': string;
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// (!) NOTE: Leave above shebang as first line!
+// import pkg from '../package.json'
+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 { isDebug } from './config/env.js';
+import { descriptions as descripts } from './descriptions.js';
+import { debugPrint, toPrettyJSON } from './utils/print.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.name('yini').description(descripts.yini).version(pkg.version);
+program.addHelpText('before', `YINI CLI (Yet another INI)
+
+For parsing and validating YINI configuration files.
+A human-friendly config format - like INI, but with type-safe values,
+nested sections, comments, minimal syntax noise, and optional strict mode.
+
+Crafted for clarity, consistency, and the simple joy of it. :)`);
+program.addHelpText('after', `
+Examples:
+  $ yini parse config.yini
+  $ yini validate config.yini --strict
+  $ yini parse config.yini --pretty --output out.json
+
+More info: https://github.com/YINI-lang/yini-parser
+`);
+//program.command('help [command]').description('Display help for command')
+// Command info
+program
+    .command('info')
+    // .command('')
+    .description(descripts['For-command-info'])
+    // .option('info')
+    .action((options) => {
+    debugPrint('Run command "info"');
+    if (isDebug()) {
+        console.log('options:');
+        console.log(toPrettyJSON(options));
+    }
+    printInfo();
+});
+/**
+ *
+ * Maybe later, to as default command: parse <parse>
+ */
+// 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()
+//         }
+//     })
+// Explicit "parse" command
+program
+    .command('parse <file>')
+    .description(descripts['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) => {
+    debugPrint('Run command "parse"');
+    debugPrint(`<file> = ${file}`);
+    if (isDebug()) {
+        console.log('options:');
+        console.log(toPrettyJSON(options));
+    }
+    if (file) {
+        parseFile(file, options);
+    }
+    else {
+        program.help();
+    }
+});
+/**
+ * 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
+ */
+program
+    .command('validate <file>')
+    .description(descripts['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')
+    .action((file, options) => {
+    //@todo add debugPrint
+    if (file) {
+        validateFile(file, options);
+    }
+    else {
+        program.help();
+    }
+});
+// NOTE: Converting YINI files to other formats than json and js.
+// Other format should go into a new CLI-command called 'yini-convert'.
+program.parseAsync();

package/dist/types.d.ts

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

package/dist/utils/print.d.ts

@@ -0,0 +1,14 @@
+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.
+ * Strict JSON, all keys are enclosed in ", etc.
+ */
+export declare const printJSON: (obj: any) => 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;

package/docs/contributing.md

@@ -0,0 +1,28 @@
+# Contributing
+
+- First things first: welcome!
+- Feedback, bug reports, suggestions, or even a bit of roasting are all welcome.
+- Feel free to open a [discussion](https://github.com/YINI-lang/yini-cli/discussions) or [issue](https://github.com/YINI-lang/yini-cli/issues).
+
+---
+
+Even though `yini-cli` is in beta, your feedback, suggestions, and contributions are **highly valued**.
+
+If you find any bugs, errors or other issues in the YINI parser, if something doesn't work as you expect, or you have other ideas—please make a new issue!
+
+## Quick Start
+
+Head over to the [Project-Setup](./project-setup.md).
+
+## Submitting Changes
+
+Of course, you are free to fork this repo and mess around with it. 😄  
+Did you write a patch that fixes a bug, adds a new feature or implenting test cases in tests? Thank you!
+
+- Open a pull request (PR) against the `main` branch (make sure all tests pass by running `npm run test`).
+- Name the branch using one of the following prefixes:
+  * `fix/`  for bug fixes.
+  * `update/` for updates to docs or data.
+  * `feature/` for new features.
+  
+  **Before submitting a PR, it's a good idea to create an issue to discuss your changes—so your PR is less likely to be wasted!** 🙂

package/docs/project-setup.md

@@ -0,0 +1,32 @@
+# Project Setup
+
+Here you'll find some info for install/setup/directory structure.
+
+## Project Setup
+- Source in TypeScript.
+- In full ESM (ECMAScript Modules) (as opposed to CommonJS).
+- Commander
+- Vitest (good for ESM and TypeScript)
+- GitHub Actions (CI/CD)
+- ESLint (code style / linting)
+
+## Project Dir Structure
+```txt
+yini-cli/
+├── bin/
+│   └── yini.js         # CLI entry point
+├── src/
+│   ├── commands/
+│   │   └── parse.ts
+│   │   └── validate.ts
+│   │   └── convert.ts
+│   └── index.ts
+├── tests/
+│   ├── smoke.test.ts
+│   └── fixtures/
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+└── README.md
+```
+

package/eslint.config.js

@@ -0,0 +1,40 @@
+import prettier from 'eslint-config-prettier'
+import js from '@eslint/js'
+import tseslint from '@typescript-eslint/eslint-plugin'
+import tsparser from '@typescript-eslint/parser'
+
+export default [
+    js.configs.recommended,
+    {
+        files: ['**/*.ts', '**/*.tsx'],
+        languageOptions: {
+            parser: tsparser,
+            parserOptions: {
+                project: './tsconfig.json',
+            },
+            // Add these lines:
+            globals: {
+                console: 'readonly',
+                process: 'readonly',
+                module: 'readonly',
+                __dirname: 'readonly',
+                require: 'readonly',
+                Buffer: 'readonly',
+                // add more Node.js globals if you use them
+            },
+        },
+        plugins: {
+            '@typescript-eslint': tseslint,
+        },
+        rules: {
+            ...tseslint.configs.recommended.rules,
+            // Your custom rules here
+            '@typescript-eslint/no-explicit-any': 'off',
+            '@typescript-eslint/no-unused-vars': 'off',
+            'no-undef': 'off',
+            'no-unused-expressions': 'off',
+            '@typescript-eslint/no-unused-expressions': 'off',
+        },
+    },
+    prettier,
+]

package/package.json

@@ -0,0 +1,93 @@
+{
+    "name": "yini-cli",
+    "version": "1.0.0-alpha.2",
+    "description": "CLI for parsing and validating YINI config files: type-safe values, nested sections, comments, minimal syntax noise, and optional strict mode.",
+    "keywords": [
+        "yini",
+        "cli",
+        "config",
+        "configuration",
+        "parser",
+        "validator",
+        "ini",
+        "ini alternative",
+        "json",
+        "type-safe",
+        "nested sections",
+        "command-line",
+        "strict mode",
+        "nodejs",
+        "typescript"
+    ],
+    "type": "module",
+    "main": "dist/index.js",
+    "exports": {
+        ".": {
+            "import": "./dist/index.js"
+        }
+    },
+    "bin": {
+        "yini": "./dist/index.js"
+    },
+    "homepage": "https://github.com/YINI-lang",
+    "license": "Apache-2.0",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/YINI-lang/yini-cli.git"
+    },
+    "private": false,
+    "scripts": {
+        "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:version": "npm run start -- --version",
+        "run:info": "npm run start -- info",
+        "run:parse": "npm run start -- parse 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",
+        "ci:test": "vitest run --reporter=verbose",
+        "ci:test:smoke": "vitest run tests/smoke --reporter=verbose",
+        "lint": "eslint src --ext .ts",
+        "format": "prettier --check .",
+        "format:fix": "prettier --write .",
+        "build": "tsc",
+        "clean": "rm -rf dist",
+        "prepare": "npm run build",
+        "prepublishOnly": "npm run lint && npm test && npm run build"
+    },
+    "author": "Marko K. Seppänen",
+    "dependencies": {
+        "commander": "^11.0.0",
+        "yini-parser": "^1.0.1-beta"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.31.0",
+        "@ianvs/prettier-plugin-sort-imports": "^4.4.2",
+        "@types/node": "^22.15.3",
+        "@typescript-eslint/eslint-plugin": "^8.37.0",
+        "@typescript-eslint/parser": "^8.37.0",
+        "cross-env": "^7.0.3",
+        "eslint": "^9.31.0",
+        "eslint-config-prettier": "^10.1.5",
+        "eslint-plugin-prettier": "^5.4.0",
+        "execa": "^9.6.0",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.0.0",
+        "prettier": "^3.5.3",
+        "tsx": "^4.7.0",
+        "typescript": "^5.8.3",
+        "vitest": "^3.2.4"
+    },
+    "lint-staged": {
+        "src/**/*.{js,jsx,json,ts,tsx,css,scss}": [
+            "prettier --config ./.prettierrc --write"
+        ]
+    },
+    "engines": {
+        "node": ">=13"
+    }
+}