@kidd-cli/config 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/dist/index.d.ts

@@ -0,0 +1,17 @@
+import { i as KiddConfig, n as CompileOptions, r as CompileTarget, t as BuildOptions } from "./types-DZWypERH.js";
+import { Tagged } from "@kidd-cli/utils/tag";
+
+//#region src/define-config.d.ts
+/**
+* Type-safe helper for kidd.config.ts.
+*
+* Tags the config with `'KiddConfig'` so consumers can verify
+* it was created through `defineConfig` at runtime via `hasTag`.
+*
+* @param config - The build configuration object.
+* @returns A tagged copy of the config.
+*/
+declare function defineConfig(config: KiddConfig): Tagged<KiddConfig, "KiddConfig">;
+//#endregion
+export { type BuildOptions, type CompileOptions, type CompileTarget, type KiddConfig, defineConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/define-config.ts"],"mappings":";;;;;;AAcA;;;;;;;iBAAgB,YAAA,CAAa,MAAA,EAAQ,UAAA,GAAa,MAAA,CAAO,UAAA"}

package/dist/index.js

@@ -0,0 +1,19 @@
+import { withTag } from "@kidd-cli/utils/tag";
+
+//#region src/define-config.ts
+/**
+* Type-safe helper for kidd.config.ts.
+*
+* Tags the config with `'KiddConfig'` so consumers can verify
+* it was created through `defineConfig` at runtime via `hasTag`.
+*
+* @param config - The build configuration object.
+* @returns A tagged copy of the config.
+*/
+function defineConfig(config) {
+	return withTag(config, "KiddConfig");
+}
+
+//#endregion
+export { defineConfig };
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/define-config.ts"],"sourcesContent":["import type { Tagged } from '@kidd-cli/utils/tag'\nimport { withTag } from '@kidd-cli/utils/tag'\n\nimport type { KiddConfig } from './types.js'\n\n/**\n * Type-safe helper for kidd.config.ts.\n *\n * Tags the config with `'KiddConfig'` so consumers can verify\n * it was created through `defineConfig` at runtime via `hasTag`.\n *\n * @param config - The build configuration object.\n * @returns A tagged copy of the config.\n */\nexport function defineConfig(config: KiddConfig): Tagged<KiddConfig, 'KiddConfig'> {\n  return withTag(config, 'KiddConfig')\n}\n"],"mappings":";;;;;;;;;;;;AAcA,SAAgB,aAAa,QAAsD;AACjF,QAAO,QAAQ,QAAQ,aAAa"}

package/dist/loader.d.ts

@@ -0,0 +1,63 @@
+import { i as KiddConfig } from "./types-DZWypERH.js";
+import { Tagged } from "@kidd-cli/utils/tag";
+import { AsyncResult, Result } from "@kidd-cli/utils";
+import { z } from "zod";
+
+//#region src/schema.d.ts
+/**
+* Zod schema validating the {@link KiddConfig} shape.
+*/
+declare const KiddConfigSchema: z.ZodType<KiddConfig>;
+/**
+* Validate arbitrary data against the {@link KiddConfigSchema}.
+*
+* @param data - The unknown value to validate.
+* @returns A Result tuple - `[null, KiddConfig]` on success or `[Error, null]` on failure.
+*/
+declare function validateConfig(data: unknown): Result<KiddConfig, Error>;
+//#endregion
+//#region src/loader.d.ts
+/**
+* Options for loading a kidd build config.
+*/
+interface LoadConfigOptions {
+  /**
+  * Working directory to search from.
+  */
+  readonly cwd?: string;
+  /**
+  * Default values merged under the loaded config.
+  */
+  readonly defaults?: Partial<KiddConfig>;
+  /**
+  * Override values merged over the loaded config.
+  */
+  readonly overrides?: Partial<KiddConfig>;
+}
+/**
+* Successful result of loading a kidd build config.
+*/
+interface LoadConfigResult {
+  /**
+  * The validated and tagged build config.
+  */
+  readonly config: Tagged<KiddConfig, "KiddConfig">;
+  /**
+  * Path to the resolved config file, or `undefined` when none was found.
+  */
+  readonly configFile: string | undefined;
+}
+/**
+* Load and validate a `kidd.config.ts` file using c12.
+*
+* Searches for a config file named `kidd` (e.g. `kidd.config.ts`, `kidd.config.mts`)
+* in the given working directory, validates it against the build config schema,
+* and returns a tagged config object.
+*
+* @param options - Optional loader configuration.
+* @returns A Result tuple - `[null, LoadConfigResult]` on success or `[Error, null]` on failure.
+*/
+declare function loadConfig(options?: LoadConfigOptions): AsyncResult<LoadConfigResult, Error>;
+//#endregion
+export { KiddConfigSchema, LoadConfigOptions, LoadConfigResult, loadConfig, validateConfig };
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","names":[],"sources":["../src/schema.ts","../src/loader.ts"],"mappings":";;;;;;;;;cA+Ca,gBAAA,EAAkB,CAAA,CAAE,OAAA,CAAQ,UAAA;;;;;;;iBAgBzB,cAAA,CAAe,IAAA,YAAgB,MAAA,CAAO,UAAA,EAAY,KAAA;;;;;AAhBlE;UC/BiB,iBAAA;;;;WAIN,GAAA;;;;WAIA,QAAA,GAAW,OAAA,CAAQ,UAAA;EDuCd;;;EAAA,SCnCL,SAAA,GAAY,OAAA,CAAQ,UAAA;AAAA;;;;UAMd,gBAAA;;;;WAIN,MAAA,EAAQ,MAAA,CAAO,UAAA;;;;WAIf,UAAA;AAAA;;;;;;;;;;;iBAaW,UAAA,CACpB,OAAA,GAAU,iBAAA,GACT,WAAA,CAAY,gBAAA,EAAkB,KAAA"}

package/dist/loader.js

@@ -0,0 +1,96 @@
+import { withTag } from "@kidd-cli/utils/tag";
+import { toErrorMessage } from "@kidd-cli/utils";
+import { err } from "@kidd-cli/utils/fp";
+import { loadConfig as loadConfig$1 } from "c12";
+import { attemptAsync } from "es-toolkit";
+import { formatZodIssues } from "@kidd-cli/utils/validate";
+import { z } from "zod";
+
+//#region src/schema.ts
+/**
+* @private
+*/
+const CompileTargetSchema = z.enum([
+	"darwin-arm64",
+	"darwin-x64",
+	"linux-arm64",
+	"linux-x64",
+	"linux-x64-musl",
+	"windows-arm64",
+	"windows-x64"
+]);
+/**
+* @private
+*/
+const BuildOptionsSchema = z.object({
+	external: z.array(z.string()).optional(),
+	minify: z.boolean().optional(),
+	out: z.string().optional(),
+	sourcemap: z.boolean().optional(),
+	target: z.string().optional()
+}).strict();
+/**
+* @private
+*/
+const CompileOptionsSchema = z.object({
+	name: z.string().optional(),
+	out: z.string().optional(),
+	targets: z.array(CompileTargetSchema).optional()
+}).strict();
+/**
+* Zod schema validating the {@link KiddConfig} shape.
+*/
+const KiddConfigSchema = z.object({
+	build: BuildOptionsSchema.optional(),
+	commands: z.string().optional(),
+	compile: z.union([z.boolean(), CompileOptionsSchema]).optional(),
+	entry: z.string().optional(),
+	include: z.array(z.string()).optional()
+}).strict();
+/**
+* Validate arbitrary data against the {@link KiddConfigSchema}.
+*
+* @param data - The unknown value to validate.
+* @returns A Result tuple - `[null, KiddConfig]` on success or `[Error, null]` on failure.
+*/
+function validateConfig(data) {
+	const result = KiddConfigSchema.safeParse(data);
+	if (!result.success) {
+		const { message } = formatZodIssues(result.error.issues);
+		return err(`Invalid kidd config:\n  ${message}`);
+	}
+	return [null, result.data];
+}
+
+//#endregion
+//#region src/loader.ts
+/**
+* Load and validate a `kidd.config.ts` file using c12.
+*
+* Searches for a config file named `kidd` (e.g. `kidd.config.ts`, `kidd.config.mts`)
+* in the given working directory, validates it against the build config schema,
+* and returns a tagged config object.
+*
+* @param options - Optional loader configuration.
+* @returns A Result tuple - `[null, LoadConfigResult]` on success or `[Error, null]` on failure.
+*/
+async function loadConfig(options) {
+	const { cwd, defaults, overrides } = options ?? {};
+	const [loadError, loaded] = await attemptAsync(() => loadConfig$1({
+		cwd,
+		defaults,
+		name: "kidd",
+		overrides
+	}));
+	if (loadError || !loaded) return err(`Failed to load kidd config: ${toErrorMessage(loadError)}`);
+	const [validateError, config] = validateConfig(loaded.config);
+	if (validateError) return [validateError, null];
+	return [null, {
+		config: withTag(config, "KiddConfig"),
+		configFile: loaded.configFile
+	}];
+}
+
+//#endregion
+export { KiddConfigSchema, loadConfig, validateConfig };
+//# sourceMappingURL=loader.js.map

package/dist/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","names":["c12LoadConfig"],"sources":["../src/schema.ts","../src/loader.ts"],"sourcesContent":["import type { Result } from '@kidd-cli/utils'\nimport { err } from '@kidd-cli/utils/fp'\nimport { formatZodIssues } from '@kidd-cli/utils/validate'\nimport { z } from 'zod'\n\nimport type { KiddConfig } from './types.js'\n\n/**\n * @private\n */\nconst CompileTargetSchema = z.enum([\n  'darwin-arm64',\n  'darwin-x64',\n  'linux-arm64',\n  'linux-x64',\n  'linux-x64-musl',\n  'windows-arm64',\n  'windows-x64',\n])\n\n/**\n * @private\n */\nconst BuildOptionsSchema = z\n  .object({\n    external: z.array(z.string()).optional(),\n    minify: z.boolean().optional(),\n    out: z.string().optional(),\n    sourcemap: z.boolean().optional(),\n    target: z.string().optional(),\n  })\n  .strict()\n\n/**\n * @private\n */\nconst CompileOptionsSchema = z\n  .object({\n    name: z.string().optional(),\n    out: z.string().optional(),\n    targets: z.array(CompileTargetSchema).optional(),\n  })\n  .strict()\n\n/**\n * Zod schema validating the {@link KiddConfig} shape.\n */\nexport const KiddConfigSchema: z.ZodType<KiddConfig> = z\n  .object({\n    build: BuildOptionsSchema.optional(),\n    commands: z.string().optional(),\n    compile: z.union([z.boolean(), CompileOptionsSchema]).optional(),\n    entry: z.string().optional(),\n    include: z.array(z.string()).optional(),\n  })\n  .strict()\n\n/**\n * Validate arbitrary data against the {@link KiddConfigSchema}.\n *\n * @param data - The unknown value to validate.\n * @returns A Result tuple - `[null, KiddConfig]` on success or `[Error, null]` on failure.\n */\nexport function validateConfig(data: unknown): Result<KiddConfig, Error> {\n  const result = KiddConfigSchema.safeParse(data)\n  if (!result.success) {\n    const { message } = formatZodIssues(result.error.issues)\n    return err(`Invalid kidd config:\\n  ${message}`)\n  }\n  return [null, result.data]\n}\n","import { toErrorMessage } from '@kidd-cli/utils'\nimport type { AsyncResult } from '@kidd-cli/utils'\nimport { err } from '@kidd-cli/utils/fp'\nimport type { Tagged } from '@kidd-cli/utils/tag'\nimport { withTag } from '@kidd-cli/utils/tag'\nimport { loadConfig as c12LoadConfig } from 'c12'\nimport { attemptAsync } from 'es-toolkit'\n\nimport { validateConfig } from './schema.js'\nimport type { KiddConfig } from './types.js'\n\nexport { KiddConfigSchema, validateConfig } from './schema.js'\n\n/**\n * Options for loading a kidd build config.\n */\nexport interface LoadConfigOptions {\n  /**\n   * Working directory to search from.\n   */\n  readonly cwd?: string\n  /**\n   * Default values merged under the loaded config.\n   */\n  readonly defaults?: Partial<KiddConfig>\n  /**\n   * Override values merged over the loaded config.\n   */\n  readonly overrides?: Partial<KiddConfig>\n}\n\n/**\n * Successful result of loading a kidd build config.\n */\nexport interface LoadConfigResult {\n  /**\n   * The validated and tagged build config.\n   */\n  readonly config: Tagged<KiddConfig, 'KiddConfig'>\n  /**\n   * Path to the resolved config file, or `undefined` when none was found.\n   */\n  readonly configFile: string | undefined\n}\n\n/**\n * Load and validate a `kidd.config.ts` file using c12.\n *\n * Searches for a config file named `kidd` (e.g. `kidd.config.ts`, `kidd.config.mts`)\n * in the given working directory, validates it against the build config schema,\n * and returns a tagged config object.\n *\n * @param options - Optional loader configuration.\n * @returns A Result tuple - `[null, LoadConfigResult]` on success or `[Error, null]` on failure.\n */\nexport async function loadConfig(\n  options?: LoadConfigOptions\n): AsyncResult<LoadConfigResult, Error> {\n  const { cwd, defaults, overrides } = options ?? {}\n\n  const [loadError, loaded] = await attemptAsync(() =>\n    c12LoadConfig({\n      cwd,\n      defaults,\n      name: 'kidd',\n      overrides,\n    })\n  )\n\n  if (loadError || !loaded) {\n    return err(`Failed to load kidd config: ${toErrorMessage(loadError)}`)\n  }\n\n  const [validateError, config] = validateConfig(loaded.config)\n  if (validateError) {\n    return [validateError, null]\n  }\n\n  return [\n    null,\n    {\n      config: withTag(config, 'KiddConfig'),\n      configFile: loaded.configFile,\n    },\n  ]\n}\n"],"mappings":";;;;;;;;;;;;AAUA,MAAM,sBAAsB,EAAE,KAAK;CACjC;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;;;;AAKF,MAAM,qBAAqB,EACxB,OAAO;CACN,UAAU,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,UAAU;CACxC,QAAQ,EAAE,SAAS,CAAC,UAAU;CAC9B,KAAK,EAAE,QAAQ,CAAC,UAAU;CAC1B,WAAW,EAAE,SAAS,CAAC,UAAU;CACjC,QAAQ,EAAE,QAAQ,CAAC,UAAU;CAC9B,CAAC,CACD,QAAQ;;;;AAKX,MAAM,uBAAuB,EAC1B,OAAO;CACN,MAAM,EAAE,QAAQ,CAAC,UAAU;CAC3B,KAAK,EAAE,QAAQ,CAAC,UAAU;CAC1B,SAAS,EAAE,MAAM,oBAAoB,CAAC,UAAU;CACjD,CAAC,CACD,QAAQ;;;;AAKX,MAAa,mBAA0C,EACpD,OAAO;CACN,OAAO,mBAAmB,UAAU;CACpC,UAAU,EAAE,QAAQ,CAAC,UAAU;CAC/B,SAAS,EAAE,MAAM,CAAC,EAAE,SAAS,EAAE,qBAAqB,CAAC,CAAC,UAAU;CAChE,OAAO,EAAE,QAAQ,CAAC,UAAU;CAC5B,SAAS,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC,UAAU;CACxC,CAAC,CACD,QAAQ;;;;;;;AAQX,SAAgB,eAAe,MAA0C;CACvE,MAAM,SAAS,iBAAiB,UAAU,KAAK;AAC/C,KAAI,CAAC,OAAO,SAAS;EACnB,MAAM,EAAE,YAAY,gBAAgB,OAAO,MAAM,OAAO;AACxD,SAAO,IAAI,2BAA2B,UAAU;;AAElD,QAAO,CAAC,MAAM,OAAO,KAAK;;;;;;;;;;;;;;;ACd5B,eAAsB,WACpB,SACsC;CACtC,MAAM,EAAE,KAAK,UAAU,cAAc,WAAW,EAAE;CAElD,MAAM,CAAC,WAAW,UAAU,MAAM,mBAChCA,aAAc;EACZ;EACA;EACA,MAAM;EACN;EACD,CAAC,CACH;AAED,KAAI,aAAa,CAAC,OAChB,QAAO,IAAI,+BAA+B,eAAe,UAAU,GAAG;CAGxE,MAAM,CAAC,eAAe,UAAU,eAAe,OAAO,OAAO;AAC7D,KAAI,cACF,QAAO,CAAC,eAAe,KAAK;AAG9B,QAAO,CACL,MACA;EACE,QAAQ,QAAQ,QAAQ,aAAa;EACrC,YAAY,OAAO;EACpB,CACF"}

package/dist/types-DZWypERH.d.ts

@@ -0,0 +1,79 @@
+//#region src/types.d.ts
+/**
+* Build options passed to tsdown during `kidd build`.
+*/
+interface BuildOptions {
+  /**
+  * Build output directory. Default: './dist'.
+  */
+  out?: string;
+  /**
+  * Node target version. Default: 'node18'.
+  */
+  target?: string;
+  /**
+  * Minify the output. Default: false.
+  */
+  minify?: boolean;
+  /**
+  * Generate source maps. Default: true.
+  */
+  sourcemap?: boolean;
+  /**
+  * Additional external packages (beyond kidd's defaults).
+  */
+  external?: string[];
+}
+/**
+* Binary compilation options for `kidd compile`.
+*/
+interface CompileOptions {
+  /**
+  * Compile output directory. Default: './dist'.
+  */
+  out?: string;
+  /**
+  * Cross-compilation targets. Default: current platform only.
+  */
+  targets?: CompileTarget[];
+  /**
+  * Binary name. Defaults to cli name.
+  */
+  name?: string;
+}
+/**
+* Supported cross-compilation targets for `kidd compile`.
+*/
+type CompileTarget = "darwin-arm64" | "darwin-x64" | "linux-x64" | "linux-arm64" | "linux-x64-musl" | "windows-x64" | "windows-arm64";
+/**
+* Configuration for kidd.config.ts.
+*/
+interface KiddConfig {
+  /**
+  * Entry point for the CLI. Default: './index.ts'.
+  */
+  entry?: string;
+  /**
+  * Where commands live. Default: './commands'.
+  */
+  commands?: string;
+  /**
+  * Build options for kidd build.
+  */
+  build?: BuildOptions;
+  /**
+  * Binary compilation options for kidd build --compile.
+  *
+  * - `true` enables compilation with default options.
+  * - An object provides explicit compile options (targets, output dir, name).
+  * - `false` or omitted disables compilation.
+  */
+  compile?: boolean | CompileOptions;
+  /**
+  * Extra file globs to include in the bundle.
+  */
+  include?: string[];
+}
+//#endregion
+export { KiddConfig as i, CompileOptions as n, CompileTarget as r, BuildOptions as t };
+//# sourceMappingURL=types-DZWypERH.d.ts.map

package/dist/types-DZWypERH.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-DZWypERH.d.ts","names":[],"sources":["../src/types.ts"],"mappings":";;AAGA;;UAAiB,YAAA;EAAA;;;EAIf,GAAA;;;;EAIA,MAAA;EAkBF;;;EAdE,MAAA;;;;EAIA,SAAA;;;AA4BF;EAxBE,QAAA;AAAA;;;AAoCF;UA9BiB,cAAA;;;;EAIf,GAAA;;;;EAIA,OAAA,GAAU,aAAA;;;;EAIV,IAAA;AAAA;;;;KAMU,aAAA;;;;UAYK,UAAA;;;;EAIf,KAAA;;;;EAIA,QAAA;;;;EAIA,KAAA,GAAQ,YAAA;;;;;;;;EAQR,OAAA,aAAoB,cAAA;;;;EAIpB,OAAA;AAAA"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@kidd-cli/config",
+  "version": "0.1.0",
+  "description": "Build-time configuration for kidd CLIs",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./loader": {
+      "types": "./dist/loader.d.ts",
+      "default": "./dist/loader.js"
+    }
+  },
+  "dependencies": {
+    "c12": "4.0.0-beta.3",
+    "es-toolkit": "^1.45.0",
+    "zod": "^4.3.6",
+    "@kidd-cli/utils": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.3",
+    "tsdown": "0.21.0-beta.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsgo --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}