@uibro/cli 0.1.0

package/bin/uibro-project-host.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+
+import { runNativeHost } from "../src/host-main.js";
+
+try {
+  await runNativeHost({ workspace: process.env.UIBRO_PROJECT_WORKSPACE });
+} catch (error) {
+  process.stderr.write(`[uibro] project host failed: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/bin/uibro.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+import { initializeProject } from "../src/config.js";
+import { writeProjectLauncher } from "../src/launcher.js";
+import { registerNativeManifest } from "../src/native-manifest.js";
+import { ensureProjectHostBinary } from "../src/project-install.js";
+
+function usage() {
+  return "Usage: uibro init --origin <http(s)://origin>";
+}
+
+function parse(args) {
+  if (args[0] === "init" && args.length === 3 && args[1] === "--origin") {
+    return { origin: args[2] };
+  }
+  throw new Error(usage());
+}
+
+try {
+  const options = parse(process.argv.slice(2));
+  const initialized = await initializeProject(process.cwd(), options);
+  const hostBin = await ensureProjectHostBinary(initialized.workspace);
+  const launcherPath = await writeProjectLauncher(initialized.workspace, hostBin);
+  const registration = await registerNativeManifest({
+    projectId: initialized.config.projectId,
+    launcherPath,
+  });
+  const meta = `<meta name="uibro-project" content="${initialized.config.projectId}">`;
+  process.stdout.write(`UIBro initialized for ${initialized.config.projectName}.\n${meta}\nNative host: ${registration.name}\n`);
+} catch (error) {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@uibro/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "uibro": "bin/uibro.js",
+    "uibro-project-host": "bin/uibro-project-host.js"
+  },
+  "files": ["bin", "src"],
+  "dependencies": {
+    "@uibro/bridge": "0.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "node --check bin/uibro.js && node --check bin/uibro-project-host.js",
+    "check": "node --test test/*.test.js",
+    "test": "node --test test/*.test.js"
+  }
+}

package/src/config.js

@@ -0,0 +1,62 @@
+import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { assertProjectId, createProjectId, normalizeOrigin } from "./identity.js";
+
+export const CONFIG_RELATIVE_PATH = join(".uibro", "project.json");
+
+async function inferredName(workspace) {
+  try {
+    const pkg = JSON.parse(await readFile(join(workspace, "package.json"), "utf8"));
+    if (typeof pkg.name === "string" && pkg.name.trim()) return pkg.name.trim().slice(0, 128);
+  } catch {}
+  return basename(workspace);
+}
+
+export async function readProjectConfig(workspace) {
+  const path = join(resolve(workspace), CONFIG_RELATIVE_PATH);
+  const value = JSON.parse(await readFile(path, "utf8"));
+  assertProjectId(value.projectId);
+  if (value.protocolVersion !== 1) throw new Error("Unsupported UIBro protocolVersion.");
+  if (typeof value.projectName !== "string" || !value.projectName.trim()) {
+    throw new Error("Invalid UIBro projectName.");
+  }
+  const allowedOrigins = value.allowedOrigins?.map(normalizeOrigin);
+  return { ...value, ...(allowedOrigins ? { allowedOrigins } : {}) };
+}
+
+export async function initializeProject(workspace, { origin } = {}) {
+  const absolute = await realpath(resolve(workspace));
+  const path = join(absolute, CONFIG_RELATIVE_PATH);
+  let existing;
+  try {
+    existing = await readProjectConfig(absolute);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  const origins = new Set(existing?.allowedOrigins || []);
+  if (origin) origins.add(normalizeOrigin(origin));
+  const config = {
+    projectId: existing?.projectId || createProjectId(),
+    protocolVersion: 1,
+    projectName: existing?.projectName || await inferredName(absolute),
+    ...(origins.size ? { allowedOrigins: [...origins].sort() } : {}),
+  };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  await ensureLocalRuntimeIgnored(dirname(path));
+  return { workspace: absolute, path, config };
+}
+
+async function ensureLocalRuntimeIgnored(directory) {
+  const path = join(directory, ".gitignore");
+  let lines = [];
+  try {
+    lines = (await readFile(path, "utf8")).split(/\r?\n/).filter(Boolean);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  for (const entry of ["/native-host.mjs", "/project.json"]) {
+    if (!lines.includes(entry)) lines.push(entry);
+  }
+  await writeFile(path, `${lines.join("\n")}\n`, { mode: 0o600 });
+}

package/src/host-controller.js

@@ -0,0 +1,86 @@
+import { projectIdentity } from "./identity.js";
+
+async function loadBridgeRuntime() {
+  try {
+    return (await import("@uibro/bridge/src/bridge-runtime.js")).createBridgeRuntime;
+  } catch (error) {
+    if (error?.code !== "ERR_MODULE_NOT_FOUND") throw error;
+    return (await import("../../../apps/bridge/src/bridge-runtime.js")).createBridgeRuntime;
+  }
+}
+
+export class HostController {
+  #runtime;
+  #bridgeOrigin;
+  #state = "disconnected";
+  constructor({ workspace, config, runtimeFactory } = {}) {
+    this.workspace = workspace;
+    this.config = config;
+    this.runtimeFactory = runtimeFactory;
+    this.project = projectIdentity(workspace, config.projectId, config.projectName);
+  }
+
+  response(id, ok, error) {
+    return {
+      id,
+      ok,
+      projectId: this.project.id,
+      protocolVersion: 1,
+      state: this.#state,
+      project: this.project,
+      ...(this.#bridgeOrigin ? {
+        bridgeOrigin: this.#bridgeOrigin,
+        endpoint: this.#bridgeOrigin,
+      } : {}),
+      ...(error ? { error } : {}),
+    };
+  }
+
+  async handle(message) {
+    try {
+      if (message.type === "status") return this.response(message.id, true);
+      if (message.type === "disconnect") await this.stop();
+      if (message.type === "reconnect") {
+        await this.stop();
+        await this.start();
+      }
+      if (message.type === "connect") await this.start();
+      return this.response(message.id, true);
+    } catch (error) {
+      await this.stop("offline");
+      return this.response(
+        message.id,
+        false,
+        error instanceof Error ? error.message : String(error),
+      );
+    }
+  }
+
+  async start() {
+    if (this.#runtime && this.#state === "connected") return;
+    const factory = this.runtimeFactory || await loadBridgeRuntime();
+    const environment = { ...process.env, UIBRO_WORKSPACE: this.workspace };
+    const runtime = factory({ environment });
+    try {
+      await runtime.start({ port: 0 });
+      const address = runtime.httpServer.address();
+      if (!address || typeof address === "string" || !Number.isInteger(address.port)) {
+        throw new Error("UIBro Helper did not expose an isolated loopback port.");
+      }
+      this.#runtime = runtime;
+      this.#bridgeOrigin = `http://127.0.0.1:${address.port}`;
+      this.#state = "connected";
+    } catch (error) {
+      await runtime.close().catch(() => {});
+      throw error;
+    }
+  }
+
+  async stop(state = "disconnected") {
+    const runtime = this.#runtime;
+    this.#runtime = undefined;
+    this.#bridgeOrigin = undefined;
+    if (runtime) await runtime.close();
+    this.#state = state;
+  }
+}

