@vlandoss/vland 0.0.1-git-53b6b02.0

package/README.md

@@ -0,0 +1,80 @@
+# 🦉 vland
+
+The CLI to init a new project in Variable Land 👊
+
+## Prerequisites
+
+- Node.js >= 20.0.0
+
+## Installation
+
+Run it directly with `npx`:
+
+```sh
+npx @vlandoss/vland init
+```
+
+…or install it globally:
+
+```sh
+pnpm add -g @vlandoss/vland
+vland init
+```
+
+## Usage
+
+```sh
+vland init                        # interactive
+vland init my-app -t library      # explicit template
+vland init my-app -t backend --no-install --no-git
+```
+
+See [`CLI.md`](./CLI.md) for the full reference (auto-generated per release).
+
+### Templates
+
+| Template   | What you get |
+|------------|--------------|
+| `library`  | A standalone TypeScript library with tsdown, Vitest, biome, Changesets release workflow. |
+| `backend`  | An Elysia (`@elysiajs/node`) backend with evlog, Vitest, Dockerfile, CI shape. |
+| `monorepo` | pnpm + Turbo workspace with an Elysia API, a Vite-React SPA, and a few internal packages. |
+
+All templates target Node.js, use pnpm, and extend `@vlandoss/config` for biome and tsconfig.
+
+## Shell completion
+
+`vland` ships a `completion` subcommand that prints a shell-specific script. Add it to your shell rc file:
+
+```sh
+# zsh — ~/.zshrc
+eval "$(vland completion zsh)"
+
+# bash — ~/.bashrc
+eval "$(vland completion bash)"
+
+# fish — ~/.config/fish/config.fish
+vland completion fish | source
+```
+
+**Prerequisite:** the [`usage`](https://usage.jdx.dev) CLI must be on your `PATH` (it powers completion at runtime). Install via one of:
+
+```sh
+mise use -g usage
+brew install usage
+```
+
+When you upgrade `@vlandoss/vland`, the next shell session will pick up new commands automatically — no need to re-run anything.
+
+## Troubleshooting
+
+To enable debug mode, set the `DEBUG` environment variable to `vland:*` before running *any* command.
+
+```sh
+DEBUG=vland:* vland init my-app
+```
+
+To point `init` at local templates instead of fetching from GitHub (useful when developing inside this monorepo):
+
+```sh
+VLAND_TEMPLATES_DIR=/absolute/path/to/dx/templates vland init my-app -t library
+```

package/bin

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+set -e
+
+SOURCE="${BASH_SOURCE[0]}"
+while [ -L "$SOURCE" ]; do
+  TARGET="$(readlink "$SOURCE")"
+  case "$TARGET" in
+    /*) SOURCE="$TARGET" ;;
+    *) SOURCE="$(dirname "$SOURCE")/$TARGET" ;;
+  esac
+done
+DIR="$(cd "$(dirname "$SOURCE")" && pwd)"
+
+if [ "$1" = "completion" ]; then
+  case "$2" in
+    bash | zsh | fish)
+      kdl="$DIR/dist/cli.usage.kdl"
+      if [ ! -f "$kdl" ]; then
+        echo "vland completion: missing $kdl. Reinstall @vlandoss/vland or run \`pnpm build\`." >&2
+        exit 1
+      fi
+      if ! command -v usage >/dev/null 2>&1; then
+        echo "vland completion: 'usage' CLI not found in PATH." >&2
+        echo "Install via: mise use -g usage  |  brew install usage" >&2
+        exit 1
+      fi
+      exec usage generate completion "$2" vland --file "$kdl"
+      ;;
+  esac
+  # Unknown shell or `--help`: fall through to Node so Commander prints help/errors.
+fi
+
+# In the source repo (tsdown.config.ts present, NOT shipped in the npm tarball),
+# always run from src/ so live edits show up. In a published install, use the
+# bundled dist/run.mjs.
+if [ -f "$DIR/tsdown.config.ts" ]; then
+  exec node "$DIR/src/run.ts" "$@"
+else
+  exec node "$DIR/dist/run.mjs" "$@"
+fi

package/dist/cli.usage.kdl

@@ -0,0 +1,32 @@
+// @generated by @usage-spec/commander from Commander.js metadata
+name vland
+bin vland
+version "0.0.1-git-53b6b02.0"
+usage "[options] [command]"
+flag --usage help="print KDL spec for this CLI (https://kdl.dev)"
+cmd completion help="print shell completion script 🐚 (\u{1b}[38;2;36;197;94musage\u{1b}[39m)" {
+	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 🚀 (\u{1b}[38;2;244;114;182mgiget\u{1b}[39m)" {
+	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 --no-install help="skip dependency installation" negate=--install
+	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,399 @@
+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, 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({ localBaseBinPath: [binDir] });
+	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 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.$`git config --get user.name`.nothrow(), shell.$`git config --get user.email`.nothrow()]);
+		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.mute();
+	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: "my-app",
+			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");
+	if (options.install) {
+		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
+				}
+			});
+			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")} (--no-install).`);
+	if (options.git) {
+		const gitSpin = spinner();
+		gitSpin.start("Initialising git repository");
+		try {
+			const gitShell = shell.at(dir).child({ env: {
+				...process.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.$`git init`;
+			await gitShell.$`git add -A`;
+			await gitShell.$`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")} (--no-git).`);
+	const detectedPm = options.pm ?? (await detectPackageManager(dir, { ignorePackageJSON: false }))?.name ?? "pnpm";
+	outro([
+		palette.success("Done!"),
+		"",
+		palette.muted("Next steps:"),
+		`  cd ${name}`,
+		options.install ? `  ${detectedPm} dev` : `  ${detectedPm} install && ${detectedPm} dev`
+	].join("\n"));
+}
+//#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("--no-install", "skip dependency installation")).addOption(new Option("--no-git", "skip git init")).addOption(new Option("-f, --force", "overwrite existing directory").default(false)).action(async (name, options) => {
+		await runInit(ctx, {
+			name,
+			...options
+		});
+	});
+}
+//#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

@@ -0,0 +1,58 @@
+{
+  "name": "@vlandoss/vland",
+  "version": "0.0.1-git-53b6b02.0",
+  "description": "The CLI to init a new project in Variable Land",
+  "homepage": "https://github.com/variableland/dx/tree/main/packages/vland#readme",
+  "bugs": {
+    "url": "https://github.com/variableland/dx/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/variableland/dx.git",
+    "directory": "packages/vland"
+  },
+  "license": "MIT",
+  "author": "rcrd <rcrd@variable.land>",
+  "type": "module",
+  "imports": {
+    "#src/*": "./src/*",
+    "#test/*": "./test/*"
+  },
+  "bin": {
+    "vland": "./bin"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "!src/**/__tests__",
+    "!src/**/*.test.*",
+    "tsconfig.json"
+  ],
+  "dependencies": {
+    "@clack/prompts": "0.11.0",
+    "@usage-spec/commander": "1.1.0",
+    "commander": "14.0.3",
+    "giget": "2.0.0",
+    "nypm": "0.6.0",
+    "@vlandoss/clibuddy": "0.4.1-git-53b6b02.0",
+    "@vlandoss/loggy": "0.2.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@vlandoss/tsdown-config": "^0.0.1"
+  },
+  "scripts": {
+    "build": "tsdown && pnpm build:kdl",
+    "build:kdl": "./bin --usage > dist/cli.usage.kdl",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:types": "rr tsc"
+  }
+}

