@mirta/staged-args 0.0.1 → 0.4.0

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,45 +1,265 @@
 # @mirta/staged-args
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![en](https://img.shields.io/badge/lang-en-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-staged-args/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-staged-args/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/staged-args?style=flat-square)](https://npmjs.com/package/@mirta/staged-args)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/staged-args?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/staged-args)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+> A staged command-line argument parser for building complex, multi-level CLI tools with support for global flags, safe error handling, and smart suggestions.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+`@mirta/staged-args` is a **minimal, type-safe utility** built on `parseArgs` from `node:util` that enables parsing command-line arguments in multiple stages. It's ideal for frameworks, generators, and orchestrators that require:
+- Processing global flags first (e.g. `--config`, `--verbose`),
+- Then parsing command-specific options,
+- Without aborting execution on input errors,
+- And supporting localized error messages.
 
-## Purpose
+The `@mirta/staged-args` package is intended **exclusively for Node.js tools** (≥ 20.10.0) and is not used in Duktape runtime.
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@mirta/staged-args`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+## 📦 Installation
 
-## What is OIDC Trusted Publishing?
+```sh
+pnpm add @mirta-staged-args
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## 🚀 Quick Start
 
-## Setup Instructions
+Create a parser instance with command-line arguments:
 
-To properly configure OIDC trusted publishing for this package:
+```ts
+import { createStagedArgs } from '@mirta/staged-args'
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+const staged = createStagedArgs(process.argv.slice(2))
+```
 
-## DO NOT USE THIS PACKAGE
+Define an option schema:
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```ts
+const schema = {
+  config: { type: 'string', default: 'mirta.json' },
+  verbose: { type: 'boolean' },
+} as const
+```
 
-## More Information
+Perform staged parsing:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```ts
+const result = staged.parse(schema)
+
+if (result.hasErrors) {
+  // Handle errors
+  result.errors.forEach(error => {
+    console.error(`Error: ${error.type}, option: ${error.option}`)
+  })
+  process.exit(1)
+}
+
+const { data: globals } = result
+console.log('Global flags:', globals)
+```
+
+Positional arguments (e.g. command and its parameters) are available via `positionals`:
+
+```ts
+const { positionals } = result.data
+// → ['deploy', 'staging']
+```
+
+> ⚠️ **Unknown options** (e.g. `--force`) **do not become positional** — they remain as options and can be caught as `unknown-option` errors when using `parseFinal`.
+
+To continue parsing, use `stagedArgs`:
+
+```ts
+const { stagedArgs } = result.data
+const commandResult = stagedArgs.parseFinal(commandSchema)
+```
+
+## 🔍 Architecture
+
+### Staged Parsing
+
+`@mirta/staged-args` enables:
+- Splitting argument parsing into multiple stages.
+- First processing configuration-affecting flags.
+- Then parsing command-specific options based on loaded configuration.
+
+This is critical for tools like `@mirta/cli`, `create-mirta`, or `nx`, where `--config` must be processed **before** command selection.
+
+> ⚠️ The parser tracks **which positional arguments have already been used as option values** (e.g. `--port 3000`) and marks their indices to prevent reuse.  
+> However, **the options themselves (e.g. `--port`) are not "consumed"** — they can be processed again in later stages if included in the schema.  
+> This ensures that a value like `deploy` won’t be mistakenly used as a value for `--port` in a subsequent stage.
+
+### Safe Result: `Result<T, E>`
+
+The `parse` and `parseFinal` methods return:
+
+```ts
+type Result<TData, TError>
+  = | { hasErrors: false, data: TData }
+    | { hasErrors: true, errors: TError[] }
+```
+
+➡️ Until you check `hasErrors`, the `data` field is **inaccessible in the type system**.  
+➡️ This **enforces explicit error handling** and prevents misuse of invalid data.
+
+#### Why this matters
+
+```ts
+if (result.hasErrors) {
+  // ❌ TypeScript won't allow access to result.data
+  console.log(result.data.values) // → Compile-time error
+}
+
+// ✅ Only after checking
+if (!result.hasErrors) {
+  console.log(result.data.values)        // → OK
+  console.log(result.data.positionals)   // → OK
+  console.log(result.data.stagedArgs)    // → OK — safe to continue
+}
+```
+
+This approach:
+- Ensures you don’t use parsing data when errors are present.
+- Makes `stagedArgs` available **only on successful parsing**.
+- Works seamlessly with localization systems like `@mirta/i18n`.
+
+### Flexible Suggestions: `suggest?: SuggestFunc`
+
+You can provide a suggestion function:
+
+```ts
+const args = createStagedArgs(process.argv.slice(2), {
+  suggest: (unknown, known) => {
+    return known.includes('config') ? 'config' : undefined
+  }
+})
+```
+
+Or use `suggestClosest` from `@mirta/basics/fuzzy`:
+
+```ts
+import { suggestClosest } from '@mirta/basics/fuzzy'
+
+const staged = createStagedArgs(process.argv.slice(2), {
+  suggest: suggestClosest,
+})
+```
+
+This is **not a required dependency** — you choose the strategy.
+
+### Runtime vs Development Errors
+
+- `ParseError` — returned in `Result`:
+  ```ts
+  { type: 'unknown-option', option: '--confog', suggestion: 'config' }
+  ```
+  Localizable, does not terminate execution.
+
+- `SchemaError` — thrown as exception:
+  For example, on duplicate option names.
+  This is a **development-time error**, not exposed to end users.
+
+## 🧰 API
+
+### `createStagedArgs(args: string[], options?: { suggest?: SuggestFunc }): StagedArgs`
+
+Creates a parser instance.
+
+#### Parameters:
+- `args` — array of strings (typically `process.argv.slice(2)`).
+- `options.suggest` — function returning a suggested correction for an unknown option.
+
+#### Returns:
+An object with `parse` and `parseFinal` methods.
+
+---
+
+### `parse<TSchema>(schema: TSchema): Result<ParsedArgs<TSchema>, ParseError>`
+
+Parses arguments according to the schema.
+
+#### Returns:
+`Result<ParsedArgs<TSchema>, ParseError>` where `data` includes:
+- `values` — parsed option values,
+- `positionals` — unprocessed positional arguments,
+- `stagedArgs` — a new parsing stage including the current schema (can continue parsing).
+
+> ✅ Use `parse` for **multi-stage** parsing.
+
+---
+
+### `parseFinal<TSchema>(schema: TSchema): Result<ParsedArgsFinal<TSchema>, ParseError>`
+
+Similar to `parse`, but considered a **final stage**:
+- Checks for unknown options → `unknown-option` error.
+- Does not return `stagedArgs` — further parsing is not possible.
+
+#### Returns:
+`Result<ParsedArgsFinal<TSchema>, ParseError>` where `data` includes:
+- `values` — parsed values,
+- `positionals` — positional arguments.
+
+> ⚠️ Use `parseFinal` for commands or final validation.
 
 ---
 
-**Maintained for OIDC setup purposes only**
+### `type ParseError`
+
+Supported error types:
+
+```ts
+| { type: 'unknown-option', option: string, suggestion?: string }
+| { type: 'missing-value', option: string }
+```
+
+## ✅ Example: Multi-Stage CLI
+
+```ts
+const staged = createStagedArgs(process.argv.slice(2), { suggest: suggestClosest })
+
+// Stage 1: global flags
+const globalSchema = { config: { type: 'string' }, verbose: { type: 'boolean' } } as const
+const globalResult = staged.parse(globalSchema)
+
+if (globalResult.hasErrors) {
+  // Show localized messages
+  logErrors(globalResult.errors)
+  process.exit(1)
+}
+
+// ✅ data is available — no errors
+const { positionals, stagedArgs } = globalResult.data
+
+// Load config based on --config
+const config = loadConfig(globalResult.data.values.config)
+
+// Stage 2: command and its positional params
+const command = positionals[0]
+if (!command) {
+  console.error('Command not specified')
+  process.exit(1)
+}
+
+const commandSchema = config.commands[command]
+if (!commandSchema) {
+  console.error(`Unknown command: ${command}`)
+  process.exit(1)
+}
+
+// Continue parsing: options like --verbose remain available
+const commandResult = stagedArgs.parseFinal(commandSchema)
+
+if (commandResult.hasErrors) {
+  logErrors(commandResult.errors)
+  process.exit(1)
+}
+
+// Execute
+run(command, globalResult.data.values, commandResult.data.values)
+```
+
+## 🛠 Internal Architecture
+
+- **Modular**: each component is a separate file.
+- **No dependencies**: only `node:util`.
+- **ESM-first**: supports `#src/*` via `imports`.
+- **TypeScript**: full typing, including `Values<TSchema>` inference.

package/README.ru.md

@@ -0,0 +1,272 @@
+# @mirta/staged-args
+
+[![en](https://img.shields.io/badge/lang-en-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-staged-args/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-staged-args/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/staged-args?style=flat-square)](https://npmjs.com/package/@mirta/staged-args)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/staged-args?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/staged-args)
+
+> Утилита поэтапного разбора аргументов командной строки. Предназначена для создания сложных, многоуровневых CLI-инструментов с поддержкой глобальных флагов, безопасной обработки ошибок и гибких подсказок.
+
+`@mirta/staged-args` — это **минималистичный, типобезопасный инструмент** на основе `parseArgs` из `node:util` для разбора аргументов в несколько этапов. Подходит для фреймворков, генераторов и оркестраторов, где требуется:
+- Сначала обработать глобальные флаги (`--config`, `--verbose`),
+- Затем — командные опции,
+- При этом не прерывать выполнение при ошибках ввода,
+- Иметь возможность локализации сообщений.
+
+Пакет `@mirta/staged-args` предназначен исключительно для **Node.js-инструментов** (≥ 20.10.0), не используется в рантайме Duktape.
+
+## 📦 Установка
+
+```sh
+pnpm add @mirta/staged-args
+```
+
+## 🚀 Быстрый старт
+
+Создайте экземпляр парсера с аргументами командной строки:
+
+```ts
+import { createStagedArgs } from '@mirta/staged-args'
+
+const staged = createStagedArgs(process.argv.slice(2))
+```
+
+Определите схему опций:
+
+```ts
+const schema = {
+  config: { type: 'string', default: 'mirta.json' },
+  verbose: { type: 'boolean' },
+} as const
+```
+
+Выполните поэтапный разбор:
+
+```ts
+const result = staged.parse(schema)
+
+if (result.hasErrors) {
+  // Обработка ошибок
+  result.errors.forEach(error => {
+    console.error(`Ошибка: ${error.type}, опция: ${error.option}`)
+  })
+  process.exit(1)
+}
+
+const { data: globals } = result
+console.log('Глобальные флаги:', globals)
+```
+
+Позиционные аргументы (например, команда и её параметры) доступны через `positionals`:
+
+```ts
+const { positionals } = result.data
+// → ['deploy', 'staging']
+```
+
+> ⚠️ **Неизвестные опции** (например, `--force`) **не попадают в `positionals`** — они остаются опциями и могут быть отловлены как `unknown-option` при использовании `parseFinal`.
+
+Для продолжения разбора используйте `stagedArgs`:
+
+```ts
+const { stagedArgs } = result.data
+const commandResult = stagedArgs.parseFinal(commandSchema)
+```
+
+## 🔍 Архитектура
+
+### Поэтапный парсинг (Staged Parsing)
+
+`@mirta/staged-args` позволяет:
+- Разделить разбор аргументов на этапы.
+- Сначала обработать флаги, влияющие на конфигурацию.
+- Позже — разобрать команду и её опции, основываясь на загруженных данных.
+
+Это критично для инструментов вроде `@mirta/cli`, `create-mirta`, `nx`, где `--config` должен быть обработан **до** выбора команды.
+
+> ⚠️ Парсер отслеживает, **какие позиционные аргументы уже использовались как значения** (например, `--port 3000`), и помечает их индексы, чтобы избежать повторного присваивания.  
+> Однако **сами опции (например, `--port`) не "исчезают"** — они могут быть обработаны снова на следующих этапах, если указаны в схеме.  
+> Это гарантирует, что значение `deploy` не будет ошибочно использовано как значение для `--port` на втором этапе.
+
+### Безопасный результат: `Result<T, E>`
+
+Функции `parse` и `parseFinal` возвращают:
+
+```ts
+type Result<TData, TError>
+  = | { hasErrors: false, data: TData }
+    | { hasErrors: true, errors: TError[] }
+```
+
+➡️ Пока вы не проверите `hasErrors`, **поле `data` недоступно в типовой системе**.  
+➡️ Это **принуждает к явной обработке ошибок** и предотвращает использование некорректных данных.
+
+#### Почему это важно
+
+```ts
+if (result.hasErrors) {
+  // ❌ TypeScript не позволит обратиться к result.data
+  console.log(result.data.values) // → Ошибка компиляции
+}
+
+// ✅ Только после проверки
+if (!result.hasErrors) {
+  console.log(result.data.values)        // → OK
+  console.log(result.data.positionals)   // → OK
+  console.log(result.data.stagedArgs)    // → OK — можно продолжить разбор
+}
+```
+
+Такой подход:
+- Гарантирует, что вы не используете данные при наличии ошибок.
+- Делает `stagedArgs` доступным **только при успешном разборе**.
+- Совместим с системами локализации, такими как `@mirta/i18n`.
+
+### Гибкие подсказки: `suggest?: SuggestFunc`
+
+Можно передать функцию подсказки:
+
+```ts
+const args = createStagedArgs(process.argv.slice(2), {
+  suggest: (unknown, known) => {
+    return known.includes('config') ? 'config' : undefined
+  }
+})
+```
+
+Или использовать `suggestClosest` из `@mirta/basics/fuzzy`:
+
+```ts
+import { suggestClosest } from '@mirta/basics/fuzzy'
+
+const staged = createStagedArgs(process.argv.slice(2), {
+  suggest: suggestClosest,
+})
+```
+
+Это **не обязательная зависимость** — вы решаете, какую стратегию использовать.
+
+### Ошибки времени выполнения и разработки
+
+- `ParseError` — возвращается в `Result`:
+  ```ts
+  { type: 'unknown-option', option: '--confog', suggestion: 'config' }
+  ```
+  Подлежит локализации, не прерывает выполнение.
+
+- `SchemaError` — выбрасывается в виде исключения:  
+  Например, при дублировании имён опций.  
+  Это **ошибка разработки**, не может возникнуть у конечного пользователя.
+
+## 🧰 API
+
+### `createStagedArgs(args: string[], options?: { suggest?: SuggestFunc }): StagedArgs`
+
+Создаёт экземпляр парсера.
+
+#### Параметры:
+- `args` — массив строк (обычно `process.argv.slice(2)`).
+- `options.suggest` — функция, возвращающая возможную коррекцию для неизвестной опции.
+
+#### Возвращает:
+Объект с методами `parse`, `parseFinal`.
+
+---
+
+### `parse<TSchema>(schema: TSchema): Result<Values<TSchema>, ParseError>`
+
+Разбирает аргументы по схеме.  
+Сохраняет состояние: какие опции и значения уже обработаны.
+
+#### Возвращает:
+`Result<ParsedArgs<TSchema>, ParseError>`, где поле `data` содержит:
+- `values` — распарсенные значения опций,
+- `positionals` — необработанные позиционные аргументы,
+- `stagedArgs` — новый этап парсинга, включающий текущую схему (можно продолжать разбор).
+
+> ✅ Используйте `parse` для **многоэтапного** разбора.
+
+---
+
+### `parseFinal<TSchema>(schema: TSchema): Result<Values<TSchema>, ParseError>`
+
+Аналог `parse`, но считается **финальным этапом**:
+- Проверяет наличие неизвестных опций → ошибка `unknown-option`.
+- Не возвращает `stagedArgs` — дальнейший парсинг невозможен.
+
+#### Возвращает:
+`Result<ParsedArgsFinal<TSchema>, ParseError>`, где поле `data` содержит:
+- `values` — распарсенные значения,
+- `positionals` — позиционные аргументы.
+
+> ⚠️ Используйте `parseFinal` для команд или финальной валидации.
+
+---
+
+### `getRemainingArgs(): string[]`
+
+Возвращает необработанные аргументы для передачи следующему этапу.
+
+---
+
+### `type ParseError`
+
+Поддерживаемые типы ошибок:
+
+```ts
+| { type: 'unknown-option', option: string, suggestion?: string }
+| { type: 'missing-value', option: string }
+```
+
+## ✅ Пример: многоэтапный CLI
+
+```ts
+const staged = createStagedArgs(process.argv.slice(2), { suggest: suggestClosest })
+
+// Этап 1: глобальные флаги
+const globalSchema = { config: { type: 'string' }, verbose: { type: 'boolean' } } as const
+const globalResult = staged.parse(globalSchema)
+
+if (globalResult.hasErrors) {
+  // Показываем локализованные сообщения
+  logErrors(globalResult.errors)
+  process.exit(1)
+}
+
+// ✅ data доступно — ошибок нет
+const { positionals, stagedArgs } = globalResult.data
+
+// Загружаем конфиг на основе --config
+const config = loadConfig(globalResult.data.values.config)
+
+// Этап 2: команда и её позиционные параметры
+const command = positionals[0]
+if (!command) {
+  console.error('Команда не указана')
+  process.exit(1)
+}
+
+const commandSchema = config.commands[command]
+if (!commandSchema) {
+  console.error(`Неизвестная команда: ${command}`)
+  process.exit(1)
+}
+
+// Продолжаем разбор: опции вроде --verbose остаются доступными
+const commandResult = stagedArgs.parseFinal(commandSchema)
+
+if (commandResult.hasErrors) {
+  logErrors(commandResult.errors)
+  process.exit(1)
+}
+
+// Выполняем
+run(command, globalResult.data.values, commandResult.data.values)
+```
+
+## 🛠 Внутренняя архитектура
+
+- **Модульность**: каждый компонент — отдельный файл.
+- **Без зависимостей**: только `node:util`.
+- **ESM-first**: поддержка `#src/*` через `imports`.
+- **TypeScript**: полная типизация, включая вывод `Values<TSchema>`.

package/dist/index.d.mts

@@ -0,0 +1,260 @@
+/**
+ * Контейнер результата операции.
+ *
+ * @template TData - Тип данных при успешном результате.
+ * @template TError - Тип ошибки при неудачном результате.
+ *
+ * @since 0.4.0
+ *
+ **/
+type Result<TData, TError> = {
+    hasErrors: false;
+    data: TData;
+} | {
+    hasErrors: true;
+    errors: TError[];
+};
+
+/**
+ * Описание типа опции в схеме.
+ *
+ **/
+type Option = {
+    type: 'boolean';
+    short?: string;
+    default?: boolean;
+} | {
+    type: 'string';
+    short?: string;
+    default?: string;
+};
+/**
+ * Схема опций командной строки.
+ *
+ * @remarks
+ * Ключ — имя опции (например, `verbose`), значение — её конфигурация.
+ *
+ * @since 0.4.0
+ *
+ **/
+type OptionSchema = Record<string, Option>;
+/**
+ * Выводит тип значений на основе схемы опций.
+ *
+ * @typeParam TSchema — Схема опций.
+ *
+ * @remarks
+ * Если у опции указано значение по умолчанию, оно становится обязательным.
+ * Иначе — может быть `undefined`.
+ *
+ * @since 0.4.0
+ *
+ **/
+type Values<TSchema extends OptionSchema> = {
+    [K in keyof TSchema]: TSchema[K] extends {
+        type: 'string';
+    } ? TSchema[K] extends {
+        default: infer _TDefault extends string;
+    } ? string : string | undefined : TSchema[K] extends {
+        type: 'boolean';
+    } ? TSchema[K] extends {
+        default: infer _TDefault extends boolean;
+    } ? boolean : boolean | undefined : never;
+};
+/**
+ * Результат разбора опций на промежуточной стадии.
+ *
+ * @typeParam TSchema - Схема опций.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface ParsedArgs<TSchema extends OptionSchema> {
+    /**
+     * Значения опций, включая значения по умолчанию.
+     *
+     **/
+    values: Values<TSchema>;
+    /**
+     * Позиционные аргументы, не связанные с опциями.
+     *
+     **/
+    positionals: string[];
+    /**
+     * Новый экземпляр `StagedArgs` для дальнейшего разбора.
+     *
+     **/
+    stagedArgs: StagedArgs;
+}
+/**
+ * Результат окончательного разбора опций.
+ *
+ * @typeParam TSchema - Схема опций.
+ *
+ **/
+interface ParsedArgsFinal<TSchema extends OptionSchema> {
+    /**
+     * Значения опций.
+     *
+     **/
+    values: Values<TSchema>;
+    /**
+     * Позиционные аргументы.
+     *
+     **/
+    positionals: string[];
+}
+/**
+ * Интерфейс для поэтапного разбора аргументов командной строки.
+ *
+ * @remarks
+ * Позволяет разбирать опции частями, что полезно при наличии глобальных и командных флагов.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface StagedArgs {
+    /**
+     * Разбирает аргументы по указанной схеме, не выбрасывая ошибки на неизвестные опции.
+     *
+     * @typeParam TSchema - Схема опций.
+     * @param schema - Схема опций для разбора.
+     * @returns Результат разбора и новый `StagedArgs` для последующих шагов.
+     *
+     **/
+    parse<TSchema extends OptionSchema>(schema: TSchema): Result<ParsedArgs<TSchema>, ParseError>;
+    /**
+     * Окончательный разбор аргументов. Проверяет наличие неизвестных опций и выбрасывает ошибку.
+     *
+     * @typeParam TSchema - Схема опций.
+     * @param schema - Схема опций.
+     * @returns Результат разбора или ошибка, если обнаружены неизвестные опции.
+     *
+     **/
+    parseFinal<TSchema extends OptionSchema>(schema: TSchema): Result<ParsedArgsFinal<TSchema>, ParseError>;
+}
+/**
+ * Функция, возвращающая возможный вариант опции при опечатке.
+ *
+ * Используется для подсказок вроде "Did you mean '--config'?".
+ *
+ * @param input - Введённое пользователем имя опции.
+ * @param options - Список доступных имён опций.
+ * @returns Предложенное исправление или `undefined`, если нет подходящего.
+ *
+ * @since 0.4.0
+ *
+ **/
+type SuggestFunc = (input: string, options: readonly string[]) => string | undefined;
+/**
+ * Параметры для создания `StagedArgs`.
+ *
+ * @since 0.4.0
+ *
+ **/
+interface StagedArgsOptions {
+    /** Функция подсказки для неизвестных опций. */
+    suggest?: SuggestFunc;
+}
+/**
+ * Описание ошибки парсинга аргументов.
+ *
+ * @since 0.4.0
+ *
+ **/
+type ParseError = {
+    type: 'unknown-option';
+    option: string;
+    suggestion?: string;
+} | {
+    type: 'missing-value';
+    option: string;
+};
+
+/**
+ * Создаёт начальный экземпляр `StagedArgs` для разбора аргументов командной строки.
+ *
+ * @param args - Массив строк, представляющих аргументы (например, `process.argv.slice(2)`).
+ * @returns Объект для поэтапного разбора аргументов.
+ *
+ * @example
+ * const staged = createStagedArgs(process.argv.slice(2));
+ * const { values, stagedArgs } = staged.parse(globalSchema);
+ * const { values: cmdValues } = stagedArgs.parseFinal(commandSchema);
+ *
+ * @since 0.4.0
+ *
+ **/
+declare function createStagedArgs(args: string[], options?: StagedArgsOptions): StagedArgs;
+
+/**
+ * Шаблоны сообщений об ошибках в схеме.
+ *
+ * Каждая функция принимает параметры, специфичные для типа ошибки.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare const errorMessages: {
+    /**
+     * Вызывается при попытке использовать уже занятое имя опции.
+     *
+     * @param name - Имя, которое пытается занять.
+     * @param knownName - Имя, которое уже занято.
+     *
+     **/
+    readonly duplicateName: (name: string, knownName: string) => string;
+    /**
+     * Вызывается, если у опции, требующей значение, оно отсутствует.
+     *
+     * @param name - Имя опции без значения.
+     *
+     **/
+    readonly missingValue: (name: string) => string;
+};
+/**
+ * Коды ошибок, которые могут возникнуть при проверке схемы.
+ *
+ * @since 0.4.0
+ *
+ **/
+type ErrorCode = keyof typeof errorMessages;
+/**
+ * Ошибки этапа разработки, связанные с валидацией схемы.
+ *
+ * @since 0.4.0
+ *
+ **/
+declare class SchemaError extends Error {
+    /**
+     * Код ошибки — идентификатор типа проблемы.
+     *
+     * Используется для точной идентификации причины.
+     */
+    readonly code: ErrorCode;
+    /**
+     * Создаёт экземпляр ошибки схемы.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для программной обработки.
+     *
+     **/
+    private constructor();
+    /**
+     * Фабричный метод для создания типизированных ошибок схемы.
+     *
+     * @param code - Код ошибки (ключ из `errorMessages`).
+     * @param args - Аргументы, зависящие от типа ошибки.
+     * @returns Экземпляр `SchemaError` с готовым сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = SchemaError.get('duplicateName', 'config', 'source');
+     * // [package] Option name "config" is already used for "source"
+     * ```
+     **/
+    static get<TError extends keyof typeof errorMessages>(code: TError, ...args: Parameters<typeof errorMessages[TError]>): SchemaError;
+}
+
+export { SchemaError, createStagedArgs };
+export type { OptionSchema, ParseError, ParsedArgs, ParsedArgsFinal, Result, StagedArgs, SuggestFunc, Values };

