@kidd-cli/core 0.1.1 → 0.2.0

package/dist/{config-BvGapuFJ.js → config-Db_sjFU-.js}

@@ -1,9 +1,10 @@
-import { i as findProjectRoot } from "./project-NPtYX2ZX.js";
+import { i as findProjectRoot } from "./project-DuXgjaa_.js";
 import { dirname, extname, join } from "node:path";
 import { attempt, attemptAsync, err, match } from "@kidd-cli/utils/fp";
 import { jsonParse, jsonStringify } from "@kidd-cli/utils/json";
-import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { formatZodIssues } from "@kidd-cli/utils/validate";
+import { fileExists } from "@kidd-cli/utils/fs";
 import { parse, printParseErrorCode } from "jsonc-parser";
 import { parse as parse$1, stringify } from "yaml";
 
@@ -37,33 +38,6 @@ function getConfigFileNames(name) {
 	return CONFIG_EXTENSIONS.map((ext) => `.${name}${ext}`);
 }
 /**
-* Check whether a file exists at the given path.
-*
-* @param filePath - The absolute file path to check.
-* @returns True when the file exists and is accessible.
-*/
-async function fileExists(filePath) {
-	const [error] = await attemptAsync(() => access(filePath));
-	return !error;
-}
-/**
-* Search a single directory for the first matching config file name.
-*
-* Checks each candidate file name in order and returns the path of the first
-* one that exists on disk.
-*
-* @param dir - The directory to search in.
-* @param fileNames - Candidate config file names to look for.
-* @returns The full path to the first matching config file, or null if none found.
-*/
-async function findConfigFile(dir, fileNames) {
-	return (await Promise.all(fileNames.map(async (fileName) => {
-		const filePath = join(dir, fileName);
-		if (await fileExists(filePath)) return filePath;
-		return null;
-	}))).find((result) => result !== null) ?? null;
-}
-/**
 * Search for a config file across multiple directories.
 *
 * Searches in order: explicit search paths, the current working directory,
@@ -88,6 +62,24 @@ async function findConfig(options) {
 	}
 	return null;
 }
+/**
+* Search a single directory for the first matching config file name.
+*
+* Checks each candidate file name in order and returns the path of the first
+* one that exists on disk.
+*
+* @param dir - The directory to search in.
+* @param fileNames - Candidate config file names to look for.
+* @returns The full path to the first matching config file, or null if none found.
+* @private
+*/
+async function findConfigFile(dir, fileNames) {
+	return (await Promise.all(fileNames.map(async (fileName) => {
+		const filePath = join(dir, fileName);
+		if (await fileExists(filePath)) return filePath;
+		return null;
+	}))).find((result) => result !== null) ?? null;
+}
 
 //#endregion
 //#region src/lib/config/parse.ts
