hugo-extended 0.154.3 → 0.154.5

package/dist/hugo.d.mts

@@ -0,0 +1,240 @@
+import { HugoCommand, HugoOptionsFor } from "./generated/types.mjs";
+import { ENV_VAR_DOCS, HugoEnvConfig, getEnvConfig } from "./lib/env.mjs";
+
+//#region src/hugo.d.ts
+
+/**
+ * Gets the path to the Hugo binary, automatically installing it if it's missing.
+ *
+ * This is the main entry point for the hugo-extended package. It checks if Hugo
+ * is already installed and available, and if not, triggers an automatic installation
+ * before returning the binary path.
+ *
+ * This handles the case where Hugo may mysteriously disappear (see issue #81),
+ * ensuring the binary is always available when this function is called.
+ *
+ * Environment variables that affect behavior:
+ * - HUGO_BIN_PATH: Use a custom binary path (skips auto-install if missing)
+ *
+ * @returns A promise that resolves with the absolute path to the Hugo binary
+ * @throws {Error} If installation fails, the platform is unsupported, or custom binary is missing
+ *
+ * @example
+ * ```typescript
+ * import hugo from 'hugo-extended';
+ *
+ * const hugoPath = await hugo();
+ * console.log(hugoPath); // "/usr/local/bin/hugo" or "./bin/hugo"
+ * ```
+ */
+declare const getHugoBinary: () => Promise<string>;
+/**
+ * Execute a Hugo command with type-safe options.
+ *
+ * This function runs Hugo with the specified command and options, inheriting stdio
+ * so output goes directly to the console. It's perfect for interactive commands
+ * like `hugo server` or build commands where you want to see live output.
+ *
+ * @param command - Hugo command to execute (e.g., "server", "build", "mod clean")
+ * @param positionalArgsOrOptions - Either positional arguments array or options object
+ * @param options - Type-safe options object (if first param is positional args)
+ * @returns A promise that resolves when the command completes successfully
+ * @throws {Error} If the command fails or Hugo is not available
+ *
+ * @example
+ * ```typescript
+ * import { exec } from 'hugo-extended';
+ *
+ * // Start development server
+ * await exec("server", {
+ *   port: 1313,
+ *   buildDrafts: true,
+ *   baseURL: "http://localhost:1313"
+ * });
+ *
+ * // Create a new site
+ * await exec("new site", ["my-site"], { format: "yaml" });
+ *
+ * // Build site for production
+ * await exec("build", {
+ *   minify: true,
+ *   cleanDestinationDir: true
+ * });
+ * ```
+ */
+declare function exec<C extends HugoCommand>(command: C, positionalArgsOrOptions?: string[] | HugoOptionsFor<C>, options?: HugoOptionsFor<C>): Promise<void>;
+/**
+ * Execute a Hugo command and capture its output.
+ *
+ * This function runs Hugo with the specified command and options, capturing
+ * stdout and stderr. It's useful for commands where you need to process the
+ * output programmatically, like `hugo version` or `hugo list all`.
+ *
+ * @param command - Hugo command to execute (e.g., "version", "list all")
+ * @param positionalArgsOrOptions - Either positional arguments array or options object
+ * @param options - Type-safe options object (if first param is positional args)
+ * @returns A promise that resolves with stdout and stderr strings
+ * @throws {Error} If the command fails or Hugo is not available
+ *
+ * @example
+ * ```typescript
+ * import { execWithOutput } from 'hugo-extended';
+ *
+ * // Get Hugo version
+ * const { stdout } = await execWithOutput("version");
+ * console.log(stdout); // "hugo v0.154.3+extended ..."
+ *
+ * // List all content
+ * const { stdout: content } = await execWithOutput("list all");
+ * const pages = content.split('\n');
+ * ```
+ */
+declare function execWithOutput<C extends HugoCommand>(command: C, positionalArgsOrOptions?: string[] | HugoOptionsFor<C>, options?: HugoOptionsFor<C>): Promise<{
+  stdout: string;
+  stderr: string;
+}>;
+/**
+ * Builder-style API for executing Hugo commands.
+ *
+ * Provides a fluent interface where each Hugo command is a method on the
+ * builder object. All methods are type-safe with autocomplete for options.
+ *
+ * @example
+ * ```typescript
+ * import { hugo } from 'hugo-extended';
+ *
+ * // Start server
+ * await hugo.server({ port: 1313, buildDrafts: true });
+ *
+ * // Build site
+ * await hugo.build({ minify: true });
+ *
+ * // Module operations
+ * await hugo.mod.clean({ all: true });
+ * await hugo.mod.get();
+ * ```
+ */
+declare const hugo: {
+  /** Build your site */
+  build: (options?: HugoOptionsFor<"build">) => Promise<void>;
+  /** Generate shell completion scripts */
+  completion: {
+    bash: (options?: HugoOptionsFor<"completion bash">) => Promise<void>;
+    fish: (options?: HugoOptionsFor<"completion fish">) => Promise<void>;
+    powershell: (options?: HugoOptionsFor<"completion powershell">) => Promise<void>;
+    zsh: (options?: HugoOptionsFor<"completion zsh">) => Promise<void>;
+  };
+  /** Print Hugo configuration */
+  config: (options?: HugoOptionsFor<"config">) => Promise<void>;
+  /** Convert content to different formats */
+  convert: {
+    toJSON: (options?: HugoOptionsFor<"convert toJSON">) => Promise<void>;
+    toTOML: (options?: HugoOptionsFor<"convert toTOML">) => Promise<void>;
+    toYAML: (options?: HugoOptionsFor<"convert toYAML">) => Promise<void>;
+  };
+  /** Print Hugo environment info */
+  env: (options?: HugoOptionsFor<"env">) => Promise<void>;
+  /** Generate documentation */
+  gen: {
+    doc: (options?: HugoOptionsFor<"gen doc">) => Promise<void>;
+    man: (options?: HugoOptionsFor<"gen man">) => Promise<void>;
+  };
+  /** Import your site from others */
+  import: {
+    jekyll: (options?: HugoOptionsFor<"import jekyll">) => Promise<void>;
+  };
+  /** List various types of content */
+  list: {
+    all: (options?: HugoOptionsFor<"list all">) => Promise<void>;
+    drafts: (options?: HugoOptionsFor<"list drafts">) => Promise<void>;
+    expired: (options?: HugoOptionsFor<"list expired">) => Promise<void>;
+    future: (options?: HugoOptionsFor<"list future">) => Promise<void>;
+    published: (options?: HugoOptionsFor<"list published">) => Promise<void>;
+  };
+  /** Module operations */
+  mod: {
+    clean: (options?: HugoOptionsFor<"mod clean">) => Promise<void>;
+    get: (options?: HugoOptionsFor<"mod get">) => Promise<void>;
+    graph: (options?: HugoOptionsFor<"mod graph">) => Promise<void>;
+    init: (options?: HugoOptionsFor<"mod init">) => Promise<void>;
+    npm: {
+      pack: (options?: HugoOptionsFor<"mod npm pack">) => Promise<void>;
+    };
+    tidy: (options?: HugoOptionsFor<"mod tidy">) => Promise<void>;
+    vendor: (options?: HugoOptionsFor<"mod vendor">) => Promise<void>;
+    verify: (options?: HugoOptionsFor<"mod verify">) => Promise<void>;
+  };
+  /** Create new content */
+  new: ((pathOrOptions?: string | HugoOptionsFor<"new">, options?: HugoOptionsFor<"new">) => Promise<void>) & {
+    content: (pathOrOptions?: string | HugoOptionsFor<"new content">, options?: HugoOptionsFor<"new content">) => Promise<void>;
+    site: (pathOrOptions?: string | HugoOptionsFor<"new site">, options?: HugoOptionsFor<"new site">) => Promise<void>;
+    theme: (nameOrOptions?: string | HugoOptionsFor<"new theme">, options?: HugoOptionsFor<"new theme">) => Promise<void>;
+  };
+  /** Start the Hugo development server */
+  server: (options?: HugoOptionsFor<"server">) => Promise<void>;
+  /** Print the Hugo version */
+  version: (options?: HugoOptionsFor<"version">) => Promise<void>;
+};
+declare const _default: (() => Promise<string>) & {
+  /** Build your site */
+  build: (options?: HugoOptionsFor<"build">) => Promise<void>;
+  /** Generate shell completion scripts */
+  completion: {
+    bash: (options?: HugoOptionsFor<"completion bash">) => Promise<void>;
+    fish: (options?: HugoOptionsFor<"completion fish">) => Promise<void>;
+    powershell: (options?: HugoOptionsFor<"completion powershell">) => Promise<void>;
+    zsh: (options?: HugoOptionsFor<"completion zsh">) => Promise<void>;
+  };
+  /** Print Hugo configuration */
+  config: (options?: HugoOptionsFor<"config">) => Promise<void>;
+  /** Convert content to different formats */
+  convert: {
+    toJSON: (options?: HugoOptionsFor<"convert toJSON">) => Promise<void>;
+    toTOML: (options?: HugoOptionsFor<"convert toTOML">) => Promise<void>;
+    toYAML: (options?: HugoOptionsFor<"convert toYAML">) => Promise<void>;
+  };
+  /** Print Hugo environment info */
+  env: (options?: HugoOptionsFor<"env">) => Promise<void>;
+  /** Generate documentation */
+  gen: {
+    doc: (options?: HugoOptionsFor<"gen doc">) => Promise<void>;
+    man: (options?: HugoOptionsFor<"gen man">) => Promise<void>;
+  };
+  /** Import your site from others */
+  import: {
+    jekyll: (options?: HugoOptionsFor<"import jekyll">) => Promise<void>;
+  };
+  /** List various types of content */
+  list: {
+    all: (options?: HugoOptionsFor<"list all">) => Promise<void>;
+    drafts: (options?: HugoOptionsFor<"list drafts">) => Promise<void>;
+    expired: (options?: HugoOptionsFor<"list expired">) => Promise<void>;
+    future: (options?: HugoOptionsFor<"list future">) => Promise<void>;
+    published: (options?: HugoOptionsFor<"list published">) => Promise<void>;
+  };
+  /** Module operations */
+  mod: {
+    clean: (options?: HugoOptionsFor<"mod clean">) => Promise<void>;
+    get: (options?: HugoOptionsFor<"mod get">) => Promise<void>;
+    graph: (options?: HugoOptionsFor<"mod graph">) => Promise<void>;
+    init: (options?: HugoOptionsFor<"mod init">) => Promise<void>;
+    npm: {
+      pack: (options?: HugoOptionsFor<"mod npm pack">) => Promise<void>;
+    };
+    tidy: (options?: HugoOptionsFor<"mod tidy">) => Promise<void>;
+    vendor: (options?: HugoOptionsFor<"mod vendor">) => Promise<void>;
+    verify: (options?: HugoOptionsFor<"mod verify">) => Promise<void>;
+  };
+  /** Create new content */
+  new: ((pathOrOptions?: string | HugoOptionsFor<"new">, options?: HugoOptionsFor<"new">) => Promise<void>) & {
+    content: (pathOrOptions?: string | HugoOptionsFor<"new content">, options?: HugoOptionsFor<"new content">) => Promise<void>;
+    site: (pathOrOptions?: string | HugoOptionsFor<"new site">, options?: HugoOptionsFor<"new site">) => Promise<void>;
+    theme: (nameOrOptions?: string | HugoOptionsFor<"new theme">, options?: HugoOptionsFor<"new theme">) => Promise<void>;
+  };
+  /** Start the Hugo development server */
+  server: (options?: HugoOptionsFor<"server">) => Promise<void>;
+  /** Print the Hugo version */
+  version: (options?: HugoOptionsFor<"version">) => Promise<void>;
+};
+//#endregion
+export { ENV_VAR_DOCS, type HugoCommand, type HugoEnvConfig, type HugoOptionsFor, _default as default, exec, execWithOutput, getEnvConfig, getHugoBinary, hugo };

