@boneskull/bargs 0.1.1

package/LICENSE

@@ -0,0 +1,55 @@
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules. The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice. If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+**_As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim._**

package/README.md

@@ -0,0 +1,483 @@
+<p align="center">
+  <a href="/"><img src="./assets/logo.png" width="512px" align="center" alt="bargs: a barg parser"/></a>
+  <h1 align="center"><span class="bargs">⁓ bargs ⁓<span></h1>
+  <p align="center">
+    <em>“Ex argumentis, veritas”</em>
+    <br/>
+    <small>by <a href="https://github.com/boneskull" title="@boneskull on GitHub">@boneskull</a></small>
+  </p>
+</p>
+
+## Install
+
+```shell
+npm install @boneskull/bargs
+```
+
+## Why bargs?
+
+Most argument parsers make you choose: either a simple API with weak types, or a complex and overengineered DSL. **bargs** uses _function helpers_ that instead provide a well-typed and composable API.
+
+### Type-Safe by Construction
+
+Each helper returns a fully-typed option definition:
+
+```typescript
+const verbose = bargs.boolean({ aliases: ['v'] });
+// Type: BooleanOption & { aliases: ['v'] }
+
+const level = bargs.enum(['low', 'medium', 'high'], { default: 'medium' });
+// Type: EnumOption<'low' | 'medium' | 'high'> & { default: 'medium' }
+```
+
+When you pass these to `bargs()`, the result is always well-typed; options with defaults or `required: true` are non-nullable.
+
+### Composable
+
+Since helpers are just functions returning objects, composition is trivial:
+
+```typescript
+// Shared options across commands
+const verboseOpt = { verbose: bargs.boolean({ aliases: ['v'] }) };
+const outputOpt = {
+  output: bargs.string({ aliases: ['o'], default: 'stdout' }),
+};
+
+// Merge with spread
+const result = bargs({
+  name: 'tool',
+  options: {
+    ...verboseOpt,
+    ...outputOpt,
+    format: bargs.enum(['json', 'text']),
+  },
+});
+```
+
+Or use `bargs.options()` and `bargs.positionals()`:
+
+```typescript
+// Throws if aliases collide
+const sharedOpts = bargs.options(verboseOpt, outputOpt);
+
+// Combine positionals with type inference
+const sharedPos = bargs.positionals(
+  bargs.stringPos({ name: 'input', required: true }),
+  bargs.stringPos({ name: 'output' }),
+);
+```
+
+### Zero (0) Dependencies
+
+Only Node.js v22+.
+
+## Quick Start
+
+```typescript
+import { bargs } from '@boneskull/bargs';
+
+const result = bargs({
+  name: 'greet',
+  options: {
+    name: bargs.string({ default: 'world' }),
+    loud: bargs.boolean({ aliases: ['l'] }),
+  },
+});
+
+const greeting = `Hello, ${result.values.name}!`;
+console.log(result.values.loud ? greeting.toUpperCase() : greeting);
+```
+
+```shell
+$ greet --name Alice --loud
+HELLO, ALICE!
+```
+
+## Sync vs Async
+
+**`bargs()`** runs synchronously. If a handler returns a `Promise`, it will break and you will be sorry.
+
+```typescript
+// Sync - no await needed
+const result = bargs({
+  name: 'my-cli',
+  options: { verbose: bargs.boolean() },
+  handler: ({ values }) => {
+    console.log('Verbose:', values.verbose);
+  },
+});
+```
+
+Instead, use **`bargsAsync()`**:
+
+```typescript
+import { bargsAsync } from '@boneskull/bargs';
+
+// Async - handlers can return Promises
+const result = await bargsAsync({
+  name: 'my-cli',
+  options: { url: bargs.string({ required: true }) },
+  handler: async ({ values }) => {
+    const response = await fetch(values.url);
+    console.log(await response.text());
+  },
+});
+```
+
+## Commands
+
+Define subcommands with `bargs.command()`:
+
+```typescript
+bargs({
+  name: 'db',
+  commands: {
+    migrate: bargs.command({
+      description: 'Run database migrations',
+      options: { dry: bargs.boolean({ aliases: ['n'] }) },
+      handler: ({ values }) => {
+        console.log(values.dry ? 'Dry run...' : 'Migrating...');
+      },
+    }),
+    seed: bargs.command({
+      description: 'Seed the database',
+      positionals: [bargs.stringPos({ required: true })],
+      handler: ({ positionals }) => {
+        const [file] = positionals;
+        console.log(`Seeding from ${file}...`);
+      },
+    }),
+  },
+});
+```
+
+```shell
+$ db migrate --dry
+Dry run...
+
+$ db seed data.sql
+Seeding from data.sql...
+```
+
+### Default Handler
+
+For command-based CLIs, use `defaultHandler` to handle the case when no command is provided:
+
+```typescript
+bargs({
+  name: 'git',
+  commands: {
+    /* ... */
+  },
+  // Run 'status' when no command given
+  defaultHandler: 'status',
+});
+
+// Or provide a custom handler
+bargs({
+  name: 'git',
+  commands: {
+    /* ... */
+  },
+  defaultHandler: ({ values }) => {
+    console.log('Run "git --help" for usage');
+  },
+});
+```
+
+## Configuration
+
+### Config Properties
+
+| Property      | Type                  | Description                                       |
+| ------------- | --------------------- | ------------------------------------------------- |
+| `name`        | `string`              | CLI name (required)                               |
+| `description` | `string`              | Description shown in help                         |
+| `version`     | `string`              | Enables `--version` flag                          |
+| `options`     | `OptionsSchema`       | Named options (`--flag`)                          |
+| `positionals` | `PositionalsSchema`   | Positional arguments                              |
+| `commands`    | `Record<string, ...>` | Subcommands                                       |
+| `handler`     | `Handler`             | Handler function(s) for simple CLIs               |
+| `epilog`      | `string \| false`     | Footer text in help (see [Epilog](#epilog))       |
+| `args`        | `string[]`            | Custom args (defaults to `process.argv.slice(2)`) |
+
+```typescript
+bargs({
+  name: 'my-cli',
+  description: 'Does amazing things',
+  version: '1.2.3', // enables --version
+  args: ['--verbose', 'file.txt'], // useful for testing
+  options: {
+    /* ... */
+  },
+});
+```
+
+### Runtime Options
+
+The second argument to `bargs()` or `bargsAsync()` accepts runtime options:
+
+| Property | Type         | Description                                    |
+| -------- | ------------ | ---------------------------------------------- |
+| `theme`  | `ThemeInput` | `--help` Color theme (see [Theming](#theming)) |
+
+```typescript
+bargs(config, { theme: 'ocean' });
+```
+
+## Option Helpers
+
+```typescript
+bargs.string({ default: 'value' }); // --name value
+bargs.number({ default: 42 }); // --count 42
+bargs.boolean({ aliases: ['v'] }); // --verbose, -v
+bargs.enum(['a', 'b', 'c']); // --level a
+bargs.array('string'); // --file x --file y
+bargs.count(); // -vvv → 3
+```
+
+### Option Properties
+
+All option helpers accept these properties:
+
+| Property      | Type       | Description                                      |
+| ------------- | ---------- | ------------------------------------------------ |
+| `aliases`     | `string[]` | Short flags (e.g., `['v']` for `-v`)             |
+| `default`     | varies     | Default value (makes the option non-nullable)    |
+| `description` | `string`   | Help text description                            |
+| `group`       | `string`   | Groups options under a custom section header     |
+| `hidden`      | `boolean`  | Hide from `--help` output                        |
+| `required`    | `boolean`  | Mark as required (makes the option non-nullable) |
+
+```typescript
+bargs.string({
+  aliases: ['o'],
+  default: 'output.txt',
+  description: 'Output file path',
+  group: 'Output Options',
+});
+
+// Hidden options won't appear in help
+bargs.boolean({ hidden: true });
+```
+
+## Positional Helpers
+
+```typescript
+bargs.stringPos({ required: true }); // <file>
+bargs.numberPos({ default: 8080 }); // [port]
+bargs.enumPos(['dev', 'prod']); // [env]
+bargs.variadic('string'); // [files...]
+```
+
+### Positional Properties
+
+| Property      | Type      | Description                                            |
+| ------------- | --------- | ------------------------------------------------------ |
+| `default`     | varies    | Default value                                          |
+| `description` | `string`  | Help text description                                  |
+| `name`        | `string`  | Display name in help (defaults to `arg0`, `arg1`, ...) |
+| `required`    | `boolean` | Mark as required (shown as `<name>` vs `[name]`)       |
+
+```typescript
+bargs.stringPos({
+  name: 'file',
+  description: 'Input file to process',
+  required: true,
+});
+```
+
+Positionals are defined as an array and accessed by index:
+
+```typescript
+const result = bargs({
+  name: 'cp',
+  positionals: [
+    bargs.stringPos({ required: true }), // source
+    bargs.stringPos({ required: true }), // destination
+  ],
+});
+
+const [source, dest] = result.positionals;
+console.log(`Copying ${source} to ${dest}`);
+```
+
+Use `variadic` for rest arguments (must be last):
+
+```typescript
+const result = bargs({
+  name: 'cat',
+  positionals: [bargs.variadic('string')],
+});
+
+const [files] = result.positionals; // string[]
+files.forEach((file) => console.log(readFileSync(file, 'utf8')));
+```
+
+## Epilog
+
+By default, **bargs** displays your package's homepage and repository URLs (from `package.json`) at the end of help output. URLs become clickable hyperlinks in supported terminals.
+
+```typescript
+// Custom epilog
+bargs({
+  name: 'my-cli',
+  epilog: 'For more info, visit https://example.com',
+});
+
+// Disable epilog entirely
+bargs({
+  name: 'my-cli',
+  epilog: false,
+});
+```
+
+## Theming
+
+Customize help output colors with built-in themes or your own:
+
+```typescript
+// Use a built-in theme: 'default', 'mono', 'ocean', 'warm'
+bargs(
+  {
+    name: 'my-cli',
+    options: { verbose: bargs.boolean() },
+  },
+  { theme: 'ocean' },
+);
+
+// Disable colors entirely
+bargs(config, { theme: 'mono' });
+```
+
+The `ansi` export provides common ANSI escape codes for styled terminal output: text styles (`bold`, `dim`, `italic`, `underline`, etc.), foreground colors, background colors, and their `bright*` variants. Use this to create your own themes (instead of hardcoding ANSI escape codes).
+
+```typescript
+import { ansi } from '@boneskull/bargs';
+
+bargs(someConfig, {
+  theme: {
+    command: ansi.bold,
+    defaultText: ansi.dim,
+    defaultValue: ansi.white,
+    description: ansi.white,
+    epilog: ansi.dim,
+    example: ansi.white + ansi.dim,
+    flag: ansi.brightCyan,
+    positional: ansi.magenta,
+    scriptName: ansi.bold,
+    sectionHeader: ansi.brightMagenta,
+    type: ansi.magenta,
+    url: ansi.cyan,
+    usage: ansi.cyan,
+  },
+});
+```
+
+Available theme color slots:
+
+| Slot            | What it styles                                  |
+| --------------- | ----------------------------------------------- |
+| `command`       | Command names (e.g., `init`, `build`)           |
+| `defaultText`   | The `default:` label                            |
+| `defaultValue`  | Default value (e.g., `false`, `"hello"`)        |
+| `description`   | Description text for options and commands       |
+| `epilog`        | Footer text (homepage, repository)              |
+| `example`       | Example code/commands                           |
+| `flag`          | Flag names (e.g., `--verbose`, `-v`)            |
+| `positional`    | Positional argument names (e.g., `<file>`)      |
+| `scriptName`    | CLI name shown in header                        |
+| `sectionHeader` | Section headers (e.g., `USAGE`, `OPTIONS`)      |
+| `type`          | Type annotations (e.g., `[string]`, `[number]`) |
+| `url`           | URLs (for clickable hyperlinks)                 |
+| `usage`         | The usage line text                             |
+
+> [!TIP]
+> You don't need to specify all color slots. Missing colors fall back to the default theme.
+
+## Advanced Usage
+
+### Error Handling
+
+**bargs** exports some `Error` subclasses:
+
+```typescript
+import {
+  bargs,
+  BargsError,
+  HelpError,
+  ValidationError,
+} from '@boneskull/bargs';
+
+try {
+  bargs(config);
+} catch (error) {
+  if (error instanceof ValidationError) {
+    // Config validation failed (e.g., invalid schema)
+    console.error(`Config error at "${error.path}": ${error.message}`);
+  } else if (error instanceof HelpError) {
+    // User needs guidance (e.g., unknown option)
+    console.error(error.message);
+  } else if (error instanceof BargsError) {
+    // General bargs error
+    console.error(error.message);
+  }
+}
+```
+
+### Programmatic Help
+
+Generate help text without calling `bargs()`:
+
+```typescript
+import { generateHelp, generateCommandHelp } from '@boneskull/bargs';
+
+const helpText = generateHelp(config);
+const commandHelp = generateCommandHelp(config, 'migrate');
+```
+
+### Hyperlink Utilities
+
+Create clickable terminal hyperlinks ([OSC 8](https://github.com/Alhadis/OSC8-Adoption)):
+
+```typescript
+import { link, linkifyUrls, supportsHyperlinks } from '@boneskull/bargs';
+
+// Check if terminal supports hyperlinks
+if (supportsHyperlinks()) {
+  // Create a hyperlink
+  console.log(link('Click me', 'https://example.com'));
+
+  // Auto-linkify URLs in text
+  console.log(linkifyUrls('Visit https://example.com for more info'));
+}
+```
+
+> [!TIP]
+> **bargs** already automatically links URLs in `--help` output if the terminal supports hyperlinks.
+
+### Additional Theme Utilities
+
+```typescript
+import {
+  ansi, // ANSI escape codes
+  createStyler, // Create a styler from a theme
+  defaultTheme, // The default theme object
+  stripAnsi, // Remove ANSI codes from string
+  themes, // All built-in themes
+} from '@boneskull/bargs';
+
+// Create a custom styler
+const styler = createStyler({ colors: { flag: ansi.green } });
+console.log(styler.flag('--verbose'));
+
+// Strip ANSI codes for plain text output
+const plain = stripAnsi('\x1b[32m--verbose\x1b[0m'); // '--verbose'
+
+// Override some colors in a built-in theme
+const customTheme = { ...themes.ocean, colors: { flag: ansi.green } };
+```
+
+## License
+
+Copyright © 2025 [Christopher "boneskull" Hiller](https://github.com/boneskull). Licensed under the [Blue Oak Model License 1.0.0](./LICENSE).

package/dist/bargs.cjs

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Core bargs parsing functions for both sync and async CLI execution.
+ *
+ * Provides `bargs()` (synchronous) and `bargsAsync()` (asynchronous) entry
+ * points that handle configuration validation, built-in `--help` and
+ * `--version` flags, argument parsing, and handler invocation. Supports both
+ * simple CLIs with options/positionals and command-based CLIs with
+ * subcommands.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bargs = bargs;
+exports.bargsAsync = bargsAsync;
+const errors_js_1 = require("./errors.cjs");
+const help_js_1 = require("./help.cjs");
+const parser_js_1 = require("./parser.cjs");
+const theme_js_1 = require("./theme.cjs");
+const validate_js_1 = require("./validate.cjs");
+/**
+ * Check if config has commands.
+ */
+const hasCommands = (config) => config.commands !== undefined && Object.keys(config.commands).length > 0;
+/**
+ * Check if user defined their own help option (by name or alias).
+ */
+const hasUserDefinedHelp = (options) => {
+    if (!options) {
+        return false;
+    }
+    if ('help' in options) {
+        return true;
+    }
+    // Check if any option has 'h' as an alias
+    return Object.values(options).some((opt) => opt.aliases?.includes('h'));
+};
+/**
+ * Check if user defined their own version option (by name or alias).
+ */
+const hasUserDefinedVersion = (options) => {
+    if (!options) {
+        return false;
+    }
+    if ('version' in options) {
+        return true;
+    }
+    // Check if any option has 'V' as an alias
+    return Object.values(options).some((opt) => opt.aliases?.includes('V'));
+};
+/**
+ * Handle help and version flags. Returns true if we should exit.
+ */
+const handleBuiltinFlags = (config, args, theme = theme_js_1.defaultTheme) => {
+    // Handle --help (unless user defined their own help option)
+    const userDefinedHelp = hasUserDefinedHelp(config.options);
+    if (!userDefinedHelp && (args.includes('--help') || args.includes('-h'))) {
+        if (hasCommands(config)) {
+            // Check for command-specific help: cmd --help
+            const helpIndex = args.findIndex((a) => a === '--help' || a === '-h');
+            const commandIndex = args.findIndex((a) => !a.startsWith('-'));
+            if (commandIndex >= 0 && commandIndex < helpIndex) {
+                const commandName = args[commandIndex];
+                console.log((0, help_js_1.generateCommandHelp)(config, commandName, theme));
+            }
+            else {
+                console.log((0, help_js_1.generateHelp)(config, theme));
+            }
+        }
+        else {
+            console.log((0, help_js_1.generateHelp)(config, theme));
+        }
+        process.exit(0);
+    }
+    // Handle --version (unless user defined their own version option)
+    const userDefinedVersion = hasUserDefinedVersion(config.options);
+    if (!userDefinedVersion && args.includes('--version') && config.version) {
+        console.log(config.version);
+        process.exit(0);
+    }
+    return false;
+};
+/**
+ * Handle HelpError by printing message and help text.
+ */
+const handleHelpError = (error, config, theme = theme_js_1.defaultTheme) => {
+    if (error instanceof errors_js_1.HelpError) {
+        console.error(error.message);
+        if (hasCommands(config)) {
+            console.log((0, help_js_1.generateHelp)(config, theme));
+        }
+        else {
+            console.log((0, help_js_1.generateHelp)(config, theme));
+        }
+        process.exit(1);
+    }
+    throw error;
+};
+/**
+ * Main bargs entry point (sync implementation). Throws BargsError if any
+ * handler returns a thenable.
+ */
+function bargs(config, options) {
+    // Validate config upfront (throws ValidationError if invalid)
+    (0, validate_js_1.validateConfig)(config);
+    const args = config.args ?? process.argv.slice(2);
+    const theme = options?.theme
+        ? (0, theme_js_1.getTheme)(options.theme)
+        : (0, theme_js_1.getTheme)('default');
+    try {
+        handleBuiltinFlags(config, args, theme);
+        // Parse
+        if (hasCommands(config)) {
+            return (0, parser_js_1.parseCommandsSync)({ ...config, args });
+        }
+        else {
+            const result = (0, parser_js_1.parseSimple)({
+                args,
+                options: config.options,
+                positionals: config.positionals,
+            });
+            // Call handler(s) if provided (sync)
+            if (config.handler) {
+                (0, parser_js_1.runSyncHandlers)(config.handler, result);
+            }
+            return result;
+        }
+    }
+    catch (error) {
+        return handleHelpError(error, config, theme);
+    }
+}
+/**
+ * Main bargs entry point (async implementation). Awaits all handlers,
+ * supporting async handlers.
+ */
+async function bargsAsync(config, options) {
+    // Validate config upfront (throws ValidationError if invalid)
+    (0, validate_js_1.validateConfig)(config);
+    const args = config.args ?? process.argv.slice(2);
+    const theme = options?.theme
+        ? (0, theme_js_1.getTheme)(options.theme)
+        : (0, theme_js_1.getTheme)('default');
+    try {
+        handleBuiltinFlags(config, args, theme);
+        // Parse
+        if (hasCommands(config)) {
+            return await (0, parser_js_1.parseCommandsAsync)({ ...config, args });
+        }
+        else {
+            const result = (0, parser_js_1.parseSimple)({
+                args,
+                options: config.options,
+                positionals: config.positionals,
+            });
+            // Call handler(s) if provided (async)
+            if (config.handler) {
+                await (0, parser_js_1.runHandlers)(config.handler, result);
+            }
+            return result;
+        }
+    }
+    catch (error) {
+        return handleHelpError(error, config, theme);
+    }
+}
+//# sourceMappingURL=bargs.js.map