@quickgui/cli 0.0.1

package/src/cli.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env bun
+
+import { resolve } from "node:path";
+
+import { parseCliArgs, type ParsedCliCommand } from "./args.ts";
+import { buildProject } from "./build.ts";
+import { loadConfig } from "./config.ts";
+import { runDev } from "./dev.ts";
+import { CliError, errorMessage } from "./error.ts";
+import { initProject } from "./init.ts";
+import { hostTarget } from "./targets.ts";
+
+export const CLI_VERSION = "0.0.1";
+
+export async function runCli(argv: string[]): Promise<number> {
+  const command = parseCliArgs(argv);
+  switch (command.command) {
+    case "help":
+      console.log(helpText(command.topic));
+      return 0;
+    case "version":
+      console.log(CLI_VERSION);
+      return 0;
+    case "init": {
+      const destination = await initProject(command);
+      console.log(`\nCreated QuickGUI project at ${destination}`);
+      console.log(`\n  cd ${relativeDisplayPath(destination)}`);
+      if (!command.install) console.log("  bun install");
+      console.log("  bun run dev");
+      return 0;
+    }
+    case "dev":
+      return await runDev(command);
+    case "build":
+      return await runBuild(command);
+  }
+}
+
+async function runBuild(
+  command: Extract<ParsedCliCommand, { command: "build" }>,
+): Promise<number> {
+  const projectRoot = resolve(command.project);
+  const config = await loadConfig(projectRoot, command.configFile);
+  const target = command.target ?? config.target ?? hostTarget();
+  console.log(`[quickgui] Building ${config.name} for ${target}`);
+  const result = await buildProject(config, {
+    mode: "production",
+    target,
+    ...(command.outDir ? { outDir: command.outDir } : {}),
+    ...(command.signingIdentity ? { signingIdentity: command.signingIdentity } : {}),
+    ...(command.notarizationProfile
+      ? { notarization: { keychainProfile: command.notarizationProfile } }
+      : {}),
+  });
+  console.log(`[quickgui] Created ${result.artifactPath}`);
+  if (result.dmgPath) console.log(`[quickgui] Created ${result.dmgPath}`);
+  return 0;
+}
+
+function helpText(topic?: "init" | "dev" | "build"): string {
+  if (topic === "init") {
+    return `Usage: quickgui init [directory] [options]
+
+Create a Solid-powered QuickGUI project.
+
+Options:
+  --name <name>              Application display name
+  --identifier <id>          Reverse-DNS bundle identifier
+  --no-install               Do not run bun install
+  -h, --help                 Show this help`;
+  }
+  if (topic === "dev") {
+    return `Usage: quickgui dev [options]
+
+Package a native development host, run it, and restart it on source changes.
+On macOS the host is a signed .app; application TS/TSX stays outside the bundle.
+
+Options:
+  --project <directory>      Project directory (default: .)
+  --config <file>            Config file (default: quickgui.config.ts)
+  --target <target>          Host target override
+  --sign <identity>          macOS signing identity (default: ad-hoc)
+  --once                     Run without watching
+  --no-launch                Only create the development app
+  -h, --help                 Show this help`;
+  }
+  if (topic === "build") {
+    return `Usage: quickgui build [options]
+
+Build a self-contained production application for a target platform.
+
+Options:
+  --project <directory>      Project directory (default: .)
+  --config <file>            Config file (default: quickgui.config.ts)
+  --target <target>          darwin-arm64, darwin-x64, linux-arm64,
+                            linux-x64, windows-arm64, or windows-x64
+  --out-dir <directory>      Output directory override
+  --sign <identity>          macOS signing identity (default: ad-hoc)
+  --notarize <profile>       Notary Keychain profile for the macOS DMG
+  -h, --help                 Show this help`;
+  }
+  return `QuickGUI CLI ${CLI_VERSION}
+
+Usage: quickgui <command> [options]
+
+Commands:
+  init [directory]           Create a Solid-powered project
+  dev                        Run a native app with source reload
+  build                      Package a production application
+
+Run \`quickgui help <command>\` for command-specific help.`;
+}
+
+function relativeDisplayPath(path: string): string {
+  const current = process.cwd();
+  return path.startsWith(`${current}/`) ? path.slice(current.length + 1) : path;
+}
+
+if (import.meta.main) {
+  try {
+    process.exitCode = await runCli(process.argv.slice(2));
+  } catch (error) {
+    console.error(`quickgui: ${errorMessage(error)}`);
+    process.exitCode = error instanceof CliError ? error.exitCode : 1;
+  }
+}