package/src/actions/init.ts

@@ -0,0 +1,210 @@
+import { readdir } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { cancel, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
+import { hasTTY, palette } from "@vlandoss/clibuddy";
+import { detectPackageManager, installDependencies } from "nypm";
+import type { Context } from "#src/services/ctx.ts";
+import { logger } from "#src/services/logger.ts";
+import { replacePlaceholders, updateRootPackageName } from "./placeholders.ts";
+import { fetchTemplate, TEMPLATES, type TemplateName } from "./template.ts";
+
+export type InitOptions = {
+  name?: string;
+  template?: TemplateName;
+  dir?: string;
+  pm?: "npm" | "pnpm" | "yarn" | "bun";
+  install: boolean;
+  git: boolean;
+  force: boolean;
+};
+
+const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
+
+function validateProjectName(name: string): string | undefined {
+  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).";
+  }
+  return undefined;
+}
+
+async function isDirEmpty(dir: string): Promise<boolean> {
+  try {
+    const entries = await readdir(dir);
+    return entries.length === 0;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return true;
+    throw error;
+  }
+}
+
+async function readGitAuthor(shell: Context["shell"]): Promise<string | undefined> {
+  try {
+    const [name, email] = await Promise.all([
+      shell.$`git config --get user.name`.nothrow(),
+      shell.$`git config --get user.email`.nothrow(),
+    ]);
+    const trimmedName = name.stdout.trim();
+    const trimmedEmail = email.stdout.trim();
+    if (!trimmedName) return undefined;
+    return trimmedEmail ? `${trimmedName} <${trimmedEmail}>` : trimmedName;
+  } catch {
+    return undefined;
+  }
+}
+
+function abort(message: string): never {
+  cancel(message);
+  process.exit(1);
+}
+
+export async function runInit(ctx: Context, options: InitOptions) {
+  const debug = logger.subdebug("init");
+  debug("options: %O", options);
+
+  // Mute zx so the @clack/prompts UI stays clean while git output is captured.
+  const shell = ctx.shell.mute();
+
+  intro(`${palette.label(" vland init ")}`);
+
+  // 1. Resolve template
+  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 as TemplateName;
+  }
+
+  // 2. Resolve project name
+  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({
+      message: "Project name",
+      placeholder: "my-app",
+      validate: (input) => validateProjectName(input ?? ""),
+    });
+    if (isCancel(value)) abort("Cancelled.");
+    name = value as string;
+  }
+  const nameError = validateProjectName(name);
+  if (nameError) abort(nameError);
+
+  // 3. Resolve target dir
+  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.`);
+  }
+
+  // 4. Resolve author
+  let author = await readGitAuthor(shell);
+  if (!author) {
+    if (!hasTTY) {
+      author = "";
+    } else {
+      const value = await text({
+        message: "Author (used in package.json / LICENSE)",
+        placeholder: "Jane Doe <jane@example.com>",
+        defaultValue: "",
+      });
+      if (isCancel(value)) abort("Cancelled.");
+      author = (value as string) || "";
+    }
+  }
+  debug("author: %s", author || "<empty>");
+
+  // 5. Download template
+  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;
+  }
+
+  // 6. Replace placeholders
+  const placeholderSpin = spinner();
+  placeholderSpin.start("Applying placeholders");
+  await replacePlaceholders(dir, {
+    projectName: name,
+    author,
+    year: new Date().getFullYear().toString(),
+  });
+  await updateRootPackageName(dir, name);
+  placeholderSpin.stop("Placeholders applied");
+
+  // 7. Install deps
+  if (options.install) {
+    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 } });
+      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")} (--no-install).`);
+  }
+
+  // 8. Git init
+  if (options.git) {
+    const gitSpin = spinner();
+    gitSpin.start("Initialising git repository");
+    try {
+      const gitShell = shell.at(dir).child({
+        env: {
+          ...process.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.$`git init`;
+      await gitShell.$`git add -A`;
+      await gitShell.$`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")} (--no-git).`);
+  }
+
+  // 9. Outro with next steps
+  const detectedPm = options.pm ?? (await detectPackageManager(dir, { ignorePackageJSON: false }))?.name ?? "pnpm";
+  outro(
+    [
+      palette.success("Done!"),
+      "",
+      palette.muted("Next steps:"),
+      `  cd ${name}`,
+      options.install ? `  ${detectedPm} dev` : `  ${detectedPm} install && ${detectedPm} dev`,
+    ].join("\n"),
+  );
+}

package/src/actions/placeholders.ts

@@ -0,0 +1,139 @@
+import fs from "node:fs";
+import { readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { createPkg } from "@vlandoss/clibuddy";
+import { logger } from "#src/services/logger.ts";
+
+export type Placeholders = {
+  projectName: string;
+  author: string;
+  year: string;
+};
+
+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: string) {
+  if (TEXT_FILENAMES.has(name)) return true;
+  return TEXT_EXTENSIONS.has(extname(name));
+}
+
+async function walk(root: string, onFile: (path: string) => Promise<void>) {
+  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: string, values: Placeholders) {
+  return content
+    .replaceAll("{{projectName}}", values.projectName)
+    .replaceAll("{{author}}", values.author)
+    .replaceAll("{{year}}", values.year);
+}
+
+export async function replacePlaceholders(rootDir: string, values: Placeholders) {
+  const debug = logger.subdebug("placeholders");
+  let touched = 0;
+
+  await walk(rootDir, async (filePath) => {
+    const name = filePath.split("/").pop() ?? "";
+    if (!isTextFile(name)) return;
+
+    const fileStat = await stat(filePath);
+    if (fileStat.size > 1_000_000) return; // skip files >1MB; templates shouldn't have those
+
+    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`.
+ */
+export async function updateRootPackageName(rootDir: string, projectName: string) {
+  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);
+  }
+}

package/src/actions/template.ts

@@ -0,0 +1,48 @@
+import { cp } from "node:fs/promises";
+import { resolve } from "node:path";
+import { downloadTemplate } from "giget";
+import { logger } from "#src/services/logger.ts";
+
+export const TEMPLATES = ["library", "backend", "monorepo"] as const;
+export type TemplateName = (typeof TEMPLATES)[number];
+
+const GITHUB_SOURCE = "github:variableland/dx";
+const GITHUB_REF = "main";
+
+type ResolveOptions = {
+  template: TemplateName;
+  dir: string;
+  force: boolean;
+};
+
+/**
+ * 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>`.
+ */
+export async function fetchTemplate(options: ResolveOptions): Promise<{ source: string }> {
+  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);
+  const result = await downloadTemplate(source, {
+    dir: options.dir,
+    force: options.force,
+    install: false,
+  });
+  return { source: result.source };
+}

package/src/program/commands/completion.ts

@@ -0,0 +1,26 @@
+import { Argument, createCommand } from "commander";
+import { TOOL_LABELS } from "../ui.ts";
+
+const SHELLS = ["bash", "zsh", "fish"] as const;
+
+// Ghost command: registered with Commander purely for discoverability — it surfaces
+// in `vland --help` and is baked into dist/cli.usage.kdl so the completion itself can
+// suggest "completion" after `vland <TAB>`. The actual handler lives in the bash bin
+// dispatcher, which intercepts `vland completion <shell>` before reaching Node.
+export 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.`,
+    );
+}

package/src/program/commands/init.ts

@@ -0,0 +1,33 @@
+import { Argument, createCommand, Option } from "commander";
+import { runInit } from "#src/actions/init.ts";
+import { TEMPLATES, type TemplateName } from "#src/actions/template.ts";
+import type { Context } from "#src/services/ctx.ts";
+import { TOOL_LABELS } from "../ui.ts";
+
+type InitOptions = {
+  dir?: string;
+  template?: TemplateName;
+  pm?: "npm" | "pnpm" | "yarn" | "bun";
+  install: boolean;
+  git: boolean;
+  force: boolean;
+};
+
+export function createInitCommand(ctx: Context) {
+  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("--no-install", "skip dependency installation"))
+    .addOption(new Option("--no-git", "skip git init"))
+    .addOption(new Option("-f, --force", "overwrite existing directory").default(false))
+    .action(async (name: string | undefined, options: InitOptions) => {
+      await runInit(ctx, {
+        name,
+        ...options,
+      });
+    });
+}

package/src/program/commands/usage.ts

@@ -0,0 +1,9 @@
+import { generateToStdout } from "@usage-spec/commander";
+import { type Command, Option } from "commander";
+
+export function addUsage(program: Command) {
+  return program.addOption(new Option("--usage", "print KDL spec for this CLI (https://kdl.dev)")).on("option:usage", () => {
+    generateToStdout(program);
+    process.exit(0);
+  });
+}

package/src/program/index.ts

@@ -0,0 +1,23 @@
+import { Command } from "commander";
+import { createContext } from "#src/services/ctx.ts";
+import { createCompletionCommand } from "./commands/completion.ts";
+import { createInitCommand } from "./commands/init.ts";
+import { addUsage } from "./commands/usage.ts";
+import { getBannerText } from "./ui.ts";
+
+export type Options = {
+  binDir: string;
+};
+
+export async function createProgram(options: 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)),
+  );
+}

package/src/program/ui.ts

@@ -0,0 +1,29 @@
+import { colorize, palette, text } from "@vlandoss/clibuddy";
+
+const vlandColor = colorize("#a78bfa");
+const usageColor = colorize("#24C55E");
+const gigetColor = colorize("#F472B6");
+
+export const TOOL_LABELS = {
+  USAGE: usageColor("usage"),
+  GIGET: gigetColor("giget"),
+};
+
+// npx figlet -f "ANSI Shadow" "vland"
+export function getBannerText(version: string) {
+  const uiLogo = vlandColor(
+    `
+██╗   ██╗██╗      █████╗ ███╗   ██╗██████╗
+██║   ██║██║     ██╔══██╗████╗  ██║██╔══██╗
+██║   ██║██║     ███████║██╔██╗ ██║██║  ██║
+╚██╗ ██╔╝██║     ██╔══██║██║╚██╗██║██║  ██║
+ ╚████╔╝ ███████╗██║  ██║██║ ╚████║██████╔╝
+  ╚═══╝  ╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═════╝ ${text.version(version)}
+`.trim(),
+  );
+
+  return `
+${uiLogo}
+
+🦉 ${palette.italic(palette.muted("The CLI to init a new project in"))} ${text.vland}\n`.trimStart();
+}

package/src/run.ts

@@ -0,0 +1,11 @@
+import path from "node:path";
+import { dirnameOf, run } from "@vlandoss/clibuddy";
+import { createProgram } from "./program/index.ts";
+import { logger } from "./services/logger.ts";
+
+const BIN_DIR = path.dirname(dirnameOf(import.meta));
+
+await run(async () => {
+  const program = await createProgram({ binDir: BIN_DIR });
+  await program.parseAsync();
+}, logger);

package/src/services/ctx.ts

@@ -0,0 +1,32 @@
+import fs from "node:fs";
+import { createPkg, createShellService, type Pkg, type ShellService } from "@vlandoss/clibuddy";
+import { logger } from "./logger.ts";
+
+export type Context = {
+  binPkg: Pkg;
+  shell: ShellService;
+};
+
+export async function createContext(binDir: string): Promise<Context> {
+  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({
+    localBaseBinPath: [binDir],
+  });
+
+  debug("shell service options: %O", shell.options);
+
+  return { binPkg, shell };
+}

package/src/services/logger.ts

@@ -0,0 +1,5 @@
+import { createLoggy } from "@vlandoss/loggy";
+
+export const logger = createLoggy({
+  namespace: "vland",
+});

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": ["@vlandoss/config/ts/no-dom/app"]
+}