package/dist/hugo.mjs

@@ -0,0 +1,246 @@
+import { buildArgs } from "./lib/args.mjs";
+import { ENV_VAR_DOCS, getEnvConfig } from "./lib/env.mjs";
+import { doesBinExist, getBinPath, logger } from "./lib/utils.mjs";
+import install_default from "./lib/install.mjs";
+import { spawn } from "node:child_process";
+
+//#region src/hugo.ts
+/**
+* Gets the path to the Hugo binary, automatically installing it if it's missing.
+*
+* This is the main entry point for the hugo-extended package. It checks if Hugo
+* is already installed and available, and if not, triggers an automatic installation
+* before returning the binary path.
+*
+* This handles the case where Hugo may mysteriously disappear (see issue #81),
+* ensuring the binary is always available when this function is called.
+*
+* Environment variables that affect behavior:
+* - HUGO_BIN_PATH: Use a custom binary path (skips auto-install if missing)
+*
+* @returns A promise that resolves with the absolute path to the Hugo binary
+* @throws {Error} If installation fails, the platform is unsupported, or custom binary is missing
+*
+* @example
+* ```typescript
+* import hugo from 'hugo-extended';
+*
+* const hugoPath = await hugo();
+* console.log(hugoPath); // "/usr/local/bin/hugo" or "./bin/hugo"
+* ```
+*/
+const getHugoBinary = async () => {
+	const envConfig = getEnvConfig();
+	const bin = getBinPath();
+	if (envConfig.binPath) {
+		if (!doesBinExist(bin)) throw new Error(`Custom Hugo binary not found at HUGO_BIN_PATH: ${bin}`);
+		return bin;
+	}
+	if (!doesBinExist(bin)) {
+		logger.warn("Hugo is missing, reinstalling now...");
+		await install_default();
+	}
+	return bin;
+};
+/**
+* Execute a Hugo command with type-safe options.
+*
+* This function runs Hugo with the specified command and options, inheriting stdio
+* so output goes directly to the console. It's perfect for interactive commands
+* like `hugo server` or build commands where you want to see live output.
+*
+* @param command - Hugo command to execute (e.g., "server", "build", "mod clean")
+* @param positionalArgsOrOptions - Either positional arguments array or options object
+* @param options - Type-safe options object (if first param is positional args)
+* @returns A promise that resolves when the command completes successfully
+* @throws {Error} If the command fails or Hugo is not available
+*
+* @example
+* ```typescript
+* import { exec } from 'hugo-extended';
+*
+* // Start development server
+* await exec("server", {
+*   port: 1313,
+*   buildDrafts: true,
+*   baseURL: "http://localhost:1313"
+* });
+*
+* // Create a new site
+* await exec("new site", ["my-site"], { format: "yaml" });
+*
+* // Build site for production
+* await exec("build", {
+*   minify: true,
+*   cleanDestinationDir: true
+* });
+* ```
+*/
+async function exec(command, positionalArgsOrOptions, options) {
+	const bin = await getHugoBinary();
+	let positionalArgs;
+	let opts;
+	if (Array.isArray(positionalArgsOrOptions)) {
+		positionalArgs = positionalArgsOrOptions;
+		opts = options;
+	} else {
+		positionalArgs = void 0;
+		opts = positionalArgsOrOptions;
+	}
+	const args = buildArgs(command, positionalArgs, opts);
+	return new Promise((resolve, reject) => {
+		const child = spawn(bin, args, { stdio: "inherit" });
+		child.on("exit", (code) => {
+			if (code === 0 || code === null) resolve();
+			else reject(/* @__PURE__ */ new Error(`Hugo command failed with exit code ${code}`));
+		});
+		child.on("error", (err) => {
+			reject(err);
+		});
+	});
+}
+/**
+* Execute a Hugo command and capture its output.
+*
+* This function runs Hugo with the specified command and options, capturing
+* stdout and stderr. It's useful for commands where you need to process the
+* output programmatically, like `hugo version` or `hugo list all`.
+*
+* @param command - Hugo command to execute (e.g., "version", "list all")
+* @param positionalArgsOrOptions - Either positional arguments array or options object
+* @param options - Type-safe options object (if first param is positional args)
+* @returns A promise that resolves with stdout and stderr strings
+* @throws {Error} If the command fails or Hugo is not available
+*
+* @example
+* ```typescript
+* import { execWithOutput } from 'hugo-extended';
+*
+* // Get Hugo version
+* const { stdout } = await execWithOutput("version");
+* console.log(stdout); // "hugo v0.154.3+extended ..."
+*
+* // List all content
+* const { stdout: content } = await execWithOutput("list all");
+* const pages = content.split('\n');
+* ```
+*/
+async function execWithOutput(command, positionalArgsOrOptions, options) {
+	const bin = await getHugoBinary();
+	let positionalArgs;
+	let opts;
+	if (Array.isArray(positionalArgsOrOptions)) {
+		positionalArgs = positionalArgsOrOptions;
+		opts = options;
+	} else {
+		positionalArgs = void 0;
+		opts = positionalArgsOrOptions;
+	}
+	const args = buildArgs(command, positionalArgs, opts);
+	return new Promise((resolve, reject) => {
+		const stdoutChunks = [];
+		const stderrChunks = [];
+		const child = spawn(bin, args);
+		if (child.stdout) child.stdout.on("data", (chunk) => {
+			stdoutChunks.push(chunk);
+		});
+		if (child.stderr) child.stderr.on("data", (chunk) => {
+			stderrChunks.push(chunk);
+		});
+		child.on("exit", (code) => {
+			const stdout = Buffer.concat(stdoutChunks).toString("utf8");
+			const stderr = Buffer.concat(stderrChunks).toString("utf8");
+			if (code === 0 || code === null) resolve({
+				stdout,
+				stderr
+			});
+			else reject(/* @__PURE__ */ new Error(`Hugo command failed with exit code ${code}${stderr ? `\n${stderr}` : ""}`));
+		});
+		child.on("error", (err) => {
+			reject(err);
+		});
+	});
+}
+/**
+* Builder-style API for executing Hugo commands.
+*
+* Provides a fluent interface where each Hugo command is a method on the
+* builder object. All methods are type-safe with autocomplete for options.
+*
+* @example
+* ```typescript
+* import { hugo } from 'hugo-extended';
+*
+* // Start server
+* await hugo.server({ port: 1313, buildDrafts: true });
+*
+* // Build site
+* await hugo.build({ minify: true });
+*
+* // Module operations
+* await hugo.mod.clean({ all: true });
+* await hugo.mod.get();
+* ```
+*/
+const hugo = {
+	build: (options) => exec("build", options),
+	completion: {
+		bash: (options) => exec("completion bash", options),
+		fish: (options) => exec("completion fish", options),
+		powershell: (options) => exec("completion powershell", options),
+		zsh: (options) => exec("completion zsh", options)
+	},
+	config: (options) => exec("config", options),
+	convert: {
+		toJSON: (options) => exec("convert toJSON", options),
+		toTOML: (options) => exec("convert toTOML", options),
+		toYAML: (options) => exec("convert toYAML", options)
+	},
+	env: (options) => exec("env", options),
+	gen: {
+		doc: (options) => exec("gen doc", options),
+		man: (options) => exec("gen man", options)
+	},
+	import: { jekyll: (options) => exec("import jekyll", options) },
+	list: {
+		all: (options) => exec("list all", options),
+		drafts: (options) => exec("list drafts", options),
+		expired: (options) => exec("list expired", options),
+		future: (options) => exec("list future", options),
+		published: (options) => exec("list published", options)
+	},
+	mod: {
+		clean: (options) => exec("mod clean", options),
+		get: (options) => exec("mod get", options),
+		graph: (options) => exec("mod graph", options),
+		init: (options) => exec("mod init", options),
+		npm: { pack: (options) => exec("mod npm pack", options) },
+		tidy: (options) => exec("mod tidy", options),
+		vendor: (options) => exec("mod vendor", options),
+		verify: (options) => exec("mod verify", options)
+	},
+	new: Object.assign((pathOrOptions, options) => {
+		if (typeof pathOrOptions === "string") return exec("new", [pathOrOptions], options);
+		return exec("new", pathOrOptions);
+	}, {
+		content: (pathOrOptions, options) => {
+			if (typeof pathOrOptions === "string") return exec("new content", [pathOrOptions], options);
+			return exec("new content", pathOrOptions);
+		},
+		site: (pathOrOptions, options) => {
+			if (typeof pathOrOptions === "string") return exec("new site", [pathOrOptions], options);
+			return exec("new site", pathOrOptions);
+		},
+		theme: (nameOrOptions, options) => {
+			if (typeof nameOrOptions === "string") return exec("new theme", [nameOrOptions], options);
+			return exec("new theme", nameOrOptions);
+		}
+	}),
+	server: (options) => exec("server", options),
+	version: (options) => exec("version", options)
+};
+const hugoCompat = getHugoBinary;
+var hugo_default = Object.assign(hugoCompat, hugo);
+
+//#endregion
+export { ENV_VAR_DOCS, hugo_default as default, exec, execWithOutput, getEnvConfig, getHugoBinary, hugo };

