gunshi 0.26.2 → 0.27.0-alpha.10

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-	<img width="196" src="./assets/logo.png">
+	<img alt="logo" width="196" src="./assets/logo.png">
 </p>
 <h1 align="center">🏯 Gunshi</h1>
 
@@ -58,7 +58,7 @@ import { cli } from 'gunshi'
 const command = {
   name: 'greet',
   description: 'A greeting command',
-  options: {
+  args: {
     name: {
       type: 'string',
       short: 'n',
@@ -102,6 +102,8 @@ About more details and usage, see [documentations](https://gunshi.dev)
 - [sourcemap-publisher](https://github.com/es-tooling/sourcemap-publisher): A tool to publish sourcemaps externally and rewrite sourcemap URLs at pre-publish time
 - [curxy](https://github.com/ryoppippi/curxy): An proxy worker for using ollama in cursor
 - [SiteMCP](https://github.com/ryoppippi/sitemcp): Fetch an entire site and use it as an MCP Server
+- [ccusage](https://github.com/ryoppippi/ccusage): A CLI tool for analyzing Claude Code usage from local JSONL files
+- [varlock](https://github.com/dmno-dev/varlock): Enhanced .env file loader, using @decorator style comments to add validation, type-safety, and more
 
 ## 🙌 Contributing guidelines
 
@@ -123,7 +125,7 @@ The development of Gunshi is supported by my OSS sponsors!
 
 <p align="center">
   <a href="https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg">
-    <img src='https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg'/>
+    <img alt="sponsor" src='https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg'/>
   </a>
 </p>
 
@@ -135,9 +137,8 @@ The development of Gunshi is supported by my OSS sponsors!
 
 [npm-version-src]: https://img.shields.io/npm/v/gunshi?style=flat
 [npm-version-href]: https://npmjs.com/package/gunshi
-[jsr-src]: https://jsr.io/badges/@kazupon/gunshi
-[jsr-href]: https://jsr.io/@kazupon/gunshi
+[jsr-src]: https://jsr.io/badges/@gunshi/gunshi
+[jsr-href]: https://jsr.io/@gunshi/gunshi
 [install-size-src]: https://pkg-size.dev/badge/install/72346
-[install-size-href]: https://pkg-size.dev/gunshi
 [ci-src]: https://github.com/kazupon/gunshi/actions/workflows/ci.yml/badge.svg
 [ci-href]: https://github.com/kazupon/gunshi/actions/workflows/ci.yml

package/lib/bone.d.ts

@@ -0,0 +1,36 @@
+import { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions$1 as ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, RendererDecorator, RenderingOptions, ValidationErrorsDecorator } from "./types-BOnmRdsD.js";
+
+//#region src/cli/bone.d.ts
+
+/**
+ * Run the command.
+ * @param args Command line arguments
+ * @param entry A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
+ * @param options A {@link CliOptions | CLI options}
+ * @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
+ */
+declare function cli<A extends Args = Args, G extends GunshiParams = {
+  args: A;
+  extensions: {};
+}>(argv: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
+/**
+ * Run the command.
+ * @param args Command line arguments
+ * @param entry A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
+ * @param options A {@link CliOptions | CLI options}
+ * @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
+ */
+declare function cli<E extends ExtendContext = ExtendContext, G extends GunshiParams = {
+  args: Args;
+  extensions: E;
+}>(argv: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
+/**
+ * Run the command.
+ * @param args Command line arguments
+ * @param entry A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
+ * @param options A {@link CliOptions | CLI options}
+ * @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
+ */
+declare function cli<G extends GunshiParams = DefaultGunshiParams>(argv: string[], entry: Command<G> | CommandRunner<G> | LazyCommand<G>, options?: CliOptions<G>): Promise<string | undefined>;
+//#endregion
+export { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CliOptions, Command, CommandCallMode, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandRunner, Commandable, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, RendererDecorator, RenderingOptions, ValidationErrorsDecorator, cli };

package/lib/bone.js

@@ -0,0 +1,18 @@
+import "./context-8mKhXvhZ.js";
+import "./utils-CgxzpzVR.js";
+import { cliCore } from "./core-BNheElod.js";
+
+//#region src/cli/bone.ts
+/**
+* Run the command.
+* @param args Command line arguments
+* @param entry A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
+* @param options A {@link CliOptions | CLI options}
+* @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
+*/
+async function cli(argv, entry, options = {}) {
+	return cliCore(argv, entry, options, []);
+}
+
+//#endregion
+export { cli };

package/lib/cli-qFRmzDw-.js

@@ -0,0 +1,107 @@
+import { cliCore } from "./core-BNheElod.js";
+import { plugin } from "./plugin-DNwLti7p.js";
+import { COMMON_ARGS, namespacedId, renderer } from "./src-CYCa2B_o.js";
+
+//#region ../plugin-global/src/types.ts
+/**
+* The unique identifier for the global options plugin.
+*/
+const pluginId = namespacedId("global");
+
+//#endregion
+//#region ../plugin-global/src/decorator.ts
+/**
+* Decorator function to extend the command with global options.
+*/
+const decorator = (baseRunner) => async (ctx) => {
+	const { values, validationError, extensions: { [pluginId]: { showVersion, showHeader, showUsage, showValidationErrors } } } = ctx;
+	if (values.version) return showVersion();
+	const buf = [];
+	const header = await showHeader();
+	if (header) buf.push(header);
+	if (values.help) {
+		const usage = await showUsage();
+		if (usage) {
+			buf.push(usage);
+			return buf.join("\n");
+		}
+		return;
+	}
+	if (validationError) return await showValidationErrors(validationError);
+	return baseRunner(ctx);
+};
+var decorator_default = decorator;
+
+//#endregion
+//#region ../plugin-global/src/extension.ts
+function extension(ctx) {
+	return {
+		showVersion: () => {
+			const version = ctx.env.version || "unknown";
+			if (!ctx.env.usageSilent) ctx.log(version);
+			return version;
+		},
+		showHeader: async () => {
+			let header;
+			if (ctx.env.renderHeader != null) {
+				header = await ctx.env.renderHeader(ctx);
+				if (header) {
+					ctx.log(header);
+					ctx.log();
+				}
+			}
+			return header;
+		},
+		showUsage: async () => {
+			if (ctx.env.renderUsage != null) {
+				const usage = await ctx.env.renderUsage(ctx);
+				if (usage) {
+					ctx.log(usage);
+					return usage;
+				}
+			}
+		},
+		showValidationErrors: async (error) => {
+			if (ctx.env.renderValidationErrors === null) return;
+			if (ctx.env.renderValidationErrors !== void 0) {
+				const message = await ctx.env.renderValidationErrors(ctx, error);
+				ctx.log(message);
+				return message;
+			}
+		}
+	};
+}
+
+//#endregion
+//#region ../plugin-global/src/index.ts
+/**
+* global options plugin
+*/
+function global() {
+	return plugin({
+		id: pluginId,
+		name: "global options",
+		extension,
+		setup(ctx) {
+			for (const [name, schema] of Object.entries(COMMON_ARGS)) ctx.addGlobalOption(name, schema);
+			ctx.decorateCommand(decorator_default);
+		}
+	});
+}
+
+//#endregion
+//#region src/cli/builtin.ts
+/**
+* Run the command.
+* @param args Command line arguments
+* @param entry A {@link Command | entry command}, an {@link CommandRunner | inline command runner}, or a {@link LazyCommand | lazily-loaded command}
+* @param options A {@link CliOptions | CLI options}
+* @returns A rendered usage or undefined. if you will use {@link CliOptions.usageSilent} option, it will return rendered usage string.
+*/
+async function cli(argv, entry, options = {}) {
+	const builtInPlugins = [global(), renderer()];
+	return cliCore(argv, entry, options, builtInPlugins);
+}
+
+//#endregion
+export { cli };

package/lib/constants-5CeepucF.d.ts

@@ -0,0 +1,8 @@
+import { CliOptions, DefaultGunshiParams } from "./types-BOnmRdsD.js";
+
+//#region src/constants.d.ts
+
+declare const ANONYMOUS_COMMAND_NAME = "(anonymous)";
+declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
+//#endregion
+export { ANONYMOUS_COMMAND_NAME as ANONYMOUS_COMMAND_NAME$1, CLI_OPTIONS_DEFAULT as CLI_OPTIONS_DEFAULT$1 };

package/lib/context-8mKhXvhZ.js

@@ -0,0 +1,97 @@
+import { create, deepFreeze, isLazyCommand, log } from "./utils-CgxzpzVR.js";
+
+//#region src/constants.ts
+const ANONYMOUS_COMMAND_NAME = "(anonymous)";
+const NOOP = () => {};
+const CLI_OPTIONS_DEFAULT = {
+	name: void 0,
+	description: void 0,
+	version: void 0,
+	cwd: void 0,
+	usageSilent: false,
+	subCommands: void 0,
+	leftMargin: 2,
+	middleMargin: 10,
+	usageOptionType: false,
+	usageOptionValue: true,
+	renderHeader: void 0,
+	renderUsage: void 0,
+	renderValidationErrors: void 0,
+	plugins: void 0
+};
+
+//#endregion
+//#region src/context.ts
+/**
+* Create a {@link CommandContext | command context}
+* @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
+* @returns A {@link CommandContext | command context}, which is readonly
+*/
+async function createCommandContext({ args, explicit, values, positionals, rest, argv, tokens, command, extensions = {}, cliOptions, callMode = "entry", omitted = false, validationError }) {
+	/**
+	* normailize the options schema and values, to avoid prototype pollution
+	*/
+	const _args = Object.entries(args).reduce((acc, [key, value]) => {
+		acc[key] = Object.assign(create(), value);
+		return acc;
+	}, create());
+	/**
+	* setup the environment
+	*/
+	const env = Object.assign(create(), CLI_OPTIONS_DEFAULT, cliOptions);
+	/**
+	* apply Command definition's rendering option with highest priority
+	*/
+	if (command.rendering) {
+		const { header, usage, validationErrors } = command.rendering;
+		if (header !== void 0) env.renderHeader = header;
+		if (usage !== void 0) env.renderUsage = usage;
+		if (validationErrors !== void 0) env.renderValidationErrors = validationErrors;
+	}
+	/**
+	* create the command context
+	*/
+	const core = Object.assign(create(), {
+		name: getCommandName(command),
+		description: command.description,
+		omitted,
+		callMode,
+		env,
+		args: _args,
+		explicit,
+		values,
+		positionals,
+		rest,
+		_: argv,
+		tokens,
+		toKebab: command.toKebab,
+		log: cliOptions.usageSilent ? NOOP : log,
+		validationError
+	});
+	/**
+	* extend the command context with extensions
+	*/
+	if (Object.keys(extensions).length > 0) {
+		const ext = create(null);
+		Object.defineProperty(core, "extensions", {
+			value: ext,
+			writable: false,
+			enumerable: true,
+			configurable: true
+		});
+		for (const [key, extension] of Object.entries(extensions)) {
+			ext[key] = await extension.factory(core, command);
+			if (extension.onFactory) await extension.onFactory(core, command);
+		}
+	}
+	const ctx = deepFreeze(core, ["extensions"]);
+	return ctx;
+}
+function getCommandName(cmd) {
+	if (isLazyCommand(cmd)) return cmd.commandName || cmd.name || ANONYMOUS_COMMAND_NAME;
+	else if (typeof cmd === "object") return cmd.name || ANONYMOUS_COMMAND_NAME;
+	else return ANONYMOUS_COMMAND_NAME;
+}
+
+//#endregion
+export { ANONYMOUS_COMMAND_NAME, CLI_OPTIONS_DEFAULT, NOOP, createCommandContext };

package/lib/context-XtGgRV6b.d.ts

@@ -0,0 +1,93 @@
+import { ArgToken, ArgValues, CliOptions, Command, CommandCallMode, CommandContext, CommandContextExtension, DefaultGunshiParams, ExtendContext, ExtractArgExplicitlyProvided, ExtractArgs, GunshiParams, GunshiParamsConstraint, LazyCommand } from "./types-BOnmRdsD.js";
+
+//#region src/context.d.ts
+
+/**
+ * Extract extension return types from extensions record
+ * @internal
+ */
+type ExtractExtensions<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
+/**
+ * Parameters of {@link createCommandContext}
+ */
+interface CommandContextParams<G extends GunshiParams | {
+  extensions: ExtendContext;
+}, V extends ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = Record<string, CommandContextExtension>> {
+  /**
+   * An arguments of target command
+   */
+  args: ExtractArgs<G>;
+  /**
+   * Explicitly provided arguments
+   */
+  explicit: ExtractArgExplicitlyProvided<G>;
+  /**
+   * A values of target command
+   */
+  values: V;
+  /**
+   * A positionals arguments, which passed to the target command
+   */
+  positionals: string[];
+  /**
+   * A rest arguments, which passed to the target command
+   */
+  rest: string[];
+  /**
+   * Original command line arguments
+   */
+  argv: string[];
+  /**
+   * Argument tokens that are parsed by the `parseArgs` function
+   */
+  tokens: ArgToken[];
+  /**
+   * Whether the command is omitted
+   */
+  omitted: boolean;
+  /**
+   * Command call mode.
+   */
+  callMode: CommandCallMode;
+  /**
+   * A target command
+   */
+  command: C;
+  /**
+   * Plugin extensions to apply as the command context extension.
+   */
+  extensions?: E;
+  /**
+   * A command options, which is spicialized from `cli` function
+   */
+  cliOptions: CliOptions<G>;
+  /**
+   * Validation error from argument parsing.
+   */
+  validationError?: AggregateError;
+}
+/**
+ * Create a {@link CommandContext | command context}
+ * @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
+ * @returns A {@link CommandContext | command context}, which is readonly
+ */
+declare function createCommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams, V extends ArgValues<ExtractArgs<G>> = ArgValues<ExtractArgs<G>>, C extends Command<G> | LazyCommand<G> = Command<G>, E extends Record<string, CommandContextExtension> = {}>({
+  args,
+  explicit,
+  values,
+  positionals,
+  rest,
+  argv,
+  tokens,
+  command,
+  extensions,
+  cliOptions,
+  callMode,
+  omitted,
+  validationError
+}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
+  args: ExtractArgs<G>;
+  extensions: ExtractExtensions<E>;
+}>>>>;
+//#endregion
+export { ExtractExtensions, createCommandContext as createCommandContext$1 };

package/lib/context.d.ts

@@ -1,71 +1,3 @@
-import { CliOptions, Command, CommandCallMode, CommandContext, LazyCommand } from "./types-DtEE4hKC.js";
-import { ArgToken, ArgValues, Args } from "args-tokens";
-
-//#region src/context.d.ts
-/**
-* Parameters of {@link createCommandContext}
-*/
-
-/**
- * Parameters of {@link createCommandContext}
- */
-interface CommandContextParams<A extends Args, V> {
-  /**
-   * An arguments of target command
-   */
-  args: A;
-  /**
-   * A values of target command
-   */
-  values: V;
-  /**
-   * A positionals arguments, which passed to the target command
-   */
-  positionals: string[];
-  /**
-   * A rest arguments, which passed to the target command
-   */
-  rest: string[];
-  /**
-   * Original command line arguments
-   */
-  argv: string[];
-  /**
-   * Argument tokens that are parsed by the `parseArgs` function
-   */
-  tokens: ArgToken[];
-  /**
-   * Whether the command is omitted
-   */
-  omitted: boolean;
-  /**
-   * Command call mode.
-   */
-  callMode: CommandCallMode;
-  /**
-   * A target command
-   */
-  command: Command<A> | LazyCommand<A>;
-  /**
-   * A command options, which is spicialized from `cli` function
-   */
-  cliOptions: CliOptions<A>;
-}
-/**
- * Create a {@link CommandContext | command context}
- * @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
- * @returns A {@link CommandContext | command context}, which is readonly
- */
-declare function createCommandContext<A extends Args = Args, V extends ArgValues<A> = ArgValues<A>>({
-  args,
-  values,
-  positionals,
-  rest,
-  argv,
-  tokens,
-  command,
-  cliOptions,
-  callMode,
-  omitted
-}: CommandContextParams<A, V>): Promise<Readonly<CommandContext<A, V>>>; //#endregion
-export { createCommandContext };
+import "./types-BOnmRdsD.js";
+import { ExtractExtensions, createCommandContext$1 as createCommandContext } from "./context-XtGgRV6b.js";
+export { ExtractExtensions, createCommandContext };

package/lib/context.js

@@ -1,4 +1,4 @@
-import "./utils-D41C8Abf.js";
-import { createCommandContext } from "./context-D_EmfRNA.js";
+import { createCommandContext } from "./context-8mKhXvhZ.js";
+import "./utils-CgxzpzVR.js";
 
 export { createCommandContext };