@flare-desktop/cli 0.1.1 → 0.1.3

package/README.md

@@ -33,6 +33,15 @@ Global options: `--project=<path>`, `--config=<path>`, `--environment=<name>`, `
 
 ## Frontend directory
 
+## Self-contained application configuration
+
+The scaffold generates a typed C++ `Flare::Config` header at build time from `flare.config.json` and its platform,
+environment and local layers. The executable does not read JSON from disk. Rebuild after changing any layer; the
+build system tracks them. `flare dev` embeds the development layer and `flare build` embeds production. The `--config`
+and `--environment` CLI flags select the input at build time. On Windows the generated CMake project enables
+`FLARE_NATIVE_WEBVIEW` before fetching the C++ core; the CLI verifies that the native backend was enabled.
+The generated project requires a CLI release containing `src/lib/embed-config-cli.js` (0.1.2 or newer). The new scaffold targets C++ core `v0.1.1`; publish that tag and its SDK release before using prebuilt mode.
+
 `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:
@@ -75,3 +84,19 @@ 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).
+
+## Frontend templates, prebuilt SDK and codegen
+
+`npm create flare-desktop@latest` offers JavaScript (the existing plain frontend) and TypeScript + Vite.
+TypeScript projects copy version-matched `core.js` and `core.d.ts` into `frontend/`; `tsconfig.json` maps
+`/core.js` to the declaration, while Vite bundles the JavaScript frontend into `dist/` before CMake embeds it.
+
+Choose `--sdk=source` (FetchContent of core tag `v0.1.1`) or `--sdk=prebuilt` (download the matching
+GitHub Release SDK archives into `vendor/flare`). The first binary SDK matrix covers Windows x64 MSVC
+Debug/Release with MD/MT, Linux x64 GCC Debug/Release and macOS x64/arm64 Clang Debug/Release.
+Unsupported architectures/ABIs must use source mode. The current C++ core's native webview runtime is
+implemented on Windows; macOS and Linux builds remain headless. Release SDK archives do not exist until
+the core v0.1.1 tag workflow finishes.
+
+The former C++ `codegen` executable is replaced by `npx flare codegen --language=header|cpp|json` with
+`--config`, `--out`, `--namespace`, `--embed-assets` and `--frontend`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flare-desktop/cli",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Command line interface for the flare desktop toolkit",
   "type": "module",
   "bin": {
@@ -36,9 +36,12 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test \"test/*.test.js\""
+    "test": "node --test"
   },
   "devDependencies": {
     "ajv": "^8.20.0"
+  },
+  "dependencies": {
+    "tar": "^7.5.22"
   }
 }

package/src/cli.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 
 import { buildCommand } from "./commands/build.js";
+import { codegenCommand } from "./commands/codegen.js";
 import { bundleCommand } from "./commands/bundle.js";
 import { completionsCommand } from "./commands/completions.js";
 import { devCommand } from "./commands/dev.js";
@@ -24,6 +25,8 @@ async function initCommand(context) {
     identifier: context.flags.identifier,
     appVersion: context.flags.appVersion ?? "0.1.0",
     force: Boolean(context.flags.force),
+    template: context.flags.template || "javascript",
+    sdkMode: context.flags.sdk || "source",
     logger: context.logger
   });
   return 0;
