@kidd-cli/cli 0.1.4 → 0.3.0

package/dist/commands/add/command.mjs

@@ -1,5 +1,6 @@
-import { n as isKebabCase, r as renderTemplate, t as writeFiles } from "../../write-CdoqLFeH.mjs";
-import { t as detectProject } from "../../detect-DcO0_CWy.mjs";
+import { n as renderTemplate, t as writeFiles } from "../../write-BF8u0sRy.mjs";
+import { t as isKebabCase } from "../../validate-D3mbQfJT.mjs";
+import { t as detectProject } from "../../detect-Cxj1jrYq.mjs";
 import { command } from "@kidd-cli/core";
 import { join } from "node:path";
 import { loadConfig } from "@kidd-cli/config/loader";
@@ -48,7 +49,7 @@ const addCommandCommand = command({
 		}
 		ctx.spinner.stop("Command created!");
 		const summary = [...result.written.map((file) => `  created ${file}`), ...result.skipped.map((file) => `  skipped ${file} (already exists)`)].join("\n");
-		if (summary.length > 0) ctx.output.raw(summary);
+		if (summary.length > 0) ctx.logger.print(summary);
 	}
 });
 /**

package/dist/commands/add/config.d.mts

@@ -0,0 +1,6 @@
+import { Command } from "@kidd-cli/core";
+
+//#region src/commands/add/config.d.ts
+declare const addConfigCommand: Command;
+//#endregion
+export { addConfigCommand as default };

package/dist/commands/add/config.mjs

@@ -0,0 +1,55 @@
+import { n as renderTemplate, t as writeFiles } from "../../write-BF8u0sRy.mjs";
+import { t as detectProject } from "../../detect-Cxj1jrYq.mjs";
+import { command } from "@kidd-cli/core";
+import { join } from "node:path";
+import { readManifest } from "@kidd-cli/utils/manifest";
+//#region src/commands/add/config.ts
+const addConfigCommand = command({
+	description: "Add a config schema to your project",
+	handler: async (ctx) => {
+		const [detectError, project] = await detectProject(process.cwd());
+		if (detectError) return ctx.fail(detectError.message);
+		if (!project) return ctx.fail("Not in a kidd project. Run `kidd init` first.");
+		const projectName = await resolveProjectName(project.rootDir);
+		ctx.spinner.start("Generating config...");
+		const [renderError, rendered] = await renderTemplate({
+			templateDir: join(import.meta.dirname, "..", "..", "lib", "templates", "config"),
+			variables: { name: projectName }
+		});
+		if (renderError) {
+			ctx.spinner.stop("Failed");
+			return ctx.fail(renderError.message);
+		}
+		const [writeError, result] = await writeFiles({
+			files: rendered,
+			outputDir: join(project.rootDir, "src"),
+			overwrite: false
+		});
+		if (writeError) {
+			ctx.spinner.stop("Failed");
+			return ctx.fail(writeError.message);
+		}
+		ctx.spinner.stop("Config created!");
+		const summary = [...result.written.map((file) => `  created ${file}`), ...result.skipped.map((file) => `  skipped ${file} (already exists)`)].join("\n");
+		if (summary.length > 0) ctx.logger.print(summary);
+		ctx.logger.newline();
+		ctx.logger.print("Next steps:");
+		ctx.logger.print("  1. Add fields to the config schema in src/config.ts");
+		ctx.logger.print("  2. Import and pass the schema to cli({ config: { schema: configSchema } })");
+	}
+});
+const DEFAULT_NAME = "my-app";
+/**
+* Resolve the project name from the project's package.json.
+*
+* @param rootDir - The project root directory.
+* @returns The project name from package.json, or a default fallback.
+* @private
+*/
+async function resolveProjectName(rootDir) {
+	const [error, manifest] = await readManifest(rootDir);
+	if (error || !manifest.name) return DEFAULT_NAME;
+	return manifest.name;
+}
+//#endregion
+export { addConfigCommand as default };

package/dist/commands/add/index.mjs