package/src/config.ts

@@ -0,0 +1,256 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { CliError } from "./error.ts";
+import { parseTarget, type QuickGuiTarget } from "./targets.ts";
+
+export type { QuickGuiTarget } from "./targets.ts";
+
+export interface MacOSNotarizationConfig {
+  /** Profile created with `xcrun notarytool store-credentials`. */
+  keychainProfile: string;
+  /** Optional non-default Keychain containing the profile. */
+  keychain?: string;
+}
+
+export interface MacOSConfig {
+  minimumSystemVersion?: string;
+  category?: string;
+  icon?: string;
+  signingIdentity?: string;
+  entitlements?: string;
+  /** Mounted disk image title. `create-dmg` limits this to 27 characters. */
+  dmgTitle?: string;
+  /** Submit the production DMG to Apple's notary service and staple its ticket. */
+  notarization?: MacOSNotarizationConfig;
+}
+
+export interface WindowsConfig {
+  icon?: string;
+  publisher?: string;
+  description?: string;
+  copyright?: string;
+  hideConsole?: boolean;
+}
+
+export interface QuickGuiConfig {
+  name: string;
+  identifier: string;
+  version?: string;
+  buildVersion?: string;
+  entry?: string;
+  outDir?: string;
+  target?: QuickGuiTarget;
+  resources?: string[];
+  /** OpenType font files embedded in the executable and registered before app startup. */
+  fonts?: string[];
+  /** Custom URL schemes. Packaged macOS apps declare these in their signed Info.plist. */
+  protocols?: string[];
+  macos?: MacOSConfig;
+  windows?: WindowsConfig;
+}
+
+export interface ResolvedQuickGuiConfig {
+  name: string;
+  executableName: string;
+  identifier: string;
+  version: string;
+  buildVersion: string;
+  entry: string;
+  outDir: string;
+  target?: QuickGuiTarget;
+  resources: string[];
+  fonts: string[];
+  protocols: string[];
+  macos: Required<Pick<MacOSConfig, "minimumSystemVersion" | "category">> & MacOSConfig;
+  windows: Required<Pick<WindowsConfig, "hideConsole">> & WindowsConfig;
+  projectRoot: string;
+  configPath: string;
+}
+
+export function defineConfig(config: QuickGuiConfig): QuickGuiConfig {
+  return config;
+}
+
+export async function loadConfig(
+  projectRoot: string,
+  configFile = "quickgui.config.ts",
+): Promise<ResolvedQuickGuiConfig> {
+  const root = resolve(projectRoot);
+  const configPath = isAbsolute(configFile) ? configFile : resolve(root, configFile);
+  if (!existsSync(configPath)) {
+    throw new CliError(`QuickGUI config not found: ${configPath}`);
+  }
+  const url = pathToFileURL(configPath);
+  url.searchParams.set("quickgui_reload", `${Date.now()}_${Math.random()}`);
+  let module: { default?: unknown };
+  try {
+    module = (await import(url.href)) as { default?: unknown };
+  } catch (error) {
+    throw new CliError(`Could not load ${configPath}`, { cause: error });
+  }
+  return resolveConfig(module.default, root, configPath);
+}
+
+export function resolveConfig(
+  input: unknown,
+  projectRoot: string,
+  configPath = resolve(projectRoot, "quickgui.config.ts"),
+): ResolvedQuickGuiConfig {
+  if (!isRecord(input)) throw new CliError("QuickGUI config must export an object");
+  const name = requiredString(input.name, "name", 128);
+  const identifier = requiredString(input.identifier, "identifier", 255);
+  if (!/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(identifier)) {
+    throw new CliError(`Invalid application identifier \`${identifier}\``);
+  }
+  const version = optionalString(input.version, "version", 64) ?? "0.1.0";
+  const buildVersion = optionalString(input.buildVersion, "buildVersion", 64) ?? version;
+  const entry = resolveRelative(projectRoot, optionalString(input.entry, "entry", 1_024) ?? "src/app.tsx");
+  const outDir = resolveRelative(projectRoot, optionalString(input.outDir, "outDir", 1_024) ?? "dist");
+  const target = input.target === undefined ? undefined : parseTarget(requiredString(input.target, "target", 64));
+  const resources = stringArray(input.resources, "resources").map((path) =>
+    resolveRelative(projectRoot, path),
+  );
+  const fonts = stringArray(input.fonts, "fonts").map((path) =>
+    resolveRelative(projectRoot, path),
+  );
+  const protocols = protocolArray(input.protocols);
+  const macos = objectOrEmpty(input.macos, "macos");
+  const windows = objectOrEmpty(input.windows, "windows");
+  const icon = optionalString(macos.icon, "macos.icon", 1_024);
+  const entitlements = optionalString(macos.entitlements, "macos.entitlements", 1_024);
+  const notarization = resolveMacOSNotarization(macos.notarization, projectRoot);
+  const windowsIcon = optionalString(windows.icon, "windows.icon", 1_024);
+
+  return {
+    name,
+    executableName: executableName(name),
+    identifier,
+    version,
+    buildVersion,
+    entry,
+    outDir,
+    ...(target ? { target } : {}),
+    resources,
+    fonts,
+    protocols,
+    macos: {
+      minimumSystemVersion:
+        optionalString(macos.minimumSystemVersion, "macos.minimumSystemVersion", 32) ?? "13.0",
+      category:
+        optionalString(macos.category, "macos.category", 255) ??
+        "public.app-category.developer-tools",
+      ...(icon ? { icon: resolveRelative(projectRoot, icon) } : {}),
+      ...(optionalString(macos.signingIdentity, "macos.signingIdentity", 512)
+        ? { signingIdentity: String(macos.signingIdentity) }
+        : {}),
+      ...(entitlements ? { entitlements: resolveRelative(projectRoot, entitlements) } : {}),
+      ...(optionalString(macos.dmgTitle, "macos.dmgTitle", 27)
+        ? { dmgTitle: String(macos.dmgTitle) }
+        : {}),
+      ...(notarization ? { notarization } : {}),
+    },
+    windows: {
+      hideConsole: optionalBoolean(windows.hideConsole, "windows.hideConsole") ?? true,
+      ...(windowsIcon ? { icon: resolveRelative(projectRoot, windowsIcon) } : {}),
+      ...(optionalString(windows.publisher, "windows.publisher", 255)
+        ? { publisher: String(windows.publisher) }
+        : {}),
+      ...(optionalString(windows.description, "windows.description", 512)
+        ? { description: String(windows.description) }
+        : {}),
+      ...(optionalString(windows.copyright, "windows.copyright", 512)
+        ? { copyright: String(windows.copyright) }
+        : {}),
+    },
+    projectRoot: resolve(projectRoot),
+    configPath: resolve(configPath),
+  };
+}
+
+function resolveMacOSNotarization(
+  value: unknown,
+  projectRoot: string,
+): MacOSNotarizationConfig | undefined {
+  if (value === undefined) return undefined;
+  const notarization = objectOrEmpty(value, "macos.notarization");
+  const keychainProfile = requiredString(
+    notarization.keychainProfile,
+    "macos.notarization.keychainProfile",
+    512,
+  );
+  const keychain = optionalString(notarization.keychain, "macos.notarization.keychain", 1_024);
+  return {
+    keychainProfile,
+    ...(keychain ? { keychain: resolveRelative(projectRoot, keychain) } : {}),
+  };
+}
+
+function protocolArray(value: unknown): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 64) {
+    throw new CliError("`protocols` must be an array with at most 64 URL schemes");
+  }
+  const protocols = value.map((item, index) =>
+    requiredString(item, `protocols[${index}]`, 64).toLowerCase(),
+  );
+  for (const protocol of protocols) {
+    if (!/^[a-z][a-z0-9+.-]*$/.test(protocol)) {
+      throw new CliError(`Invalid URL scheme \`${protocol}\` in \`protocols\``);
+    }
+  }
+  return [...new Set(protocols)];
+}
+
+function executableName(name: string): string {
+  const value = name
+    .normalize("NFKD")
+    .replace(/[^A-Za-z0-9._-]+/g, "-")
+    .replace(/^[._-]+|[._-]+$/g, "")
+    .slice(0, 128);
+  if (!value || value === "." || value === "..") {
+    throw new CliError("Application name does not contain a usable executable name");
+  }
+  return value;
+}
+
+function resolveRelative(root: string, path: string): string {
+  return isAbsolute(path) ? resolve(path) : resolve(root, path);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function objectOrEmpty(value: unknown, field: string): Record<string, unknown> {
+  if (value === undefined) return {};
+  if (!isRecord(value)) throw new CliError(`\`${field}\` must be an object`);
+  return value;
+}
+
+function requiredString(value: unknown, field: string, maximum = 255): string {
+  if (typeof value !== "string" || value.trim().length === 0 || value.length > maximum) {
+    throw new CliError(`\`${field}\` must be a non-empty string of at most ${maximum} characters`);
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown, field: string, maximum: number): string | undefined {
+  if (value === undefined) return undefined;
+  return requiredString(value, field, maximum);
+}
+
+function optionalBoolean(value: unknown, field: string): boolean | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "boolean") throw new CliError(`\`${field}\` must be a boolean`);
+  return value;
+}
+
+function stringArray(value: unknown, field: string): string[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.length > 1_024) {
+    throw new CliError(`\`${field}\` must be an array with at most 1024 paths`);
+  }
+  return value.map((item, index) => requiredString(item, `${field}[${index}]`, 1_024));
+}

