@booga/vcli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-24
+
+### Added
+
+- `vcli registry list` — enumerate every entry in `@booga/vregistry`; supports
+  `--json` and `--category <name>` filters.
+- `vcli registry inspect <id>` — print a single entry as JSON; exits 1 on miss.
+- `vcli ssg build <config>` — dynamically import a JS/TS/JSON config file and run
+  `@booga/vssg`'s `generate()` pipeline; prints pages/assets/duration on success,
+  exits 1 with the message on failure.
+- Programmatic API: `registerRegistryCmd(cmd)` and `registerSsgCmd(cmd)` attach
+  the same subcommands to any host `commander` `Command`.
+- Dual build via tsup: ESM `dist/index.js` (programmatic) + `dist/cli.js` with
+  `#!/usr/bin/env node` shebang (bound to the `vcli` binary).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bvasilenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @booga/vcli
+
+Terminal CLI for the vsuite. Wraps `@booga/vregistry` and `@booga/vssg` so the
+catalog and the static-site pipeline are reachable from the shell — no host app
+required.
+
+## Install
+
+```bash
+npm install -g @booga/vcli
+# or, ad-hoc:
+npx @booga/vcli --help
+```
+
+## Commands
+
+### `vcli registry list`
+
+Enumerate every entry in `@booga/vregistry` — id, category, name.
+
+```bash
+vcli registry list                # human-readable
+vcli registry list --json         # JSON, pipe-friendly
+vcli registry list -c block       # filter by category
+```
+
+### `vcli registry inspect <id>`
+
+Print one entry as JSON (schema, default props, source, dependencies).
+
+```bash
+vcli registry inspect hero-split
+```
+
+Exits 1 if `<id>` isn't in the catalog.
+
+### `vcli ssg build <config>`
+
+Run `@booga/vssg`'s `generate()` against a config file. The file is JS/TS/JSON
+with the config as its default export; the CLI imports it dynamically and
+prints a one-line summary on success.
+
+```bash
+vcli ssg build vssg.config.js
+# built 42 pages, 17 assets in 312ms
+```
+
+Exits 1 with the error message if the pipeline throws.
+
+## Programmatic API
+
+`vCli` also exports its subcommand registrars, so a host program can compose
+the same commands into a larger `commander` tree:
+
+```ts
+import { Command } from "commander";
+import { registerRegistryCmd, registerSsgCmd } from "@booga/vcli";
+
+const app = new Command().name("mytool");
+registerRegistryCmd(app);
+registerSsgCmd(app);
+app.parseAsync();
+```

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { dirname, resolve, isAbsolute } from 'path';
+import { fileURLToPath, pathToFileURL } from 'url';
+import pc from 'picocolors';
+import { findByCategory, registry, findById } from '@booga/vregistry';
+import { generate } from '@booga/vssg';
+
+function formatLine(e) {
+  return `${pc.cyan(e.id.padEnd(28))} ${pc.dim(e.category.padEnd(10))} ${e.name}`;
+}
+function registerRegistryCmd(program2) {
+  const reg = program2.command("registry").description("inspect the @booga/vregistry catalog");
+  reg.command("list").description("list every registered entry (id, category, name)").option("-c, --category <name>", "filter by category").option("--json", "emit JSON instead of human-readable text").action((opts) => {
+    const items = opts.category ? findByCategory(opts.category) : [...registry.entries];
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(items, null, 2) + "\n");
+      return;
+    }
+    if (items.length === 0) {
+      process.stderr.write(
+        pc.yellow(`no entries${opts.category ? ` in category "${opts.category}"` : ""}
+`)
+      );
+      return;
+    }
+    for (const e of items) process.stdout.write(formatLine(e) + "\n");
+    process.stderr.write(pc.dim(`
+${items.length} entries (registry v${registry.version})
+`));
+  });
+  reg.command("inspect <id>").description("print a single registry entry as JSON").action((id) => {
+    const entry = findById(id);
+    if (!entry) {
+      process.stderr.write(pc.red(`not found: ${id}
+`));
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify(entry, null, 2) + "\n");
+  });
+}
+async function loadConfig(path) {
+  const abs = isAbsolute(path) ? path : resolve(process.cwd(), path);
+  const mod = await import(pathToFileURL(abs).href);
+  return mod.default ?? mod;
+}
+function registerSsgCmd(program2) {
+  const ssg = program2.command("ssg").description("run the @booga/vssg static-site pipeline");
+  ssg.command("build <config>").description("build a static site from a config file (JS/TS/JSON, default export)").action(async (configPath) => {
+    try {
+      const config = await loadConfig(configPath);
+      const result = await generate(config);
+      process.stdout.write(
+        pc.green(
+          `built ${result.pages} pages, ${result.assets.length} assets in ${result.durationMs}ms
+`
+        )
+      );
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(pc.red(`ssg build failed: ${msg}
+`));
+      process.exit(1);
+    }
+  });
+}
+
+// src/cli.ts
+function pkgVersion() {
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(resolve(here, "..", "package.json"), "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+var program = new Command();
+program.name("vcli").description("Terminal CLI for the vsuite. Wraps @booga/vregistry and @booga/vssg.").version(pkgVersion());
+registerRegistryCmd(program);
+registerSsgCmd(program);
+program.parseAsync(process.argv).catch((e) => {
+  process.stderr.write(`${e instanceof Error ? e.message : String(e)}
+`);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+
+declare function registerRegistryCmd(program: Command): void;
+
+declare function registerSsgCmd(program: Command): void;
+
+export { registerRegistryCmd, registerSsgCmd };

package/dist/index.js

@@ -0,0 +1,67 @@
+import pc from 'picocolors';
+import { findByCategory, registry, findById } from '@booga/vregistry';
+import { isAbsolute, resolve } from 'path';
+import { pathToFileURL } from 'url';
+import { generate } from '@booga/vssg';
+
+// src/commands/registry.ts
+function formatLine(e) {
+  return `${pc.cyan(e.id.padEnd(28))} ${pc.dim(e.category.padEnd(10))} ${e.name}`;
+}
+function registerRegistryCmd(program) {
+  const reg = program.command("registry").description("inspect the @booga/vregistry catalog");
+  reg.command("list").description("list every registered entry (id, category, name)").option("-c, --category <name>", "filter by category").option("--json", "emit JSON instead of human-readable text").action((opts) => {
+    const items = opts.category ? findByCategory(opts.category) : [...registry.entries];
+    if (opts.json) {
+      process.stdout.write(JSON.stringify(items, null, 2) + "\n");
+      return;
+    }
+    if (items.length === 0) {
+      process.stderr.write(
+        pc.yellow(`no entries${opts.category ? ` in category "${opts.category}"` : ""}
+`)
+      );
+      return;
+    }
+    for (const e of items) process.stdout.write(formatLine(e) + "\n");
+    process.stderr.write(pc.dim(`
+${items.length} entries (registry v${registry.version})
+`));
+  });
+  reg.command("inspect <id>").description("print a single registry entry as JSON").action((id) => {
+    const entry = findById(id);
+    if (!entry) {
+      process.stderr.write(pc.red(`not found: ${id}
+`));
+      process.exit(1);
+    }
+    process.stdout.write(JSON.stringify(entry, null, 2) + "\n");
+  });
+}
+async function loadConfig(path) {
+  const abs = isAbsolute(path) ? path : resolve(process.cwd(), path);
+  const mod = await import(pathToFileURL(abs).href);
+  return mod.default ?? mod;
+}
+function registerSsgCmd(program) {
+  const ssg = program.command("ssg").description("run the @booga/vssg static-site pipeline");
+  ssg.command("build <config>").description("build a static site from a config file (JS/TS/JSON, default export)").action(async (configPath) => {
+    try {
+      const config = await loadConfig(configPath);
+      const result = await generate(config);
+      process.stdout.write(
+        pc.green(
+          `built ${result.pages} pages, ${result.assets.length} assets in ${result.durationMs}ms
+`
+        )
+      );
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      process.stderr.write(pc.red(`ssg build failed: ${msg}
+`));
+      process.exit(1);
+    }
+  });
+}
+
+export { registerRegistryCmd, registerSsgCmd };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@booga/vcli",
+  "version": "0.1.0",
+  "description": "Terminal CLI for the vsuite — wraps @booga/vregistry and @booga/vssg.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "vcli": "./dist/cli.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@booga/vregistry": "^0.1.1",
+    "@booga/vssg": "^0.1.1",
+    "commander": "^12.0.0",
+    "picocolors": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-istanbul": "^2.1.0",
+    "eslint": "^9.0.0",
+    "globals": "^15.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "bvasilenko"
+}