@kidd-cli/cli 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,17 @@
+# kidd-cli
+
+DX companion CLI for the kidd framework.
+
+## Installation
+
+```bash
+pnpm add -g kidd-cli
+```
+
+## Usage
+
+```bash
+kidd --help
+```
+
+> This package is a placeholder. The CLI implementation is not yet available.

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

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

package/dist/commands/add/command.mjs

@@ -0,0 +1,137 @@
+import { n as renderTemplate, t as writeFiles } from "../../write-DDGnajpV.mjs";
+import { t as detectProject } from "../../detect-DDE1hlQ8.mjs";
+import { command } from "@kidd-cli/core";
+import { join } from "node:path";
+import { loadConfig } from "@kidd-cli/config/loader";
+import { z } from "zod";
+
+//#region src/commands/add/command.ts
+const KEBAB_CASE_CHARS_RE = /^[a-z][\da-z-]*$/;
+const addCommandCommand = command({
+	args: z.object({
+		args: z.boolean().describe("Include args schema").optional(),
+		description: z.string().describe("Command description").optional(),
+		name: z.string().describe("Command name (kebab-case)").optional()
+	}),
+	description: "Add a new command 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 [configError, configResult] = await loadConfig({ cwd: project.rootDir });
+		if (configError) {}
+		const commandName = await resolveCommandName(ctx);
+		const commandDescription = await resolveDescription(ctx);
+		const includeArgs = await resolveIncludeArgs(ctx);
+		ctx.spinner.start("Generating command...");
+		const [renderError, rendered] = await renderTemplate({
+			templateDir: join(import.meta.dirname, "..", "..", "lib", "templates", "command"),
+			variables: {
+				commandName,
+				description: commandDescription,
+				includeArgs
+			}
+		});
+		if (renderError) {
+			ctx.spinner.stop("Failed");
+			return ctx.fail(renderError.message);
+		}
+		const outputDir = resolveCommandsDir(configResult, project.rootDir);
+		const [writeError, result] = await writeFiles({
+			files: rendered.map((file) => ({
+				content: file.content,
+				relativePath: file.relativePath.replace("command.ts", `${commandName}.ts`)
+			})),
+			outputDir,
+			overwrite: false
+		});
+		if (writeError) {
+			ctx.spinner.stop("Failed");
+			return ctx.fail(writeError.message);
+		}
+		ctx.spinner.stop("Command created!");
+		result.written.map((file) => ctx.output.raw(`  created ${file}`));
+		result.skipped.map((file) => ctx.output.raw(`  skipped ${file} (already exists)`));
+	}
+});
+/**
+* Check whether a string is valid kebab-case.
+*
+* @param value - The string to validate.
+* @returns True when the string is kebab-case.
+* @private
+*/
+function isKebabCase(value) {
+	if (!KEBAB_CASE_CHARS_RE.test(value)) return false;
+	if (value.endsWith("-")) return false;
+	if (value.includes("--")) return false;
+	return true;
+}
+/**
+* Resolve the command name from args or prompt.
+*
+* @param ctx - Command context.
+* @returns The validated command name.
+* @private
+*/
+async function resolveCommandName(ctx) {
+	if (ctx.args.name) {
+		if (!isKebabCase(ctx.args.name)) return ctx.fail("Command name must be kebab-case (e.g. deploy)");
+		return ctx.args.name;
+	}
+	return ctx.prompts.text({
+		message: "Command name",
+		placeholder: "deploy",
+		validate: (value) => {
+			if (value === void 0 || !isKebabCase(value)) return "Must be kebab-case (e.g. deploy)";
+		}
+	});
+}
+/**
+* Resolve the command description from args or prompt.
+*
+* @param ctx - Command context.
+* @returns The command description string.
+* @private
+*/
+async function resolveDescription(ctx) {
+	if (ctx.args.description) return ctx.args.description;
+	return ctx.prompts.text({
+		defaultValue: "",
+		message: "Description",
+		placeholder: "What does this command do?"
+	});
+}
+/**
+* Resolve whether to include args from args or prompt.
+*
+* @param ctx - Command context.
+* @returns True when the command should include a zod args schema.
+* @private
+*/
+async function resolveIncludeArgs(ctx) {
+	if (ctx.args.args !== void 0 && ctx.args.args !== null) return ctx.args.args;
+	return ctx.prompts.confirm({
+		initialValue: true,
+		message: "Include args schema?"
+	});
+}
+/**
+* Resolve the commands output directory from the kidd config.
+*
+* Uses the `commands` field from `kidd.config.ts` when available,
+* falling back to the kidd default of `'commands'`.
+*
+* @param configResult - The loaded config result, or null when loading failed.
+* @param rootDir - The project root directory.
+* @returns The absolute path to the commands directory.
+* @private
+*/
+function resolveCommandsDir(configResult, rootDir) {
+	const DEFAULT_COMMANDS = "commands";
+	if (configResult) return join(rootDir, configResult.config.commands ?? DEFAULT_COMMANDS);
+	return join(rootDir, DEFAULT_COMMANDS);
+}
+
+//#endregion
+export { addCommandCommand as default };

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

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

