kz3-cli 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# kz3-cli
+
+## Usage
+
+```txt
+
+USAGE kz3 [OPTIONS] preview
+
+GLOBAL OPTIONS
+                         --cwd    Current working directory to resolve config and output from
+  -c, --configFile="kz.config"    Path to kz config file (e.g. kz.config, kz3.config.ts)
+                  --catalogUrl    URL to the catalog JSON file
+                       --debug    Enable debug logging
+                        --repo    Catalog ID
+
+COMMANDS
+  preview
+  preview dlp
+```
+
+## Commands
+
+### `preview`
+
+The `preview` command has sub-commands to download the package for preview.
+
+**Usage:**
+
+```bash
+kz3-cli preview dlp [OPTIONS] <APPID>
+```
+
+### Example: Basic
+
+```bash
+kz3-cli preview dlp --repo repo-id app-id
+```
+
+The example command assumes that we have a `kz.config.ts` file in the current working directory with the following content:
+
+```ts
+import { defineConfig } from "kz3-cli";
+export default defineConfig({
+  registries: {
+    "repo-id": "http://localhost:3000/catalog.json",
+  },
+});
+```
+
+### Example: Multiple Registries
+
+```bash
+# `app-id` will be downloaded from the `github-1`
+kz3-cli preview dlp --repo github-1 app-id
+
+# `app-id` will be downloaded from the `repo-id`
+kz3-cli preview dlp --repo repo-id app-id
+```
+
+**kz.config.ts:**
+
+```ts
+import { defineConfig } from "kz3-cli";
+export default defineConfig({
+  defaultRepo: "repo-id",
+  registries: {
+    "repo-id": "http://localhost:3000/catalog.json",
+    "github-1": "https://raw.githubusercontent.com/username/repo/branch/catalog.json",
+  },
+});
+```
+
+## Catalog File
+
+The catalog file is a JSON file that contains the metadata of the packages. The structure of the catalog file is as follows:
+
+```json
+[
+  {
+    "appName": "app-id",
+    "version": "1.0.0",
+    "url": "http://localhost:3000/app-id-1.0.0.tar.gz",
+    "provider": "http"
+  },
+  {
+    "appName": "app-id",
+    "version": "1.0.0",
+    "url": "https://gitlab.com/....../app-id-1.0.0.tar.gz",
+    "provider": "gitlab"
+  }
+]
+```
+
+## Auth and Providers
+
+Only supported is HTTP provider and Gitlab provider.
+
+For Gitlab, the environment variable `KZ_AUTH` must be present for the cli to download the package. The value of `KZ_AUTH` should be a Gitlab Deploy Token that can read packages and files in the repository.

package/dist/globalArgs-DdR7vgA6.mjs

@@ -0,0 +1,34 @@
+//#region src/globalArgs.ts
+const dryRunArg = { dryRun: {
+	type: "boolean",
+	description: "Print the download URL without downloading"
+} };
+const globalArgs = {
+	cwd: {
+		type: "string",
+		description: "Current working directory to resolve config and output from"
+	},
+	configFile: {
+		type: "string",
+		alias: ["c"],
+		description: "Path to kz config file (e.g. kz.config, kz3.config.ts)",
+		default: "kz.config",
+		required: false
+	},
+	catalogUrl: {
+		type: "string",
+		description: "URL to the catalog JSON file",
+		required: false
+	},
+	debug: {
+		type: "boolean",
+		description: "Enable debug logging"
+	},
+	repo: {
+		type: "string",
+		description: "Catalog ID",
+		required: false
+	}
+};
+//#endregion
+export { globalArgs as n, dryRunArg as t };

package/dist/index.d.mts

@@ -0,0 +1,14 @@
+import { C12InputConfig, LoadConfigOptions } from "c12";
+
+//#region src/util/load-kz-config.d.ts
+interface Kz3Config {
+  defaultRepo?: string;
+  registries: Record<string, string>;
+}
+interface Kz3LoadConfigOptions extends Pick<LoadConfigOptions, "configFile" | "cwd"> {}
+type Kz3DefineConfigInput = (Kz3Config & {
+  extends?: never;
+}) & C12InputConfig<Kz3Config>;
+declare const defineConfig: (input: Kz3DefineConfigInput) => Kz3DefineConfigInput;
+//#endregion
+export { type Kz3Config, type Kz3DefineConfigInput, type Kz3LoadConfigOptions, defineConfig };

package/dist/index.mjs

@@ -0,0 +1,2 @@
+import { t as defineConfig } from "./load-kz-config-CMLz3_Tq.mjs";
+export { defineConfig };

package/dist/kz3-cli.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/kz3-cli.mjs

