icore 1.0.14 → 1.0.16

package/examples/cli-argument-syntax.md

@@ -0,0 +1,218 @@
+# CLI Argument Syntax
+
+icore supports a practical GNU-style option syntax. The parser receives
+`process.argv.slice(2)`, splits command path tokens from option tokens, and then
+uses the command schema to validate option values.
+
+Supported forms:
+
+- long options: `--name value`, `--name=value`;
+- boolean flags: `--flag`, `--no-flag`;
+- short aliases declared in the schema: `-f`, `-n value`;
+- option terminator: `--`.
+
+The supported set is intentionally small. It covers common terminal usage while
+avoiding shell-specific surprises and hidden precedence rules.
+
+## Long options
+
+Use a separate value:
+
+```bash
+node dist/cli.js users get --name Alice
+```
+
+The raw option value is:
+
+```json
+{
+  "name": "Alice"
+}
+```
+
+Use an equals sign when it reads better:
+
+```bash
+node dist/cli.js users get --name=Alice
+```
+
+The handler receives the same parsed value.
+
+Supporting both forms keeps the CLI comfortable for humans and scripts. Both
+forms map to the same option value, so command handlers do not need to care
+which spelling the user chose.
+
+Schema-known string and number options can consume values that start with `-`:
+
+```bash
+node dist/cli.js search --label -draft --limit -1
+```
+
+That works when the command schema declares `label` as `type: 'string'` and
+`limit` as `type: 'number'`.
+
+This is one reason argv parsing accepts a schema hint. Without it, values like
+`-draft` and `-1` are hard to distinguish from option-looking tokens.
+
+## Boolean flags
+
+Use the option name to set a boolean to `true`:
+
+```bash
+node dist/cli.js reports list --archived
+```
+
+Use `--no-<name>` to set a known boolean option to `false`:
+
+```bash
+node dist/cli.js reports list --no-archived
+```
+
+Do not pass explicit boolean values:
+
+```bash
+node dist/cli.js reports list --archived=true
+node dist/cli.js reports list --archived=false
+```
+
+Those forms are rejected. A boolean option is either present as a flag or, when
+the schema allows it, negated with `--no-<name>`.
+
+Rejecting explicit boolean values is stricter, but it avoids a long list of
+quasi-boolean strings such as `yes`, `no`, `1`, and `0`.
+
+This command:
+
+```bash
+node dist/cli.js reports list --archived false
+```
+
+sets `archived` to `true` and leaves `false` as a positional token. It does not
+mean `archived: false`.
+
+## Short aliases
+
+Short aliases work only when the option schema declares them.
+
+For a boolean alias:
+
+```ts
+const options = {
+  verbose: {
+    type: 'boolean',
+    alias: 'v'
+  }
+} as const;
+```
+
+The user can type:
+
+```bash
+node dist/cli.js users get -v
+```
+
+The handler receives:
+
+```json
+{
+  "verbose": true
+}
+```
+
+For a string or number alias, put the value in the next token:
+
+```ts
+const options = {
+  name: {
+    type: 'string',
+    alias: 'n'
+  },
+  limit: {
+    type: 'number',
+    alias: 'l'
+  }
+} as const;
+```
+
+The user can type:
+
+```bash
+node dist/cli.js users get -n Alice -l 10
+```
+
+The handler receives:
+
+```json
+{
+  "name": "Alice",
+  "limit": 10
+}
+```
+
+Attached short values are not supported:
+
+```bash
+node dist/cli.js users get -nAlice
+```
+
+Grouped short booleans are not supported:
+
+```bash
+node dist/cli.js users get -abc
+```
+
+Use one declared alias per token.
+
+This limitation is deliberate. Compact short syntax can be convenient, but it
+creates more parser edge cases and makes command examples harder to read. icore
+chooses clarity over maximum GNU compatibility here.
+
+## Option terminator
+
+Use `--` to stop option parsing. The terminator itself is removed; every token
+after it becomes positional, even when it starts with `-`.
+
+This is useful when the application needs to receive raw user text, patterns, or
+values that look like options.
+
+```bash
+node dist/cli.js search -- --name Alice -v
+```
+
+The parser treats `--name`, `Alice`, and `-v` as positional tokens after the
+command path.
+
+## Duplicate options
+
+Do not pass the same option twice:
+
+```bash
+node dist/cli.js users get --format json --format table
+```
+
+Do not pass the same option through both its long name and its short alias:
+
+```bash
+node dist/cli.js users get --verbose -v
+```
+
+Both forms are rejected as duplicate arguments.
+
+Rejecting duplicates is usually safer than choosing the first or last value. It
+forces the caller to send one clear value and keeps command behavior
+deterministic.
+
+## Unknown options
+
+Unknown long options are rejected when command options are validated:
+
+```bash
+node dist/cli.js users get --unknown value
+```
+
+Unknown short tokens are not expanded automatically. If the active command does
+not allow them as positionals, command validation rejects them as unexpected
+positional arguments.
+
+For application-level patterns built from this syntax, see
+[practical-cli-patterns.md](practical-cli-patterns.md).