@@ -1,5 +1,5 @@
 import { command } from "@kidd-cli/core";
 //#region src/commands/add/index.ts
-const addCommand = command({ description: "Add a command or middleware to your project" });
+const addCommand = command({ description: "Add a command, middleware, or config to your project" });
 //#endregion
 export { addCommand as default };

package/dist/commands/add/middleware.mjs

@@ -1,5 +1,6 @@
-import { n as isKebabCase, r as renderTemplate, t as writeFiles } from "../../write-CdoqLFeH.mjs";
-import { t as detectProject } from "../../detect-DcO0_CWy.mjs";
+import { n as renderTemplate, t as writeFiles } from "../../write-BF8u0sRy.mjs";
+import { t as isKebabCase } from "../../validate-D3mbQfJT.mjs";
+import { t as detectProject } from "../../detect-Cxj1jrYq.mjs";
 import { command } from "@kidd-cli/core";
 import { join } from "node:path";
 import { z } from "zod";
@@ -43,7 +44,7 @@ const addMiddlewareCommand = command({
 		}
 		ctx.spinner.stop("Middleware created!");
 		const summary = [...result.written.map((file) => `  created ${file}`), ...result.skipped.map((file) => `  skipped ${file} (already exists)`)].join("\n");
-		if (summary.length > 0) ctx.output.raw(summary);
+		if (summary.length > 0) ctx.logger.print(summary);
 	}
 });
 /**

package/dist/commands/build.mjs

@@ -41,7 +41,8 @@ const buildCommand = command({
 			ctx.logger.note(formatBuildNote({
 				cwd,
 				entryFile: buildOutput.entryFile,
-				outDir: buildOutput.outDir
+				outDir: buildOutput.outDir,
+				version: buildOutput.version
 			}), "Bundle");
 			return;
 		}
@@ -63,7 +64,8 @@ const buildCommand = command({
 		ctx.logger.note(formatBuildNote({
 			cwd,
 			entryFile: buildOutput.entryFile,
-			outDir: buildOutput.outDir
+			outDir: buildOutput.outDir,
+			version: buildOutput.version
 		}), "Bundle");
 		ctx.logger.note(formatBinariesNote({
 			binaries: compileOutput.binaries,
@@ -133,7 +135,22 @@ function resolveExistingCompile(value) {
 * @returns A formatted string with entry and output directory.
 */
 function formatBuildNote(params) {
-	return [`entry   ${relative(params.cwd, params.entryFile)}`, `output  ${relative(params.cwd, params.outDir)}`].join("\n");
+	return [
+		`entry    ${relative(params.cwd, params.entryFile)}`,
+		`output   ${relative(params.cwd, params.outDir)}`,
+		...formatVersionLine(params.version)
+	].join("\n");
+}
+/**
+* Format a version line for the build note, if a version is available.
+*
+* @private
+* @param version - The version string, or undefined.
+* @returns A single-element array with the formatted line, or an empty array.
+*/
+function formatVersionLine(version) {
+	if (!version) return [];
+	return [`version  ${version}`];
 }
 /**
 * Format compiled binaries into an aligned, multi-line string for display.

package/dist/commands/commands.mjs

@@ -22,10 +22,10 @@ const commandsCommand = command({
 		const tree = await buildTree(await autoload({ dir: commandsDir }));
 		ctx.spinner.stop("Commands");
 		if (tree.length === 0) {
-			ctx.output.write("No commands found");
+			ctx.logger.print("No commands found");
 			return;
 		}
-		ctx.output.raw(`${renderTree(tree)}\n`);
+		ctx.logger.print(renderTree(tree));
 	}
 });
 /**
@@ -43,21 +43,79 @@ async function resolveSubcommands(commands) {
 /**
 * Recursively build a sorted tree of entries from a CommandMap.
 *
+* Commands listed in the order array appear first in the specified order;
+* omitted commands fall back to alphabetical sort.
+*
 * @private
 * @param commandMap - The map of command names to Command objects.
+* @param order - Optional array of command names defining display order.
 * @returns A sorted array of TreeEntry nodes.
 */
