icore 1.0.2 → 1.0.4

package/docs/api.md

@@ -0,0 +1,466 @@
+# API Reference
+
+## Option Schemas
+
+Options are described as plain objects.
+
+Option names are exact. `icore` does not normalize camelCase to kebab-case or
+kebab-case to camelCase. Use quoted object keys when your public CLI option
+contains `-`.
+
+### String Options
+
+```ts
+const schema = {
+  token: {
+    type: 'string',
+    required: true
+  },
+  format: {
+    type: 'string',
+    choices: ['json', 'table'],
+    default: 'table'
+  }
+} as const;
+```
+
+String options reject missing required values, blank strings, boolean flag form,
+and values outside `choices`.
+
+### Boolean Options
+
+```ts
+const schema = {
+  insecure: {
+    type: 'boolean'
+  }
+} as const;
+```
+
+Boolean options accept flag form only:
+
+```sh
+--insecure
+```
+
+Explicit values are rejected:
+
+```sh
+--insecure true
+--insecure=true
+```
+
+### Number Options
+
+```ts
+const schema = {
+  limit: {
+    type: 'number',
+    integer: true,
+    min: 1,
+    max: 1000,
+    default: 100
+  }
+} as const;
+```
+
+Number options parse decimal numeric values and can validate integer and range
+constraints. Defaults are validated with the same rules as user-provided values.
+
+## `parseArgv(args, schema?)`
+
+Parses raw CLI arguments into positionals and raw option values.
+
+```ts
+import { parseArgv } from 'icore';
+
+const argv = parseArgv([
+  'users',
+  'get-accounts',
+  '--format=json',
+  '--insecure'
+]);
+```
+
+Result:
+
+```ts
+{
+  positionals: ['users', 'get-accounts'],
+  options: {
+    format: 'json',
+    insecure: true
+  }
+}
+```
+
+When an option schema is provided, boolean options are parsed as flag-only
+options without consuming the following positional argument:
+
+```ts
+const argv = parseArgv([
+  'users',
+  'get-accounts',
+  '--insecure',
+  'extra'
+], {
+  insecure: {
+    type: 'boolean'
+  }
+});
+```
+
+Result:
+
+```ts
+{
+  positionals: ['users', 'get-accounts', 'extra'],
+  options: {
+    insecure: true
+  }
+}
+```
+
+## `parseOptions(schema, values)`
+
+Validates raw option values using an option schema and returns typed options.
+
+```ts
+import { parseOptions } from 'icore';
+
+const options = parseOptions({
+  format: {
+    type: 'string',
+    choices: ['json', 'table'],
+    default: 'table'
+  },
+  depth: {
+    type: 'number',
+    integer: true,
+    min: 1,
+    required: true
+  }
+} as const, {
+  depth: '10'
+});
+```
+
+Result:
+
+```ts
+{
+  format: 'table',
+  depth: 10
+}
+```
+
+## `parseOptionsDetailed(schema, values)`
+
+Validates raw option values and returns parsed options together with
+user-provided metadata.
+
+```ts
+import { parseOptionsDetailed } from 'icore';
+
+const result = parseOptionsDetailed({
+  token: {
+    type: 'string',
+    required: true
+  },
+  format: {
+    type: 'string',
+    choices: ['json', 'table'],
+    default: 'table'
+  }
+} as const, {
+  token: 'secret'
+});
+```
+
+Result:
+
+```ts
+{
+  options: {
+    token: 'secret',
+    format: 'table'
+  },
+  provided: {
+    token: true,
+    format: false
+  }
+}
+```
+
+`provided` is useful when a default value and an omitted option have different
+application-level meaning.
+
+## `defineCommand(command)`
+
+Defines a command while preserving its option schema types.
+
+```ts
+import { defineCommand } from 'icore';
+
+const command = defineCommand({
+  path: ['marketdata', 'get-order-book'],
+  options: {
+    'instrument-id': {
+      type: 'string',
+      required: true
+    },
+    depth: {
+      type: 'number',
+      integer: true,
+      min: 1,
+      required: true
+    },
+    format: {
+      type: 'string',
+      choices: ['json', 'table'],
+      default: 'table'
+    }
+  },
+  async handle({ options, context }) {
+    const response = await context.sdk.marketdata.getOrderBook({
+      instrumentId: options['instrument-id'],
+      depth: options.depth
+    });
+
+    return context.formatOrderBook(response, options.format);
+  }
+});
+```
+
+## `defineCommandRegistry(commands)`
+
+Defines a command registry while preserving literal command path types.
+
+```ts
+import { defineCommandRegistry } from 'icore';
+
+const registry = defineCommandRegistry([
+  usersGetAccountsCommand,
+  marketdataGetOrderBookCommand
+] as const);
+```
+
+The registry exposes ordered commands and derived command names:
+
+```ts
+registry.commandNames;
+```
+
+Result:
+
+```ts
+[
+  'users get-accounts',
+  'marketdata get-order-book'
+]
+```
+
+Duplicate command paths are rejected.
+
+## `isCommandName(registry, value)`
+
+Checks whether an unknown value is a command name registered in the registry.
+
+```ts
+if (isCommandName(registry, value)) {
+  // value is narrowed to the registry command name union.
+}
+```
+
+## `resolveCommand(registry, positionals)`
+
+Resolves a command from already parsed positional arguments.
+
+```ts
+import { resolveCommand } from 'icore';
+
+const resolved = resolveCommand(registry, [
+  'users',
+  'get-accounts',
+  'extra'
+]);
+```
+
+Result:
+
+```ts
+{
+  name: 'users get-accounts',
+  path: ['users', 'get-accounts'],
+  command: usersGetAccountsCommand,
+  positionals: ['extra']
+}
+```
+
+When several command paths match, the most specific command wins. For example,
+`users get-accounts` is preferred over `users`.
+
+## `resolveCommandFromArgs(registry, args)`
+
+Resolves a command from raw CLI arguments. Each candidate command is parsed with
+its own option schema, so boolean flags do not accidentally consume command path
+segments.
+
+```ts
+const resolved = resolveCommandFromArgs(registry, [
+  '--verbose',
+  'users',
+  'get-accounts'
+]);
+```
+
+## `runCommandFromRegistry(registry, args, context)`
+
+Resolves a command from a registry and runs its handler.
+
+```ts
+const output = await runCommandFromRegistry(
+  registry,
+  ['users', 'get-accounts', '--format', 'json'],
+  context
+);
+```
+
+This is registry-level mechanics only. Application-specific setup, API request
+building, and output formatting still belong outside `icore`.
+
+## `mergeOptionsSchema(...schemas)`
+
+Merges multiple option schemas while preserving literal option definition types.
+Later schemas override earlier schemas with the same option name.
+
+```ts
+import { mergeOptionsSchema } from 'icore';
+
+const sdkOptions = {
+  token: {
+    type: 'string',
+    required: true
+  }
+} as const;
+
+const formatOptions = {
+  format: {
+    type: 'string',
+    choices: ['json', 'table'],
+    default: 'table'
+  }
+} as const;
+
+const options = mergeOptionsSchema(sdkOptions, formatOptions);
+```
+
+## `runCommand(command, args, context)`
+
+Parses arguments, validates options, checks command positionals, and runs the
+handler.
+
+```ts
+const output = await runCommand(
+  command,
+  [
+    'marketdata',
+    'get-order-book',
+    '--instrument-id',
+    'instrument-id',
+    '--depth',
+    '10'
+  ],
+  context
+);
+```
+
+By default, extra positionals are rejected. A command can opt in to extra
+positionals with `allowExtraPositionals: true`.
+
+## Type Inference
+
+Use `InferOptions` when you need the parsed option type explicitly.
+
+```ts
+import type { InferOptions } from 'icore';
+
+const schema = {
+  format: {
+    type: 'string',
+    choices: ['json', 'table'],
+    default: 'table'
+  },
+  dryRun: {
+    type: 'boolean'
+  }
+} as const;
+
+type Options = InferOptions<typeof schema>;
+```
+
+`Options` is equivalent to:
+
+```ts
+type Options = {
+  format: 'json' | 'table';
+  dryRun: boolean | undefined;
+};
+```
+
+Required options and options with defaults are always present. Optional options
+without defaults are returned as `T | undefined`.
+
+Use `InferProvidedOptions` when you need the option presence type explicitly.
+
+```ts
+import type { InferProvidedOptions } from 'icore';
+
+type Provided = InferProvidedOptions<typeof schema>;
+```
+
+`Provided` maps every schema option to `boolean`. `true` means the user
+specified that option explicitly; defaults keep the flag `false`.
+
+Use `MergeOptionsSchemas` when you need the merged schema type explicitly.
+
+```ts
+import type { MergeOptionsSchemas } from 'icore';
+
+type Schema = MergeOptionsSchemas<[typeof sdkOptions, typeof formatOptions]>;
+```
+
+Use `CommandName` when you need the inferred command name type explicitly.
+
+```ts
+import type { CommandName } from 'icore';
+
+type Name = CommandName<typeof usersGetAccountsCommand>;
+```
+
+`Name` is equivalent to:
+
+```ts
+type Name = 'users get-accounts';
+```
+
+## Error Messages
+
+`icore` throws regular `Error` objects with predictable user-facing messages.
+Applications should treat these messages as display text, not as a
+machine-readable API.
+
+Examples:
+
+```txt
+Unexpected argument '--unknown'
+Unexpected duplicate argument '--format'
+Unexpected duplicate command 'users get-accounts'
+Unknown command: users get-unknown
+Expected required argument '--token'
+Expected '--format' as one of: json, table
+Expected '--depth' as integer
+Expected '--depth' to be greater than or equal to 1
+```
+
+Applications can catch these errors and decide how to print them.