package/dist/lib/args.d.mts

@@ -0,0 +1,30 @@
+//#region src/lib/args.d.ts
+/**
+ * Build command-line arguments from a command and options object.
+ *
+ * This function:
+ * 1. Loads the Hugo spec to understand flag types
+ * 2. Converts camelCase property names to kebab-case flags
+ * 3. Formats values according to their types (boolean, string, number, arrays)
+ * 4. Returns an argv array ready to pass to child_process
+ *
+ * @param command - Hugo command string (e.g., "server", "build", "mod clean").
+ * @param positionalArgs - Optional array of positional arguments (e.g., paths, names).
+ * @param options - Options object with camelCase property names.
+ * @returns Array of command-line arguments.
+ *
+ * @example
+ * buildArgs("server", undefined, { port: 1313, buildDrafts: true })
+ * // Returns: ["server", "--port", "1313", "--build-drafts"]
+ *
+ * @example
+ * buildArgs("new site", ["my-site"], { format: "yaml" })
+ * // Returns: ["new", "site", "my-site", "--format", "yaml"]
+ *
+ * @example
+ * buildArgs("build", undefined, { theme: ["a", "b"], minify: true })
+ * // Returns: ["build", "--theme", "a", "--theme", "b", "--minify"]
+ */
+declare function buildArgs(command: string, positionalArgs?: string[], options?: Record<string, unknown>): string[];
+//#endregion
+export { buildArgs };