-async function buildTree(commandMap) {
-	const entries = Object.entries(commandMap).toSorted(([a], [b]) => a.localeCompare(b));
+async function buildTree(commandMap, order) {
+	const entries = sortEntries({
+		entries: Object.entries(commandMap),
+		order
+	});
 	return Promise.all(entries.map(async ([name, cmd]) => {
 		return {
-			children: await buildTree(await resolveSubcommands(cmd.commands)),
+			children: await buildTree(await resolveSubcommands(cmd.commands), cmd.order),
 			description: cmd.description ?? "",
 			name
 		};
 	}));
 }
 /**
+* Sort command entries with ordered names first (in specified order),
+* remaining names alphabetically.
+*
+* Validates the order array against available command names and logs a
+* warning for unknown or duplicate entries rather than failing silently.
+*
+* @private
+* @param params - The command entries and optional order array.
+* @returns Sorted array of entries.
+*/
+function sortEntries(params) {
+	const { entries, order } = params;
+	if (!order || order.length === 0) return entries.toSorted(([a], [b]) => a.localeCompare(b));
+	const validOrder = validateOrder({
+		commandNames: entries.map(([name]) => name),
+		order
+	});
+	const entryMap = new Map(entries);
+	const orderedSet = new Set(validOrder);
+	const ordered = validOrder.filter((name) => entryMap.has(name)).map((name) => [name, entryMap.get(name)]);
+	const remaining = entries.filter(([name]) => !orderedSet.has(name)).toSorted(([a], [b]) => a.localeCompare(b));
+	return [...ordered, ...remaining];
+}
+/**
+* Validate the order array by filtering out unknown and duplicate names.
+*
+* Logs warnings for invalid entries so developers see the mismatch
+* during `kidd commands` introspection, matching the runtime behaviour.
+*
+* @private
+* @param params - The order array and available command names.
+* @returns A deduplicated array of valid order names.
+*/
+function validateOrder(params) {
+	const { commandNames, order } = params;
+	const nameSet = new Set(commandNames);
+	const seen = /* @__PURE__ */ new Set();
+	return order.filter((name) => {
+		if (seen.has(name)) {
+			console.warn(`Warning: duplicate command name "${name}" in order array`);
+			return false;
+		}
+		seen.add(name);
+		if (!nameSet.has(name)) {
+			console.warn(`Warning: unknown command "${name}" in order array`);
+			return false;
+		}
+		return true;
+	});
+}
+/**
 * Render a tree of entries into an ASCII tree string.
 *
 * @private

package/dist/commands/doctor.mjs

@@ -538,7 +538,7 @@ const doctorCommand = command({
 			total: results.length,
 			warnings
 		});
-		ctx.output.raw(summary);
+		ctx.logger.print(summary);
 		if (failed > 0) ctx.fail(`${failed} ${pluralizeCheck(failed)} failed`);
 	}
 });
@@ -607,7 +607,7 @@ async function applyFixes(results, context) {
 */
 function displayResults(ctx, results, fixResults) {
 	const output = results.map((result) => formatResultLine(result, fixResults)).join("");
-	if (output.length > 0) ctx.output.raw(output);
+	if (output.length > 0) ctx.logger.print(output);
 }
 /**
 * Format a single check result line with optional hint.

package/dist/commands/init.mjs

@@ -1,4 +1,5 @@
-import { n as isKebabCase, r as renderTemplate, t as writeFiles } from "../write-CdoqLFeH.mjs";
+import { n as renderTemplate, t as writeFiles } from "../write-BF8u0sRy.mjs";
+import { t as isKebabCase } from "../validate-D3mbQfJT.mjs";
 import { createRequire } from "node:module";
 import { command } from "@kidd-cli/core";
 import { dirname, join } from "node:path";
@@ -26,6 +27,7 @@ const TSDOWN_VERSION = "^0.21.1";
 //#region src/commands/init.ts
 const initCommand = command({
 	args: z.object({
+		config: z.boolean().describe("Include config schema setup").optional(),
 		description: z.string().describe("Project description").optional(),
 		example: z.boolean().describe("Include example command").optional(),
 		name: z.string().describe("Project name (kebab-case)").optional(),
@@ -41,6 +43,7 @@ const initCommand = command({
 		const projectDescription = await resolveDescription(ctx);
 		const packageManager = await resolvePackageManager(ctx);
 		const includeExample = await resolveIncludeExample(ctx);
+		const includeConfig = await resolveIncludeConfig(ctx);
 		ctx.spinner.start("Scaffolding project...");
 		const coreVersion = await resolveDependencyVersion("@kidd-cli/core");
 		const cliVersion = await resolveSelfVersion();
@@ -50,6 +53,7 @@ const initCommand = command({
 				cliVersion,
 				coreVersion,
 				description: projectDescription,
+				includeConfig,
 				name: projectName,
 				packageManager,
 				tsdownVersion: TSDOWN_VERSION,
@@ -63,7 +67,10 @@ const initCommand = command({
 			return ctx.fail(renderError.message);
 		}
 		const [writeError] = await writeFiles({
-			files: selectFiles(includeExample, rendered),
+			files: selectFiles({
+				includeConfig,
+				includeExample
+			}, rendered),
 			outputDir: join(process.cwd(), projectName),
 			overwrite: false
 		});
@@ -72,10 +79,10 @@ const initCommand = command({
 			return ctx.fail(writeError.message);
 		}
 		ctx.spinner.stop("Project created!");
-		ctx.output.raw("");
-		ctx.output.raw(`Next steps:`);
-		ctx.output.raw(`  cd ${projectName}`);
-		ctx.output.raw(`  ${packageManager} install`);
+		ctx.logger.newline();
+		ctx.logger.print("Next steps:");
+		ctx.logger.print(`  cd ${projectName}`);
+		ctx.logger.print(`  ${packageManager} install`);
 	}
 });
 /**
@@ -155,26 +162,29 @@ async function resolveIncludeExample(ctx) {
 	});
 }
 /**
-* Select the rendered files to write, optionally excluding the example command.
+* Resolve whether to include config schema setup from args or prompt.
 *
-* @param includeExample - Whether to include the example hello command.
-* @param rendered - The full set of rendered files.
-* @returns The filtered file list.
+* @param ctx - Command context.
+* @returns True when the config schema file should be included.
 * @private
 */
-function selectFiles(includeExample, rendered) {
-	if (includeExample) return rendered;
-	return rendered.filter(excludeHelloCommand);
+async function resolveIncludeConfig(ctx) {
+	if (ctx.args.config !== void 0) return ctx.args.config;
+	return ctx.prompts.confirm({
+		initialValue: false,
+		message: "Include config schema?"
+	});
 }
 /**
-* Filter predicate that excludes the hello.ts example command.
+* Select the rendered files to write, optionally excluding the example command and config.
 *
-* @param file - A rendered file to check.
-* @returns True when the file is not the hello command.
+* @param options - Flags controlling which optional files to include.
+* @param rendered - The full set of rendered files.
+* @returns The filtered file list.
 * @private
 */
-function excludeHelloCommand(file) {
-	return !file.relativePath.includes("commands/hello.ts");
+function selectFiles(options, rendered) {
+	return rendered.filter((file) => options.includeExample || !file.relativePath.includes("commands/hello.ts")).filter((file) => options.includeConfig || !file.relativePath.includes("config.ts"));
 }
 const DEFAULT_VERSION = "0.0.0";
 /**
@@ -189,7 +199,10 @@ const DEFAULT_VERSION = "0.0.0";
 */
 async function resolveSelfVersion() {
 	const [error, manifest] = await readManifest(join(import.meta.dirname, "..", ".."));
-	if (error || !manifest.version) return DEFAULT_VERSION;
+	if (error || !manifest.version) {
+		console.warn("Warning: Could not resolve CLI version, using fallback 0.0.0");
+		return DEFAULT_VERSION;
+	}
 	return manifest.version;
 }
 /**
@@ -206,9 +219,15 @@ async function resolveSelfVersion() {
 async function resolveDependencyVersion(packageName) {
 	const require = createRequire(import.meta.url);
 	const [resolveError, entryPath] = attempt(() => require.resolve(packageName));
-	if (resolveError || entryPath === null) return DEFAULT_VERSION;
+	if (resolveError || entryPath === null) {
+		console.warn(`Warning: Could not resolve version for ${packageName}, using fallback 0.0.0`);
+		return DEFAULT_VERSION;
+	}
 	const [manifestError, manifest] = await readManifest(join(dirname(entryPath), ".."));
-	if (manifestError || !manifest.version) return DEFAULT_VERSION;
+	if (manifestError || !manifest.version) {
+		console.warn(`Warning: Could not resolve version for ${packageName}, using fallback 0.0.0`);
+		return DEFAULT_VERSION;
+	}
 	return manifest.version;
 }
 //#endregion

package/dist/index.mjs

@@ -7,30 +7,35 @@ import { readManifest } from "@kidd-cli/utils/manifest";
 *
 * Reads package.json one directory above `baseDir` (the dist output sits
 * one level below the package root) and ensures all required fields are
-* present. Throws immediately if the manifest cannot be read or any
-* required field is missing — this is an unrecoverable entry-point guard.
+* present. Returns an error Result if the manifest cannot be read or any
+* required field is missing.
 *
 * @param baseDir - The directory the CLI entry file lives in (typically `import.meta.dirname`).
-* @returns A validated {@link CLIManifest} with all required fields.
+* @returns A Result tuple: error on failure, validated {@link CLIManifest} on success.
 */
 async function loadCLIManifest(baseDir) {
 	const [manifestError, manifest] = await readManifest(join(baseDir, ".."));
-	if (manifestError) throw new Error(`Failed to read CLI manifest: ${manifestError.message}`);
-	if (!manifest.name) throw new Error("CLI manifest is missing required field: name");
-	if (!manifest.version) throw new Error("CLI manifest is missing required field: version");
-	if (!manifest.description) throw new Error("CLI manifest is missing required field: description");
-	return {
+	if (manifestError) return [/* @__PURE__ */ new Error(`Failed to read CLI manifest: ${manifestError.message}`), null];
+	if (!manifest.name) return [/* @__PURE__ */ new Error("CLI manifest is missing required field: name"), null];
+	if (!manifest.version) return [/* @__PURE__ */ new Error("CLI manifest is missing required field: version"), null];
+	if (!manifest.description) return [/* @__PURE__ */ new Error("CLI manifest is missing required field: description"), null];
+	return [null, {
 		description: manifest.description,
 		name: manifest.name,
 		version: manifest.version
-	};
+	}];
 }
 //#endregion
 //#region src/index.ts
-const manifest = await loadCLIManifest(import.meta.dirname);
+const [manifestError, manifest] = await loadCLIManifest(import.meta.dirname);
+if (manifestError) {
+	console.error(manifestError.message);
+	process.exit(1);
+}
 await cli({
 	commands: `${import.meta.dirname}/commands`,
 	description: manifest.description,
+	help: { header: `${manifest.name} v${manifest.version}` },
 	name: manifest.name,
 	version: manifest.version
 });

package/dist/lib/templates/config/config.ts.liquid

@@ -0,0 +1,16 @@
+import type { ConfigType } from '@kidd-cli/core'
+import { z } from 'zod'
+
+/**
+ * Runtime config schema for the {{ name }} CLI.
+ *
+ * This schema validates config files loaded at startup (e.g. `.{{ name }}.jsonc`).
+ * The inferred type is merged into `ctx.config` via module augmentation below.
+ */
+export const configSchema = z.object({
+  // Add your config fields here
+})
+
+declare module '@kidd-cli/core' {
+  interface CliConfig extends ConfigType<typeof configSchema> {}
+}

package/dist/lib/templates/project/src/commands/hello.ts.liquid

@@ -7,6 +7,6 @@ export default command({
     name: z.string().describe('Name to greet').default('world'),
   }),
   handler: async (ctx) => {
-    ctx.output.raw(`Hello, ${ctx.args.name}!`)
+    ctx.logger.print(`Hello, ${ctx.args.name}!`)
   },
 })

package/dist/lib/templates/project/src/config.ts.liquid

@@ -0,0 +1,16 @@
+import type { ConfigType } from '@kidd-cli/core'
+import { z } from 'zod'
+
+/**
+ * Runtime config schema for the {{ name }} CLI.
+ *
+ * This schema validates config files loaded at startup (e.g. `.{{ name }}.jsonc`).
+ * The inferred type is merged into `ctx.config` via module augmentation below.
+ */
+export const configSchema = z.object({
+  // Add your config fields here
+})
+
+declare module '@kidd-cli/core' {
+  interface CliConfig extends ConfigType<typeof configSchema> {}
+}

package/dist/lib/templates/project/src/index.ts.liquid

@@ -1,8 +1,13 @@
 import { cli } from '@kidd-cli/core'
-
+{% if includeConfig %}
+import { configSchema } from './config.js'
+{% endif %}
 void cli({
   name: '{{ name }}',
   version: '0.0.0',
   description: '{{ description }}',
   commands: import.meta.dirname + '/commands',
-})
+{% if includeConfig %}  config: {
+    schema: configSchema,
+  },
+{% endif %}})