package/examples/command-resolution.md

@@ -0,0 +1,174 @@
+# Command Resolution
+
+Use these primitives when the application needs command selection without
+immediately running a command. This is common in help systems, command previews,
+audit logs, and custom routers.
+
+For regular terminal applications, prefer `createTerminalApp()` or
+`createCommand().registry(...)`. The lower-level resolution API is more verbose,
+but it makes command selection explicit and testable.
+
+## Define Commands Without The Facade
+
+`defineCommand(...)` is the low-level form behind `command.define(...)`.
+
+```ts
+import {
+  defineCommand,
+  defineCommandRegistry,
+  type CommandName
+} from 'icore';
+
+const listJobsCommand = defineCommand({
+  path: ['jobs', 'list'],
+  options: {
+    status: {
+      type: 'string',
+      choices: ['queued', 'running', 'done', 'failed']
+    }
+  } as const,
+  handle({ options }) {
+    return `status=${options.status ?? 'any'}\n`;
+  }
+});
+
+const runJobCommand = defineCommand({
+  path: ['jobs', 'run'],
+  options: {
+    'job-id': {
+      type: 'string',
+      required: true
+    }
+  } as const,
+  handle({ options }) {
+    return `run ${options['job-id']}\n`;
+  }
+});
+
+const registry = defineCommandRegistry([
+  listJobsCommand,
+  runJobCommand
+] as const);
+
+type PublicCommandName = CommandName<typeof runJobCommand>;
+```
+
+Use this form when the registry itself is the important object. The tradeoff is
+that you do not get the convenient `commands.prepare(...)` and
+`commands.run(...)` methods until you call `createCommands(...)`.
+
+The inferred `PublicCommandName` is:
+
+```ts
+type PublicCommandName = 'jobs run';
+```
+
+## Create A Commands Object Directly
+
+`createCommands(...)` is the direct alternative to
+`createCommand().registry(...)`.
+
+```ts
+import { createCommands } from 'icore';
+
+const commands = createCommands([
+  listJobsCommand,
+  runJobCommand
+] as const);
+
+commands.names;
+commands.registry;
+```
+
+This is useful when command definitions are already created elsewhere and the
+application does not need the `createCommand()` object. It is not better for
+normal code; it is just a more direct construction form.
+
+## Resolve From Positionals
+
+Use `commands.resolve(...)` when arguments are already split into command path
+tokens.
+
+```ts
+const resolved = commands.resolve([
+  'jobs',
+  'run'
+]);
+
+resolved.name;
+resolved.positionals;
+```
+
+The resolved command name is:
+
+```text
+jobs run
+```
+
+No options are parsed in this form. That is intentional: it is useful for help
+renderers that already have command tokens, but it is not enough to validate a
+terminal call.
+
+## Resolve From Raw Arguments
+
+Use `commands.resolveFromArgs(...)` or standalone
+`resolveCommandFromArgs(...)` when raw terminal arguments may contain options.
+
+```ts
+import { resolveCommandFromArgs } from 'icore';
+
+const resolved = commands.resolveFromArgs([
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+]);
+
+const sameResolved = resolveCommandFromArgs(commands.registry, [
+  'jobs',
+  'run',
+  '--job-id',
+  'job-42'
+]);
+```
+
+This form asks each command schema how to split options from command tokens. It
+is a better fit for real argv input than `resolve(...)`.
+
+## Use The Standalone Resolver
+
+`resolveCommand(...)` is the primitive behind `commands.resolve(...)`.
+
+```ts
+import { resolveCommand } from 'icore';
+
+const resolved = resolveCommand(registry, [
+  'jobs',
+  'list'
+]);
+```
+
+Prefer `commands.resolve(...)` when you already have a `commands` object. Use
+the standalone function when a custom registry object is passed around.
+
+## Guard Command Names
+
+`isCommandName(...)` narrows unknown input to the command names registered in a
+registry.
+
+```ts
+import { isCommandName } from 'icore';
+
+function renderHelpPage(name: unknown): string {
+  if (!isCommandName(commands.registry, name)) {
+    return renderTopLevelHelp();
+  }
+
+  return renderCommandHelp(name);
+}
+```
+
+This is safer than comparing against string literals in several places. The
+cost is that the guard only checks registered command names; it does not
+validate options or execute anything.
+

