@kaptive/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 state systems gmbh
+
+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,47 @@
+# @kaptive/cli
+
+The `kaptive` CLI: a Vite plugin, typed parameters, and bundle packaging for [Kaptive](https://kaptive.ch) custom widgets.
+
+Most widget authors don't install this directly — `npm create @kaptive/widget` scaffolds a project that already depends on it and wires up its commands as npm scripts. This package is documented here for anyone customizing that setup or building tooling around it.
+
+## Install
+
+```bash
+npm install --save-dev @kaptive/cli
+```
+
+Requires Vite 8 as a peer — a scaffolded widget already has it.
+
+## The Vite plugin
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { kaptiveWidget } from "@kaptive/cli";
+
+export default defineConfig({
+  plugins: [kaptiveWidget()],
+});
+```
+
+It validates `kaptive.manifest.json` before every build, generates `src/kaptive-env.d.ts` so `parameters.yourKey` is typed from the manifest, and injects the right context into the page depending on whether you're running `vite dev` (from `kaptive.dev.json`) or building for production (`kaptive.prod.json`, if you have one).
+
+## Commands
+
+Run these via `npx kaptive widget <command>`, or the npm scripts a scaffolded project already has:
+
+| Command             | What it does                                                                                                                                                 |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `dev`               | Starts the Vite dev server, with parameters from `kaptive.dev.json`.                                                                                         |
+| `build`             | Builds the widget and packages it into `<id>-<version>.zip`.                                                                                                 |
+| `pack`              | Packages an existing `dist/` build without rebuilding it.                                                                                                    |
+| `validate [bundle]` | Validates the project (manifest, and build output if present), or an already-packaged `.zip`, against the same rules the Kaptive manager enforces at upload. |
+| `types`             | Regenerates `src/kaptive-env.d.ts` from the manifest.                                                                                                        |
+
+## Bundle limits
+
+Every workspace starts with a default upload limit; a Kaptive admin can raise it per workspace. `pack`/`build` always enforce the hard ceiling no workspace can exceed, and warn (without failing) when a bundle is over the default, so you know ahead of time whether an upload might need that limit raised.
+
+## Learn more
+
+See the [`@kaptive/create-widget`](https://www.npmjs.com/package/@kaptive/create-widget) README for a full walkthrough of building and shipping a widget.

package/dist/bundle-io.d.ts

@@ -0,0 +1,19 @@
+import { type BundleEntry } from "@kaptive/widget-api/bundle";
+export interface DiskFile extends BundleEntry {
+    absolutePath: string;
+}
+/** Lists every file under `directory`, with bundle-relative `/`-joined paths. */
+export declare function listBundleFiles(directory: string): Promise<DiskFile[]>;
+/**
+ * Checks a listing against the shared bundle rules plus the two things only a
+ * complete bundle can be checked for: the manifest is present and valid, and
+ * the entry HTML it names actually exists.
+ */
+export declare function checkBundleContents(entries: readonly BundleEntry[], manifestSource: string | null): string[];
+export interface ReadBundleResult {
+    entries: BundleEntry[];
+    manifestSource: string | null;
+    compressedBytes: number;
+}
+/** Reads a `.zip` bundle from disk without trusting anything inside it. */
+export declare function readBundleFile(zipPath: string): Promise<ReadBundleResult>;

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { c as loadManifest, f as WidgetCliError, h as writeParametersDts, n as validateProject, r as packBundle, t as validateBundle } from "./validate-Cf0ODuMg.js";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { formatBytes } from "@kaptive/widget-api/bundle";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { build, createServer } from "vite";
+//#region src/cli.ts
+async function readCliVersion() {
+	try {
+		const here = path.dirname(fileURLToPath(import.meta.url));
+		const source = await readFile(path.join(here, "..", "package.json"), "utf8");
+		const parsed = JSON.parse(source);
+		if (typeof parsed === "object" && parsed !== null && "version" in parsed && typeof parsed.version === "string") return parsed.version;
+	} catch {}
+	return "unknown";
+}
+function resolveRoot(opts) {
+	return path.resolve(opts.root ?? process.cwd());
+}
+function resolveOptional(value) {
+	return value ? path.resolve(value) : void 0;
+}
+async function runDev(root) {
+	const server = await createServer({ root });
+	await server.listen();
+	server.printUrls();
+}
+async function runBuild(root, distDir, outDir) {
+	await loadManifest(root);
+	await build({ root });
+	const result = await packBundle({
+		root,
+		distDir,
+		outDir
+	});
+	reportPack(result.zipPath, result);
+}
+function reportPack(zipPath, result) {
+	console.log(`\nBundle written to ${zipPath}\n  ${result.fileCount} files, ${formatBytes(result.uncompressedBytes)} uncompressed, ${formatBytes(result.compressedBytes)} zipped\n\nUpload it in Kaptive under Settings → Widgets.`);
+	for (const warning of result.warnings) console.warn(`\nWarning: ${warning}`);
+}
+async function runValidate(root, distDir, bundlePath) {
+	if (bundlePath) {
+		await validateBundle(path.resolve(bundlePath));
+		console.log(`${bundlePath} is a valid widget bundle.`);
+		return;
+	}
+	const { checkedBuild } = await validateProject(root, distDir);
+	console.log(checkedBuild ? "Manifest and build output are valid." : "Manifest is valid. No build output found, so only the manifest was checked.");
+}
+async function runTypes(root) {
+	const manifest = await loadManifest(root);
+	const { path: file, changed } = await writeParametersDts(root, manifest);
+	console.log(changed ? `Wrote ${file}` : `${file} is already up to date`);
+}
+var ROOT_OPTION = ["--root <dir>", "Widget project directory (default: current directory)"];
+var DIST_OPTION = ["--dist <dir>", "Build output directory (default: <root>/dist)"];
+var OUT_OPTION = ["--out <dir>", "Directory to write the bundle into (default: <root>)"];
+var program = new Command("kaptive").description("The Kaptive CLI").version(await readCliVersion(), "-v, --version", "Show the CLI version");
+program.action(() => program.help({ error: true }));
+var widget = program.command("widget").description("Build and package Kaptive custom widgets");
+widget.action(() => widget.help({ error: true }));
+widget.command("dev").description("Start the Vite dev server with parameters from kaptive.dev.json").option(...ROOT_OPTION).action(async (opts) => {
+	await runDev(resolveRoot(opts));
+});
+widget.command("build").description("Build the widget and package it into an uploadable bundle").option(...ROOT_OPTION).option(...DIST_OPTION).option(...OUT_OPTION).action(async (opts) => {
+	await runBuild(resolveRoot(opts), resolveOptional(opts.dist), resolveOptional(opts.out));
+});
+widget.command("pack").description("Package an existing build into an uploadable bundle").option(...ROOT_OPTION).option(...DIST_OPTION).option(...OUT_OPTION).action(async (opts) => {
+	const root = resolveRoot(opts);
+	const result = await packBundle({
+		root,
+		distDir: resolveOptional(opts.dist),
+		outDir: resolveOptional(opts.out)
+	});
+	reportPack(result.zipPath, result);
+});
+widget.command("validate [bundle]").description("Validate this project, or a packaged .zip bundle").option(...ROOT_OPTION).option(...DIST_OPTION).action(async (bundlePath, opts) => {
+	await runValidate(resolveRoot(opts), resolveOptional(opts.dist), bundlePath);
+});
+widget.command("types").description("Regenerate src/kaptive-env.d.ts from the manifest").option(...ROOT_OPTION).action(async (opts) => {
+	await runTypes(resolveRoot(opts));
+});
+try {
+	await program.parseAsync(process.argv);
+} catch (error) {
+	if (error instanceof WidgetCliError) {
+		console.error(`\n${error.message}`);
+		for (const detail of error.details) console.error(`  • ${detail}`);
+		console.error("");
+	} else console.error(error);
+	process.exitCode = 1;
+}
+//#endregion
+export {};

package/dist/codegen.d.ts

@@ -0,0 +1,18 @@
+import type { WidgetManifest } from "@kaptive/widget-api/manifest";
+/** File the generated parameter types are written to, relative to `src/`. */
+export declare const GENERATED_TYPES_FILENAME = "kaptive-env.d.ts";
+/**
+ * Renders the module augmentation that turns `kaptive.parameters` from an empty
+ * object into the manifest's actual shape. The leading `export {}` is what makes
+ * this file a module, which is what makes `declare module` an augmentation of
+ * `@kaptive/widget-api` rather than a replacement of it.
+ */
+export declare function renderParametersDts(manifest: WidgetManifest): string;
+/**
+ * Writes the generated types, skipping the write when nothing changed — a dev
+ * server watching `src/` would otherwise reload itself in a loop.
+ */
+export declare function writeParametersDts(root: string, manifest: WidgetManifest): Promise<{
+    path: string;
+    changed: boolean;
+}>;

package/dist/dev-env.d.ts

@@ -0,0 +1,70 @@
+import { type ResolvedParameterValues, type WidgetManifest } from "@kaptive/widget-api/manifest";
+/**
+ * `kaptive.dev.json`: stands in for the Kaptive editor and player agent while
+ * running `kaptive-widget dev`.
+ *
+ * `kaptive.prod.json`: the same shape, read once at build time. When present,
+ * its values are baked into the built bundle and used by a widget that finds
+ * no player agent to talk to — i.e. one deployed and opened outside Kaptive.
+ * Absent one, a standalone widget falls back to its manifest defaults instead.
+ *
+ * ```json
+ * {
+ *   "parameters": {
+ *     "city": "Bern",
+ *     "refreshSeconds": 30,
+ *     "showIcon": true,
+ *     "accent": "#f06a22",
+ *     "logo": "/logo.png",
+ *     "poster": { "source": "local", "localFilePath": "assets/poster.png" }
+ *   },
+ *   "player": {
+ *     "deviceName": "Lobby screen",
+ *     "orientation": 90,
+ *     "timezone": "Europe/Zurich",
+ *     "resolution": { "width": 1080, "height": 1920 }
+ *   },
+ *   "block": { "width": 600, "height": 400 }
+ * }
+ * ```
+ *
+ * An `asset` parameter takes either a plain string (shorthand for a URL, e.g.
+ * a file under `public/`) or the same object a real content block would store,
+ * for simulating a local-player file.
+ */
+export declare const DEV_CONFIG_FILENAME = "kaptive.dev.json";
+export declare const PROD_CONFIG_FILENAME = "kaptive.prod.json";
+export interface FileContextPlayer {
+    device_id: string;
+    device_name: string;
+    orientation: number;
+    timezone: string;
+    resolution: {
+        width: number;
+        height: number;
+    };
+}
+/** The context built from a `kaptive.dev.json`/`kaptive.prod.json` file. */
+export interface FileContext {
+    parameters: ResolvedParameterValues;
+    player: FileContextPlayer;
+    block: {
+        id: string;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Builds the context the SDK uses while `kaptive-widget dev` is running, from
+ * `kaptive.dev.json`. Always returns a full context — manifest defaults fill
+ * in anything the file doesn't set, and a missing file is the same as an empty
+ * one, so a widget with no config file at all still runs.
+ */
+export declare function loadDevContext(root: string, manifest: WidgetManifest): Promise<FileContext>;
+/**
+ * Reads `kaptive.prod.json` for baking into a production build. `null` when
+ * the file isn't there — unlike dev, its absence means "inject nothing", not
+ * "inject defaults": whether a standalone deployment gets manifest defaults or
+ * this file's values is exactly the presence of the file.
+ */
+export declare function loadProdContext(root: string, manifest: WidgetManifest): Promise<FileContext | null>;

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * An error the CLI is expected to produce — a bad manifest, a bundle that
+ * breaks the limits. These print as a clean message plus a bullet list, with no
+ * stack trace; anything else that escapes is a real crash and prints in full.
+ */
+export declare class WidgetCliError extends Error {
+    readonly details: readonly string[];
+    constructor(message: string, details?: readonly string[]);
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { kaptiveWidget, type KaptiveWidgetOptions } from "./plugin.js";
+export { packBundle, type PackOptions, type PackResult } from "./pack.js";
+export { validateBundle, validateProject } from "./validate.js";
+export { checkBundleContents, listBundleFiles, readBundleFile, type ReadBundleResult, } from "./bundle-io.js";
+export { loadManifest, manifestPath, parseManifestSource, serializeManifest, WIDGET_MANIFEST_FILENAME, } from "./manifest-io.js";
+export { DEV_CONFIG_FILENAME, PROD_CONFIG_FILENAME, loadDevContext, loadProdContext, type FileContext, } from "./dev-env.js";
+export { GENERATED_TYPES_FILENAME, renderParametersDts, writeParametersDts, } from "./codegen.js";
+export { WidgetCliError } from "./errors.js";

package/dist/index.js

@@ -0,0 +1,204 @@
+import { a as listBundleFiles, c as loadManifest, d as serializeManifest, f as WidgetCliError, h as writeParametersDts, i as checkBundleContents, l as manifestPath, m as renderParametersDts, n as validateProject, o as readBundleFile, p as GENERATED_TYPES_FILENAME, r as packBundle, s as WIDGET_MANIFEST_FILENAME, t as validateBundle, u as parseManifestSource } from "./validate-Cf0ODuMg.js";
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { isWidgetAssetValue, resolveParameterValues } from "@kaptive/widget-api/manifest";
+//#region src/dev-env.ts
+/**
+* `kaptive.dev.json`: stands in for the Kaptive editor and player agent while
+* running `kaptive-widget dev`.
+*
+* `kaptive.prod.json`: the same shape, read once at build time. When present,
+* its values are baked into the built bundle and used by a widget that finds
+* no player agent to talk to — i.e. one deployed and opened outside Kaptive.
+* Absent one, a standalone widget falls back to its manifest defaults instead.
+*
+* ```json
+* {
+*   "parameters": {
+*     "city": "Bern",
+*     "refreshSeconds": 30,
+*     "showIcon": true,
+*     "accent": "#f06a22",
+*     "logo": "/logo.png",
+*     "poster": { "source": "local", "localFilePath": "assets/poster.png" }
+*   },
+*   "player": {
+*     "deviceName": "Lobby screen",
+*     "orientation": 90,
+*     "timezone": "Europe/Zurich",
+*     "resolution": { "width": 1080, "height": 1920 }
+*   },
+*   "block": { "width": 600, "height": 400 }
+* }
+* ```
+*
+* An `asset` parameter takes either a plain string (shorthand for a URL, e.g.
+* a file under `public/`) or the same object a real content block would store,
+* for simulating a local-player file.
+*/
+var DEV_CONFIG_FILENAME = "kaptive.dev.json";
+var PROD_CONFIG_FILENAME = "kaptive.prod.json";
+/** Reads and JSON-parses a config file. `null` if it doesn't exist, or isn't valid JSON. */
+async function readConfigFile(root, filename) {
+	let raw;
+	try {
+		raw = await readFile(path.join(root, filename), "utf8");
+	} catch {
+		return null;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch (error) {
+		console.warn(`[kaptive-widget] ${filename} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+		return null;
+	}
+}
+function coerceValue(parameter, raw) {
+	if (raw === void 0) return void 0;
+	switch (parameter.type) {
+		case "text":
+		case "color": return typeof raw === "string" ? raw : void 0;
+		case "number": return typeof raw === "number" && Number.isFinite(raw) ? raw : void 0;
+		case "boolean": return typeof raw === "boolean" ? raw : void 0;
+		case "asset":
+			if (typeof raw === "string") return {
+				assetId: "dev-asset",
+				assetUrl: raw
+			};
+			return isWidgetAssetValue(raw) ? raw : void 0;
+	}
+}
+function toOrientation(value) {
+	return value === 90 || value === 180 || value === 270 ? value : 0;
+}
+/** Builds a `FileContext`, filling in manifest defaults for anything unset. */
+function buildFileContext(parsed, manifest) {
+	const stored = {};
+	for (const parameter of manifest.parameters) {
+		const value = coerceValue(parameter, parsed?.parameters?.[parameter.key]);
+		if (value !== void 0) stored[parameter.key] = value;
+	}
+	const resolution = parsed?.player?.resolution ?? {
+		width: 1920,
+		height: 1080
+	};
+	return {
+		parameters: resolveParameterValues(manifest, stored),
+		player: {
+			device_id: parsed?.player?.deviceId ?? "dev-device",
+			device_name: parsed?.player?.deviceName ?? "Development",
+			orientation: toOrientation(parsed?.player?.orientation),
+			timezone: parsed?.player?.timezone ?? "Europe/Zurich",
+			resolution
+		},
+		block: {
+			id: parsed?.block?.id ?? "dev-block",
+			width: parsed?.block?.width ?? resolution.width,
+			height: parsed?.block?.height ?? resolution.height
+		}
+	};
+}
+/**
+* Builds the context the SDK uses while `kaptive-widget dev` is running, from
+* `kaptive.dev.json`. Always returns a full context — manifest defaults fill
+* in anything the file doesn't set, and a missing file is the same as an empty
+* one, so a widget with no config file at all still runs.
+*/
+async function loadDevContext(root, manifest) {
+	return buildFileContext(await readConfigFile(root, DEV_CONFIG_FILENAME), manifest);
+}
+/**
+* Reads `kaptive.prod.json` for baking into a production build. `null` when
+* the file isn't there — unlike dev, its absence means "inject nothing", not
+* "inject defaults": whether a standalone deployment gets manifest defaults or
+* this file's values is exactly the presence of the file.
+*/
+async function loadProdContext(root, manifest) {
+	const parsed = await readConfigFile(root, PROD_CONFIG_FILENAME);
+	if (parsed === null) return null;
+	return buildFileContext(parsed, manifest);
+}
+//#endregion
+//#region src/plugin.ts
+/**
+* Serializes a value for embedding in an inline `<script>`. Escaping `<` is
+* what stops a manifest string containing `<\/script>` from closing the tag.
+*/
+function toInlineJson(value) {
+	return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+/**
+* Vite plugin every Kaptive widget uses. It:
+*
+* - validates `kaptive.manifest.json` before anything is built;
+* - generates the typed `KaptiveParameters` augmentation;
+* - injects the manifest into the page so the SDK can reconcile parameter
+*   values against the version the widget was built with;
+* - injects a development context from `kaptive.dev.json` so `vite dev`
+*   behaves like a player without one being present;
+* - on a production build, bakes in `kaptive.prod.json` if present, so a
+*   widget deployed outside Kaptive still has something to run on;
+* - copies the manifest into the build output, where `kaptive-widget pack`
+*   and the Kaptive manager expect to find it.
+*/
+function kaptiveWidget(options = {}) {
+	let projectRoot = options.root ?? process.cwd();
+	let isDev = false;
+	let manifest = null;
+	async function refreshManifest() {
+		manifest = await loadManifest(projectRoot);
+		if (options.generateTypes !== false) await writeParametersDts(projectRoot, manifest);
+		return manifest;
+	}
+	return {
+		name: "kaptive-widget",
+		configResolved(config) {
+			projectRoot = options.root ?? config.root;
+			isDev = config.command === "serve";
+		},
+		async buildStart() {
+			await refreshManifest();
+		},
+		configureServer(server) {
+			const watched = [manifestPath(projectRoot), path.join(projectRoot, DEV_CONFIG_FILENAME)];
+			server.watcher.add(watched);
+			const onChange = (file) => {
+				if (!watched.includes(file)) return;
+				refreshManifest().then(() => {
+					server.hot.send({ type: "full-reload" });
+				}).catch((error) => {
+					server.config.logger.error(`[kaptive-widget] ${error instanceof Error ? error.message : String(error)}`);
+				});
+			};
+			server.watcher.on("change", onChange);
+			server.watcher.on("add", onChange);
+		},
+		transformIndexHtml: {
+			order: "pre",
+			async handler() {
+				const current = manifest ?? await refreshManifest();
+				const injected = { manifest: current };
+				if (isDev) injected.devContext = await loadDevContext(projectRoot, current);
+				else {
+					const prodContext = await loadProdContext(projectRoot, current);
+					if (prodContext) injected.prodContext = prodContext;
+				}
+				return [{
+					tag: "script",
+					injectTo: "head-prepend",
+					children: `window.__KAPTIVE__=${toInlineJson(injected)};`
+				}];
+			}
+		},
+		generateBundle() {
+			if (!manifest) return;
+			this.emitFile({
+				type: "asset",
+				fileName: WIDGET_MANIFEST_FILENAME,
+				source: serializeManifest(manifest)
+			});
+		}
+	};
+}
+//#endregion
+export { DEV_CONFIG_FILENAME, GENERATED_TYPES_FILENAME, PROD_CONFIG_FILENAME, WIDGET_MANIFEST_FILENAME, WidgetCliError, checkBundleContents, kaptiveWidget, listBundleFiles, loadDevContext, loadManifest, loadProdContext, manifestPath, packBundle, parseManifestSource, readBundleFile, renderParametersDts, serializeManifest, validateBundle, validateProject, writeParametersDts };

package/dist/manifest-io.d.ts

@@ -0,0 +1,13 @@
+import { WIDGET_MANIFEST_FILENAME, type WidgetManifest } from "@kaptive/widget-api/manifest";
+export { WIDGET_MANIFEST_FILENAME };
+export declare function manifestPath(root: string): string;
+/** Parses manifest JSON, reporting `origin` in any error message. */
+export declare function parseManifestSource(source: string, origin: string): WidgetManifest;
+/** Reads and validates `kaptive.manifest.json` from a widget project. */
+export declare function loadManifest(root: string): Promise<WidgetManifest>;
+/**
+ * The canonical on-disk form of a manifest. Everything that writes a manifest
+ * — the Vite plugin into `dist/`, the packer into the zip — goes through this,
+ * so the bytes the manager validates are the bytes the schema produced.
+ */
+export declare function serializeManifest(manifest: WidgetManifest): string;

package/dist/pack.d.ts

@@ -0,0 +1,23 @@
+export interface PackOptions {
+    root: string;
+    /** Build output to package. Defaults to `<root>/dist`. */
+    distDir?: string;
+    /** Where to write the zip. Defaults to `<root>`. */
+    outDir?: string;
+}
+export interface PackResult {
+    zipPath: string;
+    fileCount: number;
+    uncompressedBytes: number;
+    compressedBytes: number;
+    /**
+     * Non-fatal notices — currently just the bundle exceeding the *default*
+     * per-workspace upload limit. A Kaptive workspace admin can raise that
+     * limit, so this is a heads-up to print, never a reason to fail the build:
+     * only exceeding {@link WIDGET_BUNDLE_HARD_LIMITS} (which no workspace can
+     * exceed) does that.
+     */
+    warnings: string[];
+}
+/** Packages a built widget into the zip an admin uploads to Kaptive. */
+export declare function packBundle(options: PackOptions): Promise<PackResult>;

package/dist/plugin.d.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from "vite";
+export interface KaptiveWidgetOptions {
+    /**
+     * Directory holding `kaptive.manifest.json`. Defaults to the Vite root, which
+     * is what a scaffolded widget wants.
+     */
+    root?: string;
+    /**
+     * Write `src/kaptive-env.d.ts` on every dev/build run so `kaptive.parameters`
+     * is typed from the manifest. On by default.
+     */
+    generateTypes?: boolean;
+}
+/**
+ * Vite plugin every Kaptive widget uses. It:
+ *
+ * - validates `kaptive.manifest.json` before anything is built;
+ * - generates the typed `KaptiveParameters` augmentation;
+ * - injects the manifest into the page so the SDK can reconcile parameter
+ *   values against the version the widget was built with;
+ * - injects a development context from `kaptive.dev.json` so `vite dev`
+ *   behaves like a player without one being present;
+ * - on a production build, bakes in `kaptive.prod.json` if present, so a
+ *   widget deployed outside Kaptive still has something to run on;
+ * - copies the manifest into the build output, where `kaptive-widget pack`
+ *   and the Kaptive manager expect to find it.
+ */
+export declare function kaptiveWidget(options?: KaptiveWidgetOptions): Plugin;

package/dist/validate-Cf0ODuMg.js

@@ -0,0 +1,287 @@
+import path from "node:path";
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { WIDGET_MANIFEST_FILENAME, WIDGET_MANIFEST_FILENAME as WIDGET_MANIFEST_FILENAME$1, parseWidgetManifest } from "@kaptive/widget-api/manifest";
+import JSZip from "jszip";
+import { DEFAULT_WIDGET_BUNDLE_COMPRESSED_BYTES, WIDGET_BUNDLE_HARD_LIMITS, checkBundleEntries, formatBytes, isIgnoredBundleEntry } from "@kaptive/widget-api/bundle";
+//#region src/codegen.ts
+/** File the generated parameter types are written to, relative to `src/`. */
+var GENERATED_TYPES_FILENAME = "kaptive-env.d.ts";
+var HEADER = `// Generated by kaptive-widget from kaptive.manifest.json.
+// Do not edit — your changes will be overwritten on the next dev or build run.
+`;
+function tsType(parameter) {
+	switch (parameter.type) {
+		case "text":
+		case "color": return "string";
+		case "number": return "number";
+		case "boolean": return "boolean";
+		case "asset": return "string | null";
+	}
+}
+function docComment(parameter, indent) {
+	const lines = [parameter.label];
+	if (parameter.description) lines.push(parameter.description);
+	if (parameter.type === "asset") lines.push(`URL of the chosen ${parameter.accept.join(" or ")}, or null.`);
+	else if (parameter.default !== void 0) lines.push(`@default ${JSON.stringify(parameter.default)}`);
+	if (lines.length === 1) return `${indent}/** ${lines[0]} */\n`;
+	return `${indent}/**\n${lines.map((line) => `${indent} * ${line}`).join("\n")}\n${indent} */\n`;
+}
+/**
+* Renders the module augmentation that turns `kaptive.parameters` from an empty
+* object into the manifest's actual shape. The leading `export {}` is what makes
+* this file a module, which is what makes `declare module` an augmentation of
+* `@kaptive/widget-api` rather than a replacement of it.
+*/
+function renderParametersDts(manifest) {
+	const body = manifest.parameters.map((parameter) => `${docComment(parameter, "    ")}    ${parameter.key}: ${tsType(parameter)};`).join("\n");
+	return `${HEADER}
+export {};
+
+declare module "@kaptive/widget-api" {
+  interface KaptiveParameters {${manifest.parameters.length ? `\n${body}\n  ` : "\n    // This widget declares no parameters.\n  "}}
+}
+`;
+}
+/**
+* Writes the generated types, skipping the write when nothing changed — a dev
+* server watching `src/` would otherwise reload itself in a loop.
+*/
+async function writeParametersDts(root, manifest) {
+	const directory = path.join(root, "src");
+	const file = path.join(directory, GENERATED_TYPES_FILENAME);
+	const next = renderParametersDts(manifest);
+	let current = null;
+	try {
+		current = await readFile(file, "utf8");
+	} catch {}
+	if (current === next) return {
+		path: file,
+		changed: false
+	};
+	await mkdir(directory, { recursive: true });
+	await writeFile(file, next, "utf8");
+	return {
+		path: file,
+		changed: true
+	};
+}
+//#endregion
+//#region src/errors.ts
+/**
+* An error the CLI is expected to produce — a bad manifest, a bundle that
+* breaks the limits. These print as a clean message plus a bullet list, with no
+* stack trace; anything else that escapes is a real crash and prints in full.
+*/
+var WidgetCliError = class extends Error {
+	details;
+	constructor(message, details = []) {
+		super(message);
+		this.name = "WidgetCliError";
+		this.details = details;
+	}
+};
+//#endregion
+//#region src/manifest-io.ts
+function manifestPath(root) {
+	return path.join(root, WIDGET_MANIFEST_FILENAME$1);
+}
+/** Parses manifest JSON, reporting `origin` in any error message. */
+function parseManifestSource(source, origin) {
+	let json;
+	try {
+		json = JSON.parse(source);
+	} catch (error) {
+		throw new WidgetCliError(`${origin} is not valid JSON`, [error instanceof Error ? error.message : String(error)]);
+	}
+	const result = parseWidgetManifest(json);
+	if (!result.ok) throw new WidgetCliError(`${origin} is not a valid widget manifest`, result.errors);
+	return result.manifest;
+}
+/** Reads and validates `kaptive.manifest.json` from a widget project. */
+async function loadManifest(root) {
+	const file = manifestPath(root);
+	let source;
+	try {
+		source = await readFile(file, "utf8");
+	} catch {
+		throw new WidgetCliError(`No ${WIDGET_MANIFEST_FILENAME$1} found in ${root}`, ["Run this command from the root of a widget project, or pass --root."]);
+	}
+	return parseManifestSource(source, WIDGET_MANIFEST_FILENAME$1);
+}
+/**
+* The canonical on-disk form of a manifest. Everything that writes a manifest
+* — the Vite plugin into `dist/`, the packer into the zip — goes through this,
+* so the bytes the manager validates are the bytes the schema produced.
+*/
+function serializeManifest(manifest) {
+	return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+//#endregion
+//#region src/bundle-io.ts
+/** Lists every file under `directory`, with bundle-relative `/`-joined paths. */
+async function listBundleFiles(directory) {
+	const files = [];
+	async function walk(current, prefix) {
+		const entries = await readdir(current, { withFileTypes: true });
+		for (const entry of entries) {
+			if (isIgnoredBundleEntry(entry.name)) continue;
+			const absolutePath = path.join(current, entry.name);
+			const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+			if (entry.isDirectory()) await walk(absolutePath, relative);
+			else if (entry.isFile()) {
+				const stats = await stat(absolutePath);
+				files.push({
+					path: relative,
+					size: stats.size,
+					absolutePath
+				});
+			}
+		}
+	}
+	await walk(directory, "");
+	return files;
+}
+/**
+* Checks a listing against the shared bundle rules plus the two things only a
+* complete bundle can be checked for: the manifest is present and valid, and
+* the entry HTML it names actually exists.
+*/
+function checkBundleContents(entries, manifestSource) {
+	const problems = [...checkBundleEntries(entries)];
+	if (manifestSource === null) {
+		problems.push(`Bundle is missing ${WIDGET_MANIFEST_FILENAME} at its root`);
+		return problems;
+	}
+	try {
+		const manifest = parseManifestSource(manifestSource, WIDGET_MANIFEST_FILENAME);
+		if (!entries.some((entry) => entry.path === manifest.entry)) problems.push(`Manifest entry "${manifest.entry}" is not in the bundle`);
+	} catch (error) {
+		problems.push(error instanceof Error ? error.message : String(error));
+		if (error instanceof Error && "details" in error) problems.push(...error.details);
+	}
+	return problems;
+}
+/**
+* JSZip exposes the sizes recorded in the zip's own headers only on a private
+* field. Reading them lets a bomb be rejected *before* it is decompressed,
+* which is the whole point of the check — so it is worth the reach-in, with a
+* decompressing fallback if the shape ever changes.
+*/
+function declaredSizes(file) {
+	const data = file._data;
+	return {
+		size: typeof data?.uncompressedSize === "number" ? data.uncompressedSize : void 0,
+		compressedSize: typeof data?.compressedSize === "number" ? data.compressedSize : void 0
+	};
+}
+/** Reads a `.zip` bundle from disk without trusting anything inside it. */
+async function readBundleFile(zipPath) {
+	const buffer = await readFile(zipPath);
+	const compressedBytes = buffer.byteLength;
+	const zip = await JSZip.loadAsync(buffer);
+	const entries = [];
+	let manifestSource = null;
+	let total = 0;
+	for (const file of Object.values(zip.files)) {
+		if (file.dir) continue;
+		const declared = declaredSizes(file);
+		let size = declared.size;
+		if (size === void 0) size = (await file.async("uint8array")).length;
+		total += size;
+		if (total > WIDGET_BUNDLE_HARD_LIMITS.maxUncompressedBytes) throw new Error(`Bundle expands to more than ${formatBytes(WIDGET_BUNDLE_HARD_LIMITS.maxUncompressedBytes)}`);
+		entries.push({
+			path: file.name,
+			size,
+			compressedSize: declared.compressedSize
+		});
+		if (file.name === WIDGET_MANIFEST_FILENAME) manifestSource = await file.async("string");
+	}
+	return {
+		entries,
+		manifestSource,
+		compressedBytes
+	};
+}
+//#endregion
+//#region src/pack.ts
+/** Packages a built widget into the zip an admin uploads to Kaptive. */
+async function packBundle(options) {
+	const { root } = options;
+	const distDir = options.distDir ?? path.join(root, "dist");
+	const outDir = options.outDir ?? root;
+	const manifest = await loadManifest(root);
+	let files;
+	try {
+		files = await listBundleFiles(distDir);
+	} catch {
+		throw new WidgetCliError(`No build output found at ${distDir}`, ["Run the build first, or pass --dist to point at the output directory."]);
+	}
+	if (files.length === 0) throw new WidgetCliError(`Build output at ${distDir} is empty`);
+	const manifestSource = serializeManifest(manifest);
+	const manifestBytes = Buffer.byteLength(manifestSource, "utf8");
+	const payload = files.filter((file) => file.path !== WIDGET_MANIFEST_FILENAME);
+	const entries = [...payload, {
+		path: WIDGET_MANIFEST_FILENAME,
+		size: manifestBytes
+	}];
+	const problems = checkBundleContents(entries, manifestSource);
+	if (problems.length > 0) throw new WidgetCliError("This build cannot be packaged", problems);
+	const zip = new JSZip();
+	zip.file(WIDGET_MANIFEST_FILENAME, manifestSource);
+	for (const file of payload) zip.file(file.path, await readFile(file.absolutePath));
+	const archive = await zip.generateAsync({
+		type: "nodebuffer",
+		compression: "DEFLATE",
+		compressionOptions: { level: 9 }
+	});
+	if (archive.byteLength > WIDGET_BUNDLE_HARD_LIMITS.maxCompressedBytes) throw new WidgetCliError(`Bundle is ${formatBytes(archive.byteLength)}, the limit is ${formatBytes(WIDGET_BUNDLE_HARD_LIMITS.maxCompressedBytes)}`);
+	const warnings = [];
+	if (archive.byteLength > DEFAULT_WIDGET_BUNDLE_COMPRESSED_BYTES) warnings.push(`Bundle is ${formatBytes(archive.byteLength)}; the default workspace upload limit is ${formatBytes(DEFAULT_WIDGET_BUNDLE_COMPRESSED_BYTES)}. A Kaptive admin can raise it for your workspace under Settings → Widgets.`);
+	const zipPath = path.join(outDir, `${manifest.id}-${manifest.version}.zip`);
+	await writeFile(zipPath, archive);
+	return {
+		zipPath,
+		fileCount: entries.length,
+		uncompressedBytes: entries.reduce((total, entry) => total + entry.size, 0),
+		compressedBytes: archive.byteLength,
+		warnings
+	};
+}
+//#endregion
+//#region src/validate.ts
+/**
+* Validates a widget project: the manifest always, and the build output too
+* when it is there. Throws {@link WidgetCliError} listing everything wrong.
+*/
+async function validateProject(root, distDir) {
+	const manifest = await loadManifest(root);
+	const outputDir = distDir ?? path.join(root, "dist");
+	let files;
+	try {
+		files = await listBundleFiles(outputDir);
+	} catch {
+		return { checkedBuild: false };
+	}
+	if (files.length === 0) return { checkedBuild: false };
+	const manifestSource = serializeManifest(manifest);
+	const problems = checkBundleContents([...files.filter((file) => file.path !== WIDGET_MANIFEST_FILENAME), {
+		path: WIDGET_MANIFEST_FILENAME,
+		size: Buffer.byteLength(manifestSource, "utf8")
+	}], manifestSource);
+	if (problems.length > 0) throw new WidgetCliError(`Build output at ${outputDir} is not packageable`, problems);
+	return { checkedBuild: true };
+}
+/** Validates an already-packaged `.zip` exactly as the Kaptive manager will. */
+async function validateBundle(zipPath) {
+	let bundle;
+	try {
+		bundle = await readBundleFile(zipPath);
+	} catch (error) {
+		throw new WidgetCliError(`${zipPath} could not be read as a widget bundle`, [error instanceof Error ? error.message : String(error)]);
+	}
+	const problems = checkBundleContents(bundle.entries, bundle.manifestSource);
+	if (bundle.compressedBytes > WIDGET_BUNDLE_HARD_LIMITS.maxCompressedBytes) problems.push(`Bundle is ${formatBytes(bundle.compressedBytes)}, the limit is ${formatBytes(WIDGET_BUNDLE_HARD_LIMITS.maxCompressedBytes)}`);
+	if (problems.length > 0) throw new WidgetCliError(`${zipPath} is not a valid widget bundle`, problems);
+}
+//#endregion
+export { listBundleFiles as a, loadManifest as c, serializeManifest as d, WidgetCliError as f, writeParametersDts as h, checkBundleContents as i, manifestPath as l, renderParametersDts as m, validateProject as n, readBundleFile as o, GENERATED_TYPES_FILENAME as p, packBundle as r, WIDGET_MANIFEST_FILENAME$1 as s, validateBundle as t, parseManifestSource as u };

package/dist/validate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Validates a widget project: the manifest always, and the build output too
+ * when it is there. Throws {@link WidgetCliError} listing everything wrong.
+ */
+export declare function validateProject(root: string, distDir?: string): Promise<{
+    checkedBuild: boolean;
+}>;
+/** Validates an already-packaged `.zip` exactly as the Kaptive manager will. */
+export declare function validateBundle(zipPath: string): Promise<void>;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@kaptive/cli",
+  "version": "0.1.0",
+  "description": "The kaptive CLI: Vite plugin, typed parameters and bundle packaging for Kaptive custom widgets, under `kaptive widget`.",
+  "keywords": [
+    "kaptive",
+    "widget",
+    "cli",
+    "vite-plugin",
+    "digital-signage"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://kaptive.ch",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "bin": {
+    "kaptive": "./dist/cli.js"
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "vite": ">=8"
+  },
+  "dependencies": {
+    "commander": "^14.0.0",
+    "jszip": "^3.10.1",
+    "@kaptive/widget-api": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "eslint": "^10.0.0",
+    "prettier": "^3.8.1",
+    "typescript": "6.0.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.0.0",
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "lint": "eslint . --max-warnings 0 --cache --cache-location node_modules/.cache/eslint/",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}