@flare-desktop/cli 0.0.0-stage → 0.1.0

package/src/commands/init.js

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, 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 { writePng } from "../lib/png.js";
+import { VERSION } from "../version.js";
+import {
+  cmakeTemplate,
+  configTemplate,
+  gitignoreTemplate,
+  indexHtmlTemplate,
+  packageJsonTemplate,
+  readmeTemplate,
+  scriptTemplate,
+  sourceTemplate,
+  styleTemplate
+} from "../templates/project.js";
+
+function write(file, content) {
+  writeFileSync(file, content, "utf8");
+}
+
+export async function initProject({
+  name = "flare-app",
+  directory,
+  baseDirectory = ".",
+  identifier,
+  appVersion = "0.1.0",
+  coreVersion = VERSION,
+  force = false,
+  logger
+}) {
+  const projectName = toKebabCase(name);
+  if (!isValidAppName(projectName)) {
+    throw new FlareError(
+      `'${name}' is not a valid project name; use lowercase letters, digits, dashes and underscores`
+    );
+  }
+
+  const appIdentifier = identifier || `com.example.${projectName}`;
+  if (!appIdentifier.includes(".")) {
+    throw new FlareError(`identifier '${appIdentifier}' must contain at least one dot`);
+  }
+
+  const targetDirectory = path.resolve(baseDirectory, directory || projectName);
+  if (existsSync(targetDirectory) && !force) {
+    throw new FlareError(`directory '${targetDirectory}' already exists`);
+  }
+
+  mkdirSync(targetDirectory, { recursive: true });
+  mkdirSync(path.join(targetDirectory, "source"), { recursive: true });
+  mkdirSync(path.join(targetDirectory, "frontend"), { recursive: true });
+  mkdirSync(path.join(targetDirectory, "icons"), { recursive: true });
+
+  const files = [
+    {
+      file: "flare.config.json",
+      content: `${JSON.stringify(
+        configTemplate({ name: projectName, identifier: appIdentifier, version: appVersion }),
+        null,
+        2
+      )}\n`
+    },
+    {
+      file: "package.json",
+      content: `${JSON.stringify(
+        packageJsonTemplate({ name: projectName, version: appVersion, cliVersion: coreVersion }),
+        null,
+        2
+      )}\n`
+    },
+    {
+      file: "CMakeLists.txt",
+      content: cmakeTemplate({ name: projectName, version: appVersion, coreVersion })
+    },
+    {
+      file: "source/main.cpp",
+      content: sourceTemplate({ name: projectName, identifier: appIdentifier, version: appVersion })
+    },
+    { file: "frontend/index.html", content: indexHtmlTemplate(projectName) },
+    { file: "frontend/style.css", content: styleTemplate() },
+    { file: "frontend/main.js", content: scriptTemplate() },
+    { file: ".gitignore", content: gitignoreTemplate() },
+    { file: "README.md", content: readmeTemplate(projectName) }
+  ];
+
+  for (const entry of files) {
+    write(path.join(targetDirectory, entry.file), entry.content);
+  }
+
+  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 (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");
+    logger.step("npm run dev");
+  }
+
+  return { directory: targetDirectory, name: projectName, identifier: appIdentifier, files: written };
+}

package/src/commands/inspect.js

@@ -0,0 +1,35 @@
+import { loadProject } from "../lib/project.js";
+
+export async function inspectCommand(context) {
+  const { config, files } = loadProject({
+    projectDirectory: context.projectDirectory,
+    configFile: context.flags.config,
+    environment: context.flags.environment
+  });
+
+  if (context.flags.json) {
+    context.logger.info(JSON.stringify(config, null, 2));
+    return 0;
+  }
+
+  context.logger.info(`resolved ${files.length} configuration layer(s)`);
+  for (const file of files) {
+    const name = file.split(/[\\/]/).pop();
+    context.logger.step(`${file} (${layerOf(name, context.flags.environment)})`);
+  }
+  context.logger.info("configuration is valid");
+  return 0;
+}
+
+function layerOf(fileName, environment) {
+  const stem = fileName.replace(/\.[^.]+$/, "").toLowerCase();
+  if (stem.endsWith(".local")) return "local";
+  const parts = stem.split(".");
+  if (parts.length >= 2) {
+    const layer = parts[parts.length - 1];
+    if (["linux", "macos", "windows"].includes(layer)) return "platform";
+    if (["development", "production", "staging"].includes(layer)) return "environment";
+    if (environment && layer === environment.toLowerCase()) return "environment";
+  }
+  return "base";
+}

package/src/help.js

