@kidd-cli/cli 0.1.0

package/dist/commands/init.mjs

@@ -0,0 +1,167 @@
+import { n as renderTemplate, t as writeFiles } from "../write-DDGnajpV.mjs";
+import { command } from "@kidd-cli/core";
+import { join } from "node:path";
+import { z } from "zod";
+
+//#region src/commands/init.ts
+const KEBAB_CASE_CHARS_RE = /^[a-z][\da-z-]*$/;
+const initCommand = command({
+	args: z.object({
+		description: z.string().describe("Project description").optional(),
+		example: z.boolean().describe("Include example command").optional(),
+		name: z.string().describe("Project name (kebab-case)").optional(),
+		pm: z.enum([
+			"pnpm",
+			"yarn",
+			"npm"
+		]).describe("Package manager").optional()
+	}),
+	description: "Scaffold a new kidd CLI project",
+	handler: async (ctx) => {
+		const projectName = await resolveProjectName(ctx);
+		const projectDescription = await resolveDescription(ctx);
+		const packageManager = await resolvePackageManager(ctx);
+		const includeExample = await resolveIncludeExample(ctx);
+		ctx.spinner.start("Scaffolding project...");
+		const [renderError, rendered] = await renderTemplate({
+			templateDir: join(import.meta.dirname, "..", "lib", "templates", "project"),
+			variables: {
+				description: projectDescription,
+				name: projectName,
+				packageManager
+			}
+		});
+		if (renderError) {
+			ctx.spinner.stop("Failed");
+			return ctx.fail(renderError.message);
+		}
+		const [writeError] = await writeFiles({
+			files: selectFiles(includeExample, rendered),
+			outputDir: join(process.cwd(), projectName),
+			overwrite: false
+		});
+		if (writeError) {
+			ctx.spinner.stop("Failed");
+			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`);
+	}
+});
+/**
+* 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 project name from args or prompt.
+*
+* @param ctx - Command context.
+* @returns The validated project name.
+* @private
+*/
+async function resolveProjectName(ctx) {
+	if (ctx.args.name) {
+		if (!isKebabCase(ctx.args.name)) return ctx.fail("Project name must be kebab-case (e.g. my-cli)");
+		return ctx.args.name;
+	}
+	return ctx.prompts.text({
+		message: "Project name",
+		placeholder: "my-cli",
+		validate: (value) => {
+			if (value === void 0 || !isKebabCase(value)) return "Must be kebab-case (e.g. my-cli)";
+		}
+	});
+}
+/**
+* Resolve the project description from args or prompt.
+*
+* @param ctx - Command context.
+* @returns The project description string.
+* @private
+*/
+async function resolveDescription(ctx) {
+	if (ctx.args.description) return ctx.args.description;
+	return ctx.prompts.text({
+		defaultValue: "A CLI built with kidd",
+		message: "Description",
+		placeholder: "A CLI built with kidd"
+	});
+}
+/**
+* Resolve the package manager from args or prompt.
+*
+* @param ctx - Command context.
+* @returns The selected package manager.
+* @private
+*/
+async function resolvePackageManager(ctx) {
+	if (ctx.args.pm) return ctx.args.pm;
+	return ctx.prompts.select({
+		message: "Package manager",
+		options: [
+			{
+				label: "pnpm",
+				value: "pnpm"
+			},
+			{
+				label: "yarn",
+				value: "yarn"
+			},
+			{
+				label: "npm",
+				value: "npm"
+			}
+		]
+	});
+}
+/**
+* Resolve whether to include the example command from args or prompt.
+*
+* @param ctx - Command context.
+* @returns True when the example hello command should be included.
+* @private
+*/
+async function resolveIncludeExample(ctx) {
+	if (ctx.args.example !== void 0 && ctx.args.example !== null) return ctx.args.example;
+	return ctx.prompts.confirm({
+		initialValue: true,
+		message: "Include example command?"
+	});
+}
+/**
+* Select the rendered files to write, optionally excluding the example command.
+*
+* @param includeExample - Whether to include the example hello command.
+* @param rendered - The full set of rendered files.
+* @returns The filtered file list.
+* @private
+*/
+function selectFiles(includeExample, rendered) {
+	if (includeExample) return rendered;
+	return rendered.filter(excludeHelloCommand);
+}
+/**
+* Filter predicate that excludes the hello.ts example command.
+*
+* @param file - A rendered file to check.
+* @returns True when the file is not the hello command.
+* @private
+*/
+function excludeHelloCommand(file) {
+	return !file.relativePath.includes("commands/hello.ts");
+}
+
+//#endregion
+export { initCommand as default };

package/dist/detect-DDE1hlQ8.mjs

@@ -0,0 +1,73 @@
+import { join } from "node:path";
+import { access, readFile } from "node:fs/promises";
+import { attemptAsync, ok, toErrorMessage } from "@kidd-cli/utils/fp";
+
+//#region src/lib/detect.ts
+/**
+* Detect whether the given directory contains a kidd-based CLI project.
+*
+* Looks for a `package.json` with `kidd` listed in `dependencies` or
+* `devDependencies`, and checks for a `src/commands/` directory.
+*
+* @param cwd - The directory to inspect.
+* @returns An async Result containing project info or null when no kidd project is found.
+*/
+async function detectProject(cwd) {
+	const packageJsonPath = join(cwd, "package.json");
+	if (!await fileExists(packageJsonPath)) return ok(null);
+	const [readError, pkg] = await readPackageJson(packageJsonPath);
+	if (readError) return [readError, null];
+	const deps = pkg.dependencies ?? {};
+	const devDeps = pkg.devDependencies ?? {};
+	const hasKiddDep = "@kidd-cli/core" in deps || "@kidd-cli/core" in devDeps;
+	if (!hasKiddDep) return ok(null);
+	const commandsPath = join(cwd, "src", "commands");
+	if (await fileExists(commandsPath)) return ok({
+		commandsDir: commandsPath,
+		hasKiddDep,
+		rootDir: cwd
+	});
+	return ok({
+		commandsDir: null,
+		hasKiddDep,
+		rootDir: cwd
+	});
+}
+/**
+* Read and parse a package.json file.
+*
+* @param filePath - Absolute path to the package.json.
+* @returns A Result tuple with the parsed package data or a GenerateError.
+* @private
+*/
+async function readPackageJson(filePath) {
+	const [readError, content] = await attemptAsync(() => readFile(filePath, "utf8"));
+	if (readError || content === null || content === void 0) return [{
+		message: `Failed to read package.json: ${toErrorMessage(readError)}`,
+		path: filePath,
+		type: "read_error"
+	}, null];
+	try {
+		return ok(JSON.parse(content));
+	} catch (error) {
+		return [{
+			message: `Failed to parse package.json: ${toErrorMessage(error)}`,
+			path: filePath,
+			type: "read_error"
+		}, null];
+	}
+}
+/**
+* Check whether a path exists on disk.
+*
+* @param filePath - The path to check.
+* @returns True when the path is accessible, false otherwise.
+* @private
+*/
+async function fileExists(filePath) {
+	const [err] = await attemptAsync(() => access(filePath));
+	return err === null;
+}
+
+//#endregion
+export { detectProject as t };

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/index.mjs

@@ -0,0 +1,41 @@
+import { cli } from "@kidd-cli/core";
+import { join } from "node:path";
+import { readManifest } from "@kidd-cli/utils/manifest";
+
+//#region src/manifest.ts
+/**
+* Read and validate the CLI package 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.
+*
+* @param baseDir - The directory the CLI entry file lives in (typically `import.meta.dirname`).
+* @returns A validated {@link CLIManifest} with all required fields.
+*/
+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 {
+		description: manifest.description,
+		name: manifest.name,
+		version: manifest.version
+	};
+}
+
+//#endregion
+//#region src/index.ts
+const manifest = await loadCLIManifest(import.meta.dirname);
+await cli({
+	commands: `${import.meta.dirname}/commands`,
+	description: manifest.description,
+	name: manifest.name,
+	version: manifest.version
+});
+
+//#endregion
+export {  };

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

@@ -0,0 +1,12 @@
+import { command } from '@kidd-cli/core'
+{% if includeArgs %}import { z } from 'zod'
+{% endif %}
+export default command({
+  description: '{{ description }}',
+{% if includeArgs %}  args: z.object({
+    // Add your args here
+  }),
+{% endif %}  handler: async (ctx) => {
+    // Implement your command here
+  },
+})

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

@@ -0,0 +1,9 @@
+import { middleware } from '@kidd-cli/core'
+
+/**
+ * {{ description }}
+ */
+export default middleware(async (ctx, next) => {
+  // Implement your middleware here
+  await next()
+})

package/dist/lib/templates/project/gitignore.liquid

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

package/dist/lib/templates/project/package.json.liquid

@@ -0,0 +1,29 @@
+{
+  "name": "{{ name }}",
+  "version": "0.0.0",
+  "description": "{{ description }}",
+  "keywords": [],
+  "license": "MIT",
+  "bin": {
+    "{{ name }}": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@kidd-cli/core": "^0.0.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "tsdown": "^0.21.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.0.0"
+  }
+}

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

@@ -0,0 +1,12 @@
+import { command } from '@kidd-cli/core'
+import { z } from 'zod'
+
+export default command({
+  description: 'Say hello',
+  args: z.object({
+    name: z.string().describe('Name to greet').default('world'),
+  }),
+  handler: async (ctx) => {
+    ctx.output.raw(`Hello, ${ctx.args.name}!`)
+  },
+})

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

@@ -0,0 +1,8 @@
+import { cli } from '@kidd-cli/core'
+
+void cli({
+  name: '{{ name }}',
+  version: '0.0.0',
+  description: '{{ description }}',
+  commands: import.meta.dirname + '/commands',
+})

package/dist/lib/templates/project/tsconfig.json.liquid

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "isolatedModules": true,
+    "isolatedDeclarations": true,
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true,
+    "outDir": "dist"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

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

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  clean: true,
+  dts: true,
+  entry: ['src/index.ts'],
+  format: 'esm',
+  outDir: 'dist',
+})

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

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.ts'],
+    passWithNoTests: true,
+  },
+})

package/dist/write-DDGnajpV.mjs

@@ -0,0 +1,166 @@
+import { dirname, join, relative } from "node:path";
+import { access, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { attemptAsync, ok, toErrorMessage } from "@kidd-cli/utils/fp";
+import { Liquid } from "liquidjs";
+
+//#region src/lib/render.ts
+/**
+* Render all `.liquid` templates in a directory using LiquidJS.
+*
+* Recursively collects `.liquid` files under `templateDir`, renders each
+* with the provided variables, and strips the `.liquid` extension from
+* the output path. Files named `gitignore.liquid` are mapped to `.gitignore`.
+*
+* @param params - Template directory and variable bindings.
+* @returns An async Result containing rendered files or a GenerateError.
+*/
+async function renderTemplate(params) {
+	const engine = new Liquid({ root: params.templateDir });
+	const entries = await collectLiquidFiles(params.templateDir);
+	if (entries.length === 0) return ok([]);
+	const results = await Promise.all(entries.map(async (entry) => {
+		const [renderError, content] = await renderSingleFile(engine, join(params.templateDir, entry), params.variables);
+		if (renderError) return renderError;
+		return {
+			content,
+			relativePath: mapOutputPath(entry)
+		};
+	}));
+	const firstError = results.find(isGenerateError);
+	if (firstError) return [firstError, null];
+	return ok(results);
+}
+/**
+* Recursively collect all `.liquid` file paths relative to root.
+*
+* @param root - The directory to scan.
+* @returns Relative paths of all `.liquid` files.
+* @private
+*/
+async function collectLiquidFiles(root) {
+	return (await readdir(root, {
+		recursive: true,
+		withFileTypes: true
+	})).filter((entry) => entry.isFile() && entry.name.endsWith(".liquid")).map((entry) => {
+		const parent = entry.parentPath;
+		return relative(root, join(parent, entry.name));
+	});
+}
+/**
+* Render a single `.liquid` file with the given variables.
+*
+* @param engine - The LiquidJS engine instance.
+* @param absolutePath - Absolute path to the `.liquid` file.
+* @param variables - Template variable bindings.
+* @returns A Result tuple with the rendered content or a GenerateError.
+* @private
+*/
+async function renderSingleFile(engine, absolutePath, variables) {
+	try {
+		const template = await readFile(absolutePath, "utf8");
+		return ok(await engine.parseAndRender(template, variables));
+	} catch (error) {
+		return [{
+			message: `Failed to render template: ${toErrorMessage(error)}`,
+			path: absolutePath,
+			type: "render_error"
+		}, null];
+	}
+}
+/**
+* Map a `.liquid` relative path to its output path.
+*
+* Strips the `.liquid` extension and renames bare `gitignore` segments
+* to `.gitignore` so dotfiles survive version control.
+*
+* @param liquidPath - Relative path ending in `.liquid`.
+* @returns The output-relative path without the `.liquid` suffix.
+* @private
+*/
+function mapOutputPath(liquidPath) {
+	return liquidPath.replace(/\.liquid$/, "").replaceAll(/(^|\/)gitignore($|\/)/g, "$1.gitignore$2");
+}
+/**
+* Type guard for GenerateError objects.
+*
+* @param value - The value to check.
+* @returns True when value has a `type` and `message` property matching GenerateError.
+* @private
+*/
+function isGenerateError(value) {
+	if (typeof value !== "object" || value === null) return false;
+	return "type" in value && "message" in value;
+}
+
+//#endregion
+//#region src/lib/write.ts
+/**
+* Write rendered files to disk with optional conflict detection.
+*
+* For each file, resolves the target path under `outputDir`, creates parent
+* directories as needed, and writes the content. When `overwrite` is false,
+* existing files are skipped rather than overwritten.
+*
+* @param params - Files to write, target directory, and overwrite flag.
+* @returns An async Result with counts of written/skipped files or a GenerateError.
+*/
+async function writeFiles(params) {
+	const written = [];
+	const skipped = [];
+	const results = await Promise.all(params.files.map((file) => writeSingleFile(file, params.outputDir, params.overwrite)));
+	const firstError = results.find((r) => r[0] !== null);
+	if (firstError) return [firstError[0], null];
+	const validStatuses = results.filter((r) => r[1] !== null);
+	const writtenPaths = validStatuses.filter(([, status]) => status.action === "written").map(([, status]) => status.path);
+	const skippedPaths = validStatuses.filter(([, status]) => status.action === "skipped").map(([, status]) => status.path);
+	writtenPaths.map((p) => written.push(p));
+	skippedPaths.map((p) => skipped.push(p));
+	return ok({
+		skipped,
+		written
+	});
+}
+/**
+* Write a single rendered file to disk.
+*
+* @param file - The rendered file to write.
+* @param outputDir - The root output directory.
+* @param overwrite - Whether to overwrite existing files.
+* @returns A Result tuple with the write status or a GenerateError.
+* @private
+*/
+async function writeSingleFile(file, outputDir, overwrite) {
+	const targetPath = join(outputDir, file.relativePath);
+	try {
+		if (await fileExists(targetPath) && !overwrite) return ok({
+			action: "skipped",
+			path: file.relativePath
+		});
+		await mkdir(dirname(targetPath), { recursive: true });
+		await writeFile(targetPath, file.content, "utf8");
+		return ok({
+			action: "written",
+			path: file.relativePath
+		});
+	} catch (error) {
+		return [{
+			message: `Failed to write file: ${toErrorMessage(error)}`,
+			path: targetPath,
+			type: "write_error"
+		}, null];
+	}
+}
+/**
+* Check whether a path exists on disk.
+*
+* @param filePath - The path to check.
+* @returns True when the path is accessible, false otherwise.
+* @private
+*/
+async function fileExists(filePath) {
+	const [err] = await attemptAsync(() => access(filePath));
+	return err === null;
+}
+
+//#endregion
+export { renderTemplate as n, writeFiles as t };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@kidd-cli/cli",
+  "version": "0.1.0",
+  "description": "DX companion CLI for the kidd framework",
+  "keywords": [
+    "cli",
+    "codegen",
+    "kidd",
+    "scaffolding"
+  ],
+  "license": "MIT",
+  "bin": {
+    "kidd": "./dist/index.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "dependencies": {
+    "fs-extra": "^11.3.3",
+    "liquidjs": "^10.24.0",
+    "picocolors": "^1.1.1",
+    "zod": "^4.3.6",
+    "@kidd-cli/bundler": "0.1.0",
+    "@kidd-cli/core": "0.1.0",
+    "@kidd-cli/utils": "0.1.0",
+    "@kidd-cli/config": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "tsdown": "0.21.0-beta.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "scripts": {
+    "build": "tsdown && mkdir -p dist/lib && cp -r src/lib/templates dist/lib/templates",
+    "typecheck": "tsgo --noEmit",
+    "lint": "oxlint --ignore-pattern node_modules",
+    "lint:fix": "oxlint --fix --ignore-pattern node_modules",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}