package/src/host-main.js

@@ -0,0 +1,38 @@
+import { readProjectConfig } from "./config.js";
+import { HostController } from "./host-controller.js";
+import { createNativeDecoder, encodeNativeMessage } from "./native-io.js";
+import { validateHostMessage } from "./message.js";
+
+export async function runNativeHost({ workspace, input = process.stdin, output = process.stdout } = {}) {
+  if (typeof workspace !== "string" || !workspace) throw new Error("UIBRO_PROJECT_WORKSPACE is required.");
+  const config = await readProjectConfig(workspace);
+  const controller = new HostController({ workspace, config });
+  let chain = Promise.resolve();
+  const send = (value) => output.write(encodeNativeMessage(value));
+  const errorResponse = (id, error) => ({
+    id,
+    ok: false,
+    projectId: config.projectId,
+    protocolVersion: 1,
+    state: "offline",
+    project: controller.project,
+    error: error.message,
+  });
+  const onError = (error) => send(errorResponse("invalid", error));
+  const decode = createNativeDecoder((raw) => {
+    chain = chain.then(async () => {
+      let message;
+      try {
+        message = validateHostMessage(raw, config);
+      } catch (error) {
+        send(errorResponse(typeof raw?.id === "string" ? raw.id : "invalid", error));
+        return;
+      }
+      send(await controller.handle(message));
+    });
+  }, onError);
+  input.on("data", decode);
+  input.on("end", () => { chain = chain.then(() => controller.stop()); });
+  input.on("error", () => { chain = chain.then(() => controller.stop()); });
+  return { controller, closed: chain };
+}

package/src/identity.js

