@clibu/core

Declarative CLI engine core for Clibu. It provides a compact, type-aware schema for defining commands and options, a deterministic two-phase parser, and validation/runtime primitives. The core focuses on a small, stable surface that other packages (facade, help, loader) consume.

Key features

• Declarative command & option DSL (flag, string, number, enumOption).
• Two‑phase parsing: relaxed scan to discover the command path, then strict option parsing for the resolved command (avoids false unknown-option errors).
• Global (root-level) options with optional inheritance; conflicts are detected at CLI creation.
• Validation and coercion for option values (required, min/max, integer, pattern, enum membership).
• Help metadata support (rendering provided by @clibu/help).
• Lightweight logger and an organ (plugin) stub for future extensions.

Basic usage

import { createCLI, flag, number, enumOption, string } from "@clibu/core"

const cli = createCLI({
  name: "riglet",
  version: "0.0.1",
  commands: {
    build: {
      description: "Build project",
      options: {
        threads: number({ min: 1, max: 8, required: true }),
        verbose: flag({ alias: "v" }),
        mode: enumOption({ choices: ["dev", "prod"], required: true }),
        profile: string({ pattern: /^[a-z]+$/ })
      },
      run(ctx) {
        ctx.logger.info("Running build", ctx.options)
      }
    }
  }
})

await cli.run(process.argv.slice(2))

Help output (example)

Root:

riglet v0.0.1
USAGE:
  riglet <command> [options]
COMMANDS:
  build  Build project
(Use <command> --help for option details)

Per‑command:

riglet v0.0.1
COMMAND:
  build Build project
USAGE:
  riglet build [options]
OPTIONS:
  --threads        Thread count [required]
  --verbose (-v)   Verbose output [default: false]
  --mode           Build mode [required choices: dev|prod]
  --profile        Lowercase profile

Surface API

• createCLI(config): create a CLI instance with run() and help().
• buildContext(cfg, argv): build an execution context (resolved command, args, validated options). The context separates globalOptions from commandOptions.
• Option DSL: flag(), string(), number(), enumOption().
• OrganManager and ClibuOrgan: plugin hook stubs for future extension.

Option validation

Validation runs after parsing:

• Number: min, max, integer.
• String: pattern, minLength, maxLength.
• Enum: choices, caseSensitive.
• Flag: boolean; supports --no-<name> for negation.

Parsing overview

1. parseArgv performs a relaxed scan (collecting root/global options and raw tokens) to discover the command path.
2. Resolve the command path via graph traversal until a non‑command token.
3. parseOptions strictly parses options for the resolved command and rejects unknown options.
4. Validation of values and construction of the final CLI context.

Internal layout

src/
  types.ts      // Core types & inference
  schema.ts     // DSL helpers & alias normalization
  graph.ts      // Command tree build & resolve
  parser.ts     // parseArgv + parseOptions
  validate.ts   // Per‑kind option validation
  context.ts    // buildContext (integrates phases)
  help.ts       // help metadata (rendering is in @clibu/help)
  run.ts        // createCLI runtime wrapper
  organ.ts      // Plugin hook stubs

Testing

• Unit & edge tests: option validation, flag negation, duplicates, unknown options.
• Snapshot tests: stable help output in test/__snapshots__.
• Performance baseline: perf.test.ts measures import & creation time.

License

MIT © KazViz