package/src/dev.ts

@@ -0,0 +1,279 @@
+import { watch, type FSWatcher } from "node:fs";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import { buildProject, type BuildResult } from "./build.ts";
+import { loadConfig, type ResolvedQuickGuiConfig } from "./config.ts";
+import { CliError, errorMessage } from "./error.ts";
+import { hostTarget, type QuickGuiTarget } from "./targets.ts";
+
+export interface DevOptions {
+  project: string;
+  configFile: string;
+  once: boolean;
+  launch: boolean;
+  target?: QuickGuiTarget;
+  signingIdentity?: string;
+}
+
+type AppProcess = Bun.Subprocess<"ignore", "inherit", "inherit">;
+
+interface ExitingProcess {
+  readonly exited: Promise<number>;
+}
+
+/** @internal */
+export class ActiveProcessMonitor<T extends ExitingProcess> {
+  #active: T | undefined;
+  #closed = false;
+  #onExit: (status: number) => void;
+
+  constructor(onExit: (status: number) => void) {
+    this.#onExit = onExit;
+  }
+
+  get active(): T | undefined {
+    return this.#active;
+  }
+
+  activate(child: T): void {
+    this.#active = child;
+    void child.exited.then((status) => {
+      if (!this.#closed && this.#active === child) this.#onExit(status);
+    });
+  }
+
+  close(): void {
+    this.#closed = true;
+  }
+}
+
+export async function runDev(options: DevOptions): Promise<number> {
+  const projectRoot = resolve(options.project);
+  const target = options.target ?? hostTarget();
+  const host = hostTarget();
+  if (target !== host) {
+    throw new CliError(
+      `Development apps must run on the host target (${host}); use \`quickgui build --target ${target}\` for cross-compilation`,
+    );
+  }
+
+  let config = await loadConfig(projectRoot, options.configFile);
+  let build = await packageDevelopmentHost(config, target, options.signingIdentity);
+  console.log(`[quickgui] Development app: ${build.artifactPath}`);
+  if (!options.launch) return 0;
+
+  if (options.once) {
+    const child = await launchApplication(build, config);
+    console.log(`[quickgui] App ready (pid ${child.pid})`);
+    return await child.exited;
+  }
+
+  const abortController = new AbortController();
+  let stopping = false;
+  const processes = new ActiveProcessMonitor<AppProcess>((status) => {
+    if (stopping || abortController.signal.aborted) return;
+    console.log(`[quickgui] App exited (status ${status}); stopping watcher`);
+    abortController.abort();
+  });
+  let reloadQueued = false;
+  let reloadPromise: Promise<void> | undefined;
+  let changedPath: string | undefined;
+  let debounce: ReturnType<typeof setTimeout> | undefined;
+
+  const reload = async (): Promise<void> => {
+    try {
+      const nextConfig = await loadConfig(projectRoot, options.configFile);
+      const nextBuild = await packageDevelopmentHost(
+        nextConfig,
+        target,
+        options.signingIdentity,
+      );
+      const candidate = await launchApplication(nextBuild, nextConfig, abortController.signal);
+      if (stopping) {
+        await stopApplication(candidate);
+        return;
+      }
+      const previous = processes.active;
+      processes.activate(candidate);
+      config = nextConfig;
+      build = nextBuild;
+      if (previous) await stopApplication(previous);
+      console.log(`[quickgui] Reloaded (pid ${candidate.pid})`);
+    } catch (error) {
+      if (!stopping) {
+        console.error(
+          `[quickgui] Reload failed; keeping the previous app running.\n${errorMessage(error)}`,
+        );
+      }
+    }
+  };
+
+  const queueReload = (path: string | undefined): void => {
+    if (stopping) return;
+    changedPath = path;
+    reloadQueued = true;
+    if (reloadPromise) return;
+    reloadPromise = (async () => {
+      while (reloadQueued && !stopping) {
+        reloadQueued = false;
+        await reload();
+      }
+    })().finally(() => {
+      reloadPromise = undefined;
+      if (reloadQueued && !stopping) queueReload(changedPath);
+    });
+  };
+
+  let watcher: FSWatcher;
+  try {
+    watcher = watch(projectRoot, { recursive: true }, (_event, filename) => {
+      const path = filename ? resolve(projectRoot, String(filename)) : undefined;
+      if (path && shouldIgnoreChange(projectRoot, path, config.outDir)) return;
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(() => queueReload(path), 80);
+    });
+  } catch (error) {
+    throw new CliError(`Could not watch ${projectRoot}`, { cause: error });
+  }
+  watcher.on("error", (error) => {
+    console.error(`[quickgui] File watcher error: ${errorMessage(error)}`);
+  });
+
+  try {
+    try {
+      const child = await launchApplication(build, config, abortController.signal);
+      processes.activate(child);
+      console.log(`[quickgui] App ready (pid ${child.pid}); watching for changes`);
+    } catch (error) {
+      console.error(`[quickgui] App failed to start; watching for changes.\n${errorMessage(error)}`);
+    }
+
+    await waitForShutdown(abortController);
+  } finally {
+    stopping = true;
+    processes.close();
+    abortController.abort();
+    if (debounce) clearTimeout(debounce);
+    watcher.close();
+    if (reloadPromise) await reloadPromise;
+    if (processes.active) await stopApplication(processes.active);
+  }
+  return 0;
+}
+
+async function packageDevelopmentHost(
+  config: ResolvedQuickGuiConfig,
+  target: QuickGuiTarget,
+  signingIdentity?: string,
+): Promise<BuildResult> {
+  const started = performance.now();
+  const result = await buildProject(config, {
+    mode: "development",
+    target,
+    ...(signingIdentity ? { signingIdentity } : {}),
+  });
+  console.log(`[quickgui] Packaged dev host in ${Math.round(performance.now() - started)} ms`);
+  return result;
+}
+
+async function launchApplication(
+  build: BuildResult,
+  config: ResolvedQuickGuiConfig,
+  signal?: AbortSignal,
+): Promise<AppProcess> {
+  let ready = false;
+  let resolveReady!: () => void;
+  let rejectReady!: (error: Error) => void;
+  const readyPromise = new Promise<void>((resolvePromise, rejectPromise) => {
+    resolveReady = resolvePromise;
+    rejectReady = rejectPromise;
+  });
+  const child = Bun.spawn([build.executablePath], {
+    cwd: config.projectRoot,
+    env: {
+      ...process.env,
+      NODE_ENV: "development",
+      QUICKGUI_DEV: "1",
+    },
+    stdin: "ignore",
+    stdout: "inherit",
+    stderr: "inherit",
+    ipc(message) {
+      if (isReadyMessage(message) && !ready) {
+        ready = true;
+        resolveReady();
+      }
+    },
+  });
+  void child.exited.then((status) => {
+    if (!ready) {
+      rejectReady(
+        new CliError(`Application exited before its first window was ready (status ${status})`),
+      );
+    }
+  });
+
+  const abort = (): void => rejectReady(new CliError("Development launch cancelled"));
+  signal?.addEventListener("abort", abort, { once: true });
+  const timeout = setTimeout(() => {
+    rejectReady(new CliError("Application did not report a ready window within 15 seconds"));
+  }, 15_000);
+  try {
+    await readyPromise;
+    return child;
+  } catch (error) {
+    await stopApplication(child);
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    signal?.removeEventListener("abort", abort);
+  }
+}
+
+async function stopApplication(child: AppProcess): Promise<void> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    await child.exited;
+    return;
+  }
+  child.kill("SIGTERM");
+  await Promise.race([child.exited, Bun.sleep(1_500)]);
+  if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+  await child.exited;
+}
+
+function shouldIgnoreChange(root: string, path: string, outDir: string): boolean {
+  const pathFromRoot = relative(root, path);
+  if (pathFromRoot.startsWith("..") || isAbsolute(pathFromRoot)) return true;
+  const parts = pathFromRoot.split(sep);
+  if (parts.some((part) => [".git", ".quickgui", "node_modules", "target"].includes(part))) {
+    return true;
+  }
+  const outDirFromRoot = relative(root, outDir);
+  const outDirIsInsideRoot =
+    outDirFromRoot !== "" && !outDirFromRoot.startsWith("..") && !isAbsolute(outDirFromRoot);
+  if (!outDirIsInsideRoot) return false;
+  const pathFromOutDir = relative(outDir, path);
+  return pathFromOutDir === "" ||
+    (!pathFromOutDir.startsWith("..") && !isAbsolute(pathFromOutDir));
+}
+
+function isReadyMessage(value: unknown): value is { type: "quickgui-ready" } {
+  return (
+    typeof value === "object" && value !== null && Reflect.get(value, "type") === "quickgui-ready"
+  );
+}
+
+async function waitForShutdown(abortController: AbortController): Promise<void> {
+  if (abortController.signal.aborted) return;
+  await new Promise<void>((resolvePromise) => {
+    const requestShutdown = (): void => abortController.abort();
+    const finish = (): void => {
+      process.off("SIGINT", requestShutdown);
+      process.off("SIGTERM", requestShutdown);
+      resolvePromise();
+    };
+    process.once("SIGINT", requestShutdown);
+    process.once("SIGTERM", requestShutdown);
+    abortController.signal.addEventListener("abort", finish, { once: true });
+  });
+}

package/src/error.ts

@@ -0,0 +1,17 @@
+export class CliError extends Error {
+  readonly exitCode: number;
+
+  constructor(message: string, options: ErrorOptions & { exitCode?: number } = {}) {
+    super(message, options);
+    this.name = "CliError";
+    this.exitCode = options.exitCode ?? 1;
+  }
+}
+
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    const cause = error.cause instanceof Error ? `\n${errorMessage(error.cause)}` : "";
+    return `${error.message}${cause}`;
+  }
+  return String(error);
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+export type {
+  MacOSConfig,
+  MacOSNotarizationConfig,
+  QuickGuiConfig,
+  QuickGuiTarget,
+  WindowsConfig,
+} from "./config.ts";
+export { defineConfig } from "./config.ts";
+export { hostTarget, supportedTargets } from "./targets.ts";