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

package/README.md

@@ -1,6 +1,6 @@
 # 🦉 vland
 
-The CLI to init a new project in [Variable Land](https://variable.land) 👊
+The CLI to init a new project in [Variable Land](https://variable.land)
 
 ## Prerequisites
 
@@ -35,11 +35,11 @@ See [`CLI.md`](./CLI.md) for the full reference (auto-generated per release).
 
 | Template   | What you get                                                                              |
 | ---------- | ----------------------------------------------------------------------------------------- |
-| `library`  | A standalone TypeScript library with tsdown, Vitest, biome, Changesets release workflow.  |
+| `library`  | A standalone TypeScript library with Vitest + 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.
+All templates target Node.js, use pnpm, and ship [`@rrlab/cli`](https://github.com/variableland/dx/tree/main/run-run) (`rr`) as the single entry point for lint, format, type-check, and build. The per-tool config files (`biome.json`, `tsconfig.json`, `tsdown.config.ts`) are not bundled — run `rr plugins add biome ts tsdown` (one at a time) in your new project to opt in. See the scaffolded README for the exact post-install setup.
 
 ## Shell completion
 
@@ -76,5 +76,5 @@ 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
+VLAND_TEMPLATES_DIR=/absolute/path/to/dx/vland/templates vland init my-app -t library
 ```

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-87d22db.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 --visibility help="package visibility (library only)" {
+		arg <VISIBILITY> {
+			choices private public
+		}
+	}
+	flag "-d --dir" help="target directory (default: ./<name>)" {
+		arg <DIR>
+	}
+	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,474 @@
+import path, { extname, isAbsolute, join, resolve } from "node:path";
+import { colorize, createPkg, createShellService, dirnameOf, hasTTY, palette, run, text } from "@vlandoss/clibuddy";
+import { generateToStdout } from "@usage-spec/commander";
+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 { installDependencies } from "nypm";
+import { downloadTemplate } from "giget";
+//#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/template.ts
+const TEMPLATES = [
+	"library",
+	"backend",
+	"monorepo"
+];
+const VISIBILITIES = ["private", "public"];
+const TEMPLATE_META = {
+	library: {
+		placeholder: "my-lib",
+		runScript: "test"
+	},
+	backend: {
+		placeholder: "my-api",
+		runScript: "dev"
+	},
+	monorepo: {
+		placeholder: "my-mono",
+		runScript: "dev"
+	}
+};
+/**
+* The npm scope a `library` template's package is published under, indexed by
+* the user-selected visibility. Public libraries live under the open-source
+* `@vlandoss` scope; private libraries under `@variableland`.
+*/
+const LIBRARY_SCOPES = {
+	private: "@variableland",
+	public: "@vlandoss"
+};
+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 `vland/templates/`).
+* 2. Otherwise → download via giget from `github:variableland/dx/vland/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}/vland/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/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 };
+}
+/**
+* Writes the root `package.json`'s `name` and `private` fields based on the
+* chosen template and visibility. Uses `pkg-types` so field ordering and
+* JSON formatting survive.
+*
+* Naming rules:
+* - `library` private → `@variableland/<projectName>`, `private: true`
+* - `library` public  → `@vlandoss/<projectName>`
+* - `backend`         → `<projectName>`, `private: true`
+* - `monorepo`        → `<projectName>`, `private: true` (root never publishes)
+*/
+async function applyRootPackage(rootDir, options) {
+	const debug = logger.subdebug("apply-root-package");
+	const pkg = await createPkg(fs.realpathSync(rootDir));
+	if (!pkg) throw new Error("Could not find package.json");
+	const { template, projectName, visibility } = options;
+	try {
+		if (template === "library") {
+			const scope = LIBRARY_SCOPES[visibility ?? "public"];
+			pkg.packageJson.name = `${scope}/${projectName}`;
+			if (visibility === "private") pkg.packageJson.private = true;
+		} else {
+			pkg.packageJson.name = projectName;
+			pkg.packageJson.private = true;
+		}
+		await pkg.write(pkg.packageJson);
+	} catch (error) {
+		debug("skipped %s", error);
+	}
+}
+//#endregion
+//#region src/actions/init.ts
+const PACKAGE_MANAGER = "pnpm";
+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);
+	let visibility = options.visibility;
+	if (template === "library" && !visibility) if (!hasTTY) visibility = "public";
+	else {
+		const choice = await select({
+			message: "Library visibility",
+			options: [{
+				value: "public",
+				label: "public (@vlandoss/<name>)"
+			}, {
+				value: "private",
+				label: "private (@variableland/<name>, private: true)"
+			}],
+			initialValue: "public"
+		});
+		if (isCancel(choice)) abort("Cancelled.");
+		visibility = choice;
+	}
+	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 applyRootPackage(dir, {
+		template,
+		projectName: name,
+		visibility
+	});
+	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 installSpin = spinner();
+		installSpin.start(`Installing dependencies with ${palette.highlight(PACKAGE_MANAGER)}`);
+		try {
+			await installDependencies({
+				cwd: dir,
+				packageManager: {
+					name: PACKAGE_MANAGER,
+					command: PACKAGE_MANAGER
+				},
+				silent: true
+			});
+			installSpin.stop(`Installed with ${palette.highlight(PACKAGE_MANAGER)}`);
+		} catch (error) {
+			installSpin.stop("Failed to install dependencies", 1);
+			log.warn(`You can install manually later with \`cd <dir> && ${PACKAGE_MANAGER} 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 runScript = TEMPLATE_META[template].runScript;
+	outro([
+		palette.success("Done!"),
+		"",
+		palette.muted("Next steps:"),
+		`  cd ${name}`,
+		shouldInstall ? `  ${PACKAGE_MANAGER} ${runScript}` : `  ${PACKAGE_MANAGER} install && ${PACKAGE_MANAGER} ${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("--visibility <visibility>", "package visibility (library only)").choices([...VISIBILITIES])).addOption(new Option("-d, --dir <path>", "target directory (default: ./<name>)")).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/index.ts
+async function createProgram(options) {
+	const ctx = await createContext(options.binDir);
+	const version = ctx.binPkg.version;
+	return new Command("vland").version(version, "-v, --version").addOption(new Option("--usage", `print KDL spec for this CLI (${palette.muted(palette.link("https://kdl.dev"))})`)).on("option:usage", function onUsage() {
+		generateToStdout(this);
+		process.exit(0);
+	}).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,21 +1,18 @@
 {
   "name": "@vlandoss/vland",
-  "version": "0.2.1-git-74f39bb.0",
+  "version": "0.2.1-git-87d22db.0",
   "description": "The CLI to init a new project in Variable Land",
-  "homepage": "https://github.com/variableland/dx/tree/main/packages/vland#readme",
+  "homepage": "https://github.com/variableland/dx/tree/main/vland/cli#readme",
   "bugs": {
     "url": "https://github.com/variableland/dx/issues"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/variableland/dx.git",
-    "directory": "packages/vland"
+    "directory": "vland/cli"
   },
   "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-87d22db.0",
+    "@vlandoss/loggy": "0.2.1-git-87d22db.0"
   },
   "publishConfig": {
     "access": "public"
@@ -48,10 +45,8 @@
     "node": ">=20.0.0"
   },
   "devDependencies": {
-    "@vlandoss/tsdown-config": "^0.0.1"
+    "@rrlab/tsdown-config": "^0.0.1-git-87d22db.0"
   },
-  "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"
   }
-}
+}

