@flare-desktop/cli 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 flare contributors
+
+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

@@ -1,3 +1,77 @@
-# Temporary Holding Version
+# @flare-desktop/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The command line interface of [flare](https://github.com/flare-desktop/flare), a C++20 desktop toolkit that renders
+an HTML frontend in the system webview.
+
+```bash
+npm install --save-dev @flare-desktop/cli
+npx flare --help
+```
+
+Create an application:
+
+```bash
+npm create flare-desktop@latest hello
+cd hello
+npm install
+npm run dev
+```
+
+| Command | Effect |
+|:--|:--|
+| `flare init [name]` | scaffold a project: `flare.config.json`, `package.json`, CMake, C++ entry point and `frontend/` |
+| `flare dev` | build the debug binary and run it with `FLARE_DEV=1` |
+| `flare build [--debug]` | build the project; release by default |
+| `flare bundle` | build a release binary and native packages under `target/bundle` |
+| `flare icon <source.png>` | write the png, ico and icns icon set |
+| `flare info` | version, platform, toolchain and project information |
+| `flare inspect` | list the resolved configuration layers and the merged configuration |
+| `flare doctor` | check Node, CMake, the compiler, git and the configuration |
+| `flare completions <shell>` | bash, zsh, fish or powershell completions |
+
+Global options: `--project=<path>`, `--config=<path>`, `--environment=<name>`, `--json`, `--verbose`.
+
+## Frontend directory
+
+`flare build` passes `build.frontendDist` to CMake as `FLARE_FRONTEND_DIR`. The scaffolded `CMakeLists.txt` uses
+that variable for `FlareEmbedFrontend` and for the development directory. Change the config key, not the CMake
+file:
+
+```json
+{
+  "build": {
+    "frontendDist": "web"
+  }
+}
+```
+
+## Native packaging
+
+`flare bundle` performs a Release build and writes real packages. `--bundles` overrides `bundle.targets`:
+
+```bash
+npx flare bundle
+npx flare bundle --bundles=nsis
+npx flare bundle --bundles=nsis,msi --out=release
+```
+
+| Target | Platform | Artifact | Required tool |
+|:--|:--|:--|:--|
+| `nsis` | Windows | `.exe` installer | `makensis` (NSIS 3) |
+| `msi` | Windows | `.msi` installer | `candle.exe`, `light.exe` (WiX 3.14) |
+| `deb` | Linux | `.deb` package | `dpkg-deb` |
+| `rpm` | Linux | `.rpm` package | `rpmbuild` |
+| `appimage` | Linux | `.AppImage` | `appimagetool` |
+| `app` | macOS | `.app` bundle | none |
+| `dmg` | macOS | `.dmg` disk image | `hdiutil` |
+
+With an empty `bundle.targets`, the targets of the current platform are used. Each artifact is written to
+`target/bundle/<target>/`. The command fails before compiling when a required tool is missing, and the error names
+the tool and the expected installation.
+
+Packaging uses `bundle.icon` (a square png), `bundle.licenseFile`, `bundle.resources`, `bundle.externalBin`,
+`bundle.publisher`, `bundle.homepage` and `bundle.shortDescription` when they are present. Resources and external
+binaries are staged next to the application binary.
+
+The configuration is validated against
+[`schemas/flare.config.schema.json`](https://raw.githubusercontent.com/flare-desktop/flare/main/schemas/flare.config.schema.json).

package/bin/flare.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { run } from "../src/index.js";
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@flare-desktop/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Command line interface for the flare desktop toolkit",
+  "type": "module",
+  "bin": {
+    "flare": "bin/flare.js"
+  },
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./schema": "./src/schema.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "flare",
+    "desktop",
+    "webview",
+    "cpp",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flare-desktop/flare-cli.git"
+  },
+  "homepage": "https://flare-desktop.github.io/",
+  "bugs": {
+    "url": "https://github.com/flare-desktop/flare/issues"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.js\""
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,93 @@
+import path from "node:path";
+
+import { buildCommand } from "./commands/build.js";
+import { bundleCommand } from "./commands/bundle.js";
+import { completionsCommand } from "./commands/completions.js";
+import { devCommand } from "./commands/dev.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { iconCommand } from "./commands/icon.js";
+import { infoCommand } from "./commands/info.js";
+import { initProject } from "./commands/init.js";
+import { inspectCommand } from "./commands/inspect.js";
+import { parseArguments } from "./lib/args.js";
+import { FlareError } from "./lib/errors.js";
+import { createLogger } from "./lib/logger.js";
+import { helpText } from "./help.js";
+import { VERSION } from "./version.js";
+
+export { createLogger };
+
+async function initCommand(context) {
+  await initProject({
+    name: context.positionals[0] ?? "flare-app",
+    baseDirectory: context.projectDirectory,
+    identifier: context.flags.identifier,
+    appVersion: context.flags.appVersion ?? "0.1.0",
+    force: Boolean(context.flags.force),
+    logger: context.logger
+  });
+  return 0;
+}
+
+const handlers = {
+  init: initCommand,
+  dev: devCommand,
+  build: buildCommand,
+  bundle: bundleCommand,
+  icon: iconCommand,
+  info: infoCommand,
+  inspect: inspectCommand,
+  doctor: doctorCommand,
+  completions: completionsCommand,
+  version: (context) => {
+    context.logger.info(VERSION);
+    return 0;
+  },
+  help: (context) => {
+    context.logger.info(helpText().trimEnd());
+    return 0;
+  }
+};
+
+export async function run(argv = []) {
+  const { flags, positionals } = parseArguments(argv);
+  const logger = createLogger({ verbose: Boolean(flags.verbose) });
+
+  if (flags.version) {
+    logger.info(VERSION);
+    return 0;
+  }
+
+  if (flags.help) {
+    logger.info(helpText().trimEnd());
+    return 0;
+  }
+
+  const commandName = positionals.shift() ?? "help";
+  const handler = handlers[commandName];
+  if (!handler) {
+    logger.error(`unknown command '${commandName}'`);
+    logger.info("run 'flare help' to list the commands");
+    return 1;
+  }
+
+  flags.environment ??= commandName === "dev" ? "development" : "production";
+
+  const context = {
+    projectDirectory: path.resolve(flags.project ?? "."),
+    flags,
+    positionals,
+    logger
+  };
+
+  try {
+    return await handler(context);
+  } catch (error) {
+    if (error instanceof FlareError) {
+      logger.error(error.message);
+      return error.exitCode;
+    }
+    logger.error(error?.stack ?? String(error));
+    return 1;
+  }
+}

package/src/commands/build.js

@@ -0,0 +1,37 @@
+import { compileApplication, runHook } from "../lib/build.js";
+import { loadProject, productName } from "../lib/project.js";
+
+export async function buildCommand(context) {
+  const { config, files } = loadProject({
+    projectDirectory: context.projectDirectory,
+    configFile: context.flags.config,
+    environment: context.flags.environment
+  });
+  const mode = context.flags.debug ? "Debug" : "Release";
+
+  context.logger.debug(`configuration layers: ${files.join(", ")}`);
+  context.logger.info(`building '${productName(config)}' ${config.app.version} (${mode.toLowerCase()})`);
+
+  await runHook(config.build.beforeBuildCommand, {
+    cwd: context.projectDirectory,
+    logger: context.logger,
+    label: "before build command"
+  });
+
+  const { binary, directory } = await compileApplication({
+    projectDirectory: context.projectDirectory,
+    config,
+    mode,
+    logger: context.logger
+  });
+
+  await runHook(config.build.afterBuildCommand, {
+    cwd: context.projectDirectory,
+    logger: context.logger,
+    label: "after build command"
+  });
+
+  context.logger.info(`built '${productName(config)}' into '${directory}'`);
+  context.logger.step(`binary ${binary}`);
+  return 0;
+}

package/src/commands/bundle.js

@@ -0,0 +1,44 @@
+import { compileApplication, runHook } from "../lib/build.js";
+import { assertBundleTools, bundleTargets, createBundles } from "../lib/packaging/index.js";
+import { loadProject } from "../lib/project.js";
+
+export async function bundleCommand(context) {
+  const { config } = loadProject({
+    projectDirectory: context.projectDirectory,
+    configFile: context.flags.config,
+    environment: context.flags.environment
+  });
+  const targets = bundleTargets(config, context.flags.bundles);
+
+  assertBundleTools(targets, config);
+
+  await runHook(config.build.beforeBuildCommand, {
+    cwd: context.projectDirectory,
+    logger: context.logger,
+    label: "before build command"
+  });
+
+  const { binary } = await compileApplication({
+    projectDirectory: context.projectDirectory,
+    config,
+    mode: "Release",
+    logger: context.logger
+  });
+
+  await runHook(config.build.afterBuildCommand, {
+    cwd: context.projectDirectory,
+    logger: context.logger,
+    label: "after build command"
+  });
+
+  await createBundles({
+    config,
+    projectDirectory: context.projectDirectory,
+    binary,
+    targets,
+    output: context.flags.out,
+    logger: context.logger
+  });
+
+  return 0;
+}

package/src/commands/completions.js

@@ -0,0 +1,45 @@
+import { COMMAND_NAMES } from "../lib/commands.js";
+import { FlareError } from "../lib/errors.js";
+
+const FLAGS = ["--project", "--config", "--environment", "--json", "--verbose", "--help", "--version"];
+
+export async function completionsCommand(context) {
+  const shell = context.positionals[0] ?? "bash";
+  const commands = COMMAND_NAMES.join(" ");
+
+  if (shell === "bash") {
+    context.logger.info(`_flare_complete() {
+  local current="\${COMP_WORDS[COMP_CWORD]}"
+  COMPREPLY=( $(compgen -W "${commands} ${FLAGS.join(" ")}" -- "$current") )
+}
+complete -F _flare_complete flare`);
+    return 0;
+  }
+
+  if (shell === "zsh") {
+    context.logger.info(`#compdef flare
+
+_arguments '1:command:(${commands})'`);
+    return 0;
+  }
+
+  if (shell === "fish") {
+    for (const command of COMMAND_NAMES) {
+      context.logger.info(`complete -c flare -f -a "${command}"`);
+    }
+    return 0;
+  }
+
+  if (shell === "powershell") {
+    const list = [...COMMAND_NAMES, ...FLAGS].map((value) => `'${value}'`).join(", ");
+    context.logger.info(`Register-ArgumentCompleter -Native -CommandName flare -ScriptBlock {
+    param($wordToComplete, $commandAst, $cursorPosition)
+    ${list} | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+    }
+}`);
+    return 0;
+  }
+
+  throw new FlareError(`unsupported shell '${shell}'`);
+}

package/src/commands/dev.js

@@ -0,0 +1,91 @@
+import { setTimeout as delay } from "node:timers/promises";
+
+import { compileApplication, runHook } from "../lib/build.js";
+import { FlareError } from "../lib/errors.js";
+import { loadProject, productName } from "../lib/project.js";
+import { run, startShell, terminate } from "../lib/process.js";
+
+async function waitForUrl(url, { timeout, logger }) {
+  const deadline = Date.now() + timeout;
+  let attempts = 0;
+  while (Date.now() < deadline) {
+    attempts += 1;
+    try {
+      const response = await fetch(url, { signal: AbortSignal.timeout(2000) });
+      if (response.status < 500) return;
+    } catch {
+      logger.debug(`waiting for ${url} (attempt ${attempts})`);
+    }
+    await delay(250);
+  }
+  throw new FlareError(`development server at '${url}' did not answer within ${Math.round(timeout / 1000)}s`);
+}
+
+export async function devCommand(context) {
+  const { config, files } = loadProject({
+    projectDirectory: context.projectDirectory,
+    configFile: context.flags.config,
+    environment: context.flags.environment
+  });
+  const timeout = Number(context.flags.devTimeout ?? 60000);
+
+  context.logger.info(`development mode for '${productName(config)}'`);
+  context.logger.debug(`configuration layers: ${files.join(", ")}`);
+
+  let server = null;
+  let application = null;
+
+  const stopServer = () => {
+    if (server) terminate(server);
+  };
+  const stopOnSignal = (code) => () => {
+    stopServer();
+    process.exit(code);
+  };
+  const sigintHandler = stopOnSignal(130);
+  const sigtermHandler = stopOnSignal(143);
+  process.once("SIGINT", sigintHandler);
+  process.once("SIGTERM", sigtermHandler);
+
+  try {
+    if (config.build.beforeDevCommand) {
+      context.logger.info(`before dev command: ${config.build.beforeDevCommand}`);
+      server = startShell(config.build.beforeDevCommand, { cwd: context.projectDirectory });
+    }
+
+    if (config.build.devUrl) {
+      context.logger.info(`waiting for ${config.build.devUrl}`);
+      await waitForUrl(config.build.devUrl, { timeout, logger: context.logger });
+    }
+
+    const { binary } = await compileApplication({
+      projectDirectory: context.projectDirectory,
+      config,
+      mode: "Debug",
+      logger: context.logger
+    });
+
+    const env = { FLARE_DEV: "1" };
+    if (config.build.devUrl) env.FLARE_DEV_URL = config.build.devUrl;
+
+    context.logger.info(`running ${binary}`);
+    application = await run(binary, [], { cwd: context.projectDirectory, env });
+  } finally {
+    stopServer();
+    process.off("SIGINT", sigintHandler);
+    process.off("SIGTERM", sigtermHandler);
+    if (application && config.build.afterDevCommand) {
+      await runHook(config.build.afterDevCommand, {
+        cwd: context.projectDirectory,
+        logger: context.logger,
+        label: "after dev command"
+      });
+    }
+  }
+
+  if (!application) return 0;
+  if (application.code !== 0) {
+    context.logger.warn(`the application exited with code ${application.code}`);
+  }
+  return application.code;
+}

package/src/commands/doctor.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+
+import { cmakeVersion, compilerVersion, ninjaVersion } from "../lib/cmake.js";
+import { frontendDirectory, loadProject, platformDisplayName, platformName } from "../lib/project.js";
+import { capture, firstLine } from "../lib/process.js";
+
+function gitVersion() {
+  const result = capture("git", ["--version"]);
+  if (result.error || result.status !== 0) return null;
+  return firstLine(result.stdout);
+}
+
+function hintsFor(platform) {
+  if (platform === "linux") {
+    return [
+      "install libwebkit2gtk-4.1-dev, libgtk-3-dev and build-essential for the native webview",
+      "libwebkit2gtk-4.0-dev works too when the distribution does not ship 4.1"
+    ];
+  }
+  if (platform === "windows") {
+    return [
+      "the WebView2 runtime ships with Windows 11 and current Windows 10 updates",
+      "install the Visual Studio Build Tools with the desktop C++ workload"
+    ];
+  }
+  if (platform === "macos") {
+    return ["WKWebView ships with macOS; install the Xcode command line tools for the compiler"];
+  }
+  return [];
+}
+
+export async function doctorCommand(context) {
+  const checks = [];
+  const add = (status, label, detail) => checks.push({ status, label, detail });
+  const platform = platformName();
+
+  add("ok", "platform", platformDisplayName());
+
+  const nodeMajor = Number(process.versions.node.split(".")[0]);
+  add(nodeMajor >= 18 ? "ok" : "fail", "node", `${process.version}${nodeMajor >= 18 ? "" : " (18 or newer required)"}`);
+
+  const cmake = cmakeVersion();
+  add(cmake ? "ok" : "fail", "cmake", cmake ?? "not found");
+
+  const compiler = compilerVersion();
+  add(compiler ? "ok" : "warn", "compiler", compiler ?? "not found");
+
+  const ninja = ninjaVersion();
+  add(ninja ? "ok" : "warn", "ninja", ninja ?? "not found, the default cmake generator is used");
+
+  const git = gitVersion();
+  add(git ? "ok" : "warn", "git", git ?? "not found, FetchContent cannot clone flare");
+
+  let config = null;
+  try {
+    const project = loadProject({
+      projectDirectory: context.projectDirectory,
+      configFile: context.flags.config,
+      environment: context.flags.environment
+    });
+    config = project.config;
+    add("ok", "configuration", project.configPath);
+  } catch (error) {
+    add("fail", "configuration", error.message);
+  }
+
+  if (config) {
+    const directory = frontendDirectory(context.projectDirectory, config);
+    add(existsSync(directory) ? "ok" : "warn", "frontend", directory);
+  }
+
+  const hints = hintsFor(platform);
+
+  if (context.flags.json) {
+    context.logger.info(JSON.stringify({ platform, checks, hints }, null, 2));
+  } else {
+    context.logger.info("flare doctor");
+    for (const check of checks) {
+      context.logger.info(`  ${check.status.padEnd(5)}${check.label.padEnd(16)}${check.detail}`);
+    }
+    if (hints.length > 0) {
+      context.logger.info("  hints:");
+      for (const hint of hints) context.logger.info(`    ${hint}`);
+    }
+  }
+
+  return checks.some((check) => check.status === "fail") ? 1 : 0;
+}

package/src/commands/icon.js

@@ -0,0 +1,31 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { FlareError } from "../lib/errors.js";
+import { buildIconSet } from "../lib/icons.js";
+import { readPng } from "../lib/png.js";
+
+export async function iconCommand(context) {
+  const source = context.positionals[0];
+  if (!source) throw new FlareError("usage: flare icon <source.png>");
+
+  const sourcePath = path.resolve(context.projectDirectory, source);
+  if (!existsSync(sourcePath)) throw new FlareError(`'${sourcePath}' does not exist`);
+  if (path.extname(sourcePath).toLowerCase() !== ".png") {
+    throw new FlareError("only png sources are supported; export the image as png first");
+  }
+
+  const image = readPng(readFileSync(sourcePath));
+  const files = buildIconSet(image);
+  const output = path.resolve(context.projectDirectory, context.flags.out || "icons");
+  mkdirSync(output, { recursive: true });
+
+  for (const file of files) {
+    const target = path.join(output, file.name);
+    writeFileSync(target, file.data);
+    context.logger.step(`wrote ${target}`);
+  }
+
+  context.logger.info(`generated ${files.length} icon(s) from '${sourcePath}'`);
+  return 0;
+}

package/src/commands/info.js

@@ -0,0 +1,65 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import { architectureName, loadProject, platformDisplayName } from "../lib/project.js";
+import { buildDirectory, cmakeVersion, compilerVersion, executableNames } from "../lib/cmake.js";
+import { VERSION } from "../version.js";
+
+function pad(label) {
+  return label.padEnd(18);
+}
+
+export async function infoCommand(context) {
+  const { config, files } = loadProject({
+    projectDirectory: context.projectDirectory,
+    configFile: context.flags.config,
+    environment: context.flags.environment
+  });
+
+  const binary = path.join(
+    buildDirectory(context.projectDirectory, "Release"),
+    "bin",
+    executableNames(config.app.mainBinaryName || config.app.productName || "flare-app")[0]
+  );
+
+  const report = {
+    flare: VERSION,
+    node: process.versions.node,
+    platform: platformDisplayName(),
+    architecture: architectureName(),
+    cmake: cmakeVersion(),
+    compiler: compilerVersion(),
+    project: context.projectDirectory,
+    configuration: files,
+    productName: config.app.productName,
+    identifier: config.app.identifier,
+    version: config.app.version,
+    windows: config.windows.length,
+    frontendDist: path.resolve(context.projectDirectory, config.build.frontendDist || "frontend"),
+    bundleTargets: config.bundle.targets,
+    binary: existsSync(binary) ? binary : null
+  };
+
+  if (context.flags.json) {
+    context.logger.info(JSON.stringify(report, null, 2));
+    return 0;
+  }
+
+  context.logger.info(`${pad("flare")}${VERSION}`);
+  context.logger.info(`${pad("node")}${process.versions.node}`);
+  context.logger.info(`${pad("platform")}${platformDisplayName()}`);
+  context.logger.info(`${pad("architecture")}${architectureName()}`);
+  context.logger.info(`${pad("cmake")}${report.cmake ?? "not found"}`);
+  context.logger.info(`${pad("compiler")}${report.compiler ?? "not found"}`);
+  context.logger.info(`${pad("project")}${context.projectDirectory}`);
+  context.logger.info(`${pad("product name")}${config.app.productName}`);
+  context.logger.info(`${pad("identifier")}${config.app.identifier}`);
+  context.logger.info(`${pad("version")}${config.app.version}`);
+  context.logger.info(`${pad("windows")}${config.windows.length}`);
+  context.logger.info(`${pad("frontend")}${report.frontendDist}`);
+  context.logger.info(
+    `${pad("bundle targets")}${config.bundle.targets.length > 0 ? config.bundle.targets.join(", ") : "platform defaults"}`
+  );
+  if (report.binary) context.logger.info(`${pad("binary")}${report.binary}`);
+  return 0;
+}