package/docs/design.md

@@ -0,0 +1,80 @@
+# Design Notes
+
+## Purpose
+
+`icore` is a small CLI mechanics module. It standardizes command definitions,
+argument parsing, primitive option validation, command registry resolution, and
+typed command handler input.
+
+It intentionally stops before application behavior. Your application still
+owns business validation, API request mapping, SDK calls, process lifecycle,
+and output formatting.
+
+## Why icore?
+
+Use `icore` when you need more than raw argument parsing:
+
+- typed command definitions;
+- command registry resolution;
+- required options;
+- string choices;
+- number parsing with integer, minimum, and maximum constraints;
+- option presence metadata;
+- typed command handler input.
+
+Use [`node:util.parseArgs`](https://nodejs.org/api/util.html#utilparseargsconfig)
+directly when you only need low-level argument parsing.
+
+## Non-goals
+
+`icore` stops at CLI mechanics. It does not build API DTOs, call SDKs, format
+output, manage process lifecycle, or validate business rules.
+
+It also does not handle:
+
+- provider-specific request modes;
+- generated contract mapping;
+- mutually exclusive application modes;
+- presentation formatting as JSON, tables, CSV, or another application format;
+- database, HTTP, gRPC, or SDK lifecycle management.
+
+Keep those decisions near the command handler or in your application layer.
+
+## Supported Syntax
+
+| Syntax | Supported | Notes |
+|---|---:|---|
+| `--name value` | yes | string and number options |
+| `--name=value` | yes | string and number options |
+| `--flag` | yes | boolean options |
+| `--flag=true` | no | boolean options are flag-only |
+| `-f` | no | short aliases are not supported |
+| `--no-cache` | no | negative boolean flags are not supported |
+| repeated options | no | duplicates are rejected |
+| multiple values | no | arrays are not supported |
+
+## Design Goals
+
+- describe CLI mechanics declaratively;
+- use literal option types: `type: 'string' | 'boolean' | 'number'`;
+- keep handlers free from repetitive option parsing;
+- keep domain and API semantics outside the framework;
+- provide predictable user-facing errors;
+- avoid runtime dependencies.
+
+## Project Boundary
+
+Good responsibilities for `icore`:
+
+- option schema evaluation;
+- command path checking;
+- common argument errors;
+- typed command handler input.
+
+Responsibilities that should stay outside `icore`:
+
+- business validation;
+- SDK lifecycle management;
+- provider-specific request modes;
+- generated contract mapping;
+- presentation formatting.

package/docs/examples.md

@@ -0,0 +1,100 @@
+# Examples
+
+## Basic Command
+
+```ts
+import { defineCommand, runCommand } from 'icore';
+
+const helloCommand = defineCommand({
+  path: ['hello'],
+  options: {
+    name: {
+      type: 'string',
+      default: 'world'
+    },
+    upper: {
+      type: 'boolean'
+    }
+  },
+  async handle({ options }) {
+    const message = `Hello, ${options.name}!`;
+
+    return options.upper ? message.toUpperCase() : message;
+  }
+});
+
+const output = await runCommand(
+  helloCommand,
+  ['hello', '--name', 'Stanislav', '--upper'],
+  {}
+);
+
+console.log(output);
+```
+
+## Command Registry
+
+```ts
+import {
+  defineCommand,
+  defineCommandRegistry,
+  runCommandFromRegistry
+} from 'icore';
+
+const usersListCommand = defineCommand({
+  path: ['users', 'list'],
+  options: {
+    limit: {
+      type: 'number',
+      integer: true,
+      min: 1,
+      max: 100,
+      default: 20
+    }
+  },
+  async handle({ options }) {
+    return `List ${options.limit} users`;
+  }
+});
+
+const registry = defineCommandRegistry([
+  usersListCommand
+] as const);
+
+const output = await runCommandFromRegistry(
+  registry,
+  ['users', 'list', '--limit', '10'],
+  {}
+);
+```
+
+## Option Presence Metadata
+
+Use `parseOptionsDetailed` when defaults and explicitly provided values have
+different application-level meaning.
+
+```ts
+import { parseOptionsDetailed } from 'icore';
+
+const result = parseOptionsDetailed({
+  format: {
+    type: 'string',
+    choices: ['json', 'table'],
+    default: 'table'
+  }
+} as const, {});
+
+result.options.format;
+result.provided.format;
+```
+
+`result.options.format` is `table`, and `result.provided.format` is `false`.
+
+## CommonJS
+
+```js
+const {
+  defineCommand,
+  runCommand
+} = require('icore');
+```