package/examples/custom-command-flow.md

@@ -0,0 +1,109 @@
+# Custom Command Flow
+
+Use this shape when the application wants command mechanics without the terminal
+application boundary. The application prepares a command, creates its runtime
+context, and then runs the prepared command explicitly.
+
+This is useful when command parsing happens before runtime dependencies are
+available. For example, the application can validate arguments, select a
+command, and only then open a database connection or create an API client. The
+tradeoff is that the application must own output rendering and error handling
+itself.
+
+Put the command registry close to the code that owns the command contract:
+
+```ts
+import {
+  createCommand,
+  type PreparedCommand
+} from 'icore';
+
+type AppContext = {
+  greeting: string;
+};
+
+const command = createCommand();
+
+const greetCommand = command.define({
+  path: ['greet'],
+  options: {
+    name: {
+      type: 'string',
+      required: true
+    }
+  } as const,
+  prepare({ options }) {
+    return {
+      normalizedName: options.name.trim()
+    };
+  },
+  handle({ payload, context }: {
+    payload: { normalizedName: string };
+    context: AppContext;
+  }) {
+    return `${context.greeting}, ${payload.normalizedName}!\n`;
+  }
+});
+
+const commands = command.registry([
+  greetCommand
+] as const);
+```
+
+The `prepare` hook is intentionally small. It normalizes command input before
+runtime context exists, but it should not perform application work. Keeping that
+split makes failed argument parsing cheap and deterministic.
+
+When application startup needs a separate preparation step, prepare first and
+run later:
+
+```ts
+async function runTwoPhase(args: readonly string[]): Promise<string> {
+  const prepared: PreparedCommand<typeof greetCommand> = await commands.prepare(args, {
+    strict: true
+  });
+
+  return commands.run(prepared, {
+    greeting: 'Hello'
+  });
+}
+```
+
+The two-phase form is the safest choice when application context is expensive
+or has side effects. If preparation fails, the runtime context never needs to be
+created.
+
+When the application does not need that split, run from raw terminal arguments:
+
+```ts
+async function runFromArgs(args: readonly string[]): Promise<string> {
+  return commands.runFromArgs(args, {
+    greeting: 'Hello'
+  }, {
+    strict: true
+  });
+}
+```
+
+`runFromArgs(...)` is more compact and works well for simple applications. It is
+less flexible because parsing, preparation, and execution happen as one step.
+
+Pass the same arguments a user would type in the terminal:
+
+```ts
+const args = [
+  'greet',
+  '--name',
+  'Alice'
+];
+
+process.stdout.write(await runTwoPhase(args));
+process.stdout.write(await runFromArgs(args));
+```
+
+The terminal prints one line for each call:
+
+```text
+Hello, Alice!
+Hello, Alice!
+```

package/examples/option-schemas.md