package/dist/commands/add/index.mjs

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

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

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

package/dist/commands/add/middleware.mjs

@@ -0,0 +1,101 @@
+import { n as renderTemplate, t as writeFiles } from "../../write-DDGnajpV.mjs";
+import { t as detectProject } from "../../detect-DDE1hlQ8.mjs";
+import { command } from "@kidd-cli/core";
+import { join } from "node:path";
+import { z } from "zod";
+
+//#region src/commands/add/middleware.ts
+const KEBAB_CASE_CHARS_RE = /^[a-z][\da-z-]*$/;
+const addMiddlewareCommand = command({
+	args: z.object({
+		description: z.string().describe("Middleware description").optional(),
+		name: z.string().describe("Middleware name (kebab-case)").optional()
+	}),
+	description: "Add a new middleware 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 middlewareName = await resolveMiddlewareName(ctx);
+		const middlewareDescription = await resolveDescription(ctx);
+		ctx.spinner.start("Generating middleware...");
+		const [renderError, rendered] = await renderTemplate({
+			templateDir: join(import.meta.dirname, "..", "..", "lib", "templates", "middleware"),
+			variables: {
+				description: middlewareDescription,
+				middlewareName
+			}
+		});
+		if (renderError) {
+			ctx.spinner.stop("Failed");
+			return ctx.fail(renderError.message);
+		}
+		const outputDir = join(project.rootDir, "src", "middleware");
+		const [writeError, result] = await writeFiles({
+			files: rendered.map((file) => ({
+				content: file.content,
+				relativePath: file.relativePath.replace("middleware.ts", `${middlewareName}.ts`)
+			})),
+			outputDir,
+			overwrite: false
+		});
+		if (writeError) {
+			ctx.spinner.stop("Failed");
+			return ctx.fail(writeError.message);
+		}
+		ctx.spinner.stop("Middleware created!");
+		result.written.map((file) => ctx.output.raw(`  created ${file}`));
+		result.skipped.map((file) => ctx.output.raw(`  skipped ${file} (already exists)`));
+	}
+});
+/**
+* Check whether a string is valid kebab-case.
+*
+* @param value - The string to validate.
+* @returns True when the string is kebab-case.
+* @private
+*/
+function isKebabCase(value) {
+	if (!KEBAB_CASE_CHARS_RE.test(value)) return false;
+	if (value.endsWith("-")) return false;
+	if (value.includes("--")) return false;
+	return true;
+}
+/**
+* Resolve the middleware name from args or prompt.
+*
+* @param ctx - Command context.
+* @returns The validated middleware name.
+* @private
+*/
+async function resolveMiddlewareName(ctx) {
+	if (ctx.args.name) {
+		if (!isKebabCase(ctx.args.name)) return ctx.fail("Middleware name must be kebab-case (e.g. auth)");
+		return ctx.args.name;
+	}
+	return ctx.prompts.text({
+		message: "Middleware name",
+		placeholder: "auth",
+		validate: (value) => {
+			if (value === void 0 || !isKebabCase(value)) return "Must be kebab-case (e.g. auth)";
+		}
+	});
+}
+/**
+* Resolve the middleware description from args or prompt.
+*
+* @param ctx - Command context.
+* @returns The middleware description string.
+* @private
+*/
+async function resolveDescription(ctx) {
+	if (ctx.args.description) return ctx.args.description;
+	return ctx.prompts.text({
+		defaultValue: "",
+		message: "Description",
+		placeholder: "What does this middleware do?"
+	});
+}
+
+//#endregion
+export { addMiddlewareCommand as default };