@@ -0,0 +1,32 @@
+import { COMMANDS } from "./lib/commands.js";
+import { VERSION } from "./version.js";
+
+export function helpText() {
+  const lines = [
+    `flare ${VERSION}`,
+    "",
+    "usage: flare <command> [options]",
+    "",
+    "commands:"
+  ];
+
+  for (const command of COMMANDS) {
+    lines.push(`  ${command.usage.padEnd(26)}${command.description}`);
+  }
+
+  lines.push(
+    "",
+    "options:",
+    "  --project=<path>      project directory (default: .)",
+    "  --config=<path>       configuration file (default: flare.config.json)",
+    "  --environment=<name>  add the environment configuration layer",
+    "  --bundles=<list>      bundle targets, for example nsis,msi,deb",
+    "  --out=<path>          bundle output directory (default: target/bundle)",
+    "  --json                machine readable output",
+    "  --verbose, -v         enable debug logging",
+    "  --version, -V         print the cli version",
+    "  --help, -h            print this help"
+  );
+
+  return `${lines.join("\n")}\n`;
+}

package/src/index.js

@@ -0,0 +1,17 @@
+export { createLogger, run } from "./cli.js";
+export { initProject } from "./commands/init.js";
+export { VERSION } from "./version.js";
+export {
+  DEFAULT_CONFIG_FILE,
+  DEFAULT_SCHEMA_URL,
+  binaryName,
+  defaults,
+  loadProject,
+  mergeConfig,
+  normalizeConfig,
+  platformName,
+  productName,
+  resolveConfigFiles,
+  validateConfig
+} from "./lib/project.js";
+export { FlareError } from "./lib/errors.js";

package/src/lib/args.js

@@ -0,0 +1,65 @@
+const VALUE_FLAGS = new Set([
+  "project",
+  "config",
+  "environment",
+  "target",
+  "bundles",
+  "out",
+  "format",
+  "identifier",
+  "app-version",
+  "dev-timeout"
+]);
+
+const SHORT_FLAGS = {
+  v: "verbose",
+  h: "help",
+  V: "version"
+};
+
+export function camelCase(name) {
+  return name.replace(/-([a-z0-9])/g, (_, character) => character.toUpperCase());
+}
+
+export function parseArguments(argv) {
+  const flags = {};
+  const positionals = [];
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+
+    if (argument === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+
+    if (argument.startsWith("--")) {
+      const body = argument.slice(2);
+      const separator = body.indexOf("=");
+      if (separator !== -1) {
+        flags[camelCase(body.slice(0, separator))] = body.slice(separator + 1);
+        continue;
+      }
+      if (body.startsWith("no-")) {
+        flags[camelCase(body.slice(3))] = false;
+        continue;
+      }
+      if (VALUE_FLAGS.has(body)) {
+        flags[camelCase(body)] = argv[index + 1] ?? "";
+        index += 1;
+        continue;
+      }
+      flags[camelCase(body)] = true;
+      continue;
+    }
+
+    if (argument.startsWith("-") && argument.length === 2 && SHORT_FLAGS[argument[1]]) {
+      flags[SHORT_FLAGS[argument[1]]] = true;
+      continue;
+    }
+
+    positionals.push(argument);
+  }
+
+  return { flags, positionals };
+}

package/src/lib/build.js

@@ -0,0 +1,29 @@
+import { buildDirectory, buildProject, configureProject, findExecutable } from "./cmake.js";
+import { FlareError } from "./errors.js";
+import { binaryName, frontendDirectory } from "./project.js";
+import { runShell } from "./process.js";
+
+export async function runHook(command, { cwd, env, logger, label }) {
+  if (!command) return;
+  logger.info(`${label}: ${command}`);
+  const result = await runShell(command, { cwd, env });
+  if (result.code !== 0) throw new FlareError(`${label} failed with code ${result.code}`);
+}
+
+export async function compileApplication({ projectDirectory, config, mode, env, logger }) {
+  const directory = buildDirectory(projectDirectory, mode);
+  await configureProject(projectDirectory, {
+    directory,
+    mode,
+    env,
+    logger,
+    frontendDirectory: frontendDirectory(projectDirectory, config)
+  });
+  await buildProject(projectDirectory, { directory, mode, env });
+  const binary = findExecutable(directory, binaryName(config));
+  if (!binary) {
+    throw new FlareError(`built binary '${binaryName(config)}' was not found in '${directory}'`);
+  }
+  logger.debug(`executable ${binary}`);
+  return { binary, directory };
+}

package/src/lib/cmake.js

