lucynui 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# LucyN UI
 
-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.
+Desktop apps from plain HTML, CSS and JS. Write web files, get a native window.
+
+Built on [webview-bun](https://github.com/tr1ckydev/webview-bun) and [Elysia](https://elysiajs.com), running on Bun.
+No React. No Rust. No Electron.
+
+## Quick start
+
+Scaffold a new app and start it:
+
+```bash
+lucyn create-ui myapp
+```
+
+Or, inside an empty folder, install the package and let it set everything up:
+
+```bash
+bun add lucynui --trust
+```
+
+Either way you end up with a dev server running and a native window on the app. The `--trust` flag matters: Bun blocks
+install scripts by default, and this package uses one to scaffold the folder and start dev. If you already ran a plain
+`bun add lucynui`, finish with `bun pm trust lucynui`.
+
+A new app is just your files plus a dependency on this package:
+
+```
+myapp/
+  app.ts              entry point — createApp()
+  index.html          your UI
+  style.css
+  app.js
+  lucyn.config.ts     title / size / port
+  package.json        depends on lucynui
+```
+
+The framework is not copied into the app — it stays in `node_modules/lucynui`. The starter files come from the
+[lucynui-template](https://github.com/LucyNBrowserEngine/lucynui-template) repo.
+
+## Commands
+
+```bash
+lucyn create-ui <appname>   # clone the template, install, test the build, start dev
+lucyn                       # set up the current folder and start it
+lucyn dev                   # dev server + window, hot reload on .html/.css/.js changes
+lucyn build                 # single binary in ./dist
+```
+
+`lucyn dev` serves your project root over `http://localhost:3927`, opens a native window pointed at it and reloads the
+window whenever an `.html`, `.css` or `.js` file changes. No browser is opened.
+
+## Config
+
+`lucyn.config.ts` in your project root. Every field is optional.
+
+```ts
+export default {
+  title: "My App", // default: "LucyN App"
+  width: 1200, // default: 1024
+  height: 800, // default: 768
+  port: 3927, // default: 3927, falls back to the next free port
+  dev: false, // default: false
+};
+```
+
+Missing file or broken config silently falls back to the defaults, so `createApp()` always works.
+
+You can also pass config straight to `createApp({ title: "Override" })` — anything passed there wins over the file.
+
+## Build
+
+`lucyn build` runs:
+
+```bash
+bun build --compile --minify ./app.ts --outfile ./dist/<name>
+```
+
+The binary name is the `title` from `lucyn.config.ts`, lowercased (`"My App"` → `my-app`). The native window library is
+embedded in the binary, so `./dist/<name>` is the only file you need to ship. The build halts with a message if there is
+no `app.ts` in your project root.
+
+## What's in the package
+
+```
+bin/lucyn.ts        the CLI entry point
+cli/                create-ui, init, dev, build, install hook, terminal styling
+src/                the framework
+  lucyn.ts          createApp — starts server + window
+  config.ts         reads lucyn.config.ts
+  server.ts         Elysia file server + hot reload
+  build.ts          compile step
+  index.ts          public exports
+webview-bun/        native window bindings + prebuilt libraries for linux, mac and windows
+```
+
+## File server
+
+| Request          | Result                       |
+| ---------------- | ---------------------------- |
+| `GET /`          | `index.html`                 |
+| `GET /style.css` | `style.css`                  |
+| `GET /app.js`    | `app.js`                     |
+| `GET /*`         | any file in the project root |
+| anything missing | LucyN branded error page     |
+
+Paths are resolved inside the project root only — anything escaping it gets a 403.
+
+## Notes
+
+- On Windows you get a warning on startup: LucyN UI is built and tested on Linux, and Windows builds differ.
+- `create-ui` checks for the GTK/WebKit libraries the window needs and installs them with apt on Debian-based Linux.
+- If `index.html` is missing, the window shows a helpful error instead of a blank page.
+- Ports: if the configured port is taken, LucyN UI keeps incrementing until it finds a free one and logs the port it
+  actually used.

package/bin/lucyn.ts

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

package/cli/create.ts

@@ -0,0 +1,223 @@
+import { closeSync, openSync } from "node:fs";
+import { cp, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import * as proc from "./proc";
+import * as ui from "./ui";
+
+/** Matches the line the framework logs once the server is listening. */
+const SERVER_READY = /dev server running on http:\/\/localhost:(\d+)/;
+
+/** The starter files, mirroring the template repo. */
+const TEMPLATE_FILES = ["index.html", "style.css", "app.js", "app.ts", "lucyn.config.ts", "tsconfig.json", ".gitignore"];
+
+const bun = () => proc.findBun() ?? "bun";
+
+/* ------------------------------------------------------------------ commands */
+
+export async function dev(): Promise<never> {
+  proc.requireProject();
+  process.exit(await proc.run(process.cwd(), [bun(), proc.frameworkPath("lucyn.ts"), "--dev"]));
+}
+
+export async function build(): Promise<never> {
+  proc.requireProject();
+  ui.info("Building your app...");
+
+  const code = await proc.run(process.cwd(), [bun(), proc.frameworkPath("build.ts")]);
+  if (code !== 0) process.exit(code);
+
+  ui.ok("Build complete! Check ./dist");
+  process.exit(0);
+}
+
+/** `lucyn create-ui <appname>` — the whole zero-to-running-app pipeline. */
+export async function create(appName: string): Promise<never> {
+  if (process.platform === "win32") ui.warn(ui.WINDOWS_NOTICE);
+
+  const bunPath = await proc.ensureBun();
+  await proc.ensureSystemDeps();
+  proc.requireGit();
+
+  ui.step(1, "cloning the template, hang on");
+  await proc.runStep(process.cwd(), ["git", "clone", "--depth", "1", proc.TEMPLATE_REPO, appName]);
+  await rm(join(appName, ".git"), { recursive: true, force: true });
+  await pinFramework(appName);
+  ui.done("cloning complete — fetching the deps and required builds");
+
+  ui.step(2, "installing modules including lucynui");
+  await proc.runStep(appName, [bunPath, "install"]);
+  ui.done("modules installed");
+
+  ui.step(3, "testing build");
+  await testBuild(appName);
+  ui.done("build was successful");
+
+  ui.step(4, "starting dev with hmr");
+  const code = await runDev(appName, (port) => {
+    ui.done(`dev is up and running on port ${port}`);
+    ui.ready(basename(appName));
+  });
+
+  process.exit(code);
+}
+
+/** `lucyn` / `lucyn init` — scaffold into the current folder, then run it. */
+export async function init(): Promise<never> {
+  const bunPath = await proc.ensureBun();
+  await proc.ensureSystemDeps();
+  proc.requireGit();
+
+  if (await isProject(process.cwd())) {
+    ui.info("This is already a LucyN UI app — starting dev.");
+  } else {
+    ui.step(1, "cloning the template, hang on");
+    await scaffoldInto(process.cwd());
+    ui.done("cloning complete — fetching the deps and required builds");
+
+    ui.step(2, "installing modules including lucynui");
+    await proc.runStep(process.cwd(), [bunPath, "install"]);
+    ui.done("modules installed");
+
+    ui.step(3, "testing build");
+    await testBuild(process.cwd());
+    ui.done("build was successful");
+  }
+
+  ui.step(4, "starting dev with hmr");
+  const code = await runDev(process.cwd(), (port) => {
+    ui.done(`dev is up and running on port ${port}`);
+    ui.ready(basename(process.cwd()));
+  });
+
+  process.exit(code);
+}
+
+/* ------------------------------------------------------------------- helpers */
+
+export function isProject(dir: string) {
+  return Bun.file(join(dir, proc.CONFIG_FILE)).exists();
+}
+
+/** Runs a build and throws away the binary — the point is proving it compiles. */
+export async function testBuild(dir: string) {
+  const code = await proc.run(dir, [bun(), proc.frameworkPath("build.ts")]);
+  await rm(join(dir, "dist"), { recursive: true, force: true });
+
+  if (code !== 0) throw new Error("the test build failed");
+}
+
+/** Copies the starter files into an existing folder, never overwriting anything. */
+export async function scaffoldInto(dir: string) {
+  const source = await fetchTemplate();
+
+  try {
+    for (const file of TEMPLATE_FILES) {
+      const target = join(dir, file);
+      if (await Bun.file(target).exists()) continue;
+      await cp(join(source, file), target);
+    }
+
+    const manifest = join(dir, "package.json");
+    if (!(await Bun.file(manifest).exists())) {
+      await cp(join(source, "package.json"), manifest);
+    }
+  } finally {
+    await rm(source, { recursive: true, force: true });
+  }
+}
+
+/** Points the app at this CLI's own version, so template drift can never bite. */
+async function pinFramework(dir: string) {
+  const manifest = Bun.file(join(dir, "package.json"));
+  if (!(await manifest.exists())) return;
+
+  // Running from a checkout rather than an install? Point the app at this copy
+  // so the whole flow can be tried out before the package is published.
+  const spec = import.meta.dir.includes("node_modules")
+    ? `^${await proc.packageVersion()}`
+    : `file:${proc.packageRoot()}`;
+
+  const pkg = await manifest.json();
+  pkg.dependencies = { ...(pkg.dependencies ?? {}), lucynui: spec };
+  await Bun.write(manifest, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+async function fetchTemplate() {
+  const tmp = await mkdtemp(join(tmpdir(), "lucyn-template-"));
+  await mkdir(tmp, { recursive: true });
+  const checkout = join(tmp, "template");
+
+  await proc.runStep(tmp, ["git", "clone", "--depth", "1", proc.TEMPLATE_REPO, checkout]);
+  await rm(join(checkout, ".git"), { recursive: true, force: true });
+
+  return checkout;
+}
+
+/**
+ * Starts dev in the foreground, forwarding output, and calls `onReady` with the
+ * port the server actually bound to.
+ */
+async function runDev(dir: string, onReady: (port: number) => void): Promise<number> {
+  const child = Bun.spawn([bun(), proc.frameworkPath("lucyn.ts"), "--dev"], {
+    cwd: dir,
+    stdin: "ignore",
+    stdout: "pipe",
+    stderr: "inherit",
+  });
+
+  const decoder = new TextDecoder();
+  let seen = "";
+  let announced = false;
+
+  for await (const chunk of child.stdout) {
+    process.stdout.write(chunk);
+    if (announced) continue;
+
+    seen += decoder.decode(chunk, { stream: true });
+    const port = SERVER_READY.exec(seen)?.[1];
+    if (port) {
+      announced = true;
+      onReady(Number(port));
+    }
+  }
+
+  return await child.exited;
+}
+
+/**
+ * Starts dev detached so the caller can exit, writing output to `logPath`.
+ * Returns the port, or null when the window never came up.
+ */
+export async function devDetached(dir: string, logPath: string): Promise<number | null> {
+  const fd = openSync(logPath, "a");
+
+  const child = Bun.spawn([bun(), proc.frameworkPath("lucyn.ts"), "--dev"], {
+    cwd: dir,
+    stdin: "ignore",
+    stdout: fd,
+    stderr: fd,
+  });
+
+  try {
+    for (let attempt = 0; attempt < 80; attempt++) {
+      await Bun.sleep(250);
+
+      const log = await Bun.file(logPath).text();
+      const port = SERVER_READY.exec(log)?.[1];
+
+      if (port) {
+        // Give it a moment to prove it survives the window actually opening.
+        await Bun.sleep(500);
+        return child.exitCode === null ? Number(port) : null;
+      }
+
+      if (child.exitCode !== null) return null;
+    }
+
+    return null;
+  } finally {
+    child.unref();
+    closeSync(fd);
+  }
+}

package/cli/index.ts

@@ -0,0 +1,53 @@
+import * as create from "./create";
+import * as ui from "./ui";
+
+const HELP = `${ui.accent("lucyn")} — desktop apps from plain HTML, CSS and JS
+
+  ${ui.accent("lucyn create-ui <appname>")}   scaffold a new app and start it
+  ${ui.accent("lucyn")}                       set up the current folder and start it
+  ${ui.accent("lucyn dev")}                   start dev mode with hot reload
+  ${ui.accent("lucyn build")}                 build your app into a single binary
+
+Inside an empty folder, ${ui.accent("bun add lucynui --trust")} runs all four steps on its own.
+`;
+
+export async function run(argv: string[]): Promise<void> {
+  const [command, ...rest] = argv;
+
+  try {
+    switch (command) {
+      case "create-ui":
+      case "create": {
+        const appName = rest[0];
+        if (!appName) throw new Error("usage: lucyn create-ui <appname>");
+        await create.create(appName);
+        return;
+      }
+
+      case "dev":
+        await create.dev();
+        return;
+
+      case "build":
+        await create.build();
+        return;
+
+      case "init":
+      case undefined:
+        await create.init();
+        return;
+
+      case "help":
+      case "--help":
+      case "-h":
+        console.log(HELP);
+        return;
+
+      default:
+        throw new Error(`unknown command: ${command} — try lucyn help`);
+    }
+  } catch (error) {
+    ui.fail(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}

package/cli/postinstall.ts

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs";
+import { join, sep } from "node:path";
+import * as create from "./create";
+import * as ui from "./ui";
+
+/**
+ * Runs after `bun add lucynui --trust` / `npm i lucynui`.
+ *
+ * When the folder is empty it scaffolds the starter app, proves the build works
+ * and leaves a dev server running before the install command returns. Any folder
+ * that already looks like a project is left completely alone.
+ */
+export async function postinstall(): Promise<void> {
+  // Only when installed as a dependency — not while developing this package.
+  if (!import.meta.dir.includes("node_modules")) return;
+  if (process.env.LUCYN_SKIP_POSTINSTALL) return;
+
+  const dir = projectDir();
+  if (!dir) return;
+
+  if (await create.isProject(dir)) return;
+  if (existsSync(join(dir, "index.html")) || existsSync(join(dir, "src"))) return;
+
+  ui.useTerminal();
+  ui.info("LucyN UI found an empty project and is setting it up.");
+  ui.line();
+
+  ui.step(1, "cloning the template, hang on");
+  await create.scaffoldInto(dir);
+  ui.done("cloning complete — fetching the deps and required builds");
+
+  ui.step(2, "installing modules including lucynui");
+  ui.done("modules installed");
+
+  ui.step(3, "testing build");
+  await create.testBuild(dir);
+  ui.done("build was successful");
+
+  ui.step(4, "starting dev with hmr");
+  const logPath = join(dir, ".lucyn-dev.log");
+  const port = await create.devDetached(dir, logPath);
+
+  if (port === null) {
+    ui.warn(`The window did not come up. Run lucyn dev yourself — log: ${logPath}`);
+    return;
+  }
+
+  ui.done(`dev is up and running on port ${port}`);
+  ui.line();
+  ui.line(`  ${ui.accent("Log:")} ${ui.text(logPath)}`);
+  ui.line();
+}
+
+/** The folder the user ran `bun add` in — the one holding `node_modules`. */
+function projectDir(): string | null {
+  const fromEnv = process.env.INIT_CWD ?? process.env.npm_config_local_prefix;
+  if (fromEnv) return fromEnv;
+
+  const marker = `${sep}node_modules${sep}`;
+  const index = import.meta.dir.lastIndexOf(marker);
+  return index === -1 ? null : import.meta.dir.slice(0, index);
+}
+
+if (import.meta.main) await postinstall();

package/cli/proc.ts

@@ -0,0 +1,98 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as ui from "./ui";
+
+/** Marks the root of a LucyN UI project. */
+export const CONFIG_FILE = "lucyn.config.ts";
+
+/** Where `create-ui` clones the starter app from. */
+export const TEMPLATE_REPO = "https://github.com/LucyNBrowserEngine/lucynui-template";
+
+/** Absolute path to the package root, wherever it is installed. */
+export function packageRoot() {
+  return fileURLToPath(new URL("..", import.meta.url));
+}
+
+/** Absolute path to a file inside the framework's own `src/`, wherever the package is installed. */
+export function frameworkPath(file: string) {
+  return fileURLToPath(new URL(`../src/${file}`, import.meta.url));
+}
+
+export async function packageVersion() {
+  const pkg = await Bun.file(new URL("../package.json", import.meta.url)).json();
+  return String(pkg.version ?? "0.0.0");
+}
+
+/** Bun on PATH, or in the default install location. */
+export function findBun(): string | null {
+  const onPath = Bun.which("bun");
+  if (onPath) return onPath;
+
+  const fallback = join(homedir(), ".bun", "bin", "bun");
+  return existsSync(fallback) ? fallback : null;
+}
+
+export function requireProject() {
+  if (!existsSync(CONFIG_FILE)) {
+    throw new Error("No lucyn.config.ts found. Are you inside a LucyN UI project?");
+  }
+}
+
+/**
+ * Runs a program with its output going straight to the terminal and returns its exit code.
+ * `stdin` is only inherited for commands that need to prompt the user.
+ */
+export async function run(dir: string, cmd: string[], stdin: "ignore" | "inherit" = "ignore"): Promise<number> {
+  const head = cmd[0];
+  if (!head) throw new Error("empty command");
+
+  let child;
+  try {
+    child = Bun.spawn(cmd, { cwd: dir, stdin, stdout: "inherit", stderr: "inherit" });
+  } catch {
+    throw new Error(`could not run ${head} — is it installed?`);
+  }
+
+  return await child.exited;
+}
+
+export async function runStep(dir: string, cmd: string[], stdin: "ignore" | "inherit" = "ignore") {
+  const code = await run(dir, cmd, stdin);
+  if (code !== 0) throw new Error(`${cmd.join(" ")} failed (exit code ${code})`);
+}
+
+/** Returns bun, installing it first when it is missing. */
+export async function ensureBun(): Promise<string> {
+  const found = findBun();
+  if (found) return found;
+
+  ui.info("Bun not found. Installing bun...");
+  await runStep(process.cwd(), ["bash", "-c", "curl -fsSL https://bun.sh/install | bash"]);
+
+  const installed = findBun();
+  if (!installed) {
+    throw new Error("bun was installed but is not on PATH yet — restart your shell and run lucyn again");
+  }
+
+  ui.ok("Bun installed successfully");
+  return installed;
+}
+
+/** Installs the GTK/WebKit libraries the window needs. Linux only. */
+export async function ensureSystemDeps() {
+  if (process.platform !== "linux") return;
+  if (!Bun.which("dpkg")) return;
+
+  const probe = Bun.spawnSync(["dpkg", "-l", "libwebkitgtk-6.0-4"]);
+  if (probe.exitCode === 0 && probe.stdout.toString().includes("ii")) return;
+
+  ui.info("Installing system dependencies...");
+  await runStep(process.cwd(), ["sudo", "apt", "install", "-y", "libgtk-4-1", "libwebkitgtk-6.0-4"], "inherit");
+  ui.ok("Dependencies installed");
+}
+
+export function requireGit() {
+  if (!Bun.which("git")) throw new Error("git is required to fetch the template");
+}

package/cli/ui.ts

@@ -0,0 +1,97 @@
+/** Every line the LucyN CLI prints goes through here. */
+
+import { openSync, writeSync } from "node:fs";
+
+type Rgb = readonly [number, number, number];
+
+const TEXT: Rgb = [0xe8, 0xea, 0xf0];
+const GOLD: Rgb = [0xe0, 0xb3, 0x4d];
+const ERROR: Rgb = [0xff, 0x6b, 0x6b];
+const SUCCESS: Rgb = [0x69, 0xdb, 0x7c];
+
+const RESET = "\x1b[0m";
+
+function paint([r, g, b]: Rgb, value: string) {
+  return `\x1b[38;2;${r};${g};${b}m${value}${RESET}`;
+}
+
+export const text = (value: string) => paint(TEXT, value);
+export const gold = (value: string) => paint(GOLD, value);
+export const error = (value: string) => paint(ERROR, value);
+export const success = (value: string) => paint(SUCCESS, value);
+/** Gold and bold — used for labels and commands. */
+export const accent = (value: string) => `\x1b[1m${paint(GOLD, value)}`;
+
+let sink = (value: string) => console.log(value);
+
+/**
+ * Sends everything straight to the terminal.
+ *
+ * Needed when we run as an install script: package managers swallow the streams
+ * of lifecycle scripts, so without this the user stares at a blank screen.
+ */
+export function useTerminal() {
+  try {
+    const fd = openSync("/dev/tty", "a");
+    sink = (value: string) => writeSync(fd, value + "\n");
+  } catch {
+    // No terminal to talk to — stdout is the best we have.
+  }
+}
+
+function emit(value: string) {
+  sink(value);
+}
+
+export const info = (message: string) => emit(text(message));
+export const warn = (message: string) => emit(gold(message));
+export const ok = (message: string) => emit(success(message));
+export const fail = (message: string) => emit(error(message));
+/** A blank line. */
+export const line = (value = "") => emit(value);
+
+/** The Windows warning, printed before anything else. */
+export const WINDOWS_NOTICE = `You are on Windows. LucyN UI on Windows is not top grade
+as Windows builds differ from Linux where the framework
+was made and tested. If you encounter any bugs or build
+errors please dont hesitate to open an issue at the LucyN
+org. Thank you.`;
+
+/** Prints a numbered step, e.g. `1. cloning the template`. */
+export function step(index: number, message: string) {
+  emit(`${accent(`${index}.`)} ${text(message)}`);
+}
+
+/** Prints the result of the step above it. */
+export function done(message: string) {
+  emit(`   ${success("✓")} ${text(message)}`);
+}
+
+const BANNER_WIDTH = 32;
+
+function centered(value: string, width: number) {
+  if (value.length >= width) return value;
+  const left = Math.floor((width - value.length) / 2);
+  return " ".repeat(left) + value + " ".repeat(width - value.length - left);
+}
+
+/** The gold double-bordered box drawn once a new app is running. */
+export function banner(value: string) {
+  const inner = `  ${centered(value, BANNER_WIDTH)}  `;
+  const edge = "═".repeat(inner.length);
+  return [gold(`╔${edge}╗`), gold("║") + accent(inner) + gold("║"), gold(`╚${edge}╝`)].join("\n");
+}
+
+/** The closing message after a successful scaffold. */
+export function ready(appName: string) {
+  line();
+  emit(banner("LucyN UI Ready!"));
+  line();
+  emit(`  ${accent("App:")} ${text(appName)}`);
+  line();
+  emit(text("  Next steps:"));
+  line();
+  emit("  " + accent(`cd ${appName}`));
+  emit("  " + accent("lucyn dev"));
+  line();
+}