package/dist/validate-D3mbQfJT.mjs

@@ -0,0 +1,16 @@
+//#region src/lib/validate.ts
+const KEBAB_CASE_CHARS_RE = /^[a-z][\da-z-]*$/;
+/**
+* Check whether a string is valid kebab-case.
+*
+* @param value - The string to validate.
+* @returns True when the string is kebab-case.
+*/
+function isKebabCase(value) {
+	if (!KEBAB_CASE_CHARS_RE.test(value)) return false;
+	if (value.endsWith("-")) return false;
+	if (value.includes("--")) return false;
+	return true;
+}
+//#endregion
+export { isKebabCase as t };

package/dist/{write-CdoqLFeH.mjs → write-BF8u0sRy.mjs}

@@ -92,21 +92,6 @@ function isGenerateError(value) {
 	return "type" in value && "message" in value;
 }
 //#endregion
-//#region src/lib/validate.ts
-const KEBAB_CASE_CHARS_RE = /^[a-z][\da-z-]*$/;
-/**
-* Check whether a string is valid kebab-case.
-*
-* @param value - The string to validate.
-* @returns True when the string is kebab-case.
-*/
-function isKebabCase(value) {
-	if (!KEBAB_CASE_CHARS_RE.test(value)) return false;
-	if (value.endsWith("-")) return false;
-	if (value.includes("--")) return false;
-	return true;
-}
-//#endregion
 //#region src/lib/write.ts
 /**
 * Write rendered files to disk with optional conflict detection.
@@ -160,4 +145,4 @@ async function writeSingleFile(file, outputDir, overwrite) {
 	}
 }
 //#endregion
-export { isKebabCase as n, renderTemplate as r, writeFiles as t };
+export { renderTemplate as n, writeFiles as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kidd-cli/cli",
-  "version": "0.1.4",
+  "version": "0.3.0",
   "description": "DX companion CLI for the kidd framework",
   "keywords": [
     "cli",
@@ -26,10 +26,10 @@
     "liquidjs": "^10.25.0",
     "picocolors": "^1.1.1",
     "zod": "^4.3.6",
-    "@kidd-cli/bundler": "0.1.3",
-    "@kidd-cli/config": "0.1.3",
-    "@kidd-cli/core": "0.3.0",
-    "@kidd-cli/utils": "0.1.3"
+    "@kidd-cli/bundler": "0.2.0",
+    "@kidd-cli/config": "0.1.4",
+    "@kidd-cli/utils": "0.1.4",
+    "@kidd-cli/core": "0.5.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",