package/dist/commands/build.d.mts

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

package/dist/commands/build.mjs

@@ -0,0 +1,163 @@
+import { command } from "@kidd-cli/core";
+import { relative } from "node:path";
+import { build, compile, resolveTargetLabel } from "@kidd-cli/bundler";
+import { loadConfig } from "@kidd-cli/config/loader";
+import { z } from "zod";
+
+//#region src/commands/build.ts
+/**
+* Build a kidd CLI project for production using tsdown.
+*
+* Loads the project's `kidd.config.ts`, invokes the bundler, and reports
+* the output entry file and directory on success. When `--compile` or
+* `--targets` is provided (or `compile` is set in config), also compiles
+* to standalone binaries via Bun.
+*/
+const buildCommand = command({
+	args: z.object({
+		compile: z.boolean().optional().describe("Compile to standalone binaries after bundling"),
+		targets: z.array(z.string()).optional().describe("Compile targets (implies --compile)")
+	}),
+	description: "Build a kidd CLI project for production",
+	handler: async (ctx) => {
+		const cwd = process.cwd();
+		const [configError, configResult] = await loadConfig({ cwd });
+		const config = extractConfig(configResult);
+		if (configError) {}
+		ctx.spinner.start("Bundling with tsdown...");
+		const [buildError, buildOutput] = await build({
+			config,
+			cwd
+		});
+		if (buildError) {
+			ctx.spinner.stop("Bundle failed");
+			ctx.fail(buildError.message);
+		}
+		if (!resolveCompileIntent({
+			compileFlag: ctx.args.compile,
+			configCompile: config.compile,
+			targets: ctx.args.targets
+		})) {
+			ctx.spinner.stop("Build complete");
+			ctx.logger.note(formatBuildNote({
+				cwd,
+				entryFile: buildOutput.entryFile,
+				outDir: buildOutput.outDir
+			}), "Bundle");
+			return;
+		}
+		ctx.spinner.message("Bundled, compiling binaries...");
+		const [compileError, compileOutput] = await compile({
+			config: mergeCompileTargets({
+				config,
+				targets: ctx.args.targets
+			}),
+			cwd,
+			onTargetComplete: (target) => ctx.spinner.message(`Compiled ${resolveTargetLabel(target)}`),
+			onTargetStart: (target) => ctx.spinner.message(`Compiling ${resolveTargetLabel(target)}...`)
+		});
+		if (compileError) {
+			ctx.spinner.stop("Compile failed");
+			ctx.fail(compileError.message);
+		}
+		ctx.spinner.stop("Build complete");
+		ctx.logger.note(formatBuildNote({
+			cwd,
+			entryFile: buildOutput.entryFile,
+			outDir: buildOutput.outDir
+		}), "Bundle");
+		ctx.logger.note(formatBinariesNote({
+			binaries: compileOutput.binaries,
+			cwd
+		}), "Binaries");
+	}
+});
+/**
+* Extract a KiddConfig from a load result, falling back to empty defaults.
+*
+* @private
+* @param result - The result from loadConfig, or null when loading failed.
+* @returns The loaded config or an empty object (all KiddConfig fields are optional).
+*/
+function extractConfig(result) {
+	if (result) return result.config;
+	return {};
+}
+/**
+* Determine whether compilation should run based on CLI flags and config.
+*
+* Resolution order:
+* 1. `--targets` provided → compile (implied)
+* 2. `--compile` flag → use its boolean value
+* 3. Fall back to config `compile` field (truthy = compile)
+*
+* @private
+* @param params - The CLI flags and config compile field.
+* @returns Whether to run the compile step.
+*/
+function resolveCompileIntent(params) {
+	if (params.targets && params.targets.length > 0) return true;
+	if (params.compileFlag !== void 0) return params.compileFlag;
+	if (params.configCompile === true) return true;
+	if (typeof params.configCompile === "object") return true;
+	return false;
+}
+/**
+* Merge CLI `--targets` into the config's compile options.
+*
+* When targets are provided via CLI, they override whatever is in config.
+* Otherwise the config is returned unchanged.
+*
+* @private
+* @param params - The config and optional CLI targets.
+* @returns A config with compile targets merged in.
+*/
+function mergeCompileTargets(params) {
+	if (!params.targets || params.targets.length === 0) return params.config;
+	const existingCompile = resolveExistingCompile(params.config.compile);
+	return {
+		...params.config,
+		compile: {
+			...existingCompile,
+			targets: params.targets
+		}
+	};
+}
+/**
+* Extract compile options object from the config's compile field.
+*
+* Returns the object as-is when it is an object, or an empty object
+* for boolean / undefined values.
+*
+* @private
+* @param value - The raw compile config value.
+* @returns A compile options object.
+*/
+function resolveExistingCompile(value) {
+	if (typeof value === "object") return value;
+	return {};
+}
+/**
+* Format bundle output into a multi-line string for display.
+*
+* @private
+* @param params - The build output paths and working directory.
+* @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");
+}
+/**
+* Format compiled binaries into an aligned, multi-line string for display.
+*
+* @private
+* @param params - The binaries and working directory for relative path resolution.
+* @returns A formatted string with one line per binary.
+*/
+function formatBinariesNote(params) {
+	const maxLen = Math.max(...params.binaries.map((b) => b.label.length));
+	return params.binaries.map((binary) => `${binary.label.padEnd(maxLen)}  ${relative(params.cwd, binary.path)}`).join("\n");
+}
+
+//#endregion
+export { buildCommand as default };