@@ -0,0 +1,19 @@
+import { n as globalArgs } from "./globalArgs-DdR7vgA6.mjs";
+import { defineCommand, runMain } from "citty";
+//#region bin/index.ts
+const main = defineCommand({
+	meta: {
+		name: "kz3",
+		description: "KZ3 CLI"
+	},
+	subCommands: { preview: () => import("./main-DLy6TSIK.mjs").then((m) => m.default) },
+	args: { ...globalArgs }
+});
+try {
+	await runMain(main);
+} catch (error) {
+	console.error("An error occurred:", error instanceof Error ? error.message : error);
+	process.exit(1);
+}
+//#endregion
+export {};

package/dist/load-kz-config-CMLz3_Tq.mjs

@@ -0,0 +1,24 @@
+import { loadConfig } from "c12";
+//#region src/util/load-kz-config.ts
+async function loadKz3Config(options) {
+	const { config } = await loadConfig({
+		name: "kz",
+		dotenv: true,
+		...options
+	});
+	function getDefaultRepo() {
+		if (config.registries && Object.keys(config.registries).length === 1) return Object.values(config.registries)[0];
+		if (config.defaultRepo) if (config.registries && config.registries[config.defaultRepo]) return config.registries[config.defaultRepo];
+		else {
+			console.warn(`Warning: defaultRepo "${config.defaultRepo}" is not found in registries. Please check your config.`);
+			return null;
+		}
+	}
+	return {
+		...config,
+		getDefaultRepo
+	};
+}
+const defineConfig = (input) => input;
+//#endregion
+export { loadKz3Config as n, defineConfig as t };

package/dist/main-DLy6TSIK.mjs