package/dist/lib/args.mjs

@@ -0,0 +1,126 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+//#region src/lib/args.ts
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+let cachedSpec = null;
+/**
+* Load the Hugo spec from the generated json file (cached after first load).
+*
+* @returns The parsed Hugo spec containing global flags and command-specific flags.
+*/
+function loadSpec() {
+	if (cachedSpec) return cachedSpec;
+	const specPath = path.join(__dirname, "..", "generated", "flags.json");
+	try {
+		const specText = fs.readFileSync(specPath, "utf8");
+		cachedSpec = JSON.parse(specText);
+	} catch (error) {
+		throw new Error(`Failed to load Hugo spec from ${specPath}. Ensure the project is built (npm run build) before use.`, { cause: error });
+	}
+	return cachedSpec;
+}
+/**
+* Convert a camelCase property name to kebab-case flag name.
+*
+* @param name - Property name in camelCase (e.g., "buildDrafts").
+* @returns Kebab-case flag name (e.g., "build-drafts").
+*
+* @example
+* camelToKebab("baseURL") // "base-u-r-l"
+* camelToKebab("buildDrafts") // "build-drafts"
+*/
+function camelToKebab(name) {
+	return name.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+}
+/**
+* Find a flag spec by its camelCase property name.
+*
+* @param flags - Array of flag specs to search.
+* @param propName - Property name in camelCase.
+* @returns The matching flag spec, or undefined if not found.
+*/
+function findFlag(flags, propName) {
+	const kebab = camelToKebab(propName);
+	return flags.find((f) => {
+		const flagName = f.long.startsWith("--") ? f.long.slice(2) : f.long;
+		return flagName === kebab || flagName === propName;
+	});
+}
+/**
+* Build command-line arguments from a command and options object.
+*
+* This function:
+* 1. Loads the Hugo spec to understand flag types
+* 2. Converts camelCase property names to kebab-case flags
+* 3. Formats values according to their types (boolean, string, number, arrays)
+* 4. Returns an argv array ready to pass to child_process
+*
+* @param command - Hugo command string (e.g., "server", "build", "mod clean").
+* @param positionalArgs - Optional array of positional arguments (e.g., paths, names).
+* @param options - Options object with camelCase property names.
+* @returns Array of command-line arguments.
+*
+* @example
+* buildArgs("server", undefined, { port: 1313, buildDrafts: true })
+* // Returns: ["server", "--port", "1313", "--build-drafts"]
+*
+* @example
+* buildArgs("new site", ["my-site"], { format: "yaml" })
+* // Returns: ["new", "site", "my-site", "--format", "yaml"]
+*
+* @example
+* buildArgs("build", undefined, { theme: ["a", "b"], minify: true })
+* // Returns: ["build", "--theme", "a", "--theme", "b", "--minify"]
+*/
+function buildArgs(command, positionalArgs, options) {
+	const spec = loadSpec();
+	const args = [];
+	args.push(...command.split(" "));
+	if (positionalArgs && positionalArgs.length > 0) args.push(...positionalArgs);
+	if (!options || Object.keys(options).length === 0) return args;
+	const cmdSpec = spec.commands.find((c) => c.command === command);
+	const allFlags = [...spec.globalFlags, ...cmdSpec?.flags ?? []];
+	for (const [key, value] of Object.entries(options)) {
+		if (value === void 0 || value === null) continue;
+		const flagSpec = findFlag(allFlags, key);
+		const flagName = flagSpec ? flagSpec.long.startsWith("--") ? flagSpec.long : `--${flagSpec.long}` : `--${camelToKebab(key)}`;
+		switch (flagSpec?.kind ?? inferKind(value)) {
+			case "boolean":
+				if (value === true) args.push(flagName);
+				break;
+			case "string":
+				args.push(flagName, String(value));
+				break;
+			case "number":
+				args.push(flagName, String(value));
+				break;
+			case "string[]":
+				if (Array.isArray(value)) for (const item of value) args.push(flagName, String(item));
+				break;
+			case "number[]":
+				if (Array.isArray(value)) for (const item of value) args.push(flagName, String(item));
+				break;
+		}
+	}
+	return args;
+}
+/**
+* Infer the kind of a value when we don't have spec information.
+*
+* @param value - The value to inspect.
+* @returns The inferred flag kind.
+*/
+function inferKind(value) {
+	if (typeof value === "boolean") return "boolean";
+	if (typeof value === "number") return "number";
+	if (Array.isArray(value)) {
+		if (value.length > 0 && typeof value[0] === "number") return "number[]";
+		return "string[]";
+	}
+	return "string";
+}
+
+//#endregion
+export { buildArgs };