@@ -101,11 +93,47 @@ function getFormat(filePath) {
 	return match(extname(filePath)).with(".jsonc", () => "jsonc").with(".yaml", () => "yaml").otherwise(() => "json");
 }
 /**
+* Parse config file content using the appropriate parser for the given format.
+*
+* @param options - Parse content options.
+* @returns A ConfigOperationResult with the parsed data or an error.
+*/
+function parseContent(options) {
+	const { content, filePath, format } = options;
+	return match(format).with("json", () => parseJson(content, filePath)).with("jsonc", () => parseJsoncContent(content, filePath)).with("yaml", () => parseYamlContent(content, filePath)).exhaustive();
+}
+/**
+* Serialize data to a string in the specified config format.
+*
+* @param data - The data to serialize.
+* @param format - The target config format.
+* @returns The serialized string representation.
+*/
+function serializeContent(data, format) {
+	return match(format).with("json", () => {
+		const [, json] = jsonStringify(data, { pretty: true });
+		return `${json}\n`;
+	}).with("jsonc", () => {
+		const [, json] = jsonStringify(data, { pretty: true });
+		return `${json}\n`;
+	}).with("yaml", () => stringify(data)).exhaustive();
+}
+/**
+* Get the file extension string for a given config format.
+*
+* @param format - The config format.
+* @returns The file extension including the leading dot (e.g. '.json').
+*/
+function getExtension(format) {
+	return match(format).with("json", () => ".json").with("jsonc", () => ".jsonc").with("yaml", () => ".yaml").exhaustive();
+}
+/**
 * Parse a JSON string and return the result as a ConfigOperationResult.
 *
 * @param content - The raw JSON string to parse.
 * @param filePath - The file path used in error messages.
 * @returns A ConfigOperationResult with the parsed data or a parse error.
+* @private
 */
 function parseJson(content, filePath) {
 	const [error, result] = jsonParse(content);
@@ -118,6 +146,7 @@ function parseJson(content, filePath) {
 * @param content - The raw JSONC string to parse.
 * @param filePath - The file path used in error messages.
 * @returns A ConfigOperationResult with the parsed data or a parse error.
+* @private
 */
 function parseJsoncContent(content, filePath) {
 	const errors = [];
@@ -134,47 +163,13 @@ function parseJsoncContent(content, filePath) {
 * @param content - The raw YAML string to parse.
 * @param filePath - The file path used in error messages.
 * @returns A ConfigOperationResult with the parsed data or a parse error.
+* @private
 */
 function parseYamlContent(content, filePath) {
 	const [error, result] = attempt(() => parse$1(content));
 	if (error) return err(`Failed to parse YAML in ${filePath}: ${String(error)}`);
 	return [null, result];
 }
-/**
-* Parse config file content using the appropriate parser for the given format.
-*
-* @param options - Parse content options.
-* @returns A ConfigOperationResult with the parsed data or an error.
-*/
-function parseContent(options) {
-	const { content, filePath, format } = options;
-	return match(format).with("json", () => parseJson(content, filePath)).with("jsonc", () => parseJsoncContent(content, filePath)).with("yaml", () => parseYamlContent(content, filePath)).exhaustive();
-}
-/**
-* Serialize data to a string in the specified config format.
-*
-* @param data - The data to serialize.
-* @param format - The target config format.
-* @returns The serialized string representation.
-*/
-function serializeContent(data, format) {
-	return match(format).with("json", () => {
-		const [, json] = jsonStringify(data, { pretty: true });
-		return `${json}\n`;
-	}).with("jsonc", () => {
-		const [, json] = jsonStringify(data, { pretty: true });
-		return `${json}\n`;
-	}).with("yaml", () => stringify(data)).exhaustive();
-}
-/**
-* Get the file extension string for a given config format.
-*
-* @param format - The config format.
-* @returns The file extension including the leading dot (e.g. '.json').
-*/
-function getExtension(format) {
-	return match(format).with("json", () => ".json").with("jsonc", () => ".jsonc").with("yaml", () => ".yaml").exhaustive();
-}
 
 //#endregion
 //#region src/lib/config/create-config.ts
@@ -279,4 +274,4 @@ function resolveReadErrorDetail(readError) {
 
 //#endregion
 export { DEFAULT_EXIT_CODE as n, createConfigClient as t };
-//# sourceMappingURL=config-BvGapuFJ.js.map
+//# sourceMappingURL=config-Db_sjFU-.js.map

package/dist/config-Db_sjFU-.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-Db_sjFU-.js","names":["stringifyYaml","parseJsonc","parseYaml"],"sources":["../src/utils/constants.ts","../src/lib/config/constants.ts","../src/lib/config/find.ts","../src/lib/config/parse.ts","../src/lib/config/create-config.ts"],"sourcesContent":["/**\n * Standard JSON indentation level used across the package.\n */\nexport const JSON_INDENT = 2\n\n/**\n * Default process exit code for error conditions.\n */\nexport const DEFAULT_EXIT_CODE = 1\n","/**\n * Supported configuration file formats.\n */\nexport type ConfigFormat = 'json' | 'jsonc' | 'yaml'\n\nexport { JSON_INDENT } from '@/utils/constants.js'\nexport const EMPTY_LENGTH = 0\nexport const CONFIG_EXTENSIONS = ['.jsonc', '.json', '.yaml'] as const\n","import { join } from 'node:path'\n\nimport { fileExists } from '@kidd-cli/utils/fs'\n\nimport { findProjectRoot } from '@/lib/project/index.js'\n\nimport { CONFIG_EXTENSIONS } from './constants.js'\n\n/**\n * Generate the list of config file names to search for based on the CLI name.\n *\n * Produces names like `.myapp.jsonc`, `.myapp.json`, `.myapp.yaml` from the\n * supported extension list.\n *\n * @param name - The CLI name used to derive config file names.\n * @returns An array of config file names to search for.\n */\nexport function getConfigFileNames(name: string): string[] {\n  return CONFIG_EXTENSIONS.map((ext) => `.${name}${ext}`)\n}\n\n/**\n * Search for a config file across multiple directories.\n *\n * Searches in order: explicit search paths, the current working directory,\n * and the project root (if different from cwd). Returns the path of the\n * first matching file found.\n *\n * @param options - Search options including cwd, file names, and optional search paths.\n * @returns The full path to the config file, or null if not found.\n */\nexport async function findConfig(options: {\n  cwd: string\n  fileNames: string[]\n  searchPaths?: string[]\n}): Promise<string | null> {\n  const { fileNames, cwd, searchPaths } = options\n\n  if (searchPaths) {\n    const searchResults = await Promise.all(\n      searchPaths.map((dir) => findConfigFile(dir, fileNames))\n    )\n    const found = searchResults.find((result): result is string => result !== null)\n    if (found) {\n      return found\n    }\n  }\n\n  const fromCwd = await findConfigFile(cwd, fileNames)\n  if (fromCwd) {\n    return fromCwd\n  }\n\n  const projectRoot = findProjectRoot(cwd)\n  if (projectRoot && projectRoot.path !== cwd) {\n    const fromRoot = await findConfigFile(projectRoot.path, fileNames)\n    if (fromRoot) {\n      return fromRoot\n    }\n  }\n\n  return null\n}\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Search a single directory for the first matching config file name.\n *\n * Checks each candidate file name in order and returns the path of the first\n * one that exists on disk.\n *\n * @param dir - The directory to search in.\n * @param fileNames - Candidate config file names to look for.\n * @returns The full path to the first matching config file, or null if none found.\n * @private\n */\nasync function findConfigFile(\n  dir: string,\n  fileNames: readonly string[]\n): Promise<string | null> {\n  const results = await Promise.all(\n    fileNames.map(async (fileName) => {\n      const filePath = join(dir, fileName)\n      const exists = await fileExists(filePath)\n      if (exists) {\n        return filePath\n      }\n      return null\n    })\n  )\n  const found = results.find((result): result is string => result !== null)\n  return found ?? null\n}\n","import { extname } from 'node:path'\n\nimport { attempt, err, match } from '@kidd-cli/utils/fp'\nimport { jsonParse, jsonStringify } from '@kidd-cli/utils/json'\nimport type { ParseError } from 'jsonc-parser'\nimport { parse as parseJsonc, printParseErrorCode } from 'jsonc-parser'\nimport { parse as parseYaml, stringify as stringifyYaml } from 'yaml'\n\nimport type { ConfigFormat } from './constants.js'\nimport { EMPTY_LENGTH } from './constants.js'\nimport type { ConfigOperationResult } from './types.js'\n\n/**\n * Determine the config format from a file path's extension.\n *\n * @param filePath - The file path to inspect.\n * @returns The detected config format ('json', 'jsonc', or 'yaml').\n */\nexport function getFormat(filePath: string): ConfigFormat {\n  const ext = extname(filePath)\n  return match(ext)\n    .with('.jsonc', () => 'jsonc' as const)\n    .with('.yaml', () => 'yaml' as const)\n    .otherwise(() => 'json' as const)\n}\n\n/**\n * Options for parsing config file content.\n */\nexport interface ParseContentOptions {\n  readonly content: string\n  readonly filePath: string\n  readonly format: ConfigFormat\n}\n\n/**\n * Parse config file content using the appropriate parser for the given format.\n *\n * @param options - Parse content options.\n * @returns A ConfigOperationResult with the parsed data or an error.\n */\nexport function parseContent(options: ParseContentOptions): ConfigOperationResult<unknown> {\n  const { content, filePath, format } = options\n  return match(format)\n    .with('json', () => parseJson(content, filePath))\n    .with('jsonc', () => parseJsoncContent(content, filePath))\n    .with('yaml', () => parseYamlContent(content, filePath))\n    .exhaustive()\n}\n\n/**\n * Serialize data to a string in the specified config format.\n *\n * @param data - The data to serialize.\n * @param format - The target config format.\n * @returns The serialized string representation.\n */\nexport function serializeContent(data: unknown, format: ConfigFormat): string {\n  return match(format)\n    .with('json', () => {\n      const [, json] = jsonStringify(data, { pretty: true })\n      return `${json}\\n`\n    })\n    .with('jsonc', () => {\n      const [, json] = jsonStringify(data, { pretty: true })\n      return `${json}\\n`\n    })\n    .with('yaml', () => stringifyYaml(data))\n    .exhaustive()\n}\n\n/**\n * Get the file extension string for a given config format.\n *\n * @param format - The config format.\n * @returns The file extension including the leading dot (e.g. '.json').\n */\nexport function getExtension(format: ConfigFormat): string {\n  return match(format)\n    .with('json', () => '.json')\n    .with('jsonc', () => '.jsonc')\n    .with('yaml', () => '.yaml')\n    .exhaustive()\n}\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Parse a JSON string and return the result as a ConfigOperationResult.\n *\n * @param content - The raw JSON string to parse.\n * @param filePath - The file path used in error messages.\n * @returns A ConfigOperationResult with the parsed data or a parse error.\n * @private\n */\nfunction parseJson(content: string, filePath: string): ConfigOperationResult<unknown> {\n  const [error, result] = jsonParse(content)\n  if (error) {\n    return err(`Failed to parse JSON in ${filePath}: ${error.message}`)\n  }\n  return [null, result]\n}\n\n/**\n * Parse a JSONC (JSON with comments) string and return the result as a ConfigOperationResult.\n *\n * @param content - The raw JSONC string to parse.\n * @param filePath - The file path used in error messages.\n * @returns A ConfigOperationResult with the parsed data or a parse error.\n * @private\n */\nfunction parseJsoncContent(\n  content: string,\n  filePath: string\n): ConfigOperationResult<unknown> {\n  const errors: ParseError[] = []\n  const result = parseJsonc(content, errors, {\n    allowEmptyContent: false,\n    allowTrailingComma: true,\n  })\n  if (errors.length > EMPTY_LENGTH) {\n    const errorMessages = errors\n      .map(\n        (parseError) =>\n          `  - ${printParseErrorCode(parseError.error)} at offset ${parseError.offset}`\n      )\n      .join('\\n')\n    return err(`Failed to parse JSONC in ${filePath}:\\n${errorMessages}`)\n  }\n  return [null, result]\n}\n\n/**\n * Parse a YAML string and return the result as a ConfigOperationResult.\n *\n * @param content - The raw YAML string to parse.\n * @param filePath - The file path used in error messages.\n * @returns A ConfigOperationResult with the parsed data or a parse error.\n * @private\n */\nfunction parseYamlContent(\n  content: string,\n  filePath: string\n): ConfigOperationResult<unknown> {\n  const [error, result] = attempt(() => parseYaml(content))\n  if (error) {\n    return err(`Failed to parse YAML in ${filePath}: ${String(error)}`)\n  }\n  return [null, result]\n}\n","import { mkdir, readFile, writeFile } from 'node:fs/promises'\nimport { dirname, join } from 'node:path'\n\nimport { attemptAsync, err, match } from '@kidd-cli/utils/fp'\nimport { formatZodIssues } from '@kidd-cli/utils/validate'\nimport type { ZodTypeAny, output } from 'zod'\n\nimport { findConfig, getConfigFileNames } from './find.js'\nimport { getExtension, getFormat, parseContent, serializeContent } from './parse.js'\nimport type {\n  Config,\n  ConfigOperationResult,\n  ConfigOptions,\n  ConfigResult,\n  ConfigWriteOptions,\n  ConfigWriteResult,\n} from './types.js'\n\n/**\n * Create a typed config client that loads, validates, and writes config files.\n *\n * @param options - Config client options including name and Zod schema.\n * @returns A {@link Config} client instance.\n */\nexport function createConfigClient<TSchema extends ZodTypeAny>(\n  options: ConfigOptions<TSchema>\n): Config<output<TSchema>> {\n  const { name, schema, searchPaths } = options\n  const fileNames = getConfigFileNames(name)\n\n  /**\n   * Find a config file in the given directory.\n   *\n   * @private\n   * @param cwd - Working directory to search from.\n   * @returns The path to the config file, or null if not found.\n   */\n  async function find(cwd?: string): Promise<string | null> {\n    return findConfig({\n      cwd: cwd ?? process.cwd(),\n      fileNames,\n      searchPaths,\n    })\n  }\n\n  /**\n   * Load and validate a config file.\n   *\n   * @private\n   * @param cwd - Working directory to search from.\n   * @returns A ConfigOperationResult with the loaded config, or [null, null] if not found.\n   */\n  async function load(\n    cwd?: string\n  ): Promise<ConfigOperationResult<ConfigResult<output<TSchema>>> | readonly [null, null]> {\n    const filePath = await find(cwd)\n    if (!filePath) {\n      return [null, null]\n    }\n\n    const [readError, content] = await attemptAsync(() => readFile(filePath, 'utf8'))\n    if (readError || content === null) {\n      const errorDetail = resolveReadErrorDetail(readError)\n      return err(`Failed to read config at ${filePath}: ${errorDetail}`)\n    }\n\n    const format = getFormat(filePath)\n    const parsedResult = parseContent({ content, filePath, format })\n\n    if (parsedResult[0]) {\n      return [parsedResult[0], null]\n    }\n\n    const result = schema.safeParse(parsedResult[1])\n    if (!result.success) {\n      const { message } = formatZodIssues(result.error.issues, '\\n')\n      return err(`Invalid config in ${filePath}:\\n${message}`)\n    }\n\n    return [\n      null,\n      {\n        config: result.data,\n        filePath,\n        format,\n      },\n    ]\n  }\n\n  /**\n   * Validate and write config data to a file.\n   *\n   * @private\n   * @param data - The config data to write.\n   * @param writeOptions - Write options including path and format.\n   * @returns A ConfigOperationResult with the write result.\n   */\n  async function write(\n    data: output<TSchema>,\n    writeOptions: ConfigWriteOptions = {}\n  ): Promise<ConfigOperationResult<ConfigWriteResult>> {\n    const result = schema.safeParse(data)\n    if (!result.success) {\n      const { message } = formatZodIssues(result.error.issues, '\\n')\n      return err(`Invalid config data:\\n${message}`)\n    }\n\n    const resolvedFormat = match(writeOptions)\n      .when(\n        (opts) => opts.format !== null && opts.format !== undefined,\n        (opts) => opts.format ?? ('jsonc' as const)\n      )\n      .when(\n        (opts) => opts.filePath !== null && opts.filePath !== undefined,\n        (opts) => getFormat(opts.filePath ?? '')\n      )\n      .otherwise(() => 'jsonc' as const)\n\n    const resolvedFilePath = match(writeOptions.filePath)\n      .when(\n        (fp) => fp !== null && fp !== undefined,\n        (fp) => fp ?? ''\n      )\n      .otherwise(() => {\n        const dir = writeOptions.dir ?? process.cwd()\n        const ext = getExtension(resolvedFormat)\n        return join(dir, `.${name}${ext}`)\n      })\n\n    const serialized = serializeContent(result.data, resolvedFormat)\n\n    const [mkdirError] = await attemptAsync(() =>\n      mkdir(dirname(resolvedFilePath), { recursive: true })\n    )\n    if (mkdirError) {\n      return err(`Failed to create directory for ${resolvedFilePath}: ${String(mkdirError)}`)\n    }\n\n    const [writeError] = await attemptAsync(() => writeFile(resolvedFilePath, serialized, 'utf8'))\n    if (writeError) {\n      return err(`Failed to write config to ${resolvedFilePath}: ${String(writeError)}`)\n    }\n\n    return [null, { filePath: resolvedFilePath, format: resolvedFormat }]\n  }\n\n  return { find, load, write }\n}\n\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve the error detail string from a read error.\n *\n * @private\n * @param readError - The error from the read operation, or null.\n * @returns A descriptive error string.\n */\nfunction resolveReadErrorDetail(readError: unknown): string {\n  if (readError) {\n    return String(readError)\n  }\n  return 'empty file'\n}\n"],"mappings":"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"}

package/dist/create-http-client-tZJWlWp1.js

@@ -0,0 +1,165 @@
+import { attemptAsync } from "@kidd-cli/utils/fp";
+
+//#region src/middleware/http/create-http-client.ts
+/**
+* Typed HTTP client factory.
+*
+* Creates a closure-based {@link HttpClient} with pre-configured base URL
+* and default headers. All methods delegate to a shared request executor.
+*
+* @module
+*/
+/**
+* Create a typed HTTP client with pre-configured base URL and headers.
+*
+* @param options - Client configuration.
+* @returns An HttpClient instance.
+*/
+function createHttpClient(options) {
+	const { baseUrl, defaultHeaders, resolveHeaders } = options;
+	return {
+		delete: (path, requestOptions) => executeRequest(baseUrl, "DELETE", path, defaultHeaders, resolveHeaders, requestOptions),
+		get: (path, requestOptions) => executeRequest(baseUrl, "GET", path, defaultHeaders, resolveHeaders, requestOptions),
+		patch: (path, requestOptions) => executeRequest(baseUrl, "PATCH", path, defaultHeaders, resolveHeaders, requestOptions),
+		post: (path, requestOptions) => executeRequest(baseUrl, "POST", path, defaultHeaders, resolveHeaders, requestOptions),
+		put: (path, requestOptions) => executeRequest(baseUrl, "PUT", path, defaultHeaders, resolveHeaders, requestOptions)
+	};
+}
+/**
+* Build the full URL from base, path, and optional query params.
+*
+* @private
+* @param baseUrl - The base URL.
+* @param path - The request path.
+* @param params - Optional query parameters.
+* @returns The fully qualified URL string.
+*/
+function buildUrl(baseUrl, path, params) {
+	const url = new URL(path, baseUrl);
+	if (params !== void 0) url.search = new URLSearchParams(params).toString();
+	return url.toString();
+}
+/**
+* Merge default, dynamic, and per-request headers into a single record.
+*
+* Per-request headers take highest priority, then dynamic headers,
+* then default headers.
+*
+* @private
+* @param defaultHeaders - Optional default headers.
+* @param dynamicHeaders - Optional dynamically resolved headers.
+* @param requestHeaders - Optional per-request headers.
+* @returns The merged headers record.
+*/
+function mergeHeaders(defaultHeaders, dynamicHeaders, requestHeaders) {
+	return {
+		...defaultHeaders,
+		...dynamicHeaders,
+		...requestHeaders
+	};
+}
+/**
+* Normalize optional request options into a concrete object with safe defaults.
+*
+* When `options` is `undefined`, returns an empty object so callers can use
+* direct property access without additional nil checks.
+*
+* @private
+* @param options - Optional per-request options.
+* @returns The resolved options object.
+*/
+function resolveRequestOptions(options) {
+	if (options !== void 0) return options;
+	return {};
+}
+/**
+* Invoke the dynamic header resolver if provided.
+*
+* @private
+* @param resolveHeaders - Optional function to resolve dynamic headers.
+* @returns The resolved headers record, or undefined.
+*/
+function resolveDynamicHeaders(resolveHeaders) {
+	if (resolveHeaders !== void 0) return resolveHeaders();
+}
+/**
+* Resolve the serialized body string and content-type header mutation.
+*
+* @private
+* @param options - Optional per-request options.
+* @returns The serialized body string or undefined.
+*/
+function resolveBody(options) {
+	if (options !== void 0 && options.body !== void 0) return JSON.stringify(options.body);
+}
+/**
+* Build the fetch init options from resolved values.
+*
+* @private
+* @param method - The HTTP method.
+* @param headers - The merged headers.
+* @param body - The serialized body or undefined.
+* @param signal - The abort signal or undefined.
+* @returns The RequestInit for fetch.
+*/
+function buildFetchInit(method, headers, body, signal) {
+	if (body !== void 0) return {
+		body,
+		headers: {
+			...headers,
+			"Content-Type": "application/json"
+		},
+		method,
+		signal
+	};
+	return {
+		headers,
+		method,
+		signal
+	};
+}
+/**
+* Execute an HTTP request and wrap the response.
+*
+* @private
+* @param baseUrl - The base URL.
+* @param method - The HTTP method.
+* @param path - The request path.
+* @param defaultHeaders - Optional default headers.
+* @param resolveHeaders - Optional function to resolve dynamic headers per-request.
+* @param options - Optional per-request options.
+* @returns A typed response wrapper.
+*/
+async function executeRequest(baseUrl, method, path, defaultHeaders, resolveHeaders, options) {
+	const resolved = resolveRequestOptions(options);
+	const url = buildUrl(baseUrl, path, resolved.params);
+	const init = buildFetchInit(method, mergeHeaders(defaultHeaders, resolveDynamicHeaders(resolveHeaders), resolved.headers), resolveBody(options), resolved.signal);
+	const response = await fetch(url, init);
+	return {
+		data: await parseResponseBody(response),
+		headers: response.headers,
+		ok: response.ok,
+		raw: response,
+		status: response.status
+	};
+}
+/**
+* Parse the response body as JSON, returning null on failure.
+*
+* Wraps `response.json()` with `attemptAsync` so malformed API
+* responses do not crash the command. Returns `null as TResponse`
+* when parsing fails.
+*
+* @private
+* @param response - The fetch Response.
+* @returns The parsed body or null.
+*/
+async function parseResponseBody(response) {
+	const [error, data] = await attemptAsync(() => response.json());
+	if (error) return null;
+	return data;
+}
+
+//#endregion
+export { createHttpClient as t };
+//# sourceMappingURL=create-http-client-tZJWlWp1.js.map

package/dist/create-http-client-tZJWlWp1.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-http-client-tZJWlWp1.js","names":[],"sources":["../src/middleware/http/create-http-client.ts"],"sourcesContent":["/**\n * Typed HTTP client factory.\n *\n * Creates a closure-based {@link HttpClient} with pre-configured base URL\n * and default headers. All methods delegate to a shared request executor.\n *\n * @module\n */\n\nimport { attemptAsync } from '@kidd-cli/utils/fp'\n\nimport type { HttpClient, RequestOptions, TypedResponse } from './types.js'\n\n/**\n * Options for creating an HTTP client.\n */\ninterface CreateHttpClientOptions {\n  readonly baseUrl: string\n  readonly defaultHeaders?: Readonly<Record<string, string>>\n  readonly resolveHeaders?: () => Readonly<Record<string, string>>\n}\n\n/**\n * Create a typed HTTP client with pre-configured base URL and headers.\n *\n * @param options - Client configuration.\n * @returns An HttpClient instance.\n */\nexport function createHttpClient(options: CreateHttpClientOptions): HttpClient {\n  const { baseUrl, defaultHeaders, resolveHeaders } = options\n\n  return {\n    delete: <TResponse = unknown>(path: string, requestOptions?: RequestOptions) =>\n      executeRequest<TResponse>(baseUrl, 'DELETE', path, defaultHeaders, resolveHeaders, requestOptions),\n\n    get: <TResponse = unknown>(path: string, requestOptions?: RequestOptions) =>\n      executeRequest<TResponse>(baseUrl, 'GET', path, defaultHeaders, resolveHeaders, requestOptions),\n\n    patch: <TResponse = unknown, TBody = unknown>(\n      path: string,\n      requestOptions?: RequestOptions<TBody>\n    ) =>\n      executeRequest<TResponse>(baseUrl, 'PATCH', path, defaultHeaders, resolveHeaders, requestOptions),\n\n    post: <TResponse = unknown, TBody = unknown>(\n      path: string,\n      requestOptions?: RequestOptions<TBody>\n    ) =>\n      executeRequest<TResponse>(baseUrl, 'POST', path, defaultHeaders, resolveHeaders, requestOptions),\n\n    put: <TResponse = unknown, TBody = unknown>(\n      path: string,\n      requestOptions?: RequestOptions<TBody>\n    ) =>\n      executeRequest<TResponse>(baseUrl, 'PUT', path, defaultHeaders, resolveHeaders, requestOptions),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build the full URL from base, path, and optional query params.\n *\n * @private\n * @param baseUrl - The base URL.\n * @param path - The request path.\n * @param params - Optional query parameters.\n * @returns The fully qualified URL string.\n */\nfunction buildUrl(\n  baseUrl: string,\n  path: string,\n  params: Readonly<Record<string, string>> | undefined\n): string {\n  const url = new URL(path, baseUrl)\n\n  if (params !== undefined) {\n    const searchParams = new URLSearchParams(params)\n    url.search = searchParams.toString()\n  }\n\n  return url.toString()\n}\n\n/**\n * Merge default, dynamic, and per-request headers into a single record.\n *\n * Per-request headers take highest priority, then dynamic headers,\n * then default headers.\n *\n * @private\n * @param defaultHeaders - Optional default headers.\n * @param dynamicHeaders - Optional dynamically resolved headers.\n * @param requestHeaders - Optional per-request headers.\n * @returns The merged headers record.\n */\nfunction mergeHeaders(\n  defaultHeaders: Readonly<Record<string, string>> | undefined,\n  dynamicHeaders: Readonly<Record<string, string>> | undefined,\n  requestHeaders: Readonly<Record<string, string>> | undefined\n): Readonly<Record<string, string>> {\n  return {\n    ...defaultHeaders,\n    ...dynamicHeaders,\n    ...requestHeaders,\n  }\n}\n\n/**\n * Normalize optional request options into a concrete object with safe defaults.\n *\n * When `options` is `undefined`, returns an empty object so callers can use\n * direct property access without additional nil checks.\n *\n * @private\n * @param options - Optional per-request options.\n * @returns The resolved options object.\n */\nfunction resolveRequestOptions(options: RequestOptions | undefined): RequestOptions {\n  if (options !== undefined) {\n    return options\n  }\n\n  return {}\n}\n\n/**\n * Invoke the dynamic header resolver if provided.\n *\n * @private\n * @param resolveHeaders - Optional function to resolve dynamic headers.\n * @returns The resolved headers record, or undefined.\n */\nfunction resolveDynamicHeaders(\n  resolveHeaders: (() => Readonly<Record<string, string>>) | undefined\n): Readonly<Record<string, string>> | undefined {\n  if (resolveHeaders !== undefined) {\n    return resolveHeaders()\n  }\n\n  return undefined\n}\n\n/**\n * Resolve the serialized body string and content-type header mutation.\n *\n * @private\n * @param options - Optional per-request options.\n * @returns The serialized body string or undefined.\n */\nfunction resolveBody(options: RequestOptions | undefined): string | undefined {\n  if (options !== undefined && options.body !== undefined) {\n    return JSON.stringify(options.body)\n  }\n\n  return undefined\n}\n\n/**\n * Build the fetch init options from resolved values.\n *\n * @private\n * @param method - The HTTP method.\n * @param headers - The merged headers.\n * @param body - The serialized body or undefined.\n * @param signal - The abort signal or undefined.\n * @returns The RequestInit for fetch.\n */\nfunction buildFetchInit(\n  method: string,\n  headers: Readonly<Record<string, string>>,\n  body: string | undefined,\n  signal: AbortSignal | undefined\n): RequestInit {\n  if (body !== undefined) {\n    return {\n      body,\n      headers: { ...headers, 'Content-Type': 'application/json' },\n      method,\n      signal,\n    }\n  }\n\n  return {\n    headers,\n    method,\n    signal,\n  }\n}\n\n/**\n * Execute an HTTP request and wrap the response.\n *\n * @private\n * @param baseUrl - The base URL.\n * @param method - The HTTP method.\n * @param path - The request path.\n * @param defaultHeaders - Optional default headers.\n * @param resolveHeaders - Optional function to resolve dynamic headers per-request.\n * @param options - Optional per-request options.\n * @returns A typed response wrapper.\n */\nasync function executeRequest<TResponse>(\n  baseUrl: string,\n  method: string,\n  path: string,\n  defaultHeaders: Readonly<Record<string, string>> | undefined,\n  resolveHeaders: (() => Readonly<Record<string, string>>) | undefined,\n  options: RequestOptions | undefined\n): Promise<TypedResponse<TResponse>> {\n  const resolved = resolveRequestOptions(options)\n  const url = buildUrl(baseUrl, path, resolved.params)\n  const dynamicHeaders = resolveDynamicHeaders(resolveHeaders)\n  const headers = mergeHeaders(defaultHeaders, dynamicHeaders, resolved.headers)\n  const body = resolveBody(options)\n  const init = buildFetchInit(method, headers, body, resolved.signal)\n\n  const response = await fetch(url, init)\n  const data = await parseResponseBody<TResponse>(response)\n\n  return {\n    data,\n    headers: response.headers,\n    ok: response.ok,\n    raw: response,\n    status: response.status,\n  }\n}\n\n/**\n * Parse the response body as JSON, returning null on failure.\n *\n * Wraps `response.json()` with `attemptAsync` so malformed API\n * responses do not crash the command. Returns `null as TResponse`\n * when parsing fails.\n *\n * @private\n * @param response - The fetch Response.\n * @returns The parsed body or null.\n */\nasync function parseResponseBody<TResponse>(response: Response): Promise<TResponse> {\n  const [error, data] = await attemptAsync(() => response.json() as Promise<TResponse>)\n\n  if (error) {\n    return null as TResponse\n  }\n\n  return data as TResponse\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA4BA,SAAgB,iBAAiB,SAA8C;CAC7E,MAAM,EAAE,SAAS,gBAAgB,mBAAmB;AAEpD,QAAO;EACL,SAA8B,MAAc,mBAC1C,eAA0B,SAAS,UAAU,MAAM,gBAAgB,gBAAgB,eAAe;EAEpG,MAA2B,MAAc,mBACvC,eAA0B,SAAS,OAAO,MAAM,gBAAgB,gBAAgB,eAAe;EAEjG,QACE,MACA,mBAEA,eAA0B,SAAS,SAAS,MAAM,gBAAgB,gBAAgB,eAAe;EAEnG,OACE,MACA,mBAEA,eAA0B,SAAS,QAAQ,MAAM,gBAAgB,gBAAgB,eAAe;EAElG,MACE,MACA,mBAEA,eAA0B,SAAS,OAAO,MAAM,gBAAgB,gBAAgB,eAAe;EAClG;;;;;;;;;;;AAgBH,SAAS,SACP,SACA,MACA,QACQ;CACR,MAAM,MAAM,IAAI,IAAI,MAAM,QAAQ;AAElC,KAAI,WAAW,OAEb,KAAI,SADiB,IAAI,gBAAgB,OAAO,CACtB,UAAU;AAGtC,QAAO,IAAI,UAAU;;;;;;;;;;;;;;AAevB,SAAS,aACP,gBACA,gBACA,gBACkC;AAClC,QAAO;EACL,GAAG;EACH,GAAG;EACH,GAAG;EACJ;;;;;;;;;;;;AAaH,SAAS,sBAAsB,SAAqD;AAClF,KAAI,YAAY,OACd,QAAO;AAGT,QAAO,EAAE;;;;;;;;;AAUX,SAAS,sBACP,gBAC8C;AAC9C,KAAI,mBAAmB,OACrB,QAAO,gBAAgB;;;;;;;;;AAa3B,SAAS,YAAY,SAAyD;AAC5E,KAAI,YAAY,UAAa,QAAQ,SAAS,OAC5C,QAAO,KAAK,UAAU,QAAQ,KAAK;;;;;;;;;;;;AAgBvC,SAAS,eACP,QACA,SACA,MACA,QACa;AACb,KAAI,SAAS,OACX,QAAO;EACL;EACA,SAAS;GAAE,GAAG;GAAS,gBAAgB;GAAoB;EAC3D;EACA;EACD;AAGH,QAAO;EACL;EACA;EACA;EACD;;;;;;;;;;;;;;AAeH,eAAe,eACb,SACA,QACA,MACA,gBACA,gBACA,SACmC;CACnC,MAAM,WAAW,sBAAsB,QAAQ;CAC/C,MAAM,MAAM,SAAS,SAAS,MAAM,SAAS,OAAO;CAIpD,MAAM,OAAO,eAAe,QAFZ,aAAa,gBADN,sBAAsB,eAAe,EACC,SAAS,QAAQ,EACjE,YAAY,QAAQ,EACkB,SAAS,OAAO;CAEnE,MAAM,WAAW,MAAM,MAAM,KAAK,KAAK;AAGvC,QAAO;EACL,MAHW,MAAM,kBAA6B,SAAS;EAIvD,SAAS,SAAS;EAClB,IAAI,SAAS;EACb,KAAK;EACL,QAAQ,SAAS;EAClB;;;;;;;;;;;;;AAcH,eAAe,kBAA6B,UAAwC;CAClF,MAAM,CAAC,OAAO,QAAQ,MAAM,mBAAmB,SAAS,MAAM,CAAuB;AAErF,KAAI,MACF,QAAO;AAGT,QAAO"}

package/dist/{create-store-BQUX0tAn.js → create-store-D-fQpCql.js}

@@ -1,8 +1,8 @@
-import { n as resolveLocalPath, t as resolveGlobalPath } from "./project-NPtYX2ZX.js";
+import { n as resolveLocalPath, t as resolveGlobalPath } from "./project-DuXgjaa_.js";
 import { join } from "node:path";
 import { attempt, err, match, ok } from "@kidd-cli/utils/fp";
 import { jsonParse, jsonStringify } from "@kidd-cli/utils/json";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
 
 //#region src/lib/store/create-store.ts
 /**
@@ -44,7 +44,6 @@ function createStore(options) {
 	* @returns The file content, or null if the file does not exist or cannot be read.
 	*/
 	function loadFromPath(filePath) {
-		if (!existsSync(filePath)) return null;
 		const [error, content] = attempt(() => readFileSync(filePath, "utf8"));
 		if (error) return null;
 		return content;
@@ -172,12 +171,41 @@ function createStore(options) {
 		if (writeError) return err(writeError);
 		return ok(filePath);
 	}
+	/**
+	* Remove a file from the store.
+	*
+	* Returns `ok(filePath)` when the file was deleted or did not exist
+	* (idempotent). Returns an error when the target directory cannot be
+	* resolved or the unlink fails.
+	*
+	* @private
+	* @param filename - The filename to remove.
+	* @param removeOptions - Options controlling the removal target.
+	* @returns A Result with the file path on success.
+	*/
+	function remove(filename, removeOptions = {}) {
+		const { source: removeSource = "global", startDir } = removeOptions;
+		const dir = resolveSaveDir({
+			globalDir: getGlobalDir(),
+			localDir: getLocalDir(startDir),
+			source: removeSource
+		});
+		if (dir === null) return err(/* @__PURE__ */ new Error(`Cannot remove from "${removeSource}" — no local project directory found`));
+		const filePath = join(dir, filename);
+		if (!existsSync(filePath)) return ok(filePath);
+		const [removeError] = attempt(() => {
+			unlinkSync(filePath);
+		});
+		if (removeError) return err(removeError);
+		return ok(filePath);
+	}
 	return {
 		getFilePath,
 		getGlobalDir,
 		getLocalDir,
 		load,
 		loadRaw,
+		remove,
 		save
 	};
 }
@@ -194,4 +222,4 @@ function resolveSaveDir(options) {
 
 //#endregion
 export { createStore as t };
-//# sourceMappingURL=create-store-BQUX0tAn.js.map
+//# sourceMappingURL=create-store-D-fQpCql.js.map

package/dist/create-store-D-fQpCql.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-store-D-fQpCql.js","names":[],"sources":["../src/lib/store/create-store.ts"],"sourcesContent":["import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'\nimport { join } from 'node:path'\n\nimport { attempt, err, match, ok } from '@kidd-cli/utils/fp'\nimport type { Result } from '@kidd-cli/utils/fp'\nimport { jsonParse, jsonStringify } from '@kidd-cli/utils/json'\n\nimport { resolveGlobalPath, resolveLocalPath } from '@/lib/project/index.js'\nimport type { PathSource } from '@/lib/project/types.js'\n\nimport type { FileStore, LoadOptions, SaveOptions, StoreOptions } from './types.js'\n\n/**\n * Create a file-backed {@link FileStore} that resolves JSON files from project-local\n * or global home directories.\n *\n * @param options - Store configuration.\n * @returns A FileStore instance.\n */\nexport function createStore<TData = unknown>(options: StoreOptions<TData>): FileStore<TData> {\n  const { dirName, defaults } = options\n\n  /**\n   * Resolve the local project directory for the store.\n   *\n   * @private\n   * @param startDir - Optional directory to start searching from.\n   * @returns The local directory path, or null if no project root is found.\n   */\n  function getLocalDir(startDir?: string): string | null {\n    return resolveLocalPath({ dirName, startDir })\n  }\n\n  /**\n   * Resolve the global home directory for the store.\n   *\n   * @private\n   * @returns The global directory path.\n   */\n  function getGlobalDir(): string {\n    return resolveGlobalPath({ dirName })\n  }\n\n  /**\n   * Read the raw string content from a file path.\n   *\n   * @private\n   * @param filePath - The file path to read.\n   * @returns The file content, or null if the file does not exist or cannot be read.\n   */\n  function loadFromPath(filePath: string): string | null {\n    const [error, content] = attempt(() => readFileSync(filePath, 'utf8'))\n\n    if (error) {\n      return null\n    }\n\n    return content\n  }\n\n  /**\n   * Resolve a file from local or global directories based on the source strategy.\n   *\n   * @private\n   * @param resolveOptions - Resolution options.\n   * @returns The resolved result, or null if not found.\n   */\n  function resolveFromSource<T>(resolveOptions: {\n    source: PathSource\n    localDir: string | null\n    globalDir: string\n    filename: string\n    handler: (filePath: string) => T | null\n  }): T | null {\n    return match(resolveOptions.source)\n      .with('local', (): T | null => {\n        if (!resolveOptions.localDir) {\n          return null\n        }\n        return resolveOptions.handler(join(resolveOptions.localDir, resolveOptions.filename))\n      })\n      .with('global', () =>\n        resolveOptions.handler(join(resolveOptions.globalDir, resolveOptions.filename))\n      )\n      .with('resolve', (): T | null => {\n        if (resolveOptions.localDir) {\n          const localResult = resolveOptions.handler(\n            join(resolveOptions.localDir, resolveOptions.filename)\n          )\n          if (localResult !== null) {\n            return localResult\n          }\n        }\n        return resolveOptions.handler(join(resolveOptions.globalDir, resolveOptions.filename))\n      })\n      .exhaustive()\n  }\n\n  /**\n   * Load the raw string content of a store file.\n   *\n   * @private\n   * @param filename - The filename to load.\n   * @param loadOptions - Options controlling source resolution.\n   * @returns The raw file content, or null if not found.\n   */\n  function loadRaw(filename: string, loadOptions: LoadOptions = {}): string | null {\n    const { source: loadSource = 'resolve', startDir } = loadOptions\n    const localDir = getLocalDir(startDir)\n    const globalDir = getGlobalDir()\n\n    return resolveFromSource<string>({\n      filename,\n      globalDir,\n      handler: loadFromPath,\n      localDir,\n      source: loadSource,\n    })\n  }\n\n  /**\n   * Load and parse a store file as JSON, merging with defaults if available.\n   *\n   * @private\n   * @param filename - The filename to load.\n   * @param loadOptions - Options controlling source resolution.\n   * @returns The parsed data, defaults, or null.\n   */\n  function load(filename: string, loadOptions: LoadOptions = {}): TData | null {\n    const raw = loadRaw(filename, loadOptions)\n\n    if (raw === null) {\n      return defaults ?? null\n    }\n\n    const [parseError, parsed] = jsonParse(raw)\n    if (parseError) {\n      return defaults ?? null\n    }\n\n    if (defaults) {\n      return { ...defaults, ...(parsed as Partial<TData>) }\n    }\n    return parsed as TData\n  }\n\n  /**\n   * Check if a file exists at the given path and return the path if so.\n   *\n   * @private\n   * @param filePath - The file path to check.\n   * @returns The file path if it exists, or null.\n   */\n  function checkFileExists(filePath: string): string | null {\n    if (existsSync(filePath)) {\n      return filePath\n    }\n    return null\n  }\n\n  /**\n   * Resolve the file path for a store file without reading its content.\n   *\n   * @private\n   * @param filename - The filename to resolve.\n   * @param loadOptions - Options controlling source resolution.\n   * @returns The resolved file path, or null if not found.\n   */\n  function getFilePath(filename: string, loadOptions: LoadOptions = {}): string | null {\n    const { source: fileSource = 'resolve', startDir } = loadOptions\n    const localDir = getLocalDir(startDir)\n    const globalDir = getGlobalDir()\n\n    return resolveFromSource<string>({\n      filename,\n      globalDir,\n      handler: checkFileExists,\n      localDir,\n      source: fileSource,\n    })\n  }\n\n  /**\n   * Serialize data to JSON and write it to a store file.\n   *\n   * Creates the target directory if it does not exist. Defaults to\n   * the global home directory when no source is specified.\n   *\n   * @private\n   * @param filename - The filename to write.\n   * @param data - The data to serialize.\n   * @param saveOptions - Options controlling the write target.\n   * @returns A Result with the written file path on success.\n   */\n  function save(filename: string, data: unknown, saveOptions: SaveOptions = {}): Result<string> {\n    const { source: saveSource = 'global', startDir } = saveOptions\n\n    const dir = resolveSaveDir({\n      globalDir: getGlobalDir(),\n      localDir: getLocalDir(startDir),\n      source: saveSource,\n    })\n\n    if (dir === null) {\n      return err(new Error(`Cannot save to \"${saveSource}\" — no local project directory found`))\n    }\n\n    const [stringifyError, json] = jsonStringify(data, { pretty: true })\n\n    if (stringifyError) {\n      return err(stringifyError)\n    }\n\n    const filePath = join(dir, filename)\n\n    const [writeError] = attempt(() => {\n      mkdirSync(dir, { mode: 0o700, recursive: true })\n      writeFileSync(filePath, json, { encoding: 'utf8', mode: 0o600 })\n    })\n\n    if (writeError) {\n      return err(writeError)\n    }\n\n    return ok(filePath)\n  }\n\n  /**\n   * Remove a file from the store.\n   *\n   * Returns `ok(filePath)` when the file was deleted or did not exist\n   * (idempotent). Returns an error when the target directory cannot be\n   * resolved or the unlink fails.\n   *\n   * @private\n   * @param filename - The filename to remove.\n   * @param removeOptions - Options controlling the removal target.\n   * @returns A Result with the file path on success.\n   */\n  function remove(filename: string, removeOptions: SaveOptions = {}): Result<string> {\n    const { source: removeSource = 'global', startDir } = removeOptions\n\n    const dir = resolveSaveDir({\n      globalDir: getGlobalDir(),\n      localDir: getLocalDir(startDir),\n      source: removeSource,\n    })\n\n    if (dir === null) {\n      return err(new Error(`Cannot remove from \"${removeSource}\" — no local project directory found`))\n    }\n\n    const filePath = join(dir, filename)\n\n    if (!existsSync(filePath)) {\n      return ok(filePath)\n    }\n\n    const [removeError] = attempt(() => {\n      unlinkSync(filePath)\n    })\n\n    if (removeError) {\n      return err(removeError)\n    }\n\n    return ok(filePath)\n  }\n\n  return {\n    getFilePath,\n    getGlobalDir,\n    getLocalDir,\n    load,\n    loadRaw,\n    remove,\n    save,\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Private helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Resolve the target directory for a save operation.\n *\n * @private\n * @param options - Resolution options.\n * @returns The directory path, or null when `local` is requested but unavailable.\n */\nfunction resolveSaveDir(options: {\n  readonly localDir: string | null\n  readonly globalDir: string\n  readonly source: 'local' | 'global'\n}): string | null {\n  return match(options.source)\n    .with('local', (): string | null => options.localDir)\n    .with('global', () => options.globalDir)\n    .exhaustive()\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { a as CommandDef, c as MiddlewareFn, i as Command, l as Context, n as AutoloadOptions, o as CommandMap, r as CliOptions, s as Middleware, t as ArgsDef } from "./types-kjpRau0U.js";
+import { a as CommandDef, c as MiddlewareEnv, i as Command, l as MiddlewareFn, n as AutoloadOptions, o as CommandMap, r as CliOptions, s as Middleware, t as ArgsDef, u as Context } from "./types-BaZ5WqVM.js";
 import { defineConfig } from "@kidd-cli/config";
 import { z } from "zod";
 
@@ -17,10 +17,14 @@ declare function cli<TSchema extends z.ZodType = z.ZodType>(options: CliOptions<
 /**
 * Define a CLI command with typed args, config, and handler.
 *
-* @param def - Command definition including description, args schema, and handler.
+* The `const TMiddleware` generic preserves the middleware tuple as a literal type,
+* enabling TypeScript to extract and intersect `Variables` from each middleware
+* element onto the handler's `ctx` type.
+*
+* @param def - Command definition including description, args schema, middleware, and handler.
 * @returns A resolved Command object for registration in the command map.
 */
-declare function command<TArgsDef extends ArgsDef = ArgsDef, TConfig extends Record<string, unknown> = Record<string, unknown>>(def: CommandDef<TArgsDef, TConfig>): Command<TArgsDef, TConfig>;
+declare function command<TArgsDef extends ArgsDef = ArgsDef, TConfig extends Record<string, unknown> = Record<string, unknown>, const TMiddleware extends readonly Middleware<MiddlewareEnv>[] = readonly Middleware<MiddlewareEnv>[]>(def: CommandDef<TArgsDef, TConfig, TMiddleware>): Command;
 //#endregion
 //#region src/autoloader.d.ts
 /**
@@ -64,10 +68,21 @@ declare function decorateContext<TKey extends string, TValue>(ctx: Context, key:
 /**
 * Create a typed middleware that runs before command handlers.
 *
+* Use the generic parameter to declare context variables the middleware provides.
+* The handler's `ctx` type in downstream commands will include these variables.
+*
 * @param handler - The middleware function receiving ctx and next.
-* @returns A Middleware object for use in the cli() middleware stack.
+* @returns A Middleware object for use in the cli() or command() middleware stack.
+*
+* @example
+* ```ts
+* const loadUser = middleware<{ Variables: { user: User } }>(async (ctx, next) => {
+*   decorateContext(ctx, 'user', await fetchUser())
+*   await next()
+* })
+* ```
 */
-declare function middleware<TConfig extends Record<string, unknown> = Record<string, unknown>>(handler: MiddlewareFn<TConfig>): Middleware<TConfig>;
+declare function middleware<TEnv extends MiddlewareEnv = MiddlewareEnv>(handler: MiddlewareFn<TEnv>): Middleware<TEnv>;
 //#endregion
-export { type Command, type Context, autoload, cli, command, decorateContext, defineConfig, middleware };
+export { type Command, type Context, type MiddlewareEnv, autoload, cli, command, decorateContext, defineConfig, middleware };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cli.ts","../src/command.ts","../src/autoloader.ts","../src/context/decorate.ts","../src/middleware.ts"],"mappings":";;;;;;;;;AAyBA;;;;iBAAsB,GAAA,iBAAoB,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA,CAAA,CACtD,OAAA,EAAS,UAAA,CAAW,OAAA,IACnB,OAAA;;;;;;;;AAFH;iBCfgB,OAAA,kBACG,OAAA,GAAU,OAAA,kBACX,MAAA,oBAA0B,MAAA,kBAAA,CAC1C,GAAA,EAAK,UAAA,CAAW,QAAA,EAAU,OAAA,IAAW,OAAA,CAAY,QAAA,EAAU,OAAA;;;;;;;;ADY7D;iBEPsB,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,UAAA;;;;;;;;AFOnE;;;;;;;;;;;;;;;;;;;;;iBGGgB,eAAA,6BAAA,CACd,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,IAAA,EACL,KAAA,EAAO,MAAA,GACN,OAAA;;;;;;;;AHPH;iBIfgB,UAAA,iBAA2B,MAAA,oBAA0B,MAAA,kBAAA,CACnE,OAAA,EAAS,YAAA,CAAa,OAAA,IACrB,UAAA,CAAW,OAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/cli.ts","../src/command.ts","../src/autoloader.ts","../src/context/decorate.ts","../src/middleware.ts"],"mappings":";;;;;;;;AAyBA;;;;;iBAAsB,GAAA,iBAAoB,CAAA,CAAE,OAAA,GAAU,CAAA,CAAE,OAAA,CAAA,CACtD,OAAA,EAAS,UAAA,CAAW,OAAA,IACnB,OAAA;;;;;;;AAFH;;;;;;iBCXgB,OAAA,kBACG,OAAA,GAAU,OAAA,kBACX,MAAA,oBAA0B,MAAA,sDACP,UAAA,CAAW,aAAA,eAA4B,UAAA,CAAW,aAAA,IAAA,CACrF,GAAA,EAAK,UAAA,CAAW,QAAA,EAAU,OAAA,EAAS,WAAA,IAAe,OAAA;;;;;;;ADOpD;;iBEPsB,QAAA,CAAS,OAAA,GAAU,eAAA,GAAkB,OAAA,CAAQ,UAAA;;;;;;;AFOnE;;;;;;;;;;;;;;;;;;;;;;iBGGgB,eAAA,6BAAA,CACd,GAAA,EAAK,OAAA,EACL,GAAA,EAAK,IAAA,EACL,KAAA,EAAO,MAAA,GACN,OAAA;;;;;;;AHPH;;;;;;;;;;;;;iBIJgB,UAAA,cAAwB,aAAA,GAAgB,aAAA,CAAA,CACtD,OAAA,EAAS,YAAA,CAAa,IAAA,IACrB,UAAA,CAAW,IAAA"}

package/dist/index.js

@@ -1,12 +1,12 @@
 import { createCliLogger } from "./lib/logger.js";
-import { i as createSpinner, r as createPromptUtils } from "./prompts-lLfUSgd6.js";
-import { n as DEFAULT_EXIT_CODE, t as createConfigClient } from "./config-BvGapuFJ.js";
-import { n as decorateContext, t as middleware } from "./middleware-D3psyhYo.js";
-import "./project-NPtYX2ZX.js";
+import { n as DEFAULT_EXIT_CODE, t as createConfigClient } from "./config-Db_sjFU-.js";
+import { n as decorateContext, t as middleware } from "./middleware-BFBKNSPQ.js";
+import "./project-DuXgjaa_.js";
 import { basename, extname, join, resolve } from "node:path";
 import { loadConfig } from "@kidd-cli/config/loader";
 import { attemptAsync, err, isPlainObject, isString, ok } from "@kidd-cli/utils/fp";
 import yargs from "yargs";
+import * as clack from "@clack/prompts";
 import { TAG, hasTag, withTag } from "@kidd-cli/utils/tag";
 import { jsonStringify } from "@kidd-cli/utils/json";
 import { readdir } from "node:fs/promises";
@@ -198,26 +198,24 @@ function writeTableToStream(stream, rows, keys) {
 /**
 * Create the interactive prompt methods for a context.
 *
-* @private
 * @returns A Prompts instance backed by clack.
 */
 function createContextPrompts() {
-	const utils = createPromptUtils();
 	return {
 		async confirm(opts) {
-			return unwrapCancelSignal(utils, await utils.confirm(opts));
+			return unwrapCancelSignal(await clack.confirm(opts));
 		},
 		async multiselect(opts) {
-			return unwrapCancelSignal(utils, await utils.multiselect(opts));
+			return unwrapCancelSignal(await clack.multiselect(opts));
 		},
 		async password(opts) {
-			return unwrapCancelSignal(utils, await utils.password(opts));
+			return unwrapCancelSignal(await clack.password(opts));
 		},
 		async select(opts) {
-			return unwrapCancelSignal(utils, await utils.select(opts));
+			return unwrapCancelSignal(await clack.select(opts));
 		},
 		async text(opts) {
-			return unwrapCancelSignal(utils, await utils.text(opts));
+			return unwrapCancelSignal(await clack.text(opts));
 		}
 	};
 }
@@ -228,13 +226,12 @@ function createContextPrompts() {
 * the typed result value.
 *
 * @private
-* @param utils - The prompt utils instance (for isCancel and cancel).
 * @param result - The raw prompt result (value or cancel symbol).
 * @returns The unwrapped typed value.
 */
-function unwrapCancelSignal(utils, result) {
-	if (utils.isCancel(result)) {
-		utils.cancel("Operation cancelled.");
+function unwrapCancelSignal(result) {
+	if (clack.isCancel(result)) {
+		clack.cancel("Operation cancelled.");
 		throw createContextError("Prompt cancelled by user", {
 			code: "PROMPT_CANCELLED",
 			exitCode: DEFAULT_EXIT_CODE
@@ -286,7 +283,7 @@ function createMemoryStore() {
 */
 function createContext(options) {
 	const ctxLogger = options.logger ?? createCliLogger();
-	const ctxSpinner = createSpinner();
+	const ctxSpinner = clack.spinner();
 	const ctxOutput = createContextOutput(options.output ?? process.stdout);
 	const ctxStore = createMemoryStore();
 	const ctxPrompts = createContextPrompts();
@@ -1022,7 +1019,11 @@ function exitOnError(error, logger) {
 /**
 * Define a CLI command with typed args, config, and handler.
 *
-* @param def - Command definition including description, args schema, and handler.
+* The `const TMiddleware` generic preserves the middleware tuple as a literal type,
+* enabling TypeScript to extract and intersect `Variables` from each middleware
+* element onto the handler's `ctx` type.
+*
+* @param def - Command definition including description, args schema, middleware, and handler.
 * @returns A resolved Command object for registration in the command map.
 */
 function command(def) {