@vlandoss/starter 0.3.0 → 0.4.0

package/README.md

@@ -16,15 +16,36 @@ It will adds the `vland` to your global workspace
 
 ## Usage
 
-> [!NOTE]
-> The documentation is WIP
-
 Run the help command:
 
 ```sh
 vland help
 ```
 
+## 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/starter`, 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.

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/starter 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,31 @@
+// @generated by @usage-spec/commander from Commander.js metadata
+name vland
+bin vland
+version "0.4.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 🚀" {
+	flag "-d --dest" help="destination path to create folder (default: cwd)" {
+		arg <DEST>
+	}
+	flag --no-git help="skip to create a git repository" negate=--git default=#true
+	flag "-f --force" help="override existing files"
+	arg "[template]" help="the template to use" required=#false {
+		choices basic monorepo
+	}
+}
+cmd add help="add config files to a project 📁" {
+	flag "-d --dest" help="destination path to create folder (default: cwd)" {
+		arg <DEST>
+	}
+	flag "-f --force" help="override existing files"
+	arg "[slug]…" help="the config slugs to pick" required=#false var=#true {
+		choices biome changeset husky mise tsconfig tsup
+	}
+}

package/dist/run.mjs

@@ -4,6 +4,7 @@ import { Argument, Command, Option, createCommand } from "commander";
 import fs from "node:fs";
 import { createLoggy } from "@vlandoss/loggy";
 import nodePlop from "node-plop";
+import { generateToStdout } from "@usage-spec/commander";
 //#region src/services/config.ts
 var ConfigService = class {
 	#baseDir;
@@ -114,6 +115,38 @@ function createAddCommand(ctx) {
 	}).addHelpText("afterAll", "\nUnder the hood, this command uses Plop.js to generate the project.");
 }
 //#endregion
+//#region src/program/ui.ts
+const vlandColor = colorize("#a78bfa");
+const TOOL_LABELS = { USAGE: colorize("#24C55E")("usage") };
+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/init.ts
 const GENERATOR_ID = "init";
 var InitAction = class {
@@ -172,27 +205,19 @@ function createInitCommand(ctx) {
 	}).addHelpText("afterAll", "\nUnder the hood, this command uses Plop.js to generate the project.");
 }
 //#endregion
-//#region src/program/ui.ts
-const vlandColor = colorize("#a78bfa");
-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();
+//#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 = getVersion(ctx.binPkg);
-	return new Command("vland").version(version, "-v, --version").addHelpText("before", getBannerText(version)).addCommand(createInitCommand(ctx)).addCommand(createAddCommand(ctx));
+	return addUsage(new Command("vland").version(version, "-v, --version").addHelpText("before", getBannerText(version)).addCommand(createCompletionCommand()).addCommand(createInitCommand(ctx)).addCommand(createAddCommand(ctx)));
 }
 //#endregion
 //#region src/run.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vlandoss/starter",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "The CLI to init a new project in Variable Land",
   "homepage": "https://github.com/variableland/dx/tree/main/packages/starter#readme",
   "bugs": {
@@ -19,10 +19,10 @@
   },
   "module": "src/main.ts",
   "bin": {
-    "vland": "./bin.mjs"
+    "vland": "./bin"
   },
   "files": [
-    "bin.mjs",
+    "bin",
     "dist",
     "src",
     "!src/**/__tests__",
@@ -31,6 +31,7 @@
     "tsconfig.json"
   ],
   "dependencies": {
+    "@usage-spec/commander": "1.1.0",
     "commander": "14.0.3",
     "node-plop": "0.32.3",
     "@vlandoss/clibuddy": "0.4.0",
@@ -46,7 +47,8 @@
     "@vlandoss/tsdown-config": "^0.0.1"
   },
   "scripts": {
-    "build": "tsdown",
+    "build": "tsdown && pnpm build:kdl",
+    "build:kdl": "./bin --usage > dist/cli.usage.kdl",
     "test:types": "rr tsc"
   }
 }

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/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

@@ -2,7 +2,9 @@ import { getVersion } from "@vlandoss/clibuddy";
 import { Command } from "commander";
 import { createContext } from "#src/services/ctx.ts";
 import { createAddCommand } from "./commands/add.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,9 +15,12 @@ export async function createProgram(options: Options) {
   const ctx = await createContext(options.binDir);
   const version = getVersion(ctx.binPkg);
 
-  return new Command("vland")
-    .version(version, "-v, --version")
-    .addHelpText("before", getBannerText(version))
-    .addCommand(createInitCommand(ctx))
-    .addCommand(createAddCommand(ctx));
+  return addUsage(
+    new Command("vland")
+      .version(version, "-v, --version")
+      .addHelpText("before", getBannerText(version))
+      .addCommand(createCompletionCommand())
+      .addCommand(createInitCommand(ctx))
+      .addCommand(createAddCommand(ctx)),
+  );
 }

package/src/program/ui.ts

@@ -1,6 +1,11 @@
 import { colorize, palette, text } from "@vlandoss/clibuddy";
 
 const vlandColor = colorize("#a78bfa");
+const usageColor = colorize("#24C55E");
+
+export const TOOL_LABELS = {
+  USAGE: usageColor("usage"),
+};
 
 // npx figlet -f "ANSI Shadow" "vland"
 export function getBannerText(version: string) {

package/bin.mjs

@@ -1,2 +0,0 @@
-#!/usr/bin/env node
-import "./dist/run.mjs";