@@ -0,0 +1,45 @@
+import { createHash, randomUUID } from "node:crypto";
+import { basename, resolve } from "node:path";
+
+export const EXTENSION_ID = "imoooahdjjjgpnffkalfaglbpdhlglnb";
+export const PROJECT_ID_PATTERN = /^uibro-([0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/;
+
+export function createProjectId(uuid = randomUUID()) {
+  const projectId = `uibro-${uuid.toLowerCase()}`;
+  assertProjectId(projectId);
+  return projectId;
+}
+
+export function assertProjectId(value) {
+  if (typeof value !== "string" || !PROJECT_ID_PATTERN.test(value)) {
+    throw new Error("Invalid UIBro projectId.");
+  }
+  return value;
+}
+
+export function nativeHostName(projectId) {
+  const uuid = assertProjectId(projectId).slice("uibro-".length);
+  return `com.uibro.project_${uuid.replaceAll("-", "_")}`;
+}
+
+export function projectIdentity(workspace, projectId, projectName = basename(workspace)) {
+  const absolute = resolve(workspace);
+  const fingerprint = createHash("sha256").update(absolute).digest("hex").slice(0, 12);
+  if (typeof projectName !== "string" || !projectName.trim() || projectName.length > 128) {
+    throw new Error("Invalid UIBro projectName.");
+  }
+  return { id: assertProjectId(projectId), name: projectName.trim(), fingerprint };
+}
+
+export function normalizeOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("pageOrigin must be a valid HTTP(S) origin.");
+  }
+  if (!new Set(["http:", "https:"]).has(url.protocol) || url.origin !== value) {
+    throw new Error("pageOrigin must be an exact HTTP(S) origin.");
+  }
+  return url.origin;
+}

package/src/launcher.js

@@ -0,0 +1,16 @@
+import { chmod, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+export async function writeProjectLauncher(workspace, hostBin = fileURLToPath(
+  new URL("../bin/uibro-project-host.js", import.meta.url),
+), nodePath = process.execPath) {
+  if (typeof nodePath !== "string" || !nodePath.startsWith("/") || /[\r\n]/.test(nodePath)) {
+    throw new Error("UIBro needs an absolute Node.js executable path.");
+  }
+  const path = join(workspace, ".uibro", "native-host.mjs");
+  const source = `#!${nodePath}\nprocess.env.UIBRO_PROJECT_WORKSPACE = ${JSON.stringify(workspace)};\nawait import(${JSON.stringify(pathToFileURL(hostBin).href)});\n`;
+  await writeFile(path, source, { mode: 0o700 });
+  await chmod(path, 0o700);
+  return path;
+}

package/src/message.js

@@ -0,0 +1,25 @@
+import { assertProjectId, normalizeOrigin } from "./identity.js";
+
+const TYPES = new Set(["status", "connect", "reconnect", "disconnect"]);
+
+export function validateHostMessage(value, config) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Message must be an object.");
+  if (typeof value.id !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(value.id)) {
+    throw new Error("Message id is invalid.");
+  }
+  if (!TYPES.has(value.type)) throw new Error("Message type is invalid.");
+  if (value.protocolVersion !== 1) throw new Error("Message protocolVersion is unsupported.");
+  assertProjectId(value.projectId);
+  if (value.projectId !== config.projectId) throw new Error("Message targets a different UIBro project.");
+  const pageOrigin = normalizeOrigin(value.pageOrigin);
+  if (config.allowedOrigins?.length && !config.allowedOrigins.includes(pageOrigin)) {
+    throw new Error("This page origin is not allowed for the UIBro project.");
+  }
+  return {
+    id: value.id,
+    type: value.type,
+    projectId: value.projectId,
+    protocolVersion: 1,
+    pageOrigin,
+  };
+}

package/src/native-io.js

@@ -0,0 +1,28 @@
+const MAX_MESSAGE_BYTES = 1024 * 1024;
+
+export function encodeNativeMessage(value) {
+  const body = Buffer.from(JSON.stringify(value));
+  if (body.length > MAX_MESSAGE_BYTES) throw new Error("Native message is too large.");
+  const header = Buffer.alloc(4);
+  header.writeUInt32LE(body.length);
+  return Buffer.concat([header, body]);
+}
+
+export function createNativeDecoder(onMessage, onError) {
+  let buffer = Buffer.alloc(0);
+  return (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length >= 4) {
+      const length = buffer.readUInt32LE(0);
+      if (length > MAX_MESSAGE_BYTES) return onError(new Error("Native message exceeds 1 MiB."));
+      if (buffer.length < length + 4) return;
+      const body = buffer.subarray(4, length + 4);
+      buffer = buffer.subarray(length + 4);
+      try {
+        onMessage(JSON.parse(body.toString("utf8")));
+      } catch {
+        onError(new Error("Native message contains invalid JSON."));
+      }
+    }
+  };
+}