package/dist/commands/commands.d.mts

@@ -0,0 +1,13 @@
+import { Command } from "@kidd-cli/core";
+
+//#region src/commands/commands.d.ts
+/**
+* Display the command tree for a kidd CLI project.
+*
+* Loads the project's `kidd.config.ts` to locate the commands directory,
+* scans it with the autoloader, and prints an ASCII tree of all discovered
+* commands and subcommands.
+*/
+declare const commandsCommand: Command;
+//#endregion
+export { commandsCommand as default };

package/dist/commands/commands.mjs

@@ -0,0 +1,135 @@
+import { autoload, command } from "@kidd-cli/core";
+import { join } from "node:path";
+import { loadConfig } from "@kidd-cli/config/loader";
+import { existsSync } from "node:fs";
+
+//#region src/commands/commands.ts
+/**
+* Display the command tree for a kidd CLI project.
+*
+* Loads the project's `kidd.config.ts` to locate the commands directory,
+* scans it with the autoloader, and prints an ASCII tree of all discovered
+* commands and subcommands.
+*/
+const commandsCommand = command({
+	description: "Display the command tree for a kidd CLI project",
+	handler: async (ctx) => {
+		const cwd = process.cwd();
+		const [configError, configResult] = await loadConfig({ cwd });
+		const config = extractConfig(configResult);
+		if (configError) {}
+		const commandsDir = join(cwd, config.commands ?? "commands");
+		if (!existsSync(commandsDir)) ctx.fail(`Commands directory not found: ${commandsDir}`);
+		ctx.spinner.start("Scanning commands...");
+		const tree = await buildTree(await autoload({ dir: commandsDir }));
+		ctx.spinner.stop("Commands");
+		if (tree.length === 0) {
+			ctx.output.write("No commands found");
+			return;
+		}
+		ctx.output.raw(`${renderTree(tree)}\n`);
+	}
+});
+/**
+* Extract a KiddConfig from a load result, falling back to empty defaults.
+*
+* @private
+* @param result - The result from loadConfig, or null when loading failed.
+* @returns The loaded config or an empty object (all KiddConfig fields are optional).
+*/
+function extractConfig(result) {
+	if (result) return result.config;
+	return {};
+}
+/**
+* Resolve a command's subcommands field, which may be a Promise, a map, or undefined.
+*
+* @private
+* @param commands - The raw subcommands value from a Command object.
+* @returns The resolved CommandMap, or an empty object when none exist.
+*/
+async function resolveSubcommands(commands) {
+	if (!commands) return {};
+	if (commands instanceof Promise) return commands;
+	return commands;
+}
+/**
+* Recursively build a sorted tree of entries from a CommandMap.
+*
+* @private
+* @param commandMap - The map of command names to Command objects.
+* @returns A sorted array of TreeEntry nodes.
+*/
+async function buildTree(commandMap) {
+	const entries = Object.entries(commandMap).toSorted(([a], [b]) => a.localeCompare(b));
+	return Promise.all(entries.map(async ([name, cmd]) => {
+		return {
+			children: await buildTree(await resolveSubcommands(cmd.commands)),
+			description: cmd.description ?? "",
+			name
+		};
+	}));
+}
+/**
+* Render a tree of entries into an ASCII tree string.
+*
+* @private
+* @param entries - The top-level tree entries to render.
+* @returns The formatted tree string.
+*/
+function renderTree(entries) {
+	return renderEntries(entries, "").join("\n");
+}
+/**
+* Recursively render tree entries with proper box-drawing connectors.
+*
+* @private
+* @param entries - The entries at this level.
+* @param prefix - The prefix string for indentation.
+* @returns An array of formatted lines.
+*/
+function renderEntries(entries, prefix) {
+	return entries.flatMap((entry, index) => {
+		const isLast = index === entries.length - 1;
+		const connector = resolveConnector(isLast);
+		const childPrefix = resolveChildPrefix(isLast);
+		return [`${prefix}${connector}${formatLabel(entry.name, entry.description)}`, ...renderEntries(entry.children, `${prefix}${childPrefix}`)];
+	});
+}
+/**
+* Get the box-drawing connector for a tree entry.
+*
+* @private
+* @param isLast - Whether this is the last entry at its level.
+* @returns The connector string.
+*/
+function resolveConnector(isLast) {
+	if (isLast) return "└── ";
+	return "├── ";
+}
+/**
+* Get the indentation prefix for children of a tree entry.
+*
+* @private
+* @param isLast - Whether the parent is the last entry at its level.
+* @returns The child prefix string.
+*/
+function resolveChildPrefix(isLast) {
+	if (isLast) return "    ";
+	return "│   ";
+}
+/**
+* Format a command name and description into a tree label.
+*
+* @private
+* @param name - The command name.
+* @param description - The command description (may be empty).
+* @returns The formatted label string.
+*/
+function formatLabel(name, description) {
+	if (description) return `${name} — ${description}`;
+	return name;
+}
+
+//#endregion
+export { commandsCommand as default };

package/dist/commands/dev.d.mts

@@ -0,0 +1,12 @@
+import { Command } from "@kidd-cli/core";
+
+//#region src/commands/dev.d.ts
+/**
+* Start a kidd CLI project in development mode with file watching.
+*
+* Loads the project's `kidd.config.ts`, starts tsdown in watch mode, and
+* logs rebuild status on each successful build.
+*/
+declare const devCommand: Command;
+//#endregion
+export { devCommand as default };