@vlandoss/vland 0.2.1-git-74f39bb.0 → 0.2.1-git-a1181c2.0

package/dist/cli.usage.kdl

@@ -0,0 +1,34 @@
+// @generated by @usage-spec/commander from Commander.js metadata
+name vland
+bin vland
+version "0.2.1-git-a1181c2.0"
+usage "[options] [command]"
+flag --usage help="print KDL spec for this CLI (https://kdl.dev)"
+cmd completion help="print shell completion script 🐚 (usage)" {
+	long_help "Prints a shell completion script for vland. Add to your shell rc file:\n\n  bash: eval \"$(vland completion bash)\"\n  zsh:  eval \"$(vland completion zsh)\"\n  fish: vland completion fish | source"
+	arg <shell> help="target shell" {
+		choices bash zsh fish
+	}
+}
+cmd init help="init a new project 🚀 (giget)" {
+	long_help "Scaffold a new variableland project from one of the official templates."
+	flag "-t --template" help="template to use" {
+		arg <TEMPLATE> {
+			choices library backend monorepo
+		}
+	}
+	flag "-d --dir" help="target directory (default: ./<name>)" {
+		arg <DIR>
+	}
+	flag --pm help="package manager to use" {
+		arg <PM> {
+			choices npm pnpm yarn bun
+		}
+	}
+	flag --install help="install dependencies (skip prompt)"
+	flag --no-install help="skip dependency installation" negate=--install
+	flag --git help="initialise git repository (skip prompt)"
+	flag --no-git help="skip git init" negate=--git
+	flag "-f --force" help="overwrite existing directory"
+	arg "[name]" help="project name (also used as the target directory)" required=#false
+}

package/dist/run.mjs

