@kidd-cli/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Joggr, Inc.
+
+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,214 @@
+# kidd
+
+An opinionated CLI framework for Node.js built on yargs and Zod.
+
+## Installation
+
+```bash
+pnpm add kidd
+```
+
+## Usage
+
+```ts
+import { cli, command } from 'kidd'
+import { z } from 'zod'
+
+const greet = command({
+  description: 'Greet a user',
+  args: z.object({
+    name: z.string().describe('Name to greet'),
+  }),
+  async handler(ctx) {
+    ctx.logger.info(`Hello, ${ctx.args.name}!`)
+  },
+})
+
+await cli({
+  name: 'my-app',
+  version: '1.0.0',
+  commands: { greet },
+})
+```
+
+## API
+
+### `cli()`
+
+Bootstrap and run the CLI application.
+
+```ts
+cli({
+  name: 'my-app',
+  version: '1.0.0',
+  description: 'My CLI tool',
+  commands: { deploy, migrate },
+  middleware: [requireAuth()],
+  config: { schema: MyConfigSchema },
+  credentials: {
+    apiKey: { env: 'API_KEY', required: true },
+  },
+})
+```
+
+### `command()`
+
+Create a command definition.
+
+```ts
+const deploy = command({
+  description: 'Deploy the application',
+  args: z.object({
+    env: z.enum(['staging', 'production']).describe('Target environment'),
+    dryRun: z.boolean().default(false).describe('Preview without applying'),
+  }),
+  async handler(ctx) {
+    ctx.logger.info(`Deploying to ${ctx.args.env}`)
+  },
+})
+```
+
+### `middleware()`
+
+Create a middleware that runs before command handlers.
+
+```ts
+const timing = middleware(async (ctx, next) => {
+  const start = Date.now()
+  await next()
+  ctx.logger.info(`Completed in ${Date.now() - start}ms`)
+})
+```
+
+### `autoload()`
+
+Dynamically discover commands from a directory.
+
+```ts
+cli({
+  name: 'my-app',
+  version: '1.0.0',
+  commands: {
+    generate: autoload({ dir: './commands/generate' }),
+  },
+})
+```
+
+### `defineConfig()`
+
+Type-safe helper for `kidd.config.ts` files.
+
+```ts
+import { defineConfig } from 'kidd'
+
+export default defineConfig({
+  build: { out: 'dist' },
+})
+```
+
+## Sub-exports
+
+### `kidd/prompts`
+
+Interactive terminal prompts backed by `@clack/prompts`.
+
+```ts
+import { prompts, spinner } from 'kidd/prompts'
+
+const name = await prompts.text({ message: 'Project name?' })
+
+spinner.start('Building...')
+spinner.stop('Done')
+```
+
+### `kidd/logger`
+
+Structured terminal logger backed by `@clack/prompts`.
+
+```ts
+import { log } from 'kidd/logger'
+
+log.intro('My CLI')
+log.info('Processing...')
+log.success('Complete')
+log.outro('Done')
+```
+
+### `kidd/output`
+
+Structured output for JSON, templates, and files.
+
+```ts
+import { output } from 'kidd/output'
+
+output.json({ status: 'ok' })
+output.write({ path: './out.json', content: output.toJson(data) })
+```
+
+### `kidd/errors`
+
+Error creation, formatting, and sanitization utilities.
+
+```ts
+import { createErrorUtil, sanitize } from 'kidd/errors'
+
+const errors = createErrorUtil({ prefix: 'deploy', sanitize: true })
+const err = errors.create('Connection refused')
+const msg = errors.getMessage(unknownError)
+const clean = sanitize('token=abc123&secret=xyz')
+```
+
+### `kidd/config`
+
+Typed config client for JSON/JSONC/YAML files.
+
+```ts
+import { createConfigClient } from 'kidd/config'
+
+const config = createConfigClient({ name: 'my-app', schema: MySchema })
+const [error, result] = await config.load()
+```
+
+### `kidd/store`
+
+File-backed JSON store with local and global resolution.
+
+```ts
+import { createStore } from 'kidd/store'
+
+const store = createStore({ dirName: '.my-app' })
+const settings = store.load('settings.json')
+```
+
+### `kidd/validate`
+
+Zod-based validation returning Result tuples.
+
+```ts
+import { validate } from 'kidd/validate'
+
+const [error, value] = validate(
+  MySchema,
+  input,
+  (zodError) => new Error(`Invalid: ${zodError.message}`)
+)
+```
+
+### `kidd/project`
+
+Git project root resolution, submodule detection, and dotenv loading.
+
+```ts
+import { findProjectRoot, createDotEnv, isInSubmodule } from 'kidd/project'
+
+const root = findProjectRoot()
+const env = createDotEnv({ dirName: '.my-app' })
+const vars = await env.load()
+const submodule = isInSubmodule()
+```
+
+## References
+
+- [yargs](https://yargs.js.org)
+- [Zod](https://zod.dev)
+- [@clack/prompts](https://www.clack.cc)

package/dist/config-BvGapuFJ.js

@@ -0,0 +1,282 @@
+import { i as findProjectRoot } from "./project-NPtYX2ZX.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 { formatZodIssues } from "@kidd-cli/utils/validate";
+import { parse, printParseErrorCode } from "jsonc-parser";
+import { parse as parse$1, stringify } from "yaml";
+
+//#region src/utils/constants.ts
+/**
+* Default process exit code for error conditions.
+*/
+const DEFAULT_EXIT_CODE = 1;
+
+//#endregion
+//#region src/lib/config/constants.ts
+const EMPTY_LENGTH = 0;
+const CONFIG_EXTENSIONS = [
+	".jsonc",
+	".json",
+	".yaml"
+];
+
+//#endregion
+//#region src/lib/config/find.ts
+/**
+* Generate the list of config file names to search for based on the CLI name.
+*
+* Produces names like `.myapp.jsonc`, `.myapp.json`, `.myapp.yaml` from the
+* supported extension list.
+*
+* @param name - The CLI name used to derive config file names.
+* @returns An array of config file names to search for.
+*/
+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,
+* and the project root (if different from cwd). Returns the path of the
+* first matching file found.
+*
+* @param options - Search options including cwd, file names, and optional search paths.
+* @returns The full path to the config file, or null if not found.
+*/
+async function findConfig(options) {
+	const { fileNames, cwd, searchPaths } = options;
+	if (searchPaths) {
+		const found = (await Promise.all(searchPaths.map((dir) => findConfigFile(dir, fileNames)))).find((result) => result !== null);
+		if (found) return found;
+	}
+	const fromCwd = await findConfigFile(cwd, fileNames);
+	if (fromCwd) return fromCwd;
+	const projectRoot = findProjectRoot(cwd);
+	if (projectRoot && projectRoot.path !== cwd) {
+		const fromRoot = await findConfigFile(projectRoot.path, fileNames);
+		if (fromRoot) return fromRoot;
+	}
+	return null;
+}
+
+//#endregion
+//#region src/lib/config/parse.ts
+/**
+* Determine the config format from a file path's extension.
+*
+* @param filePath - The file path to inspect.
+* @returns The detected config format ('json', 'jsonc', or 'yaml').
+*/
+function getFormat(filePath) {
+	return match(extname(filePath)).with(".jsonc", () => "jsonc").with(".yaml", () => "yaml").otherwise(() => "json");
+}
+/**
+* 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.
+*/
+function parseJson(content, filePath) {
+	const [error, result] = jsonParse(content);
+	if (error) return err(`Failed to parse JSON in ${filePath}: ${error.message}`);
+	return [null, result];
+}
+/**
+* Parse a JSONC (JSON with comments) string and return the result as a ConfigOperationResult.
+*
+* @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.
+*/
+function parseJsoncContent(content, filePath) {
+	const errors = [];
+	const result = parse(content, errors, {
+		allowEmptyContent: false,
+		allowTrailingComma: true
+	});
+	if (errors.length > EMPTY_LENGTH) return err(`Failed to parse JSONC in ${filePath}:\n${errors.map((parseError) => `  - ${printParseErrorCode(parseError.error)} at offset ${parseError.offset}`).join("\n")}`);
+	return [null, result];
+}
+/**
+* Parse a YAML string and return the result as a ConfigOperationResult.
+*
+* @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.
+*/
+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
+/**
+* Create a typed config client that loads, validates, and writes config files.
+*
+* @param options - Config client options including name and Zod schema.
+* @returns A {@link Config} client instance.
+*/
+function createConfigClient(options) {
+	const { name, schema, searchPaths } = options;
+	const fileNames = getConfigFileNames(name);
+	/**
+	* Find a config file in the given directory.
+	*
+	* @private
+	* @param cwd - Working directory to search from.
+	* @returns The path to the config file, or null if not found.
+	*/
+	async function find(cwd) {
+		return findConfig({
+			cwd: cwd ?? process.cwd(),
+			fileNames,
+			searchPaths
+		});
+	}
+	/**
+	* Load and validate a config file.
+	*
+	* @private
+	* @param cwd - Working directory to search from.
+	* @returns A ConfigOperationResult with the loaded config, or [null, null] if not found.
+	*/
+	async function load(cwd) {
+		const filePath = await find(cwd);
+		if (!filePath) return [null, null];
+		const [readError, content] = await attemptAsync(() => readFile(filePath, "utf8"));
+		if (readError || content === null) return err(`Failed to read config at ${filePath}: ${resolveReadErrorDetail(readError)}`);
+		const format = getFormat(filePath);
+		const parsedResult = parseContent({
+			content,
+			filePath,
+			format
+		});
+		if (parsedResult[0]) return [parsedResult[0], null];
+		const result = schema.safeParse(parsedResult[1]);
+		if (!result.success) {
+			const { message } = formatZodIssues(result.error.issues, "\n");
+			return err(`Invalid config in ${filePath}:\n${message}`);
+		}
+		return [null, {
+			config: result.data,
+			filePath,
+			format
+		}];
+	}
+	/**
+	* Validate and write config data to a file.
+	*
+	* @private
+	* @param data - The config data to write.
+	* @param writeOptions - Write options including path and format.
+	* @returns A ConfigOperationResult with the write result.
+	*/
+	async function write(data, writeOptions = {}) {
+		const result = schema.safeParse(data);
+		if (!result.success) {
+			const { message } = formatZodIssues(result.error.issues, "\n");
+			return err(`Invalid config data:\n${message}`);
+		}
+		const resolvedFormat = match(writeOptions).when((opts) => opts.format !== null && opts.format !== void 0, (opts) => opts.format ?? "jsonc").when((opts) => opts.filePath !== null && opts.filePath !== void 0, (opts) => getFormat(opts.filePath ?? "")).otherwise(() => "jsonc");
+		const resolvedFilePath = match(writeOptions.filePath).when((fp) => fp !== null && fp !== void 0, (fp) => fp ?? "").otherwise(() => {
+			return join(writeOptions.dir ?? process.cwd(), `.${name}${getExtension(resolvedFormat)}`);
+		});
+		const serialized = serializeContent(result.data, resolvedFormat);
+		const [mkdirError] = await attemptAsync(() => mkdir(dirname(resolvedFilePath), { recursive: true }));
+		if (mkdirError) return err(`Failed to create directory for ${resolvedFilePath}: ${String(mkdirError)}`);
+		const [writeError] = await attemptAsync(() => writeFile(resolvedFilePath, serialized, "utf8"));
+		if (writeError) return err(`Failed to write config to ${resolvedFilePath}: ${String(writeError)}`);
+		return [null, {
+			filePath: resolvedFilePath,
+			format: resolvedFormat
+		}];
+	}
+	return {
+		find,
+		load,
+		write
+	};
+}
+/**
+* Resolve the error detail string from a read error.
+*
+* @private
+* @param readError - The error from the read operation, or null.
+* @returns A descriptive error string.
+*/
+function resolveReadErrorDetail(readError) {
+	if (readError) return String(readError);
+	return "empty file";
+}
+
+//#endregion
+export { DEFAULT_EXIT_CODE as n, createConfigClient as t };
+//# sourceMappingURL=config-BvGapuFJ.js.map

package/dist/config-BvGapuFJ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-BvGapuFJ.js","names":["parseJsonc","parseYaml","stringifyYaml"],"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 { access } from 'node:fs/promises'\nimport { join } from 'node:path'\n\nimport { attemptAsync } from '@kidd-cli/utils/fp'\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 * Check whether a file exists at the given path.\n *\n * @param filePath - The absolute file path to check.\n * @returns True when the file exists and is accessible.\n */\nexport async function fileExists(filePath: string): Promise<boolean> {\n  const [error] = await attemptAsync(() => access(filePath))\n  return !error\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 */\nexport async 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\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","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 * 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 */\nexport function 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 */\nexport function 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 */\nexport function 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\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","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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"}