@@ -0,0 +1,257 @@
+import { n as loadKz3Config } from "./load-kz-config-CMLz3_Tq.mjs";
+import { n as globalArgs, t as dryRunArg } from "./globalArgs-DdR7vgA6.mjs";
+import { defineCommand } from "citty";
+import path, { relative } from "node:path";
+import fs, { mkdir } from "node:fs/promises";
+import fs$1, { existsSync } from "node:fs";
+import { pipeline } from "node:stream";
+import { promisify } from "node:util";
+import { extract } from "tar";
+import "valid-filename";
+import ejs from "ejs";
+import { fileURLToPath } from "node:url";
+//#region src/preview-module/core/providers.ts
+/**
+* Generic HTTP, with or without Basic Auth.
+*
+*/
+const http = (url, options) => {
+	const requestHeaders = {};
+	const originalUrl = url;
+	let transformedUrl = url;
+	if (options.auth) requestHeaders["Authorization"] = `Basic ${options.auth}`;
+	if (options.token) transformedUrl = url.replace(":token", options.token);
+	return {
+		headers: requestHeaders,
+		originalUrl,
+		url: transformedUrl
+	};
+};
+const gitlab = (url, options) => {
+	return {
+		url,
+		headers: { authorization: options.auth ? `Bearer ${options.auth}` : void 0 }
+	};
+};
+const providers = {
+	http,
+	gitlab
+};
+//#endregion
+//#region src/util/download.ts
+async function download(url, outFile, options = {}) {
+	const response = await sendDownloadRequest(url, { headers: options.requestHeaders });
+	if (response.status >= 400) throw new Error(`Failed to download from ${url}: HTTP ${response.status} ${response.statusText}`);
+	const outputStream = fs$1.createWriteStream(outFile);
+	await promisify(pipeline)(response.body, outputStream);
+}
+async function sendDownloadRequest(url, options) {
+	const result = await fetch(url, options).catch((error) => {
+		throw new Error(`Failed to download from ${url}: ${error.message}`, { cause: error });
+	});
+	if (result.status >= 400) throw new Error(`Failed to download from ${url}: HTTP ${result.status} ${result.statusText}`);
+	return result;
+}
+//#endregion
+//#region src/util/common.ts
+function toSafeFsName(str) {
+	return str.replace(/[^\da-z-.]/gi, "-");
+}
+/**
+* Fixes a template filename by replacing certain characters to comply with templating.
+*
+* - `_` becomes `.` (for dotfiles and folder names like `_git` -> `.git`)
+* - `__` becomes literal `_` (used for escaping)
+* - `.tmpl` extension is removed (used for template files that should not be rendered as-is for certain file extensions)
+*
+* @param filename filename or path-like
+*/
+function fixTemplateFilename(filename) {
+	const tmplFilesMap = {
+		".ts.tmpl": ".ts",
+		".js.tmpl": ".js"
+	};
+	const dots = (str) => {
+		return str.split(path.sep).map((part) => {
+			if (part.startsWith("__")) return part.replace(/^__/, "_");
+			else if (part.startsWith("_")) return part.replace(/^_/, ".");
+			return part;
+		}).join(path.sep);
+	};
+	const ext = Object.keys(tmplFilesMap).find((ext) => filename.endsWith(ext));
+	if (ext) return dots(filename.replace(ext, tmplFilesMap[ext]));
+	return dots(filename);
+}
+//#endregion
+//#region src/preview-module/core/download-dist.ts
+async function downloadDistPackage(options) {
+	const { dryRun } = options;
+	const providerName = options.provider;
+	if (!providerName) throw new Error("Provider is required to download dist package");
+	const getProvider = providers[providerName];
+	if (!getProvider) throw new Error(`Unknown provider: ${providerName}`);
+	options.auth = process.env.KZ3_AUTH ?? options.auth;
+	const cwd = options.cwd || process.cwd();
+	const provider = await getProvider(options.registry, { auth: options.auth });
+	const appName = toSafeFsName(options.appName);
+	const tempDir = path.resolve(cwd, ".temp", appName);
+	const tarPath = path.resolve(tempDir, appName + ".tar.gz");
+	if (dryRun) console.log(`[Dry Run] mkdir ${path.dirname(tarPath)}`);
+	else await mkdir(path.dirname(tarPath), { recursive: true });
+	const startTime = Date.now();
+	if (dryRun) {
+		console.log(`[Dry Run] Downloading from ${provider.url} to ${tarPath}`);
+		console.log(`[Dry Run] With headers: ${JSON.stringify(provider.headers)}`);
+	} else await download(provider.url, tarPath, { requestHeaders: { ...provider.headers } }).catch((error) => {
+		if (!existsSync(tarPath)) throw error;
+		throw new Error(`Failed to download package`, { cause: error });
+	});
+	const durationMs = Date.now() - startTime;
+	console.debug(`Downloaded dist package in ${durationMs}ms`);
+	if (!existsSync(tarPath) && !dryRun) throw new Error(`Failed to download package: file not found at ${tarPath}`);
+	const extractDir = path.resolve(cwd, "apps", appName, "dist");
+	if (dryRun) console.log(`[Dry Run] Extracting ${relative(cwd, tarPath)} to ${relative(cwd, extractDir)}`);
+	else {
+		try {
+			await mkdir(extractDir, { recursive: true });
+			await extract({
+				file: tarPath,
+				cwd: extractDir,
+				strip: 1
+			});
+		} catch (error) {
+			throw new Error(`Failed to extract package`, { cause: error });
+		}
+		console.log(`Extracted package to ${extractDir}`);
+	}
+	return {
+		outDir: extractDir,
+		tempPackageFile: tarPath,
+		tempPackageDir: tempDir,
+		url: provider.url
+	};
+}
+//#endregion
+//#region src/preview-module/core/catalog.ts
+/**
+* Loads the catalog from the given URL.
+* The catalog is expected to be a JSON
+*/
+async function loadCatalogData(options) {
+	if (!options.url) throw new Error("Catalog URL is required to load catalog data");
+	const response = await fetch(options.url, {
+		method: "GET",
+		headers: { Accept: "application/json" }
+	});
+	if (response.status >= 400) throw new Error(`Failed to load catalog from ${options.url}: HTTP ${response.status} ${response.statusText}`);
+	const data = await response.json().catch((error) => {
+		throw new Error(`Failed to parse catalog JSON from ${options.url}: ${error.message}`, { cause: error });
+	});
+	if (!Array.isArray(data)) throw new Error(`Invalid catalog format from ${options.url}: expected an array of entries`);
+	return data;
+}
+async function getCatalogEntryByAppName(catalog, appName) {
+	const entry = catalog.find((entry) => entry.appName === appName);
+	if (!entry) throw new Error(`App "${appName}" was not found in the catalog`);
+	if (!entry.url) throw new Error(`Catalog entry for "${appName}" has no download URL`);
+	if (!providers[entry.provider]) throw new Error(`Unknown provider "${entry.provider}" for app "${appName}"`);
+	return entry;
+}
+//#endregion
+//#region src/preview-module/core/create-app.ts
+/**
+* Creates the files from a template.
+*/
+async function createApp(options) {
+	const __dirname = path.dirname(fileURLToPath(import.meta.url));
+	const templatePath = path.resolve(__dirname, "../template");
+	const renderTemplatePath = path.resolve(templatePath, "render");
+	const staticTemplatePath = path.resolve(templatePath, "static");
+	const appDir = path.resolve(options.cwd, "apps", options.appName);
+	if (!existsSync(templatePath)) {
+		console.error(`Template path does not exist: ${templatePath}`);
+		throw new Error(`Unable to retrieve template`);
+	}
+	const vfs = {};
+	const packageJsonTemplate = await fs.readFile(path.join(renderTemplatePath, "package.json"), "utf-8");
+	vfs["package.json"] = await ejs.render(packageJsonTemplate, { appName: options.appName }, { async: true });
+	console.log(`App Dir: ${appDir}`);
+	for (const [file, content] of Object.entries(vfs)) {
+		const filePath = path.join(appDir, file);
+		if (options.dryRun) {
+			console.log(`[Dry Run] Writing file ${path.relative(process.cwd(), filePath)}`);
+			continue;
+		} else {
+			await fs.mkdir(path.dirname(filePath), { recursive: true });
+			await fs.writeFile(filePath, content, "utf-8");
+		}
+	}
+	const staticFiles = await fs.readdir(staticTemplatePath, { recursive: true });
+	for (const file of staticFiles) {
+		const staticFileDest = fixTemplateFilename(file);
+		if (options.dryRun) console.log(`[Dry Run] Copying static file from ${path.join(staticTemplatePath, file)} to ${path.join(appDir, staticFileDest)}`);
+		else await fs.copyFile(path.join(staticTemplatePath, file), path.join(appDir, staticFileDest));
+	}
+	return { outDir: appDir };
+}
+//#endregion
+//#region src/preview-module/main.ts
+const previewModule = defineCommand({
+	meta: { name: "preview" },
+	subCommands: { dlp: defineCommand({
+		meta: {
+			name: "dlp",
+			description: "Download a preview distribution package"
+		},
+		args: {
+			appId: {
+				type: "positional",
+				required: true,
+				description: "Name of the app to download distribution for"
+			},
+			...dryRunArg,
+			...globalArgs
+		},
+		async run({ args }) {
+			args.debug && console.log(args);
+			const cwd = args.cwd || process.cwd();
+			const repo = args.repo;
+			const kzConfig = await loadKz3Config({
+				configFile: args.configFile,
+				cwd
+			});
+			const repoKey = kzConfig?.registries && Object.keys(kzConfig.registries).find((key) => key === repo);
+			const catalogFromConfig = repoKey ? kzConfig.registries[repoKey] : null;
+			if (!(args.catalogUrl || catalogFromConfig || kzConfig.getDefaultRepo())) {
+				console.error(`Error: Catalog URL not specified.`);
+				console.error(`Please provide a catalog URL using the "--catalog-url" argument, or define it in the kz config under registries then use --repo to specify which one to use.`);
+				process.exit(1);
+			}
+			const catalog = await loadCatalogData({ url: args.catalogUrl });
+			if (catalog.length === 0) {
+				console.log("No entries found in the catalog");
+				process.exit(0);
+			}
+			const app = await getCatalogEntryByAppName(catalog, args.appId);
+			const downloadResult = await downloadDistPackage({
+				appName: app.appName,
+				registry: app.url,
+				provider: app.provider,
+				configFile: args.configFile,
+				dryRun: false,
+				cwd,
+				tempDir: ".temp"
+			});
+			console.log(`Package for "${app.appName}:${app.version}" downloaded to ${downloadResult.outDir}`);
+			const createAppResult = await createApp({
+				appName: app.appName,
+				cwd,
+				configFile: args.configFile,
+				dryRun: args.dryRun
+			});
+			console.log(`App config created at ${createAppResult.outDir}`);
+		}
+	}) }
+});
+//#endregion
+export { previewModule as default };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "kz3-cli",
+  "version": "0.1.0",
+  "description": "kz3-cli",
+  "homepage": "https://github.com/hirameki-labs/discussion",
+  "bugs": {
+    "url": "https://github.com/hirameki-labs/discussion/issues"
+  },
+  "license": "MIT",
+  "author": "Mark Terence Tiglao <github@markterence.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hirameki-labs/discussion.git"
+  },
+  "bin": {
+    "kz3": "./dist/kz3-cli.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./kz3-cli": "./dist/kz3-cli.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@dotenvx/dotenvx": "^1.57.2",
+    "axios": "^1.13.6",
+    "c12": "4.0.0-beta.4",
+    "citty": "^0.2.1",
+    "ejs": "^5.0.1",
+    "tar": "^7.5.13",
+    "valid-filename": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/ejs": "^3.1.5",
+    "@types/node": "^24.12.0",
+    "@typescript/native-preview": "7.0.0-dev.20260316.1",
+    "bumpp": "^11.0.1",
+    "typescript": "^5.9.3",
+    "vite-plus": "^0.1.11"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "check": "vp check"
+  }
+}