@@ -0,0 +1,443 @@
+import path, { extname, isAbsolute, join, resolve } from "node:path";
+import { colorize, createPkg, createShellService, dirnameOf, hasTTY, palette, run, text } from "@vlandoss/clibuddy";
+import { Argument, Command, Option, createCommand } from "commander";
+import fs from "node:fs";
+import { createLoggy } from "@vlandoss/loggy";
+import { cp, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text as text$1 } from "@clack/prompts";
+import { detectPackageManager, installDependencies } from "nypm";
+import { downloadTemplate } from "giget";
+import { generateToStdout } from "@usage-spec/commander";
+//#region src/services/logger.ts
+const logger = createLoggy({ namespace: "vland" });
+//#endregion
+//#region src/services/ctx.ts
+async function createContext(binDir) {
+	const debug = logger.subdebug("create-context");
+	const binPath = fs.realpathSync(binDir);
+	debug("bin path:", binPath);
+	const binPkg = await createPkg(binPath);
+	if (!binPkg) throw new Error("Could not find bin package.json");
+	debug("bin pkg info: %O", binPkg.info());
+	const shell = createShellService();
+	debug("shell service options: %O", shell.options);
+	return {
+		binPkg,
+		shell
+	};
+}
+//#endregion
+//#region src/program/ui.ts
+const vlandColor = colorize("#a78bfa");
+const usageColor = colorize("#24C55E");
+const gigetColor = colorize("#F472B6");
+const TOOL_LABELS = {
+	USAGE: usageColor("usage"),
+	GIGET: gigetColor("giget")
+};
+function getBannerText(version) {
+	return `
+${vlandColor(`
+██╗   ██╗██╗      █████╗ ███╗   ██╗██████╗
+██║   ██║██║     ██╔══██╗████╗  ██║██╔══██╗
+██║   ██║██║     ███████║██╔██╗ ██║██║  ██║
+╚██╗ ██╔╝██║     ██╔══██║██║╚██╗██║██║  ██║
+ ╚████╔╝ ███████╗██║  ██║██║ ╚████║██████╔╝
+  ╚═══╝  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝ ${text.version(version)}
+`.trim())}
+
+🦉 ${palette.italic(palette.muted("The CLI to init a new project in"))} ${text.vland}\n`.trimStart();
+}
+//#endregion
+//#region src/program/commands/completion.ts
+const SHELLS = [
+	"bash",
+	"zsh",
+	"fish"
+];
+function createCompletionCommand() {
+	return createCommand("completion").summary(`print shell completion script 🐚 (${TOOL_LABELS.USAGE})`).description(`Prints a shell completion script for vland. Add to your shell rc file:
+
+  bash: eval "$(vland completion bash)"
+  zsh:  eval "$(vland completion zsh)"
+  fish: vland completion fish | source`).addArgument(new Argument("<shell>", `target shell`).choices(SHELLS)).addHelpText("afterAll", `\nUnder the hood, this command uses ${TOOL_LABELS.USAGE} (https://usage.jdx.dev).
+Make sure to have it installed and available in your PATH.`);
+}
+//#endregion
+//#region src/actions/placeholders.ts
+const TEXT_EXTENSIONS = new Set([
+	".ts",
+	".tsx",
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".mts",
+	".cts",
+	".json",
+	".jsonc",
+	".md",
+	".mdx",
+	".yml",
+	".yaml",
+	".toml",
+	".css",
+	".html",
+	".sh",
+	".env",
+	".gitignore",
+	".gitattributes",
+	".npmrc",
+	".nvmrc",
+	".node-version",
+	".dockerignore",
+	".editorconfig",
+	".prettierrc"
+]);
+const TEXT_FILENAMES = new Set([
+	"Dockerfile",
+	"LICENSE",
+	"README",
+	"CHANGELOG",
+	".gitignore",
+	".gitattributes",
+	".npmrc",
+	".nvmrc",
+	".node-version",
+	".dockerignore",
+	".editorconfig",
+	".prettierrc",
+	"lefthook.yml",
+	"mise.toml"
+]);
+const SKIP_DIRS = new Set([
+	"node_modules",
+	".git",
+	"dist",
+	".turbo",
+	".next",
+	"build",
+	"coverage"
+]);
+function isTextFile(name) {
+	if (TEXT_FILENAMES.has(name)) return true;
+	return TEXT_EXTENSIONS.has(extname(name));
+}
+async function walk(root, onFile) {
+	const entries = await readdir(root, { withFileTypes: true });
+	await Promise.all(entries.map(async (entry) => {
+		const full = join(root, entry.name);
+		if (entry.isDirectory()) {
+			if (SKIP_DIRS.has(entry.name)) return;
+			await walk(full, onFile);
+			return;
+		}
+		if (entry.isFile()) await onFile(full);
+	}));
+}
+function applyPlaceholders(content, values) {
+	return content.replaceAll("{{projectName}}", values.projectName).replaceAll("{{author}}", values.author).replaceAll("{{year}}", values.year);
+}
+async function replacePlaceholders(rootDir, values) {
+	const debug = logger.subdebug("placeholders");
+	let touched = 0;
+	await walk(rootDir, async (filePath) => {
+		if (!isTextFile(filePath.split("/").pop() ?? "")) return;
+		if ((await stat(filePath)).size > 1e6) return;
+		const original = await readFile(filePath, "utf8");
+		const replaced = applyPlaceholders(original, values);
+		if (replaced !== original) {
+			await writeFile(filePath, replaced);
+			touched += 1;
+		}
+	});
+	debug("placeholders applied to %d file(s)", touched);
+	return { touched };
+}
+/**
+* Updates the root `package.json` `name` field via `pkg-types`. Safer than a
+* regex pass because it preserves field ordering and JSON formatting handled
+* by `pkg-types`.
+*/
+async function updateRootPackageName(rootDir, projectName) {
+	const debug = logger.subdebug("update-root-package-name");
+	const rootPath = fs.realpathSync(rootDir);
+	debug("root path:", rootPath);
+	debug("process cwd:", process.cwd());
+	const pkg = await createPkg(rootPath);
+	if (!pkg) throw new Error("Could not find package.json");
+	try {
+		pkg.packageJson.name = projectName;
+		await pkg.write(pkg.packageJson);
+	} catch (error) {
+		debug("skipped %s", error);
+	}
+}
+//#endregion
+//#region src/actions/template.ts
+const TEMPLATES = [
+	"library",
+	"backend",
+	"monorepo"
+];
+const TEMPLATE_META = {
+	library: {
+		placeholder: "my-lib",
+		runScript: "test"
+	},
+	backend: {
+		placeholder: "my-api",
+		runScript: "dev"
+	},
+	monorepo: {
+		placeholder: "my-mono",
+		runScript: "dev"
+	}
+};
+const GITHUB_SOURCE = "github:variableland/dx";
+const GITHUB_REF = "main";
+/**
+* Resolves the template into `dir`. Source order:
+* 1. `VLAND_TEMPLATES_DIR` env var → copy from local path (used by E2E tests
+*    against the in-repo `templates/`).
+* 2. Otherwise → download via giget from `github:variableland/dx/templates/<name>`.
+*/
+async function fetchTemplate(options) {
+	const debug = logger.subdebug("fetch-template");
+	const localRoot = process.env.VLAND_TEMPLATES_DIR;
+	if (localRoot) {
+		const sourceDir = resolve(localRoot, options.template);
+		debug("local source: %s", sourceDir);
+		await cp(sourceDir, options.dir, {
+			recursive: true,
+			force: options.force,
+			errorOnExist: !options.force,
+			filter: (src) => !src.includes("/node_modules") && !src.endsWith("/.turbo") && !src.endsWith("/dist")
+		});
+		return { source: sourceDir };
+	}
+	const source = `${GITHUB_SOURCE}/templates/${options.template}#${GITHUB_REF}`;
+	debug("remote source: %s", source);
+	return { source: (await downloadTemplate(source, {
+		dir: options.dir,
+		force: options.force,
+		install: false
+	})).source };
+}
+//#endregion
+//#region src/actions/init.ts
+const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+function validateProjectName(name) {
+	if (!name || !name.trim()) return "Name is required.";
+	if (/\s/.test(name)) return "Name cannot contain whitespace.";
+	if (name.startsWith(".") || name.startsWith("/") || name.startsWith("\\")) return "Name cannot start with '.', '/' or '\\'.";
+	if (name.includes("..")) return "Name cannot contain '..'.";
+	if (!NPM_NAME_RE.test(name)) return "Name must be a valid npm package name (lowercase, no spaces).";
+}
+async function isDirEmpty(dir) {
+	try {
+		return (await readdir(dir)).length === 0;
+	} catch (error) {
+		if (error.code === "ENOENT") return true;
+		throw error;
+	}
+}
+async function readGitAuthor(shell) {
+	try {
+		const [name, email] = await Promise.all([shell.runCaptured("git", [
+			"config",
+			"--get",
+			"user.name"
+		], { throwOnError: false }), shell.runCaptured("git", [
+			"config",
+			"--get",
+			"user.email"
+		], { throwOnError: false })]);
+		const trimmedName = name.stdout.trim();
+		const trimmedEmail = email.stdout.trim();
+		if (!trimmedName) return void 0;
+		return trimmedEmail ? `${trimmedName} <${trimmedEmail}>` : trimmedName;
+	} catch {
+		return;
+	}
+}
+function abort(message) {
+	cancel(message);
+	process.exit(1);
+}
+async function runInit(ctx, options) {
+	const debug = logger.subdebug("init");
+	debug("options: %O", options);
+	const shell = ctx.shell;
+	intro(`${palette.label(" vland init ")}`);
+	let template = options.template;
+	if (!template) {
+		if (!hasTTY) abort("Template is required in non-interactive environments. Use --template <library|backend|monorepo>.");
+		const choice = await select({
+			message: "Pick a template",
+			options: TEMPLATES.map((value) => ({
+				value,
+				label: value
+			}))
+		});
+		if (isCancel(choice)) abort("Cancelled.");
+		template = choice;
+	}
+	let name = options.name;
+	if (!name) {
+		if (!hasTTY) abort("Project name is required in non-interactive environments. Pass it as the first argument.");
+		const value = await text$1({
+			message: "Project name",
+			placeholder: TEMPLATE_META[template].placeholder,
+			validate: (input) => validateProjectName(input ?? "")
+		});
+		if (isCancel(value)) abort("Cancelled.");
+		name = value;
+	}
+	const nameError = validateProjectName(name);
+	if (nameError) abort(nameError);
+	const dir = options.dir ? isAbsolute(options.dir) ? options.dir : resolve(process.cwd(), options.dir) : resolve(process.cwd(), name);
+	debug("target dir: %s", dir);
+	if (!await isDirEmpty(dir) && !options.force) abort(`Target directory ${palette.highlight(dir)} is not empty. Re-run with ${palette.highlight("--force")} to overwrite.`);
+	let author = await readGitAuthor(shell);
+	if (!author) if (!hasTTY) author = "";
+	else {
+		const value = await text$1({
+			message: "Author (used in package.json / LICENSE)",
+			placeholder: "Jane Doe <jane@example.com>",
+			defaultValue: ""
+		});
+		if (isCancel(value)) abort("Cancelled.");
+		author = value || "";
+	}
+	debug("author: %s", author || "<empty>");
+	const fetchSpin = spinner();
+	fetchSpin.start(`Fetching ${palette.highlight(template)} template`);
+	try {
+		const { source } = await fetchTemplate({
+			template,
+			dir,
+			force: options.force
+		});
+		fetchSpin.stop(`Fetched template from ${palette.muted(source)}`);
+	} catch (error) {
+		fetchSpin.stop("Failed to fetch template", 1);
+		throw error;
+	}
+	const placeholderSpin = spinner();
+	placeholderSpin.start("Applying placeholders");
+	await replacePlaceholders(dir, {
+		projectName: name,
+		author,
+		year: (/* @__PURE__ */ new Date()).getFullYear().toString()
+	});
+	await updateRootPackageName(dir, name);
+	placeholderSpin.stop("Placeholders applied");
+	const shouldInstall = await resolveYesNo(options.install, "Install dependencies?");
+	const shouldGit = await resolveYesNo(options.git, "Initialise a git repository?");
+	if (shouldInstall) {
+		const detected = options.pm ?? (await detectPackageManager(dir, { ignorePackageJSON: false }))?.name ?? "pnpm";
+		const installSpin = spinner();
+		installSpin.start(`Installing dependencies with ${palette.highlight(detected)}`);
+		try {
+			await installDependencies({
+				cwd: dir,
+				packageManager: {
+					name: detected,
+					command: detected
+				},
+				silent: true
+			});
+			installSpin.stop(`Installed with ${palette.highlight(detected)}`);
+		} catch (error) {
+			installSpin.stop("Failed to install dependencies", 1);
+			log.warn("You can install manually later with `cd <dir> && <pm> install`.");
+			debug("install error: %O", error);
+		}
+	} else log.info(`Skipping ${palette.highlight("install")}.`);
+	if (shouldGit) {
+		const gitSpin = spinner();
+		gitSpin.start("Initialising git repository");
+		try {
+			const gitShell = shell.at(dir).child({ env: {
+				GIT_AUTHOR_NAME: process.env.GIT_AUTHOR_NAME ?? "vland",
+				GIT_AUTHOR_EMAIL: process.env.GIT_AUTHOR_EMAIL ?? "noreply@variable.land",
+				GIT_COMMITTER_NAME: process.env.GIT_COMMITTER_NAME ?? "vland",
+				GIT_COMMITTER_EMAIL: process.env.GIT_COMMITTER_EMAIL ?? "noreply@variable.land"
+			} });
+			await gitShell.runCaptured("git", ["init"]);
+			await gitShell.runCaptured("git", ["add", "-A"]);
+			await gitShell.runCaptured("git", [
+				"commit",
+				"-m",
+				"chore: initial commit from vland"
+			]);
+			gitSpin.stop("Initialised git repository");
+		} catch (error) {
+			gitSpin.stop("Failed to initialise git", 1);
+			debug("git error: %O", error);
+		}
+	} else log.info(`Skipping ${palette.highlight("git init")}.`);
+	const detectedPm = options.pm ?? (await detectPackageManager(dir, { ignorePackageJSON: false }))?.name ?? "pnpm";
+	const runScript = TEMPLATE_META[template].runScript;
+	outro([
+		palette.success("Done!"),
+		"",
+		palette.muted("Next steps:"),
+		`  cd ${name}`,
+		shouldInstall ? `  ${detectedPm} ${runScript}` : `  ${detectedPm} install && ${detectedPm} ${runScript}`
+	].join("\n"));
+}
+async function resolveYesNo(explicit, message) {
+	if (typeof explicit === "boolean") return explicit;
+	if (!hasTTY) return true;
+	const value = await confirm({
+		message,
+		initialValue: true
+	});
+	if (isCancel(value)) abort("Cancelled.");
+	return value;
+}
+//#endregion
+//#region src/program/commands/init.ts
+function createInitCommand(ctx) {
+	return createCommand("init").summary(`init a new project 🚀 (${TOOL_LABELS.GIGET})`).description("Scaffold a new variableland project from one of the official templates.").addArgument(new Argument("[name]", "project name (also used as the target directory)")).addOption(new Option("-t, --template <name>", "template to use").choices([...TEMPLATES])).addOption(new Option("-d, --dir <path>", "target directory (default: ./<name>)")).addOption(new Option("--pm <manager>", "package manager to use").choices([
+		"npm",
+		"pnpm",
+		"yarn",
+		"bun"
+	])).addOption(new Option("--install", "install dependencies (skip prompt)")).addOption(new Option("--no-install", "skip dependency installation")).addOption(new Option("--git", "initialise git repository (skip prompt)")).addOption(new Option("--no-git", "skip git init")).addOption(new Option("-f, --force", "overwrite existing directory").default(false)).action(async function(name, options) {
+		console.log(getBannerText(ctx.binPkg.version));
+		const installSource = this.getOptionValueSource("install");
+		const gitSource = this.getOptionValueSource("git");
+		await runInit(ctx, {
+			name,
+			...options,
+			install: installSource === "cli" ? options.install : void 0,
+			git: gitSource === "cli" ? options.git : void 0
+		});
+	});
+}
+//#endregion
+//#region src/program/commands/usage.ts
+function addUsage(program) {
+	return program.addOption(new Option("--usage", "print KDL spec for this CLI (https://kdl.dev)")).on("option:usage", () => {
+		generateToStdout(program);
+		process.exit(0);
+	});
+}
+//#endregion
+//#region src/program/index.ts
+async function createProgram(options) {
+	const ctx = await createContext(options.binDir);
+	const version = ctx.binPkg.version;
+	return addUsage(new Command("vland").version(version, "-v, --version").addHelpText("before", getBannerText(version)).addCommand(createCompletionCommand()).addCommand(createInitCommand(ctx)));
+}
+//#endregion
+//#region src/run.ts
+const BIN_DIR = path.dirname(dirnameOf(import.meta));
+await run(async () => {
+	await (await createProgram({ binDir: BIN_DIR })).parseAsync();
+}, logger);
+//#endregion
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vlandoss/vland",
-  "version": "0.2.1-git-74f39bb.0",
+  "version": "0.2.1-git-a1181c2.0",
   "description": "The CLI to init a new project in Variable Land",
   "homepage": "https://github.com/variableland/dx/tree/main/packages/vland#readme",
   "bugs": {
@@ -12,10 +12,7 @@
     "directory": "packages/vland"
   },
   "license": "MIT",