@@ -0,0 +1,206 @@
+# Option Schemas
+
+Use option schemas to describe the public arguments of a command. The schema
+defines what the user can type in the terminal and what typed values the command
+handler receives.
+
+The schema is deliberately small: it covers primitive CLI types and validation
+rules, while application-specific parsing stays in the application. That keeps
+icore reusable and prevents domain rules from leaking into command mechanics.
+
+## Start with one command
+
+Put a command close to the application code that owns the command behavior:
+
+This is preferable to a central "all options" file for most commands. The
+person reading the command can see the public CLI contract and the handler
+together.
+
+```ts
+import {
+  createCommand,
+  type InferOptions
+} from 'icore';
+
+const command = createCommand();
+
+const reportOptions = {
+  project: {
+    type: 'string',
+    required: true,
+    alias: 'p'
+  },
+  format: {
+    type: 'string',
+    choices: ['table', 'json', 'csv'],
+    default: 'table'
+  },
+  archived: {
+    type: 'boolean',
+    default: false
+  },
+  limit: {
+    type: 'number',
+    integer: true,
+    min: 1,
+    max: 100,
+    default: 20,
+    alias: 'l'
+  }
+} as const;
+
+type ReportOptions = InferOptions<typeof reportOptions>;
+
+const reportCommand = command.define({
+  path: ['reports', 'list'],
+  options: reportOptions,
+  handle({ options }: {
+    options: ReportOptions;
+  }) {
+    return JSON.stringify(options, null, 2) + '\n';
+  }
+});
+```
+
+The command now accepts one required string option, one string option with
+choices, one boolean option, and one bounded number option.
+
+The `as const` is important because it preserves literal choices for TypeScript
+inference. Without it, the handler would still work at runtime, but the inferred
+type would be wider and less useful.
+
+## Run it from the terminal
+
+The user can pass long options:
+
+```bash
+node dist/cli.js reports list --project alpha --format json --archived --limit 5
+```
+
+The handler receives:
+
+```json
+{
+  "project": "alpha",
+  "format": "json",
+  "archived": true,
+  "limit": 5
+}
+```
+
+The user can pass declared short aliases:
+
+```bash
+node dist/cli.js reports list -p alpha -l 5
+```
+
+The handler receives defaults for options that were not typed:
+
+```json
+{
+  "project": "alpha",
+  "format": "table",
+  "archived": false,
+  "limit": 5
+}
+```
+
+Defaults are useful for stable command behavior, but they are also part of the
+public contract. Prefer defaults only when the implicit value is obvious and
+safe.
+
+## Use boolean negation
+
+Boolean options can be turned off with `--no-<name>` when the option is known by
+the schema:
+
+```bash
+node dist/cli.js reports list --project alpha --archived
+node dist/cli.js reports list --project alpha --no-archived
+```
+
+The first command gives the handler `archived: true`; the second gives it
+`archived: false`.
+
+This form is more explicit than accepting `--archived=false`. It also avoids
+ambiguous text values such as `0`, `no`, or `off`.
+
+Do not pass explicit boolean values:
+
+```bash
+node dist/cli.js reports list --project alpha --archived=true
+node dist/cli.js reports list --project alpha --archived=false
+```
+
+Both forms are rejected. Boolean options use flag syntax, not `true` / `false`
+values.
+
+## Restrict a boolean to flag-only syntax
+
+Use `syntax: 'flag'` for options that should only mean "enable this behavior":
+
+This is a stricter contract. It is a good fit for options like `--dry-run`,
+where the absence of the flag already has a clear meaning.
+
+```ts
+const schema = {
+  'dry-run': {
+    type: 'boolean',
+    default: false,
+    syntax: 'flag'
+  }
+} as const;
+```
+
+The terminal accepts:
+
+```bash
+node dist/cli.js reports list --dry-run
+```
+
+The terminal rejects:
+
+```bash
+node dist/cli.js reports list --no-dry-run
+node dist/cli.js reports list --dry-run=false
+```
+
+## Reuse shared schema pieces
+
+When several commands reuse the same public options, keep small schema pieces
+and merge them at the command boundary:
+
+This reduces duplication without hiding command-specific intent. It becomes a
+bad abstraction when the reusable schema needs many exceptions for individual
+commands.
+
+```ts
+import { mergeOptionsSchema } from 'icore';
+
+const pagingOptions = {
+  limit: {
+    type: 'number',
+    integer: true,
+    min: 1,
+    max: 100,
+    default: 20
+  }
+} as const;
+
+const outputOptions = {
+  format: {
+    type: 'string',
+    choices: ['table', 'json', 'csv'],
+    default: 'table'
+  }
+} as const;
+
+const options = mergeOptionsSchema(pagingOptions, outputOptions);
+```
+
+Later schemas override earlier schemas when an option name is repeated. Keep
+that behavior intentional and visible near the command definition.
+
+For larger application patterns that combine shared schemas, global shortcuts,
+and compatibility options, see
+[practical-cli-patterns.md](practical-cli-patterns.md).