@@ -0,0 +1,102 @@
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+import { FlareError } from "./errors.js";
+import { capture, firstLine, run } from "./process.js";
+
+export function cmakeVersion() {
+  const result = capture("cmake", ["--version"]);
+  if (result.error || result.status !== 0) return null;
+  return firstLine(result.stdout);
+}
+
+export function ninjaVersion() {
+  const result = capture("ninja", ["--version"]);
+  if (result.error || result.status !== 0) return null;
+  return firstLine(result.stdout);
+}
+
+export function compilerVersion() {
+  const candidates =
+    process.platform === "win32" ? [["cl", []], ["g++", ["--version"]], ["clang++", ["--version"]]] : [["c++", ["--version"]], ["clang++", ["--version"]], ["g++", ["--version"]]];
+  for (const [command, args] of candidates) {
+    const result = capture(command, args);
+    if (!result.error && result.status === 0) return firstLine(result.stdout);
+  }
+  return null;
+}
+
+export function generatorArguments() {
+  if (process.platform === "win32") return [];
+  return ninjaVersion() ? ["-G", "Ninja"] : [];
+}
+
+export function buildDirectory(projectDirectory, mode) {
+  return path.join(projectDirectory, "build", mode === "Debug" ? "debug" : "release");
+}
+
+export async function configureProject(projectDirectory, { directory, mode, env, logger, frontendDirectory }) {
+  if (!cmakeVersion()) throw new FlareError("cmake was not found in PATH");
+  const outputDirectory = path.join(directory, "bin");
+  const configuration = mode.toUpperCase();
+  const args = [
+    "-S",
+    projectDirectory,
+    "-B",
+    directory,
+    ...generatorArguments(),
+    `-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"
+  ];
+  logger.debug(`cmake ${args.join(" ")}`);
+  const result = await run("cmake", args, { cwd: projectDirectory, env });
+  if (result.code !== 0) throw new FlareError("cmake configuration failed");
+}
+
+export async function buildProject(projectDirectory, { directory, mode, target, env }) {
+  const args = ["--build", directory, "--config", mode];
+  if (target) args.push("--target", target);
+  const result = await run("cmake", args, { cwd: projectDirectory, env });
+  if (result.code !== 0) throw new FlareError("compilation failed");
+}
+
+export function executableNames(name) {
+  if (process.platform === "win32") return [`${name}.exe`];
+  return [name];
+}
+
+export function findExecutable(directory, name) {
+  const names = executableNames(name);
+  const candidates = [
+    path.join(directory, "bin"),
+    path.join(directory, "bin", "Release"),
+    path.join(directory, "bin", "Debug"),
+    directory,
+    path.join(directory, "Release"),
+    path.join(directory, "Debug")
+  ];
+
+  for (const candidate of candidates) {
+    for (const fileName of names) {
+      const file = path.join(candidate, fileName);
+      if (existsSync(file)) return file;
+    }
+  }
+
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const nested = path.join(directory, entry.name);
+    for (const fileName of names) {
+      if (existsSync(path.join(nested, fileName))) return path.join(nested, fileName);
+    }
+  }
+
+  return null;
+}

package/src/lib/commands.js

@@ -0,0 +1,15 @@
+export const COMMANDS = [
+  { name: "init", usage: "init [name]", description: "scaffold a new flare project" },
+  { 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: "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" },
+  { name: "doctor", usage: "doctor", description: "check the toolchain and the configuration" },
+  { name: "completions", usage: "completions <shell>", description: "print shell completions (bash, zsh, fish, powershell)" },
+  { name: "version", usage: "version", description: "print the flare cli version" },
+  { name: "help", usage: "help", description: "print this help" }
+];
+
+export const COMMAND_NAMES = COMMANDS.map((command) => command.name);

package/src/lib/errors.js

@@ -0,0 +1,7 @@
+export class FlareError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.name = "FlareError";
+    this.exitCode = exitCode;
+  }
+}

package/src/lib/icons.js

@@ -0,0 +1,127 @@
+import { FlareError } from "./errors.js";
+import { resizePng, writePng } from "./png.js";
+
+export function placeholderIcon(size = 512) {
+  const data = Buffer.alloc(size * size * 4);
+  const center = (size - 1) / 2;
+  const radius = size * 0.46;
+  for (let y = 0; y < size; y += 1) {
+    for (let x = 0; x < size; x += 1) {
+      const target = (y * size + x) * 4;
+      const distance = Math.hypot(x - center, y - center) / radius;
+      const glow = Math.max(0, Math.min(1, 1 - Math.abs(distance - 0.55) * 1.6));
+      const edge = distance <= 1 ? 1 : 0;
+      data[target] = edge ? Math.round(44 + 172 * glow) : 0;
+      data[target + 1] = edge ? Math.round(35 + 132 * glow) : 0;
+      data[target + 2] = edge ? Math.round(40 + 137 * glow) : 0;
+      data[target + 3] = edge ? 255 : 0;
+    }
+  }
+  return { width: size, height: size, data };
+}
+
+const ICO_SIZES = [16, 24, 32, 48, 64, 128, 256];
+const ICNS_TYPES = {
+  16: "icp4",
+  32: "icp5",
+  64: "icp6",
+  128: "ic07",
+  256: "ic08",
+  512: "ic09",
+  1024: "ic10"
+};
+
+function encodeDib(image) {
+  const { width, height, data } = image;
+  const header = Buffer.alloc(40);
+  const xor = Buffer.alloc(width * height * 4);
+  header.writeUInt32LE(40, 0);
+  header.writeInt32LE(width, 4);
+  header.writeInt32LE(height * 2, 8);
+  header.writeUInt16LE(1, 12);
+  header.writeUInt16LE(32, 14);
+  header.writeUInt32LE(0, 16);
+  header.writeUInt32LE(xor.length, 20);
+
+  for (let y = 0; y < height; y += 1) {
+    const source = (height - 1 - y) * width * 4;
+    const target = y * width * 4;
+    for (let x = 0; x < width; x += 1) {
+      xor[target + x * 4] = data[source + x * 4 + 2];
+      xor[target + x * 4 + 1] = data[source + x * 4 + 1];
+      xor[target + x * 4 + 2] = data[source + x * 4];
+      xor[target + x * 4 + 3] = data[source + x * 4 + 3];
+    }
+  }
+
+  const maskStride = Math.ceil(width / 32) * 4;
+  const mask = Buffer.alloc(maskStride * height);
+  header.writeUInt32LE(xor.length + mask.length, 20);
+  return Buffer.concat([header, xor, mask]);
+}
+
+export function encodeIco(image) {
+  const entries = ICO_SIZES.map((size) => {
+    const resized = resizePng(image, size, size);
+    return { size, payload: size >= 128 ? writePng(resized) : encodeDib(resized) };
+  });
+
+  const header = Buffer.alloc(6);
+  header.writeUInt16LE(0, 0);
+  header.writeUInt16LE(1, 2);
+  header.writeUInt16LE(entries.length, 4);
+
+  const directory = Buffer.alloc(entries.length * 16);
+  let offset = 6 + directory.length;
+  entries.forEach((entry, index) => {
+    const target = index * 16;
+    directory[target] = entry.size === 256 ? 0 : entry.size;
+    directory[target + 1] = entry.size === 256 ? 0 : entry.size;
+    directory[target + 2] = 0;
+    directory[target + 3] = 0;
+    directory.writeUInt16LE(1, target + 4);
+    directory.writeUInt16LE(32, target + 6);
+    directory.writeUInt32LE(entry.payload.length, target + 8);
+    directory.writeUInt32LE(offset, target + 12);
+    offset += entry.payload.length;
+  });
+
+  return Buffer.concat([header, directory, ...entries.map((entry) => entry.payload)]);
+}
+
+export function encodeIcns(image) {
+  const chunks = Object.entries(ICNS_TYPES).map(([size, type]) => {
+    const payload = writePng(resizePng(image, Number(size), Number(size)));
+    const header = Buffer.alloc(8);
+    header.write(type, 0, 4, "ascii");
+    header.writeUInt32BE(payload.length + 8, 4);
+    return Buffer.concat([header, payload]);
+  });
+
+  const header = Buffer.alloc(8);
+  header.write("icns", 0, 4, "ascii");
+  header.writeUInt32BE(8 + chunks.reduce((total, chunk) => total + chunk.length, 0), 4);
+  return Buffer.concat([header, ...chunks]);
+}
+
+export function buildIconSet(image) {
+  if (image.width !== image.height) {
+    throw new FlareError(`icon source must be square, got ${image.width}x${image.height}`);
+  }
+
+  const variants = [
+    { name: "32x32.png", size: 32 },
+    { name: "128x128.png", size: 128 },
+    { name: "128x128@2x.png", size: 256 },
+    { name: "icon.png", size: 512 }
+  ];
+
+  return [
+    ...variants.map(({ name, size }) => ({
+      name,
+      data: writePng(resizePng(image, size, size))
+    })),
+    { name: "icon.ico", data: encodeIco(image) },
+    { name: "icon.icns", data: encodeIcns(image) }
+  ];
+}

package/src/lib/logger.js

@@ -0,0 +1,19 @@
+export function createLogger({ verbose = false } = {}) {
+  return {
+    info(message) {
+      process.stdout.write(`${message}\n`);
+    },
+    step(message) {
+      process.stdout.write(`  ${message}\n`);
+    },
+    warn(message) {
+      process.stderr.write(`warning: ${message}\n`);
+    },
+    error(message) {
+      process.stderr.write(`error: ${message}\n`);
+    },
+    debug(message) {
+      if (verbose) process.stderr.write(`debug: ${message}\n`);
+    }
+  };
+}