-  "author": {
-    "name": "rcrd",
-    "email": "rcrd@variable.land"
-  },
+  "author": "rcrd <rcrd@variable.land>",
   "type": "module",
   "imports": {
     "#src/*": "./src/*",
@@ -35,11 +32,11 @@
   "dependencies": {
     "@clack/prompts": "0.11.0",
     "@usage-spec/commander": "1.1.0",
-    "@vlandoss/clibuddy": "0.6.1-git-74f39bb.0",
-    "@vlandoss/loggy": "0.2.1-git-74f39bb.0",
     "commander": "14.0.3",
     "giget": "2.0.0",
-    "nypm": "0.6.0"
+    "nypm": "0.6.0",
+    "@vlandoss/clibuddy": "0.6.1-git-a1181c2.0",
+    "@vlandoss/loggy": "0.2.1-git-a1181c2.0"
   },
   "publishConfig": {
     "access": "public"
@@ -50,8 +47,6 @@
   "devDependencies": {
     "@vlandoss/tsdown-config": "^0.0.1"
   },
-  "readme": "ERROR: No README data found!",
-  "_id": "@vlandoss/vland@0.2.0",
   "scripts": {
     "build": "tsdown && pnpm build:kdl",
     "build:kdl": "./bin --usage > dist/cli.usage.kdl",
@@ -60,4 +55,4 @@
     "test:integration": "vitest run --project integration",
     "test:types": "rr tsc"
   }
-}
+}