termcraft 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mythie
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# termcraft
+
+[![CI](https://github.com/Mythie/termcraft/actions/workflows/ci.yml/badge.svg)](https://github.com/Mythie/termcraft/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+
+Build type-safe CLIs with a single function call. Parsing, help, subcommands, and lifecycle hooks, all inferred from your definition.
+
+> **Note:** termcraft is in early development (v0.1.0). The API may change between minor versions until v1.0.0.
+
+## Quick Start
+
+```sh
+bun add termcraft
+```
+
+```ts
+import { defineCommand, parseAsString, parseAsBoolean, runMain } from "termcraft";
+
+const command = defineCommand({
+  meta: { name: "greet", version: "1.0.0" },
+  args: {
+    name: parseAsString.positional(0).withDescription("Name to greet."),
+    loud: parseAsBoolean.withDefault(false).withDescription("Print in uppercase."),
+  },
+  run: ({ args }) => {
+    const line = `Hello ${args.name}!`;
+    console.log(args.loud ? line.toUpperCase() : line);
+  },
+});
+
+await runMain(command);
+```
+
+```
+$ bun run greet.ts world --loud
+HELLO WORLD!
+
+$ bun run greet.ts --help
+greet
+
+USAGE
+  greet <name> [options]
+
+ARGUMENTS
+  <name>  Name to greet.
+
+OPTIONS
+  --loud       Print in uppercase. (default: false)
+  -h, --help   Show help
+```
+
+## Why termcraft?
+
+- **Bun-native** Designed for Bun from the ground up, no Node baggage.
+- **Fully type-safe** Argument types are inferred from your definition. `args.port` is `number`, not `any`. `.withDefault()` and `.withRequired()` narrow the type from `T | null` to `T`.
+- **Lifecycle hooks** `setup` / `run` / `cleanup` / `onError` with guaranteed cleanup, even on SIGINT. No other lightweight CLI framework handles resource teardown this well.
+- **Flag-or-prompt pattern** Combine CLI flags with interactive prompts: `args.name ?? await text({ message: "Name?" })`. Ship CLIs that work both interactively and in scripts.
+- **Batteries included** Prompts, colors, and banners as sub-path imports. One `bun add`, no juggling packages.
+
+## Features
+
+- **Declarative commands** Define CLIs with `defineCommand()`.
+- **Type-safe parsers** `parseAsString`, `parseAsInteger`, `parseAsFloat`, `parseAsBoolean`, `parseAsEnum`.
+- **Fluent API** `.withAlias()`, `.withDefault()`, `.withRequired()`, `.withDescription()`, `.positional()`, `.variadic()`.
+- **Subcommand routing** Nested commands with lazy-loaded imports via `() => import()`.
+- **Auto-generated help** `--help` / `-h` with aligned columns, usage lines, and examples.
+- **Signal handling** Graceful SIGINT (exit 130) / SIGTERM (exit 143) with cleanup.
+- **Interactive prompts** via `termcraft/prompts` ([`@clack/prompts`](https://github.com/bombshell-dev/clack)).
+- **Terminal colors** via `termcraft/colors` ([`picocolors`](https://github.com/alexeyraspopov/picocolors)).
+- **ASCII banners** via `termcraft/banner` ([`figlet`](https://github.com/patorjk/figlet.js)).
+- **Custom parsers** from parse/serialize functions or any Zod-compatible schema.
+
+## Argument Parsers
+
+Parsers start as optional (`T | null`). Chain methods to refine:
+
+```ts
+import { parseAsString, parseAsInteger, parseAsEnum } from "termcraft";
+
+parseAsString.positional(0)                                    // string | null
+parseAsString.positional(0).withRequired()                     // string (non-null)
+parseAsInteger.withAlias("c").withDefault(1)                   // number (non-null)
+parseAsString.withRequired().withDescription("Output file.")   // string (non-null)
+parseAsEnum(["stable", "beta", "canary"] as const)             // "stable" | "beta" | "canary" | null
+parseAsString.positional(0).variadic()                         // string[] (collects remaining)
+```
+
+### Built-in Parsers
+
+| Parser | Type | Description |
+|--------|------|-------------|
+| `parseAsString` | `string` | Pass-through string |
+| `parseAsInteger` | `number` | Whole numbers only |
+| `parseAsFloat` | `number` | Any valid number |
+| `parseAsBoolean` | `boolean` | `true/yes/1` or `false/no/0` |
+| `parseAsEnum(values)` | `values[number]` | One of the provided values |
+
+### Custom Parsers
+
+Create parsers from functions or any object with `safeParse` (e.g., Zod):
+
+```ts
+import { createParser } from "termcraft";
+
+// From parse/serialize functions
+const parseAsDate = createParser({
+  parse: (value: string) => {
+    const date = new Date(value);
+    return isNaN(date.getTime()) ? null : date;
+  },
+  serialize: (value: Date) => value.toISOString(),
+});
+
+// From a Zod schema (requires zod as a peer dependency)
+import { z } from "zod";
+const parseAsPort = createParser(z.coerce.number().int().min(1).max(65535));
+```
+
+## Subcommands
+
+Nest commands with the `commands` field. Supports deeply nested routing and lazy-loaded imports:
+
+```ts
+import { defineCommand, parseAsInteger, runMain } from "termcraft";
+
+const command = defineCommand({
+  meta: { name: "tasks", version: "1.0.0" },
+  commands: {
+    list: defineCommand({
+      meta: { name: "list", description: "List tasks." },
+      args: {
+        limit: parseAsInteger.withDefault(10).withDescription("Max tasks."),
+      },
+      run: ({ args }) => console.log(`Listing ${args.limit} tasks`),
+    }),
+    // Lazy-loaded subcommand
+    deploy: () => import("./commands/deploy"),
+  },
+});
+
+await runMain(command);
+```
+
+```sh
+bun run cli.ts list --limit 5
+bun run cli.ts deploy
+```
+
+## Lifecycle Hooks
+
+Commands support `setup`, `run`, `cleanup`, and `onError` hooks. Cleanup is guaranteed to run even if `setup` or `run` throws:
+
+```ts
+const command = defineCommand({
+  meta: { name: "release", version: "1.0.0" },
+  args: {
+    tag: parseAsString.withRequired().withDescription("Version tag."),
+  },
+  setup: async ({ args }) => {
+    console.log(`Preparing release ${args.tag}`);
+  },
+  run: ({ args }) => {
+    console.log(`Publishing ${args.tag}`);
+  },
+  cleanup: () => {
+    console.log("Cleaning up temporary files");
+  },
+  onError: (error) => {
+    console.error(`Release failed: ${error}`);
+    process.exitCode = 1;
+  },
+});
+```
+
+## Interactive Prompts
+
+Use `termcraft/prompts` for interactive input. The flag-or-prompt pattern lets your CLI work both interactively and in CI:
+
+```ts
+import { defineCommand, parseAsString, runMain } from "termcraft";
+import { text, select, intro, outro } from "termcraft/prompts";
+
+const command = defineCommand({
+  meta: { name: "init", version: "1.0.0" },
+  args: {
+    name: parseAsString.withDescription("Project name."),
+  },
+  run: async ({ args }) => {
+    intro("Project Setup");
+
+    // Use CLI flag if provided, prompt otherwise
+    const name = args.name ?? await text({ message: "Project name?" });
+
+    const template = await select({
+      message: "Template?",
+      options: [
+        { value: "web", label: "Web App" },
+        { value: "api", label: "API Server" },
+      ],
+    });
+
+    outro(`Created ${name} with ${template} template.`);
+  },
+});
+
+await runMain(command);
+```
+
+## Colors and Banners
+
+```ts
+import { colors } from "termcraft/colors";
+import { banner } from "termcraft/banner";
+
+console.log(await banner("my-app"));
+console.log(colors.green("Success!"));
+console.log(colors.bold(colors.red("Error:")), "something went wrong");
+```
+
+## Error Handling
+
+termcraft exports error classes for programmatic error handling:
+
+```ts
+import { TermcraftError, MissingArgError, InvalidValueError } from "termcraft";
+```
+
+- `MissingArgError` is thrown when a required argument or option is missing.
+- `InvalidValueError` is thrown when a value doesn't match the parser's expected type.
+- `TermcraftError` is the base class for all termcraft errors.
+
+Signal handling is automatic: SIGINT exits with code 130, SIGTERM with 143. Cleanup hooks always run before exit.
+
+## Documentation
+
+Full guides and API reference in [`docs/`](./docs/):
+
+- [Getting Started](./docs/getting-started.md)
+- [Defining Commands](./docs/defining-commands.md)
+- [Argument Parsers](./docs/argument-parsers.md)
+- [Custom Parsers](./docs/custom-parsers.md)
+- [Subcommands](./docs/subcommands.md)
+- [Lifecycle Hooks](./docs/lifecycle-hooks.md)
+- [Prompts, Colors, and Banners](./docs/prompts.md)
+- [Error Handling](./docs/error-handling.md)
+- [API Reference](./docs/api-reference.md)
+
+## Examples
+
+See [`examples/`](./examples/) for complete working CLIs:
+
+- **[greet.ts](./examples/greet.ts)** positional args, flags, aliases
+- **[init.ts](./examples/init.ts)** interactive prompts with flag-or-prompt pattern
+- **[release.ts](./examples/release.ts)** lifecycle hooks, banners, error handling
+- **[tasks.ts](./examples/tasks.ts)** subcommands and nested commands
+- **[workspace.ts](./examples/workspace.ts)** full app-like CLI with grouped subcommands
+
+```sh
+bun run examples/greet.ts world --loud
+```
+
+## Development
+
+```sh
+bun install        # install dependencies
+bun test           # run tests
+bun run lint       # check for lint/format issues
+bun run lint:fix   # auto-fix lint/format issues
+bun run typecheck  # run TypeScript type checking
+bun run check      # lint + typecheck
+bun run build      # build dist/ for publishing
+```
+
+## License
+
+MIT

package/dist/banner/index.d.mts

@@ -0,0 +1,7 @@
+//#region src/banner/index.d.ts
+interface BannerOptions {
+  font?: "1Row" | "3-D" | "3D Diagonal" | "3D-ASCII" | "3x5" | "4Max" | "5 Line Oblique" | "Standard" | "Ghost" | "Big" | "Block" | "Bubble" | "Digital" | "Ivrit" | "Mini" | "Script" | "Shadow" | "Slant" | "Small" | "Speed" | "Tinker-Toy" | (string & {});
+}
+declare function banner(text: string, options?: BannerOptions): Promise<string>;
+//#endregion
+export { BannerOptions, banner };

package/dist/banner/index.mjs

@@ -0,0 +1,15 @@
+import figlet from "figlet";
+//#region src/banner/index.ts
+function banner(text, options) {
+	return new Promise((resolve, reject) => {
+		figlet.text(text, options, (error, result) => {
+			if (error) {
+				reject(error);
+				return;
+			}
+			resolve(result ?? "");
+		});
+	});
+}
+//#endregion
+export { banner };

package/dist/index.d.mts

@@ -0,0 +1,108 @@
+//#region src/parsers/types.d.ts
+type ParserFunctions<T> = {
+  parse: (val: string) => T | null;
+  serialize: (val: T) => string;
+};
+type ParserMeta = {
+  alias?: string;
+  description?: string;
+  defaultValue?: unknown;
+  isRequired: boolean;
+  isPositional: boolean;
+  positionalIndex?: number;
+  isVariadic: boolean;
+  typeName?: string;
+  isBooleanFlag: boolean;
+};
+type Parser<T, D extends boolean = false, V extends boolean = false> = {
+  _meta: ParserMeta;
+  parse: (val: string) => T | null;
+  serialize: (val: T) => string;
+  withAlias: (alias: string) => Parser<T, D, V>;
+  withDescription: (description: string) => Parser<T, D, V>;
+  withRequired: () => Parser<T, true, V>;
+  withDefault: (defaultValue: T) => Parser<T, true, V>;
+  positional: (index?: number) => Parser<T, true, V>;
+  variadic: () => Parser<T, D, true>;
+};
+//#endregion
+//#region src/command/types.d.ts
+type CommandMeta = {
+  name: string;
+  version?: string;
+  description?: string;
+};
+type ArgsRecord = Record<string, Parser<any, boolean, boolean>>;
+type CommandContext<T extends ArgsRecord> = {
+  args: InferArgs<T>;
+};
+type HelpConfig = {
+  header?: string;
+  examples?: string[];
+  render?: (command: CommandDef<any>, meta: CommandMeta) => string;
+};
+type InferArgs<T extends ArgsRecord> = { [K in keyof T]: T[K] extends Parser<infer V, infer D, infer IsVariadic> ? IsVariadic extends true ? V[] : D extends true ? V : V | null : never };
+type LazyCommandRef = {
+  description?: string;
+  load: () => Promise<{
+    default: CommandDef<any>;
+  }>;
+};
+type CommandRef = CommandDef<any> | (() => Promise<{
+  default: CommandDef<any>;
+}>) | LazyCommandRef;
+type CommandDef<T extends ArgsRecord> = {
+  meta: CommandMeta;
+  args?: T;
+  commands?: Record<string, CommandRef>;
+  help?: HelpConfig;
+  setup?: (context: CommandContext<T>) => void | Promise<void>;
+  run?: (context: CommandContext<T>) => unknown | Promise<unknown>;
+  cleanup?: (context: CommandContext<T>) => void | Promise<void>;
+  onError?: (error: unknown) => void | Promise<void>;
+};
+//#endregion
+//#region src/command/define.d.ts
+declare const defineCommand: <T extends ArgsRecord = ArgsRecord>(definition: CommandDef<T>) => CommandDef<T>;
+//#endregion
+//#region src/command/errors.d.ts
+declare class TermcraftError extends Error {
+  constructor(message: string);
+}
+declare class MissingArgError extends TermcraftError {
+  constructor(name: string, isPositional: boolean);
+}
+declare class InvalidValueError extends TermcraftError {
+  constructor(name: string, value: string, typeName: string, isPositional: boolean);
+}
+//#endregion
+//#region src/command/help.d.ts
+declare const renderHelp: <T extends ArgsRecord>(command: CommandDef<T>) => string;
+//#endregion
+//#region src/command/run.d.ts
+declare const runCommand: <T extends ArgsRecord>(command: CommandDef<T>, options: {
+  argv: string[];
+}) => Promise<void>;
+declare const routeAndRun: <T extends ArgsRecord>(command: CommandDef<T>, argv: string[]) => Promise<void>;
+declare const runMain: <T extends ArgsRecord>(command: CommandDef<T>) => Promise<void>;
+//#endregion
+//#region src/parsers/built-in.d.ts
+declare const parseAsString: Parser<string, false>;
+declare const parseAsInteger: Parser<number, false>;
+declare const parseAsFloat: Parser<number, false>;
+declare const parseAsBoolean: Parser<boolean, false>;
+declare const parseAsEnum: <const TValues extends readonly [string, ...string[]]>(values: TValues) => Parser<TValues[number], false>;
+//#endregion
+//#region src/parsers/create-parser.d.ts
+type ZodLikeSchema<T = unknown> = {
+  safeParse: (value: unknown) => {
+    success: true;
+    data: T;
+  } | {
+    success: false;
+  };
+};
+declare function createParser<T>(functions: ParserFunctions<T>, meta?: Partial<ParserMeta>): Parser<T, false>;
+declare function createParser<T>(schema: ZodLikeSchema<T>, meta?: Partial<ParserMeta>): Parser<T, false>;
+//#endregion
+export { type ArgsRecord, type CommandContext, type CommandDef, type CommandMeta, type CommandRef, type HelpConfig, type InferArgs, InvalidValueError, type LazyCommandRef, MissingArgError, type Parser, type ParserFunctions, type ParserMeta, TermcraftError, createParser, defineCommand, parseAsBoolean, parseAsEnum, parseAsFloat, parseAsInteger, parseAsString, renderHelp, routeAndRun, runCommand, runMain };

package/dist/index.mjs

@@ -0,0 +1,500 @@
+import { colors } from "./utils/color.mjs";
+import { parseArgs } from "node:util";
+//#region src/command/utils.ts
+const getOrderedPositionals = (args) => {
+	return Object.entries(args).filter(([, parser]) => parser._meta.isPositional).map(([name, parser], order) => ({
+		name,
+		parser,
+		order,
+		index: parser._meta.positionalIndex ?? Number.MAX_SAFE_INTEGER
+	})).sort((left, right) => {
+		if (left.index !== right.index) return left.index - right.index;
+		return left.order - right.order;
+	});
+};
+//#endregion
+//#region src/command/define.ts
+const validateArgs = (args) => {
+	const aliases = /* @__PURE__ */ new Map();
+	for (const [name, parser] of Object.entries(args)) {
+		const { alias } = parser._meta;
+		if (alias) {
+			const existing = aliases.get(alias);
+			if (existing) throw new Error(`Duplicate alias "${alias}" for arguments "${existing}" and "${name}".`);
+			aliases.set(alias, name);
+		}
+	}
+	const explicitIndices = /* @__PURE__ */ new Map();
+	for (const [name, parser] of Object.entries(args)) {
+		const positionalIndex = parser._meta.isPositional ? parser._meta.positionalIndex : void 0;
+		if (positionalIndex === void 0) continue;
+		const existing = explicitIndices.get(positionalIndex);
+		if (existing) throw new Error(`Duplicate positional index ${positionalIndex} for arguments "${existing}" and "${name}".`);
+		explicitIndices.set(positionalIndex, name);
+	}
+	const orderedPositionals = getOrderedPositionals(args);
+	const variadics = orderedPositionals.filter(({ parser }) => parser._meta.isVariadic);
+	if (variadics.length > 1) throw new Error("Only one variadic positional argument is allowed.");
+	const variadic = variadics[0];
+	if (variadic && orderedPositionals[orderedPositionals.length - 1]?.name !== variadic.name) throw new Error(`Variadic positional argument "${variadic.name}" must be the last positional argument.`);
+};
+const defineCommand = (definition) => {
+	if (definition.args) validateArgs(definition.args);
+	return definition;
+};
+//#endregion
+//#region src/command/errors.ts
+var TermcraftError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = new.target.name;
+	}
+};
+var MissingArgError = class extends TermcraftError {
+	constructor(name, isPositional) {
+		super(isPositional ? `Missing required argument: ${name}` : `Missing required option: --${name}`);
+	}
+};
+var InvalidValueError = class extends TermcraftError {
+	constructor(name, value, typeName, isPositional) {
+		super(`Invalid value for ${isPositional ? name : `--${name}`}: ${JSON.stringify(value)} (expected ${typeName})`);
+	}
+};
+//#endregion
+//#region src/command/help.ts
+const isPositionalRequired = (parser) => parser._meta.defaultValue === void 0;
+const isNamedOptionRequired = (parser) => {
+	return parser._meta.isRequired && parser._meta.defaultValue === void 0;
+};
+const formatPositionalUsage = (name, parser) => {
+	const displayName = parser._meta.isVariadic ? `${name}...` : name;
+	return isPositionalRequired(parser) ? `<${displayName}>` : `[${displayName}]`;
+};
+const formatOptionUsage = (name, parser) => {
+	return `--${name}${parser._meta.isBooleanFlag ? "" : ` <${parser._meta.typeName ?? "value"}>`}`;
+};
+const formatDefaultValue = (parser) => {
+	if (parser._meta.defaultValue === void 0) return null;
+	return parser.serialize(parser._meta.defaultValue);
+};
+const formatOptionLabel = (name, parser) => {
+	return `${parser._meta.alias ? `-${parser._meta.alias}, ` : ""}--${name}${parser._meta.isBooleanFlag ? "" : ` <${parser._meta.typeName ?? "value"}>`}`;
+};
+const formatOptionDescription = (parser) => {
+	const parts = [];
+	if (parser._meta.description) parts.push(parser._meta.description);
+	const defaultValue = formatDefaultValue(parser);
+	if (defaultValue !== null) parts.push(`(default: ${defaultValue})`);
+	return parts.join(" ");
+};
+const isLazyCommandRef$1 = (ref) => typeof ref === "object" && "load" in ref;
+const formatCommandDescription = (commandRef) => {
+	if (typeof commandRef === "function") return "";
+	if (isLazyCommandRef$1(commandRef)) return commandRef.description ?? "";
+	return commandRef.meta.description ?? "";
+};
+const renderSection = (title, lines) => {
+	if (lines.length === 0) return [];
+	return [colors.bold(colors.cyan(title)), ...lines];
+};
+const renderHelp = (command) => {
+	if (command.help?.render) return command.help.render(command, command.meta);
+	const args = command.args ?? {};
+	const argEntries = Object.entries(args);
+	const positionals = getOrderedPositionals(args);
+	const options = argEntries.filter(([, parser]) => !parser._meta.isPositional);
+	const requiredOptions = options.filter(([, parser]) => isNamedOptionRequired(parser));
+	const optionalOptions = options.filter(([, parser]) => !isNamedOptionRequired(parser));
+	const commandEntries = Object.entries(command.commands ?? {});
+	const sections = [];
+	const header = command.help?.header ?? colors.bold(command.meta.name);
+	sections.push(header);
+	if (command.meta.description) sections.push(command.meta.description);
+	const usage = [command.meta.name];
+	if (commandEntries.length > 0) usage.push("<command>");
+	usage.push(...requiredOptions.map(([name, parser]) => formatOptionUsage(name, parser)));
+	usage.push(...positionals.map(({ name, parser }) => formatPositionalUsage(name, parser)));
+	if (optionalOptions.length > 0) usage.push("[options]");
+	sections.push("", ...renderSection("USAGE", [`  ${usage.join(" ")}`]));
+	if (positionals.length > 0) {
+		const labels = positionals.map(({ name, parser }) => formatPositionalUsage(name, parser));
+		const maxLabelWidth = Math.max(...labels.map((l) => l.length));
+		sections.push("", ...renderSection("ARGUMENTS", positionals.map(({ parser }, i) => {
+			const description = formatOptionDescription(parser);
+			const label = labels[i];
+			return description ? `  ${label.padEnd(maxLabelWidth)}  ${description}` : `  ${label}`;
+		})));
+	}
+	{
+		const labels = options.map(([name, parser]) => formatOptionLabel(name, parser));
+		const implicitLabels = ["-h, --help"];
+		if (command.meta.version) implicitLabels.push("-v, --version");
+		const maxLabelWidth = Math.max(...labels.map((l) => l.length), ...implicitLabels.map((l) => l.length));
+		const optionLines = options.map(([, parser], i) => {
+			const description = formatOptionDescription(parser);
+			const label = labels[i];
+			return description ? `  ${label.padEnd(maxLabelWidth)}  ${description}` : `  ${label}`;
+		});
+		const implicitFlags = [`  ${"-h, --help".padEnd(maxLabelWidth)}  Show help`];
+		if (command.meta.version) implicitFlags.push(`  ${"-v, --version".padEnd(maxLabelWidth)}  Show version`);
+		sections.push("", ...renderSection("OPTIONS", [...optionLines, ...implicitFlags]));
+	}
+	if (commandEntries.length > 0) {
+		const names = commandEntries.map(([name]) => name);
+		const maxNameWidth = Math.max(...names.map((n) => n.length));
+		sections.push("", ...renderSection("COMMANDS", commandEntries.map(([name, commandRef]) => {
+			const description = formatCommandDescription(commandRef);
+			return description ? `  ${name.padEnd(maxNameWidth)}  ${description}` : `  ${name}`;
+		})));
+	}
+	if (command.help?.examples?.length) sections.push("", ...renderSection("EXAMPLES", command.help.examples.map((example) => `  ${colors.dim(example)}`)));
+	return sections.join("\n");
+};
+//#endregion
+//#region src/command/resolve-args.ts
+const parseValue = (name, parser, rawValue) => {
+	const parsed = parser.parse(rawValue);
+	if (parsed === null) throw new InvalidValueError(name, rawValue, parser._meta.typeName ?? "value", parser._meta.isPositional);
+	return parsed;
+};
+const resolveArgs = (args, argv) => {
+	const namedEntries = Object.entries(args).filter(([, parser]) => !parser._meta.isPositional);
+	const positionals = getOrderedPositionals(args);
+	const options = Object.fromEntries(namedEntries.map(([name, parser]) => {
+		return [name, {
+			type: parser._meta.isBooleanFlag ? "boolean" : "string",
+			...parser._meta.alias ? { short: parser._meta.alias } : {}
+		}];
+	}));
+	let parsedArgs;
+	try {
+		parsedArgs = parseArgs({
+			args: argv,
+			options,
+			allowPositionals: true,
+			strict: true
+		});
+	} catch (error) {
+		if (error instanceof Error) {
+			const missingValue = error.message.match(/^Option '(?:-[^,]+, )?--([^ ]+) <value>' argument missing$/);
+			if (missingValue) throw new MissingArgError(missingValue[1], false);
+			throw new TermcraftError(error.message);
+		}
+		throw error;
+	}
+	const resolved = {};
+	for (const [name, parser] of namedEntries) {
+		const rawValue = parsedArgs.values[name];
+		if (rawValue === void 0) {
+			if (parser._meta.defaultValue !== void 0) {
+				resolved[name] = parser._meta.defaultValue;
+				continue;
+			}
+			if (parser._meta.isRequired) throw new MissingArgError(name, false);
+			resolved[name] = null;
+			continue;
+		}
+		resolved[name] = parseValue(name, parser, String(rawValue));
+	}
+	let positionalOffset = 0;
+	for (const { name, parser } of positionals) {
+		if (parser._meta.isVariadic) {
+			const remaining = parsedArgs.positionals.slice(positionalOffset);
+			if (remaining.length === 0) {
+				if (parser._meta.defaultValue !== void 0) {
+					resolved[name] = parser._meta.defaultValue;
+					continue;
+				}
+				throw new MissingArgError(name, true);
+			}
+			resolved[name] = remaining.map((value) => parseValue(name, parser, value));
+			positionalOffset = parsedArgs.positionals.length;
+			continue;
+		}
+		const rawValue = parsedArgs.positionals[positionalOffset];
+		if (rawValue === void 0) {
+			if (parser._meta.defaultValue !== void 0) {
+				resolved[name] = parser._meta.defaultValue;
+				continue;
+			}
+			throw new MissingArgError(name, true);
+		}
+		resolved[name] = parseValue(name, parser, rawValue);
+		positionalOffset += 1;
+	}
+	const unexpectedArg = parsedArgs.positionals[positionalOffset];
+	if (unexpectedArg !== void 0) throw new TermcraftError(`Unexpected argument: ${unexpectedArg}`);
+	return resolved;
+};
+//#endregion
+//#region src/command/run.ts
+var SignalExitError = class extends Error {
+	constructor(code) {
+		super(`Process interrupted with exit code ${code}`);
+		this.code = code;
+		this.name = "SignalExitError";
+	}
+};
+let activeSignal = null;
+const formatError = (error) => {
+	if (error instanceof Error) return error.message;
+	return String(error);
+};
+const throwIfSignaled = () => {
+	const error = activeSignal?.error;
+	if (error) throw error;
+};
+const awaitWithSignal = async (value) => {
+	const signal = activeSignal;
+	if (!signal) return await value;
+	return await Promise.race([Promise.resolve(value), signal.promise.then((error) => {
+		throw error;
+	})]);
+};
+const isLazyCommandRef = (ref) => typeof ref === "object" && "load" in ref;
+const resolveCommandRef = async (commandRef) => {
+	if (typeof commandRef === "function") {
+		const module = await awaitWithSignal(commandRef());
+		throwIfSignaled();
+		return module.default;
+	}
+	if (isLazyCommandRef(commandRef)) {
+		const module = await awaitWithSignal(commandRef.load());
+		throwIfSignaled();
+		return module.default;
+	}
+	throwIfSignaled();
+	return commandRef;
+};
+const hasRequiredPositionalsForEmptyArgvHelp = (command) => {
+	const args = command.args;
+	if (!args) return false;
+	return Object.values(args).some((parser) => parser._meta.isPositional && parser._meta.defaultValue === void 0);
+};
+const runCommand = async (command, options) => {
+	const context = { args: command.args ? resolveArgs(command.args, options.argv) : {} };
+	let error;
+	try {
+		throwIfSignaled();
+		await awaitWithSignal(command.setup?.(context));
+		throwIfSignaled();
+		await awaitWithSignal(command.run?.(context));
+	} catch (caughtError) {
+		error = caughtError;
+	}
+	try {
+		await command.cleanup?.(context);
+		throwIfSignaled();
+	} catch (caughtError) {
+		if (caughtError instanceof SignalExitError || error === void 0) error = caughtError;
+	}
+	if (error === void 0) return;
+	if (error instanceof SignalExitError) throw error;
+	if (command.onError) {
+		await command.onError(error);
+		return;
+	}
+	throw error;
+};
+const routeAndRun = async (command, argv) => {
+	throwIfSignaled();
+	const [subcommandName, ...rest] = argv;
+	if (subcommandName && command.commands?.[subcommandName]) {
+		const subcommand = await resolveCommandRef(command.commands[subcommandName]);
+		throwIfSignaled();
+		await routeAndRun(subcommand, rest);
+		return;
+	}
+	if (Boolean(command.commands && Object.keys(command.commands).length > 0) && !subcommandName || !subcommandName && hasRequiredPositionalsForEmptyArgvHelp(command)) {
+		throwIfSignaled();
+		console.log(renderHelp(command));
+		return;
+	}
+	const dashDashIndex = argv.indexOf("--");
+	const flagsArgv = dashDashIndex === -1 ? argv : argv.slice(0, dashDashIndex);
+	if (flagsArgv.includes("--help") || flagsArgv.includes("-h")) {
+		throwIfSignaled();
+		console.log(renderHelp(command));
+		return;
+	}
+	if (flagsArgv.includes("--version") || flagsArgv.includes("-v")) {
+		throwIfSignaled();
+		console.log(command.meta.version ?? "");
+		return;
+	}
+	throwIfSignaled();
+	await runCommand(command, { argv });
+};
+const runMain = async (command) => {
+	const argv = process.argv.slice(2);
+	let exitCode = null;
+	let stderrOutput = null;
+	const onSigint = () => {
+		const signal = activeSignal;
+		if (signal && !signal.error) {
+			const error = new SignalExitError(130);
+			signal.error = error;
+			signal.resolve(error);
+		}
+	};
+	const onSigterm = () => {
+		const signal = activeSignal;
+		if (signal && !signal.error) {
+			const error = new SignalExitError(143);
+			signal.error = error;
+			signal.resolve(error);
+		}
+	};
+	const previousSignal = activeSignal;
+	activeSignal = {
+		...Promise.withResolvers(),
+		error: null
+	};
+	process.on("SIGINT", onSigint);
+	process.on("SIGTERM", onSigterm);
+	try {
+		await routeAndRun(command, argv);
+	} catch (error) {
+		if (error instanceof SignalExitError) exitCode = error.code;
+		else {
+			stderrOutput = `${formatError(error)}\n`;
+			exitCode = 1;
+		}
+	} finally {
+		process.off("SIGINT", onSigint);
+		process.off("SIGTERM", onSigterm);
+		activeSignal = previousSignal;
+	}
+	if (stderrOutput) process.stderr.write(stderrOutput);
+	if (exitCode !== null) process.exit(exitCode);
+};
+//#endregion
+//#region src/parsers/create-parser.ts
+const createParserMeta = (overrides = {}) => ({
+	isRequired: false,
+	isPositional: false,
+	isVariadic: false,
+	isBooleanFlag: false,
+	...overrides
+});
+const buildParser = (config) => {
+	const meta = createParserMeta(config.meta);
+	return {
+		_meta: meta,
+		parse: config.parse,
+		serialize: config.serialize,
+		withAlias: (alias) => buildParser({
+			...config,
+			meta: {
+				...meta,
+				alias
+			}
+		}),
+		withDescription: (description) => buildParser({
+			...config,
+			meta: {
+				...meta,
+				description
+			}
+		}),
+		withRequired: () => buildParser({
+			parse: config.parse,
+			serialize: config.serialize,
+			meta: {
+				...meta,
+				isRequired: true
+			}
+		}),
+		withDefault: (defaultValue) => buildParser({
+			parse: config.parse,
+			serialize: config.serialize,
+			meta: {
+				...meta,
+				defaultValue
+			}
+		}),
+		positional: (index) => buildParser({
+			parse: config.parse,
+			serialize: config.serialize,
+			meta: {
+				...meta,
+				isPositional: true,
+				positionalIndex: index
+			}
+		}),
+		variadic: () => buildParser({
+			...config,
+			meta: {
+				...meta,
+				isVariadic: true
+			}
+		})
+	};
+};
+function createParser(input, meta) {
+	if (typeof input === "object" && "parse" in input && "serialize" in input) {
+		const functions = input;
+		return buildParser({
+			parse: functions.parse,
+			serialize: functions.serialize,
+			meta
+		});
+	}
+	const schema = input;
+	return buildParser({
+		parse: (value) => {
+			const result = schema.safeParse(value);
+			return result.success ? result.data : null;
+		},
+		serialize: (value) => String(value),
+		meta
+	});
+}
+//#endregion
+//#region src/parsers/built-in.ts
+const parseAsString = createParser({
+	parse: (value) => value,
+	serialize: (value) => value
+}, { typeName: "string" });
+const parseAsInteger = createParser({
+	parse: (value) => {
+		if (value.trim() === "") return null;
+		const parsed = Number(value);
+		return Number.isInteger(parsed) ? parsed : null;
+	},
+	serialize: (value) => value.toString()
+}, { typeName: "integer" });
+const parseAsFloat = createParser({
+	parse: (value) => {
+		if (value.trim() === "") return null;
+		const parsed = Number(value);
+		return Number.isNaN(parsed) ? null : parsed;
+	},
+	serialize: (value) => value.toString()
+}, { typeName: "number" });
+const parseAsBoolean = createParser({
+	parse: (value) => {
+		const normalized = value.trim().toLowerCase();
+		if ([
+			"true",
+			"yes",
+			"1"
+		].includes(normalized)) return true;
+		if ([
+			"false",
+			"no",
+			"0"
+		].includes(normalized)) return false;
+		return null;
+	},
+	serialize: (value) => value.toString()
+}, {
+	typeName: "boolean",
+	isBooleanFlag: true
+});
+const parseAsEnum = (values) => createParser({
+	parse: (value) => values.includes(value) ? value : null,
+	serialize: (value) => value
+}, { typeName: values.join("|") });
+//#endregion
+export { InvalidValueError, MissingArgError, TermcraftError, createParser, defineCommand, parseAsBoolean, parseAsEnum, parseAsFloat, parseAsInteger, parseAsString, renderHelp, routeAndRun, runCommand, runMain };

package/dist/prompts/index.d.mts

@@ -0,0 +1,2 @@
+import { cancel, confirm, group, intro, isCancel, log, multiselect, note, outro, select, spinner, text } from "@clack/prompts";
+export { cancel, confirm, group, intro, isCancel, log, multiselect, note, outro, select, spinner, text };

package/dist/prompts/index.mjs

@@ -0,0 +1,2 @@
+import { cancel, confirm, group, intro, isCancel, log, multiselect, note, outro, select, spinner, text } from "@clack/prompts";
+export { cancel, confirm, group, intro, isCancel, log, multiselect, note, outro, select, spinner, text };

package/dist/utils/color.d.mts

@@ -0,0 +1,2 @@
+import colors from "picocolors";
+export { colors };

package/dist/utils/color.mjs

@@ -0,0 +1,2 @@
+import colors from "picocolors";
+export { colors };

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "termcraft",
+  "version": "0.1.0",
+  "description": "A type-safe CLI framework for Bun with declarative argument parsing, subcommands, and lifecycle hooks.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Mythie",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Mythie/termcraft.git"
+  },
+  "homepage": "https://github.com/Mythie/termcraft",
+  "bugs": "https://github.com/Mythie/termcraft/issues",
+  "keywords": [
+    "cli",
+    "command-line",
+    "framework",
+    "bun",
+    "typescript",
+    "parser",
+    "arguments"
+  ],
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./prompts": {
+      "types": "./dist/prompts/index.d.mts",
+      "import": "./dist/prompts/index.mjs"
+    },
+    "./banner": {
+      "types": "./dist/banner/index.d.mts",
+      "import": "./dist/banner/index.mjs"
+    },
+    "./colors": {
+      "types": "./dist/utils/color.d.mts",
+      "import": "./dist/utils/color.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "scripts": {
+    "build": "tsdown",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "check": "biome check . && tsc --noEmit",
+    "prepublishOnly": "bun run check && bun run build",
+    "prepare": "husky || true"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,jsx,json,css,md}": [
+      "biome check --write --no-errors-on-unmatched"
+    ]
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.1.0",
+    "figlet": "^1.11.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.7",
+    "@types/bun": "latest",
+    "@types/figlet": "^1.7.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.4",
+    "tsdown": "^0.21.2",
+    "typescript": "latest"
+  }
+}