package/src/actions/init.ts

@@ -2,22 +2,24 @@ import { readdir } from "node:fs/promises";
 import { isAbsolute, resolve } from "node:path";
 import { cancel, confirm, intro, isCancel, log, outro, select, spinner, text } from "@clack/prompts";
 import { hasTTY, palette } from "@vlandoss/clibuddy";
-import { detectPackageManager, installDependencies } from "nypm";
+import { 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, TEMPLATE_META, TEMPLATES, type TemplateName } from "./template.ts";
+import { applyRootPackage, replacePlaceholders } from "./placeholders.ts";
+import { fetchTemplate, TEMPLATE_META, TEMPLATES, type TemplateName, type Visibility } from "./template.ts";
 
 export type InitOptions = {
   name?: string;
   template?: TemplateName;
+  visibility?: Visibility;
   dir?: string;
-  pm?: "npm" | "pnpm" | "yarn" | "bun";
   install?: boolean;
   git?: boolean;
   force: boolean;
 };
 
+const PACKAGE_MANAGER = "pnpm" as const;
+
 const NPM_NAME_RE = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/;
 
 function validateProjectName(name: string): string | undefined {
@@ -71,7 +73,6 @@ export async function runInit(ctx: Context, options: InitOptions) {
 
   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>.");
@@ -86,7 +87,6 @@ export async function runInit(ctx: Context, options: InitOptions) {
     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.");
@@ -101,7 +101,29 @@ export async function runInit(ctx: Context, options: InitOptions) {
   const nameError = validateProjectName(name);
   if (nameError) abort(nameError);
 
-  // 3. Resolve target dir
+  // Visibility only meaningfully changes the library template (scope +
+  // private flag). For backend/monorepo we ignore it — those are always
+  // private at root. Prompt for it interactively when building a library
+  // and the user didn't pass --visibility; non-interactive default is
+  // "public" (the OSS-style scope, @vlandoss).
+  let visibility = options.visibility;
+  if (template === "library" && !visibility) {
+    if (!hasTTY) {
+      visibility = "public";
+    } else {
+      const choice = await select<Visibility>({
+        message: "Library visibility",
+        options: [
+          { value: "public", label: "public (@vlandoss/<name>)" },
+          { value: "private", label: "private (@variableland/<name>, private: true)" },
+        ],
+        initialValue: "public",
+      });
+      if (isCancel(choice)) abort("Cancelled.");
+      visibility = choice as Visibility;
+    }
+  }
+
   const dir = options.dir
     ? isAbsolute(options.dir)
       ? options.dir
@@ -113,7 +135,6 @@ export async function runInit(ctx: Context, options: InitOptions) {
     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) {
@@ -130,7 +151,6 @@ export async function runInit(ctx: Context, options: InitOptions) {
   }
   debug("author: %s", author || "<empty>");
 
-  // 5. Download template
   const fetchSpin = spinner();
   fetchSpin.start(`Fetching ${palette.highlight(template)} template`);
   try {
@@ -141,7 +161,6 @@ export async function runInit(ctx: Context, options: InitOptions) {
     throw error;
   }
 
-  // 6. Replace placeholders
   const placeholderSpin = spinner();
   placeholderSpin.start("Applying placeholders");
   await replacePlaceholders(dir, {
@@ -149,31 +168,31 @@ export async function runInit(ctx: Context, options: InitOptions) {
     author,
     year: new Date().getFullYear().toString(),
   });
-  await updateRootPackageName(dir, name);
+  await applyRootPackage(dir, { template, projectName: name, visibility });
   placeholderSpin.stop("Placeholders applied");
 
-  // 7. Resolve install / git decisions (prompt with default-yes when not set on CLI)
   const shouldInstall = await resolveYesNo(options.install, "Install dependencies?");
   const shouldGit = await resolveYesNo(options.git, "Initialise a git repository?");
 
-  // 8. Install deps
   if (shouldInstall) {
-    const detected = options.pm ?? (await detectPackageManager(dir, { ignorePackageJSON: false }))?.name ?? "pnpm";
     const installSpin = spinner();
-    installSpin.start(`Installing dependencies with ${palette.highlight(detected)}`);
+    installSpin.start(`Installing dependencies with ${palette.highlight(PACKAGE_MANAGER)}`);
     try {
-      await installDependencies({ cwd: dir, packageManager: { name: detected, command: detected }, silent: true });
-      installSpin.stop(`Installed with ${palette.highlight(detected)}`);
+      await installDependencies({
+        cwd: dir,
+        packageManager: { name: PACKAGE_MANAGER, command: PACKAGE_MANAGER },
+        silent: true,
+      });
+      installSpin.stop(`Installed with ${palette.highlight(PACKAGE_MANAGER)}`);
     } catch (error) {
       installSpin.stop("Failed to install dependencies", 1);
-      log.warn("You can install manually later with `cd <dir> && <pm> install`.");
+      log.warn(`You can install manually later with \`cd <dir> && ${PACKAGE_MANAGER} install\`.`);
       debug("install error: %O", error);
     }
   } else {
     log.info(`Skipping ${palette.highlight("install")}.`);
   }
 
-  // 9. Git init
   if (shouldGit) {
     const gitSpin = spinner();
     gitSpin.start("Initialising git repository");
@@ -198,8 +217,6 @@ export async function runInit(ctx: Context, options: InitOptions) {
     log.info(`Skipping ${palette.highlight("git init")}.`);
   }
 
-  // 10. Outro with next steps
-  const detectedPm = options.pm ?? (await detectPackageManager(dir, { ignorePackageJSON: false }))?.name ?? "pnpm";
   const runScript = TEMPLATE_META[template].runScript;
   outro(
     [
@@ -207,7 +224,7 @@ export async function runInit(ctx: Context, options: InitOptions) {
       "",
       palette.muted("Next steps:"),
       `  cd ${name}`,
-      shouldInstall ? `  ${detectedPm} ${runScript}` : `  ${detectedPm} install && ${detectedPm} ${runScript}`,
+      shouldInstall ? `  ${PACKAGE_MANAGER} ${runScript}` : `  ${PACKAGE_MANAGER} install && ${PACKAGE_MANAGER} ${runScript}`,
     ].join("\n"),
   );
 }

package/src/actions/placeholders.ts

@@ -3,6 +3,7 @@ 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";
+import { LIBRARY_SCOPES, type TemplateName, type Visibility } from "./template.ts";
 
 export type Placeholders = {
   projectName: string;
@@ -111,27 +112,44 @@ export async function replacePlaceholders(rootDir: string, values: Placeholders)
   return { touched };
 }
 
+export type ApplyRootPackageOptions = {
+  template: TemplateName;
+  projectName: string;
+  visibility?: Visibility;
+};
+
 /**
- * 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`.
+ * Writes the root `package.json`'s `name` and `private` fields based on the
+ * chosen template and visibility. Uses `pkg-types` so field ordering and
+ * JSON formatting survive.
+ *
+ * Naming rules:
+ * - `library` private → `@variableland/<projectName>`, `private: true`
+ * - `library` public  → `@vlandoss/<projectName>`
+ * - `backend`         → `<projectName>`, `private: true`
+ * - `monorepo`        → `<projectName>`, `private: true` (root never publishes)
  */
-export async function updateRootPackageName(rootDir: string, projectName: string) {
-  const debug = logger.subdebug("update-root-package-name");
+export async function applyRootPackage(rootDir: string, options: ApplyRootPackageOptions) {
+  const debug = logger.subdebug("apply-root-package");
 
   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");
 
-  if (!pkg) {
-    throw new Error("Could not find package.json");
-  }
+  const { template, projectName, visibility } = options;
 
   try {
-    pkg.packageJson.name = projectName;
+    if (template === "library") {
+      const scope = LIBRARY_SCOPES[visibility ?? "public"];
+      pkg.packageJson.name = `${scope}/${projectName}`;
+      if (visibility === "private") {
+        pkg.packageJson.private = true;
+      }
+    } else {
+      // backend + monorepo: bare project name, private root.
+      pkg.packageJson.name = projectName;
+      pkg.packageJson.private = true;
+    }
     await pkg.write(pkg.packageJson);
   } catch (error) {
     debug("skipped %s", error);

package/src/actions/template.ts

@@ -6,12 +6,25 @@ import { logger } from "#src/services/logger.ts";
 export const TEMPLATES = ["library", "backend", "monorepo"] as const;
 export type TemplateName = (typeof TEMPLATES)[number];
 
+export const VISIBILITIES = ["private", "public"] as const;
+export type Visibility = (typeof VISIBILITIES)[number];
+
 export const TEMPLATE_META: Record<TemplateName, { placeholder: string; runScript: string }> = {
   library: { placeholder: "my-lib", runScript: "test" },
   backend: { placeholder: "my-api", runScript: "dev" },
   monorepo: { placeholder: "my-mono", runScript: "dev" },
 };
 
+/**
+ * The npm scope a `library` template's package is published under, indexed by
+ * the user-selected visibility. Public libraries live under the open-source
+ * `@vlandoss` scope; private libraries under `@variableland`.
+ */
+export const LIBRARY_SCOPES: Record<Visibility, string> = {
+  private: "@variableland",
+  public: "@vlandoss",
+};
+
 const GITHUB_SOURCE = "github:variableland/dx";
 const GITHUB_REF = "main";
 
@@ -24,8 +37,8 @@ type ResolveOptions = {
 /**
  * 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>`.
+ *    against the in-repo `vland/templates/`).
+ * 2. Otherwise → download via giget from `github:variableland/dx/vland/templates/<name>`.
  */
 export async function fetchTemplate(options: ResolveOptions): Promise<{ source: string }> {
   const debug = logger.subdebug("fetch-template");
@@ -43,7 +56,7 @@ export async function fetchTemplate(options: ResolveOptions): Promise<{ source:
     return { source: sourceDir };
   }
 
-  const source = `${GITHUB_SOURCE}/templates/${options.template}#${GITHUB_REF}`;
+  const source = `${GITHUB_SOURCE}/vland/templates/${options.template}#${GITHUB_REF}`;
   debug("remote source: %s", source);
   const result = await downloadTemplate(source, {
     dir: options.dir,

package/src/program/commands/completion.ts

@@ -9,7 +9,7 @@ const SHELLS = ["bash", "zsh", "fish"] as const;
 // dispatcher, which intercepts `vland completion <shell>` before reaching Node.
 export function createCompletionCommand() {
   return createCommand("completion")
-    .summary(`print shell completion script 🐚 (${TOOL_LABELS.USAGE})`)
+    .summary(`print shell completion script (${TOOL_LABELS.USAGE})`)
     .description(
       `Prints a shell completion script for vland. Add to your shell rc file:
 

package/src/program/commands/init.ts

@@ -1,13 +1,13 @@
 import { Argument, createCommand, Option } from "commander";
 import { runInit } from "#src/actions/init.ts";
-import { TEMPLATES, type TemplateName } from "#src/actions/template.ts";
+import { TEMPLATES, type TemplateName, VISIBILITIES, type Visibility } from "#src/actions/template.ts";
 import type { Context } from "#src/services/ctx.ts";
 import { getBannerText, TOOL_LABELS } from "../ui.ts";
 
 type InitOptions = {
   dir?: string;
   template?: TemplateName;
-  pm?: "npm" | "pnpm" | "yarn" | "bun";
+  visibility?: Visibility;
   install: boolean;
   git: boolean;
   force: boolean;
@@ -15,12 +15,12 @@ type InitOptions = {
 
 export function createInitCommand(ctx: Context) {
   return createCommand("init")
-    .summary(`init a new project 🚀 (${TOOL_LABELS.GIGET})`)
+    .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("--visibility <visibility>", "package visibility (library only)").choices([...VISIBILITIES]))
     .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)"))

package/src/program/index.ts

@@ -1,8 +1,9 @@
-import { Command } from "commander";
+import { generateToStdout } from "@usage-spec/commander";
+import { palette } from "@vlandoss/clibuddy";
+import { Command, Option } 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 = {
@@ -13,11 +14,14 @@ 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)),
-  );
+  return new Command("vland")
+    .version(version, "-v, --version")
+    .addOption(new Option("--usage", `print KDL spec for this CLI (${palette.muted(palette.link("https://kdl.dev"))})`))
+    .on("option:usage", function onUsage(this: Command) {
+      generateToStdout(this);
+      process.exit(0);
+    })
+    .addHelpText("before", getBannerText(version))
+    .addCommand(createCompletionCommand())
+    .addCommand(createInitCommand(ctx));
 }

package/tsconfig.json

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

package/src/program/commands/usage.ts

@@ -1,9 +0,0 @@
-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);
-  });
-}