@@ -35,6 +38,7 @@ const handlers = {
   build: buildCommand,
   bundle: bundleCommand,
   icon: iconCommand,
+  codegen: codegenCommand,
   info: infoCommand,
   inspect: inspectCommand,
   doctor: doctorCommand,

package/src/commands/build.js

@@ -21,6 +21,8 @@ export async function buildCommand(context) {
   const { binary, directory } = await compileApplication({
     projectDirectory: context.projectDirectory,
     config,
+    configFile: context.flags.config || "flare.config.json",
+    environment: context.flags.environment,
     mode,
     logger: context.logger
   });

package/src/commands/bundle.js

@@ -21,6 +21,8 @@ export async function bundleCommand(context) {
   const { binary } = await compileApplication({
     projectDirectory: context.projectDirectory,
     config,
+    configFile: context.flags.config || "flare.config.json",
+    environment: context.flags.environment,
     mode: "Release",
     logger: context.logger
   });

package/src/commands/codegen.js

@@ -0,0 +1,53 @@
+import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { generateEmbeddedConfig } from "../lib/embedded-config.js";
+import { FlareError } from "../lib/errors.js";
+import { loadProject, mergeConfig, parseConfig, toKebabCase } from "../lib/project.js";
+
+function filesIn(directory) {
+  const result = [];
+  const walk = (current) => {
+    for (const entry of readdirSync(current, { withFileTypes: true })) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) walk(absolute);
+      else if (entry.isFile()) result.push({ key: path.relative(directory, absolute).replaceAll(path.sep, "/"), size: statSync(absolute).size });
+    }
+  };
+  walk(directory);
+  return result.sort((a, b) => a.key.localeCompare(b.key));
+}
+
+const MIME = { ".html": "text/html", ".js": "text/javascript", ".css": "text/css", ".json": "application/json", ".svg": "image/svg+xml", ".png": "image/png" };
+
+export async function codegenCommand(context) {
+  const { config, files } = loadProject({
+    projectDirectory: context.projectDirectory,
+    configFile: context.flags.config,
+    environment: context.flags.environment
+  });
+  const output = path.resolve(context.projectDirectory, context.flags.out || "generated");
+  const language = context.flags.language || "header";
+  if (!["header", "hpp", "cpp", "source", "json"].includes(language)) throw new FlareError(`unsupported codegen language '${language}'`);
+  const namespace = context.flags.namespace || "FlareGenerated";
+  if (!/^[A-Za-z_][A-Za-z_0-9]*$/.test(namespace)) throw new FlareError("invalid C++ namespace");
+  mkdirSync(output, { recursive: true });
+  let raw = {};
+  for (const file of files) raw = mergeConfig(raw, parseConfig(readFileSync(file, "utf8"), file));
+  if (language === "json") {
+    const name = config.app.identifier.replace(/[^A-Za-z0-9]/g, "_");
+    writeFileSync(path.join(output, `${name}-config.json`), JSON.stringify(config, null, 2) + "\n");
+  } else {
+    const name = `${toKebabCase(config.app.productName)}-config.h`;
+    writeFileSync(path.join(output, name), generateEmbeddedConfig(config, raw, namespace));
+    const commands = (config.build?.removeUnusedCommands || []).map((item) => `    application.Commands().Unregister(${JSON.stringify(item)});`).join("\n");
+    writeFileSync(path.join(output, "commands.cpp"), `#include <flare/core/application.h>\n\nnamespace ${namespace} {\ninline void RegisterCommands(Flare::Application& application) {\n${commands}\n    (void)application;\n}\n}\n`);
+  }
+  if (context.flags.embedAssets) {
+    const directory = path.resolve(context.projectDirectory, context.flags.frontend || config.build?.frontendDist || "frontend");
+    const assets = filesIn(directory).map(({ key, size }) => ({ key, size, mimeType: MIME[path.extname(key).toLowerCase()] || "application/octet-stream" }));
+    writeFileSync(path.join(output, "asset-manifest.json"), JSON.stringify({ count: assets.length, totalBytes: assets.reduce((a, b) => a + b.size, 0), assets }, null, 2) + "\n");
+  }
+  context.logger.info(`generated configuration in '${output}'`);
+  return 0;
+}

package/src/commands/dev.js

@@ -1,6 +1,6 @@
 import { setTimeout as delay } from "node:timers/promises";
 
-import { compileApplication, runHook } from "../lib/build.js";
+import { compileApplication, ensureFrontendDirectory, 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";
@@ -48,6 +48,12 @@ export async function devCommand(context) {
   process.once("SIGTERM", sigtermHandler);
 
   try {
+    await ensureFrontendDirectory({
+      projectDirectory: context.projectDirectory,
+      config,
+      logger: context.logger
+    });
+
     if (config.build.beforeDevCommand) {
       context.logger.info(`before dev command: ${config.build.beforeDevCommand}`);
       server = startShell(config.build.beforeDevCommand, { cwd: context.projectDirectory });
@@ -61,6 +67,8 @@ export async function devCommand(context) {
     const { binary } = await compileApplication({
       projectDirectory: context.projectDirectory,
       config,
+      configFile: context.flags.config || "flare.config.json",
+      environment: context.flags.environment,
       mode: "Debug",
       logger: context.logger
     });

package/src/commands/init.js

@@ -1,11 +1,13 @@
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import path from "node:path";
 
 import { FlareError } from "../lib/errors.js";
 import { placeholderIcon } from "../lib/icons.js";
 import { isValidAppName, toKebabCase } from "../lib/project.js";
+import { installSdk } from "../lib/sdk.js";
 import { writePng } from "../lib/png.js";
-import { VERSION } from "../version.js";
+import { runShell } from "../lib/process.js";
+import { CORE_VERSION, MIN_CLI_VERSION } from "../release-versions.js";
 import {
   cmakeTemplate,
   configTemplate,
@@ -14,6 +16,9 @@ import {
   packageJsonTemplate,
   readmeTemplate,
   scriptTemplate,
+  typescriptTemplate,
+  tsconfigTemplate,
+  viteConfigTemplate,
   sourceTemplate,
   styleTemplate
 } from "../templates/project.js";
@@ -28,10 +33,16 @@ export async function initProject({
   baseDirectory = ".",
   identifier,
   appVersion = "0.1.0",
-  coreVersion = VERSION,
+  coreVersion = CORE_VERSION,
+  template = "javascript",
+  sdkMode = "source",
+  sdkFetch,
+  installDependencies = false,
   force = false,
   logger
 }) {
+  if (!["javascript", "typescript"].includes(template)) throw new FlareError("template must be javascript or typescript");
+  if (!["source", "prebuilt"].includes(sdkMode)) throw new FlareError("SDK mode must be source or prebuilt");
   const projectName = toKebabCase(name);
   if (!isValidAppName(projectName)) {
     throw new FlareError(
@@ -58,7 +69,7 @@ export async function initProject({
     {
       file: "flare.config.json",
       content: `${JSON.stringify(
-        configTemplate({ name: projectName, identifier: appIdentifier, version: appVersion }),
+        configTemplate({ name: projectName, identifier: appIdentifier, version: appVersion, template }),
         null,
         2
       )}\n`
@@ -66,23 +77,30 @@ export async function initProject({
     {
       file: "package.json",
       content: `${JSON.stringify(
-        packageJsonTemplate({ name: projectName, version: appVersion, cliVersion: coreVersion }),
+        packageJsonTemplate({ name: projectName, version: appVersion, cliVersion: MIN_CLI_VERSION, template }),
         null,
         2
       )}\n`
     },
     {
       file: "CMakeLists.txt",
-      content: cmakeTemplate({ name: projectName, version: appVersion, coreVersion })
+      content: cmakeTemplate({ name: projectName, version: appVersion, coreVersion, sdkMode })
     },
     {
       file: "source/main.cpp",
-      content: sourceTemplate({ name: projectName, identifier: appIdentifier, version: appVersion })
+      content: sourceTemplate({ name: projectName })
     },
-    { file: "frontend/index.html", content: indexHtmlTemplate(projectName) },
+    { file: "frontend/index.html", content: indexHtmlTemplate(projectName, template) },
     { file: "frontend/style.css", content: styleTemplate() },
-    { file: "frontend/main.js", content: scriptTemplate() },
+    ...(template === "typescript" ? [
+      { file: "frontend/main.ts", content: typescriptTemplate() },
+      { file: "frontend/core.js", content: readFileSync(new URL("../templates/core.js", import.meta.url), "utf8") },
+      { file: "frontend/core.d.ts", content: readFileSync(new URL("../templates/core.d.ts", import.meta.url), "utf8") },
+      { file: "tsconfig.json", content: JSON.stringify(tsconfigTemplate(), null, 2) + "\n" },
+      { file: "vite.config.mjs", content: viteConfigTemplate() }
+    ] : [{ file: "frontend/main.js", content: scriptTemplate() }]),
     { file: ".gitignore", content: gitignoreTemplate() },
+    { file: ".clang-format", content: readFileSync(new URL("../templates/clang-format.txt", import.meta.url), "utf8") },
     { file: "README.md", content: readmeTemplate(projectName) }
   ];
 
@@ -90,19 +108,42 @@ export async function initProject({
     write(path.join(targetDirectory, entry.file), entry.content);
   }
 
+  if (sdkMode === "prebuilt") {
+    if (logger) logger.info(`downloading flare SDK v${coreVersion} for ${process.platform}/${process.arch}`);
+    try {
+      await installSdk({ destination: path.join(targetDirectory, "vendor", "flare"), version: coreVersion, ...(sdkFetch ? { fetchImpl: sdkFetch } : {}) });
+    } catch (error) {
+      if (!force) rmSync(targetDirectory, { recursive: true, force: true });
+      throw error;
+    }
+  }
+
   writeFileSync(path.join(targetDirectory, "icons", "icon.png"), writePng(placeholderIcon()));
   writeFileSync(path.join(targetDirectory, "icons", "32x32.png"), writePng(placeholderIcon(32)));
 
   const written = [...files.map((entry) => entry.file), "icons/icon.png", "icons/32x32.png"];
 
+  if (installDependencies) {
+    if (logger) logger.info("installing project dependencies with npm");
+    let result;
+    try {
+      result = await runShell("npm install --no-audit --no-fund", { cwd: targetDirectory });
+    } catch (error) {
+      throw new FlareError(`npm install could not start in '${targetDirectory}': ${error.message}; run npm install manually`);
+    }
+    if (result.code !== 0) {
+      throw new FlareError(`npm install failed in '${targetDirectory}' (code ${result.code}); the project was kept, run npm install manually`);
+    }
+  }
+
   if (logger) {
     logger.info(`created project '${projectName}' in '${targetDirectory}'`);
     logger.info("");
     logger.info("next steps:");
     logger.step(`cd ${path.relative(process.cwd(), targetDirectory) || "."}`);
-    logger.step("npm install");
+    if (!installDependencies) logger.step("npm install");
     logger.step("npm run dev");
   }
 
-  return { directory: targetDirectory, name: projectName, identifier: appIdentifier, files: written };
+  return { directory: targetDirectory, name: projectName, identifier: appIdentifier, template, sdkMode, files: written };
 }

package/src/help.js

@@ -11,7 +11,7 @@ export function helpText() {
   ];
 
   for (const command of COMMANDS) {
-    lines.push(`  ${command.usage.padEnd(26)}${command.description}`);
+    lines.push(`  ${command.usage.padEnd(39)}${command.description}`);
   }
 
   lines.push(
@@ -20,6 +20,12 @@ export function helpText() {
     "  --project=<path>      project directory (default: .)",
     "  --config=<path>       configuration file (default: flare.config.json)",
     "  --environment=<name>  add the environment configuration layer",
+    "  --template=<javascript|typescript>  frontend template (init)",
+    "  --sdk=<source|prebuilt>  C++ dependency mode (init)",
+    "  --language=<header|cpp|json>  codegen format",
+    "  --namespace=<name>    codegen C++ namespace",
+    "  --frontend=<path>    codegen asset directory",
+    "  --embed-assets       codegen asset manifest",
     "  --bundles=<list>      bundle targets, for example nsis,msi,deb",
     "  --out=<path>          bundle output directory (default: target/bundle)",
     "  --json                machine readable output",

package/src/lib/args.js

@@ -8,6 +8,11 @@ const VALUE_FLAGS = new Set([
   "format",
   "identifier",
   "app-version",
+  "sdk",
+  "template",
+  "language",
+  "namespace",
+  "frontend",
   "dev-timeout"
 ]);
 

package/src/lib/build.js

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+
 import { buildDirectory, buildProject, configureProject, findExecutable } from "./cmake.js";
 import { FlareError } from "./errors.js";
 import { binaryName, frontendDirectory } from "./project.js";
@@ -10,14 +12,37 @@ export async function runHook(command, { cwd, env, logger, label }) {
   if (result.code !== 0) throw new FlareError(`${label} failed with code ${result.code}`);
 }
 
-export async function compileApplication({ projectDirectory, config, mode, env, logger }) {
+export async function ensureFrontendDirectory({ projectDirectory, config, logger }) {
+  const frontend = frontendDirectory(projectDirectory, config);
+  if (existsSync(frontend)) return;
+  if (!config.build.beforeBuildCommand) {
+    throw new FlareError(`frontend directory '${frontend}' is missing and no beforeBuildCommand is configured`);
+  }
+  logger.info("preparing frontend assets for CMake embedding");
+  await runHook(config.build.beforeBuildCommand, {
+    cwd: projectDirectory,
+    logger,
+    label: "frontend build command"
+  });
+  if (!existsSync(frontend)) {
+    throw new FlareError(`frontend build command did not create '${frontend}'`);
+  }
+}
+
+export async function compileApplication({ projectDirectory, config, mode, env, logger, configFile, environment }) {
+  const frontend = frontendDirectory(projectDirectory, config);
+  if (!existsSync(frontend)) {
+    throw new FlareError(`frontend directory '${frontend}' is missing; run the frontend build command before compiling`);
+  }
   const directory = buildDirectory(projectDirectory, mode);
   await configureProject(projectDirectory, {
     directory,
     mode,
     env,
     logger,
-    frontendDirectory: frontendDirectory(projectDirectory, config)
+    frontendDirectory: frontend,
+    configFile,
+    environment
   });
   await buildProject(projectDirectory, { directory, mode, env });
   const binary = findExecutable(directory, binaryName(config));

package/src/lib/cmake.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";
 
 import { FlareError } from "./errors.js";
@@ -35,29 +35,47 @@ export function buildDirectory(projectDirectory, mode) {
   return path.join(projectDirectory, "build", mode === "Debug" ? "debug" : "release");
 }
 
-export async function configureProject(projectDirectory, { directory, mode, env, logger, frontendDirectory }) {
+export function msvcUtf8Arguments(directory, { platform = process.platform, cxxFlags = process.env.CXXFLAGS ?? "" } = {}) {
+  if (platform !== "win32") return [];
+  const cacheFile = path.join(directory, "CMakeCache.txt");
+  const cache = existsSync(cacheFile) ? readFileSync(cacheFile, "utf8") : "";
+  const existing = cache.match(/^CMAKE_CXX_FLAGS:STRING=(.*)$/m)?.[1] ?? cxxFlags;
+  if (/(?:^|\s)\/utf-8(?:\s|$)/i.test(existing)) return [];
+  return [`-DCMAKE_CXX_FLAGS:STRING=${[existing.trim(), "/utf-8"].filter(Boolean).join(" ")}`];
+}
+
+export async function configureProject(projectDirectory, { directory, mode, env, logger, frontendDirectory, configFile = "flare.config.json", environment = "production" }) {
   if (!cmakeVersion()) throw new FlareError("cmake was not found in PATH");
   const outputDirectory = path.join(directory, "bin");
   const configuration = mode.toUpperCase();
+  const generator = process.env.CMAKE_GENERATOR ?? "";
+  const multiConfiguration = generator
+    ? /^(Visual Studio|Xcode|Ninja Multi-Config)/.test(generator)
+    : process.platform === "win32";
+  const prebuiltSdk = existsSync(path.join(projectDirectory, "vendor", "flare", "sdk-manifest.json"));
   const args = [
     "-S",
     projectDirectory,
     "-B",
     directory,
     ...generatorArguments(),
-    `-DCMAKE_BUILD_TYPE=${mode}`,
+    ...(!multiConfiguration ? [`-DCMAKE_BUILD_TYPE=${mode}`] : []),
     `-DCMAKE_RUNTIME_OUTPUT_DIRECTORY=${outputDirectory}`,
     `-DCMAKE_RUNTIME_OUTPUT_DIRECTORY_${configuration}=${outputDirectory}`,
     "-DCMAKE_EXPORT_COMPILE_COMMANDS=ON",
     `-DFLARE_FRONTEND_DIR=${frontendDirectory ?? path.join(projectDirectory, "frontend")}`,
-    "-DFLARE_BUILD_TOOLS=OFF",
-    "-DFLARE_BUILD_EXAMPLES=OFF",
-    "-DFLARE_BUILD_TESTS=OFF",
-    "-DFLARE_INSTALL=OFF"
+    ...(!prebuiltSdk ? ["-DFLARE_BUILD_EXAMPLES=OFF", "-DFLARE_BUILD_TESTS=OFF", "-DFLARE_INSTALL=OFF"] : []),
+    ...msvcUtf8Arguments(directory, { cxxFlags: env?.CXXFLAGS ?? process.env.CXXFLAGS ?? "" })
   ];
   logger.debug(`cmake ${args.join(" ")}`);
   const result = await run("cmake", args, { cwd: projectDirectory, env });
   if (result.code !== 0) throw new FlareError("cmake configuration failed");
+  if (process.platform === "win32") {
+    const cache = readFileSync(path.join(directory, "CMakeCache.txt"), "utf8");
+    if (!/^FLARE_NATIVE_WEBVIEW:BOOL=ON$/m.test(cache)) {
+      throw new FlareError("Windows build has no native webview backend; configure with -DFLARE_NATIVE_WEBVIEW=ON");
+    }
+  }
 }
 
 export async function buildProject(projectDirectory, { directory, mode, target, env }) {

package/src/lib/commands.js

@@ -3,6 +3,7 @@ export const COMMANDS = [
   { name: "dev", usage: "dev", description: "build and run the application in development mode" },
   { name: "build", usage: "build [--debug]", description: "build the application" },
   { name: "bundle", usage: "bundle", description: "build and prepare the platform bundle targets" },
+  { name: "codegen", usage: "codegen [--language=header|json]", description: "generate a typed C++ config, JSON or an asset manifest" },
   { name: "icon", usage: "icon <source.png>", description: "generate the icon set from a square png" },
   { name: "info", usage: "info", description: "print project and platform information" },
   { name: "inspect", usage: "inspect", description: "print the resolved configuration layers" },

package/src/lib/embed-config-cli.js

@@ -0,0 +1,14 @@
+import { writeEmbeddedConfig } from "./embedded-config.js";
+
+const [projectDirectory, configFile, environment, output] = process.argv.slice(2);
+if (!projectDirectory || !configFile || !environment || !output) {
+  process.stderr.write("usage: embed-config-cli.js <project> <config> <environment> <output>\n");
+  process.exitCode = 1;
+} else {
+  try {
+    writeEmbeddedConfig({ projectDirectory, configFile, environment, output });
+  } catch (error) {
+    process.stderr.write(`failed to embed configuration: ${error.message}\n`);
+    process.exitCode = 1;
+  }
+}