package/dist/index.mjs

@@ -0,0 +1,388 @@
+import { parseArgs } from 'node:util';
+
+/**
+ * Имя текущего пакета.
+ *
+ * @since 0.4.0
+ *
+ **/
+const THIS_PACKAGE_NAME = '@mirta/staged-args';
+
+/**
+ * Шаблоны сообщений об ошибках в схеме.
+ *
+ * Каждая функция принимает параметры, специфичные для типа ошибки.
+ *
+ * @since 0.4.0
+ *
+ **/
+const errorMessages = {
+    /**
+     * Вызывается при попытке использовать уже занятое имя опции.
+     *
+     * @param name - Имя, которое пытается занять.
+     * @param knownName - Имя, которое уже занято.
+     *
+     **/
+    'duplicateName': (name, knownName) => `Option name "${name}" is already used for "${knownName}"`,
+    /**
+     * Вызывается, если у опции, требующей значение, оно отсутствует.
+     *
+     * @param name - Имя опции без значения.
+     *
+     **/
+    'missingValue': (name) => `Missing value for option "${name}"`,
+};
+/**
+ * Ошибки этапа разработки, связанные с валидацией схемы.
+ *
+ * @since 0.4.0
+ *
+ **/
+class SchemaError extends Error {
+    /**
+     * Код ошибки — идентификатор типа проблемы.
+     *
+     * Используется для точной идентификации причины.
+     */
+    code;
+    /**
+     * Создаёт экземпляр ошибки схемы.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для программной обработки.
+     *
+     **/
+    constructor(message, code) {
+        super(`[${THIS_PACKAGE_NAME}] ${message}`);
+        Object.setPrototypeOf(this, SchemaError.prototype);
+        this.name = 'SchemaError';
+        this.code = code;
+        Error.captureStackTrace(this, SchemaError);
+    }
+    /**
+     * Фабричный метод для создания типизированных ошибок схемы.
+     *
+     * @param code - Код ошибки (ключ из `errorMessages`).
+     * @param args - Аргументы, зависящие от типа ошибки.
+     * @returns Экземпляр `SchemaError` с готовым сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = SchemaError.get('duplicateName', 'config', 'source');
+     * // [package] Option name "config" is already used for "source"
+     * ```
+     **/
+    static get(code, ...args) {
+        const messageFn = errorMessages[code];
+        const message = messageFn(...args);
+        return new SchemaError(message, code);
+    }
+}
+
+/**
+ * Утилита для создания значений типа {@link Result}.
+ *
+ * Содержит статические методы для создания успешных и неудачных результатов.
+ *
+ * @since 0.4.0
+ *
+ **/
+const ResultHandler = {
+    /**
+     * Создаёт успешный результат, содержащий данные.
+     *
+     * @param data - Данные, которые будут включены в результат.
+     * @returns Объект результата с `hasErrors: false` и указанными данными.
+     *
+     * @template TData - Тип передаваемых данных.
+     *
+     * @example
+     * ```ts
+     * const result = ResultHandler.ok({ name: 'Alice', age: 30 });
+     * // { hasErrors: false, data: { name: 'Alice', age: 30 } }
+     * ```
+     **/
+    ok: (data) => ({
+        hasErrors: false,
+        data,
+    }),
+    /**
+     * Создаёт неудачный результат, содержащий список ошибок.
+     *
+     * Если передан пустой массив ошибок, выбрасывается исключение,
+     * так как неудачный результат должен содержать хотя бы одну ошибку.
+     *
+     * @param errors - Массив объектов ошибок, описывающих проблемы ввода.
+     * @returns Объект результата с `hasErrors: true` и указанным списком ошибок.
+     *
+     * @template TError - Тип объекта ошибки (например, строка или объект с типом и деталями).
+     *
+     * @throws {Error} Если передан пустой массив ошибок.
+     *
+     * @example
+     * ```ts
+     * const errors = [{ type: 'unknown-option', option: '--confog' }];
+     * const result = ResultHandler.failed(errors);
+     * // { hasErrors: true, errors: [...] }
+     * ```
+     **/
+    failed: (errors) => {
+        if (errors.length === 0)
+            throw new Error('Errors array cannot be empty');
+        return {
+            hasErrors: true,
+            errors,
+        };
+    },
+};
+
+/**
+ * Расширяет схему, добавляя ссылки на исходный ключ и проверяя дубликаты.
+ *
+ * @param schema - Исходная схема опций.
+ * @returns Расширенная схема, где каждая опция содержит свой `key` и доступна по короткому имени.
+ * @throws Ошибка при обнаружении дубликатов имён или алиасов.
+ *
+ * @since 0.4.0
+ *
+ **/
+function expandSchema(schema) {
+    const result = {};
+    for (const key of Object.keys(schema)) {
+        // Может задвоиться через short, когда длина 1 символ
+        if (key in result)
+            throw SchemaError.get('duplicateName', key, result[key].key);
+        const option = { ...schema[key], key };
+        result[key] = option;
+        if (option.short) {
+            // Может повториться в разных опциях
+            if (option.short in result)
+                throw SchemaError.get('duplicateName', option.short, result[option.short].key);
+            result[option.short] = option;
+        }
+    }
+    return result;
+}
+/**
+ * Сопоставляет токены с опциями по схеме и извлекает значения.
+ *
+ * @param schema - Схема опций.
+ * @param tokens - Разобранные токены.
+ * @param consumedIndices - Индексы токенов, уже обработанных на предыдущих стадиях.
+ * @returns Объект с значениями опций, позиционными аргументами и обновлённым списком потреблённых индексов.
+ * @throws Ошибка, если строковой опции не задано значение и нет значения по умолчанию.
+ *
+ * @since 0.4.0
+ *
+ **/
+function mapToSchema(schema, tokens, consumedIndices = []) {
+    const values = {};
+    const positionals = [];
+    const errors = [];
+    const expandedSchema = expandSchema(schema);
+    const localConsumedIndices = new Set(consumedIndices);
+    const foundKeys = new Set();
+    let nextIndex = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        nextIndex = i + 1;
+        if (token.kind === 'positional') {
+            if (localConsumedIndices.has(i))
+                continue;
+            positionals.push(token.value);
+        }
+        if (token.kind !== 'option' || !token.name || !(token.name in expandedSchema))
+            continue;
+        const option = expandedSchema[token.name];
+        foundKeys.add(option.key);
+        if (option.type === 'boolean') {
+            values[option.key] = token.value !== 'false';
+        }
+        else {
+            let value;
+            if (token.value !== undefined) {
+                value = token.value;
+            }
+            else if (nextIndex < tokens.length) {
+                const nextToken = tokens[nextIndex];
+                if (nextToken.kind === 'positional') {
+                    value = nextToken.value;
+                    localConsumedIndices.add(nextIndex);
+                }
+            }
+            if (value !== undefined)
+                values[option.key] = value;
+        }
+    }
+    for (const key of Object.keys(schema)) {
+        // Пропускаем явно установленные значения.
+        if (key in values)
+            continue;
+        // Строковые опции можно указывать только вместе со значениями.
+        if (foundKeys.has(key) && schema[key].type === 'string') {
+            errors.push({ type: 'missing-value', option: key });
+            continue;
+        }
+        const defaultValue = schema[key].default;
+        // Для отсутствующих ключей применяем значения по умолчанию.
+        if (defaultValue !== undefined)
+            values[key] = defaultValue;
+    }
+    return errors.length > 0
+        ? ResultHandler.failed(errors)
+        : ResultHandler.ok({
+            values,
+            positionals,
+            consumedIndices: [...localConsumedIndices],
+        });
+}
+
+/**
+ * Проверяет, что все опции в токенах известны. Если нет — формирует набор ошибок с подсказками.
+ *
+ * @param tokens - Список токенов.
+ * @param knownArgs - Список известных имён опций и их коротких алиасов.
+ * @returns Набор ошибок или `undefined`, если ошибок нет.
+ *
+ * @since 0.4.0
+ *
+ **/
+function restrictUnknownOptions(tokens, knownArgs, suggest) {
+    // Находим незадействованные опции.
+    const unknownTokens = tokens.filter((token) => token.kind === 'option'
+        && !knownArgs.includes(token.name));
+    if (unknownTokens.length === 0)
+        return;
+    const errors = unknownTokens.map((token) => {
+        const name = token.name;
+        const error = {
+            type: 'unknown-option',
+            option: token.rawName,
+            suggestion: suggest && name.length > 1
+                ? suggest(name, knownArgs)
+                : undefined,
+        };
+        return error;
+    });
+    return errors;
+}
+/**
+ * Дополняет список известных аргументов именами из новой схемы.
+ *
+ * @param knownArgs - Текущий список известных имён.
+ * @param schema - Новая схема опций.
+ * @returns Обновлённый список имён, включая длинные и короткие имена из схемы.
+ *
+ * @since 0.4.0
+ *
+ **/
+function extendKnownArgs(knownArgs, schema) {
+    const knownSet = new Set(knownArgs ?? []);
+    for (const key of Object.keys(schema)) {
+        knownSet.add(key);
+        const short = schema[key].short;
+        if (short)
+            knownSet.add(short);
+    }
+    return [...knownSet];
+}
+/**
+ * Внутренняя функция для поэтапного разбора аргументов.
+ *
+ * @param args - Аргументы командной строки.
+ * @param schema - Схема опций для текущего этапа.
+ * @param context - Контекст предыдущих этапов (схема, известные аргументы, suggest и т.д.).
+ * @param options - Дополнительные настройки.
+ * @returns Результат разбора: данные или ошибки.
+ *
+ * @since 0.4.0
+ *
+ * @internal
+ *
+ **/
+function parseInternal(args, schema, context, options = {}) {
+    // 1. Объединяем схемы для parseArgs
+    const stagedSchema = { ...context.schema, ...schema };
+    // 2. Токенизируем с полным контекстом
+    const { tokens } = parseArgs({
+        args,
+        options: stagedSchema,
+        tokens: true,
+        strict: false,
+        allowPositionals: true,
+    });
+    const knownArgs = extendKnownArgs(context.knownArgs, schema);
+    // Проверяем неизвестные опции, если запрещены
+    if (options.noUnknown) {
+        const errors = restrictUnknownOptions(tokens, knownArgs, context.suggest);
+        if (errors)
+            return ResultHandler.failed(errors);
+    }
+    const mapResult = mapToSchema(schema, tokens, context.consumedIndices);
+    if (mapResult.hasErrors)
+        return mapResult;
+    const { values, positionals, consumedIndices: localConsumedIndices, } = mapResult.data;
+    let stagedArgs;
+    return ResultHandler.ok({
+        values: values,
+        positionals,
+        get stagedArgs() {
+            return stagedArgs ??= createStage(args, {
+                suggest: context.suggest,
+                schema: stagedSchema,
+                knownArgs: knownArgs,
+                consumedIndices: localConsumedIndices,
+            });
+        },
+    });
+}
+/**
+ * Создаёт экземпляр `StagedArgs` с заданными параметрами.
+ *
+ * @param args - Массив аргументов командной строки.
+ * @param mergedSchema - Объединённая схема опций с предыдущих стадий.
+ * @param knownArgs - Список уже известных имён опций.
+ * @param consumedIndices - Индексы токенов, уже обработанных ранее.
+ * @returns Объект `StagedArgs` с методами `parse` и `parseFinal`.
+ *
+ * @since 0.4.0
+ *
+ **/
+function createStage(args, context = {}) {
+    const parse = (schema) => {
+        return parseInternal(args, schema, context);
+    };
+    const parseFinal = (schema) => {
+        const result = parseInternal(args, schema, context, {
+            noUnknown: true,
+        });
+        if (result.hasErrors)
+            return result;
+        return ResultHandler.ok({
+            values: result.data.values,
+            positionals: result.data.positionals,
+        });
+    };
+    return { parse, parseFinal };
+}
+/**
+ * Создаёт начальный экземпляр `StagedArgs` для разбора аргументов командной строки.
+ *
+ * @param args - Массив строк, представляющих аргументы (например, `process.argv.slice(2)`).
+ * @returns Объект для поэтапного разбора аргументов.
+ *
+ * @example
+ * const staged = createStagedArgs(process.argv.slice(2));
+ * const { values, stagedArgs } = staged.parse(globalSchema);
+ * const { values: cmdValues } = stagedArgs.parseFinal(commandSchema);
+ *
+ * @since 0.4.0
+ *
+ **/
+function createStagedArgs(args, options = {}) {
+    const { suggest } = options;
+    return createStage(args, { suggest });
+}
+
+export { SchemaError, createStagedArgs };

package/package.json

@@ -1,10 +1,52 @@
 {
   "name": "@mirta/staged-args",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @mirta/staged-args",
+  "description": "⚡ Staged CLI arguments parser with TypeScript support",
+  "version": "0.4.0",
+  "license": "Unlicense",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "cli",
+    "arguments",
+    "parser",
+    "staged",
+    "command-line",
+    "typescript",
+    "mirta"
+  ],
+  "type": "module",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "types": "./dist/index.d.mts",
+  "imports": {
+    "#src/*": "./src/*.js"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      }
+    }
+  },
+  "homepage": "https://github.com/wb-mirta/core/tree/latest/packages/mirta-staged-args#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wb-mirta/core.git",
+    "directory": "packages/mirta-staged-args"
+  },
+  "bugs": {
+    "url": "https://github.com/wb-mirta/core/issues"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "https://boosty.to/wihome/donate"
+  },
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "scripts": {
+    "build:mono": "rollup -c node:@mirta/rollup/config-package"
+  }
+}