package/src/native-manifest.js

@@ -0,0 +1,43 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { EXTENSION_ID, nativeHostName } from "./identity.js";
+
+export function chromeManifestDirectory({ platform = process.platform, env = process.env } = {}) {
+  if (env.UIBRO_NATIVE_MANIFEST_DIR) return resolve(env.UIBRO_NATIVE_MANIFEST_DIR);
+  const home = env.HOME || env.USERPROFILE || homedir();
+  if (platform === "darwin") {
+    return join(home, "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts");
+  }
+  if (platform === "linux") return join(home, ".config", "google-chrome", "NativeMessagingHosts");
+  if (platform === "win32") return join(env.LOCALAPPDATA || home, "UIBro", "NativeMessagingHosts");
+  throw new Error(`Unsupported platform for Chrome Native Messaging: ${platform}`);
+}
+
+function run(command, args) {
+  return new Promise((accept, reject) => {
+    const child = spawn(command, args, { shell: false, stdio: "ignore" });
+    child.once("error", reject);
+    child.once("exit", (code) => code === 0 ? accept() : reject(new Error(`${command} exited with ${code}`)));
+  });
+}
+
+export async function registerNativeManifest({ projectId, launcherPath, platform = process.platform, env = process.env }) {
+  const name = nativeHostName(projectId);
+  const path = join(chromeManifestDirectory({ platform, env }), `${name}.json`);
+  const manifest = {
+    name,
+    description: "UIBro project-local host",
+    path: resolve(launcherPath),
+    type: "stdio",
+    allowed_origins: [`chrome-extension://${EXTENSION_ID}/`],
+  };
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  if (platform === "win32" && !env.UIBRO_NATIVE_MANIFEST_DIR) {
+    const key = `HKCU\\Software\\Google\\Chrome\\NativeMessagingHosts\\${name}`;
+    await run("reg.exe", ["add", key, "/ve", "/t", "REG_SZ", "/d", path, "/f"]);
+  }
+  return { name, path, manifest };
+}

package/src/project-install.js

@@ -0,0 +1,56 @@
+import { spawn } from "node:child_process";
+import { access, readFile, realpath } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const sourcePackageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function runNpmInstall(workspace, spec) {
+  const command = process.platform === "win32" ? "npm.cmd" : "npm";
+  return new Promise((accept, reject) => {
+    const child = spawn(command, ["install", "--save-dev", "--ignore-scripts", spec], {
+      cwd: workspace,
+      shell: false,
+      stdio: "inherit",
+    });
+    child.once("error", reject);
+    child.once("exit", (code) => code === 0
+      ? accept()
+      : reject(new Error(`npm install for ${spec} exited with ${code}.`)));
+  });
+}
+
+async function packageVersion() {
+  const pkg = JSON.parse(await readFile(join(sourcePackageRoot, "package.json"), "utf8"));
+  if (typeof pkg.version !== "string" || !/^\d+\.\d+\.\d+/.test(pkg.version)) {
+    throw new Error("@uibro/cli has an invalid package version.");
+  }
+  return pkg.version;
+}
+
+function isInside(workspace, path) {
+  const child = relative(workspace, path);
+  return child === "" || (!child.startsWith("..") && !child.startsWith("/"));
+}
+
+export async function ensureProjectHostBinary(workspace, { install = runNpmInstall } = {}) {
+  const target = await realpath(workspace);
+  const installed = join(target, "node_modules", "@uibro", "cli", "bin", "uibro-project-host.js");
+  try {
+    await access(installed);
+    const path = await realpath(installed);
+    if (isInside(target, path)) return path;
+  } catch {}
+  if (isInside(target, sourcePackageRoot)) {
+    return realpath(join(sourcePackageRoot, "bin", "uibro-project-host.js"));
+  }
+  const spec = `@uibro/cli@${await packageVersion()}`;
+  await install(target, spec);
+  try {
+    const path = await realpath(installed);
+    if (!isInside(target, path)) throw new Error("Installed project host escaped the workspace.");
+    return path;
+  } catch (error) {
+    throw new Error("@uibro/cli was not installed inside the target project.", { cause: error });
+  }
+}